Claude Code 高度活用ガイド

1. ベーシックを超えた運用方法

Claude Code を単なるチャットボットと捉えるのをやめ、自律的なエージェントとして扱います。最も重要な原則は、Claude に自分の作業を検証させる仕組みを与えることです。

• フィードバックループの構築: Claude が動作するまで反復修正を繰り返すことで、品質が 2〜3 倍向上します。
• 運用のパターン変化:
  • 調べる → 計画する → コードを書く:

    • Shift+Tab

      を 2 回押して [Plan モード] を有効にします（読み取り専用）。
    • ファイル閲覧、フロー追跡、データモデル理解後、計画を立てて実行します。
    • 複数のファイルを変更する場合は必ず Plan モードを使用してください。
  • 設計書の活用:
    • 一度作成した計画は、別のセッションで「上級レビューヤー」として検証してもらいましょう。
    • 実装が狂った場合は、Plan モードに戻って再計画します。
  • 参照と委任の徹底:
    • ファイル名を指定（例:

      @src/auth/login.py

      ）して正確なコンテキストを提供します。
    • エラーログをパイプ処理（

      cat error.log | claude

      ）して伝えると効果的です。
    • 「ペアプログラミング」ではなく「担当業務の委任」を行い、簡潔なブリーフから始めます。
  • ミスの学習:
    • プロンプト末尾に 「このミスを繰り返さないよう Update CLAUDE.md を書き込んでください」 と指示します。

2.

.claude

ディレクトリ構造の理解

.claude/

ファイルごとの機能一覧

CLAUDE.md

CLAUDE.local.md

settings.json

settings.local.json

.mcp.json

skills/<name>/SKILL.md

