Initialize Your First Project

Learn to set up Claude Code for maximum effectiveness in your project. This guide covers creating CLAUDE.md files, managing project memory, and establishing clear context for AI-assisted development.

Understanding CLAUDE.md Files

What is CLAUDE.md?

CLAUDE.md is a special file that Claude Code automatically loads into context. Think of it as persistent memory that helps Claude understand your project’s specific needs, coding standards, and common workflows.

Key Benefits:

• 🧠 Persistent context across sessions
• 👥 Shareable team knowledge
• 🔄 Automatically loaded on startup
• 📁 Hierarchical for complex projects

Quick Start

1. Navigate to your project

   cd your-awesome-project

2. Start Claude Code

   claude

3. Initialize CLAUDE.md

   /init

4. Review and customize Claude will analyze your project and generate a tailored CLAUDE.md file

CLAUDE.md File Structure

Basic Template

CLAUDE.md

# Project Overview
Brief description of what this project does and its main purpose.

# Architecture
- Frontend: React with TypeScript
- Backend: Node.js with Express
- Database: PostgreSQL
- State Management: Redux Toolkit

# Key Directories
- `src/`: Main source code
- `src/components/`: React components
- `src/api/`: API client code
- `src/utils/`: Utility functions
- `tests/`: Test files

# Common Commands
- `npm run dev`: Start development server
- `npm run build`: Build for production
- `npm test`: Run test suite
- `npm run lint`: Run linter
- `npm run type-check`: Check TypeScript types

# Code Style
- Use TypeScript for all new files
- Prefer functional components with hooks
- Use descriptive variable names
- Write tests for new features
- Follow existing patterns in the codebase

# Important Notes
- Environment variables are in `.env.example`
- Always run tests before committing
- Use feature branches for new work
- API documentation at `/docs/api.md`

# Current Sprint Goals
- [ ] Implement user authentication
- [ ] Add data validation to forms
- [ ] Improve error handling

Advanced Example

Complex CLAUDE.md Example

# E-Commerce Platform

## Project Context
Multi-tenant SaaS e-commerce platform supporting B2B and B2C operations.
Built with microservices architecture, deployed on AWS ECS.

## Tech Stack
### Frontend
- Next.js 14 with App Router
- TypeScript strict mode
- Tailwind CSS + shadcn/ui
- React Query for data fetching
- Zustand for state management

### Backend Services
- API Gateway: Kong
- User Service: Node.js + Express + TypeORM
- Product Service: Go + Gin + GORM
- Order Service: Python + FastAPI + SQLAlchemy
- Payment Service: Java + Spring Boot

### Infrastructure
- AWS ECS for container orchestration
- PostgreSQL (RDS) for relational data
- Redis for caching and sessions
- ElasticSearch for product search
- S3 for media storage

## Development Workflow

### Local Development
```bash
# Start all services
docker-compose up

# Start specific service
docker-compose up user-service

# Run migrations
npm run migrate:up

# Seed test data
npm run seed:dev
```

### Testing Strategy
- Unit tests: Jest for JS/TS, Go test, pytest
- Integration tests: Supertest + Docker
- E2E tests: Playwright
- Min coverage: 80% for new code

### Git Workflow
1. Create feature branch from develop
2. Name format: feature/JIRA-123-brief-description
3. Commit format: "type(scope): description"
4. Open PR against develop
5. Require 2 approvals + passing CI

## API Patterns

### REST Endpoints
- GET /api/v1/resources - List with pagination
- GET /api/v1/resources/:id - Single resource
- POST /api/v1/resources - Create new
- PUT /api/v1/resources/:id - Full update
- PATCH /api/v1/resources/:id - Partial update
- DELETE /api/v1/resources/:id - Soft delete

### Common Headers
- Authorization: Bearer {token}
- X-Tenant-ID: {tenantId}
- X-Request-ID: {uuid}

## Security Considerations
- All endpoints require authentication except /health
- Use parameterized queries to prevent SQL injection
- Validate all inputs with Joi/Zod schemas
- Rate limiting: 100 req/min per user
- CORS configured for specific domains only

