atomcode-review 的 Markdown 评审规则：文档变更如何获得专属的安全检查清单

• 人工智能
• AI Agent
• 代码智能体
• 自主智能体
• MCP Clients
• CLI

本文以 crates/atomcode-review/rules/markdown.md 为核心，逐条解读 atomcode-review 面向文档/README 类文件的评审规则——它检查什么、拒绝报告什么；并结合 规则引擎源码 讲清这条规则如何被匹配、分组、注入到评审 Agent 的提示词中，以及如何在运行时用--rules-dir热覆盖而无需重新编译。读完可掌握 atomcode-review 的语言规则机制全貌，并能按同样方式为自己团队的文档定制审查口径。

markdown 规则是什么

atomcode-review 按「变更文件类型」给评审 Agent 注入差异化的检查清单，每种文件类型对应rules/目录下的一份 Markdown 规则文档。markdown.md是其中专门针对文档类文件（readme*.md、*.md、*.markdown）的一条。与 go.md、sql.md 等语言规则不同，文档没有可执行逻辑，因此该规则关注的不是代码 bug，而是文档本身是否会误导用户执行危险操作。

规则原文全文如下（编译进二进制，是这条规则的唯一事实来源）：

[Markdown] This batch contains documentation/README; pay extra attention to: #### Dangerous Operation Instructions - Does the document add unsafe commands or configurations, such as `chmod 777`, disabling TLS verification, disabling auth, exposing `0.0.0.0`, writing plaintext secrets, or using weak default passwords. - Does the README / example commands guide users to execute untrusted scripts, pipe remote content, overwrite system directories, or leak tokens. #### Configuration and Supply Chain Misguidance - Does the document recommend installing suspicious dependencies, outdated high-risk dependencies, or unpinned versions, or configurations that conflict with security requirements in the code. - Do examples for permissions, ports, CORS, databases, caches, and queues make the production environment insecure by default. #### Testing and Usage Instructions - If the document adds test/deployment steps, check whether they skip critical tests, hide failures, or mislead users into believing functionality is verified. #### Reporting Boundary - Only report documentation issues that cause security risks, production misuse, test failures, or data destruction; do not report wording, layout, or typos as pure documentation quality issues.

对照原文，四个小节各自解决一个具体问题：

危险操作指引（Dangerous Operation Instructions）

这是文档类 diff 中风险最高的一类：README 里一行chmod 777或一段「curl 远程脚本直接 pipe 给 shell」的示例，会随文档扩散到所有克隆该仓库的用户机器上。检查项覆盖两类：

• 不安全的命令与配置：chmod 777、关闭 TLS 校验、关闭鉴权、把服务暴露在0.0.0.0、明文写入密钥、弱默认密码；
• 不可信执行链：示例命令引导用户执行来源不明的脚本、把远程内容直接 pipe 给解释器执行、覆盖系统目录、或在示例命令中泄露 token。

配置与供应链误导（Configuration and Supply Chain Misguidance）

文档推荐的依赖与配置同样会酿成生产事故。检查点包括：推荐安装可疑依赖、过期高危依赖、未锁版本的依赖，或给出与代码中实际安全要求相冲突的配置；权限、端口、CORS、数据库、缓存、队列等示例是否让生产环境「默认即不安全」（insecure by default）。

测试与使用说明（Testing and Usage Instructions）

文档新增的测试/部署步骤是否跳过关键测试、掩盖失败，或误导读者以为功能已被验证。这一项针对的是「文档承诺与实际能力不符」的常见失真。

报告边界（Reporting Boundary）

这是整条规则的元约束：只报告会造成安全风险、生产误用、测试失败或数据破坏的文档问题；措辞、排版、错别字这类纯文档质量问题明确排除在外。从源码结构看，这与整套规则集的降噪设计一致——其他语言规则中也大量存在反向清单（例如 go.md 并发一节的 "Do not report the following"、sql.md 结尾的 "prefer to skip rather than misreport"），目的都是压低误报率，避免评审 Agent 把精力消耗在风格问题上。

规则如何被匹配到变更文件上

规则注入的第一环是「从 diff 找出变更文件，再为每个文件选规则」，全部实现在 crates/atomcode-review/src/rules.rs。

匹配表：精确文件名先于通配扩展名

规则表MATCHERS是一张有序列表（rules.rs#L17-L106），采用「第一个命中者获胜」策略。Markdown 相关的三条是：

("readme*.md", "markdown"), ("*.md", "markdown"), ("*.markdown", "markdown"),

三者指向同一个markdown规则，顺序本身不影响结果；但同表中「精确文件名必须排在通配扩展名之前」是硬性约束——build.gradle、pom.xml、package.json、requirements*.txt等条目全部排在*.json、*.xml、*.toml之前，否则package.json会被泛化的*.json规则抢走。匹配逻辑在 match_rule：取路径的小写基础名（rsplit('/')取最后一段再to_ascii_lowercase），逐条做仅含*通配符的匹配（wildcard_match）。测试 matcher_order_specific_before_generic 固化了这一行为：web/package.json命中package_json而非json，mapper/UserMapper.xml（大写）也能命中mapper_dao_xml，assets/data.bin则无任何规则命中。

完整的规则—文件模式对照表见 LANGUAGES.md，其中 Markdown 一行的模式为readme*.md、*.md、*.markdown。

变更文件从哪来：解析+++ b/<path>行

