Implementación de Steering Documents para Claude Code
DominicodeSteering documents: enseña a Claude tu arquitectura de una vez
Tiempo estimado de lectura: 5 min
- Convierte la memoria del agente en infra versionada: usa product.md, tech.md y structure.md.
- Son contratos operativos: Claude Code los carga al arrancar y los respeta como reglas.
- Manténlos concisos y gobernados: actualízalos como parte de la PR y asigna propietarios.
Steering documents: enseña a Claude tu arquitectura de una vez —esa es la diferencia entre repetir contexto cada sesión y tener un agente que ya entiende tu producto, tu stack y tus límites. Si usas Claude Code en proyectos reales, necesitas tres documentos permanentes en el repo: product.md, tech.md y structure.md. Con ellos conviertes la memoria del agente en infra versionada, no en promesas inútiles de prompt.
Resumen rápido (lectores con prisa)
Steering documents son archivos Markdown versionados que Claude Code carga al iniciar. Son contratos operativos: product.md define dominio y reglas inmutables; tech.md define stack y prohibiciones; structure.md define mapa y reglas de dependencia. Actualízalos con la PR que cambia el dominio o stack.
Steering documents: qué son y cómo los usa Claude Code
Un steering document es un Markdown versionado que Claude Code lee al arrancar una sesión. No es mera documentación: es el contrato operativo que la IA debe respetar. La doc raíz CLAUDE.md debe referenciarlos para que Claude los cargue automáticamente (ver docs de Claude Code y Claude (Anthropic)).
¿Por qué preocuparnos? Sin estos archivos el agente:
- Asume patrones genéricos y propone librerías no deseadas.
- Introduce convenciones inconsistentes (nombres, capas).
- Toma decisiones de negocio que rompen reglas críticas.
Con steering documents, el agente aplica las mismas restricciones y expectativas que un ingeniero senior al entrar al repositorio.
Los tres steering documents esenciales
A continuación, la estructura práctica y mínima para cada archivo. Copia, adapta y versiona.
product.md — contexto de negocio (qué y para quién)
Debe explicar el dominio y las reglas que NUNCA se rompen.
Ejemplo mínimo:
## Propósito Sistema B2B para facturación y gestión de suscripciones. ## Usuarios Admin (gestiona planes), Cliente (visualiza facturas), Billing Ops. ## Conceptos de dominio - Factura: documento inmutable que refleja obligación de pago. - Suscripción: contrato con ciclo y estado (active, trial, cancelled). ## Reglas inmutables - Una factura con estado "paid" no puede mutarse. - Cambios de plan aplican solo desde el próximo ciclo de facturación.
Product.md evita que Claude implemente validaciones técnicamente correctas pero comercialmente inválidas.
tech.md — contrato técnico (qué usar y qué evitar)
Enumera stack, patrones aprobados, patrones prohibidos y comandos de validación.
Ejemplo mínimo:
## Stack aprobado - Frontend: Next.js 14 (App Router), TypeScript - Backend: Node + Fastify - DB: PostgreSQL + Drizzle ## Patrones aprobados - Feature-based folders - Estado: Zustand - Validaciones: Zod ## Prohibiciones - No usar `any` en TS - No añadir dependencias sin RFC y PR
Incluye comandos que Claude puede ejecutar para validar cambios: pnpm test, pnpm lint, pnpm build.
structure.md — mapa del repositorio y reglas de dependencia
Describe la topología y las reglas de importación.
Ejemplo mínimo:
## Árbol principal src/ ├─ app/ ├─ features/ ├─ shared/ └─ lib/ ## Reglas de dependencia - features -> shared|lib - shared !-> features - lib !-> features|shared
Structure.md previene importaciones cruzadas, acoples y mal colocación de código.
Cómo integrarlos en CLAUDE.md y en el flujo de trabajo
Incluye estas líneas al inicio de CLAUDE.md:
Lee antes de cualquier tarea: - @product.md - @tech.md - @structure.md
Eso obliga a Claude Code a tratarlos como memoria base. Además, convierte a estos archivos en el primer artefacto que se consulta en cada sesión, reduciendo la necesidad de prompts largos.
Reglas operativas prácticas:
- Actualiza steering docs como parte de la PR que introduce el cambio (no después).
- Cada PR que modifica stack o dominio debe incluir cambios en tech.md o product.md.
- Los commits deben referenciar el documento afectado: e.g.,
tech: add pgvector to approved libs.
Mantenimiento y gobernanza
Los steering documents son infra; trátalos como tal:
- Mantén un owner (Staff/Tech Lead) responsable de aprobar cambios.
- Usa PR con plantilla: “¿Este cambio requiere actualizar product/tech/structure?”.
- Revisión obligatoria para cambios que rompan reglas prohibidas.
Medir impacto:
- % de PRs que violan tech.md (debe bajar).
- Tiempo medio para onboarding de IA (leer docs vs. explicar manualmente).
- Reverts causados por decisiones del agente (debe descender).
Límite y advertencia práctica
No conviertas estos archivos en una lista viva de todo el código. Son contratos, no specs línea por línea. Manténlos concisos, explícitos y estables. Si permites que entren cambios experimentales sin governance, el agente aplicará reglas obsoletas y causará más fricción que ahorro.
Implementar steering documents: enseña a Claude tu arquitectura de una vez
Implementar steering documents: enseña a Claude tu arquitectura de una vez. Es trabajo de equipo al principio; ahorro de tiempo y coherencia técnica permanente después. Si quieres que la IA actúe como ingeniero efectivo, no le des hints: dale el contrato.
Para equipos que automatizan workflows, integran agentes o aplican IA en procesos de ingeniería, también puede ser útil revisar recursos prácticos y experimentales en Dominicode Labs. Esa referencia complementa estrategias de gobernanza y pruebas para agentes en repositorios reales.
FAQ
- ¿Qué es un steering document?
- ¿Por qué necesito product.md, tech.md y structure.md?
- ¿Cómo se cargan estos archivos en Claude Code?
- ¿Qué poner en tech.md?
- ¿Cómo gestiono cambios en estos documentos?
- ¿Pueden ser demasiado detallados?
- ¿Qué pasa si el agente viola una regla?
¿Qué es un steering document?
Un steering document es un archivo Markdown versionado que Claude Code lee al arrancar. Funciona como un contrato operativo que la IA debe respetar.
¿Por qué necesito product.md, tech.md y structure.md?
Porque juntos convierten la memoria del agente en infra versionada: product.md define el dominio y reglas inmutables; tech.md define stack y prohibiciones; structure.md define topología y reglas de dependencia.
¿Cómo se cargan estos archivos en Claude Code?
La doc raíz CLAUDE.md debe referenciarlos para que Claude los cargue automáticamente al arrancar una sesión. Incluye al inicio: Lee antes de cualquier tarea: – @product.md – @tech.md – @structure.md.
¿Qué poner en tech.md?
Enumera stack aprobado, patrones aprobados, prohibiciones y comandos de validación (por ejemplo: pnpm test, pnpm lint, pnpm build).
¿Cómo gestiono cambios en estos documentos?
Actualízalos como parte de la PR que introduce el cambio y asigna un owner responsable de aprobar actualizaciones. Usa plantillas de PR que pregunten si los steering docs requieren cambios.
¿Pueden ser demasiado detallados?
No. Deben ser concisos y estables. Evita convertirlos en una lista viva de todo el código; son contratos, no especificaciones línea por línea.
¿Qué pasa si el agente viola una regla?
Si el agente toma decisiones que violan las reglas, revisa y refuerza los steering docs y la gobernanza: owner, PRs obligatorias y métricas de impacto (PRs que violan tech.md, reverts, tiempo de onboarding).