commands/*.md

agents/*.md

rules/*.md

典型なディレクトリ構成

my-repo/
├── .claude/
│   ├── settings.json
│   ├── agents/pr-review.md, test-writer.md
│   ├── skills/api-conventions/SKILL.md
│   └── rules/frontend.md, migrations.md
├── CLAUDE.md                  # チーム共有（チェックイン済み）
├── CLAUDE.local.md            # 個人メモ（gitignore 対象）
└── .mcp.json                  # チーム共有 MCP サーバー

重要な運用ルール

• カスケード効果: モノレポの場合、

  root/CLAUDE.md

  と

  service/CLAUDE.md

  の両方が読み込まれます。
• パスゲートの活用:

  rules/*.md

  は特定のフォルダ（例:

  .claude/rules/migrations.md

  ）へのアクセス制御に有効です。
• スキルの優先: 再利用可能で複雑なタスクは

  skills/

  フォルダへ配置し、単純コマンドには

  commands/

  を使用します。
• ローカル状態のクリーンアップ: リポジトリを渡す前に

  claude project purge ~/path/to/repo --dry-run

  で確認してください。

3. CLAUDE.md ファイルの最適化

CLAUDE.md

書式と内容のポイント

1. 簡潔さ: 必要ない行を削ぎ落してください。「削除してもミスを犯さないか？」をチェックします。
2. 自己ルールの作成:
   • 「Update CLAUDE.md so you do not repeat this」を追加して、Claude に失敗からルールを学習させます。
   • 落とし穴（Gotchas）セクションは特に重要です。過去のミスを「キャプチャしたルール」として登録します。
3. 他ファイルのインポート:

   @path

   シンタックスで詳細を参照できます。

   @README.md        # プロジェクト概要
   @package.json     # スクリプト定義
   @~/.claude/my-preferences.md
   

参考テンプレート例

# Code style
- Use ES modules (import/export), not CommonJS (require)

# Workflow
- Always use `bun`, not `npm`
- Run `bun run typecheck` before claiming done
- Never push to main directly. Always open a PR.

# Architecture
- All API routes go through src/api/middleware/auth.ts
- New database queries go in src/db/queries/. No inline raw SQL.

# Gotchas
- `User` and `UserRecord` are distinct types.
- `formatCurrency` assumes USD. Use `formatCurrencyByLocale` for intl.

4. CLAUDE.local.md の活用

CLAUDE.local.md

.gitignore

• 使い方: PR レビューからのコメントや、自分のコーディング癖（例：

  console.log

  的使用など）を即座に記録します。
• 構造化: 「他者へのフィードバック」と「自らの修正ルール」を別セクションに分けてください。
• 効果: Claude は「auth-failure テストを含める」「OpenAPI を更新する」といったルールを記憶し、繰り返しミスを減らします。

# Personal review notes (private)

## From PR feedback
- New SQS consumers need a DLQ and alarms in the same PR
- Prefer named tuples over plain dicts for return types with 3+ fields

## My own quirks to correct
- Stop using `console.log`; use the project logger instead

5. スキルの導入と活用

スキルは「何でもできる」のではなく、「特定の領域で秀でた」エージェントに変えます。

skills/<name>/SKILL.md

スキルの構成要素

• Frontmatter:

  • description

    : 目的の説明

  • disable-model-invocation

    : サイドエフェクトがあるスキルに必須（例:

    /ship

    ）。

  • allowed-tools

    ,

    agent

    : 権限設定
• In-lineシェル:

  !command

  の形式で実行結果を出力できます。
• フォルダー構造: 単なるテキストではなく、テンプレートや設定ファイルをバンドル可能です。

実例：Go API コンベンションスキル

---
description: Scaffolds a new HTTP handler in our Go service...
disable-model-invocation: false
allowed-tools: Read, Grep, Bash
---

# Go HTTP Handler Skill

## Stack
- Go 1.22 with chi router
- sqlc for typed queries
- zap for structured logging

## Gotchas
- `chi.URLParam` returns `""` for missing params. Always check.

おすすめのスキルリポジトリ

• mattpocock/skills: 高評価のリポジトリ（10 万スター）。

  • /grill-me

    : インタビューを通じた計画と TDD の強制。

  • /diagnose

    : 再現化、仮説検証、最小化デバッグ。
• Jeffallan/claude-skills:

  go-pro

  ,

  python-pro

  など言語固有のスキル。
• Anthropic:

  /code-review

  ,

  /simplify

  ,

  /batch

  など。

ヒント: シンプルなタスクをスキルの呼び出しに変換（例: 「ファイルを見る」→

/diagnose

6. カスタムサブエージェントの構築

agents/*.md

実装例：PR リビューヤー (

/pr-review

)

---
name: pr-review
description: Reviews branch diff against main...
tools: Read, Grep, Glob, Bash
model: opus
---

## Process
1. Run `git diff main...HEAD`
2. Read full files, not just diff context
3. Cross-check against CLAUDE.md and rules/

## Flag (Critical)
- Correctness bugs (null handling, race conditions)
- Security issues (secrets, missing auth)
- Missing tests for new logic

設計のポイント

• リーダーのみ: コード変更を妨げるため、読み取り専用のツールを優先します。
• モデル: 高品質なレビューには

  opus

  モデルを使用します。
• ノイズの排除:

  Do NOT flag

  セクションで不要な指摘（スタイル好みなど）を明記し、精度を高めます。

おすすめのサブエージェント

• セキュリティ:

  security-reviewer

  ,

  verify-app

• テスト:

  test-writer

  （ペアプロでテスト生成）,

  /code-review

• その他:

  debugger

  ,

  performance-auditor

  ,

  migration-writer

7. プラグインとマーケットプレイス

プラグインは、スキルやエージェントをバンドルした単位です。

おすすめの Day-One プラグイン

• /code-review: 4 つのエージェントで信頼性をスコアリングし、バグやコンベンション違反を検出。
• **/feature-dev:**要件から実装・レビューまで一連の作業を自動で実行（最も人気）。
• 言語サーバープラグイン: エディタ側でのシンボルナビゲーションと診断を提供。
• /security-guidance: 出荷前のセキュリティチェックを実行。

カバー領域

Git ワークフロー、LSP、ドキュメント生成、テスト、ブラウザ自動化（Playwright）、デザインシステムなど。75 つ以上のマーケットプレイスに 1,000 以上のプラグインがあります。

8. 高度な CLI コマンド

/clear

/compact

/insights

/rewrite

/branch

/loop <interval>

/schedule

/focus

/voice

/bare

-p

コンテキスト最適化とファンアウト

