Phase 1 — 規約整備
ルール配置と初版コミット。
Phase 1 — 規約整備
規約整備の3ツール（Cursor / Claude Code / Codex）
Cursor・Claude Code・Codex ではルールの置き場所と読み込み方が異なります。メインは1本に絞り、禁止事項など事故りやすい条項だけ複数ツールに揃えます。
3ツール比較表・各ツール setup 手順の正本 → ルール/プラン — 3ツール早見 · 初版テンプレ → 本章 ルールファイル本体。
メインで使うツール別・最小構成の早見表
配置ファイル
Cursor の配置ファイル
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 # 任意 / 停止時・ツール前後の強制処理
.mdc の frontmatter：alwaysApply（常に読む）、globs（対象パス）、description（関連時に読む）。alwaysApply（常に読む）は最小限にし、長文は Skills へ。
Claude Code の配置ファイル
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 で整形・保護ファイル・危険コマンド検査などを強制
個人のグローバルルール (
/Users/<user>/.cursor/rules/) に既に書いてあるものは重複させない。Claude Code の個人グローバル指示 (
~/.claude/CLAUDE.md) に既に書いてあるものも重複させない。Codex の個人グローバル指示 (
~/.codex/AGENTS.md) に既に書いてあるものも重複させない。
Codex の配置ファイル
project/
├── AGENTS.md # リポ全体の短い方針（Cursor と共有可）
├── packages/foo/AGENTS.md # サブツリー固有の規約（作業ディレクトリに近いほど優先）
├── .agents/
│ └── skills/ # リポ共有の Skill（SKILL.md + 任意 scripts/）
│ └── phase4-domain-tdd/
│ └── SKILL.md
└── .codex/
└── config.toml # 任意 / プロジェクト上書き（trusted プロジェクトのみ読込）
個人グローバル：~/.codex/AGENTS.md（文体の好みなど）、$HOME/.agents/skills/（全リポ共通 Skill）。一次情報：Codex Customization。詳細は リポジトリ構成。
ルールファイル本体 (テンプレート)
| コピー先 | 用途 | 詳細 |
|---|---|---|
.cursor/rules/*.mdc | Cursor 常時/条件付きルール | ルールサンプル |
CLAUDE.md / .claude/rules/ | Claude Code リポ設定 | Claude Code 章 |
AGENTS.md / .agents/skills/ | Codex / Skills 入口 | Codex 章 |
tasks/todo.md · tasks/lessons.md | Plan · 振り返り | 11.6 tasks/ |
ルールファイル本体 (テンプレート) / Cursor
AGENTS.md＝入口、.cursor/rules/*.mdc＝方針、.cursor/skills/＝手順。旧 .cursorrules は .cursor/rules/ へ移す。
コピー用全文: ルールサンプル — 下記テンプレの一覧ページ。
AGENTS.md
長くしない。Codex は作業フォルダに近い AGENTS.md を優先。Claude 併用時は CLAUDE.md から import して重複を避ける。役割は「何を読むべきか」「どこに書くべきか」の短い索引に絞り、ステークホルダー・必読ルール一覧・出力先（docs/ と z_docs/ の使い分け）・既存パターン参照・禁止事項を記載する。
コピー用全文: AGENTS.md サンプル
.cursor/rules/10-domain-rules.mdc (最重要・プロジェクト固有)
プロジェクト固有の事実だけを書く（一般論や長い手順は他ファイルへ）。数値計算の丸めポリシー、業務不変条件、業務ルール、例外設計（業務例外と技術例外の分離）、用語の日英マッピングをカバーする。
コピー用全文: 10-domain-rules.mdc サンプル
.cursor/rules/20-coding-style.mdc
---
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 標準に従う
## 既存コード優先
新規ファイル作成や大きな変更の前に類似既存ファイルを必ず参照し、命名・構成・エラー処理を揃える。
.cursor/rules/30-testing.mdc
変更箇所に最も近いテストから検証し、必要なときだけ外側へ広げる。層別（domain は Inside-out TDD 厳守、application はユースケース単位、infrastructure/interface は結合・E2E 中心）の厳格度、Red-Green-Refactor サイクル、カバレッジ方針、テスト命名、必須カバー観点（正常系・境界値・異常系・並行性）、アンチパターンを定義する。
コピー用全文: 30-testing.mdc サンプル
.cursor/rules/40-logging.mdc
構造化ログ（JSON）・必須フィールド・レベル別運用（DEBUG〜CRITICAL）・機微情報のマスキング方針（個人情報・認証トークンはログ出力禁止）・出力先（標準出力 + 基盤側で集約）を定める。
コピー用全文: 40-logging.mdc サンプル
.cursor/rules/50-documentation.mdc
docs/（チーム公式、レビュー必須）と z_docs/（任意の個人作業メモ）の役割分担、配置先の判定基準、書式・トーンの違いを定義する。z_docs は docs と二重管理せず、正式に残す内容は docs を正本とする。
コピー用全文: 50-documentation.mdc サンプル
.cursor/rules/60-ai-workflow.mdc
常時守る進め方（1チャット=1タスク、編集前に既存コード・テスト・ドキュメントを読む、推測で埋めない）、検証（最小の有効な確認を実施し未実施は明記）、履歴整備（z_docs/history への作業ログ、docs/adr への正式判断記録）を定める。
コピー用全文: 60-ai-workflow.mdc サンプル
.cursor/rules/61-tdd-loop.mdc
ユーザーが TDD を明示したときなど厳格な test-first が必要な場面でのみ使う運用規約。RED-GREEN-REFACTOR の厳守事項とサイクル粒度（1サイクル=1つの振る舞い）を定める。
コピー用全文: 61-tdd-loop.mdc サンプル
ルールファイル本体 (テンプレート) / Claude Code
長くなったら .claude/rules/ や CLAUDE.local.md へ。Cursor と同じ内容の重複は避ける。
CLAUDE.md (User / Project スコープ)
~/.claude/CLAUDE.md＝個人共通、リポ直下＝全体方針。モノレポは packages/foo/CLAUDE.md でフォルダ固有の規約を足す。User scope（応答言語・要確認コマンド）と Project scope（Claude Code 固有の補足、Cursor ルールとの対応、よく使うコマンド、禁止事項）を分けて書き、`AGENTS.md` とは重複させない。
コピー用全文: CLAUDE.md サンプル
.claude/skills/
各 Skill の frontmatter に description を書く。手動起動だけにしたい手順は disable-model-invocation: true を検討。
コピー用全文: .claude/skills/ サンプル
Hooks (任意)
大規模リポでは Stop フックで学びを CLAUDE.md の更新案として残す運用も有効。結果が一定で、遅くない処理だけ定義する（例: PreToolUse で危険コマンドを検査）。
コピー用全文: Hooks 設定サンプル
ルールファイル本体 (テンプレート) / Codex
設定は .codex/config.toml、外部連携は MCP。禁止事項は Cursor / Claude と短く対応づけ、長文は Skill へ。
AGENTS.md（Codex / 共有）
リポ直下・サブフォルダの AGENTS.md をセッション前に読む。グローバルは ~/.codex/AGENTS.md。Cursor 併用時は Cursor の AGENTS.md を正とする。毎回守る方針・ビルド/テストコマンド・レビュー期待・禁止事項・ルーティング（docs/ と z_docs/ の使い分け）を短くまとめる。
コピー用全文: AGENTS.md（Codex 補足例）サンプル
.agents/skills/
各 Skill に SKILL.md（frontmatter の name / description）と、必要なら scripts/ を置く。
コピー用全文: .agents/skills/ サンプル
.codex/config.toml（任意）
ユーザー設定は ~/.codex/config.toml。リポ上書きは .codex/config.toml。Hooks は結果が一定な処理（lint、危険コマンド検査）向け。
コピー用全文: .codex/config.toml サンプル
Phase 1 初手
新規プロジェクトのリポジトリ規約を整備します。
【プロジェクト】
[名称]
[目的・主要ユーザ・主要機能の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 に分けるべきことを混同しない