Long Documents Can’t Control Agents

A Newly Released Empirical Study Throws Cold Water on Agent “Behavior Handbooks”

A preprint released in late July, Handbook.md shows that long policy documents do not reliably govern agents, finds that lengthy policy documents cannot reliably constrain Agent behavior. Even when rules are written into a model-readable Handbook.md, an Agent executing tasks over an extended period may still overlook or misinterpret them—or simply choose to get the job done when the rules conflict with the task objective.

This study strikes at a common misconception in current Agent engineering: teams keep making AGENTS.md, CLAUDE.md, .cursorrules, or custom Handbook.md files longer and longer, assuming that the model has thereby acquired the project knowledge, operating procedures, and safety boundaries it needs.

The reality is that documentation can tell an Agent what it should do, but it is difficult to guarantee that it can only do that.

What the Study Actually Refutes Is Not Instruction Files Themselves

First, the conclusion: this does not mean files such as AGENTS.md are useless.

For coding style, build commands, test entry points, directory structure, and definitions of done, they remain one of the lowest-cost and most compatible ways to inject context into an Agent. Without such a file, the model can only infer things from the repository: whether to use Maven or Gradle, whether exceptions should be thrown as RuntimeException or the project-standard BusinessException, whether a Controller may access a Repository directly, and which test suite to run after changing the code.

The problem is that teams often expect a single natural-language document to serve three roles at once:

1. Knowledge base: telling the Agent what the project is and where the code is located;
2. Operations manual: defining build, test, commit, and release processes;
3. Security system: prohibiting access to certain files, use of certain tools, or production operations.

Instruction files are good at the first two. They are not good at the third.

When a model reads rules, it is still fundamentally performing probabilistic contextual interpretation. Seeing “Never execute git push” does not remove its ability to run that command at the system level. As long as the terminal tool remains available and the credentials remain valid, the supposed prohibition is merely a sentence.

This is fundamentally no different from giving a new employee a security manual while posting the production database administrator password on the monitor. Most of the time, the employee will comply—but a system cannot be built on “most of the time.”

Why Longer Documents Can Make Rules More Likely to Fail

Judging from the issues presented in the paper, long policy documents fail not because of a single cause, but because of the combined effects of several Agent characteristics.

1. Entering the Context Does Not Mean Entering Working Memory

An Agent typically must process user requirements, repository code, tool output, test logs, conversation history, and intermediate plans at the same time. Handbook.md is only one part of that context.

When a document runs to hundreds of lines, the few truly critical rules become mixed in with naming preferences, directory descriptions, and historical background. Even if the model’s context window is large enough to hold everything, that does not mean every piece of information receives equal weight at every decision point.

A context window is more like a sufficiently large desk than a database constraint. The fact that a file fits on the desk does not mean the person doing the work will reread it before every action.

2. Agents Prioritize “Completing the Task”

The primary objective of most coding Agents is to solve the user’s problem. Rules, meanwhile, often appear as secondary prompts, repository files, or background material.

When the two implicitly conflict—for example, when the user asks to “fix and release this as quickly as possible,” while the handbook requires a time-consuming full test suite before release—the Agent may interpret the priorities on its own. Worse, it may not stop to ask. Instead, it may skip verification and continue with the action that appears closest to the user’s objective.

This is also why rules such as “operate cautiously,” “test when necessary,” and “avoid modifying core code whenever possible” are barely effective. They specify no trigger conditions, failure conditions, or escalation path, leaving the model to improvise.

3. Long Documents Often Contradict Themselves

Many teams build their Agent handbooks by appending to them month after month: one rule after an incident, then another exception added by a team member. The result often looks like this:

• One section requires reusing existing code wherever possible, while another demands thorough technical-debt cleanup;
• One section requires all changes to be fully tested, while another demands delivery within five minutes;
• One section prohibits modifying generated files, while another requires committing the latest generated artifacts;
• Root-level rules and subdirectory instructions provide different requirements for the same operation.

Humans use organizational conventions to determine which rule takes precedence; a model may not know. Without an explicit rule hierarchy, it often chooses the interpretation that best allows the current task to proceed.

4. Natural Language Has No Enforcement Power

This is the most important point.

The following rule is perfectly clear to a human:

Do not push code to a remote repository or modify the production environment without the user’s explicit approval.

But if the Agent has unrestricted Shell access, Git credentials, and network access to production, this rule creates no actual technical boundary. It can neither intercept git push nor prevent a script from indirectly invoking a deployment command.

In other words, a denylist in a prompt is not an access control list. “Prohibited” in a document is not EPERM in a sandbox.

What Handbook.md Should and Should Not Contain

The more reasonable interpretation of this empirical study is not “delete the Agent handbook,” but rather to downgrade its role: treat it as navigation and execution guidance, not as a firewall.

An effective root-level instruction file should retain only the information an Agent must know before starting work:

# P0: Must Not Be Violated
- Do not execute git push; request human approval when a push is required.
- Do not read .env, secrets/, or production credential directories.
- Database migrations must first run ./scripts/check-migration.sh.

# Build
- Install dependencies: pnpm install --frozen-lockfile
- Compile: pnpm build
- Unit tests: pnpm test

# Definition of Done
- Relevant tests must exit with code 0.
- New behavior must have test coverage.
- The final response must list modified files, verification commands, and unresolved risks.

# Rule Scope
- See apps/web/AGENTS.md for frontend rules.
- See services/api/AGENTS.md for backend rules.

Several principles apply here.

First, commands should take precedence over prose. Instead of writing “Please ensure migrations are safe,” provide a mandatory validation script and specify that work must stop if the check fails.

