毎回守る Rules と、今回だけの Plan を分ける。

やること

1. 比較表 で役割を確認
2. Skills 実践ガイド で配置と description を確認
3. サンプル をコピーして3行以上書き換え

完了: Rules と Plan の違いを1文で説明できる

毎回守る Rules と、今回だけの Plan を分ける。

やること

1. 比較表 で役割を確認
2. 自分のツール章（Cursor / Claude / Codex）を1通り
3. サンプル をコピーして3行以上書き換え

完了: Rules と Plan の違いを1文で説明できる

Rules / Skills / Plan — いつ何を使う

種類	役割	いつ使う
Rules	毎回守る禁止事項・パス・検証手順	プロジェクト全体。常時またはファイル種別ごと
Skills	反復手順（lint 一括・デプロ手順など）	同じ手順を何度も頼むとき
Plan	今回のタスク分解・終わりの条件（Done when）・リスク	実装前。中規模以上は必須

レイヤ	役割	全ツール共通の正本
Plan	今回のスコープ・終わりの条件（Done when）	tasks/todo.md（.cursor/plans/ は Cursor の下書きのみ）
仕様	要件・設計のチーム共有	docs/<feature>/・docs/adr/
検証	ルール・仕様との整合	lint / テスト / CI
振り返り	指摘パターン	tasks/lessons.md → 再発時に各ツールの Rules へ

全体像: 0章 3段フロー · ツール選定: AIツール — 選定 · 実装参考: RAG・ベクトルDB · Tool Use・MCP。

3ツール早見（Cursor / Claude Code / Codex）

メインツール別 — 設定の置き場

• Cursor — IDE で diff を見ながら日常実装・Plan（2章: 複雑な機能・デバッグ・大規模リファクタ）
• Claude Code — ターミナルで長時間自律・CI 調査（2章: 長時間自律タスク）
• Codex — Issue / クラウド PR・ルーチン並列（2章: ルーチン修正の並列）。ローカル CLI も可

