Claude Code の使い方実践ガイド — 導入・CLAUDE.md・Hooks・Auto-Fix を実務で解説

Claude Code を導入したいが、結局どこから触ればいいのか分からない。CLAUDE.md を書いたのに出力が安定しない。Auto-Fix や権限設定まで含めると情報が散らばっていて、何を先に学ぶべきか迷う。そんな人向けに、実務で必要な論点だけを一本に整理したのがこの記事です。

この記事では、導入初日にやる設定、普段の開発で効く運用、出力品質を崩しやすい落とし穴を順番に解説します。筆者自身がポートフォリオサイトの構築・ブログ運営・SEO改善で Claude Code を継続利用してきた前提で、「まず使える状態にする」「次に安定させる」「最後に自動化する」という流れでまとめました。

特に「Claude Code の使い方」を検索している人が詰まりやすいのは、単なるインストールよりも CLAUDE.md / Hooks / 権限 / Auto-Fix の切り分けです。この記事はそこを曖昧にせず、最初の30分で何を決めるかまで具体化します。

周辺機能を深掘りした記事もあります。CLAUDE.md の設計パターン集、Hooks の使い方ガイド、Claude Code Auto-Fix 実践ガイド、Harness Engineering 入門、Claude Code vs Codex CLI 徹底比較も必要に応じて参照してください。

Claude Code とは何ができるツールか

Claude Code は Anthropic が提供する CLI ネイティブの AI コーディングエージェント です。Copilot や Cursor のようなエディタ統合型とは根本的にアーキテクチャが異なります。

ターミナルで claude と打つだけで対話が始まり、ファイルの読み書き、シェルコマンドの実行、git 操作までをすべて自然言語で指示できます。重要なのは、Claude Code は質問に答えるチャットボットではなく、自律的に問題を解決するエージェントだということです。探索し、計画し、実装し、検証するという一連の流れを自分で回せます。

インストールと起動

# インストール（Node.js 18以上が必要）
npm install -g @anthropic-ai/claude-code

# 起動
claude

初回起動時に Anthropic アカウントとの認証が求められます。ブラウザが開くので、指示に従って認証を完了してください。

Claude Code を導入した初日にやること

インストールできたら、次はすぐに実務運用へ入る準備をします。ここを飛ばすと「動くけど安定しない」状態になりがちです。

最初の 30 分で決める 4 項目

使うプラン: まずは Pro でも始められますが、日常的にコードを書かせるなら使用量上限に早く当たります。継続利用前提なら Max を検討した方がよいです。
プロジェクトルールの置き場: ルール説明は CLAUDE.md、毎回強制したい処理は Hooks に分けます。ここを混ぜると運用が崩れます。
権限の基準: 危険な操作まで常時許可するのか、Auto Mode で中間を取るのかを決めます。チーム利用では曖昧にしない方がよいです。
検証コマンド: pnpm run build や pnpm run test のように、Claude が作業後に確認すべきコマンドを固定します。

最初に試すべきプロンプト

導入直後は、いきなり大規模実装よりも「このリポジトリを調査して、どのコマンドで開発・ビルド・テストするか整理して」と依頼する方が安全です。ここで Claude が正しくプロジェクト構造を把握できるかを見ると、CLAUDE.md に何を追加すべきかが見えます。

この段階で出力がふらつくなら、先に CLAUDE.md の設計パターン集と Harness Engineering 入門を読む価値があります。プロンプト改善より、制御の設計を直した方が早いケースが多いからです。

Claude Code と Copilot / Cursor の違い

AI コーディングツールの選択肢が増える中で、Claude Code を主力にした理由を整理します。

項目	GitHub Copilot	Cursor	Claude Code
思想	補助型 — タイピング中にインライン補完	協調型 — エディタ内で複数ファイルを一括編集	自律型 — ゴールを伝えると計画から実行まで自走
動作環境	VS Code / JetBrains 等	独自エディタ（VS Code fork）	ターミナル（エディタ不問）
得意領域	関数単位の高速な補完	IDE 内でのマルチファイル編集	プロジェクト横断の大規模変更、調査・リファクタ
カスタマイズ	`.github/copilot-instructions.md`	`.cursorrules`	`CLAUDE.md` + hooks + MCP + skills

Copilot は「速いオートコンプリート」、Cursor は「エディタの中の賢いコラボレーター」、Claude Code は「タスクを渡すと完了して返してくれる同僚」という表現がしっくりきます。

