Quality Revisao Aderencia

Revisao de Aderencia a Skills e Rules

Use esta skill como ultima etapa antes de declarar uma tarefa concluida e, em mudancas grandes, tambem ao terminar cada etapa significativa (modulo novo, camada nova, refator estrutural). O objetivo e fechar o ciclo TDD/quality e impedir desvios silenciosos.

Quando rodar

Regra absoluta de gatilho — antes de qualquer frase de conclusao:

Antes de escrever no resumo final QUALQUER uma destas frases (ou equivalente em outro idioma), VOCE PRECISA ter rodado a checklist objetiva desta skill:

• "concluido" / "completo" / "completa" / "pronto" / "feito" / "terminei" / "finalizado" / "encerrado"
• "the refactoring is complete" / "refactor is done" / "implementation complete" / "all done"
• "refatoracao concluida" / "feature pronta" / "task pronta" / "tudo certo"
• Qualquer declaracao categorica de fim de tarefa (mesmo implicita: "rodei tudo, passou", "all checks pass", etc.)

Se a checklist objetiva (secao "Pontos a verificar") tem 2 ou mais itens vermelhos, voce esta PROIBIDO de usar qualquer dessas frases. Use o formato WIP transparente em vez (secao "Formato no reporte final QUANDO refatoracao esta em WIP").

Declarar conclusao com itens vermelhos sem WIP = DESVIO grave de honestidade, anula o credito do trabalho feito.

Outros gatilhos:

• Ao terminar uma implementacao, fix ou refator, antes do resumo final ao usuario.
• Ao concluir um modulo novo, antes de seguir para o proximo.
• Ao concluir uma camada (domain/application/interface) novamente, antes de seguir.
• Sempre que uma extensao criar modulo novo: aplique a checklist completa SEPARADAMENTE ao modulo novo (suite e2e propria, README proprio, cobertura propria, literal unions, etc.), mesmo que o modulo existente ja tenha cobertura completa.
• Quando o usuario pedir explicitamente revisao de aderencia.

Sintoma da skill nao rodada (auto-deteccao):

Se voce esta prestes a escrever uma frase de conclusao e NAO consegue listar mentalmente o status (❌/✅) dos 9 itens da checklist objetiva nem dos anti-padroes desta secao, voce nao rodou a skill. Pare, leia esta skill, rode item-a-item, depois decida entre "concluido" ou "WIP transparente".

Fluxo

1. Liste as skills e rules ATIVAS para a stack e tipo de mudanca (consulte .agents/skills e .agents/rules).
2. Identifique se a mudanca e criacao inicial ou extensao (projeto existente). Em extensao, identifique modulos NOVOS criados na mudanca vs modulos EXISTENTES tocados.
3. Enumere os pontos verificaveis: estrutura, camadas, nomes, tipagem do dominio, idioma do codigo, codigos de erro, lint, testes, cobertura, documentacao.
4. Em extensao, aplique a checklist completa SEPARADAMENTE para cada modulo novo. Modulo novo herda zero credito do modulo existente: precisa ter sua propria suite e2e completa (4 cenarios minimos quando aplicavel), seu proprio README, sua propria cobertura ≥ 80%, suas proprias literal unions, etc.
5. Para cada ponto, compare com o codigo produzido (working tree e diff). Marque cada item como OK ou DESVIO.
6. Quando houver desvio, decida:

• Corrigir agora (default) se o ajuste cabe no escopo da tarefa.
• Registrar bloqueio concreto se a correcao depende de algo externo.

1. Aplique as correcoes, rode lint/format/tests novamente e reavalie ate ficar limpo.
2. Em extensao, reporte tambem debito herdado visivel na area tocada (DESVIOs pre-existentes nao introduzidos por esta mudanca, mas visiveis no modulo/arquivo editado). Veja secao "Debito herdado".
3. Reporte ao usuario o resultado do checklist com OK/DESVIO/corrigido por item, antes do resumo final da tarefa.

Pontos a verificar

Esta lista cobre os desvios mais comuns observados em iteracoes anteriores. Ela nao substitui as skills/rules; e um checklist operacional.

Arquitetura

