大きなタスクは、もっともらしい依頼から始まりがちです。"ロケール一覧を作って。一覧と検索、国別フィルター、それに見栄えも整えて。"1時間後、目の前にあるのは中途半端な一覧ページ。検索は一部の項目にしか効かず、見た目はすでに二度変わっています。会話も膨らみ、確認済みの成果と、口にしただけの約束の区別がつかなくなってきました。

考えられる原因のひとつは、タスクを成果の分かる単位に分けていなかったことです。それでコードの誤りがなくなるわけではありませんが、今何が動くべきかが明確なら確認しやすくなります。大きな作業を検証できる段階に分ける方法、今の段階に必要な情報をエージェントに渡す方法、そして翌日、同じ会話でも新しい会話でも、記憶を頼りに一から組み立て直さず作業を再開するために何を記録するかを見ていきましょう。

ロケール一覧のインターフェース例検索欄と4行を備えたダークテーマの表。ロケールコード、言語、国、通貨、ドメインを表示します。List of locale codesSearch by code or languageLOCALE CODELANGUAGECOUNTRYCURRENCYTLDen-USEnglishUnited StatesUSD.usde-DEGermanGermanyEUR.defr-CAFrenchCanadaCAD.caja-JPJapaneseJapanJPY.jp

一覧はこのようになります。検索できる一覧に、ロケールコード、言語、国、通貨、ドメインが並びます。この見た目を覚えておいてください。実践では単なる画像ではなく、スタイルの見本として役立ちます。

大きなタスクと長い会話

大きなタスクは、コードに誤りが出る前に行き詰まることがあります。作業の形が崩れていくのです。コンテキストが膨らみ、仮説と決定事項が混ざり、検索にいつの間にか見た目の作り直しまで加わります。コンテキストウィンドウには上限がありますが、いちばん困るのは、今何をしていて何が終わったのか分からなくなることです。

TASK_SPECにはタスク全体の目的、範囲、確認方法を記します。その仕様に沿って、作業を検証可能なマイルストーンに分けます。各段階には成果と範囲があります。たとえば、データと見た目を保ったまま検索を追加する、といった具合です。これならClaudeは要点に沿って作業でき、あなたもタスクの進捗を把握できます。

タスクがまだ曖昧なら、最初の段階を調査にしてもかまいません。重要なファイルを2、3個読み、解決案とリスクを挙げてから、タスクの説明と次の段階を具体化します。

各段階の最後に確認を行い、短いサマリー（summary）を残しましょう。何を行い、何で確認し、次に何をするかを書きます。Gitで管理しているプロジェクトなら、確認済みの変更を小さなコミットとして保存します。サマリーは決定事項を、コミットはコードのバージョンを残します。両方あれば成果を確認し、休止後に作業を再開しやすくなります。

段階の定義

Milestone（マイルストーン）は、タスクの途中成果を確認できる節目です。その節目までの作業を、ここでは段階と呼びます。

段階には、次の3つが必要です。

  • 成果 - 何が動くようになるか
  • 範囲 - 今回は何に手を付けないか
  • 確認方法 - あなたが何を見て確かめるか

違いは依頼の書き方を見ると分かります。"検索に取り組む"には終わりがありません。いつまでも作業でき、"完了"の判断も人それぞれです。一方、"ロケールコードで検索でき、空の検索欄には一覧全体を表示する"なら、達成点が明確で、30秒もあればブラウザーで確認できます。

時間やファイル数に共通の上限はありません。ただし規模は大切です。ひとつの段階に複数の独立した変更が混ざり、ひととおり確認するのが難しければ、小さく分けましょう。目安は、単独で作成して確認できる、次の有用な成果です。

成果を動く単位に分ける

学習用のロケール一覧を例にします。各レコードの項目は、上の見本と同じくロケールコード、言語、国、通貨、ドメインです。簡単にするため、完成済みの配列はapp.jsに直接置き、これをindex.htmlから読み込みます。ページは別のリクエストでデータを取得しないので、サーバーなしでブラウザーから開けます。データは次のとおりです。

