sir-ad/claude-setup-skill

/claude-setup

Crie um diretório .claude/ funcional para o projeto atual. Leia o código-fonte, detecte o contexto e escreva apenas o que realmente é útil nesta stack.

A regra fundamental desta habilidade: não gere lixo desnecessário. Sem pastas vazias. Sem placeholders genéricos. Se uma regra, habilidade ou agente não tiver um motivo real para existir NESTE projeto, pule-o.

---

Fase 1: Detectar

Execute estes comandos em paralelo e estude a saída:

!pwd && echo "---" && ls -la !cat README.md 2>/dev/null | head -120 !cat package.json Cargo.toml pyproject.toml go.mod Gemfile pom.xml build.gradle build.gradle.kts deno.json bun.lockb 2>/dev/null | head -300 !ls .claude/ 2>/dev/null && echo "---config claude existente acima---" !cat .gitignore 2>/dev/null | head -60 !ls docs/ docs/rfcs/ docs/adr/ docs/architecture/ 2>/dev/null

Com base nessa saída, decida:

• Stack: Rust (Cargo.toml), Node/TS (package.json), Python (pyproject.toml/requirements.txt), Go (go.mod), Ruby (Gemfile), Java/Kotlin (pom.xml/build.gradle), Deno (deno.json), Bun, ou misto. Se houver múltiplas, escolha a dominante e anote a secundária.
• Layout: monorepo (workspaces/turbo/nx/lerna/cargo [workspace]/Go workspace) vs. projeto único.
• .claude/ existente: se presente, é uma mesclagem — nunca sobrescreva sem confirmação por arquivo.
• Regras rígidas extraídas de README/RFCs/ADRs: palavras como "bloqueado", "proibido", "não ", "deve ", "RFC", "ADR-NNN", "invariante" são sinais. Codifique apenas as reais — não invente nenhuma.
• Framework de teste, linter, formatador, gerenciador de pacotes — extraia das configurações e scripts para que os comandos em CLAUDE.md sejam reais.

Se a detecção for genuinamente ambígua (múltiplos lockfiles, nenhuma linguagem primária clara, nenhum README), PARE e faça ao usuário uma pergunta focada para resolver. Não pergunte por coisas que você pode detectar.

---

Fase 2: Ler o modelo correspondente

Os modelos agrupados com esta habilidade descrevem o que gerar por stack. Leia o que for aplicável (use ${CLAUDE_SKILL_DIR}/templates/<nome>.md):

• rust-workspace.md — Cargo [workspace]
• rust-single.md — Cargo.toml único
• node-monorepo.md — workspaces npm/yarn/pnpm, turbo, nx, lerna
• node-single.md — package.json único (Next.js, Vite, Express, etc.)
• python.md — Poetry, pip+venv, uv, hatch
• go.md — projetos go.mod
• generic.md — fallback para qualquer outro

Cada modelo lista o que CLAUDE.md deve incluir, quais permissões são importantes, quais regras com escopo de caminho valem a pena, como ajustar o subagente revisor de código e quais habilidades são tipicamente úteis para aquela stack.

Os modelos são referências, não modelos prontos para colar. Use-os para decidir o que gerar; formule a saída em termos DESTE projeto.

---

Fase 3: Planejar e confirmar

Imprima um plano para o usuário antes de escrever qualquer coisa:

Detectado: <stack> (<layout>)
Nome do projeto: <nome>
Comandos principais: build=<cmd>, test=<cmd>, lint=<cmd>

Criará:
  CLAUDE.md                                  (NOVO | MESCLAR | PULAR)
  .worktreeinclude                           (NOVO | PULAR)
  .claude/settings.json                      (NOVO)
  .claude/rules/<n>.md                       (NOVO, caminho: <glob>)
  .claude/agents/<lang>-revisor.md           (NOVO)
  .claude/skills/<n>/SKILL.md                (NOVO)

Pulará (sem caso de uso claro): estilos-saida/, comandos/, memoria-agente/

Arquivos existentes: <lista com ação: manter/substituir/mesclar>

Regras rígidas detectadas do README/RFCs:
  - <citação 1> → codificada em rules/<arquivo>.md
  - <citação 2> → codificada em CLAUDE.md

Prosseguir? [s/N/visualizar/editar-plano]

Se --dry-run: pare aqui.

Se um arquivo já existir, a ação padrão é manter. Pergunte antes de substituir.

Se --minimal: planeje apenas CLAUDE.md + .claude/settings.json.

Se --skip-skills: omita skills/ do plano.

---

Fase 4: Gerar

Escreva os arquivos de acordo com o plano. Regras por arquivo:

CLAUDE.md

