Geração de Documentação Técnica de Repositórios

1. Objetivo

Este documento estabelece as diretrizes e o fluxo operacional para Agentes de Inteligência Artificial (IA) na análise de repositórios de código e na subsequente geração de documentação técnica. O objetivo primordial é assegurar a produção de artefatos documentais que sejam precisos, abrangentes, tecnicamente aprofundados e imediatamente aplicáveis por equipes de desenvolvimento, visando otimizar o processo de onboarding, facilitar a manutenção proativa e garantir a evolução sustentável dos sistemas.

A documentação gerada deve capacitar qualquer desenvolvedor a compreender, de forma autônoma e eficiente:

• Propósito e Contexto: A finalidade do projeto e seu posicionamento estratégico dentro do ecossistema corporativo.
• Estrutura e Arquitetura: A organização interna do código, os padrões arquiteturais empregados e as principais camadas ou módulos.
• Funcionalidades Implementadas: O conjunto de capacidades funcionais entregues pelo sistema, com descrições claras e concisas.
• Requisitos e Restrições: Os requisitos funcionais, não funcionais e técnicos que governam o comportamento e as características do sistema.
• Regras de Negócio Críticas: As lógicas de negócio essenciais que ditam o funcionamento do sistema e suas interações.
• Integrações e Dependências: Como a aplicação se conecta e interage com outros sistemas, serviços ou componentes do ecossistema.

2. Escopo de Atuação

As diretrizes aqui definidas aplicam-se à análise e documentação de repositórios que contemplem as seguintes tipologias de projetos, mas não se limitam a elas:

• APIs Backend: Serviços que expõem interfaces programáticas (e.g., RESTful, GraphQL) para consumo por outras aplicações.
• Frontends Web: Aplicações de interface de usuário acessíveis via navegadores web.
• Microfrontends: Componentes de interface de usuário independentemente deployáveis, que compõem uma aplicação maior.
• Bibliotecas Compartilhadas: Módulos de código reutilizáveis por múltiplos projetos.
• Serviços Internos: Aplicações de suporte ou processamento que operam em segundo plano, sem interface direta com o usuário final.
• Componentes de Autenticação/Autorização: Módulos responsáveis pela gestão de identidade e controle de acesso.
• Gateway/API Management: Camadas de orquestração e segurança para APIs.
• Integrações Legadas: Conexões com sistemas ou tecnologias mais antigas.

3. Artefato Documental Obrigatório

Para cada repositório analisado, o Agente de IA DEVE gerar um arquivo Markdown (.md) no caminho /docs/project-documentation.md. Este arquivo deve ser o ponto central da documentação técnica, contendo informações objetivas, verificáveis e tecnicamente aprofundadas.

4. Fluxo Operacional Detalhado para Geração de Documentação

O Agente de IA DEVE seguir rigorosamente as etapas abaixo para garantir a consistência e a qualidade da documentação gerada:

4.1. Etapa 0: Sincronização e Validação do Repositório

Antes de iniciar qualquer análise, o Agente DEVE garantir que o código-fonte local esteja atualizado e consistente com o repositório remoto. Esta etapa é crítica para evitar a documentação de estados obsoletos ou inconsistentes do projeto.

Ação: Executar o comando de sincronização:

git pull origin main

Controle de Exceção:

• Conflito de Merge: Se a execução do git pull resultar em conflitos de merge, o processo de documentação DEVE ser interrompido imediatamente. O Agente DEVE registrar formalmente o bloqueio, indicando a causa e a necessidade de intervenção humana para resolução. A documentação só poderá ser retomada após a normalização da sincronização do repositório.
• Branch main Inexistente: Caso a branch main (ou a branch principal definida pela política da organização, e.g., master) não exista no repositório remoto, o Agente DEVE registrar um bloqueio formal e seguir a política de branching da organização para identificar a branch correta ou reportar a anomalia.

4.2. Etapa 1: Análise de Requisitos Funcionais

