2025 年はコーディングエージェントを活用した開発が主流になっており、様々なプラクティスも生まれています。完全にエージェントに任せてコードがどのように動作するかに注意を払わない Vibe Coding や、詳細な仕様を作成してからエージェントに任せる Spec-driven Development(SDD)など、多くの手法が提案されています。
私自身も普段は Claude Code, Codex, Devin などを活用し開発を進めており、コーディングエージェントに出す指示をどう調整すると実装品質と開発スピードが上がるかを試行錯誤しています。いわゆるコンテキストエンジニアリングです。かつては Cline の Memory Bank に心酔しましたし、Claude Code の Plan モードや、GitHub が公開している SDD フレームワークである Spec-Kit を試したりもしました。
その上で 2025 年 11 月現在は、既存のフレームワークに乗るのではなく自分に合うオレオレフレームワークを作るのが一番効率が良いと考え毎日調整しながら運用しており、論点駆動開発と名付けています。
この記事では私が今運用しているコーディングエージェント向けのコンテキストの作り方を紹介します。
結論
以下のテンプレートの内容を埋めながら実装を進めてもらいます。以上です。
- Purpose / Overview
- Context & Direction
- Validation & Acceptance Criteria
- Specification
- Open Questions
- Discoveries & Insights
- Decision Log
- Outcomes & Retrospectives
- Follow-up Issues
- Confidence Assessment
実際に運用している様子は以下の issue で見られます。これは自分用に開発している CLI ツールの issue の例で、Claude Code Action にテンプレートを埋めながら開発を進めてもらっています。
...これだけでは説明が足りなさすぎるので、この記事では背景や思想、テンプレートの使い方などを詳しく説明します。
背景
現在の仕様駆動開発の壁
AWS の Kiro や GitHub の Spec Kit に代表されるような仕様駆動開発の手法は最近かなり盛り上がっていますが、以下のような問題点が指摘されています。
- 小さなタスクには不向き。Kiro に小さなバグ修正を依頼した際、4 つのユーザーストーリーにまとめ、16 の受け入れ基準を設定したという話もあります。
- 開発フローが「コードレビュー」から「ドキュメントレビュー」に代わり、長大なマークダウンを読むことになります。全体を読むのはかなり苦痛で細部の問題に気づきづらく、結局コーディングエージェントとの認識齟齬が生まれます。
- 仕様の作成段階では気づけない問題が多すぎます。実装した結果実現不可能だったことに気づいたり、新たな問題に気づくことが多いです。
ソフトウェアエンジニアリングは、達成したいゴールと現時点の制約を比較し、その矛盾をパズルのように解消し続けるプロセスです。仕様駆動開発はその点では、実装前にすべての論点を解消しようとするアプローチであり、実装を通じて発見される新たな制約や矛盾に対して柔軟に対応しづらい構造になっていると感じます。
OpenAI Dev Day で紹介されていた plans.md
2025 年 10 月 6 日に開催された OpenAI Dev Day では、Codex の開発者たちがどのように開発を進めているかを紹介していました。その中で Feler さんは plans.md と呼ばれるファイルに仕様や開発計画を書き出させながら開発し、OpenAI 社内で最長セッション時間・トークン数を達成したとのことでした。 これはとても素晴らしいものでした。私のテンプレートはこの plans.md をベースにしつつ、いくつか自身の好みに合わせて修正したものです。
これらの背景を踏まえ、次のセクションからはテンプレートの設計思想やプロンプトエンジニアリングの試行錯誤について紹介していきます。
progress-document-template.md
先ほどのテンプレートを再掲します。私はこれを進捗ドキュメントと呼び、Claude Code に記載させます。
- 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 コメントは GitHub などのマークダウンレンダラーでは表示されないので、人間は純粋な進捗だけを読むことができます。
進捗ドキュメントを書くのは 100%AI で、人間は読んでレビューするだけという設計です。
テンプレートにプロンプトを含める方法は Spec Kit のアプローチを参考にしています。 https://github.com/github/spec-kit/blob/e6d6f3cdee99752baee578896797400a72430ec0/templates/tasks-template.md
Open Questions セクション
セクションの中で最も重要視しているのがこの Open Questions セクションです。受け入れ条件を満たすために解決すべき論点とその選択肢を、推奨案と自信度つきで記載してもらいます。人間は基本的にここだけを読んで意思決定を行えば良い設計です。決定した内容で Decision Log と Specification を更新してもらいます。
仕様を出力させない
「仕様」ではなく「論点+選択肢」で出力させると意味のない仕様や過剰な設計が出にくくなったと感じます。仕様駆動の場合、指示していないのに監査ログの機能を入れようとしたり、過剰なエラーハンドリングを厳密に実装しようとしたり。Spec Kit も「シンプルな解決策か」「新しいデザインパターンを導入していないか」というチェックを入れていますが、それでも大きな仕様が出てきやすいです。
タスクの抽象度
また、論点を出させることでどの抽象度のタスクでもテンプレートを適用できるようになりました。抽象度の高いタスクは論点が多すぎて仕様として事前に決め切ることは難しいですが、出力内容が論点であれば意思決定を後回しにするなど段階的に仕様を決めていくことができます。
推奨案と自信度
選択肢には推奨案とその自信度を 🟢(高)🟡(中)🔴(低) で出してもらうようにしています。これは Devin のタスク進行を参考にしています。色付けは視覚的にわかりやすいです。
自信度が高く人間としても良さそうな選択肢であればそのまま実装に入ってもらいますが、自信度が低い場合は人間も判断しづらい場合が多いので、以下の 2 パターンのどちらかを指示することが多いです。
- 「一旦推奨案で PoC を実装してみて、自信度を上げるための情報を集めて」
- 「その選択肢で良いか判断するためのサブ Issue を作って」
サブ issue を作ったら、また進捗ドキュメントのテンプレートを埋めて作業を進行してもらいます。解決したら親 issue の Open Questions を解決します。これを再帰的に繰り返すことで、どんな抽象度のタスクであってもとにかく前に進められるようにしています。
Discoveries セクション
発見や気づきを記載してもらうセクションです。Open Questions で挙げる問いにはコードベースを調べればわかることは記載して欲しくないのですが、事前にこのセクションに必ず書くようにしてもらってからそれは起きづらくなりました。
これは既存コード調査結果のキャッシュとなるので、後続の実装フェーズで無駄なコード探索が不要になり、コーディングエージェントのターン数が減りやすくなる(はず)です。
また実装中何か問題が起きたり、新たな発見があったら都度書いてもらうようにしています。これは作業完了後の振り返りフェーズで問題の再発防止を考える際の重要な情報にもなります。
タスクリストは作らない
Spec Kit の tasks.md のようにマークダウンのタスクリストでタスクを整理するのはやめ、完全に GitHub の Sub-issues 機能で管理するようにしました。 タスクリスト 1 行では情報量が少なすぎるのと、進行する上で事前に想定したタスクが大幅に変わることもあり、管理が難しいです。またタスクリストをエージェントに出力させると「lint とテストの実行」なども 1 つのタスクとして扱おうとしがちで、粒度のコントロールも難しいと感じています。
GitHub の Sub-issues だと親・子・孫と再帰的に管理できますし、GitHub API で操作もでき、人間としても UI 上での視認性が高いです。
論点の抽象度が高い場合にサブ issue を作り、そこでまた進捗ドキュメントを作ります。サブ Issue が完了したらその意思決定内容や実装内容で親 Issue の進捗ドキュメントを更新します。これを再帰的に行うことでとにかく前に進んでいきます。
サブ issue を解決するタイミングで新たな論点やタスクが生まれることもあるので、事前にタスクを決め切るのはやめ、着手するタイミングで issue を作って進めるのが良いと考えています。
Decision Log セクションと Specification セクション
前述の通り仕様はそこまで重視しておらず、意思決定内容を決定ログとして残すようにしています。実装を進める過程で意思決定内容が変わることもあり、これは ADR(Architecture Decision Record)の考え方に近いです。 ただ、仕様セクションは実装フェーズのコーディングエージェントのターン数が減りやすいのでセクションとしては用意しています。
Acceptance Criteria セクション
受け入れ条件を記載してもらいます。人間はそこまで読まず、PR のレビューをエージェントにしてもらう時に「受け入れ条件を満たしているか？」を判定してもらうためにセクションを用意しています。
「どのようにテストするか？」も記載してもらいます。Spec Kit は TDD をかなり強く指示していますが、個人的にはテストが書けない状況でも無理やりテストコードを書こうとしてうまくいかないことが多かった印象です。 既存のテストコードパターンを調査させた上で、自動テストと手動テストのどちらかを判断させるのがちょうど良い塩梅でした。
補助ツール
紹介した progress-document-template を GitHub Issue ごとに埋めていく運用ですが、それを補助するための自分用の CLI や Claude Code Commands も用意しています。
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... 進捗ドキュメントを初期作成するコマンドです。issync を使ったテンプレートのコピー、コードベース調査、基本セクション記入、Open Questions の記入、GitHub Issue への同期を行います。/issync:create-sub-issue... 新規タスクを GitHub Issue として作成します。GitHub の Sub issues API を使って親 Issue を紐づけます。/issync:complete-sub-issue... サブ issue を完了として進捗ドキュメントを更新します。振り返りを行いつつ親の Open Questions を解消したり、新しいタスクの提案をします。
Claude Code のプラグインがとても良く、コマンドの内容を更新して push したらいい感じに利用側に配布してくれます。これが便利で、プロンプトの試行錯誤がしやすいです。実装作業自体は Devin や Codex に任せられるのですが、こういった思考作業は Claude Code から離れられなくなっています。
実際の運用
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 がしづらく試行錯誤しています。
人間が創造的なタスクやコア業務に集中できるように
自分のテンプレートと、現時点での Claude Sonnet 4.5 だと、今は以下は人間のタッチポイントになるのかなと考えています。エージェントの提案を受けても良いものの、人間が判断をしなければならない最小限のポイントです。
- Issue や Sub issue の作成判断
- Open Questions の意思決定
- 実装後の最終レビュー
その他の「二次的な」作業は可能な限り自動で進められるようにワークフローを整備していきたいと考えていますが、なかなか難しいことも事実です。エージェントが実装で詰まっている箇所をサポートすることはまだまだあり、明瞭なコードベースやアーキテクチャ・情報量の多いログの整備、エージェント自身でフィードバックサイクルを回しやすいテスト基盤など、必要な要素はたくさんあります。
Notion で働いている Geoffrey Litt さんは、自身のブログで「外科医のようにコードを書く」と表現しています。外科医はマネージャーではなく実際に手術をする人です。ただ、準備や二次的な業務、事務作業など行うサポートチームがいることで、外科医は重要な業務に集中できるのです。
コードベース調査や作業が明確な実装タスクはとにかくエージェントに任せ、課題の特定・アーキテクチャ決定・デザインコンセプトの試行錯誤などの重要な業務に 100%時間を使える状態を目指したいです。
おわりに
この記事では、2025 年 11 月現在の私のコーディングエージェント向けのコンテキストの作り方と、開発スピードを上げるための試行錯誤を紹介しました。自作のフレームワークですが誰かに使ってもらいたいモチベーションはなく、コンテキストエンジニアリングの事例として参考になれば幸いです。モデルの進化や環境の変化に伴い明日には大きく変わっているかもしれませんが、変化に追従しつつ自分に合ったコンテキストの作り方を模索していくつもりです。
落穂拾い
その他本筋ではないものの、最近コーディングエージェントとよくやる行動を紹介します。
- コーディングとレビューはセッションを分ける方が最終的な精度が出やすいです。「実装しながらセルフレビュー」は複数の観点を同時に取り組むことになり期待する結果が出づらいです。コンテキストをクリアした新しいセッションを開始し、フラットな視点からレビューだけしてもらうのをよくやっています。
- それをしやすくするために、PR に
devin-reviewというラベルを貼るとレビュー観点に従って検査した後そのまま改修を進める GitHub Actions ワークフローを用意しています。CodeRabbit なども精度は高いレビューが出ますが、人間がレビューする前に実装修正までやって欲しい、となると Devin などのクラウド型のコーディングエージェントは便利です。
- それをしやすくするために、PR に
- 同様にドキュメントワークもコーディングエージェントは長文を書きがちなので、「とにかく書く」と「情報量を維持し圧縮する」セッションは分けた方が良いです。自分はこんな感じの Claude Code Command を用意しています。 https://github.com/MH4GF/dotfiles/blob/7241a1de5a9cd397096c6889a25ab0cc271cfa55/.claude/commands/compact-docs.md