# Configuration debugging and the .claude directory

> Diagnose CLAUDE.md, settings, hooks, MCP, skills, permissions, local directories, data flow, and cleanup.

URL: https://docs.passion8.cc/en/docs/claude-code/configuration-debugging
Language: en
Publisher: Passion8

When rules are ignored, hooks do not run, MCP is missing, or skills/settings do not apply, inspect what Claude Code actually loaded instead of guessing.

## Start with these commands

| Command | Inspect |
| --- | --- |
| /context | System prompt, memory, skills, subagents, MCP, messages |
| /memory | Loaded CLAUDE.md, rules, and auto memory |
| /skills | Project, user, and plugin skills |
| /hooks | Registered hooks and events |
| /mcp | Servers, connections, and approvals |
| /permissions | Sources of allow/ask/deny rules |
| /doctor | Schema, installation, duplicate subagent names |
| /status | Settings sources, policy, login, model |
| /debug <problem> | Enable logs and investigate with Claude |

## Configuration locations

| File | Purpose | Commit? |
| --- | --- | --- |
| CLAUDE.md | Project conventions and commands | Yes |
| .claude/CLAUDE.md | Additional project memory | Yes |
| .claude/settings.json | Shared settings, permissions, hooks | Yes, without keys |
| .claude/settings.local.json | Personal project overrides | No |
| ~/.claude/settings.json | User preferences, environment, permissions | No |
| .mcp.json | Project MCP servers | Yes, use environment references for secrets |
| ~/.claude.json | App/login/project state and some MCP data | Do not hand-edit business settings here |
| .claude/commands/ | Slash commands | Yes |
| .claude/skills/<name>/SKILL.md | Project skill | Yes |
| .claude/agents/ | Custom subagents | Yes |
| .claude/output-styles/ | Output styles | Project or user scope |




~/.claude.json is not a settings file. Put permissions, hooks, and env in settings.json.




## Settings merging and precedence

Ordinary precedence:

1. Managed policy.
2. Command-line configuration; individual flags/environment variables have feature-specific precedence.
3. Project local settings.
4. Shared project settings.
5. User settings.

Permission lists merge. Conflicts follow deny → ask → allow, not simple replacement.

| Symptom | Cause | Fix |
| --- | --- | --- |
| User setting ignored | Project local key overrides it | Inspect /status sources |
| Hook absent | Written into a separate file or ~/.claude.json | Put it under hooks in settings |
| MCP absent | .mcp.json placed inside .claude | Move project MCP definition to repository root |
| MCP lacks environment | Settings env differs from server process configuration | Define server env in .mcp.json |
| Skill absent | Stored as .claude/skills/name.md | Use name/SKILL.md |
| Subdirectory memory absent | Loaded on demand | Read a file in that directory |

## CLAUDE.md does not apply

```text
/memory
/context all
```

If absent, check its location and launch directory. If present but ineffective, rules may be vague, conflicting, or too long.

More reliable instructions:

- Name the actual test command.
- State directory ownership, such as React components in src/components.
- Enforce restrictions with permissions/hooks instead of prose alone.
- Split large repositories by directory instead of making the root file encyclopedic.

## Hooks do not trigger

```text
/hooks
claude --debug hooks
```

| Symptom | Cause |
| --- | --- |
| Missing from /hooks | Settings not loaded or wrong key |
| Matcher misses | Case-sensitive tool name; use Bash, Edit, Write |
| Multiple-tool matcher fails | Use one regex string such as Edit|Write |
| Schema error | /doctor reports it and the hook is discarded |
| Unstable path | Use CLAUDE_PROJECT_DIR or an absolute path |
| Wrong exit behavior | Follow the event's JSON/stderr contract |

## MCP is missing

```bash
claude mcp list
claude mcp get <name>
claude --debug mcp
```

| Symptom | Action |
| --- | --- |
| Project server pending approval | Approve in /mcp |
| Server failed | Inspect stderr, command, args, env |
| Connected with zero tools | Reconnect and inspect debug output |
| OAuth failure | claude mcp login <name> |
| Relative paths fail in some directories | Use absolute paths |
| Many tools disrupt caching | Use supported tool search or split servers |

## Compare against clean configuration

Safe mode disables most customizations:

```bash
claude --safe-mode
```

If the problem disappears, investigate CLAUDE.md, skills, plugins, hooks, MCP, custom commands, agents, output styles, and workflows.

For a clean directory:

```bash
mkdir -p /tmp/claude-clean
cd /tmp
CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
```

Notes:

- Managed policy may still apply.
- macOS credentials may remain in Keychain rather than being isolated by CLAUDE_CONFIG_DIR.
- Linux/Windows may require credentials again; Passion8 uses its gateway variables.

## Organize .claude

Recommended layout:

```text
.claude/
  settings.json
  settings.local.json
  commands/
    review.md
  skills/
    release-check/
      SKILL.md
  agents/
    qa-reviewer.md
  output-styles/
    concise.md
```

| Avoid | Reason |
| --- | --- |
| .claude/.mcp.json | Project MCP belongs at repository root |
| .claude/skills/foo.md | A skill requires a directory and SKILL.md |
| .claude/hooks.json | Ordinary hooks belong in settings; plugins can have separate hook files |
| Real keys in project settings | Project files are easy to commit accidentally |

## Data flow and local data

Claude Code sends required prompts, tool results, file excerpts, and MCP output to the selected provider. With Passion8, also consider gateway logging, billing, and retention policies.

| Data | Location/destination | Consideration |
| --- | --- | --- |
| Project files | Enter context after reads | Restrict sensitive paths |
| User settings/state | ~/.claude and ~/.claude.json | Do not commit |
| Shell output | Current session context | Avoid secrets and excessive logs |
| MCP output | Current session context | Filter database/browser results |
| Telemetry | Controlled by OTel environment | Avoid raw API bodies |
| WebFetch domain checks | May use a safety check service | Account for outbound domains |

For stricter projects:

- Deny Read on .env and .env.*.
- Ask or hook-check curl, wget, and database writes.
- Never print full keys in hook stderr.
- Collect only necessary monitoring fields; avoid OTEL_LOG_RAW_API_BODIES.

## Cache effects

Debugging often changes prompt prefixes:

| Action | Effect on five-minute / one-hour caching |
| --- | --- |
| New session after editing CLAUDE.md | Changed prefix usually creates a cache entry |
| Change permissions | Often small, but changed tool availability can alter prefixes |
| Add/remove MCP server | Changed schemas can miss |
| Add/remove skills/plugins | Instructions or tools can change |
| Safe mode | Different prefix; unsuitable for normal hit-rate evaluation |
| Clean config directory | Useful diagnosis, not representative project caching |

## Official references

- [Debug your configuration](https://code.claude.com/en/docs/en/debug-your-config.md)
- [Explore the .claude directory](https://code.claude.com/en/docs/en/claude-directory.md)
- [Data usage](https://code.claude.com/en/docs/en/data-usage.md)
- [Settings](https://code.claude.com/en/docs/en/settings.md)
- [MCP](https://code.claude.com/en/docs/en/mcp.md)