需求文档目录的更新与维护，关键在于把目录当作受控台账：先定层级、编号与字段口径，再明确新增、修改、拆分、合并、废弃、归档六类变更由谁在什么时点触发，用变更记录和评审留痕保证可追溯，最后以固定节奏核对目录与正文、状态、版本是否一致。本文给出可直接套用的结构、变更规则、角色分工与检查清单，并说明如何借助 ONES 承载目录条目与需求状态的同步。
要点总览（TL;DR）
- 先把目录结构定成受控台账：层级选业务域、版本或需求类型中的一种为主，编号全目录唯一且不复用，字段区分必填与选填。
- 把新增、修改、拆分、合并、废弃、归档六类变更各自绑定触发条件、更新动作和完成标志，并挂在评审与发布节点上同步执行。
- 角色按动作拆分：提出人、需求负责人、文档编写人、评审人、目录管理员各管一段；小团队可合并角色，但变更记录与交叉核对要保留。
- 维护采用日常即时更新加周期性集中核对：每周抽查活跃条目，每月或每季度全量核对编号、字段、状态与链接。
- 用完成检查清单验收：条目完整性、编号唯一性、变更可追溯为阻断项，状态、版本、链接问题限期修正。
目录结构先定规则：层级、编号与字段
目录能否长期维护，取决于第一版结构是否统一。建议先写一份《需求文档目录结构说明》，明确层级怎么分、编号怎么编、每条目录记录填哪些字段，之后所有更新动作都按这份说明执行，避免不同人按各自习惯增删条目。
层级划分的三种常用口径
层级决定目录的检索路径，选择时以团队查找需求的主要方式为准，不必三种全用。
- 按业务域划分：适合需求来源分散、按业务线归属清晰的团队，如“交易域—订单—下单流程”。优点是归属稳定，缺点是跨域需求需要约定主归属域。
- 按版本划分：适合按迭代或发布批次交付的团队，如“V2.3—需求清单”。优点是发布范围一目了然，缺点是长周期需求的跨版本追踪需要额外标记。
- 按需求类型划分：适合业务需求、产品需求、优化类需求并存的团队，如“业务需求／产品需求／缺陷转需求”。优点是分类清晰，缺点是类型边界需要事先定义。
实际落地常见做法是主层级选一种，次层级叠加一种，例如“业务域→版本→需求条目”，层级控制在三到四层，过深会增加维护成本。
唯一编号与命名约定
每条需求分配一个全目录唯一的编号，编号一经分配不再复用，需求废弃后编号保留并标记状态。编号规则可采用“域代码-年份-流水号”，如 TRD-2025-0187；命名采用“动词+对象+范围”的短句，如“支持订单批量导出”，避免“优化一下”“新需求”这类无法检索的名称。
目录条目字段表
| 字段 | 填写要求 | 必填/选填 | 说明 |
|---|---|---|---|
| 需求编号 | 按编号规则生成，全目录唯一 | 必填 | 分配后不复用 |
| 需求名称 | 动词+对象+范围 | 必填 | 与正文标题保持一致 |
| 状态 | 草稿／评审中／已确认／开发中／已发布／已废弃／已归档 | 必填 | 状态取值需在结构说明中固定 |
| 版本 | 与正文版本号一致，如 V1.2 | 必填 | 正文修订后同步更新 |
| 负责人 | 唯一责任人 | 必填 | 负责该条目的准确性 |
| 关联文档链接 | 指向需求文档正文 | 必填 | 链接失效视为目录缺陷 |
| 变更日期 | 最近一次目录条目变更的日期 | 必填 | 用于核对周期内是否有遗漏更新 |
| 所属业务域／版本 | 按层级口径填写 | 必填 | 决定条目在目录中的位置 |
| 关联需求编号 | 拆分、合并时填写来源或目标编号 | 选填 | 用于追溯需求演化关系 |
| 备注 | 特殊约定、依赖说明 | 选填 | 不承载正式结论 |
字段确定后写入结构说明并作为评审依据：新增条目缺必填字段不予通过，选填字段按需填写，避免为了填满表格制造无效信息。
六类变更的触发条件与更新动作
目录与正文脱节，多数发生在需求形态变化时只改了正文、没改目录。把六类变更各自的触发条件、更新动作和完成标志固定下来，更新就不再依赖个人记忆。
| 变更类型 | 触发条件 | 目录更新动作 | 完成标志 |
|---|---|---|---|
| 新增 | 需求通过初审、进入需求池 | 分配唯一编号，在对应层级下新建条目，填写全部必填字段，链接正文草稿 | 条目可检索，字段完整，正文链接可打开 |
| 修改 | 需求范围、验收标准或正文内容发生实质变化 | 更新版本号与变更日期，必要时调整名称，在变更记录中写明修改点 | 目录版本与正文版本一致，变更记录有修改说明 |
| 拆分 | 原需求范围过大，评审决定拆为多条可独立交付的需求 | 原条目状态改为“已拆分”并保留，新建子条目并填写关联需求编号指向原条目 | 原条目与子条目双向可追溯，子条目字段完整 |
| 合并 | 多条需求重复或高度重叠，评审决定合并 | 保留一条主条目，其余条目标记“已合并”并填写关联编号指向主条目，主条目补充合并说明 | 被合并条目不再作为独立交付对象，指向关系清晰 |
| 废弃 | 需求被取消、被替代或长期无推进价值 | 状态改为“已废弃”，写明废弃原因与替代需求编号，条目保留不删除 | 废弃原因可查，无悬空引用 |
| 归档 | 需求已发布且超过约定的活跃期，或项目结项 | 状态改为“已归档”，移入归档层级，冻结字段修改，仅保留查询 | 归档条目不再出现在活跃清单，历史信息完整 |
与评审、发布节点的衔接
变更动作要挂在已有流程节点上，而不是另设一套审批。需求评审通过时同步完成新增或拆分、合并的目录更新；版本发布时同步把状态推进到“已发布”并核对版本号；迭代收尾时集中处理废弃与归档。这样目录更新成为评审和发布的固定输出，评审记录本身也构成变更留痕。需要说明的是，拆分与合并涉及交付范围调整，应在评审结论中明确，目录只做如实登记。
角色分工与交付物：谁改、谁审、谁核对
目录维护出问题，通常是“大家都以为别人会改”。按动作拆角色，每个角色只对一件事负责，交接点写清楚，责任就不会悬空。
| 角色 | 目录更新中的动作 | 交付物 | 交接时点 |
|---|---|---|---|
| 需求提出人 | 提供需求背景、目标与范围，确认名称与归属域 | 需求说明或需求单 | 提交需求时 |
| 需求负责人 | 确认编号、状态与版本，对条目准确性负最终责任 | 确认后的目录条目 | 评审通过后 |
| 文档编写人 | 编写正文，保证正文标题、版本与目录条目一致 | 需求文档正文 | 正文定稿时 |
| 评审人 | 核对目录条目与评审结论是否一致，检查拆分、合并、废弃的登记 | 评审意见与结论 | 评审会上 |
| 目录管理员 | 执行条目增删改，维护编号序列，组织周期性核对 | 目录变更记录、核对报告 | 每次变更后、每个核对周期末 |
小团队的简化分工
三到五人的团队不必配齐五个角色。常见简化方式是：需求负责人兼任目录管理员，评审人由团队内另一名成员担任，文档编写人与需求负责人可为同一人。简化时保留两条底线：变更记录必须有人写，周期性核对必须由非本次修改人执行，避免自己核对自己。单人团队无法分离核对人时，至少保留变更记录，并在每个周期用清单逐项自查，把自查结果留档。
目录条目与需求状态、版本、变更记录的同步，可以在需求管理与文档工具中承载。ONES 通过统一的业务需求池与产品需求池管理需求，构建需求—任务—测试—缺陷的闭环；ONES Wiki 的页面组可关联项目，使需求与文档互相对应，并记录页面版本、支持查看与回滚。对于需要把目录条目挂在需求记录旁、随状态推进同步维护的团队，这种关联方式可以减少目录与正文两处分别维护的成本。具体字段配置与同步方式以实际使用环境为准。
一次完整的目录更新示例
以下为演示情景，用于说明目录条目在一条需求生命周期中的变化，不对应特定团队的真实项目。
某交易团队提出需求“支持订单批量导出”。
- 提出与新增：需求提出人提交需求说明，目录管理员分配编号
TRD-2025-0187，在“交易域—V2.3”下新建条目，状态填“草稿”，版本 V0.1，负责人填需求负责人，链接指向正文草稿。完成标志是条目可检索、字段齐全。 - 评审与确认：评审会上评审人核对条目与评审结论一致，需求负责人把状态改为“已确认”，版本升为 V1.0，变更日期更新，变更记录写“评审通过，范围确认为近90天订单”。
- 拆分：开发评估发现导出格式与权限控制可独立交付，评审决定拆为两条。原条目状态改为“已拆分”并保留，新建
TRD-2025-0201（导出格式）与TRD-2025-0202（导出权限），两条均填写关联需求编号指向 0187，变更记录注明拆分依据。 - 修改：开发中业务方要求增加“按客户维度筛选”，需求负责人更新 0201 的正文与版本至 V1.1，目录同步更新版本与变更日期，变更记录写明新增筛选维度。
- 发布：版本发布时，0201 与 0202 状态改为“已发布”，版本与正文发布版本对齐，变更日期更新为发布日。
- 废弃与归档：0187 作为已拆分条目不再独立交付，状态保持“已拆分”并在活跃期结束后归档；0201、0202 在发布满一个活跃期后状态改为“已归档”，移入归档层级，字段冻结。
这个示例体现的规律可以迁移到其他团队：编号只分配一次，形态变化用状态和关联编号表达而不是删除重建，每次变更都留下日期与说明，评审和发布节点承担同步动作。
维护节奏与一致性核对
目录维护靠两条线并行：日常变更即时更新，周期性集中核对兜底。只做即时更新，容易积累小偏差；只做周期核对，偏差会在周期内影响使用。
维护节奏表
| 节奏 | 动作 | 责任人 | 输出 |
|---|---|---|---|
| 每次变更发生时 | 按六类变更规则更新条目与变更记录 | 目录管理员或需求负责人 | 更新后的条目与变更记录 |
| 每次评审、发布节点 | 核对本次涉及条目的状态、版本与结论一致 | 评审人 | 评审记录中的目录核对结论 |
| 每周或每迭代 | 抽查活跃条目：链接可打开、版本与正文一致、状态未滞后 | 目录管理员 | 差异清单 |
| 每月或每季度 | 全量核对：编号唯一性、必填字段完整性、废弃与归档处理 | 非本次修改人 | 核对报告与整改记录 |
一致性核对清单
- 目录条目的名称、版本与正文标题、版本号逐条比对。
- 状态与需求实际进展比对，重点检查已发布需求是否仍显示“开发中”。
- 关联文档链接逐条打开，失效链接登记为差异。
- 拆分、合并、废弃条目检查关联编号是否双向可查。
- 变更日期晚于正文最后修改日期的条目，确认是否有未登记的正文改动。
发现差异时，由该条目负责人限期修正，目录管理员记录差异内容、责任人与处理结果；差异反复出现在同一环节的，回到结构说明或变更规则中修订，而不是每次靠人工补救。目录的历史记录建议保留两层：条目级的变更记录随条目保存，周期核对报告按时间归档，便于回溯某次状态或版本变化的原因。
完成检查：目录可用的判断标准
机制是否落地，用下面这份清单逐项判断，全部通过才算目录可用。
| 检查项 | 判断标准 | 不通过的后果 |
|---|---|---|
| 条目完整性 | 活跃需求均有对应条目，必填字段无空缺 | 需求无法检索，视为阻断项 |
| 编号唯一性 | 无重复编号，废弃编号未被复用 | 追溯混乱，需返工重编 |
| 状态准确性 | 条目状态与需求实际进展一致 | 发布范围判断失真，阻断发布核对 |
| 版本一致性 | 目录版本与正文版本一致 | 评审依据错误，需返工 |
| 链接有效性 | 关联文档链接均可打开 | 条目不可用，限期修正 |
| 变更可追溯 | 每次变更均有日期与说明，拆分、合并、废弃有原因和关联编号 | 无法回溯决策依据，视为阻断项 |
| 归档处理 | 已归档条目移出活跃清单且信息完整 | 活跃清单失真，需集中清理 |
其中条目完整性、编号唯一性、变更可追溯三项属于阻断项，未通过时暂停发布核对，先完成整改；状态、版本、链接类问题允许限期修正，但在修正完成前该条目不得作为评审或发布的依据。检查结果留档，作为下一周期核对的对照基线。
常见问题
需求文档目录的更新频率应该怎么定，多久核对一次比较合适？
更新频率分两层。日常层面，每次需求发生新增、修改、拆分、合并、废弃、归档时即时更新，不攒到固定时间集中改，否则变更记录容易漏写。核对层面，建议每周或每迭代抽查活跃条目，重点看链接能否打开、版本与正文是否一致、状态是否滞后；每月或每季度做一次全量核对，覆盖编号唯一性、必填字段完整性和废弃归档处理。团队需求量大、迭代快时缩短抽查周期，需求量小、变更少时可放宽到每两周抽查，但全量核对的周期不宜超过一个季度。
需求被拆分或合并后，原目录条目应该删除还是保留？
保留，不删除。拆分时原条目状态改为“已拆分”并继续留在目录中，新建子条目填写关联需求编号指向原条目；合并时保留一条主条目，其余条目标记“已合并”并指向主条目。保留原条目的作用是让需求演化关系可追溯：后续有人查某个编号，能看到它被拆成了哪几条、或并入了哪一条。删除原条目会切断这条线索，导致历史决策无法回溯。原条目在活跃期结束后可以归档，但归档只是移出活跃清单，信息仍需完整保留。
小团队人手少，目录管理员和需求负责人可以由同一人担任吗？
可以。三到五人的团队常见做法是需求负责人兼任目录管理员，文档编写人也可能由同一人承担。需要保留两条底线：一是变更记录必须有人写，每次改动留下日期和说明；二是周期性核对由非本次修改人执行，避免自己核对自己。单人团队无法分离核对人时，至少保留变更记录，并在每个周期用检查清单逐项自查，把自查结果留档，作为下一周期的对照基线。
目录里的条目和需求文档正文出现不一致，应该以哪个为准？
以正文的正式版本为准，目录负责如实登记。发现不一致时，先确认正文是否经过正式评审或发布：如果正文已定稿而目录未更新，由该条目负责人修正目录；如果目录先改了而正文未同步，需要回到正文补齐并重新确认版本。差异要记录内容、责任人和处理结果。同一环节反复出现差异的，说明结构说明或变更规则本身有缺口，应修订规则，而不是每次靠人工补救。
用需求管理工具承载目录，能解决哪些维护问题，哪些仍需人工保证？
工具能承载的部分主要是条目与需求记录的关联、状态推进和版本留痕。ONES 通过统一的业务需求池与产品需求池管理需求，构建需求—任务—测试—缺陷的闭环；ONES Wiki 的页面组可关联项目，使需求与文档互相对应，并记录页面版本、支持查看与回滚。这类关联可以减少目录与正文两处分别维护的成本。仍需人工保证的是：编号规则的执行、变更记录的撰写、周期性核对的组织，以及拆分合并等形态变化是否如实登记。具体字段配置与同步方式以实际使用环境为准。
