There’s a skill in using AI coding assistants well that doesn’t get talked about enough: setting up the context files. Most developers get a tool like Cursor or Claude Code, have it work reasonably well out of the box, and never think about the fact that it knows almost nothing about their specific project unless you tell it.

A well-configured context file doesn’t just make the AI generate code that follows your conventions. It changes the failure modes. Without one, the assistant confidently generates code using library APIs it assumes exist, validation approaches that conflict with your existing patterns, and test structures that don’t match your testing strategy. With a good one, those specific mistakes get replaced by a narrower set of domain-specific mistakes that are much easier to catch.

Here’s how to actually write useful ones — not generic “follow clean code principles” fluff, but context that changes real behaviour.

What Goes in a Rules File (and What Doesn’t)

The most common mistake is writing rules that describe abstract qualities rather than concrete constraints. “Write clean, readable code” does absolutely nothing. “Never use class components; always use functional components with hooks” does something specific. “Use Zod for all input validation, never Yup” prevents a whole class of wrong suggestions.

The things worth including:

Architecture decisions that aren’t obvious from the code. If you’re using a repository pattern, say so. If API routes should never directly touch the database, write that. If you’ve chosen to handle errors with a Result type rather than throwing exceptions, document it. These are the decisions that a new developer joining the team would need to know — and the AI assistant is in exactly the same position as that new developer.

Libraries and tools that are the canonical choice in your project. “We use date-fns for date manipulation, not dayjs or moment. We use React Query for server state, not Redux Toolkit Query. We use Playwright for end-to-end tests, not Cypress.” These specifics prevent the assistant from suggesting alternatives it might prefer based on training data that predates your project choices.

What to avoid. Sometimes this is as important as what to do. “Don’t use any in TypeScript.” “Don’t generate comments that describe what code does — only add comments where the why isn’t obvious.” “Don’t add console.log statements to production code.”

Testing conventions. If you write tests in a particular structure (describe blocks, fixture patterns, what gets mocked vs tested with real dependencies), document it. Test generation is one of the high-value use cases for AI assistants, and it works much better when it knows your conventions.

Domain-specific vocabulary. If your codebase uses “order” and “line item” in specific ways, or if there’s a distinction between a “customer” and a “user” that matters in your domain model, make that explicit.

Cursor Rules: The New Format

Cursor now supports project rules via the .cursor/rules/ folder (previously a single .cursorrules file at the project root — both still work, but the folder approach lets you organise rules by topic).

Each rule file is a markdown file with some optional frontmatter:

---
description: "TypeScript conventions for this project"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

# TypeScript Conventions

- Use strict mode; tsconfig has strict: true
- Prefer `type` over `interface` for object shapes unless you need declaration merging
- Never use `any` — use `unknown` with type narrowing, or create a specific type
- Async functions should use `async/await`, not `.then()` chaining
- All API responses should be validated with Zod before use in the application

The globs field means this rule is only applied when working with files that match the pattern — so TypeScript rules apply to TypeScript files, test rules apply when editing test files, and so on. This keeps the context window clean rather than loading all rules for every file edit.

A few rules files that are worth creating for most projects:

  • project-overview.md (always applied): what the project is, the tech stack, folder structure
  • typescript.md (TypeScript files): type conventions, forbidden patterns
  • testing.md (test files): testing library, file structure, what to mock
  • api.md (API route files): request validation approach, error handling pattern, auth middleware

CLAUDE.md for Claude Code

Claude Code reads a CLAUDE.md file at the project root (and optionally in subdirectories). The format is plain markdown, no special frontmatter needed.

The key difference from Cursor rules: CLAUDE.md is also read by Claude when reasoning about the whole project, not just file edits. So it’s worth including higher-level project context that helps with planning and architecture questions, not just code generation.

What works well in a CLAUDE.md:

  • A short project description and the main technologies
  • Build and test commands (Claude Code will run these)
  • Architecture overview (key modules, their responsibilities, how they communicate)
  • Conventions for naming, file structure, patterns used
  • What NOT to do — common pitfalls or deliberate anti-patterns you want to avoid

One thing that doesn’t work: making it too long. CLAUDE.md goes into every conversation. Anything over about 300 lines starts adding noise rather than signal. Keep it tight.

GitHub Copilot Instructions

Copilot reads .github/copilot-instructions.md for repository-level instructions. The format is plain markdown, no special syntax.

Copilot instructions work best for things Copilot is actually generating in its suggestions: code style conventions, preferred patterns, and things to avoid. It’s less useful for architectural context that isn’t directly relevant to line-by-line suggestions.

One practical observation: Copilot instructions have a more immediate effect on suggestion quality than Cursor or Claude Code rules, because suggestions in Copilot happen faster and at a smaller granularity. Even a short instructions file (30-50 lines) covering your main conventions will noticeably shift suggestion quality.

How to Actually Write Them

Start by looking at the last two weeks of code review comments on your team’s PRs. Anything that came up repeatedly — “don’t do it this way, do it that way” — is a candidate for a rule. Those are the real patterns your codebase enforces that an outside observer wouldn’t know.

Then look at what the AI assistant gets wrong most often in your project. If it keeps suggesting approaches you immediately reject, there’s a rule to write there.

Keep them version-controlled, treat changes to them like any other code change, and review them periodically as your project’s conventions evolve. A stale rules file that reflects decisions you’ve moved on from is worse than no rules file — you’ll spend more time correcting the AI than you save by using it.