Project Initialization

Set up new projects with Claude Code from day one

Starting a project with proper Claude Code integration from the beginning sets the foundation for productive development. This guide covers initialization patterns for different project types.

🎯 Initialization Philosophy

Security First: Configure safe permissions from the start
Quality Gates: Establish automated quality checks early
Team Consistency: Use patterns that scale across team members
Documentation Driven: Make context explicit and comprehensive
Iterative Improvement: Plan for evolving requirements

🚀 Quick Start Templates

Web Application (Next.js/React)

# Initialize project
npx create-next-app@latest my-app --typescript --tailwind --eslint --app
cd my-app

# Initialize Claude Code
claude init

# Download production-ready CLAUDE.md
curl -o CLAUDE.md https://raw.githubusercontent.com/your-username/claude-code-playbook/main/templates/claude-md-templates/web-app.md

# Set up security configuration
curl -o .claude/settings.json https://raw.githubusercontent.com/your-username/claude-code-playbook/main/templates/security/web-app-settings.json

# Initialize git with proper ignores
echo "node_modules/" > .gitignore
echo ".env*" >> .gitignore
echo ".claude/logs/" >> .gitignore

# Create .claudeignore
echo ".env*" > .claudeignore
echo "node_modules/" >> .claudeignore
echo "secrets/" >> .claudeignore

# Start first Claude session
claude

API Service (Node.js/Express)

# Initialize project structure
mkdir my-api && cd my-api
npm init -y
npm install express cors helmet morgan
npm install -D @types/node @types/express typescript ts-node nodemon

# Initialize Claude Code
claude init

# Set up TypeScript
npx tsc --init

# Download API-specific CLAUDE.md
curl -o CLAUDE.md https://raw.githubusercontent.com/your-username/claude-code-playbook/main/templates/claude-md-templates/api-service.md

# Create project structure
mkdir -p src/{routes,middleware,models,utils,tests}
mkdir -p docs logs

# Start Claude session to build initial structure
claude

Python Package

# Create project structure
mkdir my-package && cd my-package

# Initialize with modern Python tooling
poetry init
poetry add fastapi uvicorn
poetry add -D pytest black isort mypy

# Initialize Claude Code
claude init

# Download Python-specific CLAUDE.md  
curl -o CLAUDE.md https://raw.githubusercontent.com/your-username/claude-code-playbook/main/templates/claude-md-templates/python-package.md

# Create package structure
mkdir -p src/my_package tests docs
touch src/my_package/__init__.py
touch src/my_package/main.py
touch tests/__init__.py

# Start development
claude

📋 Initialization Checklist

Essential Setup

## Project Initialization Checklist

### Security & Permissions
- [ ] .claude/settings.json configured with safe permissions
- [ ] .claudeignore created with sensitive file patterns
- [ ] Environment variables properly configured
- [ ] Git hooks set up for security scanning

### Quality Assurance
- [ ] Linting and formatting tools configured
- [ ] Testing framework initialized
- [ ] Pre-commit hooks installed
- [ ] CI/CD pipeline template created

### Documentation
- [ ] CLAUDE.md file customized for project
- [ ] README.md with setup and usage instructions
- [ ] Contributing guidelines established
- [ ] Architecture decisions documented

### Development Environment
- [ ] Package manager lock files committed
- [ ] Environment configuration templates created
- [ ] Development scripts defined
- [ ] Debug configuration set up

🛠 Project-Specific Initialization

Microservices Architecture

#!/bin/bash
# microservices-init.sh

project_name=$1
services=("auth" "api" "gateway" "worker")

echo "Initializing microservices project: $project_name"

# Create root structure
mkdir -p $project_name/{services,shared,docs,scripts}
cd $project_name

# Initialize root Claude configuration
claude init
curl -o CLAUDE.md https://raw.githubusercontent.com/your-username/claude-code-playbook/main/templates/claude-md-templates/microservices.md

