05 architect · Design
Software ArchitectArquiteto de SoftwareArquitecto de Software
CODEMAP and API contracts.CODEMAP e contratos de API.CODEMAP y contratos de API.
The Software Architect is the persona that designs the program skeleton and the API contract. In an AI-native SDLC, the Software Architect operates a stack of validated primitives that produce machine-readable artifacts for humans and agents.
Executive summary
The Software Architect translates approved requirements into a coherent program skeleton, module boundaries, and API contracts that the Developer and QA Engineer can execute without ambiguity. In an AI-native SDLC the Software Architect operates inside the Design phase with a fixed set of primitives: one API contract design agent, four slash prompts, scoped instructions, schema-validated hooks, and a curated list of validated MCPs. Primary outputs are CODEMAP.md, API contract files, design review records, and domain-driven design scans.
Role and responsibilities
Think of the Software Architect like an architect designing a factory floor. They do not operate the machines, but they decide where the machines stand, how material flows between them, and what interface each machine exposes to its neighbor. In an AI-native SDLC CODEMAP.md is the floor plan, API contracts are the interfaces between machines, and the Software Architect is accountable for the fact that today’s flow still works next quarter.
Primary responsibilities:
- Author and maintain
CODEMAP.mdas the canonical program skeleton for humans and agents - Design and govern API contracts under
docs/contracts/in OpenAPI, AsyncAPI, or GraphQL SDL form - Run design reviews with the Enterprise Architect, Technical Lead, and Developer at defined gates
- Run domain-driven design scans to detect leaky boundaries and aggregate violations
- Operate the API Contract Designer agent and the
/codemap,/contract,/design-review,/ddd-scanprompts - Maintain backward compatibility discipline and version contracts explicitly
- Align designs with the
CONSTITUTION.mdprinciples and ADRs from the Enterprise Architect
Jobs to be done
- As a Software Architect, I want
CODEMAP.mdto regenerate on every public API change, so that the skeleton is never stale. - As a Software Architect, I want API contracts to be the source of truth, so that implementation and tests derive from a single document.
- As a Software Architect, I want design reviews to be structured and recorded, so that consequences outlive the meeting.
- As a Software Architect, I want DDD scans to detect leaky boundaries, so that aggregate violations are caught in design, not production.
- As a Software Architect, I want contract changes to block merge on a breaking-change violation, so that consumers are protected by the gate.
- As a Software Architect, I want every contract to link to the requirement IDs it satisfies, so that traceability is intact.
Pain points before AI-native
- Diagrams over artifacts. Boxes and arrows in a slide deck cannot be consumed by an agent or a test generator. Implementation drifts from the picture.
- Contracts authored after the fact. Implementations ship first, contracts are reverse-engineered, and consumers are surprised.
- CODEMAP as a README that no one updates. Once stale, agents hallucinate module structure and humans stop reading.
- DDD discipline by heart only. Aggregate boundaries are remembered, not enforced. Leaks appear under load.
- Breaking changes discovered by consumers. Without a gate, a minor PR breaks partners in production.
AI-native daily workflow
The Software Architect operates a fixed loop each day. The loop uses GitHub Copilot primitives inside Visual Studio Code and Claude Code at the terminal, plus a small catalog of validated MCPs for external context.
Morning setup
- Open the repository in Visual Studio Code. GitHub Copilot Chat loads
AGENTS.mdand the scoped architecture instructions. - Pull the latest
mainand review overnight design proposals and contract PRs. - Run
/codemapto confirm the skeleton is in sync with the current source tree. - Review the DDD scan dashboard generated by the
/ddd-scanscheduled GitHub Actions workflow.
Midday execution
- Contract authoring. Invoke
/contracton each new or changed API surface. The API Contract Designer agent produces an OpenAPI, AsyncAPI, or GraphQL SDL file and links it to the requirement IDs. - CODEMAP maintenance. Invoke
/codemapafter any structural change. The agent rewrites the module map, public surface list, and data-flow annotations. - Design review. Invoke
/design-reviewon proposals tagged for architectural impact. The agent prepares the agenda from the diff and records decisions against the ADR catalog. - DDD scan. Invoke
/ddd-scanon modules that changed boundaries in the last week. The agent usesgrepandglobto detect cross-aggregate calls and leaked value objects.
Afternoon review
- Run contract compatibility checks in GitHub Actions. Block merge on any breaking change without a linked major-version ADR and a migration note.
- Open a pull request on the contract and
CODEMAP.mdchanges. GitHub Copilot Code Review comments on consistency and breaking-change risk. - Publish the daily design digest to the engineering Teams channel via the Microsoft 365 Agents SDK, summarizing new contracts, superseded contracts, and open design debates.
- Update the traceability links from contracts to requirement IDs and deployed artifacts via the Azure MCP Server telemetry.
Recommended primitives
Agent
| Agent | File | Purpose |
|---|---|---|
api-contract-designer | .github/agents/api-contract-designer.agent.md | Author CODEMAP.md, API contracts, run design reviews and DDD scans |
The API Contract Designer uses claude-sonnet-4-6 by default. Tools: read, edit, search, grep, glob. No bash access in the default mode. Extended thinking is enabled for /ddd-scan only, where cross-module correlation benefits from deeper reasoning.
Slash prompts
| Command | File | Purpose |
|---|---|---|
/codemap | .github/prompts/codemap.prompt.md | Regenerate CODEMAP.md with module map, public surface, and data flow |
/contract | .github/prompts/contract.prompt.md | Author or revise an API contract linked to requirement IDs |
/design-review | .github/prompts/design-review.prompt.md | Prepare and record a structured design review |
/ddd-scan | .github/prompts/ddd-scan.prompt.md | Detect leaky boundaries and aggregate violations |
Instructions scoped
Scoped applyTo reduces token cost by approximately 68 percent compared to global instructions.
Scope (applyTo) | File | Purpose |
|---|---|---|
CODEMAP.md | .github/instructions/codemap.instructions.md | Module map schema, public surface annotation, data-flow syntax |
docs/contracts/**/*.yaml,docs/contracts/**/*.graphql | .github/instructions/contracts.instructions.md | OpenAPI, AsyncAPI, GraphQL SDL conventions and compatibility rules |
docs/design/**/*.md | .github/instructions/design.instructions.md | Design proposal template, review agenda, decision record |
Hooks
Hooks cost zero LLM tokens. They are the strongest governance layer for architecture.
pre-commit: reject any contract change without a linked requirement ID and a compatibility classification (safe,additive,breaking)post-commit: regenerateCODEMAP.mdon any public surface changepre-merge: run the DDD scan and the contract compatibility check; block merge on unresolved findings
Validated MCPs
| MCP | Purpose | Owner |
|---|---|---|
| GitHub MCP Server | Read PRs, CodeQL results, and Actions runs relevant to contract changes | GitHub (official) |
| Azure MCP Server | Query Application Insights to bind contracts to observed production traffic shapes | Microsoft (official) |
| Microsoft Learn Docs MCP | Ground contract designs on Azure and Microsoft 365 API reference documentation | Microsoft (official) |
| Azure DevOps MCP Server | Read architecture work items in Azure Boards when the team uses Azure DevOps | Microsoft (official) |
| Microsoft 365 Agents SDK MCP | Publish design digests and ingest design-review decisions from Teams | Microsoft (official) |
Real examples
Example 1: new contract for a partner integration
Input: A requirement cluster for a new partner webhook integration, approved by the Requirements Engineer.
Invocation: /contract followed by /design-review.
Expected output:
- A
docs/contracts/partner-webhook/openapi.yamlwith endpoints, schemas, and links to requirement IDs. - A
docs/contracts/partner-webhook/asyncapi.yamlif the contract includes event shapes. - A design review record in
docs/design/reviews/2026-q3-partner-webhook.mdwith decisions and a superseded-by link if the new contract replaces an older one. - A pull request with contract compatibility classification
additiveand Copilot Code Review comments on schema hygiene.
Example 2: DDD scan after a module refactor
Input: A developer refactored the orders module into three submodules.
Invocation: /ddd-scan scoped to src/orders/**.
Expected output:
- A scan report in
docs/design/scans/2026-06-orders-ddd.mdidentifying four cross-aggregate calls and two leaked value objects. - Four GitHub issues filed via the GitHub MCP with a remediation plan and an owning engineer.
- A
CODEMAP.mdupdate that annotates the new submodules and flags the remaining leaks.
Anti-patterns
- Contract authored as an afterthought. If implementation lands first, contracts are reverse-engineered. Mitigation: the
pre-commithook blocks implementation PRs whose public surface is not covered indocs/contracts/. - CODEMAP drifts. A stale map breaks agent reasoning. Mitigation:
post-commithook regenerates it on any public surface change. - Silent breaking changes. A field rename shipped as
safebreaks consumers. Mitigation: contract linter enforces compatibility classification and diff shape. - DDD by memory. Aggregate boundaries forgotten under deadline pressure leak into persistence. Mitigation: scheduled
/ddd-scanruns and thepre-mergehook. - Design reviews without records. Decisions evaporate, relitigated next quarter. Mitigation:
/design-reviewbinds every decision to an ADR entry.
KPIs and impact metrics
| KPI | Baseline | Target | Measurement |
|---|---|---|---|
| CODEMAP freshness, drift detection | 4 weeks | < 24 hours | Post-commit hook output |
| Contracts with linked requirement IDs | 35 percent | 100 percent | Contract linter in GitHub Actions |
| Breaking changes flagged before merge | 55 percent | 100 percent | Pre-merge hook output |
| DDD scan findings remediated within SLA | 40 percent | > 90 percent | Issue closure audit |
| Design review cycle time | 2 weeks | < 5 days | GitHub PR timestamps |
| Contract versioning discipline | 50 percent | 100 percent | Versioned file rename audit |
Maturity in four levels
| Level | Name | Markers |
|---|---|---|
| L1 | Manual | Diagrams in slides, contracts in wikis, CODEMAP absent |
| L2 | Assisted | Copilot used to polish diagrams and prose, contracts reverse-engineered |
| L3 | Augmented | API Contract Designer agent, four slash prompts, scoped instructions, GitHub and Azure MCPs, CODEMAP auto-regenerated |
| L4 | Autonomous | Full primitives kit, hooks enforced, DDD scans scheduled, design digests automated, compatibility gates across all contracts |
Integration with other personas
- From Enterprise Architect:
CONSTITUTION.mdprinciples and ADRs that constrain contract design - From Requirements Engineer: atomic requirement IDs that anchor contract clauses
- To Technical Lead:
CODEMAP.mdand contracts as the baseline for team primitives and scoped instructions - To Developer: API contracts as the source for
IMPLEMENTATION_PLAN.mdand the tests derived from them - To QA Engineer: contracts as direct source for contract tests and schema fuzzing
- To Platform Architect: contract surface that platform services must support
- To Tech Writer: contracts as the source for developer documentation and changelog entries
Glossary
- CODEMAP: generated document that describes the program skeleton for humans and agents, kept current by hooks.
- API contract: machine-readable description of an interface in OpenAPI, AsyncAPI, or GraphQL SDL form.
- Compatibility classification: label applied to every contract change as
safe,additive, orbreaking. - Design review: structured, recorded session that approves or defers design proposals with named participants.
- DDD scan: automated sweep that detects cross-aggregate calls and leaked value objects.
- Aggregate: a cluster of domain objects with a single root and transactional boundary, per domain-driven design.
References
- GitHub Copilot documentation — agent mode, prompts, and instructions
- Azure API Design guidance — canonical Microsoft guidance on API contract quality
- Azure Well-Architected Framework — reliability and operational excellence pillars for architectural alignment
- CodeQL documentation — static analysis that underpins breaking-change detection
- GitHub Actions documentation — automation for contract and DDD scans on every PR
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.mdcomo 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.mde ADRs do Enterprise Architect
Jobs to be done
- Como Software Architect, eu quero que o
CODEMAP.mdse regenere a cada mudança de API pública, para que o esqueleto nunca fique defasado. - 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.
- Como Software Architect, eu quero que design reviews sejam estruturadas e registradas, para que consequências sobrevivam à reunião.
- 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.
- 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.
- 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
- 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.
- Contratos escritos após o fato. Implementações embarcam primeiro, contratos são reversamente engenheirados, e consumidores são surpreendidos.
- CODEMAP como um README que ninguém atualiza. Uma vez defasado, agentes alucinam estrutura de módulo e humanos param de ler.
- Disciplina de DDD apenas de cabeça. Fronteiras de agregado são lembradas, não enforçadas. Vazamentos aparecem sob carga.
- 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ã
- Abra o repositório no Visual Studio Code. GitHub Copilot Chat carrega o
AGENTS.mde as instruções escopadas de arquitetura. - Puxe o último
maine revise propostas noturnas de design e PRs de contrato. - Rode
/codemappara confirmar que o esqueleto está em sincronia com a árvore atual do código fonte. - Revise o dashboard de DDD scan gerado pelo workflow agendado do GitHub Actions do
/ddd-scan.
Execução no meio do dia
- Escrita de contrato. Invoque
/contractem 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. - Manutenção do CODEMAP. Invoque
/codemapapó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. - Design review. Invoque
/design-reviewem propostas taggeadas com impacto arquitetural. O agente prepara a pauta a partir do diff e registra decisões contra o catálogo de ADR. - DDD scan. Invoque
/ddd-scanem módulos que tiveram fronteiras alteradas na última semana. O agente usagrepeglobpara detectar chamadas entre agregados e value objects vazados.
Revisão no fim da tarde
- 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.
- 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. - 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.
- Atualize os links de rastreabilidade de contratos para IDs de requisito e artefatos implantados via a telemetria do Azure MCP Server.
Primitivas recomendadas
Agente
| Agente | Arquivo | Propósito |
|---|---|---|
api-contract-designer | .github/agents/api-contract-designer.agent.md | Escrever 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
| Comando | Arquivo | Propósito |
|---|---|---|
/codemap | .github/prompts/codemap.prompt.md | Regenerar o CODEMAP.md com mapa de módulos, superfície pública e fluxo de dados |
/contract | .github/prompts/contract.prompt.md | Escrever ou revisar um contrato de API vinculado a IDs de requisito |
/design-review | .github/prompts/design-review.prompt.md | Preparar e registrar um design review estruturado |
/ddd-scan | .github/prompts/ddd-scan.prompt.md | Detectar 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) | Arquivo | Propósito |
|---|---|---|
CODEMAP.md | .github/instructions/codemap.instructions.md | Schema 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.md | Convenções OpenAPI, AsyncAPI, GraphQL SDL e regras de compatibilidade |
docs/design/**/*.md | .github/instructions/design.instructions.md | Template 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 oCODEMAP.mdem qualquer mudança de superfície públicapre-merge: rodar o DDD scan e a verificação de compatibilidade de contrato; bloquear o merge em achados não resolvidos
MCPs validados
| MCP | Propósito | Dono |
|---|---|---|
| GitHub MCP Server | Ler PRs, resultados do CodeQL e runs do Actions relevantes a mudanças de contrato | GitHub (oficial) |
| Azure MCP Server | Consultar Application Insights para vincular contratos a formas de tráfego observadas em produção | Microsoft (oficial) |
| Microsoft Learn Docs MCP | Ancorar designs de contrato na documentação de referência de API do Azure e Microsoft 365 | Microsoft (oficial) |
| Azure DevOps MCP Server | Ler work items de arquitetura no Azure Boards quando o time usa Azure DevOps | Microsoft (oficial) |
| Microsoft 365 Agents SDK MCP | Publicar digests de design e ingerir decisões de design review do Teams | Microsoft (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:
- Um
docs/contracts/partner-webhook/openapi.yamlcom endpoints, schemas e links para IDs de requisito. - Um
docs/contracts/partner-webhook/asyncapi.yamlse o contrato incluir formas de evento. - Um registro de design review em
docs/design/reviews/2026-q3-partner-webhook.mdcom decisões e um link de superado-por se o novo contrato substituir um mais antigo. - Um pull request com classificação de compatibilidade de contrato
additivee 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:
- Um relatório de scan em
docs/design/scans/2026-06-orders-ddd.mdidentificando quatro chamadas entre agregados e dois value objects vazados. - Quatro issues do GitHub registradas via o GitHub MCP com plano de remediação e um engenheiro dono.
- Uma atualização do
CODEMAP.mdque anota os novos submódulos e sinaliza os vazamentos remanescentes.
Anti-padrões
- Contrato escrito como apêndice. Se a implementação aterrissa primeiro, contratos são reversamente engenheirados. Mitigação: o hook de
pre-commitbloqueia PRs de implementação cuja superfície pública não esteja coberta emdocs/contracts/. - CODEMAP deriva. Um mapa defasado quebra o raciocínio do agente. Mitigação: o hook de
post-commito regenera em qualquer mudança de superfície pública. - Breaking changes silenciosas. Um rename de campo enviado como
safequebra consumidores. Mitigação: o linter de contrato enforça a classificação de compatibilidade e a forma do diff. - DDD de memória. Fronteiras de agregado esquecidas sob pressão de deadline vazam para persistência. Mitigação: execuções agendadas do
/ddd-scane o hook depre-merge. - Design reviews sem registros. Decisões evaporam, relitigadas no próximo trimestre. Mitigação:
/design-reviewvincula toda decisão a uma entrada de ADR.
KPIs e métricas de impacto
| KPI | Linha base | Meta | Medição |
|---|---|---|---|
| Frescor do CODEMAP, detecção de drift | 4 semanas | < 24 horas | Saída do hook de post-commit |
| Contratos com IDs de requisito vinculados | 35 por cento | 100 por cento | Linter de contrato no GitHub Actions |
| Breaking changes sinalizadas antes do merge | 55 por cento | 100 por cento | Saída do hook de pre-merge |
| Achados de DDD scan remediados no SLA | 40 por cento | > 90 por cento | Auditoria de fechamento de issue |
| Tempo de ciclo de design review | 2 semanas | < 5 dias | Timestamps de PR no GitHub |
| Disciplina de versionamento de contrato | 50 por cento | 100 por cento | Auditoria de rename de arquivo versionado |
Maturidade em quatro níveis
| Nível | Nome | Marcadores |
|---|---|---|
| L1 | Manual | Diagramas em slides, contratos em wikis, CODEMAP ausente |
| L2 | Assistido | Copilot usado para polir diagramas e prosa, contratos reversamente engenheirados |
| L3 | Aumentado | Agente API Contract Designer, quatro slash prompts, instruções escopadas, GitHub e Azure MCPs, CODEMAP auto-regenerado |
| L4 | Autônomo | Kit 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.mde 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.mde contratos como linha base para primitivas de time e instruções escopadas - Para o Developer: contratos de API como fonte para o
IMPLEMENTATION_PLAN.mde 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,additiveoubreaking. - 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
- Documentação do GitHub Copilot — modo agent, prompts e instruções
- Orientação de Azure API Design — guia canônico da Microsoft sobre qualidade de contrato de API
- Azure Well-Architected Framework — pilares de confiabilidade e excelência operacional para alinhamento arquitetural
- Documentação do CodeQL — análise estática que sustenta a detecção de breaking change
- Documentação do GitHub Actions — automação para scans de contrato e DDD em todo PR
El Software Architect es la persona que diseña el esqueleto del programa y el contrato de API. En un SDLC AI-native, el Software Architect opera un stack de primitivas validadas que producen artefactos legibles por máquina para humanos y agentes.
Resumen ejecutivo
El Software Architect traduce los requisitos aprobados en un esqueleto de programa coherente, fronteras de módulo y contratos de API que el Developer y el QA Engineer pueden ejecutar sin ambigüedad. En un SDLC AI-native, el Software Architect opera dentro de la fase de Design con un conjunto fijo de primitivas: un agente de diseño de contrato de API, cuatro slash prompts, instrucciones con alcance, hooks validados por esquema y una lista curada de MCPs validados. Las salidas principales son CODEMAP.md, archivos de contrato de API, registros de design review y escaneos de domain-driven design.
Rol y responsabilidades
Piensa en el Software Architect como un arquitecto que diseña el piso de una fábrica. No operan las máquinas, pero deciden dónde se paran, cómo fluye el material entre ellas y qué interfaz expone cada máquina a su vecina. En un SDLC AI-native, CODEMAP.md es el plano de planta, los contratos de API son las interfaces entre máquinas, y el Software Architect es responsable de que el flujo de hoy siga funcionando el próximo trimestre.
Responsabilidades principales:
- Redactar y mantener
CODEMAP.mdcomo el esqueleto de programa canónico para humanos y agentes - Diseñar y gobernar los contratos de API bajo
docs/contracts/en forma de OpenAPI, AsyncAPI o GraphQL SDL - Correr design reviews con el Enterprise Architect, el Technical Lead y el Developer en compuertas definidas
- Correr escaneos de domain-driven design para detectar fronteras con fugas y violaciones de agregados
- Operar el agente API Contract Designer y los prompts
/codemap,/contract,/design-review,/ddd-scan - Mantener disciplina de retrocompatibilidad y versionar los contratos de forma explícita
- Alinear los diseños con los principios de
CONSTITUTION.mdy los ADRs del Enterprise Architect
Jobs to be done
- Como Software Architect, quiero que
CODEMAP.mdse regenere en cada cambio de API pública, para que el esqueleto nunca quede obsoleto. - Como Software Architect, quiero que los contratos de API sean la fuente de verdad, para que la implementación y las pruebas se deriven de un solo documento.
- Como Software Architect, quiero que las design reviews sean estructuradas y registradas, para que las consecuencias sobrevivan a la reunión.
- Como Software Architect, quiero que los DDD scans detecten fronteras con fugas, para que las violaciones de agregado se detecten en diseño, no en producción.
- Como Software Architect, quiero que los cambios de contrato bloqueen el merge ante una violación de breaking change, para que los consumidores estén protegidos por la compuerta.
- Como Software Architect, quiero que cada contrato enlace a los IDs de requisito que satisface, para que la trazabilidad permanezca intacta.
Puntos de dolor antes de la era AI-native
- Diagramas sobre artefactos. Cajas y flechas en un mazo de diapositivas no pueden ser consumidas por un agente o un generador de pruebas. La implementación deriva de la imagen.
- Contratos escritos a posteriori. Las implementaciones envían primero, los contratos se aplican por ingeniería inversa, y los consumidores se sorprenden.
- CODEMAP como un README que nadie actualiza. Una vez obsoleto, los agentes alucinan la estructura de módulos y los humanos dejan de leerlo.
- Disciplina DDD solo de memoria. Las fronteras de agregado se recuerdan, no se imponen. Las fugas aparecen bajo carga.
- Breaking changes descubiertos por consumidores. Sin una compuerta, un PR menor rompe a partners en producción.
Flujo diario AI-native
El Software Architect opera un loop fijo cada día. El loop usa primitivas de GitHub Copilot dentro de Visual Studio Code y Claude Code en la terminal, además de un pequeño catálogo de MCPs validados para contexto externo.
Setup de la mañana
- Abrir el repositorio en Visual Studio Code. GitHub Copilot Chat carga
AGENTS.mdy las instrucciones de arquitectura con alcance. - Hacer pull del último
mainy revisar las propuestas de diseño nocturnas y los PRs de contrato. - Ejecutar
/codemappara confirmar que el esqueleto esté en sincronía con el árbol de fuente actual. - Revisar el dashboard de DDD scan generado por el workflow programado de GitHub Actions de
/ddd-scan.
Ejecución al mediodía
- Autoría de contrato. Invocar
/contractsobre cada superficie de API nueva o modificada. El agente API Contract Designer produce un archivo de OpenAPI, AsyncAPI o GraphQL SDL y lo enlaza a los IDs de requisito. - Mantenimiento de CODEMAP. Invocar
/codemapdespués de cualquier cambio estructural. El agente reescribe el mapa de módulos, la lista de superficie pública y las anotaciones de flujo de datos. - Design review. Invocar
/design-reviewsobre las propuestas etiquetadas con impacto arquitectónico. El agente prepara la agenda a partir del diff y registra decisiones contra el catálogo de ADR. - DDD scan. Invocar
/ddd-scansobre los módulos que cambiaron fronteras en la última semana. El agente usagrepyglobpara detectar llamadas entre agregados y value objects con fuga.
Revisión al final de la tarde
- Correr chequeos de compatibilidad de contrato en GitHub Actions. Bloquear el merge en cualquier breaking change sin un ADR de versión mayor enlazado y una nota de migración.
- Abrir un pull request sobre los cambios de contrato y
CODEMAP.md. GitHub Copilot Code Review comenta sobre consistencia y riesgo de breaking change. - Publicar el digest diario de diseño al canal de ingeniería en Teams a través del Microsoft 365 Agents SDK, resumiendo nuevos contratos, contratos superseded y debates de diseño abiertos.
- Actualizar los enlaces de trazabilidad desde contratos hacia IDs de requisito y artefactos desplegados vía la telemetría del Azure MCP Server.
Primitivas recomendadas
Agente
| Agente | Archivo | Propósito |
|---|---|---|
api-contract-designer | .github/agents/api-contract-designer.agent.md | Redactar CODEMAP.md, contratos de API, correr design reviews y DDD scans |
El API Contract Designer usa claude-sonnet-4-6 por defecto. Herramientas: read, edit, search, grep, glob. Sin acceso a bash en el modo por defecto. El extended thinking se habilita solo para /ddd-scan, donde la correlación entre módulos se beneficia de un razonamiento más profundo.
Slash prompts
| Comando | Archivo | Propósito |
|---|---|---|
/codemap | .github/prompts/codemap.prompt.md | Regenerar CODEMAP.md con mapa de módulos, superficie pública y flujo de datos |
/contract | .github/prompts/contract.prompt.md | Redactar o revisar un contrato de API enlazado a IDs de requisito |
/design-review | .github/prompts/design-review.prompt.md | Preparar y registrar un design review estructurado |
/ddd-scan | .github/prompts/ddd-scan.prompt.md | Detectar fronteras con fugas y violaciones de agregado |
Instrucciones con alcance
El applyTo con alcance reduce el costo en tokens en aproximadamente 68 por ciento comparado con instrucciones globales.
Alcance (applyTo) | Archivo | Propósito |
|---|---|---|
CODEMAP.md | .github/instructions/codemap.instructions.md | Esquema del mapa de módulos, anotación de superficie pública, sintaxis de flujo de datos |
docs/contracts/**/*.yaml,docs/contracts/**/*.graphql | .github/instructions/contracts.instructions.md | Convenciones de OpenAPI, AsyncAPI, GraphQL SDL y reglas de compatibilidad |
docs/design/**/*.md | .github/instructions/design.instructions.md | Plantilla de propuesta de diseño, agenda de revisión, registro de decisión |
Hooks
Los hooks cuestan cero tokens de LLM. Son la capa de gobierno más fuerte para la arquitectura.
pre-commit: rechazar cualquier cambio de contrato sin un ID de requisito enlazado y una clasificación de compatibilidad (safe,additive,breaking)post-commit: regenerarCODEMAP.mden cualquier cambio de superficie públicapre-merge: correr el DDD scan y el chequeo de compatibilidad de contrato; bloquear el merge en hallazgos sin resolver
MCPs validados
| MCP | Propósito | Dueño |
|---|---|---|
| GitHub MCP Server | Leer PRs, resultados de CodeQL y corridas de Actions relevantes a cambios de contrato | GitHub (oficial) |
| Azure MCP Server | Consultar Application Insights para amarrar contratos a las formas de tráfico observadas en producción | Microsoft (oficial) |
| Microsoft Learn Docs MCP | Anclar diseños de contrato en la documentación de referencia de APIs de Azure y Microsoft 365 | Microsoft (oficial) |
| Azure DevOps MCP Server | Leer work items de arquitectura en Azure Boards cuando el equipo usa Azure DevOps | Microsoft (oficial) |
| Microsoft 365 Agents SDK MCP | Publicar digests de diseño e ingerir decisiones de design review desde Teams | Microsoft (oficial) |
Ejemplos reales
Ejemplo 1: nuevo contrato para una integración con partner
Entrada: Un cluster de requisitos para una nueva integración de webhook con partner, aprobado por el Requirements Engineer.
Invocación: /contract seguido de /design-review.
Salida esperada:
- Un
docs/contracts/partner-webhook/openapi.yamlcon endpoints, esquemas y enlaces a IDs de requisito. - Un
docs/contracts/partner-webhook/asyncapi.yamlsi el contrato incluye formas de evento. - Un registro de design review en
docs/design/reviews/2026-q3-partner-webhook.mdcon decisiones y un enlace de superseded-by si el nuevo contrato reemplaza uno más antiguo. - Un pull request con clasificación de compatibilidad de contrato
additivey comentarios de Copilot Code Review sobre higiene de esquema.
Ejemplo 2: DDD scan tras una refactorización de módulo
Entrada: Un developer refactorizó el módulo orders en tres submódulos.
Invocación: /ddd-scan con alcance src/orders/**.
Salida esperada:
- Un reporte de escaneo en
docs/design/scans/2026-06-orders-ddd.mdque identifica cuatro llamadas entre agregados y dos value objects con fuga. - Cuatro GitHub issues presentados vía el MCP de GitHub con un plan de remediación y un ingeniero dueño.
- Una actualización de
CODEMAP.mdque anota los nuevos submódulos y marca las fugas restantes.
Anti-patrones
- Contrato redactado como ocurrencia tardía. Si la implementación llega primero, los contratos se construyen por ingeniería inversa. Mitigación: el hook
pre-commitbloquea PRs de implementación cuya superficie pública no esté cubierta endocs/contracts/. - CODEMAP que deriva. Un mapa obsoleto rompe el razonamiento del agente. Mitigación: el hook
post-commitlo regenera en cualquier cambio de superficie pública. - Breaking changes silenciosos. Un rename de campo enviado como
saferompe consumidores. Mitigación: el linter de contrato impone la clasificación de compatibilidad y la forma del diff. - DDD de memoria. Las fronteras de agregado olvidadas bajo presión de fecha límite tienen fugas hacia la persistencia. Mitigación: corridas programadas de
/ddd-scany el hookpre-merge. - Design reviews sin registros. Las decisiones se evaporan, se relitigan el siguiente trimestre. Mitigación:
/design-reviewamarra cada decisión a una entrada en el ADR.
KPIs y métricas de impacto
| KPI | Línea base | Meta | Medición |
|---|---|---|---|
| Frescura de CODEMAP, detección de drift | 4 semanas | < 24 horas | Salida del hook post-commit |
| Contratos con IDs de requisito enlazados | 35 por ciento | 100 por ciento | Linter de contrato en GitHub Actions |
| Breaking changes marcados antes del merge | 55 por ciento | 100 por ciento | Salida del hook pre-merge |
| Hallazgos de DDD scan remediados dentro del SLA | 40 por ciento | > 90 por ciento | Auditoría de cierre de issues |
| Tiempo de ciclo de design review | 2 semanas | < 5 días | Timestamps de PR de GitHub |
| Disciplina de versionado de contrato | 50 por ciento | 100 por ciento | Auditoría de rename de archivos versionados |
Madurez en cuatro niveles
| Nivel | Nombre | Marcadores |
|---|---|---|
| L1 | Manual | Diagramas en diapositivas, contratos en wikis, CODEMAP ausente |
| L2 | Asistido | Copilot usado para pulir diagramas y prosa, contratos por ingeniería inversa |
| L3 | Aumentado | Agente API Contract Designer, cuatro slash prompts, instrucciones con alcance, MCPs de GitHub y Azure, CODEMAP auto-regenerado |
| L4 | Autónomo | Kit completo de primitivas, hooks forzados, DDD scans programados, digests de diseño automatizados, compuertas de compatibilidad sobre todos los contratos |
Integración con otras personas
- Desde Enterprise Architect: principios de
CONSTITUTION.mdy ADRs que restringen el diseño de contrato - Desde Requirements Engineer: IDs de requisito atómicos que anclan las cláusulas del contrato
- Hacia Technical Lead:
CODEMAP.mdy contratos como línea base para las primitivas de equipo y las instrucciones con alcance - Hacia Developer: contratos de API como fuente para
IMPLEMENTATION_PLAN.mdy las pruebas derivadas de ellos - Hacia QA Engineer: contratos como fuente directa para pruebas de contrato y fuzzing de esquema
- Hacia Platform Architect: superficie de contrato que los servicios de plataforma deben soportar
- Hacia Tech Writer: contratos como fuente para la documentación de developers y entradas de changelog
Glosario
- CODEMAP: documento generado que describe el esqueleto de programa para humanos y agentes, mantenido vigente por hooks.
- Contrato de API: descripción legible por máquina de una interfaz en forma de OpenAPI, AsyncAPI o GraphQL SDL.
- Clasificación de compatibilidad: etiqueta aplicada a cada cambio de contrato como
safe,additiveobreaking. - Design review: sesión estructurada y registrada que aprueba o difiere propuestas de diseño con participantes nombrados.
- DDD scan: barrida automatizada que detecta llamadas entre agregados y value objects con fuga.
- Agregado: un cluster de objetos de dominio con una raíz única y frontera transaccional, según domain-driven design.
Referencias
- GitHub Copilot documentation — agent mode, prompts e instructions
- Azure API Design guidance — guía canónica de Microsoft sobre calidad de contratos de API
- Azure Well-Architected Framework — pilares de confiabilidad y excelencia operativa para alineación arquitectónica
- CodeQL documentation — análisis estático que sustenta la detección de breaking changes
- GitHub Actions documentation — automatización para escaneos de contrato y DDD en cada PR