## Performance Guidelines
- Database queries must use indexes
- Implement pagination for list endpoints
- Cache GET requests in Redis (5 min TTL)
- Lazy load images and components
- Bundle size budget: 200KB for initial load

## Known Issues
- Payment webhooks occasionally timeout - retry logic in place
- Search indexing has 2-3 minute delay
- Some legacy endpoints use camelCase instead of snake_case

## Monitoring & Debugging
- Logs: CloudWatch (search by X-Request-ID)
- APM: DataDog (user-service.datadog.dashboard)
- Errors: Sentry (filter by service + env)
- Local debugging: See /docs/debugging.md

Memory Hierarchy

Claude Code supports multiple memory locations for different scopes:

Project Memory

Location: ./CLAUDE.md

Team-shared instructions checked into version control:

• Architecture decisions
• Coding standards
• Build commands
• API patterns

# Edit during session
/memory

# Or add quick notes
# Always use async/await instead of callbacks

User Memory

Location: ~/.claude/CLAUDE.md

Personal preferences across all projects:

• Your coding style
• Preferred tools
• Personal shortcuts
• IDE settings

# My Preferences
- Use 2-space indentation
- Prefer const over let
- Always destructure imports
- Format on save

Module Memory

Location: ./frontend/CLAUDE.md, ./backend/CLAUDE.md

Module-specific context in subdirectories:

• Component patterns
• Service documentation
• Module dependencies
• Local commands

Dynamic Memory Updates

Using the # Key

The fastest way to add memories during coding:

1. Type # followed by your note

   # The UserService.authenticate method requires a valid JWT token

2. Choose memory location Claude prompts you to select where to save:

   • Project memory (./CLAUDE.md)
   • User memory (~/.claude/CLAUDE.md)

3. Continue working The memory is immediately available

Common # Key Uses

Quick Memory Patterns

# Build command is 'npm run build:prod' for production

# API keys are in Vault, not .env files

# Always run migrations before starting the app

# The calculateTax function has a known bug with decimals

# Prefer composition over inheritance in this codebase

# Contact @john for database schema changes

CLAUDE.md Imports

For large projects, organize memories with imports:

CLAUDE.md with imports

# Main Project Configuration

## Architecture Overview
High-level system design and principles...

## Import Specific Configurations
- Frontend: ./frontend/CLAUDE.md
- Backend: ./backend/CLAUDE.md
- Infrastructure: ./infra/CLAUDE.md
- Testing: ./tests/CLAUDE.md

Note

Claude Code 4.0+ automatically discovers and loads CLAUDE.md files in parent and child directories when relevant.

Project-Specific Examples

React/Next.js Project

# Next.js E-Commerce App

## Project Structure
- App Router (not Pages Router)
- Server Components by default
- Client Components only when needed
- API routes in /app/api

## State Management
- Server state: React Query + Server Components
- Client state: Zustand for global, useState for local
- Form state: React Hook Form + Zod

## Styling Approach
- Tailwind CSS for utilities
- CSS Modules for complex components
- Framer Motion for animations
- Responsive-first design

## Component Patterns
```tsx
// Prefer this pattern for components
export function ComponentName({ prop1, prop2 }: Props) {
// Hooks at the top
// Early returns for edge cases
// Main render
}
```

## Data Fetching
- Use Server Components for initial data
- React Query for client-side updates
- Loading.tsx for suspense boundaries
- Error.tsx for error boundaries

Python/Django Project

# Django REST API

## Project Standards
- Python 3.11+ with type hints
- Black for formatting (line length 88)
- isort for imports
- pytest for testing

## Django Patterns
- Class-based views for CRUD
- Function-based views for complex logic
- Serializers handle all validation
- Managers for complex queries

## Database Guidelines
- Always use migrations
- Never edit migrations after deployment
- Use select_related/prefetch_related
- Index foreign keys and filter fields

