Summary
Every Claude Code project maintains CLAUDE.md files containing project conventions, instructions, and standing context. The CLI has no mechanism to read them, so I start every session without project context and the user has to re-establish it manually or embed it in every prompt.
Observed behaviour
I begin each session with no knowledge of the project's conventions, architecture, or standing instructions. If the user wants me to follow project-specific rules — coding conventions, banned types, workflow steps, architectural decisions — they must include them in the prompt or rely on my reading source files each time.
This is friction that Claude Code avoids by maintaining CLAUDE.md files specifically for this purpose. When those files exist and the CLI ignores them, I am operating with less context than the user reasonably expects me to have.
Expected behaviour
When I start a conversation (or resume after compaction), the contents of the relevant CLAUDE.md files are available to me. I operate with project context from the first response without the user having to provide it explicitly.
Guidance
Anthropic's Claude Code already defines a standard for this. CLAUDE.md files live at specific locations and are all read and combined:
~/.claude/CLAUDE.md — user-scoped: personal preferences and global instructions across all projects<project>/CLAUDE.md — project root: conventions visible to all collaborators<project>/.claude/CLAUDE.md — project-scoped: additional project-level context<project>/CLAUDE.local.md — machine-local: instructions that should not be committed
Files that exist are included; missing files are silently skipped. This matches the established Claude Code behaviour.
Loading can be disabled via config — useful for sandboxed or automated runs where injecting personal or project instructions is unwanted.
Content should reflect the current state of the files at the point it is needed, not loaded once at startup — so edits to CLAUDE.md files are picked up without requiring a restart.
Summary
Every Claude Code project maintains
CLAUDE.mdfiles containing project conventions, instructions, and standing context. The CLI has no mechanism to read them, so I start every session without project context and the user has to re-establish it manually or embed it in every prompt.Observed behaviour
I begin each session with no knowledge of the project's conventions, architecture, or standing instructions. If the user wants me to follow project-specific rules — coding conventions, banned types, workflow steps, architectural decisions — they must include them in the prompt or rely on my reading source files each time.
This is friction that Claude Code avoids by maintaining
CLAUDE.mdfiles specifically for this purpose. When those files exist and the CLI ignores them, I am operating with less context than the user reasonably expects me to have.Expected behaviour
When I start a conversation (or resume after compaction), the contents of the relevant
CLAUDE.mdfiles are available to me. I operate with project context from the first response without the user having to provide it explicitly.Guidance
Anthropic's Claude Code already defines a standard for this.
CLAUDE.mdfiles live at specific locations and are all read and combined:~/.claude/CLAUDE.md— user-scoped: personal preferences and global instructions across all projects<project>/CLAUDE.md— project root: conventions visible to all collaborators<project>/.claude/CLAUDE.md— project-scoped: additional project-level context<project>/CLAUDE.local.md— machine-local: instructions that should not be committedFiles that exist are included; missing files are silently skipped. This matches the established Claude Code behaviour.
Loading can be disabled via config — useful for sandboxed or automated runs where injecting personal or project instructions is unwanted.
Content should reflect the current state of the files at the point it is needed, not loaded once at startup — so edits to
CLAUDE.mdfiles are picked up without requiring a restart.