crd

crd · 提出方的跨项目协作需求文档

固定由 CRD 的需求提出方使用，负责起草、修订需求、整合接收方回复和继续澄清；接收方一律使用 crd-respond，包括原样追加其已拟好的答复。先按当前代表的角色选择技能，不按「收到文档」或「追加回复」这些动作词选。

将本方向另一方提出的协作需求写成可独立阅读、逐项答复和持续跟进的 CR（Change Request），文档称为 CRD。这里的 QA 指 Q&A 问答澄清。双方都可能提出问题或补充意见，但不因此互换本份 CRD 的提出方与接收方。

默认以整份 CRD 往返协作：提出方形成 CRD → 发给接收方 → 接收方在收到的文档末尾追加答复 → 返回包含答复的完整 CRD → 提出方核对、整合并继续下一轮。CRD 本身承载需求、Q&A 和回复历史；聊天或邮件中的独立答复作为补充输入。

CR 讲清「谁需要另一方提供什么、为什么、怎样算满足、哪些问题尚未达成一致」。只展开协作边界所需的契约，不替对方编写内部实施方案，也不把写文档当作发送请求、接受需求或启动开发的授权。

1. 定位本次动作与事实来源

• 发起或修订需求：读取需求简报、相关代码/接口文档及已有 CR，形成可答复的需求条目。
• 提出方补充或答复澄清：核对接收方的反问、替代方案与条件，在文末追加本方澄清、补充需求或有依据的确认，交付完整 CRD；未获授权的表态标为草案，不代接收方决定接受需求或承诺交付。
• 整合对方返回的 CRD：读取返回文档、上次发出版本和本地当前版本，识别本轮新增答复与其他改动，按第 4 节整合并同步当前摘要，不要求用户另行摘抄已有回复。
• 收录接收方独立回复或续接 Q&A：先读完整 CR，尤其是末尾最新往返记录，再对照来信、聊天、评审意见等材料收录接收方实际回复并同步当前摘要，保留其发言归属，不替其拟造立场。

从已有上下文确定提出方、接收方、各自项目、协作目标、文档路径和当前代表的角色。若当前代表接收方，定位并读取可用的 crd-respond 后按其流程处理，不继续提出方流程；缺少技能时说明缺口，不虚构调用。角色无法确定且会改变本次动作时询问，不把当前仓库直接认作提出方。多方参与时，每条需求注明责任项目，不假设共享同一个仓库、版本或发布节奏。

只询问会改变需求对象、范围或答复归属的缺失信息，其余写「待确认」并继续完成可确定部分。拿不到对方仓库时，区分本方观察、对方陈述、推测和待核实事项；不把本方找不到的能力写成对方不存在。

每项事实保留可定位来源，如文件路径与段落、接口文档链接、消息日期与发言方。未知人员、日期、排期不补造；整理日期与原消息日期分别记录。拟稿不得冒称对方已回复。

2. 写出对方能逐项处理的需求

新建时读取 CR 模板，按实际规模删去不适用内容；更新既有 CR 时沿用其结构与编号，不强制重排。路径优先使用用户指定或仓库已有约定；没有约定时用 docs/cr/CR-<主题短名>.md。先查同主题文档，避免续谈时另建一份。

需求使用文档内稳定编号 R-01，问题使用 Q-01，往返记录使用 RESP-01；继承已有编号，新条目递增，撤销的编号不复用。它们是本地追踪号，不冒充外部系统 ID。

每条需求应包含：

• 场景与动机：谁在什么条件下需要什么；当前阻碍和不解决的影响。
• 请求与边界：希望接收方提供的可观察行为或交付物，以及提出方配合事项、非目标和前置依赖。
• 协作契约：仅写相关部分，如输入/输出、字段语义、权限、错误与重试、兼容版本、交接方式。已有契约标来源；尚未确定的设计明确标「提议」。
• 验收条件：给定前提和动作后应观察到的结果、必要的失败行为，由谁在什么环境或交付节点验证。可用具体示例，不用「正常工作」「支持对接」代替判据。
• 优先级与时间：说明影响与理由；区分提出方期望时间、接收方估计和明确承诺，不因写 CR 而编造截止日。

一条需求应能被独立答复和验收。小型协作请求不扩写为完整 PRD；不要求对方必须采用尚未达成一致的内部技术方案。

3. 维护 Q&A 与当前结论

Q&A 是双方待澄清事项的当前视图。每条记录问题、关联需求、提问方、待答方、是否阻塞及阻塞哪一步、当前回答/待确认点、状态和答复记录链接。

• 未知答案保持空缺含义明确；建议答案标为建议，不生成虚构问答。
• 回答部分问题时，仅更新对应条目；未答项继续待答。问题已回答不等于需求已接受，需求已接受不等于已交付。
• 单方提出的新范围、替代方案或时间安排，仍属待确认提议；达成一致的结论必须能指向有权限一方的明确确认，需双方确认的协作约定保留双方依据。
• 新答复与旧答复冲突时，在当前视图指出冲突及影响；只有明确撤回或替代旧意见时才采用新结论，否则保持待澄清，不能仅凭时间较新覆盖旧承诺。
• 需求、问题和答复互相引用。关闭问题需有实际回答及必要确认；关闭 CR 需有约定范围的验收证据，或明确的拒绝/撤回理由，不能用「已回复」代替闭环。

