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