個人で仕様駆動開発とcc-sddを試していたら、コンテキストエンジニアリングの問題に遭遇した話

AI やってみた

こちらは プレセナ・ストラテジック・パートナーズ Advent Calendar 2025 3日目の投稿です！プレセナのソフトウェアエンジニアの大西です。今回は cc-sdd を使った仕様駆動開発を個人的に挑戦してみたので、そのまとめを書いていきます！

TL;DR

  • AIエージェント(Claude Code)と仕様駆動開発ツール（cc-sdd）を使い個人開発するなかで、いろいろ試行錯誤をしました。
  • AI同士にレビューと修正をさせていましたが、自動化できず、エージェント間連携を手動で行なっていた。レビューと修正のラリーが続くと作業がしんどかったです。取り組み自体は悪くはなかったので、自動化などの改善の余地がありそうです。
  • AIにTDDを担わせられる安心感があり、設計の網羅性は向上しましたが、ドキュメントが肥大化し「コンテキスト腐敗(Context Rot)」が発生しました。コンテキストエンジニアリングの重要性に気づきました。
  • 当たり前ですが、AIの成果物はコンテキストの質に左右されます。コンテキストエンジニアリングの原則である分割・索引・圧縮・追跡を前提に「コンテキスト設計」を組み込むべきだと思いました。

はじめに：なぜSDD・cc-sddに取り組んだか

きっかけは個人で開発していたプロジェクトの挫折でした。

思いついたアイデアで vibe coding 的にサクサク進めていたのは良かったですが、少し難しい技術的課題をAIが自分で解決することができなくなりました。人間（私）が介入するしかなくなりましたが、もはやAIに任せきりだったためコードの全体像や設計意図をキャッチアップするのが困難となり、結果、プロジェクトを断念しました。
実装する前には都度 task を作って Plan モードで計画させていたつもりでしたが、どこかで破綻したようです。

そこでAIに全部任せて実装させるなら、もはや設計やログやADRなども全て文書にすればいいんじゃないかと考え、仕様駆動開発に辿り着きました。

SDDといえばAWSが提供しているIDEの Kiro が有名ですが、私はすでに課金していた Claude Code や CodeX 等のエージェントを活用したいと考えました。そこで見つけたのが、有志が開発した Claude Code カスタムコマンド群である cc-sdd です。

みなさんご存知の通り、コーディングエージェントの登場により実装・開発のプロセスは変わりました。

アジャイルソフトウェア開発宣言には、包括的なドキュメントよりも動くソフトウェアに価値をおく、と書かれています。この部分がAIエージェントの登場によってドキュメントの作成・運用コストが劇的に下がった今、この前提は変わるのかもしれません。

本記事では cc-sdd を触る中で、そもそもSDDとはなにか、どういうふうに進むのか、それがどう開発に影響していくのかを紹介できればと思います。

想定読者

  • 仕様駆動開発(SDD: Spec‑Driven Development) をまだ知らない・知っているが具体的にどういうふうに進めているか知りたい方
  • SDDをやる前に、こうやった方がいいかも？を知りたい方

一文で「仕様駆動開発とは」

  • 簡単に言うと、「仕様書（設計図）から、コードやテストなどをAIに自動で作らせる」という開発のやり方です

🤔 What is Spec-Driven Development?
For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.
from : https://github.com/github/spec-kit

SDDとcc-sddの概要

今回の開発プロセスを理解する上で、中心となる2つの概念「SDD」と「cc-sdd」について説明します。

SDD は、その名の通り「仕様（Spec）」を開発の中核に据え、仕様書を正として設計、実装、テストを進める開発スタイルです。

設計、実装、テスト、ドキュメントなど、開発の全工程がこの「仕様書」という羅針盤に従って進められます。仕様書が更新されれば、それに合わせてコードやテストが変更されますし、コードを変更したい場合は、まず仕様書を更新することから始めます。

要するに『仕様を中心に据えて、そこから実装・テストを生成する』という感じで、開発を進めます。

cc-sdd (Claude Code - SDD) は、このSDDの思想を、AIエージェントである Claude Code のカスタムコマンド（/kiro:系）を使って実践するための、具体的な運用プロジェクト（またはその思想）を指します。

npx でインストールできますが、中身は Claude Code などコーディングエージェントのカスタムコマンド群です。

