Melhoria nas instruções do agente: documentos secundários e modo speckit.update

[marciohernandez]

Luiz, bom dia!

Quero te contar uma evolução que fiz no framework enquanto trabalhava no meu projeto.

Contexto importante: estou iniciando na programação e estudando arquitetura de software agora, então minha relação com o TECH_STACK.md é diferente da de alguém com experiência. Enquanto eu usava o framework, percebi que nem todas as informações que precisava registrar eram decisões arquiteturais no sentido estrito — algumas eram valores operacionais, outras eram detalhes de implementação que mudam com frequência, e outras ainda eram ideias que ainda não tinham um destino certo.

O problema é que essas informações têm valor real para o desenvolvimento do sistema. Se não há um lugar certo para elas, ou se perdem ou acabam "contaminando" a Constituição com coisas que não são princípios imutáveis.

O que eu fiz:

Adaptei as instruções do agente de IA diretamente no TECH_STACK.md para que ele assuma essa classificação como responsabilidade sua. Agora, ao receber qualquer informação minha, o agente:

1. Classifica automaticamente: isso pertence à Constituição, ao ARCHITECTURE.md, ao RUNBOOK.md ou ao PRICING.md?
2. Apresenta o plano antes de agir: "isso vai para tal arquivo, por este motivo"
3. Aguarda minha confirmação antes de editar qualquer coisa
4. Nunca descarta uma informação — se não couber em nenhum documento existente, registra com uma marcação para revisão futura

O resultado foi a criação dos documentos secundários com critérios claros de onde cada tipo de informação vive:

• ARCHITECTURE.md — mapa técnico vivo do projeto: estrutura de pastas, bibliotecas utilizadas, schema do banco de dados. Evolui conforme o produto cresce.
• RUNBOOK.md — guia operacional: variáveis de ambiente, configurações do servidor, limites de uso, procedimentos de backup e monitoramento. Muda com a operação do sistema.
• PRICING.md — decisões comerciais: planos de assinatura, limites por tier, features disponíveis em cada plano. Muda com a estratégia de negócio.

A Constituição ficou limpa e os detalhes operacionais ficaram organizados em seus devidos lugares.

Abaixo está exatamente como ficou o bloco de instruções do agente no topo do TECH_STACK.md após a atualização:

<!--
=============================================================================
🤖 INSTRUÇÕES PARA O AGENTE DE IA
=============================================================================

Este é o arquivo TECH_STACK.md do framework SpecKit Vibe Coder.
Ele é a CONSTITUIÇÃO do projeto: registra as decisões técnicas e os
princípios arquiteturais oficiais. Toda sugestão de código, todo code review
e toda nova feature respeita o que está escrito aqui.

A Constituição guarda apenas DECISÕES e PRINCÍPIOS IMUTÁVEIS.
Detalhes vivos (que mudam com frequência) vivem nos documentos secundários.

=============================================================================
📚 ECOSSISTEMA DE DOCUMENTOS
=============================================================================

Antes de responder, leia os documentos abaixo conforme a necessidade:

  TECH_STACK.md    (este arquivo) — decisões estratégicas e princípios
  ARCHITECTURE.md  — estrutura de pastas, bibliotecas, adapters, Enums,
                     schema de banco. Evolui com o produto.
  RUNBOOK.md       — variáveis de ambiente, configs do painel admin,
                     rate limits, TTLs, backup, monitoramento.
  PRICING.md       — planos, limites por tier, features por plano.
                     Muda com a estratégia de negócio.

CRITÉRIO — onde cada informação vai:

  ✅ Fica na Constituição se é um princípio imutável que guia decisões.
  📄 Vai para ARCHITECTURE.md se é detalhe de implementação ou mapa atual.
  📄 Vai para RUNBOOK.md se é valor operacional ou procedimento.
  📄 Vai para PRICING.md se é limite de uso ou decisão comercial.
  📝 É ideia ou exploração ainda sem destino? → Registrar em ARCHITECTURE.md
     com o prefixo "📝 NOTA DO OWNER:" para revisão futura.

