Claude Projects: What the Docs Promise vs. What You Actually Get

Projects are Claude's answer to a problem every regular user hits within a week: you keep pasting the same context. Same company docs, same style guide, same "you are a helpful assistant that writes in AP style and never uses Oxford commas." Projects let you set that once and stop repeating yourself. Anthropic's documentation frames them as persistent knowledge containers — a place to upload files, write custom instructions, and keep related conversations together. That framing is mostly accurate, but the thing that matters most about Projects isn't the file uploads or the conversation threads. It's the custom instructions slot, and understanding what it actually does under the hood.

What The Docs Say

According to Anthropic's documentation, a Project is a workspace within Claude.ai that combines three things: custom instructions that apply to every conversation in the project, uploaded knowledge files that Claude can reference, and a collection of conversation threads scoped to that project's context. You create a Project, give it a name, write instructions, upload relevant files, and then every new conversation you start within that Project inherits all of it. The docs describe this as giving Claude "persistent context" — a way to maintain continuity across sessions without manually re-explaining your setup each time.

The file upload limit is generous. Per Anthropic's docs, you can upload up to 200K tokens worth of project knowledge [VERIFY], which works out to roughly several hundred pages of text depending on format. Supported file types include PDF, TXT, CSV, and common code files. The docs emphasize that this lets you give Claude access to information beyond its training cutoff — your internal docs, your latest API reference, your company style guide.

What Actually Happens

I tested Projects across three use cases over two weeks: a technical writing project with a style guide and reference docs, a coding project with architecture docs and API specs, and a general research project with uploaded papers. Here's what I found.

The custom instructions slot is the single most valuable feature, and it's not close. This is effectively a system prompt that persists across every conversation in the project. You write it once — "always respond in British English," "use snake_case for Python examples," "never suggest MongoDB when I ask about databases" — and it applies every time. For anyone who's been manually pasting instructions at the top of conversations, this saves real time and eliminates the drift that happens when you forget to include one of your constraints. In practice, Claude follows Project-level custom instructions with high fidelity. I set up a writing project with specific formatting rules (no headers with gerunds, paragraphs between 3-5 sentences, em dashes over parentheses) and across 30+ conversations it broke those rules maybe twice. That's better compliance than I get from pasting the same instructions manually, probably because manual pasting invites small edits that introduce inconsistency.

The file uploads work, but with caveats. Claude genuinely reads and references uploaded files — this isn't keyword matching or filename guessing. I uploaded a 40-page API reference and asked Claude to write integration code using specific endpoints. It pulled the correct endpoint paths, parameter names, and authentication patterns from the uploaded doc. That's the good part. The less good part: Claude doesn't always know when to reference uploaded files versus its training data. I uploaded a style guide that contradicted Claude's default tendencies (specifically, it required passive voice in certain contexts where Claude naturally gravitates toward active). Claude would sometimes follow the uploaded guide and sometimes revert to its defaults, especially in longer conversations where the uploaded context might be getting pushed further from the active attention window. The workaround is to explicitly reference the uploaded file: "per the style guide I uploaded" gets much better compliance than hoping Claude will check it on its own.

File type performance varies. Plain text and Markdown files work best — Claude processes these cleanly and references them accurately. PDFs work but with occasional formatting artifacts, especially for PDFs with complex layouts, tables, or images. Claude can't see images in uploaded PDFs; it only gets the extracted text. CSV files work for small to medium datasets, but if you're uploading a 10,000-row CSV expecting Claude to do data analysis, you'll hit context limits fast. Code files work well — uploading a Python module or a JavaScript file and asking Claude to work with it produces reliable results.

The Knowledge Cutoff Workaround

This is the sleeper use case that deserves its own section. Claude's training data has a cutoff, which means it doesn't know about your library's latest breaking changes, your API's new endpoints, or the framework update that shipped last month. But if you upload the current documentation as a text file to a Project, Claude can reference it as if it knew it all along. I tested this by uploading the docs for a library that had a major version bump after Claude's training cutoff. Without the upload, Claude confidently generated code using the old API. With the upload, it used the new API correctly and even warned about the deprecated patterns. This is genuinely useful for anyone working with fast-moving tools. The key insight: you don't need the entire docs. Upload the changelog, the migration guide, and the API reference for the parts you use. Targeted uploads outperform comprehensive dumps.

