0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@hikariclaude01(光 久朗土)

CLAUDE.md設計完全ガイド — 権限レベル別テンプレートで「AIが勝手にやらかす」を防ぐ

0
Posted at

結論：Claude Codeを導入したら、最初にCLAUDE.mdを書け

Claude Codeを導入して最初にやるべきことは、コードを書かせることではなく 「やっていいこと/ダメなこと」を定義するCLAUDE.mdを書くこと です。

この記事を読むと、以下がわかります。

  • CLAUDE.mdの役割と、AGENTS.mdとの明確な違い
  • 個人開発・チーム開発・本番運用の3つの権限レベル別テンプレート
  • autoモードと確認モードの実践的な使い分け
  • .claude/settings.jsonのリスクレベル別設定
  • CLAUDE.mdがなかったことで実際に事故りかけた体験談

「AIが勝手にやらかす」を防ぐ仕組みは、コード品質の問題ではなく 設計の問題 です。順を追って解説します。

環境・前提条件

項目 バージョン等
Claude Code 最新版（2025年7月時点）
OS macOS / Linux（Windowsも基本同様）
前提知識 Claude Codeの基本操作を一度は触ったことがある

1. CLAUDE.mdとは何か — AGENTS.mdとの違いと役割整理

CLAUDE.mdの正体

CLAUDE.mdは、Claude Codeがタスクを実行する際に自動的に読み込む指示書です。プロジェクトルートに配置すると、Claudeはこのファイルの内容をシステムプロンプトの一部として解釈します。

具体的には以下を定義できます。

  • プロジェクトの概要・技術スタック
  • コーディング規約・命名規則
  • やっていいこと（許可操作）
  • やってはいけないこと（禁止操作）
  • ワークフローの手順

AGENTS.mdとの違い

混同されやすいAGENTS.mdとの役割を整理します。

比較項目 CLAUDE.md AGENTS.md
対象ツール Claude Code専用 複数のAIエージェント共通
読み込み 自動（階層的にマージ） ツールによる
主な用途 権限制御・操作ルール リポジトリ情報・貢献ガイド
配置場所 ~/, プロジェクトルート, サブディレクトリ プロジェクトルート

ポイント： CLAUDE.mdは「Claude Codeへの業務命令書」、AGENTS.mdは「どのAIでも読める自己紹介カード」と捉えると整理しやすいです。

読み込み階層の優先順位

CLAUDE.mdは3つのレベルで配置でき、すべてがマージされて読み込まれます。

  1. ユーザーグローバル (~/.claude/CLAUDE.md) — 全プロジェクト共通のルール
  2. プロジェクトルート (./CLAUDE.md) — そのリポジトリ固有のルール
  3. サブディレクトリ (./src/CLAUDE.md) — 特定ディレクトリだけのルール

矛盾する指示がある場合、より具体的な（深い）レベルが優先されます。

2. 権限レベル別テンプレート3選

テンプレート①：個人開発（Low Risk）

速度重視。自分しか使わないプロジェクトで、多少壊れてもすぐ直せる前提です。

# CLAUDE.md — 個人開発プロジェクト

## プロジェクト概要
- 個人ブログのNext.jsアプリ
- TypeScript + Tailwind CSS + Prisma

## コーディング規約
- 関数コンポーネントのみ使用
- 変数名はcamelCase、コンポーネント名はPascalCase
- コミットメッセージはConventional Commits形式

## 許可事項
- ファイルの作成・編集・削除
- npm パッケージのインストール
- git add / commit（pushは確認を求めること）
- データベースのマイグレーション（開発環境のみ）

## 禁止事項
- 本番環境への直接デプロイ
- 環境変数ファイル（.env*）の内容をログ出力しないこと
- 既存テストを削除しないこと（修正は可）

テンプレート②：チーム開発（Medium Risk）

チームメンバーのコードに影響するため、破壊的操作に確認を挟みます。

# CLAUDE.md — チーム開発プロジェクト

## プロジェクト概要
- SaaS管理画面（React + Go）
- モノレポ構成（frontend/ backend/ shared/）

## 技術スタック
- Frontend: React 19, TypeScript, Zustand, Vitest
- Backend: Go 1.23, Echo, sqlc
- DB: PostgreSQL 16
- CI: GitHub Actions

