Setting Up a New Project with Claude Code: The Right Way
The most important Claude Code configuration file is CLAUDE.md — placed at the project root, it's automatically read at the start of every session and sets the context Claude uses for all work in that project. Without it, Claude starts every session knowing nothing about your project structure, conventions, or constraints. With a well-written CLAUDE.md, Claude behaves like a developer who has been on the project for months. This guide covers what to put in CLAUDE.md and the initial setup workflow that makes Claude Code immediately productive.
What CLAUDE.md is and why it matters
CLAUDE.md is a markdown file at your project root that Claude Code reads automatically at session start. It's your way of telling Claude:
- What the project does
- How the codebase is structured
- What commands to run (tests, build, lint)
- What conventions to follow
- What not to do
Without CLAUDE.md, Claude relies on reading files and asking questions every session. With it, Claude starts with full context.
CLAUDE.md template
# Project: [Project Name]
## What this project is
[1-2 sentences describing what the project does and who it's for]
## Architecture
- **Framework**: [Next.js 15 / FastAPI / Express / etc.]
- **Database**: [Neon PostgreSQL / Supabase / etc.]
- **Auth**: [Clerk / NextAuth / etc.]
- **Deployment**: [Vercel / Fly.io / etc.]
- **Key libraries**: [list main dependencies]
## Directory structure
src/ app/ # Next.js App Router pages components/ # Reusable UI components lib/ # Shared utilities (db, auth, api clients) hooks/ # Custom React hooks types/ # TypeScript type definitions
## Development commands
- `bun dev` — start dev server (localhost:3000)
- `bun run build` — production build
- `bun run typecheck` — TypeScript check
- `bun run lint` — ESLint
- `bun test` — run tests
## Code conventions
- TypeScript strict mode — no `any`, no type assertions unless necessary
- Imports: components from `@/components`, utils from `@/lib`
- Error handling: always handle Promise rejections, never silent catches
- Database: use Drizzle ORM, never raw SQL strings
- Components: functional components only, no class components
## What NOT to do
- Don't install new dependencies without asking — check if we have something equivalent
- Don't modify `schema.ts` without running a migration check
- Don't push to main — all changes via PRs
- Don't use `console.log` in production code — use the logger in `lib/logger.ts`
## Environment variables
Required vars are in `.env.example`. Copy to `.env.local` and fill in values.
Never commit `.env.local` or any file with actual credentials.
## Testing conventions
- Unit tests: colocated with source files (`*.test.ts`)
- Integration tests: `tests/` directory
- Run tests before every PR
What to put in each section
Project description
One to two sentences that answer: what does this project do, who uses it, what problem does it solve? This helps Claude understand context before reading any code.
## What this project is
A cost monitoring dashboard for Anthropic API users. Developers connect their
API key and see real-time cost breakdowns by model, usage trends, and
optimisation suggestions. SaaS product at claudecosts.app.
Architecture section
List the key technology choices. Claude will give better suggestions when it knows you're using Drizzle instead of Prisma, Neon instead of Supabase, Bun instead of npm.
Commands section
The commands section is critical. Claude needs to know exactly how to:
- Run the dev server
- Build for production
- Run tests
- Check types
- Lint
Format them as a list with the exact command. Claude will run these during development without asking.
Conventions section
Document the conventions that aren't obvious from the code. Examples:
- How to handle errors (throw vs return vs log)
- Whether to use async/await or Promises
- Component organisation patterns
- API response shapes
- Naming conventions for files, functions, variables
What NOT to do
This is the most important section for avoiding common mistakes. List the decisions you've already made that Claude shouldn't undo:
## What NOT to do
- Don't switch from Bun to npm — Bun is intentional for build speed
- Don't add Prisma — we use Drizzle and migrating would be significant work
- Don't add React Query — we use server components for data fetching
- Don't modify the auth middleware — it has subtle requirements for the app router
Initial project setup workflow
When starting a new project with Claude Code:
1. Run the exploration command first
# Ask Claude to understand the project before doing anything
# In Claude Code:
> Read the README and key source files to understand the project.
> Then tell me the 5 things you'd need to know before implementing any features.
Claude's answer reveals what context is missing. Add the answers to CLAUDE.md.
2. Ask Claude to generate the initial CLAUDE.md
> Read the project files and generate a CLAUDE.md for this project.
> Include: project description, directory structure, dev commands,
> conventions you can infer from the code, and any anti-patterns you notice.
Review Claude's output and correct anything wrong. This saves 30 minutes of manual writing.
3. Verify the commands work
> Run the dev server and confirm it starts without errors.
> Then run the type checker and lint. Report any issues.
This establishes a baseline before any changes.
Tool permissions configuration
Create .claude/settings.json to pre-approve safe operations:
{
"permissions": {
"allow": [
"Bash(bun run typecheck)",
"Bash(bun run lint)",
"Bash(bun run build)",
"Bash(bun test)",
"Bash(git log *)",
"Bash(git diff *)",
"Bash(git status)"
],
"deny": [
"Bash(git push *)",
"Bash(rm -rf *)"
]
}
}
Allow: safe read operations and commands you run frequently. Deny: destructive operations that should require explicit confirmation.
This eliminates permission prompts for safe commands while keeping a confirmation gate on dangerous ones.
Project-specific context files
For larger projects, create additional context files that Claude can reference:
.claude/
settings.json # Tool permissions
context/
database.md # Database schema and query patterns
api.md # API routes and response shapes
components.md # Component library and usage patterns
decisions.md # Architecture decisions and why
Reference them in CLAUDE.md:
## Additional context
- Database patterns: `.claude/context/database.md`
- API documentation: `.claude/context/api.md`
Claude will read these when they're relevant to the task at hand.
Common first-session tasks
After setup, the most productive first-session tasks:
1. Get a full project audit:
> Read the entire codebase and give me:
> (1) What's working well
> (2) Technical debt you noticed
> (3) Missing error handling
> (4) Security concerns
2. Establish the testing baseline:
> Run the test suite and report: what passes, what fails,
> and what has zero test coverage that should have tests.
3. Get a dependency review:
> Check package.json and flag: (1) unused dependencies,
> (2) outdated packages with breaking changes,
> (3) security vulnerabilities via npm audit.
Frequently asked questions
Does CLAUDE.md apply to Claude Code CLI only, or also the Claude.ai interface? CLAUDE.md is a Claude Code CLI feature. The claude.ai web interface doesn't read project files automatically. For the API, you'd include CLAUDE.md content in the system prompt manually.
How long should CLAUDE.md be? Long enough to cover everything Claude needs to be effective; no longer. 200–500 words covers most projects well. For complex projects with many conventions, 1,000 words is reasonable. Token length isn't a concern since CLAUDE.md is cached at session start.
Should I commit CLAUDE.md to git? Yes. CLAUDE.md is project documentation. Every team member and every Claude Code session benefits from it. It's not a personal file — it's the project's instructions for AI assistance.
What's the difference between CLAUDE.md and a system prompt?
Functionally similar, but CLAUDE.md is loaded automatically from the project root. You don't have to pass it anywhere. System prompts require explicit passing via the API system parameter. Use CLAUDE.md for Claude Code; use system prompts for API applications.
Can I have multiple CLAUDE.md files in subdirectories? Yes. Claude Code reads CLAUDE.md files hierarchically — the root CLAUDE.md plus any CLAUDE.md in the subdirectory you're working in. Useful for monorepos where each package has its own conventions.
Related guides
- Claude Code Tips from Power Users — advanced workflow patterns
- How to Get Claude Code to Fix Its Own Bugs — debugging workflow that builds on project setup
Take It Further
Power Prompts 300: Claude Code Productivity Patterns — Section 1 covers 30 project setup prompts: the CLAUDE.md generation template, initial audit prompts, team onboarding scripts, and the project exploration sequence that gets Claude up to speed in 10 minutes.
30-day money-back guarantee. Instant download.