spec-runner 1.1.13 → 1.1.16

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 (61) hide show
  1. package/package.json +1 -1
  2. package/spec-runner/templates/.claude/agents/design-reviewer.md +8 -8
  3. package/spec-runner/templates/.claude/agents/impact-analyzer.md +35 -11
  4. package/spec-runner/templates/.claude/rules/coding.md +11 -0
  5. package/spec-runner/templates/.claude/rules/design-docs.md +33 -16
  6. package/spec-runner/templates/.claude/rules/harness-formats.md +90 -0
  7. package/spec-runner/templates/.claude/settings.json +15 -0
  8. package/spec-runner/templates/.claude/skills/architecture-definition/SKILL.md +3 -3
  9. package/spec-runner/templates/.claude/skills/architecture-skill-development/SKILL.md +12 -7
  10. package/spec-runner/templates/.claude/skills/design-change/SKILL.md +13 -12
  11. package/spec-runner/templates/.claude/skills/docs-driven-seed/SKILL.md +140 -0
  12. package/spec-runner/templates/.claude/skills/docs-driven-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/01_/343/203/211/343/203/241/343/202/244/343/203/263/{/343/203/211/343/203/241/343/202/244/343/203/263/345/220/215}.md +39 -0
  13. package/spec-runner/templates/.claude/skills/docs-driven-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/02_/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/UC-{/346/227/245/346/234/254/350/252/236/345/220/215}.md +55 -0
  14. package/spec-runner/templates/.claude/skills/existing-project-to-docs/SKILL.md +12 -9
  15. package/spec-runner/templates/.claude/skills/harness-engineering/SKILL.md +4 -0
  16. package/spec-runner/templates/.claude/skills/test-driven-development/SKILL.md +104 -7
  17. package/spec-runner/templates/.github/agents/design-reviewer.agent.md +8 -8
  18. package/spec-runner/templates/.github/agents/impact-analyzer.agent.md +35 -11
  19. package/spec-runner/templates/.github/instructions/coding.instructions.md +11 -0
  20. package/spec-runner/templates/.github/instructions/design-docs.instructions.md +33 -16
  21. package/spec-runner/templates/.github/instructions/harness-formats.instructions.md +84 -0
  22. package/spec-runner/templates/.github/skills/architecture-definition/SKILL.md +3 -3
  23. package/spec-runner/templates/.github/skills/architecture-skill-development/SKILL.md +12 -7
  24. package/spec-runner/templates/.github/skills/design-change/SKILL.md +13 -12
  25. package/spec-runner/templates/.github/skills/docs-driven-seed/SKILL.md +140 -0
  26. package/spec-runner/templates/.github/skills/docs-driven-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/01_/343/203/211/343/203/241/343/202/244/343/203/263/{/343/203/211/343/203/241/343/202/244/343/203/263/345/220/215}.md +39 -0
  27. package/spec-runner/templates/.github/skills/docs-driven-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/02_/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/UC-{/346/227/245/346/234/254/350/252/236/345/220/215}.md +55 -0
  28. package/spec-runner/templates/.github/skills/existing-project-to-docs/SKILL.md +12 -9
  29. package/spec-runner/templates/.github/skills/harness-engineering/SKILL.md +4 -0
  30. package/spec-runner/templates/.github/skills/test-driven-development/SKILL.md +104 -7
  31. package/spec-runner/templates/.spec-runner/scripts/scan.js +156 -0
  32. package/spec-runner/templates/.claude/skills/plugin-development/SKILL.md +0 -173
  33. package/spec-runner/templates/.claude/skills/plugin-development/templates/01_/350/246/201/344/273/266/345/256/232/347/276/251//346/246/202/350/246/201/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -88
  34. package/spec-runner/templates/.claude/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -81
  35. package/spec-runner/templates/.claude/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/202/267/343/202/271/343/203/206/343/203/240/345/205/250/344/275/223/344/277/257/347/236/260/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -80
  36. package/spec-runner/templates/.claude/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -57
  37. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/aws.md +0 -53
  38. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/database.md +0 -54
  39. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/schema.dbml +0 -25
  40. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/sequence//343/202/267/343/203/274/343/202/261/343/203/263/343/202/271/345/233/263/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -28
  41. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/agent.md +0 -56
  42. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/config.md +0 -47
  43. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/domain.md +0 -67
  44. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/prompts.md +0 -72
  45. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/skills/{skill_name}/skill.md +0 -53
  46. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/tools/{tool_name}/tool.md +0 -51
  47. package/spec-runner/templates/.github/skills/plugin-development/SKILL.md +0 -173
  48. package/spec-runner/templates/.github/skills/plugin-development/templates/01_/350/246/201/344/273/266/345/256/232/347/276/251//346/246/202/350/246/201/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -88
  49. package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -81
  50. package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/202/267/343/202/271/343/203/206/343/203/240/345/205/250/344/275/223/344/277/257/347/236/260/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -80
  51. package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -57
  52. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/aws.md +0 -53
  53. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/database.md +0 -54
  54. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/schema.dbml +0 -25
  55. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/sequence//343/202/267/343/203/274/343/202/261/343/203/263/343/202/271/345/233/263/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +0 -28
  56. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/agent.md +0 -56
  57. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/config.md +0 -47
  58. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/domain.md +0 -67
  59. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/prompts.md +0 -72
  60. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/skills/{skill_name}/skill.md +0 -53
  61. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/tools/{tool_name}/tool.md +0 -51
