個人開発者のためのClaude Code完全ガイド

Claude Codeをこれから使い始める人に向けたガイドです。インストールから最初のセッション、許可の仕組み、CLAUDE.md の書き方までを順に追います。

このガイドの前提は「プログラミングの経験はあるが、Claude Codeは初めて」です。ターミナルでコマンドを打った経験があれば読み進められます。

公式ドキュメントに書いてあることは出典を示して引用し、そこに書かれていない、私が実際に踏んだ落とし穴はエラーの実文つきで載せています。とくに3章の課金の話は、気づかないまま数ヶ月放置していたものです。

---

1. Claude Codeとは何か

Claude Codeは、ターミナルから使うAnthropicのエージェント型コーディングツールです。

チャット型のAIとの一番の違いは、コピペが要らないことです。

	チャット型AI	Claude Code
コードの受け取り	画面からコピーして貼る	エージェントが直接ファイルへ書く
ファイルを読む	自分で開いて貼り付ける	エージェントが自分で読む
テストの実行	自分でターミナルで叩く	エージェントが実行して結果を見る
直す範囲	貼った断片だけ	プロジェクト全体

「このエラーを直して」と伝えると、関係するファイルを自分で探して読み、修正を書き、テストを走らせて、通らなければ直し直します。この一連を人間が仲介せずに回せるのが本質的な違いです。

裏を返せば、あなたのファイルを書き換えるツールでもあります。だから許可の仕組み（5章）が重要になります。

2. 導入する

有料プランが必要です

最初に押さえておくべき前提があります。公式ドキュメントに明記されています。

Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access.

（出典: Advanced setup — Authenticate）

無料のClaude.aiプランではClaude Codeは使えません。Pro / Max などのサブスクリプション、またはAPIの従量課金（Console アカウント）のどちらかが要ります。

インストール

公式のネイティブインストーラを使うのが推奨です。

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

npm 経由でも入ります。こちらは Node.js 22 以降が必要です。

npm install -g @anthropic-ai/claude-code

インストールできたか確認します。

claude --version

2.1.211 (Claude Code) のようにバージョンが表示されれば成功です。

うまく動かないときは claude doctor を実行してください。セッションを開始せずに、インストール状態と設定ファイルの検証結果を出してくれます。

起動する

作業したいプロジェクトのディレクトリでターミナルを開き、次を実行します。

cd path/to/your-project
claude

初回はブラウザが開いてログインを求められます。ログインが済めば、対話セッションが始まります。

3. 最初に確認すべき、課金の落とし穴

ここが本記事で一番伝えたい部分です。

Pro や Max のサブスクリプションに入っていても、ANTHROPIC_API_KEY という環境変数がセットされていると、サブスクリプションではなくAPIの従量課金が使われます。公式ドキュメントにこう書かれています。

API key sent as X-Api-Key header. When set, this key is used instead of your Claude Pro, Max, Team, or Enterprise subscription even if you are logged in.

（出典: Environment variables）

「ログインしていても（even if you are logged in）」という部分が肝心です。ログイン済みだから安心、とはなりません。

認証情報の優先順位は公式に6段階で定義されています。

順位	認証方法
1	クラウドプロバイダの認証情報（Bedrock / Vertex / Foundry）
2	ANTHROPIC_AUTH_TOKEN 環境変数
3	ANTHROPIC_API_KEY 環境変数
4	apiKeyHelper スクリプトの出力
5	CLAUDE_CODE_OAUTH_TOKEN 環境変数
6	/login で取得したサブスクリプションのOAuth

（出典: Authentication — Authentication precedence）

サブスクリプションは最下位です。

気づきにくい理由

対話モードでは、APIキーを使う前に1回だけ承認を求められます。ここで気づけます。

ただし、-p を付けた非対話モードでは違います。

In non-interactive mode (-p), the key is always used when present.

（出典: Environment variables）

承認プロンプトなしで、常にAPIキーが使われます。CI やスクリプト、ヘッドレス実行で無自覚に従量課金になる経路がこれです。

実際に踏んだ話

私の環境では、ANTHROPIC_API_KEY が Windows の Machine（システム）スコープに設定されていました。

設定したのは2026年2月末です。当時の別プロジェクトがClaude APIを直接叩く実装をしていて、そのために入れたものでした。そのプロジェクトは3月に別のAPIへ移行し、4月には該当コードも削除しています。用途が消えた環境変数だけが4ヶ月残り続けました。

発覚したのは7月15日です。きっかけは症状のほうでした。

• claude remote-control（サブスクリプション認証が必須の機能）が使えない
• Claude Agent SDK を動かすと stderr に警告が出る

警告の実文はこれです。

⚠ claude.ai connectors are disabled because ANTHROPIC_API_KEY or another
auth source is set and takes precedence over your claude.ai login

「別の認証ソースがあなたのclaude.aiログインより優先される」と、はっきり書いてありました。

確認する

