Claude Codeの設定とワークフロー

音声は3本です。

• 🎧 設定の置き場所原稿を読む
• 🎧 プランと反復原稿を読む
• 🎧 継続的インテグレーション原稿を読む

この章でできるようになること

指示、コマンド、スキル、パスごとの規約を、届くべき人にだけ届く場所へ置ける。大きい変更の前に調査と設計を分け、小さい既知の修正はすぐ適用できる。文章でぶれる変換を、入出力の対とテストで狭められる。パイプラインでは入力待ちを起こさず、機械が読める指摘を、前回の指摘と重複させずに出せる。

30秒で全体像

CLAUDE.md は利用者、プロジェクト、ディレクトリの三層です。共有したい指示はリポジトリ側に置きます。利用者のホームに置いた指示は、その人のセッションにしか効きません。散らばった種類のファイルへ規約を自動で載せるのは、ディレクトリの CLAUDE.md ではなく .claude/rules/ の glob です。常に読んでほしい標準は CLAUDE.md、必要なときだけ呼ぶ手順はスキル、全員が使うスラッシュコマンドは .claude/commands/ です。スキルの context: fork は長い出力を本会話から出します。アーキテクチャと多数ファイルはプランモード、範囲が見えている単一ファイルは直接実行です。パイプラインは -p で非対話にし、--output-format json と --json-schema で指摘の形を固定します。書いたのと同じ会話に、その変更のレビューをさせません。

用語

フロントマターで覚える名前は、context: fork、allowed-tools、argument-hint、ルール側の paths です。エージェントSDKの allowedTools は、親が子を起動するための許可リストです。スキルの allowed-tools は、そのスキルの実行中だけツールを絞る別の綴りです。ハイフンの有無で別物です。

本編

指示が同僚に届かないときは、層を疑う

利用者レベルの ~/.claude/CLAUDE.md は、その人の機械のセッションにだけ読み込まれます。そこに「テストは失敗名を書け」とあっても、隣の人がクローンしたリポジトリにはファイルがありません。新しいメンバーだけ規約を外すときは、指示がホームに寄っています。

プロジェクトレベルは .claude/CLAUDE.md か、リポジトリ直下の CLAUDE.md です。ここが共有面です。両方に矛盾した文があると、どちらが効いたかを想像で決めず、/memory で今読み込まれているファイルを見ます。セッションごとのぶれは、読み込まれたファイルの差であることが多いです。

ディレクトリの CLAUDE.md は、そのサブツリーに紐づきます。src/api/ のエラー形式には向きます。テストファイルが実装の隣に散らばる構成では、テストがあるディレクトリの数だけファイルを複製することになり、一つ直すと残りが古くなります。散在は次の glob の仕事です。

巨大な一枚は、無関係な節まで毎ターンの文脈に入ります。分け方は二つです。@import で、パッケージの担当者が知っている標準ファイルだけを、そのパッケージの CLAUDE.md から引きます。全員の文脈に全標準を入れません。もう一つは .claude/rules/ に話題別ファイル（テスト、API、デプロイ）を置くことです。話題が常に必要ならルールファイルを条件なしで読み、ファイル種別だけに必要なら paths を付けます。

コマンド、スキル、常時指示は別の寿命を持つ

クローンした全員が /review を打てるようにするなら、定義は .claude/commands/ のファイルです。~/.claude/commands/ は個人用で、プルしても現れません。CLAUDE.md にコマンドの手順を書いても、スラッシュコマンドとしては登録されません。指示と、呼び出し単位のコマンドは別の仕組みです。存在しない設定配列にコマンド名を書く、という第三の場所はありません。

スキルは .claude/skills/ の SKILL.md です。常時読み込まれる標準ではなく、作業の名前で呼ぶ手順です。規約をスキルに閉じると、呼び忘れたターンには規約が消えます。常に守ってほしいことは CLAUDE.md か、パスが一致したルールです。

context: fork は、スキルを分離した会話で実行し、本会話には結論だけを戻します。コードベースの探索や、案の発散は出力が長く、本会話に残すと次の実装の予算を食います。フォークしないスキルは、その長いログが本会話の履歴になります。

allowed-tools は、スキルのあいだに使えるツールを絞ります。破壊的な操作をさせないスキルなら、書き込みや、さらに狭い読み取りだけを列挙し、シェルを外します。絞りはスキルの間だけです。親エージェントの allowedTools とは別の設定です。

argument-hint は、引数なしで呼ばれたときに、必須のパラメータを利用者へ尋ねるヒントです。ヒントが無いと、モデルは空の引数で手順を始め、対象ファイルを推測します。