ツール	Rules	手順	Plan 正本	手順集
Cursor	.cursor/rules/*.mdc	.cursor/commands/ · Skills	tasks/todo.md + .cursor/plans/	初期設定 · 作業手順
Claude Code	CLAUDE.md	.claude/skills/ · Hooks	tasks/todo.md	初期設定 · 作業手順
Codex	AGENTS.md（階層）	.agents/skills/ · MCP	tasks/todo.md	初期設定 · 作業手順

公式（一次情報リンク）

ツール	一次情報
Cursor	エージェント BP · Rules · Skills · Commands
Claude Code	Best practices · Extend · Hooks
Codex	AGENTS.md
標準	Agent Skills — 詳細は BP 参照表（Cursor 章）

状況別 — 何をするか（3ツール共通）

Plan — tasks/todo.md または Plan モードに Done when まで書く。依頼 — 対象ファイルと検証コマンドを渡す。完了 — テスト結果等の証拠を添え、仕様は docs/ に残す（チャットだけにしない）。

状況	操作	Cursor	Claude Code	Codex
3ステップ以上の作業を始める前	Plan をファイル化	Shift+Tab Plan → /plan	Plan モード → tasks/todo.md	Issue + tasks/todo.md
会話が長くなった・別の機能に移るとき	コンテキストを切る	新規 + @Past Chats（前の会話を参照）	新規 + /resume（必要時）	新規スレッド + todo
変更内容をレビューするとき	ブランチ文脈	@Branch	git diff を渡す	PR / ブランチ指定
作業を終えるとき	検証を示す	/verify	テストコマンド + /goal	承認前に diff 確認
同じミスがまた起きたとき	ルール 1 条追加	.cursor/rules/	CLAUDE.md 1 行	AGENTS.md 1 行

委譲・並列: マルチエージェント · プロンプト例: プロンプト設計

共通: Plan・docs・AGENTS.md

手順: Plan 正本を置く

1. リポ直下に tasks/ を作成（無ければ）
2. tasks/todo.md をコピー（本リポの todo テンプレ または下記）
3. 各タスクに 終わりの条件（Done when）（検証コマンド or 手動確認）を 1 行ずつ書く
4. 仕様は docs/<feature>/01_requirements.md へ（Rules に複製しない）

## タスク
- [ ] 要件確認 — Done when: docs/invoice-export/01_requirements.md レビュー済
- [ ] 実装 — Done when: `docker compose exec app bundle exec rspec spec/services/invoice_export_spec.rb`
- [ ] PR — Done when: /pr-check 9 カテゴリすべて [x]

## Plan メモ
- リスク: 在庫不足時のエラー型は ErrInsufficientStock に統一

docs/
├── adr/016-pdf-async.md
└── invoice-export/
    ├── 01_requirements.md
    └── 02_design.md

Cursor

手順: Cursor 初期設定（リポ）

1. AGENTS.md をルートに置く → サンプル
2. .cursor/rules/00-project.mdc を alwaysApply: true で作成 → Rules サンプル
3. （任意）.cursor/commands/ に plan.md 等 — 本リポは AI_Doc/.cursor/commands/ をコピー可
4. （任意）.cursor/skills/<name>/SKILL.md — 週次の多段手順のみ

.cursor/
├── rules/
│   ├── 00-project.mdc      # alwaysApply: true
│   └── 10-domain-rules.mdc
├── commands/
│   └── plan.md             # → Composer で /plan
├── skills/
│   └── pr-review/SKILL.md
└── plans/                  # Plan モード「Save to workspace」

手順: 典型ワークフロー（Cursor）

出典: agent-best-practices

A. 新機能 — Plan → 実装

1. Composer で Shift+Tab → Plan
2. プロンプト例を貼る（下記）→ 計画承認 → Build
3. 「Save to workspace」→ .cursor/plans/YYYYMMDD-feature.md
4. 確定内容を tasks/todo.md に転記
5. AI（Agent）モードで実装 → /verify で証拠を残す

/plan 請求PDFエクスポート。参照 @docs/prd/invoice-export.md @tasks/todo.md
Done when: rspec spec/services/invoice_export_spec.rb green

B. 別チャットで続き — Past Chats

1. 新規 Composer
2. @Past Chats（前の会話を参照）→ 関連セッション 1 件
3. @tasks/todo.md + ゴール 1〜3 行

@Past Chats（invoice PDF セッション）
続き: InvoicePdfService のエラーハンドリング。Done when: rspec green
@tasks/todo.md

詳細: @Past Chats · /handoff

C. 検証ループ — Hooks（任意）

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "make test" }]
  }
}

配置: .cursor/hooks.json（プロジェクトルート）。失敗時はエージェントが再試行しやすくなる。

D. PR 前

/review @Branch の差分。ブロッカーがあれば push しない
/pr-check feature/foo → main。flow-14 の 9 カテゴリを [x]/[ ]

公式ワークフロー早見（2026-02）

一次情報のセクションと本サイトの対応。

公式テーマ	要点	本サイト
ハーネス	Instructions + Tools + Model	Rules / Skills / Plan
Plan first	Shift+Tab · Save to .cursor/plans/	ズレたら計画からやり直す
コンテキスト	総 @ 不要 · @Branch · @Past Chats	Past Chats 手順
TDD	テスト先行 → 実装 → 反復	エージェント TDD 5 ステップ
レビュー	diff 監視 · Agent Review · Bugbot	提出前 AI レビュー
並列	worktree · 複数モデル比較	worktree / 多模型
クラウド	Background / cursor.com/agents	Cloud · ビジュアル
画像	スクショ · Figma MCP · Browser サイドバー	ビジュアルデバッグ

公式 BP → 本リポの対応（一覧）

公式	ここでやること
Plan first	A. Plan → Build
コンテキスト	Past Chats · @Branch
Commands	16 選
レビュー	/review · Bugbot（PR）
並列	worktree / Task

手順: Rule / Skill / Command の追加

追加したいもの	置き場	手順
毎回守る下限	.cursor/rules/*.mdc	frontmatter に alwaysApply: true → 本文は 20 行以内 → サンプル
週次の多段手順	.cursor/skills/name/SKILL.md	description を命令形で → サンプル
毎日の 1 ショット	.cursor/commands/foo.md	ファイル名 = /foo · $ARGUMENTS 対応

---
description: ドメイン不変条件
alwaysApply: true
---

# ドメイン
- 在庫は 0 以上（物理削除禁止）

手順: @Past Chats（前の会話を参照）

状況	操作
同じバグの続き	同一会話を継続
別 PR / 別機能	新規 + Past Chats 1 件 + todo
差分レビュー	@Branch を追加

配置ツリー（Cursor・併用）

project/
├── AGENTS.md
├── tasks/todo.md
├── docs/invoice-export/
├── .cursor/
│   ├── rules/00-project.mdc
│   ├── commands/plan.md
│   ├── skills/pr-review/SKILL.md
│   └── plans/20260530-feature.md
├── .claude/skills/          # Claude 併用時
└── .agents/skills/          # Codex 併用時

Claude Code

手順: Claude Code 初期設定（リポ）

1. リポで claude を起動
2. /init → CLAUDE.md の下書きを生成 → 20〜40 行に削る
3. tasks/todo.md を置く（共通 Plan）
4. （任意）.claude/skills/<name>/SKILL.md
5. （任意）Hooks — .claude/settings.json で Stop 時にテスト

project/
├── CLAUDE.md              # ★ 短い Rules
├── tasks/todo.md
├── docs/
└── .claude/
    ├── skills/phase4-tdd/SKILL.md
    └── settings.json      # hooks（任意）

# CLAUDE.md（例・短く）

## 毎回
- 着手前: tasks/todo.md の終わりの条件（Done when）を読む
- 仕様: docs/ のみ（ここに API 詳細を書かない）

## 検証
- テスト: docker compose exec app bundle exec rspec <path>

## 禁止
- git push / commit はユーザー許可後のみ

手順: 典型ワークフロー（Claude Code）

出典: best-practices

A. Explore → Plan → Implement

1. Plan モード（または最初のプロンプトで「まず調査のみ」）
2. 調査結果を tasks/todo.md にチェックリスト化
3. 実装モードへ切替 → ファイルパスと検証コマンドを明示
4. テスト green → commit（許可後）

Phase3 設計のみ。コード変更なし。
docs/invoice-export/01_requirements.md を読み、不明点を質問リストに。

（Plan 確定後）
02_design.md に沿って InvoiceExportService を実装。
Done when: bundle exec rspec spec/services/invoice_export_spec.rb

B. セッション再開

/resume
# または
/resume <session-id>

長い transcript はコスト増 — 新規 + tasks/todo.md を優先（引き継ぎ）。

C. Skill を明示的に呼ぶ

/phase4-domain-tdd
spec/domain/invoice_export_spec.rb の在庫不足ケース 1 サイクルだけ

公式 BP → 本リポの対応（一覧）

公式	手順
検証手段を渡す	プロンプトに rspec / make test · 完了前検証
CLAUDE.md は短く	初期設定 · Phase1 テンプレ
Subagents	調査の任せ方
lessons	tasks/lessons.md → 再発時 CLAUDE.md 1 行

手順: セッション引き継ぎ

1. 新規セッションを開く
2. tasks/todo.md を最初に渡す（パスまたは貼り付け）
3. 前回の続きが必要なら /resume（1 セッションに絞る）
4. チーム共有は docs/ を更新（チャット全文はコピペしない）

配置ツリー（Claude Code）

project/
├── CLAUDE.md
├── tasks/{todo,lessons}.md
├── docs/
├── .claude/skills/phase3-design-doc/SKILL.md
└── packages/api/CLAUDE.md    # パッケージ固有（任意）

Codex

手順: Codex 初期設定（リポ）

構築順（公式）: AGENTS.md → Skills → MCP → Subagents

1. ルートに AGENTS.md（短い索引）→ サンプル
2. tasks/todo.md
3. .agents/skills/<name>/SKILL.md（長い手順）
4. （任意）.codex/config.toml — プロジェクト上書き
5. （任意）MCP — Skill の SKILL.md に利用ツールを宣言

project/
├── AGENTS.md
├── tasks/todo.md
├── .agents/skills/deploy/SKILL.md
├── .codex/config.toml          # 任意
└── src/feature-x/AGENTS.md     # この cwd 用の追加規約

# .codex/config.toml（例）
[project]
approval_policy = "suggest"   # 慣れたら "auto"（Git 追跡ブランチ上のみ）

手順: 典型ワークフロー（Codex）

出典: customization

A. Issue → 実装 → PR

1. GitHub Issue の Acceptance Criteria を tasks/todo.md に転記
2. Codex に Issue URL + @AGENTS.md + @tasks/todo.md
3. 差分を suggest モードで 1 ファイルずつ承認
4. CI green → PR 作成（push は許可後）

Issue #42 を実装。AGENTS.md と tasks/todo.md に従う。
Done when: CI の rspec job green。docs/invoice-export/02_design.md と整合。

B. サブフォルダ作業

cwd: src/feature-x/
→ AGENTS.md（ルート）を読んだあと src/feature-x/AGENTS.md を追加適用

公式 BP → 本リポの対応（一覧）

公式	手順
AGENTS 階層	初期設定 · ツリー
Skills 段階ロード	SKILL.md サンプル
承認モード	approval_policy = suggest から開始
CI 失敗	/fix-ci（Cursor 併用時）· ログ URL を渡す

手順: セッション引き継ぎ

1. 新規スレッド
2. tasks/todo.md + 変更対象パスを列挙
3. モジュール固有ルールはそのフォルダの AGENTS.md を参照させる

配置ツリー（Codex）

project/
├── AGENTS.md
├── tasks/todo.md
├── .agents/skills/deploy/SKILL.md
├── .codex/config.toml
└── src/feature-x/AGENTS.md

Skills 実践ガイド（2026）

Skill = 必要なときだけ読む手順。サンプル: pr-review · 置き場。

いつ Skill 化するか

シグナル	昇格先	例
毎日 1 ショットで済む	Command（.cursor/commands/）	/review · /verify
週 2 回以上・多段チェックリスト	Skill	PR 前 lint+test+docs 整合 · デプロ手順
毎セッション必須の禁止・下限	Rule（alwaysApply / globs）	git 安全 · ドメイン不変条件
同じミスが 2 回以上	lessons → Rule 1 条	tasks/lessons.md から .mdc へ
広い調査・grep だけ	Task / Subagent（Skill にしない）	別 AI への任せ方

Skills と Subagents（Task）の使い分け

種類	役割	向く場面	向かない場面
Skill	再利用ワークフロー（チェックリスト・scripts）	PR レビュー · ADR 執筆 · デプロ	「どこにある？」だけの grep
Subagent / Task	別コンテキストで調査・実行	パス一覧 · 複数 dir 探索 · shell 専門	直前の実装の続きデバッグ
Rule	毎回の下限	禁止 · 参照順 · globs 規約	10 ステップの手順全文

初めて Skill を 1 つ作る（手順）

1. 対象を決める — 直近 2 週間で 2 回以上頼んだ多段手順（例: PR 前確認）
2. ディレクトリ — チーム共有なら .agents/skills/<name>/、Cursor のみなら .cursor/skills/<name>/（配置表）
3. SKILL.md — frontmatter の name（フォルダ名一致）と description（命令形・ユースケース）を書く（フロントマター · テンプレ）
4. 本文 — チェックリスト + 出力形式。500 行超えたら references/ へ分割
5. 任意 scripts/ — 非対話・--help 必須（Agent Skills 仕様）
6. AGENTS.md に 1 行 — 「PR 前: .agents/skills/pr-review/SKILL.md」
7. 発火確認 — Agent に「PR 前のセルフレビューして」と依頼し Skill が読まれるか確認
8. 既存資産から — Cursor なら /create-skill または /migrate-to-skills（移行）

description の書き方と評価

description は Skill のトリガー。曖昧な 1 行は発火しない。

• 命令形 — 「〜の場合に使用してください」（agentskills.io 推奨）
• ユースケース列挙 — 「PR 前」「デプロ」「ADR ドラフト」など具体語
• 暗黙の依頼もカバー — 「レビュー準備」「提出前チェック」等の言い換え

評価ループ（目安）:

1. should-trigger 10 件 · should-not-trigger 10 件のプロンプトを用意
2. 各 3 回 Agent に依頼し、Skill が読まれたか確認
3. 過少トリガー → description を広げる / 過剰トリガー → 絞る

よくある失敗

• 手順を Rule（alwaysApply: true）に入れてトークン浪費
• description が「この Skill は〜します」だけ（トリガーにならない）
• 仕様全文を Skill に複製（正本は docs/）
• 調査だけの Task を Skill 化（grep 手順は Subagent 向き）
• name とフォルダ名不一致（検出・読み込み失敗）

サンプル: AGENTS.md（Cursor / Codex 共有入口）

長くしない。Cursor の詳細は .cursor/rules/、Codex の手順は .agents/skills/ へ。Claude は CLAUDE.md を別途。

# AI Agent Instructions

## 必読（毎セッション）
- .cursor/rules/00-project.mdc      # プロジェクト共通
- .cursor/rules/10-domain-rules.mdc # 業務制約。違反厳禁
- .cursor/rules/60-ai-workflow.mdc  # docs / Obsidian history / git

## ビルド・検証
- 開発: make up
- テスト: make test

## 出力先
- チーム公式: docs/（要件・設計・ADR）
- 作業ログ: Obsidian 03_Operations/history/YYYY-MM/
- Plan: tasks/todo.md

## 手順（Skills）
- PR 前: .cursor/skills/pr-review/SKILL.md
- 設計 doc: .claude/skills/phase3-design-doc/SKILL.md

サンプル: Rules（.cursor/rules/*.mdc）

00-project.mdc — 毎セッション（alwaysApply: true）:

---
description: プロジェクト共通。毎セッション適用。
alwaysApply: true
---

# プロジェクト共通

## 参照順
1. tasks/todo.md（今回の Plan）
2. docs/<feature>/（仕様）
3. 既存 src/ の同種実装

## 禁止
- 仕様を Rules に複製しない（docs を読む）
- 推測で API / DB スキーマを断定しない

10-domain-rules.mdc — 業務制約（プロジェクト固有の事実のみ）:

---
description: ドメイン不変条件。全実装で参照。
alwaysApply: true
---

# ドメインルール

## 不変条件
- 注文金額は 0 より大きい
- 在庫数量は 0 以上（物理削除禁止）

## 副作用
- 注文確定時は通知ジョブを必ず enqueue（再実行可）

## 用語
- 顧客 → customer / 注文 → order

20-coding-style.mdc — 言語別（globs）:

---
description: TypeScript / React のコーディング下限
globs: apps/web/**/*.{ts,tsx}
alwaysApply: false
---

