spechub-best-practices

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

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 字段作为默认路径。

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

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

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

核心操作速查：

# 检出项目
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。