Convenções obrigatórias para APIs em Bun + Hono + Drizzle + Zod. Use ao escrever, revisar ou discutir código de API: rotas Hono, services, repositories Drizzle, validação Zod, typed errors, schemas e migrations, auth JWT, testes com bun test. Stack: Bun, Hono, Drizzle, Zod, uuidv7, Biome.
The convention text is written in Portuguese and is shown here as it is in the repository.
API Bun + Hono — contexto obrigatório
Projeto que já existe? Estas convenções valem para código novo e para remodelação. Em sistema legado, de cliente ou de outra equipe, a arquitetura do projeto manda: antes da primeira mudança, siga
veritas:projeto-existente.Dado pessoal? Código que toca CPF, contato, saúde, dado financeiro ou credencial, e todo log, exportação ou integração, segue também a
veritas:lgpd, em qualquer modo.
Você é um engenheiro sênior do time. Ao escrever, revisar ou discutir código de API, siga obrigatoriamente os padrões deste contexto.
Stack
Runtime: Bun · HTTP: Hono · ORM: Drizzle + postgres · Validação: Zod · IDs: uuidv7 · Linter: Biome
@/* mapeia para src/*. Use sempre em imports internos.
Libs proibidas
express,fastify— use Honoprisma,typeorm,sequelize— use Drizzleclass-validator,joi,yup— use Zoduuid(v4) — useuuidv7eslint,prettier— use Biomejest,vitest— usebun test
As nove proibições
Nunca gere código que viole qualquer uma. Os exemplos de cada uma, com o certo e o errado lado a lado, estão em rules.md.
- Lógica de negócio fora do Service
- Service com mais de uma responsabilidade
- Entrada HTTP sem validação Zod
- Erros genéricos — sempre use typed
AppError - Interface de model redundante quando o tipo do Drizzle já serve
- Mapper desnecessário em queries simples
- Coluna do banco sem snake_case explícito
- Imports com caminhos relativos profundos
- Refresh token armazenado no banco
Comportamento esperado
- Sempre valide entradas HTTP com Zod
- Sempre use os typed errors de patterns/error-handling.md
- Use os tipos inferidos do Drizzle (
$inferSelect,$inferInsert) em repositories — sem interfaces redundantes - Use mapper apenas quando a query retorna um tipo composto (join com objeto aninhado)
- Testes só quando solicitado
- Docs e Bruno só quando solicitado
Onde consultar
Leia o arquivo que a tarefa pede — não todos de uma vez.
| Vou... | Leia |
|---|---|
| entender a estrutura, camadas e data flow | architecture.md |
| escolher lib, versão ou script | stack.md |
| nomear arquivo, pasta, coluna ou variável | conventions.md |
| conferir uma proibição em detalhe | rules.md |
| mexer em login, JWT ou refresh token | auth.md |
| criar um módulo do zero | patterns/new-module.md |
| tratar erro | patterns/error-handling.md |
| fazer listagem paginada | patterns/pagination.md |
| escrever schema Drizzle | patterns/drizzle-schemas.md |
| escrever teste | patterns/testing.md |
| gerar docs ou coleção Bruno | patterns/generate-docs.md |
Origem
Convenções de uma API em produção, antes mantidas num repositório de
contextos que era copiado para .context/api dentro de cada projeto; aqui
elas viajam com a skill.