Yojo（養生）パターン — AI コーダーにシャドーマスクをつける ～時間とトークンの浪費をストップ～

TL;DR

設計変更のとき、AI コーダーに旧設計・旧コードを見せない状態を作ってから実装させる。
「旧設計を無視して」と指示するのではなく、そもそも視野に入れない。
競走馬のシャドーマスクと同じ原理。

1. 問題: AI コーディング特有のアンチパターン

AI コーディングツールで設計変更をやると、毎回同じところで詰まる。8ヶ月これに付き合った。音楽プレイヤーの実装を統一しようとしたら、場所ごとに違う実装で置いてあって気づいて「？？？」だらけ。プロトタイプなのにデータの互換性とか API の後方互換とか意味ない、そもそもユーザーいないんだから、って何回言っても後方互換されている。念を押して設計変更して、念を押して実装させて、実装が済んだら前の設計のままだったこともある。

モデルを最新に変えても直らない。原因はモデルの性能ではなく、コンテキスト設計の構造問題だった。たぶん人類に貢献するはずなので共有する。

1.1 設計変更を AI に頼むとこうなる

やってほしいこと:  旧設計 → 新設計に完全置き換え

実際に起きること:  旧設計 + 新設計を「両立する実装」を頻繁に生成

具体的な症状:

• 無意味な後方互換レイヤーを追加（「旧 API も念のため残しておきます」）
• 二重実装が発生（新旧両方の処理が混在）
• 旧設計の残骸を放置（旧フィールド、旧クラスが残る）
• 「これは Breaking Change です」と過剰警告して怠業

これは人間のコーダーが陥るミスとは質が違う。

1.2 なぜ起きるか — 旧設計コンテキスト汚染

LLM はコンテキストウィンドウに存在する情報を「守るべき仕様」として認識する。旧コードや旧設計書が視野に入った瞬間、それを保持しようとする方向に推論が引っ張られる。

「旧設計は廃止です、無視してください」と指示しても効果が薄い。読んだ時点でコンテキストに入っている。 ピンクの象を想像するな、と言われても想像してしまうのと同じだ。LLM は「無視すべき情報」を処理するためにまず読む。読めば影響を受ける。

1.3 「新規は得意、改修は苦手」の正体

AI コーディングの「改修が苦手」問題の大部分はこれだと思う。新規プロジェクトでは旧設計が存在しないから汚染が起きない。既存プロジェクトの改修では、旧コードが常に視野に入っているから汚染が避けられない。

モデルの性能問題ではなく、コンテキスト設計の構造問題。 モデルを最新に変えても同じところで詰まる。

1.4 裏付けデータ

特に注目すべきはレガシーコードベースがトークン超過の 70% を占めるというデータ。Yojo パターンが直接ターゲットにしている領域だ。

2. 解決策: Yojo パターン

2.1 養生とは

大きな改修工事をするとき、建築現場では「養生（ようじょう）」をする。ブルーシートを貼り、改修対象を囲い、改修対象外を保護し、作業範囲を明示して関係者以外の立ち入りを防ぐ。これなしに工事を始める現場はない。

AI コーディングでも同じことをする。設計変更の前に、AI が旧設計・旧コードに触れないよう視野を制限してから実装させる。施工の前にやる行為だから、養生。

名前は Yojo で統一した。海外の人にも打鍵してほしい。押しやすいし、なんか謎のマジックワードみたいでﾂﾖｲ。

2.2 シャドーマスクの原理

競走馬にはシャドーマスクという器具がある。自分の影や周囲の雑多な視覚情報に驚かないよう、視野を物理的に制限する。

• 馬は「影を無視しろ」と言われているのではない
• 最初から見えていない

AI コーダーも同じ。「旧設計を無視して」と指示するのではなく、最初から視野に入っていない状態で走らせる。

2.3 Yojo の 3 段階

建築の養生にも段階がある。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 施工後の片付け — 養生は撤去まで含む

養生は施工が終わったら撤去する。建築現場も同じだ。ブルーシートを貼りっぱなしにする現場はない。

改修が全部終わったら:

1. .claude/yojo/<topic>.md を削除する
2. 設計書の改修中リンクを削除する
3. コード中の TODO [要改修？] マークを削除する（改修済みだけでなく、残存分も確認）
4. 片付けコミットを打つ

養生ファイルが残っている = 改修が未完了。これがシグナルになる。忘れ防止だ。片付けまで含めて養生。

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 が効くメカニズム

養生は以下の浪費をまとめて消す:

1. 旧コード読み込み — 読ませないので input トークンが減る
2. 後方互換コード生成 — 生成されないので output トークンが減る
3. 「違う、やり直し」ループ — 初回で正しい方向に行くのでリトライが減る
4. リトライ時のコンテキスト膨張 — ループ自体が発生しない

設計変更タスクに限れば、これらが丸ごと消える。

4.2 市場規模

このアンチパターンが影響する範囲は小さくない。

5. 既存パターンとの位置づけ

5.1 先行概念との比較

「設計書・指示書を事前に書き換えて 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