今の時代にマークダウンの書き方を強制すること
こんにちは👋
最近、Go の世界 Top 1% エンジニアになった(!?)っぽい @jackchuka です。
https://algora.io/profile/jackchuka
今日は、私が最近公開した新しいツール mdschema を紹介したいと思います。
背景：マークダウンは「人間のため」だけじゃなくなった
エンジニアがもっともよく使うドキュメントフォーマットと言えば、マークダウン（Markdown） ではないでしょうか。
マークダウンは人間に優しい軽量記法として普及し、READMEや仕様書、ブログ記事のようないろいろなドキュメントを書くのに広く使われています。
最近では人間と AI がどちらも読めるフォーマットとしても重要な役割を果たしていますね。
また、仕様駆動開発といった場面で AI がドキュメントを 読む だけではなく、調査・解析した結果をまとめて 書く ことにも使われるようになりました。
マークダウンは素晴らしいフォーマットですが、テキストベースで自由度が高いため、ドキュメントの構造が揺らぎやすい という問題があります。（そもそも AI に使われるという前提がなかったので当然ですが…）
問題：AI開発時代、ドキュメントが“揺れる”と壊れる
AI での開発やワークフローの導入が進めば進むほど、ドキュメントは
- 人間が手で追記する
- AI が自動で追記する
- 別の AI が別のスタイルで整形する
- さらに別の AI が要約して貼り直す
という感じで、いろんな「書き手」が関わる ようになります。
その結果、何が起きるかというと
- 見出しの順番がバラバラになる
- 必須セクションが消える / 追加される
- コードブロックの言語タグが抜ける
- 「ここに書くべき注意事項」が本文に埋もれる
そしてそれが、AI の出力のブレ や 人間のレビュー負荷増大 に直結します。
AI はすでにある文書の雰囲気から「たぶんこうだよね」と推測して書き換えを行いますが、ガードレールがないと普通に脱線します。
これは、マークダウンに限った話ではありませんが、特に単なるテキストであるマークダウンでは顕著に現れる問題です。
コードならリンターやフォーマッターで防いでいるじゃないか、と思うことでしょう。
そこで作ったのが、mdschema です。
マークダウンの書き方を 「好み」ではなく「仕様」 にするという、新しいツールチェーンの一部を担う CLI です。
mdschema とは
mdschema は、YAML で宣言したスキーマに基づいてマークダウンを検証する CLIです。
やりたいことはシンプルで、
- 「この README はこの順番でこの見出しが必要」
- 「このセクションには bash のコードブロックが最低 1 個必要」
- 「Usage には example という単語が必ず含まれていてほしい」
- 「このテーブルには特定のカラムが必要」
みたいなルールを スキーマとして書いて、
マークダウンがそれを満たしているかをチェックします。
特徴はだいたいこんな感じです。
- 🔍 Schema-driven validation: YAML で構造を定義
- 🌳 Hierarchical structure: ネストした見出しも扱える
- 📝 Template generation: スキーマからテンプレを生成できる
- 🔧 Rule-based validation: 見出し / コードブロック / 必須テキストなど
- 🎯 Context-aware: 文字列マッチではなく AST 解析で検証
- 🚀 Single binary: 依存なしで軽量
使い方
インストール
brew install jackchuka/tap/mdschema
まずスキーマを作る
mdschema init
プロジェクト直下に .mdschema.yml を作って、ここにルールを書いていきます。
ドキュメントを検証する
mdschema check README.md --schema .mdschema.yml
✓ No violations found
指定したドキュメントがスキーマに準拠しているかを検証します。
CI で回すなら、この使い方がメインになります。
スキーマからテンプレを生成する
mdschema generate -o new-doc.md
スキーマをもとに、テンプレートドキュメントを生成します。
「新しいドキュメントを書くときに、毎回ゼロから悩む」を減らす用途です。
スキーマの例
「README はこういう構造にしてね」を書くと、だいたいこうなります。
# .mdschema.yml
structure:
- heading:
pattern: "# [a-zA-Z0-9_\\- ]+" # プロジェクトタイトル（正規表現）
regex: true
children:
- heading: "## Features"
optional: true
- heading: "## Installation"
code_blocks:
- { lang: bash, min: 1 } # bash の code block を最低 1 つ
children:
- heading: "### Windows"
optional: true
- heading: "### macOS"
optional: true
- heading: "## Usage"
code_blocks:
- { lang: go, min: 2 } # Go の code block を最低 2 つ
required_text:
- "example" # Usage には example の文字が必要
- heading: "# LICENSE"
optional: true
ドキュメントの「形」を固定するというより、
チームが守りたい前提（= AI が読む前提）を固定するイメージです。
なぜ今これが効くのか：AI への入力と出力を守るためのガードレール
1) AI にとっての入力を安定させる
Claude でも Copilot でも、最近は「リポジトリのガイドライン」や「このプロジェクトのルール」を読み込ませて、その上で PR を作ったり、ドキュメントを更新したりすると思います。
仕様書の内容が不足していたり、適切なリストやテーブルのカラムがなかったりすると、AI の出力も揺れます。
- ルールが読めない → 違反した PR が出る
- 手順が見つからない → 推測で書き換える
- 参照箇所が安定しない → 更新漏れが起きる
これらはすべて「AI の性能不足」というよりかは、入力が不安定なのが原因だったりします。
2) 人間のレビュー負荷を減らす
また、逆も然りです。
AI を用いてドキュメントを更新したり、生成したりする場合も、AI が書いたドキュメントのレビューで辛いのは、「内容の正しさ」よりも
- どこに何が書いてあるかわからない
- いつもの並びじゃない
- 必要なセクションが消えている
みたいな、構造の問題だったりします。
ここが固定されるだけで、レビューが一気に楽になります。
3) “勝手に書き換える AI” への防御
AI は親切(?!)なので、つい
- 見出しをまとめる
- 冗長なセクションを削る
- よさげに整形する
をやります。
しかしそれがチームでマネージしているファイルや運用手順書だと、それが大きな事故になりかねません。
mdschema で「このセクションは必須」「この順番は守る」を固定しておくと、CIなどで
意図しない整形を PR で検知できます。
ユースケース
他にもいくつか考えられるユースケースを記載しておきます。
- ドキュメント標準化（README / ADR / Runbook のテンプレ化）
- 複数リポジトリで「同じ形」を維持したい
- AI エージェントに「必ずこのセクションを更新させたい」
- オンボーディング資料の抜け漏れを防ぎたい
- API ドキュメントのフォーマットを統一したい
- などなど
まとめ
今の時代、ドキュメントは「人間が読むもの」から、
AI が読み、AI が書き、AI が実行するものに変わってきました。
そのとき、マークダウンの書き方を強制するのは、
単なる好みや統一感の話ではなく、
- AI の出力を安定させる
- レビューコストを下げる
- 事故を減らす
ための ガードレールになります。
mdschema は、そのための小さな道具です。
もし「うちのリポジトリ、ドキュメントがカオスになってきたな…」とか、
「AI に任せたいけど、仕様書の整合性が怖いな…」と思ったら、
ぜひ一度試してみてください。
おまけ：次にやりたいこと・助けてほしいこと
- GitHub Actions 用のサンプル追加（コピペで導入できるやつ）
- スキーマの分割・継承（共通ルールを org 全体で使いたい）
- エラー出力の改善（どこがどう違うかをもっとわかりやすく）
Star・フィードバック・PR お待ちしてます 🙌
それでは！
Discussion