既存システムAI駆動引き継ぎ講座_受講者用

UDEMY COURSE｜CLAUDE CODE × LEGACY HANDOVER 既存システムをAI駆動で引き継ぐ 分析・回収・テスト・レビュー・質問と、並列処理【Claude Codeコマンド実践】 「引き継ぎ」の最初の3日間を、コマンドで動かして体で覚える 🐰 うさうさ研修工房 ｜ 対象：新人〜中堅の開発・DXエンジニア 確認日 2026/10/18（公式ドキュメント準拠）

WELCOME この講座でできるようになること 引き継ぎの「型」を持つ 1 分析 → 回収 → テスト → レビュー → 質問 → 並列。迷わず進める6つの流れを身につけます Claude Codeのコマンドを使い分ける 2 /plan /init /btw /goal /verify /code-review /batch など、場面ごとに「どれを使うか」を選べます AIに任せきりにしない検証の習慣 3 「できたように見える」で止めない。合否が出る形でAIに渡し、証拠を見て判断できます はじめに 1

COURSE MAP 講座の全体像（スロープ設計：全8章） 前半｜知識編（座学） 後半｜実践編（ハンズオン） Ch.1 なぜ「分けて・検証しながら」進めるのか Ch.5 1日目：分析と回収 Ch.2 今回使う道具を知る Ch.6 2日目：テストで守る Ch.3 分析する（読むだけモード） Ch.7 3日目：レビューと並列処理 Ch.4 回収する ★山場 Ch.8 振り返りと次のステップ はじめに 2

1 CHAPTER 1 なぜ「分けて」「検証しながら」進めるのか Why｜AI駆動の引き継ぎが効く理由と、最初の落とし穴 今日のゴール 引き継ぎ案件でAIを使うときの3つの基本方針を、自分の言葉で説明できる Chapter 1 3

WHY 現場の「あるある」から始めましょう ドキュメントが古い・無い 1 仕様書は3年前のまま。コードだけが唯一の真実、ということは珍しくありません 作った人がもういない 2 「なぜこう書いたのか」を聞ける相手がいない。知見は頭の中にしか無かった テストが無い 3 直した結果、別の場所が壊れても気づけない。だから触るのが怖い Chapter 1 4

KEY IDEA AIの「作業用の記憶」には限りがある ありがちな使い方 引き継ぎ向けの使い方 ・「システム全体を調べて」と範囲なしで依頼 ・調査は別の部屋（サブエージェント）に出す ・何百ファイルを読み、記憶が満杯に ・メインの会話には「要約」だけ戻ってくる ・埋まるほど性能が落ちる（公式の注意） ・範囲を絞って頼む ・結局、肝心な指示が忘れられる ・結果は文書に残して会話を /clear できる Chapter 1 5

3 PRINCIPLES 基本方針は3つだけ ① 調査はサブエージェントに出す 1 別コンテキストで動き、要約だけを返す。メインの会話が汚れません ② 検証できる形にする 2 AIは「できたように見える」で止まりがち。テストやビルドなど、合否が出る仕組みがあると自分で直して回ります ③ 作った本人にレビューさせない 3 新しいコンテキストのレビュー役は、実装時の思考に引きずられません Chapter 1 6

MINI EXERCISE ミニ演習：あなたの現場で当てはめてみよう お題1 いま手元にある引き継ぎ案件（または過去の案件）を1つ思い浮かべる 1 古い・いない・無い、のどれが一番つらいですか？ お題2 3つの方針のうち、一番「できていなかった」ものはどれ？ 2 調査／検証／レビュー の中から1つ選んでメモしましょう Chapter 1 7

2 CHAPTER 2 今回使う道具を知る What｜コマンドは覚えず、「役割」で整理する 今日のゴール 8つの道具グループの役割を説明でき、組み込みサブエージェント3種を区別できる Chapter 2 8

