visimark

VisiMark

Markdown の文書完全性レイヤーです。文書内のすべての数値が、それを生成した数式と一致しているかをチェックするため、エージェントが正しい数式を書いても、誤った合計値を出荷してしまうことはありません。

VisiMark は、Markdown 文書内の数値をチェックします。特に、エージェントが作成した文書に効果を発揮します。計算値にはそれぞれ数式が付随し、機械が両者の一致を証明します。一致しない場合は CI が失敗します。文書は通常の Markdown のままです。

これは、Markdown を AI エージェントが作成または編集する場合に最も重要です。 エージェントは数式を書くのは得意ですが、その数式が表す算術計算は苦手です。Net = Price * Qty は正しく書けても、50.00 は推測にすぎません。数値の代わりに数式を書けば、その数値は主張ではなく導出値になります。差分でレビューでき、再実行でき、CI で強制できます。エージェントが書き、VisiMark が検証し、Git が結果を記録します。

VisiMark の文書は通常の Markdown ファイルです。現在、GitHub、VS Code のプレビュー、pandoc を介した HTML と Word のどれでも、プラグインなしで正しく表示されます。これは想定ではなく、検証済みです。VisiMark が追加するのは、文書内のすべての計算値に、それを生成した数式が付随すること、機械が両者の一致を証明できること、そしてどちらかへの変更が小さく読みやすい差分として表示されることです。

対象ユーザー

現在、6 種類のユーザー層があり、それぞれに具体的な利用の入り口があります。意図的に短くしています。実際のユーザーがついたものから拡充し、それまでは増やしません。

• エージェントとレビュアー — モデルが作成したばかりの文書を検証する方には、MCP サーバーとエージェントスキルがあります。
• アナリスト、創業者、キャパシティプランナー — 別のタブを開いたりファイルのコピーを作成したりせずに、what-if 分析を行いたい方には、eval --scenario があります。従業員数モデルでの使い方は、docs/tutorial/runway.mdで解説しています。
• すでに Markdown のリンターを使っている方 — pre-commit フック、remark-lint-visimark、markdownlint-rule-visimark、複合型のGitHub Actionがあります。
• エンジニア、科学者、単位を扱う方 — 名前の後に角括弧で単位を宣言します。たとえば、Rate [PLN] や speed [m/s] = Distance / Duration と書くと、check は kg + m を拒否し、km/h を導出します（実行しないことを参照）。
• 数値を含む保管庫を持つ Obsidian ユーザー — Obsidian プラグインを使うと、閲覧モードとライブプレビューで、すべての計算値がマークされます。
• 金融関係者 — NPV、IRR、PMT と、これらを使う際に宣言が必要となる小数精度については、ローンと投資評価で解説しています。

正しく表示される誤った請求書

docs/example-invoice-drift.mdは、誰かがオンコールの作業時間を 12 時間から 20 時間に増やした後、それに依存する値を何も更新しなかった実際の B2B 請求書です。GitHub や Markdown プレビューなど、どこで見ても、きれいで一見もっともらしい請求書として表示されます。これこそが、このプロジェクトの存在意義です。請求書内のすべての数値には、それを生成した数式が付随します。構文については後ほど説明します。以下は、レビュアーがざっと目を通して承認したばかりの同じファイルを、visimark check で読み取った結果です。

