プロジェクトでAIコードエージェントを適切に運用するためのSkills - agent-workbench

はじめに

AIコードエージェントを使っていて、こういうことはありませんか。

• 最初は順調に作業していたのに、途中で別の問題を見つけて、元の作業がどこまで進んでいたのかわからなくなる。
• 設計方針を何度も説明したはずなのに、別セッションで再開すると古い前提に戻っている。
• テストは実行されたように見えるが、そのプロジェクトで本当に必要な検証コマンドではない。
• レビューで指摘された内容が修正されたのか、未対応なのか、却下されたのかがチャットの中に埋もれていく。
• 前に注意したことを、次のセッションでまた繰り返される。
• 「完了しました」と言われたが、どの要件を満たしていて、どのコマンドで検証され、どのファイルが変更され、どのレビュー指摘が閉じられたのかが追えない。

こういう問題は、コードエージェントを大きなプロジェクトで使い始めると出てきます。 大きく複雑なプロジェクトでは、作業状態そのものが複雑になります。 設計、要件、タスク、レビュー、検証、コマンド、Gitの状態、ユーザーからの修正指示、途中で発生した割り込み作業などが絡み合います。

人間同士の開発でも、こうした情報はIssue、Pull Request、設計文書、CI、レビューコメント、コミット履歴などに分散して管理されています。

コードエージェントに大きな作業を任せる場合も、本来は同じように作業状態を管理する場所が必要です。

では、作業状態をMarkdownで管理すればよいのではないか、という考えもあります。

実際、TASKS.md や AGENT.md、WORKLOG.md のようなファイルを作って、そこに作業状態を書いている人もいると思います。

これは小さく始めるには便利です。 人間も読みやすいですし、Gitで差分も追えます。

ただ、大きなプロジェクトでコードエージェントに継続的に作業させると、Markdownだけではつらくなってきます。 ファイルが巨大化すると、エージェントが全体を毎回正しく把握できなくなります。

• どの記述が最新なのか。
• どのタスクが完了しているのか。
• どのレビュー指摘が未解決なのか。
• どの設計判断が現在も有効なのか。
• どの検証コマンドが実際に実行されたのか。
• どの注意事項がすでにルール化されたのか。

これらが1つの長いMarkdownに混ざっていくと、状態管理というより、巨大なメモになります。 最悪の場合、エージェントが grep でそれっぽい文字列を拾い、古い状態と新しい状態を混ぜて解釈します。

時系列も崩れます。

• 「この指摘は後で解決されたのか」
• 「この設計判断は取り消されたのか」
• 「このテスト結果はどのコミットに対するものなのか」
• 「このメモは中断前の状態なのか、再開後の状態なのか」
• 「この注意は一度きりのコメントなのか、今後も守るべきルールなのか」

こういうことが曖昧になります。

大きく複雑なプロジェクトでコードエージェントを使うなら、作業状態を構造化して、時系列で追えて、必要な観点ごとに取り出せる台帳が必要になります。

そこで、コードエージェントの作業状態をプロジェクト側に構造化して残すためのツールとして、agent-workbench を作りました。

リポジトリはこちらです。 https://github.com/MuNeNiCK/agent-workbench

Docsはこちらです。 https://munenick.github.io/agent-workbench/

agent-workbenchとは

agent-workbench は、コードエージェント向けの作業台帳です。 大きくて複雑なプロジェクトで、コードエージェントが長い作業を進めるための運用レイヤーとして作っています。

人間向けのタスク管理ツールではありません。 TrelloやGitHub Issuesの代わりに使うものでもありません。

目的は、コードエージェントがプロジェクト内で作業するときに、現在の作業状態、設計、レビュー、検証、証拠、ユーザーからの修正指示を構造化して参照できるようにすることです。

プロジェクトには以下のようなディレクトリが作成されます。

.agent-workbench/
  ledger.sqlite
  designs/
  exports/
  logs/

中心になるのは .agent-workbench/ledger.sqlite です。

これはプロジェクトローカルなSQLite台帳です。

ここに、作業単位、設計パッケージ、タスク、チェックリスト、レビュー、指摘、検証結果、コマンド実行、Gitコミット、変更ファイル、ユーザーからの修正指示、KPTなどを記録します。

