開発の引き継ぎメモ、型を決めるだけで事故が消えた：4項目ハンドオフ術

金曜の夕方、同僚にこう言われました。「あの認証まわりのブランチ、続き引き継いでいい？」

いいよ、と返してSlackを見たら、置いてあったのは一行。「途中まで直した。あとよろしく」。

その「途中」がどこなのか、何が動いて何が壊れているのか、なぜそのファイルを触ったのか。月曜にブランチを開いた僕は、まず30分かけて他人のコードを読み直すところから始めました。差分を追い、git logを眺め、結局本人にSlackで聞く。コードを書く前の30分が、毎回まるごと消えていく。

引き継ぎがうまくいかないのは、相手の能力が低いからじゃありません。「次の人が何を知りたいか」を書く型が決まっていないだけです。そして今は、その「次の人」がClaude Codeのこともある。型がないと、人間にもAIにも文脈が伝わらず、毎朝コードを読み直す時間から一日が始まります。

この記事は、開発作業の引き継ぎ（ハンドオフ）に絞って、僕が落ち着いた4項目の型を共有します。レビュー基準や権限設計を含めたチーム運用全体は、姉妹記事のClaude Codeチーム活用ガイドにまとめてあります。

この記事の要点

• 開発の引き継ぎメモは「やったこと・残り・つまずき・次の一手」の4項目で十分。長い作業日誌は誰も読まない。
• 一番効くのは**「次の一手」**。次の人がコマンド一発・ファイル一つで動き出せる粒度まで具体に落とす。
• 状態（state）も一緒に残す。ブランチ名、最後のコミット、動かし方、未コミットの有無。コードを読み直させない。
• CLAUDE.mdは恒久ルール、ハンドオフは「いまこの瞬間」の文脈。役割が違うので混ぜない。
• Claude Codeへの引き継ぎも人間と同じ型でいい。最後に「次の一手」をそのまま渡せば続きから動く。

そもそもハンドオフメモは何を書くものか

引き継ぎメモを「作業ログ」だと思っていると、まず失敗します。

ログは時系列の記録です。「9時にA関数を直した、10時にBをリファクタした、11時にテストが落ちた」。本人には意味があるけど、引き継ぐ相手にはノイズです。相手が知りたいのは、あなたが何時間目に何をしたかじゃない。いまブランチはどういう状態で、自分は次に何をすればいいか、それだけです。

旅行の引き継ぎで考えると分かりやすい。友だちに留守宅の世話を頼むとき、「昨日は犬の散歩をして、一昨日は植木に水をやって……」と日記を渡す人はいません。渡すのは「犬の散歩は朝晩2回、ごはんは棚の上、植木は2日に1回水やり、鍵はポストの中」。相手がそのまま動ける情報だけです。

開発のハンドオフも同じ。僕がたどり着いたのは、この4項目でした。

項目	書くこと	一言でいうと
やったこと	完了して動く範囲。証拠（テスト・ビルド結果）つき	ここは信じていい
残り	まだ手をつけていない、あるいは未完成の部分	ここから先が仕事
つまずき	ハマった点、わかった原因、避けた回り道	同じ穴に落ちるな
次の一手	次の人が最初に打つコマンド・開くファイル	まずこれをやれ

順番にも意味があります。最初に「やったこと（信じていい範囲）」で安心させ、「残り」で仕事の範囲を示し、「つまずき」で地雷を共有し、最後に「次の一手」で背中を押す。これだけで、相手のコード読み直し時間が消えます。

4項目を「次の人がすぐ動ける」粒度まで落とす

型を知っただけでは事故は減りません。粒度が雑だと、項目があっても伝わらないからです。僕が実際にやらかした「ダメな書き方」と直し方を並べます。

やったこと：「だいたいできた」は禁句

最初の頃、僕は「認証まわり、だいたいできた」と書いていました。だいたい、が一番こわい。レビューする側は「だいたい」の境界が分からず、結局全部読む羽目になります。

直すなら、動く範囲を証拠つきで断言する。「ログインAPI（POST /login）は実装・テスト済み。npm test src/auth が緑。トークン発行までは本番想定で動く」。ここまで書くと、相手は「ログインは信じていい、見るのはその先」と判断できます。harness-engineering（AIの足場づくり）で学んだのと同じで、機械でわかる証拠を添えるだけで信頼の往復が一気に減ります。

残り：「リファクタ」だけでは伝わらない

「あとリファクタが残ってます」。これも何度も書きました。何のリファクタか分からないと、相手は手を出せません。

「UserService の責務が膨らんでいる。バリデーションを別クラスに切り出したい。ただし急ぎではない」。何を・なぜ・優先度まで書いて、はじめて「残り」になります。

つまずき：原因と回避策をセットで

ここを書く人は本当に少ない。でも一番感謝されるのがここです。「ローカルだとDB接続が落ちる→原因はDockerのポート競合、docker compose down してから上げ直すと直る」。自分が溶かした2時間を、相手は2分で済ませられます。

