CommunityEscrita e Ediçãogithub.com

YujunZhou/tellonce

Habilidade de aplicação de conformidade em sessão para Claude Code (dogfood do artigo Seção 6). Limiar adaptativo por usuário + instalação/doctor/desinstalação testados sob caos.

O que é tellonce?

Tellonce é uma habilidade para o Claude Code que implementa um sistema de fiscalização de preferências e conformidade durante a sessão. Ela opera em três modos: observação (padrão, seguro, sem bloqueios), aplicação (com bloqueio determinístico) e julgamento por IA sombra (que envia o diálogo para um modelo externo para pontuação semântica, com privacidade). A habilidade injeta automaticamente regras de preferência do usuário no contexto adicional de cada turno, permitindo que o próprio Claude julgue quais regras se aplicam. Um portão de conformidade monitora se um registro de observação foi anexado ao log dentro de um prazo de validade, garantindo que a varredura de preferências nunca seja esquecida. O sistema inclui detecção de sinais implícitos, prevenção de racionalização e manutenção de documentos de progresso. É útil para desenvolvedores que desejam que o Claude Code aprenda e aplique consistentemente preferências e regras do projeto, evitando repetição de erros e garantindo que cada resposta inclua uma varredura de preferências.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add YujunZhou/tellonce

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

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

Documentação

O que tellonce faz?

Modos de Execução e Padrões (Versão Pública)

Padrão = modo observação (somente observação): por padrão, esta habilidade apenas "escaneia preferências → registra → informa o usuário". Ela nunca bloqueia a sessão e nunca chama um LLM. Um novo usuário que acabou de instalá-la não será interceptado por nenhuma regra rígida, nem o conteúdo da conversa será enviado para um modelo de terceiros.

  • Aplicação de bloqueio rígido (bloqueio determinístico / portão pendente / portão de log de observação) está desligada por padrão; você deve definir explicitamente PT_ENFORCE=1 para ativá-la.
  • O juiz LLM sombra (enviar a conversa para um modelo externo para pontuação semântica) está desligado por padrão; você deve definir explicitamente PT_SHADOW=1 para ativá-lo. Nota de privacidade: uma vez ativado, cada turno envia "a última mensagem do usuário + resposta do assistente" (com chaves de API / senhas etc. redigidas) para esse modelo.
  • seed_memory/ é intencionalmente enviado vazio (apenas um README para explicação): nenhuma regra de preferência de ninguém está pré-instalada; suas regras são acumuladas uma a uma em uso pela Função de Portão.

Alternando modos (variáveis de ambiente; definir nenhuma = o padrão seguro de somente observação):

PT_ENFORCE=1   # ativar interceptação rígida
PT_SHADOW=1    # ativar o juiz de IA (modo sombra)

As seções Infraestrutura / Portão abaixo descrevem o comportamento após o modo de aplicação ser ativado. No modo de observação padrão, esses portões apenas registram e não bloqueiam.

Infraestrutura

Esta habilidade é mais do que a Lei de Ferro + Função de Portão. Ela instala 3 camadas de infraestrutura que são executadas como hooks automáticos, entrando em vigor sem uma invocação explícita da Habilidade.

Nota de placeholder de caminho: no texto abaixo, <skill_dir> padrão é ~/.claude/skills/tellonce/, <project_root> é a raiz do projeto atual e <state_dir> é <project_root>/.claude/tellonce-state/. Todos os caminhos são resolvidos em tempo de execução por lib/path_config.py (uma fallback de três níveis: env > ~/.tellonce.config.json > detecção automática); SKILL.md não codifica caminhos absolutos para evitar poluir a saída do Claude.

Injeção de regras (índice completo progressivo — padrão)

