13.6 案例：同一工作流的三层诊断

面向经管学生、研究者与从业者的 AI 智能体设计教材

13.6 配图

这一节把任务级、Skill 级和系统级评估放进同一个工作流，展示同一个失败现象落在不同层级时，处理动作会怎样变化。

案例场景：章节重构工作流

假设你需要把教材的旧章节重构为新版本。工作流的输入和输出如下：

输入：旧章大纲、参考素材、统一写作模板、交付约束（字数、格式、术语标准）。

输出：新章的 index.qmd（章首页）、若干 section-N-X.qmd（各小节）、summary.qmd（章节小结）。

这个工作流包含读取素材、生成大纲、分节撰写、格式检查、提交版本等环节。最终交付物不合格时，问题可能出在三个层面中的任何一个。

任务级：这一轮交付有没有达标

第一步先做任务级检查，不管 Skill 怎么配置、代理怎么分工，先看这一轮产出的文件本身是否满足要求。

验收清单：

检查项	通过条件	检查方式
文件完整性	所有必需 qmd 文件都存在	代码判分
YAML 格式	每个文件有正确的 title 字段	代码判分
术语规范	Agent 译为智能体，Prompt Chaining 译为提示链	代码判分
章节结构	每节有三级标题、callout、一句话总结	LLM 判分
内容覆盖	大纲中的每个要点都有对应内容	LLM 判分

def check_chapter_deliverable(chapter_dir: str) -> dict:
    """检查章节交付物的完整性"""
    import os
    results = {}
    # 检查必需文件
    required = ["index.qmd", "summary.qmd"]
    for f in required:
        results[f] = os.path.exists(os.path.join(chapter_dir, f))
    # 检查 section 文件数量
    sections = [f for f in os.listdir(chapter_dir)
                if f.startswith("section-") and f.endswith(".qmd")]
    results["has_sections"] = len(sections) >= 3
    results["pass"] = all(results.values())
    return results

假设检查发现：summary.qmd 存在但内容为空，section-13-3.qmd 缺少一句话总结。

任务级归因：这是单次执行的输出问题，优先检查：

1. 任务描述是否明确要求每节末尾补上一句话总结？如果没有写明，模型通常不会自动补全
2. summary.qmd 的写作指令是否提供了模板？如果只写“写一个小结”而没有指定内容框架，输出就容易失稳

处理动作：修改任务说明。在写作指令中明确“每节末尾必须有一句话总结”，并在 summary.qmd 的写作要求中补上结构模板。

Skill 级：大纲生成 Skill 为什么时好时坏

任务级修复后，同一个 Skill 在不同章节上运行，有时能产出完整大纲，包含案例分层、状态记录和交付约束；有时只给出粗略的目录框架。

这时问题已经不在单次执行，而在封装稳定性。

检查步骤：

第一步：触发检查。 用不同的请求表述测试大纲生成 Skill 的触发情况。

▶ Claude Code

请分别用以下 6 种表述调用大纲生成功能，记录是否正确触发了"章节大纲生成" Skill：

1. 帮我写这一章的大纲
2. 生成当前主题章节的结构
3. 列出这一章应该有哪些小节
4. 请规划当前章节的内容框架
5. 帮我做一个章节大纲
6. 重构这一章

结果发现，表述 3 和 6 没有触发 Skill，因为 description 里只包含“大纲”“生成”等关键词，没有覆盖“列出”“重构”等同义表达。

第二步：输出骨架对比。 用 5 个不同章节分别运行大纲生成 Skill，对比输出结构。

运行	章节数	案例设计	写作约束	状态记录
样例 A	6 节	有	有	有
样例 B	6 节	有	缺失	有
样例 C	5 节	缺失	缺失	缺失
样例 D	6 节	有	有	有
样例 E	6 节	有	有	缺失

样例 C 的输出明显不稳定，缺少案例设计、写作约束和状态记录这三个模块。

Skill 级归因：参考文件 supporting files 没有强制要求输出这三个模块。Skill 的执行步骤只写了“生成章节大纲”，没有规定必须包含哪些固定模块。

处理动作：修改 Skill 的参考文件和执行步骤。在参考文件中加入大纲输出模板，明确每个大纲都要包含“节次安排、案例设计、写作约束、状态记录”四个板块，并在执行步骤中补上格式校验环节。

系统级：多章节并行重构为什么会越跑越乱

Skill 级修复后，单章重构的质量稳定下来。但多个章节同时重构时，又出现了新的问题：

• 不同章节使用了不同的术语标准（一个用”子代理”，一个用”sub-agent”）
• 某一章更新了 Hook 的事件命名规范，但另一章的案例还在引用旧命名
• 修复一处 Git 流程描述后，其他章节里的相关内容反而变得不一致

这些问题有一个共同点：单独看每一章都没有错，放在一起却互相矛盾。

系统级归因可以按优先级排查：

检查项	发现的问题	修改动作
代理分工	多章并行时没有统一的术语仲裁机制	在 CLAUDE.md 中维护术语表，要求所有代理读取
Hooks 门禁	没有跨章术语一致性检查	在提交前 Hook 中加入术语扫描脚本
Git 基线	没有在每轮修改后更新回归测试集	每章通过评审后，把该章的术语和格式加入回归检查项
经验写回	发现的跨章问题没有写回下一轮	在 lessons 文件中记录”术语不一致”类问题及处理方式

处理动作：修改系统机制，而不是逐章修补。具体包括：

1. 在 CLAUDE.md 中新增术语对照表，作为所有写作代理的强制参考
2. 在 pre-commit Hook 中加入术语一致性扫描
3. 建立跨章回归检查清单，每轮修改后运行
4. 把本次发现的”术语不一致”问题模式写入 lessons，供后续重构参考

同一问题，三层不同的处理

把三层放在一起看，同一个“最终输出不合格”的现象，在不同层级对应的定位和处理并不相同：

层级	看到的现象	归因	处理动作
任务级	某一节缺少一句话总结	任务说明没有要求	修改写作指令
Skill 级	不同章节的大纲结构不一致	参考文件没有固定模板	修改 Skill 的参考文件和执行步骤
系统级	多章术语标准不统一	缺少跨章协调机制	修改 CLAUDE.md、Hook、回归集

实用建议

遇到输出不合格时，先做任务级检查。修改任务说明后问题消失，就不用继续上移；同类问题在不同输入上反复出现，再升级到 Skill 级；单个 Skill 已经稳定，多组件协作仍有问题，再进入系统级排查。逐层升级，不要一开始就改系统。

本节一句话总结： 三层案例说明，同一个失败现象落在不同层级时，改动的位点和方式并不相同。