PaperlayerView exact revision on arXiv

Source-linked AI summary

When "Do Not" Is Not Deny: Security Rules in CLAUDE.md vs Built-In Controls

Ting Yan

arXiv:2608.23550v1cs.HCcs.CR

TL;DR

Developers write security rules in CLAUDE.md without feedback about whether Claude Code can enforce them, creating a gap between natural-language intent and built-in control. The paper measures this gap across public files using classifier-based matching and blinded practitioner validation, finding that only a small minority of retrieved security rules have matching controls. The results are limited to the extracted rules and the studied Claude Code documentation and sampling frame.

  • Problem

    CLAUDE.md is a write-only security channel: developers cannot tell from the file or agent application whether a written rule will be enforced.

  • Method

    The study analyzes 481 public CLAUDE.md files, matches extracted candidate rules against documented Claude Code controls, and validates a stratified sample with two blinded security practitioners.

  • Results

    Only about 4–16% of retrieved security rules had a matching built-in control; under the strict, adjudicated standard, the estimate was 4.4% (95% CI: 2.6–6.7%).

  • Takeaways & Limitations

    The same prose form covers rules enforceable by platform controls and rules left to model interpretation, while the file and agent do not mark which case applies.

  • Takeaways & Limitations

    The reported rates apply to extracted rules in a capped, nonrandom public-file frame and do not measure other enforcement, repository configuration, or runtime effectiveness.

Abstract

from arXiv · show

In CLAUDE.md, "do not" is a natural-language instruction that the model interprets. Claude Code's deny is a built-in control that blocks an action before the agent can take it. Both can express the same security goal, but they control the agent in different ways. We measure this gap in 481 public CLAUDE.md files. An LLM matched the extracted candidate rules against Claude Code's documented controls, and two security practitioners independently checked a sample without seeing the model's answers or each other's labels. Depending on how closely a control had to match the written rule, only about 4-16% of the retrieved security rules had a matching built-in control. Under the strictest standard the estimate was 4.4% (95% CI: 2.6-6.7%), and the two annotators agreed closely on which rules had a match. A manual review of complete files found that our extraction method captured 66.3% of eligible security rules; the reported rates therefore apply to the rules it captured. This is a usable security problem: CLAUDE.md is a write-only channel. A developer writes a security rule but gets no feedback on whether a control will enforce it. The same plain-text form hides two kinds of rule: those a permission rule, mode, or sandbox can enforce, and those left to the model to interpret.

I. INTRODUCTION

Natural-language security rules in CLAUDE.md provide no feedback about enforcement, even though some can be applied by built-in controls while others depend on model interpretation. This paper measures how often written rules have matching Claude Code controls.

  • I. INTRODUCTION: CLAUDE.md security rules are write-only: developers receive no signal about whether the platform will enforce what they wrote.Unlike compilation, tests, or runtime logs, the instruction file and agent application return no enforcement feedback.
  • I. INTRODUCTION: Built-in permissions or sandbox restrictions can directly apply some rules, while others remain text for the model to interpret.For example, “Never run npm publish” can be checked before execution, whereas identifying customer secrets in logs requires model judgment.
  • I. INTRODUCTION: Prior studies describe security content in agent instruction files but do not test whether each written rule has a matching control.Other systems generate executable checks or policies, showing that stronger controls can be built rather than measuring existing coverage.
  • I. INTRODUCTION: The study analyzes 481 public CLAUDE.md files by extracting candidate rule segments, classifying their security relevance and control matches, and validating 180 segments with two practitioners.The practitioners reviewed the sample without seeing the model’s answers or each other’s labels.
  • I. INTRODUCTION: The central research question is what percentage of extracted security rules in public CLAUDE.md files have a matching Claude Code control requiring no extra code.The paper frames this as a usable-security problem because the same prose form hides enforceable and model-interpreted rules.
  • I. INTRODUCTION: Only about 4–16% of retrieved security rules had a matching built-in control, depending on the required strictness of the match.The paper also groups rules by issues such as authorization, destructive actions, and secrets.

A. What developers write in coding agent instruction files

