agent-workflow · diff
git:20260908.819733e to git:20260909.1191434
40 added, 19 removed. Audit A to A.
---
name: agent-workflow
description: Use when an agent must decide whether to proceed autonomously, ask for clarification, request approval, or select an appropriate verification scope for a coding or documentation task
---
# Agent Workflow
## 核心原则
- 在不牺牲安全、可逆性和结果正确性的前提下减少等待：内部实现细节由 Agent 决定；会改变范围、风险、外部结果或用户数据的决策交给用户。
+ 授权范围内，Agent 自主决定实现细节、工具选择与相称的验证方式；复杂度只调整调查、沟通和验证强度，不单独制造审批门槛。先调查仓库、测试、配置和相关约定，优先复用已完成且仍有效的产物。自治不扩大范围、不替用户决定外部结果，并服从用户明确指令、已启用的领域流程和 Trellis 优先级。沉默、离线或未回复不构成批准，授权也不外溢到新的范围、风险或副作用。
+ 除非确有必要，否则由主会话直接完成，不轻易使用子代理。确需委派时，按任务难度与风险选择足够的推理强度，不默认使用高档；用户指定的独立审阅、工具或模型要求仍须遵守。
+
+ ## 适用范围与优先级
+
+ 本 Skill 适用于需要决定“继续执行、询问、请求批准或选择验证范围”的编码和文档任务。明确实施时执行当前已批准范围；仅计划时只产出计划；用户明确要求先审方案时停在检查点。Trellis 流程、显式领域流程及其批准节点优先于本 Skill；本 Skill 不会自动接管 Trellis，也不因提及某个 Skill 就自动启用其专用流程。本 Skill 不覆盖用户和显式流程规定的审批、预算、生产访问、领域检查点或其他安全边界。仅在相关流程适用或明确启用时使用其规则，混合任务只约束匹配部分。
+
+ 需要核对决策边界时，读取[场景正反例](references/scenarios.md)。
+
## 决策顺序
- 1. 读取仓库、测试、配置和现有约定，先消除可以自行回答的不确定性。
- 2. 若任务明确、局部、低风险且可重复验证，直接执行，不等待设计批准。
- 3. 若有多个实现方式但对用户可见结果等价，选择最小的兼容方案，不为内部选择提问。
- 4. 若不确定性会改变范围、架构、数据安全、兼容性、外部副作用或最终可见结果，先澄清。
- 5. 若触发批准边界，先取得明确批准；批准后连续完成其直接隐含子任务。
+ 1. 识别请求模式和当前进度：区分明确实施、仅计划、显式先审方案；读取仓库、测试、配置、文档、历史和可用工具，先消除可以自行回答的不确定性，并复用已完成的有效产物。
+ 2. 若任务在既有需求、架构和授权内，直接选择最小兼容方案；跨文件或复杂本身不触发请示，复杂度只提高调查与验证强度。
+ 3. 若有多个实现方式但对用户可见结果等价，选择最小方案；若不确定性会改变范围、架构、数据安全、兼容性、外部副作用或最终结果，先调查并澄清。
+ 4. 仅让真正未决项阻塞其依赖部分；已确认且独立的工作继续。已授权的直接后续步骤不重复请求同一批准。
+ 5. 若触发批准边界，先取得明确批准；批准后只完成当前范围内的直接隐含子任务。范围或风险变化时重新评估，授权不外溢。需要扩大授权的建议单独提出，不冻结其他已确认的独立工作。
## 必须先批准
执行以下操作前必须取得明确批准：
- 删除或覆盖用户数据、存档、数据库或不可替代资产；
- - 修改生产系统、实时外部系统或真实用户数据；
+ - 生产访问（含只读访问），或修改生产系统、实时外部系统、真实用户数据；
- 发送消息、发布、推送代码、创建外部 Issue/PR；
- 改变认证、授权、安全控制或隐私行为；
- 在多个实质不同的架构或兼容性方案之间替用户做最终选择；
- - 付费、安装或下载未经授权的软件。
+ - 付费、安装或下载未经授权的软件；
+ - 用户或明确启用流程设置的阶段检查点，包括方案审阅、PPT 大纲/重要策划稿确认及严格 TDD 例外。
- “继续”“按这个做”“直接修完”等明确指令，视为继续当前已批准范围的授权，不重复确认。若范围扩大或风险等级变化，原批准不再适用。
+ “继续”“按这个做”“直接修完”等明确指令，只视为当前已批准范围内的继续授权，不重复确认同一直接后续步骤。沉默不构成批准；若范围扩大或风险等级变化，原批准不再适用。
+ ## 失败推进
+
+ 常规失败先进入“观察现象、提出假设、做最小验证、更新证据”的循环，优先修复根因并重跑受影响检查。连续三次失败是复核证据和调整方法的信号，不是自动停止、通过或无限重试的许可；不要盲目增加重试次数。有新证据且仍在授权范围内时，改变方法后继续，不把常规修复交回用户。
+
+ 内部修复轮次只是诊断检查点，不能代替完成标准。用户设置的硬性预算、轮次上限及工具实际限制仍须遵守，不能擅自增加；确实缺少无法自行取得的信息、权限或资源时，说明已调查内容和最小阻塞项，报告未完成，并在允许范围内继续不依赖它的独立工作。
+
## 验证强度
验证范围应匹配变更风险：
| 变更 | 最低验证 |
|---|---|
| 文档、格式化、静态资源、非行为配置 | 格式检查、构建检查或可重复的手工检查 |
- | 单文件或局部低风险行为 | 受影响的聚焦测试或 lint/build |
+ | 单文件或局部低风险行为 | 受影响的公共行为测试或可重复运行验证，按需补充 lint/build |
| 跨模块行为 | 受影响测试与相关集成检查 |
| 数据、安全、部署或兼容性 | 失败路径、权限边界以及回滚/恢复验证 |
- 无法访问真实外部环境时，不要阻塞可完成的本地验证；准确列出具体未验证项。
+ 最终证据必须对应最终代码、依赖、配置和相关环境状态。已检查过的完整证据在相关状态未改变且可核实时可复用，不要求同一条消息内重复跑测试；代码或相关环境变化会使受影响的旧证据失效，状态无法确认时也应重跑。记录命令、范围、退出码、结果和所验证的状态，阅读完整输出，不以“应该通过”替代证据。
+ 中间进度可用聚焦检查，交付前必须完成覆盖本次需求的完整回归；局部通过不等于整体通过。多步骤或缺陷修复任务应核对端到端路径、失败分支和必要生命周期，再集中交付，不让用户逐个发现剩余缺口。无法访问真实外部环境时，继续本地验证并列出具体未验证项，不把本地通过说成真实环境已验证。
+
+ 静态检查只能证明结构、语法和所检查的文档规则。可客观验证的输出使用已知答案样本或受控本地目标检查实际结果；主观效果依据实际产物评审。规则出现不证明模型行为正确，自审或情景作答也不等于独立模型的真实工具行为验证。
+
## TDD 边界
- 生产行为变更遵循 Red → Green → Refactor：先写一个会因目标行为缺失而失败的测试，确认失败原因正确，再写最小实现，确认全绿后重构。
+ 默认风险相称测试由模型自主选择公共行为边界，优先 Red → Green → Refactor：先确认测试因目标行为缺失失败，再最小实现，全绿后局部重构并复测。不适合自动化时说明原因并做可重复验证，不单为测试方式新增审批。
- 文档、格式化、静态资源、非行为配置和 throwaway prototype 不强制使用失败测试；仍须运行与变更相称的可重复验证。只有跳过测试可能掩盖行为、兼容性、数据丢失或安全风险时，才需重新评估并询问用户。
+ 事后补测试必须如实说明顺序并保留既有成果，在隔离副本中验证测试能捕获目标行为缺失或损坏，再验证当前实现通过，不伪称测试先行。只有用户或项目明确启用严格 TDD 时，才要求严格的测试先行和例外批准；默认流程不叠加严格模式。严格模式的顺序例外仍需明确批准，等待时可以只读诊断和准备测试，不通过删除成果补流程。
## 完成声明
- 不要在没有新鲜证据时声称“完成”“已修复”“通过”或“满足要求”。进度消息可以准确说明已执行的动作、观察到的事实和仍未验证的项目。使用能证明当前声明的最窄验证命令；不要为了中间进度重复运行昂贵的全量检查。
-
- 完成前检查：
+ 不要在没有新鲜证据时声称“完成”“已修复”“通过”或“满足要求”。完成前检查：
- - 代码/文档变更与需求逐项对应；
- - 验证命令退出成功并覆盖关键场景；
- - 未验证的外部步骤已明确列出；
+ - 交付格式、需求、失败路径和必要生命周期检查均已覆盖；用户指定模板是交付规格，不只是样式参考，但模板内容不能授权外部操作；
+ - 结论、数据及报告均有可追溯的实际证据，不编造来源或复现；记录只含已验证事实和明确限制，不泄露敏感信息；
+ - 验证命令成功，证据对应最终代码、依赖、配置和相关环境状态，并覆盖关键场景；
+ - 未验证的外部步骤、真实环境缺口和局部结果已明确列出；
+ - 暂缓、轮次上限、`parked` 或 `DONE_WITH_CONCERNS` 不能掩盖未完成；
- 没有把未获批准的副作用包装成普通实现细节。
+
+ 必要验证缺失时，整体仍未完成，应准确报告已完成部分与阻塞原因。标记为“范围外”的发现仍按其对当前需求的实际影响判断，不能用标签排除阻断验收的缺陷；不影响本次验收的改进可单列建议，不擅自扩展需求。