Claude Academy
Cargando

El CLAUDE.md

Lección 53 min

CLAUDE.md le da a Claude el contexto que necesitaría una persona nueva en el equipo, cubriendo convenciones, comandos, arquitectura y los errores que el equipo ve con más frecuencia. El conocimiento que antes residía en la cabeza de las personas y en wikis se convierte en un archivo que el agente lee al comienzo de cada sesión, mantenido por todo el equipo e iterado cada vez que se comete un error.

Primeros pasos

  • Requisitos previos: Ninguno.
  • Infraestructura: Un repositorio, Claude Code instalado y un ingeniero que conozca bien la base de código.

Cómo ejecutarlo

  1. Ejecuta /init en el repositorio. Claude genera un CLAUDE.md inicial a partir de lo que encuentra.
  2. Reduce el archivo generado a lo que una persona nueva necesitaría el primer día. Conserva los comandos de build, test y lint, las convenciones que importan y las cosas que Claude sigue haciendo mal.
  3. Registra CLAUDE.md en Git en la raíz del repositorio para que todo el equipo comparta una sola versión y los cambios se revisen como código.
  4. Aquí ayuda una regla de trabajo. Cuando Claude comete un error dos veces, la corrección se agrega a CLAUDE.md.
  5. Manténlo en menos de una página, porque Claude lo lee todo al comienzo de una sesión y cualquier cosa obsoleta está ocupando contexto sin ningún beneficio.

Cómo se ve

Este CLAUDE.md pertenece al repositorio del portal de clientes de una aseguradora. El sistema interno más antiguo que contiene los reclamos es claims-core, y intent/ guarda los archivos de planificación de cada cambio.

CLAUDE.md:

markdown
# Claims portal
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
- Run: make run (portal on :3000, claims-api on :8000)
## Conventions
- claims-api is Python 3.12 and FastAPI. portal is TypeScript and React.
- Every endpoint needs a test in claims-api/tests.
- Dates cross the API as ISO 8601, never as formatted text.
## Architecture
- portal/ is the customer site, claims-api/ is its backend, and
  intent/ holds the intent.md, spec.md and plan.md for each change.
- Only claims-api talks to claims-core. The portal never calls it.
- claims-core allows 50 requests a second. Cache reads; never poll it.
## Things Claude gets wrong
- Do not log request or response bodies in claims-api; they can hold PII.
- Do not bump dependency versions; the platform team owns them.

Consideraciones de gobernanza

CLAUDE.md está controlado por versiones, por lo que las instrucciones que sigue el agente son revisables y auditables. Las convenciones del equipo se aplican a través del archivo, los cambios a este quedan registrados en el historial de Git, y los propietarios del código aprueban esos cambios en la revisión de PR.

Cómo medirlo

  • Indicador adelantado: Con qué frecuencia Claude repite un error que CLAUDE.md debería haber detectado. Las correcciones o cambios al CLAUDE.md deben rastrearse dentro del historial de Git.
  • Indicador rezagado: Tiempo hasta el primer PR fusionado para un nuevo miembro del equipo, a partir del historial de PR.