一貫したコードレビューのための Claude Code スタイルガイド・プロンプト

スタイル違反が速く広がる理由

スタイル違反は一度に現れる大きな失敗ではなく、プルリクの中で「十分に近い」小さな選択が積み重なることで始まります。放っておくとコードベース全体が読みにくく、不均一になります。

スタイルのずれはよく次のように見えます：あるファイルでは userID、別のファイルでは userId、さらに別では uid。あるハンドラは { error: "..." } を返す、別のは throw する、別のはログに出して null を返す。各変更は小さく見えますが、まとめるとパターンが予測できなくなります。

高速なイテレーションや複数のコントリビュータがあると状況は悪化します。人は目にしたものを真似します。特に時間に追われていると、リポジトリに最新で残っている「ショートカット」が次のテンプレートになります。数週間後には「既存のスタイル」ではなく、単に「最後に行われたこと」がデフォルトになっています。

だから目標は個人の好みではなく一貫した規約にするべきです。問いは「この名前が好きか」ではなく「次の人が迷わず従えるルールに合っているか」です。

違反を早期に見つけるとは、広がる前に悪いパターンを止めることです。新規と変更されたコードに注目し、新しい不整合の最初の出現を直し、ドリフトを招くマージはブロックしましょう。問題を指摘する際は、次に真似しやすい短い望ましい例を添えてください。

現実的な例：開発者が新しい API エンドポイントを追加してデバッグ目的で生のリクエストボディをログに出すとします。それが入ると次のエンドポイントがそれをコピーし、やがて機密データがログに残ります。最初の PR で止めれば安く済み、広がってから修正するのは痛くリスクが高いです。

スタイルガイドを明確でテスト可能なルールにする

レビューでスタイルガイドが機能するには、好みではなくチェックリストのように読めることが必要です。各ガイドラインを差分でチェックできるルールに書き換えましょう。

ルールは命名、レイヤー、エラーハンドリング、ログの4つに分けて整理すると見落としにくくなります。各グループについて「何が満たされるべきか」と「何が禁止か」を書きます。

各ルールの強度を前もって決めておきます：

• Mandatory（必須）：これを満たさないと変更はブロックされる。
• Recommended（推奨）：明確な理由がない限り修正する。
• Optional（任意）：あると良いがブロックはされない。

レビューが終わらないリファクタ祭りにならないようにスコープも設定します。シンプルなルールの例：「新規および変更されたコードは準拠すること。既存の変更されていないコードは、修正を妨げない限り書き換えない。」クリーンアップが必要なら別タスクとして時間を区切って行いましょう。

またレビューから欲しいアウトプットも定義します：合否、ファイルと行参照付きの違反一覧、具体的な編集例としての修正案、バグや情報漏えいの可能性がある場合の簡単なリスク注記などです。

例：PR が生のユーザートークンをログに出している場合、レビューは「ログ：機密をログに出すな」の下で失敗とし、代わりにリクエスト ID をログすることを提案すべきです。

意見ではなくルールを強制するプロンプト構造

スタイルプロンプトが失敗するのは、好みのように聞こえるときです。良いレビュー用プロンプトは契約のように読みます：交渉不可の事項、明確に名前の付いた例外、予測可能な出力。

まず短い2つのブロックから始めます：満たされるべきことと譲れること。そして決定ルールを追加します：「不明な場合は Needs Clarification とマークし、推測しないでください。」

証拠を必須にします。ツールが違反を指摘する場合は、曖昧な説明ではなく正確な識別子とファイルパスを引用させます。この制約だけで多くのやり取りが減ります。

スコープを狭く保ちます：変更行と直接影響を受けるコードパスにだけコメントすること。他のリファクタを許すと、スタイルの強制が「ファイルを書き換えてください」に変わり、人々はフィードバックを信用しなくなります。

再利用できる構造の例：

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

レポートは毎回同じセクションを保つことを要求してください。たとえば：Naming, Layering, Error handling, Logging。

