simplify-and-harden

Agent 技能：简化与加固

安装

gh skill install pskoett/pskoett-skills simplify-and-harden

如需仅在 CI 中运行，请使用：

gh skill install pskoett/pskoett-skills simplify-and-harden-ci

通过 Agent Skills CLI 进行回退：

npx skills add pskoett/pskoett-skills/skills/simplify-and-harden
npx skills add pskoett/pskoett-skills/skills/simplify-and-harden-ci

元数据

字段	值
技能 ID	simplify-and-harden
版本	0.1.0
触发条件	完成后钩子
作者	Peter Skøtt Pedersen
类别	代码质量 / 安全
优先级	推荐

理由与理念

编码 Agent 完成任务时，对问题、解决方案以及过程中做出的权衡有着最充分的上下文理解。这些上下文会立即衰减——下一个任务就会将其清空。「简化与加固」利用这段上下文最充足的窗口，在 Agent 继续处理下一个任务之前，进行两轮有针对性的审查。

大多数 Agent 解决工单后就停下了。这个技能让「完成」变成「高质量地完成」。

其运作理念是在继续下一步之前，刻意以「全新视角」进行自我审查：仔细重读所有新编写的代码和本次任务中修改的现有代码，认真查找明显的 bug、错误、令人困惑的逻辑、脆弱的假设、命名问题，以及遗漏的加固机会。目标不是扩大范围或重写解决方案，而是趁 Agent 仍记得每项改动背后的意图，利用最充分的上下文进行一次有纪律的初步审查。

与独立审查配合使用效果最佳

此技能用于完成后的自我审查，不能替代独立审查。

建议流程：

1. 实现任务。
2. 运行「简化与加固」，以清理、加固并记录不显而易见的决策。
3. 运行独立审查，按严重程度排序报告发现。
4. 只有处理完两轮审查的发现后才合并。

如果两者意见不一致，应将独立审查的发现视为外部关卡，并修复或明确豁免这些发现。

按需进行独立审查

对于较大或风险较高的改动，可使用拥有全新上下文的通用子 Agent。 无需指定预设 Agent。向其提供已修改文件列表、差异、已批准的 计划或验收标准，以及相关的验证证据。要求其直接阅读 限定范围内的代码并报告发现，不要编辑文件。如果宿主支持，请将 工具限制为只读；否则，应在说明中明确这一限制。在 Copilot 中，可在聊天中 请求进行相同范围的独立审查。

使用下方「简化与加固」检查清单审查复杂度和安全性。同时， 将每项提供的要求与实现逐一对照：缺失的功能、 错误行为、不完整的边界情况或错误处理路径、API 和响应契约、 测试覆盖率，以及未经验证的验收标准。将规格差异归类为缺失、 错误、不完整或未经测试。

要求按严重程度排序报告发现，并包含文件和行号（或「尚未实现」）、 类别、具体证据、相关规格引用或攻击向量，以及明确的修复方法。将范围外的 观察结果单独列出，并明确说明范围内是否没有发现问题。审查者负责报告； 实现 Agent 根据现有的审批和重新验证规则处理修复。

一位审查者即可覆盖所有相关方面。只有在范围或风险确有必要时才拆分审查， 不要自动分配给三个 Agent。如果无法进行独立审查，应报告这一限制； 自我审查不能替代独立的合并关卡。

触发条件

仅当以下所有条件都满足时，此技能才会自动触发：

• Agent 已完成主要编码任务
• Agent 表示任务已完成（退出代码为 0、PR 已准备就绪或其他等效情况）
• 差异中包含实质性的代码变更（定义见下文）
• 此技能尚未在此任务中运行（不会重复触发）

实质性代码变更的定义

满足以下任一条件时，将差异视为实质性变更：

1. 至少涉及一个可执行源文件（例如：*.ts、 *.tsx、*.js、*.jsx、*.py、*.go、*.rs、*.java、*.cs、 *.rb、*.php、*.swift、*.kt、*.scala、*.sh），并且包含 以下任一情况：
   • 可执行源文件中至少有 10 行发生变更，且不包括注释和空白行；或
   • 至少有一项高影响逻辑变更（身份验证／授权检查、输入验证、数据访问／查询逻辑、外部命令执行、文件路径处理、网络请求处理或并发控制）。
