@careerchain/stdd 0.1.0

package/assets/.claude/skills/introducing-stdd/templates/introduction-plan.md

@@ -0,0 +1,64 @@
+<!--
+導入PLAN — STDD 導入の進捗を保持するプロジェクト単位の生きたチェックリスト。
+
+位置づけ:
+  - feature/session 単位の通常 PLAN とは別。プロジェクト全体の「導入」進捗を 1 ファイルで追跡する。
+  - introducing-stdd スキルがこのファイルを読み書きしながら導入を駆動する。
+  - 導入が一巡（順行運用へ移行）したら役目を終える。
+
+配置:
+  docs/common/plans/stdd-introduction.md
+
+書き換え方:
+  プレースホルダを実値に置換。機能は step 1.5 で洗い出した一覧を優先順（P0→P1→P2）で並べる。
+  完了した項目は [ ] → [x] にする。フォーマット決定は「決定ログ」に追記する。
+-->
+
+# STDD 導入PLAN — [サービス名]
+
+> 進捗トラッカー。詳細手順は `introducing-stdd` スキル / `guide-for-existing-project.md` を参照。
+> **開始**: [yyyy-mm-dd] / **基準ブランチ**: [main / develop 等]
+
+---
+
+## 進捗
+
+### 基盤
+
+- [ ] step 0: `.stdd.config.yml` 作成・テンプレ/skill 配置
+- [ ] step 1: common ティア生成（`docs/common/REQUIREMENTS.md` + `ARCHITECTURE.md`）
+  - [ ] `<!-- 要確認 -->` の解消（人間確認）
+- [ ] step 1.5: 機能インベントリ + 優先順を確定（下記「機能ループ」へ反映）
+- [ ] step 2: 代表機能のリバース（[機能名]）
+- [ ] step 3-4: フォーマット策定 → テンプレ特化（下記「決定ログ」へ）
+
+### 機能ループ（step 5）
+
+優先順（P0 → P1 → P2）。各機能 = `reverse-engineering-feature-spec` → `verifying-consistency`。
+
+- [ ] [機能A]  (P0)
+- [ ] [機能B]  (P0)
+- [ ] [機能C]  (P1)
+- [ ] [機能D]  (P2)
+
+### 移行
+
+- [ ] step 6: 既存機能の spec が一巡 → 以降は `auto-implement`（順行運用）へ
+
+---
+
+## フォーマット決定ログ（step 3-4 / 7）
+
+このプロジェクト固有に決めた spec フォーマットの方針を記録する。
+
+- 必須 spec ファイル: [REQUIREMENTS / TECH_DESIGN / ...]
+- common ARCHITECTURE に追加した固有セクション: [認証・認可 / RLS / ...]
+- docs.layout パス規約: [docs/<app>/<feature>/...]
+- Priority 基準: [このプロジェクトでの P0/P1/P2 の定義]
+- テスト層の責務分担: [E2E は P0 のみ 等]
+
+---
+
+## メモ・引き継ぎ
+
+- (セッションを跨ぐ際の注意点・保留事項)

