当智能体变成一份 Markdown 文档

在传统的软件工程中，构建一个"智能体"（Agent）意味着编写大量代码：状态机、决策树、API 集成、错误处理、权限管理。而在 LLM 时代，定义一个功能完备的 AI 智能体，可能只需要一份结构良好的 Markdown 文档。

这不是夸张。以 Claude Code 的配置体系为例，一个 .md 文件可以定义 Agent 的身份、行为约束、工具权限、专业知识、工作流程，甚至跨会话的持久记忆。但要真正理解"为什么 Markdown 就够了"，以及"如何写出高效的 Agent 定义"，需要先回到第一性原理——理解 LLM 的本质、Agent 的运行机制，以及上下文窗口的物理约束。

本文将从底层原理出发，逐层构建对 Agentic Coding 的完整认知：先理解 LLM 是什么、Agent Loop 如何运转、上下文窗口为何是核心瓶颈；再拆解 Markdown 配置体系的四层架构；最后落地到实操方法论——如何管理对话、沉淀知识、用工程手段约束 Agent、为 AI 设计友好的工作环境。

全景思维导图

mindmap
  root((Agentic Coding 全景))
    第一性原理
      LLM 本质
        概率性文本生成器
        非确定性推理引擎
        Token 预测机制
      Agent Loop
        感知-推理-行动循环
        LLM + 工具 + 循环 = Agent
        自主决策与工具调用
      上下文窗口
        工作记忆的物理约束
        注意力退化曲线
        Lost in the Middle 效应
    Markdown 配置体系
      CLAUDE.md
        项目记忆
        行为约束
        分层加载
      Commands
        参数化提示词模板
        斜杠触发
        变量插值
      Skills
        可复用知识包
        领域专业知识
        工作流定义
      Sub Agents
        独立上下文窗口
        工具权限隔离
        持久化记忆
    实操方法论
      对话管理
        短对话优于长对话
        任务分解策略
        上下文隔离
      知识沉淀
        从会话到持久记忆
        Rules 与 Memory
        经验复利效应
      工程约束
        Linter 与 Git Hooks
        拦截偷懒行为
        工程手段优于 Prompt 指令
      AI 友好设计
        信息架构优化
        API 设计平衡
        命名与统计直觉
      刻意练习
        像学乐器一样学 AI
        从失败中提取教训
        建立肌肉记忆

模式总览

本文覆盖的核心可迁移模式：

# 模式名称 一句话口诀 覆盖场景
1 概率性推理 LLM 是统计直觉而非逻辑推理 理解 Agent 行为的不确定性、命名偏好、错误模式
2 感知-行动循环 LLM + 工具 + 循环 = Agent Agent Loop 的运行机制、工具调用、自主决策
3 上下文即工作记忆 有限窗口决定一切策略 对话管理、任务分解、信息密度优化
4 分层配置 环境-触发-知识-执行四层分离 CLAUDE.md / Commands / Skills / Sub Agents
5 知识外化 把脑中隐性知识变成文档 Rules、Memory、经验复利
6 双重投资回报 对人好的改进对 AI 同样有效 文档、架构、测试速度的双重价值
7 工程约束优于提示 用代码而非文字约束 Agent Git Hooks、Linter、命令拦截
8 统计直觉对齐 顺应而非对抗 Agent 的命名偏好 AI 友好的命名、API 设计、信息架构 
flowchart LR
    subgraph 原理层
        P1[概率性推理]
        P2[感知-行动循环]
        P3[上下文即工作记忆]
    end
    subgraph 配置层
        P4[分层配置]
        P5[知识外化]
    end
    subgraph 实践层
        P6[双重投资回报]
        P7[工程约束优于提示]
        P8[统计直觉对齐]
    end
    P1 --> P2
    P2 --> P3
    P3 --> P4
    P3 --> P5
    P4 --> P6
    P5 --> P6
    P4 --> P7
    P1 --> P8
    P6 --> P7
    P7 --> P8

第一性原理：理解 Agentic Coding 的底层逻辑

在讨论如何用 Markdown 定义 Agent 之前，需要先回答三个基础问题：LLM 到底是什么？Agent 如何运转？上下文窗口意味着什么？这三个问题的答案，决定了所有上层策略的设计逻辑。

flowchart TB
    subgraph 第一性原理
        A[LLM 的本质] --> B[Agent Loop 的运行机制]
        B --> C[上下文窗口的物理约束]
    end
    C --> D[为什么 Markdown 就够了]
    C --> E[为什么需要分层配置]
    C --> F[为什么短对话优于长对话]
    style A fill:#e1f5fe
    style B fill:#e1f5fe
    style C fill:#e1f5fe

LLM 的本质：概率性文本生成器

理解 Agentic Coding 的第一步，是准确理解 LLM 的本质。LLM 不是数据库，不是搜索引擎，也不是确定性的推理引擎。它是一个概率性的文本生成器——给定一段输入文本（prompt），它预测最可能的下一个 token，然后把这个 token 加入输入，再预测下一个，如此循环。

flowchart LR
    A["输入: 'The capital of France is'"] --> B[LLM 计算概率分布]
    B --> C["P('Paris')=0.92"]
    B --> D["P('Lyon')=0.03"]
    B --> E["P('the')=0.02"]
    C --> F["输出: 'Paris'"]
    F --> G["新输入: 'The capital of France is Paris'"]
    G --> H[继续预测下一个 token...]

这个机制带来几个关键推论：

1. LLM 的"知识"是统计相关性，而非逻辑推理。 当 LLM 回答"法国的首都是巴黎"时，它并不是在"推理"，而是因为在训练数据中，"法国"和"巴黎"在"首都"这个上下文中高频共现。这意味着 LLM 在训练数据覆盖良好的领域表现出色，但在罕见场景下可能给出"看起来合理但实际错误"的答案。

2. LLM 的输出具有概率性。 同样的输入可能产生不同的输出（受 temperature 参数控制）。这不是 bug，而是 feature——它使 LLM 能够生成创造性的内容，但也意味着不能期望 LLM 每次都给出完全一致的结果。

3. LLM 没有持久记忆。 每次对话都是从零开始。LLM 不会"记住"上一次对话的内容，除非这些内容被显式地放入当前的上下文窗口中。这个特性直接决定了为什么需要 CLAUDE.md 这样的外部记忆机制。

4. LLM 的"推理"是涌现行为。 当模型规模足够大、训练数据足够丰富时，LLM 展现出类似推理的能力。但这种能力的边界是模糊的——它在常见模式上表现优异，在需要真正创新推理的场景下则不可靠。

模式提炼：概率性推理

模式公式：P(next_token) = f(所有前文 tokens 的统计相关性)

迁移表：

场景 输入上下文 统计基础 可靠性 说明
常见编程模式 标准 API 调用代码 训练数据中大量出现 高 如 Spring Boot REST 端点
项目特定约定 私有框架代码 训练数据中未出现 低 需要通过 CLAUDE.md 补充上下文
创新性设计 全新架构方案 训练数据中无直接对应 中 可组合已知模式，但需人工验证
边界情况处理 罕见错误场景 训练数据中稀少 低 需要显式提供示例和约束