$ visimark check docs/example-invoice-drift.md
docs/example-invoice-drift.md

  STALE   lines.Net       · On-call support         3120.00 ≠ 5200.00    Qty * Rate
  STALE   lines.VAT       · On-call support          717.60 ≠ 1196.00    Net * vat
  STALE   lines.Gross     · On-call support         3837.60 ≠ 6396.00    Net + VAT
  STALE   lines.Gross     · Discovery workshop      4428.50 ≠ 4428.00    Net + VAT
  STALE   lines.net_total                          23300.00 ≠ 25380.00   SUM(Net)
  STALE   lines.vat_total                           5359.00 ≠ 5837.40    SUM(VAT)
  STALE   lines.gross_total                        28659.00 ≠ 31217.40   SUM(Gross)
  STALE   lines.gross_total                        28659.00 ≠ 31217.40   SUM(Gross)
  STALE   schedule.Amount · Signature               8597.70 ≠ 9365.22    Share * lines.gross_total
  STALE   schedule.Amount · Delivery of backend    11463.60 ≠ 12486.96   Share * lines.gross_total
  STALE   schedule.Amount · Acceptance              8597.70 ≠ 9365.22    Share * lines.gross_total
  STALE   schedule.covered                         28659.00 ≠ 31217.40   SUM(Amount)
  STALE   terms.early_pay_total                    28085.82 ≠ 30593.05
  STALE   terms.early_pay_saved                      573.18 ≠ 624.35
  STALE   8 prose anchors bound to the values above

  DATE    schedule.Due    · Delivery of backend   "15.10.2026"
          Dates must be ISO 8601 calendar dates: YYYY-MM-DD.
          Unambiguous — `visimark fmt --fix-dates` rewrites it to 2026-10-15.

  DATE    schedule.Due    · Acceptance            "11/12/2026"
          Dates must be ISO 8601 calendar dates: YYYY-MM-DD.
          Ambiguous: 2026-12-11 or 2026-11-12, 29 days apart. Fix by hand.

  NOTE    schedule.Days   · 2 rows not verified (upstream DATE errors)

  UNDEF   terms.eur_total   unknown name `fx_rate`
          did you mean `fx_eur`?

  VECTOR  recon.variance    `schedule.Amount` is a column, not a value.
          Wrap it in an aggregate: SUM(schedule.Amount)

  CYCLE   late_fees.base → late_fees.fee → late_fees.total → late_fees.base

  27 problems (22 stale, 5 errors)
$ echo $?
1

問題は 27 件です。支払日が 29 日ずれて曖昧になっていること、列を正しく見せるために誰かが手動で調整したセル、循環参照など、すべてがレンダリングされたページ上では見えませんが、人が気づく前にすべて検出されます。

今これが重要な理由

数値を含む文書の多くがテキストで書かれ、Git で管理されるようになっています。レポートや調査メモ、見積書や予算書、価格提示書や請求書、プロジェクト計画書、財務サマリーなどです。テキストは共同作業、レビュー、バージョン管理に適しています。しかし、通常の Markdown には、この数値はこれらの入力値から導かれ、入力値と常に一致していなければならないと示す方法がありません。そのため、入力値が変わると、その値を使った後続の数値はすべて、人が手作業で再確認するまで推測にすぎなくなります。

VisiMark は、この欠けていた層を追加します。エージェントと共同作業するための基本的な構成は、軽く書式設定された成果物をテキストエディターで扱うことです。Markdown が文章を担い、VisiMark が計算を担います。価値があるのは算術そのものではなく、監査証跡です。

どのようなものか

| Item  | Price | Qty |   Net |
|-------|------:|----:|------:|
| pen   |  5.00 |  10 | 50.00 |
| paper |  0.10 | 100 | 10.00 |

```vmark #order
Net   = Price * Qty
total = SUM(Net)
```

Order total: **60.00**

アイデアは4つだけで、それがフォーマットのすべてです。

• vmark ブロックで、その上にある表の数式を宣言し、シート名を指定します。
• 列のルールは列全体に適用されます。Net = Price * Qty は、セルごとの数式ではなく、すべての行に適用される1つのルールです。ルールのない列は入力値として扱われ、上書きされることはありません。
• 集計値はスカラーとして、横に並べて宣言します。これによって合計行を置き換え、表を長方形のまま保ちます。
• アンカーを使うと、スカラーを文中に展開できます。HTML コメントはどのレンダラーでも表示されないため、文章は自然に読めるまま、数値は機械で検証可能です。

チュートリアル

docs/tutorial.mdは、エンドツーエンドのチュートリアルです。通常の Markdown の表から、検証済みの文書、CI ジョブ、値を読み取るスクリプトまでを、28の短い章で解説します。言語を依存関係の順に学べるほか、check が報告できるすべての指摘事項と、チェックを緑のまま意味あるものにするための習慣を説明しています。チュートリアル内のトランスクリプトはすべて実際のものです。