# TS/React

- Server Component をデフォルト。Client は必要なときのみ
- 新規 API は src/lib/api/ の既存ラッパに合わせる

git-safety.mdc — 危険操作ガード（クイックスタートでも参照）:

---
description: git push 等はユーザー許可後のみ
alwaysApply: true
---

# Git 安全運用

## 許可なしに実行しない
- git add / commit / push / merge / rebase
- docker exec（本番相当）

## 完了報告前
- 関連テストまたは再現手順で動いたことを示す

Skills の置き場（Cursor 2.4+ / Agent Skills 標準）

Cursor は起動時に次から SKILL.md を再帰検出する（公式 Skills · agentskills.io）。チーム共有はリポジトリの .agents/skills/ か .cursor/skills/ のどちらかに統一すると、Cursor / Codex / Copilot 系と資産を共有しやすい（Qiita 比較）。

スコープ	パス
プロジェクト	.agents/skills/ · .cursor/skills/（互換: .claude/skills/ · .codex/skills/）
グローバル	~/.agents/skills/ · ~/.cursor/skills/
モノレポ	apps/web/.cursor/skills/ 等 — そのディレクトリ配下のファイルを触るときだけ表示（入れ子スコープ）

Background / Cloud Agent — いつ使うか

状況	ローカル Agent	Background / Cloud
IDE で diff を見ながら実装	◎	△（結果を後から取り込む）
調査・テスト・lint の長いループ	△（会話が肥大化）	◎
秘密情報・社内 VPN 必須	◎	ポリシー確認必須
並列に 3 件以上の独立タスク	worktree + 複数ウィンドウ	◎（キュー管理）

