How to set up Claude Code for a new project (step by step)

You installed Claude Code. You opened your terminal. You typed a prompt. Claude gave you a generic response that ignored your project structure, your conventions, and your tech stack. Now you are wondering if you wasted your money.

You did not. You skipped setup. Claude Code is powerful, but it starts every session with zero context about your project. The difference between "this tool is useless" and "this tool is incredible" comes down to the first 10 minutes of configuration.

Here is the exact setup sequence, from installation to a productive first session.

Step 1: Install Claude Code

Claude Code requires Node.js 18 or later and a terminal. It works on macOS, Linux, and Windows (via WSL).

npm install -g @anthropic-ai/claude-code

Run claude in your terminal to verify the installation. On first launch it will ask you to authenticate with your Anthropic account. You need at least a Pro subscription ($20/month) to use Claude Code.

Step 2: Navigate to your project

Claude Code is project-aware. It reads files relative to where you run it. Always start Claude Code from your project root.

cd ~/projects/my-app
claude

If you start Claude Code from your home directory, it will see everything. That means slower context loading, irrelevant file suggestions, and higher token costs. Always be in the right directory.

Step 3: Create your CLAUDE.md file

This is the step that separates good Claude Code experiences from frustrating ones. CLAUDE.md is a file in your project root that Claude reads at the start of every session. It tells Claude who you are, what the project is, and what rules to follow.

Here is a minimal template that works for most projects:

# Project: [Your Project Name]

## Tech Stack
- Language: [e.g., TypeScript]
- Framework: [e.g., Next.js 14]
- Database: [e.g., PostgreSQL via Prisma]
- Hosting: [e.g., Vercel]

## Project Structure
- `src/app/` — Page routes and layouts
- `src/components/` — Reusable UI components
- `src/lib/` — Utility functions and database client
- `src/api/` — API route handlers

## Conventions
- Use functional components with TypeScript
- All database queries go through Prisma client in `src/lib/db.ts`
- Environment variables are in `.env.local` (never commit)
- Tests use Vitest, run with `npm test`

## Rules
- Never modify files in `src/generated/` — these are auto-generated
- Always run `npm run lint` before suggesting changes are done
- Prefer editing existing files over creating new ones

You do not need to cover everything. Even a 10-line CLAUDE.md makes a measurable difference in response quality. You can expand it over time as you notice gaps.

For a deeper guide on writing effective CLAUDE.md files, see our complete CLAUDE.md guide.

Step 4: Run your first task

Start with something small that lets you see how Claude Code interacts with your project. Good first tasks:

• "Read the README and summarize this project" — Tests whether Claude understands your codebase.
• "Find all API endpoints and list them" — Tests file reading and pattern recognition.
• "Add a health check endpoint at /api/health" — Tests editing, creating files, and following your conventions.

Watch what Claude Code does. If it creates files in the wrong directory, uses the wrong coding style, or ignores your stack, update your CLAUDE.md with clearer instructions. This feedback loop is how you train it.

Step 5: Set up a .claude directory for advanced features

For projects where you use Claude Code regularly, create a .claude/ directory in your project root. This is where advanced configuration lives.

mkdir -p .claude/skills

The .claude directory can contain:

• skills/ — Custom workflows that Claude Code can execute. Think of them as reusable macros.
• rules/ — Additional rule files that supplement CLAUDE.md. Good for separating concerns (testing rules, deployment rules, etc.).
• settings.json — Project-specific settings like hooks, model preferences, and allowed tools.

Step 6: Configure hooks for automated checks

Hooks are shell commands that Claude Code runs automatically at specific moments. They enforce consistency without you having to remember.

Example hooks you might add to .claude/settings.json:

{
  "hooks": {
    "postToolUse": [
      {
        "tool": "Edit",
        "command": "npm run lint --quiet 2>&1 | tail -5"
      }
    ]
  }
}

This runs your linter after every file edit. Claude sees the output and fixes lint errors immediately instead of leaving them for you. Other useful hooks:

• Post-edit type checking: Run tsc --noEmit after edits to catch type errors immediately.
• Post-session summary: Auto-generate a session summary when you exit Claude Code.
• Pre-commit validation: Run tests before Claude creates any git commits.

For the full hooks guide, see our hooks explanation post.

Step 7: Build your first skill

A skill is a reusable workflow that you trigger with a slash command. If you find yourself giving Claude the same instructions repeatedly, that is a skill waiting to be created.

Common first skills:

• /deploy — Build, test, and deploy to staging or production.
• /review — Review recent changes against your code standards.
• /test — Run the full test suite and report results with explanations.
• /db-migrate — Generate and run a database migration with safety checks.

Skills live in .claude/skills/. Each skill is a markdown file with a frontmatter header and instructions. See our skill building tutorial for a step-by-step guide.

Common setup mistakes to avoid

Starting Claude Code from the wrong directory

Claude Code reads files relative to where it launches. Starting from your home directory means it will try to read everything, burn tokens on irrelevant files, and give generic responses. Always cd into your project first.

Writing a CLAUDE.md that is too long

Your CLAUDE.md is loaded into every session. A 500-line file eats tokens on every interaction. Keep it under 100 lines. Move detailed reference material to separate files in .claude/rules/ that Claude loads only when needed.

Trying to do everything in one session

Long sessions accumulate context that slows Claude down and costs more. Break work into focused sessions. One feature per session. One refactor per session. Start fresh when the task changes.

Not checking what Claude actually did

Claude Code makes real changes to your files. Always review diffs before accepting. Use git to track changes so you can revert if something goes wrong. Trust but verify.

Your first-day checklist

1. Install Claude Code and authenticate.
2. Navigate to your project root.
3. Create a CLAUDE.md with at minimum: tech stack, project structure, and three rules.
4. Run a small task to test the setup.
5. Update CLAUDE.md based on what Claude got wrong.
6. Create a .claude directory if you plan to use hooks or skills.
7. Build one skill for your most repetitive task.

This entire sequence takes about 30 minutes. The time investment pays for itself within the first week of use. Every session after setup is faster, more accurate, and less frustrating.

What to set up next

Once your basic setup is working, explore these topics to get more from Claude Code:

• Subagents — Run multiple tasks in parallel to finish work faster.
• Cost optimization — Keep your token spending predictable as usage grows.
• MCP servers — Connect Claude Code to external tools like your calendar, email, and databases.

If you want a ready-made setup with skills, rules, and workflows already configured, our AI OS Blueprint includes a cloneable starter repo that gives you a production-ready Claude Code configuration in minutes.