04 architect · Governance
Enterprise ArchitectArquiteto CorporativoArquitecto Empresarial
Constitution and ADRs.Constituição e ADRs.Constitution y ADRs.
The Enterprise Architect is the persona that authors the constitution and curates the decision record. In an AI-native SDLC, the Enterprise Architect operates a stack of validated primitives that turn principles into enforceable policy.
Executive summary
The Enterprise Architect defines the enduring architectural principles, capability model, and decision records that constrain every squad decision in the organization. In an AI-native SDLC the Enterprise Architect operates inside the Governance phase with a fixed set of primitives: one ADR authoring agent, four slash prompts, scoped instructions, schema-validated hooks, and a curated list of validated MCPs. Primary outputs are the CONSTITUTION.md, the Architecture Decision Record catalog, the capability scan report, and the principle-check gates that run on every pull request.
Role and responsibilities
Think of the Enterprise Architect like a constitutional court. They do not pass laws and they do not deliver judgments on every parking ticket, but when a case brings a principle into question, the judgment they render becomes binding precedent. In an AI-native SDLC the principles live in CONSTITUTION.md, the precedents live in ADRs under docs/adr/, and the Enterprise Architect is accountable for coherence across both.
Primary responsibilities:
- Author and maintain
CONSTITUTION.mdwith the enduring architectural principles and constraints - Curate the ADR catalog with a stable ID schema, status lifecycle, and supersession links
- Run capability scans that surface coverage, overlap, and gaps across the enterprise technology portfolio
- Govern the principle-check gate that runs on every architecture-adjacent pull request
- Operate the ADR Drafter agent and the
/constitution,/adr,/principle-check,/capability-scanprompts - Publish the quarterly architecture review to the leadership Teams channel
- Align enterprise direction with Microsoft Azure Well-Architected Framework pillars and GitHub platform standards
Jobs to be done
- As an Enterprise Architect, I want principles authored in markdown with machine-readable tags, so that gates can enforce them without me in the loop.
- As an Enterprise Architect, I want every significant decision captured as an ADR within 48 hours, so that context never evaporates with the author.
- As an Enterprise Architect, I want principle checks to run on every architecture PR, so that violations are caught before merge.
- As an Enterprise Architect, I want capability scans to surface overlap and gaps, so that portfolio rationalization is data-driven.
- As an Enterprise Architect, I want ADRs to supersede, not overwrite, so that the decision history remains auditable.
- As an Enterprise Architect, I want quarterly reviews generated from the ADR diff, so that leadership sees the direction of travel.
Pain points before AI-native
- Principles trapped in slide decks. Slides cannot be enforced by a hook or referenced by a PR comment. Compliance drifts silently.
- ADRs written after the fact. Records authored months later miss the real trade-offs and the people who made them have moved on.
- Capability portfolio invisible. Multiple teams solve the same problem with different stacks, and nobody notices until an acquisition.
- Principle checks done in review meetings. A review that catches a violation after sprint planning is weeks too late.
- Supersession as edit in place. When an ADR is overwritten, audit trail and reasoning evaporate.
AI-native daily workflow
The Enterprise 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 architecture repository in Visual Studio Code. GitHub Copilot Chat loads
AGENTS.mdand the scoped constitution instructions. - Pull the latest
main, review overnight ADR drafts, and list architecture PRs awaiting principle-check. - Run
/principle-checkacross open PRs using the GitHub MCP to surface potential violations. - Review the capability scan dashboard generated from the Azure MCP Server telemetry.
Midday execution
- ADR drafting. Invoke
/adron each decision captured in yesterday’s design conversation. The ADR Drafter agent produces a dated record with context, options, decision, and consequences. - Constitution update. Invoke
/constitutionwhen a recurring ADR pattern warrants a new principle. The agent drafts the clause, tags it, and proposes the gate expression. - Capability scan. Invoke
/capability-scanon the portfolio to detect overlap, gaps, and principle violations in production workloads. The agent uses the Azure MCP and GitHub MCP to aggregate evidence. - Principle-check consultations. Respond to squad requests in Microsoft Teams via the Microsoft 365 Agents SDK, with ADR links as the canonical citation.
Afternoon review
- Invoke
/principle-checkas the final sweep on all open architecture PRs. Block merge on unresolved principle violations, unblock with a linked ADR that either complies or explicitly supersedes. - Open a pull request on the ADR catalog and
CONSTITUTION.mdchanges. GitHub Copilot Code Review comments on clause quality and cross-references. - Regenerate the quarterly architecture review draft from the ADR diff. A post-commit hook updates the draft on every merge.
- Publish the daily architecture digest to the leadership Teams channel via the Microsoft 365 Agents SDK.
Recommended primitives
Agent
| Agent | File | Purpose |
|---|---|---|
adr-drafter | .github/agents/adr-drafter.agent.md | Draft and curate ADRs, maintain CONSTITUTION.md, run principle checks and capability scans |
The ADR Drafter uses claude-sonnet-4-6 by default. Tools: read, edit, search, grep, glob. No bash access. Extended thinking is enabled for /capability-scan only, where cross-portfolio correlation benefits from deep reasoning.
Slash prompts
| Command | File | Purpose |
|---|---|---|
/constitution | .github/prompts/constitution.prompt.md | Author or revise an enduring architectural principle |
/adr | .github/prompts/adr.prompt.md | Draft an Architecture Decision Record with context, options, decision, consequences |
/principle-check | .github/prompts/principle-check.prompt.md | Sweep open PRs for principle violations and ADR alignment |
/capability-scan | .github/prompts/capability-scan.prompt.md | Detect portfolio overlap, gaps, and principle violations in production |
Instructions scoped
Scoped applyTo reduces token cost by approximately 68 percent compared to global instructions.
Scope (applyTo) | File | Purpose |
|---|---|---|
CONSTITUTION.md | .github/instructions/constitution.instructions.md | Principle clause format, tag schema, gate expression syntax |
docs/adr/**/*.md | .github/instructions/adr.instructions.md | ADR template, status lifecycle, supersession rules |
docs/capability/**/*.md | .github/instructions/capability.instructions.md | Capability map schema and evidence requirements |
Hooks
Hooks cost zero LLM tokens. They are the strongest governance layer for enterprise architecture.
pre-commit: reject any ADR without context, options, decision, and consequences; reject any principle without a tag and a gate expressionpost-commit: regenerate the ADR index and the quarterly review draftpre-merge: run principle-check on the diff and block merge on unresolved violations unless a linked ADR supersedes
Validated MCPs
| MCP | Purpose | Owner |
|---|---|---|
| GitHub MCP Server | Read architecture PRs, ADRs, and principle-check runs across the organization | GitHub (official) |
| Azure MCP Server | Inspect production workloads, Azure Policy state, and Azure Monitor telemetry for capability scans | Microsoft (official) |
| Microsoft Learn Docs MCP | Ground principles and ADRs in the current Well-Architected Framework and Microsoft product documentation | Microsoft (official) |
| Azure DevOps MCP Server | Read Azure Boards portfolio items when the team uses Azure DevOps | Microsoft (official) |
| Microsoft 365 Agents SDK MCP | Publish digests to leadership Teams channels and ingest decisions from Outlook | Microsoft (official) |
Real examples
Example 1: author a new principle from a recurring ADR pattern
Input: Four recent ADRs independently adopted Azure Key Vault for secret storage in four different squads.
Invocation: /constitution followed by /principle-check.
Expected output:
- A new principle in
CONSTITUTION.mdtitled “Secret storage must use Azure Key Vault with managed identity”, taggedsecurity, with a gate expression that matches direct secret values in.envfiles. - Four ADR updates marking the prior decisions as instances of the new principle.
- A sweep report that flags three new violations across repositories, each filed as a GitHub issue via the GitHub MCP.
Example 2: capability scan ahead of a reorganization
Input: Leadership requests a portfolio rationalization view ahead of the fiscal planning cycle.
Invocation: /capability-scan with scope enterprise.
Expected output:
- A
docs/capability/2026-q3-scan.mdwith overlap rings for customer identity, payment processing, and document storage. - Nine principle violations in production workloads detected via the Azure MCP, each linked to the owning team and the offending resource ID.
- A summary digest posted to the leadership Teams channel via the Microsoft 365 Agents SDK.
Anti-patterns
- Principles without gates. A principle that cannot be checked is a poster. Mitigation: the
pre-commithook rejects principles without a gate expression. - ADRs edited in place. Overwriting destroys audit trail. Mitigation: supersession via a new ADR ID is the only allowed path.
- Verbal architecture reviews. If the review does not produce an ADR, the decision will be relitigated. Mitigation: every review closes by invoking
/adr. - Capability sprawl unmeasured. Without a scan, overlap grows quietly. Mitigation:
/capability-scanruns on a scheduled GitHub Actions workflow. - Principle-check as review-meeting item. Too late, too verbal. Mitigation:
pre-mergehook runs the check automatically.
KPIs and impact metrics
| KPI | Baseline | Target | Measurement |
|---|---|---|---|
| ADR cycle time, decision to merged record | 2 weeks | < 48 hours | GitHub PR timestamps |
| Principle-check PR coverage | 25 percent | 100 percent | GitHub Actions runs |
| Principles with gate expressions | 10 percent | 100 percent | Constitution linter |
| Capability scan cadence | Ad-hoc | Monthly | Scheduled GitHub Actions run |
| Principle violations remediated within SLA | 40 percent | > 90 percent | Violation issues closed |
| ADR supersession rate vs overwrite | 30 percent | 100 percent | ADR history diff audit |
Maturity in four levels
| Level | Name | Markers |
|---|---|---|
| L1 | Manual | Principles in slides, ADRs irregular, capability map verbal |
| L2 | Assisted | Copilot used to polish ADR prose, no gates, no catalog structure |
| L3 | Augmented | ADR Drafter agent, four slash prompts, scoped instructions, GitHub and Azure MCPs, principle-check on PR |
| L4 | Autonomous | Full primitives kit, hooks enforced, capability scans scheduled, quarterly review generated, supersession discipline |
Integration with other personas
- From Business Manager: OKR tree that informs principle priorities and capability coverage
- To Software Architect: principles and ADRs that constrain
CODEMAP.mdand API contract decisions - To Technical Lead: machine-readable principles that feed scoped instructions and hooks across squads
- To Platform Architect: capability scan evidence that drives platform service roadmap
- To InfoSec Officer: security principles with gate expressions that align with GitHub Advanced Security and Azure Policy
- To Compliance Auditor: ADR history as auditable decision record
- To DevOps Engineer: principle-check as a required status check on every architecture-adjacent workflow
Glossary
- Constitution: the living document of enduring architectural principles, tagged and bound to gate expressions.
- ADR: Architecture Decision Record. A dated, numbered record with context, options, decision, and consequences.
- Principle: a constraint that all squads must satisfy unless a linked ADR explicitly supersedes.
- Principle-check: automated sweep that verifies pull request changes against principle gate expressions.
- Capability scan: portfolio-wide analysis of coverage, overlap, and gaps across services.
- Supersession: the act of replacing an ADR with a new ADR that explicitly links the prior record.
References
- Azure Well-Architected Framework — pillars used as the backbone of enterprise principles
- Azure Policy documentation — policy as code that enforces principles on Azure resources
- GitHub Advanced Security documentation — security gates that align with enterprise principles
- GitHub Copilot documentation — agent mode, prompts, and instructions
- Microsoft Cloud Adoption Framework — governance patterns for enterprise architecture
O Enterprise Architect é a persona que escreve a constituição e cura o registro de decisões. Em um SDLC AI-native, o Enterprise Architect opera uma pilha de primitivas validadas que transforma princípios em política enforçável.
Resumo executivo
O Enterprise Architect define os princípios arquiteturais duradouros, o modelo de capacidades e os registros de decisão que restringem cada decisão de squad na organização. Em um SDLC AI-native, o Enterprise Architect opera dentro da fase de Governance com um conjunto fixo de primitivas: um agente de escrita de ADRs, quatro slash prompts, instruções escopadas, hooks validados por schema e uma lista curada de MCPs validados. As saídas primárias são o CONSTITUTION.md, o catálogo de Architecture Decision Records, o relatório de capability scan e os gates de principle-check que rodam em todo pull request.
Papel e responsabilidades
Pense no Enterprise Architect como um tribunal constitucional. Eles não criam leis e não julgam toda multa de trânsito, mas quando um caso coloca um princípio em questão, o julgamento que proferem se torna precedente vinculante. Em um SDLC AI-native, os princípios vivem no CONSTITUTION.md, os precedentes vivem em ADRs sob docs/adr/, e o Enterprise Architect é responsável pela coerência entre ambos.
Responsabilidades primárias:
- Escrever e manter o
CONSTITUTION.mdcom os princípios e restrições arquiteturais duradouros - Curar o catálogo de ADR com um schema de ID estável, ciclo de vida de status e links de supersessão
- Rodar capability scans que expõem cobertura, sobreposição e gaps no portfólio de tecnologia corporativa
- Governar o gate de principle-check que roda em todo pull request adjacente à arquitetura
- Operar o agente ADR Drafter e os prompts
/constitution,/adr,/principle-check,/capability-scan - Publicar o review trimestral de arquitetura no canal do Teams da liderança
- Alinhar a direção corporativa com os pilares do Microsoft Azure Well-Architected Framework e os padrões da plataforma GitHub
Jobs to be done
- Como Enterprise Architect, eu quero princípios escritos em markdown com tags legíveis por máquina, para que gates possam enforçá-los sem me ter no loop.
- Como Enterprise Architect, eu quero toda decisão significativa capturada como um ADR em até 48 horas, para que o contexto nunca evapore com o autor.
- Como Enterprise Architect, eu quero principle checks rodando em todo PR de arquitetura, para que violações sejam pegas antes do merge.
- Como Enterprise Architect, eu quero capability scans expondo sobreposição e gaps, para que a racionalização do portfólio seja orientada a dados.
- Como Enterprise Architect, eu quero que ADRs suprimam, não sobrescrevam, para que o histórico de decisões permaneça auditável.
- Como Enterprise Architect, eu quero reviews trimestrais gerados a partir do diff dos ADRs, para que a liderança veja a direção da travessia.
Dores antes da era AI-native
- Princípios presos em decks de slides. Slides não podem ser enforçados por um hook ou referenciados por um comentário de PR. O compliance deriva silenciosamente.
- ADRs escritos após o fato. Registros escritos meses depois perdem os trade-offs reais e as pessoas que os tomaram já saíram.
- Portfólio de capacidades invisível. Múltiplos times resolvem o mesmo problema com stacks diferentes, e ninguém percebe até uma aquisição.
- Principle checks feitos em reuniões de review. Um review que pega uma violação depois do planning da sprint chega semanas tarde demais.
- Supersessão como edição no lugar. Quando um ADR é sobrescrito, a trilha de auditoria e o raciocínio evaporam.
Fluxo diário AI-native
O Enterprise 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 de arquitetura no Visual Studio Code. GitHub Copilot Chat carrega o
AGENTS.mde as instruções escopadas da constituição. - Puxe o último
main, revise drafts noturnos de ADR e liste PRs de arquitetura aguardando principle-check. - Rode
/principle-checkem PRs abertos usando o GitHub MCP para expor potenciais violações. - Revise o dashboard de capability scan gerado a partir da telemetria do Azure MCP Server.
Execução no meio do dia
- Escrita de ADR. Invoque
/adrem cada decisão capturada na conversa de design de ontem. O agente ADR Drafter produz um registro datado com contexto, opções, decisão e consequências. - Atualização da constituição. Invoque
/constitutionquando um padrão recorrente de ADR justificar um novo princípio. O agente escreve a cláusula, a tagueia e propõe a expressão de gate. - Capability scan. Invoque
/capability-scansobre o portfólio para detectar sobreposição, gaps e violações de princípio em workloads de produção. O agente usa o Azure MCP e o GitHub MCP para agregar evidências. - Consultas de principle-check. Responda a pedidos de squads no Microsoft Teams via o Microsoft 365 Agents SDK, com links de ADR como citação canônica.
Revisão no fim da tarde
- Invoque
/principle-checkcomo varredura final em todos os PRs de arquitetura abertos. Bloqueie o merge em violações de princípio não resolvidas, desbloqueie com um ADR vinculado que cumpra ou explicitamente supere. - Abra um pull request com as mudanças no catálogo de ADR e
CONSTITUTION.md. GitHub Copilot Code Review comenta sobre qualidade da cláusula e cross-references. - Regenere o draft do review trimestral de arquitetura a partir do diff dos ADRs. Um hook de post-commit atualiza o draft a cada merge.
- Publique o digest diário de arquitetura no canal do Teams da liderança via Microsoft 365 Agents SDK.
Primitivas recomendadas
Agente
| Agente | Arquivo | Propósito |
|---|---|---|
adr-drafter | .github/agents/adr-drafter.agent.md | Escrever e curar ADRs, manter CONSTITUTION.md, rodar principle checks e capability scans |
O ADR Drafter usa claude-sonnet-4-6 por padrão. Ferramentas: read, edit, search, grep, glob. Sem acesso a bash. Extended thinking é habilitado apenas para /capability-scan, onde a correlação entre portfólios se beneficia de raciocínio profundo.
Slash prompts
| Comando | Arquivo | Propósito |
|---|---|---|
/constitution | .github/prompts/constitution.prompt.md | Escrever ou revisar um princípio arquitetural duradouro |
/adr | .github/prompts/adr.prompt.md | Escrever um Architecture Decision Record com contexto, opções, decisão, consequências |
/principle-check | .github/prompts/principle-check.prompt.md | Varrer PRs abertos em busca de violações de princípio e alinhamento com ADRs |
/capability-scan | .github/prompts/capability-scan.prompt.md | Detectar sobreposição, gaps e violações de princípio no portfólio em produção |
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 |
|---|---|---|
CONSTITUTION.md | .github/instructions/constitution.instructions.md | Formato da cláusula de princípio, schema de tag, sintaxe da expressão de gate |
docs/adr/**/*.md | .github/instructions/adr.instructions.md | Template de ADR, ciclo de vida de status, regras de supersessão |
docs/capability/**/*.md | .github/instructions/capability.instructions.md | Schema do mapa de capacidades e requisitos de evidência |
Hooks
Hooks custam zero tokens de LLM. São a camada de governança mais forte para arquitetura corporativa.
pre-commit: rejeitar qualquer ADR sem contexto, opções, decisão e consequências; rejeitar qualquer princípio sem tag e expressão de gatepost-commit: regenerar o índice de ADR e o draft do review trimestralpre-merge: rodar principle-check no diff e bloquear o merge em violações não resolvidas a menos que um ADR vinculado supere
MCPs validados
| MCP | Propósito | Dono |
|---|---|---|
| GitHub MCP Server | Ler PRs de arquitetura, ADRs e runs de principle-check em toda a organização | GitHub (oficial) |
| Azure MCP Server | Inspecionar workloads de produção, estado do Azure Policy e telemetria do Azure Monitor para capability scans | Microsoft (oficial) |
| Microsoft Learn Docs MCP | Ancorar princípios e ADRs no Well-Architected Framework atual e documentação de produto Microsoft | Microsoft (oficial) |
| Azure DevOps MCP Server | Ler itens de portfólio do Azure Boards quando o time usa Azure DevOps | Microsoft (oficial) |
| Microsoft 365 Agents SDK MCP | Publicar digests em canais do Teams da liderança e ingerir decisões do Outlook | Microsoft (oficial) |
Exemplos reais
Exemplo 1: escrever um novo princípio a partir de um padrão recorrente de ADR
Entrada: Quatro ADRs recentes adotaram independentemente o Azure Key Vault para armazenamento de segredos em quatro squads diferentes.
Invocação: /constitution seguido de /principle-check.
Saída esperada:
- Um novo princípio no
CONSTITUTION.mdintitulado “Armazenamento de segredos deve usar Azure Key Vault com managed identity”, taggeado comosecurity, com uma expressão de gate que detecta valores de segredo diretos em arquivos.env. - Quatro atualizações de ADR marcando as decisões anteriores como instâncias do novo princípio.
- Um relatório de varredura que sinaliza três novas violações entre repositórios, cada uma registrada como issue do GitHub via o GitHub MCP.
Exemplo 2: capability scan antes de uma reorganização
Entrada: A liderança pede uma visão de racionalização de portfólio antes do ciclo de planejamento fiscal.
Invocação: /capability-scan com escopo enterprise.
Saída esperada:
- Um
docs/capability/2026-q3-scan.mdcom anéis de sobreposição para identidade de cliente, processamento de pagamento e armazenamento de documentos. - Nove violações de princípio em workloads de produção detectadas via o Azure MCP, cada uma vinculada ao time dono e ao ID do recurso em falta.
- Um digest-resumo postado no canal do Teams da liderança via Microsoft 365 Agents SDK.
Anti-padrões
- Princípios sem gates. Um princípio que não pode ser verificado é um cartaz. Mitigação: o hook de
pre-commitrejeita princípios sem expressão de gate. - ADRs editados no lugar. Sobrescrever destrói a trilha de auditoria. Mitigação: supersessão via novo ID de ADR é o único caminho permitido.
- Reviews de arquitetura verbais. Se o review não produzir um ADR, a decisão será relitigada. Mitigação: todo review encerra invocando
/adr. - Sprawl de capacidades não medido. Sem um scan, a sobreposição cresce silenciosamente. Mitigação:
/capability-scanroda em um workflow agendado do GitHub Actions. - Principle-check como item de reunião de review. Tarde demais, verbal demais. Mitigação: o hook
pre-mergeroda a verificação automaticamente.
KPIs e métricas de impacto
| KPI | Linha base | Meta | Medição |
|---|---|---|---|
| Tempo de ciclo de ADR, decisão até registro merged | 2 semanas | < 48 horas | Timestamps de PR no GitHub |
| Cobertura de PR por principle-check | 25 por cento | 100 por cento | Runs do GitHub Actions |
| Princípios com expressões de gate | 10 por cento | 100 por cento | Linter da constituição |
| Cadência de capability scan | Ad-hoc | Mensal | Run agendado do GitHub Actions |
| Violações de princípio remediadas no SLA | 40 por cento | > 90 por cento | Issues de violação fechadas |
| Taxa de supersessão de ADR vs sobrescrita | 30 por cento | 100 por cento | Auditoria de diff do histórico de ADR |
Maturidade em quatro níveis
| Nível | Nome | Marcadores |
|---|---|---|
| L1 | Manual | Princípios em slides, ADRs irregulares, mapa de capacidades verbal |
| L2 | Assistido | Copilot usado para polir a prosa do ADR, sem gates, sem estrutura de catálogo |
| L3 | Aumentado | Agente ADR Drafter, quatro slash prompts, instruções escopadas, GitHub e Azure MCPs, principle-check em PR |
| L4 | Autônomo | Kit completo de primitivas, hooks enforçados, capability scans agendados, review trimestral gerado, disciplina de supersessão |
Integração com outras personas
- Do Business Manager: árvore de OKRs que informa prioridades de princípio e cobertura de capacidades
- Para o Software Architect: princípios e ADRs que restringem decisões de
CODEMAP.mde contratos de API - Para o Technical Lead: princípios legíveis por máquina que alimentam instruções escopadas e hooks nos squads
- Para o Platform Architect: evidência de capability scan que guia o roadmap de serviços de plataforma
- Para o InfoSec Officer: princípios de segurança com expressões de gate que se alinham com GitHub Advanced Security e Azure Policy
- Para o Compliance Auditor: histórico de ADR como registro auditável de decisões
- Para o DevOps Engineer: principle-check como status check obrigatório em todo workflow adjacente à arquitetura
Glossário
- Constituição: o documento vivo de princípios arquiteturais duradouros, taggeados e vinculados a expressões de gate.
- ADR: Architecture Decision Record. Um registro datado e numerado com contexto, opções, decisão e consequências.
- Princípio: uma restrição que todos os squads devem satisfazer a menos que um ADR vinculado explicitamente supere.
- Principle-check: varredura automatizada que verifica mudanças de pull request contra expressões de gate de princípio.
- Capability scan: análise em todo o portfólio de cobertura, sobreposição e gaps entre serviços.
- Supersessão: o ato de substituir um ADR por um novo ADR que explicitamente vincula o registro anterior.
Referências
- Azure Well-Architected Framework — pilares usados como espinha dorsal dos princípios corporativos
- Documentação do Azure Policy — policy como código que enforça princípios em recursos Azure
- Documentação do GitHub Advanced Security — gates de segurança alinhados aos princípios corporativos
- Documentação do GitHub Copilot — modo agent, prompts e instruções
- Microsoft Cloud Adoption Framework — padrões de governança para arquitetura corporativa
El Enterprise Architect es la persona que redacta la constitución y cura el registro de decisiones. En un SDLC AI-native, el Enterprise Architect opera un stack de primitivas validadas que convierten principios en política aplicable.
Resumen ejecutivo
El Enterprise Architect define los principios arquitectónicos perdurables, el modelo de capacidades y los registros de decisión que restringen cada decisión de squad en la organización. En un SDLC AI-native, el Enterprise Architect opera dentro de la fase de Governance con un conjunto fijo de primitivas: un agente de autoría de ADR, cuatro slash prompts, instrucciones con alcance, hooks validados por esquema y una lista curada de MCPs validados. Las salidas principales son el CONSTITUTION.md, el catálogo de Architecture Decision Records, el reporte de capability scan y las compuertas de principle-check que corren en cada pull request.
Rol y responsabilidades
Piensa en el Enterprise Architect como una corte constitucional. No promulgan leyes ni dictan sentencias sobre cada multa de tránsito, pero cuando un caso pone un principio en cuestión, la sentencia que dicten se vuelve precedente vinculante. En un SDLC AI-native, los principios viven en CONSTITUTION.md, los precedentes viven en ADRs bajo docs/adr/, y el Enterprise Architect es responsable de la coherencia entre ambos.
Responsabilidades principales:
- Redactar y mantener
CONSTITUTION.mdcon los principios y restricciones arquitectónicas perdurables - Curar el catálogo de ADR con un esquema de IDs estable, ciclo de vida de estado y enlaces de supersesión
- Correr capability scans que afloran cobertura, traslape y brechas a través del portafolio de tecnología empresarial
- Gobernar la compuerta de principle-check que corre en cada pull request adyacente a la arquitectura
- Operar el agente ADR Drafter y los prompts
/constitution,/adr,/principle-check,/capability-scan - Publicar la revisión arquitectónica trimestral al canal de liderazgo de Teams
- Alinear la dirección empresarial con los pilares del Microsoft Azure Well-Architected Framework y los estándares de la plataforma GitHub
Jobs to be done
- Como Enterprise Architect, quiero principios redactados en markdown con tags legibles por máquina, para que las compuertas puedan imponerlos sin que yo esté en el loop.
- Como Enterprise Architect, quiero cada decisión significativa capturada como un ADR dentro de 48 horas, para que el contexto nunca se evapore con el autor.
- Como Enterprise Architect, quiero que los principle checks corran en cada PR de arquitectura, para que las violaciones se detecten antes del merge.
- Como Enterprise Architect, quiero que los capability scans afloran traslape y brechas, para que la racionalización del portafolio se base en datos.
- Como Enterprise Architect, quiero que los ADRs se superseden, no se sobrescriban, para que la historia de decisiones permanezca auditable.
- Como Enterprise Architect, quiero revisiones trimestrales generadas a partir del diff de ADR, para que el liderazgo vea la dirección de avance.
Puntos de dolor antes de la era AI-native
- Principios atrapados en mazos de diapositivas. Las diapositivas no pueden ser impuestas por un hook ni referenciadas por un comentario en PR. El cumplimiento deriva en silencio.
- ADRs escritos a posteriori. Los registros redactados meses después pierden las verdaderas concesiones, y las personas que las hicieron ya se fueron.
- Portafolio de capacidades invisible. Múltiples equipos resuelven el mismo problema con stacks distintos, y nadie lo nota hasta una adquisición.
- Principle checks hechos en reuniones de revisión. Una revisión que detecta una violación después del sprint planning llega semanas tarde.
- Supersesión como edición en sitio. Cuando un ADR se sobrescribe, el rastro de auditoría y el razonamiento se evaporan.
Flujo diario AI-native
El Enterprise 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 de arquitectura en Visual Studio Code. GitHub Copilot Chat carga
AGENTS.mdy las instrucciones de constitución con alcance. - Hacer pull del último
main, revisar borradores de ADR nocturnos y listar PRs de arquitectura en espera de principle-check. - Ejecutar
/principle-checksobre los PRs abiertos usando el MCP de GitHub para aflorar potenciales violaciones. - Revisar el dashboard de capability scan generado a partir de la telemetría del Azure MCP Server.
Ejecución al mediodía
- Redacción de ADR. Invocar
/adrsobre cada decisión capturada en la conversación de diseño de ayer. El agente ADR Drafter produce un registro fechado con contexto, opciones, decisión y consecuencias. - Actualización de la constitución. Invocar
/constitutioncuando un patrón recurrente de ADR amerite un nuevo principio. El agente redacta la cláusula, la etiqueta y propone la expresión de la compuerta. - Capability scan. Invocar
/capability-scansobre el portafolio para detectar traslape, brechas y violaciones de principios en cargas de trabajo de producción. El agente usa el Azure MCP y el GitHub MCP para agregar evidencia. - Consultas de principle-check. Responder a solicitudes de squads en Microsoft Teams a través del Microsoft 365 Agents SDK, con enlaces a ADR como cita canónica.
Revisión al final de la tarde
- Invocar
/principle-checkcomo barrida final en todos los PRs de arquitectura abiertos. Bloquear el merge en violaciones de principio sin resolver, desbloquear con un ADR enlazado que cumpla o explícitamente supersede. - Abrir un pull request sobre los cambios al catálogo de ADR y a
CONSTITUTION.md. GitHub Copilot Code Review comenta sobre la calidad de las cláusulas y las referencias cruzadas. - Regenerar el borrador de la revisión arquitectónica trimestral a partir del diff de ADR. Un hook post-commit actualiza el borrador en cada merge.
- Publicar el digest diario de arquitectura al canal de liderazgo de Teams a través del Microsoft 365 Agents SDK.
Primitivas recomendadas
Agente
| Agente | Archivo | Propósito |
|---|---|---|
adr-drafter | .github/agents/adr-drafter.agent.md | Redactar y curar ADRs, mantener CONSTITUTION.md, correr principle checks y capability scans |
El ADR Drafter usa claude-sonnet-4-6 por defecto. Herramientas: read, edit, search, grep, glob. Sin acceso a bash. El extended thinking se habilita solo para /capability-scan, donde la correlación a través del portafolio se beneficia de un razonamiento profundo.
Slash prompts
| Comando | Archivo | Propósito |
|---|---|---|
/constitution | .github/prompts/constitution.prompt.md | Redactar o revisar un principio arquitectónico perdurable |
/adr | .github/prompts/adr.prompt.md | Redactar un Architecture Decision Record con contexto, opciones, decisión y consecuencias |
/principle-check | .github/prompts/principle-check.prompt.md | Barrer PRs abiertos por violaciones de principio y alineación con ADR |
/capability-scan | .github/prompts/capability-scan.prompt.md | Detectar traslape, brechas y violaciones de principio en producción |
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 |
|---|---|---|
CONSTITUTION.md | .github/instructions/constitution.instructions.md | Formato de cláusula de principio, esquema de tags, sintaxis de expresiones de compuerta |
docs/adr/**/*.md | .github/instructions/adr.instructions.md | Plantilla de ADR, ciclo de vida de estado, reglas de supersesión |
docs/capability/**/*.md | .github/instructions/capability.instructions.md | Esquema del mapa de capacidades y requisitos de evidencia |
Hooks
Los hooks cuestan cero tokens de LLM. Son la capa de gobierno más fuerte para la arquitectura empresarial.
pre-commit: rechazar cualquier ADR sin contexto, opciones, decisión y consecuencias; rechazar cualquier principio sin tag y expresión de compuertapost-commit: regenerar el índice de ADR y el borrador de revisión trimestralpre-merge: correr principle-check sobre el diff y bloquear el merge en violaciones sin resolver salvo que un ADR enlazado supersede
MCPs validados
| MCP | Propósito | Dueño |
|---|---|---|
| GitHub MCP Server | Leer PRs de arquitectura, ADRs y corridas de principle-check a través de la organización | GitHub (oficial) |
| Azure MCP Server | Inspeccionar cargas de trabajo en producción, estado de Azure Policy y telemetría de Azure Monitor para capability scans | Microsoft (oficial) |
| Microsoft Learn Docs MCP | Anclar principios y ADRs en el Well-Architected Framework vigente y la documentación de productos Microsoft | Microsoft (oficial) |
| Azure DevOps MCP Server | Leer ítems de portafolio de Azure Boards cuando el equipo usa Azure DevOps | Microsoft (oficial) |
| Microsoft 365 Agents SDK MCP | Publicar digests a canales de liderazgo en Teams e ingerir decisiones desde Outlook | Microsoft (oficial) |
Ejemplos reales
Ejemplo 1: redactar un nuevo principio a partir de un patrón recurrente de ADR
Entrada: Cuatro ADRs recientes adoptaron de forma independiente Azure Key Vault para almacenamiento de secretos en cuatro squads distintas.
Invocación: /constitution seguido de /principle-check.
Salida esperada:
- Un nuevo principio en
CONSTITUTION.mdtitulado “El almacenamiento de secretos debe usar Azure Key Vault con managed identity”, etiquetadosecurity, con una expresión de compuerta que detecta valores de secreto directos en archivos.env. - Cuatro actualizaciones de ADR marcando las decisiones previas como instancias del nuevo principio.
- Un reporte de barrida que marca tres nuevas violaciones a través de los repositorios, cada una presentada como un GitHub issue vía el MCP de GitHub.
Ejemplo 2: capability scan antes de una reorganización
Entrada: El liderazgo solicita una vista de racionalización del portafolio antes del ciclo de planeación fiscal.
Invocación: /capability-scan con alcance enterprise.
Salida esperada:
- Un
docs/capability/2026-q3-scan.mdcon anillos de traslape para identidad de cliente, procesamiento de pagos y almacenamiento de documentos. - Nueve violaciones de principio en cargas de trabajo de producción detectadas vía el Azure MCP, cada una enlazada al equipo dueño y al ID del recurso infractor.
- Un digest resumen publicado en el canal de liderazgo de Teams a través del Microsoft 365 Agents SDK.
Anti-patrones
- Principios sin compuertas. Un principio que no se puede chequear es un póster. Mitigación: el hook
pre-commitrechaza principios sin expresión de compuerta. - ADRs editados en sitio. Sobrescribir destruye el rastro de auditoría. Mitigación: la supersesión vía un nuevo ID de ADR es la única ruta permitida.
- Revisiones de arquitectura verbales. Si la revisión no produce un ADR, la decisión será relitigada. Mitigación: cada revisión cierra invocando
/adr. - Sprawl de capacidades sin medir. Sin un escaneo, el traslape crece en silencio. Mitigación:
/capability-scancorre en un workflow programado de GitHub Actions. - Principle-check como ítem de reunión de revisión. Demasiado tarde, demasiado verbal. Mitigación: el hook
pre-mergecorre el chequeo automáticamente.
KPIs y métricas de impacto
| KPI | Línea base | Meta | Medición |
|---|---|---|---|
| Tiempo de ciclo de ADR, de decisión a registro fusionado | 2 semanas | < 48 horas | Timestamps de PR de GitHub |
| Cobertura de principle-check en PR | 25 por ciento | 100 por ciento | Corridas de GitHub Actions |
| Principios con expresiones de compuerta | 10 por ciento | 100 por ciento | Linter de la constitución |
| Cadencia de capability scan | Ad-hoc | Mensual | Corrida programada de GitHub Actions |
| Violaciones de principio remediadas dentro del SLA | 40 por ciento | > 90 por ciento | Issues de violación cerrados |
| Tasa de supersesión de ADR vs sobrescritura | 30 por ciento | 100 por ciento | Auditoría de diff del historial de ADR |
Madurez en cuatro niveles
| Nivel | Nombre | Marcadores |
|---|---|---|
| L1 | Manual | Principios en diapositivas, ADRs irregulares, mapa de capacidades verbal |
| L2 | Asistido | Copilot usado para pulir prosa de ADR, sin compuertas, sin estructura de catálogo |
| L3 | Aumentado | Agente ADR Drafter, cuatro slash prompts, instrucciones con alcance, MCPs de GitHub y Azure, principle-check en PR |
| L4 | Autónomo | Kit completo de primitivas, hooks forzados, capability scans programados, revisión trimestral generada, disciplina de supersesión |
Integración con otras personas
- Desde Business Manager: árbol de OKR que informa las prioridades de principio y la cobertura de capacidades
- Hacia Software Architect: principios y ADRs que restringen las decisiones de
CODEMAP.mdy los contratos de API - Hacia Technical Lead: principios legibles por máquina que alimentan instrucciones con alcance y hooks a través de squads
- Hacia Platform Architect: evidencia de capability scan que dirige la hoja de ruta de servicios de plataforma
- Hacia InfoSec Officer: principios de seguridad con expresiones de compuerta que se alinean con GitHub Advanced Security y Azure Policy
- Hacia Compliance Auditor: historial de ADR como registro de decisiones auditable
- Hacia DevOps Engineer: principle-check como check de estado requerido en cada workflow adyacente a la arquitectura
Glosario
- Constitution: el documento vivo de principios arquitectónicos perdurables, etiquetados y amarrados a expresiones de compuerta.
- ADR: Architecture Decision Record. Un registro fechado y numerado con contexto, opciones, decisión y consecuencias.
- Principio: una restricción que todas las squads deben satisfacer salvo que un ADR enlazado lo supersede explícitamente.
- Principle-check: barrida automatizada que verifica los cambios de pull request contra las expresiones de compuerta de principios.
- Capability scan: análisis de cobertura, traslape y brechas a nivel de portafolio a través de los servicios.
- Supersesión: el acto de reemplazar un ADR con un nuevo ADR que enlaza explícitamente al registro previo.
Referencias
- Azure Well-Architected Framework — pilares usados como columna vertebral de los principios empresariales
- Azure Policy documentation — políticas como código que imponen principios sobre recursos de Azure
- GitHub Advanced Security documentation — compuertas de seguridad alineadas con principios empresariales
- GitHub Copilot documentation — agent mode, prompts e instructions
- Microsoft Cloud Adoption Framework — patrones de gobierno para arquitectura empresarial