SKILL.md
SDD (Specification-Driven Development) 原則
仕様を開発の起点とし、仕様 → 計画 → 実装の一貫したパイプラインで開発を行う方法論。
核心概念
仕様 = 真実の源泉（Single Source of Truth）
- 仕様書が全ての設計判断の根拠となる
- コードは仕様の実装であり、仕様に記載のない変更は行わない
- 不明点は推測せず、明示的に記録して解決する
5つの基本原則
1. 共有言語 (Shared Language)
仕様書はチーム全員（人間・AI含む）が理解できる言葉で記述する。技術用語には定義を添え、曖昧な表現を避ける。
2. 実行可能仕様 (Executable Specification)
受入基準はGiven-When-Then形式で記述し、そのままテストケースに変換可能な粒度で書く。
3. 継続的改良 (Continuous Refinement)
仕様は一度書いて終わりではない。実装中に発見した不整合はフィードバックとして仕様に反映する。
4. 明示的不確実性 (Explicit Uncertainty)
不明点は [NEEDS CLARIFICATION: 質問内容] マーカーで明示する。推測で実装を進めない。
5. 双方向フィードバック (Bidirectional Feedback)
仕様→実装だけでなく、実装→仕様の逆方向フィードバックも重要。実装中に仕様の不備を発見したら報告・記録する。
プロジェクト憲法
SDD ワークフローで遵守する不変原則。
| 条 | 原則 | 要約 |
|---|---|---|
| I | モジュール先行 | コアロジックとインターフェース層を分離する |
| II | 契約先行 | 外部インターフェースを仕様で定義してから実装する |
| III | テスト先行 | テスト作成→実装→検証の順序で進める |
| IV | 仕様完全性 | [NEEDS CLARIFICATION] ゼロで計画フェーズへ進む |
| V | 最小依存 | 外部依存の追加には採用理由を明記する |
| VI | 関心の分離 | 各モジュールの責務を明確に分離する |
| VII | 簡潔性ゲート | 関数・ファイルの行数とネスト深度に上限を設ける |
| VIII | 直接利用 | フレームワーク標準APIを直接使用し不要な抽象化を避ける |
| IX | 統合テスト優先 | 実際のインターフェースを通じてテストする |
運用ルール
- 仕様フェーズ: 仕様書の「プロジェクト憲法チェックリスト」で全条項の準拠を確認する
- 計画フェーズ: 実装計画が各条項に違反しないことを事前確認する
- 実装フェーズ: 実装中に条項違反を発見した場合、ユーザーに報告する
- 条項の変更: プロジェクト憲法の変更はユーザーの明示的な承認が必要
フェーズゲート定義
ゲート1: Specify → Plan（仕様から計画へ）
以下の全条件を満たすこと:
| # | 条件 | 確認方法 |
|---|---|---|
| G1-1 | [NEEDS CLARIFICATION] マーカーがゼロ |
仕様書内を検索 |
| G1-2 | 受入基準が1つ以上存在 | Given-When-Thenテーブルを確認 |
| G1-3 | プロジェクト憲法チェックリストが全項目記入済み | チェックボックスを確認 |
| G1-4 | ユーザーが仕様を承認済み | 明示的な承認を確認 |
ゲート2: Plan → Implement（計画から実装へ）
以下の全条件を満たすこと:
| # | 条件 | 確認方法 |
|---|---|---|
| G2-1 | ゲート1を通過済み | 仕様書のステータスを確認 |
| G2-2 | 実装フェーズが定義されている | Part 2のフェーズセクションを確認 |
| G2-3 | 各タスクに完了条件がある | タスク定義を確認 |
| G2-4 | シンプリシティゲートが確認済み | 計画書の 2.4 を確認 |
| G2-5 | ユーザーが計画を承認済み | 明示的な承認を確認 |
不確実性マーカー仕様
記法
[NEEDS CLARIFICATION: 具体的な質問内容]運用ルール
- 推測禁止: 不明点は必ずマーカーを付け、推測で記入しない
- 質問は具体的に: 「要件が不明」ではなく「ログイン失敗時のリダイレクト先はどこか？」のように具体的に書く
- 配置場所: 該当する仕様セクション内にインラインで配置し、Part 1末尾の「不確実性」セクションにも一覧を記載
- 解決時: マーカーを削除し、確定した内容で仕様を更新する。不確実性セクションの一覧からも削除
- ゲート制御: 未解決マーカーが1つでもある場合、ゲート1を通過できない
例
## 詳細仕様
- ユーザー名: string (必須, [NEEDS CLARIFICATION: 最大文字数は？])
- タイムアウト: [NEEDS CLARIFICATION: リトライ回数の上限は？]