Plan만 사람이, 나머지는 파이프라인: Matt Pocock atomic workflow를 Pi에 올린 이유

🇰🇷 한국어 🇺🇸 English

요약:

Matt Pocock의 atomic workflow 철학을 내 Pi 멀티에이전트 세팅에 그대로 옮겨봤다. 한 번에 다 시키지 않고 Plan → Task → Execute → Review → Commit 5단계로 쪼개서, 사람은 PLAN 단계에서만 개입하고 나머지는 파이프라인이 기계적으로 밀고 나간다. 멀티 구독 세팅을 다룬 1편은 여기서 봐라.

왜 한 대화에 다 넣으면 깨지나?

한 줄 답: 하나의 긴 프롬프트에 기획, 구현, 테스트를 다 맡기면 맥락이 섞이고 환각(hallucination)이 생기기 때문이다.

에이전트한테 "알아서 다 해줘"라고 긴 대화로 퉁치면 처음엔 편한데, 대화가 길어질수록 앞에서 정한 결정과 뒤에서 짠 코드가 슬슬 어긋난다. 컨텍스트가 뒤섞이면서 존재하지 않는 함수를 부르거나, 이미 합의한 요구사항을 까먹는 식으로 환각이 튀어나온다.

그래서 파일 기반 핸드오프가 필요하다. 대화 맥락에 상태를 의존하지 않고, 각 단계 산출물을 문서로 남겨서 다음 에이전트에게 넘긴다.

• 파일 기반 핸드오프: "대화 맥락"이 아니라 .docs/<slug>/ 폴더 아래 문서로 다음 단계에 상태를 전달하는 방식.
• 과잉 설계(over-engineering) 문제: API 계약 없이 무작정 탐색부터 시키면 에이전트가 필요 이상으로 복잡하게 만든다. Challenge/Simplify, oracle/scout 같은 검토 루프가 이럴 때 쓸모 있다.

결론은 간단하다. 계획, 구현, 검증을 같은 대화창에 몰아넣지 말고 단계별로 쪼개서 문서로 주고받는 것, 그게 atomic workflow의 시작이다.

5+1 단계(Explore→…→Commit)는 어떻게 흘러가나?

한 줄 답: Explore(선택)부터 Plan, Task, Execute, Review, Commit까지 명확한 산출물 문서 단위로 파이프라인이 기계적으로 흘러간다.

작업을 하나의 긴 대화에 몰아넣지 않고, 단계마다 담당 에이전트와 산출물을 딱 정해둔다.

단계	누가	산출물
0 Explore(선택)	explorer	EXPLORE-<slug>.md
1 Plan	부모 preflight + planner	PLAN-<slug>.md
2 Task	tasker	TASKS-<slug>.md
3 Execute	worker	코드 + 체크된 TASKS
4 Review	reviewer + tester	REVIEW-<slug>.md
5 Commit	부모(self)만	git commit (푸시 없음)

각 단계는 슬러그 폴더(.docs/<slug>/)에 문서로 남고, 다음 단계의 입력이 된다.

스킬은 단계별 훈련 교관이다

Matt Pocock 스킬군을 단계마다 강제로 읽게 만든다. 스킬 이름만 언급하고 읽었다고 가정하지 않는다는 게 규칙이다.

단계	강제 스킬	역할
Plan preflight	grilling, domain-modeling, codebase-design, wayfinder	요구사항 정제, 도메인·설계
Plan	위 + workflow	PLAN 구체화
Task	to-tickets	수직 슬라이스, 검증 가능한 항목 분해
Execute	tdd	red → green
Review	code-review	Standards / Spec 두 축 검증

이 전체 파이프라인은 pi install npm:matt-pocock-atomic-workflow 한 번으로 세팅된다.

PLAN 사람 게이트 + Reviewer fresh context가 왜 중요한가?

한 줄 답: PLAN에서만 사람이 방향을 잡고 나머지는 자동으로 돌아가되, 리뷰어는 전임자의 대화 맥락 없이 백지 상태에서 객관적으로 검증해야 하기 때문이다.

사람 게이트는 딱 하나뿐이다

PLAN이 확정되면 Task → Execute → Review는 자동으로 돌아간다. 사람이 멈추는 경우는 몇 가지뿐이다.

• PLAN에 막힌 질문이 있을 때 (보안, 범위, 데이터 손실 등)
• 사용자가 "계획만", "구현만"처럼 단계를 명시적으로 제한했을 때
• done 검증이 실패(막힘)했을 때
• "커밋해"라는 말이 없을 때 (커밋 안 함)

