The headache
You're 40 minutes into a Claude Code session. You've explained the architecture, corrected the framework choice twice, and just realized it's trying to rebuild the auth you finished yesterday. Sound familiar?
The fix isn't better prompting. It's six files.
A bit about me
I've built 10+ projects with Claude Code over the past couple of months: web apps, mobile apps, data pipelines, AI tools. Some deployed to production with real users. Along the way, I kept running into the same friction: Claude forgetting context, making wrong assumptions, redoing finished work. These six files are what I landed on after enough pain to stop ignoring the problem.
The two layers
Six files, two layers. The first three handle project context. The last three handle personal identity.
Project layer: SPEC.md → CLAUDE.md → HANDOVER.md
before during between
coding every session sessions
Personal layer: soul.md → hooks → MEMORY.md
who you automatic long-term
are guardrails brain
- CLAUDE.md -- "Here's how we work here." The rulebook Claude reads every session.
- SPEC.md -- "Build THIS, not that." The blueprint before you touch code.
- HANDOVER.md -- "Here's where I left off." The relay baton between sessions.
- soul.md -- "Here's who I am." Your background, style, and values.
- Hooks -- "Here's how I want you to behave." Guardrails and automation.
- MEMORY.md -- "Here's what you've learned about me." Cross-project, long-term memory.
Let me show you what each one actually looks like in practice.
Part 1: The project layer
These three files make Claude remember your project.
File 1: CLAUDE.md -- the rulebook that stops you from repeating yourself
Think of it as a README.md for Claude Code. Except it gets smarter over time.
This is the one you should set up first. If you already have a running project, start here.
The before/after
Without CLAUDE.md -- session 1 on a new project:
Me: "Add a loading skeleton to the gallery page"
Claude: *uses inline CSS*
Me: "No -- we use Tailwind here."
Claude: *adds an emoji icon to the button*
Me: "We use Lucide icons, never emojis in UI."
Claude: *puts the component in /pages*
Me: "It's /components. And it's App Router, not Pages."
Three corrections. Ten minutes wasted. Tomorrow it'll happen again.
With CLAUDE.md -- session 47 on that same project:
Me: "Add a loading skeleton to the gallery page"
Claude: *reads CLAUDE.md -> knows Tailwind, Lucide icons, App Router,
component folder structure, even the learned rule about no emojis*
Claude: *gets it right first try*
The difference isn't Claude getting smarter. It's Claude having context.
Claude reads CLAUDE.md and soul.md automatically at the start of every session. You never paste it.
What goes in it
Project overview, key commands, architecture, conventions. But the most powerful section is Learned Rules. Every time Claude makes a mistake, you add a rule:
### Rule 1: Icons over emojis in UI
- **Trigger**: Generated HTML with emojis for UI elements
- **Correct behavior**: Use Lucide/Heroicons SVGs. Emojis only in content text.
- **Date**: 2026-02-12
Every correction becomes permanent. No mistake happens twice.
When to write it
After initial project setup. Update it as rules accumulate.
The prompt
Read through this project's codebase and generate a CLAUDE.md that covers:
1. Project overview (what it does, tech stack)
2. Key commands (dev, build, test, deploy)
3. Architecture and folder structure
4. Coding conventions and patterns used
5. Error handling approach
6. Testing requirements
7. A "Learned Rules" section (empty for now -- we'll add to it)
Be specific to THIS project. Include actual file paths and real commands.
File 2: SPEC.md -- the conversation you have before writing code
What happens without one
I learned this the hard way. I sat down to build a podcast transcription pipeline -- audio in, transcripts and summaries out, published to a static site. Simple enough, right? I told Claude "build me a podcast pipeline" and started coding.
First session: Claude picked Flask. I wanted FastAPI. It set up a relational database. I needed Firestore. It structured the output as a single JSON blob. I needed per-episode markdown files with frontmatter. It generated a REST API. I needed a CLI that runs on a cron job.
They were wrong for my project. And I didn't realize how many assumptions Claude was making until I was three files deep, undoing scaffolding that looked professional but solved the wrong problem.
That first session? I spent more time correcting architecture than building features. The second session, Claude forgot the corrections and made half the same choices again.
What a good spec looks like
I later found a well-written spec from another project. A structured decision record:
- A tech stack table with why each choice was made
- A folder structure tree showing where everything lives
- ASCII wireframes for each page layout
- API endpoint specs with input/output shapes
- A priority list (P0 = must ship, P3 = nice to have)
That spec was handed to Claude Code and the first session just... worked. No corrections. No "actually, I meant..." because the decisions were already made.
When to write it
Before any code. Have Claude help you draft it. It's great at asking the right scoping questions. Once building starts, SPEC.md is read-only: a snapshot of intent, not a living doc.
The prompt
I'm about to build a new project: [describe the idea in 2-3 sentences].
Before we write any code, help me create a SPEC.md that covers:
1. Tech stack selection (with reasoning)
2. Data sources and APIs
3. Project folder structure
4. Page/screen designs (ASCII wireframes)
5. Key component and API specs
6. UI/UX design system (colors, typography, component style)
7. Environment variables needed
8. Deployment plan
9. Development phases with priorities (P0/P1/P2/P3)
10. Constraints and known limitations
Be opinionated. Challenge my choices if there are better options.
File 3: HANDOVER.md -- the relay baton
The pain
You're deep into a refactor, halfway through migrating an auth system from one library to another. The old JWT validation is ripped out, the new one is half-wired, and three files are in a state that would break if you stopped now. Then the context window compacts. Or you need to close your laptop and pick this up tomorrow.
The new session has no idea what just happened. It re-reads the codebase, sees the half-migrated auth, and tries to "fix" it by reverting to the old library. Or it re-does work the previous session already finished. Or it makes a different architectural choice that contradicts what you decided an hour ago.
I hit this wall during a cleanup sprint across multiple projects. I was refactoring dead code, consolidating duplicates, rewriting docs. The kind of work that spans dozens of files and can't be understood from a cold read of the codebase. Without handovers, every new session would open with "what needs cleaning up?" and re-investigate from scratch. With handovers, each session picked up exactly where the last one stopped: "Phase 1 (folder cleanup) is done, Phase 2 (dead code removal) is in progress, here are the 4 files left to touch."
The relay protocol
Think of it as a relay race, not a diary:
Agent A: *approaching context limit*
-> writes HANDOVER.md (what's done, what's next, gotchas)
Agent B: *new session*
-> reads HANDOVER.md
-> deletes HANDOVER.md <- THIS IS CRITICAL
-> continues the work
-> approaching limit? writes a fresh HANDOVER.md for Agent C
Why delete? Because a stale handover from two sessions ago will poison the current one. The baton is ephemeral. Pick it up, throw it away, keep running.
A real session: Claude reads the handover, clears the file, and picks up where the last agent left off.
The prompts
When hitting context limit (tell the current session):
We're approaching the context limit. Write a HANDOVER.md for the next session:
1. What we accomplished this session
2. Current state (what works, what's broken, what's half-done)
3. Exact next steps with file paths
4. Decisions made and why
5. Gotchas or context the next agent absolutely needs
Be specific -- the next agent has zero context about our conversation.
Starting a new session:
Read HANDOVER.md, then delete or clear the file.
Continue the work from where the previous session left off.
Part 2: The personal layer
The project layer handles what you're building. These three files handle who's building it.
File 4: soul.md -- teach Claude who you are
The problem it solves
Every Claude Code session starts with the same default personality: helpful, thorough, diplomatic. That's fine for a first interaction. By session 50, you want direct, not diplomatic. Concise answers, not thorough explanations. You want Claude to know you're a senior engineer who doesn't need hand-holding, or a self-taught builder who learns by doing.
Without soul.md, Claude treats you the same as every other developer. With it, Claude adapts to how you work.
What goes in it
This isn't a config file. It's a letter to your AI collaborator. Mine includes:
Background. My career path, technical skills, what I'm strong at, what I'm growing into. Not a resume dump, just enough that Claude calibrates its explanations.
Communication style. "Direct and concise. Skip pleasantries. Challenge bad ideas." Claude actually follows this.
Values. What I prioritize when there's a tradeoff. For me: user experience > developer convenience. Ship > perfect. Quality > speed.
What to avoid. Over-engineering, adding features I didn't ask for, sugarcoating problems, long explanations when a short one works.
The result? Claude pushes back when I'm wrong. It keeps responses short. It doesn't pad answers with "Great question!" It knows I'd rather hear "that approach won't scale" than "that's an interesting idea, but you might want to consider..."
Where it lives
In your .claude/ directory. Claude reads it alongside CLAUDE.md at the start of every session.
Two ways to create it
Option A: The interview. Let Claude ask you questions. This works well if you're not sure what to include -- Claude will draw it out of you.
Option B: The resume drop. Share your resume, portfolio, or LinkedIn and let Claude extract the relevant context. Then edit the output -- remove anything too personal, add your communication preferences.
The prompt (interview mode)
I want to create a soul.md file that teaches you who I am as a developer.
Interview me about:
1. My technical background and career path
2. My strongest skills and what I'm actively learning
3. My communication preferences (how direct, how concise, how formal)
4. My values when making tradeoffs (speed vs quality, UX vs DX, etc.)
5. What behaviors annoy me in AI assistants
Ask me 3-5 questions at a time. After the interview, generate a soul.md
file I can place in my .claude/ directory.
The prompt (resume mode)
I'm dropping my resume below. Read it and generate a soul.md file for
my .claude/ directory. Extract:
1. My background and technical skills
2. My career trajectory and what I'm building toward
3. Reasonable inferences about my working style
Then ask me 3-5 follow-up questions about communication preferences
and values that a resume can't capture.
[paste resume or provide file path]
File 5: Hooks -- the guardrails that enforce your rules automatically
The problem it solves
You've told Claude the rules (CLAUDE.md) and who you are (soul.md). But Claude still occasionally commits to main, skips linting, or writes code that doesn't type-check. You catch it in review, but why should you have to?
Claude Code has a hook system: shell scripts that run automatically at key moments. Before Claude acts, after you prompt, after Claude writes code. You describe what you want, Claude generates the scripts and wiring, and the guardrails enforce themselves.
The before/after
Without hooks:
Me: "Add a login form component"
Claude: *writes component*
Me: *runs type-check manually* -> 2 type errors
Me: "Fix the type errors"
Claude: *fixes them*
Me: *runs lint* -> missing import
Me: "Fix the lint error too"
Three round trips. I'm doing QA by hand.
With hooks:
Me: "Add a login form component"
Claude: *writes component*
Hook: *auto-runs type-check and eslint*
Hook: *finds type error, shows Claude the output*
Claude: *fixes it in the same turn*
One round trip. I never ran a command.
Claude writes code, hooks catch type errors, Claude fixes them in the same turn. No manual QA.
Three hooks, three moments
PreToolUse -- runs before Claude acts:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "bash .claude/hooks/branch-guard.sh"
}
]
}
]
}
}
This one checks if you're on main and warns Claude to create a feature branch first. The hook script receives context (tool name, file path, etc.) via stdin as JSON. Parse it with jq and you can build any check you want.
PostToolUse -- runs after Claude writes code:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash .claude/hooks/auto-lint.sh"
}
]
}
]
}
}
The script receives the file path via stdin JSON (tool_input.file_path), then runs type-check and linting on it. Results go back to Claude, who fixes issues immediately. No human in the loop.
UserPromptSubmit -- runs after you type a prompt:
This one's optional but powerful. It can analyze your prompt and suggest relevant context or skills before Claude starts working. Unlike the other two, it doesn't use a matcher. It runs on every prompt.
How to set it up
You don't write the JSON by hand. You describe what you want and Claude generates everything: the shell scripts, the settings.json config, and documentation.
The prompt
I want to set up hooks for my Claude Code project. Help me create:
1. A PreToolUse hook that warns when editing files on main/master
and suggests creating a feature branch first
2. A PostToolUse hook that auto-runs type-check and linting after
Claude writes TypeScript/JavaScript files
3. A PostToolUse hook that auto-runs tests after Claude writes
test files
Generate for each hook:
- The shell script
- The settings.json configuration to wire it up
Hooks should be non-blocking -- show results to Claude, don't halt work.
File 6: MEMORY.md -- the long-term brain
The problem it solves
CLAUDE.md is per-project. soul.md is per-workspace. But some knowledge spans everything: patterns you've confirmed across multiple projects, tools you always reach for, mistakes you've corrected enough times that they should be permanent.
MEMORY.md is Claude Code's built-in long-term memory. It lives at ~/.claude/projects/<your-repo>/memory/MEMORY.md, one per project, derived from your git repository path. Only the first 200 lines load at session start, so it stays concise by design. Unlike the other files, you don't write this one directly. Claude manages it, saving insights as they come up naturally.
My MEMORY.md after a few weeks: design references, user preferences, project-specific notes. All accumulated organically across sessions.
How it actually works
Claude saves to memory when:
- You explicitly say "remember this across sessions"
- A pattern is confirmed across multiple interactions
- You correct a recurring mistake
Claude does NOT save:
- Session-specific tasks or temporary state
- Unverified conclusions from reading a single file
- Anything that duplicates CLAUDE.md
What accumulates over time
After a few weeks of active use, my memory file includes things like:
- "User prefers Tailwind + Lucide stack across all frontend projects"
- "Always use conventional commits format"
- "When deploying to Cloudflare, check edge runtime compatibility first"
- "User's communication style: direct, no fluff, challenge bad ideas"
These aren't things I sat down and wrote. They emerged from sessions. That's the difference between memory and the other files. It's organic.
Seeding it (optional but recommended)
You can jumpstart memory instead of waiting for it to accumulate naturally. The interview and resume prompts from soul.md work here too. Claude will save relevant insights to both soul.md and memory.
The prompt
Remember these preferences across all my projects:
- I always use [framework/tool] for [purpose]
- My commit style is [conventional commits / etc.]
- When I say "make it production-ready" I mean [your definition]
- Never [thing you've corrected multiple times]
Save these to your memory so they persist across sessions.
The full picture
Project layer: SPEC.md -> CLAUDE.md -> HANDOVER.md
Personal layer: soul.md -> hooks -> MEMORY.md
The project layer handles context. The personal layer handles identity. Set up both and Claude Code knows your project, your preferences, and where you left off.
Copy-paste prompt kit
All six prompts in one place. Save these and you're set.
Generate SPEC.md (run before coding)
I'm about to build a new project: [describe the idea in 2-3 sentences].
Before we write any code, help me create a SPEC.md that covers:
1. Tech stack selection (with reasoning)
2. Data sources and APIs
3. Project folder structure
4. Page/screen designs (ASCII wireframes)
5. Key component and API specs
6. UI/UX design system (colors, typography, component style)
7. Environment variables needed
8. Deployment plan
9. Development phases with priorities (P0/P1/P2/P3)
10. Constraints and known limitations
Be opinionated. Challenge my choices if there are better options.
Generate CLAUDE.md (run after initial setup)
Read through this project's codebase and generate a CLAUDE.md that covers:
1. Project overview (what it does, tech stack)
2. Key commands (dev, build, test, deploy)
3. Architecture and folder structure
4. Coding conventions and patterns used
5. Error handling approach
6. Testing requirements
7. A "Learned Rules" section (empty for now -- we'll add to it)
Be specific to THIS project. Include actual file paths and real commands.
Write HANDOVER.md (run before context limit)
We're approaching the context limit. Write a HANDOVER.md for the next session:
1. What we accomplished this session
2. Current state (what works, what's broken, what's half-done)
3. Exact next steps with file paths
4. Decisions made and why
5. Gotchas or context the next agent absolutely needs
Be specific -- the next agent has zero context about our conversation.
Resume from HANDOVER.md (run at session start)
Read HANDOVER.md, then delete or clear the file.
Continue the work from where the previous session left off.
Generate soul.md -- interview mode
I want to create a soul.md file that teaches you who I am as a developer.
Interview me about:
1. My technical background and career path
2. My strongest skills and what I'm actively learning
3. My communication preferences (how direct, how concise, how formal)
4. My values when making tradeoffs (speed vs quality, UX vs DX, etc.)
5. What behaviors annoy me in AI assistants
Ask me 3-5 questions at a time. After the interview, generate a soul.md
file I can place in my .claude/ directory.
Generate soul.md -- resume mode
I'm dropping my resume below. Read it and generate a soul.md file for
my .claude/ directory. Extract:
1. My background and technical skills
2. My career trajectory and what I'm building toward
3. Reasonable inferences about my working style
Then ask me 3-5 follow-up questions about communication preferences
and values that a resume can't capture.
[paste resume or provide file path]
Set up hooks
I want to set up hooks for my Claude Code project. Help me create:
1. A PreToolUse hook that warns when editing files on main/master
and suggests creating a feature branch first
2. A PostToolUse hook that auto-runs type-check and linting after
Claude writes TypeScript/JavaScript files
3. A PostToolUse hook that auto-runs tests after Claude writes
test files
Generate for each hook:
- The shell script
- The settings.json configuration to wire it up
Hooks should be non-blocking -- show results to Claude, don't halt work.
Seed MEMORY.md
Remember these preferences across all my projects:
- I always use [framework/tool] for [purpose]
- My commit style is [conventional commits / etc.]
- When I say "make it production-ready" I mean [your definition]
- Never [thing you've corrected multiple times]
Save these to your memory so they persist across sessions.
The setup checklist
For your next project:
- Write SPEC.md before any code (or have Claude draft it with you)
- Generate CLAUDE.md after initial setup
- Use the HANDOVER.md relay whenever sessions get long
- Create soul.md once, reuse across all projects
- Add hooks after your first "I wish Claude had caught that" moment
- Let MEMORY.md grow on its own -- seed it if you're impatient
Six files. Zero repeated explanations. I hope this article helps you kickstart your wonderful journey as a builder.
Top comments (0)