Agent 工程
软件是现实世界的解决方案在数字世界的映射,程序员的工作是将现实世界的解决方案翻译为在数字世界运行的程序代码
# 提示词工程
# TDD Vibe Coding
From Coder to Builder
Vibe Coding 本质就是自然语言驱动 LLM 直接产出可执行代码(Prompt Engineering),软件从 “工程实践” 退化成 “一个想法”,AI 是编程的义肢,并且随着 Agent 的不断发展,人逐渐编程 AI 的义肢,二者的主导关系在慢慢变化,AI 越来越主动
事实上,产品给我们提需求实际上也是一种 VIbe Coding(什么碳基 Agent)
程序员本质上是把现实需求转变为数字世界的语言描述的“翻译者”,在 AI 的帮助下,“翻译”工作变得越来越简单(这也是外界不看好这份工作会持续的原因),未来程序员的意义更多在于翻译的信达雅以及现实需求本身的完善,而不是仅仅做好“翻译”这件事 —— 相信 AI 的不断发展,这样的品味优势也会逐渐削弱
TDD 测试驱动设计是较为规范的 Vibe Coding 方式,通过提前定义验收条件,驱动 AI 开发功能,面向测试编程
- 在 TDD 里,人类天然可以充当 QA,完成 AI Coding 的质量闭环
但在实际工程场景中,测试用例总是在开发之后、上线之前,从顺序上还是自上而下的 PRD 开发,而非面向测试开发 TDD。当然,这不意味着 TDD 不好,只是在开发之前,作为 RD 需要去对齐产品和测试验收标准,这需要一定的嗅觉
让测试和验证成为开发过程的核心,这是不可避免的趋势
另外,对于已有代码库,最好的 Vibe 方式是保持已有代码的品味和清洁,让 AI 根据已有代码进行编码 —— AI 很擅长模仿而不善于创造
# Spec Coding
少写 Prompt,多用规则
规约编程(Spec Coding),或者说规范驱动编程(SDD,Spec-Driven Development),强调在动手编写代码之前,开发者与 AI 需先共同制定一套关于软件架构、功能边界与业务逻辑的详细规约文档,AI 将严格基于此文档逐点执行开发任务,旨在将 AI 编程从“玄学”拉回“工程学”
| 原则 | 解决什么问题 |
|---|---|
| 编码前思考 | 错误假设、隐藏困惑、缺少权衡 |
| 简洁优先 | 过度复杂、臃肿抽象 |
| 精准修改 | 无关编辑、触碰不应碰的代码 |
| 目标驱动执行 | 通过测试优先、可验证的成功标准 |
Rules:约束智能体的需求文档,统一放在项目根目录的 .rules 文件夹中,说白了就是规范 LLM 行为的文档形式的 System Prompt,在以下四个方面对 LLM 进行提示与约束
- What:代码库干嘛的
- Where:目录结构如何组织
- How:场景流程,few shot
- Should/Not:应该/禁止做什么
可以参考 Cursor 内置的 Rules,本质上都是一段 markdown 格式的 System Prompt,让 AI 先阅读指定文件再进行操作,进行相对规范的操作
- 单测 rule:unit-test-rules
- 代码风格 rule:code-style
- Go 单测 skill:go-unit-test
还有一种比较极端的 Spec 方式,直接用 Lint 规则、类型系统和架构约束把不合理的写法直接禁掉
# Pairing Coding
结对编程最早是 ACM 里的概念,一人编码,一人审查,在结对编程中,编码和审查的角色是随时互换的 —— Comate 厂内的 Copilot
人机协同十二原则
- 用注释加强 AI 代码理解:先写注释再编码
- 代码人易懂 = AI 易懂,提升代码可读性:保持代码风格;有意义的命名;代码块粒度合适(150 行左右);先搭架子再填空
- 留心 AI 能力范围:AI 后台运行,需要定时检查
- 准备私域知识:如优质的 few shot、RAG 等
- 编码前多提问:了解 AI 意图,明确个人需求
- 编码后 AI 审查:让 AI 审查 AI 代码
- 写代码前先澄清:清晰代码意图和功能
- 让 AI 复用和扩展个人能力:插件、MCP、Skills
- 专注于核心业务,杂活全部交给 AI:如复杂的正则表达式
- 不会的、不熟悉的让 AI 帮忙
- 人是驾驶者,AI 是辅助手
- 接受 AI 的不完美
常见场景
- 基于注释生成代码(Comment Driven Coding)
- 根据代码生成注释
- 充当搜索引擎
- 单测文件生成
使用经验:在拿到一份项目时
第一步:开启全局上下文并做全盘扫描在你的 AI 对话框里,确保你已经唤起了读取整个代码库的指令,然后发送这个破冰指令
你现在是一个资深的后端架构师,我已经将整个代码库作为上下文发给了你,请你先不要修改任何代码,只做仔细的阅读和审查。请用中文为我总结这个项目的核心信息
1. 这个项目使用的核心技术栈是什么?(包括框架、上下游依赖、状态管理、构建工具等)
2. 请梳理并解释目前的目录结构 (如下各个子目录的作用)
3. 项目的入口文件和核心路由体系是如何组织的,项目暴露了哪些接口
2
3
4
5
第二步:深挖工程规范与约定
等它梳理完骨架后,你需要让它提取项目里的“潜规则”这能保证后续它生成的代码风格与现有代码完全一致,而不是自编自导“非常好
现在请深入到具体的业务代码层面,帮我总结一下目前项目中的编码约定
1. 数据请求:项目里是如何封装和接收 HTTP、MCP 或微服务请求的?(是否有统一的工厂处理模式?)
2. 数据存储:主要有哪些用户数据,存储在哪里,是否采用了缓存设计?
3. 日志处理:是否有统一的日志处理框架,是否用到了消息队列处理日志?
4. 有没有我需要特别注意的特殊逻辑或潜在的技术栈?
2
3
4
5
6
第三步:生成“记忆面包”(沉淀文档)
当 AI 完美回答了前两步后,它此时的脑子里包含了这个项目最完整的信息,但只要开启新对话就会遗忘,所以需要让它把这些信息通过文档的方式固化下来
基于你刚才的审查结果,请帮我生成一份详尽的 PROJECT.md 文档,这份文档的目的是:以后当我开启新的 AI 会话时,只要让 AI 读取这个文档,就能立刻了解项目的全局规范和架构,请排版清晰,包含技术栈概览、 目录说明、核心开发规范等关键信息
拿到生成的 PROJECT. md 后,把它保存在项目根目录下,以后每次你想开发新功能,开启一个新的 AI 对话窗口,第一句话就是:“请先阅读 PROJECT. md,然后帮我实现 xxx 功能”,这样写出来代码质量会相当不错
# Claude Code
模型和提示词主导产出质量
发现一个很有意思的事,CC 和文库的后端栈完全一样
- 基础:提供模型能力,对应 API Token 来源,如 GLM5.1
- 策略:工作流编排和智能体循环,对应 Claude 智能体
- 业务:交互逻辑和接口调用,对应 Cli 命令行的交互方式
CC Switch:Release CC Switch v3.14.1 · farion1231/cc-switch (opens new window)
- Claude Code 配置 | PackyAPI 使用文档 (opens new window)
- 接入 Claude Code | DeepSeek API Docs (opens new window)
- DeepSeek 开放平台 (opens new window)
使用 CC Switch 切换 Claude 的模型,新建 Provider,填写请求地址和 API Key
https://api.deepseek.com/anthropic
DeepSeek V4 模型配置
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "api key...",
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
"CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
"CLAUDE_CODE_EFFORT_LEVEL": "max"
},
"theme": "dark-daltonized"
}
2
3
4
5
6
7
8
9
10
11
12
13
在设置中打开跳过 Claude Code Login,直接启动 Claude,用 /model 可以看到 DS 的四个模型
- 或者使用 shengcanxu/Reasonix (opens new window),更符合 DS 体质的 Native Agent,缓存命中率奇高
- 或者在 CC 中使用 Kimi 2.5:Claude Code 换成了 Kimi K2.5 后 - 掘金 (opens new window)
Claude Code npm 下载
npm install -g @anthropic-ai/claude-code
claude --version
claude install
claude update
# 启动 claude 需要开 tun 模式
claude
2
3
4
5
6
7
8
常用命令
/init # 初始化仓库 Claude.md
/model # 选模型
/effort # 努力值
/clear # 清除当前记忆
/compact # 整理当前对话
/agents # 子 agent
/memory # 查看记忆文件
2
3
4
5
6
7
基本使用
- 用贵的模型跑 agent.md 理解项目
- 然后用 haiku / sonnet 去执行生成任务
- plan mode 理解 → agent mode 修改
# Harness 工程
后训练正在摧毁 Harness
Rules 通过规则 Prompt 约束 Agent 行为,属于 SDD,Harness 通过严谨的环境条件限制 Agent 行为,属于 BDD
- SDD(Specification Driven Development)是一种以规范为核心、先写规范再生成代码的开发方法,强调AI辅助下的高效、可控和可追踪的软件开发流程
- BDD(Behavior-Driven Development)是一种以业务需求为导向的软件开发方法,通过自然语言描述系统行为,促进开发、测试和业务团队的协作
AI Coding 的演化一定是:SDD(rules) → BDD(harness) → DDD
# 工作流
工作流是 Agent 的心脏
常见的 Workflow
- Plan & Execute
- reAct
现在 Workflow 已经变得无比鸡肋,因为模型能力太强了,LLM 完全能够自己规划工作流,根本不需要人为编排
# Agent Loop
旨在“完成任务之前持续工作”,例如 Audit Agent 的循环审计设计和 CodeX 的 Goal 模式
RSI 在新的概念里又引入了 Loop 过程中的“自学习”能力,正如 Robin 所说,演化能力是 Agent Loop 的精髓
# 可复用技能
MCP:模块化的、标准化的、微服务化的工具调用(function call),让 LLM 快速获取某项技能,包括但不限于搜索网页、生成文档、读写文件
Skill:本质上是渐进式披露的 Markdown 系统提示词,虽然现在还没有明晰的概念提出,但是 Skill 已经明显区分为两类
- 一种是环内的 skill:给 agent loop 的 skill
- 一种是环外的 skill:与人交互的 skill
Skill 与 MCP 区别:MCP 需要 JSON-RPC 协议接入并且一次暴露整个 MCP 能力,而 Skills 直接让 LLM 读取 Markdown 文档获取,通过“渐进式披露”提供能力,并且 Markdown 文档较于 MCP 调用更具普适性
一个 Skill 的基本结构
skill-name
├── SKILL.md # 定义、描述 skill
├── scripts/ # 具体的可执行代码脚本,其说明在 SKILL 中定义
├── templates/ 文档模板
├── resources/ 资源文件
2
3
4
5
以 superpower (opens new window) 为例
/plugin marketplace add obra/superpowers-marketplace # 添加第三方市场
/plugin install superpowers@superpowers-marketplace # 下载 superpowers
2
- 这里是通过插件的形式下载,本地文件将放在
~/plugins/cache/superpowers-marketplace/superpowers/5.1下(实际上就是 github 仓库的源码),可以看到 Claude.md、Agents.md 等文件,点进 skill 目录,可以看到一个个的 skill 和对应的 skill.md - 也可以手动导入:将 skills 包 copy 进
~/.claude/skills文件夹,Claude 就能够自动渐进式的阅读 Skill 并载入相应内置命令
Skill 构造的一些思路:和写 prompt 的思路一致,few shot 和 cot 是关键
- 用 diff 形式给 llm 示例 shot,例如
--- a/pkg/request/client.go
+++ b/pkg/request/client.go
@@ -3,7 +3,7 @@
package request
-import oldhttp "github.com/example/old-http-client"
+import uhttp "github.com/example/unified-httpclient"
- return oldhttp.Do(
+ return uhttp.Do(
2
3
4
5
6
7
8
9
10
11
- 能用表格就用表格:AI 读表格比读大段文字准确得多,能结构化的信息,尽量用表格呈现
- 前置检查或配置流程比较复杂,写成脚本放到 scripts/ 目录下,SKILL.md 里直接调用就行,例如检查 go、npm、pnpm、codegraph 等等
- Skill 的水平分割,通过主 Skill 调用子 Skill 的形式模块化 Skill 的能力,严格遵守“渐进式披露”,例如
project-migration/ # 主 Skill:流程总览与编排
├── SKILL.md
└── steps/ # 拆分出的子步骤文档,主 SKILL.md 按顺序引用
├── 00-environment-setup.md
├── 01-dependency-update.md
└── 02-api-migration.md
project-migration-sub-env-setup/ # 子 Skill:可独立调用
├── SKILL.md
└── scripts/
└── check-env.sh
project-migration-sub-api-migrate/ # 子 Skill:可独立调用
├── SKILL.md
└── references/
└── api-mapping.json
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Github 上随处可见创建 Skill 的 Skill,LLM 的生态已经逐渐自旋了(类似编译器的自编译),例如根据 Rules 构造 Skill,只需要一句话就可以直接让 Comate 生成一份 Skill
请把这份单测 rules 封装成一个 Claude Code 可以直接使用的 skill
Comate 直接把 skill 生成到 ./claude/skills 目录,ducc 不用重启就能动态加载指令
/go-unit-test-rules
# 或者带参数查询特定内容
/go-unit-test-rules "Mock 规则"
/go-unit-test-rules "覆盖率"
/go-unit-test-rules "测试模板"
2
3
4
5
其他 Skill 提炼思路
| 用途 | 具体任务 |
|---|---|
| 内网 Skill | 1. 解读内网新闻 2. 解读知识库内容 3. 在内网自动搜索文章 4. 内网购物 5. 当做网页截图工具 6. 写周报 |
| 作为研发工具 | 1. 生成接口请求 curl,处理 json,类型转换;生成接口调用流程,辅助技术设计 2. 在代码库上级目录打开,这样 ai 可以去一次行读取多个代码库,对于查一下涉及上下游的调用的问题和 case 会比较好用,等于串联起完整的链路去分析,问题定位比较准 3. 同时开 Claude Code 和 Copilot,商讨技术实现,达到最终一致(Token x2) 4. 根据技术评审文档 + 接口文档改造接口并提交 CR,打通了代码仓库和知识库的数据流通和权限管理 |
# ACE 工程
ACE 上下文工程:解决上下文腐烂
- 上下文工程 ≠ 精炼总结,压缩 ≠ 总结
- 压缩可逆,总结不可逆,总结的信息丢失程度远大于压缩,就像 Hash 和 Zip
- kv cache 和 prompt cache?前缀缓存
节省上下文小妙招
- 图检索代替 grep:用 CodeGraph 代替全文 Grep 检索,减少 Agent 阅读代码时的 Token 消耗,和 LSP 代替 Grep 的思路类似
- 脚本复用:让 Agent 沉淀可执行的脚本,如”构建单测脚本“,让”任务执行“本身成为一种可复用的能力
- Agent 的动态工具选择:枚举配置工具名,根据 skill 注入 mcp 工具,用 31B 的小模型决定加载哪些 skill,JEV 和 Decision API 就是这个道理
# 组织与闭环
AI 开发的越快,人工 Review 的积压也越多,效率并没有飞跃 —— 人的注意力是有限的,All We Have is Attention
# A2A 到智能组织
“找到摸鱼的方法实现长期主义”
Agent 之间的通信,通过通信共享内存(桥接)还是共享内存通信(总机)?
- 对于 Go 编码者而言,显然通信是更符合直觉的选择,优雅高效,在实践中也确实节省 Token,不需要重复的上下文堆叠
- 共享上下文本质上就是 ReRead,这里的操作空间在于,子 Agent 是隔离的,可以用便宜模型,这样也可以实现节省,并且能更大程度上保留语义
Agent 的内存即上下文 context,在控制 Token 总量相同的前提下,很难量化二者的实际工程效果,更多需要根据隔离性和任务复杂度适当的选择桥接还是总机
这可以引申到另一个争论,即是 Multi Agent 还是 Agent as a Tool,前者对应通信的 A2A 模式,后者对应共享内存的“调用”模式(将子 agent 作为工具调用),优缺点和 Agent 通信大差不差,同样具体问题需要具体分析,到底谁更好尚无定论
此外,Graph Engineering 是较火的 A2A 方向,旨在将不同智能体的按照领域划分进行组合联系,构成图的协同工作结构,这是更上层的架构设计
在实践中,可采用 DSH + Pi 实现第二种方式的 A2A(Agent as a Tool),DSH 作为需求沟通和任务调度的主题,Pi 作为任务执行的主体,作为 Tool 供前者调用
- Pi:极简的 Harness 工程实践,依赖强模型,本质上是少了教 Agent 如何去干活的提示词,假设 —— 模型已被后训练训成"知道怎么当 agent",system prompt 大半是在重教它已经会的东西。上下文相比于 CC 少一个数量级,同样的窗口装得下更多真实代码
# windows
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# mac
curl -fsSL https://pi.dev/install.sh | sh
2
3
4
5
使用和 cc 基本一致,具备基本的 compact,ctrl + l 切模型的功能,同样的可以通过 CC-Switch 本地中转模型 API,这里用 OpenRouter 的免费低等模型:https://openrouter.ai/workspaces
pi --continue # 加载上次上下文
/model
/compact
2
3
Pi 的扩展机制:本质是一个跑在 pi 进程内的 TypeScript 模块(用 jiti 加载的本地 .ts),放在指定目录 ~/.pi/agent/extensions/hello.ts 启动钩子加载,通过注册的 /hello 命令触发
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
export default function (pi: ExtensionAPI) {
pi.registerCommand("hello", {
description: "Show a greeting",
handler: async (name, ctx) => {
ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
},
});
}
2
3
4
5
6
7
8
9
10
DSH:DeepSeek 的官方 Agent,TypeScript/Node 实现,Desktop 跑在 Electron 里,以“插件”作为其生态构建的核心,借鉴了 Koishi 的插件生态,以 Cordis 为内核构建
- Koishi 是一套聊天机器人框架,
cordis是 Koishi 的插件/依赖注入内核,作者都是 Shigma - DSH 插件 = bundle(
package.json+cordis.patch.yml),cordis 按 Context/Service 注入依赖,cordis-plugin-loader管理 EntryTree 实现运行时加载
智能组织 —— Robin 在 26 年百度智能大会上提出的概念 —— 电力没有产生效益直到他变成电机进入工厂,我们现在正处于一个有智力但尚未真正利用起来的阶段 —— 建设组织智脑,让经验可沉淀
# 递归自我改进
数据是 LLM 的血液,RSI(Recursie Self-Improvement) 的重点在于“数据闭环” —— 构建一套血液循环系统
数据闭环是自编译的艺术,例如
- AnyDev 开发与优化:通过配套的 agent + workspace + skill 承接真实需求,需求分析 → 人工审核 → 拉分支开发 → 联调 → 人工 PR → MR → 更新 skill
- “工单” Agent:工单场景的数据闭环,agent 创建工单 → 人工标注有误的工单 → 优化 rag 知识库 → 继续创建工单
Loop 和 RSI 的区别
- codex 的 goal 模式是经典的 loop 实践,让 agent 在 loop 中持续发现、解决问题,实现工作 - 复查闭环
- 递归式自我改进是当前 Loop Engineering 的核心,我们不满足在 loop 中解决问题,还需要在 loop 中改进方法
这里引申到另一个议题,即长时序智能体(long-horizon agents)的优化,通过减少决策轮次来提供任务成功率和上下文长度:[2609.02042] Act More, Decide Less: Skill-Guided Adaptive Action Chunking for Long-Horizon LLM Agents (opens new window)
LoopForge - 一个云端运行、云端共享、工程级 SOP、无人值守自动化、RSI 自进化的云端 Agent (opens new window)
# 工作区和访问控制
一个基本的控制访问思路实践是:给每个基建开放只读权限 + Loop + 人工介入实现 Bug 的全链路追查
- 只读 KubeConfig
- 只读 MySQL 账号
- 只读 Redis 账号
- 日志 Cli
- 只读 Git 权限
工作区只隔离环境,但不隔离操作 —— 只要有网络和权限,理论上 agent 可以在任意环境去读写 DB,agent 确实是需要访问控制管理的,这涉及到密码工程,当然在工程实际里,这大概率退化成管理问题
这里更多想讨论的是 Workspace 的具体形态,CubeSandbox - 容器、micro-VM 还是完整 VM (opens new window)
- Agent 跑在容器里,例如在 Docker 容器里跑一个 Pi,再对外暴露
- Agent 跑在容器外,把 Docker 容器作为一个长期资源分配给 Agent 调用操作
- Workspace 以 Sandbox、云函数的形式提供给 Agent 调用
AnyDev 给的实际上是 k8s 容器,和 micro-VM 的区别?