Cómo usar Claude Code en una solución C# grande sin agotar la ventana de contexto

Una solución C# grande y un agente con ventana de contexto limitada tienen una tensión que vale la pena entender antes de toparse con ella. El agente es más útil cuando puede razonar sobre el código que está modificando; se convierte en un problema cuando empieza a adivinar porque ha leído demasiado código irrelevante. Este post es una lista de comprobación práctica para mantener a Claude Code en contexto en una solución .NET multi-proyecto.

¿Por qué tiene dificultades Claude Code en una .sln grande?

Ventana de contexto y proyectos irrelevantes cargados. Esa es la respuesta en una frase. Una solución .NET empresarial moderna puede tener decenas de proyectos: API, workers en segundo plano, librería de dominio, adaptadores de infraestructura, tests de integración, tests unitarios, kernel compartido, shims de compatibilidad heredada. Si el agente los lee todos para responder una pregunta sobre OrderService, consume la mayor parte de su presupuesto de contexto en código que no va a cambiar. Para cuando llega a la parte que necesita, la ventana está saturada y su razonamiento se degrada.

El modo de fallo no suele ser un error duro - es deriva sutil: el agente propone un cambio que habría sido correcto para un proyecto diferente de la solución, o pasa por alto una convención que está documentada pero enterrada bajo el ruido de archivos no relacionados.

¿Cómo mantengo al agente en contexto en una solución multi-proyecto?

Esto es una lista de comprobación, no teoría. Aplica cada elemento en orden de coste.

1. Una tarea por sesión; contexto fresco por cambio. No mantengas una sesión a través de múltiples tareas no relacionadas. La ventana de contexto es un recurso compartido; cada tarea debe empezar limpia. Esta es la corrección más barata y la que más gente omite.

2. Limita el alcance a los proyectos relevantes, no a toda la .sln. Dile al agente “trabaja en src/Billing/ y src/Shared/Contracts/” en lugar de apuntarlo a la raíz de la solución. Cuantos menos proyectos lea al principio, más presupuesto tiene para el código que importa.

3. Escribe archivos CLAUDE.md por directorio. Un CLAUDE.md raíz mapea toda la arquitectura. Cada proyecto o carpeta de dominio tiene su propio CLAUDE.md que describe el rol del proyecto, sus convenciones y qué debe y no debe tocar el agente. Cuando el agente entra en src/Billing/, lee ese archivo primero y conoce las reglas antes de tocar nada.

4. Delega la exploración en subagentes. Cuando necesitas una respuesta de toda la solución - “¿qué proyectos referencian ILegacyPaymentGateway?” - lanza un subagente para la búsqueda. El subagente lee en amplitud, destila la respuesta en un resumen compacto (uno o dos párrafos) y lo devuelve a tu sesión principal. Tu contexto principal recibe la respuesta, no las miles de líneas de salida de grep.

5. Usa un MCP de Roslyn para consultas semánticas bajo demanda. En lugar de pedir al agente que lea cada archivo que podría referenciar un símbolo, dale un servidor MCP de Roslyn que pueda responder “encuentra todos los llamadores de OrderService.Save” bajo demanda. El agente llama a la herramienta cuando necesita la respuesta y obtiene un resultado preciso. Esto reemplaza grandes lecturas iniciales con consultas pequeñas y específicas.

¿Cómo ayudan los archivos CLAUDE.md por directorio?

Un CLAUDE.md por directorio responde la pregunta que Claude Code hace cuando entra en una carpeta de proyecto: “¿cuáles son las reglas aquí?” Sin él, el agente recurre a adivinar a partir de nombres de archivos y patrones de código, lo que funciona hasta que no funciona.

Un buen CLAUDE.md por proyecto en .NET es corto - unas 30 a 60 líneas. Cubre:

• Rol: “Este es el adaptador HTTP. No tiene lógica de negocio. Los controladores son finos; todas las decisiones ocurren en los servicios de dominio.”
• Convenciones clave: “Nullable habilitado. Namespaces con alcance de archivo. Records para todos los DTOs. Sin métodos estáticos.”
• Qué ejecutar: “dotnet test src/Billing.Tests/ para verificar; dotnet build src/Billing/ para comprobar la compilación.”
• Qué no tocar: “No añadas paquetes NuGet aquí. Las dependencias de infraestructura se cablean en src/Infrastructure/.”

Ese archivo de 30 líneas evita al agente una docena de errores por sesión en un proyecto que no ha visto antes en esta ventana de contexto. El coste es escribirlo una vez y actualizarlo cuando cambian las convenciones.

¿Cuándo debo delegar en subagentes?

Delega cuando el trabajo es exploratorio y quieres la respuesta, no la búsqueda. Casos concretos:

• Auditoría de dependencias: ¿qué proyectos tienen versiones antiguas de paquetes y cuáles tienen dependencias vulnerables? Deja que un subagente recorra cada *.csproj y devuelva una tabla. Tu sesión recibe la tabla.
• Mapa de cobertura de tests: ¿qué servicios públicos en src/Domain/ no tienen un archivo de test correspondiente en src/Domain.Tests/? Un subagente mapea esto y devuelve una lista.
• Búsqueda de símbolo entre proyectos: ¿dónde se usa este tipo en toda la solución? Un subagente con el MCP de Roslyn ejecuta la consulta y devuelve los puntos de llamada.
• Análisis paralelo de proyectos: si necesitas entender dos áreas de dominio independientes para planificar una refactorización, lanza un subagente por dominio, deja que se ejecuten simultáneamente y lee sus resúmenes en paralelo.

La regla: si recopilar los datos brutos costaría más de unos pocos cientos de tokens del contexto de la sesión principal, pertenece a un subagente. Tu sesión principal debe recibir respuestas estructuradas, no resultados de búsqueda en bruto.

FAQ

¿Por qué Claude Code pierde contexto en una solución C# grande? Porque una .sln multi-proyecto puede superar fácilmente la ventana de contexto efectiva del agente cuando todos los proyectos se cargan a la vez. Los proyectos irrelevantes consumen presupuesto de tokens que debería ir al código que realmente se está modificando.

¿Cuál es la forma más efectiva de mantener a Claude Code en contexto en una solución grande? Limitar cada sesión a los proyectos relevantes, no a toda la solución. Combinado con un CLAUDE.md raíz y archivos CLAUDE.md por directorio, el agente obtiene el contexto que necesita sin leerlo todo.

¿Cuántos archivos CLAUDE.md debe tener una solución grande? Uno en la raíz del repo y uno por proyecto o carpeta de dominio con convenciones distintas - normalmente entre 3 y 8 archivos para una solución empresarial real.

¿Cuándo debo usar subagentes en una solución grande? Cuando la tarea es exploratoria o puede ejecutarse en paralelo - auditorías de dependencias, búsquedas de código muerto entre proyectos, mapeo de cobertura de tests. Un subagente destila sus hallazgos en un resumen compacto antes de devolver el resultado.

¿El repo dotnet-claude-starter demuestra estos patrones? Sí. El repo es un ejemplo deliberadamente pequeño cuya disciplina - SDK fijado, warnings como errores, slices finos, un CLAUDE.md raíz - es la misma que escala. El README explica cómo extender cada patrón a una solución más grande.

---

Posts relacionados

• Claude Code para desarrolladores .NET - la guía completa de configuración
• MCP para .NET - cómo cablear el MCP de Roslyn y otras herramientas
• Subagentes y skills en Claude Code para .NET - la capa de agentes en detalle

---

La base en producción

Los patrones aquí mantienen a un agente productivo en una solución grande. Sharpyard es el starter kit .NET 10 + Angular para SaaS en producción con la capa de operación completa (CLAUDE.md raíz, CLAUDE.md por proyecto, configuración de MCP, tests de contrato) cableada desde el principio. Únete a la lista de espera para el precio fundador.