個人的には Claude Code + エディタ（VS Code）の併用 が最も効率的でした。大きな変更や調査は Claude Code に任せ、細かい微調整はエディタで直接行う。この使い分けがうまくハマります。

他の AI コーディングツールとの詳しい比較は Claude Code vs Codex CLI 徹底比較で解説しています。

料金体系とプラン選び

Claude Code を使うには Claude の有料プラン（Pro 以上）が必要です。

プラン	月額	Claude Code の利用
Free	$0	利用不可
Pro	$20	利用可能（通常の使用量制限内）
Max 5x	$100	Pro の 5 倍の使用量
Max 20x	$200	Pro の 20 倍の使用量
API 従量課金	使用量次第	1 人あたり平均 $6/日（公式発表）

日常的に使い込む場合は Max プランが安心です。API 従量課金は使用頻度にバラつきがある場合にコスト効率が良くなるケースがあります。

実務での選び方

毎日使う個人開発なら、まず Pro で試して利用量の感触をつかむ
日中ずっと並走させるなら、早めに Max 前提で見積もる
Auto-Fix や GitHub Actions まで広げるなら、サブスク枠と API 課金枠を分けて考える

Auto-Fix を本格運用するなら、Desktop 機能だけで済ませるのか、GitHub Actions まで含めるのかでコスト構造が変わります。詳細は Claude Code Auto-Fix 実践ガイドで整理しています。

コンテキスト管理 — 最も重要な概念

公式ドキュメントが最も強調しているのがコンテキストウィンドウの管理です。Claude Code の性能はここに直結します。

コンテキストウィンドウには、会話履歴、読み取ったファイルの内容、コマンドの出力がすべて蓄積されます。これがいっぱいになると、Claude は以前の指示を「忘れ」たり、ミスが増えたりします。

実践的な管理方法

/clear を頻繁に使う — 関連のないタスクに移る前にコンテキストをリセットする。これだけで品質が大きく変わります。

/compact で要約する — コンテキストが膨らんできたら /compact で会話を圧縮できます。/compact API変更に集中して のように焦点を指定することも可能です。

サブエージェントに調査を委譲する — Claude に「調査して」と頼むと大量のファイルを読み込んでコンテキストを消費します。代わりに サブエージェントを使って認証周りを調査して と指示すると、別のコンテキストで探索が行われ、メインの会話はクリーンに保たれます。

2回修正しても直らなかったら /clear — 同じ問題で2回以上修正を重ねたら、コンテキストが失敗した試行で汚染されています。/clear して学んだことを反映した新しいプロンプトで再スタートした方が速いです。

実務で効いた補足

長いログを貼る前に「このログのどこを見てほしいか」を一文添える
調査だけのタスクと実装タスクを同じ会話で混ぜすぎない
UI 修正ではスクリーンショット、CLI 修正では再現コマンドのように検証手段を必ず渡す

特に Auto-Fix や大規模リファクタでは、検証基準が曖昧だと Claude が「直したつもり」の差分を返しやすくなります。

CLAUDE.md — プロジェクトの憲法

CLAUDE.md はすべての会話の開始時に自動的に読み込まれる特別なファイルです。Claude がコードだけからは推測できない前提知識やルールを伝えます。

`/init` で始める

claude
> /init

/init コマンドを実行すると、プロジェクトのビルドシステム、テストフレームワーク、コードパターンを自動検出して CLAUDE.md の雛形を生成してくれます。ここから改善していくのが最も効率的です。

書くべきこと / 書くべきでないこと

書くべき	書くべきでない
Claude が推測できない Bash コマンド	コードを読めばわかること
デフォルトと異なるコードスタイルルール	標準的な言語規約
テスト実行方法と推奨テストランナー	詳細な API ドキュメント（リンクで十分）
ブランチ命名規則、PR の規約	頻繁に変わる情報
プロジェクト固有のアーキテクチャ決定	ファイルごとの詳細説明
よくある落とし穴や直感に反する挙動	「きれいなコードを書け」のような自明な指示

最も重要なのは簡潔さです。 各行について「これを削除したら Claude が間違いを犯すか？」と自問して、答えが No なら削除します。肥大化した CLAUDE.md は、重要なルールがノイズに埋もれて逆効果になります。

