agentleFS
xingtu1996xingtu1996/xingtu-skills/skills/harness-governance/SKILL.md

harness-governance

Skill0 starsChanged 2 months agoMITView on GitHub

对 harness 常驻配置层做减法治理闭环:审计→报告→人审→执行→回归。标尺:常驻<窗口5%、入口<200行、单文件<16KB;五分类 KEEP/SIMPLIFY/MOVE/DELETE/CONFLICT;只移不删、人审不可跳过。触发词:harness 治理/瘦身/审计/配置减法/上下文超标/skill 太多/cleanup。判据细节见正文。

The file

Files
SKILL.md

Harness 减法治理(审计 → 人审 → 执行 → 回归)

定位:任何 agent 工作区的"常驻配置"(写给模型的系统提示 / 规则 / 技能 / 子代理 / 钩子 / 设置项)都会随时间膨胀, 膨胀到一定程度模型会选择性忽略,反而降低质量。本技能提供一套工作区无关的减脂闭环:先量、再判、人拍板、可逆执行、回归验证。 它管的是"怎么把配置层做小做准",不是某个具体项目该删哪条。

何时触发

  • 人说"配置太肥了 / 瘦身 / 清理工具 / 审计一下 harness / 淘汰某组件"。
  • 体积/注入超预算(见下标尺),或新增 skill/rule/agent 前走准入自查。
  • 模型升级 / 换代:新模型能力跃迁(更强自主、更长上下文、原生多模态等)→ 旧模型时代写的"兜底规则"该清或沉降。
  • 定期巡检(建议每 ~30 天一次轻扫;每半年或大版本一次 ablation 式深扫)。

判冗余的统一标尺(防拍脑袋)

标尺阈值含义
常驻上下文占比< 有效窗口的 5%每次必注入的字节/令牌不该挤占任务本体(例:1M 窗口 ≈ 留 50K 给常驻)
主入口文件行数< 200 行系统提示/主 CLAUDE 类文件超过即"kitchen sink",>400 行模型开始漏读
单文件大小< 16 KB单个规则/技能文件的临界线,超了拆分或按需加载
"写通过删除"每条规则问一句"删掉它会犯错吗?不会 → 删/沉降"

保留底线(瘦身时不许动):机械门禁类——由 hook / 脚本强制的体积、格式、安全校验,不因"减文本"而删除。人读得懂的规则可以沉,机器兜底的红线不能撤。

三条恒定纪律

  1. 只移不删(沉降优先于删除):拿不准是否有用的,先沉降为按需加载 / 移到参考层 / 关闭(off / name-only),不直接物理删。删除是最后手段,且需人确认。
  2. 先删后加(unhobbling):不确定时先删、跑代表性任务看是否退化、退化了再加回最小必要——而不是一次全删,也不是攒着不敢删。
  3. 人审恒定不可跳过:语义价值判断(这条规则还要不要、这个 skill 是不是核心)归人;agent 只做可逆操作(备份、指针化、精简)。dormant/dead 名单必须人拍板,不凭触发频次自动关核心组件(自动触发 ≠ 显式调用,低频≠无用)。

模型升级判据(换代时逐条过旧规则)

满足任一即候选"清除或沉降",但都要经回归验证确认不退化:

判据说明
能力已内化新模型原生具备(如原生多模态、更强自主)→ 为其写的"手工兜底步骤"可废
瓶颈已解除上下文不再是瓶颈 → 为省 token 做的过度分步 / 指针化 / 压缩可放宽
自主性够模型足够可靠 → "必须给机械清单"可降级为"主 agent 直读判断"
删后不退化跑代表性任务回归,行为不变才确认这条真的能删

五分类(每条发现归一类,避免"一刀切删")

  • KEEP — 真资产 / 红线 / 机械门禁,保留。
  • SIMPLIFY — 有用但啰嗦,留其义、压其形。
  • MOVE — 有价值但非"每次都要",沉降为按需加载 / 移到参考层。
  • DELETE — 纯冗余、死规则、重复注入,删。
  • CONFLICT — 规则互相打架 / 语义歧义,交人(或产品)裁决,agent 不擅自取舍。产出物与已验收成品风格对不上时,走下方「色值指纹」配方做层位定位,别一上来改 skill。

