Starting New Projects from the Terminal

You just got the green light on a new project. You know the stack you want — maybe Next.js with Prisma, maybe a Python FastAPI service, maybe a Phoenix LiveView app. In the past, you would spend the first day wiring up boilerplate: project structure, linter config, database connections, environment variables, CI pipeline. That is an entire day of work before you write a single line of business logic.

Claude Code compresses that into a single terminal session. You describe what you want, and Claude scaffolds the project, configures the tooling, and sets up a CLAUDE.md that makes every future session more productive. The key is knowing how to guide that first conversation so you get production-quality scaffolding instead of a generic template.

What You’ll Walk Away With

A repeatable process for bootstrapping any project type from the CLI
A well-structured CLAUDE.md file that acts as persistent project memory
Copy-paste prompts for common stacks (Next.js, FastAPI, Phoenix, Express)
The /init workflow that analyzes existing projects and generates context automatically

The Bootstrap Workflow

The most effective project initialization follows a three-phase pattern: describe the project, let Claude scaffold it, then lock in the conventions with CLAUDE.md.

Create the project directory and start Claude Code
Terminal window
```
mkdir my-saas-app && cd my-saas-app
git init
claude
```
Starting with git init matters. Claude Code is git-aware and will create commits at logical checkpoints throughout the scaffolding process. Without a git repository, you lose the ability to rewind if something goes wrong during setup.

Describe the project with enough specificity to avoid generic output

A vague prompt like “create a web app” gets you a generic template. A specific prompt gets you something you can actually build on. Include the stack, the primary features, and your conventions.

Copy-paste prompt for full-stack project scaffolding:

Bootstrap a Next.js 15 app with the App Router, TypeScript strict mode,
Tailwind CSS, and Prisma with PostgreSQL. Set up:

- src/app directory structure with a landing page and auth routes
- Prisma schema with User and Session models
- Environment variables in .env.example (never .env)
- ESLint with the next/core-web-vitals config
- A docker-compose.yml for local PostgreSQL
- Basic middleware for auth route protection

Use server components by default. Client components only where needed.
No barrel exports. Prefer named exports over default exports.

Review the generated structure before moving on

Claude will create files and make commits. Before proceeding, ask it to verify the setup actually works.
```
Run the dev server and confirm it starts without errors.
Then run the linter and fix any issues. Show me the final
project structure as a tree.
```
Generate the CLAUDE.md file

This is the step most people skip, and it is the most important one. CLAUDE.md gives every future Claude session the context it needs to work effectively in your project.
```
/init
```
The /init command analyzes your project structure, detects frameworks and tooling, and generates a starter CLAUDE.md. Review it and add anything project-specific that Claude cannot infer from the code alone.

Writing a CLAUDE.md That Actually Works

The /init command gives you a solid starting point, but the best CLAUDE.md files are refined over time. Here is what to include and what to leave out.

What belongs in CLAUDE.md

# Build and test commands
npm run dev              # Start dev server on port 3000
npm run build            # Production build
npm run test             # Run vitest
npm run lint             # ESLint check
npm run db:migrate       # Run Prisma migrations
npm run db:seed          # Seed development data

# Code conventions
- Use server components by default, client components only for interactivity
- Named exports only, no default exports except page.tsx and layout.tsx
- Colocate tests next to source files: Button.tsx / Button.test.tsx
- Use Zod for all runtime validation, never trust client input

# Architecture decisions
- Auth: NextAuth.js with database sessions (not JWT)
- State: Server state via React Server Components, client state via Zustand only where needed
- API: Server Actions for mutations, Route Handlers only for webhooks

# Common gotchas
- Prisma client must be instantiated as singleton (see src/lib/db.ts)
- Middleware runs on Edge Runtime -- no Node.js APIs available
- IMPORTANT: Never commit .env files. Use .env.example for templates.

What does not belong in CLAUDE.md

Do not include things Claude can figure out by reading your code: standard TypeScript conventions, how React hooks work, or what npm install does. Do not include documentation that changes frequently — link to it instead. If your CLAUDE.md is longer than about 50 lines, Claude starts losing track of individual rules. Keep it tight.

Stack-Specific Prompts

Python FastAPI

Copy-paste prompt for FastAPI project:

Create a FastAPI project with Python 3.12 and these conventions:

- src/ layout with separate routers, models, schemas, and services directories
- SQLAlchemy 2.0 with async sessions and Alembic migrations
- Pydantic v2 for request/response schemas
- Poetry for dependency management with a pyproject.toml
- pytest with async fixtures and httpx for API tests
- A Dockerfile with multi-stage build (builder + runtime)
- Pre-commit hooks for ruff formatting and type checking with mypy

