Claude Code を継続的な業務環境へ変える

by

Claude Code は、対話欄へ依頼を書くだけでも、コードの修正、文書の生成、調査、テストの実行まで進められる。単発の作業であれば、この使い方でも効果は大きい。人間が一行ずつコードを書き、関連ファイルを探し、変更箇所を確認していた工程の一部を、自然言語による依頼へ置き換えられるからである。

ところが、同じ種類の作業を繰り返すと、別の負担が見えてくる。対象となる技術、変更してよい範囲、守るべき互換性、実行すべきテスト、成果物の保存場所を毎回説明しなければならない。Claude Code が変更を終えた後には、意図しないファイルへ触れていないか、既存の仕様を壊していないか、失敗した場合に元へ戻せるかを人間が確認する。生成や編集そのものは速くなっても、作業を成立させる前提、検証、復旧の方法は、利用者の記憶と注意力に残ったままである。

この状態では、Claude Code は作業の実行者にはなっても、同じ条件で繰り返し動く業務環境にはならない。利用者が条件を一つ書き忘れれば、その条件は存在しないものとして処理される。過去の指示文を保存して再利用しても、複数の場所に複製された規則は、更新される版と古いまま残る版に分かれる。作業品質のばらつきは、モデルの応答が毎回異なることだけではなく、モデルへ渡される前提そのものが一定していないことから生じる。

継続的な利用へ移るには、依頼文を長くするのではなく、作業条件を役割ごとに分離する必要がある。プロジェクト全体で常に守る前提は CLAUDE.md へ置き、特定のファイルや作業だけに適用する規則は .claude/rules/ へ分ける。変更前には Plan mode で対象と手順を確認し、権限設定と Hooks で実行可能な操作を制限し、チェックポイントによって編集前の状態へ戻せるようにする。安定して実行できるようになった手順は Skills へ固定し、その後に非対話実行、定期処理、サブエージェント、worktree、MCP へ広げる。利用者自身の判断基準を外部化して保持する考え方は、特定の AI サービス内に残る会話履歴だけへ依存しない文脈管理にもつながる[1]。

Claude Code が実際に利用する情報と能力は、その場の依頼文だけでは決まらない。作業ディレクトリに存在するファイル、端末で実行可能なコマンド、Git の差分とブランチ状態、CLAUDE.md、自動メモリ、読み込まれた Skills、サブエージェントの設定、MCP を通じて接続された外部サービスが、判断材料と実行範囲を構成する[2]。対話欄の文章が同じでも、作業ディレクトリ、権限、参照規則、接続先が異なれば、Claude Code が確認できる事実と選択できる操作は変わる。

Claude Code を実務へ組み込む作業は、モデルへ何を依頼するかを決めるだけでは完結しない。何を恒久的な前提として読ませるか、今回の作業でどの資料を参照させるか、どの操作を許可するか、実行前にどこで確認するか、失敗したときにどの単位まで戻せるかを設定する必要がある。これらが分離されて初めて、短い依頼と曖昧な依頼を区別できる。

利用段階 固定されるもの 作業上の変化 残る失敗条件
単発対話 目的、制約、対象ファイル、完了条件を、その都度の会話へ記述する。 小さな作業へすぐ着手できるが、同じ説明と確認を繰り返す。 説明漏れ、会話履歴の違い、参照対象の違いによって、同種作業でも判断が変わる。
前提固定 CLAUDE.md、rules、settings に、恒久条件と対象別条件を保存する。 対話欄では、作業固有の目的と対象だけを指定しやすくなる。 古くなった規則、重複した規則、相互に矛盾する規則も継続的に読み込まれる。
実行制御 Plan mode、権限設定、Hooks、チェックポイントによって、計画、操作、復旧方法を定める。 変更前の確認と、危険な操作の遮断と、編集後の巻き戻しを別の層で扱える。 誤った計画の承認、Hooks の対象漏れ、外部サービスへ確定済みの変更は残る。
手順化 入力条件、処理順序、検証方法、停止条件を Skills や非対話実行へ固定する。 同じ作業を、同じ工程と検証条件で再実行できる。 手順に含まれる誤りや古い判断も、安定した形で反復される。
並列化・外部連携 サブエージェントの役割、worktree の作業場所、MCP の接続先と権限を設定する。 複数の調査や変更を並行させ、ローカル作業から外部サービスの更新まで接続できる。 変更の競合、権限の過大化、誤った情報の外部反映によって、影響が他者の業務へ広がる。

1. 毎回ゼロから指示すると作業品質が安定しない

1.1 同じ依頼でも、渡された前提によって結果が変わる

「このスクリプトを修正する」という依頼は、一つの操作を指しているように見える。しかし、実際の修正方針を決めるには、依頼文に現れていない複数の条件が必要になる。POSIX shell の範囲を維持するのか、Bash 固有の構文を導入してよいのか、対応する OS とバージョンは何か、既存のコマンドライン引数を変更してよいのか、外部コマンドへの依存を追加できるのか、どのテストを通せば完了と判断できるのか。これらは実装上の細部ではなく、採用可能な修正案を限定する条件である。

不足する前提 Claude Code が選び得る処理 発生し得る結果
使用するシェル 配列、二重角括弧、プロセス置換など、Bash では一般的な構文を採用する。 /bin/sh で実行する環境では構文エラーとなり、既存の移植性が失われる。
互換性を維持する範囲 処理を簡潔にするため、引数名、終了コード、出力形式を変更する。 スクリプトを呼び出す cron、監視処理、別スクリプトが新しい動作へ追随できなくなる。
変更可能なファイル 対象スクリプトだけでなく、設定、テスト、文書も整合させるために編集する。 依頼者が維持しようとしていた設定や文書まで変更範囲が広がる。
完了条件 構文上の修正または局所的な動作確認だけで作業を終了する。 単体では動作しても、既存テスト、実行権限、呼び出し元との整合性が確認されない。

前提が欠けている場合、Claude Code は何も判断できなくなるわけではない。リポジトリ内の既存実装、一般的な開発慣行、周辺ファイルの書き方から、欠けた条件を補って作業を進める。その推測が妥当であれば、依頼者が詳細を書かなくても適切な修正が得られる。しかし、一般的に妥当な修正と、そのプロジェクトで採用可能な修正は一致するとは限らない。推測によって空白を埋められることが、プロジェクト固有の制約を満たしたことの証明にはならない。

この差が作業品質のばらつきとして現れる。あるセッションでは、直前の会話に POSIX shell の制約が残っているため移植性が守られる。別のセッションでは、その情報が存在せず、Bash 固有機能を使った短い実装が選ばれる。表面上は同じ依頼でも、Claude Code が参照できる状態が異なるため、候補となる実装も変わる。出力の不安定さは、モデル内部の確率的な選択だけではなく、セッションごとに異なる入力条件によって増幅される。

文書作成でも同じ構造が生じる。対象読者、文体、見出し構造、参考文献の形式、保存先、禁止表現を毎回の依頼へ書く運用では、書き忘れた条件がそのまま成果物から抜け落ちる。長い指示文をファイルへ保存して貼り付ける方法は、入力時間を短縮できるが、規則の管理場所を統一するとは限らない。複数の雛形に同じ規則が複製されれば、一方だけを修正した時点で規則の版が分岐し、どの版を基準に生成したか分からなくなる。

1
2
3
4
5
6
7
8
9
前提が会話内または複数の雛形に分散する
  ↓
セッションごとに渡される条件と規則の版が変わる
  ↓
Claude Code が参照できる制約と完了条件が変わる
  ↓
採用される実装、変更範囲、検証内容が変わる
  ↓
同じ名称の作業でも結果を再現できなくなる

再現性を高めるには、説明量を増やすのではなく、条件の置き場所を分ける必要がある。すべての作業で必要になる事実は恒久的な前提として保存し、対象ファイルにだけ適用する規則は条件付きで読み込ませ、その作業に固有の資料と目的だけを対話欄で指定する。この分離によって、指示を短くしても情報を減らさず、規則を更新する場所も限定できる。

1.2 短い指示で動くことと、曖昧な指示で動くことは異なる

対話欄へ入力する文字数が少ないことは、直ちに情報不足を意味しない。CLAUDE.md に技術的制約と検証方法があり、rules に対象ファイル固有の規則があり、今回変更するファイルと目的が明示されていれば、対話欄には作業ごとの差分だけを書けばよい。恒久条件を外部へ置くことで、短い指示の背後に、再利用可能な判断条件を持たせられる。

たとえば、プロジェクト側に「POSIX shell を使う」「既存の引数を維持する」「変更後に run_tests.sh を実行する」「対象外のファイルを変更しない」という規則が保存されているなら、今回の依頼は次の程度まで短縮できる。

1
2
3
4
scripts/backup.sh の終了コードが失われる問題を修正する。

変更前に原因と変更対象を示す。
既存の呼び出し方法は維持する。

この依頼は短いが、曖昧ではない。対象ファイル、観測されている不具合、維持すべき外部仕様、実行前の停止点が示されている。シェルの種類やテスト方法を対話欄で繰り返していないのは、それらを不要と判断したからではなく、別の場所で恒久条件として管理しているからである。

反対に、設定側にも会話側にも判断条件がない状態で「適切に直す」とだけ依頼すると、Claude Code は「適切」の内容を周辺実装から推定する。対象ファイルが明示されていなければ関連ファイルまで探索し、完了条件がなければ局所的な修正で終了するか、広い整合性修正まで進むかを自ら選ぶ。この状態では、利用者が委譲したのは実装作業だけではない。変更範囲、互換性、検証水準を決める判断まで、明示しないまま Claude Code 側へ渡している。

指示の状態 恒久条件 作業固有の指定 判断の所在
長く具体的 恒久条件も対話欄へ毎回記載する。 対象、目的、制約、検証方法を一つの依頼へまとめる。 判断条件は明確だが、再入力、更新漏れ、複製された規則の不一致が起こりやすい。
短く具体的 共通条件は CLAUDE.md、rules、settings で管理する。 今回の対象、変更目的、維持条件、停止点を指定する。 恒久条件と個別判断の境界が明確であり、同種作業へ再利用できる。
短く曖昧 必要な条件が保存されていない。 対象、完了条件、変更範囲を限定しない。 不足した条件を Claude Code が推測するため、利用者が意図せず判断権限まで委譲する。

指示の品質は、対話欄の長さではなく、作業に必要な状態がどこかに過不足なく存在するかで決まる。恒久条件を対話欄へ繰り返す必要はないが、今回だけ変わる対象、目的、維持条件、承認点は省略できない。共通条件を設定へ移し、作業固有の差分だけを対話で与える構造が、短い指示と曖昧な指示を分ける。

この区別を実際の環境へ落とし込む最初の作業が、CLAUDE.md と .claude/rules/ の役割分担である。全作業に適用する規則と、特定のファイルを扱うときだけ必要な規則を分けることで、Claude Code が毎回同じ条件を参照しながら、無関係な情報に判断を引きずられない構成を作れる。

2. CLAUDE.md と .claude/rules/ で判断条件を固定する

2.1 CLAUDE.md には常に必要な事実と規則を書く

CLAUDE.md は、毎回貼り付ける長文プロンプトの保管場所ではない。各セッションで繰り返し必要になるプロジェクトの事実、技術的制約、検証方法、変更時の判断基準を、Claude Code が作業を始める前から参照できる状態にするためのファイルである。公式文書でも、ビルドとテストのコマンド、設計上の決定、命名規則、プロジェクト構成、常に守る規則を CLAUDE.md に置き、複数工程の手順や特定部分だけに関係する指示は Skills やパス限定 rules へ分ける構成が示されている[3]。

ここで区別すべきなのは、プロジェクトについての事実と、個別作業の進め方である。「このリポジトリは Debian で動作する POSIX shell スクリプトを収録している」「既存のコマンドライン引数を維持する」「変更後は run_tests.sh を実行する」という情報は、どの修正でも判断に必要になる。一方、「今回の不具合について三つの修正案を比較する」「変更前に利用者の承認を待つ」という手順は、特定の作業や用途に依存する。後者まで CLAUDE.md に蓄積すると、すべてのセッションへ不要な工程が持ち込まれる。

情報の種類 記述例 適切な配置先 配置を誤った場合の影響
プロジェクトの事実 対象 OS、使用言語、ディレクトリ構成、主要な実行方法を記述する。 CLAUDE.md に置く。 会話だけに置くと、別のセッションでは前提が失われる。
常設する規則 互換性、命名、変更禁止範囲、必須テストを記述する。 CLAUDE.md または対象別 rules に置く。 指示文へ複製すると、規則の版が分岐しやすくなる。
対象限定の規則 シェルスクリプト、Python、文書などに固有の規則を記述する。 パス限定 rules に置く。 CLAUDE.md に集約すると、無関係な作業でも常時読み込まれる。
反復可能な手順 調査、変更、テスト、差分確認、報告までの工程を記述する。 Skills に置く。 CLAUDE.md に置くと、使わない作業手順が文脈を占有する。
今回だけの目的 対象ファイル、不具合、維持条件、今回の完了条件を記述する。 対話欄で指定する。 恒久設定へ入れると、一時的な条件が後続作業にも残る。

シェルスクリプトのリポジトリであれば、CLAUDE.md は次のように構成できる。規則は、守ったかどうかを作業後に確認できる表現まで具体化する。「適切にテストする」では、どの検証を実行すれば完了なのか決まらない。「変更後に ./run_tests.sh を実行し、結果を報告する」と書けば、実行する処理と報告すべき結果を同じ基準で確認できる。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Project overview

This repository contains POSIX shell scripts for Debian systems.

# Implementation rules

- Use /bin/sh syntax.
- Use command -v instead of which.
- Do not introduce Bash-specific syntax.
- Preserve existing command-line interfaces unless explicitly requested.
- Do not add external dependencies without explicit approval.

# Validation

- Run ./run_tests.sh after changing scripts.
- Run shellcheck when it is available.
- Report changed files, executed checks, and test results.
- Do not report success when a required check was skipped.

# File operations

- Do not delete or move files without explicit approval.
- Do not modify files outside this repository.
- Do not change generated files when their source file can be changed instead.

この設定によって減るのは、説明に使う文字数だけではない。実装前の選択と実装後の検品が、同じ規則へ接続される。Claude Code が Bash の配列を使う案を生成した場合、POSIX shell という実装規則に反していると判定できる。テストを実行せずに終了した場合は、検証規則を満たしていない。変更したファイルの報告がなければ、完了報告の条件が不足している。このように、CLAUDE.md は生成時の参考情報であると同時に、成果物を評価する基準にもなる。

ただし、CLAUDE.md に書かれた規則は、Claude Code の実行機構を強制的に制限する設定ではない。Claude Code は内容を文脈として読み、判断へ反映しようとするが、曖昧な指示、相互に矛盾する指示、過度に長い指示が含まれていれば、遵守の一貫性は下がる[3]。削除操作を確実に遮断する必要がある場合は、CLAUDE.md に「削除しない」と書くだけでなく、権限設定や Hooks で実行経路を制限しなければならない。

規則の競合は、同じファイル内だけで起こるとは限らない。利用者単位の CLAUDE.md、プロジェクトの CLAUDE.md、作業ディレクトリより上位にある CLAUDE.md、下位ディレクトリで遅延読み込みされる CLAUDE.md、CLAUDE.local.md、.claude/rules/ の内容が同時に文脈へ入る場合がある。上位の規則に「テストは変更後に実行する」とあり、下位の規則に「文書変更ではテストを省略する」とあれば、適用対象が明確でない限り判断が揺れる。

1
2
3
4
5
6
7
8
9
規則を追加する
  ↓
同種の規則が複数の場所へ分散する
  ↓
適用対象、優先関係、更新時期が一致しなくなる
  ↓
Claude Code が同時に異なる判断条件を参照する
  ↓
同じ規則群を使っているつもりでも結果が安定しなくなる

このため、CLAUDE.md の保守では、規則の追加だけでなく、重複の削除、対象範囲の限定、古い前提の更新が必要になる。公式文書では、CLAUDE.md を簡潔かつ具体的に保ち、目安として 200 行未満に抑え、長くなった対象別規則や手順を rules と Skills へ分ける考え方が示されている[3]。文字数を機械的に減らすことが目的ではなく、各セッションで常に必要な情報だけを残すことが目的である。

2.2 .claude ディレクトリは設定の役割と共有範囲で分ける

Claude Code は、プロジェクト内の .claude ディレクトリと、利用者のホームディレクトリにある ~/.claude から、設定、規則、Skills、サブエージェントなどを読み込む。プロジェクト側のファイルはリポジトリへコミットしてチームで共有でき、利用者側のファイルは複数のプロジェクトへ共通する個人設定として使える[4]。同じ機能を設定できる場合でも、どちらへ置くかによって影響範囲が変わる。

たとえば、リポジトリ全体で POSIX shell を必須とする規則は、プロジェクト側へ置く必要がある。特定の利用者だけが使う表示設定や、個人環境にしか存在しない試験用データの場所を共有設定へ入れると、ほかの端末では存在しないパスを前提とした構成になる。反対に、チーム共通のテスト方法を利用者側だけへ置けば、その設定を持たないメンバーや自動実行環境では同じ検証が行われない。

プロジェクト内の構成は、次のように役割ごとに分けられる。ここで .claude/hooks/ は Hooks の設定を自動的に読み込む特別な場所ではなく、settings.json から呼び出す検査スクリプトを整理するために設けたディレクトリである。Hooks のイベント、対象、実行コマンドは settings.json 側に定義する。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   ├── rules/
│   │   ├── shell-scripts.md
│   │   ├── python.md
│   │   └── documentation.md
│   ├── skills/
│   │   └── review-changes/
│   │       ├── SKILL.md
│   │       └── checklist.md
│   ├── agents/
│   │   └── reviewer.md
│   └── hooks/
│       └── block-destructive.sh
├── .mcp.json
└── .worktreeinclude
設定先 主な内容 共有範囲 運用上の注意
CLAUDE.md プロジェクトの目的、構成、技術制約、常設規則を置く。 リポジトリへコミットすればチームで共有できる。 常時不要な手順を蓄積すると、すべてのセッションで文脈を消費する。
CLAUDE.local.md 試験用データ、個人環境の URL、端末固有の作業条件を置く。 現在のプロジェクトにおける個人設定として使う。 通常は Git の管理対象から外し、機密情報そのものは記載しない。
.claude/settings.json 権限、Hooks、環境変数、サンドボックスなどのプロジェクト設定を置く。 リポジトリ単位でチームへ共有する。 共有すると他の利用者の操作範囲にも影響するため、個人環境のパスを含めない。
.claude/settings.local.json 個人だけに必要な上書き設定や一時的な試験設定を置く。 現在のプロジェクトと端末だけに適用する。 共有設定を変更せずに個人差を吸収できるが、ローカル依存の動作をチーム共通の仕様と混同しない。
.claude/rules/ 技術領域、ファイル形式、対象ディレクトリごとの規則を置く。 プロジェクト側と利用者側のどちらにも配置できる。 パス条件を付けない規則は常時読み込まれるため、対象範囲を確認する。
.claude/skills/ 必要時だけ利用する再実行可能な手順と、その補助資料を置く。 プロジェクトまたは利用者単位で共有できる。 事実や常設規則ではなく、入力、工程、検証、停止条件を持つ手順に使う。
.claude/agents/ 独自の役割、利用可能な道具、権限、検査基準を持つサブエージェントを定義する。 プロジェクトまたは利用者単位で共有できる。 役割名だけを分けても、参照資料と権限が同じなら独立した検証にはならない。
.claude/hooks/ settings.json の Hooks から呼び出す検査や制御用スクリプトを整理する。 プロジェクトへコミットすればチームで共有できる。 配置しただけでは実行されないため、settings.json 側のイベント定義と一致させる。
.mcp.json プロジェクトで共有する MCP サーバーの接続設定を置く。 リポジトリ単位で共有する。 認証情報そのものを埋め込まず、接続先の信頼性と利用可能な道具を確認する。
.worktreeinclude 新しい worktree へ複製する、通常は Git 管理されないファイルを指定する。 リポジトリ単位で共有する。 秘密情報や端末固有の状態を無条件に複製しない。

この分割が必要になるのは、設定ファイルの種類を整理して見せるためではない。各ファイルは、読み込まれる時点、適用される作業、共有される利用者、強制力が異なる。CLAUDE.md は判断を導く文脈であり、settings.json は権限や道具の動作を構成する。Skills は必要になった時点で手順を読み込み、agents は別の役割と権限を持つ実行主体を定義する。これらを一つの巨大な指示ファイルへまとめると、どの設定が行動を促し、どの設定が実行を制限しているのか分からなくなる。

共有範囲の選択には、再現性と個人差の両方が関係する。すべてをプロジェクト設定へ入れれば、チーム内の挙動をそろえやすいが、個人環境にしか存在しないコマンドやパスまで共有される。すべてを利用者設定へ置けば、個人の操作は整うが、リポジトリを別の端末や自動実行環境で扱ったときに同じ規則が再現されない。チーム全員が守る条件はプロジェクトへ、複数プロジェクトで共通する個人規則は ~/.claude へ、現在の端末だけに必要な差分はローカル設定へ置くことで、設定の責任範囲を分離できる。

2.3 rules は対象パスに応じて読み分ける

CLAUDE.md にすべての規則を集めると、規則の総量は増えるが、現在の作業に必要な情報の比率は下がる。文書を編集するときにもデータベース移行規則が入り、シェルスクリプトを変更するときにも記事の表記規則が入る。Claude Code は関係のない規則を必ず誤適用するわけではないが、常時読み込まれる情報が増えるほど、作業と直接関係する条件が大量の文脈へ埋もれる。

.claude/rules/ に置いた Markdown ファイルは、paths 条件を付けなければ各セッションで読み込まれる。paths を指定した規則は、Claude Code が条件に一致するファイルを扱うときに適用される[3]。これにより、プロジェクト全体に共通する規則と、特定のファイル群にだけ必要な規則を分けられる。

シェルスクリプト用の規則は、次のように対象パスを限定できる。

1
2
3
4
5
6
7
8
9
10
11
12
13
---
paths:
  - "scripts/**/*.sh"
---

# Shell script rules

- Use POSIX shell syntax.
- Do not use arrays.
- Do not use process substitution.
- Quote variable expansions unless intentional splitting is required.
- Preserve documented exit codes.
- Run shellcheck when it is available.

文書用の規則は別のファイルへ分離する。

1
2
3
4
5
6
7
8
9
10
11
12
---
paths:
  - "docs/**/*.md"
---

# Documentation rules

