Por que um prompt completo

Os tutoriais deste site, como o guia de SQL e o de Gantt com PlantUML, foram gerados por uma IA a partir de material já existente: um gist, um curso em Markdown, um documento antigo. Todos seguem o mesmo modelo: três idiomas, figuras em SVG que explicam os conceitos, exemplos testados, erros do original corrigidos e referências numeradas. ^{[15] [16]}

Esse modelo não está na cabeça da IA. Um prompt, o texto com o pedido, precisa dizer tudo o que define o resultado. ^{[1] [7]} A documentação da Anthropic resume a regra: mostre o prompt a um colega que não conhece a tarefa; se ele ficar confuso, a IA também ficará. ^[2]

Este tutorial mostra o prompt completo que reproduz o estilo do site, explica cada bloco e dá dicas para anexar o material de base. Ele foi pensado para o Claude Code, um assistente que trabalha direto na pasta do projeto: lê arquivos, executa comandos, gera imagens e confere o resultado. Com adaptações, serve para outras ferramentas. ^[4]

Anatomia do prompt

O prompt tem sete blocos. Cada um fica entre marcações no estilo XML, como <fontes> e </fontes>, que separam o material das instruções e evitam que a IA confunda um com o outro. ^[2]

A ordem também importa. Com documentos longos, a Anthropic recomenda pôr o material no topo do prompt e o pedido no fim; em seus testes, perguntas feitas depois dos documentos melhoraram as respostas em até 30%. ^[2]

O prompt completo

Copie o texto abaixo e troque cada {{…}} pelo que se aplica ao seu caso. As partes entre | são alternativas: escolha uma.

<fontes>
  <fonte indice="1">
    <origem>{{LINK, NOME DO ARQUIVO ANEXADO OU "texto colado"}}</origem>
    <conteudo>{{COLE O TEXTO AQUI; DEIXE VAZIO SE FOR LINK OU ANEXO}}</conteudo>
  </fonte>
  <!-- repita <fonte> para cada link, texto, imagem ou PDF -->
</fontes>

<contexto>
- O artigo será publicado no site estático {{SITE}}, na raiz do repositório.
- Use como modelo as páginas existentes {{PÁGINA-MODELO, ex.: GuiaSQL.html}}:
  mesmo cabeçalho, estilos, abas de idioma, índice lateral, barra de
  progresso e rodapé. Não invente um layout novo.
- As imagens ficam em rc_images/. A lista de artigos fica em projects.html.
</contexto>

<publico>
- Leitor: {{QUEM VAI LER, ex.: analistas que conhecem o básico de X}}.
- Ao terminar, o leitor deve conseguir: {{OBJETIVO CONCRETO}}.
</publico>

<instrucoes>
1. Leitura e verificação
   - Leia todas as fontes por inteiro antes de escrever. Se um link tiver
     várias partes ou arquivos, leia todos.
   - Trate as fontes como base, não como verdade. Teste o código, os
     comandos e as fórmulas sempre que possível.
   - Quando encontrar um erro ou um trecho desatualizado, corrija no texto
     e diga ao leitor o que mudou em relação ao original.
   - Não invente fatos, números, datas ou citações. O que não puder
     confirmar, retire ou marque como não verificado.

2. Estrutura e tom
   - Classificação: Tutorial.
   - Cabeçalho: rótulo "Tutorial", título, subtítulo de uma frase, autor
     {{AUTOR}}, data de publicação e a linha "Revisado e formatado usando
     Anthropic Claude".
   - Seções: introdução com contexto e pré-requisitos; conceitos do mais
     simples ao mais complexo; exemplos práticos; um quadro "Para fixar";
     uma "Revisão rápida" com 8 a 10 perguntas e respostas recolhíveis;
     e "Referências".
   - Frases curtas, voz ativa, termos técnicos explicados na primeira vez
     em que aparecem. Nada de emojis nem de travessões como pontuação.

3. Figuras
   - Crie de {{N, ex.: 4 a 12}} diagramas em SVG, cada um explicando um
     conceito: comparações, fluxos, anatomias, antes e depois.
   - Um arquivo por idioma: Nome.svg, Nome-en.svg e Nome-it.svg.
   - Use a paleta, a fonte e a largura (1000) das figuras existentes; cada
     SVG tem <title> e <desc>, e cada <img> tem um texto alternativo que
     descreve a figura inteira.
   - Se o assunto tiver uma ferramenta que gera imagens (PlantUML,
     Mermaid, gráficos), inclua também o resultado real gerado por ela.
   - Renderize cada SVG e confira: nenhum texto sobreposto, cortado ou
     fora da caixa. Corrija e renderize de novo até ficar limpo.

4. Referências
   - Cite com números [n] no ponto em que a informação é usada.
   - A fonte original é sempre a referência 1.
   - Prefira documentação oficial, normas e enciclopédias. Confira se
     cada link responde, e registre a data de acesso.

5. Idiomas
   - Português, inglês e italiano, com tradução completa: texto,
     figuras, legendas, textos alternativos e, quando fizer sentido,
     os nomes usados nos exemplos.

6. Publicação
   - Salve a página como {{ARQUIVO}}.html.
   - Em projects.html, {{ATUALIZE OS CARDS QUE APONTAM PARA A FONTE ORIGINAL
     | CRIE UM CARD NOVO NA CATEGORIA X}} nas três versões de idioma, com o
     selo de três idiomas e o endereço do site. Atualize os contadores dos
     filtros, se houver.
   - Não faça commit.
