Six small files that turn a coding agent from a clever stranger into a teammate who knows how your project works.
Day one with Claude Code goes like this.
You explain your project. Tests live in /tests, not next to the code. We use pnpm, not npm. Never touch the migration files by hand. Claude nods, does good work, and you go home impressed.
Day two, you open a new session. It runs npm install. It writes tests next to the code. It edits a migration file.
It didn’t get worse overnight. It just doesn’t remember. Every session starts from zero, with a very capable stranger who has never seen your repo.
Most people react by typing the same instructions again every morning. That works, but it’s slow, and you’ll forget something.
The better fix is to stop explaining and start writing it down, in the places Claude Code already looks.
Here’s the whole idea in one sentence: the model is the same for everyone, so the difference is in what your repo tells it.
Claude Code reads a handful of files every time it starts. Get them right once and every session, for every person on your team, starts with the same knowledge.
There are six pieces. You don’t need all of them on day one. Start at the top and add the next one when you feel the pain it solves.
[IMAGE: claude-code-setup.png. Caption: “Six pieces, one folder. The first four are instructions Claude follows; the last two are enforced by Claude Code itself.”]
“It forgets how our project works” → CLAUDE.md
“It starts editing before it understands” → Plan mode
“I explain the same procedure every week” → Skills
“Big tasks fill up its memory with noise” → Subagents
“It ignores a rule I really care about” → Hooks
“I click approve fifty times a day” → Permissions
This is a plain markdown file in your repo root. Claude Code loads it at the start of every session, so anything in it never has to be said again.
Don’t start with a blank page. Run /init inside Claude Code and it writes a first draft by reading your repo. If you already have one, it suggests improvements instead of overwriting it.
Then edit it down to what a new hire would actually need:
## Commands
- Install: `pnpm install` (never npm)
- Test: `pnpm test`
- Lint and format: `pnpm lint --fix`
## Rules
- Tests go in /tests, mirroring the src/ folder structure
- Never edit files in /migrations by hand; run `pnpm db:migrate:new`
- All dates are UTC in the database, local time only in the UI
## Where things are
- API routes: src/api/
- Report templates: src/templates/
- Shared types: src/types/ (check here before creating a new type)
Three rules that make this file work:
Keep it short. Anthropic’s docs suggest under 200 lines. Every line costs context in every session, whether it’s relevant or not.
Write commands, not essays. “Run pnpm test" beats "We value thorough testing."
Split by folder when it grows. A CLAUDE.md inside src/api/ only loads when Claude starts working in that folder. Your API conventions don't need to sit in memory while it edits CSS.
Two more files worth knowing about: ~/.claude/CLAUDE.md applies to every project on your machine (good for personal habits), and CLAUDE.local.md is for personal notes on this project that shouldn't be committed. Add it to .gitignore.
The most expensive Claude Code mistake isn’t bad code. It’s good code in the wrong place, built on a wrong assumption, across twelve files.
Plan mode fixes that. Press Shift+Tab to cycle through the modes until you reach plan mode, or start your message with /plan. In plan mode, Claude reads your code and writes a plan, but it can't edit anything until you approve.
Use it for anything bigger than a one-file change. Read the plan. Correct the one wrong assumption. Then let it build. Two minutes of reading saves an hour of undoing.
Every team has procedures that live in someone’s head. How we add a new API endpoint. How we cut a release. How we write a database migration.
A skill is that procedure, written down where Claude can find it. It’s a folder with one markdown file:
.claude/skills/new-endpoint/SKILL.md
---
name: new-endpoint
description: "Adds a new REST API endpoint. Use when the user asks to add, create or expose a new API route."
---1. Create the route in src/api/<resource>.ts using the pattern in src/api/vessels.ts
2. Add request and response types to src/types/api.ts
3. Add input validation with zod. Never trust request bodies.
4. Write tests in tests/api/<resource>.test.ts covering success, bad input, and not found
5. Run `pnpm test` and fix failures before reporting done
Two things make skills better than stuffing everything into CLAUDE.md:
They cost almost nothing until they’re needed. Only the one-line description sits in context. The full instructions load when Claude decides the skill applies, or when you type /new-endpoint.
The description does the routing. Write it like a trigger: what it does, then “Use when…”. A vague description means a skill that never fires.
If you have old files in .claude/commands/, they still work. Skills are where new ones should go.
Ask Claude to “find everywhere we calculate fuel consumption” and it might read forty files. All of that lands in its working memory, and the next thing you ask gets a slower, more confused answer.
A subagent is a helper with its own separate context window. It does the noisy work, and only the summary comes back to your main conversation.
.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code changes for bugs, missing tests and security issues. Use after finishing a feature or before a commit.
tools: Read, Grep, Glob
model: sonnet
---You are a careful senior reviewer. Look at the uncommitted changes.
Report, in order of severity:
1. Bugs or logic errors
2. Missing or weak tests
3. Security issues (secrets, injection, unchecked input)
Be specific: file, line, and the fix. Skip style nitpicks.
Notice the tools line. This reviewer can read and search, but it can't edit. That's deliberate. A reviewer that fixes things as it goes stops being a reviewer.
Good first subagents: a code reviewer, a “find where X happens” researcher, and a test writer.
Here’s the limit of everything above: CLAUDE.md, skills and subagents are all instructions. Claude follows them very well, but an instruction is still a request. On a long task, in a crowded context, a request can slip.
Some rules can’t be allowed to slip. For those, you want a hook: a small script that Claude Code itself runs at a fixed moment, whatever the model decides.
The first hook almost everyone should add formats every file right after Claude edits it, so you never review a diff full of whitespace changes:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
]
}
]
}
}
The second one protects files that should never be touched. This hook runs before any edit, and if the file is a .env file, it blocks the edit:
#!/bin/bash
file=$(jq -r '.tool_input.file_path // empty')
if [[ "$(basename "$file")" == .env* ]]; then
echo "Blocked: .env files are protected" >&2
exit 2
fi
exit 0
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-env.sh" }
]
}
]
}
}
Exit code 2 is the important bit. It stops the edit and sends your message back to Claude, so it understands why and tries something else.
The rule of thumb: if breaking the rule would be annoying, put it in CLAUDE.md. If breaking it would be expensive, make it a hook.
By default, Claude Code asks before running commands. That’s the right default, and it gets old fast when it asks for the hundredth time whether it may run your tests.
Add the safe, boring commands to an allowlist in .claude/settings.json, and block the dangerous ones outright:
{
"permissions": {
"allow": ["Bash(pnpm test *)", "Bash(pnpm lint *)", "Bash(git status *)", "Bash(git diff *)"],
"deny": ["Bash(git push *)", "Bash(rm -rf *)"]
}
}
Deny rules always win over allow rules, so a broad block stays a block. Run /permissions to see every rule in force and which file it came from.
Like hooks, these are enforced by Claude Code itself, not by the model. Writing “never push to main” in CLAUDE.md is a wish. A deny rule is a lock.
One more thing to know on day one. If Claude heads off in the wrong direction, press Esc twice (or type /rewind) and you can roll back the code, the conversation, or both, to any earlier point.
Two caveats. It doesn’t track changes made through shell commands or by you outside Claude Code. And it’s not version control. Commit early, commit often, and treat rewind as the quick undo, not the history.
It’s easy to overdo this, and an overbuilt setup is worse than none.
A 900-line CLAUDE.md is a tax on every session. If a rule only matters in one folder, move it to that folder’s CLAUDE.md or into a skill. Run /context now and then to see what's actually filling the window.
Skills you never use still cost a line each. Ten sharp skills beat forty vague ones.
Don’t automate a procedure you haven’t done by hand. Write the skill after you’ve done the task twice and know where it goes wrong, not before.
Be careful with extensions from strangers. Claude Code’s newer mods and plugins can run code with your full permissions, and mods aren’t sandboxed. Anthropic’s own docs warn they can read your API keys. Install only from authors you trust.
For a weekend script, skip all of it. This setup pays off on a codebase you’ll live in for months, especially one a team shares.
Two developers can use the exact same model, on the same plan, on the same day, and get completely different results.
It’s tempting to say one of them is better at prompting. Usually that isn’t it. One of them spent an afternoon writing down how their project works, and the other one explains it again every morning.
The model is the same for everyone. The folder is yours.
So here’s the challenge: open your repo and look for a .claude/ folder. If it's empty or missing, what are you explaining to Claude, by hand, every single day?
I’m keeping a starter .claude/ folder (CLAUDE.md template, reviewer subagent, formatter and .env hooks, a permissions file) in the ops-ai repo](https://github.com/tarunagarwal1981)*). Copy it, strip what you don't need, and open an issue if you find a hook worth sharing.
Want the full version, ready to install? The Claude Code Starter Kit adds a one-command installer, five CLAUDE.md templates, five subagents, ten tested hooks and a one-page cheat sheet of what to type.
Sources: Claude Code documentation on memory and CLAUDE.md, skills](https://code.claude.com/docs/en/skills)*), subagents](https://code.claude.com/docs/en/sub-agents)*), hooks](https://code.claude.com/docs/en/hooks)*), permission modes](https://code.claude.com/docs/en/permission-modes)*), permissions](https://code.claude.com/docs/en/permissions)*) and checkpointing](https://code.claude.com/docs/en/checkpointing)*); coverage of Claude Code mods at MIXED.](https://mixed-news.com/en/claude-code-2-1-287-mods-not-sandboxed-api-key)*.*)
Originally published on Towards AI.