- Use Japanese for explanatory prose.
- Preserve heading numbering.
- Preserve reference numbering unless the citation order changes.
- Do not modify code examples unless technically necessary.
- Report any factual statement that cannot be verified from the supplied sources.

この構成では、scripts 以下のシェルスクリプトを読むときに POSIX shell の規則が関係し、docs 以下の Markdown を扱うときに文書規則が関係する。記事の表記規則がシェルスクリプトの修正判断へ入らず、シェルの引用規則が文書の推敲へ入らない。規則を削るのではなく、必要な場面でだけ有効にすることで、具体性と文脈量を両立させている。

rules の状態 読み込み方 適した用途 主な失敗条件
paths なし 規則が各セッションの文脈へ常時入る。 セキュリティ方針、変更報告、全言語共通の禁止事項に適する。 対象固有の規則まで置くと、無関係な作業でも文脈を占有する。
paths あり 一致するファイルを Claude Code が扱うときに規則が関係する。 言語、拡張子、ディレクトリ、機能領域ごとの規則に適する。 パターンが実際のパスと一致しなければ、必要な規則が読み込まれない。
広すぎるパターン 本来の対象外となるファイルにも規則が適用される。 複数領域に本当に共通する規則に限って使う。 例外的なファイルへ不適切な制約を持ち込みやすい。
狭すぎるパターン 一部の対象ファイルだけが一致し、同種ファイルに規則が届かない。 特定の生成物や重要ディレクトリだけを厳格に扱う場合に使う。 ディレクトリ移動や拡張子変更によって規則が外れる。

パス限定規則で起きやすい失敗は、規則の内容ではなく、規則が読み込まれているという前提の誤りである。たとえば、対象が src/scripts/backup.sh へ移動した後も paths が scripts/**/*.sh のままであれば、規則本文をどれだけ精密に書いても適用されない。ファイル名に角括弧など glob の特殊文字が含まれる場合も、パターンが意図通りに解釈されない可能性がある。

1
2
3
4
5
6
7
8
9
規則本文は正しい
  ↓
paths が実際のファイル位置と一致しない
  ↓
対象ファイルを扱っても規則が読み込まれない
  ↓
Claude Code は規則が存在しない状態で判断する
  ↓
利用者は規則違反だと考えるが、実際には適用条件の設定ミスである

設定が効かない場合は、規則本文だけを修正するのではなく、対象パターン、実際のファイル位置、起動した作業ディレクトリ、読み込まれた指示ファイルを確認する必要がある。/context では、現在のセッションへ入っている CLAUDE.md や rules を確認でき、InstructionsLoaded Hook を使えば、どの指示が、いつ、どの理由で読み込まれたかを記録できる[3]。規則の存在と、現在の作業への適用は別の状態である。

2.4 settings の適用範囲と優先関係を区別する

Claude Code の settings は、単一の設定ファイルだけで決まらない。組織が配布する管理設定、起動時のコマンドライン引数、プロジェクトのローカル設定、プロジェクトの共有設定、利用者設定が階層として適用される。優先順位は、管理設定、コマンドライン引数、.claude/settings.local.json、.claude/settings.json、~/.claude/settings.json の順である[5]。

設定階層 主な利用者 用途 下位設定との関係
管理設定 組織の管理者が配布する。 禁止コマンド、認証方式、サンドボックス、利用可能な MCP サーバーなどを組織単位で強制する。 利用者、プロジェクト、ローカル設定から緩和できない。
コマンドライン引数 現在のセッションを起動する利用者が指定する。 権限モードや追加設定を、その起動だけ変更する。 管理設定には優先できないが、通常のファイル設定より優先される。
ローカルプロジェクト設定 現在の端末で作業する個人が管理する。 個人環境の差、一時的な検証、共有したくない上書きを設定する。 共有プロジェクト設定と利用者設定より優先される。
共有プロジェクト設定 リポジトリを利用するチームが共有する。 プロジェクト共通の権限、Hooks、環境変数、道具の動作を設定する。 利用者設定より優先される。
利用者設定 個人がホームディレクトリで管理する。 すべてのプロジェクトで使う個人設定を置く。 より具体的なプロジェクト設定によって変更され得る。

優先順位を知らないまま設定を追加すると、ファイルの内容と実際の動作が一致しないように見える。たとえば、利用者設定で編集を許可していても、プロジェクト設定が同じ操作を拒否していれば、そのプロジェクトでは拒否側が有効になる。ローカル設定で一時的に別のモードを指定すれば、同じリポジトリでも端末ごとに挙動が変わる。組織の管理設定で禁止された操作は、プロジェクト設定やコマンドライン引数から解除できない。

ただし、すべての設定値が単純に上書きされるわけではない。文字列や真偽値のような単一値は、優先度の高い設定が同じ項目を置き換える。一方、権限規則やサンドボックスの許可パスなど、配列として定義される設定は、複数の階層から結合され、重複が除かれる[5]。上位ファイルを確認しただけでは、最終的な配列の全体を把握できない場合がある。

1
2
3
4
5
6
7
8
9
利用者設定に許可項目がある
  ＋
プロジェクト設定に別の許可項目がある
  ＋
管理設定に拒否項目がある
  ↓
複数階層の設定が最終構成へ統合される
  ↓
単一の settings.json だけを読んでも実際の権限を判断できない

設定階層の差は、再現性にも直接影響する。ある端末では ~/.claude/settings.json に必要な環境変数と権限があり、別の端末には存在しない場合、同じリポジトリの .claude/settings.json を取得しても同じ挙動にはならない。ローカル設定によって共有設定を補っている場合も、CI や別の開発者の環境ではその補完が存在しない。個人設定がなければ動かない処理を、プロジェクト共通の処理として扱うことはできない。

再現可能なプロジェクト設定には、チーム全体で必要な条件を .claude/settings.json へ置き、端末固有の差だけを .claude/settings.local.json へ残す構成が必要になる。利用者設定には、プロジェクトの動作条件ではなく、複数プロジェクトへ共通する個人設定を置く。組織として必ず守らせる禁止事項は管理設定で強制し、CLAUDE.md の注意書きだけへ依存させない。

設定を追加した後は、ファイルが存在することではなく、現在のセッションでどの設定元が読み込まれているかを確認する。/status では、有効になっている管理、利用者、プロジェクト、ローカル設定の情報源と、設定ファイルの構文エラーを確認できる[5]。CLAUDE.md や rules の読み込み状態は /context、メモリファイルの所在と内容は /memory で確認する[3]。

確認対象 確認方法 判別できること 判別できないこと
settings の情報源 /status を実行する。 利用者、プロジェクト、ローカル、管理設定のうち、どの階層が読み込まれているかを確認できる。 各項目が最終的にどのファイルから採用されたかを、すべて一覧できるわけではない。
CLAUDE.md と rules /context を実行する。 現在の文脈へ入っている指示ファイルと、その文脈量を確認できる。 規則が実際の応答で必ず遵守されることまでは保証しない。
メモリファイル /memory を実行する。 CLAUDE.md、CLAUDE.local.md、自動メモリの保存場所と内容を確認できる。 権限設定や Hooks の最終的な実行可否までは示さない。
パス限定規則 対象ファイルを読み、/context または読み込み記録を確認する。 対象ファイルを扱った時点で規則が文脈へ入ったかを確認できる。 誤った glob が意図した別のファイルまで含むかは、パターン自体の検査が必要になる。

判断条件を固定する作業は、CLAUDE.md を一枚作成した時点では終わらない。常設する事実、対象限定の規則、再利用する手順、実行を制限する設定を別の場所へ配置し、それぞれの共有範囲と読み込み条件を確認する必要がある。CLAUDE.md と rules が整っていても、以前の会話履歴や無関係な資料が現在のセッションへ残れば、個別作業の判断は別の文脈に引きずられる。次に必要になるのは、恒久条件を維持したまま、作業単位で参照範囲を切り替えることである。

3. /clear と @ 参照で作業単位の文脈を作る

3.1 /clear は終了した作業の履歴を切り離す

CLAUDE.md と .claude/rules/ に置いた内容は、別の作業へ移っても維持すべき判断条件である。一方、前の作業で検討した仮説、採用しなかった修正案、一時的に発生したエラー、途中で読み込んだ大量のログは、その作業が終われば次の判断を妨げる情報になり得る。恒久的な規則と、一つの作業でだけ有効な会話履歴は、同じ文脈として持ち続けるべきものではない。

/clear は、現在の会話を空の状態へ切り替え、新しい作業を開始するためのコマンドである。プロジェクトの CLAUDE.md やメモリは新しい会話でも利用され、終了した会話は削除されず、必要になれば /resume から再開できる[6]。このため、/clear は設定を初期化する操作ではなく、プロジェクトの前提を保ったまま、作業固有の履歴だけを切り離す操作として使える。

1
2
3
4
5
6
7
8
9
記事の推敲を完了する
  ↓
確定した表記規則と判断結果をファイルへ保存する
  ↓
/clear
  ↓
CLAUDE.md と rules を維持した新しい会話を開始する
  ↓
別のスクリプトの不具合調査へ移る

会話履歴を残したまま異なる作業へ移ると、前の作業でだけ成立していた条件が、次の作業でも有効であるかのように扱われる可能性がある。たとえば、文書の最小修正を依頼した後にスクリプトの再設計へ移った場合、「既存構造をできるだけ変えない」という直前の方針が、再設計の選択肢を不必要に狭めることがある。反対に、大規模な整理を進めた会話の後では、小さな修正でも周辺ファイルまで変更する方向へ判断が引きずられやすい。

1
2
3
4
5
6
7
終了した作業の目的と制約が会話履歴に残る
  ↓
Claude Code は新しい依頼と過去の履歴を同じ文脈で解釈する
  ↓
前の作業でだけ必要だった判断基準が次の作業にも影響する
  ↓
新しい作業の変更範囲、優先順位、出力形式が意図せず変わる

/clear を実行すべき基準は、話題の名称が変わったかどうかではない。前の会話履歴が、次の判断に必要かどうかで決める。同じ不具合の原因調査から修正へ移る場合は、調査結果と失敗した試行が実装判断に必要になるため、履歴を維持する意味がある。記事作成を終えた後に経理資料の確認へ移る場合は、前の構成案や文体上の議論を保持する理由がない。

作業の状態 適した操作 保持される情報 使用を誤った場合の影響
同じ作業を継続する 現在の会話をそのまま続ける。 調査結果、修正案、失敗した試行、直前の判断を保持する。 会話が長くなると、古い出力や不要なログが文脈を占有する。
同じ作業の要点だけを残す /compact を使い、必要な内容を指定して要約する。 同じ会話を継続しながら、過去の内容を圧縮して保持する。 要約から落ちた細部は、後続の判断で参照できなくなる。
独立した作業へ移る /clear を使う。 プロジェクトの設定とメモリを残し、会話履歴を空にする。 未保存の判断や、次の作業にも必要な調査結果を失う。
過去の作業へ戻る /resume を使う。 選択した過去の会話履歴を再開する。 別の会話を再開すると、現在想定している前提と履歴が一致しないことがある。

/clear の前には、会話中に確定した知識と、一時的な試行錯誤を分ける必要がある。採用した設計、確認済みの原因、変更したファイル、残っている課題を、文書、課題管理、コミット、作業メモなどへ保存する。会話履歴を消しても困らない状態を先に作れば、確定した知識はプロジェクト側へ残り、採用しなかった案と一時的な出力だけを切り離せる。

会話中の情報 /clear 前の扱い 理由
採用した設計判断 設計文書、CLAUDE.md、rules、課題管理など、適切な保存先へ反映する。 次のセッションでも参照すべき確定情報だからである。
変更済みの実装 差分、テスト結果、必要に応じてコミットとして残す。 会話を失っても、変更内容と検証状態を追跡できるようにする。
未解決の課題 発生条件、確認済みの範囲、次に調べる対象を作業メモへ残す。 後から作業を再開した際に、同じ調査を繰り返さずに済む。
採用しなかった案 後で比較に必要なものだけ理由とともに残し、それ以外は会話とともに切り離す。 不採用案を恒久的な前提へ混ぜると、後続作業の判断を曖昧にする。
一時的なログとエラー出力 原因の根拠になる部分だけ保存する。 大量の生出力を維持しても、現在の作業で必要な情報の比率が下がる。

/clear は、ファイル変更や端末で実行した処理を元へ戻す機能ではない。空になるのは会話の文脈であり、編集済みのファイル、作成したブランチ、実行済みのコマンド、外部サービスへ反映した変更は残る。会話を切り替える操作と、変更を巻き戻す操作を混同すると、履歴を消した時点で復旧方法まで失う。コードと会話を以前の状態へ戻す必要がある場合はチェックポイントと /rewind、外部変更には対象サービス側の復旧手段が必要になる。

3.2 @ 参照は判断材料を明示的に追加する

@ に続けてファイルを指定すると、そのファイルの内容を会話へ明示的に追加できる。ディレクトリを指定した場合は、配下の全ファイル内容が一度に入るのではなく、ディレクトリの一覧とファイル情報が提示される。複数のファイルを同じ依頼で参照することもでき、参照されたファイルのディレクトリと上位ディレクトリにある CLAUDE.md も文脈へ追加される[7]。

この挙動によって、見本、規則、変更対象、仕様書を区別して提示できる。単に「関連ファイルを確認する」と依頼する場合、Claude Code は検索結果から参照資料を選ぶ。@ 参照で根拠を明示すれば、少なくとも最初に確認すべき資料を利用者側で固定できる。どの資料を基準に判断したのかが明確になるため、成果物の検品時にも同じ根拠へ戻りやすい。

1
2
3
4
5
@docs/style-guide.md を規則として参照する。
@draft.md だけを変更対象とする。

style-guide.md に違反している箇所を特定し、
必要な部分だけ draft.md で修正する。

この例では、二つのファイルを同時に参照しているが、役割は同じではない。style-guide.md は判断条件であり、draft.md は編集対象である。参照資料と変更対象を文章で明示しなければ、Claude Code は整合性を取るために規則側のファイルを修正する可能性もある。@ はファイルを文脈へ追加する記法であり、そのファイルを読み取り専用にしたり、ほかのファイルの編集を禁止したりする権限制御ではない。

1
2
3
4
5
@tests/test_backup.py を試験構造の見本として参照する。
新しい試験は tests/test_restore.py に作成する。

test_backup.py は変更しない。
追加した復元処理の正常系と異常系を検証する。

この例では、既存の試験ファイルを見本として使いながら、新しいファイルを変更対象として指定している。見本の役割は、試験の命名、初期化、後処理、表明方法を示すことである。既存試験の内容を正式な仕様とみなすとは限らない。過去の試験に未検出の誤りや古い前提があれば、それをそのまま模倣する可能性があるため、機能仕様と試験の見本は分けて提示する必要がある。

参照種別 本文で明示する役割 参照によって得られるもの 役割を混同した場合の失敗
規則 成果物が満たすべき条件として指定する。 禁止事項、形式、技術的制約、検品基準を与える。 見本に含まれる偶然の特徴まで必須条件として扱いやすい。
見本 構成、粒度、命名、実装形式の参考として指定する。 抽象的な品質要求を、既存の具体例として示せる。 古い設計、例外的な実装、過去の誤りまで模倣しやすい。
変更対象 実際に編集してよいファイルとして指定する。 作業の中心となる対象を明確にできる。 @ 参照しただけでは編集範囲が制限されず、周辺ファイルまで変更され得る。
判断根拠 仕様、試験結果、契約条件、設計決定などの根拠として指定する。 判断が依拠する資料と、後から検証する資料を一致させられる。 類似実装や慣例を、正式に確定した要件として扱いやすい。
調査の起点 依存関係を探索し始める場所として指定する。 広いリポジトリの中で、最初に読む範囲を限定できる。 起点だけで調査を終えると、呼び出し元や設定との関係を見落とす。

@ 参照が有効なのは、資料を追加するだけでなく、その役割を依頼文の中で固定した場合である。「@old-report.md と同じように作る」という指示では、同じにすべき対象が見出し構成なのか、文体なのか、文字数なのか、表の形式なのか分からない。Claude Code は複数の特徴から模倣対象を選ぶため、利用者が意図していなかった特徴まで再現する可能性がある。

項番 曖昧な指定 具体化した指定 限定される判断
1 @previous.md と同じように作成する。 @previous.md の h2 構成と各章の論述密度を見本とし、内容と結論は現在の資料から組み立てる。 構成と密度だけを模倣し、過去記事の主張や事実を流用しない。
2 @test.py を参考に試験を作る。 @test.py の初期化と後処理の形式を使い、期待値は @spec.md の要件から決める。 試験形式と、機能上の正解を決める根拠を分離する。
3 @config.yml を確認して修正する。 @config.yml を変更対象とし、@schema.json を検証根拠として、未定義項目だけを修正する。 編集対象、根拠、修正範囲を別々に固定する。

ファイルとディレクトリの参照には、情報量の違いもある。単一ファイルの @ 参照では内容そのものが会話へ入り、ディレクトリ参照では構造を把握するための一覧が入る[7]。ディレクトリを指定しただけで、配下のすべての実装を確認したことにはならない。構造を見た後に、判断へ必要なファイルを個別に読み込ませる必要がある。

1
2
3
4
5
6
7
8
9
@src/auth/ でディレクトリ構造を確認する
  ↓
認証処理の入口、設定、試験を特定する
  ↓
必要なファイルだけを個別に参照する
  ↓
呼び出し関係と変更対象を整理する
  ↓
実装前に不足する依存関係だけを追加で探索する

この順序には、最初からリポジトリ全体を読み込ませる方法とは異なる利点がある。最初の判断根拠を限定し、依存関係が確認された時点で参照範囲を広げるため、なぜ追加のファイルが必要になったのかを追跡できる。広く探索すること自体を避けるのではなく、探索範囲が広がる理由を明示する。

3.3 限定参照と依存関係探索を二段階に分ける

参照範囲を狭くすれば、常に正確な変更になるわけではない。対象ファイルだけを読めば、そのファイル内部の整合性は確認できる。しかし、設定ファイルから値を受け取る処理、別のスクリプトから呼び出される処理、外部へ公開している関数、試験で前提とされている出力形式は、対象ファイルの外側に存在する。局所的に正しい修正が、呼び出し元との契約を壊す場合がある。

たとえば、backup.sh の終了コードを整理する修正では、backup.sh だけを読めば、内部の分岐と return または exit の使い方を確認できる。しかし、このスクリプトを cron が直接実行し、監視処理が終了コード 1 と 2 を区別しているなら、終了コードの変更は外部仕様の変更になる。対象ファイルだけでは、どの値が呼び出し元に依存されているか判断できない。

1
2
3
4
5
6
7
8
9
@scripts/backup.sh だけを読み、内部処理を修正する
  ↓
スクリプト単体では処理が簡潔になる
  ↓
呼び出し元が依存する終了コードや出力形式を変更する
  ↓
cron や監視処理が正常と異常を正しく判別できなくなる
  ↓
局所的な改善が運用全体の障害を生む

参照設計は、最初に読む範囲と、変更前に確認する範囲を分けると安定する。最初の段階では、規則、変更対象、症状を示す資料へ限定して原因候補を絞る。次の段階では、候補となる変更が影響する呼び出し元、設定、試験、公開仕様を探索する。探索の結果、変更対象を広げる必要がある場合は、最初の依頼範囲と区別して提示する。

段階 参照する対象 確認する内容 この段階で確定しないこと
初期参照 規則、症状、変更候補となるファイル、直接の試験を読む。 現象、局所的な原因候補、既存実装の意図を確認する。 変更範囲と最終的な実装方法はまだ確定しない。
依存関係探索 呼び出し元、設定、公開インターフェース、関連試験を読む。 変更が外部へ与える影響と、維持すべき契約を確認する。 影響が確認されていない周辺ファイルを変更対象へ加えない。
変更計画 確定した対象と根拠をまとめる。 変更するファイル、変更理由、検証方法、復旧方法を整理する。 承認前にはファイルを編集しない。
実行と検証 承認された変更対象と関連試験を扱う。 局所的な修正と、依存先を含む動作の両方を確認する。 検証されていない範囲まで成功したとは報告しない。

この二段階の参照は、@ で指定したファイル以外を読ませないという意味ではない。最初の判断材料を利用者が固定し、Claude Code が追加の資料を必要と判断した場合に、追加理由を明示させる構成である。参照範囲の拡大を禁止するのではなく、根拠のない拡大を避ける。

参照資料を明示しても、Claude Code が変更できる範囲は自動的には狭まらない。@draft.md を指定した状態でも、関連する設定や試験を編集する道具と権限があれば、Claude Code は必要と判断した周辺ファイルを変更できる。読み込ませる範囲、編集を依頼する範囲、機械的に許可する範囲は別々に設計する必要がある。

境界 指定方法 制御するもの 制御しないもの
参照境界 @ 参照、ファイル名の明示、探索指示を使う。 最初に文脈へ入れる資料と、判断根拠を指定する。 ほかのファイルを読む権限や編集する権限は制限しない。
依頼範囲 変更対象と対象外を依頼文へ記述する。 Claude Code が目指す作業範囲を示す。 記述だけでは、誤った操作を機械的に遮断しない。
実行権限 Permissions、Plan mode、Hooks などを設定する。 読み取り、編集、コマンド実行など、利用可能な操作を制限する。 参照資料が正しいことや、計画の妥当性は保証しない。
復旧境界 チェックポイント、Git、バックアップを使う。 誤った変更から戻せる対象と単位を定める。 外部サービスへ確定した操作まで自動的には戻さない。

/clear と @ 参照が整えるのは、Claude Code が判断に使う文脈である。/clear は終了した作業の履歴を切り離し、@ 参照は現在の作業で最初に使う根拠を明示する。この段階で改善されるのは、何を前提として考えるかであり、実際の編集やコマンド実行を止める強制力ではない。文脈が正しくても、誤った計画を承認したり、危険なコマンドを実行したりすれば、ファイルや外部環境は変更される。次に必要になるのは、Plan mode、権限設定、Hooks、チェックポイントによって、判断から実行へ移る境界を制御することである。

4. Plan mode、Permissions、Hooks、チェックポイントで変更を制御する

4.1 人間が先に決めるのは目的、判断基準、任せない操作である

Claude Code へ作業を渡す前に、人間側で確定させるべきものは、具体的な実装手順ではない。何を改善するのか、何を維持するのか、どの状態を完了と判定するのか、どの操作を Claude Code だけでは確定させないのかである。問いの切り方、優先順位、評価基準を先に決める必要があるという既稿の議論は、Claude Code の実行制御にも直接当てはまる[8]。

