Initialize Your First Project

Master the art of project initialization with Claude Code. This guide covers creating effective CLAUDE.md files, managing project memory, configuring MCP servers, and establishing clear context for AI-assisted development.

Understanding Project Context

What Makes Claude Code Different

Unlike traditional coding tools, Claude Code maintains persistent memory across sessions through CLAUDE.md files. Think of these as your project’s DNA - they tell Claude everything it needs to know about your codebase, standards, and workflows.

Key benefits:

• Zero repetition - Document once, use forever
• Team consistency - Share knowledge across developers
• Context awareness - Claude understands your project deeply
• Evolving memory - Update as your project grows

The CLAUDE.md System

Memory Types and Hierarchy

Claude Code uses a sophisticated memory hierarchy that loads context based on your working directory:

Project Memory

Location: ./CLAUDE.md

Your team’s shared knowledge base. Check this into Git to ensure everyone works with the same context.

# Project: E-commerce Platform

## Architecture
- Next.js 15 with App Router
- Turso database with Drizzle ORM
- Stripe for payments
- Clerk for authentication

## Key Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run test suite
- `pnpm db:push` - Push schema changes

## Coding Standards
- Use TypeScript strict mode
- Prefer named exports
- Follow React Server Components patterns
- IMPORTANT: Never import client code in server components

User Memory

Location: ~/.claude/CLAUDE.md

Your personal preferences that apply across all projects.

# Personal Development Preferences

## Code Style
- Prefer early returns over nested if statements
- Use descriptive variable names (no single letters)
- Comment complex logic inline

## Workflow
- Always write tests for new features
- Commit frequently with conventional commits
- Review generated code line by line

Module Memory

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

Context-specific guidelines for different parts of your monorepo.

# Frontend Module

## Component Guidelines
- Use shadcn/ui components as base
- Follow Atomic Design principles
- Components must be accessible (WCAG 2.1 AA)

## State Management
- Server state: TanStack Query
- Client state: Zustand
- Form state: React Hook Form + Zod

Memory Lookup Process

1. Claude starts in your current working directory
2. Recursively searches up to (but not including) root /
3. Loads all CLAUDE.md and CLAUDE.local.md files found
4. Discovers nested CLAUDE.md files in subdirectories on demand
5. Merges all memories with proper precedence (local → project → user)

Tip

Claude automatically discovers CLAUDE.md files in subdirectories when you work with files in those directories. This means you don’t need to load everything upfront - Claude pulls in context as needed.

Quick Project Initialization

Using the /init Command

The fastest way to bootstrap your project context:

claude

> /init

This command analyzes your project and generates a comprehensive CLAUDE.md file. Here’s what it typically includes:

Generated CLAUDE.md

# Project Overview
Automatically detected project type and structure

## Technology Stack
- Language: TypeScript
- Framework: Next.js 15.0.3
- Database: PostgreSQL with Prisma
- Testing: Jest + React Testing Library

## Project Structure
- `/src` - Application source code
- `/src/components` - React components
- `/src/app` - Next.js app router pages
- `/src/lib` - Utility functions and shared code
- `/tests` - Test files

## Available Scripts
- `npm run dev` - Start development server on port 3000
- `npm run build` - Build for production
- `npm run test` - Run test suite
- `npm run lint` - Run ESLint

## Environment Variables
Required variables detected in .env.example:
- DATABASE_URL - PostgreSQL connection string
- NEXT_PUBLIC_API_URL - API endpoint

## Dependencies
Key packages:
- next: 15.0.3
- react: 19.0.0
- @prisma/client: 5.22.0
- tailwindcss: 3.4.1

