CLAUDE.md 最佳实践：Mermaid 用于工作流

Source: Dev.to

“一图胜千言。”
我想看到我的系统——不是代码，而是驱动它的工作流。
当规则被验证时会发生什么？会话开始时会怎样？压缩触发时会怎样？

仅使用散文的工作流问题

• 可读性在经过几次分支后会崩溃。
• 几周后返回时，需要对密集的段落进行完整的重新解析。
• 大语言模型会出现 “中段丢失” 效应：它们能很好地处理上下文的开头和结尾信息，但在中间埋藏的关键逻辑上会挣扎。
• 漂移：删除或重命名管道阶段时，散文中常常留下陈旧的引用，悄然破坏流程。

解决方案：Mermaid 流程图

我将工作流改写为 Mermaid 图表，并观察到三个立竿见影的好处：

1. 即时可视化地图 – 渲染后的图表提供了系统的一目了然的概览。
2. 更高的 LLM 可信度 – 结构化语法在充满散文的上下文窗口中格外突出，使 Claude（以及其他代理）能够更可靠地遵循步骤。
3. 自我维护 – 不可能出现悬空的箭头；缺失的步骤会一目了然。

%% Example placeholder – replace with your actual diagram
graph TD
    A[Start] --> B{Rule validated?}
    B -- Yes --> C[Proceed]
    B -- No --> D[Log error]
    D --> E[Notify user]
    C --> F[End]

支持性研究

FlowBench (Xiao et al., EMNLP 2024) 评估了在三种不同格式下呈现相同工作流知识的 LLM 代理表现：

要点： 格式很重要——结构化图表显著提升代理遵循指令的能力。

何时使用图表 vs. 文字

经验法则： 如果有分支，就需要图表；如果需要判断，就加入文字。

示例：规则验证工作流（仅文字）

以下是我在切换为图表之前的规则验证工作流的原始文字描述。

[在此插入原始散文]

下一步

1. 将现有的散文工作流转换为 Mermaid 图表。
2. 将图表与简洁的散文配对，以提供任何判断或上下文说明。
3. 对 .md 文件和生成的图表进行版本控制，以保持同步。

通过可视化系统，你可以获得更清晰的思维模型，减少 LLM 错误，并让你的工作流随时间不“腐烂”。

规则验证

对 所有 规则进行验证。对于每个规则：

1. 模式验证 – 检查字段、类型和格式。
2. 合约验证 – 确保 .md 和 .yml 文件匹配。
3. 模板解析 – 替换任何模板变量。
4. OpenGrep 验证 – 测试模式语法。

• 如果 OpenGrep 以 2 或 7 退出，则视为失败并报告错误。
• 如果它以 0 或 1 退出，则规则通过。

在每个规则处理完毕后，输出结果摘要。

流程图（Mermaid）

flowchart TD
    START([/validate-rules options]) --> COLLECT[Collect rules from paths]
    COLLECT --> LOOP[For each rule]
    LOOP --> SCHEMA[1. Schema validation\nFields, types, format]
    SCHEMA -->|fail| REPORT
    SCHEMA -->|pass| CONTRACT[2. Contract validation\n.md and .yml matching]
    CONTRACT -->|fail| REPORT
    CONTRACT -->|pass| RESOLVE[3. Resolve template variables]
    RESOLVE --> OPENGREP[4. OpenGrep validation\nPattern syntax]
    OPENGREP -->|exit 2 or 7| REPORT
    OPENGREP -->|exit 0 or 1| REPORT[Report results]
    REPORT --> NEXT{More rules?}
    NEXT -->|yes| LOOP
    NEXT -->|no| SUMMARY[Summary output]

结果

流程图将每个分支明确展示，并显示每条失败路径，从而避免任何内容被无意跳过或误解（例如，哪些 OpenGrep 退出代码算作失败）。

示例工作流

以下是实际工作流文件（rule‑validation.md）在 Reporails 项目中使用的精简摘录。它演示了如何将上述步骤与其他格式（例如 YAML 片段、Shell 命令）结合，创建完整、可复现的验证流水线。

# rule-validation.md

# (workflow content goes here)

Source: …

工作流概览

验证 rules/ 中的所有规则定义是否符合官方模式和合同。

