SDR-0021 — Planejamento obrigatório antes de alterações no repositório (agentes)

Página estática gerada a partir do Markdown do repositório — o texto abaixo já vem no HTML (adequado a importação por URL em ferramentas que não executam o ver-md.html). Arquivo: sdr-0021-planejamento-pre-alteracao-agente.md

Baixar o .md — Abrir no visualizador Markdown — Catálogo de SDRs — Início do site

Fonte: SDRs/sdr-0021-planejamento-pre-alteracao-agente.md

SDR-0021 — Planejamento obrigatório antes de alterações no repositório (agentes)

Nomenclatura: arquivo físico sdr-0021-planejamento-pre-alteracao-agente.md. Norma para uso de agentes de IA (ex.: Cursor) sobre quando planejar antes de mutar o projeto.

1. Metadados

Campo Valor
ID sdr-0021-planejamento-pre-alteracao-agente
Título Planejamento obrigatório antes de alterações no repositório (agentes)
Versão v0.4
Data 2026-05-03
Autor Equipe do repositório (norma de fluxo de agente)
Revisores (pendente)
Status Em validação
Substitui —
Substituído por —
Classificação Interno
Eixo Ambos
Domínio Governança de fluxo de trabalho com agentes; integridade do repositório
Stakeholders Quem opera o repositório via Cursor ou outro agente; revisores de PR
SDRs relacionados sdr-0003-indice-fonte-unica.md, REGRAS-AGENTE-E-PROMPTS.md, sdr-0022-repositorio-convencoes-e-construcao.md, sdr-0025-propagacao-sdr-consumidores-site-contratacao.md

2. Controle de Revisão

Versão Data Autor Mudanças
v0.1 2026-05-01 Equipe do repositório Criação: planejamento pré-alteração e vínculo com início de sessão
v0.2 2026-05-01 Equipe do repositório Modo Planejamento (Cursor) como primeiro passo ante mutação; formato único de plano + confirmações na regra Cursor
v0.3 2026-05-02 Equipe do repositório Fluxo 8.3: mutações só em modo Agente; Ask/Plan somente leitura — alinhado a inicio-sessao-agente.mdc
v0.4 2026-05-03 Equipe do repositório §8.4–8.5: edição exclusiva de sdr-*.md normativos; comando /alterar-sdr; remissão a SDR-0025 (propagação)

3. Objetivo

Garantir que toda sequência de ações de um agente que resulte em alteração de arquivos ou de estado versionável do projeto seja precedida de planejamento explícito na conversa, reduzindo retrabalho, diffs amplos sem intenção e conflito com SDRs ou arquitetura.

4. Escopo e Abstração

4.1 Dentro do escopo

  • Comandos do usuário, comandos slash (ex.: /inicio-sessao) e pedidos em linguagem natural que levem o agente a editar, criar, apagar ou refatorar arquivos do workspace.
  • Uso de ferramentas equivalentes a escrita em massa (apply_patch, escrita de arquivo, exclusão, refatoração coordenada).
  • Início de sessão: quando a sessão for alinhada por comando de início ou primeira tarefa com intenção de edição, o agente deve aplicar esta norma a toda alteração da sessão (não apenas à primeira).

4.2 Fora do escopo

  • Leitura, busca, explicação de código ou revisão sem mutação — não exige plano normativo (o agente pode planejar mentalmente).
  • Ações humanas fora do agente (commits manuais, merges no Bitbucket sem IA) — recomenda-se alinhamento de equipe, mas não é objeto deste SDR.
  • Detalhe de o que editar em cada domínio de negócio — donos continuam nos SDRs temáticos e em REGRAS-AGENTE-E-PROMPTS.md.

4.3 Nível de abstração

Política de processo para agentes; não substitui aprovação de conteúdo de contratação nem revisão humana de PR.

4.4 Implementação de software

Este SDR não exige linhas em traceability.md nem comentários SDR: em código de produto: a norma aplica-se a regras e fluxo do agente (metadocumentação operacional). O vínculo à implementação “no código” está nas regras Cursor listadas na seção 18 e na coluna da seção 17.2.

5. Contexto e Síntese Executiva

5.1 Problema