• Topo: resumo em uma linha da stack.
• Bloco ## Comandos: comandos reais extraídos dos scripts do package.json / Makefile / aliases do Cargo / scripts do pyproject. Não liste comandos que não existem.
• Bloco ## Mapa do repositório: apenas os diretórios importantes. Pule node_modules, target, dist, .next, __pycache__.
• Bloco ## Regras rígidas: apenas o que veio do README/RFCs/ADRs. Se não houver nada, omita a seção — não encha.
• Bloco ## Princípios comportamentais: mantenha os princípios existentes do usuário se CLAUDE.md já os tiver; caso contrário, omita (o ~/.claude/CLAUDE.md global provavelmente cobre isso).

.claude/settings.json

• permissions.allow: ajustado à stack. Para Rust: cargo *, git diff *, gh *. Para Node: npm test *, npm run *, pnpm *. Não permita Bash(*) genérico.
• permissions.deny: mínimo rm -rf *, git push --force *, git reset --hard *. Adicione comandos destrutivos específicos da stack (por exemplo, npm publish * para bibliotecas).
• Sem hooks, a menos que o projeto tenha uma necessidade clara de pré/pós-ferramenta.

.claude/rules/<nome>.md

Regras com escopo de caminho APENAS para diretórios com convenções reais. Heurística:

• Monorepos: uma regra por workspace que tenha regras distintas.
• Convenções de teste: uma regra com escopo **/*test* para padrões SE o projeto tiver convenções de teste não óbvias.
• Infra/IaC: uma regra com escopo infra/** SE o projeto tiver IaC.
• Design de API: uma regra com escopo para rotas de API SE houver um contrato de formato claro.

Não gere uma regra só porque o exemplo da documentação tinha uma. Se as convenções são óbvias a partir de CLAUDE.md, nenhuma regra é necessária.

.claude/agents/<lang>-revisor.md

• Ferramentas: apenas Read, Grep, Glob (somente leitura).
• Corpo: lista de verificação ajustada à linguagem (veja o modelo).
• A descrição deve ser específica o suficiente para que Claude invoque automaticamente para tarefas de revisão: "Revisa alterações em para ..." — liste as verificações específicas.

.claude/skills/<n>/SKILL.md

Gere APENAS habilidades que tenham um fluxo de trabalho claro e repetível:

• /release — se o projeto tiver um arquivo de versão (Cargo.toml, package.json, pyproject.toml) E um CHANGELOG.md.
• /test — se houver um comando de teste não trivial (por exemplo, matriz, vários conjuntos de teste). Um único cargo test não precisa de uma habilidade.
• /lint — mesma lógica.
• Específicas da stack (por exemplo, /db-migrate para Django/Rails, /deploy-preview para Next.js).

Não gere habilidades placeholders com corpos TODOs. Funcionando ou puladas, sem meio-termo.

.worktreeinclude

• Liste arquivos ignorados pelo git que as worktrees precisam: .env, .env.local.
• Se CLAUDE.md ou .mcp.json estiverem no .gitignore, inclua-os para que as worktrees não fiquem cegas.
• Se .claude/settings.local.json estiver no .gitignore, inclua-o.

---

Fase 5: Verificar e relatar

Após escrever:

echo "=== árvore gerada ==="
find .claude -type f | sort
echo "=== contagens de linhas ==="
find .claude -type f -exec wc -l {} \;

Imprima:

1. Árvore final.
2. Contagens de linhas (meta: cada arquivo ≤ 100 linhas; sinalize se algum exceder 150).
3. Uma etapa de verificação concreta (por exemplo, "abra uma sessão, execute /permissions, confirme se cargo * aparece como comprometido").
4. Lembrete: adicione .claude/settings.local.json ao .gitignore se ainda não estiver.

---

Anti-objetivos (reafirmados para clareza)

1. Sem pastas vazias. Sem estilos-saida/ a menos que haja um estilo real. Sem comandos/ (habilidades substituem, conforme documentação Anthropic).
2. Sem copiar e colar do exemplo da documentação. testing.md e api-design.md da árvore canônica são exemplos — gere algo análogo apenas se ESTE projeto realmente tiver essas convenções.
3. Sem sobrescrita. Sempre confirme por arquivo antes de substituir.
4. Sem regras rígidas do nada. Extraia do README/RFCs/ADRs. Se não existirem, o projeto não tem regras rígidas — diga isso e siga em frente.
5. Sem habilidades com TODOs. Funcionando ou puladas.
6. Sem curingas globais em permissões. Bash(cargo *) não Bash(*).

---

Referência de flags

• --minimal: apenas CLAUDE.md + .claude/settings.json.
• --skip-skills: omita skills/.
• --dry-run: imprima o plano, não escreva nada.

(Todas as flags são opcionais. O padrão é o layout canônico completo, ciente da stack, com confirmação.)