docs/tutorial.htmlには、チュートリアルを左右に並べて読めるページがあります。各ブロックの Markdown ソースとレンダリング結果を、対応させて表示します。

使用例

docs/example-invoice.mdは、計算が自動で行われるB2B請求書の完全な例です。明細項目、VAT、税込合計から導出される支払いスケジュール、早期支払い条件、通貨換算、分割払いの合計が請求額と一致することを証明する照合が含まれています。付録では各仕組みについて説明します。

docs/example-invoice-drift.mdは、請求書の数値がこの README の冒頭に示したようにずれた例です。上記の 27 problems トランスクリプトは、check がまさにこのファイルを読み込んだ結果で、付録では27件すべての問題について説明しています。

docs/example-quote-plain.mdは逆の方向を示す例です。VisiMark が一切含まれていない見積書で、vmark ブロックもアンカーもなく、表と文章で書かれた合計だけがあります。エージェントが、誰も設定していない段階で渡す見積書のようなものです。visimark infer はこの文書を読み込み、そこにあるすべての数値を再現するルールを提案します。

$ visimark infer docs/example-quote-plain.md
docs/example-quote-plain.md  table at line 10 — 4 rows, 7 columns

  column rules
    Revenue    = Seats * Fee                  4/4 rows
    Materials  = Revenue * 0.08               4/4 rows
    Delivered  = Revenue + Materials          4/4 rows

  constants worth naming
    0.08   also appears as "8%" in prose, line 18

  scalars matching figures in prose
    72        line 17  = SUM(Seats)                seats_total
    27600.00  line 18  = SUM(Revenue)              revenue_total
    2208.00   line 19  = SUM(Materials)            materials_total
    29808.00  line 19  = SUM(Delivered)            delivered_total
    530.00    line 20  = AVG(Fee)                  fee_avg

  no rule found — treating as inputs
    Module, Format, Seats, Fee

  also fits, not proposed
    Delivered = Revenue * 1.08    prefers a rule over materialised columns
    Delivered = Materials * 13.5  prefers a rule over materialised columns

docs/example-quote-plain.md  table at line 24 — 3 rows, 4 columns

  column rules
    Amount  = Share * unnamed1.delivered_total  3/3 rows

  scalars matching figures in prose
    29808.00  line 30  = SUM(Amount)               amount_total

  no rule found — treating as inputs
    Stage, Share, Due

  also fits, not proposed
    Amount = Share * 29808    prefers a rule over materialised columns

4 rules, 0 aliases, 6 scalars, 6 anchors.

ルールが提案されるのは、対象の列自身の精度で、すべての行を正確に再現できる場合に限られます。最適近似も閾値による判定もありません。また、also fits, not proposed に該当するルールも黙って除外せず、一覧に示されます。実体化された列を使うルールが、単純な定数を使うルールよりも適合する場合、それを採用するかどうかは確認する価値のある判断だからです。--write は、上記のブロックとアンカーだけを正確に挿入し、それ以外は書き換えません。すべての行に適合しても、1行だけ合わないルールは決して書き込まれません。代わりにニアミスとして報告されます。これは、誰かが文書に対して check を実行する前に、文書内にすでに間違った数値があることをツールが知らせるものです。文書の付録では、このニアミスのケースも含め、すべての仕組みについて説明しています。

infer は、数式がまったくなく、そのままでは check が何も指摘できない文書を扱うための入口です。この2つを組み合わせることで一連の流れが完成します。infer で通常の表を設定し、check でその状態を維持します。

仕組み

VisiMark はドキュメントを解析し、すべてのシートにまたがる依存関係グラフを構築して、トポロジカル順に並べ替え、10 進演算で評価します。循環依存がある場合は、循環をたどる完全なパスを報告します。

flowchart LR
  parse[Parse Markdown] --> deps[Build dependency graph]
  deps --> sort[Topological sort]
  sort --> evaluate[Evaluate in decimal]
  evaluate --> cycle{"Cycle?"}
  cycle -->|yes| report[Report the CYCLE path]
  cycle -->|no| values[Computed values]

