Zettelkasten

Claude Code 워크플로우는 하네스를 대체하지 않고 그 위에서 에이전트 실행을 조율한다

·수정 2회

요약

  • 하네스는 모델 가중치 밖의 지시·도구·환경·상태·피드백 전부다. 워크플로우 스크립트는 그중 "어떤 에이전트를 어떤 순서로 몇 개 돌리고, 누가 누구 결과를 검사하나"만 코드로 정한다.
  • 테스트·타입 검사 명령, 재현되는 실행 환경, 세션을 넘는 진행 기록은 저장소에 파일과 명령으로 있어야 한다. 워크플로우는 이것들을 만들어 주지 않는다.
  • 검증 에이전트를 늘려서 대신할 수 없는 이유: 돌릴 검사 명령이 없으면 검증 에이전트는 코드를 읽고 의견을 내는 데 그친다. 검사가 느리면 그 비용이 에이전트 수만큼 늘어난다.

본문

하네스의 범위

learn-harness-engineering 2강은 "모델 가중치가 아니라면 모두 하네스"라고 정의하고 다섯 하위 시스템으로 나눈다.

하위 시스템 저장소에 두는 것
지시 AGENTS.md/CLAUDE.md: 스택, 첫 실행 명령, 꼭 지킬 제약
도구 셸·MCP 접근 권한 (최소 권한)
환경 잠금 파일, 런타임 버전 파일, Docker
상태 PROGRESS.md: 완료·진행·막힘 항목
피드백 테스트·타입 검사·린트 명령

2강은 피드백을 "투자 대비 효과가 가장 높은 하위 시스템"으로 꼽는다.

워크플로우가 맡는 부분

Claude Code 워크플로우는 JavaScript 스크립트가 agent()·pipeline()·parallel()로 서브에이전트를 띄우고 중간 결과를 스크립트 변수에 둔다. 스크립트는 파일시스템과 셸에 직접 접근하지 않는다. 읽기·쓰기·명령 실행은 에이전트가 한다. 그래서 스크립트가 직접 정하는 것은 이것뿐이다.

  • 에이전트 수와 실행 순서 (팬아웃, 파이프라인)
  • 작성 에이전트와 검증 에이전트 분리
  • schema로 에이전트 출력 형태 강제
  • 중단된 실행 재생 (완료된 에이전트는 저장된 결과를 돌려준다)

13강은 사람 대신 시스템이 에이전트를 돌리는 층을 루프 엔지니어링이라 부르고 "루프 엔지니어링은 하네스 엔지니어링을 대체하지 않습니다 — 그 위에 한 층을 더 쌓을 뿐입니다"라고 쓴다.

워크플로우가 채우지 못하는 부분

하네스에 빠진 것 워크플로우에서 생기는 일
검사 명령 검증 에이전트가 코드를 읽고 판단한다. 13강: "괜찮아 보여"는 "확인된 정답"과 같지 않다
빠른 검사 느린 테스트를 에이전트마다 돌려 시간과 CPU가 에이전트 수만큼 든다 (아래 관찰 사례)
지시 파일 에이전트마다 패키지 매니저와 명명 규칙을 추측한다. 2강 교육용 예시의 실패 원인이 npm/yarn 잘못 선택, 컴포넌트 명명 규칙 미준수였다
진행 기록 파일 재개는 세션 디렉터리에 저장된 에이전트 결과를 재생하는 것이다. 같은 세션이나 claude --resume으로 연 세션만 재생하고, 새 세션은 처음부터 시작한다. 다른 사람이나 새 세션이 읽을 진행 기록이 아니다

공식 문서의 예시 프롬프트 "run npx tsc --noEmit and keep fixing the reported errors until the type check passes"도 저장소에 타입 검사가 이미 있어야 성립한다. 반복을 멈출 시점을 기계가 판정하게 해 주는 것은 스크립트가 아니라 tsc 명령이다.

관찰 사례: 느린 테스트와 서브에이전트

  • 한 Node 서비스의 jest 테스트가 로컬에서 한 번에 470초 걸렸다. 테스트 setup이 실제 로거를 import하자 @google-cloud/logging-winston 안의 google-auth가 프로젝트 ID를 찾으려고 테스트 파일마다 gcloud config config-helper를 실행했다 (전체 344번).
  • 서브에이전트들이 여러 worktree에서 병렬 워커 모드 npx jest를 8번 실행한 시간대에 맥 load가 200~300까지 올랐다.
  • setup에 jest.mock('@google-cloud/logging-winston', ...)을 넣자 19~20초로 줄었고 같은 902개 테스트가 통과했다 (관찰됨).
  • 에이전트를 더 붙여서는 이 470초가 줄지 않는다. 줄인 것은 검사 명령 쪽을 고친 작업이다.

용어 주의

14강의 "workflow"는 Anthropic 정의("코드가 단계를 결정하면 workflow, 모델이 런타임에 단계를 바꿀 수 있으면 agent")를 따라 노드가 결정적 함수인 경우를 말한다. Claude Code 워크플로우는 스크립트가 순서를 정하지만 노드 하나하나가 에이전트라서, 14강 기준으로는 엣지를 코드로 정한 그래프에 가깝다.

결과가 나쁠 때 먼저 볼 곳

검증 에이전트를 늘리기 전에 다섯 하위 시스템 중 어디가 비었는지부터 본다. 1강: "실패가 발생하면 먼저 모델을 교체하지 말고 하네스를 점검하십시오."

관련 노트

참고