Ticket Suitability

Context Files and Repo Conventions Coding Agents Need

Context files work best when built iteratively from agent failures, not anticipated upfront.

Cover illustration for “Context Files and Repo Conventions Coding Agents Need”
Cover illustration for “Context Files and Repo Conventions Coding Agents Need”

Coding agents need repository guidance they can use after the chat ends. A context file supplies that guidance, but its value depends on what it contains, when it loads, and whether it stays current. The practical fix for session blindness is a small, scoped, failure-driven engineering artifact.

Why coding agents start every session without project knowledge

Coding agents have no persistent memory of project conventions across sessions. They begin with generic training knowledge, the code available in the current context window, and whatever the user supplies in the prompt. Project decisions are not automatically part of that knowledge. An agent may understand a language without knowing which package manager the team uses, which patterns are deprecated, which files are generated, or which test command the repository requires.

In a large codebase, the nearest file may show a pattern in use without showing whether the team still approves it. The agent therefore navigates from local examples rather than accumulated standards, making decisions that appear reasonable within one module but violate the repository’s architecture.

What a context file is and how it solves the session-blindness problem

A context file, most commonly AGENTS.md, is a checked-in Markdown file that supplies project-specific operational guidance at agent startup. Its mechanism is simple. The agent loads durable instructions into its current context instead of depending on knowledge retained from an earlier conversation. Which files a tool finds on its own depends on the file names it supports and its loading rules, but each tool uses them to load guidance at startup.

The format requires no fixed schema or special metadata. Plain Markdown keeps the guidance readable and portable, while placement at the repository root makes it part of the project. Source control makes every edit reviewable and preserves the same guidance on a fresh clone. The file replaces repeated prompt instructions, which otherwise vary across teammates and sessions.

What belongs in a context file, section by section

An effective context file contains information the agent cannot reliably derive from reading the code. Five modes of instruction help distinguish what that information must accomplish. Descriptive guidance establishes project facts, prescriptive guidance defines required actions, and prohibitive guidance marks hard boundaries. Explanatory guidance supplies the reason behind a decision. Conditional guidance captures rules whose application depends on the task, so the agent receives more than a static description of the repository.

The file should give the exact commands for installing dependencies, starting the development server, running tests, linting, and checking types. A descriptive statement such as “This project uses pnpm workspaces” establishes the environment. A prescriptive statement such as “Run pnpm typecheck before every commit” turns that knowledge into a workflow.

Directory responsibilities and architecture rules establish ownership. They should identify where business logic lives, where validation belongs, and which major directories own which responsibilities. Approved libraries, established patterns, and architectural decisions prevent the agent from re-deciding those choices locally. Rationale helps with adjacent cases. An explanation of why a convention exists gives the agent a basis for applying it where the file does not provide an exact rule.

Hard constraints require explicit prohibitions. Generated files, restricted systems, and security or data-handling boundaries should be identified directly, using instructions such as “Never edit files under vendor/”. Database migration guidance should say which operations are safe, which are unsafe, and whether they need manual review. Verification guidance then defines completion, including required tests, linting, and reporting expectations. Conditional wording such as “If a test file exists, run it before claiming a fix is done” encodes the judgment that a purely descriptive file leaves out.

What to leave out of a context file

Standard programming explanations, generic REST API patterns, and conventions already apparent from the code consume context without resolving uncertainty. Formatting rules already enforced by a linter or formatter are similarly redundant. Enforcement belongs in the existing tool. The context file can specify that linting must run without reproducing every rule the linter applies.

Temporary feature requirements belong in the task prompt. Long procedures used only in particular situations belong in Skills or workflow files loaded on demand. Secrets have no place in the file. Conflicting instructions should be resolved and removed rather than presented as competing rules, because the agent has no reliable basis for deciding which one wins.

A statement assigning validation to a particular layer directs a decision, whereas a broad repository overview may merely repeat what the agent can discover. The distinction is consequential. Every always-loaded passage spends context on every invocation, so length should follow the minimum guidance needed.

What the research actually shows about whether context files improve agent performance

ETH Zurich’s 2026 study, arXiv:2602.11988, tested context files with several coding agents and LLMs and found that task success rates did not improve, while inference cost rose by over 20% on average. The agents did not ignore the guidance. With context files present, they explored more files, ran more tests, and used more repository-specific tooling.

The study also found that repository overviews offered no benefit, despite their popularity and recommendation by model providers. “Unnecessary requirements from context files make tasks harder, and human-written context files should describe only minimal requirements”. Following instructions and completing the task correctly are separate outcomes.

A separate 2026 paper, arXiv:2601.20404, found an efficiency benefit: curated files reduced agent runtime and output tokens on focused pull requests. The REALM @ EMNLP 2026 two-agent ablation, arXiv:2607.27250, found that neither a full repository context file nor a retrieval-style split measurably changed whether patches passed the gold PR tests. Both agents tested had the same result for correctness.

