将 Claude Code 协作机制抽成 Skills：记忆、上下文压缩、验证与多 Agent 编排

AI（人工智能）编程 Agent（智能体）做复杂任务时，真正麻烦的地方往往不是“会不会写代码”，而是能不能稳定协作：对话越来越长以后如何压缩上下文，用户偏好如何沉淀，任务完成后如何验证，大任务如何拆给多个角色处理，后台巡检任务如何被规范地描述。

cc-harness-skills 的思路，是把 Claude Code（CC）这类编程 Agent 中比较通用的协作机制抽出来，做成一组不强依赖具体运行环境的 Skills。它面向的不是单一工具，而是 Claude Code、Codex App、OpenClaw、OpenCode 这类支持 Skill 或可插入工作流的 Agent 宿主。

仓库地址：

https://github.com/LearnPrompt/cc-harness-skills

cc-harness-skills 解决什么问题

编程 Agent 的能力通常由两部分组成：

1. 模型本身的推理、代码生成和理解能力；
2. 外围工作流，也就是如何组织上下文、记忆、权限、验证和多角色协作。

第二部分可以理解为一套 harness：它不是模型本身，而是把模型“套”进一个更可控的协作框架里。一个实用的 harness 至少要处理这些问题：

整体结构可以抽象成这样：

flowchart LR
    A[用户任务] --> B[Agent 宿主<br/>Claude Code / Codex App / OpenClaw / OpenCode]

    B --> C{任务状态}

    C -->|协作结束| D[CC Memory Extractor<br/>提取偏好与约束]
    C -->|记忆堆积| E[CC Dream Memory<br/>合并长期记忆]
    C -->|上下文过长| F[CC Context Compressor<br/>九段式压缩]
    C -->|声称完成| G[CC Verification Gate<br/>只读验证]
    C -->|任务庞大| H[CC Swarm Coordinator<br/>多阶段分工]
    C -->|需要定时跟进| I[CC Kairos Lite<br/>轻量主动任务]

    D --> J[(长期记忆)]
    E --> J
    F --> K[交接摘要]
    G --> L[验证报告]
    H --> M[分工计划与执行结果]
    I --> N[周期任务定义]

这套设计的重点不是把某个工具的完整代码搬到另一个工具里，而是把可复用的协作模式沉淀成 Skills。只要宿主 Agent 支持加载类似 Skill 的指令单元，就可以迁移这些工作流。

六个 Skills 的职责

当前包含六个核心 Skills，每个 Skill 都对应一种常见协作场景。

这六个 Skill 可以单独用，也可以组合用。例如，一个复杂功能可以先用 Swarm Coordinator 拆分，执行过程中用 Context Compressor 做阶段交接，结束后用 Verification Gate 检查，再用 Memory Extractor 沉淀用户偏好和项目约束。

CC Memory Extractor：从协作中提取可复用记忆

长期协作中，Agent 最容易丢掉的不是代码细节，而是“人和项目的偏好”。

比如：

• 用户希望回答直接给结论，少写铺垫；
• 项目禁止引入新依赖；
• 单元测试必须用某个命令跑；
• API（应用程序编程接口）返回格式已经被前端依赖，不能随便改；
• 某个目录是生成物，不能手动编辑。

这些信息如果只停留在对话里，下次协作又要重新解释。CC Memory Extractor 的作用，就是在一轮协作结束后，把最近对话里真正值得保留的信息抽出来。

一个比较适合保存的记忆格式可以写成这样：

user_preferences:
  communication:
    - 回答时优先给可执行步骤，少写泛泛解释。
    - 修改代码前先说明会影响哪些文件。
  review_style:
    - 对风险点要明确标注，不要只说“已完成”。

project_constraints:
  dependencies:
    - 未经确认不要新增运行时依赖。
  testing:
    - 代码变更后优先运行项目已有测试命令。
  compatibility:
    - 对外 API 返回字段需要保持兼容。

references:
  - docs/api-contract.md
  - README.md

Memory Extractor 需要控制粒度。不是所有信息都应该进入长期记忆，临时想法、一次性的调试路径、已经废弃的方案都不适合保存。长期记忆要满足三个条件：

CC Dream Memory：把混乱记忆压成稳定长期记忆

Memory Extractor 解决的是“提取新记忆”，Dream Memory 解决的是“整理旧记忆”。

当对话、日志和记忆文件越堆越多时，会出现几个问题：

• 同一个偏好被重复记录；
• 旧约束和新约束互相冲突；
• 记忆里混入了临时任务；
• 信息太长，反而增加上下文负担。

Dream Memory 的工作方式更像一次记忆清理：读取最近会话、日志和旧记忆，去重、合并、删除过期内容，最后产出一份短小稳定的长期记忆。

flowchart TD
    A[最近会话] --> D[Dream Memory]
    B[运行日志] --> D
    C[旧长期记忆] --> D

    D --> E[去重]
    E --> F[合并同类项]
    F --> G[标记冲突]
    G --> H[删除临时信息]
    H --> I[(稳定长期记忆)]

