Skip to content

lessons_learned.md

Latest commit

 

History

History
200 lines (133 loc) · 18.7 KB

lessons_learned.md

File metadata and controls

200 lines (133 loc) · 18.7 KB
Raw

Lessons Learned

L1: 路由表分类不互斥

问题: L1 路由表中的分类有重叠，导致同一个 prompt 匹配多个路由目标。 预防: 路由条件应尽量互斥，使用消歧规则处理边界情况。

L2: 叶节点内容太宽泛

问题: 叶节点包含太多不相关的工作流，失去模块化的意义。 预防: 每个叶节点只处理一类连贯的任务，保持单一职责。

L3: 路由可观测性不足

问题: Agent 默认向用户汇报路由中间步骤（"我正在判断你属于哪个模块..."）吵闹，或完全不输出路由信息导致调试困难。 预防: 默认静默执行路由。提供按需开关：用户 prompt 含 "路由调试"/"debug routing"/"路由追踪" 时输出紧凑路由路径 [Route] ROOT → ... → [LEAF]，其他时候不输出。

L4: 上下文忽略

问题: 路由判断只看当前 prompt，忽略对话中已建立的技术栈上下文。 预防: 每个路由节点必须显式要求考虑完整对话历史。

L5: 跨领域工作流遗漏

问题: 用户任务跨越多个模块时，没有机制将多个叶节点组合执行。 预防: ROOT.md 必须包含"如果任务跨越多个类别，并行读取多个叶节点"的指令。

L6: SKILL-TREE.md 映射表不准

问题: 手动估算叶节点数，SKILL-TREE.md 统计表与实际不一致。 预防: 生成映射表后逐条计数，禁止目测估算。

L7: Mode 3 添加新 skill 时遗漏 cross-cutting 更新

问题: 添加新 skill 时只更新了子树和 ROOT.md，没有更新 cross-cutting/SKILL.md 的跨 skill 工作流定义。 预防: Mode 3 步骤 7 现在显式要求更新 cross-cutting/SKILL.md。

L8: 关键词信号缺少分层和深度

问题: ROOT.md 信号表只有高层描述词，缺少领域专有术语；多信号冲突时无优先级。 预防: 信号分 T1（唯一确定词）、T2（领域偏好词）、T3（跨领域通用词）三层。单一子任务路由时高 Tier 覆盖低 Tier；多意图 prompt 必须先拆分子任务，再在每个子任务内部应用优先级。root_template.md 消歧规则包含信号优先级模板。

L9: 共享叶节点指令不完全相同

问题: 将两个 skill 的相似能力合并为 Shared-identical 叶节点，但实际指令细节不同。 预防: 只有指令完全一致才能合并为 Shared-identical。有任何差异则分为 Shared-similar 各自独立叶节点。

L10: 存根问题

问题: 生成 skill-tree 时，叶节点只生成 stub（标题+分类摘要+指向外部文件的链接），而非内联完整数据或指令。单个 stub 导致该能力不可用；多个叶节点同时被 stub 化则导致整条路径断裂、能力域完全不可用。尤其危险的场景是：技能本身不存在于环境中，tree 完全依赖自身内容来指导 agent，此时 stub = 功能缺失。

根源: (1) 生成时没有检查源技能是否存在；(2) "自包含"要求未覆盖所有叶节点；(3) 验证阶段未检测存根模式；(4) 原始 skill 中的参考数据（特征字典、换算表、API 规格等）被拆出为独立叶节点时只做了摘要而非完整迁移。

已制度化: 本问题的预防措施已纳入 references/error_handling.md。错误分级表定义了 Fatal/Degraded/Warning 三级处理策略，自包含规则 禁止存根，Step R4 即时验证在最终验证之前拦截存根模式。

L11: 叶节点指令弱化（边界处理丢失）