「service layer leaking DB details」と言うなら、internal/orders/service/order_service.go と正確な呼び出し（例：db.QueryContext）を引用しないと意味が薄くなります。これにより修正すべき箇所が議論なく分かります。

ステップバイステップ：スタイルチェックプロンプトのワークフローを作る

スタイルガイドが定着するにはプロセスが再現可能であることが必要です。モデルに味の議論をさせるのではなく、ルールをチェックさせ、毎回同じ手順で行うことが目標です。

シンプルな2パスワークフローを使いましょう：

1. 規約をコンパクトな番号付きルールリスト（10〜25行）として貼る。各ルールはテスト可能にする。
2. 変更のコンテキストを追加する：差分、変更されたファイル、意図を一文で書く。
3. まず違反レポートを要求する。ファイルと行参照、短い理由、正確なルール番号を必須にする。
4. レポートの後に、準拠するための最小パッチを求める。
5. 同じプロンプトを更新後のコードで再実行して残りがないことを確認する。

例：PR が新しいエンドポイントを追加した場合。パス1でハンドラが直接 PostgreSQL に触っている（レイヤー）、リクエスト構造体で命名が混在している（命名）、メールを丸ごとログに出している（ログ）と報告されます。パス2では最小修正を行い：DB 呼び出しをサービス／リポジトリへ移し、構造体名を統一し、ログではメールをマスキングする。その他は変えません。

命名規則：小さな違いを見逃さないためのプロンプト

命名の問題は小さく見えますが実際のコストを生みます：意図が読みづらくなり、検索が大変になり、ほぼ同じ名前が増えます。

レビュワーが変更全体で適用すべき命名ルールを明示してください：ファイル名、エクスポートされた型、関数、変数、定数、テスト。ケーシング（camelCase、PascalCase、snake_case）を明確にし、頭字語のルール（例：APIClient vs ApiClient）を一つ選んで徹底します。

ログのフィールド名やエラータイプ、設定キーなど共通語彙も標準化してください。ログで request_id を使うなら、reqId や requestId を別のファイルで許さないでください。

実践的なレビュ指示例：

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

短い報告としては：混乱しやすい上位3つの名前、ほぼ重複している名前とどちらを残すか、ログ／設定／エラー名で基準に合わないものを挙げさせてください。

レイヤリング規則：責務を混ぜない

レイヤリング規則は平易な言葉が最も効きます：ハンドラは HTTP を扱い、サービスはビジネスルールを持ち、リポジトリは DB を扱う。

依存方向をロックします。ハンドラはサービスを呼んでよい。サービスはリポジトリを呼んでよい。リポジトリがサービスやハンドラを呼んではいけない。ハンドラはデータベースコード、SQL ヘルパー、ORM モデルをインポートしてはいけない。共有パッケージ（config、time、IDs）を使うならアプリロジックを含めないでください。

クロスカッティングな処理は居場所を決めます。バリデーションは境界でのリクエスト形のチェックと、サービス内のビジネスルールで分けるのが普通です。認可はハンドラでアイデンティティやスコープを開始し、サービスで最終決定を強制します。マッピングはレイヤ境界で行います：ハンドラは HTTP をドメイン入力に、リポジトリは DB 行をドメイン型にマップします。

プロンプトに落とし込むと具体的になります：

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

レポートは明示的に：ファイル名、属するべきレイヤ、違反しているインポートや呼び出し、そしてパターンの拡散を防ぐ最小の変更を示してください。

エラーハンドリング規約：プレッシャー下での一貫性

本番で問題が起きるとスタイル議論が激しくなりがちです。明確なエラーハンドリング方針があれば、修正が冷静に行われます。

哲学を一文で書き、それを守らせましょう。例：「コンテキストを追加するためにエラーをラップする。意味を変えるかユーザ向けメッセージにマッピングする場合のみ新しいエラーを作る。生のエラーはシステム境界でのみ扱う。」この一文で無秩序なパターンを防げます。

