From kairos-forge
Faz inventário estrutural do código existente — componentes, acoplamento, duplicação de domínio, bounded contexts e plano incremental de decomposição. Use em projetos brownfield antes de refatorações grandes, antes de extrair serviço, ao herdar codebase ou quando o usuário disser "está virando um monolito". Read-only: produz mapa em docs/arquitetura/MAPA-YYYY-MM-DD.md. Não modifica código.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kairos-forge:mapear-arquiteturaThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Você está sendo invocado para produzir um mapa honesto da arquitetura **atual** do projeto, não a ideal. O objetivo é evidência para decidir o próximo passo de evolução, não recomendação genérica.
Você está sendo invocado para produzir um mapa honesto da arquitetura atual do projeto, não a ideal. O objetivo é evidência para decidir o próximo passo de evolução, não recomendação genérica.
Read-only. Você lê arquivos, roda comandos de inspeção (find, ls, git log, ferramentas de análise estática que já existam no projeto) e produz um único artefato: o mapa. Não refatore, não crie tickets, não rode build se não for necessário para o mapa.
Toda afirmação no mapa precisa de evidência verificável (arquivo:linha, comando rodado, métrica calculada). Sem evidência, marque como "hipótese a validar".
/kairos-forge:onboardar)./kairos-forge:auditar apontar "código sem dono" ou "acoplamento alto" como gap principal.Pergunte ao usuário:
apps/api/)Se o repo for grande (> 50k linhas), exija escopo. Mapear tudo em um passo só vira mapa inútil.
Invoque laura-tech-lead. Ela decide quem entra com base no que o usuário descreveu:
| Sinal | Arquiteto |
|---|---|
| Fluxo entre serviços/módulos, eventos, filas | Diego (sistemas) |
| Banco, schema, dados, performance de query | Fernanda (dados) |
| API pública, integração externa, contratos | Thiago (integrações) |
| Decisão de padrão, trade-off de tecnologia, dívida estrutural | Rafael (Staff) |
Para mapa estrutural completo, Diego coordena e chama os outros conforme as evidências aparecem.
Para cada dimensão abaixo, gere evidência com comando real. Não pule etapas inventando o que provavelmente está lá.
find . -maxdepth 2 -type d -not -path '*/node_modules*' -not -path '*/.git*'cloc, tokei ou find ... -name '*.ts' | xargs wc -l conforme stackmain, index, server, app, rotas)Registre os 10 maiores módulos por linhas.
Para cada módulo grande, levantar:
import/require/use.index.ts, __init__.py, mod.rs).git log --since='90 days ago' --pretty=format: --name-only -- <módulo>/ | sort | uniq -c | sort -rn mostra hotspots de mudança.Dimensões para classificar acoplamento:
| Dimensão | Pergunta |
|---|---|
| Força | Quantos símbolos cruzam a fronteira? |
| Distância | Estão na mesma camada ou atravessam camadas (UI ↔ DB)? |
| Volatilidade | Mudam juntos com frequência? (git log em pares) |
Procure por:
UserDTO, User, UserModel, IUser).Se houver ferramenta de detecção de duplicação no projeto (jscpd, pmd, simian), use. Se não houver, faça amostragem manual e marque como "indício, não medição".
Agrupe módulos por contexto de negócio, não por camada técnica. Pergunte:
git log mostra commits que tocam módulos aparentemente sem relação?Saída esperada: 3 a 7 contextos. Mais que isso, refine. Menos que isso, provavelmente o projeto ainda não diferencia domínios.
Para cada contexto, registre 1-2 pontos onde a estrutura atual vai doer se a feature roadmap continuar:
Não recomende reescrita. Sempre incremental:
Cada movimento precisa de:
Em docs/arquitetura/MAPA-YYYY-MM-DD.md:
# Mapa arquitetural — <projeto> — YYYY-MM-DD
**Escopo:** <repo inteiro / apps/api / etc.>
**Coordenado por:** Diego (com Fernanda/Thiago/Rafael conforme dimensões)
**Base analisada:** `<branch / commit>`
## Resumo executivo
- 3 bullets de no máximo 2 linhas cada
- Risco principal em 1 frase
## Inventário
### Componentes de primeiro nível
| Módulo | Linhas | Arquivos | Hotspot 90d | Dono (CODEOWNERS) |
|---|---|---|---|---|
### Pontos de entrada
| Tipo | Path | Observação |
|---|---|---|
## Acoplamento
### Mapa de imports relevantes
| De | Para | Símbolos | Força | Distância | Bidirecional? |
|---|---|---|---|---|---|
### Hotspots de mudança conjunta
| Par de módulos | Commits conjuntos 90d | Hipótese |
|---|---|---|
## Duplicação de domínio
| Conceito | Implementações | Evidência | Severidade |
|---|---|---|---|
## Bounded contexts identificados
### Contexto: <nome>
**Responsabilidade:** 1 frase.
**Módulos:** lista.
**Linguagem ubíqua:** termos centrais.
**Fronteira hoje:** clara / borrada / inexistente.
## Pontos de tensão
| ID | Tensão | Onde | Por que dói no roadmap |
|---|---|---|---|
## Plano de decomposição incremental
### Movimentos baratos (próximos 7 dias)
1. **<título>** — pré-condição / critério / rollback.
### Movimentos médios (1-4 semanas)
1. **<título>** — idem.
### Movimentos grandes (> 1 mês)
1. **<título>** — idem.
## ADRs sugeridas
Liste decisões que merecem ADR formal antes de execução.
## Próximo passo
- Discutir mapa com time
- Abrir ADR para movimento grande #1
- Rodar `/kairos-forge:especificar` para movimentos médios que viram features
Resumo curto (máximo 10 linhas):
Mapa salvo em `docs/arquitetura/MAPA-YYYY-MM-DD.md`.
Escopo: <X>. Coordenado por: Diego (+ <outros>).
Achados principais:
1. <achado>
2. <achado>
3. <achado>
Movimento mais barato com maior alavancagem: <título>.
Maior risco se nada for feito: <risco em 1 frase>.
Próximo passo sugerido: <ADR / SPEC / nada por agora>.
git clean, rm, migrations. Inspeção apenas.Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
npx claudepluginhub vilelaai/kairos-forge