配布資料 2202 — rules カタログ（全10ファイル）

.claude/rules/ は「CLAUDE.md に書くと肥大する詳細規約」の分散配置先。 7ファイルは frontmatter の paths glob を持ち、該当パス編集時に文脈ロードされる想定（backend / database / deployment / frontend / testing / ui-quality / refund-architecture）。 roles / workflow / output-discipline の3つはパス指定なしの全域ルールで、hook が要点を毎セッション注入する。

CLAUDE.md は1ヶ月で477行まで膨らみました。書き足すだけの運用は必ずそうなります。

その翌週に47行まで凝縮して、詳細をここへ出しました。 毎セッション必ず読まれる唯一の文書だから、絶対原則と入口だけに絞ります。 ルールにもアーキテクチャが要ります。

分け方の基準はひとつで、「毎回必ず読ませたい原則」か「該当作業のときだけ読ませたい詳細」かです。 後者には paths を書いて、そのパスを触るときだけ読み込ませます。書き方は最後に置きました。

workflow.md — 実装・イシュー管理ワークフロー

• 目的: イシュー起票から Done までの20ステップフローと完了チェックリスト14項目を定義。全タスクの背骨
• 要点: ステップ飛ばし禁止 / 問題発見時は新規起票→その場で修正イテレーション→元イシューに戻る / Done は staging ブラウザテスト完了後のみ / 通常マージ必須（squash 禁止）/ 5タスク以上はサブエージェント駆動（Plan→Explore→coder並列→test-generator→code-reviewer）
• 参照タイミング: 全フェーズ横断（進行管理の正本）
• 誕生の経緯:/ 内部事例
• 移植のヒント: フローを「20ステップの番号付きリスト」として明文化すると、AI に「いまステップ何番か」を自己申告させられます。曖昧な「ちゃんとやる」より遥かに強く効きます

output-discipline.md — 出力規律

• 目的: ツール呼び出し書式ミス（no-op 停止）と言行不一致の再発防止。三層 hook の正本文書
• 要点: ツール呼び出しはメッセージ冒頭に単独配置 / malformed 警告時は前置きなし即再送 / 未来宣言は同ターン内に tool 呼び出しを伴う
• 参照タイミング: 毎セッション常時（hook が自動在中）
• 誕生の経緯:
• 移植のヒント: AI の失敗にも「再現条件」があります。ログから実証的にトリガーを特定して、トリガー自体を規律で排除します。バグ修正と同じ姿勢を AI の挙動にも適用してください

roles.md — 作業ロール別スキル/規律定義

• 目的: AI に委任する5ロール（PM / リードアーキテクト / プログラマー / デザインディレクター / フロントエンドコーダー）別に、必要能力・遵守規約・アンチパターン・完了定義を明文化。根拠は一般論でなくユーザーの実指示・実際の失敗
• 要点: 冒頭「全ロール共通の規律」（事実は live 値で裏取り / 着手前に全経路洗い出し / 完了は実証 / 金銭を急がない 等）が常時適用。各ロールに完了定義チェックリスト10〜11項目
• 参照タイミング: 作業着手前。フェーズごとに支配的ロールのチェックリストを適用
• 誕生の経緯: 蓄積した feedback メモリ群の集約 ほか
• 移植のヒント: 「AI に何を任せているか」をロールとして言語化すると、指示の粒度と完了判定が安定します。チェックリストは実際に起きた手戻りから逆算して書いてください

backend.md — NestJS バックエンド規則

• 目的: モジュール構成・アクター別認証・例外・バリデーションの標準パターン
• 要点: アクター別エンドポイントプレフィックス / アクター別 JWT シークレット / リフレッシュトークンはハッシュ DB 保存 + HttpOnly Cookie / Cookie sameSite は 'lax' 固定（'strict' は外部決済リダイレクト復帰で未認証誤判定）/ 業務エラーは AppException + エラーコード enum
• 参照タイミング: backend 実装時（paths glob）
• 誕生の経緯:
• 移植のヒント: 認証や Cookie のような「一度嵌ると調査が長い」領域こそ、事故の直後に規約化して定数へ集約してください

database.md — Prisma / DB 規則

