CLAUDE.md git:20261013.60e8978A

Immutable. This exact content never changes and is served at /api/v1/blob/1386f046bb781ad9.

# 面向 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 <文件路径>`，提交后 `git log -1 --format=%B` 回读确认。

### 提交身份

本仓库是公开仓库，**必须先设本地身份再提交**——全局配置是公司身份，一旦进入公开历史就抹不掉：

```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` 是对外发布动作。**先确认再推**：远端地址、目标分支、提交身份、提交内容。