julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
48 lines
2.5 KiB
Markdown
48 lines
2.5 KiB
Markdown
# AGENTS.md — Guia para agentes de IA no repositório SAR
|
|
|
|
> Pre-requisito de leitura para qualquer agente trabalhando neste repositório.
|
|
|
|
## Fontes da verdade (ler ANTES de propor código)
|
|
|
|
1. **[`STACK.md`](STACK.md) v2.2** — tecnologias, versões, monorepo, multi-tenancy, infra
|
|
2. **[`CODING-RULES.md`](CODING-RULES.md) v2.0** — invariantes + pegadinhas críticas 🔥
|
|
3. **[`brand.md`](brand.md)** — identidade visual JCS
|
|
|
|
## Phase 1/2 artifacts (contexto estratégico)
|
|
|
|
- [`design-artifacts/A-Product-Brief/`](design-artifacts/A-Product-Brief/) — Brief estratégico completo
|
|
- `00-handover-summary.md` ⭐ entrada rápida
|
|
- `01-product-brief.md` (Brief)
|
|
- `02-content-language.md` (tom, vocabulário canônico, SEO)
|
|
- `03-visual-direction.md` (Visual DNA)
|
|
- `04-platform-requirements.md` (Stack consolidada)
|
|
- [`design-artifacts/B-Trigger-Map/`](design-artifacts/B-Trigger-Map/) — Personas + driving forces + feature impact
|
|
- `00-trigger-map.md` ⭐ hub
|
|
- `01-business-goals.md`
|
|
- `personas/02-05-*.md` (Rafael, Sandra, Daniel, Alice)
|
|
- `06-feature-impact-analysis.md`
|
|
|
|
## Regras essenciais
|
|
|
|
1. **Antes de propor tecnologia fora de STACK.md:** pergunte e justifique (RFC em `docs/adr/NNN-titulo.md`)
|
|
2. **NestJS é CJS** (PGD-DB-004) — `apps/api/package.json` sem `"type": "module"`
|
|
3. **Multi-tenancy é BD-por-workspace** (ADR 0006) — sem `tenantId` em modelos de domínio
|
|
4. **Vocabulário canônico:** Cliente · Rep · Orçamento · Pedido · Faturado · Visita · Carteira · Inativo · Painel · Aprovação
|
|
5. **Tom de microcopy:** Direto · Profissional sem ser frio · Confiante · Específico · Empático nos momentos difíceis
|
|
6. **Visual:** Modern Flat + Minimal · JCS Blue `#004a99` único accent · Plus Jakarta Sans · radius 12/20 · sombra `0 4px 25px rgba(0,0,0,0.05)`
|
|
7. **Personas com prioridades:** Rafael PRIMARY (mobile-first PWA iOS) · Sandra SECONDARY · Daniel SECONDARY · Alice TERTIARY
|
|
8. **P0 absoluto:** zero pedidos perdidos por bug/sync (force R-3 do Rafael)
|
|
|
|
## Conventional commits
|
|
|
|
Conforme STACK.md §19: `feat, fix, chore, docs, refactor, test, perf, style, ci, build`.
|
|
|
|
## Não fazer
|
|
|
|
- ❌ Sem `console.log` em produção (use Pino estruturado)
|
|
- ❌ Sem `any` / `@ts-ignore` sem justificativa
|
|
- ❌ Sem `process.env.X` direto (use Zod-validated config)
|
|
- ❌ Sem `import { prisma }` singleton em service de domínio (PGD-DB-009 — multi-tenancy BD-por-workspace)
|
|
- ❌ Sem `db push` em produção (PGD-DB-001 — migrate via 5432 direto)
|
|
- ❌ Sem secret runtime embutido no build/bundle (PGD-SEC-002 — Vault Agent)
|