## Git Workflow
- Main branch: main
- Feature branches: feature/*
- Commit style: Conventional Commits

## Additional Notes
- Using TypeScript strict mode
- Tailwind CSS for styling
- Server Components by default

Customizing Generated Memory

After running /init, refine the generated file:

1. Add team conventions not detected automatically
2. Document architectural decisions and their rationale
3. Include common gotchas specific to your project
4. Add frequently used commands with explanations
5. Specify coding patterns you want Claude to follow

Dynamic Memory Updates

Using the # Shortcut

The quickest way to add memory during development:

# Always use Radix UI for dropdowns, not native select elements

Claude will prompt you to choose where to save this memory:

Memory Location Prompt

Where should this memory be saved?
> 1. Project memory (./CLAUDE.md)
2. Frontend module (./frontend/CLAUDE.md)
3. User memory (~/.claude/CLAUDE.md)
4. Local project memory (./CLAUDE.local.md)

Tip

Use the # shortcut liberally as you discover project-specific patterns. It’s faster than manually editing CLAUDE.md files and helps build comprehensive documentation over time.

CLAUDE.md Imports

For complex projects, use imports to keep memories modular:

CLAUDE.md with imports

# Main Project Configuration

See @README.md for project overview
Review @docs/ARCHITECTURE.md for system design

## Module-Specific Guidelines
- Frontend: @frontend/STYLE_GUIDE.md
- Backend: @backend/API_CONVENTIONS.md
- Database: @docs/database/SCHEMA_DESIGN.md

## Personal Overrides
- @~/.claude/my-project-preferences.md

Imports support:

• Relative paths: @./docs/guide.md
• Absolute paths: @/home/user/standards.md
• Home directory: @~/documents/notes.md
• Recursive imports (max depth: 5)

Project Configuration

Essential Settings (.claude/settings.json)

Configure Claude’s behavior for your project:

.claude/settings.json

{
"model": "claude-opus-4",
"maxTurns": 30,
"allowedTools": [
  "Edit",
  "View",
  "Bash(git:*)",
  "Bash(npm:*)",
  "Bash(pnpm:*)",
  "WebFetch",
  "mcp__*"
],
"hooks": [
  {
    "matcher": "Edit",
    "hooks": [
      {
        "type": "command",
        "command": "pnpm prettier --write \"$CLAUDE_FILE_PATHS\""
      }
    ]
  }
],
"ignoredFiles": [
  "*.env*",
  "*.key",
  "*.pem",
  "node_modules/**",
  ".next/**",
  "dist/**"
]
}

MCP Server Configuration

Set up Model Context Protocol servers for enhanced capabilities:

Project Scope

Create .mcp.json in your project root (shareable via Git):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

Via CLI

Add MCP servers interactively:

# Add GitHub integration
claude mcp add github --transport stdio \
  npx -y @modelcontextprotocol/server-github \
  -e GITHUB_TOKEN=$GITHUB_TOKEN

# Add database access
claude mcp add postgres --transport stdio \
  npx -y @modelcontextprotocol/server-postgres \
  -e CONNECTION_STRING=$DATABASE_URL

# Add browser automation
claude mcp add puppeteer --transport stdio \
  npx -y @modelcontextprotocol/server-puppeteer

User Scope

For personal tools available across all projects:

# Add to user configuration
claude mcp add -s user context7 \
  --transport sse \
  https://context7.mcp.run

Caution

When team members first use a project with .mcp.json, Claude Code will prompt for approval. This security measure prevents malicious MCP configurations. Team members can reset approvals with claude mcp reset-project-choices.

Multi-Directory Workspaces

Setting Up Complex Projects

For monorepos or multi-service architectures:

1. Start Claude in the root directory

   cd ~/projects/my-monorepo
   claude

2. Add additional directories

   > /add-dir ../shared-lib
   > /add-dir ../design-system

3. Or use CLI flags

   claude --add-dir ../backend ../frontend ../shared

4. Make it permanent

   claude config add addDirs "../backend,../frontend"

Workspace Best Practices

Monorepo Organization

project-root/
├── CLAUDE.md              # Overall project context
├── .mcp.json             # Shared MCP servers
├── frontend/
│   ├── CLAUDE.md         # Frontend-specific rules
│   └── src/
├── backend/
│   ├── CLAUDE.md         # Backend patterns
│   └── src/
└── shared/
    ├── CLAUDE.md         # Shared library context
    └── src/

Run Claude from project-root/ with all subdirectories accessible.

Custom Commands

Creating Project-Specific Commands

Store reusable workflows as slash commands:

.claude/commands/new-feature.md

# Create a new feature following our architecture

Please create a new feature called: $ARGUMENTS

Follow these steps:
1. Create feature folder in src/features/$ARGUMENTS
2. Set up the standard structure:
 - index.ts (public exports)
 - types.ts (TypeScript interfaces)
 - $ARGUMENTS.tsx (main component)
 - $ARGUMENTS.test.tsx (tests)
 - $ARGUMENTS.stories.tsx (Storybook)
3. Add feature to the main exports
4. Create initial tests with 100% coverage
5. Add to feature flags configuration

Use our standard patterns:
- Container/Presenter pattern
- Custom hooks for logic
- Styled components for styling
- React Query for data fetching

Usage: /project:new-feature user-profile

Command Organization

.claude/commands/
├── new-feature.md        # /project:new-feature
├── api/
│   └── endpoint.md      # /project:api:endpoint
├── db/
│   ├── migration.md     # /project:db:migration
│   └── seed.md          # /project:db:seed
└── test/
    └── e2e.md           # /project:test:e2e

Real-World Example

Complete Project Setup

Here’s how a senior developer sets up a new Next.js project:

1. Initialize the project

   cd ~/projects/saas-app
   claude
   > /init

2. Refine the generated CLAUDE.md

   > Edit CLAUDE.md and add our team's specific conventions

3. Configure MCP servers

   > /mcp add github --transport sse https://github.com/api/mcp
   > /mcp add postgres --transport stdio npx @modelcontextprotocol/server-postgres

4. Set up project configuration

   > Create .claude/settings.json with our preferred tools and hooks

5. Add custom commands

   > Create .claude/commands/new-component.md for our component generator
   > Create .claude/commands/deploy.md for deployment workflow

6. Configure multi-directory access

   > /add-dir ../design-system
   > /add-dir ../shared-types

7. Test the setup

   > Create a new user authentication feature following our patterns

Memory Best Practices

Golden Rules for CLAUDE.md Files

1. Be specific over general - “Use Zod for validation” not “validate inputs”
2. Include examples - Show Claude exactly what you want
3. Document the why - Explain reasoning behind conventions
4. Update regularly - Use # to add learnings as you code
5. Review periodically - Clean up outdated information monthly
6. Test effectiveness - Ask Claude to explain your conventions back

Anti-Patterns to Avoid

❌ Too vague: “Write good code”
✅ Specific: “Use early returns, max 3 levels of nesting, extract complex conditions”

❌ No context: “Use our API style”
✅ With context: “Follow REST conventions: GET /api/users, POST /api/users, use kebab-case”

❌ Outdated info: “We use React 16 class components”
✅ Current: “React 19 with Server Components, use function components only”

Troubleshooting

Common Issues

Memory Not Loading

Symptom: Claude doesn’t seem aware of your CLAUDE.md content

Solutions:

1. Check file location - must be in project root or parent directories
2. Verify file name - exactly CLAUDE.md (case-sensitive on Linux/Mac)
3. Run /memory to see what’s loaded
4. Restart Claude Code after adding new memory files

MCP Connection Failed

Symptom: MCP servers show as disconnected

Solutions:

1. Run with debug flag: claude --mcp-debug
2. Check server URL/path is correct
3. Verify authentication tokens are set
4. Test server manually: npx @modelcontextprotocol/server-name
5. Check firewall/proxy settings

Conflicting Instructions

Symptom: Claude follows old patterns despite updates

Solutions:

1. Use /clear to reset conversation context
2. Add “IMPORTANT:” or “YOU MUST” for critical rules
3. Check precedence - local overrides project overrides user
4. Remove conflicting instructions from parent directories

Next Steps

Now that your project is initialized with rich context:

PRD Workflow Learn to create comprehensive requirements with Claude

MCP Setup Configure advanced MCP servers for your workflow

Development Workflow Master the PRD → Plan → Todo methodology

Remember: Great context leads to great code. Invest time in your CLAUDE.md files and watch your productivity soar!