PJR-2ZMY 文書の編集ツール（図・プレゼン・表）の方針を決める

1. 背景

人との連携を重視し、図・プレゼン・表をどのツールと形式で書くかを決める。local の編集環境の検討レポート（2026-10-17）は draw.io・Slidev・CSV を推奨するが、agent が書いて直す運用との相性もあるため、継続して検討する

参考にした資料は、本リポジトリの local/specdojo_coderdojo_editing_environment_report_2026-10-17.md（SpecDojo と coderdojo-lessons の標準編集環境の検討レポート、推奨アーキテクチャ案）である。レポートの推奨は次のとおり。

成果物	レポートの推奨
文書	Markdown を正本にし、VitePress で公開
プレゼン	Slidev（Markdown でスライド）
図	draw.io（.drawio.svg）を標準、Mermaid は単純な図に併用
長いセルの一覧表	CSV ＋ Edit CSV ＋ Vue で表示（試験導入）
計算付きの表	CSV ＋ 数式 YAML（未実装の設計案）

2026-10-22〜23 に確かめた事実は次のとおり。

• Mermaid は 12 から ELK のレイアウトが同梱されて既定になったが、本リポジトリの packages/docs-site/mermaid-config.json は dagre を明示している。辺 35 本の cdfd-overview を描き比べると、ELK は直角の配線で流れが読めるようになるが、密さは残る。
• ノードの先頭の絵文字が、描画の環境に絵文字のフォントがないため文字化けしている。
• 中心の図形に周りから矢印を集める図は、architecture 図なら辺ごとに出入りする面を指定して描ける。block 図は格子に並ぶが図形が詰まる。elk.stress は図形が重なって使えない。
• draw.io は、圧縮しない .drawio を正本にし、SVG をビルドで書き出せば、git の差分を図形の行単位に抑えられる（.drawio.svg は XML が 1 行の属性に埋め込まれ、差分が大きい）。書き出しには draw.io のデスクトップ版の CLI が要る。
• SpecDojo は、構造のあるデータを schema 付きの YAML に持ち、表は生成したビューで見せる形が定着している。

2. 検討した選択肢

2.1. 図

選択肢	内容	利点	懸念
A	Mermaid を標準とし、ELK に切り替える。draw.io は人が配置を決めたい図に限り、.drawio を正本、SVG はビルドで書き出す	agent が書いて直せる。GitHub でそのまま表示される。人が描く図も使える	人が GUI で描く図が例外扱いになる。draw.io の書き出しの仕組みが要る
B	レポートどおり draw.io を標準とし、Mermaid は単純な図に限る	人が GUI で配置を自由に決められる	agent が座標を含む XML を直すのは難しく、差分も大きくなりやすい
C	D2 など別の図の言語に移る	ELK や TALA など配置の選択肢が多い	GitHub で表示されない。ツールが増える
D	図の複雑さで使い分ける。単純な図や状態遷移図など Mermaid が得意な図は Mermaid、複雑な図は D2、さらに複雑で人が配置を変えたい図は draw.io（2026-10-31 の利用者の提案）	図ごとに描きやすい道具を選べる。D2 と Mermaid は agent が書いて直せる	道具が 3 つになり、どれを使うかの基準と、D2・draw.io の SVG の書き出しの仕組みが要る

案 D を採る場合に決めることと前提は次のとおりである。D2 の表示と配置のエンジンの料金の扱いは、採る前に一次情報で確かめる。

• 使い分けの基準を、図の種類と規模で書けるようにする。例: Mermaid は flowchart・sequence・state・class・ER・architecture で、ノードと辺がおおむね 20 程度まで。D2 はそれを超える構成図や、入れ子の多い図。draw.io は人が配置を決めたい図（発表用の図など）に限る。
• D2 は GitHub では表示されないため、VitePress のビルドで SVG に書き出す必要がある。書き出しには d2 の CLI（単体のバイナリ）を Dev Container と CI に入れる。配置のエンジンは dagre と ELK が無料で、TALA は有料のため使わない前提とする。
• draw.io は 2.1. の案 A と同じく、圧縮しない .drawio を正本にし、SVG をビルドで書き出す。書き出しには draw.io のデスクトップ版の CLI が要る。
• agent への指示（どの図をどの道具で描くか）を、rulebook か書き方の文書に書く。

2.2. プレゼン

選択肢	内容	利点	懸念
A	Slidev を資料用の場所（例: specdojo-assets）で使い、本体のリポジトリには入れない	Markdown でスライドを管理でき、Mermaid も描ける。本体の依存が増えない	Node の実行環境が要る
B	本体のリポジトリに Slidev を入れる	文書とスライドを同じ場所で扱える	本体の依存とビルドが増える

2.3. 表

選択肢	内容	利点	懸念
A	Markdown の表と、schema 付きの YAML ＋ 生成ビューを続ける	agent が直しやすく、schema で検査できる	人が GUI で表を編集しにくい
B	レポートどおり、長いセルの一覧表を CSV ＋ Edit CSV にする	人が GUI で編集しやすい	正本の形が YAML と CSV の 2 つになる。表示に Vue の部品の実装が要る

3. 決定内容

継続して検討する（2026-10-23、利用者の判断）。SpecDojo は人との連携を重視するため、人が GUI で編集する図や表をどこまで標準に入れるかを、急いで決めない。

この決定とは別に、次は進める（いずれのツールの方針でも Mermaid は使い続けるため）。

• Mermaid の既定のレイアウトを ELK に切り替え、絵文字の文字化けを直す（PJR-QF45）。
• Slidev は、既定では入れず、Dev Container の preset の full か init --slidev を選んだときだけ入れる形で、利用者の project の要望（PJR-84F7）に応えた（2026-10-25、利用者が承認）。プレゼンの方針そのものは、この決定で引き続き検討する。
• 中心に集める図を architecture 図で描くなど、Mermaid の図の種類の使い分けを確かめて、書き方の文書に書く（PJR-QF45）。

4. 採択理由

• TODO: 判断根拠を記載する。

5. 承認

項目	内容
決定者	TODO
決定日	TODO
承認方式	TODO
証跡	TODO

• 承認方式は commit または PR を記載する。PR の場合は証跡に PR URL と merge SHA を本文テキストで記載する。
• 不可逆・高リスク・framework schema 破壊的変更に該当する決定は PR 方式で承認する。

6. 影響範囲とフォローアップ

項目	内容
影響範囲	TODO
必要な対応	TODO
追跡先	PJR-QF45（Mermaid の ELK への切り替え）

7. 関連ドキュメント

• TODO: 根拠・影響先・追跡先を [[doc-id]] 形式で記載する。