Claude Codeをローカル開発で使うための実践ガイド

最近、ローカル開発でClaude Codeを使う機会が増えてきた。

最初は「ターミナル上でClaudeに質問できるツール」くらいに考えていたが、実際に使ってみると、単なるチャット型のコード補完ではなかった。リポジトリ全体を調べ、複数ファイルを修正し、コマンドを実行し、テスト結果を見ながら次の修正まで進められる。

一方で、何も設定せずに使い始めると、毎回同じ説明をすることになる。権限を広げすぎると意図しないコマンドを実行する可能性もあるし、CLAUDE.md、Skills、Hooks、MCP、Subagentsの役割も最初は分かりにくい。

この記事では、私がWindowsとmacOSのローカル開発でClaude Codeを使うことを前提に、導入方法、設定ファイル、実務で使うコマンド、Skillsの作り方、安全な運用方法までまとめる。

内容は2026年9月時点のClaude Codeを基準にしている。Claude Codeは更新が速いため、コマンドが見つからない場合は、まずclaude --versionと公式ドキュメントを確認してほしい。

Claude Codeとは

Claude Codeは、Anthropicが提供しているエージェント型の開発ツールである。

VS Codeの入力中に次のコードを提案するだけではなく、次のような作業を一つの流れとして実行できる。

• リポジトリ内のファイル構成を確認する
• 関連コードを検索する
• 既存処理を説明する
• 実装方針を作る
• 複数のファイルを編集する
• lint、build、testを実行する
• エラーの原因を調査して修正する
• Git差分を確認する
• コードレビューやセキュリティレビューを行う

私の場合は、WordPressの子テーマ、PHP、JavaScript、ColdFusion、Goなど、技術構成の違う案件を扱うことがある。このような環境では、プロジェクトごとの決まりをCLAUDE.mdに書いておくと、毎回ゼロから説明しなくて済む。

ただし、Claude Codeは万能ではない。変更内容の最終確認、仕様判断、機密情報の管理、本番環境への反映は開発者側の責任で行う必要がある。私は「実装を任せる」というより、「調査、実装、確認を一緒に進める開発者」として使っている。

インストール

現在はネイティブインストールが推奨されている。以前よく使われていたnpm経由の導入だけを前提にせず、公式のインストーラーを使う方が分かりやすい。

macOS・Linux・WSL

curl -fsSL https://claude.ai/install.sh | bash

Homebrewで管理したい場合は、次の方法も使える。

brew install --cask claude-code

Homebrew版は自動更新されないため、定期的に更新する。

brew upgrade claude-code

Windows PowerShell

PowerShellでは次のコマンドを実行する。

irm https://claude.ai/install.ps1 | iex

WinGetで管理したい場合は、次の方法もある。

winget install Anthropic.ClaudeCode

更新は次のコマンドで行う。

winget upgrade Anthropic.ClaudeCode

WindowsではGit for Windowsも入れておく方がよい。Git for WindowsがあればClaude CodeはBashツールを利用できる。入っていない環境ではPowerShellが使われる。

私は普段PowerShell 7を使っているが、Git操作やUnix系コマンドを含むプロジェクトではGit for Windowsも併用している。

インストール確認

claude --version

問題がある場合は、次の診断コマンドを先に実行する。

claude doctor

claude doctorは、インストール状態や設定ファイルのエラーを確認するための読み取り専用コマンドである。Claude Codeのセッション内では/doctorも利用できる。

ログインと最初の起動

初回はプロジェクトのルートディレクトリへ移動してから起動する。

cd /path/to/project
claude

ブラウザが開くので、Claude Pro、Max、Team、Enterprise、またはClaude Consoleのアカウントでログインする。

ログイン状態を確認したい場合は次を使う。

claude auth status --text

アカウントを切り替える場合は、セッション内で次を実行する。

/login

またはターミナルからログアウト、再ログインできる。

claude auth logout
claude auth login

最初の起動では、いきなり修正を依頼するより、コードベースを理解させるところから始める方がよい。

このプロジェクトの技術構成と主要なディレクトリを調査してください。
まだファイルは変更せず、起動方法、テスト方法、注意点をまとめてください。