## コーディング規約
- フロントエンド: ESLint + Prettierの設定に従うこと
- バックエンド: golangci-lintの設定に従うこと
- 新規APIエンドポイントには必ずテストを書くこと
- PRタイトルはConventional Commits形式

## 許可事項（自動実行OK）
- ファイルの読み取り・検索
- 既存ファイルの編集（テスト付き）
- lint / format の実行
- テストの実行

## 確認が必要な操作
- 新しいパッケージの追加（理由を説明すること）
- ディレクトリ構造の変更
- 共有型定義（shared/）の変更
- データベーススキーマの変更

## 禁止事項
- main / developブランチへの直接コミット
- 他メンバーのPRブランチを勝手に変更
- CI/CDパイプラインの設定変更
- .env* ファイルの変更
- node_modules/ vendor/ を直接操作

## レビュー指針
- 1つのコミットは1つの責務にまとめること
- 変更理由をコミットメッセージに必ず含めること

テンプレート③：本番運用（High Risk）

本番環境に近いコードを扱う場合。原則すべて確認モードです。

# CLAUDE.md — 本番運用プロジェクト

## ⚠️ 重要：このプロジェクトは本番環境に影響します

## プロジェクト概要
- 決済システムのバックエンド
- ダウンタイム = 直接的な売上損失

## 鉄のルール（絶対に破らないこと）
1. いかなる変更も自動実行しないこと。必ず確認を求めること
2. データベースへのWRITE操作は一切行わないこと
3. 外部API（決済・認証）への実リクエストは禁止
4. シークレット・認証情報を含むファイルは読み取りも禁止
5. 本番環境のログに個人情報を出力するコードを書かないこと

## 許可事項（確認後に実行）
- コードの読み取り・分析
- ローカルでのテスト実行（モックを使用すること）
- ドキュメントの更新

## 確認が必要な操作（詳細な説明を添えること）
- すべてのコード変更
- テストコードの変更
- 設定ファイルの変更

## 絶対禁止
- デプロイコマンドの実行
- データベースマイグレーションの実行
- 本番環境へのSSH / API呼び出し
- セキュリティ関連設定（CORS, CSP, 認証）の変更
- 依存パッケージのメジャーバージョンアップ

## 変更時の必須手順
1. 影響範囲を最初に説明する
2. 変更前後のdiffを提示する
3. 関連するテストが通ることを確認する
4. ロールバック手順を提示する

3. autoモード vs 確認モードの使い分けフローチャート

Claude Codeには操作を自動実行するautoモードと、ユーザーに確認を求める確認モードがあります。どちらを使うかは「操作のリスクレベル」で判断します。

allowedToolsの具体的な設定

allowedToolsは.claude/settings.jsonで定義し、確認なしで自動実行を許可するツールを指定します。

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Grep",
      "Glob",
      "LS",
      "BatchTool",
      "Task"
    ]
  }
}

重要： allowedToolsに追加するほどClaude Codeの自律性が上がりますが、事故リスクも比例して上がります。迷ったら追加しないのが安全です。

4. .claude/settings.jsonのリスクレベル別設定例

.claude/settings.jsonはCLAUDE.mdと並ぶ重要な設定ファイルです。CLAUDE.mdが「自然言語の指示書」であるのに対し、settings.jsonは「機械的な権限制御」を担います。

リスクレベル別の設定例

Low Risk（個人開発）

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "LS",
      "BatchTool",
      "Task",
      "Bash(npm run *)",
      "Bash(npx *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "denyTools": [
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  }
}

Medium Risk（チーム開発）

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "BatchTool",
      "Task",
      "Bash(npm run lint *)",
      "Bash(npm run test *)",
      "Bash(npm run format *)"
    ],
    "denyTools": [
      "Bash(git push *)",
      "Bash(git checkout main)",
      "Bash(git checkout develop)",
      "Bash(npm publish *)",
      "Bash(rm -rf *)"
    ]
  }
}