• コン圧縮:

  CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000

  で設定。1M モデルでもシャープさを維持。
• シェルエスケープ:

  !git status

  など、コマンドの出力を即座にクロードに渡せます。

/goal

と自動モード

• /goal: 完了条件を設定（例: "all tests pass"）。Claude は条件満たすまで継続します。
• ペアリング:

  /goal

  + オートモード +

  /focus

  を組み合わせ、簡潔なブリーフで指示を出し忘れません。

9. MCP (Model Context Protocol) の活用

MCP は Claude に外部ツール（DB、エラー追跡器、デザインツールなど）へのアクセス権を与えます。

デファクトスタンダード

• GitHub: リポジトリ管理、PR/Issue 操作。
• Context7: ライブのライブラリドキュメント検索。
• Sentry: エラーコンテキストとスタックトレース。
• Linear: チケット読み込みとステータス更新。
• Postgres / Supabase: 直接 DB クエリ実行。
• Figma: ライブデザインツリーの取得。

接続方法（ローカル）

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

ヒント: MCP サーバーはリストを拡大するため、必要最小限で設定してください。

/mcp

Obsidian との連携ワークフロー

• ホットストレージ: 10-Daily フォルダにセッションログ。
• ウォームストレージ: 20-Projects フォルダにプロジェクトノート。
• コールドストレージ: 30-Decisions (ADR), 40-Atoms (知識)。
• Claude はプロジェクトの

  CLAUDE.md

  にフォルダ構造の説明を含めることで、長期コンテキストを維持します。

10. 最適化されたワークフローパターン

朝ルーティン

• プロジェクトを開き、サブエージェントやスケジューリングジョブの確認。

• /insights

  の実行（月 1 回）。

タスク別アプローチ

• 新規機能: Plan モード →

  Ctrl+G

  で調整 → 実装 →

  /pr-review

  。
• バグ修正: 再現性確認 (

  cat error.log | claude

  ) → テスト作成依頼 → 修正。
• 大規模変更:

  /batch

  コマンドで並列エージェントに分割し、各 Worktree でテスト・PR を作成。

ワイター/レビューヤーパターン

1. セッション A で実装。

2. Ctrl+G

   で計画を編集。
3. セッション B（新規）でレビュー。

4. /compact

   でコンテキストを整理し、ミレストーンとして保存。

重要なルール: Claude が「成功した」と主張する根拠（テスト通過やログ出力）がない場合は、信頼せず自分で検証してください。

11. チームのベストプラクティス

Boris と Anthropic チームが推奨する方法です。

• モデル: ほぼすべてに Opus を使用し、

  high

  または

  xhigh

  エフォート設定を推奨。
• 並列作業: 3〜5 セッションを worktree で同時に実行（

  claude --worktree

  ）。
• 知識の蓄積: プロジェクトごとにノートディレクトリを維持し、各 PR 後に更新。コードベース自体が自己学習型になります。
• デットコード対策:

  /techdebt

  スキルで重複コードを特定・削除。
• UI/UX: Playwright MCP でブラウザ動作を確認。Chrome エクステンションと連携。
• 音声入力:

  /voice

  コマンドを活用し、プロンプトの入力を加速。
• 図解化:

  asciidoctorj

  などを活用して、Claude にアーキテクチャを可視化させる（

  ASCII art

  ）。

12. リソースとまとめ

おすすめリポジトリ

• スキル:

  mattpocock/skills

  ,

  Jeffallan/claude-skills

• サブエージェント:

  VoltAgent/awesome-claude-code-subagents

• プラグイン:

  Chat2AnyLLM/awesome-claude-plugins

まとめ

Claude Code を「コードを書くためのツール」としてではなく、**「設定・トレーニング・運用するパートナー」**として扱うことで、成果は劇的に変わります。

1. CLAUDE.md は累乗するインフラ: ミスをルール化し、蓄積させます。
2. サブエージェントと並列セッション: コンテキストを分離し、品質を最大化します。
3. MCP の活用: 外部ツールとの統合でシステム全体を把握可能にします。

セットアップこそが最大の作業であり、その後の実行は主に検証と学習のプロセスです。