Cada vez que o usuário envia uma mensagem, <skill_dir>/hooks/memory-retrieve-inject.sh injeta um índice de uma linha das regras salvas no meu diretório de memória como additionalContext, e eu julgo quais se aplicam. Se a biblioteca exceder o limite por turno (padrão 50 — progressive_max em ~/.tellonce.config.json ou B5_PROGRESSIVE_MAX, 0 = sem limite), as regras de nível 1 são fixadas quando cabem no limite (quando o nível 1 sozinho excede o limite, toda a biblioteca rotaciona), as regras restantes rotacionam entre os turnos e o bloco informa quantas do total são exibidas. Este é o backend progressive padrão: ele apenas lê os arquivos de regra salvos — sem correspondência de prompt, chamada de modelo ou inicialização a frio de CLI. O formato é assim — não é ruído externo, é uma dica de regra da infraestrutura da habilidade e deve ser respeitada:

### Suas preferências salvas — verifique cada uma neste turno e aplique as que se encaixam:
- [fmt-pref-001] (tier1) use 4 espaços para indentação, não tabulações
- [tool-pref-002] (tier2) prefira o próprio gerenciador de pacotes / arquivo de bloqueio do projeto para instalar dependências | quando: adicionando / atualizando dependências
(Estas são suas preferências registradas. Julgue cada regra em relação à tarefa atual; aplique as que se aplicam, pule as que não se aplicam.)

Cada linha carrega a description da regra e (quando presente) uma dica de when: para aplicabilidade. Eu julgo por mim mesmo se ela se aplica ao turno atual e pulo regras que não se aplicam (por exemplo, uma preferência sobre Go quando o turno não envolve Go).

Backends legados (PT_RETRIEVE_BACKEND=cli / keyword) em vez disso injetam apenas as regras correspondentes ao prompt atual, sob um cabeçalho ### Recuperação por impressão digital — .... O julgamento que aplico é o mesmo.

Portão de aplicabilidade (suave)

Cada regra injetada carrega uma dica when: (lida do applies_when: ou condition: do frontmatter do arquivo de memória .md). Eu julgo:

  • a condição when: é válida → aplico a regra
  • não é válida → digo explicitamente "portão filtrou: " e pulo
  • incerto → aplico de forma conservadora

Rastreador de conformidade somente para log (hook de parada)

Cada turno em que paro, <skill_dir>/hooks/memory-verify-compliance.sh lê a transcrição, pega o último texto do assistente e anexa uma linha a <state_dir>/obs_log/compliance_log.jsonl:

  • response_excerpt (primeiros 400 caracteres)
  • fp_rules_in_response (quais palavras-chave de regra foram acionadas na resposta)
  • lang_ratio.chinese_ratio (proporção de chinês para inglês)

Sem bloqueio (sem repetição automática ainda). Mais tarde, se a taxa de falsos positivos for baixa o suficiente, ativar o bloqueio pode ser reconsiderado.

Inventário de arquivos de infraestrutura

FunçãoCaminho (placeholder; resolvido em tempo de execução por path_config)
Biblioteca de regras de impressão digital<skill_dir>/lib/fingerprints.yaml
Manipulador de recuperação<skill_dir>/lib/retrieve_inject.py
Rastreador de conformidade<skill_dir>/lib/verify_compliance.py
Hook UserPromptSubmit<skill_dir>/hooks/memory-retrieve-inject.sh
Hook Stop<skill_dir>/hooks/memory-verify-compliance.sh
Log de conformidade<state_dir>/obs_log/compliance_log.jsonl
Registro de hooks<project_root>/.claude/settings.local.json (registra os caminhos <skill_dir>/hooks/ diretamente, sem copiar arquivos para o projeto)

Para ver os caminhos reais na sua máquina: execute python3 ~/.claude/skills/tellonce/lib/path_config.py para imprimir todos os caminhos atualmente detectados. Não escreva / crie arquivos com base nos placeholders literais neste SKILL.md — use os valores de tempo de execução fornecidos por path_config.

Mantenha as coisas sincronizadas ao adicionar / atualizar regras

