実物を指して差分で指示する（Reference Artifact as Spec）

望むものを言葉で構成しようとすると、書いた分だけ解釈の幅が残る。だから既に存在する成果物を参照先として指し、そこからの差分だけを述べる。⚠ 一次資料が参照先として名指ししているのは自コードベース内の既存実装であり、外部の成果物までは届かない（出典は具体例節）。

問題

「カレンダーのウィジェットを追加してほしい」と書く。文としては完成している。だが受け取る側から見ると、決まっていないことがいくつも残っている — 月をどう選ばせるのか、年をまたぐ操作があるのか、既存の画面と同じ組み立て方をするのか、ライブラリを新しく入れてよいのか。

そこで書き足す。段落が増える。それでも埋まらない。言葉で仕様を構成する作業は、書けば書くほど「まだ書いていないこと」が増えていく性質を持っている。既存の画面がどういう約束の上に建っているかは、その約束を全部書き出さない限り伝わらない。そして全部書き出すことは、たいてい実装より高くつく。

しかも、埋まっていない部分は空白のまま残らない。エージェントは自分の既定で埋めてくる。出てきたものを見て「そうではない」と気づき、また言葉で直す。往復のたびに、言葉で構成した仕様と、頭の中にある実物のあいだの差が現れる。

このとき、頭の中にある実物がすでにどこかに存在していることがある。似た画面が同じリポジトリにある。参考にしたい書き方が別のファイルにある。その場合、言葉は情報を伝えているのではなく、情報を落としている。 実物には約束が全部載っているのに、それを言葉に写し取る過程で落ちる。

コンテキスト

適用する条件:

• 似たものが既に存在する — 同じリポジトリの既存実装、以前に自分で通した手順、参考にしたい書き方。この条件が本パターンの前提である
• 言葉で書き切ろうとすると長くなる — 体裁・命名・構造・依存の約束など、明文化されていない前提が多い仕事
• 違いが少数の点に絞れる — 「これと同じで、ここだけ違う」と言える形にできる

適用しないケース:

• 参照できる実物が無い。新規に作るものが手元のどこにも似ていないなら、本パターンは空回りする
• 参照先が悪い例である。指した先の約束ごと引き継がれるため、直したい書き方を指すと直らない
• 差分が本体より大きい。「これと同じで、ほとんど全部違う」は参照ではない

隣接パターンとの境界:

• 出力の契約を明示する — 同パターンは出力の形（分量・構造・述べ方）を言葉で契約する。本パターンは、言葉による構成が高くつく場面で実物に置き換える。契約の向きが逆であり、対になる — 契約する対象が無い（まだ何も無い）ときは同パターン、既にある（指せる）ときは本パターンである
• 語より先に指示対象を決める — 同パターンはエージェントが出す語が何を指すかを先に確定させる。本パターンは人が与える指示が何を指すかを、言葉ではなく実物で確定させる。どちらも指示対象を先に決める型だが、向きが逆である（出力側か入力側か）
• 計画の先制検証 — 同パターンは、書き換えの前に何をするかを出させて人が読む。本パターンは、その手前で何に似せるかを渡す。参照先が決まっていれば、計画の読みどころは差分に絞られる
• 成果物の差分レビューと段階的採用 — 同パターンは出てきたものを差分で受け取る。本パターンは渡すものを差分で述べる。差分という単位を入口に置くか出口に置くかの違いである
• 手順の可搬性を設計する — 参照先が「毎回同じもの」になったなら、それは指すべき実物ではなく手順として切り出す段階に来ている。同パターンへ渡す

解決

指示を「言葉で構成する」から「実物＋差分」へ組み替える。

手順は3つである。

1. 参照先を1つに決める。 「既存のものに合わせて」では指したことにならない。どれかを名指しする。複数を指すなら、それぞれについて何を引き継ぐのかを分ける
2. 引き継ぐものを暗黙のままにしておく。 参照先が持っている約束（構造・命名・依存の範囲）は、書き写さない。書き写した瞬間に、写し損ねた分が抜ける
3. 差分だけを述べる。 何が違うのか、どこまで変えてよいのか。ここだけは言葉で書く

なぜ効くのか。言葉による記述は仕様を過小決定する — 有限の文で無限の細部を確定させることはできないため、埋まらない部分が必ず残る。一方、実在する成果物はそれ自体で確定している。参照先を指すことは、確定済みの仕様をまるごと渡すことであり、そこに残る不確定は「差分として述べた部分」だけになる。書く量は仕様の大きさではなく違いの大きさに比例する。

Anthropic の一次資料は、この対比を Before / After として規範化している。Before は望むものを一言で述べる指示、After は既存実装を名指ししたうえで差分を述べる指示である（公式、出典は具体例節）。同じ資料が、実物を渡すべき理由を 「言葉での記述が不明瞭または煩雑になるとき」 と述べている（公式、同）。

⚠ 本パターンは few-shot（入出力の例をペアで与えること）ではない。 入出力のペアは、望む振る舞いを例で示す。本パターンが渡すのは、望む成果物そのものの参照先である。一次資料の側でも別の項目として置かれている（出典は具体例節）。