CLI が製品です。エージェントはエディターなしでドキュメントを検証できる必要があります。VS Code 拡張機能は、後から追加する薄いラッパーです。

コマンド

コマンドは 7 つです。重要なのは check で、残りのコマンドは、check が厳密に検査できる状態にドキュメントを整えたり、検査結果を説明したり、what-if の質問をしたりするためにあります。

flowchart LR
  plain[Plain table] -->|"infer --write"| wired[Rules and anchors in the file]
  wired -->|edit an input or a rule| stale[Stored values disagree]
  stale -->|fmt| wired
  stale -->|check| fail[Exit 1]
  wired -->|check| pass[Exit 0]
  wired -.-> evalCmd["eval / explain"]

コマンド	機能	オプション	書き込む内容	終了コード
visimark check FILE...	すべての数式を再計算し、数式と一致しなくなった数値を報告します	—	何も書き込みません	0 問題なし · 1 指摘事項あり · 2 使用方法が誤っている、またはファイルを読み取れない
visimark fmt FILE...	自身が管理する各数値のバイト列を差し替えて、古くなった値をその場で修正します	--fix-dates は、ISO 形式ではない曖昧さのない日付を書き換えます	計算セルとアンカー値のみ。入力値、文章、見出しは書き換えません	0 問題なし · 1 修正できない問題が残っている · 2 使用方法が誤っている、またはファイルを読み取れない
visimark infer FILE...	ドキュメントにすでにある数値を再現するルールを推定し、提案します	--write は提案した内容を挿入します	--write を指定しない限り何も書き込みません。指定した場合も挿入のみです	0 結果にかかわらず終了します。助言を提供するコマンドのためです · 2 使用方法が誤っている、またはファイルを読み取れない
visimark eval FILE	計算値をすべて、または名前を指定して 1 つ表示します	--get NAME、--json	何も書き込みません	0 · 2 使用方法が誤っている、ファイルを読み取れない、または該当する名前がない
visimark explain FILE	各シートの入力値、ルール、評価順序を表示します	#sheet を指定すると、対象を 1 つのシートに限定します	何も書き込みません	0 · 2 使用方法が誤っている、ファイルを読み取れない、または該当するシートがない
visimark ref [NAME]	組み込み関数の機能（シグネチャ、パラメーター、エラー、使用例）を表示するか、全 16 個の関数を一覧表示します	--json	何も書き込みません	0 · 2 該当する関数がない
visimark simulate FILE...	ドキュメントの lattice パラメーターで宣言された質問とデフォルト値をすべて使い、report 文が指定する読み取り値を表示します	--fail-on-fault は、レポートシートを開始できない場合に実行を失敗させます · --progress は stderr に進捗を表示します	何も書き込みません	0 アサーションが失敗した場合も、読み取り値を表示して終了します · 1 report が存在しない、または --fail-on-fault の指定時にシートを開始できない · 2 使用方法が誤っている、またはファイルを読み取れない

すべてのオプション、終了コード、および check が報告できるすべての指摘事項は、docs/cli-reference.md に一覧されています。

check は読み取り専用なので、どのようなファイルを対象にしても安全です。fmt が修正するのは、古くなった値だけです。それ以外の問題は人が判断する必要があるため、報告するだけで変更しません。

緑色のチェックには意味がなければなりません

数式がひとつもない文書には、照合するものがありません。数値とルールだけを比較するチェッカーなら問題なしと判定してしまいますが、それは最も誤解を招く答えです。check は、ルールが設定されていない表を、それ自体が問題として報告します。

$ visimark check quote.md
quote.md

  COVERAGE a table with no `vmark` rules — nothing in this document is checked
           run `visimark infer` to derive them, or mark it ``

  1 problem (0 stale, 1 error)

これが煩わしくならないよう、2つの仕組みがあります。まず、表がある場合にのみチェックするため、README や変更履歴などの文章に、存在しない計算を求めることはありません。また、文書全体を対象に数えるため、すべて入力値である参照表があっても、別の表にルールがあれば合格します。