個人の好みで共有スキルを書き換えると、チームの手順が変わります。別名の変種を ~/.claude/skills/ に作り、共有のファイルは触りません。

パスの glob は、編集したときだけ規約を載せる

.claude/rules/ のファイルに、フロントマターの paths で glob を書きます。terraform/**/* はその木を編集するときだけ、**/*.test.tsx は場所を問わずテストを編集するときだけ読み込まれます。一致しないファイルを編集しているターンには、その規約のトークンを払いません。

ルートの CLAUDE.md に全規約を書き、「該当の節を選べ」と頼むのは、一致がモデルの推測です。テストの隣に実装があるモノレポでは、推測は実装用の節をテストへ適用します。スキルに規約を入れると、自動ではなく呼び出し待ちになります。ディレクトリの CLAUDE.md は、散らばったテストを一枚で覆えません。自動かつ編集時だけ、を満たすのは paths です。

プランモードは、手戻りがコードより高いとき

プランモードは、変更を確定する前に、リポジトリを調べ、境界と手順を文章にします。向くのは、変更が大きい、妥当な案が複数ある、サービスの境界を決める、数十のファイルに触る、という仕事です。マイクロサービスへの分割、広範囲のライブラリ移行、インフラの要件が違う二つの統合方式、はここに入ります。先にコードを書くと、境界が間違っていたとき差分の破棄が調査より高くなります。

直接実行は、何を変えるかがすでに分かっているときです。スタックトレースが一つのファイルの一行を指している。日付の検証を一つの関数に足す。調査を挟むと、同じ結論に到達するまでの往復が増えるだけです。

調査ログが長いフェーズは、Explore というサブエージェントに渡し、要約だけを本会話へ戻します。プランモードの中でも、生の検索結果を本会話に積むと、設計を書く頃には窓が探索で埋まっています。複数フェーズの仕事は、探索を外へ出し、設計の会話を短く保ちます。

組み合わせてよいです。移行の調査と方式の選択はプランモード、選んだ方式の機械的な適用は直接実行、です。複雑さが途中で見えるかもしれないから最初から直接、というのは、要件の時点で再編だと分かっている仕事には向きません。調査せずに完全な事前指示だけを渡して直接実行するのも、境界がコードの中にしか無いときは危険です。指示は、まだ読んでいない依存を想像で固定します。

反復は、形容詞ではなく観測で進める

「もう少し堅く」は、人によって別の変換になります。入力と望む出力を二つか三つ見せると、変換の定義が共有されます。例は完成形だけでなく、端（空文字、null、全角の数字）を一つ入れます。端を入れないと、モデルは典型例の形だけを覚えて、null で落ちます。

実装の前に、期待する挙動、端、性能の上限をテストとして置き、失敗の出力を一緒に渡して直すと、直ったかどうかがテストで決まります。失敗を隠して「いい感じに」と頼むと、メッセージは成功に見えて同じ端が残ります。

不慣れな領域では、実装の前に質問させます。キャッシュの無効化、障害時に古い値を返すか、キーの衝突。頼む側が想定していない考慮が、質問として出てから実装に入ります。質問を飛ばして書き始めると、無効化の抜けがレビューまで残り、差分が大きくなってから設計が変わります。

問題の渡し方は依存で分けます。互いに影響する不具合（同じ関数の条件と、そのテストの期待値）は、一つのメッセージにまとめます。分けて直すと、先の修正が後の前提を壊します。独立した不具合（別パッケージの誤字と、無関係な日付検証）は順に直します。一度に混ぜると、片方の差分がもう片方の失敗を隠します。

パイプラインは、人の入力を待てない

対話の Claude Code は、確認の質問で止まります。ジョブに人がいません。-p（--print）は、プロンプトを処理し、結果を標準出力へ書き、入力を待たずに終了します。環境変数でヘッドレスにする、という名前の仕組みや、--batch というフラグは、この起動の代わりになりません。標準入力を捨てるだけでも、プログラムが質問を出して待つのを止められません。止めるのは -p です。

指摘をプルリクエストの行へ機械で付けるなら、文章ではなく構造です。--output-format json と --json-schema で、ファイル、行、重大度、本文の欄を固定します。自由文は、投稿スクリプトが行番号を読み違えます。

パイプラインから見たプロジェクトの基準は、CLAUDE.md に置きます。価値のあるテストとは何か、どのフィクスチャが使えるか、どのスタイルは指摘しないか。ここが空だと、体裁だけのテストと、スタイルの指摘が増えます。既存のテストファイルも文脈に渡し、すでに覆っているケースを再提案させません。

新しいコミットのあとに再レビューするときは、前回の指摘を文脈に含め、新規か未対応だけを報告させます。含めないと、同じ行に同じコメントが累積します。

コードを書いた会話に、その差分のレビューを頼むと、生成のときの理由が履歴に残っています。モデルはその理由を疑いにくいです。レビューは、差分と基準だけを渡した別の実行にします。思考を長くさせる指示を同じ会話に足しても、自分の前提は残ります。別実行のほうが、細かい矛盾に気づきます。この分離は、次の章の複数パスと同じ理由です。

リポジトリに並ぶファイルで層を見る

共有したい最小の木は、次のような並びです。ルートの CLAUDE.md には、言語、テストの実行コマンド、指摘しないスタイル、だけを書きます。.claude/rules/testing.md の paths はテストの拡張子、.claude/rules/api.md の paths は src/api/** です。.claude/commands/review.md は全員の /review です。.claude/skills/migrate/SKILL.md は、ライブラリ移行の手順で、context: fork と、読み取り中心の allowed-tools を持ちます。秘密はどこにも書きません。MCPは .mcp.json に環境変数の参照だけです。

ホーム側に同じ review.md を置くと、その人の機械では個人コマンドが勝ち、リポジトリの手順と違うレビューが走ります。チームで見たときだけ再現しない不具合は、個人の commands と skills を空にしてから再現します。

/memory の出力にホームのファイルだけがあり、プロジェクトのファイルが無いときは、開いているディレクトリがリポジトリのルートではありません。サブディレクトリから起動して、ルートの CLAUDE.md が探索の外にいる、という失敗です。起動ディレクトリを戻して、もう一度一覧を見ます。

スキルのフロントマターが、何を隔離するか

context: fork が無い探索スキルは、見つけたファイルの中身を本会話へ全部貼ります。そのあと実装を頼むと、モデルは貼られた中身の一部だけを見て、残りを忘れます。フォークすると、本会話に残るのは「変更すべきファイルは三つ、理由は有効期限の比較」のような結論です。結論にファイル名が無いフォークは、本会話が結論を使えません。スキルの最後の指示は、ファイル名と判断だけを返せ、と書きます。

allowed-tools にシェルが含まれる調査スキルは、テストのつもりでマイグレーションを実行できます。読み取りのスキルなら、Read、Grep、Glob だけにします。書き込みが必要な適用スキルは、別スキルに分け、フォークせずに本会話で差分が見えるようにします。隔離と適用を一つのスキルにすると、適用の差分がフォークの中に閉じて、利用者が差分を見ないまま終わります。

プランモードで先に書くもの

再編のプランに書くのは、残す境界、動かすモジュール、触らないディレクトリ、最初の検証コマンド、です。コードの断片を大量に貼ったプランは、調査ログです。方式の選択が文章になっていないと、直接実行へ移ったときにモデルは別の境界を発明します。プランを承認してから直接実行へ移り、プランのファイルをその会話の文脈に残します。承認せずに「だいたいこの方向で」と口頭で移ると、プランの制約が次のターンで落ちます。

単一ファイルの欠陥でプランモードに入ると、調査の往復のあいだに利用者が待たされ、結論は最初のスタックトレースと同じ行です。直接実行へ戻す基準は、変える場所が一つのシンボルに特定できていることです。特定できていないなら、それは小さい欠陥に見えて、実は境界の問題です。プランモードへ上げます。

パイプラインの一回の実行で渡すもの

プロンプトには、差分、基準のファイルの場所、前回の指摘のJSON、既存テストのパスを書きます。リポジトリ全体を無関係に読ませると、指摘がスタイルへ逃げます。スキーマは、ファイル、行、重大度、本文、既出の指摘と同じなら duplicate を立てる欄、です。投稿スクリプトは duplicate が真の行をスキップします。前回の指摘をプロンプトに入れ忘れると、この欄は常に偽になり、同じコメントが二度付きます。

書いた会話でレビューしない、をパイプラインで実現するには、生成ジョブとレビュージョブを別プロセスにします。生成のログをレビューのプロンプトへ貼ると、別プロセスでも自己レビューと同じ履歴を再構成してしまいます。レビューへ渡すのは差分と基準だけです。

一つの規約を、六つの置き場所で迷ったとき

規約は「テストの失敗メッセージには、期待値と実際の値を書く」です。置き場所は、誰が、いつ、その文を読むかで決まります。

自分の機械だけで、どのリポジトリでも効かせたいなら ~/.claude/CLAUDE.md です。隣の人のクローンには届きません。チームの再現しない指摘は、まずここを空にしてから見ます。

クローンした全員に、毎ターン効かせたいなら、ルートの CLAUDE.md か .claude/CLAUDE.md です。両方に矛盾した文があるとき、どちらが勝つかを想像で決めず、/memory で読まれているファイルを見ます。一覧にプロジェクトのファイルが無いときは、起動したディレクトリがルートではなく、探索が届いていません。

src/api/ のエラー形式だけなら、そのディレクトリの CLAUDE.md です。テストが実装の隣に散らばるなら、ディレクトリの複製はすぐ古くなります。.claude/rules/ に paths: "**/*.test.tsx" を書きます。実装ファイルを編集しているターンには、そのトークンを払いません。ルートの一枚に全規約を書き「該当の節を選べ」は、選択がモデルの推測です。推測は実装の節をテストへ適用します。

