claude长且复杂的编程任务独立性培养

培养 AI Agent 处理长任务的独立性：从"保姆式"到"自主作战"

新手刚接触 AI Agent 工具，一上来就让它做长且复杂的任务（以下简称"长任务"），不得者十之有九。本文系统整理一套"培养方案"，让 Agent 有机会独当一面。

一、为什么 AI Agent 一上来做不了长任务

很多人对 Agent 有不切实际的幻想：丢一个"帮我做个完整项目"的需求，期望它一路跑到底。现实是——能跑完的不到一成。原因集中在三点：

• 1. 上下文窗口有限**：非付费重度用户、中小 R 玩家的上下文配额吃紧，长任务还没跑一半，前面的需求已经被挤出窗口。
• 2. 聪明的模型也会犯错**：再强的模型在长链条推理中都会累积误差，方向一旦偏了，后面所有努力都在错误地基上盖楼。
• 3. 各个厂商的token用量硬控。
• 3. 多agent并发，触发资源竞争，导致文件写坏。
• 5. 服务器问题导致的阻塞性终止**：429、超时、并发限制随时可能让任务中断在半路。

● API Error: Request rejected (429) · Concurrency limit exceeded for account, please retry later

AI Agent 工具更像是一个待培养的新兵蛋子，需要你细心、耐心培养，精心挑选合适的装备，才能有机会独当一面。培养手段可以归纳为四条主线：硬性流程、防打断、流水线骨干、后处理兜底。

---

二、硬性流程：为 Agent 搭建"作战大纲"

2.1 预设知识库：让 Agent 一开始就有"地图"

Agent 最怕的不是没能力，而是没上下文。在它开跑之前，必须先把项目背景知识落地成 markdown 文档，分成三层：

• memory：Claude 的记忆系统，由 memory.md 文件索引，是给 agent 看的。
• knowledge / docs：skill 或 rules 辅助落地的文档，给用户看的，agent 也可能索引到。为避免漏检索，需要强制定义这些目录为知识库目录。

  • Claude 下：通过 CLAUDE.md 或 rule 文档指定。
    

  • Trae 下：通过 rule 文档指定，或添加到文档集里。

配置优先级必须先理清，否则三层配置互相覆盖会让你排查到怀疑人生：

层级	位置	作用范围	适合放
全局配置	~/.claude/settings.json	本机本账户所有项目	个人长期偏好：默认模型、全局权限白名单
项目级配置	<项目>/.claude/settings.json	该项目所有人（进 Git）	项目专属配置：MCP 工具、lint 钩子
个人本地覆盖	<项目>/.claude/settings.local.json	该项目×本机×本人（不进 Git）	私人 token、个人偏好、本机绝对路径

⚠️ 重要：项目级配置会进 Git，绝对不要在这里写密码、API Key。优先级：本地覆盖 > 项目级 > 全局。

额外建议——让 AI 自行完成几件落地工作：

1. 让 AI 自行整理项目目录结构，落地成 markdown 文档；
2. 让 AI 自行整理项目用到的工具（尤其是编译工具）和所在目录，落地成 markdown 文档。
3. 定下子agent单独负责指定目录或者worktree的规则，否则并发大概率容易把文件写坏。

这样能避免它发起多 agent 时，每个 agent 都重新找一遍，浪费 token 又容易找错。

2.2 架构师智能体多轮对抗性审查：扶正方向

AI 做事最怕方向错。大量事实证明，AI 相互纠察可以让方向错误率大幅度降低。每个阶段完成都让架构师智能体审查一遍，比让一个 agent 一条路走到黑要稳得多。

实操要点：

• 每个阶段必审查：不要等全部做完再审查，那时候返工成本指数级上升。
• 多轮而非一轮：单轮审查容易漏判，至少两轮，第二轮针对第一轮的修改再验。
• 审查角色与执行角色分离：执行 agent 不能自己审自己，必须独立角色。

2.3 审查后自动归档、纠正知识/PRD 文档：防止"文档过期"

随着审查反馈累积，总计划和阶段计划 PRD 文档会出现"自然过期"的内容——某项需求被调整了、某个目录改了、某个工具换版本了，但文档没同步。需要在多轮审查后自动归档、纠正相关的知识文档和 PRD 文档，让下一阶段的 agent 拿到的始终是最新地图。

💡 高价值技巧：

• 给审查 agent 单独一个"文档同步"子任务，让它把审查中产生的修正项 diff 出来，再回写到知识库。比让执行 agent 自己回头改文档要可靠得多。
• 强烈推荐按照superpowers或者autonomous-agent技能，提示词要求它每个阶段总结一下进度、经验、遇到的问题。

---

三、防打断：让 Agent 不停顿地跑下去

长任务最大的敌人是"中途询问"。Agent 跑了 30 分钟突然问你"是否执行此命令？"，你不在电脑前，任务就卡死了。

3.1 根因诊断：模型为什么会思考、记忆出错

在讲优化手段之前，先搞清楚模型为什么会出错。不对症下药，优化就是撒胡椒面。

底层原理：注意力与记忆是怎么工作的

要看懂后面的根因，先花两分钟理解两个底层机制。这两个机制是所有思考/记忆问题的物理基础。

① 注意力机制（Self-Attention）

当前主流大模型都基于 Transformer 架构，核心是"自注意力"：生成每一个 token 时，模型都会对上下文里所有 token 算一遍"注意力分数"，决定该"看哪里"。

可以把它想象成一场会议：当前发言者（正在生成的 token）扫视全场所有参会者（上下文里的 token），给每个人打一个"关注度"分数，分数越高就越倾向于参考那个人的信息。这个分数的计算方式是：

• 每个 token 同时扮演三个角色：Q（Query，"我想找什么"）、K（Key，"我能提供什么"）、V（Value，"我的实际内容"）。
• 当前 token 用自己的 Q 去和所有 token 的 K 做点积，得到"相关性分数"。
• 分数经 softmax 归一化后作为权重，对所有人的 V 加权求和——这就是当前 token 最终"看到"的信息。

