agent-teams-simplify-and-harden

Agent Teams 简化与加固

安装

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

使用 Agent Skills CLI 作为备用方案：

npx skills add pskoett/pskoett-skills/skills/agent-teams-simplify-and-harden

一个两阶段团队循环，用于产出可投入生产的代码：实现，然后使用简化和加固流程进行审计，接着修复审计发现的问题，然后重新审计，如此循环，直到代码库足够稳固或达到循环上限。

适用场景

• 根据规范或计划实现多项功能
• 对一批改动后的代码库进行加固
• 修复审查中发现的问题或缺漏列表
• 任何涉及 5 个以上文件且质量关卡很重要的任务

环境要求

以下流程使用多 Agent 团队工具（TeamCreate、TaskCreate、TaskUpdate、SendMessage、TeamDelete），以及子 Agent 创建工具（general-purpose 和 Explore Agent 类型）。这些工具适用于启用了 Agent 团队功能的 Claude Code 类环境。如果你的环境没有团队工具，但可以创建子 Agent，请跳过团队/任务工具，直接协调相同的阶段：创建实现子 Agent，然后创建审计子 Agent，并在 Markdown 检查清单中跟踪任务。如果你的环境完全无法创建子 Agent（例如 GitHub Copilot 聊天），请勿使用此技能——改用顺序执行的 simplify-and-harden 技能，并在聊天中逐阶段询问发现的问题。

流程集成

此技能以基于团队的循环替代标准流程第 2 至第 4 阶段（执行、审查、学习）。它可以接在 plan-interview 之后，也可以独立运行——所有上游产物均为可选项。

[plan-interview] → [agent-teams-simplify-and-harden] → [self-improvement]
                    ├─ intent frame (team lead)
                    ├─ implement (parallel agents)
                    ├─ audit (parallel agents)
                    ├─ drift check (team lead, between rounds)
                    └─ learning loop output → self-improvement

如果存在来自 plan-interview 的计划文件，此技能会从中提取任务。如果没有计划，团队负责人会进行简短的内联规划。上下文巡检会在循环轮次之间作为轻量级偏移检查，由团队负责人执行——子 Agent 生命周期较短，无需进行此检查。

模式

┌──────────────────────────────────────────────────────────┐
│                  TEAM LEAD (you)                          │
│                                                           │
│  Phase 1: IMPLEMENT (+ document pass on fix rounds)       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                 │
│  │ impl-1   │ │ impl-2   │ │ impl-3   │  ...            │
│  │ (general │ │ (general │ │ (general │                 │
│  │ purpose) │ │ purpose) │ │ purpose) │                 │
│  └──────────┘ └──────────┘ └──────────┘                 │
│       │             │            │                        │
│       ▼             ▼            ▼                        │
│  ┌─────────────────────────────────────┐                 │
│  │  Verify: compile + tests            │                 │
│  └─────────────────────────────────────┘                 │
│       │                                                   │
│  Phase 2: SIMPLIFY & HARDEN AUDIT                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                 │
│  │ simplify │ │ harden   │ │ spec     │  ...            │
│  │ auditor  │ │ auditor  │ │ auditor  │                 │
│  │ (Explore)│ │ (Explore)│ │ (Explore)│                 │
│  └──────────┘ └──────────┘ └──────────┘                 │
│       │             │            │                        │
│       ▼             ▼            ▼                        │
│  Exit conditions met?                                     │
│    YES → Produce summary. Ship it.                        │
│    NO  → back to Phase 1 with findings as tasks           │
│          (max 3 audit rounds)                             │
└──────────────────────────────────────────────────────────┘

循环上限与退出条件

符合以下任一条件时，循环退出：

1. 审计无问题：所有审计员均报告没有发现问题
2. 仅低严重性问题的轮次：某一轮发现的所有问题严重性均为 low——直接修复（由团队负责人或单个实现 Agent 处理），无需重新审计即可退出
3. 达到循环上限：已完成 3 轮审计。第三轮后，直接修复剩余的严重/高严重性问题，然后退出。在最终摘要中记录任何未解决的中/低严重性问题。

预算建议： 跟踪各轮累计差异的增长。如果修复轮次新增的改动超过原始实现差异的 30%，则缩小范围：跳过中/低严重性的简化问题，仅处理加固补丁和规范缺口。

分步流程

0. 规划并明确目标

