Project Initialization: CLAUDE.md and Project Context

You ask Claude to add a new API endpoint and it generates Express-style code — but your project uses Hono. You ask it to write tests and it reaches for Jest, when your repo uses Vitest with a custom configuration. Every session starts with you correcting Claude about your stack, your conventions, and your file structure. A well-crafted CLAUDE.md file eliminates this pattern entirely.

This guide shows you how to create and maintain the memory files that teach Claude about your specific project, so it writes code that fits your codebase from the first prompt.

What You’ll Walk Away With

• A CLAUDE.md file tailored to your project’s architecture and conventions
• Modular rules in .claude/rules/ for topic-specific instructions
• Understanding of the full memory hierarchy (managed, user, project, local)
• Auto memory configured to learn your preferences over time

The Memory Hierarchy

Claude Code loads instructions from multiple locations. Understanding the hierarchy helps you put the right instructions in the right place.

Memory Type	Location	Who Sees It	Loaded When
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md	All users	Always
User memory	~/.claude/CLAUDE.md	Just you, all projects	Always
Project memory	./CLAUDE.md or ./.claude/CLAUDE.md	All team members	Always (root)
Project rules	./.claude/rules/*.md	All team members	Always
Local memory	./CLAUDE.local.md	Just you, this project	Always
Auto memory	~/.claude/projects/<project>/memory/	Just you, per project	First 200 lines
Child CLAUDE.md	./subdir/CLAUDE.md	All team members	On demand

More specific instructions take precedence over broader ones. A project-level rule overrides a user-level preference. CLAUDE.local.md is automatically gitignored, making it safe for personal preferences.

Bootstrap with /init

The fastest way to start is the /init command inside a Claude Code session:

cd /path/to/your/project
claude

Then inside the session:

/init

Claude will analyze your project structure, detect your tech stack, and generate a CLAUDE.md with:

• Key commands (build, test, lint, format)
• Detected technologies and frameworks
• Directory structure overview
• Basic coding conventions

Caution

The auto-generated CLAUDE.md is a starting point, not a finished product. You must customize it with your actual coding standards, architectural decisions, and team conventions. The generic version will produce generic results.

Anatomy of a Great CLAUDE.md

Here is a production-quality template. Copy the structure and fill in your project specifics:

# Project: [Your Project Name]

## Key Commands
- `npm run dev` - Start development server (port 3000)
- `npm run build` - Production build
- `npm run test` - Run Vitest tests
- `npm run test:watch` - Watch mode
- `npm run lint` - ESLint check
- `npm run format` - Format with Prettier
- `npm run type-check` - TypeScript checking

## Architecture
- **Framework**: Next.js 14 with App Router
- **Language**: TypeScript (strict mode)
- **Styling**: Tailwind CSS with shadcn/ui components
- **Database**: PostgreSQL with Drizzle ORM
- **Auth**: NextAuth.js v5 with Google/GitHub providers
- **Testing**: Vitest + React Testing Library

## Coding Conventions
- Use functional components with TypeScript interfaces (not types) for props
- Prefer named exports over default exports
- Use `async/await` over `.then()` chains
- Error handling: always catch and log, never silently swallow errors
- Imports: external deps first, then internal absolute (`~/`), then relative

## File Organization
- `src/app/` - Next.js App Router pages and layouts
- `src/components/` - Reusable UI components
- `src/lib/` - Utility functions and shared logic
- `src/lib/db/` - Database schema and queries (Drizzle)
- `src/server/` - Server-only code (API handlers, auth)

## Important Patterns
- All API routes return `NextResponse.json()` with explicit status codes
- Database queries go through `src/lib/db/queries.ts`, not inline
- Components follow the pattern: interfaces first, hooks, handlers, render
- Never use `any` - use `unknown` and narrow the type

Tip

Copy-paste prompt to generate a custom CLAUDE.md:

Analyze this entire codebase. Then write a CLAUDE.md file that includes:
1. All key commands from package.json scripts
2. The tech stack with specific versions
3. Coding conventions based on existing code patterns
4. File organization and what each directory contains
5. Important architectural patterns you observe
6. Common mistakes to avoid based on the code style

Format it as a markdown file I can save directly as CLAUDE.md.

Modular Rules with .claude/rules/

For larger projects, splitting instructions into focused files is cleaner than one massive CLAUDE.md. Place markdown files in .claude/rules/:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       ├── api-design.md   # API endpoint patterns
│       └── security.md     # Security requirements

All .md files in .claude/rules/ are automatically loaded as project memory.

Path-Specific Rules

Rules can be scoped to specific files using YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
  - "src/server/**/*.ts"