[
  { "code": "en-US", "language": "English", "country": "United States", "currency": "USD", "tld": ".us" },
  { "code": "de-DE", "language": "German", "country": "Germany", "currency": "EUR", "tld": ".de" },
  { "code": "fr-CA", "language": "French", "country": "Canada", "currency": "CAD", "tld": ".ca" },
  { "code": "ja-JP", "language": "Japanese", "country": "Japan", "currency": "JPY", "tld": ".jp" }
]

要望全体は、一覧、検索、国別フィルターです。冒頭にあった"見栄えも整えて"は独立した段階にしません。M1で一覧と一緒に基本の見た目を作り、後回しにするのは新しいテーマへの変更だけです。要望を3段階に分けてみましょう。

Milestone 1、Milestone 2、Milestone 3の標識がある坂道の階段
段階成果確認方法後回しにすること
M1ページにロケール一覧が表示される4行と各項目をapp.jsの配列と照合する検索、フィルター、新しいデザイン
M2ロケールコードまたは言語で検索できるde-DEとGermanで1件が見つかり、zzzでは見つからず、空欄なら4件すべて表示される国別フィルター
M3国別フィルターが検索と連動するCanadaとFrenchならfr-CAが残り、CanadaとGermanなら一覧は空になる。両方の条件をリセットすると4件に戻る新機能とデザイン
Kotlin
  • M1 一覧
  • M2 検索
  • M3 フィルター

まず動く一覧を作りましょう。レコードの絞り込みを確かめるのに便利です。検索とフィルターはどちらから追加してもかまいません。ここでは検索を先にし、M3で両方の連携を確認します。段階の間の矢印は、前の成果が確認済みであることを表します。緑色のM3は要望全体が満たされる段階です。

ここでは成果を軸に作業を分けています。各段階にはコードの読み込み、変更、確認があります。"まずHTML全体、次にJS全体、最後にまとめて確認"という計画では、動作確認が最後まで先送りになります。完成したマークアップも途中成果にはなりますが、それだけでは検索が動くか分かりません。

エージェントは、まずマークアップ全部、次にロジック全部という層ごとの計画を選びがちです。AIエージェントをよく使う人たちもこの点を話していて、たとえばMatt Pocockの作業プロセスのワークショップでも触れられています。成果ごとに分けるよう明確に頼んでも、こうした計画が出ることがあります。そこでエージェントの提案を確認するときは、各段階の最後に何かを開いて、動作を確かめられるかを見てください。

最初の段階を調査にしてもよい

データの構成が分からないなら、急いでコードの計画を立てる必要はありません。その場合、最初の段階の成果は、レコードの出どころとなるファイルを特定し、項目を挙げ、計画を具体化することです。これも検証可能な成果です。ブラウザーではなく、ファイルを読んで確認します。

ここでの3段階はあくまで一例で、決まりではありません。2段階のこともあれば、6段階になることもあります。

今の段階に必要なコンテキストを渡す

段階を選んだら、プロジェクト全体ではなく、その段階に必要な情報をエージェントに渡します。学習用一覧のM2なら、依頼は次のようになります。

ロケール一覧に検索機能を追加します。
4件の一覧はすでに動作しています。項目と見た目は保ち、元の配列の内容は変えないでください。検索に必要な要素だけ追加してください。

@index.htmlと@app.jsを読んでください。

必要な内容:
- 一覧の上に検索欄を置く
- ロケールコードと言語名で検索できる
- de-DEとGermanでde-DEのレコードが見つかる
- zzzでは一覧に何も残らない
- 検索欄が空なら一覧全体を表示する

今回は国別フィルターを追加しません。
別のファイルが必要なら、名前を挙げて読んでください。
まず成果と段階の範囲を示してください。ファイルはまだ変更しないでください。

提案された範囲でよければ、次のメッセージでM2の実装を頼み、ブラウザーでの確認項目を挙げてもらいましょう。エージェント自身が確認したことと、あなたがこれから確認することも分けて書くよう頼んでください。

