Aaalexy/craft-codex-prompts

Craft Codex Prompts (Crear Prompts para Codex)

Objetivo

Convertir contexto incompleto en un paquete de tareas que otra conversación de Codex pueda ejecutar sin tratar la interpretación derivada como un hecho. Optimizar para fidelidad a la fuente, autoridad acotada, completitud verificable y baja sobrecarga de prompt.

Seleccionar la operación

• Borrador (Draft): Construir un prompt a partir de archivos, contexto del proyecto o una solicitud aproximada.
• Revisión (Review): Diagnosticar debilidades en un prompt existente y luego producir una versión revisada.
• Transferencia (Handoff): Convertir trabajo previo, resultados y problemas abiertos en el siguiente prompt ejecutable.
• Ciclo de conocimiento (Knowledge loop): Producir actualizaciones de estado actual, decisiones, problemas abiertos y transferencia listas para la base de conocimiento.

Si el usuario solo solicita un prompt, devuelve solo el prompt y las suposiciones esenciales. Si solicita un flujo de trabajo reutilizable, devuelve el paquete completo de tareas.

Flujo de trabajo

1. Establecer fuentes y autoridad

Inspecciona los archivos proporcionados por el usuario y el material accesible del proyecto en modo solo lectura antes de redactar, cuando esté autorizado y sea útil. No modifiques el proyecto fuente mientras prepares un prompt.

Clasifica las entradas:

• Hechos primarios: archivos actuales, estado del repositorio, declaraciones explícitas del usuario, documentos de proyecto autorizados.
• Contexto derivado: resúmenes, conclusiones anteriores del asistente, informes y chats copiados.
• Incógnitas: archivos faltantes, estado de ejecución no verificado, opciones no resueltas y dependencias externas.

Trata el contexto derivado como una pista, no como una prueba. Indica explícitamente que la conversación ejecutora debe verificarlo con las fuentes primarias.

No asumas que los archivos adjuntos en una conversación están disponibles en otra. Nombra cada archivo o espacio de trabajo exacto que la conversación ejecutora debe recibir.

2. Identificar el tipo de tarea

Elige el tipo de tarea más cercano:

• responder o explicar;
• inspeccionar o revisar;
• diagnosticar;
• cambiar o construir;
• investigar o comparar;
• crear un artefacto;
• realizar una acción externa.

Preserva el límite de autoridad correspondiente. Una solicitud para analizar o diagnosticar no autoriza ediciones. Una solicitud para cambiar o construir normalmente autoriza la implementación y verificación dentro del alcance, pero no refactorizaciones no relacionadas, publicaciones, mensajes, commits, envíos (pushes) o acciones destructivas.

Lee task-blueprints.md para ver la plantilla de tarea correspondiente.

3. Separar las reglas estables del delta de la tarea

Coloca las reglas duraderas del proyecto en un contrato del proyecto como AGENTS.md, PROJECT_BRIEF.md o CODEX_TASK_CONTRACT.md. Mantén el prompt actual enfocado en lo que ha cambiado esta vez.

Repite una regla estable en el prompt de la tarea solo cuando sea crítica para la seguridad o probable que se pase por alto.

4. Resolver la ambigüedad de forma proporcionada

Haz una pregunta aclaratoria solo cuando la respuesta pueda cambiar materialmente el alcance, la selección de fuentes, el comportamiento irreversible, los efectos externos o el estándar de aceptación. De lo contrario, elige la suposición razonable más segura y etiquétala.

Nunca ocultes una fuente faltante, una capacidad no soportada o un bloqueo externo dentro de un lenguaje seguro.

5. Componer el paquete de tareas

Crea estas secciones cuando sean relevantes:

1. Resultado: un estado final concreto.
2. Fuente de verdad: archivos exactos, rutas, datos o decisiones del usuario.
3. Estado actual: solo hechos verificados o claramente atribuidos.
4. Alcance: lecturas, ediciones, sistemas y artefactos permitidos.
5. No objetivos: expansiones probables pero no autorizadas.
6. Verificaciones adyacentes: superficies posteriores que pueden exponer el mismo defecto.
7. Guía de ejecución: restricciones que afectan la corrección, no detalles especulativos de implementación.
8. Aceptación: comprobaciones observables y evidencia esperada.
9. Bloqueos y condiciones de parada: condiciones que requieren informe en lugar de suposición.
10. Entrega: archivos modificados, artefactos, evidencia, limitaciones y próxima transferencia.

