O que project-registry faz?

PT — Um skill para Claude Code que gerencia um registro pessoal de projetos (~/projects/PROJECTS.json) com logs de desenvolvimento legíveis por IA por projeto (CLAUDE.md): listar, criar, deletar, salvar, retomar sessão, atribuição de decisões, verificação de saúde e reversão de versão a partir de um único menu. O texto da interface é prioritariamente em chinês, mas os comandos funcionam tanto em chinês quanto em inglês e todos os recursos são totalmente funcionais independentemente do idioma (a IA entende ambos). Instalação: npx skills add SUNQSHENG/project-registry ou /plugin marketplace add SUNQSHENG/project-registry.

Visão Geral

Gerencia a lista de projetos registrados em ~/projects/PROJECTS.json, fornecendo funcionalidades de adicionar, remover, modificar, consultar e estatísticas. Os projetos são armazenados como subdiretórios <chave>/ dentro de ~/projects/, cada um contendo um README.md com o contexto e escopo do projeto.

Ao operar um projeto, o diretório de trabalho muda automaticamente para o diretório do projeto correspondente (cd).

Fonte de Dados

~/projects/
  PROJECTS.json    # Lista de registro de projetos (única fonte oficial)
  <chave>/         # Diretório do projeto
    README.md      # Descrição do contexto e escopo do projeto (para humanos)
    CLAUDE.md      # Registro de desenvolvimento do projeto (para IA, carregado automaticamente a cada conversa)

Todos os projetos devem estar localizados no diretório ~/projects/.

Diferença: README.md é para o desenvolvedor/colaborador ver o resumo do projeto; CLAUDE.md é para a IA, registrando decisões, status e contexto durante o desenvolvimento, garantindo que projetos longos não percam informações.

Estrutura do PROJECTS.json

{
  "description": "Lista de projetos — Todos os projetos registrados aqui",
  "updated": "2026-03-01",
  "nextSeq": 3,
  "projects": [
    {
      "seq": 1,
      "key": "pet_hospital_crm_20260301",
      "name": "CRM Hospital Veterinário",
      "status": "Concluído",
      "created": "2026-03-01"
    }
  ]
}

Entrada de Operação

Ao entrar no skill, primeiro execute cd ~ para retornar ao diretório raiz do usuário, depois leia o PROJECTS.json para exibir a lista e um menu simplificado (sem verificação em nível de diretório):

📋 Lista Atual de Projetos (Total: N)
┌─────┬──────────────────────────────┬─────────────────┬──────────────────────┬──────────┬────────────┐
│ Seq │ Chave                         │ Nome             │ Status               │ Data Criação │
├─────┼──────────────────────────────┼─────────────────┼──────────────────────┼──────────┼────────────┤
│ 1   │ pet_hospital_crm_20260301    │ CRM Hospital Veterinário   │ ✅ Concluído            │ 2026-03-01 │
│ 2   │ gym_members_app_20260315     │ App Academia Membros       │ 🔄 Em Andamento      │ 2026-03-15 │
└─────┴──────────────────────────────┴─────────────────┴──────────────────────┴──────────┴────────────┘

> A exibição inicial não faz verificação de diretório, apenas lê o JSON. O status dos diretórios é verificado em lote durante a Verificação MD.

Selecione uma operação (ou digite diretamente sua solicitação):
 - Digite o **número** do projeto (1-99) → Abre o projeto correspondente (ex: 12)
 - 🆕 N. Novo Projeto
 - 🗑️ D. Deletar Projeto
 - 🔍 C. Verificação MD (Verificar todos os projetos em lote)

> Outras solicitações (modificar/pesquisar/estatísticas/atualizar registro/sair/sair/**verificar projeto**/**por que X**) podem ser ditas diretamente na conversa
> ⚠️ **Salvar/Sair atualizará automaticamente o CLAUDE.md** (regra obrigatória)

⚙️ Guia de Configuração Inicial (API Key Opcional)

Ao entrar no skill pela primeira vez:

Verifique se as variáveis de ambiente PR_API_BASE_URL / PR_API_KEY / PR_API_MODEL estão configuradas (printenv)
Não configurado → Cartão AskUserQuestion pergunte: «Deseja configurar uma chave de API para ativar o resumo automático?»
- Configurar (recomendado) → Guie para configurar as três variáveis de ambiente (o README tem exemplos de provedores: DeepSeek / OpenAI / Tongyi / Ollama local)
- Pular → Escreva em <diretório do skill>/config.json (marcar "já pulado", não perguntar novamente)
- Saiba mais → Exibir tabela de comparação de funcionalidades
Após a configuração, o efeito é imediato (não é necessário reiniciar a sessão)

