Claude Code / Codex
指示書プロンプト＆テンプレ集

あなた（このエージェント）が読み込む指示書ファイル（CLAUDE.md / AGENTS.md
など）を読み込み、AIエージェントが無視しがちな弱点を指摘してから、
効く形に書き直してください。

観点:
- 曖昧な表現を、命令形（必ず〜する / 絶対に〜しない）に直す
- 「完了の定義」と検証ステップ（lint / test の実行）を追加する
- 禁止事項を、対象（ディレクトリ名・コマンド名）まで具体的にする
- 長すぎる場合は、守らせたい核だけに絞る

まず弱点を箇条書きで指摘し、その後に修正版の全文を出力して、
その指示書ファイルに反映してください。

このリポジトリの実際の build / test / lint コマンドを特定したうえで、
あなたが読み込む指示書ファイル（CLAUDE.md / AGENTS.md など）に
「完了の定義」セクションを追記してください。

要件:
- 「次をすべて満たすまで完了と報告しない」形式のチェックリストにする
- lint と test の実コマンドを明記する
- 変更ファイルに TODO・デバッグログを残さない、diff を読み返す、を含める

既存の内容は壊さず、セクションの追加だけ行ってください。

このリポジトリの言語・フレームワークを自動で判定し、それに応じた
ベストプラクティスのルールを、あなたが読み込む指示書ファイル
（CLAUDE.md / AGENTS.md など）に追記してください。

例:
- Next.js: Server/Client 境界（既定は Server、use client は最小）
- Laravel: Form Request での検証、マイグレーション規約
- Python: 型注釈、生データを上書き・捏造しない

判定根拠（どのファイルから判断したか）を一言添えてから追記してください。
既存の記述と重複させないこと。

あなたが読み込む指示書ファイル（CLAUDE.md / AGENTS.md など）に、
以下の「絶対ルール」を、このリポジトリの構成に合わせて追記してください。

- 秘密情報・.env・認証情報をコミットしない
- 指示がない限り push / force-push しない
- 入力は境界で検証する / 認証・認可を勝手に緩めない
- 本番DBに破壊的コマンド（DROP / TRUNCATE / migrate:fresh 等）を実行しない
- 挙動を変えたら必ずテストを追加・更新する

すでに同様の記述があれば重複させず、不足分だけ補ってください。

この `CLAUDE.md` の内容を、OpenAI Codex 向けの `AGENTS.md` 形式に
変換して書き出してください。

- 意味は保ったまま、Codex が読みやすい構成（見出し・箇条書き）に整える
- コマンド・絶対ルール・完了の定義はそのまま維持する
- ルート直下に `AGENTS.md` として出力する

この `CLAUDE.md` の内容を、Cursor の Project Rules 形式
（`.cursor/rules/` 配下の `.mdc` ファイル）に変換してください。

- ルールを意味のある単位に分割する
- 常時適用すべきルールと、特定のファイル種別にだけ適用するルールを分ける
- 各ファイルの先頭に、適用条件（globs など）を適切に設定する

このモノレポの構成を調査し、あなた（このエージェント）が読み込む指示書ファイル
（Claude Code は CLAUDE.md、Codex は AGENTS.md など）を次のように分割して
作成してください。

- ルート直下: 全体共通のルール
  （コミット規約・秘密保護・全体の完了の定義）
- 各パッケージ/アプリのディレクトリ: そのスタック固有のルールとコマンドだけ

重複は避け、各パッケージ側は「ルートの共通ルールに従う」と一言入れてください。
どのディレクトリに何を置いたかを最後に一覧で報告してください。

# プロジェクト: <name>

## これは何か
アプリの概要を1段落で。何をするものか、誰が使うか、技術スタック
（言語・フレームワーク・DB・ランタイム）を書く。

## コマンド
- 開発サーバー: `npm run dev`
- ビルド:       `npm run build`
- テスト:       `npm test`
- Lint:         `npm run lint`

## 規約
- 言語は TypeScript（strict）。`any` は使わない。
- いま編集しているファイルの書き方に合わせる。完了前に必ず Lint を通す。
- 変更は最小限・関係のない行は触らない（無関係な整形をしない）。