核心洞察：当听到"AI 给了错误答案"时，首先应该检查的不是模型能力，而是上下文是否充分。LLM 的表现与输入上下文的质量直接相关——垃圾进，垃圾出；精确的上下文进，精确的答案出。这就是为什么 CLAUDE.md 和 Skills 机制如此重要——它们本质上是在为 LLM 提供高质量的上下文。

Agent Loop：感知-推理-行动的循环

单独的 LLM 只能做文本补全。要让它成为一个能完成实际任务的 Agent，需要三个要素的组合：LLM（大脑）+ 工具（手脚）+ 循环（自主性）。

flowchart TB
    A[用户输入任务] --> B{Agent Loop}
    B --> C[LLM 分析当前状态]
    C --> D{需要更多信息?}
    D -->|是| E[调用工具: 读文件/搜索/执行命令]
    E --> F[工具返回结果]
    F --> B
    D -->|否| G{需要修改代码?}
    G -->|是| H[调用工具: 编辑文件]
    H --> I[验证修改结果]
    I --> B
    G -->|否| J{任务完成?}
    J -->|否| B
    J -->|是| K[输出最终结果]
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style E fill:#e3f2fd
    style H fill:#e3f2fd

这个循环的每一轮都遵循相同的模式：

  1. 感知：LLM 读取当前上下文（用户消息 + 历史对话 + 工具返回的结果）
  2. 推理：基于上下文，决定下一步应该做什么（调用哪个工具、传什么参数，或者直接回复用户）
  3. 行动：执行决策（调用工具或生成回复）
  4. 观察：将行动的结果加入上下文，开始下一轮循环
sequenceDiagram
    participant U as 用户
    participant A as Agent(LLM)
    participant T as 工具集
    
    U->>A: "修复登录页面的 bug"
    
    Note over A: 第1轮: 感知+推理
    A->>T: read_file("src/login.tsx")
    T-->>A: 文件内容
    
    Note over A: 第2轮: 分析+搜索
    A->>T: grep("handleLogin")
    T-->>A: 搜索结果
    
    Note over A: 第3轮: 定位+修复
    A->>T: edit_file("src/login.tsx", changes)
    T-->>A: 修改成功
    
    Note over A: 第4轮: 验证
    A->>T: run_tests("login.test.tsx")
    T-->>A: 测试通过
    
    A->>U: "已修复: 问题是..."

理解 Agent Loop 的关键在于：每一轮循环都会消耗上下文空间。用户的消息、LLM 的思考过程、工具调用的参数、工具返回的结果——所有这些都会被追加到上下文中。这意味着 Agent Loop 的轮次越多，上下文消耗越大，最终可能触及上下文窗口的物理限制。

Agent Loop 还有一个重要特性：LLM 在每一轮都会重新阅读完整的上下文。这既是优势（保证了一致性），也是劣势（随着上下文增长，注意力会被稀释）。

模式提炼：感知-行动循环

模式公式：Agent = while(!done) { context = perceive(); action = reason(context); result = act(action); context += result; }

迁移表：

场景 感知 推理 行动 说明
Bug 修复 读取错误日志+代码 定位根因 编辑代码+运行测试 典型的多轮循环
代码审查 读取 diff+规范 对比规范找问题 输出审查意见 可能只需 1-2 轮
新功能开发 读取需求+现有架构 设计方案 创建文件+编写代码 轮次最多，上下文消耗最大
重构 读取现有代码+依赖 规划重构步骤 批量修改文件 需要精确的任务分解

核心洞察：当听到"Agent 做了很多无用功"时，问题往往不在 Agent 的推理能力，而在于循环的效率——每一轮是否提供了足够精确的上下文？工具返回的信息是否有助于推进任务？这就是为什么 Commands 和 Skills 机制如此重要——它们通过预定义的工作流减少了 Agent 的"摸索"轮次。

上下文窗口：Agent 的工作记忆

上下文窗口是理解所有 Agentic Coding 策略的关键。可以把它类比为人的工作记忆（Working Memory）——它是 Agent 在任何时刻能"看到"和"思考"的全部信息。

flowchart TB
    subgraph 上下文窗口["上下文窗口 (如 200K tokens)"]
        direction TB
        A["系统提示词 (CLAUDE.md 内容)"]
        B["用户消息历史"]
        C["Agent 的思考过程"]
        D["工具调用记录"]
        E["工具返回结果"]
        F["当前正在生成的回复"]
    end
    
    G["窗口外: 之前的对话"] -.->|"不可见"| 上下文窗口
    H["窗口外: 未读取的文件"] -.->|"不可见"| 上下文窗口
    I["窗口外: 其他项目知识"] -.->|"不可见"| 上下文窗口
    
    style 上下文窗口 fill:#fff8e1
    style G fill:#ffebee
    style H fill:#ffebee
    style I fill:#ffebee

上下文窗口的三个关键特性

1. 有限性

即使是 200K token 的上下文窗口，看起来很大（约 15 万个英文单词），但在实际的 Agent 工作中会被迅速消耗：

pie title "一次典型 Agent 会话的上下文消耗"
    "系统提示词 + Rules" : 10
    "用户消息" : 5
    "Agent 思考过程" : 20
    "工具调用参数" : 10
    "工具返回结果(文件内容等)" : 40
    "Agent 生成的代码" : 15

一个中等复杂度的编程任务，可能在 10-20 轮 Agent Loop 后就消耗掉大部分上下文空间。

2. 注意力退化（Lost in the Middle）

研究表明，LLM 对上下文中不同位置的信息，注意力分布是不均匀的。开头和结尾的信息得到更多关注，而中间部分的信息容易被"遗忘"。

flowchart LR
    subgraph 注意力分布
        direction LR
        A["开头<br/>注意力: 高"] --- B["中间<br/>注意力: 低"] --- C["结尾<br/>注意力: 高"]
    end
    
    D["实际影响:<br/>早期的工具返回结果<br/>可能被后续信息'淹没'"]
    
    注意力分布 --> D

这意味着：随着对话的进行，Agent 可能会"忘记"早期获取的关键信息，导致重复搜索、前后矛盾，甚至引入之前已经修复过的 bug。

3. 上下文污染

上下文中的错误信息不会自动消失。如果 Agent 在第 3 轮生成了一段有 bug 的代码，即使在第 5 轮修复了，第 3 轮的错误代码仍然存在于上下文中，可能在后续轮次中"误导" Agent。

flowchart TB
    A["第3轮: Agent 生成错误代码"] --> B["第4轮: 发现错误"]
    B --> C["第5轮: 修复错误"]
    C --> D["第8轮: Agent 再次参考上下文"]
    D --> E{"看到了哪个版本?"}
    E -->|"可能看到第3轮的错误版本"| F["再次引入相同 bug"]
    E -->|"看到第5轮的修复版本"| G["正确继续"]
    style F fill:#ffcdd2
    style G fill:#c8e6c9

上下文管理的核心策略

理解了上下文窗口的特性后，所有的 Agentic Coding 策略都可以归结为一个核心目标：在有限的上下文空间内，最大化有效信息密度。

flowchart TB
    A[上下文管理核心策略] --> B[减少无效信息]
    A --> C[增加有效信息]
    A --> D[隔离信息空间]
    
    B --> B1[短对话优于长对话]
    B --> B2[精确的工具调用]
    B --> B3[避免重复搜索]
    
    C --> C1[CLAUDE.md 预加载关键上下文]
    C --> C2[Skills 注入领域知识]
    C --> C3[结构化的错误信息]
    
    D --> D1[Sub Agent 独立上下文]
    D --> D2[任务分解与隔离]
    D --> D3[新对话 vs 继续对话]

