| name | refine-rules |
| description | リポジトリのコードベースを分析してClaude Code用のコーディングルール（CLAUDE.md / .claude/rules/）を生成・更新し、併せてコードベース側の不足や問題点も指摘・修正する。「ルールを作りたい」「コーディング規約を整えたい」「CLAUDE.mdを作りたい・見直したい」「.claude/rulesを整備したい」「このリポジトリのルールを書いて」「プロジェクトのコーディングスタイルを整えて」といったリクエストで使うこと。新規リポジトリの初期設定にも、既存ルール・既存コードベースの継続的な見直し・改善にも対応する。 |
Refine Rules
リポジトリのコードベースを観察し、Claude Codeが従うべきコーディングルールを生成・更新するスキル。併せて、コードベース側の不足や問題点（壊れたビルド、緩すぎるリンター、ルールと実装の乖離など）も指摘し、合意のうえで修正する。
ルールシステムの概要
Claude Codeには2つのルール配置先がある。用途に応じて使い分ける。
CLAUDE.md
プロジェクトルートに置く単一ファイル。セッション開始時に必ず読み込まれる。
置くべきもの：
- ビルド・テスト・リントの実行コマンド
- 環境構築手順やツールチェインの前提
- プロジェクト全体に適用されるコーディング規約（命名規則、エラーハンドリング方針など）
- アーキテクチャ上の重要な判断事項（「ORMは使わない」「状態管理はXを使う」など）
- コードから読み取れない暗黙のルールや落とし穴
置くべきでないもの：
- コードを読めばわかること（ディレクトリ構成の羅列、関数一覧など）
- git historyで追えること
- 特定のドメイン領域にしか関係しない詳細なルール（→
.claude/rules/ へ）
配置場所のバリエーション：
./CLAUDE.md — プロジェクト共有（gitにコミット）./CLAUDE.local.md — 個人用（.gitignoreに入れる）~/.claude/CLAUDE.md — グローバル（全プロジェクト共通）
.claude/rules/
ドメインごとにルールを分割するためのディレクトリ。中の .md ファイルはすべてセッション開始時に読み込まれる。
使い分けの目安：
- CLAUDE.md が200行を超えそうなら分割を検討
- テスト、API設計、フロントエンド、DB操作など領域ごとにファイルを分ける
- ファイル名は
testing.md, api-conventions.md, frontend.md のように内容を表す名前にする
書き方： フロントマターやメタデータは不要。プレーンなMarkdownで書く。
参考ドキュメント：
ルール生成の手順
Step 1: コードベースの観察
以下を調査してリポジトリの特徴を把握する：
- 言語とフレームワーク —
go.mod, package.json, Cargo.toml, pyproject.toml 等の依存定義ファイル
- ビルド・テストコマンド —
Makefile, justfile, package.json の scripts, CI設定（.github/workflows/）
- コードスタイル — リンター設定（
.golangci.yml, .eslintrc, ruff.toml 等）、フォーマッター設定
- 既存のルールファイル —
CLAUDE.md, .claude/rules/, .editorconfig 等
- テストの書き方 — テストファイルの命名規則、使用ライブラリ、モック方針
- ディレクトリ構成のパターン — レイヤー分割の方針、パッケージ構成
Step 2: 不足・問題点の指摘と修正
コードベースを観察する過程で、以下のような「ルール以前の問題」に気づいたら、ルールを書く前にユーザーに指摘し、合意のうえで修正すること。ルールを整備しても土台が崩れていると意味がないため。
指摘・修正の対象：
- ビルド・テスト・リントが壊れている、または定義されていない
- リンター/フォーマッター設定が無い、もしくは緩すぎる
- CIが無い、または主要チェックが走っていない
.gitignore の漏れ（ビルド成果物・秘密情報の混入リスク）- 既存の CLAUDE.md /
.claude/rules/ がコードベースの現状と乖離している
- 命名・ディレクトリ構成が宣言した規約と食い違っている
- README に書かれた手順が実際には動かない
進め方：
- 観察で気づいた問題を箇条書きで列挙してユーザーに見せる
- それぞれについて「ルールに書くだけ」「実際に直す」「無視する」のどれにするかを確認する
- 直すと決めたものは、ルール生成と同じセッション内で修正コミットを作る（ルール側にも対応する規約として記述する）
「ルールを書く」ことと「リポジトリを健全な状態にする」ことはセットで進める。
Step 3: ルールの構成を決定
観察結果をもとに、何をCLAUDE.mdに書き、何を .claude/rules/ に分割するか決める。
CLAUDE.md に書く内容（目安）：
- プロジェクトの一行説明
- 主要な開発コマンド（build, test, lint, format）
- 言語バージョンやツールチェインの前提
- プロジェクト全体の基本方針（3〜5項目程度）
.claude/rules/ に分けるケース：
- 特定の言語やフレームワークに固有のルール
- テスト方針の詳細
- API設計規約
- エラーハンドリングのパターン
小〜中規模リポジトリなら CLAUDE.md だけで十分なことも多い。無理に分割しない。
Step 4: ルールの記述
ルールを書くときの原則：
- 英語で書く — ルールの記述は原則として英語を使う。Claudeが最も正確に解釈でき、多言語チームでも共有しやすい
- 簡潔に、具体的に — 「きれいなコードを書け」ではなく「エラーは
fmt.Errorf("failed to %s: %w", action, err) の形式でラップする」のように
- コードから読み取れないことだけ — ファイル構成の説明やライブラリの一覧は不要
- なぜそのルールか、を添える — 「ORMは使わない（パフォーマンスチューニングの柔軟性を確保するため）」のように理由があると判断に使える
- コマンドはコピペ可能に —
go test ./... のようにそのまま実行できる形で
Step 5: ユーザーに提示して確認
生成したルールの内容をユーザーに見せ、過不足がないか確認する。ユーザーの修正指示を反映してからファイルに書き込む。
Step 6: ファイルに書き込む
確認が取れたら CLAUDE.md や .claude/rules/ にファイルを作成・更新する。既存ファイルがある場合は内容をマージする（上書きしない）。
ルール記述のテンプレート
CLAUDE.md の例
# プロジェクト名
簡潔な説明文。
## Development
- Build: `make build`
- Test: `make test`
- Lint: `make lint`
- Single test: `go test -run TestName ./path/to/package`
## Coding Rules
- エラーは必ず `%w` でラップして返す
- publicなAPIには godoc コメントを書く
- テストは table-driven test で書く
- 外部APIの呼び出しは interface 経由にする（テスタビリティのため）
.claude/rules/ の例
<!-- .claude/rules/testing.md -->
# Testing
- テストライブラリは標準の `testing` パッケージ + `testify/assert` を使う
- テストヘルパーは `t.Helper()` を呼ぶ
- 外部サービスとの結合テストは `//go:build integration` タグで分離する
- テストデータは `testdata/` ディレクトリに置く
既存ルールの更新
既に CLAUDE.md や .claude/rules/ が存在する場合：
- 既存の内容を読み込む
- コードベースの現状と照らし合わせて、古くなっている箇所や不足を特定する
- 差分をユーザーに提示する
- 承認を得てから更新する（既存の内容は壊さない）
