Communitygithub.com

usereportly/decision-memory-skill

Uma skill para agentes que ensina agentes de codificação a ler, escrever e preservar comentários de memória de decisão — notas etiquetadas no código que registram por que um design existe e o que não deve ser quebrado, para que uma edição posterior não possa desfazê-lo silenciosamente.

O que é decision-memory-skill?

O **usereportly/decision-memory-skill** é uma skill projetada para agentes de codificação (como Claude Code, Cursor, Codex, etc.) que atua como uma memória externa para decisões de design. Ela ensina o agente a ler, escrever e preservar comentários de memória de decisão — notas etiquetadas no código que registram por que um design existe e o que não deve ser quebrado. Isso garante que edições futuras não possam desfazer silenciosamente decisões críticas, evitando regressões e mantendo a integridade da base de código. A skill é útil para qualquer equipe que queira documentar decisões de design diretamente no código, tornando o processo de manutenção mais seguro e explícito. Suporta os principais agentes de codificação e funciona analisando o código em busca de comentários com marcadores específicos (por exemplo, `DECISION:`) e orientando o agente a respeitá-los durante modificações.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add usereportly/decision-memory-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que decision-memory-skill faz?

Uma skill para agentes que ensina agentes de codificação a ler, escrever e preservar comentários de memória de decisão — notas etiquetadas no código que registram por que um design existe e o que não deve ser quebrado, para que uma edição posterior não possa desfazê-lo silenciosamente.

Visão Geral

Esta skill permite que agentes de codificação:

  • Leiam comentários de memória de decisão existentes no código.
  • Escrevam novos comentários de memória de decisão ao implementar designs complexos.
  • Preservem comentários de memória de decisão durante edições, evitando que decisões importantes sejam perdidas.

Como Funciona

Os comentários de memória de decisão seguem um formato simples:

// DECISION: Por que esta função existe? Ela gerencia o cache de forma concorrente.
// DECISION: Não remover: esta validação impede ataques de injeção.

A skill instrui o agente a:

  1. Identificar comentários que começam com DECISION: no código.
  2. Antes de modificar qualquer linha, verificar se há um comentário DECISION: associado.
  3. Se houver, ler o comentário e garantir que a modificação não quebre a decisão documentada.
  4. Ao adicionar nova lógica complexa, inserir um comentário DECISION: explicando a razão.

Plataformas Suportadas

  • Claude Code
  • Cursor
  • Codex
  • Outros agentes de codificação baseados em LLM

Exemplo de Uso

// Arquivo: cache-service.js

// DECISION: Usamos um Map em vez de um objeto para evitar riscos de protótipo.
const cache = new Map();

function getFromCache(key) {
  // DECISION: Validamos a chave para evitar acesso a propriedades não intencionais.
  if (typeof key !== 'string' || key.length === 0) {
    return null;
  }
  return cache.get(key);
}

function setCache(key, value) {
  // DECISION: Não remover: esta validação é crítica para segurança.
  if (typeof key !== 'string' || key.length === 0) {
    throw new Error('Chave inválida');
  }
  cache.set(key, value);
}

Boas Práticas

  • Sempre escreva comentários DECISION: ao implementar designs que podem ser quebrados por edições futuras.
  • Use um formato claro: // DECISION: <explicação> ou // DECISION: Não remover: <motivo>.
  • Mantenha os comentários próximos ao código que eles documentam.
  • Ao modificar código existente, verifique se há comentários DECISION: nas proximidades.

Integração com Agentes

Para usar esta skill, adicione o arquivo SKILL.md ao contexto do seu agente de codificação. O agente deve ser instruído a:

  1. Ler o conteúdo da skill antes de começar a codificar.
  2. Aplicar as regras de preservação de comentários durante todo o desenvolvimento.
  3. Documentar novas decisões com comentários apropriados.

Licença

MIT

Habilidades Relacionadas