Comparação de Funcionalidades:

Funcionalidade	Sem Chave	Com Chave
Segurança de dados (backup em segundos + commit automático no final da sessão)	✅	✅
Todas as funcionalidades principais (registro/retomada de sessão/atribuição/reversão/verificação)	✅	✅
Resumo automático (diálogo extraído automaticamente → CLAUDE.md atualizado em tempo real)	❌	✅

Digite "configurar API" a qualquer momento para reorientar.

🔍 Identificação Automática do Projeto Atual

Ao entrar no skill, o comando cd ~ já foi executado automaticamente. As operações que precisam localizar o projeto (verificação/modificação/salvar/atualizar registro, etc.) identificam automaticamente o diretório atual:

1. pwd verifica se corresponde a ~/projects/<chave>/
2. Se corresponder → Seleciona automaticamente o projeto
3. Se não corresponder → Seleção manual (por número ou chave)

🧭 Fluxo de Início de Sessão (Restauração de Contexto)

Apenas para operações do tipo "entrar no projeto para trabalhar": Abrir projeto / Verificar / Modificar / Atualizar registro / Salvar / Sair. Operações leves como visualizar detalhes, pesquisar, estatísticas não acionam.

Após entrar no projeto e antes de executar a operação, primeiro revise o contexto e depois continue (evitando perda de informações em projetos longos ou retomada sem saber por onde começar):

Leia o CLAUDE.md do projeto (se existir)
Resuma o progresso anterior: cite o "status atual / último progresso", combinando com o último commit do git log, se necessário
Liste as "próximas ações" (por prioridade 1. 2. 3. …)
Pergunte ao usuário qual delas continuar (use um cartão AskUserQuestion para apresentar as opções de próximas ações), e confirme antes de prosseguir

Exemplo de diálogo (nota abaixo do cartão):

📌 Resumo do Último Progresso: Inicialização do projeto concluída, registro criado
➡️ Próximas Ações (por prioridade):
  1. Completar documento de requisitos
  2. Complementar lista de tarefas
Por qual continuar?

Para projetos novos (CLAUDE.md acabou de ser criado), pode pular a revisão e ir direto para a operação.

📂 Abrir Projeto

Localizar o projeto por número ou chave → Verificar se o diretório ~/projects/<chave>/ existe
cd para o diretório do projeto
Acionar o «🧭 Fluxo de Início de Sessão» (revisar último progresso → confirmar continuação)
Após o usuário começar a trabalhar no projeto, operar conforme necessário (modificar/atualizar registro/salvar/sair)

Detalhes da Operação

📌 Regra de Interação (Obrigatória): Todas as perguntas que exigem uma resposta "sim/não" ou "escolha uma opção" do usuário devem usar a ferramenta AskUserQuestion com um cartão de opções (dois ou mais botões de opção), é proibido usar texto simples para perguntar. Aplica-se a: se deve introduzir grill-with-docs, se deve criar esqueleto de documentação, confirmação de tipo de projeto, confirmação de chave/contexto (de acordo com sugestão ou modificar), confirmação de exclusão, seleção de continuação de sessão (por qual continuar), etc.

🆕 Novo Projeto

Perguntar o nome do projeto + descrição de contexto, gerar a chave: <abreviação_em_inglês>_<AAAAMMDD>
Fazer backup do PROJECTS.json → Criar diretório → Escrever README.md + CLAUDE.md + .gitignore (contendo PROJECTS.json, backups/, *.bak, .memory/)
Registrar no PROJECTS.json (seq = nextSeq, depois nextSeq +1)
cd para o diretório do projeto, git init
Perguntar obrigatoriamente se deseja introduzir o skill grill-with-docs (Cartão AskUserQuestion: Introduzir / Não Introduzir):
- Concordar → Executar três ações (não "já introduzido" verbalmente): ① Na tabela "Relações de Dependência" do CLAUDE.md, registrar: | grill-with-docs | Introduzido | Processo de questionamento de design (requer invocação manual pelo usuário /grill-with-docs) | ② Adicionar um lembrete no topo da lista inicial de tarefas (marcado como "Manual", não uma tarefa executável): - [ ] 📌 Lembrete (Manual): Durante design/planejamento, digite /grill-with-docs para iniciar o questionamento (este skill só pode ser invocado manualmente pelo usuário, a IA não pode ativar) ③ Informar claramente ao usuário o método de invocação: "Durante o primeiro design/planejamento, digite manualmente /grill-with-docs"
- Recusar → Não registrar, não adicionar à lista de tarefas, continuar normalmente
Projetos de código/engenharia: Perguntar se deseja criar um esqueleto de documentação opcional (Cartão AskUserQuestion: Criar / Pular; veja «📁 Esqueleto de Documentação Opcional»); projetos de negócio/documentação pular

