jeffreyehogg/agent-skills

Desarrollo de Funciones Basado en Especificaciones

Resumen

Este skill impone un Protocolo de Control Planificar-Antes-de-Codificar. Los agentes de codificación autónomos a menudo fallan al saltar directamente a ediciones de archivos, lo que provoca desviación de contexto, APIs alucinadas y desperdicio de tokens en depuración por prueba y error.

Cuando este skill se activa, no se puede modificar ningún código de aplicación hasta que se redacte, verifique y apruebe una especificación formal (SPEC.md o .specs/<slug-de-funcion>.md).

---

1. Fase 1: Exploración de Contexto y Restricciones

Antes de redactar la especificación:

1. Identifique las convenciones existentes, modelos de datos y utilidades de API en el proyecto.
2. Localice definiciones de tipos o archivos de esquema (por ejemplo, schema.prisma, drizzle/schema.ts, esquemas Zod, especificaciones OpenAPI).
3. No lea archivos completos a menos que sea necesario; inspeccione exportaciones, encabezados de interfaz y tipos.

---

2. Fase 2: Redactar SPEC.md

Lea ./references/spec_template.md y cree .specs/<slug-de-funcion>.md (o SPEC.md en la raíz del repositorio si se solicita) siguiendo esa estructura exacta:

1. Objetivo, Criterios de Éxito y No-Objetivos Explícitos: Enunciado claro del problema de 2 oraciones, criterios de aprobación deterministas y límites explícitos fuera del alcance.
2. Contratos de Datos y Firmas: Interfaces TypeScript exactas, tipos de columnas de base de datos o esquemas de API.
3. Matriz de Límites de Modificación de Archivos: Rutas explícitas Crear, Modificar (con funciones/líneas objetivo) y Prohibidas.
4. Lista de Verificación de Implementación y Protocolo de Verificación: Comandos de prueba exactos, verificaciones de linter y casos límite.

---

3. Fase 3: El Punto de Control (OBLIGATORIO)

Una vez que se genera la especificación:

1. Modo Interactivo (Sesión de Usuario): Presente un resumen conciso con un enlace al archivo de especificación, exponga cualquier compromiso arquitectónico (utilizando ask_question si existen múltiples enfoques válidos) y solicite confirmación antes de escribir código:

   "He redactado la especificación en SPEC.md. Por favor, revise los contratos de datos propuestos y la matriz de límites de archivos. ¿Procedo con la implementación?"

2. Modo Subagente Autónomo: Si es invocado por un Orquestador Principal padre (por ejemplo, desde code-audit-orchestrator) que ya proporcionó un Plan de Corrección aprobado, verifique que la Matriz de Límites de Archivos no tenga conflictos con las rutas Prohibidas y proceda a la Fase 4.
3. PARADA FIRME: En sesiones interactivas, espere la aprobación o comentarios. No toque los archivos fuente hasta que se dé luz verde.

---

4. Fase 4: Ejecución por Fases y Protocolo de Enmienda Durante el Vuelo

Tras la aprobación:

1. Aislamiento de Sandbox Opcional: Para cambios de varios archivos o cuando el árbol de trabajo principal tenga cambios no relacionados, aprovisione un árbol de trabajo aislado mediante git-worktree-isolator antes de modificar los archivos.
2. Implemente la función en hitos discretos y atómicos (por ejemplo, Esquema $\to$ Lógica Central $\to$ Manejadores de API $\to$ UI/Integración).
3. Marque las casillas de progreso en el archivo de especificación a medida que se completan los hitos.
4. Mantenga las confirmaciones de git limitadas a hitos individuales.

Escotilla de Escape: Enmienda de Especificación Durante el Vuelo

Si la implementación descubre una restricción imprevista (por ejemplo, un archivo Prohibido debe modificarse, un tipo de SDK ascendente no coincide con el contrato redactado, o el usuario modifica los requisitos durante el vuelo):

1. Detenga las ediciones inmediatamente en el hito afectado.
2. Agregue una entrada en ## 6. Enmiendas de Especificación (Registro Delta) en el archivo de especificación documentando:
   • Desencadenante/Bloqueador: Por qué el contrato original no puede mantenerse.
   • Sección Enmendada y Delta: Cambios exactos en los Contratos de Datos o la Matriz de Límites de Modificación de Archivos.
3. Si el delta afecta a un archivo previamente Prohibido o altera un contrato de API/esquema público, pause y solicite confirmación rápida del usuario antes de reanudar. Si el delta es puramente interno (por ejemplo, extraer un archivo auxiliar interno), registre el delta en la especificación y continúe.

---

5. Fase 5: Verificación y Archivo

1. Ejecute el conjunto de pruebas determinista especificado en la Fase 2.
2. Verifique que todas las comprobaciones de tipos y linters pasen sin problemas.
3. Actualice el estado de la especificación a Completado y archívelo en .specs/completed/AAAA-MM-DD-<nombre-de-funcion>.md (o elimine los archivos de especificación temporales si el repositorio no rastrea .specs/).