chancy24/codex-knowledge-base-skill

Mantenedor de Conhecimento do Projeto

Propósito

Use este Skill para inicializar, manter e evoluir uma base de conhecimento em nível de projeto para agentes de codificação de IA. A base de conhecimento ajuda futuras sessões de agente a entender o propósito do projeto, arquitetura, interfaces, decisões, bugs e mudanças recentes, sem redescobrir tudo do zero.

Mantenha o fluxo de trabalho neutro em relação a ferramentas. Deve ser utilizável por Codex, Claude Code, Cursor, Gemini CLI e outros agentes de codificação que possam ler arquivos do projeto e seguir instruções locais do repositório.

Quando Usar

Use este Skill quando o usuário pedir para:

• inicializar uma base de conhecimento do projeto
• resumir ou documentar um projeto
• corrigir um bug e preservar a experiência de reparo
• adicionar ou alterar uma funcionalidade
• adicionar ou alterar uma API, esquema, comando ou formato de dados
• registrar uma decisão técnica ou trade-off
• organizar materiais brutos do projeto em conhecimento estruturado
• revisar ou fazer uma retrospectiva de uma sessão de desenvolvimento concluída
• atualizar AGENTS.md ou arquivos em knowledge/

Entradas

As entradas comuns incluem:

• O repositório atual ou caminho do projeto alvo.
• Arquivos existentes do projeto, código fonte, documentação, issues, logs ou materiais brutos.
• A tarefa atual do usuário e quaisquer alterações de implementação feitas durante a sessão.
• Conteúdo existente de AGENTS.md, knowledge/, raw/ ou skills/, se presente.

Saídas

As saídas esperadas incluem:

• AGENTS.md regras do projeto.
• knowledge/overview.md visão geral do projeto.
• knowledge/business.md lógica de negócio e cenários de uso.
• knowledge/architecture.md arquitetura do sistema e fluxo de dados.
• knowledge/api.md interfaces, esquemas, comandos e estruturas de dados.
• knowledge/decisions.md decisões técnicas e trade-offs.
• knowledge/bugs.md histórico de bugs, causas raiz, correções e regras de prevenção.
• knowledge/changelog.md registros de alterações em nível de sessão.
• Pastas opcionais raw/ e skills/ locais do projeto.
• Um breve relatório final listando o que foi atualizado e o que ainda precisa de verificação.

Fluxo de Trabalho

1. Leia as regras do projeto primeiro:
   • AGENTS.md se presente.
   • knowledge/overview.md
   • knowledge/architecture.md
   • knowledge/decisions.md
   • knowledge/bugs.md
2. Se estiver inicializando um repositório, use os templates em references/templates/ ou execute o script de inicialização deste pacote.
3. Entenda a tarefa atual e identifique o que mudou:
   • objetivo do projeto ou lógica de negócio
   • arquitetura ou limites de módulo
   • API, comando, arquivo de dados, esquema ou estrutura de retorno
   • sintoma de bug, causa raiz, correção ou regra de prevenção
   • decisão técnica ou trade-off
   • comportamento voltado ao usuário ou convenção de interface do usuário
4. Atualize apenas os arquivos de conhecimento relevantes.
5. Remova ou reconcilie conteúdo duplicado, desatualizado ou contraditório.
6. Sempre atualize knowledge/changelog.md após trabalho importante.
7. Relate os arquivos atualizados e qualquer validação pendente.

Para orientações mais detalhadas de manutenção, leia references/playbook.md.

Atualizando knowledge/

Use o menor arquivo que corresponda à mudança:

• Atualize overview.md para propósito durável do projeto, escopo, módulos principais e saídas principais.
• Atualize business.md para cenários de usuário, fluxos de trabalho, regras de domínio e limites de segurança.
• Atualize architecture.md para relações de módulo, fluxo de dados, modos de execução e limites de integração.
• Atualize api.md para endpoints, funções, comandos, eventos, arquivos de dados, esquemas e estruturas de retorno.
• Atualize decisions.md para escolhas técnicas significativas e trade-offs.
• Atualize bugs.md para bugs confirmados e lições aprendidas.
• Atualize changelog.md para cada resumo de tarefa importante.

Não despeje raciocínio transitório na base de conhecimento. Prefira fatos estáveis, decisões validadas e lições reutilizáveis.

Retrospectivas de Bugs

Quando um bug for corrigido, atualize knowledge/bugs.md com:

• Sintoma do problema.
• Causa raiz.
• Correção.
• Escopo afetado.
• Validação realizada.
• Regra para prevenir recorrência.

Se a causa raiz for incerta, marque-a como pendente de verificação em vez de adivinhar.

Mudanças de Interface

Quando uma API, comando, função, esquema, CSV, evento ou formato de arquivo mudar, atualize knowledge/api.md com:

• Nome da interface.
• Método de requisição ou estilo de invocação.
• Caminho, comando, nome da função ou caminho do arquivo.
• Entradas e parâmetros.
• Formato de resposta ou saída.
• Notas, restrições e exemplos.

Use nomes exatos e grafias de campos.

Decisões Técnicas

Quando uma escolha técnica significativa for feita, atualize knowledge/decisions.md com:

• Contexto da decisão.
• Opções consideradas.
• Escolha final.
• Motivo da escolha.
• Consequências e trabalho de acompanhamento.

Registre decisões que ajudarão agentes futuros a evitar reabrir questões já resolvidas.

Evitando Degradação do Conhecimento

• Prefira editar uma entrada existente a adicionar uma entrada quase duplicada.
• Marque conteúdo desatualizado como substituído ou substitua-o pelo fato atual.
• Mantenha fatos do projeto separados de especulações.
• Use datas para decisões, bugs e entradas do changelog.
• Mantenha a redação neutra em relação ao agente, a menos que uma integração de ferramenta específica exija uma nota específica da ferramenta.
• Não sobrescreva regras de projeto criadas pelo usuário sem uma solicitação explícita.

Resposta Final

Mantenha a resposta final concisa. Inclua:

• Arquivos atualizados.
• Validação realizada.
• Quaisquer verificações manuais restantes.