AIエージェントのための良いスペックの書き方

 (addyosmani.com)
110 ポイント 投稿者 GN⁺ 2026-01-19 | 3件のコメント | WhatsAppで共有
  • AIコーディングエージェントに膨大な仕様を一度に投げても適切には機能せず、核心はスマートな仕様作成にある
  • まず高レベルのビジョンを提示し、AIに詳細計画を拡張させたうえで、Plan Modeで読み取り専用のまま計画をレビューし、その後コード作成段階へ移行する方式が推奨される
  • GitHubの2,500件以上のエージェント設定ファイルを分析した結果、効果的な仕様には Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries の6つの中核領域が含まれる
  • 大規模な作業は1つの巨大なプロンプトではなく、モジュール化された小さなタスクに分割し、そのタスクに必要なコンテキストだけを提供してこそ品質低下を防げる
  • 仕様に3段階の境界線（Always/Ask first/Never）、自己検証、適合性テストを組み込み、継続的にテスト・反復・進化させることが、仕様駆動開発ワークフローの核心

TL;DR

  • 適切な粒度の詳細情報（構造、スタイル、テスト、境界線など） を含む明確な仕様を書くこと
  • 大きな作業はひとかたまりのプロンプトではなく、小さな単位に分解する方式が推奨される
  • 計画はまず読み取り専用モードで立て、その後実行し継続的に改善する

核心原則: スマートな仕様を書く

  • 単に膨大な仕様をAIエージェントに投げるやり方は失敗しやすく、コンテキストウィンドウの制限とモデルの**注意予算（attention budget）**に突き当たる
  • 「スマートな仕様」 とは、エージェントを明確に導き、実用的なコンテキストサイズ内に収まり、プロジェクトとともに進化する文書を指す
  • Claude CodeやGemini CLIのようなコーディングエージェントの利用経験から得た原則を、フレームワークの形で整理している

原則1: 全体像を先に与え、詳細はAIに下書きさせる

  • 最初から過剰にすべてを設計しようとするより、まずは目標の記述といくつかの重要要件だけを明確にして始める
  • この初期仕様を**「プロダクトブリーフ」のように置き、エージェントがそれをもとに詳細仕様**を拡張して作成するよう任せる方式
  • LLMベースのエージェントは高レベルの指示が明確なときには詳細をうまく埋められるが、ミッションが曖昧だと簡単に脇道へそれる傾向がある
  • そのため重要なのは、エージェントが迷走しないよう最初に明確なミッションを打ち込んでおくこと

  • Plan Modeの活用

    • Claude CodeのPlan Modeは、エージェントを読み取り専用に固定し、コードベースの分析と詳細な計画立案だけを行わせるモード
    • Shift+TabでPlan Modeに入り、「何を作りたいのか」を説明すると、エージェントが既存コードを見渡しながら仕様の草案を作成する
    • このとき計画について、アーキテクチャ、ベストプラクティス、セキュリティリスク、テスト戦略まであわせて点検するよう求めることができる
    • 計画が誤解の余地なく十分に洗練されるまではPlan Modeを維持し、その後ではじめてPlan Modeを終了して実行段階に入る

  • 仕様をコンテキストとして活用

    • 確定した仕様は SPEC.md のようなファイルに保存し、作業時には必要なセクションだけを選んでエージェントに再度渡す
    • 仕様ファイルはセッションをまたいで残るため、プロジェクトを再開するときにもAIを同じ基準点に固定する役割を果たす
    • 会話履歴が長くなったりエージェントを再起動したりしたときに生じる忘却を減らす助けになる
    • チームでPRD（製品要求仕様書）を共有基準として使うのと同じように、人間でもAIでも誰もが参照する「単一の基準文書」として機能する

  • 目標志向を維持

    • 高レベル仕様は最初から実装方法をすべて書くのではなく、what/whyに集中し、具体的なhowは後ろに回す構成が適している
    • ユーザーストーリーと受け入れ基準のように構成する: 「ユーザーは誰か？ / 何が必要か？ / 成功した状態とは？」
    • GitHub Spec Kitでも、「何を、なぜ作るのかについて高レベルの説明を与え、コーディングエージェントがユーザー体験と成功基準を中心に詳細仕様を作る」という流れが強調されている

