Configurando el Contexto del Proyecto

Como la IA obtiene contexto

En versiones anteriores de OpenSpec, existian archivos como project.md y AGENTS.md que proporcionaban contexto a la IA. En la version actual (v1.2+), este contexto se gestiona de forma nativa para cada IDE mediante integraciones automaticas.

Para Claude Code, openspec init genera:

.claude/
├── commands/opsx/        # Slash commands con instrucciones detalladas
│   ├── propose.md
│   ├── explore.md
│   ├── apply.md
│   └── archive.md
├── skills/               # Skills que la IA invoca internamente
│   ├── openspec-propose/
│   ├── openspec-explore/
│   ├── openspec-apply-change/
│   └── openspec-archive-change/
└── CLAUDE.md             # Contexto general del proyecto

Cada herramienta (Cursor, Copilot, Windsurf, etc.) tiene su propia estructura equivalente.

El rol de CLAUDE.md

CLAUDE.md es el archivo que le da a Claude Code una comprension completa de tu proyecto. Piensa en el como la respuesta a: “Si un nuevo desarrollador se uniera hoy, que necesita saber?”

Toda decision que la IA tome se basa en la informacion de este archivo. Si esta incompleto, la IA tomara malas decisiones.

Que incluir

Un buen CLAUDE.md contiene:

# Mi Proyecto

## Tech Stack
- Runtime: Node.js 20.19, TypeScript 5.4 (strict mode)
- Frontend: React 19, Vite 6, Tailwind CSS 4
- Backend: Express 5, Prisma 6
- Base de datos: PostgreSQL 16
- Testing: Vitest (unit), Playwright (e2e)

## Arquitectura
Monorepo con dos packages:
- packages/api/ - Backend Express con patron MVC
- packages/web/ - Frontend React por feature

## Convenciones
- Archivos: kebab-case. Componentes: PascalCase
- Max 150 lineas por archivo
- Tests junto al archivo fuente

## Dominio
- Board: Tablero con columnas ordenables
- Column: Contenedor de cards con posicion
- Card: Unidad de trabajo con titulo, descripcion, tags

Secciones tipicas

Seccion	Contenido
Tech Stack	Tecnologias y versiones exactas
Arquitectura	Patron, organizacion de capas, estructura de directorios
Convenciones	Naming, formato, imports, limites
Dominio	Entidades, terminologia, reglas de negocio
Integraciones	APIs externas, servicios, autenticacion

Commands: Los slash commands

Los archivos en .claude/commands/opsx/ definen el comportamiento de cada comando. Cuando ejecutas /opsx:propose, Claude Code lee el archivo propose.md que contiene:

• Que hace: Crear un cambio y generar todos los artefactos
• Los pasos: Crear scaffold con openspec new change, consultar openspec status, generar artefactos en orden de dependencias
• Guardrails: No proceder sin entender que quiere el usuario, verificar cada artefacto

Estos archivos son generados por openspec init y se actualizan con openspec update.

Skills: Logica interna

Los skills en .claude/skills/ son invocados internamente por los commands. Mientras los commands son lo que tu ejecutas (/opsx:propose), los skills son la logica detallada que la IA sigue.

No necesitas modificar los skills directamente. Se actualizan automaticamente con:

openspec update

config.yaml: Contexto para OpenSpec

Ademas de CLAUDE.md, OpenSpec tiene su propio archivo de contexto en openspec/config.yaml. Mientras CLAUDE.md es especifico de Claude Code, config.yaml funciona con todas las herramientas soportadas.

# Contexto del proyecto (se inyecta en openspec instructions)
context: |
  Proyecto Kanban con TypeScript, React y Express.
  Base de datos PostgreSQL con Drizzle ORM.
  Idioma: Espanol.

# Reglas especificas por artefacto
rules:
  proposal: |
    Mantener bajo 500 palabras.
  specs: |
    Formato Given/When/Then obligatorio.
  design: |
    Incluir paths de archivos nuevos.
  tasks: |
    Maximo 10 tareas por cambio.

