@careerchain/stdd 0.1.2 → 0.1.3

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 (9) hide show
  1. package/assets/.claude/skills/documenting-specifications/SKILL.md +49 -0
  2. package/assets/.claude/skills/documenting-specifications/templates/architecture-common.md +1 -1
  3. package/assets/.claude/skills/documenting-specifications/templates/table-definition-common.md +1 -1
  4. package/assets/.claude/skills/introducing-stdd/SKILL.md +3 -3
  5. package/assets/.claude/skills/introducing-stdd/templates/introduction-plan.md +1 -1
  6. package/assets/.claude/skills/reverse-engineering-common-spec/SKILL.md +4 -4
  7. package/assets/.claude/skills/starting-new-with-stdd/SKILL.md +2 -2
  8. package/assets/.claude/skills/starting-new-with-stdd/templates/bootstrap-plan.md +4 -4
  9. package/package.json +1 -1
package/assets/.claude/skills/documenting-specifications/SKILL.md CHANGED
@@ -169,6 +169,55 @@ HTMLテンプレートは `lib/email/templates/` で管理。
169
169
 
170
170
  ---
171
171
 
172
+ ## 要確認マーカー（不明点は仮説とセットで明示する）
173
+
174
+ Spec を書く過程で、確信が持てない／ユーザーに確定してもらう必要がある箇所は、**章を省略したり空欄にしたりせず**、その箇所に **要確認マーカー** を置く。テンプレートの章構成は常に維持し、埋められない部分も「仮説＋要確認」で埋めることで spec の**網羅性を担保**する。
175
+
176
+ > このマーカーは STDD 全体で**唯一の確認用マーカー**。前方設計（新規・`starting-new-with-stdd`）／逆生成（既存・`reverse-engineering-*`）でも同じ構文を使う。各スキルはここを正典として参照する。
177
+
178
+ ### 唯一の構文（可視インライン）
179
+
180
+ - 標準形（箇条書き・段落の直下）:
181
+
182
+ ```markdown
183
+ **⚠️要確認**｜仮説: <現時点で最も妥当と考える答え>／確認: <ユーザーに是非を確かめたいこと>
184
+ ```
185
+
186
+ - 表・行内の短縮形:
187
+
188
+ ```markdown
189
+ | 認証 | Supabase Auth ⚠️要確認(仮説: メール＋OAuth で足りる / 確認: SSO 要件の有無) |
190
+ ```
191
+
192
+ 旧来の `<!-- 未決: ... -->` / `<!-- 要確認: ... -->` / `※要確認` は**使わない**。マーカーは要確認マーカーに一本化する。
193
+
194
+ ### 3 つのルール
195
+
196
+ 1. **必ず仮説とセット**。「要確認」だけを単独で置かない。不明点はまず現時点で最も妥当な**仮説**を立て、その**是非をユーザーに確認させる**形にする（深掘りヒアリングの代わりに、仮説提示で前進する）。
197
+ 2. **章は省略しない**。テンプレートの構成を維持し、情報が無い箇所も仮説＋要確認マーカーで埋める。空欄・章削除による「見かけ上の完成」を作らない。
198
+ 3. **可視・一時的**。マーカーはレンダリングで見える一時注記。ユーザーが是非を確定したら、仮説を確定値に書き換えてマーカーを除去する。確定済み spec にマーカーを残さない（SSoT 原則）。
199
+
200
+ ### 例
201
+
202
+ ✅ 良い例（仮説とセット・章を保つ）:
203
+
204
+ ```markdown
205
+ ### 想定スケール
206
+
207
+ 初期は同時接続 100 程度を想定。
208
+ **⚠️要確認**｜仮説: ローンチ後 3 ヶ月で MAU 1,000 規模／確認: 想定ユーザー数と成長見込み。
209
+ ```
210
+
211
+ ❌ 悪い例（仮説が無い・章を消す）:
212
+
213
+ ```markdown
214
+ ### 想定スケール
215
+
216
+ **⚠️要確認** ← 仮説が無い。何を確認したいかも不明
217
+ ```
218
+
219
+ ---
220
+
172
221
  ## 基本原則