原則 2: スペックを専門的な PRD（または SRS）のように構造化する

  • AI 向けスペックを単なるメモの寄せ集めではなく、明確なセクションを備えた構造化ドキュメントとして扱うことが重要
  • PRD やシステム設計文書のように包括的で整った形式は、内容を文字通りに解釈する AIに特によく適している
  • GitHub で 2,500 件以上のエージェント設定ファイルを分析した結果、効果的なスペックには共通して6 つの中核領域が含まれていた

    • 1. Commands

      • 実行可能なコマンドを文書の前半に配置する
      • ツール名だけでなく、フラグを含む完全なコマンドを明記する: npm test, pytest -v, npm run build

    • 2. Testing

      • テストの実行方法、使用するフレームワーク、テストファイルの場所、期待するカバレッジ水準を具体的に明記する

    • 3. Project Structure

      • ソースコード、テスト、ドキュメントの場所を明確に区別する
      • 例: 「src/ はアプリケーションコード、tests/ は単体テスト、docs/ はドキュメント用」

    • 4. Code Style

      • スタイルを冗長に説明するより、実際のコードスニペットを 1 つ示すほうがはるかに効果的
      • 命名規則、フォーマット基準、望ましい出力例をあわせて提示する

    • 5. Git Workflow

      • ブランチ命名規則、コミットメッセージ形式、PR 要件を明記すると、エージェントもその流れに従う

    • 6. Boundaries

      • エージェントが絶対に触れてはいけない領域を明確に指定する
      • シークレット、vendor ディレクトリ、本番設定、特定フォルダなど
      • GitHub の調査では、**「シークレットを絶対にコミットしないこと」**が最も頻出した有用な制約として確認された

  • スタックを具体的に明記する

    • 「React プロジェクト」のように大まかに書くのではなく、**「React 18 + TypeScript + Vite + Tailwind CSS」**のように具体的に記すことが重要
    • バージョンと主要な依存関係もあわせて記載すべきであり、曖昧なスペックは結局曖昧なコードを生む

  • 一貫した形式を使う

  • スペックをツールチェーンに統合する

    • スペックを単なる文書ではなく、バージョン管理や CI/CD に接続された**「実行可能なアーティファクト」**として扱う
    • GitHub Spec Kit は、スペックをエンジニアリングプロセスの中心に据える4 段階のゲートワークフローを採用している
      • Specify: 何を、なぜ作るのかという高水準の説明を提供し、コーディングエージェントが詳細仕様を生成する
      • Plan: 望ましいスタック、アーキテクチャ、制約条件を含む技術計画を策定する
      • Tasks: スペックと計画を実際の作業単位に分割し、それぞれをテスト可能なサイズまで細分化する
      • Implement: コーディングエージェントがタスクを 1 つずつ、または並列に処理する

  • agents.md による専門化されたペルソナ

    • GitHub Copilot のようなツールでは、専門化されたエージェントペルソナを定義できる
    • @docs-agent（技術ドキュメント）、@test-agent（QA）、@security-agent（コードレビュー）のように役割を分けられる
    • 各 agents.md ファイルは、そのペルソナの振る舞い、コマンド、境界を収めた集中型スペックとして機能する

  • Agent Experience（AX）の設計

    • API を開発者体験（DX）に合わせて設計するように、スペックも**エージェント体験（AX）**を考慮して設計する必要がある
    • 重要なのは、整理されていてパースしやすい形式であること
      • エージェントが利用する API の OpenAPI スキーマ
      • LLM 向けドキュメント要約（llms.txt）
      • 明示的な型定義
    • MCP（Model Context Protocol）のような標準に従ったスペックほど、エージェントはより安定して理解し、動作できる

  • 生きた文書として維持する

    • スペックは一度書いて終わりの文書ではなく、AI とともに意思決定を行ったり、新しい事実が明らかになったりするたびに継続的に更新する
    • スペック駆動ワークフローでは、スペックが実装、テスト、タスク分解を主導し、スペックが検証されるまでは次の段階に進まない
    • このスペックは AI だけのための文書ではなく、開発者が全体の流れを監督し、AI の成果物が実際の要件を満たしているかを確認するための中核ツールでもある