例にあるパスは仮のものです。あなたのプロジェクトでは別のファイルになります。依頼にない情報源が必要なら、エージェントに名前を挙げて読んでもらいましょう。ファイル名から中身を推測させるのはよくありませんし、そう頼む必要もありません。

ここでは見た目は独立した種類の情報で、この段階ではそれを維持します。反対に、ページを初めて作るときのように、見た目が段階の成果に含まれる場合もあります。言葉だけでは具体化しにくく、"いい感じにして"という依頼には確認できる基準がありません。判断はエージェント任せです。そんなときは、レイアウト見本、スクリーンショット、色とクラス名を書いた小さなファイルなどを添えましょう。

こうした書き方の限界も覚えておきましょう。"今回はフィルターを追加しない"は指示であって、技術的な制約ではありません。方向性は示しますが、何かを禁止する仕組みではないため、成果はあなた自身で確認します。

変更前に成果を聞いておく

成果と範囲を短く言い直してもらうと、変更前に自分の意図とのずれに気づけます。ただし、実装の正しさが保証されるわけではありません。段階の作業が終わったら、必ず確認しましょう。

段階を小さくするタイミング

段階は作業中に膨らむことがあります。検索から始めたのに、途中でデータ構造を変えたくなり、ついでに見た目を更新し、上部にナビゲーションも加えたくなる。よくある話です。

それぞれの要望が選んだ成果に必要か、確認してみましょう。新しいカラーテーマやナビゲーションは後回しにできますが、検索用の入力欄は必要です。検索対象の情報がレコードに足りなければ、まず範囲を決め直します。今の段階でデータを補うか、準備を独立した検証可能な段階に分けるかです。データを変更しないという制約を、作業中に黙って取り消してはいけません。

範囲を絞り直す依頼は短くまとめられます。

今回はデータ、デザイン、ナビゲーションを変更せず、
それぞれ後で行う項目として記録してください。
ロケールコードと言語での検索は残します。入力欄、検索結果、空欄時の表示を含めてください。

合意した成果が得られ、確認まで終わったら段階は完了です。確認に失敗したら、まず今の段階を解決しましょう。次に進んでも不確実さが増すだけです。

段階がうまく進まないこともあります。エージェントに修正を伝え、やり直してもらっても、また違う。失敗した試行も会話に残り、次の試行はその影響を受けます。Claude Codeのドキュメントには簡単な目安があります。同じ点の修正が2回を超えたら、分かったことをすべて含めた依頼で、新しい会話を始めてください。たとえば"検索用に別配列を作る方法は、元データと食い違うので使えません。元の配列を直接検索してください"。3回目の修正を続けるより、こうした依頼のほうがうまくいくことが多いです。それでも解決しなければ、段階が大きすぎる可能性が高いので分割しましょう。

再開地点を記録する

段階の確認: 成果を確認できなければ修正に戻り、確認できたら状態を記録して次へ進む現在の段階を修正成果を確認合意した基準に沿って修正する同じ段階を続ける状態を記録成果と確認内容失敗成功次の段階
次へ進めるかどうかは確認で決まる

左側の分岐は、成果がまだ確認できていないため、同じ段階の修正に戻ります。右側は状態を記録して次の段階へ進みます。メモには、成功した確認内容と、確認できていないことの両方を残してください。

成果を確認したら、状態を記録しましょう。報告のためではなく、翌日や別の会話でチャットを掘り返して経緯を復元せずに済むようにするためです。

ファイル名は自由です。すでにある作業メモでもかまいません。ここではPROGRESS.mdにします。以下はM1の確認後に書く練習用の例です。自分のメモには、実際に行って確認した内容だけ記録してください。

# ロケール一覧

## 完了
M1: app.jsの配列からロケール一覧を表示。

## 確認済み
index.htmlをブラウザーで開いた。4件があり、各行の5項目は
app.jsの元の配列と一致。

## 未確認
データが空の場合にページがどう表示されるか。
この確認はM1の基準に含まれず、空配列での動作はまだ不明。

## 決定事項
データはapp.jsの配列に保持し、別途読み込まない。
検索を追加するときもレコードの内容と見た目を維持。