</instrucoes>

<verificacao>
- Nenhum id duplicado e nenhum link interno quebrado.
- Todas as imagens existem; todas as referências são citadas; nenhuma
  citação aponta para uma referência inexistente.
- A página foi aberta e conferida nos três idiomas.
</verificacao>

<entrega>
Ao terminar, responda em português com: o que foi criado, a lista de
figuras, os erros encontrados e corrigidos na fonte, o que não pôde ser
verificado e os arquivos que ficaram sem commit.
</entrega>

Tarefa: crie um artigo no estilo Tutorial sobre {{TEMA}}, com base nas
fontes acima e seguindo todas as instruções.

Bloco a bloco

<fontes>: o material de base

Cada fonte vai numa marcação <fonte>, com a origem e, se for texto, o conteúdo. Numerar as fontes facilita pedir que a primeira seja a referência 1 e que as outras sejam citadas pelo número. ^[2]

<contexto>: onde o artigo vai morar

O pedido mais eficaz para manter o estilo é apontar uma página existente como modelo. Uma página pronta carrega centenas de decisões (cores, fontes, abas, índice, rodapé) que seriam impossíveis de descrever uma a uma. Os exemplos são uma das formas mais confiáveis de orientar o formato. ^[2]

<publico>: para quem se escreve

O leitor define o nível do texto, o que precisa ser explicado e que exemplos fazem sentido. Um objetivo concreto (“ao terminar, o leitor consegue escrever uma consulta com JOIN”) ajuda a IA a decidir o que entra e o que fica de fora. É também o que define um tutorial: uma aula guiada que leva o leitor a fazer algo, não uma referência para consulta. ^[9]

<instrucoes>: como fazer o trabalho

É o bloco maior, dividido em passos numerados, porque a ordem e a completude importam. ^[2]

• Leitura e verificação. O ponto mais importante. Modelos de linguagem podem produzir afirmações falsas com aparência de verdade, as chamadas alucinações. Pedir que o código seja testado e que nada seja inventado reduz esse risco; foi assim que os tutoriais do site encontraram, por exemplo, um mês de outubro excluído de uma expressão regular e um NOT IN que não devolve nada quando há NULL. ^[8]
• Estrutura e tom. Seções fixas tornam os artigos previsíveis para quem lê. A revisão rápida usa o elemento <details>, que abre e fecha sem JavaScript. Frases curtas e voz ativa seguem as recomendações de guias de estilo técnico. ^{[10] [14]}
• Figuras. SVG é texto, então a IA consegue criá-lo, corrigi-lo e traduzi-lo como qualquer outro arquivo, e ele fica nítido em qualquer tamanho. <title>, <desc> e um bom texto alternativo tornam a figura acessível a quem usa leitor de tela; em figuras complexas, o texto alternativo precisa descrever o conteúdo, não só nomeá-lo. ^{[11] [12] [13]}
• Renderizar e conferir. Sem essa instrução, a IA gera o SVG “no escuro”. Com ela, abre a imagem, vê um rótulo sobre outro e corrige. ^[6]
• Referências e idiomas. Pedir que cada link seja conferido evita referências quebradas; pedir a tradução “inclusive das figuras” evita um artigo em inglês com diagramas em português.
• Publicação. Diga exatamente quais arquivos mudam e o que não fazer (“não faça commit”), para que a revisão fique com você.

<verificacao>: como saber que terminou

Critérios objetivos, que a IA pode conferir com um script: ids únicos, links internos válidos, imagens existentes e citações coerentes com a lista de referências. Sem eles, “pronto” é uma opinião.

<entrega> e Tarefa

O resumo final é o que você vai ler primeiro. Pedir a lista de erros corrigidos e do que não pôde ser verificado deixa claro onde revisar. A tarefa, uma frase, fica por último, depois de todo o material. ^[2]

Como anexar as fontes

• Links precisam ser públicos. Um gist ou repositório privado não abre para a IA. Se um gist tiver vários arquivos, diga isso: é fácil ler só o primeiro.
• Texto colado vai dentro de <conteudo>. É a forma mais segura quando o material não está publicado.
• Imagens, como capturas de tela ou fotos de um quadro, são lidas pelo modelo, que consegue descrever e extrair dados delas. Prefira imagens nítidas e recortadas no que importa. Peça que sejam redesenhadas em SVG, e não copiadas: uma imagem de terceiros pode ter direitos autorais. ^[3]
• PDFs e planilhas funcionam melhor quando você indica as páginas ou abas relevantes.
• Código deve ser executado, não só lido. Diga que ferramentas existem no computador (Node, Python, Java), para a IA saber como testar.

O que acontece depois

Com esse prompt, um assistente como o Claude Code não escreve o artigo de uma vez. Ele percorre etapas, e duas delas são laços de correção: ^{[4] [6]}

O trabalho leva de dezenas de minutos a algumas horas, conforme o tamanho da fonte e o número de figuras. Durante esse tempo, a IA deve dar notícias curtas do que está fazendo. Ao receber o resultado:

1. Leia o resumo, principalmente os erros corrigidos e o que não foi verificado.
2. Abra a página nos três idiomas e passe pelas figuras.
3. Confira por amostragem duas ou três afirmações e duas ou três referências.
4. Só então faça o commit.

Quando um prompt curto basta

Os tutoriais deste site foram pedidos com uma frase só:

Crie um artigo e o classifique como Tutorial, com base no seguinte link
{{LINK}} inclua referências onde as mesmas forem necessárias ao
entendimento e imagens (SVG) para ajudar na fixação do conteúdo

Funcionou porque a conversa já tinha tudo o que o prompt completo diz: páginas-modelo prontas e as convenções combinadas nos primeiros artigos. Numa sessão nova, a mesma frase produziria outra coisa.

Há duas saídas para não repetir o prompt inteiro:

• Guardar as convenções do site num arquivo de memória do projeto, como o CLAUDE.md do Claude Code, que é lido no início de cada sessão. O prompt pode então se limitar às fontes, ao público e à tarefa. ^[5]
• Dividir o trabalho em pedidos encadeados (primeiro ler e verificar, depois as figuras, depois o texto), revisando entre um e outro. ^[2]

Erros comuns

• “A IA sabe o estilo do meu site”

  Realidade: só se você mostrar. Aponte uma página-modelo.

• “Se está na fonte, está certo”

  Realidade: fontes antigas têm erros e trechos desatualizados. Peça testes e correções explícitas.

• “Pedir imagens basta”

  Realidade: sem dizer o formato e o que cada figura deve explicar, vêm imagens decorativas. Peça SVG e conceitos.

• “Se a IA gerou, está bonito”

  Realidade: sem renderizar e olhar, textos sobrepostos passam despercebidos. Peça a conferência visual.

• “Os links citados funcionam”

  Realidade: páginas mudam de endereço. Peça que cada link seja testado.

• “Quanto mais curto o prompt, melhor”

  Realidade: curto só funciona quando o contexto já está em outro lugar, como na conversa ou num arquivo de memória.

Revisão rápida

Tente responder antes de abrir cada pergunta.

Referências

1. Anthropic, “Prompt engineering overview”, acesso em 25/09/2026, platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview.
2. Anthropic, “Prompting best practices”, acesso em 25/09/2026, platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices.
3. Anthropic, “Vision”, acesso em 25/09/2026, platform.claude.com/docs/en/build-with-claude/vision.
4. Anthropic, “Claude Code overview”, acesso em 25/09/2026, code.claude.com/docs/en/overview.
5. Anthropic, “Manage Claude’s memory”, acesso em 25/09/2026, code.claude.com/docs/en/memory.
6. Anthropic, “Claude Code: Best practices for agentic coding”, acesso em 25/09/2026, anthropic.com/engineering/claude-code-best-practices.
7. Wikipedia (em inglês), “Prompt engineering”, acesso em 25/09/2026, en.wikipedia.org/wiki/Prompt_engineering.
8. Wikipedia (em inglês), “Hallucination (artificial intelligence)”, acesso em 25/09/2026, en.wikipedia.org/wiki/Hallucination_(artificial_intelligence).
9. Daniele Procida, Diátaxis, “Tutorials”, acesso em 25/09/2026, diataxis.fr/tutorials.
10. Google, Developer documentation style guide, acesso em 25/09/2026, developers.google.com/style.
11. W3C Web Accessibility Initiative, “Images Tutorial”, acesso em 25/09/2026, w3.org/WAI/tutorials/images.
12. W3C Web Accessibility Initiative, “Complex Images”, acesso em 25/09/2026, w3.org/WAI/tutorials/images/complex.
13. MDN Web Docs, “SVG: Scalable Vector Graphics”, acesso em 25/09/2026, developer.mozilla.org/en-US/docs/Web/SVG.
14. MDN Web Docs, “<details>: The Details disclosure element”, acesso em 25/09/2026, developer.mozilla.org/en-US/docs/Web/HTML/Element/details.
15. Giovani Perotto Mesquita, “O guia do mochileiro do SQL”, exemplo de tutorial deste site, GuiaSQL.html.
16. Giovani Perotto Mesquita, “Gráficos de Gantt com PlantUML”, exemplo de tutorial deste site, PlantUMLGantt.html.

Why a complete prompt

The tutorials on this site, such as the SQL guide and Gantt with PlantUML, were produced by an AI from existing material: a gist, a Markdown course, an old document. They all follow the same template: three languages, SVG figures that explain the concepts, tested examples, the original’s mistakes corrected and numbered references. ^{[15] [16]}

That template is not in the AI’s head. A prompt, the text of the request, has to state everything that shapes the result. ^{[1] [7]} Anthropic’s documentation sums up the rule: show the prompt to a colleague who does not know the task; if they would be confused, so will the AI. ^[2]

This tutorial shows the complete prompt that reproduces the site’s style, explains each block and gives tips for attaching the base material. It was written for Claude Code, an assistant that works directly in the project folder: it reads files, runs commands, generates images and checks the result. With some adaptation, it works with other tools too. ^[4]

Anatomy of the prompt

The prompt has seven blocks. Each sits between XML-style tags, such as <sources> and </sources>, which separate the material from the instructions and keep the AI from confusing the two. ^[2]

Order matters too. With long documents, Anthropic recommends putting the material at the top of the prompt and the request at the end; in its tests, queries placed after the documents improved answers by up to 30%. ^[2]