原則 3: タスクをモジュール化されたプロンプトとコンテキストに分割

  • 1つの巨大なプロンプトにすべてを詰め込むより、一度に1つのタスクだけに集中できるようコンテキストを与える
  • プロジェクト全体の要件・コード・指示を単一のプロンプトに盛り込むと、かえって混乱を招きやすい
  • トークン制限に引っかかるリスクだけでなく、「指示の呪い(curse of instructions)」 によってモデルの集中力が急激に低下する可能性がある

  • 指示の呪い

    • 研究結果によれば、プロンプトに指示やデータを多く積み重ねるほど、各指示に正確に従う性能が 目に見えて低下 する
    • GPT-4 や Claude のような強力なモデルでも、多くの要件を同時に満たすよう求められると苦戦する
    • たとえば詳細なルールを10個の箇条書きで与えると、最初の数個だけ守り、後ろのルールは徐々に無視する傾向が見られる
    • より良い戦略は 反復的な集中: 一度に1つの下位問題だけに集中させ、終わったら次の問題へ進む方式

  • スペックを段階またはコンポーネントに分割

    • スペック文書が長い、または扱う範囲が広いなら、複数の部分に分けることを検討する
    • 例: 「Backend API Spec」と「Frontend UI Spec」を別々のセクションに分離
    • バックエンド作業をするとき、フロントエンドのスペックを常に一緒に渡す必要はない
    • マルチエージェント環境では、各領域ごとに別個のエージェントや下位プロセスを置くこともできる
    • DigitalOcean AI ガイドでも「認証タスクとデータベーススキーマ変更を一度に混ぜるな」と警告している

  • 大規模スペックのための拡張 TOC/要約

    • エージェントに、まずスペック全体を要約した 拡張目次(TOC) を作成させる方法
    • 各セクションをいくつかの重要ポイントやキーワードに圧縮し、詳細内容がある場所も併せて参照する
    • 例: 「Security: HTTPS の使用、API キー保護、入力検証の実装（詳細はスペック全体の §4.2 を参照）」
    • このように階層的な要約を用意しておけば、プロンプトには全体像だけを維持し、詳細は必要なときだけ提供できる
    • 拡張 TOC は一種のインデックスとして機能し、エージェントが「なるほど、セキュリティのセクションがある」と認識してその部分を要求できるようにする
    • このような 階層的要約方式 は、LLM が高レベルの構造を維持するのに役立つ

  • サブエージェントまたは「スキル」の活用

    • Anthropic がいうサブエージェント（または「スキル」）のように、役割を分離した複数エージェントを活用できる
    • 各サブエージェントは特定の専門領域に合わせて設定され、その領域に該当するスペックの一部だけを受け取る
    • 例: Database Designer サブエージェントはデータモデルのセクションだけ、API Coder サブエージェントは API エンドポイントのスペックだけを認識する
    • こうすることで各エージェントはより小さいコンテキストとより明確な役割を持ち、精度向上と並列作業 が可能になる
    • Claude Code は、独自のシステムプロンプトとツールを持つサブエージェントを定義する機能をサポートしている

  • スループットのための並列エージェント

    • 複数のエージェントを同時に動かす方法が、開発者生産性の次の段階として注目されている
    • 1つのエージェントが終わるのを待たず、互いに重ならない作業へ並列にエージェントを投入する
    • Simon Willison はこれを 「並列コーディングエージェントを受け入れること」 と表現し、驚くほど効果的だが精神的にはかなり疲れる と述べている
    • 重要なのは、エージェント同士が互いの作業を妨げないようにタスク範囲を明確に分けること
    • LangGraph や OpenAI Swarm のようなオーケストレーションフレームワークがこの調整を助け、
    • Chroma のようなベクターデータベースを共有メモリとして使えば、重複したプロンプトなしに共通コンテキストへアクセスできる

  • 単一 vs マルチエージェント: いつ使うべきか

    側面 単一エージェント 並列/マルチエージェント
    長所 設定が単純でオーバーヘッドが低く、デバッグとフロー追跡がしやすい スループットが高く、複雑な相互依存への対応やドメインごとの専門化が可能
    短所 大規模プロジェクトではコンテキスト過負荷、反復速度の低下、単一障害点 調整コストの増加、衝突の可能性、共有メモリが必要
    適したケース 分離されたモジュール、中小規模プロジェクト、初期プロトタイピング 大規模コードベース、コーディング・テスト・レビューの分離、独立した機能開発
    ヒント スペック要約を活用、タスクごとにコンテキスト更新、セッションを頻繁にリセット 初期は 2〜3 個のエージェントに制限、MCP でツール共有、境界を明確化

  • 各プロンプトを1つのタスク/セクションに集中

    • 複雑なマルチエージェント環境がなくても、手動で十分にモジュール性を強制できる
    • 例: スペック作成後、「Step 1: データベーススキーマ実装」の段階ではスペックの Database セクションだけを提供
    • 主要タスクが変わるたびにコンテキストを組み直し、古い情報や関係のない情報による気の散りを減らす
    • 一部のガイドでは、主要機能の切り替え時に 新しいセッションを開始 してコンテキストを整理するよう勧めている

  • インライン指示文とコード TODO の活用

    • コードに // TODO コメントとしてやるべきことを書いておき、エージェントに1つずつ埋めさせる方法
    • 各 TODO が小さなタスクに対する ミニスペック の役割を果たす
    • その結果、AI は「このスペックスニペットに合わせてこの関数だけを実装せよ」というように、非常に狭い範囲へ集中できる

