Setting Up a New Project with Claude

Series: Claude Learning Journey · Intermediate Usage

The first time you open Claude in a new project, it knows nothing. No structure, no conventions, no sense of what you’ve already built or why. You can spend the first ten minutes of every session feeding it context, or you can set a project up once and let it hold that context for you.

That’s what this post is about: making sure Claude understands your project before you start asking it to do real work.

Why Project Setup Matters

Claude’s usefulness scales with context. Ask it to write a function in a vacuum, you get a generic function. Give it your existing codebase, your patterns, your naming conventions, your constraints, and it writes something that actually fits.

The setup step is where you give it that foundation. Done well, you do it once per project. Done badly, you repeat it badly every session.

The README Transfer

The fastest way to give Claude project context is to drop your README into the conversation. Not just the title and installation instructions, but the stuff that matters: what the project does, what decisions have already been made, why certain choices were rejected, what the team conventions are.

If your README is thin, paste in more. A good README for Claude is one that explains not just what the project is, but how decisions were made.

Share the Architecture

For anything beyond a single-file script, give Claude the architecture. Not every internal detail, but the key decisions: what the main components are, how data flows, where the boundaries are.

For a typical web app: “The frontend is React with a separate API layer. The backend is a REST API in Python using FastAPI. Database is PostgreSQL. Auth is token-based. We keep business logic in service layers, not in route handlers.”

That one paragraph is worth twenty minutes of Claude guessing wrong.

Set the Conventions Upfront

Tell Claude how you want it to work in your project. A few examples:

“We use TypeScript strict mode. Prefer functional components. Never use default exports. Components go in src/components/.”

“Our Python code uses type hints everywhere. We follow the Black formatter. Import order: stdlib, third-party, local.”

These conventions are not restrictions. They are the difference between output that fits your project and output that needs significant rework.

What You’ll Learn

• Why project context compounds over sessions
• How to structure a project brief for Claude
• Where to store project conventions so Claude retains them
• How to avoid re-explaining your project every session

The Project Brief Pattern

The most useful thing you can do for a new project: write a project brief. Not for Claude, initially — for yourself. But keep it where Claude can read it.

A project brief for Claude should cover:

• What the project does and why it exists
• The main technical decisions and why they were made
• Coding conventions and style preferences
• What “done” looks like for this project
• Any constraints or non-goals

It does not need to be long. Two hundred words of real context beats a thousand words of vague overview.

Test It

Start a new Claude session, give it your project brief, and ask it something basic: “What’s the main entry point for this project?” or “Where would you add a new API endpoint?” If the answer shows real understanding, you’ve set it up right. If it guesses, the context gap is still too wide.

What’s Next

Now that Claude understands your project, the next skill is making it work with your existing code without breaking things. We will cover context windows — how to give Claude enough to work with without overwhelming it.

---

Part of the Claude Learning Journey series · Next: Context Windows: Giving Claude the Right Amount of Information