Modelo inicial do CLAUDE.md no final.

🗑️ Deletar Projeto

Localizar o projeto → Listar entrada JSON + lista de arquivos do diretório → Marcar risco irreversível
Após confirmação do usuário: Fazer backup do PROJECTS.json → Deletar entrada JSON → Deletar diretório do projeto → Renumerar projetos restantes consecutivamente a partir de 1 → nextSeq = max(seq) + 1

💾 Salvar Projeto

Fazer backup do CLAUDE.md (no <diretório do skill>/backups/, ou seja, ~/.claude/skills/project-registry/backups/)
Revisar a conversa atual e anexar ou atualizar no CLAUDE.md:
- Último progresso e itens concluídos
- Novas decisões de arquitetura (decisões do dia a dia registradas no formato «📜 Disciplina de Registro de Decisões», razão não pode ser omitida)
- Atualizar lista de tarefas (itens concluídos marcados com ✅, novos itens adicionados)
- Atualizar problemas conhecidos
- ⚠️ «Próximas Ações» devem ser listadas por prioridade (1. 2. 3.), não podem ser omitidas (a próxima sessão continuará a partir daqui)
Comitar as alterações do CLAUDE.md no git
Sugerir próximas ferramentas: Com base no conteúdo e nas tarefas do projeto, sugerir possíveis skills (como ppt-master / docx / xlsx / pdf, etc.) para o usuário decidir
Após salvar, não sair, permanecer no diretório atual

⚠️ A atualização automática do CLAUDE.md é uma regra obrigatória e não pode ser pulada.

🚪 Sair do Projeto

Mesma operação de salvar, mas o último passo é voltar para ~:

Fazer backup do CLAUDE.md
Revisar a conversa atual e atualizar o CLAUDE.md (incluindo «Próximas Ações» por prioridade)
Comitar as alterações no git
Sugerir próximas ferramentas (mesmo fluxo de salvar)
Após sair, voltar diretamente para ~

🔍 Verificação MD (Verificar Status do CLAUDE.md de Todos os Projetos em Lote)

Verificar em lote se o CLAUDE.md de todos os projetos registrados é válido (sem necessidade de seleção manual):

Percorrer todos os diretórios de projetos, verificando os 3 itens a seguir:
- Se o diretório existe
- Se o CLAUDE.md existe
- Se .git existe (pré-requisito para o CLAUDE.md ser efetivo: deve estar no mesmo nível que .git)
Exibir tabela resumo:

🔍 Verificação de Saúde MD (Total: N projetos)
┌─────┬─────────────────────────────┬─────────────────┬──────────┬──────────┬──────────┬──────────┐
│ Seq │ Chave                        │ Nome do Projeto  │ Dir Existe │ CLAUDE.md│ .git     │ Válido? │
├─────┼─────────────────────────────┼─────────────────┼──────────┼──────────┼──────────┼──────────┤
│ 1   │ pet_hospital_crm_20260301   │ CRM Hospital Veterinário │ ✅       │ ✅       │ ✅       │ ✅      │
│ 2   │ gym_members_app_20260315    │ App Academia Membros     │ ✅       │ ✅       │ ✅       │ ✅      │
│ ... │ ...                         │ ...              │ ...      │ ...      │ ...      │ ...      │
└─────┴─────────────────────────────┴─────────────────┴──────────┴──────────┴──────────┴──────────┘

Para projetos onde "Válido?" é ❌, localizar o problema individualmente:
- Diretório não existe → Verificar se há resquícios de registro no JSON
- CLAUDE.md ausente → Recriar usando o modelo
- .git ausente → Executar git init
Executar automaticamente cd para o diretório raiz do usuário (não entrar em um projeto específico)

