dev-lifecycle

name	dev-lifecycle
description	spec-weaver で仕様管理された開発ライフサイクル全体を統制するスキル。 ユーザーが要件や仕様を伝えた場合、および開発に取り組む場合は必ずこのスキルを使うこと。 以下のキーワードでもトリガーすること: 「開発」「実装」「設計」「ADR」「仕様」「要件」 「仕様管理」「仕様更新」「Doorstop」「Gherkin」「要件定義」「.feature」「BDD」 「受け入れ条件」「Spec-Weaver」「トレーサビリティ」 「behave」「BDDテスト」「Gherkin実装」「ステップ定義」「step定義」 「featureファイル実装」「behaveテスト」「受け入れテスト」 「仕様を見直したい」「ドキュメントが増えてきた」「構造を整理したい」 「仕様のレビュー」「再編」「整合性チェック」「ドキュメント整理」 「分割」「集約」「統合」「階層変更」「親を変える」

開発ライフサイクル管理スキル

絶対ルール

1. MUST: フェーズを飛ばしてはならない。Phase 1 → 2 → 3 → 4 → 5 → 6 の順に進むこと。
2. MUST: 各フェーズ開始時に ## 🔷 Phase N: 名称 を出力すること。
3. MUST: ⛔ STOP マーカーではユーザー承認を待つこと。承認なしに次フェーズへ進んではならない。
4. MUST: spec-weaver コマンドを実行すること（省略禁止）。
5. MUST NOT: Phase 2 を経ずにコードを書き始めてはならない（小規模バグ修正を除く）。
6. MUST: .feature ファイルを作成・変更したら、その直後に必ず spec-weaver scaffold を実行してステップファイルを更新すること。手書きでゼロから Step 定義を書き始めてはならない。

---

フェーズ判定

タスクを受け取ったら、まず開始フェーズを判定すること。

タスクの種類	開始フェーズ
新機能 / 大きな変更	Phase 1 から開始
小さなバグ修正（1〜2ファイル）	Phase 4 から開始（Phase 5・6 は必須）
仕様の質問のみ	spec-weaver trace で調査して回答（フェーズ不要）

---

Phase 1: 分析

出力: ## 🔷 Phase 1: 分析

必須ステップ

1. ユーザーの要求を正確に理解すること。不明点があれば質問すること。
2. 以下のコマンドを実行し、関連する既存仕様を特定すること:

   uv run spec-weaver status
   uv run spec-weaver trace <関連ID> -f ./specification/features
   

3. Grep / Glob / Read ツールで影響を受けるコードモジュールを特定すること。
4. 分析結果を以下の形式でユーザーに報告すること:
   • 関連する REQ / SPEC のリスト
   • 影響を受けるモジュール
   • 新規 REQ / SPEC / .feature の追加が必要か
   • リスク・懸念事項

⛔ STOP: 分析結果を報告し、ユーザーの承認を得ること。承認なしに Phase 2 へ進んではならない。

---

Phase 2: 設計

出力: ## 🔷 Phase 2: 設計

必須ステップ

1. 新規/更新が必要な REQ / SPEC を references/doorstop-guide.md の手順で 作成・更新すること:

   doorstop add REQ          # 新規REQ追加
   doorstop add SPEC         # 新規SPEC追加
   doorstop link SPEC-xxx REQ-xxx   # リンク設定
   

2. REQ / SPEC の YAML に status: draft を設定すること。 新規 SPEC には layer 属性も設定すること（behavior または architecture）:

   layer: behavior     # 外部から観察可能な振る舞い → .feature でテスト
   # layer: architecture  # 内部構造・技術的制約 → ユニットテストで検証
   

3. 規模に応じて設計ドキュメントを作成すること（判定表を参照）:

   規模	DESIGN	ADR	PLAN
   大規模（複数モジュール横断）	必須	必要に応じて	必須
   中規模（単一モジュール内の大きな変更）	推奨	—	推奨
   小規模（数ファイルの変更）	—	—	任意

4. .feature ファイルの追加・更新方針を決定し、references/behave-and-testing.md の Gherkin 規則に従って Feature / Scenario を記述すること。

5. .feature を作成・更新したら、その直後に scaffold を実行してステップ雛形を生成すること:

   uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps
   

   scaffold はステップ定義の「骨格」を生成するだけ。肉付けは Phase 4 で行う。

6. 設計方針をユーザーに提示すること。

