記事

Claude Codeにコード規約を守らせるための書き方

Claude Codeが命名規則や依存追加ルールを無視しないよう、CLAUDE.md・Hooks・Skillsの3つで規約を適用する方法を解説します。書くべき内容・避けるべき内容・例文テンプレートをまとめます。

Claude Codeはデフォルトでは「よくある実装」を選びます。命名規則・import方式・コメントスタイル・依存追加の判断は、プロジェクト固有の規約をどこかに明示しないとプロジェクトのスタイルから外れます。この記事ではCLAUDE.md・Hooks・Skillsの3つを使ってコード規約を確実に適用する方法を整理します。

AIが規約を破る2つの原因

Claude Codeがコード規約を無視するのは、おおむね次の2つが原因です。

1. そもそも規約が書かれていない: CLAUDE.mdやプロンプトに書いていない規約を守らせるのは不可能です。

2. CLAUDE.mdが長すぎて特定のルールが埋もれる: 公式ドキュメントは「CLAUDE.mdが長すぎると、重要なルールが見つからず無視される」と明確に述べています。200行を超えているようなら、優先度の低い記述を削るか.claude/rules/に分割する必要があります。

どちらも「書けば解決」ではなく「何をどこに、どう書くか」が重要です。

CLAUDE.mdに書くコード規約の例

CLAUDE.mdはセッション開始時に必ず読み込まれます。プロジェクト全体に適用したい規約はここに書きます。

書くべき規約の例

# コードスタイル
- ES modules（import/export）を使う。CommonJS（require）は使わない
- importはできるだけ分割代入で書く（例: import { foo } from 'bar'）
- 型は明示的に書く。any型の使用は禁止

# 命名規則
- コンポーネント: PascalCase（例: UserProfile）
- 関数・変数: camelCase（例: getUserById）
- 定数: UPPER_SNAKE_CASE（例: MAX_RETRY_COUNT）
- ファイル: kebab-case（例: user-profile.tsx）

# 依存関係
- 新しいnpmパッケージの追加は禁止。必要な場合は作業を止めて確認を求めること
- 標準ライブラリやすでにpackage.jsonにあるパッケージのみ使用すること

「IMPORTANT:」や「YOU MUST」を前置きすると守られやすいことが公式ドキュメントで言及されています。守らせたいルールには強調を加えると効果的です。

# IMPORTANT: 依存関係
- YOU MUST NOT install new npm packages. If you need a library not in package.json,
  stop and ask for approval before proceeding.

書かないほうがよい規約

書かなくてよい内容	理由
「変数名はわかりやすく」	標準的な話でClaude Codeはもともと知っている
「コードはきれいに書く」	抽象的すぎて指針にならない
「Reactを使っています」	コードを読めばわかる
バージョン番号や変更頻度が高い情報	すぐに古くなって誤誘導になる
APIドキュメントの全文	長大になりすぎる（リンクで代替する）

「このルールを削っても、Claudeは普通に正しくやるだろうか？」という問いにYesなら削除対象です。残すルールは「書かないとClaude Codeがミスをする」ものだけにします。

規約ファイルを@importで分割する

CLAUDE.mdが200行を超え始めたら、.claude/rules/に分割して@インポートで参照します。

# CLAUDE.md
プロジェクト概要: スノーピーク技術ブログのmonorepo

@.claude/rules/coding-style.md
@.claude/rules/git-workflow.md
@.claude/rules/dependencies.md

各ファイルを小さく保つことで、特定ルールの追加・削除・更新が容易になります。この方法については「CLAUDE.mdテンプレート完全版」で詳しく解説しています。

Hooksで「例外なく実行」を保証する

CLAUDE.mdへの記述はアドバイザリーです。Claude Codeが読んで判断の参考にしますが、忘れたり無視したりすることがあります。

一方、Hooksはスクリプトを確定的に実行します。「ファイルを編集するたびに必ずESLintを実行する」「特定ディレクトリへの書き込みをブロックする」といった例外を許さないルールに向いています。