たとえば、「認証処理を安全にする」という依頼だけでは、変更の方向は定まらない。現在の認証方式を維持したまま入力検証を追加するのか、セッション管理を変更するのか、外部の認証サービスへ移行するのかによって、対象ファイル、必要な資格情報、停止時間、復旧方法が変わる。Claude Code はリポジトリを調査して実装案を提示できるが、運用上どの変更を受け入れられるかまでは、コードだけから確定できない。

人間が先に決める項目 認証処理を変更する場合の例 未確定のまま委譲した場合の失敗
目的 認証失敗時の情報漏えいを防ぎ、既存利用者のログイン方法は維持する。 安全性向上を理由に、利用者側の操作や認証方式まで変更される。
維持条件 既存の API、セッション Cookie、終了コード、監視項目を維持する。 局所的な実装は改善しても、呼び出し元や監視処理との互換性が失われる。
完了条件 既存試験、新しい異常系試験、構成検査、手動確認をすべて通す。 コードを変更した時点で完了と判断され、運用上の検証が残る。
変更範囲 認証モジュールと試験を対象とし、利用者データの変換は別工程とする。 調査中に見つかった周辺課題まで同じ変更へ取り込まれる。
任せない操作 本番資格情報の変更、利用者データの移行、本番環境への反映は人間が承認する。 実装と対外的な確定操作が一つの流れとして実行される。
復旧単位 コードは Git、設定は編集前コピー、データはスナップショットから戻す。 変更後に不具合が判明しても、どの状態へ戻すか判断できない。

ファイルを編集できることと、その変更を確定してよいことは別である。Claude Code が正しい構文で設定を書き換えられても、その設定を本番環境へ反映してよいかは、停止時間、利用者への影響、監視体制、復旧担当者まで含めて決める必要がある。モデルが持つのは実行候補を作る能力であり、業務上の影響を受け入れる権限ではない。

1
2
3
4
5
6
7
8
9
目的と維持条件が未確定のまま作業を依頼する
  ↓
Claude Code がコードと一般的な慣行から変更方針を補う
  ↓
実装上は妥当でも運用条件と一致しない計画が作られる
  ↓
調査、編集、外部反映が連続して実行される
  ↓
技術的な修正が業務上の障害へ変わる

この連鎖を分断するために、調査、計画、承認、実行を別の段階として扱う。Plan mode は調査と編集を分離し、Permissions は利用可能な操作を制限し、Hooks は実行直前の入力を検査する。チェックポイント、Git、バックアップは、実行後に戻せる範囲を定める。各機能は同じ安全策を重ねているのではなく、異なる時点の失敗を受け持っている。

4.2 Plan mode は変更前に対象、依存関係、検証方法を確定する

Plan mode では、Claude Code はファイルを読み、検索し、読み取り専用のコマンドを使ってコードベースを調査するが、ソースファイルの編集へ進まない。対話中の /plan、Shift+Tab によるモード切り替え、起動時の –permission-mode plan から利用できる[9]。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/plan

認証失敗時の応答から内部情報が漏れる問題を修正する。

次を含む変更計画を作成する。

1. 観測されている現象
2. 直接原因
3. 変更対象のファイル
4. 変更しない範囲
5. 呼び出し元と外部への影響
6. 正常系と異常系の試験方法
7. 失敗した場合の復旧方法

計画が承認されるまで編集しない。

計画へ必要なのは、変更予定のファイル名だけではない。なぜそのファイルを変更するのか、どの依存関係を確認したのか、既存の外部仕様をどのように維持するのか、何をもって修正成功と判定するのかが必要になる。対象一覧だけの計画では、実行前に変更量は分かっても、その変更が妥当であるかを評価できない。

計画の確認項目 確認する内容 不足した場合に起こること
現象 再現条件、実際の出力、期待する出力を区別する。 推測した問題を修正し、利用者が観測した現象が残る。
原因 観測事実と原因候補を分け、根拠となるコードや試験を示す。 最初の仮説を確定原因として実装へ反映する。
変更対象 編集するファイル、追加するファイル、削除候補を区別する。 調査で見つかった関連ファイルが無制限に変更対象へ加わる。
維持条件 公開 API、引数、終了コード、設定形式、データ形式を確認する。 内部実装の改善によって外部との契約が壊れる。
検証方法 既存試験、新規試験、静的検査、手動確認を具体化する。 構文が通ることだけを成功条件として扱う。
復旧方法 ファイル、データ、設定、外部操作をどの手段で戻すか示す。 実行後に、戻せる変更と戻せない変更を初めて調べることになる。

Plan mode が保証するのは、正しい計画が作られることではない。調査結果と変更案を、ファイルへ反映される前に確認できる状態を作る。原因の理解が誤っていれば、読み取り専用で作られた計画も誤る。承認者がファイル名だけを見て通せば、誤った仮説は承認済みの計画として実行へ進む。

計画の承認と、個々の操作に対する権限承認も同一ではない。計画全体を承認した後でも、Claude Code が計画に記載されていないコマンドや外部接続を選ぶ可能性は残る。反対に、個々の Bash コマンドが安全に見えても、複数の操作を組み合わせた変更全体が妥当とは限らない。Plan mode は作業全体を確認し、Permissions は実際に呼び出される道具を制御する。

1
2
3
4
5
6
7
8
9
Plan mode で変更全体を確認する
  ↓
目的、対象、依存関係、検証方法を承認する
  ↓
実行段階で個々の道具とコマンドが選択される
  ↓
Permissions と Hooks が実際の操作を検査する
  ↓
計画と異なる操作、許可されていない操作を実行前に止める

小さな誤字修正まで常に Plan mode を挟むと、承認件数が増え、確認行為が形式化する。対象が一つのファイルに限られ、変更内容が明確で、既存の試験で確認でき、巻き戻しも容易な作業では、通常の権限確認で足りる。複数ファイル、認証、データ形式、公開設定、外部サービスのように、誤りが局所的な編集で終わらない作業で Plan mode の効果が大きくなる。

4.3 Permissions は実行可能な道具とコマンドを限定する

Permission mode は、Claude Code が道具を呼び出す際の基本的な承認方式を決める。Permission rules は、その基本方式の上に、特定の道具やコマンドを allow、ask、deny として追加する。モードが作業全体の既定動作を決め、規則が個別操作の例外と制限を定める[10]。

Permission mode 承認なしで実行される主な操作 適した用途 注意点
default 作業ディレクトリ内の読み取りと、組み込みの読み取り専用コマンドを実行する。 初めて扱うリポジトリ、影響を都度確認したい作業に適する。 編集や変更可能な Bash コマンドでは承認が必要になり、長い作業では確認回数が増える。
acceptEdits ファイル編集と、作業ディレクトリ内の一部のファイル操作を自動承認する。 差分を継続的に確認しながら実装を反復する作業に適する。 編集のたびに止まらないため、対象範囲の指定と差分確認が必要になる。
plan 読み取りと読み取り専用の調査を実行する。 コードベース調査、変更計画、影響範囲の確認に適する。 計画の妥当性を自動的には保証せず、実行段階では別のモードへ移る。
auto 依頼との整合性を検査する安全判定を通じて、道具の呼び出しを自動承認する。 長時間の作業で承認待ちを減らす用途に適する。 自動判定へ依存するため、明示的な deny 規則と隔離を併用する必要がある。
dontAsk 事前に許可された道具だけを実行し、それ以外を自動的に拒否する。 非対話処理、CI、読み取り専用の検査など、必要な操作を事前に列挙できる作業に適する。 必要な操作の許可漏れは、利用者へ質問せず処理失敗として現れる。
bypassPermissions 通常の権限確認を大幅に省略して操作を実行する。 破損してもホストへ影響しない隔離済みのコンテナや仮想計算機に限って使う。 プロンプトインジェクションや意図しない操作への保護を失うため、通常環境では使用できない。

Permission rules は、deny、ask、allow の順で評価される。より具体的な allow 規則があっても、広い deny 規則に一致すれば拒否される。たとえば、Bash(git push *) を deny に置いた状態では、Bash(git push origin review) を allow に置いても push は許可されない。deny の中へ例外的な許可を作る構造ではなく、拒否する範囲を適切な粒度へ分ける必要がある。

次の設定例では、状態確認と差分確認は自動許可し、通常の push は毎回確認し、破壊的な操作と機密ファイルの読み取りを拒否する。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git show *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git reset --hard)",
      "Bash(git reset --hard *)",
      "Bash(git clean *)",
      "Bash(git push *--force*)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

Bash 規則では、空白とワイルドカードの位置が一致範囲を変える。Bash(ls *) は ls に引数が続くコマンドへ一致するが、lsof には一致しない。Bash(ls*) と書けば lsof まで一致し得る。広い allow 規則は、想定していない引数やサブコマンドまで自動承認する経路になるため、実際に必要なコマンド接頭辞まで狭める。

道具名だけを deny に置く場合と、括弧内に条件を書く場合にも違いがある。deny の Bash は Bash 道具そのものを Claude Code の利用候補から外す。deny の Bash(rm *) は Bash を残したまま、該当するコマンドだけを拒否する。読み取り専用のレビューでは Edit と Write を道具単位で外し、実装作業では危険なコマンドだけを限定的に拒否するという使い分けができる。

権限規則 効果 適した場面 残る経路
deny の Bash Bash 道具全体を利用できなくする。 文章検査、ファイル読解、コードレビューなど、端末操作を必要としない作業に適する。 ほかの道具に許可された読み取りや編集は別途制御する必要がある。
deny の Bash(rm *) rm で始まる Bash コマンドを拒否する。 一般的な開発コマンドを許可しつつ、直接削除を防ぐ場合に適する。 find の削除機能、Python、呼び出したスクリプト内部の削除など、別の表現は一致しない。
deny の Read(./.env) 組み込みの Read 道具による対象ファイルの読み取りを拒否する。 秘密情報を会話文脈へ入れないために使う。 Bash や外部プログラムからの読み取りは、サンドボックスと対応する拒否設定も必要になる。
ask の Bash(git push *) push のたびに人間の確認を求める。 ローカルなコミット作業とリモート反映を分離する場合に適する。 承認者が送信先、ブランチ、差分を確認しなければ誤送信を防げない。

権限規則は Claude Code が機械的に適用し、プロンプトや CLAUDE.md の指示より強い制限として働く。ただし、規則は記述した道具と入力にしか作用しない。削除を rm だけで表現できるとは限らず、同じ結果へ到達する別の道具やスクリプトが残っていれば、拒否規則を迂回する経路になる。個別コマンドの拒否と、実行環境そのものの隔離を組み合わせる理由はここにある。

4.4 Hooks は決定的な規則を実行直前に検査する

CLAUDE.md は望ましい判断を伝え、Permission rules は道具と入力の一致条件を制御する。Hooks は Claude Code の処理途中にある特定の事象で外部処理を実行し、実際の入力、結果、セッション状態を検査する。毎回必ず実行する検証や、作業状態を含めて判定する条件は、モデルの判断だけへ任せず Hooks に置ける[11]。

次の設定では、すべての Bash 呼び出しの直前に検査スクリプトを実行する。PreToolUse はツールが実行される前に発火するため、拒否されたコマンドはホスト側へ到達しない。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ""$CLAUDE_PROJECT_DIR"/.claude/hooks/block-destructive.sh"
          }
        ]
      }
    ]
  }
}

検査スクリプトは、標準入力として受け取った JSON から実行予定のコマンドを抽出する。終了コード 2 と標準エラー出力を返すと、PreToolUse はツール呼び出しを拒否し、拒否理由を Claude Code へ返す[12]。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#!/bin/sh

set -eu

input=$(cat)
command=$(printf '%s\n' "$input" | jq -r '.tool_input.command // ""')

case "$command" in
  rm\ *|git\ reset\ --hard|git\ reset\ --hard\ *|git\ clean\ *|git\ push\ *--force*)
    printf '%s\n' "Blocked destructive command: $command" >&2
    exit 2
    ;;
esac

exit 0

このスクリプトが防ぐのは、列挙した形式で始まるコマンドだけである。cd /tmp && rm file、sh -c に包まれた削除、find -delete、Python からの削除、実行した別スクリプト内部の削除は一致しない可能性がある。文字列検査は狭い防波堤としては使えるが、シェル構文全体を正確に解析するものではない。

禁止操作の列挙だけで守ろうとすると、同じ効果を持つ別の表現を追加し続ける必要がある。読み取り専用の処理では Bash 自体を許可しない、実装処理では書き込み先をサンドボックス内へ限定する、本番操作では MCP や資格情報を接続しないというように、可能な経路を先に減らす方が強い。Hooks は残った経路の中で、プロジェクト固有の条件を検査する。

Hook の事象 実行時点 適した処理 制御上の限界
PreToolUse 道具の入力が作られた後、実行される前に動く。 危険なコマンドの拒否、書き込み先の検査、入力の修正、追加承認の要求に使う。 検査ロジックが認識しない操作は通過する。
PostToolUse 道具が正常終了した後に動く。 整形、静的検査、ログ記録、変更後の試験に使う。 操作はすでに完了しているため、Hook 自体で実行前の状態へ戻せない。
PermissionRequest 対話環境で権限確認が表示されるときに動く。 既知の安全な操作の自動承認、危険な操作の拒否、承認内容の記録に使う。 非対話実行の -p では発火しないため、自動処理では PreToolUse が必要になる。
ConfigChange セッション中に設定変更が読み込まれるときに動く。 権限や Hooks の緩和を監査し、許可されない変更を拒否する。 Hook 自体の設定が保護されていなければ、別経路から変更される余地が残る。

複数の Hooks が同じ事象へ一致した場合は、すべてが実行され、PreToolUse の判断では最も制限の強い結果が採用される。ある Hook が拒否しても、同時に起動した別の Hook のログ出力などは実行される。副作用を持つ Hooks を組み合わせる場合は、別の Hook が拒否することを前提に処理を省略できない。

PreToolUse は Permission mode の判定より前に動き、deny を返せば bypassPermissions を含むモードでも操作を止められる。一方、Hook が allow を返しても、settings の deny 規則を上書きできない。Hooks は制限を強められるが、上位の権限規則を緩める経路としては使えない。この非対称性によって、プロジェクト固有の強制規則を Permission mode の変更から分離できる。

1
2
3
4
5
6
7
8
9
CLAUDE.md が望ましい操作を示す
  ↓
Permission mode と rules が利用可能な道具を限定する
  ↓
PreToolUse Hook が実際の入力と現在の状態を検査する
  ↓
サンドボックスが Bash の到達可能範囲を OS 側で制限する
  ↓
人間が例外と対外的な確定操作を承認する

4.5 サンドボックスは Bash と子プロセスの到達範囲を OS 側で狭める

Permissions と Hooks は Claude Code による道具の呼び出しを制御する。サンドボックスは Bash コマンドと、そのコマンドから起動された子プロセスがアクセスできるファイルとネットワークを OS 側で制限する。モデルが危険な操作を選んだ場合だけでなく、依存パッケージ、ビルドスクリプト、外部から取得したコードが意図しない処理を行った場合にも境界が働く[13]。

サンドボックスは、Claude Code のすべての道具を隔離する機能ではない。Bash とその子プロセスへ適用され、組み込みの Read、Edit、Write は Permission rules によって制御される。Bash から cat .env を実行する経路と、Read 道具で .env を読む経路は異なるため、機密情報を守るには両方の境界を確認する必要がある。

既定のサンドボックスでは、作業ディレクトリとその配下への書き込みが許可される。一方、読み取りは拒否設定を置かない限り広い範囲へ届き、ホームディレクトリにある資格情報も自動的にはすべて遮断されない。秘密情報を扱う環境では、許可する場所を決めるだけでなく、SSH、クラウド資格情報、秘密鍵、環境変数などの読み取り経路を明示的に閉じる必要がある。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": [
        "~/.ssh",
        "~/.aws",
        "~/.config/gcloud",
        "~/.kube"
      ]
    },
    "network": {
      "allowedDomains": [
        "github.com",
        "api.github.com"
      ]
    }
  }
}

failIfUnavailable を指定しない場合、必要な依存関係がないなどの理由でサンドボックスを開始できなくても、警告後に隔離なしでコマンドが実行される場合がある。安全境界として必須にするなら、開始できない時点で処理を失敗させる必要がある。allowUnsandboxedCommands を false にすると、サンドボックス内で失敗したコマンドを、隔離を外して再試行する経路も閉じられる。

境界 制御対象 代表的な設定 単独では防げないもの
Permission rules Claude Code が呼び出す道具と入力を制御する。 Bash、Read、Edit、WebFetch、MCP の allow、ask、deny を設定する。 許可された Bash の内部で子プロセスが行うすべての処理は制限しきれない。
Hooks 特定の事象で実際の入力と状態を検査する。 PreToolUse でコマンド、パス、接続先、環境を検査する。 検査条件に含まれない別表現や、Hook の外で発生する副作用は止められない。
ファイルシステムのサンドボックス Bash と子プロセスが読み書きできる場所を OS 側で制限する。 allowWrite、denyWrite、denyRead、allowRead を設定する。 組み込みの Read、Edit、Write は Permission rules で別途制御する。
ネットワークのサンドボックス Bash と子プロセスが接続できるドメインを制限する。 allowedDomains と deniedDomains を設定する。 許可したドメイン上で何が送受信されるかまでは、既定では内容検査しない。
仮想計算機またはコンテナ 作業環境全体をホスト、利用者データ、資格情報から分離する。 一時的なファイルシステム、限定資格情報、限定ネットワークを与える。 接続した外部サービスへ許可済みの操作を行うこと自体は防がない。

ネットワークの許可も、ドメイン名だけで安全性を保証するものではない。広いドメインを許可すれば、そのドメインを経由したデータ送信経路が残る。既定のプロキシは接続先のホスト名を基準に判断し、暗号化通信の内容までは検査しない。機密性の高い環境では、接続先を必要最小限に限定し、必要に応じて組織側の検査可能なプロキシを使う。

bypassPermissions は、サンドボックスの別名ではない。権限確認を省略するモードであり、隔離されていないホストで使えば、誤った判断やプロンプトインジェクションが直接ファイルと資格情報へ届く。使える状態を作るには、破損しても廃棄できる計算環境、限定された認証情報、必要最小限のネットワーク、外部操作の監査を先に整える必要がある。

4.6 チェックポイント、Git、バックアップは異なる障害を復旧する

Claude Code のチェックポイントは、ファイル編集用の道具による変更前の状態を自動的に記録する。/rewind では、選択した時点までコードと会話の両方を戻す、会話だけを戻す、コードだけを戻すという選択ができる。チェックポイントは会話とともに保存されるため、同じ会話を再開した後にも利用できる[14]。

追跡されるのは、Claude Code の直接的なファイル編集用の道具が行った変更である。Bash から実行した rm、mv、cp、sed -i、生成スクリプト、データベース更新は追跡されない。手作業による編集、別の Claude Code セッション、外部サービスへの書き込みも、通常は同じチェックポイントから戻せない。

1
2
3
4
5
6
7
8
9
10
11
Edit で設定ファイルを変更する
  ↓
チェックポイントからファイル内容を戻せる

Bash で mv、rm、sed -i を実行する
  ↓
チェックポイントでは変更を戻せない

MCP で外部サービスを更新する
  ↓
接続先サービス側の履歴または取消処理が必要になる
復旧方法 主な対象 適した復旧単位 戻せない代表例
チェックポイント Claude Code の編集用の道具が変更したローカルファイルと会話を扱う。 現在の作業で行った編集を、直前または途中の状態へ戻す。 Bash による変更、別セッション、外部サービス、長期的な変更履歴は戻せない。
Git 追跡対象ファイルのコミット、ブランチ、差分を管理する。 検証済みの状態を長期保存し、複数人の変更を統合する。 未追跡ファイル、データベース、送信済み情報、漏えいした資格情報は戻せない。
ファイルまたはデータのバックアップ 設定、生成物、データベース、作業ディレクトリを保存する。 障害前の一式を、定めた時点へ復元する。 バックアップ後に他者へ送信または複製された情報は回収できない。
トランザクション データベースなど、複数の更新を一つの確定単位として扱う。 途中失敗時に一連の変更を確定せず、更新前の状態へ戻す。 トランザクション外の通知、ファイル生成、外部 API 呼び出しは別途補償が必要になる。
外部サービスの取消または補償処理 公開、送信、課題登録、予定変更、顧客記録更新などを訂正する。 すでに確定した対外操作を、逆操作または訂正記録によって補う。 既読、通知済み、複製済みの情報を完全に存在しなかった状態には戻せない。

復旧方法は、作業後に選ぶものではない。編集前に、どの操作がチェックポイントへ入り、どのファイルを Git で追跡し、どのデータをバックアップし、どの外部操作に取消機能があるかを確認する。戻せない操作が含まれる場合は、その直前へ人間の承認点を置く。

たとえば、データ移行では、移行スクリプトの編集は Git とチェックポイントで管理できる。試験用データベースの更新は、スナップショットまたはトランザクションで戻せる。本番データの更新は、バックアップ、移行前後の検証、担当者の承認、失敗時の復元手順が必要になる。利用者へ送信した通知は、データを戻しても取り消せないため、移行成功が確認された後の別工程とする。

1
2
3
4
5
6
7
8
9
変更するコードを Git とチェックポイントで保護する
  ↓
試験環境で移行と復旧を実行する
  ↓
本番データのバックアップと検証条件を確認する
  ↓
人間が本番更新を承認する
  ↓
更新成功を確認してから外部通知を実行する

Claude Code の安全機能は、利用者による計画確認、コマンド確認、差分確認、最小権限、信頼できない内容への警戒と組み合わせて成立する[15]。Plan mode、Permissions、Hooks、サンドボックス、チェックポイントのいずれか一つを有効にしても、誤った変更、過大な権限、外部への影響、復旧不能な操作を同時には解決できない。

この章で構成した制御は、Claude Code を慎重に使うための注意事項ではなく、反復可能な手順を作るための前提である。毎回、人間が危険な操作を思い出して止め、試験方法をその場で指示し、復旧方法を考え直す状態では、作業を自動化しても安全性は再現されない。入力条件、許可する道具、実行前の検査、検証方法、停止条件、復旧方法まで一定になった作業だけが、次の段階で Skills として固定できる。

5. Skills で繰り返し作業を再利用可能な手順にする

5.1 手順を CLAUDE.md から切り離す

CLAUDE.md に置くべきものは、プロジェクトの事実、常設する技術的制約、すべての作業で守る規則である。これに対して、差分の取得、問題箇所の分類、検証コマンドの実行、結果の報告という複数工程は、特定の目的で呼び出す作業手順である。両者を同じファイルへ書くと、差分確認を行わない作業でも検品手順が読み込まれ、プロジェクトの基本情報と用途限定の工程が区別できなくなる。

