第19章 AIコーディングの実務ワークフロー

AIにコードを書かせること自体は目的ではない。何を作るかを仕様化し、読ませる情報を選び、計画を確認し、小さく実装し、diffを読み、テストし、PRで説明する一連の工程として扱うことが、AIコーディングを安全に使う前提になる。

AIコーディング

読み：エーアイコーディング（AI coding／agentic coding、AI支援開発）
一言で言うと：AIを使ってコードの調査、計画、実装、検証を進める開発のやり方。
くわしく：AIコーディングは、AIにコードを速く書かせる道具としてだけ捉えると失敗しやすい。何を作るかが曖昧なら、AIは曖昧な実装を速く作る。読ませる情報が足りなければ既存設計とずれ、触ってよい範囲を決めなければ関係ない変更が混ざる。だから実務では、仕様化、context設計、workspace確認、計画確認、小さな実装、diffレビュー、テスト、記録、PRという管理された工程として扱う。この流れの中心にいるのはAIではなく開発者で、仕様の最終判断、secretの扱い、テスト結果の解釈、PRを出す責任は人間が持つ。
具体例：支援ステータス一覧の絞り込み機能で、AIに調査と実装を手伝わせつつ、受け入れ条件の判断や採否は開発者が行う。
つまずきやすい点：速くコードを書かせる作業だと考えると、仕様化、計画、レビュー、検証が抜けて、曖昧な実装を速く量産してしまう。
関連語：AI coding agent（第19章）、Claude Code（第19章）、small diff（第19章）、diff review（第19章）
テキスト本文での登場箇所：第19章「AIコーディングは、速く書く道具ではなく作業工程である」

AI coding agent

読み：エーアイコーディングエージェント（AI coding agent）
一言で言うと：codebaseを読み、file編集やcommand実行まで行えるAI支援ツール。
くわしく：AI coding agentは、チャットで相談に答えるだけでなく、実際の開発環境へ作用する。関連fileを探す、既存パターンを要約する、小さな実装を作る、テストを走らせる、エラーの修正案を出す、PR説明の下書きを作る、といった作業を支援できる。便利な一方で、間違ったfile編集、不要な依存追加、強すぎるcommand実行、secretや個人情報の読み取りにつながることがある。tool名より、読める範囲、書ける範囲、実行できるcommand、network access、approvalを確認することが重要である。
具体例：Claude CodeやCodexに、支援ステータス一覧の絞り込み機能の関連file調査、実装計画、初期実装、test failureの原因候補整理を手伝わせる。
つまずきやすい点：普通のチャットと同じ感覚で使うと、file編集やcommand実行といった現実への作用を軽く見てしまう。
関連語：AIコーディング（第19章）、permission（第19章）、sandbox（第19章）、approval（第19章）
テキスト本文での登場箇所：第19章「AI coding agentは、チャットではなく作業環境である」

Claude Code

読み：クロードコード（Claude Code）
一言で言うと：codebaseを読み、fileを編集し、commandを実行し、開発toolと連携できるagentic coding tool。
くわしく：Claude Codeは単なるチャットではなく、実際の開発環境へ作用する作業相手である。terminal、IDE、desktop app、browserなどで使え、関連ファイルを探す、既存パターンを要約する、小さな実装を作る、テストを走らせる、エラーの修正案を出す、PR説明の下書きを作る、といったことができる。便利さが増えるほど影響範囲も広がり、間違ったfileを編集したり、許可していないcommandを実行しようとしたりすることもある。だから、promptだけでなくpermission、settings、CLAUDE.md、計画確認、diffレビューを合わせて設計する。
具体例：支援ステータス一覧の絞り込み機能で、Claude Codeに関連file調査、実装計画、初期実装、test failureの原因候補整理を手伝わせる。
つまずきやすい点：チャット相手と同じ感覚で使うと、fileの編集やcommand実行といった現実への作用を軽く見てしまう。
関連語：AI coding agent（第19章）、AIコーディング（第19章）、permission（第19章）、CLAUDE.md（第19章）
テキスト本文での登場箇所：第19章「AI coding agentは、チャットではなく作業環境である」

Codex