如果计划文件存在（来自 plan-interview，路径为 docs/plans/plan-NNN-<slug>.md，或由用户提供）：读取文件，提取实现检查清单，并将其作为第 2 步的任务列表。

如果没有计划，进行简短的内联规划访谈：

1. 需要构建、修复或加固什么？（功能、缺陷、目标）
2. 规范或事实依据是什么？（文档、问题、PR 或口头描述）
3. 验收标准是什么？

将答案整理成具体的任务列表。这不是完整的 plan-interview，只需将工作拆分为可并行处理的单元即可。

目标框定： 创建团队之前，团队负责人先输出：

## Intent Frame #1

**Outcome:** [What the team session will deliver]
**Approach:** [Team structure, number of agents, audit dimensions]
**Constraints:** [Scope boundaries, loop cap, budget limits]
**Success criteria:** [Clean audit or loop cap with all critical/high resolved]
**Estimated complexity:** [Small / Medium / Large — based on task count and file count]

继续前请向用户确认。这将为后续所有偏移检查确立基准。

1. 创建团队

TeamCreate:
  team_name: "<project>-harden"
  description: "Implement and harden <description>"

2. 创建任务

将工作拆分为明确、可并行处理的任务。每项任务都应足够独立，使单个 Agent 无需等待其他 Agent 即可完成。

TaskCreate for each unit of work:
  subject: "Implement <specific thing>"
  description: "Detailed requirements, file paths, acceptance criteria"
  activeForm: "Implementing <thing>"

如有需要，设置依赖关系：

TaskUpdate: { taskId: "2", addBlockedBy: ["1"] }

3. 创建实现 Agent

创建 general-purpose Agent（可读取、写入和编辑文件）。每项任务创建一个，或按逻辑分组创建。并行运行。

Task tool (spawn teammate):
  subagent_type: general-purpose
  team_name: "<project>-harden"
  name: "impl-<area>"
  mode: bypassPermissions
  prompt: |
    You are an implementation agent on the <project>-harden team.
    Your name is impl-<area>.

    Check TaskList for your assigned tasks and complete them.
    After completing each task, mark it completed and check for more.

    Quality gates:
    - Code must compile cleanly (substitute your project's compile
      command, e.g. bunx tsc --noEmit, cargo build, go build ./...)
    - Tests must pass (substitute your project's test command,
      e.g. bun test, pytest, go test ./...)
    - Follow existing code patterns and conventions

    When all your tasks are done, notify the team lead.

4. 等待实现完成

监控 Agent 消息。所有实现 Agent 报告完成后：

1. 运行编译／类型检查，确认构建干净
2. 运行测试，确认全部通过
3. 如果其中任何一项失败，在继续之前修复问题或分配修复任务

可选：将此编译／测试步骤委托给 verify-gate 技能，而不是临时运行命令，以便与内循环流水线保持一致。verify-gate 会运行项目的编译／测试／lint，并返回包含诊断信息的通过／失败信号。

启动审计 Agent 之前，收集本次会话中修改过的文件列表：

git diff --name-only <base-branch>  # or: git diff --name-only HEAD~N

你会将此文件列表传给每位审计员。

5. 启动审计 Agent

启动 Explore Agent（只读——它们不能编辑文件，从而避免它们悄悄“修复”问题）。每位审计员负责一个不同的关注领域，并采用简化与加固方法。

建议的审计维度：

审计员	关注点	思考方式
simplify-auditor	代码清晰度和不必要的复杂性	“有没有更简单的表达方式？”
harden-auditor	安全性和弹性方面的缺口	“如果有人恶意查看这段代码，会尝试做什么？”
spec-auditor	实现与规范／计划的完整性对照	“代码是否符合要求？”

每位审计员的完整提示词模板位于 references/auditor-prompts.md。每个提示词都要求：只读范围、以全新视角开始、采用结构化问题报告格式，并明确报告零问题的情况。

简化审计员

以 Explore Agent 的身份启动。检查：死代码、命名、控制流、API 表面、过度抽象、整合。将问题归类为外观问题或重构（重构门槛：“显然有误，而非仅仅不够完美”）。报告文件、行号、类别、修复方式和严重程度。

加固审计员

以 Explore Agent 的身份启动。检查：输入验证、错误处理、注入向量、认证／授权、机密、数据暴露、依赖风险、竞态条件。将问题归类为补丁或安全重构。报告文件、行号、类别、严重程度、攻击向量和修复方式。

