Module 6: Context Management for Large Projects

Module Project: Context Strategy for a 100K+ Project

Next →

Module Project: Context Strategy for a 100K+ Project

Project description

This project closes Phase 2 of the guide. You're going to design a complete context strategy for a large open-source project (100K+ lines): create a CLAUDE.md, define chunking strategies for common tasks, and execute a real modification using your strategy.

It's not a theoretical exercise — you produce artifacts that make the project workable with Claude Code. Without these artifacts, a 100K+ line project is practically unmanageable. With them, you can work effectively in any part of the codebase.

Project Objective

Design and implement a complete context management strategy for a large project.

By completing it:

  • ✅ You'll have created a professional CLAUDE.md for a large project
  • ✅ You'll have defined chunking strategies for 3 common tasks
  • ✅ You'll have created @-reference templates for daily work
  • ✅ You'll have executed a real modification using your strategy
  • ✅ You'll have verified that the strategy works in practice

Technical Specifications

Suggested Project

Choose an open-source Python project of 100K+ lines:

ProjectLinesWhy it's good
Django~300KA complete web framework, many modules
FastAPI~50KSmaller but with depth
requests~30KAlthough smaller, excellent for practice
flask~40KA manageable size with good structure
httpx~15KThe most accessible to start

Recommendation: For your first time, use FastAPI or httpx. For a real challenge, use Django.

Setup

git clone [chosen project]
cd [project]
claude

Deliverables

1. CLAUDE.md (The main deliverable)

Create a complete CLAUDE.md for the project. It should include:

  • Architecture overview (3-5 paragraphs)
  • Directory structure with purpose
  • Key conventions (naming, patterns, error handling)
  • Module map (main modules with dependencies)
  • Common tasks (how to contribute, how to test)
  • Do NOT list

Criterion: Another developer can open the project for the first time with your CLAUDE.md and be productive immediately.

2. Chunking Strategy Document

Define chunking strategies for 3 common tasks:

# Chunking Strategies

## Task 1: Fix bug in [module]
Strategy: Feature
Files to include:
  - [route file]
  - [service file]
  - [model file]
  - [test file]
Estimated tokens: ~XK

## Task 2: Add new feature to [module]
Strategy: Feature + Interface reference
Files to include:
  - [Similar feature as reference]
  - [New files to create]
  - [Interfaces of dependent modules]
Estimated tokens: ~XK

## Task 3: Refactor [module] for consistency
Strategy: Layer
Files to include:
  - [All files of the same layer]
Estimated tokens: ~XK

3. @-Reference Templates

Pre-built references for frequent tasks:

# @-Reference Templates

## To modify an endpoint:
@src/api/routes/[module].py
@src/services/[module]_service.py
@tests/test_[module].py

## To add a model:
@src/models/[existing_model].py (reference)
@src/migrations/ (last migration as reference)

## For debugging:
@src/[file_with_bug].py
@tests/test_[file].py
@src/config/settings.py

4. Proof of Concept (Real Modification)

Execute ONE real modification to the project using your context strategy:

  • It can be: fix a typo, add a test, improve a docstring
  • Document which chunks you used and why
  • Verify that the tests pass

Success Criteria

  • ✅ CLAUDE.md has 100-200 lines of useful and precise content
  • ✅ Chunking strategies defined for 3 tasks
  • ✅ @-Reference templates for 3 scenarios
  • ✅ Proof of concept executed successfully
  • ✅ Documentation shows that the strategy works

Evaluation Rubric (100 points)

CLAUDE.md (40 points)

  • (10 pts) Accurate and useful architecture overview
  • (10 pts) Complete directory structure
  • (10 pts) Conventions based on real observation of the code
  • (10 pts) Module map with correct dependencies

Chunking Strategies (25 points)

  • (8 pts) 3 strategies defined with justification
  • (8 pts) Files listed for each strategy
  • (9 pts) Reasonable token estimates

Templates + Proof of Concept (25 points)

  • (10 pts) Practical and reusable @-reference templates
  • (10 pts) Proof of concept executed and documented
  • (5 pts) Tests pass after the modification

General Quality (10 points)

  • (5 pts) Everything based on real observation, not assumptions
  • (5 pts) Clear and reusable documentation

Extra Credit (+10 points)

  • (+3 pts) Hierarchical CLAUDE.md (global + per module)
  • (+3 pts) Comparison: with vs without CLAUDE.md (measured time)
  • (+2 pts) Chunking strategy for a complete migration
  • (+2 pts) Strategy for onboarding a new member

Common Errors

Error 1: CLAUDE.md based on assumptions

Don't write "it probably uses MVC." Read the code and confirm. If you're not sure, use Explore to verify before documenting.

Error 2: Chunking that's too large

If a chunk has 50 files, it's too much. 5-10 files per chunk is the sweet spot.

Error 3: Not testing the strategy

A CLAUDE.md you don't test is theoretical documentation. The proof of concept confirms it works.

Error 4: Generic templates

@src/[file].py isn't a useful template. @src/api/routes/users.py @src/services/user_service.py @tests/test_user.py is.