package/assets/.claude/skills/kaizen/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: kaizen
+description: |-
+  継続的改善・過剰設計回避のための開発原則。Poka-Yoke（エラー防止）、YAGNI、Rule of Three、段階的リファクタリングを提供する。
+when_to_use: |-
+  「リファクタリング」「改善」「過剰設計」「YAGNI」「シンプル」「エラー防止」「コード品質」「設計改善」「段階的改善」に関する作業のとき。
+allowed-tools: Read, Edit, Grep, Glob
+---
+
+# Kaizen: 継続的改善
+
+小さな改善を継続的に。設計段階でエラーを防止。実績あるパターンに従う。必要なものだけを作る。
+
+**核心**: 大きな一発勝負より、小さな改善の積み重ねが大きな成果を生む。
+
+## 適用タイミング
+
+- コード実装とリファクタリング
+- アーキテクチャ・設計判断
+- エラーハンドリング・バリデーション設計
+
+## 4つの柱
+
+### 1. 継続的改善（Kaizen）
+
+小さく頻繁な改善が、大きな成果に複利的に積み上がる。
+
+**段階的に進める**:
+- 品質を改善する最小限の変更を行う
+- 一度に1つの改善のみ
+- 各変更を検証してから次へ
+
+**コードは見つけた時より良くする**:
+- 小さな問題を見つけたらその場で修正（スコープ内で）
+- 古いコメントを更新、デッドコードを削除
+
+**反復的に洗練する**:
+1. まず動くものを作る
+2. 次に明確にする
+3. 最後に効率化する
+4. 一度に3つ全部はやらない
+
+**実践**: 機能実装時は最もシンプルなバージョンから始める。リファクタリング時は1つずつコードの匂いを修正し、各改善後にコミット。テストを常にパスさせる。
+
+### 2. Poka-Yoke（エラー防止）
+
+実行時ではなく、コンパイル時・設計時にエラーを防止するシステムを設計する。
+
+**エラーを不可能にする**:
+- 型システムで間違いを検知
+- 無効な状態を表現不可能にする（Discriminated Union）
+- エラーは早期に（本番ではなく開発時に）検出
+
+**防御の層**:
+1. **型システム**（コンパイル時） - Union TypeでStringを避ける
+2. **バリデーション**（実行時、早期） - 境界で1回検証すれば内部は安全
+3. **ガード節**（前提条件） - Early returnで前提を明示
+4. **エラー境界**（グレースフルデグレード）
+
+**実践**:
+- API設計時: 型で入力を制約し、無効な状態を表現不可能に
+- エラー処理時: システム境界でバリデーション、ガード節で前提条件チェック、明確なメッセージで失敗
+- 設定管理時: optionalよりrequired、起動時に全設定を検証
+
+### 3. 標準化された作業
+
+既存パターンに従う。うまくいくものを文書化する。良い慣行を簡単に従えるようにする。
+
+**一貫性は賢さに勝る**:
+- 既存のコードベースパターンに従う
+- 解決済みの問題を再発明しない
+- 新パターンは大幅に改善される場合のみ導入
+
+**標準を自動化する**:
+- リンターでスタイルを強制
+- 型チェックで契約を強制
+- テストで挙動を検証
+- CI/CDで品質ゲートを強制
+
+**実践**:
+- 新パターン追加前: コードベースで類似問題の解決策を検索し、CLAUDE.mdの規約を確認
+- コード記述時: 既存のファイル構造、命名規則、エラーハンドリングパターンに合わせる
+
+### 4. Just-In-Time（JIT）
+
+今必要なものだけを作る。それ以上も以下もなく。
+
+**YAGNI（You Aren't Gonna Need It）**:
+- 現在の要件のみ実装
+- 「念のため」の機能は不要
+- 「将来必要になるかも」のコードは不要
+- 推測的コードは削除
+
+**動く最もシンプルなもの**:
+- 直接的な解決策から始める
+- 必要になった時にのみ複雑さを追加
+- 要件変更時にリファクタリング
+
+**抽象化のタイミング（Rule of Three）**:
+- 3箇所以上で同じパターンが出現してから抽象化
+- 間違った抽象化より重複のほうがマシ
+- パターンが明確になってからリファクタリング
+
+**実践**:
+- 実装時: 目の前の問題を解決、「もし〜だったら」思考に抵抗
+- 最適化時: まず計測、次に最適化
+- 抽象化時: 3箇所以上の類似ケースを待つ
+
+## 危険信号
+
+| 柱 | 危険信号 |
+|---|---------|
+| 継続的改善 | 「後でリファクタリングする」（実行されない） |
+| Poka-Yoke | 「ユーザーが気をつければいい」 |
+| 標準化 | 「自分のやり方でやりたい」 |
+| JIT | 「いつか必要になるかも」 |
+
+## コード例
+
+詳細なコード例は [references/code-examples.md](references/code-examples.md) を参照:
+- 段階的リファクタリングの例
+- 型システムによるエラー防止の例
+- 過剰設計 vs 適切な設計の例
+
+## まとめ
+
+**Kaizenの本質**: 今日十分に良いものを作り、明日さらに良くする。これを繰り返す。
+
+完璧を一発で目指すのではなく、小さな改善を積み重ねる。大規模リファクタリングより段階的改善。巧妙な抽象化より明快なコード。

package/assets/.claude/skills/kaizen/references/code-examples.md

