第1章 作業の定義とエージェントへの指示

学習目標

• 漠然とした機能の要望を、観察できる完了の基準を持つ作業指示に書き直す。
• 大きな機能を、1つずつ実行・検証・取り消しができる小さな作業に分ける。
• 作業の不確実性と影響範囲から、先に計画を出させるか、すぐに任せるかを選ぶ。
• エージェントの計画をレビューし、不要な段階を外して範囲を調整する。
• リポジトリの指示ファイル（AGENTS.md・CLAUDE.md・GEMINI.md）に入れる内容と、別の仕組みに移す内容を区別する。

はじめに

ある金曜日の夕方、1人で事業を営む起業家が、コーディングエージェントに「会員登録をもう少しスムーズにして」と任せて夕食に出かけました。戻ると、エージェントは「作業が完了しました」という報告とともに、フォームのデザイン、パスワードのルール、パッケージ一覧まで変更していました。何が良くなり何が壊れたかを判断する基準がなく、結局すべて元に戻しました。

エージェントが無能だったからではありません。受けた指示の中で真面目に働き、「できたように見える」瞬間に止まったのです。問題は、どこを終点とし、どこまで変更してよいか、何をもって結果を証明するかが、指示に示されていなかったことです。

この章では、作業を任せる側の技術を扱います。まず完了の基準と良い作業指示の構造を学び、大きな機能を小さく分ける方法と、既存のコードの方式に従わせる方法を見ます。続いて、いつ計画を先に受け取り、どうレビューするか、毎回繰り返す言葉をリポジトリの指示ファイルにまとめる方法を学びます。「さらに深く」では、ルールが未定の機能と、人が見守らない作業を扱います。

重要な概念

作業を任せるということ

コーディングエージェントに作業をさせても、結果の責任は人に残ります。指示する人が担うことは4つです。

1. 目標を決める：何をなぜ作るか、どこが終わりかを決めます。
2. 計画をレビューする：エージェントが選んだ方法が、目標と範囲に合うかを見ます。
3. 結果を確かめる：報告ではなく証拠で判断します（第2章）。
4. 公開するか判断する：記録し（第3章）、リスクを点検し（第4章）、ユーザーに公開するかを決めます（第5章）。

Claude Codeのベストプラクティスは、この関係を一文で説明しています。エージェントは「完了したように見える」ときに止まり、自分で実行できるチェックがなければ、「そう見える」ことが唯一の手がかりになるということです。そのときは人が検証担当になり、すべてのミスを自分で見つけなければなりません。内装業者に「リビングをおしゃれに」とだけ伝えると、仕上がりが気に入らなくても指摘する根拠がないのと同じです。「壁は白、照明は暖色を2つ、既存の造り付け収納はそのまま」と伝えれば、完成時に1つずつ確認できます。

完了の基準：「終わり」を先に決める

完了の基準（definition of done）とは、作業が終わったかを誰が確認しても同じ結論になるよう、あらかじめ書いた条件です。良い完了の基準は、画面を見るかコマンドを実行して、正しいか誤りかを判定できます。「良く」「すっきり」「速く」といった形容詞は、人によって基準が違うため、完了の基準にはなりません。

完了の基準は2種類に分けて書くと、抜けが減ります。機能の基準は何が動作するか（「星4を押すと星4のレビューだけが表示される」）、品質の基準はどんな条件を守るか（「既存のテストがすべて通る」「新しいパッケージを追加しない」「狭い画面でも崩れない」）です。

Claude Codeのベストプラクティスは、完了の基準を、エージェントが自分で実行できるチェックとして与えるよう勧めています。入力例と期待する結果をいくつか示し、「実装後にテストを実行する」と書けば、エージェントが通るまで自分で直します。

良い作業指示の4つの要素

良い作業指示には、たいてい次の4つが含まれます。小さな契約書と考えるとよいでしょう。

1. 目標：何を作るか。ユーザーが何をできるようになるか。
2. 完了の基準：何が確認できれば終わりか。
3. 範囲と禁止事項：どこまで触ってよく、何には手を出してはいけないか。
4. 検証方法：どのコマンドや確認手順で完了を証明し、何を証拠として示すか。

