get-shit-done 仓库 ADR/PRD 文档命名规范升级：以 issue 前缀 slug 命名取代本地顺序编号-平芜编程栈

人工智能
AI 应用
提示工程
开发工具
工作流自动化
AI Agent

【免费下载链接】get-shit-done

A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.

项目地址：https://gitcode.com/GitHub_Trending/getshi/get-shit-done

点击查看免费下载

导读

本文围绕 get-shit-done（GSD）仓库的一条 changeset 变更记录（.changeset/zesty-goats-dart.md，type:Changed，PR #3487）展开：ADR（架构决策记录）与 PRD（产品需求文档）文件从此统一改用docs/adr/<issue#>-<slug>.md/docs/prd/<issue#>-<slug>.md的 issue# 前缀 slug 命名，而旧的本地计算顺序编号（NNNN-*）仅作为不可变历史记录保留。读完本文，你将掌握：为什么本地顺序编号必然撞号、新旧命名格式的精确形态、从提 issue 到合 PR 的完整流程、分支命名规则，以及仓库中对应的 README、源码与测试证据，可直接用于向本仓库提交新的 ADR/PRD。

变更全景：一条 changeset 说了什么

GSD 仓库采用 changeset 机制管理 CHANGELOG：每个有用户可见影响的 PR 在 .changeset/ 目录下放置一个<随机词>-<随机词>-<随机词>.md变更片段，发布时统一合并进顶层 CHANGELOG.md。片段格式为 frontmatter + 正文（见 .changeset/README.md）：

--- type: Fixed pr: 1234 --- **`/gsd-foo` no longer drops trailing slashes** — explain the user-visible change.

type允许的值遵循 Keep a Changelog：Added、Changed、Deprecated、Removed、Fixed、Security。本文关联的 zesty-goats-dart.md 属于Changed类型，其正文原文为：

ADR and PRD files now use issue#-prefix slug naming(docs/adr/<issue#>-<slug>.md,docs/prd/<issue#>-<slug>.md). The legacy local-compute sequential scheme (NNNN-*) is retained for the existingdocs/adr/0001-*through0011-*files as immutable historical record but cannot be used for new ADRs/PRDs — collisions where two parallel PRs picked the same number prompted the change. See CONTRIBUTING.md "Proposing an ADR or PRD" for the full process.

也就是说，这次变更包含三个关键决定：

新文件必须使用 GitHub 分配的 issue 编号作为文件名前缀；
旧文件docs/adr/0001-*至0011-*保留为不可变历史记录，不得重编号；
变更的诱因是两个并行 PR 独立选中了同一个编号，产生了文件名冲突。

为什么必须放弃"本地计算下一个编号"

要理解这次命名变更的必要性，先回到旧的本地顺序编号方案（NNNN-*）。它的工作方式是：贡献者查看当前docs/adr/目录里最大的编号，然后本地加一作为自己的新编号。

这个方案有两个致命问题：

其一，本地计算不具原子性。两个开发者各自基于自己的main分支快照计算"下一个编号"，会独立得出同一个整数，两个并行 PR 都提交该编号的文件，合并时即发生碰撞。这正是 docs/adr/README.md 中记录的情况：冲突已经真实地留在了磁盘上——0010-*存在两个文件，0011-*存在三个文件。

看实际目录即可验证（docs/adr/ 当前内容）：

docs/adr/ ├── 0001-dispatch-policy-module.md ├── 0002-command-contract-validation-module.md ├── ... ├── 0010-file-operation-engine-module.md ← 重复编号 1/2 ├── 0010-skill-surface-budget-module.md ← 重复编号 2/2 ├── 0011-review-default-reviewers-prd.md ← 重复编号 1/3 ├── 0011-review-default-reviewers.md ← 重复编号 2/3 ├── 0011-skill-surface-budget-module.md ← 重复编号 3/3 ├── 0012-command-routing-hub.md ├── 3524-cjs-sdk-hard-seam.md ← 新规范示例 └── 3660-runtime-artifact-layout-module.md ← 新规范示例

其中0010-*的双份与0011-*的三份，在 README 中被明确标注为"旧本地计算约定的残留产物（documented residue of the old local-compute convention）——不是值得模仿的模式"。

其二，GitHub issue 编号是服务端分配、全局唯一的。与本地计算不同，一旦你打开一个 issue，该编号立即被 GitHub 原子性地保留，任何其他人都拿不到同一个编号。因此，两个 PR 各自以不同 issue 编号作前缀，永远不会撞名。

这与 changeset 机制的设计思路完全同构：.changeset/README.md 解释过，两个 PR 同时编辑CHANGELOG.md的### Fixed块必然在合并时冲突，而两个 PR 各添加一个随机命名的独立片段则因为不共享行而永不冲突。ADR 命名同理——0011-*撞号与"双 PR 共改 CHANGELOG 冲突"是同一类并发问题，issue# 前缀方案就是它的一致性解法。

新旧命名规范对照

