Manueldav2/begin

O que begin faz?

Oriente-se em uma base de código em uma passada, com base em evidências, sem vagar.

A falha que isto existe para evitar: um agente abre um repositório, faz grep de uma palavra que parece plausível, lê três arquivos que coincidentemente correspondem e relata um resumo de arquitetura confiante que descreve 4% do sistema. begin substitui adivinhação sobre onde está o código importante por medição de onde ele está, e então lê apenas o que a medição apontou.

O contrato

1. Nada é lembrado. Tudo é derivado. Importância vem de um PageRank sobre o grafo de importação real; complexidade, de pontos de decisão contados; foco, do git e do log de PRs. Se você não pode apontar para um arquivo:linha ou um commit, você não diz isso.
2. Toda afirmação é ancorada. Cada declaração em BEGIN.md cita path:line, um commit ou um número de PR. Uma frase não ancorada é um palpite, e palpites são o que esta skill existe para matar.
3. Duas camadas, uma delas viva. .begin/ é saída de máquina, regenerada e auto-ignorável. BEGIN.md é prosa que você escreveu, commitou e carimbou com o commit do qual foi derivada. Um hook pós-commit re-deriva a camada de máquina e relata quais seções da prosa o código ultrapassou. Nada nesta skill jamais edita um arquivo rastreado — .begin/ carrega seu próprio .gitignore, então o do repositório fica intocado.
4. Proxies são nomeados como proxies. complexityProxy é uma contagem de pontos de decisão, não uma análise sintática. Aninhamento é medido a partir da indentação. Diga isso; não transforme um proxy em um fato.
5. Uma medição degradada é anunciada, nunca usada silenciosamente. A varredura imprime um bloco [!WARNING] para um clone raso, uma janela de churn morta, arquivos descartados, uma linguagem que não consegue analisar de forma alguma, ou resolução falhando para uma que consegue. Leia esse bloco antes da tabela e repita o que ele diz em BEGIN.md. Um ranking construído sobre um grafo quebrado parece exatamente com um bom — esse é o perigo todo.

Execute

S=~/.claude/skills/begin/scripts

bash  $S/recon.sh      # quem/o quê/quando: PRs, seus commits, edições ao vivo, docs
node  $S/scan.mjs      # estrutura: grafo de importação, hotspots, superfície->motor

Ambos escrevem em .begin/ e imprimem um resumo. Execute-os de qualquer lugar no repositório — a varredura se ancora na raiz do repositório. recon.sh degrada-se limpiamente sem gh, sem rede e sem remoto, mas requer node (redação é obrigatória). Tempos medidos em cache quente: 259 arquivos 0,24s · 3.384 arquivos 1,9s · 2.809 arquivos 1,9s · 1.819 arquivos 2,5s · 1.397 arquivos 3,5s. A contagem de arquivos não prediz o tempo; o conteúdo sim.

Flags que valem a pena conhecer:

• --since "90 days ago" — janela de churn (ambos os scripts usam 90 por padrão).
• --top 40 — quantos hotspots imprimir (padrão 25).
• --author "..." — uma regex. Você raramente precisa dela: o padrão é o user.name do repositório, e recon.sh recai para o autor mais ativo do repositório e diz isso quando você não tem commits lá. Esse é o caso normal em um repositório que você acabou de clonar.
• --exclude 'examples/**,site/**' — mantenha árvores vendidas e sites de documentação fora da contagem de superfície. Os padrões são ancorados em ambas as extremidades, e o número de arquivos removidos é impresso, porque uma exclusão silenciosa aparece mais tarde como uma aresta faltante.
• --root DIR — varra um repositório diferente.

A ordem das operações — siga-a exatamente

Fazer estas fora de ordem é como um agente acaba lendo os arquivos errados.

1. Reconhecimento antes da estrutura

Execute recon.sh primeiro. Ele responde "o que esta pessoa tem feito?" — edições não commitadas, commits branch-vs-main, os últimos ~20 PRs mergeados com seus corpos, e o que cada um mudou. Esse é o prior de foco. Leia .begin/recon.md completamente; é curto.

O diff não commitado é geralmente a coisa mais informativa no repositório — é a pergunta que o usuário está segurando no momento. O Recon sinaliza três coisas sobre ele: quando a árvore está limpa, ele diz isso explicitamente (em vez de omitir a seção e deixar você procurando); quando o diff é apenas lockfiles e saída de build, ele diz para você não gastar sua primeira leitura lá; e quando seu checkout está atrás de origin, ele diz por quantos commits e nomeia os arquivos de PRs recentes que não estão em sua árvore.

Esse último é uma pré-condição, não uma ressalva. Se o recon relatar que você está atrás, o passo 3.2 abaixo é inseguro: as listas de arquivos de PR descrevem código que você não tem. Ou git pull primeiro, ou pule o passo de leitura de PR e diga em BEGIN.md que você o fez.

2. Estrutura em segundo

Execute scan.mjs e leia .begin/scan.md, começando por qualquer bloco [!WARNING]. Você então tem, medido em vez de assumido:

• Superfícies — todo lugar onde um humano ou chamador realmente toca o sistema, agrupados por tipo (web-page, ui-component, http-route, cli-command, mcp-tool, worker, public-api, migration, mais example, config e test que são superfícies mas não produto). Esta é a extremidade de UI do mapa.
• Hotspots — ranqueados, com uma coluna why nomeando o termo que colocou cada arquivo lá: depended-on, churn, complex ou recent. Um arquivo no topo por churn é um animal diferente de um no topo por depended-on; a coluna diz qual conversa ter.
• Caminhos superfície → motor — a cadeia de importação literal de um endpoint ou botão até a parte difícil, computada por BFS. Um caminho que cruza uma aresta await import() preguiçosa é rotulado como tal, porque é resolvido em tempo de chamada em vez de tempo de carga.
• Grupos de ciclo de importação — conjuntos fortemente conectados sobre arestas de valor estático, com um loop direcionado real percorrido. Arestas apenas de tipo e preguiçosas (await import(...)) são excluídas, porque nenhuma forma um ciclo de inicialização real.
• Arquivos inalcançáveis — código morto, ou uma superfície que as heurísticas perderam. Decida qual, e diga qual.

2.5. Leia o mapa que o repositório já escreveu para você

Antes de abrir qualquer hotspot, verifique se há AGENTS.md, CLAUDE.md, ARCHITECTURE.md ou READMEs por diretório — recon.md os lista. Um repositório que envia um mapa de subsistema entrega a você em trinta linhas o que a varredura infere em dois segundos e a prosa leva uma hora para reconstruir. Leia esses primeiro, então use a varredura para verificá-los: a documentação fica desatualizada, o grafo não.

3. Leia apenas o que a medição apontou

Leia, nesta ordem, e pare:

1. O diff não commitado e os commits da branch atual (o que eles estão fazendo agora).
2. Os arquivos alterados pelos 3–5 PRs mergeados mais recentes (o que eles acabaram de decidir).
3. Os 8–15 hotspots principais de scan.md.
4. Para cada um dos 3 primeiros, percorra sua superfície reachedVia para dentro, para que você possa declarar o caminho completo da ação do usuário ao motor.
5. README, os documentos voltados ao agente de 2.5, e qualquer documento cujo cabeçalho corresponda a um hotspot.

Não abra arquivos fora deste conjunto em uma primeira passada. Se algo parecer faltando, isso é uma descoberta a relatar, não uma licença para navegar.

4. Verifique antes de escrever

A tabela é um conjunto de leads, não uma conclusão. Antes de cada afirmação ir para BEGIN.md:

• Abra o arquivo e confirme que a linha que você está prestes a citar diz o que você pensa.
• Para um caminho superfície → motor, confirme que a importação realmente existe no código-fonte.
• Para qualquer coisa sobre comportamento, prefira um teste que o demonstre a uma função que pareça fazer isso.
• grep os caminhos quentes por falhas engolidas — catch {}, .catch(() => {}), as any, as never, retornos descartados. Bugs vivem onde erros são jogados fora, e estes são o item de maior valor que você pode devolver no primeiro dia.
• Gaste pelo menos uma passagem tentando falsificar sua afirmação principal, não confirmá-la. As frases mais valiosas em um bom BEGIN.md são as que contradizem a varredura.

Se a varredura estiver errada sobre algo, diga isso em BEGIN.md e corrija. Um arquivo que o grafo chama de morto mas que é realmente alcançado por HTTP ou uma fila é a coisa mais útil que você pode registrar, porque ninguém mais vai encontrá-lo novamente também. Declare tais pontos de entrada em .begin/surfaces.txt (um caminho por linha, opcionalmente path<TAB>kind) e a próxima execução os tratará como superfícies.

5. Escreva BEGIN.md

Use references/BEGIN-template.md, e leia references/EXAMPLE-BEGIN.md primeiro para calibrar — é um real, não uma maquete. Estrutura, em ordem:

1. O que este sistema faz em um parágrafo — nos termos do usuário, não do código.
2. O mecanismo fundamental — primeiros princípios. Qual é a transformação central? Qual é a única ideia que torna o resto óbvio? O que quebra sem ela?
3. Superfícies → motor — uma tabela dos caminhos de scan.md, cada linha verificada. Se nenhuma linha cruzar um limite de processo ou rede, diga isso explicitamente: em um repositório de linguagem dividida, a costura real é geralmente uma chamada HTTP ou de fila que nenhum grafo de importação pode ver.
4. As partes complexas, ranqueadas — descoberta primeiro, medição por último. Cada entrada precisa de uma armadilha que cite um file:line não já em sua linha de medição. Uma entrada para a qual você não pode dar isso é uma que você não leu de fato: delete-a.
5. Decisões e porquê — cada uma vinculada ao seu PR ou commit, com o raciocínio do corpo do PR. Isto é o que torna o documento um grafo de conhecimento em vez de um tour de código.
6. Onde você parou — ou, em um repositório que você não possui, quem é o dono e onde está crescendo: os autores ativos, o que os PRs abertos mais novos estão adicionando, qual ler primeiro.
7. O que a camada de máquina não pôde ver aqui — e perguntas em aberto, incluindo a única suposição que está fazendo o maior trabalho de sustentação. Nunca omita isto.