@@ -35,20 +35,22 @@ Phase 7: セットアップ専用 skill のアーカイブ提案
35
35
 
36
36
  ## Phase 3: skill / rule / template へ分解
37
37
 
38
+ ファイルを作成する前に **`.github/instructions/harness-formats.instructions.md`** を読み、フォーマットを確認する。
39
+
38
40
  1. 会話フローは skill にする
39
41
  2. 常時守る約束は rule にする
40
42
  3. 毎回コピーする設計書は template にする
41
43
 
42
- ### plugin-development を種として使う
44
+ ### docs-driven-seed を種として使う
43
45
 
44
- 新規開発フローの skill を作る場合は、`plugin-development` を種として使う。
45
- `plugin-development` はプラグイン型アーキテクチャ向けの reference workflow であり、
46
+ 新規開発フローの skill を作る場合は、`docs-driven-seed` を種として使う。
47
+ `docs-driven-seed` UC/DDD 駆動の docs 正本開発フローの参照実装であり、
46
48
  そのまま使うのではなく、**このプロジェクトのアーキテクチャに合わせて書き換えた project 専用 skill を作る**ことを目的とする。
47
49
 
48
50
  具体的には:
49
- - `.claude/skills/plugin-development/SKILL.md` をコピーして、project 専用の開発 skill の土台にする
51
+ - `.claude/skills/docs-driven-seed/SKILL.md` をコピーして、project 専用の開発 skill の土台にする
50
52
  - フェーズ構成・テンプレートパス・用語をこのプロジェクトの実態に合わせて書き換える
51
- - 元の `plugin-development` は書き換え完了後にアーカイブ候補とする(Phase 7 で提案する)
53
+ - 元の `docs-driven-seed` は書き換え完了後にアーカイブ候補とする(Phase 7 で提案する)
52
54
 
53
55
  ユーザーに確認・承認を得る
54
56
 
@@ -109,7 +111,7 @@ Phase 7: セットアップ専用 skill のアーカイブ提案
109
111
  |---|---|
110
112
  | `architecture-definition` | 新規プロジェクト初期化専用。アーキテクチャ確定後は不要 |
111
113
  | `existing-project-to-docs` | 既存プロジェクト取り込み専用。docs 生成後は不要 |
112
- | `plugin-development` | Phase 3 で project 専用 skill の種として使い終えたら不要 |
114
+ | `docs-driven-seed` | Phase 3 で project 専用 skill の種として使い終えたら不要 |
113
115
  | `architecture-skill-development`(このファイル自身) | project 専用 skill が安定したら不要。ただしアーキテクチャが大きく変わる場合は再利用する可能性があるため、削除ではなくアーカイブを推奨 |
114
116
 
115
117
  ### 手順
@@ -117,7 +119,10 @@ Phase 7: セットアップ専用 skill のアーカイブ提案
117
119
  1. 上記の候補をユーザーに提示し、整理してよいか確認する
118
120
  2. 承認を得た skill を `.claude/skills/` と `.github/skills/` から削除する
119
121
  3. 必要であれば削除前にバックアップ先をユーザーに伝える
