Quando usar

Use Typst em vez de Word/.docx para qualquer relatório técnico detalhado — relatórios de investigação, resumos de arquitetura, documentação de causa raiz, explicadores de migração. Documentos alvo que:

Pareçam um relatório técnico real: página de título, resumo executivo, seções numeradas
Tenham boa aparência na impressão (tipografia semelhante ao LaTeX: #set page, #set heading(numbering: "1.1"), texto justificado)
Incluam diagramas (diagramas de arquitetura/fluxo, não apenas prosa)
Incluam tabelas (tabelas de comparação, tabelas de evidências, tabelas de status)
Incluam links clicáveis para fontes (tópicos de chat, PRs do GitHub, páginas wiki)
Cites fontes primárias com citações diretas (mensagens, corpos de PR) atribuídas por nome/data

Frases de gatilho: "escreva isso", "crie um documento", "typst it", "faça um relatório sobre isso" — especialmente após uma investigação de múltiplas fontes (pesquisa de chat, revisão de PR do GitHub, evidências de sistema ao vivo) que precisam ser sintetizadas em um artefato compartilhável.

Antes de compilar, mantenha e consulte um arquivo pessoal de armadilhas do Typst (ex.: ~/notes/typst.md) para armadilhas de sintaxe conhecidas (posicionamento de nota de rodapé, colisões #N, importação do fletcher, dimensionamento de colunas de tabela, etc.) — e anexe a ele sempre que uma nova classe de erro de compilação for descoberta.

Regras de Sintaxe Críticas (Lista de verificação pré-voo antes de typst compile):

A marcação de negrito é *palavra*, NUNCA **palavra**: Os dois asteriscos do Markdown emitem dezenas de avisos do compilador (warning: no text within stars; using multiple consecutive stars has no additional effect).
Strings no modo matemático exigem aspas: Em $ ... $ , identificadores com várias letras como $Count=65$ ou $RTO$ falham na compilação (unknown variable). Escreva $"Count"=65$ ou coloque o código em crases (`Count=65`).
Nenhum operador de barra invertida do LaTeX em matemática: Escrever $\approx$ falha (unknown variable: pprox). Typst usa símbolos nus: $approx$ sem uma barra invertida.

Aprofunde-se no conteúdo; seja consciente com recursos sobre apresentação

Duas diretrizes permanentes que moldam cada relatório:

Aprofunde-se em conteúdo técnico genuíno. Busque profundidade técnica excruciante, não um resumo superficial — mais saída de console bruta, mais diagramas de arquitetura/máquina de estados, detalhamento de registradores/campos de bits ou nível de circuito digital quando o assunto for próximo a hardware, detalhamento de nível de instrução de CPU/assembly quando o assunto for próximo à execução de software. Quando um rascunho parecer "pronto" em 5-6 páginas, isso é um sinal para cavar uma camada mais fundo (um dump extra de redis-cli/systemctl/register, um diagrama de arquitetura extra, um ângulo de comparação da indústria extra), não para parar. Veja "Expectativa de profundidade" abaixo para a divisão concreta seção por seção.
Mas seja consciente com recursos sobre a apresentação, não sobre o conteúdo. A profundidade do conteúdo e a consciência de recursos da estilização são eixos separados — aprofunde-se em fatos/evidências/diagramas, mas mantenha a apresentação visual em si com pouca tinta: fundos com tonalidade clara + bordas/texto coloridos em vez de preenchimentos de cor sólida, e cor usada apenas onde carrega significado (veja Esquema de cores abaixo). Pouca tinta rege a página do corpo da tinta, NÃO o bloco de título — o título DEVE ter caixa (veja Esquema de cores item 1). Mais páginas de substância técnica real é o objetivo; mais tinta de cor sólida por página não é.

Fluxo de trabalho

Colete TODAS as evidências primeiro (pesquisas de chat, leituras de PR do GitHub, saída de comando ao vivo, pesquisa de arte anterior no issue-tracker/chat) antes de escrever — não comece o arquivo .typ durante a pesquisa; sintetize de uma vez.
Escreva o código-fonte .typ completo em uma ou duas chamadas write/eval, usando o modelo de estrutura acima (título em caixa com acento único, títulos com acento e uma regra fina, cabeçalhos de tabela com tonalidade clara, chamadas semânticas em 2 a 4 momentos-chave escolhidos pelo significado e não pela novidade, blocos de console claros, diagramas fletcher envoltos em #figure para gráficos de nós, sem sumário por padrão). Se usar fletcher, SEMPRE inicie o arquivo com #import "@preview/fletcher:0.5.7": diagram, node, edge — omitir esta importação é o erro de primeira compilação mais comum.
Compile: typst compile arquivo.typ (de um diretório de trabalho onde o arquivo reside — verifique typst --version uma vez por sessão para confirmar que o binário está disponível; se usar fletcher, uma compilação de teste descartável em /tmp confirma a resolução de rede/pacote antes de conectá-lo ao documento real). Encontrou um erro de compilação? Verifique seu arquivo de notas de armadilhas antes de depurar do zero.
Sempre verifique visualmente antes de declarar concluído — renderize cada página para PNG (typst compile --format png --ppi 100 arquivo.typ "pagina-{p}.png" — coloque o padrão de saída entre aspas) e read cada PNG para inspecionar layout/espaçamento/renderização, especialmente qualquer página com um diagrama, tabela ou chamada. Diagramas com 3+ arestas ou pares de arestas bidirecionais precisam de escrutínio particular para colisões de rótulos.
Em seguida, faça uma passagem de LEITURA de conteúdo separada — a verificação de layout não é verificação de conteúdo. O passo 4 prova que nada está renderizado errado; NÃO prova que nada está verdadeiro. read cada página renderizada novamente, desta vez lendo a prosa contra o material de origem, e especificamente procure: (a) referências cruzadas de seção digitadas à mão ("veja §9.1.3") que ficaram desatualizadas quando um capítulo foi inserido; (b) células de tabela cuja afirmação está invertida ou transposta em relação à fonte; (c) números que foram transcritos de segunda mão em vez do artefato primário — marque-os com [INFERÊNCIA] ou vá verificá-los. Confirmado necessário na prática: um documento que passou na passagem de layout completa ainda continha uma referência § pendente E uma célula de tabela factualmente invertida, ambos capturados apenas pela leitura. Um documento de 40 KB escrito em uma passagem NÃO foi revisado apenas porque compilou.
Mova o arquivo .typ + .pdf final para o local de documentos do projeto (ex.: docs/generated/) e commit ambos, em seguida, exclua quaisquer arquivos de verificação PNG intermediários — mantenha a fonte junto com a saída compilada para que possa ser reeditada posteriormente.

Use marcação semântica

De acordo com o próprio guia de acessibilidade do Typst: sempre use o elemento semântico real (= Heading, #quote(...), #table(...)) em vez de estilizar manualmente texto simples/prosa para parecer com aquele elemento (ex.: #text(size: 16pt, weight: "bold")[Heading]). Nunca invente uma convenção paralela "parece um título"; sempre conduza a aparência a partir do elemento de marcação real.

Esquema de cores

Fonte do corpo: New Computer Modern. O benchmark é "como LaTeX" — NCM é a aparência do LaTeX e vem com Typst, então sempre resolve. NUNCA escolha uma fonte que não esteja instalada na máquina (verifique com typst fonts): Typst apenas avisa sobre uma família ausente e volta silenciosamente para uma fonte padrão, então o documento compila "limpo" enquanto parece errado. Se um aviso unknown font family aparecer, isso é um defeito a ser corrigido, não um aviso a ser tolerado.
Paleta de chamadas semânticas. verde #1a7f37, amarelo #9a6700, vermelho #cf222e, azul #0969da, roxo #6639ba, laranja #bc4c00; tons de console/tabela #f2f6fb / #eaf1fb com borda #9fb8d6 / #c8d6e8. raw inline e em bloco devem usar uma família monoespaçada que existe na máquina (ex.: Consolas, JetBrains Mono, Menlo).

Uma cor de acento estrutural, usada apenas para moldura — mais blocos de chamada semântica para significado. Este é o padrão estabelecido; aplique-o por padrão sem re-derivar do zero:

Bloco de título: texto colorido centralizado com caixa com borda. Use #box(fill: white, stroke: 1.5pt + accent, ...) ao redor do título.
Cabeçalhos de tabela: preenchimento de tonalidade clara + texto na cor de acento, NUNCA um preenchimento de cor sólida.
Blocos de chamada semântica para descobertas significativas — é aqui que a cor extra é merecida, porque é funcional, não decorativa. Use aquele que se encaixar no conteúdo; não force todos em todos os documentos — 2-4 chamadas totais por relatório é uma boa densidade, não uma por parágrafo.
- Verificado (marca de seleção verde) — descoberta confirmada como boa, uma linha.
- Anomalia (exclamação amarela) — inesperado, mas ainda não confirmado como um defeito.
- Defeito confirmado (X vermelho) — descoberta confirmada como ruim, uma linha.
- Nota (informação azul) — uma observação não crítica que vale a pena destacar.
- Dica (lâmpada roxa) — uma sugestão útil ou melhor prática.
- Pergunta em aberto (ponto de interrogação laranja) — uma discrepância ou consulta genuína não resolvida.
Varie a tonalidade por documento/seção onde ajuda na legibilidade da impressão.
As cores das caixas do diagrama permanecem baseadas em função/semântica.
Nenhum preenchimento grande de cor escura sólida em qualquer lugar (ex.: um banner azul escuro completo com texto branco). Títulos de seção: texto colorido + uma regra colorida fina abaixo, não uma faixa ou caixa de cor preenchida.
Blocos de console/saída de código: fundo com tonalidade clara, não cinza. Um cinza plano #f4f4f4 parece monótono/como fotocópia. Use uma tonalidade clara com uma borda combinando sutil.
NUNCA use #pagebreak() entre capítulos. Uma quebra antes de cada título = deixa meia página de papel em branco por capítulo e desperdiça folhas reais quando impresso. Deixe as seções fluírem; um novo capítulo começando no meio da página está CORRETO. O único #pagebreak() aceitável é aquele único que separa a página de título do corpo.

Duas seções padrão — inclua-as sem ser solicitado

Contexto competitivo / da indústria. Como as alternativas resolvem esse problema, e o que esta posição arquitetônica compra e custa estruturalmente? Enquadre cada vantagem como um risco testável correspondente. Rotule a seção como conhecimento geral da indústria com [INFERÊNCIA] a menos que venha de um documento competitivo real.
O harness de automação / teste, concretamente. Invocação exata, host executor, venv e deps fixadas, seleção de marcadores e como ler contagens de coletados vs desmarcados vs executados. "Existe uma suíte" não é cobertura.

Posicionamento de figuras: envolva diagramas/tabelas em `#figure(...)`, deixe Typst flutuá-los

De acordo com a própria orientação de layout do Typst, as figuras padrão são colocadas inline no fluxo de conteúdo, mas envolver um diagrama ou tabela em #figure(..., caption: [...]) desbloqueia placement: top/placement: bottom para permitir que Typst o flutue para o topo/fundo da página em vez de dividir o conteúdo desajeitadamente ao redor dele no meio de um parágrafo. Sempre dê aos diagramas um invólucro #figure(...) com uma legenda real (nunca uma chamada #diagram(...) nua flutuando na prosa) — isso também é o que torna o diagrama referenciável cruzadamente via @sec-label e dá aos leitores de tela/ferramentas de reaproveitamento um par figura+legenda semântica adequado, não apenas uma imagem sem rótulo.

Fletcher para diagramas de nós/arestas

Padrão de trabalho, confirmado compilando e renderizando corretamente (envolto em #figure de acordo com a orientação de posicionamento acima). Lembre-se da importação (veja Etapa 2 do Fluxo de trabalho) — este trecho assume que já está no topo do arquivo:

#figure(
  diagram(
    node-stroke: 0.6pt,
    spacing: (3em, 2em),
    node((0,0), [Passo 1], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    node((0,1), [Passo 2], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    edge((0,0), (0,1), "-|>", bend: 10deg),
    edge((0,1), (0,0), "-|>", bend: 10deg),
  ),
  caption: [Legenda de uma linha explicando ambas as direções/arestas, já que os rótulos inline são omitidos aqui.],
)

As coordenadas são tuplas (coluna, linha); node-stroke/fill/corner-radius estilizam nós individuais; edge(from, to, "-|>") desenha uma seta (a string de marca, não um argumento de palavra-chave, seleciona a ponta de seta — "-|>" e "->" ambos funcionam; "..|>" para uma seta pontilhada). Múltiplas cadeias independentes podem compartilhar uma chamada diagram(...) usando diferentes índices de coluna por cadeia mais um nó de linha de cabeçalho com stroke: none por cadeia. Mantenha os rótulos de aresta para uma palavra/frase curta e mova a explicação completa para a caption da figura — rótulos de aresta inline mais longos que uma palavra são a falha clássica de colisão de rótulos.

Expectativa de profundidade: padrão para formato longo, nerd-profundo, não um resumo

A menos que explicitamente solicitado algo curto, almeje 10-12 páginas renderizadas para um relatório de investigação completo — um relatório curto, correto, mas superficial, é um modo de falha, não um resultado eficiente. Concretamente, "ir a fundo" significa incluir, onde quer que o assunto suporte:

Saída completa de console/log bruta, não trechos truncados — comando real + saída real, verbatim, para cada afirmação que veio de evidência de sistema ao vivo.
Pelo menos um diagrama de arquitetura ou máquina de estados (via fletcher, veja acima) mostrando como as peças realmente se conectam, não apenas prosa descrevendo.
Detalhamento de nível de registrador/campo de bits ou circuito digital quando o assunto for próximo a hardware (ex.: layout de bits de um registrador de configuração específico, um diagrama de temporização de sinal, uma tabela de mapeamento de portas de um bloco ASIC, definições reais de struct/opcode extraídas do código-fonte do driver real) — não pare em "o hardware faz X", mostre o mecanismo real.
Detalhamento de nível de instrução de CPU/assembly ou syscall quando o assunto for próximo à execução de software (ex.: qual syscall um driver realmente emite, como é a desmontagem do caminho quente) — não pare em "o driver faz X", mostre o caminho de código real.
Uma seção dedicada de Contexto da Indústria/Externo (veja abaixo) — nunca apresente um mecanismo interno isoladamente.
Pesquisa genuína de arte anterior/histórico — verifique o issue tracker, o histórico de chat e o histórico do git para saber se esta mesma pergunta foi feita antes (mesmo anos antes); um relatório que fecha uma pergunta em aberto de vários anos é uma evidência mais forte do que um que trata uma descoberta como totalmente nova.

Estrutura: (1) Título + Resumo Executivo, (2) Contexto, (3) Linha do Tempo de Evidências/Metodologia — uma subseção por descoberta distinta com seu próprio bloco de evidência citada, geralmente a seção mais longa, (4) Seção de Desambiguação se o nome do assunto se sobrepõe a outra coisa, (5) Tabelas comparativas, (6) Contexto da indústria/externo, (7) Arquitetura/Síntese como uma lista numerada de ponta a ponta emparelhada com diagramas, (8) Perguntas em Aberto com acompanhamentos concretos, (9) Conexão com a investigação original, (10) Apêndice com evidências brutas completas aparadas do corpo. Quando um rascunho parecer pronto, mas curto, faça mais uma rodada real de investigação (outra verificação ao vivo, outro dump de registrador, outra pesquisa na web, outro diagrama, outra pesquisa de histórico para arte anterior) em vez de encher a prosa existente — a profundidade deve vir de conteúdo real, nunca de redimensionamento de fonte ou layouts de página vazia.

Notas do implementador

O agente deve ter typst instalado no PATH e acessível via typst compile. Execute typst --version uma vez por sessão para confirmar que está disponível.
Se usar fletcher, execute uma compilação de teste descartável (cd /tmp && typst compile test.typ com o import do fletcher) antes de integrar ao documento real — isso confirma que a resolução de pacotes da rede está funcionando.
Sempre mantenha o arquivo de armadilhas pessoal (~/notes/typst.md) — crie-o se não existir e anexe a ele toda vez que um novo tipo de erro de compilação for encontrado.
A verificação visual e de conteúdo são etapas separadas e obrigatórias — nunca pule a passagem de leitura de conteúdo apenas porque o documento compilou e parece bom.

ankitg12/agent-skills

O que é agent-skills?

Perguntar na sua IA favorita

Documentação