paulasilvatech ASP Personas do SDLC Agêntico v1.0.0
EN PT ES
05 architect · Design

Arquiteto de Software

CODEMAP e contratos de API.

Atualizado: 2026-04-24 14 seções Baixar .zip

O Software Architect é a persona que desenha o esqueleto do programa e o contrato de API. Em um SDLC AI-native, o Software Architect opera uma pilha de primitivas validadas que produz artefatos legíveis por máquina para humanos e agentes.

Resumo executivo

O Software Architect traduz requisitos aprovados em um esqueleto coerente de programa, fronteiras de módulo e contratos de API que o Developer e o QA Engineer podem executar sem ambiguidade. Em um SDLC AI-native, o Software Architect opera dentro da fase de Design com um conjunto fixo de primitivas: um agente de design de contrato de API, quatro slash prompts, instruções escopadas, hooks validados por schema e uma lista curada de MCPs validados. As saídas primárias são CODEMAP.md, arquivos de contrato de API, registros de design review e scans de domain-driven design.

Papel e responsabilidades

Pense no Software Architect como um arquiteto desenhando o chão de fábrica. Eles não operam as máquinas, mas decidem onde as máquinas ficam, como o material flui entre elas e qual interface cada máquina expõe à sua vizinha. Em um SDLC AI-native, o CODEMAP.md é a planta baixa, os contratos de API são as interfaces entre máquinas, e o Software Architect é responsável pelo fato de que o fluxo de hoje continua funcionando no próximo trimestre.

Responsabilidades primárias:

  • Escrever e manter o CODEMAP.md como o esqueleto canônico do programa para humanos e agentes
  • Desenhar e governar contratos de API sob docs/contracts/ em formato OpenAPI, AsyncAPI ou GraphQL SDL
  • Rodar design reviews com o Enterprise Architect, Technical Lead e Developer em gates definidos
  • Rodar scans de domain-driven design para detectar fronteiras vazadas e violações de agregado
  • Operar o agente API Contract Designer e os prompts /codemap, /contract, /design-review, /ddd-scan
  • Manter disciplina de compatibilidade retroativa e versionar contratos explicitamente
  • Alinhar designs com os princípios do CONSTITUTION.md e ADRs do Enterprise Architect

Jobs to be done

  1. Como Software Architect, eu quero que o CODEMAP.md se regenere a cada mudança de API pública, para que o esqueleto nunca fique defasado.
  2. Como Software Architect, eu quero que contratos de API sejam a fonte da verdade, para que implementação e testes derivem de um único documento.
  3. Como Software Architect, eu quero que design reviews sejam estruturadas e registradas, para que consequências sobrevivam à reunião.
  4. Como Software Architect, eu quero que DDD scans detectem fronteiras vazadas, para que violações de agregado sejam pegas no design, não em produção.
  5. Como Software Architect, eu quero que mudanças de contrato bloqueiem o merge em uma violação de breaking change, para que consumidores sejam protegidos pelo gate.
  6. Como Software Architect, eu quero que todo contrato aponte para os IDs de requisito que satisfaz, para que a rastreabilidade esteja intacta.

Dores antes da era AI-native

  1. Diagramas no lugar de artefatos. Caixas e setas em um deck de slides não podem ser consumidas por um agente ou gerador de testes. A implementação deriva do desenho.
  2. Contratos escritos após o fato. Implementações embarcam primeiro, contratos são reversamente engenheirados, e consumidores são surpreendidos.
  3. CODEMAP como um README que ninguém atualiza. Uma vez defasado, agentes alucinam estrutura de módulo e humanos param de ler.
  4. Disciplina de DDD apenas de cabeça. Fronteiras de agregado são lembradas, não enforçadas. Vazamentos aparecem sob carga.
  5. Breaking changes descobertas por consumidores. Sem um gate, um PR menor quebra parceiros em produção.

Fluxo diário AI-native

O Software Architect opera um loop fixo todo dia. O loop usa primitivas do GitHub Copilot dentro do Visual Studio Code e Claude Code no terminal, além de um pequeno catálogo de MCPs validados para contexto externo.

Setup da manhã

  1. Abra o repositório no Visual Studio Code. GitHub Copilot Chat carrega o AGENTS.md e as instruções escopadas de arquitetura.
  2. Puxe o último main e revise propostas noturnas de design e PRs de contrato.
  3. Rode /codemap para confirmar que o esqueleto está em sincronia com a árvore atual do código fonte.
  4. Revise o dashboard de DDD scan gerado pelo workflow agendado do GitHub Actions do /ddd-scan.

