ousterhout-build-deep

SKILL.md

---
name: ousterhout-build-deep
description: Use ao escrever ou modificar código, antes de considerar a tarefa concluída, sempre que a alteração adicionar um nome exportado ou importável, criar um módulo, classe, componente, helper, hook, serviço ou wrapper, ou centralizar código repetido. Lista de verificação para o autor ao construir módulos profundos: nomear a decisão que o limite esconde, passar nos testes de profundidade e invariância, corrigir problemas em vez de realocá-los, nunca dividir apenas pelo tamanho e terminar com uma nota de design curta. Companheiro compacto do ousterhout-quality-program, que permanece como a lente completa de revisão.
---

# Build it deep (Ousterhout, author-time)

Você está escrevendo código, não revisando-o. Execute isso na sua própria alteração antes de considerar a tarefa concluída.

## 1. Gate

A alteração adiciona um nome exportado/importável, cria um módulo, classe, componente, helper, hook, serviço ou wrapper, ou centraliza código repetido? Se não, pule esta habilidade. Renomeações, codemods, edições de configuração/dados e correções de uma linha estão isentas.

## 2. Antes de escrever a fronteira

- Encontre como este repositório já resolve um problema dessa natureza e siga isso, a menos que você possa justificar o motivo para não seguir. Leia a documentação e os tipos atuais da dependência: uma API lembrada de memória é uma afirmação, não uma fonte.
- Escreva primeiro o comentário da interface: o que ela promete, o que ela esconde. Se você não conseguir nomear a decisão oculta (um formato, uma política, uma regra, uma escolha de esquema), a fronteira não deve existir. Incorpore-a.
- Nomeie-a na linguagem do domínio. Se o único nome honesto for `utils`, `helpers` ou `manager`, o corte está no lugar errado.

## 3. Dois testes

- **Profundidade.** A interface deve esconder substancialmente mais do que expõe. Um wrapper que apenas encaminha seus argumentos é um custo sem benefício; delete-o.
- **Invariante.** Extraia código compartilhado apenas quando ele protege uma regra compartilhada. A evidência é a co-mudança: as cópias foram corrigidas ou alteradas juntas na história. Semelhanças que mudam independentemente permanecem duplicadas.

## 4. Uma correção deve remover o problema, não relocá-lo

- Seis casts movidos para um helper genérico de cast ainda são seis casts. Escreva o mapper tipado que os casts estavam mascarando.
- Não adicione um parâmetro ou flag que empurre uma decisão para os chamadores, a menos que os chamadores realmente saibam algo que você não sabe. Absorva o caso difícil internamente.
- Prefira semântica onde o caso de erro não possa ocorrer a fazer cada chamador lidar com ele.
- Mover complexidade essencial do domínio para outro arquivo não é simplificação.

## 5. Sob pressão de "limpar isso" ou "este arquivo está muito grande"

Nunca divida apenas pelo tamanho. Um módulo de 400 linhas escondendo uma decisão vence quatro módulos de 100 linhas vazando as mesmas junções. Pergunte qual decisão cada divisão esconde; se nenhuma, não divida.

## 6. Segurança

Código existente: fixe o comportamento atual com um teste antes de aprofundá-lo. Código novo: escreva o teste que define o comportamento pretendido.

## 7. Relatório

Se o gate foi acionado, termine sua mensagem final com uma nota de design de 2-4 linhas: cada fronteira que você adicionou e a decisão que ela esconde; duplicação que você deixou de propósito e por quê; qualquer coisa superficial que você aceitou e por quê.

Para uma chamada contestada ou uma revisão completa, carregue `ousterhout-quality-program`.

Tags