关键在于 softmax 归一化：所有人的注意力分数加起来等于 1。这意味着注意力是"零和博弈"——关注 A 多了，关注 B 就必然少了。上下文越长，分数被分摊得越稀，中间位置的 token 就越容易被"稀释"掉。这就是"Lost in the Middle"的数学根因。

多头注意力（Multi-Head Attention）：模型同时跑多组注意力（如 32 个头），每个头关注不同维度——有的看语法、有的看语义、有的看位置，最后合并。但这不改变"零和博弈"的本质，只是从多个维度分别做了一遍零和分配。

影响注意力的 6 大因素：

因素	影响	实操启示
上下文长度	越长，中间 token 注意力越低	长上下文要把关键信息放首尾
信息位置	首尾注意力高，中间低（U 型分布）	核心约束放开头或结尾
信息格式	结构化标记（###、```、表格）吸引更多注意力	关键指令用标题/代码块包裹
指令强度	"必须""禁止"等强约束词注意力高	硬性约束用强语气词
干扰噪声	无关内容越多，关键信息被淹没越深	及时清理无关上下文
信息重复	重复出现的信息累积更高注意力	关键约束可在首尾各放一次

② 记忆机制：Transformer 本身没有"记忆"

这是最容易被误解的一点。Transformer 是无状态的——每次推理都从头计算，模型权重不会因为之前的对话而改变。所谓"记住之前的对话"，完全靠把之前的对话内容塞进上下文窗口。上下文窗口一旦装满，最早的内容就被挤出去，模型就"忘了"——它不是"想不起来"，而是物理上已经看不到了。

Agent 的"记忆"实际分三层，各层容量和特性完全不同：

记忆层	实现方式	容量	特点
上下文记忆（短期）	当前上下文窗口里的所有 token	= 窗口大小（如 200K）	精确，但容量有限，溢出即遗忘
KV Cache（推理缓存）	推理时缓存已算的 K/V 矩阵，避免重复计算	受显存限制	工程加速手段，不是真正的"记忆"
外置记忆（长期）	文件系统/数据库（如 MEMORY.md）	理论无限	需主动召回，召回质量取决于检索机制

KV Cache 补充：它是推理引擎的工程优化——把前面 token 已算好的 K/V 矩阵缓存起来，生成新 token 时直接复用，不必重算。它让长上下文生成变得可行，但也吃显存——这就是为什么上下文越长、推理越慢、越容易 OOM。它不是"记忆"，但它的显存占用直接决定了你能用多大的上下文窗口。

③ Claude Memory 的检索原理

Claude 的 memory 不是向量数据库式的语义检索，而是 LLM 自身的"阅读理解"式检索，分三步：

1. 全量加载索引：每次会话启动，MEMORY.md 索引文件被全量加载到上下文。
2. 阅读判断相关性：模型"读"这个索引，靠自身的语言理解能力判断哪些记忆与当前任务相关。
3. 按需读取内容：读取相关记忆文件内容，注入上下文参与推理。

这个原理解释了几个反直觉的现象：

• 为什么 200 行会溢出：MEMORY.md 是全量加载的，超过 200 行占用过多上下文 token，且模型对长索引文件的注意力会衰减——中间的记忆条目被"Lost in the Middle"效应吃掉。
• 为什么 description 是召回关键：模型靠"读"索引来判断相关性，description 是它唯一能看到的"摘要"。description 写得模糊，模型判断不准；写得精准，模型一读就知道该不该召回。
• 为什么记忆会"幻觉"：模型在推理时，无法区分"从记忆文件读到的事实"和"自己生成的中间结论"——两者在上下文里都是 token，没有标记区分。它可能把后者当成前者，信誓旦旦"我记得"，但翻遍记忆文件根本没有。

影响记忆的 6 大因素：

因素	影响	实操启示
索引文件长度	超长会占用上下文 + 注意力衰减	MEMORY.md 只放指针，控制在 150 行内
description 质量	决定模型能否判断相关性	用"问题-答案"形式，带关键词
记忆文件结构	frontmatter 规范度影响加载与识别	必含 name / description / metadata.type
记忆关联密度	[[name]] 网络让召回能触类旁通	相关记忆交叉引用
记忆时效性	过期记忆会误导推理	审查后同步更新
检索时机	该召回没召回 = 遗忘；不该召回却召回 = 干扰	description 精准匹配当前任务上下文

💡 一句话总结：注意力是"零和博弈"，记忆是"阅读理解式检索"。理解了这两点，后面的所有根因和优化技巧都是它们的推论。

思考出错的 6 大根因

根因	表现	触发场景
注意力衰减（Lost in the Middle）	上下文中间的关键信息被忽略	长上下文（>50K token）
指令漂移	跑着跑着就忘了原始目标和约束	多阶段长任务
错误累积与上下文污染	前面的错误结论留在上下文，污染后续推理	链式推理
过早收敛	第一个看似可行的方案就停下	方案探索类任务
思维定式	形成路径后即使发现错了也跳不出来	调试、重构
幻觉与过度自信	对错误结论不自我怀疑，缺乏元认知	新工具/API、知识截止后

逐条拆解：

1. 注意力衰减：研究表明，模型对上下文首尾的注意力远高于中间。关键指令放在 50K token 的中间位置，召回率断崖式下降。这就是为什么长任务跑到中段，模型开始"忘记"你最初的要求。
2. 指令漂移：长任务多阶段，每阶段有子目标。模型会把注意力聚焦到当前子目标，原始总目标逐渐被淡忘。表现为：跑着跑着就开始做你没要求的事。
3. 错误累积与上下文污染：模型每步推理的输出都进入上下文。第 3 步推错了，第 4 步基于错误的第 3 步继续推，错误被放大。更糟的是，即使后面发现第 3 步错了，错误结论还留在上下文里，模型可能再次引用。
4. 过早收敛：模型找到第一个"看起来能用"的方案就停下，不会主动探索更优解。表现为：你让它优化代码，它改了一处就停了，明明还有 5 处可以优化。
5. 思维定式：模型一旦形成某种解题路径，即使后面遇到矛盾证据，也倾向于沿用原路径。这是长任务调试中最致命的问题——模型认定是 A 问题，你告诉它不是 A，它下一轮还是按 A 来。
6. 幻觉与过度自信：模型对训练数据截止日期之后的新工具、新 API 版本会"编造"用法，而且语气非常自信。更危险的是"幻觉记忆"——模型会"记起"从未写入的记忆内容。