Execução no meio do dia

  1. Escrita de contrato. Invoque /contract em cada nova ou alterada superfície de API. O agente API Contract Designer produz um arquivo OpenAPI, AsyncAPI ou GraphQL SDL e o vincula aos IDs de requisito.
  2. Manutenção do CODEMAP. Invoque /codemap após qualquer mudança estrutural. O agente reescreve o mapa de módulos, a lista de superfície pública e as anotações de fluxo de dados.
  3. Design review. Invoque /design-review em propostas taggeadas com impacto arquitetural. O agente prepara a pauta a partir do diff e registra decisões contra o catálogo de ADR.
  4. DDD scan. Invoque /ddd-scan em módulos que tiveram fronteiras alteradas na última semana. O agente usa grep e glob para detectar chamadas entre agregados e value objects vazados.

Revisão no fim da tarde

  1. Rode as verificações de compatibilidade de contrato no GitHub Actions. Bloqueie o merge em qualquer breaking change sem um ADR de major-version vinculado e uma nota de migração.
  2. Abra um pull request com as mudanças em contratos e CODEMAP.md. GitHub Copilot Code Review comenta sobre consistência e risco de breaking change.
  3. Publique o digest diário de design no canal do Teams da engenharia via Microsoft 365 Agents SDK, resumindo novos contratos, contratos superados e debates de design abertos.
  4. Atualize os links de rastreabilidade de contratos para IDs de requisito e artefatos implantados via a telemetria do Azure MCP Server.

Primitivas recomendadas

Agente

AgenteArquivoPropósito
api-contract-designer.github/agents/api-contract-designer.agent.mdEscrever CODEMAP.md, contratos de API, rodar design reviews e DDD scans

O API Contract Designer usa claude-sonnet-4-6 por padrão. Ferramentas: read, edit, search, grep, glob. Sem acesso a bash no modo default. Extended thinking é habilitado apenas para /ddd-scan, onde a correlação entre módulos se beneficia de raciocínio mais profundo.

Slash prompts

ComandoArquivoPropósito
/codemap.github/prompts/codemap.prompt.mdRegenerar o CODEMAP.md com mapa de módulos, superfície pública e fluxo de dados
/contract.github/prompts/contract.prompt.mdEscrever ou revisar um contrato de API vinculado a IDs de requisito
/design-review.github/prompts/design-review.prompt.mdPreparar e registrar um design review estruturado
/ddd-scan.github/prompts/ddd-scan.prompt.mdDetectar fronteiras vazadas e violações de agregado

Instruções escopadas

applyTo com escopo reduz o custo em tokens em aproximadamente 68 por cento comparado a instruções globais.

Escopo (applyTo)ArquivoPropósito
CODEMAP.md.github/instructions/codemap.instructions.mdSchema do mapa de módulos, anotação de superfície pública, sintaxe de fluxo de dados
docs/contracts/**/*.yaml,docs/contracts/**/*.graphql.github/instructions/contracts.instructions.mdConvenções OpenAPI, AsyncAPI, GraphQL SDL e regras de compatibilidade
docs/design/**/*.md.github/instructions/design.instructions.mdTemplate de proposta de design, pauta de review, registro de decisão

Hooks

Hooks custam zero tokens de LLM. São a camada de governança mais forte para arquitetura.

  • pre-commit: rejeitar qualquer mudança de contrato sem um ID de requisito vinculado e uma classificação de compatibilidade (safe, additive, breaking)
  • post-commit: regenerar o CODEMAP.md em qualquer mudança de superfície pública
  • pre-merge: rodar o DDD scan e a verificação de compatibilidade de contrato; bloquear o merge em achados não resolvidos

MCPs validados

MCPPropósitoDono
GitHub MCP ServerLer PRs, resultados do CodeQL e runs do Actions relevantes a mudanças de contratoGitHub (oficial)
Azure MCP ServerConsultar Application Insights para vincular contratos a formas de tráfego observadas em produçãoMicrosoft (oficial)
Microsoft Learn Docs MCPAncorar designs de contrato na documentação de referência de API do Azure e Microsoft 365Microsoft (oficial)
Azure DevOps MCP ServerLer work items de arquitetura no Azure Boards quando o time usa Azure DevOpsMicrosoft (oficial)
Microsoft 365 Agents SDK MCPPublicar digests de design e ingerir decisões de design review do TeamsMicrosoft (oficial)

Exemplos reais

Exemplo 1: novo contrato para uma integração com parceiro

Entrada: Um cluster de requisitos para uma nova integração de webhook com parceiro, aprovado pelo Requirements Engineer.

Invocação: /contract seguido de /design-review.