原則4: 自己チェック、制約条件、人間の専門性を組み込む

  • スペックを単なるエージェントのToDoリストではなく、品質を管理するガイドとして扱い、自分の専門性を積極的に反映すること
  • 良いスペックは、AIがどこでミスしうるかをあらかじめ指摘し、その地点にガードレールを設けておく
  • ドメイン知識、エッジケース、各種「注意事項」を盛り込み、AIが文脈のない真空状態で動作しないようにする
  • スペックをAIのコーチ兼審判だと考えると理解しやすい。正しいアプローチは導き、誤った行動には即座にブレーキをかける
  • GitHubの2,500件以上のエージェントファイル分析結果によると、最も効果的なスペックは単なる禁止事項の一覧ではなく、3段階の境界システムを使っている
    • エージェントがいつそのまま進めてよいのか、いつ立ち止まって尋ねるべきか、いつ完全に中止すべきかを明確に伝える

    • ✅ Always do（常に実行）

      • 確認せずに実行すべき作業
      • 例: 「コミット前には常にテストを実行する」「スタイルガイドの命名規約を常に守る」「エラーは常に監視サービスにロギングする」

    • ⚠️ Ask first（先に確認すること）

      • 人間の承認が必要な作業
      • 例: 「データベーススキーマを変更する前に確認すること」「新しい依存関係を追加する前に確認すること」「CI/CD設定を変更する前に確認すること」
      • 技術的には可能でも、影響範囲が大きく人間の判断が必要な変更をここでふるいにかける

    • 🚫 Never do（絶対禁止）

      • 明確なハードストップ領域
      • 例: 「シークレットやAPIキーは絶対にコミットしない」「node_modules/やvendor/は絶対に編集しない」「明示的な承認なしに失敗しているテストを削除しない」
      • 調査でも**「シークレットを絶対にコミットしないこと」**が最も頻出する有用な制約として確認された

  • 自己検証を促す

    • エージェントがスペックに照らして自ら結果を点検するよう促す
    • ツールが許可されているなら、コード生成後に単体テストやlintを自分で実行するようワークフローに含める
    • プロンプトレベルでも再確認を指示できる
      • 例: 「実装後、結果をスペックと比較してすべての要件を満たしているか確認し、未達の項目があれば列挙せよ」
    • LLMが自身の出力をスペックと照合するようにして、漏れを減らす効果がある

  • 主観的な検査のためのLLM-as-a-Judge

    • コードスタイル、可読性、アーキテクチャパターン遵守のような自動化しにくい基準には、LLM-as-a-Judgeアプローチを活用する
    • 2人目のエージェント（または別プロンプト）が、1人目のエージェントの出力をスペックの品質基準に照らしてレビューする
    • 例: 「このコードが我々のスタイルガイドに準拠しているかレビューし、違反箇所を示せ」
    • 審判役のエージェントがフィードバックを返し、それを反映したり修正のきっかけとして使う

  • 適合性テスト

    • Willisonは**適合性スイート（conformance suite）**の構築を推奨している
    • 言語に依存しないテスト（しばしばYAMLベース）で、すべての実装が必ず通過すべき契約として機能する
    • APIを作る場合、適合性スイートが期待される入力と出力を定義し、エージェントが作成したコードはそのすべてを満たさなければならない
    • スペックのSuccessセクションに「conformance/api-tests.yamlの全ケースに合格必須」のように基準を明記する

  • スペックでテストを活用する

    • 可能なら、スペックやプロンプトの流れにテスト計画または実際のテストを直接含める
    • TDDのように、テストケースで要件を明確にする
      • 例: Success Criteriaに「このサンプル入力は必ずこの出力を生成しなければならない」と書く
    • Willisonは堅牢なテストスイートがエージェントに事実上のスーパーパワーを与えると表現している
    • テストが失敗したときに即座に検証して反復できるためだ
    • サブエージェント構成では、スペック基準を受け取ってコード出力を継続的に検証する専用のテストエージェントを置くこともできる

  • ドメイン知識を反映する

    • スペックには、経験のある開発者や文脈を知る人だけが持っている現実的な洞察を盛り込むべきだ
    • 例: EC向けエージェントを作るとき、「products」と「categories」が多対多の関係にあることを明記しておく
      • AIが自力で推論してくれると期待しない
    • 特定のライブラリが扱いづらいなら、よくある落とし穴や注意点もあわせて明記する
    • 自分のメンタリングをスペックに溶け込ませるやり方
      • 例: 「ライブラリXを使う場合、バージョンYではメモリリークの問題があるため回避策Zを適用する」

  • 簡単なタスクにはミニマリズムを

    • 徹底したスペックは重要だが、専門性の一部はいつシンプルにすべきかを知ることにもある
    • 比較的単純で隔離された作業では、過剰なスペックがかえって混乱を増やすことがある
    • 例: 「ページ内でdivを中央揃えにする」のような作業なら
      • 「解決策は簡潔に保ち、不要なマークアップやスタイルを追加しないこと」程度で十分だ
    • 逆に「トークン更新とエラーハンドリングを含むOAuthフローを実装する」のような複雑な作業には、詳細なスペックが必要になる
    • 経験的な基準は、タスクの複雑さに合わせてスペックの密度を調整することだ

  • 人間を最終品質フィルターとして維持する

    • スペックはエージェントに権限を委譲するが、最終的な品質責任は開発者にある
    • エージェントが技術的にはスペックを満たしていても、感触や文脈が合わないなら自分の判断を信頼する
    • 必要であればスペックを再度磨き込んだり、成果物を直接手直ししたりするのも自然なプロセスだ
    • WillisonはAIエージェントと働くことを「非常に奇妙な形のマネジメント」であり、「人間のインターンを管理することと不快なくらい似ている」とたとえている
    • 結局のところ、明確な指示（スペック）、十分なコンテキスト、実行可能なフィードバックを与える役割は、依然として人間のものだ