## 見送った案
別のJSONファイルからデータを読み込む案。サーバーがないと
ブラウザーで読み込めず、ページをファイルとして開けなくなる。

## ファイル
index.html, app.js

## 残りの段階
M2: ロケールコードまたは言語名で検索できる。
確認: de-DEとGermanでde-DEが見つかる。
zzzでは何も見つからず、空欄なら4件すべて表示。

M3: 国別フィルターが検索と連動する。
確認: Canada + Frenchならfr-CAが残る。
Canada + Germanなら一覧は空。
両方をリセットすると4件に戻る。

## 次のステップ
M2を実施。国別フィルターはまだ追加しない。

重要なのは"確認済み"の項目です。"全部動く"とだけ書いても、1週間後には何の意味もありません。一方、"ブラウザーで開き、4件表示され、項目が一致した"とあれば意味があります。未確認の項目を別に記録するのは、明日になればその違いはもう思い出せないからです。

"見送った案"は、プロジェクトに存在しないことを書くので不要に思えるかもしれません。しかし新しい会話のエージェントは以前の試行を知らず、同じ案を改めて提案することがあります。理由を一行残すだけで、その繰り返しを防げます。

メモ作成をエージェントに任せてもかまいませんが、最新のファイルと確認結果に照らして見直してください。エージェントは、実際に行った作業と計画が並んでいる会話履歴を参照することがあります。ブラウザーで確認した人も記録しましょう。実行していない確認をエージェントがしたことにしないでください。

注意点は2つあります。作業中の一時的な状況をCLAUDE.mdに書くのは避けましょう。ここに記すのはプロジェクトの恒常的なルールであって、今日の作業内容ではありません。また、メモはコードのバージョンを保存しません。状態を記したテキストであり、ファイルの複製ではありません。

必要な情報をそろえて再開する

段階の区切りは、次の作業をどの会話で進めるか決めるのに便利です。判断基準はシンプルです。今の会話が次の作業に役立つか、それとも妨げになっているか。

役立つなら、そのまま続ければよく、特別な作業は必要ありません。"段階ごとに会話をクリアする"という決まりも、何パーセントを超えたらやり直すという基準もありません。

履歴がどれだけ場所を使っているか分からなければ、/contextを実行してウィンドウの使用状況を確認してください。作業の進み具合と照らし合わせ、次の段階で長い出力や議論がまだ必要か考えます。このコマンドは量を見積もる助けになりますが、どの情報が役立つかは判断してくれません。

関係のない情報が増え、新しい会話を始めることにしたら、まずメモを保存してください。/clearコマンドは新しい会話を始めます。前の履歴はその会話の作業コンテキストに渡されませんが、元ファイルはディスクに残り、プロジェクトの指示も引き続き読み込まれます。以前の会話が完全に削除されるわけではなく、保存した会話は/resumeから再開できます。ただし、新しいセッションで作業を続けるなら、必要な決定事項を明示的に伝えるほうが確実です。

作業の再開にはPROGRESS.mdと最新ファイルの両方が必要です。読み込んで状態を照合してからM2を実施しますPROGRESS.md確認・決定したこと残っている作業最新のファイルindex.html + app.js現在の実装読み込んで状態を照合変更を始める前にずれを解消M2から再開状態を把握したら
メモとコードは互いを補う

2本の矢印は、作業再開の前に合流します。メモには決定事項と確認結果があり、ファイルには現在のコードがあります。エージェントに両方を読ませて状態を説明してもらい、M2を依頼する前にあなたが回答を照合します。

新しい会話での依頼は簡単です。

@PROGRESS.md、@index.html、@app.jsを読んでください。
何が完了・確認済みで、何が残っているかを自分の言葉で説明してください。
ファイルはまだ変更しないでください。

回答は注意して読みましょう。実際には行っていないことを完了済みと言われたら、メモ、ファイル、確認結果と照合してください。記録が曖昧なのか、コードが古いのか、エージェント自身が間違えたのかもしれません。新たな変更の前に食い違いを解消してください。新しい会話にするだけでは、誤った仕様が直ることも、正しく理解されることも保証されません。

