Agent DX (Experiencia de Agente)
La experiencia de desarrollo de una superficie donde un agente de IA es el desarrollador — un SDK, herramienta, salida estructurada, envoltura de errores o telemetría que un agente consume para construir con ella o actuar a través de ella. La procedencia vive en skill.json; este archivo es solo enrutamiento en tiempo de ejecución.
Produce: un change-plan.md (HACER), un audit-report.md más un ledger de hallazgos + estado del flujo de trabajo cuando se rastrea (REVISAR), o un design-doc.md / refactor-runbook.md / explanation.md (DISEÑAR).
Principio central
Un agente consume la superficie solo, a velocidad de máquina, sin ningún tooltip al que recurrir. Por lo tanto, la barra para cualquier SDK, herramienta, error o span es si un consumidor estocástico puede analizarlo, recuperarse de él y no ser dañado por él: contratos tipados sobre prosa; recuperación diseñada, no esperada; el límite de confianza cerrado por defecto. Se sitúa sobre el piso de cliente HTTP que poseen dx-audit / dx-design, sin reemplazarlo nunca.
Activación
- Invocación simple (
"use agent-dx","start"): muestra un menú compacto: elección de modo (guiado / piloto automático / ¿gríllame?) e intenciones numeradas desde el enrutador. Espera. Sin inspección de archivos, sin llamadas de red, sin escrituras. - Invocación concreta con intención y superficie inferible: salta al paso 3.
- Invocación ambigua: pregunta una vez — p. ej., "¿Estás auditando un SDK, un esquema de herramienta, una envoltura de salida estructurada o una superficie de telemetría?" o "¿Es esto una revisión de contrato/recuperación o una auditoría de límite de confianza?"
Flujo de trabajo
- Elegir intención. Carga
references/intent-router.csv; coincide condo,reviewodesign. Ambiguo → pregunta una vez. - Elegir superficie. Carga
references/intents/<intent>.csv; coincide con una o más desdk-design,tools-and-mcp,structured-output,errors-and-retry,sdk-telemetry— oallpara un despliegue en abanico de REVISIÓN. Ambiguo → pregunta una vez con el menú. - Cargar contexto fundamentado. Carga solo el
playbookde la fila elegida más suscore_refs. No cargues otros playbooks (la filareview/allno lleva ninguno — cada agente de superficie carga el suyo; ver paso 6). - Identificar la persona objetivo desde
references/core/personas.md. - Luego calibrar según la escala del proyecto (REVISIÓN / DISEÑO) según
references/calibration.md: por debajo de Carga-Estructural, acota el alcance, colapsa brechas del mismo mecanismo en un único hallazgo sistémico y divide Ahora vs Después (a medida que crece). El nivel alimenta la emisión, nunca la severidad. - Despachar lentes en paralelo (REVISIÓN por defecto cuando está permitido): una superficie por agente para
all; en caso contrario, las tres lentes siguientes. Retroceso secuencial si no hay primitiva de delegación. - Aplicar el playbook. Usa las heurísticas etiquetadas para la intención. Para REVISIÓN, puntúa cada
superficie de 0 a 10 (
references/core/score-rubric.md); sintetiza los hallazgos de las lentes, preservando desacuerdos como preguntas abiertas. Aplica severidad e IDs establesAGENT-DX-<surface>-NNN(references/core/severity-rubric.md):AGENT-DX-SDK,AGENT-DX-TOOL,AGENT-DX-OUT,AGENT-DX-ERR,AGENT-DX-TEL. - Emitir. HACER →
templates/change-plan.md. REVISAR →templates/audit-report.md. DISEÑAR →templates/design-doc.md(forma),templates/refactor-runbook.md(secuencia de endurecimiento) otemplates/explanation.md(explicar un principio). - Crear, reanudar o cerrar estado de seguimiento (REVISAR). Para una auditoría con 7+ hallazgos, cualquier
severidad 3–4, o una solicitud de guardar/rastrear/cerrar, carga
references/trackable-findings.md. Si la solicitud nombra un ledger existente, estado del flujo de trabajo, PR o IDAGENT-DX-*, lee el estado guardado primero; actualiza los estados solo después de que cada regla de verificación pase. De lo contrario, escribe el ledger endocs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.mdy el estado del flujo de trabajo endocs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json(opta poraudit-artifacts/agent-dx-...sidocs/audits/no se puede escribir). Reporta ambas rutas; mantén hojas de ruta, incidencias y ediciones no relacionadas con el seguimiento como opt-in.
¿Dirección incorrecta? Si el usuario dice que esto no es lo que quería, vuelve al paso 1 (Elegir intención) — no parchees en la dirección incorrecta. Replantea la comprensión corregida y vuelve a planificar.
Modos
Borrador Guiado (por defecto), Piloto Automático, Gríllame — consulta references/modes.md. Ofrece en
invocación simple; por defecto a Borrador Guiado en invocaciones concretas.
Requisitos de salida
Cada salida nombra la intención, superficie(s), persona, playbook(s) aplicados y fuentes de fundamentación
desde skill.json; REVISAR añade severidad + verificación por hallazgo y el nivel del proyecto.
Nombra las garantías de consumibilidad por agente que deliberadamente NO estás añadiendo (YAGNI), no solo
las que estás añadiendo.
Despacho de subagentes
Por defecto para REVISAR cuando la delegación está permitida; saltar trabajos pequeños o con secretos. Genera
tres lentes en paralelo — contrato-y-esquema (esquemas tipados desde código, envoltura de error estable,
salida validada), recuperación-del-agente (detener+verificar, errores con forma de reintento, reintento
semántico, bucle acotado), confianza-y-aislamiento (inyección de metadatos de herramienta, puntos de
control de guardarraíles, muros de credenciales, redacción de contenido) — según references/subagent-dispatch.md, luego sintetiza,
ordenando por severidad.
Mapa de referencias
references/intent-router.csv+references/intents/<intent>.csv— las dos capas de enrutamiento.references/playbooks/<surface>.md— sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.references/subagent-dispatch.md— prompts de las tres lentes y síntesis.references/core/*.md— severidad, puntuación, personas, glosario.references/{calibration,trackable-findings,modes}.md— compartidos (enlaces simbólicos).templates/*.md— change-plan, audit-report, design-doc, refactor-runbook, explanation, además de los artefactos compartidos de seguimiento.evals/,skill.json— compuertas y procedencia.