DEV Community: NongdyZ

Cursor Rules That Actually Improve AI Output (.mdc Project Rules)

NongdyZ — Sat, 27 Jun 2026 19:06:17 +0000

Most Cursor rules I see online are wish lists. "Write clean code." "Follow best practices." "Be concise." Cursor reads them, nods politely, and ships exactly the same code it would have without them.

The reason is simple: vague rules give the model nothing to act on. A rule only changes output if it's specific, enforceable, and scoped to when it matters. After rewriting my rules around those three properties, Cursor went from "code that works but I'd reject in review" to "code that passes review the first time" on most requests.

Here's what actually moved the needle, with real .mdc rules you can paste in.

The format: `.cursor/rules/*.mdc`, not `.cursorrules`

Cursor has moved to Project Rules stored as .mdc files in .cursor/rules/. The big advantage over the old single .cursorrules file is scoping: each rule has frontmatter that controls when it loads.

---
description: "Security rules for all code"
globs:
alwaysApply: true
---

Three frontmatter fields decide everything:

alwaysApply: true — the rule is in context on every request. Use for short, universal rules (security, error handling).
globs: "**/*.tsx" — the rule auto-attaches only when a matching file is in play. Use for stack-specific rules so your React rules don't pollute your Python context.
Neither set — the agent pulls the rule in when it judges it relevant, based on the description. Use for situational best-practice rules.

This scoping is the whole game. Loading every rule on every request dilutes the context and the model starts ignoring all of them. Scoped rules stay sharp because only the relevant ones are present.

Rule 1: A global rule the model can actually enforce

Keep your always-on rule short and written as concrete checks, not aspirations:

---
description: Global engineering rules — always apply
globs:
alwaysApply: true
---

- Validate and type all external input (API bodies, query params, env vars) at the boundary.
- Every function that can fail returns a typed error or throws — never returns null silently.
- No secrets in code. Read from env. Never log tokens, passwords, or full PII.
- When you change a function's signature, update every caller in the same change.
- Prefer deleting code over adding flags. The best fix removes complexity.

Notice there's no "write clean code." Every line is a check the model can apply to a specific diff. "Validate input at the boundary" produces a zod schema; "write clean code" produces nothing.

Rule 2: A stack rule scoped by glob

This one only loads when a TypeScript/React file is involved, so it never interferes with your backend or scripts:

---
description: React + TypeScript conventions
globs: "**/*.tsx, **/*.ts"
alwaysApply: false
---

- Components are typed function components. No `React.FC`. Props via an explicit interface.
- No `any`. Use `unknown` + a narrow, or define the type. If you truly can't, add a `// TODO: type` and explain.
- Follow the Rules of Hooks: no hooks in conditions or loops. Effects list every dependency they read.
- Data fetching goes through the existing query layer, not raw `fetch` inside components.
- Every interactive element is keyboard-accessible and has an accessible name (label, aria-label, or text).

The no any rule is the one people underrate. Left alone, Cursor reaches for any constantly because it's the path of least resistance. One scoped line removes most of it and forces it to think about the actual type.

Rule 3: A best-practice rule the agent loads on demand

Some rules only matter sometimes — like database access. Leave alwaysApply off and write a clear description so the agent pulls it in when it touches SQL:

---
description: Database and SQL safety — apply when writing queries or migrations
globs:
alwaysApply: false
---

- Always use parameterized queries / prepared statements. Never interpolate user input into SQL.
- Every query that can return many rows is paginated or explicitly bounded with LIMIT.
- Add an index before shipping a query that filters or joins on a non-indexed column — call it out.
- Migrations are reversible and never run automatically. Generate the file; let the human apply it.
- Watch for N+1: fetching a list then querying per item is a bug, not a style choice.

Because this rule isn't always loaded, it doesn't eat context on your CSS work. But the moment you ask Cursor to write a query, its description makes it relevant and it gets pulled in.

The before/after that convinced me

Same request — "add an endpoint to fetch a user's orders" — with and without the rules above.

Without rules:

