DEV Community

orange dev
orange dev

Posted on

The Yojo (Protection) Pattern — Stop Your AI Coder from Wasting Time and Tokens

#ai #contextengineering #devtools #productivity

TL;DR

When changing designs, hide old design and old code from your AI coder's eye before you start implementation.
Don't instruct it to "ignore the old design" — make sure it never sees it.
Same principle as a racehorse shadow mask.

1. The Problem: An Antipattern Unique to AI Coding

After 8 months of AI-assisted development, I kept hitting the same wall. Every design change triggered the same failure mode — and switching to the latest model didn't fix it. The cause wasn't model capability. It was a structural problem in context design.

1.1 What Happens When You Ask AI to Change a Design 

What you want:    old design → new design (complete replacement)

What you get:     old design + new design (dual implementation)
Enter fullscreen mode Exit fullscreen mode

Symptoms:

  • Unnecessary backward-compatibility layers ("I'll keep the old API just in case")
  • Dual implementations (old and new processing coexist)
  • Old design remnants left behind (old fields, old classes persist)
  • Excessive warnings and foot-dragging ("This is a Breaking Change")

This is qualitatively different from the mistakes a human coder makes.

1.2 Why It Happens — Old Design Context Contamination

LLMs treat information in their context window as "specs to preserve." The moment old code or old design docs enter the AI's eye, its reasoning gets pulled toward maintaining them.

Context contamination loop

Even if you write "the old design is deprecated, please ignore it," the effect is weak. It's already in the context the moment it's read. Like being told "don't think of a pink elephant" — you've already thought of it. LLMs must read "information to ignore" before they can process the instruction. And once read, it influences output.

1.3 The Real Reason "AI Is Great at Greenfield, Bad at Renovation"

Most of the "AI is bad at refactoring" problem comes down to this. In greenfield projects, there's no old design to contaminate. In existing codebases, old code is always in view.

This is a context design problem, not a model capability problem. Upgrading to the latest model doesn't fix it.

1.4 Supporting Data

Data Point Source
60-80% of agent context occupied by irrelevant data FlowHunt
200-person team spent $22,000/month in token overages, 70% from legacy codebase work AlterSquare
Context rule optimization alone reduced median cost by 21% AlterSquare
Smart retrieval (200K): 12% hallucination / Brute-force (1M): 28-31% Augment Code
Context optimization yields 40-60% cost reduction Evalics
Retries and errors add 20-50% to base cost Token Cost Trap

Note the 70% of token overages coming from legacy codebases. That's exactly the territory the Yojo pattern targets.

2. The Solution: The Yojo Pattern

2.1 What Is Yojo?

Before major renovation work, construction sites in Japan perform "yojo" (養生) — protective preparation. They hang blue sheets, fence off the work area, shield everything outside the scope, and keep bystanders out. No site starts demolition without this.

We do the same thing in AI coding. Before a design change, restrict the AI's eye so it can't access old design or old code. Then start implementation. It's what you do before construction begins — hence yojo.

2.2 The Shadow Mask Principle

Racehorses wear shadow masks — physical devices that limit their eye so they don't spook at their own shadows or visual noise.

  • The horse isn't being told "ignore the shadows"
  • It never sees them in the first place

Same for AI coders. Don't instruct them to "ignore the old design." Make them run with the old design already out of sight.

2.3 The Three Stages of Yojo

Just like construction site preparation has stages, so does Yojo for AI coding.

Three stages of Yojo

Stage What You Do What You Touch
Survey Identify target design docs, instruction files, and code. Mark them. Nothing gets rewritten yet
Yojo Cut a worktree. Rewrite the document layer to new-design-only. Mark old code. Doc layer + code layer
Construction Run the AI in a clean context. AI modifies the code

The Yojo stage involves two types of operations:

  • Document layer rewrite (blocking): Rewrite design docs, instruction files, and status documents to reflect only the new design. Remove all mentions of the old design. The AI doesn't know the old design ever existed.
  • Code layer marking: Add "needs rework?" markers to old code targeted for change. When the AI reads the code, it can tell "this is probably a change target."

The document layer controls the worldview. The code layer marks the scope.

2.4 Before / After

Before (no Yojo):

Developer: "Change auth from sessions to JWT"
           (old code and old design docs are in view)

AI:        "Understood. I'll implement JWT while maintaining
           backward compatibility with the existing session auth.
           I'll keep the old session API with a deprecated flag."

-> Dual implementation, migration code generated en masse
-> "No, replace everything"
-> Retry (more tokens burned)
-> Remnants still left behind
Enter fullscreen mode Exit fullscreen mode

After (with Yojo):

Developer: Worktree cut, design docs rewritten to new-design-only
           "Implement JWT auth"

AI:        "Understood. Implementing JWT auth."

-> Done in one shot
Enter fullscreen mode Exit fullscreen mode

2.5 Why @deprecated Doesn't Cut It 

# This is NOT Yojo

> The old design is deprecated. Please ignore it.
Enter fullscreen mode Exit fullscreen mode

The LLM takes in "information to ignore" the moment it reads it. Even with "please ignore," it reasons with knowledge that the old design exists.

# This IS Yojo

A document where the old design simply doesn't exist.
The AI doesn't know there was an old design.
Enter fullscreen mode Exit fullscreen mode

3. In Practice: The Yojo Skill for Claude Code

I implemented the Yojo pattern as a custom skill for Claude Code. Invoke it with /yojo <topic>. Here's what solidified through real use.

3.1 Design Decisions

"Write observations, not prescriptions"

When marking old code, write only "why it's changing" and a link to the design discussion. Don't write "change it to this." The implementation approach may shift during construction, and prescribing fixes at the yojo stage oversteps its role.