记忆出错的 6 大根因

根因	表现	触发场景
记忆溢出	MEMORY.md 超 200 行，旧记忆被挤出	长期项目累积
召回相关性失真	该想起的没想起，不该想起的干扰	description 写得模糊
记忆冲突	同一事实多个版本，模型用错版本	手动重复写入
记忆过期	项目变化了但记忆没更新	重构、改版后
记忆孤立	记忆之间无关联，无法触类旁通	缺少 [[name]] 交叉引用
幻觉记忆	模型"记起"了从未写入的内容	模型混淆推理与记忆

逐条拆解：

1. 记忆溢出：MEMORY.md 是每会话自动加载的索引，默认只检索前 200 行。长期项目累积下来，早期写入的记忆被挤到 200 行之外，模型就"不记得"了。
2. 召回相关性失真：记忆召回靠 description 字段做相关性匹配。description 写得模糊（如"项目笔记"），召回时相关性分数低，该想起的想不起；写得过于宽泛，又会召回无关记忆干扰推理。
3. 记忆冲突：同一事实被写入多个文件（比如手动复制了一份），后来只更新了其中一个。模型召回时可能命中旧版本，得出错误结论。
4. 记忆过期：项目重构后，目录结构、工具版本、API 都变了，但记忆没同步更新。模型按过期记忆操作，到处碰壁。
5. 记忆孤立：每条记忆都是独立文件，没有用 [[name]] 交叉引用。模型召回一条记忆时，无法顺着网络找到相关的其他记忆，导致"知其然而不知其所以然"。
6. 幻觉记忆：这是最隐蔽的问题。模型在推理时混淆了"自己生成的中间结论"和"从记忆文件读取的事实"，把前者当成后者。表现为：模型信誓旦旦"我记得之前说过 X"，但翻遍记忆文件根本没这条。

根因 → 优化手段速查

根因	对应优化手段
注意力衰减	关键信息放上下文首尾；阶段性重述目标（见 3.4）
指令漂移	每阶段加载阶段 PRD 时附带总目标摘要（见 2.1）
错误累积与上下文污染	/compact 清理错误结论；子 agent 销毁带走错误（见 3.4、3.6）
过早收敛	架构师审查强制要求"至少 2 个方案"（见 2.2）
思维定式	rewind 回溯到错误发生前；换子 agent 重做（见五章）
幻觉与过度自信	让模型输出记忆来源；提供参考实现对照（见 3.3）
记忆溢出	MEMORY.md 只写指针；定期归档（见 3.3）
召回相关性失真	description 用"问题-答案"形式（见 3.3）
记忆冲突	写入前 grep 检查同主题；单一权威源（见 3.3）
记忆过期	审查后自动纠正知识文档（见 2.3）
记忆孤立	[[name]] 交叉引用构建记忆网络（见 3.3）
幻觉记忆	引用记忆时必须输出文件路径（见 3.3）

💡 用法：上面这张表是"症状→药方"索引。当你发现 agent 出现某种错误模式时，先查这张表定位根因，再跳到对应小节看具体技巧。比盲目套用所有优化手段高效得多。

3.2 禁止询问：硬性放权

Claude 下：预设全向权限，可选 auto mode 或更激进的 --dangerously-skip-permissions（dangerous mode）。

claude --dangerously-skip-permissions   # 临时模式，关掉终端后失效

永久生效需改配置文件 ~/.claude/settings.json 或 .claude/settings.local.json：

{
  "skipDangerousModePermissionPrompt": true,
  "permissions": { "defaultMode": "bypassPermissions" }
}

个人推荐做法：先预判任务的危险性——预判 agent 是否会做坏事，可能性低则用 --dangerously-skip-permissions，其次用 auto mode。同时通过项目预设的 hooks（硬约束）和 rules（软约束） 帮 agent 界定边界：

• hooks 是硬约束：在执行前拦截，违反就阻断，agent 绕不过去。
• rules 是软约束：写在规则文件里，agent 通常会遵守，但极端情况下可能忽略。

Trae work 下：开启"自动运行命令"和"自行调用 MCP"。可赞的是它的部分询问会设超时，超时后采用推荐项，这点比 Claude 友好。

3.3 优化记忆：让 Agent 记住该记的

Claude 的 memory 默认只检索前 200 行索引的记忆，超出就会"记忆溢出"——agent 假装不记得。优化记忆的核心规范：

1. Write 写事实文件 C:\Users\xxx\.claude\projects\<project>\memory\g1.4-brainstorming-notes.md
   含 frontmatter（name / description / metadata.type: project）+ 正文（范围、参考分析、待 explore、下一步）
2. Edit 在 MEMORY.md 索引追加一行 - [G1.4 brainstorming 笔记](g1.4-brainstorming-notes.md) — ...

记忆规范要点（来自内置 Memory 指引）：

• 一个文件一个事实：不要把多件事塞进同一文件，否则召回时相关性判断会失真。
• frontmatter 必含 name / description / metadata.type（user/feedback/project/reference）。
• description 是召回相关性的关键：写得越精准，agent 越能在对的时候想起来。
• MEMORY.md 只放一行指针，不存内容——它是每会话自动加载的索引，写满 200 行就溢出。
• 正文用 [[name]] 关联其他记忆，构建记忆网络而非孤岛。
• 写入前检查是否已有同主题文件：更新而非重复，避免一个事实散落多处。
• description 用"问题-答案"形式：不要写"项目笔记"，要写"如何配置 dangerously-skip-permissions？——改 settings.json 的 skipDangerousModePermissionPrompt"。问题-答案形式天然带关键词，召回相关性大幅提升，治"召回相关性失真"。
• 引用记忆时必须输出文件路径：给 agent 配规则"引用记忆事实时，必须附上记忆文件路径"。路径不存在的就是幻觉记忆，能当场识破，治"幻觉记忆"。
• 定期归档 MEMORY.md：超过 150 行时（留 50 行余量），把最早的、已完成的记忆归档到 memory/archive/ 子目录。归档不是删除，需要时 agent 仍可主动检索，治"记忆溢出"。
• 单一权威源：同一事实只允许一个权威文件，其他地方用 [[name]] 引用。更新时只改权威文件，所有引用自动生效，治"记忆冲突"和"记忆过期"。

