automation-distill-zh

name	automation-distill-zh
description	端到端自动化提炼方法论, 把重复流程蒸馏为可复用自动化。三阶段: 挖掘对话和代码库的重复模式 → 实施项目内自动化 → 提取跨项目通用模板 (含脱敏与参数化)。触发条件: 用户提到识别重复操作、构建可复用自动化、提取通用模板、找出可自动化的环节、流程蒸馏、问"项目里什么能自动化", 或想 review/退役已有自动化。中文版。

Automation Distill (中文)

三阶段方法论: 挖掘 → 实施 → 通用化。

每阶段产出独立交付物作为下一阶段输入。如果项目规模不值得深做, 任一阶段都可停。

核心术语: 工作流轮次 (workflow cycle)

工作流轮次 = 项目主流程的一次完整端到端迭代 (例: 训一个模型 + 评估 + 报告 = 一轮; 处理一批数据 + ship = 一轮)。各项目自定义轮次边界。

本方法论以轮次计数 (而非日历时间) 为时间锚。理由: 项目节奏差异巨大, 用轮次自动 normalize 自动化的真实价值。

何时调用

• 项目经过 ≥ 3 轮工作流, 出现相似操作重复
• 用户察觉"我一直在做 X"
• 新项目启动想继承旧项目自动化
• 周期 review (每几个轮次): 审计已有自动化的衰减/退役

何时不要自动化 (战略层防御)

信号	跳过原因
每次实例差异显著	自动化锁死创造性, 过早结构化
重复本身就是思考时间	自动化掉了反思, 决策质量下降
累计 < 5 次 且 单次成本 < 2min	构建成本超过全生命周期节省
一次性项目 / 无复用窗口	没有摊销空间
输出需要不可替代的人类判断	自动化降质
重复是架构问题的症状	应修根因, 不是包装症状

量化阈值

频率用"重复信号"表达, 不用日历速率:

Tier	重复信号	处理
P0	每轮工作流出现 ≥ 3 次, 或 transcripts 累计 ≥ 20 次, 或跨 ≥ 5 个独立 session	立即做
P1	每轮工作流出现 ≥ 1 次, 或累计 ≥ 10 次, 或跨 ≥ 3 个 session	下一轮
P2	跨轮次偶发, 累计 ≥ 5 次	有余力再做
Skip	累计 < 3 次, 或一次性, 或单次成本 < 2min	手动

计数规则: 数 transcripts 实际调用次数, 非估算。 成本规则: 从操作开始到验证完成的中位 wall-clock。

决策树

观察到: 重复操作
  ├─ 命中战略层 veto?       → 停, 记录原因
  ├─ Tier = Skip?            → 停, 保持手动
  ├─ 同步 + < 1s + 事件触发  → Hook
  ├─ 多步 + 显式调用         → Subagent
  ├─ 跨项目方法论 + 可复用   → Skill
  ├─ User 纠正或持久规则     → Memory 文件
  └─ 会话起始需项目状态      → SessionStart hook

Stage 1: 挖掘 — 识别重复模式

输入

• 对话历史 / session 记录 (能看的都看)
• 项目产物 (脚本/文档/配置)
• 用户痛点

步骤

1. 扫描 transcripts, 找重复 ≥ 3 次的操作
2. 抽象动作 → 模式 (是"做什么"而非"怎么做")
3. 按通用类别归类 (见 catalog)
4. 数累计次数 / 独立 session 数 / 每轮频次 → 分 tier

通用模式分类表

模式	本质	Claude Code 机制
状态查询	"现在到哪了" — 长跑任务、跨会话	SessionStart hook + monitor subagent
模板派生	从已有产物参数化克隆	Skill + sed/template
一致性同步	一处变多处跟变	PostToolUse hook
不变量校验	复杂结构默认有错, 必须显式验证	Pre/PostToolUse hook + assertion lib
决策辅助	数据 + 呈现, 决策保留 user	仅 Subagent
根因调查	异常 → 假设 → 修复 → 沉淀 invariant	Subagent + assertion 库
跨版本可比性	单变量设计前置, 不事后救火	Skill + 设计 checklist
数据血缘	多版本派生 trace	Skill + provenance graph
嵌入式知识	User 纠正变持久规则	Memory + reflexive hook

验证

• 每个模式条目附 ≥ 3 个真实 transcript 实例
• Tier 分配以实际计数为依据, 不靠估算
• 没有清晰机制映射的模式 → 标记, 不强凑

交付物

analysis/repetitive_patterns.md: 模式 catalog + 频次 + 每条 ROI tier。

Stage 2: 实施 — 项目内自动化

输入

Stage 1 catalog, 按 tier 排序。

