chancy24/codex-knowledge-base-skill

Mantenedor de Base de Conocimiento del Proyecto

Propósito

Usa esta habilidad para inicializar, mantener y evolucionar una base de conocimiento a nivel de proyecto para agentes de codificación de IA. La base de conocimiento ayuda a futuras sesiones de agente a entender el propósito del proyecto, arquitectura, interfaces, decisiones, errores y cambios recientes sin tener que redescubrir todo desde cero.

Mantén el flujo de trabajo neutral en cuanto a la herramienta. Debería ser utilizable por Codex, Claude Code, Cursor, Gemini CLI y otros agentes de codificación que puedan leer archivos del proyecto y seguir instrucciones locales del repositorio.

Cuándo Usar

Usa esta habilidad cuando el usuario pida:

• inicializar una base de conocimiento del proyecto
• resumir o documentar un proyecto
• corregir un error y preservar la experiencia de reparación
• agregar o cambiar una funcionalidad
• agregar o cambiar una API, esquema, comando o formato de datos
• registrar una decisión técnica o compensación
• organizar materiales brutos del proyecto en conocimiento estructurado
• revisar o hacer retrospectiva de una sesión de desarrollo completada
• actualizar AGENTS.md o archivos bajo knowledge/

Entradas

Las entradas comunes incluyen:

• La ruta del repositorio actual o del proyecto de destino.
• Archivos de proyecto existentes, código fuente, documentación, incidencias, registros o materiales brutos.
• La tarea actual del usuario y cualquier cambio de implementación realizado durante la sesión.
• Contenido existente de AGENTS.md, knowledge/, raw/ o skills/ si está presente.

Salidas

Las salidas esperadas incluyen:

• AGENTS.md reglas del proyecto.
• knowledge/overview.md visión general del proyecto.
• knowledge/business.md lógica de negocio y escenarios de uso.
• knowledge/architecture.md arquitectura del sistema y flujo de datos.
• knowledge/api.md interfaces, esquemas, comandos y estructuras de datos.
• knowledge/decisions.md decisiones técnicas y compensaciones.
• knowledge/bugs.md historial de errores, causas raíz, correcciones y reglas de prevención.
• knowledge/changelog.md registros de cambios a nivel de sesión.
• Carpetas opcionales raw/ y skills/ locales del proyecto.
• Un informe final breve que enumere lo que se actualizó y lo que aún necesita verificación.

Flujo de Trabajo

1. Lee primero las reglas del proyecto:
   • AGENTS.md si está presente.
   • knowledge/overview.md
   • knowledge/architecture.md
   • knowledge/decisions.md
   • knowledge/bugs.md
2. Si se está inicializando un repositorio, usa las plantillas en references/templates/ o ejecuta el script de inicialización de este paquete.
3. Entiende la tarea actual e identifica qué cambió:
   • objetivo del proyecto o lógica de negocio
   • arquitectura o límites de módulos
   • API, comando, archivo de datos, esquema o estructura de retorno
   • síntoma de error, causa raíz, corrección o regla de prevención
   • decisión técnica o compensación
   • comportamiento visible para el usuario o convención de UI
4. Actualiza solo los archivos de conocimiento relevantes.
5. Elimina o reconcilia contenido duplicado, desactualizado o contradictorio.
6. Siempre actualiza knowledge/changelog.md después de trabajo importante.
7. Informa los archivos actualizados y cualquier validación faltante.

Para obtener una guía de mantenimiento más detallada, lee references/playbook.md.

Actualizando knowledge/

Usa el archivo más pequeño que coincida con el cambio:

• Actualiza overview.md para el propósito duradero del proyecto, alcance, módulos principales y salidas principales.
• Actualiza business.md para escenarios de usuario, flujos de trabajo, reglas de dominio y límites de seguridad.
• Actualiza architecture.md para relaciones entre módulos, flujo de datos, modos de ejecución y límites de integración.
• Actualiza api.md para endpoints, funciones, comandos, eventos, archivos de datos, esquemas y estructuras de retorno.
• Actualiza decisions.md para elecciones técnicas significativas y compensaciones.
• Actualiza bugs.md para errores confirmados y lecciones aprendidas.
• Actualiza changelog.md para cada resumen de tarea importante.

No vuelques razonamiento transitorio en la base de conocimiento. Prefiere hechos estables, decisiones validadas y lecciones reutilizables.

Retrospectivas de Errores

Cuando se corrija un error, actualiza knowledge/bugs.md con:

• Síntoma del problema.
• Causa raíz.
• Corrección.
• Alcance afectado.
• Validación realizada.
• Regla para prevenir la recurrencia.

Si la causa raíz es incierta, márcala como pendiente de verificación en lugar de adivinar.

Cambios de Interfaz

Cuando una API, comando, función, esquema, CSV, evento o formato de archivo cambie, actualiza knowledge/api.md con:

• Nombre de la interfaz.
• Método de solicitud o estilo de invocación.
• Ruta, comando, nombre de función o ruta de archivo.
• Entradas y parámetros.
• Formato de respuesta o salida.
• Notas, restricciones y ejemplos.

Usa nombres y ortografía de campos exactos.

Decisiones Técnicas

Cuando se tome una elección técnica significativa, actualiza knowledge/decisions.md con:

• Contexto de la decisión.
• Opciones consideradas.
• Elección final.
• Motivo de la elección.
• Consecuencias y trabajo de seguimiento.

Registra decisiones que ayudarán a futuros agentes a evitar reabrir preguntas ya resueltas.

Evitando la Degradación del Conocimiento

• Prefiere editar una entrada existente en lugar de agregar una entrada casi duplicada.
• Marca el contenido desactualizado como reemplazado o reemplázalo con el hecho actual.
• Mantén los hechos del proyecto separados de la especulación.
• Usa fechas para decisiones, errores y entradas del registro de cambios.
• Mantén la redacción neutral para el agente a menos que una integración específica de herramienta requiera una nota específica de la herramienta.
• No sobrescribas las reglas del proyecto creadas por el usuario sin una solicitud explícita.

Respuesta Final

Mantén la respuesta final concisa. Incluye:

• Archivos actualizados.
• Validación realizada.
• Cualquier verificación manual restante.