SRS Writer(严格需求文档撰写)
把用户的功能需求固化成可评审、可实施、可验收的正式需求规格说明书,评审通过后归档到项目 doc/srs/。
工作流
- 需求澄清:确认功能边界、目标、约束。主动套用项目的开发守则(最小改动、低耦合、UT 看护、静态检查满分)。
- 代码侦察(必做):读真实源码再写文档——
- 命令注册/参数解析(注册器register、参数解析器、必需参数校验装饰器)
- 数据/JSON 结构必须源码实读(serialize 实现),不猜字段;数据来源映射表逐字段对源码
- 错误处理现状(装饰器、已捕获异常、类型转换行为),保持"与现有实现一致"的边界 - 撰写 SRS:按模板章节结构,FR/TC/NFR/RK 编号,每条带优先级 + 可测试的验收标准。字段内容只写事实(实测/源码),不写猜测。
- 用户评审:交付评审;无意见即通过。
- 归档:通过后移动到
doc/srs/<SRS名>.md;草案(proposal)一并归档并注明被取代。项目若已用 CLAUDE.md,同步更新命令速查。 - 实施:按 FR + TC 逐条落地(遵循项目开发守则),DoD = 全量测试 + 静态检查满分。
编号约定
| 前缀 | 含义 | 编号 |
|---|---|---|
| FR | 功能需求(每项含优先级/描述/验收) | FR-1..n |
| TC | 测试场景(含前置/步骤/预期/优先级) | TC-01..n |
| NFR | 非功能需求(性能/兼容/质量) | NFR-n |
| RK | 风险(等级 + 缓解) | RK-n |
| G/C | 目标 / 约束 | G1.. / C1.. |
文档章节骨架(必含)
- 引言(目的/范围/术语/参考)
- 需求背景(业务背景/问题陈述/目标/约束)——"问题陈述"必须具体,避免空话
- 总体描述(产品视角/用户特征/运行环境)
- 功能需求 FR
- 数据需求(JSON 结构 + 数据来源映射表)
- 新增依赖(第三方/内部契约依赖,注明"不改")
- 测试需求(测试场景列表 + DoD)
- 非功能需求
- 性能评估(阶段开销分解 + 量化对比 + 结论)
- 风险
- 交付物与变更清单
- 里程碑
关键要点
- 数据来源映射表:JSON 每个字段 → 来源代码/函数 → 生成阶段,这是文档最值钱的部分,必须源码实读。
- 低耦合声明:新增功能若组合现有命令,列出"依赖命令契约表"(依赖的具体行为 + 不改)。
- 性能评估:分解各阶段开销(命令分发/缓存命中/冷路径),量化对比现状,结论明确"无劣化/收益在哪"。
- 测试场景列表:每条含前置/步骤/预期/优先级,优先覆盖缓存复用、参数变化、失败路径、命令行入口冒烟。
模板
templates/SRS_template.md— 通用可填模板(章节骨架 + 填写指引)templates/example_command_SRS.md— 实例:某 CLI 工具新增 export 命令的完整 SRS(示例用,已评审通过)
归档规则
- 目录:
<project>/doc/srs/(项目内,跟随版本控制) - 命名:
SRS_<feature>.md;历史草案命名<feature>_proposal.md,归档时注明"被 SRS_xxx 取代"
