---
id: document-project
agent: architect
title: Gerar a documentação de arquitetura do projeto
inputs: [codebase]
outputs: [documentação de arquitetura, mapa de dependências, riscos estruturais]
elicit: false
modes: [interactive, yolo]
---

# Gerar a documentação de arquitetura do projeto

**Objetivo:** produzir uma documentação de arquitetura fiel ao que o codebase **realmente é** — não
ao que deveria ser — para que qualquer agente ou humano entenda o sistema, suas fronteiras e onde ele
racha, sem ter que reler o repositório inteiro.

**Pré-condições:**
- O repositório está acessível e legível. Se estiver vazio ou inacessível, **pare** e reporte.
- Há um destino de documentação (`docs/architecture/`). Se já existir doc, eu atualizo o que mudou em
  vez de reescrever do zero.

## Passos

1. **Reconheça o terreno.** Identifico stack, linguagens, gerenciador de pacotes, entrypoints e a
   convenção de organização (por camada / feature / domínio). Documento o que existe, sem julgar.
2. **Mapeie as camadas e fronteiras.** Frontend, backend, dados, infra: o que cada camada faz, onde
   ela termina e onde fala com a próxima. Cada fronteira de serviço e contrato de API vira uma seção.
3. **Levante o mapa de dependências** (`Grep`/`Glob`, code-intel se disponível). Módulos internos,
   dependências externas e — crucial — qualquer ciclo de dependência. Anoto acoplamentos que viram
   gargalo.
4. **Documente o fluxo de dados** das entradas às saídas: como um request atravessa as camadas, onde
   os dados persistem, onde há cache/fila. Para a camada de dados, registro a tecnologia e o contrato;
   o schema detalhado é território da @data-engineer.
5. **Anote os riscos estruturais (teste do 10×).** Para cada fronteira crítica, o que quebra ao
   escalar: N+1, hot path, ponto único de falha, acoplamento perigoso. Registro o failure mode
   observado — documentação honesta inclui as rachaduras.
6. **Escreva no template e salve.** Preencho a documentação a partir do template de arquitetura, salvo
   em `docs/architecture/` e entrego como base para `analyze-project-structure`,
   `architect-analyze-impact` ou um assessment brownfield. Subida do doc → @devops.

## Critério de pronto (DoD)

- [ ] Stack, entrypoints e convenção de organização documentados como realmente são
- [ ] Cada camada e fronteira de serviço descrita, com seus contratos de API
- [ ] Mapa de dependências completo, com ciclos identificados
- [ ] Fluxo de dados ponta a ponta documentado
- [ ] Riscos estruturais anotados com failure mode ao escalar (teste do 10×)
- [ ] Documentação salva em `docs/architecture/`, sem invenção (reflete o codebase, não o desejo)

## Falha / recuperação

- **O codebase é grande demais para documentar de uma vez** → priorizo as camadas e fronteiras
  críticas primeiro, marco o resto como pendente explícito; não invento o que não inspecionei.
- **Não consigo determinar o comportamento real de um módulo** → registro a incerteza como tal, em
  vez de afirmar uma arquitetura que estou supondo (No Invention vale para documentação também).
- **A camada de dados exige detalhamento de schema/DDL** → documento a tecnologia e o contrato e
  delego o aprofundamento de schema à @data-engineer.
- **A documentação precisa ser commitada e subida** → faço o registro local; a subida ao remoto é
  exclusiva do @devops.