In Post 4, I crammed architecture notes, coding conventions, deployment config, and emotional baggage into a single CLAUDE.md file. By Post 8, every session started with Claude doing something wrong that I'd already corrected in a previous session, because the correction was buried on line 94 of a file that was trying to do everything.
It took me a month to realize that Claude Code has a configuration stack, not a configuration file. Once I understood it, I built a best-practices project across seven languages to make sure nobody else wasted that month.
The Configuration Stack
Claude Code has multiple configuration layers that compose:
User settings (~/.claude/settings.json)
↓ merges with
Project settings (.claude/settings.json)
↓ merges with
CLAUDE.md (project-level instructions)
↓ merges with
.claude/rules/ (modular convention files)
Settings control what Claude can do. CLAUDE.md controls how Claude should think. Rules control what conventions to follow. Three different concerns, three different locations.
Rules files use YAML frontmatter to scope conventions to specific file patterns:
---
globs: ["**/*.ts", "**/*.tsx"]
---
# TypeScript Conventions
- Use strict mode always
- Prefer `interface` over `type` for object shapes
- Use `unknown` over `any`
This TypeScript rule only applies when Claude works on .ts files. Different rules for different contexts. Version them independently. Share them across repos.
I learned this separation the hard way. In Post 2, I put global preferences in project config. In Post 4, I crammed everything into CLAUDE.md: architecture, conventions, commands, deployment notes, emotional baggage. In Post 8, I finally separated them properly, and immediately felt the difference across sessions.
Four Lessons, Each From a Specific Disaster
Be specific about what you don't want. I asked Claude to fix a one-line bug. It fixed the bug, added docstrings to 40 functions I hadn't touched, and created three new utility files. That's when I added "Don't add comments to code you didn't modify" and "Don't create new files unless absolutely necessary" to my rules. Negative instructions are more useful than positive ones because Claude's default is thoroughness, and thoroughness manifests as extra everything.
Document your architecture decisions, not just your architecture. My CLAUDE.md for the pet social network (Post 13) said "uses DynamoDB." Claude promptly designed a schema that assumed relational JOINs would work. When I changed it to "uses DynamoDB because we need sub-millisecond reads at scale and accepted the trade-off of designing access patterns upfront," the suggestions stopped requiring schema restructuring.
Version your conventions. The car report project (Post 9) ran the same pipeline on different vehicles and got different results. The prompts weren't in source control. Fixed it once, never had the problem again. Obvious in retrospect. Invisible until it burned me.
Review architecture, not just code. Claude writes syntactically perfect code. It also designed a database schema for the pet social network that couldn't support a basic query I needed (Post 13). The code review passed. The architecture review should have caught it. The architecture review is where your expertise actually matters.
The Team Rollout Question
Every engineering org adopting AI tools faces this: how much do you standardize, and how much do you leave to individual developers?
Too strict → developers work around the rules. Too loose → inconsistent results across the team.
The balance: security rules are enforced (no arbitrary shell commands, no secret file access), coding conventions are recommended (testing patterns, documentation standards), personal preferences are left alone (shell, editor, aliases).
The teams that adopt AI tooling fastest won't be the ones with the best developers. They'll be the ones with the best configuration.
The Takeaway
Fork a best-practices repo. Customize for your stack. Write CLAUDE.md templates. Enforce security rules at the org level. Recommend coding conventions. Leave personal preferences alone.
The tool is only as good as its setup. I spent a month learning that. You don't have to.