shinpr 文档创建标准
本技能负责文档路由：即变更需要记录哪些会对后续工作产生长期影响的决策，以及每种文档存放在何处。“存放位置”中链接的每个模板负责该文档的内容与结构要求。
每种文档固定的内容
- PRD — 固定业务成果、当前需求、排除项以及后续工作所追溯的验收标准。其 AC ID 是设计与验证的稳定追溯键。实现设计属于设计文档，技术方案选型属于 ADR，任务顺序属于工作计划
- ADR — 固定一项会对后续工作产生长期影响的技术选择，以及在决策中败选的实质性不同备选方案，使后续工作能够区分已接受的决策与偶发的实现细节。完整的实现设计属于设计文档
- UI 规范 — 在实现之前固定界面结构、界面跳转、组件与状态契约、交互以及视觉验收标准。仅在这些决策尚未确定时创建；若具有代表性的仓库依据已经确定了这些内容，则复用已批准的 UI 规范，或直接进入设计文档
- 设计文档 — 记录已确认范围的完整实现设计：职责、流程、契约、变更影响以及验证边界。实现阶段将其视为主要技术基线，因此实现阶段不会擅自臆造缺失的“如何做”。当仓库依据推翻了技术上的“如何做”，而已确认的成果、目标状态需求和非目标仍然成立时，通过其所属工作流修正实现及受影响的技术产物，而无需重新打开产品需求
- 工作计划 — 固定依赖顺序、任务边界、可执行的验证方式以及最早可用的证明点。它引用设计细节，而非重复这些细节
- 任务文件 — 将一个可执行的工作计划成果、其约束来源、调查起点、写入职责以及可观测的验证方式带入实现阶段
创建决策矩阵
| 结构规模 | 基础文档 | 创建顺序 |
|---|---|---|
| Small（小型） | 无 | 直接实现 |
| Medium（中型） | 设计文档、工作计划 | 设计文档 -> 工作计划 |
| Large（大型） | PRD、设计文档、工作计划 | PRD -> 设计文档 -> 工作计划 |
对于前端/全栈工作，若相关决策尚未确定，应在设计文档之前新增 UI 规范。在设计文档之前完成任何符合条件的 ADR 批次。符合条件的 ADR 会将规模至少提升到中型。
对于 Large（大型）变更，可通过创建新 PRD、更新相关 PRD，或在没有现行产品文档时创建逆向工程 PRD 来满足 PRD 要求。无论规模如何，当产品范围发生变化时都应更新现有 PRD。
结构规模
按决策负担而非仓库层级来分类。文件数量仅作为辅助依据。
| 规模 | 决策负担 |
|---|---|
| Small（小型） | 单一连贯成果，在单一职责边界内有明显的、有仓库依据支持的实现方式，且不存在会对后续工作产生长期影响的未决选择 |
| Medium（中型） | 单一连贯成果，涉及跨边界协调或包含可能对后续工作产生长期影响的选择 |
| Large（大型） | 多个各自独立产生价值的成果，需要各自独立的设计决策 |
跨层实现如果服务于单一连贯成果，仍可归为 Medium（中型）。
ADR 决策过滤器
对已确认实现范围内的每个技术主题，依次应用“选择必要性（Choice）”和“长期影响（Durability）”这两个过滤条件。创建新记录前先检查已接受的 ADR。
- 选择必要性（Choice） — 已确认的需求、已采纳的决策以及具有代表性的仓库依据，至少留下两个可信且实质性不同的备选方案。
- 长期影响（Durability） — 在这些方案中做出选择，会实质性地改变职责、依赖方向、共享契约、持久化方式、技术选型、可逆性，或未来工作必须维持或理解的生命周期成本。
对通过这两个过滤器的每个主题创建一份 ADR，并将整个批次一并评审。将必须一起选择或一起重新考虑的选择归为一组；将可独立重新审视的决策分开。局部实现细节及其他成本低廉、易于逆转的选择属于设计文档。
存放位置
| 文档 | 路径 | 命名约定 | 模板 |
|---|---|---|---|
| PRD | docs/prd/ |
[feature-name]-prd.md |
prd-template.md |
| ADR | docs/adr/ |
ADR-[4-digits]-[title].md |
adr-template.md |
| UI 规范 | docs/ui-spec/ |
[feature-name]-ui-spec.md |
ui-spec-template.md |
| UI 规范附件 | docs/ui-spec/assets/{feature-name}/ |
原型代码文件 | - |
| 设计文档 | docs/design/ |
[feature-name]-design.md |
design-template.md |
| 工作计划 | docs/plans/ |
YYYYMMDD-{type}-{description}.md |
plan-template.md |
| 任务文件 | docs/plans/tasks/ |
{plan-name}-task-{NN}.md（仅含 backend 的计划）；{plan-name}-backend-task-{NN}.md（混合层计划中的 backend）；{plan-name}-frontend-task-{NN}.md（frontend） |
task-template.md |
生成路径中的变量必须使用小写 ASCII kebab-case slug。非 ASCII 输入应在构造路径前转换为该格式。
工作计划已在 .gitignore 中排除。
参考资料
每个模板定义了其文档的内容、状态规则、所需依据、可选图表以及完成检查项。仅加载正在创建或评审的文档所对应的模板。