We Scanned 34,266 Repos. 1 in 4 Orgs Showed Gaps In AI Agent Config Files

Teams are shipping code with AI coding assistants such as Claude Code, Cursor, and GitHub Copilot, increasingly guided by repository-level instruction files. The problem is that most teams treat these files like informal documentation rather than the production-level configuration they have become.

We ran AgentLinter across 34,266 repositories to see how organizations are actually managing their agent instruction files. The findings reveal a consistent gap: ambiguous instructions, missing failure behavior, and security risks that would never pass review in application code. This article breaks down what we found and what it takes to enforce the same discipline on agent configs that you already apply to the rest of your codebase.

In this article:

• Why agent configuration files require security controls
• What we found across 34,266 repositories
• Finding 1: Ambiguity is the most common issue
• Finding 2: Missing escape hatches create runaway behavior
• Finding 3: Security issues are lower volume but higher severity
• Why defined rules are not the same as enforced rules
• What good enforcement looks like for agent instructions
• How to harden agent config files this week
  
  

Why agent configuration files require security controls

Securing AI agent configuration files in software repositories comes down to a few core practices: externalize secrets instead of hardcoding them, enforce strict access controls, validate configurations for clarity and safety, and continuously scan for potentially leaked credentials. The problem is that most teams have not yet started treating agent config files with the same discipline they apply to application code. A McKinsey survey found only ~30% of organizations at AI governance maturity level 3 or higher.

AI coding agents like Claude Code, Cursor, and GitHub Copilot rely on repository-level instruction files to guide their behavior. You might recognize names like CLAUDE.md, .cursorrules, copilot-instructions.md, or AGENTS.md. The files tell the agent what coding standards to follow, which directories to avoid, how to handle errors, and what commands it can run.

Here is where the risk comes in. Agent instruction files influence how agents read code, make edits, run shell commands, and interact with sensitive data. Yet teams often author and review them with less rigor than a typical pull request. When an instruction file is vague, contradictory, or contains hardcoded secrets, the agent amplifies that weakness across every task it performs.

Traditional documentation is interpreted by humans who can infer intent and ignore irrelevant details. Agent instruction files, on the other hand, are consumed by LLM-based systems that act on the text directly. Human docs guide judgment. Agent configs shape execution.

What we found across 34,266 repositories

We ran AgentLinter, an open-source static analysis tool for AI agent configuration files, across 34,266 repositories with the feature enabled. The scan covered 1,353 organizations.

The results showed a clear gap between how teams treat application code and how they treat agent instructions:

• 1,604 repositories had issues flagged in their agent config files
• 354 organizations had at least one repository with findings
• Over 13,000 issues related to comprehensibility and clarity
• Nearly 5,000 issues related to missing escape hatches
• Approximately 1,150 issues related to security risks

The findings break down into three categories: ambiguity, missing failure behavior, and security vulnerabilities. Each category represents a different kind of risk, but they share a common root cause. Teams are giving agents production-level influence without production-level enforcement over the rules that guide them.

Finding 1: Ambiguity is the most common issue

The most frequent problem we found was unclear instructions. More than 7,700 instances of undefined terms appeared across the scanned repositories. Other common issues included vague directives and overly complex sentences that an agent cannot reliably interpret.

LLM-based agents are highly sensitive to unclear language. When an instruction says "format code properly" or "follow best practices," the agent has to infer what that means. Different agents, or even the same agent on different runs, may interpret it differently.

Consider the difference between weak and concrete instructions:

The weak versions force the agent to guess, while the concrete versions give it something testable to follow.

When instructions are ambiguous, you get more hallucinated behavior, more inconsistent code changes across repositories, and more reviewer effort to correct avoidable mistakes.

Finding 2: Missing escape hatches create runaway behavior

Nearly 5,000 occurrences of missing escape hatches appeared in the scan. Another 2,000+ instances involved duplicate or contradictory instructions.

An escape hatch is an explicit instruction that tells the agent what to do when something goes wrong. Traditional software has error handling: exceptions, retries, timeouts, fallbacks, escalation paths. Agent workflows benefit from the same concept. Without explicit failure behavior, agents may loop on the same failing command, keep editing unrelated files, invent missing context, or continue after a tool failure.

A common anti-pattern we observed is teams trying to fix bad agent behavior by repeating stronger instructions:

• "Never do this."
• "Absolutely never do this."
• "I repeat, never do this."

Repeating instructions increases context size and can make behavior harder to reason about without necessarily improving enforceability. Duplicate and contradictory rules make behavior less predictable, not more controlled.