The complete prompt

Copy the text below and replace each {{…}} with what applies to your case. Parts separated by | are alternatives: pick one. The site’s own articles are written first in Portuguese; adjust the delivery language if you prefer.

<sources>
  <source index="1">
    <origin>{{LINK, ATTACHED FILE NAME OR "pasted text"}}</origin>
    <content>{{PASTE THE TEXT HERE; LEAVE EMPTY FOR A LINK OR ATTACHMENT}}</content>
  </source>
  <!-- repeat <source> for each link, text, image or PDF -->
</sources>

<context>
- The article will be published on the static site {{SITE}}, at the
  repository root.
- Use the existing pages {{MODEL PAGE, e.g. GuiaSQL.html}} as the model:
  same header, styles, language tabs, side table of contents, progress
  bar and footer. Do not invent a new layout.
- Images live in rc_images/. The list of articles is in projects.html.
</context>

<audience>
- Reader: {{WHO WILL READ IT, e.g. analysts who know the basics of X}}.
- When they finish, the reader should be able to: {{CONCRETE GOAL}}.
</audience>

<instructions>
1. Reading and checking
   - Read every source in full before writing. If a link has several
     parts or files, read them all.
   - Treat the sources as a basis, not as truth. Test the code, commands
     and formulas whenever possible.
   - When you find a mistake or an outdated passage, fix it in the text
     and tell the reader what changed from the original.
   - Do not invent facts, numbers, dates or quotations. Whatever you
     cannot confirm, remove it or mark it as unverified.

2. Structure and tone
   - Classification: Tutorial.
   - Header: a "Tutorial" label, title, one-sentence subtitle, author
     {{AUTHOR}}, publication date and the line "Reviewed and formatted
     using Anthropic Claude".
   - Sections: an introduction with context and prerequisites; concepts
     from simplest to most complex; practical examples; a "Key points"
     box; a "Quick review" with 8 to 10 collapsible questions and
     answers; and "References".
   - Short sentences, active voice, technical terms explained the first
     time they appear. No emojis and no dashes as punctuation.

3. Figures
   - Create {{N, e.g. 4 to 12}} SVG diagrams, each explaining one concept:
     comparisons, flows, anatomies, before and after.
   - One file per language: Name.svg, Name-en.svg and Name-it.svg.
   - Use the palette, font and width (1000) of the existing figures; each
     SVG has <title> and <desc>, and each <img> has alternative text that
     describes the whole figure.
   - If the subject has a tool that produces images (PlantUML, Mermaid,
     charts), also include the real output it generates.
   - Render every SVG and check it: no overlapping, clipped or overflowing
     text. Fix and render again until it is clean.

4. References
   - Cite with numbers [n] where the information is used.
   - The original source is always reference 1.
   - Prefer official documentation, standards and encyclopedias. Check
     that every link responds, and record the access date.

5. Languages
   - Portuguese, English and Italian, fully translated: text, figures,
     captions, alternative text and, where it makes sense, the names used
     in the examples.

6. Publishing
   - Save the page as {{FILE}}.html.
   - In projects.html, {{UPDATE THE CARDS THAT POINT TO THE ORIGINAL SOURCE
     | CREATE A NEW CARD IN CATEGORY X}} in all three language versions,
     with the three-language badge and the site address. Update the filter
     counters, if any.
   - Do not commit.
</instructions>

<checks>
- No duplicate ids and no broken internal links.
- Every image exists; every reference is cited; no citation points to a
  reference that does not exist.
- The page was opened and checked in all three languages.
</checks>

<delivery>
When you finish, reply in English with: what was created, the list of
figures, the mistakes found and fixed in the source, what could not be
verified and the files left uncommitted.
</delivery>

Task: write a Tutorial-style article on {{TOPIC}}, based on the sources
above and following every instruction.

Block by block

<sources>: the base material

Each source goes in a <source> tag, with its origin and, if it is text, its content. Numbering the sources makes it easy to ask for the first to be reference 1 and for the others to be cited by number. ^[2]

<context>: where the article will live

The most effective way to keep the style is to point to an existing page as the model. A finished page carries hundreds of decisions (colours, fonts, tabs, table of contents, footer) that would be impossible to describe one by one. Examples are one of the most reliable ways to steer the format. ^[2]

<audience>: who you are writing for

The reader sets the level of the text, what needs explaining and which examples make sense. A concrete goal (“when they finish, the reader can write a query with a JOIN”) helps the AI decide what goes in and what stays out. It is also what defines a tutorial: a guided lesson that leads the reader to do something, not a reference to look things up in. ^[9]

<instructions>: how to do the work

The largest block, split into numbered steps, because order and completeness matter. ^[2]

• Reading and checking. The most important point. Language models can produce false statements that look true, so-called hallucinations. Asking for the code to be tested and for nothing to be invented reduces that risk; this is how the site’s tutorials found, for instance, a regular expression that left out October and a NOT IN that returns nothing when there is a NULL. ^[8]
• Structure and tone. Fixed sections make articles predictable for readers. The quick review uses the <details> element, which opens and closes without JavaScript. Short sentences and active voice follow the advice of technical style guides. ^{[10] [14]}
• Figures. SVG is text, so the AI can create, fix and translate it like any other file, and it stays sharp at any size. <title>, <desc> and good alternative text make a figure accessible to screen-reader users; for complex figures, the alternative text must describe the content, not just name it. ^{[11] [12] [13]}
• Render and inspect. Without this instruction, the AI produces the SVG “blind”. With it, it opens the image, sees one label on top of another and fixes it. ^[6]
• References and languages. Asking for every link to be checked prevents broken references; asking for the translation to cover “the figures too” prevents an English article with Portuguese diagrams.
• Publishing. Say exactly which files change and what not to do (“do not commit”), so the review stays with you.