全員が /review と打つ手順は .claude/commands/ です。CLAUDE.md に手順を書いても、スラッシュコマンドにはなりません。~/.claude/commands/ に同名があると、その人の機械だけ別のレビューが走ります。

呼び出したときだけ読む長い手順はスキルです。常に守ることをスキルに閉じると、呼び忘れたターンには規約が消えます。

スキルが隔離するものと、隔離してはいけないもの

探索スキルに context: fork が無いと、見つけたファイルの中身が本会話へ全部残ります。そのあと実装を頼むと、モデルは貼られた中身の一部だけを見て、残りを忘れます。フォークすると、本会話に残るのは結論です。結論の指示を「ファイル名と判断だけを返せ」と書かないと、本会話は結論を使えません。

読み取りのスキルの allowed-tools は Read、Grep、Glob だけにします。シェルが含まれると、調査のつもりでマイグレーションを実行できます。書き込みが必要な適用は別スキルにし、フォークしません。差分がフォークの中に閉じると、利用者は差分を見ないまま終わります。

allowed-tools はスキルのあいだだけの綴りです。親が子を起動する allowedTools とは別です。ハイフンの有無を揃えて一つにすると、片方の設定がもう片方を絞ったつもりで、どちらも変わりません。

argument-hint が無いスキルは、対象ファイルを推測して走ります。必須のパスは、空で呼ばれたときに利用者へ尋ねさせます。

