Contents
Project rules for coding agents are text files in your repository that tell an agent, before every task, how your project works: commands, architecture, conventions and boundaries. Written well, they are the most effective lever for better results because the agent no longer has to guess. This guide shows what belongs in them, what does not – and how to keep them current.
What context files for coding agents are
Every agentic coding tool offers a way to store persistent instructions that are automatically loaded into the context of each session. The file names vary by tool, for example AGENTS.md as a cross-tool convention, CLAUDE.md for Claude Code, rule files in a configuration folder for Cursor, or an instructions file for GitHub Copilot. Check your tool's documentation to see which file names and locations it supports.
They all serve the same purpose: they replace the onboarding conversation a new colleague would get on day one. Without this information the agent relies on generic patterns from its training data – and those rarely match your project exactly. Typical consequences of missing rules are wrong libraries, deviating code style, duplicated helpers or tests structured differently from the existing ones.
The key contents of good project rules
| Section | Content | Example |
|---|---|---|
| Project overview | Purpose, users, core modules in two to five sentences | "Booking app for physiotherapy practices, backend in Kotlin, app in Flutter" |
| Commands | Build, tests, linter, local start – exact and copy-pasteable | npm run test -- --watch=false |
| Architecture | Layers, directory structure, where new code goes | "Business logic only in /domain, never in UI components" |
| Conventions | Naming, error handling, logging, test style | "Return errors as a Result type, no exceptions in the domain layer" |
| Dependencies | Preferred libraries, banned packages | "HTTP only via the existing ApiClient" |
| Boundaries | What the agent must not change or run | "Never edit migration files that are already deployed" |
| Definition of done | What must be true before a task is complete | "Tests and linter green, changelog entry added" |
How to write rules agents actually follow
Specific, not generic
"Write clean code" achieves nothing because every agent tries that anyway. Effective rules pre-empt a concrete decision: "Use only the helpers in utils/date.ts for date values." Ask yourself for each rule: would an experienced developer without project knowledge do something different here? If not, the rule can go.
Short and prioritised
Context files are loaded into every session and compete with the actual task for attention. Long files with hundreds of rules cause individual instructions to get lost. Keep the main file compact and put the most important points first. Detailed knowledge about specific areas belongs in separate files you reference or – if your tool supports it – in rule files in subdirectories that apply only there.
Include the reason
A short clause explaining why helps the agent apply the rule correctly in edge cases: "No direct database access from controllers – we need the repository layer for tenant isolation."
Positive phrasing and examples
Say what to do instead, not just what is forbidden. A short code example of the desired pattern often works better than a paragraph of explanation. For the underlying principles, read our article on context engineering.
What does not belong in context files
- Secrets and credentials: context files live in the repository and end up in the model's context. Passwords, API keys or internal URLs with tokens have no place there – see also agentic coding and data security.
- Task-specific instructions: anything that applies only to the current task belongs in the prompt, not in the permanent rules.
- Outdated information: a wrong rule is worse than no rule, because the agent trusts it.
- Copies of existing documentation: link to architecture or API documents instead of duplicating them.
- The obvious: general best practices every agent knows only take up space.
Step by step to your first context file
- Let the agent draft it: many tools can analyse the repository and propose a first version. That saves time but does not replace review.
- Verify the commands: run every build and test command yourself. Wrong commands are the most common error in generated files.
- Add architecture and boundaries: knowledge that lives only in experienced team members' heads cannot be guessed by any agent. This is where the biggest value lies.
- Cut: remove everything generic and duplicated.
- Test run: give the agent two or three typical tasks and check whether it follows the rules.
- Commit via pull request: treat context files like code – with review and versioning.
Keeping project rules up to date
Context files go stale like any documentation. Three habits have proven useful. First: when an agent makes a mistake caused by missing project knowledge, add the rule – ideally in the same pull request as the fix. Second: architecture changes always include an update to the rules. Third: at regular intervals, for example once a quarter, someone reviews the file for outdated and redundant content.
Teams with several repositories benefit from a shared baseline for cross-cutting standards such as security policies or commit conventions, complemented by project-specific files. To go one step further, combine project rules with per-feature specifications as described in spec-driven development. In our workshops, for which we place AI developers from real-world practice as trainers, teams often create such rules directly on their own code.
Planning an app? Request a free fixed-price quote in 2 minutesConclusion
Good project rules are short, specific, justified and current. They contain verified commands, architecture principles, conventions and clear boundaries – but no secrets and no platitudes. If you treat the file like code and turn every recurring agent mistake into a rule, you improve your coding agents' results for the long term.
Frequently Asked Questions
How long should a context file for coding agents be?
As short as possible, as long as necessary. A compact main file with the key commands, principles and boundaries usually works better than an extensive document in which individual rules get lost.
Does AGENTS.md work with every tool?
Many tools support this convention, but not all, and not always in the same way. Check your tool's documentation and, if needed, reference a shared source from the tool-specific file.
Who should maintain the project rules?
The whole team, with one clearly named owner. Changes go through pull requests with review, just like code.
Can internal information go into context files?
Architecture and process knowledge yes, credentials and confidential business data no. The agent sends these files to the model it uses, so treat them accordingly.