Chunking Strategies — Feature, Layer, Module

Descripción de la cápsula

Cuando tu proyecto tiene 100K+ líneas, no cabe en una sesión de Claude Code. Necesitas dividir el trabajo en chunks que sí caben. Pero ¿cómo divides? No es arbitrario — hay tres estrategias probadas, cada una optimizada para un tipo diferente de tarea.

Chunking por feature agrupa todos los archivos de un feature (ruta, servicio, modelo, test). Chunking por layer agrupa todos los archivos de una capa (todos los services, todos los models). Chunking por module agrupa un directorio completo. Cada strategy tiene ventajas y la elección depende de tu tarea.

Las 3 Strategies

Strategy 1: Por Feature (Vertical)

Tomas todos los archivos relacionados con UN feature, de todas las capas:

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 archivos, ~500-1000 líneas total
# Claude Code tiene contexto COMPLETO de este feature

Cuándo usar: Refactoring de un feature específico. Agregar funcionalidad a un feature. Bug fix en un feature.

Ventaja: Claude Code ve el flujo completo de punta a punta. Desventaja: No ve cómo este feature se relaciona con otros features.

Strategy 2: Por Layer (Horizontal)

Tomas todos los archivos de UNA capa:

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 archivos, ~1000-2000 líneas total
# Claude Code ve TODOS los services y sus patterns

Cuándo usar: Asegurar consistencia entre servicios. Refactoring de un pattern que cruza todos los services. Agregar un nuevo service que siga el patrón existente.

Ventaja: Claude Code ve patterns y consistency. Desventaja: No ve las capas que conectan con los services.

Strategy 3: Por Module (Directorio)

Tomas todo un directorio/módulo:

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 archivos, ~800-1500 líneas total
# Claude Code ve TODO el módulo internamente

Cuándo usar: Refactoring interno de un módulo. Entender cómo funciona un módulo. Migración de un módulo.

Ventaja: Visión completa del módulo con todas sus piezas internas. Desventaja: No ve cómo el módulo se conecta con el resto.

Cuándo Usar Cada Strategy

Implementando Chunking con Claude Code

Approach 1: @-references explícitos

# Chunking por feature:
> "Lee estos archivos para entender el feature de orders:
   @src/api/routes/orders.py
   @src/services/order_service.py
   @src/models/order.py
   @tests/test_order_service.py
   
   Después, refactoriza order_service para separar
   la validación del cálculo."

Approach 2: Directorio como chunk

# Chunking por module:
> "Lee todo el directorio src/payments/ y analiza
   la arquitectura interna. ¿Qué patterns usa?
   ¿Hay anti-patterns?"

Approach 3: Multi-sesión con handoff

# Sesión 1: Analizar (chunking por module)
> "Analiza src/payments/ y genera un CLAUDE.md section
   que describa la arquitectura de pagos."

# Sesión 2: Modificar (chunking por feature)
> "Usando el contexto de CLAUDE.md sobre pagos,
   refactoriza el flujo de checkout:
   @src/api/routes/checkout.py
   @src/services/payment_service.py"

Combinando Strategies

Para tareas complejas, combina strategies:

# Fase 1: Entender (Layer)
# Carga todos los services para ver patterns
> "Lee todos los services en src/services/ e identifica
   el patrón de error handling dominante"

# Fase 2: Modificar (Feature)
# Carga un feature completo para refactorizar
> "Ahora lee el feature de orders completo y aplica
   el patrón de error handling que identificamos"

# Fase 3: Verificar (Layer)
# Carga los services otra vez para confirmar consistencia
> "Verifica que order_service ahora sigue el mismo
   patrón de error handling que los otros services"

Conexión con Proyecto

En el Proyecto del Módulo (cápsula 05), diseñas una chunking strategy para un proyecto de 100K+ líneas. Defines qué chunks usar para tareas comunes: bug fix, refactoring, nueva feature.

Troubleshooting

Problema 1: No sé qué strategy elegir

Solución: Pregúntate: "¿Mi tarea cruza capas verticalmente (feature) o horizontalmente (layer)?" Si necesitas ver el flujo completo de un feature → feature. Si necesitas ver consistencia → layer. Si necesitas ver un módulo internamente → module.

Problema 2: Mi chunk es demasiado grande

Solución: Sub-chunk. Si el módulo de pagos tiene 5K líneas, trabaja con un sub-módulo a la vez: primero processor.py, luego validator.py, etc.

Problema 3: Necesito contexto de otro chunk

Solución: Incluye la interfaz (solo los types/signatures) del otro chunk, no la implementación completa:

> "Lee las interfaces de user_service.py (solo las firmas
   de funciones, no la implementación) para entender
   qué puede llamar order_service.py"

Ejercicios

Ejercicio 1: Elegir strategy (Fácil)

Para cada tarea, elige la chunking strategy correcta:

1. Agregar logging a todos los endpoints
2. Fix bug en el flujo de registro
3. Reestructurar internamente el módulo de notificaciones
4. Asegurar que todos los models tienen type hints

Ejercicio 2: Diseñar chunks para un proyecto (Medio)