正本手順: エージェント運用 — マルチエージェント · 公式: Cloud Agent · エージェント BP。

Skills description — should-trigger テスト例

description を書いたら、次の 10 クエリで「発火すべき / すべきでない」を 3 回ずつ試す（フロントマター）。

種別	例（pr-review Skill）
should-trigger	「PR 出す前にセルフチェックして」「レビュー観点を整理して」「lint と test を通してから merge」
should-not-trigger	「この関数の名前を変えて」「README の誤字修正」「DB マイグレーションの SQL だけ書いて」

過少トリガー → description を具体化。過剰トリガー → paths や disable-model-invocation を検討。

Plugins / Marketplace（2026）

Cursor は Rules · Skills · Commands · MCP · Subagents をプラグインとして Marketplace からインストールできる（Cursor Docs · 2026 製品更新）。Claude Code の Plugins（Hooks→Skills→Plugins→MCP の積み上げ）と同趣旨。

ツール	拡張の入口	チーム共有
Cursor	Settings → Plugins / Marketplace · .cursor/ に展開	リポにコミット + ドキュメント化
Claude Code	Plugins ディレクトリ · engineering スキル	CLAUDE.md に 1 行リンク
Codex	Skills plugin · MCP	AGENTS.md + .agents/skills/

導入前: 権限（MCP・shell）・秘密情報・alwaysApply との重複を確認。本リポは Starter セット を正本とし、Marketplace 追加は ADR または tasks/lessons.md に記録。

SKILL.md フロントマター（公式 + コミュニティ）