その結果を確認してから、プロジェクト用の設定を作る。

最初に覚えておきたい起動コマンド

標準入力も利用できるため、ログの解析にも使える。

cat error.log | claude -p "このエラーの原因と確認手順を日本語で整理してください"

PowerShellでは次のように渡せる。

Get-Content .\error.log -Raw | claude -p "このエラーの原因と確認手順を整理してください"

-pはシェルスクリプトや定型処理と組み合わせやすい。ただし、自動処理でファイル変更まで許可する場合は、権限と実行範囲を慎重に設定する必要がある。

.claudeディレクトリの基本構成

Claude Codeを継続的に使うなら、プロジェクト内の.claudeディレクトリが重要になる。

project-root/
├── CLAUDE.md
├── CLAUDE.local.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   ├── rules/
│   │   ├── coding-style.md
│   │   ├── testing.md
│   │   └── security.md
│   ├── skills/
│   │   └── release-check/
│   │       └── SKILL.md
│   └── agents/
│       └── code-reviewer.md
└── .mcp.json

すべてを最初から作る必要はない。私なら、まずCLAUDE.mdと.claude/settings.jsonだけを作り、繰り返し発生する作業が増えてからRulesやSkillsを追加する。

CLAUDE.mdにプロジェクトの前提を書く

CLAUDE.mdは、Claude Codeがセッション開始時に読むプロジェクトの説明書である。

初回は次のコマンドでひな型を作れる。

/init

ただし、自動生成された内容をそのまま使うのではなく、実際のプロジェクトに合わせて整理した方がよい。

配置場所と適用範囲

CLAUDE.local.mdには個人環境固有の内容を書き、Gitには含めないようにする。

私ならこのように書く

# Project overview

このリポジトリはWordPressのSWELL子テーマです。
親テーマのファイルは直接変更しません。

# Main directories

- `wp-content/themes/example-child/`: 子テーマ
- `assets/css/`: 追加CSS
- `assets/js/`: フロントエンドJavaScript
- `template-parts/`: 共通テンプレート

# Development rules

- 既存のコード構造と命名規則を優先する
- PHP出力時はコンテキストに応じてエスケープする
- WordPress標準APIがある場合は独自実装より優先する
- jQuery依存の既存処理を、依頼なしに全面的なVanilla JSへ置き換えない
- 親テーマは変更しない
- 修正前に影響範囲を確認する

# Verification

- PHP構文エラーを確認する
- PCとSPの表示を確認する
- Chrome、Firefox、Safariへの影響を考慮する
- 変更後に`git diff --check`を実行する

# Communication

- 回答は日本語で行う
- 実装前に変更方針を簡潔に示す
- 変更後は対象ファイル、変更内容、確認結果をまとめる

重要なのは、長い説明を書くことではなく、毎回守ってほしい事実とルールに絞ることである。

「デプロイ作業を順番に実行する」「リリース前に10項目を確認する」のような手順は、CLAUDE.mdではなくSkillに分けた方が管理しやすい。

.claude/rules/でルールを分割する

プロジェクトが大きくなると、CLAUDE.mdだけでは読みにくくなる。その場合は.claude/rules/へ分割する。

.claude/rules/
├── backend.md
├── frontend.md
├── database.md
├── security.md
└── testing.md

例えばsecurity.mdには、次のような内容を置く。

# Security rules

- パスワード、APIキー、アクセストークンをコードへ直接記述しない
- `.env`の内容を回答へ出力しない
- SQLは必ずパラメータ化する
- HTML出力時は出力先に応じて適切にエスケープする
- 認証・権限チェックを省略しない
- セキュリティ関連の既存処理を変更する場合は、変更理由と影響範囲を説明する

特定のファイルやディレクトリにだけ適用するルールも作れる。モノレポや、フロントエンドとバックエンドで規約が違うプロジェクトでは特に便利である。

設定ファイルの使い分け

Claude Codeの主な設定ファイルは次のとおりである。

Windowsでは~/.claudeは通常%USERPROFILE%\.claudeに相当する。

.claude/settings.local.jsonは、個人的に許可したコマンドやローカル固有の設定に向いている。Claude Codeが自動作成した場合は通常Gitの除外対象になるが、自分で作成した場合は.gitignoreも確認しておく。

