Qué va en un CLAUDE.md para un proyecto C# / .NET (con plantilla lista para copiar)

Claude Code lee tu CLAUDE.md antes de tocar un solo archivo. Para un proyecto .NET, afinar este archivo es el paso de configuración con mayor retorno de inversión que puedes hacer. Un CLAUDE.md bien escrito es la diferencia entre un agente que produce C# idiomático en el primer intento y uno que inventa patrones que nunca pediste.

¿Qué es un CLAUDE.md y por qué Claude Code lo lee automáticamente?

Un CLAUDE.md es un archivo Markdown en la raíz de tu repositorio (o en cualquier subdirectorio) que Claude Code carga en contexto al inicio de cada sesión - sin que se lo pidas. Es el mecanismo que Claude Code proporciona para instrucciones persistentes a nivel de proyecto.

Piénsalo como el documento de onboarding que le darías a un nuevo ingeniero senior: visión general de la arquitectura, los comandos que necesita ejecutar, las convenciones acordadas por el equipo y una definición clara de qué significa “terminado”. Un agente que ha leído este archivo no necesita adivinar tu estructura de carpetas, no ejecuta dotnet build con argumentos incorrectos y no deja la suite de tests en rojo cuando hace commit.

La documentación oficial de mejores prácticas de Claude Code es explícita: incluye cosas que Claude no puede inferir leyendo el código. Cualquier cosa que Claude descubriría por sí solo es ruido que diluye la señal - y un CLAUDE.md inflado hace que Claude empiece a ignorar las reglas enterradas al fondo.

Puedes colocar archivos CLAUDE.md en varios lugares:

• Raíz del repo - cargado cada sesión, compartido vía git.
• Subdirectorio (ej. src/Api/CLAUDE.md) - cargado bajo demanda cuando Claude trabaja en esa carpeta. Útil para reglas específicas en un monorepo.
• Carpeta home (~/.claude/CLAUDE.md) - tus overrides personales, no se commitean al repo.

Comienza con /init dentro de Claude Code. Inspecciona tu codebase y genera un archivo de inicio. Luego refínalo.

¿Qué debe incluir un CLAUDE.md de .NET - y qué NO debe ir?

Qué pertenece a CLAUDE.md

Visión general de la arquitectura. Dos o tres frases describiendo la forma de la solución: cuántos proyectos hay, cuáles son los puntos de entrada, qué capa tiene qué responsabilidad. Un agente que sabe que Api/ son endpoints delgados que delegan a Application/ no añadirá lógica de negocio en el controlador.

El conjunto de comandos. Cada comando que el agente puede ejecutar, especificado exactamente:

dotnet build src/MySolution.sln
dotnet test src/MySolution.sln --no-build
dotnet format src/MySolution.sln
dotnet ef migrations add <Nombre> --project src/Infrastructure --startup-project src/Api

Pre-aprobar estos en .claude/settings.json significa que el agente no hará una pausa para pedir permiso. Listarlos en CLAUDE.md le indica al agente cuáles comandos están sancionados.

Decisiones de arquitectura que no son obvias del código. Por qué elegiste almacenamiento en memoria en lugar de base de datos en el starter. Por qué usas records para todos los comandos y queries. Por qué los endpoints son delgados y específicos por slice. Estas son las decisiones que un agente tomaría diferente por instinto.

Definición de hecho. Una checklist explícita: el build pasa, los tests están en verde, dotnet format no muestra diferencias. Esto es lo que el agente verifica antes de detenerse.

Gotchas no obvios. Variables de entorno que el proyecto requiere, un secreto local que debe configurarse, una particularidad del setup de tests.

Qué NO pertenece a CLAUDE.md

Estilo de código. Sangría, estilo de llaves, orden de directivas using y convenciones de nomenclatura pertenecen a .editorconfig, aplicados por dotnet format. Ponlos ahí - no en CLAUDE.md - y la cadena de herramientas los aplica mecánicamente. Claude no necesita releer una regla que el formateador ya aplica.

Convenciones estándar de .NET. Claude ya sabe que los métodos async retornan Task, que IDisposable debe envolver en using, y que ArgumentNullException.ThrowIfNull es la verificación de nulos moderna. Escribirlas es ruido.

Descripciones archivo por archivo del codebase. El agente lee los archivos directamente. Una descripción en prosa de cada clase está desactualizada el segundo día y desperdicia tokens de contexto.

Información que cambia frecuentemente. Si una sección de CLAUDE.md necesita actualizarse cada sprint, pertenece a un comentario en el código o a una sección del README, no a las instrucciones del agente.

¿Qué tan largo debe ser un CLAUDE.md?