Esta etapa visa estabelecer a fonte primária de verdade para o entendimento do domínio de negócio e das expectativas funcionais do sistema.

Ação: Verificar a existência do arquivo de requisitos funcionais no caminho /docs/requisitos.md.

Processamento:

• requisitos.md Existente: Se o arquivo for encontrado, o Agente DEVE utilizá-lo como a principal referência para extrair:
  • O objetivo macro do sistema.
  • As funcionalidades esperadas e seus comportamentos.
  • As regras de negócio que governam as operações.
  • Os fluxos críticos de usuário ou sistema.
  • As integrações planejadas ou existentes.
  • As restrições funcionais e não funcionais.
• Divergência Requisito vs. Código: Se, durante a análise subsequente do código-fonte, for identificada qualquer divergência entre o que está documentado em requisitos.md e a implementação real, o Agente DEVE registrar explicitamente essa inconsistência na documentação final, detalhando a natureza da diferença e seu impacto potencial.

4.3. Etapa 2: Classificação da Tipologia do Projeto

A classificação do projeto é fundamental para direcionar a análise técnica e a estrutura da documentação, permitindo que o Agente aplique heurísticas específicas para cada tipo.

Ação: Classificar o repositório em uma das seguintes categorias, com base na análise inicial de sua estrutura e dependências:

• Backend: Aplicações que fornecem lógica de negócio e acesso a dados (e.g., APIs RESTful, serviços de processamento).
• Frontend: Aplicações de interface de usuário (e.g., SPAs, MPAs).
• Microfrontend: Componentes de UI que operam de forma autônoma.
• Biblioteca Compartilhada: Pacotes de código reutilizáveis.
• Infraestrutura: Repositórios contendo configurações de infraestrutura (e.g., IaC, scripts de deploy).
• Segurança / Auth / Gateway: Componentes focados em autenticação, autorização ou gerenciamento de tráfego de API.

4.4. Etapa 3: Análise Aprofundada do Código-Fonte

Esta etapa envolve o mapeamento detalhado da estrutura e dos componentes internos do projeto, adaptando a profundidade da análise à tipologia previamente identificada.

Ação: Realizar uma varredura e análise estrutural do código-fonte para identificar os principais componentes e seus relacionamentos.

Processamento Específico por Tipo:

• Para Projetos Backend (e.g., Spring Boot):
  • Controllers: Mapear endpoints e suas responsabilidades (recebimento de requisições, validação de entrada).
  • Services: Identificar a lógica de negócio principal e a orquestração de operações.
  • Repositories: Entender a camada de persistência de dados e as interações com o banco de dados.
  • Entities/Models: Analisar a representação dos dados e o modelo de domínio.
  • DTOs (Data Transfer Objects): Mapear as estruturas de dados utilizadas na comunicação entre camadas ou serviços.
  • Configurations: Identificar configurações de ambiente, beans e propriedades da aplicação.
  • Security: Analisar mecanismos de autenticação, autorização e políticas de segurança.
  • Schedulers/Listeners: Identificar tarefas agendadas ou ouvintes de eventos.
  • Integrações: Mapear chamadas a serviços externos, filas de mensagens, caches, etc.
• Para Projetos Frontend (e.g., React):
  • Pages/Views: Identificar as principais telas da aplicação e seus propósitos.
  • Routes: Mapear as rotas de navegação e seus componentes associados.
  • Components: Analisar a modularização da interface, componentes reutilizáveis e sua hierarquia.
  • Hooks (React): Entender a lógica de estado e ciclo de vida encapsulada.
  • Contexts/Stores: Mapear o gerenciamento de estado global da aplicação.
  • Services/APIs: Identificar as chamadas a APIs backend e a lógica de comunicação.
  • Autenticação: Analisar o fluxo de login, gestão de tokens e sessões.
  • Guards de Rota/Middlewares: Mapear as proteções de acesso a rotas específicas.

4.5. Etapa 4: Leitura e Validação de Contratos de API

