Mastering System Instructions: Fine-Tuning Claude Code & Cursor for Custom Tech Stacks
If you've spent any time pair programming with AI tools like Claude Code or Cursor, you've probably noticed that they have a default coding style. They love writing boilerplate code, using massive Tailwind utility strings, and introducing external npm packages for simple operations that could easily be solved with vanilla JavaScript.
While these defaults work fine for simple prototypes, they become a major liability when you are working on a mature product. In a production environment, you have specific architectural guidelines, a custom CSS variables design system, and strict performance targets.
If you want the AI to generate code that fits your codebase seamlessly, you must define the constraints at the system level using Project Rules.
---
1. The Paradigm Shift: From Legacy .cursorrules to .cursor/rules/.mdc
Historically, developers configured project instructions by dropping a single, monolithic .cursorrules file into the root of their repository. While this worked, it quickly ran into size limits. If you had rules for database migrations, CSS variables, unit testing, and API routes all in one file, the editor had to attach that entire text block to every single prompt. This wasted valuable context space and caused the model to cross-reference conflicting rules.
Modern AI code editors have shifted to a directory-based scoping pattern:
Legacy Location: Root-level .cursorrules file (plain text or JSON).
Modern Standard: Rules are split into modular Markdown files inside the .cursor/rules/ directory, ending with the .mdc extension.
Key Advantage: Each .mdc file includes metadata frontmatter that controls scoping. This means rules for database schema design are only loaded when you are editing database files, and styling rules are only loaded when you edit CSS files.
---
2. Anatomy of a Production .mdc Rule File
Each rule inside .cursor/rules/ is a Markdown file with a YAML frontmatter header. The header contains critical parameters:
description: Explains to the IDE when this rule is relevant.
globs: A list of glob matching patterns. The IDE will automatically load this rule if the user is editing or has opened a file matching these patterns.
* alwaysApply: If set to true, this rule will be included in the context for all prompts, regardless of the active file.
Here is a production-grade rule file targeting component styling consistency:
```markdown ---
description: "Rules for styling React components using CSS Modules" globs: "app/*/.module.css, app/*/.js, app/*/.jsx" alwaysApply: false ---
Styling Consistency & CSS Modules
When writing styling components or styling CSS files, you MUST adhere to the Vibe Coding design system.
Design Tokens (CSS Variables)
Do not write hex codes or arbitrary HSL values. You must use the variables defined inapp/globals.css:
- Background Color:
var(--color-bg-primary) - Card Background:
var(--color-bg-secondary) - Accent Glow:
var(--color-accent-glow) - Primary Accent:
var(--color-accent-primary-hover) - Borders:
var(--color-border-primary)
Class Naming & CSS Modules
- All styling rules must be written in camelCase within
.module.cssfiles (e.g.,.cardWrapper, not.card-wrapper). - Always import styles in your React components as:
- Apply classes using:
- Do NOT install or use TailwindCSS unless explicitly instructed.
---
3. Best Practices for Authoring Rules
To make your system instructions effective:
- Be Declatative and Direct: AI models respond best to firm directives. Use words like
MUST, REQUIRED, and Do NOT rather than passive recommendations.
Give Examples: The most reliable way to show the model how to write code is to provide a short code block of the "correct" approach vs the "incorrect" approach.
Set Up Clean Scopes: Keep your globs tight. For example, if you have a database rule, set globs: "lib/db.js, app/api/*/.js". Loading database instructions while the user is tweaking a landing page only wastes context tokens and degrades performance.
Automate Error Handling Rules: Add a rule requiring that all POST/PUT API handlers implement validation checks and return clean, structured JSON errors ( { error: "Detailed message" }) with appropriate HTTP status codes.
---
4. Reinforcing System Instructions in Your Prompts
Even with
.mdc` rules active, LLMs can occasionally drift during long chat sessions. To maintain absolute alignment, prefix complex prompts with a reference hook:
"Referring to our styling rules, add a billing settings modal to this page..."
This triggers the editor to reload the relevant rules files, ensuring the AI writes standard, production-ready code that matches your style guide exactly on the first try.
Ready to Stop Typing Code & Start Directing AI Systems?
Join 5,000+ developers building real production software with AI. Learn the 7-Stage Vibe Coding OS, harness engineering, and earn your verified Build DNA Certificate.