つまり、エージェントが「今の会話」や「巨大なMarkdown」だけではなく、「プロジェクトに残った構造化された作業状態」を見て動けるようにするためのものです。

なぜ必要なのか

大きな作業はチャットだけでは管理できない

コードエージェントに任せたい作業は、単なるファイル編集だけではありません。

たとえば、以下のような作業があります。

- 既存設計を読み解く
- 仕様や制約を整理する
- 実装方針を決める
- タスクへ分解する
- 実装する
- テストや検証を実行する
- レビュー指摘を受ける
- 修正する
- 再検証する
- 完了してよいか判断する

このような作業では、途中の判断が後続の作業に影響します。

• どの設計判断が有効なのか。
• どの要件がどのタスクに対応しているのか。
• どのテストを実行すべきなのか。
• どのレビュー指摘がまだ残っているのか。
• どの変更が今回の作業に含まれるべきなのか。

これらをチャット履歴だけで管理すると、作業が長くなるほど不安定になります。

エージェントが文脈を読み落とすこともあります。 人間側も、どこに何を書いたのかを追うのがつらくなります。

agent-workbench では、この状態をチャットではなくプロジェクト側に残します。

Markdown管理は巨大化すると破綻しやすい

作業状態をMarkdownで管理する方法は皆さんもよくやられていると思います。

- TODOをMarkdownに書く
- 作業ログをMarkdownに残す
- 設計判断をMarkdownに追記する
- レビュー指摘をMarkdownに貼る
- 検証結果をMarkdownに書く

人間が読むだけなら、それでも十分なことがあります。 ただ、コードエージェントに継続的に使わせる状態管理としては限界があります。

まず、ファイルが大きくなります。

大きくなったMarkdownをエージェントが毎回正しく読むとは限りません。 コンテキストに入りきらない場合もあります。 必要な部分だけを拾おうとして、古い情報を拾うこともあります。

次に、時系列が壊れやすいです。

Markdownは基本的に文書です。 追記、編集、移動、削除を繰り返すと、「いつの状態なのか」「どの変更によって状態が変わったのか」が曖昧になります。

また、状態の種類が混ざります。

タスク一覧、設計判断、検証ログ、レビュー指摘、ユーザー修正、作業メモが1つのファイルに混ざると、エージェントはそれを状態として扱うのではなく、文章として検索します。

最悪の場合、grep でそれっぽい行を拾い、時系列も状態遷移も無視して判断します。

これは、大きなプロジェクトでは危険です。

agent-workbench では、、作業状態のsource of truthをSQLite台帳に置きます。

作業単位、レビュー指摘、検証結果、コマンド実行、完了判定、ユーザー修正、KPTなどは、構造化されたレコードとして扱います。

エージェントが作業を勝手に切り替える

大きなプロジェクトでは、作業中に別の問題が見つかることがよくあります。

• ドキュメントを更新していたら、CLIの挙動がおかしいことに気づく。
• 実装していたら、既存テストの前提が壊れていることに気づく。
• レビュー中に、別モジュールの設計漏れが見つかる。

こうした割り込み自体は悪いことではありません。

問題は、元の作業がどこで止まったのか、なぜ止まったのか、戻る前に何を確認すべきなのかが曖昧になることです。

コードエージェントは、目の前の問題に進んでいくことがあります。 その間にコンテキスト圧縮などが入ると、元の問題を忘れてしまうことが多くあります。 その結果、元の作業が置き去りになります。

agent-workbench では、作業単位をwork unitとして扱います。

work unitには、active、suspended、blocked、closed、reopened、follow-upなどの状態があります。

また、activation stackによって、現在の作業、割り込み、復帰を記録します。

たとえば以下のような流れです。

docs workがactive
  ↓
release wrapperの問題が見つかる
  ↓
docs workをsuspend
  ↓
wrapper workをactive
  ↓
wrapper workをclose
  ↓
resume-readyを確認してdocs workへ戻る

単に「あとで戻る」とチャットやMarkdownに書くのではなく、作業状態として中断と復帰を管理します。

設計と実装がずれる

大きなプロジェクトでは、設計と実装の対応関係が重要です。

