textlint/markdownlint(文章校正自動化)

何のための道具か

コードに [[静的解析とリンター]] があるように、文章にも機械が判定できる規則があります。

markdownlint — Markdown の書式を見る。見出しレベルの飛び、リストのインデント、行末の空白、テーブルの書式
textlint — 日本語の文章を見る。表記ゆれ、二重否定、一文の長さ、句読点の連続、である/ですます混在

区別は「書式か中身か」です。## の次に #### が来るのは markdownlint、「サーバ」と「サーバー」が混在しているのは textlint の担当です。

npx markdownlint-cli2 "docs/**/*.md"
npx textlint "docs/**/*.md"

何を自動化すべきか

[[コードレビュー]] で「サーバとサーバーが混ざっています」と毎回書くのは、人がやる価値のない指摘です。機械が判定できる規則は機械に任せ、レビューでは構成・正確さ・読者にとっての分かりやすさを扱います。

機械に任せる	人がレビューする
表記ゆれ、送り仮名、全角半角	説明の順序が読者の理解に沿っているか
見出しレベル、リストの書式	事実として正しいか
一文の長さ、句読点の数	その説明が本当に必要か

ルールは強すぎると無視される

導入で失敗しやすいのが、既定のルールを全部有効にすることです。既存の文書が数百件の警告を出し、誰も直さなくなり、やがて検査そのものが無視されます。

現実的な順番は次のとおりです。

既存文書が通る最小の構成から始める — まずは表記ゆれ辞書だけ、など
新規・変更した文書にだけ適用する — 差分に対して検査する
合意できたルールを1つずつ足す — 増やすときは既存への影響を測ってから

「既存の執筆スタイルによる警告は修正不要」と方針を明文化しておくと、警告と実際の欠陥を取り違えずに済みます。既存の文体を否定しない範囲を決めることが定着の条件です。

CIへの組み込み

設定は [[YAML]] や JSON で書き、[[CI/CD]] のジョブとして走らせます。

文書だけの変更でも走らせる — コードの検査を飛ばす設定にしていると、文章検査まで一緒に飛ぶことがあります
修正の自動適用は分けて考える — --fix は便利ですが、文章の自動書き換えは意図を変えることがあります。書式(markdownlint)は自動修正、文章(textlint)は指摘のみ、という分け方が無難です
除外設定を明示する — 生成物や引用を含む文書は対象から外します

初学者向けポイント

表記ゆれの辞書はプロジェクト固有の語から作ると効果が出ます。製品名・用語の統一が最初の成果になります
警告が出たとき、規則のほうを疑う視点を残します。文章の規則はコードほど自明ではなく、書き手の判断が正しいこともあります
[[ドキュメンテーション]] の価値は読まれることです。検査は読みやすさの手段であって目的ではありません

関連技術とのつながり

[[静的解析とリンター]] — 同じ「機械が判定できる規則を自動化する」考え方の文章版
[[ドキュメンテーション]] — 検査の対象。読まれる文書にするための手段
[[コードレビュー]] — 機械に任せた分、人は構成と正確さに集中できる
[[CI/CD]] — 差分に対して検査を走らせる実行基盤
[[YAML]] — ルールと辞書を書く設定ファイルの書式

Q: markdownlintとtextlintの役割分担として正しいのはどれ?
- [x] markdownlintは書式、textlintは日本語の文章を見る
- [ ] markdownlintは日本語、textlintは英語を見る
- [ ] どちらも同じ規則を別の書式で書いたもの
解説: 見出しレベルやリストの書式はmarkdownlint、表記ゆれや一文の長さはtextlintの担当です。

Q: 文章Lintの導入で失敗しやすいやり方はどれ?
- [ ] 表記ゆれ辞書だけを有効にして始める
- [x] 既定のルールをすべて有効にして既存文書に一斉適用する
- [ ] 変更した文書にだけ検査を適用する
解説: 大量の警告が出ると誰も直さなくなり、検査そのものが無視されるようになります。

Q: `--fix` による自動修正の扱いとして無難なのはどれ?
- [ ] 書式も文章もすべて自動修正する
- [x] 書式は自動修正、文章は指摘のみに留める
- [ ] 自動修正は一切使わない
解説: 文章の自動書き換えは意図を変えることがあるため、書式の整形と切り分けます。