SpecNative
Ingeniería de agentes orientada por repositorio
Spec-Driven Development / Agent-Driven Development
SpecNative Development es un modelo de desarrollo donde las especificaciones, reglas de arquitectura, convenciones y decisiones viven en archivos estables del repositorio para que los agentes puedan planificar e implementar con menos ambigüedad en runtime.
Concepto
El cambio es directo: en lugar de reconstruir el contexto del proyecto dentro de una conversación, el repositorio codifica ese contexto una vez y el agente lo navega de forma determinista.
La intención se convierte en una especificación. Las especificaciones se descomponen en tareas. La arquitectura y las decisiones restringen el plan. El código y las pruebas materializan el resultado.
Motivación
Los prompts largos se vuelven un sustituto frágil de arquitectura, decisiones y reglas operativas que deberían existir en control de versiones.
Los agentes suelen heredar estado superficial de sesión en lugar de contexto estable de producto y sistema con ownership explícito.
Los layouts de código optimizan almacenamiento de source code, no navegación determinista, tracking de decisiones ni lookup de especificaciones.
Los equipos reexplican las mismas reglas de producto, límites arquitectónicos y convenciones de código entre sesiones.
Estructura
La plantilla de este proyecto mantiene la mayor parte del contexto bajo
agents/. En sistemas más grandes, el mismo modelo puede
expandirse a áreas dedicadas como specs/, tasks/,
architecture/ y workflows/.
repo/
├── AGENTS.md
├── README.md
├── agents/
│ ├── README.md
│ ├── PRODUCT.md
│ ├── ARCHITECTURE.md
│ ├── STACK.md
│ ├── CONVENTIONS.md
│ ├── COMMANDS.md
│ ├── DECISIONS.md
│ ├── SPEC.md
│ └── specs/
│ ├── README.md
│ └── authentication/
│ ├── README.md
│ ├── SPEC.md
│ └── TASKS.md
└── workflows/
└── implementation.md
Los README.md enrutan a humanos y agentes al contexto correcto
sin duplicar todo el conocimiento del proyecto.
Archivos como PRODUCT.md, SPEC.md,
ARCHITECTURE.md y DECISIONS.md contienen la
verdad duradera.
Los archivos o secciones de tareas descomponen specs en unidades implementables y las conectan con validación.
Los agentes deben navegar, no ingerir todo el repositorio. Empieza por la navegación local y luego carga solo los documentos necesarios para la tarea actual.
Runtimes
SpecNative no está atado a un solo runtime de agentes. El repositorio es la capa estable. El runtime es la capa de ejecución. El patrón de integración es darle a cada herramienta un bootstrap delgado hacia el mismo contexto del repositorio.
OpenCode ofrece agentes primarios y subagentes, permisos configurables e integraciones ACP/editor. Encaja bien cuando quieres separar planificación y ejecución alrededor de un flujo nativo del repositorio.
AGENTS.md y en los README.md de carpetas.{
"$schema": "https://opencode.ai/config.json",
"agent": {
"plan": {
"permission": {
"edit": "deny",
"bash": { "*": "ask" }
}
},
"build": {
"permission": {
"edit": "allow",
"bash": { "*": "ask", "git status *": "allow" }
}
}
}
}
Claude Code lee un CLAUDE.md raíz, soporta comandos
personalizados, hooks, MCP y múltiples agentes. En un repositorio
SpecNative, usa CLAUDE.md como archivo de bootstrap y no como
manual monolítico del proyecto.
CLAUDE.md corto que apunte a AGENTS.md y al modelo de navegación local./implement-spec authentication.# CLAUDE.md
Empieza leyendo ./AGENTS.md.
En cada carpeta, lee el README.md local antes de hacer cambios.
Usa los archivos bajo ./agents/ como documentos fuente.
Si vas a implementar una feature, localiza primero el SPEC.md relevante.
No trates este archivo como fuente de verdad de producto o arquitectura.Fuente: overview de Claude Code
Codex puede trabajar localmente o en entornos cloud y funciona mejor cuando el repositorio ya expone restricciones y setup de forma clara. SpecNative le da a Codex una superficie de contexto estable entre terminal, IDE y tareas delegadas.
AGENTS.md y en archivos de spec, no solo en prompts de tarea.Implementa la iniciativa de autenticación.
Lee AGENTS.md primero.
Luego lee agents/README.md, agents/ARCHITECTURE.md,
agents/CONVENTIONS.md y agents/specs/authentication/SPEC.md.
Planifica el trabajo, impleméntalo, ejecuta los comandos de validación
documentados y actualiza DECISIONS.md si cambia un trade-off persistente.Flujo de Implementación
Escribe comportamiento, alcance, restricciones y criterios de aceptación en una spec.
Carga arquitectura, stack, convenciones y decisiones previas antes de planificar.
Descompón la spec en unidades de implementación que puedan validarse.
Produce código, pruebas y actualizaciones documentales que satisfagan la spec.
Adopción
Agrega AGENTS.md, un README.md raíz y un
agents/SPEC.md para una iniciativa activa.
Mueve intención de producto, arquitectura, reglas de stack, comandos y convenciones a archivos del repositorio con ownership claro.
Dale al runtime una instrucción de entrada corta que diga dónde mirar, no un resumen largo del proyecto.
Introduce carpetas por iniciativa, archivos explícitos de tareas y documentos de workflow a medida que aumente la complejidad del proyecto.
Recursos