文書から本当に導出するものが何もない場合は、その旨を文書内に記載してください。

これが唯一の例外であり、意図的にそうしています。このマーカーはワークフローのフラグではなくファイル内にあるため、内容とともに移動し、レビューに表示され、grep でも見つかります。導出できるものがまったくない場合、visimark infer --write がこのマーカーを書き込みます。一方、ニアミスや、どちらを選ぶか判断できない2つのルールが見つかった場合は書き込みを拒否します。これは、文書に計算があり、人による確認が必要だということだからです。このマーカーもほかのものと同じようにチェックされます。後からマーカー付きの文書にルールを追加すると、check はマーカーが誤りになったことを知らせます。

CI での利用

check の要点は、人の判断とは別の場所で実行できることです。そのため、CI での利用方法は1行です。

npx visimark check **/*.md

最初の不一致が見つかると、終了コードがゼロ以外になります。ほとんどの CI システムではこれで十分です。このリポジトリに同梱されているコンポジットアクション（action.yml）を使えば、npx の行を手作業で用意する代わりに、GitHub Actions のワークフローでも同じことができます。

- uses: michal-niedzwiedzki/[email protected]
  with:
    files: "docs/**/*.md"

設定するものはなく、厳密さを調整する項目もありません。グロブを指定するだけでセットアップは完了です。そのグロブに該当する文書に表があり、ルールがない場合は失敗します。そのため、上記の `` マーカーはワークフローではなくファイルに記載します。判断の対象は CI の実行ではなく、文書だからです。

すでに remark/remark-lint を使っているプロジェクトでは、代わりに remark-lint-visimark を使って同じチェックを追加できます。詳しくは docs/ci.md chapter 25 をご覧ください。

markdownlint を使っているプロジェクトでは、markdownlint-rule-visimark を使って追加できます。詳しくは docs/ci.md chapter 26 をご覧ください。

エージェントは visimark-mcp を使って、MCP 経由で同じエンジンにアクセスできます。simulate 以外のすべてのコマンドをツールとして、作成時の作法をリソースとして提供します。また、オペレーターが書き込みゲートを開かない限り、何も書き込みません。

npm i -g visimark-mcp   # or: bun add -g visimark-mcp
npx visimark-mcp        # or: bunx visimark-mcp
claude mcp add visimark -- npx -y visimark-mcp

すべての機能については docs/mcp.md をご覧ください。また、CI のチェックと並行して実行する方法については、docs/ci.md の chapter 27 をご覧ください。

構造上、差分を確認できます

.xlsx は XML を格納した zip 形式です。セルを 1 つ変更すると、コードレビューでファイルが変更されたことはわかりますが、それ以外はほとんど何もわかりません。VisiMark ではドキュメントをソースコードと同じようにレビューできます。これはテキストであることの副次的な効果ではなく、設計上の制約です。

fmt は Markdown を再レンダリングしません。位置を基準に自身が管理する各値を特定し、元のバイトバッファに差し込むため、書き換えられるのはその数値の文字だけです。段落の再配置、強調マーカーの再正規化、表の列の再整列は行われず、セルを 1 つ変更しただけで Markdown プリンターを通した際に発生する 400 行の差分も生じません。また、書き込むのは自身が管理する値だけです。計算セルとアンカー付きの値が対象です。入力列、文章、見出しは人間が管理する領域であり、変更されることはありません。

上記の差分例で未反映のままになっている編集、つまり作業した請求書で入力値の 1 つ、オンコール時間を 12 時間から 20 時間に増やすと、fmt は 6 個のセルと 9 個のアンカーを更新します。その結果は、127 行のドキュメントで13 行の差分になります。変更された各行は、実際にその入力値に依存する数値です。つまり、差分そのものが変更の波及を示します。レビュー担当者は VAT、3 回のマイルストーン分割払い、早期支払い条件、EUR 換算がすべて連動して変わったことを確認し、正しい理由で変わったかどうかを確かめられます。