コードエージェントに設計文書を渡して実装させることはできます。 ただ、自由形式の設計メモだけでは、どれが要件で、どれが制約で、どれが決定済みの設計判断なのかが曖昧になります。

その結果、エージェントは「それっぽい実装」をします。 しかし、その実装がどの要件を満たしているのか、どの設計判断に従っているのか、どの検証で確認されたのかが追えないと、大きなプロジェクトでは危険です。

agent-workbench では、Design Packageという形で設計材料を構造化します。

Design Packageには、人間が読むための設計説明だけでなく、requirements、decisions、validation gate templatesなどの機械可読な情報を含めます。

要件には REQ-001 のような安定したキーを持たせます。 設計判断には DEC-001 のようなキーを持たせます。 検証条件はvalidation gateとして定義します。

これにより、設計、タスク、チェックリスト、実装証拠、検証結果、レビュー結果をつなげられるようにしています。

検証コマンドを推測される

大きなプロジェクトでは、正しい検証コマンドが単純ではないことが多いです。

cargo test だけでは足ず、feature flagが必要。 特定のworkspace memberだけを対象にする必要がある。

npm test ではなく pnpm test を使う必要がある。 通常のテストよりもDocs生成やrelease wrapperの検証が重要な場合もある。

コードエージェントは、よくあるコマンドを推測して実行しがちです。 そして、間違ったコマンドを実行したのに「テストしました」と報告することがあります。

これは大きなプロジェクトではかなり危険です。

agent-workbench では、command profileを記録できます。

固定の検証コマンド、推奨コマンド、非推奨コマンド、実行結果、逸脱理由などを台帳に残せます。 エージェントは作業前にcommand profileを確認し、プロジェクトで使うべき検証コマンドを選びます。

検証結果はcommand usageやvalidation gate runとして記録します。

これにより、「どのコマンドを実行したのか」「その結果はどうだったのか」「どの要件の検証証拠なのか」を追えるようになります。

レビュー指摘が流れていく

大きな作業では、レビューも1回では終わりません。

• 設計レビュー
• タスク分解レビュー
• 実装レビュー
• 設計と実装の差分レビュー
• 既知の指摘が修正されたかの確認

これらを全部チャットやMarkdownで扱うと、どの指摘がまだ残っているのかがわかりづらくなります。

• 指摘が修正されたのか。
• 修正されたが検証はまだなのか。
• 却下されたのか。
• 別の指摘に派生したのか。

agent-workbench では、review plan、review run、finding、closure、verificationを分けて扱います。

レビューで出た指摘をfindingとして記録し、修正したらclosureを記録し、必要に応じてverificationを残します。

レビューを「コメント」ではなく、作業状態として扱うための仕組みです。

同じ指摘を繰り返してしまう

コードエージェントを使っていると、同じような注意を何度もすることがあります。

• このプロジェクトではこのテストコマンドを使う。
• このディレクトリは直接編集しない。
• このレビュー観点を必ず確認する。
• この形式でログを残す。
• この実装方針は採用しない。

こうした指摘がチャットの中だけに残っていると、次のセッションでまた同じことを繰り返す可能性があります。

レビュー指摘も同じです。 一度修正したはずの問題が、別のタスクでまた発生することがあります。

agent-workbench では、ユーザー修正やKPTを記録できます。

その場限りのコメントとして流すのではなく、次の作業で参照できる形にします。

たとえば、Keep、Problem、Tryとして整理することで、何を継続し、何が問題で、次に何を試すべきかを残せます。 また、繰り返し発生する指摘は、単なるレビューコメントではなく、ルールやcommand profile、チェックリストへ昇格できます。

これにより、エージェントが同じ失敗を繰り返しにくくなります。

「前にも言ったこと」をチャット履歴から探すのではなく、プロジェクトの台帳に残して、作業前に確認させるのが目的です。

完了報告に証拠がない

コードエージェントは、作業が終わったように見えると「完了しました」と言いがちです。 しかし、大きなプロジェクトでは、自然言語の完了報告だけでは足りません。