问题: 拆分原始 skill 时，叶节点中保留了算法骨架，但弱化了原始 skill 中的关键执行细节（如 boundary clamp 的具体实现、5% tolerance 的 clamp 行为变成了"可选建议"）。原始 skill 说 "acceptable to use a 5% tolerance and clamp values"，拆分后变成 "do NOT clamp unless very slightly outside" —— 语义反转导致边界值未被修复。 预防: 叶节点必须保留原始 skill 中的所有执行级指令（具体代码、阈值、clamp 行为），不能只保留"高层指导"。特别是数值处理逻辑，弱化措辞会导致行为改变。生成时应比对原始 skill 中的每个具体指令是否完整迁移。

L12: Mode 3 添加不同 skill 时未转型 Single-Skill Tree

问题: 初始用 Mode 1 将单个 skill 转为 skill-tree（Single-Skill 结构，ROOT.md 使用 "Step 1: L1 路由"），之后通过 Mode 3 --update --add 添加一个不同的新 skill 时，如果只检测到 Single-Skill Tree 就直接进入 Step C（添加能力到已有 skill），会导致新 skill 被错误地当作已有 skill 的能力增量处理，而非作为独立 skill 子树加入。

根源: Mode 3 的分支逻辑缺失了 "Single-Skill + 不同 skill" 这种情况。Step C 的设计前提是添加能力到同一个 skill，不适用于添加全新 skill。

预防:

  1. Step B 显式判断: Single-Skill Tree 下必须进一步判断 --add 是同一 skill 还是不同 skill
  2. Step D 转型: 不同 skill 时，必须先将 Single-Skill tree 转型为 Multi-Skill tree（Mode 2 结构），再通过 Step E 添加新 skill
  3. 转型保留完整性: 转型过程保持所有现有叶节点内容和路由逻辑不变，仅调整目录结构和 ROOT.md 格式

L13: Step D 转型后未删除原 Single-Skill 顶级模块目录

问题: Single-Skill tree 转型为 Multi-Skill tree 时，将原顶级模块目录（charts/、interactivity/ 等）移入 {existing-skill}/ 子目录后，未显式删除树根目录下的原模块目录。结果树中存在两套并行的模块文件——一套在 {existing-skill}/ 下（Multi-Skill 路由目标），一套在树根目录下（孤儿文件，不被任何路由引用）。不仅造成混乱，还可能导致 agent 误读孤儿文件而绕过正确的 Phase 1 路由。

根源: Step D 的 "move" 步骤在实践中可能被执行为 "copy"（尤其当目标子目录已存在时），缺少显式的删除原目录步骤。

预防:

  1. Step D 步骤 8 显式删除: 转换完成后，必须删除树根目录下的原模块目录（{module1}/、{module2}/ 等）
  2. 验证检测: Check 3 (Reachability) 会标记所有孤儿文件，转型后必须无孤儿文件
  3. 删除前确认: 在删除前确认 {existing-skill}/ 子目录下的对应文件已完整迁移

L14: 引用文件未内联/拷贝导致叶节点依赖外部源技能

问题: 源技能中引用了外部文件（如 docs/、references/、scripts/），生成器在叶节点中保留了指向源技能目录的外部路径（如 .claude/skills/xxx/docs/...），而不是将内容内联或拷贝到 tree 内。导致：

  • 删除源技能后 tree 中的检索/参考路径全部失效
  • tree 不是真正自包含的，违反了 自包含规则

根源: 生成器对所有引用一视同仁——没有区分"可内联的短内容"和"应拷贝的大文件集"。对于 docs/ 这类大量文件，简单地保留了外部路径引用。

已制度化: 本问题的预防措施已纳入 references/error_handling.md 的 Reference File Processing Flow。Step R1-R4 定义了量化标准（≤200行/≤10KB 内联，>5文件/>50KB 拷贝）和即时验证步骤。

L15: 叶节点中"参考文档索引"段落未做路径替换或删除

问题: 叶节点生成后，从源技能复制过来的"参考文档索引"/"Reference Documents"段落仍保留了指向源技能 references/ 目录的原始路径。这些文件在复制包中往往不存在，删除源技能后这些路径完全失效。更严重的是，这些段落给 agent 造成"还有更多详细信息在外部"的错觉，实际内容已经在叶节点中内联完毕。