规范审计员

以 Explore Agent 的身份启动。检查：缺失功能、行为错误、实现不完整、契约违规、测试覆盖率、验收标准缺口。将问题归类为缺失、错误、不完整或未测试。报告文件、行号、类别、规范引用和严重程度。

6. 处理审计结果

收集所有审计员发现的问题。对于每个问题：

• 严重／高：创建任务并分配给实现 Agent
• 中：创建任务，纳入下一轮实现
• 低／外观问题：仅在修复轻而易举时纳入下一轮；否则记入最终摘要并跳过

重构门槛： 对于归类为重构或安全重构的问题，在创建任务前评估该重构是否确有必要。判断标准：“资深工程师会认为当前状态显然有误，而非仅仅不够完美吗？”拒绝仅仅出于风格偏好或边际改进而提出的重构建议。

退出检查： 如果本轮所有问题的严重程度均为 low，则直接修复，并跳过重新审计（参见循环限制）。

创建修复任务时，将一项文档补充工作一并加入每位实现 Agent 的任务：

修复分配给你的问题后，在你修改过的文件中最多添加 5 条单行注释，说明不明显的决策：

• 需要花超过 5 秒思考“为什么会有这段代码？”的逻辑
• 变通方案或临时处理，并说明背景以及移除条件的 TODO
• 性能方面的选择，以及为何采用当前方案

不要注释审计修复本身——只注释原始实现中缺少说明的决策。

这样可以让文档补充保持轻量且范围明确。后续轮次的审计员不应将这些注释列为问题。

7. 循环

如果有需要修复的问题：

1. 根据问题创建任务（包含文档审查说明）
2. 启动实现 Agent（或通过 SendMessage 重用空闲 Agent）
3. 等待修复完成
4. 运行编译和测试验证
5. 漂移检查（团队负责人）： 在下一轮审计前，重新阅读意图框架和计划／任务拆分。将当前工作状态与原始范围进行对比。如果审计发现将团队引向无关领域，或范围已超出既定框架，则重新界定范围或提前退出循环并生成摘要。
6. 检查循环限制（参见“循环限制和退出条件”）
7. 如果不退出：再次启动审计 Agent（使用新的 Agent，而非重用旧 Agent——保持上下文干净）
8. 重复

8. 最终验证和摘要

满足退出条件后：

1. 编译／类型检查——必须无错误
2. 测试——必须全部通过
3. 不得引入没有对应任务的 // TODO 或 // FIXME 注释

为本次会话生成最终摘要：

## Hardening Summary

**Audit rounds completed:** 2 of 3 max
**Exit reason:** Clean audit (all auditors reported zero findings)

### Findings by round

Round 1:
- simplify-auditor: 4 cosmetic, 1 refactor (rejected -- style preference)
- harden-auditor: 2 patches, 1 security refactor (approved)
- spec-auditor: 1 missing feature

Round 2:
- simplify-auditor: 0 findings
- harden-auditor: 0 findings
- spec-auditor: 0 findings

### Actions taken
- Fixed: 6 findings (4 cosmetic, 2 patches, 1 security refactor, 1 missing feature -- rejected refactor excluded)
- Skipped: 1 refactor proposal (reason: style preference, not a defect)
- Document pass: 3 comments added across 2 files

### Unresolved
- None

### Out-of-scope observations
- <any out-of-scope items auditors flagged, for future reference>

### Learning loop
learning_loop:
  target_skill: "self-improvement"
  candidates:
    - pattern_key: "harden.input_validation"
      auditor: "harden-auditor"
      rounds_to_resolve: 1
      severity: "high"
      suggested_rule: "Validate and bound-check external inputs before use."
    - pattern_key: "simplify.dead_code"
      auditor: "simplify-auditor"
      rounds_to_resolve: 1
      severity: "low"
      suggested_rule: "Remove dead code and unused imports before finalizing."

将各轮中反复出现的审计发现规范化为 pattern_key 条目，格式与 simplify-and-harden 相同。这些条目会提供给 self-improvement，用于跨任务跟踪和提升模式。

根据你的情境调整格式。目标是清晰记录发现了什么、修复了什么、跳过了什么及原因，以及还有哪些事项未解决。

9. 清理

向所有 Agent 发送关闭请求，然后删除团队：

SendMessage type: shutdown_request to each agent
TeamDelete