原則 5: テスト、反復、スペックの進化（適切なツール活用）

  • スペック作成とエージェント構築を一度きりで終わる作業ではなく、反復ループとして捉える
    • 素早くテストし、フィードバックを集め、スペックを磨き、ツールで検査を自動化する流れ
  • 初期スペックは完成版ではなく、サイクルの出発点

  • 継続的テスト

    • すべての実装が終わるまで待たず、主要なマイルストーンや関数単位でテストまたは簡単な手動確認を行う
    • 失敗が見つかったらそのまま進めず、まずスペックやプロンプトを修正する
    • 自動テストは特に効果的で、テストがあるならエージェントに npm test のようなコマンドを直接実行させられる
    • テスト失敗の結果をそのまま次のプロンプトの入力として使う
      • 例: 「出力が X、Y、Z でスペックを満たしていないので修正せよ」
    • コード → テスト → 修正 → 反復へとつながるエージェント的ループは非常に強力な方法

  • スペック自体の反復

    • エージェントが誤解したり、要件の欠落が明らかになったりしたなら、問題を覆い隠さず、まずスペック文書を修正する
    • 修正したスペックをエージェントと明示的に再同期する
      • 例: 「スペックを次のように更新した。この変更を反映して計画を調整するか、コードをリファクタリングせよ」
    • スペックを常に単一の信頼できる情報源として維持する
    • 可能ならコミットメッセージやノートでバージョン履歴を残し、何がなぜ変わったのかを追跡する

  • コンテキスト管理とメモリツールの活用

    • AIエージェントのコンテキストと知識管理を助けるツールエコシステムが急速に成長している
    • **RAG（検索拡張生成）**パターンを活用すると、エージェントはベクターデータベースのような知識ベースから必要な情報だけを即座に取得できる
    • スペックが非常に大きい場合は、セクションを埋め込みしておき、エージェントが全文を受け取る代わりに最も関連の高い部分だけ検索するように構成する
    • **MCP（Model Context Protocol）**ベースのフレームワークは、現在のタスクに合ったコンテキストを自動で提供する
    • Context7(context7.com) のようなツールは、作業中の内容に応じて文書から関連スニペットを自動で読み込む

  • 慎重な並列化

    • 一部の開発者は、複数のエージェントインスタンスを異なるタスクに並列実行して速度を高めている
    • 例: あるエージェントがコード生成を行い、別のエージェントが同時にテストを書く
    • この方法を取る場合、衝突を避けるためにタスクが本当に独立しているか、明確に分離されている必要がある
    • 例: 2つのエージェントが同時に同じファイルを修正しないよう制限する
    • 管理負荷を減らすため、初期段階では最大 2〜3 個のエージェントから始めるのが現実的

  • バージョン管理とスペックの固定

    • Git のようなバージョン管理ツールでエージェントの作業を丁寧に追跡する
    • AIを活用するほど、良いバージョン管理習慣 の重要性はさらに高まる
    • スペックファイル自体をリポジトリにコミットして変更履歴を残す
    • エージェントも git diff や blame を読み、変更の文脈を理解できる
      • 実際、LLM は diff の解釈にかなり長けている
    • スペックをリポジトリに置けば、開発者とAIの両方がプロジェクトの進化を一緒に追跡できる
    • Willison はモデルが「Gitに猛烈に有能だ」と表現している

  • コストと速度の考慮

    • 大規模モデルと長いコンテキストを使う作業は、遅く高コストになり得る
    • モデル選択を戦略的に分ける
      • 初期ドラフトや反復作業には高速で安価なモデル
      • 最終出力や複雑な推論には最も有能な（高価な）モデル
    • 例: GPT-4 や Claude は計画立案と重要な段階に、単純な拡張やリファクタリングはローカルモデルや小型APIモデルに任せる
    • テスト実行エージェントやリンターエージェントは、比較的小さなモデルでも十分
    • コンテキストサイズも管理対象

  • すべてを監視し、ログを取ること

    • 複雑なエージェントワークフローでは、エージェントの行動と出力のログが必須
    • ログによって、エージェントが意図から外れたか、エラーが発生したかを確認できる
    • 多くのフレームワークはトレースログを提供するか、段階ごとの思考過程を出力するよう支援している
    • ログを見れば、スペックや指示がどこで誤って解釈されたのかが明らかになる

  • 学習と改善

    • 各プロジェクトを、スペック作成能力を磨く学習の機会とする
    • 特定の表現が繰り返しAIを混乱させるか、どのようなスペック構造のほうがよく守られるかを観察できる
    • そうした教訓を次のスペックに積極的に反映する
    • AIエージェント分野は急速に進化しており、新しいツールやベストプラクティスが継続的に登場している

