M3Configuración del entorno como sistema

Semana 2 de 4 Carga 2-3 horas Entregable Estructura base para cualquier proyecto nuevo

3.1 El problema del entorno sin sistema

Muchos desarrolladores que usan IA tienen el mismo patrón: abren el chat, escriben un prompt, reciben código, lo pegan, corrigen.

Cada conversación empieza desde cero. La IA no sabe nada del proyecto. No sabe qué patrones usas. No sabe qué ya existe. No sabe qué no tocar.

El resultado: cada sesión es un sprint de integración no planeado. La IA genera código genérico. Tú lo adaptas. Pierdes la mitad del tiempo en traducción.

SDD resuelve esto a nivel de spec. Pero si el entorno no está configurado, tienes que meter ese contexto en cada spec manualmente.

La solución: convertir el entorno en sistema. Que el contexto esté siempre disponible, estructurado, y que la IA lo consuma automáticamente.

Las tres capas trabajan juntas. Sin la primera, la IA improvisa. Sin la segunda, pierdes el hilo entre sesiones.

3.2 Las tres capas del entorno SDD

CAPA 1 — Memoria del proyecto
  CLAUDE.md / copilot-instructions.md
  Qué es el proyecto, stack, patrones, convenciones

CAPA 2 — Protocolo de trabajo
  Carpeta ai/ o specs/
  Specs, entregables, decisiones técnicas, historial

CAPA 3 — Automatizaciones
  Slash commands, skills, MCPs
  Flujos repetibles que la IA puede ejecutar con una instrucción

Las tres capas trabajan juntas. Sin la primera, la IA improvisa. Sin la segunda, pierdes el hilo entre sesiones. Sin la tercera, repites trabajo manual.

3.3 Capa 1: Memoria del proyecto

El archivo CLAUDE.md (o copilot-instructions.md)

Es el documento que le dice a la IA quién eres, qué es el proyecto y cómo trabajas. Se coloca en la raíz del proyecto.

Estructura recomendada:

# [NOMBRE DEL PROYECTO]

## Descripción
Qué hace el proyecto. Una o dos frases.

## Stack
- Frontend: Next.js 14, App Router, TypeScript, Tailwind
- Backend: API Routes / FastAPI
- Base de datos: Supabase / SQLite / Oracle
- Auth: NextAuth / Firebase Auth
- Deploy: Vercel / Cloudflare

## Arquitectura
Descripción de la estructura de carpetas relevante.
Qué va en /app, qué en /lib, qué en /components, qué en /types.

## Convenciones
- Nombres de archivos: kebab-case
- Nombres de componentes: PascalCase
- Hooks: useNombreDescriptivo
- No usar any en TypeScript
- Comentarios en español

## Patrones establecidos
- Fetching de datos: server components por defecto, client solo si necesita interactividad
- Estado global: Zustand (no Context API)
- Formularios: react-hook-form + zod
- Estilos: Tailwind utility-first, no CSS modules

## Lo que NO tocar
- /lib/db.ts — conexión a BD, no modificar sin spec explícita
- /types/supabase.ts — generado automáticamente, no editar a mano

## Contexto adicional
Cualquier cosa que la IA deba saber para no meter la pata.

Principio clave

El CLAUDE.md no es documentación para humanos. Es contexto para la IA. Escríbelo pensando en qué necesita saber la IA para no tener que preguntarte nada obvio.

3.4 Capa 2: Protocolo de trabajo — la carpeta ai/

La carpeta ai/ es el cerebro del proyecto desde el punto de vista de SDD. Es donde viven las specs, las decisiones y el historial.

Estructura recomendada

ai/
├── specs/
│   ├── pendientes/
│   │   └── feature-filtro-estado.spec.md
│   ├── en-progreso/
│   │   └── feature-login.spec.md
│   └── completadas/
│       └── feature-registro.spec.md
├── decisiones/
│   └── ADR-001-usar-supabase-vs-firebase.md
├── contexto/
│   └── modelo-datos.md
│   └── flujos-principales.md
└── plantillas/
    └── spec-template.md
    └── adr-template.md

Por qué este orden importa

El ciclo de vida de una spec es: pendiente → en progreso → completada. Tener carpetas separadas te da visibilidad de en qué estado está cada trabajo.

Las decisiones/ (ADR — Architecture Decision Records) documentan por qué se eligió algo. Cuando vuelvas a un proyecto 6 meses después, sabrás por qué hiciste lo que hiciste.

El contexto/ es complemento al CLAUDE.md para información más extensa (el modelo de datos completo, los flujos de usuario principales, etc.)

3.5 Capa 3: Automatizaciones

Slash commands (GitHub Copilot / Claude Code)

Son instrucciones predefinidas que puedes invocar con un comando corto. El principio generalizado:

/spec → genera el esqueleto de una spec para la feature que describes
/worklog → registra lo que hiciste en la sesión
/handoff → genera un resumen del estado actual para retomar mañana
/review → revisa el código generado contra la spec activa
/validate → corre los criterios de validación de la spec activa

