【小ネタ】AIが生成するマークダウンがやたらmarkdownlintで引っかかる現象の緩和策

アプリケーションサービス本部 DevOps 担当の兼安です。

AI コーディングエージェント（Claude Code、Kiro、GitHub Copilot Agent Mode など）に
マークダウンファイルを生成・編集させると、
markdownlint の警告が大量に出て困った経験はないでしょうか。

この記事では、よくある違反パターンと、
AI エージェントへの指示ファイルと markdownlint の設定を組み合わせた緩和策を紹介します。

markdownlint とは

マークダウンには「見出しの前後に空行を入れる」「1行の長さを制限する」といった
書式上のベストプラクティスがあります。
これらを自動で検査してくれるのが markdownlint です。

markdownlint は、マークダウンファイルのスタイルや構文の一貫性をチェックするリンターです。
MD001〜MD060 までのルールが定義されており、
VS Code 拡張（davidanson.vscode-markdownlint）や CLI（markdownlint-cli2）で利用できます。

• GitHub - DavidAnson/markdownlint: A Node.js style checker and lint tool for Markdown/CommonMark files. · GitHub
• markdownlint - Visual Studio Marketplace

プロジェクトルートに .markdownlint.json を置くことで、
ルールの有効/無効やパラメータをカスタマイズできます。

markdownlint で警告が出たからといって読めないわけではありません。
しかし、警告をスルーする習慣がつくと、いずれ警告を気にしなくなり、
リンター全般が効力を発揮しない文化に繋がりかねません。

AI にマークダウンを生成させた時によく見られる現象

私の環境では markdownlint を導入したプロジェクトで
AI にマークダウンを生成させると、おおむね以下のような違反が頻発します。
環境によって差はあるかもしれませんが、概ね共感いただけるのではないでしょうか。

• MD022（見出し前後の空行）: 見出しの直前・直後に空行を入れ忘れる
• MD032（リスト前後の空行）: リストブロックの前後に空行がない
• MD058（テーブル前後の空行）: テーブルの前後に空行がない
• MD013（行の長さ）: 日本語の長い段落を改行せず 1 行に詰め込む
• MD036（強調を見出し代わりに使う）: **太字** だけの行で見出しの代わりにする
• MD009（行末スペース）: 行末に不要なスペースが残る
• MD012（連続空行）: 空行を 2 行以上連続で入れる

特に目にするのは MD036（強調を見出し代わりに使う）です。
AI はセクションの区切りを強調するために **太字** だけの行を挿入しがちです。

日本語テキストでは MD013（行の長さ制限）もよく発生します。
AI は句読点で改行するという日本語特有の慣習を考慮せず、
段落をまるごと 1 行で出力する傾向があります。

緩和策と設定ファイルの置き場所

対策は大きく 2 つのアプローチがあります。

1. markdownlint の設定で許容範囲を広げる — ルールを緩和して警告を減らす
2. AI エージェントへの指示ファイルでルールを守らせる — 生成時点で違反しないよう指示する

AI への指示は 100％守られる保証はありません。
設定ファイルで対処できるものはそちらで対処した方が確実なので、
両方を組み合わせるのが良いと思います。

.markdownlint.json（リンター設定）

プロジェクトルートに .markdownlint.json を配置します。
以下は私が使用している設定です。

{
  // デフォルトの80文字を120文字に緩和。
  // テーブル・コードブロック・見出しは検査対象外にしている
  "MD013": {
    "line_length": 120,
    "tables": false,
    "code_blocks": false,
    "headings": false
  },
  // 同名見出しの禁止を無効化。
  // 技術記事では「手順1」「手順2」のように同名見出しを使うことがある
  "MD024": false,
  // テーブルのパイプスタイルを consistent（同一テーブル内で統一）に設定。
  // CJK文字を含むテーブルでは列幅の厳密な揃えが難しいため
  "MD060": {
    "style": "consistent"
  }
}

1行の文字数に関してはむしろ改行を入れない方が好みの人もいらっしゃるとは思います。

AI エージェントへの指示ファイルでルールを守らせる

markdownlint だけでは「生成時点で違反しないようにする」ことはできません。
AI エージェントに対して「このルールを守って書いて」と指示するファイルが必要です。

私は AGENTS.md に以下のような指示を記載しています。

## Markdown 記述ルール

このプロジェクトでは markdownlint を使用しています。
Markdown ファイルを作成・編集する際は以下のルールを必ず守ってください。

### 見出し（MD022）

見出しの前後には必ず1行の空行を入れる。

### リスト（MD032）

リストブロックの前後には必ず1行の空行を入れる。

### 行の長さ（MD013）

1行は120文字以内に収める。テーブル・コードブロック・見出しは対象外。