📁 Esqueleto de Documentação Opcional (Projetos de Código/Engenharia)

Ao criar um novo projeto de código, perguntar se deseja criá-lo (projetos de negócio/documentação pulam). Após a criação, a divisão de trabalho com o CLAUDE.md é: CLAUDE.md registra status e decisões, enquanto o esqueleto documenta os detalhes do design:

<diretório do projeto>/
├── CLAUDE.md              # Registro de desenvolvimento (status/decisões/tarefas)
└── docs/
    ├── ARCHITECTURE.md    # Descrição da arquitetura geral (opcional)
    ├── adr/               # Registro de Decisões de Arquitetura (opcional, conecta-se com a saída ADR do grill-with-docs/domain-modeling)
    └── dev/
        ├── README.md      # Índice de funcionalidades
        └── <funcionalidade>/
            ├── SPEC.md    # Especificação da funcionalidade
            └── DESIGN.md  # Design de implementação

Princípio leve: Criar apenas quando o usuário confirmar, não obrigatório, não padrão. Conexão com grill-with-docs: grill-with-docs (questionamento+termos+ADR) é o processo de design, o esqueleto é a estrutura de armazenamento — primeiro questionar claramente, depois armazenar no esqueleto. Divisão: Decisões leves vão para a "seção de Registro de Decisões de Arquitetura" do CLAUDE.md (uma linha); decisões difíceis de reverter, com trade-offs reais, vão para docs/adr/; o glossário CONTEXT.md é mantido exclusivamente pelo domain-modeling, o esqueleto não o recria.

cd Automático + Atualização Automática do CLAUDE.md

Operação	cd	Atualização Automática do CLAUDE.md
Novo	Entra no diretório do projeto	✅ Cria automaticamente o modelo inicial
Verificar/Modificar	Entra no diretório do projeto	❌ Não atualiza automaticamente
Atualizar Registro	Entra no diretório do projeto	✅ Acionado manualmente para atualizar
Salvar	Entra no diretório do projeto, após salvar, não sai, permanece no diretório	✅ Atualiza automaticamente
Sair/Retornar	Primeiro atualiza o CLAUDE.md, depois retorna para `~`	✅ Atualiza automaticamente

Mecanismo de Segurança

Operações de escrita no PROJECTS.json (novo, modificar, deletar) devem fazer backup primeiro:

Caminho do backup: <diretório do skill>/backups/ (ou seja, ~/.claude/skills/<nome-do-skill>/backups/)
Arquivo de backup: PROJECTS.json.<AAAAMMDD_HHMMSS>.bak

Operações de escrita no CLAUDE.md (atualização automática ao atualizar registro, salvar) devem fazer backup primeiro:

Caminho do backup: <diretório do skill>/backups/
Arquivo de backup: CLAUDE.md.<AAAAMMDD_HHMMSS>.bak

Se o diretório de backup não existir, crie-o automaticamente.

Rotação automática de backups:

Após cada novo backup, limpe os backups antigos por tipo de arquivo, mantendo os 10 mais recentes de cada tipo:

Prefixo do tipo de backup:
  PROJECTS.json.*.bak    # Backup da lista de projetos, manter 10
  CLAUDE.md.*.bak        # Backup do registro de desenvolvimento, manter 10
  SKILL.md.*.bak         # Backup do próprio skill, manter 10

Regra de limpeza: Ordene pelo timestamp no final do nome do arquivo (AAAAMMDD_HHMMSS). Nota: Para backups com nomes especiais como CLAUDE.md.<nome do projeto>.<timestamp>.bak, o timestamp está no final, não pode usar a string inteira do nome para ordenar. Mantenha os 10 mais recentes, delete o restante.

🔁 Salvamento Automático (hooks, execução silenciosa)

Duas camadas de mecanismo, todas executadas em segundo plano de forma silenciosa, com repetição silenciosa em caso de falha, e só funcionam no diretório do projeto em ~/projects/.

Camada 1: Instantâneo Mecânico (Zero Dependência, Ativado por Padrão)

Hook	Ação
Stop (após cada resposta)	Sincronizar o transcript para `<projeto>/.memory/transcript-latest.jsonl` (em segundos)
SessionEnd (final da sessão)	Backup do CLAUDE.md (rotação de 10) + commit git (apenas se houver alterações)

