Escrever intenções que importam

Os documentos de intenção registram os comportamentos e as restrições que você quer que o software atenda. Escreva o que já decidiu e refine à medida que aprende com a implementação e as evidências. Isso mantém o documento legível e deixa espaço para o Agente implementar.

Escolha requisitos que vale a pena manter

A intenção pode descrever vários tipos de requisitos:

Descreva a condição de acionamento e um resultado observável. “A exportação deve ser confiável” é difícil de verificar. “Se a exportação falhar, preservar os filtros atuais e permitir nova tentativa” oferece uma base mais clara para avaliação.

Quando uma decisão de implementação for importante o bastante para que alterações futuras precisem respeitá-la, registre-a na intenção. Os detalhes que você ainda não decidiu podem permanecer como escolhas da implementação.

Separe requisitos duradouros da tarefa de hoje

A intenção descreve o que o software deve continuar fazendo. Não é uma lista de tarefas para apagar quando o trabalho termina. Mantenha os requisitos depois que uma funcionalidade ficar pronta e altere o texto relevante quando decidir mudar o comportamento.

As conversas também contêm instruções para a rodada atual de trabalho. Use esta distinção:

Pergunte o que a frase realmente restringe. “Validar os dados antes de cada exportação” define a ordem de execução do software e pertence à intenção. “Investigar primeiro o módulo de exportação desta vez” organiza a tarefa atual.

Diga ao Agente quais instruções são requisitos duradouros e quais se aplicam apenas a esta tarefa. Repita instruções importantes específicas da tarefa quando necessário; não presuma que uma nova conversa as herda.

Crie e edite um documento

Clique em Nova Intenção na barra lateral e digite um nome. O Noea cria um arquivo .noea.md na raiz da pasta de intenção com um título de nível um.

Os documentos usam Markdown, com leitura e edição na mesma visualização. Clique no texto para editar e organize-o com títulos, listas, tabelas e blocos de código.

Por exemplo:

# Check-ins diários

Os usuários podem fazer check-in uma vez por dia.

## Recompensas

Conceder uma recompensa ao usuário após 7 dias consecutivos de check-ins. Conceder a recompensa apenas uma vez dentro da mesma sequência.

Use títulos para seções e parágrafos para requisitos distintos. A Investigação trata uma lista inteira como uma única unidade de conteúdo. Separe assuntos em parágrafos ou seções quando quiser investigá-los e discuti-los de forma independente.

Desenvolva a intenção por meio da conversa

Se uma regra ainda não estiver clara, discuta-a antes de pedir ao Agente que proponha uma alteração:

Quero evitar recompensas de check-in duplicadas. Ajude a definir o que “duplicada” significa aqui e espere minha confirmação antes de propor uma alteração de intenção.

Depois de chegar a uma decisão, peça ao Agente que a transforme em proposta. Revise a redação, edite o texto novo se necessário e aceite. Uma afirmação na conversa só passa a fazer parte do documento de intenção quando é escrita nele.

O texto resultante deve usar conceitos e linguagem que você entende. Pergunte sobre termos desconhecidos ou requisitos adicionados antes de decidir mantê-los. Uma boa redação permite que você explique o requisito e encontre a frase a alterar quando quiser outro comportamento.

Para propostas e cartões de sugestões, consulte Discutir e revisar alterações de intenção.

Use diagramas para relações

Um bloco de código com a linguagem mermaid pode ser exibido como diagrama. Use-o para ilustrar transições de estado, fluxos de trabalho ou relações entre módulos.

O controle no canto superior direito alterna entre o diagrama e seu código-fonte. Mude para o código-fonte para editar. Se a sintaxe for inválida ou o tipo de diagrama não for compatível, o Noea mostra o código-fonte e o motivo; o restante do documento continua legível.

Salve e trabalhe com editores externos

Salve manualmente com ⌘S no macOS, Ctrl+S no Windows / Linux ou Arquivo → Salvar. Um ponto ao lado do título marca alterações não salvas. Trocar de aba as preserva; fechar o documento ou projeto, ou encerrar o aplicativo, solicita que você salve.

O salvamento normaliza a formatação Markdown. Você também pode manter os arquivos em um editor externo. Se um arquivo mudar no disco enquanto você o edita no Noea, o aplicativo oferece opções para recarregar ou salvar como outro arquivo, em vez de sobrescrevê-lo diretamente.

Entenda o significado de uma mudança de redação

Adicionar, substituir e apagar texto afetam os requisitos de maneiras diferentes:

Remover “A recompensa deve ser uma medalha” não torna necessariamente inválida uma implementação existente com medalhas. Ela ainda pode atender à intenção restante. Para remover as recompensas por completo, diga que elas não devem mais ser concedidas, em vez de apagar apenas um requisito sobre sua forma.

Antes de editar, pergunte ao Agente quais comportamentos mudariam e quais requisitos devem permanecer. Use a resposta como base para discussão e depois confira a implementação e as evidências reais.

Depois de salvar, as explicações antigas mostram Texto anterior. Se o novo requisito exigir mudanças de código, implemente-o antes de investigar. Se quiser apenas verificar o comportamento existente, investigue diretamente.

Continue com Trabalhar com um Agente na implementação ou Manter as explicações atualizadas.