Skip to content

README_ES.md

Latest commit

 

History

History
341 lines (241 loc) · 15.9 KB

README_ES.md

File metadata and controls

341 lines (241 loc) · 15.9 KB
Raw

🧰 AI Development Context Framework

Especificaciones, guardrails y memoria de proyecto para Agents de programación.

License: MIT Markdown Claude Code Edition Stars

Files Guardrails Triage Sync


🧭  ¿Tu Agent de programación pierde la intención del producto, las decisiones de arquitectura y el contexto de las tareas entre sesiones?
📚  ¿Un proyecto pequeño necesita una estructura ligera, mientras que uno mayor requiere especificaciones y entregas de contexto duraderas?
🔒  ¿Quieres que el Agent mantenga el progreso con libertad y proteja las decisiones que requieren aprobación?

✨ Convierte una conversación de producto en un sistema vivo de contexto para Agents de programación.

Conversar → especificar → inicializar → construir → mantener el contexto


🧩 Ediciones · ✨ Aspectos destacados · 🗺 Flujo · 📦 Archivos · ⚡ Instalación · 🚀 Uso · 🛡 Principios · 🎬 Ejemplo · 📂 Estructura · 📌 Notas

English · 简体中文 · Español · Deutsch · 日本語 · Русский · Português · 한국어

🧩 Elige una edición

Full Lite
Skills spec-gen, project-init, readme-craft spec-gen-lite, project-init-lite
Archivos del proyecto 3 archivos principales, hasta 9 cuando se activan 3 archivos principales
Modelo de tareas Cola priorizada, cabeceras de triaje, problemas, decisiones y entregas Cola por fases con tamaños [S/M/L/XL]
Opción adecuada Trabajo con varios módulos, proyectos largos, varias sesiones o entregas de equipo Proyectos individuales centrados, prototipos y ciclos de entrega cortos
Fuente de instalación skills/ lite/skills/

Ambas ediciones viven en este repositorio. Instala una sola edición en cada entorno de programación para mantener claros los dos pares de activadores de Skill que se solapan.

✨ Tres Skills, un framework

Skill Entrada Salida Lugar en el flujo
spec-gen Conversación de producto y restricciones Un SPEC.md estructurado Primero: definir el producto
project-init Un SPEC.md existente Archivos de orientación y gestión del proyecto Segundo: preparar el entorno de programación
readme-craft Datos del repositorio y público Un README.md de proyecto pulido Independiente: explicar públicamente el proyecto

La ruta principal de desarrollo utiliza spec-gen y después project-init. readme-craft es un Skill de documentación independiente incluido en el mismo repositorio.

🗺 Flujo de trabajo

flowchart LR
    A([Conversar sobre el producto]) --> B[spec-gen]
    B --> C[SPEC.md]
    C --> D[project-init]
    D --> E[CLAUDE.md]
    D --> F[TODO.md]
    D -. cuando sea necesario .-> G[ARCHITECTURE · SCHEMA · DESIGN]
    E --> H([Agent de programación])
    F --> H
    G --> H
    H -. primer problema .-> I[ISSUES.md]
    H -. primera decisión .-> J[DECISIONS.md]
    H -. entrega entre sesiones .-> K[PROGRESS.md]
    H --> L([Construir con contexto])

    M([Datos del repositorio]) --> N[readme-craft]
    N --> O[README.md]

    style A fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#000
    style B fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style C fill:#EDE9FE,stroke:#8B5CF6,stroke-width:2px,color:#000
    style D fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style E fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#000
    style F fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#000
    style G fill:#F8FAFC,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style H fill:#DCFCE7,stroke:#22C55E,stroke-width:2px,color:#000
    style I fill:#FEF2F2,stroke:#EF4444,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style J fill:#FFFBEB,stroke:#F59E0B,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style K fill:#F0FDF4,stroke:#22C55E,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style L fill:#DCFCE7,stroke:#22C55E,stroke-width:2px,color:#000
    style M fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#000
    style N fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style O fill:#EDE9FE,stroke:#8B5CF6,stroke-width:2px,color:#000
Loading

project-init lee el SPEC y decide cuánta estructura necesita el proyecto. También escribe reglas de mantenimiento en lenguaje natural dentro de CLAUDE.md. Un Agent que siga esas reglas puede crear archivos con estado cuando ocurra su primer desencadenante real; ningún hook de ejecución obliga a cumplir este comportamiento.

📦 Qué se genera

Archivos principales

