<div align="center">
<img src="claude-lendo.png" alt="Claude lendo" width="180">
# 𧰠Claude Code Starter Pack
### *B2 Tech Edition*
**Base mĂnima, opinativa e segura para começar qualquer projeto com Claude Code.**
PermissĂ”es determinĂsticas · Hooks que rodam 100% das vezes · Skills sob demanda · EmpacotĂĄvel como plugin.
<br>
</div>
---
## đ Ăndice
- [Por que existe](#-por-que-existe)
- [Os 4 pilares](#-os-4-pilares)
- [Filosofia](#-filosofia)
- [Estrutura](#-estrutura)
- [Quick start](#-quick-start)
- [Hooks](#-hooks)
- [Skills](#-skills)
- [PermissÔes](#-permissÔes-settingsjson)
- [Distribuir como plugin](#-distribuir-como-plugin)
- [Novidades da 2.0](#-novidades-da-20)
- [DecisÔes de escopo](#-decisÔes-de-escopo)
---
## đŻ Por que existe
Todo projeto novo repete a mesma configuração de Claude Code: definir o que ele
pode rodar sem perguntar, garantir que segredos nunca vazem, padronizar formatação
e ensinar as convençÔes do time. Este pack entrega isso pronto â **copie para a raiz
do projeto e comece com guardrails de segurança e qualidade desde o primeiro prompt.**
---
## đïž Os 4 pilares
| Pilar | Arquivo | Papel |
|-------|---------|-------|
| âïž **Configuração** | `.claude/settings.json` | PermissĂ”es, env e attribution â o que Ă© **determinĂstico**. |
| đȘ **Hooks** | `.claude/hooks/*.sh` | AutomaçÔes que rodam *toda vez, sem exceção* (lint, format, guardrails). |
| đ§ **Skills** | `.claude/skills/*/SKILL.md` | Conhecimento de domĂnio com *progressive disclosure* â carregado sĂł quando relevante. |
| đŠ **Plugin** | `.claude-plugin/plugin.json` | Empacotamento opcional para distribuir tudo num marketplace privado. |
---
## đĄ Filosofia
> TrĂȘs regras guiam cada decisĂŁo deste pack:
1. **`settings.json` para o determinĂstico.** PermissĂ”es, attribution, model.
Nunca escreva *"NEVER faça X"* no `CLAUDE.md` se då pra enforçar via setting ou hook.
2. **Hooks para o que precisa rodar 100% das vezes.** Formatação, secrets scan,
bloqueio de paths. Hooks sĂŁo determinĂsticos; `CLAUDE.md` Ă© apenas conselho.
3. **Skills para conhecimento sob demanda.** ConvençÔes de DDD/VSA, checklists de
segurança, padrÔes de commit. Carregadas só quando o contexto pede.
---
## đïž Estrutura
```
seu-projeto/
âââ .claude/
â âââ settings.json # â
Versionado no git â vale pro time inteiro
â âââ settings.local.json.example # đ€ Modelo de preferĂȘncias pessoais (gitignored)
â âââ hooks/
â â âââ pre-bash-guard.sh # đĄïž Bloqueia comandos destrutivos
â â âââ pre-commit-secrets.sh # đ Escaneia secrets antes de commit/push
â â âââ post-edit-format.sh # đš Formata + lint apĂłs cada edição
â â âââ block-secrets.sh # đ Guard extra p/ paths sensĂveis (opcional)
â âââ skills/
â âââ code-review-b2/SKILL.md # đ RevisĂŁo padrĂŁo B2 Tech (VSA + DDD)
â âââ security-check/SKILL.md # đ Auditoria Security by Design (OWASP)
â âââ commit/SKILL.md # âïž Conventional commits assistidos
â âââ frontend-design/SKILL.md # đ Frontend distinto, sem "AI slop"
âââ .claude-plugin/
â âââ plugin.json # đŠ Metadados do plugin b2tech-starter
âââ .mcp.json # đ MCP servers do projeto (vazio por padrĂŁo)
âââ .gitignore
âââ CLAUDE.md # đ Contexto do projeto (curto, humano)
```
---
## đ Quick start
```bash
# 1. Clone o pack
git clone https://github.com/brunobracaioli/claude-code-starter-pack.git
# 2. Copie a config para a raiz do seu projeto
cp -r claude-code-starter-pack/.claude seu-projeto/
cp -r claude-code-starter-pack/.claude-plugin seu-projeto/ # opcional (plugin)
cp claude-code-starter-pack/.mcp.json seu-projeto/ # opcional (MCP)
cp claude-code-starter-pack/CLAUDE.md seu-projeto/
# 3. Torne os hooks executĂĄveis
chmod +x seu-projeto/.claude/hooks/*.sh
# 4. (Opcional) Crie suas preferĂȘncias locais a partir do exemplo
cp seu-projeto/.claude/settings.local.json.example \
seu-projeto/.claude/settings.local.json
# 5. Rode
cd seu-projeto && claude
```
> đ§ **DependĂȘncia:** os hooks usam [`jq`](https://jqlang.github.io/jq/) para ler o
> JSON do stdin. Instale com `sudo apt install jq` (Debian/Ubuntu/WSL) ou `brew install jq`.
> đ **Customize o `CLAUDE.md`:** ele vem como template (`# <Nome do Projeto>`).
> Preencha stack, comandos e estrutura â mantenha curto e humano.
---
## đȘ Hooks
AutomaçÔes wired em `settings.json`. Todas seguem o mesmo contrato: leem JSON do
stdin, **`exit 0` permite**, **`exit 2` bloqueia** e devolve o stderr ao Claude
como contexto para auto-correção.
| Hook | Evento | Matcher | O que faz |
|------|--------|---------|-----------|
| `pre-bash-guard.sh` | `PreToolUse` | `Bash` | Bloqueia `rm -rf /`, fork bombs, `mkfs`, `DROP/TRUNCATE`, `curl \| sh`, `git push --force` em `main`, e remoção de arquivos sensĂveis. |
| `pre-commit-secrets.sh` | `PreToolUse` | `Bash` | Em `git commit`/`push`, escaneia arquivos *staged* por chaves AWS/GitHub/OpenAI/Anthropic/Slack/Meta e private keys. |
| `post-edit-format.sh` | `PostToolUse` | `Write \| Edit \| NotebookEdit` | Formata e då lint após ediçÔes: Prettier+ESLint (JS/TS), Ruff (Python), `jq` (JSON), `gofmt` (Go), `rustfmt` (Rust). |
| `block-secrets.sh` | â | â | **NĂŁo wired por padrĂŁo.** Guard mais agressivo: bloqueia qualquer tool tocando `.env`, `secrets/`, chaves SSH, `~/.aws`, `~/.config/gcloud`, etc. |
<details>
<summary><b>Como ativar o <code>block-secrets.sh</code></b></summary>
<br>
à um guard opcional, mais amplo que os defaults. Para ativå-lo em operaçÔes de
arquivo, adicione-o ao bloco `PreToolUse` do `settings.json`:
```jsonc
{
"matcher": "Write|Edit|Read",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-secrets.sh",
"timeout": 10
}
]
}
```
</details>
---
## đ§ Skills
Carregadas via *progressive disclosure* â o Claude lĂȘ o `SKILL.md` sĂł quando o
contexto da conversa bate com a `description`.
| Skill | Quando invocar | Cobre |
|-------|----------------|-------|
| đ **`code-review-b2`** | *"revise o cĂłdigo"*, *"code review"*, fim de feature/PR | Vertical Slice + DDD, Security by Design, qualidade Python/Flask + Next.js/TS, testes. Output com `đŽ Blocker` / `đĄ Major` / `đą Nit` + decisĂŁo. |
| đ **`security-check`** | *"audite a segurança"*, antes de subir pra prod | OWASP Top 10, secrets, AuthN/AuthZ, supply chain, logs. Findings `đ„ CRĂTICO`â`đ” INFO` com ameaça â impacto â fix. |
| âïž **`commit`** | `/commit` (ou peça pra commitar) | Stage + mensagem em Conventional Commits a partir do diff. **NĂŁo dĂĄ push** â vocĂȘ decide quando. |
| đ **`frontend-design`** | *"crie um componente/pĂĄgina/UI"* | Frontend distinto e production-grade, fugindo da estĂ©tica genĂ©rica de IA. |
---
## đ PermissĂ”es (`settings.json`)
Defense in depth desde o primeiro prompt â trĂȘs nĂveis de permissĂŁo:
```
â
allow â roda sem perguntar
read/glob/grep, git status|diff|log|branch, lint/typecheck/test, ruff, mypy, pytest
â ask â pede confirmação
git push, git commit, npm/pnpm publish, WebFetch
đ« deny â bloqueado sempre
ler/editar .env e .env.*, secrets/**, *.pem, *.key, credentials.json,
service-account*.json · sudo, rm -rf /, curl|sh, wget|sh, ssh
```
Outros defaults: `cleanupPeriodDays: 14`, `enableAllProjectMcpServers: false`,
e trĂĄfego nĂŁo-essencial desligado (`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`).
> đ€ **PreferĂȘncias pessoais** (spinner verbs, output style, permissĂ”es extras)
> vĂŁo em `settings.local.json` â gitignored. Use o `.example` como ponto de partida.
---
## đŠ Distribuir como plugin
O `.claude-plugin/plugin.json` empacota hooks e skills como o plugin
**`b2tech-starter`**, pronto para um marketplace privado do time. Assim, em vez de
copiar arquivos manualmente, cada projeto instala o pack com um comando.
---
## âš Novidades da 2.0
Mapeado direto dos commits desde o `first commit`:
- đ **Skill `commit`** â Conventional Commits assistidos a partir do diff.
- đ **Skill `frontend-design`** â UIs distintas, sem estĂ©tica genĂ©rica de IA.
- đ **Hook `block-secrets.sh`** â guard opcional, mais agressivo, para paths sensĂveis.
- đ **`.mcp.json`** â ponto de entrada para MCP servers do projeto.
- đ§ **`settings.json` revisado** â permissĂ”es `allow`/`ask`/`deny` mais granulares,
`autoMemory`/`autoDream` ligados, env de privacidade.
- đ§ **`pre-bash-guard.sh` refinado** â padrĂ”es ancorados para reduzir falso-positivo
(`rm -rf /` literal nĂŁo bloqueia `rm -rf /tmp/...`).
- đïž **Reorganização** â arquivos movidos do subdiretĂłrio para a raiz do repositĂłrio.
---
## đ§ DecisĂ”es de escopo
O que ficou **de fora de propĂłsito**, e por quĂȘ:
- **Subagentes (`agents/`)** â adicione conforme necessidade real; evite genĂ©ricos.
- **Slash commands dedicados (`commands/`)** â skills sĂŁo mais flexĂveis e suportam
*supporting files*.
- **MCP servers configurados** â projeto-especĂfico; `.mcp.json` vem vazio, pronto
para vocĂȘ preencher.
> **Stack-aware, nĂŁo stack-locked.** Os hooks e skills assumem Python/Flask +
> Next.js/TypeScript em GCP, mas o `post-edit-format.sh` jĂĄ cobre Go e Rust. Ajuste
> os comandos de lint/format conforme a stack do seu projeto.
---
<div align="center">
**[Bruno Bracaioli](https://b2tech.io)** · MIT License
*Feito para começar projetos com segurança e qualidade desde o primeiro prompt.*
</div>