120
- 4. `CLAUDE.md` を更新する
122
+ 4. `.spec-runner/` の不要ファイルも整理する
123
+ - `intake/current-system-inventory.md` — docs に昇格済みなら削除してよい
124
+ - `architecture/architecture.yaml` — project 専用 skill が完成し、参照不要になったら削除してよい
125
+ 5. `CLAUDE.md` を更新する
121
126
  - 「初回自動起動」セクション(spec-runner インストール時に生成されたもの)を削除する
122
127
  - 作成した project 専用 skill の名前と使いどころを記載する
123
128
  - 例:
@@ -41,16 +41,16 @@ Phase 6: TDD → 実装 → 検証
41
41
  3. 各案について概要・メリット・デメリット・適合性を示す
42
42
  4. ユーザーが案を決定する
43
43
  5. テンプレート `templates/90_ADR/ADRテンプレート.md` をコピーして生成する
44
- 6. ファイル名は `mmdd-{日本語タイトル}.md` 形式にする(例: `0404-キャッシュ戦略の変更.md`)
44
+ 6. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は対象フォルダ
45
45
 
46
46
  ### ADR 配置ルール
47
47
 
48
- | 変更スコープ | 配置先 |
49
- |------------|--------|
50
- | 横断的な決定 | `docs/02_概要設計/90_ADR/` |
51
- | 特定ドメイン寄りの決定 | `docs/02_概要設計/<ドメイン>/90_ADR/` |
52
-
53
- MVP では `docs/02_概要設計/90_ADR/` に集約する。
48
+ | 対象 | 配置先 |
49
+ |------|--------|
50
+ | システム横断の決定 | `docs/02_概要設計/90_ADR/全体/` |
51
+ | ドメイン設計の決定 | `docs/02_概要設計/90_ADR/ドメイン/` |
52
+ | UC フローの決定 | `docs/02_概要設計/90_ADR/UC/` |
53
+ | DB・外部サービスの決定 | `docs/02_概要設計/90_ADR/DB/` |
54
54
 
55
55
  ## Phase 3: 影響ドキュメントの確定
56
56
 
@@ -62,7 +62,7 @@ MVP では `docs/02_概要設計/90_ADR/` に集約する。
62
62
 
63
63
  ## Phase 4: 概要設計の修正
64
64
 
65
- 1. `ユースケース一覧.md` / `システム全体俯瞰.md` / UC 個別文書 / ADR を必要順に修正する
65
+ 1. `ユースケース一覧.md` / `システム全体俯瞰.md` / `ドメインモデル.md` / ADR を必要順に修正する
66
66
  2. 修正完了ごとにチェックリストを更新する
67
67
  3. 全概要設計の修正完了後、ユーザーに確認・承認を得る
68
68
 
@@ -73,10 +73,11 @@ MVP では `docs/02_概要設計/90_ADR/` に集約する。
73
73
 
74
74
  ## Phase 5: 詳細設計の修正
75
75
 
76
- 1. `docs/03_詳細設計/src/**` を `src/` ミラーで修正する
77
- 2. 補助設計が必要な場合だけ `docs/03_詳細設計/infrastructure/**` を修正する
78
- 3. frontmatter `depends_on` / `maps_to` を更新する
79
- 4. ユーザーに最終確認を得る
76
+ 1. `docs/03_詳細設計/01_ドメイン/**` のドメイン設計を修正する
77
+ 2. `docs/03_詳細設計/02_ユースケース/**` の UC 設計を修正する
78
+ 3. DB・外部サービスの変更がある場合は `docs/03_詳細設計/03_DB・外部サービス/**` を修正する
79
+ 4. frontmatter の `depends_on` / `maps_to` を更新する
80
+ 5. ユーザーに最終確認を得る
80
81
 
81
82
  ## Phase 6: TDD → 実装 → 検証
82
83
 
