O que Agent DX faz?
A experiência de desenvolvedor de uma superfície onde um agente de IA é o desenvolvedor — um SDK, ferramenta,
saída estruturada, envelope de erro ou telemetria que um agente consome para construir com ou agir
através. A proveniência vive em skill.json; este arquivo é apenas roteamento em tempo de execução.
Produz: um change-plan.md (DO), um audit-report.md mais um ledger de descobertas +
estado de fluxo de trabalho quando rastreado (REVIEW), ou um design-doc.md / refactor-runbook.md /
explanation.md (DESIGN).
Princípio central
Um agente consome a superfície sozinho, em velocidade de máquina, sem dica visual para se apoiar. Portanto,
o padrão para qualquer SDK, ferramenta, erro ou span é se um consumidor estocástico pode analisá-lo,
recuperar-se dele e não ser prejudicado por ele: contratos tipados em vez de prosa; recuperação projetada, não
apenas esperada; o limite de confiança fechado por padrão. Ele fica acima do piso de cliente HTTP que
dx-audit / dx-design possuem, nunca o substituindo.
Ativação
- Invocação simples (
"use agent-dx","start"): mostra um menu compacto: escolha de modo (guiado / piloto automático / me questione?) e intenções numeradas do roteador. Aguarde. Sem inspeção de arquivos, sem chamadas de rede, sem gravações. - Invocação concreta com intenção e superfície inferíveis: pule para o passo 3.
- Invocação ambígua: pergunte uma vez — por exemplo, "Você está auditando um SDK, esquema de ferramenta, envelope de saída estruturada ou superfície de telemetria?" ou "Isso é uma revisão de contrato/recuperação ou uma auditoria de limite de confiança?"
Fluxo de trabalho
- Escolha a intenção. Carregue
references/intent-router.csv; combine comdo,reviewoudesign. Ambíguo → pergunte uma vez. - Escolha a superfície. Carregue
references/intents/<intent>.csv; combine uma ou mais desdk-design,tools-and-mcp,structured-output,errors-and-retry,sdk-telemetry— ouallpara um fan-out de REVIEW. Ambíguo → pergunte uma vez com o menu. - Carregue contexto fundamentado. Carregue apenas o
playbookda linha escolhida mais seuscore_refs. Não carregue outros playbooks (a linhareview/allnão carrega nenhum — cada agente de superfície carrega o seu; veja o passo 6). - Identifique a persona alvo a partir de
references/core/personas.md. - Em seguida, calibre para a escala do projeto (REVIEW / DESIGN) conforme
references/calibration.md: abaixo de Crítico, estreite o escopo, colapse lacunas de mesmo mecanismo em uma única descoberta sistêmica e divida Agora vs Depois (conforme cresce). O nível alimenta a emissão, nunca a gravidade. - Despache lentes em paralelo (padrão REVIEW quando permitido): uma superfície por agente para
all; caso contrário, as três lentes abaixo. Fallback sequencial se não houver primitiva de delegação. - Aplique o playbook. Use as heurísticas marcadas para a intenção. Para REVIEW, pontue cada
superfície de 0 a 10 (
references/core/score-rubric.md); synthesize descobertas das lentes, preservando discordâncias como perguntas em aberto. Aplique gravidade e IDs padronizadosAGENT-DX-<surface>-NNN(references/core/severity-rubric.md):AGENT-DX-SDK,AGENT-DX-TOOL,AGENT-DX-OUT,AGENT-DX-ERR,AGENT-DX-TEL. - Emita. DO →
templates/change-plan.md. REVIEW →templates/audit-report.md. DESIGN →templates/design-doc.md(forma),templates/refactor-runbook.md(sequência de hardening) outemplates/explanation.md(explique um princípio). - Crie, retome ou feche estado de rastreamento (REVIEW). Para uma auditoria com 7+ descobertas, qualquer
gravidade 3–4 ou uma solicitação de salvar/rastrear/fechar, carregue
references/trackable-findings.md. Se a solicitação nomear um ledger existente, estado de fluxo de trabalho, PR ou IDAGENT-DX-*, leia o estado salvo primeiro; atualize status apenas após cada regra de verificação passar. Caso contrário, escreva o ledger emdocs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.mde o estado de fluxo de trabalho emdocs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json(fallback paraaudit-artifacts/agent-dx-...sedocs/audits/não for gravável). Relate ambos os caminhos; mantenha roadmaps, issues e edições não relacionadas a rastreamento como opt-in.
Direção errada? Se o usuário disser que não era isso que ele queria, volte ao passo 1 (Escolha a intenção) — não corrija na direção errada. Reafirme o entendimento corrigido e replaneje.
Modos
Rascunho Guiado (padrão), Piloto Automático, Me Questione — veja references/modes.md. Ofereça na
invocação simples; padrão para Rascunho Guiado em invocações concretas.
Requisitos de saída
Toda saída nomeia a intenção, superfície(s), persona, playbook(s) aplicados e fontes de fundamentação
de skill.json; REVIEW adiciona gravidade + verificação por descoberta e o nível do projeto.
Nomeie as garantias de consumibilidade por agente que você está deliberadamente NÃO adicionando (YAGNI), não apenas
as que você está adicionando.
Despacho de subagentes
Padrão para REVIEW quando a delegação é permitida; pule trabalho pequeno ou com segredos. Crie três
lentes em paralelo — contrato-e-esquema (esquemas tipados do código, envelope de erro estável,
saída validada), recuperação-do-agente (pare+verifique, erros em formato de retry, retry semântico,
loop limitado), confiança-e-isolamento (injeção de metadados de ferramenta, pontos de verificação de guardrail,
muros de credenciais, redação de conteúdo) — conforme references/subagent-dispatch.md, depois sintetize,
ordenando por gravidade.
Mapa de referências
references/intent-router.csv+references/intents/<intent>.csv— as duas camadas de roteamento.references/playbooks/<surface>.md— sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.references/subagent-dispatch.md— prompts das três lentes e síntese.references/core/*.md— gravidade, pontuação, personas, glossário.references/{calibration,trackable-findings,modes}.md— compartilhados (symlinks).templates/*.md— change-plan, audit-report, design-doc, refactor-runbook, explanation, mais os artefatos de rastreamento compartilhados.evals/,skill.json— portões e proveniência.