治理流程(6 Phase)

Phase 1 · 审计(主 agent 直读判冗余,脚本只做机械量)

主 agent 直接读常驻配置(系统提示 / 规则 / skills / hooks / settings),按上表标尺自主判"冗余 / 可沉降 / 可删 / 冲突"。 脚本只负责两类机械活(不喂结论):

  • 体积 / 注入基线(本区若有体积脚本就跑它;无则手动 wc -l / du 对阈值)。
  • 触发频次统计——仅作休眠名单的参考信号,绝不单独作关闭依据。

Phase 2 · 报告(输出一份 _report.md)

发现列表(标 P0 体积超标/重复注入/死 hook、P1 可沉降、P2 微优化)+ 生命周期(active / dormant / dead)+ 引用影响映射(改一处会牵动哪些引用)+ 体积对照(常驻字节、主入口行数 vs 预算)+ 每条发现归入五分类。

Phase 3 · 角色分工

角色负责判定
人P0 审批 / 语义取舍 / 删除确认红线、是否保留、CONFLICT 裁决
agent方案生成 / 可逆执行P1/P2 沉降、精简、指针化(git 可回退)
hook / 脚本自动拦截与预警体积超标告警、新组件未过准入拦截

Phase 4 · 人审(HITL,不可跳过)

把休眠/建议关闭名单 + 五分类报告交人,等确认后落地。写配置时优先用交互入口或人明确确认,不手写覆盖全表。

Phase 5 · 执行(agent,可逆)

改任何既有配置/文件前先备份(cp 为 *.bak-YYYYMMDD 或走本区备份脚本),改后 git diff(若纳管)确认无核心语义被误删。P0 去重复注入/清死 hook、P1 规则沉降与主入口减肥、P2 脚本精简。

Phase 6 · 回归冒烟

  • 配置断言:settings/入口文件结构合法、关键旋钮未被误降级。
  • 体积断言:重跑体积量 vs 预算,确认达标。
  • 功能冒烟:被治理的入口(常用命令 / 关键 skill)仍可调用、提交无脚本报错。

CONFLICT 具体诊断配方:视觉/色系风格漂移 → 色值指纹定位与 SSoT 收敛

何时用:agent 按流程产出的东西(排版、色系、封面、样式)与人已验收的成品不一致,人说"你发出来跟我们之前的不一样"。 上面 6 Phase 是框架,本配方是可逐字复跑的执行抓手。色值仅为示例,方法工作区无关。

Step 1 · 取指纹(用实物定义"成品长什么样") 从已验收的真实产出物(发布 HTML / 导出物)grep 主题色值计数与结构特征——如 grep -oc d71a1b(红指纹)、grep -oci 056de8(蓝指纹)、<h2 style=...> 内联样式抽样。线上成品 URL 抓不到(反爬/验证页)时,改用本地包内实物 HTML 取证,并在结论里明说取证源。

Step 2 · 四方对齐,定位误导层(先定层,再动手) 把「实物指纹 / 视觉 SSoT 文件 / 编排层 skill 正文 / 规则与入口文件兜底」四方口径列对照表,找出哪一层在误导。 关键判据:skill 正文可能本来就是对的——漂移根因高频藏在规则分册、AGENTS/系统提示类入口文件的旧默认兜底,以及跨层多套口径打架(同一约定三处三个版本)。别一上来改 skill。

Step 3 · 人审拍板 → 收敛到唯一真相源 把差异表 + 收敛选项(A/B 制)交人裁决;拍板后:先备份,再逐文件 Read 原文 → Edit 收敛。口径只留 SSoT 一处完整定义,其余层改指针引用("细则见 X §Y"),不留第二份正文(防副本腐烂,对齐"只移不删")。

Step 4 · 全仓残留清扫(现行活口径 = 0,带两条豁免铁律) 对全部配置/流程文件 grep 旧口径的现行活表述,要求命中 = 0。命中后按两条豁免复核,不许机械清零:

  • 语境豁免:出现在"禁用 / 作废 / 旧 / 收敛 / 仅…才用"等否定或历史语境中的是合法残留,不误删。
  • 边界豁免:不同子系统(如配图/概念图 vs 正文/封面)可能合法使用另一套色或约定——先判命中行的归属范围,只清本约定辖区内的残留,别跨界误伤。

