vue-componentes/.agent/skills/mapear-codigo-fonte.global/SKILL.md

name	scope	description
mapear-codigo-fonte	global	Guia operacional para mapear, navegar e compreender a estrutura de um monorepo TypeScript.

Skill: Mapear Código-Fonte de Monorepo TypeScript

Use esta skill ao iniciar trabalho em um monorepo desconhecido, ao onboardar em novo projeto, ou quando precisar localizar rapidamente onde uma funcionalidade vive no código.

---

PASSO 1 — Identificar a Raiz e o Gerenciador de Pacotes

Localize os arquivos que definem a estratégia de monorepo:

# Identificar o gerenciador e workspace config
ls -la package.json pnpm-workspace.yaml lerna.json turbo.json nx.json tsconfig.base.json 2>/dev/null

Elementos a extrair:

• Gerenciador: pnpm (workspaces em pnpm-workspace.yaml), npm/yarn (workspaces em package.json), ou nx/turbo
• Pacotes compartilhados: diretórios listados em packages: ou workspaces:
• Apps/serviços: diretórios de aplicações deployáveis
• TSConfig base: herança de configuração TypeScript entre pacotes

---

PASSO 2 — Mapear a Árvore de Pacotes

# Listar todos os pacotes do workspace com nomes e caminhos
# pnpm
pnpm ls --depth -1 -r --json 2>/dev/null | jq '.[].name'

# Alternativa genérica: encontrar todos os package.json
fd package.json --max-depth 3 --type f --exec sh -c 'echo "$(dirname {}): $(jq -r .name {})"'

Organizar os pacotes em categorias:

Categoria	Padrão de nome	Exemplo
Libs compartilhadas	@org/common, *-comuns, *-shared	Tipos, utils, schemas
Backend	*-back, *-api, *-server	Serviços Node/Express/Fastify
Frontend	*-front, *-web, *-app	Apps Vue/React/Angular
Ferramentas	*-cli, *-scripts, *-tools	Scripts de build, migrations
Configs	*-config, *-eslint-config	Configs compartilhadas

---

PASSO 3 — Mapear Dependências Internas

Identificar o grafo de dependências entre pacotes internos:

# Para cada package.json, listar deps internas (que apontam para workspace:)
rg '"workspace:' --include='package.json' -l | while read f; do
  echo "=== $(jq -r .name "$f") ==="
  jq -r '.dependencies // {} | to_entries[] | select(.value | startswith("workspace:")) | .key' "$f"
  jq -r '.devDependencies // {} | to_entries[] | select(.value | startswith("workspace:")) | .key' "$f"
done

Anotar:

• Quais pacotes são folha (não dependem de outros internos)
• Quais são raiz (ninguém depende deles — geralmente apps)
• Quais são núcleo (muitos dependem deles — geralmente libs compartilhadas)

---

PASSO 4 — Mapear Arquitetura de Cada Pacote

Para cada pacote relevante, identificar a estrutura interna:

# Visão geral rápida (2 níveis de profundidade)
eza --tree --level=2 --icons --group-directories-first <caminho-do-pacote>/src/
# ou
tree -L 2 -I node_modules <caminho-do-pacote>/src/

Padrões comuns a procurar:

Diretório	Responsabilidade típica
src/routes/ ou src/api/	Endpoints/rotas HTTP
src/services/	Lógica de negócio
src/models/ ou src/entities/	Modelos de dados
src/utils/ ou src/helpers/	Funções utilitárias
src/types/ ou src/typings/	Definições de tipos TS
src/schemas/	Schemas de validação (Zod, Joi)
src/migrations/	Migrações de banco
src/components/	Componentes de UI (frontend)
src/composables/ ou src/hooks/	Lógica reutilizável (Vue/React)
src/stores/	Gerenciamento de estado

---

PASSO 5 — Identificar Pontos de Entrada e Exportações

# Encontrar exports públicos de cada pacote
rg "export " --include='index.ts' --include='index.tsx' -l

# Encontrar entry points no package.json
fd package.json --max-depth 3 --type f --exec sh -c 'echo "$(jq -r .name {}):" && jq "{main, module, types, exports}" {}'

---

PASSO 6 — Documentar o Mapa

Produzir um resumo estruturado com:

# Mapa do Monorepo: <nome>

## Gerenciador: pnpm | npm | yarn
## Build System: tsc | turbo | nx

## Pacotes

### Libs Compartilhadas
- `@org/types` → tipos compartilhados (depende de: nenhum)
- `@org/utils` → funções utilitárias (depende de: @org/types)

### Aplicações
- `@org/api` → backend Express (depende de: @org/types, @org/utils)
- `@org/web` → frontend Vue (depende de: @org/types)

## Fluxo de dados
Descrever como os dados fluem entre pacotes.

## Scripts importantes
- `pnpm build` → Build de todos os pacotes
- `pnpm dev` → Inicia dev server
- `pnpm test` → Roda testes

---

Checklist Final

• O gerenciador de pacotes e workspace strategy estão identificados?
• Todos os pacotes foram categorizados (lib/app/tool)?
• O grafo de dependências internas foi mapeado?
• Os pontos de entrada de cada pacote estão claros?
• A arquitetura interna dos pacotes principais foi documentada?
• Scripts de build/dev/test foram identificados?

Referências

• Rules: .agent/rules/typescript-sem-any.global.md
• Workflow: .agent/workflows/documentar-codigo.global.md