Stage 2 · Mold · 90 min
Etapa 2 · Molde · 90 min
Generate Your Full Specification
Genera tu Especificación Completa
This recipe produces the complete GS sentinel tree: a SPEC.md with overview, vision, phases, functional features, NFRs, tech stack, and module map — plus assistant-agnostic architectural constitutions (CLAUDE.md for Claude Code, AGENTS.md for OpenAI Codex and most other tools, .cursor/rules/ for Cursor, .github/copilot-instructions.md for GitHub Copilot) — plus STATUS.md and an initial ADR. Everything the AI reader needs to derive correct behavior across all lifecycle stages without external context.
Esta receta produce el árbol sentinel GS completo: un SPEC.md con visión general, visión, fases, funcionalidades, NFRs, stack tecnológico y mapa de módulos — más constituciones arquitectónicas independientes del asistente (CLAUDE.md para Claude Code, AGENTS.md para OpenAI Codex y la mayoría de herramientas, .cursor/rules/ para Cursor, .github/copilot-instructions.md para GitHub Copilot) — más STATUS.md y un ADR inicial. Todo lo que el lector de IA necesita para derivar comportamiento correcto a través de todos los estadios del ciclo de vida sin contexto externo.
Files this recipe creates: docs/spec/SPEC.md · CLAUDE.md · AGENTS.md · STATUS.md · docs/adrs/ADR-000.md. All written in one session. If you want SPEC.md somewhere else, tell the AI before you begin: "Write SPEC.md to [your path]."
Archivos que crea esta receta: docs/spec/SPEC.md · CLAUDE.md · AGENTS.md · STATUS.md · docs/adrs/ADR-000.md. Todos escritos en una sesión. Si querés SPEC.md en otra ubicación, decíselo al AI antes de empezar: "Escribe SPEC.md en [tu ruta]."
Step 01 — Interview
Paso 01 — Entrevista
For new projects · 9 questions · one at a time
Para proyectos nuevos · 9 preguntas · una a la vez
Before writing any files, the AI asks nine questions — one at a time, waiting for your answer before asking the next. No guessing, no defaults filled in silently. The answers become the raw material for the spec.
Antes de escribir archivos, la IA te hace nueve preguntas — una a la vez, esperando tu respuesta antes de hacer la siguiente. Sin adivinar, sin defaults llenados silenciosamente. Las respuestas se convierten en la materia prima de la especificación.
01
Open a new AI session in your project folder (empty folder for a new project). Paste the interview prompt below.
Abre una nueva sesión de IA en tu carpeta de proyecto (carpeta vacía para un proyecto nuevo). Pega el prompt de entrevista abajo.
Paste this — InterviewPega esto — EntrevistaBefore writing any files, ask me the following questions one at a time.
Wait for my answer before asking the next. Do not guess or fill in defaults.
1. What is this project? One sentence: what it does and who uses it.
2. What does "done" look like in 6–12 months? What would a successful
first public version mean?
3. What phase are we in right now?
0 = idea only, 1 = early development, 2 = working prototype,
3 = production / real users
4. What are the 3–5 most important features in scope for the current phase?
5. What should this system never do? Name explicit non-goals.
6. Tech stack: language, runtime, framework, database, deployment target.
7. Module structure: the main areas of the codebase, even if not yet built.
Name them and describe their responsibility in one sentence each.
8. Performance requirements: acceptable response latency, expected concurrent
users, any throughput SLA.
9. What must the AI never do? Examples: never delete records without
confirmation, never bypass authentication, never run migrations
automatically.
When I have answered all nine questions, tell me "Ready to generate" and wait
for my go-ahead before writing any files.Antes de escribir archivos, hazme las siguientes preguntas una a la vez.
Espera mi respuesta antes de hacer la siguiente. No adivines ni llenes defaults.
1. ¿Qué es este proyecto? Una oración: qué hace y quién lo usa.
2. ¿Cómo se ve "listo" en 6–12 meses? ¿Qué significaría una primera
versión pública exitosa?
3. ¿En qué fase estamos ahora mismo?
0 = solo idea, 1 = desarrollo temprano, 2 = prototipo funcionando,
3 = producción / usuarios reales
4. ¿Cuáles son las 3–5 funcionalidades más importantes en alcance para
la fase actual?
5. ¿Qué nunca debe hacer este sistema? Nombra no-objetivos explícitos.
6. Stack tecnológico: lenguaje, runtime, framework, base de datos,
destino de despliegue.
7. Estructura de módulos: las áreas principales del código, incluso si
aún no están construidas. Nómbralas y describe su responsabilidad
en una oración cada una.
8. Requerimientos de performance: latencia de respuesta aceptable,
usuarios concurrentes esperados, cualquier SLA de throughput.
9. ¿Qué nunca debe hacer la IA? Ejemplos: nunca eliminar registros sin
confirmación, nunca saltarse la autenticación, nunca correr
migraciones automáticamente.
Cuando haya respondido las nueve preguntas, dime "Listo para generar"
y espera mi visto bueno antes de escribir archivos.
For an existing project, skip the interview. Use Step 02 directly — the AI will read the codebase first and fill in what it finds.
Para un proyecto existente, salta la entrevista. Usa el Paso 02 directamente — la IA leerá la base de código primero y completará lo que encuentre.
Step 02 — Generate the full sentinel tree
Paso 02 — Genera el árbol sentinel completo
After the interview — or directly, for existing projects
Después de la entrevista — o directamente, para proyectos existentes
Once the interview is complete, paste this generation prompt. The AI writes all five files in one pass. No further questions.
Una vez completada la entrevista, pega este prompt. La IA escribe los cinco archivos de una vez. Sin más preguntas.
SPEC.md structure
Estructura de SPEC.md
The specification the AI will write. Sections map directly to the interview answers.
La especificación que escribirá la IA. Las secciones mapean directamente a las respuestas de la entrevista.
| SectionSección | ContentContenido |
|---|
Overview · Vision | What the system is, who uses it, what "done" looks likeQué es el sistema, quién lo usa, cómo se ve "listo" |
Phase · Scope | Current phase, in-scope features, explicit non-goalsFase actual, features en alcance, no-objetivos explícitos |
F-001 · F-002… | Functional features — Actor, Precondition, Flow, Postcondition, Acceptance criteriaFuncionalidades — Actor, Precondición, Flujo, Postcondición, Criterios de aceptación |
NFRs | Performance, Reliability, Security, Scalability — each as a numbered constraintPerformance, Confiabilidad, Seguridad, Escalabilidad — cada uno como restricción numerada |
Tech Stack | Language, runtime, framework, database, deployment, test framework, CILenguaje, runtime, framework, base de datos, despliegue, framework de tests, CI |
Module Map | One row per module — name, responsibility, key interfacesUna fila por módulo — nombre, responsabilidad, interfaces clave |
Quality Gates | Coverage minimum, file/function length limits, commit format, CI rulesCobertura mínima, límites de longitud, formato de commit, reglas de CI |
Constraints | The AI Must Never — explicit prohibitions, derived from interview Q9La IA Nunca Debe — prohibiciones explícitas, derivadas de la pregunta 9 de la entrevista |
02
Paste this — after the interviewPega esto — después de la entrevistaGenerate the complete GS sentinel tree for this project.
Write the files to the exact paths listed below.
Use the answers from our interview. If something is ambiguous, state your
assumption in a comment inside the relevant file. Do not ask further questions.
────────────────────────────────────────────────
FILE 1: docs/spec/SPEC.md (the canonical specification)
────────────────────────────────────────────────
# [Project Name] Specification
## Overview
[One paragraph: what it is, what it does, who uses it]
## Vision
[What "done" looks like in 6–12 months — concrete, not aspirational]
## Current Phase: Phase [N] — [Phase Name]
**In scope:**
- [Feature 1]
- [Feature 2]
- ...
**Explicitly out of scope (this phase):**
- [Non-goal 1]
- [Non-goal 2]
## Functional Features
### F-001: [Feature Name]
Actor: [who triggers this]
Precondition: [what must be true before]
Flow:
1. [step]
2. [step]
Postcondition: [observable result]
Acceptance criteria:
- [ ] [testable criterion 1]
- [ ] [testable criterion 2]
[Repeat F-002, F-003... for each feature in scope]
## Non-Functional Requirements
### Performance
- P-001: [Primary endpoint] responds within [X ms] at [Y] concurrent users
- P-002: [Secondary endpoint] responds within [X ms]
### Reliability
- R-001: Error rate below [X]% over any 24-hour window
- R-002: Recovery from crash in under [X] minutes
### Security
- S-001: All routes require authentication except [list public routes]
- S-002: All user input validated at the trust boundary
- S-003: Secrets in environment variables, never in code or logs
### Scalability
- SC-001: Must support [X] concurrent users without horizontal scaling changes
## Tech Stack
- Language: [language + version]
- Runtime: [runtime]
- Framework: [framework]
- Database: [database + version]
- Deployment: [platform]
- Test framework: [framework]
- CI: [platform]
## Module Map
| Module | Responsibility | Key interfaces |
|--------|---------------|----------------|
| [name] | [one sentence] | [in/out contracts] |
## Quality Gates
- Test coverage minimum: 80%
- Max file length: 400 lines
- Max function length: 50 lines
- Commit format: Conventional Commits (feat/fix/chore/refactor/test/docs)
- Pre-commit: lint + type check
- CI: full test suite on every PR
## Constraints — The AI Must Never
- [Constraint 1 from interview answers]
- [Constraint 2]
- Never delete records without an explicit confirmation step in the prompt
- Never run database migrations without human review
- Never bypass authentication for convenience
────────────────────────────────────────────────
FILE 2: CLAUDE.md (Claude Code architectural constitution)
────────────────────────────────────────────────
# [Project Name] — Architectural Constitution
> Read SPEC.md before every session. This file is the grammar.
> SPEC.md is the source of truth. When in conflict, SPEC.md wins.
## Project
[One sentence from SPEC.md Overview]
## Architecture
[Key architectural decisions — derived from module map and tech stack]
- Layered: [describe the layers]
- Dependency direction: [e.g., domain → application → infrastructure, never reversed]
- [Other key constraints]
## Standards
- Language: [language], runtime: [runtime]
- Framework: [framework], database: [database]
- Test framework: [test framework]
- Coverage minimum: 80%
- Max file length: 400 lines, max function length: 50 lines
- Commit format: Conventional Commits
## Module Structure
[Mirror the module map from SPEC.md — one line per module]
## The AI Must Never
[Mirror the constraints from SPEC.md]
## Session Closing Checklist
- [ ] Tests pass
- [ ] No linting errors
- [ ] STATUS.md updated
- [ ] Commit follows Conventional Commits format
────────────────────────────────────────────────
FILE 3: AGENTS.md (OpenAI agents / any other assistant)
────────────────────────────────────────────────
[Same content as CLAUDE.md — identical constitution, different filename.
This ensures the project works with Claude Code, OpenAI agents, and
any assistant that reads a root-level AGENTS.md]
────────────────────────────────────────────────
FILE 4: STATUS.md (session continuity)
────────────────────────────────────────────────
# [Project Name] — Status
> Updated: [today's date]
## Current Phase
Phase [N]: [Phase Name]
## Last Session
[To be filled after first development session]
## In Progress
[To be filled when work begins]
## Completed
[Empty at project start]
## Next Session Entry Point
Read SPEC.md → read CLAUDE.md → begin at [first feature].
────────────────────────────────────────────────
FILE 5: docs/adrs/ADR-000-initial-architecture.md
────────────────────────────────────────────────
# ADR-000: Initial Architecture
Date: [today's date]
Status: Accepted
## Context
[Why were these architectural choices made? What alternatives were considered?]
## Decision
[The chosen architecture — reference SPEC.md Module Map]
## Consequences
[What this decision makes easy, and what it makes hard]
## Constraints Accepted
[The explicit non-goals from SPEC.md that shaped these choices]
────────────────────────────────────────────────
After writing all five files, print a summary table:
| File | Purpose | First session read order |
|------|---------|--------------------------|
| docs/spec/SPEC.md | Canonical specification | 1 |
| CLAUDE.md | Claude Code constitution | 2 |
| AGENTS.md | Other assistants constitution | 2 |
| STATUS.md | Session continuity | 3 |
| docs/adrs/ADR-000... | Architecture rationale | 4 |
Then print the first session prompt to paste into a new AI session:
"Read SPEC.md, then CLAUDE.md (or AGENTS.md), then STATUS.md. Confirm you
have read all three before beginning work. Ask me what to work on first."Genera el árbol sentinel GS completo para este proyecto.
Escribe los archivos en las rutas exactas indicadas abajo.
Usa las respuestas de nuestra entrevista. Si algo es ambiguo, enuncia tu supuesto
en un comentario dentro del archivo relevante. No hagas más preguntas.
────────────────────────────────────────────────
ARCHIVO 1: docs/spec/SPEC.md (la especificación canónica)
────────────────────────────────────────────────
# Especificación de [Nombre del Proyecto]
## Visión General
[Un párrafo: qué es, qué hace, quién lo usa]
## Visión
[Cómo se ve "listo" en 6–12 meses — concreto, no aspiracional]
## Fase Actual: Fase [N] — [Nombre de Fase]
**En alcance:**
- [Feature 1]
- [Feature 2]
- ...
**Explícitamente fuera de alcance (esta fase):**
- [No-objetivo 1]
- [No-objetivo 2]
## Funcionalidades
### F-001: [Nombre de Funcionalidad]
Actor: [quién la activa]
Precondición: [qué debe ser verdad antes]
Flujo:
1. [paso]
2. [paso]
Postcondición: [resultado observable]
Criterios de aceptación:
- [ ] [criterio verificable 1]
- [ ] [criterio verificable 2]
[Repetir F-002, F-003... para cada feature en alcance]
## Requerimientos No Funcionales
### Performance
- P-001: [Endpoint primario] responde en menos de [X ms] con [Y] usuarios concurrentes
- P-002: [Endpoint secundario] responde en menos de [X ms]
### Confiabilidad
- R-001: Tasa de error por debajo de [X]% en cualquier ventana de 24 horas
- R-002: Recuperación tras caída en menos de [X] minutos
### Seguridad
- S-001: Todas las rutas requieren autenticación excepto [listar rutas públicas]
- S-002: Todo input de usuario validado en el trust boundary
- S-003: Secretos en variables de entorno, nunca en código ni logs
### Escalabilidad
- SC-001: Debe soportar [X] usuarios concurrentes sin cambios de escalado horizontal
## Stack Tecnológico
- Lenguaje: [lenguaje + versión]
- Runtime: [runtime]
- Framework: [framework]
- Base de datos: [base de datos + versión]
- Despliegue: [plataforma]
- Framework de pruebas: [framework]
- CI: [plataforma]
## Mapa de Módulos
| Módulo | Responsabilidad | Interfaces clave |
|--------|----------------|-----------------|
| [nombre] | [una oración] | [contratos in/out] |
## Gates de Calidad
- Cobertura mínima de pruebas: 80%
- Longitud máxima de archivo: 400 líneas
- Longitud máxima de función: 50 líneas
- Formato de commit: Conventional Commits (feat/fix/chore/refactor/test/docs)
- Pre-commit: lint + type check
- CI: suite completa de pruebas en cada PR
## Restricciones — La IA Nunca Debe
- [Restricción 1 de las respuestas de entrevista]
- [Restricción 2]
- Nunca eliminar registros sin un paso explícito de confirmación en el prompt
- Nunca correr migraciones de base de datos sin revisión humana
- Nunca saltarse la autenticación por conveniencia
────────────────────────────────────────────────
ARCHIVO 2: CLAUDE.md (constitución arquitectónica para Claude Code)
────────────────────────────────────────────────
# [Nombre del Proyecto] — Constitución Arquitectónica
> Lee SPEC.md antes de cada sesión. Este archivo es la gramática.
> SPEC.md es la fuente de verdad. En conflicto, SPEC.md gana.
## Proyecto
[Una oración del Resumen de SPEC.md]
## Arquitectura
[Decisiones arquitectónicas clave — derivadas del mapa de módulos y el stack]
- En capas: [describe las capas]
- Dirección de dependencias: [p.ej., dominio → aplicación → infraestructura, nunca invertido]
- [Otras restricciones clave]
## Estándares
- Lenguaje: [lenguaje], runtime: [runtime]
- Framework: [framework], base de datos: [base de datos]
- Framework de pruebas: [framework]
- Cobertura mínima: 80%
- Longitud máxima de archivo: 400 líneas, longitud máxima de función: 50 líneas
- Formato de commit: Conventional Commits
## Estructura de Módulos
[Espeja el mapa de módulos de SPEC.md — una línea por módulo]
## La IA Nunca Debe
[Espeja las restricciones de SPEC.md]
## Checklist de Cierre de Sesión
- [ ] Pruebas pasan
- [ ] Sin errores de linting
- [ ] STATUS.md actualizado
- [ ] Commit sigue formato Conventional Commits
────────────────────────────────────────────────
ARCHIVO 3: AGENTS.md (agentes OpenAI / cualquier otro asistente)
────────────────────────────────────────────────
[Mismo contenido que CLAUDE.md — constitución idéntica, nombre de archivo diferente.
Esto asegura que el proyecto funcione con Claude Code, agentes OpenAI, y
cualquier asistente que lea un AGENTS.md en la raíz]
────────────────────────────────────────────────
ARCHIVO 4: STATUS.md (continuidad de sesión)
────────────────────────────────────────────────
# [Nombre del Proyecto] — Estado
> Actualizado: [fecha de hoy]
## Fase Actual
Fase [N]: [Nombre de Fase]
## Última Sesión
[Se llenará después de la primera sesión de desarrollo]
## En Progreso
[Se llenará cuando comience el trabajo]
## Completado
[Vacío al inicio del proyecto]
## Punto de Entrada para la Siguiente Sesión
Lee SPEC.md → lee CLAUDE.md → comienza en [primera feature].
────────────────────────────────────────────────
ARCHIVO 5: docs/adrs/ADR-000-arquitectura-inicial.md
────────────────────────────────────────────────
# ADR-000: Arquitectura Inicial
Fecha: [fecha de hoy]
Estado: Aceptado
## Contexto
[¿Por qué se tomaron estas decisiones arquitectónicas? ¿Qué alternativas se consideraron?]
## Decisión
[La arquitectura elegida — referencia el Mapa de Módulos de SPEC.md]
## Consecuencias
[Qué hace fácil esta decisión, y qué hace difícil]
## Restricciones Aceptadas
[Los no-objetivos explícitos de SPEC.md que moldearon estas elecciones]
────────────────────────────────────────────────
Después de escribir los cinco archivos, imprime una tabla resumen:
| Archivo | Propósito | Orden de lectura primera sesión |
|---------|-----------|--------------------------------|
| docs/spec/SPEC.md | Especificación canónica | 1 |
| CLAUDE.md | Constitución Claude Code | 2 |
| AGENTS.md | Constitución otros asistentes | 2 |
| STATUS.md | Continuidad de sesión | 3 |
| docs/adrs/ADR-000... | Rationale de arquitectura | 4 |
Luego imprime el prompt de primera sesión para pegar en una nueva sesión de IA:
"Lee SPEC.md, luego CLAUDE.md (o AGENTS.md), luego STATUS.md. Confirma que
has leído los tres antes de comenzar a trabajar. Pregúntame en qué trabajar primero."
For an existing project: replace "Generate" with "Read the codebase first, then generate SPEC.md from what you find, filling gaps with [TODO] markers where the intent is not clear from the code."
Para un proyecto existente: reemplaza "Genera" con "Lee la base de código primero, luego genera SPEC.md desde lo que encuentres, llenando huecos con marcadores [TODO] donde la intención no sea clara desde el código."
Step 03 — Cascade Infrastructure
Paso 03 — Infraestructura de Cascada
Same session · enforce doc-first discipline
Misma sesión · hacer cumplir la disciplina doc-first
Your sentinel tree is the specification. Now scaffold the folder structure, manifest, and git hooks that enforce the doc-first cascade on every commit going forward.
Tu árbol sentinel es la especificación. Ahora crea la estructura de carpetas, el manifest y los git hooks que hacen cumplir la cascada doc-first en cada commit de ahora en adelante.
03
In the same session, paste this cascade setup prompt.
En la misma sesión, pega este prompt de configuración de cascada.
Paste this — Cascade Infrastructure SetupPega esto — Configuración de Infraestructura de CascadaNow set up the cascade infrastructure for this project.
Use the project name, stack, and constraints from SPEC.md.
─────────────────────────────────────────────
1. FOLDER STRUCTURE
─────────────────────────────────────────────
Create these directories (add .gitkeep to each):
docs/specs/ feature-level spec files
docs/adrs/active/ open architecture decisions
docs/adrs/done/ closed or superseded ADRs
docs/use-cases/ UC-NNN detailed use case files
docs/schemas/ data schemas and ER diagrams
docs/decisions/ code-only change justifications
docs/edrs/ engineering decision records (spec changes)
─────────────────────────────────────────────
2. docs/manifest.yaml
─────────────────────────────────────────────
---
project: "[project name]"
version: "0.1.0"
phase: [phase number]
stack:
language: [language]
framework: [framework]
database: [database]
deployment: [deployment]
disciplines:
- solid
- tdd
- conventional-commits
- doc-first-cascade
- hexagonal-architecture
- adr-on-arch-change
cascade-rules:
feat: must touch docs/specs/ or create docs/edrs/ entry before code
fix: must add failing test before patch
refactor: should have docs/adrs/active/ entry
docs: documentation only — no production code changes
chore: tooling and config only
ai-never:
[list each item from SPEC.md Constraints section]
─────────────────────────────────────────────
3. .git/hooks/commit-msg (Conventional Commits)
─────────────────────────────────────────────
#!/usr/bin/env bash
msg=$(cat "$1")
pattern="^(feat|fix|chore|refactor|test|docs|style|ci|perf)(\(.+\))?: .{1,72}"
if ! echo "$msg" | grep -qE "$pattern"; then
echo "ERROR: Commit message must follow Conventional Commits."
echo " Format: type(scope): description"
echo " Types: feat fix chore refactor test docs style ci perf"
echo " Example: feat(auth): add JWT refresh token endpoint"
exit 1
fi
─────────────────────────────────────────────
4. .git/hooks/pre-commit (cascade check)
─────────────────────────────────────────────
#!/usr/bin/env bash
staged=$(git diff --cached --name-only)
src_changed=$(echo "$staged" | grep -E "^(src|app|lib|components|pages)/")
doc_changed=$(echo "$staged" | grep -E "^docs/")
if [ -n "$src_changed" ] && [ -z "$doc_changed" ]; then
today=$(date +%Y-%m-%d)
decision=$(ls docs/decisions/${today}-*.md 2>/dev/null | head -1)
if [ -z "$decision" ]; then
echo "⚠ Code changed without a doc update."
echo " Option A: update or create a file in docs/ in this commit."
echo " Option B: create docs/decisions/${today}-[reason].md"
echo " (one paragraph explaining why no doc update is needed)."
exit 1
fi
fi
Make both hooks executable:
chmod +x .git/hooks/commit-msg .git/hooks/pre-commit
─────────────────────────────────────────────
5. .github/workflows/ci.yml
─────────────────────────────────────────────
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install
run: [install command for this stack]
- name: Lint
run: [lint command]
- name: Test
run: [test command]
- name: Coverage
run: [coverage check — fail below 80%]
─────────────────────────────────────────────
After all files are created, confirm:
"Cascade infrastructure ready.
docs/ structure ✓ manifest.yaml ✓
commit-msg hook ✓ pre-commit cascade check ✓ CI workflow ✓"Ahora configura la infraestructura de cascada para este proyecto.
Usa el nombre del proyecto, stack y restricciones de SPEC.md.
─────────────────────────────────────────────
1. ESTRUCTURA DE CARPETAS
─────────────────────────────────────────────
Crea estos directorios (agrega .gitkeep a cada uno):
docs/specs/ archivos de spec a nivel de feature
docs/adrs/active/ decisiones de arquitectura abiertas
docs/adrs/done/ ADRs cerrados o supersedidos
docs/use-cases/ archivos de casos de uso UC-NNN detallados
docs/schemas/ esquemas de datos y diagramas ER
docs/decisions/ justificaciones de cambios solo-código
docs/edrs/ registros de decisión de ingeniería (cambios de spec)
─────────────────────────────────────────────
2. docs/manifest.yaml
─────────────────────────────────────────────
---
project: "[nombre del proyecto]"
version: "0.1.0"
phase: [número de fase]
stack:
language: [lenguaje]
framework: [framework]
database: [base de datos]
deployment: [despliegue]
disciplines:
- solid
- tdd
- conventional-commits
- doc-first-cascade
- hexagonal-architecture
- adr-on-arch-change
cascade-rules:
feat: debe tocar docs/specs/ o crear entrada en docs/edrs/ antes del código
fix: debe agregar test fallido antes del parche
refactor: debería tener entrada en docs/adrs/active/
docs: solo documentación — sin cambios a código de producción
chore: solo tooling y configuración
ai-never:
[listar cada item de la sección Restricciones de SPEC.md]
─────────────────────────────────────────────
3. .git/hooks/commit-msg (Conventional Commits)
─────────────────────────────────────────────
#!/usr/bin/env bash
msg=$(cat "$1")
pattern="^(feat|fix|chore|refactor|test|docs|style|ci|perf)(\(.+\))?: .{1,72}"
if ! echo "$msg" | grep -qE "$pattern"; then
echo "ERROR: El mensaje de commit debe seguir Conventional Commits."
echo " Formato: tipo(scope): descripción"
echo " Tipos: feat fix chore refactor test docs style ci perf"
echo " Ejemplo: feat(auth): agregar endpoint de refresh de JWT"
exit 1
fi
─────────────────────────────────────────────
4. .git/hooks/pre-commit (verificación de cascada)
─────────────────────────────────────────────
#!/usr/bin/env bash
staged=$(git diff --cached --name-only)
src_changed=$(echo "$staged" | grep -E "^(src|app|lib|components|pages)/")
doc_changed=$(echo "$staged" | grep -E "^docs/")
if [ -n "$src_changed" ] && [ -z "$doc_changed" ]; then
today=$(date +%Y-%m-%d)
decision=$(ls docs/decisions/${today}-*.md 2>/dev/null | head -1)
if [ -z "$decision" ]; then
echo "⚠ Código cambió sin actualización de docs."
echo " Opción A: actualiza o crea un archivo en docs/ en este commit."
echo " Opción B: crea docs/decisions/${today}-[motivo].md"
echo " (un párrafo explicando por qué no se necesita actualización de docs)."
exit 1
fi
fi
chmod +x .git/hooks/commit-msg .git/hooks/pre-commit
─────────────────────────────────────────────
5. .github/workflows/ci.yml
─────────────────────────────────────────────
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Instalar
run: [comando de instalación para este stack]
- name: Lint
run: [comando de lint]
- name: Tests
run: [comando de tests]
- name: Cobertura
run: [verificación de cobertura — fallar por debajo de 80%]
─────────────────────────────────────────────
Al terminar, confirmar:
"Infraestructura de cascada lista.
estructura docs/ ✓ manifest.yaml ✓
hook commit-msg ✓ pre-commit cascada ✓ CI workflow ✓"
The cascade check hook does not block all code-only commits — it requires a one-paragraph decision note in docs/decisions/ explaining why the change doesn't need a doc update. This leaves a trace without blocking emergency patches.
El hook de verificación de cascada no bloquea todos los commits solo-código — requiere una nota de decisión de un párrafo en docs/decisions/ explicando por qué el cambio no necesita una actualización de docs. Esto deja rastro sin bloquear parches de emergencia.
Step 04 — First Session
Paso 04 — Primera Sesión
Open a new session — the spec is the mold
Abre una sesión nueva — la especificación es el molde
04
Your specification is your mold. Open a new AI session, paste: "Read SPEC.md, then CLAUDE.md, then STATUS.md. Confirm you have read all three before beginning." The AI derives the implementation. You review intent, not code.
Tu especificación es tu molde. Abre una sesión nueva de IA, pega: "Lee SPEC.md, luego CLAUDE.md, luego STATUS.md. Confirma que leíste los tres antes de comenzar." La IA deriva la implementación. Tú revisas intención, no código.
Each session follows the same entry point: read SPEC.md → read CLAUDE.md → read STATUS.md → confirm → begin work. The architectural constitution tells the AI what it must never do. STATUS.md tells it where work left off. The spec tells it what to build. You never have to re-explain the project from scratch.
Cada sesión sigue el mismo punto de entrada: leer SPEC.md → leer CLAUDE.md → leer STATUS.md → confirmar → comenzar trabajo. La constitución arquitectónica le dice a la IA qué nunca debe hacer. STATUS.md le dice dónde quedó el trabajo. La spec le dice qué construir. Nunca tienes que re-explicar el proyecto desde cero.