• Identifique a skill de arquitetura ativa antes de avaliar: Clean Arch (architecture-ddd-clean-arch) exige domain/application/interface; Hexagonal (architecture-ddd-hexagonal) exige domain/application/adapters/in+adapters/out. A escolha segue a precedencia: padrao do projeto > pedido do usuario > default Clean Arch. Modulo misturando os dois layouts e DESVIO.
• Modulo tem as camadas minimas exigidas pela arquitetura ativa.
• Camada de entrada (interface ou adapters/in) chama application/caso de uso; application chama domain. Sem atalhos da interface direto para o domain.
• Dominio NAO contem: parsing textual, IO, serializacao, framework, mensagens humanas, import de adapter.
• Application NAO faz parsing textual cru (tokenizar string, split, regex em argv, Number(text), JSON.parse(body)). Esses passos sao da camada de entrada (interface ou adapters/in). Application recebe DTO/Request ja tipado e orquestra dominio.
• Em Hexagonal: portas de saida declaradas no nucleo; implementacoes em adapters/out; wiring em config/ ou entrypoint.

Tipagem do dominio

• Quando o conjunto de valores aceitos for finito (operador, status, papel, codigo), a assinatura do dominio expressa isso por tipo (Literal, literal union, enum, typed alias).
• O tipo expressivo esta USADO na assinatura, nao apenas exportado.
• Nao ha validacao duplicada do conjunto (uma vez na interface, outra dentro do dominio com default/else).

Modelagem tatica (Aggregate, Entity, Value Object)

• Conceitos com identidade ou semantica propria (TaskId, UserId, TenantId, Money, BillingMonth, EmailAddress, Cpf) estao modelados como Value Object com invariantes no construtor, nao como string/number cru.
• Aggregates expoem um Aggregate Root explicito como classe com metodos, nao type/record mutavel por funcoes externas. Entities filhas do aggregate sao mutaveis SO via metodos do root (ex.: project.completeTask(...), nunca task.status = "done" direto nem setProjectTaskStatus(project, ...) externa que muta o campo).
• Aggregate root e dono da colecao de seus filhos. Composite externo (type X = XAggregate & { children: ... } definido em outro modulo ou no shared-kernel, com mutacao da colecao por fora via cast) e DESVIO; a colecao mora dentro do aggregate root, manipulada por seus metodos.
• Referencias entre aggregates sao por ID (VO de identidade), nao por objeto direto.
• Cross-BC: nenhum BC importa entity ou aggregate de outro BC. Comunicacao via porta + DTO proprio do BC consumidor, com VOs de identidade compartilhados em src/shared-kernel/value-objects/ ou duplicados intencionalmente.

Shared-kernel restrito

src/shared-kernel/ so pode conter: value-objects/ (VOs de identidade compartilhados) + errors.ts opcional (classe base de erro) + event-types.ts opcional (tipos de evento). Tudo o mais e DESVIO:

• shared-kernel/application/ = DESVIO.
• shared-kernel/infrastructure/ = DESVIO.
• shared-kernel/interface/ = DESVIO.
• shared-kernel/domain/.ts com state composto cross-BC (ProjectManagementState, Tenant & { clients }) = DESVIO.
• Helpers como findTenant/findClient/findProject em shared-kernel/application/ = DESVIO.

Quando shared-kernel cresce alem disso, o monolito foi renomeado, nao quebrado.

Isolamento de estado por BC

Cada BC tem state, repositorio e schema persistido proprios:

• Port de repositorio do BC retorna State proprio (ex.: TenantState), NAO um composto cross-BC (ProjectManagementState).
• Adapter concreto implementa o repositorio diretamente, NAO via classe vazia herdando do shared-kernel.
• Schema persistido por BC. Se a stack obriga arquivo unico, sub-arvore versionada por BC com cada repositorio acessando SOMENTE a sua sub-arvore.

Layout estrutural

• Cada modulo segue src//{domain, aggregates, value-objects, application, infrastructure, interface}.
• aggregates/ e value-objects/ ficam no mesmo nivel de domain/, NUNCA dentro de domain/.
• Cada aggregate root em arquivo proprio (aggregates/.ts). Cada VO em arquivo proprio (value-objects/.ts).
• src/shared-kernel/value-objects/ na RAIZ de src/ para VOs de identidade compartilhados. Nunca dentro de outro modulo.
• Bounded context separado = src// irmao, com estrutura completa. Subpastas dentro de domain/ (domain/tenancy/, domain/billing/) NAO sao BCs.