設定ファイルは厳密なJSONであり、コメントや末尾カンマは使えない。

私が最初に入れる権限設定

便利だからといって、すべてのBash操作を最初から許可するのは避けている。日常的に使う安全な確認コマンドだけを許可し、危険な操作や機密ファイルへのアクセスは拒否する。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git diff --check)",
      "Bash(npm run lint *)",
      "Bash(npm run test *)",
      "Bash(npm run build *)",
      "Bash(go test ./...)",
      "Bash(go vet ./...)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git commit *)",
      "Bash(npm install *)",
      "Bash(go get *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/secrets/**)",
      "Bash(rm -rf *)",
      "Bash(git reset --hard *)",
      "Bash(git clean -fd *)",
      "Bash(git push --force *)"
    ]
  }
}

権限ルールはdeny、ask、allowの順で評価される。広いdenyに対して、狭いallowを後から書いて例外にすることはできない。そのため、拒否ルールは広げすぎず、実際に止めたい操作を具体的に書く。

現在の権限はセッション内で確認できる。

/permissions

設定が読み込まれているか分からない場合は、次を確認する。

/status

Permission Modeの使い分け

私は大きな修正では、最初にplanで調査させ、方針を確認してからacceptEditsへ切り替えることが多い。

/plan

またはShift + Tabでモードを切り替えられる。

bypassPermissionsは便利に見えるが、通常のPC上では使わない方がよい。使うなら、破壊されても戻せるコンテナ、VM、専用の作業環境などに限定する。

セッション内でよく使うコマンド

Claude Codeを起動した後に使う/から始まるコマンドは、シェルコマンドとは別物である。

基本操作

会話とコンテキスト

長時間の作業では、コンテキストが増えすぎると判断が不安定になることがある。私は一つのタスクが終わった時点で/clearするか、同じタスクを続ける場合は/compactを使う。

開発と確認

コードレビューでは、対象を明確にした方が結果が安定する。

/code-review high

/code-review high --fix

/code-review high 1234

--fixを付ける前に、一度指摘内容だけを確認する方が安全である。

プロンプトは「目的・範囲・制約・完了条件」で書く

Claude Codeへ短く依頼できるのは便利だが、複数ファイルへ影響する修正では、最低限の条件を書いた方がよい。

私がよく使う形は次のとおりである。

目的:
ログイン画面で二要素認証コードを確認できるようにする。

対象:
- 認証用CFC
- ログイン画面のCFM
- 関連JavaScript

制約:
- 既存のパスワード認証は変更しない
- 既存のレスポンス形式を維持する
- SQLは必ずパラメータ化する
- 最初は実装せず、関連処理と影響範囲を調査する

完了条件:
- 正常系と異常系の処理がある
- 既存ログインへのデグレがない
- 変更ファイルと確認結果を最後にまとめる

「いい感じに直して」でも動くことはあるが、仕様の境界が曖昧なまま実装が進みやすい。特に既存システムでは、変えない部分を書くことが重要である。

Skillsとは

Skillは、何度も使う手順、チェックリスト、専門知識を再利用する仕組みである。

例えば、毎回次のような依頼をしているならSkillに向いている。

• Git差分を確認してコミットメッセージを作る
• WordPress公開前の確認を行う
• ColdFusionのセキュリティ観点でレビューする
• Go APIのハンドラーとテストを同じ基準で確認する
• リリース前にbuild、test、diffを順番に確認する

Skillは必要なときだけ本文が読み込まれる。そのため、常に必要な短いルールはCLAUDE.md、特定作業の詳しい手順はSkillという分け方がよい。

Skillの保存場所

チームで共有するSkillはプロジェクト側へ置き、Gitで管理する。自分だけの汎用Skillはホームディレクトリ側へ置く。

最初に作りたいSkill：Git差分の要約

~/.claude/skills/git-diff-summary/
└── SKILL.md

SKILL.mdの例は次のとおりである。

---
description: 未コミットのGit差分を確認し、変更概要、リスク、確認項目、コミットメッセージ案を作成する。差分確認、コミット前確認、コミットメッセージ作成を依頼されたときに使用する。
---