Step 5 · 留痕(防下个会话再漂) 变更日志 + 跨工具长期记忆同步更新收敛结论与根因(哪层曾是误导源)。只改文件不写记忆/日志 = 下一个 agent 会话仍照旧口径执行,等于没收敛。

首实例凭证(2026-09,某内容工作区):agent 产出 pure 极简主题 vs 实发成品 review 红系(指纹 d71a1b×12 / 056de8×0)不一致 → 定位三套口径打架(视觉 SSoT 与 skill 已收敛红系,规则分册 + 入口文件铁律仍写"默认 pure"误导新会话)→ 人审拍板"分文体" → 6 文件备份+Edit 收敛、workflow 层旧命令同清 → 全仓清扫时豁免配图子系统(合法保留另一色)与"作废/禁用"语境 → CHANGELOG + memory 双留痕。

协作过程时间线(首实例完整走法,供复跑对照)

  1. recap 确认需求:先讲"要解决什么 / 关键判断(落点可能在 SSoT 不在 skill)/ 已做到哪",确认理解一致再动手。
  2. 只读取证:包结构、变更日志线索、既有 SSoT 现行约定、编排层 skill 原文、实物 HTML 指纹——全程零写;线上成品抓取被拦时降级本地实物并明说取证源。
  3. 证据表定结论:四方对照表(载体 × 主题 × 色值 × 谁在用),点名误导层,明说"skill 本来是对的,错在规则兜底层"。
  4. 拍板项 ≤2 个 A/B 选择题(禁开放式):每个选项带权衡,人拍板后才执行。
  5. 执行前并发防护:对全部待改文件 stat mtime 核无并行修改 → 备份脚本打快照 → 核对备份非空。
  6. 逐文件 Read→Edit:改前先读原文建立基线;执行中收到"文件已修改"提示先辨伪(可能是自己刚落的编辑,非真冲突)。
  7. 中途残留即扫即追:新命中先判归属——边界豁免(子系统另一色合法保留)与本辖区旧默认(要修)分开处理,不机械清零。
  8. 终态验证:grep 现行活口径 = 0 + 正向确认新口径已在各处落位。
  9. 双留痕:变更日志(类型+路径+"因为什么改了什么"+工具归属)+ 跨工具长期记忆(记根因教训,防下个会话再漂)。
  10. 治理技能自身同样走此环:进化建议 → 回查原始对话取证 → 更新计划先出人审 → 拍板后执行 → 体积/结构回归核验。

副作用与隔离铁律(治理工具本身不得成为新污染源)

治理的使命是"减",它自己绝不能变成新的膨胀源:

  1. 只读优先:Phase 1 审计全程只读,零写。
  2. 备份先行:动手改前必先快照。
  3. 范围隔离:只治本工作区这一套 harness;不跨项目写、不碰他项目/全局环境变量/他人配置。
  4. 单文件试点:批量前先拿一个文件试跑,确认无副作用再推广。
  5. 可回滚:能还原才动手;改后 diff 复核。
  6. 不硬编码:本技能复制到他区时,路径用 $HOME / 相对定位,脚本不默认写死任何项目路径。

治理周期

  • 模型升级/换代 → 全量深扫一次(旧兜底规则必过一遍,判据见上)。
  • 定期 → 每 ~30 天轻扫(体积 + 死 hook + 重复注入);每半年或大版本一次 ablation 式复核:整段清空、只对真实失败点逐条加回,别等它自然再膨胀。
  • 每次改动后 → 回归体积量 + 一致性检查 + 功能冒烟。

产出物

_report.md(P0/P1/P2 + 五分类 + 生命周期 + 角色分工)| 回归冒烟清单 | 决策沉淀(D1~Dn,记"为什么删/为什么留",供下次换代复用)。

<!-- public-sync: 2026-09-27 | 脱敏版本 | 源工程效能库(治理四件套) -->

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.