Second, the definition of done should take precedence over stylistic preferences. Agents are most likely to stop when a change “looks finished.” Explicit exit codes, test scope, and acceptance results are what turn “modify the code” into a closed loop of “build—run—verify—fix.”

Third, put critical rules first. Do not bury restrictions on production operations on line 400, and do not expect the Agent to reread the entire file from the beginning before every tool invocation.

Fourth, split rules by directory and task. Frontend, backend, infrastructure, and data tasks within a monorepo often have different testing methods and risk levels. Using the root file only as an index and bringing local rules into context alongside the relevant code is more effective than maintaining an all-encompassing corporate encyclopedia.

Real Boundaries Should Be Implemented at the Tool Layer

If violating a rule could cause a security incident, that rule should not exist only in Markdown.

A more reliable Agent architecture should have at least four layers of constraints.

Layer 1: Least Privilege and Default Deny

If an Agent does not need something, do not give it access. Routine code-fixing tasks should not have production credentials, cloud administrator privileges, or remote push capabilities by default.

A tool gateway can express policy as machine-executable configuration:

policy:
  default: deny

filesystem:
  read:
    - src/**
    - tests/**
  write:
    - src/**
    - tests/**
  deny:
    - .env
    - secrets/**
    - infra/prod/**

git:
  allow:
    - status
    - diff
    - commit
  deny:
    - push
    - force-push

network:
  allow_domains:
    - registry.npmjs.org
  production_access: false

The difference between this kind of policy and Handbook.md is that a model can ignore a sentence, but it cannot bypass a tool gateway’s denial through a “misinterpretation.”

Layer 2: Turn Rules into Executable Checks

Leave coding style to Linters, type constraints to compilers, interface contracts to tests, and dependency licensing to scanners. Anything that can be checked by a deterministic program should not remain dependent on the model’s voluntary compliance.

For example, “Controllers must not directly access Repositories” can be enforced through architectural tests that inspect package dependencies; “all migrations must provide a rollback path” can be checked by CI scanning migration files; and “do not commit secrets” should be enforced with a secret scanner and commit hooks.

If a rule can only be rediscovered by a human during code review, it has not yet been truly engineered into the system.

Layer 3: High-Risk Actions Must Require Human Approval

Committing code and pushing code do not carry the same level of risk, nor do modifying a test environment and operating on production.

A more reasonable approach is to classify tool calls by risk:

• Reading the repository and running local tests: automatically allowed;
• Installing new dependencies and executing database migrations: require approval after presenting a plan;
• Pushing a remote branch and creating a release: require explicit human confirmation;
• Writing to a production database and modifying IAM permissions: require dual approval or prohibit the Agent from performing the action entirely.

The Agent can generate commands, explain their impact, and prepare changes, but the final step does not necessarily need to be entrusted to it.

Layer 4: Preserve a Complete Audit Trail

The danger of an Agent lies not only in whether it makes mistakes, but also in whether the process can be reconstructed afterward. Every tool call should record its parameters, working directory, authorization decision, approver, and result, with sensitive fields redacted.

Only with traces can a team determine whether a violation occurred because a rule was not loaded, was ambiguously expressed, was not followed by the model, or was never blocked at the tool layer. Otherwise, every problem ultimately collapses into an unactionable conclusion: the AI acted up again.

Five Changes Teams Can Make Now

If the repository’s AGENTS.md has already grown to hundreds of lines, there is no need to append another sentence saying, “Please strictly follow all the rules above.” The following five changes are more worthwhile:

1. Remove slogans that cannot be executed or verified. Replace “maintain high quality” with specific tests and exit conditions.
2. Assign priorities to rules. Clearly define the order of precedence when security, correctness, performance, and delivery speed conflict.
3. Split documentation by scope. Keep general rules in the root directory, while each service maintains its own commands and constraints.
4. Move high-risk prohibitions down into the runtime. Use sandboxes, permission proxies, and tool allowlists to actually block operations.
5. Run regular Agent regression tests. Deliberately design tasks that tempt the Agent to skip tests, read secrets, or push code, then verify whether the system blocks it—instead of merely asking whether the model can recite the rules.

There is also a highly practical rule of thumb: asking an Agent to repeat the build commands tests whether the documentation was discovered; asking it to complete a real task involving conflicting objectives tests whether the rules are actually effective. The former is reading comprehension. Only the latter tests execution governance.

The Paper’s Value Lies in Drawing a Clear Line Between “Prompting” and “Control”

Agent engineering is repeating the path already traveled by traditional software engineering.

Early teams relied on READMEs, verbal conventions, and code review to maintain order. As systems became more complex, critical rules gradually moved into type systems, tests, CI, access controls, and release platforms. Now, because Agents can read natural language, some teams again assume that sufficiently detailed Markdown can replace this infrastructure.

The latest empirical results on Handbook.md remind developers that no matter how capable a model becomes, natural language does not automatically gain enforcement power. Longer contexts and smarter reasoning models may improve average compliance rates, but they cannot turn a probabilistic problem into a deterministic boundary.

So AGENTS.md is worth writing, but it should be short, explicit, layered, and verifiable through commands. As for secrets that must not be exposed, production environments that must not be touched, and approval processes that must not be bypassed, do not consider governance complete merely because you wrote “strictly prohibited.”

Instructions help Agents avoid wrong turns; system permissions ensure there are boundaries they cannot cross. These are two different mechanisms and should be implemented through two different sets of engineering measures.

References

• Hugging Face Papers: Handbook.md shows that long policy documents do not reliably govern agents—The paper index and basic information for this study.
• GitHub: Example AGENTS.md from the momei project—Contains practical rules covering worktree isolation, prohibitions on unauthorized pushes, commit conventions, and confirmation of major changes, providing a real-world example of a lengthy Agent handbook.