步骤

1. 收集规则

   # Find all rule files and store the list in a temporary file
   find rules/ -name "*.yml" > rule-list.txt

2. 模式验证

   # Validate each rule file against a basic yamllint configuration
   while read -r file; do
       yamllint -d "{extends: default, rules: {line-length: {max: 120}}}" "$file" \
           || echo "Schema error in $file"
   done < rule-list.txt

3. OpenGrep 验证

   # Run OpenGrep against the resolved pattern file
   opengrep -p pattern.resolved.yml
   case $? in
       0|1) echo "Pattern OK" ;;
       2|7) echo "Pattern error" ;;
       *)   echo "Unexpected exit code: $?" ;;
   esac

4. 汇总

   echo "Validation complete – see logs for details."

通过 组合：

• Markdown 用于文档编写，
• YAML 用于数据表示，
• Shell 代码片段 用于执行，
• Mermaid（可选）用于可视化流程，

工作流保持 人类可读 与 机器可执行 两者兼顾。这种多格式的方法正是 FlowBench 认定的传达复杂验证逻辑的最有效方式。

flowchart TD
    A[Collect rules] --> B[Schema validation]
    B --> C[OpenGrep validation]
    C --> D[Summary]

规则验证工作流

flowchart TD
    START([/validate-rules options]) --> COLLECT[Collect rules from paths]
    COLLECT --> LOOP[For each rule]
    LOOP --> SCHEMA[1. Schema validation<br/>Fields, types, format]
    SCHEMA -->|fail| REPORT
    SCHEMA -->|pass| CONTRACT[2. Contract validation<br/>.md and .yml matching]
    CONTRACT -->|fail| REPORT
    CONTRACT -->|pass| RESOLVE[Resolve template variables]
    RESOLVE --> OPENGREP[3. OpenGrep validation<br/>Pattern syntax]
    OPENGREP -->|exit 2 or 7| REPORT
    OPENGREP -->|exit 0 or 1| REPORT[Report results]
    REPORT --> NEXT{More rules?}
    NEXT -->|yes| LOOP
    NEXT -->|no| SUMMARY[Summary output]

• START – 入口点（使用选项的 /validate-rules）。
• COLLECT – 从提供的路径收集规则文件。
• LOOP – 对每个发现的规则进行迭代。
• SCHEMA – 验证规则的 JSON/YAML 架构（字段名、数据类型、格式）。
  • 失败时 → REPORT。
  • 成功时 → CONTRACT。
• CONTRACT – 确保规则的 .md 文档与其 .yml 定义匹配。
  • 失败时 → REPORT。
  • 成功时 → RESOLVE。
• RESOLVE – 替换规则中的模板变量。
• OPENGREP – 运行 OpenGrep 模式检查。
  • 退出码 2 或 7 → REPORT（错误）。
  • 退出码 0 或 1 → REPORT（结果）。
• REPORT – 输出当前规则的验证结果。
• NEXT – 判断是否还有剩余规则：
  • 是 → 返回 LOOP。
  • 否 → 继续 SUMMARY。
• SUMMARY – 生成所有验证结果的最终汇总。

为什么按此顺序使用三层

flowchart TD
    A[Schema validation] -->|passes| B[Contract validation]
    B -->|passes| C[OpenGrep validation]
    A -->|fails| D[Stop processing]
    B -->|fails| D
    C -->|fails| D
    style A fill:#e0f7fa,stroke:#006064,stroke-width:2px
    style B fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style C fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style D fill:#ffebee,stroke:#b71c1c,stroke-width:2px

原理

1. Schema validation – 最便宜的检查。它仅检查文件的结构（缺少字段、类型错误），且没有外部依赖。它过滤掉会导致下游混乱失败的规则。

2. Contract validation – 在文件结构正确后执行。它验证 rule.md 与 rule.yml 是否一致，捕获其中一个文件已更新而另一个未更新的错误。

3. OpenGrep validation – 最耗费资源的步骤。它对语法检查器运行实际模式，需要模板解析、文件 I/O 和 agent‑config 加载。仅在已经通过前两层的规则上执行。

排序遵循 “先便宜后昂贵” 的原则。每一层都依赖前一层的干净状态，确保管道可预测且高效。