Módulo 6: Context Management para Proyectos Grandes

Proyecto del Módulo: Strategy de Context para Proyecto 100K+

Siguiente →

Proyecto del Módulo: Strategy de Context para Proyecto 100K+

Descripción del proyecto

Este proyecto cierra Phase 2 de la guía. Vas a diseñar una context strategy completa para un proyecto open-source grande (100K+ líneas): crear un CLAUDE.md, definir chunking strategies para tareas comunes, y ejecutar una modificación real usando tu strategy.

No es un ejercicio teórico — produces artefactos que hacen al proyecto trabajable con Claude Code. Sin estos artefactos, un proyecto de 100K+ líneas es prácticamente inmanejable. Con ellos, puedes trabajar efectivamente en cualquier parte del codebase.

Objetivo del Proyecto

Diseñar e implementar una context management strategy completa para un proyecto grande.

Al completar:

  • ✅ Habrás creado un CLAUDE.md profesional para un proyecto grande
  • ✅ Habrás definido chunking strategies para 3 tareas comunes
  • ✅ Habrás creado templates de @-references para trabajo diario
  • ✅ Habrás ejecutado una modificación real usando tu strategy
  • ✅ Habrás verificado que la strategy funciona en la práctica

Especificaciones Técnicas

Proyecto Sugerido

Elige un proyecto open-source Python de 100K+ líneas:

ProyectoLíneasPor qué es bueno
Django~300KFramework web completo, muchos módulos
FastAPI~50KMás pequeño pero con profundidad
requests~30KAunque más pequeño, excelente para practicar
flask~40KTamaño manejable con buena estructura
httpx~15KEl más accesible para empezar

Recomendación: Para primera vez, usa FastAPI o httpx. Para un challenge real, usa Django.

Setup

git clone [proyecto elegido]
cd [proyecto]
claude

Entregables

1. CLAUDE.md (El entregable principal)

Crea un CLAUDE.md completo para el proyecto. Debe incluir:

  • Architecture overview (3-5 párrafos)
  • Directory structure con propósito
  • Key conventions (naming, patterns, error handling)
  • Module map (módulos principales con dependencies)
  • Common tasks (cómo contribuir, cómo testear)
  • Do NOT list

Criterio: Otro developer puede abrir el proyecto por primera vez con tu CLAUDE.md y ser productivo inmediatamente.

2. Chunking Strategy Document

Define chunking strategies para 3 tareas comunes:

# 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 para tareas frecuentes:

# @-Reference Templates

## Para modificar un endpoint:
@src/api/routes/[module].py
@src/services/[module]_service.py
@tests/test_[module].py

## Para agregar un model:
@src/models/[existing_model].py (referencia)
@src/migrations/ (última migración como referencia)

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

4. Proof of Concept (Modificación Real)

Ejecuta UNA modificación real al proyecto usando tu context strategy:

  • Puede ser: fix un typo, agregar un test, mejorar un docstring
  • Documenta qué chunks usaste y por qué
  • Verifica que los tests pasan

Criterios de Éxito

  • ✅ CLAUDE.md tiene 100-200 líneas de contenido útil y preciso
  • ✅ Chunking strategies definidas para 3 tareas
  • ✅ @-Reference templates para 3 escenarios
  • ✅ Proof of concept ejecutado con éxito
  • ✅ Documentación muestra que la strategy funciona

Rúbrica de Evaluación (100 puntos)

CLAUDE.md (40 puntos)

  • (10 pts) Architecture overview preciso y útil
  • (10 pts) Directory structure completo
  • (10 pts) Conventions basadas en observación real del código
  • (10 pts) Module map con dependencies correctas

Chunking Strategies (25 puntos)

  • (8 pts) 3 strategies definidas con justificación
  • (8 pts) Files listados para cada strategy
  • (9 pts) Token estimates razonables

