Originally published at claudeguide.io/claude-code-first-project-setup
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 in 2026. 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
bash
# Ask Claude to understand the project before doing anything
# In Claude Code:
[→ Get Power Prompts 300 — $29](https://shoutfirst.gumroad.com/l/agfda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-code-first-project-setup)
*30-day money-back guarantee. Instant download.*
Top comments (0)