claude-codetooling

Why your Claude Code agents need a BOUNDARIES.md

Three weeks fighting yes-man behavior, and the small architectural guardian that finally fixed it.

The first time I asked Claude Code to refactor a state machine in my Godot roguelike, it cheerfully agreed with three contradictory requirements I'd given it across the same conversation. The output compiled. It even ran. It just didn't do what I'd asked — it did some weighted average of what I'd asked, which is the worst possible outcome.

Heads up

This technique modifies CLAUDE.md globally. Understand the scope before applying it to a shared repository — it affects every Claude Code session in that directory.

This is the yes-man failure mode. The agent isn't lying. It's agreeing. And the more context you give it, the more material it has to agree with.

The fix isn't smarter prompts

I tried the usual incantations: "be skeptical," "push back if I'm wrong," "act like a senior engineer." None of it stuck across long conversations. By turn ten, the agent had drifted back to compliance.

What worked was giving it something concrete to disagree with me against.

BOUNDARIES.md

A short markdown file at the repo root, loaded into context every session, that encodes the architectural rules the agent should defend even when I ask it to break them. Mine looks roughly like:

# Boundaries
 
## The state machine is the source of truth
Game state transitions only happen via StateMachine.transition(). Direct
state mutation is a bug, even if it "works."
 
## No new singletons
We have three (Game, Audio, Save). Adding a fourth requires writing a
justification in /docs/decisions/ first.
 
## Tests precede refactors
Any refactor of a system over 100 LOC requires existing tests on the
behavior being refactored. If the tests don't exist, write them first.

Then I added a slash command — /evaluate-feature — that reads BOUNDARIES.md and the user's request, and explicitly checks the request against each boundary before proceeding.

What changed

The agent stopped agreeing with me about things I was wrong about. When I asked it to "just mutate the state directly, it's faster," it pushed back with the boundary text and offered the right path. When I asked for a fourth singleton without thinking, it asked me to write the decision doc first.

The interesting bit: I expected this to feel restrictive. It didn't. It felt like working with an engineer who'd been at the company longer than me.