D.1 에이전트 성숙도 4단계

실무 팁: 프로덕션 대부분은 L2~L3가 스윗스팟. L4는 인프라·평가·거버넌스 비용이 급격히 증가.

D.2 핵심 패턴 6선

패턴 1. Plan → Execute → Verify 루프

[계획] 작업 단계 생성
   ↓
[실행] 각 단계를 도구 호출로 수행
   ↓
[검증] 테스트·린터·타입체커·스크린샷 비교
   ↓  실패 시 ↻
[보고]

Claude Code 기본 동작이지만, 프롬프트에서 "각 단계 후 npm test를 실행하고 실패 시 스스로 수정하라"를 명시하면 안정도가 크게 향상됩니다.

패턴 2. Critic-Actor 분리

같은 모델에 두 역할을 주고 번갈아 수행:

Role A (Actor): 코드 작성
Role B (Critic): A가 쓴 코드를 엄격히 리뷰 — 버그·보안·성능
A는 Critic 피드백을 반영해 재작성. Critic이 "이상 없음" 선언할 때까지 반복(최대 3회).

Claude의 서브에이전트 기능(Agent SDK)이나 Claude Code의 oh-my-claudecode:critic 같은 스킬로 자동화 가능.

패턴 3. 메모리 분리 (Scratchpad)

에이전트가 긴 작업 중 단기 메모를 남기게 해 컨텍스트 낭비를 막음:

• .claude/notes.md에 진행 상황을 체크리스트로 기록
• 작업 재개 시 이 파일만 읽고 바로 이어감
• 완료된 항목은 삭제해 파일 크기 유지

패턴 4. 도구 호출 예산(Budget)

에이전트가 무한 루프에 빠지지 않도록 상한을 지정:

- 최대 20개 파일 편집까지만
- 도구 호출 30회 초과 시 중단 후 보고
- 비용이 $5 초과 예상되면 확인 요청

패턴 5. Golden Path 우선

에이전트에게 성공 케이스부터 먼저 구현·검증하게 하고, 엣지 케이스는 이후 단계로 분리. 안 그러면 에이전트가 예외 처리에만 매달려 본론이 늦어짐.

패턴 6. Git 중심 워크플로

• 작업 시작 시 브랜치 생성
• 의미 있는 단위마다 중간 커밋
• 검증 실패 시 마지막 성공 커밋으로 git reset하고 재시도

Claude Code의 git worktree 활용 시 실험을 격리할 수 있어 안전도 상승.

D.3 실전 케이스 — 레거시 Java 200 파일 → Spring Boot 3

상황

• Spring Boot 2.7 → 3.2 마이그레이션. javax.* → jakarta.*, Actuator 재구성, Security 설정 변경
• 대상 200 파일, 수작업 시 2~3주 추정

에이전트 설계

1. 계획 에이전트 — 마이그레이션 가이드(공식) + 실제 레포를 읽고 체크리스트 10개 단계로 분해
2. 변환 에이전트 — 각 단계별로 파일을 순회하며 변환 + 개별 커밋
3. 테스트 에이전트 — 각 커밋 후 ./gradlew test 실행, 실패 시 직전 커밋으로 되돌리고 변환 전략 수정
4. 리뷰 에이전트 — 전체 완료 후 git diff를 읽고 PR 설명 작성

결과

• 소요 시간: 실제 2~3주 → 약 9시간(야간 무인 실행 + 아침 리뷰)
• 테스트 통과율 100%, 리뷰 후 12개 수동 보정(대부분 커스텀 어노테이션)
• 비용: API 호출 $28 + PR 리뷰 시간 2시간

교훈

• 작은 커밋이 핵심. 5~20 파일 단위 커밋이 실패 복구의 생명줄
• 테스트가 없으면 에이전트가 일 못함. 마이그 전 테스트 커버리지 확보 선행
• 야간 실행 → 아침 리뷰가 심리적으로 안전. 실시간 감시는 피로

D.4 실전 케이스 — 고객 지원 티켓 분류 에이전트

• 하루 1,200건 티켓 수신. 이전엔 상담사가 수동 라벨링(평균 40초/건 = 13시간/일)
• 에이전트 설계: 티켓 내용 읽기 → 유사 과거 티켓 3건 검색(RAG) → 카테고리·우선도 판정 → 담당팀 라우팅 → 로그 기록
• 결과: 자동 처리율 78%, 수동 재분류 22% → 상담사 2.5명 시간 절감 → 고부가 케이스에 투입
• 주의: 오분류 시 피드백을 RAG 인덱스에 재학습. 분기별 공정성 감사(모듈 B 참고)

D.5 안티 패턴 (피하세요)

• 무한 톱레벨 권한 — "모든 도구 허용 + 모든 디렉토리 쓰기"는 사고의 시간문제. .claude/settings.json의 permission 세분화 필수
• 스스로에게 리뷰 맡기기 — 같은 대화 맥락에서 Actor=Critic은 편향 강함. 최소한 새 세션 또는 별도 모델로 분리
• 추측 기반 픽스 — "일단 돌려보고 에러 나면 고치자"는 에이전트에겐 독. 사전에 테스트 정의 → TDD 흐름이 훨씬 안정
• 컨텍스트 폭식 — 전체 레포를 매번 프롬프트에 넣지 말고, 필요한 파일만 동적으로. Claude Opus 4.7 1M이어도 비용 생각

D.5.1 신규 패턴 — PreToolUse defer 훅 (2026-04)

Claude Code v2.1.89부터 PreToolUse 훅에 세 번째 결정값 defer가 추가됐습니다. 기존엔 allow / deny 둘 뿐이었는데, defer는 훅이 외부 시그널을 기다리며 도구 실행을 일시 정지합니다. 인간 승인·CI 게이트·법무 검토 같은 비동기 단계를 에이전트 흐름에 끼워넣기 좋은 원시 도구입니다.

• 활용 시나리오: 프로덕션 DB 쓰기 → 슬랙으로 매니저 승인 요청 → defer 상태로 대기 → 승인 콜백 수신 시 resume
• 활용 시나리오: git push --force 같은 destructive 명령 → CI에 사전 검증 잡 트리거 → 그린이면 resume
• 주의: 외부 시그널이 영영 안 오면 세션이 멈춘 상태로 남음. 타임아웃 정책 필수 (예: 10분 무응답 → auto-deny)

D.6 PM/PL 관점의 KPI

D.7 참고

• Anthropic Engineering — Building effective agents (research/building-effective-agents)
• Cursor Agent 문서 — docs.cursor.com/agent
• 관련: 부록 A. MCP 서버 개발, 10.6 하네스 엔지니어링