El campo context es lo que openspec instructions envia a la IA al generar artefactos. Las rules son restricciones adicionales por tipo de artefacto.

Soporte multi-idioma: Agrega Idioma: Espanol en el campo context para que todos los artefactos se generen en tu idioma.

Schemas: Flujos de trabajo configurables

Los schemas definen que artefactos genera cada cambio y en que orden. El schema por defecto es spec-driven:

proposal → specs → design → tasks

Referencia: openspec schemas

Opcion	Descripcion
--json	Salida en JSON para uso programatico

Referencia: openspec schema <subcomando>

Subcomando	Opciones	Descripcion
init <nombre>	--artifacts <lista>, --description <texto>, --default, --force	Crea un schema nuevo en el proyecto
fork <base> [nombre]	--force, --json	Copia un schema existente para personalizarlo
validate [nombre]	--verbose, --json	Valida estructura y templates de un schema
which [nombre]	--all, --json	Muestra de donde se resuelve un schema

openspec schemas                          # Ver schemas disponibles
openspec schema init mi-workflow          # Crear schema nuevo
openspec schema fork spec-driven rapido   # Copiar schema para customizar
openspec schema validate mi-workflow      # Validar estructura

openspec instructions: Contexto enriquecido

El comando openspec instructions es la pieza clave que conecta el CLI con la IA. Cuando la IA necesita crear un artefacto, ejecuta:

openspec instructions <artefacto> --change "<nombre>" --json

Referencia: openspec instructions [artefacto]

Opcion	Descripcion
--change <id>	Nombre del cambio (obligatorio en modo no interactivo)
--schema <name>	Override del schema (auto-detectado desde config.yaml)
--json	Salida en JSON para consumo por agentes

El argumento artefacto puede ser: proposal, specs, design, tasks o apply (caso especial para instrucciones de implementacion).

La salida JSON incluye:

• context: Informacion del proyecto desde config.yaml
• rules: Reglas del artefacto desde config.yaml
• template: Estructura que debe seguir el archivo
• instruction: Guia especifica del schema
• outputPath: Donde escribir el artefacto
• dependencies: Artefactos completados para leer como contexto

openspec status: Seguimiento de artefactos

Referencia: openspec status

Opcion	Descripcion
--change <id>	Nombre del cambio (interactivo si se omite)
--schema <name>	Override del schema
--json	Salida en JSON

openspec status                              # Interactivo
openspec status --change "setup-data-model"  # Cambio especifico
openspec status --change "setup-data-model" --json  # Para agentes

Muestra que artefactos estan completos (done), cuales estan listos (ready) y cuales bloqueados por dependencias (blocked).

Actualizar tras upgrade del CLI

Cuando actualizas OpenSpec a una nueva version, ejecuta:

npm install -g @fission-ai/openspec@latest
openspec update

Esto regenera los commands y skills con las instrucciones mas recientes sin perder tu configuracion personalizada.

Errores comunes

CLAUDE.md demasiado generico

## Tech Stack
- JavaScript
- React
- Node.js

Esto no le dice nada util. Especifica versiones, variantes (TypeScript vs JavaScript), herramientas exactas.

No ejecutar openspec update

Si actualizas el CLI pero no ejecutas openspec update, los commands y skills de tu proyecto quedaran desactualizados. Hazlo siempre despues de un upgrade.

Confundir commands con skills

Los commands son lo que tu ejecutas (ej: /opsx:propose). Los skills son logica interna que la IA invoca. No necesitas modificar los skills manualmente.

Resumen

• El contexto del proyecto se gestiona mediante integraciones nativas del IDE
• CLAUDE.md contiene el contexto global: stack, arquitectura, convenciones, dominio
• Commands (.claude/commands/opsx/) definen los slash commands
• Skills (.claude/skills/) contienen la logica detallada interna
• Schemas definen el flujo de artefactos (configurable)
• openspec instructions proporciona contexto enriquecido a la IA
• openspec update mantiene todo sincronizado tras upgrades

---

Capitulo 2: Instalacion y Estructura | Siguiente -> Capitulo 4: Primer Cambio con Propose