他の仕様駆動開発ツールとして、GitHub公式の Spec Kit なども存在します。

🔎用語早見表

  • vibe coding : 「vibe coding（バイブコーディング）」とは、AIに自然言語で指示を出し、AIがコードを生成する開発手法です。厳密な設計にこだわらず、直感的な「雰囲気」や「流れ」を重視しながら、AIとの対話を通じて開発を進めます。
  • SDD : 仕様書を正とし、設計→実装→テストを一気通貫させる開発手法。
  • cc-sdd : SDD をClaude Codeカスタムコマンドで実現する運用プロジェクト。

ツールと役割分担

AIエージェントは「適材適所」が鍵です。私は以下のように役割分担させました。

  • Claude Code (Haiku/Sonnet): 計画・設計・実装のメイン担当。
  • CodeX : Claude Code と同じく コードベース全体を認識できるため、Plan（実行計画）や実装のレビューに使いました。Claude Code の実行計画をコピペし、レビュー用プロンプトで検証させます。VS Code のIDE拡張機能でチャット形式でしてくれるのも良い点です。
  • ChatGPT Desktop / Gemini Pro : 第三者的な視点でのレビューで使います。Deep Research 機能を使って要件や設計の妥当性チェックや「壁打ち」相手になってもらいます。cc-sdd のプロセスでいくつかドキュメントが生成されるので、それを丸ごとコピペして評価させます。
  • Claude Opus: 高コスト・高性能モデル。リソース（予算）の枯渇を防ぐため、複雑な「設計(Design)」と「validate（検証）」フェーズに限定して投入します。

cc-sddの実務導線：コマンドと成果物

cc-sdd では、まずプロジェクト全体の指針として Steering Documents を定義します。これはプロジェクトの憲法であり、技術スタック（ tech.md ）、設計原則（ design.md ）、開発原則（ principle.md ）などをAIと人間が共有するために記述します。「ステアリング（Steering）」＝「舵取り」という名前の通り、AIと人間（開発者）の両方が従うべき「北極星」のような役割を果たします。AIが迷った時や、開発者が技術選定で悩んだ時に立ち返るべき指針がここに書かれます。

その上で、開発する「機能（feature）」ごとに Spec を作成して管理をします。この Spec が、要件・設計・タスクのドキュメント群を格納する単位となります。

開発の大まかな流れとしては、「要件 → 設計 → タスク化 → 実装 → 差分検証 → ステアリング更新」となります。 cc-sdd ではClaudeCodeのカスタムコマンドを使うことでAIに作業をお願いすることで、現在の作業ステータスが管理され、次に何をすべきか？が一目でわかるようになっております。また、コマンドの完了時に「次はこのコマンドを打ちましょう」というガイドが出るのも良いです。

コマンド早見表

# プロジェクト全体の指針を定義・更新。Steering Documentsの作成  
/kiro:steering

# 機能のSpecsテンプレートを生成  
/kiro:spec-init <機能の一言説明>

# 要件定義 (requirements.mdが生成される)  
/kiro:spec-requirements <機能スラッグ>

# 要件の妥当性チェック (自作コマンド) 
/kiro:validate-requirements

# 設計 (design.mdが生成される)  
/kiro:spec-design <機能スラッグ> 

# 設計の妥当性チェック  
/kiro:validate-design <機能スラッグ> 

# タスク作成・分解 (tasks.md)  
/kiro:spec-tasks <機能スラッグ>

# (自作コマンド) タスク妥当性チェック  
/kiro:validate-tasks  <機能スラッグ> 

#  実装 (Plan \-\> Execute)  
/kiro:spec-impl <タスク番号>

# (任意) 既存コードとの実装の差分検証  
/kiro:validate-gap <機能スラッグ>

開発フェーズ別のモデルや指示の使い分け

AIの性能を引き出すには、フェーズごとに指示やフローを意識的に変える必要がありました。

要件定義・設計フェーズ

  • AIの「解像度」を最大にするため、粒度を細かくします。validate系コマンドと Opus を使い、設計の妥当性を高めます。
  • 特に要件定義ではEARS (Easy Approach to Requirements Syntax) が採用されており、自然言語の曖昧さを排除されています。
（参考）EARS
  • フォーマット: WHEN \<イベント> THEN \<システム> SHALL \<振る舞い>
  • 例: WHEN ユーザが「保存」を押す THEN システム SHALL 下書きを5秒以内に永続化

