Most developers install Claude Code or Cursor, try a few prompts, and walk away unimpressed. The agent edits the wrong files, ignores their conventions, and confidently invents a project structure that doesn't exist.
The tools aren't the problem. The missing config is.
An AI coding agent is like a brilliant contractor who's never seen your codebase. Drop them in with no brief and they'll guess. Give them a one-page brief — your stack, your rules, your commands, what not to touch — and they behave like someone who's worked on your team for a year.
That brief is the CLAUDE.md file (or .cursorrules for Cursor). Here's how to write one that actually works.
1. Tell it the architecture rules — as rules, not suggestions
The single biggest win. Don't describe your stack vaguely; give it hard rules it must follow:
## Architecture rules (follow exactly)
- Server Components by default. Only add "use client" when a component needs
state, effects, or browser APIs. Push client boundaries as far down as possible.
- Data fetching lives in Server Components or Route Handlers, never in useEffect.
- Mutations go through Server Actions, not ad-hoc API routes.
- No business logic in components — extract to lib/.
Notice these are imperative and specific. "Use best practices" does nothing. "Server Components by default, add 'use client' only for state/effects" changes the agent's output immediately.
2. Give it the commands — and make it run them
The agent can't verify its own work unless you tell it how:
## Commands
- Typecheck: `pnpm tsc --noEmit`
- Lint: `pnpm lint`
- Test: `pnpm test`
**Always run typecheck and lint before telling me a task is done.**
That last line is the one most people miss. Without it, the agent says "done" on code that doesn't compile. With it, it catches its own mistakes before you do.
3. Write a "What NOT to do" section
Negative constraints are underrated. They stop the most annoying failure modes:
## What NOT to do
- Don't add dependencies without asking — check if the capability already exists.
- Don't use `any` or `@ts-ignore` to make type errors go away — fix the type.
- Don't reformat files you didn't change.
4. Add a subagent for code review
Both Claude Code and Cursor support subagents — specialized roles you can invoke. A code-reviewer that reviews only your diff like a blunt senior engineer is the highest-leverage one:
---
name: code-reviewer
description: "Reviews a diff for bugs and quality. Use after writing code."
---
You review the git diff. Classify findings as 🔴 Bug / 🟡 Risk / 🔵 Cleanup.
Cite exact file:line. Skip style nits a formatter catches. Don't rubber-stamp.
Now "review my changes" gives you a focused review instead of generic praise.
Steal my configs (free)
I packaged working, drop-in versions of all of the above. Two CLAUDE.md templates (Next.js + Python/FastAPI) and the code-reviewer subagent are free on GitHub, MIT licensed:
👉 https://github.com/devloadout/awesome-claude-code-configs
Copy the one for your stack, edit three lines, restart your agent. That's the whole setup.
If you want the full set — 6 stacks (Go, Rust, monorepo too), 4 subagents, slash commands (/review, /ship, /test), hook recipes (auto-format, block committed secrets, run tests on stop), and copy-paste MCP setups — it's all in the complete kit (launch-week price).
What's in your CLAUDE.md? Drop your best rule in the comments — I'm collecting the good ones.