# Git diff summary

## Current status

!`git status --short`

## Current diff

!`git diff HEAD`

## Instructions

次の順で日本語で回答する。

1. 変更概要
2. 影響範囲
3. バグやデグレの可能性
4. 不足しているテスト
5. 日本語のコミットメッセージ案

差分に含まれていない処理を変更済みとして説明しない。
機密情報らしき値を見つけた場合は、値を再掲せず注意だけを出す。

セッション内で次のように実行できる。

/git-diff-summary

frontmatterのdescriptionは重要である。何をするSkillなのかだけでなく、「どのような依頼のときに使うか」まで書いておくと、自動選択されやすい。

WordPress・SWELL向けSkillの例

---
description: WordPressのSWELL子テーマの変更を公開前に確認する。PHP、エスケープ、親テーマへの変更、レスポンシブ表示、キャッシュ、ブラウザ互換性の確認を依頼されたときに使用する。
---

# SWELL child theme release check

## Check procedure

1. `git status --short`と`git diff --check`を確認する
2. 変更したPHPファイルの構文を確認する
3. 出力値のエスケープと入力値のサニタイズを確認する
4. 親テーマを直接変更していないか確認する
5. PCとSPのレイアウトへの影響を確認する
6. Chrome、Firefox、Safariで差が出そうなCSSとJavaScriptを確認する
7. キャッシュによって古いCSSやJavaScriptが残る可能性を確認する
8. 公開前に人が確認すべき項目を一覧にする

自動的に本番へデプロイしない。
キャッシュを削除する前に対象と影響を説明する。

ColdFusion向けSkillの例

---
description: ColdFusionのCFM・CFC変更をセキュリティと既存仕様の観点でレビューする。CFML、cfquery、remote関数、Ajax通信、認証処理の確認時に使用する。
---

# ColdFusion security review

## Review points

- `cfqueryparam`を使用しているか
- HTML、JavaScript、URLなど出力先に応じたエンコードを行っているか
- CFCの`access="remote"`が必要な関数だけに付いているか
- GETとPOSTの仕様が適切か
- セッションと権限をサーバー側で確認しているか
- エラー内容に内部パス、SQL、認証情報が含まれていないか
- 既存のCF2018、CF2021、CF2023環境への影響がないか

指摘は「重大」「要確認」「改善提案」に分ける。
既存仕様が不明な場合は、推測で修正せず確認事項として残す。

私はSkillに実装方法を細かく固定しすぎないようにしている。確認観点と完了条件は固定するが、具体的な修正方法は、その時点のコードを見て判断させる方がよい。

組み込みSkillsでよく使うもの

現在のClaude Codeには、最初からいくつかのSkillsが含まれている。利用できるものはバージョンや環境によって異なるため、/skillsまたは/メニューで確認する。

特に/run-skill-generatorは、起動に複数の手順が必要なプロジェクトで便利である。毎回起動方法を推測させるのではなく、動作した手順をプロジェクト用Skillとして保存できる。

ただし、データベース、AWS、S3、本番相当の外部サービスへ接続するプロジェクトでは、Skill内に認証情報を書かない。必要な環境変数名だけを書き、実際の値は安全な方法で管理する。

Subagentsの使いどころ

Subagentは、メインの会話とは別のコンテキストで、特定の役割を担当させる仕組みである。

例えば次のように分けられる。

• 調査だけを行うAgent
• 読み取り専用のコードレビューAgent
• テスト失敗の原因だけを調査するAgent
• セキュリティ観点だけを確認するAgent

プロジェクト用は.claude/agents/、個人用は~/.claude/agents/へ配置する。

---
name: code-reviewer
description: 変更されたコードを読み取り専用でレビューし、バグ、デグレ、保守性、テスト不足を確認する。
tools: Read, Grep, Glob
model: sonnet
---

あなたは既存システムのコードレビュー担当です。

ソースコードは変更せず、次の順で報告してください。

1. 重大な問題
2. デグレの可能性
3. テスト不足
4. 保守性の改善案

根拠となるファイルと処理を明示し、確認できないことを断定しないでください。