よくある失敗を避ける

  • GitHub 上の 2,500 件以上のエージェントファイルを分析した結果、失敗の最大の原因はスペックと指示が過度に曖昧であることだった

  • 曖昧なプロンプト

    • 「すごいものを作って」「もっとよく動くようにして」といった依頼では、エージェントに判断基準そのものがない
    • 入力、出力、制約条件をできるだけ具体的に明示する必要がある
    • 「あなたは役に立つコーディングアシスタントです」のような一般的な役割指定はほとんど効果がない
    • 逆に「あなたは React コンポーネントテストを書くテストエンジニアであり、この例に従い、ソースコードは決して変更しない」のように役割・範囲・制約をまとめて指定すると、はるかによく機能する

  • 要約のない過剰なコンテキスト

    • 50ページの文書をそのままプロンプトに流し込み、モデルが勝手に理解してくれると期待するやり方はたいてい失敗する
    • 階層的要約や RAG を活用し、今のタスクと直接関係する内容だけを浮かび上がらせる必要がある
    • コンテキスト長を増やしても、コンテキストの質の不足を補うことはできない

  • 人間によるレビューの省略

    • Willison の個人的原則: 「他人に説明できないコードはコミットしない」
    • エージェントがテストを通る何かを作ったからといって、そのコードが直ちに正確で安全で保守可能だという意味ではない
    • 特に重要なコードパスは常に人が直接レビューする
    • AI生成コードは見た目には堅牢でも、未テストのエッジケースで崩れることがあるという点で、「トランプの家」という比喩がよく当てはまる

  • バイブコーディングとプロダクションエンジニアリングの混同

    • AIを活用した高速プロトタイピング、いわゆる「バイブコーディング」は探索段階や単発プロジェクトに向いている
    • 厳格なスペック、テスト、レビューなしにその成果物をそのまま本番にデプロイすると、問題が発生する可能性が高い
    • 「バイブコーディング」と「AI支援エンジニアリング」は明確に区別すべきであり、後者にはこのガイドで説明した規律と手順が必要
    • 今どのモードで作業しているのかを自覚することが重要

  • 「致命的な三重奏」を無視する

    • Willison が警告する、AIエージェントを危険にする 3 つの特性
      • 速度: 人がレビューできる速度を超えて結果を生成する
      • 非決定性: 同じ入力でも実行ごとに異なる出力になる
      • コスト: 十分な検証よりも近道を選ぶよう誘導する
    • スペックとレビューのプロセスは、この 3 つすべてを前提に設計されなければならない
    • 特に、速度が検証能力を上回らないよう意識的な制御が必要

  • 6つの重要領域の欠落

    • スペックが Commands、Testing、Project Structure、Code Style、Git Workflow、Boundaries を扱っていないと、エージェントは作業に必要な重要情報を見落としやすい
    • エージェントに渡す前に、6つの領域チェックリストでもう一度確認するのが安全