フィールド	必須	用途
name	はい	小文字・ハイフン。親フォルダ名と一致（例: pr-review）
description	はい	トリガー用。命令形・具体キーワード（「PR前」「セキュリティ監査」）。曖昧な1行は発火しない（Zenn）
paths	任意	**/*.tsx 等。該当ファイルを触るときだけ Skill を提示（Rules の globs に近いが Skill 専用）
disable-model-invocation: true	任意	従来のスラッシュコマンド相当。自動適用しない（/skill-name のときだけ）

本文は 500 行目安。詳細は references/・実行は scripts/・テンプレは assets/ へ（Progressive Disclosure — Zenn 解説）。

既存 Rules / Commands の移行（公式）

Cursor 2.4+ 組み込み: Agent チャットで /migrate-to-skills または /create-skill（公式）。

• 移行対象: alwaysApply: false かつ globs なしの動的 Rule、ワークスペース / ユーザーの slash commands
• 移行しない: alwaysApply: true、globs 付き Rule（トリガー条件が別物）、User Rules（ファイルシステム外）
• Commands を残す方針も可 — 本リポは 16 選 を維持し、多段手順だけ Skills 化

Rules / Skills / Commands の判断（公式 + 実務）

種類	いつ	確実性
Rules（.mdc）	毎回の禁止・下限・globs 付き規約	常時（トークンコスト大）
Skills	多段ワークフロー・ドメイン手順	関連時のみ自動（description 次第）
Commands	毎日の 1 ショット定型	明示 / のみ
Hooks（Claude）	lint / 危険コマンド阻止など100% 必須	決定的（Claude Code）

Claude Code では CLAUDE.md は助言（常に従うとは限らない）。100% 守らせるなら Hooks（Anthropic BP · コミュニティ検証）。Cursor は Rules + 検証コマンド（/verify）で近い運用。

Hooks（Cursor）— 検証ループの自動化

出典: Cursor 公式 BP（2026-02）。Rules は毎会話、Hooks は決定的な停止・再開に使う。

用途	設定	本リポ
テスト green まで反復	.cursor/hooks.json の stop hook	/verify · 完了前検証
lint 必須	post-edit hook で lint 実行	Rules にコマンド列挙 + hook
Partner 連携	Secrets / Observability MCP と組み合わせ	MCP 参考

Skill 内 hook と混同しない — hook はエージェント停止時に必ず走る。長時間ループは loop_count 上限を設ける（公式 grind 例参照）。

サンプル: Skills（SKILL.md + 任意 scripts/）

1 Skill ＝ 1 ディレクトリ。description は命令形でユースケースを書く（トリガー用）。共有は .agents/skills/ 推奨。全文: pr-review サンプル · フロントマター。

.agents/skills/pr-review/   # または .cursor/skills/pr-review/
├── SKILL.md
├── references/              # 任意（長文はここ）
└── scripts/
    └── run_checks.sh

---
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 なら提出可と明示。

scripts/run_checks.sh（任意・非対話）:

#!/usr/bin/env bash
set -euo pipefail

usage() {
  echo "Usage: run_checks.sh [--quick]" >&2
  exit 1
}

QUICK=0
[[ "${1:-}" == "--quick" ]] && QUICK=1
[[ "${1:-}" == "--help" || "${1:-}" == "-h" ]] && usage

if [[ "$QUICK" -eq 1 ]]; then
  make lint
else
  make test
fi

ベストプラクティス参照（公式・コミュニティ）

区分	タイトル	要点
Cursor 公式	エージェント BP（2026-02）	Plan first · コンテキスト節約 · Rules/Skills/Commands · Hooks · 検証可能なゴール
Cursor 公式	Agent Skills	ディレクトリ · paths · /migrate-to-skills · 入れ子
Cursor 公式	Rules	.mdc · AGENTS.md · Remote Rules（GitHub）
Anthropic 公式	Claude Code BP	コンテキスト管理 · 検証ループ · Explore→Plan→Implement · 具体プロンプト
標準	Agent Skills 仕様	クロスツール互換 · Progressive Disclosure
Zenn	Skills 作成 Tips	SKILL.md は薄く · 詳細は scripts/references
Zenn	Skills ハンズオン	description 設計 · 粒度 · セキュリティ
Zenn	AGENTS.md と Rules	AGENTS.md + globs · Skills は別レイヤ
Qiita	5ツール Skills 比較	.agents/skills/ 共有 · Remote import
Qiita	Skills パラダイム解説	オープン標準化 · /migrate-to-skills の位置づけ
X	@leerob — エージェント実践（2025-06）	検証ループ（高速テスト・型・lint）· Cursor＝IDE/ diff · Claude Code＝ループ · Codex＝背景レビュー
X	@bcherny — 本人のセットアップ（2026-01）	並列 worktree · Plan→Build · CLAUDE.md 共有 · Hooks · 検証で品質 2–3x
X	@bcherny — チーム Tips（2026-01）	worktree 並列 · Plan に注力 · Skills 化 · サブエージェント · 音声入力
X	@bcherny — 隠れ機能（2026-03）	/loop · teleport · Chrome 拡張検証 · /batch · --add-dir
X	@commte — 大規模 CB 要約	薄いルート CLAUDE.md · サブディレクトリから開始 · Stop hook
X	@NainsiDwiv50980 — セットアップ 12 項	環境整備 · MCP · worktree · CI 連携（4章）

X（公開スレッド）ベストプラクティス要約

Cursor

出典（X）	推奨	本サイトでの置き場
@leerob（Cursor VP DX）	エージェントに自己検証ループを渡す — 高速テスト・型付き言語・lint。エージェントはコンパイル/テスト失敗を読んで自己修正する	Cursor 公式 BP · 18章 検証
同上	Cursor は IDE として diff レビュー・インライン編集に強い。1 ツール万能ではなく用途分担（Plan は Cursor、長いループは Claude Code 等）	2章 Cursor · 横断表
公式 BP（X 以外の正本）	Plan Mode（Shift+Tab）→ 計画承認 → Build。ズレたら follow-up ではなく計画を直して再実行	Plan Mode 公式 · @Past Chats

Claude Code

出典（X）	推奨	本サイトでの置き場
@bcherny セットアップ	ターミナル 5 + Web 5–10 セッション並列 · Opus + thinking · 共有 CLAUDE.md を git 管理 · PR で @.claude 学習	Claude 公式 BP · 18章 並列
同上	複雑タスクは Plan mode（Shift+Tab×2）→ 計画 OK なら auto-accept で 1-shot · PostToolUse で format · 検証手段が最重要（品質 2–3x）	Phase1 CLAUDE
@bcherny チーム Tips	git worktree で 3–5 並列が最大の生産性 · 計画に時間を使い実装は 1-shot · 修正のたび「CLAUDE.md を更新せよ」· 1 日 2 回以上の作業は Skill 化	セットアップ 12 項 · Skills 配置
@bcherny 隠れ機能	/loop で PR 監視・rebase 自動化 · /teleport で Web↔CLI · Chrome 拡張で UI 検証 · /batch で大規模 migration · claude -w worktree	サブエージェント
@commte 要約	ルート CLAUDE.md は薄く · 作業はサブディレクトリから · Hooks→Skills→Plugins→MCP · Stop hook で学びを CLAUDE.md へ	大規模 CB

Codex

出典	推奨	本サイトでの置き場
@leerob（Codex 言及）	サイドプロジェクトで背景エージェントとして利用 — アーキテクチャ批判的レビュー・「コードの理解」を説明させ比較・明らかなバグ/ red flags 探索	2章 Codex
OpenAI 公式 BP（X より正本）	AGENTS.md に実行可能コマンド・禁止事項 · /init で下書き→人手で削る · 32 KiB 上限 · 同じミス 2 回で AGENTS.md 更新	Codex 公式 BP · Phase1 テンプレ
同上	検証: codex --ask-for-approval never "Summarize the current instructions." で読み込み確認 · モノレポはネスト AGENTS.md / AGENTS.override.md	AGENTS.md サンプル

本サイトにまだ無い / 別章の新しめ手法（Skills ページ外だが公式・開発者が推すもの）:

• Cursor: Background / Cloud Agent（2章）、Automations、Settings から GitHub Remote Rules
• Claude Code: /goal による完了条件、Stop hook の検証ゲート、claude -p 非対話、Subagents（18章）
• 横断: チームで .agents/skills/ を正本にし、Cursor Rules は短い alwaysApply のみ（Qiita Rules 入門 は Rule Type の説明として参照可）

以下のサンプル・Commands は Cursor 専用（Claude は /スキル名、Codex は Skills のみ）。

おすすめ Commands 16 選（.cursor/commands/）

review.md → Composer で /review。引数は本文の $ARGUMENTS に差し込み。

.cursor/commands/plan.md   → /plan
~/.cursor/commands/       → 全プロジェクト共通（任意）
AI_Doc/.cursor/commands/  → 本リポ同梱 16 件

コピペ例: 16件の一行例 · 追加手順: Rule/Skill/Command 追加

#	コマンド	いつ使う	主な参照
1	/plan	3 ステップ以上・設計判断あり。着手前に Done when を固定	Phase 2 Plan・tasks/todo.md
2	/review	PR 提出前のセルフレビュー	PR前チェック
3	/pr-check	9 カテゴリの提出前チェックを漏れなく	チェック詳細
4	/requirements	PRD Must を要件 doc にトレース	Phase 3
5	/design	要件から設計 doc（API・境界・エラー）	設計 doc 生成
6	/tdd-cycle	RED → GREEN → REFACTOR を 1 サイクルだけ	TDD テンプレ
7	/verify	完了報告前。テスト・ログ・再現手順のいずれかを示す	完了前の検証
8	/debug	再現はできるが原因不明。仮説→計測→局所修正	Cursor Debug モード
9	/investigate	「どこにある？」系。スコープ限定の調査だけ	調査の任せ方
10	/lessons	指摘・修正後にパターンを蓄積	tasks/lessons.md・lessons
11	/adr	技術選定・トレードオフを ADR に残す	ADR
12	/handoff	新規チャットへ。Past Chats + todo の引き継ぎ	@Past Chats
13	/explain	変更報告。触ったパスのディレクトリツリー必須	agent-workflow-orchestration.mdc
14	/security	認可・入力検証・秘密情報のレビュー	セキュリティ
15	/fix-ci	CI 失敗ログから再現→修正→ green 確認	自律的バグ修正
16	/ask-spec	コードを変えず仕様・ADR の壁打ち（Ask 推奨）	要件すり合わせ

使い分けの目安: 毎日の定型 → Commands / 同じ多段手順が週次 → Skills / 毎回守る下限 → Rules（Rules と Skills）。

各コマンドの使い方・例（16件）

Composer にそのまま貼れる一行と、似たコマンドとの違い。スラッシュのあとに続けた文字が $ARGUMENTS になる。

コマンド	コピペ用（一行）	混同しやすい相手
/plan	/plan 請求PDFエクスポート Phase3。PRD: docs/prd/invoice-export.md。Done when: rspec green + staging 手動確認	/ask-spec（まだ決めない）・/design（設計 doc 執筆）
/review	/review 現在ブランチの差分をセルフレビュー。ブロッカーがあれば push 提案しない	/pr-check（9 カテゴリ網羅）・/security（セキュリティ特化）
/pr-check	/pr-check feature/invoice-export → main。flow-14 の 9 カテゴリを [ ]/[x] で	/review（ざっくりレビュー）・/verify（テスト実行）
/requirements	/requirements docs/prd/invoice-export.md → docs/invoice-export/01_requirements.md。Must を REQ-001 形式でトレース	/design（API 詳細）・/ask-spec（未確定の壁打ち）
/design	/design docs/invoice-export/。01_requirements.md を読み 02_design.md に API・ジョブ・エラー型	/requirements（要件のみ）・/plan（タスク分解）
/tdd-cycle	/tdd-cycle spec/services/invoice_export_spec.rb の「在庫不足で ErrInsufficientStock」1 サイクルだけ	/verify（全体テスト）・Agent に「全部実装して」（サイクル無視）
/verify	/verify docker compose exec app bundle exec rspec spec/services/invoice_export_spec.rb	/review（コード読み）・完了報告だけ口頭（証拠なし）
/debug	/debug POST /api/invoices/export が 500。staging で再現可。ログは CloudWatch の該当 request_id	/fix-ci（CI ログ起点）・/investigate（変更しない調査）
/investigate	/investigate <Service> の呼び出し元だけ。src/domain/ と src/app/。JSON {paths, summary} のみ	メインに「全部 grep して」（ログ肥大）・/debug（修正まで）
/lessons	/lessons レビュー指摘: push 許可なしで commit 提案された。再発防止を lessons に追記	/plan（今回のタスク）・Rules へいきなり長文追加
/adr	/adr PDF 生成を同期 vs ジョブキュー。docs/adr/016-*.md ドラフト。未決は todo リスクへ	/design（機能設計 doc）・/ask-spec（決定前の相談）
/handoff	/handoff Phase4 PDF ロジック続き。PR #482。次チャットで @Past Chats 1 件 + @tasks/todo.md	会話全文コピペ・/plan（新規 Plan 作成）
/explain	/explain 直前のコミット分。ディレクトリツリー必須。検証コマンドも添える	「変更した」（ツリーなし）・/review（品質評価）
/security	/security src/api/middleware/auth.ts と export エンドポイント。認可漏れ・IDOR・秘密情報	/review（一般品質）・/pr-check（全カテゴリ）
/fix-ci	/fix-ci spec/services/invoice_export_spec.rb:42 expected 200 got 500。ログ要点を再現して修正	/debug（手元再現）・/tdd-cycle（1 サイクルだけ）
/ask-spec	/ask-spec 請求PDFを同期生成 vs 非同期ジョブのトレードオフ。コード変更なし。ADR 案だけ	/plan（実装着手）・/design（doc 確定執筆）

場面別の詳細（モード・添付・期待する返答）。

/plan — 着手前にスコープと Done when を固定

使う: 3 ステップ以上、設計判断、影響範囲が広い。使わない: 1 ファイルの typo 修正、仕様がまだ曖昧（先に /ask-spec）。

例:

/plan ユーザー招待メール再送。tasks/todo.md を更新。
Done when: 結合テスト green、staging で 1 件再送確認、docs/invite/01_requirements.md 更新

モード: Plan 推奨（Shift+Tab）→ 承認 → Build。添付: @tasks/todo.md、@docs/prd/...

返ってほしいもの: チェックリスト付き tasks/todo.md 案、リスク列挙。

/review — PR 前のざっくりセルフレビュー

使う: コミット済み・PR 直前。使わない: 公式チェックリストの網羅（/pr-check）、セキュリティ特化（/security）。

/review @Branch の差分。alwaysApply ルール違反がないか。重大度つきで

添付: @Branch または @git（環境による）。返答: ブロッカー / 警告 / OK の箇条書き。

/pr-check — 提出前 9 カテゴリの漏れチェック

使う: マージ直前の最終確認。使わない: 実装中の途中確認（重い）。

/pr-check PR #512。docs/invoice-export/ 01〜07、ADR、glossary、CI、セキュリティまで [x]/[ ]

返答: カテゴリごとの [ ] / [x]。未確認は「未確認」と明記。

/requirements — PRD → 要件 doc

使う: Phase 3 の最初。使わない: API パスや DB カラムの確定（/design）。

/requirements docs/prd/billing-v2.md の Must だけ。
出力: docs/billing-v2/01_requirements.md（REQ-xxx で PRD Must にトレース）

禁止の確認: エージェントが API を断定していないこと。

/design — 要件 → 設計 doc

使う: 01_requirements.md が揃ったあと。使わない: PRD から要件を起こす段階（/requirements）。

/design docs/invoice-export/。
@docs/invoice-export/01_requirements.md を読み 02_design.md に REST・ジョブ・エラー型

返答: 02_design.md の diff または章立て案。未決は todo リスクへ。

/tdd-cycle — TDD 1 サイクルだけ

使う: 振る舞いを 1 つ追加するとき。使わない: 機能まるごと実装依頼。

/tdd-cycle 「二重送信で 409」を spec/requests/invoices_export_spec.rb で RED→GREEN→REFACTOR 1 回

返答: どのフェーズか、変更ファイル、テスト結果 1 行。

/verify — 完了報告前の証拠

使う: 「終わった」と言う直前。使わない: コードレビューだけで完了扱い。

/verify make test と flow-17 の HTML 変更なら curl 本番 HEAD

返答: 実行コマンド、終了コード、ログ要点または再現手順。

/debug — 再現できる不具合

使う: 手元または staging で再現できる 500 / 例外。使わない: CI のみで落ちる（/fix-ci）。

/debug ローカル docker compose up 後、GET /health は 200 だが POST /export が 500。
仮説→ログ確認→最小修正

モード: Debug 推奨。返答: 原因 1 行 + 修正 diff + 再現手順。

/investigate — 調査だけ（実装しない）

使う: 呼び出し元洗い出し、設定の所在確認。使わない: バグ修正まで任せたい（/debug）。

/investigate .cursor/rules/ で alwaysApply:true のファイル一覧だけ

返答: { "paths": [...], "summary": "..." } 程度。grep 全文禁止。

/lessons — 指摘の蓄積

使う: レビュー・ユーザー指摘のあと。使わない: 初回の雑談メモ。

/lessons Mermaid エッジに <br/> を入れてパース失敗。再発防止を lessons に 1 行

返答: tasks/lessons.md 追記案。繰り返しなら Rules 昇格提案 1 条。

/adr — 設計判断の記録

使う: 技術選定が分岐するとき。使わない: 仕様未確定の壁打ち（/ask-spec）。

/adr ストレージを S3 直 PUT vs 署名付き URL。docs/adr/ 次番号でドラフト

返答: ADR ドラフト（コンテキスト・決定・代替・影響）。

/handoff — チャット切替用の引き継ぎ文

使う: 会話が長い・別機能へ移る。使わない: 同じ機能のデバッグ続き（同一会話を維持）。

/handoff 次チャット用の冒頭 3 行を書いて。Past Chats は invoice PDF セッション 1 件想定

操作: 新規チャット → @Past Chats 1 件 → 生成文を貼る → @tasks/todo.md。

/explain — 変更報告（ツリー必須）

使う: 実装・ドキュメント更新の報告時。使わない: 品質評価（/review）。

/explain さっき編集した flow-17 と .cursor/commands/ だけ。ツリー + 検証コマンド

返答: 触ったパスのツリー（1 行役割）、why、検証結果。

/security — セキュリティレビュー

使う: 認証・認可・外部入力・エクスポート機能。使わない: 文言・スタイルのみの PR。

/security 新規 middleware と /api/invoices/export。IDOR と認可漏れを重点

返答: 重大度付き findings + 修正案。

/fix-ci — CI 赤の解消

使う: GitHub Actions / CI ログが手元にある。使わない: ローカルだけで再現（/debug）。

/fix-ci RSpec: spec/models/order_spec.rb:88 Failure/Error: expected true got false。再現して green まで

返答: 原因、修正、同コマンドで green の証拠。push は許可後。

/ask-spec — コードを変えない壁打ち

使う: 要件・ADR の選択肢整理。使わない: 実装・ファイル編集（Agent / Plan）。

/ask-spec マルチテナント請求の集計単位: 組織 vs ワークスペース。Pros/Cons と ADR 案のみ

モード: Ask 必須。返答: 選択肢表、推奨、未決リスト（doc 案は書いてよいが apply しない）。

サンプル: Commands（.cursor/commands/*.md）

チャットで /review のように呼ぶ定型。Skill より短い 1 ショット向け。下は /review の最小例（全 16 件はリポジトリの .cursor/commands/ を正本とする）。

# review

PR 提出前チェックを実行する。

1. `.cursor/skills/pr-review/SKILL.md` のワークフローに従う
2. 結果を箇条書きで報告。ブロッカーがあれば push を提案しない
3. 参照: flow-14-pr-check.html のチェックリスト

/investigate でスコープを渡す例:

# investigate

次のスコープだけを調査し、構造化結果だけ返す: $ARGUMENTS

- 返却: `{ "paths": [...], "summary": "..." }` または表
- 長い grep ログは貼らない
- git add/commit/push はしない

サンプル: Plan（全ツール共通 + Cursor 下書き）

チーム共有の正本は tasks/todo.md。Cursor Plan モードは .cursor/plans/ に下書き → 確定後 todo へ写す。

# 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 で決める

## レビュー・結果
（実装後: 変更概要、検証コマンド、残課題）

tasks/lessons.md（指摘の蓄積 → Rules 昇格用）:

# tasks/lessons.md

| 日付 | 状況 | 教訓 | 再発防止 |
|------|------|------|----------|
| 2026-05-29 | push 許可なしで commit 提案 | 危険操作は必ず確認 | git-safety.mdc |

.cursor/plans/20260529-feature.md（Plan モード保存例）:

# 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

プロンプト設計

• XML タグや見出しでブロックを分け、モデルが参照しやすくする
• 技術スタックはバージョン付きで宣言（モデルは複数世代の知識を混同しうる）
• 禁止事項（Negative instructions）を明示 — 「〜しない」と「〜する」は同じ重要度
• 例示（few-shot）は 1 パターンずつ短く、本番と同じスキーマで揃える
• 繰り返す依頼は Skills / Commands に昇格する
• プロンプトはコードと同様にレビュー・バージョン管理する

公式: Anthropic — Prompt engineering

実証的チューニング

1. 代表シナリオを 2〜3 件固定（入力・成功条件をファイル化）
2. ルール / プロンプトを1 テーマだけ変えて再実行（差分を追えるようにする）
3. 自己申告 + メトリクス（手数・時間・再試行）を表に記録
4. 連続 N 回クリアで採用。失敗例は tasks/lessons.md へ

深掘り（別エージェントで評価・バイアス排除）: empirical-prompt-tuning（原典 SKILL）。書き手の自己再読は評価の代替にならない。

---

---

クイックスタート Step 3 後。完了 → Phase 2

project/
├── AGENTS.md                          # 入口・必読 rules 索引（Codex 本体にもなる）
├── .cursorignore                      # エージェントから除外するパス
└── .cursor/
    ├── rules/                         # 静的ルール（.mdc + frontmatter）
    │   ├── 00-project.mdc           # alwaysApply: true
    │   ├── 10-domain-rules.mdc
    │   ├── 20-coding-style.mdc      # globs で言語別
    │   └── 60-ai-workflow.mdc
    ├── skills/                        # Agent Skills（SKILL.md、必要時ロード）
    │   └── my-workflow/SKILL.md
    ├── commands/                      # /review 等の再利用コマンド
    ├── plans/                         # Plan モード「Save to workspace」
    └── hooks.json                     # 任意 / 停止時・ツール前後の強制処理

project/
├── AGENTS.md                    # Cursor / Codex 共有の入口
├── CLAUDE.md                    # リポ全体の薄い方針 (+ 必要なら User scope)
├── packages/foo/CLAUDE.md       # 大規模モノレポ向け: サブツリー固有の規約（公式推奨）
├── .agents/skills/              # Codex: リポ共有 Skill
├── .codex/config.toml           # Codex: 任意のプロジェクト設定
└── .claude/
    ├── skills/                  # 必要時に明示利用 / 反復する手順・長い運用を Skill に分離する置き場所
    ├── agents/                  # 任意 / 複雑調査や役割分担が必要な時 / 専用サブエージェントの振る舞いを定型化
    └── settings.json            # 任意 / 対象イベント時 / Hooks で整形・保護ファイル・危険コマンド検査などを強制

project/
├── AGENTS.md                    # リポ全体の短い方針（Cursor と共有可）
├── packages/foo/AGENTS.md       # サブツリー固有の規約（作業ディレクトリに近いほど優先）
├── .agents/
│   └── skills/                  # リポ共有の Skill（SKILL.md + 任意 scripts/）
│       └── phase4-domain-tdd/
│           └── SKILL.md
└── .codex/
    └── config.toml              # 任意 / プロジェクト上書き（trusted プロジェクトのみ読込）

# 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 の平文出力
- 既存実装・既存テスト・既存ドキュメントを読まずに「最善実装」を提案すること

---
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

---
description: コーディング規約 (プロジェクト言語に合わせる)
globs: ["**/*.<project-ext>"]  # 例: **/*.ts, **/*.tsx, **/*.py
---

