nexus-core-v3 3.0.0

package/knowledge/engineering/clean-code-principles.md

@@ -0,0 +1,429 @@
+---
+id: clean-code-principles
+domain: engineering
+agents: [dev]
+when: "ao escrever ou refatorar qualquer código, para garantir legibilidade e manutenibilidade"
+---
+
+# Clean Code — heurísticas de legibilidade e manutenção
+
+Código se lê muito mais vezes do que se escreve. A régua aqui é a do `clean-code-javascript`
+de Ryan McDermott (adaptação do _Clean Code_ de Robert C. Martin para JS) — não um style guide,
+mas um guia para produzir software **legível, reutilizável e refatorável**. Os exemplos abaixo são
+os pares reais do repositório-fonte (JavaScript). A regra-mãe: **toda decisão de código tem que se
+justificar** — se um nome, um argumento ou uma condicional só existe porque "saiu assim", é dívida.
+
+> Aviso do próprio autor: nem todo princípio precisa ser seguido à risca, e poucos são unânimes. São
+> diretrizes. Mas elas vêm de anos de experiência coletiva — use-as como pedra-de-toque ao avaliar a
+> qualidade do código que você produz.
+
+## O problema / os tells
+
+Se o diff tem 3+ destes, ele cheira a código apressado, não a craft:
+
+1. **Nomes não-pesquisáveis e mágicos** — `setTimeout(blastOff, 86400000)`. Ninguém sabe o que é
+   `86400000`, e você não consegue dar `grep` num número solto no meio do código.
+2. **Nomes não-pronunciáveis / abreviados** — `yyyymmdstr`, `l`, `d1`. Se você não consegue falar o
+   nome em voz alta numa code review, ele está errado.
+3. **Vocabulário inconsistente pro mesmo conceito** — `getUserInfo()`, `getClientData()`,
+   `getCustomerRecord()` espalhados, todos buscando a mesma coisa.
+4. **Funções com 4+ argumentos posicionais** — `createMenu("Foo", "Bar", "Baz", true)`. Na chamada,
+   ninguém sabe o que cada posição significa, e o `true` no fim é um enigma.
+5. **Argumento-flag booleano** — `createFile(name, temp)`. A flag denuncia que a função tem dois
+   caminhos, logo faz mais de uma coisa.
+6. **Função que faz várias coisas** — filtra, transforma e dispara no mesmo corpo; impossível de
+   testar ou reusar em pedaços.
+7. **Side effects escondidos** — função que muta uma variável global ou o objeto recebido por
+   parâmetro, em vez de receber e retornar.
+8. **Condicionais negativas e cruas** — `if (!isDOMNodeNotPresent(node))`: dupla negação que trava o
+   leitor; `if (fsm.state === "fetching" && isEmpty(listNode))` sem nome que explique a intenção.
+9. **Herança por preguiça** — `EmployeeTaxData extends Employee` quando a relação é "tem-um", não "é-um".
+10. **`catch (error) { console.log(error) }`** — engole o erro sem plano de reação.
+11. **Código morto** — `oldRequestModule` que ninguém chama, mantido "por via das dúvidas". O histórico
+    do git já guarda isso.
+
+## Os princípios (com pares bad→good reais)
+
+### 1. Nomes pesquisáveis (sem números mágicos)
+
+Constantes nomeadas em vez de literais soltos — para o leitor entender e para o `grep` achar.
+
+```javascript
+// Bad — o que diabos é 86400000?
+setTimeout(blastOff, 86400000);
+
+// Good — constante nomeada e maiúscula
+const MILLISECONDS_PER_DAY = 60 * 60 * 24 * 1000; // 86400000
+
+setTimeout(blastOff, MILLISECONDS_PER_DAY);
+```
+
+### 2. Nomes pronunciáveis e significativos
+
+Você lê mais código do que escreve; abreviação economiza segundos na escrita e custa minutos na leitura.
+
+```javascript
+// Bad
+const yyyymmdstr = moment().format("YYYY/MM/DD");
+
+// Good
+const currentDate = moment().format("YYYY/MM/DD");
+```
+
+E sem mapeamento mental: nomeie a variável do loop pelo que ela é, não `l`.
+
+```javascript
+// Bad — "espera, o que é `l` mesmo?"
+locations.forEach(l => { /* ...muitas linhas... */ dispatch(l); });
+
+// Good
+locations.forEach(location => { /* ... */ dispatch(location); });
+```
+
+### 3. Mesmo vocabulário pro mesmo tipo
+
+Um conceito, um nome. Escolha um e use em todo lugar.
+
+```javascript
+// Bad
+getUserInfo();
+getClientData();
+getCustomerRecord();
+
+// Good
+getUser();
+```
+
+### 4. ≤2 argumentos — objeto quando precisar de mais
+
+Mais de 2-3 parâmetros leva à explosão combinatória de casos de teste e some com a clareza na chamada.
+Quando precisar de muitos, passe **um objeto** e desestruture — a assinatura passa a documentar quais
+campos a função usa, e simula parâmetros nomeados.
+
+```javascript
+// Bad — o que é `true`? e a ordem?
+function createMenu(title, body, buttonText, cancellable) { /* ... */ }
+createMenu("Foo", "Bar", "Baz", true);
+
+// Good — campos nomeados, ordem irrelevante
+function createMenu({ title, body, buttonText, cancellable }) { /* ... */ }
+createMenu({ title: "Foo", body: "Bar", buttonText: "Baz", cancellable: true });
+```
+
+### 5. Função faz UMA coisa
+
+A regra mais importante. Quando a função faz mais de uma coisa, é difícil compor, testar e raciocinar.
+Isole cada ação.
+
+```javascript
+// Bad — itera, busca no banco, checa estado e envia, tudo junto
+function emailClients(clients) {
+  clients.forEach(client => {
+    const clientRecord = database.lookup(client);
+    if (clientRecord.isActive()) {
+      email(client);
+    }
+  });
+}
+
+// Good — cada função tem um trabalho
+function emailActiveClients(clients) {
+  clients.filter(isActiveClient).forEach(email);
+}
+
+function isActiveClient(client) {
+  const clientRecord = database.lookup(client);
+  return clientRecord.isActive();
+}
+```
+
+### 6. Sem flag booleana como argumento
+
+A flag avisa que a função tem caminhos diferentes — ou seja, faz mais de uma coisa. Separe.
+
+```javascript
+// Bad
+function createFile(name, temp) {
+  if (temp) {
+    fs.create(`./temp/${name}`);
+  } else {
+    fs.create(name);
+  }
+}
+
+// Good
+function createFile(name) {
+  fs.create(name);
+}
+
+function createTempFile(name) {
+  createFile(`./temp/${name}`);
+}
+```
+
+### 7. Evite side effects
+
+Uma função idealmente recebe valores e retorna valores — não muta estado global nem o objeto/array
+recebido. Mutar dado compartilhado gera bugs em lugares distantes. Centralize os efeitos que forem
+inevitáveis (ex.: escrever em arquivo) em um único serviço.
+
+```javascript
+// Bad — muta uma global; outra função que use `name` quebra
+let name = "Ryan McDermott";
+function splitIntoFirstAndLastName() {
+  name = name.split(" ");
+}
+
+// Good — recebe e retorna, sem tocar no de fora
+function splitIntoFirstAndLastName(name) {
+  return name.split(" ");
+}
+const newName = splitIntoFirstAndLastName(name);
+```
+
+O mesmo vale para arrays/objetos passados por parâmetro: clone em vez de mutar.
+
+```javascript
+// Bad — muta o cart de quem chamou
+const addItemToCart = (cart, item) => {
+  cart.push({ item, date: Date.now() });
+};
+
+// Good — retorna um novo cart
+const addItemToCart = (cart, item) => {
+  return [...cart, { item, date: Date.now() }];
+};
+```
+
+### 8. Evite condicionais negativas
+
+Negativa (ainda mais dupla) força o leitor a inverter a lógica na cabeça. Nomeie no positivo.
+
+```javascript
+// Bad — dupla negação
+function isDOMNodeNotPresent(node) { /* ... */ }
+if (!isDOMNodeNotPresent(node)) { /* ... */ }
+
+// Good
+function isDOMNodePresent(node) { /* ... */ }
+if (isDOMNodePresent(node)) { /* ... */ }
+```
+
+### 9. Encapsule condicionais
+
+Uma expressão booleana composta vira uma função com nome que diz a intenção.
+
+```javascript
+// Bad
+if (fsm.state === "fetching" && isEmpty(listNode)) { /* ... */ }
+
+// Good
+function shouldShowSpinner(fsm, listNode) {
+  return fsm.state === "fetching" && isEmpty(listNode);
+}
+if (shouldShowSpinner(fsmInstance, listNodeInstance)) { /* ... */ }
+```
+
+### 10. Composição > herança
+
+Se sua cabeça já foi pra `extends`, pare e pergunte se é "é-um" (herança) ou "tem-um" (composição).
+`EmployeeTaxData` não é um tipo de `Employee` — um empregado **tem** dados fiscais.
+
+```javascript
+// Bad — herança forçada numa relação "tem-um"
+class EmployeeTaxData extends Employee {
+  constructor(ssn, salary) {
+    super();
+    this.ssn = ssn;
+    this.salary = salary;
+  }
+}
+
+// Good — composição
+class Employee {
+  constructor(name, email) {
+    this.name = name;
+    this.email = email;
+  }
+  setTaxData(ssn, salary) {
+    this.taxData = new EmployeeTaxData(ssn, salary);
+  }
+}
+```
+
+### 11. SOLID em JS — os cinco
+
+**S — Single Responsibility.** Uma classe, uma razão para mudar. Separe autenticação de configuração.
+
+```javascript
+// Bad — UserSettings também verifica credenciais
+class UserSettings {
+  changeSettings(settings) {
+    if (this.verifyCredentials()) { /* ... */ }
+  }
+  verifyCredentials() { /* ... */ }
+}
+
+// Good — auth virou colaboradora
+class UserAuth {
+  constructor(user) { this.user = user; }
+  verifyCredentials() { /* ... */ }
+}
+class UserSettings {
+  constructor(user) {
+    this.user = user;
+    this.auth = new UserAuth(user);
+  }
+  changeSettings(settings) {
+    if (this.auth.verifyCredentials()) { /* ... */ }
+  }
+}
+```
+
+**O — Open/Closed.** Aberto para extensão, fechado para modificação. Em vez de `if adapter.name === ...`,
+deixe cada adapter implementar o contrato.
+
+```javascript
+// Bad — fetch precisa mudar a cada novo adapter
+fetch(url) {
+  if (this.adapter.name === "ajaxAdapter") { return makeAjaxCall(url).then(/*...*/); }
+  else if (this.adapter.name === "nodeAdapter") { return makeHttpCall(url).then(/*...*/); }
+}
+
+// Good — cada adapter tem request(); HttpRequester não muda
+fetch(url) {
+  return this.adapter.request(url).then(response => { /* transform */ });
+}
+```
+
+**L — Liskov Substitution.** Subtipo tem que substituir o tipo base sem quebrar resultados. O clássico
+Square/Rectangle: forçar `Square extends Rectangle` faz `getArea()` mentir. Modele ambos sobre `Shape`.
+
+```javascript
+// Good — sem herança que viola contrato
+class Shape { render(area) { /* ... */ } }
+class Rectangle extends Shape {
+  constructor(width, height) { super(); this.width = width; this.height = height; }
+  getArea() { return this.width * this.height; }
+}
+class Square extends Shape {
+  constructor(length) { super(); this.length = length; }
+  getArea() { return this.length * this.length; }
+}
+```
+
+**I — Interface Segregation.** Não force o cliente a depender do que não usa. Settings opcionais em vez
+de "fat interface".
+
+```javascript
+// Good — animationModule é opcional, dentro de options
+const $ = new DOMTraverser({
+  rootNode: document.getElementsByTagName("body"),
+  options: { animationModule() {} }
+});
+```
+
+**D — Dependency Inversion.** Módulo de alto nível não depende do de baixo nível — ambos dependem de
+abstração. Injete a dependência em vez de instanciá-la dentro.
+
+```javascript
+// Bad — InventoryTracker cria a dependência concreta
+class InventoryTracker {
+  constructor(items) {
+    this.items = items;
+    this.requester = new InventoryRequester(); // acoplado
+  }
+}
+
+// Good — requester é injetado (qualquer um com requestItem serve)
+class InventoryTracker {
+  constructor(items, requester) {
+    this.items = items;
+    this.requester = requester;
+  }
+}
+```
+
+### 12. Lance objetos Error, não strings; e nunca ignore o erro capturado
+
+Erros lançados são bons: o runtime te avisa que algo deu errado, com stack trace. Lance um `Error` de
+verdade (carrega mensagem **e** stack), e dê um plano para o `catch` — não engula.
+
+```javascript
+// Tell — string crua não tem stack trace
+throw "Must be of type String or Number";
+
+// Good — Error object, com stack
+throw new Error("Must be of type String or Number");
+```
+
+```javascript
+// Bad — engole o erro
+try {
+  functionThatMightThrow();
+} catch (error) {
+  console.log(error);
+}
+
+// Good — reaja: log de erro, notifique, ou reporte
+try {
+  functionThatMightThrow();
+} catch (error) {
+  console.error(error);
+  notifyUserOfError(error);
+  reportErrorToService(error);
+}
+```
+
+O mesmo vale para promises rejeitadas: trate no `.catch`, não só `console.log`.
+
+### 13. Remova código morto
+
+Se ninguém chama, apague. O histórico do git guarda. `oldRequestModule` parado ao lado do `new` só
+confunde quem lê.
+
+```javascript
+// Bad — função antiga nunca chamada, mantida "por garantia"
+function oldRequestModule(url) { /* ... */ }
+function newRequestModule(url) { /* ... */ }
+const req = newRequestModule;
+
+// Good — só o que está em uso
+function newRequestModule(url) { /* ... */ }
+const req = newRequestModule;
+```
+
+## Checklist
+
+Antes de marcar a task como pronta, responda — qualquer "sim" é dívida a corrigir:
+
+- [ ] Tem número/string mágico que deveria ser constante nomeada e pesquisável?
+- [ ] Algum nome é abreviado, não-pronunciável ou exige mapeamento mental (`l`, `d1`, `yyyymmdstr`)?
+- [ ] O mesmo conceito aparece com nomes diferentes (`getUserInfo`/`getClientData`/...)?
+- [ ] Alguma função tem mais de 2-3 argumentos posicionais sem virar objeto?
+- [ ] Há argumento booleano (flag) que denuncia dois caminhos na mesma função?
+- [ ] Alguma função faz mais de uma coisa (mistura busca, transformação e efeito)?
+- [ ] Alguma função muta estado global ou o objeto/array recebido por parâmetro?
+- [ ] Há condicional negativa (ou dupla negação) que poderia ser positiva?
+- [ ] Há booleano composto cru no `if` que mereceria uma função nomeada?
+- [ ] Usei `extends` numa relação "tem-um" em vez de composição?
+- [ ] Lancei string em vez de `new Error(...)`? Engoli algum erro com `console.log` sem reação?
+- [ ] Sobrou código morto (função/branch que ninguém chama)?
+
+## Tabela de decisão
+
+| Use isto | Quando |
+|---|---|
+| Constante nomeada (`MILLISECONDS_PER_DAY`) | houver qualquer literal numérico/string com significado no código |
+| Argumento objeto + desestruturação | a função precisar de mais de 2-3 parâmetros |
+| Duas funções separadas | você fosse passar uma flag booleana para escolher o caminho |
+| Receber + retornar (sem mutar) | a função tocaria estado global ou o objeto/array recebido |
+| Clonar (`[...cart, item]`) | precisar "alterar" um array/objeto vindo por parâmetro |
+| Função nomeada (`shouldShowSpinner`) | um `if` tiver booleano composto ou intenção não-óbvia |
+| Condicional no positivo | o nome/teste estiver no negativo (ou em dupla negação) |
+| Composição (`has-a`) | a relação for "tem-um" (`Employee` tem `TaxData`) |
+| Herança (`is-a`) | for genuinamente "é-um", houver reuso da base e mudança global desejada |
+| Injeção de dependência (DIP) | um módulo de alto nível instanciaria diretamente um concreto de baixo nível |
+| Polimorfismo / contrato comum (OCP, LSP) | um `if/switch` ramificar por `type`/`name` e tender a crescer |
+| `throw new Error(...)` + reação no `catch` | algo puder dar errado e você precisar de stack trace e plano |
+| Apagar (confiar no git) | o código não for chamado por ninguém |