目標：注文履歴画面に「配送中」の注文だけを表示するフィルターを追加する。
完了の基準：
- フィルターで「配送中」を選ぶと、配送中の注文だけが表示される。
- 「すべて」を選ぶと、元の一覧に戻る。
- この2つのケースを確認するテストを追加し、npm test がすべて通る。
範囲と禁止事項：
- src/pages/orders/ 内のファイルだけを変更する。
- 注文データの構造と決済のコードは変更しない。新しいパッケージはインストールしない。
検証方法：
- 実行したテストコマンドと出力全体、幅360pxの画面キャプチャを示す。

4つの要素がそろっていれば、指示は短くても構いません。逆に、形容詞を10行並べても、完了の基準と範囲がなければ結果を判断できません。

1枚の画面に収まらない状態も決める

機能を説明するとき、人はすべてがうまくいった画面を1つ思い浮かべがちです。しかし実際のアプリは、その画面に至るまでにさまざまな状態を通ります。指示にその状態がなければ、エージェントが自分で決めるか、実装を見落としてしまいます。

状態を漏れなく見つけるコツは、先にユーザーフロー（user flow）を描くことです。ユーザーがどこから入り、何を押し、どこで終わるかを順番に書き、各段階で「ここでデータがなかったら？ 遅かったら？ 失敗したら？ 途中で離脱したら？」と問います。その答えが完了の基準になります。

小さく分ける：縦に切る

任せる作業が大きいほど変更ファイルが増え、レビューが難しくなり、問題がどの変更によるものかを突き止めにくくなります。そのため、大きな機能は小さな作業に分けて任せます。このとき、分ける方向が大切です。

ケーキを思い浮かべてください。層ごとに分けると（スポンジだけ、クリームだけ、果物だけ）、一切れが完成するまで誰も味見できません。縦に切れば、一切れごとにすべての層が含まれているので、最初の一切れから味見できます。作業も同じです。

縦に切った作業は、それぞれ独立して実行し、検証し、元に戻すことができます。作業が適切な大きさかどうかは、2つの点で判断します。変更した内容を一文で説明できるか、そして、一度腰を据えてレビューを始めたら、その場で最後まで確認を終えられるかです。引っ越しの段ボールごとに中身を書いておくように、「1つの作業＝1つの目的」に分けると、確認と取り消しがしやすくなります。

Anthropicの長時間実行エージェントの実験でも、セッションごとに機能を1つだけ任せたことが決定的で、機能ごとにコミットを残し、問題時に以前の状態に戻れるようにしていました。

既存の方式を指し示して任せる

エージェントは同じ機能を作る方法を複数知っています。指示がなければその中から1つ選びますが、このリポジトリの方式と違うかもしれません。エラーの形式、入力の検証方法、コンポーネントの構造がファイルごとに異なると、アプリは次第に直しにくくなります。

解決策は、従うべき例を直接指し示すことです。Claude Codeのベストプラクティスも、既存ファイルを1つ良い例として指定し、その方式に従わせ、すでに使っている以外のライブラリは使わないよう範囲を定めることを勧めています。エージェントがリポジトリの実際のコードを基準にするため、長い説明より効果があります。

src/api/products.ts が入力を検証し、エラーを返す方式を先に読むこと。
同じ方式で src/api/coupons.ts にクーポン取得APIを作る。
すでに package.json にあるパッケージだけを使う。

先に計画を出させる

初めて見るコードに複数ファイルが関わる機能を追加するときは、すぐにコードを書かせるより、先に計画を受け取るほうが安全です。計画段階で変更するファイル、作業順序、触らない範囲を確認し、調整できるからです。計画を修正するコストは、コードを元に戻すコストよりはるかに小さく済みます。

Claude Codeのベストプラクティスは、調査、計画、実装、コミットの4段階を勧めています。調査と計画にはplan modeを使います。ファイルを読み、読み取り専用のコマンドで調べますが、ソースファイルは変更しないモードです。ステータスバーにplan modeが有効と表示されるまでShift+Tabで切り替えるか、claude --permission-mode planでセッションを開始します。受け取った計画はCtrl+Gでテキストエディターを開き、直接修正してから進められます。計画を承認するか、再びShift+Tabでモードを変えると実装段階に移ります。

