Claude User Context Pattern

A worked example of how to organise user-level (~/.claude/) context for Claude Code so the top-level CLAUDE.md stays lean and Claude pulls only the topical files it actually needs.

This is one person's setup, depersonalised and shared as a starting point. Fork it, fill in the <placeholders>, and adapt to your own machine and workflow.

The pattern

~/.claude/CLAUDE.md is loaded into every Claude Code session, so anything you put there is paid for on every turn. The trick is to keep that file small — identity, autonomy directive, output style, naming conventions, plan-handling rules — and offload everything topical (system environment, dev tools, MCP rules, troubleshooting, contacts, etc.) into separate files under ~/.claude/context/, then list them with one-line descriptions in the top-level file.

When Claude needs to know about your hardware, your git rules, or how you want it to provision MCPs, it reads the relevant context file on demand. Most turns it doesn't need any of them. The top-level file is the index, not the encyclopedia.

~/.claude/
├── CLAUDE.md                       # Lean. Routes to context/ files by topic.
└── context/
    ├── identity.md                 # Who you are, contact, workstation summary
    ├── system-environment.md       # OS, hardware, storage, network, LAN map
    ├── development-environment.md  # Languages, package managers, containers, git
    ├── git-rules.md                # Commit / push policy (critical-priority)
    ├── mcp-usage.md                # Which MCPs you have and when to use them
    ├── mcp-provisioning.md         # Rules for adding NEW MCPs
    ├── file-organization.md        # Where repos / scripts / programs live
    ├── media-tools.md              # Audio / video / image / local-LLM tooling
    ├── auth-and-security.md        # SSH / GPG / API-key handling
    ├── contacts.md                 # Recurring email recipients
    ├── troubleshooting.md          # Common platform-specific gotchas
    ├── tools.md                    # Niche utilities worth remembering
    └── preferences.md              # Date format, naming conventions

Why split it up

• Context-window economy — the top-level CLAUDE.md is loaded on every turn. Topical files are pulled only when relevant.
• Editability — git-tracked, narrow files are easier to diff and review than one 500-line monolith.
• Topical priority — the <files> index in the top-level file can mark individual files as priority="critical" so Claude knows which to consult eagerly.
• Drop-in for new machines — when you set up a new workstation, clone this kind of folder, swap the placeholders, and your assistant immediately knows the lay of the land.

What to change

Every file in context/ contains <placeholders-in-angle-brackets> for things you'll want to set yourself:

• <your-name>, <your-email>, <your-domain.com>
• <your-city>, <your-timezone>
• LAN IPs, MAC addresses, machine hostnames (under system-environment.md)
• Specific tool paths, GPU model, ROCm vs CUDA (under media-tools.md)
• Recurring contacts (under contacts.md)

The structure, prompts, and rules are the part worth copying. The specifics are the part worth replacing.

What's deliberately not here

• Anything secret. No API keys, no SSH-key paths, no actual credentials. The auth-and-security.md file describes policy (e.g. "sudo without asking", "API keys from environment"), not material.
• Project-level CLAUDE.md patterns. This is purely the user-level ~/.claude/ layer. Project-level context lives in each repo's own CLAUDE.md.
• Plugin / skill / agent definitions. Those are a separate concern.

The autonomy directive

The most opinionated piece in the top-level file is the <autonomy_directive> block. It tells Claude to stop laddering "should I proceed?" confirmations on local, recoverable, or git-tracked actions. If you want a more cautious assistant, soften it. If you want a more aggressive one, harden it. It's the single biggest dial on how the relationship feels day-to-day.

License

MIT. Use it, fork it, rewrite it. Credit appreciated but not required.