What you'll learn

By the end of this you'll have a working Claude Project configured for a real codebase, and you'll understand how to use it in a way that produces consistently better output than a blank conversation. You'll know what to upload, how to write effective project instructions, and where the feature falls short compared to what you might expect.

This is a practical guide, not a features overview. The focus is on the setup decisions that actually affect output quality and the workflow patterns that make the feature worth paying for.

Who this is for

  • Developers who use Claude regularly and find themselves re-explaining the same context at the start of every conversation
  • Anyone evaluating whether Claude Pro is worth it specifically because of the Projects feature
  • Cursor or other IDE users who access Claude through the chat panel and want the same kind of persistent context their editor gives them in a standalone claude.ai workflow

If you're brand new to Claude and haven't used the basic interface yet, start with the Claude review first. Projects is a layer on top of the base tool — it makes more sense once you have some experience with what the base tool is doing.

What are Claude Projects?

Claude Projects is a feature in Claude.ai Pro (and Teams) that creates persistent context for a specific body of work. A Project has its own memory: you can upload reference files, write instructions that shape how Claude responds within the Project, and all conversations within the Project share that foundation.

Plain English: instead of pasting your README, your tsconfig, and a "I use TypeScript with explicit return types" explanation at the start of every conversation, you upload those once to a Project and they're available in every conversation you start within it.

Simple idea: it's the closest Claude has to Cursor's rules file, but in the claude.ai interface instead of the editor. Not identical — it doesn't have live file access — but meaningful for developers who do a significant amount of their AI-assisted work outside the editor.

Prerequisites

  • Claude Pro or Teams plan — Projects is not available on the free tier
  • A real codebase or project to configure — the guide is more useful with something concrete
  • Familiarity with Claude's basic interface — if you haven't used Claude for coding yet, spend a day with it first

You don't need to be technical about AI to use this well. The setup is essentially "write clear instructions and choose the right files to upload." The decisions are judgment calls, not technical ones.

Setup from zero

Step 1 — Create a new Project

In the claude.ai sidebar, click the "Projects" section and then "New Project." Give it a clear name that describes the codebase or area of work: "Main API project," "Blog site," "Data pipeline scripts." The name matters for navigation when you have several projects — be specific enough that you'll know what it is in two months.

You can create multiple Projects. Most developers end up with two or three: one for their main work codebase, one for a side project or different technology context, and sometimes one for general reference material. Keep Projects focused — mixing two unrelated codebases in a single Project degrades the output quality.

Step 2 — Write your Project instructions

Before uploading any files, write the Project instructions. This is the part that most people underprepare. The instructions are persistent context that shapes every conversation in the Project. Think of them as the equivalent of a Cursor rules file, written in plain English.

A useful structure:

[What this project is]
This is a Next.js 15 App Router application using TypeScript and MongoDB.
Deployed on Vercel. The main purpose is a content-focused blog with server-side rendering.

[Code conventions]
TypeScript with explicit return types on all functions. No any.
Server Components by default. Add "use client" only when state or browser APIs require it.
Tailwind for all styles — no CSS modules, no inline styles.
Zod for runtime validation on any external data.

[Communication style]
Skip the preamble. Answer directly.
When proposing code changes, show only the modified section unless the full file is relevant.
If a question is ambiguous, ask one clarifying question before answering.

[What to avoid]
Don't suggest third-party libraries unless I ask.
Don't suggest changes outside the files I reference.

The last two "avoid" instructions are the ones that matter most in practice. Without them, Claude will helpfully suggest a caching library when you asked about a function, or rewrite a file you didn't mention. The explicit scope constraints prevent the majority of scope drift.

Step 3 — Choose and upload reference files

This is where most developers make the mistake of uploading everything. More context is not better context. Upload focused, hand-written files that represent how the codebase actually works.

What works well:
- A plain-English project overview or README (1–2 pages max)
- Your tsconfig.json or equivalent config file
- 2–4 representative source files that show your actual patterns
- A brief data model or schema description if you work with a database

What to avoid uploading:
- Minified or bundled files (package-lock.json, build outputs)
- Auto-generated code
- Large files that are mostly boilerplate
- Files you never actually work with in conversations