ほかのツールにも似た仕組みがあります。Gemini CLIは--approval-modeにplanという値を用意しています。計画モードのないツールでも「まず計画だけを立てて、ファイルは変更しないで」と頼めますが、権限は変わらないため、ファイルの変更を実際には阻止できません。阻止する必要があるなら、計画モードや読み取り専用権限を使います。

計画をレビューする5つの問い

もっともらしい段階の一覧が、良い計画とは限りません。計画を受け取ったら、次の5つを順番に問います。

1. 要件につながるか：各段階がどの要件のためのものか、1つずつ対応づけられますか。対応する要件がない段階は、作業範囲の外にある可能性が高いです。
2. 範囲を超えていないか：変更を禁止したファイルや、関係のない整理作業（「ついでに共通コンポーネントも整理する」）が紛れ込んでいませんか。
3. 元に戻しにくい作業がないか：既存のデータを一括で修正したり、データベースの構造を変更したり、外部にメールを送ったりする段階はありますか。ある場合は、その段階だけを切り離して確認します。
4. 検証の段階があるか：計画の最後に、どのチェックを使って何を確認するのかが書かれていますか。
5. 大きさは適切か：小さな要望に対して、計画が大きすぎませんか。新しいライブラリの導入やフォルダ構造の変更など、要望には含まれていなかった大きな決定が隠れていませんか。

レビューの結果は具体的に返します。「第3段階は外してください。既存の会員データは変更しません」「第5段階の前にテストを書く段階を加えてください」のように、段階の番号と理由を一緒に伝えると、エージェントは正確に修正できます。

リポジトリの指示ファイル：ツールごとの読み方

リポジトリ（repository）とは、プロジェクトのファイルと変更履歴を収めるフォルダです。リポジトリの指示ファイルは、セッション開始時にエージェントが先に読む案内メモで、チームが同じことを繰り返し伝えずに済みます。新人に渡す業務案内のようなものです。

複数のツールを併用するチームは、内容を1つのファイルで管理したいと考えます。Claude Codeのドキュメントは、CLAUDE.mdとAGENTS.mdが両方ある場合、通常はCLAUDE.mdだけを読むと説明し、1つのファイルを共有するなら、CLAUDE.mdの先頭に@AGENTS.mdと書いて取り込むよう案内しています。個人設定で両方読む値（claude-md-and-agents-md）を選ぶこともできます。@パスはClaude Codeの取り込み構文で、Gemini CLIもGEMINI.mdで@ファイルの取り込みに対応しています。Codexでは~/.codex/config.tomlのproject_doc_fallback_filenamesで、別名の指示ファイルを認識させられます。

@AGENTS.md

## Claude Code専用
- src/billing/ 以下を変更するときは、plan modeで先に計画を示す。

実際に読まれたかも確認できます。Claude Codeでは/contextで読み込んだファイルを確認し、Gemini CLIでは/memory showで連結された内容を表示します。Codexのドキュメントは、エージェントに指示を要約させ、読み込んだ順番を確認する方法を紹介しています。

指示ファイルに何を入れるか

基準は1つです。コードを読むだけではわからず、知らないとミスにつながることだけを入れます。Claude Codeのベストプラクティスは、各行について「この行を削るとエージェントがミスするか」と問い、そうでなければ削るよう勧めています。長くなると、肝心のルールが埋もれて無視されるからです。

分量も管理します。Claude Codeのドキュメントは、CLAUDE.mdを1ファイル200行未満に保つよう勧めています。それを超える内容は、性質に応じて別の場所に移します。

@パスでの取り込みは長いファイルの整理には役立ちますが、取り込んだファイルもセッション開始時に読み込むため、分量は減りません。初めて指示ファイルを作るときは、Claude Codeの/init（コードベースを分析して下書きを作り、既存の場合は改善点を提案）のような生成コマンドから始め、コードからわからない内容を人が補います。