步骤

1. 按决策树为每个 P0/P1 模式映射机制
2. 先做 P0
3. 项目特定路径/约定先硬编码
4. 每个产物独立验证再集成

交付物

• .claude/hooks/ — 事件触发脚本
• .claude/agents/ — Subagent 定义
• .claude/skills/ — 项目内 skill
• .claude/settings.json — Hook 注册 (增量改, jq -e 验证)
• Memory 文件 — User 纠正沉淀

验证 (每个产物)

产物	Smoke test
Hook	加 sentinel echo "$(date) fired" >> .claude/logs/hook-trace.log, 触发匹配 tool, tail 日志
Subagent	合成符合 frontmatter 的输入, 验证输出 schema
Skill	开新会话, 提及触发关键词, 观察是否在 skill 列表中浮现
Memory	后续 prompt 引用, 验证行为符合规则

故障模式:

• Hook silent fail: jq -e '.hooks' .claude/settings.json 必须 exit 0; 查 stderr 日志
• Skill 不触发: description 缺用户实际措辞 → 重读 transcript, 扩 trigger 关键词
• Subagent 超时: prompt 太开放 → 加输出 schema + 字数上限

Stage 3 前的验证门

• 经过 ≥ 3 轮完整工作流真实使用
• Sentinel 日志显示实际调用次数与估算 ±2× 内
• 已有 workflow 无 silent regression

Stage 3: 通用化 — 跨项目抽取

输入

Stage 2 经过 ≥ 3 轮工作流, 或 ≥ 2 个不同子任务真实使用考验的产物。

步骤

1. 通用度评分 每个产物:

   • 数项目特定术语 (路径/名字/行话)
   • 密度 > 60% → 舍弃; 20-60% → 参数化; < 20% → 保留原样

2. 脱敏:

   • 移除硬编码路径
   • 项目/用户/数据集名称替换为占位符
   • 扫描意外 PII: 用户名、内部主机名、密钥
   • 兜底: grep -rE '(/home/|/Users/|@.*\.com|192\.168|api[_-]?key)' <artifact>

3. 参数化:

   • Hook: 用 env vars 传路径/正则
   • Skill: 用 prompt 参数传上下文
   • Subagent: frontmatter 显式声明输入字段

4. 抽象:

   • 把具体步骤换为流程阶段
   • 描述阶段达成"什么", 不写"怎么做"

5. 重命名:

   • 动词-名词通用命名
   • 避免领域绑定

6. 边界明确:

   • 每个产物输入/输出显式定义
   • 跨产物用名字引用, 不用路径

验证

• 在第二个项目 (真实或 scratch) 装载模板
• 在新环境跑 Stage 2 的 smoke test
• 任一失败 → 参数化不完整, 迭代

交付物

automation_universal/ 含脱敏 + 参数化的模板 + README 说明安装/smoke-test 路径。

Stage 3 跳过条件

• 产物未经 ≥ 3 轮考验
• 领域价值太高, 抽象后失去意义
• 用户无跨项目复用打算

冲突处理

冲突	解决
多 hook 同事件	合并到一个 orchestrator 脚本; 或 settings.json 数组里显式排序
多 skill 触发条件重叠	紧化 description 区分场景; 或合并加分支
项目级 vs 用户级 skill 撞名	项目级默认胜; 用户 override 总是可行
Hook 触发过频	加 matcher 收窄或入参 guard; 别 silent disable

可观测性

• 每个 hook 写一行 sentinel: <unix-ts>,<event>,<matched_file> → .claude/logs/hook-trace.log
• 每个 subagent 调用由 harness 自动记录
• Skill 触发每几个轮次 review transcripts
• 实际调用次数对比 Stage 1 估算; 偏差 > 2× → 重新分 tier

生命周期管理

每 ≥ 3 轮工作流 review 一次, 或项目节奏切换时:

信号	处理
Hook 最近 3 轮触发数 = 0	候选退役
Subagent 输出从未被后续轮次引用	输出格式错或已过时
Skill 被触发但 Claude 绕过指引	description/body 错位, 重写或移除
项目结构变更, hook regex 失配	更新或退役
多轮实际触发 > 2× 估算	候选升级到通用包
实际触发 < 0.5× 估算	tier 高估, 降级或退役
观察到多个新模式	重跑 Stage 1, 当增量更新

退役流程: mv 到 .claude/_archive/<轮次标识>_<名字>/, 从 settings.json 移除, 更新 README。

反模式

战略层

• 自动化思考时间 — 重复处恰是你做推理的地方, 自动化掉了推理本身
• 未验证 ROI 就开建 — 跳过 tier 分配累积低价值自动化
• 一次性当复发 — 等到 ≥ 3 真实实例再做机制设计
• 修症状不修根因 — 反复清理坏输出? 修生成器, 不是包装清理