次の一手：コマンド一発まで具体に

そして最重要が「次の一手」。ここが抽象的だと、4項目すべてが台無しになります。

• 悪い例：「続きをお願いします」
• 良い例：「git checkout feature/auth → npm run dev でログイン画面を開き、src/auth/refresh.ts のTODOコメントから着手。リフレッシュトークンの実装が次のゴール」

次の人が、メモを読み終えた瞬間にキーボードに手を伸ばせるか。それが「次の一手」の合格ラインです。

状態（state）を一緒に残してコードを読み直させない

4項目は「何をすべきか」を伝えます。でもそれだけだと、相手はまずいまの状態を把握するところから始めないといけない。ブランチはどれ？最後のコミットは？動かし方は？未コミットの変更はある？——この確認に、また時間が溶けます。

だから僕は4項目の手前に、機械的な「状態スナップショット」を必ず置きます。考える必要のない、コピペで埋まる事実だけです。

残すもの	例	なぜ要るか
ブランチ名	feature/auth-refresh	どこを開けばいいか即わかる
最後のコミット	a1b2c3d チェックする前の状態	戻す基準点になる
動かし方	npm install && npm run dev	環境構築で詰まらせない
未コミットの有無	stashに2件あり / なし	「あれ、変更どこ？」を防ぐ
関連リンク	IssueのURL、設計メモ	背景を本人に聞かなくて済む

状態は、本人なら頭に入っているけど、引き継いだ瞬間に消える情報です。これを文字に落とすだけで、相手は「環境を整えて、いまの地点に立つ」までをノータイムで終えられます。

ここで一つ、実務で効くコツ。ロールバック地点（戻せるコミットやブランチ）も状態の一部として書いておくと安心です。引き継いだ相手が手を入れて崩したとき、「どこに戻せばいいか」が書いてあるかないかで、復旧の落ち着きがまるで違います。権限やロールバックを含めた運用ループは権限と予算を毎朝回すpermission budget loopで詳しく扱っています。

コピペで使える開発ハンドオフのテンプレ

ここまでを1枚にまとめます。PRコメント、Issue、Slack、Notionにそのまま貼れるMarkdownです。Claude Codeに作業させたあとでも、自分で手を動かしたあとでも、空欄を埋めるだけで引き継ぎが完成します。

# 開発ハンドオフ: <ブランチ名 / 機能名>

## 状態（事実だけ・考えずに埋める）
- ブランチ: feature/auth-refresh
- 最後のコミット: a1b2c3d チェックする前の状態
- 動かし方: npm install && npm run dev
- 未コミット: stashに2件 / なし
- 戻す地点: a1b2c3d
- 関連: IssueのURL、設計メモ

## やったこと（信じていい範囲・証拠つき）
- POST /login 実装・テスト済み（npm test src/auth が緑）

## 残り（何を・なぜ・優先度）
- リフレッシュトークン未実装（優先・次のゴール）
- UserService のバリデーション分離（後回しでよい）

## つまずき（原因と回避策をセットで）
- ローカルでDB接続が落ちる → ポート競合。docker compose down で復旧

## 次の一手（コマンド一発まで具体に）
- git checkout feature/auth-refresh
- npm run dev で /login を開く
- src/auth/refresh.ts のTODOから着手

人間に渡すならこれで十分です。読み終えた相手が、すぐgit checkoutできる状態になっています。

引き継ぐ相手がチームで、権限の線引きまで一緒に渡したいときは、JSONで「触っていい範囲」を添えると話が早い。ここでのsafeは自由に触ってよい範囲、review_requiredは人間の確認が要る変更、blockedは依頼してはいけない操作です。

{
  "handoff_branch": "feature/auth-refresh",
  "approval_rules": {
    "safe": ["read files", "search", "small refactor inside src/auth"],
    "review_required": ["DB migration", "auth config", "deployment"],
    "blocked": ["secrets", "force push", "delete customer data"]
  }
}

このJSONは、次の人が「どこまで自分の判断で進めていいか」を一目で確認するための地図です。口頭で「まあ常識の範囲で」と伝えるより、差分として残したほうが事故が減ります。権限設計そのものの考え方は姉妹記事に譲ります。

Claude Codeに引き継ぐときも、型は同じでいい

ここからが今っぽい話です。引き継ぐ相手が人間とは限りません。Claude Codeに「続きをやって」と渡す日が、もう普通にあります。

うれしいことに、型を変える必要はほぼありません。人間向けに書いた4項目＋状態は、そのままClaude Codeにも効きます。むしろAIのほうが律儀に「次の一手」から動き出すので、書き手側の雑さがそのまま結果に出ます。「いい感じに直しといて」と丸投げすれば、AIは“いい感じ”に意図しない40ファイルを書き換えます。「次の一手」を具体に書けば、その一手から着実に進む。差が露骨です。

