gil
5f664546cf
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
186 lines
5.3 KiB
Markdown
186 lines
5.3 KiB
Markdown
# 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 공식 문서)
|