需求开发前为什么要设置上下文门禁

让 Agent 根据一句“把导出做一下”直接修改代码，速度很快，返工也很快。需求开发的第一项产物不应该是代码，而应该是一份可复核的上下文摘要。

先确定唯一工作项

同一标题可能出现在多个项目、迭代或子任务中。Harness 要通过明确链接或 ID 定位工作项，并读取类型、当前节点、负责人、更新时间和关联文档。候选不唯一时必须让人确认，不能选择“最新的那个”。

文档链接不等于正文可读

工作项常只保存设计文档链接。只有真正取得正文和修订信息，才能把它作为需求证据；没有读取权限时，应明确指出哪些行为或验收条件未知。界面稿、接口约定、附件和评论也要分别处理，不能把一个可见标题当成完整输入。

把描述改写成验收条件

摘要至少包含：目标用户、触发条件、正常流程、异常流程、权限、兼容性、数据迁移、可观测性和不在范围内的事项。每条验收条件应映射到候选入口、契约、数据流和测试层级，而不是泛泛写“功能可用”。

开发前后都要校验漂移

开始实现时保存工作项更新时间、关键评论边界、附件摘要和文档版本。验收前重新读取；如果范围、接口、版本或验收条件已经变化，旧结论立即失效，应重新确认而不是继续交付。

最小实践模板

开发前评审只回答五个问题：我们在解决谁的什么问题？什么结果可机器验证？哪些系统受影响？哪些信息仍不可读？本次授权是否允许外部写入？五项都明确后，Agent 才从“理解需求”进入“修改实现”。

第二轮实践复核

可复用交付物： 需求上下文摘要、验收映射和漂移检查记录。这些内容是从工程实践抽象出的通用方法，不包含内部仓库、真实工作项、业务数据、凭据、地址或实现源码。

最低验收： 开发前后两次读取的范围、接口与验收条件一致，否则旧结论作废。验收记录必须分开事实、推断、缺口和授权范围；只读检查不能自动扩展为提交、推送、评论或发布。

上下文摘要的结构化契约

work_item:
  id: REQ-241
  revision: "2026-08-22T09:15:00Z"
  type: feature
goal: "运营人员可导出当前筛选结果"
actors: ["具有 export:orders 权限的运营人员"]
acceptance:
  - id: AC-1
    given: "结果不超过 100000 行"
    when: "用户提交导出"
    then: "系统创建异步任务并返回可追踪 task_id"
  - id: AC-2
    given: "用户无导出权限"
    when: "调用导出接口"
    then: "拒绝且不创建任务"
unknowns:
  - "导出文件保留时间尚未确定"
out_of_scope: ["跨租户合并导出"]
authorization: "read repository; edit working tree; no external publish"

摘要必须给每条验收条件稳定 ID，后续设计、代码、测试和发布证据都引用它。unknowns 不是附录：若影响安全、数据格式、权限或不可逆迁移，应让门禁保持 blocked；不影响首个可逆切片的未知项可以记录负责人和截止时间后继续。

需求到实现的覆盖矩阵

验收条件	入口/契约	数据变化	测试	观测	状态
AC-1	`POST /exports`	export_jobs 新记录	契约 + 集成	创建率、失败率、队列年龄	planned
AC-2	权限中间件	无	越权用例	拒绝审计	planned

矩阵能暴露“正常路径写了代码，但无权限分支没有测试和审计”的缺口。不要把代码搜索命中自动等同于覆盖；每项状态需要具体证据链接或本地路径。

漂移检测与决策

实现前保存工作项修订号、附件摘要和关键评论 ID；验收前重新获取并做语义分类：文案澄清可以继续，接口、权限、范围、迁移或验收变化必须重新评审。若来源不可访问，不从缓存摘要推断“应该没变”。

用五组 fixture 测试门禁：唯一完整需求、同名多候选、附件无权限、开发中修订、恶意评论要求扩大权限。断言它们分别进入 ready、needs_confirmation 或 blocked，并且门禁阶段没有提交、推送或外部写入。

公开规范

RFC 2119 规范性关键词

规范复核日期：2026-08-22。

小规模演练

定位唯一工作项，读取正文与附件，改写成可测试条件；实现前后各生成一次摘要并做差异。

失败注入： 故意提供一个缺字段、过期版本或无权限目标，确认流程停在预定门禁。
观测指标： 不可读关键字段数、验收条件覆盖率、开发中范围漂移数。
回滚方法： 需求漂移时停止旧实现并回到确认节点；不要用旧摘要继续交付。