Registro de Preferências

O que Registro de Preferências faz?

As pessoas tomam dezenas de pequenas decisões enquanto trabalham com um assistente: uma cor, uma biblioteca, uma regra de nomenclatura, "não faça X", "opção B". A maioria nunca é escrita, então na próxima sessão o assistente pergunta de novo ou as desfaz silenciosamente. Esta skill mantém um único arquivo, PREFERENCES.md, que registra cada decisão no momento em que é tomada, para que permaneça válida entre sessões, ferramentas e colaboradores.

Quando agir

Leia PREFERENCES.md antes da sua primeira alteração em um projeto que tenha um, e novamente antes de propor designs, opções ou qualquer coisa que o arquivo já possa ter definido. Siga o que ele diz. Não pergunte novamente sobre algo que já está registrado, a menos que o usuário traga o assunto.

Escreva nele na mesma rodada de trabalho sempre que o usuário:

• afirmar uma preferência ou regra ("Prefiro tabs", "sempre use ortografia britânica", "nunca commitar na main");
• escolher entre opções que você ofereceu ("A", "vai com a segunda", "mistura A e C");
• corrigir ou rejeitar como algo foi feito ("isso está feio", "não, coloque à direita", "errado, só quando…"), desde que a correção indique como deveria ser;
• mudar ou reverter uma decisão anterior;
• tentar algo provisoriamente ("vamos testar isso"): registre marcado como teste.

Não registre:

• instruções pontuais que só se aplicam à tarefa atual ("renomeie esta variável");
• fatos que o código ou histórico já contêm (estrutura de arquivos, qual biblioteca está instalada);
• segredos, credenciais, tokens ou dados pessoais de alguém (endereços, números de identificação, saúde). Registre a decisão, não o valor privado: "use o nome real do usuário no rodapé", nunca o nome em si se for sensível;
• suas próprias sugestões que o usuário não aceitou.

Se você não tiver certeza se algo é uma decisão duradoura, registre-a: uma linha extra curta custa menos do que uma escolha esquecida.

Onde o arquivo fica

PREFERENCES.md na raiz do projeto, a menos que as instruções do agente do projeto (CLAUDE.md, AGENTS.md ou similar) indiquem outro caminho. Sem um projeto (um chat avulso), não crie um arquivo; apenas siga o que o usuário disser.

Se ainda não houver arquivo, crie-o a partir de templates/PREFERENCES.md (ao lado deste arquivo) com a primeira decisão. Em seguida, se o projeto tiver um CLAUDE.md ou AGENTS.md, adicione uma linha perto do topo para que toda sessão futura o leia:

Leia PREFERENCES.md primeiro e mantenha-o atualizado: sempre que uma decisão for tomada ou alterada, edite sua linha e adicione uma entrada no changelog com data, na mesma rodada.

O formato

# <Projeto> — decisões

Uma linha sobre o que este arquivo é.

## <Tópico>
- **<Nome curto da decisão>:** o que foi decidido, em palavras simples. Por quê, quando o usuário disse o motivo. (Anteriormente: o que substituiu, e quando.)

## Registro de alterações
- 17 Out 2026 — <o que foi decidido ou alterado, em uma linha> (palavras deles: "…").

Regras para mantê-lo útil:

1. Uma linha por decisão, agrupada por tópico. Escolha tópicos que se encaixem no projeto (Produto, Design, Stack, Fluxo de trabalho, Escrita, …). Comece com poucos e adicione um quando uma decisão não se encaixar em nenhum.
2. Edite no lugar. Quando uma decisão mudar, reescreva sua linha para refletir o que vale agora e mantenha a escolha anterior em uma breve nota "Anteriormente: …". Nunca deixe duas linhas que discordem.
3. Adicione uma entrada no changelog para cada alteração, a mais nova no final, com data absoluta ("17 Out 2026", nunca "hoje" ou "ontem"). Converta datas relativas ao escrevê-las.
4. Mantenha as próprias palavras do usuário para a parte importante, citadas e curtas: elas resolvem o que foi pretendido depois. Não coloque palavras na boca do usuário nem faça um comentário soar mais forte do que foi.
5. Diga o porquê quando o usuário deu uma razão. Uma razão permite que uma sessão posterior lide com um caso que a regra não previu.
6. Vincule o que a decisão aponta: um design, um issue, um mockup, um commit.
7. Marque testes e incógnitas: "(testando)", "(não final)". Remova a marca quando for confirmado.
8. Escreva de forma clara. Frases curtas, sem jargão que o usuário não usou. Use o nome da pessoa ou "eles", a menos que ela tenha dito quais pronomes usar; não adivinhe a partir do nome.

Quando uma solicitação conflita com o arquivo

A declaração explícita mais recente vence. Se o usuário agora pedir algo que o arquivo descarta, faça o que ele pede e atualize a linha e o changelog. Se for ambíguo se ele pretendia mudar a regra, pergunte em uma pergunta curta, citando a linha registrada.

Avise o usuário brevemente

Depois de atualizar o arquivo, mencione isso em uma cláusula curta no final da sua resposta ("Registrei isso em PREFERENCES.md"), não um resumo do arquivo. Mostre o arquivo completo apenas quando solicitado.

Exemplo

O usuário está escolhendo entre três designs de barra lateral que você mostrou e responde "A, mas os botões devem ser ícones". Na mesma rodada em que constrói:

## Design
- **Barra lateral:** menu compacto; a lista de pastas preenche a altura restante e rola; Configurações e o botão de privacidade são botões de ícone em uma única linha inferior (escolheu A das três opções, com botões de ícone).

## Registro de alterações
- 17 Out 2026 — Barra lateral: opção A, com as ações inferiores como botões de ícone (palavras deles: "A, mas os botões devem ser ícones").

Uma semana depois, o usuário diz "coloque os rótulos de volta nesses botões":

- **Barra lateral:** … Configurações e o botão de privacidade são botões com rótulos em uma única linha inferior. (Anteriormente: apenas ícone, 17 Out 2026.)

- 24 Out 2026 — Botões inferiores da barra lateral recebem seus rótulos de volta (palavras deles: "coloque os rótulos de volta nesses botões").