@@ -0,0 +1,140 @@
1
+ ---
2
+ name: docs-driven-seed
3
+ description: UC/DDD 駆動の docs 正本開発フローの種。新規プロジェクトの初期テンプレートとして使い、architecture-skill-development でプロジェクト専用スキルに育てる。
4
+ ---
5
+
6
+ # docs-driven-seed
7
+
8
+ UC/DDD 駆動の docs 正本開発フローの**参照実装(種)**。
9
+ プロジェクト固有のスキルに育てる前の出発点として使う。
10
+
11
+ **このスキルをそのまま使い続けない。`architecture-skill-development` で自プロジェクト専用スキルに育てることを前提とする。**
12
+
13
+ ## 全体フロー
14
+
15
+ ```
16
+ Phase 1: 要件定義
17
+ Phase 2: 概要設計(ユースケース + ドメインモデル)
18
+ Phase 3: ADR(必要時のみ)
19
+ Phase 4: 詳細設計(ドメイン → UC → DB・外部サービス)
20
+ Phase 5: TDD → 実装
21
+ ```
22
+
23
+ ## 前提ルール
24
+
25
+ - docs は正本とし、各ドキュメントに `spec_runner` frontmatter を付ける
26
+ - 詳細設計は `01_ドメイン/` `02_ユースケース/` `03_DB・外部サービス/` の 3 層で構成する
27
+ - UC がドメインを使う。ドメインの中に UC は入れない
28
+ - `maps_to` は必ず設定する。パス推定に頼らない
29
+ - ユーザー承認なしに次フェーズへ進めない
30
+
31
+ ## Phase 1: 要件定義
32
+
33
+ 1. 以下をユーザーにヒアリングする
34
+ - 解決すべき課題・提供価値
35
+ - 対象ユーザー
36
+ - 非機能要件・スコープ外
37
+ - 技術・ビジネス制約
38
+ 2. `docs/01_要件定義/要件定義.md` を作る
39
+ 3. ドメイン用語が出てきたら `docs/01_要件定義/ユビキタス言語辞書.md` に随時追記する
40
+ 4. ユーザーに確認・承認を得る
41
+
42
+ ### 出力
43
+
44
+ ```
45
+ docs/01_要件定義/
46
+ 要件定義.md
47
+ ユビキタス言語辞書.md
48
+ ```
49
+
50
+ ## Phase 2: 概要設計
51
+
52
+ ### 2-1. ユースケース一覧
53
+
54
+ 1. 要件定義からユースケースを洗い出す(Query / Command を意識)
55
+ 2. `docs/02_概要設計/ユースケース一覧.md` を作る
56
+ 3. ユーザーに確認・承認を得る
57
+
58
+ ### 2-2. ドメインモデル + システム全体俯瞰
59
+
60
+ 1. UC から集約・境界コンテキストを整理し `docs/02_概要設計/ドメインモデル.md` を作る
61
+ 2. コンポーネント全体図・外部 IF を整理し `docs/02_概要設計/システム全体俯瞰.md` を作る
62
+ 3. ユーザーに確認・承認を得る
63
+
64
+ ### 出力
65
+
66
+ ```
67
+ docs/02_概要設計/
68
+ ユースケース一覧.md
69
+ ドメインモデル.md
70
+ システム全体俯瞰.md
71
+ 90_ADR/
72
+ 全体/
73
+ ドメイン/
74
+ UC/
75
+ DB/
76
+ ```
77
+
78
+ ## Phase 3: ADR(必要時のみ)
79
+
80
+ 1. 設計判断が必要な場合だけ ADR を作る
81
+ 2. **必ず 3 案を比較する**
82
+ 3. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は対象フォルダ
83
+
84
+ | 対象 | 配置先 |
85
+ |------|--------|
86
+ | システム横断の決定 | `90_ADR/全体/` |
87
+ | ドメイン設計の決定 | `90_ADR/ドメイン/` |
88
+ | UC フローの決定 | `90_ADR/UC/` |
89
+ | DB・外部サービスの決定 | `90_ADR/DB/` |
90
+
91
+ 4. 採用案を概要設計へ反映してから次へ進む
92
+
93
+ ## Phase 4: 詳細設計
94
+
95
+ **ドメイン → UC → DB・外部サービス の順に設計する。**
96
+
97
+ ### 4-1. ドメイン
98
+
99
+ テンプレート: `templates/03_詳細設計/01_ドメイン/{ドメイン名}.md`
100
+
101
+ ```
102
+ docs/03_詳細設計/01_ドメイン/
103
+ {ドメイン名}.md
104
+ ```
105
+
106
+ ### 4-2. ユースケース
107
+
108
+ シーケンス図は UC ファイルに Mermaid で埋め込む。
109
+
110
+ テンプレート: `templates/03_詳細設計/02_ユースケース/UC-{日本語名}.md`
111
+
112
+ ```
113
+ docs/03_詳細設計/02_ユースケース/
114
+ UC-{日本語名}.md
115
+ ```
116
+
117
+ ### 4-3. DB・外部サービス(必要時のみ)
118
+
119
+ ```
120
+ docs/03_詳細設計/03_DB・外部サービス/
121
+ スキーマ定義.dbml
122
+ 外部サービス.md
123
+ ```
124
+
125
+ ユーザーに確認・承認を得る
126
+
127
+ ## Phase 5: TDD → 実装
128
+
129
+ `test-driven-development` スキルへ移行する。
130
+
131
+ ### 実装完了後
132
+
133
+ - `@design-reviewer` — 設計書⇔実装の整合性チェック
134
+ - `@code-reviewer` — コーディング規約への適合チェック
135
+
136
+ ## 原則
137
+
138
+ - **このスキルは種。`architecture-skill-development` でプロジェクト専用スキルに育てることを前提とする**
139
+ - **ドメインを先に設計し、UC はドメインを参照する形で書く**
140
+ - **`maps_to` は必ず設定する。パス推定に頼らない**
@@ -0,0 +1,39 @@
1
+ ---
2
+ spec_runner:
3
+ node_id: detail.domain.{ドメイン名}
4
+ kind: detailed_design
5
+ depends_on:
6
+ - overview.domain_model
7
+ maps_to:
8
+ - src/domain/{ドメイン名}/
9
+ ---
10
+
11
+ # {ドメイン名} ドメイン詳細設計
12
+
13
+ ## 責務
14
+
15
+ - {このドメインが扱うビジネス概念}
16
+ - {このドメインの不変条件・制約}
17
+
18
+ ## 集約
19
+
20
+ | 集約 | 責務 | ルートエンティティ |
21
+ |------|------|----------------|
22
+ | {集約名} | {責務} | {ルートエンティティ名} |
23
+
24
+ ## 値オブジェクト
25
+
26
+ | 値オブジェクト | 制約・ルール |
27
+ |--------------|------------|
28
+ | {名前} | {制約} |
29
+
30
+ ## ドメインルール
31
+
32
+ - {ルール1}
33
+ - {ルール2}
34
+
35
+ ## テスト観点
36
+
37
+ - {正常系の観点}
38
+ - {ルール違反の観点}
39
+ - {境界条件の観点}
@@ -0,0 +1,55 @@
1
+ ---
2
+ spec_runner:
3
+ node_id: detail.usecase.{UC名}
4
+ kind: detailed_design
5
+ depends_on:
6
+ - overview.use_case_list
7
+ - detail.domain.{ドメイン名}
8
+ maps_to:
9
+ - src/application/{uc_name}/
10
+ - tests/application/{uc_name}/
11
+ ---
12
+
13
+ # UC-{UC名} 詳細設計
14
+
15
+ ## 概要
16
+
17
+ - 使用するドメイン: {ドメイン名}
18
+ - トリガー: {何がこのUCを呼び出すか}
19
+ - 事前条件: {UCが成立するために必要な状態}
20
+ - 事後条件: {UC完了後の状態}
21
+
22
+ ## 入出力
23
+
24
+ | 種別 | 名前 | 型 | 説明 |
25
+ |------|------|----|------|
26
+ | 入力 | {入力名} | {型} | {説明} |
27
+ | 出力 | {出力名} | {型} | {説明} |
28
+
29
+ ## 主要フロー
30
+
31
+ ```mermaid
32
+ sequenceDiagram
33
+ {シーケンス図}
34
+ ```
35
+
36
+ 1. {ステップ1}
37
+ 2. {ステップ2}
38
+
39
+ ## 判断条件
40
+
41
+ | 判断ポイント | 条件 | アクション |
42
+ |------------|------|----------|
43
+ | {判断ポイント} | {条件} | {アクション} |
44
+
45
+ ## エラーポリシー
46
+
47
+ | エラーケース | 発生条件 | 対応 |
48
+ |------------|---------|------|
49
+ | {エラーケース} | {発生条件} | {対応} |
50
+
51
+ ## テスト観点
52
+
53
+ - {正常系の観点}
54
+ - {異常系の観点}
55
+ - {境界条件の観点}
@@ -27,22 +27,25 @@ Phase 5: architecture contract 化
27
27
 
