issue-pr-traceability-standard

# Issue/PR 关联与需求事实来源标准 其他工程标准回答的是**"怎么做、做到哪、怎么验"**；本标准回答更靠前的一个问题： **"这次到底要做什么，以谁说的为准，上下文从哪来。"** 没有这一层，闭环执行就退化成"人类反复粘贴需求和报错日志"—— Agent 有自主性，却没有权威输入。 ## 0. 边界：与其他标准的分工 本标准与既有标准**交叉互补、互不重复**。属于下表右列的内容，去对应标准查，本文不再复述： | 主题 | 归属 | | --- | --- | | 分支类型 / PR 目标矩阵 / 合并与发布 / tag 规则 | [`project-development-standard`](../project-development-standard/) | | PR 正文必填项、跨仓 companion PR 互链与合并顺序 | [`project-development-standard`](../project-development-standard/) | | 角色权限边界、红线、越权与泄露应急响应 | [`ai-agent-collaboration-standard`](../ai-agent-collaboration-standard/) | | CI/CD 编排、脚本外置、假绿防治的**流水线侧实现** | [`ci-cd-workflow-spec`](../ci-cd-workflow-spec/) | | 环境路由、OIDC/Vault 鉴权与密钥分层 | [`multi-environment-delivery-and-release`](../multi-environment-delivery-and-release/) | | Terraform / Ansible 的写法与状态隔离 | [`infrastructure-as-code-spec`](../infrastructure-as-code-spec/)、[`config-as-code-spec`](../config-as-code-spec/) | | 闭环循环本身的推进、重规划与回滚编排 | [`harness-workflow`](../harness-workflow/) | 本标准**只管**四件事：需求的权威载体、溯源链的标识符落点、自取上下文的义务、需求与验收的对应关系。 一个容易混淆的对照：`config-as-code-spec` 里的"CMDB 是**交付目标**的事实来源"回答"改哪台机器"； 本标准的"Issue 是**需求**的事实来源"回答"为什么要改"。两者是不同的轴，不冲突。 ## 1. 需求事实来源 1. **Issue（或等价的任务单）是唯一权威需求载体。** 对话记录、口头交代、截图、聊天里的补充要求， 都不是事实来源——它们是**尚未回写的输入**。 2. **无 Issue 不开工。** 收到没有 Issue 的任务时，先创建 Issue 并取得确认，再进入执行循环。 紧急止损可以先动手，但必须在同一轮内补登 Issue 并写明"事后补登"。 3. **Issue 必须包含**（缺一项就不具备开工条件，应先补全而不是猜）： - 目标：要达成的用户或工程结果，一句话说清； - 验收标准：可机器判定的条目（见 §4），不是"跑通了就行"； - 影响范围：涉及哪些仓库、哪些环境； - 约束：不能动什么、必须兼容什么。 4. **冲突时以 Issue 为准。** 对话里出现与 Issue 不一致的新要求， **先回写 Issue，再据此执行**；不得凭对话直接改代码而让 Issue 停留在旧版本。 回写这一步本身就是"人类确认"的载体。 ## 2. 溯源链 一次交付必须形成**双向可导航**的链条，任一环都能反查需求，也能从需求正查到产物： ``` Issue ──▶ branch ──▶ commit ──▶ PR ──▶ CI run ──▶ deploy record ──▶ tag ▲ │ └──────────────────── 关闭时回写证据 ◀──────────────────────────────┘ ``` 标识符的落点（**只规定放哪、不重复各标准已定义的格式**）： | 环节 | 承载需求标识的位置 | | --- | --- | | 分支 | 分支名带 Issue 编号（前缀仍按 `project-development-standard` 的类型矩阵） | | commit | 正文或 trailer 引用 Issue 编号；一个逻辑变更一个 commit | | PR | 正文用关闭关键字关联 Issue；跨仓时同时指向父 Issue | | CI run | 由 PR 关联自然获得，不额外标注 | | 部署记录 | 记录本次部署对应的 PR / tag，可反查回 Issue | | tag | 发布说明列出本次包含的 Issue 清单 | **断链即缺陷**：出现"改了代码但查不到需求"或"Issue 关了但找不到落地 PR"时，按缺陷处理并补链。 ## 3. 自取上下文：不得要求人类粘贴 **红线：Agent 不得向人类索取自己有权限、有工具取到的信息。** 需求正文、既有实现、变更历史、CI 失败日志——这些都属于必须自取的范畴。 | 需要什么 | 自取方式（示例，按实际工具链替换） | | --- | --- | | 需求正文与讨论 | `gh issue view <n> --comments` | | 关联 PR 的现状与评审意见 | `gh pr view <n> --comments` | | 变更历史与既有约定 | `git log`、`git diff`、读仓内既有实现与邻近测试 | | CI 结论 | `gh pr checks <n>` | | CI 失败详情 | `gh run view <id> --log-failed` | | 仓库结构与边界 | 仓内 `AGENTS.md` / `README` / [Repo Map](../references/) | 允许向人类索取的，只有三类：**权限之外**的信息、**判断题**（方案取舍、风险接受）、 以及**授权**（闸门确认）。除此之外张口要资料，视为违反本标准。 ## 4. 验收标准即证据契约 1. Issue 的验收标准必须写成**可机器判定**的条目——可以是命令与期望结果、可复查的 URL/编号、 可断言的探针，而不是主观描述。 2. **关闭 Issue 需要证据链**：PR 编号 + CI 结论 + （涉及部署时）部署记录。缺证据不得关闭。 3. **退出码 0 不等于验收通过。** 流水线侧如何防假绿属于 `ci-cd-workflow-spec`； 本标准只要求：验收标准必须写成"能证伪"的形式—— 一条无论做没做都会通过的验收标准，等于没有验收标准。 4. 部分完成时**不关闭**：拆出剩余项到新 Issue 并互相引用，而不是关掉再说。 ## 5. 范围漂移控制 - 实际要做的事超出 Issue 时：**先更新 Issue（或拆新 Issue），再继续动手**。 禁止让 PR 悄悄变宽而 Issue 停在原描述——那会让溯源链名存实亡。 - 一个 Issue 一条主线。顺手发现的问题另开 Issue，不塞进当前 PR。 - 需求被否决或作废：关闭 Issue 并写明原因，同时关掉其派生分支与 PR，不留悬空引用。 ## 6. 跨仓需求扇出 一个需求跨多个仓库落地时： - 建**一个父 Issue** 承载需求与验收标准，位置选在需求归属方（通常是发起变更的业务仓）； - 每个仓各自开 PR，**全部回指父 Issue**； - 各 PR 之间的互链、合并顺序、兼容窗口与回滚责任人，按 `project-development-standard` 的跨仓条款写； - **父 Issue 只在所有子 PR 落地且验收证据齐备后关闭**，不随第一个 PR 合并而关闭。 ## 7. 禁止模式 - 凭对话记录开工，Issue 停留在旧版本或根本不存在。 - 要求人类粘贴 Issue 正文、报错日志、diff 或 CI 输出。 - 验收标准写成"功能正常""跑通即可"这类无法证伪的描述。 - PR 范围超出 Issue 而不回写。 - 拿"CI 绿了"当验收依据却拿不出对应的证据条目。 - 父 Issue 在子 PR 尚未全部落地时提前关闭。