Claude Codeの自走制御とベストプラクティス【2025年版】¶

Claude Codeが自走しすぎてルールを守らない問題を解決する最新の制御方法と、効果的なCLAUDE.mdファイルの書き方を解説します。実際の開発現場で使える実践的なテクニックを網羅的に紹介します。

記事の位置づけ

本記事: CLAUDE.mdによる包括的なAI制御手法
自動実行ガイド: 権限設定の具体的な操作方法
権限管理概要: 企業レベルの権限システム戦略

📋 目次¶

Claude Codeの自走問題とは
CLAUDE.mdファイルによる制御
効果的な指示の書き方
実践的な制御テクニック
チーム開発での運用方法
トラブルシューティング

Claude Codeの自走問題とは¶

よくある問題¶

Claude Codeを使っていると、以下のような「自走しすぎ」の問題が発生することがあります：

✋ 指示を無視して勝手にコードを変更
✋ 必要以上に多くのファイルを編集
✋ コーディング規約を守らない
✋ テストを実行せずにコミット
✋ 承認なしで重要な設定を変更

自走の危険性

Claude Codeは強力なツールですが、制御なしに使うと予期しない変更を行う可能性があります。適切な制御メカニズムの設定が重要です。

なぜ自走問題が起きるのか¶

コンテキスト不足: プロジェクトのルールが十分に伝わっていない
曖昧な指示: 具体性に欠ける指示により、Claude独自の判断で動作
設定不備: CLAUDE.mdファイルの設定が不完全
権限設定: 自動承認モードの不適切な使用

CLAUDE.mdファイルによる制御¶

CLAUDE.mdファイルとは¶

CLAUDE.mdはClaude Codeが自動的にコンテキストに読み込む特別なファイルです。プロジェクトのルール、制約、ワークフローを定義することで、Claudeの動作を制御できます。

ファイル配置場所¶

プロジェクト/
├── CLAUDE.md              # プロジェクト全体のルール
├── CLAUDE.local.md        # ローカル固有の設定（gitignore推奨）
├── src/
│   └── CLAUDE.md          # srcディレクトリ固有のルール
└── docs/
    └── CLAUDE.md          # docsディレクトリ固有のルール

基本的なCLAUDE.mdテンプレート¶

# CLAUDE.md - プロジェクト制御ファイル

## 🚨 重要な制約

### 必須承認事項
以下の操作は**必ず事前に確認**してから実行すること：
- パッケージの追加・削除
- 設定ファイルの変更（package.json、tsconfig.json等）
- データベーススキーマの変更
- 本番環境に影響する変更

### 禁止事項
- `.env`ファイルの作成・変更
- `node_modules`内のファイル編集
- テストを実行せずにコミット
- 承認なしでのPRマージ

## 🔧 開発ワークフロー

### コマンド一覧
```bash
# 開発サーバー起動
npm run dev

# テスト実行
npm run test

# 型チェック
npm run typecheck

# リント修正
npm run lint:fix

# ビルド
npm run build

必須手順¶

コード変更後は必ずnpm run typecheckを実行
テストが通ることを確認
リント違反がないことを確認
変更内容を説明

📝 コーディング規約¶

TypeScript¶

ES modules（import/export）を使用、CommonJS（require）は禁止
インポートは可能な限り分割代入を使用
型定義は明示的に記述

React¶

関数コンポーネントを使用
Hooksの順序を守る
propsの型定義は必須

ファイル構成¶

コンポーネントはsrc/components/配下
ユーティリティはsrc/utils/配下
型定義はsrc/types/配下

🧪 テスト方針¶

テスト実行順序¶

単体テスト（Jest）
結合テスト（Testing Library）
E2Eテスト（Playwright）

必須テストカバレッジ¶

新規機能は80%以上

重要な関数は100%

### 高度な制御設定

```markdown
# 高度なCLAUDE.md設定例

## 🤖 AI動作制御

### 思考モード
- 複雑な変更の前に「think hard」を使用
- アーキテクチャ変更時は「ultrathink」を使用

