前回から6年ぶりの投稿です。
TL;DR
設計変更のとき、AI コーダーに旧設計・旧コードを見せない状態を作ってから実装させる。
「旧設計を無視して」と指示するのではなく、そもそも視野に入れない。
競走馬のシャドーマスクと同じ原理。
1. 問題: AI コーディング特有のアンチパターン
AI コーディングツールで設計変更をやると、毎回同じところで詰まる。8ヶ月これに付き合った。音楽プレイヤーの実装を統一しようとしたら、場所ごとに違う実装で置いてあって気づいて「？？？」だらけ。プロトタイプなのにデータの互換性とか API の後方互換とか意味ない、そもそもユーザーいないんだから、って何回言っても後方互換されている。念を押して設計変更して、念を押して実装させて、実装が済んだら前の設計のままだったこともある。
モデルを最新に変えても直らない。原因はモデルの性能ではなく、コンテキスト設計の構造問題だった。たぶん人類に貢献するはずなので共有する。
1.1 設計変更を AI に頼むとこうなる
やってほしいこと: 旧設計 → 新設計に完全置き換え
実際に起きること: 旧設計 + 新設計を「両立する実装」を頻繁に生成
具体的な症状:
- 無意味な後方互換レイヤーを追加（「旧 API も念のため残しておきます」）
- 二重実装が発生（新旧両方の処理が混在）
- 旧設計の残骸を放置（旧フィールド、旧クラスが残る）
- 「これは Breaking Change です」と過剰警告して怠業
これは人間のコーダーが陥るミスとは質が違う。
1.2 なぜ起きるか — 旧設計コンテキスト汚染
LLM はコンテキストウィンドウに存在する情報を「守るべき仕様」として認識する。旧コードや旧設計書が視野に入った瞬間、それを保持しようとする方向に推論が引っ張られる。
「旧設計は廃止です、無視してください」と指示しても効果が薄い。読んだ時点でコンテキストに入っている。 ピンクの象を想像するな、と言われても想像してしまうのと同じだ。LLM は「無視すべき情報」を処理するためにまず読む。読めば影響を受ける。
1.3 「新規は得意、改修は苦手」の正体
AI コーディングの「改修が苦手」問題の大部分はこれだと思う。新規プロジェクトでは旧設計が存在しないから汚染が起きない。既存プロジェクトの改修では、旧コードが常に視野に入っているから汚染が避けられない。
モデルの性能問題ではなく、コンテキスト設計の構造問題。 モデルを最新に変えても同じところで詰まる。
1.4 裏付けデータ
| データポイント | 出典 |
|---|---|
| エージェントのコンテキストの 60〜80% が無関係なデータで占められている | FlowHunt |
| 200人チームで月 $22,000 のトークン超過、うち 70% がレガシーコードベースでの作業 | AlterSquare |
| コンテキストルールの最適化だけで中央値コスト 21% 削減 | AlterSquare |
| スマート検索（200K）で幻覚率 12% / ブルートフォース（1M）で 28〜31% | Augment Code |
| コンテキスト適正化で 40〜60% のコスト削減 | Evalics |
| リトライ・エラーで基本コストの 20〜50% 増加 | Token Cost Trap |
特に注目すべきはレガシーコードベースがトークン超過の 70% を占めるというデータ。Yojo パターンが直接ターゲットにしている領域だ。
2. 解決策: Yojo パターン
2.1 養生とは
大きな改修工事をするとき、建築現場では「養生（ようじょう）」をする。ブルーシートを貼り、改修対象を囲い、改修対象外を保護し、作業範囲を明示して関係者以外の立ち入りを防ぐ。これなしに工事を始める現場はない。
AI コーディングでも同じことをする。設計変更の前に、AI が旧設計・旧コードに触れないよう視野を制限してから実装させる。施工の前にやる行為だから、養生。
名前は Yojo で統一した。海外の人にも打鍵してほしい。押しやすいし、なんか謎のマジックワードみたいでﾂﾖｲ。
2.2 シャドーマスクの原理
競走馬にはシャドーマスクという器具がある。自分の影や周囲の雑多な視覚情報に驚かないよう、視野を物理的に制限する。
- 馬は「影を無視しろ」と言われているのではない
- 最初から見えていない
AI コーダーも同じ。「旧設計を無視して」と指示するのではなく、最初から視野に入っていない状態で走らせる。
2.3 Yojo の 3 段階
建築の養生にも段階がある。AI コーディングでも同じだ。
| 段階 | やること | 触るもの |
|---|---|---|
| 調査 | 変更対象の設計書・指示書・コードを特定、マーキング | まだ何も書き換えない |
| 養生 | worktree を切り、文書層を新設計に書き換え + 旧コードにマーク | 文書層 + コード層 |
| 施工 | クリーンなコンテキストで AI を走らせる | AI がコードを変える |
養生段階では2 種類の操作を行う:
- 文書層の書き換え（遮断）: 設計書・指示書・ステータスドキュメントを新設計のみに書き直す。旧設計の記述は消す。AI は旧設計の存在を知らない状態になる
- コード層のマーキング: 書き換え対象の旧コードに「要改修？」と印をつける。AI がコードを読んだときに「これは変更対象かも」と判断できる状態にする
文書層で世界観を制御し、コード層で変更範囲を示す。
2.4 Before / After
Before（養生なし）:
開発者:「認証をセッション方式から JWT に変えて」
（旧コード・旧設計書が視野にある）
AI: 「承知しました。既存のセッション認証との互換性を保ちながら、
JWTも使えるよう両対応の実装を行います。
旧セッション API は deprecated フラグを立てて残します」
→ 二重実装・移行期間コードが大量生成
→ 「違う、全部置き換えて」と指示
→ リトライ（さらにトークン消費）
→ それでも残骸が残る
After（養生あり）:
開発者: worktree を切り、設計書を新設計のみに書き換え済み
「認証を JWT で実装して」
AI: 「承知しました。JWT 認証を実装します」
→ 一発で完了
2.5 なぜ「deprecated」では駄目なのか
# これは養生ではない
> 旧設計は廃止済みです。無視してください。
LLM は「無視すべき情報」を読んだ時点でコンテキストに取り込む。「無視して」と書いても、旧設計の存在を知った状態で推論する。
# これが養生
旧設計の記述がそもそも存在しない状態の文書。
AI は旧設計を知らない。
3. 実践: Claude Code での Yojo スキル
Yojo パターンを Claude Code のカスタムスキルとして実装した。/yojo <topic> で呼び出す。実戦で使って固まった知見を共有する。
3.1 設計判断
「所見を書く、処方は書かない」
旧コードへのマークには「なぜ変わるか」と「設計検討リンク」だけ書く。「こう直せ」は書かない。変更方針は実装時に変わりうるし、養生の時点で実装方法を決めるのは越権だ。
/**
* TODO [要改修？] D1: 認証方式がセッションから JWT に転換
* 現状: セッションベースの認証ミドルウェア
* 設計検討: docs/planning/auth-jwt-migration.md
*/
「要改修？」と疑問符を付ける。改修が必要かどうかも含めて未確定。目星にすぎない。
@deprecated を使わない理由
@deprecated は「もう使えない」を意味する。養生対象のコードはまだ動作中で、新方式の実装が来るまで動き続ける。TODO [要改修？] は「方針が変わった、いずれ手を入れる、詳細は設計書を見ろ」という目星だ。意味が違う。
掲示ファイルで一時情報を分離する
.claude/yojo/<topic>.md という一時ファイルを作り、判断の要約・マーク付きファイル一覧・設計検討リンク・改修完了条件を書く。設計書本体には恒久的な方針だけを書き、一時的な注意書きは埋め込まない。
3.2 施工後の片付け — 養生は撤去まで含む
養生は施工が終わったら撤去する。建築現場も同じだ。ブルーシートを貼りっぱなしにする現場はない。
改修が全部終わったら:
-
.claude/yojo/<topic>.mdを削除する - 設計書の改修中リンクを削除する
- コード中の
TODO [要改修？]マークを削除する（改修済みだけでなく、残存分も確認） - 片付けコミットを打つ
養生ファイルが残っている = 改修が未完了。これがシグナルになる。忘れ防止だ。片付けまで含めて養生。
3.3 チェックリスト
【文書層（遮断）】
□ 設計書から旧設計の記述を除去したか
□ 設計書を新設計のみにしたか（または worktree から除外したか）
□ ステータスドキュメントを更新したか
□ README 等に旧設計への言及がないか
【コード層（マーキング）】
□ 書き換え対象の旧コードにマークしたか
□ コード内コメントの旧設計言及を確認したか
【総合】
□ AI が見そうな場所を全部チェックしたか
3.4 スキル定義（共有）
以下は実際に使っているスキルの骨格だ。Claude Code の .claude/skills/ に置いて使う。プロジェクトに合わせて調整してほしい。
# /yojo <topic>
大規模な設計変更の実装に先立ち、旧設計を封印する。
実装者が旧方式に従う「隙」をなくし、新設計の指示書を整備することが目的。
> Yojo != 実装。新機能のコードは書かない。
> 「旧を封じ、新の指示書を整備する」だけ。
## 手順
### Step 1: Worktree の作成
設計書レベルの変更を含むため、本流と隔離する。
### Step 2: 封印範囲の確認（HIL）
調査ドキュメントを読み込み、封印対象リストをユーザーに提示。
ユーザーの明示的な承認を得てから次に進む。
### Step 3: 指示書・設計書の書き換え（シャドーマスク）
新パラダイムの方針を指示書に先に記述する。
旧設計の記述は削除する（「廃止済み」セクションも作らない）。
掲示ファイル .claude/yojo/<topic>.md を作成する。
### Step 4: コードへのマーク付与
旧方式のコードに TODO [要改修？] マークを付ける。
マークの書き方:
- 判断ID + 変更理由の一行要約
- 現状の説明
- 設計検討ドキュメントへのリンク
原則:
- 所見を書く、処方は書かない（「こう直せ」は書かない）
- ？を付ける（改修が必要かどうかも未確定）
- コードは削除しない
### Step 5: コミット・PR
各ステップでユーザー確認を取る（HIL）。
### Step 6: 改修完了時の片付け
1. .claude/yojo/<topic>.md を削除
2. 設計書の改修中リンクを削除
3. コード中の TODO [要改修？] マークを削除
4. 片付けコミット
養生ファイルが残っている = 改修が未完了。
4. トークン削減のポテンシャル
4.1 Yojo が効くメカニズム
養生は以下の浪費をまとめて消す:
- 旧コード読み込み — 読ませないので input トークンが減る
- 後方互換コード生成 — 生成されないので output トークンが減る
- 「違う、やり直し」ループ — 初回で正しい方向に行くのでリトライが減る
- リトライ時のコンテキスト膨張 — ループ自体が発生しない
設計変更タスクに限れば、これらが丸ごと消える。
4.2 市場規模
このアンチパターンが影響する範囲は小さくない。
| 指標 | 数値 | 出典 |
|---|---|---|
| AI コーディングツール市場（2025年） | $5〜7B | Mordor Intelligence, SNS Insider |
| AI コード生成市場（2032年予測） | $30B | Second Talent |
5. 既存パターンとの位置づけ
5.1 先行概念との比較
| 概念 | Yojo との関係 |
|---|---|
| Context Engineering（Karpathy 2025, Anthropic 2026） | 「コンテキストに必要な情報だけを精密に詰め込む」思想。Yojo はこの実践パターンの一つ |
@Deprecated |
コンパイラと人間向け。AI の読解動線を考慮していない |
.cursorignore |
ファイル単位でブロック。Yojo は文書層の書き換えで「世界観」を制御する |
| Strangler Fig | アーキテクチャ移行のマクロ戦略。ファイル単位の操作ではない |
| Sub-context Pattern（Pete Hodgson） | サブエージェントへの委譲で汚染を防ぐ。文書層の操作は含まない |
「設計書・指示書を事前に書き換えて AI の視野を制限する」という実践パターンは、2026 年 3 月時点で体系的な記述が見つからなかった。
5.2 Context Engineering の中での位置
Anthropic の Context Engineering は「どんな情報環境が最も信頼性の高い出力を生むか？」を問う。Yojo はその中でも**「入力から何を除くか」**に焦点を当てたパターン。
Context Engineering の問い: 何を見せるか？ + 何を見せないか？
Yojo の問い: 何を見せないか？
余談: 建築現場からもっと学べる
ソフトウェアの「アーキテクチャ」は建築から借りた言葉だが、借りてきたのは設計思想だけで、現場の施工知識はほとんど輸入されていない。
養生は建築現場では当たり前の工程だ。工事前に周囲を保護し、作業範囲を明示し、関係者以外の立ち入りを防ぐ。これなしに工事を始める現場はない。
AI コーディングは今、「養生なしで工事を始めている」状態にある。設計パターンやアーキテクチャの議論は盛んだが、施工前の準備工程という発想がまだない。建築が数千年かけて磨いてきた現場の知恵には、まだ輸入する価値のあるものが眠っていると思う。知らんけど。
参考文献
- Anthropic: Effective context engineering for AI agents
- Chroma Research: Context Rot
- Augment Code: Context Window Wars
- FlowHunt: Context Engineering for AI Agents
- Manus: Context Engineering for AI Agents
- Tacnode: Context Drift in AI Agents
- VentureBeat: Why AI coding agents aren't production-ready
- AlterSquare: AI Coding Tools in 2026
- Evalics: Token Limits and Context Size