app.get("/orders", async (req, res) => {
  const userId = req.query.userId;
  const orders = await db.query(`SELECT * FROM orders WHERE user_id = ${userId}`);
  res.json(orders);
});

SQL injection, no input validation, no pagination, SELECT *.

With the rules:

const Query = z.object({ userId: z.string().uuid(), page: z.coerce.number().min(1).default(1) });

app.get("/orders", async (req, res) => {
  const parsed = Query.safeParse(req.query);
  if (!parsed.success) return res.status(400).json({ error: parsed.error.flatten() });
  const { userId, page } = parsed.data;
  const limit = 50;
  const orders = await db.query(
    "SELECT id, total, status, created_at FROM orders WHERE user_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3",
    [userId, limit, (page - 1) * limit]
  );
  res.json({ orders, page });
});

Parameterized, validated, paginated, explicit columns. Same model, same prompt. The rules did that.

How to start without overdoing it

Don't write twenty rules on day one — you'll dilute the context and burn out maintaining them. Start with exactly three:

One short alwaysApply global rule (security + error handling).
One glob-scoped rule for your main stack.
One on-demand rule for whatever bites you most (SQL, accessibility, tests).

Live with those for a week, then add a rule only when you catch Cursor making the same mistake twice. Rules earn their place by preventing a real, repeated error.

If you want a full, tuned AI-coding setup

Rules are one half of the picture. The other half is giving your AI assistant a real workflow — focused review/test/refactor steps instead of one generalist doing everything. I packaged my complete setup as Claude Code Agent OS: 26 specialized subagents, 12 slash commands, ready-to-edit CLAUDE.md templates, MCP configs, and safety hooks — the same scoped, anti-fluff philosophy as the rules above, applied to the whole coding loop. It works alongside Cursor and any editor.

That said, the three-rule starter in this post costs nothing and will improve your very next Cursor session. Build those first, then decide if you want the full setup.

What's the one mistake Cursor keeps making in your codebase? Tell me in the comments and I'll suggest a rule for it.

How I Set Up Claude Code with 26 Production Subagents (CLAUDE.md, MCP, Hooks)

NongdyZ — Sat, 27 Jun 2026 13:54:39 +0000

When I first opened Claude Code on a real project, it felt like hiring a brilliant junior who had read every book but never shipped anything. It could write code fast, but it would forget my conventions halfway through a session, run a migration without asking, and "fix" a bug by deleting the failing test.

After a few weeks of tuning, it now behaves like a small senior team: it plans before it codes, reviews its own work, writes tests, and refuses to run anything destructive. The difference wasn't a better model. It was a better setup — a CLAUDE.md, a set of focused subagents, a couple of MCP servers, and two small hooks.

Here is exactly how that setup works, so you can build your own.

1. CLAUDE.md is the contract, not a wishlist

CLAUDE.md is the file Claude Code reads automatically at the start of every session. Most people treat it like a README. It works far better as a contract: short, specific, and written in always/never terms the agent can't misread.

The two rules that gave me the biggest jump in quality:

## Build & test (run these, do not guess)
- Install:  pnpm install
- Dev:      pnpm dev
- Test:     pnpm test -- --run
- Lint:     pnpm lint
- Typecheck: pnpm typecheck

## Always
- Run `pnpm typecheck && pnpm test -- --run` before saying a task is done.
- Use parameterized queries. Never build SQL with string concatenation.
- When you change a public function, update its tests in the same edit.

## Never
- Never run `git push`, `git reset --hard`, or any DB migration without me confirming.
- Never add a dependency to fix something a few lines of code can solve.
- Never disable a failing test to make the suite pass.

The reason the "Build & test" block matters: without the exact commands, the agent guesses them (npm test, yarn test, make test) and wastes turns failing. Give it the real commands once and it stops guessing.

Keep this file under ~50 lines. A long CLAUDE.md gets diluted in the context and the agent starts ignoring the middle of it. Be ruthless.

2. Subagents: split one generalist into many specialists

