Project-local instructions are repository files or embedded prompts that shape how an AI tool behaves inside a specific codebase. When those files are writable by an attacker, they become a control surface, because the model may treat them as trusted guidance during review, generation, or remediation tasks.
Expanded Definition
Project-local instructions are codebase-scoped directives that sit alongside source files and shape how an AI coding tool interprets, edits, or explains that repository. In practice, they function like a local policy layer for agentic behavior, separate from global model settings and broader organisational prompts.
In NHI and agentic AI work, the distinction matters because these instructions can influence tool use, file selection, remediation style, and even what the model treats as authoritative during a task. Definitions vary across vendors, and no single standard governs this yet, so teams should treat the term operationally rather than assume a universal format. The closest governance analogue is repository-specific trust guidance, which should be reviewed with the same care given to build scripts and automation rules. For a broader NHI risk context, see Ultimate Guide to NHIs and the NIST Cybersecurity Framework 2.0 for governance alignment.
The most common misapplication is treating project-local instructions as harmless documentation, which occurs when teams allow unreviewed repository edits to influence AI actions in sensitive codepaths.
Examples and Use Cases
Implementing project-local instructions rigorously often introduces a governance burden, requiring organisations to weigh developer convenience against the risk that repository content can steer an AI tool toward unsafe outputs.
- A repository contains agent instructions that tell a code assistant how to follow local linting, testing, and commit conventions during pull request remediation.
- A security team uses repository-scoped prompts to tell an AI reviewer which files contain policy exceptions, but locks those instructions behind branch protection and review.
- An attacker modifies a writable instruction file so the assistant ignores secret patterns, which makes embedded credentials less likely to be flagged during code review.
- A platform team standardises project-local instructions across multiple services so the AI tool uses consistent dependency and deployment guidance for each codebase.
- Repository guidance is paired with the visibility concerns highlighted in Ultimate Guide to NHIs and with the repository security principles described in the NIST Cybersecurity Framework 2.0.
Why It Matters in NHI Security
Project-local instructions matter because they can become an indirect privilege boundary for an AI agent. If an attacker can write to them, they may redirect the model’s attention, suppress warnings, or bias remediation in ways that look legitimate inside the workflow. That is especially dangerous in repositories that already contain secrets, deployment manifests, or code that touches service accounts and API keys.
This is not a theoretical edge case. NHI Mgmt Group reports that 96% of organisations store secrets outside of secrets managers in vulnerable locations including code, config files, and CI/CD tools, which means a compromised instruction file can sit next to material the AI is likely to inspect. See Ultimate Guide to NHIs for the underlying exposure patterns. The control implication is simple: treat instruction files as governed assets, review them like code, and restrict who can alter them.
Organisations typically encounter the impact only after an AI-assisted review misses a secret, weakens a fix, or accepts a malicious repository prompt, at which point project-local instructions become operationally unavoidable to address.
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 OWASP Non-Human Identity Top 10 address the attack and risk surface, while NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Agentic AI Top 10 | AA-03 | Repository instructions can steer agent behavior and tool use inside a codebase. |
| OWASP Non-Human Identity Top 10 | NHI-02 | Writable instructions can expose secrets and weaken NHI-related review controls. |
| NIST CSF 2.0 | PR.AC-4 | Local instructions affect access enforcement and trusted workflow boundaries. |
Limit write access to project-local instructions and enforce change review before agents consume them.
