用途 本约定用于把技术工作解释给混合受众，即同时包含了解代码与不了解代码的读者。核心要求：读者必须在30秒内理解目的，在2分钟内理解结构；单纯文字通常做不到这一点。若 AGENTS.md 对本主题另有约定，以 AGENTS.md 为准。
主要能力
- 通俗开篇：文档开头写一个短节（规格文档中用 ## TL;DR，拉取请求中用 ## In plain words），面向不了解代码、行话或本次会话的读者。描述效果而非机制，例如写“输错密码太多次后，登录要等一分钟”，而不是写“每 IP 每分钟 5 次请求的限流”。内容覆盖：改了什么、谁使用、能做什么、哪些保持不变、哪些不在本次范围内。形式为一段话，或一句加最多八条要点。不得使用框架名、协议名、缩写和文件名。
- ASCII 表达结构：在 ```text 代码围栏内使用 ASCII 画图，包括文件树（新文件用 + 标记、改动的文件用 ~ 标记，每项后加简短注释）、数据流或流程的前后对比视图、流程时间线（如“spec → plan → build → review”）。
- Mermaid 表达行为：用于会“动”的内容，按需选择图型——请求或任务如何经过各项检查用 flowchart TD；谁与谁以什么顺序交互用 sequenceDiagram；表与关系用 erDiagram；会话、订单或记录的生命周期用 stateDiagram-v2；决策表用带菱形判断节点的 flowchart。每个读者疑问画一张图，不要仅因存在某种图型就加图。
- 渲染兼容的语法规则：含 /、:、(、)、{、?、, 的标签一律加引号，如 A["POST /login"]；换行用 <br/>，不使用其他 HTML；erDiagram 属性类型保持单词简单形式，如 int、string。
- 校验每个 Mermaid 块：交付前逐块渲染。文档中提供了完整命令：先 mkdir -p .scratchpad/mermaid && rm -f .scratchpad/mermaid/*，再用 python3 脚本以正则提取文档中的 ```mermaid 块并写入 .scratchpad/mermaid/d{index}.mmd，然后循环调用 npx -y @mermaid-js/mermaid-cli -q -i "$file" -o "${file%.mmd}.svg"，成功输出 ok，失败输出 FAIL。
- 环境问题处理：若所有文件都失败，通常是渲染器找不到浏览器（常见于容器和云会话），可用 Puppeteer 配置指向已安装的 Chromium，并加 -p .scratchpad/puppeteer.json，配置为 {"executablePath":"<path to chrome>","args":["--no-sandbox"]}。若报 Cannot find package 'puppeteer'，需在同一位置安装 mermaid-cli 与 puppeteer（PUPPETEER_SKIP_DOWNLOAD=1 npm i --prefix .scratchpad/tools @mermaid-js/mermaid-cli puppeteer），把 executablePath 指向已安装的 Chrome，并运行 .scratchpad/tools/node_modules/.bin/mmdc。建议用一个故意写坏的块检查校验器，必须输出 FAIL。没有 Node.js 时，应说明图未渲染，并在发布前于代码托管预览（如 GitHub 或 GitLab 文件视图）中检查。不要把生成的 SVG 读入上下文，文件很大，退出状态即可。
- 忠实性：图只展示代码或规格定义的行为，不得虚构路由、字段或检查。若某细节规格未定义，应省略并作为歧义列给用户。每张图放在它所解释的小节旁，配一行引导语，不要把所有图堆在末尾。图任务适合交给子代理，可用本技能及 scratchpad-working-files 中的子代理规则下达任务。
适用场景 需要向混合受众说明技术变更的规格文档、拉取请求、流程或数据流说明、系统交互与生命周期描述等。
限制 所有 Mermaid 图须经渲染校验；无 Node.js 环境时无法本地校验，只能声明未渲染并在托管预览中人工检查；图内容不得超出代码或规格所定义的范围。