Archivo Origen Propósito
SPEC.md spec-gen Alcance del producto, módulos, restricciones, necesidades de datos y límites del MVP
CLAUDE.md project-init Punto de entrada del Agent, permisos, mapa del repositorio y reglas de automatización
TODO.md project-init Cola priorizada con una sección centrada en la tarea actual

Se añaden cuando el SPEC los requiere

Archivo Desencadenante Propósito
ARCHITECTURE.md Tres o más módulos funcionales Estructura del sistema, dependencias, interfaces y flujo de datos
SCHEMA.md Una base de datos o un modelo de datos complejo Entidades, campos, restricciones, índices y migraciones
DESIGN.md Una interfaz de usuario Sistema visual, componentes, flujos, estados y comportamiento adaptable

Se crean durante el desarrollo

Archivo Primer desencadenante Propósito
ISSUES.md Un bug, problema técnico, limitación o pregunta abierta Seguimiento estructurado de problemas con estados e identificadores de módulo
DECISIONS.md Una decisión técnica o de arquitectura Registro de decisiones, opciones descartadas y nivel de reversibilidad
PROGRESS.md La primera entrega entre sesiones Fase actual, bloqueos, hitos y punto de reanudación

El framework comienza con tres archivos y puede crecer hasta nueve. Cada archivo adicional tiene un desencadenante concreto.

⚡ Instalación

Estas instrucciones instalan la edición Full. Para la configuración de tres archivos principales, usa la guía de instalación de Lite.

Da a Claude Code esta instrucción:

Elimina los cinco directorios de Skills Full y Lite gestionados del ámbito de destino y después instala los tres Skills Full desde https://github.com/okht/ai-dev-context-framework/tree/main/skills.

🛠️ Instalación manual

Clona el repositorio:

git clone --depth=1 https://github.com/okht/ai-dev-context-framework.git

Instala globalmente para Claude Code y limpia los Skills Lite gestionados:

bash ai-dev-context-framework/scripts/sync-skills.sh full

Instala en el proyecto actual y limpia los Skills Lite gestionados:

mkdir -p .claude/skills
rm -rf .claude/skills/spec-gen .claude/skills/project-init .claude/skills/readme-craft .claude/skills/spec-gen-lite .claude/skills/project-init-lite
cp -r ai-dev-context-framework/skills/* .claude/skills/

Inicia un nuevo turno de Claude Code después de la instalación para actualizar el índice de Skills.

Para desarrollar en este repositorio, el script de sincronización incluido copia los directorios actuales de skills/ a ~/.claude/skills/:

bash scripts/sync-skills.sh full

El script de sincronización elimina los cinco directorios gestionados de Skills Full y Lite y después copia la edición Full seleccionada. Los demás Skills globales permanecen en su sitio. Revisa el script y el destino antes de ejecutarlo.

Otras herramientas de programación con IA pueden utilizar directamente las instrucciones y plantillas Markdown. La detección de Skills y la sintaxis de invocación dependen del host.

🚀 Uso

1. Convierte la conversación en un SPEC

/spec-gen

También puedes pedirlo con lenguaje natural:

Convierte nuestra conversación de producto en un SPEC estructurado.

spec-gen escribe SPEC.md con una vista general del producto, módulos funcionales, requisitos no funcionales, necesidades de datos, restricciones técnicas, alcance del MVP y glosario.

2. Inicializa el contexto del proyecto

/project-init

project-init comprueba que exista SPEC.md, crea los archivos principales, evalúa los archivos condicionales e incorpora reglas de mantenimiento para el desarrollo posterior.

3. Crea una guía pública del proyecto

/readme-craft

Usa readme-craft de forma independiente cuando el repositorio necesite un README público claro basado en datos verificados del proyecto.

🛡 Principios de diseño

Principio Cómo lo aplica el framework
Estructura legible para LLM Encabezados estables, relaciones explícitas, tablas y reglas en texto plano
Permisos a nivel de instrucciones Las regiones bloqueadas y generadas indican al Agent qué espera el flujo que modifique
Separación entre procesos y decisiones El progreso rutinario puede avanzar con rapidez, mientras que los cambios de producto y arquitectura requieren aprobación
Archivos ajustados a la complejidad Los proyectos pequeños se mantienen ligeros; otros archivos aparecen a partir de señales explícitas
Tamaño de documento limitado Un SPEC de más de 300 líneas solicita una división por módulos en docs/spec/
Resúmenes deterministas Las cabeceras de estado se reconstruyen a partir de recuentos, módulos, identificadores y fechas

Zonas bloqueadas y generadas

Los archivos generados marcan sus límites con comentarios HTML:

<!-- 🔒 START 锁定区：规则 -->
Reglas que el Agent debe conservar
<!-- 🔒 END 锁定区：规则 -->

<!-- 🔓 START 生成区：项目内容 -->
Contenido específico del proyecto que el Agent puede mantener
<!-- 🔓 END 生成区：项目内容 -->

Las instrucciones generadas requieren confirmación del usuario antes de realizar cambios sustanciales en SPEC.md, ARCHITECTURE.md, SCHEMA.md, DESIGN.md y DECISIONS.md. Los archivos de proceso, como TODO.md, ISSUES.md y PROGRESS.md, están pensados para el mantenimiento rutinario por parte del Agent. Estos controles son convenciones en Markdown y dependen de que el Agent los cumpla.

Cabeceras de triaje rápido

TODO.md, ISSUES.md, PROGRESS.md y DECISIONS.md comienzan con un bloque de estado compacto y derivado mecánicamente.

Archivo Enfoque de la cabecera
TODO.md Número de tareas en curso, distribución del trabajo pendiente, siguiente acción y fecha de actualización
ISSUES.md Módulos activos, primer elemento relevante, recuentos por estado y bloqueos del MVP
PROGRESS.md Fase, avance del hito, bloqueos y punto de reanudación
DECISIONS.md Decisiones irreversibles, recuento y fecha de actualización

Cada plantilla incluye el algoritmo de reconstrucción en una sección bloqueada. Después de cambiar el cuerpo, el Agent vuelve a calcular la cabecera completa a partir de las entradas originales.

🎬 Ejemplo: ChatLens

El directorio examples/ contiene un conjunto completo para ChatLens, un producto ficticio de análisis de conversaciones B2B.

Qué muestra el ejemplo Contexto importante
Los nueve archivos del proyecto Se generaron juntos intencionadamente para mostrar todas las plantillas
Regiones bloqueadas y generadas El modelo de permisos en documentos realistas
Cabeceras de triaje y algoritmos Cómo los resúmenes de estado se mantienen derivados mecánicamente
Referencias entre archivos Cómo se conectan tareas, problemas, decisiones y progreso

Los proyectos reales siguen las reglas de activación. Un proyecto pequeño puede utilizar únicamente SPEC.md, CLAUDE.md y TODO.md.

📂 Estructura del proyecto

ai-dev-context-framework/
├── README.md
├── LICENSE
├── scripts/
│   └── sync-skills.sh
├── skills/
│   ├── spec-gen/
│   │   ├── SKILL.md
│   │   └── templates/SPEC.md.example
│   ├── project-init/
│   │   ├── SKILL.md
│   │   └── templates/*.md.example
│   └── readme-craft/
│       ├── SKILL.md
│       ├── agents/openai.yaml
│       ├── references/
│       │   ├── visual-system.md
│       │   └── verification.md
│       ├── scripts/validate_readme.py
│       └── templates/README.md.example
├── lite/
│   ├── README.md
│   ├── WORKFLOW.md
│   └── skills/
│       ├── spec-gen-lite/SKILL.md
│       └── project-init-lite/SKILL.md
└── examples/
    ├── SPEC.md
    ├── CLAUDE.md
    ├── TODO.md
    ├── ARCHITECTURE.md
    ├── SCHEMA.md
    ├── DESIGN.md
    ├── ISSUES.md
    ├── DECISIONS.md
    └── PROGRESS.md

El repositorio almacena Skills, plantillas reutilizables, un ejemplo completo y una herramienta de sincronización para desarrollo. No contiene un runtime de aplicación.

📌 Notas

  • spec-gen y project-init forman el flujo principal del proyecto.
  • readme-craft es un Skill independiente para redactar README.
  • lite/ es la edición de tres archivos principales mantenida en el mismo repositorio.
  • Instala la edición Full o Lite en cada entorno de programación para evitar activadores de Skill superpuestos.
  • project-init requiere un SPEC.md existente y completo.
  • El conjunto de nueve archivos de ChatLens es una muestra; la salida normal se ajusta a la complejidad del proyecto.
  • scripts/sync-skills.sh full|lite limpia la otra edición gestionada antes de copiar los Skills globales seleccionados.
  • El repositorio distribuye actualmente carpetas fuente de Skills y no publica versiones .skill empaquetadas.

Se aceptan incidencias y pull requests.

Mantén la intención del producto, el contexto de implementación y el estado del proyecto en el mismo sistema.


Licencia MIT © okht