ユーザ向けの文言と内部の詳細を分離します。ユーザメッセージは短く安全に。内部エラーには操作名や主キーなどを含め検索できるようにしますが、秘密情報は含めません。

レビューで確認する代表的な失敗：エラーを吸い込む（ログに出すだけで返さない）、あいまいな戻り（失敗後に nil 値と nil エラーを返す）、スタックトレースやクエリ文、トークンや PII を漏らすユーザ向けメッセージ。リトライやタイムアウトをサポートするならそれらが明示されていることを要求します。

例：チェックアウトの呼び出しがタイムアウトしたとき、ユーザには「Payment service is taking too long.」のように見せ、内部では op=checkout.charge と注文 ID をラップして記録すると検索可能で対応しやすくなります。

ログ規約：読みやすく、検索でき、安全に

ログは全員が同じ書き方をすると役に立ちます。各開発者が異なる言い回しやレベル、フィールドを使うと検索が難しくなります。

ログレベルは交渉不可にします：debug は開発用の詳細、info は通常の節目、warn は想定外だがハンドル済み、error はユーザ操作が失敗したか注意が必要なとき。fatal や panic は稀で明確なクラッシュポリシーと結びつけます。

構造化ログは文章の完璧さより重要です。ダッシュボードやアラートが壊れないよう安定したキー名を要求します。少数のコアキー（例：event、component、action、status、duration_ms）を決めて一貫させましょう。

機微なデータは厳しく禁止します。絶対にログに出してはいけないもの：パスワード、認証トークン、クレジットカードの全番号、シークレット、生の個人データ。見た目は harmless なものでも、パスワードリセットリンクやセッション ID、生のリクエストボディはアウトです。

相関 ID はデバッグを可能にします。リクエスト内のすべてのログ行に request_id を含めることを要求してください。user_id をログに入れるときはいつ許されるか、その表現方法（匿名ユーザの表記など）を定義してください。

再利用できるプロンプトの例：

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

マージ前に簡易の「安全パス」を実施してください：リクエスト作業の新しいログで request_id がないもの、新しいキーが既存の名前を変えるもの（userId vs user_id）、エラーログで何が失敗したか不明なもの（operation/resource/status がない）、リクエストごとに発火する高頻度ログ、フィールドやメッセージにシークレットや個人データが含まれる可能性のあるものをチェックします。

違反が広がる前に見つける方法

スタイルのドリフトは提案ではなくビルドブレイクのように扱いましょう。マージ前に厳格なゲートを追加し、合否を返すようにします。命名、レイヤ境界、ログ安全、エラーハンドリングなど必須ルールが破られていれば失敗させ、正確なファイルと行を指摘させます。

ゲートは短く保ってください。実用的なトリックは各ルールごとに YES/NO チェックリストを必須にし、どれかが NO なら承認を拒否する方法です。

PR サイズで効くチェックリスト例：

• Naming: ファイル、型、関数が承認されたパターンに一致しているか
• Layering: レイヤを飛ばす直接呼び出しがないか（例：ハンドラが DB を呼ぶ）
• Errors: コンテキスト付きで返されているか、黙認された例外はないか
• Logging: フィールドが一貫しているか、シークレットがないか、レベルが影響に合っているか
• Tests/docs: 振る舞いや公開 API が変わった時に更新されているか

ツールが修正案を出す場合、触ったルールごとに小さな準拠スニペットを必須にしてください。これで「名前を分かりやすく」など曖昧なフィードバックを防げます。

スタイル強制プロンプトで陥りがちな罠

スタイルガイドが失敗する最速の方法は解釈の余地を残すことです。同じルールを2人のレビュワーが読んで異なる結論に至るなら、ツールは好みを強制することになります。

命名はその典型例です。「分かりやすい名前を使え」はテスト不能です。検証可能に絞り込みます："関数は動詞（例：createInvoice）、真偽値は is/has/can、公開型は PascalCase" のように。

