Part 5 AIと知識作業・動画
第19章 AIコーディングの実務ワークフロー
動画台本ナレーション全文
Slide 01. AIコーディングの実務ワークフロー
第19章では、AIコーディングの実務ワークフローを扱います。ここではClaude Codeを中心例にします。Claude Codeは、チャットで答えをもらうだけでなく、ファイルを読み、コマンドを実行し、コードも編集できるAI作業環境です。Codexなど別のAI coding agentを使う場合も、この章で覚えたいのは細かい機能名ではありません。何を作るか、何を読ませるか、どう確認するかを自分で管理する型です。
Slide 02. この章で持ち帰ること
この章で持ち帰ってほしいことは三つです。一つ目は、AIコーディングを速く書く道具ではなく、仕様、計画、実装、レビュー、検証の流れとして扱うことです。二つ目は、AIに読ませる情報と、読ませてはいけない情報、そして許可する操作を分けることです。三つ目は、AIが作った差分を自分で読み、テストとログで説明できるようにすることです。
Slide 03. 第18章との接続
第18章では、LLM、prompt、context、tool use、agent、evaluationを学びました。第19章では、その考え方をコード変更に使います。つまり、AIにコードを書かせる前に、何を作るか、何を読ませるか、どこで人間が確認するかを決めます。題材は、支援ステータス一覧を絞り込む小さな機能です。
Slide 04. 速く書くだけではない
AIはコードを書く時間を短くしてくれます。ただし、速く書けるだけでは十分ではありません。何を作るかが曖昧なら、AIの実装も曖昧になります。読ませる情報が足りなければ、既存の作り方とずれることがあります。だから、依頼を小さく分け、差分を読み、テストで確かめるところまでを人間が管理します。
Slide 05. feature brief
AIに依頼する前に、feature briefを書きます。feature briefは、何を作るかを短く整理するメモです。目的、使う人、変更する範囲、今回はやらないこと、受け入れ条件、不明点を書きます。今回なら、メンターが支援ステータス一覧を、ステータスと最終更新日で絞り込めるようにする、という機能です。依頼文を書く前に、作りたいものを整理します。
Slide 06. acceptance criteria
acceptance criteriaは、受け入れ条件です。何ができたら完了かを示します。たとえば、ステータスで絞り込める。最終更新日の範囲で絞り込める。絞り込み条件が、URLやAPIへの問い合わせ条件に残る。不正な値を受け取っても画面を壊さない。既存の一覧表示を壊さない。受け入れ条件があると、AIも人間も完了判断をしやすくなります。
Slide 07. 作業分割
AIに大きな機能を丸ごと任せると、差分が大きくなり、読むのが難しくなります。作業は、workspace確認、調査、計画、実装、テスト、修正、文書化に分けます。最初にbranchやgit statusを見て、今回触ってよい変更と触ってはいけない変更を分けます。1回のAI依頼は、1つの目的と1つの成果物に寄せます。レビューできる大きさに分けることが、実務では大切です。
Slide 08. context pack
context packは、AIに読ませる情報をまとめたものです。仕様、関連ファイル、既存の書き方、テスト、制約、やってはいけないこと、現在のworkspace状態を含めます。AGENTS.mdやCLAUDE.mdのようなAI向け指示ファイルも、あれば確認します。全部読ませれば良いわけではありません。不要な情報が多いと、大事な情報が埋もれます。何を読ませるかを選ぶところから、実装作業は始まります。
Slide 09. 渡してはいけない情報
AIに渡してはいけない情報も先に分けます。.env、secret、API key、本番データ、個人情報、不要なログです。AGENTS.mdやCLAUDE.mdも、秘密情報の置き場ではありません。支援ステータス機能では、実在する受講者データや個人情報を読ませないようにします。AIに必要なのは、仕様、既存実装の形、テスト方針です。迷ったら、貼る前に止まります。
Slide 10. AI coding agent
Claude CodeやCodexのようなAI coding agentは、ファイルを読み、コマンドを実行し、コードを編集できる作業相手です。調査、計画、実装、検証を手伝わせることができます。一方で、実際にコマンドを動かす相手でもあります。だから、何をしてよいか、どのファイルを触ってよいか、どこで人間が承認するかを先に決めます。チャット相談より、確認地点の設計が大切になります。
Slide 11. plan mode
いきなり編集させず、まず調査と計画を依頼します。plan modeは、AIに状況を読ませ、変更方針を出してもらう段階です。この時点では、できるだけ読み取り中心にします。計画には、関連ファイル、既存の書き方、変更対象、テスト方針、リスク、確認したい質問を含めます。実装前に、AIが何を変えようとしているかを見ます。
Slide 12. permission、sandbox、approval
permissionは、AIが何を実行できるかを管理する仕組みです。読むだけ、コマンドを動かす、ファイルを書き換える、gitを操作する、という種類があります。sandboxは触れる範囲を技術的に制限する境界で、approvalは強い操作の前に人間へ確認する止め方です。普段使う開発環境では、強い権限を最初から許可しません。依頼文だけでなく、設定でも止められるようにします。
Slide 13. settings
settingsでは、プロジェクトや個人の設定を管理します。project settingsは、チームで共有したい設定です。local settingsは、自分のPCだけで必要な設定です。たとえば、許可するコマンド、確認が必要な操作、作業ディレクトリの前提を分けます。チームで同じ安全基準を使うには、設定ファイルもレビュー対象として扱います。
Slide 14. CLAUDE.md
CLAUDE.mdは、毎回AIに伝えたいプロジェクトの前提を書くファイルです。AGENTS.mdなど、他のAI向け指示ファイルも同じ役割を持つことがあります。開発コマンド、テストコマンド、設計方針、命名規則、禁止事項、レビュー観点を書きます。ただし、これらは安全を強制する魔法の設定ではありません。古い指示や矛盾した指示は品質を下げるので、コードと同じように見直します。
Slide 15. hooksとskills
hooksとskillsは、繰り返す作業を同じ手順にするための仕組みです。ここでは、名前だけ押さえれば大丈夫です。hooksは、特定のツール利用後にlintやformatなどを動かすきっかけにできます。skillsは、繰り返し使う手順、チェックリスト、作業テンプレートを渡す仕組みです。最初から高度な自動化を作らず、まず手順を明文化します。
Slide 16. 実装依頼
実装依頼では、範囲と検証をセットにします。変更してよいファイル、触らないファイル、受け入れ条件、実行するテストを明示します。AIに、実装後に確認して、とだけ言うのでは足りません。実行したコマンド、結果、失敗、残課題も記録させます。途中で変更範囲が広がったら、いったん止めて計画に戻ります。
Slide 17. 小さな差分
AIが強くても、大きすぎる差分はレビューできません。UI、API、テスト、文書を一度に大きく変えるより、意味のある小さな単位に分けます。まずAPIの絞り込み条件を追加する。次に画面をつなぐ。最後にテストと手動確認を整える。小さな差分は、戻しやすく、説明しやすく、レビューしやすいです。
Slide 18. AI-generated diff review
AIが書いたコードも、人間のコードと同じようにレビューします。AIが自信ありげに説明していても、説明だけで判断せず、diffとテストを見ます。仕様を満たしているか。既存の書き方に沿っているか。不要な抽象化がないか。セキュリティ、アクセシビリティ、エラーハンドリング、テストが抜けていないか。チェックリストで確認すれば、不安を行動に変えられます。
Slide 19. 仕様観点
仕様観点では、受け入れ条件との対応を見ます。ステータスで絞り込めるか。最終更新日で絞り込めるか。条件を組み合わせたときに期待通りか。不正な値や空の条件をどう扱うか。既存の一覧表示を壊していないか。AIが追加した便利そうな動きが、今回の仕様外になっていないかも確認します。
Slide 20. 設計観点
設計観点では、既存の書き方に沿っているかを見ます。画面から送る絞り込み条件、APIでの値の確認、UI部品、テストの書き方が、周りのコードと合っているかを確認します。不要な共通化や大きな抽象化が入っていないかも見ます。AIの提案がきれいに見えても、小さな機能追加なら、今ある構造に合わせた局所変更を優先します。
Slide 21. セキュリティ観点
セキュリティ観点では、入力検証、認可、秘密情報、ログを見ます。絞り込みの値を、そのまま危険な形でDBへの問い合わせに渡していないか。担当外のデータが見えないか。.envやsecretを読ませていないか。ログに個人情報が出ていないか。AIは実装を急ぐと、このあたりを軽く扱うことがあります。第14章の観点をここでも使います。
Slide 22. アクセシビリティ観点
画面を変えるなら、アクセシビリティも確認します。絞り込み項目にラベルはあるか。キーボードだけで操作できるか。選択状態やエラーが伝わるか。色だけに依存していないか。読み上げやフォーカス順で不自然なところがないか。AIが見た目だけ整えたUIを作ることもあるので、第12章の画面確認を使ってレビューします。
Slide 23. テストで閉じる
AIが完了したと言っても、確認なしでは完了にしません。自動テストでは、unit test、integration test、E2Eを使い分けます。手で画面を見るmanual checkも必要です。lint、type check、formatも検証に含めます。テストがない場合は、確認できる最小のテストを追加します。AIコーディングでは、テストが人間とAIの共通言語になります。
Slide 24. 失敗ログを渡す
テストが失敗したら、AIに必要な範囲だけを渡します。実行したコマンド、失敗したテスト名、エラーメッセージ、関連する差分です。ログ全体やsecretを含む出力を、そのまま貼らないようにします。失敗を直させるときも、何を変えてよいか、何を変えてはいけないかを明確にします。失敗ログは、原因候補を絞るためのcontextです。
Slide 25. sessionを見直す
AIが同じ失敗を繰り返すときは、依頼文を少し変え続けるだけでは効率が悪いことがあります。古い指示や関係ない情報が残っている。前提が矛盾している。作業が大きすぎる。テストが不足している。そうした可能性を見ます。session reset、作業分割、context packの作り直し、人間による小さな実装への切り替えを検討します。
Slide 26. ai-work-log
AIを使った開発では、何を依頼し、何が変わり、どう検証したかを残します。prompt全文をすべて残す必要はありませんが、重要な依頼、採用した計画、変更ファイル、実行したテスト、失敗と修正、残課題は残します。AIを使ったかどうかだけでなく、どこを人間が確認したかを説明できるようにします。
Slide 27. PR説明
PRでは、AIが作ったかどうかより、何を変更し、どう確認したかが重要です。AI利用については、チームのルールに沿って必要な範囲で書きます。変更概要、AIの使い方、手で確認した点、テスト結果、レビューしてほしい箇所、残課題を簡潔に書きます。AIが作った大きな差分をそのまま投げず、レビュアーが変更を追える形にします。
Slide 28. ケース: 絞り込み機能
この章のケースは、支援ステータス一覧の絞り込み機能です。メンターが、ステータスと最終更新日で一覧を絞り込めるようにします。ここでは、受け入れ条件、API、画面、テスト、contextと評価の考え方を使います。過去章を全部思い出す必要はありません。AIに全部任せるのではなく、小さく計画し、小さく実装し、レビューして検証します。
Slide 29. Exercise 1
一つ目の演習では、feature briefを書きます。機能、利用者、目的、変更範囲、品質条件、非対象、受け入れ条件、不明点を整理します。書き始めは、今回作るのは、メンターが一覧を絞り込める機能です、で十分です。AIに依頼する前に、人間が作るものと作らないものを決めます。成果物は ai-feature-brief.md です。
Slide 30. Exercise 2
二つ目の演習では、context packを作ります。読ませたいファイル、参考にしたい既存の書き方、現在のgit状態、実行してよい確認コマンド、渡してはいけない情報を書きます。たとえば、一覧画面のファイルとAPIの実装は読む、.envは読ませない、と書きます。AI coding agentへの調査依頼案も作ります。成果物は ai-context-pack.md です。
Slide 31. Exercise 3
三つ目の演習では、Claude Code session planを書きます。plan modeで何を調査させるか、期待する出力、実装で触ってよい範囲、permission、sandbox、approval、実行するテスト、停止条件を整理します。たとえば、まず関連ファイルを読んで、変更案とテスト案だけ出してください、と書きます。成果物は claude-code-session-plan.md です。
Slide 32. Exercise 4
四つ目の演習では、AI-generated diffをレビューします。git status、変更ファイル、受け入れ条件との対応、既存の書き方、不要な抽象化、セキュリティ、アクセシビリティ、テスト、依存変更を確認します。書き始めは、この差分は受け入れ条件の一つ目を満たしている、のように対応を書けば十分です。成果物は ai-diff-review.md です。
Slide 33. Exercise 5と第20章への接続
五つ目の演習では、検証ログとPR説明を書きます。使ったAI tool、主要promptの要約、採用した計画、採用しなかった提案、変更ファイル、検証結果、実行しなかった確認、失敗と修正、残課題を ai-work-log.md に残します。さらに ai-assisted-pr-description.md を作ります。ここで残した判断理由と確認手順は、第20章でREADME、設計メモ、ADR、障害報告を書く材料になります。