• 目的: スキーマ規約と DB 破壊事故防止の安全手順
• 要点: PK は ULID（UUID 禁止）/ 物理削除禁止・deleteFlag 論理削除 + 全クエリで除外 / 監査5フィールド必須 / メール2カラム構成（表示用 + 正規化 UNIQUE）/ DB に触れる直前に必ず手動バックアップ / migration SQL は当該テーブルのみ手書き / migrate diff --shadow-database-url に実 DB 指定禁止（全テーブル DROP で破壊）
• 参照タイミング: prisma 配下変更時
• 誕生の経緯: shadow DB 指定ミスで開発 DB を全消去した事故
• 移植のヒント: ORM の「便利コマンド」には破壊的なものが混ざっています。事故ったコマンドは規約で名指し禁止にして、バックアップを直前の動作として義務化してください

deployment.md — Docker / デプロイ / SSH 規則

• 目的: SSH タイムアウトに耐える堅牢デプロイ手順と時間帯・頻度ガード
• 要点: 長時間デプロイは非同期起動（setsid + watchdog）+ マーカーファイル監視のペア必須（直接 SSH 同期実行禁止）/ 本番は JST AM2:00〜6:00 のみ / staging はセッション原則1回 / マイグレーション時は事前 DB バックアップ / 静的アセット世代保持・イメージ世代 prune / 監視は Prometheus + アラートメール
• 参照タイミング: docker 配下変更時・デプロイ実施フェーズ
• 誕生の経緯:/ 内部事例/ 内部事例/ 内部事例ほか多数
• 移植のヒント: デプロイは「AI の接続が切れても死なない」設計にします。プロセスの生存をセッションに依存させず、完了はマーカーのポーリングで確認してください

frontend.md — Next.js フロントエンド規則

• 目的: アクター別ルーティング/テーマ機構・配色トークン・メッセージ表示方式の規約
• 要点: data-actor テーマとレイアウト幅3段階 / ワイヤーフレームが正 / CSS import 順固定 / inline style 厳禁（トークン追従が壊れる）/ 主要 CTA は専用 class / 操作フィードバックは toast・恒久状態はインラインバナー・検証は入力欄直下 / ネイティブ confirm/alert 禁止 / 共通コンポーネント再利用・'use client' 最小化
• 参照タイミング: frontend 実装時
• 誕生の経緯:/ 内部事例/ 内部事例 ほか
• 移植のヒント: 表示方式（toast かバナーか）のような「毎回迷う小さな判断」を規約で固定すると、AI の出力が安定して差し戻しが激減します

testing.md — テスト規則

• 目的: ユニット/E2E の実行・命名・エラー対応規約
• 要点: ユニットはソース同居 + Prisma/Config モック化 / it 名は日本語で「状態 → 期待結果」/ テスト中に発見したエラーは目的外でも必ず修正（放置禁止・起票して着手）/ 全 PASS まで完了としない
• 参照タイミング: spec 作成・実行時（検証フェーズ）
• 誕生の経緯: > 出典: COM 参照なし
• 移植のヒント: 「既存の問題なので触りません」は AI の常套句です。発見したら直すか起票するかの二択だ、と明文化してください

ui-quality.md — UI 品質ルール

• 目的: 画面表示の用語・視認性の品質基準
• 要点: システム内部用語を画面に出さない（業務用語化）/ 社内イシュー番号を画面表示に出さない（seed 混入の自己修復 + spec ガードあり）/ コントラスト WCAG AA 4.5:1 / 入力項目にヘルプツールチップ
• 参照タイミング: frontend 実装・文言変更時
• 誕生の経緯:
• 移植のヒント: 内部識別子は、コードから seed、メール文面へと意外な経路で画面に漏れます。禁止だけでなく「混入検知の spec」と「seed の自己修復」まで作ると再発が止まります

refund-architecture.md — 返金・キャンセル・精算の絶対制約

• 目的: 金銭フロー実装の絶対制約の正本。過去に議論で否定された誤設計の再提案を禁止するリスト
• 要点: 絶対禁止10項目 / 購入者には全額返金 / 販売者負担は3成分（サービス手数料 + 返金事務コスト + 振込手数料）で feePayer 依存 / 回収は相殺→請求書の順 / ユーザー向け文言に決済事業者名・内部手数料名を出さない / 返金モード2種（運営代行 / 主催者自己）と二重送金防止 / PR 時の実装チェックリスト約30項目
• 参照タイミング: 返金/精算/キャンセル関連パスの設計・実装・レビュー時（実装前必読指定）
• 誕生の経緯: を核に十数イシューで増補
• 移植のヒント: AI は同じ誤設計を何度でも再提案します。「否定済み案のリスト」を明文化して照合を義務づけるのは、金銭や法務のような高リスク領域で特に効きます。ドメイン固有の規約をどう書くかの見本としても使えます

