前情提要：我跟着 learn-claude-code 项目 学习了一个简易agent的设计思路。12 个章节学完后回头看，每一章都在教正确的思路，但也在刻意忽略工程细节。这篇文章把所有偷懒的地方列出来，给同样在学习的人一个改进参考。

 

下面逐章盘点。

 

S01：Agent 循环

 

粗糙点：系统提示词是一句硬编码字符串。

 

真正产品：动态拼装 CLAUDE.md、Memory 系统、Skills 目录、工具列表、安全规则。Claude Code 启动时的 system prompt 有数千行，来自十几个不同文件。

 

改进方向：SystemPromptBuilder 类，从多个来源拼接，支持优先级覆盖。

 

S02：工具系统

 

粗糙点：4 个工具定义硬编码在 buildTools() 里，是一大段 JSON 字符串。

 

真正产品：工具按 agent 类型动态裁剪。Explore agent 不需要 write_file 权限，code-reviewer agent 不该有 bash 权限。每种 agent 类型的工具箱不同。

 

改进方向：ToolRegistry 加 ToolCapability 注解，按 agent 类型过滤。

 

S03：任务管理

 

粗糙点：Todo.md 纯文本，加上"同时只能有一个进行中任务"的硬约束。

 

真正产品：这个约束在 S12 被 Worktree 彻底废除。有了文件隔离，多个任务可以同时进行。约束从全局一个变成每个 worktree 一个。

 

改进方向：从 S03 就为 S12 设计接口，不写死限制。

 

S04：子代理

 

粗糙点：30 轮硬上限，超额直接报错，子代理不能递归。

 

真正产品：接近上限时倒数提醒"请在 3 轮内给出结论"。超限后自动结算，把中间结果发回主 Agent。递归是允许的，但有深度限制和 token 预算。

 

改进方向：倒计时警告机制、强制检查点保存、深度计数器。

 

S05：技能加载

 

粗糙点：YAML frontmatter 只做最简解析，按三个横线分割。技能内容用完即弃，每次都重新读磁盘。

 

真正产品：至少要有 name、description、version、triggers 等字段的完整解析。热点技能缓存到内存。技能之间可以有依赖关系，比如 skill A 需要 skill B。

 

改进方向：用 SnakeYAML 库做正式解析，加上技能缓存和依赖解析。

 

S06：上下文压缩

 

粗糙点：Token 估算用字符数除以 4。压缩方式是暴力删消息。

 

真正产品：用 tiktoken 或等效库精确计数。压缩前让 LLM 生成结构化摘要，包括已完成事项、当前进度、关键发现、身份信息。身份信息保留是压缩后不失忆的关键。

 

改进方向：精确 tokenizer，结构化摘要模板，身份字段保留。

 

S07：任务系统

 

粗糙点：每个任务一个 JSON 文件。分配新 ID 靠扫目录文件名算最大值。依赖清理要全量扫所有文件。

 

真正产品：SQLite 单文件数据库。task_id 是自增主键。查谁被我阻塞和我被谁阻塞都是索引查询，时间复杂度 O(1)。

 

改进方向：TaskManager 接口不变，底层从 JSON 文件切到 SQLite。接口设计好，换存储只是换实现。

 

S08：后台任务

 

粗糙点：通知队列用 list 加锁手搓。子进程和守护线程的生死不同步，线程被杀后子进程变孤儿。

 

真正产品：进程树管理，主进程退出时所有子进程一并终止。通知队列用 BlockingQueue 或轻量消息队列。长命令自动路由到后台执行，短命令同步等待。

 

改进方向：进程树管理、命令时长预估、自动路由。

 

S09：Agent 团队

 

粗糙点：JSONL 文件收件箱，读完即清空。50 轮硬上限，静默死亡。Spawn 创建，用完即弃。

 

真正产品：内存队列做热路径，文件仅做持久化备份。读写分离，send 不阻塞 read。线程池复用，空闲 agent 可被重新分配任务而不是销毁重建。

 

改进方向：消息队列接口、Agent 线程池、优雅关闭通知。

 

S10：审批协议

 

粗糙点：状态机只有一轮来回，从挂起到同意或拒绝。无法协商。审批不校验请求来源。请求状态存内存，崩溃丢失。

 

真正产品：支持有条件审批，比如可以做但不能删那行注释。请求有超时机制，3 分钟没回应自动拒绝。身份签名防止伪造。所有待处理请求持久化，重启可恢复。

 

改进方向：条件审批、超时计时器、身份令牌、请求持久化。

 

S11：自治 Agent

 

粗糙点：空闲阶段每 5 秒轮询，空转消耗 CPU。60 秒没活就直接关机，不问有没有未完成任务。

 

真正产品：事件驱动，任务看板变化时主动推送通知，不靠轮询。智能休眠：根据历史任务频率动态调整空闲超时。

 

改进方向：任务看板监听器，观察者模式，自适应休眠策略。

 

S12：Worktree 隔离

 

粗糙点：非 git 项目降级为普通目录复制，文件操作代价高。完成不自动合并，全靠人。

 

真正产品：容器化隔离（Docker）或 chroot，不受 git 限制。完成时自动生成差异化文件，创建 Pull Request，通知 Leader 审查。

 

改进方向：Docker 沙箱、自动差异化生成、PR 生成流程。