模式提炼：上下文即工作记忆

模式公式：有效性 = 有效信息量 / 总上下文消耗 × 注意力权重(位置)

迁移表：

场景 上下文压力 推荐策略 说明
简单 bug 修复 低 单次对话完成 2-5 轮 Loop 即可
中等功能开发 中 预加载 Rules + 精确搜索 控制在 10-15 轮
大型重构 高 任务分解 + Sub Agent 每个子任务独立上下文
跨模块修改 极高 多次短对话 + 持久记忆 每个模块一次对话

核心洞察：当听到"Agent 在长对话中表现越来越差"时，根因几乎总是上下文窗口的退化。解决方案不是"换一个更强的模型"，而是"开一个新对话"。这就是为什么 Sub Agent 机制如此重要——它通过创建独立的上下文窗口，从根本上解决了上下文污染问题。

Markdown 配置体系：用文档定义智能体

理解了第一性原理之后，再来看 Claude Code 的 Markdown 配置体系，就能理解每一层设计背后的"为什么"。

这套体系包含四种机制：CLAUDE.md（项目记忆）、Commands（参数化触发）、Skills（专业知识包）、Sub Agents（独立执行体）。它们按照关注点分离的原则，各自承担不同的职责。

flowchart TB
    subgraph 四层配置体系
        direction TB
        L1["CLAUDE.md<br/>──────────<br/>项目记忆与行为约束<br/>始终在场 | 自动加载"]
        L2["Commands<br/>──────────<br/>参数化提示词模板<br/>按需加载 | 用户触发"]
        L3["Skills<br/>──────────<br/>可复用知识包<br/>按需加载 | Agent 自动匹配"]
        L4["Sub Agents<br/>──────────<br/>独立执行的专业角色<br/>按需加载 | 独立上下文"]
    end
    
    L1 -->|"提供环境上下文"| L2
    L2 -->|"触发具体任务"| L3
    L3 -->|"提供专业知识"| L4
    L4 -->|"隔离执行"| R[任务完成]
    
    style L1 fill:#e8eaf6
    style L2 fill:#e3f2fd
    style L3 fill:#e8f5e9
    style L4 fill:#fff3e0

CLAUDE.md：项目记忆与行为约束

CLAUDE.md 是整个体系的基础层。它解决的核心问题是：LLM 没有持久记忆，每次对话都从零开始。通过在对话开始时自动加载 CLAUDE.md 的内容，Agent 能立即获得项目的关键上下文。

分层加载机制

CLAUDE.md 支持三级作用域，按从全局到局部的顺序加载：

flowchart TB
    A["~/.claude/CLAUDE.md<br/>全局级：跨项目通用偏好"] --> D[合并注入上下文]
    B["项目根目录/CLAUDE.md<br/>项目级：技术栈、规范、架构"] --> D
    C["当前目录/CLAUDE.md<br/>目录级：模块特定约束"] --> D
    D --> E["Agent 开始工作<br/>已具备完整的项目认知"]
    
    style A fill:#e8eaf6
    style B fill:#c5cae9
    style C fill:#9fa8da

这种分层设计的精妙之处在于：它用最小的上下文消耗，提供了最大的信息覆盖。全局偏好只写一次，项目规范只在项目级定义，模块特定的约束只在需要时加载。

CLAUDE.md 的内容结构

一份高效的 CLAUDE.md 应该包含以下信息（按优先级排序）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 项目概述
这是一个基于 Spring Boot 3.2 的电商平台后端服务。
Java 21，Maven 构建，MySQL + Redis。

# 关键命令
- 构建: `mvn clean package -DskipTests`
- 测试: `mvn test -pl module-name`
- 本地运行: `mvn spring-boot:run -pl app`

# 代码规范
- REST API 统一返回 `Result<T>`，见 `common/Result.java`
- 使用 MapStruct 做 DTO 转换，禁止手写 getter/setter 转换
- 异常统一通过 `@RestControllerAdvice` 处理

# 架构约束
- 严格分层: Controller → Service → Repository
- 禁止 Controller 直接访问 Repository
- 跨模块调用必须通过 API 接口，禁止直接依赖实现类

# 当前工作重点
- 正在重构订单模块，从单体迁移到 DDD 风格
- 支付模块不要改动，正在等待第三方 SDK 升级

关键原则：CLAUDE.md 应该是声明式的——告诉 Agent “是什么"和"不要做什么”，而不是"怎么做"。具体的"怎么做"应该交给 Skills 和 Commands。

从第一性原理理解 CLAUDE.md 的设计

回到上下文窗口的约束：CLAUDE.md 的内容会在每次对话开始时被注入上下文。这意味着：

  • 内容必须精炼：每多一行，就多消耗一点宝贵的上下文空间
  • 信息密度要高：用最少的 token 传达最关键的信息
  • 避免重复：不要在 CLAUDE.md 中写已经在代码注释或 README 中存在的信息
flowchart LR
    A["CLAUDE.md 内容"] -->|"每次对话都消耗"| B["上下文空间"]
    B -->|"剩余空间"| C["实际工作可用"]
    
    D["过长的 CLAUDE.md"] -->|"挤占"| C
    E["过短的 CLAUDE.md"] -->|"Agent 需要额外搜索<br/>反而消耗更多上下文"| C
    
    F["最优: 精炼但完整"] -->|"平衡"| C
    style F fill:#c8e6c9
    style D fill:#ffcdd2

Commands：参数化的提示词模板

Commands 解决的问题是：重复性任务的标准化触发。如果发现自己经常对 Agent 说类似的话（“帮我写一个 API 端点，路径是 X，方法是 Y”），就应该把它封装成一个 Command。

Command 的定义结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
---
name: create-api
description: 创建一个新的 REST API 端点
arguments:
  - name: method
    description: HTTP 方法 (GET/POST/PUT/DELETE)
    required: true
  - name: path
    description: API 路径 (如 /api/v1/users)
    required: true
  - name: description
    description: API 功能描述
    required: false
---

创建一个新的 REST API 端点。

HTTP 方法: $ARGUMENTS.method
API 路径: $ARGUMENTS.path
功能描述: $ARGUMENTS.description

请按照以下步骤实现:
1. 在对应的 Controller 中添加端点方法
2. 在 Service 层添加业务逻辑接口和实现
3. 如需要，在 Repository 层添加数据访问方法
4. 编写单元测试
5. 更新 API 文档

遵循项目的 REST API 规范（见 CLAUDE.md）。

用户只需输入 /create-api POST /api/v1/orders "创建订单" 即可触发完整的工作流。

Command 与上下文的关系

从上下文管理的角度看，Command 的价值在于：用少量的用户输入 token，展开为大量的精确指令 token。这比用户每次手动输入完整指令更高效，也更一致。

flowchart LR
    A["用户输入:<br/>/create-api POST /orders"] -->|"展开"| B["完整的提示词模板<br/>+ 参数值<br/>+ 工作流步骤<br/>+ 规范引用"]
    
    C["用户手动输入:<br/>帮我创建一个 POST API...<br/>路径是 /orders...<br/>记得遵循规范...<br/>要写测试..."] -->|"对比"| D["信息可能遗漏<br/>表述可能不一致<br/>消耗更多 token"]
    
    style A fill:#c8e6c9
    style C fill:#ffcdd2

