| 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 记录 (能看的都看)
- 项目产物 (脚本/文档/配置)
- 用户痛点
步骤
- 扫描 transcripts, 找重复 ≥ 3 次的操作
- 抽象动作 → 模式 (是"做什么"而非"怎么做")
- 按通用类别归类 (见 catalog)
- 数累计次数 / 独立 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 排序。
步骤
- 按决策树为每个 P0/P1 模式映射机制
- 先做 P0
- 项目特定路径/约定先硬编码
- 每个产物独立验证再集成
交付物
.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 个不同子任务真实使用考验的产物。
步骤
-
通用度评分 每个产物:
- 数项目特定术语 (路径/名字/行话)
- 密度 > 60% → 舍弃; 20-60% → 参数化; < 20% → 保留原样
-
脱敏:
- 移除硬编码路径
- 项目/用户/数据集名称替换为占位符
- 扫描意外 PII: 用户名、内部主机名、密钥
- 兜底:
grep -rE '(/home/|/Users/|@.*\.com|192\.168|api[_-]?key)' <artifact>
-
参数化:
- Hook: 用 env vars 传路径/正则
- Skill: 用 prompt 参数传上下文
- Subagent: frontmatter 显式声明输入字段
-
抽象:
- 把具体步骤换为流程阶段
- 描述阶段达成"什么", 不写"怎么做"
-
重命名:
-
边界明确:
- 每个产物输入/输出显式定义
- 跨产物用名字引用, 不用路径
验证
- 在第二个项目 (真实或 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)
把方法论带到新项目:
端到端示例
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× 预期 → 考虑升级到通用包