Resources for the Project

  1. Claude Code - CLAUDE.md - Official documentation
  2. Django Source - For a challenge with a large project
  3. FastAPI Source - Medium size, good structure
  4. httpx Source - Accessible size
  5. Token Counter - To estimate tokens
  6. Anthropic Token Counting API - Anthropic's official counting

What to Do if You Get Stuck?

If CLAUDE.md feels generic and doesn't add value:
  → Read 5 random files and compare with your CLAUDE.md
  → Do the conventions you documented REALLY show up in the code?
  → If not, rewrite — without real observation, it's useless

If the chunks feel arbitrary:
  → Define the TASK first, then the chunk
  → "Refactor payment_service" → chunk = 4-5 specific files
  → If you can't name the task with verb + object, it's not a task

If the proof of concept "doesn't feel real":
  → Choose something smaller (a typo, a docstring) but CONCRETE
  → Better a small PoC that passes tests than a large one without verification

If the token estimate diverges a lot from reality:
  → Use the Anthropic token counting API to validate
  → Heuristics are approximations — correct your estimates with data

Evidence of Success (Self-Verification)

Before declaring the project complete, validate that you meet these checkpoints:

CLAUDE.md

  • ✅ Each section is backed by real observation of the code, not assumptions
  • ✅ A developer who opens the project for the first time can be productive in under 30 minutes by reading it
  • ✅ The documented conventions show up in at least 5 files of the project

Chunking Strategies

  • ✅ The 3 strategies are justified with the specific task they solve
  • ✅ The estimated token count for each chunk is within 30% of the real one (measured)
  • ✅ Each strategy has a recognizable use case, not a generic one

Templates

  • ✅ The @-references are real project paths, not placeholders
  • ✅ Each template solves a frequent task (not an invented one)

Proof of Concept

  • ✅ The modification is real, committed, and tests pass
  • ✅ You documented which chunks you used and why
  • ✅ If the project has CI, the CI is green

If the 11 points are in place, the deliverable is portfolio-worthy and demonstrates professional context management.

Connection with the Next Module

This project closes Phase 2: Refactoring. Everything that follows in Phase 3 (Modules 7-8) uses the context management techniques you designed here.

Module 7: Modernize Legacy Code works with legacy code that is, by definition, hard to navigate. Your CLAUDE.md and chunking strategies are essential tools for doing that work effectively.

Module 8: Capstone Project applies context management to the real legacy project — without the techniques you designed here, the capstone project is executable only on small codebases.

How Your Work Will Look in a Month

The value of this project isn't fully seen on the day you deliver it. It's seen when:

  • Day 1: you finish the project, you have CLAUDE.md + chunking strategies + templates
  • Week 1: every time you work on the project, the first sessions are productive immediately — you don't repeat onboarding every time
  • Month 1: a colleague joins the project, reads your CLAUDE.md, and becomes productive in a day (vs a week without it)
  • Month 3: the chunks you designed are used automatically; you no longer decide "which files to load", you apply the template
  • Month 6: the CLAUDE.md has evolved with the project. Your first version is still the skeleton.

The deliverable is a seed, not a final product. A good CLAUDE.md grows with the project. A bad CLAUDE.md is ignored after 2 weeks. The difference is that the good one is based on real observation (not assumptions) and solves concrete workflow pain points.

If your CLAUDE.md meets the 3 criteria from the "Evidence of Success" section (based on observation, productivity in 30 min, verifiable conventions), you have a seed that's going to grow. If not, it's paperwork that will be ignored.

Maintaining CLAUDE.md (For After the Project)

What you deliver in this project is a version 1.0. For it to stay useful:

  • When the project adopts a new pattern: update CLAUDE.md in the same PR. Not "later", in the same PR that introduces the pattern.
  • When a pattern is deprecated: mark it in CLAUDE.md as "deprecated, don't use in new code" before starting to remove it.
  • When a new member joins the team: watch what questions they ask. If the question should be answered in CLAUDE.md and isn't, add it.
  • When you refactor the architecture: CLAUDE.md is the first file you update, not the last.

Mnemonic rule: "If you're not maintaining it, you're deprecating it". A 6-month-old CLAUDE.md without updates probably lies about the current state of the project. An actively maintained CLAUDE.md is the highest productivity asset a project can have for AI collaboration.

This practice connects directly with Module 8 (Capstone Project), where the final documentation of the migrated project includes an updated CLAUDE.md for the modernized codebase.

Anti-pattern: CLAUDE.md as "the whole project in one file"

Some developers treat CLAUDE.md as a substitute for the complete project documentation. It's the opposite of what it should be:

  • ✅ Ideal CLAUDE.md: 100-300 lines, high-level conventions and rules, oriented to "what Claude Code needs to know to be productive here"
  • ❌ Poorly-made CLAUDE.md: 2000+ lines, repeats the README, includes a changelog, copies library documentation

If your CLAUDE.md grows beyond 500 lines, it's probably loading documentation that should live elsewhere. Quality over length — a well-curated 200-line CLAUDE.md beats a 2000-line unfocused one.

← PreviousCLAUDE.md and Project Context FilesNext →Module 7: Modernize Legacy Code