Prior work shows that developers use coding-agent instruction files to express security-related guidance, but it does not establish whether built-in controls can enforce those rules. This paper examines that unresolved coverage question from the developer’s perspective.

  • A. What developers write in coding agent instruction files: Security-related content appears in 14.8% of 2,303 agent instruction files and about 4.4% of coded instructions in 12,110 Cursorrules files.These studies characterize what developers write rather than whether each rule has a matching control.
  • A. What developers write in coding agent instruction files: Prior studies also examine instruction-file configuration, growth over time, and how developers express values and responsibilities.Together, this work describes the contents and use of instruction files without measuring built-in enforcement coverage.
  • B. Why a written rule is not a security control: A plain-language security instruction does not itself block commands, prevent file writes, or stop network requests; the model decides how to act.Evidence also indicates that instructions may be ignored inconsistently and that adding rules can help without closely tracking their wording.
  • B. Why a written rule is not a security control: Systems including ContextCov, Prose2Policy, and AutoCedar convert prose into executable checks or verified policies.Other approaches insert monitors between agents and the tools they use.
  • C. Permission systems and the developer’s security work: Agent-security research proposes controls for tool arguments, runtime conditions, permissions, filesystems, isolation, data access, and permission graphs.Michael and Roesner compare permission mechanisms across research proposals and five commercial agents, including Claude Code.
  • C. Permission systems and the developer’s security work: This study differs by starting with rules developers already wrote and asking whether an existing Claude Code control can apply the same rule.Related work measures protected-object coverage or governance observability rather than the frequency of matching controls for written rules.
  • C. Permission systems and the developer’s security work: Natural-language access-control intent can exceed what systems represent, leaving developers to resolve the gap between policy and available enforcement.The paper measures how often Claude Code can resolve that gap through an existing matching control.

D. What existing evaluations measure

Existing evaluations mainly test instruction following, runtime blocking, configuration, or policy coverage after a rule or control has been chosen. This paper instead measures whether a matching built-in control exists for a developer-written security rule.

  • D. What existing evaluations measure: Instruction-following benchmarks test whether models obey rules presented through different instruction files.They evaluate model behavior after an instruction has already been selected.
  • D. What existing evaluations measure: Runtime studies test whether controls stop agents, including under concurrent execution, while other work examines operator configuration of available controls.These evaluations address later stages than the existence of a matching control.
  • D. What existing evaluations measure: The study asks whether a matching built-in control exists, separately from enabling or configuring it, runtime reliability, and model compliance with prose.If no match exists, the rule remains dependent on model interpretation unless another check is added.
  • D. What existing evaluations measure: Policy-as-code studies measure whether formal policy languages cover vendor or regulatory requirements, not real security rules written for coding agents.The paper supplies the missing percentage for developer-written coding-agent rules.
  • D. What existing evaluations measure: The method collects files, retrieves candidate rule segments, classifies security relevance and control matches, and checks results against human labels.A security rule concerns what an agent must, must not, or may do when violation could expose or alter data, interrupt systems, bypass permissions or approvals, or harm privacy.
  • D. What existing evaluations measure: A built-in control is configurable without executable code, while a matching control must cover the rule’s action, target, wrongness condition, and required approver.The main label records whether such a matching control exists; secondary reasons for nonmatches are exploratory and not manually checked.

B. Corpus and sampling

The primary corpus is a frozen, relevance-ranked slice of public GitHub CLAUDE.md files rather than a random sample. A single pipeline filters repositories and files, extracts and classifies segments, and samples records for annotator reference labels.

  • B. Corpus and sampling: The primary frame contains public CLAUDE.md files retrieved from GitHub code search on 2026-08-14, which returns at most 1,000 relevance-ranked results per query.The authors therefore limit claims to this capped convenience frame.
  • B. Corpus and sampling: Each repository contributes one primary CLAUDE.md, which must be non-empty, at least 500 characters, English-dominant, pinnable to a commit, and not a fork or mirror.The frozen pool, manifest, and random seed support reproducibility.
  • B. Corpus and sampling: The study repeats the classifier measurement on the independent Agent READMEs corpus because the primary frame is a convenience sample.The second frame tests whether the estimated rate and rule-family pattern replicate under a different published corpus.
  • B. Corpus and sampling: Figure 1 tracks counts through repositories examined, included files, retrieved and classified candidate segments, security-relevant segments, matching-control segments, and the annotator-reference sample.The figure presents the sampling and classification pipeline with per-stage counts.

C. Primary label and secondary categories

The primary label asks whether a complete written security rule has a matching built-in control, while secondary categories describe why unmatched rules may lack coverage. The secondary categories are exploratory and do not support population claims.

  • Primary label: A matching control must cover the complete rule, using one built-in control or a small set of controls.The headline coverage rate depends only on this binary yes-or-no judgment.
  • Primary label: “Do not run rails credentials” matches because a permission deny rule blocks that exact command, whereas “Never commit secrets or tokens” does not.The latter requires an added secret scanner or pre-commit hook because built-in controls cannot inspect commit content.
  • Secondary categories: Unmatched rules receive one secondary reason in priority order: missing-context, custom, or model-mediated.These categories distinguish unavailable information, extra code requirements, and rules left for the model to judge.
  • Secondary categories: The secondary reasons lack human-reference validation and are retained only for transparency and hypothesis generation.No percentage or ordering from this split answers the research question or supports a population claim.
  • Control boundary: Hooks are excluded from the built-in-control set, alongside the documented permission, mode, sandbox, and managed restriction controls.The reference table records each control’s inspectable action, target, condition, effect, scope, and official source.