---

# API Development Rules

- All API endpoints must validate input with Zod schemas
- Return standardized error responses with { error: string, code: number }
- Include rate limiting middleware on public endpoints
- Log all 5xx errors to our monitoring service

Rules without a paths field apply to all files. Rules with paths only load when Claude works with matching files.

Organizing Rules by Concern

.claude/rules/
├── frontend/
│   ├── react.md        # React component patterns
│   └── styling.md      # Tailwind conventions
├── backend/
│   ├── api.md          # API design patterns
│   └── database.md     # Query patterns
└── general.md          # Universal rules

All .md files are discovered recursively, so subdirectories work fine.

CLAUDE.md Imports

You can import external files into your CLAUDE.md using @path/to/file syntax:

See @README.md for project overview and @package.json for available commands.

# Additional References
- API docs: @docs/api-reference.md
- Git workflow: @docs/git-workflow.md

Both relative and absolute paths work. Relative paths resolve from the file containing the import. Imports can be nested up to 5 levels deep.

Note

The first time Claude Code encounters external imports in a project, it shows an approval dialog. Once approved, imports load silently on subsequent sessions.

User-Level Memory

For preferences that apply across all your projects, edit ~/.claude/CLAUDE.md:

# Personal Preferences

- I prefer detailed explanations with code examples
- Always show the full file path when creating new files
- When writing tests, include both happy path and error cases
- Use British English in comments and documentation

You can also create user-level rules in ~/.claude/rules/:

~/.claude/rules/
├── preferences.md    # Your coding preferences
└── workflows.md      # Your preferred workflows

Auto Memory

Claude Code can automatically save learnings across sessions. Auto memory records project patterns, debugging insights, and your preferences without you manually editing files.

To opt in (if not yet enabled by default):

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

Auto memory is stored at ~/.claude/projects/<project>/memory/MEMORY.md. The first 200 lines are loaded into every session. Detailed notes go into topic files that Claude reads on demand.

You can ask Claude to remember things explicitly:

Remember that we use pnpm, not npm, in this project.

Save to memory that the API tests require a local Redis instance running on port 6379.

Use /memory to open the memory file selector and edit any memory file directly.

Tip

Copy-paste prompt to audit your CLAUDE.md effectiveness:

Read my CLAUDE.md file and evaluate it against these criteria:
1. Does it include all key commands from package.json?
2. Does it accurately describe the tech stack?
3. Are coding conventions specific enough to be useful?
4. Are there any outdated or incorrect instructions?
5. What important patterns am I missing?

Suggest concrete improvements with exact text to add.

CLAUDE.local.md for Personal Overrides

For project-specific preferences that should not be committed to git, use CLAUDE.local.md in the project root:

# My local preferences

- My local API runs on port 8080, not the default 3000
- Use my test database: postgresql://localhost:5433/myapp_test
- When running E2E tests, use --headed flag so I can watch

This file is automatically gitignored. It is loaded alongside the project CLAUDE.md but only affects your local sessions.

When This Breaks

Claude ignores your CLAUDE.md instructions — Make sure the file is in the project root or at .claude/CLAUDE.md. Claude loads memory files relative to the directory where you started the session. If you run claude from a subdirectory, it walks up the tree but your file must be discoverable.

Instructions conflict between files — More specific scopes win. Project rules override user rules, and local rules override project rules. If you have conflicting instructions, the closest scope to the working directory takes precedence.

CLAUDE.md is too long and Claude seems to lose track — Keep the main CLAUDE.md concise (under 200 lines) with the most critical information. Move detailed guidelines into .claude/rules/ files. Claude loads rules files alongside the main memory but can manage more content when it is organized by topic.

Auto memory files getting stale — Use /memory to open and edit memory files. Delete outdated entries. Claude may also update memory automatically as patterns change.

What’s Next

With your project context established, learn how to turn product requirements into structured implementation plans.

PRD Workflow Turn requirements into plans and task lists

Deep Reasoning Use /think and extended thinking for complex problems