跳转至

SOP — 文档规范修正（skill_rules_fix_20260926）

1. 背景

用户核验发现既有规范导致两类误产出：① SOP 第 5 章被写成 Python 入口命令（.venv/bin/python main.py install），而非与实现体等价的 shell 操作序列，且缺少流程叙述与"坑/注意事项"；② RUNBOOK 判定"长期运行服务时必出"被误判跳过，EDA 安装类交付物无使用手册；③ 全局规则"若项目存在 docs/HANDOFF.md"字面不覆盖新建，新项目首份交接快照无人创建。经 2026-09-26 多轮讨论定稿方案后执行。

2. 目标

  • 第 5 章规范：分步三件套（叙述含坑 + 等价 shell + 预期/失败判断），入口命令调用被显式禁止，有反例与正例对照；
  • RUNBOOK：有可复用交付物即必出，已有则同步更新；
  • HANDOFF：任一触发时点到来、文件不存在即新建；
  • 三文件旧表述零残留。

3. 前置条件

  • 三个目标文件可读可写（/home/rain/.trae-cn/ 下）；
  • 备份已完成：backup/ 下按来源路径层次存放，命名 .bak.20260926-115050，台账见 backup/README.md。

4. 影响范围

  • 文件：~/.trae-cn/skills/writing-ops-change-sop/SKILL.md、~/.trae-cn/skills/writing-handoff/SKILL.md、~/.trae-cn/user_rules/rule-ops-scenario-routing.md；
  • 影响面：全局（后续所有会话的文档产出行为），不涉及任何服务、无需停服、无在跑作业；
  • 生效时机：skill 与 user_rules 每会话加载，下次会话即生效；
  • 成本提示（Hook 通知）：改 skill/全局规则使上游前缀缓存失效（约 0.35 元/次），本轮收尾后应开新会话继续。

5. 分步操作

TS=20260926-115050
BK=/home/rain/Documents/eda_tools_ins/Cadence/skill_rules_fix_20260926/backup/home/rain/.trae-cn

# ① 备份三文件（保留来源路径层次）
mkdir -p "$BK/skills/writing-ops-change-sop" "$BK/skills/writing-handoff" "$BK/user_rules"
cp -p ~/.trae-cn/skills/writing-ops-change-sop/SKILL.md "$BK/skills/writing-ops-change-sop/SKILL.md.bak.$TS"
cp -p ~/.trae-cn/skills/writing-handoff/SKILL.md        "$BK/skills/writing-handoff/SKILL.md.bak.$TS"
cp -p ~/.trae-cn/user_rules/rule-ops-scenario-routing.md "$BK/user_rules/rule-ops-scenario-routing.md.bak.$TS"

# ② 编辑（SearchReplace 共 7 处，见第 6 章验证 diff）
#    writing-ops-change-sop：RUNBOOK 产出行+判定小节 / 八章清单第5条 /
#    第5章小节重写 / 通用禁令 / 示例段反例正例
#    writing-handoff：触发时机补"不存在即新建"
#    rule-ops-scenario-routing.md：交接文件节改"不存在则新建"

# ③ 回读验证
diff -u "$BK/skills/writing-ops-change-sop/SKILL.md.bak.$TS" ~/.trae-cn/skills/writing-ops-change-sop/SKILL.md
diff -u "$BK/skills/writing-handoff/SKILL.md.bak.$TS" ~/.trae-cn/skills/writing-handoff/SKILL.md
diff -u "$BK/user_rules/rule-ops-scenario-routing.md.bak.$TS" ~/.trae-cn/user_rules/rule-ops-scenario-routing.md

预期：三个 diff 均只含上述改动点；旧表述（长期运行的服务、若项目存在、不追求逐行可执行、virsh 示例）零残留。

坑（本次已知）：改 skill 会使前缀缓存失效，属一次性成本，不要反复读改同一 skill 多次；~/.trae-cn 目录巨大（>4 万文件），定位文件用 Grep 定点搜，不用全量 LS。

失败判断：diff 出现预期外差异 → 用备份覆盖回滚（见 backup/README.md），重新编辑。

6. 验证

  • 静态：三文件 diff 与方案一致 + grep 旧表述零匹配（已执行，通过）；
  • 行为验收（关键）：按新规范重写 ic25_install_20260924/docs/SOP.md 第 5 章并补 RUNBOOK，用户只看这两份产出——流程与坑看得懂才算规范改到位，看不懂则回到本 SOP 修正。

7. 回滚

备份位置：skill_rules_fix_20260926/backup/（结构、台账、回滚命令见其 README.md）。 回滚判据：验收（第 6 章行为验收）不通过且无法通过修订规范解决时，执行 README.md 中整体回滚命令，三文件恢复原状。 回滚后验证：diff 各文件与其备份零输出。

8. 风险说明

风险 缓解
规范改动影响后续所有会话的产出 已备份可回滚；行为验收兜底
三文件分属 skill 与 user_rules 两处，改一半造成矛盾 本轮同批修改，diff 逐一验证
前缀缓存失效成本 一次改完，收尾后开新会话（Hook 已提示）

来源：/home/rain/Documents/eda_tools_ins/Cadence/skill_rules_fix_20260926/SOP.md ｜ 最后更新：2026-09-26 11:54（由 build/sync.py 同步，请勿在站点侧修改）