realshahriya/mukhon-desenvolvimento-orientado-por-restricoes

Desenvolvimento Orientado por Restrições

Visão Geral

Outras skills neste pacote descrevem como é a aparência do "bom". code-review-and-quality fornece cinco eixos. test-driven-development fornece um ciclo. security-and-hardening fornece uma lista de ameaças. Tudo isso vive em prosa que o agente lê e pode ou não seguir, e nada disso sobrevive ao final da sessão.

Esta skill produz algo diferente: um registro escrito do padrão deste projeto, com números, que sobrevive à conversa e pode ser verificado mecanicamente.

A razão é importante. Quando você escrevia o código, lê-lo dizia se ele era bom. Um agente escreve mais em uma tarde do que você lerá naquela semana, então o julgamento sai da sua cabeça e vai para verificações que rodam em loop. Essas verificações precisam existir, precisam de números que você realmente escolheu, e precisam disparar perto o suficiente do trabalho para que o agente corrija sua própria saída.

O desenvolvimento orientado por especificação diz o que construir. O desenvolvimento orientado por testes prova que funciona. O desenvolvimento orientado por restrições define o que significa "bom o suficiente para enviar", antes que alguém discuta sobre isso em um pull request.

Quando Usar

Aplique esta skill quando:

• Iniciar um projeto ou uma funcionalidade significativa e nenhum padrão de qualidade estiver escrito
• O usuário pedir para "configurar restrições", "adicionar portões de qualidade", "definir nossos padrões" ou "impedir o agente de enviar lixo"
• Um agente estiver produzindo volume que ninguém está lendo linha por linha
• CI tiver verificações, mas ninguém puder dizer quais bloqueiam um merge e quais são decoração
• Números de cobertura, desempenho ou acessibilidade forem discutidos por PR em vez de decididos uma vez
• Você estiver prestes a executar /build auto ou qualquer loop autônomo, e a única coisa entre ele e a main for uma suíte de testes que o agente também escreveu

Quando NÃO usar:

• O projeto já tem um CONSTRAINTS.md e o usuário não o está alterando — leia-o e siga-o
• Scripts únicos, spikes, protótipos descartáveis
• O usuário quer uma revisão de código agora (code-review-and-quality) ou um pipeline de CI construído (ci-cd-and-automation)
• Código pré-product-market-fit com vida útil esperada de duas semanas — o floor abaixo ainda vale a pena, o resto não

Carregando Restrições

A entrevista precisa de um usuário ativo. Não execute em contextos não interativos (CI, /loop, execuções autônomas). Se as restrições estiverem faltando e você estiver em um desses, aplique o Floor abaixo, anote que o fez e sinalize o resto para um humano.

O Processo

Passo 1: Detecte antes de perguntar

Nunca pergunte o que você pode ler. Antes da primeira pergunta, colete:

O quê	Onde procurar
Linguagem e stack	package.json, pyproject.toml, go.mod, Cargo.toml
Executor de testes	dependências de dev, script test, arquivos de teste existentes
Linters existentes	eslint.config.*, biome.json, .ruff.toml
Cobertura hoje	saída coverage/, ou execute a suíte uma vez
CI	.github/workflows/, .gitlab-ci.yml
Integração com agente	.claude/, .codex/, AGENTS.md

Relate o que você encontrou em duas linhas, depois pergunte apenas o que restou.

Passo 2: Quatro perguntas, cada uma com um padrão

Siga a disciplina de uma pergunta de cada vez do interview-me, com uma mudança: cada pergunta aqui tem um padrão, então "não sei" é uma resposta completa que ainda produz uma configuração funcional.

P1: Além do floor, quais destes você quer aplicar?
    (a) Cobertura de testes em código novo
    (b) Varredura de segurança
    (c) Orçamentos de desempenho
    (d) Acessibilidade
    (e) Limites arquiteturais
PALPITE: (a) e (b) — você já tem um executor de testes e está lidando com entrada do usuário.
PADRÃO se não souber: (a) e (b).
Diga o que cada escolha custa: (c) e (d) precisam de uma URL em execução, (e) precisa de um arquivo de regras escrito.

P2: Quando uma verificação falha enquanto o agente está no meio de uma tarefa, deve bloquear ou avisar?
PALPITE: Bloquear. Você está executando agentes sem supervisão e um aviso que ninguém lê é um aviso.
PADRÃO se não souber: Bloquear no floor, avisar em todo o resto nas primeiras duas semanas.

