spec-runner 1.3.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.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: existing-project-to-docs
|
|
3
|
-
description: 既存プロジェクトを読み解き、docs
|
|
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:
|
|
17
|
-
Phase 4:
|
|
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.
|
|
32
|
-
3.
|
|
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:
|
|
61
|
+
## Phase 3: 概要設計
|
|
36
62
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
76
|
+
1. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
|
|
77
|
+
2. ファイル名は `mmdd-{日本語タイトル}.md`
|
|
43
78
|
|
|
44
79
|
`style: ddd` の場合:
|
|
45
80
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
67
|
-
- `maps_to` と `depends_on` を使って後続変更に耐える形へ整える
|
|
126
|
+
- `depends_on` を使って後続変更に耐える形へ整える
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: existing-project-to-docs
|
|
3
|
-
description: 既存プロジェクトを読み解き、docs
|
|
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:
|
|
17
|
-
Phase 4:
|
|
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.
|
|
32
|
-
3.
|
|
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:
|
|
61
|
+
## Phase 3: 概要設計
|
|
36
62
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
76
|
+
1. 提案時に必ず 3 案を比較する。ドキュメントには採用案と採用理由のみ記録する
|
|
77
|
+
2. ファイル名は `mmdd-{日本語タイトル}.md`
|
|
43
78
|
|
|
44
79
|
`style: ddd` の場合:
|
|
45
80
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
67
|
-
- `maps_to` と `depends_on` を使って後続変更に耐える形へ整える
|
|
126
|
+
- `depends_on` を使って後続変更に耐える形へ整える
|