.claude/settings.jsonに次のように書くと、ファイル編集後に自動でlintが走ります。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix"
          }
        ]
      }
    ]
  }
}

/hooksコマンドで現在の設定を確認・編集できます。「毎回必ず実行すべきチェック」はHooksに書き、「判断が必要なルール」はCLAUDE.mdに書く、という使い分けが基本です。

Skillsで専門的ルールを分離する

Skillsは.claude/skills/に置いたSKILL.mdファイルで定義するドメイン知識のパッケージです。セッション開始時ではなく必要なときだけロードされるため、CLAUDE.mdに全部書くよりもコンテキストを節約できます。

たとえば、REST API設計の規約をSkillとして定義する場合は次のようになります。

# .claude/skills/api-conventions/SKILL.md
---
name: api-conventions
description: このプロジェクトのREST API設計規約。APIエンドポイントを追加・変更するとき自動的に適用。
---
# API規約
- URLパスはkebab-caseを使う（/user-profileなど）
- JSONプロパティはcamelCaseを使う
- リスト系エンドポイントには必ずページネーションを付ける
- バージョンはURLに含める（/v1/, /v2/）
- エラーレスポンスは{ error: string, code: string }の形式で返す

APIエンドポイントを追加するタスクを依頼すると、Claude CodeはdescriptionからこのSkillを自動的に呼び出します。「APIエンドポイント変更のときだけ読む規約」を毎回のセッションに持ち込まずに済みます。

コピー可能な規約テンプレート集

実際にCLAUDE.mdに貼り付けて使える規約のサンプルです。プロジェクトに合わせて調整してください。

TypeScript／フロントエンドプロジェクト向け

# コードスタイル
- TypeScriptを使う。any型は禁止
- ES modules（import/export）を使う。CommonJS（require）は使わない
- Reactコンポーネントは関数コンポーネントで書く。クラスコンポーネントは使わない
- スタイルはTailwind CSSを使う。インラインstyleは禁止
- 非同期処理はasync/awaitを使う。Promiseチェーンは使わない

# 命名
- コンポーネント: PascalCase
- hooks: use プレフィックス（例: useUserData）
- 型・インターフェース: PascalCase（例: UserProfile, ApiResponse）
- ファイル: コンポーネントはPascalCase.tsx、それ以外はkebab-case.ts

# IMPORTANT: 依存関係
- package.jsonに記載のないパッケージを追加しないこと
- 必要な場合は実装を止めてユーザーに確認を求めること

バックエンド／Node.jsプロジェクト向け

# コードスタイル
- TypeScript strict modeを使う
- エラーはthrowせず Result型か { data, error } のパターンで返す
- ロギングはconsole.logではなくloggerモジュール（src/lib/logger）を使う

# DB操作
- 生SQLは使わない。必ずORMのクエリビルダーを使う
- トランザクションが必要な場合はwithTransaction()ヘルパーを使う

# IMPORTANT: セキュリティ
- ユーザー入力はzodでバリデーションしてから使う
- 環境変数は直接process.env.FOOで読まず、src/config.tsを経由する

規約が守られないときの診断

規約を書いても守られない場合、次の順番で確認します。

CLAUDE.mdが200行を超えていないか: 長すぎると重要なルールが埋もれます。まず削減か分割を試みてください
規約が具体的か抽象的か: 「きれいに書く」より「インライン型は使わずtype/interfaceで定義する」のほうが従いやすい
コード規約がコードから推測可能な内容ではないか: 既存のファイルを読めばわかることはCLAUDE.mdに書かなくてもよい
Hooksで強制できるか: 「必ず実行すべきもの」はアドバイスではなくHooksのスクリプトで保証する
依頼文で明示されているか: CLAUDE.mdの規約は全体方針ですが、タスク依頼文に「既存のコードスタイルに合わせて実装してください」と書くとより確実です

プロジェクト固有のファイル構成や命名方針については「Claude Codeでプロジェクトを読ませる前に整理すべきファイル構成」が詳しいです。