处理记忆时要避免一个常见错误：把“发生过的事”都当成“以后要遵守的规则”。例如“这次为了修 bug 临时跳过测试”不能保存成长期偏好，否则之后 Agent 可能错误地认为测试不重要。

更合理的长期记忆应该像这样：

stable_memory:
  project_rules:
    - 修改数据库 schema 前，需要同步更新迁移脚本和接口文档。
    - 生成文件不要手动编辑，应修改生成源文件。
  user_preferences:
    - 输出验证结果时要写明实际运行过的命令。
  unresolved_conflicts:
    - 是否允许新增依赖尚未确认，遇到相关需求需要先询问。

CC Context Compressor：九段式上下文压缩

长上下文是编程 Agent 的高频问题。对话越长，模型越容易忘记早期约束，也越容易把已经废弃的方案混进当前计划里。

Context Compressor 的目标不是简单“总结一下”，而是生成可交接、可继续执行的结构化摘要。它尤其适合三种场景：

• 当前会话太长，需要开启新会话；
• 任务要交给另一个 Agent；
• 多阶段任务完成了一个阶段，需要固定当前状态。

一个实用的九段式压缩模板可以这样组织：

# 1. 任务目标
用一两段说明当前任务要解决什么问题，完成标准是什么。

# 2. 用户原话与硬约束
保留用户明确说过的要求，尤其是不能改、必须做、输出格式等约束。

# 3. 当前进展
列出已经完成的动作，不混入未验证的猜测。

# 4. 关键决策
记录为什么选择当前方案，以及放弃了哪些方案。

# 5. 涉及文件与接口
列出关键文件、函数、配置项、接口路径。

# 6. 命令、日志与错误
保留运行过的命令、重要报错、失败原因。

# 7. 已完成事项
用清单列出确定完成的部分。

# 8. 风险与未知项
列出尚未验证、可能有问题、需要用户确认的内容。

# 9. 下一步动作
给出可直接执行的后续步骤。

这个结构里最重要的是第 2、5、6、8、9 段。它们决定了新 Agent 接手时会不会踩坑：

压缩上下文时要尽量保留用户的关键原话。改写可以让摘要更短，但硬约束最好不要过度转述。比如用户说“不要新增依赖”，摘要里就应该保留这句话，而不是写成“倾向于少改动”。

CC Verification Gate：用只读视角检查是否真的完成

编程 Agent 容易出现一种典型问题：任务看起来完成了，但并没有真实验证。

常见表现包括：

• 代码改了，但测试没跑；
• 测试命令失败，却被描述成通过；
• 只验证了正常路径，漏掉边界条件；
• 文档、类型、配置没有同步更新；
• 任务目标的一部分被遗漏。

Verification Gate 的设计，是在 Agent 声称完成时切换到只读验证视角。它不再继续实现功能，而是检查“完成声明是否成立”。

sequenceDiagram
    participant U as 用户
    participant A as 实现 Agent
    participant V as Verification Gate
    participant C as 代码/测试/日志

    U->>A: 提出开发任务
    A->>C: 修改代码
    A-->>U: 声称已完成
    U->>V: 触发只读验证
    V->>C: 检查变更、测试、边界条件
    V-->>U: 返回验证结论与风险

Verification Gate 的输出不应该只写“通过”或“不通过”，而应该把证据列出来：

## 验证结论
部分通过。

## 已确认
- 已修改 src/api/user.ts 中的返回字段。
- 已更新对应类型定义。
- 已运行 npm test，测试通过。

## 未确认
- 没有看到端到端测试。
- 没有验证旧客户端是否兼容新增字段。

## 风险
- 如果前端依赖字段顺序或空值行为，仍可能出现兼容问题。

## 建议动作
- 补充一个旧响应格式兼容测试。
- 使用已有 mock 数据跑一次前端调用链路。

只读验证的关键是边界清晰：Verification Gate 可以读取文件、分析 diff、检查日志、建议命令，但不应该顺手继续改代码。否则验证阶段又会变成实现阶段，任务状态会变得更混乱。

CC Swarm Coordinator：把大任务拆成多角色协作

复杂任务通常不适合让一个 Agent 从头做到尾。研究、方案整理、代码实现、验证检查是不同类型的工作，混在一个上下文里会增加错误概率。

Swarm Coordinator 使用四段式分工：

对应流程如下：

flowchart TD
    A[用户提出复杂任务] --> B[Swarm Coordinator]

    B --> C[Research<br/>查代码与约束]
    C --> D[Synthesis<br/>整理方案]
    D --> E[Implementation<br/>执行修改]
    E --> F[Verification<br/>只读检查]

    F --> G{是否通过}
    G -->|通过| H[交付结果]
    G -->|不通过| I[返回问题清单]
    I --> D

这种拆分方式适合跨很多文件、影响多个模块、需要谨慎验证的任务。例如：