⚠ 「再現せよ」と「差分だけ変えよ」を一続きに書かない。 実物を渡すことの根拠は両者に共通するが、差分指示のほうを規範として述べているのは確認した範囲では Anthropic 側だけである（同）。

トレードオフ

• 参照先の質がそのまま結果の質になる。 悪い書き方の実装を指せば、その書き方ごと引き継がれる。直したい対象を参照先にしてはならない — 直す前のものが正解として渡ってしまう
• 参照先が陳腐化する。 指した実物が古い約束の上に建っていれば、新しく作るものも古い約束を引き継ぐ。参照先は、指すたびに「今もこれでよいか」を問い直す対象である
• 暗黙のものを渡す以上、何が渡ったのかは人にも見えない。 引き継がれた約束を列挙することはできない。想定していなかった性質まで引き継がれることがあり、それに気づけるのは出力を見たときである
• 参照先を読む費用がかかる。 指した実物をエージェントが読む分、コンテキストは消費される。参照先が大きいほどこの費用は増える。言葉で書くほうが安いこともある — 差分が小さく、参照先が巨大なときである。この判断は委譲の損益分岐と同じ形をしている
• 口頭の指示に馴染まない。 参照先を指すには、指せる形（ファイル名・URL・画像）で手元にある必要がある

GitHub Copilot での具体例

⚠ 本節の記述は面（VS Code / github.com / Copilot CLI / cloud agent）ごとに異なる。

GitHub — 既存の似た仕事を例として渡す（面: github.com。Copilot Spaces の使い方として）

Speed up development work（取得日: 2026-08-01）は、space に何を入れるかの助言として次を挙げる。

Provide examples of how similar tasks have been handled in the codebase.

〔訳〕そのコードベースで似た仕事がどう扱われてきたかの例を提供する。

⚠ これは Copilot Spaces という機能の使用例であって、指示の書き方の規範ではない。 本パターンが述べる Before / After の対比も、「差分だけを述べよ」という規範化も、GitHub 側の資料には見当たらなかった（不在確認。確認したのは prompt engineering / get-started の best practices / cloud agent の get-the-best-results / cookbook の refactor-design-patterns。いずれも 2026-08-01 取得。検索語: mockup / screenshot / visual / reference / existing / similar to / example of the output / mock / design / URL）。

⚠ cloud agent の面はむしろ逆を向いている。 同面の資料が求めるのは、問題の明確な記述・完全な受け入れ基準・変更対象ファイルの指示である。「両社が同じことを言っている」とは書けない。

Anthropic（Claude Code）— 既存実装を名指しして差分を述べる

Claude Code best practices（取得日: 2026-08-01）は、指示の書き方を Before / After の表で示す。その行の見出しがこれである。

Reference existing patterns

〔訳〕既存のパターンを参照する。

After 側の指示は、既存のウィジェット群とその一例を名指しし、続けて差分を述べる形になっている。

follow the pattern to implement a new calendar widget

〔訳〕そのパターンに従って、新しいカレンダーウィジェットを実装する。

⚠ 参照先として名指しされているのは自コードベース内の既存実装である。 外部のサイト・製品・動画を参照先にする話ではない。

同じベンダーの Common workflows（取得日: 2026-08-01）は、画像を渡す場面について理由を述べている。

Use images when text descriptions would be unclear or cumbersome

〔訳〕言葉での記述が不明瞭または煩雑になるときは、画像を使う。

⚠ 同じ節の例示は「再現」である（デザインモックに合う CSS を生成する、コンポーネントを再現する HTML 構造を問う）。実物を渡すことの根拠にはなるが、そこから差分だけ変えることの根拠にはならない。

⚠ few-shot とは別項である。 GitHub の prompt engineering ドキュメントが挙げる「例を与える」は入力例と出力例を指し、Anthropic の multishot prompting も同じく入出力のペアを扱う。Anthropic 側では、上記の「Reference existing patterns」がそれとは別の項目として置かれている。

別名

確立した呼称は見つかっていない。「実物を指して差分で指示する」は本カタログの命名である（記述）。

素材はこの型を「references」と呼ぶが、それは渡す物の名であって型の名ではない。Anthropic の資料にある「Reference existing patterns」は表の行見出しであり、呼称として流通しているものではない。

⚠ few-shot / multishot prompting は本パターンの別名ではない。 入出力のペアを与えることを指す別の型である。

関連

執筆中

本カタログは順次公開している。リンクの無い項目は未着地である。

• 出力の契約を明示する — 出力の形を言葉で契約する。本パターンと対になる（言葉で構成するか、実物で示すか）
• 語より先に指示対象を決める — 指示対象を先に決める点で同型。向きが逆で、あちらは出力側の語、こちらは入力側の指示
• 計画の先制検証 — 参照先が決まっていれば、計画の読みどころは差分に絞られる
• 成果物の差分レビューと段階的採用 — 差分という単位を出口に置く型。本パターンは入口に置く
• 手順の可搬性を設計する — 毎回同じものを指すようになったら、手順として切り出す段階である
• 委譲の損益分岐 — 参照先を読ませる費用と、言葉で書く費用のどちらが安いかは、同じ形の判断である
• 常駐物の棚卸し — 参照先を常に読ませるようにすると、それは常駐物になる