계획 단계에서 충분히 생각하고, 그 이후는 기계적으로 밀어 넣되, 검증 게이트에서만 다시 멈추는 구조다.

Reviewer는 백지 상태에서 검증한다

부모 세션은 파이프라인만 돌리는 오케스트레이터고, 구현·계획·리뷰는 서브에이전트가 맡는다. 특히 Reviewer는 Worker의 대화 맥락을 상속받지 않는다. 작업자의 "다 했어요" 설명을 믿는 게 아니라, PLAN/TASKS 명세와 git diff, 테스트 결과만 대조하는 독립 검증(fresh context)이 설계 의도다.

"다 했어"는 완료가 아니다

워커가 "테스트 통과했습니다"라고 말해도 그걸로 끝난 게 아니다. TASKS 항목의 done 필드는 부모가 직접 실행할 셸 명령이고, 부모는 scripts/run-done.mjs로 직접 재실행해서 증거를 남긴다. 실패하면 로그 마지막 20줄(errorTail)만 요약 보고하고 파이프라인을 멈춘다. AI의 자기 보고보다 재현 가능한 명령 실행 결과를 믿는 거다.

Pi-first, Cursor-portable로 어떻게 옮기나?

한 줄 답: Pi를 기본 하네스로 설계하되, sync-cursor.mjs로 Cursor용 에이전트·명령어를 동기화해서 환경 제약을 없앤다.

구조는 단일 소스로 동기화한다

agents/, prompts/, skills/를 단일 소스로 두고, Cursor용 .cursor/agents, .cursor/commands는 sync-cursor.mjs로 생성한다. Pi에서는 subagent 툴로 위임하고, Cursor에서는 Task 툴로 같은 철학을 적용한다. 하네스는 다르지만 파이프라인 구조는 똑같다.

안전 경계는 세 가지다

• 푸시 금지: 에이전트는 커밋만 하고, 푸시는 사람의 영역이다.
• 비밀 금지: 브리프·커밋에 토큰이나 .env 값을 남기지 않는다.
• 문서는 evidence 폴더로: PLAN/TASKS/REVIEW는 기본적으로 레포에 커밋하지 않고, evidence 폴더에 복사본만 보관한다.

계획(PLAN)에서 한 번만 사람과 맞추고, 나머지는 단계별 전문 에이전트 + 스킬 + run-done 증거 게이트로 자동화하되, 리뷰는 fresh context로, 커밋은 명시적일 때만 — 이게 이 워크플로 전체를 한 줄로 요약한 문장이다.

자주 묻는 질문

파이프라인 중간에 테스트가 실패하면 어떻게 되나?

run-done.mjs가 재실행한 결과가 실패하면 errorTail(로그 마지막 20줄)만 요약해서 보고하고, 파이프라인은 거기서 멈춘 뒤 사람 개입을 기다린다.

매번 워크트리를 따로 파나?

아니다. 기본은 최소 오버헤드 원칙이라 단일 워커가 현재 작업공간에서 순차로 진행한다. 다중 에이전트 병렬 수정이나 충돌 위험이 있을 때만 조건부로 워크트리를 분리한다.

부모 에이전트는 정확히 뭘 하나?

오케스트레이터 역할만 한다. 커밋, 설정, 상태 보고, 자식 서브에이전트 호출까지만 담당하고, 실제 구현·계획·리뷰는 서브에이전트가 처리한다.

출처

Matt Pocock atomic workflow 패키지 철학 문서와 Pi 에이전트 가이드라인을 바탕으로 정리했다.

Summary:

I adapted Matt Pocock's atomic workflow philosophy into my Pi multi-agent setup. Instead of dumping everything into one long chat, I split the work into five stages — Plan → Task → Execute → Review → Commit — and only step in as a human during Plan; everything else runs mechanically. Part 1, on my multi-subscription setup, is here.

Why does cramming everything into one chat break down?

Short answer: Mixing planning, implementation, and testing into one long prompt causes context to bleed together and produces hallucinations.

Telling an agent to "just handle everything" in one long conversation feels convenient at first, but as the chat grows, earlier decisions and later code quietly drift apart. Context gets mixed, and the agent starts calling functions that don't exist or forgetting requirements it already agreed to.

That's why file-based handoff matters: instead of relying on chat memory for state, each stage writes its output to a document that the next agent reads.

