Claude Codeで引き継ぎ資料を作る — 社内ツールをコードとgit履歴からRUNBOOK.mdへ

担当者が抜けた社内ツールの引き継ぎ資料は、「CLAUDE.md」と「RUNBOOK.md」の2枚に分けて作ると、次の担当者にも次のClaude Codeセッションにも使えます。CLAUDE.mdは毎回読み込まれる短い要点で、RUNBOOK.mdは障害時に人が開く手順書です。材料にするのはソースとgit履歴で、Claude Codeには読み取りだけを任せます。

この記事では、請求CSVを毎晩作る社内バッチを例に、棚卸し、git履歴の掘り方、2枚の書き分け、触ってはいけない所の固め方、聞き取りが必要な項目を順に示します。例の名前やパスは説明用の仮のものです。

引き継ぎで拾うのは「コードに書かれていないこと」

引き継ぎ資料に、ディレクトリ構成や依存ライブラリの一覧は要りません。それはClaude Codeがコードを読めば分かる内容です。公式のベストプラクティスも、書くのは「リポジトリを読んでも見つからないもの」に絞るよう勧めています。例として挙がるのは、会議で決まった判断、特定の人の頭の中にしかないデプロイ手順、結合テストに必要な環境変数です。

書くかどうかは、次の2つで決められます。

1. コードを読めば見つかるか
2. 実際に見に行くか

両方「はい」なら書きません。社内ツールの属人化は、この線の外側に集まります。

下の3行は、コードからは読めません。履歴と人から集める必要があります。

CLAUDE.mdとRUNBOOK.mdの役割を分ける

公式ドキュメントは、CLAUDE.mdを「毎回の会話の冒頭で読み込まれる指示」と位置づけています。1ファイル200行以内が目安で、長いほどコンテキストを使い、守られにくくなります。複数手順にわたる内容や、一部のコードにしか関係しない内容は、スキルやパス指定のルールに移すよう案内されています。

引き継ぎ資料はこの性質に合わせて2枚に割ります。

RUNBOOK.mdをCLAUDE.mdから@RUNBOOK.mdで取り込むのは避けます。公式によれば、@pathのインポートは読み込む量を減らさず、取り込んだファイルも同じ会話の冒頭で一緒に読み込まれます。長い手順書を毎回読ませることになります。CLAUDE.mdには「障害対応の手順はdocs/RUNBOOK.md」とパスを書くだけにして、必要になったときにClaudeが開く形にします。

人間向けのメモをCLAUDE.mdに残したいときは、ブロック単位のHTMLコメントが使えます。コメントはClaudeに渡る前に取り除かれるので、コンテキストを消費しません。

手順1: 読み取りだけで棚卸しする

最初の1回は、書き換えを許さないplanモードで始めます。planモードのClaudeはファイルを読み、読み取り専用のシェルコマンドで調べますが、承認するまで編集しません。

cd ~/work/billing-batch
claude --permission-mode plan

起動したら、材料の洗い出しだけを頼みます。プロンプトの例です。

このリポジトリは退職した担当者が運用していた請求バッチです。
引き継ぎ資料の材料として、次を表にしてください。
1. 起動のきっかけ（cron、スケジューラ、手動実行）と実行場所
2. 読み書きする外部のもの（DB、ファイルサーバー、API）
3. 必要な環境変数と設定ファイル（値は書かず、名前だけ）
4. 失敗時にログが出る箇所と、出力先
各行に根拠のファイルと行番号を付け、コードから読み取れなかった
項目は「未確認」と書いてください。推測で埋めないでください。

「未確認」を許すことが肝心です。cronの設定がサーバー側にあれば、リポジトリからは見えません。未確認の行は、後で前任者への聞き取りか、サーバーの調査で埋めます。

大きなリポジトリなら、探索をサブエージェントに任せると、ファイルの読み込みで本体の会話が膨らむのを防げます。公式のワークフロー集にも、探索を委任して結果だけを受け取る方法が載っています。

手順2: git履歴から「壊れた所」と「触れない所」を拾う

過去に壊れた箇所は、コードを読んでも出てきません。履歴を見ます。次のgitコマンドの出力をClaudeに渡して分類させます。