根源: 生成器在拆分源技能内容到叶节点时，将"参考文档索引"段落原样复制，没有执行路径替换（指向 tree 内部副本）或删除（引用文件不存在）的决策。

L16: Multi-Skill 多意图 prompt 被单一路径优先级吞并

问题: Multi-Skill ROOT.md 只表达 "Phase 1 选 Skill"，在 prompt 同时包含多个 skill 名称、多个唯一领域词或多个可分解子任务时，agent 容易按最高优先级信号只选择一个 skill，导致其他明确意图的路径丢失。

根源: 信号优先级规则被用于整个 prompt，而不是先拆分子任务后在每个子任务内部消歧；Mode 3 更新 ROOT.md 时也可能只新增单个 skill route 和消歧规则，没有补充多意图保留规则。

预防:

  1. Multi-Skill ROOT.md 必须写成 "Phase 1 选一个或多个 Skill"，并包含多意图路由规则
  2. 多意图 prompt 先拆分子任务，再分别应用 P1/P2/P3 优先级
  3. Mode 3 添加新 skill 或 Single-Skill 转型时，必须同步更新多意图路由规则，确保新旧 skill 可在同一 prompt 中同时命中
  4. Validation Check M5 必须构造多意图测试，验证不得只返回单个最高优先级路径

L17: 关键词信号停留在技术实现视角

问题: ROOT.md/ROUTER.md 的信号只从源 skill 的技术文档提取，例如 API 名、产品名、内部术语或目录名。用户用自然语言描述功能需求、业务目标或可见结果时，路由无法召回正确 skill。

根源: 生成流程把 source skill 的实现词当成用户触发词，缺少从任务对象、用户动作、功能场景、期望结果等维度做用户视角扩展。

预防:

  1. ROOT.md 和 ROUTER.md 的每条非 fallback 路由至少包含一个用户会说的自然语言信号
  2. 技术名词、产品名、API 名和 skill 名只能作为补充，不能作为唯一信号，除非该 skill 只能按精确名称调用
  3. 生成 ROOT.md 前必须执行 root_template.md 的 Pre-Write Routing Signal Preparation
  4. Validation Check 8A 必须检查自然语言信号覆盖

L18: 常见用户动作词在有能力的域中覆盖不均

问题: 某些动作词在部分域有路由行，在同样具备该能力的域中缺失。例如某些 tree 覆盖“生成图片/视频/摘要”，却漏掉“生成网页/页面/工具”一类用户表达。

根源: 生成时按 skill 名称或技术分类逐行写路由，没有反向检查“用户动作词 → 可处理域”的覆盖。

预防:

  1. 生成 ROOT.md 后列出高频用户动作词，如生成、制作、创建、查找、搜索、分析、转换、部署
  2. 只对确实具备对应能力的域检查覆盖，不做全域笛卡尔积扩张
  3. 缺失时补充用户动作 + 任务对象组合信号，例如“生成网页”“制作表格”“转换 PDF”
  4. 对没有明确能力归属的动作词，不硬编码路由，改为询问用户或记录 [待补充]

L19: 元查询意图与执行意图混淆

问题: 用户说“找个能做 XX 的技能”“有没有 XX 技能”时，agent 把 XX 当作执行意图路由到执行 skill，而不是识别整体意图为 skill discovery。

根源: 路由表只看能力词，不识别“找/推荐/安装技能”对能力词的包裹关系，也没有定义元查询和执行意图的边界。

预防:

  1. 如果 tree 中存在 skill discovery / find-skills 能力，ROOT.md 必须包含元查询消歧规则
  2. “找/推荐/安装一个能做 XX 的技能”默认路由到 discovery skill，XX 作为查询参数
  3. 只有用户同时要求“现在处理/转换/执行”并给出具体文件、对象或任务时，才并行保留执行路由
  4. Validation Check 8B 必须包含纯找技能、纯执行、找技能+具体执行对象三类测试

L20: 路由协议假设关键词穷举匹配

