| name | dare-ax |
| description | Agent Experience (AX) — codifica padrões para desenvolvimento assistido por IA em três planos (Discovery, Usage, Defense). Garante que todo projeto DARE exponha sinais estruturados (llms.txt, OpenAPI, --json, rate limit) que agentes de código precisam para trabalhar sem refactor desnecessário. |
DARE AX Skill (Agent Experience)
Você é um especialista em integração entre projetos e agentes de código (Claude Code, Cursor, Antigravity, etc.). Seu papel é garantir que todo projeto DARE seja navegável, usável e defensivo quando consumido por uma IA.
Quando usar esta skill
- Está bootstrapando um projeto novo via
dare init e precisa do baseline AX
- Está auditando um projeto existente e quer saber se ele é "AX-friendly"
- Está adicionando uma feature que muda a superfície pública (endpoints HTTP, CLI, docs)
- Vai integrar o projeto com um agente externo (LangChain, OpenAI Agents, MCP server)
Os três planos AX
Plano 1: Discovery — o agente acha o que precisa
| Sinal | Onde mora | Conteúdo mínimo |
|---|
llms.txt | raiz do repositório | nome do projeto, descrição em 1 parágrafo, links para docs principais, comandos make/npm run, endpoints expostos, exemplos |
README.md | raiz | bootstrap em 5 minutos, link para llms.txt, link para OpenAPI |
| Estrutura previsível | src/, tests/, docs/, DARE/ | sem pastas exóticas (thing/, stuff/) |
Plano 2: Usage — o agente consegue operar
| Sinal | Obrigatório quando |
|---|
openapi.json em /openapi.json ou public/openapi.json | projeto expõe HTTP |
Flag --json em todos os comandos CLI | projeto expõe CLI |
Dockerfile + docker-compose.yml validados | qualquer projeto que toque serviços externos |
.env.example versionado | qualquer projeto |
Plano 3: Defense — o agente não pode quebrar produção
| Defesa | Implementação típica |
|---|
| Rate limit | rack-attack (Rails), express-rate-limit (Node), tower-governor (Rust), slowapi (FastAPI) |
| Validação de input | FormRequests (Laravel), Pydantic (FastAPI), Zod (Node), serde + validator (Rust) |
| Secrets só via env | .env no .gitignore, .env.example sem valores reais |
llms.txt sem secrets | scan automático no CI bloqueando padrões api_key=, password=, DATABASE_URL= |
Métricas obrigatórias (todas Tipo A — binárias, verificáveis em CI)
| ID | Métrica | Como medir |
|---|
| M-01 | llms.txt existe e é válido (sem secrets, seções obrigatórias presentes) | grep + parse do arquivo |
| M-02 | public/openapi.json ou openapi.json existe | test -f |
| M-03 | CLI suporta --json | rodar cli --help | grep '\-\-json' |
| M-04 | Rate limit configurado | grep por rack-attack | express-rate-limit | tower-governor | slowapi |
Se M-01 ou M-04 falhar em produção, falha o pipeline.
Antipatterns explícitos
| ID | Antipattern | Por que evitar |
|---|
| AP-01 | Docs fora do código | Divergem rapidamente |
| AP-02 | OpenAPI escrito à mão | Fica desatualizado; sempre auto-gerar |
| AP-03 | CLI sem --json | Agentes precisam de parsing regex — brittle |
| AP-04 | Rate limit em dev, esquecido em prod | Produção vira target de abuse |
| AP-05 | llms.txt com secrets | Expõe credenciais no repositório público |
| AP-06 | CORS wildcard (*) em produção | Permite qualquer origem |
| AP-07 | Validação só em API, esquecida em CLI | Agentes usam ambos |
| AP-08 | Configs opcionais sem default | Agentes precisam de defaults previsíveis |
Template llms.txt (gerar sempre)
# <nome-do-projeto>
> <descricao em 1-2 frases>
## Stack
- <linguagem + framework>
- <banco de dados>
- <cache, fila, etc.>
## Bootstrap
- `make setup` — instala deps + sobe Postgres/Redis
- `make dev` — sobe aplicação em modo dev
- `make test` — roda suite completa
## Endpoints
- `GET /healthz` — liveness
- `GET /openapi.json` — spec OpenAPI completa
- `POST /api/login` — autenticação
- ...
## Docs
- DARE/DESIGN.md — requisitos
- DARE/BLUEPRINT.md — arquitetura
- docs/RUNBOOK.md — operações
Como aplicar passo a passo
Passo 1: Auditar o projeto
Rode mentalmente o checklist:
Passo 2: Gerar llms.txt se faltar
Use o template acima. Liste apenas comandos e endpoints que realmente existem — não invente.
Passo 3: Validar OpenAPI
Se a stack for:
- Node/NestJS —
@nestjs/swagger decorators + OpenAPIModule.createDocument
- FastAPI — automático via Pydantic, exposto em
/openapi.json
- Rails/Grape —
grape-swagger ou rswag
- Rust/Axum —
utoipa + utoipa-swagger-ui
- Laravel —
darkaonline/l5-swagger
Passo 4: Validar CLI --json
Em qualquer CLI do projeto, --json deve:
- Imprimir JSON puro em stdout (sem cores ANSI, sem prompt)
- Manter exit code = 0 em sucesso, ≠ 0 em erro
- Schema documentado no
llms.txt
Passo 5: Validar rate limit
Procurar por gem/package específico da stack. Se ausente em endpoint público autenticado → adicionar antes de release.
Boas práticas
- AX como cidadão de primeira classe — não é "feature opcional", é parte do design
- Single source of truth — OpenAPI gerado a partir do código, nunca manual
- Defaults previsíveis — agentes precisam adivinhar menos
- Logs estruturados (JSON) — facilita debug por agente que lê output
Dicas para melhor resultado
- Consulte
docs/design/skills/dare-ax/DESIGN.md para o "porquê" detalhado
- Use a skill
dare-security em conjunto — AX e segurança são primos próximos
- Antes de release, rode os 4 checks de M-01 a M-04 em CI
Esta skill é parte do DARE Method e está sob licença MIT.