@@ -0,0 +1,233 @@
+# Kaizen コード例集
+
+SKILL.md本体の4つの柱に対応する詳細なコード例。
+
+## 目次
+
+- [継続的改善のコード例](#継続的改善のコード例)
+- [Poka-Yokeのコード例](#poka-yokeのコード例)
+- [JIT/YAGNIのコード例](#jityagniのコード例)
+
+---
+
+## 継続的改善のコード例
+
+### 段階的リファクタリング
+
+```typescript
+// Iteration 1: まず動くものを作る
+const calculateTotal = (items: Item[]) => {
+  let total = 0;
+  for (let i = 0; i < items.length; i++) {
+    total += items[i].price * items[i].quantity;
+  }
+  return total;
+};
+
+// Iteration 2: 明確にする（リファクタ）
+const calculateTotal = (items: Item[]): number => {
+  return items.reduce((total, item) => {
+    return total + (item.price * item.quantity);
+  }, 0);
+};
+
+// Iteration 3: 堅牢にする（バリデーション追加）
+const calculateTotal = (items: Item[]): number => {
+  if (!items?.length) return 0;
+
+  return items.reduce((total, item) => {
+    if (item.price < 0 || item.quantity < 0) {
+      throw new Error('Price and quantity must be non-negative');
+    }
+    return total + (item.price * item.quantity);
+  }, 0);
+};
+```
+
+各ステップが完結しており、テスト可能。一度にすべてやろうとしない。
+
+### 悪い例: 一度にすべてやろうとする
+
+```typescript
+const calculateTotal = (items: Item[]): number => {
+  if (!items?.length) return 0;
+  const validItems = items.filter(item => {
+    if (item.price < 0) throw new Error('Negative price');
+    if (item.quantity < 0) throw new Error('Negative quantity');
+    return item.quantity > 0;
+  });
+  // キャッシュも、ロギングも、通貨変換も一度に…
+  return validItems.reduce(...);
+};
+```
+
+---
+
+## Poka-Yokeのコード例
+
+### 型システムによるエラー防止
+
+```typescript
+// 悪い例: stringで状態管理
+type OrderBad = {
+  status: string; // "pending", "PENDING", "pnding" 何でも入る
+  total: number;
+};
+
+// 良い例: Union Typeで制約
+type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';
+type Order = {
+  status: OrderStatus;
+  total: number;
+};
+
+// より良い例: 状態に応じたデータを強制
+type Order =
+  | { status: 'pending'; createdAt: Date }
+  | { status: 'processing'; startedAt: Date; estimatedCompletion: Date }
+  | { status: 'shipped'; trackingNumber: string; shippedAt: Date }
+  | { status: 'delivered'; deliveredAt: Date; signature: string };
+// shipped状態ではtrackingNumberが必須になる
+```
+
+### バリデーションの境界防御
+
+```typescript
+// 悪い例: バリデーション前に使用
+const processPayment = (amount: number) => {
+  const fee = amount * 0.03; // バリデーション前に使っている
+  if (amount <= 0) throw new Error('Invalid amount');
+};
+
+// 良い例: 境界でバリデーション、以降は安全
+const processPayment = (amount: number) => {
+  if (amount <= 0) {
+    throw new Error('Payment amount must be positive');
+  }
+  const fee = amount * 0.03;
+};
+```
+
+### ガード節（Early Return）
+
+```typescript
+const processUser = (user: User | null) => {
+  if (!user) {
+    logger.error('User not found');
+    return;
+  }
+
+  if (!user.email) {
+    logger.error('User email missing');
+    return;
+  }
+
+  if (!user.isActive) {
+    logger.info('User inactive, skipping');
+    return;
+  }
+
+  // ここに到達 = userは有効かつアクティブであることが保証される
+  sendEmail(user.email, 'Welcome!');
+};
+```
+
+### 設定のエラー防止
+
+```typescript
+// 悪い例: optionalで起動時にチェックしない
+type ConfigBad = {
+  apiKey?: string;
+  timeout?: number;
+};
+
+// 良い例: 必須にして起動時に検証
+type Config = {
+  apiKey: string;
+  timeout: number;
+};
+
+const loadConfig = (): Config => {
+  const apiKey = process.env.API_KEY;
+  if (!apiKey) {
+    throw new Error('API_KEY environment variable required');
+  }
+  return { apiKey, timeout: 5000 };
+};
+
+// アプリ起動時に失敗する（リクエスト中ではなく）
+const config = loadConfig();
+```
+
+---
+
+## JIT/YAGNIのコード例
+
+### 過剰設計の例
+
+```typescript
+// 悪い例: 「将来必要かもしれない」で過剰設計
+interface LogTransport {
+  write(level: LogLevel, message: string, meta?: LogMetadata): Promise<void>;
+}
+class ConsoleTransport implements LogTransport { /* ... */ }
+class FileTransport implements LogTransport { /* ... */ }
+class RemoteTransport implements LogTransport { /* ... */ }
+class Logger {
+  private transports: LogTransport[] = [];
+  private queue: LogEntry[] = [];
+  // 200行のコード…
+}
+
+// 良い例: 今必要なものだけ
+const logError = (error: Error) => {
+  console.error(error.message);
+};
+```
+
+### 段階的な複雑化
+
+```typescript
+// Step 1: シンプルに始める
+const formatCurrency = (amount: number): string => {
+  return `$${amount.toFixed(2)}`;
+};
+
+// Step 2: 要件が増えたら対応（複数通貨）
+const formatCurrency = (amount: number, currency: string): string => {
+  const symbols = { USD: '$', EUR: '€', GBP: '£' };
+  return `${symbols[currency]}${amount.toFixed(2)}`;
+};
+
+// Step 3: さらに要件が増えたら（ロケール対応）
+const formatCurrency = (amount: number, locale: string): string => {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: locale === 'en-US' ? 'USD' : 'EUR',
+  }).format(amount);
+};
+```
+
+### 早すぎる抽象化
+
+```typescript
+// 悪い例: 使用箇所1つで汎用フレームワーク構築
+abstract class BaseCRUDService<T> {
+  abstract getAll(): Promise<T[]>;
+  abstract getById(id: string): Promise<T>;
+  abstract create(data: Partial<T>): Promise<T>;
+  abstract update(id: string, data: Partial<T>): Promise<T>;
+  abstract delete(id: string): Promise<void>;
+}
+class GenericRepository<T> { /* 300行 */ }
+
+// 良い例: 今必要な関数だけ
+const getUsers = async (): Promise<User[]> => {
+  return db.query('SELECT * FROM users');
+};
+
+const getUserById = async (id: string): Promise<User | null> => {
+  return db.query('SELECT * FROM users WHERE id = $1', [id]);
+};
+// 3箇所以上で同じパターンが出てきたら抽象化を検討する
+```

package/assets/.claude/skills/reverse-engineering-common-spec/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: reverse-engineering-common-spec
+description: |-
+  既存プロジェクトに STDD を導入する際、コードベース全体をリバースエンジニアリングして common ティアの Spec（docs/common/REQUIREMENTS.md + docs/common/ARCHITECTURE.md）を作成する。サービス概要・システム構成・リポジトリ構成・レイヤ規約・データモデルを俯瞰する正典を、導入時に一度だけ生成する。機能/ページ単位のリバースエンジニアリングには reverse-engineering-feature-spec を使用する。
+when_to_use: |-
+  「STDD導入」「stdd導入」「共通spec生成」「commonティア」「プロジェクト全体のリバースエンジニアリング」「ARCHITECTURE.md作成」「アーキテクチャのドキュメント化」「既存プロジェクトにstdd」に関する作業のとき。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# common spec のリバースエンジニアリング
+
+既存（稼働中）プロジェクトに STDD を導入する際、コードベース全体を input にして **common ティア**の Spec を作成する。
+
+| 出力 | 内容 |
+| ---- | ---- |
+| `docs/common/REQUIREMENTS.md` | サービス概要・登場アクター・アプリ構成（プロジェクト全体のビジネス要件） |
+| `docs/common/ARCHITECTURE.md` | システム構成・リポジトリ構成・レイヤ規約・データモデル（プロジェクト全体の技術設計） |
+
+テンプレートは `packages/core/templates/common/REQUIREMENTS.md` / `ARCHITECTURE.md` を参照する。
+
+## 位置づけ — 導入時に一度だけ
+
+common ティアはプロジェクト全体で 1 組しか存在しない正典であり、本スキルは **STDD 導入時に一度だけ**実行する想定。
+作成後の更新（アーキテクチャ変更時など）は本スキルではなく、通常の Spec 更新として `documenting-specifications` で扱う。
+
+```
+STDD 導入フロー（既存プロジェクト）
+
+1. reverse-engineering-common-spec  ← 本スキル（一度だけ）
+        ↓  common ティアが揃う
+2. reverse-engineering-feature-spec ← 機能ごとに繰り返す
+        ↓
+3. auto-implement                    ← 以降の新機能は順行 STDD
+```
+
+**順序の理由**: 先に common ティア（レイヤ規約・共有ドメインモデル・テーブル一覧）を固定しておくと、後続の機能単位リバース（`reverse-engineering-feature-spec`）の精度と速度が上がる。
+
+---
+
+## 最重要原則 — 実装・設定が真実
+
+common ティアでも **実装が真実（Source of Truth）** である。推測や理想論で書かず、必ず一次情報を確認してから書く。
+feature ティアと違い、確認する一次情報は **UI 文言ではなく構成・設定・型定義** である。
+
+| 記述する内容 | 確認元（一次情報） | よくある間違い |
+| ------------ | ------------------ | -------------- |
+| アプリ構成・責務 | トップレベルディレクトリ / README | 想像でアプリ名・責務を書く |
+| パッケージ分割 | `package.json` の workspaces / 依存定義 | モジュール境界を推測で書く |
+| レイヤ規約・依存方向 | `domain/` 配下の実構成・lint ルール | 一般論の Clean Architecture を書く |
+| 外部サービス連携 | 環境変数・SDK の import 箇所 | 使っていないサービスを書く／使用中を漏らす |
+| テーブル一覧・ER | 生成された DB 型定義（`database.types.ts` 等） | テーブル名・カラム名を想像で書く |
+| デプロイ・環境 | CI/CD 設定（`.github/workflows` 等） | ブランチ→環境マッピングを推測で書く |
+
+---
+
+## 読む順序とチェックリスト
+
+`ARCHITECTURE.md` の目次がそのまま読む順序になる。
+
+### 1. システム構成（`REQUIREMENTS.md` のサービス概要・アクターもここで把握）
+
+```
+□ README / トップレベルディレクトリ構成 → サービスの目的・アプリ構成
+□ デプロイ設定 (vercel.json / Dockerfile / .github/workflows) → 環境とブランチ戦略
+□ 環境変数・SDK の import → 外部サービス連携 (認証 / DB / ストレージ / メール / 監視 等)
+```
+
+### 2. リポジトリ構成
+
+```
+□ package.json の workspaces / モジュール分割
+□ 依存管理ルール (どの依存がどこに置かれているか、アプリ間 import 制限の有無)
+□ 共有パッケージ (packages/shared 等) の責務
+```
+
+### 3. レイヤードアーキテクチャ
+
+```
+□ domain/ 配下の構成 (models / repository / service / ports)
+□ 依存方向ルール (UI → Service → Repository → DB 等)、禁止依存
+□ 代表的なデータフロー 1 本 (Server Action / API → Service → Repository)
+```
+
+### 4. データモデル・DB設計
+
+```
+□ 生成された DB 型定義 (database.types.ts 等) を正としてテーブルを列挙
+□ ドメイングループへの分類、中心テーブルごとの ER 図
+□ 設計方針 (論理削除 / 主キー / 時系列カラム / マイグレーション規約)
+```
+
+---
+
+## 確信が持てない箇所は要確認マーカーを残す
+
+実装からの読み取りに確信が持てない箇所は `<!-- 要確認: ... -->` のインラインコメントで明示する。
+これは**一時的な注記**であり、人間レビューで確定したら除去する（恒久的に残さない）。SSoT 原則上、確定済みの Spec に作成プロセスや未確定メモを残してはならない。
+
+```markdown
+- **外部ウォレット連携**: 関連テーブルと RPC が存在する。<!-- 要確認: 現行稼働範囲（本番で有効か） -->
+```
+
+---
+
+## 完了条件
+
+```
+□ docs/common/REQUIREMENTS.md を作成（サービス概要 / アクター / アプリ構成）
+□ docs/common/ARCHITECTURE.md を作成（システム構成 / リポジトリ / レイヤ / データモデル）
+□ テーブル一覧は生成された型定義ファイルと一致している
+□ 固有名詞・社外秘の値を不要に含めていない（公開を想定する場合）
+□ 要確認マーカーは「人間に確認すべき項目」としてレビュー依頼にまとめた
+```
+
+---
+
+## When NOT to Use This Skill
+
+- **機能 / ページ単位のリバースエンジニアリング**: `reverse-engineering-feature-spec` を使用
+- **新規機能の仕様策定**: `documenting-specifications` を使用
+- **common ティア作成後のアーキテクチャ更新**: 通常の Spec 更新として `documenting-specifications` で扱う
+
+---
+
+## 次のステップ
+
+1. **機能単位のリバース** → `reverse-engineering-feature-spec`（common ティアを前提に、機能ごとに繰り返す）
+2. **新機能の実装** → `auto-implement`（以降は Spec → Test → 実装 の順行 STDD）
+
+---
+
+## 参照ファイル
+
+- **common テンプレート**: `packages/core/templates/common/REQUIREMENTS.md` / `ARCHITECTURE.md`
+- **2 ティア構造の解説**: `packages/core/docs/stdd-methodology.md` §3.0
+- **機能単位リバース**: [reverse-engineering-feature-spec skill](../reverse-engineering-feature-spec/SKILL.md)
+- **Specテンプレート**: [documenting-specifications skill](../documenting-specifications/SKILL.md)