Claude Code and the context window on bigger projects

My website is now close to a thousand files, so I no longer ask Claude Code to "fix the page." I give each session one task and name the files involved, as similar components now exist in several folders.

Context Management: Fresh Sessions

My first rule is to start a fresh session for each new task.

A new session loads the project instructions without the assumptions from the previous task. I use /clear when I want to reset the conversation in the same terminal. If the task must continue, /compact keeps a shorter version of the context. I choose a fresh session when the work changes, because old context can point Claude toward the wrong files or decisions.

Before deciding which of those I need, I run /context. It shows what is actually filling the window, and the answer is often one large file read rather than the conversation itself, which is a different problem with a different fix. In Claude Code v2.1.221 or later, /autocompact sets how many tokens to reserve before automatic compaction.

Be Specific About Files

With five files, "fix the header" probably means one thing. With fifty files, it could mean any of ten different headers.

I name the file and the visible problem:

In pages/contact.html, fix the header spacing. The heading is
too close to the navigation bar.

Not:

Fix the header spacing.

Claude can search the project, but naming the likely file gives it a better starting point and avoids reading unrelated code.

Reusable Skills Pay Off at Scale

I turn repeated project checks into skills, as I do not want the review criteria to change between sessions. For example:

• review runs the same code-review checklist
• check-links checks navigation and links
• mobile checks each page at mobile width

Put a repeated checklist in a project skill so the team can run the same review each time. Existing .claude/commands files still work, but new reusable workflows belong in .claude/skills/<name>/SKILL.md.

Break Big Tasks into Steps

"Add a blog section to the website" is a big ask. It involves creating templates, styling, navigation updates, content, and possibly restructuring your project.

Break it into pieces:

Step 1: Create a blog listing page at blog/index.html that shows
a list of post titles and dates. Use the same style as the rest
of the site. No actual posts yet, just the listing page structure.

Review the first result before asking for the next part. Then continue with the second task:

Step 2: Create a template for individual blog posts at
blog/post-template.html. It should have the post title, date,
content area, and a back link to the blog listing.

Review that result, then continue with the next small task.

Each step is small enough to review thoroughly. If something goes wrong, you know exactly where it happened. If you need to undo, you only lose one step, not the whole thing.

Agents for Big Analysis

When you need to analyze or check something across many files, tell Claude to use parallel agents (Module 2, Chapter 7):

Use parallel agents to check all HTML pages for:
- Missing page titles
- Missing meta descriptions
- Broken image paths
- Links that don't go anywhere

Work through all files and give me one combined report.

Use separate subagents for independent checks, then combine their findings in the main session. They can run concurrently, but each uses its own context and increases token usage. Do not split work that needs the same files or a shared decision.

For a large change that can be split into independent units, /batch can plan 5 to 30 units and run each in its own Git worktree. It requires Git and gives each unit its own pull request, so I would not use it to rename one class. A normal search-and-replace is enough for that.

If a project grows past one repository, or into a monorepo, Anthropic's guide for large codebases covers how to lay out instructions and rules so the right ones load in the right place.

CLAUDE.md Grows With Your Project

Small project CLAUDE.md:

Personal portfolio website. Dark theme. Four pages.

Bigger project CLAUDE.md:

# Portfolio & Blog

## Structure
- pages/ - Static pages (home, about, projects, contact)
- blog/ - Blog listing and posts
- css/ - Stylesheets (main.css, blog.css)
- images/ - All images
- js/ - JavaScript (if any)

## Design
- Dark theme (#0f172a background)
- Accent: #38bdf8
- Font: Inter
- Max width: 900px

## Important
- Blog posts use blog/post-template.html as the base
- Navigation is consistent across all pages
- New pages must include meta title and description
- All images go in images/ with descriptive names

Update CLAUDE.md when the structure or project rules change, so Claude starts each session with the current information.

Signs Your Project Needs Structure Cleanup

I update the project structure when the same confusion appears more than once:

• Claude edits the wrong file because similar files have unclear names.
• I cannot find a file without searching several folders.
• The same style is defined in several places.
• CLAUDE.md no longer matches the current structure.

At that point I rename, move, or consolidate the source before adding more instructions.

When you notice these, ask Claude to help:

Audit the project structure. Are there files in the wrong places?
Duplicate styles? Anything that would confuse someone seeing
this project for the first time? Suggest improvements.

How I Work on a Big Project

I also break every big feature into small tasks. "Add a tools section" becomes: create the model, create the controller, create the listing view, create the detail view, add the routes, update navigation. Each task gets its own session.

I no longer try to cover the whole project in one session. One task per session works, provided the project instructions are current.

Frequently Asked Questions

How do I see what is filling Claude Code's context window?

Run /context. It shows what is taking up the window. Often it is one large file, not the conversation, so the fix is different.

What is the difference between /clear and /compact?

/clear gives you an empty context and saves the previous conversation so you can resume it later. Project instructions load again. /compact keeps a shorter version of the current context, which is what you want when the same long task has to continue. I use /clear when the work changes.

Does Claude Code read every file in my project?

No. It searches and reads the files the current task needs, which is why naming the likely file gives it a better starting point than a general description of the problem.

How do I stop Claude Code from editing the wrong file?

Name the file and the visible problem in the same sentence. On a project with fifty files, "in pages/contact.html, fix the header spacing, the heading is too close to the navigation bar" leaves far less room for interpretation than "fix the header spacing."

When are subagents worth using?

Use them for independent checks that can run at the same time, then combine the findings in the main session. Each subagent carries its own context and adds token usage, so do not split work that needs the same files or a shared decision.

Sources

• Commands, Anthropic. Documents /context, /clear, /compact, /autocompact, and the Git, worktree, and unit requirements of /batch.
• Explore the context window, Anthropic. Explains what enters context, automatic compaction, and what survives compaction.
• Create custom subagents, Anthropic. Supports separate subagent context windows and the return of summarized results to the main session.
• Set up Claude Code in a monorepo or large codebase, Anthropic. Supports structuring project instructions and rules for large repositories and monorepos.