はじめに
本記事は、ShrivuさんのHow I Use Every Claude Code Featureを参考に、Claude Codeの機能と実践的な使い方を日本語で解説したものです。
重要: 元記事で紹介されているClaude Code SDKがclaude-agent-sdkに名称変更されるなど、破壊的変更を含む機能更新がありました。本記事では公式ドキュメントに基づき、最新の情報に更新しています。元記事のコードをそのまま使用すると動作しない場合があります。
「Claude Codeを使い始めたけど、基本的な使い方しか知らない…」
AnthropicのClaude Codeは、CLI(コマンドライン)で動作するAIコーディングアシスタントです。Cursor、Codex CLI、Gemini CLIなど競合ツールが多い中、Claude Codeは強力な拡張機能とエンタープライズ向けの運用機能で差別化されています。
本記事では、月間数十億トークンを消費するプロフェッショナル開発チームでClaude Codeを運用しているShrivuさんの知見を元に、以下を解説します:
- Claude Codeの主要機能の全体像
-
CLAUDE.mdの効果的な書き方 - Hooks、MCP、Subagentsなどの実践的な活用方法
- GitHub Actionsでの自動化
Claude Codeの主要機能
Claude Codeは単なるコード生成ツールではありません。以下の機能を組み合わせることで、個人開発から大規模チーム開発まで対応できます:
コア機能
- CLAUDE.md - プロジェクト固有の設定とガイドライン
-
コンテキスト管理 (
/context) - トークン使用量の可視化 - カスタムスラッシュコマンド - プロジェクト固有のタスク自動化
拡張機能
- Hooks - イベント駆動の自動化(ツール実行前後の処理)
- Subagents - 複雑なタスクの委譲
- MCP (Model Context Protocol) - 外部ツールとの統合
運用機能
- Claude Code SDK - Pythonスクリプトからの呼び出し
- GitHub Actions - CI/CDパイプラインでの自動化
それでは、各機能を具体的に見ていきましょう。
CLAUDE.md:最も重要なファイル
CLAUDE.mdは、あなたのリポジトリにおけるClaude Codeの憲法です。このファイルに、プロジェクト固有のルールやベストプラクティスを記述します。
基本的な考え方
Shrivuさんのチームでは、以下のような哲学でCLAUDE.mdを管理しています:
個人プロジェクト
- Claudeに自由に書かせる
- 実験的な使い方もOK
エンタープライズモノレポ
- 厳密に管理(現在13KB、最大25KBを想定)
- 30%以上のエンジニアが使うツールのみ記載
- 各ツールに「トークン枠」を割り当て(広告スペースのような管理)
ベストプラクティス
1. ガードレールから始める
最初から網羅的なマニュアルを書かない。Claudeが間違えた箇所を記録していく。
# Python
## テスト実行
- 常に `pytest tests/` を使用
- `python -m unittest` は使用しない(理由: カスタム設定が読み込まれない)
## 依存関係管理
- パッケージ追加時は `poetry add <package>` を使用
- `pip install` は使用しない
私の環境: 私はpoetryの代わりにuvを使用しています。uvはRustで書かれた高速なPythonパッケージマネージャーで、poetryと同様の依存関係管理が可能です(uv add <package>)。
2. @-File Docsを避ける
別ファイルに詳細ドキュメントがある場合、@path/to/docs.mdで参照したくなりますが、これはコンテキストウィンドウを圧迫します。
悪い例:
詳細は @docs/deployment.md を参照
良い例:
デプロイ時は `./deploy.sh production` を実行。
エラーが発生した場合や高度な設定が必要な場合は、
docs/deployment.md を参照してトラブルシューティング。
Claudeがなぜ・いつそのファイルを読むべきかを明示的に伝えます。
3. "Never"だけを言わない
「〜を使うな」だけでは、Claudeが代替手段を見つけられず行き詰まります。
悪い例:
- `--force` フラグは使用しない
良い例:
- `--force` フラグは使用しない
- 代わりに `--confirm` を使用してユーザー確認を取る
4. CLAUDE.mdを強制関数として使う
複雑なCLIコマンドを長々と説明するのではなく、シンプルなラッパースクリプトを作り、それを記載します。
CLAUDE.mdを簡潔に保つことが、ツール自体の改善につながります。
サンプル構成
# モノレポ
## Python
- 常に `uv run python` を使用
- テストは `uv run pytest tests/` で実行
... 10項目ほど ...
## 内部CLIツール
... 80%のユースケースに焦点を当てた10項目 ...
- 使用例: `<command> --param value`
- 常に <X> を使用
- <X>ではなく<Y>を優先
複雑な使用方法や<特定のエラー>の場合は、
path/to/<tool>_docs.md を参照。
AGENTS.mdとの互換性
AGENTS.mdファイルと同期することで、他のAI IDE(Cursor、Codex CLIなど)を使うチームメンバーとの互換性を保ちます。
私の実践: 私はAGENTS.mdを作成し、CLAUDE.mdとGEMINI.mdをシンボリックリンクとして作成しています。これにより、Claude Code、Cursor、Gemini CLIなど、どのツールでも同じガイドラインを参照できます。
# AGENTS.mdを作成後、シンボリックリンクを作成
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
重要: CLAUDE.mdは「高レベルのガードレールとポインタのキュレーション」として扱います。包括的なマニュアルではなく、AIフレンドリーなツール設計への投資先を示すガイドです。
コンテキスト管理:/context
Claude Codeは200kトークンのコンテキストウィンドウ(Sonnet 4では最大1Mトークン)を持ちますが、実際に全体が効果的に使われているかは疑問です。
/contextコマンド
セッション中に /context を実行すると、現在のトークン使用量が表示されます:
各要素の説明:
- System prompt: Claude Codeのシステムプロンプト
- System tools: 組み込みツールの定義
- MCP tools: 接続されているMCPサーバーのツール
- Memory files: CLAUDE.mdなどのメモリファイル
- Messages: 会話履歴(紫色の部分)
- Free space: 利用可能な空き容量
- Autocompact buffer: 自動圧縮のバッファ
Shrivuさんのチームのモノレポでは:
- 新規セッション開始時:約20k tokens(10%)
- 残り180k tokensで実装作業
数分〜数時間の作業で、メッセージ履歴(紫の部分) がどんどん溜まります。適宜クリアして空き容量を確保する必要があります。
コンテキストウィンドウはディスクスペースのようなもの。作業を進めると埋まっていくので、定期的に/contextでチェックしましょう。
カスタムスラッシュコマンド
.claude/commands/ディレクトリにMarkdownファイルを配置することで、プロジェクト固有のスラッシュコマンドを作成できます。
作成方法
-
.claude/commands/review-pr.mdを作成 - 以下のような内容を記述:
---
description: PRのコードレビューを実行
---
現在のブランチの変更内容をレビューしてください:
1. `git diff main...HEAD`で変更を確認
2. 以下の観点でレビュー:
- バグやエラーハンドリングの問題
- パフォーマンス上の懸念
- コーディング規約の遵守
3. 改善提案をMarkdown形式で出力
-
/review-prで実行
実用例
デプロイ前チェック:
---
description: デプロイ前の最終確認
---
1. テストが全てパスしているか確認
2. CHANGELOG.mdが更新されているか確認
3. バージョン番号が適切か確認
4. 本番環境の設定ファイルをチェック
ドキュメント生成:
---
description: APIドキュメントを自動生成
---
現在のディレクトリのPythonファイルから、
OpenAPI仕様書を生成してください。
高度な機能
カスタムスラッシュコマンドは、引数を受け取ることができます:
引数の使い方:
---
description: 指定されたファイルのテストを生成
argument-hint: [file_path]
---
`\\$1` のファイルに対するユニットテストを作成してください。
すべての引数: `\\$ARGUMENTS`
Bashコマンドの実行:
---
description: 現在のgit状態を確認
---
現在のgit状態:
!`git status`
上記の状態から、次に何をすべきか提案してください。
ファイル参照:
---
description: ヘルパー関数をレビュー
---
@src/utils/helpers.js のコードをレビューしてください。
元記事で紹介されていない新たな機能
以下の機能は、元記事執筆後に追加または強化されたものです。公式ドキュメントに基づいて解説します。
Plugin Commands:
プラグインから提供されるコマンドも利用できます。プラグインをインストールすると、そのコマンドが自動的に使用可能になります。
# プラグインのコマンドを実行
/plugin-name:command-name
# 名前衝突がない場合は短縮形も可能
/command-name
MCP Slash Commands:
MCPサーバーが提供するプロンプトも、スラッシュコマンドとして自動的に利用可能になります。
# MCPサーバーのコマンド形式
/mcp__<server-name>__<prompt-name> [arguments]
# 例: GitHubのPRをレビュー
/mcp__github__pr_review 456
SlashCommand Tool:
Claudeが必要に応じて自動的にスラッシュコマンドを実行する機能です。CLAUDE.mdでコマンドを参照すると、Claudeが適切なタイミングで自動実行します。
# CLAUDE.mdの例
ユニットテストを書く際は /write-unit-test コマンドを使用してください。
カスタムコマンドは、チーム共通のワークフローを標準化するのに最適です。
Hooks:イベント駆動の自動化
Hooksは、Claude Codeのツール実行前後に自動的にスクリプトを実行する機能です。
セキュリティ警告: Hooksは自動的に実行されるため、悪意のあるHooksコードはデータを漏洩させる可能性があります。Hooksを登録する前に、必ず実装内容を十分にレビューしてください。
設定方法
settings.jsonで設定:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "./hooks/before-bash.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "./hooks/after-edit.sh"
}
]
}
]
}
}
実用例
例1: セキュリティチェック
#!/bin/bash
# hooks/before-bash.sh
# ツール情報はstdin経由でJSONとして受け取る
input=$(cat)
# jqで情報を抽出
tool_name=$(echo "$input" | jq -r '.tool')
command=$(echo "$input" | jq -r '.input.command // empty')
# 本番環境への操作を検証
if [[ "$command" == *"production"* ]]; then
echo "⚠️ 本番環境への操作を検出: $command" >&2
echo "続行しますか? (y/n)" >&2
read -r response </dev/tty
if [[ "$response" != "y" ]]; then
exit 1 # 実行をブロック
fi
fi
例2: 自動テスト実行
#!/bin/bash
# hooks/after-edit.sh
# ツール情報をstdinから取得
input=$(cat)
# ファイルパスを抽出
file_path=$(echo "$input" | jq -r '.input.file_path // empty')
# Pythonファイルが変更されたらテストを実行
if [[ "$file_path" == *.py ]]; then
echo "🧪 テストを実行中..." >&2
pytest "$file_path" 2>&1 || echo "❌ テスト失敗" >&2
fi
例3: コスト追跡
#!/bin/bash
# hooks/after-tool.sh
# ツール情報をstdinから取得
input=$(cat)
# ツール名と使用トークン数を抽出
tool_name=$(echo "$input" | jq -r '.tool')
tokens=$(echo "$input" | jq -r '.usage.total_tokens // 0')
# API使用量をログに記録
echo "$(date '+%Y-%m-%d %H:%M:%S'),${tool_name},${tokens}" >> ~/.claude/usage.log
Hooksはガードレールや監査ログとして非常に強力です。
MCP (Model Context Protocol)
MCPは、Claude Codeが外部ツールと統合するための標準プロトコルです。
主要なMCPサーバー
公式提供:
-
@modelcontextprotocol/server-brave-search- Web検索 -
@modelcontextprotocol/server-filesystem- ファイルシステム操作 -
@modelcontextprotocol/server-github- GitHub API
サードパーティ:
- Playwright MCP - ブラウザ自動化
- Postgres MCP - データベース操作
- Slack MCP - Slack通知
設定方法
~/.config/claude/mcp.json:
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key"
}
}
}
}
使い方
MCPサーバーを設定後、Claudeに指示するだけ:
「最新のPython 3.13の新機能をBrave Searchで調べて、まとめてください」
Claude Codeが自動的にMCPサーバーを使用して検索します。
MCPは、Claude Codeを「閉じた環境」から「外部データとツールにアクセスできるエージェント」に変えます。
Subagents:独立コンテキストでのタスク分割
Subagentsは、専門化されたAIアシスタントです。各subagentは独立したコンテキストウィンドウを持ち、特定のタスク向けにカスタマイズされたシステムプロンプトと選択されたツールで設定されます。
作成方法
.claude/agents/にMarkdownファイルを作成:
---
name: code-reviewer
description: コードレビューが必要なとき自動で使用
tools: Read, Grep, Glob
model: sonnet
---
あなたは経験豊富なコードレビュアーです。以下の観点でコードをレビューしてください:
1. コード構造と可読性
2. エラーハンドリング
3. パフォーマンス上の懸念
4. セキュリティ問題
5. テストカバレッジ
レビュー時は、Read、Grep、Globツールを使用してコードベース全体を調査してください。
Subagentの優先順位
元記事には明記されていませんが、公式ドキュメントによれば、同じ名前のSubagentが複数の場所に定義されている場合、以下の優先順位が適用されます:
-
Project subagents (
.claude/agents/) - 最優先 -
CLI-defined subagents (
--agentsフラグ) - 中優先 -
User subagents (
~/.claude/agents/) - 最低優先
プロジェクト固有のSubagentが、ユーザー全体の設定を上書きします。
使い方
自動委譲:
Claudeがdescriptionフィールドとタスク内容から自動判定して使用します。
明示的呼び出し:
「code-reviewerサブエージェントを使って変更をチェックしてください」
CLI経由の一時利用:
claude --subagent "tests/フォルダ内の全テストを修正して"
使用シーン
大規模リファクタリング:
- メイン: アーキテクチャ設計
- Subagent 1: バックエンドの実装
- Subagent 2: フロントエンドの実装
並行作業:
- メイン: 新機能の実装
- Subagent: ドキュメント更新
隔離されたコンテキスト:
- メイン: 複雑な問題のデバッグ(多くのファイルを参照)
- Subagent: 単純なテスト追加(クリーンなコンテキスト)
Subagentsは、コンテキストウィンドウの限界を回避し、タスクを論理的に分割するのに役立ちます。
Claude Agent SDK:プログラマティックな使用
名称変更: Claude Code SDKはclaude-agent-sdkに改名されました。コーディングだけでなく、あらゆるタイプのAIエージェント構築に対応しています。
パッケージ名の変更:
-
TypeScript:
@anthropic-ai/claude-code→@anthropic-ai/claude-agent-sdk -
Python:
claude-code-sdk→claude-agent-sdk
Claude Agent SDKを使うと、PythonスクリプトからClaudeをプログラマティックに呼び出せます。
インストール
# Python
pip install claude-agent-sdk
# TypeScript
npm install @anthropic-ai/claude-agent-sdk
主要な変更点 (Breaking Changes)
Breaking Changes: 旧SDKから移行する場合、以下の破壊的変更に注意してください。既存コードは動作しなくなります。
Pythonの変更:
-
ClaudeCodeOptions→ClaudeAgentOptions - システムプロンプトのデフォルト:
claude_code→agent_mode - 設定ソースの読み込みが変更
TypeScriptの変更:
-
ClaudeCode→ClaudeAgent - インポートパスが変更
基本的な使い方
from claude_agent_sdk import query, ClaudeAgentOptions
# オプション設定
options = ClaudeAgentOptions(
working_dir="/path/to/project",
settingSources=["project"], # プロジェクト設定を読み込む
systemPrompt={
"type": "preset",
"preset": "claude_code" # Claude Codeのシステムプロンプトを使用
}
)
# タスクを実行
result = query(
"tests/フォルダの全テストを修正して、レポートを生成",
options=options
)
print(result)
実用例
例1: バッチ処理
from claude_agent_sdk import query, ClaudeAgentOptions
# 複数のリポジトリを一括処理
repos = ["repo1", "repo2", "repo3"]
for repo in repos:
options = ClaudeAgentOptions(
working_dir=f"/projects/{repo}",
settingSources=["project"]
)
query("依存関係を最新版にアップデート", options=options)
query("テストを実行して結果を保存", options=options)
例2: 内部チャットツール
from claude_agent_sdk import query, ClaudeAgentOptions
def designer_tool(prompt: str, framework: str = "react"):
"""デザイナー向けのコード生成ツール"""
options = ClaudeAgentOptions(
working_dir="/design-workspace",
systemPrompt="あなたはUIデザイン実装の専門家です"
)
result = query(
f"{framework}で以下のUIを実装:{prompt}",
options=options
)
return result
非技術者向けに簡単なインターフェースでAIコーディングを提供できます。
例3: エージェントプロトタイピング
from claude_agent_sdk import query, ClaudeAgentOptions
def threat_investigation_agent(alert_id: str):
"""セキュリティアラートを調査するエージェント"""
options = ClaudeAgentOptions(
working_dir="/security/investigations",
systemPrompt="あなたはセキュリティ分析の専門家です",
# MCPサーバーの設定はsettings.jsonで行う
settingSources=["user", "project"]
)
result = query(f"""
アラートID {alert_id} を調査:
1. Slackで関連する会話を検索(MCP経由)
2. GitHubで最近のコミットをチェック(MCP経由)
3. AWSログで異常を検出(MCP経由)
4. 調査レポートを生成
""", options=options)
return result
複雑なエージェントを本番フレームワークにコミットする前に、SDKで迅速にプロトタイプできます。
GitHub Actions:CI/CDでの自動化
Claude Code GitHub Action(GHA)は、おそらく最も注目されていない強力な機能と元記事で紹介されています(私も使っていませんでした)。
基本的な仕組み
GitHub Actions内でClaude Codeを実行します。シンプルですが、その柔軟性が強力です:
- 完全なコンテナ制御
- 強力なサンドボックス化
- 監査ログの完全な記録
- HooksとMCPのサポート
認証方法
元記事には記載されていませんが、Claude Code GitHub Actionは複数の認証方法をサポートしています:
-
Anthropic直接API -
anthropic_api_keyを使用(最も一般的) - Amazon Bedrock - AWS認証情報を使用
- Google Vertex AI - GCPサービスアカウントを使用
エンタープライズ環境では、既存のクラウドプロバイダーの認証を活用できます。
設定例
.github/workflows/claude-fix.yml:
name: Claude Auto Fix
on:
issue_comment:
types: [created]
jobs:
auto-fix:
if: contains(github.event.comment.body, '/claude-fix')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Claude Code
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: \\${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Issue #\\${{ github.event.issue.number }} を修正:
\\${{ github.event.issue.body }}
1. 問題を再現
2. 修正を実装
3. テストを追加
4. PRを作成
- name: Create Pull Request
uses: peter-evans/create-pull-request@v5
with:
title: "Fix: Issue #\\${{ github.event.issue.number }}"
body: "Claude Codeによる自動修正"
実用例
例1: Slackからのトリガー
Slack、Jira、CloudWatchアラートなど、どこからでもPRを作成できます:
on:
repository_dispatch:
types: [slack-command]
jobs:
handle-slack-command:
steps:
- name: Run Claude
run: |
claude --prompt "\\${{ github.event.client_payload.command }}"
例2: 定期的な改善
on:
schedule:
- cron: '0 0 * * 0' # 毎週日曜日
jobs:
weekly-improvements:
steps:
- name: Claude Code Review
run: |
claude --prompt "
過去1週間のコミットをレビューし、
改善できる箇所があればPRを作成
"
例3: データ駆動の改善ループ
# GHAログを分析し、共通エラーを修正
$ query-claude-gha-logs --since 5d | claude -p "
他のClaudeインスタンスが詰まっていた問題を確認し、
CLAUDE.mdやCLIツールを改善してPRを作成
"
これにより、バグ → CLAUDE.md改善 → より良いエージェントという自己改善サイクルが生まれます。
GHAは、Claude Codeを個人ツールからコアの監査可能で自己改善するエンジニアリングシステムに変えます。
settings.json:高度な設定
最後に、Shrivuさんが使用している重要なsettings.jsonの設定を紹介します。
{
// デバッグ用プロキシ
"HTTPS_PROXY": "http://localhost:8888",
"HTTP_PROXY": "http://localhost:8888",
// タイムアウトの延長
"MCP_TOOL_TIMEOUT": 300000,
"BASH_MAX_TIMEOUT_MS": 600000,
// エンタープライズAPIキー
"ANTHROPIC_API_KEY": "sk-ant-...",
// 自動許可コマンド(定期的に監査)
"permissions": {
"autoApprove": ["git status", "git diff", "pytest"]
}
}
重要な設定項目
HTTPS_PROXY / HTTP_PROXY
- Claude Codeが送信するプロンプトをインスペクト
- バックグラウンドエージェントのネットワークサンドボックス化
タイムアウト
- 長時間実行コマンドのため、デフォルトより大きく設定
- バックグラウンドタスク機能があるため、今は不要かもしれないが保険として維持
ANTHROPIC_API_KEY
- エンタープライズでは「シート制」の基本料金に「Extra Usage(使用量ベース)」を組み合わせた柔軟な価格設定を使用
- エンジニア間の使用量の大きな差(1:100倍)に対応
- Claude Code以外のLLMスクリプトも同じアカウントで実行可能
Anthropicの価格体系:
- Team/Enterpriseプラン: シート制が基本(Premium seat: $150/person/month)
- Extra Usage: シートの使用量上限を超えた場合、API料金($3/MTok for Sonnet 4.5 inputなど)で追加課金
- API直接利用: 完全な使用量ベース(シート不要)
元記事の著者のチームは、Enterpriseプランでシートを契約しつつ、Extra Usageを有効化することで、実質的に使用量ベースに近い運用をしていると考えられます。
permissions
- 定期的に自動承認コマンドのリストを監査
- 安全なコマンドのみ自動実行
まとめ
本記事では、Claude Codeの全機能を解説しました:
コア機能
- CLAUDE.md: ガードレールから始め、簡潔に保つ
-
コンテキスト管理:
/contextで定期的にチェック - カスタムコマンド: チーム共通のワークフローを標準化
拡張機能
- Hooks: セキュリティチェックや自動テストで強力なガードレール
- MCP: 外部ツールとの統合で能力を拡張
- Subagents: タスク分割でコンテキスト限界を回避
運用機能
- Claude Agent SDK: バッチ処理や内部ツール、エージェントプロトタイピング
- GitHub Actions: CI/CDで自動化、自己改善サイクルの構築
Claude Codeは単なるコード生成ツールではありません。適切に設定すれば、個人開発から大規模チームまで、AIを活用した開発を強力にサポートします。
もしまだCLI型エージェント(Claude CodeやCodex CLI)を使っていないなら、ぜひ試してみてください。これらの高度な機能を学ぶ唯一の方法は、実際に使ってみることです。
参考文献
- How I Use Every Claude Code Feature - Shrivu's Substack(元記事)
- Model Context Protocol (MCP) - MCP公式ドキュメント
- Claude Code GitHub Action - GitHubリポジトリ
