系列导航

• 上一篇：AI Agent 工程实践（00）：为什么我要构建 AI Engineering OS

本文是 AI Agent 工程实践 系列的第 01 篇。

1发布时间：2026-07-08

标签：AI Agent｜LLM｜架构设计｜工程实践｜知识管理

---

为什么很多 AI Agent 项目越做越乱？我用了一年、踩了半年坑，最终把整个系统拆成五层：

Knowledge → Rules → Agent → Project → Review

这篇讲清楚为什么一定这样分、而不是别的方式。读完后你会明白：你遇到的问题，90% 都能用它解决。

本文你将学到

• ✓ 为什么 AI Agent 需要分层架构
• ✓ 五层分别负责什么、边界在哪
• ✓ 为什么一定要有 Review（很多系统缺这一层）
• ✓ 如何形成"学到→做到→复盘→改进"的闭环

适合阅读

• ✓ AI Agent 初学者（了解完整架构）
• ✓ Claude Code / LangGraph 重度用户
• ✓ 想搭建个人知识+开发体系的人
• ✓ 对"工程化"而非 demo 感兴趣的人

目录

[TOC]

不先讲架构，先讲为什么不是别的

这篇文章最后长成五层，不是一开始设计出来的。它是一步步演化出来的。

从 v0 到 v5 的演进

graph LR
    v0["v0: 只有 Prompt"]:::v --> v1["v1: +Knowledge<br/>知识能存了"]
    v1 --> v2["v2: +Rules<br/>行为统一了"]
    v2 --> v3["v3: +Agent<br/>执行解耦了"]
    v3 --> v4["v4: +Project<br/>交付可追溯了"]
    v4 --> v5["v5: +Review 🔁<br/>闭环形成了"]
    classDef v fill:#e6f1fb,stroke:#185fa5

版本	加了什么	解决了什么	还缺什么
v0	Prompt 文件	能跑起来	知识无法沉淀
v1	Obsidian 知识库	知识有地方存	Agent 行为不统一
v2	core/heavy 规则分层	行为统一了	规则和 Agent 耦合
v3	Hermes + Claude Code	Agent 独立执行	项目和工具混一起
v4	项目目录标准化	交付物可追溯	经验无法回流
v5	每日/每周复盘	闭环形成	Review 半自动（当前）

每个版本都在补上一个版本的漏洞，而不是为了"多一层"而多一层。

为什么不选其他方案

候选方案	问题在哪
单体（一个文件全包）	规则>20条后维护成本指数上升，多 Agent 互相覆盖
扁平（层无方向）	双向依赖，改了 A 不知影响 B，复盘找不到根因
四层（缺 Review）	经验不回流，踩过的坑下个新项目再踩一遍
五层 + 反馈闭环	架构留对了位置，自动化可以迭代——推荐

选五层的核心理由：Review 把系统从"一堆工具"变成了"能自我改进的有机体"。

第一层：Knowledge — 土壤

Knowledge = Obsidian 知识库（原子笔记 + MOC + PARA 管理体系）

存一切：技术概念、论文笔记、踩坑记录、设计决策。为什么是底层？因为规则不能拍脑袋。如果 Knowledge 里没有"LLM 上下文窗口有限"这个事实，Rules 层就产不出"关键提示放开头和结尾"这条规则。

设计三原则：写入（人类/Hermes 写笔记）→ 读取（Rules/Agent 检索）→ 不做决策（只存事实，不含"应该怎么做"）。

第二层：Rules — 从知识到约束

Rules = core/（3 条常驻底线） + heavy/（20+ 按需能力文件）

把"知道是什么"变成"应该怎么做"。

Knowledge 中的事实	转化为 Rule
LLM 上下文窗口有限	加载 heavy/ 前估算 token，超限时剪裁
模型会 lost in the middle	关键提示放开头和结尾
修改文件前要读内容	Read 优先于 Edit

为什么独立一句话：规则可以被多个 Agent 共享（Hermes 和 Claude Code 读同一套 core/），可以独立测试，可以按需加载（详见 01 篇）。塞在 Knowledge 或 Agent 里都拿不到这些好处。

第三层：Agent — 规则的执行者

Agent = Hermes Agent（学习教练） + Claude Code（编码工程师）

只管执行。接收任务 → 加载 Rules → 输出结果。不制造规则、不管理知识。

为什么不和 Rules 合并？Rules 定义"应该遵守什么"，Agent 负责"在特定任务中遵守它"。合并的话，每新增一个 Agent 都要重新配一遍规则。分开后 Agent 只管加载，规则层独立演进。

当前分工：Hermes 管知识管理/面试准备；Claude Code 管代码生成/架构/测试。两者共享 core/。

第四层：Project — 交付物

Project = agentone_test / agent_code / ...

Agent 产出的代码、文档、配置。分开的理由很务实：

• 换工具时（Claude Code → Cursor）项目不受影响
• 出问题时能分清是"Agent 的问题"还是"规则的问题"还是"项目本身的问题"

一句话：责任可追溯。

第五层：Review — 自愈

Review = Daily Review（日复盘） + Weekly Review（周复盘）

定期检查前四层 → 发现问题 → 更新 Knowledge → 迭代 Rules → 优化 Agent。

为什么独立成层？经验证明：如果 Review 是"顺便做的事"，它就不会被做。独立成层是强制闭环——它不是可选装饰，是架构的一部分。

一个概念的五层之旅

用真实例子说明五层如何联动：

