「関連ファイルを全部見て直して」という依頼は、何を達成すればよいかが曖昧になりがちです。
一方で、対象を狭めすぎると、共有部品への影響を見落とします。
このレッスンでは、申込ボタンの修正を例に、入口、変更対象、参照対象、対象外を分けます。
必要な背景を渡しながら、探索と編集を目的に沿って進める方法を学びます。
この記事で学ぶこと
- 正本から読む順番を作る
- 参照と変更を分担させる
- 追加変更には理由と検証を添える
最初に読む正本を選ぶ
入口には、現在の仕組みと今回の目的が分かる文書を選びます。
プロジェクトのREADMEが役立つ場合もあれば、画面の仕様書が適している場合もあります。
入口を1つ示し、そこから対象の画面やデータへ進めるようにします。
ファイル名を大量に列挙するより、読む順番と役割が分かることを優先します。
架空のサイトで申込ボタンの表示が曖昧なら、依頼メモに「資料請求と申込を区別できない」と書きます。
その上で、対象ページと確定した操作の説明を示します。
「分かりやすくする」だけでは、デザインを変えるのか、文言を変えるのか、動作を変えるのかが揃いません。
困りごとの具体化が探索の基準になります。
正本の更新状態も確認してください。
古い仕様書と現在のコードが違う場合、どちらが正しいかはファイル名だけでは分かりません。
確認済みの決定を根拠にし、不明な差は報告へ残します。
入口を指定することは、その内容を無条件に正しいとすることではなく、判断を始める場所を共有することです。
入口に示す要求は、観察した事実と改善案を分けます。
ボタンの意味を利用者が取り違えたという記録と、色を変えれば解決するという仮説は別です。
最初から色の変更だけに限定すると、文言の問題を見落とすかもしれません。
困りごとを根拠として渡し、解決案は検討できる余地を残します。
編集と参照の役割を分ける
対象のページを理解するために、共通部品や設定を読む必要があっても、それらを変更する必要があるとは限りません。
「参照してよい」と「編集してよい」を分けて指示します。
これにより、調査に必要な背景を渡しながら、無関係な変更を抑えられます。
例えば、申込ページの文言を直すためにボタン部品を確認したところ、文言はページ側で指定できると分かったとします。
この場合、共通部品の変更は不要です。
反対に、文言が部品内に固定されていれば、複数ページへの影響を確認する必要があります。
最初に想定したファイルだけに固執せず、理由を示して範囲を更新します。
生成されたファイルにも注意します。
出力済みのページだけを直しても、元のデータから再生成すれば消えることがあります。
どこを編集すれば次の更新にも残るかを調べます。
ファイルの場所ではなく役割で考えると、正本と生成物を区別でき、後で消える修正を避けやすくなります。
参照範囲には、変更箇所を理解するための依存先を含めます。
ボタンが外部の設定値を読むなら、その設定の意味を確認する必要があります。
ただし、参照したものすべてを最新化する必要はありません。
読む目的を今回の要求へ結び付ければ、調査と改修が無制限に広がることを避けられます。
対象外を影響から決める
対象外には、今回変える必要がなく、変わると困る条件を置きます。
申込ボタンの文言なら、送信先、料金、個人情報の入力項目などが候補です。
「他は全部触らない」とだけ書くより、特に重要な動作を示す方が確認しやすくなります。
禁止の長さより、影響の大きい条件を明確にします。
対象外を設定する理由も短く添えます。
「送信先は運用確認済みなので維持する」なら、目的との関係が分かります。
ただし、現状に不具合が見つかった場合は、見つけた事実として報告してもらいます。
今回の修正へ混ぜず、別の判断へ回してください。
変更の責任範囲を保つための区別です。
セキュリティや重大な動作不良を見つけたときも、勝手に大規模修正へ広げることが最善とは限りません。
現象、影響、必要な確認を整理し、許可された範囲で対応します。
目の前の不具合を直したい気持ちと、依頼全体の管理を分けて考えることが、複数人での作業では特に必要です。
対象外の不具合を報告するときは、今回の変更によるものと誤解されないよう区別します。
見つけた場所、現象、再現条件を短く残し、修正済みとは書きません。
別の依頼へ分ければ、優先順位と検証範囲を改めて決められます。
発見を無視せず、今回の作業へ無秩序に混ぜない整理方法です。
情報不足だけを追加で調べる
探索を広げるときは、答えたい問いを具体化します。
「ほかも調べる」ではなく、「同じ部品を使うページを確認する」「申込先がどこで決まるかを確認する」と書きます。
問いが明確なら、必要な検索範囲と得たい結果を判断できます。
調べること自体が目的にならないようにします。
追加調査の結果は、変更判断に関係する情報へまとめます。
ファイルの一覧を長く並べるより、「同じ部品を3画面が使用し、そのうち文言を渡しているのは2画面」といった関係が役立ちます。
数は実際に確認した結果として扱い、推測を含む場合は区別します。
調査結果が設計の判断へつながる形にします。
必要な資料が見つからない場合、似た名前のファイルやAIの知識で補って進めないようにします。
見つからなかった範囲と、次に必要な情報を残します。
根拠がない状態を明示すれば、担当者が資料を追加できます。
探索を長く続けるより、何が不足しているかを早く特定する方が有効な場合もあります。
探索の終了条件も置くと、同じ検索を繰り返すことを減らせます。
指定の範囲で正本が見つからなければ、その範囲と候補を報告するという条件です。
どこまで調べたかが分かれば、人が資料を補えます。
探索量を増やすより、不足する情報を特定できたかを成果として扱います。
実際の差分で範囲を評価する
作業後は、指定した範囲と実際の変更を比較します。
予定したページだけが変わったか、共通部品への変更があれば理由は妥当かを見ます。
次に、対象外として指定した動作が維持されているかを確認します。
ファイル数だけでなく、利用者への影響を判断することが必要です。
報告には、変更対象が増えた場合の理由を含めます。
「文言が共有部品に固定されていたため、ページごとに指定できるようにした」などです。
その場合は他の利用箇所の検証も必要になります。
範囲の拡大は必ず悪いわけではありませんが、理由と確認が対応していなければ採用の判断ができません。
予定外の変更を見つけたら、他者の作業を巻き込まず、対象を限定して調べます。
差分に含まれるものがすべて今回のCodexの作業とは限りません。
作業開始時の状態を記録しておくと区別しやすくなります。
入口、変更範囲、開始状態の3つが揃うと、作業後の確認にも一貫した基準を持てます。
範囲内の変更でも、目的を達成していなければ完了ではありません。
ボタンの文言を変えても、周囲の説明と食い違えば利用者は迷います。
指定箇所と前後の文脈を一緒に読み、行動が分かるか確認してください。
範囲の管理と利用者の成果を、別々の合格条件として見ることが必要です。
実践課題
実践課題：四欄の作業指定を作る
つくるものは、申込ボタン修正の範囲指定です。
用意するのは、架空の仕様メモと対象ページの情報です。
入口、変更対象、参照のみ、対象外の4欄で書きます。
共有部品の変更が必要と分かった場合の扱いも添えてください。
- 入口から目的と正本を示す
- 編集するページと箇所を指定する
- 背景として読む資料と維持する動作を書く
- 追加調査が必要になる条件を決める
架空の完成例：「入口はrequest.md。対象は申込ページのボタン文言。共通部品は参照のみ。送信先と料金は維持する。共通部品の変更が不可欠なら、影響する画面と検証案を示して範囲を更新する。」
自己確認
- 読み始める場所が明確である
- 読むことと編集を区別している
- 範囲を広げる理由と確認が対応する
まとめ
作業範囲は、入口だけでなく編集、参照、対象外を分けて指定します。
必要な背景を保ちつつ、情報不足の問いに沿って探索を広げます。
次の依頼では4欄を使い、終了後に実際の差分と照合してください。
- 正本から読む順番を作る
- 参照と変更を分担させる
- 追加変更には理由と検証を添える
