The Markdown Org

崩溃现场：一个 Agent 试图成为所有人

你的 AI 看起来变笨了——多半是被上下文淹没了

你让 Cursor agent 重构一个模块。进展顺利。然后你追加一句：「顺便把测试也写了。」再追加：「文档也更新一下。」

前 5 轮一切如常。到第 10 轮就开始跑偏——它写的测试用例引用了一个刚被自己删掉的函数。你指出错误，它改了测试，但文档描述的接口又跟改后的代码对不上了。

你正在经历三种不同的摩擦同时发作：

1. 上下文串味——重构时的思路带进了测试编写。代码里已经把 getUserById 改成了 findUser，但 context window 里还残留着旧的调用方式，于是测试「看到」了两个版本，选了错的那个。
2. 等待阻塞——你其实可以在它写测试的时候同步推进文档，但你做不到。你只有一个对话窗口，只能看着它一行行地生成测试代码，等。
3. 你成了人工路由器——「先改这个文件」、「现在去写测试」、「回来更新文档」——这些调度决策全部落在你头上。你本来雇了一个工程师，结果自己当起了项目经理。

想象一块白板。你在上面画系统架构图。画到一半，又要在同一块白板上画测试矩阵。再加上文档大纲。三张图在物理上互相覆盖。白板就那么大，三个独立的思考空间根本挤不下。

把这三种摩擦放在一起看，结论就很清楚了：这个活不应该是同一个人做的。

卡住的地方在架构：一个 agent 在一个 context window 里同时处理多个需要深度专注的任务，天花板就在那里。模型再强，白板还是那么大。

简历就是接口

一个 Markdown 文件的全部——从约束推导到完整定义

既然一个 agent 不行，那就需要多个。问题变成：怎么定义一个 agent 的角色？

从约束倒推。角色定义需要持久化，不能每次对话重新描述一遍，所以得是文件。人要能直接读写，JSON 或二进制都太重，Markdown 最合适。系统还得结构化地提取元数据——模型选择、权限这些东西不能靠正则猜——所以加个 YAML frontmatter。

三条约束一合并，答案就一个：YAML 头 + Markdown 正文 = 完整的 Agent 定义。没有第二个文件。

这就是 Cursor subagent 的全部形态。看一个实际的定义文件：

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities,
  injection risks, secret leaks, and unsafe patterns.
model: inherit
readonly: true
---

You are a security-focused code reviewer. For any code change:
1. Check for injection vulnerabilities (SQL, XSS, command injection)
2. Identify hardcoded secrets or credentials
3. Flag unsafe deserialization or eval usage
4. Check dependency security (known CVEs)

Output: ranked findings with severity (Critical / High / Medium / Low).
If clean, state "No security issues identified."

十几行就能定义一个完整的 agent。文件放到 .cursor/agents/ 目录下，Cursor 就会加载它。

每个字段都有明确的职责。要快速理解它们，最好的办法是问一个问题：删掉会怎样？

有个细节值得单独说：description 其实是路由规则，给系统看的。当你说「帮我 review 这个 PR」，主 agent 会扫描所有 subagent 的 description，用语义匹配找到最相关的角色，自动委派。description 写得模糊，路由就不准。把它当招聘帖标题来写就对了。

model 决定 subagent 用哪个模型思考：

model: inherit                            # 默认——继承父 agent 的模型
model: fast                               # 快速低成本

# 日常够用
model: gemini-3-flash
model: claude-4.6-sonnet-medium-thinking
model: gpt-5.2-high

# 重度推理
model: gpt-5.2-xhigh
model: gemini-3.1-pro
model: claude-4.6-opus-max-thinking

大多数时候 inherit 就够了——你用什么模型跟它说话，它就用什么模型思考。只有当你明确知道某个角色需要更快更便宜、或需要特定模型的深度推理时，才显式指定。

两种调用方式

显式调用——你点名要人：/security-reviewer 检查这个文件有没有注入风险。直接，明确，零歧义。

自动委派——你只说需求：「帮我看看这段代码的安全性」。主 agent 根据 description 语义匹配，自动路由到合适的 subagent。你不需要记住谁叫什么名字。

Cursor 自带三个内置 subagent：explore（代码搜索专家），shell（命令执行），browser（浏览器自动化）。你之前用的其实一直是 subagent 架构——只是现在你可以定义自己的角色了。

隔离不是限制

让每个 agent 知道更少，整个系统反而犯更少的错

Subagent 有个关键点听起来有点反常识：隔离越强，并行越真实。

想象三个人共用一张办公桌。理论上他们可以「并行工作」——但实际上，一个人摊开的图纸会压住另一个人的笔记，第三个人的咖啡随时可能洒在所有人的文件上。他们花在协调物理空间上的精力，可能比花在思考上的还多。

