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: 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 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. 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: 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. 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. 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: 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: An agent without an escape hatch behaves like a script without error handling. It will keep going until something external stops it. Security-related findings were smaller in volume but represent the highest-risk category: 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: 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. 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: 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. If you are looking to improve the security and reliability of your agent configuration files, here is a practical checklist: 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. Run AgentLinter across your connected repositories to identify ambiguity, missing escape hatches, and security risks in AI agent configuration files.
Why agent configuration files require security controls
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.What we found across 34,266 repositories
Finding 1: Ambiguity is the most common issue
Weak instruction
Concrete instruction
"Be helpful."
"When a user asks for a code change, implement the change and explain what you modified."
"Format code properly."
"Use 2-space indentation for TypeScript files."
"Use our standard style."
"Follow the ESLint configuration in
.eslintrc.js."
"Follow best practices."
"Do not modify generated files under
/dist."Finding 2: Missing escape hatches create runaway behavior
Finding 3: Security issues are lower volume but higher severity
curl | bash
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
CLAUDE.md, .cursorrules, AGENTS.md, copilot-instructions.md, and similar)See what AgentLinter finds in your repositories