Cultura de Ingeniería (Docs-as-Code)
Este documento define cómo operamos ingeniería usando documentación como sistema de control, no como artefacto decorativo.
1. Principios operativos
- Fuente única de verdad: arquitectura, contratos y reglas viven en docs versionados.
- Cambio sin trazabilidad no existe: todo cambio relevante requiere RFC/ADR/changelog.
- Operación verificable: cada módulo tiene runbook, SLOs y criterio de rollback.
- Calidad como puerta, no recomendación: PR sin checks/documentación no se fusiona.
- Aprendizaje institucional: incidentes y decisiones se convierten en mejoras documentadas.
2. Ownership documental
| Campo | Regla |
|---|---|
| DRI | Cada documento tiene owner principal en owners |
| Backup owner | Cada documento tiene al menos 1 owner alterno |
| SLA actualización | Máximo 72h tras cambio funcional/técnico relevante |
| Cobertura | Todo módulo de producto debe mapear a API + DB + runbook |
3. Ritual mínimo de trabajo
| Ritual | Frecuencia | Resultado obligatorio |
|---|---|---|
| Docs review | Semanal | Lista de gaps con owner y fecha |
| Freshness audit | Mensual | % docs actualizadas y plan de corrección |
| API review | Por release | Cambios compat./breaking documentados |
| Incident review | Por incidente SEV1/SEV2 | Postmortem publicado y acciones asignadas |
4. Flujo de cambios de ingeniería
Reglas:
- RFC obligatorio para cambios de arquitectura, seguridad, datos o procesos críticos.
- ADR obligatorio para decisiones que comprometen dirección técnica.
- Ningún release sin changelog y rollback plan.
5. Definiciones de calidad (Ready / Done)
Definition of Ready (DoR)
- Requerimiento con contexto y alcance.
- Diseño (Miro/Figma) referenciado.
- Contrato API preliminar en OpenAPI si aplica.
- Riesgos y dependencias identificadas.
Definition of Done (DoD)
- Código, pruebas y documentación alineados.
- Contrato API y docs de producto actualizados.
- Observabilidad (logs/métricas/trazas) implementada.
- Seguridad mínima validada (authz, rate limit, manejo de errores).
- Runbook o actualización de runbook completada.
6. Métricas de cultura (KPIs)
| KPI | Meta |
|---|---|
| PRs con actualización documental cuando aplica | >= 95% |
| Docs desactualizadas (>30 días sin revisión) | <= 10% |
| Incidentes críticos con postmortem publicado < 5 días | 100% |
| Cambios API con changelog y estado de compatibilidad | 100% |
| Runbooks cubriendo servicios críticos | 100% |
7. Artefactos obligatorios
- RFC: ver
template-rfc.md. - Postmortem: ver
template-postmortem.md. - Threat model: ver
template-threat-model.md. - ADRs: ver
12-adr-registro.md. - Scorecard de madurez: ver
26-scorecard-madurez-ingenieria.md. - Política de excepciones: ver
27-politica-excepciones-tecnicas.md. - Gobernanza operativa: ver
28-gobernanza-operativa.md. - Ownership de artefactos: ver
29-matriz-ownership-artefactos.md. - SLA de frescura documental: ver
30-sla-frescura-documental.md. - Plan de adopción: ver
31-plan-adopcion-cultura.md.
8. Auditoría de cumplimiento
Una vez por sprint (o semanal en Kanban), Tech Lead y PO revisan:
- Cumplimiento de gates de documentación.
- Excepciones autorizadas y fecha de cierre.
- Acciones de mejora con owner y ETA.
9. RACI por ritual de ingeniería
| Ritual / Entregable | R (Responsible) | A (Accountable) | C (Consulted) | I (Informed) |
|---|---|---|---|---|
| Docs review semanal | Tech Lead, owners de módulo | Tech Lead | PO, QA Lead | Equipo completo |
| Freshness audit mensual | Tech Lead, PMO/PO | Product Owner | Frontend Lead, Backend Lead | Stakeholders |
| RFC (cambio mayor) | Autor del cambio | Tech Lead | PO, Seguridad, QA | Equipo completo |
| ADR (decisión arquitectónica) | Tech Lead | Tech Lead | Backend Lead, Frontend Lead, PO | Equipo completo |
| Cambio de contrato OpenAPI | Backend Lead | Tech Lead | Frontend Lead, QA Lead | Equipo completo |
| Runbook de servicio | Owner del servicio | Tech Lead | DevOps, QA | Soporte/Operación |
| Postmortem SEV1/SEV2 | Incident Commander | Tech Lead | DevOps, QA, Seguridad | Producto + Dirección |
| Release/rollback | DevOps, owner del servicio | Tech Lead | QA Lead, PO | Equipo completo |
Reglas RACI:
- Siempre debe existir un único
Apor ritual. - Si cambia el owner de módulo, se debe actualizar este RACI en el mismo PR.
- Ningún ritual se considera cerrado sin evidencia enlazada (PR, ticket, dashboard o acta).