Skip to main content
What this unit solvesEarlier units covered CLAUDE.md, rules, skills, subagents, hooks, and plugins each in depth, but you need one complete reference: every file and folder in .claude/, what it does, when it loads, and whether to commit it. This unit is that reference. It maps project-level .claude/ and user-level ~/.claude/ item by item, threads each entry back to its deep-dive unit, and fully covers five topics that have no dedicated unit: output-styles, keybindings, themes, workflows, and agent-memory. The authoritative source is the official interactive directory page [1].

​
Learning objectives

  • State the purpose, load timing, and commit status of every file and folder under .claude/.
  • Distinguish the files that live in the project root (CLAUDE.md, .mcp.json, .worktreeinclude) from those inside .claude/.
  • Configure output-styles, keybindings, and themes, and identify where workflows and agent-memory are stored.
  • Map any file to its deep-dive unit and know where to look for details.
Timeliness noticeDirectory structure and filenames verified as of 2026-06, sourced from the official interactive directory page at code.claude.com/docs/zh-TW/claude-directory [1] and the corresponding topic pages. Claude Code changes frequently; treat the current official page as the authoritative reference before acting.

​
1. Three location families

.claude-related files are spread across three places. Pinning this boundary first keeps everything below from sliding out of position:
FamilyLocationCommit to VCSVisible to
Project rootrepo root directory (CLAUDE.md, .mcp.json, .worktreeinclude)mostly committedteam
Project .claude/.claude/ inside the repomostly committed; *.local.* gitignoredteam (personal overrides excepted)
User layer~/.claude/ (Windows: %USERPROFILE%\.claude\) and ~/.claude.jsonnot committed (machine-local)only you
The most common mistake is treating CLAUDE.md and .mcp.json as files inside .claude/. They live in the project root, not in .claude/ [1].

​
2. Project root (not inside .claude/)

(repo root)
CLAUDE.md · loaded in full at every session start; primary project instructions file
CLAUDE.local.md · gitignored; personal private settings (sandbox URLs, local test data)
.mcp.json · connected at session start; project-level MCP servers, shared with the team
.worktreeinclude · at git worktree creation; lists gitignored files to copy from the main repo
FileCommitWhen loadedPurposeDeep read
CLAUDE.mdcommittedfull load at every session startproject instructions (conventions, common commands, architecture context); can also be placed at .claude/CLAUDE.md04-1
CLAUDE.local.mdgitignoredevery session startpersonal private settings for this project04-1
.mcp.jsoncommittedconnected at session start; tool schemas lazy-loaded by defaultproject-level MCP servers, team-shared; personal MCP goes in ~/.claude.json04-9
.worktreeincludecommittedat git worktree creationlists gitignored files (e.g. .env) to copy into a new worktree; uses .gitignore syntaxofficial worktrees page [1]

​
3. Project-level .claude/

