■ 1. 論点駆動開発
- 論点駆動開発:
- 2025年11月現在運用しているコーディングエージェント向けのコンテキストの作り方
- 既存のフレームワークに乗るのではなく、自分に合うオレオレフレームワークを作るのが一番効率が良い
- 毎日調整しながら運用している
- 試行錯誤の経緯:
- 普段は Claude Code、Codex、Devin を活用し開発を進めている
- エージェントへの指示をどう調整すると実装品質と開発スピードが上がるかを試行錯誤している
- Cline の Memory Bank に心酔し、Claude Code の Plan モードや GitHub の Spec-Kit も試した
- 結論:
- 進捗ドキュメントのテンプレートの内容を埋めながら実装を進めてもらう
■ 2. 仕様駆動開発の壁
- 小さなタスクに不向き:
- Kiro に小さなバグ修正を依頼した際、4つのユーザーストーリーと16の受け入れ基準が設定された話がある
- ドキュメントレビュー化:
- 開発フローがコードレビューからドキュメントレビューに代わり、長大なマークダウンを読むことになる
- 全体を読むのは苦痛で細部の問題に気づきづらく、結局コーディングエージェントとの認識齟齬が生まれる
- 事前に気づけない問題:
- 仕様の作成段階では気づけない問題が多すぎる
- 実装した結果実現不可能だったことに気づいたり、新たな問題に気づくことが多い
- エンジニアリングの本質:
- 達成したいゴールと現時点の制約を比較し、その矛盾をパズルのように解消し続けるプロセス
- 仕様駆動開発は実装前にすべての論点を解消しようとするアプローチである
- 実装を通じて発見される新たな制約や矛盾に対して柔軟に対応しづらい構造になっている
■ 3. plans.md からの着想
- OpenAI Dev Day の紹介:
- 2025年10月6日開催のイベントで Codex の開発者たちが開発の進め方を紹介していた
- Feler さんは plans.md というファイルに仕様や開発計画を書き出させながら開発していた
- その手法で OpenAI 社内で最長のセッション時間とトークン数を達成した
- テンプレートの出自:
- 自身のテンプレートは plans.md をベースに、いくつか自身の好みに合わせて修正したもの
■ 4. 進捗ドキュメントのテンプレート
- 構成セクション:
- Purpose / Overview、Context & Direction、Validation & Acceptance Criteria、Specification、Open Questions
- Discoveries & Insights、Decision Log、Outcomes & Retrospectives、Follow-up Issues、Confidence Assessment
- 位置づけ:
- 仕様駆動ではなく、常に更新し矛盾を解消させ続けるためのドキュメント
- 1つの GitHub issue に対して1つの進捗ドキュメントを作る
- 各セクションを埋めていくと最終的に良質なコンテキストとなるようセクションを設計している
- テンプレートもプロンプト:
- テンプレートには多くの HTML コメントを記載し、その多くは AI 向けの記載方法のプロンプトである
- HTML コメントはマークダウンレンダラーで表示されないため、人間は純粋な進捗だけを読める
- 進捗ドキュメントを書くのは100%AI で、人間は読んでレビューするだけという設計
- テンプレートにプロンプトを含める方法は Spec Kit のアプローチを参考にしている
■ 5. Open Questions セクション
- 最重要セクション:
- 受け入れ条件を満たすために解決すべき論点とその選択肢を、推奨案と自信度つきで記載してもらう
- 人間は基本的にここだけを読んで意思決定を行えばよい設計
- 決定した内容で Decision Log と Specification を更新してもらう
- 仕様を出力させない:
- 仕様ではなく論点と選択肢で出力させると、意味のない仕様や過剰な設計が出にくくなる
- 仕様駆動では指示していない監査ログ機能や、過剰なエラーハンドリングを厳密に実装しようとする
- Spec Kit はシンプルな解決策か、新しいデザインパターンを導入していないかを確認させている
- それでも仕様駆動では大きな仕様が出てきやすい
- タスクの抽象度:
- 論点を出させることで、どの抽象度のタスクでもテンプレートを適用できるようになった
- 抽象度の高いタスクは論点が多すぎて仕様として事前に決め切ることは難しい
- 出力内容が論点であれば、意思決定を後回しにするなど段階的に仕様を決めていける
- 推奨案と自信度:
- 選択肢には推奨案と、高・中・低の三段階を色分けした自信度を出してもらう
- これは Devin のタスク進行を参考にしており、色付けは視覚的にわかりやすい
- 自信度が高く人間としても良さそうな選択肢であれば、そのまま実装に入ってもらう
- 自信度が低い場合は人間も判断しづらいことが多い
- 自信度が低い場合の指示:
- 一旦推奨案で PoC を実装し、自信度を上げるための情報を集めるよう指示する
- もしくは、その選択肢で良いか判断するためのサブ Issue を作るよう指示する
- 再帰的な進行:
- サブ issue を作ったら、また進捗ドキュメントのテンプレートを埋めて作業を進行してもらう
- 解決したら親 issue の Open Questions を解決する
- これを再帰的に繰り返すことで、どんな抽象度のタスクであってもとにかく前に進められる
■ 6. Discoveries セクション
- 役割:
- 発見や気づきを記載してもらうセクション
- Open Questions にコードベースを調べればわかることを書かせないため、事前に必ずここへ書かせる
- これにより無意味な問いが Open Questions に挙がることが起きづらくなった
- 調査結果のキャッシュ:
- 既存コード調査結果のキャッシュとなり、後続の実装フェーズで無駄なコード探索が不要になる
- コーディングエージェントのターン数が減りやすくなるはずである
- 実装中の記録:
- 実装中に問題が起きたり新たな発見があったら都度書いてもらう
- 作業完了後の振り返りフェーズで問題の再発防止を考える際の重要な情報になる
■ 7. タスクリストを作らない
- 方針:
- Spec Kit の tasks.md のようなマークダウンのタスクリストはやめ、GitHub の Sub-issues 機能で管理する
- タスクリストの問題:
- タスクリスト1行では情報量が少なすぎる
- 進行する上で事前に想定したタスクが大幅に変わることもあり管理が難しい
- エージェントに出力させると lint とテストの実行なども1タスクとして扱いがちで粒度の制御が難しい
- Sub-issues の利点:
- 親・子・孫と再帰的に管理でき、GitHub API で操作もでき、人間としても UI 上の視認性が高い
- 着手時に issue を作成:
- 論点の抽象度が高い場合にサブ issue を作り、そこでまた進捗ドキュメントを作る
- サブ Issue が完了したら、その意思決定内容や実装内容で親 Issue の進捗ドキュメントを更新する
- サブ issue を解決するタイミングで新たな論点やタスクが生まれることもある
- 事前にタスクを決め切るのはやめ、着手するタイミングで issue を作って進めるのが良い
■ 8. Decision Log と Specification
- 仕様より意思決定:
- 仕様はそこまで重視せず、意思決定内容を決定ログとして残す
- 実装を進める過程で意思決定内容が変わることもあり、ADR の考え方に近い
- 仕様セクションの意義:
- 実装フェーズのコーディングエージェントのターン数が減りやすいのでセクションとして用意している
■ 9. Acceptance Criteria セクション
- 用途:
- 受け入れ条件を記載してもらうが、人間はそこまで読まない
- PR のレビューをエージェントに依頼する際、受け入れ条件を満たしているかを判定させるために用意している
- テスト方針:
- どのようにテストするかも記載してもらう
- Spec Kit は TDD をかなり強く指示している
- テストが書けない状況でも無理やりテストコードを書こうとしてうまくいかないことが多い印象がある
- 既存のテストコードパターンを調査させた上で、自動テストと手動テストのどちらかを判断させるのが良い塩梅
■ 10. 補助ツール
- issync CLI:
- テンプレートを特定のファイルパスにコピーし、GitHub Issue のコメントに同期するだけの小さなツール
- 管理場所の悩み:
- コーディングエージェントの Read/Edit ツールは効率的なファイル操作に最適化されており活用したい
- git 管理下のローカルファイルとして保存するとコミット操作やコンフリクトが気になる
- 作業完了後も残り、古いドキュメントとして後続エージェントの無駄なコンテキストになってしまう
- Git Worktree による複数セッションやリモートのコーディングエージェントによる同時操作がしづらい
- 到達した解決策:
- gitignore されたディレクトリにマークダウンファイルを置きつつ、GitHub Issue のコメントに同期する
- GitHub Issue から取り出せば複数セッションで並列作業が可能になる
- 人間は GitHub Issue 上でレンダリングされたテキストを読めばよい
- チームメンバーに意思決定内容を共有するための過去ログとしても使える
- Claude Code Plugin:
- issync を使った作業を定型化した Claude Code Commands を Plugin として提供している
- /issync:understand-progress は issue の URL を渡して進捗ドキュメントを理解してもらうコマンド
- 新しい Claude Code セッションを開いたらとりあえず叩いて作業を始める汎用的なコマンドである
- /issync:plan は進捗ドキュメントを初期作成するコマンド
- テンプレートのコピー、コードベース調査、基本セクション記入、Open Questions 記入、Issue 同期を行う
- /issync:create-sub-issue は Sub issues API で親 Issue に紐づけた新規タスクの Issue を作成する
- /issync:complete-sub-issue はサブ issue を完了として進捗ドキュメントを更新する
- 振り返りを行いつつ親の Open Questions を解消したり、新しいタスクの提案をする
- プラグインの利点:
- コマンドの内容を更新して push すると利用側に配布され、プロンプトの試行錯誤がしやすい
- 実装作業自体は Devin や Codex に任せられるが、思考作業は Claude Code から離れられない
■ 11. 実際の運用と自動化
- 運用フロー:
- Issue を作ったら /plan を実行し、論点が大きければ /create-sub-issue で分割する
- 実装できそうなら Devin や Claude Code Action に任せる
- PR がマージできたら /complete-sub-issue を実行して親 issue を更新し、並列でどんどん進める
- 人間がボトルネック:
- 並列作業可能なタスクが圧倒的に増えると、人間のコンテキストスイッチがボトルネックになる
- 人間のタッチポイントを極限まで減らしていくことが重要になる
- そのためには思考作業を言語化・定型化し、エージェントが再現可能な状態にしていく必要がある
- 自動実行:
- /plan と /complete-sub-issue は品質が高く求めるものが出てきやすくなった
- GitHub Actions の Claude Code Action で Issue 作成時に /plan、Issue 完了時に /complete-sub-issue を自動実行している
- タッチポイントを減らせた事例である
- Claude Code Action を整備したことで GitHub モバイルだけで開発を進められるようにもなった
- 未解決の自動化:
- 意思決定後の実装依頼や、完了後の PR が受け入れ条件を達成しているかのチェックも自動化できそうである
- UI の変更などではまだうまく QA がしづらく試行錯誤している
■ 12. 人間のタッチポイント
- 人間が判断すべき最小限のポイント:
- 自身のテンプレートと現時点の Claude Sonnet 4.5 を前提とした想定である
- Issue や Sub issue の作成判断
- Open Questions の意思決定
- 実装後の最終レビュー
- 自動化の難しさ:
- その他の二次的な作業は可能な限り自動で進められるようワークフローを整備したい
- エージェントが実装で詰まっている箇所をサポートすることはまだまだある
- 明瞭なコードベースやアーキテクチャ、情報量の多いログの整備が必要な要素として挙がる
- エージェント自身でフィードバックサイクルを回しやすいテスト基盤も必要である
- 外科医のようにコードを書く:
- Notion で働く Geoffrey Litt さんが自身のブログで用いた表現である
- 外科医はマネージャーではなく実際に手術をする人である
- 準備や二次的な業務、事務作業を行うサポートチームがいることで外科医は重要な業務に集中できる
- コードベース調査や作業が明確な実装タスクはとにかくエージェントに任せる
- 課題の特定、アーキテクチャ決定、デザインコンセプトの試行錯誤に100%時間を使える状態を目指したい
■ 13. 位置づけと今後
- 自作フレームワークの位置づけ:
- 誰かに使ってもらいたいモチベーションはなく、コンテキストエンジニアリングの事例として参考になれば幸いである
- モデルの進化や環境の変化に伴い明日には大きく変わっているかもしれない
- 変化に追従しつつ自分に合ったコンテキストの作り方を模索していく
■ 14. 落穂拾い
- コーディングとレビューの分離:
- セッションを分ける方が最終的な精度が出やすい
- 実装しながらセルフレビューは複数の観点に同時に取り組むことになり期待する結果が出づらい
- コンテキストをクリアした新しいセッションで、フラットな視点からレビューだけしてもらう
- レビュー用ワークフロー:
- PR に devin-review ラベルを貼るとレビュー観点に従って検査した後そのまま改修を進める GitHub Actions を用意している
- CodeRabbit なども精度は高いレビューが出る
- 人間がレビューする前に実装修正までやって欲しい場合は Devin などのクラウド型エージェントが便利
- ドキュメントワークの分離:
- コーディングエージェントは長文を書きがちである
- 「とにかく書く」と「情報量を維持し圧縮する」セッションは分けた方が良い
- そのための Claude Code Command を用意している