# 修正・巻き戻し・緊急対応らしいコミット
git log --oneline -i -E --grep='fix|revert|hotfix|緊急|障害|戻' \
  --since='3 years ago'
 
# 変更の多いファイル（壊れやすい場所の候補）
git log --since='3 years ago' --name-only --pretty=format: \
  | sort | uniq -c | sort -rn | head -20
 
# 特定のファイルの来歴（改名後も追う）
git log --follow --stat -- src/rate_table.py

出力はそのままパイプでも渡せます。公式の例はgit log --oneline -20 | claude -p "summarize these recent commits"の形です。ただし、引き継ぎ資料では要約だけでは足りません。コミットごとに「何が壊れたか」「どう直したか」「再発しうる条件」を表にさせます。

次のgit logの出力から、障害や不具合の修正コミットを拾い、
RUNBOOK.mdの「過去に壊れた箇所」の表にしてください。
列は、コミットID、日付、症状、原因、直し方、再発しうる条件。
コミットメッセージから読み取れない列は「未確認」にしてください。

履歴から拾える合図と、その読み方は次のとおりです。

revertが出てきたら要注意です。「やってみて戻した」という事実は、なぜ戻したかが分からないと、次の担当者が同じことを繰り返す原因になります。

手順3: RUNBOOK.mdに書く骨格

棚卸しと履歴の表が揃ったら、RUNBOOK.mdにまとめます。各項目に根拠を付けるのが、この資料を信用できるものにする条件です。根拠のない記述は、後から誰も直せません。

# 請求バッチ RUNBOOK
 
## 概要
- 目的: 毎晩2:00に当日分の請求CSVを作り、経理の共有フォルダに置く
- 根拠: `crontab.sample`、`src/main.py` の `run()`
 
## 実行方法
| 項目 | 内容 | 根拠 |
|---|---|---|
| 起動 | サーバー`batch01`のcron（毎日2:00） | 未確認（サーバーで`crontab -l`） |
| 手動実行 | `python -m src.main --date YYYY-MM-DD` | `src/main.py` L40 |
| 環境変数 | `DB_URL`、`SMB_PATH`（値は管理者に確認） | `.env.example` |
 
## 失敗したとき（上から順に確認）
1. 共有フォルダに当日のCSVがあるか
2. `logs/batch.log` の末尾にERRORがあるか
3. `DB_URL`の接続先が生きているか
4. 同じ日付で再実行してよいか → 下の「再実行の注意」
 
## 再実行の注意
- 同じ日付を2回流すとCSVが上書きされる（`src/export.py` の `open(..., 'w')`）
- 経理が取り込み済みかを先に確認する（未確認: 取り込みの時刻）
 
## 過去に壊れた箇所
| コミット | 日付 | 症状 | 原因 | 再発しうる条件 |
|---|---|---|---|---|
 
## 触ってはいけない所
- `config/rate_table.csv`: 手編集禁止。経理が更新する（根拠: 手編集で金額がずれた修正コミット）
 
## 未確認の項目（前任者に聞く）
- cronの実際の設定、障害時の連絡先、経理の取り込み時刻

「失敗したとき」は、症状から原因に近づく順に並べます。ログの場所だけを書いた資料は、深夜に障害が起きたときに役に立ちません。

手順4: CLAUDE.mdには短い要点だけを残す

CLAUDE.mdは、次のClaude Codeセッションが作業を安全に進めるための最小限にします。公式のベストプラクティスでは、残すものを4つに絞っています。作業を確認するコマンド、コードが誤解を招く箇所、リポジトリにない判断、2回直したことのある指摘です。

# 請求バッチ
 
## コマンド
- テスト: `pytest tests/ -q`
- 1日分を手動実行: `python -m src.main --date YYYY-MM-DD --dry-run`
 
## 注意（コードを読んでも分からないこと）
- `config/rate_table.csv` は編集しない。経理が更新する
- 本番の再実行は同じ日付のCSVを上書きする。`--dry-run` で確認する
- `src/legacy/` は現役で動いている。新しいコードの手本にしない
 
## 運用の手順書
- 障害対応と過去の事故: `docs/RUNBOOK.md`

この例の--dry-runは仮のオプションです。実在しないオプションを書くと、次のセッションが存在しないコマンドを実行しようとします。書く前に、実際のコードで動くことを確かめてください。