P3: Você tem números-alvo em mente, ou devo medir onde você está hoje e manter essa linha?
PALPITE: Medir. A maioria das equipes não tem um número, e um inventado é ignorado.
PADRÃO se não souber: Medir e manter. Veja "Catracas" abaixo.

P4: Qual é a verificação mais lenta que você tolerará antes do agente devolver o trabalho?
PALPITE: Cerca de 90 segundos. Mais longo e você vai parar de executá-la.
PADRÃO se não souber: 90 segundos no final da tarefa, ilimitado no CI.

Pare em quatro. Uma coleta de doze perguntas produz uma configuração que ninguém entende e um usuário que se arrepende de ter começado.

Passo 3: Escreva CONSTRAINTS.md

Um único arquivo na raiz do repositório. Qualquer agente em qualquer plataforma pode lê-lo, e uma alteração nele aparece na revisão onde pertence.

# Restrições

Última revisão: 2026-08-08 por @mukhon-core

## Floor (sempre aplicado, sem necessidade de configuração)

- Nenhum novo comentário de supressão: `@ts-ignore`, `eslint-disable`, `# noqa`, `# type: ignore`
- Nenhum stub não implementado: `throw new Error("Not implemented")`, `catch {}` vazio
- Nenhum teste ignorado ou excluído sem uma razão na mensagem de commit
- Nenhum segredo no código-fonte
- Este arquivo não pode ser enfraquecido para fazer uma alteração passar

## Aplicado com números

| Dimensão | Regra | Verificado por | Executa em |
|----------|-------|---------------|------------|
| Tipos | Zero erros de tipo | `tsc --noEmit` | a cada edição |
| Lint | Zero erros da nossa configuração | `biome check` | a cada edição |
| Segredos | Nenhum segredo no código-fonte | `gitleaks detect --redact` | a cada edição |
| Cobertura | Linhas alteradas ≥ 80% cobertas | `vitest run --coverage` + git diff | fim da tarefa, CI |
| Segurança: código | Nenhum achado de alta gravidade | `semgrep scan --config p/default` | CI |
| Segurança: dependências | Nada em alta ou acima | `osv-scanner scan source -r .` | CI |
| Acessibilidade | Zero crítico ou grave | `axe $PREVIEW_URL --tags wcag2a,wcag2aa,wcag21aa` | deploy de preview |
| Desempenho | LCP ≤ 2500ms, CLS ≤ 0.1 | `lighthouse $PREVIEW_URL --output=json` | deploy de preview |

Cada linha nomeia o comando que produz o veredito. Uma dimensão com um número e nenhum comando nesta coluna é uma aspiração, não uma restrição.

## Medido, ainda não aplicado

| Métrica | Hoje | Direção |
|---------|------|---------|
| Cobertura do projeto | 62.4% | não deve cair |
| Tamanho do bundle (main) | 184 kB | não deve crescer |

## Exceções

| ID | Regra | Caminho | Motivo | Responsável | Expira em |
|----|-------|---------|--------|-------------|-----------|
| W1 | `no-explicit-any` | `src/legacy/**` | Reescrita rastreada em ENG-441 | @mukhon-core | 2026-11-01 |

Em seguida, adicione uma linha a AGENTS.md e CLAUDE.md: Leia CONSTRAINTS.md antes de escrever código. Não o enfraqueça para fazer uma alteração passar.

Passo 4: Instale o que cada dimensão precisa

Escolher uma dimensão significa instalar algo. Não deixe o usuário com um número e nenhum mecanismo, e não invente seu próprio verificador quando um de fato existir — essas ferramentas estão listadas porque seus formatos de regra e limites são o que todo o resto do ecossistema tem como alvo, então a configuração existente da equipe continua funcionando.

