Claude Code 워크플로우: 계획이 Claude의 머릿속을 벗어나 편집 가능한 스크립트로 이동합니다

서브에이전트(Subagents), 기술(skills), 그리고 에이전트 팀(agent teams)은 모두 하나의 장소, 즉 Claude의 머릿속에 '계획(plan)'을 보관합니다. Claude는 차례대로 다음에 무엇을 생성할지 결정하며, 모든 결과는 다음 결정이 내려지기 전에 단일 컨텍스트 윈도우(context window)에 다시 맞춰져야 합니다. 이는 작업 규모가 한꺼번에 담기에 너무 커지기 전까지만 유효합니다.

**Claude Code 워크플로우(workflow)**는 계획을 다른 곳, 즉 코드로 옮깁니다. Claude는 루프(loop), 분기(branching), 그리고 중간 결과물을 보유하는 작은 JavaScript 스크립트를 작성하며, 런타임(runtime)은 사용자의 대화형 세션이 자유로운 동안 수십 명의 에이전트에 걸쳐 백그라운드에서 해당 스크립트를 실행합니다. 오케스트레이션(orchestration)은 더 이상 Claude가 턴(turn) 사이에 기억해야 할 사항이 아닙니다. 그것은 디스크 위의 파일입니다.

저는 이 기초적인 개념을 두 번 가르쳐주는 8분짜리 영상을 만들었습니다. 한 번은 사소한 작업으로, 또 한 번은 손을 대지 않고 2시간 동안 실행된 실제 기능 빌드 작업으로 설명했습니다. 이 글은 그 영상의 텍스트 동반자입니다. (Workflow는 연구 프리뷰 도구이며, Claude Code v2.1.154+ 버전에서 사용 가능합니다. 공식 문서 링크).

멘탈 모델: Claude는 작업을 '수행'하는 것이 아니라, 작업을 수행하는 스크립트를 '작성'합니다

제가 이해하는 데 시간이 조금 걸렸던 핵심적인 변화는 이것입니다. 워크플로우를 요청할 때, Claude는 대화 속에서 작업을 수행하지 않습니다. Claude는 스크립트를 작성하며, 런타임이 나중에 백그라운드에서 그 스크립트를 실행합니다.

그 형태를 배우기 위해

parallel(...)은 파일당 하나의 agent()를 동시에 실행합니다. 제가 이를 실행했을 때, /workflows 패널에 실행 상황이 실시간으로 표시되었습니다: 6개의 에이전트, 37초, 37개의 README 수정 완료. 이것이 하나의 화면에 담긴 전체적인 멘탈 모델(Mental Model)입니다 — 작업 단위당 하나의 에이전트, 스크립트가 팬아웃(Fan-out)을 제어함. 그 외의 모든 것도 더 큰 규모에서는 동일한 개념입니다.

진짜 테스트: 20개의 승인된 명세(Specs)에 적용하기

사소한 예시는 진짜 테스트를 준비하기 위한 것입니다. 제 테스트 프로젝트에는 **승인된 명세 트리(Approved Spec Tree)**가 있습니다. 즉

Discover(탐색) 및 Understand(이해) 단계의 각 에이전트는 JSON 스키마 (schema) (DISCOVERY_SCHEMA, UNDERSTANDING_SCHEMA)에 종속됩니다. 스키마가 있으면 에이전트는 산문(prose)이나 최선을 다한 요약이 아니라, 당신이 요청한 형태인 검증된 JSON을 반드시 반환해야 합니다. 이것이 멀티 에이전트 실행을 자유 형식(free-form)이 아닌 제어 가능한 상태로 만드는 핵심입니다. 즉, 런타임(runtime)이 스키마를 강제했기 때문에 Plan(계획) 단계는 Discover 단계가 생성한 정확한 구조에 의존할 수 있습니다. 에이전트 간의 자유 형식 텍스트 전달(Free-text handoffs)은 다단계 실행이 조용히 무너지는 지점이며, 스키마는 이를 해결하는 방안입니다.

