この記事は cc-sdd をまだ使ったことのない読者に向けて書かれており、ツールからではなく、ツールが対処しようとしている失敗から話を始めている。記事によれば、大きな機能を一度にエージェントに頼むと、3 つの典型的なかたちでうまくいかなくなる。頼む側が要件を曖昧にしか言語化していないので返ってくるものがばらつくこと、再試行を繰り返すうちにコンテキストがあふれてエージェントが話の筋を見失うこと、そして設計の理由が会話ログの中にしか残らず、後から誰もたどれなくなることである。記事の論点は、人間のチームが用いる段階的な進め方（要件、設計、タスク分解、実装）はまさにこうした問題を避けるためにあり、協働相手がエージェントであってもそのまま当てはまるというものである。仕様を事前に構造化しておけば、エージェントは実装に集中でき、人間は各段階でレビューできる。
中盤はウォークスルーである。1 つのコマンドでパッケージがインストールされ、スラッシュコマンドはエージェントのコマンドディレクトリの下に、テンプレートとルールファイルは .kiro/ ツリーの下に配置される。プロジェクトのコンテキストと機能ごとの仕様を置くディレクトリは、それらを埋めるコマンドによって後から作成される。続く 6 つのステップは、任意のコードベース分析のステップから始まり、仕様の初期化、要件、技術設計、タスク分解を経て実装に至る。著者は各フェーズが何を書き出すかを説明したうえで、プロセスの一点を強調している。前のフェーズを自動承認するフラグは、学習中には使うべきではない。要件の誤りが設計とタスクにまとめて波及するからである。
最後の 3 分の 1 は、コードが書かれた後に何が起こるか、そしてこれらをいつ使うべきでないかを扱っている。仕様は実装したら凍結するものではなく、生きたドキュメントとして扱うべきものとされる。記事は変更の種類ごとに再生成が必要な下流の成果物を表にまとめており、その流れは常に上流から下流へ向かう。また、完成した仕様をリポジトリにコミットすることを 4 つの理由を挙げて推奨している。そのうえで、オーバーヘッドを払う価値のない 3 つのケース（タイポ程度の修正、一回限りの質問、明確なゴールのない探索的な作業）を挙げ、1 つのプルリクエストにつき 1 つの仕様という粒度のルールを示している。
要点
- 記事が述べる問題は、エージェントが悪いコードを書くことではなく、仕様が不十分な依頼が出力のばらつきを生み、再試行のたびにコンテキストをあふれさせ、設計の根拠をチャットログの中にしか残さないことである。
- 記事の中心的な主張は、仕様を前もって構造化しておくことで、エージェントは実装に集中でき、人間には各段階でレビューする機会が与えられるというものである。
- cc-sdd は、この段階的なプロセスをスラッシュコマンド一式として提供し、要件、設計、タスクをリポジトリ内の Markdown ファイルとして保持する npm パッケージとして説明されている。
- その設計は Kiro の仕様駆動開発に着想を得たものとされており、Kiro の仕様と互換性があることが、Kiro のプラクティスを再利用できる理由として述べられている。
- インストールは、エージェントを指定するフラグと出力言語を指定するフラグを付けた 1 回の
npxの実行である。記事の報告では、スラッシュコマンドはエージェントのコマンドディレクトリに、テンプレートとルールファイルは.kiro/settings/の下に配置される。 - 記事は、本番の実行の前に dry-run フラグでプレビューし、何がどこに作成されるかを確認することを推奨している。
- 最小のワークフローは 6 つのステップからなる。任意のステアリングのステップ、仕様の初期化、そして要件、技術設計、タスク分解、実装であり、それぞれが個別のコマンドとして呼び出される。
- ステアリングのステップは、コードベースを読んで 3 つのファイルを生成するものとして説明されている。1 つ目はプロダクトの目的、対象ユーザー、中核的な価値、2 つ目は技術スタック、バージョン管理の戦略、コーディング規約、3 つ目はディレクトリ構造のパターンと命名規則を扱い、これらはその後、すべてのコマンドが参照するプロジェクトのメモリとして機能する。
- 変更のあったプロジェクトでステアリングのステップを再実行すると、差分を検出して同期を提案すると報告されている。また、既存のソースを分析するものなので、空のディレクトリでは実行できないと記載されている。
- 要件は EARS 形式で生成される。記事はこれを Easy Approach to Requirements Syntax と説明しており、曖昧さを減らすために「When…, the system shall…」のようなパターンを用いる、構造化された自然言語の形式である。
- 設計フェーズでは、エージェントが既存のコードを調査して調査ログをあるファイルに残し、それから技術設計を別のファイルに書くと報告されており、見つかったことの記録と下された判断とが分けられている。
- 生成されたタスクには、順番に実行しなければならないものと並列に実行できるものとを区別するラベルが付けられ、記事はこれを並行開発の境界を明示するものとして提示している。
- プロセスについての著者の最も強い推奨は、初心者は自動承認フラグを使わないことであり、その根拠として、要件の段階の誤りが設計とタスクにまとめて持ち越されることを挙げている。
- 大きな機能については、一度に 1 つか 2 つのタスクずつ実装し、タスクの合間にコンテキストをクリアまたはコンパクトにしてエージェントの精度を保つことを推奨している（コンパクション を参照）。
- 記事自身の立場は、仕様は実装したら凍結するのではなく、開発を通じて継続的に更新される生きたドキュメントとして扱うべきだというものである。
- 修正は上流から下流へと流れるべきものとされる。記事は、要件の変更、設計の変更、タスクの変更のそれぞれについて、どの成果物の再生成が必要かを表にしており、タスクの変更は下流の何にも影響しない。
- 実装の途中で大きな要件変更が生じた場合は、いったん止めて 3 つの成果物を順に更新し、再開する前に検証コマンドで完了済みのタスクとの整合性を確認することを推奨している。
- 完成した仕様は削除せずにコミットすることが推奨されており、理由として 4 つが挙げられている。アーキテクチャ決定記録と同じように設計意図を記録すること、コードからは読み取れないコンテキストを共有すること、将来の保守担当者に元の要件を渡すこと、そしてレビュアーに変更の内容と理由を伝えることである。
- このプロセスに向かないケースとして 3 つが挙げられている。タイポや単一ファイルの些細な変更のような小さな修正、エラーの診断のように 1 回のやり取りで答えが出るタスク、そしてゴールがまだ明確でない探索的な作業である。
- 記事が推奨する粒度は 1 つのプルリクエストにつき 1 つの仕様であり、そうすることで仕様とコード変更との対応関係を扱いやすく保てると論じている。
- よくある 3 つのつまずきと対処法が挙げられている。ステアリングの内容が薄い場合は、ステップを再実行してファイルを手で編集することで解決する。コンテキストがあふれる場合は、タスクごとに実行してタスク間でクリアすることで解決する。空のディレクトリでステアリングのステップが失敗する場合は、ステップがソースコードを分析して動作するものなので、すでにソースコードのあるプロジェクトのルートで実行することで解決する。
背景
この記事は日本のクラウドコンサルティング企業のブログで公開された入門ガイドであり、記事自身もそのように位置づけている。掲げられた目標は、読者が読み終えた時点でインストールコマンドを実行し、最初の仕様を書ける状態になることであり、結びでは全面的な導入ではなく、小さな機能でワークフローを一周してみることを勧めている。記事の拠り所はツール自身のドキュメントであり、コマンドリファレンス、仕様駆動のガイド、カスタマイズについてはそちらにリンクしているほか、あわせて記事とスライド資料にもリンクしている。それらの文書の詳細はそれぞれの文書に属するものであり、ここでは確定させていない。記事は説明の範囲を超える箇所ではそのことを明示している。自動承認フラグへの警告、1 つのプルリクエストにつき 1 つの仕様というルール、タスクの合間にコンテキストをクリアする助言は、文書化された挙動としてではなく、著者の推奨として示されている。記事が教えているプラクティスそのものは、多くの実装にまたがる独立した主題として 仕様駆動開発 で扱われている。