読み：コーデックス（Codex）
一言で言うと：OpenAIが提供する、コード調査、編集、実行、レビューを支援するAI coding agent。
くわしく：Codexは、ローカルCLIやIDEでコードを読み、変更し、コマンドを実行できる。cloud tasksでは、ローカルPCではなく隔離された環境で背景タスクとして作業できる。ローカルで使う場合とcloudで使う場合では、読めるfile、secretの扱い、network access、approvalの置き方が異なる。Claude Codeと同じく、toolの出力をそのまま採用せず、brief、context、permission、sandbox、diff review、test、PR説明で管理する。
具体例：Codex CLIで、支援ステータス一覧の絞り込みに関係するfileを調査させ、read-onlyやapproval付きで計画を確認してから小さな差分を実装する。
つまずきやすい点：ローカルとcloudで実行環境やsecretの扱いが違うことを意識せず、同じ感覚で権限を広げてしまう。
関連語：AI coding agent（第19章）、permission（第19章）、sandbox（第19章）、approval（第19章）
テキスト本文での登場箇所：第19章「AI coding agentは、チャットではなく作業環境である」

plan mode

読み：プランモード（plan mode、計画モード）
一言で言うと：いきなり編集させず、調査と変更方針を先に出させて確認する進め方。
くわしく：plan modeは、変更がdiskへ触れる前に、AIの理解と変更方針を人間がreviewするための段階である。Claude Codeのcommon workflowsでも、編集前に計画を作りreviewする流れが扱われている。Codexなどでも、read-onlyや承認つきの状態で調査させ、編集前に人間が確認する流れを作れる。まず編集せずに、関連ファイル、既存の書き方、変更対象、テスト方針、リスク、確認すべき質問を出させる。人間は、目的と合っているか、変更範囲が広すぎないか、非対象に踏み込んでいないか、不明点を勝手に決めていないか、既存の未commit変更を壊さないかを見る。
具体例：支援ステータス一覧の絞り込みで、まず「編集せずに調査だけして、実装計画を出して」と依頼し、計画を確認してから実装に進む。
つまずきやすい点：早く動くものを見たくて計画確認を飛ばすと、目的とずれた大きな変更を後から戻すことになる。
関連語：AI coding agent（第19章）、Claude Code（第19章）、AIコーディング（第19章）、diff review（第19章）
テキスト本文での登場箇所：第19章「plan modeで、編集前に理解と方針を見る」

permission

読み：パーミッション（permission、権限）
一言で言うと：AIが何を実行できるかを、操作ごとに許可・確認・拒否で管理する仕組み。
くわしく：permissionは、AIへの信頼度を表すものではなく、作業の影響範囲に応じて安全な摩擦を置く仕組みである。Claude Codeでは、tool permissionをallow（許可）、ask（確認してから実行）、deny（実行しない）のように扱える。初心者の方針は単純でよく、読み取りは必要な範囲で許可、対象fileの編集は確認を挟む、testやlintは許可または確認つき、.env読み取り・secret参照・network access・git push・deploy・本番データ変更は拒否または確認にする。毎回すべてを確認すると遅いが、強い操作を無条件で許すと危険なので、読む、書く、実行する、外へ出す、消す、戻せない変更を分ける。
具体例：支援ステータス一覧の絞り込みで、関連ソースの読み取りはallow、対象fileの編集はask、.env読み取りやgit pushはdenyに設定する。
つまずきやすい点：権限を強くしすぎると毎回確認で遅くなり、緩すぎると影響の大きい操作を止め損ねる。読む・書く・実行する・外へ出すを分ける必要がある。sandboxとapprovalを同じものだと考えない。
関連語：settings（第19章）、sandbox（第19章）、approval（第19章）、AI coding agent（第19章）
テキスト本文での登場箇所：第19章「permissions、sandbox、approvalで、読む、書く、実行するを分ける」

sandbox

