What Is a Rules File for AI Agents? How to Write Standing Orders That Survive Sessions

The Problem with Stateless AI Sessions

Every time you start a new session with an AI coding agent, it forgets everything. Your preferred naming conventions, the architecture decisions you made last week, the fact that you never want it to modify the auth module without asking first — gone.

This isn’t a bug. It’s how large language models work by design. But it creates a real friction point when you’re using AI agents like Claude Code or Cursor for serious, ongoing development work. You end up spending the first few minutes of every session re-explaining the same context, or worse, you don’t, and the agent makes confident, confident decisions that break your conventions.

A rules file for AI agents solves this. It’s a persistent file — usually sitting in your project root — that gets loaded automatically at the start of every session. Whatever you put in it becomes the agent’s standing orders. Write it once, and the agent reads it every time.

This guide covers what rules files are, how they work across different tools, and how to write standing orders that actually hold up in practice.

What a Rules File Actually Is

A rules file is a plain text or Markdown document that provides an AI agent with persistent context about a project. It tells the agent things the codebase itself doesn’t tell it: team conventions, architectural decisions, communication preferences, and constraints.

Think of it like onboarding documentation — except instead of orienting a new developer, you’re orienting an AI that will otherwise approach every session as if it has never seen your project before.

Rules files go by different names depending on the tool:

Claude Code reads CLAUDE.md from the project root (and any parent directories)
Cursor reads .cursorrules (and now supports project-level rules via .cursor/rules/)
Windsurf reads .windsurfrules
GitHub Copilot reads .github/copilot-instructions.md

The format and naming differ, but the purpose is identical: give the agent durable instructions it can reference throughout every session.

How Rules Files Differ from System Prompts

A system prompt is written by whoever deploys the model. It shapes the AI’s core behavior and typically can’t be modified by the end user. A rules file is written by you — the developer using the agent — and it layers project-specific instructions on top of whatever system-level behavior the tool already has.

System prompts set personality and constraints. Rules files set project context.

Another difference: system prompts are usually invisible. Rules files are just files in your repository. You can version-control them, share them with your team, and update them as the project evolves.

Where Rules Files Live

Most tools load rules files from the project root automatically. Claude Code will also walk up the directory tree and load rules from parent directories, which means you can have organization-wide rules at a higher level and project-specific rules closer to the code.

Some tools let you have multiple rules files organized by topic. Cursor’s newer rules system lets you put multiple .mdc files inside a .cursor/rules/ directory and attach them to specific contexts (e.g., only apply these rules when working in the /api directory).

Rules Files Across Different Tools

CLAUDE.md for Claude Code

CLAUDE.md is Claude Code’s native rules file format. Place it in your project root and Claude Code will read it automatically at the start of every session. You can also create CLAUDE.md files in subdirectories — Claude will read the closest one to whatever file you’re working in.

Anthropic designed CLAUDE.md specifically for development context. Common things teams put in it:

Build and test commands so Claude doesn’t have to guess
Code style and formatting rules (even if you also have a linter, stating them explicitly helps)
Architecture overview and module responsibilities
Patterns to follow and patterns to avoid
Who to ask (or what to check) before making certain changes

Because Claude Code can run shell commands and modify files autonomously, the behavioral guardrails in CLAUDE.md carry real weight. If you tell it never to run destructive database operations without confirmation, that instruction persists.

.cursorrules for Cursor