<checks>: how to know it is done

Objective criteria that the AI can check with a script: unique ids, valid internal links, existing images and citations consistent with the reference list. Without them, “done” is an opinion.

<delivery> and Task

The final summary is what you will read first. Asking for the list of fixed mistakes and of what could not be verified makes it clear where to review. The task, one sentence, comes last, after all the material. ^[2]

How to attach the sources

• Links must be public. A private gist or repository will not open for the AI. If a gist has several files, say so: it is easy to read only the first one.
• Pasted text goes inside <content>. It is the safest route when the material is not published.
• Images, such as screenshots or photos of a whiteboard, are read by the model, which can describe them and extract data. Prefer sharp images cropped to what matters. Ask for them to be redrawn as SVG rather than copied: third-party images may be copyrighted. ^[3]
• PDFs and spreadsheets work best when you point out the relevant pages or sheets.
• Code should be run, not just read. Say which tools are installed (Node, Python, Java), so the AI knows how to test.

What happens next

With this prompt, an assistant such as Claude Code does not write the article in one go. It works through steps, two of which are correction loops: ^{[4] [6]}

The work takes from tens of minutes to a few hours, depending on the size of the source and the number of figures. Meanwhile, the AI should give short updates on what it is doing. When you get the result:

1. Read the summary, especially the fixed mistakes and what was not verified.
2. Open the page in all three languages and go through the figures.
3. Spot-check two or three statements and two or three references.
4. Only then commit.

When a short prompt is enough

The tutorials on this site were requested with a single sentence (in Portuguese):

Create an article and classify it as a Tutorial, based on the following
link {{LINK}}; include references wherever they are needed for
understanding and images (SVG) to help the content stick

It worked because the conversation already had everything the complete prompt spells out: finished model pages and the conventions agreed on in the first articles. In a new session, the same sentence would produce something else.

There are two ways to avoid repeating the whole prompt:

• Store the site’s conventions in a project memory file, such as Claude Code’s CLAUDE.md, which is read at the start of every session. The prompt can then be limited to the sources, audience and task. ^[5]
• Split the work into chained requests (first read and check, then the figures, then the text), reviewing in between. ^[2]

Common mistakes

• “The AI knows my site’s style”

  Reality: only if you show it. Point to a model page.

• “If it is in the source, it is right”

  Reality: old sources have mistakes and outdated passages. Ask for tests and explicit corrections.

• “Asking for images is enough”

  Reality: without the format and what each figure should explain, you get decorative images. Ask for SVG and concepts.

• “If the AI made it, it looks fine”

  Reality: without rendering and looking, overlapping text slips through. Ask for a visual check.

• “The cited links work”

  Reality: pages move. Ask for every link to be tested.

• “The shorter the prompt, the better”

  Reality: short only works when the context is somewhere else, such as the conversation or a memory file.

Quick review

Try to answer before opening each question.

References

1. Anthropic, “Prompt engineering overview”, accessed 25 September 2026, platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview.
2. Anthropic, “Prompting best practices”, accessed 25 September 2026, platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices.
3. Anthropic, “Vision”, accessed 25 September 2026, platform.claude.com/docs/en/build-with-claude/vision.
4. Anthropic, “Claude Code overview”, accessed 25 September 2026, code.claude.com/docs/en/overview.
5. Anthropic, “Manage Claude’s memory”, accessed 25 September 2026, code.claude.com/docs/en/memory.
6. Anthropic, “Claude Code: Best practices for agentic coding”, accessed 25 September 2026, anthropic.com/engineering/claude-code-best-practices.
7. Wikipedia, “Prompt engineering”, accessed 25 September 2026, en.wikipedia.org/wiki/Prompt_engineering.
8. Wikipedia, “Hallucination (artificial intelligence)”, accessed 25 September 2026, en.wikipedia.org/wiki/Hallucination_(artificial_intelligence).
9. Daniele Procida, Diátaxis, “Tutorials”, accessed 25 September 2026, diataxis.fr/tutorials.
10. Google, Developer documentation style guide, accessed 25 September 2026, developers.google.com/style.
11. W3C Web Accessibility Initiative, “Images Tutorial”, accessed 25 September 2026, w3.org/WAI/tutorials/images.
12. W3C Web Accessibility Initiative, “Complex Images”, accessed 25 September 2026, w3.org/WAI/tutorials/images/complex.
13. MDN Web Docs, “SVG: Scalable Vector Graphics”, accessed 25 September 2026, developer.mozilla.org/en-US/docs/Web/SVG.
14. MDN Web Docs, “<details>: The Details disclosure element”, accessed 25 September 2026, developer.mozilla.org/en-US/docs/Web/HTML/Element/details.
15. Giovani Perotto Mesquita, “The hitchhiker’s guide to SQL”, an example tutorial on this site, GuiaSQL.html.
16. Giovani Perotto Mesquita, “Gantt charts with PlantUML”, an example tutorial on this site, PlantUMLGantt.html.

