AGENTS.md Is Not a Decision System

What AGENTS.md does well

Coding agents need repository-specific context. Without it, an agent may not know which package owns a feature, how the repository is structured, which test commands are authoritative, which libraries or frameworks the team prefers, how changes should be formatted or submitted, which directories contain generated code, or what must be verified before declaring work complete.

An AGENTS.md file gives teams a persistent place to supply that information. GitHub Copilot, for example, supports repository-wide instructions, path-specific instructions and agent instruction files. Multiple AGENTS.md files can exist within a repository, with the nearest applicable file taking precedence for the area being changed. GitHub also supports path-scoped instruction files using glob patterns.

This is useful. It lets a repository say what commands to run, which files not to edit, which local technologies to use and where domain logic belongs. For many tasks, that is substantially better than giving the agent no repository guidance at all.

The mistake is treating this file as the complete governance mechanism.

• Run cargo test --workspace before completing a change.
• Do not edit files under generated/.
• Use SQLite for local persistence.
• Keep HTTP handlers thin.
• Place domain logic in src/core/.

Instructions and decisions are different things

An instruction tells an agent what to do. A decision explains a deliberate choice, including the context that caused it, the alternatives rejected, its scope and its consequences.

Consider the instruction: Use SQLite for local persistence. That tells the agent the expected outcome. It does not tell the agent why SQLite was selected, whether the decision applies to all storage or only desktop state, whether PostgreSQL is still permitted on the server, whether the decision is temporary, which constraints would justify revisiting it, what code or configuration would violate it, or which later decision may have superseded it.

A conventional architecture decision record is designed to preserve this missing context. A widely used ADR definition describes it as a document that captures an important architectural decision together with its context and consequences. The concise Nygard-style structure records the decision’s status, context, chosen action and consequences.

That record is more useful than the one-line instruction because it preserves the boundary of the decision.