2. 对配置、工作流、权限、部署或安全策略的修改可能改变哪些人可以执行操作、执行哪些内容、部署哪些内容或适用哪些保护措施。

若差异仅涉及文档、低影响配置、注释、格式、生成文件或测试，则将其视为非实质性变更。

以下情况不会触发此技能：

• Agent 失败或被中断
• 变更仅涉及文档
• 变更仅涉及测试
• 变更涉及生成文件（锁文件、构建产物）
• 用户通过 --no-review 或等效标志明确跳过

范围限制

硬性规则：只能修改本任务中已修改的文件。

Agent 不得：

• 重构未修改的相邻代码
• 进行差异范围之外的“顺手”改进
• 引入新依赖或进行架构变更
• 根据在其他位置发现的模式推测并修复问题

对于超出范围的问题，Agent 应在摘要输出中指出，而不是采取行动。

预算限制：

• 额外变更最多为原始差异大小的 20%（按变更行数计算）
• 最长执行时间为 60 秒（可配置）
• 达到任一限制时，Agent 停止执行，并使用 budget_exceeded 标志输出已有结果

第 1 轮：简化

目标： 减少实现中引入的不必要复杂性。

默认做法：简化，不重构。 本轮的主要目标是进行轻量清理，且能证明不会改变行为。重构是例外，而非惯例。

从全新视角开始（强制要求）： 在本轮进行任何编辑之前，以“全新视角”重新阅读本任务中新增或修改的所有代码，并主动查找明显的错误、易混淆的逻辑、脆弱的假设、命名问题以及遗漏的加固机会。

Agent 应审查自己的工作并思考：

“现在我已了解完整方案，是否有更简单的表达方式？”

审查清单

1. 死代码和脚手架代码 —— 我是否遗留了调试日志、注释掉的尝试、未使用的导入，或迭代过程中产生的临时变量？将它们删除。

2. 命名清晰度 —— 函数名、变量名和参数名在初次阅读时是否容易理解？实现过程中看似合理的名称，事后读起来往往不够清晰。将它们重命名。

3. 控制流 —— 能否简化嵌套条件？能否用提前返回替代深层嵌套？是否有可以简化的布尔表达式？让代码更精炼。

4. API 表面 —— 我是否暴露了不必要的内容？能否将某些公共方法或函数设为私有？减少可见性。

5. 过度抽象 —— 我是否创建了超出当前范围所需的类、接口或包装函数？Agent 往往会过度设计。标记出来，但除非收益显著，否则不要重构。

6. 整合机会 —— 我是否将逻辑分散在多个函数或文件中，而它们本可以放在同一处？标记出来，但只有在重复十分严重且整合方式清晰时才建议重构。

简化操作

对于每项发现，Agent 会将其归类为：

• 保持行为不变的修复（例如，删除可确认为未使用的导入 或任务创建的死代码）——在预算范围内自动应用。
• 可观察到的变化或不确定的变化（包括命名、控制流、 可见性、API、策略、权限、部署或安全行为）——需提交人工审批，即使改动很小。
• 重构（整合、结构调整、抽象变更）——仅当 Agent 判断确实有必要或收益显著时才提出。重构不是默认操作。判断标准是：“资深工程师会认为当前状态明显有问题，而不只是存在瑕疵吗？”

重构停止钩子（强制）：

Agent 将任何变更归类为重构时，都会触发交互式提示。Agent 必须：

1. 说明计划进行的变更及其原因
2. 展示变更前后的内容（或清晰描述结构上的变化）
3. 等待人工明确批准后再应用

Agent 不会批量提出重构建议。每项重构都会单独提出，以便人工逐项批准、拒绝或修改。

[simplify-and-harden] Refactor proposal (1 of 2):

  I want to merge duplicated validation logic from handleCreate() and 
  handleUpdate() into a shared validatePayload() function.

  Why: Both functions validate the same fields with identical rules.
  The duplication was introduced because I built handleUpdate as a 
  copy of handleCreate during implementation.

  Files affected: src/api/handler.ts (lines 34-67)
  Estimated diff: -22 lines, +14 lines

  [approve] [reject] [show diff] [skip all refactors]

