Você tem as informações necessárias para orientar uma revisão, mas elas estão num parágrafo que mistura objetivo, regras, exceções e resultado esperado. Quem lê precisa reconstruir essa organização mentalmente. Quando o documento cresce, surgem referências vagas, instruções repetidas e dúvidas sobre o que realmente deve ser feito. Trocar a extensão do arquivo não resolve essa dificuldade.
Markdown ajuda a organizar texto sem exigir um editor sofisticado. Ele permite indicar títulos, listas, links e trechos de código usando caracteres comuns. Mas a qualidade do arquivo depende também de decisões de escrita: explicar o contexto, separar responsabilidades e oferecer critérios que permitam conferir o trabalho. Formatação e entendimento precisam caminhar juntos.
Neste segundo capítulo da série sobre instruções para IA, vamos aprender a sintaxe essencial e aplicá-la ao exemplo fictício de revisão de uma importação Delphi. O objetivo não é decorar todos os recursos do formato, mas construir um documento que uma pessoa consiga revisar e uma ferramenta consiga apresentar de forma previsível. Também veremos os limites desse cuidado.
Para aprofundar a passagem de uma solicitação vaga para requisitos, contratos e critérios de aceite, conheça SDD em Delphi. O sumário e a degustação gratuita ajudam a avaliar esse método antes de escolher a edição. A conexão com este capítulo é direta: um arquivo bem apresentado só ganha valor técnico quando registra um entendimento verificável.
O que é Markdown, antes de escrever
Markdown é um formato de texto simples para escrever documentos estruturados. Um arquivo com extensão .md pode conter frases comuns e marcações que indicam sua organização. O texto-fonte é aquilo que você escreve; a versão apresentada por um leitor de Markdown é a interpretação dessas marcações. Essa distinção é descrita na introdução da especificação CommonMark.
Um editor de texto é suficiente para criar o arquivo. Não é necessário começar com uma ferramenta especializada, embora uma prévia de apresentação possa facilitar a conferência. Se você abrir o documento como texto comum, continuará vendo os títulos e as listas com seus marcadores. Essa possibilidade favorece a revisão do próprio conteúdo, não apenas de sua aparência final.
Há diferentes implementações e extensões de Markdown. Portanto, um recurso exibido numa plataforma pode não funcionar exatamente da mesma maneira em outra. Para os exemplos deste capítulo, usamos um conjunto pequeno de recursos e evitamos depender de tabelas, caixas especiais ou elementos próprios de um aplicativo. A proposta é favorecer portabilidade, não demonstrar todos os efeitos disponíveis.
Também é importante preservar a distinção construída na introdução a AGENTS.md e skills: formato não é mecanismo de carregamento. Um arquivo legível não será necessariamente descoberto por um assistente. Você ainda precisa saber se ele será anexado, solicitado ou reconhecido pela ferramenta utilizada.
Títulos são um mapa, não decoração
No estilo de título que usaremos, um sinal de cerquilha seguido de espaço indica o título principal. Duas cerquilhas indicam uma seção; três, uma subseção. Essa hierarquia representa relações entre partes do documento. Ela ajuda a distinguir um assunto principal de um detalhamento, sem depender de tamanho de letra escolhido manualmente.
Imagine um arquivo chamado revisao-importacao.md. O título pode dizer qual trabalho ele descreve. Depois, seções como objetivo, escopo, critérios e entrega permitem localizar informações diferentes. Prefira títulos que indiquem a função do conteúdo. “Coisas importantes” exige interpretação; “Critérios de aceite” orienta a busca por condições que a revisão deverá conferir.
Um único título principal é uma escolha editorial útil para esse documento, não uma limitação geral do formato. Da mesma forma, manter uma hierarquia sem saltos é uma recomendação de organização. O importante é que a estrutura corresponda ao raciocínio: se uma seção ganhou vários temas independentes, talvez deva ser dividida em vez de receber uma sequência de títulos vagos.
Não transforme cada frase em um subtítulo. Se todas as linhas parecem igualmente importantes, o documento perde a capacidade de orientar o olhar. Um parágrafo desenvolvido pode explicar o motivo de uma regra; uma lista pode reunir itens comparáveis; uma subseção pode detalhar uma exceção. A estrutura deve revelar essas diferenças, não substituí-las por aparência.
Parágrafos, listas e ênfases com função clara
Escreva parágrafos separados por linhas em branco. Para listas simples, podemos usar um hífen seguido de espaço; para etapas ou condições numeradas, números seguidos de ponto e espaço. Deixe espaço visual entre blocos. Esses recursos estão definidos na especificação CommonMark, mas nossa recomendação editorial é usar uma organização simples e conferir o resultado na ferramenta de destino.
Listas ajudam quando os itens desempenham o mesmo papel. Duas restrições podem formar uma lista; uma explicação sobre a finalidade da revisão pode continuar como parágrafo. Não transforme uma argumentação completa em vinte marcadores apenas porque isso parece mais fácil para a IA. O leitor também precisa compreender como as ideias se relacionam.
A ênfase pode destacar um termo curto. Neste capítulo, por exemplo, a entrega precisa diferenciar evidência e recomendação. Evite destacar parágrafos inteiros: isso enfraquece a hierarquia visual. Mais importante que usar negrito é explicar a diferença. Evidência descreve o que foi encontrado ou observado; recomendação indica o que pode ser feito a partir disso.
Para escrever essas marcações, coloque um asterisco de cada lado de uma palavra para ênfase, como *recomendação*, ou dois de cada lado para destaque forte, como **evidência**. O texto-fonte contém os sinais; a apresentação mostra a ênfase. Use esse recurso para orientar a leitura, não para atribuir importância técnica a algo que o documento ainda não explicou.
Quando uma lista representa passos, pense nas dependências. “Execute testes” pode ser inadequado se o ambiente não existe. Uma orientação melhor informa quais testes são relevantes, onde encontrá-los e como registrar a impossibilidade de execução. O marcador numérico organiza a leitura; ele não resolve uma condição operacional que ficou ausente no texto.
Links e identificadores precisam ser reconhecíveis
Um link possui texto de apresentação e um endereço de destino. A ideia é oferecer um nome que explique o que será consultado, não apenas uma palavra genérica. “Especificação da importação vigente” orienta melhor que “clique aqui”. Para documentos locais, o caminho também precisa corresponder à organização real do projeto, não a uma pasta inventada num modelo.
A escrita básica é [nome da referência](endereço). Por exemplo, [Especificação CommonMark](https://spec.commonmark.org/0.31.2/) apresenta o nome como link para a especificação. Os colchetes delimitam o texto visível e os parênteses delimitam o destino. Um caminho relativo, como referencias/contrato.md, depende da localização do arquivo e do modo como a ferramenta resolve links; confira-o no destino real.
Verifique se o material apontado existe e se continua pertinente. Um link tecnicamente válido pode levar a uma regra antiga. Quando a decisão depende de versão, data ou aprovação, registre esse contexto junto da referência. A formatação do endereço não demonstra que a fonte é correta; essa conferência continua sendo parte da revisão.
Identificadores como CodigoProduto podem ser apresentados como código em linha. Isso ajuda a distingui-los da frase que os explica. Não traduza um nome real de campo só para tornar o texto mais natural: preserve o identificador e explique seu significado. No exemplo deste artigo, o nome é fictício e não representa um componente de um sistema existente.
Para trechos maiores, blocos cercados de código preservam a apresentação do conteúdo. É útil indicar a linguagem quando houver código. Neste capítulo, o exemplo usa markdown: queremos mostrar a escrita do documento, não executar um programa Delphi. A presença de um bloco de código não deve fazer o leitor presumir que uma integração foi testada.
Código em linha é delimitado por um acento grave de cada lado do identificador. Para um bloco, coloque três acentos graves numa linha de abertura, escreva a linguagem logo depois e encerre com três acentos graves em outra linha. A amostra abaixo demonstra esse formato com a linguagem markdown. Assim, o leitor vê as marcações do documento em vez de confundi-las com os títulos do artigo.
Do parágrafo misturado a uma revisão organizada
Infográfico ilustrativo gerado por IA. Síntese autoral do roteiro do capítulo; os objetos não representam documentos reais nem uma aprovação técnica do exemplo.
Nosso exemplo parte de uma necessidade fictícia: revisar uma alteração que rejeita linhas sem código de produto na prévia de uma importação. O documento deve informar que o trabalho é de análise, não de implementação, e que nenhum dado real de cliente será utilizado. Essas condições são decisões do exercício, não regras universais de todos os sistemas.
Uma versão pouco clara poderia dizer: “revise a importação, veja o código, não mude nada, confira produto vazio e espaços, explique os erros e veja os testes”. A frase mistura quatro responsabilidades. Ela não diz claramente o comportamento esperado nem separa o que deve ser analisado daquilo que será entregue.
A versão organizada pode começar assim:
# Revisão da prévia de importação
## Objetivo
Revisar a alteração que rejeita linhas sem código de produto antes da gravação.
## Escopo
- Analisar a alteração fornecida e os testes disponíveis.
- Não modificar arquivos nem acessar dados reais de clientes.
## Regra de negócio
Neste exemplo fictício, código ausente ou formado somente por espaços
torna a linha inválida. A prévia deve mostrar a rejeição e seu motivo.
Uma linha rejeitada não pode ser gravada.
## Critérios de aceite
1. Código presente mantém a linha elegível para as demais validações.
2. Código ausente produz rejeição com motivo identificável.
3. Código composto por espaços recebe o mesmo tratamento do código ausente.
4. O relatório distingue evidência encontrada, teste executado e teste sugerido.O conteúdo ficou mais fácil de localizar, mas ainda exige material real para uma revisão efetiva. O documento não inclui a alteração, a implementação ou os testes do projeto. Por isso, ele não permite concluir que um importador funciona. Sua função neste capítulo é mostrar como registrar condições e limites antes de examinar essas evidências.
Observe também que código presente não foi tratado como garantia de linha válida. Ele apenas mantém a linha elegível para outras validações. Essa precisão evita que uma frase aparentemente conveniente elimine regras que não fazem parte deste exemplo. Em especificações reais, os critérios precisam representar o domínio completo do escopo analisado, com suas fontes reconhecidas.
Como conferir o arquivo sem confundir níveis de teste
Neste capítulo, o exemplo completo foi salvo como arquivo e convertido com a biblioteca marked, com suas extensões GFM desativadas, em Node.js 25.4.0. Um ensaio local conferiu a quantidade esperada de títulos e itens, o destino do link, a ênfase e o identificador apresentado como código. As verificações foram aprovadas; o registro fica junto da pesquisa do artigo.
Esse ensaio confirma o comportamento daquele exemplo no conversor utilizado. Não demonstra conformidade completa do conversor com CommonMark, nem leitura correta por qualquer agente. Tampouco avalia a regra de negócio da importação. Testar a estrutura de um documento, testar a interpretação de uma instrução e testar o software são atividades relacionadas, mas diferentes.
Você pode começar com uma conferência manual: abra o texto-fonte e sua prévia, identifique os títulos e veja se as listas pertencem às seções esperadas. Depois, peça a outra pessoa para localizar objetivo, restrições e entrega. Se ela precisar reconstruir o documento inteiro para encontrar uma informação simples, a organização ainda pode melhorar.
Para a parte do entendimento, confira a relação entre regras e evidências. O artigo sobre testes gerados com IA aprofunda por que executar uma verificação não demonstra, sozinho, que ela prova a necessidade correta. O mesmo cuidado vale para um arquivo com todos os títulos esperados e conteúdo insuficiente.
Um modelo útil não deve virar uma obrigação vazia
Objetivo, contexto, escopo, referências, critérios e entrega formam um ponto de partida para muitos documentos de trabalho. Não são seções obrigatórias do Markdown. Adapte-as ao problema. Um registro curto pode não precisar de todas; um procedimento complexo pode precisar explicar dependências e interrupções. Evite preencher campos só para deixar o modelo completo.
Separe fatos, regras e exemplos. Se uma mensagem de erro foi imaginada para facilitar a explicação, identifique-a como ilustrativa. Se o comando de compilação pertence ao projeto, confira-o no ambiente correspondente. Se falta uma decisão de negócio, registre a dúvida em vez de transformar uma suposição conveniente em critério definitivo.
Também evite espalhar a mesma regra em vários arquivos. Uma referência central, quando confiável e mantida, permite que outros documentos indiquem onde consultar o contrato. Essa seleção se conecta à engenharia de contexto: organização não significa enviar toda a documentação em toda tarefa.
Por fim, o documento não substitui controle de acesso. Escrever “não alterar” informa uma intenção; impedir uma gravação exige controles técnicos adequados ao ambiente. A clareza do texto favorece revisão e responsabilização, mas não concede permissão nem comprova segurança. Preserve essa diferença ao levar um modelo didático para o trabalho real.
Conclusão
Um arquivo Markdown útil combina sintaxe simples com decisões claras de escrita. Títulos mostram a organização, parágrafos explicam relações, listas reúnem itens comparáveis, links apontam fontes e exemplos preservam detalhes. Nenhum desses recursos compensa uma regra ambígua ou uma conclusão sem evidência.
Comece reorganizando uma tarefa pequena e confira tanto a apresentação quanto o entendimento. Quando a dificuldade passar da forma do documento para a definição do comportamento, SDD em Delphi aprofunda especificações e critérios ligados à implementação e aos testes. Use a degustação para conhecer essa abordagem; um bom arquivo é o início do trabalho de engenharia, não seu encerramento.
Referências
MACFARLANE, John. CommonMark Spec: version 0.31.2. CommonMark, 28 jan. 2024. Disponível em: https://spec.commonmark.org/0.31.2/. Acesso em: 4 out. 2026.
SILVEIRA, Régys Borges da. AGENTS.md, instruções e skills: como orientar uma IA dentro do projeto. regys.com.br, publicação agendada para 20 out. 2026. Disponível em: https://regys.com.br/agents-md-instrucoes-e-skills-como-orientar-uma-ia-dentro-do-projeto/. Acesso em: 4 out. 2026. Consulta ao rascunho.
SILVEIRA, Régys Borges da. Como gerar testes com IA e descobrir quando eles não provam nada. regys.com.br, publicação agendada para 22 out. 2026. Disponível em: https://regys.com.br/como-gerar-testes-com-ia-e-descobrir-quando-eles-nao-provam-nada/. Acesso em: 4 out. 2026. Consulta ao arquivo editorial; reconferir remoto no fechamento.
SILVEIRA, Régys Borges da. Engenharia de contexto: por que um bom prompt não basta para programar com IA. regys.com.br, publicação agendada para 19 out. 2026. Disponível em: https://regys.com.br/engenharia-de-contexto-por-que-um-bom-prompt-nao-basta-para-programar-com-ia/. Acesso em: 4 out. 2026. Consulta ao rascunho.
SILVEIRA, Régys Borges da. SDD em Delphi. Livros de Régys Borges da Silveira, [s. d.]. Disponível em: https://livros.regys.com.br/sdd-em-delphi. Acesso em: 4 out. 2026.
0 comentário(s)