徐术挺-漫思录

BRIEF

14分钟阅读

BRIEF — 《Agent 开发·从心智模型到造出 Claude Code》

本文件是所有写作代理的”施工图纸”。开始写任何章节前，必须先读完整本 BRIEF，并参考样章 01-开篇.md 与 02-Part1-心智模型.md 的语气与节奏。

0. 项目目标

做一套系统化、硬核、对话讨论式的 Agent 开发教程，目标读者（一个 5 年经验的 Go 后端工程师）学完能从”听说过 ReAct、但落地不会”走到”理解 Claude Code / Codex 为什么丝滑、并且能自己设计出一个同等架构层次的 agent 系统”。

本教程不交付可运行工程，定位是：

  • 理论：把 Agent 背后的心智模型、机制、工程权衡讲透；
  • 架构剖析：拆解 Claude Code / Codex 等真实工具的架构与系统设计取舍；
  • 真实经验：穿插一线踩坑、反模式、协作成本。

代码只作为示意片段（Python 为主），用来锚定理解，不是拿来跑的。

1. 读者画像（务必时刻对准）

  • 5 年 Go 后端经验，会写 CRUD、中间件，协议层自认”会用不精通”。
  • 技术底子好，讨厌科普层、水字数、背诵式罗列。要的是系统认知、设计意图、为什么这样而不是那样。
  • 听得懂代码，但 Agent/LLM 领域是新手——所以术语第一次出现必须给直觉解释和生活化类比，不要假设他懂 Prompt、Token、Embedding、RAG 这些词就能跳过。
  • 他想要”能自己造工具”的 level，不是”调个 SDK”的 level。

2. 写作风格（硬性要求）

  • 对话讨论式：导师叫「墨叔」（住在网络协议栈里的老兵，循循善诱，多反问，不喂结论，用”你觉得呢""你先猜一下为什么”这类话术），读者叫「老哥」。通篇是墨叔 vs 老哥的对谈推进，不是单向灌输。
  • 多反问、层层剥：每个核心概念先抛问题，引他思考，再给解释。该铺陈时不急着掀底牌。
  • 生活化类比要狠：邮局、餐厅、快递柜、装修队、合同、乐队指挥、司机、仓库管理员……能把抽象机制讲清楚的比喻就用，但类比之后必须落回技术本质，别停在比喻。
  • 代码少而准：Python 示意片段，重点在”这段体现了什么机制”，而非完整工程。片段要能跑通逻辑（伪代码级别即可），别写会报错的代码。
  • 不堆术语、不搬文档：禁止把 OpenAI/Anthropic 的官方文档复述一遍。讲设计意图。
  • 不用 emoji。标点 ASCII 或中文全角即可。

3. 固定章节结构（每个 ## 子章节必须包含以下模块，顺序可微调）

  1. 钩子/反问：用一个问题或场景把人拉进来（“老哥，你有没有想过……”）。
  2. 核心论述：把机制讲清楚，先直觉后原理，配生活化类比。
  3. 与读者的连接：点明”作为一个 Go 后端，你其实已经懂一半了，区别在……”式的连接，降低陌生感。
  4. 真实经验/案例：一段踩坑或真实工具的做法。
  5. 【思考题】：1-3 道，必须能引发进一步思考，不是送分题。
  6. 【参考答案】：独立成行，给老哥当学习材料看（他明确要答案），答案要有深度、有延伸，不是一句话。
  7. 小结：3-5 句话收束。

4. 字数要求

  • 每个 ## 子章节 3000–6000 中文字（约 30 分钟阅读量，含代码注释不计入纯中文但算篇幅）。
  • 每个 Part（文件）含 4–5 个子章节，单文件 12000–18000 字。
  • 全套总目标 ≥ 120000 中文字。
  • 字数校验用 Python（本环境 wc 不可用）： 
    import re
t = open(r'C:\...\xx.md', encoding='utf-8').read()
print(len(re.findall(r'[一-鿿]', t)))
    每个代理写完后必须自检并报告中文字数；不足要就地扩写，不要靠凑字数，要加深度。

5. 章节清单与文件命名

文件内容
00-导读与地图.md主代理最后写：总目录、阅读路线、分章索引、学习方法论（墨叔写，不在代理范围）
01-开篇.md为什么你觉得 LLM 没法逻辑
02-Part1-心智模型.mdAgent 到底是什么（样章，墨叔写）
03-Part2-工具机制.md工具：给 LLM 一只手
04-Part3-规划与分解.md规划、分解与自我修正
05-Part4-记忆.md短期/长期记忆与 RAG
06-Part5-工程化.md把玩具变成生产级工具
07-Part6-架构剖析.mdClaude Code / Codex 真实架构拆解
08-Part7-多智能体与编排.md多 agent 与编排模式
09-Part8-迷你ClaudeCode蓝图.md如何架构一个迷你 Claude Code（蓝图，非可运行）
10-Part9-进阶与避坑.md评测、反模式、未来

文件均存于 C:\Users\admin\Desktop\Agent开发系统修炼手册\。

6. 标记规范（终验会查）

  • 【思考题】 与 【参考答案】 独立成行，方头括号，前后不加空格，不用 ### 标题形式。
  • 每个教学子章节二者必须同时出现、数量配对。
  • 不要在正文行内随手写”【思考题】“当普通词，会被校验误伤——只在章末模块用。

7. 禁止事项

  • 禁止把思考题答案提前剧透在正文里（答案只放【参考答案】模块）。
  • 禁止写成 SDK / API 文档搬运。
  • 禁止水字数（重复、空话、无信息量的排比）。
  • 禁止纯罗列框架名词不解释。
  • 禁止假设读者已懂 LLM 基础术语而不给直觉解释。