まず、Claude Code のセッション内で /status を実行してください。Login method の行にログイン中のアカウントが出ます。APIキーが使われているときは API key の行が追加で表示されます。

Windows で環境変数そのものを調べるときは、別プロセスで読むのが確実です。

reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v ANTHROPIC_API_KEY

終了コード 1 なら存在しません。

ここには私が時間を溶かした罠があります。同じPowerShellプロセスの中では、削除した後でも古い値が返り続けます。 [Environment]::GetEnvironmentVariable('ANTHROPIC_API_KEY','Machine') も Get-ItemProperty も、削除前から起動していたプロセスではレジストリハンドルを使い回すため古い値を返しました。「消したのに消えていない」と誤判定して、原因を1時間近く探しました。

reg query を新しいプロセスで叩けば、正しい状態が読めます。

解除する

一時的に外すだけなら、公式が示す方法はこれです。

unset ANTHROPIC_API_KEY

Windows の Machine スコープに入っている場合は、削除に管理者権限が必要です。そして削除の反映にはPCの再起動が必要でした。既存のプロセスは起動時の環境ブロックを保持し続けるためです。

再起動後にもう一度 reg query で不在を確認し、Agent SDK を1回動かして先ほどの警告が出ないことを確認して、ようやく決着しました。

まとめると、Claude Code を入れたらまず /status を見てください。 これだけで、意図しない課金の経路にいるかどうかが分かります。

4. 最初の10分でやること

導入と課金の確認が済んだら、実際に動かします。おすすめの順序は次の3ステップです。

ステップ1: まず読ませる

いきなり書かせないでください。最初は、プロジェクトを理解しているかを確かめます。

このプロジェクトの構成を説明してください。
どのファイルがエントリポイントですか。

ここで返ってきた説明が的外れなら、あなたのプロジェクトの構造が読み取りにくいということです。その場合は6章の CLAUDE.md が効きます。

ステップ2: 小さな変更を1つ

次に、間違っても被害が小さいものを1つ頼みます。

README.md のインストール手順に、Node.js のバージョン要件を追記してください。

このとき、変更前に許可を求めてくることを確認してください。それが標準の挙動です。

ステップ3: git diff で確認する

エージェントが「できました」と言っても、鵜呑みにしないでください。自分で確認します。

git diff

この習慣が、後々いちばん効きます（8章）。

5. 許可の仕組みを理解する

Claude Code は、ファイルを編集したりコマンドを実行したりする前に、あなたに確認を取ります。この確認の頻度を決めるのがパーミッションモードです。

公式に定義されているモードは6つあります。

モード	確認なしで実行されるもの	向いている場面
default（Manual）	読み取りのみ	最初はこれ。 慎重に進めたいとき
acceptEdits	読み取り、ファイル編集、mkdir mv などのファイル操作	自分でレビューしながら回すとき
plan	読み取りと、計画のための調査	変更する前に方針を立てたいとき
auto	ほぼすべて（別のモデルが背後で安全性を判定）	長時間のタスク
dontAsk	事前に許可したツールだけ	CI やスクリプト
bypassPermissions	すべて	隔離されたコンテナ・VMのみ

（出典: Choose a permission mode）

セッション中は Shift+Tab でモードを切り替えられます。起動時に指定することもできます。

claude --permission-mode plan

--dangerously-skip-permissions を安易に使わない

ネット上の記事では --dangerously-skip-permissions（bypassPermissions と同等）を勧めているものがあります。確認が煩わしいのは事実です。

しかし公式ドキュメントは、はっきり警告を出しています。

Only use this mode in isolated environments like containers, VMs, or dev containers without internet access, where Claude Code cannot damage your host system.

bypassPermissions offers no protection against prompt injection or unintended actions.

（出典: Choose a permission mode）

「プロンプトインジェクションに対する保護が一切ない」という点が重要です。エージェントが読んだファイルやWebページに悪意ある指示が仕込まれていた場合、それを防ぐ層が無くなります。

確認の回数を減らしたいだけなら、まず acceptEdits を試してください。ファイル編集は通しつつ、それ以外のコマンドは確認が残ります。

6. CLAUDE.md を書く

CLAUDE.md は、セッションのたびに読み込まれる指示書です。「毎回同じことを説明している」と感じたら、それを書く場所です。

置き場所は複数あり、読み込み順が決まっています。

スコープ	場所	用途
ユーザー	~/.claude/CLAUDE.md	全プロジェクト共通の個人的な好み
プロジェクト	./CLAUDE.md または ./.claude/CLAUDE.md	チームで共有する規約
ローカル	./CLAUDE.local.md	個人的なプロジェクト設定（.gitignore に入れる）

（出典: How Claude remembers your project）

まず /init を実行してみてください。コードベースを解析して、ビルドコマンドやテスト手順を含む雛形を生成してくれます。そこから育てるのが早道です。

書き方のコツ

公式が示す原則は3つです。

具体的に書く。 検証できる粒度にします。

