Skip to content

README.md

Latest commit

 

History

History
54 lines (40 loc) · 3.25 KB

README.md

File metadata and controls

54 lines (40 loc) · 3.25 KB
Raw

Specs 方案

specs/ 用于记录复杂需求、重构、公共 API 变更和跨目录修复。它是普通的工程文档，不依赖 Cursor、Codex 或其他 AI 工具。

什么时候创建 Spec

以下情况建议先创建 Spec：

  • 修改公共组件 API 或行为契约；
  • 组件重构涉及多个文件、状态或交互路径；
  • 需要同时修改组件、示例、测试和站点文档；
  • Bug 根因复杂，或需要明确边界条件和人工验收步骤。

单行文案、格式调整和简单局部修复不要求创建完整 Spec。

「是否需要 Spec」与「是否需要更新日志」是两件独立的事：Spec 看「改动复杂度 / 碰公共契约」（面向开发者），更新日志看「用户感不感知」（面向用户），两者不能互相推导。最容易出错：行为不变的纯内部重构需 Spec（属于重构）但用户无感、不写更新日志——不要因"不写日志"就跳过 Spec。完整判断见 CONTRIBUTING.md「PR 更新日志规范」第 3 条。

标准目录

specs/
├── README.md
├── _template/
│   ├── spec.md
│   ├── plan.md
│   ├── tasks.md
│   └── acceptance.md
└── <number>-<short-name>/
    ├── spec.md
    ├── plan.md
    ├── tasks.md
    └── acceptance.md

目录编号按创建顺序递增，名称使用小写 kebab-case。已完成的 Spec 保留在仓库中，作为设计决策和验收记录。

操作流程

  1. 复制 specs/_template/，创建新的编号目录。
  2. 在 spec.md 中写清背景、目标、范围、非目标、行为契约和验收标准。
  3. 在 plan.md 中记录技术方案、影响范围、API 变化、风险和验证策略。
  4. 在 tasks.md 中拆分可执行任务，按 TODO、DOING、DONE 更新状态。
  5. 实现代码、测试、示例和文档；不要只更新 Spec 而不落地代码。
  6. 在 acceptance.md 中记录实际执行的命令、结果、未覆盖项和人工验收结论。
  7. Review 时同时检查实现是否满足 spec.md，以及 Spec 是否准确反映最终实现。
  8. 提交的代码必须与 spec.md 定义的行为契约、验收标准一致；若实现偏离 Spec，需先修订 Spec 再改代码，避免文档与实现长期分叉。
  9. PR 描述「更新日志」小节须与 Spec 描述一致，只记录用户可感知的实际变更（目标受众是用户，非开发者 / 维护者）；内部 / CI / 文档结构调整等用户无需感知的改动不写日志，勾选「本条 PR 不需要纳入 Changelog」；breaking change 使用 breaking commit type，如 - breaking(toast): 调整 xxx 默认行为，会自动归入 Breaking Changes 分组。commit type 与最终分组的对应关系见 CONTRIBUTING.md（tdesign-component/CHANGELOG.md 由 CLI 自动生成，无需人工维护）。

文档边界

  • spec.md 记录“要解决什么问题”和“最终应满足什么行为”。
  • plan.md 记录“准备如何实现”。
  • tasks.md 记录“还剩哪些工作”。
  • acceptance.md 记录“实际验证了什么”。

如果实现过程中方案发生变化，先更新 Spec，再继续修改代码；不要让文档和实现长期分叉。