More on Tokens: Project Instructions, Project Files, and the Token Trade-offs You Need to Know

More on Tokens: Project Instructions, Project Files, and the Token Trade-offs You Need to Know

Published: December 5, 2025 • 16 min read

It's been really fun exploring tokens and by now, I hope you have read the first, second, third, fourth and fifth blog posts on tokens.

As you read and understand them, you should naturally start asking questions like "how can I be more efficient with token usage when working with Claude?"

I found myself asking this question, especially when it comes to working with projects, after I uploaded the most recent blog post about tokens. So in this blog post, we are going to explore how projects work from a token and context window perspective.

What Are Projects in Claude?

First, I am tempted to once again make the assumption that anyone reading this definitely knows what a project is in Claude but just in case, let me break it down.

In Claude, you can simply click on the plus button with an orange background at the top left corner of your screen to start a new chat. Everyone knows this and this is how most people use other LLMs like ChatGPT. However, projects give you a way to structure or organize your chats. It is like having a folder of chats.

REGULAR CHATS (No Organization):

┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│  Chat 1  │ │  Chat 2  │ │  Chat 3  │ │  Chat 4  │ │  Chat 5  │
│  ------  │ │  ------  │ │  ------  │ │  ------  │ │  ------  │
│ Job help │ │ Recipe Q │ │ Job help │ │ French Q │ │ Job help │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
     ↑                          ↑                         ↑
     └────────── Related but scattered ───────────────────┘


PROJECTS (Organized Workspaces):

┌─────────────────────────────────────┐   ┌─────────────────────────────────────┐
│  📁 Job Search Project              │   │  📁 French Learning Project         │
│  ─────────────────────────────────  │   │  ─────────────────────────────────  │
│  Instructions: "Help me find dev    │   │  Instructions: "Include 3-5 French  │
│  roles in Canada, tailor resume..." │   │  sentences per response..."         │
│                                     │   │                                     │
│  Files: resume.pdf, certificates/   │   │  Files: vocab-list.md, grammar.pdf  │
│  ─────────────────────────────────  │   │  ─────────────────────────────────  │
│  ┌────────┐ ┌────────┐ ┌────────┐   │   │  ┌────────┐ ┌────────┐             │
│  │ Chat 1 │ │ Chat 3 │ │ Chat 5 │   │   │  │ Chat 4 │ │ Chat 6 │             │
│  │  RBC   │ │  CIBC  │ │  Okta  │   │   │  │Practice│ │ Quiz   │             │
│  └────────┘ └────────┘ └────────┘   │   │  └────────┘ └────────┘             │
└─────────────────────────────────────┘   └─────────────────────────────────────┘

✓ All job chats share the same instructions + files
✓ No need to re-upload resume for each conversation
✓ Easy to find related conversations

What Doesn't Affect Your Tokens

Now that you understand this, let's talk about other features of a Claude project and how they may or may not affect the context window.

When you start a Claude project, you are asked to give it a name and a description. You could have a project titled "French TCF Test" with a description of "I want to practice for my TCF test which I have to take later in January, 2026".