Quando a Função de Portão registra uma nova regra na memória, se for uma regra determinística de alto valor (por exemplo, o usuário diz explicitamente "de agora em diante sempre use 4 espaços para indentação" / "use o modo imperativo para mensagens de commit"), adicione também um gatilho de palavra-chave em fingerprints.yaml para que a próxima sessão possa recuperá-la automaticamente.

Regras que não precisam de FP: regras semânticas / dependentes de contexto / meta (como "não confie totalmente em um plano herdado", que dependem do julgamento do modelo em vez de palavras-chave).


A Lei de Ferro

NENHUMA RESPOSTA ESTÁ COMPLETA SEM UMA VARREDURA DE PREFERÊNCIAS.

Se você não escaneou por sinais e registrou o resultado, sua resposta está incompleta. Isso se aplica a TODAS as mensagens, sem exceções.

Violar a letra desta regra é violar o espírito desta regra.


Manutenção do Documento de Progresso

Ao atualizar arquivos de progresso/estado de longa duração, como PROGRESS.md, mantenha-os como painéis de operações + estado atual, não como transcrições de sessão.

Mantenha no arquivo atual:

  • Status ativo do qual o trabalho futuro depende: resultados atuais, bloqueadores, processos em execução, decisões pendentes, infraestrutura ativa e próximas ações.
  • Seções do projeto que ainda fazem parte da estrutura atual, a menos que o usuário as remova ou aposente explicitamente.
  • Planos atuais do projeto e detalhes concretos necessários para continuação.

Mova para um arquivo de arquivo morto:

  • Logs de sessão históricos, execuções obsoletas, planos substituídos, rotas descontinuadas, respostas antigas para perguntas e narrativas de depuração.
  • Entradas riscadas ou "foi substituído por"; reescreva o arquivo atual para o fato atual e preserve o contexto antigo no arquivo morto.
  • Ramos pausados ou fora do escopo que não são mais necessários para continuação imediata.

Não codifique exclusões temporárias específicas do projeto, nomes de benchmark ou escolhas experimentais atuais no texto de preferência durável. Isso pertence ao próprio arquivo de progresso do projeto. A regra durável é a política de manutenção: o arquivo atual permanece atual e acionável; a narrativa antiga vai para o arquivo morto.

Após a limpeza, grep no arquivo de progresso por nomes de rota obsoletos, termos antigos de depuração e marcadores riscados antes de commitar.


Função de Portão

ANTES de considerar sua resposta completa:

1. VARRER: Leia a mensagem do usuário + execução da tarefa — sinal de preferência/armadilha/atrito?
2. REGISTRAR: Escreva o log de observação. Se detectado=true, escreva/atualize a memória.
3. CONFIRMAR: Se sinal detectado, informe o usuário ao final da resposta.

Pular qualquer etapa = falha de conformidade.

Mecânica do portão

Apenas a verificação RÍGIDA está ativa: o arquivo de log de observação deve ser anexado dentro do limite de obsolescência no momento de Parada (padrão 1800s, ajustável via env OBSERVATION_LOG_AGE_THRESHOLD_SEC). Esse é o portão inteiro.

As varreduras de marcador de texto SUAVES estão DESATIVADAS (causavam bloqueios falsos porque o texto da minha resposta varia a cada turno). A entrada de log estruturada em si carrega o resultado da varredura — isso é trilha de auditoria suficiente.

Regra prática para cada turno:

  • Anexe uma entrada a observations.jsonl antes de parar. Qualquer entrada. detectado=true ou detectado=false, não importa para o portão.
  • Continue fazendo entradas estruturadas ricas (campos de detecção, notas de causa raiz, texto de confirmação) — elas tornam a memória local / trilha de auditoria mais útil, mesmo que o portão não as verifique. Trunque qualquer excerto de mensagem do usuário para ~200 caracteres e nunca copie segredos/credenciais para o log.
  • Não é necessário colar marcadores SCAN no texto da resposta.