Usa la escalera de verificación L1-L4 cuando la implementación esté involucrada:

• L1: validación de sintaxis, importaciones, esquema o estática;
• L2: pruebas unitarias, de servicio o de regresión enfocadas;
• L3: validación de archivos reales o de ruta de datos de extremo a extremo;
• L4: UI real, tiempo de ejecución empaquetado, dispositivo, entorno similar a producción o aceptación humana.

No presentes un nivel inferior como prueba de un nivel superior.

Incluye esta cláusula de fidelidad a la fuente, adaptada a la tarea:

Trata este prompt como un resumen ejecutivo, no como una prueba del estado del repositorio. Verifica sus afirmaciones contra el espacio de trabajo actual y los archivos primarios. Si entran en conflicto, conserva el material fuente, reporta el conflicto y sigue la fuente primaria a menos que el usuario decida lo contrario.

6. Mantener el prompt ejecutable

• Comienza con el resultado.
• Usa instrucciones directas y sustantivos concretos.
• Prefiere nombres de archivo, rutas, conteos y artefactos esperados sobre adjetivos.
• Evita copiar chats en bruto a menos que el texto exacto sea en sí mismo evidencia.
• Evita prescribir arquitectura antes de la inspección a menos que el usuario haya fijado esa elección.
• Mantén las prohibiciones limitadas a modos de fallo realistas.
• Indica si Codex solo debe reportar, diagnosticar, implementar, o implementar y verificar.
• Termina con un formato de finalización compacto.

7. Auditar antes de la entrega

Evalúa internamente el prompt contra seis comprobaciones:

• Fidelidad: ¿Cada afirmación factual puede rastrearse hasta una fuente?
• Autoridad: ¿Las lecturas, ediciones, acciones externas y acciones prohibidas son inequívocas?
• Completitud: ¿Están cubiertos los consumidores adyacentes probables y las rutas de fallo?
• Testabilidad: ¿La finalización puede demostrarse con evidencia observable?
• Viabilidad: ¿Están expuestas las herramientas no disponibles, los límites de tiempo de ejecución y las dependencias humanas?
• Brevedad: ¿Cada instrucción cambia la ejecución o la verificación?

Devuelve un estado:

• READY: ejecutable con el contexto disponible;
• READY_WITH_ASSUMPTIONS: ejecutable después de enumerar suposiciones acotadas;
• NEEDS_INPUT: faltan una o más elecciones materiales;
• BLOCKED_SOURCE_MISSING: el material primario requerido no está disponible.

No infles el prompt solo para mejorar su rigor aparente.

8. Cerrar el ciclo de conocimiento

Cuando el usuario archive trabajo en Obsidian u otra base de conocimiento, lee obsidian-loop.md. Mantén los chats en bruto inmutables separados de la verdad actual del proyecto. Después de la ejecución, actualiza el estado actual, las decisiones, los problemas abiertos y la transferencia, en lugar de confiar solo en la transcripción.

Salida predeterminada

A menos que el usuario solicite otro formato, devuelve:

## TASK_BRIEF (RESUMEN_DE_TAREA)
[hechos verificados, suposiciones, incógnitas, fuentes]

## MAIN_PROMPT (PROMPT_PRINCIPAL)
[prompt listo para copiar]

## PROMPT_STATUS (ESTADO_DEL_PROMPT)
[READY, READY_WITH_ASSUMPTIONS, NEEDS_INPUT o BLOCKED_SOURCE_MISSING]
[breve explicación y cualquier adjunto requerido]

Para la revisión de prompts, añade una sección breve KEY_GAPS (BRECHAS_CLAVE) antes de MAIN_PROMPT. No expongas cadenas de pensamiento privadas; proporciona razones concisas y relevantes para la decisión.