Tu proyecto tiene: src/api/ (12 rutas), src/services/ (8 services), src/models/ (10 models), src/utils/ (15 utils). Diseña chunks para la tarea "refactorizar el sistema de pagos".

# Chunk 1 (Feature - pagos):
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 - integraciones):
src/integrations/stripe_client.py
src/integrations/paypal_client.py

# Chunk 3 (Interfaces - para contexto):
src/services/order_service.py (solo firmas)
src/services/user_service.py (solo firmas)

Errores Comunes en Chunking

Error 1: Elegir feature cuando deberías elegir layer (o viceversa)

Síntoma: Chunkeaste por feature para "estandarizar error handling en services". Pero solo viste 1 service — no puedes ver consistencia con los demás. Trabajo con resultado mediocre.

Por qué pasa: El instinto es "incluir el flujo completo del feature". Pero la tarea era de consistencia entre services — eso es layer chunking, no feature.

Cómo corregir: Antes de chunkear, pregúntate: ¿la tarea cruza vertical (un feature de punta a punta) o horizontal (todos los services, todos los models)? Vertical → feature. Horizontal → layer.

Error 2: Chunks demasiado grandes "para no perder contexto"

Síntoma: Tu chunk tiene 30 archivos "por si acaso". Claude Code degrada y no logra ver el detalle de ninguno.

Por qué pasa: Confundes "tener todo cargado" con "tener todo presente". El context tiene límites de atención, no solo de capacidad. 30 archivos compiten por la atención del modelo.

Cómo corregir: Sweet spot: 5-10 archivos por chunk. Si necesitas más, sub-chunkea o usa CLAUDE.md para contexto persistente que no consume context window dinámico.

Error 3: No tener un "interface chunk" para tareas que cruzan módulos

Síntoma: Trabajas en payment_service.py que llama a email_service.py. No incluiste email_service. Claude Code inventa parámetros porque no puede ver la firma real.

Por qué pasa: Pensaste "solo edito payment_service, no necesito email". Pero necesitas las interfaces de los servicios que llamas, aunque no los modifiques.

Cómo corregir: Incluye firmas (no implementación) de los módulos consumidos. La cápsula 04 (CLAUDE.md) muestra cómo persistir esas firmas para no repetirlas.

Error 4: Chunkear arbitrariamente sin un patrón

Síntoma: Cada vez que trabajas en algo, decides ad-hoc qué archivos cargar. Resultado inconsistente.

Por qué pasa: No tienes templates pre-pensados de chunks para tus tareas frecuentes.

Cómo corregir: Define en CLAUDE.md (o en un archivo aparte) chunks pre-construidos para tus tareas típicas: "para fix bug en orders → estos 4 archivos", "para nuevo endpoint → estos 6 archivos". Es lo que el proyecto del módulo (cápsula 05) te pide producir.

Error 5: Olvidar tests del chunk

Síntoma: Modificaste 3 archivos de pagos pero olvidaste cargar test_payments.py. Claude Code modifica sin saber qué casos tienes que preservar.

Por qué pasa: Tests "no son código de producción", se sienten secundarios. Pero son el contrato del comportamiento.

Cómo corregir: En cualquier chunk, siempre incluye los tests del código modificado. Es la única forma de que Claude Code sepa qué comportamiento preservar.

Resumen

• 3 chunking strategies: feature (vertical), layer (horizontal), module (directorio)
• Feature para flujos end-to-end. Layer para consistencia. Module para piezas internas
• Combinar strategies para tareas complejas: analizar (layer) → modificar (feature) → verificar (layer)
• Sub-chunking cuando un chunk es demasiado grande
• Interfaces como puente entre chunks: incluye firmas, no implementaciones
• Templates pre-pensados para tareas frecuentes evitan decisiones ad-hoc
• Tests siempre van en el chunk — son el contrato del comportamiento

Próxima cápsula: CLAUDE.md y Project Context Files — la herramienta que hace cada sesión productiva.

Recapitulación: ¿Cómo Eliges en la Práctica?

Cuando estés frente a una tarea real, sigue este flujo de decisión:

1. ¿Qué tarea voy a hacer?
   → Si "fix bug en feature X" → FEATURE chunking
   → Si "estandarizar/consistencia entre similares" → LAYER chunking
   → Si "refactor interno de un módulo" → MODULE chunking

2. ¿Cuántos archivos toca mi chunk?
   → 5-10 archivos: óptimo
   → 11-20: considera sub-chunkear
   → 21+: definitivamente sub-chunkea

3. ¿Necesito interfaces de otros módulos?
   → Sí: incluye solo firmas/types, no implementación
   → No: chunk autocontenido

4. ¿Tengo los tests del código que voy a tocar?
   → Sí: incluye en el chunk
   → No: ese es tu paso 0 antes de modificar

Si sigues este flujo, los chunks son consistentes entre sesiones y entre miembros del equipo. Sin él, la chunking strategy depende del humor del día.

Recursos Adicionales

1. Claude Code - Project Files - CLAUDE.md y configuración
2. Modular Architecture - Fundamentos de modularidad
3. Feature Slicing - Vertical Slice Architecture - Arquitectura por features
4. Clean Architecture Layers - Capas arquitecturales