Documentação e Modernização

Dois fluxos de trabalho complementares para um repositório que o usuário já tem clonado localmente, agrupados como uma única habilidade:

• Modo de Documentação — produz um documento de arquitetura definitivo e citado a partir do código no disco. Ideal para integração, mapas de design de sistemas ou como base de evidências para um esforço de modernização.
• Modo de Modernização — transforma essa arquitetura em um plano faseado e com escada de segurança para atualizar, migrar ou reescrever um sistema legado.

Seleção de modo

• Se o usuário deseja entender, documentar, mapear, pesquisar ou se integrar a uma base de código, execute o Modo de Documentação.
• Se o usuário deseja modernizar, migrar, atualizar ou reescrever um sistema, execute o Modo de Modernização. O Modo de Modernização é autossuficiente: se nenhum documento de arquitetura existir ainda, ele executa o fluxo de trabalho do Modo de Documentação primeiro (na mesma execução) e, em seguida, continua direto para o plano.

Em caso de dúvida, produza o documento de arquitetura primeiro — ele é a base de evidências auditada na qual ambos os modos se baseiam.

Modo de Documentação

Gera um documento de arquitetura definitivo e citado para um repositório que o usuário já tem clonado localmente. O objetivo é um texto que alguém possa entregar a um novo engenheiro como referência de integração — amplo o suficiente para cobrir todo o sistema, profundo o suficiente nas partes difíceis para ser útil e confiável porque cada afirmação remonta a um arquivo no disco.

Por que local-primeiro

Ler do clone local (não da API do GitHub ou da web) é o padrão deliberado. É mais rápido, gratuito, evita limites de taxa e — o mais importante — descreve o código exato à sua frente em vez de o que quer que main pareça remotamente. O único compromisso é que fatos apenas remotos (contagem de estrelas, histórico completo de execução de CI, repositórios irmãos) não são visíveis. Tudo bem: declare-os como fora do escopo ou marque-os como [UNVERIFIED] em vez de adivinhar.

Local-primeiro não é local-nunca-remoto: uma consulta na web/API é uma última opção de fallback deliberada, reservada para um fato que genuinamente não pode ser determinado a partir do disco e que importa materialmente para o documento. Quando você o utilizar, marque o resultado claramente (por exemplo, [UNVERIFIED] / obtido-remotamente) para que o leitor saiba que não veio do clone, e nunca deixe que se torne o caminho fácil que substitui a leitura do código no disco.

Fluxo de trabalho

1. Estabeleça a identidade primeiro. Execute git remote -v, git branch --show-current e git log -1 para que o documento seja ancorado a um remoto, branch e commit específicos. Um leitor deve ser capaz de dizer qual snapshot isso descreve. URLs remotos podem conter credenciais embutidas (por exemplo, https://<token>@github.com/...) — redija quaisquer credenciais/tokens da URL antes de gravá-la no documento.
2. Detecte, não assuma. Leia os manifestos reais (go.mod, package.json, Cargo.toml, pyproject.toml, pom.xml, etc.), o executor Makefile/tarefas, a configuração de CI e quaisquer documentos de agente ou contribuidor específicos do repositório (AGENTS.md, CONTRIBUTING, README, docs/). Estas são a fonte da verdade para a pilha de tecnologia e comandos — prefira-as ao seu conhecimento prévio do framework.
3. Mapeie a amplitude, depois aprofunde. Primeiro construa o mapa de todo o repositório (as três lentes abaixo), depois escolha os 2-3 subsistemas mais difíceis e aprofunde-se neles.
4. Verifique conforme avança. Abra os arquivos que você cita. Se você referenciar um número de linha, você deve ter realmente lido essa linha. Afirmações não suportadas são piores que omissões aqui — todo o valor deste documento é que ele pode ser confiável.

Estrutura de saída

Produza um único arquivo Markdown com as seções abaixo, nesta ordem. Adapte os títulos ao projeto real (uma ferramenta CLI não tem uma lente "frontend" — incorpore esse espaço ao que for relevante para esse repositório), mas mantenha a forma de três lentes e a disciplina de verificação.

Parte 1 — Mergulho técnico em todo o repositório

• O que é o repositório (um parágrafo, citado ao README).
• Tabela de detecção de pilha de tecnologia: camada | tecnologia | evidência (arquivo+linha).
• Pontos de entrada (backend, frontend, CLI — o que for aplicável).
• Inventário de Comandos e Verificação — uma tabela dos comandos canônicos do projeto (command | purpose | evidence), verificados contra o executor de tarefas / manifestos / configuração de CI, não adivinhados. Cubra build, run/serve, test (e como executar um único teste), lint, format e — onde existirem — typecheck, end-to-end/smoke, contract e quaisquer outros comandos de gate, além do CI

…