Skip to main content
This page is the map for Part IVPart IV (04-0 through 04-11) covers the entire customization layer of Claude Code. This page’s job is to give you the full picture first: every file and folder under .claude/, what it does, when it loads, and whether to commit it. With this map in hand, the deep-dive units (04-1 through 04-11) become much easier to navigate.Boundary with 02-6: this page is the complete reference for Claude’s own .claude/ directory. 02-6 is the cross-tool comparison (Claude vs Codex vs Antigravity vs Copilot). To find where a Codex equivalent lives, see 02-6. To understand what a file inside .claude/ does, see this page.Five topics without dedicated units: output-styles, keybindings, themes, workflows, and agent-memory have no standalone unit in Part IV. Section 2 of this page covers them to an actionable level.

​
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.

​
Interactive directory explorer

Click any item on the left to see its purpose, load timing, and usage tips on the right. Switch between Project and Global tabs to view the project layer and user layer respectively.

​
1. Three location families

.claude-related files are spread across three places. Pinning this boundary first keeps everything below from sliding out of position: 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. Five topics without dedicated units

Units 04-1 through 04-11 each have a deep-dive page. The five items below are exceptions; this section covers them to an actionable level.

​
2.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.

​
2.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.

​
2.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.

​
2.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].

​
2.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]: 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.

​
3. 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 the interactive explorer above 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.

​
4. 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 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-06.
  • [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)