Registre também como executar e verificar (os scripts que recon.md extraiu de package.json) e um glossário para qualquer palavra que este repositório sobrecarregue. Ambos são o que um recém-chegado precisa primeiro e o que todo tour de código esquece.

Faça links cruzados com âncoras [[wiki-style]]. Carimbe cada seção:

<!-- begin:section id="ingestion" sha="0055f01" files="src/adapter.ts,src/identity.ts" -->

sha = git rev-parse --short HEAD no momento em que você derivou a seção (não o commit que mais tarde adiciona BEGIN.md). files = os arquivos nos quais as afirmações da seção se baseiam; globs como src/engine/** funcionam. Uma seção com nenhum files=, ou um files= nomeando um caminho que não existe, nunca pode ficar desatualizada e é reportada como não verificável — que é a falha que esta skill existe para prevenir, então acerte os caminhos.

6. Torne-a viva

bash $S/install-hook.sh          # pós-commit; --pre-push para o outro gatilho

O hook reexecuta a varredura e imprime um aviso de uma linha nomeando quantas seções ficaram desatualizadas, com detalhes em .begin/stale.md. Ele honra core.hooksPath (husky) e worktrees do git, anexa a um hook existente sem corrompê-lo, recusa-se a anexar a um hook que não seja shell e nunca toca um arquivo rastreado. Remova-o com --uninstall, que remove apenas seu próprio bloco.

/begin update

Quando o usuário retornar a um repositório que já tem um BEGIN.md:

node $S/refresh.mjs && cat .begin/stale.md

Reescreva apenas as seções desatualizadas, reexecute recon.sh para atualizar a seção 6, e recarimbe cada seção reescrita com o novo sha do HEAD. Deixe as seções atuais byte-idênticas — uma atualização que reescreve tudo destrói tanto a sensação do leitor sobre o que mudou quanto a utilidade do histórico do git.

Se ainda não houver BEGIN.md, /begin update é apenas /begin: escreva um.

Reportando de volta

Um parágrafo curto: o mecanismo fundamental, o ou dois arquivos que mais importam e por quê, onde o usuário parou e a única coisa que você não pôde verificar. Detalhes vivem em BEGIN.md, não na resposta.

Termine com o que você não verificou. Uma passagem begin que alega cobertura total está mentindo.

Limitações conhecidas — declare-as, não as encubra

• O grafo de importação é estático. Um import('./x') literal é resolvido (e marcado como preguiçoso); um import(expr) computado, um contêiner de DI ou um registro chaveado por string não produz aresta alguma, então tal arquivo pode parecer inalcançável enquanto é fundamental. Em um repositório de linguagem dividida, a costura frontend↔backend é uma chamada HTTP ou WebSocket e é invisível por construção. A varredura sinaliza arquivos inalcançáveis precisamente para que um humano possa julgar.
• Resolução completa de JS/TS e Python — tsconfig paths (cada config na árvore, não apenas a raiz), extends, references de projeto, NodeNext ./x.js → x.ts, e importações absolutas, relativas e de submódulo do Python contra raízes inferidas (medido em ~98% de recall e precisão contra uma verdade absoluta ast do CPython). Go, Rust, Ruby, Java, Kotlin, Swift, PHP, C# e C/C++ não contribuem com arestas alguma. Em tal repositório, todo arquivo mostra importância no piso e aparece "inalcançável"; a varredura avisa, e você deve repetir esse aviso em vez de relatar um grafo vazio como uma descoberta.
• complexityProxy conta pontos de decisão por linguagem, em código com comentários e strings de linha única removidos. Arquivos de marcação e esquema pontuam 0 por design; arquivos vendidos, minificados e gerados são detectados e ranqueados separadamente. Literais de modelo multilinha ainda são contados, então um arquivo pesado em modelos parece um pouco quente.
• Churn é limitado por --since, e um clone raso ou fresco não tem nenhum — a varredura diz isso alto e claro. Um arquivo reescrito uma vez há dois anos ainda pontua perto de zero e ainda pode ser o arquivo mais importante do repositório.

Testes

node $S/test-scan.mjs                   # grafo, ciclos, superfícies, alcançabilidade, Python
node $S/test-scan.mjs --mutate pyDotDot # ...e prove que as asserções podem ficar vermelhas
bash  $S/test-living.sh                 # desatualização, hooks, limpeza da árvore
node  $S/redact.mjs --self-test         # segredos capturados E texto limpo intacto

Toda asserção existe porque aquele bug foi real e foi enviado uma vez. Mutações: alias, jsToTs, valueCycle, typeCycle, pyAbsolute, pyDotDot — cada uma deve tornar sua asserção vermelha, e CI falha se uma não o fizer.