28
28
  ## Phase 2: 要件とユースケースの抽出
29
29
 
30
- 1. 既存機能からユースケースを逆算する
30
+ 1. `current-system-inventory.md` を起点に、既存機能からユースケースを逆算する
31
31
  2. `docs/01_要件定義/要件定義.md` と `docs/02_概要設計/ユースケース一覧.md` の draft を作る
32
- 3. ユーザーに確認・承認を得る
32
+ 3. ドメイン用語が識別できたら `docs/01_要件定義/ユビキタス言語辞書.md` も draft する
33
+ 4. ユーザーに確認・承認を得る
33
34
 
34
35
  ## Phase 3: 概要設計の draft 化
35
36
 
36
- 1. `docs/02_概要設計/システム全体俯瞰.md` を作る
37
- 2. 必要なら ADR 候補も洗い出す
38
- 3. ユーザーに確認・承認を得る
37
+ 1. UC から集約・境界コンテキストを整理し `docs/02_概要設計/ドメインモデル.md` を draft する
38
+ 2. `docs/02_概要設計/システム全体俯瞰.md` を作る
39
+ 3. 必要なら ADR 候補も洗い出す(配置先は `90_ADR/全体/` / `ドメイン/` / `UC/` / `DB/`)
40
+ 4. ユーザーに確認・承認を得る
39
41
 
