declare-when-a-setting-takes-effect
Um controle que salva com sucesso e não muda nada até reiniciar é pior que um que falha. Diga quando ele passa a valer, e derive isso de onde o valor é lido.
Conferida por quem revisou e leu o cartão, não reivindicada pelo próprio arquivo. Um cartão que o agente destila durante uma execução que consumiu conteúdo não confiável nasce contaminado e fica retido para revisão antes de alguma vez ser recuperado.
Quando ele vem à mente
- criando uma tela de configurações
- a config está em cache
- por que minha mudança não pegou
- exige reiniciar
Evite e Verifique são onde costuma estar o valor. Faça é a seção que todo mundo escreve.
O corpo do cartão acima é uma tradução. O original em inglês é o que a CLI importa, o que o agente lê em execução e o que o hash abaixo atesta.
Gatilho
Você está expondo uma configuração numa interface de usuário, e o código que a consome lê o valor em algum momento que não é a cada uso: na inicialização do processo, na construção de uma sessão, ou dentro de um objeto em cache.
Não se aplica a uma configuração lida a cada uso. Essas se aplicam imediatamente e não devem dizer nada — uma nota sobre um atraso que não existe ensina a mesma desconfiança que uma nota ausente.
Faça
- Para cada configuração, encontre a linha que a lê. Quando ela passa a valer é uma propriedade dessa linha, não do controle na interface.
- Prefira fazer a leitura ao vivo. Uma propriedade que resolve no momento do acesso geralmente não custa nada e remove o problema em vez de apenas descrevê-lo.
- Onde genuinamente não for possível — algo é iniciado no boot — rotule isso, e gere o rótulo a partir do servidor ou do mesmo módulo que conhece o ponto de leitura, para que o rótulo não possa divergir com o tempo.
- Agrupe os rótulos em classes com significado: aplica agora, aplica na próxima conversa, aplica depois de um reinício.
Evite
Uma tela de configurações que confirma o salvamento e silenciosamente não faz nada. É pior que um erro: um erro manda o usuário procurar uma causa, enquanto um sucesso o manda culpar a feature, o modelo, ou a si mesmo.
Evite fixar (hard-coding) a lista de "precisa reiniciar" na interface. Essa lista é uma cópia de um conhecimento que vive em outro lugar, e ela envelhece na primeira vez que o ponto de leitura muda de lugar — silenciosamente, que é exatamente como o problema original foi criado.
Evite uma nota genérica do tipo "algumas configurações exigem reinício". É verdadeira, inútil, e cobre também as que não exigem.
Verifique
Mude a configuração, use a feature, e observe o comportamento — não a tela. Leia um valor de volta a partir do sistema em execução, não a partir do formulário que você acabou de enviar.
A versão mecânica: afirme que nenhuma configuração está rotulada como imediata, e que toda configuração que a interface expõe aparece na classificação que o servidor publica.
Risco
Rótulos adicionam ruído a uma tela de configurações, e uma tela em que toda linha tem um selo é uma tela em que os selos não significam nada. Só as configurações com atraso precisam de um.
O risco mais profundo é tratar o rótulo como se fosse a correção. Declarar que um controle fica inerte até o reinício é honesto; torná-lo ao vivo é melhor, e o rótulo não deveria virar um jeito confortável de evitar a mudança mais difícil.
Como usar
O cartão é dado. Clone o repositório e importe pelo caminho — o que chega pela rede é tratado como contaminado e fica retido para aprovação, que é o comportamento desejável e a razão de não haver um instalador de uma linha aqui.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/declare-when-a-setting-takes-effect/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
2f1c9fd86ac24a61af75b11945b5042d1a2b53ef081cd9a87c3031d5fa97fcf3