- タスクは閉じられているか
- レビュー指摘は残っていないか
- 検証コマンドは実行されているか
- 実行結果は記録されているか
- 変更ファイルは意図した範囲か
- Gitコミットは作られているか
- 設計要件との対応は取れているか
- 作業ディレクトリのdirty stateは分類されているか
- ユーザー修正やKPTに反映すべき学びは記録されているか

これらが確認できない状態で「完了」と言われても、人間側が結局全部確認することになります。

agent-workbench では、close-ready gateを用意しています。

close-readyは、作業を閉じてよいかを確認するためのreadiness gateです。

タスク、チェックリスト、レビュー、指摘、検証コマンド、repository state、work recordなどを確認し、不足があればブロックします。

つまり、エージェントが「完了しました」と言う前に、完了条件を構造的に確認させるための仕組みです。

agent-workbenchで解決すること

agent-workbench が解決したいことは、コードエージェントの作業を「その場のチャット」や「巨大なMarkdown」から「プロジェクトの作業状態」へ移すことです。

• エージェントが作業を始める前に、現在の状態を確認する。
• 作業中に、設計判断や検証結果を記録する。
• 割り込みが発生したら、中断理由と復帰条件を残す。
• レビュー指摘が出たら、指摘、修正、検証を追跡する。
• ユーザー修正やKPTを残し、同じ指摘を繰り返さないようにする。
• 完了前に、証拠が揃っているか確認する。

これを自然言語のメモだけでやるのではなく、CLIとSQLite台帳で構造化します。 大まかには、以下を扱います。

- 作業単位
- 中断と復帰
- 設計パッケージ
- 要件
- 設計判断
- タスク
- チェックリスト
- 検証ゲート
- コマンドプロファイル
- コマンド実行履歴
- レビュー計画
- レビュー結果
- 指摘と修正確認
- Gitコミット
- 変更ファイル
- repository state
- ユーザー修正指示
- KPT
- 作業記録

これにより、エージェントが「次に何をすべきか」を、チャットの雰囲気やgrep結果ではなく、台帳から判断できるようにします。

使い方

agent-workbench は、基本的には人間がCLIを直接叩くのではなく、コードエージェントに使わせる想定です。 人間は、エージェントに対して「何をしてほしいか」と「agent-workbenchを使って状態管理してほしいこと」を指示します。

ここでは、プロジェクト初期状態から使う場合と、既存プロジェクトに導入する場合で分けます。

インストール

agent-workbench はAgent Skillとしてインストールします。

ユーザー単位でインストールする場合は以下です。

gh skill install MuNeNiCK/agent-workbench agent-workbench \
  --scope user \
  --agent <target-agent>

プロジェクト単位でインストールする場合は以下です。

gh skill install MuNeNiCK/agent-workbench agent-workbench \
  --scope project \
  --agent <target-agent>

<target-agent> には、利用しているコードエージェントに対応する値を指定します。

プロジェクト初期状態から使う場合

新規プロジェクトや、まだ設計が固まっていない段階から使う場合は、いきなり実装させません。

流れとしては以下です。

1. agent-workbenchを初期化する
2. 設計メモまたは設計書を作成する
3. 設計メモをDesign Packageとして取り込む
4. 設計レビューを行う
5. 設計をcloseする
6. タスクとチェックリストへ分解する
7. タスク分解レビューを行う
8. implementation-readyを確認する
9. 実装する
10. 検証・レビュー・close-readyを通して完了する

最初に、エージェントへ以下のように指示します。

このプロジェクトで $agent-workbench を使えるように初期化してください。
初期化後、現在の状態、次に必要な作業、利用できるワークフローを報告してください。

次に設計をAgentに渡します。 すでに設計を書いている場合は、それを渡します。

以下の設計メモをもとに、このプロジェクトの設計を整理してください。

まだ実装には入らないでください。
要件、制約、設計判断、検証方針、不明点を分けて整理してください。

<ここに設計メモを貼る>

または、設計をエージェントと相談しながら作る場合は、以下のように依頼します。

$agent-workbench を使って、このプロジェクトの設計を一緒に整理してください。

まず、目的、要件、制約、設計判断、検証方法を洗い出してください。
不明点があれば、勝手に決めずに確認してください。
まだ実装には入らないでください。

設計メモまたは設計書ができたら、agent-workbench に取り込ませます。