E. Classification and validation

The study retrieves candidate rules with a rule-word parser, classifies them against a frozen control reference, and validates the classifications through blinded practitioner labeling and adjudication. Coverage rates are compared under three matching standards, with the adjudicated strict standard treated as primary.

  • Candidate extraction: The parser retrieves non-code Markdown segments containing predeclared rule words, while the reported results exclude the optional LLM extraction step.Connected clauses remain one segment, and long paragraph lines are split at sentence boundaries.
  • Recall audit: A whole-file audit of 50 randomly sampled files records prospective security rules and excludes text describing only existing architecture or security mechanisms.The audit leaves 95 in-scope reference segments from 135 recorded segments.
  • Classification and validation: An LLM classifies every candidate on security relevance and matching-control status against a frozen reference, naming the specific control for claimed matches.The prompt counts uncertain cases as matches to discourage false negatives, but the classifier is treated as a measurement instrument rather than the authority.
  • Classification and validation: Two security practitioners independently label a stratified sample of 180 candidates while blind to model and each other’s labels, then disagreements are adjudicated against the frozen control reference.Inverse-probability weights account for the three strata, whose population sizes are 3,791, 726, and 144 rows; recall auditing remains single-annotator.
  • Coverage estimates: Three loose-to-strict matching standards are reported, combining a full-corpus classifier rate with weighted human estimates and repository-clustered 95% confidence intervals.The adjudicated strict standard is designated the primary estimate.

A. Overall coverage rate

Built-in-control coverage is low across retrieved CLAUDE.md security rules, and the estimate varies mainly with how strictly a control must match the complete rule. Family-level comparisons are exploratory because agreement on family labels is limited.

  • Overall coverage rate: 4.4% [2.6, 6.7] of retrieved security rules had a matching built-in control under the strict, adjudicated standard.Under the broader standards, estimated coverage ranges from about 4% to 16%; 95.6% [93.3, 97.4] had no matching control under the strict standard.
  • Reliability and recall: 16.6% coverage was estimated by the full-corpus classifier, but the human reference supported substantially less coverage.The classifier had recall 1.000 and precision 0.350 against the adjudicated reference labels.
  • Reliability and recall: κ = 0.89 agreement was reached on matching-control decisions for the 115 rules both annotators judged security-related.They agreed on 111 of 115 such rules; Gwet’s AC1 was 0.95 and positive-specific agreement was 0.91.
  • Coverage by resource family: 57.1% exact family agreement makes the resource-family breakdown exploratory rather than a human-confirmed ranking.On 91 annotator-reference security-positive rows, raw agreement was 69.2%, with unequal-strata correction producing 57.1% [43.0, 73.2].
  • Coverage by resource family: Destructive commands and network egress received the most classifier-estimated matches, while authorization and personal data received the fewest.These are full-corpus classifier descriptions, not rankings confirmed by the annotator family labels.
  • Coverage by resource family: A matching-control verdict requires one named built-in control to cover the rule’s full action, target, condition, and approval.Representative examples are provided by family in de-identified form.

D. Coverage by rule wording and by control

Coverage varies little by rule wording, while the classifier predominantly associates matched segments with permission controls. Robustness checks leave the low-coverage finding broadly intact, but corpus concentration and sampling-frame limits constrain generalization.

  • Coverage by control: 69% of the 144 classifier-marked matches cited permission deny, while 23% cited permission ask.The remaining 12 citations involved permission allow, network sandbox, permission modes, and filesystem sandbox controls; these citations were not human-verified.
  • Robustness: 17 of 870 security segments were additional copies after normalization, and the largest template cluster contained 4.Equal-weighting templates or repositories, and excluding the largest repositories, left the classifier estimate in the same range.
  • Corpus structure: 870 segments spread across 201 repositories, with a median of 2 and a maximum of 78 per repository.This long-tailed distribution is why the paper clusters every interval by repository.
  • Sampling-frame replication: The second sampling frame also produced a minority coverage estimate, but without annotator reference labels it provides instrument replication rather than independent confirmation.The family gap for destructive commands replicated at 31.5 versus 51.8%.
  • Scope: 93% of segments came from repositories created in 2025 and 2026, and 58% of repositories had no stars.The paper therefore does not extend the rate to large, established projects.

V. DISCUSSION