The project name and description have no effect on the tokens consumed and context window available for chats started within that conversation as Claude does not have access to these details (according to Claude's support documentation). They are just UI metadata that helps you, the user, find and organize your projects.

What DOES Affect Your Tokens

Now the next two features you might want to take advantage of are:

Project Instructions (Always Loaded)

Think of this like a rule that you want every single conversation that you start within that project to follow. For instance, I have mentioned in previous posts that I have this sentence as part of my project instruction for the project I work with the most: "For every response you provide to me, 3-5 sentences should be in French to help me learn French on the go."

With this instruction specified in my project, I don't have to specify it in every single chat.

Project Files (On-Demand via RAG)

Usually when you start a project in Claude, it is for a specific purpose: perhaps job applications, learning a language, learning a new skill, etc.

Let's say you are applying to jobs and you need Claude to help you draft resumes and cover letters for each job you apply to. For Claude to do this effectively, it needs to know about your previous work experiences and overall employment and education history. You may even need to provide information about what certifications you have, where you live and what geographical areas you are open to working from, especially if you want Claude to do the job of searching for available jobs for you.

If you had to specify all this information at the start of each chat, it would be time consuming and you will also most likely be inconsistent as you may forget to provide one or more certifications in one chat and then forget to provide a specific work experience detail in another chat.

When you simply add all the relevant files to your Project Files, Claude now has access to them in every single chat within that project.

How Project Context Affects Your Token Budget

Now unlike the project name and description which do not affect token consumption, the project files and instructions do affect token consumption and your context window for chats within that project. Here's how.

When you specify instructions and files for a project, you are essentially "pre-loading" context that automatically gets injected into EVERY conversation within that project.

Visualize it this way assuming that each conversation has an available context window of 200k tokens (which is the case for most Claude users anyways):

Standard Conversation (no project):
┌─────────────────────────────────────────────────────────┐
│ [System Prompt ~10K] [Your messages + Claude responses] │
│                      ← 190K available →                 │
└─────────────────────────────────────────────────────────┘

Project Conversation:
┌─────────────────────────────────────────────────────────────────────────────┐
│ [System Prompt ~10K] [Project Instructions] [Project Files] [Your messages] │
│                      ← Remaining available →                                │
└─────────────────────────────────────────────────────────────────────────────┘

Now you notice I added a "System Prompt ~10K" in the visualization above. If that doesn't make sense to you, then you've probably not read this blog post and I suggest you check it out. However, a brief explanation is that for every conversation started within Claude, Claude has its own prompts (aka, set of instructions under the hood) that control the model's behavior and these instructions use up tokens. This means that the amount of tokens you have access to within a chat is actually always less than the advertised number on Claude's website.

The Key Difference: Instructions vs Files

Now let's break it down even further as the visual above slightly oversimplifies things. Project Instructions and Project Files are not "pre-loaded" the exact same way.

How Project Instructions Work

For example, let's say you add a project instruction (also known as Context Instruction) of approximately 200 tokens to a project. That 200-token instruction gets loaded into context at the START of every single conversation in that project.

The implication of this is that long, detailed project instructions permanently reduce your available tokens per conversation.

500-word project instruction ≈ 650-800 tokens
Every conversation starts with ~650-800 fewer available tokens

How Project Files Work

Now with Project files, it works a bit differently.

If you are reading this, you have probably uploaded files to Claude or any other LLM when working with them. Here is how a direct upload of a file in a conversation affects your token consumption and context window:

You attach resume.pdf → Entire file tokenized → Added to context window

Now it works slightly differently when you add the same file to your list of project files.

In the Claude God Tip #5 blog post, I introduced the concept of tools in Claude and also briefly talked about the project_knowledge_search tool that allows Claude to dig through the documents provided in your project files list.

You see, what this project_knowledge_search tool does that is really nice is that it only retrieves relevant chunks of the file or files attached in the project files list.

For instance, if you added a resume file that cost a total of 2500 tokens directly to a conversation, you have automatically used up 2500 tokens. However, if you add the same resume file to your project files and you ask a question in a specific chat that only requires the education section in your resume, the project_knowledge_search tool will only retrieve the education section which might only use up 800 tokens versus loading the entire file.

How project_knowledge_search Works

You can visualize it this way:

You ask: "What was my GPA?"

Step 1: Claude calls project_knowledge_search
Step 2: System searches indexed project files
Step 3: Relevant chunks returned (maybe ~500-2000 tokens)
Step 4: Those chunks added to context
Step 5: Claude responds using that context

Token Accumulation from Multiple Searches

Each retrieval of information from the project files adds tokens to your context window and multiple searches in one conversation accumulates:

Search 1: +1,500 tokens (chunk about education)
Search 2: +1,200 tokens (chunk about work history)
Search 3: +800 tokens (chunk about skills)
Running total: 3,500 tokens consumed by retrievals

Direct Upload vs Project Files: A Comparison

Here is a quick table comparison that summarizes the difference between direct file uploads and adding them to your project files:

The key takeaway here is that a 50-page document added as a project file might only cost ~2,000 tokens per conversation as Claude uses the project_knowledge_search tool to retrieve relevant chunks. However, the same document uploaded directly would immediately cost ~15,000+ tokens.

Projects use files this way by using retrieval-augmented generation (RAG), which allows Claude to work with larger amounts of information more efficiently by only loading relevant content into the context window.

A Typical Project Conversation

Here is a great visual of what a typical conversation might look like when you have a project with 500 tokens of instructions and 10 files that get searched frequently:

Conversation start:
  System prompt:        ~10,000 tokens
  Project instructions:    ~500 tokens
  Available:           ~189,500 tokens

After 5 project searches:
  Retrieved chunks:     ~6,000 tokens
  Available:           ~183,500 tokens

After 20 messages + responses:
  Conversation content: ~25,000 tokens
  Available:           ~158,500 tokens

After 10 more searches:
  More retrieved chunks: ~12,000 tokens
  Available:           ~146,500 tokens

Notice from the illustration above that it is very easy for project-conversations to fill up their context window very quickly.

Optimization Tips

To optimize your token usage for conversations within projects:

• Keep your project instructions concise as every word costs tokens in every conversation within that project
• If the instruction is super long and detailed, convert them into a project file so that they are retrieved on demand rather than always loaded instructions for every chat
• Use separate files for separate topics and provide descriptive filenames for them as that helps the project_knowledge_search tool to retrieve the files more accurately
• Remove files you no longer need from your project files list as they can pollute search results

Bonus: Project Instruction Optimization Prompt

As a bonus in this blog post, here is a prompt that you can use to optimize your project instructions:

Analyze my project instructions below and optimize them for token efficiency
while preserving all functional requirements.

For your optimization:
1. Remove filler words, redundant phrases, and unnecessary politeness
2. Convert verbose explanations into concise directives
3. Identify content that should be moved to project files (retrieved on-demand)
   rather than always-loaded instructions
4. Combine related instructions into single statements
5. Replace examples with patterns where possible
6. Remove any "why" explanations — keep only "what" directives

Provide:
- The optimized instructions
- Estimated token savings (percentage)
- List of content recommended to move to project files

Here are my current project instructions:

[PASTE YOUR PROJECT INSTRUCTIONS HERE]

In case you skimmed through the prompt above, notice that there is an important instruction there, number 3, which asks to identify content that should be moved to project files so that they are retrieved on demand.

Before: Non-Optimized Project Instructions (~850-900 tokens)

Now, here is an example of what a really long non-optimized project instruction might look like for a student learning Organic Chemistry within a Claude Project:

Hi, I'm a second-year university student majoring in Biochemistry and I created
this project to help me study for my Organic Chemistry II course. I'm finding
this course really challenging and I need help understanding the concepts better
so I can do well on my exams.

When I ask you questions about chemistry, I need you to explain things in a way
that I can actually understand. I'm not a genius or anything, so please don't
assume I already know everything. Break down complex concepts into simpler steps
and use analogies when possible to help me relate new ideas to things I already
know from everyday life.

I learn best through visual representations, so whenever it makes sense, please
include diagrams, reaction mechanisms drawn out step by step, or molecular
structures. If you can't draw them, describe them in enough detail that I could
draw them myself. I really need to see how electrons move in reactions and how
molecules change throughout a reaction pathway.

Here are the specific topics we're covering this semester that I'll need help with:
- Alcohols, ethers, and epoxides (reactions and synthesis)
- Aldehydes and ketones (nucleophilic addition reactions)
- Carboxylic acids and their derivatives (acyl substitution reactions)
- Enols and enolates (alpha-carbon chemistry)
- Conjugated systems and aromaticity
- Aromatic substitution reactions (electrophilic and nucleophilic)
- Amines and nitrogen-containing compounds
- Carbonyl condensation reactions (aldol, Claisen, etc.)
- Retrosynthesis and multi-step synthesis planning

When explaining reaction mechanisms, please always include:
1. The type of mechanism (SN1, SN2, E1, E2, addition, elimination, substitution, etc.)
2. Curved arrows showing electron movement
3. All intermediates and transition states
4. The driving force behind each step (why does this happen?)
5. Any relevant stereochemistry considerations
6. Common mistakes students make with this mechanism

I also need help with practice problems. When I ask you to give me practice problems,
please follow this format:
- Give me the problem first without the answer
- Wait for me to attempt it
- Then provide detailed feedback on my attempt
- Show me the correct solution with full explanation
- Suggest similar problems I should try to reinforce the concept

For my upcoming exams, I'll need help with different types of questions:
- Predict the product questions
- Propose a mechanism questions
- Synthesis problems (how would you make X from Y?)
- Retrosynthesis problems (work backwards from target molecule)
- Ranking/comparison questions (rank these in order of acidity, etc.)
- Conceptual questions about why certain reactions occur

Please also help me connect new material to things I learned in Organic Chemistry I
last year. I sometimes forget the basics and need a refresher on things like
electronegativity, resonance, induction, hybridization, and basic stereochemistry.

When I'm studying for exams, I might ask you to quiz me. In quiz mode, please:
- Ask me questions one at a time
- Don't give hints unless I specifically ask for them
- Keep track of which topics I'm struggling with
- At the end, summarize what I need to review more

My professor is Dr. Martinez and she really emphasizes understanding the "why"
behind reactions, not just memorizing them. She always says "electrons are lazy
and greedy" meaning they seek stability and are attracted to positive charges.
Please incorporate this philosophy into your explanations.

I also have access to our course textbook "Organic Chemistry" by Klein (4th edition)
and I sometimes reference specific chapters or problems from there. If I mention
a chapter or section number, please tailor your explanation to align with how
Klein presents the material.

My exams are usually structured like this:
- 20% multiple choice (conceptual)
- 30% short answer (mechanisms and predict the product)
- 50% long answer (synthesis and multi-step problems)

So I really need to focus on synthesis since that's where most of my grade comes from.

One last thing - I have a study group that meets on Wednesdays, so sometimes I'll
ask you to help me explain concepts to my classmates in simpler terms. Being able
to teach something means you really understand it, right?

Thanks so much for being my study buddy this semester! Let's ace this class!

After: Optimized Project Instructions (~130-150 tokens, 85% savings!)

Now here is what the optimized version would look like after applying the prompt I showed above:

Organic Chemistry II tutor for university student. Visual learner.

Core approach:
- Break concepts into steps with everyday analogies
- Show electron movement with curved arrow notation
- Connect to Orgo I fundamentals when needed
- Emphasize "why" over memorization (electrons seek stability, attracted to positive charge)

Mechanism explanations must include: type, electron arrows, intermediates,
driving force, stereochemistry, common mistakes.

Practice problem mode: Problem → wait for my attempt → feedback → solution → similar problems.

Quiz mode: One question at a time, no hints unless asked, track weak areas, summarize at end.

Course topics and textbook reference: See orgo2-syllabus.md in project files.

The prompt also created an orgo2-syllabus.md file with the following content to be added to project files:

# Organic Chemistry II - Course Topics

## Units
1. Alcohols, ethers, epoxides
2. Aldehydes and ketones (nucleophilic addition)
3. Carboxylic acids and derivatives (acyl substitution)
4. Enols and enolates (alpha-carbon chemistry)
5. Conjugated systems and aromaticity
6. Aromatic substitution (electrophilic/nucleophilic)
7. Amines and nitrogen compounds
8. Carbonyl condensations (aldol, Claisen)
9. Retrosynthesis and multi-step synthesis

## Exam Format
- 20% multiple choice (conceptual)
- 30% short answer (mechanisms, predict product)
- 50% long answer (synthesis) ← primary focus

## Textbook
Klein, Organic Chemistry, 4th edition

## Question Types to Practice
- Predict the product
- Propose a mechanism
- Synthesis (A → B)
- Retrosynthesis (work backwards)
- Ranking (acidity, reactivity, etc.)
- Conceptual reasoning

Moving Chats into Projects

Now if you have played around with Claude enough, you probably know that you can move a regular chat that was not initiated within a project, into a project. It is almost like moving a file into a folder.

There are many reasons why you may want to do this, perhaps for organization purposes or simply wanting future messages to follow project guidelines.

This is what likely happens when you do this:

Before the move:
Standalone Conversation:
┌─────────────────────────────────────────────────────┐
│ [System Prompt] [Your messages + Claude responses]  │
└─────────────────────────────────────────────────────┘

After moving into a project:
Project Conversation:
┌───────────────────────────────────────────────────────────────────────────────┐
│ [System Prompt] [Project Instructions] [Your messages + Claude responses]     │
│                                        + access to project files via search   │
└───────────────────────────────────────────────────────────────────────────────┘

This means that your already existing conversation history within that chat is preserved in the context window. However, the project instructions for the project you moved the chat into will now be injected into context for all future messages in that conversation. The project files within that project will also be searchable via the project_knowledge_search tool for future messages.

Conclusion

This post turned out longer than I initially anticipated but I hope you found its contents useful.

As always, thanks for reading!