03 - 에이전트 워크플로: AI 문제 분해
AI가 보조자 역할을 멈추고 협력자가 되는 정확한 순간이 있습니다. 네가 묻기를 멈추면 "이 함수를 작성하세요" 그리고 당신은 그녀에게 묻기 시작합니다 "해결하다 이 문제". 단일 지시에서 복잡한 작업에 이르기까지 정신적 도약은 마음입니다. 신들 에이전트 워크플로. 또한 대부분의 개발자가 효과적인 에이전트 워크플로를 구축하려면 근본적인 패러다임 전환이 필요하기 때문에 막히게 됩니다. 더 긴 프롬프트가 아니라 아키텍처에 관한 것입니다.
2025년에는 미국 개발자의 92%가 일상 업무에서 AI 도구를 사용합니다. (Stack Overflow Developer Survey 2025), 그러나 이들 중 일부만이 실제로 에이전트 시스템의 잠재력. 문제는 기술에 대한 접근이 아니라 기술의 부족이다 명확한 아키텍처 패턴의 복잡한 문제를 분해하다 작업에서 AI 에이전트가 안정적이고 검증 가능하며 반복 가능한 방식으로 문제를 해결할 수 있습니다.
이 문서에서 우리는 에이전트 워크플로에 대한 깊은 이해를 함께 구축할 것입니다. fundamental patterns (Sequential, Parallel, Hierarchical, Iterative) to the implementation Claude Code를 사용하여 컨텍스트 관리, 품질 지표 및 유망한 작업 흐름을 신뢰할 수 없는 시스템으로 바꾸는 안티 패턴입니다. 모든 것 실제 사례 연구와 작업 코드를 통해
무엇을 배울 것인가
- 네 가지 기본 분해 패턴: 순차, 병렬, 계층, 반복
- 에이전트 워크플로의 아키텍처: 플래너, 실행자, 검토자, 메모리
- 실제 프로젝트에서 에이전트를 안내하기 위해 CLAUDE.md를 구성하는 방법
- 계획-실행-검토 루프 및 자가 복구 워크플로우
- 긴 에이전트 세션을 위한 도구 사용 및 컨텍스트 관리
- 에이전트 워크플로의 품질을 평가하는 측정항목
- 가장 위험한 안티 패턴과 이를 방지하는 방법
- 사례 연구: 에이전트 워크플로를 사용하여 Angular 코드베이스 리팩터링
에이전트 워크플로란 무엇입니까?
Un 에이전트 워크플로 그리고 하나 이상의 구조화된 작업 순서 AI 에이전트는 복잡한 목표를 달성하기 위해 작업을 계획, 실행 및 확인합니다. 에이 단일 LLM 호출과 달리 에이전트 워크플로에는 단계 사이에 메모리가 있습니다. 도구(파일 시스템, 터미널, 웹, API)는 하위 작업을 전문 에이전트에 위임할 수 있으며 사람의 개입 없이 오류에 적응할 수 있습니다.
"순진한" 바이브 코딩과의 주요 차이점은 다음과 같습니다. 의도적인 구조. Claude에게 "이 코드베이스를 리팩터링"하라고 요청하면 평범한 결과가 나옵니다. 워크플로우 구축 (1) 코드베이스를 분석하고, (2) 우선 순위에 따라 리팩터링할 구성 요소를 식별합니다. (3) 회귀 테스트를 통해 한 번에 하나의 구성 요소를 리팩토링하고, (4) 각 단계를 먼저 테스트합니다. 진행하면 전문적인 결과를 얻을 수 있습니다. 차이와 분해.
운영상의 정의
에이전트 워크플로 e 믿을 수 있는 언제: 각 단계가 독립적으로 검증 가능하며, 한 단계의 실패로 인해 전체 작업 흐름, 최종적이고 결정적인 출력이 손상되지 않습니다. 입력과 관련하여 인간 운영자는 언제든지 작업 흐름을 검사하고 수정할 수 있습니다. 검문소. 이 정의는 인류학 프레임워크 "효과적인 에이전트 구축"(2024)에서 나온 것입니다. 구현을 평가하기 위한 나침반으로 남아 있습니다.
문제 분해: 에이전트 워크플로의 핵심
TDAG 연구(Task Decomposition and Agent Generation, 2025)에서는 품질이 다음과 같은 것으로 나타났습니다. 분해 및 다중 에이전트 시스템 성공의 가장 예측 가능한 요소는 다음과 같습니다. 잘못된 분해는 후속 단계를 통해 오류를 기하급수적으로 전파합니다. 올바른 분해는 오류를 격리하고 복구를 허용합니다.
네 가지 기본 분해 패턴이 있으며 각각은 다양한 유형의 문제에 적합합니다.
패턴 1: 순차(체인)
가장 간단한 패턴: 각 작업은 이전 작업의 결과에 따라 달라집니다. 선형 워크플로에 적합 순서가 의미상 중요한 경우(예: 분석 -> 설계 -> 구현 -> 테스트)
Pattern Sequential:
[Input]
|
v
[Task A] --> output_A
|
v
[Task B] --> output_B
|
v
[Task C] --> [Output Finale]
Caratteristiche:
- Ogni task riceve output del precedente come contesto
- Fallimento in Task B blocca Task C
- Debugging semplice: errore localizzato al task fallito
- Latenza: somma di tutti i tempi (A + B + C)
Caso d'uso tipico: Pipeline di generazione codice
1. Analisi requisiti
2. Design architetturale
3. Implementazione
4. Test generation
5. Documentation패턴 2: 병렬(분산-수집)
여러 개의 독립적인 작업이 수집기와 함께 별도의 에이전트에 의해 동시에 실행됩니다. 결과를 수집하고 요약하는 것입니다. 대기 시간을 대폭 줄여주지만 다음 사항이 필요합니다. 하위 작업은 완전히 독립적입니다(변경 가능한 상태를 공유하지 않음).
Pattern Parallel (Scatter-Gather):
[Input]
|
[Orchestrator/Splitter]
/ | \
v v v
[Task A] [Task B] [Task C]
out_A out_B out_C
\ | /
v v v
[Aggregator/Merger]
|
[Output Finale]
Caratteristiche:
- Task A, B, C eseguiti in parallelo (via sub-agents)
- Latenza: max(A, B, C) invece di A + B + C
- Fallimento parziale: gestibile se aggregatore e robusto
- Rischio: race condition su risorse condivise
Caso d'uso tipico: Review multi-dimensionale
Agent 1: Security review
Agent 2: Performance analysis
Agent 3: Code style check
Agent 4: Test coverage analysis
Aggregator: Synthesize findings패턴 3: 계층적(감독자-근로자)
감독 에이전트는 문제를 하위 작업으로 분해하고 전문 작업자에게 위임합니다. 노동자 그들은 차례로 하위 작업자를 가질 수 있습니다. 그리고 큰 문제에 대한 가장 강력한 패턴 디버깅하기 가장 복잡하기도 합니다. LangGraph는 이 패턴을 가장 많이 문서화했습니다. 2025년에 엔터프라이즈 시스템용으로 채택되었습니다.
Pattern Hierarchical:
[Planner Agent]
"Refactorizza il modulo auth"
/ | \
v v v
[Backend Agent] [Frontend] [Test Agent]
"Refactorizza "Aggiorna "Aggiorna
AuthService" LoginCmp" test suite"
| | |
[sub-tasks] [sub-tasks] [sub-tasks]
| | |
done done done
\ | /
v v v
[Planner: Merge & Verify]
|
[Output Finale]
Livelli tipici in sistemi reali:
L0: Problem Planner (decompone goal globale)
L1: Domain Agents (backend, frontend, infra)
L2: Task Workers (singoli file, funzioni)
L3: Tool Calls (bash, file system, test)패턴 4: 반복(반응/반사)
에이전트는 루프에서 작동합니다. 작업을 수행하고, 결과를 관찰하고, 현재 상태를 반영합니다. 그리고 다음 단계를 결정합니다. 그리고 패턴의 ReAct 프레임워크 (추론 + 연기) 및 그 확장인 반사(노골적인 비판을 추가함)입니다. 문제에 적합 솔루션 경로가 선험적으로 알려지지 않은 탐색적입니다.
Pattern Iterative (ReAct + Reflexion):
[Goal]
|
v
[Think] <-----------+
| |
v |
[Act / Tool Use] | (se max_iter non
| | raggiunto e goal
v | non soddisfatto)
[Observe] |
| |
v |
[Critique/Reflect]--+
|
(se goal soddisfatto)
|
v
[Output]
Elementi chiave:
- Scratchpad: memoria degli step precedenti
- Stop condition: goal raggiunto O max_iterations
- Critique: valutazione esplicita dell'output parziale
- Tool repertoire: set di tool disponibili all'agente
Caso d'uso: Debugging di un test che fallisce
1. Leggi error message
2. Analizza codice correlato
3. Formula ipotesi
4. Applica fix
5. Esegui test
6. Se fallisce ancora: ritorna a step 2
7. Se passa: scrivi explanation에이전트 워크플로의 아키텍처
선택한 패턴에 관계없이 성숙한 에이전트 워크플로에는 네 가지 구성 요소가 있습니다. 기본. 이를 이해하는 것은 프로덕션에서 강력한 시스템을 구축하기 위한 전제 조건입니다.
1. 플래너
The Planner receives the high-level goal and turns it into a structured plan: a sequence 종속성이 있는 하위 작업(또는 DAG), 에이전트에 할당, 각 단계의 성공 기준 및 자원 추정(토큰 예산, 필요한 도구). 좋은 플래너는 계획을 세운다 증명할 수 있는: 각 단계에는 잘 정의된 예상 결과가 있습니다.
2. 집행자
Executor는 Planner에서 개별 작업을 가져와 파일 시스템, 파일 시스템,
bash, 웹 검색, API. 각 전문 실행자(백엔드 에이전트, 테스트 에이전트, 문서 에이전트)는
다음의 원칙에 따라 해당 도메인에 필요한 도구에만 액세스합니다.
최소 권한. Claude Code는 이를 시스템을 통해 구현합니다.
권한 및 사용자 정의 하위 에이전트 allowedTools 구성 가능.
3. 심사위원
검토자는 각 실행자의 출력이 정의된 성공 기준을 충족하는지 확인합니다. 플래너에서. 이는 단순한 "괜찮아 보인다"가 아닙니다. 품질 검토자가 자동 테스트를 수행합니다. 정적 분석, 회귀 검사. 검토자가 승인할 수 있으며(워크플로 진행), 변경을 요청하거나(실행자 재시도) 사람에게 에스컬레이션합니다(필수 체크포인트).
4. 기억
메모리는 워크플로우 단계를 통해 컨텍스트를 관리합니다. 여기에는 두 가지 수준이 있습니다.
- 단기(상황에 맞게): 현재 컨텍스트 창의 내용, 이전 단계의 출력을 포함합니다. 사용 가능한 토큰으로 제한됩니다.
-
장기(외부): 상태 파일(예:
claude-progress.txt), 데이터베이스, Git 기록. 여러 세션 간에 중단된 워크플로를 재개할 수 있습니다.
패턴 clude-progress.txt
Anthropic은 다음을 사용할 것을 권장합니다. claude-progress.txt 프로젝트 루트에서
for inter-session memory. 개시자 에이전트는 워크플로우 상태를 다음과 같이 기록합니다.
검문소; 다음 에이전트는 이 파일을 읽어 작업 위치와 내용을 파악합니다.
해야합니다. 와 결합하여 git log, 없이 전체 컨텍스트를 제공합니다.
컨텍스트 창을 포화시킵니다.
Claude Code를 통한 실제 구현
Claude Code는 에이전트 워크플로 구축을 위한 세 가지 주요 도구를 제공합니다.
클로드.md 에이전트의 행동을 안내하기 위해
작업 도구 하위 에이전트에게 위임하고 저는 맞춤 에이전트
(에 정의됨 .claude/agents/) 전문화로. 그것들을 결합하는 방법을 살펴 보겠습니다.
에이전트 워크플로를 위한 CLAUDE.md 구조
CLAUDE.md 파일은 AI 에이전트에 대한 프로젝트의 "구성"입니다. 클로드.md 에이전트 워크플로용으로 설계된 여기에는 프로젝트 정보뿐만 아니라 워크플로 자체의 구조: 어떤 에이전트가 존재하는지, 어떻게 조정하는지, 각 단계의 성공 기준.
# CLAUDE.md - Workflow Agentico per Progetto Angular
## Progetto
Portfolio Angular con SSR, Angular 21, TypeScript strict.
Stack: Angular, Firebase, SCSS.
## Workflow Agentici Disponibili
### Workflow: Feature Development
Usa questo workflow per implementare nuove feature:
**Fase 1 - Planning** (obbligatoria):
- Leggi tutti i file correlati alla feature
- Crea `docs/plans/[feature-name].md` con:
- Componenti da creare/modificare
- Interfacce TypeScript necessarie
- Test da scrivere (TDD: scrivi prima i test)
- Dipendenze e rischi
- NON implementare finchè il piano non e approvato
**Fase 2 - TDD Implementation**:
- Scrivi unit test PRIMA dell'implementazione
- Implementa il minimo necessario per far passare i test
- Poi refactorizza
- Verifica `npm test` passa senza errori
**Fase 3 - Review**:
- Esegui `npm run lint`
- Verifica che build SSR compili: `npm run build`
- Controlla che non ci siano regressioni
### Workflow: Refactoring
Per refactoring di componenti esistenti:
1. Crea branch: `git checkout -b refactor/[nome]`
2. Analizza dipendenze del componente con grep/Glob
3. Refactorizza UN componente alla volta
4. Verifica test dopo ogni componente
5. Commit atomico per ogni componente
### Workflow: Debug
Per bug fixing:
1. Riproduci il bug con un test che fallisce
2. Identifica root cause (NON fixare sintomi)
3. Applica fix minimale
4. Verifica che il test ora passi
5. Controlla regressioni
## Agenti Specializzati
Disponibili in `.claude/agents/`:
- `architect.md`: Per decisioni architetturali
- `security-reviewer.md`: Prima di ogni commit
- `code-reviewer.md`: Dopo ogni implementazione
- `tdd-guide.md`: Per TDD workflow
## Criteri di Successo Globali
- TypeScript strict: zero errori `tsc --noEmit`
- Test coverage: minimo 80%
- Build SSR: `npm run build` deve completare senza errori
- Nessun `any` implicito
- Nessuna mutazione di stato (immutability pattern)
## Gestione Errori
Se un comando fallisce:
1. Leggi l'errore completo
2. NON procedere al passo successivo
3. Identifica e risolvi prima di continuare
4. Se non riesci dopo 2 tentativi: STOP e chiedi chiarimenti태스크 분해를 위한 신속한 엔지니어링
분해 품질은 초기 프롬프트의 품질에 직접적으로 좌우됩니다. 다음은 에이전트가 복잡한 작업을 분해하도록 안내하는 테스트된 템플릿입니다.
# Prompt Template: Task Decomposition
## Contesto
Sei un Planning Agent. Il tuo compito e decomporre il goal seguente
in subtask concreti, verificabili e assegnabili a agenti specializzati.
## Goal
[DESCRIZIONE DEL GOAL]
## Vincoli
- Ogni subtask deve avere: ID, descrizione, input atteso, output atteso,
agente responsabile, criteri di successo (verificabili automaticamente)
- I subtask devono essere ordinati per dipendenze (DAG)
- Nessun subtask deve durare più di [X] minuti / [Y] token
- Definisci i checkpoint obbligatori dove un umano deve approvare
## Output Atteso
Produci un piano strutturato in questo formato JSON:
{
"goal": "descrizione del goal",
"estimated_complexity": "low|medium|high",
"subtasks": [
{
"id": "T001",
"description": "Analizza la struttura del componente AuthService",
"agent": "analyzer",
"inputs": ["src/app/services/auth.service.ts"],
"outputs": ["docs/analysis/auth-service.md"],
"success_criteria": ["file creato", "contiene sezioni: deps, interfaces, methods"],
"depends_on": [],
"estimated_tokens": 8000
},
{
"id": "T002",
"description": "Scrivi test per AuthService",
"agent": "tdd-agent",
"inputs": ["docs/analysis/auth-service.md", "src/app/services/auth.service.ts"],
"outputs": ["src/app/services/auth.service.spec.ts"],
"success_criteria": ["npm test -- --testPathPattern=auth.service passa"],
"depends_on": ["T001"],
"estimated_tokens": 12000
}
],
"checkpoints": ["dopo T001: review del piano", "dopo T003: review implementazione"],
"rollback_strategy": "git stash prima di ogni modifica distruttiva"
}하위 에이전트에 대한 작업 도구 사용
Claude Code는 작업을 하위 에이전트에 위임하기 위한 작업 도구를 제공합니다. 각 하위 에이전트가 작동합니다. 워크플로우를 관리할 수 있는 자체 컨텍스트 창이 있는 격리된 컨텍스트에서 단일 세션의 한도를 초과합니다. 인류학 연구(2026 Agentic Coding Trends Report)는 가장 효과적인 패턴이 오케스트레이션을 위해 Opus를 사용하고 Sonnet을 사용함을 나타냅니다. 작업자의 경우 품질을 유지하면서 비용을 40~60% 절감합니다.
# Prompt per orchestrare sub-agents con Task tool
Devo refactorizzare il modulo di autenticazione di questa Angular app.
Ho analizzato il codebase e identifico questi task paralleli indipendenti:
**Task 1 - Security Review** (usa Task tool):
Prompt: "Leggi src/app/services/auth.service.ts e tutti i file che lo importano.
Analizza vulnerabilità di sicurezza: token storage, session management,
CSRF protection. Produci un report markdown in docs/security/auth-review.md
con priorità: CRITICAL, HIGH, MEDIUM, LOW."
Tools: Read, Grep, Write
**Task 2 - Test Coverage Analysis** (usa Task tool):
Prompt: "Analizza src/app/services/auth.service.spec.ts vs auth.service.ts.
Identifica funzioni non coperte dai test. Produci lista in docs/analysis/test-gaps.md"
Tools: Read, Glob, Grep, Write
**Task 3 - Dependency Graph** (usa Task tool):
Prompt: "Mappa tutte le dipendenze di AuthService usando grep e glob.
Crea docs/analysis/auth-deps.md con grafo ASCII delle dipendenze."
Tools: Read, Glob, Grep, Write
Esegui i 3 Task in parallelo. Quando tutti completano, leggi i 3 report
e produci docs/plans/auth-refactoring.md con il piano di refactoring
consolidato, ordinato per priorità."고급 워크플로 패턴
계획-실행-검토 루프
PER(계획-실행-검토) 루프는 복잡한 워크플로에 대한 가장 강력한 패턴입니다. 매 반복은 다음 단계로 진행하기 전에 검증 가능한 아티팩트를 생성합니다. 열쇠 검토 단계는 선택 사항이 아닙니다. 이는 오류 전파를 방지하는 메커니즘입니다.
Plan-Execute-Review Loop:
ITERAZIONE 1:
Plan: "Analizza AuthService e crea piano di refactoring"
Execute: Agente legge codice, scrive docs/plans/auth.md
Review: Verifica che docs/plans/auth.md esiste e ha sezioni richieste
-> PASS: procedi a iterazione 2
-> FAIL: retry Execute (max 2 volte), poi escalate
ITERAZIONE 2:
Plan: "Scrivi test per AuthService (basati sul piano)"
Execute: Agente scrive auth.service.spec.ts
Review: `npm test -- --testPathPattern=auth` deve passare
-> PASS: procedi a iterazione 3
-> FAIL: agente debug + retry
ITERAZIONE 3:
Plan: "Refactorizza AuthService (TDD: test devono restare verdi)"
Execute: Agente modifica auth.service.ts
Review: `npm test` + `tsc --noEmit` + `npm run lint`
-> PASS: procedi a iterazione 4
-> FAIL: `git checkout src/app/services/auth.service.ts` + retry
ITERAZIONE 4:
Plan: "Aggiorna componenti che usano AuthService"
Execute: Agente aggiorna LoginComponent, ProfileComponent, etc.
Review: `npm run build` (SSR build completa)
-> PASS: workflow completato
-> FAIL: rollback + analisi root cause
Metriche del Loop:
- Tasso di retry per iterazione (ideale: <20%)
- Token consumati per iterazione
- Tempo per iterazione
- Success rate complessivo다중 에이전트 코드 검토 파이프라인
다중 에이전트 코드 검토 파이프라인 및 가장 성숙한 워크플로 사용 사례 중 하나 2025년의 에이전트. 각 전문 에이전트는 서로 다른 관점과 집계를 제공합니다. 단일 에이전트보다 더 포괄적인 검토를 생성합니다.
Pipeline Multi-Agent Code Review:
Input: Pull Request con modifiche al codebase
FASE 1 - Parallel Review (4 agenti in parallelo):
Agent A: Security Reviewer
- Cerca: SQL injection, XSS, CSRF, secrets esposti
- Tool: Read, Grep (pattern: hardcoded secrets, eval, innerHTML)
- Output: security-report.md (CRITICAL/HIGH/MEDIUM/LOW)
Agent B: Performance Analyst
- Cerca: memory leak, N+1 queries, bundle size impact
- Tool: Read, Glob, Bash (npm run analyze)
- Output: performance-report.md
Agent C: Type Safety Checker
- Cerca: any impliciti, type assertion unsafe, null check mancanti
- Tool: Read, Bash (tsc --noEmit --strict)
- Output: types-report.md
Agent D: Test Coverage
- Verifica: nuove funzioni hanno test, edge cases coperti
- Tool: Read, Bash (npm test -- --coverage)
- Output: coverage-report.md
FASE 2 - Synthesis (1 agente):
Input: i 4 report paralleli
Task: Sintetizza in PR-review.md con:
- Issues raggruppate per severita
- Blockers (nessun merge finchè non risolti)
- Suggestions (opzionali ma consigliate)
- Positive findings (cosa e fatto bene)
FASE 3 - Human Checkpoint:
Il developer legge PR-review.md e decide:
- Merge as is (zero blockers)
- Fix blockers e re-run pipeline
- Request clarification on specific issues자가 복구 워크플로: 재시도 및 대체
생산 워크플로가 실패합니다. 문제는 '만약'이 아니라 '언제', '어떻게 회복하느냐'이다. 자가 복구 워크플로는 지수 백오프, 롤백을 사용하여 재시도 전략을 구현합니다. 자동으로 마지막 유효한 체크포인트로 이동하고 대체 전략으로 대체 기본 경로가 반복적으로 실패합니다.
Self-Healing Workflow Pattern:
STRATEGIA 1: Retry con Backoff
Tentativi: 1, 2, 3 (max)
Attesa: 0s, 30s, 120s
Condizione retry: errore transitorio (timeout, rate limit)
Condizione NO retry: errore logico (file non trovato, syntax error)
STRATEGIA 2: Checkpoint + Rollback
Prima di ogni modifica distruttiva:
$ git stash push -m "checkpoint-[step-id]-[timestamp]"
Se step fallisce dopo max retry:
$ git stash pop # rollback allo stato precedente
-> Notifica umano con context dell'errore
STRATEGIA 3: Alternative Path
Step principale: Refactorizza con TypeScript strict
Se fallisce 3 volte:
Fallback 1: Refactorizza con TypeScript non-strict + TODO commenti
Se fallisce ancora:
Fallback 2: Documenta il problema invece di risolvere
Escalate: crea docs/issues/[step-id]-blocked.md
STRATEGIA 4: Isolamento Fallimenti
Workflow di 10 step:
Step 1-5: completati con successo
Step 6: fallisce
-> NON annullare step 1-5
-> Salva stato "parzialmente completato"
-> Riprendi da step 6 dopo fix manuale
IMPLEMENTAZIONE in Claude Code:
"Se il comando fallisce, NON procedere al passo successivo.
Prima di ogni modifica ai file, esegui:
git stash push -m 'pre-[descrizione]'
Se dopo 2 tentativi il task non funziona, STOP.
Crea docs/blocked/[task-id].md con:
- Comando che ha fallito
- Output dell'errore completo
- Ipotesi sulla causa
- Cosa e stato completato prima del blocco"도구 사용 및 컨텍스트 관리
컨텍스트 관리는 아마도 에이전트 워크플로에서 가장 미묘한 기술적 과제일 것입니다. 잘못 관리된 컨텍스트 창은 성능 저하, 건망증 및 환각을 초래합니다. 잘 관리되는 컨텍스트 창을 통해 수천 개의 코드베이스에서 몇 시간 동안 에이전트 세션을 수행할 수 있습니다. 파일의.
토큰 예산 및 우선순위
Claude Code는 200,000개 토큰의 컨텍스트 창으로 작동하지만 이를 모두 한 번에 소비합니다. 세션 및 안티 패턴. 인류 연구에 따르면 60~80% 범위에서 작동하는 것으로 나타났습니다. 일정한 품질을 유지하기 위한 최대 컨텍스트 창. 80% 이상, 답변의 질 현저히 저하됩니다.
Strategie di Context Management:
1. PROGRESSIVE SUMMARIZATION
Dopo ogni step completato:
"Aggiorna claude-progress.txt con un riassunto conciso di questo step:
- Cosa e stato fatto
- File modificati (lista)
- Test status (pass/fail)
- Prossimo step previsto
MAX 200 parole. Poi usa /compact per comprimere la conversazione."
2. SELECTIVE LOADING
NON leggere tutti i file del progetto all'inizio.
Leggi solo i file rilevanti per il task corrente:
- Usa Glob per identificare file per pattern
- Usa Grep per trovare dipendenze specifiche
- Leggi file solo quando necessario (lazy loading)
3. EXTERNAL STATE
File di stato persistenti (sopravvivono tra sessioni):
- claude-progress.txt: stato workflow corrente
- docs/plans/[feature].md: piano approvato
- docs/analysis/[component].md: analisi completate
Inizio sessione: "Leggi claude-progress.txt e docs/plans/
attivi. Dimmi dove siamo nel workflow e cosa devi fare ora."
4. TOOL CHAINING EFFICIENTE
INSTEAD OF: Read 20 file + analizza tutto
DO THIS:
1. Grep per pattern specifico (trova file rilevanti)
2. Glob per struttura directory
3. Read SOLO i file identificati come rilevanti
4. Elabora
Risparmio tipico: 60-70% token
5. CHECKPOINT COMPACTION
Ogni 5-10 step complessi, usa /compact in Claude Code.
Poi ricarica contesto da claude-progress.txt.
Mantieni la sesione fresca per i task restanti.도구 호출 관리
각 도구 호출은 도구 사용 및 응답 모두를 위해 토큰을 사용합니다. 효율적인 관리 긴 작업 흐름에 대한 도구 호출 및 비판. 핵심 원리 e 일괄 처리: 별도의 호출을 많이 하는 대신 여러 작업을 동일한 도구 호출로 집계합니다.
안티 패턴: Tool Call Storm
일반적인 실수는 에이전트에게 명시적인 루프를 사용하여 한 번에 하나씩 파일을 읽도록 요청하는 것입니다.
이로 인해 수백 개의 도구 호출이 생성되고 컨텍스트가 빠르게 포화됩니다. 대신 패턴을 사용하세요.
어떻게 Glob + Grep 관련 파일을 식별하려면 해당 파일만 읽으십시오.
Claude Code는 독립적인 경우 여러 도구 호출을 병렬로 실행할 수 있습니다.
기능은 순차 호출에 비해 대기 시간을 40-60% 줄입니다.
에이전트 워크플로의 측정 및 평가
“작동한다”는 것은 지표가 아닙니다. 에이전트 워크플로를 평가하고 개선하려면 측정항목이 필요합니다. 신뢰성, 출력 품질, 효율성 및 안전성이라는 네 가지 차원에 대한 정량적 정보입니다.
Framework di Metriche per Workflow Agentici:
AFFIDABILITA
- Task Completion Rate (TCR): % task completati senza intervento umano
Target: >85% per workflow di produzione
- Retry Rate: % step che richiedono più di 1 tentativo
Target: <20% per step (>20% indica task mal specificato)
- Escalation Rate: % step escalati a umano
Target: dipende dal rischio del dominio (5-30%)
QUALITA OUTPUT
- Test Pass Rate: % test che passano dopo il workflow
Target: 100% (zero regressioni accettabili)
- Build Success Rate: % build SSR che completano senza errori
Target: 100%
- Code Review Score: punteggio da code-reviewer agent (1-10)
Target: >7 prima di merge
EFFICIENZA
- Token per Task: token consumati / task completato
Baseline: misura nelle prime 10 esecuzioni
- Latenza End-to-End: tempo totale del workflow
Ottimizza con parallelismo quando bottleneck identificato
- Cost per Feature: costo API totale / feature implementata
Target: definito dal business, tipico $0.10 - $2.00
SICUREZZA
- Destructive Operations Count: operazioni che modificano/eliminano dati
Flag ogni operazione con rm, DROP, DELETE, overwrite
- Unauthorized Tool Use: tool calls non consentite dal CLAUDE.md
Target: 0 (monitorato via hooks)
- Secret Exposure: secrets nel codice generato
Verifica automatica con grep patterns피해야 할 안티패턴
에이전트 시스템에 관한 2025년 문헌에서는 반복되는 실패 패턴을 확인했습니다. 이를 미리 아는 것이 강력한 워크플로우를 구축하는 가장 효율적인 방법입니다.
1. 과분해
작업을 너무 많은 하위 작업으로 나누면 이점보다 더 큰 조정 오버헤드가 발생합니다. 작업에 소요되는 시간이 5분 미만이고 토큰이 3,000개라면 위임하는 것이 의미가 없을 것입니다. 별도의 하위 에이전트에게. 다중 에이전트 연구에 따르면 에이전트가 5~7개 이상인 시스템은 동시에 활성 상태인 경우 오류율이 기하급수적으로 높아지는 경향이 있습니다. (Towards Data Science, 2025에 문서화된 소위 "17x 오류 트랩").
과분해: 예
잘못된: 15개의 하위 에이전트를 생성하여 15개의 기능을 단일 기능으로 리팩터링
200줄 파일. 조정 오버헤드(에이전트별 컨텍스트 설정,
결과, 충돌 관리)이 단일 에이전트에 소요되는 시간을 초과합니다.
옳은: 단일 에이전트가 파일을 읽고 15가지 기능을 식별하며,
중간 테스트를 통해 순차적으로 리팩터링합니다. 파일/모듈 전용 하위 에이전트
독립적이고 규모가 크다.
2. 사양 미달
모호하게 설명된 작업은 예측할 수 없는 결과를 생성합니다. "코드 개선"은 작업이 아닙니다. 그리고 희망. 각 작업은 다음을 지정해야 합니다. 수행할 작업, 어떤 파일, 준수할 제약 조건, 성공을 확인하는 방법. 사양 부족이 워크플로의 가장 큰 원인인 것으로 보입니다. 작동하지만 출력 품질이 좋지 않습니다.
3. 맥락 오염
관련 없는 컨텍스트를 컨텍스트 창에 너무 많이 로드하는 경우(불필요한 파일, 대화 선례, 자세한 문서)는 답변의 품질을 저하시킵니다. '잃어버린' 현상 중간”(2024년 LLM 연구에 의해 문서화됨)은 LLM의 성과가 낮다는 것을 보여줍니다. 컨텍스트 창 중앙에 있는 정보에 주의하세요. 맥락을 깔끔하고 집중적으로 유지하세요 그리고 구조화되어 있습니다.
4. 누락된 롤백 전략
에이전트가 프로덕션 데이터베이스를 삭제한 2025년 Replit 사건과 롤백 전략이 없는 워크플로의 가장 많이 인용되는 예입니다. 파괴적인 작업(삭제, 덮어쓰기, DROP)에는 실행 취소 메커니즘(git stash, 백업, 되돌릴 수 있는 트랜잭션)이 있어야 합니다. “에이전트는 자신이 무엇을 하고 있는지 알고 있었습니다”는 재해 복구 전략이 아닙니다.
5. 인간 개입 금지
사람의 체크포인트가 없는 완전 자동화된 워크플로는 작업에만 적합합니다. 위험이 낮고 잘 이해되어 있습니다. 인류학 연구(2026 에이전트 코딩 동향 보고서) 개발자는 작업의 20%만 완전히 위임(감독 0%)함을 보여줍니다. 나머지 80%에는 하나 이상의 검토 체크포인트가 필요합니다. Human-in-을 통한 디자인 워크플로 아키텍처 결정, 배포 및 데이터 변경을 위한 명시적인 the-Loops입니다.
6. 세션간 메모리리스 에이전트
각각의 새로운 Claude Code 세션은 처음부터 시작됩니다. 복잡한 작업 흐름(5시간 이상의 작업)
외부 상태를 작성하지 않으며 진행 상황을 잃을 운명입니다. 항상 사용 claude-progress.txt,
계획 파일 docs/ 지속성 메커니즘으로 자주 커밋합니다.
사례 연구: Agentic 워크플로를 사용하여 Angular 코드베이스 리팩토링
이러한 원칙이 실제 사례에 어떻게 적용되는지 살펴보겠습니다. 블로그 모듈 리팩토링 레거시 아키텍처의 Angular 포트폴리오(대형 구성 요소, 템플릿의 논리, 테스트 없음)을 최신 아키텍처(소형 구성 요소, 별도의 서비스, 80% 이상의 적용 범위)로 전환합니다.
문맥
- 코드베이스: Angular 21, SSR, 블로그 모듈의 ~3,000줄
- 문제: 테스트 적용 범위 0%, 행 구성 요소 500개 이상, 문제 분리 없음
- 목표: 기능적 회귀 없이 리팩토링 완료
- 제약 조건: 활성 생산, 가동 중지 시간이 허용되지 않음
워크플로우 설계
WORKFLOW: Blog Module Refactoring
FASE 0 - Setup (5 min, umano):
$ git checkout -b refactor/blog-module
Crea claude-progress.txt con stato iniziale
Crea docs/plans/blog-refactoring.md (vuoto, agente lo popolera)
FASE 1 - Analysis (agente, ~30 min):
Task: "Analizza il modulo blog completo.
Leggi tutti i file in src/app/articles/ e src/app/services/blog.service.ts.
Crea docs/analysis/blog-module.md con:
- Lista completa componenti e loro dimensioni (righe)
- Dipendenze tra componenti (chi importa chi)
- Logica duplicata identificata
- Violazioni separation of concerns
- Priorità di refactoring (impatto x sforzo)"
Review: Umano legge docs/analysis/blog-module.md e approva il piano
FASE 2 - Test Foundation (agente, ~60 min):
Task: "Scrivi test E2E per le funzionalità critiche del blog
PRIMA di qualsiasi refactoring. Usa Playwright.
Funzionalità da coprire:
- Navigazione alla lista articoli
- Apertura articolo specifico
- Navigazione serie (prev/next)
- Switch lingua IT/EN
I test devono passare sulla versione CORRENTE del codice."
Review: `npm run test:e2e` deve avere 100% dei test E2E verdi
FASE 3 - Service Extraction (agente, ~90 min, iterativo):
Task: "Estrai logica da BlogComponent in servizi separati.
UN servizio alla volta, in questo ordine:
1. BlogFilterService (filtraggio e ricerca articoli)
2. BlogSeriesService (navigazione serie)
3. BlogSEOService (meta tags per articoli)
Per ogni servizio:
a) Crea il file .service.ts con logica estratta
b) Crea il file .service.spec.ts con test unitari
c) Aggiorna BlogComponent per usare il servizio
d) Verifica: npm test passa, npm run build passa
e) Commit: git commit -am 'refactor: extract [ServiceName]'"
Review dopo ogni servizio: E2E test devono restare verdi
FASE 4 - Component Split (agente, ~120 min, iterativo):
Task: "Dividi BlogComponent (attuale 480 righe) in:
- BlogListComponent (lista articoli)
- BlogCardComponent (singola card articolo)
- BlogFilterComponent (filtri e ricerca)
- BlogPaginationComponent (paginazione)
Un componente alla volta. Stesso pattern di FASE 3:
implementa, test, verifica build, commit atomico."
Review: Umano verifica UI visivamente + E2E test
FASE 5 - Coverage Check (agente, ~30 min):
Task: "Verifica che coverage sia >80% per tutti i nuovi file.
Per ogni file sotto soglia, aggiungi test mancanti.
Produci report in docs/analysis/coverage-report.md"
Review: Coverage report + npm test
FASE 6 - Final Review (umano):
- Legge PR diff completo
- Verifica docs/analysis/coverage-report.md
- Merge su master se tutto ok
RISULTATI TIPICI DI QUESTO WORKFLOW:
Coverage: 0% -> 82%
Dimensione componenti: 480 righe -> media 95 righe
Build time: -15% (componenti più piccoli, lazy loading più efficace)
Tempo umano: ~45 min (fase 0 + review + fase 6)
Tempo agente: ~5-6 ore
Costo API stimato: $3-8 (dipende da modello)사례 연구에서 얻은 교훈
실제 코드베이스에 대한 이러한 유형의 워크플로에서 세 가지 통찰력이 나타났습니다.
- 리팩토링 전 E2E 테스트는 협상할 수 없습니다. 네트워크가 없으면 기능적 안전성에 있어 리팩토링의 각 단계는 어둠 속으로의 도약입니다. 투자한 시간 2단계(E2E 테스트)에서는 감지되지 않은 회귀를 방지하는 데 10배의 성과를 거두었습니다.
-
원자적 커밋은 워크플로 메모리입니다. 각 서비스/구성 요소에 대해 하나의 커밋
리팩토링을 통해 롤백이 수술적으로 이루어집니다. 리팩토링으로 인해 문제가 발생하면 완료됩니다.
git revert이전 작업을 잃지 않고 단일 커밋을 수행합니다. - 인간의 시간은 전체 시간의 10~15%로 줄어듭니다. 잘 설계된 워크플로를 통해 개발자는 출력을 검토하고 체크포인트를 승인하는 데 대부분의 시간을 보냅니다. 코드를 작성하지 않습니다. 이것은 성숙한 분위기의 코딩입니다. 모든 것을 위임하지 말고 위임하세요. 주요 결정에 대한 감독을 전략적으로 유지합니다.
명심해야 할 사실
YC Winter 2025 스타트업의 21%는 91% 이상의 코드가 생성된 코드베이스를 보유하고 있습니다. AI에 의해. 그러나 이들 중 보다 성숙한 스타트업은 "원시" 분위기 코딩을 사용하지 않고 작업 흐름을 사용합니다. 인간 체크포인트, 자동화된 테스트 및 롤백 전략을 갖춘 구조화된 에이전트. "생성된 코드"와 "AI가 생성한 고품질 소프트웨어"의 차이점은 바로 워크플로우 구조.
에이전트 워크플로의 미래
2025~2026년 연구에서는 에이전트 워크플로의 세 가지 진화 방향을 지적합니다. 소프트웨어 개발 상황:
- 동적 작업 분해: TDAG(2025)와 같은 프레임워크는 정적(개발자가 정의함)에서 동적(에이전트가 구조를 결정함)으로 분해 문제에 따른 워크플로우). 첫 번째 결과는 유망하지만 더 많은 것이 필요합니다. 프로덕션 코드베이스에 대한 인간 감독.
- 영구 에이전트 메모리: 벡터 데이터베이스와 에이전트 프레임워크의 통합 (LangGraph + pgVector, CrewAI + Chroma)를 통해 에이전트는 프로젝트 전체의 패턴을 기억할 수 있습니다. 특정 코드베이스에 대한 "경험"이 축적됩니다.
- 표준 상담원 기술: Anthropic은 2025년에 에이전트 스킬을 도입했습니다. 에이전트가 동적으로 로드할 수 있는 명령문, 스크립트 및 리소스의 번들입니다. 아이디어 "Angular Expert", "Security Auditor" 또는 "Performance Optimizer"와 같은 기술은 팀과 조직 전체에서 재사용 가능한 양식.
결론
에이전트 워크플로는 마술이 아니라 아키텍처입니다. 에이전트 시스템의 차이점 작동하는 것과 실패하는 것은 거의 항상 분해의 품질에 달려 있습니다. 성공 기준의 명확성과 오류 복구 전략의 견고성.
네 가지 패턴(순차적, 병렬적, 계층적, 반복적)은 상호 배타적이지 않습니다. 독특함: 가장 효과적인 워크플로우는 이들을 결합합니다. 계층적 계획자는 작업을 위임할 수 있습니다. 병렬, 각각은 반복 루프를 사용하여 필요한 품질을 달성합니다. 구조는 항상 특정 문제를 해결합니다.
오늘 취할 수 있는 가장 중요한 실제 단계는 일반적으로 복잡한 작업을 수행하는 것입니다. 단일 AI 세션에서 문제를 해결하고 이를 테스트 가능한 3~5개의 하위 작업으로 분해해 보세요. 정의 시작하기 전에 각각의 성공 기준을 알아보세요. 각 후에 휴먼 체크포인트를 추가하세요. 중요한 단계. 그런 다음 측정하십시오. 구조화된 작업 흐름이 더 나은 결과를 생성합니까? 거의 확실합니다. 그리고 이것이 에이전트 시스템 아키텍트가 되기 위한 출발점입니다.
시리즈: Vibe Coding 및 Agentic 개발
관련 통찰력
- Claude 및 모델 컨텍스트 프로토콜(MCP) - MCP가 외부 도구를 사용하여 에이전트 기능을 확장하는 방법
- 웹 보안: API 및 취약점 - 에이전트 워크플로의 특정 보안 위험