如果人工选择 skip all refactors，Agent 会跳过剩余的重构建议，并进入 Harden 阶段。跳过的重构仍会在输出摘要中以 flagged 状态列出，状态为 skipped_by_user。

只有经证实能够保持行为不变的变更才不会触发停止钩子。类别标签不能凌驾于可观察到的行为之上：重命名、分支重写或降低可见性可能会对外部产生重大影响；如果其效果不确定，就必须获得批准。

阶段 2：加固

目标： 在 Agent 仍然理解代码意图时，弥补安全性和韧性方面的缺口。

Agent 会审查自己的工作，并自问：

“如果有人恶意查看这段代码，他们会试图做什么？”

审查清单

1. 输入验证 —— 所有外部输入（用户输入、API 参数、文件路径、环境变量）是否都在使用前经过验证？检查是否存在类型强制转换问题、缺少边界检查，以及字符串长度不受限制的情况。

2. 错误处理 —— catch 块是否足够具体？记录错误时是否包含上下文，但不会泄露敏感数据？是否存在被吞掉的异常？

3. 注入攻击面 —— 检查任何根据外部输入构建字符串的代码中是否存在 SQL 注入、XSS、命令注入、路径遍历和模板注入。

4. 身份验证与授权 —— 新增的端点或函数是否强制执行身份验证？权限检查是否存在且正确？是否存在权限提升风险？

5. 机密信息与凭据 —— 是否存在硬编码的机密信息、API 密钥、令牌或密码？连接字符串是否使用参数化方式？检查日志输出中是否包含凭据。

6. 数据泄露 —— 错误输出、日志或 API 响应是否泄露内部状态、堆栈跟踪、数据库架构或个人身份信息（PII）？

7. 依赖项风险 —— Agent 是否引入了新的依赖项？如果有，这些依赖项是否维护良好、版本设置是否正确，以及是否不存在已知漏洞？

8. 竞态条件与状态 —— 对于并发代码，共享资源是否经过适当同步？是否存在 TOCTOU（检查时与使用时之间）漏洞？

强化操作

对于每项发现，Agent 会将其归类为：

• 修补（添加验证检查、转义输出、移除硬编码机密信息）——仅当已批准的验收约定已要求修补，且针对性验证能够证明结果时才自动应用；否则请求人工批准
• 安全重构（重组身份验证流程、用新方案替换易受攻击的模式、更改数据处理架构）——继续操作前始终需要人工批准

此处同样适用 Simplify 阶段中的 重构停止钩子。安全重构会逐项呈现，并附上严重性和攻击向量的相关背景：

[simplify-and-harden] Security refactor proposal:

  The new /admin/export endpoint inherits base authentication but has 
  no role-based access check. Any authenticated user can trigger a 
  full data export.

  Severity: HIGH
  Vector: Privilege escalation
  
  Proposed fix: Add role guard requiring 'admin' role before the 
  handler executes. This changes the middleware chain for this route.

  Files affected: src/api/routes/admin.ts (line 12)
  Estimated diff: +8 lines

  [approve] [reject] [show diff] [skip all security refactors]

• 标记为严重 —— Agent 无法在没有人工输入的情况下安全修补的问题（无论是否获批，都会在输出中注明）
• 标记为建议 —— 尚未构成实际漏洞的强化机会

预算受限时，安全修补（非重构）优先于简化更改。

阶段 3：记录文档（微型阶段）

目标： 在 Agent 还记得做出决策的原因时，记录不明显的决策。

此阶段刻意保持轻量——这不是文档编写阶段，只记录决策。

规则

• 对于任何需要花费超过 5 秒思考“为什么要这样做？”的逻辑：添加一条单行注释，解释该决策
• 对于任何变通方案或临时处理：添加一条注释说明背景，最好再附上注明移除条件的 TODO
• 对于任何对性能敏感的选择：说明为何选择当前方案，而不是显而易见的替代方案
• 最多：每项任务添加 5 条注释。这不是一次文档冲刺。

阶段 4：重新验证

发出完成信号前，必须重新验证。

1. 如果 Simplify & Harden 更改了任何文件，请重新运行覆盖这些修改的最小现有测试、检查、代码检查工具或行为验收。
2. 如果没有进行任何修改，只要紧接在前的 verify-gate 证据仍覆盖已审查的差异，就可以复用该证据。
3. 如果验证失败，请根据诊断结果返回实现阶段；不要宣称任务已成功完成。
4. 如果没有适用的验证方式，请记录 not-run，设置 review_followup_required: true，且不得声称任务已完全验证。

