aidd — framework de desenvolvimento com IA, por projeto

Cada projeto possui e versiona o próprio framework: rules, hooks, git hooks, vault Obsidian, scripts e infra como código. O aidd instala esse seed no projeto e o mantém atualizado. Funciona com o Claude Code, o Codex e o Cursor (uma ou mais ao mesmo tempo), a partir de uma fonte só.

Instalação

mkdir meu-app && cd meu-app
npx [email protected] init

Num terminal interativo, sem flags, o aidd faz até 6 perguntas (nome, como prefere que o assistente fale, em quais ferramentas você usa agente de IA, onde o projeto vai rodar, extras) e mostra um resumo antes de criar. Por padrão ele cria o repositório git (se a pasta ainda não for um), liga os hooks de git e registra o projeto no Obsidian; tudo isso aparece no resumo. Se você não é programador, escolha a linguagem Simples: sem jargão e sem sugestão de produção.

Para scripts e CI, passe tudo por flag (nesse caso o aidd não pergunta nada):

npx [email protected] init . --persona technical --tools claude,codex,cursor --git-init

Não precisa de conta nem de autenticação. Sem repo git o init funciona, mas os gates de git ficam desligados (core.hooksPath: n/a); o doctor mostra o comando para ligá-los depois. A versão é pinada de propósito: o init fica reprodutível e o aidd update sabe de qual versão para qual está indo.

Requisitos: Node ≥ 20 e git. Windows funciona nativo. O grupo infra (com --profile) usa Ansible e Terraform via toolbox Docker ou WSL2. corepack enable (pnpm) não é necessário para instalar; só para rodar pnpm install/pnpm test no projeto gerado.

Recomendado (o doctor avisa se faltar): gitleaks e semgrep para os gates de segredo e de código, e Playwright para as evidências de entrega.

Uso

Use o prefixo npx [email protected] no lugar de aidd:

aidd init [dir]                                  # sem flags, em terminal interativo: assistente guiado (≤ 6 perguntas)
aidd init [dir] --persona technical|non-technical [--tools claude,codex,cursor] [--name X] [--modular] [--local-business] [--seo] [--profile validacao|producao] [--git-init] [--no-git-config] [--no-agent] [--no-register] [--dry-run] [--wizard|--no-wizard]
aidd update [dir] [--tools claude,codex,cursor]   # atualiza o que o projeto não editou; conflito vira <arquivo>.aidd-new; --tools acrescenta ou tira ferramenta (nunca apaga arquivo)
aidd doctor [dir]     # persona, hooks, rules, core.hooksPath, vault lint, login de agente, ferramentas e o guard de cada uma
aidd user init        # cria ~/.aidd/user (memória da pessoa) + ponteiro no global do agente
aidd user new <preferencia|correcao|vocabulario|contexto> "<texto>"
aidd user list | show <slug> | lint | path
aidd vaults [add [dir]]                         # vaults no Obsidian (projetos anotados + pessoa)
aidd graph [--out arquivo] [--json] [--open]    # grafo de tudo em ~/.aidd/grafo.html
aidd eval                                       # comportamento do agente sob as rules (evals/*.eval.md)
aidd metrics [--save]                           # memória, auto-melhoria e evals do uso real
aidd delegar <projeto> [--skill X] [--sem-merge] "<instrução>"   # roda uma skill do projeto sem abrir a sessão dentro dele

--persona é obrigatório porque muda como o agente fala e sugere, sem enfraquecer nenhum gate:

• technical: tom de dev, com jargão, arquivo:linha, opções e trade-offs.
• non-technical: linguagem simples, UMA recomendação, produção nunca sugerida.

A escolha fica em .claude/aidd.json e o agente a lê antes de sugerir, publicar ou explicar. Um projeto antigo sem persona resolve com aidd update . --persona <valor> uma vez; enquanto faltar, o doctor acusa FAIL persona.

Arquivo do seed que o projeto adaptou de propósito (personalizados)

O aidd update só atualiza arquivo que você não editou; o que você mexeu vira <arquivo>.aidd-new (conflito) a cada update. Quando a edição é permanente (ex.: o gate-prepush com uma variável do projeto), liste o caminho no .claude/aidd.json:

"personalizados": [".claude/hooks/gate-prepush.mjs", ".githooks/pre-commit"]

O update passa a não tocar nesses arquivos: sem .aidd-new, sem sobrescrever, e eles saem da lista de conflitos (aparecem como "personalizados (mantidos)" no relatório). O custo é seu: o arquivo não recebe mais as melhorias do seed. Para voltar ao normal, tire o caminho da lista e rode o update.

