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.
v0.7
La plantilla consolida todo el contexto del proyecto bajo spec-native/,
expone el repositorio como servidor MCP, instala comandos nativos por agente
y ahora incluye archetypes y templates para que los proyectos arranquen con
contenido real en lugar de placeholders.
spec-native/ pre-relleno para stacks y patrones comunes.
apply_archetype('java-hexagonal') escribe ARCHITECTURE, STACK,
CONVENTIONS, COMMANDS, DECISIONS y ROADMAP en una llamada.
Agrega los tuyos en .specnative/archetypes/.
apply_spec_template('feature-rest-endpoint', 'user-auth') crea
un SPEC.md listo para rellenar. apply_decision_snippet('jwt-authentication')
appenda DEC-XXXX a DECISIONS.md. Reutilizables entre proyectos.
.specnative/specnative_mcp.py expone el repositorio como
recursos tipados (spec:// URIs), herramientas y prompts para
Claude Code, Claude Desktop, OpenCode y Codex.
Se instala automáticamente con su propio venv.
/spec-init, /spec-update, /spec-status,
/spec-handoff — instalados automáticamente en todos los perfiles.
Disponibles como slash commands en Claude Code, prompts en OpenCode y
codex --prompt en Codex.
spec-native/SESSION.md persiste el estado activo de trabajo en git.
checkpoint() guarda dónde estás; resume() le dice
al siguiente agente — Claude Code, Codex o Cursor — exactamente qué hacer a continuación.
specnative init entrevista al desarrollador y llena los documentos
de contexto en minutos. specnative update detecta vacíos y guía
el refinamiento iterativo.
Todo vive en spec-native/: producto, specs, tareas, workflows,
pipelines y estado de sesión. Un punto de entrada, cero fricción de navegación
para cualquier agente.
install.py inicializa SpecNative en un repositorio existente
desde un release de GitHub. Cuatro perfiles: context, spec,
team, platform. Sin dependencias más allá de stdlib.
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
Todo el contexto del proyecto vive bajo spec-native/ — un único
punto de entrada para cualquier agente. AGENTS.md es el
meta-índice universal que explica SpecNative y cómo usar el servidor MCP.
repo/
├── AGENTS.md # Meta-índice: qué es SpecNative, referencia MCP
├── spec-native/
│ ├── PRODUCT.md # Problema, usuarios, objetivos (permanente)
│ ├── ARCHITECTURE.md # Estructura del sistema y límites
│ ├── STACK.md # Stack tecnológico y restricciones
│ ├── CONVENTIONS.md # Reglas de código, naming, testing
│ ├── COMMANDS.md # Comandos de dev/test/build
│ ├── DECISIONS.md # Decisiones persistentes y tradeoffs
│ ├── ROADMAP.md # Dirección temporal
│ ├── TRACEABILITY.md # Vínculos entre artefactos
│ ├── SESSION.md # Estado activo (continuidad multi-agente)
│ ├── specs/
│ │ └── <iniciativa>/SPEC.md
│ ├── tasks/
│ │ └── <iniciativa>/TASKS.md
│ ├── workflows/
│ │ ├── PLANNING.md
│ │ ├── IMPLEMENTATION.md
│ │ └── REVIEW.md
│ └── pipelines/
│ ├── CI.md
│ └── CD.md
├── .claude/commands/ # /spec-init, /spec-update, /spec-status, /spec-handoff
├── codex.toml # Comandos prompt para Codex
├── opencode.json # MCP + prompts para OpenCode
└── .specnative/
├── SCHEMA.md
├── MCP.md
└── specnative_mcp.py # Servidor MCP (auto-instalado)
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 de tareas descomponen specs en unidades implementables con estado, responsables, dependencias y criterio de cierre.
.specnative/ contiene el contrato del framework y la
referencia del CLI, separados del contenido del proyecto para poder
actualizarlos de forma independiente.
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" }
}
}
}
}// opencode.json — generado automáticamente por install.py
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"specnative": {
"type": "local", "enabled": true,
"command": ["./.specnative/.venv/bin/python3",
"./.specnative/specnative_mcp.py"]
}
},
"prompts": {
"spec-init": { "description": "Setup guiado del proyecto" },
"spec-update": { "description": "Detectar vacíos, refinar docs" },
"spec-status": { "description": "Health check rápido" },
"spec-handoff": { "description": "Traspaso al siguiente agente" }
}
}
Claude Code lee AGENTS.md y soporta slash commands personalizados
vía .claude/commands/. SpecNative instala cuatro comandos
automáticamente para que el desarrollador empiece con /spec-init el primer día.
/spec-init para llenar los documentos de contexto la primera vez./spec-status al iniciar cada sesión para ver el trabajo activo./spec-handoff antes de cerrar para que el siguiente agente pueda retomar.start_initiative, plan_tasks).# Slash commands instalados (.claude/commands/)
/spec-init # Entrevista al dev, llena spec-native/
/spec-update # Detecta vacíos, refina iterativamente
/spec-status # Sesión + specs + tareas + alertas
/spec-handoff # Genera SESSION.md para el siguiente agente
# MCP (auto-instalado)
claude mcp add specnative \
"$(pwd)/.specnative/.venv/bin/python3" \
"$(pwd)/.specnative/specnative_mcp.py" \
-- --repo "$(pwd)"Fuente: overview de Claude Code
Codex lee AGENTS.md y funciona mejor cuando el repositorio
expone restricciones y setup de forma clara. SpecNative instala prompts
listos para usar vía codex.toml.
codex --prompt spec-status para ver el trabajo activo.resume() del MCP para continuar desde el checkpoint del agente anterior.codex --prompt spec-handoff antes de cerrar para guardar el estado de sesión.# codex.toml — generado automáticamente por install.py
[mcp_servers.specnative]
command = "./.specnative/.venv/bin/python3"
args = ["./.specnative/specnative_mcp.py"]
type = "stdio"
# Prompts listos para usar:
# codex --prompt spec-init
# codex --prompt spec-update
# codex --prompt spec-status
# codex --prompt spec-handoffFlujo 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