• File-based handoff: state is passed through documents under .docs/<slug>/ instead of chat memory.
• Over-engineering risk: letting an agent explore freely without an API contract tends to produce more complexity than needed. Challenge/Simplify and oracle/scout loops help catch this.

The takeaway: don't cram planning, implementation, and verification into one chat window. Split them into stages and hand off through files — that's the starting point of atomic workflow.

How does the 5+1 stage pipeline (Explore→…→Commit) flow?

Short answer: The pipeline flows mechanically through explicit artifact stages — Explore (optional), Plan, Task, Execute, Review, and Commit.

Instead of piling work into one conversation, each stage has a fixed owner and a fixed artifact.

Stage	Owner	Artifact
0 Explore (optional)	explorer	EXPLORE-<slug>.md
1 Plan	Parent preflight + planner	PLAN-<slug>.md
2 Task	tasker	TASKS-<slug>.md
3 Execute	worker	Code + checked TASKS
4 Review	reviewer + tester	REVIEW-<slug>.md
5 Commit	Parent (self) only	git commit (no push)

Each stage leaves a document inside a slug folder (.docs/<slug>/), which becomes the next stage's input.

Skills act as stage coaches

Matt Pocock's skills are forced reading at each stage — the rule is never to assume an agent "read" a skill just because it's mentioned by name.

Stage	Required skills	Role
Plan preflight	grilling, domain-modeling, codebase-design, wayfinder	Refine requirements, domain/design
Plan	above + workflow	Flesh out PLAN
Task	to-tickets	Vertical slices, verifiable items
Execute	tdd	Red → green
Review	code-review	Verify against standards and spec

The whole pipeline is set up with a single command: pi install npm:matt-pocock-atomic-workflow.

Why do the PLAN human gate and Reviewer's fresh context matter?

Short answer: Humans align direction only during PLAN, everything else runs automatically, and the reviewer must validate objectively with zero inherited context.

There's exactly one human gate

Once PLAN is locked, Task → Execute → Review run automatically. Humans only step in for:

• A blocked question in PLAN (security, scope, data loss, etc.)
• An explicit stage limit from the user, like "plan only" or "implementation only"
• A failed/blocked done validation
• The absence of a "commit" instruction (so nothing gets committed)

Think hard during planning, then push mechanically through the pipeline — only pausing again at a validation gate.

The reviewer validates with a blank slate

The parent session is purely an orchestrator that runs the pipeline; implementation, planning, and review are handled by subagents. Crucially, the reviewer never inherits the worker's chat history. Instead of trusting the worker's "I'm done" claim, it independently checks the PLAN/TASKS spec against git diff and test results — a deliberately fresh context.

"I'm done" is not evidence

Even if the worker says "tests pass," that's not accepted at face value. The done field on a TASKS item is a shell command the parent re-runs directly via scripts/run-done.mjs, leaving evidence behind. On failure, only the last 20 lines of the log (errorTail) get summarized, and the pipeline stops. Reproducible command output is trusted over the AI's self-report.

How do I port this from Pi-first to Cursor-portable?

Short answer: Pi is the primary harness, and sync-cursor.mjs syncs the same agents and commands into Cursor, removing environment lock-in.

Structure syncs from a single source

agents/, prompts/, and skills/ stay as a single source of truth, and sync-cursor.mjs generates Cursor's .cursor/agents and .cursor/commands from them. Pi delegates through its subagent tool; Cursor uses its Task tool. Different harness, same pipeline philosophy.

Three safety boundaries

• No pushes: agents commit only; pushing stays a human action.
• No secrets: no tokens or .env values in briefs or commits.
• Docs stay out of the repo: PLAN/TASKS/REVIEW aren't committed by default — only copies live in the evidence folder.

Align with a human once, during PLAN. Everything after that is automated by stage-specific agents, skills, and the run-done evidence gate — reviewed with a fresh context, and committed only when explicitly told to.

FAQ

What happens if a test fails mid-pipeline?

run-done.mjs re-runs the command; on failure it reports only the errorTail (last 20 log lines) and stops the pipeline until a human steps in.

Do you always spin up a separate worktree?

No. The default is minimal overhead — a single worker runs sequentially in the current workspace. Worktrees are created only conditionally, for parallel agents or conflict risk.

What exactly does the parent agent do?

Just orchestration: commits, configuration, status reporting, and invoking subagents. Actual implementation, planning, and review are handled by the subagents.

English Sources

Compiled from the Matt Pocock atomic workflow package philosophy doc and Pi agent guidelines.