High Risk（本番運用）

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Glob",
      "Grep",
      "LS"
    ],
    "denyTools": [
      "Bash(git push *)",
      "Bash(git checkout main)",
      "Bash(rm -rf *)",
      "Bash(docker *)",
      "Bash(kubectl *)",
      "Bash(ssh *)",
      "Bash(scp *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

settings.jsonとCLAUDE.mdの併用が重要な理由

settings.jsonだけでは「なぜその操作が禁止されているか」がClaudeに伝わりません。CLAUDE.mdで理由を自然言語で説明することで、Claudeは禁止操作の意図を理解し、類似の危険な操作も自発的に避けるようになります。

5. 実際に事故りかけた体験談とCLAUDE.mdで防げた理由

事故りかけたケース：本番DBへのマイグレーション未遂

あるチーム開発プロジェクトで、CLAUDE.mdを整備する前のことです。

状況：

Claude Codeに「ユーザーテーブルにプロフィール画像カラムを追加して」と指示しました。Claudeは以下を順に実行しました。

  1. マイグレーションファイルを生成 ✅
  2. モデルファイルを更新 ✅
  3. npx prisma migrate deployを実行しようとした 🚨

幸い確認プロンプトが表示されたので止められましたが、もしallowedToolsにBash(npx *)をワイルドカードで許可していたら、本番接続用の.envが読み込まれた状態でマイグレーションが走るところでした。

CLAUDE.mdで防げた理由

この事故の後、以下をCLAUDE.mdに追記しました。

## データベース操作のルール
- マイグレーションファイルの「生成」は許可する
- マイグレーションの「実行」（migrate deploy / migrate dev）は禁止
- 実行は開発者が手動で行う。理由：接続先DBの確認が必要なため

さらにsettings.jsonにも追加しました。

{
  "permissions": {
    "denyTools": [
      "Bash(npx prisma migrate deploy*)",
      "Bash(npx prisma migrate dev*)",
      "Bash(npx prisma db push*)"
    ]
  }
}

二重防御がポイントです。 settings.jsonで機械的にブロックし、CLAUDE.mdで理由を説明する。こうすることで、Claudeは「prisma migrateは使えないから、代わりにマイグレーションファイルを生成してユーザーに実行を案内する」という正しい行動を選択するようになりました。

もうひとつの教訓：git push --force

別の場面では、リベース後に「プッシュして」と気軽に頼んだところ、git push --force origin mainを提案されたこともあります。mainブランチへの--forceは壊滅的です。

## Git操作のルール
- git pushは一切自動実行しないこと
- force pushは絶対に提案しないこと
- ブランチ名にmain/develop/releaseが含まれる場合、直接コミットを禁止

これを書いてからは、Claudeは必ず「pushの準備ができました。以下のコマンドを手動で実行してください」と案内するようになりました。

6. コピペで使えるテンプレートリポジトリ紹介

公式リソース

Anthropicの公式ドキュメントにCLAUDE.mdのベストプラクティスが記載されています。

最小構成テンプレート

まず始めるなら、この最小構成から始めてください。

# CLAUDE.md

## プロジェクト概要
（1〜2行でプロジェクトの説明）

## 技術スタック
（使用言語・フレームワーク・DB）

## コーディング規約
（命名規則・フォーマッタ・リンター）

## 許可事項
- （箇条書きで列挙）

## 確認が必要な操作
- （箇条書きで列挙）

## 禁止事項
- （箇条書きで列挙）

段階的に育てるのがコツ

CLAUDE.mdは最初から完璧にしなくていいです。運用しながら以下のサイクルで育てましょう。

  1. 最小構成で始める
  2. Claudeに危ない操作をされたら、そのルールを追記する
  3. チームメンバーから「Claudeにこれやられて困った」と報告があれば追記する
  4. 月1回、不要になったルールを整理する

まとめ

  • **CLAUDE.mdは「AIへの業務命令書」**であり、Claude Code導入時に最初に書くべきファイル。settings.jsonとの二重防御で事故を防ぐ
  • 権限レベルは3段階（個人/チーム/本番）で設計する。リスクが上がるほどautoモードの許可範囲を狭め、禁止事項を厳格にする
  • CLAUDE.mdは育てるもの。最小構成から始めて、実際の事故・ヒヤリハットを元にルールを追加していくのが最も実践的

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?