## 絶対ルール（厳守）
- 完了と報告する前に、必ず上記のテストと Lint を実行して通すこと。
- 秘密情報・.env・ビルド生成物は絶対にコミットしない。
- 新規ファイルを作るより、既存ファイルの編集を優先する。
- 要件が曖昧なときは、大きく変更する前に1つだけ確認の質問をする。

## 触ってはいけない範囲（指示がない限り）
- CI 設定、依存パッケージのバージョン、インフラ構成。

# <name>

- スタック: <例: Next.js + TypeScript + PostgreSQL>
- 完了前に必ず実行: `npm run lint` と `npm test`（両方通すこと）
- 既存の書き方に合わせる。無関係な行は整形しない。
- 秘密情報・.env はコミットしない。push は指示があるまでしない。
- 曖昧なら、推測せず1つだけ質問する。

# Next.js（App Router）+ TypeScript

## スタック
Next.js（App Router）, TypeScript strict, Tailwind CSS, <your-ORM>

## コマンド
- 開発:   `npm run dev`
- ビルド: `npm run build`   # 型エラーなしで通ること
- Lint:   `npm run lint`
- テスト: `npm test`

## アーキテクチャの規則
- 既定は Server Component。state・effect・ブラウザAPIが要るときだけ
  "use client" を付ける。Client Component は小さく末端に保つ。
- データ取得は Server Component か Route Handler で行う。
  初期表示を useEffect で取得しない。
- コンポーネントはルートセグメントに co-locate。共通UIは `components/`。
- 外部入力は境界で必ずスキーマ検証する（例: Zod）。

## 規約
- `any` 禁止。公開関数には明示的な戻り値型を付ける。
- 既存のデザイントークン／Tailwind クラスを使う。色を勝手に増やさない。
- `page.tsx` は薄く保ち、ロジックは関数・コンポーネントへ寄せる。

## 完了の定義
`npm run build` `npm run lint` `npm test` がすべて 0 で通る。
`any` なし・未使用 export なし・console.log の残しなし。

# React（Vite）+ TypeScript

## コマンド
- 開発:   `npm run dev`
- ビルド: `npm run build`
- Lint:   `npm run lint`
- テスト: `npm test`（Vitest + Testing Library）

## 規則
- 関数コンポーネント＋Hooks のみ。クラスコンポーネントは使わない。
- 状態は「ローカル → Context → 状態ライブラリ」の順で必要最小限に。
  むやみにグローバル状態へ上げない。
- 副作用は useEffect に閉じ込め、依存配列を正しく書く。
- UI とロジックを分離。データ取得は専用フック（useXxx）にまとめる。
- アクセシビリティ: 対話要素は適切なロールとキーボード操作を持たせる。

## 規約
- `any` 禁止。props は型で定義する。
- 既存のコンポーネント／スタイルの流儀に合わせる。

## 完了の定義
`npm run build` `npm run lint` `npm test` が 0 で通る。

# Node.js API（Express / Hono）+ TypeScript

## コマンド
- 開発:   `npm run dev`
- ビルド: `npm run build`
- テスト: `npm test`
- Lint:   `npm run lint`

## 規則
- すべての入力（body・query・params・header）を境界でスキーマ検証する。
- エラーは握りつぶさない。集約エラーハンドラで型付きで返す。
- 秘密情報は環境変数から読む。コードに直書きしない。
- DB アクセスは層を分ける（ルート → サービス → リポジトリ）。
- 返却は一貫した JSON 形（成功・失敗の形を統一）。

## 絶対ルール
- 認証・認可のロジックを勝手に省略・緩和しない。
- 外部公開エンドポイントを増やすときは必ず認可を確認する。
- ログに個人情報・トークン・パスワードを出さない。

## 完了の定義
`npm test`（正常系＋異常系）と `npm run lint` が通る。

# Laravel + PHP

## コマンド
- 起動:       `php artisan serve`
- マイグレート: `php artisan migrate`
- テスト:     `php artisan test`
- 整形:       `./vendor/bin/pint`   # 完了前に実行

## 規約（Laravel の流儀に従う）
- Eloquent のリレーションを使う。明確な理由がなければ生SQLを避ける。
- 入力検証は Form Request クラスで行う。コントローラ内でやらない。
- コントローラは薄く。業務ロジックは Service / Action へ。
- スキーマ変更は毎回新しいマイグレーション。実行済みのものは編集しない。
- 名前付きルートとルートモデルバインディングを使う。

