| name | dev-lifecycle |
| description | spec-weaver で仕様管理された開発ライフサイクル全体を統制するスキル。 ユーザーが要件や仕様を伝えた場合、および開発に取り組む場合は必ずこのスキルを使うこと。 以下のキーワードでもトリガーすること: 「開発」「実装」「設計」「ADR」「仕様」「要件」 「仕様管理」「仕様更新」「Doorstop」「Gherkin」「要件定義」「.feature」「BDD」 「受け入れ条件」「Spec-Weaver」「トレーサビリティ」 「behave」「BDDテスト」「Gherkin実装」「ステップ定義」「step定義」 「featureファイル実装」「behaveテスト」「受け入れテスト」 「仕様を見直したい」「ドキュメントが増えてきた」「構造を整理したい」 「仕様のレビュー」「再編」「整合性チェック」「ドキュメント整理」 「分割」「集約」「統合」「階層変更」「親を変える」
|
開発ライフサイクル管理スキル
絶対ルール
- MUST: フェーズを飛ばしてはならない。Phase 1 → 2 → 3 → 4 → 5 → 6 の順に進むこと。
- MUST: 各フェーズ開始時に
## 🔷 Phase N: 名称 を出力すること。
- MUST:
⛔ STOP マーカーではユーザー承認を待つこと。承認なしに次フェーズへ進んではならない。
- MUST: spec-weaver コマンドを実行すること（省略禁止）。
- MUST NOT: Phase 2 を経ずにコードを書き始めてはならない（小規模バグ修正を除く）。
- MUST:
.feature ファイルを作成・変更したら、その直後に必ず spec-weaver scaffold を実行してステップファイルを更新すること。手書きでゼロから Step 定義を書き始めてはならない。
フェーズ判定
タスクを受け取ったら、まず開始フェーズを判定すること。
| タスクの種類 | 開始フェーズ |
|---|
| 新機能 / 大きな変更 | Phase 1 から開始 |
| 小さなバグ修正（1〜2ファイル） | Phase 4 から開始（Phase 5・6 は必須） |
| 仕様の質問のみ | spec-weaver trace で調査して回答（フェーズ不要） |
Phase 1: 分析
出力: ## 🔷 Phase 1: 分析
必須ステップ
- ユーザーの要求を正確に理解すること。不明点があれば質問すること。
- 以下のコマンドを実行し、関連する既存仕様を特定すること:
uv run spec-weaver status
uv run spec-weaver trace <関連ID> -f ./specification/features
- Grep / Glob / Read ツールで影響を受けるコードモジュールを特定すること。
- 分析結果を以下の形式でユーザーに報告すること:
- 関連する REQ / SPEC のリスト
- 影響を受けるモジュール
- 新規 REQ / SPEC /
.feature の追加が必要か
- リスク・懸念事項
⛔ STOP: 分析結果を報告し、ユーザーの承認を得ること。承認なしに Phase 2 へ進んではならない。
Phase 2: 設計
出力: ## 🔷 Phase 2: 設計
必須ステップ
-
新規/更新が必要な REQ / SPEC を references/doorstop-guide.md の手順で 作成・更新すること:
doorstop add REQ
doorstop add SPEC
doorstop link SPEC-xxx REQ-xxx
-
REQ / SPEC の YAML に status: draft を設定すること。
新規 SPEC には layer 属性も設定すること（behavior または architecture）:
layer: behavior
-
規模に応じて設計ドキュメントを作成すること（判定表を参照）:
| 規模 | DESIGN | ADR | PLAN |
|---|
| 大規模（複数モジュール横断） | 必須 | 必要に応じて | 必須 |
| 中規模（単一モジュール内の大きな変更） | 推奨 | — | 推奨 |
| 小規模（数ファイルの変更） | — | — | 任意 |
-
.feature ファイルの追加・更新方針を決定し、references/behave-and-testing.md の Gherkin 規則に従って Feature / Scenario を記述すること。
-
.feature を作成・更新したら、その直後に scaffold を実行してステップ雛形を生成すること:
uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps
scaffold はステップ定義の「骨格」を生成するだけ。肉付けは Phase 4 で行う。
-
設計方針をユーザーに提示すること。
⛔ STOP: 設計方針を提示し、ユーザーの承認を得ること。承認なしに Phase 3 へ進んではならない。
Phase 3: 計画
Plan Modeで立てた実装計画などをドキュメントとして保存する。
出力: ## 🔷 Phase 3: 計画
必須ステップ
- 実装タスクを具体的なステップに分解すること。各ステップは以下を満たすこと:
- 1つの論理的な変更単位である
- 完了条件が明確である
- 依存関係が明示されている
- 中〜大規模の場合、PLAN ドキュメントを Doorstop に作成すること:
doorstop add PLAN
doorstop link PLAN-xxx SPEC-xxx
- タスクの実行順序を整理すること（依存関係順 → リスク順 → テスト容易性）。
- 実装計画をユーザーに提示すること。
⛔ STOP: 実装計画を提示し、ユーザーの承認を得ること。承認なしに Phase 4 へ進んではならない。
Phase 4: 実装
出力: ## 🔷 Phase 4: 実装
必須ステップ
- 計画に沿ってコードを変更すること。
- コード変更に伴い仕様が変わる場合は、コードと同時に SPEC /
.feature を更新すること（references/doorstop-guide.md の手順に従う）。
.feature ファイルを追加・更新した場合は、必ず scaffold を実行してステップファイルを更新し、references/behave-and-testing.md の手順で ステップ定義を肉付けすること:
uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps
uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps --overwrite
scaffold の役割: .feature の Gherkin に対応するステップ骨格（raise NotImplementedError）を自動生成する。
.feature を1行でも変更したら scaffold を再実行し、新規/変更ステップの骨格を取り込む。
- 関連する REQ / SPEC の
status を in-progress に更新すること。
- テストを実行し、確認すること:
uv run pytest tests/ -q
uv run behave
- 実装したファイルのパスを、対応する SPEC の YAML に
impl_files カスタム属性としてリスト形式で記述すること:
impl_files:
- src/your_module.py
- src/another_module.py
また、実装ファイルの先頭付近にアノテーションも記述すること:
注意: Doorstop の ref フィールドは文字列専用のため、ファイルパスリストには必ず impl_files を使うこと。
検証方法: uv run spec-weaver audit --check-impl ./specification/features で impl_files とアノテーションの乖離を確認できる。
必須条件（Phase 5 へ進む前に全て満たすこと）
- 計画の全タスクが完了している
pytest テストが通過している.feature を追加・更新した場合、対応するステップ定義が実装されている（behave 実行済み）- 実装ファイルが対応 SPEC の
impl_files カスタム属性に記述されている
Phase 5: 波及確認
出力: ## 🔷 Phase 5: 波及確認
目的: 変更されたアイテムを起点に、関連する全てのアイテム（REQ / SPEC / .feature / DESIGN / PLAN / コード）が整合しているか精査し、必要な更新を行う。
必須ステップ
-
今回変更した全アイテム（REQ / SPEC / .feature / DESIGN / PLAN / コード）をリストアップすること。
-
変更した各アイテムについて、spec-weaver trace で上位・下位の関連アイテムを洗い出すこと:
uv run spec-weaver trace <変更したID> -f ./specification/features
-
以下の観点で各関連アイテムを精査し、不整合があれば更新すること:
| 変更元 | 精査対象 | 確認すべきこと |
|---|
| REQ を変更 | 子 SPEC / .feature / DESIGN | SPEC の記述が REQ の変更を反映しているか |
| SPEC を変更 | 親 REQ / .feature / DESIGN / PLAN | .feature のシナリオが SPEC と一致しているか |
.feature を変更 | 対応 SPEC / テストコード | SPEC の testable 属性やタグが正しいか |
| DESIGN を変更 | 親 SPEC / 実装コード | コードが設計と一致しているか |
| コードを変更 | 対応 SPEC / .feature | 仕様に記載のない振る舞いが増えていないか |
SPEC の layer | .feature との対応 | layer: behavior の SPEC に .feature があるか。layer: architecture の SPEC に .feature が紐づいていないか |
-
精査結果と更新内容をユーザーに報告すること。
⛔ STOP: 波及確認の結果を報告し、ユーザーの承認を得ること。承認なしに Phase 6 へ進んではならない。
Phase 6: 検証・コミット
出力: ## 🔷 Phase 6: 検証・コミット
必須コマンド（この順序で実行すること。失敗したら修正して再実行）
uv run pytest tests/ -q
uv run behave
uv run spec-weaver audit ./specification/features
doorstop
uv run spec-weaver build ./specification/features --out-dir .specification
必須ステップ
- 上記4つの検証コマンドを 全て 実行し、通過を確認すること。
- 関連する REQ / SPEC の
status を implemented に更新すること。
- ステータスを確認すること:
uv run spec-weaver status
- コミット規約（Conventional Commits）に従ってコミットすること。scope に仕様ID を記載すること:
feat(SPEC-xxx): 変更の概要
詳細は references/commit-conventions.md を参照。
拡張ドキュメント階層
REQ → SPEC の下に以下のドキュメント型を配置できる。
REQ（ビジネス要件）
└── SPEC（システム仕様）
├── DESIGN（アーキテクチャ・コンポーネント設計）
├── PLAN（実装タスク分解・順序）
├── ADR（技術選定の記録）
└── RESEARCH（技術調査・PoC結果）
初回セットアップが必要な場合:
doorstop create DESIGN ./specification/designs --parent SPEC
doorstop create PLAN ./specification/plans --parent SPEC
doorstop create ADR ./specification/adrs --parent SPEC
doorstop create RESEARCH ./specification/research --parent SPEC
各ドキュメント型の詳細は references/document-types.md を参照。
BDD テスト実装の原則
テストは「通すためのもの」ではない。
テストは「設計として正しい世界」を固定するために存在する。
現在の実装がテストに追従できていない場合、テストが失敗するのは正しい。
3層構造（Spec-Glue-Execution）
Spec 層 ──── .feature（Gherkin） : ビジネスの振る舞いを宣言
Glue 層 ──── Step 定義（Python） : 翻訳・委譲のみ（ロジック禁止）
Execution 層 ── ヘルパー / クライアント : 実際のシステム操作
絶対原則
- 仕様至上主義: 実装の都合で Gherkin を変更しない。仕様として正しければ、テストが失敗してもよい。
- 関心の分離: Gherkin はビジネスの振る舞い（What）、Step は翻訳と委譲のみ（How）。Step にロジックを書かない。
- 宣言的記述: Gherkin に UI・API・DB の実装詳細を書かない。ドメイン用語を最優先する。
詳細は references/behave-and-testing.md を参照。
ドキュメントレビュー & 再編
仕様ドキュメントの健全性を診断し、問題があれば再整理する3つのモード:
| モード | 目的 | 操作 |
|---|
| レビュー | ドキュメントを変更せず問題点を報告 | 構造・リンク・内容・鮮度・layer分類を6カテゴリでチェック |
| 再編 | 構造的問題の改善 | 分割（サブドキュメント化）、集約（統合）、階層変更（親の変更） |
| 個別修正 | アイテム単位の問題修正 | リンク切れ修正、孤立アイテムへのリンク追加、重複統合 |
詳細は references/review-and-reorganization.md を参照。
scaffold の実行タイミング（まとめ）
.feature に変更が入ったタイミングでは必ず scaffold を実行すること:
| タイミング | 操作 |
|---|
Phase 2 で .feature を新規作成した | scaffold 実行 → ステップ骨格（NotImplementedError）を生成 |
Phase 4 で .feature を追加・変更した | scaffold 実行 → 差分ステップ骨格を取り込む |
Phase 5 で .feature を修正した（波及更新） | scaffold 実行 → ステップファイルに反映 |
uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps
uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps --overwrite
参照ファイル
| ファイル | 読むタイミング |
|---|
references/workflow-phases.md | 各フェーズの詳細手順を確認するとき |
references/commit-conventions.md | コミットメッセージを作成するとき |
references/document-types.md | DESIGN / PLAN / ADR / RESEARCH を作成するとき |
references/design-principles.md | 設計原則・4層モデル・layer属性の詳細を確認するとき |
references/doorstop-guide.md | Doorstop CLI の使い方・YAML テンプレート・セットアップ手順を確認するとき |
references/gherkin-guide.md | .feature ファイルを作成・編集するとき |
references/spec-weaver-commands.md | Spec-Weaver の各コマンドの使い方を確認するとき |
references/behave-and-testing.md | BDD テスト（behave）の実装・ステップ定義・パターンを確認するとき |
references/ci-integration.md | GitHub Actions や Pre-commit の設定をするとき |
references/review-and-reorganization.md | ドキュメントのレビュー・再編・整合性修正を行うとき |
