muller-g/repo-analyst

Repo Analyst — Skill

Objetivo

Transformar qualquer projeto codado sem IA em um ambiente onde agentes de IA consigam entender e trabalhar efetivamente, gerando toda a documentação, skills e commands necessários.

Princípios de Análise

O que sempre ler primeiro

1. Arquivo de dependências (package.json, requirements.txt, go.mod, Gemfile, pom.xml, Cargo.toml)
2. README.md se existir
3. CLAUDE.md se já existir (entender o que já foi documentado)
4. .env.example ou .env.sample (variáveis de ambiente críticas)
5. Arquivo de configuração principal (tsconfig.json, eslint.config.js, jest.config.*)
6. Dockerfile e docker-compose.yml se existirem

Estrutura de diretórios — o que procurar

src/routes|controllers|handlers  →  define a API/interface do sistema
src/models|entities|schemas       →  define a camada de dados
src/services|usecases             →  lógica de negócio
src/middleware|filters            →  cross-cutting concerns
src/utils|helpers|lib             →  código utilitário
tests|__tests__|spec              →  estrutura de testes
migrations|db/migrations          →  migrações de banco
prisma/schema.prisma              →  schema do banco (Prisma)

Detecção de Arquitetura

| Padrão | Indícios | |--------|----------| | MVC | /controllers, /models, /views | | Clean Architecture | /usecases, /entities, /repositories, /adapters | | Hexagonal | /ports, /adapters, /domain | | Microservices | múltiplos package.json, /services/* independentes | | Monolito Modular | /modules/* cada um com sua estrutura interna | | Serverless | serverless.yml, /functions, handlers separados | | Event-driven | /events, /subscribers, /publishers, message queues |

Detecção de Tech Stack

Node.js:

• Framework: express, fastify, koa, hapi, nestjs, next, nuxt
• ORM: prisma, typeorm, drizzle, sequelize, knex, mongoose
• Testing: jest, vitest, mocha, cypress, playwright
• Auth: passport, jsonwebtoken, auth.js, lucia

Python:

• Framework: django, flask, fastapi, tornado
• ORM: sqlalchemy, django.db, peewee
• Testing: pytest, unittest

Ruby:

• Framework: rails, sinatra, hanami
• Testing: rspec, minitest

Go: gin, echo, fiber, chi

Java/Kotlin: spring, quarkus, micronaut

O que NÃO ler (ignorar completamente)

• node_modules/, vendor/, .git/, dist/, build/, __pycache__/
• Arquivos binários: .png, .jpg, .ico, .woff, .pdf, .zip
• Arquivos .map, .lock (exceto para identificar package manager)
• Arquivos muito grandes (>100KB) — ler apenas os primeiros 3000 chars

Como Analisar Cada Domínio

API / Rotas

Ler 3-5 arquivos de rotas/controllers para entender:

• Padrão de URL (ex: /api/v1/resource)
• Como autenticação é aplicada (middleware? decorator?)
• Formato de resposta (padrão de sucesso e erro)
• Como validação é feita

Banco de Dados

Ler schema/migrations para entender:

• Principais entidades e seus campos importantes
• Relacionamentos (1:N, N:N)
• Convenções de nomenclatura (snake_case? camelCase?)
• Soft deletes? Timestamps automáticos?

Autenticação

Buscar por: jwt, session, cookie, bearer, auth, login Entender:

• Onde o token é gerado/validado
• Onde o user é carregado
• Rotas protegidas vs públicas

Testes

Ler 2-3 arquivos de teste para entender:

• Estrutura (describe/it? test? classes?)
• Padrão de mocking
• Factories/fixtures usados
• Integração vs unitário

O que o CLAUDE.md Gerado DEVE Conter

Ver template completo em: docs/agents/templates/CLAUDE.md.template.md

Resumo obrigatório:

1. Visão geral — o que o projeto faz (1-2 parágrafos)
2. Stack técnica — linguagem, framework, banco, testes
3. Arquitetura — tipo, camadas, padrões
4. Estrutura de diretórios — o que fica onde e por quê
5. Setup local — comandos para rodar localmente
6. Comandos principais — tabela com start, build, test, migrate, etc.
7. Convenções — nomenclatura, organização de arquivos, imports
8. Banco de dados — schema resumido, como fazer migrations
9. API — autenticação, padrões de endpoint, request/response
10. Testes — como rodar, onde ficam, como escrever novos
11. Workflows comuns — adicionar feature, criar endpoint, criar model
12. Notas críticas — o que NÃO fazer, armadilhas, decisões importantes

Skills a Gerar

Gerar baseado no que o projeto usa:

| Se o projeto tem | Gerar skill | |------------------|-------------| | Banco de dados / ORM | database.md | | API (REST/GraphQL/etc) | api.md | | Testes automatizados | testing.md | | Autenticação | auth.md | | Docker / Deploy | deployment.md | | Frontend / UI | frontend.md | | Sempre | architecture.md + development.md |

Ver templates em: docs/agents/templates/skill.template.md

Commands a Gerar

Gerar baseado na arquitetura do projeto:

| Sempre | implement.md, fix.md, review.md | |--------|---------------------------------------| | Se tem API | add-endpoint.md | | Se tem banco | add-model.md | | Se tem testes | write-tests.md | | Se tem deploy | deploy.md |

Ver templates em: docs/agents/templates/command.template.md

Qualidade do que é Gerado

NUNCA gerar conteúdo genérico. Cada arquivo gerado deve:

• Referenciar arquivos específicos do projeto (ex: src/routes/user.ts não src/routes/[arquivo].ts)
• Usar os nomes reais das entidades/modelos detectados
• Mostrar exemplos reais do código do projeto
• Incluir os comandos exatos do projeto (ex: npm run dev não npm start)
• Mencionar variáveis de ambiente reais encontradas no .env.example

Testar mentalmente: Um agente lendo o CLAUDE.md consegue começar a trabalhar no projeto sem nenhuma outra fonte de informação?