概要
Claude CodeやCodexのようなAIコーディングエージェントは、コードの調査、実装、テスト、ドキュメント更新などをまとめて進められます。
小さな修正であれば、「この不具合を直してください」という指示だけでも十分な結果が得られることがあります。
一方、数十〜数百件のタスクを含む開発では、同じ進め方は通用しません。
- どのタスクを作業しているのか分からなくなる
- 依頼していない範囲まで変更される
- 実装済みと検証済みが混同される
- ドキュメントとソースコードの状態がずれる
- 「完了しました」という報告を受けたものの、実環境では動かない
- 新しく見つかった問題が、作業中のタスクへ無理に混ぜ込まれる
こうした問題は、AIのコーディング能力だけでは解決できません。
重要なのは、AIが迷わず作業でき、人間があとから検証できる形にタスクを設計することです。
この記事では、実際に多数の開発タスクをAIコーディングエージェントへ順番に任せる中で整理した、次の運用方法を紹介します。
-
task-list.mdをタスク管理の唯一の正本にする - 原則として、進行中のタスクを1件に限定する
- 複数のAIを使う場合は、役割とコンテキストの境界を決める
- 目的、変更範囲、禁止事項、テスト、停止条件を明文化する
- 実装、テスト、文書更新、コミット、Draft PRまでを一つの作業単位にする
- AIの自己申告ではなく、差分、テスト結果、実環境の証拠で完了を判定する
なお、特定のプロジェクト名、顧客名、リポジトリ名、実際のタスクIDは出さず、一般化した形でまとめています。
大規模開発では「長いプロンプト」だけでは管理できない
大規模開発で最初に起きやすいのは、プロンプトが巨大化することです。
要件、設計、禁止事項、過去の決定、テスト方法、残タスクを毎回プロンプトへ貼り付けると、指示する側もAI側も重要事項を見失いやすくなります。
また、チャットの会話だけを進捗管理に使うと、次の問題が発生します。
- 新しいセッションで過去の決定が正しく引き継がれない
- 会話の途中で変更された方針が、正式な仕様なのか分からない
- 「前回どこまで終わったか」を毎回調べ直す必要がある
- 複数のAIや人間が作業すると、認識が分岐する
- 完了報告は残っているが、何を根拠に完了としたのか追跡できない
チャットは作業の入口としては便利ですが、プロジェクトの正本には向きません。
そこで、会話の外に「現在の正しい状態」を残す必要があります。
基本方針：task-list.mdを唯一の正本にする
タスク管理の中心として、リポジトリ内にdocs/task-list.mdを置きます。
ここでいう「唯一の正本」とは、進捗について判断が分かれた場合に、最終的にこのファイルを確認するという意味です。
Slack、GitHub Issue、チャット、AIの完了報告に異なる記載があっても、正式な状態はtask-list.mdへ反映された内容とします。
たとえば、次のような形式です。
| ID | タスク | 状態 | 進捗 | 依存 | 完了条件 | 証拠 |
|---|---|---|---:|---|---|---|
| DEV-001 | 記事下書きAPIの作成 | 完了 | 100% | - | APIテスト成功 | Test #18 / PR #12 |
| DEV-002 | 二重登録の防止 | 進行中 | 70% | DEV-001 | 同一IDで投稿が増えない | 検証待ち |
| DEV-003 | 承認画面の追加 | 未着手 | 0% | DEV-002 | 仕様書記載の操作が可能 | - |
最低限、次の情報を持たせます。
| 項目 | 目的 |
|---|---|
| ID | タスクを一意に識別する |
| タスク名 | 何を実現するかを短く示す |
| 状態 | 未着手、進行中、検証待ち、完了、保留などを示す |
| 進捗 | 状態だけでは分からない途中経過を補助する |
| 依存関係 | 先に終えるべきタスクを明確にする |
| 完了条件 | 何をもって終了とするかを定義する |
| 証拠 | テスト、PR、ログ、画面確認などを紐付ける |
タスクIDは途中で再利用しない
一度発行したタスクIDは、削除したタスクであっても別の用途へ再利用しません。
再利用すると、過去のコミット、PR、テスト結果、会話に書かれたIDが別の意味になってしまいます。
タスクを取りやめた場合は行を消すのではなく、状態を「中止」や「対象外」に変更し、理由を残します。
新しい問題は新しいタスクとして登録する
作業中に別の不具合や改善点を見つけても、現在のタスクへ安易に含めません。
まず、次のどれに該当するかを判断します。
- 現在の完了条件を満たすために必須である
- 関連はあるが、現在の完了条件とは別である
- 無関係な既存問題である
1であれば現在のタスク内で扱います。
2または3であれば、新しいタスクとして登録し、現在の作業を継続します。
この切り分けを行わないと、1件のタスクが際限なく膨らみ、いつまでも完了できなくなります。
原則として、進行中のタスクは1件に限定する
大規模開発だからこそ、通常は進行中のタスクを1件に限定します。
AIは複数の処理を高速に進められますが、同じリポジトリで複数タスクを同時に変更すると、人間が確認すべき組み合わせが急増します。
たとえば、3件のタスクが同時に同じAPIやDBへ変更を加えると、次の判断が難しくなります。
- どの変更が不具合の原因なのか
- どのタスクのテストで検出すべきなのか
- 仕様変更がどのタスクから発生したのか
- 途中で差し戻す場合、どこまで戻せばよいのか
そのため、基本の流れを次のようにします。
- 次に着手するタスクを1件決める
- 開始時点のGit状態を確認する
- 対象タスクだけを実装する
- テストとレビューを行う
- 文書と証拠を更新する
- コミットまたはDraft PRを作成する
- タスクを完了または検証待ちにする
- 次のタスクへ進む
並列化する場合も、同じファイルや同じデータへ書き込まない、独立性の高い調査やテストに限定します。
複数の実装を並列で進める場合は、ブランチやGit worktreeを分離します。
1タスクに含めるべき情報
AIへ渡すタスクには、少なくとも次の6項目を含めます。
1. 目的
「何を変更するか」だけでなく、「なぜ変更するか」を書きます。
悪い例：
二重登録を直してください。
改善例：
外部システムが同じ候補を再送した場合でも、
同じ下書きが複数作成されないようにしてください。
再送は正常系として扱い、既存の下書きを再利用します。
目的が分かれば、AIは単にエラーを隠すのではなく、利用者が期待する状態を基準に実装できます。
2. 変更範囲
調査・変更してよいファイルや機能を示します。
変更対象：
- 下書き登録API
- 外部候補IDを扱う投稿メタ
- 上記に対応する自動テスト
- 関連設計書とtask-list.md
変更範囲を狭めることで、AIが「ついでのリファクタリング」まで始めることを防ぎます。
3. 禁止事項
実行してはいけないことを明示します。
禁止事項：
- 公開済みデータを変更しない
- APIの既存レスポンス形式を変更しない
- 本タスクと無関係な警告を一括修正しない
- テストを通すために期待値を実装へ合わせない
- 根拠なく仕様を補完しない
特に、「不明点を推測で埋めない」というルールは重要です。
4. 完了条件
完了条件は、第三者がYes／Noで判定できる形にします。
完了条件：
- 初回リクエストでは下書きが1件作成される
- 同じ外部候補IDで再送しても新規投稿が増えない
- 2回目は初回と同じ投稿IDを返す
- 異なる外部候補IDでは別の下書きが作成される
- 既存テストを含む関連テストが成功する
「適切に動作すること」「問題なく実装されていること」といった表現は、判定基準になりません。
5. テスト方法
どの層で何を確認するかを指定します。
| テスト | 確認する内容 |
|---|---|
| Unit Test | 判定ロジック単体の正しさ |
| Integration Test | API、DB、外部IDの連携 |
| Regression Test | 既存機能が壊れていないこと |
| 実環境確認 | 本番に近い構成で操作できること |
すべてのタスクで全種類を行う必要はありません。
ただし、どのテストを行い、どのテストを行っていないかは区別して報告させます。
6. 停止条件
AIが勝手に判断してはいけない境界を定めます。
次の場合は作業を停止し、変更せずに報告してください。
- 仕様書同士に矛盾がある
- 対象データの削除が必要になる
- DBマイグレーションが既存データへ影響する
- 認証情報や本番環境への追加権限が必要になる
- task-list.mdに記載された変更範囲を超える
- 開始時点で作業ツリーに未確認の変更がある
停止条件は、AIの能力を制限するものではありません。
人間が判断すべき箇所を、あらかじめ切り分けるためのものです。
タスク指示のテンプレート
実際には、次のようなテンプレートを使用できます。
# 対象タスク
DEV-002 二重登録の防止
## 開始前確認
- 現在のブランチ、HEAD、git statusを確認する
- task-list.mdと関連仕様書を読む
- 先行タスクDEV-001が完了していることを確認する
- 作業ツリーに既存変更がある場合は停止する
## 目的
同じ外部候補が再送されても、新しい下書きを重複作成しない。
## 変更範囲
- 下書き登録API
- 外部候補IDの保存・検索処理
- 関連テスト
- 関連ドキュメント
## 禁止事項
- 既存APIのレスポンス形式を変更しない
- 公開済み投稿を変更しない
- 無関係なリファクタリングを行わない
- 仕様が不明な場合に推測で実装しない
## 完了条件
- 初回のみ下書きが作成される
- 再送時は既存の投稿IDが返る
- 異なる候補IDは別投稿として作成される
- 関連テストと既存テストが成功する
## 完了時に行うこと
- task-list.mdの状態、進捗、証拠を更新する
- 変更差分を自己レビューする
- タスクIDを含むコミットを作成する
- 必要に応じてDraft PRを作成する
- 指定形式で完了報告する
## 停止条件
- 仕様矛盾、破壊的変更、権限不足、既存変更を検出した場合は停止する
毎回使うルールは、プロンプトへ繰り返し貼り付けるより、リポジトリ内の永続的な指示ファイルへ置く方が管理しやすくなります。
CodexではAGENTS.md、Claude CodeではCLAUDE.mdを利用できます。両方を使う場合は、共通ルールを1か所へまとめ、片方から読み込む構成にすると重複を減らせます。
ただし、個別タスクの目的や完了条件まで永続ルールへ詰め込むべきではありません。
| 置き場所 | 書く内容 |
|---|---|
AGENTS.md / CLAUDE.md
|
テストコマンド、禁止事項、Git運用、レビュー基準 |
task-list.md |
タスクの状態、依存関係、完了条件、証拠 |
| 個別タスク指示 | 今回の目的、対象範囲、固有の確認事項 |
| 設計書 | システム全体の仕様、データ構造、判断理由 |
「実装済み」と「完了」を分ける
大規模開発で特に重要なのが、状態を細かく分けることです。
コードが存在するだけでは、その機能が正しいとは限りません。
たとえば、次の状態はすべて異なります。
| 状態 | 意味 |
|---|---|
| 未着手 | 調査も実装も始まっていない |
| 調査中 | 仕様や既存コードを確認している |
| 実装中 | コードを変更している |
| ローカル検証済み | 自動テストなどは成功した |
| 実環境検証待ち | デプロイ先や実データでの確認が残っている |
| 完了 | 定義した完了条件と必要な検証をすべて満たした |
| 保留 | 外部回答、権限、仕様決定などを待っている |
この区別がないと、AIはコードを書いた時点で「完了」と報告し、人間は実環境で使える状態だと誤認します。
実環境でしか確認できない項目が残っている場合は、無理に100%にせず、「実装完了・実環境検証待ち」とします。
完了報告は「作業内容」ではなく「証拠」を中心にする
AIから次のような報告を受けても、完了確認としては不十分です。
二重登録防止機能を実装しました。
テストも追加し、問題なく動作しています。
必要なのは、第三者が追跡できる情報です。
## 結果
- DEV-002を実装
- 初回リクエスト：投稿ID 120を作成
- 同一外部候補IDでの2回目：投稿ID 120を再利用
- 投稿件数：1件のまま
- 異なる候補ID：投稿ID 121を新規作成
## テスト
- 対象テスト：12件成功、0件失敗
- 関連回帰テスト：48件成功、0件失敗
- 実環境確認：未実施
## Git
- 開始時HEAD：abc1234
- 終了時HEAD：def5678
- ブランチ：feature/DEV-002-idempotency
- コミット：DEV-002 Prevent duplicate drafts
## 残事項
- 検証環境への反映後、同一リクエストの再送確認が必要
- task-list.mdは「実環境検証待ち、90%」へ更新
確認したい証拠
- 変更ファイル一覧
- Git差分
- 実行したコマンド
- テスト件数と結果
- 再現手順と修正後の結果
- 作成または更新されたデータの識別子
- 未実施の確認項目
- コミットSHAまたはPR URL
- 開始時と終了時の
git status
重要なのは、すべて成功したように見せることではありません。
未確認事項を未確認のまま正確に報告することです。
実装・テスト・文書更新・Gitを一つの単位にする
コードだけを先に大量実装し、あとからテストや文書をまとめて更新すると、どの変更に対応するものか分からなくなります。
そのため、1タスクを次の単位で閉じます。
- 仕様確認
- 実装
- テスト追加・実行
- 差分レビュー
-
task-list.mdと関連文書の更新 - コミット
- 必要に応じてDraft PR作成
- 完了報告
コミットメッセージやブランチ名にタスクIDを入れると、あとから追跡しやすくなります。
feature/DEV-002-idempotency
fix(DEV-002): prevent duplicate draft creation
Draft PRは「すべて完了した」という意味ではなく、レビュー可能な単位まで変更がまとまったことを示すために使えます。
実環境検証が残っている場合は、PR本文とtask-list.mdの両方へ明記します。
Planと実装を分ける
変更範囲が広いタスクでは、いきなり実装させず、先に調査と計画だけを依頼します。
計画段階では、次を確認します。
- 参照した仕様書とコード
- 変更予定のファイル
- 既存機能への影響
- DBやAPI互換性への影響
- 追加するテスト
- 判断が必要な不明点
- ロールバック方法
この段階で変更範囲が想定より広いと判明した場合は、タスクを分割します。
Claude Code、Codexともに、変更前に計画を確認するためのPlan系の進め方を利用できます。
ただし、計画を作っただけで安全になるわけではありません。計画がtask-list.mdの完了条件と一致しているか、人間が確認することが重要です。
複数のAIを使うなら、役割とコンテキストの境界を決める
ChatGPT、Claude Code、Codexなどを組み合わせれば、要件整理、実装、レビューを分担できます。
しかし、複数のAIへ同じリポジトリ全体を理解させれば精度が上がるとは限りません。役割を決めずに併用すると、それぞれが同じコードや設計書を読み、似た調査と説明を繰り返します。
たとえば、次のように役割を分けます。
| 担当 | 主な役割 | 主に参照する情報 | 出力 |
|---|---|---|---|
| 人間 | 優先順位、仕様判断、完了判定 | タスク一覧、証拠、事業要件 | 着手判断、承認、差し戻し |
| ChatGPT | 要件整理、指示作成、結果レビュー | 対象タスク、必要な仕様、変更差分 | 実装指示、指摘事項 |
| Claude Code / Codex | コード調査、実装、テスト | 対象タスクに必要なリポジトリ内情報 | 差分、テスト結果、完了報告 |
重要なのは、AI間の受け渡しへリポジトリ全体の説明を毎回含めないことです。
受け渡す情報は、原則として次の範囲へ絞ります。
- 対象タスクIDと目的
- 変更対象と変更禁止範囲
- 完了条件と停止条件
- 実際の変更差分
- テスト結果と未確認事項
- 判断が必要な論点
実装担当のAIは、必要なファイルをリポジトリから直接確認します。レビュー担当のAIには、まず対象タスク、差分、テスト結果を渡し、必要な場合だけ関連ファイルを追加で確認させます。
このように「誰が何を読むか」まで決めることが、複数のAIを動かすハーネス設計です。
AIが止まるべき場面を決める
AIへ大規模開発を任せるとき、「自律的に進めてほしい」と「勝手に決めてほしくない」は両立します。
日常的な判断はAIに任せ、事業・契約・セキュリティ・破壊的変更に関わる判断では止めます。
そのまま進めてよい例
- 既存の書式に合わせたテスト追加
- 仕様書に明記された入力チェックの実装
- 対象範囲内の軽微なリファクタリング
- lintやformatterによる対象ファイルの整形
- 再現済み不具合に対する最小限の修正
停止して確認すべき例
- 仕様書と実装のどちらを正とするか決められない
- 既存データの削除や変換が必要
- 公開APIの互換性を壊す可能性がある
- 認証・決済・個人情報の扱いが変わる
- 本番環境の設定変更が必要
- タスク外の大規模な設計変更が必要
- ユーザーの既存変更と競合する
停止時の報告にも形式を持たせます。
## 停止理由
仕様書Aでは重複時に409を返す一方、仕様書Bでは既存IDを返す記載があります。
## 確認済み
- 対象箇所：API仕様書 4.2、基本設計書 7.1
- 現在の実装：409を返す
- ファイル変更：なし
- Git状態：開始時から変更なし
## 判断が必要な点
重複時の正式なレスポンスを、409または既存ID返却のどちらにするか。
「分からないので停止した」は失敗ではありません。
根拠なく実装して手戻りを増やすより、安全な成果です。
ありがちな失敗例
失敗例1：ChatGPTとClaude Codeの両方にGitHub全体を読ませた
実際に、ChatGPTをGitHubと連携し、実装をClaude Codeへ依頼する運用を行ったことがあります。
当初の流れは次のようなものでした。
- ChatGPTがGitHubを読み、状況を整理してClaude Codeへの指示を作る
- Claude Codeも同じリポジトリと設計書を読み直して実装する
- Claude Codeの完了報告をChatGPTへ渡す
- ChatGPTがGitHubを再確認して追加指示を作る
- Claude Codeが指摘を受け、関連ファイルを再び読み直す
このラリーを繰り返すたび、同じコード、設計書、完了報告が何度もコンテキストへ入ることになりました。確認精度が読み込み量に比例して上がったわけではなく、トークンだけが異常に消費されました。
問題は、複数のAIを使ったことでも、AIへ広い範囲を任せたこと自体でもありません。
問題の本質は、ハーネス側で次の事項を設計しないまま、両方のAIへプロジェクト全体を理解させようとしたことです。
- どのAIが要件を整理するのか
- どのAIが実装するのか
- どのAIが何をレビューするのか
- AI間で何を受け渡すのか
- どこまで再読み込みを許容するのか
- 最終的な完了を誰が判定するのか
以降は、ChatGPTを要件整理とレビュー、Claude Codeを実装とテストに限定しました。また、受け渡しには対象タスク、変更対象、完了条件、差分、テスト結果、未確認事項だけを含めるようにしました。
対策：
- AIごとの責務を先に決める
- 同じリポジトリ全体を複数のAIに毎回読ませない
- レビューはタスク、差分、テスト結果から開始する
- 追加調査は疑義がある箇所だけに限定する
- AI同士を直接ラリーさせず、人間が継続・停止・完了を判定する
AIに任せる範囲を広げるほど、AI同士の役割分担とコンテキスト境界を人間が設計する必要があります。
失敗例2：一度に複数タスクを依頼する
未完了のタスクを上からすべて実装してください。
この依頼では、途中で仕様矛盾やテスト失敗が起きたとき、どの変更を残すべきか判断しづらくなります。
対策：
- 依存関係を確認し、1件ずつ進める
- 独立タスクを並列化する場合は、ブランチやworktreeを分ける
- 各タスクを個別のコミットまたはPRにする
失敗例3：「残りをいい感じに進めて」と依頼する
AIは、優先順位、事業上の重要度、外部依存を完全には把握できません。
対策：
- 次に着手するタスクIDを明示する
- 優先順位と依存関係を
task-list.mdへ記録する - 判断が必要な場合は候補と根拠を出させ、人間が選ぶ
失敗例4：AIの完了報告だけで100%にする
テストコードが通っても、実環境の設定やデータ条件によって動かない場合があります。
対策：
- 完了条件ごとに証拠を確認する
- ローカル検証と実環境検証を分ける
- 未検証なら「検証待ち」として残す
失敗例5：テストを通すために仕様を変える
AIが失敗しているテストの期待値を実装へ合わせてしまうと、テストは成功しても本来の要件を満たしません。
対策：
- 期待値の根拠となる仕様を明示する
- テスト変更時は、変更理由を報告させる
- 修正前に失敗を再現し、修正後に同じ条件で成功することを確認する
失敗例6：ドキュメント更新だけが進む
タスク一覧を100%へ更新しても、コードや環境が変わるわけではありません。
対策：
- コード差分、テスト、実環境の証拠を確認してから状態を更新する
- 文書のみの変更なのか、機能実装を伴うのかを分ける
- 「確認できなかったこと」も記録する
失敗例7：同じ失敗をプロンプトで毎回注意する
同じ注意を毎回書く運用は、いずれ抜けます。
対策：
- 繰り返し発生するルールは
AGENTS.mdまたはCLAUDE.mdへ移す - 機械的に検出できるものはCIやlintへ移す
- 作業手順として再利用できるものはスキルやテンプレートにする
実務で使うチェックリスト
プロジェクト開始時
- タスク管理の正本を決める
- タスクIDの命名規則を決める
- 状態と進捗率の定義を決める
- 完了条件と証拠の記録欄を設ける
- 設計書、テスト計画、タスク一覧の関係を明確にする
- AIが必ず読む永続指示ファイルを用意する
- ビルド、テスト、lintの実行方法を記載する
- 禁止事項と停止条件を記載する
- 複数のAIを使う場合は、それぞれの責務を決める
- AI間で受け渡す情報と再読み込みの範囲を決める
タスク開始前
- 対象タスクIDを1件に絞る
- 依存タスクが完了しているか確認する
-
現在のブランチ、HEAD、
git statusを確認する - 既存の未コミット変更がないか確認する
- 目的、変更範囲、禁止事項を確認する
- 完了条件がYes／Noで判定できるか確認する
- 必要なテストと実環境確認を決める
- 他のAIが同じ調査を重複して行っていないか確認する
実装後
- 対象外の変更が混ざっていないか差分を確認する
- 修正前の失敗と修正後の成功を比較する
- 関連する既存テストを実行する
- 未実施の検証項目を明記する
- タスク一覧と関連設計書を更新する
- コミットにタスクIDを含める
- Draft PRの説明と実際の差分が一致しているか確認する
- 開始時と終了時のGit状態を記録する
- 次のAIへ渡す情報を、対象タスク、差分、テスト結果、未確認事項に絞る
完了判定時
- 完了条件をすべて証拠付きで確認できる
- 「実装済み」と「実環境検証済み」を混同していない
- AIの説明だけでなく、Git差分を確認した
- テスト件数と失敗件数を確認した
- 新たに発見した問題が別タスクとして記録されている
- 保留事項、外部依存、既知の制限が残されている
まとめ
Claude CodeやCodexへ大規模開発を任せるとき、重要なのは長いプロンプトを書くことではありません。
重要なのは、次の6点です。
-
task-list.mdを進捗管理の唯一の正本にする - 原則として進行中のタスクを1件に限定する
- 複数のAIを使う場合は、責務とコンテキストの境界を決める
- 目的、変更範囲、禁止事項、完了条件、停止条件を明文化する
- 実装、テスト、文書更新、Git操作を一つの作業単位にする
- AIの自己申告ではなく、差分、テスト結果、実環境の証拠で完了を判定する
AIコーディングエージェントは、明確なタスクを実行する能力には優れています。
一方で、プロジェクトの優先順位、事業上の判断、リスク許容度まで自動的に正しく決められるわけではありません。
人間が「何を、どこまで、誰に任せ、何をもって完了とするか」を管理し、AIが調査、実装、検証、記録を進める。
この役割分担ができると、数十件、数百件のタスクであっても、状態を見失わずに開発を継続しやすくなります。
AIに任せる範囲を広げるほど、管理を減らすのではなく、役割、情報の流れ、完了条件を判定可能な形へ変えることが大切です。
参考資料
- OpenAI: Best practices for Codex
https://developers.openai.com/codex/learn/best-practices - OpenAI: Custom instructions with AGENTS.md
https://developers.openai.com/codex/agent-configuration/agents-md - Anthropic: How Claude remembers your project
https://docs.anthropic.com/en/docs/claude-code/memory - Anthropic: Common workflows
https://docs.anthropic.com/en/docs/claude-code/common-workflows