40
42
  ## Phase 4: 詳細設計の draft 化
41
43
 
42
- 1. `docs/03_詳細設計/src/**``src/` ミラーで作る
43
- 2. `maps_to` に対応コードとテストを入れる
44
- 3. 補助設計が必要なら `docs/03_詳細設計/infrastructure/**` を作る
45
- 4. ユーザーに確認・承認を得る
44
+ 1. ドメインごとにビジネスルール・集約を整理し `docs/03_詳細設計/01_ドメイン/{ドメイン名}.md`draft する
45
+ 2. UC ごとに `docs/03_詳細設計/02_ユースケース/UC-{日本語名}.md` を draft する
46
+ 3. DB・外部サービスの仕様が必要なら `docs/03_詳細設計/03_DB・外部サービス/` を作る
47
+ 4. 各ファイルの `maps_to` に対応コードとテストを入れる
48
+ 5. ユーザーに確認・承認を得る
46
49
 
47
50
  ## Phase 5: architecture contract 化
48
51
 
@@ -68,6 +68,8 @@ Phase 4: 影響範囲の反映確認
68
68
 
69
69
  ## Phase 3: skill / rule / agent / template の修正
70
70
 
71
+ ファイルを作成・修正する前に **`.github/instructions/harness-formats.instructions.md`** を読み、フォーマットを確認する。
72
+
71
73
  1. 対象ファイルを特定する
72
74
  2. 意図が変わらない最小差分で修正する
73
75
  3. 片系だけでなく、対応するテンプレートも揃えて更新する
@@ -91,6 +93,8 @@ Phase 4: 影響範囲の反映確認
91
93
  - Claude / Copilot の対応ファイルに反映漏れがないか
92
94
  - 今回限りのノイズをルール化していないか
93
95
  - skill 名・起動条件・使いどころを変更した場合、`CLAUDE.md` の記述と一致しているか
96
+ - `CLAUDE.md` が肥大化していないか(20行超えたら `instructions/` や `skills/` へ移動を検討する)
97
+ - docs 構造・命名規則・node_id 体系に影響する変更の場合、`design-docs.instructions.md` と整合しているか
94
98
 
95
99
  ## 原則
96
100
 
@@ -26,13 +26,89 @@ description: 新機能実装やバグ修正を行う際、実装コードを書
26
26
  テストより先にコードを書いたなら削除して最初からやり直す。
27
27
  「参考として残す」も「テストを書きながら適応させる」も不可。
28
28
 