読み取り専用にしたいAgentには、Read、Grep、Globだけを許可する。このように役割と利用可能なツールを絞ると、レビュー中に勝手に修正されることを防ぎやすい。

作成後は次のように依頼する。

code-reviewerを使って、現在のGit差分をレビューしてください。

Subagentは何でも並列化するための機能ではない。小さな修正ではメインセッションだけの方が速い。調査範囲が分かれている場合や、実装とレビューの視点を分離したい場合に使う。

Hooksで必ず実行したい処理を自動化する

CLAUDE.mdやSkillはClaudeへの指示であり、必ず実行される保証ではない。一方、Hooksは特定のタイミングでコマンドや処理を実行する仕組みである。

例えば次の用途に向いている。

• ファイル編集後にformatterを実行する
• JavaScript変更後にlintを実行する
• 特定ディレクトリへの書き込みを止める
• 作業完了時に通知する
• ツール実行前に独自チェックを行う

設定状況は次のコマンドで確認できる。

/hooks

Hooksは強力だが、最初から増やしすぎると「なぜコマンドが実行されたのか」が分かりにくくなる。私はまず手動で安定している確認処理をSkillにし、本当に毎回必要だと判断したものだけHookへ移す。

また、外部から取得した文字列をそのままシェルへ渡すHookは作らない。パス、引数、環境変数の扱いを確認し、リポジトリに含めるHookはコードレビューの対象にする。

MCPで外部ツールと接続する

MCPは、Claude Codeから外部サービスや社内ツールを利用するための仕組みである。

例えば、GitHub、Notion、課題管理、データベース、監視サービスなどと接続できる。ただし、MCPサーバーを追加するとClaude Codeが扱える情報と操作範囲が増えるため、提供元、権限、取得データを確認してから接続する。

リモートHTTPサーバーを追加する

claude mcp add --transport http notion https://mcp.notion.com/mcp

ローカルstdioサーバーを追加する

claude mcp add --transport stdio my-server -- npx -y @example/mcp-server

管理コマンド

claude mcp list
claude mcp get notion
claude mcp remove notion

セッション内では次を使う。

/mcp

MCPには主に3つの適用範囲がある。

• local: 現在のプロジェクトで自分だけが使う
• project: .mcp.jsonへ保存し、チームで共有する
• user: 自分の全プロジェクトで使う

チーム共有が必要な場合は--scope projectを使う。

claude mcp add --scope project --transport http example https://example.com/mcp

.mcp.jsonをGit管理する場合も、トークンを直接書かない。環境変数を利用し、必要以上に広い権限を与えない。

知らないリポジトリをcloneした直後は、.mcp.jsonもコードと同じように内容を確認する。外部コンテンツを取得するMCPには、プロンプトインジェクションのリスクもある。

VS Codeで使う場合

Claude Codeはターミナルだけでなく、VS Code拡張機能からも利用できる。

VS Code版では、ファイルの参照、インラインdiff、選択範囲を含めた質問、Planの確認などが画面上で行える。私は次のように使い分けている。

• 小さな修正、選択中コードの質問：VS Code
• リポジトリ全体の調査：CLI
• 複数ファイルの実装とテスト：CLI
• 差分を見ながら微調整：VS Code
• ログをパイプして解析：CLIの-p

CLIとVS Code版は別の製品というより、同じClaude Codeを異なる操作方法で使うイメージに近い。

私がよく使う実務フロー

1. 現在の状態を確認する

git status
git branch --show-current

未コミットの変更がある状態でClaude Codeを起動する場合は、その変更を上書きしないよう最初に伝える。

現在の未コミット変更は私が作業中の内容です。
既存の変更を削除・復元せず、今回の対象だけを調査してください。

2. Plan Modeで調査する

/plan

この不具合の再現条件、原因候補、影響範囲を調査してください。
まだ修正は行わず、変更予定ファイルと確認方法を提示してください。

3. 計画を確認してから実装する

仕様の勘違いがあれば、この段階で修正する。

方針は問題ありません。
ただし既存のレスポンス形式は変更せず、最小限の修正で実装してください。

4. テストと差分確認を行う

/diff