Start with a health check endpoint and a basic CRUD resource for "projects"
with GET list, GET detail, POST create, and PATCH update.

Phoenix LiveView

Copy-paste prompt for Phoenix project:

Initialize a Phoenix 1.7 project with LiveView, Tailwind CSS, and
PostgreSQL. Set up:

- mix phx.new with --live flag
- Ecto schemas for User and Organization with a many-to-many relationship
- LiveView for a dashboard page with real-time updates
- ExUnit tests for the context modules
- A .formatter.exs configured for the project
- Docker Compose for PostgreSQL

Use contexts for business logic (Accounts context for User/Org).
Keep LiveView modules thin -- delegate to contexts for data operations.

Express with TypeScript

Copy-paste prompt for Express API project:

Scaffold a Node.js Express API with TypeScript strict mode:

- src/ with routes/, middleware/, services/, and lib/ directories
- Drizzle ORM with PostgreSQL and a migrations folder
- Zod for request validation middleware
- pino for structured JSON logging
- Vitest for tests with a test database configuration
- Dockerfile with multi-stage build and non-root user
- GitHub Actions CI that runs lint, type-check, and tests

Include a health check route and a complete CRUD for a "users" resource
with proper error handling middleware. Use async/await everywhere,
no callbacks.

Initializing Existing Projects

Not every project starts from scratch. When you join an existing codebase, Claude Code’s /init command becomes your onboarding tool.

Navigate to the project root and run Claude Code
Terminal window
```
cd /path/to/existing-project
claude
```
Generate CLAUDE.md from the existing codebase
```
/init
```
Claude reads your package.json (or equivalent), examines your directory structure, detects test frameworks, and generates a CLAUDE.md tailored to the project.

Ask Claude to fill in what /init missed

Read through the README, the CI configuration, and the last 20 commits.
Update CLAUDE.md with any conventions, gotchas, or workflow patterns
you can identify that aren't already captured.

Validate by asking a question only a well-configured session could answer
```
How do I run just the unit tests for the auth module?
What is the deployment process?
```
If Claude answers correctly from CLAUDE.md without reading additional files, your configuration is working.

Setting Up Hooks for Consistency

Hooks are scripts that run automatically at specific points in Claude’s workflow. Unlike CLAUDE.md instructions (which are advisory), hooks execute deterministically every time.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $FILE_PATH"
      }
    ]
  }
}

This hook runs ESLint with auto-fix after every file edit Claude makes. No more reviewing code and finding style issues that should have been caught automatically.

Copy-paste prompt for setting up project hooks:

Create hooks in .claude/settings.json that:
1. Run ESLint --fix after every file edit (PostToolUse on Edit/Write)
2. Run TypeScript type-check after editing .ts or .tsx files
3. Block writes to the migrations/ directory (PreToolUse on Write)
   with a message saying "Use the migration generator instead"

Creating Custom Skills for Your Team

Once your project is set up, you can encode team-specific workflows as skills that anyone can invoke.

---
name: new-feature
description: Scaffold a new feature with all required files
---
Create a new feature: $ARGUMENTS

1. Create a new branch named feature/$ARGUMENTS
2. Add route handler in src/app/api/$ARGUMENTS/route.ts
3. Add service in src/services/$ARGUMENTS.service.ts
4. Add Zod schemas in src/schemas/$ARGUMENTS.schema.ts
5. Add tests in src/services/$ARGUMENTS.service.test.ts
6. Update CLAUDE.md if new conventions are introduced

Invoke it with /new-feature user-preferences and Claude scaffolds the entire feature structure following your team’s conventions.

When This Breaks

Claude generates a generic template instead of what you described. Your prompt was too vague. Add specific framework versions, directory structure preferences, and conventions. The more specific your first prompt, the less course-correcting you do later.

The generated project has dependency conflicts. Claude sometimes pulls in incompatible package versions. Always include “run the dev server and fix any errors” as part of your scaffolding prompt. Claude is excellent at resolving dependency issues when it can see the actual error output.

CLAUDE.md gets ignored in later sessions. If the file exceeds roughly 50 lines or contains vague instructions like “write clean code,” Claude stops paying attention to individual rules. Keep every line specific and actionable. If removing a line would not change Claude’s behavior, remove it.

/init misses project conventions. The command analyzes code structure but cannot read your team’s unwritten rules. Always supplement /init output with the conventions that exist only in your team’s heads: branch naming, PR process, deployment procedures.

What’s Next

Your project is scaffolded, your CLAUDE.md is configured, and your hooks are in place. Now it is time to learn how Claude Code navigates code you did not write.

Codebase Analysis Use Claude Code to understand large, unfamiliar codebases through systematic exploration

Feature Planning Turn requirements into detailed implementation plans using Plan Mode and extended thinking