/initで最初の下書きを作る方法もあります。公式によれば、/initはコードベースを分析してビルドコマンドやテスト手順を拾います。ただし、拾えるのはコードから分かる範囲です。そこへ上の「注意」の節を人間が足すことになります。

触ってはいけない所は、文章に頼らず設定で止める

CLAUDE.mdの記述は、強制される設定ではなく、Claudeが読む文脈です。公式ドキュメントでも、守られる保証はないとされています。「このファイルは編集しない」を確実にしたいなら、権限のdenyルールを使います。

{
  "permissions": {
    "deny": [
      "Edit(/config/rate_table.csv)",
      "Read(./.env)"
    ]
  }
}

これは.claude/settings.jsonに置く例です。denyルールは、どの権限モードでも効きます。パスの先頭の/は、プロジェクト設定では作業ディレクトリ（Claude Codeを起動した場所）からの相対パスとして扱われます。

ここで限界も押さえておきます。ベストプラクティスの文書は、ルールが照合するのはツール呼び出しであって意図ではないと説明し、Readのdenyはファイルを開くスクリプトまでは止めないと述べています。シェル経由の書き換えまで確実に止めたいときは、サンドボックスやフックとの併用を検討します。設定の見方はClaude Codeの/permissionsコマンドで権限ルールとauto mode拒否を管理するにまとめています。

聞き取りが要る項目は「未確認」のまま残す

Claude Codeに作らせた資料が最も危険になるのは、分からない所が、それらしい文章で埋まったときです。未確認の項目は、未確認のまま残します。前任者がまだ連絡のつく相手なら、次の質問を30分の聞き取りに使えます。

• cronやスケジューラは、どのサーバーのどのユーザーで動いているか
• 年に1回や月末だけ動く処理はあるか
• 手動で行っている作業（ファイルの受け渡し、承認）はあるか
• 過去の障害で、記録に残っていない回避策はあるか
• 触ってはいけないと言われている所と、その理由は何か
• 連絡が必要な相手（経理、基盤、ベンダー）は誰か

聞いた内容は、RUNBOOK.mdの該当行を「未確認」から確認済みに書き換える形で反映します。聞き取り元が分かるよう、「前任者に確認（日付）」と添えておくと、後から検証し直せます。連絡がつかない場合は、未確認の行がそのまま次の担当者の宿題になります。それでも、宿題の存在が見える状態は、見えない状態よりはるかに安全です。

引き継ぎの後に、資料を腐らせない

引き継ぎ資料は書いた日から古くなります。公式が勧めるのは、同じミスを2回したときや、同じ説明を毎回チャットで繰り返すときにCLAUDE.mdへ足す運用です。新しい担当者が最初の1か月で詰まった所は、そのままRUNBOOK.mdの更新材料になります。

定期的な点検には/doctor prompt-auditが使えます。存在しないファイルやコマンドへの参照、互いに矛盾する指示を洗い出してくれます。v2.1.283以降が必要で、結果は提案として出るだけで、頼むまでファイルは書き換わりません。CLAUDE.mdが長くなってきたときの扱いはCLAUDE.md is too long警告の意味と直し方が詳しいです。

隣接する資料との使い分け

引き継ぎ資料は、運用の視点で書く資料です。同じコードから作る別の資料とは、目的が違います。

• 画面と業務ルールを仕様として起こすなら、VB6のコードを読み仕様書に起こす手順の形になります
• 業務用語とコード上の名前の対応表は、ドメイン用語集をCLAUDE.mdに置く手順で作れます
• 新メンバー向けにコードの構造を説明するなら、アーキテクチャ概要を根拠つきで書く手順です
• ファイルごとの担当を履歴から割り出す作業は、CODEOWNERSをgit logから作る手順で扱っています

まとめ

引き継ぎ資料の価値は、コードから読めない情報をどれだけ残せたかで決まります。ソースの要約はClaude Codeが毎回やり直せるので、資料には「いつ・どこで動くか」「壊れたときの見方」「過去の事故」「触れない所」を残します。分からなかった所を「未確認」と明示して、前任者の聞き取りや次の担当者の確認で埋めていく運用にすれば、資料は一度きりの成果物ではなく、更新され続ける台帳になります。