-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Backend do ERP Bem Comum Esta wiki é o repositório de conhecimento geral — aquilo que não pertence ao código, não é uma decisão arquitetural formal e não é registro histórico.
Ela reside em um repositório separado (core-api.wiki.git) e é sincronizada para o disco via comando. Ela é clonada no diretório .wiki/ (adicionado ao .gitignore). É esse mecanismo que garante a visibilidade do conteúdo para quem opera no repositório, sejam desenvolvedores ou agentes: conhecimento fora do clone é conhecimento invisível.
A existência desta wiki é pautada por restrições. O repositório já possui quatro fontes de verdade com papéis rigorosamente delimitados. Inserir a informação no lugar errado não é apenas desorganização estrutural — é criar uma segunda versão que, fatalmente, vai divergir da primeira.
| Se o conteúdo é… | Então o destino é… | Justificativa |
|---|---|---|
| Diretrizes de edição | .claude/rules/ |
Carregadas automaticamente via paths: no contexto da IDE/Agente. |
| Decisão arquitetural | handbook/architecture/adr/ |
ADR aceito é imutável. Para revogar, abre-se um novo com supersedes. |
| Registro de eventos |
handbook/ ou Discussion
|
É acervo histórico: documenta o passado, não dita o presente. |
| Comportamento real | O próprio código | O código é a única fonte que não pode mentir sobre sua execução. |
| Débito ou problema | Issue no GitHub | Exige um responsável, estado e resolução concreta (fechamento). |
Important
Se uma validação mecânica (CI, linter, testes) pode cobrar a regra, ela não pertence à wiki. Ela é um gate.
Uma regra que não bloqueia o build perde a validade. Antes de documentar um "sempre faça X" aqui, avalie se um teste estrutural em tests/cleanup/, uma regra de ESLint ou um git hook não resolveria de forma determinística. A wiki serve apenas para o que o ferramental não alcança.
O mapa de navegação do repositório para responder "onde eu procuro isso?":
| A pergunta | A resposta está em |
|---|---|
| Como clonar, dar setup e rodar? | README.md |
| Quais regras se aplicam a este arquivo? |
.claude/rules/ (injetadas passivamente)
|
| Por que escolhemos MySQL e não Postgres? | handbook/architecture/adr/0020 |
| Por que Fastify? Onde está a CLI? | ADR-0025 e ADR-0037 (CLI embutida retirada — não existe cli/ em src/)
|
Por que usamos pnpm e nunca npm? |
ADR-0029 |
| Como a borda HTTP valida entradas? | ADR-0027 (Contract-first com Zod, OpenAPI) |
| Esse problema já foi investigado antes? | handbook/inquiries/ |
| O que foi feito naquela sessão específica? | pnpm run logbook |
| O que significa este termo de negócio? | Glossário (nesta wiki) |
As regras moram em .claude/rules/ e entram no contexto automaticamente quando o padrão paths: dá match com o arquivo aberto. Elas cobrem: Domain, Application, Adapters, Public API, borda HTTP, persistência, primitivas, runtime, testes, supply-chain, jobs/workers, CNAB, e regras por Bounded Context (auth, contracts, financial, partners).
Warning
Elas só são ativadas via Read/Edit/Write.
Ler um arquivo de código com cat ou head não carrega regra nenhuma — quem inspeciona o repositório assim trabalha no escuro, sem o harness. O hook block-bash-file-io.sh recusa essa forma, e recusa também a escrita por sed -i ou > arquivo.ts, que fura o Prettier do PostToolUse.
Buscar não é ler: cat x.ts | grep e qualquer pipeline seguem liberados de propósito, assim como git show e caminhos fora do repositório.
Estas diretrizes têm como fonte primária o CLAUDE.md. Estão refletidas aqui apenas como ponteiros, nunca como cópia: a fonte de verdade continua sendo lá.
- Verdade Absoluta: O código é a verdade sobre o estado atual; o ADR é a verdade sobre as decisões. Divergências são defeitos estruturais a corrigir, não textos a embelezar.
-
Tolerância Zero a Regressões: Qualquer vermelho — teste,
lint,typecheck, hook ou build — é regressão a corrigir agora, tenha ou não sido causado pelo diff atual. A justificativa "já estava quebrado" não encerra o turno. -
Idioma e Nomenclatura: Código em Inglês (EN), prosa em PT-BR com acentuação correta. O Bounded Context se chama
contracts; o modelo se chama Contrato. Jamais escrevamodules/contratos/. - Segurança Pública: Issues, PRs, commits e comentários têm leitura pública. É terminantemente proibido comitar hosts internos, IPs, credenciais, chaves de API ou dados reais de clientes (PII).
- Filtre o conteúdo: Certifique-se de que não é uma Rule, ADR, histórico, Issue ou passível de validação por um gate.
- Mantenha o padrão de idioma: Escreva a prosa em PT-BR formal; mantenha identificadores técnicos e blocos de código em Inglês.
- Cite a fonte primária: Referencie o próprio código ou a documentação oficial. Documentação que parafraseia outra documentação é uma falha de sincronia esperando para acontecer.
- Evite números mágicos (hardcoded): Não escreva "temos 8 módulos" ou "lido até o ADR-0068". No código, testes garantem a contagem; aqui, a disciplina é sua.
-
Sincronize sempre: Após qualquer edição via interface web, traga as mudanças da nuvem para o disco local:
pnpm run wiki:sync
- Glossário — o vocabulário do negócio em PT-BR e o nome que ele tem no código, por módulo, com os prefixos de tabela e os erros comuns de tradução.