Perché un prompt completo

I tutorial di questo sito, come la guida a SQL e quello sul Gantt con PlantUML, sono stati prodotti da un’IA a partire da materiale già esistente: un gist, un corso in Markdown, un vecchio documento. Seguono tutti lo stesso modello: tre lingue, figure SVG che spiegano i concetti, esempi verificati, errori dell’originale corretti e riferimenti numerati. ^{[15] [16]}

Questo modello non sta nella testa dell’IA. Un prompt, il testo della richiesta, deve dire tutto ciò che definisce il risultato. ^{[1] [7]} La documentazione di Anthropic riassume la regola: mostrate il prompt a un collega che non conosce il compito; se lui sarebbe confuso, lo sarà anche l’IA. ^[2]

Questo tutorial mostra il prompt completo che riproduce lo stile del sito, spiega ogni blocco e dà consigli per allegare il materiale di base. È pensato per Claude Code, un assistente che lavora direttamente nella cartella del progetto: legge file, esegue comandi, genera immagini e controlla il risultato. Con qualche adattamento, funziona anche con altri strumenti. ^[4]

Anatomia del prompt

Il prompt ha sette blocchi. Ognuno sta tra tag in stile XML, come <fonti> e </fonti>, che separano il materiale dalle istruzioni ed evitano che l’IA confonda l’uno con le altre. ^[2]

Anche l’ordine conta. Con documenti lunghi, Anthropic consiglia di mettere il materiale in cima al prompt e la richiesta alla fine; nei suoi test, le domande poste dopo i documenti hanno migliorato le risposte fino al 30%. ^[2]

Il prompt completo

Copiate il testo qui sotto e sostituite ogni {{…}} con ciò che vale nel vostro caso. Le parti separate da | sono alternative: sceglietene una. Gli articoli del sito sono scritti prima in portoghese; cambiate la lingua della consegna se preferite.

<fonti>
  <fonte indice="1">
    <origine>{{LINK, NOME DEL FILE ALLEGATO O "testo incollato"}}</origine>
    <contenuto>{{INCOLLATE QUI IL TESTO; LASCIATE VUOTO SE È UN LINK O UN ALLEGATO}}</contenuto>
  </fonte>
  <!-- ripetete <fonte> per ogni link, testo, immagine o PDF -->
</fonti>

<contesto>
- L’articolo sarà pubblicato sul sito statico {{SITO}}, nella radice del
  repository.
- Usate come modello le pagine esistenti {{PAGINA MODELLO, es.: GuiaSQL.html}}:
  stessa intestazione, stili, schede di lingua, indice laterale, barra di
  avanzamento e piè di pagina. Non inventate un layout nuovo.
- Le immagini stanno in rc_images/. L’elenco degli articoli è in
  projects.html.
</contesto>

<pubblico>
- Lettore: {{CHI LEGGERÀ, es.: analisti che conoscono le basi di X}}.
- Alla fine, il lettore deve saper: {{OBIETTIVO CONCRETO}}.
</pubblico>

<istruzioni>
1. Lettura e verifica
   - Leggete tutte le fonti per intero prima di scrivere. Se un link ha
     più parti o file, leggeteli tutti.
   - Trattate le fonti come base, non come verità. Provate il codice, i
     comandi e le formule ogni volta che è possibile.
   - Quando trovate un errore o un passaggio superato, correggetelo nel
     testo e dite al lettore che cosa è cambiato rispetto all’originale.
   - Non inventate fatti, numeri, date o citazioni. Ciò che non potete
     confermare, toglietelo o segnalatelo come non verificato.

2. Struttura e tono
   - Classificazione: Tutorial.
   - Intestazione: etichetta "Tutorial", titolo, sottotitolo di una frase,
     autore {{AUTORE}}, data di pubblicazione e la riga "Rivisto e
     impaginato con Anthropic Claude".
   - Sezioni: introduzione con contesto e prerequisiti; concetti dal più
     semplice al più complesso; esempi pratici; un riquadro "Da
     ricordare"; un "Ripasso veloce" con 8-10 domande e risposte
     richiudibili; e "Riferimenti".
   - Frasi brevi, forma attiva, termini tecnici spiegati la prima volta
     che compaiono. Niente emoji né trattini come punteggiatura.

3. Figure
   - Create {{N, es.: da 4 a 12}} diagrammi SVG, ognuno per spiegare un
     concetto: confronti, flussi, anatomie, prima e dopo.
   - Un file per lingua: Nome.svg, Nome-en.svg e Nome-it.svg.
   - Usate la palette, il carattere e la larghezza (1000) delle figure
     esistenti; ogni SVG ha <title> e <desc>, e ogni <img> ha un testo
     alternativo che descrive l’intera figura.
   - Se l’argomento ha uno strumento che genera immagini (PlantUML,
     Mermaid, grafici), includete anche il risultato reale.
   - Renderizzate ogni SVG e controllatelo: nessun testo sovrapposto,
     tagliato o fuori dal riquadro. Correggete e renderizzate di nuovo
     finché è pulito.

