Claude Code 개발 워크플로: RPI에서 CRISPY·교차 모델·에이전트 팀까지

워크플로가 필요한 이유

공개된 워크플로는 이름이 달라도 거의 모두 Research → Plan → Execute → Review → Ship 골격으로 수렴하고, 구현과 검증을 작업마다 반복하는 하위 루프로 둔다. 차이는 「맨 앞에서 사람과 얼마나 정렬하느냐」와 「어떤 문서를 누가 읽느냐」에 있다.

flowchart LR
  R["Research"] --> P["Plan"] --> E["Execute"] --> V["Review"] --> S["Ship"]
  E -->|"작업마다 반복"| E
  V -->|"검증 통과까지"| E

두 가지 제약이 모든 설계를 끌고 간다.

맥락이 나빠지는 원리와 KV 캐시 관점은 하네스 엔지니어링에 있다.

RPI: 단계마다 게이트

RPI(Research → Plan → Implement)는 가망 없는 기능에 힘을 쓰지 않도록 단계마다 검증 게이트를 두는 워크플로다.

flowchart TB
  D["계획 모드로 기능 설명"] --> RQ["REQUEST.md"]
  RQ --> RS["/rpi:research"]
  RS --> G{"GO / NO-GO"}
  G -->|"NO-GO"| X["중단"]
  G -->|"GO"| PL["/rpi:plan<br/>pm.md · ux.md · eng.md · PLAN.md"]
  PL --> IM["/rpi:implement"]
  IM --> PH["단계 루프: 탐색 → 구현 → 자체 검증<br/>→ 코드 리뷰 → 사용자 검증 → 문서"]
  PH -->|"다음 단계"| PH
  PH -->|"모든 단계 PASS"| PR["PR 준비"]

준비물은 프로젝트 루트의 constitution.md와 .claude/settings.json의 "plansDirectory": "./rpi/plans"다. 조사·계획·구현 단계마다 product-manager, ux-designer, senior-software-engineer, code-reviewer 같은 서브에이전트가 나눠 맡는다. 진행 상태는 [ ] 시작 전, [~] 진행 중, [x] 통과, [!] 조건부, [-] 실패로 표시한다.

CRISPY: RPI를 쪼갠 이유

RPI 프롬프트를 많은 팀에 나눠 줘 보니 전문가는 잘 쓰는데 팀 결과는 나빴다. 원인과 고친 방식은 이렇다.

flowchart LR
  T["티켓"] --> Q["Questions<br/>질문 생성"]
  Q --> R["Research<br/>티켓 숨긴 새 맥락, 사실만"]
  R --> D["Design discussion<br/>약 200줄"]
  D --> S["Structure outline<br/>약 2쪽"]
  S --> P["Plan"] --> W["Worktree"] --> I["Implement"] --> PR["PR"]
  H["사람·코드 오너"] -.->|"재조정"| D
  H -.->|"재조정"| S
  H -.->|"코드를 읽는다"| I

• Design discussion(약 200줄): 현재 상태, 원하는 최종 상태, 따를 패턴, 확정된 결정, 열린 질문. 잘못 고른 코드 패턴을 여기서 바로잡는다(「그건 옛 방식이야, 저쪽을 따라」).
• Structure outline(약 2쪽, 계획은 약 8쪽): 단계 개요, 변경 순서, 단계별 테스트 방법. 계획이 구현이라면 outline은 시그니처와 새 타입만 담은 C 헤더 파일이다.
• 수직 계획: 모델은 DB 전부 → 서비스 전부 → API 전부 → 프런트 전부로 짜려 해서 1,200줄 뒤에야 무엇이 깨졌는지 안다. outline에서 목(mock) API → 프런트 연결 → 서비스 → 마이그레이션처럼 체크포인트를 둔 수직 순서로 고친다.
• design discussion과 outline은 코드 오너에게 먼저 보낸다. 2일짜리 기능에서 코딩만 20분으로 줄면 여전히 2일이다. 정렬·리뷰 단계도 줄여야 한다.

grill-me → PRD → 칸반 → AFK 루프

사람과 일할 때 통하던 소프트웨어 공학 기본기가 에이전트에도 그대로 통한다는 관점의 흐름이다. 작업은 사람이 앉아 있어야 하는 일(HITL: 정렬·계획) 과 자리를 떠도 되는 일(AFK: 구현) 로 나눈다. 낮 근무는 사람이 계획하고, 밤 근무는 AI가 구현한다.

flowchart LR
  subgraph HITL["사람이 함께 (낮 근무)"]
    I["브리프"] --> G["grill-me<br/>공유 설계 개념"]
    G --> PRD["PRD = 목적지"]
    PRD --> K["칸반 이슈 = 여정<br/>수직 슬라이스"]
  end
  subgraph AFK["자리를 떠도 됨 (밤 근무)"]
    K --> RL["Ralph 루프<br/>탐색 → TDD → 테스트·타입 검사 → 커밋"]
    RL --> RV["clear 후 자동 리뷰"]
  end
  RV --> QA["사람 QA"]
  QA -->|"새 이슈"| K
  QA -->|"만족"| M["팀 리뷰·머지"]

보조 개념:

