| 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 来[编写规约 / 管理规约工作流]。"
设计原则
无论哪种类型的规约，都遵循这些原则：
- 显式优于隐式 — 所有约束、取值范围、边界条件都必须写出来。永远不要假设消费方"了解"你的上下文。
- 示例即合约 — 一个完整的具体示例胜过十行抽象描述。描述和示例都要提供。
- 负面约束同样重要 — "不要做 X"和"要做 Y"同等重要。明确告知消费方应该避免什么。
- 自包含 — 规约必须在不访问源代码、数据库、设计稿或历史对话的前提下完全可理解。
- AI 优先，人类可读 — 用一致的标题、表格、代码块等结构化格式便于 AI 解析，同时保持人类可读。
- 交代 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 不需要重新扫描全量文档去找区别。
消费方增量工作流：
git pull 拉取更新- 先只读 CHANGELOG.md 最新条目
- 按"消费方需要做什么"和"涉及文件和章节"，只读对应变更部分
- 完成增量修改
生产方义务： 每次更新规约文档时，必须同步更新 CHANGELOG.md，否则增量协作形同虚设。
通用模板（README、CHANGELOG）和自检清单详见 references/通用模板.md。
分类规约模板
不同类型的协同任务需要不同的规约内容结构。根据任务类型选择对应模板：
| 模板 | 适用场景 | 参考文件 |
|---|
| API 对接 | 前后端联调、服务间接口对接、第三方 API 封装 | references/API对接模板.md |
| (更多模板待扩展) | | |
如果任务类型不在上表中，使用通用框架（references/通用模板.md），按任务特点自行组织 01/02 内容。设计原则和变更管理机制始终适用。
SpecHub Git 工作流
通过 git worktree 管理多项目规约的检出、阅读、更新、推送。
仓库路径解析
所有 git 操作都在 SpecHub 仓库内执行。启动时按以下优先级确定仓库绝对路径：
- 用户显式指定：用户在调用 skill 时带上路径（如"在 /path/to/spechub 里更新 xxx 规约"），以用户指定为准。
- 默认配置：读取
~/.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
cd "$SPECHUB/specs/<project>"
git add . && git commit -m "<变更类型>(<模块>): <简述>" && git push
完整操作指南、新建分支流程、常见错误详见 references/git工作流.md。