長くなりやすいケースの対処法：
- 日本語の長い段落: 句点（。）や読点（、）のあとで改行する
- 長いURL: 前後に空行を置き、URL単体で1行にする

### 強調を見出し代わりに使わない（MD036）

段落内に太字・斜体のみのテキストを置いて見出し代わりにしてはいけない。

良い例・悪い例を添えると、AI はより正確にルールを理解します。

指示ファイルの置き場所

ファイル	対象ツール	配置場所
CLAUDE.md	Claude Code	~/.claude/CLAUDE.md（グローバル）またはプロジェクトルート
AGENTS.md	複数の AI エージェント	プロジェクトルート
.kiro/steering/*.md	Kiro	プロジェクトの .kiro/steering/ ディレクトリ
.github/copilot-instructions.md	GitHub Copilot	.github/ ディレクトリ

AGENTS.md と CLAUDE.md の違い

前項では AGENTS.md を用いて例を示しましたが、
AI エージェントへの指示ファイルで一番有名なのは CLAUDE.md でしょう。
両者の違いを述べておきます。

AGENTS.md

AGENTS.md はプロジェクトルートに置く、AI エージェント全般向けの指示ファイルです。
OpenAI が仕様を公開しており、オープンな標準フォーマットとして提唱されています。

• AGENTS.md
• GitHub - agentsmd/agents.md: AGENTS.md — a simple, open format for guiding coding agents · GitHub

公式サイトに記載がある通り、
多数の AI コーディングエージェントとツールが AGENTS.md をサポートしています。
従って、マークダウンのルールのようにツール横断で守ってほしいルールは
AGENTS.md に書いておくのが効率的です。

CLAUDE.md

CLAUDE.md は Claude Code 専用の指示ファイルです。
Claude Code がプロジェクトを開いた時に自動で読み込まれます。

配置場所は 2 種類あります。

• ~/.claude/CLAUDE.md — 全プロジェクト共通のグローバル設定
• プロジェクトルートの CLAUDE.md — プロジェクト固有の設定

Claude Code にも AGENTS.md を読ませたいところですが、
現状ではそのような仕様は見当たりません。
CLAUDE.md の中で AGENTS.md を読むよう指定すれば
擬似的に目的を達成できる可能性はありますが、
確実にそうなるとは言い切れないのが正直なところです。

Kiro の場合

Kiro には独自のステアリング機構があり、
.kiro/steering/*.md に配置したマークダウンファイルが指示として読み込まれます。

加えて、Kiro は AGENTS.md もサポートしています。

Steering - CLI - Docs - Kiro

公式ドキュメント（Steering — Kiro）には以下のように記載されています。

Kiro supports providing steering directives via the AGENTS.md standard.
AGENTS.md files are in markdown format, similar to Kiro steering files;
however, AGENTS.md files are always included.

つまり、AGENTS.md をワークスペースルートに置けば、
ステアリングファイルの inclusion 設定に関わらず常に読み込まれます。

なお、この公式ドキュメントは「CLI」セクション配下に掲載されており、
IDE（Kiro IDE）での挙動については明示的な記載がありません。
しかし、筆者が Kiro IDE で確認したところ、
AGENTS.md は CLI と同様にワークスペースレベルの「Included Rules」として
自動的にコンテキストに含まれていました。
公式の明言はないものの、
CLI と IDE でステアリングの仕組みは共通であると推測されます。

配置場所は以下の通りです。

• ワークスペースルートの AGENTS.md — プロジェクト固有のルール
• ~/.kiro/steering/AGENTS.md — 全プロジェクト共通のグローバルルール

Kiro 固有のステアリングファイル（.kiro/steering/*.md）と AGENTS.md は併用可能です。
マークダウンのルールのようにツール横断で守ってほしい内容は AGENTS.md に、
Kiro 特有の指示はステアリングファイルに、と使い分けるのが良いでしょう。

まとめ

AI コーディングエージェントが生成するマークダウンの markdownlint 違反を減らすには、
以下の 2 つを組み合わせるのが効果的です。

1. .markdownlint.json で許容範囲を適切に調整する
2. AGENTS.md や CLAUDE.md で具体的なルールと例を示す

完全にゼロにすることは難しいですが、
この 2 つを設定すると体感的に違反が大幅に減ります。

兼安 聡(執筆記事の一覧)

アプリケーションサービス本部 DS3課
2026 Japan AWS Ambassadors
2024-2026 Japan AWS Top Engineers
2024-2026 Japan AWS All Certifications Engineers
2025-2026 AWS Community Builders
Certified ScrumMaster
PMP
広島在住です。今日も明日も修行中です。
X(旧Twitter)