# Coding Style

## このファイルの役割
- formatter / linter / type checker で表現できることはそちらを正本にする
- ここにはプロジェクト固有の設計・命名・コメント方針だけを書く

## 型と関数
- 型情報は言語標準の方法で明示する
- 公開APIのドキュメントはプロジェクト標準の形式に従う (Docstring / TSDoc / Godoc 等)
- パブリックAPIは pure function を優先、副作用は infrastructure層に閉じる

## コメント
- コメントは「なぜ」のみ。「何をしているか」のコメント禁止
- 許可するアノテーション: TODO / FIXME / HACK / NOTE / WARNING / REVIEW / OPTIMIZE / CHANGED / XXX
- 上記以外の独自接頭辞禁止

## 設計
- レイヤ: interface / application / domain / infrastructure
- domain層は他レイヤに依存しない (依存逆転)
- ORM model と domain entity を混在させない

## 命名
- クラス: PascalCase
- 関数/変数: 言語標準 (`snake_case` / `camelCase`)
- 定数: 言語標準 (`UPPER_SNAKE` 等)
- 私有メンバ: 言語 / FW 標準に従う

## 既存コード優先
新規ファイル作成や大きな変更の前に類似既存ファイルを必ず参照し、命名・構成・エラー処理を揃える。

---
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 を増やす

