Claude CodeやCodexに作業を任せる前に、スペックファイルを3つ作成してください

AIコーディングエージェントを1週間以上使っていれば、こんな経験が必ずあるはずです。月曜日には完璧なコードが出てきたのに、火曜日には使い物にならないものが返ってくる。プロンプトはほぼ同じ。コードベースも変わっていない。なのに結果がまったく違う。

この問題を追い続けて、気づけば1年近く経っていました。より良いプロンプト、より詳細な指示、異なるモデル。いろいろ試しましたが、本質的な問題は何も解決しませんでした。本当の問題は、意図を伝えるための構造化された方法を持っていなかったことです。プロジェクトのルール、機能の要件、タスクの手順、コーディング規約、すべてをプロンプト1つに詰め込んでいた。それは単一の入力に課す重荷としては重すぎます。

解決策は、指示を3つのレイヤーに分けた3つのファイルに分割することでした。この変更を加えてから、セッション間の品質のばらつきはほぼなくなりました。

1つのファイルに何でも書くと破綻する理由

LLMの指示追従に関する研究では、「指示の呪い（Curse of Instructions）」と呼ばれるパターンが報告されています。単一のコンテキスト内の指示の数が増えると、個々の指示への遵守率が急激に低下するというものです¹。実際に試してみました。プロジェクトのルール、機能のスペック、タスクリストをすべて1つのCLAUDE.mdファイルに詰め込んだとき、エージェントは後半の指示のおよそ半分を無視しました。

アテンションの仕組みを考えれば納得できます。混在した関心事が詰まった長いドキュメントは、モデルにリアルタイムで「何が最も重要か」の判断を強いります。そのトレードオフは往々にして外れます。解決策は、各レイヤーが集中できるよう情報を役割で分離することです。

レイヤー1：プロジェクトの憲法としてのCLAUDE.md

CLAUDE.md（またはお使いのエージェントの同等ファイル）はすべてのセッションで自動的に読み込まれます。そのため、機能固有の指示を置く場所としては適していません。プロジェクト全体を通じて真実であることだけを書くべきです。

• ビルドコマンドと技術スタックのバージョン
• フォルダ構造と命名規則
• 「必ずやること」「先に確認すること」「絶対にやってはいけないこと」の3段階の行動ルール

このファイルに思いつく限りのことを最初から詰め込まないようにすることを学びました。代わりに、エージェントが繰り返しミスをする場所を観察し、ルールを段階的に追加していく方法が定着しました。最初から完璧な仕様を書こうとするより、ずっと効果がありました。

CLAUDE.mdに入れるべきでないものもいくつかあります。APIキー（古くなります）、コードスニペット（実際のコードから乖離していきます）、リンターがすでに強制するスタイルルール、そして特定の機能に固有のものはすべて次のレイヤーに属します。

レイヤー2：「何を」と「なぜ」のためのSPEC.md

スペックファイルは1つの機能を記述します。その機能が何をするか、なぜ存在するか、成功基準は何か、技術的な制約は何か、境界はどこかを答えます。それだけです。5つのセクションです。

従来のPRDとの決定的な違いは、スペックファイルは人間のレビュー会議のためではなく、エージェントが消費するために構造化されているということです。そして意図的に「どうやって」を省いています。実装はエージェントが既存のコードベースを分析して判断するべきであって、スペックのステップバイステップの指示に従うべきではありません。

良いスペックを書く方法は2つあります。上記の5セクション構造を使って自分で下書きするか、エージェントにインタビューさせるかです。インタビューのアプローチは、2つのルールを守れば驚くほどうまくいきます。一度に1つの質問、そして自由記述より選択式を優先する。その結果できるスペックは、1人で書いた場合に見落としていたエッジケースをカバーする傾向があります。

完成したスペックはdocs/specs/YYYY-MM-DD-topic.mdに保存してコミットしましょう。これによりエージェントがgit diffで追えるトレイルが生まれ、コードレビュアーが意図的な決定と偶発的なものを区別する手がかりにもなります。

レイヤー3：実行可能タスクのためのplan.md

プランファイルは最も狭いレイヤーです。スペックを2〜5分で完了できるタスクに分解し、明示的なファイルパスと固定された実行順序を持ちます。すべてのプランをTDDサイクルに固定しています。テストを先に書き、それをパスする最小限のコードを実装し、テストがパスすることを確認してからコミットする。

明示的なファイルパスは思っていた以上に重要です。なければエージェントはファイルの置き場所を推測し、その推測はセッションをまたぐと食い違います。パスを固定することでそのばらつきをなくせます。

品質を安定させたセッション分割

何ヶ月も気づけなかった部分がここです。3つのきれいなファイルが揃っていても、スペックを書いて同じセッションで実装を走らせると、品質は依然として劣化しました。理由は明快です。スペック作成中のブレインストーミングとQ&Aがコンテキストウィンドウの大部分を消費します。実装が始まる頃には、エージェントはすでに以前の決定を忘れ始めています。

修正は単純です。セッション1でSPEC.mdを書いて保存する。セッション2でスペックからplan.mdを生成する。セッション3以降でタスクを1つずつ実行する。コンテキストウィンドウがおよそ半分になった時点でも新しいセッションに切り替えます。精度の改善はすぐに実感できました。

これが向かう先

アジャイルマニフェストのチームは、エージェントベースのソフトウェア開発の成熟度モデルを発表しており、この階層的アプローチに対応しています²。

• レベル1：スペックを書いて実装し、スペックを捨てる
• レベル2：スペックをコードとともに進化する生きたドキュメントとして維持する
• レベル3：スペックが唯一の真実の源泉となり、コードは生成された成果物になる

話を聞いてきた開発者の多くは、まだレベル1にも達していません。プロンプトが唯一の入力でコードが唯一の出力というモードで動いています。小さなタスクならそれで通用しますが、複雑さが増すにつれて崩壊します。

レベル1からレベル2への移行は、たった1つの習慣です。スペックファイルをGitにコミットすること。レベル2からレベル3への移行はワークフローの変更です。コードを修正する必要があるとき、先にスペックを更新してから再生成する。

今日から始められます。プロジェクトの基本を記したCLAUDE.mdを作り、次の機能のSPEC.mdをコードに触れる前に書いて、何が起きるか確かめてみてください。違いは急速に積み重なっていきます。

Footnotes

1. He et al., “Instruction Following without Instruction Tuning,” NeurIPS 2024. https://arxiv.org/abs/2409.14254 ↩

2. Dave Thomas & Andy Hunt, “Agile Is Dead,” PragDave blog, 2014; extended agent maturity discussions at agilemanifesto.org community resources. ↩