The test for whether to upload a file: "Would I paste this into a conversation to explain how this project works?" If not, it probably doesn't belong in the Project context.

Step 4 — Run a test conversation

Before using the Project for real work, run a test. Ask Claude to do a small task in the Project context and check two things: does it follow the instructions you wrote, and does it reference the uploaded files appropriately?

A good test prompt: "I need to add a simple utility function that fetches a user by ID from MongoDB. Where would this go in the current architecture, and what would it look like?" Don't tell it where to put the function. See if it suggests a location that makes sense given the files you uploaded.

If it suggests something wrong — the wrong directory, the wrong pattern, a library you don't use — fix the instructions or uploaded files before continuing. A good test conversation before real work saves you from building on wrong assumptions for a week.

The mental model

Claude Projects work because Claude is good at using provided context rather than relying on memorized generalizations. When you upload a representative file, Claude doesn't "learn" from it in a training sense — it reads it as context for the current conversation. The persistent part is that you only have to provide that context once per Project, not in every conversation.

The gap to understand: Projects don't give Claude live access to your files. If you add a new file to your codebase and don't upload it to the Project, Claude doesn't know about it. This is meaningfully different from Cursor, where the editor has real-time access to your file tree.

The practical implication: Projects are most valuable for stable architectural context — the things about your codebase that don't change often. For current, in-progress work, you still paste the relevant code into the conversation directly. Projects reduce the baseline setup overhead; they don't eliminate the need to provide current code.

Key terms

Project instructions — the persistent text that shapes every conversation in a Project. The equivalent of a system prompt or rules file. Written once, applied consistently.

Project files — reference files you upload to a Project. Available as context in every conversation within the Project. Not edited by Claude — they're read-only reference material.

Conversation memory — within a single Project, Claude has access to recent conversation history in addition to the Project instructions and files. This fades for very old conversations; the Project files and instructions are the stable persistent layer.

Project scope — the implicit definition of what belongs in a Project. Should correspond to a single coherent codebase or area of work, not multiple unrelated projects. Mixing scope degrades output quality.

Context window — the total amount of text Claude can process at once: Project instructions plus uploaded files plus the current conversation. Claude's 200k token context window is large, but very large Project uploads do reduce the effective space for conversation.

Step-by-step

Writing effective Project instructions

The most common failure mode for Project instructions is being vague where specificity matters. "Follow best practices" is not an instruction. "Return types must be explicit on all functions, no any, use the logger module at src/lib/logger.ts for all error logging" is an instruction.

Write the instruction for the specific mistake you want to avoid. If you've caught Claude using console.log instead of your logger twice, add the explicit rule. If it keeps adding unnecessary comments, add "no comments that just describe what the code does." Instructions should evolve based on actual output failures, not anticipate every possible issue upfront.

Uploading a good architectural summary

Uploaded files don't have to be actual source code. One of the most useful things to upload is a plain-text architectural summary you write yourself:

## Architecture overview

This is a Next.js 15 App Router blog. MongoDB for content storage via Mongoose.
Vercel for deployment. No client-side state management library — useState where needed.

## Directory structure

src/app/ — route files and layouts (App Router conventions)
src/modules/ — business logic, data access, type definitions
src/components/ — shared UI components
scripts/ — seed data, one-off utilities

## Data flow

Content is fetched server-side in page.tsx files using async functions.
No client-side fetching for primary content.
Forms use Server Actions defined in the same file as the form component.

## What to avoid suggesting