⚠️ Privacidade: .memory/ contém o texto original da conversa — deve ser excluído pelo .gitignore (o novo projeto gera automaticamente .gitignore contendo .memory/), nunca entra no repositório
Se o terminal for encerrado à força, o SessionEnd não é acionado, mas a sincronização em segundos do Stop ainda ocorre — os dados não são perdidos

Camada 3: Resumo Automático (Opcional, Ativado após Configuração da API)

Acionamento: Controle de limite (≥10 novas mensagens ou ≥10 minutos) — não chama a API a cada resposta
Fluxo: Ler .memory/ incrementalmente → Chamar PR_API_BASE_URL (qualquer provedor compatível com OpenAI) → Extrair progresso/decisões/tarefas/próximos passos → Mesclar e atualizar o CLAUDE.md (anexar decisões/atualizar progresso/tarefas/próximos passos)
Configuração (variáveis de ambiente): PR_API_BASE_URL / PR_API_KEY / PR_API_MODEL (se não configurado, pula automaticamente)
Privacidade: A conversa é enviada apenas para o endpoint configurado pelo usuário; a chave é lida das variáveis de ambiente, nunca codificada

Relação com Salvamento Manual

Resumo automático = manutenção em tempo real (mesclagem incremental); Salvamento manual = organização autorizada (revisão abrangente) — ambos são compatíveis e complementares.

📜 Disciplina de Registro de Decisões (Toda Decisão Deve Ter Fundamento)

Todas as decisões devem ser rastreáveis: "Por que isso foi feito" deve ser sempre verificável, a razão não pode ser omitida.

Formato de Decisão Leve

- [Status] AAAA-MM-DD — <Decisão> (Razão: <Motivo>) (Expectativa: <Efeito>)

Marcador de status: ✅ Executado / 🔄 Em Andamento / ⛔ Substituído / ⏸️ Suspenso
Razão obrigatória: Sem razão, não registra
Expectativa opcional: Se o efeito esperado for conhecido no momento do registro, adicione (usado para verificar o efeito durante a atribuição)

Momento de Registro (Por Nível)

Tipo	Momento
Decisão importante (impacta direção / difícil de reverter / consome recursos)	Confirmação imediata durante a conversa: Claude pergunta ativamente "Devo registrar esta decisão?"
Decisões do dia a dia	Registro retrospectivo unificado ao salvar/sair (obrigatório)

Decisão Pesada → ADR

Decisões difíceis de reverter, com trade-offs reais, vão para docs/adr/, deixando uma linha de índice no CLAUDE.md:

- 2026-08-08 — ADR-0001 <Título da Decisão> (Status: ✅ Executado)

Estrutura do ADR: # ADR-000N <Título> + Status / Date / Context / Decision / Consequences.

Modelo Inicial do CLAUDE.md

# <Nome do Projeto>

## Objetivo do Projeto
<Resumo da descrição do contexto>

## Stack Tecnológico
(A ser preenchido — Linguagem/Framework/Banco de Dados/Implantação, etc.)

## Status Atual
state: active
- Fase: Análise de Requisitos / Em Desenvolvimento / Concluído
- Último Progresso: Inicialização do projeto

## Registro de Decisões de Arquitetura
Registrar todas as decisões importantes, formato:
- [Status] AAAA-MM-DD — <Decisão> (Razão: <Motivo>) (Expectativa: <Efeito>)
(Status: ✅ Executado / 🔄 Em Andamento / ⛔ Substituído / ⏸️ Suspenso; razão não pode ser omitida, expectativa opcional)

## Escopo e Funcionalidades do Projeto
(Lista de funcionalidades principais, pode ser apresentada em tabela)

## Relações de Dependência
| Projeto Dependente | Relação | Descrição |
|:---|---|:---|
| <Nome do Projeto> | Depende/É dependido | <Descrição Específica> |

## Tarefas
- [ ] Tarefa 1 (detalhada até granularidade executável)

## Problemas Conhecidos
- (Nenhum no momento — complementar quando descoberto, incluindo escopo de impacto)

## Próximas Ações
- Listar por prioridade (1. 2. 3.), atualização obrigatória ao salvar/sair

