Add inline claude:ignore directive for co-located file exclusion from AI contex

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

"I need to be able to demonstrate to my organization, legal team, or client that I have taken reasonable steps to prevent proprietary code from being processed by AI tools."

The current mechanisms for excluding files from Claude Code's context — permissions.deny in .claude/settings.json and .claudeignore — share a fundamental architectural flaw: the exclusion rules and the files they govern are separate artifacts that can be decoupled. When they are, the failure is silent. Claude simply consumes files that were intended to be excluded, with no error or warning.

This is not hypothetical. Issue #34833 (filed March 16, 2026) demonstrates that .claudeignore is actively bypassable today. But even if it worked perfectly, the underlying problem remains: a separate config file can be absent from a new clone, missing from a CI environment, or simply unknown to a new team member.

For a subset of files, proprietary algorithms, patent-pending code, NDA-covered reference implementations, licensed third-party IP — this fragility crosses from inconvenience into legal and compliance risk. Compliance cannot depend on every developer, workstation, and CI environment being correctly configured.

Proposed Solution

Support a single-line directive at the top of a source file that instructs Claude Code to skip it during context ingestion:

// claude:ignore

# claude:ignore

<!-- claude:ignore -->

Claude Code performs a lightweight prefix scan (first line or ~512 bytes) to detect the directive before deciding whether to include the file. The file is never fully processed if the directive is present.

The directive should be case-insensitive and use each language's standard line-comment syntax. This feature is additive and does not change permissions.deny behavior.

Alternative Solutions

• .claudeignore: proposed in #579 and #29455, currently broken per #34833. Even when working, it is a separate artifact subject to the same co-location failure modes described above.
• permissions.deny in .claude/settings.json: the current recommended approach. Reliable as an access control, but poor discoverability and subject to the same co-location problem. Cannot be audited or enforced in code review without additional tooling.
• // ai:ignore as a vendor-agnostic standard: rather than a Claude-specific directive, the broader and more durable solution would be a tool-agnostic // ai:ignore convention that Cursor, Copilot, Gemini Code Assist, and other AI coding tools could also adopt. A developer would mark a file once and have it protected across their entire AI toolchain, regardless of which tools their team uses. .gitignore works because every VCS tool respects it; the same principle applies here. Anthropic is well-positioned to propose and lead this standard. // claude:ignore is the pragmatic near-term ask; // ai:ignore is the right long-term solution given that teams likely will have differing tool chains. litter code with ignores for multiple tools would become ridiculous.

Priority

High - Significant impact on productivity

Feature Category

File operations

Use Case Example

1. Patent-pending algorithms: Legal has flagged specific files. With an inline directive, compliance is enforceable via code review (grep -r "claude:ignore" produces the audit list). With a config file, it depends entirely on whether every developer, workstation, and CI environment has been correctly configured.

1. NDA-covered components: A contractor integrating licensed DSP or cryptographic code needs a per-file opt-out that survives repo forks, CI spins, and developer onboarding without any additional configuration steps.

1. Licensed third-party IP: A vendor-supplied reference implementation lives in the repo for build purposes but carries redistribution and usage restrictions. The IP owner needs a durable, auditable guarantee it won't be processed by external inference pipelines.

Additional Context

This pattern is well-established across the tooling ecosystem. In each case the metadata governing tool behavior lives in the artifact itself:

| Tool | Directive |
|---|---|
| Pylint / Flake8 | # noqa |
| ESLint | /* eslint-disable */ |
| golangci-lint | // nolint |
| TypeScript | // @ts-nocheck |
| Clang-Tidy | // NOLINT |
| Semgrep | // nosemgrep |
| Prettier | // prettier-ignore |

On token efficiency: one could argue that a working .claudeignore is strictly more efficient for token reduction, as it gives Claude a complete exclusion manifest before any files are opened, avoiding all file I/O for excluded paths. An inline directive requires at least a prefix scan of every file to check for it. This is a valid tradeoff. The two features solve different problems and should coexist: .claudeignore is the right tool for bulk exclusion of directories, file types, and build artifacts; the inline directive is the right tool for individual files where the exclusion intent needs to be durable and co-located with the content. The same way Python developers have both # noqa for individual files and .pylintignore for project-wide patterns, one does not replace the other.

Related issues: #79, #579, #29455, #34833.