3.4 优化上下文：减慢上下文溢出

3.4.1 适当时机做上下文压缩

Agent 跑久了上下文会爆，主动压缩可以延长寿命。压缩后用 ctrl+o 检查压缩后的上下文是否还保留了关键信息。

3.4.2 安装 cf（ContextFlow）技能

cf 能及时保存上下文到 .claude 同级的 .session-bridge 下，是长任务的"存档点"。

⚠️ 关键陷阱：如果先执行了 /clear 或 /compact，cf 只能抓到当前会话窗口的 2 条消息（/clear + /cf save）。原因是 cf-save 只能读取当前活跃会话存储，拿不到被压缩/清除前的完整会话。正确顺序：先 /cf save，再 /clear 或 /compact。

3.4.3 本地上下文层优化工具

程序员首推 graphify：基于代码图谱的上下文压缩工具。

# 仓库地址
https://github.com/safishamsi/graphify

默认安装到 Claude 平台。如果希望在 Trae IDE 中也能用 /graphify 命令：

[graphify安装目录]\graphify.exe install --platform trae-cn

headroom 也是一个知名的本地上下文层优化工具，安装好后用它包装平时 claude 命令来启动 claude cli：

headroom wrap claude

可参考：https://sjxi.cn/detil/ab0742a1f64a41a68843a06d5f308200

💡 高价值技巧：graphify 适合大型代码库的代码问答场景（它通过代码图谱压缩无关代码），headroom 适合长会话场景（它管理整个会话的上下文滚动）。两者可以叠加使用——graphify 负责代码层压缩，headroom 负责会话层压缩。

3.4.4 针对思考出错的优化技巧

上面讲的是"减慢上下文溢出"的通用工具。下面针对 3.1 节诊断的 6 大思考根因，给出对应的优化技巧——这些技巧不需要装工具，改提示词和流程即可生效：

• 关键信息放首尾，避开中间盲区：重要指令、约束、目标放在上下文的开头或结尾，绝不放在中间。长 PRD 的核心需求放第一节，附录放最后。治"注意力衰减"。
• 阶段性重述目标：每阶段开始时，让 agent 先输出"原始总目标 + 当前阶段目标 + 必须遵守的约束"三行摘要，再开始执行。强制把漂移的注意力拉回来。治"指令漂移"。
• 错误结论及时清理：发现错误结论后，立即 /compact 压缩掉错误上下文，或让子 agent 销毁带走错误。不要让错误结论留在上下文里继续污染——模型不会"假装没看见"，它会反复引用。治"错误累积与上下文污染"。
• 强制多方案探索：在架构师审查环节要求"至少给出 2 个可行方案并对比优劣"，堵死"第一个方案就停"的退路。治"过早收敛"。
• 思维定式时换 agent，不要继续纠正：调试中模型反复坚持同一个错误方向时，不要继续在同一会话里纠正它——直接换一个新子 agent 从头分析。新 agent 没有前一个 agent 的思维定式包袱，往往一眼就能看出问题。治"思维定式"。
• 提供参考实现对照，别让它猜：遇到新工具/API 时，先让 agent 读官方文档或参考项目实现，不要让它凭训练记忆猜。给"地图"比给"方向"更可靠。治"幻觉与过度自信"。

3.4.5 提示词的正确用法：用对关键词撬动模型能力

3.4.4 讲的是"改流程"层面的优化，这一节讲"改提示词"层面的优化。很多新手知道"第一性原理""对抗性审查""多轮审查"这些词，但用不对——要么用得太宽泛模型不知道做什么，要么用错场景反而帮倒忙。提示词是撬动模型能力的杠杆，杠杆放对位置能四两拨千斤，放错位置就是给上下文添噪。

💡 核心原则：关键词不是咒语，模型不会因为听到"第一性原理"就自动切换思维模式。关键词必须配套"具体维度/约束/产出格式"才有用。下面把高频关键词的正确用法和常见误用逐一拆解。

关键词正确用法速查表：

关键词	作用	正确用法	常见误用
第一性原理	从基本约束推导，不模仿现有方案	明确"列出不可妥协的约束→基于约束推导"两步	"用第一性原理思考一下"（太宽泛）
对抗性审查	站在对立面主动找漏洞	指定对抗者身份+攻击维度+最少反例数	"对抗性审查一下"（没给维度）
多轮审查	每轮聚焦不同维度，后轮验前轮	明确每轮焦点（架构/实现/边界）	"多轮审查一下"（没定义轮次焦点）
思维链（CoT）	显式输出推理过程	复杂推理/多步决策才用	简单任务也强制 CoT，浪费 token
自我反思	交付前回头自检	给出自检清单（正确性/边界/性能）	"反思一下"（没给清单）
角色扮演	指定具体角色与职责	角色名+职责边界+产出格式	"扮演一个专家"（太宽泛）
少样本（Few-shot）	提供具体输入输出示例	示例与真实任务同构	示例和任务不匹配
逐步推理	分解复杂任务	明确"先 X 再 Y 最后 Z"	对简单任务也分解

逐个关键词的正确用法：

① 第一性原理（First Principles）

让 agent 从最基本的事实和约束出发推导方案，而不是"看现有代码怎么写就照着改"。治"思维定式"和"过早收敛"——它强迫模型跳出现有实现的路径依赖。

