夜雨聆风从能跑就行;到可维护、可扩展、可审计——差的不是代码量，是结构。
先问你一个问题：
你的 Agent 项目，现在有几个文件？如果超过 3 个：prompt 一个文件、工具调用一个文件、记忆管理一个文件；你是不是已经开始感受到"目录快炸了"？
这不是你一个人的问题。Agent 从 Demo 走向生产，第一个撞上的硬墙就是工程化目录结构。一个混乱的项目结构会让调试变成噩梦、让协作变成灾难、让安全审计无从下手。
今天这篇文章，拆解一个标准的工程化 Agent 项目目录。每一个目录都有明确的职责边界，每一个文件都有清晰的上下游依赖。读完你会发现：Agent 工程化的秘密，全在目录里。
一、整体结构：一图胜千言
agent/ ├── prompts/# 提示词核心 — Agent 的行为边界 ├── memory/# 记忆模块 — 跨会话的持久化上下文 ├── tools/# 工具调用 — Agent 与外部世界交互 ├── workflows/# 工作流编排 — 任务处理流程定义 ├── skills/# 能力模块 — 可复用的专项能力 ├── knowledge/# 知识库 — 减少幻觉的外部知识 ├── configs/# 配置管理 — 模型参数/权限/环境 ├── logs/# 运行记录 — 调试、审计、优化 ├── README.md# 项目说明 └── agent-index.md# 文件索引（整个项目的"地图"）
八个核心目录，两个入口文件。不多不少，刚好覆盖 Agent 从"接收指令"到"执行任务"到"记录反馈"的完整生命周期。
二、逐层拆解：每个目录解决什么问题
1. `prompts/` — Agent 的"宪法"
职责： 存放所有提示词定义，管理 Agent 的行为边界。
文件 | 干了什么 |
system-prompt.md | 系统级提示词：身份、角色、核心原则 |
task-router.md | 任务路由：决定把任务分给哪个 Skill 或工具 |
role-config.md | 角色配置：不同场景下 Agent 的身份切换 |
output-format.md | 输出格式：约束返回的格式和结构 |
一句话： prompts/ 是 Agent 的"宪法"——定义它是什么、能做什么、不能做什么。所有其他模块都在这个边界内运行。
学术关联： System Prompt 的设计原则可追溯到 Brown 等人（2020）提出的 In-Context Learning 框架——模型的行为可以通过文本指令而非参数修改来控制 [¹]。ReAct 模式中的"Thought"步骤，本质上也是 system-prompt 中定义的推理范式 [²]。
2. `memory/` — Agent 的"记忆系统"
职责： 管理不同时间尺度的记忆，让 Agent 能"记住"跨会话的信息。
文件 | 时间尺度 | 存什么 |
user-profile.md | 长期 | 用户画像：稳定不变的基本信息 |
session-context.md | 短期 | 会话上下文：当次对话的临时状态 |
long-term-memory.md | 长期 | 跨会话积累的重要信息和决策 |
knowledge-notes.md | 知识层 | 从对话中提取的结构化知识 |
一句话： Agent 没有记忆就没有连续性。三层记忆（短期/长期/知识）分别解决"当前在做什么""以前做过什么""学到了什么"三个问题。
学术关联： 记忆系统的三层架构（工作记忆/情景记忆/语义记忆）可追溯到认知科学中的记忆分类理论。在 LLM Agent 领域，Sumers 等人（2024）在 CoALA 框架中系统论证了"记忆模块应作为 Agent 架构的独立组件"，将记忆分为工作记忆（当前任务状态）、情景记忆（历史经验）和语义记忆（抽象知识）三个层次 [³]。
3. `tools/` — Agent 的"双手"
职责： 定义 Agent 可调用的外部工具及其接口。
文件 | 能力 |
browser-tool.md | 浏览器工具：网页访问与操作 |
code-executor.md | 代码执行器：安全沙箱中的代码运行 |
api-connectors.md | API 连接器：第三方服务接入 |
search-tool.md | 搜索工具：搜索引擎调用 |
一句话： LLM 是大脑，tools/ 是双手。没有工具，Agent 只会"想"不会"做"。
学术关联： 工具调用是 ReAct 框架的核心环节（Action 步骤）。Yao 等人（2022）证明，LLM 通过"推理→行动→观察"的闭环，可以自主调用外部工具完成复杂任务——而工具的定义质量和描述准确性，直接决定了调用的成功率 [²]。
4. `workflows/` — Agent 的"执行流程"
职责： 定义不同场景下的任务处理流程，把多个模块串联成可执行的链路。
文件 | 流程 |
plan-execute.md | 规划执行流：先计划，后执行 |
rag-pipeline.md | RAG 检索增强：检索→组装→生成 |
multi-agent.md | 多 Agent 协作：任务分发与协调 |
evaluation-loop.md | 评测闭环：结果验证与反思优化 |
一句话： workflows/ 是"编排层"——把 prompts、memory、tools、skills 串成可执行的业务逻辑。
学术关联： RAG（Retrieval-Augmented Generation）由 Lewis 等人（2020）在 NeurIPS 上提出，核心思想是将检索与生成解耦——先检索相关文档，再让 LLM 基于检索结果生成回答。workflows/ 中的 rag-pipeline.md 正是这一思想的工程化落地 [⁴]。
5. `skills/` — Agent 的"能力插件"
职责： 每个文件是一个独立的可复用能力模块。
文件 | 能力 |
writing.md | 写作能力 |
coding.md | 编程能力 |
analysis.md | 分析能力 |
design.md | 设计能力 |
一句话： skills/ 是"插件系统"——能力模块化、可插拔、可复用。新增一个能力只需加一个文件，不碰其他模块。
学术关联： 模块化设计是软件工程的核心原则（Parnas, 1972），在 Agent 工程中同样适用。Skill 的本质是对"WHEN/WHAT/HOW/REFERENCE/LIMITS"五要素的结构化封装，将"Agent 能做什么"从"Agent 怎么做"中解耦。
6. `knowledge/` — Agent 的"外部知识"
职责： 存放 Agent 可引用的外部知识，减少幻觉、提高准确性。
文件 | 内容 |
domain-faq.md | 领域 FAQ：常见问题的标准答案 |
product-docs.md | 产品文档：产品相关知识 |
policy-rules.md | 政策规则：合规及业务规则 |
glossary.md | 术语表：统一术语定义 |
一句话： 知识库是 RAG 的核心——减少幻觉的第一道防线不是更好的模型，而是更准确的检索。
学术关联： Lewis 等人（2020）证明，RAG 架构通过将知识检索与语言生成分离，在不重新训练模型的情况下显著减少事实性错误 [⁴]。knowledge/ 目录正是知识检索层的工程化实现。
7. `configs/` — Agent 的"控制面板"
职责： 管理模型参数、工具权限、环境变量，支持多环境部署。
文件 | 内容 |
model-settings.yaml | 模型参数（温度、top-p、上下文窗口） |
tool-permissions.yaml | 工具权限：哪些可调用、哪些禁止 |
env.example | 环境变量模板 |
agent-profile.json | Agent 档案：元信息配置 |
一句话： configs/ 把"可变项"从"不变项"中分离出来——改配置不改代码，这是工程化的基本功。
学术关联： 在 OWASP Top 10 for LLM Applications 中，LLM01（Prompt Injection）和 LLM08（Excessive Agency）都直接与工具权限配置相关 [⁵]。tool-permissions.yaml 通过最小权限原则限制 Agent 的工具调用范围，是安全的第一道防线。
8. `logs/` — Agent 的"黑匣子"
职责： 记录执行历史，用于调试、优化和合规审计。
文件 | 内容 |
run-history.md | 执行历史：每次任务的完整流程 |
error-trace.md | 错误追踪：完整的调用栈 |
feedback-record.md | 反馈记录：用户或系统对输出的评价 |
metrics-report.md | 指标报告：质量、延迟、成本 |
一句话： 你无法改进你看不见的东西。logs/ 是可观测性的底线。
学术关联： Agent 可观测性是生产级部署的核心要求。OWASP LLM10（Unbounded Consumption）强调了对 Agent 行为进行持续监控和审计的必要性 [⁵]。logs/ 目录不仅是调试工具，更是合规审计的数据基础。
三、入口文件：两个"导航"
`README.md` — 项目说明书
包含：项目概述、安装方法、使用规范、维护协议。任何人接手项目，第一眼就看它。
`agent-index.md` — 文件索引
整个项目的"地图"。新加入的开发者可以通过它快速定位任何文件。它记录了目录导航、快速查找路径和模块间依赖关系。
一句话： README 告诉你是谁，agent-index 告诉你去哪找。
四、八个模块的协作全景
把这八个目录串起来，就是一个完整的 Agent 执行链路：
用户输入 ↓ prompts/（解析意图，确定行为边界） ↓ memory/（加载历史上下文） ↓ workflows/（选择执行流程） ↓ skills/（匹配具体能力）←→ knowledge/（检索外部知识） ↓ tools/（调用外部工具） ↓ configs/（权限检查，参数控制） ↓ logs/（记录执行过程） ↓ 输出结果
每一步都有明确的职责归属，每一步都有可追溯的记录。 这就是工程化。
五、写在最后
很多人觉得 Agent 工程化是"大厂才需要的东西"。错了。
当你的 Agent 项目超过 3 个文件，当你开始同时调试 prompt、工具调用和记忆系统，当你需要让另一个人接手你的项目——目录结构就是你最好的文档。
八个目录，两个入口文件。不多不少，刚好够用。
• prompts/ 定边界，memory/ 管记忆，tools/ 做执行
• workflows/ 编排流程，skills/ 封装能力，knowledge/ 补知识
• configs/ 控参数，logs/ 留痕迹
• README.md 和 agent-index.md 是入口
这套结构不是唯一的答案，但它是一个经过了工程验证的起点。先有结构，再有代码——这才是 Agent 工程化的正确打开方式。
参考文献：
1. Brown, T., et al. (2020). Language Models are Few-Shot Learners. NeurIPS 2020. arXiv:2005.14165
2. Yao, S., et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629
3. Sumers, T., et al. (2024). Cognitive Architectures for Language Agents (CoALA). TMLR 2024. arXiv:2309.02427
4. Lewis, P., et al. (2020). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS 2020. arXiv:2005.11401
5. OWASP Top 10 for LLM Applications (2025). LLM01: Prompt Injection, LLM08: Excessive Agency, LLM10: Unbounded Consumption. genai.owasp.org
评论区聊聊：你的 Agent 项目现在有几个文件？目录结构乱不乱？有没有踩过"改一行 prompt 崩了整条链路"的坑？