個人の好みで共有の SKILL.md を書き換えると、チームの手順が変わります。別名を ~/.claude/skills/ に置きます。

途中で、プランと直接の境界が動く

最初の報告は「session.ts の比較が一日になっている」です。スタックトレースが一つの関数を指しているなら、直接実行です。プランモードに入ると、同じ行に戻るまでの往復だけが増えます。

読み始めて、比較がミドルウェアと各ハンドラの二箇所にあり、有効期限の置き場所がサービス境界だと分かったら、そこで直接実行を止めます。プランに書くのは、残す境界、動かすモジュール、触らないディレクトリ、最初の検証コマンドです。コード断片の貼り付けは調査ログで、方式の選択になっていません。承認したプランのファイルを、次の直接実行の文脈に残します。「だいたいこの方向で」と口頭で移ると、制約は次のターンで落ちます。

妥当な案が二つある移行は、最初からプランです。選んだ方式の機械的な置換だけを、そのあと直接実行にします。調査ログが長いあいだは Explore に渡し、本会話にはファイル名と理由だけを戻します。生の検索を本会話に積むと、設計を書く頃には窓が探索で埋まっています。

ぶれを、観測の単位で狭める

「日付の検証をもう少し堅く」は、人によって別の関数になります。入力と望む出力を二つ、端を一つ、見せます。空文字、null、全角の数字。端が無いと、典型例の形だけを覚えて null で落ちます。

直ったかの判定は、先に置いたテストです。失敗の出力を一緒に渡します。失敗を隠して「いい感じに」と頼むと、メッセージは成功に見えて同じ端が残ります。

不慣れなキャッシュなら、実装の前に質問させます。無効化のタイミング、障害時に古い値を返すか、キーの衝突。質問を飛ばすと、無効化の抜けがレビューまで残り、差分が大きくなってから設計が変わります。

同じ関数の条件と、そのテストの期待値は、一つのメッセージにまとめます。分けて直すと、先の修正が後の前提を壊します。別パッケージの誤字と、無関係な日付検証は順に直します。一度に混ぜると、片方の差分がもう片方の失敗を隠します。

パイプラインが、指摘を一行にするまで

ジョブに人はいません。対話の確認で止まる起動は、ここで使えません。-p はプロンプトを処理し、結果を出して終了します。ヘッドレスという名前の環境変数や、--batch は、この停止の代わりになりません。標準入力を捨てても、プログラムが質問を出して待つことは残ります。