• 错误用法："用第一性原理思考一下这个需求"——模型不知道你说的"原理"指什么，会泛泛而谈。
• 正确用法：把"原理"具象成"不可妥协的约束"，并强制分两步走。

请从第一性原理出发设计这个模块：
1. 先列出 3-5 条不可妥协的业务/物理约束（如：单服同时在线 1 万人、延迟 < 50ms、不能丢消息）
2. 再基于这些约束推导方案，禁止参考现有代码的写法
3. 如果推导出的方案与现有实现冲突，说明现有实现哪里妥协了

• 适用场景：架构设计、技术选型、解决"改了又改还是不对"的顽固问题。
• 不适用场景：bug 修复、格式调整——这些有现成模式可循，硬套第一性原理是杀鸡用牛刀。

② 对抗性审查（Adversarial Review）

让审查 agent 站在对立面，主动找漏洞、找反例，而不是"看看有没有问题"。治"幻觉与过度自信"和"过早收敛"——它强迫模型面对最坏的输入。

• 错误用法："对抗性审查一下这段代码"——模型会客客气气地挑几个无关痛痒的小毛病。
• 正确用法：指定对抗者身份、攻击维度、最少反例数，并要求"找不到 N 个反例不许交差"。

请以对抗者视角审查这个方案，假设你是想让它失败的攻击者：
- 身份：恶意用户/高并发流量/磁盘故障（选一个）
- 攻击维度：至少覆盖 3 个——输入边界、并发竞争、异常路径、资源耗尽、权限越界
- 产出：列出至少 3 个能让方案崩溃的具体输入或场景，并说明现有方案为什么挡不住
- 禁止：只说"建议加强校验"这种没营养的话，必须给出具体的崩溃输入

• 适用场景：安全审计、核心交易链路、并发模块、外部输入处理。
• 不适用场景：文档校对、UI 微调——这些没有"攻击者"概念。

③ 多轮审查（Multi-round Review）

2.2 节讲了"多轮而非一轮"，这里补充每轮的焦点设计。多轮审查不是"同样的事审好几遍"，而是每轮聚焦不同维度，后一轮基于前一轮的反馈再验。

• 错误用法："多轮审查一下"——模型会每轮重复同样的审查，浪费 token。
• 正确用法：预先定义每轮焦点，且后一轮要验前一轮的修改有没有引入新问题。

本轮审查为第 2 轮，焦点：实现正确性与边界条件
- 第 1 轮已审：架构合理性（已修复 3 处）
- 第 2 轮任务：
  1. 验证第 1 轮的 3 处修复是否引入新问题
  2. 重点检查：空值/越界/并发/超时 4 类边界
  3. 不要重复第 1 轮的架构审查
- 产出格式：沿用第 1 轮的 issue 列表格式，标注"复验通过"或"新发现"

• 适用场景：复杂方案、长任务阶段性验收、安全敏感模块。
• 不适用场景：一次性小改动——单轮审查足够，多轮反而拖慢。

④ 思维链（Chain of Thought, CoT）

让 agent 显式输出推理过程，而不是直接给答案。治"错误累积"——中间步骤可见，错在哪一步一目了然。

• 错误用法：简单任务也强制"请一步一步思考"，模型为了配合会把一句话拆成五句说，纯浪费 token。
• 正确用法：仅在复杂推理（数学计算、多步决策、依赖推理）时启用，并指定推理的"骨架"。

请按以下推理链分析这个性能问题：
1. 现象：【描述症状】
2. 假设：列出 3 个可能根因，按可能性排序
3. 验证：每个假设如何用最小成本验证
4. 排除：根据验证结果排除哪些假设
5. 结论：最终根因 + 修复方案
每一步都要输出，不要跳步。

• 适用场景：性能调优、根因分析、复杂业务逻辑推导。
• 不适用场景：CRUD 实现、格式转换——直接给答案更快。

⑤ 自我反思（Self-Reflection）

让 agent 在交付前回头审视自己的输出。治"幻觉完成"——agent 不能再凭"我改完了"就交差。

• 错误用法："做完后反思一下"——模型会写一段"总体还不错，可以优化"的空话。
• 正确用法：给出具体的自检清单，要求逐项打勾。

交付前请对照以下清单逐项自检，每项标注【通过/不通过/不适用】：
- [ ] 编译通过（附 uloop 日志）
- [ ] 单测全过（附测试结果）
- [ ] 边界条件：空值/越界/并发 已处理
- [ ] 没有引入新的 TODO/FIXME
- [ ] 改动范围与 PRD 一致，没有越界改其他模块
- [ ] 引用的记忆事实都附了文件路径
任何一项"不通过"禁止声称已完成。

• 适用场景：任何交付前的最后一道关。
• 与 5.3 自动化测试的关系：自检清单里的"编译通过/单测全过"应该用 uloop 这类工具跑出客观证据，而不是 agent 自己说"我跑了"。

⑥ 角色扮演（Role-Playing）

指定具体角色和职责边界，让 agent 进入对应视角。比泛泛的"专家"更聚焦。

• 错误用法："扮演一个资深架构师"——"资深"是模糊的，模型不知道该资深在哪。
• 正确用法：角色名 + 职责边界 + 关心的维度 + 产出格式。

角色：高并发游戏服务端架构师（10 年经验）
- 你只关心：吞吐、延迟、容灾、扩展性
- 你不关心：UI 美观、文案措辞
- 产出格式：先给架构图（mermaid），再列 3 个最关键的风险点
- 禁止：给"建议进一步评估"这种没结论的话

• 适用场景：多视角方案评审（架构师/DBA/安全/运维各审一遍）。
• 进阶：用 3.5 节的多 agent 协作，给每个角色派一个独立子 agent，避免单 agent 兼演多角色导致视角混淆。

⑦ 少样本（Few-shot）

提供具体的输入→输出示例，让 agent 模仿格式和风格。比纯描述更精确。

• 错误用法：给的示例和真实任务结构不一致，agent 照着示例的格式套，反而出错。
• 正确用法：示例与真实任务同构（同样的字段、同样的结构），给 2-3 个覆盖不同情况的示例。