Skills は、手順を SKILL.md として保存し、必要になった時点で読み込む仕組みである。利用者は /skill-name で明示的に呼び出せる。自動呼び出しを許可した Skill については、description と現在の依頼が対応すると Claude Code が判断した場合にも選択される。従来の .claude/commands/ に置いたカスタムコマンドも引き続き動作するが、カスタムコマンドの仕組みは Skills へ統合されている。Skills では、手順本体に加えて、見本、検査表、参照資料、補助スクリプト、呼び出し条件を一つのディレクトリで管理できる[16]。

1
2
3
4
5
6
7
8
9
.claude/
└── skills/
    └── review-changes/
        ├── SKILL.md
        ├── checklist.md
        ├── examples/
        │   └── review-example.md
        └── scripts/
            └── validate.sh

SKILL.md は、Skill の入口となる必須ファイルである。checklist.md は詳細な検査項目、review-example.md は出力形式の見本、validate.sh は機械的な検証を担当する。すべての情報を SKILL.md へ書くのではなく、主手順から必要な補助ファイルを参照する構成にすれば、Skill が呼び出された時点でも、不要な詳細を一度に文脈へ入れずに済む。

ファイル 役割 読み込み方 肥大化した場合の影響
SKILL.md 呼び出し条件、入力、主手順、停止条件、出力を定義する。 Skill が呼び出された時点で本文が会話文脈へ入る。 実行後も同じセッションの文脈に残るため、長すぎる手順は後続の会話を圧迫する。
checklist.md 詳細な検査観点や判定条件を保持する。 SKILL.md から必要な場面で読むように指示する。 常に読み込ませると、現在の検査に不要な項目まで判断へ入る。
examples/ 期待する出力形式や具体的な処理例を示す。 形式を確認するときだけ参照する。 過去の例に含まれる偶然の特徴や古い判断まで模倣しやすくなる。
scripts/ 構文検査、差分取得、形式検証など、決定的に実行できる処理を置く。 Claude Code が必要な道具を使って実行する。 スクリプト内部の副作用や必要権限を確認しないと、Skill の記述より広い変更が起こる。

Skill の名前は、原則としてディレクトリ名から決まり、description は何を行い、どの依頼で使うかを Claude Code が判断する材料になる。description に「変更を確認する」とだけ書けば、コードレビュー、変更要約、コミット準備、試験結果の確認のどれを対象とするか分からない。「未コミット差分をプロジェクト規則と照合し、危険な変更と検証不足を報告する」のように、対象と目的を同時に示す必要がある。

次の Skill は、未コミット差分の検品を利用者が明示的に開始し、ファイルを変更せずに結果を報告する構成である。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
---
name: review-changes
description: Review uncommitted changes against project rules and report defects without editing files.
disable-model-invocation: true
argument-hint: "[optional target path]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - "Bash(git diff *)"
  - "Bash(git status *)"
---

# Input

Review the current uncommitted changes.

If $ARGUMENTS specifies a path, limit the primary review target to that path.
If the path does not exist, stop and report the missing input.

# Procedure

1. Read the current git status and diff.
2. Identify behavior changes separately from formatting-only changes.
3. Read CLAUDE.md and the rules applicable to the changed files.
4. Read checklist.md and apply the relevant checks.
5. Run scripts/validate.sh if its prerequisites are available.
6. Report defects, unverified assumptions, skipped checks, and residual risks.

# Restrictions

- Do not edit, stage, commit, reset, or delete files.
- Do not report a check as passed when it was not executed.
- Stop if the diff cannot be obtained.

# Output

Report:
1. Reviewed files
2. Behavior changes
3. Defects and evidence
4. Validation results
5. Checks not performed
6. Residual risks

この Skill では、入力、処理、禁止操作、出力が別々に定義されている。「差分を確認する」という一文だけでは、どの規則を使うか、検証スクリプトを動かすか、未実行の検査をどう報告するかが実行ごとに変わる。工程と停止条件まで書くことで、同じ名前の作業が同じ判断経路を通るようになる。

disable-model-invocation を true にすると、Claude Code はその Skill を自動では呼び出さず、利用者が /review-changes のように明示した場合だけ実行する。この設定では Skill の description も通常の会話文脈へ常時掲載されない。デプロイ、コミット、外部送信、公開、削除候補の確定など、実行時期を利用者が決めるべき処理では、手順の内容だけでなく呼び出し主体も固定する必要がある[16]。

呼び出し設定 利用者からの呼び出し Claude Code からの呼び出し 適した内容
既定 /skill-name から呼び出せる。 description と依頼が対応すると判断した場合に呼び出せる。 調査手順、表記規則、参照知識、読み取り中心の検査に適する。
disable-model-invocation: true 利用者が明示した場合だけ呼び出せる。 自動で呼び出せない。 コミット、デプロイ、送信、公開など、開始判断を人間側へ残す処理に適する。
user-invocable: false スラッシュコマンドの一覧から呼び出せない。 関連する作業で呼び出せる。 旧システムの仕様や社内規約など、操作ではなく背景知識として使う内容に適する。

Skills の本文は、呼び出された一回の応答だけに作用するわけではない。呼び出された SKILL.md の内容は、その後も同じセッションの文脈へ残る。後続の依頼でも同じ検査方針を使いたい場合には有効だが、別種類の作業へ移った後にも影響し得る。Skill を呼び出した作業が完了した後に独立した作業へ移るなら、前章で扱った /clear によって会話単位を切り替える必要がある。

1
2
3
4
5
6
7
8
9
Skill を呼び出す
  ↓
SKILL.md の本文が現在の会話文脈へ入る
  ↓
同じ作業の後続ターンでも手順と規則が参照される
  ↓
無関係な作業へ移っても会話を継続すれば影響が残る
  ↓
作業境界で /clear を使い、恒久規則だけを残す

5.2 Skill は定型文ではなく実行仕様として書く

Skill を再利用可能にする条件は、毎回同じ文章を Claude Code へ渡せることではない。入力が不足している場合に止まり、同じ順序で調査し、同じ根拠で判定し、同じ形式で結果を返せることである。出力の見た目だけを固定しても、参照資料、検査範囲、試験方法が実行ごとに変われば、結果を比較できない。

構成要素 Skill に書く内容 実行時に確認できること 欠けた場合の失敗
目的 何を調査、生成、変更、検証する手順なのかを定義する。 実行結果が Skill の役割から外れていないか確認できる。 関連する別の課題まで同じ処理へ取り込みやすくなる。
入力 対象ファイル、仕様、期間、引数、必要な環境を定義する。 処理開始前に必要資料がそろっているか確認できる。 不足情報を推測し、別の対象や期間を処理する。
根拠 どの規則、仕様、試験、差分を判定基準にするか定義する。 出力の判断を元資料へさかのぼれる。 既存実装や一般的な慣行を正式要件として扱いやすい。
処理順序 調査、計画、変更、検証、報告の順序を定義する。 検証前に変更を確定していないか確認できる。 同じ名前の作業でも、実行する工程と順序が変わる。
出力 保存先、形式、必須項目、未確認事項の示し方を定義する。 後続処理が必要な情報を安定して取得できる。 結果の粒度や形式が変わり、自動処理や比較へ使えない。
停止条件 入力不足、試験失敗、権限不足、根拠不明で確定しない条件を定義する。 不完全な処理が次工程へ進むことを防げる。 推測した値や未検証の成果物が正常結果として確定される。
承認点 削除、送信、公開、外部書き込みの前に止まる条件を定義する。 下処理と不可逆な確定操作を分離できる。 候補の生成と業務上の採用が一つの自動処理になる。
失敗時の報告 実行できなかった処理、残った影響、再開条件を定義する。 成功、部分成功、失敗を区別できる。 一部の処理だけが成功した状態を完了として報告する。

入力条件は、Skill を呼び出す文章の説明だけでなく、引数として定義できる。argument-hint は補完時に期待する値を示し、$ARGUMENTS または位置引数を SKILL.md 内で利用できる。これにより、対象や期間を会話の前後から推測させず、呼び出し時の入力として固定できる[16]。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
name: inspect-path
description: Inspect a specified path and report rule violations without modifying files.
disable-model-invocation: true
argument-hint: "[path]"
arguments:
  - target
---

Inspect $target.

If $target is empty or does not exist, stop without inspecting another path.
Read the rules applicable to $target.
Report violations with file locations and evidence.
Do not modify files.

この Skill では、対象パスが欠けた場合にリポジトリ全体へ対象を広げない。入力不足を推測で補うのではなく、処理を停止する。再利用可能な手順では、入力が正常な場合の処理だけでなく、入力が成立しない場合の動作を決める必要がある。

検証処理には、モデルによる判断と、スクリプトによる機械的検査を使い分ける。差分が仕様の意図に合っているか、説明が読者に届くかという判断は、資料を読んだ上で評価する必要がある。一方、JSON の構文、参照番号の欠落、必須ファイルの存在、試験の終了コードは、補助スクリプトで決定的に確認できる。

検証対象 適した検証方法 理由
構文 言語処理系、構文検査器、検証スクリプトを実行する。 解釈によらず、同じ入力へ同じ結果を返せる。
試験結果 試験コマンドの終了状態と出力を取得する。 実行していない試験を推測で合格とは判定できない。
仕様適合性 仕様、差分、試験を照合して Claude Code が評価する。 複数資料の関係と、変更の意味を解釈する必要がある。
影響範囲 呼び出し元、設定、公開インターフェースを探索する。 対象ファイルだけでは外部依存を確定できない。
対外的な採否 人間が差分、影響、残存リスクを確認する。 技術的な正しさだけで、業務上受け入れられる変更かは決まらない。

ファイル整理 Skill では、候補抽出と削除を別の実行単位にする。重複ファイル、旧版、参照されていない成果物を探す処理は、対象の列挙、内容比較、参照確認として実行できる。しかし、参照が見つからないことは、不要であることの証明にはならない。運用手順、外部システム、手作業から参照されている可能性が残るため、削除対象の確定は別の判断として扱う。

1
2
3
4
5
6
7
8
9
# Procedure

1. Find files with identical or substantially overlapping content.
2. Identify older versions using names, metadata, and repository history.
3. Search the repository for references to each candidate.
4. Report the evidence and the possible impact of removal.
5. Do not delete, move, rename, or overwrite files.
6. Stop after producing the candidate list.
7. Wait for an explicit list of approved operations.
1
2
3
4
5
6
7
8
9
候補を探索する
  ↓
重複、旧版、参照状態の根拠を集める
  ↓
削除した場合の影響を一覧化する
  ↓
人間が候補ごとに採否を決める
  ↓
承認済みの操作だけを別の手順で実行する

この分割によって、探索と分類の負担は Claude Code へ渡しながら、不可逆な判断を人間側へ残せる。候補抽出 Skill に削除権限がなければ、誤分類が直ちにデータ喪失へ変わらない。承認済み操作を実行する別の Skill を作る場合も、disable-model-invocation、Plan mode、権限規則、バックアップを組み合わせる必要がある。

5.3 allowed-tools は利用可能な道具を制限する設定ではない

SKILL.md の allowed-tools は、列挙した道具を Skill の実行中に事前承認する設定である。allowed-tools に含まれない道具が Claude Code から消えるわけではなく、それらには通常の Permission mode と Permission rules が適用される。読み取り専用の Skill に Read、Grep、Glob だけを書いても、ほかの設定で Edit や Bash が許可されていれば、それらを呼び出す余地は残る[16]。

設定 作用 作用しないもの
allowed-tools Skill の実行中に、指定した道具を承認要求なしで使えるようにする。 指定していない道具を禁止したり、Claude Code の候補から除外したりはしない。
permissions.allow 一致する道具やコマンドを通常のセッションで自動承認する。 deny に一致する操作を許可できない。
permissions.ask 一致する操作の直前に人間の承認を求める。 承認者が内容を確認することまでは保証しない。
permissions.deny 一致する道具やコマンドを拒否する。 別の道具や別表現で同じ副作用へ到達する経路は、個別に制御する必要がある。

review-changes Skill を読み取り専用として運用するなら、Skill 側で必要な Git コマンドを事前承認するだけでなく、プロジェクト設定または検品エージェント側で Edit、Write、破壊的な Bash コマンドを拒否する。Skill の文章に「変更しない」と記述する層、allowed-tools で安全な確認処理を事前承認する層、Permission rules で変更経路を拒否する層を分ける必要がある。

1
2
3
4
5
6
7
8
9
10
11
12
{
  "permissions": {
    "deny": [
      "Edit",
      "Write",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git reset *)",
      "Bash(git clean *)"
    ]
  }
}

プロジェクトへコミットされた Skill は、手順だけでなく allowed-tools による事前承認も含み得る。信頼していないリポジトリの Skill をそのまま実行すると、見かけ上は検査手順でも、広い Bash コマンドや外部接続が事前承認される可能性がある。ワークスペースを信頼する前に、SKILL.md、補助スクリプト、allowed-tools、動的に実行されるコマンドを確認する必要がある。

Skills では、感嘆符とバッククォートを用いて、Claude Code が Skill 本文を読む前にコマンドを実行し、その出力を本文へ挿入することもできる。この機能は現在の差分や課題情報を入力へ組み込む場合に有効だが、Skill の呼び出しと同時に前処理が実行される。本文を読んだ Claude Code が実行可否を判断する工程より前に動くため、外部から取得した Skill では特に確認が必要になる[16]。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
name: summarize-changes
description: Summarize the current uncommitted changes.
allowed-tools:
  - "Bash(git diff HEAD)"
---

# Current diff

!`git diff HEAD`

# Procedure

Summarize behavior changes and report possible risks.

この例では、git diff HEAD が先に実行され、その出力を含む完成済みの Skill 本文が Claude Code へ渡される。差分取得のような読み取り処理であれば用途は明確だが、同じ仕組みへ変更、送信、外部 API 呼び出しを置けば、Skill の説明を解釈する前に副作用が発生する。組織側で動的なシェル実行を許可しない場合は、設定によって Skill 内のシェル前処理を無効化できる。

5.4 修正差分を次の Skill 改善へ戻す

Skill を作成した時点で、手順が完成するわけではない。実際に呼び出すと、入力条件の不足、不要な工程、検査漏れ、出力形式の不一致が見つかる。人間が結果を修正した場合は、修正内容だけでなく、なぜ修正が必要になったのかを分類し、適切な設定へ戻す必要がある。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Skill の実行結果を確認する
  ↓
人間が誤りまたは不足を修正する
  ↓
修正理由を分類する
  ├── 全作業で守る事実または規則
  │     └── CLAUDE.md
  ├── 特定のファイルや領域だけに適用する規則
  │     └── .claude/rules/
  ├── 入力、工程、停止条件、出力の不足
  │     └── SKILL.md
  ├── 決定的な検査の不足
  │     └── 補助スクリプトまたは Hooks
  └── 一度だけの例外
        └── 恒久設定へ追加しない
  ↓
次回の実行で同じ失敗が解消されたか確認する
修正理由 反映先 例 誤った反映先へ置いた場合の影響
全作業に共通する技術的制約 CLAUDE.md 既存のコマンドライン引数を維持する。 Skill だけへ書くと、別の修正手順では制約が適用されない。
対象ファイル固有の規則 .claude/rules/ シェルスクリプトでは Bash 固有構文を使わない。 CLAUDE.md へ置くと、無関係な言語の作業にも常時読み込まれる。
調査工程の不足 SKILL.md 差分確認の前に、変更されたファイルへ適用される rules を読む。 CLAUDE.md へ置くと、差分検品以外の作業にも同じ順序が持ち込まれる。
機械的に検出できる漏れ 補助スクリプトまたは Hooks 参考文献番号と参照先 ID の不一致を検出する。 文章指示だけに置くと、検査の実行と判定がモデルの選択へ依存する。
一時的な例外 作業記録または今回の入力 旧形式との比較のため、この一回だけ非推奨ファイルを参照する。 恒久規則へ追加すると、例外が後続の通常作業にも適用される。

一度の修正を直ちに恒久規則へ昇格させると、特定事例への過剰適合が起こる。たとえば、あるレビューで表現上の理由から一つの見出しを維持したとしても、「見出しは常に変更しない」という規則にはならない。修正理由が、プロジェクト全体に共通するのか、特定種類のファイルだけに必要なのか、その一回の事情なのかを分ける必要がある。

規則と手順の更新には、変更日、変更理由、適用範囲、確認した事例を残す。実行結果が改善しなかった場合には、新しい規則をさらに追加する前に、既存規則との競合、Skill の呼び出し条件、参照している補助ファイル、Permission rules を確認する。失敗の原因が Skill 本文ではなく、対象 rules が読み込まれていないことや、必要な道具が拒否されていることである場合もある。

Skill のファイルを更新しても、すでに呼び出されて現在の会話へ入った本文が、その場で自動的に置き換わるわけではない。修正後の手順を同じセッションで確認する場合は、Skill を再度呼び出す。別の作業として検証する場合は、/clear で以前の手順と実行結果を切り離してから、新しい Skill を呼び出す。旧版と新版の手順が同じ文脈へ残る状態では、どちらの指示が結果へ影響したか判定しにくい。

1
2
3
4
5
6
7
8
9
10
11
旧版の Skill を実行する
  ↓
結果と不足を記録する
  ↓
SKILL.md または補助ファイルを修正する
  ↓
/clear で旧版の手順と試行錯誤を切り離す
  ↓
新版の Skill を同じ入力条件で実行する
  ↓
結果の差を比較する

同じ入力条件で旧版と新版を比較すれば、変更によって改善したのか、入力や対象が変わったため結果が異なるのかを区別できる。Skill の品質は、手順を登録した数ではなく、同じ条件で再実行したときに、同じ工程を通り、失敗時には同じ場所で止まり、確認可能な根拠を返せるかで評価する。

Skills によって手順を一回の呼び出しへまとめても、実行開始には対話中の操作が残る。定期的な検査、週次集計、継続的インテグレーションでのレビューへ進むには、Skill または同等の指示を非対話モードから実行し、終了状態、構造化出力、権限、重複実行、失敗時の扱いを外部の実行基盤へ接続する必要がある。

6. 非対話実行と予定実行で作業を反復可能にする

6.1 claude -p で対話操作をスクリプトへ移す

対話中に安定して動く Skill や指示は、claude -p による非対話実行へ移せる。非対話実行では、利用者が対話欄へ入力し、途中の確認へ応答し、最終結果を画面から取り出す工程を、標準入力、コマンドライン引数、標準出力、終了状態へ置き換える。これにより、シェルスクリプト、継続的インテグレーション、外部の予定実行基盤から Claude Code を呼び出せる[17]。

ただし、対話で一度成功した依頼を、そのまま claude -p へ渡しただけでは反復可能な処理にならない。対話中には、利用者のホームディレクトリにある設定、現在の作業ディレクトリ、CLAUDE.md、Skills、Hooks、MCP、認証状態が暗黙に利用されている。非対話処理を別の利用者、cron、CI の実行環境へ移すと、これらの一部が存在しないか、別の内容になる。

対話中に暗黙化されやすい状態 非対話実行で起こる差 明示すべき条件
作業ディレクトリ 呼び出した場所によって、読み込まれる CLAUDE.md、rules、Skills、対象ファイルが変わる。 実行前に対象プロジェクトへ移動し、想定したディレクトリから起動する。
利用者設定 cron や CI が別の利用者で動くと、~/.claude の設定、許可規則、認証が存在しない。 実行利用者と、必要な設定の配置先を固定する。
認証 対話端末のログイン状態や鍵保管領域を、無人処理から利用できない場合がある。 API 鍵、apiKeyHelper、または利用するクラウド事業者の資格情報を安全な経路で供給する。
権限確認 途中で承認を求める処理は、画面を見ている利用者がいなければ停止する。 事前に許可する操作と拒否する操作を決め、非対話用の Permission mode を選ぶ。
出力の読み取り 自然言語の応答を人間が読んで判断する工程がなくなる。 出力形式、必須項目、異常時の終了状態を機械的に検証できるようにする。

claude -p は、通常の起動では対話セッションと同じように、作業ディレクトリと利用者設定から CLAUDE.md、Skills、Hooks、プラグイン、MCP、自動メモリを読み込む。前章で作成した weekly-report Skill を使う場合は、この動作によってリポジトリ内の .claude/skills/weekly-report/SKILL.md を呼び出せる。

一方、–bare を付けると、CLAUDE.md、Skills、Hooks、プラグイン、MCP、自動メモリの自動探索を行わず、コマンドラインから明示した設定だけで起動する。端末ごとの個人設定へ影響されにくいため、CI や配布スクリプトでは再現性を上げやすい。ただし、通常起動で利用していた Skill や Hooks も読み込まれなくなる。–bare は設定を簡略化する機能ではなく、暗黙の設定を利用しない実行方式である[17]。

起動方式 読み込まれる主な状態 適した処理 主な失敗条件
通常の claude -p 作業ディレクトリと利用者側の CLAUDE.md、rules、Skills、Hooks、MCP などを読み込む。 既存のプロジェクト設定と Skills を、そのまま非対話処理へ移す場合に適する。 端末や利用者ごとの設定差が、処理結果と権限へ影響する。
claude –bare -p 自動探索を行わず、引数から明示した設定だけを使用する。 CI、配布可能なスクリプト、異なる端末で同じ条件を再現する処理に適する。 必要な規則、Skill、Hooks、MCP、認証を明示し忘れると、対話時とは異なる処理になる。

通常起動と –bare のどちらを選ぶかは、速度だけで決められない。リポジトリにコミットした Skill と rules を処理の一部として使うなら、通常起動で作業ディレクトリを固定する方が構成しやすい。外部へ配布する検査処理や、利用者の ~/.claude に依存させたくない CI では、–bare を使い、必要な指示、settings、MCP、プラグインを引数から明示する方が再現性を確保しやすい。

1
2
3
4
5
6
7
8
9
対話中の処理をそのまま claude -p へ移す
  ↓
作業ディレクトリ、利用者設定、認証が暗黙に引き継がれる
  ↓
別の利用者や CI では同じ状態が存在しない
  ↓
Skill が見つからない、権限で停止する、異なる MCP に接続する
  ↓
同じプロンプトでも実行経路と結果が変わる

非対話処理では、結果を人間が画面からコピーするのではなく、後続の処理が解釈できる形式で受け取る。–output-format json は、応答本文に加えて、セッション識別子や利用量などを含む JSON を返す。応答本文そのものは result 項目に入る。出力項目を固定する必要がある場合は、–json-schema を併用して、指定した JSON Schema に適合する構造化出力を生成できる[18]。