Better patterns give agents explicit fallback paths:

• Stop conditions: "If tests fail twice with the same error, stop and summarize the failure."
• Missing context handling: "If a required secret or credential is missing, do not invent one. Ask the user for the required setup."
• Structure validation: "If the repository structure does not match the instructions, stop and report the mismatch."
• Destructive command confirmation: "If a command requires destructive flags, ask for confirmation before running it."

An agent without an escape hatch behaves like a script without error handling. It will keep going until something external stops it.

Finding 3: Security issues are lower volume but higher severity

Security-related findings were smaller in volume but represent the highest-risk category:

• 449 instances of dangerous command permissions
• 437 instances of PII exposure risks
• 71 data exfiltration vulnerabilities
• 21 hardcoded secrets in agent files

Agent configuration files can define what the agent is allowed to read, write, run, or transmit. Because the files are often Markdown or lightweight configuration, teams may not treat them as security-sensitive. But they are: the OWASP Top 10 for Agentic Applications identifies excessive agency and tool misuse as critical risks in these systems.

Examples of risky patterns we found:

• API keys or tokens committed directly into instruction files
• User data pasted into examples without masking
• Overly broad permission to run shell commands
• Unsafe command patterns such as curl | bash
• Instructions that allow copying proprietary code or data into external services

The agent may act on risky instructions repeatedly. Unsafe rules can be copied across many repositories. Reviewers may ignore agent files because they look like documentation. Existing scanners may not classify agent config files as high-risk policy surfaces.

Tip: Treat agent config files as part of the application security boundary. They belong in the same category as CI/CD configuration, infrastructure-as-code, and environment variable definitions.

Why defined rules are not the same as enforced rules

Many teams already have informal expectations for agent behavior. The issue is that expectations are scattered across README files, internal docs, chat messages, copied prompt snippets, and repository-specific config files.

The result is a familiar enforcement gap:

• A policy exists somewhere
• Developers interpret it differently
• Repositories drift
• Reviewers catch issues inconsistently
• CI/CD does not reliably enforce the standard

Governance maturity is lagging behind AI adoption. Gartner predicts that, by 2027, 40% of enterprises will demote or decommission autonomous AI agents because governance gaps will only become apparent after production incidents. Agent safety depends less on writing a perfect prompt once and more on enforcing acceptable instruction patterns wherever changes happen.

What good enforcement looks like for agent instructions

Effective enforcement for agent configuration files follows the same principles as code quality and security enforcement. You scan where developers work, treat clarity as a quality issue, require explicit failure behavior, and apply security policy to agent configs.

• Scan agent files where developers work. IDE feedback catches issues early. Git hooks provide fast local feedback. Pull request checks give review visibility. CI/CD enforcement ensures organization-wide consistency.
• Treat ambiguity as a quality issue. Flag undefined terms, vague instructions, and overly complex sentences. Encourage concrete wording that an agent can follow consistently.
• Require explicit failure behavior. Check for missing escape hatches. Require stop conditions for repeated failures. Require escalation paths for uncertainty or unsafe commands.
• Detect contradictions and prompt bloat. Flag repeated instructions and conflicting rules. Reduce unnecessary context that increases unpredictability.
• Apply security policy to agent configs. Run secrets detection on agent files. Flag dangerous command permissions. Detect PII exposure patterns. Check for exfiltration-prone instructions. Require review for permissions that allow command execution, network access, or access to sensitive paths.
• Make ownership explicit. Assign maintainers for shared agent rules. Use CODEOWNERS or equivalent review routing for agent config changes. Keep organization-level policy separate from repository-specific guidance where possible.
  
  

How to harden agent config files this week

If you are looking to improve the security and reliability of your agent configuration files, here is a practical checklist:

• Inventory all agent instruction files across repositories (CLAUDE.md, .cursorrules, AGENTS.md, copilot-instructions.md, and similar)
• Add agent config files to code review scope explicitly
• Run linting against agent config files to catch ambiguity, missing escape hatches, and security issues
• Remove hardcoded secrets, tokens, customer data, and production examples
• Replace vague instructions with concrete rules
• Add escape hatches for failed tests, missing context, command failures, and uncertainty
• Remove duplicate or contradictory instructions
• Restrict dangerous shell commands and require confirmation for destructive operations
• Add PR checks so agent config changes cannot bypass review
• Track recurring findings across repositories to identify shared policy problems

The path forward is straightforward. Write clearer instructions. Define failure behavior. Remove dangerous permissions and sensitive data. Enforce checks consistently across repositories.

If agent instructions affect production code, they deserve the same engineering discipline as production code.