DEV Community

Satoshi Kaneyasu
Satoshi Kaneyasu

Posted on

How to Reduce markdownlint Violations in AI-Generated Markdown

#ai #markdown #kiro #claudecode

I'm Kaneyasu from the Application Services Division, DevOps team at Serverworks.

Have you ever had AI coding agents (Claude Code, Kiro, GitHub Copilot Agent Mode, etc.)
generate or edit Markdown files, only to find yourself drowning in markdownlint warnings?

This article covers the common violation patterns and
a mitigation strategy combining markdownlint configuration with AI agent instruction files.

What is markdownlint?

Markdown has style best practices such as
"add blank lines around headings" and "limit line length."
markdownlint is the linter that automatically checks these rules.

markdownlint checks Markdown files for style and syntax consistency.
It defines rules from MD001 through MD060 and can be used via
the VS Code extension (davidanson.vscode-markdownlint) or CLI (markdownlint-cli2).

You can customize which rules are enabled and their parameters
by placing a .markdownlint.json file in your project root.

Warnings from markdownlint don't make files unreadable.
However, if you get into the habit of ignoring warnings,
eventually no one will pay attention to them,
and linters in general lose their effectiveness.

Common Violations When AI Generates Markdown

In my environment, when I have AI generate Markdown in a project with markdownlint enabled,
the following violations occur frequently.
Your experience may vary, but I suspect most people can relate.

  • MD022 (blank lines around headings): Forgets blank lines before/after headings
  • MD032 (blank lines around lists): No blank lines before/after list blocks
  • MD058 (blank lines around tables): No blank lines before/after tables
  • MD013 (line length): Outputs long paragraphs as a single line without line breaks
  • MD036 (emphasis used instead of heading): Uses a **bold**-only line as a heading substitute
  • MD009 (trailing spaces): Leaves unnecessary trailing spaces at end of lines
  • MD012 (multiple blank lines): Inserts 2 or more consecutive blank lines

MD036 (emphasis as heading) is the one I see most often.
AI tends to insert **bold**-only lines to visually separate sections.

MD013 (line length) is especially common with CJK text.
AI doesn't consider the CJK convention of breaking lines at punctuation marks,
and tends to output entire paragraphs as a single line.

Mitigation Strategies and File Locations

There are two main approaches:

  1. Relax markdownlint settings — widen the tolerance to reduce warnings
  2. Instruct AI agents via instruction files — tell them to follow the rules at generation time

AI instructions are not guaranteed to be followed 100% of the time.
Since configuration files provide more reliable enforcement,
combining both approaches works best.

.markdownlint.json (Linter Configuration)

Place a .markdownlint.json file in your project root.
Here is the configuration I use:

{
  // Relax the default 80 characters to 120.
  // Exclude tables, code blocks, and headings from inspection
  "MD013": {
    "line_length": 120,
    "tables": false,
    "code_blocks": false,
    "headings": false
  },
  // Disable the duplicate heading rule.
  // Technical articles often use headings like "Step 1", "Step 2"
  "MD024": false,
  // Set table pipe style to consistent (uniform within each table).
  // Strict column alignment is difficult with CJK characters
  "MD060": {
    "style": "consistent"
  }
}
Enter fullscreen mode Exit fullscreen mode

Some people may prefer not to enforce line length limits at all — that's a valid preference.

Instructing AI Agents to Follow the Rules

markdownlint alone cannot prevent violations at generation time.
You need an instruction file that tells the AI agent to follow specific rules.

I include instructions like the following in my AGENTS.md:

## Markdown Style Rules

This project uses markdownlint.
When creating or editing Markdown files, you must follow these rules.

### Headings (MD022)

Always add a blank line before and after headings.

### Lists (MD032)

Always add a blank line before and after list blocks.

### Line Length (MD013)

Keep each line within 120 characters. Tables, code blocks, and headings are exempt.

Tips for long lines:
- Long paragraphs: Break lines after periods or commas
- Long URLs: Place the URL on its own line with blank lines around it

### No Emphasis as Headings (MD036)

Do not use bold/italic-only lines as heading substitutes.
Enter fullscreen mode Exit fullscreen mode

Adding good/bad examples helps the AI understand the rules more accurately.

Where to Place Instruction Files

File Target Tool Location
CLAUDE.md Claude Code ~/.claude/CLAUDE.md (global) or project root
AGENTS.md Multiple AI agents Project root
.kiro/steering/*.md Kiro .kiro/steering/ directory
.github/copilot-instructions.md GitHub Copilot .github/ directory

Differences Between AGENTS.md and CLAUDE.md

In the previous section I used AGENTS.md for the example,
but CLAUDE.md is probably the most well-known AI agent instruction file.
Let me explain the differences.

AGENTS.md

AGENTS.md is an instruction file for AI agents in general, placed at the project root.
OpenAI published the specification as an open standard format.

As stated on the official site,
many AI coding agents and tools support AGENTS.md.
Therefore, rules you want enforced across multiple tools — like Markdown style rules —
are best placed in AGENTS.md.

CLAUDE.md

CLAUDE.md is an instruction file exclusive to Claude Code.
It is automatically loaded when Claude Code opens a project.

There are two placement options:

  • ~/.claude/CLAUDE.md — Global settings for all projects
  • CLAUDE.md at project root — Project-specific settings

Ideally, Claude Code would also read AGENTS.md,
but currently there doesn't appear to be such a feature.
You could instruct Claude Code to read AGENTS.md from within CLAUDE.md,
which might achieve the goal indirectly,
but it's not guaranteed to work reliably.

Kiro

Kiro has its own steering mechanism
where Markdown files placed in .kiro/steering/*.md are loaded as instructions.

Additionally, Kiro supports AGENTS.md.
The official documentation (Steering — Kiro) states:

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.

This means if you place AGENTS.md at the workspace root,
it will always be loaded regardless of steering file inclusion settings.

Note that the official documentation is published under the "CLI" section,
and there is no explicit statement about IDE (Kiro IDE) behavior.
However, when I verified this in Kiro IDE,
AGENTS.md was automatically included in the context
as a workspace-level "Included Rules" entry, just like in the CLI.
Although there is no official confirmation,
the steering mechanism appears to be shared between CLI and IDE.

Placement options:

  • AGENTS.md at workspace root — Project-specific rules
  • ~/.kiro/steering/AGENTS.md — Global rules for all projects

Kiro's steering files (.kiro/steering/*.md) and AGENTS.md can be used together.
A good approach is to put cross-tool rules (like Markdown style) in AGENTS.md
and Kiro-specific instructions in steering files.

Summary

To reduce markdownlint violations in AI-generated Markdown,
combining the following two approaches is effective:

  1. Adjust .markdownlint.json to set appropriate tolerances
  2. Provide specific rules and examples in AGENTS.md or CLAUDE.md

It's difficult to eliminate violations entirely,
but setting up both of these significantly reduces them in practice.

Top comments (0)