architecture-deepener
Skill28 starsChanged 3 months agoApache-2.0View on GitHub
Identifica melhorias estruturais e fronteiras arquiteturais. Trigger em: "deepening", "deep module", "shallow module", "refactor architecture", "improve architecture", "consolidate modules", "agent-friendly codebase", "AI-navigable", "module depth", "melhorar a arquitetura", "fronteiras de domínio", "estado compartilhado".
In this repository92 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- po-feature-specSkill
- ui-ux-designSkill
- backend-apiSkill
- frontend-integrationSkill
- qa-testingSkill
- security-reviewSkill
- deploy-dockerSkill
- context-managerSkill
- orchestratorSkill
- documenterSkill
- reviewerSkill
- motion-designSkill
- marketing-copySkill
- seo-specialistSkill
- mobile-tauriSkill
- image-generatorSkill
- repo-auditorSkill
- asset-librarianSkill
- observability-sreSkill
- data-analyticsSkill
- accessibility-specialistSkill
- migration-refactor-specialistSkill
- release-managerSkill
- ai-integration-architectSkill
- prompt-engineerSkill
- video-integration-specialistSkill
- claude-md-generatorSkill
- design-intelligenceSkill
- cost-trackerSkill
- session-summarySkill
- smart-suggestionsSkill
- detective-specSkill
- static-analysisSkill
- skill-authorSkill
- web-asset-generatorSkill
- tdd-engineerSkill
- program-routerSkill
- parallel-dispatcherSkill
- blog-publisherSkill
- blog-screenshotSkill
- canary-deploymentSkill
- zoom-outSkill
- handoff-contextSkill
- post-deploy-canary-monitorSkill
- pattern-conformitySkill
- research-prepSkill
- context-budgetSkill
- direct-response-copySkill
- ux-researchSkill
- ui-polishSkill
- doubt-driven-reviewSkill
- video-analysisSkill
- marketing-reporting-analyticsSkill
- responsive-conversionSkill
- mobile-ux-foundationsSkill
- i18n-localizationSkill
- closed-loop-revenueSkill
- app-reference-architectureSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 80
Use docs/skill-guides/architecture-and-evidence.md e examples/architecture-decisions.md para os cenários de domínio, duplicação, falha de …
- Distinctive: line 84
Use os termos do domínio e distinga os conceitos arquiteturais abaixo.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Architecture Deepener — Refactors que Importam
Identificar friccao arquitetural e propor deepening opportunities — refactors que transformam modulos shallow em deep. Objetivo: testabilidade + AI-navigability (codebase que agente consegue evoluir sem quebrar coisas).
Adaptado de mattpocock/skills/engineering/improve-codebase-architecture e integrado ao kit (skill 23 Migration & Refactor + skill 33 Detective Spec + policies/vertical-slices.md).
Fitness Functions YAML (v2.5.0+)
Inspirado em Birgitta Böckeler (Thoughtworks) + Neal Ford ("Building Evolutionary Architectures"). Ver
docs/inspiration/harness-engineering.md+policies/harness-categories.md.
Esta skill agora também produz fitness functions runnable quando o usuário pedir auditoria arquitetural com gates concretos. Formato canônico:
# .harness/fitness-functions.yml
fitness_functions:
- id: <kebab-case-id>
description: "Frase clara do que regula"
type: structural | performance | accessibility | security
runner: grep | dep-cruiser | lighthouse | custom-script
rule: <padrão ou query do runner>
fail_threshold: <int — 0 = zero tolerância>
severity: high | medium | low
applies_to: <glob opcional>Exemplo prático — leaky abstraction de DB:
- id: no-db-in-domain
description: Domain layer não importa bibliotecas de DB
type: structural
runner: dep-cruiser
rule:
forbidden:
- from: 'src/domain/'
to: '(prisma|typeorm|sequelize|knex|pg|mongodb)'
severity: highQuando produzir YAML vs apenas relatório:
| Output | Quando |
| Relatório markdown apenas | Auditoria inicial, usuário entendendo opções |
+ fitness-functions.yml | Quer gate automatizado, tem CI, prevenir regressão |
| + Aplicar refactor | Via /auto, /swarm ou refactor-safely |
Ao produzir YAML, salvar em <consumer>/.harness/fitness-functions.yml. Roadmap v2.5.1: /run-fitness command runs the file.
Governanca Global
Esta skill segue GLOBAL.md, policies/source-driven.md, policies/writing-clarity.md, policies/handoffs.md e policies/readiness-gate.md (decisão de arquitetura registrada explicitamente, não implícita, é um dos critérios que decide PASS/CONCERNS/FAIL antes do slice ir para implementação — decisão pendente reprova o gate).
Filosofia
Deletion test: imagine deletar o modulo. Se complexidade desaparece, era pass-through. Se complexidade reaparece em N callers, estava ganhando seu lugar.
The interface is the test surface.
One adapter = hypothetical seam. Two adapters = real seam.
Essa última heurística ajuda a identificar abstração especulativa, mas uma fronteira de IO ou confiança pode justificar um adaptador mesmo com uma única implementação. Não invente um segundo adaptador para legitimar uma separação útil.
Contratos, estado e recuperação
Para cada candidato, descreva a invariante, os estados/transições, o dono da escrita e a fronteira de confiança. Proponha uma representação que impeça combinações inválidas sem supor que tipos validam dados externos. Separe decisões de domínio de IO quando houver ganho de clareza e testabilidade; evite camadas pass-through.
Quando houver estado compartilhado ou repetição, verifique a estrutura que arbitra concorrência, a identidade da intenção e os efeitos após uma queda. Um lock local não coordena processos distintos. Um candidato arquitetural deve indicar o cenário que comprovaria sua vantagem, a menor etapa de transição e os contratos que permaneceriam válidos.
Use docs/skill-guides/architecture-and-evidence.md e examples/architecture-decisions.md para os cenários de domínio, duplicação, falha de hipótese e recuperação. Métricas podem localizar fricção, mas não justificam extrair módulos ou remover guardas por si sós.
Glossario (use exatamente — consistencia e o ponto)
Use os termos do domínio e distinga os conceitos arquiteturais abaixo. Uma fronteira de confiança descreve mudança de trust; um seam descreve onde substituir comportamento. Não trate os dois como sinônimos.
- Module — qualquer coisa com interface e implementacao (funcao, classe, package, slice).
- Interface — tudo que o caller precisa saber para usar o modulo: tipos, invariantes, modos de erro, ordering, config. Nao apenas a assinatura de tipo.
- Implementation — codigo dentro.
- Depth — leverage na interface: muito comportamento atras de interface pequena. Deep = alta leverage. Shallow = interface quase tao complexa quanto a implementacao.
- Seam — onde uma interface vive; lugar onde comportamento pode ser alterado sem editar in place.
- Adapter — coisa concreta satisfazendo uma interface em um seam.
- Leverage — o que callers ganham com depth.
- Locality — o que mantenedores ganham com depth: mudanca, bugs, conhecimento concentrados em um lugar.
- Cohesion — sinal de que um Module merece ser deep: suas responsabilidades fazem sentido juntas e mudam pela mesma razao. Alta coesao = candidato a deep. (Nao e termo novo — e o gatilho para aplicar deletion test.)
- Coupling leak — quando a Implementation de um Module vaza pela Interface, forcando callers a saber detalhes internos. Sintoma de shallow: a Interface nao esconde o que devia.
- Contract — a Interface de um Module distribuido (schema, classe de mensagem, media type). Vale a definicao estrita de Interface: tudo que o outro sistema precisa saber — nao apenas o formato do payload, mas modos de erro, versionamento e compatibilidade.
Quando Usar
- semanalmente ou apos sprint de desenvolvimento (prep antes de proxima iteracao)
- antes de delegar manutencao para agente em modulo complexo
- onboarding de codebase desconhecido (mapear seams existentes)
- antes de feature grande que vai estressar arquitetura atual
- review de PR que adiciona modulo novo (esta deep ou shallow?)
- pos-
/detective-specem legado (Detective ja mapeou; Deepener propoe melhorias)
Quando NAO Usar
- bug fix localizado
- spike exploratorio
- task que ja tem ADR proibindo refactor naquela area
- codebase muito novo (deixar arquitetura emergir antes de "consertar")
Entradas Esperadas
- caminho do escopo (repo inteiro, subdir, ou modulo especifico)
- glossario de dominio do projeto (
CONTEXT.mdoudocs/glossary.md) - ADRs em
docs/adr/se existirem - (opcional)
graphify-out/graph.json— god nodes priorizados - (opcional)
_detective_sdd/— Detective Spec ja mapeou - (opcional) max-candidates (default: 5-7)
Saidas Esperadas
- lista priorizada de deepening candidates em formato markdown (template
## Architecture Deepening Candidatesmais abaixo) - caminho de saida:
_architecture_review/YYYY-MM-DD-candidates.md(criar dir se nao existir, gitignored por default) - (se conversa de grilling produziu termos novos) entradas inseridas em
CONTEXT.md - (se usuario rejeitou candidato com motivo load-bearing) ADR proposto em
docs/adr/ - handoff para skill 23 (Migration & Refactor) com plano de deepening do candidato escolhido
- nenhum codigo do projeto modificado (Deepener so propoe; skill 23 executa)
Pre-requisitos
- glossario de dominio do projeto (
CONTEXT.mdoudocs/glossary.md) — sem isso, nomes ficam genericos - ADRs em
docs/adr/(se existirem) — respeitar decisoes registradas - (opcional)
graphify-out/graph.json— god nodes sao candidatos prioritarios - (opcional)
_detective_sdd/— Detective ja mapeou; reusar
Processo
Fase 1 — Explore
Ler glossario de dominio + ADRs primeiro. Depois usar Read/Grep/Glob (ou despachar Explore subagent) para caminhar pelo codebase.
Nao siga heuristicas rigidas — explore organicamente e anote onde voce sente friccao:
- Onde entender UM conceito exige pular entre N modulos pequenos?
- Onde modulos sao shallow — interface quase tao complexa quanto implementacao?
- Onde funcoes puras foram extraidas apenas para testabilidade, mas bugs reais escondem em como sao chamadas (sem locality)?
- Onde modulos acoplados vazam pelos seams?
- Quais partes nao sao testadas, ou sao dificeis de testar pela interface atual?
Aplicar o deletion test em qualquer suspeito de shallow: deletar concentraria complexidade ou apenas a moveria? "Sim, concentra" e o sinal que voce quer.
Fase 2 — Apresentar candidatos
Lista numerada de deepening opportunities. Para cada candidato:
- Files — quais files/modules envolvidos
- Problem — por que arquitetura atual causa friccao
- Solution — descricao em portugues claro do que mudaria
- Benefits — explicados em termos de locality e leverage, e como testes melhorariam
Usar vocabulario do glossario do projeto para o dominio, e o glossario desta skill para arquitetura. Se CONTEXT.md define "Order", fale "modulo de Order intake" — nao "FooBarHandler", nem "Order service" generico.
Conflitos com ADR: se candidato contradiz ADR existente, so trazer quando friccao for real o suficiente para reabrir o ADR. Marcar claramente: "contradicts ADR-0007 — but worth reopening because…". NAO listar todo refactor teorico que ADR proibe.
Em auditoria exploratória sem candidato definido, apresente as opções antes de aprofundar interfaces. Se o usuário já delimitou o candidato ou autorizou o escopo, avance com esse contexto; não peça a mesma escolha novamente.
Fase 3 — Grilling Loop (sobre o candidato escolhido)
Quando usuario escolhe um candidato, entrar em conversa de grilling (analoga a /grill-me). Caminhar pela arvore de design — restricoes, dependencias, shape do modulo deepened, o que fica atras do seam, quais testes sobrevivem.
Side effects acontecem inline conforme decisoes cristalizam:
- Nomeando modulo deepened com termo nao em
CONTEXT.md? Adicionar termo aoCONTEXT.md— mesma disciplina de skill 28 (CLAUDE.md Generator). Criar arquivo lazy se nao existir. - Refinando termo durante a conversa? Atualizar
CONTEXT.mdali mesmo. - Usuario rejeita candidato com motivo "load-bearing"? Oferecer ADR: "Quer registrar isso como ADR para que reviews futuros nao re-sugiram?". So oferecer quando o motivo seria realmente necessario para um explorador futuro evitar re-sugestao — pular motivos efemeros ("nao vale a pena agora") e auto-evidentes.
Checkpoint após o deepening implementado: execute os testes dos contratos preservados e dos consumidores afetados. Uma falha pede investigação: regressão, alteração autorizada de interface, teste acoplado ou ambiente. Não ajuste a expectativa para esconder regressão; também não trate qualquer falha como prova automática de vazamento arquitetural. Propriedades de concorrência/IO exigem integração com o mecanismo relevante.
Heuristicas de Detecao
| Sintoma | Suspeita | Acao |
| Modulo so re-exporta de outro | shallow / pass-through | deletion test |
| Interface tem 10 metodos, cada um faz so 1 thing | shallow | mover comportamento para dentro, expor menos |
| Bugs sempre em "como X e usado", nunca em X | falta locality | unificar X com chamadores |
| Multiplos modulos sabem como chamar Y na ordem certa | seam errado / shallow | esconder ordem dentro de modulo deep |
| Refactor pequeno quebra muitos testes | testes acoplados a implementacao | reescrever testes pela interface; modulo provavelmente shallow |
| God file (>1000 linhas, >20 callers) | falta de seam | identificar sub-responsabilidades, criar seams |
| Detalhe de impl (conexao, driver, ordem de chamada) aparece na assinatura | coupling leak / shallow | esconder atras do seam; expor Interface menor |
| Adicionar campo a mensagem/schema quebra consumidores que nao usam o campo | Contract rigido demais / acoplamento desnecessario | aplicar Must-Ignore; validar so o que se usa |
| Layer/tier so repassa chamadas sem encapsular decisao | shallow / pass-through distribuido | deletion test; mover complexidade real para dentro ou eliminar o tier |
Coordenar com graphify quando disponivel:
- god nodes do
graphify-out/GRAPH_REPORT.md= candidatos prioritarios - bridges entre comunidades = seams ja existentes (boas ou ruins)
- comunidades coesas = candidates a virar deep modules (interface unica, implementacao concentrada)
Lentes Adicionais — Coesao, Integracao e Camadas
Inspirado em Silveira et al., Introducao a Arquitetura e Design de Software (Casa do Codigo), cap. 4, 6.1, 6.5, 7. Principios atemporais cross-linguagem — a parte JVM-especifica do livro (GC, classloaders, JIT) e ignorada de proposito; nao e o dominio desta skill.
Tres reformulacoes do mesmo nucleo (depth, deletion test, leverage, locality) aplicadas a contextos que a Fase 1 ja varre, mas que ganham vocabulario aqui. Nao sao novos passos do processo — sao lentes para nomear friccao durante a exploracao.
Coesao/acoplamento como heuristica de profundidade
Coesao e acoplamento nao sao metas em si nesta skill — sao sinais que apontam para candidatos:
- Modulo coeso (responsabilidades que mudam pela mesma razao — SRP, "uma razao para mudar") e candidato natural a deep: ja concentra uma decisao, falta so esconder a Implementation atras de Interface menor. Rode o deletion test para confirmar.
- Acoplamento que vaza pelo seam (callers sabem como chamar Y na ordem certa, ou um detalhe de persistencia aparece na assinatura) e coupling leak = shallow. A acao e a de sempre: mover comportamento para dentro, expor menos.
- SRP mapeia direto em locality: se voce consegue pensar em dois motivos para mudar um Module, ele tem duas responsabilidades e a mudanca/bug nao esta concentrada em um lugar.
Cuidado simetrico: baixo acoplamento != zero acoplamento. Sempre havera uma ligacao entre dois Modules que cooperam; a meta e que ela seja a menor e mais simples possivel (a Interface), nao que desapareca. Extrair um Module so para "desacoplar" sem deletion test e mover complexidade, nao remover.
Seam distribuido — REST vs async vs RPC como escolha de Interface
A fronteira entre dois sistemas e um seam como qualquer outro; o estilo de integracao e a escolha de que tipo de seam:
- RPC/SOAP — acopla o caller a operacoes e tipos especificos (WSDL gera stubs; mudanca no contrato => regerar). Seam rigido: tende a shallow quando cada metodo remoto faz so 1 coisa e o caller orquestra a ordem.
- Async/mensageria (broker) — o seam e a classe + formato da mensagem. Quem envia nao conhece quem recebe — desacoplamento alto, mas o formato da mensagem e o Contract: adicionar um campo quebra consumidores rigidos. Deep aqui = consumidor Must-Ignore (ignora o que nao conhece), que mantem a Interface estavel sob evolucao.
- REST orientado a recurso — poucas operacoes (verbos HTTP) sobre muitos recursos; capilaridade no lugar de N operacoes ad-hoc. Interface uniforme = menos superficie para o caller aprender.
Em todos os casos, o Contract e a Interface no sentido estrito da 38: nao so o shape do payload, mas modos de erro, ordering e compatibilidade. Validar o schema inteiro quando voce usa so parte dele e auto-imposicao de acoplamento — o equivalente distribuido de um caller que importa detalhes internos.
HATEOAS como Interface profunda. Hipermidia (links com rel, media types, content negotiation) e exemplo limpo de deep interface: o caller acopla ao significado do link (rel="pagamentos"), nao a URI. O servidor pode trocar a URI, a maquina, ate o fornecedor por tras — a Implementation muda, a Interface (o significado) nao. Versionamento e re-roteamento ficam escondidos atras do seam.
Camadas/tiers sob a mesma lente
Uma camada se avalia pela leverage que oferece, igual a qualquer Module:
- Layer/tier que so repassa ("apenas uma ponte" entre cliente e dados, repassando chamadas sem encapsular decisao) e shallow — passa no deletion test como pass-through. Suspeito classico: um tier intermediario cuja unica funcao e relay gera round-trips extras sem esconder complexidade.
- Layer que encapsula complexidade real (regra de negocio, orquestracao de workflow, traducao de protocolo que de fato esconde detalhe) e deep — concentra decisao e da locality. Mover logica de negocio de um relay burro para um business tier coeso e uma deepening opportunity valida.
Distinguir layer (separacao logica — reduz acoplamento no codigo) de tier (separacao fisica — roda em maquina separada). Adicionar layer/tier so porque "fica organizado", sem encapsular complexidade, e o mesmo anti-padrao de extrair Module sem deletion test.
Output
# Architecture Deepening Candidates — <YYYY-MM-DD>
**Scope:** src/...
**Source:** <CONTEXT.md / ADRs / graphify / Detective Spec>
## Candidates (priorizados)
### 1. <nome usando vocabulario do dominio>
**Files:** src/foo.ts, src/bar.ts, src/baz/index.ts
**Problem:** entender Order intake exige pular entre FooBarHandler, OrderService, OrderValidator e OrderRepository. Validacao acontece em 3 lugares com regras ligeiramente diferentes (RN-005 vs RN-012).
**Solution:** consolidar Order intake atras de modulo unico `OrderIntake` com interface `intake(rawOrder): Order | OrderError`. Esconder validacao + persistencia + emit-event atras desse seam.
**Invariants and ownership:** declarar quais regras precisam ser iguais, quais variam por contrato e quem arbitra a escrita do pedido.
**Recovery:** definir como persistencia e emit-event se recuperam de queda/repeticao, sem supor atomicidade entre banco e recurso externo.
**Verification and first step:** teste de caracterizacao do contrato, cenario de falha relevante e menor etapa de migracao compativel.
**Benefits:**
- **Leverage:** callers param de saber sobre os 4 modulos
- **Locality:** regras comuns ficam em um lugar; diferencas legitimas entre RN-005 e RN-012 continuam explicitas
- **Testabilidade:** 1 interface a testar, vs 4 hoje. Testes ficam integration-style por default.
### 2. ...
## Recomendacao
Pegue 1 candidato por vez. Comecar pelo numero 1 (highest leverage).
## Para discutir
Qual candidato voce quer explorar? (responda com numero)Anti-Padroes
"Refactor por refactor"
Mexer porque "ficou feio" sem deletion test = mover complexidade, nao remover. Sempre rodar deletion test primeiro.
"Usar vocabulario novo"
Inventar "OrderProcessor" quando glossario diz "Order intake" = drift terminologico. Sempre usar termos do CONTEXT.md.
"Re-litigar ADR"
ADR-0007 proibe X. Refactor sugere X. Solucao: re-abrir ADR primeiro, justificar mudanca, depois refactorar. Nao silenciosamente contradizer.
"Propor 20 candidatos"
Usuario nao consegue priorizar lista de 20. Maximo 5-7 candidatos, ordenados por impacto.
"Propor solucao antes de validar problema"
"Aqui esta a interface nova" antes de "voce concorda que e shallow?" = perde feedback do usuario sobre a fricao real.
Evidencia de Conclusao
- lista priorizada de candidatos com deletion test aplicado
- vocabulario do dominio respeitado em toda proposta
- ADRs respeitados (ou conflito explicitamente marcado)
- nenhum codigo modificado nesta fase (Deepener so propoe; skill 23 implementa)
Handoff
Apos usuario escolher candidato e fase de grilling concluir:
- Skill 23 (Migration & Refactor): recebe plano de deepening + executa o refactor incremental com feature flags
- Skill 37 (TDD Engineer): escreve testes contra a NOVA interface antes da migracao (red-green-refactor)
- Skill 28 (CLAUDE.md Generator): atualiza
CLAUDE.mdse vocabulario novo emergiu - Documenter (skill 10): registra ADR se conversa gerou decisao "load-bearing" — se o candidato escolhido ganha mais clareza com um diagrama (arquitetura, dependency graph, sequence) do que com prosa, ver
## Diagramas em Docs e ADRsna skill 10
Integracao com Pipeline
- Detective Spec (33): roda ANTES desta skill em legado, mapeia o que existe
- Repo Auditor (18): roda antes para ter
current.mdatualizado - Migration & Refactor (23): sempre roda DEPOIS desta skill — Deepener propoe, Migration executa
- TDD Engineer (37): acompanha refactor, garantindo testes contra interface nova
- CLAUDE.md Generator (28): atualiza vocabulario quando termos novos emergem
- Reviewer (11): valida que refactor manteve comportamento (testes verdes)
Material Adicional
docs/skill-guides/architecture-language.md(a criar conforme demanda) — glossario completo equivalente a LANGUAGE.mddocs/skill-guides/architecture-deepening.md— exemplos de antes/depois, padroes comunsdocs/skill-guides/architecture-interface-design.md— design de interface boa
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

