CommunityEscrita e Ediçãogithub.com

Shaelz/codebase-orient-skill

Uma habilidade reutilizável de orientação de código para Claude Code e Codex.

O que é codebase-orient-skill?

Esta habilidade é projetada para orientar rapidamente um agente de IA (como Claude Code ou Codex) sobre o estado atual de um repositório de software antes de realizar trabalhos complexos. Ela cria ou reconcilia um pacote fixo de quatro artefatos em `docs/ai/`, garantindo que o agente tenha um mapa preciso da base de código, incluindo estrutura, dependências, rotas, autenticação, implantação e muito mais. A habilidade prioriza a verificação de fatos contra o código fonte, usa rótulos de confiança e segue regras rigorosas para evitar modificar o código de aplicação ou realizar commits. Ela é útil para desenvolvedores que entram em repositórios desconhecidos ou após mudanças estruturais, economizando tokens de contexto ao evitar rediscovery repetitivo da base de código. A habilidade oferece modos normal e dry-run, e é compatível com Claude Code e Codex, com sondas específicas para frameworks como SvelteKit.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add Shaelz/codebase-orient-skill

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidade: codebase-orient

Propósito

Orientar Claude sobre o estado atual deste repositório antes de trabalhos não triviais. Ele cria ou reconcilia um pacote fixo de quatro artefatos com procedência comprovada em docs/ai/. O código fonte e a configuração do projeto permanecem como autoridade.

Quando usar esta habilidade

Use esta habilidade quando

  • Entrando em um repositório novo ou desconhecido
  • Iniciando uma nova sessão após um período significativo de afastamento do repositório
  • Antes de trabalhos de implementação abrangentes ou com múltiplos arquivos
  • Antes de refatorações, limpezas, planejamento de arquitetura ou handoff de agente
  • Após mudanças estruturais: rotas, esquemas, autenticação, implantação, configuração ou superfícies administrativas
  • Quando docs/ai/ está ausente, desatualizado, incompleto ou internamente inconsistente
  • Quando a estrutura do repositório, superfícies de mudança, alvos de implantação, comportamento de autenticação, rotas administrativas, comandos ou formato de teste não estão claros
  • Quando o agente gastaria contexto significativo redescobrindo o que já está em ou perto de docs/ai/
  • Sempre que o usuário disser "digitalizar", "orientar", "entender", "mapear", "revisar", "auditar", "levantar", "familiarizar" ou "antes de eu começar"

Pule esta habilidade quando

  • Fazendo uma pequena edição local e conhecida em um único arquivo
  • Corrigindo um bug de um arquivo onde o arquivo relevante e a mudança já estão claros
  • Fazendo mudanças apenas de cópia ou apenas de string
  • A tarefa está estritamente escopada para arquivos já verificados no contexto atual
  • docs/ai/ acabou de ser atualizado e a tarefa é estreita o suficiente para não precisar de uma passagem de orientação completa

Orientação de uso consciente de tokens

docs/ai/ é um cache de orientação. Um cache novo reduz o custo de tokens de redescoberta do repositório repetido entre sessões e handoffs de agente.

  • Se docs/ai/ está novo e completo: leia-o como contexto e prossiga. Pule a reexecução da orientação.
  • Se docs/ai/ pode estar desatualizado ou está ausente: execute a habilidade para atualizar o cache. O custo inicial de token se amortiza ao longo do trabalho pela frente.
  • Se a tarefa é minúscula e o arquivo alvo já é conhecido: pule a orientação. Use leituras direcionadas em vez disso.
  • Se o agente gastaria muitos tokens redescobrindo o que docs/ai/ já captura: atualize-o.

Não economize tokens pulando a orientação e depois adivinhando a estrutura. Se a redescoberta ampla do repositório seria de outra forma repetida ou cara, atualize o cache em vez disso.

Regras rígidas durante a orientação

  • Não modifique código de aplicação ou código fonte.
  • Não refatore.
  • Não faça commit.
  • Verifique afirmações contra o código fonte antes de escrevê-las.
  • Marque cada afirmação significativa com um rótulo de confiança.

