mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-20 23:54:26 +08:00
77 lines
1.9 KiB
Markdown
77 lines
1.9 KiB
Markdown
|
# 规格文档说明 / Specs
|
|||
|
|
|
|||
|
|
## 中文
|
|||
|
|
|
|||
|
|
### 目的
|
|||
|
|
|
|||
|
|
`.trae/specs/` 用来存放“一个需求从意图到落地”的协作文档，而不是长期产品说明。它适合记录功能变更、交互改造、重要修复和跨模块调整。
|
|||
|
|
|
|||
|
|
### 目录结构
|
|||
|
|
|
|||
|
|
每个功能目录建议使用：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
.trae/specs/<feature-name>/
|
|||
|
|
spec.md
|
|||
|
|
tasks.md
|
|||
|
|
checklist.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 每个文件的职责
|
|||
|
|
|
|||
|
|
#### `spec.md`
|
|||
|
|
|
|||
|
|
用于描述这次变更的意图和行为要求，建议包含：
|
|||
|
|
|
|||
|
|
- `Why`：为什么要做
|
|||
|
|
- `What Changes`：会改什么
|
|||
|
|
- `Impact`：影响哪些规范或代码区域
|
|||
|
|
- Requirements / Scenarios：可验证的行为要求
|
|||
|
|
|
|||
|
|
#### `tasks.md`
|
|||
|
|
|
|||
|
|
用于把实现拆成可执行任务，建议包含：
|
|||
|
|
|
|||
|
|
- 分阶段任务或模块任务
|
|||
|
|
- 依赖关系
|
|||
|
|
- 可并行项
|
|||
|
|
- 完成状态
|
|||
|
|
|
|||
|
|
#### `checklist.md`
|
|||
|
|
|
|||
|
|
用于验收与回归检查，建议包含：
|
|||
|
|
|
|||
|
|
- 关键 UI 或行为检查点
|
|||
|
|
- 构建、运行、测试检查点
|
|||
|
|
- 手工验证项
|
|||
|
|
|
|||
|
|
### 什么时候新建 spec
|
|||
|
|
|
|||
|
|
- 新增功能
|
|||
|
|
- 已有功能行为发生变化
|
|||
|
|
- 设置页、主界面、组件系统出现结构性调整
|
|||
|
|
- 插件系统、共享契约、SDK 接入方式发生变化
|
|||
|
|
|
|||
|
|
### 什么时候只更新现有 spec
|
|||
|
|
|
|||
|
|
- 同一 feature 的后续迭代仍属于原目标范围
|
|||
|
|
- 原 spec 仍是当前实现的权威描述
|
|||
|
|
- 只是补充场景、任务拆解或验收项
|
|||
|
|
|
|||
|
|
### 什么时候可以不写 spec
|
|||
|
|
|
|||
|
|
- 纯拼写修复
|
|||
|
|
- 纯内部重构且不改变行为
|
|||
|
|
- 只改注释、日志、文档索引等非行为项
|
|||
|
|
|
|||
|
|
### 与其他文档的关系
|
|||
|
|
|
|||
|
|
- 长期产品说明看 `docs/PRODUCT.md`
|
|||
|
|
- 长期架构说明看 `docs/ARCHITECTURE.md`
|
|||
|
|
- 开发运行方式看 `docs/DEVELOPMENT.md`
|
|||
|
|
- feature 级变更过程看 `.trae/specs/`
|
|||
|
|
|
|||
|
|
## English
|
|||
|
|
|
|||
|
|
Use `.trae/specs/` for feature-level change tracking, not for long-lived product or architecture documentation. `spec.md` defines intent and requirements, `tasks.md` breaks implementation into actionable work, and `checklist.md` captures validation and regression checks.
|