CLAUDE.md の具体的な設計パターンや実例テンプレートは CLAUDE.md の書き方設計パターン集で詳しく解説しています。「60行以下に収めるべき理由」や「CLAUDE.md vs Hooks の使い分け判断フロー」も掲載しているので、CLAUDE.md を本格的に運用したい方はあわせてご覧ください。

実務で書き足すと効く項目

よく使う開発コマンドと、そのプロジェクトでの正しい順番
触ってはいけないファイルやディレクトリ
PR の粒度やブランチ運用など、コードから推測できないチームルール
「調査だけなら書き込み禁止」のような運用ポリシー

逆に、一般的なコーディング規約まで書き込むのはやめた方がよいです。そこは Claude が元から知っています。

配置場所

CLAUDE.md は複数の場所に配置でき、それぞれスコープが異なります。

~/.claude/CLAUDE.md — すべてのプロジェクトに適用（個人設定）
./CLAUDE.md — プロジェクトルート（git にコミットしてチーム共有）
./CLAUDE.local.md — プロジェクトルート（.gitignore に追加して個人用）
子ディレクトリの CLAUDE.md — そのディレクトリ内のファイル操作時にオンデマンドで読み込まれる

モノレポでは親子ディレクトリに CLAUDE.md を階層的に配置するのが有効です。

効果的なワークフロー

探索 → 計画 → 実装 → コミット

公式が推奨する4フェーズのワークフローです。

1. 探索（Plan Mode）

Shift + Tab で Plan Mode に入ります。この状態では Claude はファイルを読むだけで変更を加えません。

認証周りの実装を調べて、セッション管理とログインの仕組みを理解して

2. 計画（Plan Mode のまま）

Google OAuth を追加したい。変更が必要なファイルは？セッションのフローは？計画を作って

3. 実装（Normal Mode に戻す）

計画に沿って OAuth フローを実装して。コールバックハンドラのテストを書いて、テストスイートを実行して失敗を修正して

4. コミット

変更内容を説明するコミットメッセージで commit して PR を作って

ただし、スコープが明確な小さい修正（タイポ修正、変数のリネームなど）では計画フェーズは不要です。差分を一文で説明できるなら、直接実行で問題ありません。

Claude にインタビューさせる

大きな機能を実装する前に、Claude に質問させると要件の抜け漏れを防げます。

[簡単な説明] を作りたい。技術的な実装、UI/UX、エッジケース、トレードオフについて詳しくインタビューして。自分が考えてなかったことも掘り下げて。

Claude が技術的な実装やエッジケースについて質問してくるので、それに答えていくと自然と仕様が固まります。仕様がまとまったら新しいセッションを立ち上げて実装に入ると、クリーンなコンテキストで集中できます。

検証手段を与える

公式が「最もレバレッジが高い」と言っているのが、Claude に自分の作業を検証させることです。

# NG: 検証手段なし
メールアドレスを検証する関数を実装して

# OK: テストケースを提示
validateEmail を書いて。テストケース：
user@example.com → true、invalid → false、user@.com → false
実装後にテストを実行して

テストだけでなく、UI 変更ならスクリーンショットの比較、ビルドの成功確認など、Claude が「正しい」と自己判断できる基準を与えると精度が劇的に上がります。

hooks — 確実に実行されるガードレール

CLAUDE.md のルールは「アドバイス」ですが、hooks は「確実に実行される」スクリプトです。例外なく毎回実行したい処理に使います。

主要なフックポイント

フック	タイミング	用途例
`PreToolUse`	ツール実行前	特定ファイルへの書き込みブロック、危険コマンドの防止
`PostToolUse`	ツール実行後	自動フォーマット、リンター実行
`SessionStart`	セッション開始時	環境チェック、コンテキスト注入

実践例: ファイル編集後に自動フォーマット

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ]
  }
}

実践例: 本番設定の保護

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '(\\.env|production)'; then echo 'BLOCKED: production config files are read-only' >&2; exit 2; fi"
      }
    ]
  }
}

exit code 2 で返すとアクションがブロックされ、stderr に書いた理由が Claude にフィードバックされます。Claude はそれを読んで別のアプローチに切り替えます。

Claude 自身に hooks を書かせることもできます。「ファイル編集後に eslint を実行するフックを書いて」と依頼すれば設定してくれます。

