Saltar a contenido

Estándar de documentación técnica — Compulandia

Este repositorio es un template: al crear un repo nuevo (o documentar uno existente) se copia esta estructura y se completan los placeholders {{...}}. Este archivo (docs/index.md) describe el estándar en sí — en el repo destino reemplazalo por una portada breve del sistema (una o dos oraciones y links a arquitectura y runbook alcanzan).

Regla de decisión: ¿dónde va cada documento?

¿El documento cambia cuando cambia el código? - Sí → vive en el repositorio, junto al código, y se versiona con él. - No → va a Outline (documentación organizacional: procesos, RRHH, comercial, políticas generales).

Casos borde: un manual de usuario final no va al repo (no lo mantiene quien programa). Un diagrama de infraestructura sí va al repo de infraestructura.

Estructura obligatoria

repo/
├── README.md          # máx. 40 líneas: qué es, stack, levantar en local
├── AGENTS.md          # comandos, convenciones y restricciones para agentes IA
├── CLAUDE.md          # symlink → AGENTS.md (ln -s AGENTS.md CLAUDE.md)
└── docs/
    ├── arquitectura.md    # componentes, dependencias externas, diagrama
    ├── runbook.md         # deploy, logs, rollback, 3 fallas frecuentes
    └── adr/
        ├── README.md      # índice y reglas
        └── NNNN-titulo.md # una decisión por archivo, formato MADR
  • README de máximo 40 líneas. Si necesita más, ese contenido pertenece a docs/. El README es la puerta de entrada, no la casa.
  • AGENTS.md sin sección "Arquitectura" — genera ruido sin aportar contexto útil; el agente lee docs/arquitectura.md si la necesita.

Front-matter obligatorio para documentos generados con IA

Todo documento redactado total o parcialmente por un modelo de IA lleva:

---
generado_por: <modelo, ej: claude-fable-5>
revisado_por: <nombre del humano que validó | pendiente>
fecha: <YYYY-MM-DD>
estado: borrador | validado | obsoleto
---

Un documento queda en estado: borrador hasta que un humano lo lea y confirme que es cierto. La validación real es el único check que importa: otro dev del equipo debe poder levantar el sistema siguiendo solo el README, sin consultar al autor.

Cómo documentar un repo existente

  1. Crear repo desde este template (o copiar la estructura a mano).
  2. Completar README, arquitectura y runbook. Empezar por el runbook: es el que más valor da por hora invertida.
  3. Redactar como máximo 3 ADRs retroactivos — solo decisiones que siguen costando dinero re-discutir (ver docs/adr/README.md).
  4. Verificar que no haya secretos, credenciales ni tokens en el contenido.
  5. Pedir a otro dev que levante el sistema siguiendo solo el README.
  6. Recién ahí, cambiar los front-matter a estado: validado.

Definition of Done — "Repositorio documentado"

□ README.md de máximo 40 líneas: qué es, stack, cómo levantar en local
□ docs/arquitectura.md: componentes, dependencias externas, diagrama
□ docs/runbook.md: deploy, ubicación de logs, rollback, 3 fallas frecuentes
□ docs/adr/ con al menos 1 ADR de una decisión vigente
□ AGENTS.md con comandos, convenciones y restricciones (sin sección "Arquitectura")
□ Verificado: ningún secreto, credencial ni token en el contenido
□ El repositorio aparece en el portal y su búsqueda devuelve resultados
□ VALIDACIÓN REAL: otro dev levantó el sistema siguiendo solo el README