ここまで整理した設計を、$agent-workbench が理解できるDesign Packageとして取り込んでください。

要件、設計判断、検証ゲートを構造化してください。
取り込み後、Design Packageとして不足している情報、曖昧な点、確認が必要な点を報告してください。

取り込み後、設計レビューを行わせます。

$agent-workbench を使って設計レビューを実行してください。

要件漏れ、設計判断の矛盾、検証方針の不足、実装前に解決すべきブロッカーがないか確認してください。
レビュー結果は台帳に記録してください。

設計レビューで問題がなければ、設計をcloseさせます。

設計レビューの結果を確認し、設計をcloseできるか判断してください。

closeできない場合は、未解決の指摘と次に必要な修正を報告してください。
closeできる場合は、$agent-workbench 上で設計をcloseしてください。

設計がcloseしたら、タスク分解へ進めます。

close済みの設計をもとに、$agent-workbench で実装タスクとチェックリストへ分解してください。

各タスクがどの要件に対応しているか、どの検証ゲートで確認するかも紐づけてください。
まだ実装には入らないでください。

タスク分解レビューを行わせます。

$agent-workbench を使って、タスク分解レビューを実行してください。

設計要件がタスクとチェックリストに漏れなく落ちているか、
検証ゲートとの対応が取れているか、
実装前に不足している作業がないか確認してください。

実装に進めるか確認します。

$agent-workbench の implementation-ready を確認してください。

実装に進めない場合は、ブロッカーと必要な対応を報告してください。
実装に進める場合は、実装対象のタスク、検証方法、注意すべき設計判断をまとめてから実装を開始してください。

実装中は、検証コマンドや変更内容を記録させます。

$agent-workbench の現在のタスクに従って実装してください。

実行したコマンド、検証結果、変更したファイル、設計要件との対応を台帳に記録してください。
テストコマンドは推測せず、登録済みのcommand profileを確認してから実行してください。

実装中に注意したことや、同じ指摘を繰り返してほしくない内容が出た場合は、ユーザー修正やKPTとして記録させます。

今の指摘を $agent-workbench にユーザー修正として記録してください。

今後同じ指摘を繰り返さないように、適用範囲、避けるべき行動、次回確認すべき内容を整理してください。
必要であればKPTにも反映してください。

完了前にはclose-readyを確認させます。

実装が完了したと思う場合でも、まだ作業をcloseしないでください。

$agent-workbench の close-ready を確認し、
未完了タスク、未解決レビュー指摘、検証不足、変更ファイル、Git状態、ブロッカー、記録すべきユーザー修正やKPTが残っていないかを報告してください。
close-readyが通る場合のみ、作業をcloseしてください。

既存プロジェクトに導入する場合

既存プロジェクトに導入する場合は、まず現在の状態を棚卸しします。

すでにコード、設計メモ、Issue、README、テスト、CIなどが存在するため、いきなり新しい設計を作るのではなく、現在のプロジェクト状態を台帳に取り込むところから始めます。

流れとしては以下です。

1. agent-workbenchを初期化する
2. 既存の設計・README・Issue・テスト・CIを調査する
3. 現在の状態をDesign Packageまたはwork unitとして整理する
4. 既存の検証コマンドをcommand profileへ登録する
5. 既存の注意事項や繰り返したくない指摘をユーザー修正やKPTとして登録する
6. 未完了作業や既知の問題をwork unitとして登録する
7. 必要に応じて設計レビューやimplementation-readyを確認する
8. 実装・修正・レビュー・close-readyへ進む

最初に、エージェントへ以下のように指示します。

この既存プロジェクトに $agent-workbench を導入してください。

まず台帳を初期化し、現在のリポジトリ状態、既存ドキュメント、テスト方法、CI、未完了作業の有無を調査してください。
まだ実装や修正には入らないでください。

既存状態を調査させます。

$agent-workbench を使って、このプロジェクトの現在状態を棚卸ししてください。

README、docs、Issue相当のメモ、テストコマンド、CI設定、既存の設計判断、未完了に見える作業を確認し、
台帳に登録すべき項目を整理してください。

検証コマンドを登録させます。

