AIエージェントにも「振り返り」が必要だった話
はじめに
最近、Claude Codeにて、Agent Teamsという機能が追加されました。
現在私が構築しているメンバーは以下の6人です。（人ではない）
| 名前 | 役割 |
|---|---|
| project-manager | タスク管理・整合性チェック・QCレビュー |
| tech-leader | DB設計・パフォーマンス設計 |
| designer | UI/UX設計・Figmaスペック作成 |
| researcher | 技術調査・競合分析 |
| analyzer | パフォーマンス分析・定量評価 |
| quality-control-manager | 成果物レビュー・品質評価・ドキュメント最適化 |
ここで起きた問題が、、、
project-manager がコンテキストウィンドウを使い果たし応答不能になった。
正直起きた問題自体は初歩的なコンテキスト管理のルールをチーム起動時に指定していなかっただけです。
KPTA で振り返りを実施
振り返りの内容は補足として最後の方に記載します。
Problem（発見した問題）
- 全量読み込みが習慣化しており、適切なコンテキスト管理ができていない
- 別タスクに移行しても前タスクの情報がコンテキストに残ったまま作業再開
Try → Action（策定した改善ルール）
振り返りから4つの改善ルールを策定し、チーム設定ファイル（team-config.md）に反映しました。
ルール1: コンテキスト最適化（ファイル管理）
- レビューを依頼する側が参照ファイルを明示し、レビュアーのコンテキストを最適化する
→ 推論によって勝手にコンテキストが膨れるのを防ぐ - レビュー依頼ごとにコンテキストウィンドウを初期化する
ルール2: タスク切り替え時のコンテキストリセット
手順: 要約メモ書き出し → /compact or /clear → 新タスク着手
切り替え前に現在のコンテキストを要約メモとしてファイルに保存してから初期化します。
保管先: docs/context-memos/{role}-{task-id}-summary.md
ルール3: 大規模ファイルの取り扱い
Grep-first 原則を導入しました。
❌ 以前: ファイルを全量 Read → 目的の箇所を探す → Edit
✅ 改善: Grep で対象行を特定 → 必要セクションのみ Read → Edit
1,000行超のファイルは、まず細分化できないか検討します。
細分化が不適切な場合のみ offset/limit による部分読み込みを使います。
ルール4: サブエージェントの活用
- コア作業コンテキストと補足コンテキストを分離する
Keep（よかったこと）
問題点だけでなく、継続すべき良い実践も22件記録しました。一部を紹介します。
プロセス面
| 内容 | 効果 |
|---|---|
| レビュー準備書の事前作成 | チェックリスト・仮説リストで漏れのないレビューを実現 |
| ピンポイント編集 | コンテキスト消費を抑えつつ正確な修正 |
| 並列ツール呼び出し | 並列実行による高速化 |
コミュニケーション面
| 内容 | 効果 |
|---|---|
指摘への一意 ID 付与（例: US-ISSUE-1） |
チーム内で統一されたレビュー言語の形成 |
| 修正しなかった箇所と理由の明示 | 「修正漏れ」誤認を防止 |
| 重複作業の即時検出・報告 | 無駄なコンテキスト消費と競合を防止 |
振り返り後のチーム状態
PMが応答不能になった時よりファイルサイズの大きい設計資料の作成およびレビューを行っていますが、応答不能にはなっていません。
ここで重要なのは、コンテキストを最適化できたこと自体ではありません。
AIエージェントに反省点を考えさえることで、ブラックボックスになっているボトルネックを洗い出すことができた
ということです。
おわりに
AIエージェントチームを動かしてみて気づいたのは、チームとして機能させるには、人間チームの運営ノウハウがほぼそのまま必要ということです。
- 振り返りをしないとチームは改善しない
- コミュニケーションの設計が品質を左右する
- 一人の問題がチーム全体に波及する
AIエージェントの「コンテキスト」は、人間の「認知負荷」に相当します。
チームとして持続可能な作業を続けるには、各メンバーのコンテキストを意識した設計が必要です。
今回の振り返りで策定したルールが実際に有効かどうかは、次回セッションの検証待ちです。
また結果を記事にしたいと思います。
Discussion