読み：サンドボックス（sandbox）
一言で言うと：AIやAIが実行するcommandが触れられるfile、network、system resourceを制限する境界。
くわしく：sandboxは、AIがどこまで実際に作用できるかを技術的に制限する。たとえば、workspace内だけ書ける、network accessを禁止する、特定directoryを読み取れないようにする、といった使い方がある。approvalが「人間に確認する止め方」なのに対し、sandboxは「そもそも触れられる範囲」を決める境界である。AIが起動したtest commandやscriptにも影響することがあるため、agent本体だけでなく実行されるcommandの範囲として考える。
具体例：支援ステータス一覧の絞り込みで、workspace内の対象fileだけ編集できるようにし、network accessや本番データへの接続は使わない。
つまずきやすい点：approvalがあれば安全、またはsandboxがあれば確認不要、と考える。実務では両方を組み合わせる。
関連語：permission（第19章）、approval（第19章）、AI coding agent（第19章）
テキスト本文での登場箇所：第19章「permissions、sandbox、approvalで、読む、書く、実行するを分ける」

approval

読み：アプルーバル（approval、承認）
一言で言うと：AIが強い操作を行う前に、人間が許可するか判断する確認点。
くわしく：approvalは、file編集、test実行、package install、network access、git操作、deployなど、影響のある操作の前に人間へ確認を挟む仕組みである。sandboxが技術的な範囲を決めるのに対し、approvalは人間の判断を挟む。すべてを承認必須にすると遅くなるが、強い操作を自動許可すると危険である。小さな読み取りや安全なtestは許可し、package追加、lockfile変更、git push、deploy、本番データ変更は確認または拒否にする。
具体例：支援ステータス一覧の絞り込みで、対象file編集はask、test実行はallow/ask、package installやgit pushはaskまたはdenyにする。
つまずきやすい点：承認を押すことが内容レビューの代わりになると思ってしまう。承認後もdiff、test、manual checkを確認する。
関連語：permission（第19章）、sandbox（第19章）、diff review（第19章）
テキスト本文での登場箇所：第19章「permissions、sandbox、approvalで、読む、書く、実行するを分ける」

settings

読み：セッティングス（settings、設定）
一言で言うと：Claude Codeの権限やhook、MCP serverなどをscopeごとに管理する設定。
くわしく：settingsでは、権限、hook、MCP serverなどの設定をscope（適用範囲）ごとに管理する。公式ドキュメントでは、managed、user、project、localといったscopeが説明されている。新人がまず押さえるのはprojectとlocalの違いである。project settingsはチームで共有したい設定（許可するtest command、禁止する危険操作、共通hook、MCP serverなど）に向き、レビュー対象にする。local settingsは自分のPCだけの設定（terminal環境、machine-specificなpathなど）に向く。secretや個人のtokenをproject settingsへ書いてはいけない。shared settingsへ強い許可を入れるとチーム全員のAI作業に影響する。設定を入れても人間のレビューが不要になるわけではなく、設定・prompt・diffレビュー・testを重ねる。
具体例：支援ステータス一覧の絞り込みで、チーム共通の許可コマンドはproject settingsに、自分の環境固有の設定はlocal settingsに置く。
つまずきやすい点：localに置くべき情報を共有設定へ混ぜると、他の人の環境で壊れるだけでなく、秘密情報の漏えいにもつながる。
関連語：permission（第19章）、sandbox（第19章）、CLAUDE.md（第19章）、MCP（第19章）
テキスト本文での登場箇所：第19章「settingsは、個人設定とチーム設定を分ける」

CLAUDE.md

読み：クロードエムディー（CLAUDE.md、Claude Codeのmemory file）
一言で言うと：Claude Codeに毎回伝えたいプロジェクトの前提を書いておくfile。
くわしく：CLAUDE.mdは、開発コマンド、テストコマンド、設計方針、命名規則、禁止事項、レビュー観点など、毎回promptへ貼る代わりにプロジェクトの共通前提として置くfileである。ただし魔法のsystem promptではなく、単独で安全を強制する境界でもない。公式ドキュメントでも、読み込まれているか、指示が具体的か、矛盾した指示がないかを確認する必要があるとされる。長すぎる、古い、矛盾している、抽象的すぎるCLAUDE.mdは品質を下げる。プロジェクトが変われば更新する保守対象で、古いコマンドや古い設計方針が残っているとAIは古い前提で作業してしまう。AGENTS.mdなど他のAI向けinstruction fileも同じく、secretの置き場にはしない。
具体例：支援ステータス一覧の絞り込みで、CLAUDE.mdに「既存UI componentを優先」「DB schema変更は事前相談」「.envを読まない」などを書いておく。
つまずきやすい点：一度書いて放置すると、古い指示や矛盾がそのまま残り、AIの品質を下げる。強制設定だと思い込み、permissionやsandboxの設定を省くのも危険である。
関連語：AI coding agent（第19章）、Claude Code（第19章）、settings（第19章）、permission（第19章）
テキスト本文での登場箇所：第19章「CLAUDE.mdは、プロジェクトの前提をAIへ渡す入口である」