现在给每个人一个独立的工作间。门一关，他们真正在并行。互不干扰，各自深入。

这就是 context isolation 做的事。如果你熟悉 Unix，对应的概念是 fork()——子进程获得父进程内存空间的副本，但之后的修改互不影响。Subagent 获得必要的任务上下文，但之后的推理在独立的 context window 中进行，不会污染主 agent 的思考空间，也不会被其他 subagent 的中间结果干扰。

换个角度讲：context isolation 是聚焦，不是失忆。Subagent 拿到了完成任务所需的全部信息，只是不会被无关内容分散注意力。安全审查员不需要知道你同时在做性能优化，性能审查员也不用关心安全审查的中间发现。这种「各管各的」是刻意设计的——把噪音隔开，反而更容易把一件事想深。

另一个直接收益是省等待时间。安全审查需要 15 秒，性能审查需要 12 秒，文档检查需要 8 秒。串行执行：35 秒。并行执行：15 秒。任务越多，折叠效果越显著。

当所有 subagent 完成工作，它们将各自的分析结果——纯文本——返回给主 agent。主 agent 持有全局上下文，负责综合这些独立报告，形成统一的回复。推理阶段彼此隔离，汇报阶段再做整合——先独立思考，再统一汇总。

文件夹即团队

从一个文件扩到一个团队：递归的力量

Subagent 可以派遣 subagent。主 agent 委派安全审查，安全审查 agent 如果发现可疑的依赖项，可以进一步派遣 explore agent 去搜索相关代码。这种递归委派能力意味着你不需要预设所有可能的工作流——agent 根据实际情况动态分工。

回过头看 .cursor/agents/ 文件夹：

.cursor/agents/
├── security-reviewer.md
├── perf-reviewer.md
└── docs-checker.md

这个文件结构本身就是一张 org chart。每个 .md 文件是一个岗位。文件夹是团队。删一个文件就是裁员，加一个文件就是招聘。

顺着这个思路往下想：

1. 一个文件 = 一个 agent → 一个文件夹 = 一个团队 → 一个仓库 = 一个组织。从单兵到军团，只是文件数量的变化。
2. 团队可以 git 管理。 git log 看团队的演变历史。git blame 追溯谁在什么时候修改了某个 agent 的职责。Pull request 审查 agent 定义的变更——组织架构变更也要走 code review。
3. 团队可以 fork。 看到一个开源项目的 agents/ 定义得好？复制这个文件夹，你就拥有了同样的团队。你不需要从零开始设计分工，直接复用别人的「团队配置」。

分工的道理一直没变——从厨房旅制度到 Unix 哲学到微服务，都是这个逻辑。只是这一次，团队定义本身变成了代码——可以 git 管理、版本化、code review。

你的第一支特种部队

五分钟，从零到一个能并行工作的 review 团队

场景：你提交了一段代码变更，希望同时获得安全审查和性能审查。两个独立的专家，并行工作，各自提交报告。

你只需要创建两个文件。

安全审查员

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities,
  injection risks, secret leaks, and unsafe patterns.
model: inherit
readonly: true
---

You are a security-focused code reviewer. For any code change:
1. Check for injection vulnerabilities (SQL, XSS, command injection)
2. Identify hardcoded secrets or credentials
3. Flag unsafe deserialization or eval usage
4. Check dependency security (known CVEs)

Output: ranked findings with severity (Critical / High / Medium / Low).
If clean, state "No security issues identified."

readonly: true——审查员只看不碰代码。model: inherit——继承你当前使用的模型，不用额外操心选型。

性能审查员

---
name: perf-reviewer
description: Reviews code changes for performance issues, N+1 queries,
  memory leaks, and unnecessary computations.
model: inherit
readonly: true
---

You are a performance-focused code reviewer. For any code change:
1. Identify N+1 query patterns or unnecessary database calls
2. Flag potential memory leaks or unbounded growth
3. Check for O(n²) or worse algorithms where O(n) is possible
4. Spot unnecessary re-renders or redundant computations

Output: specific findings with estimated impact (High / Medium / Low).

两个文件创建完毕。现在来看触发方式。

触发

自动委派——你只需说一句：

帮我 review 一下这个 PR 的改动

主 agent 读取两个 agent 的 description，判断「安全漏洞审查」和「性能问题审查」都与 review 相关，自动同时派发。两者在各自独立的 context 中并行运行，各自返回报告。你拿到的是综合后的双视角审查结果。

显式调用——你也可以精确指定：

/security-reviewer 检查这个文件有没有注入风险

点名调用，零歧义。适合你已经知道需要哪个专家的场景。

整条链路不到 20 秒。如果串行，你要等至少 30 秒，而且还要亲自在两种审查视角之间切换调度。