spec-driven-development について
仕様書と並行して機能を実装する開発者向けのスキルです。`.claude/specs/` をアーキテクチャ決定や API 契約の基準とし、仕様とコードの整合性を繰り返し確認・更新する手順を示します。
主な機能
- 01仕様を基準とする実装ワークフロー
- 02仕様がない場合の進め方
- 03実装 TODO の管理
- 04実装後の整合性チェック
- 05差分と未対応項目の整理
活用シーン
- 01複雑な機能の実装開始
- 02実装変更に伴う仕様の更新
- 03API 契約に沿ったコードの検証
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/spec-driven-developmentを入力して読み込まれたか確認します。
詳細
仕様主導開発
仕様は .claude/specs/ にあります。仕様は、アーキテクチャ上の決定、API コントラクト、実装範囲の信頼できる情報源です。実装と仕様は常に同期させる必要があり、どちらか一方だけを先行させてはいけません。
基本的なサイクル
Read spec → Implement → Verify alignment → Update spec or code → Repeat
作業を始める前に
- 仕様を探します。
.claude/specs/から、対象機能に一致するファイルを検索します。
ls .claude/specs/
-
仕様を最後まで読みます。 コードを書く前に、範囲、決定事項、API コントラクト、未解決の質問を理解します。
-
仕様が存在しない場合、タスクが重要なものである場合（新しいモジュール、新しい API、アーキテクチャの変更）は、まず仕様を作成するかユーザーに確認します。
実装中
- 仕様の決定事項を参照します — 仕様ですでに決まっていることを再び検討しません。
- 仕様から逸脱する場合（より良い方法が見つかった、ユーザーから変更を依頼された、制約が判明した）、同じセッション内ですぐに仕様を更新します。仕様とコードを不整合のままにしません。
- TODO のチェックボックスを更新します（
- [ ]→- [x]）。項目が完了したらチェックを付けます。 - 意図的にスキップまたは置き換えた項目は、簡潔な理由を添えて取り消し線を引くか、注記します。
- [x] ~~OpenRouter proxy~~ → Direct execution: nodes call OpenRouter directly
作業完了後
仕様の検証を行います。
- 実装と照らし合わせながら仕様を再読します。
- 各セクションを確認します。
- 仕様の API エンドポイントはコントローラーと一致していますか？
- 仕様の設定／環境変数は設定クラスと一致していますか？
- 仕様のモジュール構造は実際のファイルツリーと一致していますか？
- 仕様の型定義は
@n8n/api-typesと一致していますか？ - すべての TODO 項目のチェック状態は正しいですか？
- 見つかった差異に合わせて仕様を更新します。 よくある差異：
- 構成セクションに記載されていない新しいファイルが追加されている
- 実装中に API レスポンスの形式が変更された
- 設定のデフォルト値が調整された
- アーキテクチャ上の決定事項が見直された
- 未解決の不足事項をユーザーに伝えます。仕様で約束されているものの、実装ではまだ提供されていない項目を報告します（MVP では許容される場合もありますが、記録しておく必要があります）。
仕様ファイルの規約
- 機能ごとに
.claude/specs/内に 1 つ以上の Markdown ファイルを作成します。 - 仕様は簡潔に保ちます。対応関係には表を、形式の記述にはコードブロックを使用します。
- 進捗の記録には、チェックボックス付きの
## Implementation TODOを使用します。 - 必要に応じて複数のファイルに分割します（例：バックエンド／フロントエンドを分ける）。ただし、厳格な命名規則は設けません。
ユーザーから「セルフレビュー」または「仕様との照合」を依頼された場合
- 関連するすべての仕様を読みます。
- 実装ファイルをすべて読みます。
- 次の項目に分けて、構造化された比較結果を提示します。
- 一致：仕様とコードが一致している項目
- 差異：仕様とコードが食い違っている項目（すぐに修正します）
- 不足：まだ実装されていない仕様項目（今後の作業として記録します）
- 差異を修正し、仕様を更新して、不足事項をユーザーに報告します。
コメント
Markdown 対応