- コピー先
your-repo/.cursor/rules/00-project.mdc- 目的
- 毎セッションの土台。docs 正本・推測での API/DB 断定禁止。
- 使うツール
- Cursor
- 適用
- alwaysApply: true（毎セッション自動適用）
手順: Cursor 利用時は最初に置く。10-domain-rules より先に作成する。
---
description: プロジェクト共通。毎セッション適用。
alwaysApply: true
---
# プロジェクト共通
## 参照順
1. tasks/todo.md（今回の Plan）
2. docs/<feature>/（仕様）
3. 既存 src/ の同種実装
## 禁止
- 仕様を Rules に複製しない（docs を読む）
- 推測で API / DB スキーマを断定しない
- コピー先
your-repo/.cursor/rules/10-domain-rules.mdc- 目的
- 金額・状態遷移・用語など業務の不変条件だけを書く。一般論や長い手順は他ファイルへ。
- 使うツール
- Cursor
- 適用
- alwaysApply: true（ドメイン違反は厳禁）
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: プロジェクト固有のドメイン制約。全実装・全レビューで参照する。
alwaysApply: true
---
# ドメインルール (違反厳禁)
> NOTE: ここにはプロジェクト固有の事実だけを書く。一般論や長い手順は他ファイルへ寄せる。
## 数値計算 (該当する場合)
- 金額/数量/単価/利率/物理量など、誤差が許容できない値は固定小数 (Decimal等) 必須
- float の使用箇所と禁止箇所を明示
- 丸めポリシー: ROUND_HALF_EVEN / HALF_UP / DOWN のどれを使うか
- 単位系の統一 (SI/カスタム)
## 業務不変条件
ここにプロジェクト固有の不変条件を列挙する。例:
- ユーザは同時に複数のアクティブセッションを持てない
- 注文金額は0より大きい
- 在庫数量は0以上
## 業務ルール (具体的な処理ルール)
ここに業務処理のルールを記載。例:
- A状態からB状態への遷移は管理者のみ可能
- イベント Z の発生時は通知 Y を必ず送る
- データ X は論理削除のみ、物理削除禁止
- 外部通知 / メール / 課金 / ジョブ投入など副作用は、発火条件・順序・再実行可否を明示
- 取消不能な操作や公開処理は、事前条件と監査要件を明示
## 例外設計
- 業務例外は `domain/errors` などプロジェクトで定めた場所に集約
- `BusinessRuleError` 等の業務例外と、技術例外 (DB接続失敗等) を明確に分離
- 業務例外はログレベル WARNING、技術例外は ERROR
## 用語統一 (日↔英マッピング)
ここに業務用語と英訳のマッピングを記載。例:
- 顧客 → customer
- 注文 → order
- 担当者 → assignee
- コピー先
your-repo/.cursor/rules/20-coding-style.mdc- 目的
- 言語・フレームワーク固有のコーディング規約。globs で対象ファイルを限定する。
- 使うツール
- Cursor
- 適用
- globs で **/*.ts 等に限定（alwaysApply は false 推奨）
手順: スタックに合わせて globs と本文を差し替える（Next.js / Go 等）。
---
description: TypeScript / React のコーディング下限
globs: apps/web/**/*.{ts,tsx}
alwaysApply: false
---
# TS/React
- Server Component をデフォルト。Client は必要なときのみ
- 新規 API は src/lib/api/ の既存ラッパに合わせる
- コピー先
your-repo/.cursor/rules/30-testing.mdc- 目的
- テストコマンド・カバレッジ方針・Docker 経由の実行方法を固定する。
- 使うツール
- Cursor
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: テスト方針。変更に最も近い粒度から検証し、必要なときだけ外側へ広げる。
globs: tests/**, **/*test*, **/*spec*
---
# Testing Rules (TDD)
## 基本方針
- 変更箇所に最も近いテストから追加・実行する
- ドメイン / ロジック変更は unit or use-case tests を優先し、E2E は主要経路に絞る
- リポジトリやタスクで厳格TDDが必要な場合は `61-tdd-loop.mdc` を併用する
## TDD方針 (層別)
| 層 | 方式 | 厳格度 |
|---|---|---|
| domain | Inside-out TDD (Red-Green-Refactor 厳守) | 高 |
| application | ユースケース単位TDD (Refactorは時間次第) | 中 |
| infrastructure| 結合テスト先行 | 低 |
| interface | E2E でハッピーパス + 主要異常系 | 低 |
## Red-Green-Refactor サイクル
1. RED: 失敗する最小のテストを1つ書く。実装は一切書かない
2. GREEN: テストが通る最小コードを書く。過度な抽象化禁止
3. REFACTOR: テストを保ったまま設計改善。新規テスト追加は別サイクル
## 1サイクルの粒度
- 1サイクル = 1つの振る舞い / 失敗理由に絞る
- failing test は「意図した理由」で失敗していることを確認する
## カバレッジ (チーム基準に合わせる)
- CI / リポジトリ設定に閾値がある場合はそれを正本とする
- 数値だけを追わず、変更した分岐・例外・境界値・副作用の観点を優先する
- 目安: 重要ドメインは C0 90% 前後、その他はチーム合意に合わせる
## テスト命名
test_<対象>_<条件>_<期待結果>
## 必須カバー観点
- 正常系
- 境界値 (0, null, 空配列, 上限, 下限)
- 異常系 (バリデーション違反, 外部依存失敗)
- ドメイン特有 (業務不変条件を破ろうとするケース)
- 並行性 (該当する箇所のみ)
## アンチパターン
- 実装に合わせてテストを後追いで書く
- 1テストで複数assertを混ぜる
- モック過多でドメインロジックがテストされない
- テストをコメントアウトしてGREEN偽装
- 既存テストが落ちたら理由を考えず修正する
- 時刻 / 乱数 / 外部I/O に依存する flaky test を増やす
- コピー先
your-repo/.cursor/rules/40-logging.mdc- 目的
- ログレベル・構造化ログ・request_id の付け方を統一する。
- 使うツール
- Cursor
- 適用
- globs: バックエンド実装向け
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: ログ・機微情報規約
alwaysApply: true
---
# Logging Rules
## フォーマット
- 構造化ログ (JSON) を優先。event 名は安定した識別子にする
- 必須フィールド: timestamp / level / event / trace_id (or request_id)
- 業務イベント時は主要識別子 (user_id, order_id 等) を含む
- request / response / prompt / 添付本文の全量出力は原則しない
## レベル
- DEBUG: 開発時のみ、本番無効
- INFO : 業務イベント (作成・更新・削除・状態遷移)
- WARN : 業務例外、回復可能なエラー
- ERROR: 技術例外、回復不能なエラー
- CRITICAL: データ不整合検出、即時対応必要
## マスキング (プロジェクトポリシーに合わせる)
- 機密IDは部分マスキング (例: 下4桁のみ)
- 個人氏名/住所/電話/メール/クレジットカード等: ログ出力禁止
- 認証トークン・APIキー: ログ出力禁止
- 例外メッセージや外部APIエラー本文にも機微情報を残さない
## 出力先
- 標準出力 (コンテナ環境前提、12-factor準拠)
- 集約は基盤側 (Datadog/CloudWatch/Stackdriver等) に任せる
- コピー先
your-repo/.cursor/rules/50-documentation.mdc- 目的
- docs/ や ADR の置き場・書式。仕様の正本を docs に置く方針を明示する。
- 使うツール
- Cursor
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: ドキュメント規約 (docs を正本、z_docs は任意の作業メモ)
globs: ["docs/**", "z_docs/**"]
---
# Documentation Rules
## docs/ と個人メモ (z_docs/) の扱い
### docs/ (チーム公式ドキュメント、レビュー必須、品質バー高)
- docs/architecture.md # 全体アーキテクチャ (常時更新)
- docs/glossary.md # 用語集 (常時更新)
- docs/setup.md # セットアップ手順
- docs/adr/<NNNN>-<slug>.md # ADR (Architecture Decision Records)
- docs/<feature-name>/README.md # 機能ドキュメントの索引
- docs/<feature-name>/01_requirements.md
- docs/<feature-name>/02_design.md
- docs/<feature-name>/03_db_schema.md
- docs/<feature-name>/04_tech_decisions.md
- docs/<feature-name>/05_test_plan.md
- docs/<feature-name>/06_logging.md
- docs/<feature-name>/07_deployment.md
- docs/operations/<runbook>.md # 運用手順・障害対応
### z_docs/ (任意のローカル作業メモ)
- z_docs/history/yymmdd-hhMM-summary.md # セッションごとの作業ログ
- z_docs/<feature-name>/00_plan.md # 必要なら残す個人タスク分解
- z_docs/scratch/ # 試行錯誤・調査メモ
- z_docs/notes/ # 個人メモ
### 判定基準
| この文書は? | 配置先 |
|---|---|
| チームメンバー・将来の自分が必ず読む | docs/ |
| レビュー対象、品質が問われる | docs/ |
| 意思決定の根拠 (永続化したい) | docs/adr/ |
| 個人用のドラフト・下書き (必要なら) | z_docs/ |
| 個人用の作業ログ・振り返り (必要なら) | z_docs/history/ |
| 個人的な試行錯誤・調査メモ | z_docs/scratch/ |
> z_docs は必要なときの個人メモ置き場。同じ情報を docs/ と二重管理しない。正式に残す内容は docs/ を正本として扱う。
## 書式 (共通)
- Mermaidは最小構文。erDiagram / sequenceDiagram / flowchart のみ
- エッジラベル `|...|` に HTML を入れない
- 表は意思決定の根拠を1列入れる
- スクリーンショット・バイナリは原則禁止 (UIスクショは assets/ で別途管理)
## トーン (docs/)
- レビュアー (他人・将来の自分・新メンバー) が読む前提
- 前提知識を仮定しない
- 用語は docs/glossary.md と整合
## トーン (z_docs/)
- 自分用メモなので簡潔でよい
- 共有する可能性がある場合だけ、後から自分が読める程度の文脈を残す
- コピー先
your-repo/.cursor/rules/60-ai-workflow.mdc- 目的
- Plan・作業ログ・git 方針・Obsidian 等、AI 運用の手順をまとめる。
- 使うツール
- Cursor
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: AIエージェントの動き方の規約
alwaysApply: true
---
# AI Workflow
## このファイルの役割
- 常時守る進め方だけを書く
- 長い手順・フェーズ別チェックリストは Skill / prompt template に分ける（TDD 詳細は任意の Skill）
## 進め方
- 1チャット = 1タスクを基本とし、スコープがズレたら分割を提案する
- 編集前に関連する既存コード・既存テスト・関連ドキュメントを読む
- 既存規約と異なる選択をする場合は理由を明示する
- 推測で埋めず、未確認事項は確認事項として残す
## 検証
- 変更後は最小の有効な確認 (テスト / lint / 型チェック / 画面確認) を実施する
- 実行していない確認は「未実施」と明記する
- 失敗した既存テストや lint を無言で握りつぶさない
## 履歴整備
- セッションの作業ログが必要な場合は z_docs/history/ に短く残す
- チームで残すべき判断は docs/<feature>/04_tech_decisions.md または docs/adr/ に記録する
- 正式な仕様を z_docs だけに閉じ込めない
- コピー先
your-repo/.cursor/rules/61-tdd-loop.mdc- 目的
- Red → Green → Refactor の TDD ループと完了条件をエージェントに守らせる。
- 使うツール
- Cursor
- 適用
- globs: テスト駆動が必要な実装タスク向け
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: 厳格なTDDを採るタスクで使う運用規約。テスト先行の進め方を揃える。
---
# TDD Loop Rules for AI
## 使う場面
- ユーザーが TDD を明示したとき
- リポジトリ / 対象層が test-first を前提としているとき
- docs / 単純リネーム / 設定変更など、挙動を増やさない作業では無理に使わない
## 厳守事項
- RED: 失敗する最小テストを先に追加し、失敗理由を確認する
- GREEN: そのテストを通す最小実装に留める
- REFACTOR: 振る舞いを変えずに重複削減・命名改善・構造整理を行う
- 新しい振る舞いを足すときは次の RED に戻る
- 各サイクルで実行したテストコマンドと結果を共有する
## サイクル粒度
- 1サイクル = 1つの振る舞い / 失敗理由に絞る
- 大きすぎる変更はテストケース単位に分割する
- コピー先
your-repo/.cursor/rules/70-local-env.mdc- 目的
- Docker・ローカル DB・環境変数など開発環境の起動・検証手順。
- 使うツール
- Cursor
手順: docker compose 等、プロジェクトの実コマンドに必ず差し替える。
---
description: ローカル開発環境はDocker前提。コマンド提示時はコンテナ経由を必須とする。
alwaysApply: true
---
# ローカル開発環境ルール
## 原則
- ホストOSに言語ランタイム・DB・キャッシュを直接インストールしない
- 全ての開発コマンドはコンテナ内で実行する
- 接頭辞: `docker compose exec <service> <command>`
- 例外: `git` `docker` `make` 自体はホスト側で実行
## AIエージェントへの指示
実行系コマンドを提案する際は、必ず以下の形式で提示すること:
- 悪い例: `pip install httpx`
- 良い例: `docker compose exec app pip install httpx` (一時的) または
Dockerfile.dev / pyproject.toml に追加し `docker compose build app` (恒久)
- 悪い例: `pytest tests/`
- 良い例: `make test` または `docker compose exec app pytest tests/`
- 悪い例: `psql -U app app_dev`
- 良い例: `make shell-db` または `docker compose exec db psql -U app -d app_dev`
## 新規依存追加時のフロー
1. パッケージマネージャ定義ファイル (pyproject.toml / package.json / go.mod) に追記
2. `docker compose build app` でイメージ再ビルド
3. `docker compose up -d` で再起動
4. 既存コンテナで一時的に試したい場合のみ `docker compose exec app <install>`
## 環境変数
- `.env.example` を雛形として配布
- 各開発者は `.env` を作成 (gitignore対象)
- 新規環境変数を追加した場合は `.env.example` も同時更新 + PR本文で言及
## IDE統合
- IDE実行 (Cursor/VS Code) は Dev Containers 経由を推奨
- ホスト側のフォーマッタ/lintはCIで担保される前提なら使用可
- ただしテスト・ビルド・マイグレーションは必ずコンテナ内で実行
- コピー先
your-repo/.cursor/rules/git-safety.mdc- 目的
- git 操作は明示許可後のみ。
- 使うツール
- Cursor
- 適用
- alwaysApply: true 推奨
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: git push 等はユーザー許可後のみ
alwaysApply: true
---
# Git 安全運用
## 許可なしに実行しない
- git add / commit / push / merge / rebase
- docker exec（本番相当）
## 完了報告前
- 関連テストまたは再現手順で動いたことを示す
- コピー先
your-repo/.cursor/rules/api-errors.mdc- 目的
- API のエラーレスポンス形式と HTTP ステータスの対応を揃える。
- 使うツール
- Cursor
- 適用
- globs: API 実装ファイル向け（必要なときだけ）
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: API エラーレスポンスの形式と HTTP ステータスの対応
globs: src/**/*.{ts,py,go}
alwaysApply: false
---
# API エラー
## レスポンス形
- クライアント向け: `{ "error": { "code": "...", "message": "..." } }`
- ログ用 request_id はレスポンスヘッダ `X-Request-Id` に載せる
## ステータス
- 400: バリデーション
- 401/403: 認証・認可
- 404: リソース不存在
- 409: 競合（在庫不足など）
- 500: 未分類（スタックはログのみ）
- コピー先
your-repo/.cursor/rules/ui-list.mdc- 目的
- 管理画面の一覧・テーブル UI を既存パターンに合わせて追加するときの指針。
- 使うツール
- Cursor
- 適用
- globs: フロントエンド向け
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: 管理画面の一覧・テーブル UI を追加するとき
globs: apps/web/**/*.{tsx,ts}
alwaysApply: false
---
# 一覧 UI
- 既存の DataTable / List コンポーネントを先に @ してパターンを合わせる
- 列定義・ソート・ページネーションは Storybook または既存画面と同型
- マージ前: Storybook 表示 + `npm test`（プロジェクト標準）
- コピー先
your-repo/AGENTS.md- 目的
- Codex（と Cursor 併用時）が最初に読む短い索引。ビルド・テスト・禁止事項への入口。
- 使うツール
- Cursor · Codex
- 補足
- AGENTS.md（リポ直下）
手順: リポジトリのルート（package.json や README と同じ階層）に置く。
# AI Agent Instructions
## このファイルの役割
- `AGENTS.md` は入口。長い手順や詳細規約は `.cursor/rules/*.mdc`（Cursor）または `.agents/skills/`（Codex）に分ける
- ここには「何を読むべきか」「どこに書くべきか」だけを短く残す
## プロジェクト概要
[1〜2段落でプロジェクトの目的・主要ユーザ・主要機能を記載]
## ステークホルダー
- PO/PM: [氏名]
- テックリード: [氏名]
- レビュアー: [氏名 or チーム]
## 必読ルール
- .cursor/rules/10-domain-rules.mdc ← 業務制約。違反厳禁
- .cursor/rules/20-coding-style.mdc
- .cursor/rules/30-testing.mdc
- .cursor/rules/40-logging.mdc
- .cursor/rules/50-documentation.mdc
- .cursor/rules/60-ai-workflow.mdc
- .cursor/rules/61-tdd-loop.mdc ← 厳格TDDを採るタスクのみ
- .cursor/rules/70-local-env.mdc ← ローカル環境の制約がある場合のみ
## 出力先
- **チーム公式ドキュメント** (要件・設計・ADR等): docs/
- **セッション履歴・作業メモ**: z_docs/history/
- **機能別の下書き・調査メモ** (必要なときだけ): z_docs/<feature-name>/ または z_docs/scratch/
- 実装: src/
- テスト: tests/
- ADR (Architecture Decision Records): docs/adr/
詳細な使い分けは `.cursor/rules/50-documentation.mdc` と `.cursor/rules/60-ai-workflow.mdc` を参照。
## 既存パターンの参照
新規実装時は以下を必ず先に確認:
- 類似機能の実装例: [パスを記載]
- 既存のドメインサービス: src/domain/
- 既存テストパターン: tests/unit/
- 既存ドキュメント / ADR: docs/
## 禁止事項
- [ドメインルールに違反する実装パターン]
- ログ・エラー・監査イベントへの個人情報 / 機微情報 / secret の平文出力
- 既存実装・既存テスト・既存ドキュメントを読まずに「最善実装」を提案すること
- コピー先
your-repo/AGENTS.md- 目的
- Codex 専用の補足・検証コマンドを AGENTS.md に追記するときの例。
- 使うツール
- Codex
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Codex で codex --ask-for-approval never "Summarize the current instructions." を試す
# AI Agent Instructions（Codex 向け補足例）
## このファイルの役割
- 毎回守る方針・ビルド/テストコマンド・レビュー期待だけを書く
- 長い手順は `.agents/skills/` へ。Cursor 併用時の詳細規約は `.cursor/rules/*.mdc` へ
- サブツリー固有の規約は `packages/<name>/AGENTS.md` 等、適用範囲の近くに置く
## ビルド・テスト（このディレクトリで使うコマンド）
- 開発: [例: npm run dev]
- テスト: [例: npm test --workspace=foo]
- Lint: [例: npm run lint]
## レビュー・禁止事項
- [ドメイン不変条件]
- [要確認コマンド: git push / docker exec / 本番操作]
- [機微情報をログ・PR に出さない]
## ルーティング（読みすぎ防止）
- 設計の正: `docs/architecture.md`
- 機能仕様: `docs/<feature>/`
- 作業履歴: `z_docs/history/`（チーム規約で docs を使う場合はそちら）
- コピー先
your-repo/CLAUDE.md- 目的
- Claude Code がプロジェクト開始時に読む短いルール入口（目安 200 行以下）。
- 使うツール
- Claude Code
- 補足
- CLAUDE.md（Project）
手順: /init で下書き生成後、短く削ってから保存。
# Claude Code Instructions
@AGENTS.md ← AGENTS.md を併用する場合のみ
## このファイルの役割
- ルートは薄く（全体像・クリティカルな gotcha）。パッケージ固有は `packages/<name>/CLAUDE.md` 等のサブツリーへ
- `AGENTS.md` と重複させず、Claude Code 固有の補足だけを書く
- 長い手順は `.claude/skills/` へ、パス別 / 言語別の恒久ルールは `.claude/rules/` へ寄せる
- 個人だけが使うプロジェクト固有メモは `CLAUDE.local.md` に分離し、コミットしない
- この配下で使う test / lint コマンドを明示する（大規模リポでは全件実行を避ける）
## User scope
- 応答言語: [日本語 / 英語]
- 要確認コマンド: [git push / docker exec / aws / 本番操作]
- 個人環境共通の禁止事項: [例: bypass permissions を常用しない]
## Project scope
### Claude Code 固有の補足
- Plan / execution の分岐条件: [例]
- 追加の確認が必要な危険操作: [例]
- Claude Code 専用の skill / hook / local memory 運用: [例]
### Cursor ルールとの対応
- ドメイン制約: [.cursor/rules/10-domain-rules.mdc と同旨]
- 実装規約: [.cursor/rules/20-coding-style.mdc と同旨]
- テスト方針: [.cursor/rules/30-testing.mdc と同旨]
- 厳格TDDが必要なとき: [.cursor/rules/61-tdd-loop.mdc と同旨]
- ログ / 機微情報: [.cursor/rules/40-logging.mdc と同旨]
- ドキュメント配置 / 作業履歴: [.cursor/rules/50-documentation.mdc, 60-ai-workflow.mdc と同旨]
### よく使うコマンド
- 開発: [例: make up / npm run dev]
- テスト: [例: make test / npm test]
### 禁止事項
- [ドメインルールに反する実装]
- [未確認のまま本番操作]
- [機微情報の出力]
- コピー先
your-repo/CLAUDE.local.md- 目的
- 個人だけのメモ（ショートカット・好み）。チームには共有しない。
- 使うツール
- Claude Code
- 補足
- CLAUDE.local.md（gitignore・個人のみ）
手順: .gitignore に CLAUDE.local.md を追加すること。
# CLAUDE.local.md（コミットしない）
- 個人だけのプロジェクト固有メモ（ショートカット・好みのコマンド）
- `.gitignore` に `CLAUDE.local.md` を追加
- チーム共有は `CLAUDE.md` または `docs/` / `tasks/`
- コピー先
~/.claude/CLAUDE.md- 目的
- 全リポ共通の文体・言語・推測実装禁止など。業務ルールはリポ側へ。
- 使うツール
- Claude Code
手順: mkdir -p ~/.claude して配置。3〜6 ヶ月ごとに棚卸し。
# ~/.claude/CLAUDE.md（User スコープ）
- 全リポ共通の文体・言語・「推測で広く実装しない」等
- プロジェクト固有の業務ルールはリポの `CLAUDE.md` / `.cursor/rules/` へ（重複禁止）
- 3〜6 ヶ月ごとに棚卸し
- コピー先
~/.codex/AGENTS.md- 目的
- Codex の個人グローバル設定。文体・確認の好みのみ（リポ AGENTS と重複禁止）。
- 使うツール
- Codex
手順: 1. 配置先のフォルダを用意（例: mkdir -p ~/.codex） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え
# ~/.codex/AGENTS.md
- 個人グローバル: 文体・確認の好みのみ
- リポの `AGENTS.md` と重複させない
- 手順の詳細は `$HOME/.agents/skills/` へ
- コピー先
your-repo/.claude/skills/<name>/SKILL.md- 目的
- Claude Code 向けの多段手順。description でトリガーさせる。
- 使うツール
- Claude Code
手順: を手順名（例: phase4-tdd）に置き換えてフォルダごと作成。
.claude/skills/
├── phase1-rules-sync/
│ ├── SKILL.md
│ └── checklist.md
├── phase3-design-doc/
│ └── SKILL.md
└── phase4-domain-tdd/
├── SKILL.md
└── examples/
└── red-green-refactor.md
# 例: .claude/skills/phase4-domain-tdd/SKILL.md
---
description: ドメイン層の厳格なTDDを1サイクルずつ進めるときに使う
disable-model-invocation: true
---
## 使う場面
- ドメイン層の TDD を 1 サイクルずつ進めるとき
## 入力
- 対象ユースケース / 既存テスト / 関連ドメインルール
## 手順
1. RED: 失敗する最小テストを書く
2. GREEN: 最小実装で通す
3. REFACTOR: 設計改善のみ行う
## 参照ルール
- .cursor/rules/30-testing.mdc と同旨
- .cursor/rules/61-tdd-loop.mdc と同旨
- コピー先
your-repo/.claude/settings.json- 目的
- Claude Code の Hooks（停止時テスト等）。任意だが品質安定に有効。
- 使うツール
- Claude Code
- 補足
- .claude/settings.json（Hooks）
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.claude） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Claude Code で /init 後、CLAUDE.md が短いか確認
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-dangerous-command.sh" }]
}]
}
}
- コピー先
your-repo/.agents/skills/<name>/SKILL.md- 目的
- Codex / Cursor 併用時の共有 Skills。長い手順はここに置く。
- 使うツール
- Codex · Cursor
手順: チーム共有なら .agents/skills/ をコミット対象にする。
.agents/skills/
└── phase4-domain-tdd/
├── SKILL.md
└── scripts/
└── run-red-cycle.sh # 任意
# 例: .agents/skills/phase4-domain-tdd/SKILL.md
---
name: phase4-domain-tdd
description: ドメイン層の厳格なTDDを1サイクルずつ進める。RED-GREEN-REFACTOR の順守が必要なときに使う。
---
1. RED: 失敗する最小テストを追加し、失敗理由を確認する
2. GREEN: そのテストを通す最小実装に留める
3. REFACTOR: 振る舞いを変えずに構造を改善する
4. 各サイクルで実行したテストコマンドと結果を共有する
## 参照
- .cursor/rules/30-testing.mdc と同旨（Cursor 併用時）
- docs/<feature>/05_test_plan.md
- コピー先
your-repo/.codex/config.toml- 目的
- Codex CLI の承認ポリシー等。リポまたはユーザーホームに置く。
- 使うツール
- Codex
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.codex） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え
# .codex/config.toml（例・必要なキーのみ）
# 詳細: https://developers.openai.com/codex/config-reference
[approval_policy]
# 対話実行: on-request / 非対話 CI: never など、チーム方針に合わせる
[[hooks]]
event = "pre_tool_use"
# matcher / command はリポのポリシーに合わせて定義（パスは .codex/ 基準）
- コピー先
your-repo/.cursor/skills/pr-review/SKILL.md- 目的
- PR レビュー手順を Skill 化した例。Cursor が必要時に読み込む。
- 使うツール
- Cursor
手順: mkdir -p .cursor/skills/pr-review して SKILL.md を配置。
---
name: pr-review
description: >
PR 提出前のセルフレビュー。lint・テスト・PR description・docs 整合を確認する。
ユーザーが PR 前確認・レビュー準備を求めるときに使う。
paths:
- "**/*.{rb,ts,tsx}"
---
# PR セルフレビュー
## ワークフロー
- [ ] make test（またはプロジェクト標準）
- [ ] PR description にレビュー観点を 1 行以上
- [ ] migration がある場合 forward / rollback を確認
- [ ] tasks/todo.md の Done when と整合
## 出力
未完了があればブロッカーとして報告。すべて OK なら提出可と明示。
- コピー先
your-repo/.cursor/commands/review.md- 目的
- Cursor の /review 用プロンプト。レビュー観点を固定する。
- 使うツール
- Cursor
手順: mkdir -p .cursor/commands してから配置。
# review
PR 提出前のセルフレビュー。対象: $ARGUMENTS（未指定なら現在の差分・ブランチ）
1. `git diff` / `git status` の要点を確認（commit/push は許可があるまで提案しない）
2. flow-14-pr-check.html の 9 カテゴリ観点でブロッカー / 警告 / OK を分類
3. `.cursor/rules/` と `AGENTS.md` への抵触がないか
4. 結果は箇条書き。ブロッカーがあれば push / PR 作成を提案しない
- コピー先
your-repo/.cursor/commands/plan.md- 目的
- Cursor の /plan 用。調査のみ・Plan 保存の指示をテンプレ化。
- 使うツール
- Cursor
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/commands） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
# plan
複雑な作業の着手前に Plan を書く。$ARGUMENTS があれば今回の機能名・スコープとして扱う。
1. `tasks/todo.md` を読み、未完了があれば更新方針を示す
2. チェック可能なタスク分解と **Done when** を書く（検証ステップまで含める）
3. 3 ステップ以上または設計判断があるときは Plan モード推奨。承認後に実装
4. 仕様の正本は `docs/`。推測で API / DB を断定しない
5. 参照: guide-design.html#phase-2-plan、guide-ops.html#18-plan-patterns
- コピー先
your-repo/.cursor/commands/investigate.md- 目的
- 障害調査用コマンド。ログ・再現手順の観点を揃える。
- 使うツール
- Cursor
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/commands） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
# investigate
次のスコープだけを調査し、構造化結果だけ返す: $ARGUMENTS
- 返却: `{ "paths": [...], "summary": "..." }` または表
- 長い grep ログは貼らない
- git add/commit/push はしない
- コピー先
your-repo/tasks/todo.md- 目的
- Plan 正本。Done when を書く。
- 使うツール
- Cursor · Claude Code · Codex
手順: mkdir -p tasks して配置。セッション開始時に AI に最初に読ませる。
# tasks/todo.md — <feature-slug>
## タスク
- [ ] docs/prd/<slug>.md の Must → 01_requirements.md（ID トレース）
- [ ] ADR ドラフト
- [ ] ユースケース実装 + 結合テスト
- [ ] PR 前: pr-review Skill でセルフチェック
## Done when
- staging / 手元で受け入れ条件を手動確認（手順を PR に記載）
- CI green
## リスク・未決
- 未決の設計判断 → ADR で決める
## レビュー・結果
（実装後: 変更概要、検証コマンド、残課題）
- コピー先
your-repo/tasks/lessons.md- 目的
- 指摘・修正パターンの蓄積。再発時はルールや ADR に昇格する。
- 使うツール
- Cursor · Claude Code · Codex
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/tasks） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
# tasks/lessons.md
| 日付 | 状況 | 教訓 | 再発防止 |
|------|------|------|----------|
| 2026-05-29 | push 許可なしで commit 提案 | 危険操作は必ず確認 | git-safety.mdc |
- コピー先
your-repo/.cursor/plans/YYYYMMDD-feature.md- 目的
- Cursor Plan モードの保存先例。ワークスペース内の下書き Plan。
- 使うツール
- Cursor
手順: YYYYMMDD-feature を実タスク名に変えて .cursor/plans/ に保存。
# Plan: <feature> Phase 3
## スコープ
- PRD Must の範囲のみ（Won't は触らない）
## タスク分解
1. 01_requirements.md — PRD Must → 要件 ID
2. 02_design.md — API / ジョブ / エラー型
3. ADR — 主要な設計判断
## 検証（省略しない）
- [ ] 01_requirements.md をレビュアーに渡せる
- [ ] 未決は tasks/todo.md「リスク」に列挙
## 参照
- docs/prd/<slug>.md
- .cursor/rules/10-domain-rules.mdc
- コピー先
your-repo/.cursor/rules/agent-workflow-orchestration.mdc- 目的
- AI_Doc 用。Plan・サブエージェント・検証・tasks 記録の運用正本。
- 使うツール
- Cursor
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: エージェント運用（Plan・調査の任せ方・検証・タスク記録）
alwaysApply: true
---
# エージェント運用オーケストレーション
`index.html`（Playbook Hub）・`guide-ops.html#18-orchestration`・`tasks/todo.md` / `tasks/lessons.md` と整合させる。HTML サイト編集時は `html-doc-site.mdc` も併用する。
## 1. まず Plan モードで始める
- **複雑な作業**（手順が3つ以上、または設計の判断が必要）では Plan モード（同じような計画の段階）で始める。
- 方針がずれたら無理に続けず、**すぐ計画をやり直す**。
- Plan には実装だけでなく**確認ステップ**（テスト・本番 HEAD・リンク確認など）まで含める。
- 曖昧さを減らすため、**先に詳細な仕様・完了条件**を書く。
- Plan の置き場は状況で選ぶ — **チャット Plan モード** / `.cursor/plans/` / `tasks/todo.md`（詳細: `guide-ops.html#18-plan-patterns`）。
## 2. 調査は別の AI に任せる
正本の詳細・シナリオ: `guide-ops.html#18-2-subagents` / `#18-multiagent`
- メインの会話を散らかさないよう、**別の AI 担当（Task ツール等）を積極的に使う**。
- 調査・探索・並列分析は別の AI 担当に任せる。
- 複雑な問題は、担当を増やして切り分ける。
- **1 担当 = 1 タスク**で焦点を絞る。
### 任せる場面（メインがやらない）
- コードベースの広い調査・「どこにある？」・並列分析
- 複数ディレクトリにまたがる ripgrep / 探索（メインに長いログを流さない）
- 執筆・実装の**前段**の調査だけ（結果を構造化して返す）
### 任せない場面（メインで続ける）
- 同一機能の反復デバッグ（直前の実装文脈が必要）
- 特定 1〜2 ファイルの読み取り・小さな修正
- ユーザーが指定したファイルを `@` してすぐ触る作業
### 委譲の約束（データ契約）
- プロンプトに **スコープ**（例: `src/domain/` のみ）と **返却形式** を書く
- メインに戻すのは**構造化結果だけ**（全文ダンプ・長い grep 出力を貼らない）
- 例: ファイルパス一覧、`{ "paths": [...], "summary": "..." }`、表形式の早見表
- コードベースを総 `@` しない。自然言語で領域を指定し、必要なら 1 ファイルだけ `@`
### 協調パターン（段階的に増やす）
| パターン | 向く場面 | 約束 |
|----------|----------|------|
| 単発調査 | 呼び出し元洗い出し等 | Task に grep 調査だけ任せ、パス一覧のみ返却 |
| パイプライン | 調査 → 執筆・設計 doc | 受け渡しスキーマを先に固定（調査 JSON → 執筆） |
| ファンアウト | 独立アイテムの並列 | 集約ロジックを先に定義。最初は 2 体で固めてから増やす |
### マルチエージェント時のチェック
- [ ] ゴール・サブタスク・並列可否を Plan（チャット or `tasks/todo.md`）に書いた
- [ ] 各担当に役割・ツール・構造化出力を割り当てた
- [ ] 失敗時フォールバック（再調査・メインへ戻す条件）を 1 行でも書いた
- [ ] 汎用担当だらけ・出力形式未標準・並列の早まり・トークン肥大を避ける
## 3. ミスから学ぶ仕組み
- ユーザーからの**修正・指摘のたび**に `tasks/lessons.md` へパターンを追記する。
- 同じミスを防ぐルール（`.cursor/rules/` 等）を、再発防止として書く。
- ミス率が下がるまで lessons を磨き続ける。
- **セッション開始時**に、関連プロジェクトの `tasks/lessons.md` を読む。
## 4. 完了前の確認
- **テスト等で動いたことを示すまで完了報告しない**（テスト・curl・ログ・再現手順のいずれか）。
- **HTML サイト（`*.html`）を更新したとき** — `html-doc-site.mdc` に従い、**許可なく** `vercel deploy --prod --yes` → **1c. 本番 HEAD 確認**まで行ってから完了報告（2026-05-31 プロジェクト方針）。
- 該当時は main ブランチとの**動きの違い**を確認する。
- 「シニアエンジニアなら承認するか」を自問する。
- テスト実行・ログ確認・正しさの実演を行う。
## 5. 簡潔さへのこだわり（バランス）
- **複雑な変更**では一度止まり、「もっと簡単な方法はないか」を検討する。
- 場当たり修正に感じたら、「今の知識で簡潔に実装し直す」。
- **単純で明白な修正**には過剰設計しない。
- 提出前に自分の成果物を疑う。
## 6. 自律的なバグ修正
- バグ報告を受けたら、**手取り足取りせず修正**する。
- ログ・エラー・失敗テストを示し、そこから解決する。
- ユーザーに**別画面や別作業への切替を求めない**。
- 失敗 CI があれば、指示待ちせず調査・修正する（リポジトリの git 操作制限はユーザー指示に従う）。
## タスク管理
1. **まず Plan を書く** — チャット Plan モード可。チーム追跡は `tasks/todo.md` にチェック可能な項目で書く。
2. **Plan を確認してもらう** — 実装前にユーザーと方針を合わせる（要確認操作は明示的許可を待つ）。
3. **進捗を更新する** — 進めながら項目を完了にする。
4. **変更内容を伝える** — 各ステップで変更の概要を伝える。**編集したファイルはディレクトリツリーで位置を示す**（下記「ファイル編集の説明」）。
5. **結果を記録する** — `tasks/todo.md` にレビュー・結果セクションを残す。
6. **lessons に残す** — 修正後に `tasks/lessons.md` を更新する。
## 基本原則
- **Simplicity First** — 変更は可能な限り単純に。影響するコードは最小限。
- **No Laziness** — 根本原因を探る。暫定修正で済ませない。シニア開発者の基準で仕上げる。
- **Minimal Impact** — 必要な箇所だけ触る。無関係なリファクタやついで修正を入れない。
## ファイル編集の説明（必須）
ファイルを編集・追加した報告では、**変更ファイルの位置が分かるディレクトリツリー**を必ず入れる。
- ツリーは **今回触ったパスだけ** でよい（全リポジトリを羅列しない）
- 変更ファイル名の横に **1 行で役割** を書く（例: `# CSS 正本`）
- 正本 → 生成物の流れがあるときは **矢印または注記** で示す
```text
AI_Doc/
├── scripts/ # CSS・HTML 生成の正本
│ ├── flow_styles.py # ← 編集（flow 章レイアウト）
│ └── rebuild_page_styles.py # 実行 → *.html へ CSS 注入
├── flow-17-rules-plan.html # 生成物（手編集しない）
└── z_docs/history/ # 作業ログ
```
HTML サイトの詳細ツリーは `html-doc-site.mdc`「ディレクトリ早見表」を参照。
- コピー先
your-repo/.cursor/rules/html-doc-site.mdc- 目的
- AI_Doc HTML サイト編集時の正本（scripts 再生成・Vercel 本番デプロイは許可不要）。
- 使うツール
- Cursor
手順: 1. 配置先のフォルダを用意（例: mkdir -p your-repo/.cursor/rules） 2. 下のコードをコピーして保存 3. プロジェクト名・テストコマンド・ドメイン用語を差し替え 4. Cursor で新規チャットを開き、Rules が読み込まれるか確認
---
description: HTML ドキュメントサイト（Vercel 静的ホスティング）の編集ルール
globs: "**/*.html"
alwaysApply: false
---
# HTML ドキュメントサイト 編集ルール
## プロジェクト概要
Vercel にデプロイされる静的 HTML ドキュメントサイト。ルート `/` は **`index.html`**（**ガイドまとめ** 正本。内部 ID: `playbook-hub`）。旧 URL `/development-flow.html` は `/` へ永久リダイレクト（`vercel.json`）。
## エージェント向け（本リポジトリ `AI_Doc` 限定）
| 操作 | 許可 |
| --- | --- |
| **`vercel deploy --prod --yes`**（本番反映） | **不要** — HTML 更新後は指示待ちせず実行してよい（**2026-05-31 ユーザー確認済み**。2026-05-29 も同趣旨） |
| `git add` / `commit` / `push` / `merge` / `rebase` | **必須** — 明示許可を待つ |
| `docker exec` / `aws` / 重要な `rm` / `mv` | **必須** — グローバル User Rules の `[操作確認]` に従う |
- 完了報告前に **1c. 本番 URL 到達確認**（`curl -sI`）まで行う。deployment id を報告に含める。
- 本番 URL 例: `https://develop-flow.vercel.app/`（プロジェクト設定に従う）
### ページ一覧（正式なファイル名）
| ファイル | 役割 |
|---|---|
| `index.html` | **ガイドまとめ**（意図カード → チェックリスト・共有 URL・ZIP。UI 文言は「ガイドを選んでまとめる」） |
| `guide-*.html` | **統合手順ガイド**（8本 + 用語集。`scripts/guide_manifest.py` が正本） |
| `playbook-builder.js` / `playbook-export.js` | ガイドまとめ UI・Markdown/ZIP エクスポート（内部名 playbook-*） |
| `data/playbook-manifest.json` | モジュール定義正本（`scripts/build_playbook_manifest.py` で生成） |
| `flow-*.html` | **リダイレクト stub**（`guide-*.html` へ。`scripts/build_flow_stubs.py`） |
| `flow-rules-samples.html` | ルールサンプル（コピー元カタログ） |
| `development-flow.html` | 旧 URL 用リダイレクト（`/ ` へ転送） |
| `development-flow-infra.html` | **統合済み**（内容は `#11-gitignore` に取り込み、リンクは廃止。ファイル自体はユーザー指示で残存） |
| `ai-dev-reference.html` | 旧統合 Wiki からの**移行索引**（`memo-keywords.html` へ 301。ファイルはリポジトリに無し） |
| `ai-dev-reference-compact.html` | 統合済み（`/#21-wiki` へリダイレクト。ファイルはリポジトリに無し） |
| `rule-generator.html` | **廃止**（`/flow-4-phase1.html` へ 301。ファイル削除済み） |
| `adr-generator.html` | ADR 生成ツール |
| `lambda-api-guide.html` | Lambda API 設計ガイド（**サイドバーは `memo-cloud.html` 配下**。Hub ツールカード・本文内リンクから到達） |
| `memo-index.html` | **廃止**（301 → `memo-ai-tools.html`。旧ブックマーク用 stub） |
| `memo-ai-tools.html` | メモ — AIツール |
| `memo-ai-reference-rag.html` | メモ — RAG・ベクトルDB |
| `memo-ai-reference-tools.html` | メモ — Tool Use・MCP |
| `memo-ai-reference.html` | 旧 URL リダイレクト（→ RAG ページ） |
| `memo-dev-method.html` | メモ — 開発手法 |
| `memo-stack.html` | メモ — 開発スタック（旧 flow-12-stack） |
| `memo-cloud.html` | メモ — クラウド |
| `memo-keywords.html` | メモ — キーワード |
| `ai-news.html` | AI ニュースダッシュボード（公式サイト・changelog 等への導線） |
### エージェント運用（Cursor ルール・tasks）
| パス | 役割 |
|---|---|
| `.cursor/rules/agent-workflow-orchestration.mdc` | Plan・サブエージェント・検証・タスク記録（`alwaysApply: true`） |
| `tasks/todo.md` | 計画・進捗テンプレ |
| `tasks/lessons.md` | 指摘・修正パターンの蓄積 |
| `index.html#18-orchestration` | エージェント運用（Web）→ `guide-ops.html#18-orchestration` |
| `index.html#memo-hub` | メモ hub（index 内アンカー → `memo-ai-tools.html`） |
## ディレクトリ早見表
ファイル編集の説明では、触ったパスをこのツリーから抜粋して示す（全体コピー不要）。
```text
AI_Doc/ # リポジトリルート（Vercel 配信）
├── index.html # ガイドまとめ（#playbook-hub）
├── guide-*.html # 統合手順ガイド
├── playbook-builder.js # ガイドまとめ UI
├── playbook-export.js # エクスポート・共有 URL
├── data/playbook-manifest.json # モジュール定義（生成物）
├── flow-*.html # 旧章リダイレクト stub
├── memo-*.html # メモページ（生成物）
├── ai-news.html # AI ニュース（生成物）
├── adr-generator.html # ADR ツール（個別 HTML）
├── lambda-api-guide.html
├── vercel.json # リダイレクト・配信設定
├── .vercelignore # 配信除外（scripts/ z_docs/ 等）
│
├── scripts/ # ★ 正本（編集はここ → 再生成）
│ ├── playbook_catalog.py # Playbook Intent/Module SSOT
│ ├── build_playbook_manifest.py
│ ├── build_playbook_hub.py
│ ├── guide_manifest.py # サイドバー IA・リダイレクト map
│ ├── consolidate_guides.py # flow → guide 統合
│ ├── build_flow_stubs.py
│ ├── build_vercel_redirects.py
│ ├── flow_chapters.py # 旧章メタ（stub 生成用）
│ ├── site_shell.py # シェル CSS（sidebar / main-area）
│ ├── cursor_blog_theme.py # Cursor blog 風トークン（背景・プロース）
│ ├── github_primer_css.py # プロース（theme へ委譲）
│ ├── flow_styles.py # flow 章 CSS
│ ├── content_design.py # info-panel / cite-example 等
│ ├── memo_styles.py
│ ├── ai_news_styles.py
│ ├── github_primer_css.py # markdown-body トークン
│ ├── rebuild_page_styles.py # *.html の <style> 再生成
│ ├── build_sidebar_toc.py # サイドバー TOC 注入
│ ├── inject_site_shell.py # page-shell ラップ
│ └── inject_related_links.py # 関連ページリンク
│
├── .cursor/
│ ├── rules/
│ │ ├── html-doc-site.mdc # 本ルール
│ │ ├── site-style-guide.mdc # スタイルガイド（色・字・余白・IA）
│ │ ├── memo-pages-design.mdc # 開発メモ UI 指針
│ │ └── agent-workflow-orchestration.mdc
│ └── commands/ # /plan, /review 等（16 件。flow-17 参照）
├── tasks/
│ ├── todo.md
│ └── lessons.md
└── z_docs/history/ # 作業ログ（yymmdd-hhMM.md）
```
**正本 → 生成** の典型フロー:
1. `scripts/*.py` を編集
2. `python3 scripts/rebuild_page_styles.py`（必要なら `build_sidebar_toc.py` / `inject_site_shell.py`）
3. `vercel deploy --prod --yes`（HTML 更新時は許可待ち不要）
**guide-rules.html / guide-ops.html** は `scripts/fragments/` + `patch_guide_*.py` が正本。`consolidate_guides.py` は flow stub から再統合しない（SSOT 保護）。`flow-*.html` リダイレクトは `build_flow_stubs.py` のみ更新。
## スタイルガイド（タイポ・カラー・余白・情報設計）
**正本ルール**: `.cursor/rules/site-style-guide.mdc`（CSS 編集・HTML 執筆時は必ず併読）。
- トークン・見出しスケール: `scripts/cursor_blog_theme.py`
- パネル・手順: `scripts/content_design.py`
- シェル・サイドバー: `scripts/site_shell.py`
- 変更後は `rebuild_page_styles.py` → `audit_site_layout.py`
## サイドバー・ナビの現在地表示
- 正本: `scripts/site_shell.py`（`.sidebar .toc a[aria-current="page"]`）
- **現在地はグレー背景（`#ebeae5`）+ 太字** のみ。`box-shadow: inset 2px 0 0 var(--link)` など**左のアクセント線（赤括弧風）は使わない**。
## 開発メモ（memo-*）デザイン
**詳細ルール**: `.cursor/rules/memo-pages-design.mdc`（memo 編集時は必ず併読）。
- CSS 正本は **`scripts/memo_styles.py`**。HTML にスタイルを直書きしない。
- 全 memo ページに **`.memo-nav` + `.memo-page-head` + `.memo-content`**（リファレンスは `.memo-body`）を維持する。
- **`memo-index.html` ハブ UI は廃止**。サイドバーはカテゴリ直リンクのみ。旧 URL は `vercel.json` で `memo-ai-tools.html` へ 301。
- 変更後は `build_memo_index.py`（hub のみ）→ `rebuild_page_styles.py` → 必要なら `build_sidebar_toc.py` → `audit_site_layout.py`。
## 編集内容チェック
- 更新を行った場合は **NEW マーク**を該当するメニュー項目に追加する。以前ついていたものは **必ず削除**する（同時に複数章へ付けない）。
- コンテンツの並び替え、挿入を行った場合は、メニューとコンテンツの番号を振り直す。
- コンテンツの追加編集を行った場合は、メニューとコンテンツのレイアウトが崩れないように調整する
### NEW マーク運用（`index.html`）
| 場所 | マークアップ | 管理方法 |
|---|---|---|
| サイドバー TOC（h2 / h3） | リンクテキスト直後に `<span class="toc-badge-new" aria-label="新規・更新">NEW</span>`（**`<a>` の内側**） | `scripts/build_sidebar_toc.py` の `TOC_NEW_IDS` に見出し `id` を列挙し、`python3 scripts/build_sidebar_toc.py` を実行 |
| ヘッダー `page-header-tools` の外部 HTML リンク | `<span class="badge badge-new">NEW</span>`（例: `AIニュース`） | `scripts/site_shell.py` の `render_header` を更新し `inject_site_shell.py` を実行 |
手順（コンテンツ更新のたび）:
1. 前回の `TOC_NEW_IDS` を空にするか、今回触った `id` だけに差し替える。
2. 章の並べ替え・目次構造変更・大きな追記があった **h2 / h3 の `id`** を `TOC_NEW_IDS` に追加する。
3. `python3 scripts/build_sidebar_toc.py` でサイドバーを再生成する。
4. ヘッダー外部リンクを更新した場合は `page-header-tools` にも NEW を付ける。
5. デプロイ後、本番 HTML に `toc-badge-new` が含まれることを確認する。
**注意**: 本文 Wiki 内の `badge badge-new`（製品情報用）と混同しない。目次用は `toc-badge-new` のみ。
## デプロイ対象（Vercel）
- ルート `/` は **`index.html`** が配信される。**他の `*.html` も静的ファイルとしてそのまま配信される**。
- **`.vercelignore` に載せた `*.html` は本番で 404 になる**。ローカルにファイルがあっても、配信除外されていればリンク切れになる。
- ヘッダー・本文・相互リンクから参照する HTML は **必ず `.vercelignore` に含めない**。除外してよいのは `z_docs/`・`scripts/`・`.claude/` など配信不要なディレクトリのみ。
- 新規 HTML を追加したら、**リンク元ページと `.vercelignore` の両方**を更新する。
## 本番デプロイ
- HTML を編集して本番反映が必要なときは、**ユーザーの明示許可を待たず** `vercel deploy --prod --yes` を実行する（上記「エージェント向け」表。**2026-05-31 ユーザー確認済み** — 本プロジェクトではデプロイ確認は不要）。
- **git add / commit / push** は従来どおりユーザー許可が必要（本節の対象外）。
- デプロイ後は下記 **1c. 本番 URL 到達確認** を必ず行い、完了報告に deployment id と HEAD 結果を含める。
- ユーザーが「デプロイしないで」と明示したセッションのみ例外（その指示が優先）。
## 更新後チェック（必須）
HTML / CSS 正本を編集したら、**変更種別に応じた最小セット**を実行してから完了報告する。
### 変更種別 → 最小チェック
| 種別 | 例 | 必須コマンド / 確認 |
| --- | --- | --- |
| **A. CSS 正本のみ** | `cursor_blog_theme.py`, `flow_styles.py` 等 | `rebuild_page_styles.py` → `audit_site_layout.py` → `audit_ui.py` |
| **B. HTML 本文のみ（1 章）** | `flow-*.html` 本文 | 当該ファイルの内部リンク `rg` → 代表 URL 本番 HEAD（デプロイ時） |
| **C. シェル / サイドバー** | `site_shell.py`, `build_sidebar_toc.py` | A + `build_sidebar_toc.py`（inject 込み）→ 全 HTML リンク走査 |
| **D. 新規 HTML 追加** | 新 `*.html` | C + `.vercelignore` 突合 → リンク元更新 → 本番 HEAD 全 URL |
| **E. リダイレクト stub のみ** | `development-flow-infra.html` 等 | `vercel.json` に 301 あり → stub は §8 監査例外（shell 不要） |
**共通（HTML を本番反映するとき）**: 下記 1c 本番 HEAD 確認。デプロイは `html-doc-site.mdc`「本番デプロイ」に従う。
### 1. リンク切れチェック（リポジトリ内）
```bash
# 全 HTML の内部リンク（href="*.html" / href="#..."）を走査
rg -n 'href="[^"]*"' *.html
```
確認項目:
- `href="<file>.html"` の参照先ファイルが実在するか
- `href="<file>.html#<id>"` のアンカーが参照先 HTML 内に `id="<id>"` として存在するか、または参照先が SPA なら `page-<id>` + `show()` の hash 名と一致するか
- `href="#<id>"` のページ内アンカーが同一ファイル内に `id="<id>"` または `id="page-<id>"`（hash routing）として存在するか
- `ai-dev-reference-compact.html#<hash>` は `show()` が `page-<hash>` を表示する。外部からの直リンク用に `id="<hash>"` も併設すること
- **compact / reference のナビ・カードは `href="#"` 禁止**。`href="#<hash>"` と `onclick="show('...')"` を併用する（JS 無効時・右クリック「リンクをコピー」・新規タブでも URL が有効になる）
### 1b. 配信対象チェック（`.vercelignore`）
```bash
# 他ページから参照されている HTML が ignore されていないか
rg -o 'href="[a-zA-Z0-9_.-]+\.html' *.html | sort -u
cat .vercelignore
```
- 上記で列挙された各 `*.html` が `.vercelignore` に**一行も無い**こと
- 除外する意図がある場合は、**リンク元をすべて削除または差し替え**てから完了報告しない
### 1c. 本番 URL 到達確認（デプロイ後・必須）
デプロイ後、**リンクとして使っている全 HTML** に対して HTTP 200 を確認する（404 はリンク切れと同義）。
```bash
BASE="https://develop-flow.vercel.app"
for f in development-flow.html development-flow-infra.html \
ai-dev-reference-compact.html ai-dev-reference.html \
adr-generator.html ai-news.html; do
code=$(curl -sI "$BASE/$f" | awk '/^HTTP/{print $2; exit}')
echo "$f -> $code"
done
# 代表アンカー（compact PRD）
curl -sI "$BASE/ai-dev-reference-compact.html#prd" | awk '/^HTTP/{print "compact#prd page:", $2; exit}'
```
- いずれかが `404` なら **デプロイ設定（`.vercelignore`）を疑う**。id の有無を直す前に配信されているか切り分ける。
- 本番確認なしで「リンク修正済み」と報告しない。
### 2. ヘッダー・ナビゲーション整合性
各ページのヘッダー/ナビ領域のリンクが**他のページと矛盾しない**ことを確認する。
### 3. ヘッダー固定表示
`development-flow.html` / `development-flow-infra.html` の `.page-header` は **`position: sticky; top: 0`** で固定表示する。サイドバーは `top: var(--page-header-h)` でヘッダー直下に揃える。アンカージャンプ用に `html { scroll-padding-top: var(--page-header-h); }` を維持する。
### 4. 体裁レビュー
- 見出しの階層が正しいか（h1 → h2 → h3 の順序）
- テーブルの列数が揃っているか
- 開きタグ・閉じタグの対応が取れているか
- インデントが周囲のコードと統一されているか
- ラベルは **18 文字以内**（`build_sidebar_toc.py` `MAX_TOP`）。超える場合は `flow_chapters.nav_label` を短くするか **`H2_SHORT`**（`eid` → 短縮ラベル）に登録。truncate（`…`）は最終手段（`site-style-guide.mdc` §4.3）
## 監査例外・リダイレクト stub
正本: `scripts/audit_constants.py` + `site-style-guide.mdc` §8。
| ファイル | 扱い |
| --- | --- |
| `development-flow-infra.html` | 301 → `flow-11-repo.html#11-gitignore`（統合済み本文） |
| `flow-12-stack.html` | 301 → `memo-stack.html` |
| `memo-index.html` | 301 → `memo-ai-tools.html` |
| `memo-ai-reference.html` | 301 → `memo-ai-reference-rag.html` |
| `adr-generator.html`, `ai-dev-reference.html`, `ai-news.html` | 専用 UI（標準 layout 監査対象外） |
## 編集時の禁止事項
- **章番号をナビ/ヘッダーのリンクテキストに露出させない**（例: ✕「第11章」「17. ルール×Plan」→ ○「ルール×Plan」「リポジトリ構成」）。**サイドバー最上位**は数値プレフィックスを付けない。**本文 `h2` の表示番号**は読み順に合わせる（`2` の次は `3` ルール×Plan、`4` エージェント運用、`5` 全体フロー…）。**`id` は互換のため変更しない**（`#17-tdd-plan` 等）。`toc-sub` は `13.1` のように親章の新番号に合わせる
- **メニュー名・リンク名は 18 文字以内**（全角・半角とも 1 文字として数える）
- **フェーズ表記**: ナビ/リンクでは `フェーズN` ではなく **`PhaseN`**（例: `5. Phase1 Plan`）
- **本フローの中心**: AI **ルール・ガイドライン・Skills・docs** を優先。TDD はチーム採用時の任意検証手段として Phase3〜4 に記載
- **補助巻表記**: 旧ルール。現在は `development-flow-infra.html` を本体に統合済み。新しい「補助巻」を作る場合はこの表記方針（`〜メモ`）を踏襲する
- **ページ間リンクの href を変更するときは、リンク元とリンク先の両方を確認する**。片方だけ変えない
- **id 属性を変更・削除するときは、その id を参照している全ページを検索してから行う**
- **id の永久固定（互換）**: 外部ブックマーク用に `id` は原則変更しない（例: `#17-tdd-plan`）。章番号の表示だけ変える。**リネームが必要なとき**は (1) 旧 id を残したまま新 id を追加、または (2) `vercel.json` / stub HTML で旧 URL を 301、(3) 本文に「旧アンカー `#foo` → `#bar`」を 1 行記載
- **サイドバー TOC は 2 階層まで**（`h2` 最上位 + `h3` を `ul.toc-sub`）。例外: `3. 全体フロー` 配下 Phase0〜6 の 1 段サブ（`toc-sub`）
## ヘッダーリンクのリンク切れ対応
ヘッダー（`page-header-tools` / `topbar`）に配置されたリンクにリンク切れがある場合は、**リンク元を削除するのではなく、リンク先ページ側を修正する**（アンカー `id` の追加、ファイル名の修正など）。ヘッダーリンクはサイト全体のナビゲーション導線であり、リンク元を消すと導線が壊れる
## 過去の指摘事項（再発防止）
> ユーザーから指摘された問題をここに追記し、同じミスを繰り返さない。
| 日付 | 指摘内容 | 対処 |
|---|---|---|
| 2026-05-17 | ヘッダーに「第11章」が直接出ていて不自然 | ナビリンクから章番号を除去。章番号はナビに出さない |
| 2026-05-17 | リンク切れ 3 件（`#値オブジェクト-value-object`, `#protocol--interface`, `#adr-architecture-decision-records`） | href を実際の id に修正。更新後は必ずリンク切れチェック |
| 2026-05-18 | ヘッダーに「インフラ詳細」リンクが不要 | ヘッダーから削除、サイドバーのみに残す |
| 2026-05-18 | サイドバー TOC のサブ階層が深すぎる | 原則トップレベルのみ。**例外**: `3. 全体フロー` 配下に Phase0〜6 の 1 段サブメニュー（`toc-sub`） |
| 2026-05-18 | `compact.html#prd` に `id="prd"` が無い | リンク先に `id="prd"` を追加。ヘッダーリンク切れはリンク先側を修正する |
| 2026-05-18 | `<a>` タグのネスト（HTML違反） | toclink 内の別 `<a>` を外側に分離 |
| 2026-05-18 | `ClaudeCode`（スペースなし）表記の混在 | `Claude Code` に統一（12箇所） |
| 2026-05-18 | 本番で `ai-dev-reference-compact.html` が 404（ヘッダー「Wiki」「PRDフロー」が全滅） | **原因**: `.vercelignore` で Wiki 2 ファイルを配信除外していた。ローカル id チェックだけでは検出不可。**対処**: ignore から Wiki HTML を削除。デプロイ後 `curl -sI` で全リンク先 HTML を 200 確認。ルールに 1b・1c を追加 |
| 2026-05-18 | `development-flow-infra.html` 11.6 の本文が古い（z_docs ルール更新を反映していない） | `documentation-z-docs.mdc` 統合後の前提（`z_docs/history/` 必須・`docs/` 新規追加はユーザー明示時のみ）に書き換え |
| 2026-05-18 | infra ページが分離されたままだと参照が分散する | `development-flow.html` の 11 章に infra 本文 11.1〜11.9 を統合。infra への外部リンク 21 件を内部アンカーに置換。infra ページ自体はユーザー指示で残存（リンク経路なし） |
| 2026-05-18 | デプロイのたびに許可確認が不要と明示された | `vercel deploy --prod` は許可待ちせず実行可。git 操作のみ従来どおり許可必須。ルールに「本番デプロイ」節を追加 |
| 2026-05-18 | ch2 直後に 17・18 を置くとサイドバーが `2→17→18→3` と番号が飛ぶ | 配置は読み順のまま、**リンクテキストから章番号を除去**（`ルール×Plan` / `エージェント運用`）。本文 h2 の章番号は維持 |
| 2026-05-18 | 目次更新後も NEW マークが付かない | ルールに手順が無く `build_sidebar_toc.py` も未対応。**`TOC_NEW_IDS` + 再生成 + ヘッダー手更新**を必須化（上記「NEW マーク運用」） |
## 自己レビュー（2026-05-18・compact 404）
| 見落とし | なぜ起きたか |
|---|---|
| 本番 404 | 静的チェックは「ファイルがディスクにあるか」のみ。`.vercelignore` と本番 HEAD を見ていなかった |
| 「アンカー不足」と誤診しうる | `compact.html#prd` は `page-prd` + JS で動くため、id だけのチェッカーが false positive になり、真因（未デプロイ）が隠れた |
| ヘッダー導線の破壊 | `development-flow.html` は配信されているが、リンク先 Wiki だけ ignore されており、**リンク元は正常・リンク先だけ 404** というパターン |
**再発防止**: 完了報告前に **(1) `.vercelignore` ↔ 全 `href="*.html"` の突合** → **(2) `vercel deploy` 後の本番 HEAD** の順で必ず実行する。