手順の可搬性を設計する（Designing Procedure Portability）

再利用する手順をどこに置くかは、道具の側が決めている。そして道具どうしの互換は、たいてい片方向である — 一方が他方のディレクトリを読むからといって、逆が成り立つとは限らない。

問題

同じ仕事を繰り返すなら、手順を書いて再利用したい。ところが手順の置き場所は、自分では決められない。エージェント製品が「ここを読む」と決めた場所にしか置けない。

道具を1つしか使わないなら、これは問題ではない。言われた場所に置けばよい。問題が始まるのは、道具が2つ以上になったときである。同じ手順を、製品ごとの場所に置くことになる。

そこで素直に複製すると、複製の数だけ悩みが増える。どれが最新か。片方だけ直したのはどれか。片方にしか無い記述は、意図した差か、直し忘れか。やがて誰も、どれが正本か言えなくなる。

もう一つ、複製とは別の壊れ方がある。共有したい手順に、特定の製品でしか意味を持たない記述が混ざる。 書いたときは1つの製品しか使っていないので、混ざっていることに気づかない。二つ目の製品に持っていって初めて、その記述が無視されるか、あるいは解釈されずに落ちることが分かる。

そして最も見落とされやすいのが、互換の非対称性である。「製品 X は製品 Y のディレクトリも読む」と分かると、人は安心して「では共通で置ける」と考える。しかしそれは片方向の事実でしかない。 逆向きに同じことが成り立つ保証はどこにも無い。

コンテキスト

適用する条件:

• エージェント製品を2つ以上使っている（あるいは同じ製品の複数の面を使っている）— 1つなら、道具の言うとおりに置けば終わる
• 同じ手順を両方から使いたい — 片方でしか使わない手順に可搬性は要らない
• 手順が育つ — 一度書いて終わりなら複製でも困らない。改訂が続くものほど、正本の不在が高くつく
• 手順が長い — 数行の規約なら重複させても管理できる。長い手続きほど食い違いが見えにくい

適用しないケース:

• 道具を1つしか使わないとき。 可搬性は将来の保険であり、保険料は今払うことになる
• 手順が一度きりのとき。 そもそも切り出す段階に至っていない（「命令の階層化と適用範囲の限定」）
• 互換が既に成立している向きだけを使うとき。 後述するように、片方向は「置くだけ」で済む場合がある。成立している向きに、要らない仕組みを足さない

隣接パターンとの境界:

• 命令の正本を一つにする — 最も近いが、扱う壊れ方が違う。同パターンは優先順位の食い違い（複数の命令のうちどれが勝つか分からない）を扱う。本パターンは複製の散逸（同じ内容の写しが増えてどれが正本か分からない）を扱う。前者の対策は「競合を作らない」、後者の対策は「配布元を1つにする」である
• 命令の階層化と適用範囲の限定 — 常駐させるか必要時に読ませるかが同パターン。本パターンは、必要時に読まれる手順の置き場所を扱う。切り出すかどうかを決めてから、どこへ置くかを決める
• 常駐物の棚卸し — 常駐物の総量。切り出した手順は常駐しないため、直接は緊張しない
• 無人経路にこそ強いゲート — 手順がいつ起動するかは同パターンが扱う。本パターンはどこに置かれるかだけを扱う

解決

順序がある。まず互換を調べ、それから足りない分だけ仕組みを作る。

1. どちらの向きが成立しているかを、資料で確かめる。 「たぶん共通だろう」で始めない。探索先は製品の仕様であり、書いてある。そして両方向を別々に確かめる — 片方向の記述を見て双方向だと読むのが、この領域で最もよくある誤りである。

2. 成立している向きには、何も足さない。 製品 A が製品 B のディレクトリを読むなら、B の場所に置くだけで両方から使える。ここに同期の仕組みを入れるのは、費用だけ払って何も買わないことになる。

3. 成立していない向きにだけ、配布を用意する。 正本を1つ決め、そこだけを編集する。各製品の探索先には配布物を置き、配布物は生成物として扱う（編集しない、あるいは生成し直せば消える前提で扱う）。正本をどこに置くかは、どの製品の探索先でもない場所にするのが素直である — 探索先の1つを正本にすると、その製品だけが特別扱いになり、後で製品が増えたときに歪む。

4. 共有する正本には、どの製品でも意味を持つ記述だけを置く。 特定の製品にしか無い設定は、正本に混ぜず外へ出す。混ぜても壊れないことは多いが、壊れないことと、意味を持つことは違う。 他の製品ではただ無視されるため、書いた側は「効いている」と誤解したまま運用することになる。

なぜこの順序なのか。可搬性は目的ではなく費用だからである。 正本と配布物を分けると、編集の場所を間違える余地が生まれ、配布を忘れる余地が生まれ、生成物をコミットするかどうかの判断が要る。互換が既に成立している範囲では、これらを一切払わずに済む。 だから先に調べる。

トレードオフ

利点

• 正本が一意になる。 「どれが最新か」を考えなくてよくなる。改訂の頻度が高い手順ほど効く
• 製品を増やすときの費用が下がる。 配布先を1つ足すだけになる。複製運用では、既存の写しすべてと突き合わせる作業が発生する
• 意図した差と直し忘れが区別できる。 差が出るのは配布の仕組みの中だけになり、正本の側には差が存在しない
• 製品固有の記述が可視化される。 正本から追い出す過程で、「これはどの製品の話か」を一度は考えることになる

代償