## 絶対ルール
- `.env` や本物の認証情報を絶対にコミットしない。
- 本番DBに対して `migrate:fresh` など破壊的コマンドを実行しない。
- 挙動を変えたら必ずテストを追加・更新する（`php artisan test`）。

## 完了の定義
`php artisan test` と `./vendor/bin/pint --test` の両方が通る。

# Python / データ分析

## 環境
- プロジェクトの venv `.venv` を使う。グローバルに入れない。
- 導入: `pip install -r requirements.txt`
- 実行: `python -m src.main`
- テスト: `pytest`
- 整形: `ruff check .` と `ruff format .`

## 規約
- すべての関数シグネチャに型注釈を付ける。設定があれば `mypy src` を実行。
- ノートブックにロジックを書かない。再利用コードは `src/` へ。
- 乱数を使う処理はシードを固定し、結果を再現可能にする。

## データの絶対ルール（最重要）
- 欠損値を黙って埋めない・捏造しない。欠損があれば報告し、扱いを確認する。
- 生データファイルを上書きしない。出力は `data/processed/` へ書く。
- 前提（フィルタ・除外行・単位）はすべてコードのコメントに明記する。

## 完了の定義
`pytest` が通り、`ruff check .` がクリーンで、
クリーンな状態から結果が再現できる。

# Go

## コマンド
- ビルド: `go build ./...`
- テスト: `go test ./...`
- 整形:   `gofmt -w .` と `go vet ./...`

## 規約
- エラーは握りつぶさない。`if err != nil` で必ず処理し、文脈を付けて返す
  （`fmt.Errorf("...: %w", err)`）。
- 早期 return でネストを浅く保つ。
- 並行処理は必要なときだけ。goroutine のリークと競合に注意する
  （`go test -race` を通す）。
- 公開シンボルにはコメントを付ける。標準ライブラリを優先する。

## 絶対ルール
- 不要な抽象化・インターフェースを足さない（必要になってから作る）。
- 依存を増やすときは標準ライブラリで足りないか先に確認する。

## 完了の定義
`go build ./...` `go vet ./...` `go test -race ./...` がすべて通る。

# Rust

## コマンド
- ビルド: `cargo build`
- テスト: `cargo test`
- Lint:   `cargo clippy -- -D warnings`
- 整形:   `cargo fmt`

## 規約
- 本番コードで `unwrap()` / `expect()` を安易に使わない。
  `Result` / `Option` を `?` や match で正しく処理する。
- `unsafe` は原則禁止。どうしても必要なら理由をコメントで明記する。
- 借用とライフタイムはコンパイラに従う。`clone()` で逃げる前に設計を見直す。
- エラー型は `thiserror` / `anyhow` などで意味のある形にする。

## 完了の定義
`cargo build` `cargo test` が通り、
`cargo clippy -- -D warnings` が警告ゼロ。

# Ruby on Rails

## コマンド
- 起動:       `bin/rails server`
- マイグレート: `bin/rails db:migrate`
- テスト:     `bin/rails test`（または `bundle exec rspec`）
- 整形:       `bundle exec rubocop -A`

## 規約（Rails の流儀に従う）
- 「設定より規約」を尊重し、独自の構成を勝手に作らない。
- 太ったコントローラ／モデルを避ける。ロジックは Service / Concern へ。
- 強いパラメータ（strong parameters）で入力を絞る。
- N+1 を避ける（`includes` を使う）。
- スキーマ変更は新しいマイグレーション。実行済みは編集しない。

## 絶対ルール
- `.env` や credentials を絶対にコミットしない。
- 本番DBに破壊的コマンドを実行しない。
- 挙動を変えたらテストを追加・更新する。

## 完了の定義
テストと `bundle exec rubocop` が通る。

# SQL / データベースマイグレーション

## 絶対ルール（データ保護が最優先）
- 本番データに対して破壊的な操作を勝手に実行しない
  （DROP / TRUNCATE / 条件なし DELETE・UPDATE）。
- マイグレーションは前進方向だけでなく、ロールバック手順も用意する。
- 実行済みのマイグレーションは編集しない。常に新しいものを追加する。
- カラム削除・リネームは「追加 → 移行 → 廃止」の段階を踏む（一発でやらない）。