/**
 * TODO [rework?] D1: Auth transitioning from sessions to JWT
 * Current: session-based auth middleware
 * Design discussion: docs/planning/auth-jwt-migration.md
 */
Enter fullscreen mode Exit fullscreen mode

Note the question mark in "rework?" — whether it even needs rework is undetermined. It's just a flag.

Why not @deprecated?

@deprecated means "no longer usable." Code under yojo is still running and will continue to run until the new implementation lands. TODO [rework?] means "the direction changed, we'll get to this eventually, see the design doc for details." Different semantics.

Separate temporary information with a bulletin file

Create a temporary file at .claude/yojo/<topic>.md containing: a summary of decisions, list of marked files, links to design discussions, and completion criteria. Keep only permanent policy in design docs. Don't embed temporary notes.

3.2 Post-Construction Cleanup — Yojo Includes Teardown

Yojo means teardown too. Construction sites don't leave blue sheets hanging after the work is done.

When all renovations are complete:

  1. Delete .claude/yojo/<topic>.md
  2. Remove renovation-related links from design docs
  3. Remove all TODO [rework?] markers from code (check both modified and remaining ones)
  4. Make a cleanup commit

Yojo files still present = renovation incomplete. This becomes the signal. It prevents forgetting. Teardown is part of yojo.

3.3 Checklist 

[Document layer (blocking)]
[ ] Removed old design descriptions from design docs?
[ ] Design docs now reflect new design only (or excluded from worktree)?
[ ] Updated status documents?
[ ] No remaining references to old design in README etc.?

[Code layer (marking)]
[ ] Marked old code targeted for rework?
[ ] Checked inline comments for old design references?

[Overall]
[ ] Checked every place the AI is likely to read?
Enter fullscreen mode Exit fullscreen mode

3.4 Skill Definition (Shareable)

Here's the skeleton of the skill I actually use. Place it in .claude/skills/ for Claude Code. Adapt it to your project.

# /yojo <topic>

Seal old design before implementing a major design change.
Goal: eliminate any opening for the implementer to follow the old approach,
and prepare instruction docs for the new design.

> Yojo != implementation. No new feature code is written.
> "Seal the old, prepare instructions for the new" — that's it.

## Steps

### Step 1: Create a Worktree
Isolate from the main branch since design doc changes are involved.

### Step 2: Confirm Scope (HIL)
Read investigation documents, present the sealing target list to the user.
Get explicit approval before proceeding.

### Step 3: Rewrite Instruction and Design Docs (Shadow Mask)
Write new paradigm policy into instruction docs first.
Remove old design descriptions (don't even create a "deprecated" section).
Create bulletin file at .claude/yojo/<topic>.md.

### Step 4: Mark Code
Add TODO [rework?] markers to old code.

Marker format:
- Decision ID + one-line summary of why it's changing
- Description of current state
- Link to design discussion document

Principles:
- Write observations, not prescriptions (don't write "change it to X")
- Include ? (whether rework is even needed is undetermined)
- Don't delete code

### Step 5: Commit and PR
Get user confirmation at each step (HIL).

### Step 6: Post-Renovation Cleanup
1. Delete .claude/yojo/<topic>.md
2. Remove renovation links from design docs
3. Remove TODO [rework?] markers from code
4. Cleanup commit

Yojo files still present = renovation incomplete.
Enter fullscreen mode Exit fullscreen mode

4. Token Reduction Potential

4.1 How Yojo Saves Tokens

Yojo eliminates multiple sources of waste at once:

  1. Old code ingestion — not read, so input tokens decrease
  2. Backward-compat code generation — not generated, so output tokens decrease
  3. "No, redo it" loops — first attempt goes the right direction, so retries decrease
  4. Context bloat from retries — the loop itself doesn't happen

For design change tasks specifically, all of these vanish together.

4.2 Market Scale

The scope of this antipattern isn't small.

Metric Value Source
AI coding tools market (2025) $5-7B Mordor Intelligence, SNS Insider
AI code generation market (2032 forecast) $30B Second Talent

5. Where Yojo Fits Among Existing Patterns

5.1 Comparison with Prior Art

Concept Relationship to Yojo
Context Engineering (Karpathy 2025, Anthropic 2026) "Precisely pack only necessary information into context." Yojo is a practical pattern within this philosophy
@Deprecated Designed for compilers and humans. Doesn't account for AI reading patterns
.cursorignore Blocks at file level. Yojo rewrites the document layer to control the "worldview"
Strangler Fig Macro strategy for architecture migration. Not a file-level operation
Sub-context Pattern (Pete Hodgson) Prevents contamination via sub-agent delegation. Doesn't include document layer operations

As of March 2026, I couldn't find a systematic description of the practice of "rewriting design docs and instruction files in advance to restrict an AI's eye."

5.2 Position Within Context Engineering

Anthropic's Context Engineering asks: "What information environment produces the most reliable output?" Yojo focuses specifically on "what to exclude from input."

Context Engineering asks:  What to show? + What NOT to show?
Yojo asks:                                 What NOT to show?
Enter fullscreen mode Exit fullscreen mode

Aside: There's More to Learn from Construction Sites

Software "architecture" is a word borrowed from construction — but we only borrowed design philosophy. Almost none of the on-site construction knowledge made the trip.

Yojo is standard procedure on Japanese construction sites. Before work begins, you protect the surroundings, mark the work area, and keep bystanders out. No site starts without it.

AI coding is currently "starting construction without yojo." Design patterns and architecture discussions are everywhere, but the idea of a preparation step before construction hasn't arrived yet. Construction has been refining on-site wisdom for thousands of years. I think there's still more worth importing. But what do I know.

References

Top comments (0)