@careerchain/stdd 0.1.1 → 0.1.3

package/assets/.claude/skills/documenting-specifications/templates/requirements.md

@@ -1,184 +1,164 @@
-# REQUIREMENTS.md テンプレート
+# REQUIREMENTS.md テンプレート（feature）
 
-**目的**: ビジネス要件とユーザージャーニーをステークホルダー視点で定義
+**目的**: 機能の要件を「業務要件 → 機能要件 → 非機能要件」の3層で定義し、後続（TECH_DESIGN / テスト / コード）の一次インプットにする。
 
 **配置**: `docs/<app>/<path>/REQUIREMENTS.md`
 
-## テンプレート構造
-
-```markdown
-# [機能名] 仕様書
-
----
-
-## 1. 概要
-
-### 解決する問題
-
-（この機能が解決する問題）
-
-### 対象ユーザー
-
-（対象ユーザー）
+## 章立ての骨格（3層 ＋ コア/拡張）
 
-### ビジネス目標
+必ず **業務要件 → 機能要件 → 非機能要件** の順に並べる。
+**機能要件は、アプリ種別を問わない「コア」と、機能の性質に応じた「拡張」に分ける**（章立てを特定アプリ・技術スタックに依存させないため）。
 
-（ビジネス目標 - 箇条書きで3-5項目）
+| 区分 | セクション | 適用 |
+|---|---|---|
+| 業務要件〔コア〕 | 解決する問題・対象ユーザー・ビジネス目標 | 常に |
+| 機能要件・コア | ユースケース（振る舞い＋受入基準）・業務ルール | 常に |
+| 機能要件・拡張 | 指標定義 / UI・画面 / 外部インターフェース | **該当する機能のみ（無ければ章ごと省略）** |
+| 非機能要件〔コア〕 | 性能・可用性・セキュリティ・アクセシビリティ 等 | 常に |
+| スコープ外〔コア〕 | 対応しない項目 | 常に |
 
----
+**拡張章の適用基準**:
 
-## 2. ユーザージャーニー
+- **指標定義** … 集計・分析・KPI を持つ機能（ダッシュボード等）
+- **UI/UX・画面** … 画面を持つ機能（API・バッチには不要）
+- **外部インターフェース** … 外部システム連携・API を持つ機能
 
-### [メインフロー名]
+> コア章だけで要件定義として成立する。拡張章はアプリ種別に依存する部分をここに隔離し、該当しない機能では付けない。
 
-**Priority**: P0 (Critical Path)
+## 記法の役割分担（重要）
 
-#### 手順
+ユースケースは **振る舞い（番号付き手順）＋ 受入基準（EARS）** の2部構成で書く。
 
-1. ユーザーが...する
-2. システムは...する
-3. ユーザーは...する
+- **振る舞い → 番号付き手順（1. 2. 3. …）**: ユーザー操作とシステム応答の主要フロー。**各ステップの主語を明示**（「ユーザーは〜」「システムは〜」）。E2E テストの骨格になる。抽象（ビジネス言語）に保ち、テストデータ・セレクタはテストコード側へ。
+- **受入基準・制約 → EARS**: フローが満たすべき詳細条件・例外・データ制約。手順と重複させず、例外・境界・横断ルールを担う。
 
-#### 期待結果
-
-- xxが...されること
-- xxが...すること
-- xxが...されないこと
-
----
-
-### [別のクリティカルパス]
-
-**Priority**: P0 (Critical Path)
-
-#### 手順
+## テンプレート構造
 
-1. ...
+````markdown
+# [機能名] 要件定義書
 
-#### 期待結果
+> 全体要件は [`docs/common/REQUIREMENTS.md`](../../common/REQUIREMENTS.md) を前提とする。
 
-- ...
+## 1. 業務要件
 
----
+### 1.1 解決する問題
+（この機能が解決する業務課題。Why）
 
-### [重要なエラーケース]
+### 1.2 対象ユーザー / 利用シーン
+（誰が・どんな場面で使うか）
 
-**Priority**: P1 (Important)
+### 1.3 ビジネス目標
+（この機能が支える意思決定・KPI。3〜5項目）
 
-#### 手順
+## 2. 機能要件
 
-1. ユーザーが（誤った操作）...
-2. システムはエラーメッセージ「...」を表示
-3. ユーザーは...
+### 2.1 ユースケース別 機能要件
 
-#### 期待結果
+ユースケース（ユーザーが達成する単位）ごとに見出し＋Priority を立て、
+**振る舞い（手順）** と **受入基準・制約** を併記する。
 
-- エラーメッセージが明確
-- ユーザーが次のアクションを理解できる
+#### [ユースケース名]
 
----
+**Priority**: P0
 
-### [エッジケース]
+**振る舞い（手順）**
 
-**Priority**: P2 (Nice to Have)
+1. ユーザーは（前提となる状態にある／操作を行う）
+2. システムは…する
+3. ユーザーは…する
+4. システムは…する
 
-#### 手順
+**受入基準・制約**
 
-1. ...
+```
+[WHEN]  …したとき、システムは、…すること。
+[IF]    もし…ならば、システムは、…すること。
+[WHERE] …の場合、システムは、…すること。
+```
 
-#### 期待結果
+### 2.2 業務ルール / 制約
 
-- ...
+機能横断・常時成立する規則（論理削除除外・代理母集団の注記 等）。
 
----
+```
+[常時] システムは、…すること。
+```
 
-## 3. UI/UXデザイン
+### 2.3 指標定義（KPI 定義表）  〔拡張：集計・分析を持つ機能のみ。無ければ章ごと省略〕
 
-ワイヤーフレーム（WF）はHTMLで `./wireframes/` 配下に置き、本セクションからリンクする。
-WFは `generating-wireframes` スキルで生成する（低忠実度・グレースケール・主要文言は実値）。
-ASCIIアートは使わない。
+| 指標 | 定義（What） | 算出ロジック | データソース | 近似・代理 | 注記表示 |
+|------|------|------|------|------|:---:|
+| | | | | | |
 
-### ワイヤーフレーム
+### 2.4 UI/UX・画面  〔拡張：画面を持つ機能のみ。無ければ章ごと省略〕
 
-- [ワイヤーフレーム一覧（index）](./wireframes/index.html)
+- [ワイヤーフレーム一覧](./wireframes/index.html)
 
 | 画面 | 状態 | WF |
 |------|------|----|
-| [画面名1] | 通常 / 空 / エラー | [画面名1](./wireframes/[screen-1].html) |
-| [画面名2] | 通常 | [画面名2](./wireframes/[screen-2].html) |
-
-### 画面ごとの要点
-
-#### [画面名1]
-
-- 主な操作（ボタン文言）: [検索] / [新規登録] / ...
-- 表示要素: （ヘッダー / 検索条件 / 一覧 / ページネーション など要点）
-- インタラクション: （選択・遷移・送信時の挙動）
-
-#### [画面名2]
+| [画面名] | 通常 / 空 / エラー | [画面](./wireframes/[screen].html) |
 
-- 主な操作（ボタン文言）: ...
-- 表示要素: ...
-
----
-
-### 表示要素
+#### 表示要素
 
 | 要素 | 説明 |
 |------|------|
-| 要素名 | 説明 |
-| 要素名 | 説明 |
+| | |
 
----
+> 画面状態（通常 / 空 / ローディング / エラー）の表示設計は TECH_DESIGN.md（画面項目定義）で扱う。
 
-### 空状態・エラー状態
+### 2.5 外部インターフェース  〔拡張：連携・API を持つ機能のみ。無ければ章ごと省略〕
 
-（コンテンツがない場合やエラー時の表示）
+（外部システム連携・API の入出力概要を業務視点で。プロトコル・スキーマ詳細は TECH_DESIGN）
 
----
+## 3. 非機能要件
 
-## 4. エッジケース
+（機能固有の品質特性のみ記載。共通は common §6 を参照。固有要件が無ければ「common 準拠」と明記）
 
-### [ケース名1]
-- 詳細説明
+## 4. スコープ外
 
-### [ケース名2]
-- 詳細説明
+- （この機能で対応しない項目 / 別 feature の項目）
+````
 
----
+## 記法ルール
 
-## 5. 成功基準
+### 振る舞い → 番号付き手順
 
-（この機能の成功基準 - チェックリスト形式）
+- `1. 2. 3. …` でユーザー操作とシステム応答の主要フロー（ハッピーパス＋主要分岐）を記述。1ユースケース＝1つの主要フロー。
+- **各ステップの主語を明示する**（「ユーザーは〜する」「システムは〜する」）。ユーザーの操作とシステムの応答を主語で区別する。
+- 前提となる状態は手順の冒頭ステップに書く（例: 「1. ユーザーは認可済みでダッシュボードに到達している」）。
+- **抽象（ビジネス言語）に保つ**。テストデータ・セレクタ・実装詳細は書かず、テストコード側に委ねる。これがそのまま E2E テストの骨格になる。
 
-- ✅ [達成すべき項目1]
-- ✅ [達成すべき項目2]
-- ✅ [達成すべき項目3]
+### 受入基準・業務ルール → EARS（5パターン）
 
----
+| パターン | 形 |
+|---|---|
+| 常時 | システムは、〜すること |
+| イベント (WHEN) | 〜したとき、システムは、〜すること |
+| 状態 (WHILE) | 〜の間、システムは、〜すること |
+| 異常 (IF / THEN) | もし〜ならば、システムは、〜すること |
+| オプション (WHERE) | 〜の場合、システムは、〜すること |
 
-## 6. スコープ外
-
-- （この機能で対応しない項目）
-- （将来的な拡張として残す項目）
-```
+- 振る舞い（手順）と重複させず、EARS は例外・境界・データ制約・横断ルールを網羅する。
+- 各要件は観測可能・検証可能（テスト1件に落ちる粒度）。曖昧語（適切に / 正しく / きちんと）は禁止。
 