変更に対応するテストを実行し、失敗した場合は原因を調査してください。
テストを通すためだけに既存仕様を変更しないでください。

5. 別の視点でレビューする

/code-review high

必要ならセキュリティレビューも行う。

/security-review

6. 最後は自分で確認する

私は少なくとも次を自分で見る。

• git diffに依頼外の変更がないか
• 削除された処理が本当に不要か
• 例外処理と境界値が足りているか
• テストが実装内容に合っているか
• 認証情報や個人情報が含まれていないか
• 本番環境固有の設定に影響しないか

Claude Codeが「テスト成功」と書いていても、実際のコマンド出力と終了コードを確認する。

Git操作を任せるときの注意

Claude CodeはGit操作もできるが、私は次の操作を自動許可していない。

• git commit
• git push
• git reset --hard
• git clean -fd
• force push
• ブランチの削除

コミットまで依頼する場合は、最初に差分を確認し、対象ファイルとコミットメッセージを指定する。

現在の差分を確認し、今回の修正に関係するファイルだけをstageしてください。
コミットはまだ実行せず、対象ファイルとコミットメッセージ案を提示してください。

AIが生成した変更と、自分が作業中だった変更が混在している場合に、git add .を安易に使わせないことも重要である。

うまくいかなかったときの確認順序

設定が反映されない

/status

どの設定ファイルが読み込まれているか確認する。JSONエラーが疑われる場合は次を使う。

claude doctor

Skillが表示されない

確認する項目は次のとおりである。

• ディレクトリ名とSKILL.mdの大文字小文字
• 配置場所が.claude/skills/<name>/SKILL.mdになっているか
• YAML frontmatterが正しいか
• descriptionが書かれているか
• セッションを再起動したか
• /skillsに表示されるか

Claudeが同じ間違いを繰り返す

2回以上同じ修正を伝えたなら、口頭で繰り返すのではなくCLAUDE.mdへ短いルールとして追加する。

ただし、一度しか使わない仕様や長い作業手順までCLAUDE.mdへ詰め込まない。長い手順はSkill、特定パスだけの規約はRules、絶対に止めたい操作はPermissionまたはHookへ分ける。

会話が長くなって精度が落ちた

/context
/compact

別のタスクへ移るなら、同じセッションを引き延ばさず/clearする。

最初から入れすぎない方がよい設定

Claude Codeには多くの拡張機能があるが、最初から全部使う必要はない。

私が考える導入順序は次のとおりである。

1. Claude Codeをインストールする
2. プロジェクトルートで起動する
3. CLAUDE.mdを整える
4. よく使う読み取り・テストコマンドだけ許可する
5. Plan → 実装 → diff → testの流れに慣れる
6. 繰り返す作業をSkillにする
7. 必ず実行したい処理だけHookにする
8. 必要な外部サービスだけMCPで接続する
9. 明確に分離できる作業だけSubagentへ任せる

設定を増やすこと自体が目的になると、メンテナンスするファイルが増え、逆に使いにくくなる。まず手動で何度か実行し、安定した作業だけを自動化する方がよい。

まとめ

Claude Codeをローカル開発で安定して使うには、プロンプトの書き方だけでなく、プロジェクトの情報と権限を整理することが重要だった。

私が特に重要だと感じているのは次の点である。

• プロジェクト固有の前提はCLAUDE.mdへ書く
• 大きな変更はPlan Modeから始める
• 権限は必要なコマンドだけ許可する
• 繰り返す手順はSkillにする
• 必ず実行したい処理はHookにする
• 外部サービスとの接続はMCPで管理する
• 実装後は/diff、テスト、コードレビューを行う
• 最終判断と本番反映は自分で行う

Claude Codeは、指示を一度出して放置するより、調査結果と差分を途中で確認しながら使う方が強い。プロジェクトのルールを少しずつ整え、自分の開発フローに合わせて育てていくと、調査、実装、レビューにかかる時間をかなり減らせる。

参考資料

• Claude Code Quickstart
• CLI reference
• Claude Code settings
• How Claude remembers your project
• Configure permissions
• Commands
• Extend Claude with skills
• Create custom subagents
• Hooks reference
• Connect Claude Code to tools via MCP