補記: rules と skills の鮮度管理（教材の重要論点）

同じ知識が rules と skills の両方に書かれると、片方だけ更新されて腐ります（実際、skill 内の Cookie 例が旧仕様のまま残っていました）。正本は rules 側と決め、skills は手順のみ・知識は rules へのポインタにするのが安全です。

rules の書き方

パス連動のルール（frontmatter に paths を書く）

該当するファイルを触ったときだけ読み込ませたいものは、先頭に glob を書きます。 全域ルールにしないことで、毎回のコンテキストを軽く保てます。

---
description: Prisma / DB 規則（スキーマ規約と DB 破壊事故の防止）
paths:
  - "apps/api/prisma/**"
  - "apps/api/src/**/*.repository.ts"
---

# Prisma / DB 規則

## 絶対に守ること

- **DB に触れる直前に、環境を問わず必ず手動バックアップを取る**
  対象コマンド: `migrate deploy` / `migrate dev` / `db push` / `migrate diff`
- `migrate diff --shadow-database-url` に実 DB を指定しない
  → 指定した DB は全テーブル DROP される。開発 DB を1回全消去した（事例 #04）
- 物理削除は禁止。`deleteFlag` による論理削除とし、全クエリで除外する

## 迷ったら

PK は ULID を使う（UUID は禁止）。監査5フィールドは全テーブル必須。
メールは2カラム構成（表示用 + 正規化した UNIQUE 制約用）。

要点は、禁止事項に「なぜ」を1行添えることです。

理由のない禁止は、次のセッションの AI にとって根拠のない制約でしかありません。 根拠がないと、もっともらしい例外を作って回避してきます。事故番号を添えておくと強く効きます。

否定した案を残すルール

これは金銭や法務のような高リスク領域で特によく効きます。 採用した設計だけでなく、却下した案とその理由を表にして残しておきます。

---
description: 返金・キャンセル・精算の絶対制約（実装前必読）
paths:
  - "apps/api/src/refund/**"
  - "apps/api/src/settlement/**"
---

# 返金アーキテクチャの絶対制約

## 絶対禁止（過去に議論で否定された設計）

| # | 禁止する設計 | 理由 |
|---|---|---|
| 1 | 将来売上からの天引きで返金原資を回収する | 販売者が退会したら回収できない |
| 2 | 決済手数料を「ほぼ±0」として計算から除外する | 1件数十円でも年間数万件で数百万円。商売として許容できない |
| 3 | 銀行振込での補填を原資回収の手段にする | 原資問題を構造的に解決していない |

## 正本

回収は「相殺 → 請求書」の順。詳細は要件定義（機能別 41）を参照。
**この表にある設計を再提案しないこと。** 提案する場合は、まず要件定義を読むこと。

AI はセッションを跨ぐと否定された記憶を失います。だから同じ案が何度でも戻ってきます。 実際、返金の設計では8パターンを却下して、同じ案が2回出てきました（事例 #11）。

否定リストがなければ、AI は同じ提案を必ず繰り返します。

CLAUDE.md 側には何を残すか

分散したあとの CLAUDE.md は、原則と入口だけになります。179行で安定しています。

# プロジェクト名 — 作業指示

## 絶対遵守

1. **完了は実証で示す。** grep や機械の出力だけで「完了」と言わない
2. **本番には自分で触らない。** 明示指示の引用がない限りデプロイしない
3. **スカッシュマージ禁止。** 通常マージのみ（コード欠損事故を起こした）

## 詳細ルール

`.claude/rules/` に分散している。該当パスを触るときに自動で読み込まれる。

- `workflow.md` — 起票から Done までの20ステップ
- `database.md` — スキーマ規約と DB 破壊事故の防止
- `refund-architecture.md` — 金銭フローの絶対制約（**実装前必読**）

15行から始めて大丈夫です。作り込まないでください。 このプロジェクトも15行から始めて、膨らませて、減らして、今の形に落ち着きました。