Skills：可复用的知识包

Skills 是 Commands 的升级版。如果说 Command 是一个"提示词模板"，那么 Skill 就是一个"知识包"——它不仅包含指令，还包含领域知识、参考文档、工作流定义。

Skill 的完整结构

1
2
3
4
5
6
7
8
9
.claude/skills/
└── api-design/
    ├── skill.md              # Skill 定义（入口）
    └── references/
        ├── rest-conventions.md    # REST API 设计规范
        ├── error-codes.md         # 错误码定义
        └── examples/
            ├── user-api.md        # 用户 API 示例
            └── order-api.md       # 订单 API 示例

Skill 定义文件（skill.md）的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
name: api-design
description: REST API 设计专家，遵循团队的 API 设计规范
---

作为 API 设计专家，在设计和实现 REST API 时：

1. 遵循 `references/rest-conventions.md` 中的命名和路径规范
2. 错误响应使用 `references/error-codes.md` 中定义的错误码
3. 参考 `references/examples/` 中的示例了解团队风格

设计原则：
- URL 使用名词复数形式（/users, /orders）
- 使用标准 HTTP 状态码
- 响应体统一使用 Result<T> 包装
- 分页使用 cursor-based pagination

Skill 的加载机制

当 Agent 判断当前任务需要某个 Skill 的知识时，会自动加载该 Skill 的全部内容（包括 references/ 目录下的文件）到上下文中。这个过程是按需的——只有在需要时才加载，避免了不必要的上下文消耗。

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant S as Skill 工具
    
    U->>A: "设计一个订单退款 API"
    
    Note over A: 判断需要 API 设计知识
    A->>S: 搜索匹配的 Skill
    S-->>A: 找到 api-design Skill
    
    Note over A: 加载 Skill 内容到上下文
    A->>S: 读取 skill.md + references/*
    S-->>A: API 规范 + 错误码 + 示例
    
    Note over A: 基于 Skill 知识执行任务
    A->>U: 按照团队规范设计的退款 API

Skills 与 CLAUDE.md 的分工

flowchart TB
    subgraph CLAUDE.md
        A1["项目级通用信息"]
        A2["技术栈声明"]
        A3["全局行为约束"]
    end
    
    subgraph Skills
        B1["领域专业知识"]
        B2["详细的参考文档"]
        B3["具体的工作流程"]
    end
    
    C["上下文空间"] 
    
    CLAUDE.md -->|"始终占用"| C
    Skills -->|"按需占用"| C
    
    D["设计原则:<br/>CLAUDE.md 放'必须始终知道的'<br/>Skills 放'需要时才加载的'"]
    
    style D fill:#e8f5e9

Sub Agents：独立执行的专业角色

Sub Agents 是四层体系中最强大的机制。它解决的核心问题是：上下文隔离。

回到第一性原理：上下文窗口是有限的，长对话会导致注意力退化和上下文污染。Sub Agent 通过创建独立的上下文窗口，从根本上解决了这个问题。

flowchart TB
    subgraph 主对话["主 Agent 上下文窗口"]
        M1["用户任务"]
        M2["项目上下文"]
        M3["任务分解决策"]
    end
    
    subgraph SA1["Sub Agent A 上下文窗口"]
        A1["独立的上下文"]
        A2["专属工具权限"]
        A3["子任务 A 的全部工作"]
    end
    
    subgraph SA2["Sub Agent B 上下文窗口"]
        B1["独立的上下文"]
        B2["专属工具权限"]
        B3["子任务 B 的全部工作"]
    end
    
    主对话 -->|"委派子任务 A"| SA1
    主对话 -->|"委派子任务 B"| SA2
    SA1 -->|"只返回摘要结果"| 主对话
    SA2 -->|"只返回摘要结果"| 主对话
    
    style 主对话 fill:#e8eaf6
    style SA1 fill:#e3f2fd
    style SA2 fill:#e8f5e9

Sub Agent 的定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
---
name: code-reviewer
description: 代码审查专家，专注于代码质量和安全性审查
tools: Read, Grep, Glob
---

作为代码审查专家，执行以下审查流程：

1. 读取待审查的代码文件
2. 检查代码质量：命名规范、函数长度、复杂度
3. 检查安全性：SQL 注入、XSS、敏感信息泄露
4. 检查性能：N+1 查询、不必要的循环、内存泄漏风险
5. 输出结构化的审查报告

审查标准：
- 函数不超过 30 行
- 圈复杂度不超过 10
- 所有外部输入必须验证
- 数据库查询必须使用参数化

注意 tools: Read, Grep, Glob——这个 Sub Agent 只有读取权限，没有编辑权限。工具列表就是权限边界。

Sub Agent 的高级特性

1. 持久化记忆

Sub Agent 可以拥有跨对话持久化的记忆目录：

1
2
3
4
5
---
name: code-reviewer
description: 代码审查专家
memory: project
---

memory 字段支持三种作用域：

作用域 存储位置 适用场景
user ~/.claude/agent-memory/<name>/ 跨项目通用的经验积累
project .claude/agent-memory/<name>/ 项目特定的知识，可提交 Git
local .claude/agent-memory-local/<name>/ 项目特定但不提交 Git

启用记忆后，Sub Agent 的系统提示词中会自动注入记忆目录中 MEMORY.md 的前 200 行内容。这意味着 Agent 会随着使用越来越"聪明"——它在审查代码时发现的模式、踩过的坑，都会被记录下来，下次自动参考。

2. Hook 机制——工具调用的拦截与增强

Sub Agent 支持在工具调用前后执行自定义脚本：

1
2
3
4
5
6
7
8
9
10
11
---
name: db-reader
description: 只读数据库查询专家
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

对应的验证脚本会在每次 Bash 调用前拦截并验证命令内容，只允许 SELECT 查询通过。这实现了比简单的工具白名单更细粒度的权限控制。

3. 预加载 Skills

Sub Agent 可以声明需要预加载的 Skills：

1
2
3
4
5
6
7
---
name: api-developer
description: API 开发专家
skills:
  - api-conventions
  - error-handling-patterns
---

skills 字段列出的 Skill 的全部内容会被注入到 Sub Agent 的上下文中，使得 Sub Agent 在启动时就具备了特定领域的专业知识。

四种机制的 MECE 对比

flowchart TB
    subgraph 何时加载
        direction LR
        A1["始终在场"] ---|"←→"| A2["按需加载"]
        A1 --- A1a["CLAUDE.md"]
        A2 --- A2a["Commands / Skills / Sub Agents"]
    end
    
    subgraph 在哪执行
        direction LR
        B1["主对话上下文"] ---|"←→"| B2["独立上下文"]
        B1 --- B1a["CLAUDE.md / Commands / Skills"]
        B2 --- B2a["Sub Agents"]
    end
    
    subgraph 信息密度
        direction LR
        C1["低密度<br/>CLAUDE.md"] --- C2["中密度<br/>Commands"] --- C3["高密度<br/>Skills"] --- C4["最高密度<br/>Sub Agents"]
    end
维度 CLAUDE.md Commands Skills Sub Agents
加载时机 对话开始自动加载 用户 / 触发 Agent 自动匹配 Agent 委派任务
执行上下文 主对话 主对话 主对话 独立上下文窗口
工具权限 继承主对话 继承主对话 继承主对话 独立工具白名单
持久记忆 不支持 不支持 不支持 支持
信息密度 声明式偏好 提示词模板 知识+流程 角色+工具+流程+权限+记忆
适用场景 项目级通用约束 重复性任务标准化 领域专业知识 自包含的独立任务

判断标准：如果任务需要频繁的用户交互和迭代，用 Skill；如果任务是自包含的、可以独立完成并返回摘要的，用 Sub Agent。

四种机制的协同工作

以一个完整的场景说明四种机制如何协同：在电商项目中为订单模块添加退款 API。

sequenceDiagram
    participant U as 用户
    participant M as 主 Agent
    participant C as CLAUDE.md
    participant CMD as Command
    participant SK as Skill
    participant SA1 as Sub Agent: reviewer
    participant SA2 as Sub Agent: developer
    
    Note over M,C: 第一层: CLAUDE.md 自动加载
    C-->>M: 项目技术栈、规范、架构信息
    
    Note over U,CMD: 第二层: 用户触发 Command
    U->>M: /create-api POST /api/v1/orders/{id}/refund
    CMD-->>M: 展开为完整的任务指令
    
    Note over M,SK: 第三层: Skill 自动匹配
    M->>SK: 加载 api-design Skill
    SK-->>M: REST 规范 + 错误码 + 示例
    
    Note over M,SA2: 第四层: Sub Agent 并行执行
    M->>SA1: 审查现有退款相关代码(只读权限)
    M->>SA2: 实现退款 API(读写权限, 预加载 api-conventions Skill)
    SA1-->>M: 审查报告摘要
    SA2-->>M: 实现完成摘要
    
    M->>U: 综合报告 + 最终结果

CLAUDE.md 提供"我是谁、我在哪"的环境上下文，Commands 提供"做这件事"的触发入口，Skills 提供"怎么做好这件事"的专业知识，Sub Agents 提供"让专人去做"的执行隔离。

更广泛的视角：Rules 和 Specs

在不同的 AI 编码平台中，还存在 Rules 和 Specs 这样的概念。它们本质上是对上述体系的变体或补充。

Rules：CLAUDE.md 的跨平台等价物

平台 配置文件
Claude Code CLAUDE.md
Cursor .cursorrules
Windsurf .windsurfrules
GitHub Copilot .github/copilot-instructions.md
Aone Copilot Skills (SKILL.md)

不同的名字，相同的本质：告诉 Agent 所处的环境和应该遵循的规范。如果项目需要支持多个 AI 编码工具，可以维护一份核心规范文档，然后通过符号链接或脚本同步到各平台的配置文件中。

Specs：面向任务的需求文档

Specs 与上述所有机制都不同。它们不是 Agent 的"行为定义"，而是 Agent 工作时需要参考的"需求文档"——API 设计规格、数据库 schema 说明、产品需求文档等。

flowchart LR
    subgraph Agent行为定义
        A[CLAUDE.md / Rules]
        B[Commands]
        C[Skills]
        D[Sub Agents]
    end
    
    subgraph 任务需求
        E[Specs / 需求文档]
    end
    
    Agent行为定义 -->|"定义 Agent 怎么工作"| F[Agent]
    任务需求 -->|"定义 Agent 要完成什么"| F

模式提炼：分层配置

模式公式：Agent 配置 = 环境上下文(始终) + 触发入口(按需) + 专业知识(按需) + 执行隔离(按需)

迁移表：

场景 环境层 触发层 知识层 执行层
个人项目 简单的 CLAUDE.md 不需要 不需要 不需要
团队项目 详细的 CLAUDE.md 常用 Commands 领域 Skills 审查 Sub Agent
大型企业项目 分层 CLAUDE.md 标准化 Commands 多领域 Skills 多角色 Sub Agents
开源项目 贡献者指南 PR 模板 Command 代码风格 Skill CI 审查 Sub Agent

核心洞察：当听到"Agent 不遵循项目规范"时，问题往往不在 Agent 的能力，而在于规范没有被正确地放入 Agent 的上下文中。分层配置体系的核心价值是：确保正确的信息在正确的时机出现在 Agent 的上下文中。

实操方法论：从原理到实践

理解了第一性原理和配置体系之后，接下来是最关键的部分：如何在日常工作中高效地使用 Agentic Coding。

flowchart TB
    subgraph 实操方法论
        A[对话管理] --> B[知识沉淀]
        B --> C[工程约束]
        C --> D[AI 友好设计]
        D --> E[刻意练习]
    end
    
    F["第一性原理"] -->|"指导"| 实操方法论
    G["配置体系"] -->|"支撑"| 实操方法论
    
    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0
    style D fill:#fce4ec
    style E fill:#f3e5f5

对话管理：短对话优于长对话

这是从上下文窗口约束直接推导出的最重要的实操原则。

为什么长对话会失败

flowchart TB
    A["开始: 新对话<br/>上下文清晰"] --> B["第5轮: 上下文开始积累<br/>仍然高效"]
    B --> C["第15轮: 上下文大量积累<br/>注意力开始分散"]
    C --> D["第25轮: Lost in the Middle<br/>Agent 开始遗忘早期信息"]
    D --> E["第35轮: 上下文污染严重<br/>Agent 可能前后矛盾"]
    E --> F["第45轮: 接近上下文上限<br/>性能急剧下降"]
    
    style A fill:#c8e6c9
    style B fill:#dcedc8
    style C fill:#fff9c4
    style D fill:#ffe0b2
    style E fill:#ffccbc
    style F fill:#ffcdd2

Agent 的表现与对话长度之间存在一个"中间区域"的性能退化：

  • 简单任务（1-5 轮）：表现优异，上下文清晰
  • 中等任务（5-15 轮）：表现良好，但需要注意上下文管理
  • 复杂任务（15+ 轮）：表现开始退化，需要主动干预
  • 超长对话（30+ 轮）：高风险区域，建议拆分为多次对话

任务分解策略

面对复杂任务，核心策略是分解为多个短对话，每个对话完成一个独立的子任务：

flowchart TB
    A["复杂任务:<br/>重构订单模块"] --> B["拆分"]
    
    B --> C["对话1: 分析现有代码结构<br/>输出: 架构分析文档"]
    B --> D["对话2: 设计新的领域模型<br/>输入: 架构分析文档<br/>输出: 领域模型定义"]
    B --> E["对话3: 实现核心实体<br/>输入: 领域模型定义<br/>输出: 实体代码"]
    B --> F["对话4: 迁移服务层<br/>输入: 实体代码<br/>输出: 服务层代码"]
    B --> G["对话5: 编写测试<br/>输入: 服务层代码<br/>输出: 测试代码"]
    
    C --> D
    D --> E
    E --> F
    F --> G
    
    style C fill:#e3f2fd
    style D fill:#e3f2fd
    style E fill:#e3f2fd
    style F fill:#e3f2fd
    style G fill:#e3f2fd

每个对话之间的"接力"通过以下方式实现：

  1. 文件系统：前一个对话的输出（代码文件）自然成为下一个对话的输入
  2. CLAUDE.md：在 CLAUDE.md 中记录当前工作进度和决策
  3. Memory：利用 Sub Agent 的持久记忆跨对话传递经验

何时开始新对话的判断标准

flowchart TB
    A{Agent 是否开始<br/>重复之前的搜索?} -->|是| NEW[开始新对话]
    A -->|否| B{Agent 的回复是否<br/>与之前矛盾?}
    B -->|是| NEW
    B -->|否| C{当前任务是否<br/>已经完成一个里程碑?}
    C -->|是| NEW
    C -->|否| D{对话是否已经<br/>超过 15 轮?}
    D -->|是| NEW
    D -->|否| E[继续当前对话]
    
    style NEW fill:#e3f2fd
    style E fill:#c8e6c9

知识沉淀：从会话记忆到持久记忆

Agentic Coding 中最容易被忽视的一个维度是知识的沉淀与复用。每次与 Agent 的对话都会产生有价值的知识——项目的隐性约定、踩过的坑、有效的解决方案——但如果这些知识只存在于对话历史中，它们会随着对话的结束而消失。

知识沉淀的三个层次

flowchart TB
    subgraph 层次1["第一层: 会话内记忆"]
        A1["上下文窗口中的信息"]
        A2["生命周期: 单次对话"]
        A3["容量: 有限"]
    end
    
    subgraph 层次2["第二层: 项目级记忆"]
        B1["CLAUDE.md / Rules"]
        B2["生命周期: 项目存续期"]
        B3["容量: 中等(需精炼)"]
    end
    
    subgraph 层次3["第三层: 持久化记忆"]
        C1["Sub Agent Memory"]
        C2["生命周期: 跨项目/跨对话"]
        C3["容量: 较大(文件系统)"]
    end
    
    层次1 -->|"手动提炼"| 层次2
    层次2 -->|"自动积累"| 层次3
    
    style 层次1 fill:#ffecb3
    style 层次2 fill:#c8e6c9
    style 层次3 fill:#b3e5fc

经验复利效应

知识沉淀的真正价值在于复利效应。每一次修复、每一次审查、每一次教训都在为未来投资：

flowchart LR
    A["第1次: 手动告诉 Agent<br/>'这个项目用 Result 包装返回值'"] --> B["沉淀到 CLAUDE.md"]
    B --> C["第2次: Agent 自动遵循<br/>无需再次提醒"]
    C --> D["第3次: Agent 在审查中<br/>主动指出不符合规范的代码"]
    D --> E["第N次: Agent 基于积累的经验<br/>主动提出改进建议"]
    
    style A fill:#ffecb3
    style B fill:#dcedc8
    style C fill:#c8e6c9
    style D fill:#a5d6a7
    style E fill:#81c784

具体的沉淀实践：

1. 及时更新 CLAUDE.md

每当发现 Agent 犯了一个"本不该犯"的错误时，问自己：这个信息是否应该写入 CLAUDE.md？

1
2
3
4
5
6
# CLAUDE.md 中的经验沉淀示例

# 已知陷阱
- 订单状态机不允许从 CANCELLED 回到 PAID，见 OrderStateMachine.java
- Redis 缓存的 key 前缀必须包含环境标识，如 prod:order:123
- 不要使用 @Transactional(readOnly=true) 在写操作方法上

2. 利用 Memory 机制

对于 Sub Agent，启用 memory 字段后，Agent 会自动将工作中发现的模式和教训记录到 MEMORY.md 中：

1
2
3
4
5
6
7
8
9
# MEMORY.md (由 code-reviewer Sub Agent 自动维护)

## 发现的模式
- 该项目倾向于使用 Builder 模式构造复杂对象
- 异常处理统一在 GlobalExceptionHandler 中，不要在 Service 层 catch

## 踩过的坑
- PR #234: 变量命名不一致导致审查遗漏
- PR #241: 缺少空指针检查导致生产事故

3. 将经验编码为 Skills

当某类问题反复出现时，将解决方案编码为 Skill：

flowchart TB
    A["问题反复出现:<br/>'如何正确处理分布式事务?'"] --> B["提炼为 Skill"]
    B --> C["distributed-transaction Skill"]
    C --> D["包含:<br/>- 事务模式选择决策树<br/>- Saga 模式实现模板<br/>- 补偿逻辑示例<br/>- 常见陷阱清单"]
    D --> E["下次遇到类似问题<br/>Agent 自动加载 Skill"]

工程约束：用代码而非文字约束 Agent

这是一个反直觉但极其重要的原则：工程约束比 Prompt 指令更可靠。

Agent 有时会试图走捷径，绕过 Prompt 中设定的规则。与其在 Prompt 中反复强调"不要跳过测试"，不如用工程手段来强制执行。

借助 Linters、Formatters 和 Git Hooks

flowchart TB
    A["Agent 尝试提交代码"] --> B["pre-commit hook 拦截"]
    B --> C{类型检查通过?}
    C -->|否| D["拒绝提交<br/>Agent 必须修复类型错误"]
    C -->|是| E{Lint 检查通过?}
    E -->|否| F["拒绝提交<br/>Agent 必须修复 Lint 错误"]
    E -->|是| G{测试通过?}
    G -->|否| H["拒绝提交<br/>Agent 必须修复测试"]
    G -->|是| I["允许提交"]
    
    style D fill:#ffcdd2
    style F fill:#ffcdd2
    style H fill:#ffcdd2
    style I fill:#c8e6c9

一个典型的 pre-commit hook：

1
2
3
4
5
6
7
8
9
10
11
12
13
#!/bin/bash
# .git/hooks/pre-commit

echo "Running type check..."
npm run typecheck || exit 1

echo "Running linter..."
npm run lint || exit 1

echo "Running tests..."
npm test || exit 1

echo "All checks passed!"

拦截 Agent 的"偷懒"行为

Agent 有时会发现测试一直失败后，尝试使用 --no-verify 绕过 pre-commit hook。解决方案是用一个 git 命令 wrapper 脚本拦截这种行为：

1
2
3
4
5
6
7
8
9
10
11
$ git commit --no-verify
------------------------------------------------------------------
ERROR: Commit Rejected.
------------------------------------------------------------------

GUIDANCE FOR THE AI AGENT:
You have attempted to bypass the required pre-commit verification.
All code must pass quality checks before it can be committed.

DO NOT BYPASS THE CHECKS. YOU MUST FIX THE UNDERLYING ERRORS.
------------------------------------------------------------------

这个技巧的本质是：把对 Agent 的指导嵌入到工具的输出中。Agent 会读取命令执行的结果，所以错误信息本身就是最好的 Prompt 注入点。

flowchart LR
    A["Prompt 指令:<br/>'不要跳过测试'"] -->|"Agent 可能忽略"| B["效果不稳定"]
    C["工程约束:<br/>pre-commit hook"] -->|"Agent 无法绕过"| D["效果稳定"]
    E["工具输出中的指导:<br/>错误信息包含修复建议"] -->|"Agent 必然读取"| F["效果最佳"]
    
    style B fill:#ffcdd2
    style D fill:#c8e6c9
    style F fill:#a5d6a7

模式提炼：工程约束优于提示

模式公式：可靠性 = 工程强制(hook/lint/CI) > 工具输出引导(错误信息) > Prompt 指令(文字约束)

迁移表：

约束需求 Prompt 方式 工程方式 推荐
代码风格 “请遵循 ESLint 规范” .eslintrc + pre-commit hook 工程
测试覆盖 “请确保测试通过” CI pipeline + 覆盖率门禁 工程
提交规范 “请写好 commit message” commitlint + husky 工程
安全检查 “请注意 SQL 注入” SAST 工具 + pre-commit 工程
架构约束 “请遵循分层架构” ArchUnit 测试 工程

核心洞察：当听到"Agent 总是不遵守规范"时，首先应该检查的不是 Prompt 是否写得够清楚，而是是否有工程手段来强制执行。每当 Agent 发明新的"偷懒"方式，就需要堵上这个漏洞——但总体来说，工程约束比 Prompt 指令更可靠。

AI 友好设计：对人难的事，对 AI 也难

有一个简单但常被忽视的事实：如果一个任务对人类开发者来说很难，那么它对当前的 AI 来说大概率也很难。 这个推论的深远意义在于：所有能提升人类开发者体验的工作，对 AI 同样有价值。

flowchart TB
    A["对人难的事<br/>对 AI 也难"] --> B["文档缺失"]
    A --> C["架构混乱"]
    A --> D["测试缓慢"]
    A --> E["错误信息模糊"]
    
    B --> B1["人: 花大量时间读源码猜意图<br/>AI: 反复搜索, 消耗上下文, 可能理解错误"]
    C --> C1["人: 不知道该改哪里<br/>AI: 改错文件, 遗漏同步修改"]
    D --> D1["人: 倾向于跳过测试<br/>AI: 等待超时, 浪费上下文"]
    E --> E1["人: 需要额外调试<br/>AI: 盲目搜索, 效率低下"]
    
    style A fill:#fff3e0

双重投资回报

当投资于更好的文档、更清晰的架构、更快的测试时，获得的回报是双倍的：

flowchart LR
    subgraph 投资
        A["更好的文档"]
        B["更清晰的架构"]
        C["更快的测试"]
        D["更好的错误信息"]
    end
    
    subgraph 回报
        E["人类开发者更高效"]
        F["AI 助手更高效"]
    end
    
    A --> E
    A --> F
    B --> E
    B --> F
    C --> E
    C --> F
    D --> E
    D --> F
    
    style E fill:#c8e6c9
    style F fill:#b3e5fc

更好的文档：好的文档不仅帮助新人上手，也帮助 AI 快速建立正确的心智模型。架构决策记录（ADR）解释"为什么这样设计"，避免 AI 做出违背设计意图的修改。API 使用示例比纯粹的类型定义更有效。已知陷阱和常见错误直接告诉 AI 什么不该做。

更清晰的代码结构：清晰的命名（processUserData() 而非 doStuff()）、单一职责（一个做一件事的函数）、显式依赖（依赖注入而非全局变量）——这些对 AI 的帮助和对人类一样大。

更快的反馈循环：这可能是最容易被低估的一点。Agent Loop 的每一轮都需要等待工具执行完成。秒级的单元测试让 Agent 可以频繁验证、快速迭代；快速的增量构建让改动能立即得到反馈。

专门为 AI 设计的优化

反过来的推论并不总是成立：对人来说简单的事，对 AI 未必简单。有时候需要专门为 AI 设计工具和接口。

1. LLM 需要专门的信息架构

LLM 是在现有的 CLI 工具上训练的，但这些工具是为人类设计的。需要为 Agent 增强这些工具，提供对 LLM 更有用的上下文：

1
2
3
4
5
6
# 在 .zshrc 中添加，帮助 Agent 快速定位
command_not_found_handler() {
    echo "zsh: command not found: '$1'"
    echo "zsh: current directory is $PWD"
    return 127
}

很多命令行工具都提供了 --json 或 --porcelain 选项，在给 Agent 使用的工具中优先使用这些格式——人类喜欢格式化的输出，但 AI 更擅长解析结构化数据。

2. API 设计：在信息量和上下文消耗之间取得平衡

为 Agent 设计工具接口时，需要在两个目标之间取得平衡：提供足够的信息（减少工具调用次数）和避免填满上下文（不要返回过多无关信息）。

一个好的实践是：提供便捷函数和底层函数两套 API，并通过工具描述引导 Agent 优先使用便捷函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
def get_global_variable_at(address: str) -> dict:
    """
    获取指定地址的全局变量值。自动识别类型并返回最佳字符串表示。
    这是读取全局变量的首选方法。
    """
    # 智能的、高层的实现
    ...

def data_read_byte(address: str) -> int:
    """
    读取指定地址的 1 字节值。
    仅在 get_global_variable_at 失败时使用此函数。
    """
    # 底层的、更通用的实现
    ...

3. 显式优于隐式

1
2
3
4
5
6
7
8
9
10
11
# 有状态的 API: AI 需要跟踪隐含状态变化
client.connect()
client.authenticate(user, password)
client.query("SELECT * FROM users")

# 无状态的 API: AI 更容易正确使用
result = db.query(
    connection={"host": host, "port": port},
    auth={"user": user, "password": password},
    sql="SELECT * FROM users"
)

4. 结构化的错误信息

1
2
3
4
5
6
# 对人足够，对 AI 可能困惑
Error: Something went wrong. Please try again later.

# 对 AI 更友好
Error [AUTH_TOKEN_EXPIRED]: Token expired at 2024-01-15T10:30:00Z.
Call refreshToken() to obtain a new token. See: docs/auth.md#token-refresh

顺应 Agent 的统计直觉

一个更微妙的发现：AI 认为合理的代码结构和命名，可能和人类的直觉不一致。

Agent 的命名"直觉"来自训练数据的统计概率。例如，present() 是 Flutter 等框架中双缓冲交换的常见命名，对于 Agent 来说是"最可能"的名字。当开发者用自己的命名 swapScreens() 覆盖它时，实际上是在对抗 Agent 的统计直觉——Agent 不能再从权重中找到答案，它必须记住人类的特殊习惯。

flowchart TB
    A["Agent 的统计直觉:<br/>present() 是双缓冲交换的常见命名"] --> B{开发者干预?}
    B -->|"改为 swapScreens()"| C["Agent 后续反复寻找 present()<br/>找不到后才找到 swapScreens()<br/>浪费 token 和时间"]
    B -->|"保留 present()"| D["Agent 后续直接找到<br/>高效继续工作"]
    
    style C fill:#ffcdd2
    style D fill:#c8e6c9

实用的权衡策略：

  1. 不要过度干预：如果频繁地因为"觉得这个名字更好"而覆盖 Agent 的决策，可能反而在降低效率
  2. 注意"找不到"的信号：如果 Agent 反复在某个地方"找不到"东西，考虑是否是命名和它的预期不一致
  3. 拥抱常见模式：使用广泛使用的设计模式和命名约定，AI 的训练数据中更可能包含这些
  4. 模块级的风格隔离：在 Agent 主导开发的模块中，可以考虑让 Agent 保持它自己的风格

模式提炼：统计直觉对齐

模式公式：Agent 效率 ∝ 代码库命名与训练数据统计分布的对齐程度

迁移表：

场景 人类偏好 Agent 统计偏好 推荐策略
函数命名 团队自定义术语 业界通用术语 优先使用通用术语
设计模式 自创模式 标准 GoF 模式 优先使用标准模式
文件布局 团队约定 框架默认布局 在 CLAUDE.md 中明确说明
错误处理 自定义异常体系 标准异常体系 在 Skills 中提供映射

核心洞察：当听到"Agent 总是用错误的方式做事"时，考虑是否是项目的约定与 Agent 的统计直觉不一致。解决方案不是反复纠正 Agent，而是要么对齐约定，要么在 CLAUDE.md 中显式说明。

刻意练习：像学乐器一样学习 AI

为什么有些人说"AI 对我不起作用"，而另一些人却能用 AI 完成大量的工作？

这个问题需要区分来看。如果只在公司的大型私有代码库中使用过 AI，体验可能确实不好——那些代码库可能有古老的架构和专有模式，AI 的训练数据中根本没有这些。但关键问题是：有没有在个人项目中尝试过 AI？有没有进行刻意的、有意识的练习？

flowchart TB
    A["刻意练习的五个维度"] --> B["创造干净的实验环境"]
    A --> C["从失败中提取教训"]
    A --> D["观察和模仿高手"]
    A --> E["建立肌肉记忆"]
    A --> F["持续投入时间"]
    
    B --> B1["启动个人项目<br/>没有历史包袱"]
    C --> C1["Prompt 是否清晰?<br/>上下文是否充分?<br/>任务是否过大?"]
    D --> D1["关注公开分享工作流的开发者<br/>复制他们的技巧"]
    E --> E1["何时开始新对话?<br/>如何组织复杂 Prompt?<br/>哪种工具组合最有效?"]
    F --> F1["每天 30 分钟<br/>坚持几个月<br/>远超每周一次几小时"]

AI 工具就像一件乐器。那些从 AI 中获益最多的人，都投入了刻意练习。他们不会因为一次失败就下结论说"它不行"，然后假设这将是常态体验。他们会实验、会失败、会从失败中学习。

从失败中提取教训的检查清单：

  • Prompt 是否足够清晰？
  • 是否提供了足够的上下文？
  • 是否在一个对话里塞了太多任务？
  • 这个错误是否揭示了 AI 的某个系统性弱点？
  • 是否应该将这个教训沉淀到 CLAUDE.md 或 Skills 中？

每次失败都是一次学习机会。把它记录下来，下次避免同样的陷阱。

本质洞察：从"编写程序"到"编写职位描述"

回到最初的问题：为什么一份 Markdown 就能定义一个智能体？

因为 LLM 改变了"智能"的供给方式。在传统范式下，智能需要被编程——用代码一行一行地告诉计算机如何思考。在 LLM 范式下，智能是预训练好的——模型已经具备了通用的推理、规划和执行能力，只需要用自然语言告诉它"你是谁、该做什么、不该做什么"。

flowchart LR
    subgraph 传统范式
        A1["开发者<br/>(编程能力)"] --> A2["编写代码<br/>(编译部署)"] --> A3["Agent<br/>(运行)"]
    end
    
    subgraph LLM范式
        B1["任何人<br/>(表达能力)"] --> B2["编写文档<br/>(.md 文件)"] --> B3["Agent<br/>(即时生效)"]
    end
    
    style A1 fill:#e8eaf6
    style B1 fill:#e8f5e9
维度 传统范式 LLM 范式
创建者 程序员 任何能清晰表达的人
载体 代码 文档
生效方式 编译部署 保存即生效
迭代速度 天级别 秒级别
门槛 会编程 + 会部署 会写文档

这就是为什么定义一个 Agent 的过程，从"编写程序"变成了"编写职位描述"。而 Markdown，恰好是编写职位描述的最佳格式。

但这并不意味着"随便写写就行"。正如一份好的职位描述需要精确地定义岗位职责、能力要求、工作流程和权限边界，一份好的 Agent 定义也需要精心设计：

  • 关注点分离：CLAUDE.md 管环境、Commands 管触发、Skills 管知识、Sub Agents 管执行
  • 最小权限原则：Sub Agent 的 tools 白名单和 Hook 机制确保每个 Agent 只能做它该做的事
  • 上下文隔离：Sub Agent 的独立上下文窗口防止信息泄漏和上下文污染
  • 渐进式复杂度：从简单的 CLAUDE.md 到复杂的带 Hook 的 Sub Agent，根据需要选择合适的抽象层级

模式速查表

听到的需求关键词 对应模式 方案 口诀
“AI 给了错误答案” 概率性推理 检查上下文是否充分，补充 CLAUDE.md 垃圾进垃圾出
“Agent 做了很多无用功” 感知-行动循环 用 Commands/Skills 减少摸索轮次 预定义工作流
“长对话中 Agent 越来越差” 上下文即工作记忆 拆分为多个短对话，使用 Sub Agent 短对话优于长对话
“Agent 不遵循项目规范” 分层配置 将规范写入 CLAUDE.md 或 Skills 信息在正确时机出现
“每次都要重复告诉 Agent” 知识外化 沉淀到 CLAUDE.md / Memory / Skills 写一次用无数次
“改了文档/架构后 Agent 更好用了” 双重投资回报 持续投资开发者体验 帮人也帮 AI
“Agent 总是跳过测试” 工程约束优于提示 用 Git Hooks / CI 强制执行 代码约束不可绕过
“Agent 总是用错误的命名” 统计直觉对齐 使用通用命名，或在 CLAUDE.md 中说明 顺应而非对抗 
flowchart TB
    subgraph 模式组合示例
        A["大型项目重构"] --> B["分层配置<br/>+ 上下文隔离<br/>+ 知识外化"]
        C["日常功能开发"] --> D["感知-行动循环<br/>+ 分层配置<br/>+ 双重投资回报"]
        E["代码质量治理"] --> F["工程约束优于提示<br/>+ 统计直觉对齐<br/>+ 知识外化"]
    end

总结

AI 正在以惊人的速度发展。本文讨论的许多"限制"——上下文窗口的约束、会话间的失忆、中间区域的性能退化——很可能在未来几年内被大幅改善。但这并不意味着应该等待那一天的到来。

恰恰相反，正是这个充满限制的阶段，给了工程师极大的探索和成长空间。那些现在就开始深入理解 LLM 工作原理、积极实践最佳方法、在限制中寻找创造性解决方案的人，将在 AI 能力进一步释放时获得最大的杠杆效应。

从第一性原理理解 LLM 的本质，理解它们如何"思考"、如何受到上下文的限制、如何在 Agent Loop 中发挥作用——这些知识不会随着具体工具的迭代而过时。无论使用的是哪个 Coding Agent，无论模型如何更新换代，这些基础原理都将帮助更好地与 AI 协作。

而 Markdown 配置体系的分层设计——CLAUDE.md 管环境、Commands 管触发、Skills 管知识、Sub Agents 管执行——这种关注点分离的思想，同样具有跨平台、跨时代的迁移价值。

这个范式转换带来的深远影响是：Agent 的创建门槛从"会编程"降低到了"会写文档"。 任何能清晰描述一个工作流程的人——产品经理、项目经理、领域专家——都有能力定义一个专业的 AI 智能体。而对于程序员来说，理解这套 Markdown 配置体系的分层设计，就像理解 DDD 的战略设计一样重要——它决定了能否有效地组织和管理一个由多个 AI Agent 协作的复杂工作流。

去实验，去失败，去学习。像学习乐器一样学习 AI。这个过程本身，就是价值所在。