実際にClaude Codeへ引き継ぐときは、ハンドオフメモの末尾に作業範囲のプロンプトを足すだけ。

これは開発ハンドオフの引き継ぎです。
まず「状態」を読んで、いまのブランチと動かし方を把握してください。
次にやることは「次の一手」に書いてあります。
作業範囲は src/auth 配下のみ。
DBマイグレーションと認証設定（review_required）は、手を入れる前に必ず確認を取ってください。
完了したら、同じ4項目の形でハンドオフメモを書き直して返してください。

最後の一文がポイントです。Claude Codeに、次のハンドオフメモまで書かせる。すると引き継ぎが途切れず回ります。AIが終わった地点を、また人間かAIが受け取れる。実装の細かい設定例はClaude Code公式ドキュメントで確認できます。

CLAUDE.md とハンドオフメモの使い分け

ここでよく混乱が起きます。「プロジェクトのルールはCLAUDE.mdに書くんだよね？じゃあ引き継ぎもCLAUDE.mdでいいのでは？」——これをやると、両方が壊れます。

違いは時間軸です。

	CLAUDE.md	ハンドオフメモ
寿命	恒久（プロジェクトが続く限り）	使い捨て（引き継いだら役目終了）
内容	常に守るルール・規約・コマンド	いまこの瞬間の作業状態
例	「テストはvitest」「PRは日本語」	「refresh.tsのTODOから着手」
読む人	全員・毎回	次の担当者・一回だけ

CLAUDE.mdに「refresh.tsのTODOから着手」と書いたら、その作業が終わった後もずっと残って、的外れな指示としてAIを惑わせます。逆に、ハンドオフメモに「テストはvitestを使う」と毎回書いていたら、本来CLAUDE.mdに一度書けば済むルールを、引き継ぎのたびに書き写すことになる。

線引きはシンプルです。「来週も再来週も正しいこと」はCLAUDE.md。「今日だけ正しいこと」はハンドオフメモ。CLAUDE.mdは育てすぎても効かなくなるので、何を書き何を消すかの原則はCLAUDE.mdは何を書かないかで決まるにまとめてあります。作業文脈の残し方をさらに掘りたいならセッション引き継ぎテンプレートもどうぞ。

よくある質問

Q. 小さい修正でも毎回テンプレを埋めるんですか？ A. 全部は要りません。タイポ修正なら「次の一手」だけ一行で十分です。逆に、未完成のまま渡す・他人やAIが続きをやる・本番に近い箇所、この3つのどれかなら4項目＋状態を埋めてください。事故るのはたいていこの3パターンです。

Q. つまずきを書くのが面倒で続きません。 A. ハマった瞬間にその場で一行メモする運用に変えると続きます。後でまとめて書こうとすると、何にハマったか自分でも忘れます。僕はターミナルの履歴を見ながら、解決した直後に「○○が原因、△△で回避」とだけ残しています。

Q. Claude Codeに引き継ぐとき、人間向けと別のメモを用意すべき？ A. 不要です。同じ4項目＋状態でいけます。違いは末尾に作業範囲のプロンプト（触っていい場所、確認が要る操作）を足すかどうかだけ。AIは「次の一手」が具体なほど素直に動きます。

Q. 引き継ぎ先が崩したとき、戻し方も書くべき？ A. はい。状態に「戻す地点（コミットやブランチ）」を一行入れておくと、相手が安心して手を入れられます。記事や設定だけなら前コミットに戻せば済みますが、マイグレーションや本番設定に触る変更は、戻す順番まで書いておくと現場で迷いません。

Q. レビューや権限のルールはこの記事の範囲ですか？ A. ここは「引き継ぎメモの型」に絞っています。レビュー基準・権限設計・チーム全体の運用はClaude Codeチーム活用ガイドで扱っています。あわせて読むと、引き継ぎから運用までつながります。

実際に試した結果

冒頭の「途中まで直した。あとよろしく」事件のあと、僕はチームの引き継ぎを全部この4項目＋状態に揃えました。

一番変わったのは、月曜の朝です。前は他人のブランチを開いて30分コードを読み直していたのが、状態スナップショットを見てgit checkout、「次の一手」を見て即着手、になりました。読み直しの30分が、ほぼゼロになった。

意外だったのは、Claude Codeへの引き継ぎが同じ型でそのまま回ったことです。人間向けに書いた4項目を渡すと、AIが「次の一手」から動き、終わったら同じ形でメモを書き直して返す。人とAIの間で、引き継ぎがバトンのようにつながりました。

賢いAIや優秀な同僚を探す前に、「次の人が何を知りたいか」を型にする。たった4項目ですが、毎朝のコード読み直しから解放されたのは、これがいちばん効いた、というのが今の実感です。引き継ぎの先にあるチーム運用やレビューまで固めたくなったら、Claude Codeチーム活用ガイドへどうぞ。