维度	旧规范（已废弃）	新规范（现行）
文件名格式	`NNNN-<slug>.md`（本地计算顺序号）	`<issue#>-<slug>.md`（GitHub 分配的 issue 号）
ADR 路径	`docs/adr/NNNN-<slug>.md`	`docs/adr/<issue#>-<kebab-slug>.md`
PRD 路径	（历史上混在`docs/adr/`中，如`0011-review-default-reviewers-prd.md`）	`docs/prd/<issue#>-<kebab-slug>.md`
编号来源	本地扫描目录最大值 + 1	打开 issue 后由 GitHub 分配
冲突风险	高（并行 PR 撞号）	无（编号全局原子分配）
历史文件	—	`docs/adr/0001-`~`0011-`保留为不可变记录，禁止重编号

新规范下，slug 采用 kebab-case（连字符小写）。仓库中已落地的实例：

ADR：docs/adr/3524-cjs-sdk-hard-seam.md（issue #3524）
ADR：docs/adr/3660-runtime-artifact-layout-module.md（issue #3660）
PRD：docs/prd/3524-cjs-sdk-hard-seam.md（issue #3524）

注意 ADR 与 PRD 可以共享同一个 issue 号（如 #3524 同时存在docs/adr/3524-*与docs/prd/3524-*），因为路径不同，文件名不会冲突；两者在内容上通过"Related PRD / Related ADR"字段互相引用。

完整流程：Proposing an ADR or PRD

命名变更的完整工作流记录在 CONTRIBUTING.md 的"Proposing an ADR or PRD"一节。该节开宗明义：ADR 记录一个重大的架构决策，PRD 捕获一个功能在实现之前的 what 与 why，两者都遵循与项目其他一切事项相同的issue-first（先提 issue）规则。流程共四步：

打开一个合适类型的 issue 并完整填写：enhancement（重访既有领域的 ADR）、feature（新的架构面）、chore（策略/文档决策）。
等待维护者批准：维护者必须打上approved-enhancement、approved-feature标签，或确认 chore，之后才允许创建任何文件。
用 GitHub 分配的 issue 编号作为文件名前缀，在以 issue 命名的分支上创建文件：
- docs/adr/<issue#>-<slug>.md（ADR）
- docs/prd/<issue#>-<slug>.md（PRD）
- 分支名：docs/<issue#>-<slug>
用对应模板开 PR，并在 PR body 中以Closes #<issue#>关闭该 issue。

配套的硬性约束（CONTRIBUTING.md 原文要点）：

一个 issue = 一个 ADR 或 PRD = 一个 PR。禁止把多个决策塞进同一个文件或同一个 PR。
禁止本地计算"下一个编号"。任何用旧NNNN-*顺序模式命名新 ADR/PRD 的 PR，会在合并前被要求改名为<issue#>-<slug>.md格式。
拒绝理由清单：issue 在创建文件前未获批准；文件名用了本地计算顺序号而非 issue#；一个 PR 打包了多个决策；文件放错目录（docs/adr/vsdocs/prd/）。

CONTRIBUTING.md 还给出了命名示例：issue #3485 获批后，其编号成为前缀，生成docs/adr/3485-adr-prd-naming-convention.md，分支为docs/3485-adr-prd-naming-convention。在 docs/adr/README.md 中亦有3485-adr-prd-naming-convention.md、3464-review-default-reviewers.md等示例格式。

目录级约定：两份 README 的分工

新命名规范同时写进了 ADR 与 PRD 两个目录的 README，形成目录级的自文档化约定：

docs/adr/README.md：声明新 ADR 使用 issue# 前缀 slug 命名；解释 Why（两个开发者本地计算"下一个编号"会撞号，冲突已在磁盘上——0010-*两份、0011-*三份）；将0001-*至0011-*定义为不可变历史记录；末尾附完整 ADR 索引表（含 Status 字段：Accepted / Proposed / Superseded by 0011 / Reference 等），并说明 ADR-0005 是顶层 SDK seam 索引、各 seam ADR 之间的交叉引用关系。
docs/prd/README.md：声明 PRD 与 ADR 采用相同的 issue# 前缀 slug 命名；用docs/prd/3491-bar-feature.md（issue #3491 的示例）说明格式；指出历史文件docs/adr/0011-review-default-reviewers-prd.md早于本目录存在，保留为不可变历史记录，"不是值得模仿的模式"；并附 PRD 索引表。

两份 README 都将完整流程指针指向 CONTRIBUTING.md，形成"CONTRIBUTING 定流程 → 目录 README 定命名 → 文件内 frontmatter 定状态"的三层规范体系。

ADR 与 PRD 文件内部结构

新规范下的实际文件展示了统一的头部元数据结构。以 docs/adr/3524-cjs-sdk-hard-seam.md 为例，其开头为：

