# 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 합산
```

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

```bash
# 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 트리거 → 실패 진단 → 버그 리포트

```bash
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 모드 (자동화 기초)

```bash
# 단발 쿼리
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 공식 문서)