さらに深く

ルールが未定の機能：インタビューと仕様書

完了の基準を書こうにも書けない場合があります。予約に空きが出た際、キャンセル待ちの人に何分間の優先権を与えるか、返事がなければ次の人に回すか、といった業務ルールが未定の場合です。すぐに実装を任せると、エージェントは空白をもっともらしい推測で埋め、その推測がコード全体に広がります。

Claude Codeのベストプラクティスは、大きな機能ほど先に人へのインタビューをさせるよう勧めています。短い説明だけを渡し、AskUserQuestionツールで詳しく質問させます。ただし、ありきたりな質問は除き、実装方式、画面、境界事例、心配事、選択肢の長所と短所など、人が考えつかなかった難しい部分を掘り下げさせます。終わったら、結果をSPEC.mdのような仕様ファイルに書かせます。

良い仕様書は、それだけで完結しています。関連ファイルやインターフェースを名前で示し、やらないことを明記し、機能全体の動作を証明する最初から最後までの確認手順で締めます。仕様書が完成したら、新しいセッションで実装を始めます。インタビューの長い会話が残っていない、まっさらなコンテキストで、仕様ファイルだけを基準に働かせるためです。ドキュメントも、仕様書を練る時間は実装を見守る時間より価値があると述べています。

インタビューは、人の盲点を明らかにすることにも役立ちます。「キャンセル待ちの2人がほぼ同時に承諾したら？」「優先権の時間内にレッスンが中止されたら？」といった問いで、運営者自身の見落としを発見できます。ただし、ルールを決めるのは引き続き人の役目です。

コンテキストという予算

エージェントが1つの会話で参照するすべての内容（メッセージ、読んだファイル、コマンドの出力）をコンテキスト（context）と呼びます。容量には限りがあります。Claude Codeのドキュメントは、コンテキストが埋まるほど以前の指示を忘れたり、ミスが増えたりするとして、最も重要な管理資源と位置づけています。

そのため指示ファイルは短く保ち（毎セッション読み込むため）、無関係な作業の間では/clearでコンテキストを空にします。作業中に関係のない質問をしてから戻る「何でも詰め込んだセッション」が、最もよくある無駄です。何十ものファイルを調べる調査はサブエージェント（subagent）に任せます。別のコンテキストでファイルを読み、要約だけを返すので、実装中の会話のコンテキストを保てます。

人が見守らない作業

一晩任せる、何百ものファイルに同じ変更を一括適用する、クラウドで動くエージェントに任せるといった作業には、途中で質問に答える人がいません。こうした作業ほど、指示を完結させる必要があります。

一括作業は順番が大切です。Claude Codeのベストプラクティスは、次の方法を紹介しています。まず変更対象の一覧をファイルに出し、対象ごとに非対話実行（claude -p "指示"）を呼ぶスクリプトを作ります。全件実行前に2〜3件で試し、そこで見つかった問題に合わせて指示を直します。必要なツールは--allowedToolsであらかじめ許可し、--permission-mode dontAskで、本来承認を求める呼び出しは質問せず拒否させます（作業フォルダ内のファイル読み取りなど、承認不要の作業はそのまま実行されます）。--max-turnsで反復回数に上限を設ければ、1件で迷い続ける実行も止まります。小さな試行で先にミスを取り除かないと、同じミスが対象全体に広がります。

クラウドエージェントも同じです。Codexのクラウド環境設定には、依存関係のインストールスクリプト、環境変数とシークレット、インターネットアクセスの可否やドメイン範囲の項目があります。テストに必要なものは先に準備し、アクセスは必要な分だけ許可します。

実務の場面

路地裏書店：11個のファイルを元に戻してから

町の書店「路地裏書店」の店主ユンさんは、読者レビューの掲示板に星評価のフィルターを付けたいと考えました。最初に「レビューページを少し改善して」と頼むと、エージェントはデザイン、並び順、投稿フォームまで11個のファイルを変更しました。何が正しくなったか判断できず、ユンさんはすべて元に戻しました。

2回目は、4つの要素をそろえて書き直しました。

