Communitygithub.com

Agent DX

Um kit de habilidades para agentes que o mantenedor realmente usa — instale via npx skills add justinramos101/agent-skill-kit

O que é Agent DX?

O Agent DX é uma skill especializada em avaliar e melhorar a experiência de desenvolvedor (DX) para agentes de IA. Seu propósito é garantir que SDKs, ferramentas, saídas estruturadas, envelopes de erro e telemetria sejam consumíveis exclusivamente por agentes, em velocidade de máquina, sem depender de dicas visuais. A skill suporta três intenções principais: DO (produzir um plano de mudança), REVIEW (realizar uma auditoria detalhada com descobertas e rastreamento) e DESIGN (criar documentos de design, runbooks de refatoração ou explicações). O fluxo de trabalho é altamente roteirizado: o agente seleciona uma intenção, identifica uma ou mais superfícies (como design de SDK, ferramentas/MCP, saída estruturada, erros/retry, telemetria), carrega o contexto adequado, calibra a análise com base na escala do projeto, despacha lentes de avaliação em paralelo (contrato/esquema, recuperação do agente, confiança/isolamento) e gera os artefatos correspondentes. A skill enfatiza contratos tipados, recuperação projetada e limites de confiança fechados por padrão, registrando descobertas com IDs padronizados (AGENT-DX-{SDK,TOOL,OUT,ERR,TEL}) e pontuações de 0 a 10. Ideal para equipes que desejam garantir que suas interfaces de API e ferramentas sejam robustas e seguras para consumo autônomo por agentes.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add justinramos101/agent-skill-kit

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. Escolha a intenção. Carregue references/intent-router.csv; combine com do, review ou design. Ambíguo → pergunte uma vez.
  2. Escolha a superfície. Carregue references/intents/<intent>.csv; combine uma ou mais de sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry — ou all para um fan-out de REVIEW. Ambíguo → pergunte uma vez com o menu.
  3. Carregue contexto fundamentado. Carregue apenas o playbook da linha escolhida mais seus core_refs. Não carregue outros playbooks (a linha review/all não carrega nenhum — cada agente de superfície carrega o seu; veja o passo 6).
  4. Identifique a persona alvo a partir de references/core/personas.md.
  5. 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.
  6. 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.
  7. 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 padronizados AGENT-DX-<surface>-NNN (references/core/severity-rubric.md): AGENT-DX-SDK, AGENT-DX-TOOL, AGENT-DX-OUT, AGENT-DX-ERR, AGENT-DX-TEL.
  8. 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) ou templates/explanation.md (explique um princípio).
  9. 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 ID AGENT-DX-*, leia o estado salvo primeiro; atualize status apenas após cada regra de verificação passar. Caso contrário, escreva o ledger em docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md e o estado de fluxo de trabalho em docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json (fallback para audit-artifacts/agent-dx-... se docs/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.

Habilidades Relacionadas