もう一つの利点は、差分にすべてが含まれることです。計算式はドキュメント内にあるため、ルールが変更されれば、そのルールの変更が表示されます。ファイル外のものが数値を変えることはありません。プラグインも設定も時計も関与しません。また、集計は式ではなく列を受け取るため、中間値はすべてページ上に表示されます。合計は常に、レビュー担当者が確認できる数値の合計です。

VisiMark が拒否すること

値が二つの意味に解釈できる場合、VisiMark は推測せずにエラーにします。

日付は ISO 8601 のみです。YYYY-MM-DD の形式で、10 文字です。15.10.2026 は修正案を提示して拒否されます。15 は月になりえないためです。11/12/2026 は無条件で拒否されます。書いた人がどこに住んでいるかによって、12 月 11 日にも 11 月 12 日にもなるため、読み取るだけではどれだけ注意しても判別できません。桁区切りも同じ理由で拒否されます。

列には通貨記号または物理単位を付けられます。たとえば $5.50 や 12 N の場合、VisiMark は計算時にそれらを取り除き、書き込む際に元に戻します。ただし、一つの列に二つの意味を持たせることはできません。$5.00 と €5.00 の両方が入った列は、合計ではなくエラーになります。角括弧で宣言された単位はさらに厳密です。ヘッダーの Weight [kg] やバインディングの fx_eur [PLN/EUR] のように宣言すると、すべての式に引き継がれます。そのため、キログラムにメートルを足したり、為替レートを割る代わりに掛けたりすると、check が失敗します。係数による換算は一切行われず、$ が USD として読み取られることもありません。

同じスコープで名前を二重にバインドすると、黙って上書きするのではなくエラーになります。

真偽値リテラルはありません。比較によって真偽値が生成され、IF() がそれを受け取りますが、セルに真偽値が書き込まれることはありません。実体化された値は数値、日付、または文字列であるため、列の true という単語は、見た目どおり文字列のままです。

プラグインアーキテクチャは存在せず、今後も導入されません。 ドキュメントの数値は、そのドキュメント自身のテキストと、それを読み取る VisiMark のバージョンだけに依存し、それ以外には依存しません。拡張モジュールも、設定ファイルも、環境も、ネットワークも、時計もありません。ホストが提供する関数のレジストリがあれば、ドキュメントの内容から算術を検証できないドキュメントが生まれてしまいます。それこそが、この形式が防ぐために存在する唯一の事柄です。組み込みの語彙が小さすぎる場合の答えは、誰もが読めて実行できるエンジンの新しいプリミティブです。値が本当に外部から得られる場合は、人間が記録した入力列に置きます。この語彙を拡張する要望や、その他の言語・ツール変更の提案は、docs/vocabulary-catalogue.md を通じて提出します。ここにはすべての要望と、それに対する判断が記録されています。レビュー手順については docs/issue-runbook.md を参照してください。

これにより、形式は単に厳格になるだけでなく、より小さくなります。ロケールも、設定も、単独の / が何を意味するかを定める規則もありません。

ステータス

7 つのコマンドはすべて TypeScript で実装されています。npm i -g visimark または bun add -g visimark で visimark コマンドをインストールできます。PATH 上にある Node または Bun のいずれかで実行されます。インストールせずに実行するには、 npx visimark または bunx visimark を使用してください。（Windows では、npx / npm i -g のシムに PATH 上の sh が必要です。Git Bash または WSL で利用できます。）3 つの動作例が受け入れテストになっています。ドリフトした請求書に対する check は、 上記の記録をバイト単位で再現し、fmt は問題のない請求書を変更せず、数式がまったく含まれていない見積書 docs/example-quote-plain.md に対する infer は、そのドキュメント独自の付録にある記録を再現します。 設計と、先送りされた作業および既知の緊張関係については、docs/visimark-design.md を参照してください。