Ao criar, preencha pelo menos: Objetivo do Projeto, Stack Tecnológico, Status Atual, três primeiras tarefas. O restante é enriquecido gradualmente durante o desenvolvimento.

Regra de Nomenclatura da Chave

<abreviação_em_inglês/pinyin>_<AAAAMMDD>

Exemplo:
  CRM Hospital Veterinário      → pet_hospital_crm_20260301
  App Academia Membros    → gym_members_app_20260315

Priorizar inglês, pinyin como alternativa
Tudo minúsculo, separado por sublinhado
Adicionar data no final

Regras de Gerenciamento de Números de Sequência

Operação	Regra
Novo	Ler `nextSeq` como seq do novo projeto, após registro, `nextSeq` +1
Deletar	Após deletar, renumerar projetos restantes consecutivamente a partir de 1, `nextSeq` = `max(seq) + 1`
seq	Sempre consecutivo, nunca pular números

🧠 Gerenciamento de Memória (Mecanismo de Três Níveis)

Memória de Nível de Projeto (Gerenciada pelo Skill)

Veículo de Memória	O que Registra	Mecanismo de Gerenciamento
CLAUDE.md	Status / Decisões e Razões / Tarefas / Problemas Conhecidos / Próximas Ações	Carregado automaticamente a cada sessão + Atualização forçada ao salvar + Commit git + Rotação de backups
PROJECTS.json	Lista de registro de projetos (seq/chave/nome/status/criado)	Backup antes de operações de escrita
Histórico git + backups/	Instantâneos de versões históricas	Pode ser revertido a qualquer momento (`git show` / arquivos de backup)

Ciclo de Vida da Memória

Escrita (atualização forçada ao salvar/sair)
  → Carregamento automático (Claude Code injeta automaticamente o CLAUDE.md a cada sessão)
  → Backup (rotação de 10 + commit git)
  → Recuperação (ler CLAUDE.md / investigação de atribuição "por que X" / reversão do histórico git)

Limites da Memória

Não registrar: Implementação de código detalhada | Alterações rastreáveis pelo git | Discussões temporárias (o texto original da conversa não é arquivado — para consultar "o que foi falado especificamente na época", use o arquivo de sessão --resume do Claude Code, que não está na responsabilidade deste skill)

Divisão de Trabalho com a Memória Global

Relacionado ao projeto (progresso/decisões/por que foi definido assim) → Memória deste skill (CLAUDE.md, segue o projeto)
Preferências do usuário / fatos entre projetos (ex: "PPT usa preferencialmente ppt-master") → Memória global do Claude Code (~/.claude/.../memory/, mantida pelo sistema, o skill não escreve)

Manutenção do CLAUDE.md

O CLAUDE.md é o arquivo de contexto do projeto carregado automaticamente a cada conversa do Claude, registrando decisões e progresso.

Momento de Atualização (Regra Obrigatória): Gerado automaticamente ao criar | Chamar "atualizar registro" ao final de cada conversa | Anexar ao tomar decisões importantes | Sincronizar quando os requisitos mudam | ⚠️ Ao sair ou salvar, a atualização é executada automaticamente (deve ser executada, não pode ser pulada), e as «Próximas Ações» são escritas por prioridade

Não Registrar: Implementação de código detalhada | Alterações rastreáveis pelo git | Discussões temporárias

Condição de Efetividade: Deve estar no mesmo nível que .git, nome do arquivo CLAUDE.md (letras maiúsculas)

Ao criar um novo projeto, execute automaticamente git init. Para diretórios existentes sem .git, informe o motivo e pergunte se deseja executar git init.

🔎 Investigação de Atribuição (Por que X)

Acionado quando o usuário diz "por que X / qual o contexto dessa decisão / por que foi feito assim na época / atribuir X".

Fluxo:

Localizar: Confirmar o objeto da investigação (projeto + tema/ponto no tempo)
Coletar Evidências: Ler a "seção de Registro de Decisões de Arquitetura" do CLAUDE.md do projeto + docs/adr/ (se existir) + último commit do git log + progresso/tarefas
Gerar Relatório de Atribuição:
- Linha do Tempo das Decisões: Decisões relevantes organizadas por tempo
- Cadeia de Razões: Motivo de cada decisão + relação entre decisões (qual decisão baseada em qual)
- Status: ✅ Executado / 🔄 Em Andamento / ⛔ Substituído / ⏸️ Suspenso
- Impacto Posterior: Combinar com o último progresso para julgar se a expectativa foi alcançada
Conclusão: Responder "por que foi feito assim na época", indicando se a expectativa foi verificada, se necessário

