gil-wiki/wiki/claude-code-workflow-patterns.md

Claude Code 워크플로우 패턴

카테고리: 패턴 & 레시피 최종 수정: 2026-05-13 관련: claude-code-overview, claude-code-project-setup

요약

단순한 것부터 시작하라. Sequential 패턴이 무너질 때만 복잡성을 추가하라. 장기 프로젝트에는 세션 간 상태를 유지하는 Harness 구조가 필요하다.

---

5가지 에이전틱 패턴

패턴 선택 매트릭스

시나리오	패턴
명확한 단계의 선형 작업	Sequential
서브 위임 필요한 대규모 작업	Operator
독립적 항목 다량 처리	Split-and-Merge
다중 도메인 장기 프로젝트	Agent Teams
반복·이벤트 트리거 자동화	Headless

---

1. Sequential (순차)

각 단계가 순서대로 실행. 이전 출력 → 다음 입력.

적합: 예측 가능한 선형 작업, 1~2개 컨텍스트 윈도우에 들어오는 크기.

명세 읽기 → 함수 구현 → 단위 테스트 작성 → 테스트 실행

✅ 최대 단순성, 예측 가능성
❌ 독립 작업 시 낮은 처리량, 긴 작업에서 컨텍스트 한계

---

2. Operator (오케스트레이터)

하나의 제어 에이전트가 계획 → 특화된 subagent나 도구에 실행 위임.

적합: 작업이 단일 컨텍스트 초과, 컴포넌트마다 전문화 필요, 계획과 실행 분리 필요.

오케스트레이터
├── 인증 스캔 subagent
├── DB 쿼리 스캔 subagent
└── 입력 검증 스캔 subagent
→ 결과 종합 → 최종 리포트

✅ 확장성
❌ 오케스트레이터가 병목, 명확한 인터페이스 설계 필요

---

3. Split-and-Merge (병렬)

코디네이터가 독립 청크로 분할 → 병렬 실행 → 결과 합성.

적합: 상호 의존성 없는 분리 가능한 작업, 속도 중요, 대량의 유사 항목 처리.

함수 50개 문서화
→ 5개씩 10 배치로 분할
→ 병렬 실행
→ docstring 합산

✅ 병렬성으로 극적인 성능 향상
❌ 합병 단계 복잡성, 불일관 출력 처리, 비용 상승

# Fan-out 예시
for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

---

4. Agent Teams (다중 에이전트 팀)

역할이 정의된 여러 특화 에이전트가 지속적으로 협업.

적합: 여러 세션에 걸친 장기 프로젝트, 진정한 도메인 전문화 필요.

Planning agent  → 전체 목표 유지
Code agent      → 구현 작성·수정
Testing agent   → 동작 검증
Review agent    → 품질 검사
Documentation agent → 문서 업데이트

✅ 에이전트당 집중된 컨텍스트, 복잡한 지속 작업에 강력
❌ 조율 오버헤드, 오류 전파 위험

---

5. Headless Autonomous (자율 자동화)

인간 개입 없이 이벤트/스케줄로 트리거. 작업 완료까지 독립 실행.

적합: 잘 정의된 반복 작업, 알려진 실패 모드, 완전 자동화.

예시:

• 야간 저장소 스캔 → 의존성 업데이트 → 자동 PR 생성
• CI/CD 트리거 → 실패 진단 → 버그 리포트

claude --permission-mode auto -p "fix all lint errors"

✅ 반복 작업 최대 자동화
❌ 엄격한 안전장치 필요: 최소 권한, 가역적 작업 우선, 종료 조건 명확화

---

장기 실행 에이전트 Harness 패턴

여러 세션에 걸친 프로젝트는 세션 간 상태를 유지하는 구조가 필요하다.

핵심 문제

각 세션은 이전 작업을 기억하지 못한 채 시작된다. 인간이 세션 사이 컨텍스트를 복구해주면 안 된다 — 에이전트가 스스로 추적해야 한다.

2단계 Harness 구조

1단계: Initializer Agent (첫 번째 세션)

init.sh 생성          → 환경 설정 스크립트
claude-progress.txt 생성 → 진행 상황 추적 로그
기능 목록 작성         → JSON으로 관리 (passing/failing 상태)
초기 git commit        → 추가된 파일 기록

2단계: Coding Agent (이후 세션들)

매 세션 시작 루틴:
1. pwd (현재 디렉토리 확인)
2. progress 파일 읽기
3. 다음 기능 선택
4. init.sh 실행
5. 핵심 기능 동작 확인
6. 점진적 변경 구현 (한 번에 기능 하나)

실패 모드와 대응

문제	해결
전체 프로젝트를 한 번에 완성하려 함	feature list를 "failing" 상태로 목록화, 하나씩만 허용
테스트 없이 "완료" 선언	Puppeteer MCP로 브라우저 자동화 테스트 의무화
버그를 기록 없이 방치	설명적 커밋 메시지 + progress 파일 업데이트 강제

---

Non-interactive 모드 (자동화 기초)

# 단발 쿼리
claude -p "이 프로젝트가 무엇인지 설명해줘"

# JSON 출력 (스크립트 파싱용)
claude -p "API 엔드포인트 나열해줘" --output-format json

# 스트리밍
claude -p "로그 파일 분석해줘" --output-format stream-json

---

참고 / 출처

• raw/claude-code-5-agentic-workflow-patterns.md (mindstudio.ai)
• raw/claude-code-long-running-agent-harnesses.md (Anthropic 엔지니어링 블로그)
• raw/claude-code-best-practices-official.md (code.claude.com 공식 문서)