⛔ STOP: 設計方針を提示し、ユーザーの承認を得ること。承認なしに Phase 3 へ進んではならない。

---

Phase 3: 計画

Plan Modeで立てた実装計画などをドキュメントとして保存する。

出力: ## 🔷 Phase 3: 計画

必須ステップ

1. 実装タスクを具体的なステップに分解すること。各ステップは以下を満たすこと:
   • 1つの論理的な変更単位である
   • 完了条件が明確である
   • 依存関係が明示されている
2. 中〜大規模の場合、PLAN ドキュメントを Doorstop に作成すること:

   doorstop add PLAN
   doorstop link PLAN-xxx SPEC-xxx
   

3. タスクの実行順序を整理すること（依存関係順 → リスク順 → テスト容易性）。
4. 実装計画をユーザーに提示すること。

⛔ STOP: 実装計画を提示し、ユーザーの承認を得ること。承認なしに Phase 4 へ進んではならない。

---

Phase 4: 実装

出力: ## 🔷 Phase 4: 実装

必須ステップ

1. 計画に沿ってコードを変更すること。
2. コード変更に伴い仕様が変わる場合は、コードと同時に SPEC / .feature を更新すること（references/doorstop-guide.md の手順に従う）。
3. .feature ファイルを追加・更新した場合は、必ず scaffold を実行してステップファイルを更新し、references/behave-and-testing.md の手順で ステップ定義を肉付けすること:

   # .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
   # 生成された雛形の NotImplementedError を仕様に従って肉付けする
   

   scaffold の役割: .feature の Gherkin に対応するステップ骨格（raise NotImplementedError）を自動生成する。 .feature を1行でも変更したら scaffold を再実行し、新規/変更ステップの骨格を取り込む。

4. 関連する REQ / SPEC の status を in-progress に更新すること。
5. テストを実行し、確認すること:

   uv run pytest tests/ -q
   uv run behave          # BDD シナリオの実行（失敗は仕様と実装の乖離を示すため正常）
   

6. 実装したファイルのパスを、対応する SPEC の YAML に impl_files カスタム属性としてリスト形式で記述すること:

   impl_files:
     - src/your_module.py
     - src/another_module.py
   

   また、実装ファイルの先頭付近にアノテーションも記述すること:

   # implements: SPEC-XXX
   

   注意: 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 / コード）が整合しているか精査し、必要な更新を行う。

必須ステップ

1. 今回変更した全アイテム（REQ / SPEC / .feature / DESIGN / PLAN / コード）をリストアップすること。

2. 変更した各アイテムについて、spec-weaver trace で上位・下位の関連アイテムを洗い出すこと:

   uv run spec-weaver trace <変更したID> -f ./specification/features
   

3. 以下の観点で各関連アイテムを精査し、不整合があれば更新すること:

   変更元	精査対象	確認すべきこと
   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 が紐づいていないか

4. 精査結果と更新内容をユーザーに報告すること。

⛔ STOP: 波及確認の結果を報告し、ユーザーの承認を得ること。承認なしに Phase 6 へ進んではならない。

---

Phase 6: 検証・コミット

出力: ## 🔷 Phase 6: 検証・コミット

必須コマンド（この順序で実行すること。失敗したら修正して再実行）

# 1. ユニットテスト
uv run pytest tests/ -q

# 2. BDD 受け入れテスト（失敗は仕様と実装の乖離を示す）
uv run behave

# 3. Spec-Weaver 監査（仕様 ↔ Gherkin の整合性）
uv run spec-weaver audit ./specification/features

# 4. Doorstop バリデーション（リンク整合性）
doorstop

# 5. ドキュメント再生成
uv run spec-weaver build ./specification/features --out-dir .specification

必須ステップ

1. 上記4つの検証コマンドを 全て 実行し、通過を確認すること。
2. 関連する REQ / SPEC の status を implemented に更新すること。
3. ステータスを確認すること:

   uv run spec-weaver status
   

4. コミット規約（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 層 ── ヘルパー / クライアント : 実際のシステム操作

絶対原則

1. 仕様至上主義: 実装の都合で Gherkin を変更しない。仕様として正しければ、テストが失敗してもよい。
2. 関心の分離: Gherkin はビジネスの振る舞い（What）、Step は翻訳と委譲のみ（How）。Step にロジックを書かない。
3. 宣言的記述: 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	ドキュメントのレビュー・再編・整合性修正を行うとき