Dimensão	Ferramenta	Instalação	Executar	Portão
Tipos (TS)	tsc	já está lá	tsc --noEmit	qualquer erro
Tipos (Python)	mypy	pip install mypy	mypy .	qualquer erro
Lint	sua configuração existente	já está lá	eslint . / biome check / ruff check	qualquer erro
Cobertura (JS)	seu executor de testes	já está lá	vitest run --coverage (ou jest --coverage)	cobertura das linhas alteradas
Cobertura (Python)	pytest-cov	pip install pytest-cov	pytest --cov --cov-report=lcov	mesmo
Segurança: código	Semgrep	pipx install semgrep	semgrep scan --config p/default --config p/owasp-top-ten	qualquer achado de alta
Segurança: segredos	gitleaks	brew install gitleaks	gitleaks detect --redact --no-banner	qualquer achado
Segurança: dependências	osv-scanner	brew install osv-scanner	osv-scanner scan source -r .	alta ou acima
Desempenho: página	Lighthouse	npm i -D lighthouse	lighthouse $URL --output=json --quiet	LCP, CLS, pontuação de desempenho
Desempenho: bundle	size-limit	npm i -D size-limit	size-limit --json	orçamento de bytes por entrada
Acessibilidade	axe-core	npm i -D @axe-core/cli	axe $URL --tags wcag2a,wcag2aa,wcag21aa	zero crítico ou grave
Arquitetura	dependency-cruiser	npm i -D dependency-cruiser	depcruise --validate src	qualquer violação
Qualidade de asserção	Stryker	npm i -D @stryker-mutator/core	stryker run --mutate <arquivos alterados>	pontuação de mutação

Cinco coisas que vão te morder se você pular:

1. --redact no gitleaks não é opcional. Sem ele, o segredo encontrado vai parar no transcript do agente, que é como uma chave vazada termina em um log, um resumo ou uma mensagem de commit. Reporte a regra e a localização, nunca o valor.
2. Lighthouse e axe precisam de uma URL. Eles só funcionam contra um aplicativo em execução, então pertencem ao estágio de runtime contra um deploy de preview ou um servidor local que você inicia primeiro. Se o projeto não tiver uma URL para acessar — um CLI, uma biblioteca, um aplicativo desktop — diga e remova a dimensão em vez de inventar uma verificação que não pode ser executada.
3. Escopo das caras para o diff. stryker run --mutate em todo o repositório leva horas e é desligado; nos arquivos que uma alteração tocou leva menos de um minuto. O mesmo para Semgrep, que aceita uma lista de caminhos.
4. Cobertura não precisa de uma segunda execução de teste. Leia o lcov que sua suíte já escreve e interseccione com git diff. Executar a suíte duas vezes para obter um número é o caminho mais rápido para fazer as pessoas odiarem isso.
5. As regras de registro do Semgrep são gratuitas para executar; verifique a licença antes de redistribuí-las. opengrep é um fork drop-in com o mesmo formato de regra e saída JSON se isso for importante para seu time jurídico.

Adicione cada uma ao script do próprio projeto para que seja reproduzível sem um agente:

{
  "scripts": {
    "check:fast": "tsc --noEmit && eslint . && gitleaks detect --redact --no-banner",
    "check:task": "npm run check:fast && vitest run --coverage",
    "check:full": "npm run check:task && semgrep scan --config p/default && osv-scanner scan source -r ."
  }
}

Esse mapeamento importa mais do que as ferramentas. check:fast é o que executa após uma edição, check:task quando o agente acha que terminou, check:full no CI.

Os comandos agora vivem em dois lugares — a coluna Verificado por em CONSTRAINTS.md e esses scripts. CONSTRAINTS.md é a fonte canônica: carrega a razão junto com cada comando e aparece na revisão. Os scripts são wrappers de conveniência que devem espelhá-lo, não uma segunda fonte da verdade; se divergirem, o arquivo vence.

Passo 5: Conecte ao ciclo de vida

O maior erro é executar tudo em todos os lugares. Uma verificação que trava o agente é desligada, e um portão que as pessoas desligaram é pior do que nenhum portão, porque o padrão ainda parece existir.

Fase	Comando	O que executa	Orçamento
BUILD	/build	Tipos, lint, segredos, o floor	abaixo de 5s, apenas arquivo alterado
VERIFY	/test	Testes relacionados, cobertura em linhas alteradas	abaixo de 90s
REVIEW	/review	Tudo, mais os guardiões abaixo	minutos
SHIP	/ship	Verificações de direção, sem regressões	CI

Duas regras que mantêm isso tolerável:

1. Escopo para o diff. Verifique as linhas que esta alteração tocou, não todo o repositório. Cobertura de linhas alteradas é um número que o agente pode mover; a cobertura do projeto é algo que ele herdou.
2. O custo decide o posicionamento. Qualquer coisa acima de alguns segundos sai do loop de edição. Testes de mutação em todo o repositório levam horas; nos arquivos que uma alteração tocou, leva menos de um minuto, o que é a diferença entre uma verificação que as pessoas executam e uma que não executam.

