spaget
guide claude-code

CLAUDE.md explained: configuring claude code the right way

spaget team 5 min read

Claude Code is one of the most capable AI coding tools out there. But drop it into a new project without any context and it’s essentially guessing — smart guessing, sure, but guessing nonetheless. The fix? A well-written CLAUDE.md file that tells Claude exactly how your project works.

What is CLAUDE.md?

CLAUDE.md is a markdown file that lives at the root of your project. When Claude Code starts a session, it reads this file first. Everything inside becomes part of Claude’s working context — your project’s conventions, architecture, tooling preferences, and anything else that helps it write better code.

Think of it as onboarding documentation, except the new hire is an AI that reads really fast and follows instructions remarkably well.

Where does CLAUDE.md go?

Claude Code looks for CLAUDE.md in a few locations, in order of priority:

  1. Project root (./CLAUDE.md) — project-specific instructions, shared with your team via version control
  2. Home directory (~/CLAUDE.md) — personal preferences that apply across all your projects
  3. Nested directories — you can place CLAUDE.md files in subdirectories for context-specific instructions

The project root is the most common and important location. That’s the one your whole team benefits from.

What to put in your CLAUDE.md

A great CLAUDE.md covers several areas without being overwhelming. Here’s a solid structure:

Project overview

Start with the basics. What is this project? What does it do? This helps Claude make better architectural decisions.

# Project


This is a Next.js 14 e-commerce platform using the App Router,
Prisma ORM with PostgreSQL, and Stripe for payments.

Tech stack and conventions

Be explicit about your tools and patterns. Claude knows a lot of technologies, but it needs to know which ones you use.

# Tech stack


- Next.js 14 with App Router (not Pages Router)
- TypeScript in strict mode
- Tailwind CSS for styling — no CSS modules
- Prisma for database access
- Zod for runtime validation


# Conventions


- Use server components by default, client components only when needed
- All API routes use route handlers, not API routes from Pages
- Prefer named exports over default exports
- Use early returns to reduce nesting

Common commands

Tell Claude how to build, test, and deploy. This is surprisingly useful for task automation.

# Commands


- `pnpm dev` — start development server
- `pnpm test` — run Vitest unit tests
- `pnpm lint` — ESLint with auto-fix
- `pnpm db:migrate` — run Prisma migrations

Things to avoid

Just as important as what to do is what not to do. If there are common mistakes or anti-patterns in your stack, call them out.

# Avoid


- Do NOT use `any` type — use `unknown` and narrow instead
- Do NOT create barrel files (index.ts re-exports)
- Do NOT use relative imports for shared modules — use path aliases
- Do NOT commit .env files

Common CLAUDE.md mistakes

Being too vague. “Write clean code” tells Claude nothing. “Keep functions under 30 lines and use early returns” is actionable.

Writing a novel. Your CLAUDE.md eats into the context window. Be concise — if a rule takes a paragraph, simplify the rule itself.

Forgetting to update it. Your project evolves and your CLAUDE.md should too. Stale instructions lead to stale suggestions.

Including secrets. This file gets committed. Don’t put API keys or passwords in it — reference environment variables by name instead.

Duplicating what’s obvious. Claude already knows TypeScript. Focus on what’s specific to your project.

A real-world example

Here’s a condensed CLAUDE.md that covers the essentials:

CLAUDE.md
## Project
SaaS analytics dashboard. Next.js 14, TypeScript, Tailwind, Supabase.


## Conventions
- Server components by default
- Zod schemas for all API inputs
- Use `@/` path alias for imports from src/
- Error boundaries around every route segment
- All dates stored as UTC, displayed in user timezone


## Commands
- `pnpm dev` — development server on port 3000
- `pnpm test` — run tests with Vitest
- `pnpm check` — TypeScript type checking


## Avoid
- No `any` types
- No inline styles — use Tailwind utilities
- No direct database queries in components — use server actions

Short, specific, and immediately useful.

The faster way: build it with spaget

Writing CLAUDE.md by hand is totally doable — but what if you also use Cursor? Or GitHub Copilot? Now you’re maintaining the same instructions in three different formats, and they’re slowly drifting apart.

spaget solves this. You build your agent configuration once, visually, then export to CLAUDE.md, .cursor/rules, or .github/copilot-instructions.md — all from the same source of truth.

No reformatting. No copy-paste drift. And no account required to get started.

Design your agent at app.spaget.ai, export to Claude Code, and get back to building.

The bottom line

CLAUDE.md is the single highest-impact thing you can do to improve your Claude Code experience. A few minutes of thoughtful configuration saves hours of re-prompting, correcting, and wondering why the AI keeps suggesting patterns your team abandoned months ago.

Start simple. Add what matters. Iterate as you learn. Your future self will thank you.