次の例は、プロジェクト内の weekly-report Skill を非対話で呼び出し、Claude Code 自身にはファイルを変更させず、標準出力から取得した結果をラッパースクリプトが正式ファイルへ置き換える。Skill は報告本文を返すだけの手順として設計されていることを前提とする。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
#!/bin/sh

set -eu

umask 077

project_dir=/opt/project
state_dir=/var/lib/claude-weekly-report
output_dir=$project_dir/output
output_file=$output_dir/weekly.md
log_file=$state_dir/run.log
lock_dir=$state_dir/lock
lock_pid_file=$lock_dir/pid

tmp_json=
tmp_report=
tmp_error=
lock_acquired=0

cleanup()
{
    if [ -n "$tmp_json" ]; then
        rm -f "$tmp_json"
    fi

    if [ -n "$tmp_report" ]; then
        rm -f "$tmp_report"
    fi

    if [ -n "$tmp_error" ]; then
        rm -f "$tmp_error"
    fi

    if [ "$lock_acquired" -eq 1 ]; then
        rm -f "$lock_pid_file"
        rmdir "$lock_dir" 2>/dev/null || :
    fi
}

acquire_lock()
{
    if mkdir "$lock_dir" 2>/dev/null; then
        printf '%s\n' "$$" >"$lock_pid_file"
        lock_acquired=1
        return 0
    fi

    if [ ! -r "$lock_pid_file" ]; then
        return 1
    fi

    lock_pid=$(cat "$lock_pid_file" 2>/dev/null || :)

    case "$lock_pid" in
      ''|*[!0-9]*)
        return 1
        ;;
    esac

    if kill -0 "$lock_pid" 2>/dev/null; then
        return 1
    fi

    rm -f "$lock_pid_file"

    if ! rmdir "$lock_dir" 2>/dev/null; then
        return 1
    fi

    if ! mkdir "$lock_dir" 2>/dev/null; then
        return 1
    fi

    printf '%s\n' "$$" >"$lock_pid_file"
    lock_acquired=1
    return 0
}

trap cleanup 0
trap 'exit 129' 1
trap 'exit 130' 2
trap 'exit 143' 15

PATH=/usr/local/bin:/usr/bin:/bin
export PATH

mkdir -p "$state_dir" "$output_dir"

if ! acquire_lock; then
    printf '%s\n' "Another report process is running or the lock state is invalid." >>"$log_file"
    exit 75
fi

tmp_json=$(mktemp "$state_dir/result.XXXXXX")
tmp_report=$(mktemp "$output_dir/.weekly.md.XXXXXX")
tmp_error=$(mktemp "$state_dir/error.XXXXXX")

cd "$project_dir"

if ! claude -p "/weekly-report" \
    --output-format json \
    --permission-mode dontAsk \
    --allowedTools "Read,Grep,Glob,Bash(git log *),Bash(git status)" \
    --disallowedTools "Edit,Write" \
    --max-turns 12 \
    --max-budget-usd 2.00 \
    >"$tmp_json" 2>"$tmp_error"
then
    cat "$tmp_error" >>"$log_file"
    exit 1
fi

if ! jq -er '.result | select(type == "string" and length > 0)' \
    "$tmp_json" >"$tmp_report"
then
    printf '%s\n' "Claude returned no usable report." >>"$log_file"
    exit 1
fi

if [ ! -s "$tmp_report" ]; then
    printf '%s\n' "The generated report is empty." >>"$log_file"
    exit 1
fi

mv "$tmp_report" "$output_file"
tmp_report=

printf '%s\n' "Weekly report completed." >>"$log_file"

このスクリプトでは、Claude Code の Edit と Write を利用不能にし、ファイルの確定処理をラッパー側へ移している。Claude Code が不完全な結果を返した場合は、一時ファイルだけが破棄され、前回の weekly.md は残る。正式ファイルと一時ファイルを同じファイルシステム上へ作成し、検証後に mv で置き換えることで、生成途中の内容が正式版として読まれる時間を作らない。

dontAsk は、通常なら確認を求める操作を自動的に許可するモードではない。permissions.allow または –allowedTools に一致する操作と、許可された読み取り専用処理だけを実行し、それ以外を質問せず拒否する。無人処理で承認待ちを残さない代わりに、必要な道具を実行前に列挙する構成である。許可漏れがあれば処理は失敗するが、失敗ログから不足している操作を確認し、妥当なものだけを追加できる。

–allowedTools は列挙した道具を事前承認し、–disallowedTools は道具または一致する操作を拒否する。裸の道具名として Edit、Write を拒否すると、その道具自体が Claude Code の利用候補から外れる。Bash(git log *) のように入力条件を付けた規則は、Bash を残したまま、一致するコマンドだけを事前承認する[18]。

処理時間と費用にも上限が必要になる。–max-turns は Claude Code が道具を使って反復する回数を制限し、–max-budget-usd は API 利用額の推定値が指定値へ達した場合に停止する。上限へ到達して終了した処理は、成功した処理ではない。終了状態と JSON 内の結果を確認し、部分的な出力を正式成果物へ昇格させない。

6.2 セッション内の反復と永続的な予定実行を使い分ける

予定実行には、現在の会話を一定時間後に再開する処理と、独立した実行環境で新しいセッションを起動する処理がある。両者は時刻を指定できる点では似ているが、引き継ぐ文脈、利用できるファイル、権限確認、停止条件が異なる。

/loop は、現在の Claude Code セッション内でプロンプトを反復するための組み込み Skill である。配備状態、継続的インテグレーション、プルリクエストの更新などを短期間確認する用途に向く。指定した反復タスクは現在の会話に属し、セッションを新しくすると停止する。期限内であれば –resume または –continue で会話を再開した際に復元されるが、反復タスクは作成から 7 日で失効する[19]。

たとえば、「/loop 5m 配備が完了したか確認し、失敗していれば原因となった処理を報告する」と指定する。

/loop の予定時刻は、厳密な実行時刻を保証するものではない。定期的な処理には負荷分散のためのずれが加わり、Claude Code が別の応答を処理している場合は、その応答が終わるまで実行が待たされる。5 分ごとに指定したからといって、毎回同じ秒に処理が始まるわけではない。短い状態監視には適するが、締切時刻に外部操作を確定する用途には向かない。

実行方法 実行場所と状態 適する用途 主な制約
/loop 現在の CLI セッションと会話文脈を使う。 配備、試験、プルリクエストなどを数分から数日の範囲で確認する。 セッションへ依存し、反復タスクは 7 日で失効し、予定時刻にはずれがある。
Desktop の予定タスク 利用者の端末で、予定ごとに新しいセッションを開始する。 ローカルファイル、未コミット差分、端末上の道具へ直接アクセスする処理に適する。 アプリケーションと端末が稼働している必要があり、スリープ中の実行は保証されない。
cron または systemd timer 指定した端末上でラッパースクリプトを起動する。 ローカルファイルを明示的なシェル処理と組み合わせる場合に適する。 認証、作業ディレクトリ、排他制御、ログ、端末の稼働を利用者側で管理する。
クラウド側の Routines Anthropic が管理する環境で、選択したリポジトリを複製して新しいセッションを実行する。 利用者の端末が停止していても継続すべき調査、課題整理、プルリクエスト作成に適する。 ローカルの未コミット状態は利用できず、接続した道具は承認待ちなしで動作する。
GitHub Actions GitHub の runner 上で、workflow に定義した commit と権限を使って実行する。 リポジトリのイベント、手動実行、予定時刻を起点とする検査や変更に適する。 秘密情報、GITHUB_TOKEN、runner、既定ブランチ、同時実行、利用費用を管理する必要がある。

Desktop の予定タスクは、予定時刻ごとに手動セッションとは独立した新しいセッションを起動する。ローカルファイルへ直接アクセスできる一方、既定では作業ディレクトリに残っている未コミット変更も処理対象となる。前回の実行や手作業と変更を混在させたくない場合は、予定タスクごとに worktree を有効にする必要がある。

Desktop の予定タスクを端末の稼働状態に依存させる場合、入力期間を「前回から現在まで」と曖昧にせず、処理対象の日付または commit 範囲を実行時に再確認する必要がある。

クラウド側の Routines は、予定時刻、API 呼び出し、GitHub のイベントを起点として、Anthropic が管理する環境で動く。各実行は選択されたリポジトリを新たに複製するため、利用者の端末にある未コミット差分やローカル専用ファイルは含まれない。Routines は自律実行され、途中の Permission mode 選択や承認確認は存在しない。接続した MCP の道具には書き込み操作も含まれ得るため、不要な接続先を外し、リポジトリとブランチへの書き込み範囲を先に限定する必要がある。

予定実行方法を選ぶ基準は、どこで時刻を設定しやすいかではない。処理が必要とする状態がどこにあり、誰の権限で実行され、承認なしで何を変更できるかで決める。ローカルの未コミット差分を検査する処理をクラウド側の Routines へ移しても、対象となる差分が存在しない。利用者の端末が停止していても必ず動かす必要がある処理を /loop へ置けば、セッション終了とともに監視も止まる。

6.3 cron では対話端末に存在した実行環境を明示する

cron は指定した時刻にコマンドを起動する。Claude Code の処理内容を理解したり、失敗時に条件を補ったりする機能はない。指定した利用者、環境変数、作業ディレクトリ、標準入出力の条件で、同じコマンドを繰り返すだけである。

POSIX の crontab では、予定処理へ与えられる HOME、LOGNAME、PATH、SHELL の既定値は、crontab を登録した対話端末の値をそのまま引き継ぐものではない。標準出力と標準エラーを明示的に転送しなければ、実装依存の方法で利用者へメール送信される[20]。対話端末で command -v claude が成功していても、cron の PATH から同じ実行ファイルを見つけられるとは限らない。

1
2
3
4
SHELL=/bin/sh
PATH=/usr/local/bin:/usr/bin:/bin

17 7 * * 1 /opt/project/scripts/run_weekly_report.sh >>/var/log/claude-weekly-report.log 2>&1

予定時刻を毎時または毎日の 0 分に集中させる必要はない。処理内容に時刻上の制約がなければ、17 分のようにずらすことで、外部サービスや端末内のほかの予定処理と同時に開始する可能性を下げられる。ただし、時刻をずらしても、前回の処理が長引く場合や手動実行と重なる場合は残る。前節のラッパースクリプトでは、ロックディレクトリに実行中の PID を記録し、その PID が存在しない場合だけ残留ロックを回収する。

cron で明示する条件 設定内容 省略した場合の失敗
実行利用者 Claude Code の設定、認証、対象ファイルへ必要最小限のアクセスを持つ専用利用者を選ぶ。 対話時とは別の設定を読み、認証失敗または過大な権限で実行される。
PATH claude、jq、git など、必要なコマンドを含む値へ固定する。 対話端末では見つかったコマンドが予定実行では見つからない。
作業ディレクトリ ラッパースクリプト内で対象プロジェクトへ移動してから claude -p を呼ぶ。 別の CLAUDE.md と Skills を読むか、対象リポジトリを見つけられない。
認証 予定実行の利用者から利用できる API 鍵または認証補助処理を、安全な設定から供給する。 対話ログインへ依存した認証が利用できず、処理が開始前に停止する。
排他制御 前回の処理が残っている間は、新しい処理を開始しない。 同じ一時ファイル、出力、外部記録を複数の処理が同時に変更する。
標準出力と標準エラー 保存先、通知先、保持期間、閲覧権限を定める。 失敗を検知できないか、機密情報を含むログが広い権限で残る。
実行時間 systemd の TimeoutStartSec など、利用する実行基盤で上限を設ける。 停止条件を満たさない処理が残り、次の予定実行と重なる。

認証情報を crontab のコマンド行へ直接書くと、設定の閲覧、プロセス情報、バックアップなどを通じて露出する範囲が広がる。利用する実行環境に応じて、限定された権限の設定ファイル、apiKeyHelper、クラウド側の短期資格情報を使う。ログにも、プロンプト、外部 API の応答、ファイル内容、エラー詳細を通じて機密情報が残る可能性があるため、保存期間と閲覧権限を設定する。

cron がコマンドを起動できたことと、週次報告が正しく作られたことも別である。claude -p が終了状態 0 を返しても、入力期間が誤っている、必要なリポジトリ情報が欠けている、報告本文に必須項目がない可能性は残る。ラッパー側で JSON の存在を確認し、result が空でないことを検査し、必要であれば見出し、対象期間、commit 数などの業務条件も検証してから正式ファイルへ置き換える。

6.4 GitHub Actions では起動条件、runner、Claude Code の権限を分ける

GitHub Actions の workflow は、リポジトリ内の .github/workflows/ に置いた YAML ファイルによって定義される。workflow はイベントまたは予定時刻で起動し、一つ以上の job を runner 上で実行し、各 job は複数の step から構成される[21]。Claude Code GitHub Actions は、この runner 上で Claude Code を実行する一つの Action であり、予定実行、checkout、秘密情報、GitHub への書き込み権限は GitHub Actions 側で管理される。

on.schedule は予定時刻を定めるが、workflow は既定ブランチに存在する最新版を使い、予定実行も既定ブランチ上で動く。既定では UTC として解釈されるが、IANA タイムゾーンを指定することもできる[22]。

次の例は、毎週月曜日の 7 時 17 分に Asia/Tokyo で weekly-report Skill を呼び出す読み取り専用の workflow である。手動検証のために workflow_dispatch も用意している。リポジトリ内の Skill を使用するため、Claude Code Action より前に actions/checkout を実行する。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
name: Weekly Claude report

on:
  schedule:
    - cron: "17 7 * * 1"
      timezone: "Asia/Tokyo"
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: weekly-claude-report
  cancel-in-progress: false

jobs:
  report:
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run weekly report
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/weekly-report"
          claude_args: |
            --permission-mode dontAsk
            --allowedTools "Read,Grep,Glob,Bash(git log *),Bash(git status)"
            --disallowedTools "Edit,Write"
            --max-turns 12

Claude Code GitHub Actions v1 では、prompt に通常の指示だけでなく、リポジトリ内またはプラグインに含まれる Skill の呼び出しを指定できる。リポジトリ内の .claude/skills/ を使う場合は、Action の実行前にリポジトリを checkout する。Claude Code の CLI 引数は claude_args から渡し、API 鍵は GitHub Secrets から供給する[23]。

workflow の permissions と Claude Code の –allowedTools は異なる境界を制御する。permissions の contents: read は、runner へ渡される GITHUB_TOKEN がリポジトリへ書き込む権限を持たないようにする。–disallowedTools の Edit、Write は、Claude Code が runner 上の作業ツリーを編集する道具を使わないようにする。どちらか一方だけでは、もう一方の経路を制御できない。

制御箇所 制御するもの 設定例 単独では防げないもの
workflow の trigger どのイベントと予定時刻で job を起動するかを決める。 schedule、workflow_dispatch、pull_request などを設定する。 起動後に Claude Code が何を読むか、何を変更するかは制限しない。
workflow の permissions GITHUB_TOKEN が GitHub 上で行える操作を制限する。 contents: read、pull-requests: write などを必要最小限に設定する。 runner 内のローカルファイル操作や外部 API への接続は別途制御する。
Claude Code の Permission rules Claude Code が runner 上で使用できる道具とコマンドを制御する。 –allowedTools、–disallowedTools、–permission-mode を設定する。 GITHUB_TOKEN 自体の権限や GitHub Secrets の供給範囲は決めない。
Secrets と OIDC Claude API、クラウド事業者、GitHub App へ認証する資格情報を供給する。 ANTHROPIC_API_KEY または短期資格情報を job へ限定して渡す。 資格情報を受け取った処理が、許可された範囲で誤操作することは防がない。
concurrency 同じ workflow の複数実行が重なることを抑える。 同一の group を設定し、重複する実行を待機または取消対象にする。 一回の処理内部で同じ登録を二度行う問題は、冪等性で別途防ぐ。
timeout-minutes job が runner を占有し続ける時間を制限する。 処理の通常時間より長く、異常反復を止められる値を設定する。 時間内に生成された不正な結果を検出するには、出力検証が必要になる。

workflow を書き込み処理へ拡張する場合は、contents: write や pull-requests: write を追加する前に、どの成果物を誰が確認するかを決める。Claude Code に直接既定ブランチへ push させるより、専用ブランチへ変更を作り、プルリクエストとして人間の確認へ渡す方が、差分、試験、責任主体を追跡しやすい。

予定実行は既定ブランチの最新版を使うため、workflow や Skill の変更も次回実行へ直ちに影響する。Skill を変更した commit と、予定処理の結果を対応づけられるよう、実行ログには commit SHA、workflow run、Skill の版、対象期間を残す必要がある。処理結果だけを保存すると、同じ週次報告でもどの手順で生成されたか確認できない。

6.5 自動化では技術的成功と業務上の成功を分ける

対話作業では、入力ファイルが不足している、期間が誤っている、結果が不自然であると利用者が気づき、途中で条件を補うことがある。非対話処理では、その補完を行う人間がいない。コマンドが終了状態 0 を返し、JSON が構文上正しくても、対象期間が空である、必要なデータが取得されていない、結論が入力資料に対応していない可能性は残る。

処理結果は、少なくとも三段階で検証する必要がある。

検証段階 確認する内容 失敗時の処理
実行基盤 Claude Code が開始し、認証、道具、最大実行時間、費用上限の範囲で正常終了したかを確認する。 正式成果物を更新せず、終了状態と標準エラーを記録する。
構造 JSON、必須項目、文字コード、ファイル名、出力件数が契約した形式に合うか確認する。 不正な出力を隔離し、後続処理へ渡さない。
業務内容 対象期間、入力件数、参照元、異常値、完了条件が実際の業務要件を満たすか確認する。 正常結果として公開または送信せず、人間の確認対象へ回す。

週次報告であれば、Markdown が生成されたことだけでは足りない。対象となる開始日と終了日、利用した commit の範囲、前週との比較に必要なデータ件数、取得できなかった情報を確認する。対象期間に commit が存在しない場合は、空の報告を通常結果として出すのか、入力不足として停止するのかを先に決める。

1
2
3
4
5
6
7
8
9
claude -p が終了状態 0 を返す
  ↓
JSON が構文上正しいことを確認する
  ↓
必須項目と対象期間を確認する
  ↓
入力件数と出力内容の対応を確認する
  ↓
すべてを満たした場合だけ正式結果へ置き換える

自動化は、正しい手順だけでなく、誤った手順も同じ頻度で反復する。入力期間の計算が一日ずれていれば、毎週同じ範囲を欠落させる。MCP の登録先を誤っていれば、毎回同じ場所へ誤記録する。予定実行の価値は、人間の操作をなくすことだけではなく、入力、権限、検証、停止、復旧を毎回同じ条件で適用できる点にある。

運用条件 実装する内容 防ぐ失敗
冪等性 同じ実行識別子または対象期間を二度処理しても、重複登録や二重送信を起こさない。 再試行、補完実行、手動実行によって同じ結果が複数回確定することを防ぐ。
排他制御 前回実行が残っている場合は、新しい処理を待機、拒否、または取消対象にする。 同じファイル、ブランチ、外部レコードを複数処理が同時に更新することを防ぐ。
入力固定 期間、commit SHA、対象ファイル、データ件数を実行開始時に記録する。 処理中に入力が変化し、同じ報告内で異なる時点のデータが混ざることを防ぐ。
構造化出力 JSON Schema、必須項目、列数、値の型を検証する。 自然な文章であることだけを理由に、不完全な結果を後続処理へ渡すことを防ぐ。
意味検証 対象期間、件数、合計、参照元、異常値を業務条件と照合する。 形式は正しいが対象や結論が誤った結果を正式版にすることを防ぐ。
失敗通知 実行識別子、失敗段階、終了状態、再開条件を人間へ返す。 処理が停止したまま、正常に完了したと誤認することを防ぐ。
費用と反復の上限 最大ターン数、最大実行時間、API 利用額、同日中の再試行回数を制限する。 進展しない調査や繰り返しによって、runner と API の費用が増え続けることを防ぐ。
版の記録 commit SHA、Skill、設定、モデル、実行基盤の情報を結果と対応づける。 同じ入力で結果が変わった際に、どの構成差が原因か追跡できない状態を防ぐ。

失敗通知では、ログ全体を無条件に外部へ送らない。プロンプト、ファイル内容、認証エラー、MCP の応答には機密情報が含まれ得る。通知には実行識別子、失敗した段階、再実行の可否を載せ、詳細ログはアクセス制限された保存先で確認する。

予定実行で最も危険なのは、処理が完全に停止する場合だけではない。一部の入力だけを取得し、自然な報告を生成し、終了状態 0 で完了する場合である。実行基盤から見れば成功でも、業務上は欠落した結果である。入力件数、対象期間、取得失敗の一覧を出力契約へ含めることで、静かな欠落を検出できる。

6.6 予定実行の価値は業務条件を固定できる範囲で決まる

Claude Code を予定実行へ移すと、モデルが自動で動くこと自体が目立つ。しかし、実務上の価値を決めるのは、モデルを起動できる回数ではない。どのデータを読み、どの版の規則を使い、どの権限で処理し、どの条件を満たした結果だけを確定し、失敗を誰が追跡できるかである。

モデル性能だけでなく、社内データ、権限、監査、既存システム、業務手順へ接続できるかが生成 AI の価値を左右するという既稿の整理は、Claude Code の予定実行にも当てはまる[24]。予定実行へ移した時点で、Claude Code は対話支援の範囲を越え、定期的に権限を行使し、成果物を更新する業務処理の一部になる。

この段階では、プロンプトを一度書いて登録するだけでは足りない。次の実行までにリポジトリ、入力形式、Skill、モデル、外部 API が変わる可能性がある。処理が長期間続くほど、初回に正しかった前提が古くなる。予定タスクには、実行結果の監視だけでなく、入力契約、権限、接続先、費用、規則の定期的な棚卸しが必要になる。

1
2
3
4
5
6
7
8
9
10
11
対話で一度成功する
  ↓
Skill と権限を固定する
  ↓
claude -p で非対話化する
  ↓
入力、出力、終了状態を機械的に検証する
  ↓
cron、Routines、GitHub Actions から予定実行する
  ↓
実行履歴、権限、費用、規則の版を継続的に監査する

非対話実行と予定実行によって、一つの作業を人間の操作なしで反復できるようになる。しかし、複数の調査や変更を同時に走らせると、次の問題として、同じ会話文脈、同じ作業ツリー、同じ外部資源を複数の処理が共有する競合が生じる。並列化では、処理数を増やす前に、サブエージェントの役割と worktree の作業場所を分離する必要がある。

7. サブエージェントと worktree で役割と作業場所を分離する

7.1 生成と検品を同じ判断経路に閉じない