Cobertura do pre-push: arquivo inteiro ou só as linhas do PR (gates.cobertura)

O pre-push exige 85% de cobertura de linhas. Por padrão mede o arquivo inteiro de cada arquivo de código tocado; num arquivo antigo sem teste, mexer em uma linha herda a dívida toda. Para medir só o que o PR escreve ou altera, no .claude/aidd.json:

"gates": { "cobertura": { "modo": "linhas-alteradas" } }

O piso é o mesmo: linha executável nova ou alterada sem teste reprova, inclusive em arquivo que nenhum teste carrega. Comentário, branco, tipo e import não são linhas executáveis. Projeto novo (aidd init) já nasce nesse modo; projeto existente fica em arquivo até você trocar, e o aidd update não mexe nessa chave. Sem o relatório por arquivo (coverage-final.json) ou com o diff falhando, o gate volta ao cálculo por arquivo.

Claude Code, Codex e Cursor

--tools (ou a pergunta do assistente) diz em quais ferramentas você usa agente de IA. A fonte é uma só (.claude/rules/ do projeto, mais as skills do aidd); o aidd update regenera o que é de cada ferramenta e nunca sobrescreve o que você editou nem apaga arquivo de ferramenta que você desmarcou.

| Ferramenta | O que o aidd gera | Como os guards entram | Limite a saber | |---|---|---|---| | Claude Code | CLAUDE.md, .claude/settings.json, .claude/skills/ | hooks do settings.json | é a referência: cobre leitura, escrita e shell | | Codex | bloco do AGENTS.md, .codex/hooks.json, .agents/skills/, .codex/agents/*.toml | hook PreToolUse em shell e apply_patch | o Codex só roda o hook depois que você abre /hooks e confia nele; não há hook para a leitura nativa de arquivo; hook não pode pedir confirmação, então operação destrutiva é negada (você a executa à mão) | | Cursor | .cursor/rules/*.mdc, .cursor/hooks.json, .agents/skills/, .cursor/agents/*.md | hooks de shell, de leitura de arquivo e de escrita | o workspace precisa estar confiável; o Cursor também executa os hooks do .claude/settings.json, então com os dois marcados a checagem pode rodar duas vezes (sem furo) |

O AGENTS.md é seu: o aidd só mantém o trecho entre <!-- aidd:begin --> e <!-- aidd:end -->, e um AGENTS.md que você (ou o /init do Codex) já tinha continua inteiro. O .codex/hooks.json e o .cursor/hooks.json também: o aidd só troca as entradas que chamam o tool-shim.mjs.

Confira na sua ferramenta (o aidd prova o guard por teste automático, mas só você vê a ferramenta real):

1. aidd doctor: cada ferramenta marcada tem hooks.json válido e guard responde.
2. Codex: abra /hooks e confie nos hooks do projeto; depois peça ao agente para ler o arquivo de segredos do ambiente: deve ser negado.
3. Cursor: abra o projeto como workspace confiável e peça o mesmo.

Saída real do doctor logo após git init + init numa máquina limpa, sem nenhuma ferramenta opcional (exit 0; qualquer FAIL derruba para exit 1). Os WARN são o que falta instalar ou é opcional:

OK   .claude/aidd.json — versão 1.10.3, grupos base
OK   persona — technical
OK   hooks node --check — 34 hooks
OK   rules obrigatórias
OK   rules carregáveis (.md)
OK   core.hooksPath local — .githooks
OK   vault lint
OK   login de agente (.env.claude)
OK   .env.claude no .gitignore
WARN Playwright — necessário para scripts/evidence.mjs (pnpm add -D @playwright/test && pnpm exec playwright install chromium)
WARN gitleaks (secret-scan do commit) — ausente — o pre-commit não escaneia segredo no commit manual (fail-open). Instale (scoop/winget/brew install gitleaks) e registre a lacuna como nota `subtype: gap` no vault
WARN semgrep (config versionada) — ausente — o gate não roda semgrep (fail-open); a config versionada .claude/semgrep.yml já vai no seed
WARN memória da pessoa (~/.aidd/user) — não inicializada — rode: aidd user init (opcional; guarda preferências cross-project)
WARN Obsidian — não encontrado — docs/ é um vault Obsidian; instale em https://obsidian.md/download e rode: aidd vaults add (opcional)

Skills do projeto sem abrir a sessão nele (aidd delegar)

As skills do seed (/finish-him, /finalizar, /cleanup, /verify…) ficam em .claude/skills/ do projeto, e o Claude Code só as carrega com o diretório da sessão no projeto. Sessão aberta em outra pasta (o home, por exemplo) responde Unknown skill. aidd delegar resolve isso sem skill global:

npx [email protected] delegar meu-app --skill finalizar "fecha a entrega da branch atual"

• Abre um claude -p com o diretório no projeto (nome registrado em ~/.aidd/projetos.json ou caminho) e devolve resultado, custo, turnos e sessão. --dry-run mostra o comando sem executar.
• Não pula permissão: dontAsk + lista de ferramentas por perfil (finish-him, finalizar, cleanup; skill sem perfil só lê) + negadas fixas (force-push, --no-verify, --admin, reset --hard, clean, rm). finalizar nunca mescla; --sem-merge tira o merge das outras. Os hooks do projeto continuam valendo.
• Tetos: --budget (US$, máx. 20), --max-turns, --timeout (min). Timeout e Ctrl+C matam o filho e os processos dele.
• Custo: cada delegação paga o piso da sessão (~US$ 0,30) mais o trabalho. Use para um fluxo inteiro, não para pergunta solta. O filho não vê a conversa, então a instrução tem de bastar.

O que o seed instala

| Grupo | Conteúdo | |---|---| | base (sempre) | .claude/rules/*.md; .claude/hooks/ (bloqueio de leitura de .env, confirmação de comando destrutivo, evidência de entrega, gates); .githooks/ (lint/format no pre-commit, testes e cobertura no pre-push); docs/ (vault Obsidian com schema, templates e bases); scripts/; skill security-review (OWASP web + Agentic AI); skill frontend-make-me-sell (guia de conversão para landing, preço, cadastro, onboarding e retenção, com recusa de apostas); kit de produto /produto (da ideia ao MVP: pesquisa com fonte, SWOT/TOWS, painel cético, corte do MVP e plano de ação, com portão de validação que só abre com sinal de gente real); login de agente para DEV em .env.claude | | modular (--modular) | apps/ + packages/<ctx>/{core,persistence,http} + shared, .dependency-cruiser.cjs com as regras de fronteira, tsconfig com project references, primitivas de padrões (redact, rate-limit, idempotência, audit, telemetry) | | seo (--seo; --local-business já inclui; aidd update --seo em projeto existente) | SEO, GEO e AEO: diagnóstico por tipo de site (negócio local, SaaS, e-commerce, blog), auditoria, conteúdo com aprovação, autoridade e medição de presença no Google e nas IAs; 3 agentes (auditor, redator, analista) e o scanner scripts/agent-scan.mjs. Toda recomendação com número tem fonte pública; nada é publicado sem a sua aprovação | | local-business (--local-business) | SEO/GEO/AEO: app/robots.ts (libera crawlers de IA), app/sitemap.ts, public/llms.txt + llms-full.txt, lib/seo/json-ld.ts e a regra seo-geo-aeo | | infra (--profile) | Terraform (Cloudflare, R2, Pages, Workers, Render, Supabase, VPS, Sentry e PostHog), Ansible, Makefile, toolbox Docker, workflow de CI e runbooks em docs/infra/ |

Cada arquivo tem uma política em templates/manifest.json:

• managed: o update sobrescreve só se o projeto não editou.
• merge: JSON e listas de linhas são mesclados.
• once: o arquivo nunca é tocado depois do init.

Segurança

• O agente não lê .env, .env.local e equivalentes. O bloqueio vale para todas as ferramentas do Claude Code: Read, Grep, Glob, Bash e PowerShell. Só .env.claude (credenciais que você aprova para o agente) e *.example ficam liberados.
• Comandos destrutivos pedem confirmação, por exemplo git reset --hard, git clean -f, DROP, TRUNCATE e reset de banco.
• O commit é varrido atrás de segredos com o gitleaks quando ele está instalado. Sem ele, entra uma camada própria para os formatos de chave mais comuns.

Memória da pessoa (privacidade)

O aidd aprende sobre a pessoa, não só sobre o projeto. Essa memória vive em ~/.aidd/user/: um vault seu, com git próprio, fora de qualquer repositório de projeto.

• Nunca é versionado no repo do projeto. O vault não entra no init nem no update.
• O global recebe só um ponteiro. O ~/.claude/CLAUDE.md ganha apenas um bloco entre <!-- aidd:user-memory --> e <!-- /aidd:user-memory -->. O bloco é idempotente: rodar user init duas vezes não duplica nada nem mexe no resto do arquivo.
• Anti-envenenamento. O user new recusa o que não deve virar memória: falha de ambiente, afirmação negativa sobre ferramenta, erro transitório e dado pessoal sensível.

Licença

MIT