Claude Code CLI ドキュメント — 公式ドキュメントの網羅範囲、不足している点、そして私が毎日実際に使っている機能 | OpenAIToolsHub

訳者注: この記事はAI翻訳ベースで、Jim Liu（シドニーの個人開発者）が用語と文章の自然さを校閲しました。誤訳や不自然な表現があれば、メールでご指摘ください。原文（英語）: English.

Claude Code CLI ドキュメント — 現場の開発者が教える「ドキュメントの行間」

クイックサマリー（TL;DR）

Anthropic の公式 Claude Code CLI ドキュメントは code.claude.com/docs/en/ にあります。 クイックスタート、コマンドリファレンス、コスト、スキルなどは正確です。しかし、現場の開発者が最初の1週間で直面するいくつかの重要なポイントについては説明が不足しています。
ドキュメントで補いきれなかった5つの重要事項： スラッシュコマンドの引数パース、フック（hook）の終了コード、再起動時の MCP サーバーのライフサイクル、正しく読み込まれる Skills フロントマター、そして出力スタイル（output styles）とプロジェクトルール（CLAUDE.md）の優先順位について。
隠れた重要トピック： ~/.claude/ ディレクトリの構造そのものです。公式ドキュメントは各パーツを個別に説明していますが、commands/、skills/、hooks/、mcp/、settings.json がどう組み合わさっているかの全体像（マップ）が欠けています。この記事でそれを図解します。
セットアップの結論：インストールの手順と最初の対話については公式のクイックスタートで十分です。それ以降は、GitHub のリリースノートやコミュニティガイドを参考にすることをお勧めします。新機能については、ドキュメントが実態に追いつくのに1週間ほどタイムラグがあるためです。

私の Claude Code 活用法（リアルのセットアップ）
公式ドキュメントが優れている点
今週直面した、ドキュメントにない5つのギャップ
~/.claude/ の解剖図 — ドキュメントに書かれていないマップ
ドキュメント vs 現場のリアル — 正直な比較
クイックスタートから日常使いへの5ステップ
FAQ

私の Claude Code 活用法（リアルのセットアップ）

シドニーを拠点に、Cloudflare Workers と Postgres VPS で5つのサイトを運営している個人開発者のジムです。Claude Code は、私の毎日の業務でターミナルに常に開いている CLI です。セットアップ環境は：macOS（M2 MacBook Pro, fish shell）と、本番環境用スクリプトを動かす Hostinger の Ubuntu VPS。どちらも同じ Anthropic アカウントで認証しています。

私はデスクトップアプリは使いません。CLI を使う最大の利点は、エージェントが Git と同じファイルを読み込み、実際のシェルと直接やり取りできる点にあるからです。

今週、私はあえてドキュメントのタブをすべて閉じ、claude code --help と ~/.claude/ ディレクトリの中身だけで作業をしてみました。その結果、どうしてもドキュメントを読み返さざるを得なかった（そしてドキュメントに答えがなかった）5つのポイントが以下です。

公式ドキュメントが優れている点

誤解のないように言っておきますが、Anthropic のドキュメント（code.claude.com/docs/en/）は以下の点において非常に優秀です。

インストールと認証： npm インストール、claude auth login のフロー、API キーとサブスクリプションの違いなどは、非常に明快です。
CLI フラグのリファレンス： --print, --continue, --resume, --allowedTools, --mcp-config などは正確で、新機能追加後も数週間以内に更新されています。
コストとレート制限： /docs/en/costs のページは、セッション制限や Pro / Max プランの仕組みについて正直に記載されています。
最初の対話： クイックスタートでは「ただ設定する」だけでなく、実際に何かをさせるまでの流れが解説されています。

ゼロの状態から、最初の有益な対話を15分以内に開始させるという点において、公式ドキュメントは素晴らしい基準をクリアしています。

今週直面した、ドキュメントにない5つのギャップ