Templates + Proof of Concept (25 puntos)

  • (10 pts) @-Reference templates prácticos y reutilizables
  • (10 pts) Proof of concept ejecutado y documentado
  • (5 pts) Tests pasan después de la modificación

Calidad General (10 puntos)

  • (5 pts) Todo basado en observación real, no suposiciones
  • (5 pts) Documentación clara y reutilizable

Extra Credit (+10 puntos)

  • (+3 pts) CLAUDE.md jerárquico (global + por módulo)
  • (+3 pts) Comparison: con vs sin CLAUDE.md (tiempo medido)
  • (+2 pts) Chunking strategy para migración completa
  • (+2 pts) Strategy para onboarding de nuevo miembro

Errores Comunes

Error 1: CLAUDE.md basado en suposiciones

No escribas "probablemente usa MVC." Lee el código y confirma. Si no estás seguro, usa Explore para verificar antes de documentar.

Error 2: Chunking demasiado grande

Si un chunk tiene 50 archivos, es demasiado. 5-10 archivos por chunk es el sweet spot.

Error 3: No probar la strategy

Un CLAUDE.md que no pruebas es documentación teórica. El proof of concept confirma que funciona.

Error 4: Templates genéricos

@src/[file].py no es un template útil. @src/api/routes/users.py @src/services/user_service.py @tests/test_user.py sí lo es.

Recursos para el Proyecto

  1. Claude Code - CLAUDE.md - Documentación oficial
  2. Django Source - Para challenge con proyecto grande
  3. FastAPI Source - Tamaño medio, buena estructura
  4. httpx Source - Tamaño accesible
  5. Token Counter - Para estimar tokens
  6. Anthropic Token Counting API - Conteo oficial de Anthropic

¿Qué Hacer si Te Atoras?

Si CLAUDE.md se siente genérico y no añade valor:
  → Lee 5 archivos al azar y compara con tu CLAUDE.md
  → ¿Las conventions que documentaste se ven REALMENTE en el código?
  → Si no, reescribe — sin observación real, no sirve

Si los chunks se sienten arbitrarios:
  → Define la TAREA primero, después el chunk
  → "Refactorizar payment_service" → chunk = 4-5 archivos específicos
  → Si no puedes nombrar la tarea con verbo + objeto, no es una tarea

Si el proof of concept "no se siente real":
  → Elige algo más pequeño (un typo, un docstring) pero CONCRETO
  → Mejor un PoC chico que pase tests, que uno grande sin verificar

Si el token estimate diverge mucho de la realidad:
  → Usa la API de token counting de Anthropic para validar
  → Heurísticas son aproximaciones — corrige tus estimados con datos

Evidencia de Éxito (Auto-Verificación)

Antes de declarar el proyecto completo, valida que cumples estos checkpoints:

CLAUDE.md

  • ✅ Cada sección está respaldada por observación real del código, no suposiciones
  • ✅ Un developer que abre el proyecto por primera vez puede ser productivo en menos de 30 minutos leyéndolo
  • ✅ Las conventions documentadas se ven en al menos 5 archivos del proyecto

Chunking Strategies

  • ✅ Las 3 strategies están justificadas con la tarea específica que resuelven
  • ✅ El conteo de tokens estimado para cada chunk está dentro del 30% del real (medido)
  • ✅ Cada strategy tiene un caso de uso reconocible, no genérico

Templates

  • ✅ Los @-references son paths reales del proyecto, no placeholders
  • ✅ Cada template resuelve una tarea frecuente (no inventada)

Proof of Concept

  • ✅ La modificación es real, está commiteada, y tests pasan
  • ✅ Documentaste qué chunks usaste y por qué
  • ✅ Si el proyecto tiene CI, el CI está verde

Si los 11 puntos están en su lugar, el entregable es portfolio-worthy y demuestra context management profesional.

Conexión con Siguiente Módulo

Este proyecto cierra Phase 2: Refactoring. Todo lo que sigue en Phase 3 (Módulos 7-8) usa las técnicas de context management que diseñaste aquí.