実装フェーズ

  • /kiro:spec-implでPlanを立てさせます。このPlanをレビュー（前述）し、OKならExecute。タスクが完了したら即座にドキュメント（Steering や design.md）を更新させ、仕様と実装の一貫性を保ちます。実装自体はTDDで進めてくれます。

やって良かったこと・ だめだったこと

やって良かったこと

CodeX でクロスレビューさせ、Opusはすぐ使い切るため設計・検証フェーズに限定しました。また実装の前にスケルトン実装を行わせたり、validate系コマンドを拡張したり、文書整備サブエージェント(docs-gardener)で対処しました。

  • AIによるTDDの徹底:
    • cc-sdd では、TDDを実践するよう組まれており、テストコードを書いてくれるため、コード品質に対する心理的ハードルが下がります。
    • ただ実装が進んでいくにつれて動作確認でバグが出てくることがあり、「これって本当に有効なテストなんだろうか？」みたいなことも多々ありました。そのあたりは注視しなければいけないポイントだと思います。
  • AIクロスレビュー:
    • CodeX（コードベース参照可）やChatGPT（ドキュメントをコピー＆ペースト）にレビューさせました。（詳細は後述）
  • スケルトン先行開発:
    • TDDでも特に関数とモックを先行させて全体像を作ってもらいました。
    • 加えて、UMLやクラス図で全体像を作ってもらいました。
  • 「コンテキストエンジニアリング」への到達: これが最大の収穫です（後述）。

AIクロスレビューについて

  • CodeX は VS Code の拡張機能もあり、コードベースの閲覧をしてもらいながらチャット形式での対話ができます。もちろん実装もしてくれます
  • ChatGPT にドキュメントをまるごと読ませてレビューさせる
  • 一方で、そのレビュー結果を Claude Code に戻すと、結構指摘を鵜呑みにしてしまうので、次のようなプロンプトを最初に挟むようにしました
    • 「あなたは優秀なプログラマーです。
    • 下記の指摘は本当ですか？懐疑的・批判的に確認してください。
    • 本当に必要で取り入れるべきだと判断できる指摘の場合のみ、取り入れてください。
    • 改善できたら良い、程度のものは無視して良いです。」
  • CodeX のレビューが厳しくて、 Claude Code とのラリーが続くこともありました。間に挟まれる人間の気持ちになりつつ、MVPでやるならそこまでやらなくても…、みたいな指摘もありましたが、今後破綻する可能性をほのめかしてきたので泣く泣く従ったりすることもありました。
  • ClaudeCode が指摘を素直に鵜呑みにしたり、CodeX とのやりとりが続いたこともあり、プロンプトを調整してみたところ健全なやりとりになったように思います。
    • 実装レビュー時
      • 「致命的な欠陥・対応が必須な課題がないか精査してください。改善できたら良い程度のものは無視して良いです。」
    • 指摘の受け入れ時
      • 「下記の指摘は本当ですか？あなたは優秀なプログラマであり、懐疑的・批判的に確認してください。本当に必要で取り入れるべきだと判断できる指摘の場合のみ、取り入れてください。改善できたら良い、程度のものは無視して良いです。」

だめだったこと

  • 終わらない設計とレビュー
    • 初日は実装せず、6時間くらいAIと設計タスクをしていました。AI レビューを挟むと、その往復でさらに時間が膨らみます。それでも人間がやるよりは早いと思ってしまいました。
  • ドキュメントの肥大化
    • 実装も進んでいき、いろんな技術的課題に遭遇していくにつれて、.mdファイルやタスクが増殖していきました。タスク番号が 10.1.2 のようにマイナーバージョンまで細分化し、一機能がなかなか終わらないようになりました。
  • 並列作業
    • タスクの依存関係を整理し並列で進めることで、2枠、多い時は3枠とかでやっていたのですが、コンテキストスイッチがきつくほぼAI任せになったりただの作業になったりであまりよい感触は得られませんでした。
  • 手動連携の多さ:
    • Claude Code, CodeX , ChatGPT... 異なるAIエージェント間でコンテキスト（指示やコード）をコピペする作業が多発し、非効率でした。
  • ルール文書の量産:
    • いくらか「このように実装して欲しい」のルールを作りましたが、AIがコンテキストとして読み込んでくれなかったり脱落したりで、あまり効果が感じられませんでした。
  • サブエージェント（kiro-spec-guardian 等）を呼び出し
    • 呼び出してくれない場面が多数ありました
    • 常駐化できず、手動運用で回したり忘れたりしていました。hooksなりで常駐させた方がよさそうです。