成果物	公開場所	詳細
CLI の visimark	npm	docs/cli-reference.md
ライブラリの visimark	npm、同じパッケージ	docs/library.md
MCP サーバーの visimark-mcp	npm および公式 MCP レジストリ	docs/mcp.md
言語サーバーおよび VS Code 拡張機能	VS Code Marketplace および Open VSX	editors/vscode/README.md
Obsidian プラグイン	Obsidian コミュニティプラグイン、および独自の GitHub リリース（v なしのタグ）	editors/obsidian/README.md
Joplin プラグイン	未公開。CI ビルドから作成した .jpl	editors/joplin/README.md
codemirror-visimark	npm、これを含む最初のタグから	packages/codemirror-visimark/README.md
markdown-it-visimark	npm、これを含む最初のタグから	packages/markdown-it-visimark/README.md
remark-lint-visimark	npm	packages/remark-visimark/README.md
markdownlint-rule-visimark	npm	packages/markdownlint-visimark/README.md

docs/distribution.md には、各成果物が掲載されているすべてのレジストリとディレクトリが記録されています。vX.Y.Z タグを付けると、 npm パッケージ、MCP レジストリのエントリー、VS Code 拡張機能が公開されます。 docs/releasing.md はチェックリストです。また、 CONTRIBUTING.md では、クローンからエディタープラグインをビルドしてインストールする方法を説明しています。

エージェント向け

skills/visimark/SKILL.md は、これらのドキュメントを作成、検証するためのエージェントスキルです。インストールするには、~/.claude/skills/visimark/ にコピーしてください。中心となる注意点は、ここでも述べておく価値があります。緑のチェックが示すのは整合性であり、導出過程ではありません。ドキュメントが正しく連携していると判断する前に、入力を変更し、チェッカーが問題を報告し始めることを確認してください。前述の COVERAGE 検出は、ビルドを含まないドキュメントでエージェントがビルド成功を報告できないようにするものですが、より確かな安全策は、やはりこの習慣です。

また、初めて作業するリポジトリでエージェントが利用できる MCP サーバー、visimark-mcp もあります。npx visimark-mcp または bunx visimark-mcp、あるいは claude mcp add visimark -- npx -y visimark-mcp で実行できます。このサーバーは上記のスキルをリソースとして提供するため、検証ツールとは別にではなく、検証ツールとともにその規律が導入されます。--allow-write を指定し、さらにホストが宣言したルートを渡さない限り、読み取り専用です。

エディターのサポートは docs/visimark-editor-plugins-design.md で仕様が定められています。1 つの言語サーバーで、継続的な check を診断として、fmt をエディター独自の保存時フォーマット機能の背後で実行し、クイックフィックスと、バイト列に触れずに計算結果を示すインレイヒントを提供します。最初のクライアントは VS Code です。

git clone … && cd visimark && bun install
bun run test                # the full suite, the three examples included
bunx visimark check docs/example-invoice-drift.md

bun install はエンジンをビルドし、visimark コマンドを node_modules/.bin にリンクするため、新しくクローンしたリポジトリでも bunx visimark を利用できます。ビルドせずにソースから CLI を直接実行するには、bun packages/visimark/src/cli/main.ts check FILE を使用してください。

このプロジェクトは CSV ベースのアイデアとして始まり、複数の小さなシートを 1 つのマスタードキュメント内にまとめられること、またファイルがデータではなくドキュメントとして表示されることを目指して Markdown に移行しました。名前は、最初のスプレッドシートソフトウェアであり、VisiCorp が Apple II 向けに開発し、後に IBM PC に移植した VisiCalc にちなんでいます。

対象外

VisiMark は、意図的にスプレッドシートの代替にはしていません。グリッド、プレゼンテーションレイヤー、セルのスタイル設定、ロケール、Excel ファイルとの互換性、Excel の関数ライブラリを再現する試みはありません。見栄えよく表示するには別のツールを使い、スプレッドシートが必要な場合はスプレッドシートを使ってください。

ドキュメントを作りたいときに VisiMark を使ってください。ツールがなくても読めるプレーンテキストで、通常のプルリクエストでレビューでき、人間やエージェントが編集でき、すべてのコミットで数値を検証できるドキュメントです。