Modo normal vs modo dry-run

Modo normal (padrão - use quando o usuário não especificar):

  • Resolva pequenas incertezas relevantes à tarefa automaticamente lendo arquivos fonte
  • Crie um pacote completo no primeiro uso em um repositório limpo
  • Reutilize um pacote limpo exato-atual sem reescrevê-lo
  • Trate uma solicitação inespecífica para atualizar ou reconciliar como uma reconciliação completa
  • Relate o que mudou no final

Modo dry-run / apenas relatório (use quando o usuário disser "dry-run", "apenas relatório", "não escreva", "proponha mudanças primeiro", "apenas audite", "sem escritas" ou similar):

  • Inspecione e colete mudanças propostas
  • Relate edições propostas a docs/ai/ sem escrevê-las
  • Aguarde aprovação explícita antes de escrever

Se o modo não for especificado, padronize para Modo normal.

Ciclo de vida e segurança de escrita

  • Atualização explícita: Atualize ou reconcilie apenas quando o usuário pedir explicitamente depois que um pacote exato-atual for encontrado.
  • Atualização escopada: Siga um escopo explícito do usuário e suas dependências diretas. Registre a cobertura escopada sem avançar ou reivindicar um snapshot completo do pacote. Não crie um pacote suportado parcial antes que um pacote completo exista.
  • Adoção de legado: Artefatos Markdown sem ORIENTATION_STATE.json são material legado. Inspecione-os, mas obtenha aprovação explícita antes de escrever um manifesto ou alterá-los. Reconcilie a partir da fonte após a aprovação.
  • Árvore suja: Antes de escrever estado que representa trabalho não comitado, pergunte se deve escrever um snapshot sujo ou apenas relatar. Registre a condição da árvore; mantenha-a marcada como suja até que uma atualização limpa a substitua.
  • Nenhum histórico Git utilizável: Execute uma reconciliação completa e registre que a comparação de revisões não está disponível.
  • Edições manuais: Orient possui o pacote. Não prometa comportamento de mesclagem ou preservação para estado de Orient editado manualmente.

Rótulos de confiança

  • Fato: verificado diretamente no código ou documentação
  • Inferência forte: suportado por múltiplos arquivos
  • Inferência fraca: plausível mas não confirmado
  • Desconhecido: precisa de mais inspeção antes de editar

Distinga como uma afirmação foi estabelecida:

  • verificado independentemente da fonte/config: afirmação verificada contra a fonte real ou arquivo de configuração, não tirada de documentos
  • herdado de documentos existentes: afirmação tirada de CLAUDE.md, README, ou outra documentação sem verificação independente
  • herdado e depois verificado: afirmação originada em documentos e subsequentemente confirmada contra a fonte
  • existência de caminho confirmada: arquivo encontrado mas não lido
  • leitura parcial: porção do arquivo inspecionada; pode não capturar o contexto completo
  • leitura completa da fonte: conteúdo completo do arquivo inspecionado
  • inferido da implementação: deduzido de como o código se comporta, não explicitamente declarado
  • inferido de comentários/testes/fixtures: originado de contexto não autoritário; trate como Inferência forte no máximo
  • comportamento verificado por teste: confirmado por execução de teste aprovado
  • desconhecido: base não estabelecida; não apresente como Fato

Em relatórios finais e documentos de orientação, rotule cada afirmação não trivial com uma das origens acima para que os leitores possam julgar quais afirmações precisam de reverificação antes de agir sobre elas.

Ordem de descoberta

Nota de personalização: A ordem de descoberta abaixo é intencionalmente ampla e funciona na maioria das formas de projeto sem edição. Você pode ajustar os caminhos de arquivo e a ordem para um projeto específico, mas isso é opcional - não necessário antes do primeiro uso.