### 段階的実行
大きな変更は以下のステップで実行：
1. 変更計画の提示と承認待ち
2. 影響範囲の分析
3. テスト戦略の策定
4. 段階的実装

### 自動承認の制限
以下の場合は自動承認を無効化：
- 複数ファイルの同時変更（3ファイル以上）
- 設定ファイルの変更
- 依存関係の変更

## 🔍 品質チェック

### 変更前チェックリスト
- [ ] 既存テストが通ることを確認
- [ ] 型エラーがないことを確認
- [ ] リント違反がないことを確認
- [ ] セキュリティ脆弱性がないことを確認

### 変更後チェックリスト
- [ ] 新しいテストを追加
- [ ] ドキュメントを更新
- [ ] 変更ログを記録
- [ ] レビューリクエストを作成

## 📋 プロジェクト固有ルール

### データベース
- マイグレーションファイルは手動作成
- SEEDデータの変更は本番環境確認後

### API
- エンドポイントの追加はAPI設計書更新必須
- 後方互換性を保つ

### セキュリティ
- 認証が必要な機能は必ずテスト
- ユーザー入力のサニタイズ必須

効果的な指示の書き方¶

具体的で明確な指示¶

❌ 悪い例：

ログイン機能を作って

✅ 良い例：

ログイン機能を以下の仕様で作成してください：

1. components/auth/LoginForm.tsxを作成
2. email/passwordでの認証
3. バリデーション：email形式チェック、パスワード8文字以上
4. 送信中はローディング状態を表示
5. エラーハンドリング実装
6. テストファイルも同時作成
7. 変更後はnpm run testとnpm run typecheckを実行

制約と優先順位の明示¶

## 指示例：新機能追加

### 要件
- ユーザープロフィール編集機能の追加

### 制約
- 既存のUserコンポーネントは変更しない
- APIエンドポイントは/api/users/:idを使用
- 画像アップロードは今回対象外

### 優先順位
1. 基本的な編集機能（名前、メール）
2. フォームバリデーション
3. エラーハンドリング
4. テストの追加

### 完了条件
- [ ] フォームが正常に動作する
- [ ] バリデーションが機能する
- [ ] テストカバレッジ80%以上
- [ ] 型チェックが通る

3. Claude Code Hooksによる高度な制御¶

Hooksとは¶

Claude Code Hooksは、Claude Codeのライフサイクルの特定の時点でシェルコマンドを実行できる機能です。これにより、ツールの使用を制御し、ワークフローをカスタマイズできます。

利用可能なHookイベント¶

PreToolUse: ツール実行前に起動
PostToolUse: ツール完了後に起動
Notification: 通知時に起動
Stop: メインエージェント終了時に起動
SubagentStop: サブエージェント完了時に起動

Hooks設定例¶

基本的な設定構造¶

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "log-bash-command.sh"
          }
        ]
      }
    ]
  }
}

実用的なHooksの例¶

1. コード変更の自動フォーマット

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write {file_path} || true"
          }
        ]
      }
    ]
  }
}

2. 危険なコマンドのブロック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "check-dangerous-commands.sh"
          }
        ]
      }
    ]
  }
}

3. 変更の自動ログ記録

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[{timestamp}] Modified: {file_path}' >> claude-code.log"
          }
        ]
      }
    ]
  }
}

Hooksのベストプラクティス¶

セキュリティを最優先に
Hooksはフルユーザー権限で実行されるため、慎重に設計する
不明なコマンドや外部スクリプトは実行しない
エラーハンドリング
|| trueを使用してエラーでも継続できるようにする
重要な処理は別途ログを出力する
パフォーマンスへの配慮
重い処理は避ける
非同期処理を活用する
段階的な導入
まず通知やログから始める
徐々に制御を強化していく

4. 実践的な制御テクニック¶

段階的な承認システム¶

# CLAUDE.md内の段階的承認設定

## 承認レベル