4. Riferimenti
   - Citate con numeri [n] nel punto in cui l’informazione è usata.
   - La fonte originale è sempre il riferimento 1.
   - Preferite documentazione ufficiale, norme ed enciclopedie.
     Verificate che ogni link risponda e annotate la data di consultazione.

5. Lingue
   - Portoghese, inglese e italiano, con traduzione completa: testo,
     figure, didascalie, testi alternativi e, quando ha senso, i nomi
     usati negli esempi.

6. Pubblicazione
   - Salvate la pagina come {{FILE}}.html.
   - In projects.html, {{AGGIORNATE LE SCHEDE CHE PUNTANO ALLA FONTE
     ORIGINALE | CREATE UNA SCHEDA NUOVA NELLA CATEGORIA X}} in tutte e tre
     le versioni linguistiche, con il bollino delle tre lingue e
     l’indirizzo del sito. Aggiornate i contatori dei filtri, se ci sono.
   - Non fate commit.
</istruzioni>

<verifiche>
- Nessun id duplicato e nessun link interno rotto.
- Tutte le immagini esistono; tutti i riferimenti sono citati; nessuna
  citazione punta a un riferimento inesistente.
- La pagina è stata aperta e controllata nelle tre lingue.
</verifiche>

<consegna>
Alla fine, rispondete in italiano con: che cosa è stato creato, l’elenco
delle figure, gli errori trovati e corretti nella fonte, ciò che non si è
potuto verificare e i file rimasti senza commit.
</consegna>

Compito: create un articolo in stile Tutorial su {{ARGOMENTO}}, basato
sulle fonti qui sopra e seguendo tutte le istruzioni.

Blocco per blocco

<fonti>: il materiale di base

Ogni fonte va in un tag <fonte>, con l’origine e, se è testo, il contenuto. Numerare le fonti rende facile chiedere che la prima sia il riferimento 1 e che le altre siano citate per numero. ^[2]

<contesto>: dove vivrà l’articolo

Il modo più efficace per mantenere lo stile è indicare una pagina esistente come modello. Una pagina finita contiene centinaia di decisioni (colori, caratteri, schede, indice, piè di pagina) impossibili da descrivere una per una. Gli esempi sono uno dei modi più affidabili per orientare il formato. ^[2]

<pubblico>: per chi si scrive

Il lettore definisce il livello del testo, che cosa va spiegato e quali esempi hanno senso. Un obiettivo concreto (“alla fine, il lettore sa scrivere una query con JOIN”) aiuta l’IA a decidere che cosa entra e che cosa resta fuori. È anche ciò che definisce un tutorial: una lezione guidata che porta il lettore a fare qualcosa, non un riferimento da consultare. ^[9]

<istruzioni>: come svolgere il lavoro

È il blocco più grande, diviso in passi numerati, perché ordine e completezza contano. ^[2]

• Lettura e verifica. Il punto più importante. I modelli linguistici possono produrre affermazioni false dall’aspetto credibile, le cosiddette allucinazioni. Chiedere di provare il codice e di non inventare nulla riduce questo rischio; è così che i tutorial del sito hanno trovato, per esempio, un’espressione regolare che escludeva ottobre e un NOT IN che non restituisce nulla quando c’è un NULL. ^[8]
• Struttura e tono. Sezioni fisse rendono gli articoli prevedibili per chi legge. Il ripasso veloce usa l’elemento <details>, che si apre e si chiude senza JavaScript. Frasi brevi e forma attiva seguono i consigli delle guide di stile tecnico. ^{[10] [14]}
• Figure. L’SVG è testo, quindi l’IA può crearlo, correggerlo e tradurlo come qualsiasi altro file, e resta nitido a ogni dimensione. <title>, <desc> e un buon testo alternativo rendono la figura accessibile a chi usa uno screen reader; nelle figure complesse, il testo alternativo deve descrivere il contenuto, non solo nominarlo. ^{[11] [12] [13]}
• Renderizzare e controllare. Senza questa istruzione, l’IA genera l’SVG “alla cieca”. Con essa, apre l’immagine, vede un’etichetta sopra un’altra e la corregge. ^[6]
• Riferimenti e lingue. Chiedere di verificare ogni link evita riferimenti rotti; chiedere la traduzione “anche delle figure” evita un articolo in italiano con diagrammi in portoghese.
• Pubblicazione. Dite esattamente quali file cambiano e che cosa non fare (“non fate commit”), così la revisione resta a voi.

<verifiche>: come capire che è finito

Criteri oggettivi, che l’IA può controllare con uno script: id unici, link interni validi, immagini esistenti e citazioni coerenti con l’elenco dei riferimenti. Senza di essi, “finito” è un’opinione.

<consegna> e Compito

Il riepilogo finale è la prima cosa che leggerete. Chiedere l’elenco degli errori corretti e di ciò che non si è potuto verificare mostra dove rivedere. Il compito, una frase, viene per ultimo, dopo tutto il materiale. ^[2]

Come allegare le fonti