Claude Code が短時間で多くの候補を生成できても、その候補が要求を満たすかを確認し、再現し、修正し、採用する工程は残る。脆弱性対応では、候補の発見、再現、認定、修正、公開が別の工程であり、発見量だけを増やすと検証側が処理できなくなるという構造がある[25]。コード修正や文書作成でも、生成件数が増えたことと、採用可能な成果物が増えたことは一致しない。

同じ会話で成果物を作成し、その直後に「問題がないか確認する」と依頼すると、検品時にも制作時の判断経路が残る。最初に採用した原因仮説、変更しないと決めた範囲、不採用にした案が会話履歴へ含まれているため、検品は成果物を独立に読み直す作業ではなく、自分が選んだ方針を再確認する作業になりやすい。

1
2
3
4
5
6
7
8
9
原因候補を一つ選ぶ
  ↓
選んだ原因に沿って成果物を作る
  ↓
同じ会話履歴の中で成果物を検品する
  ↓
制作時の仮説と判断基準をそのまま利用する
  ↓
最初の仮説そのものの誤りを見落としやすくなる

検品担当へ渡すべきものは、制作担当の試行錯誤ではなく、要求仕様、成果物、差分、検査基準、試験結果、判断根拠となる資料である。制作担当が「なぜこの実装を選んだか」を先に説明すると、その説明が検品側の読み方を限定する。最初の検品では成果物と要求を直接比較し、実装理由は疑問点が生じた後に確認する方が、要求から外れた判断を発見しやすい。

検品担当へ渡す情報 役割 渡し方を誤った場合の影響
要求仕様 成果物が満たすべき動作、形式、互換性、禁止事項を示す。 制作担当の説明だけを基準にすると、要求から外れた実装を正当化しやすくなる。
成果物または差分 実際に生成、追加、変更された内容を示す。 要約だけを渡すと、要約者が省略した変更を検査できない。
検査基準 正しさ、安全性、互換性、表記、試験範囲などの評価軸を固定する。 自由形式の検品では、担当ごとに見る観点が変わり、結果を比較できない。
試験結果 実行したコマンド、終了状態、成功件数、失敗内容を示す。 「試験済み」という要約だけでは、未実行の試験と成功した試験を区別できない。
一次資料 仕様書、公式文書、既存契約など、判断をさかのぼる根拠を示す。 既存実装や制作担当の説明を、正式な仕様と取り違えやすくなる。
制作時の議論 検品後に、実装理由や制約を確認する補足資料として使う。 最初から渡すと、検品担当が同じ仮説と優先順位を引き継ぎやすくなる。

Claude Code の通常のサブエージェントは、親会話とは別の文脈窓から開始する。親会話の履歴、すでに呼び出した Skills、親が読み込んだファイルは自動的には渡らず、主担当が作成した委譲文、プロジェクトの CLAUDE.md と rules、明示的に事前読込した Skills などを基に作業する[26]。この性質を使えば、制作時の長い試行錯誤を渡さず、検品に必要な資料だけを読み直させられる。

ただし、文脈が別であることは、判断が完全に独立していることを意味しない。主担当が委譲文を作る段階で、自分の原因仮説や評価を要約へ混ぜれば、検品担当も同じ方向へ誘導される。同じモデル、同じ仕様、同じ試験だけを使えば、共通する見落としも残る。独立性を高めるには、役割名を変えるだけでなく、渡す情報、評価軸、利用できる道具を分ける必要がある。

分離する要素 制作担当 検品担当
目的 要求を満たす成果物を作成する。 要求からの逸脱、未検証の前提、残存リスクを発見する。
初期情報 要求、既存実装、設計上の制約、関連資料を受け取る。 要求、完成した差分、試験結果、検査基準を受け取る。
利用可能な操作 承認された範囲で編集と試験を行う。 読み取り、検索、差分確認、試験に限定する。
出力 変更内容、実行した試験、残っている制約を報告する。 問題箇所、根拠、再現方法、修正必要度を報告する。
採用権限 実装候補を提示する。 採否を確定せず、検査結果を提示する。

検品結果を最終判断として自動適用すると、制作と検品を分けても、検品担当の誤りがそのまま変更へ変換される。検品担当は問題候補と根拠を提示し、修正の採否は要求の責任を持つ主体が決める。生成、検品、採用を三つの判断単位へ分けることで、一つのエージェントの誤認が直ちに確定変更となる経路を短くできる。

7.2 カスタムサブエージェントへ役割、文脈、道具を固定する

カスタムサブエージェントは、プロジェクト側の .claude/agents/ または利用者側の ~/.claude/agents/ に置く Markdown ファイルで定義する。定義には、役割を判断する description、利用可能な道具、禁止する道具、権限モード、事前に読み込む Skills、必要に応じた worktree 隔離を指定できる[26]。

次の reviewer は、現在の差分を要求と照合し、問題を報告する検品担当である。tools は利用可能な道具の許可一覧として働くため、Write、Edit、MCP、外部検索は最初から利用候補へ入らない。permissionMode を plan にすることで、ファイル変更へ進まない読み取り中心の動作を指定している。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
---
name: reviewer
description: Review the current changes against requirements and report defects with evidence without modifying files.
tools: Read, Grep, Glob, Bash
permissionMode: plan
---

# Role

Review completed changes independently from the implementation process.

# Required inputs

- The original request or specification
- The current git diff
- Applicable CLAUDE.md and rules
- Relevant tests and their results

# Procedure

1. Read the request before reading the implementation explanation.
2. Inspect the complete diff.
3. Identify behavior changes separately from formatting changes.
4. Verify each behavior change against the stated requirements.
5. Check affected callers, configuration, and tests.
6. Reproduce defects when possible.
7. Report checks that could not be performed.

# Restrictions

- Do not edit, write, stage, commit, reset, or delete files.
- Do not infer that a test passed when it was not executed.
- Do not treat the implementation rationale as the specification.
- Do not approve or reject the change on behalf of the responsible person.

# Output

Report:
1. Reviewed scope
2. Confirmed behavior changes
3. Defects with file locations and evidence
4. Missing or insufficient tests
5. Unverified assumptions
6. Residual risks

tools を指定した場合は、列挙した道具だけが利用可能になる。disallowedTools を使う場合は、親から継承する道具のうち、指定したものだけを除外する。たとえば Write と Edit だけを禁止すると、Bash、MCP、外部取得などは残る。読み取り専用の検品担当を作る場合は、禁止項目を増やすより、必要な道具だけを tools へ列挙する方が、実行経路を確認しやすい。

定義項目 作用 設定時の注意
description Claude Code がどの依頼をサブエージェントへ委譲するかを判断する材料になる。 「レビューする」だけでは対象が広いため、入力、目的、変更禁止を含めて具体化する。
tools サブエージェントが利用できる道具を許可一覧として定める。 Bash を許可すると任意のシェル処理へ到達し得るため、親側の Permission rules とサンドボックスも必要になる。
disallowedTools 親から継承する道具の一部を除外する。 除外していない道具は残るため、読み取り専用を保証する設定としては範囲が分かりにくい場合がある。
permissionMode サブエージェント内での権限確認方式を指定する。 親セッションのモードによっては親側の設定が優先されるため、サブエージェント定義だけを安全境界にしない。
skills 指定した Skill の全文をサブエージェント開始時の文脈へ読み込む。 検品基準を固定できる一方、長い Skills を多数読み込むと独立した文脈を消費する。
isolation worktree を指定すると、サブエージェントの作業ディレクトリを別の Git worktree へ移す。 ファイルは分かれるが、外部サービス、ポート、データベース、資格情報は自動的には分離されない。

permissionMode: plan と書けば、それだけであらゆる親セッションから読み取り専用になるわけではない。親が acceptEdits、auto、bypassPermissions などのモードで動いている場合、親側の権限文脈がサブエージェントの指定より優先される場合がある[26]。検品担当の変更経路を確実に閉じるには、親またはプロジェクトの Permission rules でも Edit、Write、危険な Bash コマンドを拒否する必要がある。

サブエージェントを前景で動かす場合、主会話は結果が返るまで待機する。背景で動かす場合は、主会話が別の作業を続けている間に検品を進められる。背景処理で権限確認が必要になれば主会話へ確認が表示されるが、利用者が複数の依頼を同時に見ていると、どの担当の何の操作を承認しているかを取り違えやすい。承認画面ではサブエージェント名、対象、コマンド、作業ディレクトリを確認する。

7.3 並列実行方式は調整主体と通信経路で選ぶ

Claude Code には、主会話から呼び出すサブエージェント、利用者が管理する独立セッション、複数の担当が直接通信する agent teams、スクリプトが工程を保持する動的ワークフローがある。いずれも複数の処理を動かせるが、調整主体、文脈の共有方法、担当同士の通信、ファイルの分離方法は異なる[27]。

方式 調整主体 担当間の通信 適する作業 主な失敗条件
サブエージェント 主会話の Claude Code が依頼を作り、結果を回収する。 原則として各担当から主会話へ結果を返す。 調査、検品、分類、特定領域の実装など、入力と出力を限定できる作業に適する。 委譲文が曖昧だと、必要な前提を持たないまま独立した判断を進める。
独立セッション 利用者が各セッションへ作業を割り当て、進捗と結果を確認する。 自動的な相互通信はなく、利用者が情報を受け渡す。 互いに依存しない不具合修正、調査、実装案の比較に適する。 要求、規則、進捗が複数の会話へ分散し、統合時に状態を再構成できなくなる。
agent teams 主担当が作業を割り当て、共有タスクを通じて複数担当を調整する。 担当同士が直接メッセージを交換できる。 異なる仮説の検証、複数領域にまたがる調査、担当間の議論が必要な課題に適する。 実験的機能であり、同一ファイルを編集すると競合し、調整費用と利用量も増える。
動的ワークフロー スクリプトまたは定義済みの工程が、担当、検証、分岐、再試行を管理する。 工程で定義された入出力を通じて結果を受け渡す。 複数の検査、比較、投票、統合を同じ手順で反復する処理に適する。 工程設計が誤っていると、同じ欠陥を複数エージェントで大規模に反復する。

agent teams は、共有タスクと担当同士の直接通信を持つ実験的機能であり、既定では無効である[27]。複数の仮説を相互に批判させる調査には向くが、順番に処理すべき作業や、同じファイルへ集中的に変更を加える作業では、通信と調整が増えるだけになる。

agent teams の各担当は、作業ツリーを自動的には分離されない。同じリポジトリ内で並行編集する場合は、担当ごとに異なるファイル群を所有させる必要がある[27]。同じファイルを複数担当へ割り当てるなら、同時に統合する実装作業ではなく、相互に独立した候補を作って比較する作業として扱う。

方式の選択は、エージェント数ではなく、作業間の依存関係から決める。結果だけを返せばよい短い調査はサブエージェント、互いに独立した長い作業は独立セッション、担当間の議論が必要な探索は agent teams、再現可能な多段処理は動的ワークフローに向く。順番にしか進められない処理を並列化しても、待機と統合の工程が増える。

7.4 worktree でファイルと Git の作業状態を分離する

エージェントの文脈を分けても、同じ作業ディレクトリを共有すれば、ファイル上の状態は共有されたままである。一方が未コミット差分を作成した後に、もう一方が同じファイルを読み直せば、後者は自分の作業開始時には存在しなかった変更を入力として受け取る。試験結果も、どの担当の変更を含む状態で実行されたか分からなくなる。

1
2
3
4
5
6
7
8
9
担当 A が認証処理を編集する
  ↓
同じ作業ディレクトリで担当 B が試験を実行する
  ↓
担当 B の変更だけでなく担当 A の未完成差分も試験対象になる
  ↓
成功または失敗の原因を担当ごとに分離できなくなる
  ↓
どの変更を採用すべきか比較できなくなる

Claude Code は、–worktree または -w を指定して起動すると、既定では .claude/worktrees/ 以下へ独立した worktree とブランチを作る[28]。各セッションを異なる worktree で動かせば、一方のファイル編集は別のセッションの作業ディレクトリへ直接現れない。

1
2
3
claude --worktree feature-auth
claude --worktree fix-backup
claude --worktree review-changes
1
2
3
4
5
6
7
8
9
10
repository/
├── .git/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/
│       ├── fix-backup/
│       └── review-changes/
├── src/
├── tests/
└── .worktreeinclude

既定の fresh 設定では、新しい worktree は現在の作業ツリーではなく、通常は origin/HEAD が示すリモートの既定ブランチから作られる[28]。主作業ツリーに未コミット差分や未送信のコミットがあっても、新しい worktree には入らない。現在のローカル HEAD を起点にする必要がある場合は、worktree.baseRef を head に設定する。

1
2
3
4
5
{
  "worktree": {
    "baseRef": "head"
  }
}
起点 含まれる状態 適する作業 確認すべき点
fresh リモートの既定ブランチを基準とする、清潔な作業ツリーから開始する。 既定ブランチを基準にした独立修正、比較実装、プルリクエスト作成に適する。 ローカルだけにあるコミットや未コミット差分は含まれない。
head 起動元の現在のローカル HEAD にあるコミットを起点とする。 未送信の基盤変更を前提に、別の担当へ作業を分ける場合に適する。 未コミット差分は含まれず、起点となるコミット自体が検証済みか確認する必要がある。

Git の worktree は、一つのリポジトリへ複数の作業ツリーを関連付ける仕組みである。各 worktree は独自の作業ディレクトリ、HEAD、index を持つ一方、オブジェクトデータベース、リモート情報、多くの参照とリポジトリ設定は共有する[29]。完全なリポジトリ複製ではないため、履歴を効率よく共有しながら、作業中のファイル状態を分けられる。

共有されるものがあるため、一つの worktree が別の worktree と無関係になるわけではない。ある担当が fetch すれば共有されるリモート追跡参照が更新され、ブランチやタグへの操作もリポジトリ全体へ影響する。同じローカルブランチを複数の worktree で同時に検出する操作は通常拒否されるが、強制操作や共有参照の変更まで各 worktree 内へ閉じ込められるわけではない。

状態 worktree ごとに分離されるか 運用上の意味
作業ディレクトリ 分離される。 担当 A の未コミット編集は、担当 B のファイルへ直接現れない。
HEAD と index 分離される。 異なるブランチとステージング状態を同時に保持できる。
Git オブジェクト 共有される。 コミット、ツリー、ファイル内容を複製せず利用できる。
リモートと多くの参照 共有される。 fetch、ブランチ、タグなどの操作は、ほかの worktree からも観測され得る。
リポジトリ設定 既定では共有される。 一つの worktree で変更した Git 設定が、別の worktree にも影響する場合がある。

カスタムサブエージェントへ isolation: worktree を指定すると、その担当の Bash やファイル操作を一時的な worktree 内で実行できる[28]。変更がなければ終了時に自動削除され、変更や未送信のコミットが残る場合は、作業を失わないように保持される。

1
2
3
4
5
6
7
8
9
10
11
12
13
---
name: implementation-candidate
description: Implement one isolated candidate solution and report the branch, diff, and test results.
tools: Read, Grep, Glob, Edit, Write, Bash
permissionMode: acceptEdits
isolation: worktree
---

Implement only the assigned candidate.

Do not merge, push, or modify the main worktree.
Commit the completed candidate only after all required tests pass.
Report the worktree path, branch, commit, changed files, and test results.

独立した作業環境、実装、試験、レビュー、継続的インテグレーションまでを一つの作業単位として委任する製品の進化からも、コード生成能力だけでなく、作業環境、検証経路、統合単位を分離する必要性が見える[30]。Claude Code の worktree も、並列数を増やす機能として使うだけでは不十分である。どの要求から分岐し、どの試験を通し、どの commit を統合候補とするかを追跡できる単位として使う必要がある。

7.5 worktree はプロセス、データベース、資格情報を分離しない

worktree が分けるのは、主として Git が管理するファイルと worktree ごとの作業状態である。各担当が同じ端末で動けば、待受ポート、試験用データベース、キャッシュ、コンテナ名、一時ディレクトリ、環境変数、認証情報、MCP の接続先は共有され得る。ファイル競合がなくても、実行時の状態が衝突すれば試験結果を担当ごとに分離できない。

共有資源 起こり得る競合 分離方法
待受ポート 複数の担当が同じポートで開発サーバーを起動し、後から起動した処理が失敗する。 worktree または担当ごとにポート番号を割り当てる。
試験用データベース 別の担当が作成、更新、削除したデータによって試験結果が変わる。 データベース名、スキーマ、コンテナ、保存領域を担当ごとに分ける。
キャッシュと一時ファイル 同じキーや固定パスを使い、別の実装の生成物を読み込む。 worktree の絶対パスや実行識別子を保存先へ含める。
コンテナ名 同じ compose project 名やコンテナ名を使い、起動、停止、削除が競合する。 担当または worktree ごとにプロジェクト名を変える。
資格情報 複数の担当が同じ権限で外部環境を操作し、誰の変更か判別できなくなる。 読み取り専用または担当別の限定資格情報を使い、操作履歴を残す。
MCP と外部サービス 別の worktree から同じ課題、文書、予定、顧客記録を同時に更新する。 並列作業中は読み取りに限定するか、接続先の領域と更新対象を担当ごとに分ける。

新しい worktree は清潔な Git の checkout であるため、Git 管理外の .env、ローカル設定、依存関係、仮想環境は自動的には存在しない。.worktreeinclude を使うと、Git から除外されているファイルのうち、指定したものを Claude Code が作成する worktree へ複製できる[28]。

1
2
3
.env.test
config/local-test.json
fixtures/private-test-data/

.worktreeinclude は .gitignore と同じ形式で対象を指定し、Git 管理外かつパターンに一致するファイルだけを複製する。便利である一方、実運用の資格情報や本番接続設定を指定すると、作成するすべての worktree とサブエージェントへ秘密情報が広がる。複製するのは試験専用の限定設定にとどめ、本番資格情報は必要な処理へ実行時に供給する。

依存関係も担当ごとに初期化が必要になる。worktree を作っただけでは、言語処理系の仮想環境、パッケージ、生成済み成果物、データベース移行はそろわない。各 worktree で同じ初期化手順を実行し、初期化に失敗した環境を実装候補の比較へ含めない。

1
2
3
4
5
6
7
8
9
10
11
worktree を作成する
  ↓
必要な Git 管理外設定を限定的に複製する
  ↓
依存関係と試験環境を初期化する
  ↓
担当固有のポート、データベース、保存先を割り当てる
  ↓
初期状態の試験を実行する
  ↓
正常な環境だけで変更を開始する

変更前の試験が失敗している worktree で実装を始めると、実装後の失敗が既存状態によるものか、新しい変更によるものか判別できない。並列作業では、担当ごとの開始時点をそろえることが、成果物を比較する前提になる。

7.6 並列化は共通基準で比較可能な成果物へ収束させる

三つの担当へ同じ課題を渡しても、共通の要求、起点、試験、評価軸がなければ、三つの比較不能な成果物が残る。ある担当は変更量を抑え、別の担当は依存関係を追加し、別の担当は外部仕様まで変更する可能性がある。すべてが局所的には動作しても、何を理由に一つを採用するか決められない。

並列作業には、異なる候補を競わせる方式と、異なる担当範囲を統合する方式がある。両者は目的が異なるため、同じ運用で扱えない。

並列化の方式 担当の割り当て 統合方法 主な失敗条件
候補比較 同じ要求と同じ起点から、異なる実装案を各 worktree で作る。 共通の評価軸で一つを選び、ほかの候補は原則として統合しない。 複数案の一部を根拠なく混ぜると、各案が成立していた前提が崩れる。
担当分割 機能、層、ファイル群など、重ならない責務を各 worktree へ割り当てる。 境界となるインターフェースを確認し、決めた順序で統合する。 担当境界が曖昧だと、同じファイルと仕様を複数担当が変更する。
独立検品 セキュリティ、性能、互換性、試験など、異なる評価軸を各担当へ割り当てる。 指摘を重複排除し、根拠と重大度をそろえて一つの検品結果へまとめる。 同じ観点を言い換えただけの指摘が増え、修正優先度を決められなくなる。

候補比較では、すべての担当を同じ commit から開始し、同じ要求、同じ入力データ、同じ試験を与える。評価項目には、試験の成否だけでなく、変更範囲、既存仕様との互換性、追加依存関係、復旧方法、保守性、残存リスクを含める。試験に通った最初の案を自動採用すると、変更量や運用条件の差を比較できない。

1
2
3
4
5
6
7
8
9
10
11
共通の要求と起点 commit を固定する
  ↓
各候補へ異なる設計上の制約を与える
  ↓
独立した worktree で実装と試験を行う
  ↓
変更量、互換性、依存関係、性能、復旧性を比較する
  ↓
採用する候補を一つ決める
  ↓
採用候補だけを統合し、統合後の状態で再試験する

担当分割では、先にインターフェースを固定する。たとえば、一方が認証処理、他方が試験を担当する場合、試験担当が想定する関数名、引数、戻り値、エラー形式を共有する必要がある。実装担当が途中で契約を変更すると、両方の worktree では個別に成功しても、統合時に接続できない。

各 worktree で試験が成功しても、統合後の成功は保証されない。ブランチを順に取り込むことで、依存関係の版、設定、生成物、同じ行への変更が変わる。統合作業は、差分を機械的に結合する工程ではなく、複数の変更が同じ状態で成立するかを確認する新しい検証工程である。

統合時の確認 確認する内容 個別試験だけでは不足する理由
起点 各候補がどの commit から分岐したかを確認する。 異なる起点の差分を比較すると、課題とは無関係な変更が混ざる。
競合 同じ行だけでなく、同じ設定、依存関係、公開仕様への変更を確認する。 Git が自動統合できても、意味上の競合が残る。
統合順序 前提となる変更を先に取り込み、依存する変更を後に統合する。 順序によって生成物、移行、試験結果が変わる場合がある。
全体試験 統合済みのブランチで、単体、結合、静的検査を再実行する。 各 worktree の試験は、ほかの担当の変更を含まない状態で実行されている。
差分検品 要求外の変更、重複実装、不要になった暫定処理を確認する。 個別には必要だった補助処理が、統合後には重複する場合がある。
復旧 統合 commit、取り消し単位、データ変更との対応を確認する。 複数の変更を一括で戻すべきか、個別に戻すべきかが統合後に変わる。

統合担当と最終検品担当も分けると、統合時に行った手修正を独立して確認できる。競合解消では、どちらかの変更を選ぶだけでなく、両方の意図を満たす第三の変更を作る場合がある。この手修正は、各担当の worktree では試験されていない新しい成果物である。