问题: 生成的 ROOT.md/ROUTER.md 容易让 agent 把关键词列当作必须字面命中的穷举清单。用户使用同义词、口语、拆分式表达或业务目标描述时，路由失败或进入兜底。

根源: 模板没有足够明确地声明“语义匹配”和“代表性关键词信号”，导致 LLM 采取机械匹配策略。

预防:

  1. ROOT.md 模板必须声明：基于完整对话历史和当前 prompt 语义理解用户目标，而非机械匹配关键词
  2. 表头使用“代表性关键词信号”，并说明这些信号是召回示例，不是穷举清单
  3. ROUTER.md 模板同样要求代表性信号用于语义召回
  4. Validation Check 8A 必须验证语义匹配指令存在

L21: 嵌套 skill 转入聚合树后的入口/重复文件问题

问题: 源 skill 本身是 index/路由型（其目录下有 ≥2 个子技能各含 SKILL.md，自身 SKILL.md 主要职责是路由）。聚合时若把源 SKILL.md 整体转为 {skill}/ROUTER.md，会导致该 skill 子目录只剩 ROUTER.md 而无 SKILL.md，外部 skill 扫描器误判为损坏 skill；反之若已用 SKILL.md 承载路由又额外建 ROUTER.md，会出现两个重复路由文件。

根源: Mode 2 的标准结构是 {skill}/ROUTER.md + {skill}/{capability}/SKILL.md，领域级容器目录本来只有 ROUTER.md 无 SKILL.md（正常）。但对应真实源 skill 的嵌套型目录需要明确「这是 skill 还是纯领域容器」，且承载路由的方式有两种，不能混用。