hook

読み：フック（hook）
一言で言うと：Claude Codeのlifecycleの特定時点で処理を自動で動かす仕組み。
くわしく：hookは、編集後にformatを走らせる、危険なcommandをblockする、Claudeが入力を必要としているときに通知する、といったように、決まったタイミングで処理を動かす仕組みである。便利だが、初心者が最初から高度なhookを作る必要はない。hook自体もcommandやscriptとして実行されるため、何を読み、何を実行し、失敗したときにどう止まるかをレビューする。まず手順を文書にし、同じreview checklistやtest commandを繰り返し使うようになってから自動化を考える。自動化は良い手順を速くするが、悪い手順を自動化すると悪い結果が速く広がる。
具体例：支援ステータス一覧の絞り込みで、fileを編集するたびに自動でlintやformatを走らせるhookを、手順が固まってから導入する。
つまずきやすい点：最初から作り込みすぎると、固まっていない手順を自動化してしまい、悪い結果が速く広がる。
関連語：skill（第19章）、settings（第19章）、permission（第19章）、Claude Code（第19章）
テキスト本文での登場箇所：第19章「hooksとskillsは、手順が固まってから使う」

skill

読み：スキル（skill）
一言で言うと：繰り返し使う手順や専門的な作業指示を、再利用できる形にまとめる仕組み。
くわしく：skillは、同じPR説明テンプレートや決まったレビュー手順のような、繰り返し使う作業指示を再利用する仕組みである。hookと同じく、初心者が最初から作り込む必要はない。まず手順を文書にして繰り返し使い、固まってからskill化を考えるとよい。skillは便利だが、悪い手順をそのままskillにすると悪い結果が再利用されてしまう。目的、影響範囲、失敗時の止め方を説明できる段階で使う。
具体例：支援ステータス一覧の絞り込みで、毎回使うdiff reviewの観点やPR説明テンプレートが固まってから、それをskillとして再利用する。
つまずきやすい点：固まっていない手順をskillにすると、まだ良いと確認できていないやり方を繰り返してしまう。
関連語：hook（第19章）、Claude Code（第19章）、AIコーディング（第19章）
テキスト本文での登場箇所：第19章「hooksとskillsは、手順が固まってから使う」

MCP

読み：エムシーピー（Model Context Protocol）
一言で言うと：AIツールと外部のデータやツールを接続するための共通プロトコル。
くわしく：MCPは、Claude Codeのようなツールが外部のデータソースやツール（MCP server）と連携するための仕組みである。本章では、settingsで管理する設定項目の一つとして登場する。MCP serverはチームで共有したい設定に含まれることがあり、その場合はproject settingsに置いてレビュー対象にする。MCPを使うと連携先が増えるぶん、何を読ませ何を実行させるかをpermissionや設定で管理する必要がある点は、他のtool連携と同じである。
具体例：支援ステータス一覧の絞り込みで、外部のツール連携をMCP serverとして設定する場合、その設定をproject settingsで共有しレビューする。
つまずきやすい点：連携先を増やすほど、読ませてよい情報と実行してよい操作の境界をpermissionや設定で決め直す必要がある。
関連語：settings（第19章）、tool use（第18章）、permission（第19章）
テキスト本文での登場箇所：第19章「settingsは、個人設定とチーム設定を分ける」

small diff

読み：スモールディフ（small diff、小さな差分）
一言で言うと：一度の変更を小さな範囲にとどめた差分。
くわしく：small diffは、AIに大きな機能を丸ごと任せて差分を大きくするのではなく、API・UI・テストなどの単位に分けて小さく実装する考え方である。小さい差分は、戻しやすく、レビューしやすく、AIの失敗にも気づきやすい。AIが強くても、レビューできない大きさの差分は実務では危険である。実装範囲を小さくし、API側が確認できたら次にUIをつなぎ、手動確認をし、最後にPR説明を書く、という順で進める。
具体例：支援ステータス一覧の絞り込みで、まずAPIのquery処理とテストだけを実装させ、確認できてからUIをつなぐ。
つまずきやすい点：一度に画面・API・テスト・文書を大きく変えると、どこで問題が入ったか分からなくなる。
関連語：diff review（第19章）、AIコーディング（第19章）、acceptance criteria（第19章）
テキスト本文での登場箇所：第19章「作業は調査、計画、実装、検証へ分ける」「実装依頼では、範囲と検証をセットにする」