もう一つの罠は一度に全部を求めることです。命名、レイヤリング、エラー、ログ、テスト、パフォーマンスを一つのプロンプトで全部要求すると、フィードバックは薄くなります。深掘りが必要ならフォーカスしたパスに分けるか、ゲートプロンプトは必須ルールのみに限定しましょう。

ドリフトを起こしやすい問題：

• 曖昧なルール："クリーン" や "一貫" は測れない言葉なので、測定可能な言葉に置き換える。
• スタイル修正と設計変更を混ぜる：スタイルプロンプトに新しいアーキテクチャを提案させない。
• 引用されない証拠：すべてのコメントに正確な識別子やスニペットの引用を要求する。
• 無言の例外：例外を許すならいつ許されるか短いメモを必須にし、いつ取り除くかフォローアップを明示する。

プロンプトをテストのように扱えば、強制は予測可能になります。助言のように扱うと違反が忍び込み増えます。

変更ごとに素早く回すチェックリスト

差分（リポジトリ全体ではなく差分）に対して迅速にパスを回し、次を確認します：

• Naming: 新しい識別子がパターンに従っているか（ケーシング、接頭辞、接尾辞）。同一概念はファイル間で同じ名前か。
• Layering: 依存は許可された方向のみか。下位レイヤが上位レイヤをインポートしていないか。
• Errors: 失敗はコンテキスト付きで返されているか。無視されているものはないか。
• Logging: 適切なレベル、安定したフィールド、シークレットや個人データがないか。
• Final pass: レビュワーが明確に「no mandatory violations found」か、マージ前に修正すべき違反を列挙するかを宣言する。

小さなプロンプトテンプレートを用意して、変更ごとに貼り付けてください：

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

例：ハンドラ内の新しい関数 procUsr() が PostgreSQL に直接書き込むような場合、機能が動作していても命名とレイヤリングで失敗させます。ここで止めることでコピー＆ペーストが広がるのを防げます。

例：違反を早期に修正する現実的なレビュー

チームメンバーが POST /v1/invoices/{id}/send を追加し、ハンドラ、サービス、ストレージに変更があるとします。

最初のパスではレポートだけを欲します。書き換えは求めません：

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

典型的な指摘：SendInvoiceNow() と SendInvoice の命名不一致、ハンドラが db.QueryRow を直接呼んでいる（レイヤリング違反）、生の err をコンテキスト無しで返している、log.Printf("sending invoice %v", invoice) のようにオブジェクトを丸ごと出す冗長ログ。

2回目のパスでは最小限の安全な修正案を求めます：

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

ルールを破ることが許される場合は事前に明示させます：「例外は許されるが、その理由を短くコメントし、例外を取り除くためのフォローアップタスクを追加すること。」

修正後はハンドラは薄いアダプタになり、サービスがワークフローを担当し、ストレージがクエリを持ち、エラーは fmt.Errorf("send invoice: %w", err) のようにラップされ、ログは請求書IDなど安全なフィールドだけを含む一行にまとまります。

次のステップ：遅くしすぎず定常化する

チーム承認済みのプロンプトを1つ選び、それを共有ツールとして扱いましょう。レビューで最も困っている点（命名のドリフト、レイヤの漏洩、一貫性のないエラー、安全でないログ）から始め、違反が実際に起きたときにのみプロンプトを更新します。

プロンプトの先頭に小さなルールブロックを置き、毎回変更せずに貼り付ける習慣をつけてください。誰もが毎回ルールを編集してしまうと、標準ではなく議論になります。

簡単な運用提案：週のトップのスタイルミスを一人が集め、1つだけ明確なルールか例を追加する。これ以上は増やさない。

チャット駆動のビルドフロー（例：Koder.ai (koder.ai)）で作業するなら、変更の終わりだけでなく変更中にも同じゲートチェックを回す価値があります。Planning、スナップショット、ロールバックなどの機能は、スタイル修正を小さく可逆に保つのに役立ちます。