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
Using Dictation Tools for More Effective AI Agent Instructions
A developer found that switching from typed to spoken instructions for OpenClaw improved output quality by providing more natural, detailed context, using SaySo.ai as a dictation tool.
Compress CLAUDE.md Files to Reduce System Prompt Bloat in Claude Code
A technique for compressing CLAUDE.md files by removing human-readable formatting like markdown headers and prose, replacing them with compact notation like pipe-delimited lists, achieving 60-70% character reduction while maintaining the same information for Claude.
Eight Prompting Techniques That Improve Claude Output Quality
A Reddit user shares eight specific prompting techniques that consistently improved their Claude output quality, including commands like "Think through every layer before answering" and "Find the 20% of actions that drive 80% of results."
Auth 400 Error Fix: Using Python's mnemonic Package to Avoid BIP39 Filter Triggers
A Reddit user identified that Anthropic's content filter triggers a 400 error when AI agents attempt to write the full BIP39 wordlist (2048 standardized English words) into Python code. The solution is to use the mnemonic Python package instead, which contains the wordlist internally.