• 重构鉴权流程；
• 改造缓存策略；
• 迁移配置系统；
• 修复一个涉及前后端协议的缺陷；
• 给已有项目补齐测试体系。

小任务不一定适合使用 Swarm Coordinator。比如只改一个文案、补一个类型错误、解释一个函数，强行拆成四个阶段会增加沟通成本。

CC Kairos Lite：定义轻量主动任务

有些任务不是一次性完成的，而是需要慢节奏跟进：

• 每隔一段时间检查构建状态；
• 后台观察某个问题是否复现；
• 长任务完成后生成简报；
• 定期整理某个目录的变化；
• 监控某个实验的输出结果。

Kairos Lite 用来描述这类轻量主动任务。它的重点不是让 Agent 无限自主运行，而是把任务范围、频率和停止条件写清楚。

一个任务定义可以写成这样：

task_name: check-build-status
scope:
  - 检查 CI 构建结果
  - 只读取构建日志，不修改代码
schedule:
  interval: 30m
  max_runs: 6
stop_conditions:
  - 构建成功
  - 连续 3 次失败且错误相同
  - 用户手动停止
report:
  format: brief
  include:
    - 当前状态
    - 失败原因
    - 建议动作
permissions:
  mode: read_only

Kairos Lite 最适合“小范围、低频率、可停止”的任务。它不适合开放式目标，例如“持续优化整个项目”或“自动把所有问题修好”。这类目标太大，权限和验收标准都不清晰，容易产生不可控行为。

权限边界：让 Agent 知道自己能做什么

cc-harness 里的一个重要思想，是不要让所有 Skill 都拥有同样的权限。不同阶段应该有不同边界。

可以把权限粗略拆成四层：

权限边界的价值在于减少误操作。比如 Verification Gate 如果拥有实现权限，就可能在验证时继续改代码；Kairos Lite 如果没有停止条件，就可能把一个轻量巡检变成长期后台任务。

怎么上手

可以先克隆仓库：

git clone https://github.com/LearnPrompt/cc-harness-skills.git

不同 Agent 宿主的 Skill 加载方式不完全一样，处理方式通常是：

1. 选择一个目标宿主，例如 Claude Code、Codex App、OpenClaw 或 OpenCode；
2. 按宿主的 Skill 目录或配置规范导入需要的 Skill；
3. 不要一次性启用所有 Skill，优先从一个高频痛点开始；
4. 为每个 Skill 写清触发条件，避免 Agent 在不合适的时候误用。

推荐的启用顺序：

触发 Skill 时，可以直接把任务意图写清楚：

请使用 CC Context Compressor 压缩当前上下文。
要求保留用户硬约束、关键文件、运行过的命令、报错信息、未完成事项和下一步动作。

或者：

请使用 CC Verification Gate 进行只读验证。
不要修改代码，只检查任务是否真的完成，并列出已验证、未验证、风险和建议动作。

适合和不适合的场景

使用时容易踩的坑

1. 记忆不是越多越好

长期记忆应该只保存稳定偏好、项目约束和可复用事实。不要把所有对话都塞进记忆文件，否则模型每次都要处理大量噪声。

2. 压缩摘要不能只保留结论

Context Compressor 要保留关键证据，尤其是命令、日志、错误和用户硬约束。只有结论没有证据，新 Agent 接手后很难判断哪些内容已经验证过。

3. 验证阶段要保持只读

Verification Gate 的职责是检查，不是继续实现。发现问题后应该输出问题清单和建议动作，再由实现阶段处理。

4. 多 Agent 协作有成本

Swarm Coordinator 适合复杂任务，不适合小任务。任务越简单，越应该减少角色和阶段。

5. 主动任务必须有停止条件

Kairos Lite 需要明确最大运行次数、停止条件和报告格式。没有停止条件的后台任务不可控，也很难验证是否完成。

一个组合使用示例

假设要改造一个项目的登录鉴权逻辑，可以这样组织工作流：

flowchart TD
    A[用户提出鉴权改造需求] --> B[Swarm Coordinator 拆分任务]
    B --> C[Research 查找鉴权入口、配置、测试]
    C --> D[Synthesis 生成改造方案]
    D --> E[Implementation 修改代码]
    E --> F[Verification Gate 只读验证]
    F --> G{验证是否通过}

    G -->|不通过| H[返回问题清单]
    H --> D

    G -->|通过| I[Context Compressor 生成交接摘要]
    I --> J[Memory Extractor 提取长期偏好与项目约束]

这个流程把“做事”和“检查”拆开，把“当前上下文”和“长期记忆”拆开。Agent 不需要在一个混乱对话里同时承担所有职责，任务状态也更容易被追踪。

cc-harness-skills 的价值在于把这些协作习惯做成可复用组件。模型能力会变化，Agent 宿主也会变化，但记忆整理、上下文压缩、完成验证、多阶段协作和轻量主动任务这些机制，会长期存在于复杂 AI 编程工作流里。