ギャップ1（火曜日）：スラッシュコマンドの引数パース。 サイトのスラッグを受け取って適切な Wrangler コマンドを実行する /deploy <site> コマンドを作りたかったのですが、ドキュメントにはスラッシュコマンドが ~/.claude/commands/*.md にあり、$ARGUMENTS を受け取ることしか書かれていません。複数の位置引数をどうパースするかの記載がないのです。結局、GitHub で他の開発者のリポジトリを見て、シェルツールを使って自分で $ARGUMENTS を分割する必要があると知りました。ビルトインの $1 $2 のような変数はありません。解決策として、現在はコマンド内で read -r site rest <<< "$ARGUMENTS" を使っています。

ギャップ2（水曜日）：フック（hook）の終了コードのセマンティクス。 git push --force をブロックするために PreToolUse フックを設定しました。ドキュメントには「ゼロ以外の終了コードでツール呼び出しをブロックする」とありますが、大事なことが抜けています。終了コード 2 を返さないと、フックの stderr（標準エラー出力）がモデルに返されず、エージェントが「なぜブロックされたか」を理解できないのです。コード 1 だと汎用エラーとして処理され、Claude は別の方法を試そうとしてしまいます。これに気づくまで15分ほど無駄にしました。

ギャップ3（水曜日の午後）：シェル再起動時の MCP サーバーのライフサイクル。 カスタム MCP サーバーを運用していますが、新しいターミナルセッションを開始すると、claude code が MCP サーバーを二重に生成してしまうことがありました。.mcp.json への登録方法は書かれていますが、セッションをまたいだライフサイクルや古いプロセスの検知については何も書かれていません。結論（GitHub Issue より）：CLI はセッション間でサーバーを再利用せず、各セッションが独自のサーバーを開始します。二重に見える場合は、前のクラッシュによるゾンビプロセスです。解決策として、セッション開始前に pkill -f "node my-mcp-server" を実行するようにしています。

ギャップ4（木曜日）：正しく読み込まれる Skills のフロントマター。 Skills は比較的新しい機能で、ドキュメントには YAML フロントマター（name, description）の記述があります。しかし、このローダーがいかに厳格であるかについては触れられていません。name フィールドの末尾にスペースがあったり、スマートクォート（“”）を使っていたり、tags フィールドの形が少しでも違うと、警告なしに Skill が読み込まれません。1時間ほどハマりましたが、既知の正常な Skill のフロントマターをバイト単位でコピーして書き換えることで解決しました。

ギャップ5（金曜日）：出力スタイルと CLAUDE.md の干渉。 出力スタイル（~/.claude/output-styles/*.md）とプロジェクトごとの CLAUDE.md は、どちらもシステムコンテキストに影響を与えます。しかし、その優先順位はどこにも書かれていません。試行錯誤の結果：ルールの内容（実質的な指示）についてはプロジェクトの CLAUDE.md が優先されますが、出力スタイルはフォーマット（長さやヘッダーなど）に影響し続けます。「常に一行で回答する」という出力スタイルを、「常に TODO の概要を表示する」というプロジェクトルールよりも優先させることはできません。実体はプロジェクトファイル、形状はスタイルが優先されるという関係です。

~/.claude/ の解剖図 — ドキュメントに書かれていないマップ

数ヶ月使い込んでわかった、ディレクトリ構造の全体像です。

パス	役割	読み込みタイミング
`~/.claude/settings.json`	パーミッション、フック、MCP 設定（ユーザーレベル）	毎セッション
`~/.claude/CLAUDE.md`	個人のグローバルルール	毎セッション
`~/.claude/commands/*.md`	個人のスラッシュコマンド	`/<name>` 実行時
`~/.claude/skills/<name>/SKILL.md`	個人の Skills（自動起動）	モデルが必要と判断した時
`~/.claude/output-styles/*.md`	出力スタイルのルール	名前でアクティブにした時
`~/.claude/hooks/*.sh`	ツール実行前後のフック	ツール呼び出し前後
`./.claude/` (プロジェクト内)	プロジェクト単位の設定（ユーザーレベルを上書き）	プロジェクトディレクトリ内
`./.mcp.json`	プロジェクトの MCP サーバー登録	ディレクトリでのセッション開始時
`./CLAUDE.md`	プロジェクトのルール — ユーザーレベルより優先	ディレクトリでのセッション開始時

ドキュメントに最初から書いておいてほしかったルールは2つ：「プロジェクト設定はユーザー設定を上書きする」こと、そして「Skills は自動的に呼び出されるが、Commands は明示的に呼ぶ必要がある」ことです。これさえわかれば、あとはリファレンスだけで理解できます。

ドキュメント vs 現場のリアル — 正直な比較

トピック	公式ドキュメントの深さ	実務で必要な深さ
インストール + 最初の対話	素晴らしい	ドキュメントだけでOK
CLI フラグリファレンス	素晴らしい	ドキュメントだけでOK
スラッシュコマンド	表面的な解説のみ	ドキュメント + コミュニティのリポジトリを参考にする
フック	終了コードへの言及はあるが詳細は不明	ドキュメント + 動作するフックのソースを読む
Skills	フォーマットの記述のみ	最初は正常な SKILL.md をコピーして使う
MCP	設定方法は網羅されているがライフサイクルは不明	ドキュメント + GitHub Issue を確認する
出力スタイル	定義はあるが組み合わせは不明	空のプロジェクトで試行錯誤する
コストと制限	正直かつ最新	ドキュメントだけでOK

私は常に Anthropic のドキュメントとコミュニティのガイドを併用しています。それぞれカバーしている範囲が異なるからです。

クイックスタートから日常使いへの5ステップ

運用ガイド (🧭):

公式のクイックスタートを完了させる。 インストールと認証のフローは正確なので、飛ばさずにやりましょう。
自分でスラッシュコマンドを1つ書いてみる。 git status を実行して要約するだけの /git-status などで十分です。これで $ARGUMENTS が単一の文字列であり、自分でパースが必要なことが学べます。
MCP サーバーを1つインストールする。 Anthropic の filesystem MCP が最も手軽です。セッションログを見て、いつ起動し、いつ終了するかを確認しましょう。
メインプロジェクトに ./CLAUDE.md を追加する。 3つほどルールを書き、ユーザーレベルのルールが上書きされるか確認してください。これで優先順位が理解できます。
コミュニティの Skill を1つ導入する。 公開されているリポジトリから SKILL.md をそのままコピーし、1行だけ変えて読み込まれるか確認しましょう。これを一度やれば、ドキュメントが単なる「チュートリアル」ではなく「リファレンス」として機能し始めます。

FAQ

公式ドキュメントはどこにありますか？ code.claude.com/docs/en/ です。リファレンスページは常に最新の状態が保たれています。

ドキュメントは正確ですか？ インストール、認証、CLI フラグ、コストについては「はい」です。カスタマイズ（コマンド、フック、スキル、MCP、スタイル）については、正確ですが情報が不足しています。コミュニティのリソースを併用してください。

新機能がドキュメントに反映されるまでどのくらいかかりますか？ 経験上、約1週間です。まずバイナリにフラグが追加され、次に GitHub のリリースノート、最後にウェブサイトという順番です。

オフラインで実行できますか？ いいえ。ローカルの MCP サーバーを使用している場合でも、エージェントは各ターンごとに Anthropic の API を呼び出します。2026年4月現在、オフラインオプションはありません。

著者について

ジム・リュウ（Jim Liu） — シドニーの独立開発者。OpenAI Tools Hub、LowRiskTradeSmart などを Cloudflare + Next.js で運営。実際に自腹で支払って毎日使っている CLI ツールについて執筆しています。

日本のエンジニア視点で補足

国内ではClaude 3.5 Sonnetの日本語表現の自然さとコーディング精度の高さから、Cursorと並んで本CLIへの注目が非常に高まっています。ZennやQiitaでは特にMCP（Model Context Protocol）を活用した独自ツールとの連携事例が多く、日本語特有の仕様書を読み込ませるフローが定石化しつつあります。API経由の従量課金によるコスト管理は課題ですが、CLAUDE.mdに「日本語で返答して」と一行添えるだけで、開発体験が劇的に向上する点は国内の個人開発者からチーム開発まで広く支持されています。