## クエリの規約
- `SELECT *` を避け、必要な列を明示する。
- WHERE / JOIN の条件にインデックスが効くか確認する。
- 大量更新はバッチに分け、ロック時間を短く保つ。
- 破壊的な検証クエリは、まず `SELECT` で対象件数を確認してから実行する。

## 完了の定義
ステージング相当で適用→ロールバックの両方が成功し、
既存データに意図しない変化がないことを確認した。

# テスト駆動の進め方

挙動を変えるときは、毎回このループに従う:
1. 望む挙動を表す「失敗するテスト」を先に書く。
2. テストを実行し、正しい理由で失敗することを確認する。
3. テストを通す最小限のコードを書く。
4. テスト全体を実行し、すべて緑になることを確認する。
5. 緑を保ったままリファクタリングする。

## 絶対ルール
- テストを削除・スキップして全体を通さない。
- 緑にするためにアサーションを弱めない。
- テストが本当に間違っているなら、変更前に理由を説明する。
- テストのない新規コードは「完了」ではない。

## 完了の定義
テスト全体が通り、カバレッジが下がっておらず、
実装を元に戻すと新しいテストが失敗する（＝意味のあるテストである）。

# デバッグの進め方

次の順序で進める。当てずっぽうで直さない:
1. 再現手順を確定する（どうすればバグが起きるか）。
2. 期待される挙動と、実際の挙動を1文ずつ書き出す。
3. 仮説を立てる。ログや最小再現で仮説を検証してから直す。
4. 原因を特定できたら、最小限の修正を当てる。
5. 修正後、再現手順でバグが消えたことと、既存テストが通ることを確認する。
6. 可能なら、このバグを捕まえる回帰テストを追加する。

## 絶対ルール
- 原因が分からないまま、複数箇所を同時に変えない。
- 「とりあえず動いた」で終わらせない。なぜ直ったかを説明する。
- 関係のないリファクタリングをデバッグに混ぜない。

# リファクタリングの進め方

## 大原則
外から見た挙動を変えない。入力に対する出力・副作用を一切変えない。

## 手順
1. 対象範囲のテストが存在し、緑であることを先に確認する。
   なければ、現状の挙動を固定する特性テストを先に書く。
2. 小さく1ステップずつ変更し、毎ステップでテストを実行する。
3. 1コミット=1種類の改善に保つ。

## 絶対ルール
- 機能追加・バグ修正をリファクタリングに混ぜない（別作業にする）。
- テストが赤になったら、その場で立ち止まる。先へ進まない。
- 公開APIのシグネチャを勝手に変えない（必要なら先に確認する）。

## 完了の定義
すべてのテストが緑のまま、コードが読みやすく・重複が減っている。

# 設計ドキュメントの書き方

実装の前に、まず次を文章で出す（コードは書かない）:

## 1. 目的
解きたい課題と、達成できたと言える条件（成功基準）。

## 2. 現状と制約
既存の仕組み・依存・守るべき制約（性能・互換性・締切）。

## 3. 設計案
- 採用案と、検討して捨てた案（なぜ捨てたか）。
- データの流れ・主要なインターフェース・変更するファイル。

## 4. リスクと未確定事項
壊れうる箇所、確認が必要な前提、要・意思決定の論点。

## 5. 段取り
実装を小さなステップに分割し、検証可能な単位で並べる。

## ルール
- この設計が承認されるまで実装に入らない。
- 不明点は「未確定事項」に挙げ、勝手に仮定で埋めない。

# 大規模変更の進め方

## 大原則
1つの巨大な変更を避ける。各ステップが単独でレビュー・テスト・
（理想的には）デプロイ可能になるよう分割する。

## 手順
1. 最終形に至る変更を、小さな独立ステップの列に分解して提示する。
2. ステップごとに「何を・なぜ・影響範囲」を1〜2行で書く。
3. 各ステップ後にテスト全体を実行し、緑を確認してから次へ進む。
4. 後方互換を保ちながら進める（追加 → 移行 → 旧経路の廃止）。

## 絶対ルール
- 一度に広範囲を書き換えて「あとでまとめてテスト」をしない。
- 1ステップが大きくなりすぎたら、さらに分割する。
- 各ステップは元に戻せる（revert 可能な）粒度に保つ。

## 完了の定義
全ステップ完了後もテストが緑で、途中の各コミットも壊れていない。

# コードレビューの指示