# Create each service
for service in "${services[@]}"; do
  echo "Creating service: $service"
  mkdir -p services/$service/{src,tests,docs}
  
  # Service-specific CLAUDE.md
  cp CLAUDE.md services/$service/CLAUDE.md
  echo "## Service-Specific Context" >> services/$service/CLAUDE.md
  echo "This is the $service service, responsible for..." >> services/$service/CLAUDE.md
done

# Create shared libraries
mkdir -p shared/{types,utils,config}

# Docker setup
cat > docker-compose.yml << EOF
version: '3.8'
services:
$(for service in "${services[@]}"; do
  echo "  $service:"
  echo "    build: ./services/$service"
  echo "    ports:"
  echo "      - \"300${#services}:3000\""
  echo ""
done)
EOF

echo "Microservices project initialized. Run 'claude' to start development."

Mobile App (React Native)

# Initialize React Native project
npx react-native init MyApp --template react-native-template-typescript
cd MyApp

# Initialize Claude Code
claude init

# Download mobile-specific CLAUDE.md
curl -o CLAUDE.md https://raw.githubusercontent.com/your-username/claude-code-playbook/main/templates/claude-md-templates/mobile-app.md

# Set up mobile-specific tooling
npm install -D @react-native-community/eslint-config prettier
npm install react-navigation react-native-screens react-native-safe-area-context

# Configure for both platforms
npx pod-install ios  # iOS setup

Full-Stack Application

#!/bin/bash
# fullstack-init.sh

app_name=$1
echo "Initializing full-stack application: $app_name"

# Create project structure
mkdir -p $app_name/{frontend,backend,shared,docs}
cd $app_name

# Initialize root Claude configuration
claude init
curl -o CLAUDE.md https://raw.githubusercontent.com/your-username/claude-code-playbook/main/templates/claude-md-templates/fullstack.md

# Frontend setup (Next.js)
cd frontend
npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir
cd ..

# Backend setup (Express + TypeScript)
cd backend
npm init -y
npm install express cors helmet morgan
npm install -D @types/node @types/express typescript ts-node nodemon
npx tsc --init
mkdir -p src/{routes,middleware,models,utils}
cd ..

# Shared utilities
cd shared
npm init -y
npm install -D typescript
mkdir -p src/{types,utils,constants}
cd ..

# Development tools
npm init -y  # Root package.json for scripts
npm install -D concurrently

# Add development scripts
cat >> package.json << EOF
{
  "scripts": {
    "dev": "concurrently \"npm run dev:backend\" \"npm run dev:frontend\"",
    "dev:frontend": "cd frontend && npm run dev",
    "dev:backend": "cd backend && npm run dev",
    "build": "npm run build:frontend && npm run build:backend",
    "build:frontend": "cd frontend && npm run build",
    "build:backend": "cd backend && npm run build"
  }
}
EOF

echo "Full-stack project initialized. Run 'npm run dev' to start development."

📚 Template Customization

CLAUDE.md Customization Process

After downloading a CLAUDE.md template:

1. **Update Project Information**:
   - Replace placeholder names with actual project name
   - Update technology stack versions
   - Customize build and test commands

2. **Add Project-Specific Context**:
   - Business domain information
   - Specific architectural decisions
   - Integration requirements
   - Performance targets

3. **Configure Security Requirements**:
   - Authentication/authorization patterns
   - Data protection requirements
   - Compliance needs
   - Security testing approaches

4. **Establish Quality Standards**:
   - Code coverage targets
   - Performance benchmarks
   - Documentation requirements
   - Review processes

Configuration Templates

// .claude/settings.json template for different project types

// Web Application
{
  "allowedCommands": [
    "Edit", "Create",
    "Bash(npm run *)",
    "Bash(git status)",
    "Bash(git diff)"
  ],
  "deniedPaths": [
    ".env*", "secrets/**", "node_modules/**"
  ],
  "hooks": {
    "PreToolUse": {
      "command": "npm run lint",
      "matcher": "Edit|Create",
      "timeout": 20000
    }
  }
}