Idioma do codigo

• Identificadores em ingles (variaveis, funcoes, classes, modulos, pacotes, testes).
• Mensagens ao usuario nao sao literais traduzidos no dominio/application. Dominio/application lancam codigo estavel snake_case ingles; interface resolve para texto via dicionario/i18n.

Nomes e estrutura

• Nome do pacote/modulo reflete o DOMINIO, nao a interface. Sufixos _cli, _api, _web so no nome publicado.
• src/ na raiz; sem pasta intermediaria com nome do projeto.
• Testes seguem a rule da linguagem: colocalizados (Go/Rust/TS/JS) ou em tests// (Python/PHP/etc).
• README na raiz e README de cada modulo (sem README de submodulo de camada).

Lint, format, manifesto

• Linter idiomatico instalado e configurado (ruff, biome/eslint, clippy, golangci-lint, etc.).
• Scripts lint e format no manifesto invocam ferramentas REAIS, nao alias de typecheck/build/test.
• Runtime declarado em projeto novo (engines.node+.nvmrc em Node, requires-python em Python, etc.).
• Lint roda limpo, ou apontamentos foram corrigidos. Nenhum aviso silenciado sem justificativa.

Testes e cobertura

• Suite roda verde.
• Cobertura >= 80% ou bloqueio explicado.
• Testes cobrem caminho feliz e erros relevantes; nao ha teste vazio ou snapshot sem asseracao.
• Se o modulo persiste estado externo (arquivo, banco, fila, cache, broker, HTTP) ou expoe entrypoint executavel (CLI, HTTP server, daemon), existe ao menos um teste e2e cobrindo o fluxo cross-command/cross-request, alem de unit e integration. Integration sozinho NAO basta.
• Se o modulo tem autorizacao/permissao, validacao cruzada ou multiplos comandos, a suite e2e cobre tambem fluxos criticos de erro (permissao negada, recurso inexistente, validacao de entrada), nao apenas o happy path.
• Em extensao: modulo novo criado durante a extensao precisa de suite e2e propria com cobertura completa dos 4 cenarios (happy + permissiondenied + notfound + invalid_input), independente do modulo existente ja ter cobertura completa. O fato de o modulo existente ter 6 e2e no padrao nao isenta o modulo novo de cobrir os mesmos cenarios para suas proprias operacoes.

Portas, casos de uso e politicas

• Quando ha 2+ portas (interfaces de saida) na application, cada uma vive em seu proprio arquivo em application/ports/.ts (Clean Arch ou Hex). Multiplas portas declaradas dentro de use-cases.ts = DESVIO.
• Quando ha 5+ casos de uso na application, cada um vive em seu proprio arquivo em application/use-cases/.ts. Arquivo unico use-cases.ts ou Service monolitico com 5+ metodos publicos = DESVIO.
• Quando o dominio expoe 3+ funcoes assertCan*/canDo*/mayAccess* que so diferem em listas de papeis/estados aceitos, substitua por uma policy table (Record>) + helper generico assertCan(role, action). Funcoes espelhadas = DESVIO.
• Funcao assertCan*/assert*/validate* com corpo vazio ou apenas return; mantida por simetria = DESVIO; remova ou absorva no helper generico.

Codigos de erro