Passo 6: Guarde o padrão

Alguém vai apontar que, se o agente escreve o código e as verificações, as verificações não provam nada. Meio certo, e vale a pena projetar em torno disso.

Agentes não criam brechas engenhosas. Eles encontram uma verificação vermelha e pegam o caminho mais barato para o verde. Fique de olho nestes cinco movimentos no diff, na hora da revisão:

1. O limite mudou. Um orçamento reduzido, uma gravidade diminuída, uma verificação removida do estágio rápido. Compare CONSTRAINTS.md com seu estado no ponto de ramificação.
2. Um teste ficou mais fácil. .skip adicionado, um arquivo de teste excluído, asserções removidas de testes que permaneceram.
3. Um verificador foi silenciado. Novo @ts-ignore ou eslint-disable. Quatro supressões merecem atenção especial porque desligam uma verificação na qual você está confiando: istanbul ignore remove código da cobertura em vez de testá-lo, Stryker disable esconde um mutante sobrevivente, nosemgrep e gitleaks:allow fazem isso para achados de segurança.
4. Trabalho inacabado. Um stub que lança exceção, um catch vazio transformando uma falha em silêncio, um TODO no lugar onde a implementação deveria estar.
5. Uma exceção apareceu. Uma nova linha na tabela de Exceções que ninguém discutiu.

Nada disso precisa de ferramentas além de git diff. Apertar o padrão deve ser silencioso; afrouxá-lo deve ser barulhento.

Ao contrário das dimensões numeradas, o floor não tem uma ferramenta de fato própria, então um agente instruído a aplicá-lo tende a escrever um verificador do zero, e dois agentes escrevem dois diferentes. Uma implementação de referência dessas cinco verificações acompanha esta skill em references/floor-guard.md (com escopo no diff, saída 0/1/2, padrões adaptáveis por ecossistema). Adapte-a em vez de reinventá-la, pela mesma razão que cada dimensão nomeia uma ferramenta de fato: para que o mecanismo seja o mesmo em todas as execuções e stacks.

Nem todas as verificações são igualmente circulares. Classifique-as por uma pergunta: o agente pode fazer esta verificação passar escrevendo código que não funciona?

• Externa — axe-core codifica WCAG, osv-scanner lê um banco de dados de vulnerabilidades, Lighthouse mede um navegador real. O agente não pode argumentar contra estas.
• Projeto — suas regras de lint, seus limites de camada. Um humano possui o arquivo.
• Suíte — seus próprios testes. Mais úteis, e as únicas genuinamente circulares. Você as quer mesmo assim, porque testam se o código faz o que deveria, mas um agente que escreve os dois pode fazer o teste passar com o código errado. As dimensões externas e de projeto existem para limitar o dano quando isso acontece.

Passo 7: Catracas

O estado final é a direção que você quer: cobertura sobe, tamanho do bundle desce, tempo de resposta desce. O estado intermediário é "não piore o que você não melhorou".

• Se o usuário escolheu "medir e manter", a linha que você mediu no passo 2 se torna o limite dessa dimensão. Um PR que cai abaixo disso falha.
• Depois de dois ciclos de "medir e manter" sem queda, ou quando o usuário disser "subir", troque para uma meta: suba a barra em 5% ou 100ms e aplique-a. O agente agora tem que não apenas não piorar as coisas, mas realmente melhorá-las.
• Reavalie a cada 50 PRs ou a cada mês, o que vier primeiro. Altere a data de "Última revisão" em CONSTRAINTS.md e mova o que está medido para aplicado, se for o caso.

O que vem a seguir?

Com as restrições gravadas e os portões no lugar, o loop autônomo produz menos lixo e mais valor. O próximo passo natural são as verificações de front-end que dependem de uma URL em execução (accessibility, performance: page). Para isso, veja deployment-and-preview-environments — skill que dá ao seu agente um ambiente efêmero onde essas verificações baseadas em URL podem executar contra código real antes de chegar ao main.

A ordem certa: restrições primeiro, CI em segundo, URLs de preview em terceiro. Pule a ordem e seu novo ambiente de preview vai executar verificações que ainda não têm limites.