サブエージェントと worktree によって分離できるのは、役割、会話文脈、ファイル、ブランチ、試験環境の一部である。外部サービスへ接続すると、各担当の操作は同じ課題管理、文書、予定表、顧客記録へ到達する。次の段階では、MCP の接続先、読み取りと書き込みの権限、承認点、取消方法を、ローカルな作業ツリーとは別の境界として設計する必要がある。

8. MCP で外部サービスへ接続すると影響範囲が変わる

8.1 MCP は外部の情報と操作能力を Claude Code へ接続する

MCP を使うと、Claude Code はローカルファイルと端末コマンドだけでなく、課題管理、文書管理、データベース、予定表、監視基盤、GitHub など、外部サービスが提供する情報と操作能力を利用できる[31]。MCP は、LLM を組み込んだアプリケーションであるホスト（host）、ホスト内で各接続を担当するクライアント（client）、情報と機能を提供するサーバー（server）の間で通信する規格であり、JSON-RPC 2.0 を基礎として能力の確認と処理の呼び出しを行う[32]。

MCP サーバーが提供するものは、一種類ではない。resources（資源）はファイル、データベース構造、業務記録など、判断材料となる情報を提供する。prompts（プロンプト）は、利用者が呼び出す定型的な入力や作業の入口を提供する。tools（道具）は、検索、登録、更新、削除、送信など、Claude Code が実行できる処理を提供する。外部接続の影響を判断する際は、サーバーが接続されているかだけでなく、どの種類の能力が公開されているかを確認する必要がある。

MCP の機能 提供するもの 利用例 主なリスク
resources（資源） 文書、レコード、データベース構造、アプリケーション固有の情報を文脈として提供する。 課題の詳細、顧客記録、会議資料、表の構造を参照する。 必要以上の情報を読み込み、機密情報や無関係な個人情報が会話文脈へ入る。
prompts（プロンプト） 定型的な入力、作業の入口、再利用可能な対話形式を提供する。 障害調査、週次報告、顧客対応案の作成を一定の形式で開始する。 サーバー側で更新された指示が、利用者の想定とは異なる手順を会話へ持ち込む。
tools（道具） 外部サービスを検索、作成、更新、削除、送信する実行処理を提供する。 課題の登録、文書の更新、予定の変更、データベースへの追記を行う。 誤った判断がローカルな候補では終わらず、共有データや他者の業務へ確定される。

資源を読む処理と道具で外部状態を変える処理では、失敗時の帰結が異なる。ローカルファイルから課題一覧を読み取って誤った要約を作った場合は、要約を破棄すればよい。課題管理の道具で担当者、期限、状態を書き換えた場合は、他の利用者がその変更を基に作業を始める可能性がある。MCP の導入によって増えるのは情報量だけではなく、Claude Code が結果を外部へ確定できる経路である。

1
2
3
4
5
6
7
8
9
10
11
12
13
ローカルファイルだけを扱う
  ↓
誤りは作業ディレクトリと現在の成果物に残る
  ↓
差分を破棄または修正できる

MCP の道具で外部サービスを更新する
  ↓
共有レコード、通知、予定、担当者の状態が変わる
  ↓
別の利用者や自動処理が変更後の状態を参照する
  ↓
誤りの訂正に履歴確認、関係者への通知、補償操作が必要になる

MCP を接続する判断では、「どのサービスが使えるか」より先に、「どの情報を読み、どの操作を実行し、結果がどこへ残るか」を確認する必要がある。サーバー名が同じでも、読み取り専用の検索用の道具だけを提供する構成と、削除や送信を含む管理用の道具を提供する構成では、Claude Code が到達できる影響範囲が異なる。

8.2 接続定義の適用範囲と信頼範囲を一致させる

Claude Code では、MCP サーバーを標準入出力または HTTP などの方式で登録し、local、project、user の適用範囲を選べる。local は現在のプロジェクトだけで利用者個人が使う設定、project はリポジトリの .mcp.json を通じてチームで共有する設定、user は利用者のすべてのプロジェクトで使う設定である[31]。

次の例は、HTTP で提供される課題管理用サーバーを project の適用範囲へ登録する。–transport と –scope はサーバー名より前に置く必要がある。

1
2
3
4
5
claude mcp add --transport http --scope project \
  issue-tracker https://example.invalid/mcp

claude mcp list
claude mcp get issue-tracker

project の適用範囲で登録すると、接続定義はプロジェクト直下の .mcp.json へ保存される。このファイルをリポジトリへコミットすれば、チームは同じサーバー名、接続方式、URL、起動コマンドを共有できる。ただし、共有された .mcp.json を取得しただけでサーバーが無条件に実行されるわけではない。Claude Code は、project の設定から読み込んだサーバーを初めて使う際に承認を求める[31]。

適用範囲 読み込まれる場所 チーム共有 適した接続 主な失敗条件
local 現在のプロジェクトに対応する利用者設定から読み込まれる。 共有されない。 個人用の試験サーバー、ローカル開発サーバー、資格情報を含む実験的な接続に適する。 利用者の端末だけで動く構成を、プロジェクト共通の前提と誤認する。
project プロジェクト直下の .mcp.json から読み込まれる。 バージョン管理を通じて共有できる。 チーム全員が同じ接続先とサーバー定義を使う業務連携に適する。 信頼していないリポジトリの起動コマンドや接続先を、内容確認なしで承認する。
user 利用者の ~/.claude.json から読み込まれる。 共有されない。 複数プロジェクトで使う個人用の検索、文書管理、開発補助に適する。 業務上無関係なプロジェクトにも強い権限を持つサーバーが接続される。

同じサーバー名が複数の適用範囲に定義されている場合、Claude Code は local、project、user の順で優先する[31]。チームが .mcp.json で issue-tracker を定義していても、利用者の local 設定に同名のサーバーがあれば、実際には local 側へ接続される。接続先の違いに気づかないと、試験環境へ登録するつもりで本番環境へ書き込む、またはその逆が起こり得る。

1
2
3
4
5
6
7
8
9
project の .mcp.json に issue-tracker を定義する
  ＋
利用者の local 設定にも同名 server が存在する
  ↓
優先度の高い local 定義が使われる
  ↓
チーム共通の接続先を使っているつもりでも実際の URL が異なる
  ↓
意図しない環境のデータを読み書きする

接続後は、claude mcp list と claude mcp get でサーバーの定義を確認し、Claude Code 内の /mcp で接続状態、公開されている道具、OAuth の認証状態を確認する。サーバー名だけでなく、transport、URL または起動コマンド、適用範囲、提供される道具数を確認する必要がある。

.mcp.json へ資格情報を直接記述すると、リポジトリ、レビュー、履歴、複製先へ秘密情報が残る。Claude Code は .mcp.json の command、args、env、url、headers で環境変数展開を利用できるため、共有する接続定義と、各環境で供給する秘密情報を分けられる[31]。

1
2
3
4
5
6
7
8
9
10
11
{
  "mcpServers": {
    "issue-tracker": {
      "type": "http",
      "url": "${ISSUE_MCP_URL:-https://mcp.example.invalid/mcp}",
      "headers": {
        "Authorization": "Bearer ${ISSUE_MCP_TOKEN}"
      }
    }
  }
}

必要な環境変数が未設定で、既定値もない場合は、Claude Code は設定を解析できず接続に失敗する。この失敗は、資格情報がない状態で匿名接続へ切り替わるより安全である。一方、環境変数を設定した利用者と設定していない利用者で接続可否が変わるため、必要な変数名、供給方法、権限、更新方法はプロジェクト側の運用資料へ残す。

HTTP サーバーが OAuth に対応している場合は、固定トークンを .mcp.json の headers へ組み込むより、/mcp から認証し、Claude Code の安全なトークン保存と更新処理を利用できる[31]。標準入出力で起動するサーバーは HTTP の認可フローを使わず、必要な資格情報をサーバーの実行環境から取得する構成になる[33]。

8.3 サーバーの認証と道具の実行許可を分ける

MCP サーバーへ認証できることは、Claude Code がそのサーバーのすべての道具を自動実行してよいことを意味しない。認証は、どの利用者またはクライアントがサーバーへ接続しているかを確認する。認可は、その主体がどの資源と操作へ到達できるかを決める。Claude Code の Permission rules は、接続後に個々の MCP の道具を自動許可、確認対象、拒否へ分ける[10]。

Claude Code では、MCP の道具の権限名は mcp__server-name__tool-name の形式になる。サーバー全体を対象にする場合は mcp__issue-tracker または mcp__issue-tracker__*、個別の道具を対象にする場合は mcp__issue-tracker__search_issues のように指定する。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "permissions": {
    "allow": [
      "mcp__issue-tracker__search_issues",
      "mcp__issue-tracker__get_issue"
    ],
    "ask": [
      "mcp__issue-tracker__create_comment",
      "mcp__issue-tracker__update_issue"
    ],
    "deny": [
      "mcp__issue-tracker__delete_issue",
      "mcp__issue-tracker__bulk_update"
    ]
  }
}

この構成では、検索と単一課題の取得は承認なしで実行できる。コメント追加と更新は実行のたびに確認し、削除と一括更新は拒否する。サーバー単位で mcp__issue-tracker__* を allow に置くと、現在存在する道具だけでなく、サーバーの更新によって後から追加された道具も自動承認の対象になり得る。外部状態を変更するサーバーでは、必要な道具名を個別に列挙する方が権限拡大を発見しやすい。

権限設定 作用 適した用途 残るリスク
サーバー全体を allow サーバーが提供するすべての道具を承認なしで利用できる。 閉じた試験環境で、公開される道具が少なく、すべての副作用を把握している場合に限って使う。 サーバー更新で追加された強い道具も、自動的に許可範囲へ入る。
読み取り用の道具を allow 検索、取得、一覧表示を承認なしで実行できる。 調査、下書き、検品など、外部状態を変更しない作業に適する。 大量取得、機密範囲の検索、個人情報の文脈流入は残る。
書き込み用の道具を ask 登録、更新、コメント、送信の直前に確認を求める。 対象と差分を人間が確認してから確定する処理に適する。 承認画面に十分な情報がなければ、内容を理解せずに許可する承認疲れが起こる。
破壊的な道具を deny 削除、一括変更、権限変更などを Claude Code から呼び出せなくする。 取消困難な操作や、通常業務で必要のない管理処理に適する。 更新用の道具の引数によって削除と同等の状態へ到達できる場合は、道具名だけの拒否では不足する。

MCP の仕様には、道具が読み取り専用か、破壊的か、同じ入力で再実行しても追加の副作用がないか、外部の不特定な対象と通信するかを示す注釈がある。しかし、これらはサーバーが提供するヒントであり、信頼できないサーバーの注釈を事実として権限判断へ使ってはならない[32]。

道具の注釈 示す意図 運用上の扱い
readOnlyHint 道具が外部状態を変更しないことを示す。 サーバーと実装を信頼できる場合の補助情報として使い、権限と監査を省略する根拠にはしない。
destructiveHint 道具が既存状態を破壊的に変更する可能性を示す。 false でも追加処理による重複や誤登録は起こり得るため、書き込み対象と取消方法を確認する。
idempotentHint 同じ引数で再実行しても追加の副作用がないことを示す。 再試行設計の参考にはできるが、実際の識別子、対象、サーバー実装を検証する。
openWorldHint 道具が不特定の外部主体や公開環境と通信し得ることを示す。 送信先、取得範囲、外部への情報流出経路を確認する。

名前が get_record であっても、内部でアクセス履歴を残す、外部 API の利用量を消費する、対象レコードを自動更新する可能性はある。道具名、description、注釈だけで読み取り専用と判断せず、サーバーの実装、運用文書、試験環境での実行結果を確認する。

8.4 HTTP 認可ではトークンの対象と権限範囲を確認する

HTTP を使う保護された MCP サーバーでは、サーバーは OAuth 2.1 の資源サーバー、MCP クライアントは OAuth クライアントとして動作し、認可サーバーがアクセストークンを発行する。MCP の認可仕様では、クライアントは保護資源メタデータから認可サーバーを発見し、要求する対象資源を resource パラメーターで明示する。サーバーは受け取ったトークンが自分自身を対象として発行されたものか検証しなければならない[33]。

この資源束縛が必要なのは、あるサービス向けのトークンを別の MCP サーバーで再利用する経路を防ぐためである。MCP サーバーがクライアントから受け取ったトークンを、そのまま下流 API へ転送する「トークンの転送」も禁止されている。MCP サーバーが別の API を呼び出す場合は、その API 用に別の認証関係とトークンを持つ必要がある[33]。

1
2
3
4
5
6
7
8
9
MCP クライアントがサーバー A 用のトークンを取得する
  ↓
トークンには対象資源としてサーバー A が結び付けられる
  ↓
サーバー A がトークンの対象を検証する
  ↓
サーバー B や下流 API へ同じトークンを転用しない
  ↓
サービスごとの権限と監査境界を維持する

認証が成功しても、付与されたスコープが必要最小限であるとは限らない。検索だけに使う接続へ、作成、更新、削除、管理者操作まで含むスコープを与えれば、Claude Code 側で道具を deny にしていても、資格情報自体は広い権限を持つ。Claude Code の Permission rules は道具の呼び出しを制御し、認可サーバーのスコープは資格情報が外部サービスで行使できる権限を制御する。両方を狭める必要がある。

制御層 制御するもの 確認事項 単独では防げないこと
OAuth のスコープ アクセストークンが外部サービスで利用できる操作範囲を制限する。 読み取り、書き込み、削除、管理権限が分離されているか確認する。 許可されたスコープの中で、Claude Code がどの道具をいつ呼ぶかは制御しない。
Claude Code の Permission rules Claude Code が特定の MCP の道具を呼び出せるか制御する。 読み取りを allow、書き込みを ask、不要な破壊操作を deny に分ける。 漏えいしたトークンを別のクライアントから利用することまでは防げない。
MCP サーバーの認可検査 トークンの有効性、対象資源、スコープを検証する。 別資源用トークンの拒否、期限切れ、権限不足を正しく処理する。 正当な権限を持つ利用者が誤ったデータを登録することは防げない。
外部サービスの権限 利用者、組織、領域、レコード単位の実際の操作範囲を決める。 本番と試験、部署、顧客、プロジェクトの境界が分かれているか確認する。 MCP サーバーが取得した情報を会話へ過剰に返すことは別途制御する必要がある。

アクセストークンは URL の問い合わせ文字列へ入れず、Authorization ヘッダーで送る。サーバーと認可サーバーの通信は HTTPS を使い、短命なアクセストークンと安全な更新方法を利用する[33]。固定トークンを長期間共有すると、漏えい時に誰の処理で使われたか判別しにくくなり、権限変更後も古い資格情報が残りやすい。

認証切れは、予定実行では特に扱いが必要になる。対話中であれば /mcp から再認証できるが、人が見ていない処理ではブラウザー認証を完了できない。認証エラーを一般的な一時障害として自動再試行すると、設定変更が必要な失敗を繰り返す。認証失敗、権限不足、接続先不明は再試行ではなく、人間の対応が必要な状態として通知する。

8.5 読み取り、下書き、書き込み、対外操作を別の工程にする

外部サービスの情報を読むこと、ローカルに下書きを作ること、共有レコードを更新すること、他者へ通知することは、それぞれ異なる確定度を持つ。これらを一つの指示へまとめると、前半の抽出が誤っていても、後半の書き込みと送信まで連続して進む。

面談記録から顧客管理を更新する処理では、文字起こしに含まれる人名、企業名、日付、決定事項を抽出する。抽出結果に誤りがあれば、顧客記録の対象、次回予定、担当者、約束した行動まで誤る可能性がある。自然な議事録が生成されたことは、外部記録へ反映してよいことの根拠にならない。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
録画または文字起こしを取得する
  ↓
発言者、日時、決定事項、次の行動を抽出する
  ↓
根拠となる発言位置を付けた議事録を作る
  ↓
顧客記録の変更案と変更前後の差分を作る
  ↓
人間が対象、内容、担当者、期限を確認する
  ↓
承認済みの差分だけを MCP tool で更新する
  ↓
更新結果を再取得して期待した状態と照合する
  ↓
共有文を作り、人間が送信先と内容を確認する
  ↓
送信を別の確定操作として実行する
処理段階 自動化する内容 確定前に確認する内容 失敗時の扱い
読み取り 指定された面談記録、顧客情報、予定、関連課題を取得する。 対象顧客、期間、取得件数、アクセス範囲が正しいか確認する。 必要資料が欠けていれば、推測で補わず下書き作成前に停止する。
抽出と分類 決定事項、行動項目、担当者、期限、未解決事項を構造化する。 根拠となる発言、曖昧な表現、推測した項目を区別する。 確信できない項目を未確定として残し、外部更新の入力に使わない。
ローカル下書き 議事録、更新案、課題案、共有文案をファイルへ保存する。 対象者、事実、表現、機密範囲、保存先を確認する。 下書きを破棄または修正し、外部サービスの状態は変えない。
限定書き込み 承認済みの項目だけを指定されたレコードへ追記または更新する。 変更対象、変更前後、操作識別子、取消方法を表示する。 更新結果を再取得し、差異があれば後続処理を停止する。
対外操作 内部状態更新後に、共有、送信、予定変更を実行する。 送信先、公開範囲、日時、添付、最終本文を人間が確認する。 取消不能な場合は訂正文と関係者への連絡を補償手順として実行する。

承認画面には、「update_issue を実行する」のような道具名だけではなく、接続先、対象レコード、変更前後、変更理由、根拠、取消方法を表示する必要がある。同じ道具でも、一つの内部メモを追記する操作と、全利用者に公開される状態を変更する操作では影響が異なる。

確認件数が増えて承認疲れが起きる場合、すべてを自動承認へ変える前に、処理単位を見直す。十件の軽微な内部メモを一件ずつ確認する代わりに、変更一覧と異常項目をまとめて表示できる。金額、担当者、期限、公開範囲が変わる項目だけを個別確認へ回すこともできる。承認を減らす設計は、確認情報を削ることではなく、リスクに応じて確認単位を変えることである。

8.6 外部書き込みでは実行結果、監査記録、取消方法を一組にする

MCP の道具が成功を返したことは、意図した業務状態が作られたことの証明ではない。道具は要求を正常に受け付けても、別のレコードを更新する、値を正規化する、非同期処理を開始する、外部サービス側の規則で一部項目を無視する場合がある。書き込み後には、対象を再取得して期待した状態と比較する必要がある。

1
2
3
4
5
6
7
8
9
10
11
12
13
書き込み前の状態を取得する
  ↓
対象 ID と変更差分を固定する
  ↓
一意の操作識別子を付けて tool を実行する
  ↓
tool の応答と外部サービスの更新結果を保存する
  ↓
対象を再取得して期待値と比較する
  ↓
一致した場合だけ後続工程へ進む
  ↓
不一致なら取消または補償処理を行う
記録する項目 内容 必要になる理由
実行識別子 一回の業務処理と、各 MCP の道具の呼び出しを対応づける識別子を残す。 再試行、二重実行、複数サービス間の処理を追跡するために必要になる。
接続先 サーバー名、環境、組織、プロジェクト、対象資源を記録する。 同名サーバーの適用範囲や接続先が異なる場合でも、実際の更新先を判別できる。
実行主体 利用者、予定タスク、GitHub Actions、サブエージェントなどを記録する。 誰の権限で、どの自動処理が変更したか確認するために必要になる。
変更前後 対象 ID、更新前の値、送信した値、更新後に再取得した値を残す。 誤更新の特定、差分の説明、取消値の作成に使える。
根拠 変更の根拠となった面談記録、仕様、承認、入力期間を記録する。 自然言語の推測ではなく、どの情報から変更したか確認できる。
実行結果 成功、部分成功、失敗、未確認を区別し、サーバーの応答を保存する。 一部のサービスだけ更新された状態を完全成功と誤認しないために必要になる。
取消方法 逆操作、版履歴、以前の値の再設定、訂正記録、関係者通知を定義する。 外部サービスの変更は Claude Code のチェックポイントから戻せないためである。

Claude Code のチェックポイントと /rewind は、Claude Code の編集用の道具が変更したローカルファイルを対象とし、MCP を通じて確定した外部サービスの変更は戻さない[14]。外部書き込みには、サービス側の版履歴、取消 API、逆操作、訂正レコードなど、接続先ごとの復旧手段が必要になる。

削除、送信、公開のような操作は、逆操作を行っても元の状態へ完全には戻らない。削除前に他者が情報を参照していれば、その事実は戻せない。誤ったメールを削除できても、受信者が読んだ内容は回収できない。公開を取り消しても、通知、検索索引、複製、画面記録が残る可能性がある。これらの操作では、復旧ではなく影響を抑える補償手順まで用意する。

外部操作 技術的な取消 残る影響 補償手順
レコード更新 以前の値へ戻すか、版履歴から復元する。 誤った値を参照して行われた後続作業は残る。 影響を受けた担当者と処理を特定し、再確認を依頼する。
課題の削除 復元機能またはバックアップから再作成する。 元の識別子、履歴、外部リンクが戻らない場合がある。 新旧識別子の対応を通知し、参照先を修正する。
メール送信 送信済みメール自体は原則として取り消せない。 受信者が内容を読み、転送、保存する可能性がある。 訂正文、撤回依頼、情報漏えい対応を行う。
予定変更 元の日時と参加者へ戻す。 既に通知された変更や参加者の予定調整は残る。 変更理由と正しい日時を参加者へ連絡する。
公開 非公開化または削除を行う。 索引、キャッシュ、複製、閲覧記録は残り得る。 訂正告知、キャッシュ削除依頼、影響範囲の調査を行う。

8.7 多段処理は一つの大きなトランザクションにならない

複数の MCP サーバーを使って、顧客記録を更新し、課題を登録し、予定表を変更し、メールを送る処理を考える。個々の道具が成功しても、四つのサービスをまたぐ一つのトランザクションとして原子的に確定されるわけではない。三つ目の予定変更で失敗した時点で、顧客記録と課題だけが更新済みという中間状態が残る。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
顧客記録を更新する
  ↓ 成功
課題を登録する
  ↓ 成功
予定表を変更する
  ↓ 失敗
メールを送る
  ↓ 未実行

結果
  ├── 顧客記録は更新済み
  ├── 課題は作成済み
  ├── 予定は旧状態
  └── 関係者への通知は未送信

この状態を一括して「失敗」とだけ記録すると、どこまで戻すべきか分からない。各工程に、開始前条件、成功後の状態、再実行可能性、取消処理、次へ進む条件を持たせる必要がある。後続工程が失敗した場合に前工程を戻すのか、前工程を残して後から続きを実行するのかも、業務ごとに決める。