29
+ ## テスト戦略:テストピラミッド
30
+
31
+ 実装前にどのテスト種別を書くかを決める。迷ったら**単体テストから始める**。
32
+
33
+ ```
34
+ /\
35
+ /E2E\ 少数・遅い・ユーザーシナリオ全体
36
+ /------\
37
+ / 結合 \ 中程度・モジュール間連携・外部境界
38
+ /----------\
39
+ / 単体 \ 多数・高速・関数・クラス単位
40
+ /______________\
41
+ ```
42
+
43
+ ### 単体テスト(Unit)
44
+
45
+ **対象:** 関数・クラス・モジュールの振る舞い(外部依存なし)
46
+
47
+ **書くとき:**
48
+ - ビジネスロジック・計算・変換処理
49
+ - エラー処理・バリデーション
50
+ - 状態変化(純粋関数・値オブジェクト)
51
+
52
+ **外部依存の扱い:** 実際に遅い・副作用がある依存のみモック。それ以外は実物を使う。
53
+
54
+ **速度目安:** ミリ秒単位。CI で毎回全件実行できる。
55
+
56
+ ### 結合テスト(Integration)
57
+
58
+ **対象:** 複数モジュールの連携、DB・キャッシュ・外部APIとの境界
59
+
60
+ **書くとき:**
61
+ - DB へのクエリ・永続化
62
+ - 外部サービス呼び出し(HTTP, メッセージキュー等)
63
+ - 複数の集約をまたぐユースケース
64
+
65
+ **外部依存の扱い:** 原則として実物を使う(テスト用 DB、テスト環境の外部サービス)。
66
+ 動かせない外部サービスのみスタブ/フェイクで代替する。
67
+
68
+ **速度目安:** 秒単位。PR ごとに実行できる。
69
+
70
+ ### E2E テスト
71
+
72
+ **対象:** ユーザーが実際に操作するシナリオ全体(UI から DB まで)
73
+
74
+ **書くとき:**
75
+ - 最重要のユーザーシナリオ(ハッピーパス)
76
+ - リグレッションが致命的な機能(決済・認証等)
77
+
78
+ **数を絞る:** E2E は維持コストが高い。書く前に「単体+結合で代替できないか?」を問う。
79
+
80
+ **速度目安:** 分単位。夜間や本番リリース前など頻度を落として実行。
81
+
82
+ ## テスト種別の選び方
83
+
84
+ | 実装するもの | まず書くテスト | 追加で書くテスト |
85
+ |---|---|---|
86
+ | ロジック・計算 | 単体 | — |
87
+ | DB 操作 | 結合 | — |
88
+ | API エンドポイント | 結合 | 主要シナリオは E2E |
89
+ | 複数サービスをまたぐフロー | 結合 | — |
90
+ | ユーザー向け主要機能 | 単体+結合 | E2E(絞る) |
91
+ | バグ修正 | 最小レベルで再現テスト | — |
92
+
93
+ **バグ修正の場合:** バグを再現できる最も低いレベルのテストを書く。
94
+ 単体で再現できるなら単体、DBが絡むなら結合。E2E で初めて再現するバグは、単体・結合に落とし込めないか検討する。
95
+
29
96
  ## テスト実行コマンド
30
97
 
31
98
  > このスキルはテンプレートとして配布されます。
32
99
  > `architecture-skill-development` を使ってプロジェクト固有のコマンドに書き換えてください。
33
100
 
34
101
  ```bash
35
- # 全テスト(プロジェクトのテストコマンドに置き換える)
102
+ # 単体テスト(高速・毎回実行)
103
+ <your-unit-test-command>
104
+
105
+ # 結合テスト
106
+ <your-integration-test-command>
107
+
108
+ # E2E テスト
109
+ <your-e2e-test-command>
110
+
111
+ # 全テスト
36
112
  <your-test-command>
37
113
 
38
114
  # 特定ファイル
@@ -46,7 +122,7 @@ description: 新機能実装やバグ修正を行う際、実装コードを書
46
122
 
47
123
  ### RED - 失敗するテストを書く
48
124
 
49
- 起きてほしいことを示す、最小のテストを1つ書く。
125
+ テスト種別を決めたうえで、起きてほしいことを示す最小のテストを1つ書く。
50
126
 
51
127
  ```
52
128
  // 例(言語・フレームワークはプロジェクトに合わせる)
