docs-markdown — Claude Code rule: what it does, how to install
docs-markdown — a markdown documentation rule: command samples must run, project paths start at the root, and architecture notes have to match what the code does.
MIT ★ 1,198 updated 2026-10-23
.claude/rules/docs-markdown.mdWhat docs-markdown does
The rule lists what markdown in the repo has to look like. Command samples run and match the real scripts, file paths start from the project root, and any claim about the architecture reflects current code behaviour.
One bullet covers syncing. When a workflow changes, README.md, README-EN.md and its mirrors, ARCHITECTURE, SETUP, INSTALL and mcp/README all get edited in the same pass. Sections stay short, and troubleshooting gives real steps.
The frontmatter carries paths: **/*.md, so the rule fires on markdown only and leaves source files alone. The usual failure is fixing one README from that list and skipping the rest; the docs then contradict each other.
What it helps with
- keep command samples in the docs runnable
- use root-based file paths instead of guessed relative ones
- update every affected README in a single pass after a workflow change
- drop architecture claims the code no longer backs
- trim a section down to concrete troubleshooting steps
Example prompts for the agent
- Update
README.mdandARCHITECTUREfor the new startup flow, and check that every command in them actually runs. - Rewrite the install section of
README-EN.mdwith root-based paths and real troubleshooting steps. - We reworked how
mcp/READMEis structured — go through the other docs that reference it.
How to install docs-markdown
Manually: put the files in place
.claude/rules/docs-markdown.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/docs-markdown.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/docs-markdown.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/docs-markdown.mdManually: put the files in place
.clinerules/docs-markdown.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about docs-markdown
How do I install docs-markdown in Claude Code?
Place the rule file in your project at .claude/rules/docs-markdown.md.
What does docs-markdown do?
It sets five requirements for markdown docs: runnable command samples, root-based paths, architecture notes that match the code, all affected docs updated together, and short sections with concrete troubleshooting.
Which files does the rule apply to?
Markdown files only, scoped by paths: **/*.md in the frontmatter. Source code and configs are outside it.
Source text
docs-markdown.md · MIT
--- paths: - "**/*.md" --- # Documentation Rules - Keep command examples executable and aligned with actual scripts. - Use absolute or clearly rooted paths when discussing project files. - When adding architecture claims, reflect current code behavior. - Update all affected docs together (`README.md` landing, `README-EN.md` full guide and mirrors, `ARCHITECTURE`, `SETUP`, `INSTALL`, `mcp/README`) when workflows change. - Prefer concise sections and concrete troubleshooting steps.
© hoangsonww · MIT · hoangsonww/Claude-Code-Agent-Monitor