変更をレビューし、重大度ごとにまとめて、この順で報告する:
1. CRITICAL - セキュリティ穴・データ消失・クラッシュ・認証破綻
2. HIGH     - ロジックバグ・競合状態・エラー処理の欠落
3. MEDIUM   - 性能問題・テスト不足・分かりにくい命名
4. LOW      - スタイルの細かい指摘（上位の問題がない場合のみ）

## 報告のしかた
- 各指摘: ファイル:行 / 何が問題か / なぜ重要か / 具体的な修正案。
- 該当する最小のスニペットだけ引用する。ファイル全体を貼らない。
- 変更が正しいなら、正しいと明言する。問題を捏造しない。

## やってはいけないこと
- 本物のバグを見落として LOW の細かい指摘で埋め尽くさない。
- ファイル全体を書き直さない。最小の diff を提案する。
- 実害がない限り、diff の範囲外の行を指摘しない。

## 出力
最後に一行の判定: APPROVE / REQUEST CHANGES / BLOCK と理由を付ける。

# Git・PR ルール

## コミット
- Conventional Commits を使う: `type(scope): 要約`
  type: feat, fix, refactor, test, docs, chore。
- 1コミット=1つの論理的変更。小さくレビュー可能に保つ。
- 本文には「何を」より「なぜ」を書く。

## 絶対ルール
- 指示がない限り `git push` をしない。
- 共有ブランチ／main に force-push・rebase・amend をしない。
- 秘密情報・.env・認証情報・大きなバイナリをコミットしない。
- ファイルは名前を指定して add する。`git add -A` で巻き込まない。

## プルリクエスト
- タイトルは70文字以内。本文は「概要」＋「テスト計画（チェックリスト）」。
- 破壊的変更があれば明記する。
- マージはしない。PR を作成して URL を報告する。

# セキュリティレビューの指示

変更を、次の観点で順にチェックし、見つけた問題を重大度付きで報告する:
- 入力の検証漏れ（インジェクション: SQL / コマンド / XSS / SSRF）
- 認証・認可の抜け（権限チェック漏れ、権限昇格）
- 秘密情報の露出（ハードコードされた鍵・トークン、ログへの出力）
- 安全でないデフォルト（過剰な公開範囲、緩い CORS、未検証リダイレクト）
- 依存の既知脆弱性、安全でない暗号・乱数の使用

## 報告のしかた
- 各指摘: 場所 / 攻撃シナリオ（どう悪用されるか）/ 具体的な修正。
- 確証がない疑いは「要確認」と明示して挙げる（黙って見逃さない）。
- 問題がなければ、確認した観点とともに「問題なし」と述べる。

## やってはいけないこと
- 実際に攻撃するコードや悪用手順を生成しない（修正方法のみ示す）。

# Docker / インフラ作業ルール

## 絶対ルール（破壊防止が最優先）
- 本番・共有環境に対して破壊的コマンドを勝手に実行しない
  （`docker system prune`、ボリューム削除、`down -v` など）。
- イメージは固定タグで指定する。`latest` に依存しない。
- 秘密情報は環境変数・シークレット管理で渡す。
  Dockerfile やイメージに焼き込まない。
- 公開ポート・権限（privileged 等）を必要最小限にする。

## 規約
- Dockerfile はマルチステージで小さく保ち、レイヤキャッシュを意識する。
- 非 root ユーザーで動かす。
- 変更後はローカルでビルド＆起動確認してから報告する。

## 完了の定義
`docker build` が通り、コンテナが起動し、
ヘルスチェック／基本動作が確認できる。

# 依存パッケージのルール

## 絶対ルール
- 依存を追加する前に、標準ライブラリや既存の依存で足りないか確認する。
- 新しい依存を入れるときは、目的・代替案・メンテ状況を一言添える。
- メジャーバージョンの更新を勝手にしない（指示があるときだけ）。
- ロックファイル（package-lock.json 等）を勝手に作り直さない。
- 出所の怪しい・スター数やメンテが極端に乏しいパッケージを避ける。

## 手順
1. 追加・更新の理由を述べる。
2. 入れた後、ビルド・テストが通ることを確認する。
3. ライセンスが用途と矛盾しないかを確認する。

## 完了の定義
依存変更後もビルド・テストが通り、ロックファイルの差分が説明できる。