SDDを通して、新しく知ったこと

  • 英語のSpecってSpecificationの「仕様」で、Requirementsは「要件」。
  • EARS（Easy Approach to Requirements Syntax）を初めて知った。
    • EARSを要件記法の基準に採用し、AI（Claude Code／CodeX／ChatGPT）でTDDとドキュメント整備を回す。
  • 「コンテキストエンジニアリング」の重要性に着地

コンテキストエンジニアリング：肥大と腐敗（Context Rot）への対処

SDDの試行錯誤で直面した最大の壁は、ドキュメントの「肥大化」と「腐敗 (Context Rot)」でした。

AIはコンテキストウィンドウ（一度に記憶できる量）から溢れた情報を忘れます。「コンテキストの腐敗」とは、入力が長くなるにつれてモデルの性能が不安定になり、信頼性が低下する現象を指します。

参考：コンテキスト腐敗（Context Rot)

性能低下は正直感じるほどではなかったですが、コンテキストをすぐに使い切ってcompactする頻度が多くなったりしていました。また、design.md ファイルが2万トークンを超えて、そもそもファイルを開いてくれない、みたいなことも結構ありました。

その問題を解決する一つとして、コンテキストエンジニアリングがあります。コンテキストエンジニアリングの原則は、Write / 索引 (Select) / 圧縮 (Compress):/ 分割 (Isolate) の4つです。それを取り入れて、AIが情報を追いやすくするため、以下の戦略を取りました。（順不同）

  • 分割 (Isolate):
    • tasksとdesignってどんどん追記してもらったり、実装詳細にまで設計をさせていたため、文章量が増えてしまったんですよね。大きめの機能の時は、下記のように分割してもらいました。
    • design.md を design-modules/ に分割。1モジュール＝1設計ファイル。
      • overview / architecture / component / data / flow / testing などに分けてもらいました
    • tasks.md が肥大化 → task-design/ フォルダに分離。タスクごとの詳細な計画書を配置。
  • 索引 (Select):
    • 最上位にインデックス用 .md を置き、各ファイルへの参照を持つ階層構造にする。
  • 追跡 (Write):
    • 採番規則（例: STT-<feature>-<major.minor.patch>）を導入し、タスクとドキュメントのトレーサビリティを確保。
  • 圧縮 (Compress):
    • docs-gardener という「文書整備サブエージェント」を自作しました。都度呼び出して、トレーサビリティ/最新性/冗長排除をAIに実行させることが目的です。
    • Steering Documents を中核に、都度差分アップデート。

以上を試していて、タスクの細分化や単一責務、依存関係などはシステム設計と似ているな、と感じました。

全体を通した学び・指針（まとめ）

AIはTDDとドキュメント整備といった「手間だが重要な作業」に最適だと感じました。　docs-gardener や validate系 の常時化で「肥大化」と「腐敗」を抑制すると少しは楽になるかもしれません。Opusのような高性能モデルは使いどころを「設計」と「検証」といった重要な場面に限定するとよさそうです。

コンテキストエンジニアリングが重要スキルになる

当たり前ですが文書は多ければ良い、というものではなく質も大事だということが改めて身に沁みました。結局、AIエージェントの性能は、私たちが提供する「コンテキストの質」で決まるようです。ドキュメントをどう分割し、どう接続し、どう腐らせないか。この「コンテキスト設計」が、これからの開発の主流になりそうです。
結局、人間がやらないといけない。これはもうみなさん知っての通りで言わずもがなですね。

まとめと今後の展望

  • docs-gardener（文書整備サブエージェント）の常駐化: hooks などを利用し、手動運用から脱却したいです。
  • RAG / GraphRAGの導入: 肥大化したドキュメント群から、AIが必要な情報を正確に「検索(Select)」できる仕組みを構築してみたいです。
  • エージェント間の自動連携: CLIプロセス間の手動コピペを撲滅するため、共通コンテキスト（AGENT.mdの標準化など）や、AI同士が合議して意思決定してほしいなぁ、と思っています。