spec-runner 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +17 -10
  2. package/package.json +1 -1
  3. package/spec-runner/templates/.claude/rules/coding.md +13 -1
  4. package/spec-runner/templates/.claude/skills/architecture-skill-development/SKILL.md +4 -2
  5. package/spec-runner/templates/.claude/skills/existing-project-to-docs/SKILL.md +79 -20
  6. package/spec-runner/templates/.github/instructions/coding.instructions.md +13 -1
  7. package/spec-runner/templates/.github/skills/architecture-skill-development/SKILL.md +4 -2
  8. package/spec-runner/templates/.github/skills/existing-project-to-docs/SKILL.md +79 -20
package/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # spec-runner
2
2
 
3
- `spec-runner` は、`docs/` を正本にして開発を進める運用ハーネスを、**Claude Code（`.claude/`）** と **GitHub Copilot（`.github/`）** に導入するインストーラ。
3
+ AI は設計を飛ばして実装に走る。`docs/` があっても読まないし、仕様が曖昧なまま動くコードを返す。
4
4
 
5
- 主線は `要件定義 -> 概要設計 -> 詳細設計 -> TDD -> 実装`。rules / agents / skills はその流れを安定運用するために配る。
5
+ `spec-runner` はそれを防ぐ。**`docs/` を正本にした開発フロー**を AI に守らせるための rules / agents / skills を、**Claude Code（`.claude/`）** と **GitHub Copilot（`.github/`）** にインストーラ一発で配る。
6
+
7
+ フローは `要件定義 → 概要設計 → 詳細設計 → TDD → 実装`。AI はこの順序で docs を読み書きしながら進み、設計なしに実装フェーズへ進めない。
8
+
9
+ インストール後は `architecture-skill-development` を使ってプロジェクトのアーキテクチャを定義し、そこから **プロジェクト専用 skill** を生やす。汎用 skill はその土台にすぎない。
6
10
 
7
11
  ## インストール
8
12
 
@@ -42,15 +46,22 @@ curl -sSL https://raw.githubusercontent.com/TEEE88/spec-runner/main/install.sh |
42
46
 
43
47
  ### 同梱するベース skill
44
48
 
49
+ **セットアップ用**（プロジェクト初期に使い、完了後はアーカイブする）
50
+
45
51
  - `architecture-definition`: 新規プロジェクトで docs と architecture contract を起こす
46
52
  - `existing-project-to-docs`: 既存コードから docs の draft と構造化情報を起こす
47
53
  - `architecture-skill-development`: architecture contract から project 専用 skill を育てる
48
- - `plugin-development`: プラグイン型アーキテクチャ向けの reference workflow
49
- - `design-change`: 変更要求に対して影響調査 -> ADR -> 設計修正 -> TDD で進める
54
+ - `docs-driven-seed`: DDD 向けの project 専用 skill の種（`style: ddd` のとき）
55
+ - `simple-seed`: レイヤードアーキテクチャ向けの project 専用 skill の種（`style: layered` のとき）
56
+
57
+ **開発ループ用**（日常的に使う）
58
+
59
+ - `design-change`: 変更要求に対して影響調査 → ADR → 設計修正 → TDD で進める
50
60
  - `test-driven-development`: アプリケーションコード向けの TDD を徹底する
51
61
  - `harness-engineering`: rules / agents / skills / templates 自体を改善する
62
+ - `commit`: コミットメッセージの生成とコミット実行
52
63
 
53
- `docs/` や `.spec-runner/` の中身は、導入後にこれらの skill を使ってプロジェクトごとに作る。
64
+ `docs/` の中身は、導入後にこれらの skill を使ってプロジェクトごとに作る。
54
65
 
55
66
  ## 推奨フロー
56
67
 
@@ -87,13 +98,9 @@ SPEC_RUNNER_FORCE=1 npx spec-runner
87
98
  - `spec-runner/templates/.claude/`
88
99
  - `spec-runner/templates/.github/`
89
100
 
90
- ### 構想メモ
91
-
92
- - `docs/ハーネスエンジニアリング構想.md`
93
-
94
101
  ## バージョン運用ルール
95
102
 
