Blog / / 4 min read
Four small Cursor rules I ship with every theme
Scoped rules stop AI tools from refactoring things you didn't ask about, inventing dependencies, and breaking content schemas. Here are the four rules in every Lexington theme's .cursor/rules folder, and the thinking behind each.
The worst AI edits aren’t the ones that fail. They’re the ones that succeed at something you didn’t ask for.
You ask for a new page, and the diff also renames two props, “cleans up” an import you were using, and adds a dependency for something the project already does. Each change is defensible in isolation. Together they turn a two-minute review into twenty.
Cursor has a fix for this: scoped rules in .cursor/rules/, small Markdown files that apply automatically based on what you’re touching. Every Lexington theme ships four of them. Here’s what they are and why each exists.
1. The global rule: how to behave
This one always applies, and it’s mostly about restraint:
- Use the
@/import alias, not relative path chains. - Prefer existing patterns over new abstractions.
- Keep diffs minimal. No drive-by refactors, no invented dependencies.
That last line pays for the whole file. “No drive-by refactors” is the difference between reviewing the change you asked for and untangling three changes you didn’t.
2. The config rule: how the pieces fit
Applies when the agent touches configuration. It explains how astro.config.mjs, tsconfig.json, and the Tailwind setup fit together, so a “simple config tweak” doesn’t quietly break the path alias or the content layer.
Config files are where agents do the most damage per line, because every line affects everything downstream. A few sentences of context here prevent the expensive category of mistake.
3. The content rule: schemas are law
Applies when you work in src/content/. It spells out the collection schemas and frontmatter rules: which fields are required, how image fields work, what the dates look like.
Without it, an agent writing a blog post invents plausible frontmatter, and plausible is not valid. The build fails, or worse, it doesn’t and the page renders wrong. With the rule, “add a blog post about X” produces a file that passes the schema first try.
4. The pages rule: routing and layouts
Applies in src/pages/. Which layout wraps what, how dynamic routes connect to collections, where a new page should actually go. This is the difference between a new page that inherits the site’s head tags, SEO defaults, and navigation, and one that half-works because it skipped the layout.
What it changes in practice
Without the rules, a safe prompt has to carry all the caveats yourself:
“Add a testimonials section to the homepage. Use the existing components, don’t add any dependencies, use the @/ alias for imports, don’t change anything else, and follow the frontmatter format if you touch content.”
With the rules in the repo, the same request is just:
“Add a testimonials section to the homepage.”
The caveats didn’t disappear. They moved into files that load automatically, on every prompt, whether you remembered them or not. That’s the whole trick: you write the judgment down once instead of retyping it forever.
Why four small files instead of one big one
Scope is the point. The content rule only loads when you’re in src/content/, so it never dilutes the context of an edit that has nothing to do with content. Big monolithic instruction files get skimmed; small scoped ones land exactly when they’re relevant.
There’s a maintenance benefit too. When I change how a theme’s content layer works, I update one small file, not a paragraph buried in a general document.
And the CMS ports are covered separately: Sanity and EmDash variants have their own rules adapted to that stack, including the adapter layer and admin workflow, because rules written for plain Astro would be wrong there.
The pattern, if you want to steal it
Nothing here is specific to my themes. The recipe:
- One always-on rule about behavior: minimal diffs, existing patterns, no invented dependencies.
- One rule per dangerous area of your codebase, scoped to the files it protects, saying what’s fragile and what’s law.
Write them once, and every AI session starts with the judgment you’d otherwise repeat in every prompt.
The rules are one of three context files in every theme, next to AGENTS.md, the project brief, and a design skill that keeps generated pages on-brand. I’ve written about the other two on this blog, and together they’re why a one-line prompt on a Lexington theme produces something that still looks like the theme.
If you want to set up all three on your own codebase in an afternoon, I wrote a guide with the full walkthrough and fill-in templates for every file: Making Your Codebase AI-Ready.
/Michael Andreuzza