Para projetos que expõem APIs, a documentação de contrato é a fonte autoritativa para a definição de endpoints e suas especificações.

Ação: Para projetos Backend, verificar a existência de arquivos de especificação OpenAPI (e.g., openapi.json, swagger.json).

Processamento:

• Contrato OpenAPI Existente: Se um contrato OpenAPI for encontrado, o Agente DEVE tratá-lo como a fonte oficial e primária para a definição de endpoints, métodos HTTP, estruturas de request/response, parâmetros, esquemas de autenticação e agrupamentos funcionais. É proibido inferir endpoints manualmente quando uma especificação OpenAPI válida estiver disponível.
• Contrato OpenAPI Inexistente: Se nenhum contrato OpenAPI for encontrado, o Agente DEVE inferir os endpoints e suas características a partir da análise do código-fonte (e.g., anotações em controladores Spring Boot, definições de rotas em frameworks).

4.6. Etapa 5: Cruzamento e Síntese de Informações

Esta etapa consiste em consolidar todas as informações coletadas, identificando correlações, inconsistências e lacunas, para gerar uma documentação coesa e precisa.

Ação: Integrar e correlacionar dados provenientes de:

• Requisitos funcionais (/docs/requisitos.md).
• Análise do código-fonte (estrutura, componentes, lógica).
• Contratos de API (OpenAPI).
• Classificação da tipologia do projeto.

Resultado Esperado: Uma documentação que reflita a consistência entre as expectativas de negócio e a implementação técnica, destacando pontos de alinhamento e desalinhamento.

5. Estrutura Obrigatória do Documento Gerado (/docs/project-documentation.md)

O documento gerado DEVE seguir a seguinte estrutura hierárquica e de conteúdo, garantindo a completude e a padronização. Cada seção DEVE ser preenchida com detalhes técnicos e explicativos.

5.1. Visão Geral do Projeto

• Propósito: Descrever a finalidade da aplicação, o problema que ela resolve e seu valor para o negócio.
• Contexto no Ecossistema: Explicar o papel do projeto dentro da arquitetura de sistemas da organização, suas interdependências e como ele se encaixa no fluxo de valor.
• Público-Alvo/Consumidores: Identificar quem utiliza ou interage com a aplicação (usuários finais, outros sistemas, APIs).

5.2. Arquitetura Técnica

• Tipo da Aplicação: Reafirmar a classificação do projeto (e.g., API Spring Boot, Frontend React, Microfrontend, Serviço Interno).
• Stack Tecnológica: Listar as principais tecnologias, linguagens, frameworks, bibliotecas e versões utilizadas (e.g., Java 17, Spring Boot 3.x, React 18, TypeScript, PostgreSQL, Redis, RabbitMQ).
• Estrutura do Projeto: Detalhar a organização dos diretórios e arquivos, explicando a função de cada módulo ou camada (e.g., controller/, service/, repository/, dto/ para backend; src/pages, src/components, src/services para frontend).
• Fluxo Principal de Dados/Execução: Descrever, de forma técnica, como os dados ou as requisições percorrem o sistema, desde a entrada até a saída, passando pelas principais camadas e componentes.
• Integrações e Dependências Externas: Listar e descrever as integrações com sistemas externos ou serviços de terceiros (e.g., Keycloak para IAM, Kong como API Gateway, PostgreSQL como DB, RabbitMQ para mensageria, APIs internas/externas).

5.3. Funcionalidades Chave

• Listar as funcionalidades reais e implementadas do sistema, com uma breve descrição técnica para cada uma. Evitar generalizações; focar no que o código efetivamente faz (e.g., autenticação de usuários via OAuth2, gestão de campanhas de marketing com segmentação, emissão de notificações transacionais via fila de mensagens, dashboard analítico de performance de vendas, upload de arquivos para S3, consulta de relatórios financeiros).

5.4. Requisitos