Pedidos ambíguos ou execução imediata sem plano tendem a gerar alterações desalinhadas, escopo excessivo (“drive-by refactors”) e dificuldade de revisão.

5.2 Solução proposta (resumo)

Planejar antes de mutar: o agente expõe brevemente objetivo, escopo (arquivos/pastas), passos e riscos antes da primeira ferramenta de escrita daquele bloco de trabalho; em início de sessão, reconhece que a regra vale para a sessão.

5.3 Benefícios esperados

PRs mais legíveis, menos surpresas para o solicitante, melhor aderência a SDR e a “só o necessário”.

5.4 Riscos se não implementado

Inflação de diff, normas de governança contornadas por pressa e retrabalho na validação.

6. Slides Executivos

  • Planejar → depois mutar — ordem obrigatória para alterações.
  • Início de sessão — regra “ligada” para toda a conversa com edição.
  • Leitura — sem obrigação de plano escrito.

7. Restrições Globais, Não-Funcionais e Critérios de Sucesso

7.1 Restrições técnicas

  • O plano deve ser visível na conversa ou no modo Planejamento do Cursor (equivalente aceito para revisão humana), nunca só como raciocínio interno oculto, salvo indisponibilidade real do canal — nesse caso, registrar na primeira mensagem possível.
  • Planejamento não dispensa início de sessão: confirmações de autor e salvar/merge seguem o formato estruturado daquela regra quando exigidas.

7.2 Restrições de negócio / compliance

Não altera classificação de documentos; apenas disciplina o como o agente altera o repositório.

7.3 Critérios de sucesso mensuráveis

  • Em revisão amostral de conversas com edição: presença de plano antes do primeiro patch/escrita de cada novo objetivo.
  • Regra citada no início de sessão quando o checklist da equipe for executado.

8. Design / Arquitetura

8.1 Visão geral

Norma em camadas: SDR-0021 (canônico entre SDRs para este tema) → regra Cursor inicio-sessao-agente.mdc → comando inicio-sessao.md → AGENTS.md.

8.2 Componentes

Componente Papel
Este SDR Fonte única da política “planejar antes de alterar”
.cursor/rules/inicio-sessao-agente.mdc Aplica a política junto ao início de sessão
inicio-sessao.md (comando /inicio-sessao) Checklist único de arranque da sessão
.cursor/rules/sdr-edicao-exclusiva-fonte-verdade.mdc Quando o escopo tocar SDRs/sdr-*.md: reforça pedido dedicado e proíbe mistura com outros objetivos no mesmo plano (salvo exceção explícita)
alterar-sdr.md (comando /alterar-sdr) Atalho de intenção: só alteração normativa em sdr-*.md (Fase A); propagação a consumidores em outro objetivo — ver sdr-0025

8.3 Fluxos

  1. Usuário inicia sessão ou pede alteração.
  2. Se houver intenção de mutação: o agente, no Cursor, solicita o modo Planejamento como primeiro passo quando ainda não estiver nele (ver inicio-sessao-agente.mdc); em seguida publica plano + confirmações no formato estruturado daquela regra (objetivo, escopo, passos, riscos; bloco Confirmações necessárias com autor e salvar/merge).
  3. Implementação: com plano e respostas satisfeitas, a conversa deve estar em modo Agente (execução com escrita); não usar ferramentas de mutação em Ask ou equivalente somente leitura. O modo Planejamento é somente leitura — após o plano, voltar ao modo Agente para apply_patch/terminal mutador.
  4. Executar ferramentas de escrita apenas no passo 3, quando permitido pelo modo do produto.

8.4 Alteração exclusiva de SDRs normativos

Arquivos SDRs/sdr-*.md (e sub-SDRs sdr-<NNNN><letra>-*.md) são a fonte da verdade normativa entre especificações SDR — ver REGRAS-AGENTE-E-PROMPTS.md e sdr-0003.

  1. Pedido dedicado: a mensagem do usuário (ou o comando /alterar-sdr) deve tratar apenas da alteração normativa nos SDRs e metadocumentos inevitáveis do mesmo bloco (ex.: linha no sdr-0003, ajuste de link em outro sdr-*). Proibido combinar, no mesmo plano/objetivo, a edição de sdr-*.md com propagação a site HTML, processo-contratacao/, ANS modelo, TR, Proposta, IMR ou scripts de deploy — salvo exceção explícita do solicitante na conversa, listando arquivo por arquivo (SDRs e consumidores), com aceite do risco de diff amplo.
  2. Planejamento obrigatório: §8.3 aplica-se em cheio (modo Planejamento → plano estruturado → modo Agente para mutar). Não iniciar edição de SDR “de surpresa” no meio de outro comando.
  3. Depois do SDR: alinhar consumidores conforme sdr-0025, em objetivo separado (nova mensagem ou plano claramente delimitado), salvo a exceção do item 1.