Agent 数量指南

代码库／任务规模	实现 Agent	审计 Agent
小（< 10 个文件）	1-2	2（简化 + 加固）
中（10-30 个文件）	2-3	2-3
大（30+ 个文件）	3-5	3（简化 + 加固 + 规范）

Agent 越多，并行度越高，但协调开销也越大。对于大多数任务，2-3 个实现 Agent 和 2-3 个审计 Agent 是最佳组合。

提示

• 实现 Agent 应使用 general-purpose——它们需要写入权限
• 审计 Agent 应使用 Explore——只读权限可防止它们暗中“修复”问题，否则审计就失去了意义
• 每轮都使用新的审计 Agent——不要重用上一轮的审计 Agent；它们会保留上下文，从而倾向于认为“已经检查过”某些区域
• 任务描述必须具体——包含文件路径、函数名称和预期的确切行为。模糊的任务会导致模糊的实现。
• 阶段之间运行编译和测试——不要在代码有问题时启动审计 Agent；先修复编译／测试错误
• 保持循环紧凑——如果审计人员只发现 1-2 个低严重性外观问题，就自行修复，不必启动完整的实现轮次
• 启动 Agent 前先分配任务——通过 TaskUpdate 设置任务的 owner，让 Agent 立即知道要处理什么
• 优先简化——处理审计发现时，优先清理外观问题以减少干扰，再处理重构。默认进行清理，只有特殊情况才重构
• 安全优先于风格——预算或时间有限时，优先处理加固类发现，而非简化类发现
• 提供文件列表——始终向审计人员提供明确的已修改文件列表。不要指望他们自行确定范围。

示例：实现规范功能

0.  Plan: Read spec (or run inline interview), break into 8 tasks
0b. Emit Intent Frame #1, confirm with user
1.  TeamCreate: "feature-harden"
2.  TaskCreate x8 (one per feature)
3.  Spawn 3 impl agents, assign ~3 tasks each
4.  Wait → all done → compile clean → tests pass
5.  Collect modified file list (git diff --name-only)
6.  Spawn 3 auditors: simplify-auditor, harden-auditor, spec-auditor
7.  Simplify-auditor finds 4 cosmetic + 1 refactor proposal
8.  Harden-auditor finds 2 patches + 1 security refactor
9.  Spec-auditor finds 1 missing feature
10. Team lead evaluates refactors (approve security refactor,
    reject simplify refactor), creates fix + document tasks
11. Spawn 2 impl agents for fixes
12. Wait → compile clean → tests pass
13. Drift check: re-read intent frame, scope looks good
14. Round 2: Spawn 3 fresh auditors
15. Auditors find 0 issues → exit condition met
16. Produce hardening summary + learning loop output
17. Shutdown agents, TeamDelete

质量门禁（不可妥协）

循环退出前，必须满足以下条件：

1. 编译／类型检查干净——零错误
2. 测试——零失败
3. 满足退出条件（审计干净、仅低严重性问题的一轮，或达到循环上限且关键／高严重性问题已解决）
4. 不得引入没有对应任务的 // TODO 或 // FIXME 注释

与其他技能的互操作性

此技能的输入

• 来自 plan-interview（可选）： 计划文件（docs/plans/plan-NNN-<slug>.md）。如果有该文件，则从实现检查清单中提取任务；如果没有，团队负责人会执行内联规划阶段。
• 来自用户（始终可用）： 任务描述、规格说明或功能列表。如果不存在计划文件，则以此作为事实依据。

此技能的产出

• 用于自我改进： 从反复出现的审计发现中提取学习循环候选项，采用与 simplify-and-harden 相同的 pattern_key 格式。
• 面向用户： 包含所有轮次完整审计记录的加固摘要。

流程中的位置

此技能通过团队协作循环替代标准流程的第 2–4 阶段：

1. plan-interview（可选，或在阶段 0 中进行内联规划）
2. agent-teams-simplify-and-harden（团队负责人 + 意图框定 + 实现 + 审计 + 偏差检查 + 学习循环）
3. self-improvement（使用学习循环的输出进行跨任务模式跟踪）

团队负责人会自行进行意图框定（不使用 intent-framed-agent 的产出），并在轮次之间进行轻量级上下文浏览偏差检查（而非完整的退出／交接流程）。子 Agent 生命周期较短，不会运行流程技能。