-## 重要なポイント
+## 記載基準チェックリスト（作成後に必ず実行）
 
-### 記述すべき内容
-
-- すべてのユーザージャーニーを記述（正常系、エラーケース、エッジケース）
-- 各ジャーニーにPriority（P0/P1/P2）を付与
-- **ユーザー視点で記述（What & Why）**
-- **ユーザーから見える挙動のみを記述**
-- UI/UXデザイン（HTMLワイヤーフレームへのリンク、表示要素、空状態）→ generating-wireframes スキルで生成
-- 成功基準（この機能の成功基準チェックリスト）
+```
+□ コア章（業務要件／機能要件のユースケース＋業務ルール／非機能要件／スコープ外）が揃っている
+□ 拡張章（指標定義・UI/UX・外部IF）は該当する機能のみ。不要なら章ごと省略している
+□ 業務要件・機能要件・非機能要件の3層が揃っている（非機能が「common 準拠」でも明記）
+□ 全ユースケースに Priority＋振る舞い（番号付き手順・主語明示）＋受入基準（EARS）がある
+□ 振る舞い手順は主要フロー（抽象）に保たれ、テストデータ・セレクタが混入していない
+□ 受入基準（EARS）が例外・境界・データ制約を網羅している（エッジケースは IF/WHERE で統合）
+□ 指標を持つ機能は §2.3 指標定義表が埋まっている（算出/データソース/代理注記）
+□ 近似・代理指標は「注記表示=必須」が明記されている
+□ 履歴・経緯・version 記述が無い（SSOT 違反 grep を流用）
+```
 