diff review

読み：ディフレビュー（diff review、差分レビュー）
一言で言うと：変更差分を人間が読んで、採用してよいか確認する作業。
くわしく：diff reviewは、AIが作ったdiffも人間が作ったdiffと同じように読む作業である。AIの説明だけで判断せず、git status、diff、test result、manual checkを確認する。観点には、仕様（受け入れ条件を満たすか）、範囲（unrelatedな変更が混ざっていないか）、既存パターン、設計（不要な抽象化がないか）、エラー処理、認可、セキュリティ、アクセシビリティ、テスト、依存追加やlockfile変更を含める。AIが作った差分だから特別に厳しくする必要はないが、説明を信じて差分を読まないのは危険である。自分のPRとして出せる状態かを確認するために行う。
具体例：支援ステータス一覧の絞り込みで、AIが追加した検索boxやsortなど、briefにない「便利な追加」を非対象として戻す判断をする。
つまずきやすい点：AIの説明が自然だと、diffを読まずに採用してしまいやすい。説明ではなくコード・テスト・手動確認を見る。git statusを見ないと、AIの報告に出ていないfile変更を見落とす。
関連語：small diff（第19章）、manual check（第19章）、acceptance criteria（第19章）
テキスト本文での登場箇所：第19章「AI-generated diffは、人間のコードと同じようにレビューする」

manual check

読み：マニュアルチェック（manual check、手動確認）
一言で言うと：自動テストとは別に、人間が実際に動かして確かめる確認。
くわしく：manual checkは、自動テスト（unit、integration、E2E）やlint、type checkだけでなく、画面を変えるときに人間が実際に操作して確かめる確認である。AIが完了したと言っても、確認なしでは完了にしない。とくにアクセシビリティ（labelの有無、キーボード操作、結果なしやエラーの状態表示）は、手動確認でないと分かりにくい。diff reviewでも、diffとtest resultに加えてmanual checkを確認する。AIの完了報告だけで終わらせず、テストと手動確認で完了を判断する。
具体例：支援ステータス一覧の絞り込みで、絞り込み中・結果なし・エラーの状態がブラウザ上で正しく伝わるかを手動で確認する。
つまずきやすい点：自動テストが通ったことだけで安心しがちだが、画面の状態表示や操作性は手動でしか気づけないことがある。
関連語：diff review（第19章）、acceptance criteria（第19章）、AIコーディング（第19章）
テキスト本文での登場箇所：第19章「AI-generated diffは、人間のコードと同じようにレビューする」「テストで閉じる」

feature brief

読み：フィーチャーブリーフ（feature brief、機能概要）
一言で言うと：AIへ依頼する前に、作るものと作らないものを決めておく短い作業定義。
くわしく：feature briefは、機能の短い作業定義で、利用者、目的、変更範囲、品質条件、非対象、受け入れ条件、不明点を書く。AIのためだけでなく、自分とチームが今回何を作るのかを揃えるための文書である。briefがないままAIに依頼すると、AIは暗黙の前提を補い、悪意はなくても判断がずれる(「便利そうだからDB schemaを変える」など)。品質条件には、認可、入力検証、アクセシビリティ、依存追加の扱いなどを入れる。briefは、AIの自由度を下げるためではなく、今回の目的に集中させるためにある。
具体例：支援ステータス一覧の絞り込みで、利用者をメンター、非対象をDB schema変更・通知・CSV export・本番デプロイと先に決めておく。
つまずきやすい点：briefを書かずに依頼すると、AIが暗黙の前提で範囲を広げ、目的とずれた実装になりやすい。
関連語：acceptance criteria（第19章）、AIコーディング（第19章）、small diff（第19章）
テキスト本文での登場箇所：第19章「feature briefで、作るものと作らないものを決める」

acceptance criteria

→第9章