codebase-design (mattpocock/skills)
Fornece um vocabulário comum para projetar módulos profundos com interfaces pequenas e limites claros.
codebase-design: dá às revisões de arquitetura o vocabulário de profundidade e uma estrutura mais clara (controle 3.2, skill 3.9, prompt de uma frase 4.5) com 1.1x os tokens, mas não encontrou mais problemas plantados do que o prompt de uma frase
Codex CLI · gpt-6-astra
23.6 / 30
Ganho sobre sem skill: +0.71 · Situacional · 18 execuções
Situacional: o ganho +0.71 está abaixo de +1.0. Para ser recomendado, é preciso total de 22/30, qualidade da saída de 3.5 e ganho de +1.0.
SOTA
AprovadoTestado com Codex.
Cobre Codex, Claude Code
Codex CLI 0.166 (nível SOTA): 18 execuções avaliadas. Uma aprovação aqui também vale para o Claude Code pela nossa regra de níveis; ela não diz nada sobre o segundo nível.
Notas
Cada dimensão vai de 0 a 5, e as seis somam o total de 30. 5 é melhor em todas as dimensões. Custo 5 significa barato e rápido. Instalação 5 significa fácil.
- Confiabilidade do acionamento
- 5.0
- Ganho sobre sem skill
- 2.7
- Qualidade da saída
- 3.9
- Custo de tokens e tempo
- 4.0
- Instalação e portabilidade
- 4.0
- Segurança
- 4.0
Revisão de segurança
SeguroVarredura estática: 0 CRÍTICO / 0 ALTO / 0 MÉDIO. Revisão manual: seguro para executar em sandbox sem rede (nenhum achado). Uma varredura limpa não prova que a skill é segura.
Instalar
npx skills@latest add mattpocock/skills --skill codebase-design
Commit fixado: 4ae2317ddb22b046e26455e4f9c9b3aaaf62212d
Testado: 2026-11-02
O que testamos
- Varredura de arquitetura do repositório inteiro — Revise este backend de loja pequena em busca de melhorias de arquitetura: onde a reestruturação tornaria o código mais fácil de mudar e de testar? Escreva seus achados como um relatório HTML autocontido chamado report.html nesta pasta (não abra um navegador nem inicie um se…
- Somente pagamentos e estoque — Olhe apenas as partes de pagamento e estoque deste backend e me diga quais reestruturações valeriam a pena. Escreva seus achados como um relatório HTML autocontido chamado report.html nesta pasta (não abra um navegador nem inicie um servidor) e não altere nenhum código…
- Por que place_order é difícil de testar? — Parece penoso escrever um teste adequado para place_order neste backend. Por quê, e qual reestruturação resolveria isso? Não altere nenhum arquivo; responda na sua mensagem final.
Prós
- Eleva a nota média de 3.21 para 3.92 em relação ao grupo sem skill (+0.71).
- A skill foi acionada sem ser nomeada: o arquivo da skill foi lido em 6/6 execuções de tratamento.
Contras
- Um prompt de uma frase marcou 4.54, contra 3.92 com a skill (-0.63).
- n=2 por tarefa por braço; diferenças abaixo de cerca de 1 ponto são ruído.
Avaliação
Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC de teste Windows dedicado, com um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (tratamento), ausente (grupo de controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo do prompt de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo). Um backend de loja pequena com seis pontos de atrito plantados (validadores e wrappers de dinheiro rasos, um serviço de estoque que só repassa chamadas, um único adaptador de pagamento, lógica duplicada e outros). Tarefas: escrever um relatório HTML de melhorias de arquitetura, um relatório limitado a pagamento e estoque, e 'por que place_order é difícil de testar e como você corrigiria isso' (resposta no chat). Os prompts não citam nenhum termo de design. O prompt de uma frase enuncia a ideia de profundidade e o que deve ser sinalizado.
Comparação entre os braços
| Braço | Nota média (0-5) | Tokens por execução |
|---|---|---|
| Sem a skill | 3.21 | 119k |
| Prompt de uma frase | 4.54 | 114k |
| Com a skill | 3.92 | 133k |
Medido com Codex CLI em 18 execuções, com pontuação por verificações baseadas em regras e sem juiz LLM. Total 23.6 / 30, veredito Situacional.
Veredicto: Situacional (23.6 / 30). Fonte: mattpocock/skills, skills/engineering/codebase-design, fixado no commit 4ae2317. Instalação: npx skills@latest add mattpocock/skills --skill codebase-design. Licença: MIT (LICENSE do repositório).
O que é
A skill codebase-design (mattpocock/skills): uma forma de analisar a arquitetura pela profundidade dos módulos: módulos profundos com uma interface pequena que esconde muito comportamento; sinaliza módulos rasos de repasse, pontos de junção com adaptador único que são apenas hipotéticos, lógica duplicada e comportamento testado apenas por helpers; indica onde um ponto de junção deve ficar para que o comportamento seja testado pela interface.
Como testamos
Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC de teste Windows dedicado, com um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (tratamento), ausente (controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo).
Um backend pequeno de loja com seis pontos de atrito plantados (validadores e wrappers de dinheiro rasos, um serviço de inventário de repasse, um único adaptador de pagamento, lógica duplicada e outros). Tarefas: escrever um relatório HTML de melhorias de arquitetura, um relatório limitado a pagamento e inventário, e "por que place_order é difícil de testar e como você corrigiria isso" (resposta no chat). Os prompts não citam nenhum termo de design. A frase única apresenta a ideia de profundidade e os itens a sinalizar.
- Varredura de arquitetura do repositório inteiro — Analise este backend pequeno de loja em busca de melhorias de arquitetura: onde a reestruturação tornaria o código mais fácil de alterar e de testar? Escreva suas descobertas como um relatório HTML autocontido chamado report.html nesta pasta (não abra um navegador nem inicie um se…
- Somente pagamentos e inventário — Analise apenas as partes de pagamento e inventário deste backend e me diga quais reestruturações valeriam a pena. Escreva suas descobertas como um relatório HTML autocontido chamado report.html nesta pasta (não abra um navegador nem inicie um servidor) e não altere nenhum có…
- Por que place_order é difícil de testar? — Parece penoso escrever um teste adequado para place_order neste backend. Por quê, e que reestruturação resolveria isso? Não altere nenhum arquivo; responda na sua mensagem final.
A pontuação é programática (testes ocultos / identificação de problemas plantados / verificações de restrições / renderização + OCR quando aplicável), de 0 a 5 por execução. Nenhum juiz LLM decidiu qualquer pontuação.
Resultados
A frase única dada ao terceiro grupo: "Julgue os módulos pela profundidade: um módulo profundo tem uma interface pequena que esconde muito comportamento; sinalize módulos rasos de repasse, pontos de junção hipotéticos com adaptador único, lógica duplicada e comportamento testado apenas por helpers, e diga onde um ponto de junção deve ficar para que o comportamento seja testado pela interface."
| Tarefa | Pontuação do controle | Uma frase | Com a skill | Tokens do controle | Tokens de uma frase | Tokens com a skill | Skill lida |
|---|---|---|---|---|---|---|---|
| t1-scan | 2.54 | 3.63 | 3.83 | 135k | 135k | 177k | 2/2 |
| t2-focus | 2.5 | 5.0 | 3.75 | 153k | 139k | 148k | 2/2 |
| t3-testing | 4.58 | 5.0 | 4.17 | 65k | 65k | 72k | 2/2 |
Pontuação média: 3.21 sem a skill vs. 3.92 com a skill (delta +0.71). Tokens por execução: 119k vs. 133k (1.12x); tempo 154s vs. 158s. Grupo de uma frase: 4.54 (ganho da skill sobre a frase única: -0.63; ganho da própria frase única sobre sem skill: +1.34); 114k tokens por execução no grupo de uma frase, então a skill custa 1.17x a frase única.
O que aconteceu
- Controle 3.21, skill 3.92, frase única 4.54 (n=6 cada). Sem orientação, os relatórios HTML quase não usaram o vocabulário de arquitetura (0-2 usos de profundo/raso/junção/interface, quando a verificação exige 6) em 4 de 4 execuções de relatório. Os relatórios com a skill usaram esse vocabulário em todas as 4 execuções, assim como a frase única.
- Varredura do backend inteiro: skill 4.24 e 3.41, frase única 3.41 e 3.86, controle 2.88 e 2.2. Os dois grupos guiados encontraram 3-4 dos 6 pontos plantados; os wrappers de validadores rasos e o único adaptador de pagamento passaram despercebidos em várias execuções de todos os grupos.
- Tarefa focada em pagamento e inventário: skill 3.75 nas duas execuções, controle 2.5 nas duas, frase única 5.0 nas duas. Todas as execuções com a skill e do controle encontraram apenas um dos dois pontos (o adaptador único de pagamento hipotético passou despercebido); a frase única encontrou os dois.
- Por que place_order é difícil de testar: todos os grupos ficaram próximos (controle 4.17 e 5.0, skill 4.17 e 4.17, frase única 5.0 e 5.0); as execuções com a skill deixaram passar uma causa (testes apenas por helper) em uma execução e camadas de repasse em outra.
- Tokens: skill 133k, frase única 114k, controle 119k por execução (1.12x o controle). A skill foi lida em 6/6 execuções com a skill.
Pontuação por dimensão
| Dimensão | Pontuação | Por quê |
|---|---|---|
| 1_output_quality | 3.92 | Pontuação média de 3.92/5 com a skill (verificações programáticas; consulte a tabela por tarefa). |
| 2_lift_vs_no_skill | 2.71 | +0.71 ponto vs. 3.21 sem a skill (n=2 por tarefa; abaixo de ~1 ponto é ruído). |
| 3_trigger | 5.0 | Arquivo da skill lido em 6/6 execuções com a skill. |
| 4_instructions_portability | 4 | SKILL.md mais alguns arquivos de referência. |
| 5_efficiency | 4 | 1.12x tokens (133k vs. 119k por execução) e 1.03x tempo (158s vs. 154s). |
| 6_safety_hygiene | 4 | Somente texto; consulte security.md. |
Limites deste teste
- Verificações de recall por regras no texto do relatório (palavras-chave perto de nomes de arquivos) e uma contagem de vocabulário; não foi julgado se as reestruturações propostas são sólidas, e os relatórios não foram abertos no navegador.
- A verificação de vocabulário premia os próprios termos da skill, que a frase única também nomeia, e favorece os grupos guiados.
- A verificação de "antes/depois" aparece para 2 execuções que falharam apenas na tarefa de varredura; não é um diferencial.
- n=2 por célula; um único codebase pequeno.
- n = 2 por grupo por tarefa: diferenças abaixo de cerca de 1 ponto são ruído.
- A pontuação por regras mede o que as verificações conseguem ver; não julga bom gosto nem se o resultado é o melhor possível.
Segurança
Consulte security.md. Scan: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Veredicto: segura para execução (sandbox sem rede). Um scan limpo não prova que uma skill é segura.
Conclusão
A skill dá claramente à análise o enquadramento de profundidade de módulos que um prompt sem skill não tem, com um pequeno ganho de pontuação sobre o controle, mas a mesma ideia em uma frase encontra mais problemas plantados gastando menos tokens, então o ganho é principalmente estilístico.
Transcrição
Log de execuções: codebase-design (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.) Colunas: tarefa, grupo-execução, nota (0-5), tokens, segundos, verificações aprovadas, arquivos da skill abertos pelo agente. t1-scan control-1: nota 2.88, tokens 135577, s 182.2, verificações 4/6, nada aberto t1-scan control-2: nota 2.2, tokens 136096, s 168.8, verificações 4/6, nada aberto t1-scan oneliner-1: nota 3.86, tokens 135437, s 152.3, verificações 5/6, nada aberto t1-scan oneliner-2: nota 3.41, tokens 135611, s 172.2, verificações 4/6, nada aberto t1-scan treatment-1: nota 3.41, tokens 176681, s 216.0, verificações 4/6, abriu codebase-design t1-scan treatment-2: nota 4.24, tokens 178425, s 181.7, verificações 6/6, abriu codebase-design t2-focus control-1: nota 2.5, tokens 164638, s 128.2, verificações 2/4, nada aberto t2-focus control-2: nota 2.5, tokens 143158, s 298.9, verificações 2/4, nada aberto t2-focus oneliner-1: nota 5.0, tokens 112021, s 375.7, verificações 4/4, nada aberto
18 execuções, 3 artefatos
Resultado de exemplo
SOTA · With the skill: report.html (t1-scan, run 1, Codex)
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Small shop backend — architecture review</title> <style> :root{color-scheme:light;--ink:#183047;--muted:#506276;--accent:#116b66;--line:#d8e2e8}*{box-sizing:border-box}body{margin:0;background:#f3f6f8;color:var(--ink);font:16px/1.65 system-ui,sans-serif}main{max-width:1060px;margin:auto;padding:48px 28px 70px}header{border-top:6px solid var(--accent);padding:24px 0}h1{font-size:2.5rem;line-height:1.15;letter-spacing:-.04em}h2{font-size:1.55rem;margin-top:0}h3{font-size:1.1rem;margin-bottom:6px}p{margin:10px 0 18px}.eyebrow,.meta{color:var(--muted)}.eyebrow{text-transform:uppercase;letter-spacing:.13em;font-size:.8rem;font-weight:700}section{background:white;border:1px solid var(--line);border-radius:12px;padding:26px;margin:22px 0}code,pre{font-family:Consolas,monospace;font-size:.9em}code{overflow-wrap:anywhere}pre{background:#edf4f5;padding:18px;white-space:pre-wrap;border-left:4px solid var(--accent)}table{width:100%;border-collapse:collapse;font-size:.93rem}th,td{text-align:left;vertical-align:top;padding:12px;border-bottom:1px solid var(--line)}th{background:#edf4f5}a{color:var(--accent)}.tag{display:inline-block;background:#e3f2ef;color:#155b53;border-radius:20px;padding:3px 10px;font-size:.8rem;font-weight:700}.note{border-left:4px solid #d1a03b;padding-left:16px}.flow{display:flex;gap:12px;flex-wrap:wrap;margin:18px 0}.flow div{flex:1;min-width:180px;background:#edf4f5;padding:16px;border-radius:8px}li{margin:8px 0}@media(max-width:650px){main{padding:24px 14px}section{padding:18px}h1{font-size:2rem}table{font-size:.83rem}th,td{padding:7px}}@media print{body{background:white}main{padding:0}section{break-inside:avoid}a{color:inherit}} </style> </head> <body><main> <header><div class="eyebrow">Architecture review · 2 November 2026</div> <h1>Make pricing and ordering the test surface.</h1> <p>The highest-value restructuring is to concentrate pricing policy in one pure module and let an order module own validation, stock decisions, and payment sequencing behind a small interface. Remove pass-through layers as this happens. This backend is small enough that a framework, generic repository hierarchy, or distributed decomposition would add more work than leverage.</p> <p class="meta">Scope: all ten Python files in <code>shop/</code>, <code>tests/test_helpers.py</code>, and the README. This report proposes changes; no application or test files were edited. Source references use the line numbers of the reviewed snapshot.</p> <nav aria-label="Report contents"><a href="#pricing">Pricing</a> · <a href="#orders">Order module</a> · <a href="#stock">Stock consistency</a> · <a href="#validation">Validation</a> · <a href="#plan">Migration & tests</a></nav> </header> <section><h2>Current structure and where knowledge leaks</h2> <pre aria-label="Current dependency diagram">cart ──→ money pricing (discount implementation) └── own discount rules ↑ imported by orders, never called orders ──→ validators + money + own discount rules ├─→ inventory_service ──→ inventory_repo ──→ g [... excerpt: first 3200 of 17083 characters]