---
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等) に任せる

---
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/)
- 自分用メモなので簡潔でよい
- 共有する可能性がある場合だけ、後から自分が読める程度の文脈を残す

---
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 だけに閉じ込めない

---
description: 厳格なTDDを採るタスクで使う運用規約。テスト先行の進め方を揃える。
---

# TDD Loop Rules for AI

## 使う場面
- ユーザーが TDD を明示したとき
- リポジトリ / 対象層が test-first を前提としているとき
- docs / 単純リネーム / 設定変更など、挙動を増やさない作業では無理に使わない

## 厳守事項
- RED: 失敗する最小テストを先に追加し、失敗理由を確認する
- GREEN: そのテストを通す最小実装に留める
- REFACTOR: 振る舞いを変えずに重複削減・命名改善・構造整理を行う
- 新しい振る舞いを足すときは次の RED に戻る
- 各サイクルで実行したテストコマンドと結果を共有する

## サイクル粒度
- 1サイクル = 1つの振る舞い / 失敗理由に絞る
- 大きすぎる変更はテストケース単位に分割する

# Claude Code Instructions

@AGENTS.md  ← AGENTS.md を併用する場合のみ

## このファイルの役割
- ルートは薄く（全体像・クリティカルな gotcha）。パッケージ固有は `packages//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]

### 禁止事項
- [ドメインルールに反する実装]
- [未確認のまま本番操作]
- [機微情報の出力]

.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 と同旨

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-dangerous-command.sh" }]
    }]
  }
}

# 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 を使う場合はそちら）

.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

# .codex/config.toml（例・必要なキーのみ）
# 詳細: https://developers.openai.com/codex/config-reference

[approval_policy]
# 対話実行: on-request / 非対話 CI: never など、チーム方針に合わせる

[[hooks]]
event = "pre_tool_use"
# matcher / command はリポのポリシーに合わせて定義（パスは .codex/ 基準）

新規プロジェクトのリポジトリ規約を整備します。

【プロジェクト】
[名称]
[目的・主要ユーザ・主要機能の3行サマリ]

【技術スタック (既知の範囲)】
- 言語: ...
- FW: ...
- DB: ...

【作業】
リポジトリ直下に AGENTS.md を作成し、利用するラインに応じて以下を整備してください。
- Cursor ライン: .cursor/rules/*.mdc
- Claude Code ライン: CLAUDE.md と .claude/skills/ (必要なら .claude/agents/ / Hooks)
- Codex ライン: .agents/skills/ と必要なら .codex/config.toml
内容は本ドキュメント 7.2 のテンプレートに従い、上記プロジェクト前提で具体化してください。
特に 10-domain-rules.mdc は、私が後で埋めるべき項目をプレースホルダで残してください。
tasks/todo.md と tasks/lessons.md が無ければ、リポジトリ同梱のテンプレをコピーして配置してください。

追記方針:
- 毎回守る禁止事項・確認フロー・責務分離は rules / AGENTS.md / CLAUDE.md / Skills に書く
- 機能固有の要件・設計・ADR は docs/ に書く
- 再利用する依頼文テンプレートは docs/prompts/ に分ける

Cursor ルールファイルは frontmatter (description, alwaysApply/globs) を必ず含めてください。
Claude Code 側は CLAUDE.md を短く保ち、長い手順は .claude/skills/ に逃がしてください。
Codex 側は AGENTS.md を短く保ち、長い手順は .agents/skills/ に逃がしてください。
作成後、整備したラインの要点を10行以内で要約してください。

既存リポジトリに本フローを導入します。

【現状】
- 言語/FW: ...
- 規模: 約 XX ファイル, YY KLoC
- 既存規約ファイル: [.editorconfig / pre-commit / 等の有無]

【作業】
1. 既存コードをサンプリングして規約パターンを抽出
2. 抽出結果をもとに AGENTS.md、Cursor 用 .cursor/rules/*.mdc、Claude Code 用 CLAUDE.md / .claude/skills/、Codex 用 .agents/skills/ の初版を提案 (本ドキュメント Phase 1 — 配置ファイルのファイル群)
3. 既存と衝突する箇所は「現状」と「提案」を併記

注意:
- 既存規約を上書きせず追補する形で
- alwaysApply: true は最小限に (現状コードと矛盾しない範囲のみ)
- Claude Code / Codex 側も同じ制約を短く対応付け、長い手順は各 Skill ディレクトリに寄せる
- 恒久ルールに書くことと、docs / prompts / task markdown に分けるべきことを混同しない