package/knowledge/engineering/effective-code-review.md

@@ -0,0 +1,204 @@
+---
+id: effective-code-review
+domain: engineering
+agents: [dev, qa]
+when: "ao revisar um pull/merge request ou preparar o próprio CL para review"
+---
+
+# Code review eficaz — o padrão do Google
+
+A maioria das discussões de code review trava por falta de um critério compartilhado. Sem ele, o
+review vira gosto pessoal: o revisor segura o CL até ele ficar "do jeito dele", o autor responde na
+defensiva, e o que era pra melhorar o código vira queda de braço. Este pack destila o padrão do Google
+(`google/eng-practices`: *How to do a code review* + *The CL author guide*), porque ele resolve isso com
+**um único critério-mestre** do qual todo o resto deriva.
+
+> A fonte chama o pull request de **CL** (changelist). Aqui usamos "CL" e "PR/MR" como sinônimos.
+
+## O problema / os tells
+
+Você está num review medíocre quando vê:
+
+1. **Review como busca pela perfeição.** O revisor segura o CL porque "dá pra ficar melhor" — sem que o
+   estado atual piore o código. A fonte é direta: *"there is no such thing as 'perfect' code—there is
+   only better code."* Perfeição não é o critério; melhoria do code health é.
+2. **CLs gigantes.** Um PR de 800 linhas espalhado por 40 arquivos. Ninguém revisa de verdade: *"important
+   points get missed or dropped."*
+3. **Feedback sem severidade.** Tudo no mesmo tom. O autor não sabe o que é bloqueante e o que é gosto, e
+   trata um typo de comentário com o mesmo peso de um bug de concorrência.
+4. **Feedback como ordem, nunca como ensino.** O revisor manda "faça X" sem dizer por quê. O autor obedece
+   sem aprender; o próximo CL repete o erro.
+5. **Descrição de CL inútil.** Título "Fix bug", "Phase 1", "Add patch". Daqui a um ano, o `git log` não
+   diz nada a ninguém.
+6. **Review parado por dias.** O CL fica encalhado porque autor e revisor não chegam a acordo, ou porque
+   o revisor "depois olha". A velocidade do time inteiro cai.
+7. **Autor na defensiva.** Resposta no calor, tratando crítica ao código como ataque pessoal — *"never
+   respond in anger to code review comments."*
+
+## Os princípios
+
+### 1. O critério-mestre: aprove quando o CL melhora a saúde do código
+
+O propósito do review não é provar que o código é perfeito, é garantir que *"the overall code health of
+the codebase is improving over time."* Daí a regra de aprovação:
+
+> *"In general, reviewers should favor approving a CL once it is in a state where it definitely improves
+> the overall code health of the system being worked on, even if the CL isn't perfect."*
+
+Isso não é desculpa pra deixar passar lixo — a contrapartida é igualmente firme: *"Don't accept CLs that
+degrade the code health of the system."* O CL não precisa ser perfeito; precisa ser **melhor**, e não pode
+piorar. Quando ele claramente melhora e só restam refinamentos opcionais, aprove com comentários (o
+"LGTM with comments"): você libera o autor e confia que ele endereça os nits.
+
+```text
+# ❌ revisor segurando por perfeição
+"Funciona e está mais limpo que o anterior, mas não vou aprovar até você
+ extrair essas 3 funções, renomear o módulo e adicionar 4 testes a mais."
+
+# ✅ aprovar a melhoria, marcar o resto como opcional
+"LGTM. Melhora clara sobre o que existia. Nit: dá pra extrair `parseHeader`
+ numa função à parte depois — opcional, não bloqueia o merge."
+```
+
+### 2. O que o revisor procura (nesta ordem de importância)
+
+A fonte lista explicitamente o que olhar — **design vem primeiro**, não estilo:
+
+- **Design.** A interação das peças faz sentido? A mudança pertence a este codebase ou a uma lib? É o
+  ponto mais importante do review.
+- **Funcionalidade.** *"Does this CL do what the developer intended?"* Pensa em edge cases, concorrência,
+  bugs. Mudança de UI muitas vezes pede um demo pra entender o impacto real no usuário.
+- **Complexidade.** Está *"more complex than it should be"*? O teste prático: se *"can't be understood
+  quickly by code readers"*, é complexo demais. Cuidado com over-engineering — resolva o problema que
+  você sabe que precisa ser resolvido **agora**, não o especulado.
+- **Testes.** Há testes unit/integration/e2e adequados? Eles **falham quando o código quebra** e fazem
+  asserções úteis, sem complexidade desnecessária.
+- **Nomes.** *"long enough to fully communicate what the item is or does, without being so long that it
+  becomes hard to read."*
+- **Comentários.** Bons comentários *"explain why"* o código existe — a razão que o código não mostra
+  sozinho —, não parafraseiam o que ele faz.
+- **Estilo / consistência.** Style guide é autoridade. Divergência de gosto pessoal vira `Nit:`, não
+  bloqueio.
+- **Documentação.** README, docs e referências acompanham a mudança quando relevante.
+- **Cada linha.** Revise todo o código designado — entender cada peça importa pro próximo dev.
+- **Contexto.** Olhe o impacto sistêmico, não só o diff. E **elogie o que está bom**: reconheça boas
+  soluções, não só aponte problemas.
+
+### 3. CLs pequenos: o multiplicador de qualidade
+
+Tamanho não é detalhe — é o fator que mais muda a qualidade do review. A régua da fonte:
+
+> *"100 lines is usually a reasonable size for a CL, and 1000 lines is usually too large."*
+
+E o tamanho é sobre **mudança lógica autocontida**, não só contagem bruta: *"A 200-line change in one file
+might be okay, but spread across 50 files it would usually be too large."* O CL certo faz **uma coisa**.
+Na dúvida, *"write CLs that are smaller than you think you need to write."*
+
+Por que pequeno ganha: é revisado mais rápido (cinco minutos várias vezes), revisado a fundo (em CL
+grande *"important points get missed or dropped"*), introduz menos bugs, desperdiça menos trabalho se a
+direção estiver errada, dá menos conflito de merge, é mais fácil de desenhar bem e de reverter.
+
+```text
+# ❌ um CL: "Add user profiles"
+  migration + model + 3 endpoints + UI + refactor do auth + rename de 12 arquivos
+  → 900 linhas, 40 arquivos, ninguém revisa de verdade
+
+# ✅ sequência de CLs autocontidos
+  CL1: migration + model              (~80 linhas)
+  CL2: endpoints de leitura + testes  (~120 linhas)
+  CL3: UI de profile                  (~150 linhas)
+  → cada um revisável em minutos, mergeável e reversível sozinho
+```
+
+### 4. Dar feedback: severidade explícita, ensinar não impor
+
+**Marque a severidade.** O autor precisa distinguir bloqueante de sugestão. Prefixos da fonte:
+
+- `Nit:` — *"a minor thing. Technically you should do it, but it won't hugely impact things."*
+- `Optional (ou Consider):` — *"I think this may be a good idea, but it's not strictly required."*
+- `FYI:` — *"I don't expect you to do this in this CL, but you may find this interesting."*
+
+**Ensine, não mande.** *"Pointing out problems and letting the developer make a decision often helps the
+developer learn."* Explique o **porquê**. E quando o código está complexo demais, *"encourage developers
+to simplify code or add code comments instead of just explaining the complexity to you"* — o ganho fica
+no código, não na conversa do review. Sempre: *"courteous and respectful while also being very clear and
+helpful."*
+
+```text
+# ❌ ordem sem razão, severidade ambígua
+"Use um map aqui."
+
+# ✅ aponta o problema, ensina, marca severidade
+"Este loop aninhado é O(n²); com a lista de pedidos crescendo isso vira gargalo.
+ Um map de id→pedido resolve em O(n). Required."
+
+# nit de verdade, marcado como tal:
+"Nit: `d` poderia ser `daysUntilDue` pra ficar autoexplicativo. Opcional."
+```
+
+### 5. O guia do AUTOR
+
+- **Descrição do CL.** Primeira linha = resumo curto, no **imperativo** ("Delete the FizzBuzz RPC and
+  replace it with the new system"), dizendo **o que** muda. Corpo = **o quê e por quê**, com números de
+  bug, benchmarks e links de design. Ruins (da fonte): "Fix bug", "Fix build", "Add patch", "Phase 1",
+  "kill weird URLs" — *"do not provide enough useful information."* Bom: *"RPC: Remove size limit on RPC
+  server message freelist. Servers like FizzBuzz have very large messages and would benefit from reuse."*
+- **Responder a reviews.** *"Don't take it personally"* — a crítica é ao código, não a você. Nunca
+  responda com raiva. Se o revisor não entendeu, **conserte o código** primeiro; se não dá pra clarear,
+  adicione um comentário no código explicando o porquê; explicar só no review tool é último recurso (o
+  próximo leitor não vê a thread do PR).
+- **Discordar bem.** Pense em colaboração, não defesa: *"I went with X because of [these pros/cons]... Are
+  you suggesting that Y better serves the original tradeoffs?"*
+
+### 6. Resolver conflitos e velocidade
+
+Conflito entre autor e revisor se resolve por **fatos, não preferências**: *"Technical facts and data
+overrule opinions and personal preferences."* Style guide é autoridade no estilo. Busquem consenso; se
+não houver, apliquem os princípios deste padrão e, persistindo, escalem pra liderança técnica. Acima de
+tudo: *"Don't let a CL sit around because the author and the reviewer can't come to an agreement."*
+
+**Velocidade:** o que importa é o **tempo de resposta**, não o tempo total do CL. A régua: *"One business
+day is the maximum time it should take to respond to a code review request."* Se você não está no meio de
+uma tarefa focada, revise logo que o CL chega; se está codando concentrado, *"don't interrupt yourself"*
+— responda num ponto natural de pausa. Review lento derruba a velocidade do time inteiro.
+
+## Checklist
+
+Antes de **aprovar** um CL:
+
+- [ ] O CL **melhora** a saúde do código e **não a piora**? (critério-mestre — não exija perfeição)
+- [ ] O **design** faz sentido e a mudança pertence a este codebase?
+- [ ] Faz o que o autor pretendeu, incluindo edge cases e concorrência?
+- [ ] Não está mais complexo que o necessário, sem over-engineering pra o futuro?
+- [ ] Tem testes que **falham quando o código quebra**, com asserções úteis?
+- [ ] Nomes claros, comentários que explicam o **porquê**, docs atualizadas?
+- [ ] Revisei **cada linha** designada e elogiei o que está bom?
+- [ ] Marquei a **severidade** (`Nit:`/`Optional:`/`FYI:`) e expliquei o **porquê** de cada comentário?
+- [ ] Respondi em até **um dia útil**?
+
+Antes de **enviar** o próprio CL:
+
+- [ ] É **uma mudança autocontida** (~100 linhas; 1000 é grande demais; cuidado com o espalhamento)?
+- [ ] A descrição tem primeira linha no imperativo + corpo com **o quê e por quê** (não "Fix bug")?
+- [ ] Vou responder ao review sobre o **código**, sem levar pro pessoal?
+
+## Tabela de decisão
+
+| Situação | O que fazer |
+|---|---|
+| CL melhora o código mas não está perfeito | **Aprove** (LGTM with comments); marque refinamentos como `Nit:`/`Optional:` |
+| CL piora a saúde do código | **Não aprove**; aponte o problema com o porquê |
+| Comentário é gosto pessoal / estilo | `Nit:`; não bloqueie o merge por isso |
+| Comentário é design/funcionalidade/segurança | Required; bloqueie e explique o porquê |
+| CL > ~1000 linhas ou espalhado por dezenas de arquivos | Peça pra **quebrar** em CLs autocontidos |
+| Código complexo demais de entender | Peça **simplificar ou comentar no código** — não aceite explicação só no PR |
+| Quer que o dev aprenda | Aponte o **problema** e deixe ele decidir, em vez de dar a ordem pronta |
+| Autor e revisor não chegam a acordo | Decida por **fatos/dados** e pelo style guide; persistindo, **escale** — não deixe o CL parado |
+| Chegou um review e você não está focado em outra coisa | Revise **logo** (alvo: resposta em ≤ 1 dia útil) |
+| Chegou um review e você está codando concentrado | Não se interrompa; responda numa **pausa natural** |
+| Revisor não entendeu seu código | **Conserte o código** ou comente nele o porquê; explicar só no PR é último recurso |
+
+---
+
+**Fonte:** Google Engineering Practices — `google.github.io/eng-practices`
+(*How to do a code review* e *The CL author guide*).