@@ -93,7 +169,7 @@ test("ある入力に対して期待する出力を返す", () => {
93
169
  `@test-runner` エージェントに委任して実行する。
94
170
 
95
171
  - テストが通る
96
- - **他のテストも全て通る**
172
+ - **同種のテストが全て通る**(単体なら単体全件、結合なら結合全件)
97
173
  - 出力がクリーン(エラー、警告なし)
98
174
  - **カバレッジの未カバー行を確認** — 新規コードが未カバーなら追加テストを書く
99
175
 
@@ -122,18 +198,34 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
122
198
 
123
199
  ## テスト構成
124
200
 
125
- テストファイルは `src/` と同じディレクトリ構造を `tests/` に鏡写しにする。
201
+ ```
202
+ tests/
203
+ unit/ # 単体テスト(src/ と同じ構造を鏡写し)
204
+ integration/ # 結合テスト
205
+ e2e/ # E2E テスト
206
+ ```
207
+
208
+ テストファイルは `src/` と同じディレクトリ構造を各テスト種別のディレクトリ内に鏡写しにする。
126
209
 
127
210
  ## fixture / テストデータの活用
128
211
 
129
212
  - テストごとに独立した状態を持つ
130
213
  - テストデータ生成にはヘルパ関数を定義して一貫性を保つ
131
214
  - 外部サービス(API・メール・ストレージ等)は必要な場合のみモックする
215
+ - 結合テスト用のシードデータは `tests/integration/fixtures/` に置く
132
216
 
133
217
  ## モックのルール
134
218
 
135
219
  モックは分離の手段であり、テスト対象ではない。
136
220
 
221
+ **テスト種別ごとのモック方針:**
222
+
223
+ | テスト種別 | 原則 |
224
+ |---|---|
225
+ | 単体 | 外部 I/O(DB・HTTP・ファイル)のみモック可。ビジネスロジックはモックしない |
226
+ | 結合 | 実物の外部依存を使う。動かせない外部サービスのみスタブ可 |
227
+ | E2E | モックしない。全て実物 |
228
+
137
229
  **モック前の自問:**
138
230
  1. 「実メソッドにはどんな副作用があるか?」
139
231
  2. 「このテストはその副作用に依存しているか?」
@@ -168,6 +260,8 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
168
260
  | テスト前にコードを書いた | コードを削除し、TDDで最初からやり直す |
169
261
  | テストが最初から通る | 既存挙動をテストしている。テストを修正する |
170
262
  | なぜ失敗したか説明できない | テストが正しいか再検討する |
263
+ | 全部 E2E で書いた | ピラミッドが逆転している。単体・結合に落とし込む |
264
+ | 全部モックだらけ | 結合が強すぎる。または結合テストを書くべき |
171
265
 
172
266
  **どれか1つでも当てはまるなら: コードを削除し、TDDで最初からやり直す。**
173
267
 
@@ -180,14 +274,15 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
180
274
 
181
275
  完了宣言の前に:
182
276
 
277
+ - [ ] 実装前にテスト種別(単体・結合・E2E)を決めた
183
278
  - [ ] 新規関数/メソッドにテストがある
184
279
  - [ ] 各テストは実装前に失敗するのを見た
185
280
  - [ ] 期待通りの理由で失敗した(機能不足であり誤字ではない)
186
281
  - [ ] 通す最小コードを書いた
187
- - [ ] 全テストが通る
282
+ - [ ] 同種のテストが全件通る
188
283
  - [ ] 出力がクリーン(エラー、警告なし)
189
284
  - [ ] カバレッジを確認し、新規コードの未カバー行がない
190
- - [ ] 実コード中心(不可避な場合のみモック)
285
+ - [ ] モック方針がテスト種別に合っている
191
286
  - [ ] エッジケースとエラーをカバーした
192
287
 
193
288
  すべてにチェックできないならTDDを飛ばしている。やり直すこと。
@@ -197,9 +292,11 @@ GREEN / REFACTORフェーズで書く実装コードにもビジネスロジッ
197
292
  | 問題 | 解決 |
198
293
  |------|------|
199
294
  | どうテストすべきか分からない | 望むAPIを書き、まずアサーションを書く。ユーザーに相談する |
295
+ | どのテスト種別か迷う | 単体から始める。単体で書けないなら結合を検討する |
200
296
  | テストが複雑すぎる | 設計が複雑すぎる。インターフェースを簡素化する |
201
- | 何でもモック必須 | 結合が強すぎる。依存性注入を使う |
297
+ | 何でもモック必須 | 結合が強すぎる。依存性注入を使う。または結合テストで書く |
202
298
  | セットアップが巨大 | fixtureやテストユーティリティに抽出する。それでも大きいなら設計を簡素化する |
299
+ | E2E が遅すぎる | 単体・結合に落とし込めるか検討する |
203
300
 
204
301
  ## 最終ルール
205
302