いつ使うか
詳細な技術文書（調査報告書、アーキテクチャ概要、根本原因分析ドキュメント、移行説明書）には、Word/.docxではなくTypstを使用します。対象となるドキュメントは以下の条件を満たします：
- 本格的な技術レポートのように読める：タイトルページ、エグゼクティブサマリー、番号付きセクション
- 印刷品質が優れている（LaTeXのような組版：
#set page、#set heading(numbering: "1.1")、両端揃えの本文） - 図表を含む（アーキテクチャ図やフロー図であり、単なる散文ではない）
- テーブルを含む（比較表、証拠表、ステータス表）
- ソースへのクリック可能なリンクを含む（チャットスレッド、GitHub PR、wikiページ）
- 一次ソースからの直接引用を、名前と日付を明記して含む（メッセージ、PR本文）
トリガーフレーズ：「これを書き起こして」「ドキュメントを作成して」「Typstにして」「これについてレポートを作成して」—特に、複数のソース（チャット検索、GitHub PRレビュー、ライブシステム証拠）を調査した後、共有可能な成果物に統合する必要がある場合に使用します。
コンパイルする前に、個人のTypst注意事項ファイル（例：~/notes/typst.md）を保持し、参照してください。既知の構文の落とし穴（脚注の配置、#Nの衝突、fletcherのインポート、テーブル列のサイズ設定など）を確認し、新しいコンパイルエラークラスを発見したら、そのファイルに追記してください。
重要な構文ルール（typst compile前の事前確認チェックリスト）：
- ボールドマークアップは単一の
*word*であり、決して**word**ではありません：Markdownの二重アスタリスクは、多数のコンパイラ警告を引き起こします（warning: no text within stars; using multiple consecutive stars has no additional effect）。 - 数式モードの文字列には引用符が必要です：
$ ... $内で、$Count=65$や$RTO$のような複数文字の識別子はコンパイルに失敗します（unknown variable）。$"Count"=65$と記述するか、コードをバッククォート（`Count=65`）で囲んでください。 - 数式内でLaTeXのバックスラッシュ演算子は使用禁止：
$\approx$と書くと失敗します（unknown variable: pprox）。Typstでは、バックスラッシュなしで裸の記号を使用します：$approx$。
コンテンツは深く、プレゼンテーションはリソース節約型に
すべてのレポートを形作る2つの常設指示：
- 本物の技術コンテンツを深く掘り下げる。 浅い要約ではなく、恐ろしいほど詳細な技術的深みを目指してください — より多くの生のコンソール出力、より多くのアーキテクチャ/ステートマシン図、ハードウェアに近いテーマではレジスタ/ビットフィールドまたはデジタル回路レベルの詳細、ソフトウェア実行に近いテーマではCPU命令/アセンブリレベルの詳細を含めます。草案が5〜6ページで「完成」したと感じたら、それは1層深く掘り下げる（追加の
redis-cli/systemctl/レジスタダンプ、追加のアーキテクチャ図、追加の業界比較の視点）合図であり、止まる合図ではありません。具体的なセクションごとの内訳については、以下の「深度の期待値」を参照してください。 - しかし、コンテンツではなく、プレゼンテーションに関してはリソース節約型であること。 コンテンツの深さとスタイリングのリソース節約は別の軸です — 事実/証拠/図表は深く掘り下げますが、視覚的なプレゼンテーション自体はインクを節約したものに保ちます：淡い色の背景 + 色付きの境界線/テキスト（ベタ塗りの色の代わりに）、および色は意味がある場合にのみ使用します（以下のカラースキームを参照）。インク節約はページ本文のインクを支配し、タイトルブロックは支配しません — タイトルはボックスで囲まれます（以下のカラースキーム項目1を参照）。目標は、より多くのページの本物の技術的実体であり、ページあたりのベタ塗りインクの増加ではありません。
ワークフロー
- まずすべての証拠を収集します（チャット検索、GitHub PRの読み取り、ライブコマンド出力、課題トラッカー/チャットの先行事例検索）— 調査中に
.typファイルの作成を開始せず、一度に統合します。 - 上記の構造テンプレート（シングルアクセントのボックス化されたタイトル、細い罫線付きのアクセント見出し、淡い色のテーブルヘッダー、意味に基づいて選択された2〜4箇所の重要な瞬間のセマンティックコールアウト、明るいコンソールブロック、ノードグラフ用の
#figureでラップされたfletcher図、デフォルトでは目次なし）を使用して、1回または2回のwrite/eval呼び出しで完全な.typソースを記述します。fletcherを使用する場合は、常にファイルの先頭に#import "@preview/fletcher:0.5.7": diagram, node, edgeを記述します — このインポートを省略することは、最も一般的な最初のコンパイルエラーの原因です。 - コンパイル：
typst compile file.typ（ファイルが存在する作業ディレクトリから実行 — セッションごとに一度typst --versionを確認してバイナリが利用可能であることを確認します。fletcherを使用する場合、破棄可能な/tmpテストコンパイルで、実際のドキュメントに組み込む前にネットワーク/パッケージ解決を確認します）。コンパイルエラーが発生した場合、ゼロからデバッグする前に、注意事項ファイルを確認してください。 - 完了と宣言する前に常に視覚的に確認する — すべてのページをPNGにレンダリングし（
typst compile --format png --ppi 100 file.typ "page-{p}.png"— 出力パターンを引用符で囲む）、各PNGをreadしてレイアウト/間隔/レンダリングを検査します。特に、図、テーブル、またはコールアウトを含むページ。3つ以上のエッジまたは双方向エッジペアがある図は、ラベルの衝突について特に注意深く検査する必要があります。 - 次に、別途コンテンツ確認パスを実行します — レイアウト確認はコンテンツ確認ではありません。 ステップ4は、何も間違ってレンダリングされていないことを証明するだけです。何かが正しいことを証明するものではありません。レンダリングされた各ページを再度
readし、今回はソースマテリアルに対して散文を読み、特に以下を探します：(a) 章が挿入されたときに古くなった手動で入力されたセクション相互参照（「§9.1.3参照」）；(b) ソースに対して主張が反転または転置されているテーブルセル；(c) 一次成果物からではなく、二次的な情報源から転記された数値 — これらに[INFERENCE]のマークを付けるか、検証します。実際に必要であることが確認されています：レイアウトパスに合格したドキュメントでも、ぶら下がった§参照と事実上反転したテーブルセルの両方が含まれており、どちらも読み取りによってのみ発見されました。1回のパスで記述された40 KBのドキュメントは、コンパイルされたからといって校正されたわけではありません。 - 最終的な
.typ+.pdfをプロジェクトのdocs場所（例：docs/generated/）に移動し、両方をコミットし、中間のPNG確認ファイルを削除します — ソースをコンパイル済み出力と一緒に保管することで、後で再編集可能になります。
セマンティックマークアップを使用する
Typst自身のアクセシビリティガイドに従って、プレーンテキスト/散文を手動でスタイリングしてその要素のように見せかける（例：#text(size: 16pt, weight: "bold")[Heading]）のではなく、常に実際のセマンティック要素（= Heading、#quote(...)、#table(...)）を使用してください。決して「見出しのように見える」という独自の慣習を発明しないでください。常に実際のマークアップ要素から外観を駆動してください。
カラースキーム
- 本文フォント：
New Computer Modern。 ベンチマークは「LaTeXのような」 — NCMはLaTeXの外観であり、Typstに同梱されているため、常に解決されます。マシンにインストールされていないフォントを絶対に選択しないでください（typst fontsで確認）：Typstは欠落したファミリーに対して警告を発するだけで、サイレントにフォールバックするため、ドキュメントは「クリーン」にコンパイルされますが、見た目は間違っています。unknown font familyの警告が表示された場合、それは許容する警告ではなく、修正すべき欠陥です。 - セマンティックコールアウトパレット。 緑
#1a7f37、黄#9a6700、赤#cf222e、青#0969da、紫#6639ba、オレンジ#bc4c00；コンソール/テーブルの色合いは#f2f6fb/#eaf1fb、境界線は#9fb8d6/#c8d6e8。インラインおよびブロックのrawは、マシンに存在する等幅フォント（例：Consolas、JetBrains Mono、Menlo）を使用する必要があります。
1つの構造用アクセントカラーを、クロームにのみ使用します — さらに、意味のためのセマンティックコールアウトブロックを使用します。 これが確定したパターンです；ゼロから再導出するのではなく、デフォルトでこれを適用してください：
- タイトルブロック：中央揃えの色付きテキストとボックス化された境界線。タイトルの周りに
#box(fill: white, stroke: 1.5pt + accent, ...)を使用します。 - テーブルヘッダー：淡い色合いの塗りつぶし + アクセントカラーのテキスト。決してベタ塗りの色の塗りつぶしは使用しません。
- 重要な発見のためのセマンティックコールアウトブロック — ここで追加の色が正当化されます。それは機能的であり、装飾的ではないからです。コンテンツに合うものを使用し、すべてをすべてのドキュメントに無理に含めないでください — レポートあたり合計2〜4個のコールアウトが適切な密度であり、段落ごとに1つではありません。
- 検証済み（緑のチェックマーク）— 確認済みの良い発見、1行。
- 異常（黄色の感嘆符）— 予期しないが、まだ欠陥として確認されていない。
- 確認済み欠陥（赤いX）— 確認済みの悪い発見、1行。
- 注記（青い情報）— 強調する価値のある重要な観察。
- ヒント（紫の電球）— 役立つ提案またはベストプラクティス。
- 未解決の質問（オレンジの疑問符）— 真に未解決の矛盾または問い合わせ。
- 印刷の読みやすさに役立つ場合、ドキュメント/セクションによって色合いを変えます。
- 図のボックスの色は、役割ベース/セマンティックのままにします。
- 大きなベタ塗りの暗い色の塗りつぶしはどこにも使用しません（例：白いテキストが入った全面濃紺のバナー）。セクション見出し：色付きのテキスト + 下部に細い色付きの罫線。塗りつぶされた色の帯やボックスは使用しません。
- コンソール/コード出力ブロック：淡い色の背景、グレーではありません。 フラットな
#f4f4f4グレーは、退屈/コピー機のように読み取られます。微妙なマッチング境界線を持つ淡い色合いを使用します。 - 章の間に
#pagebreak()を絶対に使用しないでください。 すべての=見出しの前に改ページを入れると、章ごとに半ページの白紙が残り、印刷時に実際のシートを無駄にします。セクションを流れさせてください；新しい章がページの途中から始まるのは正しいです。許容される唯一の#pagebreak()は、タイトルページを本文から分離する1つだけです。
2つのデフォルトセクション — プロンプトなしで含める
- 競合/業界コンテキスト。 代替案はこの問題をどのように解決しているか、そしてこのアーキテクチャ上の立場は構造的に何を得て、何を犠牲にしているか？各利点を、対応するテスト可能なリスクとしてフレーム化します。実際の競合文書からの情報でない限り、そのセクションを一般的な業界知識として
[INFERENCE]でラベル付けします。 - 自動化/テストハーネス、具体的に。 正確な呼び出し、ランナーホスト、venvと固定された依存関係、マーカー選択、および収集されたテスト数、選択解除されたテスト数、実行されたテスト数の読み方。「スイートがある」ことはカバレッジではありません。
図の配置：図/テーブルを#figure(...)でラップし、Typstにフロートさせる
Typst自身のレイアウトガイダンスによると、図はデフォルトでコンテンツフロー内のインライン配置になりますが、図またはテーブルを#figure(..., caption: [...])でラップすると、placement: top/placement: bottomのロックが解除され、Typstが段落の途中でコンテンツを不格好に分割するのではなく、ページの上部/下部にフロートできるようになります。図には常に実際のキャプション付きの#figure(...)ラッパーを付けてください（散文内で裸の#diagram(...)呼び出しをフロートさせないでください）—これにより、図が@sec-labelで相互参照可能になり、スクリーンリーダーや再利用ツールに適切なセマンティックな図+キャプションのペアリングが提供されます（ラベルのない画像だけではありません）。
ノード/エッジ図のためのFletcher
コンパイルとレンダリングが正しく行われることが確認された動作パターン（上記の配置ガイダンスに従って#figureでラップ）。インポートを忘れないでください（ワークフローステップ2を参照）— このスニペットはファイルの先頭に既にあることを前提としています：
#figure(
diagram(
node-stroke: 0.6pt,
spacing: (3em, 2em),
node((0,0), [Step 1], fill: rgb("#dbe9ff"), corner-radius: 4pt),
node((0,1), [Step 2], fill: rgb("#dbe9ff"), corner-radius: 4pt),
edge((0,0), (0,1), "-|>", bend: 10deg),
edge((0,1), (0,0), "-|>", bend: 10deg),
),
caption: [インラインラベルが省略されているため、両方の方向/エッジを説明する1行のキャプション。],
)
座標は(列、行)タプルです；node-stroke/fill/corner-radiusは個々のノードをスタイリングします；edge(from, to, "-|>")は矢印を描画します（マーク文字列は、キーワード引数ではなく、矢印の先端を選択します — "-|>"と"->"の両方が機能します；点線の矢印には"..|>"）。複数の独立したチェーンは、チェーンごとに異なる列インデックスと、チェーンごとにstroke: noneのヘッダー行ノードを使用して、1つのdiagram(...)呼び出しを共有できます。エッジラベルは短い1つの単語/フレーズに保ち、完全な説明は図のcaptionに移動します — 1語より長いインラインエッジラベルは、古典的なラベル衝突の失敗です。
深度の期待値：デフォルトで長文、オタク的に深く、要約ではない
特に短いものを明示的に要求されない限り、完全な調査書き起こしの場合は10〜12ページのレンダリングを目標にしてください — 短くて正しいが薄っぺらいレポートは、効率的な結果ではなく、失敗モードです。具体的には、「深く掘り下げる」とは、主題がそれをサポートする場合、以下を含めることを意味します：
- 完全な生のコンソール/ログ出力、切り詰められたスニペットではなく — 実際のコマンド + 実際の出力を、ライブシステムの証拠に基づくすべての主張に対して逐語的に。
- 少なくとも1つのアーキテクチャまたはステートマシン図（上記のfletcherを使用）、それがどのように接続されているかを示す散文だけでなく、実際に接続を示す。
- レジスタ/ビットフィールドまたはデジタル回路レベルの詳細、主題がハードウェアに近い場合（例：特定の設定レジスタのビットレイアウト、信号タイミング図、ASICブロックのポートマッピングテーブル、実際のドライバソースから取得した実際の構造体/オペコード定義）— 「ハードウェアはXを行う」で止まらず、実際のメカニズムを示す。
- CPU命令/アセンブリまたはシステムコールレベルの詳細、主題がソフトウェア実行に近い場合（例：ドライバが実際に発行するシステムコール、ホットパスの逆アセンブリがどのように見えるか）— 「ドライバはXを行う」で止まらず、実際のコードパスを示す。
- 専用の業界/外部コンテキストセクション（以下を参照）— 内部メカニズムを単独で提示しないでください。
- 真の先行事例/履歴検索 — 課題トラッカー、チャット履歴、git履歴をチェックして、この正確な質問が以前（何年も前であっても）行われたかどうかを確認します。何年も前の未解決の質問を閉じるレポートは、発見を真新しいものとして扱うレポートよりも強力な証拠です。
構造：(1) タイトル + エグゼクティブサマリー、(2) 背景、(3) 証拠のタイムライン/方法論 — 個別の発見ごとに1つのサブセクションと独自の引用証拠ブロック、通常は最長のセクション、(4) 主題の名前が他のものと重複する場合の曖昧性解消セクション、(5) 比較表、(6) 業界/外部コンテキスト、(7) 図と組み合わせた番号付きのエンドツーエンドリストとしてのアーキテクチャ/統合、(8) 具体的なフォローアップを含む未解決の質問、(9) 元の調査への結びつき、(10) 本文から削除された完全な生の証拠を含む付録。草案が完成したが短いと感じたら、既存の散文を水増しするのではなく、もう1回実際の調査ラウンド（別のライブチェック、別のレジスタダンプ、別のウェブ検索、別の図、別の先行事例の履歴検索）を実行します — 深さは実際のコンテンツから得られなければならず、決して追記からではありません。