A single agent juggling "review this, also write tests, also refactor" produces mediocre output at every task. Subagents fix this by giving each job its own focused instructions and its own context window. In Claude Code these live in .claude/agents/*.md and you invoke them by name.

A subagent is just a Markdown file with frontmatter and a system prompt. Here's a real one — my code-reviewer:

---
name: code-reviewer
description: "Reviews a diff for bugs, security issues, and convention violations. Use after writing or changing code."
tools: Read, Grep, Bash
---

You are a senior code reviewer. Review ONLY the changed lines plus their immediate context.

Output exactly three sections:
1. **Blocking** — bugs, security holes, data loss risks. Each with file:line and a fix.
2. **Should fix** — correctness or clarity issues that aren't blocking.
3. **Nits** — style/naming. Keep this short.

Rules:
- If there are no blocking issues, say so on line one. Do not invent problems to look thorough.
- Check: injection, missing error handling, N+1 queries, unhandled null, race conditions.
- Quote the exact line you're flagging. No vague "consider improving error handling".

The two lines that make it useful are "Do not invent problems to look thorough" and "Quote the exact line." Without them, reviewers either rubber-stamp everything or generate a wall of generic advice. With them, you get actionable output.

I run a roster of focused specialists this way — a debugger that reproduces before it theorizes, a test-writer that targets edge cases instead of happy paths, a security-auditor that thinks in OWASP categories, an api-designer, a refactor-architect, and so on. Each one is a small file with a tight output format. The pattern is always the same: one job, one output format, one anti-fluff constraint.

3. MCP: give the agent eyes and memory

MCP (Model Context Protocol) servers are how Claude Code reaches outside the chat — the filesystem, a browser, a persistent memory store. You configure them in .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

The one I'd add first is sequential-thinking. It gives the agent a scratchpad to break a problem into steps before acting, which noticeably reduces the "confidently wrong" answers on multi-step tasks. A browser MCP (Playwright) is the second I reach for, because it lets the agent actually load the page and read the console instead of guessing why the UI broke.

One caution: MCP servers move fast and some get abandoned. Pin to maintained ones and check they still install before you rely on them.

4. Hooks: the safety net that runs without asking

Hooks are shell commands Claude Code runs on events you choose. Two are worth setting up on day one.

Auto-format on save — so you never review a diff full of whitespace noise:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "pnpm prettier --write \"$CLAUDE_FILE_PATHS\"" }]
      }
    ]
  }
}

Block dangerous commands — a pre-execution guard that refuses destructive shell calls even if the agent tries them:

#!/usr/bin/env bash
# .claude/hooks/guard.sh — exit non-zero to block the command
if echo "$CLAUDE_TOOL_INPUT" | grep -qE 'rm -rf /|git reset --hard|DROP TABLE'; then
  echo "Blocked: destructive command refused by guard hook." >&2
  exit 1
fi

This is the difference between trusting an autonomous agent and babysitting it. The model can be wrong; the hook is deterministic.

Putting it together: a feature, start to finish

With the setup above, my actual workflow on a new feature is short:

Ask the agent to plan — it writes the steps before touching code.
It scaffolds and implements, formatting on save via the hook.
I invoke code-reviewer on the diff, then test-writer for the gaps it found.
pnpm typecheck && pnpm test runs because CLAUDE.md says it must.
It drafts the commit and PR description.

The agent does the typing. I do the deciding. That's the whole point.

Want the whole thing as a drop-in?

Building all of this from scratch is a real time sink — the 26 subagents alone took me weeks of tuning to get the output formats right. If you'd rather skip that and drop a finished setup into any repo, I packaged my exact configuration as Claude Code Agent OS: 26 specialized subagents, 12 slash commands (/plan, /review, /test, /ship...), 5 ready-to-edit CLAUDE.md templates, the MCP configs, and the safety + format hooks (bash and PowerShell) — with a START HERE quickstart that gets you running in about 5 minutes.

But you don't need it to get value from this post. Start with a tight CLAUDE.md and one code-reviewer subagent today; that pair alone will change how your next commit feels.

If you build your own subagent roster, I'd genuinely like to see which specialists you find most useful — drop them in the comments.