381 lines
14 KiB
Markdown
381 lines
14 KiB
Markdown
# Spec Coding Skills
|
||
|
||
一套同时支持 Claude Code 和 Codex 的 Skills，覆盖产品文档工作流的完整生命周期管理。
|
||
|
||
## 平台适配
|
||
|
||
| 平台 | 安装目录 | 触发方式 |
|
||
|------|----------|----------|
|
||
| Claude Code | `.claude/skills/` | `/rr`、`/wp`、`/go` 这类 slash commands |
|
||
| Codex | `.codex/skills/` | `/rr`、`/wp` 这类 slash commands，或直接自然语言说明“用 rr skill 评审需求文档” |
|
||
|
||
> Codex 额外需要项目根目录存在 `AGENTS.md`。本仓库已提供 `AGENTS.md.template`，安装脚本在 Codex 模式下会自动生成。
|
||
|
||
## 功能概览
|
||
|
||
```
|
||
RequirementsDoc ──▶ PRD ──▶ FeatureSummary ──▶ DevelopmentPlan ──▶ UIDesign ──▶ tasks
|
||
│ │ │ │ │ │
|
||
rr rp rf rd ru rt ← Review
|
||
mr mp mf md mu mt ← Modify
|
||
wp wf wd wu wt ← Write
|
||
```
|
||
|
||
### Skills 列表
|
||
|
||
| 类型 | Skill | Claude Code | Codex | 描述 |
|
||
|------|-------|-------------|-------|------|
|
||
| **Review** | `rr` | `/rr` | `/rr` | 评审 RequirementsDoc.md |
|
||
| | `rp` | `/rp` | `/rp` | 评审 PRD.md |
|
||
| | `rf` | `/rf` | `/rf` | 评审 FeatureSummary.md |
|
||
| | `rd` | `/rd` | `/rd` | 评审 DevelopmentPlan.md |
|
||
| | `ru` | `/ru` | `/ru` | 评审 UIDesign.md |
|
||
| | `rt` | `/rt` | `/rt` | 评审 tasks.md |
|
||
| **Write** | `wp` | `/wp` | `/wp` | 从 RequirementsDoc 生成 PRD |
|
||
| | `wf` | `/wf` | `/wf` | 从 PRD 生成 FeatureSummary |
|
||
| | `wd` | `/wd` | `/wd` | 从 FeatureSummary 生成 DevelopmentPlan |
|
||
| | `wu` | `/wu` | `/wu` | 从 DevelopmentPlan 生成 UIDesign |
|
||
| | `wt` | `/wt` | `/wt` | 从 DevelopmentPlan 生成 tasks |
|
||
| **Modify** | `mr` | `/mr` | `/mr` | 增量修改 RequirementsDoc |
|
||
| | `mp` | `/mp` | `/mp` | 增量修改 PRD（自动读取评审报告） |
|
||
| | `mf` | `/mf` | `/mf` | 增量修改 FeatureSummary |
|
||
| | `md` | `/md` | `/md` | 增量修改 DevelopmentPlan |
|
||
| | `mu` | `/mu` | `/mu` | 增量修改 UIDesign |
|
||
| | `mt` | `/mt` | `/mt` | 增量修改 tasks |
|
||
| **执行** | `go` | `/go` | `/go` | 🚀 发射按钮，激进模式一口气完成开发 |
|
||
| **辅助** | `iter` | `/iter` | `/iter` | 迭代变更入口（Bug/功能/重构） |
|
||
| | `doc` | `/doc` | `/doc` | 渐进式文档生成器，先写梗概再迭代完善 |
|
||
| | `capture` | `/capture` | `/capture` | 把一次成功任务复刻成结构化经验记录，输出到指定目录 |
|
||
| | `update` | `/up` | `/up` | Skill 升级优化 |
|
||
| | `deploy` | `/deploy` | `/deploy` | Drone CI/CD 全流程部署引导 |
|
||
| | `gitea` | `/gitea` | `/gitea` | 统一 Gitea 入口（issue / push / PR） |
|
||
| | `issue` | `/issue` | `/issue` | Gitea issue 只读专用入口（支持当前仓库自动识别） |
|
||
| | `issue-drive` | `/issue-drive` | `/issue-drive` | Gitea issue 拆单与批量创建专用入口 |
|
||
| | `changelog` | `/changelog` | `/changelog` | 一键发版（日志 + commit + tag） |
|
||
| **Miaobao** | `miaobao-nightly-ci-report` | `/miaobao-nightly-ci-report` | `/miaobao-nightly-ci-report` | Miaobao Drone nightly/main CI 证据报告 |
|
||
| | `miaobao-issue-acceptance-closeout` | `/miaobao-issue-acceptance-closeout` | `/miaobao-issue-acceptance-closeout` | Miaobao issue/PR 验收、Feishu 回写与清理 |
|
||
| | `miaobao-jianying-alignment` | `/miaobao-jianying-alignment` | `/miaobao-jianying-alignment` | 秒爆视频编辑对齐剪映/CapCut 实测基准 |
|
||
| | `update-miaobao` | `/update-miaobao` | `/update-miaobao` | 从已完成 Miaobao 工作沉淀 skill 更新建议 |
|
||
|
||
> Codex 兼容历史 `$skill` 写法，但本文档统一以 `/skill` 作为主入口。
|
||
|
||
## 安装 & 更新
|
||
|
||
一行命令搞定安装和更新。脚本会智能处理：新 skill 直接装，已有的对比更新，本地魔改自动备份；项目根目录的 `AGENTS.md` / `CLAUDE.md` 仅在缺失时生成，已存在则跳过。
|
||
|
||
```bash
|
||
# Claude Code + Codex（推荐）
|
||
bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh) both
|
||
|
||
# Codex only
|
||
bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh) codex
|
||
|
||
# Claude Code only
|
||
bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh) claude
|
||
```
|
||
|
||
或者先下载再执行：
|
||
|
||
```bash
|
||
curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh -o /tmp/install-skills.sh
|
||
bash /tmp/install-skills.sh both
|
||
```
|
||
|
||
### 安装脚本行为
|
||
|
||
- `both` 模式：同时安装 `.codex/skills/` 和 `.claude/skills/`，并生成缺失的 `AGENTS.md` + `CLAUDE.md`；已有则跳过
|
||
- `codex` 模式：安装到 `.codex/skills/`，并在项目根目录生成缺失的 `AGENTS.md`；已有则跳过
|
||
- `claude` 模式：安装到 `.claude/skills/`，并在项目根目录生成缺失的 `CLAUDE.md`；已有则跳过
|
||
- 如果传入自定义目标目录，脚本会优先安装 Codex 版 skills；目标路径包含 `.claude/skills` 时自动切到 Claude 版
|
||
|
||
### 推荐用法
|
||
|
||
- 团队项目、模板仓库：用 `both`，一次安装双端，最省心
|
||
- 只有你自己在 Codex 里用：用 `codex`
|
||
- 仓库明确只服务 Claude Code：用 `claude`
|
||
|
||
### 更新策略
|
||
|
||
| 情况 | 处理方式 |
|
||
|------|---------|
|
||
| 新 skill（本地没有） | 直接安装 |
|
||
| 本地未改 + 上游有更新 | 自动更新，并把旧版本备份为 `SKILL.md.local.bak` |
|
||
| 本地改过 + 上游有更新 | 保留本地版本，把上游新版写入 `SKILL.md.upstream.new` |
|
||
| 本地和上游一致 | 跳过 |
|
||
|
||
安装脚本会在 `.codex/skills/.install-state/` 或 `.claude/skills/.install-state/` 记录上次安装的上游文件指纹。只有本地文件仍等于上次安装版本时才自动更新；如果用户改过同名 skill，本地特性默认不会被覆盖。
|
||
|
||
项目根目录 guide 文件单独处理：
|
||
|
||
| 情况 | 处理方式 |
|
||
|------|---------|
|
||
| `AGENTS.md` / `CLAUDE.md` 不存在 | 从模板创建 |
|
||
| `AGENTS.md` / `CLAUDE.md` 已存在 | 跳过，保持原样 |
|
||
|
||
恢复本地版本：`mv SKILL.md.local.bak SKILL.md`
|
||
对比差异：`diff SKILL.md SKILL.md.local.bak`
|
||
合并本地特性与上游新版：`diff SKILL.md SKILL.md.upstream.new`
|
||
确认要强制覆盖本地版本时：`bash install.sh codex --force-overwrite`
|
||
|
||
## 使用示例
|
||
|
||
### 0->1 阶段：从需求到开发
|
||
|
||
Claude Code:
|
||
|
||
```bash
|
||
/wp
|
||
/wf
|
||
/wd
|
||
/wt
|
||
/go
|
||
```
|
||
|
||
Codex:
|
||
|
||
```text
|
||
/wp
|
||
/wf
|
||
/wd
|
||
/wt
|
||
/go
|
||
```
|
||
|
||
### 1->100 阶段：持续迭代
|
||
|
||
Claude Code:
|
||
|
||
```bash
|
||
/iter
|
||
/go
|
||
```
|
||
|
||
Codex:
|
||
|
||
```text
|
||
/iter
|
||
/go
|
||
```
|
||
|
||
也可以直接说自然语言，例如：
|
||
|
||
```text
|
||
请用 rr skill 评审 doc/RequirementsDoc.md
|
||
请用 wf skill 根据 PRD 生成 FeatureSummary
|
||
请用 go skill 按 doc/tasks.md 执行未完成任务
|
||
请用 doc skill 为认证模块写一份 300 字以内的使用说明
|
||
请用 capture skill 把这次成功任务复刻到 ./docs/lessons
|
||
请用 gitea skill 看当前仓库 open issues
|
||
请用 gitea skill 给当前分支开 PR 到 main
|
||
请用 gitea skill push 当前分支到远端
|
||
请用 issue-drive skill 把当前 bug 拆成两张 Gitea issue
|
||
请用 miaobao-nightly-ci-report skill 看最近 10 个 Miaobao CI 失败
|
||
请用 miaobao-issue-acceptance-closeout skill 收尾 Miaobao #1906 / PR #1910
|
||
请用 miaobao-jianying-alignment skill 给这个时间线交互对齐剪映
|
||
请用 update-miaobao skill 复盘这次验收并提炼 skill 更新
|
||
```
|
||
|
||
### Miaobao 专项
|
||
|
||
另一台机器要吃到最新 Miaobao skill，直接在目标项目根目录执行安装命令即可：
|
||
|
||
```bash
|
||
bash <(curl -sL https://git.internal.intelligrow.cn/zhangfucai/spec-coding-skills/raw/branch/main/install.sh) both
|
||
```
|
||
|
||
- `miaobao-nightly-ci-report` 依赖 Drone 访问环境：`DRONE_SERVER`、`DRONE_TOKEN`
|
||
- `miaobao-issue-acceptance-closeout` 依赖当前 Miaobao worktree、Gitea/Drone 状态，以及可用的 `lark-cli`
|
||
- `miaobao-jianying-alignment` 依赖可操作的剪映/Jianying Pro 桌面环境，必要时配合 Computer Use 或 GUI 探针
|
||
- `update-miaobao` 默认只维护 Miaobao skill；反思型更新要先给出目标、理由和 diff，再等确认
|
||
- Codex 新会话会重新扫描 skill；如果刚安装后当前会话没有看到新 skill，开一个新会话最稳
|
||
|
||
### 复刻一次成功经验
|
||
|
||
Claude Code:
|
||
|
||
```bash
|
||
/capture ./docs/lessons
|
||
```
|
||
|
||
Codex:
|
||
|
||
```text
|
||
/capture ./docs/lessons
|
||
$capture /tmp/经验库
|
||
```
|
||
|
||
说明：
|
||
|
||
- 目录由调用时显式指定，不绑定 `doc/`
|
||
- 输出文件名：`YYYY-MM-DD-task-slug.md`
|
||
- 文件内容只包含一个 fenced `yaml` code block，便于复用和提取
|
||
|
||
### 统一 Gitea 入口
|
||
|
||
先配置环境变量：
|
||
|
||
```bash
|
||
export GITEA_TOKEN=your_gitea_token
|
||
export GITEA_BASE_URL=https://git.example.com # 可选；owner/repo 简写或 SSH origin 时推荐配置
|
||
```
|
||
|
||
Claude Code:
|
||
|
||
```bash
|
||
/gitea 看当前仓库 open issues
|
||
/gitea 查 issue 7
|
||
/gitea 把这个 bug 拆成两张 issue
|
||
/gitea push
|
||
/gitea 给当前分支开 PR 到 main
|
||
/gitea 看当前仓库 open PR
|
||
/gitea 在 PR 12 留言：已完成回归
|
||
```
|
||
|
||
Codex:
|
||
|
||
```text
|
||
/gitea 看当前仓库 open issues
|
||
/gitea 查 issue 7
|
||
/gitea 把这个 bug 拆成两张 issue
|
||
/gitea push
|
||
/gitea 给当前分支开 PR 到 main
|
||
/gitea 看当前仓库 open PR
|
||
/gitea 在 PR 12 留言：已完成回归
|
||
```
|
||
|
||
说明：
|
||
|
||
- `gitea` 是统一入口，会按自然语言自动路由到 issue、issue-drive、push 或 PR
|
||
- push 默认先预检，再执行；只有明确要求 force push 时才会强推
|
||
- PR v1 只支持同仓库 list / create / comment
|
||
- 直接 `/gitea 看 issue 7` 或 `/gitea push` 时，skill 会优先从当前项目的 `git origin` 自动识别仓库
|
||
- 传 `owner/repo` 时，需要 `GITEA_BASE_URL`
|
||
- 当前仓库 `origin` 是 SSH 地址时，建议配置 `GITEA_BASE_URL`，避免 Web/API 域名与 SSH 域名不一致
|
||
|
||
### 专用入口：查询 Gitea Issues
|
||
|
||
Claude Code:
|
||
|
||
```bash
|
||
/issue
|
||
/issue 7
|
||
/issue owner/repo
|
||
/issue https://git.example.com/owner/repo
|
||
/issue https://git.example.com/owner/repo --state=all --limit=20
|
||
/issue https://git.example.com/owner/repo 7
|
||
```
|
||
|
||
Codex:
|
||
|
||
```text
|
||
/issue
|
||
/issue 7
|
||
/issue owner/repo
|
||
/issue https://git.example.com/owner/repo
|
||
/issue https://git.example.com/owner/repo --state=all --limit=20
|
||
/issue https://git.example.com/owner/repo 7
|
||
```
|
||
|
||
### 专用入口：创建 Gitea Issues
|
||
|
||
Claude Code:
|
||
|
||
```bash
|
||
/issue-drive
|
||
```
|
||
|
||
Codex:
|
||
|
||
```text
|
||
/issue-drive
|
||
```
|
||
|
||
自然语言也可以：
|
||
|
||
```text
|
||
请用 issue-drive skill 把当前仓库这个线上 bug 拆成两张 Gitea issue
|
||
请用 issue-drive skill 给 owner/repo 创建一张工程任务 issue，内容是补齐告警和回归测试
|
||
```
|
||
|
||
`issue-drive` 会优先从当前仓库 `origin` 推断目标仓库；如果你显式指定其他仓库，skill 会按用户输入创建 issue。
|
||
|
||
### 工作流总览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 0->1 全新项目 │
|
||
│ │
|
||
│ 需求 → wp → wf → wd → wt → go 🚀 │
|
||
│ │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 1->100 持续迭代 │
|
||
│ │
|
||
│ 发现问题 → iter → go 🚀 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 文档定位
|
||
|
||
| 文档 | 定位 | 受众 |
|
||
|------|------|------|
|
||
| PRD | 「价值主张」- 业务语言描述产品价值 | 产品、业务、管理层 |
|
||
| FeatureSummary | 「功能契约」- 精确定义功能边界 | 产品与开发的桥梁 |
|
||
| DevelopmentPlan | 「执行蓝图」- 技术方案和排期 | 开发团队 |
|
||
| UIDesign | 「界面蓝图」- ASCII 原型图 | 前端开发 |
|
||
| tasks | 「任务清单」- 可执行的开发任务 | 开发执行 |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
your-project/
|
||
├── AGENTS.md # ← Codex 项目入口（Codex 模式）
|
||
├── CLAUDE.md # ← Claude Code 项目入口（Claude 模式）
|
||
├── .codex/
|
||
│ └── skills/ # ← Codex Skills 安装位置
|
||
│ ├── rr/
|
||
│ ├── rp/
|
||
│ ├── ...
|
||
│ ├── iter/
|
||
│ ├── capture/
|
||
│ ├── gitea/
|
||
│ └── issue-drive/
|
||
├── .claude/
|
||
│ └── skills/ # ← Claude Code Skills 安装位置
|
||
│ ├── rr/
|
||
│ ├── rp/
|
||
│ ├── ...
|
||
│ ├── iter/
|
||
│ ├── capture/
|
||
│ ├── gitea/
|
||
│ └── issue-drive/
|
||
├── doc/ # ← 文档输出位置
|
||
│ ├── RequirementsDoc.md
|
||
│ ├── PRD.md
|
||
│ ├── FeatureSummary.md
|
||
│ ├── DevelopmentPlan.md
|
||
│ ├── UIDesign.md
|
||
│ └── tasks.md
|
||
└── ...
|
||
```
|
||
|
||
## 标记规范
|
||
|
||
Skills 使用注释标记追踪文档变更：
|
||
|
||
```markdown
|
||
<!-- NEW START -->
|
||
新增内容...
|
||
<!-- NEW END -->
|
||
|
||
<!-- MODIFIED: 原内容为 "xxx" -->
|
||
修改后的内容
|
||
|
||
<!-- ITER: 2024-01-23 - 修复登录验证漏洞 -->
|
||
迭代变更内容
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|