@careerchain/stdd 0.1.0 → 0.1.2

package/assets/.claude/skills/documenting-specifications/guides/error-handling.md

@@ -12,30 +12,32 @@ REQUIREMENTS.mdとTECH_DESIGN.mdでエラーケースを記述する際のガイ
 ## REQUIREMENTS.md: ユーザー向けエラー
 
 **原則**:
-- エラーケースも通常のユーザージャーニーとして扱う
-- 各エラージャーニーにPriorityを付与
-- クリティカルなエラーは**P0/P1**、その他は**P2**
+- エラーケースはユースケースの一部として扱う。主要フローは振る舞い（手順）に、例外・分岐・境界は **受入基準（EARS）** に落とす
+- 各ユースケースに Priority を付与し、クリティカルなエラーは **P0/P1**、その他は **P2**
+- 「もし〜ならば（IF）」「〜の場合（WHERE）」のパターンで、観測可能・検証可能な粒度に書く
 
 **例**:
 
-```markdown
-### P1 ジャーニー: 無効な認証情報（ID/パスワード）
-**Priority**: P1（Important）
-**Status**: ✅ 実装済み
-
-#### 手順
-1. ユーザーが`/login`ページでID/パスワードタブを選択
-2. ユーザーは間違ったメールアドレスまたはパスワードを入力
-3. ユーザーは「ログイン」ボタンをクリック
-4. システムは認証に失敗
-5. システムはエラーメッセージ「ログインに失敗しました。メールアドレスとパスワードを確認してください。」を表示
-6. ユーザーはログインページに留まり、再試行できる
-
-#### 期待結果
-- ユーザーに明確なエラーメッセージが表示される
-- セキュリティのため、「メールアドレスが存在しない」vs「パスワードが間違っている」を区別しない
-- ユーザーは再試行できる
+````markdown
+#### ログイン（ID/パスワード）
+
+**Priority**: P1
+
+**振る舞い（手順）**
+
+1. ユーザーは `/login` ページで ID/パスワードタブを選択する
+2. ユーザーは メールアドレスとパスワードを入力する
+3. ユーザーは「ログイン」ボタンをクリックする
+4. システムは 認証を行い、成功すれば遷移先へ進める
+
+**受入基準・制約（EARS）**
+
+```
+[IF]   もし認証情報が無効ならば、システムは、エラーメッセージ「ログインに失敗しました。メールアドレスとパスワードを確認してください。」を表示し、ユーザーをログインページに留めること。
+[常時] システムは、「メールアドレスが存在しない」と「パスワードが間違っている」をユーザーに区別させないこと（セキュリティのため）。
+[WHEN] 認証に失敗したとき、システムは、ユーザーが再試行できる状態を保つこと。
 ```
+````
 
 ## TECH_DESIGN.md: 技術的なエラーハンドリング
 
@@ -74,5 +76,5 @@ REQUIREMENTS.mdとTECH_DESIGN.mdでエラーケースを記述する際のガイ
 
 - **REQUIREMENTS.md**: ユーザー視点 - どのエラーメッセージが表示され、次に何が起こるか
 - **TECH_DESIGN.md**: 技術視点 - エラーコード、HTTPステータス、どう処理するか、どうテストするか
-- エラーケースも通常のジャーニーと同様にPriorityを付与
+- エラーケースも通常のユースケースと同様にPriorityを付与
 - TECH_DESIGN.mdでエラーケースを適切なテストレベルにマッピング

package/assets/.claude/skills/documenting-specifications/guides/stdd-violations.md

@@ -167,7 +167,7 @@ test('利用規約リンクが別タブで開く', async ({ page }) => {
    - 「現在この方式を採用している理由」は書いてよい（設計根拠）。「以前の方式から変更した理由」は書かない（履歴）
 
 2. **UIを変更した場合**
-   - REQUIREMENTS.mdのUser Journey、画面仕様を**現在のUIのみ**を反映する形で書き換える
+   - REQUIREMENTS.mdのユースケース（振る舞い＋受入基準）、画面仕様を**現在のUIのみ**を反映する形で書き換える
    - TECH_DESIGN.mdの画面設計セクションを書き換える
    - **E2Eテスト、Integrationテストの両方を確認・更新**
 
@@ -178,7 +178,7 @@ test('利用規約リンクが別タブで開く', async ({ page }) => {
 □ 2. TECH_DESIGN.mdのテスト総数を確認・更新
 □ 3. TECH_DESIGN.mdの実装方法・技術的詳細を「現在の仕様のみ」に更新
 □ 4. SSOT原則違反の禁止語（変更前/変更後/今回/既存/...）が含まれていないかgrep
-□ 5. REQUIREMENTS.mdのUser Journey、画面仕様を確認
+□ 5. REQUIREMENTS.mdのユースケース（振る舞い＋受入基準）、画面仕様を確認
 □ 6. E2Eテストが実装と整合しているか確認・更新
 □ 7. Integrationテストが実装と整合しているか確認・更新
 ```