Cursor’s .cursorrules file works similarly, but it’s focused more on editor-level behavior: how the AI completes code, what frameworks it should assume, and what patterns to prefer. Cursor has been migrating users toward a more structured rules system (.cursor/rules/*.mdc) that lets you scope rules to specific file types or directories.

Cursor rules files are particularly useful for specifying:

Which version of a framework you’re using (important when the AI might otherwise default to outdated patterns)
Component and file naming conventions
Whether to use TypeScript strict mode
Preferred import styles and module resolution patterns

Other Agentic Tools

Any agent that supports a persistent context file follows roughly the same pattern. The specifics differ, but the mental model is the same: a file the agent reads at session start becomes its working assumptions for that session.

If you’re building or deploying agents programmatically — through frameworks like LangChain, CrewAI, or custom pipelines — you can implement your own rules file concept by loading a context file and injecting its content into the system message before the agent begins working.

How to Write an Effective Rules File

There’s no universal template, but there are consistent patterns in rules files that work well. The goal is to give the agent enough context that it makes good decisions on its own, without having to ask you about established conventions.

Start with Role and Context

Open with a brief description of what this project is and what role the agent is playing. This isn’t just flavor text — it sets the frame for all subsequent instructions.

This is a B2B SaaS application built with Next.js 14 and Postgres.
You are helping a small engineering team of three people maintain and extend it.
The codebase is production and has paying customers.

Two to four sentences is enough. The agent doesn’t need a business plan; it needs to know what kind of project this is, what’s at stake, and what kind of decisions it’s expected to make.

Define Code and Style Conventions

This is where most rules files spend the most space, and for good reason. Explicit conventions prevent the agent from making technically correct but stylistically inconsistent choices.

Cover:

Language and framework versions — “We use TypeScript 5.2 with strict mode enabled”
Naming patterns — “React components use PascalCase. Utility functions use camelCase. Database columns use snake_case”
File organization — “API handlers go in /api/routes/. Shared types go in /types/”
Import style — “Always use named imports. Never use default exports except for Next.js pages and layouts”
Testing conventions — “Write unit tests with Vitest. Test files live next to the source file with a .test.ts suffix”

Don’t just list rules — explain why briefly when the reason isn’t obvious. “We avoid default exports because they make refactoring harder in this codebase” helps the agent generalize better than just “no default exports.”

Set Behavioral Guardrails

This section is especially important for autonomous agents that can execute commands, modify files, or call external services. Guardrails define what the agent should confirm before doing, what it should never do, and how it should handle uncertainty.

Examples:

Never modify files in /scripts/migrations without explicitly being asked to.
If a task requires changing the database schema, explain the change and wait for approval before writing any code.
When you're unsure whether a change might break something, say so rather than proceeding.
Do not install new npm packages without confirming the package name and version first.

Be specific. “Be careful” is not a guardrail. “Confirm before running any command that deletes data” is.

Add Project-Specific Knowledge

This is the section most people underutilize. Beyond conventions, the rules file is a good place to capture things that are true about your specific project and would take the agent time to figure out (or might never figure out correctly).

Useful things to include:

Known quirks — “The useAuth hook depends on a specific provider order in _app.tsx. Don’t refactor the provider tree without checking this.”
Environment setup — “Run npm run dev:local to start with local environment variables. npm run dev will attempt to connect to staging.”
Important third-party constraints — “We’re on the Stripe API version 2022-11-15 due to a contract. Do not suggest upgrading.”
Active work areas — “We’re currently migrating from REST to tRPC. New endpoints should use tRPC. Do not create new REST endpoints.”

This kind of context lives in developers’ heads and rarely makes it into documentation. A rules file is a good forcing function to write it down somewhere accessible.

Common Mistakes That Break Your Rules File

Making it too long

A rules file that’s 2,000 words long will have diminishing returns. Most models have context windows large enough to handle it, but a bloated rules file tends to have lower signal-to-noise ratio. The agent has to work harder to find the relevant instruction.

Aim to keep it under 500 words for most projects. If you need more, consider using a tiered structure: top-level rules for the whole project, sub-directory rules for specific modules.

Writing instructions that conflict

Contradictory instructions produce unpredictable behavior. “Always write unit tests” and “only write tests when explicitly asked” in the same file will leave the agent guessing which rule applies when.

Review your rules file the same way you’d review a pull request. Look for instructions that undermine each other.

Treating it as a one-time document

The rules file is a living document. As the project evolves, the rules should evolve with it. If you’ve migrated to a new testing framework, update the testing conventions. If you’ve hired more developers and want to enforce more consistent patterns, add them.

A stale rules file is worse than no rules file in some cases — it tells the agent to do things that are no longer true about the project.

Being vague about scope

“Write clean code” tells the agent nothing useful. “Extract functions when they exceed 30 lines unless there’s a specific readability reason to keep them together” tells it something it can act on.

Effective rules are specific enough to produce consistent behavior. If two different developers read your rules file and would make the same decision in the same situation, the rule is specific enough.

Forgetting to document what not to do

Rules files often focus entirely on what the agent should do. But “never do X” instructions are equally important, especially for agents with tool access.

If there’s a library you’ve tried and abandoned, say so. If there’s an architectural pattern that looks appealing but doesn’t fit your codebase, explain why it’s off limits. Negative rules often prevent the most frustrating mistakes.

Where MindStudio Fits into the Agent Workflow

Rules files solve the persistence problem within a single tool or session. But many production agent workflows involve more than one AI agent, and coordinating them introduces a different challenge: how do you give agents capabilities — like sending emails, running web searches, or triggering other workflows — without building that infrastructure yourself?

This is where MindStudio’s Agent Skills Plugin comes in. It’s an npm SDK (@mindstudio-ai/agent) that any agent — Claude Code, LangChain agents, custom pipelines — can use to call 120+ typed capabilities as simple method calls. Instead of building your own email-sending logic or search integration, you call agent.sendEmail() or agent.searchGoogle() and MindStudio handles auth, retries, and rate limiting.

The practical connection to rules files: when you’re writing standing orders for an agent that has tool access, you want to be specific about which tools it can use and when. If your agent has access to MindStudio capabilities, you can reference those directly in your rules file:

You have access to agent.searchGoogle() for real-time information lookups.
Use it when the user asks about anything that might have changed since your training cutoff.
Do not use it for questions you can answer confidently from context.

Specificity in the rules file makes tool use more predictable. The agent knows what tools exist, when to reach for them, and when not to.

If you’re building the agent itself — not just configuring an existing one — MindStudio’s no-code builder lets you create agents with persistent system prompts, branching workflows, and integrations with 1,000+ business tools. You can try it free at mindstudio.ai.

Frequently Asked Questions

What is a CLAUDE.md file?

CLAUDE.md is the rules file format used by Claude Code, Anthropic’s agentic coding tool. When you place a CLAUDE.md file in your project root, Claude Code reads it automatically at the start of every session. It can contain anything from code style preferences to architectural constraints to behavioral guardrails. Claude Code also supports CLAUDE.md files in subdirectories, which take precedence over the root-level file for work done in that directory.

What should I put in a .cursorrules file?

A .cursorrules file should contain the context Cursor needs to make consistent, project-appropriate decisions. At minimum: the framework and language versions you’re using, naming conventions, file organization patterns, and any constraints on how the AI should handle code generation. If you’re using newer versions of Cursor, you can also use the .cursor/rules/ directory to scope different rules to different parts of the project.

Can AI agents actually remember instructions between sessions?

Not natively — most AI agents are stateless by default. Each session starts fresh. Rules files are the practical workaround: they provide persistent context by being loaded at the start of each session. The agent isn’t “remembering” — it’s re-reading the same instructions you’ve written down. Some tools also support memory features that log important facts between sessions, but rules files remain the most reliable mechanism for standing orders.

What’s the difference between a rules file and a system prompt?

A system prompt is set by the tool or platform deploying the AI and defines its core behavior. End users typically can’t modify it. A rules file is set by you and layers project-specific instructions on top of that base behavior. System prompts define what kind of agent it is. Rules files define what it should know and do within your specific project context.

How long should a rules file be?

For most projects, 200–500 words is the right range. Long enough to cover the important conventions and constraints, short enough that every rule has genuine signal. Very large codebases with complex conventions might justify up to 1,000 words, but past that point, consider whether the rules file structure itself needs to be broken into smaller, scoped files rather than adding more content to one document.

Do rules files work for non-coding agents?

Yes. While the most common use case is software development, the underlying concept applies to any agent workflow. If you’re building an agent that handles customer support, content generation, or data analysis, a rules file (or equivalent persistent context document) can define the tone, constraints, escalation paths, and domain-specific knowledge the agent should carry into every session. The format and loading mechanism depend on the tool, but the writing principles are the same.

Key Takeaways

A rules file is a plain text or Markdown document loaded automatically at the start of each AI agent session, providing persistent instructions that survive across sessions.
Different tools use different filenames: CLAUDE.md for Claude Code, .cursorrules for Cursor, .windsurfrules for Windsurf, and .github/copilot-instructions.md for GitHub Copilot.
Effective rules files cover role and project context, code and style conventions, behavioral guardrails, and project-specific knowledge.
Common mistakes include writing conflicting instructions, letting the file go stale, being vague about scope, and forgetting negative rules (“never do X”).
Rules files are living documents — update them as your project evolves, the same way you’d update any other critical documentation.

For developers building or extending agents programmatically, MindStudio offers both a no-code agent builder with persistent system prompt support and an npm SDK that gives agents access to 120+ typed capabilities — worth exploring if you’re moving beyond single-session, single-agent workflows.