03 product · Discovery
Requirements EngineerEngenheiro de RequisitosIngeniero de Requisitos
Encodes requirements in EARS.Codifica requisitos em EARS.Codifica requisitos en EARS.
The Requirements Engineer is the persona that encodes, decomposes, and traces requirements with discipline. In an AI-native SDLC, the Requirements Engineer operates a stack of validated primitives that convert draft intent into auditable EARS clauses.
Executive summary
The Requirements Engineer decomposes approved specifications into atomic, testable EARS requirements and maintains the traceability matrix from requirement to test to deployed artifact. In an AI-native SDLC the Requirements Engineer operates inside the Discovery phase with a fixed set of primitives: one EARS encoding agent, four slash prompts, scoped instructions, schema-validated hooks, and a curated list of validated MCPs. Primary outputs are atomic requirement files, gap analyses, traceability reports, and requirement review records.
Role and responsibilities
Think of the Requirements Engineer like a legal codifier who turns a legislator’s intent into numbered statutes that courts can apply without interpretation. The legislator proposes, the codifier transforms, and every future judgment cites a clause by number. In an AI-native SDLC the Product Owner proposes in SPECIFICATION.md, the Requirements Engineer codifies in atomic EARS form, and every test, commit, and release note cites a requirement ID.
Primary responsibilities:
- Decompose every approved spec into atomic EARS requirements under
docs/requirements/ - Maintain the traceability matrix that links each requirement to its acceptance criteria, tests, pull requests, and deployed artifacts
- Run gap scans to detect requirements without tests, tests without requirements, and deployments without either
- Run requirement reviews with the Product Owner, Software Architect, and QA Engineer at defined gates
- Operate the EARS Encoder agent and the
/ears,/traceability,/gap-scan,/requirement-reviewprompts - Govern the requirement change log, ensuring every change references an approved spec diff
- Publish the readiness report that releases depend on
Jobs to be done
- As a Requirements Engineer, I want to decompose an approved spec into atomic requirements within hours, so that development is never blocked on clarification.
- As a Requirements Engineer, I want every requirement in strict EARS form, so that agents and humans parse it identically.
- As a Requirements Engineer, I want the traceability matrix to regenerate on every merge, so that audit answers are always current.
- As a Requirements Engineer, I want gap scans to run on every pull request, so that tests and requirements never diverge silently.
- As a Requirements Engineer, I want requirement reviews to be structured and recorded, so that decisions persist beyond the meeting.
- As a Requirements Engineer, I want the readiness report to refuse release if any gap is unresolved, so that scope discipline is enforced at the gate.
Pain points before AI-native
- Specs too coarse to test. High-level specs cannot be bound to test cases. Developers improvise decomposition inconsistently.
- Traceability built once and abandoned. Matrix spreadsheets go stale within a sprint. Audit preparation becomes a rebuild.
- Gaps discovered at release. Missing tests and orphan features surface at the release gate, forcing schedule slips.
- Reviews without records. Clarifications happen verbally. Next sprint, the same question is asked again.
- Requirement churn untracked. Changes are made in place without a diff history. Regressions in scope are invisible.
AI-native daily workflow
The Requirements Engineer 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 requirement instructions. - Pull the latest
mainand review overnight spec changes by the Product Owner. - Run
/gap-scanto produce the current gap report: requirements without tests, tests without requirements, deployments without either. - Review the traceability dashboard generated from the Azure MCP Server and GitHub MCP telemetry.
Midday execution
- Decomposition. Invoke
/earson each new spec section. The EARS Encoder agent produces atomic requirements with unique IDs, each in strictWHEN ... THE system SHALL ...form. - Traceability. Invoke
/traceabilityto bind each new requirement to existing tests, pull requests, and deployment records. The agent updates the matrix and flags orphans. - Gap closure. For each gap flagged in the morning scan, either author the missing requirement, raise a test task for QA Engineer, or file an ADR if architectural change is required.
- Cross-persona sync. Use the Microsoft 365 Agents SDK MCP to raise clarification requests in the Teams channel when spec intent is ambiguous.
Afternoon review
- Invoke
/requirement-reviewto run the structured review session with the Product Owner, Software Architect, and QA Engineer. The agent prepares the agenda from the day’s diffs and records decisions against requirement IDs. - Open a pull request on the requirement files. GitHub Copilot Code Review comments on EARS compliance; human reviewers approve content.
- Update the readiness report. A post-merge hook regenerates the report with gap counts and blocker lists.
- Publish the daily requirement digest to the product Teams channel via the Microsoft 365 Agents SDK.
Recommended primitives
Agent
| Agent | File | Purpose |
|---|---|---|
ears-encoder | .github/agents/ears-encoder.agent.md | Decompose specs into atomic EARS requirements, maintain traceability, run gap scans |
The EARS Encoder uses claude-sonnet-4-6 by default. Tools: read, edit, search, grep, glob. No bash access. Extended thinking is enabled for /gap-scan only, where cross-document correlation benefits from deep reasoning.
Slash prompts
| Command | File | Purpose |
|---|---|---|
/ears | .github/prompts/ears.prompt.md | Decompose a spec section into atomic EARS requirements |
/traceability | .github/prompts/traceability.prompt.md | Bind requirements to tests, PRs, and deployments, regenerate the matrix |
/gap-scan | .github/prompts/gap-scan.prompt.md | Detect requirements without tests, tests without requirements, orphan deployments |
/requirement-review | .github/prompts/requirement-review.prompt.md | Prepare and record the structured review session |
Instructions scoped
Scoped applyTo reduces token cost by approximately 68 percent compared to global instructions.
Scope (applyTo) | File | Purpose |
|---|---|---|
docs/requirements/**/*.md | .github/instructions/requirements.instructions.md | Atomic EARS format, ID schema, cross-reference rules |
docs/traceability/**/*.md | .github/instructions/traceability.instructions.md | Matrix schema, regeneration rules, audit evidence format |
docs/reviews/**/*.md | .github/instructions/reviews.instructions.md | Review agenda template, decision record format |
Hooks
Hooks cost zero LLM tokens. They are the strongest governance layer for requirements.
pre-commit: reject any requirement file with non-atomic or non-EARS clauses, or with duplicate IDspost-commit: regenerate the traceability matrix and the readiness reportpre-merge: block merge of any requirement change that introduces a new gap without a linked follow-up issue
Validated MCPs
| MCP | Purpose | Owner |
|---|---|---|
| GitHub MCP Server | Read pull requests, tests, and Actions runs to populate the traceability matrix | GitHub (official) |
| Azure DevOps MCP Server | Read Azure Boards work items and test plans when the team uses Azure DevOps | Microsoft (official) |
| Azure MCP Server | Query Application Insights to confirm deployed artifacts match requirement IDs | Microsoft (official) |
| Microsoft Learn Docs MCP | Ground requirements on Microsoft product surfaces in current documentation | Microsoft (official) |
| Microsoft 365 Agents SDK MCP | Raise clarification threads in Teams and record decisions from Outlook | Microsoft (official) |
Real examples
Example 1: decompose an approved spec section
Input: A spec section on contract renewal covering initiation, eligibility, and notification, approved by the Product Owner.
Invocation: /ears followed by /traceability.
Expected output:
- A
docs/requirements/contract-renewal/directory with twelve atomic requirement files, each with a unique ID and strict EARS clause. - A regenerated traceability matrix that binds three pre-existing tests to two of the new requirements and flags the remaining ten as gaps.
- A pull request with Copilot Code Review comments on clause shape and ID consistency.
Example 2: gap closure before release
Input: A release candidate with 146 merged requirements. The morning /gap-scan report flags six requirements without passing tests and two tests without requirements.
Invocation: /gap-scan followed by /requirement-review.
Expected output:
- Six tasks in GitHub Projects created via the GitHub MCP, each linked to the requirement anchor and assigned to QA Engineer.
- Two requirement files authored to bind the orphan tests to requirement IDs.
- A recorded review session in
docs/reviews/2026-q3-release-readiness.mdwith decisions tagged by requirement ID. - A readiness report update that reopens the release gate until all eight items close.
Anti-patterns
- Compound requirements. Clauses that bundle two or more conditions cannot be tested atomically. Mitigation: the
/earsagent and thepre-commithook reject non-atomic clauses. - Manual traceability. Spreadsheets cannot be trusted on a sprint boundary. Mitigation: the matrix regenerates on
post-commit. - Silent ID collisions. Reused IDs break audit trails. Mitigation: the
pre-commithook rejects duplicates across thedocs/requirements/tree. - Reviews without records. Verbal clarifications evaporate. Mitigation:
/requirement-reviewenforces a recorded decision for every agenda item. - Gaps waived verbally. A waived gap without an ADR or follow-up issue re-emerges at release. Mitigation:
pre-mergeblocks the waiver path.
KPIs and impact metrics
| KPI | Baseline | Target | Measurement |
|---|---|---|---|
| Requirements in atomic EARS | 30 percent | 100 percent | Requirements linter in GitHub Actions |
| Traceability freshness, last regeneration | 7 days | < 1 hour | Post-commit hook timestamp |
| Gap count at release gate | 14 | 0 | Readiness report |
| Requirement review cycle time | 2 weeks | < 1 week | PR timestamps |
| Orphan test rate | 12 percent | < 2 percent | Gap scan output |
| Audit query response time | 1 day | < 1 hour | Traceability matrix query log |
Maturity in four levels
| Level | Name | Markers |
|---|---|---|
| L1 | Manual | Prose specs, ad-hoc decomposition, traceability built by hand |
| L2 | Assisted | Copilot used to polish requirement phrasing, no atomic discipline |
| L3 | Augmented | EARS Encoder agent, four slash prompts, scoped instructions, matrix auto-generated, gap scans on PR |
| L4 | Autonomous | Full primitives kit, hooks enforced, readiness report live, reviews recorded automatically, audit response within the hour |
Integration with other personas
- From Product Owner: approved
SPECIFICATION.mdwith numbered EARS requirements as the canonical input - From Business Manager: KPI-bound outcomes that inform gap prioritization
- To Software Architect: stable requirement IDs that anchor
CODEMAP.mdand API contracts - To QA Engineer: atomic requirements that drive test case generation and coverage reports
- To Developer: requirement anchor on every PR enabling implementation traceability
- To Compliance Auditor: regenerated matrix as audit evidence on demand
- To Release Manager: readiness report gating the release cut
Glossary
- EARS: Easy Approach to Requirements Syntax. The canonical
WHEN ... THE system SHALL ...form. - Atomic requirement: a single testable clause with a unique ID, no conjunctions that introduce independent conditions.
- Traceability matrix: generated table binding each requirement to acceptance criteria, tests, pull requests, and deployments.
- Gap scan: automated sweep that detects requirements without tests, tests without requirements, and deployments without either.
- Readiness report: generated document summarizing release gate status against open requirement gaps.
- Requirement review: structured, recorded session that approves or defers requirement changes with named participants.
References
- GitHub Copilot documentation — agent mode, prompts, and instructions
- Azure Boards documentation — work item tracking for requirement-linked tasks
- GitHub Actions documentation — automation for traceability regeneration and gap scans
- Application Insights documentation — deployed artifact telemetry for requirement verification
- Microsoft Learn, Well-Architected Framework — operational excellence and audit evidence guidance
O Requirements Engineer é a persona que codifica, decompõe e rastreia requisitos com disciplina. Em um SDLC AI-native, o Requirements Engineer opera uma pilha de primitivas validadas que converte intenção em draft em cláusulas EARS auditáveis.
Resumo executivo
O Requirements Engineer decompõe especificações aprovadas em requisitos EARS atômicos e testáveis, e mantém a matriz de rastreabilidade de requisito para teste para artefato implantado. Em um SDLC AI-native, o Requirements Engineer opera dentro da fase de Discovery com um conjunto fixo de primitivas: um agente de encoding EARS, quatro slash prompts, instruções escopadas, hooks validados por schema e uma lista curada de MCPs validados. As saídas primárias são arquivos de requisitos atômicos, análises de gap, relatórios de rastreabilidade e registros de review de requisitos.
Papel e responsabilidades
Pense no Requirements Engineer como um codificador jurídico que transforma a intenção do legislador em estatutos numerados que os tribunais podem aplicar sem interpretação. O legislador propõe, o codificador transforma, e todo julgamento futuro cita uma cláusula pelo número. Em um SDLC AI-native, o Product Owner propõe no SPECIFICATION.md, o Requirements Engineer codifica em forma EARS atômica, e todo teste, commit e release note cita um ID de requisito.
Responsabilidades primárias:
- Decompor toda spec aprovada em requisitos EARS atômicos sob
docs/requirements/ - Manter a matriz de rastreabilidade que liga cada requisito a seus critérios de aceitação, testes, pull requests e artefatos implantados
- Rodar gap scans para detectar requisitos sem testes, testes sem requisitos e deploys sem nenhum dos dois
- Rodar reviews de requisitos com o Product Owner, Software Architect e QA Engineer em gates definidos
- Operar o agente EARS Encoder e os prompts
/ears,/traceability,/gap-scan,/requirement-review - Governar o log de mudanças de requisitos, garantindo que toda mudança referencie um diff de spec aprovado
- Publicar o relatório de prontidão do qual os releases dependem
Jobs to be done
- Como Requirements Engineer, eu quero decompor uma spec aprovada em requisitos atômicos em horas, para que o desenvolvimento nunca fique bloqueado aguardando clarificação.
- Como Requirements Engineer, eu quero todo requisito em forma EARS estrita, para que agentes e humanos o parseiem de modo idêntico.
- Como Requirements Engineer, eu quero que a matriz de rastreabilidade se regenere a cada merge, para que as respostas de auditoria estejam sempre atuais.
- Como Requirements Engineer, eu quero gap scans rodando em todo pull request, para que testes e requisitos nunca divirjam silenciosamente.
- Como Requirements Engineer, eu quero que reviews de requisitos sejam estruturadas e registradas, para que decisões persistam para além da reunião.
- Como Requirements Engineer, eu quero que o relatório de prontidão recuse o release se qualquer gap estiver sem resolução, para que a disciplina de escopo seja enforçada no gate.
Dores antes da era AI-native
- Specs grossas demais para testar. Specs de alto nível não podem ser vinculadas a casos de teste. Developers improvisam decomposição de modo inconsistente.
- Rastreabilidade construída uma vez e abandonada. Planilhas de matriz ficam defasadas dentro de uma sprint. Preparação de auditoria se torna uma reconstrução.
- Gaps descobertos no release. Testes ausentes e features órfãs aparecem no gate de release, forçando atrasos no cronograma.
- Reviews sem registros. Clarificações acontecem verbalmente. Na próxima sprint, a mesma pergunta é feita de novo.
- Churn de requisitos não rastreado. Mudanças são feitas no próprio lugar sem histórico de diff. Regressões de escopo são invisíveis.
Fluxo diário AI-native
O Requirements Engineer 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 requisitos. - Puxe o último
maine revise mudanças noturnas de spec feitas pelo Product Owner. - Rode
/gap-scanpara produzir o relatório de gap atual: requisitos sem testes, testes sem requisitos, deploys sem nenhum dos dois. - Revise o dashboard de rastreabilidade gerado a partir da telemetria do Azure MCP Server e do GitHub MCP.
Execução no meio do dia
- Decomposição. Invoque
/earsem cada nova seção da spec. O agente EARS Encoder produz requisitos atômicos com IDs únicos, cada um em formaWHEN ... THE system SHALL ...estrita. - Rastreabilidade. Invoque
/traceabilitypara vincular cada novo requisito a testes, pull requests e registros de deploy existentes. O agente atualiza a matriz e sinaliza órfãos. - Fechamento de gap. Para cada gap sinalizado no scan matinal, ou escreva o requisito ausente, levante uma tarefa de teste para o QA Engineer, ou abra um ADR se uma mudança arquitetural for necessária.
- Sincronização entre personas. Use o Microsoft 365 Agents SDK MCP para levantar pedidos de clarificação no canal do Teams quando a intenção da spec for ambígua.
Revisão no fim da tarde
- Invoque
/requirement-reviewpara rodar a sessão de review estruturada com o Product Owner, Software Architect e QA Engineer. O agente prepara a pauta a partir dos diffs do dia e registra decisões contra os IDs de requisito. - Abra um pull request nos arquivos de requisito. GitHub Copilot Code Review comenta em conformidade EARS; revisores humanos aprovam o conteúdo.
- Atualize o relatório de prontidão. Um hook de post-merge regenera o relatório com contagens de gap e listas de bloqueadores.
- Publique o digest diário de requisitos no canal do Teams do produto via Microsoft 365 Agents SDK.
Primitivas recomendadas
Agente
| Agente | Arquivo | Propósito |
|---|---|---|
ears-encoder | .github/agents/ears-encoder.agent.md | Decompor specs em requisitos EARS atômicos, manter rastreabilidade, rodar gap scans |
O EARS Encoder usa claude-sonnet-4-6 por padrão. Ferramentas: read, edit, search, grep, glob. Sem acesso a bash. Extended thinking é habilitado apenas para /gap-scan, onde a correlação entre documentos se beneficia de raciocínio profundo.
Slash prompts
| Comando | Arquivo | Propósito |
|---|---|---|
/ears | .github/prompts/ears.prompt.md | Decompor uma seção da spec em requisitos EARS atômicos |
/traceability | .github/prompts/traceability.prompt.md | Vincular requisitos a testes, PRs e deploys, regenerar a matriz |
/gap-scan | .github/prompts/gap-scan.prompt.md | Detectar requisitos sem testes, testes sem requisitos, deploys órfãos |
/requirement-review | .github/prompts/requirement-review.prompt.md | Preparar e registrar a sessão estruturada de review |
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 |
|---|---|---|
docs/requirements/**/*.md | .github/instructions/requirements.instructions.md | Formato EARS atômico, schema de ID, regras de cross-reference |
docs/traceability/**/*.md | .github/instructions/traceability.instructions.md | Schema da matriz, regras de regeneração, formato de evidência de auditoria |
docs/reviews/**/*.md | .github/instructions/reviews.instructions.md | Template de pauta de review, formato de registro de decisão |
Hooks
Hooks custam zero tokens de LLM. São a camada de governança mais forte para requisitos.
pre-commit: rejeitar qualquer arquivo de requisito com cláusulas não-atômicas ou não-EARS, ou com IDs duplicadospost-commit: regenerar a matriz de rastreabilidade e o relatório de prontidãopre-merge: bloquear o merge de qualquer mudança de requisito que introduza um novo gap sem uma issue de follow-up vinculada
MCPs validados
| MCP | Propósito | Dono |
|---|---|---|
| GitHub MCP Server | Ler pull requests, testes e runs do Actions para popular a matriz de rastreabilidade | GitHub (oficial) |
| Azure DevOps MCP Server | Ler work items do Azure Boards e planos de teste quando o time usa Azure DevOps | Microsoft (oficial) |
| Azure MCP Server | Consultar Application Insights para confirmar que artefatos implantados correspondem a IDs de requisito | Microsoft (oficial) |
| Microsoft Learn Docs MCP | Ancorar requisitos em superfícies de produto Microsoft em documentação atual | Microsoft (oficial) |
| Microsoft 365 Agents SDK MCP | Levantar threads de clarificação no Teams e registrar decisões do Outlook | Microsoft (oficial) |
Exemplos reais
Exemplo 1: decompor uma seção de spec aprovada
Entrada: Uma seção de spec sobre renovação de contrato cobrindo iniciação, elegibilidade e notificação, aprovada pelo Product Owner.
Invocação: /ears seguido de /traceability.
Saída esperada:
- Um diretório
docs/requirements/contract-renewal/com doze arquivos de requisito atômicos, cada um com um ID único e cláusula EARS estrita. - Uma matriz de rastreabilidade regenerada que vincula três testes pré-existentes a dois dos novos requisitos e sinaliza os dez restantes como gaps.
- Um pull request com comentários do Copilot Code Review sobre forma da cláusula e consistência de ID.
Exemplo 2: fechamento de gap antes do release
Entrada: Um release candidate com 146 requisitos merged. O relatório matinal do /gap-scan sinaliza seis requisitos sem testes passando e dois testes sem requisitos.
Invocação: /gap-scan seguido de /requirement-review.
Saída esperada:
- Seis tarefas no GitHub Projects criadas via o GitHub MCP, cada uma vinculada à âncora do requisito e atribuída ao QA Engineer.
- Dois arquivos de requisito escritos para vincular os testes órfãos a IDs de requisito.
- Uma sessão de review registrada em
docs/reviews/2026-q3-release-readiness.mdcom decisões taggeadas por ID de requisito. - Uma atualização no relatório de prontidão que reabre o gate de release até que todos os oito itens fechem.
Anti-padrões
- Requisitos compostos. Cláusulas que juntam duas ou mais condições não podem ser testadas atomicamente. Mitigação: o agente
/earse o hook depre-commitrejeitam cláusulas não-atômicas. - Rastreabilidade manual. Planilhas não podem ser confiáveis na borda de uma sprint. Mitigação: a matriz se regenera no
post-commit. - Colisões silenciosas de ID. IDs reutilizados quebram trilhas de auditoria. Mitigação: o hook de
pre-commitrejeita duplicatas em toda a árvoredocs/requirements/. - Reviews sem registros. Clarificações verbais evaporam. Mitigação:
/requirement-reviewenforça uma decisão registrada para cada item de pauta. - Gaps renunciados verbalmente. Um gap renunciado sem ADR ou issue de follow-up re-emerge no release. Mitigação:
pre-mergebloqueia o caminho de renúncia.
KPIs e métricas de impacto
| KPI | Linha base | Meta | Medição |
|---|---|---|---|
| Requisitos em EARS atômico | 30 por cento | 100 por cento | Linter de requisitos no GitHub Actions |
| Frescor da rastreabilidade, última regeneração | 7 dias | < 1 hora | Timestamp do hook de post-commit |
| Contagem de gap no gate de release | 14 | 0 | Relatório de prontidão |
| Tempo de ciclo de review de requisitos | 2 semanas | < 1 semana | Timestamps de PR |
| Taxa de teste órfão | 12 por cento | < 2 por cento | Saída do gap scan |
| Tempo de resposta de consulta de auditoria | 1 dia | < 1 hora | Log de consultas da matriz de rastreabilidade |
Maturidade em quatro níveis
| Nível | Nome | Marcadores |
|---|---|---|
| L1 | Manual | Specs em prosa, decomposição ad-hoc, rastreabilidade construída à mão |
| L2 | Assistido | Copilot usado para polir o fraseamento do requisito, sem disciplina atômica |
| L3 | Aumentado | Agente EARS Encoder, quatro slash prompts, instruções escopadas, matriz auto-gerada, gap scans em PR |
| L4 | Autônomo | Kit completo de primitivas, hooks enforçados, relatório de prontidão ao vivo, reviews registradas automaticamente, resposta de auditoria em até uma hora |
Integração com outras personas
- Do Product Owner:
SPECIFICATION.mdaprovado com requisitos EARS numerados como input canônico - Do Business Manager: outcomes atados a KPIs que informam priorização de gaps
- Para o Software Architect: IDs de requisito estáveis que ancoram o
CODEMAP.mde contratos de API - Para o QA Engineer: requisitos atômicos que guiam geração de casos de teste e relatórios de cobertura
- Para o Developer: âncora de requisito em todo PR habilitando rastreabilidade de implementação
- Para o Compliance Auditor: matriz regenerada como evidência de auditoria sob demanda
- Para o Release Manager: relatório de prontidão gatekeeping do corte de release
Glossário
- EARS: Easy Approach to Requirements Syntax. A forma canônica
WHEN ... THE system SHALL .... - Requisito atômico: uma única cláusula testável com ID único, sem conjunções que introduzam condições independentes.
- Matriz de rastreabilidade: tabela gerada vinculando cada requisito a critérios de aceitação, testes, pull requests e deploys.
- Gap scan: varredura automatizada que detecta requisitos sem testes, testes sem requisitos e deploys sem nenhum dos dois.
- Relatório de prontidão: documento gerado que resume o status do gate de release contra gaps abertos de requisito.
- Review de requisitos: sessão estruturada e registrada que aprova ou adia mudanças de requisito com participantes nomeados.
Referências
- Documentação do GitHub Copilot — modo agent, prompts e instruções
- Documentação do Azure Boards — rastreio de work items para tarefas vinculadas a requisitos
- Documentação do GitHub Actions — automação para regeneração de rastreabilidade e gap scans
- Documentação do Application Insights — telemetria de artefato implantado para verificação de requisito
- Microsoft Learn, Well-Architected Framework — orientação sobre excelência operacional e evidência de auditoria
El Requirements Engineer es la persona que codifica, descompone y traza requisitos con disciplina. En un SDLC AI-native, el Requirements Engineer opera un stack de primitivas validadas que convierten la intención en borrador en cláusulas EARS auditables.
Resumen ejecutivo
El Requirements Engineer descompone las especificaciones aprobadas en requisitos EARS atómicos y testables, y mantiene la matriz de trazabilidad desde el requisito hasta la prueba y el artefacto desplegado. En un SDLC AI-native, el Requirements Engineer opera dentro de la fase de Discovery con un conjunto fijo de primitivas: un agente de codificación EARS, cuatro slash prompts, instrucciones con alcance, hooks validados por esquema y una lista curada de MCPs validados. Las salidas principales son archivos atómicos de requisitos, análisis de brechas, reportes de trazabilidad y registros de revisión de requisitos.
Rol y responsabilidades
Piensa en el Requirements Engineer como un codificador legal que convierte la intención de un legislador en estatutos numerados que los tribunales pueden aplicar sin interpretación. El legislador propone, el codificador transforma y cada juicio futuro cita una cláusula por número. En un SDLC AI-native, el Product Owner propone en SPECIFICATION.md, el Requirements Engineer codifica en forma EARS atómica, y cada prueba, commit y release note cita un ID de requisito.
Responsabilidades principales:
- Descomponer cada spec aprobado en requisitos EARS atómicos bajo
docs/requirements/ - Mantener la matriz de trazabilidad que enlaza cada requisito con sus criterios de aceptación, pruebas, pull requests y artefactos desplegados
- Correr gap scans para detectar requisitos sin pruebas, pruebas sin requisitos y despliegues sin ninguno de los dos
- Correr revisiones de requisitos con el Product Owner, el Software Architect y el QA Engineer en compuertas definidas
- Operar el agente EARS Encoder y los prompts
/ears,/traceability,/gap-scan,/requirement-review - Gobernar el log de cambios de requisitos, asegurando que cada cambio referencie un diff de spec aprobado
- Publicar el reporte de readiness del que dependen los releases
Jobs to be done
- Como Requirements Engineer, quiero descomponer un spec aprobado en requisitos atómicos en horas, para que el desarrollo nunca se bloquee esperando aclaraciones.
- Como Requirements Engineer, quiero cada requisito en forma EARS estricta, para que agentes y humanos lo parseen de forma idéntica.
- Como Requirements Engineer, quiero que la matriz de trazabilidad se regenere en cada merge, para que las respuestas de auditoría siempre estén actualizadas.
- Como Requirements Engineer, quiero que los gap scans corran en cada pull request, para que pruebas y requisitos nunca diverjan en silencio.
- Como Requirements Engineer, quiero que las revisiones de requisitos sean estructuradas y registradas, para que las decisiones persistan más allá de la reunión.
- Como Requirements Engineer, quiero que el reporte de readiness rechace el release si alguna brecha está sin resolver, para que la disciplina de alcance se imponga en la compuerta.
Puntos de dolor antes de la era AI-native
- Specs demasiado gruesos para probar. Los specs de alto nivel no se pueden amarrar a casos de prueba. Los developers improvisan la descomposición de forma inconsistente.
- Trazabilidad construida una vez y abandonada. Las hojas de cálculo de matriz quedan obsoletas dentro de un sprint. La preparación de auditoría se vuelve una reconstrucción.
- Brechas descubiertas en el release. Las pruebas faltantes y las features huérfanas afloran en la compuerta de release, forzando retrasos en el cronograma.
- Revisiones sin registros. Las aclaraciones ocurren verbalmente. El siguiente sprint, se pregunta lo mismo de nuevo.
- Churn de requisitos no rastreado. Los cambios se hacen en sitio sin un historial de diff. Las regresiones de alcance son invisibles.
Flujo diario AI-native
El Requirements Engineer 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 requisitos con alcance. - Hacer pull del último
mainy revisar los cambios nocturnos al spec por parte del Product Owner. - Ejecutar
/gap-scanpara producir el reporte de brechas actual: requisitos sin pruebas, pruebas sin requisitos, despliegues sin ninguno. - Revisar el dashboard de trazabilidad generado a partir de la telemetría del Azure MCP Server y el GitHub MCP.
Ejecución al mediodía
- Descomposición. Invocar
/earssobre cada nueva sección del spec. El agente EARS Encoder produce requisitos atómicos con IDs únicos, cada uno en forma estrictaWHEN ... THE system SHALL .... - Trazabilidad. Invocar
/traceabilitypara amarrar cada nuevo requisito con pruebas existentes, pull requests y registros de despliegue. El agente actualiza la matriz y marca los huérfanos. - Cierre de brechas. Para cada brecha marcada en el escaneo de la mañana, ya sea redactar el requisito faltante, levantar una tarea de prueba para el QA Engineer o presentar un ADR si se requiere un cambio arquitectónico.
- Sincronización entre personas. Usar el MCP del Microsoft 365 Agents SDK para levantar solicitudes de aclaración en el canal de Teams cuando la intención del spec sea ambigua.
Revisión al final de la tarde
- Invocar
/requirement-reviewpara correr la sesión de revisión estructurada con el Product Owner, el Software Architect y el QA Engineer. El agente prepara la agenda a partir de los diffs del día y registra decisiones contra los IDs de requisito. - Abrir un pull request sobre los archivos de requisitos. GitHub Copilot Code Review comenta sobre el cumplimiento de EARS; los reviewers humanos aprueban el contenido.
- Actualizar el reporte de readiness. Un hook post-merge regenera el reporte con conteos de brechas y listas de bloqueadores.
- Publicar el digest diario de requisitos al canal de producto en Teams a través del Microsoft 365 Agents SDK.
Primitivas recomendadas
Agente
| Agente | Archivo | Propósito |
|---|---|---|
ears-encoder | .github/agents/ears-encoder.agent.md | Descomponer specs en requisitos EARS atómicos, mantener trazabilidad, correr gap scans |
El EARS Encoder usa claude-sonnet-4-6 por defecto. Herramientas: read, edit, search, grep, glob. Sin acceso a bash. El extended thinking se habilita solo para /gap-scan, donde la correlación entre documentos se beneficia de un razonamiento profundo.
Slash prompts
| Comando | Archivo | Propósito |
|---|---|---|
/ears | .github/prompts/ears.prompt.md | Descomponer una sección del spec en requisitos EARS atómicos |
/traceability | .github/prompts/traceability.prompt.md | Amarrar requisitos a pruebas, PRs y despliegues, regenerar la matriz |
/gap-scan | .github/prompts/gap-scan.prompt.md | Detectar requisitos sin pruebas, pruebas sin requisitos, despliegues huérfanos |
/requirement-review | .github/prompts/requirement-review.prompt.md | Preparar y registrar la sesión de revisión estructurada |
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 |
|---|---|---|
docs/requirements/**/*.md | .github/instructions/requirements.instructions.md | Formato EARS atómico, esquema de IDs, reglas de referencias cruzadas |
docs/traceability/**/*.md | .github/instructions/traceability.instructions.md | Esquema de matriz, reglas de regeneración, formato de evidencia para auditoría |
docs/reviews/**/*.md | .github/instructions/reviews.instructions.md | Plantilla de agenda de revisión, formato de registro de decisión |
Hooks
Los hooks cuestan cero tokens de LLM. Son la capa de gobierno más fuerte para los requisitos.
pre-commit: rechazar cualquier archivo de requisito con cláusulas no atómicas o no EARS, o con IDs duplicadospost-commit: regenerar la matriz de trazabilidad y el reporte de readinesspre-merge: bloquear el merge de cualquier cambio de requisitos que introduzca una nueva brecha sin un issue de seguimiento enlazado
MCPs validados
| MCP | Propósito | Dueño |
|---|---|---|
| GitHub MCP Server | Leer pull requests, pruebas y corridas de Actions para poblar la matriz de trazabilidad | GitHub (oficial) |
| Azure DevOps MCP Server | Leer work items y planes de prueba en Azure Boards cuando el equipo usa Azure DevOps | Microsoft (oficial) |
| Azure MCP Server | Consultar Application Insights para confirmar que los artefactos desplegados coincidan con los IDs de requisito | Microsoft (oficial) |
| Microsoft Learn Docs MCP | Anclar requisitos sobre superficies de productos Microsoft en documentación vigente | Microsoft (oficial) |
| Microsoft 365 Agents SDK MCP | Levantar hilos de aclaración en Teams y registrar decisiones desde Outlook | Microsoft (oficial) |
Ejemplos reales
Ejemplo 1: descomponer una sección de spec aprobada
Entrada: Una sección de spec sobre renovación de contrato que cubre iniciación, elegibilidad y notificación, aprobada por el Product Owner.
Invocación: /ears seguido de /traceability.
Salida esperada:
- Un directorio
docs/requirements/contract-renewal/con doce archivos de requisitos atómicos, cada uno con un ID único y una cláusula EARS estricta. - Una matriz de trazabilidad regenerada que amarra tres pruebas preexistentes a dos de los nuevos requisitos y marca los diez restantes como brechas.
- Un pull request con comentarios de Copilot Code Review sobre la forma de las cláusulas y la consistencia de los IDs.
Ejemplo 2: cierre de brechas antes del release
Entrada: Un release candidate con 146 requisitos fusionados. El reporte matutino de /gap-scan marca seis requisitos sin pruebas pasando y dos pruebas sin requisitos.
Invocación: /gap-scan seguido de /requirement-review.
Salida esperada:
- Seis tareas en GitHub Projects creadas vía el MCP de GitHub, cada una enlazada al ancla del requisito y asignadas al QA Engineer.
- Dos archivos de requisitos redactados para amarrar las pruebas huérfanas a IDs de requisito.
- Una sesión de revisión registrada en
docs/reviews/2026-q3-release-readiness.mdcon decisiones etiquetadas por ID de requisito. - Una actualización del reporte de readiness que reabre la compuerta de release hasta que cierren los ocho ítems.
Anti-patrones
- Requisitos compuestos. Las cláusulas que agrupan dos o más condiciones no se pueden probar atómicamente. Mitigación: el agente
/earsy el hookpre-commitrechazan cláusulas no atómicas. - Trazabilidad manual. Las hojas de cálculo no son confiables al cierre del sprint. Mitigación: la matriz se regenera en
post-commit. - Colisiones silenciosas de IDs. Los IDs reutilizados rompen los rastros de auditoría. Mitigación: el hook
pre-commitrechaza duplicados a través del árboldocs/requirements/. - Revisiones sin registros. Las aclaraciones verbales se evaporan. Mitigación:
/requirement-reviewexige una decisión registrada para cada ítem de la agenda. - Brechas dispensadas verbalmente. Una brecha dispensada sin un ADR o issue de seguimiento reaparece en el release. Mitigación:
pre-mergebloquea la ruta de dispensa.
KPIs y métricas de impacto
| KPI | Línea base | Meta | Medición |
|---|---|---|---|
| Requisitos en EARS atómico | 30 por ciento | 100 por ciento | Linter de requisitos en GitHub Actions |
| Frescura de la trazabilidad, última regeneración | 7 días | < 1 hora | Timestamp del hook post-commit |
| Conteo de brechas en la compuerta de release | 14 | 0 | Reporte de readiness |
| Tiempo de ciclo de revisión de requisitos | 2 semanas | < 1 semana | Timestamps de PR |
| Tasa de pruebas huérfanas | 12 por ciento | < 2 por ciento | Salida del gap scan |
| Tiempo de respuesta a consulta de auditoría | 1 día | < 1 hora | Log de consultas a la matriz de trazabilidad |
Madurez en cuatro niveles
| Nivel | Nombre | Marcadores |
|---|---|---|
| L1 | Manual | Specs en prosa, descomposición ad-hoc, trazabilidad construida a mano |
| L2 | Asistido | Copilot usado para pulir el fraseo de requisitos, sin disciplina atómica |
| L3 | Aumentado | Agente EARS Encoder, cuatro slash prompts, instrucciones con alcance, matriz auto-generada, gap scans en PR |
| L4 | Autónomo | Kit completo de primitivas, hooks forzados, reporte de readiness en vivo, revisiones registradas automáticamente, respuesta de auditoría dentro de la hora |
Integración con otras personas
- Desde Product Owner:
SPECIFICATION.mdaprobado con requisitos EARS numerados como entrada canónica - Desde Business Manager: resultados ligados a KPI que informan la priorización de brechas
- Hacia Software Architect: IDs de requisito estables que anclan
CODEMAP.mdy los contratos de API - Hacia QA Engineer: requisitos atómicos que dirigen la generación de casos de prueba y reportes de cobertura
- Hacia Developer: ancla del requisito en cada PR habilitando la trazabilidad de implementación
- Hacia Compliance Auditor: matriz regenerada como evidencia de auditoría a demanda
- Hacia Release Manager: reporte de readiness que controla el corte de release
Glosario
- EARS: Easy Approach to Requirements Syntax. La forma canónica
WHEN ... THE system SHALL .... - Requisito atómico: una cláusula testable única con un ID único, sin conjunciones que introduzcan condiciones independientes.
- Matriz de trazabilidad: tabla generada que amarra cada requisito a criterios de aceptación, pruebas, pull requests y despliegues.
- Gap scan: barrida automatizada que detecta requisitos sin pruebas, pruebas sin requisitos y despliegues sin ninguno.
- Reporte de readiness: documento generado que resume el estado de la compuerta de release contra brechas de requisitos abiertas.
- Revisión de requisitos: sesión estructurada y registrada que aprueba o difiere cambios de requisitos con participantes nombrados.
Referencias
- GitHub Copilot documentation — agent mode, prompts e instructions
- Azure Boards documentation — seguimiento de work items para tareas enlazadas a requisitos
- GitHub Actions documentation — automatización para regeneración de trazabilidad y gap scans
- Application Insights documentation — telemetría de artefactos desplegados para verificación de requisitos
- Microsoft Learn, Well-Architected Framework — guía de excelencia operativa y evidencia de auditoría