app-entwickeln-lassen.de LogoApp entwickeln lassen

Agentic Coding

How to Write Project Rules and Context Files for Coding Agents

app-entwickeln-lassen.de editorial team 6 min read
Contents
  1. What context files for coding agents are
  2. The key contents of good project rules
  3. How to write rules agents actually follow
  4. What does not belong in context files
  5. Step by step to your first context file
  6. Keeping project rules up to date
  7. Conclusion
  8. Frequently Asked Questions

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

SectionContentExample
Project overviewPurpose, users, core modules in two to five sentences"Booking app for physiotherapy practices, backend in Kotlin, app in Flutter"
CommandsBuild, tests, linter, local start – exact and copy-pasteablenpm run test -- --watch=false
ArchitectureLayers, directory structure, where new code goes"Business logic only in /domain, never in UI components"
ConventionsNaming, error handling, logging, test style"Return errors as a Result type, no exceptions in the domain layer"
DependenciesPreferred libraries, banned packages"HTTP only via the existing ApiClient"
BoundariesWhat the agent must not change or run"Never edit migration files that are already deployed"
Definition of doneWhat 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

  1. Let the agent draft it: many tools can analyse the repository and propose a first version. That saves time but does not replace review.
  2. Verify the commands: run every build and test command yourself. Wrong commands are the most common error in generated files.
  3. 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.
  4. Cut: remove everything generic and duplicated.
  5. Test run: give the agent two or three typical tasks and check whether it follows the rules.
  6. 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 minutes

Conclusion

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.

This article was written by the editorial team of app-entwickeln-lassen.de – the app and AI development service of jocapps GmbH, based in Freiburg, Germany, and building apps since 2014. The content is for general information and does not replace individual (legal) advice.

You might also like

Agentic CodingAgentic Coding in the Terminal vs. the IDE: Which Fits Your Team?

Agentic coding in the terminal or in the IDE? Strengths, limits and use cases of both approaches compared – with a practical decision guide for your dev team.

6 min read
Agentic CodingAgentic Coding for Mobile Apps: iOS and Android Development with Agents

Agentic coding for mobile apps: where coding agents help in iOS and Android projects, where their limits are, and how to set up a clean, reliable workflow.

6 min read
Agentic CodingCommon Agentic Coding Mistakes and How to Avoid Them

Common agentic coding mistakes explained: the ten typical pitfalls with coding agents and concrete countermeasures for development teams and tech leads.

7 min read
Agentic CodingAgentic Coding and Code Ownership: Who Is Accountable for the Code?

Agentic coding and code ownership: who is accountable for agent-generated code, how to assign responsibilities and keep knowledge in your team.

6 min read
Agentic CodingThe Developer's Role in the Age of Agentic Coding

The developer role in agentic coding: which tasks remain, which skills matter more and how teams and careers change as coding agents take on more work.

6 min read
Agentic CodingHow Agentic Coding Shortens Time-to-Market for Apps

Agentic coding and time-to-market: in which phases coding agents get apps to market faster, where the limits are – and how to plan your launch realistically.

6 min read