Documentação do Fluxo de Trabalho de Arquitetura C4

Gere documentação abrangente de arquitetura C4 para um repositório/base de código existente usando uma abordagem de análise de baixo para cima.

[Pensamento estendido: Este fluxo de trabalho implementa um processo completo de documentação de arquitetura C4 seguindo o modelo C4 (Contexto, Container, Componente, Código). Ele usa uma abordagem de baixo para cima, começando pelos diretórios de código mais profundos e subindo, garantindo que cada elemento de código seja documentado antes de ser sintetizado em abstrações de nível superior. O fluxo de trabalho coordena quatro agentes C4 especializados (Código, Componente, Container, Contexto) para criar um conjunto completo de documentação arquitetônica que atende tanto a stakeholders técnicos quanto não técnicos.]

Use esta habilidade quando

• Trabalhando em tarefas ou fluxos de trabalho de documentação de arquitetura C4
• Precisando de orientação, melhores práticas ou checklists para o fluxo de trabalho de documentação de arquitetura C4

Não use esta habilidade quando

• A tarefa não está relacionada ao fluxo de trabalho de documentação de arquitetura C4
• Você precisa de um domínio ou ferramenta diferente fora deste escopo

Instruções

• Clarifique metas, restrições e entradas necessárias.
• Aplique melhores práticas relevantes e valide os resultados.
• Forneça etapas acionáveis e verificação.

Visão Geral

Este fluxo de trabalho cria documentação abrangente de arquitetura C4 seguindo o modelo C4 oficial por:

1. Nível de Código: Analisando cada subdiretório de baixo para cima para criar documentação em nível de código
2. Nível de Componente: Sintetizando a documentação de código em componentes lógicos dentro de containers
3. Nível de Container: Mapeando componentes para containers de implantação com documentação de API (mostra escolhas de tecnologia de alto nível)
4. Nível de Contexto: Criando contexto de sistema de alto nível com personas e jornadas de usuário (foca em pessoas e sistemas de software, não em tecnologias)

Nota: De acordo com o modelo C4, você não precisa usar todos os 4 níveis de diagrama - os diagramas de contexto do sistema e de container são suficientes para a maioria das equipes de desenvolvimento de software. Este fluxo de trabalho gera todos os níveis para completude, mas as equipes podem escolher quais níveis usar.

Toda a documentação é escrita em um novo diretório C4-Documentation/ na raiz do repositório.

Fase 1: Documentação em Nível de Código (Análise de Baixo para Cima)

1.1 Descobrir Todos os Subdiretórios

• Use a pesquisa na base de código para identificar todos os subdiretórios no repositório
• Ordene os diretórios por profundidade (mais profundos primeiro) para processamento de baixo para cima
• Filtre diretórios comuns que não são de código (node_modules, .git, build, dist, etc.)
• Crie uma lista de diretórios para processar

1.2 Processar Cada Diretório (De Baixo para Cima)

Para cada diretório, começando do mais profundo:

• Use a ferramenta Tarefa com subagent_type="c4-architecture::c4-code"

• Prompt: | Analise o código no diretório: [directory_path]

  Crie documentação abrangente em nível de Código C4 seguindo esta estrutura:

  1. Seção de Visão Geral:
     • Nome: [Nome descritivo para este diretório de código]
     • Descrição: [Breve descrição do que este código faz]
     • Localização: [Link para o caminho real do diretório em relação à raiz do repositório]
     • Linguagem: [Linguagem(ns) de programação principal(is) utilizada(s)]
     • Propósito: [O que este código realiza]
  2. Seção de Elementos de Código:
     • Documente todas as funções/métodos com assinaturas completas:
       • Nome da função, parâmetros (com tipos), tipo de retorno
       • Descrição do que cada função faz
       • Localização (caminho do arquivo e números de linha)
       • Dependências (do que esta função depende)
     • Documente todas as classes/módulos:
       • Nome da classe, descrição, localização
       • Métodos e suas assinaturas
       • Dependências
  3. Seção de Dependências:
     • Dependências internas (outro código neste repositório)
     • Dependências externas (bibliotecas, frameworks, serviços)
  4. Seção de Relacionamentos:
     • Diagrama Mermaid opcional se os relacionamentos forem complexos

  Salve a saída como: C4-Documentation/c4-code-[nome-do-diretorio].md Use um nome de diretório sanitizado (substitua / por -, remova caracteres especiais) para o nome do arquivo.

  Certifique-se de que a documentação inclua:

  • Assinaturas completas de funções com todos os parâmetros e tipos
  • Links para locais reais do código-fonte
  • Todas as dependências (internas e externas)
  • Nomes e descrições claros e descritivos

• Saída esperada: arquivo c4-code-<nome-do-diretorio>.md em C4-Documentation/

• Contexto: Todos os arquivos no diretório e seus subdiretórios

…