Agent-Ready Codebases: Negative Rules, Precise Names, Directory READMEs

A developer on r/ClaudeAI detailed how they adapted their Android codebase after Claude Code repeatedly stuffed new features into a monolithic UserManager class (auth, sessions, profile, analytics). The key insight: the agent shows up cold every time, like a new hire on day one, with no memory of architectural decisions. The fix was explicit rules in a CLAUDE.md at the repo root.

Three patterns that made the biggest difference

1. Negative rules outperform positive ones

Instead of “follow good design,” the developer writes instructions like:

Do NOT touch BaseActivity – it’s shared across 12 features and breaks silently.

The agent is optimistic by default and takes the path of least resistance. Closing off dangerous paths explicitly stops bad decisions more effectively than vague guidance.

2. Names matter more than you think

A class named UserSessionExpiryHandler is a contract. Naming it just Handler is noise. The agent pattern-matches hard on names; good names reduce how much file-reading it needs to do. The developer recommends avoiding generic suffixes and making the purpose explicit in the name.

3. Each directory gets a README listing what does NOT belong there

Instead of “this folder is for UI,” the README says:

No business logic in presentation/

This negative framing “seems to land harder” on the agent, preventing more bad placements than positive guidance.

Practical rules for CLAUDE.md

• Keep files small. One class, one job.
• Create a new file rather than extend an old one.
• Don’t produce monoliths – split concerns early.

The developer reports that after applying these rules, the pattern of the agent re-reading a 600-line file three times in one session basically disappeared. They suspect token cost dropped significantly but haven’t instrumented it properly.

Who it's for

Developers using AI coding agents (Claude Code, Copilot, etc.) who want to reduce token waste and prevent agents from making bad architectural decisions.