# Rules and Instructions: Persistent Context for Your Agent

> How to use rules files, repository instructions, and AGENTS.md to give agents consistent, project-level context without repeating yourself in every prompt. The difference between global rules, project rules, and task-specific instructions.

- **Source:** https://ainativesoftware.engineering/roadmap/day-4/rules-and-instructions-persistent-context-for-your-agent
- **Site:** AI-Native Software Engineering — https://ainativesoftware.engineering/book

- **Day:** 4 · position 2 of 8
- **Reading time:** 3 minutes
- **Day overview:** [Day 4](https://ainativesoftware.engineering/roadmap/day-4.md)

How to use rules files, repository instructions, and AGENTS.md to give agents consistent, project-level context without repeating yourself in every prompt. The difference between global rules, project rules, and task-specific instructions.

## Theory

Every time you start a new agent session, the model begins with a blank slate. Without persistent context, you end up repeating the same things in every prompt: use TypeScript, follow this folder structure, never use class components, prefer `date-fns` over `moment`. Rules and instruction files solve this. They let you define context once and have it automatically loaded into every conversation, without any extra work on your part.

### What rules actually are

Rules are plain Markdown files. You write down whatever you want the agent to consistently know or follow: coding conventions, architectural decisions, libraries to prefer or avoid, security requirements, naming patterns, how to structure commit messages. The agent reads them as part of its context before reasoning about your request.

### The hierarchy

Most tools support three levels:

- **User-level rules**: personal preferences that apply across all your projects (your preferred code style, how you like responses formatted)
- **Workspace/project rules**: project-specific conventions that apply to everyone working in the repo. In Cursor these live in `.cursor/rules/`. In VS Code/Copilot they go in `.github/copilot-instructions.md` or `*.instructions.md` files under `.github/instructions/`. In Claude Code you use `CLAUDE.md`
- **File-specific rules**: instructions that only apply to certain file types or folders, using glob patterns like `applyTo: "**/*.test.ts"` for test-specific conventions

### AGENTS.md

`AGENTS.md` is an emerging standard, now supported by VS Code, Cursor, and Claude Code, for a single file that all agents in a workspace can read. It is especially useful in monorepos where different parts of the codebase have different conventions, and in teams where multiple tools need to share the same ground rules.

### Tips that actually make a difference

- **Include the reason behind a rule.** "Use `date-fns` instead of `moment.js` because moment is deprecated and increases bundle size" gives the agent enough context to apply the rule correctly in edge cases. "Use `date-fns`" alone sometimes gets ignored.
- **Focus on non-obvious things.** Skip conventions that linters and formatters already enforce. Rules are most valuable for decisions the tooling cannot express.
- **Keep rules short and specific.** A rule that tries to say everything ends up saying nothing useful. One clear statement per rule is more reliable than a paragraph.
- **Commit project rules to version control.** That way the whole team gets consistent behavior, not just whoever happened to set up the rule locally.

**Theory resources**

- [Custom Instructions in VS Code – Microsoft Docs](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
- [Rules – Cursor Docs](https://cursor.com/docs/context/rules)
- [Agents.md](https://agents.md/)

## Practice

Run this in a repository you already know, not a toy project.

Pick a real project you are currently working on. Your goal is to write a set of rules that make the agent behave consistently without you having to repeat yourself.

1. **Start with a brain dump.** List the things you find yourself correcting or re-explaining to the agent most often. Think about: naming conventions, preferred libraries, patterns to avoid, folder structure expectations, how tests should be written, and anything architecture-specific.

2. **Browse [awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) for inspiration.** Find a ruleset for a technology stack close to yours. You don't need to copy it verbatim, but reading a well-structured ruleset is the fastest way to understand what good rules look like.

3. **Write 5 to 10 rules** for your project. Create the right file for your tool:
   - Cursor: `.cursor/rules/project.mdc`
   - VS Code / Copilot: `.github/copilot-instructions.md`
   - Claude Code: `CLAUDE.md`

   For each rule, write the instruction and the reason behind it.

4. **Test before and after.** Take a task you would normally do and run it without the rules first. Then run the same task with the rules active. Note the differences: did the agent follow conventions it previously ignored? Did it use the right libraries? Did the output need less editing?

5. **Reflect.** Which rules made the biggest difference? Were there any that seemed to be ignored? Did writing the rules help you clarify conventions you hadn't explicitly thought through before?

**Practice resources**

- [Awesome Cursor Rules – Community-Contributed Rulesets](https://github.com/PatrickJS/awesome-cursorrules)

- **Previous topic:** [From Prompt Engineering to Context Engineering](https://ainativesoftware.engineering/roadmap/day-4/from-prompt-engineering-to-context-engineering.md)
- **Next topic:** [Skills and Commands: Reusable Patterns](https://ainativesoftware.engineering/roadmap/day-4/skills-and-commands-reusable-patterns.md)

---

_AI-Native Software Engineering by Alfonso Graziano (O'Reilly Media, Early Release; print edition February 2027). Every page of ainativesoftware.engineering is also served as Markdown: append `.md` to any URL. Index: https://ainativesoftware.engineering/llms.txt — whole site in one file: https://ainativesoftware.engineering/llms-full.txt._