8.5 Comando e regra Cursor

9. Processos e Integrações

9.1 Processos afetados

  • Revisão de PR (entradas mais previsíveis).
  • Uso de /inicio-sessao.

9.2 Integrações

9.3 SLAs / tempos

Não prescrito — o plano deve ser proporcional ao pedido (uma frase pode bastar para micro-tarefa localizada).

10. Dados, Modelos e Classificações

10.1 Entidades / glossário

Termo Significado
Alteração no projeto Qualquer mutação persistente no workspace: criar/editar/apagar arquivos; refatoração em lote; comandos de terminal que gravem arquivos versionáveis ou alterem estado Git de forma relevante ao diff.
Planejamento Texto na conversa com: objetivo, escopo (pastas/arquivos afetados), ordem de passos e, se útil, riscos ou dependências relevantes (ex.: SDR dono, proposta ou exceção documentada conforme governança do repositório).
Início de sessão Primeiro alinhamento explícito da sessão (ex.: comando /inicio-sessao ou primeira mensagem com tarefa que vá a edições).
Edição exclusiva de SDR Alteração de sdr-*.md em pedido isolado, com plano prévio, sem misturar propagação a consumidores no mesmo objetivo — §8.4.

10.2 Modelos de dados

Não aplicável.

10.3 Classificações (LGPD, criticidade, etc.)

Não aplicável.

11. Controles de Exclusividade e Risco

11.1 Exclusividade / fonte única

Este arquivo é o único dono, entre sdr-*.md, da política “planejamento obrigatório antes de alterações por agente”. Outros documentos remetem aqui; não repetem a norma como texto canônico paralelo.

11.2 Riscos e mitigação

Risco Mitigação
Fadiga com planos longos Plano proporcional ao tamanho do pedido
Duplicar regra em vários .md Link a este SDR

12. Segurança, LGPD e Auditoria

12.1 Controles de segurança

Planejamento pode mencionar caminhos sem colar segredos (tokens, senhas).

12.2 LGPD / privacidade

Não aplicável diretamente.

12.3 Auditoria / evidências

Histórico da conversa no produto de IA serve como evidência informal de cumprimento.

13. Rastreabilidade e Validação

13.1 Critérios de aceite globais

  • Regra presente na regra Cursor de início de sessão e nos comandos referenciados.
  • Índice de fonte única atualizado.

13.2 Validações automáticas (quando existem)

python scripts/check_sdr_conformity.py — estrutura e metadados deste arquivo.

13.3 Validações manuais

Revisão de conversas ou de checklist interno da equipe.

14. Matriz de Implementações Dependentes e Riscos

Implementação Depende de Risco se atrasar
Agentes seguem plano Regras Cursor carregadas Comportamento inconsistente entre sessões

15. Histórico de Mudanças Governadas

Data Mudança SDR / proposta
2026-05-01 Criação do SDR-0021 v0.1
2026-05-01 v0.2: modo Planejamento Cursor + formato único de confirmações v0.2
2026-05-02 v0.3: execução com escrita só em modo Agente (Cursor) v0.3
2026-05-03 v0.4: §8.4 edição exclusiva de SDRs; /alterar-sdr; RF-006/007; remissão SDR-0025 v0.4