预防:

  1. 生成前用 Glob 扫源 skill 目录 src/<skill>/*/SKILL.md，命中 ≥2 个即判定为嵌套 skill，在 GENERATION-REPORT.md 记录。
  2. 嵌套 skill 转入聚合树时二选一（不得混用）：
    • 方式 A（路由分离型）：源路由迁入 {skill}/ROUTER.md + 额外补 {skill}/SKILL.md 入口元数据（frontmatter + [NESTED SKILL SUBTREE ENTRY] + 指向 ROUTER 的指针 + 子技能清单）。上游父 ROUTER 指向 ./{skill}/ROUTER.md。
    • 方式 B（路由内嵌型，忠于源 index skill 形态）：路由表 + 全局约束直接承载在 {skill}/SKILL.md（标 [Ln ROUTING NODE] [NESTED SKILL SUBTREE]），不另设 ROUTER.md。上游父 ROUTER 指向 ./{skill}/SKILL.md。
  3. 聚合树的领域级容器目录（media-creation/document-processing 等）保持「纯路由容器」即只有 ROUTER.md 无 SKILL.md，但必须在 SKILL-TREE.md「节点类型声明」段显式标注，避免与嵌套 skill 混淆。
  4. Validation 增加 Check 3.1：含 ROUTER.md 的目录要么有入口 SKILL.md（方式 A），要么声明为纯路由容器（领域级）；嵌套 skill 目录不得同时存在承载路由的 ROUTER.md 和承载路由的 SKILL.md（多余文件删除）；上游父 ROUTER 路由目标必须指向实际承载路由的文件。
  5. 已制度化到 references/error_handling.md 的「Nested Skill Detection」段 + references/validation_template.md Check 3.1。

L22: 嵌套 skill 误选方式 A，为「路由表+入口」一体源文件制造多余 ROUTER.md

问题: 生成聚合树时，对嵌套/index skill（如 xiaoyi-health，源 SKILL.md 本身就是「路由表 + 入口/使用说明 + 全局规范」的一体文件），误选方式 A（路由分离型）：额外建了 {skill}/ROUTER.md 承载路由表，又留 {skill}/SKILL.md 作入口元数据。结果一个源一体文件被拆成两个文件，ROUTER.md 与源一体结构不符，且 SKILL.md 退化成只指向 ROUTER 的指针。

根源: error_handling.md Nested Skill Detection 原文方式 B 的触发条件写成「当源 SKILL.md 本身就是『带路由表 + 入口』的一体文件时」，但没给判定方法、没标默认首选。方式 A 列在前面，生成器看到源含路由表就倾向方式 A，未识别源文件已是「路由+入口」一体（方式 B 适用前提）。

预防:

  1. 方式 A/B 判定写明可执行标准：读完源 SKILL.md 全文——含「路由表 + 入口/使用说明 + 全局约束」同一文件 → 方式 B（默认首选）；仅路由表无入口性内容 → 方式 A。
  2. 明示「禁止凭『含路由表』就选方式 A」：含路由表 ≠ 纯路由文件。源文件同时含入口/使用说明/全局规范即属方式 B 的一体文件，不应拆出 ROUTER.md。
  3. 已制度化到 references/error_handling.md Nested Skill Detection 第 2 条「方式 A/B 判定标准（防误选）」+ validation_template.md Check 3.1。

L23: Check M0 误把单叶 skill 纳入「必须有 ROUTER.md」检查，生成指向自己的冗余 ROUTER

问题: validation_template.md Check M0 原文「对每个非 shared、非 cross-cutting 的 skill 子树，确认存在 {skill}/ROUTER.md」被生成器理解为「每个 skill 都要有 ROUTER.md」，于是为 17 个单叶 skill（1 源 → 1 叶，无内部分流）各生成一个仅一行 Read ./SKILL.md 的 ROUTER.md——指向自己，无任何分流决策，纯属冗余。

根源: Check M0 没区分「需要 Phase 2 分流的 skill」与「单叶 skill」。M0 的真实意图是「命中 skill 后能追踪到 leaf」，单叶 skill 由 ROOT 直接路由到唯一 leaf 即满足，不需要 ROUTER.md。把单叶 skill 也算进 M0 范围，等于强制生成自指向 ROUTER，违背「单叶无分流」的事实。

预防:

  1. Check M0 明确适用范围：仅对需要 Phase 2 能力分流的 skill 子树（≥2 并列能力/子叶）检查。单叶 skill 不适用，不要求也不应有 ROUTER.md。
  2. 明示「禁止要求单叶 skill 自带指向自己的 ROUTER.md」；若发现单叶 skill 有仅 ./SKILL.md 一行的 ROUTER.md，应删除（冗余文件）。
  3. 承认方式 B：分流 skill 的 Phase 2 路由可承载在 {skill}/SKILL.md 内（方式 B），不一定非得是 ROUTER.md。
  4. 已制度化到 references/validation_template.md Check M0 + references/overview_template.md 三种 skill 子树形态 + SKILL.md Mode 2 Step C1。

L24: Mode 2 聚合缺少 per-skill 能力拆解，复杂 skill 被当单叶处理

问题: Mode 2 Step A 只要求「独立分析并提取能力」然后建比较矩阵，没有像 Mode 1 Step 1 那样对每个 skill 做结构化的能力拆解（core domains → sub-domains → leaf capabilities → routing criteria）。结果是：大部分 skill 被 1:1 直接映射为单叶节点，即使该 skill 内部包含多个可独立路由的能力组（如脚本编写、拍摄、剪辑、发布等），也没有被拆分为多叶结构。

根源: Mode 1 有显式的分析步骤（识别核心域/子域/叶能力/路由信号），Mode 2 Step A 缺少等价的 per-skill 拆解步骤。Nested Skill Detection 只检测物理目录结构（子目录里有 SKILL.md），无法识别「单文件但内含多能力」的情况。

预防:

  1. Mode 2 Step A 拆为 A1（per-skill 能力拆解，与 Mode 1 Step 1 等价）+ A2（跨 skill 比较矩阵）
  2. A1 必须为每个 skill 输出 decomposition decision：单叶（功能单一）或多叶（≥2 个可独立路由的能力组）
  3. Step C1 综合 A1 判定和 Nested Skill Detection 两个来源决定 skill 形态
  4. A1 判定为「多叶」但源为单文件时，Step C2 按「拆分型叶节点」规则生成多子叶
  5. GENERATION-REPORT.md 必须记录每个 skill 的 decomposition decision 和理由