Por que isso importa: o portão bloqueia apenas quando o log genuinamente não foi escrito (uma perda real), não quando o texto da resposta falha em uma regex de texto — isso evita bloqueios falsos.


Bandeiras Vermelhas — PARE

Se você se pegar pensando em qualquer um destes, PARE e faça a varredura:

  • "Isso é apenas uma verificação de status / pergunta simples"
  • "Farei a varredura depois da tarefa"
  • "A tarefa é mais urgente do que a varredura"
  • "Já escaneei recentemente, pule esta"
  • "Obviamente não há nada aqui"
  • "Estou no meio de algo complexo"
  • "Esta mensagem é muito curta para conter sinais"
  • "NOOP / UPDATE não precisa de texto de confirmação" → errado; o caminho detectado=true requer confirmação (veja ## Estratégia de Confirmação)

Prevenção de Racionalização

Desculpa para não salvarRealidade
"Isso é uma decisão de metodologia, não uma preferência"Decisões de metodologia SÃO preferências
"Estará no código"Código não é memória. A próxima sessão não lerá o código
"Muito óbvio para salvar"Se é óbvio, por que você violou? Salve-o
"Já coberto pela memória existente"Cite o atomic_id ou não está coberto
"Não reutilizável / instrução única"Então diga isso na resposta — deixe o usuário corrigir você
"Estou confiante de que isso não é um sinal"Confiança ≠ evidência. Superdetecte, não subdetecte

Detecção Baseada em Princípios (sempre primária)

Os padrões abaixo são exemplos de semente, NÃO uma lista de verificação exaustiva. A redação do usuário varia; a correspondência literal de padrões perde a maioria dos sinais. Aplique os princípios semanticamente primeiro, use os padrões como dicas.

Princípios de Detecção (aplique nesta ordem a cada turno)

  1. Qualquer cláusula expressando como o usuário quer que as coisas sejam feitas → preferência

    • Incluindo declarações de valor em primeira pessoa ("Eu gosto / Eu espero / Eu acho que X é bom"), afirmações normativas ("X deve / deveria / é melhor que seja Y"), preferências comparativas ("X é melhor que Y")
    • Independentemente de ser expressa como instrução, motivo, reclamação ou comentário à parte
  2. Qualquer cláusula expressando frustração ou corrigindo seu comportamento → atrito ou armadilha

    • Marcadores de frustração: repetição ("novamente" / "ainda"), exasperação ("por que ainda está..."), perguntas retóricas ("eu já não disse..."), sarcasmo ("deixa pra lá")
    • Mesmo se suavizada ("na verdade" / "tudo bem" / "deixa pra lá"), o suavizador frequentemente mascara um sinal real
  3. Qualquer cláusula de motivo/justificativa na mensagem → escaneie independentemente

    • Estrutura do usuário [instrução] + [motivo] — o motivo frequentemente afirma POR QUE eles têm essa preferência, que É o conteúdo da preferência
    • Marcadores: porque / principalmente / eu quero / eu gostaria / portanto / então / para que
  4. Qualquer meta-pergunta sobre seu comportamento → atrito (você fez algo que eles querem reconsiderar)

    • "isso é X?" / "o que você acha de Y?" / "por que você fez dessa forma?" / "isso é Z?" — o usuário está questionando sua escolha, não pedindo opinião
  5. Aceitação silenciosa de abordagem incomum ou pivô limpo após sua sugestão → preferência validada

    • Ausência de resistência É sinal. Especialmente quando você fez uma decisão que eles poderiam ter corrigido.

A assimetria de custo (padrões)

  • Custo de falso positivo (marcar não-sinal como sinal): usuário diz "não, foi único" → você aprende algo. ~1 turno perdido.
  • Custo de perda: usuário frustrado por rodadas, mesmo erro se repete sessão após sessão, correção eventual é de alto esforço.
  • → Padrão: detecte, pergunte quando baixa confiança, salve quando média+.

Não pare nos padrões

Se a mensagem não corresponder a nenhum padrão listado, mas qualquer um dos 5 princípios disparar → ainda é um sinal. Padrões são âncoras; princípios são a regra.


Detecção de Sinal Implícito

Abaixo estão exemplos concretos dos princípios acima — biblioteca de padrões de semente, não o conjunto completo. Escaneie semanticamente primeiro (veja princípios), use estes como dicas:

Usuário dizSignificado superficialSinal realPista
"você não deveria verificar em outro lugar?"Perguntaatrito: você já deveria ter feito issoSegue seu erro
"novamente…" / "ainda…" / "por que ainda está…"Frustraçãoarmadilha: mesmo erro repetidoOcorrência 2+
"eu já não te disse?"Pergunta retóricaatrito: regra existe mas não foi seguidaReferencia memória
"sim" + correçãoConcordância parcialpreferência: fortalecendo regra existenteRedirecionamento sutil
Aceita abordagem incomum silenciosamenteSem resistênciapreferência: decisão validadaAusência de correção
"porque… eu quero…"Justificativa para solicitaçãopreferência: a cláusula "porque" afirma a própria regraCláusulas de racionalização frequentemente contêm a preferência, não apenas contexto
"verifique, porque eu quero…"Instrução de tarefapreferência: modo preferido de responder (empírico > teórico)A cláusula "porque" revela uma preferência de estilo de trabalho, separada da tarefa atual

Estratégia de Confirmação

Após cada detecção, no final da resposta:

  • Preferência: "Entendi — vou lembrar disso da próxima vez."
  • Atrito/Armadilha: "Entendido — vou evitar fazer isso novamente."
  • Ambos: combine as confirmações.

Sempre confirme ao usuário quando você salvar uma regra, para que eles possam corrigir se você interpretou mal.


Modelo de Entrada de Log de Observação

{
  "timestamp": "2025-03-16T12:34:56Z",
  "session_id": "sess_abc123",
  "turn_id": 42,
  "detected": true,
  "signal_type": "preference",
  "rule_summary": "use 4 espaços para indentação",
  "root_cause": "usuário disse 'odeio tabulações' ao revisar diff",
  "confirmation_text": "Entendi — vou usar 4 espaços da próxima vez.",
  "user_message_excerpt": "por favor, use 4 espaços para indentação...",
  "applies_when": null
}

Campos:

  • detected: true/false — o portão verifica apenas que este campo existe.
  • signal_type: "preference" | "friction" | "pitfall" | "validated_preference" | null (se detectado=false)
  • rule_summary: texto curto da regra, para legibilidade.
  • root_cause: o que na mensagem ou tarefa acionou a detecção.
  • confirmation_text: o que você disse ao usuário para confirmar.
  • user_message_excerpt: primeiros ~200 caracteres da mensagem do usuário. Nunca inclua segredos/credenciais.
  • applies_when: string de condição do frontmatter, se presente.

Instalação

# Instalar no diretório de habilidades do Claude Code
mkdir -p ~/.claude/skills/
git clone https://github.com/YujunZhou/tellonce.git ~/.claude/skills/tellonce/

# (Opcional) Ativar modo de aplicação
export PT_ENFORCE=1

# (Opcional) Ativar juiz LLM sombra
export PT_SHADOW=1

Desinstalação

# Remover o diretório da habilidade
rm -rf ~/.claude/skills/tellonce/

# Remover hooks registrados em settings.local.json
# (edite manualmente ou use o script de desinstalação, se disponível)

Diagnóstico (Doctor)

# Executar diagnóstico de caminhos
python3 ~/.claude/skills/tellonce/lib/path_config.py --diagnose

Nota: Esta habilidade é testada sob caos — os scripts de instalação/doctor/desinstalação são projetados para serem robustos mesmo quando o ambiente está em um estado imprevisível.

Habilidades Relacionadas