一覧を最初から最後まで作る

説明はここまでです。今度は同じ一覧を実際に作ります。空のフォルダーから始め、M2を確認して再開地点を記録するところまで、記事の流れに沿って4つのステップを進めます。各ステップでは、まず自分でプロンプトを考え、次に見本を別案として確認してください。目的は文をコピーすることではなく、エージェントに何の情報が必要か考えることです。

ステップ1. コードなしで計画する

まだプロジェクトはありません。最初に"一覧を作って"と頼みたくなるかもしれません。そうすると、方針を決める前にファイルができてしまいます。このステップでは逆に、計画だけを作り、ファイルはひとつも作らないようにします。入力する前に、次の4点を考えてみてください。

  • エージェントにすぐコードを書かせないため、どう伝えるか
  • まだファイルがない状態で、代わりにどんな情報を渡せるか
  • 余計なツールを持ち込まないため、どんな技術上の制約を示すか
  • まだ何も作らないなら、何を成果として求めるか

例はこちらです。

学習用のロケール一覧を作りたいです。レコード一覧と検索、
国別フィルターが必要です。まだプロジェクトはありません。

サーバーやビルドなしで、ページをファイルとしてブラウザーから
開けるようにしてください。ファイルはindex.html、styles.css、
app.jsだけにします。レコードの項目はロケールコード(en-US)、
言語、国、通貨、ドメインです。

まず計画を立ててください:
- タスク全体の目的、範囲、確認方法を挙げる
- 作業を3段階に分ける
- 各段階の成果と、確認時に私が目にするものを示す
- 私から追加で必要な情報を挙げる
- 作成するファイルを列挙する

まだファイルは作成しないでください。

提案された段階を上のM1-M3の表と照らし合わせてください。順序が違っても問題ありません。エージェントが"マークアップ全体、その後JS全体"と分けたら、各段階の後にページが何かできるよう、分け直してもらいましょう。段階の終了時に観察できる動作が書かれていなければ、今のうちに依頼を修正します。コードを書く前なら、ひとこと伝えるだけで済みます。

ステップ2. M1だけを見本付きで

範囲は狭く、ページに4件を表示するだけです。検索もフィルターもありません。ただし、ページを初めて作るので、見た目は後回しにできません。見本を添えましょう。プロジェクトのフォルダーにmockup.htmlとして保存します。JavaScriptなしの静的なマークアップで、色とクラス名だけを記します。

