Este repositorio contiene un conjunto completo de reglas de desarrollo, estándares y configuraciones de agentes de IA diseñados para funcionar a la perfección con múltiples copilotos de codificación por IA. La configuración es portátil y puede importarse a cualquier proyecto para proporcionar un desarrollo asistido por IA consistente y de alta calidad.

Se recomienda encarecidamente utilizarlo junto con frameworks de Desarrollo Guiado por Especificaciones (Spec-Driven Development) como OpenSpec.

.
├── ai-specs/                    # Directorio principal con todas las reglas y configuraciones
│   ├── specs/                   # Estándares de desarrollo y especificaciones
│   │   ├── base-standards.mdc   # Reglas core de desarrollo (única fuente de verdad)
│   │   ├── backend-standards.mdc
│   │   ├── frontend-standards.mdc
│   │   ├── documentation-standards.mdc
│   │   ├── api-spec.yml         # Especificación OpenAPI
│   │   ├── data-model.md        # Modelos de base de datos y dominio
│   │   └── development_guide.md
│   ├── .commands/               # Prompts de comandos reutilizables (plan, develop, enrich, etc.)
│   ├── .agents/                 # Definiciones de roles de agentes (backend, frontend, analista, etc.)
│   └── changes/                 # Planes de implementación de funcionalidades
│       └── SCRUM-10_backend.md  # Demo: Plan de funcionalidad de actualización de posición
│
├── AGENTS.md                    # Configuración genérica de agentes
├── CLAUDE.md                    # Configuración específica para Claude
├── codex.md                     # Configuración para GitHub Copilot/Codex
└── GEMINI.md                    # Configuración específica para Gemini

Este repositorio utiliza enlaces simbólicos o convenciones de nomenclatura para soportar múltiples copilotos de codificación por IA sin duplicaciones:

• AGENTS.md → Reglas genéricas de agentes (funciona con la mayoría de los copilotos)
• CLAUDE.md → Optimizado para Claude/Cursor
• codex.md → Optimizado para GitHub Copilot/Codex
• GEMINI.md → Optimizado para Google Gemini

Todos estos archivos hacen referencia a las mismas reglas core en ai-specs/specs/base-standards.mdc, garantizando la consistencia entre diferentes herramientas de IA y permitiendo personalizaciones específicas para cada copiloto.

✅ Única Fuente de Verdad: Reglas core mantenidas en un solo lugar (base-standards.mdc)
✅ Compatibilidad con Copilotos: Cada herramienta de IA encuentra su configuración usando su convención de nomenclatura preferida
✅ Configuración Cero: Se importa en un nuevo proyecto y funciona inmediatamente
✅ Actualizaciones Fáciles: Actualiza las reglas una vez y todos los copilotos se benefician
✅ Portátil: Copia esta estructura a cualquier proyecto