El Módulo 7: Modernizar Legacy Code trabaja con código legacy que es, por definición, difícil de navegar. Tu CLAUDE.md y chunking strategies son herramientas esenciales para hacer ese trabajo efectivamente.

El Módulo 8: Proyecto Integrador aplica context management al proyecto legacy real — sin las técnicas que diseñaste aquí, el proyecto integrador es ejecutable solo en codebases pequeños.

Cómo Va a Verse Tu Trabajo en un Mes

El valor de este proyecto no se ve completamente en el día que lo entregas. Se ve cuando:

  • Día 1: terminas el proyecto, tienes CLAUDE.md + chunking strategies + templates
  • Semana 1: cada vez que trabajas en el proyecto, las primeras sesiones son productivas inmediatamente — no repites onboarding cada vez
  • Mes 1: un colega llega al proyecto, lee tu CLAUDE.md, y se vuelve productivo en un día (vs una semana sin él)
  • Mes 3: los chunks que diseñaste se usan automáticamente; ya no decides "qué archivos cargar", aplicas el template
  • Mes 6: el CLAUDE.md ha evolucionado con el proyecto. Tu primera versión sigue siendo el esqueleto.

El entregable es semilla, no producto final. Un buen CLAUDE.md crece con el proyecto. Un mal CLAUDE.md se ignora después de 2 semanas. La diferencia es que el bueno está basado en observación real (no en suposiciones) y resuelve dolores concretos del workflow.

Si tu CLAUDE.md cumple los 3 criterios de la sección "Evidencia de Éxito" (basado en observación, productividad en 30 min, conventions verificables), tienes una semilla que va a crecer. Si no, es paperwork que va a ignorarse.

Mantenimiento del CLAUDE.md (Para Después del Proyecto)

Lo que entregas en este proyecto es una versión 1.0. Para que siga siendo útil:

  • Cuando el proyecto adopta un patrón nuevo: actualiza CLAUDE.md en el mismo PR. No "después", en el mismo PR que introduce el patrón.
  • Cuando un patrón se deprecia: márcalo en CLAUDE.md como "deprecated, no usar en código nuevo" antes de empezar a removerlo.
  • Cuando llega un nuevo miembro al equipo: observa qué preguntas hace. Si la pregunta debería estar respondida en CLAUDE.md y no lo está, agrégala.
  • Cuando refactorizas la arquitectura: CLAUDE.md es el primer archivo que actualizas, no el último.

Regla mnemotécnica: "Si no lo estás manteniendo, lo estás deprecando". Un CLAUDE.md de hace 6 meses sin updates probablemente miente sobre el estado actual del proyecto. Un CLAUDE.md activamente mantenido es el activo de productividad más alto que un proyecto puede tener para colaboración con AI.

Esta práctica se conecta directamente con el Módulo 8 (Proyecto Integrador), donde la documentación final del proyecto migrado incluye un CLAUDE.md actualizado para el codebase modernizado.

Anti-patrón: CLAUDE.md como "todo el proyecto en un archivo"

Algunos developers tratan CLAUDE.md como un substituto de la documentación completa del proyecto. Es lo opuesto de lo que debe ser:

  • ✅ CLAUDE.md ideal: 100-300 líneas, conventions y reglas de alto nivel, orientado a "qué necesita saber Claude Code para ser productivo aquí"
  • ❌ CLAUDE.md mal hecho: 2000+ líneas, repite el README, incluye changelog, copia documentación de librerías

Si tu CLAUDE.md crece más allá de las 500 líneas, probablemente está cargando documentación que debería vivir en otros lugares. La calidad va sobre la longitud — un CLAUDE.md de 200 líneas bien curadas vence a uno de 2000 líneas sin foco.

← AnteriorCLAUDE.md y Project Context FilesSiguiente →Módulo 7: Modernizar Legacy Code