173
222
 
174
223
  ### REQUIREMENTS.md（要件定義書）
package/assets/.claude/skills/documenting-specifications/templates/architecture-common.md CHANGED
@@ -29,7 +29,7 @@
29
29
 
30
30
  ## 確度マーカーの運用
31
31
 
32
- - 実装・ヒアリングから確信が持てない箇所は `※要確認` を文末に付す（リバース直後・前方設計時など）。確定後に除去する。
32
+ - 実装・ヒアリングから確信が持てない箇所は **要確認マーカー** を置く（リバース直後・前方設計時など）。必ず**仮説とセット**で `**⚠️要確認**｜仮説: … ／確認: …`（表・行内は `⚠️要確認(仮説: … / 確認: …)`）の形にし、ユーザーが是非を確定したら除去する。構文の正典は [documenting-specifications SKILL「要確認マーカー」](../SKILL.md) を参照。
33
33
  - 指標やデータの確からしさを区別する場合は `[可]`（直接算出可能）/ `[近似]`（代理母集団・近似指標）等のマークを併記する。
34
34
 
35
35
  ## テンプレート構造
package/assets/.claude/skills/documenting-specifications/templates/table-definition-common.md CHANGED
@@ -19,7 +19,7 @@
19
19
 
20
20
  ## 確度マーカーの運用
21
21
 
22
- - 確信が持てないカラム・型は説明欄に `※要確認` を付す。確定後に除去する。
22
+ - 確信が持てないカラム・型は、説明欄に **要確認マーカー** を仮説とセットで置く（`⚠️要確認(仮説: … / 確認: …)`）。ユーザーが是非を確定したら除去する。構文の正典は [documenting-specifications SKILL「要確認マーカー」](../SKILL.md) を参照。
23
23
 
24
24
  ## テンプレート構造
25
25
 
package/assets/.claude/skills/introducing-stdd/SKILL.md CHANGED
@@ -47,7 +47,7 @@ docs/common/plans/stdd-introduction.md
47
47
  | step | 実行内容 | 呼ぶスキル | ★停止して確認 |
48
48
  | ---- | -------- | ---------- | ------------- |
49
49
  | 0 | `.stdd.config.yml` を対話的に作成（下記「step 0」詳細）/ テンプレ・skill 配置 | — | 構成（単一/複数アプリ・パス規約） |
50
- | 1 | common ティア生成 | `reverse-engineering-common-spec` | 生成後の `<!-- 要確認 -->` 一覧 |
50
+ | 1 | common ティア生成 | `reverse-engineering-common-spec` | 生成後の**要確認マーカー**一覧 |
51
51
  | 1.5 | 機能インベントリ + 優先順 → 導入PLAN へ記載 | — | ★ 機能一覧と優先順（P0 から） |
52
52
  | 2 | 代表機能 1 つをリバース | `reverse-engineering-feature-spec` | ★ Spec 粒度・スコープ |
53
53
  | 3-4 | フォーマット策定 → テンプレ特化 | `tailoring-spec-format` | ★★ フォーマット決定（テーラリング） |
@@ -62,7 +62,7 @@ docs/common/plans/stdd-introduction.md
62
62
 
63
63
  1. **プロジェクト点検**: ディレクトリ構成・`package.json`・ルーティングをざっと把握。
64
64
  2. **step 0（対話的セットアップ）**: `.stdd.config.yml` が無ければ、下記「step 0」手順で 点検 → 草案 → 確認 → 書き込み を対話的に行う。
65
- 3. **step 1 実行**: `reverse-engineering-common-spec` を呼び、common ティアを生成。`<!-- 要確認 -->` を一覧化して人間に提示。
65
+ 3. **step 1 実行**: `reverse-engineering-common-spec` を呼び、common ティアを生成。**要確認マーカー**（仮説つき）を一覧化して人間に提示。
66
66
  4. **step 1.5（★人間判断）**: ルーティング・主要ドメインから機能を洗い出し、**優先順をユーザーと合意**。