What Projects Are NOT

This is where the mental model matters. Projects are not RAG (retrieval-augmented generation). There is no vector database, no embedding search, no dynamic retrieval happening when you upload files. The uploaded content goes into Claude's context window alongside the custom instructions and your conversation. This means it's subject to the same context window constraints as everything else. If your uploaded files plus your conversation plus the custom instructions exceed the context limit, something gets compressed or dropped. In practice, this means Projects work best when the uploaded knowledge is focused and relevant, not when you dump everything you have and hope Claude will find the right needle.

Projects are also not persistent memory across conversations. Each conversation within a Project starts fresh — Claude doesn't remember what you discussed in a previous thread. The custom instructions and uploaded files carry over, but the conversation history doesn't. If you spent an hour refining a code architecture in one conversation, the next conversation in the same Project starts from zero on that topic. You'd need to either continue the existing conversation or re-explain the context. This is the most common source of frustration I see on r/ClaudeAI: users expect Projects to give Claude a memory of past conversations, and that's not what they do. They give Claude a memory of your setup, not your history.

Projects are not a filing cabinet either. Uploading 50 documents because they're all vaguely related to your work doesn't help. Claude performs better with 5 highly relevant documents than with 50 loosely related ones, because the relevant content gets more attention in the context window. Think of it as packing a carry-on, not filling a storage unit.

When To Use This

Projects earn their keep in three scenarios. First, any recurring task with consistent constraints. If you write code in a specific style, produce content with specific rules, or analyze data with specific frameworks, a Project with those constraints baked in saves you from re-establishing context every session. The time savings compound — what feels like a minor convenience in one conversation becomes significant across fifty.

Second, working with documentation that's newer than Claude's training data. This is straightforward: upload the current docs, get current answers. Developers working with actively maintained libraries should be doing this by default. Third, any domain where Claude's defaults are wrong for your context. Claude has opinions — about code style, about writing tone, about how to structure explanations. If your needs diverge from those defaults, custom instructions in a Project are how you override them reliably.

When To Skip This

If your tasks are one-off or highly varied, Projects add friction without payoff. Creating a Project, writing instructions, uploading files — that's setup time that only pays off if you're returning to the same context repeatedly. For a quick question about Python syntax or a one-time email draft, just use a regular conversation. Skip Projects when your context changes faster than you can update the uploads. If you're working on a codebase where the architecture shifts weekly, your uploaded files become stale fast, and stale context is worse than no context — Claude will confidently reference your outdated docs instead of falling back on its training data. Also skip Projects if you're tempted to use them as an organizational tool rather than a context tool. Having a "Work Stuff" project and a "Personal" project with no custom instructions and no uploaded files gives you exactly the same experience as regular Claude with extra clicks.

The Practical Setup

The ideal Project setup is minimal and intentional. Write custom instructions that are specific and testable — not "be helpful and thorough" but "always include error handling in code examples, use TypeScript over JavaScript unless I specify otherwise, keep explanations under 200 words unless I ask for detail." Upload 3-5 documents that directly relate to the work, not 30 documents that might be relevant someday. Test the setup by asking a few representative questions and checking whether the outputs actually differ from what you'd get in a vanilla conversation. If they don't differ, your instructions aren't specific enough.

The gap between what Projects promise and what they deliver is small, but it runs in both directions. They're less magical than "a second brain" and more useful than "a folder for conversations." The custom instructions slot alone — a persistent system prompt you write once — justifies the feature for anyone who uses Claude more than casually. Everything else is a bonus that works best when you treat it with the same discipline you'd apply to any context window: be specific, be relevant, and don't try to upload the world.

This article is part of the Claude Deep Cuts series at CustomClanker.