claude-code-template

Template de scaffolding Claude Code para projetos Node.js + Express + React + PostgreSQL + Docker.

Estrutura

.
├── CLAUDE.md                          ← Constituição do projeto (carregada sempre)
├── .claude/
│   ├── settings.json                  ← Hooks, permissões, MCP
│   ├── agents/                        ← Subagentes especializados
│   │   ├── db-postgres-migration.md
│   │   ├── dba-postgres-architect.md
│   │   ├── backend-api-nodejs-senior-engineer.md
│   │   ├── frontend-react-senior-engineer.md
│   │   ├── database-postgres-specialist.md
│   │   ├── docker-specialist.md
│   │   ├── ci-cd-pipeline-specialist.md
│   │   ├── github-actions-specialist.md
│   │   ├── documentation-specialist.md
│   │   ├── qa-specialist.md
│   │   └── automation-tests-specialist.md
│   ├── skills/                        ← Workflows reutilizáveis
│   │   ├── code-review/SKILL.md
│   │   ├── new-feature/SKILL.md
│   │   ├── debug-production/SKILL.md
│   │   └── deploy-checklist/SKILL.md
│   ├── commands/                      ← Slash commands customizados
│   │   ├── pr-description.md
│   │   ├── migration-create.md
│   │   └── test-coverage.md
│   └── memory/
│       └── MEMORY.md                  ← Memória factual do projeto
├── specs/                             ← Especificações de referência
│   ├── API.md
│   ├── DATABASE.md
│   ├── QUALITY.md
│   └── INFRASTRUCTURE.md
└── hooks/                             ← Scripts de lifecycle
    ├── validate-bash.py               ← Bloqueia comandos destrutivos
    └── audit-log.py                   ← Registra operações de escrita

Como usar este template

1. Copiar para seu projeto

cp -r claude-project-template/.claude /seu-projeto/
cp -r claude-project-template/specs /seu-projeto/
cp -r claude-project-template/hooks /seu-projeto/
cp claude-project-template/CLAUDE.md /seu-projeto/

2. Adaptar o CLAUDE.md

Edite /CLAUDE.md e preencha:

• Nome e descrição do projeto
• Comandos específicos (npm run dev, npm test, etc.)
• Arquivos específicos que não devem ser tocados

3. Adaptar as specs

Preencha specs/ com detalhes reais do seu projeto:

• DATABASE.md → schema, convenções do seu banco
• API.md → endpoints reais
• QUALITY.md → thresholds de coverage
• INFRASTRUCTURE.md → variáveis de ambiente reais

4. Adaptar settings.json

Em .claude/settings.json, ajuste:

• Permissões de Write e Edit para suas pastas reais
• MCP servers se necessário (PostgreSQL local, GitHub, etc.)

5. Tornar os hooks executáveis

chmod +x hooks/*.py

6. Iniciar o Claude Code

claude

Os agentes estarão disponíveis automaticamente. Use /agents para listar.

---

Guia rápido de agentes

Quando	Acionar
Nova feature	Skill new-feature → orquestra todos
Schema / banco	dba-postgres-architect
Migration	db-postgres-migration
Query lenta	database-postgres-specialist
Backend / API	backend-api-nodejs-senior-engineer
Frontend / React	frontend-react-senior-engineer
Docker / container	docker-specialist
Pipeline CI/CD	ci-cd-pipeline-specialist → github-actions-specialist
Testes	qa-specialist → automation-tests-specialist
Docs / ADR	documentation-specialist
Problema em prod	Skill debug-production
Antes de deploy	Skill deploy-checklist
Antes de merge	Skill code-review

Slash commands disponíveis

/pr-description          Gera descrição de PR baseada no diff
/migration-create <nome> Cria migration com template padrão
/test-coverage           Executa testes e analisa gaps de cobertura

Política de autonomia por agente

Agente	Autonomia
db-postgres-migration	🟡 Read-only — nunca executa migrations
dba-postgres-architect	🟡 Read-only — só recomendações
database-postgres-specialist	🟡 Read-only — só produz SQL
ci-cd-pipeline-specialist	🟡 Read-only — só design
qa-specialist	🟡 Read-only — só análise
backend-api-nodejs-senior-engineer	🟠 Read+Write (configs críticas: confirmar)
frontend-react-senior-engineer	🟠 Read+Write (configs globais: confirmar)
automation-tests-specialist	🟠 Read+Write (thresholds de CI: confirmar)
documentation-specialist	🟠 Read+Write (specs de contrato: sinalizar)
docker-specialist	🟠 Read+Write (compose.prod: confirmar)
github-actions-specialist	🟠 Read+Write (workflows de prod ativos: confirmar)