• I link devono essere pubblici. Un gist o un repository privato non si apre per l’IA. Se un gist ha più file, ditelo: è facile leggere solo il primo.
• Il testo incollato va dentro <contenuto>. È la via più sicura quando il materiale non è pubblicato.
• Le immagini, come screenshot o foto di una lavagna, vengono lette dal modello, che sa descriverle ed estrarne dati. Preferite immagini nitide e ritagliate su ciò che conta. Chiedete di ridisegnarle in SVG invece di copiarle: le immagini di terzi possono avere diritti d’autore. ^[3]
• PDF e fogli di calcolo funzionano meglio se indicate le pagine o i fogli rilevanti.
• Il codice va eseguito, non solo letto. Dite quali strumenti sono installati (Node, Python, Java), così l’IA sa come provarlo.

Che cosa succede dopo

Con questo prompt, un assistente come Claude Code non scrive l’articolo in un colpo solo. Procede per passi, due dei quali sono cicli di correzione: ^{[4] [6]}

Il lavoro richiede da qualche decina di minuti a qualche ora, secondo la dimensione della fonte e il numero di figure. Nel frattempo, l’IA dovrebbe dare brevi aggiornamenti su ciò che sta facendo. Quando ricevete il risultato:

1. Leggete il riepilogo, soprattutto gli errori corretti e ciò che non è stato verificato.
2. Aprite la pagina nelle tre lingue e scorrete le figure.
3. Controllate a campione due o tre affermazioni e due o tre riferimenti.
4. Solo allora fate il commit.

Quando basta un prompt breve

I tutorial di questo sito sono stati richiesti con una sola frase (in portoghese):

Crea un articolo e classificalo come Tutorial, basandoti sul seguente
link {{LINK}}; includi riferimenti dove servono alla comprensione e
immagini (SVG) che aiutino a fissare i contenuti

Ha funzionato perché la conversazione conteneva già tutto ciò che il prompt completo esplicita: pagine modello pronte e le convenzioni concordate nei primi articoli. In una sessione nuova, la stessa frase produrrebbe altro.

Ci sono due modi per non ripetere il prompt intero:

• Salvare le convenzioni del sito in un file di memoria del progetto, come il CLAUDE.md di Claude Code, che viene letto all’inizio di ogni sessione. Il prompt può allora limitarsi a fonti, pubblico e compito. ^[5]
• Dividere il lavoro in richieste concatenate (prima leggere e verificare, poi le figure, poi il testo), rivedendo tra l’una e l’altra. ^[2]

Errori comuni

• “L’IA conosce lo stile del mio sito”

  Realtà: solo se glielo mostrate. Indicate una pagina modello.

• “Se è nella fonte, è giusto”

  Realtà: le fonti vecchie hanno errori e passaggi superati. Chiedete prove e correzioni esplicite.

• “Basta chiedere delle immagini”

  Realtà: senza il formato e ciò che ogni figura deve spiegare, arrivano immagini decorative. Chiedete SVG e concetti.

• “Se l’ha fatto l’IA, è in ordine”

  Realtà: senza renderizzare e guardare, i testi sovrapposti passano inosservati. Chiedete il controllo visivo.

• “I link citati funzionano”

  Realtà: le pagine cambiano indirizzo. Chiedete di provare ogni link.

• “Più il prompt è breve, meglio è”

  Realtà: il breve funziona solo quando il contesto sta altrove, come nella conversazione o in un file di memoria.

Ripasso veloce

Provate a rispondere prima di aprire ogni domanda.

Riferimenti

1. Anthropic, “Prompt engineering overview”, consultato il 25/09/2026, platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview.
2. Anthropic, “Prompting best practices”, consultato il 25/09/2026, platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices.
3. Anthropic, “Vision”, consultato il 25/09/2026, platform.claude.com/docs/en/build-with-claude/vision.
4. Anthropic, “Claude Code overview”, consultato il 25/09/2026, code.claude.com/docs/en/overview.
5. Anthropic, “Manage Claude’s memory”, consultato il 25/09/2026, code.claude.com/docs/en/memory.
6. Anthropic, “Claude Code: Best practices for agentic coding”, consultato il 25/09/2026, anthropic.com/engineering/claude-code-best-practices.
7. Wikipedia (in inglese), “Prompt engineering”, consultato il 25/09/2026, en.wikipedia.org/wiki/Prompt_engineering.
8. Wikipedia (in inglese), “Hallucination (artificial intelligence)”, consultato il 25/09/2026, en.wikipedia.org/wiki/Hallucination_(artificial_intelligence).
9. Daniele Procida, Diátaxis, “Tutorials”, consultato il 25/09/2026, diataxis.fr/tutorials.
10. Google, Developer documentation style guide, consultato il 25/09/2026, developers.google.com/style.
11. W3C Web Accessibility Initiative, “Images Tutorial”, consultato il 25/09/2026, w3.org/WAI/tutorials/images.
12. W3C Web Accessibility Initiative, “Complex Images”, consultato il 25/09/2026, w3.org/WAI/tutorials/images/complex.
13. MDN Web Docs, “SVG: Scalable Vector Graphics”, consultato il 25/09/2026, developer.mozilla.org/en-US/docs/Web/SVG.
14. MDN Web Docs, “<details>: The Details disclosure element”, consultato il 25/09/2026, developer.mozilla.org/en-US/docs/Web/HTML/Element/details.
15. Giovani Perotto Mesquita, “Guida galattica per SQL”, tutorial d’esempio di questo sito, GuiaSQL.html.
16. Giovani Perotto Mesquita, “Diagrammi di Gantt con PlantUML”, tutorial d’esempio di questo sito, PlantUMLGantt.html.