Execute nesta ordem:

  1. Arquivos de instrução do projeto como CLAUDE.md, AGENTS.md e README.md, se presentes - propósito do produto, regras do agente, convenções do projeto. Regra de documentos como hipóteses
    • Trate esses documentos como hipóteses úteis, não como verdade autoritária.
    • Extraia alegações factuais de alto impacto sobre arquitetura, rotas, implantação, testes e arquivos fonte da verdade.
    • Verifique essas alegações contra o código fonte antes de confiar nelas. Foco em alegações que afetariam edições futuras; não audite cada frase.
    • Não copie alegações desses documentos para CODEBASE_MAP.md sem rotular se são verificadas independentemente da fonte/config ou herdadas de documentos existentes.
    • Se um documento de instrução estiver desatualizado ou enganoso em comparação com o que a fonte mostra, registre a deriva em OPEN_QUESTIONS.md sob a regra de relatório de risco oculto e rotule-a como deriva de documentação.
    • Mapeie a topologia da camada de instrução: observe quais arquivos de instrução estão presentes (ex., CLAUDE.md, AGENTS.md, .claude/settings.json) e em qual escopo (projeto-local vs nível de usuário). Registre isso em CODEBASE_MAP.md; ajuda agentes futuros a saber quais regras se aplicam.
  2. Manifesto do projeto (ex., package.json, pyproject.toml, Cargo.toml) - dependências, scripts, comandos de construção/teste
  3. Arquivos de construção e configuração (ex., configuração do framework, configuração do bundler) - adaptador, config de construção
  4. Diretório scripts/, se presente - pode conter ferramentas executadas manualmente não representadas em scripts de pacote ou CI
  5. Pontos de entrada e camada de roteamento - todas as páginas, controladores ou rotas de API
  6. Lógica de negócio principal - tipos de domínio, modelos, pontuação, lógica de relatório
  7. Serviços do lado do servidor - autenticação, banco de dados/esquema, e-mail, integrações externas
  8. Camada de IU/apresentação - componentes, visualizações, modelos
  9. Arquivos de internacionalização ou cópia - arquivos de localidade
  10. Ciclo de vida da requisição / middleware - hooks, interceptadores, middleware
  11. Camada de banco de dados - migrações, snapshots de esquema
  12. Testes - estrutura de teste e formato de cobertura
  13. Documentação - documentos existentes, matrizes de verificação. Se um plano de lançamento, documento de acompanhamento de marco ou changelog de versão for encontrado, adicione uma seção ## Status de lançamento a CODEBASE_MAP.md resumindo a versão atual, o marco ativo e o que está bloqueando o próximo lançamento. Omita esta seção se nenhum artefato de ciclo de vida de lançamento estiver presente.
  14. Incerteza conhecida

Sondas específicas de framework

Aplique estas sondas além da ordem de descoberta genérica quando o framework relevante for detectado.

A habilidade reutilizável atualmente inclui um conjunto de sondas ajustadas explícitas para SvelteKit. Outros frameworks atualmente usam a ordem de descoberta genérica a menos que evidências de fogo real ou avaliação justifiquem uma seção de sonda ajustada dedicada.

SvelteKit

Globe os seguintes padrões de arquivo quando um projeto SvelteKit for detectado:

  • src/routes/**/+page.svelte: páginas de rota de IU; cada arquivo é um candidato a rota; verifique subdiretórios, não apenas o src/routes/+page.svelte de nível superior
  • src/routes/**/+page.server.ts: carregamento de dados do lado do servidor, ações de formulário e controle de acesso ao nível da rota
  • src/routes/**/+layout.svelte: shells de layout compartilhado
  • src/routes/**/+layout.server.ts: funções de carregamento do lado do servidor para autenticação, sessão ou dados ao nível do layout
  • src/routes/**/+server.ts: endpoints de API e manipuladores de requisição apenas do servidor

Arquivos de rota do lado do servidor (+page.server.ts, +layout.server.ts, +server.ts) são críticos para entender autenticação, carregamento de dados, ações de formulário, endpoints de API e controle de acesso ao nível da rota. Não os pule ao mapear rotas ou superfícies de mudança.

  • O modelo de shell de aplicativo padrão é src/app.html.
  • A escolha do adaptador em svelte.config.js determina o alvo de implantação - confirme antes de fazer alegações relacionadas à implantação.

Regra de precisão de CI/implantação