8. 各 Part 内容要点（代理据此展开，可补充但不可偏题）

01-开篇.md（样章，墨叔写，列此仅作上下文）

  • 你不是不会，是缺了”循环”这层心智模型
  • LLM 是函数还是人？把概率模型想清楚
  • 这本教程怎么读：地图与学习方法

02-Part1-心智模型.md（样章，墨叔写）

  • 1.1 从”补全文本”到”调用工具”：一次认知跃迁
  • 1.2 ReAct 拆解：Reasoning 与 Acting 为什么必须交替
  • 1.3 The Agent Loop：最简循环的代码骨架（Python 示意）
  • 1.4 Context Window = Agent 的”工作台记忆”
  • 1.5 确定性程序 vs 概率程序：你该怎么信任它

03-Part2-工具机制.md

  • 2.1 工具的本质：给 LLM 一只”手”（Function Calling 直觉；为什么不是让它直接写代码执行）
  • 2.2 Tool Schema 设计：名字/描述/参数的取舍（描述写得好坏直接决定调用准确率；参数类型与必填）
  • 2.3 工具调用的失败与重试：错误处理是 agent 的免疫系统（parse 失败、工具报错、超时怎么兜）
  • 2.4 副作用与安全：为什么不能随便让 agent 删文件（幂等、确认、沙箱）
  • 2.5 真实案例：把一个 CRUD 系统暴露成 agent 工具（哪些该暴露、哪些绝对不能）

04-Part3-规划与分解.md

  • 3.1 规划为什么难：LLM 的”想一步走一步”缺陷（与编译器/人类规划的对比）
  • 3.2 Plan-and-Execute：先画地图再走路（规划器与执行器分离）
  • 3.3 任务分解的粒度控制（太粗 vs 太细）
  • 3.4 反思与自我修正：Critic 循环（self-reflection、retry with critique）
  • 3.5 真实经验：规划失败的 5 种常见形态

05-Part4-记忆.md

  • 4.1 短期记忆（上下文窗口）与长期记忆（外部存储）的边界
  • 4.2 RAG 不是银弹：什么时候该检索、什么时候不该（检索噪声、上下文污染）
  • 4.3 结构化记忆 vs 非结构化（笔记、KV、向量；何时用哪种）
  • 4.4 真实案例：让 agent 记住你的项目约定（user-level / project-level memory 的设计）

06-Part5-工程化.md

  • 5.1 状态管理与可恢复性：agent 不是一次性脚本（会话、checkpoint、断点续跑）
  • 5.2 流式输出与交互体验：为什么 Claude Code 丝滑（token 流、增量渲染、可打断）
  • 5.3 成本、延迟、限流：生产级 agent 的隐藏账单（token 计价、并发、重试放大）
  • 5.4 可观测性：日志、trace、eval（没有观测就没有迭代）
  • 5.5 安全护栏：权限、沙箱、人类确认（HITL）

07-Part6-架构剖析.md

  • 6.1 Claude Code 架构分层拆解（真实形态：CLI 前端 / agent loop / 工具层 / 模型调用 / 上下文工程）
  • 6.2 Codex 的”无头 agent”模式（云端沙箱、diff 评审、与 Claude Code 的差异）
  • 6.3 工具集设计：读、写、搜、执行（为什么这些是最核心的 4 类）
  • 6.4 系统提示词里藏了什么（行为约束、工具使用纪律、输出格式、安全边界）
  • 6.5 它们为什么”丝滑”：延迟与并行的秘密（预读取、并行工具调用、流式）

08-Part7-多智能体与编排.md

  • 7.1 什么时候需要多个 agent（单 agent 的天花板）
  • 7.2 Orchestrator-Worker 模式（委派、汇总、上下文隔离）
  • 7.3 主流框架对比：LangGraph / AutoGen / 自研的取舍
  • 7.4 真实经验：多 agent 的协作成本（token 爆炸、错误传播、调试地狱）

09-Part8-迷你ClaudeCode蓝图.md（架构蓝图，非可运行代码）

  • 8.1 架构设计：我们要造什么（分层蓝图：REPL/前端层、上下文工程层、agent loop、工具执行层、模型适配层）
  • 8.2 核心循环该怎么写（Python 伪代码骨架：observe→think→act→observe）
  • 8.3 工具集设计：文件读写 + shell 执行（schema、安全边界、输出截断）
  • 8.4 上下文管理：把长对话塞进窗口（摘要、滑动窗口、关键事件保留）
  • 8.5 让它真正能改一个 bug：端到端设计（从 issue 到 PR 的信息流）

10-Part9-进阶与避坑.md

  • 9.1 评测：你怎么知道 agent 变好了（offline eval、轨迹评估、任务成功率）
  • 9.2 常见反模式（过度工具化、无边界 system prompt、把 LLM 当数据库、忽略失败模式）
  • 9.3 从 agent 到 agentic 系统：未来图景（长程任务、自我改进、与现有系统的融合）

9. 给代理的硬性交付要求

  • 一篇对应一个文件，用 Write 直接落盘到上述路径。
  • 写前先 Read 本 BRIEF 与样章 01-开篇.md、02-Part1-心智模型.md。
  • 写完用上面的 Python 片段自测中文字数，在返回消息里明确报告文件路径 + 中文字数 + 子章节数。
  • 风格必须与样章一致：墨叔/老哥对谈、反问、生活化类比、Python 示意、思考题+参考答案齐全。
  • 若某 Part 内容过多，宁可拆细子章节、加深论述，也不要超单文件 20000 字导致篇幅失控。