实施层

• Hook 跑长任务 — 阻塞后续操作, 改用 subagent
• Subagent 代替决策 — 失去 user 控制, subagent 只准备数据
• 大改 settings 文件 — 一处语法错全部 hook 静默失效; 增量改, jq -e 验证
• Skill description 太窄 — 漏掉同义词; 把用户 transcript 中真实措辞写进去
• 通用模板内嵌项目路径 — 复用失败; 参数化或舍弃

跨项目

• 直接 cp 装载 — 覆盖目标 settings.json; 用 jq merge
• 装载后无 smoke test — silent failure 等用时才暴露
• EN/ZH 各自独立维护 — 必然漂移; 选一份为正本, 改动时同步翻译

团队协作

文件	策略
.claude/hooks/ .claude/agents/ .claude/skills/	团队共享 → commit
.claude/settings.json	共享 hook commit; 个人 hook → settings.local.json
.claude/settings.local.json	gitignore
Memory 文件	个人, 永不 commit

多人团队: skills 抽到共享仓库, submodule 或 symlink 装载。

复用 checklist (从 0 到 1)

把方法论带到新项目:

• 找 ≥ 3 个任意重复操作实例
• 分 tier; Skip-tier 直接跳
• 按决策树选机制
• 仅实施 P0 (一个产物); 其他暂缓
• Smoke test; commit
• 用 ≥ 1 轮工作流再加 P1
• ≥ 3 轮后 review: 未用的退役, 超用的升级到通用

端到端示例

User: "我老是手动查训练进度并更新报告"

Stage 1 (挖掘):
- 模式: 状态查询, 每轮训练 ~3 次, 累计 60+ → P0
- 模式: 一致性同步, 每轮 ~1 次, 累计 15+ → P1
- 战略层 veto 检查: 非思考时间, 非创造性; 可自动化

Stage 2 (实施):
- Hook: SessionStart loader 注入训练状态
- Subagent: task-monitor 按需详细进度
- Hook: PostToolUse 警告派生报告缺索引条目
- Smoke test: sentinel 日志确认 3 个都正常触发

Stage 3 (通用化, 经过 ≥ 3 轮训练考验):
- state-snapshot.sh 用 env var 配置
- task-monitor.md agent 通过 prompt 参数适配
- index-sync.sh 用 regex 配置
- Smoke test: 装到第二个项目验证

配套 skill

data-lineage 和 derive-experiment 是本方法论产出的具体实例, 实施 Stage 2 时可参考。

Examples

Example 1 — User 抱怨触发挖掘 Input: "每次派生新版本都忘了更新血缘文件" Output:

• Stage 1: 模式 H (数据血缘), tier P1 (每轮派生 ~1 次, ~10min/次)
• Stage 2: 装 derive-experiment skill, 步骤 5 自动写血缘
• Stage 3 (稍后): 抽取 data-lineage schema 为通用模板

Example 2 — 跨项目移植 Input: "启动一个新 ML 项目, 应该带什么自动化" Output:

• 跳过 Stage 1 (分析已完成)
• Stage 2: 装通用模板, env vars 配置项目参数
• 用前跑 smoke test

Example 3 — 拒绝过早通用化 Input: "今天写的脚本, 升级成通用 skill" Output:

• 拒绝 Stage 3 (缺真实使用证据, < 3 轮)
• 建议先做 Stage 2 (项目 skill), ≥ 3 轮后再评估

Example 4 — 文档密集项目 (非 ML) Input: "文档团队总忘记 ship feature 时更新 changelog" Output:

• Stage 1: 一致性同步, tier P0 (每轮发布 ≥ 3 次)
• Stage 2: PostToolUse hook 监听 CHANGELOG 邻近文件, 缺版本段则 warn
• Stage 3: 参数化为 index-sync.sh, 已在通用包内

Example 5 — 战略层 veto 胜出 Input: "每个 PR description 都很重复, 模板化吧" Output:

• 战略层 veto: PR description 恰是对变更的反思; 模板化丢信号
• 建议手写; 提供 subagent 起草初稿供 user 编辑

Example 6 — 轮次 review 触发退役 Input: "审计我们的自动化, 哪些还在挣钱" Output:

• 拉 .claude/logs/hook-trace.log sentinel 日志
• 3 个 hook 最近 3 轮 0 触发 → 退役到 _archive/
• 1 个 skill 触发但从未被采纳 → 重写 description 或移除
• 1 个 hook 触发 5× 预期 → 考虑升级到通用包