name: disciplina-doc-agente description: Disciplina de escrita para documentos consumidos por agentes (as cinco superfícies, especificações, tickets, .omc/skills/) — toda regra verificável e acompanhada de um porquê, passos antes de referência, um significado em um único lugar, sem repetir o que o ambiente já diz. Obrigatória na geração de sementes do drydock e na passagem de sedimentos C5 do lançamento; opcional para qualquer outra edição de documento voltado a agentes. Companheira da disciplina-código-mínimo: uma disciplina o código, esta disciplina os textos. nível: 3
Disciplina de Documento para Agentes
Use esta habilidade para aplicar uma disciplina de escrita ao criar ou editar qualquer documento que um agente consome para agir: as cinco superfícies (CLAUDE.md, CONTEXT.md, docs/standards/, design-system/, .omc/skills/), especificações, tickets e arquivos de skill. O teste que um documento deve passar: uma sessão de agente nova pode agir com base nele apenas lendo.
Obrigatória quando: o drydock gera sementes de superfície, a passagem de sedimentos C5 do lançamento escreve uma lição em um slot. Opcional para todas as outras edições — mas qualquer edição em um documento voltado a agentes deve sobreviver a estas regras.
Quando não usar
Documentos escritos apenas para humanos: narrativa docs/business/, histórias de decisão ADR, READMEs para integração de humanos. Eles podem ainda seguir as regras onde isso não custa nada, mas não estão sujeitos a esta disciplina.
A Disciplina
Escreva para um leitor sem histórico de chat. O documento é autodescritivo: nada depende de "como discutido", de uma sessão anterior ou de conhecimento que existe na cabeça de alguém. Teste: uma sessão de agente nova pode agir com base no documento apenas lendo.
Toda regra verificável e acompanhada de um porquê. Nada de "mantenha limpo" — escreva a condição observável e o motivo. Teste: um agente pode decidir aprovado/reprovado apenas pelo texto, e o porquê está indicado ao lado da regra.
Um significado, um lar. Cada regra ou definição tem um único lugar autoritativo; duplicação é deriva à espera de acontecer. Teste: alterar um comportamento é uma edição em um só lugar.
Nunca repita o que o ambiente confessa. Scripts de pacote, estruturas de diretório, saída --help são consultas, não documentos — uma consulta copiada fica desatualizada. Documente apenas o que não pode ser encontrado olhando: a convenção não escrita, o motivo por trás de uma escolha, a pegadinha. Teste: cada linha sobrevive a "isso pode ser consultado em outro lugar?".
Passos primeiro, referência atrás, material raro atrás de um ponteiro. O que fazer, em ordem, no topo; regras para consulta sob demanda abaixo; material de baixa frequência empurrado para trás de um ponteiro cujo texto nomeia os ramos que devem acionar seu acesso. Teste: a próxima ação é encontrável na primeira tela.
Cada passo termina com um critério de conclusão. Feito deve ser distinguível de não feito — um limite vago convida à conclusão prematura. Teste: para cada passo, "como sei que isso está terminado?" tem uma resposta no texto.
Promova o positivo. Declare o comportamento alvo; uma proibição é reservada para barreiras rígidas e sempre emparelhada com o alvo positivo. Teste: toda proibição no documento nomeia a coisa a fazer em vez.
Remova incrustações ao escrever. Quando o documento contém material obsoleto ou redundante, remova-o na mesma edição; quando não contém, adicione apenas o material necessário e não invente exclusões. Uma frase que o modelo já obedece por padrão gera custo sem retorno — exclua a frase inteira. Teste: cada linha relida merece seu lugar contra "isso muda o comportamento versus o padrão?", e qualquer material obsoleto ou redundante encontrado durante a edição foi removido.
Verificação
Antes de relatar uma alteração de documento como concluída, confirme:
- uma sessão nova poderia agir com base nele sem perguntar nada a um humano
- toda regra é verificável e declara seu porquê; nenhuma regra repete uma consulta
- significados vivem em um só lugar; ponteiros nomeiam seus ramos de acionamento
- material obsoleto ou redundante encontrado durante a edição foi removido, enquanto conteúdo válido não relacionado foi preservado