67
67
  5. **導入PLAN 生成**: `templates/introduction-plan.md` を雛形に `docs/common/plans/stdd-introduction.md` を作成し、機能を優先順で並べる。
68
68
  6. 「次は step 2（代表機能のリバース）」を提示して停止。
@@ -100,7 +100,7 @@ docs/common/plans/stdd-introduction.md
100
100
 
101
101
  ### 0-2. 草案を提示
102
102
 
103
- 点検結果から `.stdd.config.yml` の草案を生成して提示する。先頭に `yaml-language-server` の schema ディレクティブを付ける。**推定できなかった項目は「要確認」として明示し、ユーザーに尋ねる**。
103
+ 点検結果から `.stdd.config.yml` の草案を生成して提示する。先頭に `yaml-language-server` の schema ディレクティブを付ける。**推定し切れない項目も空欄にせず、推定値（仮説）を入れた上でコメントに `# ⚠️要確認: …` を添えてユーザーに是非を尋ねる**（spec の[要確認マーカー](../documenting-specifications/SKILL.md)と同じ「仮説＋確認」の原則を config 草案にも適用）。
104
104
 
105
105
  ```yaml
106
106
  # yaml-language-server: $schema=<schema の URL または相対パス>
package/assets/.claude/skills/introducing-stdd/templates/introduction-plan.md CHANGED
@@ -27,7 +27,7 @@
27
27
 
28
28
  - [ ] step 0: `.stdd.config.yml` 作成・テンプレ/skill 配置
29
29
  - [ ] step 1: common ティア生成（`docs/common/REQUIREMENTS.md` + `ARCHITECTURE.md`）
30
- - [ ] `<!-- 要確認 -->` の解消（人間確認）
30
+ - [ ] **要確認マーカー**（仮説つき）の解消（人間が是非を確定 → マーカー除去）
31
31
  - [ ] step 1.5: 機能インベントリ + 優先順を確定（下記「機能ループ」へ反映）
32
32
  - [ ] step 2: 代表機能のリバース（[機能名]）
33
33
  - [ ] step 3-4: フォーマット策定 → テンプレ特化（下記「決定ログ」へ）
package/assets/.claude/skills/reverse-engineering-common-spec/SKILL.md CHANGED
@@ -102,11 +102,11 @@ feature ティアと違い、確認する一次情報は **UI 文言ではなく
102
102
 
103
103
  ## 確信が持てない箇所は要確認マーカーを残す
104
104
 
105
- 実装からの読み取りに確信が持てない箇所は `<!-- 要確認: ... -->` のインラインコメントで明示する。
106
- これは**一時的な注記**であり、人間レビューで確定したら除去する（恒久的に残さない）。SSoT 原則上、確定済みの Spec に作成プロセスや未確定メモを残してはならない。
105
+ 実装からの読み取りに確信が持てない箇所は **要確認マーカー**（可視インライン）で明示する。逆生成でも「実装からこう読めた」という**仮説とセット**で置き、その是非をユーザーに確認させる。構文の正典は [documenting-specifications SKILL「要確認マーカー」](../documenting-specifications/SKILL.md)。
106
+ これは**一時的な注記**であり、人間レビューで確定したらマーカーを除去する（恒久的に残さない）。SSoT 原則上、確定済みの Spec に作成プロセスや未確定メモを残してはならない。
107
107
 
108
108
  ```markdown