Hooks の設定方法や段階的な導入手順をさらに詳しく知りたい方は、Claude Code Hooks の使い方実践ガイドをご覧ください。実際にハマった5つの落とし穴と対策も紹介しています。

なお、CLAUDE.md と Hooks をどう使い分けるかは重要なポイントです。CLAUDE.md は「お願い」であり無視される可能性がありますが、Hooks は「強制」で例外なく実行されます。この使い分けの判断フローは Harness Engineering 入門で体系的に解説しています。

まず入れるべき Hooks

導入初期なら、いきなり複雑な Hook を増やす必要はありません。優先順位は次の順です。

編集後の自動フォーマット
危険コマンドや機密ファイル編集のブロック
セッション終了時の最低限の品質チェック

この順で入れれば、運用コストを抑えつつ効果だけ先に取れます。

権限管理 — Auto Mode と安全な運用

Claude Code はファイル編集やコマンド実行のたびに確認プロンプトを表示します。信頼できるプロジェクトでは --dangerously-skip-permissions や Auto Mode で確認を省略できますが、安易に全開放するとリスクがあります。

Auto Mode は権限プロンプトを AI が自動判定する仕組みで、「安全な操作は自動承認、危険な操作は確認」というバランスを取れます。詳しくは Claude Code Auto Mode 徹底解説で、権限設定のベストプラクティスとあわせて解説しています。

組織で Claude Code を導入する際は、権限管理だけでなく、利用ルール・セキュリティポリシー・ガバナンス全体を設計する必要があります。

権限設定で迷ったときの基準

個人の検証用リポジトリなら、Auto Mode を試しつつ危険コマンドだけ Hook で塞ぐ
本番に近い設定や顧客データを触るリポジトリでは、確認省略を前提にしない
チーム利用では「誰がどこまで自動承認してよいか」を文章化する

AI コーディングツールの組織導入まで含めて考えるなら、AI組織導入ガイドやバイブコーディング脆弱性チェックリストも読むべきです。便利さだけで運用を決めると事故ります。

Claude Code Auto-Fix はいつ使うべきか

claude autofix 系のクエリでこの記事に来た人向けに先に結論を書くと、Auto-Fix は「導入直後の機能」ではなく、CLAUDE.md と Hooks が最低限整ってから使う機能です。

CI が落ちたたびに Claude に直させる運用は魅力的ですが、ルールが曖昧なまま有効化すると「通すためだけの修正」をしやすくなります。特にテスト書き換えや any 逃げは典型的な事故パターンです。

Auto-Fix を入れる前のチェックリスト

CLAUDE.md に禁止事項と検証コマンドが書かれている
Hooks または CI で最低限の品質ゲートがある
差分レビューを人間が行う前提になっている
失敗時に止めるルールが決まっている

この条件を満たせていないなら、先に Claude Code Auto-Fix 実践ガイドを読み、Desktop で小さい PR から試すのが現実的です。

チェックポイント / rewind / fork — 安全な実験環境

Claude Code はファイル編集のたびに自動でチェックポイントを作成します。これにより、いつでも以前の状態に巻き戻せるセーフティネットが常に張られています。「大胆に試して、ダメなら戻す」という開発スタイルが可能になります。

rewind — 会話とコードの巻き戻し

Esc を 2 回押すか /rewind コマンドで巻き戻しメニューが開きます。

復元オプションは 3 つあります。

オプション	動作
会話のみ復元	指定時点の会話に戻るが、ファイル変更はそのまま残る
コードのみ復元	ファイルを指定時点に戻すが、会話履歴は保持
コードと会話の両方を復元	両方を指定時点に完全復元（最もよく使う）

加えて、「ここから要約（Summarize from here）」 オプションもあります。選択したポイント以降のメッセージを凝縮してコンテキストを解放しつつ、それ以前の会話は保持します。コンテキストが圧迫されてきたときに便利です。

実践的な rewind の使い方

別のアプローチを試したいとき：

実装 A を試してうまくいかなかった場合、Esc × 2 で実装前に戻り、別のアプローチ B を試せます。失敗した試行がコンテキストに残らないため、クリーンな状態で再挑戦できます。

横道にそれた質問を巻き戻すとき：

メインのタスクを進めている途中で、ちょっとした質問をしたくなることがあります。質問を投げて回答を得たら、Esc × 2 で質問前の状態に巻き戻してメインタスクに復帰。横道の回答は会話から消えますが、トランスクリプトには記録が残ります。

