Quand l'utiliser

Utilisez Typst plutôt que Word/.docx pour tout compte rendu technique détaillé — rapports d'investigation, résumés d'architecture, documents d'analyse de causes racines, explications de migration. Visez les documents qui :

Se lisent comme un vrai rapport technique : page de titre, résumé exécutif, sections numérotées
Rendent bien à l'impression (composition LaTeX-like : #set page, #set heading(numbering: "1.1"), texte justifié)
Incluent des diagrammes (diagrammes d'architecture/de flux, pas seulement du texte)
Incluent des tableaux (tableaux comparatifs, tableaux de preuves, tableaux de statut)
Incluent des liens cliquables vers les sources (fils de discussion, PR GitHub, pages wiki)
Citent les sources primaires avec des citations directes (messages, corps de PR) attribuées par nom/date

Phrases déclencheurs : "rédige ça", "crée un doc", "typst-le", "fais un rapport sur ça" — surtout après une investigation multi-sources (recherche de conversation, revue de PR GitHub, preuves système en direct) qui nécessite une synthèse en un artefact partageable.

Avant de compiler, gardez et consultez un fichier d'astuces Typst personnel (par exemple ~/notes/typst.md) pour les pièges syntaxiques connus (placement des notes de bas de page, collisions #N, import fletcher, dimensionnement des colonnes de tableau, etc.) — et ajoutez-y chaque fois qu'une nouvelle classe d'erreur de compilation est découverte.

Règles syntaxiques critiques (Liste de vérification avant typst compile) :

Le gras se fait avec un seul *mot*, JAMAIS **mot** : les doubles astérisques Markdown émettent des dizaines d'avertissements du compilateur (warning: no text within stars; using multiple consecutive stars has no additional effect).
Les chaînes en mode math nécessitent des guillemets : Dans $ ... $ , les identifiants multi-lettres comme $Count=65$ ou $RTO$ échouent à la compilation (unknown variable). Écrivez $"Count"=65$ ou placez le code entre guillemets inversés (`Count=65`).
Pas d'opérateurs LaTeX avec backslash en mode math : Écrire $\approx$ échoue (unknown variable: pprox). Typst utilise des symboles nus : $approx$ sans backslash.

Allez en profondeur sur le contenu ; soyez économe en ressources pour la présentation

Deux directives permanentes qui façonnent chaque rapport :

Allez en profondeur sur le contenu technique authentique. Visez une profondeur technique exhaustive, pas un résumé superficiel — plus de sortie console brute, plus de diagrammes d'architecture/machines d'état, des détails de registres/champs de bits ou de circuits numériques quand le sujet est proche du matériel, des détails au niveau des instructions CPU/assembleur quand le sujet est proche de l'exécution logicielle. Quand un brouillon semble "fini" en 5-6 pages, c'est un signal pour creuser une couche plus profondément (un vidage redis-cli/systemctl/register supplémentaire, un diagramme d'architecture supplémentaire, un angle de comparaison sectorielle supplémentaire), pas pour s'arrêter. Voir "Attente de profondeur" ci-dessous pour la décomposition concrète section par section.
Mais soyez économe en ressources pour la présentation, pas pour le contenu. La profondeur du contenu et l'économie de ressources du style sont des axes séparés — allez en profondeur sur les faits/preuves/diagrammes, mais gardez la présentation visuelle elle-même légère en encre : arrière-plans teintés clairs + bordures/texte colorés au lieu de remplissages de couleur unie, et couleur utilisée uniquement là où elle a du sens (voir Schéma de couleurs ci-dessous). L'encre légère gouverne l'encre du corps de la page, PAS le bloc de titre — le titre EST encadré (voir Schéma de couleurs point 1). Plus de pages de substance technique réelle est l'objectif ; plus d'encre de couleur unie par page ne l'est pas.

Flux de travail

Rassemblez TOUTES les preuves d'abord (recherches de conversation, lectures de PR GitHub, sorties de commandes en direct, recherche d'antécédents dans le traqueur de tickets/chat) avant d'écrire — ne commencez pas le fichier .typ en cours de recherche ; synthétisez une fois.
Écrivez le code source complet .typ en un ou deux appels write/eval, en utilisant le modèle de structure ci-dessus (titre encadré avec un accent, titres de section accentués avec une règle fine, en-têtes de tableau teintés clairs, encadrés sémantiques à 2-4 moments clés choisis par sens et non par nouveauté, blocs de console clairs, diagrammes fletcher enveloppés dans #figure pour les graphes de nœuds, pas de table des matières par défaut). Si vous utilisez fletcher, commencez TOUJOURS le fichier par #import "@preview/fletcher:0.5.7": diagram, node, edge — omettre cette importation est l'erreur de première compilation la plus courante.
Compilez : typst compile fichier.typ (depuis un répertoire de travail où se trouve le fichier — vérifiez typst --version une fois par session pour confirmer que le binaire est disponible ; si vous utilisez fletcher, une compilation de test dans /tmp confirme la résolution réseau/package avant de l'intégrer dans le vrai document). Vous rencontrez une erreur de compilation ? Consultez votre fichier d'astuces avant de déboguer à partir de zéro.
Vérifiez toujours visuellement avant de déclarer terminé — générez chaque page en PNG (typst compile --format png --ppi 100 fichier.typ "page-{p}.png" — mettez le motif de sortie entre guillemets) et read chaque PNG pour inspecter la mise en page/l'espacement/le rendu, en particulier toute page contenant un diagramme, un tableau ou un encadré. Les diagrammes avec 3+ arêtes ou paires d'arêtes bidirectionnelles nécessitent une attention particulière pour les collisions d'étiquettes.
Ensuite, faites une passe de lecture du CONTENU séparée — la vérification de la mise en page n'est pas une vérification du contenu. L'étape 4 prouve que rien ne s'affiche mal ; elle ne prouve PAS que quoi que ce soit est vrai. read chaque page rendue à nouveau, cette fois en lisant le texte par rapport au matériau source, et cherchez spécifiquement : (a) les références croisées de sections tapées à la main ("voir §9.1.3") qui sont devenues obsolètes lorsqu'un chapitre a été inséré ; (b) les cellules de tableau dont l'affirmation est inversée ou transposée par rapport à la source ; (c) les nombres qui ont été retranscrits de seconde main plutôt qu'à partir de l'artefact primaire — marquez-les comme [INFERENCE] ou allez les vérifier. Confirmé nécessaire en pratique : un document qui a passé la passe de mise en page complète contenait encore une référence § pendante ET une cellule de tableau factuellement inversée, tous deux détectés uniquement en lisant. Un document de 40 Ko écrit en une seule passe n'a PAS été relu simplement parce qu'il a compilé.
Déplacez les fichiers .typ + .pdf finaux dans l'emplacement docs du projet (par exemple docs/generated/) et engagez les deux, puis supprimez tous les fichiers de vérification PNG intermédiaires — gardez le source à côté de la sortie compilée afin qu'il soit rééditable plus tard.

Utilisez un balisage sémantique

Conformément au propre guide d'accessibilité de Typst : utilisez toujours l'élément sémantique réel (= Titre, #quote(...), #table(...)) plutôt que de styliser manuellement du texte/prose simple pour ressembler à cet élément (par exemple #text(size: 16pt, weight: "bold")[Titre]). N'inventez jamais une convention parallèle "qui ressemble à un titre" ; dérivez toujours l'apparence de l'élément de balisage réel.

Schéma de couleurs

Police du corps : New Computer Modern. La référence est "comme LaTeX" — NCM a le look LaTeX et est livré avec Typst, donc il se résout toujours. NE choisissez JAMAIS une police qui n'est pas installée sur la machine (vérifiez avec typst fonts) : Typst ne fait que prévenir en cas de famille manquante et se rabat silencieusement, donc le doc compile "propre" tout en ayant un mauvais aspect. Si un avertissement unknown font family apparaît, c'est un défaut à corriger, pas un avertissement à tolérer.
Palette d'encadrés sémantiques. vert #1a7f37, jaune #9a6700, rouge #cf222e, bleu #0969da, violet #6639ba, orange #bc4c00 ; teintes console/tableau #f2f6fb / #eaf1fb avec bordure #9fb8d6 / #c8d6e8. Le raw en ligne et en bloc doit utiliser une famille mono-espace qui existe sur la machine (par exemple Consolas, JetBrains Mono, Menlo).

Une couleur d'accent structurelle, utilisée uniquement pour le chrome — plus des blocs d'encadrés sémantiques pour le sens. C'est le modèle établi ; appliquez-le par défaut sans le redériver à partir de zéro :

Bloc de titre : texte coloré centré simple avec cadre bordé. Utilisez #box(fill: white, stroke: 1.5pt + accent, ...) autour du titre.
En-têtes de tableau : fond teinté clair + texte de couleur d'accent, JAMAIS un remplissage de couleur unie.
Blocs d'encadrés sémantiques pour les constatations significatives — c'est là que la couleur supplémentaire est méritée, car elle est fonctionnelle, pas décorative. Utilisez ceux qui correspondent au contenu ; ne les forcez pas tous dans chaque document — 2-4 encadrés au total par rapport est une bonne densité, pas un par paragraphe.
- Vérifié (coche verte) — constatation confirmée bonne, une ligne.
- Anomalie (point d'exclamation jaune) — inattendu mais pas encore confirmé comme un défaut.
- Défaut confirmé (X rouge) — constatation confirmée mauvaise, une ligne.
- Note (info bleue) — une observation non critique qui mérite d'être soulignée.
- Astuce (ampoule violette) — une suggestion utile ou une bonne pratique.
- Question ouverte (point d'interrogation orange) — un écart ou une interrogation authentique non résolu(e).
Variez la teinte par document/section là où elle améliore la lisibilité à l'impression.
Les couleurs des cadres des diagrammes restent basées sur le rôle/sémantiques.
Pas de grands remplissages de couleur sombre unie nulle part (par exemple une bannière bleu foncé avec du texte blanc). En-têtes de section : texte coloré + une fine règle colorée en dessous, pas une bande ou un bloc de couleur rempli.
Blocs de sortie console/code : fond teinté clair, pas gris. Un gris uni #f4f4f4 se lit comme terne/photocopieuse. Utilisez une teinte claire avec une bordure subtile assortie.
N'utilisez JAMAIS #pagebreak() entre les chapitres. Un saut avant chaque titre = laisse une demi-page de papier vierge par chapitre et gaspille de vraies feuilles lors de l'impression. Laissez les sections s'enchaîner ; un nouveau chapitre commençant en milieu de page est CORRECT. Le seul #pagebreak() acceptable est celui qui sépare la page de titre du corps.

Deux sections par défaut — incluez-les sans y être invité

Contexte concurrentiel / sectoriel. Comment les alternatives résolvent-elles ce problème, et qu'est-ce que cette position architecturale achète et coûte structurellement ? Cadrez chaque avantage comme un risque testable correspondant. Étiquetez la section comme connaissance sectorielle générale avec [INFERENCE] à moins qu'elle ne provienne d'un véritable document concurrentiel.
Le harnais d'automatisation / de test, concrètement. Invocation exacte, hôte d'exécution, venv et dépendances épinglées, sélection de marqueurs, et comment lire les comptes collectés vs désélectionnés vs exécutés. "Il y a une suite" n'est pas une couverture.

Placement des figures : enveloppez les diagrammes/tableaux dans `#figure(...)`, laissez Typst les faire flotter

Conformément aux propres directives de mise en page de Typst, les figures sont par défaut placées en ligne dans le flux de contenu, mais envelopper un diagramme ou un tableau dans #figure(..., caption: [...]) déverrouille placement: top/placement: bottom pour laisser Typst le faire flotter en haut/en bas de la page plutôt que de diviser maladroitement le contenu autour de lui au milieu d'un paragraphe. Donnez toujours aux diagrammes une enveloppe #figure(...) avec une légende réelle (jamais un appel #diagram(...) nu flottant dans le texte) — c'est aussi ce qui rend le diagramme référençable via @sec-label et donne aux lecteurs d'écran/outils de repurposing un véritable appariement figure+légende sémantique, pas seulement une image non étiquetée.

Fletcher pour les diagrammes nœuds/arêtes

Motif de travail, confirmé compilant et s'affichant correctement (enveloppé dans #figure conformément aux directives de placement ci-dessus). Rappelez-vous l'importation (voir l'étape 2 du Flux de travail) — cet extrait suppose qu'elle est déjà en haut du fichier :

#figure(
  diagram(
    node-stroke: 0.6pt,
    spacing: (3em, 2em),
    node((0,0), [Étape 1], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    node((0,1), [Étape 2], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    edge((0,0), (0,1), "-|>", bend: 10deg),
    edge((0,1), (0,0), "-|>", bend: 10deg),
  ),
  caption: [Légende d'une ligne expliquant les deux directions/arêtes car les étiquettes en ligne sont omises ici.],
)

Les coordonnées sont des tuples (colonne, ligne) ; node-stroke/fill/corner-radius stylisent les nœuds individuels ; edge(from, to, "-|>") dessine une flèche (la chaîne de marque, pas un argument mot-clé, sélectionne la tête de flèche — "-|>" et "->" fonctionnent tous deux ; "..|>" pour une flèche pointillée). Plusieurs chaînes indépendantes peuvent partager un seul appel diagram(...) en utilisant différents indices de colonne par chaîne plus un nœud de ligne d'en-tête avec stroke: none par chaîne. Gardez les étiquettes des arêtes à un mot/une phrase court(e) et déplacez l'explication complète dans la caption de la figure — les étiquettes d'arête en ligne plus longues qu'un mot sont l'échec classique de collision d'étiquettes.

Attente de profondeur : par défaut, optez pour une forme longue, pointue comme un nerdy, pas un résumé

Sauf demande explicite de quelque chose de court, visez 10-12 pages rendues pour un rapport d'investigation complet — un rapport court, correct mais superficiel est un mode d'échec, pas un résultat efficace. Concrètement, "aller en profondeur" signifie inclure, partout où le sujet le permet :

Sortie console/log brute complète, pas des extraits tronqués — commande réelle + sortie réelle, textuellement, pour chaque affirmation provenant de preuves système en direct.
Au moins un diagramme d'architecture ou de machine d'état (via fletcher, voir ci-dessus) montrant comment les pièces se connectent réellement, pas seulement du texte le décrivant.
Détails au niveau du registre/champ de bits ou du circuit numérique quand le sujet est proche du matériel (par exemple la disposition des bits d'un registre de configuration spécifique, un diagramme de chronométrage de signal, une table de mappage de ports d'un bloc ASIC, des définitions réelles de struct/opcode tirées du code source réel du pilote) — ne vous arrêtez pas à "le matériel fait X", montrez le mécanisme réel.
Détails au niveau de l'instruction CPU/assembleur ou de l'appel système quand le sujet est proche de l'exécution logicielle (par exemple quel appel système un pilote émet réellement, à quoi ressemble le désassemblage du chemin chaud) — ne vous arrêtez pas à "le pilote fait X", montrez le chemin de code réel.
Une section Contexte sectoriel/externe dédiée (voir ci-dessous) — ne présentez jamais un mécanisme interne isolément.
Recherche authentique d'antécédents/historique — vérifiez le traqueur de tickets, l'historique des conversations et l'historique git pour savoir si cette question exacte a été posée auparavant (même des années plus tôt) ; un rapport qui clôt une question ouverte vieille de plusieurs années est une preuve plus solide qu'un rapport qui traite une constatation comme toute nouvelle.

Structure : (1) Titre + Résumé exécutif, (2) Contexte, (3) Chronologie des preuves/Méthodologie — une sous-section par constatation distincte avec son propre bloc de preuves cité, généralement la section la plus longue, (4) Section de désambiguïsation si le nom du sujet chevauche autre chose, (5) Tableaux comparatifs, (6) Contexte sectoriel/externe, (7) Architecture/Synthèse sous forme de liste numérotée de bout en bout associée à des diagrammes, (8) Questions ouvertes avec des suivis concrets, (9) Lien avec l'investigation d'origine, (10) Annexe avec les preuves brutes complètes retirées du corps. Quand un brouillon semble fini mais court, faites un vrai tour d'investigation supplémentaire (une autre vérification en direct, un autre vidage de registre, une autre recherche Web, un autre diagramme, une autre recherche historique d'antécédents) plutôt que de gonfler le texte existant — la profondeur doit venir du contenu réel, jamais de la réécriture...

ankitg12/agent-skills

Qu'est-ce que agent-skills ?

Demander à votre IA préférée

Documentation