# Use SQLite for desktop workspace state
## Status
Accepted
## Context
The desktop application must work without a network connection.
Workspace state is local to one user and does not require concurrent
multi-host writes. The application must remain simple to install.
## Decision
Use SQLite for persistent desktop workspace state.
This decision applies to apps/desktop/** and packages/local-store/**.
It does not govern hosted service persistence.
## Consequences
The desktop application requires no external database service.
Features requiring multi-user concurrent writes must remain in hosted
services or trigger a new decision.

ADRs solve recording, not delivery

A decision can exist in a repository and still have no effect on the work. The developer or agent must know that the decision exists, recognise that it applies to the current task, find the relevant record, interpret it correctly, implement the change consistently, and verify that the implementation complies.

Repositories commonly stop after the first step: the decision was written down. This creates a passive archive. The repository contains the rationale, but the relevant information may never reach the point where a change is planned, implemented or reviewed.

The problem becomes more pronounced with coding agents. Agents can scaffold frameworks, select dependencies, create storage layers, wire external services and introduce orchestration patterns within a single task. Those are architectural choices, even when nobody explicitly labels them as such.

Recent research describes this as “vibe architecting”: architectural structure emerging from prompt wording and agent choices rather than an explicit design process. Different prompts can produce structurally different systems for the same stated task. A folder full of ADRs cannot govern those choices unless the applicable records are deliberately brought into the task.

Making AGENTS.md longer is not the answer

The obvious response is to copy every important decision into AGENTS.md. That works for a while. Then the file accumulates architecture choices, language conventions, test procedures, release rules, design guidance, historical warnings, deployment constraints, security policies, exceptions, tool instructions and instructions for several unrelated subsystems.

Eventually, every task receives a large body of context, much of which is irrelevant to the files being changed. More context is not automatically better context.

A 2026 study of 100 popular repositories containing AGENTS.md or CLAUDE.md files found configuration problems to be widespread. The reported smells included context bloat, leakage of instructions better handled by tools, and conflicting instructions. Context bloat appeared in 42% of the analysed files, while several smells frequently occurred together.

A separate controlled study across Claude Code and Codex found that persistent context files did not measurably improve correctness across the tested tasks. Its failure analysis suggested that many agent failures came from implementation and pattern-selection weaknesses rather than missing repository facts.

That does not make context files useless. It means teams should not expect a single large Markdown file to compensate for every weakness in planning, retrieval, implementation and verification. The goal should be to provide the smallest relevant set of instructions and decisions for the current change.

A decision system needs three layers

The useful model is: Record → Route → Enforce. Each layer solves a different problem.

1. Record

The record preserves the decision. At minimum, it should identify the decision, its status, the context that caused it, the scope where it applies, its consequences, relevant alternatives, what would cause it to be revisited, and any decision it supersedes.

The record should be stable enough to explain the decision later, but explicit about lifecycle changes. When a decision is replaced, the new record should reference the superseded one rather than quietly rewriting history.

An ADR, decision record or another structured decision artifact is appropriate for this layer. The prose record explains the reasoning. Structured fields make the decision easier to route and inspect.

id: DEC-014
title: Use SQLite for desktop workspace state
status: accepted
scope:
  paths:
    - apps/desktop/**
    - packages/local-store/**
decision:
  local_persistence: sqlite
excludes:
  - services/api/**
  - services/worker/**
revisit_when:
  - desktop workspaces require concurrent multi-user writes
  - state must be shared across devices in real time

2. Route

Routing determines which decisions matter to the current work. A task changing apps/desktop/src/storage/workspace.ts should receive the SQLite decision. A task changing services/api/src/persistence/accounts.ts should not receive it merely because the repository contains a general statement about persistence.

Routing can use changed file paths, affected components, dependency boundaries, labels or task metadata, repository ownership, referenced APIs, declared capabilities and explicit relationships between decisions.

The agent can then receive a focused brief instead of all 70 repository decisions. Context-selection research for automated ADR generation supports the broader principle that context quality matters more than context quantity: a small window of relevant records can offer a better quality-efficiency balance than supplying the entire history, with targeted retrieval becoming more useful for cross-cutting cases.

Routing is the missing link between recording a decision and using it.

task:
  files:
    - apps/desktop/src/storage/workspace.ts
applicable_decisions:
  - DEC-014
  - DEC-021
  - DEC-033

## Applicable decisions
### DEC-014: Use SQLite for desktop workspace state
This change touches desktop persistence. Do not introduce another
database client. Hosted service persistence is outside this decision.
### DEC-021: Keep migrations reversible
Every schema migration must define a tested rollback path.

3. Enforce

Some decisions should remain explanatory. Others can and should become executable checks. The SQLite decision could be enforced by rejecting unsupported database dependencies in the governed paths.

Other decisions may become dependency rules, architecture tests, linter configuration, schema validation, policy-as-code, CI checks, forbidden import rules, ownership requirements, migration tests, API compatibility checks or pull-request review gates.

This does not mean every decision should become a test. A decision such as “Prefer a calm, low-distraction interface for operational workflows” requires judgement. It may support design review criteria but cannot be reduced safely to a deterministic boolean check. A decision such as “Code under domain/ must not import from infrastructure/” is directly enforceable.

Research into LLM detection of architectural decision violations similarly found that automated evaluation works better for explicit, code-inferable decisions than for implicit or organisational decisions dependent on deployment or human knowledge.

• Enforce mechanically what can be established mechanically.
• Preserve visible human judgement for everything else.
• Do not present a judgement-based decision as an automated guarantee.

from pathlib import Path

FORBIDDEN = {
    "psycopg",
    "asyncpg",
    "pymysql",
    "pymongo",
}
desktop_requirements = Path(
    "apps/desktop/requirements.txt"
).read_text()
violations = [
    dependency
    for dependency in FORBIDDEN
    if dependency in desktop_requirements
]
if violations:
    raise SystemExit(
        "DEC-014 violation: desktop persistence must use SQLite. "
        f"Found: {', '.join(violations)}"
    )

Where AGENTS.md belongs

AGENTS.md still has an important role. It should contain durable operating instructions that apply broadly to work in its scope: how the agent should work, which validation commands are authoritative, which boundaries must be respected, and where to find the applicable decision brief.

• Before editing: read the applicable decision brief and inspect existing patterns before adding new abstractions.
• Validation: run the authoritative tests and decision checks; do not claim completion if an applicable decision is unresolved.
• Repository boundaries: do not edit generated files; keep domain code independent from infrastructure adapters.

A worked repository example

Suppose a coding agent is asked to add cloud synchronisation to desktop workspaces. The repository contains decisions covering SQLite for desktop state, PostgreSQL for hosted services, offline-first sync, explicit user conflict resolution and idempotent background jobs.

A weak workflow sends the task and the whole repository to the agent. A better workflow evaluates the affected areas — apps/desktop/**, services/sync/** and packages/protocol/** — and routes only the decisions that govern those boundaries.

The implementation brief makes the boundaries explicit: desktop state remains in SQLite; the hosted synchronisation service may use PostgreSQL; the client must continue accepting local writes while offline; conflicting updates must not be resolved silently; and retrying a synchronisation job must not duplicate effects.

• Dependency validation for desktop storage.
• Migration tests for both databases.
• An offline integration test.
• A conflict-resolution test.
• Idempotency tests for retry behaviour.
• Human review of the user-facing conflict experience.

What this changes for agent governance

Teams often frame coding-agent governance as a permissions problem: which commands the agent can run, whether it can access the network, whether it can merge a pull request, and whether it can modify production infrastructure. Those controls matter, but they govern what the agent is allowed to do.

Decision governance addresses a separate question: how does the agent know which technical choices have already been made, where they apply, and whether its implementation contradicts them? A sandbox cannot answer that. A longer prompt cannot answer it reliably. A folder of unread ADRs cannot answer it.

The answer is a system that delivers relevant decisions into the work and checks the results where possible.

The practical model

Use AGENTS.md for stable working instructions. Use decision records for meaningful choices and their rationale. Add explicit scope so decisions can be matched to code, components and tasks. Route only applicable decisions into each agent session. Turn enforceable decisions into deterministic checks. Require human review for decisions that remain contextual, experiential or organisational.

The result is not an agent that blindly follows a bigger prompt. It is a development process in which decisions remain connected to the work they govern.

Conclusion

AGENTS.md is a useful repository interface for coding agents. It can explain how to build, test and navigate a codebase. It can reinforce local conventions and point the agent towards the right tools.

It is not a decision system. A decision system must preserve why a choice was made, identify where that choice applies, bring it into the relevant task, and verify compliance where verification is possible.

Without recording, decisions disappear. Without routing, they are ignored. Without enforcement, they remain suggestions.