このプロジェクトで使うべき検証コマンドを調査し、$agent-workbench のcommand profileに登録してください。

推奨コマンド、避けるべきコマンド、用途ごとの検証コマンドを分けてください。
推測で登録せず、README、CI設定、package設定、既存スクリプトを確認してください。

既存の注意事項や繰り返したくない指摘を登録させます。

このプロジェクトで今後繰り返したくない指摘や、守るべき注意事項を整理し、
$agent-workbench にユーザー修正またはKPTとして登録してください。

対象範囲、避けるべき行動、今後確認すべき内容を分けてください。

既存設計をDesign Package化させます。

既存の設計情報を整理し、必要であれば $agent-workbench のDesign Packageとして取り込んでください。

要件、制約、設計判断、検証ゲートを分けて整理してください。
不明点や設計が曖昧な部分は、勝手に補完せず確認事項として報告してください。

既存の未完了作業をwork unitにします。

現在のプロジェクトで未完了または継続中に見える作業を洗い出し、
$agent-workbench のwork unitとして登録してください。

各work unitについて、目的、現在の状態、ブロッカー、次に必要な作業を記録してください。

既存プロジェクトで作業を再開する場合は、最初に状態を報告させます。

$agent-workbench を使って、現在の状態を確認してください。

activeなwork unit、suspendedなwork unit、未解決レビュー指摘、登録済みcommand profile、
ユーザー修正、KPT、現在のGit状態、次に取るべき作業を報告してください。
その後、実装計画を立ててください。

実装へ進む前には、implementation-readyを確認させます。

この作業を実装に進めてよいか、$agent-workbench の implementation-ready を確認してください。

不足している設計、未解決の指摘、検証コマンドの未登録、リポジトリ状態の問題があれば報告してください。
問題がなければ、対象タスクと検証方法を明示してから実装に進んでください。

完了前には、必ずclose-readyを通します。

作業を完了扱いにする前に、$agent-workbench の close-ready を確認してください。

未完了タスク、未解決レビュー指摘、検証不足、変更ファイル、Git状態、ブロッカー、
記録すべきユーザー修正やKPTが残っていないかを報告してください。
close-readyが通らない場合は、作業をcloseせず、次に必要な対応を提示してください。

主な概念

Ledger

ledgerはプロジェクトローカルなSQLite台帳です。

.agent-workbench/ledger.sqlite

ここに、作業状態、設計、レビュー、検証、証拠などを記録します。

Markdownやチャットではなく、構造化された台帳をsource of truthにするのがポイントです。

Work unit

work unitは、エージェントが行う作業単位です。

たとえば以下のようなものです。

- release workflowを実装する
- public docsを再構成する
- 設計パッケージを作成する
- レビュー指摘を修正する

work unitは、active、suspended、blocked、closed、reopened、follow-upなどの状態を持ちます。

これにより、作業が今どういう状態なのかを追跡できます。

Activation stack

activation stackは、中断と復帰を扱うための仕組みです。

たとえば、以下のような流れを記録します。

docs workがactive
  ↓
release wrapper issueが見つかる
  ↓
docs workをsuspend
  ↓
wrapper workをactive
  ↓
wrapper workをclose
  ↓
resume-readyを確認してdocs workへ戻る

resume-ready gateを通して、設計状態、レビュー状態、repository state、前提条件が変わっていないかを確認します。

Design Package

Design Packageは、設計材料を agent-workbench が扱いやすい形に構造化したものです。

最初から専用形式で書く必要はありません。

元になるものは、普通の設計メモでも、Markdownの設計書でも、txtでも、会話しながら整理した内容でも構いません。

重要なのは、その設計材料をそのまま巨大なメモとして扱うのではなく、agent-workbench が追跡できる形へ取り込むことです。

Design Packageとして取り込むと、設計の中に含まれる情報を以下のように分けて扱えます。

- 要件
- 制約
- 設計判断
- 検証方針
- 検証ゲート
- 未解決の確認事項

要件は REQ-001 のようなキーを持ちます。 設計判断は DEC-001 のようなキーを持ちます。

これにより、実装タスク、チェックリスト、検証ゲート、レビュー、実装証拠を設計要件へ紐づけられます。

