What is a rules file?

A rules file is a markdown file in your project that a coding agent reads before it changes anything. Cursor, Claude Code, Windsurf, GitHub Copilot, and Codex each look for a specific name. The contents are the notes you would give a new teammate who types very fast and forgets the boring constraints.

Why vibe coding goes sideways without one

If you do not say which stack you are on, the agent fills the gap with whatever it has seen most often. A Vite app grows a Next.js import. A Django project gets a second requirements file. A Unity script calls GameObject.Find because a tutorial did. None of that is malice. It is a missing instruction.

A short rules file makes those guesses boring. The agent already knows the package manager, the test command, and that it should not touch generated folders. You spend the chat on the feature instead of on cleanup.

What to put in it

Write the things that are expensive when they are wrong, and skip the rest. A useful file is usually one to three screens. Past that, tools truncate it or the model skims.

• Commands. The exact install, dev, test, and lint lines. Agents will run what you name.
• Stack choices. Router, ORM, styling, language version, package manager. One of each.
• Boundaries. Secrets, migrations that must not be edited, generated directories, and how much testing you want.
• Conflicts. Say that existing code wins over the file, and that a direct instruction in chat wins over both.

Leave the product pitch, the license, and the welcome paragraph in the README. The agent does not need them, and they crowd out the commands.

Where each tool looks

• Cursor: .cursor/rules/project.mdc with frontmatter. Set alwaysApply: true for a rule that should load every chat. Plain markdown in that folder is ignored. .cursorrules is the old filename.
• Claude Code: CLAUDE.md at the repo root, or .claude/CLAUDE.md. Split later topics into .claude/rules/*.md.
• Windsurf / Devin Desktop: .devin/rules/project.md with trigger: always_on. .windsurfrules is the legacy always-on file. Keep each file under about 12,000 characters.
• GitHub Copilot: .github/copilot-instructions.md. Path-specific files live in .github/instructions/ and must end in .instructions.md.
• Codex and most other agents: AGENTS.md at the root. Nested files cover a single package. Do not leave an empty AGENTS.override.md next to a real file.

The tool pages on this site show the frontmatter and the install steps for each of those names.

How to install a file from RulePaste

1. Open the generator. Pick the tools you actually use and the stack the repo already has. Do not pick the stack you wish you had.
2. Copy or download each file. Save it at the path shown above the code, including the folders. Create .cursor/rules or .github if they are missing.
3. Commit the file with the rest of the project so the next session, and your teammates, get the same instructions.
4. Start a new chat. Rules are loaded when a session starts. An open chat often keeps the old ones.
5. Edit the file when the repo disagrees with it. The copy in your project is the source of truth. This site does not sync it back.

How this generator works

RulePaste does not call a language model. Each framework, database, and test runner is a written module. The generator stitches the modules you picked into one markdown document, then wraps that document in the header the tool requires. The same choices always produce the same file, which is why it is free to run.

That also means the file is a starting point, not a portrait of your repo. If you use a custom script name or an unusual folder, change that line after you paste. An agent that follows a wrong command is worse than one with no command.

Mistakes that waste the file

• Pasting a giant style guide. The model will not hold all of it, and Windsurf may truncate the file.
• Contradicting the code. If the rule says pnpm and the repo has package-lock.json, the agent will thrash. Match the repo, then fix the rule.
• Hiding a secret in the file to "give the agent access". Commit the filename, never the key.
• Generating once and never editing. Add a line when the agent makes the same mistake twice. That line is worth more than a generic paragraph.