03 - エージェントティック ワークフロー: AI の問題の分解
AI がアシスタントをやめて協力者になるまさにその瞬間があります。 尋ねるのをやめたら 「この関数を書いてください」 そしてあなたは彼女に尋ね始めます 「解決する この問題」。単一の指示から複雑なタスクへの精神的な飛躍が心臓です 神々 エージェントワークフロー。そして、ほとんどの開発者がここで 効果的なエージェント ワークフローを構築するには、大幅なパラダイム シフトが必要になるため、行き詰まります。 それは長いプロンプトに関するものではなく、アーキテクチャに関するものです。
2025 年には、アメリカの開発者の 92% が日常業務で AI ツールを使用している (Stack Overflow Developer Survey 2025) ですが、実際にこの機能を利用しているのはそのうちのほんの一部だけです。 エージェントシステムの可能性。問題はテクノロジーへのアクセスではなく、テクノロジーの欠如です 明確なアーキテクチャパターンの 複雑な問題を分解する タスクで AI エージェントが信頼性が高く、検証可能で、再現可能な方法で解決できること。
この記事では、エージェント ワークフローについて一緒に深く理解を深めていきます。 基本的なパターン (順次、並列、階層、反復) を実装に適用する クロード コードを使用して、コンテキスト管理、品質メトリクス、および 有望なワークフローを信頼性の低いシステムに変えるアンチパターン。全部 実際のケーススタディと実際に動作するコードを紹介します。
何を学ぶか
- 4 つの基本的な分解パターン: 順次、並列、階層、反復
- エージェント ワークフローのアーキテクチャ: プランナー、実行者、レビュー担当者、メモリ
- 実際のプロジェクトでエージェントをガイドするために CLAUDE.md を構造化する方法
- 計画、実行、レビューのループと自己修復ワークフロー
- 長時間のエージェント セッションにおけるツールの使用とコンテキスト管理
- エージェントワークフローの品質を評価するための指標
- 最も危険なアンチパターンとその回避方法
- ケーススタディ: エージェント ワークフローを使用した Angular コードベースのリファクタリング
エージェントワークフローとは
Un エージェントのワークフロー および 1 つ以上の構造化された一連の操作 AI エージェントは、複雑な目標を達成するためにアクションを計画、実行、検証します。あ 単一の LLM 呼び出しとは異なり、エージェント ワークフローにはステップ間にメモリがあり、 ツール (ファイル システム、ターミナル、Web、API) は、サブタスクを専門のエージェントに委任でき、 人間の介入なしにエラーに適応できます。
「素朴な」バイブコーディングとの主な違いは次のとおりです。 意図的な構造。 クロードに「このコードベースをリファクタリングしてください」と依頼すると、平凡な結果が得られます。ワークフローの構築 (1) コードベースを分析し、(2) リファクタリングするコンポーネントを優先順位に従って特定します。 (3) 回帰テストを使用して一度に 1 つのコンポーネントをリファクタリングします。(4) 最初に各ステップをテストします。 続行すると、プロフェッショナルな結果が得られます。違いと分解。
運用上の定義
エージェントワークフロー 信頼性のある いつ: 各ステップが独立して検証可能である、 1 つのステップが失敗しても、ワークフロー全体、つまり最終的な決定的な出力が損なわれることはありません。 人間のオペレーターはいつでもワークフローを検査して修正できます。 チェックポイント。この定義は、人類の枠組み「効果的なエージェントの構築」(2024) に由来しています。 そして、あらゆる実装を評価するための羅針盤であり続けます。
問題の分解: エージェント ワークフローの核心
TDAG の調査 (タスクの分解とエージェントの生成、2025 年) では、その品質が 分解の様子と、マルチエージェント システムの成功を予測する最も重要な要素: 間違った分解は、後続のステップを通じてエラーを指数関数的に伝播させます。 一方、正しく分解すると障害が分離され、回復が可能になります。
基本的な分解パターンは 4 つあり、それぞれがさまざまな種類の問題に適しています。
パターン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 / Reflexion)
エージェントはループで動作します。アクションを実行し、結果を観察し、現在の状態を反映します。 そして次のステップを決定します。そしてそのパターンは、 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エージェントワークフローのアーキテクチャ
選択したパターンに関係なく、成熟したエージェント ワークフローには 4 つのコンポーネントがあります 基本的なこと。これらを理解することは、運用環境で堅牢なシステムを構築するための前提条件です。
1. プランナー
プランナーは高レベルの目標を受け取り、それを構造化された計画、つまりシーケンスに変換します。 依存関係のあるサブタスク（または DAG）、エージェントへの割り当て、各ステップの成功基準 リソースの見積もり (トークンの予算、必要なツール)。優れたプランナーは計画を作成します 検証可能な: 各ステップには、明確に定義された期待される出力があります。
2. 執行者
Executor は、Planner から個々のタスクを取得し、利用可能なツール (ファイル システム、
bash、Web検索、API。それぞれの特殊なエグゼキュータ (バックエンド エージェント、テスト エージェント、ドキュメント エージェント) には、
の原則に従って、そのドメインに必要なツールのみにアクセスします。
最低限の特権。 Claude Code はシステムを通じてこれを実装します
権限とカスタムサブエージェント allowedTools 設定可能。
3. 査読者
レビューアーは、各実行者の出力が定義された成功基準を満たしていることを検証します。 プランナーさんから。それは単純な「大丈夫そう」ではありません。品質レビュー担当者が自動テストを実行します。 静的分析、回帰チェック。レビュー担当者は承認できます (ワークフローは進行します)。 変更を要求するか (実行者の再試行)、人間にエスカレーションします (チェックポイントが必須)。
4. 記憶
メモリは、ワークフロー ステップを通じてコンテキストを管理します。これには 2 つのレベルがあります。
- 短期的 (状況に応じて): 現在のコンテキスト ウィンドウの内容、 前のステップからの出力も含まれます。利用可能なトークンによって制限されます。
-
長期 (外部): ステータス ファイル (例:
claude-progress.txt）、 データベース、git 履歴。異なるセッション間で中断されたワークフローを再開できます。
パターン claude-progress.txt
Anthropic は、 claude-progress.txt プロジェクトルート内
セッション間の記憶のために。イニシエータ エージェントは、ワークフローの状態を次の間隔で書き込みます。
チェックポイント。次のエージェントはこのファイルを読み取って、作業の場所と内容を理解します。
しなければなりません。と組み合わせて git log、完全なコンテキストを提供します。
コンテキスト ウィンドウがいっぱいになります。
クロードコードによる実践的な実装
Claude Code は、エージェント ワークフローを構築するための 3 つの主要な手段を提供します。
クロード.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 年のエージェントティック コーディング) Trends Report) は、オーケストレーションと Sonnet に Opus を使用する最も効果的なパターンを示しています。 品質を維持しながらコストを 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マルチエージェントコードレビューパイプライン
マルチエージェント コード レビュー パイプラインとワークフローの最も成熟したユースケースの 1 つ 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 トークンのコンテキスト ウィンドウで動作しますが、すべてを 1 つのトークンで消費します セッションとアンチパターン。人類の研究は、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 バッチ処理: 多数の個別の呼び出しを行う代わりに、複数の操作を同じツール呼び出しに集約します。
アンチパターン: ツール呼び出しの嵐
よくある間違いは、明示的なループを使用してファイルを一度に 1 つずつ読み取るようにエージェントに要求することです。
これにより、何百ものツール呼び出しが生成され、コンテキストがすぐに飽和状態になります。代わりにパターンを使用してください
どうやって Glob + Grep 関連するファイルを特定し、それらのファイルのみを読み取ります。
クロード コードは、複数のツール呼び出しが独立している場合に並行して実行できます。
この機能により、連続呼び出しと比較して遅延が 40 ～ 60% 削減されます。
エージェントワークフローのメトリクスと評価
「うまくいく」ということは指標ではありません。エージェントのワークフローを評価して改善するには、メトリクスが必要です 信頼性、出力品質、効率、安全性の 4 つの側面で定量的です。
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 を超えるエージェントが存在します。 同時にアクティブになると、エラー率が指数関数的に高くなる傾向があります (いわゆる「17x エラー トラップ」。Towards Data Science、2025 年に文書化されています)。
過剰分解: 例
間違っている： 15 のサブエージェントを作成して 15 の関数を 1 つの関数にリファクタリングする
200行のファイル。調整のオーバーヘッド (各エージェントのコンテキスト設定、エージェントのマージ)
結果、競合管理など）は、1 人のエージェントが要する時間を超えています。
正しい： 1 人のエージェントがファイルを読み取り、15 の関数を識別し、
中間テストで順次リファクタリングします。実際にはファイル/モジュールのみのサブエージェント
独立していてかなりのサイズです。
2. 過小仕様
曖昧に説明されたタスクは、予測できない出力を生成します。 「コードを改善する」ことはタスクではありません。 そして希望。各タスクは、何を行うか、どのファイルに対して、どの制約を尊重するかを指定する必要があります。 成功を確認する方法。ワークフローの最大の原因は仕様不足であると思われる 機能しますが、低品質の出力が生成されます。
3. コンテキスト汚染
無関係なコンテキストをコンテキスト ウィンドウにロードしすぎている (不要なファイル、会話) 先例、冗長な文書など）は回答の質を低下させます。 「迷子」現象 2024 年の LLM に関する調査で文書化された「中間」は、LLM のパフォーマンスが低いことを示しています コンテキスト ウィンドウの中央にある情報に注目してください。文脈を明確にして焦点を絞った状態に保つ そして構造化されています。
4.ロールバック戦略が欠落している
2025年のReplitインシデント – エージェントが本番データベースを削除した – そして ロールバック戦略を持たないワークフローの最もよく引用される例です。あらゆる破壊的な操作 (削除、 上書き、DROP) には、元に戻すメカニズム (git stash、バックアップ、可逆トランザクション) が必要です。 「エージェントは自分が何をしているのか知っていた」というのは災害復旧戦略ではありません。
5. 介入者なし
人間のチェックポイントを必要としない完全に自動化されたワークフローは、タスクにのみ適しています リスクは低く、よく理解されています。人間研究 (2026 年のエージェント コーディング トレンド レポート) 開発者がタスクの 20% のみを完全に委任 (0% 監督) していることを示しています。 残りの 80% には、少なくとも 1 つのレビュー チェックポイントが必要です。 Human-in- を使用してワークフローを設計する アーキテクチャ上の決定、展開、データ変更のための明示的なループ。
6. セッション間メモリレスエージェント
新しいクロード コード セッションはそれぞれ最初から始まります。複雑なワークフロー (5 時間以上の作業)
外部状態は書き込まれず、進行状況が失われることになります。常に使用する claude-progress.txt、
計画ファイル docs/ 永続化メカニズムとしての頻繁なコミット。
ケーススタディ: エージェントティック ワークフローを使用した 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)ケーススタディから学んだ教訓
実際のコードベースでのこのタイプのワークフローから、次の 3 つの洞察が得られました。
- リファクタリング前の E2E テストは交渉の余地がありません。 のネットワークがなければ、 機能安全性を考慮すると、リファクタリングの各ステップは暗闇への飛躍です。投資した時間 フェーズ 2 (E2E テスト) では、検出されない回帰を回避する上で 10 倍の効果があります。
-
アトミック コミットはワークフロー メモリです。 サービス/コンポーネントごとに 1 つのコミット
リファクタリングによりロールバックが外科的に行われます: リファクタリングによって問題が発生した場合、それは完了します
git revert以前の作業を失うことなく、その単一のコミットを実行できます。 - 人間の時間は全体の 10 ～ 15% に減少します。 適切に設計されたワークフローにより、 開発者は出力のレビューとチェックポイントの承認にほとんどの時間を費やします。 コードを書いていない。これは成熟した雰囲気のコーディングです。すべてを委任するのではなく、委任します。 重要な決定に対する戦略的な監視を維持します。
留意すべき事実
YC Winter 2025 スタートアップ企業の 21% が、91% 以上のコードが生成されたコードベースを持っています AIによる。しかし、これらのより成熟したスタートアップは、「生の」バイブコーディングを使用せず、ワークフローを使用します。 人間によるチェックポイント、自動テスト、ロールバック戦略を備えた構造化されたエージェント。 「生成されたコード」と「AIが生成した高品質ソフトウェア」の違いはまさに ワークフロー構造。
エージェント ワークフローの将来
2025 年から 2026 年の調査では、エージェント ワークフローの進化の 3 つの方向性が指摘されています。 ソフトウェア開発コンテキスト:
- 動的タスク分解: TDAG (2025) のようなフレームワークは、 静的 (開発者によって定義される) から動的 (エージェントが構造を決定する) への分解 問題に基づいてワークフローを決定します)。最初の結果は有望ですが、さらに多くの結果が必要です 実稼働コードベースを人間が監督します。
- 永続的なエージェント メモリ: ベクトルデータベースとエージェントフレームワークの統合 (LangGraph + pgvector、CrewAI + Chroma) により、エージェントはプロジェクト全体のパターンを記憶できます 異なる、特定のコードベースでの「経験」を蓄積します。
- 標準としてのエージェント スキル: Anthropic は 2025 年にエージェント スキルを導入しました。 エージェントが動的にロードできるステートメント、スクリプト、リソースのバンドル。アイデア そして、「Angular Expert」、「Security Auditor」、「Performance Optimizer」などのスキルが チームや組織全体で再利用可能なフォーム。
結論
エージェント ワークフローは魔法ではなく、アーキテクチャです。エージェントシステムとの違い うまくいくものと失敗するものは、ほとんどの場合、分解の質にあります。 成功基準の明確さとエラー回復戦略の堅実さ。
4 つのパターン (順次、並列、階層、反復) は相互に排他的ではありません。 ユニーク: 最も効果的なワークフローはこれらを組み合わせたものです。階層型プランナーはタスクを委任できます それぞれが反復ループを使用して必要な品質を達成します。 構造は常に特定の問題に役立ちます。
今日実行できる最も重要な実践的なステップは、通常は複雑なタスクに取り組むことです。 単一の AI セッションで解決し、それを 3 ～ 5 つのテスト可能なサブタスクに分解してみます。定義する 始める前に、それぞれの成功基準を確認してください。それぞれの後に人間によるチェックポイントを追加します 重要な段階。次に、構造化されたワークフローがより良い成果を生み出すかどうかを測定します。ほぼ確実にそうです。 これがエージェント システム アーキテクトになるための出発点です。
シリーズ: Vibe コーディングとエージェント開発
関連する洞察
- クロードとモデル コンテキスト プロトコル (MCP) - MCP が外部ツールを使用してエージェント機能を拡張する方法
- Web セキュリティ: API と脆弱性 - エージェントワークフローにおける特定のセキュリティリスク