• 正本と配布物という二重構造そのものが費用である。 編集する場所を間違えると、次の配布で黙って消える。消えることが最悪ではない — 消えたことに気づかないのが最悪である
• 配布の実行を忘れる。 手作業なら必ず忘れる。忘れたことを検出する仕組みまで用意して、初めて仕組みとして完成する（「機械ゲートと意味ゲートの分離」）
• ⚠ 「外部に正本を置いて配布する」構成そのものは、確認した範囲ではどちらのベンダーも推奨していない。 公式に確認できるのは探索先がどこかまでである。構成は本カタログが機構から導いた設計案であり、公式の推奨として読まないこと（具体例節）
• 互換は変わりうる。 探索先は製品の仕様であり、仕様は改訂される。今日の非対称が明日も同じとは限らない — 依存している向きは、記録に残して定期的に確かめる（「記録した判断を後から監査させる」）
• 共有のために内容が痩せる。 どの製品でも意味を持つ記述だけに絞ると、特定の製品でだけ効く強い指定を諦めることになる。可搬性と最適化は交換関係にある

GitHub Copilot での具体例

探索先の非対称は、両ベンダーの一次資料で確認できる。 以下はいずれも 2026-07-26 に生 HTML を取得し、本文に対して検索した結果である。バイト数は全文を取得したことの記録であり、同一性の証明ではない。

GitHub 側 — 三つのディレクトリを読む 公式

出典: About Agent Skills（551,223 バイト）。

Project skills, stored in your repository (.github/skills, .claude/skills, or .agents/skills)

〔訳〕プロジェクトのスキルは、リポジトリに置かれる（.github/skills、.claude/skills、または .agents/skills）

Personal skills, stored in your home directory and shared across projects (~/.copilot/skills or ~/.agents/skills)

〔訳〕個人のスキルは、ホームディレクトリに置かれ、プロジェクト間で共有される（~/.copilot/skills または ~/.agents/skills）

grep -c は .github/skills が2件、.claude/skills が2件、.agents/skills が3件、.copilot/skills が2件である。

Copilot は、他のベンダーの慣習的なディレクトリを読む側にいる。

Anthropic 側 — .claude/ 配下だけを読む 公式

出典: Skills（953,891 バイト）。同じ資料に対する grep -c は次のとおりである。

検索語	ヒット数
.claude/skills	23
.github/skills	0
.agents/skills	0
SKILL.md	27

非対称はここに現れる。 Copilot 側の資料は3つのディレクトリを列挙するが、Anthropic 側の資料が列挙する探索先は .claude/ 配下に限られ、他ベンダーのディレクトリへの言及は0件である。

したがって実務上こうなる — .claude/skills に置いた手順は、確認した範囲では両方から読める。.github/skills にだけ置いた手順は、Copilot からしか読めない。 置き場所を1つ選ぶだけで済む場合があり、そのときは配布の仕組みを作る理由が無い。

⚠ これは「今日の資料にそう書いてある」という事実であって、恒久的な保証ではない。 依存するなら、依存していること自体を記録に残すこと。

面ごとに探索先が違う — 手順以外でも同じである 公式

同じ非対称は、手順以外の再利用単位にも現れる。

• Copilot CLI のカスタムエージェント — .github/agents/ と ~/.copilot/agents/ に .agent.md を置く（Creating custom agents for Copilot CLI、581,336 バイト。grep -c は .github/agents が2件、.copilot/agents が2件、.agent.md が4件）
• リポジトリのカスタム命令 — .github/copilot-instructions.md と .github/instructions/NAME.instructions.md（Adding repository custom instructions）
• Claude Code のメモリ — ~/.claude/CLAUDE.md、./CLAUDE.md、./.claude/CLAUDE.md ほか（Manage Claude's memory、616,932 バイト）

同じ「再利用したい文章」でも、単位ごとに置き場所の規約が別々にある。 手順で互換が成立していても、命令やエージェント定義で成立しているとは限らない。単位ごとに確かめること。

不在確認 — 配布という構成を勧める記述は無い

上記4資料（About Agent Skills / Claude Code の Skills / Copilot CLI のカスタムエージェント / Claude Code のメモリ）の本文全体を確認した範囲で、「探索先の外に正本を置き、各探索先へ同期せよ」という趣旨の記述は見つからなかった。 公式が述べているのは、どのディレクトリを読むかまでである。

したがって本ページの「解決」節のうち、探索先の非対称は 公式、正本と配布物に分ける構成は本カタログの設計案である。この差を潰さないこと。

別名

呼称	出典
手順の可搬性を設計する / Designing Procedure Portability	記述 — 本カタログの記述的呼称であり、一次資料に出典は無い
Agent Skills / SKILL.md	一次 — ただしこれは手順を書く形式の名であり、可搬性を設計するという実践の名ではない
Single source of truth	通説 — 一般的な設計用語。手順の配布という文脈での一次出典は確認できていない。なお本カタログでは、命令の優先順位を扱う「命令の正本を一つにする」がこの語を別名に持つ

形式には公式の名前があるが、「どこへ置き、どう配るか」という設計には名前が無い。 形式の名前を実践の名前として使うと、「その形式で書いている＝可搬である」という誤解になる。実際には、同じ形式で書いても片方からしか読めない場所に置くことはできる。

関連

• 命令の正本を一つにする — 正本を一つにするという目的は共通だが、扱う壊れ方が違う。あちらは優先順位の食い違い、本パターンは複製の散逸である
• 命令の階層化と適用範囲の限定 — 常駐させるか切り出すかが同パターン。切り出すと決めた後、どこへ置くかが本パターンである
• 無人経路にこそ強いゲート — 置いた手順がいつ起動するかを扱う。置き場所と起動条件は別の問題である
• 機械ゲートと意味ゲートの分離 — 配布の実行漏れは機械で検出する。人間の注意で守る仕組みにしない
• 記録した判断を後から監査させる — 依存している互換の向きは、仕様の改訂で崩れうる前提である。監査の対象になる