Platform ArchitectArquiteto de PlataformaArquitecto de Plataforma
Golden paths and IDP.Golden paths e IDP.Golden paths e IDP.
The Platform Architect is the persona that designs the paved roads every team walks on. In an AI-native SDLC, the Platform Architect operates a stack of validated primitives, not a wiki full of aspirational diagrams.
Executive summary
The Platform Architect owns the Internal Developer Platform: the golden path templates, the capability matrix, and the architectural decision records that shape how every team builds. In an AI-native SDLC, the Platform Architect operates inside the Platform phase with a fixed set of primitives: one platform agent, four slash prompts, scoped instructions, schema-validated hooks, and a curated list of validated MCPs. The platform is delivered as a Backstage-style catalog backed by Azure DevOps and GitHub Enterprise, with Bicep-based service templates, GitHub reusable workflows, and Azure Policy initiatives. The primary outputs are template repositories, capability matrices, ADRs, and a measurable developer experience.
Role and responsibilities
Think of the Platform Architect like a city planner. The planner does not build the buildings; the planner defines the streets, utilities, zoning, and building codes that allow thousands of builders to work in parallel without the city collapsing. The planner’s success is measured not by the number of buildings they designed, but by the time it takes a new builder to break ground with confidence. In an AI-native SDLC, the city is the Internal Developer Platform, the streets are GitHub Actions reusable workflows, the utilities are Azure shared services, and the zoning is Azure Policy.
Primary responsibilities:
- Define and maintain the golden path templates for every service archetype (API, worker, front-end, data pipeline)
- Operate the Backstage-style catalog backed by Azure DevOps and GitHub Enterprise
- Author and govern architectural decision records in a central ADR repo
- Maintain the capability matrix that maps business domains to platform primitives
- Set the policy initiative in Azure Policy that applies to every subscription in scope
- Sponsor the validated MCP catalog and the agent governance model
- Operate the Path Keeper agent and the
/golden-path,/template-new,/adr-platform,/capability-matrixprompts
Jobs to be done
- As a Platform Architect, I want a new service repo created from a golden path template in minutes, so that teams start on the paved road.
- As a Platform Architect, I want every service to declare its capabilities in a machine-readable matrix, so that platform evolution is data-driven.
- As a Platform Architect, I want ADRs to be drafted from design conversations, so that the decision record is never skipped.
- As a Platform Architect, I want templates versioned and rolled forward via automated PRs, so that the paved road stays paved.
- As a Platform Architect, I want platform usage telemetry to flow into Application Insights, so that unused capabilities are retired, not accumulated.
- As a Platform Architect, I want the MCP catalog to be enforced at commit time, so that teams cannot install rogue MCPs.
Pain points before AI-native
- Templates rot. The scaffolding repo has not been updated in 14 months. New services start on the old road.
- ADRs are optional. Decisions are made in calls, documented later, or not at all. Context evaporates in six months.
- Capability matrix is a spreadsheet. Nobody updates it; nobody trusts it.
- Policy sprawl. Each subscription grows its own Azure Policy definitions. Compliance reports are contradictory.
- MCP free-for-all. Every team installs the MCP of the week. Supply-chain surface area explodes.
AI-native daily workflow
The Platform 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 platform monorepo in Visual Studio Code. GitHub Copilot Chat loads
AGENTS.mdand the scoped.github/instructions/*.instructions.mdfor templates and ADRs. - In Claude Code, run a daily report that queries the GitHub MCP for template usage, template drift PRs, and ADR review queue.
- Review the capability matrix for any service that fell out of compliance overnight (driven by Azure Policy and GitHub Advanced Security).
- Triage the inbound template requests in Azure Boards.
Midday execution
Each midday cycle is a single platform change, typically 2 to 4 hours of focused work.
- Golden path. Invoke
/golden-pathwith an archetype (API, worker, front-end, data). The Path Keeper agent composes the template from Bicep modules, GitHub reusable workflows, and the validated MCP catalog. - Template change. Invoke
/template-newto version the template, open a rollout PR fleet across consuming repos, and attach a migration guide. - ADR. Invoke
/adr-platformto draft an ADR from the design meeting transcript. The agent fills the EARS constraints, the options considered, and the decision rationale. - Capability matrix. Invoke
/capability-matrixto refresh the domain-to-primitive map from the service catalog index. - Pull request. The PR description is composed from the ADR and the template diff. GitHub Copilot Code Review scans for policy drift.
Afternoon governance
- Run a weekly template drift report in Azure Monitor. Services more than two minor versions behind are flagged.
- Publish the capability matrix snapshot to the Microsoft 365 SharePoint site for the platform review meeting.
- Hand off infrastructure changes to the DevOps Engineer; hand off security posture changes to the InfoSec Officer.
Recommended primitives
Agents
| Agent | File | Purpose |
|---|---|---|
path-keeper | .github/agents/path-keeper.agent.md | Author golden paths, govern templates, draft ADRs, maintain the capability matrix |
The Path Keeper agent uses claude-sonnet-4-6 by default. It holds tools read, edit, search, grep, glob, bash, and MCP bindings to GitHub MCP Server and Azure DevOps MCP Server for catalog traversal.
Prompts
| Command | File | Purpose |
|---|---|---|
/golden-path | .github/prompts/golden-path.prompt.md | Compose a new golden path template for a service archetype |
/template-new | .github/prompts/template-new.prompt.md | Version a template and open the rollout PR fleet |
/adr-platform | .github/prompts/adr-platform.prompt.md | Draft an ADR from a design meeting transcript or specification |
/capability-matrix | .github/prompts/capability-matrix.prompt.md | Refresh the domain-to-primitive capability matrix |
Instructions
Scoped applyTo reduces token cost by approximately 68 percent compared to global instructions.
Scope (applyTo) | File | Purpose |
|---|---|---|
templates/**/* | .github/instructions/templates.instructions.md | Template parameter schema, README structure, upgrade path |
adr/**/*.md | .github/instructions/adr.instructions.md | ADR format: context, options, decision, consequences |
catalog/**/*.yaml | .github/instructions/catalog.instructions.md | Catalog schema, ownership, lifecycle |
Skills
Skills are lazy-loaded, so the Platform Architect can install many and pay tokens only for the ones that trigger.
template-drift-scan: calls GitHub MCP to list consuming repos still on old template versionsmcp-catalog-enforcer: refuses PRs that add MCPs not present in the validated catalog
Hooks
Hooks cost zero LLM tokens. They are the strongest governance layer.
pre-commit: validate template parameter schema and ADR front matterpre-merge: verify template version bump and migration guide on any template changepost-merge: open rollout PRs across consuming repos via the GitHub MCP
Validated MCPs
Every MCP below is registered in the MCP catalog. Do not reference any MCP that is not in the catalog.
| MCP | Status | Use in this persona |
|---|---|---|
| GitHub MCP Server | Official | Catalog traversal, template rollout PRs, usage telemetry |
| Azure DevOps MCP Server | Official (Microsoft) | Read intake tickets, update Azure Boards, manage pipeline templates |
| Azure MCP Server | Official (Microsoft) | Query Azure Policy initiatives and resource group inventories |
| Microsoft Learn Docs MCP | Official | Fetch Azure Well-Architected Framework and Azure reference guidance during ADR drafting |
| Microsoft 365 Agents SDK MCP | Official (Microsoft) | Publish capability matrix snapshots and ADR notifications into Teams and SharePoint |
| Playwright MCP | Official (Microsoft) | Validate that golden path templates bootstrap working end-to-end smoke tests |
Real examples
Scenario A: launch a new API golden path
Input: The org decides that every new internal API must use Azure API Management, Entra ID auth, and a Bicep-deployed App Service. No other archetype is allowed for internal APIs.
Invocation: /golden-path with archetype internal-api.
Expected output:
- A template repo
template-internal-apiwith Bicep module, GitHub Actions reusable workflow, Entra ID app registration skeleton, and OpenAPI scaffold. - An Azure Policy initiative that denies any App Service created outside this template.
- An ADR
adr/0042-internal-api-golden-path.mdrecording the decision, options considered, and consequences. - A capability matrix update linking the
internal-apiarchetype to the shared APIM instance.
Scenario B: roll forward a breaking template change
Input: The org upgrades the standard .NET runtime from 8 to 9. Every service using the API golden path must upgrade.
Invocation: /template-new with the template version bump.
Expected output:
- A new template version
template-internal-api@2.0.0with the runtime bumped and a migration guide. - A fleet of PRs opened by the Path Keeper agent across every consuming repo, each with the migration diff and a link to the ADR.
- A drift dashboard in Application Insights that shows adoption over time, published to the platform review meeting.
Anti-patterns
- Template as wiki page. A markdown page that describes the golden path without a scaffolding engine. Mitigation: every golden path is a real template repo with parameters and tests.
- ADRs written after the fact. Decisions are documented months later, if at all. Mitigation:
/adr-platformdrafts from the design meeting transcript during the meeting. - Manual capability matrix. A spreadsheet that nobody updates. Mitigation:
/capability-matrixregenerates from the catalog YAML. - MCP free-for-all. Teams install any MCP they find. Mitigation:
mcp-catalog-enforcerskill refuses PRs that reference uncatalogued MCPs. - Policy per subscription. Each subscription grows its own Azure Policy tree. Mitigation: a single initiative owned by the Platform Architect, assigned at the management group.
KPIs and impact metrics
The Platform Architect persona is evaluated with a mix of platform engineering and developer experience metrics.
| Metric | Baseline (manual) | Target (agentic) | Measurement |
|---|---|---|---|
| Time to first commit for a new service | 2 weeks | < 1 day | Time from intake to first merged PR |
| Template adoption rate | 40 percent | > 90 percent | Percent of services on the latest golden path |
| ADR coverage | 20 percent | > 95 percent | Percent of architecture decisions with a linked ADR |
| Capability matrix freshness | Quarterly | Weekly | Days since last refresh |
| Platform NPS from developers | Unknown | > 40 | Quarterly survey |
| Policy compliance | 70 percent | > 98 percent | Azure Policy compliance score |
| MCP catalog drift | Unmeasured | 0 uncatalogued MCPs | Repo scan |
| Token efficiency | N/A | < 300k tokens per template version | Copilot usage report |
Maturity in four levels
| Level | Name | Markers |
|---|---|---|
| L1 | Manual | Scaffolding is a wiki page, ADRs optional, policies per subscription |
| L2 | Assisted | Template repo exists but drifts, GitHub Copilot helps draft ADRs occasionally |
| L3 | Augmented | One Path Keeper agent, four slash prompts, scoped instructions, two MCPs, template rollout automated |
| L4 | Agentic | Full primitives kit, hooks enforced, MCP catalog enforced, capability matrix refreshed weekly, ADR coverage > 95 percent |
Integration with other personas
Handoffs:
- From Enterprise Architect: target architecture, reference patterns, investment themes
- From Software Architect: service-level ADRs that bubble up to platform decisions
- To DevOps Engineer: reusable workflows, Bicep modules, policy initiatives
- To Developer: scaffolded repo, scoped instructions, validated MCP catalog
- To InfoSec Officer: policy initiative, MCP catalog, Entra ID app registration skeleton
Glossary
- Agent: a configured LLM role with tools, instructions, and a defined output shape.
- Prompt: a reusable slash command that invokes an agent with a specific task.
- Instructions: scoped guidance applied by pattern match on file paths via
applyTo. - Skill: a lazy-loaded capability that activates on keyword match.
- Hook: a zero-token rule enforced at a specific lifecycle event.
- MCP: Model Context Protocol server that exposes external systems to the agent.
- Golden path: the paved road every team is expected to use; deviation requires an ADR.
- IDP: Internal Developer Platform; the system that makes the golden path easy to follow.
- ADR: Architectural Decision Record; a dated markdown file that captures context, options, decision, consequences.
- Capability matrix: a machine-readable map from business domain to platform primitive.
References
- Azure Well-Architected Framework — the reference for platform design decisions
- GitHub Enterprise documentation — the platform on which the IDP is built
- Azure DevOps documentation — templates, pipelines, boards
- Azure Policy documentation — initiatives, assignments, remediation
- Backstage documentation — the catalog pattern the IDP follows
- Model Context Protocol specification — the protocol that binds agents to external systems
- Team Topologies — the organizational model behind platform teams
O Platform Architect é a persona que desenha as estradas pavimentadas por onde todos os times passam. Em um SDLC AI-native, o Platform Architect opera uma pilha de primitivas validadas, não um wiki cheio de diagramas aspiracionais.
Resumo executivo
O Platform Architect é dono do Internal Developer Platform: os templates de golden path, a matriz de capacidades e os registros de decisão arquitetural que moldam como todo time constrói. Em um SDLC AI-native, o Platform Architect opera dentro da fase de Platform com um conjunto fixo de primitivas: um agente de plataforma, quatro slash prompts, instruções escopadas, hooks validados por schema e uma lista curada de MCPs validados. A plataforma é entregue como um catálogo estilo Backstage com backing de Azure DevOps e GitHub Enterprise, com templates de serviço baseados em Bicep, reusable workflows do GitHub e initiatives do Azure Policy. As saídas primárias são repositórios de template, matrizes de capacidade, ADRs e uma experiência de desenvolvedor mensurável.
Papel e responsabilidades
Pense no Platform Architect como um urbanista. O urbanista não constrói os prédios; o urbanista define as ruas, utilidades, zoneamento e códigos de construção que permitem a milhares de construtores trabalharem em paralelo sem a cidade desabar. O sucesso do urbanista não é medido pelo número de prédios que desenhou, mas pelo tempo que leva para um novo construtor colocar o primeiro tijolo com confiança. Em um SDLC AI-native, a cidade é o Internal Developer Platform, as ruas são reusable workflows do GitHub Actions, as utilidades são serviços compartilhados do Azure e o zoneamento é Azure Policy.
Responsabilidades primárias:
- Definir e manter os templates de golden path para cada arquétipo de serviço (API, worker, front-end, data pipeline)
- Operar o catálogo estilo Backstage com backing de Azure DevOps e GitHub Enterprise
- Escrever e governar registros de decisão arquitetural em um repo central de ADRs
- Manter a matriz de capacidades que mapeia domínios de negócio para primitivas de plataforma
- Definir a initiative de policy no Azure Policy que se aplica a toda assinatura no escopo
- Patrocinar o catálogo de MCPs validados e o modelo de governança de agentes
- Operar o agente Path Keeper e os prompts
/golden-path,/template-new,/adr-platform,/capability-matrix
Jobs to be done
- Como Platform Architect, eu quero um novo repo de serviço criado a partir de um template de golden path em minutos, para que os times comecem na estrada pavimentada.
- Como Platform Architect, eu quero que todo serviço declare suas capacidades em uma matriz legível por máquina, para que a evolução da plataforma seja guiada por dados.
- Como Platform Architect, eu quero que ADRs sejam rascunhados a partir de conversas de design, para que o registro de decisão nunca seja pulado.
- Como Platform Architect, eu quero templates versionados e atualizados via PRs automatizados, para que a estrada pavimentada continue pavimentada.
- Como Platform Architect, eu quero que telemetria de uso da plataforma flua para o Application Insights, para que capacidades não usadas sejam aposentadas, não acumuladas.
- Como Platform Architect, eu quero que o catálogo de MCPs seja aplicado no commit, para que times não instalem MCPs piratas.
Dores antes da era AI-native
- Templates apodrecem. O repo de scaffolding não é atualizado há 14 meses. Novos serviços começam na estrada velha.
- ADRs são opcionais. Decisões são tomadas em calls, documentadas depois, ou nunca. O contexto evapora em seis meses.
- Matriz de capacidades é uma planilha. Ninguém atualiza; ninguém confia.
- Sprawl de policy. Cada assinatura cria suas próprias definições de Azure Policy. Relatórios de compliance ficam contraditórios.
- MCP liberação geral. Cada time instala o MCP da semana. A superfície de ataque de supply-chain explode.
Fluxo diário AI-native
O Platform 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 monorepo de plataforma no Visual Studio Code. GitHub Copilot Chat carrega o
AGENTS.mde os.github/instructions/*.instructions.mdescopados para templates e ADRs. - No Claude Code, rode um relatório diário que consulta o GitHub MCP para uso de templates, PRs de drift de template e fila de review de ADRs.
- Revise a matriz de capacidades para qualquer serviço que caiu em não-compliance durante a madrugada (guiado por Azure Policy e GitHub Advanced Security).
- Faça triage de pedidos de template entrantes no Azure Boards.
Execução no meio do dia
Cada ciclo de meio de dia é uma única mudança de plataforma, tipicamente 2 a 4 horas de trabalho focado.
- Golden path. Invoque
/golden-pathcom um arquétipo (API, worker, front-end, data). O agente Path Keeper compõe o template a partir de módulos Bicep, reusable workflows do GitHub e do catálogo de MCPs validados. - Mudança de template. Invoque
/template-newpara versionar o template, abrir uma frota de PRs de rollout nos repos consumidores e anexar um guia de migração. - ADR. Invoque
/adr-platformpara rascunhar um ADR a partir do transcript da reunião de design. O agente preenche as restrições EARS, as opções consideradas e o racional da decisão. - Matriz de capacidades. Invoque
/capability-matrixpara atualizar o mapa domínio-para-primitiva a partir do índice do catálogo de serviços. - Pull request. A descrição do PR é composta a partir do ADR e do diff do template. GitHub Copilot Code Review escaneia em busca de drift de policy.
Governança no fim da tarde
- Rode um relatório semanal de drift de template no Azure Monitor. Serviços mais de duas versões menores atrás são sinalizados.
- Publique o snapshot da matriz de capacidades no site Microsoft 365 SharePoint para a reunião de review de plataforma.
- Entregue mudanças de infraestrutura ao DevOps Engineer; entregue mudanças de postura de segurança ao InfoSec Officer.
Primitivas recomendadas
Agentes
| Agente | Arquivo | Propósito |
|---|---|---|
path-keeper | .github/agents/path-keeper.agent.md | Escrever golden paths, governar templates, rascunhar ADRs, manter a matriz de capacidades |
O agente Path Keeper usa claude-sonnet-4-6 por padrão. Ele carrega ferramentas read, edit, search, grep, glob, bash e ligações MCP ao GitHub MCP Server e Azure DevOps MCP Server para traversal do catálogo.
Prompts
| Comando | Arquivo | Propósito |
|---|---|---|
/golden-path | .github/prompts/golden-path.prompt.md | Compor um novo template de golden path para um arquétipo de serviço |
/template-new | .github/prompts/template-new.prompt.md | Versionar um template e abrir a frota de PRs de rollout |
/adr-platform | .github/prompts/adr-platform.prompt.md | Rascunhar um ADR a partir de um transcript de reunião de design ou especificação |
/capability-matrix | .github/prompts/capability-matrix.prompt.md | Atualizar a matriz de capacidades domínio-para-primitiva |
Instruções
Um applyTo escopado reduz o custo em tokens em aproximadamente 68 por cento em comparação com instruções globais.
Escopo (applyTo) | Arquivo | Propósito |
|---|---|---|
templates/**/* | .github/instructions/templates.instructions.md | Schema de parâmetros de template, estrutura de README, caminho de upgrade |
adr/**/*.md | .github/instructions/adr.instructions.md | Formato de ADR: contexto, opções, decisão, consequências |
catalog/**/*.yaml | .github/instructions/catalog.instructions.md | Schema de catálogo, ownership, ciclo de vida |
Skills
Skills são lazy-loaded, então o Platform Architect pode instalar muitas e pagar tokens só pelas que forem ativadas.
template-drift-scan: chama o GitHub MCP para listar repos consumidores ainda em versões velhas de templatemcp-catalog-enforcer: recusa PRs que adicionam MCPs que não estão no catálogo validado
Hooks
Hooks custam zero tokens de LLM. São a camada mais forte de governança.
pre-commit: validar schema de parâmetros de template e front matter do ADRpre-merge: verificar bump de versão de template e guia de migração em qualquer mudança de templatepost-merge: abrir PRs de rollout nos repos consumidores via GitHub MCP
MCPs validados
Todos os MCPs abaixo estão registrados no catálogo de MCPs. Não referencie nenhum MCP que não esteja no catálogo.
| MCP | Status | Uso nesta persona |
|---|---|---|
| GitHub MCP Server | Oficial | Traversal de catálogo, PRs de rollout de template, telemetria de uso |
| Azure DevOps MCP Server | Oficial (Microsoft) | Ler tickets de intake, atualizar Azure Boards, gerenciar templates de pipeline |
| Azure MCP Server | Oficial (Microsoft) | Consultar initiatives do Azure Policy e inventários de resource group |
| Microsoft Learn Docs MCP | Oficial | Buscar guia do Azure Well-Architected Framework e referências Azure durante a autoria de ADR |
| Microsoft 365 Agents SDK MCP | Oficial (Microsoft) | Publicar snapshots da matriz de capacidades e notificações de ADR no Teams e SharePoint |
| Playwright MCP | Oficial (Microsoft) | Validar que templates de golden path fazem bootstrap de smoke tests ponta a ponta funcionais |
Exemplos reais
Cenário A: lançar um novo golden path de API
Entrada: A organização decide que toda nova API interna deve usar Azure API Management, auth Entra ID e um App Service deployado via Bicep. Nenhum outro arquétipo é permitido para APIs internas.
Invocação: /golden-path com arquétipo internal-api.
Saída esperada:
- Um repo de template
template-internal-apicom módulo Bicep, reusable workflow do GitHub Actions, esqueleto de app registration no Entra ID e scaffold OpenAPI. - Uma initiative do Azure Policy que nega qualquer App Service criado fora deste template.
- Um ADR
adr/0042-internal-api-golden-path.mdregistrando a decisão, opções consideradas e consequências. - Uma atualização da matriz de capacidades linkando o arquétipo
internal-apià instância compartilhada de APIM.
Cenário B: fazer roll forward de uma mudança breaking de template
Entrada: A organização faz upgrade do runtime padrão de .NET de 8 para 9. Todo serviço usando o golden path de API precisa fazer upgrade.
Invocação: /template-new com o bump de versão do template.
Saída esperada:
- Uma nova versão de template
template-internal-api@2.0.0com o runtime bumpado e um guia de migração. - Uma frota de PRs abertos pelo agente Path Keeper em cada repo consumidor, cada um com o diff de migração e um link para o ADR.
- Um dashboard de drift no Application Insights que mostra adoção ao longo do tempo, publicado na reunião de review de plataforma.
Anti-padrões
- Template como página de wiki. Uma página markdown que descreve o golden path sem um engine de scaffolding. Mitigação: todo golden path é um repo de template real com parâmetros e testes.
- ADRs escritos depois dos fatos. Decisões são documentadas meses depois, se é que são. Mitigação:
/adr-platformrascunha a partir do transcript da reunião de design durante a reunião. - Matriz de capacidades manual. Uma planilha que ninguém atualiza. Mitigação:
/capability-matrixregenera a partir do YAML do catálogo. - MCP liberação geral. Times instalam qualquer MCP que encontram. Mitigação: skill
mcp-catalog-enforcerrecusa PRs que referenciam MCPs não catalogados. - Policy por assinatura. Cada assinatura cria sua própria árvore de Azure Policy. Mitigação: uma única initiative de propriedade do Platform Architect, atribuída no management group.
KPIs e métricas de impacto
A persona Platform Architect é avaliada com uma mistura de métricas de engenharia de plataforma e experiência de desenvolvedor.
| Métrica | Linha base (manual) | Meta (agentic) | Medição |
|---|---|---|---|
| Tempo até o primeiro commit em um novo serviço | 2 semanas | < 1 dia | Tempo do intake até o primeiro PR merged |
| Taxa de adoção de template | 40 por cento | > 90 por cento | Porcentagem de serviços no último golden path |
| Cobertura de ADR | 20 por cento | > 95 por cento | Porcentagem de decisões arquiteturais com ADR linkado |
| Frescor da matriz de capacidades | Trimestral | Semanal | Dias desde a última atualização |
| NPS de plataforma dos desenvolvedores | Desconhecido | > 40 | Pesquisa trimestral |
| Compliance de policy | 70 por cento | > 98 por cento | Score de compliance do Azure Policy |
| Drift do catálogo de MCPs | Não medido | 0 MCPs não catalogados | Scan de repo |
| Eficiência de tokens | N/A | < 300k tokens por versão de template | Relatório de uso do Copilot |
Maturidade em quatro níveis
| Nível | Nome | Marcadores |
|---|---|---|
| L1 | Manual | Scaffolding é uma página de wiki, ADRs opcionais, policies por assinatura |
| L2 | Assistido | Repo de template existe mas deriva, GitHub Copilot ajuda a rascunhar ADRs ocasionalmente |
| L3 | Aumentado | Um agente Path Keeper, quatro slash prompts, instruções escopadas, dois MCPs, rollout de template automatizado |
| L4 | Autônomo | Kit completo de primitivas, hooks aplicados, catálogo de MCPs aplicado, matriz de capacidades atualizada semanalmente, cobertura de ADR > 95 por cento |
Integração com outras personas
Hand-offs:
- Do Enterprise Architect: arquitetura-alvo, patterns de referência, temas de investimento
- Do Software Architect: ADRs em nível de serviço que sobem para decisões de plataforma
- Para DevOps Engineer: reusable workflows, módulos Bicep, initiatives de policy
- Para Developer: repo com scaffold, instruções escopadas, catálogo de MCPs validados
- Para InfoSec Officer: initiative de policy, catálogo de MCPs, esqueleto de app registration no Entra ID
Glossário
- Agente: um papel de LLM configurado com ferramentas, instruções e uma forma de saída definida.
- Prompt: um slash command reutilizável que invoca um agente com uma tarefa específica.
- Instruções: guia escopado aplicado por pattern match em caminhos de arquivo via
applyTo. - Skill: uma capacidade lazy-loaded que ativa em match de keyword.
- Hook: uma regra de custo zero em tokens aplicada em um evento específico do ciclo de vida.
- MCP: Model Context Protocol server que expõe sistemas externos ao agente.
- Golden path: a estrada pavimentada que todo time deve usar; desvio requer um ADR.
- IDP: Internal Developer Platform; o sistema que torna o golden path fácil de seguir.
- ADR: Architectural Decision Record; um arquivo markdown datado que captura contexto, opções, decisão, consequências.
- Matriz de capacidades: um mapa legível por máquina de domínio de negócio para primitiva de plataforma.
Referências
- Azure Well-Architected Framework — a referência para decisões de design de plataforma
- Documentação do GitHub Enterprise — a plataforma sobre a qual o IDP é construído
- Documentação do Azure DevOps — templates, pipelines, boards
- Documentação do Azure Policy — initiatives, atribuições, remediação
- Documentação do Backstage — o padrão de catálogo que o IDP segue
- Especificação do Model Context Protocol — o protocolo que liga agentes a sistemas externos
- Team Topologies — o modelo organizacional por trás dos times de plataforma
El Platform Architect es la persona que diseña los caminos pavimentados por los que cada equipo camina. En un SDLC AI-native, el Platform Architect opera un stack de primitivas validadas, no una wiki llena de diagramas aspiracionales.
Resumen ejecutivo
El Platform Architect es dueño de la Internal Developer Platform: las plantillas del golden path, la matriz de capacidades y los registros de decisiones arquitectónicas que dan forma a cómo construye cada equipo. En un SDLC AI-native, el Platform Architect opera dentro de la fase de Platform con un conjunto fijo de primitivas: un agente de plataforma, cuatro slash prompts, instrucciones con alcance, hooks validados por esquema y una lista curada de MCPs validados. La plataforma se entrega como un catálogo estilo Backstage respaldado por Azure DevOps y GitHub Enterprise, con plantillas de servicio basadas en Bicep, workflows reutilizables de GitHub y iniciativas de Azure Policy. Las salidas principales son repositorios de plantillas, matrices de capacidades, ADRs y una experiencia de developer medible.
Rol y responsabilidades
Piense en el Platform Architect como un urbanista. El urbanista no construye los edificios; el urbanista define las calles, los servicios públicos, la zonificación y los códigos de construcción que permiten a miles de constructores trabajar en paralelo sin que la ciudad colapse. El éxito del urbanista no se mide por el número de edificios que diseñó, sino por el tiempo que toma a un nuevo constructor empezar a construir con confianza. En un SDLC AI-native, la ciudad es la Internal Developer Platform, las calles son workflows reutilizables de GitHub Actions, los servicios públicos son servicios compartidos de Azure y la zonificación es Azure Policy.
Responsabilidades principales:
- Definir y mantener las plantillas de golden path para cada arquetipo de servicio (API, worker, front-end, pipeline de datos)
- Operar el catálogo estilo Backstage respaldado por Azure DevOps y GitHub Enterprise
- Autorar y gobernar registros de decisiones arquitectónicas en un repo central de ADRs
- Mantener la matriz de capacidades que mapea dominios de negocio a primitivas de plataforma
- Establecer la iniciativa de policy en Azure Policy que aplica a cada suscripción dentro del alcance
- Patrocinar el catálogo de MCPs validados y el modelo de gobernanza de agentes
- Operar el agente Path Keeper y los prompts
/golden-path,/template-new,/adr-platform,/capability-matrix
Jobs to be done
- Como Platform Architect, quiero que un nuevo repo de servicio se cree desde una plantilla golden path en minutos, para que los equipos arranquen en el camino pavimentado.
- Como Platform Architect, quiero que cada servicio declare sus capacidades en una matriz legible por máquina, para que la evolución de la plataforma sea data-driven.
- Como Platform Architect, quiero que los ADRs se redacten desde conversaciones de diseño, para que el registro de decisión nunca se omita.
- Como Platform Architect, quiero plantillas versionadas y propagadas vía PRs automatizados, para que el camino pavimentado se mantenga pavimentado.
- Como Platform Architect, quiero que la telemetría de uso de la plataforma fluya hacia Application Insights, para que las capacidades no usadas se retiren, no se acumulen.
- Como Platform Architect, quiero que el catálogo de MCPs se aplique en commit time, para que los equipos no puedan instalar MCPs no autorizados.
Puntos de dolor antes de la era AI-native
- Las plantillas se pudren. El repo de scaffolding no se ha actualizado en 14 meses. Los nuevos servicios arrancan en el camino viejo.
- Los ADRs son opcionales. Las decisiones se toman en llamadas, se documentan después o nunca. El contexto se evapora en seis meses.
- La matriz de capacidades es una hoja de cálculo. Nadie la actualiza; nadie confía en ella.
- Sprawl de policy. Cada suscripción crece sus propias definiciones de Azure Policy. Los reportes de cumplimiento son contradictorios.
- MCP a libre demanda. Cada equipo instala el MCP de la semana. La superficie de ataque de cadena de suministro explota.
Flujo diario AI-native
El Platform Architect opera un ciclo fijo cada día. El ciclo usa primitivas de GitHub Copilot dentro de Visual Studio Code y Claude Code en la terminal, más un pequeño catálogo de MCPs validados para contexto externo.
Setup de la mañana
- Abrir el monorepo de plataforma en Visual Studio Code. GitHub Copilot Chat carga
AGENTS.mdy los.github/instructions/*.instructions.mdcon alcance para plantillas y ADRs. - En Claude Code, ejecutar un reporte diario que consulta el GitHub MCP por uso de plantillas, PRs de drift de plantilla y la cola de revisión de ADRs.
- Revisar la matriz de capacidades por cualquier servicio que cayó fuera de cumplimiento durante la noche (impulsado por Azure Policy y GitHub Advanced Security).
- Hacer triage de los pedidos entrantes de plantilla en Azure Boards.
Ejecución al mediodía
Cada ciclo de mediodía es un único cambio de plataforma, típicamente 2 a 4 horas de trabajo enfocado.
- Golden path. Invocar
/golden-pathcon un arquetipo (API, worker, front-end, datos). El agente Path Keeper compone la plantilla desde módulos Bicep, workflows reutilizables de GitHub y el catálogo de MCPs validados. - Cambio de plantilla. Invocar
/template-newpara versionar la plantilla, abrir una flota de PRs de rollout entre repos consumidores y adjuntar una guía de migración. - ADR. Invocar
/adr-platformpara redactar un ADR desde la transcripción de la reunión de diseño. El agente llena las restricciones EARS, las opciones consideradas y la justificación de la decisión. - Matriz de capacidades. Invocar
/capability-matrixpara refrescar el mapa dominio-a-primitiva desde el índice del catálogo de servicios. - Pull request. La descripción del PR se compone desde el ADR y el diff de la plantilla. GitHub Copilot Code Review escanea por drift de policy.
Gobernanza en la tarde
- Ejecutar un reporte semanal de drift de plantillas en Azure Monitor. Servicios con más de dos versiones menores de retraso se marcan.
- Publicar el snapshot de la matriz de capacidades en el sitio de Microsoft 365 SharePoint para la reunión de revisión de plataforma.
- Hacer hand-off de cambios de infraestructura al DevOps Engineer; hand-off de cambios de postura de seguridad al InfoSec Officer.
Primitivas recomendadas
Agentes
| Agente | Archivo | Propósito |
|---|---|---|
path-keeper | .github/agents/path-keeper.agent.md | Autorar golden paths, gobernar plantillas, redactar ADRs, mantener la matriz de capacidades |
El agente Path Keeper usa claude-sonnet-4-6 por defecto. Tiene herramientas read, edit, search, grep, glob, bash y bindings MCP a GitHub MCP Server y Azure DevOps MCP Server para recorrer el catálogo.
Prompts
| Comando | Archivo | Propósito |
|---|---|---|
/golden-path | .github/prompts/golden-path.prompt.md | Componer una nueva plantilla golden path para un arquetipo de servicio |
/template-new | .github/prompts/template-new.prompt.md | Versionar una plantilla y abrir la flota de PRs de rollout |
/adr-platform | .github/prompts/adr-platform.prompt.md | Redactar un ADR desde una transcripción de reunión de diseño o especificación |
/capability-matrix | .github/prompts/capability-matrix.prompt.md | Refrescar la matriz de capacidades dominio-a-primitiva |
Instructions
El applyTo con alcance reduce el costo de tokens en aproximadamente 68 por ciento comparado con instrucciones globales.
Alcance (applyTo) | Archivo | Propósito |
|---|---|---|
templates/**/* | .github/instructions/templates.instructions.md | Esquema de parámetros de plantilla, estructura del README, ruta de upgrade |
adr/**/*.md | .github/instructions/adr.instructions.md | Formato ADR: contexto, opciones, decisión, consecuencias |
catalog/**/*.yaml | .github/instructions/catalog.instructions.md | Esquema del catálogo, ownership, ciclo de vida |
Skills
Los skills se cargan de forma perezosa, así que el Platform Architect puede instalar muchos y pagar tokens solo por los que se disparan.
template-drift-scan: llama al GitHub MCP para listar repos consumidores que aún están en versiones viejas de plantillamcp-catalog-enforcer: rechaza PRs que añaden MCPs no presentes en el catálogo validado
Hooks
Los hooks cuestan cero tokens de LLM. Son la capa de gobernanza más fuerte.
pre-commit: validar el esquema de parámetros de plantilla y el front matter del ADRpre-merge: verificar el bump de versión de plantilla y la guía de migración en cualquier cambio de plantillapost-merge: abrir PRs de rollout en repos consumidores vía el GitHub MCP
MCPs validados
Cada MCP a continuación está registrado en el catálogo de MCPs. No referencie ningún MCP que no esté en el catálogo.
| MCP | Estado | Uso en esta persona |
|---|---|---|
| GitHub MCP Server | Oficial | Recorrido del catálogo, PRs de rollout de plantilla, telemetría de uso |
| Azure DevOps MCP Server | Oficial (Microsoft) | Leer tickets de intake, actualizar Azure Boards, gestionar plantillas de pipeline |
| Azure MCP Server | Oficial (Microsoft) | Consultar iniciativas de Azure Policy e inventarios de resource group |
| Microsoft Learn Docs MCP | Oficial | Consultar el Azure Well-Architected Framework y guía de referencia de Azure durante la redacción de ADRs |
| Microsoft 365 Agents SDK MCP | Oficial (Microsoft) | Publicar snapshots de matriz de capacidades y notificaciones de ADR en Teams y SharePoint |
| Playwright MCP | Oficial (Microsoft) | Validar que las plantillas golden path arrancan smoke tests end-to-end funcionales |
Ejemplos reales
Escenario A: lanzar un nuevo golden path de API
Entrada: La organización decide que cada nueva API interna debe usar Azure API Management, autenticación con Entra ID y un App Service desplegado por Bicep. Ningún otro arquetipo está permitido para APIs internas.
Invocación: /golden-path con arquetipo internal-api.
Salida esperada:
- Un repo de plantilla
template-internal-apicon módulo Bicep, workflow reutilizable de GitHub Actions, esqueleto de registro de app de Entra ID y scaffold de OpenAPI. - Una iniciativa de Azure Policy que niega cualquier App Service creado fuera de esta plantilla.
- Un ADR
adr/0042-internal-api-golden-path.mdregistrando la decisión, opciones consideradas y consecuencias. - Una actualización de la matriz de capacidades enlazando el arquetipo
internal-apicon la instancia compartida de APIM.
Escenario B: propagar un cambio de plantilla con ruptura
Entrada: La organización actualiza el runtime estándar de .NET de 8 a 9. Cada servicio que use el golden path de API debe actualizarse.
Invocación: /template-new con el bump de versión de plantilla.
Salida esperada:
- Una nueva versión de plantilla
template-internal-api@2.0.0con el runtime actualizado y una guía de migración. - Una flota de PRs abiertos por el agente Path Keeper en cada repo consumidor, cada uno con el diff de migración y un enlace al ADR.
- Un dashboard de drift en Application Insights que muestra adopción a lo largo del tiempo, publicado en la reunión de revisión de plataforma.
Anti-patrones
- Plantilla como página de wiki. Una página markdown que describe el golden path sin un motor de scaffolding. Mitigación: cada golden path es un repo de plantilla real con parámetros y tests.
- ADRs escritos a posteriori. Las decisiones se documentan meses después, si acaso. Mitigación:
/adr-platformredacta desde la transcripción de la reunión de diseño durante la reunión. - Matriz de capacidades manual. Una hoja de cálculo que nadie actualiza. Mitigación:
/capability-matrixregenera desde el YAML del catálogo. - MCP a libre demanda. Los equipos instalan cualquier MCP que encuentren. Mitigación: el skill
mcp-catalog-enforcerrechaza PRs que referencian MCPs no catalogados. - Policy por suscripción. Cada suscripción crece su propio árbol de Azure Policy. Mitigación: una sola iniciativa propiedad del Platform Architect, asignada en el management group.
KPIs y métricas de impacto
La persona Platform Architect se evalúa con una mezcla de métricas de platform engineering y experiencia de developer.
| Métrica | Línea base (manual) | Meta (agéntico) | Medición |
|---|---|---|---|
| Tiempo al primer commit en un nuevo servicio | 2 semanas | < 1 día | Tiempo desde intake al primer PR mergeado |
| Tasa de adopción de plantilla | 40 por ciento | > 90 por ciento | Porcentaje de servicios en el último golden path |
| Cobertura de ADR | 20 por ciento | > 95 por ciento | Porcentaje de decisiones arquitectónicas con un ADR vinculado |
| Frescura de la matriz de capacidades | Trimestral | Semanal | Días desde el último refresh |
| NPS de plataforma de los developers | Desconocido | > 40 | Encuesta trimestral |
| Cumplimiento de policy | 70 por ciento | > 98 por ciento | Score de cumplimiento de Azure Policy |
| Drift del catálogo de MCPs | Sin medir | 0 MCPs no catalogados | Scan del repo |
| Eficiencia de tokens | N/A | < 300k tokens por versión de plantilla | Reporte de uso de Copilot |
Madurez en cuatro niveles
| Nivel | Nombre | Marcadores |
|---|---|---|
| L1 | Manual | El scaffolding es una página de wiki, ADRs opcionales, policies por suscripción |
| L2 | Asistido | Existe el repo de plantilla pero hace drift, GitHub Copilot ayuda a redactar ADRs ocasionalmente |
| L3 | Aumentado | Un agente Path Keeper, cuatro slash prompts, instrucciones con alcance, dos MCPs, rollout de plantilla automatizado |
| L4 | Autónomo | Kit completo de primitivas, hooks aplicados, catálogo de MCPs aplicado, matriz de capacidades refrescada semanalmente, cobertura de ADR > 95 por ciento |
Integración con otras personas
Hand-offs:
- Desde el Enterprise Architect: arquitectura objetivo, patrones de referencia, temas de inversión
- Desde el Software Architect: ADRs a nivel de servicio que escalan a decisiones de plataforma
- Hacia el DevOps Engineer: workflows reutilizables, módulos Bicep, iniciativas de policy
- Hacia el Developer: repo scaffolded, instrucciones con alcance, catálogo de MCPs validados
- Hacia el InfoSec Officer: iniciativa de policy, catálogo de MCPs, esqueleto de registro de app de Entra ID
Glosario
- Agente: un rol LLM configurado con herramientas, instrucciones y una forma de salida definida.
- Prompt: un slash command reutilizable que invoca a un agente con una tarea específica.
- Instructions: guía con alcance aplicada por coincidencia de patrón en rutas de archivos vía
applyTo. - Skill: una capacidad cargada de forma perezosa que se activa por coincidencia de palabra clave.
- Hook: una regla de cero tokens aplicada en un evento específico del ciclo de vida.
- MCP: servidor Model Context Protocol que expone sistemas externos al agente.
- Golden path: el camino pavimentado que cada equipo se espera use; cualquier desviación requiere un ADR.
- IDP: Internal Developer Platform; el sistema que hace fácil seguir el golden path.
- ADR: Architectural Decision Record; un archivo markdown fechado que captura contexto, opciones, decisión, consecuencias.
- Matriz de capacidades: un mapa legible por máquina desde dominio de negocio a primitiva de plataforma.
Referencias
- Azure Well-Architected Framework — la referencia para decisiones de diseño de plataforma
- Documentación de GitHub Enterprise — la plataforma sobre la que se construye el IDP
- Documentación de Azure DevOps — plantillas, pipelines, boards
- Documentación de Azure Policy — iniciativas, asignaciones, remediación
- Documentación de Backstage — el patrón de catálogo que sigue el IDP
- Especificación de Model Context Protocol — el protocolo que vincula agentes a sistemas externos
- Team Topologies — el modelo organizacional detrás de los equipos de plataforma