109
- - **外部ウォレット連携**: 関連テーブルと RPC が存在する。<!-- 要確認: 現行稼働範囲（本番で有効か） -->
109
+ - **外部ウォレット連携**: 関連テーブルと RPC が存在する。⚠️要確認(仮説: 本番で有効 / 確認: 現行稼働範囲)
110
110
  ```
111
111
 
112
112
  ---
@@ -120,7 +120,7 @@ feature ティアと違い、確認する一次情報は **UI 文言ではなく
120
120
  □ docs/common/API_SPEC.md を作成（API がある場合・API 契約の正典）
121
121
  □ テーブル一覧は生成された型定義ファイルと一致している
122
122
  □ 固有名詞・社外秘の値を不要に含めていない（公開を想定する場合）
123
- □ 要確認マーカーは「人間に確認すべき項目」としてレビュー依頼にまとめた
123
+ □ 要確認マーカーは仮説とセットになっており、「人間に確認すべき項目」としてレビュー依頼にまとめた
124
124
  ```
125
125
 
126
126
  ---
package/assets/.claude/skills/starting-new-with-stdd/SKILL.md CHANGED
@@ -98,7 +98,7 @@ docs/common/plans/stdd-bootstrap.md
98
98
  ### 1-2. 進める条件（重要）
99
99
 
100
100
  - **最低 1 レスポンス**を得たら、その**詳細度に関わらず**次ステップへ進む。追加質問で深掘りしない。
101
- - 不足は step 3（common ティアの前方設計）以降で**仮説**として補い、feature 開発で検証して更新する前提。
101
+ - 不足は step 3（common ティアの前方設計）以降で**仮説**として補う。仮説には必ず**要確認マーカー**を添えてユーザーに是非を確認させ、feature 開発で検証して更新する（→ [要確認マーカー](../documenting-specifications/SKILL.md)）。
102
102
 
103
103
  ### 1-3. 記録
104
104
 
@@ -141,7 +141,7 @@ docs/common/plans/stdd-bootstrap.md
141
141
 
142
142
  - **一度に 1 ステップ**。複数 feature を無確認で連続処理しない。
143
143
  - **★ポイントでは必ず停止**してユーザーに聞く（アーキ判断・粒度・フォーマット）。
144
- - common ティアは**前方設計＝仮説**。作り込みすぎず、feature 開発で検証して更新する。確定しない箇所は `<!-- 未決: ... -->` で残す。
144
+ - common ティアは**前方設計＝仮説**。作り込みすぎず、feature 開発で検証して更新する。確定しない箇所は**章を省略せず**、**要確認マーカー**（`**⚠️要確認**｜仮説: … ／確認: …`）を仮説とセットで置いて網羅性を保つ。構文の正典は [documenting-specifications SKILL「要確認マーカー」](../documenting-specifications/SKILL.md)。
145
145
  - 立ち上げPLAN 以外に進捗・履歴を持たない（SSOT 原則。spec 本体に「今回」「変更前」等を書かない）。
146
146
  - 遡行スキル（`reverse-engineering-*`）は使わない（新規にはコードが無い）。
147
147
 
package/assets/.claude/skills/starting-new-with-stdd/templates/bootstrap-plan.md CHANGED
@@ -68,12 +68,12 @@
68
68
 
69
69
  ---
70
70
 
71
- ## 前方設計の未決事項（common ティア）
71
+ ## 前方設計の要確認事項（common ティア）
72
72
 
73
- 前方設計で仮置きした・確定していない事項。feature 開発で検証して埋める。
73
+ 前方設計で仮説として置き、ユーザーに是非を確認したい事項。spec 本体にも**要確認マーカー**（`**⚠️要確認**｜仮説: … ／確認: …`）を残し、ここに一覧化して追跡する。確定したら spec のマーカーを除去し、この項目を `- [x]` にする。
74
74
 
75
- - [ ] [未決事項1]
76
- - [ ] [未決事項2]
75
+ - [ ] [仮説1] — 確認: [何を確かめたいか]
76
+ - [ ] [仮説2] — 確認: [何を確かめたいか]
77
77
 
78
78
  ---
79
79
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@careerchain/stdd",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "STDD (Spec and Test Driven Development) を既存・新規プロジェクトに導入する CLI",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",