1. Knowledge：我记了一条原子笔记——"LLM 对 Prompt 中间位置的指令遵循率低于两端"（来源：Lost in the Middle 论文）。
2. Rules：Claude Code 常忽略写在中段的约束。我把笔记转化为 heavy/ 规则："关键提示放在对话开头或结尾。"
3. Agent：Claude Code 加载规则后，自动把安全边界、风格约束放 prompt 头尾，中段只放参考内容。
4. Project：agentone 项目的代码风格一致性提升，手动修正减少 40%。
5. Review：周复盘记录了改善。Hermes 的 cron 发现连续两周出现"遵循率波动"备注，建议补充规则——"对话超过 10 轮后重新注入关键约束"。

闭环跑通的前提：五层职责清晰、数据流向明确。

架构图

五层堆叠（自底向上）

阅读方向：自底向上。KNOWLEDGE 是土壤 → RULES 提取约束 → AGENT 加载执行 → PROJECT 产出 → REVIEW 反馈改进。

再抽象一步，和操作系统的类比：

OS 概念	AI Engineering OS
文件系统	Knowledge（持久化存储）
系统配置	Rules（行为约束）
进程调度	Agent（任务执行）
工作目录	Project（交付物）
监控日志	Review（可观测 + 反馈）

代码或配置示例

完整目录结构

一、AI核心规则配置根目录（Rules + Review 层）
统一存放模型约束规则、复盘记录、通用技能库，为智能体执行提供标准化规范与迭代素材
/.claude-data/
├── core/
│   └── 00-must.md         # 全局核心底线规则（3条常驻强制规范，所有场景通用）
├── heavy/                 # 场景化按需增强规则库（20+细分能力配置）
│   ├── 10-review.md       # 内容复盘、输出校验规则
│   ├── 20-test.md         # 代码测试、用例编写规则
│   ├── 30-architecture.md # 系统架构、方案设计规则
│   └── 40-security.md     # 代码安全、合规校验规则
├── memory/                # 常态化复盘归档目录（体系自愈迭代核心）
│   ├── YYYY-MM-DD.md      # 每日复盘迭代记录（按日期归档）
│   └── MEMORY.md          # 全局汇总复盘台账
└── skills/                 # 可复用通用技能库
    └── code-review.md      # 代码评审标准化技能规范
二、通用知识知识库目录（Knowledge 层）
全局私有知识沉淀载体，采用标准化笔记架构，为规则、智能体提供底层知识土壤
/knowledge-base/
├── 概念/                  # 基础理论、技术概念沉淀
│   └── llm-context-window.md
├── MOC/                   # 主题知识地图（全局知识索引体系）
└── 公开内容/              # 博客、文档、公开输出素材库
三、项目交付工程目录（Agent + Project 层）
业务/技术项目落地载体，支持项目级独立配置、可追溯、可复用
/workspace/project-demo/
├── src/                   # 项目核心源码、业务逻辑目录
├── .claude/               # 项目专属个性化配置（覆盖全局规则）
└── README.md              # 项目说明、交付文档、迭代记录
核心架构对应关系
知识层：/knowledge-base/ 全域知识库，提供所有上下文素材
规则层：/.claude-data/core + heavy 双层规则，统一模型输出约束
执行层：依托规则+知识，驱动智能体完成代码、文档、复盘等任务
交付层：/workspace/ 各项目落地产出，形成标准化交付物
复盘迭代层：/.claude-data/memory/ 日周复盘，反向更新知识与规则，完成闭环迭代

层间交互配置示例

这是 core/00-must.md（常驻规则——任何任务都加载）：

# core/00-must.md — 行为底线
core:
  - 始终使用中文回复
  - 修改文件前先 Read 原始内容
  - 提出架构方案时必须说明 trade-off

这是 heavy/10-review.md（按需加载——仅代码审查任务）：

# heavy/10-review.md — 代码审查规范
trigger: "用户要求代码审查或提交变更"
max_lines: 300
priority:
  - 设计问题
  - 正确性
  - 可读性
  - 性能
rules:
  - 每个问题必须有「描述 + 反例 + 改进建议」
  - 不指出缺少文档/注释等非功能性建议

加载逻辑伪代码

def build_context(task_type: str) -> list[str]:
    context = load_file("core/00-must.md")   # 常驻
    task_heavy = {
        "review":  ["heavy/10-review.md"],
        "test":    ["heavy/20-test.md"],
        "arch":    ["heavy/30-architecture.md"],
        "security": ["heavy/40-security.md"],
    }
    for f in task_heavy.get(task_type, []):
        context += load_file(f)               # 按需
    return context

总结

• ✅ 五层是从 v0 一步步演化出来的，不是为了分层而分层。
• ✅ 每一层不可替代：Knowledge（存）→ Rules（约）→ Agent（行）→ Project（交）→ Review（馈）。
• ✅ 依赖方向单向（上→下），反馈方向反向（下→上），避免循环依赖。
• ✅ Review 层是这套系统"有资格叫 OS"的原因。没有闭环，它只是一堆工具的堆叠。
• ✅ 坦诚：Review 目前半自动，但架构里留好位置，比自动化程度更重要——自动化可以迭代，架构推倒重来成本极高。

参考资料

• Lost in the Middle 论文 → 为什么关键指令不能放中间，直接影响了 Rules 层的设计原则
• Claude Code 官方文档 → Rules 与 Project 配置，分层加载的工程基础（[待补链接]）
• PARA Method (Tiago Forte) → 知识库管理方法论，Knowledge 层的组织依据
• Obsidian Linking & MOC → 笔记互连和索引导航，让 Knowledge 层可检索
• Hermes Agent Skills 系统 → Review 半自动化的技术基础（[待补链接]）