TOOLBOX 今回使う道具（役割で覚える） 道具 役割 主なコマンド・設定 プランモード 読むだけで計画を立てる /plan Shift+Tab --permission-mode plan サブエージェント 別コンテキストで調査・レビュー .claude/agents/*.md @"名前 (agent)" /btw 会話に残さない質問 /btw 質問 /goal 条件を満たすまで続ける /goal 条件 検証系 実際に動かして確認 /verify /run レビュー系 バグ・セキュリティ・整理 /code-review /security-review /simplify 並列実行 複数を同時に回す /subtask /fork /batch claude agents --worktree Chapter 2 9

BUILT-IN 組み込みサブエージェント3種 名前 用途 ツール Explore コードベースの高速な検索・分析 読み取り専用（Write・Editは拒否） Plan プランモード中のコードベース調査 読み取り専用 general-purpose 探索と実行が必要な複雑な作業 すべてのツール Chapter 2 10

MINI EXERCISE ミニ演習：たとえ話で整理しよう プランモード ＝ 「見学だけの現場視察」 1 手を出さず、見て回って計画を立てる。サブエージェント ＝ 「別室の調査担当」 お題 /goal と /btw は、現場のどんな役割に近い？ 2 ヒント：「終わるまで帰れない係」と「ちょっとした横の質問係」 Chapter 2 11

3 CHAPTER 3 分析する：まず「読むだけ」で始める How①｜プランモードと質問の型で、システムの全体像をつかむ 今日のゴール プランモードで起動し、出典を指した質問とサブエージェント調査で、安全に分析を始められる Chapter 3 12

HOW 1-1 最初の一歩はプランモードで「読むだけ」 この間、Claudeはファイルを変更しません。壊す心配なく探検できます。 # 起動時にプランモード ポイント claude --permission-mode plan # 起動後は Shift+Tab で切り替え • 引き継ぎの初日は、まずここから • 特別な書き方は不要。先輩に聞く感覚で普通に 質問してOK • 計画だけ立てさせたいときは /plan も使える # → ステータスバーに # Chapter 3 plan mode on と出ればOK 13

ASK WELL 「出典」を指して聞くと精度が上がる 悪い例 良い例 「なぜこのAPIはこんなに変なの？」 「ExecutionFactory の git 履歴を見て、このAPIがどうなってきた か要約して」 → 憶測で答えるしかなく、 もっともらしい作り話になりやすい Chapter 3 → git履歴・チケット・設計書が「なぜそうなったか」を教えてくれる 14

HOW 1-2 調査はサブエージェントに出す 公式が勧めるプロンプトです。日本語でも通じます。 サブエージェントを使って、 ポイント 認証まわりのトークン更新の仕組みを調べて。 再利用できる OAuth 用の • メインの会話には要約だけが戻る ユーティリティがあるかも教えて。 • 「investigate」を範囲なしで頼むと、何百ファイル も読んで記憶を使い切る • 範囲を絞る or サブエージェントへ # 容量が心配なとき /context # 使用量を見る /compact # 圧縮する /clear # 新しい話題なら全消し Chapter 3 15

MINI EXERCISE ミニ演習：質問を「強く」書き換える お題1 「ログイン周りがよくわからない」を、出典つきの質問に書き換える 1 例：「src/auth/ と直近のgit履歴を見て、セッション期限の扱いを要約して」 お題2 範囲なしの「このシステムを調べて」を、範囲を絞った依頼に直す 2 対象ディレクトリ・知りたいこと・出力形式の3点を入れてみましょう Chapter 3 16

4 CHAPTER 4 回収する：頭の中の知見を文書に残す ★山場 How②｜CLAUDE.md・SPEC.md・インタビュー方式 今日のゴール 分析で分かったことを「どこに・どう残すか」を判断し、SPEC.mdまで書き出す流れを説明できる Chapter 4 17

HEADS UP ここが山場です（でも大丈夫） 「回収」とは何をすること？ 1 既存コード・設定・人の頭の中にある仕様や知見を拾い上げ、CLAUDE.mdや仕様書として文書に残すことです なぜ会話に置いたままではダメ？ 2 会話は /clear で消えます。文書にすれば、次のセッションにもチームにも渡せます コツは「置き場所」を先に決めること 3 次のスライドの表に沿って選べば迷いません Chapter 4 18

WHERE TO KEEP 回収先を決める 回収するもの 置き場所 コマンド 常に守るルール（コマンド・命名・禁止事項） CLAUDE.md /init /memory 機能ごとの仕様 SPEC.md などのファイル インタビュー方式 たまに使う手順・ドメイン知識 スキル（.claude/skills/名前/SKILL.md） 手作成 毎回必ず実行したい処理 フック /hooks Chapter 4 19

CLAUDE.md CLAUDE.md は「短く」。消したらAIが間違えるか？ 入れる 入れない ・AIが推測できないBashコマンド ・コードを読めばわかること ・デフォルトと違うコードスタイル ・言語の標準的な慣習 ・テストの実行方法 ・詳細なAPIドキュメント（リンクで十分） ・ブランチ名・PRの作法 ・頻繁に変わる情報 ・プロジェクト固有の設計判断 ・ファイルごとの説明 ・環境のクセ（必須の環境変数） ・「きれいに書く」のような当たり前 Chapter 4 20

INTERVIEW 仕様は「インタビューさせて」書き出す 現行コードから読めることは先に調べさせ、わからない業務ルールだけ質問させます。 この請求バッチの仕様を、 ポイント 私にインタビューして整理して。 現行コードから読み取れることは 先に調べ、わからない業務ルール だけ質問して。 • 仕様ができたら新しいセッションで実装すると、記 憶がきれいな状態で始められる • 良い仕様の条件：自己完結／関係ファイルを名 指し／やらないことを書く／最後に検証手順 聞き終えたら SPEC.md に 書き出して。 Chapter 4 21

FACT / GUESS / UNKNOWN 分析結果は「事実・推測・不明」に分ける 事実 1 ファイルパス・行番号つきで確認できたこと 推測 2 それらしいが、確認できていないこと（ここを放置すると誤解のまま進む） 不明 3 コードからは分からないこと → 推測で実装せず、私に質問して（選択肢つきで）と頼む Chapter 4 22

MINI EXERCISE ミニ演習：回収先の仕分けゲーム お題 次の4つはどこに残す？（CLAUDE.md／SPEC.md／スキル／フック） 1 ①テスト実行コマンド ②請求バッチの締め日ルール ③コミット前に必ずlintを回す ④障害対応の定型手順 答え合わせのヒント 2 「毎回必ず」ならフック、「常に守る」ならCLAUDE.md、「機能ごと」ならSPEC.md、「たまに」ならスキル Chapter 4 23

BRIDGE 前半の知識が、後半のどこで使われる？ Ch.1 基本方針 → 全ての章で「分ける・検証する」 Ch.2 道具 → Ch.5〜7 でコマンドを実際に叩く Ch.3 分析 → Ch.5 1日目の前半 Ch.4 回収 → Ch.5 1日目の後半 と Ch.6 のテストの土台 🐰 ここで小休憩。コーヒーをどうぞ！ 後半は実際に手を動かします 橋渡し 24

5 CHAPTER 5 1日目：分析と回収をやってみよう Hands-on｜最初の小さな成功体験をつくる 今日のゴール プランモードで調査し、CLAUDE.mdとSPEC.mdの土台を作って /clear するまでを完走できる Chapter 5 25

DAY 1 1日目の手順（7ステップ） 完璧を目指さず、まず最後まで通してみましょう。 1. claude --permission-mode plan 2. /init 3. code-explorerで構成と業務フローを調査 4. 「事実／推測／不明の3つに分けて」 5. /memory ポイント # CLAUDE.mdの土台 # 共通ルールを回収 • 3の調査はサブエージェントに任せる • 4で「分かっていること」を可視化する • 7で会話を空にしても、文書は残る 6. 不明点はインタビュー → SPEC.md 7. /clear Chapter 5 26

SUBAGENT 調べる人：code-explorer を作る .claude/agents/code-explorer.md（公式パターンに沿った例） --- ポイント name: code-explorer • 必須は name と description だけ code works and reports findings with • description は「いつ任せるか」を具体的に file paths. Use before any change. • tools を読み取り系だけにして安全に description: Investigates how existing tools: Read, Glob, Grep model: sonnet --You investigate existing code. Never modify files. Report: (1) facts (2) assumptions (3) open questions Chapter 5 27

CHECK POINT 1日目の確認ポイント CLAUDE.md は短くなっていますか？ 1 1行ずつ「消したらAIが間違えるか？」で見直し。/doctor で削る提案ももらえます 不明点が「質問」として残っていますか？ 2 推測で埋めていないか。SPEC.md に未解決事項として書かれていればOK 調査結果が文書になっていますか？ 3 /clear しても、次のセッションで続きができる状態が合格ライン Chapter 5 28

6 CHAPTER 6 2日目：テストで守りを作る Hands-on｜合否が出る形でAIに渡す 今日のゴール 現行動作を固定するテストを書かせ、/goal で全テスト成功まで回せる Chapter 6 29

PRINCIPLE AIに「合否が出る確認」を渡す 1回のプロンプトで 1 「実装して、テストを実行して、直るまで繰り返して」 セッション全体で 2 /goal に条件を書く。条件を満たすまで続けてくれます 決定論的な門番として／第二の目として 3 Stopフックでテストが通るまでターン終了をブロック。検証用のサブエージェントに見せる Chapter 6 30

ASK WELL テストの頼み方：弱い依頼と強い依頼 弱い依頼 強い依頼 「foo.py の、ログアウト状態のエッジケースのテストを書いて。 「foo.py のテストを書いて」 モックは使わないで」 「ログインのバグを直して」 「src/auth/ を見て。まず再現する失敗テストを書き、それから直 して」 Chapter 6 31

/goal /goal で「通るまで」回す 評価モデルは会話に出た内容だけを見ます。結果の表示を条件に入れるのがコツ。 /goal `npm test` の結果が会話に ポイント 表示され、全テストが成功していること # 動かして確かめる /run # アプリを起動して操作 /verify # ビルド・起動して観察 • /goals ではなく /goal（v2.1.139以降） • 成功した、だけの報告はいらない • Claudeのチェック後、自分でも /verify # 証拠を見せて、と頼む 「テスト出力と実行コマンドを見せて」 Chapter 6 32

CHECK POINT 2日目の確認ポイント テストは「現行動作を固定」していますか？ 1 test-writer には本番コードを変えさせない（isolation: worktree で隔離すると安心） /goal の条件に「結果を表示」が入っていますか？ 2 入っていないと評価モデルが判断できず、止まらない／早く止まることがあります /diff で変更範囲を確認しましたか？ 3 範囲外の変更が混ざっていないか、必ず自分の目で Chapter 6 33

7 CHAPTER 7 3日目：レビューと並列処理 Hands-on｜書く人と見る人を分け、エージェントを並べる 今日のゴール 目的別にレビューコマンドを選び、worktreeで衝突を避けながら並列で進められる Chapter 7 34

REVIEW レビューは目的別に使い分ける コマンド 探すもの 補足 /code-review 正しさのバグ level: low〜ultra、--fix で修正、--comment でPRコメント /security-review インジェクション・認可・データ露出 originリモートが必要 /simplify 整理（再利用・簡素化・効率） バグ探しではない Chapter 7 35

WRITER / REVIEWER 書いた人と見る人を分ける セッションA（書く人） セッションB（見る人） 「APIのレート制限を実装して」 「@src/middleware/rateLimiter.ts を レビューして。エッジケース・競合状態・ ↓ レビュー結果を受け取り 既存ミドルウェアとの一貫性を見て」 「これを直して」 ※ 新しい記憶なので、実装時の思い込みが無い Chapter 7 36

WATCH OUT 指摘を全部直さない 穴を探せと言われたレビュー役は、健全なコードでも何か報告する 1 全部に対応すると過剰設計になります（公式の注意） 頼み方で防ぐ 2 「正しさと明示した要件に関わる不足だけ報告して。スタイルの好みは不要」と伝える それ以外は「任意」として扱う 3 採用するかは自分で決める。AIの指摘は意見であり、命令ではありません Chapter 7 37

PARALLEL 並列の判断表：やりたいこと → 方法 やりたいこと 向いている方法 使うもの 調べものを横に流す サブエージェント 「サブエージェントを使って…」 今の会話を引き継いで脇の作業 フォークしたサブエージェント /subtask <task> 会話をコピーして別セッションで並走 バックグラウンドセッション /fork [prompt] 同じ変更を大量のファイルに 並列サブエージェント /batch <指示> 複数の機能を同時に作る 別セッション＋worktree claude -w 名前 / claude agents 数千ファイルをスクリプトで claude -p のループ シェルスクリプト Chapter 7 38

WORKTREE 並列で「ファイルがぶつからない」ために git worktree は、ファイルとブランチが別の作業ディレクトリ（履歴は共有）です。 claude --worktree feature-auth ポイント # 別ターミナルで claude --worktree bugfix-123 # 監視画面（研究プレビュー） claude agents claude --bg "flakyなテストを調べて" • worktreeは新規チェックアウト → .env は入らな い。.worktreeinclude で自動コピー • 依存関係のインストールも再度必要 • 並列にするほど利用量の上限に早く近づく • Agent viewで削除すると worktree も消える → 先にコミット # 隔離したサブエージェント isolation: worktree Chapter 7 39

CHECK POINT 3日目の確認ポイント レビュー役は新しいセッション（または別サブエージェント）ですか？ 1 PLAN.md と照らして「不足だけ」報告させていますか コマンドを目的で使い分けましたか？ 2 /code-review＝バグ、/security-review＝安全性、/simplify＝整理、/verify＝実動作 並列にした作業はコミット済みですか？ 3 worktreeの中の作業は、消す前に必ずコミット Chapter 7 40

8 CHAPTER 8 振り返りと次のステップ Wrap-up｜失敗パターンを知り、現場へ橋をかける 今日のゴール 避けたい失敗パターンを言え、明日から自分の現場で試す1つを決められる Chapter 8 41

PITFALLS 避けたい失敗パターン（公式より） パターン 対策 何でも入りのセッション 無関係な作業の間で /clear 直しては直される 2回失敗したら /clear。学んだことを入れた良いプロンプトで最初から 長すぎる CLAUDE.md 容赦なく削る。自然にできることは消すか、フックにする 信じてから確かめる テスト・スクリプト・スクリーンショットで検証。検証できないなら出荷しない 終わらない調査 範囲を絞る、またはサブエージェントに出す 指摘を全部直す レビュー役に「正しさに関わる不足だけ」と伝える Chapter 8 42

SUMMARY まとめ：6つの流れ 分析・回収 1 プランモードで読むだけ。調査はサブエージェント。分かったことは CLAUDE.md・SPEC.md・スキルへ テスト・レビュー 2 合否が出る形で渡す（/goal に「結果を表示」）。書く人と見る人を分ける 質問・並列 3 /btw で会話を汚さない。不明は質問させる。worktree で衝突を避け、利用量に注意 Chapter 8 43

NEXT STEP 明日からの一歩（1つだけ決めよう） 今日いちばん使えそうだったものは？ 1 例：プランモード／CLAUDE.mdの見直し／/goal／Writer-Reviewer それを、どの案件の・いつ試す？ 2 場面・日付まで決めると実行率が上がります コマンドは更新が速いので最新を確認 3 /help と /release-notes、公式のcommandsページ。日本語版と食い違ったら英語版を優先 Chapter 8 44

おつかれさまでした！ 引き継ぎは「分けて、検証して、文書に残す」。 それだけで、怖くなくなります。 🐰 参考：Claude Code 公式ドキュメント（Best practices／Subagents／Worktrees／Agent view／Commands／Goal） うさうさ研修工房