输出架构

此技能会生成一份结构化摘要，并追加到任务输出中：

simplify_and_harden:
  version: "0.1.0"
  task_id: "<original task ID>"
  execution:
    mode: "interactive"
    mode_source: "auto_detected"  # "auto_detected", "config", "env_override"
    human_present: true
  scope:
    files_reviewed: ["src/api/handler.ts", "src/utils/validate.ts"]
    original_diff_lines: 142
    additional_changes_lines: 18
    budget_exceeded: false

  simplify:
    applied:
      - file: "src/api/handler.ts"
        line: 45
        type: "consolidation"
        category: "refactor"
        approval: "approved_by_user"
        description: "Merged duplicated validation logic from handleCreate and handleUpdate into shared validatePayload function"
    flagged:
      - file: "src/utils/validate.ts"
        type: "over-abstraction"
        category: "refactor"
        approval: "skipped_by_user"
        description: "ValidationStrategy interface may be unnecessary -- only one implementation exists. Consider inlining if no additional strategies are planned."
        confidence: "medium"
    cosmetic_applied:
      - file: "src/api/handler.ts"
        line: 12
        type: "dead_code"
        description: "Removed unused import of deprecated AuthHelper"

  harden:
    applied:
      - file: "src/api/handler.ts"
        line: 62
        type: "input_validation"
        severity: "high"
        description: "Added bounds check on pageSize parameter -- previously accepted arbitrary integers"
    flagged_critical:
      - file: "src/api/handler.ts"
        type: "authorization"
        description: "New /admin/export endpoint inherits base auth but no role check -- any authenticated user can access it. Requires human decision on role policy."
    flagged_advisory:
      - file: "src/utils/validate.ts"
        type: "error_handling"
        description: "Catch block on L31 logs full request body which may contain PII in production"

  document:
    comments_added: 2
    locations:
      - file: "src/api/handler.ts"
        line: 78
        comment: "// Pagination uses cursor-based approach instead of offset -- offset breaks when items are deleted between pages"
      - file: "src/api/handler.ts" 
        line: 93
        comment: "// WORKAROUND: Legacy API returns dates as strings without timezone. Assuming UTC until migration completes (see TICKET-1234)"

  verification:
    command: "npm test -- src/api/handler.test.ts"
    result: "pass" # pass | fail | not-run
    evidence: "Targeted handler tests passed after review edits"

  learning_loop:
    target_skill: "self-improvement"
    log_file: ".learnings/LEARNINGS.md"
    candidates:
      - pattern_key: "simplify.dead_code"
        pass: "simplify"
        finding_type: "dead_code"
        severity: "low"
        source_file: "src/api/handler.ts"
        source_line: 12
        suggested_rule: "Remove dead code and unused imports before finalizing a task."
      - pattern_key: "harden.input_validation"
        pass: "harden"
        finding_type: "input_validation"
        severity: "high"
        source_file: "src/api/handler.ts"
        source_line: 62
        suggested_rule: "Validate and bound-check external inputs before use."
    recurrence_window_days: 30
    promotion_threshold:
      min_occurrences: 3
      min_distinct_tasks: 2

  summary:
    simplify_applied: 1
    simplify_cosmetic_applied: 1
    simplify_flagged: 1
    simplify_rejected_by_user: 0
    simplify_skipped_by_user: 1
    harden_applied: 1
    harden_flagged_critical: 1
    harden_flagged_advisory: 1
    harden_rejected_by_user: 0
    comments_added: 2
    total_additional_lines: 18
    budget_utilization: "12.7%"
    human_prompts_shown: 3
    human_prompts_approved: 1
    human_prompts_rejected: 0
    human_prompts_skipped: 1
    human_prompts_timed_out: 1
    learning_candidates: 2
    learning_promotions_recommended: 1
    verification_result: "pass"
    review_followup_required: true

只要仍有未解决的问题（严重/建议标记、跳过或超时的重构提案）、budget_exceeded 为 true，或验证结果不是 pass，就将 review_followup_required 设为 true。只有无需后续跟进时，才将其设为 false。

