@careerchain/stdd 0.1.0

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

@@ -0,0 +1,241 @@
+# TECH_DESIGN.md テンプレート
+
+**目的**: 機能実装のための技術設計とテスト戦略
+
+**配置**: `docs/<app>/<path>/TECH_DESIGN.md`
+
+## テンプレート構造
+
+```markdown
+# [機能名] - 技術設計書
+
+---
+
+# Part 1: 技術設計
+
+## 1. 機能固有アーキテクチャ
+
+（この機能固有のアーキテクチャ図とデータフロー）
+
+```mermaid
+graph TD
+    A[ユーザー] --> B[ページコンポーネント]
+    B --> C[APIエンドポイント]
+    C --> D[サービス層]
+    D --> E[リポジトリ]
+    E --> F[(データベース)]
+```
+
+---
+
+## 2. 主要な設計判断
+
+### 判断1: [技術選定]
+
+**選択**: ...
+**理由**: ...
+
+### 判断2: [アーキテクチャパターン]
+
+**選択**: ...
+**理由**: ...
+
+---
+
+## 3. データモデル
+
+### ER図
+
+```mermaid
+erDiagram
+    users ||--o{ projects : has
+    users {
+        uuid id PK
+        string email
+        timestamp created_at
+    }
+```
+
+### TypeScript型定義
+
+```typescript
+// Entity型
+export interface UserEntity {
+  id: string;
+  email: string;
+  created_at: string;
+}
+
+// UI型
+export interface User {
+  id: string;
+  email: string;
+  createdAt: Date;
+}
+```
+
+### バリデーションルール
+
+- `email`: 必須、メール形式、最大255文字
+- `created_at`: ISO8601形式、過去の日時
+
+---
+
+## 4. API設計
+
+### エンドポイント
+
+#### POST /api/users
+
+**リクエスト**:
+```typescript
+interface CreateUserRequest {
+  email: string;
+}
+```
+
+**レスポンス**:
+```typescript
+interface CreateUserResponse {
+  user: User;
+}
+```
+
+**ビジネスロジック**:
+1. メールアドレスの重複チェック
+2. ユーザー作成
+3. ウェルカムメール送信
+
+---
+
+## 5. エラーハンドリング戦略
+
+### エラーコード定義
+
+| エラーコード | HTTPステータス | メッセージ | 原因 |
+|------------|--------------|----------|------|
+| `USER_NOT_FOUND` | 404 | ユーザーが見つかりません | 存在しないユーザーID |
+| `EMAIL_ALREADY_EXISTS` | 409 | このメールアドレスは既に使用されています | メール重複 |
+| `VALIDATION_ERROR` | 400 | 入力内容を確認してください | バリデーション失敗 |
+
+### 実装方針
+
+- すべてのエラーは`AppError`クラスを継承
+- エラーコードでエラー種別を識別
+- ユーザー向けメッセージとログ用メッセージを分離
+
+---
+
+## 6. セキュリティ要件
+
+- **認証・認可**: 実装方法と適用範囲
+- **XSS対策**: 対策内容
+- **CSRF対策**: 対策内容
+- **SQLインジェクション対策**: 対策内容
+- **個人情報の暗号化**: 暗号化方式
+
+---
+
+## 7. パフォーマンス要件
+
+- **ページ読み込み時間**: 2秒以内
+- **API応答時間**: 500ms以内
+- **同時接続数**: 1000ユーザー
+
+---
+
+## 8. テスト戦略
+
+### ジャーニー別テスト戦略
+
+| ジャーニー | E2E | Integration | Unit | 根拠 |
+|---------|-----|-------------|------|-----------|
+| P0: メインフロー | ✅ | ✅ | ✅ | Critical path、ビジネスに直結、複数システム統合 |
+| P1: 重要なエラーケース | ⚠️ 検討 | ✅ | ✅ | 頻度高い、Integration必須、E2Eは複雑さ・コストで判断 |
+| P2: エッジケース | ❌ | ⚠️ | ✅ | 低頻度、Unit十分 |
+
+### テストファイル構成
+
+- **E2E**: `e2e/tests/[app]/[feature].spec.ts`
+- **Integration**: `[app]/components/[name].test.tsx`
+- **Unit**: `[app]/lib/*.test.ts`, `[app]/domain/models/*.test.ts`
+```
+
+## 重要なポイント
+
+- REQUIREMENTS.mdのジャーニーをテストレベル（E2E/Integration/Unit）にマッピング
+- テストレベル決定の根拠（Rationale）を含める
+- 設計判断は「選択」と「理由」を明記
+- アーキテクチャ、API設計、エラーハンドリング戦略
+
+### 実装例・コード例について
+
+**TECH_DESIGN.mdには実装例・コード例を含めない**。ただし、以下の場合はコードブロックの使用が許容される:
+
+- **型定義・インターフェース**: Entity型、UI型、Request/Response型など設計情報として必要なもの
+- **データモデル**: ER図、バリデーションルール
+- **API設計**: エンドポイント、リクエスト/レスポンス型
+
+以下は記述しないこと:
+- 関数・メソッドの具体的な実装
+- コンポーネントの実装
+- Server Actions の実装
+- 処理フローのコード
+
+## TECH_DESIGN.md作成時のルール
+
+### 1. 「実装済み」「新規追加」の分類は不要
+
+**理由**: REQUIREMENTS.mdが常にSSoT（Single Source of Truth）であるため、TECH_DESIGN.mdでは実装済みかどうかの区別は不要。すべての要件を統一的に設計する。
+
+❌ **悪い例**:
+```markdown
+### 実装済み（既存）
+- ✅ 認証・認可: NextAuth + Supabase Authで二重認証
+
+### 新規追加（パスワード認証）
+- ✅ Supabase Authによるパスワード認証
+```
+
+✅ **良い例**:
+```markdown
+## 6. セキュリティ要件
+
+- **認証・認可**: NextAuth + Supabase Authで二重認証
+- **Supabase Authによるパスワード認証**: Credentials Providerで`signInWithPassword`を使用
+```
+
+### 2. 削除すべきセクション
+
+TECH_DESIGN.mdでは以下のセクションは**削除する**こと:
+
+- ❌ **Integration Points**: 外部システム・内部システムの一覧
+- ❌ **実装順序**: フェーズ別の実装計画
+- ❌ **ドキュメント参照文言**: 「このドキュメントは〜を参考に作成されました」
+
+### 3. チェックボックス形式の削除
+
+TECH_DESIGN.mdでは、実装状態を示すチェックボックス（`- [ ]`や`- ✅`）は使用しない。
+
+❌ **悪い例**:
+```markdown
+## 6. セキュリティ要件
+
+- [ ] 認証・認可の実装
+- [ ] XSS対策
+- ✅ CSRF対策
+```
+
+✅ **良い例**:
+```markdown
+## 6. セキュリティ要件
+
+- **認証・認可**: NextAuth + Supabase Authで二重認証
+- **XSS対策**: React自動エスケープ + DOMPurify
+- **CSRF対策**: NextAuthがCSRFトークンを自動管理
+
+### スコープ外
+
+- 二要素認証（2FA）
+- アカウントロック
+```

package/assets/.claude/skills/generating-wireframes/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: generating-wireframes
+description: |-
+  REQUIREMENTS.md のユーザージャーニーから、低忠実度（low-fidelity）の HTML ワイヤーフレームを生成する。技術スタック非依存の素の HTML（CSS は各 HTML に `<style>` で埋め込み・自己完結）で、画面レイアウト・情報設計・主要文言（タイトル / ボタン / 項目ラベル）を合意形成用に可視化する。
+when_to_use: |-
+  「ワイヤーフレーム」「WF」「wireframe」「画面設計」「画面イメージ」「モックの前段」「UI/UX デザインのHTML化」「REQUIREMENTS の画面を作る」に関する作業のとき。
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# ワイヤーフレーム生成
+
+REQUIREMENTS.md の **ユーザージャーニー**と**画面要素**をもとに、低忠実度の HTML ワイヤーフレーム（WF）を生成する。WF は REQUIREMENTS.md の「3. UI/UX デザイン」セクションの実体となり、ステークホルダーが画面構成・遷移・主要文言を合意するために使う。
+
+## 何を作るか / 作らないか
+
+| 作る | 作らない |
+| ---- | -------- |
+| 画面レイアウト（ヘッダー / サイドバー / 検索 / 一覧 / フォーム / カード / カンバン等） | 確定したビジュアルデザイン（ブランドカラー・余白の最終値・タイポグラフィ） |
+| 主要文言（画面タイトル・ボタン文言・項目ラベル・タブ名）を**実値で** | ピクセルパーフェクトなモック |
+| 状態の出し分け（通常 / 空 / エラー） | 実データ・実 API 連携・JS による挙動 |
+| レスポンシブの大枠（モバイル 1 列 → デスクトップ展開） | 細かいアニメーション・トランジション |
+
+⚠️ **低忠実度だが、文言は実値**。`[ボタン]` のようなダミーで終わらせず、合意済みの「検索」「新規登録」「保存」「キャンセル」などの実文言を入れる。色や装飾は持たせない（実装の自由度を縛らないため、かつ公開資産としてブランド中立に保つため）。
+
+## 配置ルール
+
+```
+docs/<app>/<feature_path>/wireframes/
+├── index.html           … 画面一覧（目次）
+├── <screen-1>.html      … 画面ごとの WF（状態違いは <screen>-empty.html 等）
+└── <screen-2>.html
+```
+
+- 各 HTML は **自己完結**（self-contained）。デザインシステムの CSS は `<head>` 内に `<style>` で**直接埋め込む**。**CSS 単体ファイル（wireframe.css 等）は作らない**。
+- `<app>` / `<feature_path>` は REQUIREMENTS.md と同じ階層に合わせる（`.stdd.config.yml` の `docs.layout.wireframes` があればそれに従う。なければ上記の固定規約）。
+- REQUIREMENTS.md からは **相対リンク**で `./wireframes/index.html` を指す。
+
+## 生成手順
+
+### 1. 入力を読む
+
+- 対象の `REQUIREMENTS.md`（ユーザージャーニー・表示要素・空 / エラー状態）
+- `SCREEN_ITEMS_DEFINITION.md`（存在する場合 — フォーム項目名・選択肢・必須/任意の出所はこれ）
+- 既存の類似画面の WF（`docs/**/wireframes/` を Glob して文言・構造を踏襲）
+
+### 2. 画面を洗い出す
+
+ユーザージャーニーの各ステップが「どの画面で起きるか」を割り出し、画面のリストを作る。1 ジャーニー = 複数画面のことも、複数ジャーニーが 1 画面を共有することもある。各画面について必要な**状態**（通常 / 空 / エラー / ローディング）を決める。詳細は [guides/from-requirements.md](guides/from-requirements.md)。
+
+### 3. 雛形をコピーして組む
+
+1. `templates/screen.html` を各画面ぶんコピーする。このひな型は `<head>` 内に**デザインシステムの `<style>` を埋め込み済み**（＝デザインシステム本体）。`<body>` をコンポーネント（下表 `wf-*`）で組む。
+2. `templates/index.html` をコピーし、全画面へのリンクと 1 行説明を並べる。
+3. 各画面の `<title>` と `.wf-screen-label` に「画面名 / 状態名」を実値で入れる。
+4. `<style>` ブロックは各画面で同一内容を保つ（デザインシステムを変えたい場合は全画面の `<style>` を揃えて更新する）。CSS 単体ファイルは作らない。
+
+### 4. REQUIREMENTS.md の「3. UI/UX デザイン」を更新
+
+ASCII アートは置かない。代わりに以下を書く（テンプレートは `documenting-specifications` の REQUIREMENTS テンプレートに準拠）:
+
+- `./wireframes/index.html` へのリンク（ワイヤーフレーム一覧）
+- 画面ごとに: 画面名・主な操作（ボタン文言）・表示要素の要点
+- 表示要素テーブル / 空・エラー状態の説明
+
+### 5. セルフチェック
+
+- [ ] すべての P0 / P1 ジャーニーに対応する画面が WF 化されている
+- [ ] 各画面に**実文言**のタイトル・ボタン・ラベルが入っている（ダミー `[...]` が残っていない）
+- [ ] 空状態・主要エラー状態の WF がある
+- [ ] モバイル幅でも破綻しない（`wf-page--mobile` でプレビュー確認、または論理的に 1 列化される構造）
+- [ ] `index.html` から全画面に到達できる
+- [ ] 各 HTML が自己完結している（`<style>` 埋め込み・外部 CSS ファイルを参照していない）
+- [ ] ブランドカラー・固有の装飾を持ち込んでいない（グレースケール維持）
+
+## コンポーネント早見表（埋め込み `<style>` のクラス）
+
+| 用途 | クラス |
+| ---- | ------ |
+| ページ枠 | `wf-page`（モバイル枠は `wf-page--mobile`） |
+| グローバルヘッダー | `wf-header` / `wf-header__logo` / `wf-header__nav` / `wf-header__spacer` |
+| 本体レイアウト | `wf-body` / `wf-sidebar` / `wf-sidebar__item(--active)` / `wf-main` |
+| 見出し | `wf-breadcrumb` / `wf-title` / `wf-subtitle` / `wf-tabs` / `wf-tabs__item(--active)` |
+| ツールバー | `wf-toolbar` / `wf-toolbar__spacer` / `wf-count` |
+| 検索・フィルタ | `wf-search` / `wf-search__head` / `wf-search__body` / `wf-search__actions` |
+| フォーム | `wf-form(--2col)` / `wf-field(--full)` / `wf-label(--required)` / `wf-input` / `wf-select` / `wf-textarea` / `wf-help` / `wf-error` |
+| ボタン | `wf-button` / `wf-button--primary` / `wf-button--ghost` / `wf-button--sm` |
+| テーブル | `wf-table-wrap` / `wf-table` / `wf-td--muted` |
+| カード / グリッド | `wf-grid(--2/--3)` / `wf-card` / `wf-card__title` / `wf-card__meta` |
+| カンバン | `wf-kanban(--3)` / `wf-kanban__col` / `wf-kanban__head` |
+| タグ / 画像 / アバター | `wf-tag` / `wf-img` / `wf-avatar` |
+| ページネーション | `wf-pagination` / `wf-pagination__item(--active)` |
+| 空・エラー | `wf-empty` |
+| モーダル | `wf-modal` / `wf-modal__head` / `wf-modal__body` / `wf-modal__foot` |
+| 注記・ユーティリティ | `wf-note` / `wf-row` / `wf-stack` / `wf-muted` / `wf-mt` |
+
+実例は [examples/](examples/) を参照（toC 一覧 / フォーム、toB 管理画面 一覧 / フォーム）。
+
+## STDD フローでの位置づけ
+
+```
+REQUIREMENTS.md（ジャーニー）
+  └─ ワイヤーフレーム生成（本スキル）── 「3. UI/UX デザイン」の実体に
+       └─ TECH_DESIGN.md → テスト → 実装
+```
+
+- WF は **Spec の一部**。実装前のステークホルダー合意に使う（Figma 等の実画面キャプチャは実装**後**の別工程で、混同しない）。
+- 仕様変更時は SSOT 原則に従い、REQUIREMENTS.md → WF の順で更新する（WF だけ先に直さない）。
+
+## When NOT to Use This Skill
+
+- UI を持たない機能（バッチ・API のみ・内部ロジック）
+- 既存画面の文言・ロジックのみの軽微な変更（画面構成が変わらない）
+- 実装後の実画面キャプチャ（それは別工程）
+
+## 参照ファイル
+
+- [templates/screen.html](templates/screen.html) — 画面ひな型（`<head>` に汎用デザインシステムの `<style>` を埋め込み済み＝デザインシステム本体）
+- [templates/index.html](templates/index.html) — 画面一覧ひな型
+- [guides/from-requirements.md](guides/from-requirements.md) — ジャーニー → 画面の起こし方
+- [examples/](examples/) — toC / toB のサンプル WF
+- 関連: [documenting-specifications](../documenting-specifications/SKILL.md)（REQUIREMENTS テンプレート）