CLAUDE.md · diff
git:20261013.764c8fb to git:20261013.be4849d
10 added, 1 removed. Audit A to A.
# 面向 agent 的仓库说明
本文件给**在本仓库干活的 agent** 看：命令、隐性规范、踩坑点。
使用者的安装与用法见 [README.md](README.md)；贡献者流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 这是什么
11 个产品经理 skill 的集合，首尾相接成一条链路。全是 Markdown，**没有代码、没有构建、没有测试**。
```
skills/<name>/
├── SKILL.md # 必需。agent 读它执行
├── README.md # 必需。给人看的使用说明
├── agents/ # 可选。Codex 的 openai.yaml
├── references/ # 可选。展开文档
└── assets/ # 可选。模板、示例
```
## 常用命令
```bash
# 发布前自检（与 CI 门禁一致）
grep -rnI $'\xef\xbf\xbd' . --exclude-dir=.git && echo "发现乱码" || echo "无乱码"
grep -rnIE '(/Users/[A-Za-z0-9._-]+/|/home/[A-Za-z0-9._-]+/|[A-Za-z]:.Users.)' . --exclude-dir=.git
# 校验 frontmatter name 与目录名一致
for d in skills/*/; do
echo "$(basename $d) -> $(sed -n '1,10p' $d/SKILL.md | grep -m1 '^name:')"
done
# 链路闭环检查：每个「下一步」指向的 skill 必须真实存在
grep -rhoE '\[`[a-z-]+`\]\(\.\./[a-z-]+/\)' skills/ | sort -u
```
仓库没有构建步骤。改完 Markdown 就是改完了，但**必须跑上面几条**。
---
## 隐性规范（不照做会被 CI 拦住，或者更糟——静默出错）
### 1. frontmatter 的 `name` 必须等于目录名
CI 的 `structure` job 会拦。不一致时 agent 的 skill 发现机制会错位。
### 2. 产物路径是硬约定
- 功能级产物 → `docs/prd/<feature-name>/`
- 产品级基线 → `docs/product/<project-name>/`
`<feature-name>` 用**小写短横线**（`user-auth`、`payment-flow`）。
链路靠这个目录约定衔接：上一个 skill 写进去，下一个 skill 直接读。**改任何 skill 的输出路径前，
先 grep 全仓库看谁在读它**。
### 3. 证据标注三分法
所有面向事实的 skill 都用同一套标记，不要自创：
| 标记 | 含义 |
|---|---|
| `[OBSERVED: URL]` / `[OBSERVED: SCREENSHOT]` | 直接可见的事实 |
| `[INFERRED]` | 合理的重建推断 |
| `[UNKNOWN]` | 输入资料无法确立，**必须写明归属人** |
**绝不允许把 `[UNKNOWN]` 编成事实**。这是本仓库所有 skill 的共同底线。
### 4. 「下一步」只能指向仓库内真实存在的 skill
这是最容易犯、也最伤的错误——读者被指去用一个他根本没有的 skill。新增或改名 skill 后，
**grep 全仓库**确认没有悬空引用：
```bash
grep -rnI "某个被删掉的-skill-名" --include="*.md" skills/
```
### 5. 不引入外部工具链依赖
本仓库的 skill **默认不依赖任何外部工具、MCP 服务或常驻进程**。可以提及某个外部工具是「可选」，
但必须写清「不装也不影响链路」，且**不得写死绝对路径**。
唯一被允许的例外是「解析特定文件格式确实绕不开的运行环境」——
目前只有 `product-prd-extract` 一个（`.docx` 是 ZIP+XML，非 Node 不可）。它必须严格遵守下面第 7 条。
历史上这里踩过两个坑：
- `design-spec-prototyper/SKILL.md` 里写过 `/Users/<原作者>/...` 的硬编码路径（已删）
- 多个 README 引用过一批本仓库根本没有的 skill（已清）
### 6. 不写死作者本机路径
CI 门禁 2 会拦。
### 7. 需要运行环境时，必须「自检 → 自动装 → 给退路」
如果某个 skill 确实需要 Node / Python 之类，**不允许把安装步骤甩给用户**。必须写成 agent 的主动行为：
1. **先自检，不要先问用户**——自己跑 `node --version` 之类确认环境。
2. **缺依赖就直接装**，不必先征求同意，但装之前要用一句话说清在装什么、多大、装几次。
3. **装不上要给可照做的指引**——按平台（macOS / Windows / Linux）给具体命令，不要只说「请安装 Node」。
4. **必须同时给退路**——让用户有办法在不装环境的情况下继续（例如粘贴文本），并说明走了退路会损失什么
（例如没做保真度校验、没提取内嵌图片）。
反面教材：文档里写「本 skill 需要 Node，请自行安装」。正面参照：`skills/product-prd-extract/SKILL.md`
的「依赖与自动准备」一节。
---
## 新增一个 skill 的步骤
1. 建 `skills/<name>/`，目录名用**小写短横线**。
2. 写 `SKILL.md`：frontmatter 至少 `name` + `description`；正文照现有 skill 的骨架
（`## 使用边界` / `## 开始前` / 产物 / `## 不做什么` / `## 下一步`）。
3. `description` 要同时说清**做什么**和**什么时候用**，并写明**不适用**的情况与替代 skill。
这段文字决定 agent 会不会选它。
4. 写 `README.md`：面向使用者，说清用途、输入、产物、不做什么。**别抄 SKILL.md**——
README 讲「什么时候用」，SKILL.md 讲「怎么做」。
5. 如果是 Codex 也要用，加 `agents/openai.yaml`（三字段：`display_name` / `short_description` / `default_prompt`）。
6. 把它接进链路：改前一个 skill 的「下一步」和 README 的链路图，别让它成为孤儿。
7. 更新 `README.md` 和 `README.en.md` 的 skill 清单与链路图。
---
## 踩坑点
### 中文提交信息不要用 heredoc
Windows + Git Bash 会把 heredoc 里的中文写成 U+FFFD 乱码，**而且不报错**——静默进历史。
用编辑器写入仓库外的临时文件，再 `git commit -F <文件路径>`，提交后回读确认。
### 工具参数里的中文也会被吞字
不只是 heredoc。**agent 传工具参数时，中文偶发被替换成 U+FFFD**——这个仓库实测中过招的字有
- 「合」「的」「依赖」「完整」「且」。写完文件必须复扫，提交信息也一样。
+ 「合」「的」「依赖」「完整」「且」「外」。写完文件必须复扫，提交信息也一样。
+
+ **这条不只管本仓库。** skill 在用户项目里产出的中文文档会以同样的方式中招，而用户根本不知道要扫。
+ 所以每个会写中文产物的 skill，`## 交付前检查` 里都该带一条：
+
+ ```bash
+ grep -rnI $'\xef\xbf\xbd' <产物目录> && echo "发现乱码，先修再交付" || echo "无乱码"
+ ```
+
+ 让 agent 交付前自己扫一遍，而不是等用户肉眼发现某个字变成了两个黑方块。
工具参数这个通道没法从源头防，只能靠**写完就扫**。CI 两道门禁合起来才覆盖全：
**门禁 1 扫工作区，门禁 4 扫提交信息**。本地推之前先跑一遍：
```bash
# 工作区
grep -rnI $'\xef\xbf\xbd' . --exclude-dir=.git --exclude-dir=node_modules
# 待推送的提交信息
for sha in $(git log --format=%H origin/main..HEAD); do
git log -1 --format=%B "$sha" | grep -q $'\xef\xbf\xbd' && echo "❌ $sha 提交信息有乱码"
done
```
**提交信息里的乱码只能靠 `git commit --amend` + force push 修**，比改文件麻烦得多——
所以别偷懒，提交前先扫。
### 提交身份
本仓库是公开仓库，**必须先设本地身份再提交**——全局配置是公司身份，一旦进入公开历史就抹不掉：
```bash
git config --local user.name "mingdui"
git config --local user.email "37131158+mingdui@users.noreply.github.com"
git config --local user.email # 每次提交前回读确认
```
### 第三方内容
收录任何第三方作品前，先确认对方 **LICENSE**：
- 有许可（如 Apache-2.0 / MIT）→ 保留许可副本 + 在 [THIRD-PARTY.md](THIRD-PARTY.md) 写明来源与修改情况
- **没有 LICENSE → 默认保留全部权利，一个字都不能拷**。可以借鉴思路（思路不受著作权保护），
但必须独立重写。**这种情况不需要在 THIRD-PARTY.md 留痕**——没有署名义务，写多了是噪音
### `prototype-html` 是第三方，不要顺手改
它原样收录自 `vagerent/prototype-html`（Apache-2.0），改动会让「原样收录」的声明失准。
要改就先更新 THIRD-PARTY.md 里的修改说明。
---
## 推送前
`git commit` / `git push` 是对外发布动作。**先确认再推**：远端地址、目标分支、提交身份、提交内容。