CLAUDE.md security rules often outpace agent controls

At a glance

What this is: This analysis shows that most CLAUDE.md security rules written for coding agents cannot be fully enforced by built-in controls, leaving developers with policy intent but no reliable enforcement signal.

Why it matters: IAM and NHI teams need to treat agent instructions as governance artefacts, because security rules that cannot be enforced create false confidence across autonomous and human-reviewed development workflows.

By the numbers:

• Only 4.4% of the rules had a control covering the whole rule.
• The extractor caught 66.3% of the security rules in a file.
• The corpus included 481 public CLAUDE.md files.

👉 Read Cakewalk's analysis of CLAUDE.md security rules and agent control gaps

Context

CLAUDE.md security rules are developer-written instructions that an AI coding agent reads before taking action. The problem is not that teams lack policy language, but that the policy language often has no matching enforcement primitive inside the agent’s control model.

That creates a governance gap for agentic AI identity and broader NHI oversight. If a rule cannot be expressed as a control, then access decisions, approval expectations, and action constraints may exist only as text, not as an enforceable boundary.

Key questions

Q: What breaks when CLAUDE.md rules do not map to agent controls?

A: The rule becomes advisory instead of enforceable. Developers may believe the agent is constrained, but the platform cannot actually stop the action, verify the condition, or require approval. That creates a governance gap where policy intent exists without a technical boundary, which is especially dangerous for secret handling and release operations.

Q: Why do security rules for coding agents fail in practice?

A: They fail when the rule depends on context the control cannot see, such as content, system state, or a human approval moment. A built-in agent permission model may handle commands, but it often cannot express the full condition that makes an action unsafe. The result is partial enforcement and false confidence.

Q: How can teams tell whether a CLAUDE.md rule is actually enforceable?

A: Check whether the platform can bind the rule to the exact action, target, condition, and approval path. If any one of those is missing, the rule is not fully enforceable. Teams should test the rule with realistic agent actions, not just read the text and assume the control exists.

Q: Should organisations rely on natural-language instructions for agent governance?

A: No, not on their own. Natural-language instructions are useful for intent, but governance requires machine-enforced checkpoints, logging, and review states. If the agent can still execute the action without a technical gate, the instruction is guidance, not control. Policy text should complement, not replace, enforcement.

Technical breakdown

Why built-in agent controls miss written security rules

The paper’s central finding is that agent controls typically operate on commands, files, or allow and deny lists, while CLAUDE.md rules often describe conditions, meaning, or approval context. A rule such as never commit secrets requires the system to interpret content, not just path or command metadata. That mismatch matters because a control can only enforce what it can represent. When the control model is narrower than the written instruction, the rule becomes guidance rather than governance.

Practical implication: teams must test whether every policy statement written for coding agents maps to an enforceable control.

Why approval language does not equal human-in-the-loop control

The phrase ask before sounds like an approval workflow, but the paper shows that wording alone does not put a person into the execution path. Human-in-the-loop is a control state, not a natural-language instruction. If the agent can still decide, time, or complete an action without an actual approval gate, the written rule has no operational force. This is especially important where code changes, release actions, or data deletion requests are involved, because the review moment must be technically enforced, not implied by text.

Practical implication: validate that approval is a real execution gate, not a comment the agent can ignore.

Why write-only policy channels create false confidence

The article describes CLAUDE.md as a write-only channel because developers can publish rules but cannot see whether the agent can enforce them. That is a governance problem, not a documentation problem. In practice, organisations may overestimate protection when the agent simply lacks the control surface to comply. The issue is similar to any identity system where policy intent and enforcement are disconnected: the rule may exist, but the environment still allows the action.

Practical implication: treat unenforceable agent instructions as risk statements until they are tied to real controls and telemetry.

NHI Mgmt Group analysis

Write-only policy is a control failure, not a documentation quirk. CLAUDE.md lets teams state rules for coding agents, but the article shows that most rules do not map to built-in controls. That means the security team can publish intent without being able to prove enforcement. In identity terms, the policy exists outside the enforcement plane, which makes it ineffective as governance.

Content-based and condition-based rules expose the limit of command-level control. Rules such as never commit secrets or only publish during a release require the agent to understand content, context, and state. A control that only sees commands or locations cannot represent the condition that makes the action wrong. Practitioners should read this as a structural mismatch between policy language and control design.

Approval wording does not create approval authority. The paper’s ask before example shows that natural-language instructions can imply human review without actually enforcing it. That matters for agentic AI governance because the boundary between suggestion and gate is operational, not linguistic. Organisations need to assume that any approval language without a technical checkpoint is advisory only.

