How should security teams test whether a coding agent will obey instructions in a repository README?

Create a scratch repository and put one plain instruction in the README for each permission the agent already has, such as running a setup target, writing environment data, contacting a host, or pushing a branch. Then give the agent an unrelated task and review the runtime record to see which actions it actually completed. The result shows which permissions the README can borrow today.

Testing whether the README can actually steer a coding agent

The practical question is not whether the README is readable, but whether it changes what the agent can do when instructions compete with the task prompt, available tools, or repository state. That matters because README text often acts like an implicit policy layer for coding agent, yet the agent may treat it as guidance rather than a binding constraint. Security teams should test the README against permissions the agent already has, not against hypothetical powers it does not.

That distinction is important for agent governance, because the failure mode is usually silent permission borrowing: the README appears advisory, but the agent still uses existing write, network, or branch actions in ways the team did not intend. For agentic systems, this sits squarely in the trust boundary between declared instructions and executable capability. OWASP Agentic AI Top 10 treats instruction handling and tool abuse as core risk areas, which is why test design should measure obedience against concrete permissions rather than against prose quality alone. In practice, many teams discover README overreach only after an agent has already executed a side effect they assumed was just documentation.

How to structure a meaningful obedience test

A useful test isolates the README as the variable being evaluated. Start with a scratch repository, then seed the README with one unambiguous instruction per existing permission, such as invoking a setup target, writing environment data, contacting a host, or pushing a branch. Keep each instruction simple enough that success or failure is observable in the runtime record. The point is not to see whether the agent can solve a hard task, but whether it treats README text as an instruction source when the task itself is unrelated.

Then assign a separate task that does not require those README actions. If the agent still performs the README-listed steps, the README is functioning as a borrowed privilege path, not merely documentation. If it ignores them, that does not prove the README is harmless in all contexts, only that the tested task did not create a strong enough execution opportunity. The result is strongest when the runtime record includes the command history, file writes, network attempts, and any branch activity, because those are the concrete behaviours that show obedience or resistance.

Use only permissions the agent already has, so the test measures instruction uptake, not escalation.
Write one instruction per capability, so the result maps cleanly to a specific action.
Keep the unrelated task stable, so changes in behaviour are attributable to the README.
Review the execution trace, not just the final output, because partial compliance still matters.

OWASP Top 10 for Agentic Applications 2026 is useful here because it frames agent behaviour in terms of observable misuse paths rather than abstract intent. This approach breaks down when the agent has no auditable runtime trace or when the repository setup already contains instructions that blur the test signal.

Where the test becomes noisy or misleading

Tighter agent testing often increases setup overhead, requiring teams to balance repeatability against how close the test stays to real developer workflows. The main edge case is instruction ambiguity: if the README is vague, the agent may appear compliant while actually choosing its own interpretation. Another is tool coupling, where a single action like “prepare the repo” can legitimately trigger several sub-actions, making it harder to tell whether the README changed behaviour or merely accompanied normal execution.

There is also a difference between testing instruction obedience and testing safety boundaries. A coding agent may obey a README instruction exactly and still behave unsafely if the instruction itself is harmful, overbroad, or placed where the agent is likely to treat it as higher priority than the task prompt. For that reason, guidance-vs-consensus is still unsettled on how much weight a README should carry relative to higher-level system policy, and teams should treat their own agent stack as the deciding reference, not assume a universal hierarchy. Where network access, branch pushes, or environment writes are involved, the test should be treated as a trust-boundary exercise, not just a prompt-quality check. In practice, the most misleading results come from setups where the agent’s normal workflow already resembles the README instructions, making obedience look higher than it really is.

Risk and Threat Considerations

README-driven agent behaviour creates a material trust and exposure risk when repository text can steer actions that touch files, credentials, network destinations, or version control state. The concern is not just accidental compliance. A malicious or compromised repository can use ordinary-looking instructions to redirect an agent into making changes, contacting external systems, or disclosing data under the appearance of routine development work.

Failure mechanism: The agent treats repository prose as actionable guidance and executes it within already-granted permissions, allowing instruction content to become an abuse path for write, network, or branch operations.

Impact: The team can lose control over what the agent touches, what it sends, and what it commits, which creates integrity, confidentiality, and provenance problems that are hard to separate after the fact.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

OWASP Agentic AI Top 10 and MITRE ATT&CK address the attack and risk surface, while NIST AI RMF and CIS Controls v8 set the governance and control requirements practitioners need to meet.

Framework	Control / Reference	Relevance
OWASP Agentic AI Top 10	A1 — Prompt and Instruction Injection	README text can steer agent behavior through injected instructions.
	A2 — Tool and Action Misuse	The question measures which permitted actions the agent will actually execute.
	A5 — Excessive Agency and Permission Sprawl	The test is built around actions the agent already has permission to take.
Recommendation — Test whether repository instructions can override or redirect the agent's intended task. Validate that agent tool use stays within intended boundaries and review every executed action. Limit agent permissions so repository instructions cannot borrow broader access than intended.
NIST AI RMF	GOVERN — GOVERN	The issue is governance of how agent instructions are trusted and evaluated.
Recommendation — Establish governance for when repository instructions are authoritative and how they are tested.
CIS Controls v8	6.3 — Access Grants and Revocation	Agent permissions determine which README instructions can be executed.
	8.2 — Audit Log Management	The runtime record is the evidence base for whether the agent complied.
Recommendation — Review and constrain the access the agent can use before testing instruction obedience. Retain execution logs so each agent action can be attributed and reviewed.
MITRE ATT&CK	T1204 — User Execution	The README is acting as an instruction source that can induce actions.
Recommendation — Map repository-triggered actions to induced execution paths and hunt for coercive instruction patterns.

Practitioner Guidance

What to verify: Verify that the test has a clean separation between task intent and README instructions. If the agent obeys the README only when the task naturally calls for the same action, the signal is weak; if it obeys unrelated README steps, the README is functioning as an active control surface.

What practitioners underestimate: Teams often focus on whether the agent followed the instruction, but the more important question is whether the instruction changed the agent’s use of existing permissions. That distinction determines whether the README is merely descriptive or operationally influential.

Practitioner takeaway: Treat README obedience as a capability test, not a documentation test, and judge it by observed side effects within existing permissions rather than by whether the agent sounded compliant.