4 Rules in My CLAUDE.md That Fixed Bad Claude Code Sessions

Claude Code is an incredible productivity accelerator for about the first week. Then, inevitably, the honeymoon phase ends. It refactors a file you never asked it to touch, over-engineers a simple five-line bug fix into a complex architecture, or proudly announces that a task is done when it clearly does not work.

If you use AI coding assistants daily on client projects, you will recognize these frustrating moments immediately. Almost every single one of these failure modes traces back to a foundational truth of LLM behavior: the agent only knows what is in its context window right now. It does not remember what it learned yesterday, and it has never read your team's unwritten conventions. If a rule or constraint is not explicitly in the context, it simply does not exist.

Therefore, your job as a developer using tools powered by advanced models like Claude 3.5 Sonnet or OpenAI o3 is not just "prompting"—it is curation. It is the art of deciding what goes into the context window and what stays out.

The cheapest, highest-impact place to start this curation is your global ~/.claude/CLAUDE.md file. By routing your instructions through a well-crafted configuration, you can drastically reduce hallucinations and erratic behavior. Here are the four rules I put in my global configuration that completely transformed my workflow.

1. No Silent Assumptions: State Assumptions and Tradeoffs

The first and most dangerous trap for an autonomous coding agent is the confident wrong turn. Left to its own devices, an LLM will often write 300 lines of code based on a hidden assumption that you would have corrected in five seconds if you had known about it.

• The Rule: No silent assumptions. State what you are assuming before writing code, and explicitly surface architectural tradeoffs.
• Why it matters: It stops the agent from building complex logic on top of flawed premises. When you integrate high-performance LLM APIs via aggregators like n1n.ai, latency and token efficiency matter. Eliminating wasted iterations caused by unstated assumptions saves both time and API costs.

2. Minimum Viable Code: Zero Speculative Features

AI models love to show off. Ask them to solve a minor bug, and they will often rewrite your entire utility library, add speculative configuration options that nobody asked for, and build generic interfaces for single-use code.

• The Rule: Write the minimum code that solves the problem. No speculative features. No abstractions for single-use code. If a senior engineer would call it overcomplicated, simplify it immediately.
• Why it matters: This single rule completely eliminates the classic "enterprise" reflex where simple scripts bloat into unmaintainable class hierarchies.

3. Surgical Precision: Touch Only What You Must

One of the most annoying habits of AI coding tools is their propensity to "clean up" code adjacent to the actual bug, introducing subtle syntax errors or style mismatches in files you didn't want modified.

• The Rule: Touch only what you must. Do not "improve" adjacent code, comments, or formatting. Do not refactor what isn't broken. Strictly match existing project style.
• Why it matters: This rule is the secret behind making code reviews twice as fast. When you open a pull request, the git diff is finally just the task itself—no random whitespace changes or unsolicited renamings.

4. Define Success Criteria and Loop Until Verified

Too many developers treat AI prompts as fire-and-forget commands. They ask for a feature, read the generated output, and manually test it.

• The Rule: Define success criteria upfront. Loop until verified.
• Why it matters: This shifts the paradigm from "Write the code" to "Make this test pass, then verify it in the browser or terminal." It prevents the model from declaring premature victory when a unit test is still failing or an endpoint is throwing a 500 error.

Moving Beyond Wishes: Writing Actionable Constraints

Most CLAUDE.md files fail because they are full of passive wishes rather than active constraints. Writing lines like "Write clean, maintainable code following best practices" is entirely useless. The model already assumes it always writes clean code; that sentence changes nothing about its generation patterns.

An effective constraint must be specific and checkable—both by you and by the model. Furthermore, adding a reason behind the constraint makes it exponentially stronger. When you provide a rationale, the agent can apply the rule to edge cases you never explicitly listed, rather than dropping the constraint under context pressure.

Managing Context Budgets and Gotchas

Every line in your CLAUDE.md file exacts a toll; it is paid for in every single session's token budget. Keep your global configuration lean (< 60 lines) and project-specific instructions focused (< 150 lines).

If you have procedural instructions—such as release checklists or deployment steps—do not put them in CLAUDE.md. They belong in custom skills or scripts that load only when needed. For instance, when routing complex multi-step workflows through robust infrastructure like n1n.ai, separating static rules from dynamic procedures keeps your context window optimized for raw problem-solving.

Finally, maintain a Gotchas section in your project-level file. Whenever the agent makes a mistake that a reasonable human newcomer would also make, add a one-line entry to this section. Over months, this becomes the most valuable living documentation in your entire repository.

Get a free API key at n1n.ai