結論

  • AIコーディングエージェントのための効果的なスペック作成には、堅実なソフトウェアエンジニアリング原則とLLMの特性を理解し、それに合わせて調整するアプローチの両方が必要
  • すべては目的を明確に定めることから始まり、その上でAIが計画と詳細を拡張するように役割分担する
  • スペックはメモではなく本格的な設計文書として扱うべきであり、6つの中核領域を含み、ツールチェーンと連携した実行可能なアーティファクトとして扱う
  • 一度にすべてを与えるのではなく、作業単位ごとに分けて提供し、エージェントの集中を維持する
    （要約TOC、サブエージェント、並列オーケストレーションは大規模なスペックを扱うための実践的な手段）
  • 3段階の境界線（Always / Ask first / Never）、自己チェック、適合性テストを通じて、AIが陥りやすい落とし穴をあらかじめ防ぐ
  • スペックと実装を固定された成果物ではなく反復プロセスとして扱い、テストとフィードバックを通じてスペックとコードを継続的に磨いていくことが重要
  • このガイドラインに従えば、AIエージェントが大規模なコンテキストの中で方向を見失ったり、でたらめに陥ったりする可能性を目に見えて減らせる

関連記事

3件のコメント

 
gomjellie 2026-01-22

AI翻訳ではありますが、日本語訳版があるのでリンクを共有します。

https://rosetta.page/post/…
 
qor0923 2026-01-20

ありがとうございます。
 
googol 2026-01-19

個人的に、SDD（Specs Driven Development）でプロジェクトを開発したとき、最初は確かな生産性向上を感じましたが、まだすべてのコードをスペックベースで書けるわけではなく、直接修正が必要になるたびにコードとスペックを一緒に更新しなければならないため、かえって生産性が低下する経験をしました。