Apunta a 50-100 líneas en el archivo raíz. La documentación de mejores prácticas de Anthropic dice mantenerlo corto y legible por humanos. El techo antes de que la señal empiece a perderse en el ruido es de alrededor de 200 líneas para un solo archivo. Los archivos con scope por ruta (archivos CLAUDE.md en subdirectorios) pueden llegar hasta 200 líneas porque solo se cargan cuando son relevantes.

Para cada línea, aplica la prueba: ¿eliminar esto haría que Claude cometiera un error? Si no, córtala.

Las cuatro secciones que sobreviven esta prueba en casi todo proyecto .NET:

1. Tech overview - runtime, framework, paquetes clave, forma de la solución.
2. Razonamiento de arquitectura - las decisiones que no son obvias del código.
3. Conjunto de comandos - los comandos exactos que el agente puede ejecutar.
4. Definición de hecho - la checklist que el agente verifica antes de detenerse.

Una plantilla CLAUDE.md de ejemplo para una minimal API de .NET 10

La siguiente plantilla está adaptada de las convenciones y definición de hecho usadas en el repo starter gratuito github.com/Khavel/dotnet-claude-starter. Clónalo para verlo en contexto.

# CLAUDE.md - MiProyecto

## Tech overview
- .NET 10 minimal API, C# 13, nullable reference types habilitado
- Paquetes: MediatR (CQRS), FluentValidation, Serilog
- Almacenamiento en memoria en este starter; el kit de producción añade EF Core + PostgreSQL
- Solución: src/Api (punto de entrada), src/Application, src/Domain, tests/Api.Tests

## Arquitectura
- Vertical slice: cada feature vive en una carpeta bajo src/Api/Features/<Feature>/
- Los endpoints son delgados: validar, despachar un comando/query de MediatR, retornar el resultado
- Todos los comandos y queries son records de C#; los handlers viven en la misma carpeta del feature
- Sin dependencias entre features; código compartido va a src/Application/Common/

## Comandos (pre-aprobados en .claude/settings.json)
- Build: dotnet build src/MySolution.sln
- Test: dotnet test src/MySolution.sln --no-build --logger "console;verbosity=minimal"
- Verificar formato: dotnet format src/MySolution.sln --verify-no-changes
- Aplicar formato: dotnet format src/MySolution.sln

## Definición de hecho
Un cambio está completo cuando TODOS los siguientes se cumplen:
1. dotnet build sale con 0
2. dotnet test sale con 0 (sin tests saltados sin un comentario)
3. dotnet format --verify-no-changes sale con 0
4. El feature nuevo o cambiado tiene al menos un test de contrato

## Gotchas no obvios
- Los tests usan WebApplicationFactory<Program>; Program.cs debe ser partial
- Configura ASPNETCORE_ENVIRONMENT=Development para ejecución local (ver .env.example)

Esta plantilla es intencionalmente ligera. El agente lee los archivos fuente reales para todo lo demás. El CLAUDE.md proporciona solo lo que el agente no puede inferir de forma segura por sí solo.

FAQ

¿Qué es un archivo CLAUDE.md? CLAUDE.md es un archivo Markdown que Claude Code lee automáticamente al inicio de cada sesión. Le da al agente contexto persistente que no puede inferir del código: decisiones de arquitectura, conjunto de comandos, convenciones y definición de hecho.

¿Dónde debo colocar CLAUDE.md en una solución .NET? Pon un CLAUDE.md en la raíz del repositorio para las reglas de todo el proyecto. Puedes añadir CLAUDE.md adicionales en subdirectorios (ej. src/Api/) que Claude carga bajo demanda. Mantén el archivo raíz por debajo de 100 líneas.

¿Deben ir las reglas de estilo de código en CLAUDE.md? No. El estilo de código pertenece a .editorconfig y lo aplica dotnet format. Pon en CLAUDE.md solo lo que dotnet format no puede aplicar: decisiones de arquitectura, comandos de workflow y la definición de hecho.

¿Qué tan largo debe ser un CLAUDE.md? Apunta a 50-100 líneas en el archivo raíz. Para cada línea aplica la prueba: ¿eliminarla haría que Claude cometiera un error? Si no, córtala.

¿El repo dotnet-claude-starter incluye un CLAUDE.md? Sí. github.com/Khavel/dotnet-claude-starter incluye un CLAUDE.md completamente anotado para una minimal API de .NET 10. Clónalo para ver las convenciones y la definición de hecho en contexto, luego adáptalo a tu solución.

---

¿Construyendo un SaaS .NET en producción, agent-first?

El repo dotnet-claude-starter te da la forma. Sharpyard es el kit de producción: un starter SaaS de .NET 10 y Angular con auth, multi-tenancy, billing, y la capa de operación de agente completa (CLAUDE.md, config de MCP, tests de contrato, conjunto de comandos pre-aprobado) integrada en todo. Únete a la lista de espera fundadora para acceso anticipado y el precio fundador.