Starting New Projects with Claude Code

Starting New Projects with Claude Code

Starting a new project traditionally involves hours of boilerplate setup: creating directory structures, configuring build tools, setting up linting, initializing git, writing initial documentation, and establishing project conventions. Claude Code transforms this multi-hour process into a guided conversation that produces a production-ready project foundation in minutes.

The Challenge: From Blank Directory to Working Project

Every developer knows the friction of starting fresh. You have an idea or requirement, but between that vision and writing actual feature code lies a maze of setup tasks. Should you use TypeScript or JavaScript? How should you structure directories? What testing framework fits best? What about linting, formatting, deployment configuration?

Claude Code doesn’t just generate boilerplate—it acts as an experienced architect who understands your requirements and makes informed decisions about project structure, tooling, and conventions.

Prerequisites

Before starting, ensure you have:

• Claude Code installed (npm install -g @anthropic-ai/claude-code)
• A blank directory or repository where you want to create your project
• Node.js 18+ installed (for JavaScript/TypeScript projects)
• Any language-specific tools installed (Python, Elixir, PHP, etc.)

Workflow: From PRD to Running Project

1. Create your project directory and navigate to it

   mkdir my-awesome-project
   cd my-awesome-project
   claude

2. Initialize with project context

   > /init

   This creates an initial CLAUDE.md file. Claude will analyze any existing files and generate appropriate context documentation.

3. Describe your project vision

   > I need to build a task management API with the following requirements:
   > - RESTful API with user authentication
   > - PostgreSQL database
   > - Email notifications for task assignments
   > - Admin dashboard for monitoring
   > - Should be built with Node.js and TypeScript
   > - Need Docker support for deployment

4. Let Claude create a comprehensive plan

   > Based on these requirements, think hard about the best architecture
   > and create a detailed implementation plan. Include technology choices,
   > directory structure, and key implementation steps.

5. Review and refine the plan Claude will present a detailed plan. Review it and ask for adjustments:

   > Let's use Fastify instead of Express for better performance.
   > Also, add Redis for caching and session management.

6. Execute the project setup

   > Great plan! Now let's implement the project structure and initial setup.
   > Start with creating all directories, configuration files, and package.json.

7. Set up development environment

   > Set up the development environment including:
   > - TypeScript configuration
   > - ESLint and Prettier
   > - Git hooks with Husky
   > - Initial Docker configuration
   > - Environment variable structure

8. Create initial implementation

   > Now implement the basic server setup with:
   > - Health check endpoint
   > - Basic error handling
   > - Database connection
   > - Logging setup

9. Add testing foundation

   > Set up the testing framework with:
   > - Jest configuration for TypeScript
   > - Example unit and integration tests
   > - Test database configuration
   > - GitHub Actions for CI

10. Document and commit

    > Create a comprehensive README with:
    > - Project overview
    > - Setup instructions
    > - API documentation structure
    > - Development workflow
    > Then create an initial git commit with a descriptive message

Real-World Examples

Example 1: Next.js SaaS Starter

Prompt

> I need a Next.js SaaS starter with:
> - Authentication (NextAuth with Google/GitHub)
> - Stripe integration for subscriptions
> - PostgreSQL with Prisma ORM
> - Tailwind CSS with shadcn/ui components
> - Email sending with Resend
> - Landing page, dashboard, and settings pages
> Think through the architecture and implement it step by step

Claude's Plan

## SaaS Starter Architecture Plan

### Technology Stack
- **Frontend**: Next.js 14 (App Router), React 18, TypeScript
- **Styling**: Tailwind CSS, shadcn/ui components
- **Auth**: NextAuth.js with Google/GitHub providers
- **Database**: PostgreSQL with Prisma ORM
- **Payments**: Stripe (subscriptions, webhooks)
- **Email**: Resend for transactional emails
- **Deployment**: Vercel-ready configuration

### Directory Structure

├── app/ │ ├── (auth)/ │ │ ├── login/ │ │ └── register/ │ ├── (dashboard)/ │ │ ├── dashboard/ │ │ ├── settings/ │ │ └── billing/ │ ├── (marketing)/ │ │ ├── page.tsx │ │ ├── pricing/ │ │ └── about/ │ ├── api/ │ │ ├── auth/ │ │ ├── stripe/ │ │ └── trpc/ │ └── layout.tsx ├── components/ │ ├── ui/ # shadcn/ui components │ ├── dashboard/ │ └── marketing/ ├── lib/ │ ├── auth.ts │ ├── stripe.ts │ ├── email.ts │ └── db.ts ├── prisma/ │ └── schema.prisma └── …configuration files

### Implementation Steps
1. Initialize Next.js with TypeScript
2. Set up Tailwind and shadcn/ui
3. Configure Prisma and database schema
4. Implement NextAuth with providers
5. Create Stripe integration
6. Build page layouts and components
7. Add email functionality
8. Set up environment variables
9. Create development scripts
10. Add documentation

Example 2: Python FastAPI Microservice

Prompt

> Create a Python FastAPI microservice for image processing:
> - Accept image uploads
> - Resize images to multiple sizes
> - Store in S3-compatible storage
> - PostgreSQL for metadata
> - Redis for job queue
> - Docker-ready with proper structure
> Use modern Python with type hints and async throughout

Implementation

# Claude creates main.py
from fastapi import FastAPI, UploadFile, BackgroundTasks
from fastapi.responses import JSONResponse
import asyncio
from contextlib import asynccontextmanager

from app.config import settings
from app.database import init_db
from app.redis import init_redis
from app.routers import images, health

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    await init_db()
    await init_redis()
    yield
    # Shutdown
    # Cleanup connections

