Claude Code File Structure & Configuration

Example project CLAUDE.md (keep it short and specific):

# Architecture
- All API routes use the middleware chain: auth → validate → handler
- Database access only through the repository pattern

# Commands
- Build: npm run build · Test: npm test · Lint: npm run lint

# Conventions
- Never use the `any` type in TypeScript
- Every new feature includes unit and integration tests

Path-scoped rule (.claude/rules/api.md, loads only when Claude works on matching files):

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

• <project> is derived from the git repository, not a hash, so all worktrees and subdirectories of one repo share one memory directory.
• Turn it off with the /memory toggle, "autoMemoryEnabled": false in a project's settings, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Move it with autoMemoryDirectory (an absolute or ~/ path).
• Subagents don't see the main conversation's auto memory (forks are the exception). A custom subagent with a memory field gets its own agent-memory/<name>/ directory.
• Auto memory files are not deleted by the cleanupPeriodDays sweep that removes old transcripts.

• Precedence: if one server name is defined in several places, Claude Code connects once, using the whole entry from the highest source: Local, then Project, then User, then plugin servers, then claude.ai connectors. Fields are not merged.
• MCP "local" scope is not settings.local.json. They are unrelated files.
• Approval: interactive sessions ask before using servers from a project's .mcp.json. Reset your choices with claude mcp reset-project-choices. claude -p and Agent SDK runs load them without asking.
• Secrets: .mcp.json supports ${VAR} and ${VAR:-default} expansion. See section 11.
• Organization control: managed-mcp.json takes exclusive control of which servers exist. allowedMcpServers and deniedMcpServers can be set in any settings scope and merge across scopes. A denylist match always blocks a server. Only allowManagedMcpServersOnly: true in managed settings limits the allowlist to managed sources.

claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp list                    # shows servers and warns about unset ${VAR}s
claude mcp reset-project-choices   # re-prompt for .mcp.json approvals

Hook entries merge across levels. /hooks opens a read-only browser showing each hook's source. "disableAllHooks": true turns them off. Events, handler types and exit codes are covered in the companion Claude Code Capabilities guide.

Format every file Claude edits (.claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

• Delivery sources, highest first: server-managed settings (claude.ai admin console or a Claude apps gateway), MDM / OS policy (macOS com.anthropic.claudecode plist, Windows HKLM\SOFTWARE\Policies\ClaudeCode), the managed-settings.json file, then the user-writable HKCU registry fallback. By default only the highest source that has a policy is used.
• Managed skills and output styles live in .claude/skills/ and .claude/output-styles/ inside the managed directory.
• Developers run /status to see which managed source applies to them.

How to supply secrets safely, file by file

The principle is the same everywhere: the file holds a reference (a variable name, a helper script path or an OAuth registration), and the secret itself lives in the OS keychain, a secret manager or your shell environment.

Step 1. Store the secret in the macOS Keychain (the trailing -w prompts for the value so it never appears in shell history).

security add-generic-password -a "$USER" -s sn-mcp-token -w

Step 2. Export it from the Keychain in ~/.zshrc, so only the variable name is ever written to any file.

export SN_MCP_TOKEN="$(security find-generic-password -s sn-mcp-token -w)"

Step 3. Reference the variable in the committed .mcp.json.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_API_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${SN_MCP_TOKEN}" }
    }
  }
}

Step 4. Check it: claude mcp list warns about any variable that isn't set. Open a new terminal first, so ~/.zshrc is reloaded.

Dynamic headers for tokens that expire (the script must print JSON such as {"Authorization": "Bearer …"}):

"internal-api": {
  "type": "http",
  "url": "https://mcp.internal.example.com",
  "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
}

Claude API key from a vault, plus deny rules for local secret files (~/.claude/settings.json):

{
  "apiKeyHelper": "/Users/you/bin/get-anthropic-key.sh",
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}