Skills de Claude Code

Son instrucciones de comportamiento más profundas que los slash commands. Definen cómo la IA debe comportarse en un dominio concreto.

Ejemplo de skill para SDD:

# skill: spec-driven-implementation

Cuando recibas una spec:
1. Lee todos los bloques antes de generar código
2. Implementa solo lo que está en COMPORTAMIENTO ESPERADO
3. Respeta todas las RESTRICCIONES
4. Genera tests para todos los CRITERIOS DE VALIDACIÓN
5. No implementes nada que esté en FUERA DE ALCANCE
6. Si hay ambigüedad, pregunta antes de asumir

MCPs relevantes para SDD

Los MCPs (Model Context Protocol) permiten que la IA interactúe con sistemas externos. Para SDD, los más útiles son:

Filesystem MCP: lee y escribe archivos de specs directamente
Git MCP: consulta el historial de cambios para entender el contexto
Supabase MCP: puede consultar el esquema de BD sin que tú lo copies a la spec
Confluence/Atlassian MCP: si las specs viven en Confluence o Jira

3.6 Estructura de proyecto SDD — plantilla base

Esta es la estructura mínima para cualquier proyecto nuevo con SDD:

proyecto/
├── CLAUDE.md                    ← Memoria del proyecto
├── ai/
│   ├── specs/
│   │   ├── pendientes/
│   │   ├── en-progreso/
│   │   └── completadas/
│   ├── decisiones/
│   ├── contexto/
│   └── plantillas/
│       └── spec-template.md
├── .github/
│   └── copilot-instructions.md  ← Si usas GitHub Copilot
├── src/ (o app/)
└── ...resto del proyecto

3.7 Aplicado a tus proyectos actuales

Proyectos en repos corporativos

Ya tienes una carpeta ai/ con protocolo. Lo que falta:

Mover las specs a subcarpetas pendientes/en-progreso/completadas
Añadir un CLAUDE.md con el contexto de la migración a Python/FastAPI + Oracle
Crear el skill de SDD en .github/copilot-instructions.md

gowy.es

Crear CLAUDE.md con stack (Next.js 14, Supabase, TypeScript)
Crear carpeta ai/ con la spec del filtro de subastas del M2
Añadir ADR-001 con la decisión de usar Supabase vs. otra BD

Proyectos nuevos (Recepcionista Digital, CFO Personal, etc.)

Usar la plantilla base desde el primer commit
La spec de la primera feature va a ai/specs/en-progreso/ antes de escribir código

3.8 La plantilla de spec reutilizable

Guarda esto en ai/plantillas/spec-template.md en cada proyecto:

# SPEC: [TÍTULO — acción + resultado]

**Fecha:** YYYY-MM-DD
**Estado:** pendiente | en-progreso | completada
**Proyecto:** [nombre]
**Relacionada con:** [ticket Rally / issue GitHub / ADR]

---

## CONTEXTO
[Estado actual del sistema. Stack relevante. Archivos afectados.]

## OBJETIVO
[Por qué se hace esto. Valor de negocio o técnico. 1-2 frases.]

## COMPORTAMIENTO ESPERADO
[Qué tiene que hacer. Input → proceso → output. Todos los estados.]

## RESTRICCIONES
[Qué no puede hacer. Qué patrones debe respetar. Qué no debe tocar.]

## CASOS LÍMITE
[Situaciones no obvias. Qué pasa cuando algo falla o es inesperado.]

## CRITERIOS DE VALIDACIÓN
[Cómo se verifica. Tests concretos o criterios manuales verificables.]

## NOTAS TÉCNICAS
[Información técnica adicional. Referencias a código existente.]

## FUERA DE ALCANCE
[Qué no entra en esta spec. Límite explícito del trabajo.]

Ejercicio M3

Elige uno de tus proyectos activos (el que más uses ahora).
Crea la estructura de carpetas SDD en él (ai/, CLAUDE.md, plantillas).
Escribe el CLAUDE.md para ese proyecto.
Mueve o crea la spec del M2 dentro de ai/specs/en-progreso/.

Cuando lo tengas, comparte el contenido del CLAUDE.md en el chat. Lo revisamos y afinamos antes de pasar al M4.

Entregable M3

Contenido del CLAUDE.md de tu proyecto elegido. Guarda también la estructura de carpetas creada como: M3-Entregable-CLAUDE.md

Resumen del Módulo 3

El entorno SDD tiene tres capas: memoria del proyecto, protocolo de trabajo y automatizaciones.
CLAUDE.md es el documento de contexto que la IA consume en cada sesión.
La carpeta ai/ organiza specs por ciclo de vida: pendientes, en progreso, completadas.
Las decisiones técnicas se documentan en ADRs — para que el futuro tú sepa por qué.
Los slash commands y skills automatizan los flujos repetibles del ciclo SDD.
Esta estructura se aplica desde el primer commit, no cuando el proyecto ya es un caos.