1. 目標：レビュー一覧の上に星評価（1〜5）のフィルターボタンを置く。
2. 完了の基準：星4を押すと星4のレビューだけが表示され、「すべて」を押すと全件が表示される。該当する評価のレビューがなければ、「この評価のレビューはまだありません」が表示される。3つのケースを確認するテストを追加し、npm testが通れば終わり。
3. 範囲と禁止事項：レビュー一覧の画面だけを変える。投稿フォームとデータベース構造は変えない。
4. 検証：テストの出力とブラウザの画面キャプチャを示す。

ユンさんは最初、空の状態を忘れていましたが、ユーザーフローを描いて追加しました。星2を押すお客さまもいるはずで、星2のレビューが1件もなければ、空白の画面になってしまうからです。

変更するファイルが複数になりそうだったため、plan modeで先に計画を受け取りました。計画には「レビューテーブルに星評価のインデックスを追加する」という段階がありました。ユンさんは5つの問いを使って計画を確認しました。この段階はどの要件とも対応づけられず（問い1）、データベースに手を入れるため禁止した範囲に該当し（問い2）、レビューは200件ほどしかないので画面側で絞り込めば十分でした（問い5）。ユンさんはその段階を外し、画面側で絞り込ませました。

エージェントはテストの出力と画面キャプチャを示し、ユンさんはブラウザで実際に押してから受け入れました。2回の違いはエージェントの能力ではなく、指示の構造でした。完了の基準が止まる地点を示し、範囲が計画の不要な段階を取り除いたのです。

波音サーフスクール：大きな機能を縦に切る

レッスン予約アプリを運営する「波音サーフスクール」の代表トさんは、「波が危険な日にレッスンを中止したら、予約者に知らせて返金まで処理する機能」を作りたいと考えました。機能は管理画面、予約データ、SMS送信、決済の返金にまたがっていました。

トさんが最初に思いついた方法は3つでした。

• 一度に任せる：一度の指示で終わりそうです。しかし変更ファイルは20個を超え、返金に誤りが出ても、どの変更が原因かを調べにくいため、退けました。
• 層ごとに分ける：データ構造、サーバー、画面の順に任せる方法です。3つとも終わるまで実際に動くものがなく、途中確認ができないため、退けました。
• 縦に切る：ユーザーが使える成果の単位に分ける方法です。これを選びました。

トさんは、まずルールが未定だと気づきました。レッスン2時間前の中止は全額返金か、振り替えのレッスンを選べるかを決めていませんでした。そこで先にエージェントにインタビューを任せ、「すでに振り替えを選んだ人にもSMSを送るか」などの問いに答え、ルールを決めてSPEC.mdに残しました。

そして3つの作業に分けました。

1. 管理者がレッスンを「天候による中止」にすると、予約者一覧画面に中止表示が出る。SMSと返金はまだ行わない。
2. 天候による中止になったら、予約者に案内SMSを1回だけ送る。テストでは実際に送らず、送信記録だけを残す。
3. 予約者が案内リンクから「返金」を選ぶと、決済の取り消しを要求し、予約状態が「返金完了」に変わる。

トさんは、作業ごとに新しいセッションを開き、SPEC.mdを基準に任せました。決済のコードに触る3つ目の作業だけは、plan modeで計画を受け取りました。計画に「決済モジュールの共通エラー処理を整理する」という段階が紛れ込んでいるのを見て、範囲外だとして外しました。最初の作業が終わった日から、管理者は実際に中止の表示を使うことができました。3つ目の作業で返金額の計算ミスが見つかったときも、その直前の作業まではすでに検証済みだったため、原因を探す範囲を3つ目の作業での変更だけに絞ることができました。

間違えやすいポイント

