112 lines
5.9 KiB
Markdown
112 lines
5.9 KiB
Markdown
# why-here
|
||
|
||
`why-here` 是一个在交付前使用的审查 skill（供 agent 按需加载的一组工作规则）。它对改动里每个可疑的部分问同一个问题：**它现在为什么还在这里？**
|
||
|
||
完成后的结果仍然需要它，就留下。它只是因为做的过程走过某条路才存在，就删掉。
|
||
|
||
## 它解决什么问题
|
||
|
||
一次改动做完时，常会留下只对制作过程有意义的内容：回应早先误解的说明、放弃的方案留下的分支、迁移完成后仍在的临时字段、被替换掉的旧实现。这些内容一旦进入代码、接口、配置、注释或文档，下一个读到它们的人会把它们当成当前设计的一部分继续理解和维护。
|
||
|
||
普通的“简化”定位不了这个问题。一段说明可能很短，却仍然只是在记录来路；一个结构可能看起来不整洁，却仍被调用方、公开契约、已有数据或外部系统要求，删掉就出事。判断标准不是长短，也不是整洁，而是完成后的结果现在还需不需要它。
|
||
|
||
## 它如何判断
|
||
|
||
审查分五步：
|
||
|
||
1. 先确定完成后的结果是什么。从用户的请求、验收标准、相关文档、当前契约和真实调用方推导需要的行为、结构和文档。依据缺失或互相矛盾时，标记为证据不足，不从当前实现反推。
|
||
2. 找出可能已经过期的部分：回应旧误解的说明、复述尝试和反复的叙述、迁移留下的临时字段和分支、保护已被删除行为的测试、新旧两套表示同时保留的情况。
|
||
3. 逐项找现在仍然成立的理由。文字看删除后是否会改变读者的理解、判断或操作；代码、接口、配置和数据结构要检查当前调用方、契约、已有数据、外部约束。历史能解释一个东西为什么出现，但只有当前证据能决定它是否留下。
|
||
4. 只在证明过的范围内清理。默认只审查和报告，用户明确要求修改时才动文件。公开接口、持久化数据、传输格式、迁移历史和仍在使用的兼容路径，先给出证据和拟议结果，取得授权再改。
|
||
5. 跑针对性验证，检查有没有产生新的孤立代码、测试、配置或文档。
|
||
|
||
“如果从完成后的设计开始，还会加入它吗”这个反问只用来找候选项。答案是“不会”只说明值得调查，不等于可以删。
|
||
|
||
最终回复说明完成后的状态、仍然成立的约束、实际跑过的检查，以及因为证据或授权不足而保持原样的部分。它不会把刚清掉的过程改写成一份删除清单再交回来。
|
||
|
||
## 适用场景
|
||
|
||
`why-here` 可以由 agent 在交付前主动选择，也可以由你显式调用。它适合：
|
||
|
||
- 一次改动中途换过方案、纠正过误解，或者完成了一次内部迁移；
|
||
- 你想知道某个字段、状态、分支、注释或文档段落是否还属于完成后的结果；
|
||
- 你要清理旧实现留下的内容，同时保留真实的兼容要求。
|
||
|
||
它不适合只想减少行数的重构和代码美化，不适合以找出全仓库死代码和重复抽象为目标的简化审计，也不适合只要求把文字写得自包含或核实事实。调查和方案设计还在进行时不要用它：那时的过程记录仍在起作用。
|
||
|
||
## 安装
|
||
|
||
所有 skill 统一从分发仓 `agent-skills/skills` 安装：
|
||
|
||
```bash
|
||
npx skills add https://git.im0o.top/agent-skills/skills.git
|
||
```
|
||
|
||
安装程序会列出全部 skill，勾选 `why-here` 即可。获取仓库前，可以先检查当前机器是否有访问权限：
|
||
|
||
```bash
|
||
git ls-remote https://git.im0o.top/agent-skills/skills.git HEAD
|
||
```
|
||
|
||
命令返回 commit hash 就表示可以继续安装。
|
||
|
||
本仓库负责开发和发布，不作为常规安装来源。需要单独取一份时，可以从本仓 Release 下载 `why-here.zip`，解压后把目录交给安装工具：
|
||
|
||
```bash
|
||
npx skills add ./why-here
|
||
```
|
||
|
||
安装工具不接受 ZIP 文件路径，只接受解压后的目录。
|
||
|
||
## 使用
|
||
|
||
交付前直接说明要审查的范围：
|
||
|
||
```text
|
||
这次改动中途换过方案。提交前用 why-here 看看还有没有只属于旧方案的内容。
|
||
```
|
||
|
||
```text
|
||
迁移已经做完了。用 why-here 检查这些临时字段和兼容分支现在还有没有人用，先只报告不要改。
|
||
```
|
||
|
||
```text
|
||
这份文档里有几段是在回应我早先的误解。用 why-here 判断哪些对现在的读者还有用，可以直接改。
|
||
```
|
||
|
||
在提供同名斜杠命令的客户端中，也可以运行：
|
||
|
||
```text
|
||
/why-here
|
||
```
|
||
|
||
默认是只审查不修改。需要它直接动文件时，在请求里说清楚，例如“可以直接改”“清理掉”。
|
||
|
||
## 与其他 skill 的边界
|
||
|
||
`think-twice` 负责把一段文字重写成读者可以独立理解和执行的最终文本，范围只有文字。`why-here` 同时看文字和有运行意义的产物，而且对两者用不同的修改门槛：文字按读者是否需要判断，代码、接口和数据结构必须再检查真实调用方、契约、已有数据和外部约束。
|
||
|
||
以查找死代码、重复状态和无收益抽象为目标的通用简化审计是另一件事。`why-here` 的判据只有一条：这个部分现在是否只因为做的过程走过某条路才存在。
|
||
|
||
`why-here` 不依赖其他 skill，可以单独安装使用。
|
||
|
||
## 文件说明
|
||
|
||
```text
|
||
skill/
|
||
└── SKILL.md # 审查范围、五步流程、分类判据和交付要求
|
||
```
|
||
|
||
发布包只包含 `skill/` 目录中的内容，因此解压后的 `why-here.zip` 根目录直接包含 `SKILL.md`。
|
||
|
||
## 发布
|
||
|
||
推送与 `v*` 匹配的 annotated tag（带说明文字的 tag）后，Gitea Actions 会运行 `.gitea/workflows/release.yml`：
|
||
|
||
1. 读取 annotated tag message，作为 Release 正文；
|
||
2. 读取 `skill/SKILL.md` 中的 `name` 字段；
|
||
3. 将 `skill/` 打包为 `why-here.zip`；
|
||
4. 创建同名 Release，并上传 ZIP 文件。
|
||
|
||
发布 tag 必须是 annotated tag，而且 message 不能为空。创建和推送 tag 时使用完整的 `refs/tags/<name>` 路径，避免同名 branch 与 tag 混淆。
|