Saída esperada:

  1. Um docs/contracts/partner-webhook/openapi.yaml com endpoints, schemas e links para IDs de requisito.
  2. Um docs/contracts/partner-webhook/asyncapi.yaml se o contrato incluir formas de evento.
  3. Um registro de design review em docs/design/reviews/2026-q3-partner-webhook.md com decisões e um link de superado-por se o novo contrato substituir um mais antigo.
  4. Um pull request com classificação de compatibilidade de contrato additive e comentários do Copilot Code Review sobre higiene de schema.

Exemplo 2: DDD scan após uma refatoração de módulo

Entrada: Um developer refatorou o módulo orders em três submódulos.

Invocação: /ddd-scan com escopo em src/orders/**.

Saída esperada:

  1. Um relatório de scan em docs/design/scans/2026-06-orders-ddd.md identificando quatro chamadas entre agregados e dois value objects vazados.
  2. Quatro issues do GitHub registradas via o GitHub MCP com plano de remediação e um engenheiro dono.
  3. Uma atualização do CODEMAP.md que anota os novos submódulos e sinaliza os vazamentos remanescentes.

Anti-padrões

  1. Contrato escrito como apêndice. Se a implementação aterrissa primeiro, contratos são reversamente engenheirados. Mitigação: o hook de pre-commit bloqueia PRs de implementação cuja superfície pública não esteja coberta em docs/contracts/.
  2. CODEMAP deriva. Um mapa defasado quebra o raciocínio do agente. Mitigação: o hook de post-commit o regenera em qualquer mudança de superfície pública.
  3. Breaking changes silenciosas. Um rename de campo enviado como safe quebra consumidores. Mitigação: o linter de contrato enforça a classificação de compatibilidade e a forma do diff.
  4. DDD de memória. Fronteiras de agregado esquecidas sob pressão de deadline vazam para persistência. Mitigação: execuções agendadas do /ddd-scan e o hook de pre-merge.
  5. Design reviews sem registros. Decisões evaporam, relitigadas no próximo trimestre. Mitigação: /design-review vincula toda decisão a uma entrada de ADR.

KPIs e métricas de impacto

KPILinha baseMetaMedição
Frescor do CODEMAP, detecção de drift4 semanas< 24 horasSaída do hook de post-commit
Contratos com IDs de requisito vinculados35 por cento100 por centoLinter de contrato no GitHub Actions
Breaking changes sinalizadas antes do merge55 por cento100 por centoSaída do hook de pre-merge
Achados de DDD scan remediados no SLA40 por cento> 90 por centoAuditoria de fechamento de issue
Tempo de ciclo de design review2 semanas< 5 diasTimestamps de PR no GitHub
Disciplina de versionamento de contrato50 por cento100 por centoAuditoria de rename de arquivo versionado

Maturidade em quatro níveis

NívelNomeMarcadores
L1ManualDiagramas em slides, contratos em wikis, CODEMAP ausente
L2AssistidoCopilot usado para polir diagramas e prosa, contratos reversamente engenheirados
L3AumentadoAgente API Contract Designer, quatro slash prompts, instruções escopadas, GitHub e Azure MCPs, CODEMAP auto-regenerado
L4AutônomoKit completo de primitivas, hooks enforçados, DDD scans agendados, digests de design automatizados, gates de compatibilidade em todos os contratos

Integração com outras personas

  • Do Enterprise Architect: princípios do CONSTITUTION.md e ADRs que restringem o design de contrato
  • Do Requirements Engineer: IDs de requisito atômicos que ancoram cláusulas de contrato
  • Para o Technical Lead: CODEMAP.md e contratos como linha base para primitivas de time e instruções escopadas
  • Para o Developer: contratos de API como fonte para o IMPLEMENTATION_PLAN.md e os testes derivados deles
  • Para o QA Engineer: contratos como fonte direta para contract tests e fuzzing de schema
  • Para o Platform Architect: superfície de contrato que serviços de plataforma devem suportar
  • Para o Tech Writer: contratos como fonte para documentação de desenvolvedor e entradas de changelog

Glossário

  • CODEMAP: documento gerado que descreve o esqueleto do programa para humanos e agentes, mantido atualizado por hooks.
  • Contrato de API: descrição legível por máquina de uma interface em forma OpenAPI, AsyncAPI ou GraphQL SDL.
  • Classificação de compatibilidade: rótulo aplicado a toda mudança de contrato como safe, additive ou breaking.
  • Design review: sessão estruturada e registrada que aprova ou adia propostas de design com participantes nomeados.
  • DDD scan: varredura automatizada que detecta chamadas entre agregados e value objects vazados.
  • Agregado: um cluster de objetos de domínio com uma única raiz e fronteira transacional, conforme domain-driven design.

Referências