Security Considerations for CLAUDE.md

CLAUDE.md is usually committed to git and read automatically into an agent’s context on every session — two properties that make it worth thinking about deliberately from a security standpoint, in ways that don’t come up with private, one-off instructions typed into a single conversation.

Never Put Secrets in CLAUDE.md

<!-- Never do this -->
## Database Access
Connection string: postgresql://admin:hunter2@prod-db.internal:5432/app

<!-- Instead -->
## Database Access
Connection details are in `.env` (gitignored) — see `.env.example` for the
required variable names. Never hardcode credentials in code or docs.

This is the same rule that applies to any committed file — a secret in CLAUDE.md is a secret in git history, readable by anyone with repository access, indexed by any tooling that scans the repo, and persisting even if later “removed” (since git history retains it unless explicitly purged). CLAUDE.md is documentation, and documentation is exactly the wrong place for credentials regardless of whether an AI agent reads it.

Untrusted Content Flowing Into Context Is a Real Concern

Since CLAUDE.md content becomes part of what the agent treats as trusted context, it’s worth being deliberate about what feeds into it. A CLAUDE.md that’s built partly from external, less-controlled sources — pasted content from a third-party README, an auto-generated summary of an external API’s documentation — inherits whatever trust level that source deserves, which may be lower than content the team wrote and reviewed directly.

<!-- Worth extra scrutiny before including verbatim -->
## Third-Party API Notes
[content pasted directly from an external vendor's documentation site]

This isn’t a reason to avoid referencing external documentation — it’s a reason to review it the same way you’d review any other content before committing it, rather than assuming anything pasted in is automatically safe simply because it ended up in a project file.

Distinguishing CLAUDE.md From Runtime Tool Output

It’s worth being clear about the boundary: CLAUDE.md is authored, reviewed, committed content — a fundamentally different trust category from content an agent encounters during a session through tool calls (web pages, API responses, file contents from untrusted sources). The general security principle that tool results and external content should be treated as data, not instructions, is a separate and broader concern than CLAUDE.md specifically — but it’s worth understanding that CLAUDE.md’s elevated trust (because it’s deliberately authored and reviewed) is exactly why it shouldn’t casually incorporate unreviewed external content that would blur that distinction.

Review Changes the Way You’d Review Any Trusted Configuration

Because CLAUDE.md content is read automatically and treated as standing context, a malicious or careless change to it — added by someone with write access, or introduced through an insufficiently reviewed PR — has more leverage than a one-off bad instruction in a single conversation, since it persists across every subsequent session. This is a reasonable argument for the same review discipline covered in Team Collaboration Conventions for CLAUDE.md — not because CLAUDE.md is uniquely dangerous, but because anything read into every session’s context deserves the same scrutiny as any other piece of trusted configuration.

Access Control Follows Repository Access

CLAUDE.md’s security model largely inherits from your repository’s own access control — anyone who can read the repo can read CLAUDE.md, and anyone with write/merge access can change what every future session’s context includes. There’s no separate access-control layer specific to CLAUDE.md itself; if a repository has appropriately scoped access already, CLAUDE.md is covered by that same scoping.

Common Mistakes

Hardcoding any credential, API key, or connection string into CLAUDE.md — no different from hardcoding it into application code, and just as wrong, since the file is committed and broadly readable.

Pasting large blocks of unreviewed external content into CLAUDE.md without treating it with the same scrutiny as any other addition to trusted, automatically-loaded context.

Assuming CLAUDE.md needs no more review discipline than a casual internal note, when in practice it’s read into every session automatically and persists until explicitly changed — a bad or malicious entry has real leverage precisely because of that automatic, repeated exposure.

Frequently Asked Questions

Does CLAUDE.md need its own separate encryption or access controls? No — it inherits your repository’s existing access model; there’s no CLAUDE.md-specific security layer beyond standard repository permissions and code review.

Is it safe to reference (link to) external documentation from CLAUDE.md, even if I don’t paste its content in directly? Yes — a link doesn’t pull untrusted content directly into the agent’s automatically-loaded context the way pasting the content verbatim does; the concern is specifically about incorporating unreviewed external content as if it were reviewed, first-party documentation.

What if CLAUDE.md accidentally had a secret committed to it in the past? Treat it exactly as you would any other accidentally-committed secret — rotate the credential immediately, and follow your standard process for purging sensitive data from git history; simply deleting the line in a new commit doesn’t remove it from history.

Summary

CLAUDE.md’s security considerations mostly follow from two properties: it’s committed (so secrets are permanently exposed the same way they would be in any committed file) and it’s automatically, repeatedly loaded into trusted context (so a bad entry has more leverage than a one-off instruction, and unreviewed external content deserves scrutiny before being folded in). Treat it with the same discipline you’d apply to any other committed, automatically-consumed configuration — no secrets, deliberate review, and care about what external content gets incorporated.