2. 웨이브 모델 (The wave model)

Build(빌드) 단계는 20개의 명세(specs)를 한꺼번에 쏟아붓지 않습니다. 이를 의존성을 인식하는 작업 패키지(work-packages)로 그룹화하고, 각 웨이브를 "최대 안전" 병렬성으로 실행합니다. 먼저 기초 작업 패키지(공통 모듈, DB 마이그레이션 등)를 실행한 다음, 그 위에 독립적인 기능 명세들을 동시에 실행합니다. 스크립트가 이 순서를 인코딩하므로, 어떤 명세가 언제 시작될 수 있는지 일일이 지켜볼 필요가 없습니다.

Claude는 자동 실행을 거부했습니다 — 그리고 그것은 옳은 결정이었습니다

스크립트가 준비되었을 때, Claude는 자동으로 실행하는 것을 거부했습니다. 20개의 명세에 걸쳐 코드를 작성하려는 상황이었기에, 명령어를 통해 제가 명시적으로 실행하도록 만든 것입니다. 저는 이러한 본능이 매우 마음에 듭니다. 코드베이스 전체를 건드릴 수도 있는 워크플로우는 채팅의 부수 효과(side effect)가 아니라, 의도적인 키 입력(deliberate keystroke)이어야 합니다.

저는 실행을 시작했습니다. 스크립트는 약 2시간 동안 사람의 개입 없이(hands-off) 실행되었습니다 (영상에서는 화면 속 속도가 빠르게 재생됨). 실행 중간에 이것이 가짜가 아닌지 확인하기 위해 소스 제어(Source Control)를 확인했는데, 실제 **26개 파일의 변경 사항(changeset)**이 있었습니다. 새로운 lib/social-* 모듈, 0028_social_groundwork 데이터베이스 마이그레이션, 스키마 와이어링(wiring), 그리고 기초 작업 테스트들이 포함되어 있었습니다. 데모용 껍데기가 아니라, 실제 검토 가능한 작업이었습니다.

그리고 왼쪽의 스펙 트리(spec tree)에서는 각 스펙이 빌드됨에 따라 상태 아이콘의 색상이 변경되었습니다 — approved (파란색) → in-development (노란색) → under-test (보라색). 이러한 색상 변화는 워크플로우(workflow) 자체가 수행하는 상태 업데이트입니다. 즉, 각 빌드 에이전트(Build agent)가 방금 구현한 스펙의 라이프사이클(lifecycle)을 진전시키는 것입니다. 여러분은 트리를 훑어보는 것만으로 2시간 동안 실행된 작업이 정확히 어디까지 진행되었는지 확인할 수 있습니다.

워크플로우는 단지 스크립트일 뿐입니다 — 따라서 버그는 일반적인 편집 과정입니다

실행 과정에서 버그가 발생했습니다. 모든 _요구사항(requirement)_의 상태는 올바르게 변경되었지만, **세 개의 상위 기능(parent features)**은 approved 상태에 그대로 머물러 있었습니다. 즉, 리프(leaf) 노드들은 진전시켰지만, 브랜치(branch)로 상태를 상향 전파(roll up)하지는 못한 것입니다.

워크플로우는 단지 스크립트일 뿐이기에, 이를 수정하는 것은 일반적인 편집 과정이었으며, 저는 질문함으로써 이를 해결했습니다. 저는 Claude에게 "요구사항은 업데이트했지만 상위 기능은 업데이트하지 않았으니 수정해 주세요"라고 말했습니다. 그러자 Claude는 규칙(모든 자식 노드가 진전되어야 기능이 "완료"된다는 규칙)을 진단하고, 최하위 우선 상위 상태 상향 전파(deepest-first parent-status rollup) 방식을 통해 스크립트를 패치(patch)했습니다. 다음 실행 시에는 상위 기능들이 자동으로 변경됩니다. 이번에는 Claude가 레시피(recipe)를 수정하는 동안 제가 UI에서 세 개의 기능을 수동으로 under-test로 변경해 두었는데, Claude가 재확인했을 때 해당 기능들이 "이미 under-test 상태"임을 발견했습니다. 인간과 에이전트가 서로 다른 방향에서 동일한 상태로 수렴한 것입니다.

