Date: 2026-09-10

NOVA.md e regras do projeto

Nesta lição, vais definir instruções concisas e verificáveis para que a Nova trabalhe de forma consistente no teu projeto.

Objetivo

NOVA.md dá à Nova instruções duradouras sobre como trabalhar num projeto. É o local certo para convenções que devem aplicar-se entre sessões: comandos de verificação obrigatórios, limites de arquitetura, normas de linguagem, políticas para ficheiros gerados, restrições de segurança e regras de lançamento. Deve descrever como o repositório deve ser trabalhado, e não duplicar informações que a Nova consegue descobrir facilmente a partir de manifestos de pacotes ou da inspeção do repositório.

Ordem de descoberta das instruções

A Kore-CLI carrega as instruções do projeto pela seguinte ordem, da prioridade mais elevada para a mais baixa:

<projectRoot>/NOVA.local.md
<projectRoot>/.compass/rules/*.md, por ordem alfabética.
<projectRoot>/NOVA.md
<projectRoot>/.compass/NOVA.md
~/.compass/NOVA.md

Todos os ficheiros não vazios encontrados são concatenados no contexto de instruções. A política de sistema e da organização, com maior autoridade, continua a ter precedência sobre qualquer ficheiro de projeto.

Escolher uma localização

Usa cada localização de forma deliberada:

NOVA.md — instruções partilhadas pela equipa no repositório, normalmente com commit no controlo de versões.
NOVA.local.md — instruções de projeto específicas de cada programador, normalmente excluídas do controlo de versões.
.compass/rules/*.md — regras modulares de projeto separadas por tema, como testes, frontend, base de dados ou segurança.
.compass/NOVA.md — instruções de projeto guardadas com outra configuração da Compass.
~/.compass/NOVA.md — predefinições pessoais aplicáveis a todos os projetos.

Mantém uma regra no âmbito sensato mais restrito. Não a repitas em todas as camadas.

O que incluir nas instruções do projeto

Exemplos úteis incluem:

Sistemas operativos suportados e sintaxe de shell.
O gestor de pacotes e comandos de instalação, lint, verificação de tipos, testes e builds.
Ficheiros gerados que nunca devem ser editados manualmente.
Limites de arquitetura e direção das dependências.
Requisitos de tratamento de erros, validação, acessibilidade e segurança.
Convenções de commits ou ramos específicas da equipa.
Destinos de implementação e requisitos de aprovação, sem credenciais.
Instruções para proteger trabalho do utilizador que ainda não foi submetido.

Escreve regras observáveis:

## Verificação

Depois de alterares código TypeScript, executa:

- `npm run lint`
- `npm run typecheck`
- O menor alvo relevante de `npm test -- <path>`

Para alterações apenas de documentação, revê a estrutura renderizada e o diff em vez de executares verificações de TypeScript.

Isto é mais eficaz do que “testa o teu trabalho”, porque identifica as evidências esperadas.

O que não incluir

Evita:

Chaves de API, palavras-passe, tokens, certificados privados ou cadeias de ligação.
Explicações longas de implementação que vão ficar desatualizadas.
Estado temporário de tarefas ou notas de depuração pontuais.
Registos brutos e saída de comandos.
Regras que entrem em conflito com a política da organização.
Preferências vagas como “escreve código limpo”.
Um catálogo de todos os ficheiros do repositório.

Usa notas de sessão, sistemas de acompanhamento de issues, planos ou memória explícita para informação que não é uma regra de trabalho duradoura.

Escrever instruções concisas e testáveis

Uma boa instrução indica a condição e a ação necessária:

- Never edit generated files directly; regenerate them with `npm run generate`.
- Preserve the public API of `packages/core` unless the task explicitly authorises a breaking change.
- Validate all HTTP input at the route boundary and return the existing typed error shape.
- Use PowerShell syntax for local commands on Windows; do not provide Bash-only command chains.

Se existirem exceções, documenta-as. Regras contraditórias obrigam o modelo a adivinhar qual a convenção pretendida pela equipa.

Regras modulares

Usa .compass/rules quando for difícil analisar um único ficheiro na raiz:

.compass/
  rules/
    10-general.md
    20-testing.md
    30-frontend.md
    40-security.md

Os ficheiros são ordenados alfabeticamente, por isso os prefixos numéricos podem tornar a ordem de carregamento explícita. A modularização deve reduzir a carga cognitiva, não duplicar os mesmos requisitos em vários ficheiros.

Sobreposições locais

NOVA.local.md tem a prioridade mais elevada entre os ficheiros de projeto e é adequado para caminhos locais, comandos específicos da máquina ou detalhes do fluxo de trabalho pessoal. Mantém-no fora do Git se contiver informação específica do ambiente. Mesmo assim, não deve conter segredos.

Manter o ficheiro

Revê as instruções quando as ferramentas, a arquitetura ou a política da equipa mudarem. Remove regras obsoletas ou já impostas automaticamente. Um NOVA.md curto e rigoroso é mais eficaz do que um documento histórico extenso com orientações contraditórias. Depois de editares as instruções, inicia uma sessão nova ou garante que a Nova recarrega o contexto alterado antes de dependeres da nova regra.

Recapitulação

Usa NOVA.md para convenções duradouras, observáveis e específicas do projeto. Mantém cada regra no menor âmbito adequado e nunca guardes segredos em ficheiros de instruções.

Prática segura

Cria ou revê uma regra que indique exatamente qual o comando de verificação a executar depois de um tipo concreto de alteração. Confirma que a regra não duplica informação fácil de descobrir nem inclui dados sensíveis. Anterior: Revisão de código e recuperação segura | Seguinte: Agentes especializados

​NOVA.md e regras do projeto

​Objetivo

​Ordem de descoberta das instruções

​Escolher uma localização

​O que incluir nas instruções do projeto

​O que não incluir

​Escrever instruções concisas e testáveis

​Regras modulares

​Sobreposições locais

​Manter o ficheiro

​Recapitulação

​Prática segura