agentleFS
felvieirafelvieira/claude-skills-fv/skills/38-architecture-deepener/SKILL.md

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".

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
  1. Very specific:

    Use docs/skill-guides/architecture-and-evidence.md e examples/architecture-decisions.md para os cenários de domínio, duplicação, falha de …

    line 80
  2. Distinctive:

    Use os termos do domínio e distinga os conceitos arquiteturais abaixo.

    line 84

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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: high

Quando produzir YAML vs apenas relatório:

OutputQuando
Relatório markdown apenasAuditoria inicial, usuário entendendo opções
+ fitness-functions.ymlQuer gate automatizado, tem CI, prevenir regressão
+ Aplicar refactorVia /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-spec em 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.md ou docs/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 Candidates mais 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.md ou docs/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 ao CONTEXT.md — mesma disciplina de skill 28 (CLAUDE.md Generator). Criar arquivo lazy se nao existir.
  • Refinando termo durante a conversa? Atualizar CONTEXT.md ali 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

SintomaSuspeitaAcao
Modulo so re-exporta de outroshallow / pass-throughdeletion test
Interface tem 10 metodos, cada um faz so 1 thingshallowmover comportamento para dentro, expor menos
Bugs sempre em "como X e usado", nunca em Xfalta localityunificar X com chamadores
Multiplos modulos sabem como chamar Y na ordem certaseam errado / shallowesconder ordem dentro de modulo deep
Refactor pequeno quebra muitos testestestes acoplados a implementacaoreescrever testes pela interface; modulo provavelmente shallow
God file (>1000 linhas, >20 callers)falta de seamidentificar sub-responsabilidades, criar seams
Detalhe de impl (conexao, driver, ordem de chamada) aparece na assinaturacoupling leak / shallowesconder atras do seam; expor Interface menor
Adicionar campo a mensagem/schema quebra consumidores que nao usam o campoContract rigido demais / acoplamento desnecessarioaplicar Must-Ignore; validar so o que se usa
Layer/tier so repassa chamadas sem encapsular decisaoshallow / pass-through distribuidodeletion 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:

  1. Skill 23 (Migration & Refactor): recebe plano de deepening + executa o refactor incremental com feature flags
  2. Skill 37 (TDD Engineer): escreve testes contra a NOVA interface antes da migracao (red-green-refactor)
  3. Skill 28 (CLAUDE.md Generator): atualiza CLAUDE.md se vocabulario novo emergiu
  4. 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 ADRs na 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.md atualizado
  • 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.md
  • docs/skill-guides/architecture-deepening.md — exemplos de antes/depois, padroes comuns
  • docs/skill-guides/architecture-interface-design.md — design de interface boa

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.