プロンプトに渡すのは、差分、基準のファイル、前回の指摘、既存テストのパスです。リポジトリ全体を無関係に読ませると、指摘はスタイルへ逃げます。基準そのものは CLAUDE.md に置きます。価値のあるテスト、使えるフィクスチャ、指摘しないスタイル。ここが空だと、体裁だけのテストが増えます。

--output-format json と --json-schema で、ファイル、行、重大度、本文、既出なら duplicate の欄を固定します。投稿スクリプトは duplicate が真の行を落とします。前回の指摘をプロンプトに入れ忘れると、この欄は常に偽になり、同じ行に同じコメントが二度付きます。

生成とレビューは別プロセスです。生成のログをレビューのプロンプトへ貼ると、別プロセスでも、書いたときの理由が履歴として再構成されます。レビューへ渡すのは差分と基準だけです。同じ会話で見直すと、モデルはその理由を擁護します。思考を長くする指定も、同じ履歴の上で起きます。

読み込みの失敗を、/memory の一覧で見る

一覧がホームのファイルだけなら、プロジェクトの指示は届いていません。起動ディレクトリをルートへ戻します。

一覧にプロジェクトとホームの両方があり、指摘が人によって違うなら、ホーム側の文が勝っていないかを見ます。共有したい文はプロジェクトへ移し、ホームからはその文を消します。

テストを編集しているのにテストのルールが無く、実装を編集しているときにテストのルールがあるなら、paths の glob が逆です。ディレクトリの CLAUDE.md を増やしても、散らばったテストは一枚で覆えません。

個人の review コマンドだけが走るなら、ホームの commands に同名があります。チームで揃えるなら、個人側を外し、リポジトリ側だけを残します。

どう判断するか

• 同僚に届かない指示は、利用者レベルのファイルを疑う。/memory で読まれているファイルを見る。
• 共有コマンドは .claude/commands/。常時の標準は CLAUDE.md。呼び出す手順はスキル。散在する自動規約は paths の glob。
• context: fork は本会話を守る。allowed-tools はスキル中のツールを絞る。argument-hint は引数の促し。SDKの allowedTools とは別。
• 大きい、複数案、多数ファイルはプランモード。分かっている小さい修正は直接実行。長い探索は Explore に要約させる。
• ぶれる変換は入出力を二、三個。影響し合う修正は一通、独立は順に。不慣れな領域は実装前に質問させる。
• パイプラインの停止は -p。機械が読む指摘は json とスキーマ。再レビューは新規と未対応だけ。書いた会話でレビューしない。

確認

問1

リポジトリをクローンした全員が使えるレビューコマンドを置きたい。ファイルはどこですか。

A. .claude/commands/
B. ~/.claude/commands/
C. ルートの CLAUDE.md の中だけ
D. 個人の ~/.claude.json

問2

テストが各実装の隣に散らばっています。編集したときだけ、同じテスト規約を自動で載せたい。どれですか。

A. .claude/rules/ に **/*.test.tsx の paths を書く
B. 全規約をルートの CLAUDE.md に書き、節の選択はモデルに任せる
C. 規約をスキルに入れ、毎回人が呼ぶ
D. テストがあるディレクトリごとに CLAUDE.md を複製する

問3

数十ファイルとサービス境界の判断が必要な再編です。最初の進め方はどれですか。

A. プランモードで調査し、方式を決めてから変更する
B. 直接実行で進め、境界は書きながら決める
C. 調査なしの完全な事前指示だけで直接実行する
D. 直接実行を始め、困ってからプランモードへ切り替える

問4

パイプラインのレビューが、確認の入力待ちで終わりません。どれを付けますか。

A. -p
B. 文書に無いヘッドレス用の環境変数
C. 文書に無い --batch
D. 標準入力を捨てるだけ

問5

説明文では変換結果がぶれます。次に足すものとして効くのはどれですか。

A. 「注意深く」という語
B. 端を含む入出力の対を二、三個
C. モデルの確信度の自己申告
D. 利用者レベルの CLAUDE.md への秘密のトークン

自分で確かめる

同じ規約文を、ホームの CLAUDE.md とプロジェクトの CLAUDE.md に分けて置き、別のディレクトリから開いたときにどちらが効くかを /memory で見てください。次に、**/*.test.* のルールが、実装ファイルを編集しているときには読み込まれないことを確認します。最後に、同じプロンプトを対話で実行して入力待ちになることと、-p を付けると終了することを、短いエコーで比べます。