二、任务分级标准与最高风险等级原则
2.1 按最高风险等级执行（Highest Risk Overrides）
重要
凡改动触及以下任一核心语义或运行行为，无论代码增删行数多少（哪怕仅改动 1 行），必须按 L3 级标准执行，不得降级：
- 资金与记账：金额计算、数值精度、舍入截断、账本流水、账户余额、支付/退款流转、订单资金状态机；
- 身份与权限：认证机制、JWT 校验、mTLS、Session、授权策略、租户数据隔离、密钥与敏感数据边界；
- 数据与持久化：数据库 Schema、数据迁移、破坏性 DDL/DML、数据订正/清理、数据恢复与重建脚本；
- 边界与对外契约：公开 API、事件消息 Schema、跨模块/跨服务分布式状态协作，以及引发多方契约变动的联合交付。
注：纯排版、错别字等不改变业务语义的修改按实际风险处理；修改规范中的业务决定、权限要求或验收口径，仍属于高危语义变更。
2.2 任务分级管控矩阵
| 级别 | 适用场景与边界 | 最小上下文载体 | 审查深度与方式 | 验证与环境隔离要求 |
|---|---|---|---|---|
| L1 (轻量) | 非敏感局部修正、文案或开发辅助改动 | 单张任务卡（目标、边界、依据、验收一体化） | 对照任务卡与适用规范；单份报告分两轴输出 | 仓库规定的编辑期/提交前检查；按冲突风险选择工作区 |
| L2 (标准) | 模块内常规特性、非破坏性重构、多文件联动 | spec.md + 简短计划，引用现有架构与规范 | Standards / Spec 双轴审查 | 受影响闭包验证、全量回归节拍；隔离工作目录及冲突资源 |
| L3 (高危/跨仓) | 命中任一高风险条件，或跨仓联合交付 | 需求与验收、设计/契约、必要 D-ID/ADR、测试与恢复方案 | 双轴审查；由具备领域责任的人类独立审查并签字（Sign-off） | 适用的全量验证与真实依赖集成测试、故障/幂等/持久化检查、制品冒烟；独立隔离测试资源 |
说明
- 级别决定验证深度，不代表机械运行所有无关测试；每项测试的适用性应在计划中说明，不适用、未运行和失败绝不能记为通过；
- L3 所需信息可整合在单一设计或任务文档中，不强制创建空文件；独立审批按领域职责判定，不以堆砌审查人数代替专业判断。
2.3 开工准备与就绪条件
本节承接第〇章已澄清并选入近期计划的需求，说明具体实现前的准备；它不替代需求价值判断、容量评估或版本取舍。
- 确认现状与权威：查阅项目入口、现行规范、有效决定与相关代码；检查工作区状态及并发任务，区分已实现的功能、设计目标与技术欠账；
- 明确需求与边界：明确用户画像、核心痛点、交付范围、非目标、成功与失败分支，确保验收口径可判定；
- 确定领域与契约：锁定数据责任方、领域不变量、状态机流转、接口契约、权限规则及失败恢复语义；
- 选择技术方案：优先复用成熟方案与现有依赖；对比必要备选方案，评估技术风险与环境约束；
- 完成必要决策：引用既有决策编号；对新权衡、设计冲突或推翻旧决定的事项取得正式决策，不得自行猜测；
- 设计验证与交付：将验收准则逐条映射至测试类型、环境要求、命令入口、责任人、证据形式与恢复步骤；
- 形成切片计划：按契约与依赖拆分为可独立验证的切片，明确各自完成条件，再进入第三章的实施循环；适用行为变更采用 TDD。
2.4 项目级文档体系与维护矩阵
以下定义信息职责而非硬性文件名；小项目可合并承载，每类事实只保留一个权威来源。
| 文档类型 | 适用时机 | 核心要素 | 维护责任人 |
|---|---|---|---|
| 需求池 / 产品路线图 | 持续收集、定期复查 | 需求来源、问题证据、目标、排序、依赖、取舍理由与状态权威链接 | 产品 / 需求负责人 |
| README / 项目总览 | 项目存续期间持续维护 | 项目定位、快速启动、核心模块、文档索引、关键联系人 | 仓库维护者 |
| AGENTS / 规范强制约束 | 多 Agent / 人员协作期间 | 开发强制约束、门禁与阻断规则、文档读取条件、命令入口映射 | 架构师 / 工程负责人 |
| 工程规范 | 技术栈选定或规则变更时 | 命名、分层调用、错误通道、并发、依赖准入、日志脱敏、配置演进 | 各技术领域负责人 |
| 产品需求与业务规则 | 功能立项及范围变更时 | 用户任务、业务规则、Non-goals、交付里程碑与验收范围；引用需求池和路线图的排序事实 | 产品 / 业务负责人 |
| 领域模型 / 术语词典 | 业务逻辑演进全周期 | 领域概念定义、实体关系、状态机流转、核心业务不变量 | 领域专家 / 业务架构师 |
| 架构总览与拓扑图 | 系统结构重大调整时 | 模块划分、数据流向、上下游依赖、网络拓扑与安全域划分 | 系统架构师 |
| 决策台账 (D-ID / ADR) | 涉及关键技术/业务选型时 | 决策编号、背景痛点、备选评估、决策结果、影响与后果、状态 | 决策发起人 / 审批人 |
| 接口契约 (SPEC / Schema) | 跨模块/跨服务接口设计时 | 协议规范、数据结构、幂等键、错误码、向后兼容性、结果未知时的处理方式 | 接口提供方负责人 |
| 安全设计 / 威胁模型 | 鉴权、敏感数据流向变更时 | 数据流图、潜在威胁、凭据范围、攻击面分析、缓解控制、验证责任 | 安全团队 / 核心研发 |
| Agent / 工具治理记录 | 首次接入 Agent、工具或权限变动 | 所有者、运行身份、工具来源、数据边界、拦截机制、审计与停止入口 | 工程负责人 / 安全管理员 |
| 测试策略与执行入口 | 业务实现前或测试体系演进时 | 测试分层、真实依赖与替身依赖、执行时机、命令、阻断规则、证据与盲区 | 测试架构师 / 研发负责人 |
| UI / 交互 / 无障碍规范 | 涉及人机交互界面开发时 | 信息架构、组件状态、响应式断点、键盘/焦点流、读屏语义、设计基线 | 前端负责人 / UI/UX 设计师 |
| 发布与运维手册 (Runbook) | 服务进入部署与持续运行时 | 构建打包、环境配置、数据迁移、观测指标、告警策略、故障处置 | SRE / 服务负责人 |
2.5 任务级文档清单
| 文档类型 | 编制时机 | 核心要素 | 裁剪与简化规则 |
|---|---|---|---|
| 迭代 / 批次计划 | 开始前及范围变化时 | 目标、容量、切片、依赖、审查与验证窗口、变更记录 | 复用现有计划或任务系统，不复制实现状态 |
| 版本计划 | 确定交付目标时 | 用户与环境、必备/可调整范围、目标窗口、退出条件、恢复与效果观察 | 发布准入时关联 Release Manifest；不以计划冒充回执 |
| 任务卡 / Intent | 开工前 | 痛点描述、目标用户、交付范围、非目标、强制约束、风险等级 | L1 任务单卡承载；已有需求直接引用链接 |
| SPEC 规格 | 实现具体行为前 | 输入输出契约、状态迁移、成功与失败语义、OPEN 范围、验收标准 | 可与任务卡或技术方案合并编写 |
| 技术方案 / RFC | 架构调整或关键取舍前 | 现状、备选方案、选型权衡、数据模型影响、风险、回退方案 | 沿用成熟设计时仅记录本次差异 |
| D-ID / ADR | 依赖该决定的实现前 | 最终决定、决策人、依据、收益与代价、替代关系 | 普通局部实现细节不单独立项 |
| 实施计划 | 切片前并动态维护 | 依赖拓扑、执行切片、跨仓协同人、资源预算、完成条件 | 文件清单属于可演进计划，严禁替代业务承诺 |
| 本次执行授权与例外 | 执行动作前，范围变化时更新 | 明确主体、工具、资源、环境、期限、预算、停止入口及例外到期时间 | 默认置于任务卡内；已有配置仅引用版本及差异 |
| 测试计划 / 向量 | 实现前设计，实现中扩充 | 验收映射、独立预期、边界用例、真实依赖、故障注入与变异测试 | 允许直接以可读代码用例与测试夹具承载 |
| 数据迁移方案 | 持久化变更前 | 版本基线、读写兼容策略、执行顺序、权限要求、回滚/向前修复 | 无数据变更的任务不创建 |
| Review 报告 | 规格就绪及实现冻结后 | 比较基线、两轴依据、缺陷发现、处置记录、复核确认、未审查范围 | Standards / Spec 两轴可合并在单份文档分节呈现 |
| EVIDENCE 验证记录 | 关键验证完成后 | 受测 Commit、执行命令、环境摘要、退出码、日志路径、覆盖边界 | 原始日志独立归档，正文保留可检索索引与结论 |
| Release Manifest | 跨仓联合交付或发布前 | 源码 SHA、制品摘要（Digest）、兼容矩阵、迁移校验和、配置引用、恢复方案 | 简单单仓发布复用原有发布记录 |
| 效果评估 / 复盘 | 版本观察窗口到期、迭代结束或问题处置后 | 目标与实际结果、交付瓶颈、故障证据、必要的根因分析、改进责任人 | 优先补充类型约束与自动化用例，最后补充规则文档 |
2.6 D-ID（决策编号）与 ADR 的联动机制
- D-ID（Decision ID）：项目内部业务与技术决策的唯一追踪编号（如
D-001）； - ADR（Architecture Decision Record）：重大技术与架构选型的论证记录。
两者互为补充：重大决策由 ADR 记录详细论证，由 D-ID 台账统一索引并指向最终决策；新项目亦可仅使用 ADR 承载完整的决策过程。
- 决策记录核心要素：问题背景、备选方案（含未选理由与调研日期）、最终决定、决策人、签署日期、收益与代价、退出/重评条件、生命周期状态（
Proposed/Accepted/Rejected/Superseded）、受影响依赖链； - 决策演进原则：已接受的决定发生改变时，必须新增记录并建立替代关系链接；
- 状态独立性：
Accepted仅代表决策本身获批，不等于代码已实现或已验收； - 完整追溯链：
需求/Issue➔D-ID / ADR➔当前 SPEC/契约➔提交 Commit➔测试向量➔执行证据➔Manifest/OPEN 项
2.7 协作契约与依赖协同顺序
接口双方开始编码前，必须明确：由哪个服务负责接口与数据的权威定义、数据如何产生、消费方需兼容哪些版本，以及各方的运行身份和对接负责人。
- 标准协作顺序：权威方发布契约 ➔ 消费方按约对接 ➔ 按依赖顺序完成对接 ➔ 验证权限与业务语义 ➔ 跨服务联合验收；
- 跨仓交付要求：源码之间存在依赖关系，并不能证明相关服务已部署到目标环境；各模块各自跑通单元测试，绝不能替代跨仓交付组合的端到端联合验收。
2.8 新项目或首次接入：建立最小可运行环境
首次建立基础设施后持续复用；工具链、契约或运行环境变化时维护并重新核验相关入口。若已有等价入口、文档和流水线，只需修补缺口，无需推翻现有目录或重命名。
第一步：整理入口，明确四类核心信息
以下是示例组织方式；也可合并为同一文档中的不同章节，保持每类信息只有一处正式记录。
text
AGENTS.md 开发强制约束、执行规则、其他文档的读取条件
docs/project.md 项目目标、模块/数据权威、现行方案与决策入口
docs/testing.md 真实命令、测试环境、触发条件、证据归档与失败处理
docs/tasks/T-001.md 首个任务卡：需求、验收、切片、实施与审查证据完成标准：新接手的 Agent 能顺利定位现行规则、本次任务与验证方式；每类结论仅保留单一权威位置。
第二步：查明命令并实际运行
Agent 从构建配置、包管理脚本与已有 CI 中查明执行入口，填写下表并实际运行，建立初始基线：
| 用途分类 | 登记与填写内容 | 首次接入时的验证动作 |
|---|---|---|
| 环境准备 | 工具链版本、基于锁文件的依赖安装命令、配置来源 | 在约定环境中完成安装；密钥仅记录引用 |
| 服务启动 | 实际启动命令、依赖服务、监听端口、健康检测、退出方式 | 应用真实启动并能正常响应退出信号 |
| 定向验证 | 如何指定当前模块或单条用例 | 修改目标代码后能获得稳定且可复现的反馈 |
| 提交前检查 | 实际脚本/命令、工作目录、触发时机 | 真实运行并确认退出码；如实记录失败或通过 |
| 完整回归 | 全量回归入口、条件门及真实依赖是否需单独启动 | 明确适用范围；缺失入口登记补齐责任人 |
| 集成与恢复 | 依赖服务启动、数据夹具、权限配置、库重建与清理入口 | 在自有测试资源上完整运行代表性用例 |
| 证据留存 | 日志落盘目录、版本与环境摘要记录方式 | 团队成员能依据路径找到并确认本次运行结果 |
完成标准：本次试点所需命令均已真实执行并留存基线记录，缺失项已登记补齐责任人。
第三步：让工具接管规则与执行
- 优先将重复操作封装为项目原生脚本，确保本地与 CI 执行完全相同的命令；
- 维护者配置并验证 CI 保护链路：事件触发 ➔ 干净环境执行 ➔ 命令失败使 Job 失败 ➔ 分支保护阻止合并 ➔ 由指定责任人处理失败；
- 验证 Agent 执行边界：在无敏感数据的隔离环境中，依次测试一次允许动作、一次越界拒绝与一次停止/撤权；无法拦截的操作严禁授予对应凭据。
第四步：用一个真实需求验收全套机制
按前文“快速上手”的六个步骤跑通首个真实任务（T-001），完成端到端验证，形成可复用闭环。