package/assets/.claude/skills/documenting-specifications/templates/api-spec-common.md

@@ -0,0 +1,97 @@
+# API_SPEC.md テンプレート（common）
+
+**目的**: プロジェクトの API 仕様（入出力契約）を集約する正典。各 feature の `TECH_DESIGN.md` は本書を**参照**し、エンドポイントを再定義しない。
+
+**配置**: `docs/common/API_SPEC.md`（`.stdd.config.yml` の `docs.layout.common_api_spec` に従う）
+
+## 章立ての骨格
+
+- OpenAPI / Swagger 風の **Markdown テーブル**で記述する（実 YAML ではない）。
+- エンドポイント単位に: **パス / メソッド / 概要 / パラメータ / リクエスト / レスポンス / エラー**。
+- REST に限らず、RPC / Server Actions / GraphQL なども「操作単位」で同形式で表現できる。
+- **API を持たない構成**（例: フロントから DB を直接参照）では本書は「該当なし」と明記してよい。
+
+**含めない**:
+
+- 各操作の**処理アルゴリズム**（どう集計・計算するか）→ 各 feature の `TECH_DESIGN.md`（ロジック設計）
+- クライアント側のエラーハンドリング方針 → 各 feature の `TECH_DESIGN.md`（エラーハンドリング戦略）
+- データ構造の定義 → [`TABLE_DEFINITION.md`](./table-definition-common.md)
+
+## テンプレート構造
+
+````markdown
+# [サービス名] API 仕様
+
+> API 入出力契約の正典（SSoT）。各機能の `TECH_DESIGN.md` は本書を参照する。
+> 処理アルゴリズムは各 feature の `TECH_DESIGN.md`（ロジック設計）に置く。
+>
+> **最終更新**: [yyyy-mm-dd] / **ベース URL**: [https://example.com/api] / **認証**: [Bearer / Cookie 等]
+
+## 共通仕様
+
+- **認証**: [全エンドポイント共通の認証方式]
+- **共通エラー形式**:
+
+  ```json
+  { "code": "ERROR_CODE", "message": "ユーザー向けメッセージ" }
+  ```
+
+- **共通エラーコード**:
+
+  | コード | HTTP | 意味 |
+  | --- | --- | --- |
+  | `UNAUTHORIZED` | 401 | 未認証 |
+  | `FORBIDDEN` | 403 | 権限なし |
+  | `VALIDATION_ERROR` | 400 | 入力検証エラー |
+
+---
+
+## [リソース / 機能グループ名]
+
+### POST /api/[resource]   — [操作の概要]
+
+[このエンドポイントが何をするかを 1 行で]
+
+**パラメータ（パス / クエリ）**
+
+| 名前 | 位置 | 型 | 必須 | 説明 |
+| --- | --- | --- | --- | --- |
+| [id] | path | string | ○ | ... |
+| [page] | query | integer | – | ... |
+
+**リクエストボディ**
+
+| フィールド | 型 | 必須 | 説明 |
+| --- | --- | --- | --- |
+| [email] | string | ○ | メール形式・最大 255 |
+
+**レスポンス（200 / 201）**
+
+| フィールド | 型 | 説明 |
+| --- | --- | --- |
+| [user] | object | 作成されたユーザー（→ `TABLE_DEFINITION.md#users`） |
+
+**エラー**
+
+| コード | HTTP | 条件 |
+| --- | --- | --- |
+| `EMAIL_ALREADY_EXISTS` | 409 | メール重複 |
+| `VALIDATION_ERROR` | 400 | 入力検証エラー |
+
+### GET /api/[resource]/{id}   — [操作の概要]
+
+（同形式で繰り返す）
+````
+
+## 記述基準
+
+- フィールド型は論理型（`string` / `integer` / `boolean` / `object` / `array` / `ISO8601` 等）で表記。
+- レスポンスの実体（リソース）は `TABLE_DEFINITION.md` の該当テーブルへリンクして二重定義を避ける。
+- エラーは「共通エラーコード」に集約し、エンドポイント固有のものだけ各操作の「エラー」表に記す。
+
+## 記述しない内容（責務分界）
+
+- 処理アルゴリズム・集計ロジック → 各 feature の `TECH_DESIGN.md`（ロジック設計）
+- クライアントのエラー UX（リトライ / トースト等）→ 各 feature の `TECH_DESIGN.md`（エラーハンドリング戦略）
+- データ構造 → `TABLE_DEFINITION.md`
+- 履歴・経緯・version（SSoT 原則）

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

@@ -0,0 +1,188 @@
+# ARCHITECTURE.md テンプレート（common）
+
+**目的**: プロジェクト全体のシステム概要を俯瞰する正典。STDD における common ティアの技術設計で、各 feature の `TECH_DESIGN.md` の上位ティアにあたる（システム全体 = ARCHITECTURE / 機能単位 = TECH_DESIGN）。
+
+**配置**: `docs/common/ARCHITECTURE.md`（`.stdd.config.yml` の `docs.layout.common_architecture` に従う）
+
+## 章立ての骨格
+
+「システム概要」に集約し、複数 feature が前提とする横断的な技術文脈を一箇所に固定する。
+**データモデルは [`TABLE_DEFINITION.md`](./table-definition-common.md)、API 仕様は [`API_SPEC.md`](./api-spec-common.md) に外出し**し、本書には持たない。
+
+| 節 | 内容 | 適用 |
+| --- | --- | --- |
+| 1.1 システム構成概要 | 全体構成・特徴・リポジトリ構成・レイヤ規約 | 常に |
+| 1.2 使用技術スタック | フロント / バックエンド / テスト / CI・CD | 常に |
+| 1.3 システム間連携 | 主要連携・連携方針・外部連携 | 常に |
+| 1.4 データフロー概要 | 代表的なリクエストの流れ 1 本（シーケンス図） | 常に |
+| 1.5 セキュリティ概要 | 認証・アクセス制御 / 通信 / データ保護 | 常に |
+| 1.6 インフラ構成概要 | ホスティング / 可用性 / 運用・監視 | 常に |
+
+**含めない**:
+
+- データモデル（テーブル・カラム定義）→ [`TABLE_DEFINITION.md`](./table-definition-common.md)
+- API 仕様（エンドポイント・契約）→ [`API_SPEC.md`](./api-spec-common.md)
+- 機能単位のロジック設計・画面項目・テスト戦略 → 各 feature の `TECH_DESIGN.md` / `TEST_PLAN.md`
+- 実装の進捗・履歴・変更経緯（SSoT として常に最新の構成のみ保持する）
+
+**サービスの目的・アクター・業務要件**は同階層の [`REQUIREMENTS.md`](./requirements-common.md)（common）を参照する。
+
+## 確度マーカーの運用
+
+- 実装・ヒアリングから確信が持てない箇所は `※要確認` を文末に付す（リバース直後・前方設計時など）。確定後に除去する。
+- 指標やデータの確からしさを区別する場合は `[可]`（直接算出可能）/ `[近似]`（代理母集団・近似指標）等のマークを併記する。
+
+## テンプレート構造
+
+プレースホルダを実値に置換し、不要な節・図は削除する。単一アプリ構成では複数アプリ前提の記述を畳む。
+
+````markdown
+# [サービス名] アーキテクチャ設計書
+
+> **位置づけ**: 本書は [サービス名] 全体のシステム概要を俯瞰する正典（common ティアの技術設計）。
+> サービスの目的・アクターなどのビジネス要件は [`REQUIREMENTS.md`](./REQUIREMENTS.md) を参照。
+> データモデルは [`TABLE_DEFINITION.md`](./TABLE_DEFINITION.md)、API 仕様は [`API_SPEC.md`](./API_SPEC.md) を参照。
+> 機能・画面単位の技術設計は `docs/<app>/<feature>/TECH_DESIGN.md` を参照。
+>
+> **最終更新**: [yyyy-mm-dd] / **基準ブランチ**: [main / develop 等]
+
+---
+
+## 1. システム概要
+
+### 1.1 システム構成概要
+
+（本システムが何であるか・全体構成・特徴を端的に。1 枚の構成図を添える）
+
+**全体構成**
+
+- フロントエンド層: [技術・レンダリング方式・主要画面]
+- バックエンド層: [新規構築 / 既存流用・責務の委譲先]
+- データソース: [DB・主要テーブル群]
+
+```mermaid
+flowchart TB
+    subgraph Frontend["フロントエンド"]
+        APP["[アプリ]"]
+    end
+    subgraph Backend["バックエンド / データ基盤"]
+        AUTH["[認証]"]
+        DB[("[DB]")]
+    end
+    EXT["[外部サービス]"]
+
+    APP --> AUTH & DB
+    APP --> EXT
+```
+
+**特徴**
+
+- [参照専用 / 書き込みあり 等の基本性質]
+- [代理指標・近似の扱いなど、データ上の制約と方針]
+
+**リポジトリ構成 / レイヤ規約**
+
+```
+[repo]/
+├── [app]/             # (役割)
+├── docs/              # 機能別 Spec + 全体ドキュメント (本書を含む)
+└── .github/workflows/ # CI/CD
+```
+
+| レイヤー | 責務 | 依存方向 |
+| --- | --- | --- |
+| UI / アプリケーション層 | 表示・入力・ガード | 下位へのみ依存 |
+| Service | ビジネスロジック | Repository の I/F に依存 |
+| Repository | データアクセス | DB |
+
+（依存は一方向。下位レイヤーは上位を知らない。アプリ間 import の禁止など固有ルールを追記）
+
+### 1.2 使用技術スタック
+
+**フロントエンド**
+
+- [フレームワーク / 言語 / 主要ライブラリ]
+
+**バックエンド / データ基盤**
+
+- [DB / 認証 / データアクセス方式 / アクセス制御]
+
+**テスト**
+
+- [E2E / Integration / Unit の採用ツール]
+
+**CI/CD・ホスティング**
+
+- [ビルド・デプロイ自動化 / ホスティング先]
+
+### 1.3 システム間連携
+
+**主要連携**
+
+1. [アプリ] ⇔ [連携先A]: [目的・方式]
+2. [アプリ] ⇔ [連携先B]: [目的・方式]
+
+**連携方針**
+
+- [専用バックエンドを設けるか / 直接連携か 等の方針]
+
+**外部連携**
+
+- [外部システム連携。なければ「現時点で未定義」]
+
+### 1.4 データフロー概要
+
+（代表的なリクエストの流れを 1 本、シーケンス図で示す。機能個別のフローは各 feature の TECH_DESIGN に置く）
+
+```mermaid
+sequenceDiagram
+    participant UI as UI
+    participant App as アプリケーション層
+    participant Svc as Service
+    participant Repo as Repository
+    participant DB as DB
+
+    UI->>App: 呼び出し
+    App->>App: 認証 / 入力チェック
+    App->>Svc: 実行
+    Svc->>Repo: ビジネスロジック
+    Repo->>DB: CRUD
+    DB-->>Repo: rows
+    Repo-->>Svc: Entity / Model
+    Svc-->>App: 結果
+    App-->>UI: レスポンス
+```
+
+### 1.5 セキュリティ概要
+
+- **認証・アクセス制御**: [方式・適用範囲]
+- **セッション / トークン管理**: [保持・検証・失効方針]
+- **通信**: [TLS 等]
+- **データ保護**: [RLS・暗号化・機密情報の扱い]
+
+### 1.6 インフラ構成概要
+
+- **ホスティング**: [フロント / バックエンドの配置先]
+- **データ・認証基盤**: [新規 / 既存流用・移行要否]
+- **可用性**: [稼働率目標・メンテナンス方針]
+- **CI/CD・運用・監視**: [自動化・監視・通知]
+- **性能・拡張性**: [同時接続・対象ブラウザ・最適化方針]
+
+---
+
+## 付録・関連ドキュメント
+
+- 共通要件定義: [`./REQUIREMENTS.md`](./REQUIREMENTS.md)
+- テーブル定義: [`./TABLE_DEFINITION.md`](./TABLE_DEFINITION.md)
+- API 仕様: [`./API_SPEC.md`](./API_SPEC.md)
+- 機能別 Spec: `docs/<app>/<feature>/TECH_DESIGN.md`
+````
+
+## 記述しない内容（責務分界）
+
+- サービスの目的・アクター・ビジネス要件 → common の [`REQUIREMENTS.md`](./requirements-common.md)
+- テーブル・カラム定義 → common の [`TABLE_DEFINITION.md`](./table-definition-common.md)
+- API 契約 → common の [`API_SPEC.md`](./api-spec-common.md)
+- 機能個別のロジック設計・画面項目・テスト → 各 feature の `TECH_DESIGN.md` / `TEST_PLAN.md`
+- 関数 / メソッドの具体実装コード。特定の型定義は載せない（データ構造は `TABLE_DEFINITION.md`、I/F は `API_SPEC.md`）
+- 履歴・経緯・version（SSoT 原則）

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

@@ -0,0 +1,57 @@
+# DESIGN.md テンプレート（common・任意）
+
+**目的**: プロジェクトのデザイン標準（デザイントークン・コンポーネント規約・レイアウト原則）を定義する正典。UI を持つ feature の実装・ワイヤーフレーム・画面項目定義が参照する。
+
+**配置**: `docs/common/DESIGN.md`（`.stdd.config.yml` の `docs.layout.common_design` に従う）
+
+**作成タイミング**（任意。以下に当てはまる場合に作成を検討）:
+
+- 複数画面で一貫した UI トークン / コンポーネントを共有する
+- 既存デザインシステム（例: getdesign 等）をベースに標準化する
+
+## 章立ての骨格
+
+| 章 | 内容 |
+| --- | --- |
+| 1. デザイン原則 | トーン＆マナー・アクセシビリティ方針 |
+| 2. デザイントークン | カラー / タイポグラフィ / スペーシング / 角丸・影 |
+| 3. コンポーネント規約 | ボタン / フォーム / テーブル / グラフ等の共通仕様 |
+| 4. レイアウト原則 | グリッド / ブレークポイント / 余白 |
+
+## テンプレート構造
+
+````markdown
+# [サービス名] デザイン標準
+
+> UI を持つ機能の実装・ワイヤーフレームが参照する正典。
+> ベースとするデザインシステム: [getdesign(apple) / 自社 等]
+
+## 1. デザイン原則
+
+- [トーン＆マナー / 一貫性 / アクセシビリティの方針]
+
+## 2. デザイントークン
+
+| 種別 | トークン | 値 |
+| --- | --- | --- |
+| Color | `color.primary` | #... |
+| Typography | `font.body` | ... |
+| Spacing | `space.md` | 16px |
+
+## 3. コンポーネント規約
+
+- **ボタン**: [種別・状態・サイズ]
+- **フォーム**: [入力・バリデーション表示]
+- **テーブル / グラフ**: [共通描画方針]
+
+## 4. レイアウト原則
+
+- **グリッド / ブレークポイント**: ...
+- **余白 / 階層**: ...
+````
+
+## 記述しない内容（責務分界）
+
+- 画面ごとの項目・バリデーション → 各 feature の `TECH_DESIGN.md`（画面項目定義）
+- 実装コード（CSS / コンポーネント実装） → 実装
+- 履歴・経緯・version（SSoT 原則）

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

@@ -0,0 +1,104 @@
+# REQUIREMENTS.md テンプレート（common）
+
+**目的**: プロジェクト全体の要件を俯瞰する正典。各 feature の REQUIREMENTS.md はこれを前提とする。
+
+**配置**: `docs/common/REQUIREMENTS.md`
+
+## 章立ての骨格（3層 ＋ コア/拡張）
+
+feature と同じく **業務要件 → 機能要件(省略可能) → 非機能要件** の3層を骨格とする。
+common は全体横断のため、前段に「サービス概要 / 登場アクター / 用語集」を置く。
+機能要件はアーキテクチャ設計に関わる要件がある場合のみ記載する。
+非機能要件・横断業務ルールはここで一元化する（feature は「common 準拠」で参照）。
+
+| 区分               | セクション                                 | 適用       |
+| ------------------ | ------------------------------------------ | ---------- |
+| 前段〔コア〕       | サービス概要 / 登場アクター / 用語集       | 常に       |
+| 業務要件〔コア〕   | 業務上の課題 / ビジネスゴール・KPI         | 常に       |
+| 機能要件           | ※必要に応じて定義                          | 該当時のみ |
+| 非機能要件〔コア〕 | 性能・可用性・セキュリティ・横断業務ルール | 常に       |
+| スコープ外〔コア〕 |                                            | 常に       |
+
+**記法**: ユースケースは **振る舞い（番号付き手順・主語明示）＋ 受入基準（EARS）** の2部構成。横断業務ルールは EARS。
+
+## テンプレート構造
+
+````markdown
+# [プロジェクト名] — 全体要件（common）
+
+機能単位の要件は各 feature の `REQUIREMENTS.md` に置き、本書を前提とする。
+
+## 1. サービス概要
+
+（解決する課題・提供価値・基本性質）
+
+## 2. 登場アクター
+
+| アクター | 説明 | 権限 |
+| -------- | ---- | ---- |
+|          |      |      |
+
+## 3. 用語集（Glossary）
+
+| 用語 | 定義 |
+| ---- | ---- |
+|      |      |
+
+## 4. 業務要件
+
+### 4.1 業務上の課題
+
+| 課題 | 現状 |
+| ---- | ---- |
+|      |      |
+
+### 4.2 ビジネスゴール / KPI
+
+| ゴール | KPI | 目標値 |
+| ------ | --- | ------ |
+|        |     |        |
+
+## 5. 機能要件
+
+## 6. 非機能要件
+
+### 6.1 性能 / 可用性
+
+### 6.2 セキュリティ / 認可
+
+### 6.3 アクセシビリティ / ユーザビリティ
+
+### 6.4 横断業務ルール
+
+```
+[常時] システムは、…すること。
+```
+
+## 7. スコープ外
+````
+
+## 記法・記載基準
+
+- ユースケースは **振る舞い（番号付き手順・主語明示）＋ 受入基準（EARS）** の2部構成（feature と同一ルール）。
+- 横断業務ルールは EARS で一元化し、feature から「common 準拠 / 参照」として引く（複製しない）。
+- 機能要件は コア（アプリ構成・全体ユースケース）＋ 拡張（ダッシュボード構成・指標方針、該当時のみ）。
+
+## 記載基準チェックリスト
+
+```
+□ コア章（前段・業務要件・機能要件のコア・非機能要件・スコープ外）が揃っている
+□ 拡張章（ダッシュボード構成・指標方針）は該当時のみ
+□ 用語集に、feature 横断で解釈が割れる用語が定義されている
+□ 全体ユースケースに 振る舞い（手順・主語明示）＋受入基準（EARS）がある
+□ 横断業務ルールが EARS で一元化されている
+□ 非機能要件が散在せず §6 に集約されている
+□ 履歴・経緯・version 記述が無い（SSOT）
+```
+
+## 記述しない内容（責務分界）
+
+- 機能個別の詳細要件（ユースケース・受入基準・指標）→ 各 feature の **REQUIREMENTS.md**
+- システム構成図・レイヤ規約・技術スタック詳細 → common の **ARCHITECTURE.md**
+- テーブル定義 → common の **TABLE_DEFINITION.md** ／ API 仕様 → common の **API_SPEC.md**
+- E2E テストの実装詳細 → テストコード
+- 履歴・経緯・version（SSOT 原則）