1. 「長く詳しく書くほど良い指示だ。」 長さが正確さを生むと感じがちです。しかし、形容詞を10行並べても、確認する条件がなければ結果を判断できません。短くても、完了の基準、範囲、検証方法が明確な指示のほうが優れています。
2. 「指示ファイルに書いておけば、エージェントは必ず守る。」 ファイルに書かれたルールは、守られるルールに見えます。しかし、指示はエージェントが判断するときに参考にする資料にすぎないため、内容が長かったり、前後で矛盾していたりすると、読み落とす行が出てきます。必ず阻止しなければならない行動は、権限ルールやフックなど、強制する仕組みに任せます。
3. 「慎重に進めるには、すべての作業で先に計画が必要だ。」 慎重さは美徳ですが、計画が効果を発揮するのは不確実で大きな作業です。一文で説明できる修正まで計画を受け取ると、時間がかかるだけです。
4. 「一度に多く任せれば、やり取りが減って効率的だ。」 指示を出す回数だけを見れば、そのとおりです。しかし、やり取りが減る効果よりも、増えるレビュー時間と元に戻すコストのほうが大きくなります。問題が起きると、大きな作業のまとまり全体を捨てなければならない場合もあります。
5. 「機能を分けるときは、データ、サーバー、画面の順に分けるのが定石だ。」 技術的な構造に沿って分けると、整って見えます。しかし、最後の層の作業が終わるまで動作を確認できません。ユーザーができることを単位に、縦に切ります。
6. 「エージェントが計画を立てたので、その計画は信頼してよい。」 もっともらしい段階の一覧には説得力があります。しかし、計画には要望に含まれていない整理作業や、元に戻しにくいデータの変更が混ざっていたり、検証の段階が抜けていたりする可能性があります。5つの問いでレビューしてから承認します。

ひと目でわかるまとめ

公式ドキュメントで確認する

• Claude Code: Best practices — 検証する手段を与えること、調査→計画→実装→コミット、計画を省く場合、インタビューと仕様書、一括実行
• Claude Code: How Claude remembers your project — CLAUDE.mdの配置場所と読み込む順序、@による取り込み、.claude/rules/、AGENTS.mdの扱い
• Claude Code: Skills — スキルファイルの場所とdisable-model-invocation
• Codex: Custom instructions with AGENTS.md — AGENTS.mdを探索する順序、ファイルのサイズの上限、代わりに使うファイル名
• Gemini CLI: GEMINI.md — 指示ファイルの階層、@取り込み、/memory、context.fileName
• Anthropic: Effective harnesses for long-running agents — 機能を1つずつ任せ、進捗を記録する

セルフチェック

1-1. 2つの要望があります。（ア）「通知設定画面を使いやすく整えて」（イ）「通知をオフにすると翌朝の要約メールが届かず、設定画面を再読み込みしてもオフが維持される」。完了の基準があるのはどちらですか。もう一方をどう書き直すか説明してください。

1-2. お客さまの過去の予約履歴を示す一覧画面を任せます。すべてがうまくいった画面以外に、指示に含める状態を4つ挙げ、それぞれの完了の基準を一行ずつ書いてください。

1-3. 工房体験の予約アプリに「団体予約の問い合わせ」機能を追加します。問い合わせフォーム、管理者の確認画面、受付案内メールが必要です。縦に切った3つの作業に分け、それぞれ完了の基準を1つ付けてください。

1-4. Claude Codeのplan modeで受け取った計画のうち、1つの段階の表現だけを直接直してから進めたい場合、どのキーを使いますか。またplan modeを使わずにすぐ任せてよい作業の例を1つ挙げてください。

1-5. 商品詳細画面に「再入荷通知を申し込む」ボタンを追加する計画を受け取りました。①申し込みボタンと完了メッセージの追加 ②申し込み履歴を保存するAPIの追加 ③アプリ全体のボタンコンポーネントの色と余白の整理 ④完了報告、の4段階です。5つの問いで見ると何が問題で、どう直すよう返すか説明してください。

1-6. リポジトリにはチームのAGENTS.mdだけがあり、Claude Codeは正しく読んでいました。あるメンバーが個人メモを含むCLAUDE.local.mdをルートに作ると、その人のセッションだけでチームのルールが守られなくなりました。理由と解決方法を説明してください。

1-7. チームが指示をTEAM_GUIDE.mdの1ファイルで管理することにしました。CodexとGemini CLIにこのファイルを指示として読ませるには、それぞれどの設定を変えるか説明してください。

実習課題