Chunking Strategies — Feature, Layer, Module

Capsule description

When your project has 100K+ lines, it doesn't fit in a Claude Code session. You need to divide the work into chunks that do fit. But how do you divide? It's not arbitrary — there are three proven strategies, each optimized for a different type of task.

Chunking by feature groups all the files of a feature (route, service, model, test). Chunking by layer groups all the files of a layer (all the services, all the models). Chunking by module groups a complete directory. Each strategy has advantages and the choice depends on your task.

The 3 Strategies

Strategy 1: By Feature (Vertical)

You take all the files related to ONE feature, from all the layers:

Feature: "User Management"
├── src/api/routes/users.py        (route)
├── src/services/user_service.py   (logic)
├── src/models/user.py             (model)
├── src/repositories/user_repo.py  (data access)
└── tests/test_user_service.py     (test)

# 5 files, ~500-1000 lines total
# Claude Code has COMPLETE context of this feature

When to use: Refactoring a specific feature. Adding functionality to a feature. Bug fix in a feature.

Advantage: Claude Code sees the complete flow end-to-end. Disadvantage: It doesn't see how this feature relates to other features.

Strategy 2: By Layer (Horizontal)

You take all the files of ONE layer:

Layer: "Services"
├── src/services/user_service.py
├── src/services/order_service.py
├── src/services/payment_service.py
├── src/services/email_service.py
└── src/services/notification_service.py

# 5 files, ~1000-2000 lines total
# Claude Code sees ALL the services and their patterns

When to use: Ensuring consistency between services. Refactoring a pattern that crosses all the services. Adding a new service that follows the existing pattern.

Advantage: Claude Code sees patterns and consistency. Disadvantage: It doesn't see the layers that connect with the services.

Strategy 3: By Module (Directory)

You take a whole directory/module:

Module: "src/payments/"
├── src/payments/__init__.py
├── src/payments/processor.py
├── src/payments/validator.py
├── src/payments/models.py
├── src/payments/stripe_client.py
├── src/payments/paypal_client.py
└── src/payments/exceptions.py

# 7 files, ~800-1500 lines total
# Claude Code sees the WHOLE module internally

When to use: Internal refactoring of a module. Understanding how a module works. Migration of a module.

Advantage: A complete view of the module with all its internal pieces. Disadvantage: It doesn't see how the module connects with the rest.

When to Use Each Strategy

Implementing Chunking with Claude Code

Approach 1: Explicit @-references

# Chunking by feature:
> "Read these files to understand the orders feature:
   @src/api/routes/orders.py
   @src/services/order_service.py
   @src/models/order.py
   @tests/test_order_service.py
   
   Then, refactor order_service to separate
   the validation from the calculation."

Approach 2: Directory as a chunk

# Chunking by module:
> "Read the whole src/payments/ directory and analyze
   the internal architecture. What patterns does it use?
   Are there anti-patterns?"

Approach 3: Multi-session with handoff

# Session 1: Analyze (chunking by module)
> "Analyze src/payments/ and generate a CLAUDE.md section
   that describes the payments architecture."

# Session 2: Modify (chunking by feature)
> "Using the CLAUDE.md context about payments,
   refactor the checkout flow:
   @src/api/routes/checkout.py
   @src/services/payment_service.py"

Combining Strategies

For complex tasks, combine strategies:

# Phase 1: Understand (Layer)
# Load all the services to see patterns
> "Read all the services in src/services/ and identify
   the dominant error handling pattern"

# Phase 2: Modify (Feature)
# Load a complete feature to refactor
> "Now read the complete orders feature and apply
   the error handling pattern we identified"

# Phase 3: Verify (Layer)
# Load the services again to confirm consistency
> "Verify that order_service now follows the same
   error handling pattern as the other services"

Connection with the Project

In the Module Project (capsule 05), you design a chunking strategy for a project of 100K+ lines. You define which chunks to use for common tasks: bug fix, refactoring, new feature.

Troubleshooting

Problem 1: I don't know which strategy to choose

Solution: Ask yourself: "Does my task cross layers vertically (feature) or horizontally (layer)?" If you need to see the complete flow of a feature → feature. If you need to see consistency → layer. If you need to see a module internally → module.

Problem 2: My chunk is too large

Solution: Sub-chunk. If the payments module has 5K lines, work with one sub-module at a time: first processor.py, then validator.py, etc.

Problem 3: I need context from another chunk

Solution: Include the interface (only the types/signatures) of the other chunk, not the complete implementation:

> "Read the interfaces of user_service.py (only the function
   signatures, not the implementation) to understand
   what order_service.py can call"

Exercises

Exercise 1: Choose a strategy (Easy)

For each task, choose the right chunking strategy:

1. Add logging to all the endpoints
2. Fix bug in the registration flow
3. Internally restructure the notifications module
4. Ensure all the models have type hints

Exercise 2: Design chunks for a project (Medium)

Your project has: src/api/ (12 routes), src/services/ (8 services), src/models/ (10 models), src/utils/ (15 utils). Design chunks for the task "refactor the payment system".

# Chunk 1 (Feature - payments):
src/api/routes/payments.py
src/services/payment_service.py
src/models/payment.py
src/models/transaction.py
tests/test_payment_service.py

# Chunk 2 (Module - integrations):
src/integrations/stripe_client.py
src/integrations/paypal_client.py

# Chunk 3 (Interfaces - for context):
src/services/order_service.py (signatures only)
src/services/user_service.py (signatures only)

Common Errors in Chunking

Error 1: Choosing feature when you should choose layer (or vice versa)

Symptom: You chunked by feature to "standardize error handling in services". But you only saw 1 service — you can't see consistency with the others. Work with a mediocre result.

Why it happens: The instinct is to "include the complete flow of the feature". But the task was about consistency between services — that's layer chunking, not feature.

How to fix: Before chunking, ask yourself: does the task cross vertically (one feature end-to-end) or horizontally (all the services, all the models)? Vertical → feature. Horizontal → layer.

Error 2: Chunks that are too large "so as not to lose context"

Symptom: Your chunk has 30 files "just in case". Claude Code degrades and can't see the detail of any of them.

Why it happens: You confuse "having everything loaded" with "having everything present". Context has attention limits, not just capacity limits. 30 files compete for the model's attention.

How to fix: Sweet spot: 5-10 files per chunk. If you need more, sub-chunk or use CLAUDE.md for persistent context that doesn't consume the dynamic context window.

Error 3: Not having an "interface chunk" for tasks that cross modules

Symptom: You work in payment_service.py which calls email_service.py. You didn't include email_service. Claude Code invents parameters because it can't see the real signature.

Why it happens: You thought "I only edit payment_service, I don't need email". But you need the interfaces of the services you call, even if you don't modify them.

How to fix: Include the signatures (not the implementation) of the consumed modules. Capsule 04 (CLAUDE.md) shows how to persist those signatures so you don't repeat them.

Error 4: Chunking arbitrarily without a pattern

Symptom: Every time you work on something, you decide ad-hoc which files to load. Inconsistent result.

Why it happens: You don't have pre-thought-out chunk templates for your frequent tasks.

How to fix: Define in CLAUDE.md (or in a separate file) pre-built chunks for your typical tasks: "for a bug fix in orders → these 4 files", "for a new endpoint → these 6 files". It's what the module project (capsule 05) asks you to produce.

Error 5: Forgetting the chunk's tests

Symptom: You modified 3 payment files but forgot to load test_payments.py. Claude Code modifies without knowing what cases you have to preserve.

Why it happens: Tests "aren't production code", they feel secondary. But they're the behavior contract.

How to fix: In any chunk, always include the tests of the modified code. It's the only way for Claude Code to know what behavior to preserve.

Summary

• 3 chunking strategies: feature (vertical), layer (horizontal), module (directory)
• Feature for end-to-end flows. Layer for consistency. Module for internal pieces
• Combine strategies for complex tasks: analyze (layer) → modify (feature) → verify (layer)
• Sub-chunking when a chunk is too large
• Interfaces as a bridge between chunks: include signatures, not implementations
• Pre-thought-out templates for frequent tasks avoid ad-hoc decisions
• Tests always go in the chunk — they're the behavior contract

Next capsule: CLAUDE.md and Project Context Files — the tool that makes each session productive.

Recap: How Do You Choose in Practice?

When you're facing a real task, follow this decision flow:

1. What task am I going to do?
   → If "fix bug in feature X" → FEATURE chunking
   → If "standardize/consistency between similar ones" → LAYER chunking
   → If "internal refactor of a module" → MODULE chunking

2. How many files does my chunk touch?
   → 5-10 files: optimal
   → 11-20: consider sub-chunking
   → 21+: definitely sub-chunk

3. Do I need interfaces from other modules?
   → Yes: include only signatures/types, not implementation
   → No: a self-contained chunk

4. Do I have the tests of the code I'm going to touch?
   → Yes: include them in the chunk
   → No: that's your step 0 before modifying

If you follow this flow, the chunks are consistent between sessions and between team members. Without it, the chunking strategy depends on the mood of the day.

Additional Resources

1. Claude Code - Project Files - CLAUDE.md and configuration
2. Modular Architecture - Fundamentals of modularity
3. Feature Slicing - Vertical Slice Architecture - Feature-based architecture
4. Clean Architecture Layers - Architectural layers

Module 6, Capsule 03 — Refactoring & Legacy Code with Claude Code Guide