These findings leave other potential benefits unmeasured. The ETH Zurich study evaluates benchmark task performance, leaving coordination between teammates, consistency across tools, and the cost of different agents behaving differently in the same repository unmeasured. Those are distinct questions. The available results therefore show a correctness null and added cost in one setting, an efficiency benefit in another, and no direct answer about team coordination.

In a large codebase, the nearest file may show a pattern in use without showing whether the team still approves it.

How iterative, failure-driven content produces context files that actually work

The ETH Zurich result concerns human-authored or single-pass LLM-generated files, rather than guidance repeatedly refined against observed failures. Instead of asking what an agent might need to know, iterative refinement tests which instructions address actual mistakes. It provides a narrower basis for adding rules than a one-time attempt to anticipate every possible task.

Shepard and Albrecht’s “Probe-and-Refine Tuning of Repository Guidance for Coding Agents”, published in June 2026 as arXiv:2606.20512, develops that approach through synthetic bug-fix experiments. The procedure improves repository guidance through failure feedback using targeted single-shot LLM calls, without an agent loop or reinforcement learning. The paper attributes the difference from the ETH Zurich results to iterative refinement. Separately, Agentic Context Engineering, or ACE, reported a 10.6% gain on agent tasks in an ICLR 2026 result using incremental updates and accumulated lessons.

A team should add a rule when an agent makes a mistake. One implementation is to have the agent append what it learned about the repository after a session, with those edits subject to review. This method leads to prohibitive and conditional instructions because failures show which actions must be ruled out and which preconditions were missing. It gives teams a way to refine content against evidence.

How the fragmented tool ecosystem affects which file name to use and how to structure multi-tool repos

No single file name is read natively by every agent. Claude Code reads CLAUDE.md, Codex reads AGENTS.md, and Cursor uses.cursor/rules/*.mdc. These files do the same job, but keeping separate copies up to date takes work. When each teammate’s agent reads a different version of the rules, behavior can diverge within the same repository.

The recommended structure is one canonical AGENTS.md with thin tool-specific stubs where needed. A stub should direct the agent to read the root file and identify any remaining instructions as tool-specific additions. The real guidance stays in one place.

Claude Code has an important default behavior. When CLAUDE.md is present with AGENTS.md, it reads CLAUDE.md and suppresses AGENTS.md. A repository with no Claude-specific content should use AGENTS.md alone and leave out the unneeded CLAUDE.md. Where CLAUDE.md is needed, its import references and hierarchical directory-level loading can support genuinely different package conventions, capabilities that AGENTS.md does not standardize.

How to structure context files in monorepos and large codebases

A canonical source of guidance does not require one monolithic file. In a large codebase, a root AGENTS.md that covers every package, service, and module loads rules that have nothing to do with the task at hand. That wastes context and weakens the signal from relevant instructions. The structural principle is scope. Repository-wide rules belong at the root, while guidance that applies only to one subproject belongs near that subproject.

A short root file should hold conventions that stay the same over time, such as the package manager, top-level architectural boundaries, and security restrictions shared across the repository. Nested AGENTS.md files should hold package commands, module responsibilities, and local conventions where these differ from those in the rest of the repository. The same principle applies to CLAUDE.md hierarchies with focused files in directories such as apps/web and packages/api.

Loading behavior must match that design. Support and precedence for nested AGENTS.md files vary between tools, so teams should verify how their agent handles the hierarchy before relying on it. Directory placement alone is not a guarantee.

Why context files rot and how to treat them as maintained engineering artifacts

Staleness can undermine otherwise sound guidance. A rule for a retired tool or an abandoned pattern remains an explicit instruction, and the agent may trust it over what the current code suggests. Absence leaves a gap. A stale instruction supplies the wrong answer, while a stale rule next to a current one creates a conflict the agent cannot reliably resolve.

This is context rot across sessions. Stale, low-signal, and contradictory text accumulates in the durable file just as it can accumulate within a long conversation. Maintenance therefore requires deletion as well as addition. An agent beginning to make mistakes it did not make months earlier may be signaling an overgrown or contradictory context file.

The governance response is to treat context files like Dockerfiles or CI/CD workflows. Teams should review them on the cadence of CI configuration, remove rules inferable from current code, and move requirements that must always run into hooks or CI steps. Deterministic enforcement is stronger than an instruction competing for attention. Agent behavior should also be watched for ignored rules that indicate excessive length or contradictions.

Across multiple teams, this becomes a distribution and drift problem that extends beyond editing within one repository. A ContextOps model makes context distribution, drift detection, and automated checks before guidance enters the codebase part of how the organization manages that guidance. The file remains small only through active curation. Context files are engineering artifacts that need upkeep, so teams should plan for review, scope, and enforcement when they design them.

Sources

  1. Context engineering for large codebases : a practical guide

    Informed the discussion of ContextOps, context rot, and treating context files as maintained engineering artifacts requiring drift detection and curation.

Priya Venkataraman

More in Ticket Suitability

← Front page