Runtime governance gap: the missing control is not the rule itself, but the ability to bind the rule to the exact action, condition, and approval path the agent must follow. The article’s 4.4% coverage rate shows how often that binding fails in practice. For practitioners, this means governance must move from text-first policy writing to control-first design for agent actions.

Autonomous or semi-autonomous coding agents invalidate human-paced governance assumptions. Access review and policy review processes assume a person can inspect intent, assess output, and intervene before harm occurs. When the agent can act at runtime with its own tool and timing decisions, that assumption weakens sharply. The implication is that agent governance needs machine-enforced checkpoints, not just policy prose.

From our research:

• The average estimated time to remediate a leaked secret is 27 days, despite 75% of organisations expressing strong confidence in their secrets management capabilities, according to The State of Secrets in AppSec.
• Only 44% of developers are reported to follow security best practices for secrets management, which helps explain why policy intent often outruns actual control behaviour.
• If your programme is moving from human-managed secrets to coding agents, Analysis of Claude Code Security shows why agent governance needs operational controls, not just written rules.

What this signals

Teams that are expanding into agentic development should expect a growing mismatch between policy intent and enforcement reality. A rule written into a repo is not the same thing as a policy enforced by the execution layer, and that distinction will matter more as coding agents touch release paths, secrets, and deployment workflows.

Runtime governance gap: the next phase of agent security will be measured by whether organisations can prove that written instructions translate into blocking controls, approval gates, and auditable outcomes. That is the difference between guidance and governance.

For practitioners building an AI coding agent programme, the priority is to inventory which instructions depend on human interpretation and which can survive machine-enforced testing. The closer the agent gets to privileged operations, the more valuable a control-first model becomes.

For practitioners

• Map every CLAUDE.md rule to an enforceable control Review each written rule and verify that the agent platform can technically enforce the same action, target, condition, and approval path. If any of those elements cannot be bound in control logic, classify the rule as advisory and track the gap separately.
• Separate approval language from true approval gates Audit any ask before or similar wording and confirm that the agent cannot continue until a real human checkpoint or policy engine decision occurs. If the review is only textual, it is not a control and should not be counted as one.
• Test content, condition, and data-flow rules explicitly Prioritise rules that depend on secret material, release state, or outbound model calls, because these are the cases where command-level controls usually fail. Build test cases that prove the control can see the same context the rule depends on.
• Treat unenforceable agent instructions as governance debt Record each policy statement that lacks a matching control as an open risk, then assign ownership for either control implementation or rule removal. A policy that cannot be enforced should not remain in production as if it were protection.

Key takeaways

• Most CLAUDE.md security rules do not have an equivalent built-in control, so text-based policy alone cannot be treated as enforcement.
• The 4.4% control coverage figure shows a structural gap between what developers write and what the agent platform can actually constrain.
• Practitioners need to map agent instructions to real execution gates, or they will keep confusing governance language with governance control.

Key terms

• Write-only policy channel: A governance channel where people can publish security rules but cannot verify whether an identity system can actually enforce them. In practice, the policy exists as text, while the control plane lacks the same expressive power, creating false confidence and weak operational accountability.
• Human-in-the-Loop (HITL): A governance pattern requiring human approval before an AI agent takes high-impact, irreversible, or out-of-scope actions. HITL is a critical control for agentic AI identity governance.
• Control Coverage: Control coverage is the degree to which security controls actually match the assets, identities, and data flows they are meant to protect. A programme can look mature on paper while still missing blind spots if discovery, classification, and enforcement are not aligned.
• Agentic Runtime Governance Gap: The distance between approving an AI agent as a project artefact and controlling its actual production behaviour. This gap appears when static approvals, access reviews, or policy documents do not keep pace with the agent’s live tool use and changing operational context.

What's in the full report

Cakewalk's full analysis covers the operational detail this post intentionally leaves for the source:

• The paper’s rule classification method, including how candidate security segments were extracted from 481 public CLAUDE.md files.
• The breakdown of rule types that failed to map cleanly to built-in controls, including condition-based, content-based, access-control, and data-flow cases.
• The confidence interval and adjudication method behind the 4.4% coverage figure, which matters if you need to assess the strength of the evidence.
• The exploratory corpus characteristics, including the relevance-ranked GitHub sample and why the authors do not generalise the result to all projects.

👉 Cakewalk's full article covers the rule extraction method, coverage ranges, and error analysis in more detail.

Deepen your knowledge

NHI governance, agentic AI identity, and machine identity security are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are responsible for identity security strategy or programme maturity, it is worth exploring.