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.
📖 Read the full source: r/ClaudeAI
👀 See Also
Agent Skills: Stop Writing SOPs, Start Building Boundary Systems
A Reddit post argues that adding more skills or tools to an AI agent makes it more fragile. The solution: minimum complete toolset, maximum boundary clarity.
Run a Second OpenCLAW Instance as a Safety Net
Deploy a basic OpenCLAW instance with key models to troubleshoot your main instance when it crashes. Works on Raspberry Pi, phone, or Clawx.
4 Files That Made Claude Code Write Safe Prod-Database Code
A developer shares four files—CLAUDE.md, MEMORY.md, framework.md, decisions/log.md—plus a Python bridge with idempotency keys and write guards that let Claude Code safely write to a Convex prod database.
Good AI-Assisted Development Happens at the Systems Level, Not the Task Level
A Reddit user explains how shifting from fixing AI agent output to designing constraints—like a linter rule that forces UI navigation—prevents entire classes of bugs permanently.