96
- - このリポジトリでは **コミットごとに `package.json` の `version` を更新**する
103
+ - **開発のたびに `package.json` の `version` を更新してからコミットする**
97
104
  - バージョンは原則 SemVer に従い、迷う場合はパッチを 1 つ上げる
98
105
 
99
106
  ## ライセンス
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spec-runner",
3
- "version": "1.2.0",
3
+ "version": "1.4.0",
4
4
  "description": "docs を正本にした開発運用ハーネスを Claude / Copilot に導入する",
5
5
  "license": "MIT",
6
6
  "bin": {
package/spec-runner/templates/.claude/rules/coding.md CHANGED
@@ -24,10 +24,22 @@ paths: ["src/**", "tests/**"]
24
24
 
25
25
  ## コメント
26
26
 
27
+ ### 原則（全プロジェクト共通）
28
+
27
29
  - **言語**: 日本語
28
- - **インラインコメント**: ビジネスロジックの「なぜ」を説明する場合のみ。処理内容の「何」は書かない
29
30
  - **変更履歴コメント禁止**: 変更経緯はコードに書かない。git の commit message で管理する
30
31
 
32
+ ### プロジェクト固有の決定事項
33
+
34
+ > `architecture-skill-development` で以下をチームで合意し、`<...>` を書き換える。
35
+
36
+ - **インラインコメント（なぜ）**: `<ビジネスロジックの判断理由は必ず書く / 任意>`
37
+ - **処理ブロックのコメント（何）**: `<禁止（命名で表現する） / 複雑なフローに限り許可>`
38
+ - **ファイル / モジュールレベルのコメント**: `<必須 / 任意 / 不要>`
39
+ - **関数・クラスの docコメント**: `<常に必須 / 公開 API のみ / 複雑なものだけ / 不要>`
40
+ - **TODO / FIXME マーカー**: `<許可する（課題管理ツールの番号を添える） / 禁止>`
41
+ - **セクション区切りコメント**: `<許可する場合はフォーマットを記載 / 禁止>`
42
+
31
43
  ## 言語・型固有ルール
32
44
 
33
45
  > このセクションを言語・フレームワークに合わせて書き換える。
package/spec-runner/templates/.claude/skills/architecture-skill-development/SKILL.md CHANGED
@@ -109,8 +109,10 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
109
109
  `architecture.yaml` の `language` と `folder_structure` を参照して、以下を実際の値に置き換える。
110
110
 
111
111
  1. **命名規則**: 言語の慣習に合わせてテーブルの規則・例を書き換える
112
- 2. **言語・型固有ルール**: `<your-language-and-type-rules>` を言語・フレームワークに合わせた具体的なルールに書き換える
113
- 3. **プロジェクト構造**: `<your-project-structure>` を `folder_structure` の実際のディレクトリ構成に書き換える
112
+ 2. **コメント規約**: `## コメント` の「プロジェクト固有の決定事項」をユーザーと合意してから書き換える
113
+ - インラインコメント（なぜ）・処理ブロック（何）・docコメント・TODO/FIXME・セクション区切りの各方針を決定する
114
+ 3. **言語・型固有ルール**: `<your-language-and-type-rules>` を言語・フレームワークに合わせた具体的なルールに書き換える
115
+ 4. **プロジェクト構造**: `<your-project-structure>` を `folder_structure` の実際のディレクトリ構成に書き換える
114
116
 
115
117
  上記の `integrations` ルールに従って反映する。
116
118
 
package/spec-runner/templates/.claude/skills/existing-project-to-docs/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: existing-project-to-docs
3
- description: 既存プロジェクトを読み解き、docs の draft と architecture contract を起こすリバース設計フロー。
3
+ description: 既存プロジェクトを読み解き、docs の正本と architecture contract を起こすリバース設計フロー。
4
4
  ---
5
5
 
6
6
  # existing-project-to-docs
@@ -12,12 +12,24 @@ description: 既存プロジェクトを読み解き、docs の draft と archit
12
12
 
13
13
  ```
14
14
  Phase 1: 現状把握
15
+ Phase 1.5: docs 構成の合意
15
16
  Phase 2: 要件とユースケースの抽出
16
- Phase 3: 概要設計の draft 化
17
- Phase 4: 詳細設計の draft 化
17
+ Phase 3: 概要設計
18
+ Phase 4: 詳細設計
18
19
  Phase 5: architecture contract 化
19
20
  ```
20
21
 
22
+ ## 前提ルール
23
+
24
+ - docs は正本とし、各ドキュメントに `spec_runner` frontmatter を付ける
25
+ - `maps_to` は必ず設定する。パス推定に頼らない
26
+ - 既存コードを正として観測する。推測する場合は明示する
27
+ - ユーザー承認なしに次フェーズへ進めない
28
+ - `style: ddd` の場合: UC がドメインを使う。ドメインの中に UC を入れない
29
+ - `style: ddd` の場合: 詳細設計は `01_ドメイン/` `02_ユースケース/` `03_DB・外部サービス/` の 3 層で構成する
30
+ - `style: layered` の場合: ドメイン層は持たない。ビジネスロジックは UC / サービス層で表現する
31
+ - `style: layered` の場合: 詳細設計は `01_ユースケース/` `02_DB・外部サービス/` の 2 層で構成する
32
+
21
33
  ## Phase 1: 現状把握
22
34
 
23
35
  1. `src/`、`tests/`、設定ファイル、README、IaC を読む
@@ -25,43 +37,90 @@ Phase 5: architecture contract 化
25
37
  3. `.spec-runner/intake/current-system-inventory.md` を作る
26
38
  4. ユーザーに確認・承認を得る
27
39
 
40
+ ## Phase 1.5: docs 構成の合意
41
+
42
+ ファイルを作成する前に、docs の構成をユーザーと合意する。
43
+
44
+ 1. `current-system-inventory.md` を元に以下を提案する
45
+ - `style`（`ddd` / `layered`）
46
+ - `docs/` のフォルダ構成
47
+ - 作成予定ファイルの一覧
48
+ 2. ユーザーに確認・承認を得る
49
+ 3. 承認後、`.spec-runner/architecture/architecture.yaml` を新規作成し `style` だけ先に書き込む（残りは Phase 5 で完成させる）
50
+
28
51
  ## Phase 2: 要件とユースケースの抽出
29
52
 
53
+ 要件定義テンプレートは `simple-seed` に存在しないため、`style` に関わらず `docs-driven-seed` のテンプレートを使う。
54
+
30
55
  1. `current-system-inventory.md` を起点に、既存機能からユースケースを逆算する
31
- 2. `docs/01_要件定義/要件定義.md` と `docs/02_概要設計/ユースケース一覧.md` の draft を作る
32
- 3. ドメイン用語が識別できたら `docs/01_要件定義/ユビキタス言語辞書.md` も draft する
33
- 4. ユーザーに確認・承認を得る
56
+ 2. `.claude/skills/docs-driven-seed/templates/01_要件定義/要件定義.md` を使い `docs/01_要件定義/要件定義.md` を作る
57
+ 3. `.claude/skills/docs-driven-seed/templates/02_概要設計/ユースケース一覧.md` を使い `docs/02_概要設計/ユースケース一覧.md` を作る
58
+ 4. ドメイン用語が識別できたら `.claude/skills/docs-driven-seed/templates/01_要件定義/ユビキタス言語辞書.md` を使い `docs/01_要件定義/ユビキタス言語辞書.md` を作る
59
+ 5. ユーザーに確認・承認を得る
34
60
 
35
- ## Phase 3: 概要設計の draft 化
61
+ ## Phase 3: 概要設計
36
62
 
37
- 1. `docs/02_概要設計/システム全体俯瞰.md` を作る
38
- 2. `style: ddd` の場合: UC から集約・境界コンテキストを整理し `docs/02_概要設計/ドメインモデル.md` を draft する
39
- 3. 必要なら ADR 候補も洗い出す（配置先は `90_ADR/全体/` / `ドメイン/` / `UC/` / `DB/`）
40
- 4. ユーザーに確認・承認を得る
63
+ `style: ddd` の場合:
64
+
65
+ 1. `.claude/skills/docs-driven-seed/templates/02_概要設計/システム全体俯瞰.md` を使い `docs/02_概要設計/システム全体俯瞰.md` を作る
66
+ 2. `.claude/skills/docs-driven-seed/templates/02_概要設計/ドメインモデル.md` を使い `docs/02_概要設計/ドメインモデル.md` を作る
67
+ 3. 必要なら ADR を作る（作成ルールは下記）
68
+
69
+ `style: layered` の場合:
70
+
71
+ 1. `.claude/skills/simple-seed/templates/02_概要設計/システム全体俯瞰.md` を使い `docs/02_概要設計/システム全体俯瞰.md` を作る
72
+ 2. 必要なら ADR を作る（作成ルールは下記）
73
+
74
+ ### ADR 作成ルール（必要時のみ）
41
75
 
42
- ## Phase 4: 詳細設計の draft 化
76
+ 1. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
77
+ 2. ファイル名は `mmdd-{日本語タイトル}.md`
43
78
 
44
79
  `style: ddd` の場合:
45
80
 
46
- 1. ドメインごとにビジネスルール・集約を整理し `docs/03_詳細設計/01_ドメイン/{ドメイン名}.md` を draft する
47
- 2. UC ごとに `docs/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を draft する
48
- 3. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/03_DB・外部サービス/` を作る
81
+ | 対象 | 配置先 |
82
+ |------|--------|
83
+ | システム横断の決定 | `90_ADR/全体/` |
84
+ | ドメイン設計の決定 | `90_ADR/ドメイン/` |
85
+ | UC フローの決定 | `90_ADR/UC/` |
86
+ | DB・外部サービスの決定 | `90_ADR/DB/` |
49
87
 
50
88
  `style: layered` の場合:
51
89
 
52
- 1. UC ごとに `docs/03_詳細設計/01_ユースケース/UC-{日本語名}.md` を draft する
90
+ | 対象 | 配置先 |
91
+ |------|--------|
92
+ | システム横断の決定 | `90_ADR/全体/` |
93
+ | UC フローの決定 | `90_ADR/UC/` |
94
+ | DB・外部サービスの決定 | `90_ADR/DB/` |
95
+
96
+ 3. 採用案を概要設計へ反映してから次へ進む
97
+
98
+ ユーザーに確認・承認を得る。
99
+
100
+ ## Phase 4: 詳細設計
101
+
102
+ `style: ddd` の場合（ドメイン → UC → DB・外部サービス の順に設計する）:
103
+
104
+ 1. `.claude/skills/docs-driven-seed/templates/03_詳細設計/01_ドメイン/{ドメイン名}.md` を使い、ドメインごとにビジネスルール・集約を整理し `docs/03_詳細設計/01_ドメイン/{ドメイン名}.md` を作る
105
+ 2. `.claude/skills/docs-driven-seed/templates/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を使い、UC ごとに `docs/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を作る（シーケンス図は Mermaid で埋め込む）
106
+ 3. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/03_DB・外部サービス/` を作る
107
+
108
+ `style: layered` の場合（UC → DB・外部サービス の順に設計する）:
109
+
110
+ 1. `.claude/skills/simple-seed/templates/03_詳細設計/01_ユースケース/UC-{日本語名}.md` を使い、UC ごとに `docs/03_詳細設計/01_ユースケース/UC-{日本語名}.md` を作る
53
111
  2. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/02_DB・外部サービス/` を作る
54
112
 
55
- 各ファイルの `maps_to` に対応コードとテストを入れる。ユーザーに確認・承認を得る。
113
+ 各ファイルの `maps_to` に対応コードとテストを必ず入れる。ユーザーに確認・承認を得る。
56
114
 
57
115
  ## Phase 5: architecture contract 化
58
116
 
59
- 1. `.spec-runner/architecture/architecture.yaml` を作る
117
+ 1. `.spec-runner/architecture/architecture.yaml` を完成させる
60
118
  2. 現状構造を project 専用 skill へ渡せる粒度に整える
61
119
  3. `architecture-skill-development` へ引き渡す
62
120
 
63
121
  ## 原則
64
122
 
123
+ - docs は正本。draft であっても `spec_runner` frontmatter とテンプレートを使う
124
+ - `maps_to` は必ず設定する。パス推定に頼らない
65
125
  - 既存コードを正として観測する。推測する場合は明示する
66
- - docs は最初から完璧を目指さず draft として起こす
67
- - `maps_to` と `depends_on` を使って後続変更に耐える形へ整える
126
+ - `depends_on` を使って後続変更に耐える形へ整える
package/spec-runner/templates/.github/instructions/coding.instructions.md CHANGED
@@ -23,10 +23,22 @@ applyTo: "src/**,tests/**"
23
23
 
24
24
  ## コメント
25
25
 
26
+ ### 原則（全プロジェクト共通）
27
+
26
28
  - **言語**: 日本語
27
- - **インラインコメント**: ビジネスロジックの「なぜ」を説明する場合のみ。処理内容の「何」は書かない
28
29
  - **変更履歴コメント禁止**: 変更経緯はコードに書かない。git の commit message で管理する
29
30
 
31
+ ### プロジェクト固有の決定事項
32
+
33
+ > `architecture-skill-development` で以下をチームで合意し、`<...>` を書き換える。
34
+
35
+ - **インラインコメント（なぜ）**: `<ビジネスロジックの判断理由は必ず書く / 任意>`
36
+ - **処理ブロックのコメント（何）**: `<禁止（命名で表現する） / 複雑なフローに限り許可>`
37
+ - **ファイル / モジュールレベルのコメント**: `<必須 / 任意 / 不要>`
38
+ - **関数・クラスの docコメント**: `<常に必須 / 公開 API のみ / 複雑なものだけ / 不要>`
39
+ - **TODO / FIXME マーカー**: `<許可する（課題管理ツールの番号を添える） / 禁止>`
40
+ - **セクション区切りコメント**: `<許可する場合はフォーマットを記載 / 禁止>`
41
+
30
42
  ## 言語・型固有ルール
31
43
 
32
44
  > このセクションを言語・フレームワークに合わせて書き換える。
package/spec-runner/templates/.github/skills/architecture-skill-development/SKILL.md CHANGED
@@ -109,8 +109,10 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
109
109
  `architecture.yaml` の `language` と `folder_structure` を参照して、以下を実際の値に置き換える。
110
110
 
111
111
  1. **命名規則**: 言語の慣習に合わせてテーブルの規則・例を書き換える
112
- 2. **言語・型固有ルール**: `<your-language-and-type-rules>` を言語・フレームワークに合わせた具体的なルールに書き換える
113
- 3. **プロジェクト構造**: `<your-project-structure>` を `folder_structure` の実際のディレクトリ構成に書き換える
112
+ 2. **コメント規約**: `## コメント` の「プロジェクト固有の決定事項」をユーザーと合意してから書き換える
113
+ - インラインコメント（なぜ）・処理ブロック（何）・docコメント・TODO/FIXME・セクション区切りの各方針を決定する
114
+ 3. **言語・型固有ルール**: `<your-language-and-type-rules>` を言語・フレームワークに合わせた具体的なルールに書き換える
115
+ 4. **プロジェクト構造**: `<your-project-structure>` を `folder_structure` の実際のディレクトリ構成に書き換える
114
116
 
115
117
  上記の `integrations` ルールに従って反映する。
116
118
 
package/spec-runner/templates/.github/skills/existing-project-to-docs/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: existing-project-to-docs
3
- description: 既存プロジェクトを読み解き、docs の draft と architecture contract を起こすリバース設計フロー。
3
+ description: 既存プロジェクトを読み解き、docs の正本と architecture contract を起こすリバース設計フロー。
4
4
  ---
5
5
 
6
6
  # existing-project-to-docs
@@ -12,12 +12,24 @@ description: 既存プロジェクトを読み解き、docs の draft と archit
12
12
 
13
13
  ```
14
14
  Phase 1: 現状把握
15
+ Phase 1.5: docs 構成の合意
15
16
  Phase 2: 要件とユースケースの抽出
16
- Phase 3: 概要設計の draft 化
17
- Phase 4: 詳細設計の draft 化
17
+ Phase 3: 概要設計
18
+ Phase 4: 詳細設計
18
19
  Phase 5: architecture contract 化
19
20
  ```
20
21
 
22
+ ## 前提ルール
23
+
24
+ - docs は正本とし、各ドキュメントに `spec_runner` frontmatter を付ける
25
+ - `maps_to` は必ず設定する。パス推定に頼らない
26
+ - 既存コードを正として観測する。推測する場合は明示する
27
+ - ユーザー承認なしに次フェーズへ進めない
28
+ - `style: ddd` の場合: UC がドメインを使う。ドメインの中に UC を入れない
29
+ - `style: ddd` の場合: 詳細設計は `01_ドメイン/` `02_ユースケース/` `03_DB・外部サービス/` の 3 層で構成する
30
+ - `style: layered` の場合: ドメイン層は持たない。ビジネスロジックは UC / サービス層で表現する
31
+ - `style: layered` の場合: 詳細設計は `01_ユースケース/` `02_DB・外部サービス/` の 2 層で構成する
32
+
21
33
  ## Phase 1: 現状把握
22
34
 
23
35
  1. `src/`、`tests/`、設定ファイル、README、IaC を読む
@@ -25,43 +37,90 @@ Phase 5: architecture contract 化
25
37
  3. `.spec-runner/intake/current-system-inventory.md` を作る
26
38
  4. ユーザーに確認・承認を得る
27
39
 
40
+ ## Phase 1.5: docs 構成の合意
41
+
42
+ ファイルを作成する前に、docs の構成をユーザーと合意する。
43
+
44
+ 1. `current-system-inventory.md` を元に以下を提案する
45
+ - `style`（`ddd` / `layered`）
46
+ - `docs/` のフォルダ構成
47
+ - 作成予定ファイルの一覧
48
+ 2. ユーザーに確認・承認を得る
49
+ 3. 承認後、`.spec-runner/architecture/architecture.yaml` を新規作成し `style` だけ先に書き込む（残りは Phase 5 で完成させる）
50
+
28
51
  ## Phase 2: 要件とユースケースの抽出
29
52
 
53
+ 要件定義テンプレートは `simple-seed` に存在しないため、`style` に関わらず `docs-driven-seed` のテンプレートを使う。
54
+
30
55
  1. `current-system-inventory.md` を起点に、既存機能からユースケースを逆算する
31
- 2. `docs/01_要件定義/要件定義.md` と `docs/02_概要設計/ユースケース一覧.md` の draft を作る
32
- 3. ドメイン用語が識別できたら `docs/01_要件定義/ユビキタス言語辞書.md` も draft する
33
- 4. ユーザーに確認・承認を得る
56
+ 2. `.github/skills/docs-driven-seed/templates/01_要件定義/要件定義.md` を使い `docs/01_要件定義/要件定義.md` を作る
57
+ 3. `.github/skills/docs-driven-seed/templates/02_概要設計/ユースケース一覧.md` を使い `docs/02_概要設計/ユースケース一覧.md` を作る
58
+ 4. ドメイン用語が識別できたら `.github/skills/docs-driven-seed/templates/01_要件定義/ユビキタス言語辞書.md` を使い `docs/01_要件定義/ユビキタス言語辞書.md` を作る
59
+ 5. ユーザーに確認・承認を得る
34
60
 
35
- ## Phase 3: 概要設計の draft 化
61
+ ## Phase 3: 概要設計
36
62
 
37
- 1. `docs/02_概要設計/システム全体俯瞰.md` を作る
38
- 2. `style: ddd` の場合: UC から集約・境界コンテキストを整理し `docs/02_概要設計/ドメインモデル.md` を draft する
39
- 3. 必要なら ADR 候補も洗い出す（配置先は `90_ADR/全体/` / `ドメイン/` / `UC/` / `DB/`）
40
- 4. ユーザーに確認・承認を得る
63
+ `style: ddd` の場合:
64
+
65
+ 1. `.github/skills/docs-driven-seed/templates/02_概要設計/システム全体俯瞰.md` を使い `docs/02_概要設計/システム全体俯瞰.md` を作る
66
+ 2. `.github/skills/docs-driven-seed/templates/02_概要設計/ドメインモデル.md` を使い `docs/02_概要設計/ドメインモデル.md` を作る
67
+ 3. 必要なら ADR を作る（作成ルールは下記）
68
+
69
+ `style: layered` の場合:
70
+
71
+ 1. `.github/skills/simple-seed/templates/02_概要設計/システム全体俯瞰.md` を使い `docs/02_概要設計/システム全体俯瞰.md` を作る
72
+ 2. 必要なら ADR を作る（作成ルールは下記）
73
+
74
+ ### ADR 作成ルール（必要時のみ）
41
75
 
42
- ## Phase 4: 詳細設計の draft 化
76
+ 1. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
77
+ 2. ファイル名は `mmdd-{日本語タイトル}.md`
43
78
 
44
79
  `style: ddd` の場合:
45
80
 
46
- 1. ドメインごとにビジネスルール・集約を整理し `docs/03_詳細設計/01_ドメイン/{ドメイン名}.md` を draft する
47
- 2. UC ごとに `docs/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を draft する
48
- 3. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/03_DB・外部サービス/` を作る
81
+ | 対象 | 配置先 |
82
+ |------|--------|
83
+ | システム横断の決定 | `90_ADR/全体/` |
84
+ | ドメイン設計の決定 | `90_ADR/ドメイン/` |
85
+ | UC フローの決定 | `90_ADR/UC/` |
86
+ | DB・外部サービスの決定 | `90_ADR/DB/` |
49
87
 
50
88
  `style: layered` の場合:
51
89
 
52
- 1. UC ごとに `docs/03_詳細設計/01_ユースケース/UC-{日本語名}.md` を draft する
90
+ | 対象 | 配置先 |
91
+ |------|--------|
92
+ | システム横断の決定 | `90_ADR/全体/` |
93
+ | UC フローの決定 | `90_ADR/UC/` |
94
+ | DB・外部サービスの決定 | `90_ADR/DB/` |
95
+
96
+ 3. 採用案を概要設計へ反映してから次へ進む
97
+
98
+ ユーザーに確認・承認を得る。
99
+
100
+ ## Phase 4: 詳細設計
101
+
102
+ `style: ddd` の場合（ドメイン → UC → DB・外部サービス の順に設計する）:
103
+
104
+ 1. `.github/skills/docs-driven-seed/templates/03_詳細設計/01_ドメイン/{ドメイン名}.md` を使い、ドメインごとにビジネスルール・集約を整理し `docs/03_詳細設計/01_ドメイン/{ドメイン名}.md` を作る
105
+ 2. `.github/skills/docs-driven-seed/templates/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を使い、UC ごとに `docs/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を作る（シーケンス図は Mermaid で埋め込む）
106
+ 3. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/03_DB・外部サービス/` を作る
107
+
108
+ `style: layered` の場合（UC → DB・外部サービス の順に設計する）:
109
+
110
+ 1. `.github/skills/simple-seed/templates/03_詳細設計/01_ユースケース/UC-{日本語名}.md` を使い、UC ごとに `docs/03_詳細設計/01_ユースケース/UC-{日本語名}.md` を作る
53
111
  2. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/02_DB・外部サービス/` を作る
54
112
 
55
- 各ファイルの `maps_to` に対応コードとテストを入れる。ユーザーに確認・承認を得る。
113
+ 各ファイルの `maps_to` に対応コードとテストを必ず入れる。ユーザーに確認・承認を得る。
56
114
 
57
115
  ## Phase 5: architecture contract 化
58
116
 
59
- 1. `.spec-runner/architecture/architecture.yaml` を作る
117
+ 1. `.spec-runner/architecture/architecture.yaml` を完成させる
60
118
  2. 現状構造を project 専用 skill へ渡せる粒度に整える
61
119
  3. `architecture-skill-development` へ引き渡す
62
120
 
63
121
  ## 原則
64
122
 
123
+ - docs は正本。draft であっても `spec_runner` frontmatter とテンプレートを使う
124
+ - `maps_to` は必ず設定する。パス推定に頼らない
65
125
  - 既存コードを正として観測する。推測する場合は明示する
66
- - docs は最初から完璧を目指さず draft として起こす
67
- - `maps_to` と `depends_on` を使って後続変更に耐える形へ整える
126
+ - `depends_on` を使って後続変更に耐える形へ整える