16. Propostas Governadas (alternativas)

  • Modo Planejamento (Plan) do Cursor: adotado como via preferida quando houver mutação: o agente deve solicitar a mudança para esse modo antes das ferramentas de escrita; o conteúdo do plano e as perguntas obrigatórias seguem o modelo estruturado em inicio-sessao-agente.mdc. Se o usuário recusar o modo, o mesmo modelo deve aparecer na conversa antes de mutar — e a mutação em si ocorre em modo Agente, não em Ask.
  • Modo Agente vs Ask: o produto Cursor separa pergunta (Ask, somente leitura) de agente (Agent, execução). Este repositório exige que edições usem o modo Agente após o plano; detalhes na mesma regra Cursor.
  • Planejamento só na primeira edição: rejeitado para este repositório — cada novo objetivo que implique mutação deve ter plano (pode ser atualização breve de um plano anterior).

17. Requisitos

17.1 Requisitos funcionais

ID Requisito Prioridade Aceite quando
RF-001 Antes de qualquer mutação de arquivos do projeto no âmbito do agente, haver planejamento explícito na conversa imediatamente antes das ferramentas de escrita daquele bloco de trabalho Alta Texto de plano visível antes do primeiro patch/escrita do pedido
RF-002 Em início de sessão alinhado por comando ou equivalente, o agente informa que a política de planejamento pré-alteração aplica-se à sessão (para todo pedido subsequente que resulte em alteração) Alta Menção explícita no checklist de abertura
RF-003 Para trabalho somente leitura, o agente não precisa publicar plano por este SDR Média Ausência de ferramentas de mutação
RF-004 Quando houver mutação prevista no Cursor, o agente solicita o modo Planejamento antes das ferramentas de escrita (salvo já estar nesse modo); plano e confirmações no formato da regra de início de sessão Alta SwitchMode para plan ou recusa documentada com mesmo formato na conversa
RF-005 Ferramentas que mutam o repositório só com a conversa em modo Agente do Cursor; não em Ask ou em modo somente leitura; após plano no modo Planejamento, voltar ao Agente para implementar Alta Ausência de apply_patch/terminal mutador fora do modo Agente
RF-006 Alteração de qualquer SDRs/sdr-*.md normativo ocorre em pedido dedicado (recomenda-se /alterar-sdr), sem misturar no mesmo plano propagação a site/contratação, salvo exceção explícita listando todos os arquivos — §8.4 Alta Plano ou conversa demonstram separação ou exceção documentada
RF-007 Após fechar o bloco de edição de SDRs, propagação a consumidores segue sdr-0025 em objetivo distinto, salvo exceção §8.4 Média Ordem Fase A → Fase B evidenciada em PR ou mensagens

17.2 Rastreabilidade implementação ↔ requisito

Requisito Arquivo / componente Observação
RF-001, RF-002, RF-004, RF-005 .cursor/rules/inicio-sessao-agente.mdc Norma operacional do agente; modelo Plan + modo Agente para escrita
RF-001, RF-002, RF-004, RF-005 .cursor/commands/inicio-sessao.md Checklist de início de sessão (único comando)
RF-002 AGENTS.md Mapa para agentes
RF-001 REGRAS-AGENTE-E-PROMPTS.md (seção 4) Passo “planejar” com link ao dono
RF-006, RF-007 .cursor/rules/sdr-edicao-exclusiva-fonte-verdade.mdc, .cursor/commands/alterar-sdr.md, sdr-0025 Edição exclusiva + propagação

17.3 Requisitos não-funcionais

ID Requisito Métrica
RNF-001 Proporcionalidade do texto de plano Revisor julga adequação ao tamanho do pedido

18. Checklist de Governança

  • [x] Metadados completos (seção 1)
  • [x] Status coerente com o ciclo de vida (Em validação)
  • [x] Sem duplicar norma já dona em outro sdr-*.md (ver sdr-0003)
  • [x] Política “somente documentação” para código de produto declarada na seção 4.4
  • [ ] Revisores e data de aprovação quando Status: Aprovado

Agentes de conformidade (Cursor)

Agente Regra Cursor Norma em SDRs/governance/rules/
Verificador de conformidade SDR sdr-conformity-checker.mdc sdr-conformity-checker.md
Detector de implementação sem vínculo SDR implementation-without-sdr-detector.mdc implementation-without-sdr-detector.md
Anti-vibecoding sem SDR no-vibecoding-without-sdr.mdc no-vibecoding-without-sdr.md

Processo: governance/README.md · Rastreabilidade código: traceability.md · Checagem: python scripts/check_sdr_conformity.py (na raiz do repositório).