fork — セッションの分岐

fork はセッション自体を分岐させる機能です。rewind が「過去に戻る」なのに対し、fork は「並行世界を作る」イメージです。

# 別ターミナルから実行
claude --continue --fork-session

元のセッションは一切影響を受けず、fork 先で自由に作業できます。終了したら /exit で抜け、元のセッションに claude --resume で戻ります。

rewind と fork の使い分け

状況	推奨
1〜2 ターンの軽い質問・確認	rewind — すぐ戻れる
複数ターンにわたる重い調査	fork — 別セッションで履歴も保存される
別の実装アプローチを試したい	rewind — コードと会話を巻き戻して再挑戦
元セッションに絶対影響を与えたくない	fork — 完全に独立した環境

注意点

チェックポイントが追跡するのは Claude のファイル編集ツールによる変更のみ。rm や mv などの bash コマンドによるファイル操作は追跡されない
チェックポイントは git の代替ではない。「ローカルアンドゥ」として使い、永続的な履歴管理は git で行う
チェックポイントはセッション間で保持され、30 日後に自動クリーンアップされる
fork 先ではセッション権限が引き継がれないため、再承認が求められることがある

MCP サーバー — 外部ツールとの接続

MCP（Model Context Protocol）サーバーを接続すると、Claude が外部のツールやサービスと直接やりとりできるようになります。ファイル操作やコマンド実行だけでなく、データベースクエリ、ブラウザ操作、外部 API 連携など、Claude の能力を大幅に拡張できます。

追加方法

MCP サーバーの追加は claude mcp add コマンドで行います。トランスポートの種類によって構文が異なります。

# stdio トランスポート（ローカルプロセス）
claude mcp add serena -- uvx serena-mcp

# HTTP / SSE トランスポート（リモートサーバー）
claude mcp add remote-server --transport http --url https://example.com/mcp

# OAuth 認証が必要なサーバー
claude /mcp
# → ブラウザが開き、OAuth フローが始まる

スコープ — 設定の適用範囲

MCP の設定には 3 つのスコープがあります。

スコープ	保存場所	用途
local	`.claude/settings.local.json`	個人用、git に含めない
project	`.mcp.json`（プロジェクトルート）	チーム共有。git にコミットして全員で同じ MCP 構成を使える
user	`~/.claude/settings.json`	ユーザーグローバル設定

デフォルトは local です。チームで共有したい場合は -s project を指定します。

claude mcp add serena -s project -- uvx serena-mcp

これにより .mcp.json が生成され、チームメンバーが同じ MCP サーバー構成を自動的に利用できます。