CLAUDE.md combines rules enforceable by built-in controls with rules left to model interpretation, without indicating which is which. The paper frames this write-only interface as a practical security problem and proposes feedback mechanisms to close the loop.

  • Discussion: Only about 4–16% of written security rules had a matching built-in control, depending on the coding standard.The same natural-language form covers both enforceable rules and rules only the model can interpret.
  • Discussion: CLAUDE.md provides no feedback on whether a written security requirement is backed by a control.Teams may enforce rules through mechanisms outside the file, but the paper does not observe those mechanisms.
  • Discussion: The family breakdown reflects the classifier’s view because agreement with human coding was only moderate.The paper says ranking families would require sharper definitions and a larger sample coded by multiple independent experts.
  • Discussion: A write-only interface may be most dangerous for people least likely to notice that their written rule is unenforced.The motivation links this concern to language models lowering the barrier to software development and many new builders having little security background.
  • Design response: Proposed remedies include showing control coverage, marking unenforceable rules as advisory, logging when controls apply, and turning prose into reviewable checks.Each remedy is intended to restore observable feedback comparable to ordinary software development.

VI. LIMITATIONS

The study’s scope is limited to written CLAUDE.md rules and documented Claude Code controls, not broader runtime or organizational enforcement. Results also depend on classifier judgment, sampling, documentation completeness, and extraction recall.

  • Scope: The analysis measures whether rules as written in CLAUDE.md have documented matching Claude Code controls, not whether teams enforce them through other tools.It does not assess repository configuration, runtime behavior, continuous integration, hooks, or organization tooling.
  • Classification judgment: 14–17% of rules matched under a loose reading, compared with about 4% under a strict reading.The reported rate depends substantially on how closely a control must match the written rule.
  • Reliability: κ = 0.89 for annotator agreement on matching-control decisions, versus κ = 0.77 for deciding whether a segment was a security rule.The family breakdown is treated as exploratory because it rests on one human-coding round with only moderate agreement.
  • Generality: The findings are bounded to Claude Code’s documented controls on the freeze date and to public CLAUDE.md files, which are not a random sample.A control-reference audit found one imprecise entry and one missing credential-protection feature, without proving the reference complete.
  • Extraction recall: The extractor’s 50-file audit found 66.3% recall for eligible security rules, so the reported rates apply to captured rules.Rules written without the predefined rule words can be missed.

APPENDIX A CONTROL REFERENCE (CLAUDE CODE, FROZEN

The frozen control reference defines built-in controls as configurable protections requiring no executable code and preserves the instrument used for classification. It also documents post-hoc reference corrections without silently changing the frozen table.

  • Control definition: A control counts as built-in only when a developer can configure it without writing executable code.The table serves as the shared reference for both the classifier and human coders.
  • Reference maintenance: The frozen reference was reproduced rather than silently repaired after validation.The audit identified imprecise or missing entries, including additionalDirectories and sandbox.credentials, and clarified network-denial conditions.
  • Instrument: The classifier used one prompt frozen before validation and retained the legacy field name first_class for matching-control decisions.In the paper, first_class means that a matching built-in control exists.
  • Matching rule: A matching control had to faithfully bind the rule’s action, resource, and condition without over-blocking a much larger set.The prompt required naming the exact native control and instructed conservative labeling when faithful coverage was uncertain.
  • Qualification: The phrase “upper bound” records an instrument instruction, not a validation-established one-sided error bound.This qualification limits how the prompt’s conservative rule should be interpreted.

MATCHING CONTROL

The secondary analysis categorizes unmatched security rules after the primary matching decision, but its reasons are exploratory and the sampling and release procedures define the study’s reproducibility frame.

  • Secondary categories: The classifier first records whether a security rule has a matching built-in control, then assigns one possible reason for each unmatched rule.The annotator-reference task did not validate these secondary reasons.
  • Interpretation: The secondary category percentages are retained for reproducibility and future hypotheses, not as estimates of how much added code could close the gap.The “custom” share should not be interpreted as the fraction remediable through additional code.
  • Sampling: 481 of 647 repositories examined were included in the primary CLAUDE.md sampling frame.The search targeted repositories containing a file named CLAUDE.md.
  • Replication: The replication frame contained 701 included CLAUDE.md files from the Agent READMEs dataset.This frame changes the sampling source while reusing the same instrument and control vocabulary.
  • Validation: Two security practitioners independently and blindly labeled 180 candidates, with disagreements adjudicated against the frozen control reference.The 91 security-positive rows also received a single blind resource-family pass.
  • Reproducibility: The release includes sampling frames, manifests, the control reference, analysis scripts, aggregate outputs, and bibliography.Per-rule source links undergo harm and license review before release.
Loading 2608.23550v1…