10. Governing Claude Code with Invisible JSON Files (The .claude Directory and Settings)
Show notes
In Episode 10 of Beyond Prompting, we explore how to configure and govern Claude Code through the .claude directory and JSON settings files. Author Sho Shimoda breaks down how configuration is structured, which files take precedence when rules conflict, and how settings merge across scopes. In this episode, we cover:
- What Lives Where: Distinguishing between committed project configuration (.claude/settings.json, rules/, skills/), personal overrides (.claude/settings.local.json), user-level global settings (~/.claude/), and organizationally enforced managed-settings.json.
- The Five-Tier Precedence Ladder: How settings resolve from strongest to weakest: managed settings, --settings flags, .claude/settings.local.json, .claude/settings.json, and ~/.claude/settings.json.
- Why Lists Merge Instead of Override: Why permission rules like permissions.allow combine additively across files rather than replacing team defaults, preventing local tweaks from silently wiping out team guardrails.
- When Edits Take Effect & Workspace Trust: Which settings reload live mid-session versus which require a session restart, and why sensitive permissions wait for workspace trust before taking effect.
- What Claude Code Writes About You: Managing session transcripts, rewind checkpoints, prompt history (history.jsonl), and transcript retention periods under ~/.claude/projects/.
(Note for listeners: This episode covers Chapter 10 of Sho Shimoda's book RUNNING CLAUDE: The Operator’s Guide to Chat, Cowork and Claude Code, available on Amazon as the successor book to Master Claude: Chat, Cowork and Code).