soyun9947/codebase-intel

O que codebase-intel faz?

Mapeia dependências do projeto e documenta a intenção do código base para fornecer aos agentes de IA um contexto arquitetural profundo.

Visão Geral

Esta habilidade analisa a estrutura do seu projeto para construir um mapa de dependências e extrair a intenção do código. Ao fazer isso, capacita agentes de IA a entender não apenas o que o código faz, mas por que ele foi escrito daquela forma, melhorando drasticamente a qualidade das sugestões e ações.

Como Funciona

1. Mapeamento de Dependências: Examina arquivos de configuração como package.json, requirements.txt, Cargo.toml, etc., para identificar todas as dependências externas. Em seguida, analisa as importações internas (ex: import ... from ..., require, use) para criar um grafo de dependências entre módulos.
2. Extração de Intenção: Lê docstrings, comentários e nomes de funções/classes para inferir o propósito de cada componente. Armazena essa semântica em um formato estruturado.
3. Fornecimento de Contexto: Gera um resumo compacto do grafo de dependências e intenções codificadas, que é fornecido ao agente de IA via prompt ou ferramenta de contexto. O agente pode então usar essa informação para tomar decisões mais informadas.

Exemplo de Uso

Suponha que você tenha um projeto Node.js:

my-app/
├── src/
│   ├── utils/
│   │   ├── logger.js    # Fornece logging centralizado
│   │   └── validator.js # Valida entrada de dados
│   ├── services/
│   │   ├── userService.js    # Gerencia lógica de usuário
│   │   └── authService.js    # Lida com autenticação
│   ├── routes/
│   │   └── userRoutes.js     # Define endpoints da API
│   └── index.js               # Ponto de entrada
├── package.json
└── README.md

Após executar codebase-intel, você receberia um mapa como:

Dependências:
- userRoutes.js -> userService.js, authService.js, utils/validator.js
- userService.js -> utils/logger.js
- authService.js -> utils/logger.js

Intenções:
- logger.js: Fornecer logging centralizado com níveis (info, warn, error)
- validator.js: Validar entrada de usuário com regras personalizadas
- userService.js: CRUD de usuários, hash de senha
- authService.js: Autenticação JWT, refresh tokens
- userRoutes.js: Endpoints REST para usuários

Quando você pede ao agente de IA para "adicionar um serviço de email", ele entende que precisa criar um módulo em src/services/, seguir o padrão de logging existente, e integrar com as rotas de usuário, gerando código mais coerente.

Plataformas Suportadas

• Claude Code: Funciona como uma ferramenta de análise de código e contexto.
• Cursor: Integra-se com o recurso de contexto do Cursor.
• Codex: Pode ser usado para preparar prompts ricos em contexto.

Como Instalar

Adicione a habilidade ao seu projeto:

# Supondo que você use um sistema de habilidades (ex: claude-code, cursor)
# O comando exato depende do seu gerenciador de habilidades
# Exemplo: npx codebase-intel [options]

Configuração

A habilidade pode ser configurada através de variáveis de ambiente ou um arquivo de configuração (.codebase-intel.json ou codebase-intel.yaml).

Opção	Descrição	Padrão
include	Padrões de arquivo para incluir	"src/**/*.js", "src/**/*.py"
exclude	Padrões de arquivo para excluir	"node_modules/**", "vendor/**"
output	Formato de saída (json, markdown)	json
intent	Extrair intenção?	true

Exemplo de .codebase-intel.json:

{
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules/**", "dist/**"],
  "output": "markdown",
  "intent": true
}

Saída Típica

A saída (em markdown, por exemplo) é um bloco de contexto que pode ser injetado diretamente na conversa com o agente:

## Contexto do Código Base

### Mapa de Dependências
- `src/index.ts` depende de `src/services/userService.ts`, `src/services/authService.ts`
- ...

### Intenções
- `src/index.ts`: Ponto de entrada do servidor Express.
- ...

---
Dica: Use estas informações para fazer alterações consistentes com a arquitetura.

Contribuições

Contribuições são bem-vindas! Abra uma issue ou PR no repositório original: soyun9947/codebase-intel

Licença

MIT