# Clona o copia este repositorio en tu proyecto
cp -r LIDR-ai-specs/* tu-proyecto/

# El copiloto de IA detectará automáticamente el archivo de configuración relevante

Tu copiloto de IA cargará automáticamente:

• Claude/Cursor: CLAUDE.md → ai-specs/specs/base-standards.mdc
• GitHub Copilot: codex.md → ai-specs/specs/base-standards.mdc
• Gemini: GEMINI.md → ai-specs/specs/base-standards.mdc

Todas las rutas y reglas están configuradas para funcionar sin problemas y sin ajustes manuales.

La forma más eficiente de trabajar con esta configuración es utilizando un flujo de trabajo basado en comandos:

Si tu user story carece de detalles o criterios de aceptación, usa el comando enrich-us para mejorarla:

/enrich-us SCRUM-10

Este comando analiza la user story y genera:

• Criterios de aceptación detallados
• Casos borde y reglas de validación
• Consideraciones técnicas
• Escenarios de prueba

Nota: Omite este paso si tu user story ya tiene suficiente profundidad y requisitos claros.

Usa los comandos plan-ticket para generar planes detallados de implementación:

plan-backend-ticket SCRUM-10

o

plan-frontend-ticket SCRUM-15

Esto crea un plan de implementación completo y paso a paso en ai-specs/changes/.

Referencia el plan generado y ejecuta:

develop-backend @SCRUM-10_backend.md

o

develop-frontend @SCRUM-15_frontend.md

La IA seguirá el plan con precisión, implementando cada paso con TDD, pruebas adecuadas y actualizaciones de documentación.

Tú dices:

/enrich-us SCRUM-10

La IA mejora la user story con criterios de aceptación detallados y consideraciones técnicas (omitir si ya es detallada).

Tú dices:

/plan-backend-ticket SCRUM-10

La IA genera:

• Analiza los requisitos del ticket
• Crea ai-specs/changes/SCRUM-10_backend.md con:
  • Contexto de arquitectura
  • Instrucciones de implementación paso a paso
  • Especificaciones completas de pruebas (capas de validación, servicio, controlador)
  • Actualizaciones de documentación de la API
  • Reglas de validación
  • Estrategias de manejo de errores

Tú dices:

/develop-backend @SCRUM-10_backend.md

La IA ejecuta:

1. Crea la rama de funcionalidad feature/SCRUM-10-backend
2. Implementa la función de validación con reglas completas
3. Implementa la capa de servicio con la lógica de negocio
4. Implementa el controlador con el manejo de HTTP
5. Añade la configuración de rutas
6. Escribe más del 90% de cobertura de pruebas en todas las capas
7. Actualiza la documentación de la API
8. Ejecuta las pruebas y verifica la implementación
9. Realiza el commit y push (configurable para esperar hasta la confirmación)

Consulta ai-specs/changes/SCRUM-10-Position-Update.md para ver un ejemplo completo de cómo se ve una user story enriquecida. Este documento exhaustivo incluye:

• User Story: Descripción clara con persona, objetivo y beneficio
• Especificación Técnica: Detalles completos de la implementación técnica
• Documentación de Endpoint de API: Formatos de petición/respuesta, códigos de estado y manejo de errores
• Campos de Base de Datos: Todos los campos actualizables con reglas de validación
• Reglas de Validación: Requisitos de validación en el lado del servidor y del cliente
• Requisitos de Seguridad: Necesidades de autenticación, autorización y sanitización de entradas
• Requisitos de Pruebas: Pruebas unitarias, pruebas de integración y escenarios de pruebas manuales
• Criterios de Aceptación: Criterios claros y testeables para cada requisito
• Requisitos No Funcionales: Estándares de usabilidad, rendimiento, fiabilidad y seguridad
• Definición de Hecho (Definition of Done): Lista de verificación completa para la finalización de la funcionalidad

Este documento enriquecido transforma una simple user story en una especificación detallada que proporciona todo el contexto necesario para la implementación autónoma por parte de agentes de IA o desarrolladores.

Consulta ai-specs/changes/SCRUM-10_backend.md para ver un ejemplo completo de cómo se ve un plan de implementación de funcionalidad. Este plan exhaustivo incluye:

• Contexto de Arquitectura: Capas, componentes y dependencias
• Instrucciones Paso a Paso: Validación → Servicio → Controlador → Rutas → Pruebas → Documentación
• Ejemplos de Código Completos: Implementaciones completas para cada capa
• Especificaciones Exhaustivas de Pruebas: Requisitos de más del 90% de cobertura con ejemplos de pruebas
• Manejo de Errores: Códigos de estado HTTP, mensajes de error y formatos de respuesta
• Reglas de Negocio: Requisitos de validación y restricciones
• Lista de Verificación de Pruebas: Pruebas unitarias, manuales, de integración y de regresión

Este plan demuestra cuán detallados y accionables son los planes generados, permitiendo la implementación autónoma por parte de agentes de IA.

Todo desarrollo sigue los principios definidos en ai-specs/specs/base-standards.mdc:

1. Tareas Pequeñas, Una a la Vez: Pequeños pasos, nunca saltarse ninguno
2. Desarrollo Guiado por Pruebas (TDD): Escribir primero las pruebas que fallan
3. Seguridad de Tipos: Código completamente tipado (TypeScript)
4. Nombres Claros: Variables y funciones descriptivas
5. Solo Inglés: Todo el código, comentarios, documentación y mensajes en inglés
6. +90% de Cobertura de Pruebas: Pruebas exhaustivas en todas las capas
7. Cambios Incrementales: Modificaciones enfocadas y revisables

• Estándares de Backend: ai-specs/specs/backend-standards.mdc

  • Patrones de desarrollo de API
  • Mejores prácticas de base de datos
  • Directrices de seguridad
  • Requisitos de pruebas

• Estándares de Frontend: ai-specs/specs/frontend-standards.mdc

  • Patrones de componentes React
  • Directrices de UI/UX
  • Gestión de estado
  • Pruebas de componentes

• Estándares de Documentación: ai-specs/specs/documentation-standards.mdc

  • Estructura de documentación técnica
  • Documentación de API (OpenAPI)
  • Documentación de código
  • Directrices de mantenimiento

• ✅ Calidad de Código Consistente: La IA sigue los mismos estándares cada vez
• ✅ Pruebas Exhaustivas: Cobertura automática de más del 90% en todas las capas
• ✅ Documentación Completa: Especificaciones de API actualizadas automáticamente
• ✅ Incorporación más Rápida: Los nuevos miembros del equipo consultan las mismas reglas
• ✅ Tiempo de Revisión Reducido: El código sigue patrones establecidos

• ✅ Flexibilidad de Copiloto: Los miembros del equipo pueden usar su herramienta de IA preferida
• ✅ Preservación del Conocimiento: Estándares documentados, no en la cabeza de las personas
• ✅ Consistencia de Calidad: Mismos estándares independientemente de quién (o qué) escriba el código
• ✅ Revisiones de Código más Fáciles: Expectativas y patrones claros
• ✅ Prácticas Escalables: Los estándares escalan con el equipo

• ✅ Base de Código Mantenible: Arquitectura limpia y clara separación de conceptos
• ✅ Código Listo para Producción: TDD, manejo de errores y validación integrados
• ✅ Documentación Viva: Especificaciones de API y modelos de datos siempre actualizados
• ✅ Desarrollo de Funcionalidades más Rápido: Implementación autónoma de la IA a partir de planes
• ✅ Menor Deuda Técnica: Mejores prácticas aplicadas desde el primer día

1. Actualizar el contexto técnico: Busca los diferentes archivos en ai-specs/specs y modifica los principios core, los estándares de codificación, las reglas de negocio y la documentación técnica para adaptarlos a tus necesidades:
   • estándares de backend/frontend/pruebas/documentación
   • guía de instalación
   • modelo de datos
   • documentación de API
   • ...
2. Adaptar agentes en ai-specs/.agents: Ajusta las definiciones de los agentes a los roles y flujos de trabajo de tu proyecto
3. Extender Comandos: Define prompts probados en batalla en comandos dentro de ai-specs/.commands
4. Enlazar Recursos: Referencia la documentación específica o tareas de tu proyecto usando MCPs
5. Mantener la estructura de enlaces simbólicos: Recuerda crear enlaces simbólicos relativos desde las carpetas de claude y cursor a los agentes o comandos recién creados para mantener la consistencia

• Única Fuente de Verdad: Actualiza siempre base-standards.mdc primero
• Control de Versiones: Rastrea los cambios en los estándares como si fuera código
• Revisión del Equipo: Los cambios en los estándares deben revisarse como las pull requests
• Documentación: Mantén los ejemplos actualizados con la implementación real

Los siguientes archivos se incluyen como ejemplos de referencia del proyecto LIDR. Debes crear tus propias versiones adaptadas a tu proyecto específico:

• Especificación de API: ai-specs/specs/api-spec.yml (formato OpenAPI 3.0)
  • Crea tu propia especificación de API documentando los endpoints de tu proyecto
• Modelos de Datos: ai-specs/specs/data-model.md (Esquemas de base de datos, modelos de dominio)
  • Documenta tu estructura de base de datos y entidades de dominio
• Guía de Desarrollo: ai-specs/specs/development_guide.md (Instalación, flujos de trabajo)
  • Escribe instrucciones de instalación específicas para tu stack tecnológico

Al contribuir a los estándares:

1. Actualiza base-standards.mdc (fuerza de verdad única)
2. Prueba con múltiples copilotos de IA para asegurar la compatibilidad
3. Actualiza los ejemplos en la carpeta changes/ si es necesario
4. Documenta los cambios que rompan la compatibilidad (breaking changes) claramente
5. ¡Sigue los mismos estándares que estás definiendo!

Copyright (c) 2025 LIDR.co Licenciado bajo la Licencia MIT

English:

The content of this repository is part of the AI4Devs program by LIDR.co. If you want to learn to code with AI like the pros and get more templates and resources like these, you can find all the information on the official website: https://lidr.co/ia-devs

Español:

El contenido de este repositorio es parte del programa AI4Devs de LIDR.co. Si quieres aprender a programar con IA como los pros, y obtener más plantillas y recursos como estos, puedes encontrar toda la información en la página oficial: https://lidr.co/ia-devs

Hecho con 🤖 por la comunidad de LIDR

Para preguntas, problemas o sugerencias, visita LIDR.co