<style>
  body   { background:#0f172a; color:#e2e8f0; font-family:system-ui, sans-serif; padding:24px }
  .search{ width:100%; margin-bottom:12px; padding:10px 14px; border-radius:10px;
           background:#1e293b; color:#e2e8f0; border:1px solid #334155 }
  table  { width:100%; border-collapse:collapse }
  th, td { padding:10px 12px; text-align:left; border-bottom:1px solid #334155 }
  th     { color:#8b98b1; font-size:13px }
  .code  { font-family:ui-monospace, monospace; font-weight:700; color:#818cf8 }
</style>

<input class="search" placeholder="Search by code or language">
<table>
  <tr><th>Code</th><th>Language</th><th>Country</th><th>Currency</th><th>TLD</th></tr>
  <!-- 行の見本。実際の行はapp.jsが描画 -->
  <tr><td class="code">en-US</td><td>English</td><td>United States</td><td>USD</td><td>.us</td></tr>
</table>
C++

見本には検索欄も描かれていますが、M1ではページに追加しません。何もしない空の欄は確認しにくいからです。スタイルは.searchクラスにあり、M2で使います。

もうひとつ、エージェントにはデータを明示的に渡しましょう。渡さないと独自のデータを作り、表にある確認項目（4行、de-DE、Canada）と一致しなくなります。ではプロンプトです。ひとつの段階に留めるにはどう伝えるか、変更前に何を提示してもらうか、成果をどう確認するかを考えてください。

M1だけを実施します。app.jsの配列からロケール一覧を
表示してください。今回は検索もフィルターもありません。
見本にある検索欄もまだ追加しないでください。

データはこの4件の配列です。内容を変更しないでください:
[記事内の配列を挿入]

見た目は@mockup.htmlを使い、色とクラス名もそこにあるものに
してください。新しく考えないでください。

まず、作成するファイルの計画と、どこまで作業するかを示してください。
私が計画を承認するまでファイルは作成しないでください。
変更後に、私が何を開き、何と照合すればよいか教えてください。

M1の後で止めてください。私が言うまでM2に進まないでください。

計画が膨らみすぎていたら承認せず、確認可能な成果ひとつに段階を絞ってもらいましょう。計画がよければ変更を許可し、ページを開いて4行を配列と照合します。この時点で基本の見た目も決まりました。以降は維持し、テーマ全体の変更は後回しにします。

ステップ3. M2と正確なメモ

M2のプロンプトは"今の段階に必要なコンテキストを渡す"で説明しました。そこに戻り、自分のパスを入れてください。例ではファイルが2つですが、M1後のあなたのプロジェクトには3つあります。index.htmlとapp.jsに加えてstyles.cssも指定します。もう一文加えましょう。見た目は新たに決めるのではなく、維持することを伝えます。

見た目はM1で@mockup.htmlに合わせて決めました。変更せず、
検索欄にはその中の.searchクラスを使ってください。

エージェントが正しい範囲を示したら、変更を許可しましょう。フィルターやデータ構造に手を付けようとしたら、作業前に確認してください。検索の3項目を確認できたら、上の例を参考にPROGRESS.mdへ状態を記録します。今度はM2の後なので、実際のファイル一覧に合わせてください。

メモが役に立つかも確かめましょう。"確認済み"の項目が"だいたいできた。あと少し"だけだったと想像してください。1週間後には何の意味もありません。再開できるよう、何を開いて何を確認したか、確認範囲に含まれなかったこと、次のステップを具体的に書き足します。たとえば"M2: de-DEとGermanでde-DEが見つかり、zzzでは何も見つからず、空欄なら4件が表示される"、"データが空のときの動作は未確認"、"次はM3、国別フィルター"のように。

ステップ4. 新しい会話から再開する

最後のステップで確認するのはコードではなくメモです。新しい会話を始め、PROGRESS.mdと最新ファイル3つすべて（styles.cssも含む）を基に状態を説明してもらい、自分が行ったことと照らし合わせます。確認していないことをエージェントが完了済みとしたなら、メモが曖昧すぎる可能性があります。直すべきなのは新しい会話ではなくメモです。それでもファイルと照合してください。原因がコードやエージェントの誤りにある場合もあります。内容が一致すれば、確認済みのM1とM2、そしてM3を始める地点がそろいます。

このプロンプトが唯一の正解ではない

あなたの依頼でも、コードを書く前の計画、ひとつずつ進める段階、明確な成果と確認方法という手がかりがそろっていれば、見本と同じように使えます。まだアイデアしかないなら、エージェントに確認質問をしてもらい、範囲の案を2、3個出してもらいましょう。曖昧なアイデアから無理に正確な仕様をひねり出す必要はありません。

次の段階へ進む

全体の流れは次のとおりです。

  1. すぐに確認できる次の成果を選ぶ
  2. その段階の情報源を渡し、範囲を伝える
  3. 今の段階を実施し、新しい要望は別に記録する
  4. 合意した方法で確認する。この例ではブラウザーでページの動作を見る
  5. 完了、確認済み、未確認、見送った案、次のステップを記録する
  6. 今の会話を続けるか、新しい会話を始めるか決める

ひとつの段階がひとつのメッセージで終わるとは限りません。3通で済むことも15通かかることもあります。それで問題ありません。段階の数と会話の数も同じではありません。隣り合う複数の段階をひとつの会話で進めてもよく、難しい段階ひとつに会話を2つ使うこともあります。

どの時点でも、何が動いていて、何で確認したかを答えられるようになります。大きなタスクでは、これがいちばん大切かもしれません。