请按以下示例格式输出错误分析：
示例1（空指针）：
输入：player:GetEquip(slot) 返回 nil
根因：slot 索引越界，equip 表无此 slot
修复：调用前校验 slot 范围

示例2（并发竞争）：
输入：两个协程同时写 backpack[itemId]
根因：无锁，后写覆盖前写
修复：加 sync.Mutex 或串行化到单 agent

现在分析这个错误：【真实错误日志】

• 适用场景：需要固定输出格式、风格统一的批量任务。
• 不适用场景：开放式探索——示例会限制模型的创造力。

提示词组合的三个高价值模板：

单个关键词用对了是入门，真正的高手是把多个关键词组合成模板。下面三个模板覆盖长任务里最高频的场景：

模板 A：架构方案评审（第一性原理 + 对抗性审查 + 多轮审查）

【第 1 轮：第一性原理推导】
请从第一性原理出发设计：
1. 列出不可妥协的业务约束
2. 基于约束推导方案，禁止参考现有写法
3. 给出至少 2 个候选方案并对比优劣

【第 2 轮：对抗性审查】
以攻击者视角审查第 1 轮选定的方案：
- 攻击维度：并发/边界/异常/资源耗尽
- 至少 3 个能让方案崩溃的具体输入

【第 3 轮：复验】
验证第 2 轮发现的问题是否已修复，且未引入新问题

模板 B：交付前自检（自我反思 + 思维链）

交付前请按思维链自检：
1. 复述：原始目标 + 当前阶段目标 + 约束
2. 核对：逐项对照自检清单（编译/测试/边界/范围）
3. 反思：本次改动最可能出问题的 1 个点是什么
4. 结论：是否可交付，理由
任何一项不通过，禁止声称已完成。

模板 C：顽固 bug 诊断（角色扮演 + 思维链 + 第一性原理）

角色：调试专家（只关心根因，不关心临时绕过）
请按第一性原理 + 思维链诊断：
1. 现象：【症状】
2. 第一性原理：这个模块"必须"满足的不变量是什么
3. 假设：3 个可能打破不变量的根因
4. 验证：每个假设的最小复现路径
5. 排除：根据日志排除哪些
6. 根因 + 修复（不是绕过）
禁止：给"重启试试"这种治标方案。

💡 高价值技巧：把这三个模板固化进 rules 或 workflow 的提示词节点，长任务里反复调用，不用每次重写。模板是"沉淀培养方案"的最终形态——下一轮跑类似任务，直接复用模板就行。

⚠️ 避坑：提示词不是越长越好。3.1 节讲过"注意力是零和博弈"，提示词越长，关键指令的注意力越被稀释。模板里每句话都要问"删了会怎样"，删了不影响产出的就删掉。一个紧凑的 5 行提示词，往往比一个啰嗦的 50 行提示词效果好。

3.5 多 Agent 协作：分工 + 工作交接 + 主 Agent 只记结果

这是原文最容易被忽略、但价值极高的一环。长任务不应该让一个 agent 全包，而应该拆成多个子 agent 协作。

核心原则：

• 主 agent 只做编排，不亲自下场做事：它负责拆任务、分派、验收，不负责具体执行。这样主 agent 的上下文始终保持干净。
• 子 agent 职责单一：每个子 agent 只做一件事，做完即销毁。
• 工作交接通过文件而非内存：子 agent 之间不直接通信，通过落地文件交接中间产物。文件是持久化的，子 agent 死了产物还在。
• 子 agent 只回传结论，不回传过程：子 agent 把过程细节留在自己的会话日志里，只把结论写进交接文件。主 agent 只读结论，不被过程细节撑爆上下文。

典型交接协议：

子agent A → 写入 .handoff/A-result.md（结论 + 关键产物路径）→ 退出
主agent   → 读 A-result.md，确认无误 → 启动子agent B
子agent B → 读 A-result.md 作为输入 → 执行 → 写入 .handoff/B-result.md → 退出
主agent   → 读 B-result.md → ...

3.6 主动遗忘：让 Agent 学会"扔掉"

与"记住该记的"对应的是"忘掉该忘的"。Agent 默认会把所有中间过程留在上下文里，长任务到中段上下文已经堆满无用细节。

主动遗忘的几种手段：

• 阶段性 /clear：完成一个阶段后，把成果落地到文件，然后 /clear 清空上下文，从文件重新开始下一阶段。
• 子 agent 销毁：子 agent 完成任务后立即销毁，过程细节随会话一起消失，只留交接文件。
• PRD 拆分：长 PRD 拆成阶段 PRD，每个阶段只加载当前阶段的 PRD，不加载全量。
• 日志归档：过程日志归档到 .logs/ 目录，需要时再翻，不占主上下文。

💡 高价值技巧：给主 agent 配一条规则——"每完成一个阶段，主动总结当前阶段成果到 progress.md，然后建议是否需要 /compact"。让遗忘变成 agent 的主动行为，而不是你手动触发。

---

四、Workflow：流水线骨干

当任务可以拆成稳定的、可复用的步骤序列时，就该上 workflow 了。workflow 是把"培养方案"沉淀成"标准化流水线"的关键一步——一旦跑通，下次类似任务可以直接复用。

4.1 OpenWorkflow：脚本式工作流

OpenWorkflow 是一个开源的工作流引擎，支持多 agent 并行、断点续跑、token 预算控制。

安装关键步骤：

# 1. 初始化（需要先有 package.json，没有就 npm init -y）
npx --yes @openworkflow/cli init
# 选择 SQLite 作为 backend，会让它自动安装依赖并创建示例

# 2. 启动 worker
npx @openworkflow/cli worker start

# 3. 运行示例工作流
node openworkflow/hello-world.run.js

# 4. 查看 dashboard
npx @openworkflow/cli dashboard

Python 长任务 runner 模板（绕开 PowerShell 引号地狱）：

"""Real-LLM runner — bypasses PowerShell quote hell."""
import asyncio, json, os, sys
from openworkflow import run_workflow, ToolAgentBackend