- No Redux, Zustand, or other state management
- No CSS-in-JS
- No getServerSideProps (we're App Router, not Pages Router)

This kind of summary is better than uploading five random source files because it's curated. It tells Claude exactly what the architecture is rather than hoping it infers the right patterns from examples.

Little tip: include a "what to avoid" section in your architectural summary. It's faster to head off common AI mistakes in the context than to correct them repeatedly in conversations.

Running a focused coding session

Within a Project, you still paste the relevant code for the specific task. The Project instructions and files reduce the baseline setup — you don't explain the stack every time — but the actual code you're working on should still be in the conversation:

I need to add a function that retrieves posts by tag from MongoDB.
Here's the existing getPosts function to use as a reference:

[paste the existing function]

The new function should follow the same patterns. Return type should be explicit.
Sort by publishedAt descending. Limit to 20 by default.

The Project context means Claude already knows your database module location, your TypeScript conventions, and your codebase structure. The conversation-level context is the specific code you're working on right now. Both layers together produce output that's consistent with your actual codebase.

Keeping Project files current

Project files don't update automatically when your codebase changes. If you significantly refactor a module you've uploaded, update the Project file. If you add a major new module, upload a summary of it.

A practical cadence: at the start of each week, spend a couple of minutes checking if anything you've uploaded is significantly out of date. You don't need to keep it perfectly synchronized — the purpose of the uploaded context is to represent the stable architecture, and that doesn't change every day.

Little tip: add the date to your architectural summary file name or the first line of the file ("Updated: 2026-07-22"). It makes it easy to tell at a glance whether the context is current, and reminds you to update it when you've made significant changes.

Using multiple Projects

If you work across more than one codebase — or even different domains within the same codebase — separate Projects are worth the overhead. A frontend and a backend service with different conventions, different tech stacks, or different team norms should be separate Projects.

The signal that a single Project is getting too broad: you start noticing that Claude occasionally applies conventions from one context to another. A TypeScript convention that makes sense for your frontend doesn't belong in a Python data pipeline script. Separate Projects prevent that bleed.

Patterns / when to use

  • Repeated codebase work — if you're returning to the same codebase regularly, a Project pays back within the first week. Less re-explaining means more useful first responses.
  • Architectural consistency — Projects are especially useful when you want generated code to match your actual patterns, not just follow generic best practices. Upload a representative service file and Claude generates new service files in the same style.
  • Code review sessions — start a Project conversation with "here's the PR diff" without having to re-explain your conventions. The review feedback reflects your actual standards.
  • Technical writing — documentation for a specific codebase is better when Claude knows the codebase. A Project with the relevant modules uploaded produces README and API reference prose that uses the actual function signatures and names.

Not worth the setup for: one-off tasks, experiments you'll discard, or questions that don't depend on codebase context. Open a regular conversation for those.

Common mistakes

Uploading minified or auto-generated files — package-lock.json, dist/ output, generated type files, anything that isn't hand-written. These add token overhead without adding useful context. Claude can't derive your code conventions from a minified bundle.

Setting vague instructions — "write clean code" and "follow TypeScript best practices" are not instructions. Every AI already tries to do those things. Specific instructions address specific problems you've actually encountered: "explicit return types on all functions," "never suggest adding try-catch unless the error needs specific handling," "always use the ErrorCode enum from src/types/errors.ts."

Never updating the Project files — if you upload an architectural summary in January and your team refactors the data layer in February, Claude's context is wrong. The outputs will be subtly off in ways that are hard to debug because they look reasonable but don't fit the actual current architecture.

Using Projects as a substitute for pasting current code — Projects give Claude stable architectural context. They don't give it the current state of the file you're working on. You still need to paste the relevant code. "Here's the function I'm working on" is still required; Projects just mean you don't also need "here's the stack we use and here's how we structure services."

Mixing unrelated codebases in a single Project — a backend API and a mobile app in the same Project causes convention drift. Keep Projects scoped to a single coherent technology context.

Troubleshooting

Claude is ignoring the Project instructions — check for conflicts: if your instructions say "no CSS-in-JS" but an uploaded file uses CSS-in-JS, Claude will be confused about which to follow. Also check for vague vs specific: "use modern patterns" isn't actionable. Rewrite the specific instruction that's being ignored to be more precise.

Uploaded files aren't being used — very long Project files or a large total upload can dilute context. Trim uploaded files to the most relevant sections. Also check if the conversation topic is actually related to the uploaded files — Claude uses context proportionally to relevance.

The same mistake keeps happening despite instructions — try moving the relevant instruction to the first line of the instructions file, rather than buried in the middle. Position matters. Also check if the instruction is specific enough: "don't use inline styles" is better than "use Tailwind consistently."

Project conversations feel slower than regular ones — they are, slightly. The persistent context adds to the token overhead on every request. If speed is critical for a specific session, a regular conversation without the Project context is faster. Use Projects for the work that benefits from context; use regular conversations for quick questions.

Context from old Project conversations is affecting new ones — if a Project has many old conversations, Claude's conversation memory may include context from sessions that are no longer relevant. Starting a fresh conversation within the Project resets the conversational context while keeping the Project instructions and files.

Checklist

  • [ ] Claude Pro or Teams plan active
  • [ ] Project created with a specific, descriptive name
  • [ ] Project instructions written — conventions, communication style, what to avoid
  • [ ] Architectural summary written and uploaded as a reference file
  • [ ] 2–4 representative source files selected and uploaded
  • [ ] Test conversation run — asked a location question and verified the response makes sense
  • [ ] Date or version marker added to uploaded files for staleness tracking
  • [ ] Instructions updated at least once based on a specific output failure

Practice task

Take a module in your current codebase that you work in regularly — somewhere between 100 and 300 lines. Write a plain-English architectural summary of what the module does, how it connects to the rest of the application, and what conventions it follows. Upload that summary to a new Project along with the actual module file. Then open a conversation within the Project and ask: "I need to add a new function to this module that handles [a specific thing you actually need]. Show me what it would look like."

Compare that output to what you'd get in a regular Claude conversation where you paste the same prompt without the Project context. The difference in how well the generated code matches your actual patterns is the value you're measuring. If the difference is large, Projects will save you significant re-explanation overhead every week.

FAQ

Is Claude Projects the same as Cursor's rules file?
Similar concept, different implementation. Both give Claude persistent context about a codebase. Cursor's rules file has live access to your project files and open editor context. Claude Projects work through uploaded static files — you upload a snapshot of key files once, and they serve as reference material. Cursor's integration is deeper, but Claude Projects is available for any workflow that happens outside the editor.

Do I need to re-upload files every time I make code changes?
No — and that's the point. Upload stable architectural context, not constantly-changing feature code. Update the uploads when you've made a significant architectural change, not on every commit. The Project is for the things about your codebase that stay relatively stable.

Can I share a Project with teammates?
On the Teams plan, yes — Projects can be shared within a workspace. On Plus (individual plan), Projects are personal. If you're on a team that uses Claude, the Teams plan is worth the additional $10/user/month for the shared context alone.

What's the difference between Project instructions and uploaded files?
Instructions are active — they tell Claude how to behave and what to avoid. Uploaded files are reference material — Claude reads them for context but doesn't follow them as directives. Put your code conventions in instructions. Put your representative source files and architectural summaries in uploaded files. Both contribute to better output but in different ways.

How many files can I upload to a Project?
Anthropic's current limits allow multiple files with a total context budget per Project. More important than the limit is quality: five focused files are worth more than twenty diluted ones. If you're hitting limits, that's a sign you're uploading too broadly, not that you need a higher limit.

Does a Project conversation share data with OpenAI or other providers?
No — Claude is an Anthropic product. Conversations with Claude go through Anthropic's infrastructure. Read Anthropic's current privacy policy for specifics on data retention and use. For Teams and Enterprise, Anthropic provides explicit data handling commitments.

What to learn next

  • Claude review — the full picture of Claude's capabilities and limits before investing in the Projects setup
  • Prompt engineering for code — the constraint and verify patterns that improve Claude output regardless of whether you're using Projects
  • Cursor AI complete guide — how editor-integrated AI context compares to Projects for developers who spend most of their AI time inside an editor
  • [Claude review](/ai/reviews/claude-review)
  • [Cursor AI complete guide](/ai/tutorials/cursor-ai-complete-guide)
  • [Prompt engineering for code](/ai/tutorials/prompt-engineering-for-code)

Takeaways

Claude Projects closes the biggest friction gap in standalone Claude use: re-explaining your codebase and conventions at the start of every conversation. With a well-configured Project, Claude's first response in a session is already grounded in your stack, your patterns, and your preferences — without any manual context setup.

The setup isn't complex, but the decisions matter. What you upload, how specific your instructions are, and whether you keep the context reasonably current determine whether the feature actually helps. Vague instructions and irrelevant uploads produce marginal improvement. Focused files and specific rules produce consistent output that matches your actual codebase.

If you remember only one thing: write specific instructions, not general ones. "Follow best practices" does nothing. "Explicit return types on all functions, no any, use ErrorCode from src/types/errors.ts for all errors" does something. Every instruction in your Project should address a specific mistake you've actually seen Claude make.