CommunityEscrita e Ediçãogithub.com

SmallNoc/noc-living-docs

Protocolo de documentação viva e skill para Codex que mantém alterações de código assistidas por IA, requisitos, status, proteções, testes e registros de mudanças sincronizados.

O que é noc-living-docs?

Este skill implementa o conceito de 'documentação viva' (living docs) como memória executável do projeto, permitindo que agentes de IA como Codex mantenham documentação sincronizada com o código. Ele é acionado sempre que há discussão de requisitos, alterações de código (novas funcionalidades, correções de bugs, refatorações, mudanças de API/segurança/implantação) ou consultas à documentação do projeto. O fluxo de trabalho envolve identificar o recurso afetado via mapa de recursos (`feature-map.json`), executar um plano de trabalho com `python scripts/noc.py work`, ler e atualizar os documentos relevantes (`requirements.md`, `status.md`, `guardrails.md`, etc.), alterar o código, e então executar indexação e verificação com CLI antes do commit. O skill possui regras claras de parada quando há conflitos com guardrails, requisitos ambíguos, ou tarefas que exigem mudanças silenciosas, e define uma Definition of Done rigorosa que inclui a verificação de que todos os documentos foram lidos/atualizados e os comandos apropriados foram executados.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add SmallNoc/noc-living-docs

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

Documentação Viva do Projeto

Use NOC Living Docs como memória executável do projeto. Roteie por noc_docs/, leia apenas os documentos afetados, atualize os documentos vivos quando o código ou intenção mudar, e então verifique com a CLI.

Gatilho

Use este skill para:

  • inicializar ou migrar noc_docs/
  • discutir um requisito e então alterar código
  • novas funcionalidades, correções de bugs, refatorações, mudanças de API/dados/segurança/implantação
  • verificar se alterações de código precisam de atualizações na documentação
  • consultar ou auditar a documentação viva do projeto

Não use para perguntas gerais que não envolvam memória do projeto, comportamento do código, requisitos, guardrails, testes ou documentação NOC.

Execução

  1. Identifique o recurso/domínio afetado a partir da solicitação, caminhos alterados e noc_docs/.living-docs/feature-map.json.
  2. Execute um plano de trabalho quando o código puder mudar:
python scripts/noc.py work /caminho/para/projeto --feature <recurso> --intent "<requisito acordado>"

Use --path <caminho/código> quando caminhos forem mais claros que nomes de recursos.

  1. Leia os menores documentos relevantes: agent-guide.md, requirements.md, status.md, guardrails.md, test-record.md, mais os guardrails de domínio quando presentes.
  2. Escreva a intenção nova/alterada confirmada em requirements.md; coloque discussões incertas em notes.md.
  3. Altere o código.
  4. Atualize status.md, test-record.md, change-record.md e guardrails.md quando comportamento, verificação, mudanças importantes ou restrições forem alterados.
  5. Execute python scripts/noc.py index <projeto> após alterações em documentos, recursos ou mapeamento.
  6. Execute python scripts/noc.py check <projeto> --staged --warn-only antes do commit quando Git estiver disponível.

Para regras detalhadas do fluxo de trabalho, leia references/workflow.md.

Não Prossiga

Pare e pergunte ao usuário antes de editar código quando:

  • a solicitação conflitar com guardrails.md ou guardrails de domínio
  • a intenção do produto conflitar com requirements.md e a direção pretendida não estiver clara
  • o recurso/domínio afetado não puder ser identificado e a alteração não for obviamente global
  • documentos necessários estiverem faltando e a tarefa depender de requisitos ou restrições desconhecidos
  • o usuário pedir para reescrever silenciosamente os requisitos para corresponder ao código atual
  • a alteração envolver segurança, permissões, cobrança, perda de dados, migrações ou contratos públicos de API e o comportamento solicitado for ambíguo

Definição de Pronto

Uma tarefa usando este skill só está concluída quando:

  • os documentos afetados foram identificados através do mapa de recursos, caminhos ou nome explícito do recurso
  • os documentos necessários foram lidos ou a falta deles foi apontada
  • as alterações de código e de documentação estão alinhadas
  • requirements.md foi alterado apenas para mudanças intencionais de comportamento
  • status.md reflete o comportamento atual após as alterações de código
  • test-record.md registra a verificação ou explica por que a verificação não foi executada
  • change-record.md registra alterações importantes de implementação
  • índices/verificações foram executados quando disponíveis, ou ignorados com justificativa

Formato da Resposta Final

Termine com:

NOC Living Docs:
- documentos verificados:
- documentos atualizados:
- documentos intencionalmente inalterados:
- comandos executados:
- testes executados:
- riscos remanescentes:

Mantenha as listas curtas. Use nenhum quando uma categoria não se aplicar.

Referências

  • references/workflow.md: seleção de modo, regras de fallback, tratamento de conflitos, loop de trabalho
  • references/feature-doc-template.md: o que cada documento de recurso deve conter
  • references/domain-mode-guide.md: quando e como usar o modo de domínio
  • references/codex-prompts.md: prompts de usuário recomendados para fluxos de plano/meta/código do Codex

Habilidades Relacionadas