Modelo — CLAUDE.md do projeto

Copie para a raiz do projeto. Um arquivo só, que aponta para o Manifesto e descreve o contexto operacional (comandos, setup, ambiente). Não repita o Manifesto — referencie-o. Um AGENTS.md de poucas linhas que manda ler o CLAUDE.md atende os agentes que só leem esse nome.

# CLAUDE.md — [Nome do projeto]

[Uma frase: o que é o projeto, para quem, onde roda.]

## A regra de ouro

**Tudo o que mexe no código é ADR**, de um módulo a um bugfix: uma pasta numerada em
`.specs/adr/NNN-slug/` com seis arquivos. O que não mexe no código (deploy, roadmap, organização) é
tarefa no Gestor, se valer registrar. **Você orquestra sozinho** pela regra de
`manifesto/02-fluxo-adr/04-tarefa-ou-adr.md`: decide se é ADR, acha ou cria a ADR, vincula à
tarefa e anda a tarefa — sem esperar a pessoa pedir. Leia antes de mudanças significativas:
`manifesto/01-principios/01-principios.md` e `manifesto/02-fluxo-adr/`.

O número de uma ADR nova vem da reserva do Gestor (sem ele, o maior + 1); este arquivo não diz
qual é a próxima. O `manifesto/` é **read-only** aqui: a origem é o jhowdev, e a versão nova chega
por `pnpm manifesto:pull` (revisar o diff e commitar).

## Gestor

[Com o Gestor (recomendado):] o projeto é **[projeto]** em [endereço do Gestor]. A IA fala com ele
pelo MCP do Gestor (`gestor`): nos espaços, já configurado; fora deles, com um token pessoal do
Gestor. [Sem o Gestor: apague esta seção; vale `manifesto/02-fluxo-adr/06-sem-o-gestor.md`.]

## Idioma

Código, variáveis, funções e entidades em **inglês**; documentação, ADRs, commits e comentários em
**português**, com acentuação.

## Stack

A stack universal do Manifesto (`manifesto/03-stack/01-stack-universal.md`) e, além dela:
[o que o projeto acrescenta — ver .specs/stack/].
Proibições duras: sem `any`; sem `alert()` (toast só via Sonner); Zod em todo input e OpenAPI em
todo endpoint; autorização por escopo no `where` (anti-IDOR).

## Setup

```bash
pnpm install
pnpm run init                 # .env.local a partir do .env.example (nunca vai ao git)
pnpm db:start                 # PostgreSQL do compose.yml (Docker, que já vem no espaço do Gestor;
                              # Podman também funciona; só o orquestrador opera o banco)
pnpm db:deploy && pnpm db:seed
pnpm dev                      # porta via .env.local
```

## Validações antes de toda entrega

```bash
pnpm lint         # 0 erro e 0 aviso
pnpm typecheck
pnpm test         # Vitest
pnpm build
pnpm smoke        # smoke por domínio contra o app rodando
```

## Estrutura

```
apps/            os apps (ex.: apps/web)
packages/        ui (shadcn/ui), eslint-config, typescript-config
manifesto/       a metodologia (read-only; pnpm manifesto:pull)
.specs/
├── adr/         o trabalho que mexe no código (seis arquivos cada)
├── stack/       escolhas técnicas próprias do projeto
├── design/      Design System (quando uma ADR a criar)
└── notes/       anotações humanas (a IA ignora por padrão)
scripts/         PDFs das ADRs (pnpm adr:pdf) e o kit do projeto
```

## Git

- Trabalhe na `develop`; a `main` recebe merge só por decisão do dono. Branch por ADR é opcional
  (a regra com agentes em paralelo); sem pull request: integrar é o merge local.
- `git push` só quando o dono pedir ou autorizar daquela vez (a IA pode oferecer); nunca `--force`;
  agente secundário e workflow nunca fazem push.
- Conventional Commits em português; prefixo `adr/docs:` para a documentação de uma ADR; o rodapé
  cita a tarefa e a ADR (`Tarefa: KBP-12`, `ADR: 012`).
- Commit seletivo (`git add` com caminhos); nada de `git reset --hard`, `git push --force` sobre
  trabalho compartilhado nem `--no-verify`.

## Regras que não são óbvias

- [O que um agente novo precisa saber para não quebrar o projeto: portas, bancos, serviços
  externos, testes que travam padrões. Uma linha por regra, com a ADR que a decidiu.]
- **Não edite `manifesto/`** (use `pnpm manifesto:pull`) e **ignore `.specs/notes/`**, salvo pedido
  explícito.
- **Não acesse banco de produção** em desenvolvimento; não commite `.env.local` nem segredos.

## Fechamento de uma ADR

Escrever o 005 (com as tarefas vinculadas) e o 006, marcar o 001 como `Concluído` com os prazos
reais, atualizar o 004 e a linha do índice em `.specs/readme.md`, rodar `pnpm adr:pdf <slug>`,
commitar, mover a tarefa para Revisão no Gestor (com o comentário interno) e avisar "PDFs prontos
para envio".