제가 강조하고 싶은 부분은 바로 이것입니다: 여러분은 스크립트를 소유(own)합니다. 이것은 다운로드해서 기도하며 바라기만 해야 하는 YAML 레시피가 아니라, 대화를 통해 패치할 수 있는 읽기 가능한 코드입니다. 이해하지 못하는 수많은 git 워크플로우 더미보다, 여러분이 이해하고 제어할 수 있는 하나의 워크플로우가 훨씬 강력합니다.

SPECLAN의 역할 (제작자 공개)

솔직히 말씀드리면, 저는 이 영상에서 스펙 트리와 라이프사이클 상태 메커니즘을 구현한 무료 VS Code 확장 프로그램인 SPECLAN의 제작자입니다. SPECLAN은 요구사항을 안정적인 ID와 approved → in-development → under-test 라이프사이클을 가진 검토 가능한 Markdown + YAML 형태로 유지합니다.

제가 이 점을 밝히는 이유는 승인된 명세(approved specs)가 왜 그렇게 훌륭한 워크플로우 입력값이 되는지, 그리고 이것이 제 도구를 넘어 어떻게 일반화될 수 있는지를 설명하기 위해서입니다. 워크플로우는 깨끗하고 열거 가능한 **작업 단위 (unit of work)**를 통해 가장 잘 확장됩니다. 승인된 명세는 정확히 그러한 것입니다: 안정적인 ID, 명확한 경계, 그리고 에이전트가 진행할 수 있는 상태(status)를 갖추고 있습니다. 따라서 "README당 에이전트 하나"가 그랬던 것과 마찬가지로, 데이터로부터 "명세당 에이전트 하나"라는 결론이 자연스럽게 도출됩니다. 만약 당신의 작업 단위가 티켓(tickets), 테스트 케이스(test cases), 또는 마이그레이션 사이트(migration sites)라면, 위의 메커니즘은 순수하게 Claude Code의 방식이며 직접적으로 적용됩니다. 스키마(schema)와 웨이브 모델(wave model)은 항목이 무엇인지 상관하지 않기 때문입니다.

보상 (The payoff)

고객이 명세 트리(spec tree)를 승인하면 → 두 시간 이내에, 개입 없이(hands-off) 검토 가능한 작동 기능이 완성됩니다. 영상 마지막 부분에서 저는 localhost에서 앱을 열어 보여드리는데, 바로 여기에 있습니다: 승인된 명세들을 바탕으로 점심시간 동안 구축된 "당신의 소셜 세상" 허브 — 커뮤니티("당신의 무리를 찾으세요"), 추모관("사랑하는 기억 속에서"), 마일스톤("비스킷의 첫 입양 기념일") — 가 구현되어 있습니다.

명세는 지속 가능하고 검토 가능한 산출물(artifact)로 남습니다. 워크플로우는 이를 대규모(fleet scale)로 구축하는 방법입니다. 그리고 워크플로우는 당신이 그것을 설명함으로써 작성한 스크립트이기 때문에, 워크플로우가 잘못되었을 때는 그것을 작성했을 때와 같은 방식, 즉 질문을 함으로써 수정할 수 있습니다.

만약 당신이 자신만의 작업 단위를 기반으로 확장되는 워크플로우를 구축했다면, 에이전트를 어떤 스키마에 결합했는지 진심으로 알고 싶습니다. 그 부분이 제가 여전히 미세 조정(tuning)하고 있는 영역입니다.

Claude Code 워크플로우 문서: https://code.claude.com/docs/en/workflows
SPECLAN (무료 VS Code 확장 프로그램): https://marketplace.visualstudio.com/items?itemName=DigitalDividend.speclan-vscode-extension
명세 라이프사이클에 대한 자세한 내용: https://speclan.net