def main() -> int:
    if not os.environ.get("ANTHROPIC_API_KEY"):
        print("ERROR: ANTHROPIC_API_KEY not set.", file=sys.stderr)
        return 1

    with open("examples/tech_analysis.py", encoding="utf-8") as f:
        script = f.read()

    args = {
        "target": "openworkflow",
        "focus": "architecture and error handling",
    }

    async def run():
        return await run_workflow(
            script,
            args=args,
            backend=ToolAgentBackend(),   # 真实 LLM + 多轮工具循环
            budget_total=50000,           # 硬 token 上限
            concurrency=8,                # 最大并行 agent 数
            quiet=False,
            journal_path="run_case.jsonl",# 断点续跑日志
            resume=True,                  # 重跑时复用已完成 agent，省 token
        )

    result = asyncio.run(run())
    print(json.dumps(result.result, ensure_ascii=False, indent=2, default=str))
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

关键参数说明：

• budget_total：硬 token 上限，防止单次跑飞烧光额度。
• concurrency：并行 agent 数，机器扛得住就开大。
• journal_path + resume=True：断点续跑的关键组合，长任务被中断后可以从上次完成的 agent 处继续。

⚠️ 避坑：OpenWorkflow 的 SQLite backend 在多 worker 抢同一个 db 时会报 database is locked。生产环境要么单 worker，要么换 PostgreSQL backend。

4.2 CC Workflow Studio：蓝图式工作流

harness的dynamic workflow抑或openworkflow，都是编码中操作流水线，是不是很难看。别怕，CC Workflow Studio 提供了类似 Unreal Engine 蓝图的可视化编辑器。

发现它硬控了vs code的版本，改用trae后亲测可用。

用起来跟 Unreal 的蓝图大体一致——拖节点、连边、配置参数。

可以自定义子 agent——把常用角色（架构师、实现者、审查者）封装成可复用节点：

工作流配置默认存放在：

.vscode\workflows

一个典型 workflow 案例只做了三件事：

1. 启动 claude，并启动 cc workflow studio 的 mcp server：

   claude "【workflow配置路径】"
   claude "/test-workflow01"
   

2. 进入 claude 后，把【workflow配置路径】作为提示词输入。
3. 通过 mcp 回调给 cc workflow studio 执行后续步骤。

你可以活用workflow将阶段任务交接给下一个agent，避免单agent上下文塞爆了。

💡 选型建议：脚本式（OpenWorkflow）适合需要细粒度控制 token、并发、断点续跑的程序员；蓝图式（CC Workflow Studio）适合快速搭建可视化、可分享给非技术人员查看的工作流。两者不冲突，可以先用蓝图搭建原型，再翻译成脚本投入生产。
但不要什么都都用workflow，要控制节点的粒度，并学会固化业务节点。这样更能发挥workflow的优势。

---

五、验收：让 Agent 自己跑测试闭环

5.1 为什么需要自动化测试验收

靠人工 review 一遍 agent 交付的代码，慢、不可靠，而且违背"培养独立性"的初衷。真正的验收应该是：agent 自己跑编译、跑测试、看日志、修问题，跑到全绿为止。

• 避免"看起来没问题"陷阱：agent 容易凭编译通过就声称完成，但运行时崩溃、UI 错位、逻辑回归它自己看不见。
• 给"结果分级验收"提供客观数据：5.2 节的"完全达标 / 部分达标 / 不达标"分级，没有自动化测试就只能凭感觉。
• 形成闭环：测试失败 → 日志反馈 → agent 修复 → 再跑 → 通过。这个闭环不需要你介入，agent 自己跑到收敛。

5.2 测试：无规矩不成方圆。

一个unity模块，agent一上来大概率就直接用dotnet编译，编完提示用户点进play mode自行验收，然后默默等待你反馈结果。
虽然最终目的就是啥也不干，一上来就让agent验收自己的写的代码。但基于客观现实，这其实很难闭环。我们需要借助一些框架或者规则来明确怎么测试验收。
接下来，我们用以往用airtest的经验来实现这个闭环。

5.2.1 Unity mcp

Unity 项目最缺的就是"agent 自己驱动 Unity Editor"的能力——传统 CLI 工具只能改代码，不能编译、不能跑场景、不能看 Game View。为什么不直接采用airtest，而是通过mcp来驱动unity editor？
个人的理由是：mcp天然支持对接ai，并提供了dynamic-code机制，可以按节点执行，而airtest则需要额外的开发成本来对接ai。
常见的unity mcp有：

https://github.com/CoplayDev/unity-mcp.git
https://github.com/hatayama/unity-cli-loop

unity-cli-loop 个人采用的是unity-cli-loop (uloop)，（前身 uLoopMCP，下文简称 uloop）专门解决这个问题。

四大核心理念：

1. 自主持开发循环：compile → run-tests → get-logs → clear-console，agent 自己跑编译、跑测试、看日志、修问题。
2. AI 驱动 Editor 操作：execute-dynamic-code 执行任意 C# 代码，screenshot 截 Editor 窗口验证 UI 布局。
3. PlayMode 自动化测试：simulate-mouse-ui 点击 UI、simulate-keyboard 按键、record-input / replay-input 录制回放，AI 能像玩家一样玩游戏并验证行为。
4. 最少工具集合：用 execute-dynamic-code 一个工具覆盖绝大多数 Editor 操作，避免工具爆炸让 agent 选错。

与验收强相关的 6 个 Skills：

Skill	作用
/uloop-compile	触发编译，返回 error/warning，能识别内置 linter 漏掉的错
/uloop-run-tests	跑 Unity Test Runner（PlayMode/EditMode），支持 filter，可输出 xml 结果给 agent 读
/uloop-get-logs	拉取 Unity Console 日志，支持 LogType 过滤、正则、Stack Trace 搜索
/uloop-clear-console	清空 Console，避免旧日志污染下一轮验收
/uloop-screenshot	截 Editor/Game View，agent 能"看"自己做的 UI 对不对
/uloop-execute-dynamic-code	跑任意 C#，覆盖 prefab 批量改、场景操作、菜单调用等