`.mcp.json` の構造

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["serena-mcp"],
      "env": {
        "API_KEY": "${SERENA_API_KEY}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

${変数名} でシステム環境変数を参照できるため、トークンやシークレットをファイルに直接書く必要がありません。

実用的な MCP サーバー

サーバー	できること
GitHub MCP	イシュー読み取り、PR 管理、CI/CD ステータス確認
Serena	シンボルの参照関係を意識したコード解析・編集。大規模リファクタリングに強い
Playwright	ブラウザ自動操作、スクリーンショット取得、E2E テスト実行
Context7	npm パッケージや各種ライブラリの最新ドキュメントをリアルタイム取得
PostgreSQL / MySQL	SQL 実行、スキーマ確認、データ検証
Sentry	エラーログの取得と分析。「この例外の原因を調べて」が可能に
Slack	チャンネルの読み書き。通知の自動化

MCP リソースと `@` メンション

MCP サーバーが「リソース」を公開している場合、プロンプト内で @ を使って参照できます。

@postgres://users テーブルのスキーマを確認して、
nameカラムにインデックスを追加する migration を作って

ファイルパスだけでなく、データベーステーブルや外部ドキュメントも直接コンテキストとして渡せるのが強力です。

セキュリティの注意点

アクセス範囲は最小限に — 読み取り専用で十分な場合はフル権限を与えない
トークンは環境変数で管理 — .mcp.json に ${ENV_VAR} で参照し、ハードコードしない
信頼できるソースから導入 — 公式リポジトリや検証済みのパッケージを使う
段階的に導入 — 最初は 1-2 個から始めて動作を確認してから拡張する
プロジェクト設定はレビュー対象 — .mcp.json への変更は PR でレビューする

サブエージェントとエージェントチーム

カスタムサブエージェント

.claude/agents/ にマークダウンファイルを置くと、専用の役割を持つサブエージェントを定義できます。

## <!-- .claude/agents/security-reviewer.md -->

name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash

---

あなたはシニアセキュリティエンジニアです。以下を確認してください：

- インジェクション脆弱性（SQL, XSS, コマンドインジェクション）
- 認証・認可の欠陥
- コード内のシークレットや資格情報
- 安全でないデータ処理

具体的な行番号と修正案を提示してください。

セキュリティの問題がないかサブエージェントでレビューして

サブエージェントは独自のコンテキストウィンドウで動作するため、メインの会話を汚さずに大量のファイルを調査できます。

エージェントチーム（Swarm）

2026年初頭に追加された機能で、複数の Claude Code インスタンスがチームとして協調作業できます。リーダーがタスクを分割し、チームメイトが並列で実行。互いにメッセージをやりとりして調整します。

大規模なリファクタリングや、調査・実装・テストを同時進行したいケースで威力を発揮します。

skills — オンデマンドのドメイン知識

CLAUDE.md は毎回コンテキストに読み込まれますが、skills は必要な時だけ読み込まれます。プロジェクト固有のワークフローやドメイン知識を定義するのに最適です。

CLAUDE.md と skills の使い分け

	CLAUDE.md	skills
読み込み	毎回自動	オンデマンド（必要時のみ）
向いている内容	常に必要な規約、プロジェクト概要	特定タスク向けのワークフロー、ドメイン知識
サイズの影響	大きいとコンテキストを圧迫	必要な時だけ読まれるので影響小

CLAUDE.md が肥大化したら、タスク固有の内容を skills に移動するのが効果的です。

ディレクトリ構成

skills は SKILL.md というファイルを中心にしたディレクトリ構造で管理します。

.claude/skills/
├── api-conventions/
│   └── SKILL.md
├── fix-issue/
│   ├── SKILL.md
│   └── references/          # 補足資料を格納
│       ├── api-schema.yaml
│       └── error-codes.md
└── deploy/
    └── SKILL.md

references/ ディレクトリに補足資料を配置すると、Claude が skill 実行時に参照できます。API スキーマ定義やコード規約のサンプルなど、テキストが長くなるものは SKILL.md 本体ではなくここに分けます。

SKILL.md の frontmatter

---
name: api-conventions
description: REST API design conventions for this project
allowed-tools: Read, Grep, Glob, Edit, Write
context: fork
disable-model-invocation: true
user-invocable: true
---

フィールド	説明
`name`	skill の識別名
`description`	Claude がどの skill を使うか判断するための説明文
`allowed-tools`	この skill で使用可能なツールを制限。セキュリティ向上に有効
`context: fork`	skill 実行を別コンテキスト（サブエージェント）で行う。メインの会話を汚さない
`disable-model-invocation`	`true` にすると Claude が自動で呼び出さない。ユーザーの明示的な `/skill名` でのみ起動
`user-invocable`	`true` にすると `/skill名` でスラッシュコマンドとして呼び出し可能

自動呼び出しと手動呼び出し

skills には 2 つの起動方法があります。

自動呼び出し（デフォルト） — Claude がタスクの内容と description を照合し、関連する skill を自動で読み込む。

---
name: api-conventions
description: REST API design conventions
---

# API 規約

- URL パスは kebab-case
- JSON プロパティは camelCase
- リストエンドポイントには必ずページネーションを含める

API に関する作業を頼むと、Claude が自動的にこの skill を参照します。

手動呼び出し（スラッシュコマンド） — disable-model-invocation: true を設定し、ユーザーが /skill名 で明示的に起動する。$ARGUMENTS で引数を受け取れます。

---
name: fix-issue
description: Fix a GitHub issue end-to-end
disable-model-invocation: true
---

GitHub イシューを修正: $ARGUMENTS

1. `gh issue view $ARGUMENTS` でイシュー詳細を取得
2. 問題の分析と関連ファイルの特定
3. 修正の実装
4. テストの作成と実行
5. コミットと PR 作成

/fix-issue 1234

$ARGUMENTS には /fix-issue の後に続く文字列がそのまま展開されます。

実践的な skill の例

コードレビュー skill（context: fork で実行）

---
name: review
description: Comprehensive code review
context: fork
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash
---

以下の変更をレビューしてください: $ARGUMENTS

## チェック項目

- セキュリティ脆弱性（インジェクション、認証不備）
- エラーハンドリングの網羅性
- テストカバレッジ
- パフォーマンスへの影響
- プロジェクト規約への準拠（references/ を参照）

context: fork を指定すると、レビュー処理がサブエージェントで実行され、メインの会話コンテキストを消費しません。大量のファイルを読む必要があるレビューや調査系のタスクに向いています。

実際の開発フローでの体験

このポートフォリオサイトは、ほぼ全て Claude Code との対話で構築しました。

スキルセクションの試行錯誤

スキルシート（Excel）を読み込ませ、「これに基づいてスキルセクションを再構成して」と依頼。ここから 10 回以上のフィードバックを繰り返しました。

「TypeScript がフロントエンドカテゴリにあるのは違和感がある、言語とフレームワークが混ざってる」→ Languages カードを分離
「Plasmo はモバイルフレームワークではない」→ Frameworks に移動
「Frontend / Backend で分けずにフレームワークで一本化したい」→ 統合

最終的に Languages / Frameworks / Database / Cloud & Infra / DevOps & CI/CD の 5 カード構成に落ち着きました。この過程で実感したのは、Claude は構造の提案は得意だが、ドメイン固有の分類は人間が判断すべきということです。

ブログ記事の協調執筆

「実務の知見を使ってブログを書いて」と依頼し、Nuxt→Next 移行の記事を生成。そこから「状態管理は jotai だった」「認証は Firebase Auth」「Pages Router で Server Components は使ってない」と事実を補正していきました。

AI が書いた「もっともらしい内容」をそのまま使うのではなく、自分の実体験と照合しながら修正するのがポイントです。これは公式ドキュメントが「信頼してから検証するギャップ」として警告しているパターンそのものです。

知っておくと便利な Tips

Tips	説明
`Esc`	実行中のアクションを即座に停止。コンテキストは保持される
`Esc` × 2 / `/rewind`	巻き戻しメニュー。会話・コード・両方を任意の時点に復元
`/fork`	現在のセッションを分岐。元セッションに影響なし
`/clear`	コンテキストを完全リセット。タスク切り替え時に必須
`/compact`	会話を圧縮してコンテキストを解放
`claude --continue`	前回のセッションを再開
`claude --resume`	過去のセッション一覧から選択して再開
`claude --continue --fork-session`	前回セッションを fork して新セッションで作業
`/rename`	セッションに名前をつけて管理しやすくする
`Shift + Tab`	Plan Mode に切り替え（読み取り専用モード）
`think hard` / `ultrathink`	Claude の思考を深くする（複雑な問題で有効）
`cat error.log \| claude`	パイプでデータを直接渡せる
`@ファイルパス`	プロンプト内でファイルを参照

まとめ

Claude Code は「コードを書いてくれる AI」ではなく、タスクを渡すと自律的に完遂するエージェントです。

効果的に使うための原則：

コンテキストを管理する — /clear と /compact を駆使し、サブエージェントで調査を委譲する
CLAUDE.md を簡潔に保つ — 「削除したら Claude が間違えるか？」でフィルタリング
検証手段を与える — テスト、スクリーンショット、期待する出力を提示する
段階的に進める — 探索 → 計画 → 実装 → 検証の 4 フェーズ
間違いは即座に指摘する — 2 回修正しても直らなかったら /clear して再出発
hooks で確実性を担保する — CLAUDE.md はアドバイス、hooks は強制

AI ツールに完璧を求めるのではなく、自分のドメイン知識と AI の実行力を掛け合わせる。この対話のリズムをつかむことが、Claude Code を使いこなす鍵だと感じています。

次に読む — Claude Code を深く使いこなすために

この記事で全体像をつかんだら、目的に応じて以下の記事に進んでください。

CLAUDE.md を本格運用したい → CLAUDE.md の書き方設計パターン集
ルールを確実に強制したい → Claude Code Hooks の使い方実践ガイド
権限管理を自動化したい → Claude Code Auto Mode 徹底解説
CI/CD と連携したい → Claude Code Auto-Fix 実践ガイド
出力品質を体系的に安定させたい → Harness Engineering 入門
他のツールと比較したい → Claude Code vs Codex CLI 徹底比較

Claude Code の使い方 実践ガイド — 導入・CLAUDE.md・Hooks・Auto-Fix を実務で解説