# Spechub Best Practices

> 编写高质量规约文档并通过 git worktree 管理的指南，用于 AI 间协同工作的任务交接。适用于任何需要 A 的 AI 产出文档让 B 的 AI 消费执行的场景。当用户提到联调文档、对接文档、spec、spechub、规约、写交接文档，或要为另一个团队/AI 准备工作规约，或在 SpecHub 仓库中操作时触发。包含通用规约框架和分类模板（当前支持：API 对接）。口语触发如"写对接文档"、"看下接口文档"、"更新spec"、"准备交接规约"、"新建spec分支"。

- Skill: `garveyhu/spechub-best-practices` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add garveyhu/spechub-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/garveyhu/spechub-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: garveyhu (https://skillmd.com/u/garveyhu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/garveyhu/spechub-best-practices

---


# SpecHub Best Practices

编写高质量规约文档并通过 git worktree 工作流管理的指南。规约文档是不同开发者的 AI 助手之间的任务交接桥梁——文档质量直接决定了接收方 AI 能否在零猜测的情况下正确完成工作。

**开始时声明：** "使用 spechub-best-practices 来[编写规约 / 管理规约工作流]。"

---

## 设计原则

无论哪种类型的规约，都遵循这些原则：

1. **显式优于隐式** — 所有约束、取值范围、边界条件都必须写出来。永远不要假设消费方"了解"你的上下文。
2. **示例即合约** — 一个完整的具体示例胜过十行抽象描述。描述和示例都要提供。
3. **负面约束同样重要** — "不要做 X"和"要做 Y"同等重要。明确告知消费方应该避免什么。
4. **自包含** — 规约必须在不访问源代码、数据库、设计稿或历史对话的前提下完全可理解。
5. **AI 优先，人类可读** — 用一致的标题、表格、代码块等结构化格式便于 AI 解析，同时保持人类可读。
6. **交代 Why** — 对每个重要决策说明原因。消费方 AI 理解了 why，遇到边界情况就能自行做出正确判断。

---

## 文件结构

每个规约模块遵循以下结构：

```
<模块名称>/
├── README.md              # 范围、阅读指引、通用约定、关键决策
├── CHANGELOG.md           # 变更记录（增量协作的关键）
├── 01-总览.md             # 全局视图：流程、依赖关系、执行顺序
└── 02-详细说明.md          # 逐项合约：完整的输入输出规格
```

多模块项目：

```
feature/<project>/
├── .gitignore
├── CHANGELOG.md           # 项目级变更记录（跨模块汇总）
├── <模块A>/
│   ├── README.md
│   ├── CHANGELOG.md
│   ├── 01-总览.md
│   └── 02-详细说明.md
└── <模块B>/
    └── ...
```

模块目录命名反映其内容即可，不强制后缀。01/02 文件的具体标题和内容结构因规约类型而异，见分类模板。

---

## 增量协作：CHANGELOG 驱动

生产方做了增量修改后，消费方 AI 不需要重新扫描全量文档去找区别。

**消费方增量工作流：**
1. `git pull` 拉取更新
2. **先只读 CHANGELOG.md 最新条目**
3. 按"消费方需要做什么"和"涉及文件和章节"，只读对应变更部分
4. 完成增量修改

**生产方义务：** 每次更新规约文档时，**必须同步更新 CHANGELOG.md**，否则增量协作形同虚设。

> 通用模板（README、CHANGELOG）和自检清单详见 `references/通用模板.md`。

---

## 分类规约模板

不同类型的协同任务需要不同的规约内容结构。根据任务类型选择对应模板：

| 模板 | 适用场景 | 参考文件 |
|------|---------|---------|
| API 对接 | 前后端联调、服务间接口对接、第三方 API 封装 | `references/API对接模板.md` |
| *(更多模板待扩展)* | | |

> 如果任务类型不在上表中，使用通用框架（`references/通用模板.md`），按任务特点自行组织 01/02 内容。设计原则和变更管理机制始终适用。

---

## SpecHub Git 工作流

通过 git worktree 管理多项目规约的检出、阅读、更新、推送。

### 仓库路径解析

所有 git 操作都在 SpecHub 仓库内执行。启动时按以下优先级确定仓库绝对路径：

1. **用户显式指定**：用户在调用 skill 时带上路径（如"在 /path/to/spechub 里更新 xxx 规约"），以用户指定为准。
2. **默认配置**：读取 `~/.agents/path.json` 的 `spechub` 字段作为默认路径。

```bash
# 默认路径读取
SPECHUB=$(jq -r '.spechub' ~/.agents/path.json)
```

后续命令统一使用 `$SPECHUB` 作为仓库根目录。若读取失败或字段为空，提示用户配置 `~/.agents/path.json` 或显式指定路径。

**仓库识别：** 进入 `$SPECHUB` 后，`.gitignore` 含 `specs/`、存在 `specs/` 目录、有 `feature/*` 远程分支——至少匹配两项即为 SpecHub 仓库。

**核心操作速查：**

```bash
# 检出项目
git -C "$SPECHUB" worktree add specs/<project> feature/<project>

# 消费方拉取更新
git -C "$SPECHUB/specs/<project>" pull

# 生产方推送更新（必须同步更新 CHANGELOG）
cd "$SPECHUB/specs/<project>"
git add . && git commit -m "<变更类型>(<模块>): <简述>" && git push
```

> 完整操作指南、新建分支流程、常见错误详见 `references/git工作流.md`。