# Harness Ops 目录约定

`harness/` 是工程、工具和第三方 Skills 的长期经验驾驭层。这里的 `harness` 指稳定的约束、读取、验证和写回框架；目录中的具体 Skill 一律使用 `<target>-ops` 命名，其中 `ops` 是 Operations，表示目标对象的运行、维护、适配与持续改进。

## 创建路由

当用户说“创建一个 harness skill”“给某工程建 harness”或“把这个工具的经验沉淀起来”时：

1. 使用官方 `skill-creator`。
2. 默认创建到 `harness/<target>-ops/`，名称和 frontmatter `name` 都使用 `<target>-ops`。
3. 不再创建 `*-harness` 目录；`harness` 只作为顶层分类名。
4. 先确认目标对象和典型触发场景；没有额外要求时，采用本文件规定的最小结构。

## 最小结构

```text
harness/<target>-ops/
├── SKILL.md
├── .gitignore
└── experience.local.md   # 本机创建，默认不进 Git
```

只有在真实需要时才增加：

- `scripts/`：反复执行且需要确定性的修复、诊断或提取脚本。
- `references/`：较长的可分享机制、协议和最佳实践。
- `assets/`：Skill 产出必须复用的模板或静态资源。

不要给单个 Skill 增加 README、安装指南或变更日志；设计说明统一放在仓库 `docs/`。

## 职责边界

Ops Skill 可以服务两类对象：

1. **自有工程**：保存架构入口、调试路径、运行拓扑、问题复盘和维护手册。
2. **第三方工具或 Skills**：不复制、不篡改上游能力，专门保存最佳实践、版本差异、本机水土不服、兼容性问题、已验证绕法和组合方式。

`SKILL.md` 负责稳定、可分享的部分：

- 目标对象和触发场景
- 读取本地经验的规则
- 问题路由、验证顺序和写回协议
- 换一台机器仍成立的最佳实践
- 隐私边界和失效处理规则

`experience.local.md` 负责实时、本机私有的部分：

- 绝对路径、机器、地址、端口、账号、代理、登录态和版本快照
- 本机复现的错误、根因、修复命令和验证证据
- 上游 Skill 在本机不适配的表现与绕法
- 尚未泛化、需要继续验证的经验

## 工作循环

每次触发 Ops Skill 时：

1. 先读 `experience.local.md`，再检查源码或当前运行态。
2. 优先复用最近且带验证证据的经验；旧记录冲突时不做平均判断。
3. 完成排障、适配或最佳实践验证后，当场写回本地经验。
4. 只有经过重复验证、与具体机器无关的结论，才提炼进 `SKILL.md`。
5. 既有经验失效时标记或替换旧结论，不允许只追加相互冲突的新段落。

## Worktree 原则

Ops Skill 位于独立的 `jacky-skills/harness/`，不放进被维护工程的 `CLAUDE.md`。这样同一工程的多个 Worktree 可以读取同一份外部经验源，避免每个分支各自复制、合并和版本化本机事实。

如果 `jacky-skills` 自身使用多个 Worktree，本机经验仍应选择一个明确的主目录作为唯一写入源，其他 Worktree 通过链接或安装注册表复用，避免出现多个 `experience.local.md` 真相源。

## 隐私和分享

- `experience.local.md`、`*.local.*` 和私有子目录必须被 `.gitignore` 排除。
- 真实用户路径、主机、密钥、私有端点和代理端口不得进入可分享文件。
- 分享时只发布通用协议、抽象示例和已脱敏的最佳实践。
- 文件格式允许演进，但“先读取、再验证、解决后写回、私有事实不进 Git”是稳定协议。

## 重命名与迁移

重命名 Ops Skill 时必须同步更新：目录名、frontmatter `name`、description 触发词、自引用、跨 Skill 调用、安装器、审计器、README、测试和全局链接。以评测、打分为职责的 `harness-benchmark` 不属于本目录，不因名称含 `harness` 而迁入。