正文是当前工作视图：已确认内容写入需求与验收条件；未确认变更放在提议或待决项中。历史往返记录保留当时原意。正文与历史不同不等于错误，但须能追到变更依据。

4. 整份 CRD 往返与文末答复

交付给对方的版本

保持同一 CR 标识，注明当前文档版本及本轮基于的版本；沿用已有版本约定，无约定时可用 v1、v2 等区分交接版本。交付完整需求、Q&A 和全部往返记录，关键内容不只链接到对方无法访问的本地文件。接收方保留原需求与历史，在文末追加自己的答复；范围或验收的修改先写为建议。

本地保留可定位的发出基线（已有文件或版本控制记录即可），便于下轮核对，不为每次文字编辑制造新副本。尚未实际发出时称「待发送版本」；用户提供了发送事实后才记录为已发出。

整合返回文档

• 先核对 CR 标识与版本关系，再比较返回版本相对发出基线的变化，以及本地当前版本相对该基线的变化。文件名变化不代表新 CR，返回文件的时间较新也不代表可以覆盖本地。
• 对方已在文末写好的答复直接保留或并入一次，不把整份返回文档作为一条新回复再次粘贴。来源可定位到返回文件、版本及答复章节；保留原发言方和时间。
• 对方直接改了需求、验收、Q&A 结论或历史答复时，显式列出差异及影响；尚未确认的实质变更作为提议或冲突，不能静默成为双方已同意的新基线。保留既有历史，历史更正以追加记录承接。
• 本地也有新增内容时，合并互不冲突的增量；有冲突则保留双方意见并列入待确认项，不丢弃本地补充。并行副本发生编号碰撞时保留来源版本限定（如 v2-甲方/RESP-02），明确映射，不让一个编号指向两份不同内容。
• 缺少发出基线时仍可整理可识别的答复，但说明无法完整核实正文改动；缺少本地版本时可将返回 CRD 作为当前工作稿，保留来源和未核实范围，不声称完成了版本合并。

追加规则

所有轮次放在文档最后的「往返答复记录」中，按收录顺序追加；需求、Q&A、来源和其他章节位于它之前。提出方收录接收方的实际答复、追加本方补充及双方后续确认，均使用同一记录格式；记录他人回复不等于代表他人作答。

每次追加包含记录编号、发言方/项目、原消息时间（未知则注明）、整理时间、来源、关联 R/Q 编号、答复内容、未答项及下一步。拟答复显式标「草案，未发送/未确认」；收到的答复标「已收到」，但不据此推定内容已获双方认可。

• 原文引用必须与已读取材料一致；概括写成「整理摘要」，保留条件、否定、例外及承诺边界。大段原文可链接原件，并在记录内保留关键答复。
• 只追加新记录，不改写或删除已收录的历史答复。更正通过新记录引用被更正的编号，注明差异与依据；可以同步正文当前视图。
• 追加前检查来源标识和内容，重复导入同一答复不重复记账。相似但有新增条件的消息是新记录，注明变化。
• 一轮逐项对应 R/Q；无法可靠归属的答复保留原意并标「关联待确认」，不强行绑定。新的反问建立 Q 编号，链接该轮记录。
• 用户只要求「原样追加」时只追加与必要标识，不擅自重写需求或采纳方案；用户要求整理、同步或续接时，才按证据更新正文当前视图。

不通过邮件、聊天工具或项目系统发送 CR，除非用户另有明确授权；只负责落盘时无需增加发送审批步骤。生成文件不表示已送达接收方。

5. 回读与交付

检查新增/修改内容及关联位置：

• 当前代表提出方；接收方回复均来自实际材料而非代拟。双方角色、需求边界、配合事项和验收判据可理解，未知信息未伪装成事实。
• R/Q/RESP 编号唯一且引用可达；未答、部分接受、冲突和时间条件未丢失。
• 当前结论均有来源；草案、提议、已收到、已确认和验收完成没有混用。
• 历史答复未被覆盖，新记录位于文末；重复输入未造成重复追加。
• 返回版本的增量已核对，本地补充未丢失；交接版本保留完整上下文，正文改动与未确认分歧有明确归属。
• 相对链接正确，修改仅涉及本次 CR；不把文档检查报告成业务验收通过。

交付文档链接、这轮新增或变化的结论、仍待谁回答的阻塞问题。没有实际发送就说明「文档已保存，未发送」。

调用示例

使用 $crd，为订单项目向账号项目提出批量查询用户展示名的协作需求。
使用 $crd，站在提出方订单项目，答复账号项目的 Q-02，在文末补充查询用途与已有确认。
使用 $crd，站在提出方订单项目，这是账号项目返回的 CRD，请与上次发出版本及本地当前稿核对，整合新增回复并更新 Q&A。
使用 $crd，把下面收到的账号项目回复收录到订单项目的 docs/cr/CR-user-display-name.md，并同步需求与 Q&A 当前状态。
使用 $crd，作为提出方，将本方这段补充原样追加到现有 CR 末尾，保留正文。