### レベル1（自動実行可能）
- スタイルの調整
- コメントの追加
- 軽微なバグ修正

### レベル2（簡易承認）
- 新しい関数の追加
- 既存機能の拡張
- テストの追加

### レベル3（詳細確認必要）
- 複数ファイルの変更
- アーキテクチャの変更
- 依存関係の変更
- 設定ファイルの変更

### レベル4（必須承認）
- データベーススキーマの変更
- セキュリティ関連の変更
- 本番環境への影響がある変更

チェックポイントの設定¶

# .claude/checkpoints.md

## 必須チェックポイント

### コード変更前
1. git status で未コミット変更を確認
2. 現在のブランチを確認
3. テストが全て通ることを確認

### コード変更中
1. 3ファイル以上変更する場合は事前報告
2. 重要な関数変更時は影響範囲を分析
3. 新しい依存関係追加時は理由を説明

### コード変更後
1. npm run test の実行
2. npm run typecheck の実行
3. git diff でレビュー
4. コミットメッセージの確認

自動承認モードの制御¶

// claude-config.js（設定例）
module.exports = {
  autoApprove: {
    // 自動承認を許可するファイルパターン
    allowedFiles: [
      'src/**/*.test.ts',
      'src/**/*.spec.ts',
      'docs/**/*.md'
    ],
    // 自動承認を禁止するファイルパターン
    blockedFiles: [
      'package.json',
      'tsconfig.json',
      '.env*',
      'database/**/*'
    ],
    // 自動承認の最大ファイル数
    maxFiles: 2,
    // 自動承認の最大変更行数
    maxLines: 50
  }
};

チーム開発での運用方法¶

チーム共有CLAUDE.md¶

# team-claude.md

## チーム開発ルール

### コミット規約
- feat: 新機能
- fix: バグ修正
- docs: ドキュメント更新
- style: コードスタイル
- refactor: リファクタリング
- test: テスト追加

### ブランチ戦略
- main: 本番環境
- develop: 開発環境
- feature/*: 機能開発
- hotfix/*: 緊急修正

### レビュープロセス
1. PRテンプレートに従って記述
2. 最低1人の承認が必要
3. CIが通ってからマージ

### Claude使用時の注意
- 個人のCLAUDE.local.mdで個別設定
- チーム設定は変更前に相談
- 重要な変更は必ずレビューを通す

個人設定ファイル¶

# CLAUDE.local.md（個人用、gitignore対象）

## 個人設定

### 開発環境
- Node.js: v20.x
- エディタ: VS Code
- ターミナル: iTerm2

### 個人的な制約
- 午後6時以降は本番環境への変更禁止
- 金曜日は大きなリファクタリング禁止
- 休暇前は新機能開発停止

### よく使うコマンド
```bash
# 個人用ショートカット
alias ctest="npm run test -- --watch"
alias cbuild="npm run build && npm run typecheck"

## トラブルシューティング

### よくある問題と解決方法

#### 1. Claude が指示を無視する

**原因：**
- CLAUDE.mdの記述が曖昧
- 複数の相反する指示

**解決方法：**
```markdown
# CLAUDE.md改善例

## 🚨 最優先ルール（他の指示より優先）
1. テストを破壊しない
2. 型エラーを発生させない
3. 設定ファイルは承認なしで変更しない

## 判断に迷った場合の行動
1. 変更を停止
2. 現在の状況を報告
3. 詳細な指示を求める

2. 自動承認で予期しない変更¶

原因： - 自動承認の範囲が広すぎる - チェック機能が不十分

解決方法：

# 自動承認制限の強化

## 自動承認条件
以下の全てを満たす場合のみ自動承認：
- 変更ファイル数が2個以下
- 変更行数が20行以下
- テストファイルまたはドキュメントのみ
- package.jsonや設定ファイルは含まない

## 確認フロー
1. git diff で変更内容を表示
2. 5秒待機
3. ユーザーに確認を求める

3. パフォーマンスの問題¶

原因： - CLAUDE.mdが長すぎる - 不要な情報が多い