changed_files_from_diff 从统一 diff 的+++行提取文件路径：去掉b/前缀、跳过/dev/null（纯删除文件）、按首次出现去重。实现与 git 解耦——对 PR diff、CI 产物、stdin 传入的任意统一 diff 文本都适用；测试 files_parsed_from_diff_plus_lines 验证了删除gone.py的 hunk 不会进入结果。

分组渲染：一个规则文档只出现一次，并声明作用域

render_rules_section 把变更文件按命中的规则分组，输出形如：

## Targeted review focus for this batch (each rule applies ONLY to its listed files) ### Applies to: docs/guide.md, README.md [Markdown] This batch contains documentation/README; pay extra attention to: ...

「每条规则只作用于它列出的文件」这一声明是关键设计：一个同时改了 Go、SQL 和文档的批次，评审 Agent 不会把 Go 并发清单套到 SQL 文件上。当没有任何文件命中规则时函数返回空串，调用方什么都不追加。测试 render_groups_scope_files_and_renders_doc_once 验证了三件事：同语言文件归组且文件名全部列出、规则文档只渲染一次、以及纯不匹配输入（a.bin）输出为空。

注入点：规则文本如何进入评审提示词

规则文本最终进入提示词有两条路径，对应评审能力的两种消费方式：

1. 独立 CLIatomcode review：crates/atomcode-cli/src/review.rs 先计算 diff、提取变更文件（L215），在非--no-rules时调用render_rules_section（L217-L234），并把规则段拼进persona_append——引擎注入的语言规则在前，用户的--append-system-prompt内容在后（L356-L360）。组合逻辑由 compose_persona 完成：内置 reviewer persona（或被--system-prompt全量覆盖的文本）为基底，append 段追加在末尾。CLI 还会向 stderr 打印[rules] injected for N changed file(s)，作为规则确实被注入的可观测信号。
2. 宿主内嵌的 code_review 工具：crates/atomcode-review/src/review_tool.rs 在组装任务文本时直接内联规则段，最终格式为「评审指令 +{rules}+ 影响面计划 + 带行号的 diff」，并要求评审者「只标记变更代码中的问题」、通过report_finding上报。

两条路径共用同一组构建函数，deep-mode 设计文档 中也明确这一点：shared task 由「annotated diff + rules + impact plan」组成，不存在并行再实现。

与「低信号文件」的微妙关系

值得注意的一个细节：Markdown 文件同时出现在 is_low_signal_file 的清单里（.md、.markdown、.txt等被判定为低信号）。该函数的注释写明其用途是「impact plan 跳过、CLI coverage 兜底不重审」——因为文档没有可执行逻辑，「零 finding」是预期结果，不值得反复评审或进入影响面分析目标（impact_plan.rs 在两处都调用了它）。

也就是说，系统对文档类文件采取「一次安全审视、不反复纠缠」的策略：

• diff 里出现README.md时，markdown规则照常注入，评审者按文档安全清单检查一遍；
• 但它不会成为影响面计划追踪的目标，coverage 二轮兜底也不会因为「文档文件没有产出 finding」而触发重审（测试 low_signal_file_covers_common_lockfiles 明确README.md、docs/notes.MD、guide.markdown都在低信号之列）。

两者并不矛盾：规则注入保证文档变更被「认真看一次」，低信号判定保证它不会被「看很多遍」。

运行时定制：--rules-dir 热覆盖

markdown.md这类规则文档通过include_str!编译进二进制（RULE_DOCS 中的("markdown", include_str!("../rules/markdown.md"))），但 load_rule_doc 在每次渲染时优先读取--rules-dir下的同名文件：目录里存在且非空的<name>.md覆盖内置版本，缺失的名字回落到编译内版本。因此调整 Markdown 审查口径（比如给团队文档加上额外的合规检查项）不需要重新编译，LANGUAGES.md 给出的标准做法是：

mkdir -p ./my-rules cp crates/atomcode-review/rules/markdown.md ./my-rules/markdown.md # edit ./my-rules/markdown.md atomcode review --rules-dir ./my-rules

对应的 CLI 参数见 review.rs#L85-L93：--rules-dir只做按名覆盖，其余规则继续使用内置版本；--no-rules则完全关闭规则注入，适用于需要干净提示词做 A/B 对比的场景。测试 rules_dir_overrides_builtin 验证了「覆盖生效 + 未覆盖规则回落内置」两种行为。

如果要新增一种语言/文件类型的规则（而非覆盖 Markdown 这条），LANGUAGES.md 给出四步：创建rules/<name>.md、在 rules.rs 的MATCHERS注册文件模式、在RULE_DOCS注册规则文档、运行cargo test -p atomcode-review验证匹配器与文档的一致性——其中一致性由测试 every_matcher_rule_has_a_builtin_doc 强制：任何 matcher 指向的规则名若漏注册文档，测试会直接失败。

小结

• crates/atomcode-review/rules/markdown.md 是 atomcode-review 面向文档类文件的评审规则：只查危险操作指引、配置/供应链误导、测试说明失真这三类会酿成事故的文档问题，措辞与排版明确排除在报告范围之外；
• 规则经有序MATCHERS表（精确文件名优先）匹配到 diff 中的readme*.md/*.md/*.markdown文件，由render_rules_section按规则分组、带作用域声明地渲染一次，再经persona_append（CLI）或任务文本（code_review 工具）进入提示词；
• Markdown 同时被判定为低信号文件：只被审视一次，不进入影响面追踪与 coverage 重审；
• 规则支持--rules-dir运行时按名覆盖、--no-rules完全关闭，调整审查口径无需重新编译。

• 人工智能
• AI Agent
• 代码智能体
• 自主智能体
• MCP Clients
• CLI