Claude Code best practices: a year of production rules, distilled
Not another generic tips list. Four rules that survived a year of running Claude Code on real client codebases, each one with the reason it exists.
After a year of running Claude Code on real client codebases, what's left is not a generic tips list, it's four rules: keep CLAUDE.md short and scoped, never trust the agent's own claim that a build or typecheck passed, never leave payment, migration, or secret work to the agent alone, and write the plan down before you hand off the task. Each rule below carries the reason behind it: either something broke, or something measurably improved.
TL;DR
Four rules carried us through a year of production work: keep CLAUDE.md short and scoped, run the build and typecheck yourself instead of trusting the agent's "done", never leave payment, migration, or secret work to the agent alone, and write the plan down before the task starts. Each section below shows how we apply it and why it exists.
This is the rules reference for the workflow we described in how we actually use Claude Code. That piece walks through the flow end to end; this one is just the rules and the reasoning behind each.
Rule 1: CLAUDE.md is the single source, but it doesn't hold everything
CLAUDE.md is the one file Claude Code reads at the start of every session, so its job is to carry what genuinely changes behavior: the project in one line, the stack that doesn't change, the banned tools and patterns, the order work moves through, and which specialized agent gets called for what. What it should not carry is anything that reads like a wiki page, any credential or key, or any decision that shifts week to week. A file that grows past a page stops getting fully read, which defeats the point of having one.
Measured: our own CLAUDE.md, this repo
Command: wc -l .claude/CLAUDE.md && grep -c '^##' .claude/CLAUDE.md, run against this site's own repo while writing this article.
71
lines total, including headers and whitespace
9
section headers, none longer than a few lines each
Nine sections in seventy-one lines is the actual ceiling we work under: project, team, stack, language, voice, workflow, agent call signs, current focus, goal. Anything that would make this longer gets a pointer to another file instead of a paragraph here.
If you're starting from a blank repo, our CLAUDE.md generator produces a scoped starting file in this same shape rather than a blank page you have to structure yourself.
Rule 2: before the agent says "done," run the command yourself
An agent reporting that a build succeeded or a test suite passed is a claim, not a verification. The rule is simple and absolute: nothing merges until a human, or a CI step a human configured, has actually run the build and the typecheck and watched it exit clean. This catches the failure mode that costs the most time, an agent that edited a type definition, broke three unrelated files, and described all of it as a successful change.
Measured
Command: npx tsc --noEmit, run against this site's own repo while writing this article.
Finished in 3.2 seconds with zero errors. This article's own build went through the same gate it's describing, not as a figure of speech, as the actual command that ran before the PR opened.
Rule 3: payment, migration, and secrets never go to the agent alone
The line we draw is about reversibility, not difficulty. Writing a migration, drafting a refactor, or reviewing a diff is work an agent does well and we let it run unsupervised. Running that migration against a production database, touching a live payment flow, or rotating a credential is work that gets a human in the loop every time, because the failure mode has no undo. Two real, public examples of what happens when that boundary isn't drawn: Cursor's agent deleting a production database in nine seconds, and the same failure pattern in Replit's agent. Neither was our client, but both are exactly the reason this rule exists before it gets tested on one.
The agent runs this alone
Never without a human
Rule 4: write the plan down before the task starts
A task handed to an agent without a written plan spends its first pass figuring out what you meant instead of doing the work. The fix costs almost nothing: a short written brief, the goal, the files involved, what counts as done, before the agent writes a line. The expensive version of skipping this isn't a failed task, it's a plausible-looking one that solved the wrong problem and still has to be caught in review.
What a year of this actually prevented
None of the incidents linked above happened on our own work, and that's the point of writing the rule down before it gets tested on a client's production database instead of in an article. The pattern is consistent across every public case of an agent deleting or corrupting live data: the agent had standing access to something irreversible and no human checkpoint sat between a prompt and that action. Rule 3 exists specifically to keep that checkpoint in place regardless of how much the agent's track record on smaller tasks earns it.
Where this list stops being enough
These four rules assume the team actually reads CLAUDE.md, if nobody opens it, it's a rule on paper, not a rule in practice. A single file also stops scaling past a certain repo size, a large monorepo needs it split per package rather than one file trying to cover everything. And none of this replaces a human architecture review for a genuinely new decision, a new service, a schema change, a new third-party dependency, those still need a person who isn't optimizing for "does this compile." These rules are written for Claude Code specifically; if your team runs a different agent, the principles carry over but the file format and triggers don't, see our Cursor vs Claude Code vs Windsurf comparison for where the mechanics actually differ.
If your team has taken over a codebase where none of these four rules were in place, the pattern we see is familiar: a demo that worked, a CLAUDE.md that never existed or was never read, and a production incident that forced the question. Our AI project completion service exists for exactly that handoff point.
Frequently asked questions
Where should CLAUDE.md actually live?
At the repository root as .claude/CLAUDE.md. Claude Code reads it automatically at the start of every session in that repo, no extra configuration needed.
Do these rules apply if my team uses a different coding agent?
The principles do, verify before you trust, never delegate irreversible actions, plan before you prompt. The file format and the exact triggers differ by agent.
Is writing the plan myself better than having the agent draft one first?
Either works, the requirement is that a human reviews and approves the final plan before work starts, not that a human typed every word of it.
Is force-push ever acceptable?
On your own unshared feature branch, occasionally, with you doing it deliberately. On a shared branch, no, there's no clean way to undo a rewritten history other people have already based work on.
Do these rules matter for a small solo project too?
The payment, migration, and secret rule doesn't scale down. A solo project's database is exactly as unrecoverable as a large team's once it's gone.