# 良い例
- インデントは半角スペース2つ
- コミット前に `npm test` を実行する
- APIハンドラは `src/api/handlers/` に置く

# 悪い例
- コードを綺麗にフォーマットする
- 変更をテストする
- ファイルを整理する

200行を目安にする。 CLAUDE.md は毎回コンテキストに載るため、長いほどトークンを食い、かつ遵守率が下がります。

矛盾を残さない。 2つのルールが食い違っていると、どちらが選ばれるかは不定になります。

何を書くか

判断基準はシンプルです。公式はこう述べています。

Treat CLAUDE.md as the place you write down what you’d otherwise re-explain.

つまり「また説明することになったら書く」。具体的には次のタイミングです。

• 同じ間違いを2回された
• 前のセッションと同じ訂正を入力した
• 新しく参加する人にも同じ説明が要る

7. Windows で踏む3つ

Windows で使う場合、Unix 前提の記事どおりに進めると詰まる箇所があります。実際に踏んだものを挙げます。

7-1. Git for Windows を入れる

公式ドキュメントに記載があります。

Git for Windows is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead.

（出典: Advanced setup — Set up on Windows）

Git for Windows があると Git Bash が使われ、無いと PowerShell が使われます。ネット上の記事はほぼ Bash 前提で書かれているため、入れておくほうが情報との齟齬が減ります。

見つけられないときは、設定ファイルでパスを指定できます。

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

7-2. npm run の VAR=value 形式が動かない

package.json に Unix スタイルのスクリプトを書いていると、Windows では失敗します。

{
  "scripts": {
    "dry": "DRY_RUN=true tsx src/digest.ts"
  }
}

これを npm run dry で実行すると、次のエラーになります。

'DRY_RUN' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

原因は、Windows の npm がスクリプトを既定で cmd.exe 経由で実行することです。Claude Code の Bash ツール自体が Git Bash で動いていても、npm スクリプトの中身は cmd.exe が解釈します。

ローカルで動作確認したいときは、npm run を介さず Bash から直接渡します。

DRY_RUN=true npx tsx src/digest.ts

なお GitHub Actions（Ubuntu）上では npm run 経由でも問題なく動きます。この制約はローカル Windows での確認時だけです。

7-3. gh api の先頭スラッシュが書き換えられる

GitHub CLI を Git Bash から叩くと、こうなります。

gh api /users/villhell/settings/billing/actions

invalid API endpoint: "C:/Program Files/Git/users/villhell/settings/billing/actions".
Your shell might be rewriting URL paths as filesystem paths.

原因は Git Bash（MSYS）のパス変換です。先頭がスラッシュの引数を、Windows のファイルパスとみなして書き換えてしまいます。

対処は、先頭のスラッシュを省くことです。

gh api users/villhell/settings/billing/actions

同じ理由で reg コマンドの /v /f オプションも壊れます。こちらは環境変数を付けて回避します。

MSYS_NO_PATHCONV=1 reg query "HKCU\Environment" /v PATH

8. 「できました」を確認する習慣

エージェントは自信を持って間違えます。完了報告をそのまま信じないでください。

最低限、次の4つは自分で回します。

# 1. ビルドが通るか
npm run build

# 2. 型が通るか
npm run typecheck

# 3. テストが通るか
npm test

# 4. 差分が意図どおりか
git diff

ビルドが通ることと、機能が正しいことは別です。 型エラーが消えただけで「直りました」と報告されるケースはよくあります。UI を変えたなら、実際に画面を開いて確認してください。

この確認を毎回やるのが面倒なら、CLAUDE.md に書いてしまうのが手です。

## 完了報告の前に必ず実行する

1. `npm run build`
2. `npm run typecheck`
3. `npm test`

いずれかが失敗した状態で「完了」と報告しない。
実行していない検証を実行したと書かない。

9. 次の一歩

ここまでで、Claude Code を安全に使い始める準備が整いました。次に効いてくるのは次の3つです。

• 効果レベル（effort）の使い分け — タスクの複雑さに応じて思考の深さを変えると、速度とコストのバランスが取れます
• Codex との併用 — 設計・レビューと実装を別のエージェントに分けると、片方の判断をもう片方が検証する形になります（Claude Code と Codex の役割分担）
• MCP サーバー連携 — 外部システムとのやり取りをエージェントに直接任せられます

いずれも、まず3章の課金の確認と5章の許可モードを押さえてからで十分です。動かす前に、自分がどの認証で、どこまで許可しているかを把握しておく。 これが一人で回すうえでいちばん効きました。

---

出典

本記事で引用した公式ドキュメント（いずれも2026-08-03時点で確認）

• Advanced setup — システム要件、インストール、Windows での設定
• Environment variables — ANTHROPIC_API_KEY の挙動
• Authentication — 認証情報の優先順位
• Choose a permission mode — パーミッションモード
• How Claude remembers your project — CLAUDE.md

3章の実体験、7-2 と 7-3 のエラーは、いずれも筆者の環境で実際に発生したものです。