// API Service  
{
  "allowedCommands": [
    "Edit", "Create",
    "Bash(npm run *)",
    "Bash(docker-compose *)",
    "Bash(curl -X *)"
  ],
  "deniedPaths": [
    ".env*", "secrets/**", "ssl/**", "keys/**"
  ],
  "hooks": {
    "PreToolUse": {
      "command": "npm run test && npm run security-check",
      "matcher": "Edit",
      "filePattern": "**/api/**/*.ts"
    }
  }
}

🎯 First Session Goals

Initial Development Session

Welcome to the project! Let's establish our development foundation.

I've initialized a [project type] project with:
- Technology stack: [list key technologies]
- Purpose: [brief description]
- Team size: [team context]

Let's start by:
1. Reviewing and customizing our CLAUDE.md file
2. Setting up our first feature using TDD
3. Establishing code quality practices
4. Creating our development workflow

Are you ready to begin?

Progressive Enhancement Plan

## First Week Development Plan

Day 1: Foundation
- [ ] Complete project initialization
- [ ] Set up development environment
- [ ] Create first simple feature with tests
- [ ] Establish git workflow

Day 2-3: Core Features
- [ ] Implement authentication system
- [ ] Set up database integration
- [ ] Create API endpoints
- [ ] Add comprehensive testing

Day 4-5: Quality & Polish
- [ ] Performance optimization
- [ ] Security hardening
- [ ] Documentation completion
- [ ] Deployment preparation

Week 2+: Feature Development
- [ ] Iterative feature development
- [ ] Continuous improvement
- [ ] Team scaling preparation

🔧 Advanced Initialization

Team Setup Script

#!/bin/bash
# team-setup.sh - Onboard new team members

team_member_name=$1
project_name=$2

echo "Setting up $team_member_name for $project_name"

# Clone and set up project
git clone <project-repo> $project_name-$team_member_name
cd $project_name-$team_member_name

# Install dependencies
npm install

# Set up Claude Code
claude init

# Copy team configuration
cp .claude/settings.json.template .claude/settings.json

# Set up development environment
cp .env.example .env
echo "Please update .env with your local configuration"

# Install git hooks
npm run prepare

# Run initial tests
npm test

echo "Setup complete! Run 'claude' to start your first session."
echo "Remember to:"
echo "1. Update .env with your configuration"
echo "2. Read CLAUDE.md for project context"
echo "3. Review recent commits to understand current state"

Environment-Specific Initialization

#!/bin/bash
# env-init.sh - Set up for different environments

environment=$1  # development, staging, production

case $environment in
  "development")
    echo "Setting up development environment"
    npm install  # Include dev dependencies
    cp .env.development .env
    ;;
  "staging")
    echo "Setting up staging environment"
    npm ci  # Only production dependencies
    cp .env.staging .env
    ;;
  "production")
    echo "Setting up production environment"
    npm ci --only=production
    cp .env.production .env
    ;;
esac

# Environment-specific Claude configuration
cp .claude/settings.$environment.json .claude/settings.json

📊 Success Metrics

Initialization Effectiveness

Track these metrics to improve your initialization process:

Time to First Commit: How quickly can someone start contributing?
Setup Success Rate: Percentage of successful first-time setups
Context Comprehension: How well do new team members understand the project?
Quality Consistency: Are quality standards maintained from day one?

Remember: Great projects start with great foundations. Investing time in proper initialization pays dividends throughout the project lifecycle. Use Claude Code to establish patterns early that will scale with your project and team.

FilesExpand file tree

project-initialization.md

Latest commit

History

project-initialization.md

File metadata and controls

Project Initialization

Project Initialization

🎯 Initialization Philosophy

🚀 Quick Start Templates

Web Application (Next.js/React)

API Service (Node.js/Express)

Python Package

📋 Initialization Checklist

Essential Setup

🛠 Project-Specific Initialization

Microservices Architecture

Mobile App (React Native)

Full-Stack Application

📚 Template Customization

CLAUDE.md Customization Process

Configuration Templates

🎯 First Session Goals

Initial Development Session

Progressive Enhancement Plan

🔧 Advanced Initialization

Team Setup Script

Environment-Specific Initialization

📊 Success Metrics

Initialization Effectiveness