## API Conventions
- RESTful URLs (/api/v1/users/)
- camelCase for JSON (use djangorestframework-camel-case)
- Pagination on all list endpoints
- Standard error format

## Testing Requirements
- Unit test all business logic
- Integration test all endpoints
- Use factory_boy for test data
- Mock external services

DevOps/Infrastructure

# Infrastructure as Code

## Terraform Conventions
- Modules in /modules directory
- Environments in /environments
- State in S3 with DynamoDB lock
- Always run plan before apply

## Kubernetes Patterns
- One namespace per environment
- ConfigMaps for config
- Secrets for sensitive data
- HPA for autoscaling
- PDB for availability

## CI/CD Pipeline
1. Lint (terraform fmt -check)
2. Validate (terraform validate)
3. Security scan (tfsec)
4. Plan (save plan file)
5. Manual approval for prod
6. Apply

## Monitoring Setup
- Prometheus for metrics
- Grafana for visualization
- Alert on SLI breaches
- Runbooks in /docs/runbooks

Best Practices

CLAUDE.md Best Practices

1. Be Specific: “Use 2-space indentation” not “format nicely”
2. Include Examples: Show actual code patterns you want followed
3. Stay Current: Update as your project evolves
4. Document Gotchas: Known issues, workarounds, and edge cases
5. Link Resources: Reference documentation, wikis, and tools
6. Use Structure: Organize with clear headings and sections
7. Keep It Scannable: Use bullet points and code blocks
8. Version Control: Track changes to understand evolution

Optimizing for Large Codebases

Hierarchical Organization

project/
├── CLAUDE.md                 # Root context
├── frontend/
│   ├── CLAUDE.md            # Frontend-specific
│   └── components/
│       └── CLAUDE.md        # Component patterns
├── backend/
│   ├── CLAUDE.md            # Backend-specific
│   └── services/
│       └── CLAUDE.md        # Service patterns
└── infrastructure/
    └── CLAUDE.md            # DevOps context

Token Efficiency

Managing Context Size

CLAUDE.md files consume tokens from Claude’s context window. Keep them focused:

• Aim for 200-500 lines per file
• Use imports for modular organization
• Remove outdated information
• Focus on patterns, not exhaustive lists

Team Collaboration

Establishing Team Standards

1. Create initial CLAUDE.md together

   • Hold a team session to agree on contents
   • Document existing conventions
   • Clarify ambiguous patterns

2. Review in pull requests

   • Treat CLAUDE.md changes like code
   • Require team approval for updates
   • Keep history of why changes were made

3. Regular maintenance

   • Review quarterly
   • Remove outdated information
   • Add new patterns as they emerge

4. Onboarding tool

   • New developers read CLAUDE.md first
   • Use it during code reviews
   • Reference it in discussions

Troubleshooting

CLAUDE.md Not Loading

Symptoms: Claude doesn’t seem aware of your project context

Solutions:

1. Verify file name is exactly CLAUDE.md (case-sensitive)
2. Check file location (project root)
3. Restart Claude Code session
4. Run /memory to verify contents

Conflicting Instructions

Symptoms: Claude follows old patterns despite updates

Solutions:

1. Clear conversation with /clear
2. Check for multiple CLAUDE.md files
3. Verify import paths are correct
4. Use more specific language (“ALWAYS”, “NEVER”)

Token Limit Issues

Symptoms: Claude mentions context window limits

Solutions:

1. Split large CLAUDE.md into modules
2. Remove verbose sections
3. Use concise bullet points
4. Focus on patterns over examples

Next Steps

IDE Integration Connect Claude Code with VS Code, JetBrains, and other editors

Development Workflow Learn the optimal workflow from planning to implementation

Quick Reference

Command	Purpose
/init	Generate initial CLAUDE.md
/memory	Edit memory files
#	Add quick memory note
/clear	Clear conversation context
@CLAUDE.md	Reference memory in prompts

Remember: A well-crafted CLAUDE.md file is like having perfect documentation that never gets lost and is always available exactly when Claude needs it.