Ao ler arquivos de fluxo de trabalho de CI ou implantação, preserve detalhes operacionalmente relevantes. Não arredonde especificidades para resumos vagos.

Capture e relate:

  • nome do grupo de concorrência (quais execuções competem entre si)
  • comportamento cancel-in-progress - se true, diga "execuções mais recentes cancelam execuções em andamento do mesmo grupo", não apenas "impede deploys paralelos"
  • comportamento fail-fast
  • caminhos de artefato de deploy
  • formato de nomenclatura de lançamento incluindo qualquer componente de timestamp ou hash
  • política de retenção e limpeza para lançamentos ou artefatos antigos
  • condições de acionamento manual vs automático
  • segredos e variáveis de ambiente necessários
  • se a implantação sobrescreve no local, prepara para um caminho temporário, usa links simbólicos, ou usa diretórios de lançamento versionados

Rotule alegações de CI/implantação com verificado independentemente da fonte/config quando lido diretamente do arquivo de fluxo de trabalho. Não resuma esses detalhes de maneiras que percam precisão que um operador precisaria durante um incidente.

Heurística de profundidade de leitura

Não leia todos os grandes arquivos CSS, config ou gerados por padrão.

  • Leitura completa: arquivos que afetam diretamente a tarefa solicitada (pontos de entrada, roteamento, autenticação, esquema, config de construção, o arquivo a ser editado).
  • Leitura parcial ou confirmação de caminho apenas: superfícies secundárias como grandes folhas de estilo, código fornecido, saída gerada ou arquivos de configuração não relevantes para a tarefa. Se você apenas confirmar o caminho de um arquivo ou ler uma parte, diga isso explicitamente no relatório usando os rótulos existência de caminho confirmada ou leitura parcial definidos em Rótulos de confiança.
  • Pular: arquivos que estão claramente fora do escopo (ex., assets binários, lock files, snapshots de teste) a menos que uma pergunta específica os torne relevantes.

Em caso de dúvida, prefira confirmar a existência primeiro e ler completamente apenas se uma alegação exigir.

Existência de caminho vs leitura de conteúdo

A existência de caminho sozinha é suficiente para alegações de inventário de baixo risco - confirmar uma estrutura de diretório, listar contagens de arquivos ou notar que um arquivo de configuração está presente.

Leia o conteúdo real do arquivo quando a alegação afetar comportamento, arquitetura, risco, comandos, implantação, autenticação, roteamento ou superfícies de mudança. Não rotule uma alegação como verificada independentemente da fonte/config com base apenas na existência do caminho quando o arquivo é barato de inspecionar e seu conteúdo afetaria materialmente o mapa.

Regra de leitura de pequeno arquivo fonte da verdade

Se um arquivo pequeno parece definir vocabulário ou tokens fonte da verdade usados em todo o projeto, leia o suficiente dele para verificar o vocabulário em vez de herdar o vocabulário de documentos.

Exemplos onde isso se aplica:

  • arquivos de token de propriedade personalizada CSS
  • arquivos de configuração de rota ou menu
  • arquivos pequenos de esquema ou constantes
  • registros de comando ou plugin

Use uma leitura parcial quando isso for suficiente. Rotule as alegações resultantes com a origem de alegação apropriada (leitura parcial, leitura completa da fonte). Não as rotule como verificadas independentemente da fonte/config se você não leu realmente o arquivo.

Regra de glob de artefato barato

Antes de deixar uma pergunta em aberto sobre a existência ou escopo de assets estáticos, scripts, saídas geradas, documentação, testes, migrações ou arquivos de configuração, resolva-a com um glob de caminho barato.

Padrões de glob comuns para tentar:

  • static/**/*
  • public/**/*
  • scripts/**/*
  • tests/**/* ou test/**/* ou spec/**/*
  • .github/workflows/*
  • docs/**/*
  • migrations/**/*
  • dist/**/* ou build/**/*

Não leia profundamente todos os arquivos correspondidos por padrão. Use o glob para resolver questões de existência e escopo de forma barata. Acompanhe com leituras direcionadas apenas quando o conteúdo de um arquivo específico for necessário.

[truncado para tradução]

Habilidades Relacionadas