自我改进集成（学习循环）

Simplify & Harden 会将反复出现的质量/安全问题反馈给 self-improvement 技能，让重复问题逐渐成为持久的提示词规则。

每次运行后：

1. 将每个问题规范化为一个 pattern_key：
   • Simplify 示例：simplify.dead_code、simplify.naming、simplify.control_flow
   • Harden 示例：harden.input_validation、harden.authorization、harden.error_handling
2. 在 simplify_and_harden.learning_loop.candidates 中输出这些候选模式。
3. 将候选模式交给 self-improvement，由其在 .learnings/LEARNINGS.md 中记录或更新条目（而不是创建重复的一次性记录）。
4. 候选模式达到重复出现阈值时，将其标记为可晋升：在 30 天内，跨越至少 2 个不同任务出现 >= 3 次。
5. 将可晋升的模式写入 Agent 上下文/系统提示词文件（CLAUDE.md、AGENTS.md、.github/copilot-instructions.md 或等效文件），以减少重复问题。

这样，Simplify & Harden 就能专注于单个任务的清理和加固，而由 self-improvement 负责跨任务记忆与晋升。

执行模式

此技能适用于有人可以即时批准重构的一般编码 Agent 会话。

行为：

• 一次显示一个重构提案，并清楚说明理由
• Agent 暂停并等待 [approve]、[reject]、[show diff] 或 [skip all refactors]
• 只有能够证明不改变行为的修复，以及有验收依据的安全补丁，才会自动应用

对于 CI 流水线和无头自动化，请使用 simplify-and-harden-ci。

Agent 上下文文件引用

要启用此技能，请在 Agent 上下文文件中引用它。

针对特定 Agent 的复制粘贴片段位于 references/agent-context-snippets.md。 只加载当前使用的 Agent 对应的片段，以保持上下文精简。

所有 Agent 集成都必须遵守的核心不变量：

1. 范围锁定——仅处理当前任务中修改的文件
2. 预算上限——额外差异最多为 20%
3. 简化优先——默认进行清理，重构是例外
4. 重构停止钩子——结构性更改始终需要人工批准
5. 四个阶段——简化、加固、记录、重新验证（按此顺序）
6. 编辑后验证——任何审查编辑后都要重新运行适用的检查
7. 结构化输出——总结已应用、已批准、已拒绝、已标记和已验证的项目

注意：部分 Agent 在高自主模式下可能无法可靠地暂停以等待批准。在生产环境中使用前，请先验证此行为。

Agent 兼容性

此技能旨在适用于任何遵循基于任务工作流的编码 Agent，不依赖任何特定的 Agent 框架或产品。

编程式集成（具有技能/钩子 API 的 Agent）：

• Claude Code、GitHub Copilot Workspace、Codex、Opencode、OpenClaw、Cursor Agent、Windsurf、Aider、SWE-Agent、OpenHands、Devin，以及任何暴露任务完成生命周期事件的 Agent

基于提示词的集成（没有正式技能 API 的聊天式 Agent）：

• 任何接受任务后指令的大模型编码助手——在 Agent 表示任务完成后，可将此技能的逻辑作为后续提示词注入

输出架构采用与 Agent 无关的 YAML。使用工具只需解析结构化摘要即可。

集成说明

此技能与 Agent 无关。它可接入任何暴露任务完成生命周期事件的编码 Agent。以下示例均为通用示例——请根据 Agent 的具体 API 进行调整。

Agent 集成

此技能会接入 Agent 的任务完成生命周期。建议采用以下集成模式：

agent.on('task:complete', async (context) => {
  if (context.diff.isNonTrivial() && !context.flags.includes('no-review')) {
    const result = await skills.run('simplify-and-harden', {
      diff: context.diff,
      files: context.modifiedFiles,
      budget: { maxLines: context.diff.linesChanged * 0.2, maxTime: 60000 }
    });
    context.appendOutput(result.summary);
  }
});

支持此技能的 Agent 应实现以下接口：

• 访问已完成任务生成的 diff
• 获取包含完整内容的已修改文件列表
• 能够展示交互式提示（用于交互模式）
• 提供结构化摘要的输出渠道（stdout、PR 评论或等效渠道）

基于提示词的集成