=============================================================================
👤 SOBRE O USUÁRIO
=============================================================================

O usuário é o owner do produto e está aprendendo programação. Ele toma
decisões de negócio e de produto, mas pode não ter o vocabulário técnico
preciso. Suas observações têm valor mesmo quando não pertencem à Constituição.

Ao receber uma observação do usuário, o agente SEMPRE deve:
1. Classificar: a qual documento ela pertence?
2. Apresentar o plano: o que muda, em qual documento, o que fica de fora.
3. Aguardar confirmação antes de editar qualquer arquivo.
4. NUNCA descartar uma observação — se não couber na Constituição,
   ela vai para o documento secundário correto.

=============================================================================
🚀 MODOS DE OPERAÇÃO
=============================================================================

## MODO 1 — speckit.constitution
Ativado quando o usuário envia o comando: speckit.constitution

O que você deve fazer:
- Ler este arquivo e os documentos secundários integralmente.
- Adotá-los como o guia técnico oficial do projeto.
- Em TODAS as respostas, sugestões de código e decisões de arquitetura,
  respeitar as escolhas documentadas aqui.
- Não sugerir abordagens que contradigam as opções já escolhidas.
- Se uma pergunta ainda tiver DUAS opções (não decidida), alertar o usuário
  que aquela decisão precisa ser tomada antes de avançar naquele tema.

## MODO 2 — speckit.agent
Ativado quando o usuário envia o comando:
  speckit.agent [descrição do projeto]

O que você deve fazer:
1. Ler cada seção e cada pergunta deste arquivo.
2. Com base na descrição do projeto fornecida pelo usuário, escolher a
   opção mais adequada para cada pergunta.
3. No arquivo final, manter apenas a opção escolhida e remover a outra.
4. Logo abaixo da opção escolhida, adicionar uma linha no formato:
   > 💡 Decisão: [justificativa objetiva de 1 a 2 linhas]
5. Identificar o que pertence aos documentos secundários e criá-los ou
   atualizá-los conforme o ecossistema acima.
6. Ao final, apresentar um resumo das decisões tomadas, agrupadas por seção.

## MODO 3 — speckit.update
Ativado quando o usuário envia o comando:
  speckit.update [observação ou mudança]

O que você deve fazer:
1. Classificar a observação conforme o critério acima.
2. Apresentar ao usuário: o que vai mudar, em qual documento, e o que
   fica de fora — antes de qualquer edição.
3. Aguardar confirmação explícita.
4. Após confirmação, editar apenas os documentos indicados.

## FORMATO DAS PERGUNTAS (quando ainda há decisão pendente)
Cada pergunta segue a estrutura:
  ### Título da Pergunta
  Contexto explicativo.
  - Opção A: descrição. _Vibe:_ consequência.
  - Opção B: descrição. _Vibe:_ consequência.

## CRITÉRIOS DE DECISÃO (speckit.agent)
Use os seguintes critérios para guiar as escolhas ao responder como agente:
- Projetos em fase inicial/MVP: priorize simplicidade e velocidade.
- Projetos com equipes pequenas (1–3 devs): evite complexidade desnecessária.
- Projetos com dados sensíveis (financeiro, saúde): priorize segurança e auditoria.
- Projetos SaaS: atenção especial a multi-tenancy, planos e faturamento.
- Projetos com SEO importante: SSR sobre SPA.
- Projetos com alta concorrência esperada: cache, filas e indexação.
- Quando houver dúvida, escolha a opção mais simples e documente a razão.

## REGRA GLOBAL
- Sempre responder em pt-BR — toda comunicação do agente com o usuário,
  incluindo justificativas, resumos e perguntas de confirmação, deve ser
  em português do Brasil.
-->

Achei que valia compartilhar porque essa adaptação pode ser útil para outros alunos que, como eu, estão aprendendo e têm informações valiosas mas não sabem sempre onde encaixá-las na estrutura do framework.