• O code/kind/reason da classe de erro deve ser enumeracao explicita (literal union em TS, Literal[...]/Enum em Python, enum em Rust/Java/C#). code: string cru = DESVIO; perde a garantia de exaustividade entre codigos e catalogo de mensagens.
• O dicionario de mensagens da interface deve ser tipado como Record (ou equivalente). Record = DESVIO; aceita typo silenciosamente e nao alerta sobre codigo novo sem mensagem.

Fronteira de modulo

• Cada diretorio irmao em src/ e um bounded context com vocabulario proprio. Adapter de persistencia, cliente HTTP, parser, mapper do PROPRIO modulo nao sao modulos irmaos: ficam como submodulo de camada (infrastructure/ em Clean Arch ou adapters/out/ em Hexagonal) dentro do modulo dono.
• A decisao vale tambem em extensoes. Em projeto existente, bounded context novo (vocabulario proprio, ciclo de vida proprio) vira src// irmao, NUNCA enxertado no modulo existente. "Preservar padrao local" vale para naming/estilo/layout, nao para misturar bounded contexts no mesmo modulo.
• Sintomas de vazamento (cada um sozinho ja e DESVIO): tipo de entidade existente ganhou campo com vocabulario do novo dominio (Task.completedBillingMonth, User.subscriptionTier); State/agregado existente ganhou colecao do novo dominio (ProjectManagementState.monthlyCharges); constante/regra do novo dominio em arquivos do dominio existente (COMPLETED_TASK_CHARGE_CENTS em domain/project.ts); policy table existente ganhou actions do novo dominio (issue_monthly_charges); UX existente passou a exigir campos do novo dominio (complete-task --billing-month); README do modulo existente cita novos dominios no titulo/responsabilidade.

Documentacao

• README da raiz e do modulo refletem a estrutura atual.
• Comandos documentados foram validados.

Debito herdado (em extensao)

Em extensao de projeto existente, o agente toca arquivos/modulos que podem conter DESVIOs pre-existentes — codigo nao introduzido por esta mudanca mas visivel no diff ou na vizinhanca. A regra:

• Reportar, nao obrigar correcao. Debito herdado vai em secao separada na resposta final, listada como "Debito herdado visivel" (nao como "DESVIO desta mudanca"). A decisao de corrigir e do usuario.
• Nao expandir escopo silenciosamente. Refatorar codigo legado fora do pedido do usuario contraria a precedencia "preservar padrao local + escopo da tarefa". Mencionar o debito permite ao usuario decidir conscientemente.
• Quando corrigir junto: apenas se (a) a correcao e trivial e diretamente relacionada ao escopo, OU (b) o debito impede a entrega correta da mudanca, OU (c) o usuario autorizou a refatoracao. Caso contrario, apenas reporte.

Exemplos de debito herdado a reportar:

• *Service monolitico com 5+ metodos publicos (regra de "use cases por arquivo" violada antes da mudanca).
• Funcao assertCan* vazia ou funcoes espelhadas que sobreviveram a iteracoes anteriores.
• code: string cru em classe de erro existente.
• Record em catalogo de mensagens antigo.
• Tipos sem readonly quando o padrao do projeto e imutavel.
• any remanescente em codigo legado.
• README desatualizado para a estrutura atual.

Formato no reporte final

## Revisao de aderencia

### DESVIOs desta mudanca (corrigidos)
- ... (lista de itens corrigidos)

### Debito herdado visivel (nao corrigido nesta mudanca)
- src/project-management/application/project-management-service.ts: classe com 11 metodos publicos viola a regra "5+ casos de uso em arquivos proprios". Pre-existente; correcao fora do escopo desta extensao.
- ...

Formato no reporte final QUANDO refatoracao esta em WIP

Quando a checklist objetiva de conclusao (process-refatoracao-segura secao 7) tem 2+ itens falhando, NUNCA declare "refatoracao concluida". Use este formato:

## Refatoracao em andamento (WIP)

### Feito
- (lista do que foi efetivamente movido/extraido/migrado)

### Pendente (bloqueia "concluido")
- (lista objetiva: o que ainda precisa ser feito para fechar a checklist objetiva)
- (cite os itens da checklist que ainda falham, com caminho dos arquivos envolvidos)

### Itens da checklist objetiva (status atual)
1. Modulo original reduzido para ~30% ou removido: ❌/✅
2. Cada BC novo com estrutura completa: ❌/✅
3. Composition root roteando BCs novos: ❌/✅
4. Suite de testes por BC novo: ❌/✅
5. Migracao de dados decidida e implementada: ❌/✅
6. Isolamento de estado real (cada BC com state/port/repo/schema proprios; sem repositorio vazio herdando): ❌/✅
7. shared-kernel dentro do limite (so value-objects + opcionalmente errors/event-types): ❌/✅
8. Nenhum modulo (independente do nome) define composite cross-BC ou e "monolito disfarcado" (sem aggregates/use-

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gianverdum](https://github.com/gianverdum)
- **Source:** [gianverdum/ai-dev-skillset](https://github.com/gianverdum/ai-dev-skillset)
- **License:** MIT

Install and usage instructions live in the source repository linked above.