Originally published at devtoolpicks.com
Most CLAUDE.md files are written once, during initial setup, then forgotten. They contain three lines about the tech stack and a reminder to write tests. Claude ignores half of it because nothing is specific enough to actually constrain its behavior.
The developers getting consistent results from Claude Code treat CLAUDE.md the same way they treat their test suite: something they update whenever they catch Claude making the same mistake twice.
This guide is specifically for solo developers and indie hackers running SaaS projects. Not enterprise teams with 10-person engineering orgs. Just you, your codebase, and an AI agent that needs to understand your project in the first 30 seconds of every session.
What does CLAUDE.md actually do?
CLAUDE.md is a markdown file in your project root. Claude Code reads it at the start of every single session, before you type anything. It's the closest thing Claude has to persistent memory about your project.
Without it, Claude defaults to whatever pattern showed up most in its training data. For Laravel projects that often means Laravel 8-era tutorial code. For Node projects it might be CommonJS imports when you've moved to ESM. For any project, it means Claude guessing at conventions instead of knowing them.
The practical constraint worth understanding: every line in CLAUDE.md loads into the context window at the start of every session. A 500-line CLAUDE.md wastes tokens before you've written a single prompt. Keep it short. Use the @path/to/file import syntax to pull in detail files for sections that need more depth.
Run /init to generate a starter based on your actual codebase. It detects your build system, test framework, and code patterns automatically. Treat the output as a starting point to trim, not a finished document.
The 5 sections that actually matter
1. Your tech stack (2-3 lines, not a paragraph)
Claude needs your actual versions, not generic stack names.
## Tech Stack
- Laravel 12, PHP 8.4, PostgreSQL
- Vue 3 + Inertia.js, Tailwind CSS v4
- Pest for tests, Pint for formatting
Three lines. That's it. Don't list every package. Don't explain what Laravel is. Claude knows. What it doesn't know is that you're on Laravel 12 with Filament v4, not the Laravel 10 + Filament v3 that dominated its training data.
2. Your run commands (the highest-value section)
This is where most CLAUDE.md files fail. Claude can generate code, but if it can't run your test suite to verify the code works, it becomes your feedback loop instead of its own.
## Commands
- Run tests: `./vendor/bin/pest`
- Single test: `./vendor/bin/pest --filter="test name"`
- Format code: `./vendor/bin/pint`
- Check types: `./vendor/bin/phpstan analyse`
- Start dev server: `php artisan serve`
- Run queue worker: `php artisan queue:work`
Claude performs significantly better when it can verify its own work. Give it the commands to do that. The official documentation calls this "the single highest-leverage thing you can do." Every time Claude writes a feature and then runs your tests without being asked, your commands section is doing that work.
3. Your architecture pattern (what lives where)
For a solo SaaS project, Claude needs to know your patterns so it doesn't invent new ones every time.
## Architecture
- Controllers stay thin: validation via Form Requests, logic in Service classes
- No business logic in models or controllers
- API responses use Resources, never raw model output
- Queue jobs live in app/Jobs, always implement ShouldQueue
- No env() calls outside of config files
## Key directories
- app/Services/ # business logic
- app/Actions/ # single-purpose operations
- app/Http/Resources/ # API response formatting
The "what lives where" map prevents Claude from creating a new pattern when your existing one would work fine. Without this, Claude invents a fresh approach each session.
4. The Don't section (your hardest rules)
This is the most underused section and arguably the most important one for a solo developer. The Don't section is where you capture every mistake you've already fixed once and don't want to fix again.
## Don't
- Never use raw SQL. Eloquent only, unless there's a documented reason
- Never call env() outside config/ files
- Never write tests using PHPUnit syntax. Pest only.
- Never add global helpers. Use service injection
- Never chain multiple artisan make: commands with &&. Timestamps will collide.
- Never edit migrations that have been run in production. Always create new ones
- No commented-out code. Delete it or document the reason it's staying
Every item in this list represents a real mistake. When Claude violates one of these, add it to the list immediately. Over time, the Don't section becomes a compressed history of everything that has gone wrong on your project.
The official Claude Code docs confirm you can add IMPORTANT or YOU MUST emphasis to critical rules:
## Don't
- IMPORTANT: Never call env() outside config files. This breaks config caching.
- YOU MUST use Pest syntax for all tests, never PHPUnit-style.
5. The anti-sycophancy instruction
This one is not in most CLAUDE.md templates, but it makes a measurable difference. LLMs tend to agree with whatever the user says. If you propose a bad approach, Claude will often implement it instead of pushing back.
One instruction that consistently helps, based on real developer experience:
## How to interact with me
Don't agree with my suggestions by default. If I propose something questionable,
say so. Challenge my assumptions. Ask what I'm treating as true that might be wrong.
I want a real technical opinion, not confirmation.
The Geocodio engineering team reported this single instruction "dramatically improved the quality of conversations" and reduced the sycophancy that makes AI code assistants unreliable on complex decisions. As a solo developer with nobody to sanity-check your architecture decisions, having Claude push back when you're heading the wrong direction is genuinely useful.
What to skip
A lot of CLAUDE.md templates include sections that help teams but add noise for a solo developer.
Skip the onboarding guide. You don't need to explain the project history or why certain decisions were made the way you'd document it for a new hire. Claude does not need context it cannot act on.
Skip generic coding principles. "Write clean code" and "follow SOLID principles" tell Claude nothing it doesn't already know. Only include principles that constrain Claude's default behavior specifically for your project.
Skip exhaustive dependency lists. List the packages that affect how Claude should write code (your auth package, your payment library, your admin panel). Don't list utilities Claude uses the same way regardless of which specific package you chose.
Skip the README summary. You can import your README with @README.md if Claude needs project context, but summarizing your README inside CLAUDE.md just duplicates information.
A working template for a solo SaaS project
Copy this and adjust for your stack:
# Project Name
## Tech Stack
- [Framework + version, Language + version, Database]
- [Frontend stack]
- [Test framework, formatter, linter]
## Commands
- Run tests: [your test command]
- Run single test: [your filtered test command]
- Format: [your formatter command]
- Dev server: [your dev command]
## Architecture
- [Where business logic lives]
- [Where validation lives]
- [Where API responses are formatted]
- [Your key directories]
## Conventions
- [Naming convention that differs from framework default]
- [Pattern you use consistently, e.g. thin controllers]
- [Test approach, e.g. integration-first]
## Don't
- [Hard rule 1: your most important constraint]
- [Hard rule 2]
- [Hard rule 3]
- IMPORTANT: [Your most critical rule]
## How to interact with me
Push back when I propose something questionable.
Challenge assumptions. Give honest technical opinions.
The /init shortcut
If you are setting up Claude Code on an existing project for the first time, run /init before writing your CLAUDE.md manually. Claude Code analyzes your codebase and generates a reasonable starter file automatically.
What /init generates well:
- Your tech stack detection
- Your test framework and command syntax
- Your package manager
What /init misses:
- Your architecture decisions and patterns
- Your Don't rules (it cannot know what mistakes you've made)
- Your anti-sycophancy preference
- Anything specific to your business domain
Use /init as the foundation. Add the Don't section and the architecture pattern manually. The combination gets you to a useful CLAUDE.md in about 20 minutes.
How this fits into the broader Claude Code setup
CLAUDE.md is one layer of how you give Claude context. The .claude/ directory holds the rest: hooks that run automatically after certain actions, custom commands you invoke with slash syntax, and skills for domain-specific knowledge.
For the full picture on using Claude Code for agentic coding and how it compares to Codex and other tools in 2026, the Codex /goal vs Claude Code comparison covers when each tool makes more sense and what the pricing looks like across both.
The CLAUDE.md file is where you start. Run /init, trim it down, add your Don't rules, and commit it. Every time Claude makes the same mistake twice, add a line. After a month, you'll have a file that genuinely reflects how your project works, and Claude's output will reflect that too.
Top comments (0)