工程設計 定義する内容 定義がない場合の失敗
事前条件 対象が存在する、版が一致する、必要な承認があるなど、実行前の状態を定義する。 古い情報や別の対象へ変更を適用する。
成功条件 道具の正常応答だけでなく、再取得した外部状態が期待値と一致することを定義する。 要求が受け付けられただけの状態を確定成功と扱う。
冪等性 同じ操作識別子で再実行した場合に、二重登録や二重送信を起こさない方法を定義する。 一時障害からの再試行によって、課題、コメント、通知が重複する。
再開点 途中成功した工程を再利用し、どの工程から続行するか記録する。 最初から全工程を再実行し、成功済みの操作を重ねる。
取消処理 更新前の値、削除対象、外部識別子を保存し、逆操作を定義する。 部分成功が残っても、元の状態を再構成できない。
補償処理 完全には戻せない操作について、訂正、通知、再調整を定義する。 技術的な値だけを戻し、既に発生した業務影響を放置する。

外部サービスが更新時の版番号、更新日時、ETag などを提供する場合は、読み取った時点と書き込む時点の状態が同じであることを確認する。読み取り後に別の利用者が変更していれば、古い状態を基に上書きせず、競合として停止する。Claude Code が正しい差分を作っていても、外部状態が変わった後に適用すれば、他者の変更を失う可能性がある。

定期実行と組み合わせる場合は、認証エラー、権限不足、対象不存在、版競合、入力不足を同じ再試行条件にしない。一時的な接続障害は再試行できるが、認証切れには再認証、権限不足には設定変更、版競合には差分の再作成が必要になる。原因を区別せず一定時間後に同じ道具を呼び直すと、解消しない処理を繰り返し、外部サービスの利用量と監査記録だけを増やす。

8.8 外部連携は読み取りから段階的に広げる

MCP の導入は、サーバーを接続した時点で完了するものではない。最初に資源と読み取り用の道具だけを使い、必要な情報を正しい対象から取得できるかを確認する。次に、取得した情報から下書きを作り、分類誤りと修正傾向を記録する。書き込みへ進むのは、対象、差分、承認、監査、取消方法を一つの実行単位として確認できるようになった後である。

導入段階 許可する処理 確認する内容 次へ進む条件
接続確認 サーバーの一覧、接続状態、公開資源、プロンプト、道具を確認する。 実際の接続先、適用範囲、認証主体、提供される能力を確認する。 意図した環境だけへ接続し、不要な道具を拒否できる。
読み取り 指定された範囲の検索、取得、一覧表示だけを許可する。 取得範囲、個人情報、件数、出力内容、アクセス履歴を確認する。 必要な情報を過不足なく取得し、機密範囲を越えない。
下書き 取得した情報から、ローカルに更新案、議事録、課題案を作る。 誤分類、推測、根拠不足、対象者の取り違えを確認する。 人間の修正傾向と停止条件を手順へ反映できる。
承認付き書き込み 特定の道具と対象だけを ask にし、承認後に更新する。 変更前後、根拠、実行主体、取消方法、更新後の状態を確認する。 誤更新を対象単位で検出し、取消または訂正できる。
限定自動書き込み 冪等で影響が小さい内部追記だけを allow にする。 二重実行、対象競合、サーバー更新、道具の追加を監視する。 例外時に停止し、人間の確認へ戻せる。
複数サービス連携 工程ごとの状態と補償処理を持つワークフローとして接続する。 部分成功、再開点、取消、サービス間の整合性を確認する。 一部失敗を識別し、重複なく再開または補償できる。
予定実行 入力と権限を固定し、人が見ていない状態で処理を開始する。 認証切れ、版競合、入力欠損、費用、監査、失敗通知を確認する。 異常時に外部状態を追加変更せず、安全に停止できる。

段階を進める判断は、一定回数成功したかだけでは決まらない。誤りが起きた場合に、どの工程で検出され、どの外部状態が変わり、どの手順で訂正できたかを確認する必要がある。正常系だけを反復しても、認証切れ、対象競合、部分成功、重複実行に耐えられるかは分からない。

MCP の仕様は、利用者による同意と制御、データへの適切なアクセス制御、道具実行前の理解と承認を重要な原則としている一方、それらをプロトコルだけで完全に強制するものではない[32]。実際の承認画面、Permission rules、資格情報、監査、復旧は、Claude Code、MCP サーバー、外部サービスを組み合わせる利用環境側で設計する必要がある。

8.9 MCP の価値は接続数ではなく、変更境界の明確さで決まる

MCP によって、外部情報の検索、下書き作成、レコード更新、通知を一つの会話から実行できる。手作業による転記が減り、複数サービスの情報を同じ文脈で扱えるため、処理時間と入力漏れを減らせる。一方で、人間が転記時に行っていた対象確認、内容確認、送信前確認も同時に失われる。

外部連携を安定させる条件は、すべての道具を利用可能にすることではない。接続定義の適用範囲を明確にし、読み取りと書き込みを分け、外部サービスと Claude Code の両方で最小権限を設定し、書き込み前後の状態を記録し、部分成功時の再開と補償を決めることである。

1
2
3
4
5
6
7
8
9
10
11
12
13
MCP サーバーを接続する
  ↓
資源、プロンプト、道具の能力を確認する
  ↓
接続先、認証主体、権限、適用範囲を固定する
  ↓
読み取り、下書き、承認付き書き込みを分離する
  ↓
実行前後の状態と監査記録を残す
  ↓
部分成功、再試行、取消、補償を工程ごとに定義する
  ↓
安全に停止できる処理だけを複数サービスと予定実行へ広げる

Claude Code がローカルな候補を作る段階では、誤りは差分として確認できる。MCP を通じて共有記録、予定、課題、通知へ書き込む段階では、誤りは他者が参照する業務状態になる。MCP の導入で変わる本質は、利用できる機能の数ではなく、Claude Code の判断が外部へ確定されるまでの距離である。接続範囲が広がるほど、権限、承認、監査、復旧を具体的な操作単位で設計する必要がある。

9. 導入順序が Claude Code の効果と危険性を決める

9.1 高度な機能は前段で定義した条件を増幅する

Claude Code の各機能は、単独で品質を高める部品ではない。CLAUDE.md と rules は判断条件を供給し、Skills はその条件に基づく工程を再実行可能にする。非対話実行は工程を人間の操作から切り離し、サブエージェントは同時に進む作業数を増やし、MCP は処理結果を外部サービスへ反映する。後段の機能へ進むほど、前段で定義した内容が広い範囲へ、短い間隔で、繰り返し適用される。

この関係では、後段の機能が前段の不備を補うとは限らない。CLAUDE.md に互換性条件がなければ、Skill は互換性を確認しない手順を安定して反復する。停止条件のない Skill を予定実行へ移せば、入力不足や試験失敗が起きても同じ処理を繰り返す。広すぎる権限を持つサブエージェントを複数起動すれば、同じ変更経路を複数の担当が同時に利用する。書き込み可能な MCP を接続すれば、ローカルで発生した判断の誤りが、共有記録、予定、課題、通知へ確定される。

1
2
3
4
5
6
7
8
9
10
11
12
13
判断条件が曖昧なまま Skill を作る
  ↓
曖昧な手順が再利用可能になる
  ↓
非対話実行で人間の途中確認がなくなる
  ↓
予定実行で同じ処理が反復される
  ↓
サブエージェントで同時実行数が増える
  ↓
MCP で外部サービスへ結果が確定される
  ↓
一つの判断ミスが継続的な業務状態の誤りへ変わる

反対に、前段の条件が具体的であれば、後段の機能は人間の注意力へ依存していた作業を再現可能な構造へ移せる。CLAUDE.md で維持条件を固定し、rules で対象別の制約を限定し、Plan mode で変更前の因果と影響範囲を確認する。Permissions、Hooks、サンドボックスで実行経路を狭め、チェックポイント、Git、バックアップで復旧単位を定める。この状態で作成した Skill には、入力、工程、検証、停止、報告を一つの実行仕様として持たせられる。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
CLAUDE.md で常設する判断条件を固定する
  ↓
rules で対象ごとの制約を限定する
  ↓
/clear と @ 参照で作業固有の文脈を作る
  ↓
Plan mode で原因、対象、影響、検証方法を確認する
  ↓
Permissions、Hooks、サンドボックスで実行経路を制限する
  ↓
チェックポイント、Git、バックアップで復旧単位を定める
  ↓
Skills へ入力、工程、停止条件、出力を固定する
  ↓
非対話実行と予定実行で同じ条件を反復する
  ↓
サブエージェントと worktree で役割と変更単位を分ける
  ↓
MCP で承認済みの処理だけを外部サービスへ接続する
機能 増幅するもの 導入前に必要な条件 条件が不足した場合の帰結
CLAUDE.md 各セッションで参照されるプロジェクトの事実と常設規則を固定する。 規則の適用範囲、検証可能な表現、重複しない管理場所を決める。 古い前提や競合する規則が、すべての作業へ継続的に影響する。
.claude/rules/ 対象ファイルに応じた技術的制約を適用する。 実際のパスと一致する条件、対象外となる範囲を確認する。 必要な規則が読み込まれないか、無関係な作業へ誤適用される。
/clear と @ 参照 現在の作業で利用する会話履歴と判断材料を限定する。 確定した知識をファイルへ残し、参照資料の役割を明示する。 必要な結論を失うか、見本、仕様、変更対象を混同する。
Plan mode 調査結果から作られた変更案を、実行前の確認対象にする。 現象、原因、維持条件、変更対象、検証、復旧を計画へ含める。 誤った原因仮説が、承認済みの変更計画として実行へ進む。
Permissions と Hooks 道具、コマンド、書き込み先、外部操作の実行可否を制御する。 許可する経路を必要最小限にし、別表現による迂回経路を確認する。 広い許可規則や検査漏れを通じて、意図しない変更へ到達する。
チェックポイント、Git、バックアップ 失敗後に戻せる対象、時点、単位を定める。 編集用の道具、Bash、データ、外部サービスごとの復旧方法を分ける。 会話やローカルファイルを戻しても、外部変更やデータ更新が残る。
Skills 入力、処理順序、検証、停止、報告を同じ手順として反復する。 対話中に同じ条件で複数回成功し、失敗時の動作も確認する。 誤った工程や一時的な例外が、正式な標準手順として固定される。
非対話実行と予定実行 手順の実行頻度を増やし、人間の途中操作を取り除く。 入力検証、冪等性、排他制御、出力検証、通知、費用上限を実装する。 静かな入力欠損や部分成功が、正常処理として繰り返される。
サブエージェントと worktree 役割、会話文脈、作業ツリー、変更候補の数を増やす。 担当範囲、共通の起点、評価軸、試験環境、統合方法を決める。 比較不能な成果物、共有資源の競合、統合後の未検証変更が残る。
MCP Claude Code の判断と処理結果を外部の共有状態へ接続する。 接続先、読み取り範囲、書き込み対象、承認、監査、取消方法を固定する。 ローカルな誤りが他者の業務へ伝播し、完全には取り消せない状態になる。

この順序は、各機能を一度も前後させてはならないという意味ではない。読み取り専用の MCP を調査へ使う、変更権限を持たないサブエージェントへ検品だけを任せるといった限定導入は、早い段階でも実施できる。導入順序が問題になるのは、反復回数、同時実行数、書き込み範囲を広げる場合である。読み取りから書き込みへ、単発から予定実行へ、一担当から並列作業へ進む前に、増幅される判断条件と失敗時の境界を確認する必要がある。

後段の機能を導入する判断は、機能が利用可能になったかではなく、前段の失敗を検出して停止できるかで決める。対話で成功しただけの手順は、まだ予定実行へ移せない。正常系の試験だけを通した外部書き込みは、まだ無人実行へ移せない。並列化した各 worktree で試験が通っても、統合後の再試験がなければ変更を確定できない。高度な機能の導入条件は、成功例の存在ではなく、失敗時の挙動が定義されていることである。

9.2 人間の仕事は実行から境界設計と例外判断へ移る

Claude Code を継続的な業務環境へ組み込むと、人間の作業量が一様に減るわけではない。コードを一行ずつ書く、ファイルを順番に読む、定型報告を毎週作るといった実行作業は減らせる。一方で、何を入力として認めるか、どの変更を自動承認するか、どの異常で停止するか、誰が外部書き込みを確定するかという設計と判断が必要になる。

手作業では、実行と判断が同じ操作の中に混ざっている。担当者がファイルを開くときに対象を確認し、値を転記するときに内容を読み直し、送信ボタンを押す前に宛先を見る。自動化はこれらの操作を取り除くため、操作の途中に埋め込まれていた確認も同時に失う。人間の関与を減らすには、消える確認を特定し、入力検証、差分表示、承認点、停止条件として別の場所へ実装しなければならない。

1
2
3
4
5
6
7
8
9
10
11
人間が手作業で実行する
  ↓
操作の途中で対象、内容、例外を確認する
  ↓
Claude Code が処理を自動化する
  ↓
手作業とともに途中確認も消える
  ↓
確認内容を入力検証、権限、承認、監査へ移す
  ↓
定型処理だけを自動化し、例外判断を人間へ返す
従来の作業 Claude Code へ移せる実行 人間側に残る判断 判断の根拠
文書を最初から作る 資料の抽出、構成案、本文案、表、形式検査を生成する。 中心命題、採用する根拠、事実と解釈の境界、公開可能性を決める。 一次資料、対象読者、公開方針、既稿との関係を確認する。
コードを一行ずつ修正する 原因候補の調査、差分作成、試験実行、変更報告を行う。 維持すべき互換性、許容する設計変更、残存リスク、採用する差分を決める。 要求仕様、呼び出し元、試験結果、運用条件を照合する。
ファイルを一件ずつ整理する 重複、旧版、参照状態、削除候補を一覧化する。 参照されていないファイルを本当に廃棄できるか判断する。 外部参照、運用手順、バックアップ、復旧可能性を確認する。
毎週同じ集計を行う 対象データを収集し、構造化し、報告書を生成する。 異常値、入力欠損、対象期間のずれ、結果の業務上の意味を判断する。 入力件数、過去値、業務基準、未取得データを確認する。
複数案を順番に試す 複数の worktree で実装案と試験結果を並行して作る。 評価軸を定義し、採用候補と統合方法を決める。 変更量、互換性、依存関係、性能、復旧性を比較する。
外部サービスへ転記する 情報を抽出し、更新案を作り、承認済み差分を書き込む。 対象、内容、公開範囲、取消不能な影響を確認して確定する。 変更前後、根拠、権限、操作履歴、補償手順を確認する。

境界設計では、少なくとも六つの境界を分ける必要がある。入力境界は、何を事実として読み込むかを決める。判断境界は、Claude Code が提案してよいことと、人間が確定することを分ける。実行境界は、利用できる道具、コマンド、書き込み先を限定する。時間境界は、単発、反復、予定実行の開始と終了を決める。復旧境界は、失敗時に戻せる対象と戻せない影響を分ける。責任境界は、誰が計画、差分、外部操作を採用したかを記録する。

境界 設計する内容 Claude Code の機能 境界がない場合の失敗
入力境界 恒久条件、作業固有資料、外部から取得する情報の範囲を決める。 CLAUDE.md、rules、/clear、@ 参照、MCP resources を使う。 古い会話、無関係な規則、過剰な外部情報が判断へ混ざる。
判断境界 Claude Code が候補を作る範囲と、人間が採用する範囲を決める。 Plan mode、Skills の停止条件、サブエージェントの役割を使う。 候補生成と業務上の確定が一つの処理として連続する。
実行境界 道具、コマンド、ファイル、ネットワーク、外部 tool の利用範囲を決める。 Permissions、Hooks、サンドボックス、MCP tool 権限を使う。 誤った判断が、必要のない変更経路へ到達する。
時間境界 開始条件、反復間隔、有効期限、最大実行時間、再試行回数を決める。 /loop、claude -p、cron、Routines、GitHub Actions を使う。 古い前提を使った処理や、進展しない反復が継続する。
作業境界 担当、会話文脈、ファイル、ブランチ、試験環境を分ける。 サブエージェント、独立セッション、worktree を使う。 未完成差分、試験結果、外部資源が担当間で混ざる。
復旧境界 編集、データ更新、外部送信をどの方法で戻すか決める。 チェックポイント、Git、バックアップ、外部サービスの取消処理を使う。 ローカルだけを戻し、外部に残った影響を見落とす。
責任境界 計画、承認、実行、検品、採用を誰が行ったか記録する。 差分、ログ、commit、workflow run、MCP の監査記録を使う。 誤りが発生しても、判断主体と修正責任を追跡できない。

人間がすべての操作を個別に承認し続ければ、安全になるとも限らない。確認件数が増えると、操作内容を読まずに許可する承認疲れが起きる。定型的で影響が限定された読み取りや検査は事前承認し、外部書き込み、削除、公開、例外処理だけを確認対象へ残す方が、承認一件あたりの意味を保ちやすい。

人間が保持すべきものは、道具を操作する仕事そのものではなく、例外を分類し、境界を変更し、成果物を採用する権限である。入力形式が変わった、Skill が想定しないファイルが現れた、試験結果が過去の傾向から外れた、MCP の接続先が変更されたといった状態は、自動処理の中で無理に解決させず、人間へ返す。例外が繰り返され、処理方法が確定した後に、規則または Skill へ反映する。

9.3 結論

Claude Code を実務で安定させる条件は、長いプロンプトを一度で正確に書くことではない。作業のたびに変わらない事実と規則を CLAUDE.md と .claude/rules/ へ固定し、現在の作業に必要な履歴と資料だけを /clear と @ 参照で構成する。Plan mode で変更前の因果と影響範囲を確認し、Permissions、Hooks、サンドボックスで実行可能な経路を限定する。チェックポイント、Git、バックアップ、外部サービスの取消処理によって、失敗後に戻せる範囲を作業開始前に決める。

この基盤が整った後に、安定した工程を Skills へ移す。対話中に同じ入力と停止条件で再実行できることを確認し、claude -p と予定実行へ広げる。並列処理では、サブエージェントの役割と worktree の作業場所を分け、共通の起点、試験、評価軸によって成果物を比較する。MCP を接続する際は、読み取り、下書き、承認付き書き込み、対外操作を分離し、外部サービスへ確定した変更を監査、取消、補償できる状態にする。

この導入順序によって得られるのは、短い指示だけで何でも自動実行する環境ではない。プロジェクト固有の判断条件を同じ場所から読み、同じ工程を通り、同じ失敗条件で止まり、変更と根拠を追跡できる環境である。短い指示が成立するのは、判断を省略したからではなく、恒久条件、実行制御、検証、復旧を対話欄の外へ移したからである。

成果物が整った形式で生成され、試験を通り、外部サービスへの書き込みに成功しても、その結果を業務上採用してよいかは別の判断である。Claude Code の出力は、生成された時点では候補であり、コードへ統合する、文書として公開する、共有記録へ反映する、他者へ送信する段階で、採用した主体の判断になる[34]。

成熟した利用では、すべての確認を消すことを目標にしない。常設できる事実は CLAUDE.md へ、対象限定の規則は rules へ、反復可能な工程は Skills へ、機械的な禁止は Permissions と Hooks へ、並列作業は worktree へ、外部操作は MCP の限定された tool と承認点へ移す。人間は、目的、例外、不可逆な操作、対外的な採用を保持する。

Claude Code が単発の対話支援から継続的な業務環境へ変わる境界は、自動実行できる機能の数では決まらない。何を読ませ、何を許可し、どこで止め、どの単位で戻し、誰が採用したかを、作業ごとの注意力ではなく環境の構成として説明できるかで決まる。高度な機能は、その構成が整った後に初めて、速度だけでなく再現性を増幅する。

参考文献

  1. id774, AI に自身の文脈を持ち運ぶ（2026-05-04）. https://blog.id774.net/entry/2026/05/04/4675/
  2. Anthropic, How Claude Code works | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/how-claude-code-works
  3. Anthropic, How Claude remembers your project | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/memory
  4. Anthropic, Explore the .claude directory | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/claude-directory
  5. Anthropic, Claude Code settings | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/settings
  6. Anthropic, Commands | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/commands
  7. Anthropic, Use Claude Code in VS Code | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/ide-integrations
  8. id774, AI に任せる前に、人間が残すべき判断（2026-06-21）. https://blog.id774.net/entry/2026/06/21/4912/
  9. Anthropic, Choose a permission mode | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/permission-modes
  10. Anthropic, Configure permissions | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/permissions
  11. Anthropic, Automate actions with hooks | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/hooks-guide
  12. Anthropic, Hooks reference | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/hooks
  13. Anthropic, Configure the sandboxed Bash tool | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/sandboxing
  14. Anthropic, Checkpointing | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/checkpointing
  15. Anthropic, Security | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/security
  16. Anthropic, Extend Claude with skills | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/slash-commands
  17. Anthropic, Run Claude Code programmatically | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/headless
  18. Anthropic, CLI reference | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/cli-reference
  19. Anthropic, Run prompts on a schedule | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/scheduled-tasks
  20. IEEE and The Open Group, crontab | The Open Group Base Specifications Issue 8, IEEE Std 1003.1-2024（2024）. https://pubs.opengroup.org/onlinepubs/9799919799/utilities/crontab.html
  21. GitHub, Workflows | GitHub Docs（参照日 2026-07-18）. https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows
  22. GitHub, Workflow syntax for GitHub Actions | GitHub Docs（参照日 2026-07-18）. https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
  23. Anthropic, Claude Code GitHub Actions | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/github-actions
  24. id774, 生成 AI の競争軸は、モデルから業務実装へ移る（2026-06-25）. https://blog.id774.net/entry/2026/06/25/4922/
  25. id774, AI が脆弱性を見つけても、安全になるとは限らない（2026-07-14）. https://blog.id774.net/entry/2026/07/14/4959/
  26. Anthropic, Create custom subagents | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/sub-agents
  27. Anthropic, Run agents in parallel | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/agents
  28. Anthropic, Run parallel sessions with worktrees | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/worktrees
  29. Git, git-worktree Documentation（参照日 2026-07-18）. https://git-scm.com/docs/git-worktree.html
  30. id774, 2026 年上期の Devin の進化を振り返る（2026-07-10）. https://blog.id774.net/entry/2026/07/10/4976/
  31. Anthropic, Connect Claude Code to tools via MCP | Claude Code Docs（参照日 2026-07-18）. https://code.claude.com/docs/en/mcp
  32. Model Context Protocol, Specification（2025-11-25）. https://modelcontextprotocol.io/specification/2025-11-25
  33. Model Context Protocol, Authorization（2025-11-25）. https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
  34. id774, AI の答えは、採用されたときに責任になる（2026-06-26）. https://blog.id774.net/entry/2026/06/26/4925/