単に「設計を読んで実装して」ではなく、「この要件をこのタスクで実装し、この検証で満たした」と言える状態にするための仕組みです。

Readiness gate

readiness gateは、作業を次の段階へ進めてよいか確認するための仕組みです。

代表的なgateは以下です。

gateは基本的にread-onlyです。

状態を勝手に進めるのではなく、不足している証拠や次に必要な操作を表示します。

エージェントが「たぶん大丈夫」と判断するのではなく、節目ごとにgateを通すことで、思い込みを減らします。

Review

agent-workbench はレビューを作業フローに組み込みます。

レビュー計画、レビュー対象、レビュー結果、指摘、指摘の分類、修正、検証を分けて扱います。

レビュー種別も分けています。

また、fresh reviewとresume reviewも分けています。

fresh reviewは、新しい独立したレビューです。 resume reviewは、既知の指摘が修正されたかを確認するためのレビューです。

完了判定には、基本的にfreshなレビューを使う想定です。

Evidence

evidenceは、作業が本当に行われたことを示す証拠です。

たとえば以下です。

- command usage
- validation run
- repository snapshot
- Git commit
- changed file
- implementation evidence
- review finding and closure
- work record

close-ready gateは、これらの証拠を見て、作業を閉じてよいか確認します。

Command profile

command profileは、プロジェクト固有の検証コマンドを記録するための仕組みです。

コードエージェントは、テストコマンドを推測しがちです。

しかし、プロジェクトによって正しいコマンドは違います。

command profileに、固定コマンド、推奨コマンド、非推奨コマンド、逸脱理由などを記録しておくことで、エージェントが毎回推測せずに済むようにします。

ユーザー修正とKPT

ユーザー修正とKPTは、同じ指摘を繰り返さないための仕組みです。

コードエージェントに対して、人間が作業中に注意したことや、次回から守ってほしいことを残します。

たとえば以下です。

- このプロジェクトではこのテストコマンドを使う
- このディレクトリは直接編集しない
- この形式のレビュー指摘を繰り返さない
- 完了前に必ずこの検証を実行する
- この設計方針は採用しない

その場のチャットで注意するだけだと、次のセッションでまた同じ指摘が必要になることがあります。

agent-workbench では、こうした内容をユーザー修正やKPTとして台帳に残せます。

Keep、Problem、Tryとして整理することで、継続すること、問題だったこと、次に試すことを明確にします。

また、繰り返し発生する指摘は、command profile、チェックリスト、レビュー観点、作業ルールへ反映できます。

どういう時に使うか

大きく複雑なプロジェクトでコードエージェントを使う時

agent-workbench は、大きなプロジェクト向けです。

設計、実装、レビュー、検証、修正、完了確認まで含むような作業に向いています。

複数セッションをまたぐ時

作業を翌日に再開したり、別のエージェントに引き継いだりする場合に使えます。

チャット履歴や巨大なMarkdownに頼るのではなく、プロジェクト内の台帳を確認して再開できます。

設計駆動で実装したい時

requirements、decisions、validation gatesをDesign Packageとして扱い、タスク、レビュー、実装証拠へつなげたい場合に使えます。

レビューと完了判定を厳密にしたい時

エージェントが「終わりました」と言う前に、close-ready gate、レビュー結果、検証証拠、repository stateを確認させたい場合に使えます。

同じ注意を何度もしたくない時

ユーザー修正やKPTを記録し、次のエージェントセッションでも同じ前提を使わせたい場合に使えます。

おわりに

コードエージェントは、大きなプロジェクトでもかなり使えるようになってきました。

ただし、作業が大きくなるほど、チャットやMarkdownだけでは状態管理が難しくなります。

設計がどこまで有効なのか。 どのタスクが終わっているのか。 どのレビュー指摘が残っているのか。 どの検証コマンドを使うべきなのか。 作業を閉じてよいだけの証拠が揃っているのか。 前に注意したことを、また繰り返していないか。

こういった情報をエージェントが毎回雰囲気やgrep結果で判断すると、作業が壊れます。

大きなプロジェクトでコードエージェントを使い、設計、レビュー、検証、完了判定、再発防止をきちんと扱いたい場合は、試してみてください。