• TDD: 실패 테스트 하나 → 통과를 반복한다. 층별로 구현하고 테스트를 몰아 쓰면 테스트를 속인다. 피드백 루프의 질이 AI 코딩 품질의 천장이다.
• 깊은 모듈: 작은 파일이 얽힌 얕은 모듈은 에이전트가 탐색하기 어렵고 테스트 경계가 모호하다. 작은 인터페이스 뒤에 기능이 많은 깊은 모듈을 큰 테스트 경계로 감싸고, 인터페이스는 사람이, 구현은 에이전트가 맡는다.
• push와 pull: CLAUDE.md처럼 늘 보내는 지시가 push, 스킬처럼 필요할 때 당겨 쓰는 것이 pull이다. 구현자에게는 코딩 표준을 pull로, 리뷰어에게는 push로 준다.
• 문서 부패: 끝난 PRD를 저장소에 두면 낡은 내용이 에이전트를 오도한다. 이슈를 닫아 둔다.
• 프런트엔드는 AI의 눈이 약하다. 버리는 라우트에 시안 3개를 만들게 하고 고른 것을 grill 세션에 다시 넣는다.

두 흐름의 공통점과 차이

교차 모델 워크플로

같은 모델은 같은 맹점을 공유하므로 다른 계열 모델에게 검토·검증을 맡긴다. 터미널 두 개를 쓴다.

flowchart LR
  P["1 계획<br/>Claude Code 계획 모드, 터미널 1"] --> F["plans/기능.md"]
  F --> Q["2 검토<br/>Codex CLI, 터미널 2"]
  Q -->|"Phase 2.5 형태로 지적 삽입"| F
  F --> I["3 구현<br/>새 Claude 세션, 단계별 테스트 게이트"]
  I --> V["4 검증<br/>새 Codex 세션, 계획 대비"]
  V -.->|"불일치"| I

검토 모델은 원래 단계를 고쳐 쓰지 않고 「Codex Finding」 같은 중간 단계를 끼워 넣기만 한다. 그래야 누가 무엇을 바꿨는지 남는다. 다른 모델을 붙이는 방법은 셋이다.

모델을 역할로 나누는 원칙은 AI에게 일 맡기기에도 있다.

에이전트 팀

에이전트 팀(베타)은 독립된 Claude Code 세션 여럿이 공유 작업 목록(shared task list)으로 조율하는 구조다. 한 세션 안에서 맥락만 포크하는 서브에이전트와 달리, 팀원마다 CLAUDE.md·MCP·스킬이 로드된 온전한 세션이다.

tmux new -s dev
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

팀 프롬프트는 네 부분으로 짠다.

구현이 서로 독립이고 인터페이스만 맞으면 되기 때문에 병렬로 돈다. 공유 작업 목록에는 「계약 합의」, 「커맨드는 bash가 아니라 Agent 도구를 쓴다」, 「스킬은 받은 값을 다시 조회하지 않는다」 같은 확인 항목을 둔다. 실제로 Claude Code의 플러그인 기능은 스펙 → 티켓 약 100개 → 수백 개 에이전트가 집어 구현하는 방식으로 주말 동안 만들어졌다. 사람용 협업 도구(이슈 보드)가 모델용 협업 도구도 된다. 커맨드 → 에이전트 → 스킬 패턴 자체는 커맨드·스킬·서브에이전트 고르기에 있다.

끝날 때까지 돌리기: /goal, /loop, /schedule

/goal 프롬프트는 직접 쓰기보다 「지금까지를 바탕으로 오래 돌릴 /goal 후보 셋을 제안해」나 「이 세션과 저장소를 분석해 정확한 의도로 /goal 프롬프트를 써 줘, 모호하면 질문해」로 초안을 받는 편이 낫다. 실제 루프 예는 Claude Code 실전 팁에 있다. cron + claude -p로 직접 파이프라인을 짜는 방식은 내 일을 줄이는 하네스 만들기에 있다.

공개 워크플로 비교

README 표(2026-11)의 단계명이다. 별표(*)는 작업마다 반복하는 하위 루프다.

거의 모두 맨 앞에 정렬 단계(grill-me, brainstorming, office-hours, deep-interview, forge-idea, explore)를 두고 구현·검증을 하위 루프로 돌린다. 정답이 정해지지 않은 시기에는 프레임워크를 그대로 들이기보다 계획 스택을 직접 소유하는 편이 낫다.

정리

• 지시 예산(약 150~200개)과 dumb zone(약 40%) 때문에 큰 프롬프트 하나보다 지시가 적은 단계 여럿, 압축보다 clear와 문서 상태가 낫다.
• 조사는 사실만, 계획은 수직 슬라이스로. 긴 계획 문서를 리뷰하기보다 짧은 정렬 문서와 코드를 읽는다.
• 사람은 정렬·QA(HITL)에 앉아 있고, 구현(AFK)은 루프와 샌드박스에 맡긴다. 리뷰는 맥락을 비운 뒤, 가능하면 다른 모델로 한다.
• 병렬은 서브에이전트(한 세션 안)와 에이전트 팀(독립 세션 + 공유 작업 목록)으로 나뉘고, 팀은 데이터 계약만 먼저 합의한다.

관련 노트: 프롬프트에서 하네스로, 루프 엔지니어링, 내 일을 줄이는 하네스 만들기, 멀티 에이전트, 커맨드·스킬·서브에이전트 고르기, AI에게 일 맡기기