• Funcionais: Detalhar os requisitos de negócio que a aplicação atende (e.g., permitir cadastro de novos usuários, consultar registros de transações, exportar dados em formato CSV, aprovar solicitações de reembolso).
• Técnicos: Especificar os requisitos técnicos e não funcionais (e.g., autenticação obrigatória para todas as APIs, paginação em todas as listagens, logs auditáveis para operações críticas, integração com SSO corporativo, validação robusta de entrada de dados).
• Operacionais: Abordar requisitos relacionados à operação e manutenção (e.g., alta disponibilidade, performance em picos de acesso, rastreabilidade de eventos, monitoramento de métricas).

5.5. Regras de Negócio

• Explicar as regras de negócio do domínio de forma clara e técnica, com foco em como elas são implementadas no código (e.g., "Somente usuários com perfil ADMIN podem executar a operação de exclusão de registros, conforme validação na camada de serviço UserService", "Um usuário inativo não possui permissão para acessar funcionalidades protegidas, verificado pelo SecurityFilter", "O status APROVADO para uma transação exige validação prévia de N critérios, orquestrada pelo TransactionManager", "Campanhas de marketing que já foram enviadas não podem ser editadas, garantido pela imutabilidade do objeto Campaign após o status SENT", "Dados sensíveis, como informações de cartão de crédito, devem ser criptografados em repouso e em trânsito, utilizando AES-256 e TLS 1.2 respectivamente").

5.6. Endpoints da API (Exclusivo para Backend)

Se houver um contrato OpenAPI, gerar uma tabela detalhada dos endpoints, agrupados por domínio funcional. A tabela DEVE incluir:

Método HTTP	Endpoint	Descrição	Requer Autenticação	Escopos/Permissões	Exemplo de Request/Response
POST	/users	Cria um novo usuário no sistema.	Sim	users:write	{ "name": "John Doe", "email": "john.doe@example.com" }
GET	/users/{id}	Consulta os detalhes de um usuário específico.	Sim	users:read	200 OK { "id": "uuid", "name": "John Doe" }
POST	/auth/login	Realiza a autenticação do usuário e retorna um token JWT.	Não	N/A	{ "username": "user", "password": "pass" }

Observação: Indicar claramente quando um endpoint exige autenticação e quais permissões ou escopos são necessários.

5.7. Rotas da Aplicação (Exclusivo para Frontend)

Mapear as rotas da aplicação frontend, incluindo:

Rota	Componente/Página	Objetivo	Requer Autenticação	Guards de Rota
/login	LoginPage	Interface para autenticação de usuários.	Não	N/A
/dashboard	DashboardPage	Painel principal com visão geral das métricas.	Sim	AuthGuard
/users/profile	UserProfilePage	Exibição e edição do perfil do usuário.	Sim	AuthGuard, ProfileOwnerGuard

5.8. Pontos Críticos para Manutenção e Evolução

Listar e descrever os riscos técnicos, tech debts ou áreas do código que exigem atenção especial durante a manutenção ou evolução. Exemplos:

• Acoplamento de DTOs: "Alterações na estrutura do DTO UserDTO no backend podem quebrar o contrato com múltiplos frontends que o consomem, exigindo coordenação de versionamento."
• Dependência de Autenticação: "A lógica de autenticação está fortemente acoplada ao Keycloak; qualquer mudança na API do Keycloak ou na estratégia de segurança pode impactar diretamente este módulo."
• Versionamento de API: "A API atual não possui um esquema de versionamento explícito, o que pode gerar breaking changes para clientes existentes em futuras atualizações."
• Processamento Assíncrono: "Mudanças na estrutura da fila de mensagens (RabbitMQQueue) ou no formato das mensagens podem impactar o processamento assíncrono de eventos, exigindo testes de regressão abrangentes."

6. Regras de Redação e Estilo

A documentação DEVE ser redigida com uma linguagem técnica e precisa, direcionada exclusivamente a desenvolvedores. As seguintes diretrizes DEVERÃO ser observadas:

