Stop Re-Explaining Your Project to AI Every Morning
How the .claude folder turns your repo into a self-documenting workspace where your AI coding agent already knows the rules, the style, and the plan.
Loading content...
How the .claude folder turns your repo into a self-documenting workspace where your AI coding agent already knows the rules, the style, and the plan.
I got tired of opening Claude Code and typing the same sermon: Tailwind, tests in __tests__, don't touch auth without asking. A committed .claude/ folder fixed it. The agent reads your rules at session start instead of guessing from whatever file you had open.
Every few days I was re-onboarding an intern with perfect amnesia. "We use Tailwind." "Tests live in __tests__." "No, the API layer does not look like that other repo you trained on last week." Five minutes gone before anything useful happened.
Claude Code solves this with a .claude/ folder in the repo. You write the context once. The agent loads it automatically. I have not repeated my whole stack speech in weeks.
Two layers. Shared stuff in git. Personal stuff in .gitignore.
CLAUDE.md at the root is the main brief: stack, architecture calls, naming, the weird exceptions ("we camelCase JSON even when the DB doesn't"). Everyone who clones the repo gets the same starting point.
CLAUDE.local.md is for you only. I keep paths to my local env templates and a note that I want diffs explained in plain English. My teammates do not need that.
Inside .claude/, same split: committed settings.json for team defaults, settings.local.json for your permission tweaks.
Drop markdown files in .claude/commands/. They become custom slash commands.
On this site I have a review command that checks MDX frontmatter and internal links the way I actually want them checked, not the way a generic linter guesses. Type /project:review and the agent runs that list.
When someone improves the command in a PR, everyone picks it up on pull. I like that better than another wiki page titled "How we use AI" that goes stale by March.
CLAUDE.md gets fatMine got long fast. I split .claude/rules/ into focused files:
code-style.md for imports, naming, the stuff you keep correcting in reviewtesting.md for where tests live, how we mock, what "done" means for a PRapi-conventions.md for response shapes and error formatEdit one file when one convention changes. Rules can also target path patterns, so frontend rules do not bleed into a random script in /scripts.
.claude/agents/ is for personas with one job. I use a code-reviewer.md tuned for performance and missed error paths. I tried a security-auditor.md on an auth PR once. It caught an edge case on session refresh I would have shipped.
They run in isolated context, which keeps the main chat from turning into "also security, also performance, also rewrite the README."
I do not spin these up for every typo. I use them when the diff is scary and I want a focused pass.
Without committed rules, the agent pattern-matches whatever file is on screen. I have had camelCase API responses one day and snake_case the next because it saw different handlers. Small drift. Annoying in review.
With rules in the repo, "API responses use camelCase" is not a suggestion. It loads every session. Same idea as a design system for UI, except for how the agent writes code.
Six months in, the diffs look more like one team's work and less like five freelancers who have never met.
If you are on Claude Code and still opening every chat with the same paragraph, spend half an hour on .claude/. Write the rant once. Then stop giving it.