安装要点：

# 1. Unity Package Manager 加 git URL
#    https://github.com/hatayama/unity-cli-loop.git?path=/Packages/src

# 2. Unity 内 Window > Unity CLI Loop > Settings 点 Install CLI
#    或直接 npm 安装
npm install -g uloop-cli

# 3. 装 Skills 到对应 IDE（Claude Code / Cursor / Codex / Antigravity / Copilot）
uloop skills install --claude

⚠️ 依赖：Unity 2022.3+，Node.js 22.0+。run-tests 需额外装 com.unity.test-framework；Input System 相关工具（simulate-keyboard / simulate-mouse-input / record-input / replay-input）需 com.unity.inputsystem。

让 agent 在交付前自己跑一遍这个循环，比你 review 它的代码高效得多：

agent 完成 Lua/C# 改动
  ↓
/uloop-compile                  # 触发编译
  ↓
/uloop-get-logs LogType=Error   # 拉错误日志
  ↓ （有错？）── 是 ──→ 修代码 → 回到 compile
  ↓ （无错）
/uloop-run-tests FilterType=all # 跑全量测试
  ↓
读 xml 结果 / 失败用例日志
  ↓ （有失败？）── 是 ──→ 定位 → 修 → 回到 compile
  ↓ （全过）
/uloop-screenshot GameView      # 截 Game View 看 UI
  ↓ （UI 错位？）── 是 ──→ /uloop-execute-dynamic-code 调整 → 回到 screenshot
  ↓ （UI 正常）
交付

不依赖 Skills 也能直接走 CLI（适合嵌入 workflow 脚本）：

uloop compile --wait-for-domain-reload true
uloop get-logs --max-count 50
uloop run-tests --filter-type all
uloop screenshot --target GameView

5.2.2 单元测试

• 为什么需要单元测试？
  其实我们可以通过硬性流程让agent根据检测hierarchy数来触发控件，但：
  一方面极其浪费token，它需要解析hierarchy树，还要根据控件的路径到代码里面匹配对应的业务逻辑，而且每次测试都需要重复这些步骤，消耗同样大量的token，显然这不可持续。
  另一方面：agent需要理解上下文来临时定制测试逻辑，每次测试可能都不一样的理解，流程极度不稳定。

• 那么，我们如何实现单元测试呢？
  我们可以在workflow流程里面添加定制单元测试的步骤，预先定验收点，让agent编写单元测试代码。每次测试都固定代码，即不用解析hierarchy取匹配逻辑，也不会因为不充分理解业务或者上下文而胡乱测试。
  细分好单元测试的粒度，作为单个dynamic-code节点，我们可以组合多个测试用例，来实现较为长链的复合测试。

---

六、后处理：结果不理想怎么办

长任务不可能每次都一次跑通，必须有后处理手段兜底。

6.1 回溯（rewind）：从检查点重新开始

rewind 是 Claude Code 的回溯功能，可以指定从某个检查点开始重新执行，而不必从头跑一遍。

rewind 实操要点：

• 回溯点选择：尽量回溯到最近一个"已验证正确"的检查点，而不是出问题前那一刻——否则大概率重蹈覆辙。
• 回溯后改提示词：回溯不只是重跑，更是改方向的机会。回溯后调整提示词再跑，往往能走出新路。
• 配合 cf 存档：rewind 是工具内的回溯，cf 是会话级的存档。两者配合，可以在更早的会话节点重新开始。

6.2 极端性存档上下文

每个阶段借助第三方skill（例如cf）将上下文保存起来，方便后续回溯。

6.3 其他后处理技巧

• 失败 agent 转人工：子 agent 失败超过 N 次不要无限重试，把失败上下文打包成"待人工处理"文件，主 agent 跳过该任务继续推进，最后由人工兜底。
• journal + resume 断点续跑：OpenWorkflow 的 journal_path + resume=True 是长任务断点续跑的利器，比从头重跑省 80% token。
• 结果分级验收：不要 binary 地判断"成功/失败"。把结果分成"完全达标 / 部分达标 / 不达标"三级，部分达标的可以局部 rewind 重跑，不必全量重做。
• 过程日志归档：每次长任务的完整过程日志归档到 task-logs/<日期>/<任务名>/，便于事后复盘哪些环节最容易失败，反向优化培养方案。

---

六、总结：培养 Agent 独立性的"四件套"

回到开头那个比喻——Agent 是新兵蛋子，你要培养它独当一面。整套培养方案可以浓缩为四件套：

培养维度	核心手段	关键工具
硬性流程	预设知识库 + 架构师多轮审查 + 文档自动纠正	memory / CLAUDE.md / rules
防打断	禁止询问 + 优化记忆 + 优化上下文 + 多 agent 协作 + 主动遗忘	--dangerously-skip-permissions / cf / graphify / headroom
流水线骨干	把培养方案沉淀成可复用 workflow	OpenWorkflow / CC Workflow Studio
后处理兜底	回溯 + 断点续跑 + 失败转人工 + 结果分级验收 + 自动化测试闭环	rewind / journal+resume / unity-cli-loop (uloop)

培养 Agent 处理长任务的独立性，本质上是在做三件事：

1. 让它有地图——预设知识库、PRD、文档同步，确保它始终知道自己在哪、要去哪。
2. 让它不停顿——权限放行、上下文优化、多 agent 分工，确保它不被打断、不被撑爆。
3. 让它能回头——rewind、断点续跑、分级验收，确保它跑错了能回来，回来后能继续。

剩下的，就是耐心。Agent 培养和新兵培养一样，前几轮你要手把手教，跑通一两个 workflow 后，它就能开始自己跑了。等到 workflow 沉淀到第三版、第四版，你会发现它已经能独当一面——而你需要做的，只是审查它交回来的结果。

最后一句话：不要指望超级模型一次跑通长任务，要指望你设计的流程让普通模型也能跑通。流程稳了，模型再普通也能出活；流程不稳，再强的模型也会翻车。