• Foco Técnico: Priorizar a explicação de "como funciona", "onde alterar", "qual o impacto técnico", "quais as dependências" e "qual o fluxo de dados e riscos".
• Objetividade: Evitar linguagem executiva, gerencial ou genérica. A informação deve ser direta e relevante para a implementação.
• Diferenciação: Distinguir claramente fatos (observados no código ou requisitos) de inferências (conclusões baseadas na análise, mas não explicitamente documentadas). Se uma informação for uma inferência ou houver lacuna de contexto, isso DEVE ser explicitado (e.g., "Provavelmente, este módulo é responsável por X, mas a confirmação requer análise adicional").
• Verificabilidade: Não inventar funcionalidades ou comportamentos que não possam ser comprovados pelo código-fonte ou por documentos de requisitos.
• Consistência: Apontar explicitamente quaisquer conflitos ou desalinhamentos entre os requisitos funcionais (requisitos.md) e a implementação real do código.

7. Controle de Qualidade: Checklist de Aceite

Antes de finalizar a documentação, o Agente DEVE realizar uma autoavaliação rigorosa, utilizando o seguinte checklist:

• O código-fonte foi atualizado (git pull origin main) antes da análise?
• Os requisitos funcionais (/docs/requisitos.md) foram verificados e utilizados como fonte primária?
• O tipo de projeto foi corretamente classificado (Backend, Frontend, etc.)?
• A estrutura técnica do código-fonte foi mapeada de forma abrangente?
• Contratos de API (OpenAPI) foram verificados e priorizados para endpoints de backend?
• O arquivo de documentação foi gerado no caminho /docs/project-documentation.md?
• Todas as seções obrigatórias (Visão Geral, Arquitetura, Funcionalidades, Requisitos, Regras de Negócio) estão completas e detalhadas?
• Conflitos entre requisitos e código, e lacunas de contexto, foram explicitados?
• A linguagem utilizada é técnica, objetiva e direcionada a desenvolvedores?
• A documentação é útil para um desenvolvedor que nunca viu o sistema antes?

8. Pós-Documentação: Processo de Versionamento e Revisão

Após a conclusão e validação do arquivo /docs/project-documentation.md, o Agente DEVE iniciar o processo de versionamento e revisão, conforme as melhores práticas de desenvolvimento de software.

Ações Obrigatórias:

1. Versionamento: As alterações na documentação DEVERÃO ser versionadas em uma branch de trabalho específica (e.g., feature/docs-update-project-x).
2. Merge Request (MR): Abrir uma Merge Request (ou Pull Request) para a branch principal do repositório (main ou master, conforme a política de branching vigente).
3. Corpo da MR: O corpo da Merge Request DEVE incluir:
   • Um resumo técnico das mudanças realizadas na documentação.
   • A descrição de pontos críticos identificados durante a análise e documentação.

Controle de Exceção:

• Branch Alvo Inexistente/Acesso Negado: Se a branch alvo (main/master) não existir ou se o Agente não possuir permissões para criar uma Merge Request, DEVE registrar um bloqueio formal, reportar a evidência e aguardar a resolução manual.

9. Tratamento de Exceções e Bloqueios Formais

O Agente DEVE registrar um bloqueio formal e interromper o processo de documentação nas seguintes situações:

• Conflito de Merge: Conforme detalhado na Etapa 0.
• Ausência de Permissões: Falta de permissões para realizar operações críticas (e.g., git pull, criar Merge Request).
• Branch Alvo Indefinida: A branch principal para Merge Requests não está clara ou não existe.
• Artefatos Essenciais Indisponíveis: Requisitos (requisitos.md), contratos de API (openapi.json) ou código-fonte estão incompletos, corrompidos ou inacessíveis.

Em todos os casos de bloqueio formal, o registro DEVE conter:

• Causa Raiz: A origem do problema.
• Impacto: As consequências do bloqueio no processo de documentação.
• Ação Recomendada: Sugestões para a resolução do problema.
• Condição para Retomada: Os critérios que devem ser atendidos para que o processo de documentação possa ser reiniciado.