对于不支持以编程方式接入技能钩子的 Agent（例如 Claude Code、Cursor、Copilot Chat 等基于聊天的编码 Agent），可以通过任务完成后的提示词注入来实现此技能：

After completing the task, run the Simplify & Harden review:
1. Review only the files you modified
2. Simplify: Your default action is cleanup. Apply only changes proven
   behavior-preserving, such as removing a task-created unused import.
   Naming, control-flow, visibility, API, policy, permission, deployment, and
   security changes require approval when their effect is observable or
   uncertain. Refactoring is NOT the default.
3. Harden: Check for input validation gaps, injection vectors, auth issues, 
   exposed secrets, and error handling problems. Apply a patch directly only
   when the approved acceptance contract requires it and a targeted check can
   verify it. Otherwise describe the issue with severity and ask for approval.
4. Document: Add up to 5 comments on non-obvious decisions.
5. Re-verify: Run the smallest existing checks that cover all review edits.
6. Output a summary of what you changed, what you flagged, what you left
   alone, and the verification evidence.

CI 流水线变体

对于 GitHub Actions 或其他 CI／无头模式用法，请运行 simplify-and-harden-ci。

配置

# Example configuration (adapt path to your agent's config format)
# e.g., .agent/skills.yaml, .claude/skills.yaml, .cursor/skills.yaml
simplify-and-harden:
  enabled: true
  budget:
    max_diff_ratio: 0.2        # Max additional changes as ratio of original diff
    max_time_seconds: 60       # Hard time limit
  simplify:
    enabled: true
    auto_apply_behavior_preserving: true
    refactor_requires_approval: true  # ALWAYS true -- cannot be disabled
  harden:
    enabled: true
    auto_apply_acceptance_backed_patches: true
    refactor_requires_approval: true  # ALWAYS true -- cannot be disabled
  document:
    enabled: true
    max_comments: 5
  stop_hook:
    mode: "interactive"
    show_diff_preview: true
    allow_skip_all: true
    timeout_seconds: 300       # 5 min -- human is at the keyboard
    timeout_action: "flag"     # Assume they stepped away, don't discard
  skip_patterns:               # Glob patterns to exclude from review
    - "**/*.test.*"
    - "**/*.spec.*"
    - "**/migrations/**"

设计决策

为什么在任务完成后执行，而不是持续执行？ 在实现过程中持续审查会形成反馈循环，拖慢 Agent 的速度，还可能导致反复震荡（简化，然后重新复杂化，再次简化）。任务完成后再审查，Agent 就能基于稳定的代码库进行检查。

为什么先简化，而不是先重构？ Agent 很喜欢重构。只要允许它们“改进”代码，它们就会重新组织代码。但大多数任务后的改进都只是表面调整：无用的导入、不恰当的命名、无谓的深层条件判断。这些改进以近乎零风险带来了 80% 以上的价值。重构则存在真实风险——可能引入 bug、破坏测试，还会让 diff 臃肿。默认简化、例外重构，能让此技能持续带来价值，而不会突然改写代码。重构的标准应是“这里确实有问题”，而不是“这里还能稍微改好一点”。

为什么要设定预算？ 没有限制时，Agent 会把审查当作无止境重构的许可。20% 规则能让此技能保持专注：改进你构建的内容，而不是重新构建它。

为什么要将简化与加固分开？ 两者需要不同的思维方式。简化关注“这是否是表达我意图最清晰的方式？”，而加固关注“这可能会如何被利用？”。把两者混为一谈，会导致两方面都做得不够好。按顺序运行也能让我们在预算紧张时优先处理安全修复。

为什么要进行文档微调？ 如果没有明确提示，Agent 很不擅长记录自己的推理。审查 Agent 生成代码的人类审查者普遍认为，最大的阻碍是难以理解做出某项选择的原因。加上五条注释成本微不足道，却能大幅节省审查时间。

未来考虑

• 团队校准：允许团队调整审查清单中各项的权重（例如：“相比命名，我们更关注注入攻击向量”）
• 理解 diff 的上下文加载：对于大型代码库，智能加载与 diff 相关的文件和符号，而不是加载整个项目
• 跨技能组合：Simplify & Harden 可以为“PR 描述”技能提供输入，利用其摘要自动生成有意义的 PR 描述