# CJS↔SDK hard seam — one source of truth per Shared Module - **Status:** Proposed - **Date:** 2026-05-14 - **Tracking issue:** #3524 - **Related PRD:** docs/prd/3524-cjs-sdk-hard-seam.md - **Extends:** ADR-0005 (seam map) - **Defers to:** ADR-0001, ADR-0003, ADR-0004, ADR-0006, ADR-0009

其配套的 docs/prd/3524-cjs-sdk-hard-seam.md 则为：

# PRD: CJS↔SDK hard seam — Shared-Module migration - **Status:** Reference - **Date:** 2026-05-14 - **Tracking issue:** #3524 - **Related ADR:** docs/adr/3524-cjs-sdk-hard-seam.md

可以看出：Tracking issue 字段与文件名前缀的 issue# 严格对应；ADR 与 PRD 通过 Related 字段互相链接；正文采用"决策 → 分节细节 → 后果 → 超出范围 → 修订记录（Append-only，用带日期标题追加而非改写）"的结构。ADR 的修订段明确写着"Append-only. Use a dated header when the decision evolves."——这是 ADR 文档的追加式演进约束。

仓库中的验证与测试证据

命名规范与 ADR 结构在仓库中并非仅靠约定维护，还有测试用例兜底：

tests/enh-3271-sdk-adr-structure.test.cjs：专门校验docs/adr/目录与 README 索引的一致性。它断言docs/adr/README.md必须存在且链接到每一个现有 ADR 文件（"README must link to every ADR. Missing: …"），并解析具体 ADR（如0005-sdk-architecture-seam-map.md、0006-planning-path-projection-module.md）的 title、status、date、headings 结构。这说明 ADR 文件不是自由格式，其 frontmatter 与章节结构受到测试约束。
tests/lint-docs-required.test.cjs：在文档变更强制检查（OK_DOCS_UPDATED）中识别docs/adr/、docs/agents/这类嵌套 docs 路径（如docs/adr/0099-new.md被判定为文档文件），并支持以docs/adr/0001-foo.md形式判断 docs 文件。这意味着对 ADR 文件的变更同样触发文档更新门禁。
tests/adr-parser.test.cjs：通过parseAdrMarkdown解析 ADR Markdown（sourcePath 如docs/adr/0010.md），校验options_considered等结构化字段——仓库中存在专门的 ADR 解析器用于消费 ADR 内容。
tests/contributor-standards.test.cjs：要求 docs/contributor-standards.md 必须包含 ADR 章节并引用docs/adr/目录，确保贡献者标准文档与 ADR 体系互相打通。

从源码结构可以推断：GSD 将"ADR 文档 → 解析器 → 测试"串成了一条可机器校验的链路，命名规范本身虽然主要靠 CONTRIBUTING 与 CI 的 rename 要求执行，但目录完整性（README 索引覆盖全部 ADR）与文档结构合法性已有自动化测试保障。

贡献者实操清单

如果你要向本仓库提交一个新的 ADR 或 PRD，按下列顺序操作即可一次通过：

先开 issue，不要先写文件。根据变更性质选 enhancement / feature / chore，完整填写模板。
等待维护者批准标签（approved-enhancement/approved-feature/ chore 确认）。未获批准前创建文件 = 直接拒绝。
记录 issue 编号。这是文件名前缀的唯一合法来源，禁止本地计算顺序号。
创建分支docs/<issue#>-<slug>，并创建文件：
- docs/adr/<issue#>-<slug>.md
- 或docs/prd/<issue#>-<slug>.md
- slug 用 kebab-case（如cjs-sdk-hard-seam、runtime-artifact-layout-module）。
保持一对一。一个文件只记录一个决策，一个 PR 只含一个 ADR/PRD。
更新目录索引。在 docs/adr/README.md 或 docs/prd/README.md 的索引表中登记新文件，否则enh-3271-sdk-adr-structure测试会失败（README 必须链接到每个 ADR）。
按模板开 PR，PR body 写Closes #<issue#>。若改动涉及用户可见行为，同时用 changeset 工具（node scripts/changeset/new.cjs --type <Added|Changed|Fixed|...> --pr <PR号> --body "一句话说明"）补充变更片段，发布时由node scripts/changeset/cli.cjs render --version vX.Y.Z --date YYYY-MM-DD统一合并进 CHANGELOG.md。
不要碰历史文件。docs/adr/0001-*至0011-*是不可变历史记录，即使存在0010-*双份、0011-*三份，也禁止重编号。

小结

本次Changed变更（PR #3487）本质上是把 ADR/PRD 文档的编号主权从"贡献者本地猜测"移交给了"GitHub 服务端原子分配"：文件名前缀由本地计算的顺序整数改为 issue 编号，彻底消除了并行 PR 撞号这一类并发缺陷；旧文件作为历史记录原样保留，新文件统一走<issue#>-<slug>.md格式。这套规范与 changeset 随机词命名、README 索引测试、CONTRIBUTING 流程共同构成了 GSD 文档治理中"并发安全命名 + 机器可校验结构"的完整闭环。