AGENTS.md: Give Coding Agents Your Legacy System's Rules

What is AGENTS.md?

The official AGENTS.md site describes an open format for guiding coding agents. It provides a predictable place for repository instructions, separate from a general project introduction. Its examples cover setup, testing and coding conventions. The useful question for a business is what an experienced maintainer knows that a new coding session might miss.

A source file can show how a rule is implemented without explaining why it exists. An unusual date calculation may support a contract agreed years earlier. Before asking an agent to simplify that code, give it the rule, the relevant module and a way to check the behavior. Treat undocumented assumptions as questions to resolve.

AGENTS.md examples should point to evidence

Illustrative example: a service-contract system treats renewal dates differently for one historic contract category. The agent's task is to improve a reporting screen. Its instructions should identify the authoritative renewal logic and the test fixtures for that exception, and state that this task does not change contract calculations.

A useful instruction explains the constraint and where to verify it. Replace a vague request to be careful with a specific direction to reuse the existing renewal calculation and run the relevant tests. Keep customer identities and contract documents out of the instruction file; link to approved internal documentation without embedding confidential records.

• Purpose: which business process this module supports.
• Constraint: the behavior that this task must preserve.
• Evidence: the maintained specification and test location.
• Verification: the exact working directory and command.
• Uncertainty: who resolves a conflict between code and documented policy.

Keep shared knowledge separate from today's assignment

Put durable repository knowledge in the instruction file. Put the current objective, permitted scope and expected deliverable in the task brief. A temporary migration workaround should have an owner and a removal condition rather than becoming a permanent instruction by accident.

CLAUDE.md is Claude Code's documented mechanism for persistent instructions. Its documentation distinguishes authored rules from notes accumulated through auto memory. When several tools work on the repository, verify their actual instruction-loading behavior and keep a single maintained source for shared facts. Do not assume identical discovery or precedence just because two tools can read Markdown.

Avoid copying the full architecture manual into every session. Keep a short map of the important boundaries and point to detailed documentation when needed. Conflicting copies create another maintenance problem; review instruction changes with the code or process change that made them necessary.

Instructions guide work; controls enforce boundaries

Claude Code explicitly describes instruction files as context rather than enforced configuration. A sentence prohibiting production writes does not remove a credential or block a command. Match important boundaries with actual access controls, protected environments and required checks.

Evaluate the instruction file with a small, reversible task in an isolated checkout. Ask the agent to identify the applicable rule and evidence before proposing a change. Verify which files it read, which commands it ran and whether the resulting diff stays within scope. Do not score success merely by whether the agent says it understood.

When a repeated error occurs, decide whether the cause was missing context, stale documentation, an inadequate test or an unenforced permission boundary. Adding another paragraph is useful only when missing guidance was the problem.

Make repository context part of ongoing ownership

Start with one frequently changed module. Have its maintainer verify the business constraints and test commands, then use the instructions on a bounded change. Track repeated clarification and correction work across comparable tasks; do not promise a productivity gain before observing it.

UVISION provides dedicated developers and managed projects with at least one full-time developer per project. In critical legacy systems, that continuity helps preserve the understanding behind existing behavior while adding new capabilities. AI coding tools can accelerate implementation, but maintaining trustworthy context remains part of the engineering responsibility.