# Engineering Dev Guidelines

> Guia de engenharia web Java-centric segmentado em ficheiros na mesma pasta. **parceria.md** (§1 colaboração, qualidade de código, Windows). **arquitetura.md** (§2–7 stack, MVP, MVC/DDD, HTTP). **front-tecnico.md** (§8–9 design system, SPA, API client, estado). **backend-java.md** (§10 Spring, erros, JPA, perfis). **dados-seguranca.md** (§11–14 BD, filas, auth, segurança). **ops.md** (§15–18 observabilidade, CI, ADR, monorepo gateway/worker). **ui-visual.md** (tokens obrigatórios, grid 8 pt, dark mode, microinterações, shadcn/Tailwind, identidade, anti-UI genérica de IA, a11y). O agente deve **abrir os ficheiros que a tarefa exige**, não só este SKILL. Use ao implementar ou rever backend, front, UI, dados ou operações.

- Skill: `kaualealz/engineering-dev-guidelines` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add kaualealz/engineering-dev-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaualealz/engineering-dev-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: KauaLealz (https://skillmd.com/u/kaualealz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kaualealz/engineering-dev-guidelines

---


# Engineering dev guidelines

Esta skill está **dividida em ficheiros `.md`** ao lado deste `SKILL.md`. O Cursor entra por aqui; o agente deve **ler os segmentos certos** (progressive disclosure — um nível de links).

## Ordem prática de escolha (decisão rápida)

1. **Só “embelezar” ecrã / tipografia / motion / anti-template** → **[ui-visual.md](ui-visual.md)** (e **front-tecnico.md** se também mexer em `fetch`, rotas ou estrutura de pastas).
2. **SPA: hooks, cliente HTTP, pastas, TanStack Query, cookies** → **[front-tecnico.md](front-tecnico.md)**.
3. **Java: controller, service, JPA, `application.yml`, exceções API** → **[backend-java.md](backend-java.md)**.
4. **Postgres/Mongo, migrações, SQS/Rabbit, JWT, `/internal`, CORS** → **[dados-seguranca.md](dados-seguranca.md)**.
5. **Logs, tracing, Docker/CI, ADR, desenho gateway + worker** → **[ops.md](ops.md)**.
6. **“MVC ou DDD?”, MVP, validação `@Valid`, paginação API** → **[arquitetura.md](arquitetura.md)**.
7. **Qualquer código ou refactor** → incluir **[parceria.md](parceria.md)** (regras de parceria, §1.13, PowerShell, segurança em YAML). **Se tiver dúvida**, começar por aqui.

## Contexto por projeto

Cruzar sempre com **README**, **`docs/`** e **ADRs** do repositório em curso.

## Checklist §1.0 (memória imediata)

1. **Contexto**: app/serviço do repo (API, worker, `web`, BFF) + módulo + objetivo; se ambíguo → **uma pergunta**.
2. **grep** antes de duplicar padrões.
3. **Padrão do repo** + erros API (detalhe em **backend-java.md** §10.2–10.3).
4. **Um eixo** por entrega; diff revisável.
5. **Validação**: PowerShell + Maven/Gradle no módulo certo (**parceria.md** §1.9).
6. **Leitura em paralelo** em tarefas médias/grandes.

Pormenor completo da §1: **[parceria.md](parceria.md)**.

## Tabela de ficheiros (§ e gatilhos)

| Ficheiro | § | Incluir quando a tarefa envolve | Palavras-chave |
|----------|---|----------------------------------|----------------|
| [parceria.md](parceria.md) | §1 | Comportamento do agente, escopo, Git, overengineering, DRY/SOLID, argumentos em variáveis, PowerShell, `SecurityConfig` / YAML | *sempre código*, *refactor*, *Windows*, *commits* |
| [arquitetura.md](arquitetura.md) | §2–§7 | Escolha de stack, MVP, modular, **MVC vs DDD**, gateway, `@Valid`, webhooks, paginação | *MVC*, *DDD*, *MVP*, *OpenAPI*, *gateway* |
| [front-tecnico.md](front-tecnico.md) | §8–§9 | Tokens de DS, a11y base, **cliente HTTP único**, pastas, Query/SWR, estados loading/erro | *React*, *Vue*, *fetch*, *axios*, *i18n*, *CSRF* |
| [backend-java.md](backend-java.md) | §10 | Spring Boot, **code/type** erros, JPA/Flyway, records, **perfis yml**, RestClient, `@Transactional` | *Spring*, *JPA*, *Flyway*, *DTO*, *handler* |
| [dados-seguranca.md](dados-seguranca.md) | §11–§14 | Escolha de BD, convenções SQL/Mongo, **fila**, OAuth/RBAC, TLS, `/internal` | *Postgres*, *Mongo*, *SQS*, *JWT*, *RBAC* |
| [ops.md](ops.md) | §15–§18 | Logs, tracing opcional, Compose, **tópicos ADR**, padrão monorepo (edge + APIs + worker) | *Docker*, *CI*, *ADR*, *Micrometer*, *monorepo* |
| [ui-visual.md](ui-visual.md) | extensão | **Tokens** (cores/raios/spacing), grid 8 pt, dark mode, microinterações, tipo, sombra, anti-UI de IA, checklist visual | *bonito*, *layout*, *CSS*, *tokens*, *dark mode*, *shadcn*, *Lovable*, *Replit* |

**Full-stack típico**: **parceria.md** + **arquitetura.md** ou **backend-java.md** + **front-tecnico.md**; se a UI for protagonista, **ui-visual.md**.

**Mapa § → ficheiro**: §1 → parceria · §2–7 → arquitetura · §8–9 → front-tecnico · §10 → backend-java · §11–14 → dados-seguranca · §15–18 → ops.

---

## Quando em dúvida sobre produto

Não inventar regra de negócio: perguntar ao humano ou apontar para **documentação de produto** do repositório (`docs/`, README, ADRs).

## Após planejamento

Quando a tarefa vier de um plano (feature, ADR), ao implementar manter consistência com o que foi decidido; se o plano e o código divergirem, sinalizar antes de silenciosamente seguir só uma das partes.

## Planejamento de produto

Para planear antes de codar, usar a skill **product-technical-planning**.