These files act as persistent instructions. Unlike a chat prompt that applies to one request, a rules file is loaded automatically every time the agent starts working. It tells the agent about your coding standards, architecture decisions, naming conventions, and constraints before you even type a task.
The format is usually simple. Most agents expect a markdown file or a plain text file with structured sections. There is no required schema. You write what matters for your project, and the agent reads it as context alongside your code.
What to include in a rules file
Coding standards
Language conventions, naming patterns, formatting rules. Tell the agent whether you use camelCase or snake_case, tabs or spaces, and which style guide you follow.
Architecture constraints
Which patterns to use, which to avoid, folder structure. If your project follows a specific architecture like hexagonal or feature-based modules, state it here.
File naming conventions
How to name files, components, tests, modules. Consistent naming is one of the easiest wins a rules file can provide.
Forbidden patterns
What the agent should never do: specific anti-patterns, deprecated APIs, libraries you have banned. Explicit prohibitions are often more useful than general advice.
Testing requirements
Test file locations, framework preferences, coverage expectations. Tell the agent where tests live and how you expect them to be structured.
Context hints
Which files are most important, entry points, key dependencies. Help the agent find the right starting point instead of guessing from the file tree.
Rules files are not a security boundary
A rules file is guidance, not enforcement. The agent reads it as context, but nothing prevents the agent from ignoring a rule or interpreting it differently than you intended. If your rules file says "never delete files," the agent might still delete files if it decides that is the best way to complete the task.
Prompt injection makes this worse. If a malicious dependency, README, or code comment contains instructions that override your rules file, the agent may follow those injected instructions instead. Rules files have no privilege over other text the agent reads. They are just another part of the context window.
The practical consequence is clear: do not rely on rules files to prevent dangerous behavior. Use diff review to catch unwanted changes before they land. Use sandboxing to limit what the agent can execute. Use automated checks to verify that output meets your standards. Rules files improve the average quality of agent output, but they are not a control mechanism.
Portable instructions vs vendor-locked formats
Every AI coding tool has its own convention. Claude Code reads CLAUDE.md. Cursor reads .cursorrules. Windsurf reads .windsurfrules. If your team uses multiple tools, maintaining separate files for each one becomes a maintenance burden that grows with every new tool.
A more portable approach is to write your project instructions in a generic markdown file — something like PROJECT_RULES.md or CODING_GUIDELINES.md — and then have each vendor-specific file reference or include it. This way, the core instructions live in one place and each tool-specific file is a thin wrapper.
The advantage of portability is not just convenience. It forces you to write instructions that are clear to any agent, not just one vendor's model. Instructions that depend on a specific model's quirks tend to be fragile. Instructions that describe your project clearly tend to work well across tools and across model updates.
Common mistakes with rules files
| Mistake | Problem | Fix |
|---|---|---|
| Rules file too long | Dilutes important instructions, wastes tokens | Keep under 500 lines, prioritize what matters most |
| Contradictory rules | Agent receives conflicting instructions | Review rules file for consistency |
| Over-specific formatting | Rules fight the model's natural patterns | Describe intent, not exact formatting |
| Security instructions in rules | Rules cannot enforce security — agent can ignore them | Use diff review and automated checks instead |
| No rules file at all | Agent guesses your conventions | Start with a minimal rules file and iterate |
A practical rules file template
Below is a structured template you can adapt for your project. Copy the sections that apply, remove what does not, and keep it concise.
# Project: [Your Project Name]
## Overview
Brief description of what this project does, its main purpose,
and the key problem it solves.
## Tech Stack
- Language: TypeScript 5.x
- Framework: React 18 with Next.js 14
- Styling: Tailwind CSS
- Testing: Vitest + Testing Library
- Package manager: pnpm
## Conventions
- Use functional components with hooks. No class components.
- Name components in PascalCase. Name utilities in camelCase.
- One component per file. Co-locate tests next to source files.
- Use named exports, not default exports.
- Prefer early returns over nested conditionals.
## Forbidden Patterns
- Do NOT use `any` type. Use `unknown` and narrow.
- Do NOT use `console.log` in production code. Use the logger.
- Do NOT add new dependencies without noting them in the PR.
- Do NOT modify files in /generated — they are auto-generated.
## Testing
- Tests live next to source: `Component.test.tsx`
- Run tests with `pnpm test`
- New features require at least one integration test.
- Mock external APIs, never call them in tests.
## Key Files
- Entry point: `src/app/layout.tsx`
- API routes: `src/app/api/`
- Shared utilities: `src/lib/`
- Database schema: `prisma/schema.prisma`Where CodeWinger fits
CodeWinger supports project-level instructions that feed into agent context. Because it is local-first and BYOK, your rules stay on your machine and are sent directly to your chosen provider.
- Project-level instructions are read locally and included in agent context.
- Local-first architecture means rules files never leave your machine except as part of the API call to your own key's provider.
- BYOK means you choose the model and the provider. Rules file compatibility follows the model, not the IDE vendor.
- Inline diff review lets you verify that the agent followed your rules before changes land in your codebase.
Try it
Download CodeWinger Desktop for Windows x64
CodeWinger Desktop 0.3.0 is currently free. The setup installer is the recommended download for normal Windows users.
Bottom line
Rules files are one of the simplest ways to improve AI coding agent output. They cost nothing to create, they live in your repository, and they make the agent's first guess better. But they are not magic. They do not enforce anything. They do not replace diff review, testing, or developer judgment. Write a short, clear rules file. Keep it updated. And treat it as guidance, not governance.
FAQ
What is a rules file for AI coding?
A text file in your project (CLAUDE.md, .cursorrules, etc.) that gives the AI agent project-specific instructions about conventions, patterns, and constraints.
Are rules files the same as prompt engineering?
Related but different. Rules files provide persistent project context. Prompt engineering is per-task instruction writing. Rules files are closer to context engineering.
Can rules files prevent the agent from writing bad code?
No. Rules files are guidance, not enforcement. The agent can ignore or misinterpret them. Diff review is the actual quality gate.
Should I use CLAUDE.md or .cursorrules?
Depends on your IDE. For portability, use a generic markdown file that any agent can read. Avoid vendor-locked formats when possible.
How long should a rules file be?
Under 500 lines. Shorter is better. Focus on the conventions and constraints that produce the biggest impact on agent output quality.
Does CodeWinger support rules files?
Yes. CodeWinger reads project-level instructions that feed into agent context. Because it is local-first, rules are read locally and sent directly to your chosen BYOK provider.