Setting Up Your First Project in Claude Code
The way you prepare a project folder before opening Claude Code determines how useful every session will be. A well-prepared project takes Claude Code two minutes to understand. A poorly prepared project takes fifteen minutes of back-and-forth just to get oriented.
The Anatomy of a Claude-Ready Project
IDEAL PROJECT STRUCTURE FOR CLAUDE CODE ┌─────────────────────────────────────────────────────────┐ │ my-project/ │ │ ├── CLAUDE.md ← Project guide for Claude │ │ ├── README.md ← Human-facing docs │ │ ├── .gitignore ← Tells Claude (and git) │ │ │ what NOT to look at │ │ ├── package.json ← Dependencies and scripts │ │ ├── src/ │ │ │ ├── index.js ← Main entry point │ │ │ ├── routes/ ← Grouped by function │ │ │ └── utils/ ← Grouped by function │ │ └── tests/ ← Tests in one clear spot │ └─────────────────────────────────────────────────────────┘ Clear structure = Claude finds the right file fast Flat chaos = Claude guesses and sometimes guesses wrong
Creating a New Project from Scratch
Open your terminal and create a project folder:
mkdir my-first-project cd my-first-project
Now create a basic starting structure. For a simple JavaScript project:
mkdir src tests touch src/index.js tests/index.test.js README.md
Initialize it as a Node.js project:
npm init -y
This creates a package.json file that tracks your project name, version, and dependencies. The -y flag accepts all defaults so you do not have to answer a series of questions.
Creating Your CLAUDE.md File
The CLAUDE.md file is the single most important thing you add to any project that Claude Code will work on. Claude Code reads this file automatically at the start of every session in this folder. Think of it as a briefing document you write once so you never have to repeat yourself.
What to Put in CLAUDE.md
CLAUDE.md — THE BRIEFING DOCUMENT ┌──────────────────────────────────────────────────────────┐ │ Section 1: Project Overview │ │ • What this project does (one paragraph) │ │ • Who it is for │ │ • Current status (in development, in production, etc.) │ ├──────────────────────────────────────────────────────────┤ │ Section 2: Tech Stack │ │ • Language and version │ │ • Framework │ │ • Key libraries │ │ • Database if any │ ├──────────────────────────────────────────────────────────┤ │ Section 3: Code Style Rules │ │ • Tabs or spaces, and how many │ │ • Naming convention (camelCase, snake_case, etc.) │ │ • File organization rules │ ├──────────────────────────────────────────────────────────┤ │ Section 4: Important Commands │ │ • How to run the project │ │ • How to run tests │ │ • How to build for production │ ├──────────────────────────────────────────────────────────┤ │ Section 5: Things to Avoid │ │ • Libraries not to use │ │ • Patterns that caused problems before │ │ • Files never to touch without discussion │ └──────────────────────────────────────────────────────────┘
A Real CLAUDE.md Example
# Project: Task Manager API ## What This Is A REST API that lets users create, read, update, and delete personal tasks. Built for the final-year university project. Currently in development. ## Tech Stack - Language: JavaScript (Node.js 20) - Framework: Express.js 4 - Database: SQLite (via better-sqlite3) - Testing: Jest ## Code Style - 2-space indentation - camelCase for variables and functions - PascalCase for classes - All functions must have a JSDoc comment above them ## Commands - Run: npm start - Test: npm test - Lint: npm run lint ## Do Not Do This - Do not use async/await inside the database layer — use callbacks - Do not add new npm packages without asking me first - Never edit database/migrations directly — always create a new migration file
This file takes ten minutes to write and saves hours of confusion over the project lifetime.
Setting Up a .gitignore File
A .gitignore file tells both Git and Claude Code which files to ignore. Without it, Claude Code might read large auto-generated files, node_modules folders with thousands of files, or secret environment files.
WITHOUT .gitignore WITH .gitignore ────────────────── ──────────────── Claude reads: Claude reads: • node_modules/ (10,000 files) • src/ (your actual code) • .env (your secrets!) • tests/ • build/ (generated code) • package.json • .DS_Store (Mac junk) • CLAUDE.md Context window fills up Context window stays immediately with noise focused on useful code
Create a .gitignore file in your project root:
touch .gitignore
Open it in any text editor and add these lines for a typical Node.js project:
node_modules/ .env .env.local build/ dist/ .DS_Store *.log coverage/
Launching Claude Code in Your Project
Always launch Claude Code from inside your project folder. The folder you are in when you type claude becomes the root that Claude Code works from. It reads files relative to that location.
CORRECT LAUNCH WRONG LAUNCH
────────────── ────────────
$ cd my-first-project $ claude
$ claude (from home directory)
Claude sees: src/, tests/, Claude sees: Desktop/,
CLAUDE.md, package.json Documents/, Downloads/,
hundreds of unrelated files
What Claude Code Shows When It Starts
┌──────────────────────────────────────────────────────┐ │ │ │ Claude Code v1.0.xx │ │ Working directory: /Users/you/my-first-project │ │ Reading CLAUDE.md... ✓ │ │ │ │ Type your message below. Press Enter to send. │ │ Type /help for a list of commands. │ │ │ │ > │ │ │ └──────────────────────────────────────────────────────┘
The "Reading CLAUDE.md" confirmation line tells you the briefing document loaded correctly. If you do not see it, check that the CLAUDE.md file is in the current directory, not inside a subfolder.
Opening an Existing Project with Claude Code
Navigate to the existing project folder before launching:
cd path/to/existing-project claude
If the project has no CLAUDE.md file, create one before your first session. Ask Claude Code to help you write it — give it a few minutes to explore the project first:
Explore this project and then create a CLAUDE.md file that explains what it does, its tech stack, and the code style conventions you can observe from the existing code.
Claude Code reads through the files, infers the project structure, and drafts a CLAUDE.md for you to review and refine. This process takes about two minutes and pays back that time on every future session.
Managing Multiple Projects
HOW CLAUDE CODE HANDLES MULTIPLE PROJECTS ┌────────────────────────────────────────────────────┐ │ │ │ projects/ │ │ ├── project-a/ │ │ │ └── CLAUDE.md ← "I am a Python web scraper" │ │ ├── project-b/ │ │ │ └── CLAUDE.md ← "I am a React dashboard" │ │ └── project-c/ │ │ └── CLAUDE.md ← "I am a Go microservice" │ │ │ │ Open terminal in project-a → Claude knows it is │ │ the scraper and behaves accordingly │ │ │ │ Open terminal in project-b → Claude knows it is │ │ the dashboard — completely separate context │ │ │ └────────────────────────────────────────────────────┘
Each project is completely independent. Claude Code picks up the context from whichever folder it launches in. You switch projects by switching terminal windows or navigating to a different folder before typing claude.
Key Points
- Always launch Claude Code from inside your project folder — the launch location sets the working directory for the entire session.
- A CLAUDE.md file in your project root acts as a permanent briefing document that Claude Code reads at the start of every session.
- A proper .gitignore prevents Claude Code from wasting context window space on node_modules, build files, and secrets.
- For existing projects without CLAUDE.md, ask Claude Code to generate one by exploring the codebase — it drafts a solid starting version in minutes.
- Each project gets its own independent Claude Code context — switching projects means switching folders.