Claude Code CLAUDE.md vs settings.json: which one controls what (and why it matters)

Claude Code CLAUDE.md vs settings.json: which one controls what (and why it matters) If you've been using Claude Code for more than a week, you've probably edited both CLAUDE.md and .claude/settings.json — and at some point wondered: which file should this go in? They look similar. They both configure Claude's behavior. But they control completely different things, and mixing them up leads to frustrating results. Here's the complete breakdown. The mental model CLAUDE.md = Claude's brain settings.json = Claude's permissions CLAUDE.md is natural language. You write instructions, context, constraints, and preferences. Claude reads it like a colleague reads a briefing doc. settings.json is machine config. It controls what tools Claude is allowed to use, what commands it can run, what it's blocked from doing. What CLAUDE.md controls # Project context This is a Next.js 14 app using Prisma + PostgreSQL. # Architecture decisions - All API routes live in /app/api/ - Database models are in /pris