app = FastAPI(
    title="Image Processing Service",
    version="1.0.0",
    lifespan=lifespan
)

app.include_router(health.router, tags=["health"])
app.include_router(images.router, prefix="/api/v1", tags=["images"])

# Claude also creates:
# - Dockerfile with multi-stage build
# - docker-compose.yml for local development
# - Full project structure with proper separation
# - Async S3 client implementation
# - Redis job queue with retries
# - Comprehensive error handling

Example 3: Elixir Phoenix API

Prompt

> Build an Elixir Phoenix API for a real-time analytics platform:
> - GraphQL API with Absinthe
> - Real-time subscriptions
> - TimescaleDB for time-series data
> - Authentication with Guardian
> - Rate limiting per API key
> - Prometheus metrics
> Follow OTP best practices and use contexts properly

Key Files Created

lib/analytics_web/schema.ex

defmodule AnalyticsWeb.Schema do
  use Absinthe.Schema
  import_types AnalyticsWeb.Schema.MetricTypes

  query do
    field :metrics, list_of(:metric) do
      arg :start_time, non_null(:datetime)
      arg :end_time, non_null(:datetime)
      arg :aggregation, :aggregation_type

      middleware AnalyticsWeb.Middleware.Authenticate
      middleware AnalyticsWeb.Middleware.RateLimit
      resolve &Resolvers.Metric.list_metrics/3
    end
  end

  subscription do
    field :metric_updates, :metric do
      arg :metric_names, list_of(:string)

      config fn args, %{context: context} ->
        {:ok, topic: "metrics:#{context.current_user.id}"}
      end
    end
  end
end

# Plus full context modules, GenServers for real-time processing,
# Prometheus integration, and comprehensive test suite

Advanced Patterns

Pattern 1: Monorepo Setup

> I need a monorepo setup for our full-stack application:
> - Frontend: Next.js app
> - Backend: Node.js API
> - Shared: TypeScript types and utilities
> - Mobile: React Native app
> - Use pnpm workspaces
> - Set up build orchestration
> Think about the structure and implement it

Claude will create a sophisticated monorepo structure with:

• Workspace configuration
• Shared TypeScript configurations
• Cross-package dependencies
• Unified testing setup
• CI/CD pipeline configuration

Pattern 2: Microservices Architecture

> Design a microservices architecture for an e-commerce platform:
> - API Gateway (Kong or custom)
> - User Service (authentication)
> - Product Service (catalog)
> - Order Service (transactions)
> - Notification Service (email/SMS)
> - Use Docker Compose for local development
> - Include service discovery and health checks

Claude designs inter-service communication, shared libraries, and orchestration.

Pattern 3: CLI Tool Development

> Create a CLI tool for database migrations:
> - Support multiple database types
> - Version control for migrations
> - Rollback capability
> - TypeScript with Commander.js
> - Distribute via npm
> - Include man pages and shell completions

Best Practices

Start with Clear Requirements

The more specific your initial requirements, the better Claude’s initial plan. Include technical constraints, performance requirements, and deployment targets.

Iterate on the Plan

Don’t accept the first plan blindly. Ask Claude to explain trade-offs, suggest alternatives, or dive deeper into specific architectural decisions.

Leverage Claude's Knowledge

Claude knows about latest best practices, security considerations, and common pitfalls. Ask it to review its own suggestions for potential issues.

Customize CLAUDE.md Early

As soon as the project structure exists, customize the CLAUDE.md file with project-specific conventions, making future development smoother.

Common Pitfalls to Avoid

Uwaga

Over-engineering Alert: Claude might suggest overly complex architectures for simple projects. Always question whether suggested complexity is necessary for your use case.

• Skipping the planning phase: Jumping straight to implementation often leads to refactoring later
• Not customizing generated code: Claude’s output is a starting point—adapt it to your specific needs
• Ignoring documentation: The initial setup is the best time to establish good documentation practices
• Forgetting environment setup: Ensure all team members can run the project with minimal friction

Accelerating Future Projects

Create Project Templates

Once you have a successful project setup, create a custom slash command:

.claude/commands/create-api.md

Create a new TypeScript API project with our standard setup:
- Fastify with TypeScript
- Our standard folder structure
- PostgreSQL with our migration setup
- Our ESLint and Prettier configs
- Standard GitHub Actions
- Our logging and monitoring setup

Project name: $ARGUMENTS

Build Your Snippets Library

Create a collection of project-specific patterns:

> # remember our standard error handling middleware:
> - Global error handler with proper logging
> - Structured error responses
> - Correlation ID tracking
> - Sentry integration for production

Measuring Success

A well-initialized project should have:

• ✅ Clear directory structure following language conventions
• ✅ All necessary configuration files
• ✅ Development environment that starts with a single command
• ✅ Test setup with at least one passing test
• ✅ Linting and formatting configured and passing
• ✅ Git repository with meaningful initial commit
• ✅ README with clear setup instructions
• ✅ CLAUDE.md with project-specific context
• ✅ Basic CI/CD pipeline configuration

Next Steps

Understanding Large Codebases Learn how to navigate and understand existing codebases with Claude Code

Feature Planning with Deep Reasoning Master Claude's planning capabilities for complex features

Summary

Starting new projects with Claude Code fundamentally changes the development experience. Instead of spending hours on setup, you engage in a high-level architectural discussion with an AI that translates your requirements into a working project foundation. The key is to think of Claude not as a code generator, but as an experienced developer who can help you make informed decisions and implement them consistently.

Remember: the goal isn’t to have Claude do everything automatically, but to collaborate on creating a solid foundation that accelerates your actual feature development. Every minute saved on boilerplate is a minute you can spend on what makes your project unique.