# 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](./sdr-0003-indice-fonte-unica.md), [REGRAS-AGENTE-E-PROMPTS.md](./REGRAS-AGENTE-E-PROMPTS.md), [sdr-0022-repositorio-convencoes-e-construcao.md](./sdr-0022-repositorio-convencoes-e-construcao.md), [sdr-0025-propagacao-sdr-consumidores-site-contratacao.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](./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](./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](../.cursor/rules/inicio-sessao-agente.mdc): 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`](../.cursor/rules/inicio-sessao-agente.mdc) → comando [`inicio-sessao.md`](../.cursor/commands/inicio-sessao.md) → [`AGENTS.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](./sdr-0025-propagacao-sdr-consumidores-site-contratacao.md) | ### 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](../.cursor/rules/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--*.md`) são a **fonte da verdade normativa** *entre* especificações SDR — ver [REGRAS-AGENTE-E-PROMPTS.md](./REGRAS-AGENTE-E-PROMPTS.md) e [sdr-0003](./sdr-0003-indice-fonte-unica.md). 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](./sdr-0003-indice-fonte-unica.md), 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](./sdr-0025-propagacao-sdr-consumidores-site-contratacao.md), em **objetivo separado** (nova mensagem ou plano claramente delimitado), salvo a exceção do item 1. ### 8.5 Comando e regra Cursor - Comando: [`.cursor/commands/alterar-sdr.md`](../.cursor/commands/alterar-sdr.md) (`/alterar-sdr`). - Regra com `globs` em `SDRs/sdr-*.md`: [`.cursor/rules/sdr-edicao-exclusiva-fonte-verdade.mdc`](../.cursor/rules/sdr-edicao-exclusiva-fonte-verdade.mdc). --- ## 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 - [REGRAS-AGENTE-E-PROMPTS.md](./REGRAS-AGENTE-E-PROMPTS.md) — ordem de trabalho; remissão a este SDR para o passo “planejar”. ### 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](../.cursor/rules/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](./sdr-0025-propagacao-sdr-consumidores-site-contratacao.md) 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`](../.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`](../.cursor/commands/inicio-sessao.md) | Checklist de início de sessão (único comando) | | RF-002 | [`AGENTS.md`](../AGENTS.md) | Mapa para agentes | | RF-001 | [REGRAS-AGENTE-E-PROMPTS.md](./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/rules/sdr-edicao-exclusiva-fonte-verdade.mdc), [`.cursor/commands/alterar-sdr.md`](../.cursor/commands/alterar-sdr.md), [sdr-0025](./sdr-0025-propagacao-sdr-consumidores-site-contratacao.md) | 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](./sdr-0003-indice-fonte-unica.md)) - [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`](../.cursor/rules/sdr-conformity-checker.mdc) | [`sdr-conformity-checker.md`](./governance/rules/sdr-conformity-checker.md) | | Detector de implementação sem vínculo SDR | [`implementation-without-sdr-detector.mdc`](../.cursor/rules/implementation-without-sdr-detector.mdc) | [`implementation-without-sdr-detector.md`](./governance/rules/implementation-without-sdr-detector.md) | | Anti-vibecoding sem SDR | [`no-vibecoding-without-sdr.mdc`](../.cursor/rules/no-vibecoding-without-sdr.mdc) | [`no-vibecoding-without-sdr.md`](./governance/rules/no-vibecoding-without-sdr.md) | **Processo:** [`governance/README.md`](./governance/README.md) · **Rastreabilidade código:** [`traceability.md`](./traceability.md) · **Checagem:** `python scripts/check_sdr_conformity.py` (na raiz do repositório).