-### 記述不要な内容
+## 記述しない内容（責務分界）
 
-- データモデル（テーブル定義、RLSポリシー）→ TECH_DESIGN.mdに記載
-- セッション管理の実装詳細（NextAuth、JWT等）
-- 実装ファイルへの参照・行番号
-- 関数名、クラス名などのコード詳細
-- テスト実装の詳細（TECH_DESIGN.mdに記載）
-- 実装方法の詳細（TECH_DESIGN.mdに記載）
+- ロジック設計・集計実装・画面項目 × バリデーション × DB マッピング → **TECH_DESIGN.md**
+- テーブル定義 → common **TABLE_DEFINITION.md** ／ API 設計 → common **API_SPEC.md**
+- テスト戦略 → **TEST_PLAN.md** ／ E2E テストの実装詳細（テストデータ・セレクタ・step 実装）→ **テストコード**
+- 実装ファイルへの参照・関数名・クラス名などのコード詳細
+- 履歴・経緯・「今回の変更」（SSOT 原則）

package/assets/.claude/skills/documenting-specifications/templates/table-definition-common.md

@@ -0,0 +1,78 @@
+# TABLE_DEFINITION.md テンプレート（common）
+
+**目的**: プロジェクトの全テーブル定義を集約する正典（実装・DB 設計・QA の SSoT）。各 feature の `TECH_DESIGN.md` は本書を**参照**し、テーブル・カラムを再定義しない。
+
+**配置**: `docs/common/TABLE_DEFINITION.md`（`.stdd.config.yml` の `docs.layout.common_table_definition` に従う）
+
+## 章立ての骨格
+
+- テーブルごとに「カード（見出し＋カラム表）」で表現する。
+- 列は **`カラム名 / データ型 / NULL / 説明`** の 4 列。主キーは `🔑` で示す。
+- **ER 図は持たない**（リレーションが必要な場合は各カラムの説明に「FK → <table>.<column>」と記す）。
+- テーブルが多い場合はドメイングループ見出し（`# ユーザー系` 等）で束ねる。
+
+**含めない**:
+
+- インデックス / RLS / トリガ等の DB メタデータ詳細 → 必要なら各 feature の `TECH_DESIGN.md`（ロジック設計 / 非機能要件）
+- 集計・変換などのロジック設計 → 各 feature の `TECH_DESIGN.md`（ロジック設計）
+- 実装の進捗・履歴（SSoT として常に最新のスキーマのみ保持する）
+
+## 確度マーカーの運用
+
+- 確信が持てないカラム・型は、説明欄に **要確認マーカー** を仮説とセットで置く（`⚠️要確認(仮説: … / 確認: …)`）。ユーザーが是非を確定したら除去する。構文の正典は [documenting-specifications SKILL「要確認マーカー」](../SKILL.md) を参照。
+
+## テンプレート構造
+
+````markdown
+# [サービス名] テーブル定義
+
+> 全テーブル定義の正典（SSoT）。各機能の `TECH_DESIGN.md` は本書を参照する。
+> 生成された型定義 / マイグレーションを正とし、本書はそれに追従する。
+>
+> **最終更新**: [yyyy-mm-dd]
+
+## 設計方針
+
+- **主キー**: [UUID / 連番 等]
+- **削除方針**: [論理削除 / 物理削除・判定カラム（例: `deleted_at IS NULL` で有効）]
+- **時系列**: [`created_at` / `updated_at` の方針]
+- **命名規則**: [テーブル / カラムの命名規則]
+
+---
+
+## [ドメイングループ名（例: ユーザー系）]
+
+### users   （PK: user_id ・ N カラム）
+
+| カラム名 | データ型 | NULL | 説明 |
+| --- | --- | --- | --- |
+| 🔑 user_id | UUID | NOT NULL | ユーザー ID |
+| email | VARCHAR(255) | 許容 | メールアドレス |
+| referred_by | UUID | 許容 | 紹介元ユーザー ID（FK → users.user_id） |
+| status | INTEGER | 許容 | 状態区分 |
+| last_login_at | TIMESTAMP | 許容 | 最終ログイン日時（最新のみ・履歴なし） |
+| created_at | TIMESTAMP | NOT NULL | 登録日時 |
+| updated_at | TIMESTAMP | 許容 | 更新日時 |
+| deleted_at | TIMESTAMP | 許容 | 論理削除日時（NULL で有効レコード） |
+
+### [次のテーブル]   （PK: [pk] ・ N カラム）
+
+| カラム名 | データ型 | NULL | 説明 |
+| --- | --- | --- | --- |
+| 🔑 [col] | [type] | NOT NULL | ... |
+| [col] | [type] | 許容 | ... |
+````
+
+## 記述基準
+
+- **型は DB の論理型で表記**（`UUID` / `VARCHAR(255)` / `INTEGER` / `TIMESTAMP` / `BOOLEAN` / `JSONB` 等）。言語固有の型（TS 型等）は持ち込まない（→ feature の TECH_DESIGN）。
+- **NULL 列は `NOT NULL` / `許容` の 2 値**で統一。
+- FK は説明欄に `FK → <table>.<column>` と明記する（ER 図の代替）。
+- 既存 DB に同名カラムがある場合はそれを正とし、無い場合は新規追加として説明欄に「新規」と注記する。
+
+## 記述しない内容（責務分界）
+
+- 集計・変換・ドメインロジック → 各 feature の `TECH_DESIGN.md`（ロジック設計）
+- 画面項目とのマッピング → 各 feature の `TECH_DESIGN.md`（画面項目定義）
+- インデックス / RLS / トリガ等の詳細 → 必要に応じて feature の `TECH_DESIGN.md`
+- 履歴・経緯・version（SSoT 原則）