.claude
settings.json · shared config: permissions / hooks / model / env / statusLine / outputStyle
settings.local.json · gitignored; personal overrides, same schema; arrays merge across layers, scalars take nearest layer
rules
*.md · topic rules; without paths: frontmatter loads like CLAUDE.md; with paths: loads only when matching glob is read
skills
File / folderCommitPurposeDeep read
settings.jsoncommittedpermissions, hooks, model, env, statusLine, outputStyle, and more; enforced settings (unlike CLAUDE.md, which is only context)02-3
settings.local.jsongitignoredpersonal overrides; same schema as settings.json; array-type settings merge across layers, scalars take the nearest layer02-3
rules/*.mdcommittedtopic rule files; without paths: frontmatter, loaded at session start like CLAUDE.md; with paths:, loaded only when Claude reads a file matching the glob04-2
skills/<name>/SKILL.mdcommittedskill invokable via /<name> or auto-triggered by Claude based on description; directory can include references/ and scripts/04-4
commands/<name>.mdcommittedlegacy single-file slash command; same mechanism as skills; new workflows should prefer skills/; skill wins on name conflict04-3
output-styles/committedproject-shared output styles (see Section 5.1); personal styles go in ~/.claude/output-styles/this unit, Section 5.1
agents/*.mdcommittedsubagent definitions (each has isolated context, tool set, optional model override)04-5
workflows/*.jscommitteddynamic workflow scripts, generated by saving a /workflows run; each .js becomes a /<name> command; project layer overrides personal layerthis unit, Section 5.4
agent-memory/<agent>/MEMORY.mdcommittedproject-scoped persistent memory for a subagent (memory: project frontmatter); separate from the main session’s auto-memorythis unit, Section 5.5
Different from main session auto-memory.claude/agent-memory/ is a subagent’s own memory, entirely separate from your main session’s auto-memory (stored at ~/.claude/projects/<repo>/memory/). A subagent using memory: local writes to .claude/agent-memory-local/ (gitignored); memory: user writes to ~/.claude/agent-memory/ (cross-project) [1].

​
4. User-level ~/.claude/ and ~/.claude.json

~
.claude.json · app state / UI preferences / OAuth session / personal MCP; managed via /config, not hand-edited
.claude
CLAUDE.md · personal cross-project instructions; loaded alongside project CLAUDE.md; project layer wins on conflict
settings.json · default for all projects; overridden by project-level keys
keybindings.json · custom keyboard shortcuts (see Section 5.2; requires v2.1.18+)
File / folderPurposeDeep read
~/.claude.jsonapp state, UI preferences, OAuth session, per-project trust decisions, personal MCP servers; managed mostly via /config, not hand-edited. Note: IDE-switching flags (e.g. autoConnectIde) and permissions approved during a session are stored in different locations (the latter goes into .claude/settings.local.json)02-4
~/.claude/CLAUDE.mdpersonal cross-project instructions, loaded alongside the project CLAUDE.md; project layer wins on conflict04-1
~/.claude/settings.jsondefault applied to all projects; overridden by project-layer keys of the same name02-3
~/.claude/keybindings.jsoncustom keyboard shortcuts (see Section 5.2)this unit, Section 5.2
~/.claude/themes/custom color themes (see Section 5.3)this unit, Section 5.3
~/.claude/rules/ skills/ commands/ output-styles/ agents/ workflows/same as project-layer counterparts but apply to all projectsrespective deep-dive units
~/.claude/agent-memory/subagent cross-project memory for memory: user04-5
~/.claude/projects/<repo>/memory/MEMORY.mdmain session auto-memory (v2.1.59+; first 200 lines or 25 KB loaded at session start)04-1

​
5. Five topics without dedicated units

Sections 2 through 4 map every entry to a deep-dive unit. The five items below have no dedicated unit; this section covers them to an actionable level.

​
5.1 output-styles: rewriting the system prompt for a different mode

An output style is a block of text appended to the system prompt. By default it replaces the built-in software-engineering task instructions, making it possible to repurpose Claude Code for non-coding work (teaching, review mode) [2].
  • Four built-in styles: Default, Proactive, Explanatory, Learning.
  • Custom styles: place at ~/.claude/output-styles/<name>.md (personal) or .claude/output-styles/ (project-shared). Frontmatter fields: name, description, keep-coding-instructions (defaults to false; set to true to keep the built-in task instructions), force-for-plugin (plugin-specific).
  • To activate: use /config to select an output style, or set the outputStyle key in settings.json. The system prompt is locked at session start for caching purposes — a change requires /clear or a new session before it takes effect.
A teaching-mode output style
---
description: Explain design decisions; leave small changes for the user to implement
keep-coding-instructions: true
---

After each task, add a paragraph explaining the key trade-offs in the design.
When a change is fewer than 10 lines, mark it TODO(human) and leave it for the user to implement rather than writing it yourself.

​
5.2 keybindings: custom shortcuts

~/.claude/keybindings.json rebinds keys in the interactive CLI (requires v2.1.18+) [3].
  • Format: { "bindings": [{ "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor", "ctrl+u": null } }] }. Setting a value to null removes the binding. Chords (sequential keypresses separated by a space) are supported.
  • Context types include Global, Chat, Autocomplete, Settings, and others; a binding is scoped to its declared interface area.
  • Reserved keys that cannot be rebound: Ctrl+C, Ctrl+D, Ctrl+M, Caps Lock.
  • Use /keybindings to create or open the file (with schema attached); /doctor reports binding conflicts. Changes are auto-detected and hot-reloaded.

​
5.3 themes: custom colors

~/.claude/themes/<name>.json defines a theme as a built-in base preset plus a set of overrides color values [1]. Create one interactively with /theme or write the JSON directly. After selecting a custom theme the preference is stored as custom:<slug>. Themes are read at session start and hot-reloaded. 
{
  "name": "Dracula",
  "base": "dark",
  "overrides": { "claude": "#bd93f9", "error": "#ff5555", "success": "#50fa7b" }
}

​
5.4 workflows: dynamic multi-agent scripts

.claude/workflows/<name>.js (project) or ~/.claude/workflows/ (personal) are JavaScript scripts that run in the background at runtime to generate and coordinate tens to hundreds of subagents. Requires Claude Code v2.1.154+ [1, 4]. These files are not hand-written; they are generated by running /workflows and pressing s to save (the built-in /deep-research is a ready-made example). Each .js becomes a /<name> command; project-layer files override personal-layer files of the same name. To disable: use /config to toggle Dynamic workflows, set disableWorkflows: true in settings.json, or set the environment variable CLAUDE_CODE_DISABLE_WORKFLOWS=1 [4]. The full mechanism is covered in the official dedicated page [4]; this unit records only the storage location and the source.

​
5.5 agent-memory: persistent memory for subagents

A subagent only gets a dedicated memory directory when memory: is set in its frontmatter. The write destination depends on the scope [1]:
frontmatterWrite locationCommittedScope
memory: project.claude/agent-memory/<agent>/MEMORY.mdcommittedteam-shared
memory: local.claude/agent-memory-local/gitignoredthis machine, this project
memory: user~/.claude/agent-memory/machine-localcross-project
The mechanism mirrors main session auto-memory: the subagent reads and writes its own file; the first 200 lines (up to 25 KB) are loaded at start. You do not write to this file manually.

​
6. Tool comparison: directory equivalents in other agents

The “configuration-as-directory” pattern has counterparts in other tools (as of 2026-06; strict paths are in 02-6):
DimensionAnthropic Claude (primary)OpenAI CodexGoogle AntigravityGitHub Copilot CLICursor (brief)
Config root.claude/, ~/.claude/.codex/, ~/.codex/ (CODEX_HOME relocatable)workspace .agents/, global ~/.gemini/, ~/.gemini/config/.github/, ~/.copilot/ (COPILOT_HOME).cursor/
Project instructionsCLAUDE.mdAGENTS.md (AGENTS.override.md takes priority)GEMINI.md / AGENTS.md, .agents/rules/.github/copilot-instructions.md, AGENTS.md.cursor/rules/*.mdc, AGENTS.md
Behavior settingssettings.jsonconfig.tomlGUI + ~/.gemini/antigravity-cli/settings.json~/.copilot/config.jsonGUI (Settings)
Skills.claude/skills/<n>/SKILL.md.agents/skills/<n>/SKILL.mdworkspace .agents/skills/; global IDE ~/.gemini/config/skills/, CLI ~/.gemini/antigravity-cli/skills/~/.copilot/skills/, .github/skills/(no native skill)
Subagents.claude/agents/*.md~/.codex/agents/*.toml, .codex/agents/*.toml.agents/ primary~/.copilot/agents/*.agent.md, .github/agents/(none)
Hookssettings.json hooks block~/.codex/hooks.json, config.toml [hooks]hooks.json (in .agents/ or ~/.gemini/config/)~/.copilot/hooks/, .github/hooks/(none)
MCP.mcp.json, ~/.claude.jsonconfig.toml [mcp_servers.<id>]~/.gemini/config/mcp_config.json~/.copilot/mcp-config.json, .mcp.json.cursor/mcp.json
Equivalent does not mean identicalA shared row in the table means the concepts map onto each other, not that the behavior is the same. Codex skills live in .agents/skills/ (not .codex/skills/); Antigravity workspace rules use the plural .agents/ (not the singular). Both are easy to get wrong when carrying over a mental model from Claude. When switching tools, look up each cell in 02-6 rather than substituting Claude paths directly.

​
7. Hands-on: audit your .claude/

1

List what you have

Run ls -la .claude/ and ls -la ~/.claude/ in a project you use regularly. Compare against Sections 3 and 4 and note which items you already have and which you have not yet used.
2

Check your .gitignore

For each file present, ask: should this be committed? settings.local.json, CLAUDE.local.md, and agent-memory-local/ must be in .gitignore. Missing entries push personal settings to your team.
3

Try one personalization feature

Pick one personalization area you have not used: run /theme to create a theme, or /keybindings to bind a frequently used key, then confirm hot-reload works.
4

Check your output style

Run /config to see the current output style. If you regularly do non-coding work (review, teaching), try switching to a built-in style.

​
8. Common pitfalls

Anti-pattern list
  • Treating CLAUDE.md / .mcp.json as files inside .claude/: they belong in the project root. Wrong location means Claude never reads them.
  • Missing gitignore for personal-layer files: once settings.local.json, CLAUDE.local.md, or .claude/agent-memory-local/ are committed, your personal overrides and local memory go to the whole team.
  • Assuming output style or theme changes take effect immediately: the system prompt is locked at session start; a change requires /clear or a new session.
  • Conflating subagent memory with main session memory: they use different directories and different scopes. Without a memory: frontmatter entry, a subagent has no memory directory at all.
  • Copy-pasting .claude/ paths to other tools: the structure does not transfer verbatim to Codex or Antigravity. Look up each entry in Section 6 and 02-6.

​
Self-check

The bar for passing this unit
  1. Given any filename under .claude/, can you state its purpose, when it loads, whether to commit it, and which unit covers it in depth?
  2. Can you name the three files that live in the project root rather than inside .claude/?
  3. Do you know the config file location and the moment a change takes effect for output styles, keybindings, and themes?
  4. Where do the three memory: scopes for a subagent each write to, and which one gets committed?

​
Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.
  • [1] Anthropic, “Explore the .claude directory” (interactive file reference listing location, load timing, commit status, and examples for each entry), Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/zh-TW/claude-directory (as of 2026-06)
  • [2] Anthropic, “Output styles” (four built-in styles, custom frontmatter fields, outputStyle setting, and when changes take effect), Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/en/output-styles (as of 2026-06)
  • [3] Anthropic, “Keybindings” (~/.claude/keybindings.json, context and action fields, chords, reserved keys), Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/en/keybindings (as of 2026-06)
  • [4] Anthropic, “Orchestrate subagents at scale with dynamic workflows” (.claude/workflows/*.js runtime background execution, generating and coordinating tens to hundreds of subagents, saved from /workflows with s, each file becomes /<name>, project overrides personal, requires v2.1.154+, disabled via disableWorkflows or CLAUDE_CODE_DISABLE_WORKFLOWS=1), Claude Code Docs. Accessed: 2026-06. [Online]. Available: https://code.claude.com/docs/en/workflows (as of 2026-06)