A saída fica dentro da conversa; quando for solicitado arquivamento, o armazenamento é feito fora do repositório (~/project-audit-logs/) — o conteúdo da verificação/atribuição contém privacidade do projeto, é proibido escrever no repositório do projeto.

📋 Verificação de Projeto (Acionado por Linguagem Natural, Não Ocupa Menu)

Acionado quando o usuário diz "verificar projeto / check-up / audit", não adiciona novo item ao menu.

Varredura Completa («Verificar Todos os Projetos»)

Verificação estrutural (mesmo que Verificação MD C) + 5 itens de conteúdo:

#	Dimensão	Lógica de Verificação
1	Consistência de Status	O status do PROJECTS.json vs o último progresso/tarefas do CLAUDE.md são contraditórios?
2	Projeto Estagnado	Última atualização do CLAUDE.md (tempo do git log) > 14 dias → "Possível estagnação"
3	Acúmulo de Tarefas	Mais de 10 tarefas não concluídas ou sem progresso por muito tempo
4	Decisão Não Implementada	Decisão marcada como ✅ Executado, mas sem evidência no progresso/tarefas
5	Ausência de Próximos Passos	Sem seção «Próximas Ações» (preguiça no fluxo de salvar)

Itens anômalos trazem automaticamente pistas de atribuição: Rastrear as últimas N decisões, indicar quais decisões podem estar relacionadas.

Inspeção Profunda de Projeto Único («Verificar Projeto XX»)

5 itens de conteúdo, verificar apenas o projeto especificado.

O relatório é exibido apenas dentro da conversa; quando for solicitado armazenamento, salvar em ~/project-audit-logs/ (fora do repositório).

↩️ Reversão de Versão

Acionado quando o usuário diz "reverter / restaurar versão / voltar / desfazer salvamento". Dois canais: histórico do git (arquivos do projeto) + instantâneos de backup (registro/registro de desenvolvimento).

Regras Gerais de Segurança (Toda Reversão Deve Seguir):

Fazer backup da versão atual primeiro (a própria reversão pode ser revertida)
Deve exibir um resumo das diferenças + cartão AskUserQuestion para confirmar (Reverter / Cancelar) antes de prosseguir
A reversão gera um novo commit, não reescreve o histórico do git

① Reversão do CLAUDE.md (Modificação/Exclusão Acidental do Registro de Desenvolvimento)

Localizar: git log --oneline lista os commits recentes (ou timestamp do nome do arquivo backups/CLAUDE.md.*.bak)
Comparar: git show <commit>:CLAUDE.md vs versão atual (foco: decisões/tarefas/próximas ações)
Confirmar: Exibir resumo das diferenças → Cartão de confirmação
Executar: Fazer backup da versão atual → git checkout <commit> -- CLAUDE.md → Commitar (registrar "revertido para ")
Relatar: Resumo do conteúdo revertido

② Reversão de Arquivos do Projeto (README/docs/código)

Localizar: git log para encontrar a versão alvo
Comparar: git diff <commit> -- <arquivo>
Confirmar: Resumo das diferenças → Cartão de confirmação
Executar: Fazer backup da versão atual → git checkout <commit> -- <arquivo> → Commitar
Relatar

③ Reversão do Registro (PROJECTS.json deletado/modificado acidentalmente)

Localizar: backups/PROJECTS.json.<timestamp>.bak (10 mais recentes, ordenar pelo timestamp no final)
Comparar: diff atual vs backup (listar adições/remoções de projetos)
Confirmar: Resumo das diferenças → Cartão de confirmação
Executar: Fazer backup da versão atual → cp backup → PROJECTS.json → Validar (número de projetos/continuidade do seq)
Relatar

Dica: A reversão funciona em conjunto com a «🔎 Investigação de Atribuição» — primeiro investigue "por que ficou assim", depois decida para qual versão reverter.

Perguntas Frequentes

PROJECTS.json não existe: Criar lista vazia usando o modelo padrão
Diretório já existe: Reutilizar o diretório existente, apenas registrar no JSON
Projeto não encontrado ao deletar: Primeiro exibir a lista para o usuário confirmar

Perguntar na sua IA favorita

Documentação