编码任务完成后做简化、加固与微文档自审（适用于非平凡代码改动…

当编码代理完成一个非平凡代码改动、准备宣告任务结束时，利用峰值上下文做一次有界的质量与安全自审。

适用场景

解决思路

1. 触发条件：仅当代理已完成主要编码任务、已发出完成信号（exit code 0、PR ready 等）、diff 属于非平凡代码改动、且本任务尚未运行过该技能时激活。
2. 非平凡改动判定：必须同时满足 (1) 触及至少一个可执行源文件（如 *.ts、*.tsx、*.js、*.jsx、*.py、*.go、*.rs、*.java、*.cs、*.rb、*.php、*.swift、*.kt、*.scala、*.sh）；(2) 可执行源文件中至少 10 行非注释非空白改动，或至少一处高影响逻辑改动（auth/authz 检查、输入校验、数据访问/查询逻辑、外部命令执行、文件路径处理、网络请求处理、并发控制）。
3. 范围硬约束：只触碰本任务修改过的代码；不得重构未修改的相邻代码、不得做“顺手改”的改进、不得引入新依赖或架构变更、不得基于别处模式做推测性修复；范围外问题只在摘要中标记，不实际动手。
4. 预算限制：额外改动最多为原始 diff 行数的 20%，最长执行 60 秒（可配置）；任一限制触顶即停止并输出已有结果，标记 budget_exceeded。
5. Pass 1 Simplify 默认姿态：以清理为主、不重构；偏向不改变结构的表面修复，重构是例外而非默认。
6. Simplify 强制“新鲜眼光”起点：编辑前先重新通读本任务新增或修改的全部代码，主动寻找明显 bug、错误、令人困惑的逻辑、脆弱假设、命名问题和遗漏的加固机会。
7. Simplify 检查清单：(1) 死代码与脚手架——删除调试日志、注释掉的尝试、未用 import、临时变量；(2) 命名清晰度——重命名实现过程中合理但事后读起来糟糕的函数/变量/参数名；(3) 控制流——扁平化嵌套条件、用提前返回替代深层嵌套、简化布尔表达式；(4) API 表面——减少不必要的公开方法/函数可见性；(5) 过度抽象——标记当前范围不合理的类/接口/包装函数，除非收益显著否则不重构；(6) 合并机会——标记逻辑分散，仅在重复严重且合并干净时才提议重构。
8. Simplify 动作分类：表面修复（删死代码、未用 import、命名、控制流收紧、降低可见性）在预算内自动应用；重构（合并、重构结构、改抽象）仅在确实必要或收益显著时提议，标准是“资深工程师会认为当前状态明显错误，而不只是不够完美”。
9. 重构停止钩子（强制）：任何被归类为重构的改动都必须触发交互式提示——描述要改什么及原因、展示 before/after 或清晰的结构变更说明、等待人工明确批准后才应用；不得批量提议重构，每个重构单独呈现，供人工逐项 approve/reject/modify；提供 [approve] [reject] [show diff] [skip all refactors] 选项；若选 skip all refactors，跳过剩余重构提议并进入 Harden，跳过的重构在输出摘要中标记为 flagged、状态 skipped_by_user；表面修复不触发停止钩子，静默应用并在摘要中报告。
10. Pass 2 Harden 目标：趁代理仍理解代码意图时关闭安全与韧性缺口，自问“如果恶意者看到这段代码，会尝试什么？”。
11. Harden 检查清单：(1) 输入校验——所有外部输入（用户输入、API 参数、文件路径、环境变量）使用前是否校验，检查类型强制转换、缺失边界检查、未约束字符串长度；(2) 错误处理——catch 是否具体、日志是否带上下文但不泄露敏感数据、是否有被吞掉的异常；(3) 注入向量——检查 SQL 注入、XSS、命令注入、路径遍历、模板注入；(4) 认证与授权——新端点/函数是否强制认证、权限检查是否正确、是否有提权风险；(5) 密钥与凭据——是否有硬编码 secret/API key/token/密码、连接字符串是否参数化、日志中是否有凭据；(6) 数据暴露——错误输出、日志或 API 响应是否泄露内部状态、堆栈跟踪、数据库 schema 或 PII；(7) 依赖风险——新引入依赖是否维护良好、版本正确、无已知漏洞；(8) 竞态与状态——并发代码共享资源是否正确同步、是否有 TOCTOU 漏洞。
12. Harden 动作分类：补丁（加校验、转义输出、移除硬编码密钥）在预算内自动应用；安全重构（重构认证流、替换脆弱模式、改变数据处理架构）始终需要人工批准，使用与 Simplify 相同的重构停止钩子，并额外提供严重程度与攻击向量上下文；无法安全修补的发现标记为 flagged_critical，非活跃漏洞的加固机会标记为 flagged_advisory；预算紧张时安全补丁优先于简化改动。
13. Pass 3 Document 微文档：刻意轻量，只做决策捕获——对任何需要超过 5 秒思考“为什么存在”的逻辑加一行注释说明决策；对任何 workaround/hack 加注释说明上下文并尽量附 TODO 及移除条件；对性能敏感选择注明为何选当前方案而非明显替代方案；每任务最多加 5 条注释。
14. 输出结构化 YAML 摘要，包含 simplify_and_harden 版本、task_id、execution（mode、mode_source、human_present）、scope（files_reviewed、original_diff_lines、additional_changes_lines、budget_exceeded）、simplify（applied、flagged、cosmetic_applied）、harden（applied、flagged_critical、flagged_advisory）、document（comments_added、locations）、learning_loop（target_skill、log_file、candidates、recurrence_window_days、promotion_threshold）、summary（各项计数、budget_utilization、human_prompts_*、learning_candidates、learning_promotions_recommended、review_followup_required）。
15. 当存在任何未解决发现（critical/advisory 标记、被跳过或超时的重构提议）或 budget_exceeded 为 true 时，将 review_followup_required 设为 true；仅当无需跟进时设为 false。
16. 学习循环集成：每次运行后将每个发现归一化为 pattern_key（如 simplify.dead_code、simplify.naming、simplify.control_flow、harden.input_validation、harden.authorization、harden.error_handling），在 learning_loop.candidates 中输出候选，交给 self-improvement 技能记录或更新 .learnings/LEARNINGS.md；当 30 天窗口内出现 >= 3 次且跨 >= 2 个不同任务时标记为可提升，并提升到 agent 上下文/系统提示文件（AGENTS.md、.github/copilot-instructions.md 或等价文件）以减少重复问题。
17. 执行模型：适用于人类可在线批准重构的通用编码代理会话——重构提议逐条展示并附清晰理由，代理暂停等待 [approve]/[reject]/[show diff]/[skip all refactors]；表面修复和直接安全补丁自动应用；CI 流水线与无头自动化改用 simplify-and-harden-ci。
18. 代理集成方式：程序化集成通过任务完成生命周期钩子（如 agent.on('task:complete')）在 diff 非平凡且未带 no-review 标志时运行技能，传入 diff、修改文件、预算（maxLines = 改动行数 * 0.2，maxTime = 60000），并把结果摘要追加到输出；提示式集成则在任务完成后注入后置提示，要求只审查修改过的文件、按 simplify→harden→document 顺序执行、输出变更/标记/未动内容的摘要。
19. 配置项：enabled、budget.max_diff_ratio（0.2）、budget.max_time_seconds（60）、simplify.enabled、simplify.auto_apply_cosmetic（true）、simplify.refactor_requires_approval（始终 true，不可禁用）、harden.enabled、harden.auto_apply_patches（true）、harden.refactor_requires_approval（始终 true，不可禁用）、document.enabled、document.max_comments（5）、stop_hook.mode（interactive）、stop_hook.show_diff_preview（true）、stop_hook.allow_skip_all（true）、stop_hook.timeout_seconds（300）、stop_hook.timeout_action（flag）、skip_patterns（如 **/*.test.*、**/*.spec.*、**/migrations/**）。
20. 核心不变量：范围锁定（只改本任务修改的文件）、预算上限（额外 diff 最多 20%）、简化优先姿态（清理是默认、重构是例外）、重构停止钩子（结构性改动始终需人工批准）、三遍顺序（simplify、harden、document）、结构化输出（已应用/已批准/已拒绝/已标记项的摘要）。
21. 推荐流程：先实现任务，再运行 Simplify & Harden 清理、加固并记录非显然决策，然后运行独立审查获取按严重程度排序的发现，两者都处理完后再合并；若两者冲突，以独立审查发现作为外部闸门，修复或明确豁免。
22. 注意事项：某些代理在高自主模式下可能无法可靠地暂停等待批准，生产使用前需验证该行为。
23. 不适用情形：代理失败或被中断；仅文档改动；仅测试改动；仅生成文件（lockfile、构建产物）；用户通过 --no-review 或等价标志显式跳过。

适用边界 · 注意事项

• 代理失败或被中断时不要运行。
• 改动仅为文档、测试、配置、注释、格式化或生成产物时不要运行。
• 用户通过 --no-review 或等价标志显式跳过时不要运行。