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.
- package/package.json +1 -1
- package/spec-runner/templates/.claude/agents/design-reviewer.md +8 -8
- package/spec-runner/templates/.claude/agents/impact-analyzer.md +35 -11
- package/spec-runner/templates/.claude/rules/coding.md +11 -0
- package/spec-runner/templates/.claude/rules/design-docs.md +33 -16
- package/spec-runner/templates/.claude/rules/harness-formats.md +90 -0
- package/spec-runner/templates/.claude/settings.json +15 -0
- package/spec-runner/templates/.claude/skills/architecture-definition/SKILL.md +3 -3
- package/spec-runner/templates/.claude/skills/architecture-skill-development/SKILL.md +12 -7
- package/spec-runner/templates/.claude/skills/design-change/SKILL.md +13 -12
- package/spec-runner/templates/.claude/skills/docs-driven-seed/SKILL.md +140 -0
- 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
- 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
- package/spec-runner/templates/.claude/skills/existing-project-to-docs/SKILL.md +12 -9
- package/spec-runner/templates/.claude/skills/harness-engineering/SKILL.md +4 -0
- package/spec-runner/templates/.claude/skills/test-driven-development/SKILL.md +104 -7
- package/spec-runner/templates/.github/agents/design-reviewer.agent.md +8 -8
- package/spec-runner/templates/.github/agents/impact-analyzer.agent.md +35 -11
- package/spec-runner/templates/.github/instructions/coding.instructions.md +11 -0
- package/spec-runner/templates/.github/instructions/design-docs.instructions.md +33 -16
- package/spec-runner/templates/.github/instructions/harness-formats.instructions.md +84 -0
- package/spec-runner/templates/.github/skills/architecture-definition/SKILL.md +3 -3
- package/spec-runner/templates/.github/skills/architecture-skill-development/SKILL.md +12 -7
- package/spec-runner/templates/.github/skills/design-change/SKILL.md +13 -12
- package/spec-runner/templates/.github/skills/docs-driven-seed/SKILL.md +140 -0
- 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
- 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
- package/spec-runner/templates/.github/skills/existing-project-to-docs/SKILL.md +12 -9
- package/spec-runner/templates/.github/skills/harness-engineering/SKILL.md +4 -0
- package/spec-runner/templates/.github/skills/test-driven-development/SKILL.md +104 -7
- package/spec-runner/templates/.spec-runner/scripts/scan.js +156 -0
- package/spec-runner/templates/.claude/skills/plugin-development/SKILL.md +0 -173
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- package/spec-runner/templates/.github/skills/plugin-development/SKILL.md +0 -173
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
|
-
###
|
|
44
|
+
### docs-driven-seed を種として使う
|
|
43
45
|
|
|
44
|
-
新規開発フローの skill を作る場合は、`
|
|
45
|
-
`
|
|
46
|
+
新規開発フローの skill を作る場合は、`docs-driven-seed` を種として使う。
|
|
47
|
+
`docs-driven-seed` は UC/DDD 駆動の docs 正本開発フローの参照実装であり、
|
|
46
48
|
そのまま使うのではなく、**このプロジェクトのアーキテクチャに合わせて書き換えた project 専用 skill を作る**ことを目的とする。
|
|
47
49
|
|
|
48
50
|
具体的には:
|
|
49
|
-
- `.claude/skills/
|
|
51
|
+
- `.claude/skills/docs-driven-seed/SKILL.md` をコピーして、project 専用の開発 skill の土台にする
|
|
50
52
|
- フェーズ構成・テンプレートパス・用語をこのプロジェクトの実態に合わせて書き換える
|
|
51
|
-
- 元の `
|
|
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
|
-
| `
|
|
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.
|
|
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
|
|
44
|
+
6. ファイル名は `mmdd-{日本語タイトル}.md`、配置先は対象フォルダ
|
|
45
45
|
|
|
46
46
|
### ADR 配置ルール
|
|
47
47
|
|
|
48
|
-
|
|
|
49
|
-
|
|
50
|
-
|
|
|
51
|
-
|
|
|
52
|
-
|
|
53
|
-
|
|
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` /
|
|
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_詳細設計/
|
|
77
|
-
2.
|
|
78
|
-
3.
|
|
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_
|
|
37
|
-
2.
|
|
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_詳細設計/
|
|
43
|
-
2. `
|
|
44
|
-
3.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|