引言
当项目同时包含 Agent 应用和管理后台,且希望 AI Agent 能稳定参与迭代时,目录结构的设计目标会发生根本变化。传统目录结构服务的是"人类开发者的协作与长期维护",而 AI 稳定迭代的目录结构服务的是"Agent 的上下文获取成本与修改边界约束"。两者不是深浅之别,而是优化目标不同。
本文从目录结构设计出发,说明它与传统编程开发所需目录结构的差异点、差异的成因,以及复用问题如何在新结构下得到解决。
一、总体结构:双应用 + 共享契约 + Agent 操作层
采用 monorepo 风格的工作区,将 Agent 应用与管理后台物理隔离,但共享类型与基础组件。根目录放置 Agent 的"操作入口",使其无需遍历全仓即可理解项目规则。
text
project-root/
├── AGENTS.md # Agent 唯一入口:技术栈、命令、目录安全边界
├── .agent/
│ ├── skills/ # 可复用操作流程(新增页面、改路由、跑验证)
│ ├── specs/ # 当前迭代的验收标准(按 feature 分文件)
│ └── contexts/ # 只读上下文:路由表、菜单树、组件清单快照
├── apps/
│ ├── agent-web/ # Agent 用户侧应用
│ └── admin/ # 管理后台
├── packages/
│ ├── shared-types/ # 跨应用共享的 API 类型与领域模型
│ ├── ui-core/ # 无业务逻辑的基础组件(Button、Modal、Table)
│ └── request-client/ # 统一请求实例、错误码映射、拦截器
├── scripts/
│ └── verify # 唯一验证入口:typecheck + lint + test + build
└── pnpm-workspace.yaml
设计证明 :Agent 在修改代码前需要知道"路由怎么注册、组件放哪里、验证命令是什么"。如果这些信息分散在各个 src 目录里,Agent 每次都要重新推断,容易产生不一致的改动。根目录的 AGENTS.md 配合 .agent/ 目录,相当于给 Agent 一张地图和一套可执行的检查清单,而不是让它靠猜测工作。
Agent 应用目录:会话状态与工具调用分离
Agent 应用的特殊性在于:它既有传统前端 UI,又有会话管理、工具调用渲染、流式响应处理等逻辑。目录需要让 Agent 能清晰区分"纯展示"与"有副作用的状态逻辑"。
text
apps/agent-web/src/
├── app/ # 路由与页面组装
│ ├── (chat)/ # 会话主界面
│ ├── (history)/ # 历史会话
│ └── layout.tsx
├── features/
│ ├── conversation/ # 会话域:消息列表、输入框、流式渲染
│ │ ├── components/
│ │ ├── hooks/ # useStreamingResponse, useMessageQueue
│ │ └── stores/ # 会话状态
│ ├── tools/ # 工具调用渲染
│ │ ├── registry.ts # 工具名 → 渲染组件的映射表
│ │ └── renderers/
│ └── artifacts/ # Agent 产出物预览
├── lib/
│ ├── agent-client/ # 与 Agent 后端通信的客户端(SSE/WebSocket)
│ └── guardrails/ # 前端侧安全兜底:输出过滤、超时处理
└── shared/
设计证明 :Agent 应用最易出问题的地方是"工具调用渲染"与"会话状态"的耦合。将 tools/registry.ts 作为唯一注册点,Agent 新增一个工具渲染器时,只需在 registry 中加一行映射,而不需要改动会话主流程。lib/agent-client 集中处理流式协议,避免每个 feature 各自实现一套 SSE 解析,降低迭代时的连锁风险。
管理后台目录:按领域拆分,限制共享扩散
管理后台的迭代频率通常高于 Agent 应用,但它的变更不应影响 Agent 应用的稳定性。通过 packages/ 的依赖方向约束来实现:管理后台可以依赖共享包,但共享包不能反向依赖管理后台。
text
apps/admin/src/
├── app/
│ ├── (dashboard)/
│ ├── (agent-config)/ # Agent 配置管理(模型、提示词、工具权限)
│ └── (audit)/ # 审计日志、调用记录
├── domains/ # 按业务领域拆分,每个域自包含
│ ├── agent-config/
│ │ ├── api/
│ │ ├── components/
│ │ └── hooks/
│ ├── audit-log/
│ └── user-management/
├── components/ # 仅 admin 使用的布局组件
└── lib/
└── permissions/ # RBAC 权限判断
设计证明 :管理后台常见的失败模式是"所有业务组件堆在 components/ 下,半年后没人知道哪个组件属于哪个功能"。按 domains/ 拆分后,每个域的边界清晰,Agent 在修改"Agent 配置"相关页面时,只需关注 domains/agent-config/,不会误改审计日志的代码。
二、Agent 操作层的具体约定
目录之外还需要几条硬性规则,写在 AGENTS.md 中:
唯一验证入口 。scripts/verify 必须存在且可执行,Agent 完成任何修改后只运行这一条命令。内部按顺序执行 typecheck、lint、相关包的 test、build。验证失败则不得提交。
路由与菜单的快照机制 。管理后台的菜单和权限路由通常由后端动态返回,Agent 在本地开发时看不到全貌。在 .agent/contexts/ 下放置一份从开发环境导出的路由/菜单快照,Agent 修改路由相关代码前先读这份快照,避免凭空编造路由名或权限码。
禁止 Agent 修改的目录 。packages/shared-types/ 中的类型由后端契约决定,Agent 不应自行修改。如需新增类型,必须在 .agent/specs/ 中说明需求,由人工确认后更新,或通过代码生成从后端 schema 产出。
每轮迭代的 Spec 落盘 。不要让 Agent 仅凭聊天记录工作。每个迭代任务在 .agent/specs/ 下建一个 markdown 文件,写清:涉及哪个应用、预期行为、验收命令、禁止触碰的目录。Agent 开始前读 spec,结束后对照 spec 自检。
跨应用契约类型统一 。管理后台中"Agent 配置"模块的接口返回结构,与 Agent 应用运行时实际读取的配置结构,往往存在细微差异。将这类跨应用契约类型统一放在 packages/shared-types/agent-config.ts,两端都从这里导入。管理后台改了字段,TypeScript 会立刻在 Agent 应用的消费处报错,防止"后台改了配置但前端运行时解析失败"这类隐性破坏。
三、与传统目录结构的差异点及成因
差异的根源在于:传统目录结构服务的是"人类开发者的协作与长期维护",而 AI 稳定迭代的目录结构服务的是"Agent 的上下文获取成本与修改边界约束"。
1. 根目录多了"Agent 操作入口层"
传统项目根目录通常是 src/、public/、package.json、README.md。README 写给人看,格式自由,Agent 读它要猜测哪些是规则、哪些是说明。
AI 友好结构增加了 AGENTS.md 和 .agent/ 目录。AGENTS.md 是机器可解析的规则文件:命令、安全边界、禁止修改的目录,条目化、无歧义。.agent/skills/、.agent/specs/、.agent/contexts/ 把"操作流程""本轮验收标准""路由菜单快照"从聊天记录和人的记忆里落盘成版本化文件。
成因:人类开发者可以通过口头沟通、Code Review、团队惯例传递这些信息。Agent 没有这些隐性渠道,每次会话都是冷启动,所以必须把隐性知识显性化、文件化。
2. 验证入口从"多个脚本"收敛为"唯一命令"
传统项目 package.json 里常有 dev、build、test、lint、typecheck 多个脚本。人类知道改完代码该跑哪几个,Agent 不知道,容易漏跑或跑错顺序。AI 友好结构要求 scripts/verify 作为唯一验证入口。
成因:人类会自己判断验证顺序,Agent 不会。传统项目没有动力把"验证的确定性"做到这个程度。
3. 目录拆分依据从"技术分层"转向"修改边界"
传统前端常见 components/、hooks/、utils/、services/ 按技术类型分层。这对人类友好,因为人找东西靠"这是组件还是工具函数"的直觉。
但对 Agent 而言,按技术分层意味着一次业务修改要横跨多个目录。改"Agent 配置"功能时,组件、hook、接口、类型分散在各处,Agent 必须理解整个项目的技术分层惯例才能改对,上下文成本高,且容易漏改某一层。
AI 友好结构改用 features/ 或 domains/ 按业务领域自包含。Agent 改一个功能时,修改范围收敛在一个目录内,边界清晰。
成因:传统分层优化的是"人类按类型检索",AI 结构优化的是"按修改范围隔离"。
4. 共享包有了"依赖方向约束"
传统 monorepo 也会抽 packages/shared,但依赖方向往往靠约定,偶尔出现共享包反向引用业务代码也没人拦。
AI 友好结构把依赖方向变成硬约束:packages/ 只能被 apps/ 依赖,不能反向依赖;shared-types/ 由后端契约决定,Agent 不得自行修改。
成因:Agent 缺乏"这个改动会不会造成循环依赖"的全局判断力,一旦共享包被污染,所有应用一起坏。传统项目靠人的架构意识兜底,AI 项目必须靠目录和规则兜底。
5. 跨应用契约类型被提升为独立包
传统项目里,管理后台和用户端共享的类型常放在某一端的 types/ 下,另一端 import 过来,或各写一份靠联调对齐。AI 友好结构把跨应用契约提升到 packages/shared-types/,两端都从这里导入。
成因:Agent 改代码时不会主动想到"另一端还在用这个字段"。传统项目靠联调和测试发现这类问题,AI 项目靠类型系统在编译期拦截。
6. 快照文件成为目录的一部分
传统项目里,后端动态返回的菜单、权限路由,前端开发时靠登录开发环境查看,没有落盘习惯。AI 友好结构在 .agent/contexts/ 下放路由/菜单快照。
成因:人类开发者打开浏览器就能看到菜单,Agent 看不到运行时状态,只能靠快照文件补上这个信息差。
差异对照表
| 维度 | 传统目录结构 | AI 稳定迭代目录结构 |
|---|---|---|
| 服务对象 | 人类开发者 | Agent + 人类 |
| 知识载体 | 口头沟通、惯例、Code Review | 版本化文件(AGENTS.md、specs、快照) |
| 拆分依据 | 技术类型分层 | 业务领域自包含(修改边界) |
| 验证方式 | 多脚本、人判断顺序 | 唯一命令、固定顺序 |
| 依赖约束 | 靠架构意识 | 靠目录规则硬约束 |
| 契约同步 | 联调、测试发现 | 共享类型包、编译期报错 |
本质:AI 友好目录结构把一部分"人的职责"转移给了"项目结构本身"。传统结构的稳定性依赖人类开发者的隐性知识和主动判断,Agent 没有这些,所以必须把隐性知识显性化、把判断规则固化成目录和文件。
四、复用怎么办
按领域自包含最容易被质疑的点是:难道每个域都复制一份组件?答案是:复用没有消失,而是被重新分层了------复用发生在"稳定的下层",域内自包含的是"易变的业务组合"。
复用的三个层次
第一层:无业务语义的基础件 → packages/ui-core/ Button、Modal、Table、Form 控件。不依赖任何领域状态,接口稳定,变更频率低。Agent 可放心复用,因为契约由 props 定义。
第二层:跨应用的契约与客户端 → packages/shared-types/、packages/request-client/ API 类型、错误码映射、统一请求实例。这是"逻辑复用"最该发生的地方------请求拦截、鉴权、错误处理只写一次。
第三层:域内的业务组合 → features/xxx/ 或 domains/xxx/ 会话消息列表、工具调用渲染器、Agent 配置表单。这些是"业务组装",复用范围通常就在本域内。域内组件默认不跨域复用,除非被证明稳定。
跨域复用:提升,而不是复制
当两个域都需要同一个业务组件时,传统做法是挪到公共 components/。AI 友好结构的做法是提升(promote):
- 先在本域内存在,被第二个域引用时不直接跨域 import,先评估是否已剥离业务语义。
- 若只依赖 props、不依赖特定域状态和接口,提升到
packages/ui-core/或新建packages/ui-business/。 - 若仍带业务语义,提升到
packages/下按业务命名的包,而不是塞回某个域的目录。
复用是被"证明"出来的,不是被"预设"的 。传统项目常见的失败是过早抽象------建一个巨大的 components/,谁都能往里放,半年后没人知道哪个组件稳定。提升机制让每个共享件都有明确的"晋升记录",Agent 在 packages/ 里看到的就是已被验证的稳定件。
逻辑复用的两类处理
无业务状态的工具逻辑 (日期格式化、防抖、SSE 解析、权限码匹配)→ packages/utils/ 或 packages/request-client/。纯函数化,复用零风险。
带业务状态的 hooks (useStreamingResponse、useMessageQueue、useAgentConfigForm)→ 留在域内 features/xxx/hooks/。这类 hook 依赖本域的状态管理和接口,强行提升会把业务状态泄漏到共享层。如果两个域都要用,说明它们共享同一套业务模型,应考虑是否该合并域,而不是抽公共 hook。
硬规则:packages/ 下的代码不得 import apps/ 下的任何东西。依赖方向单向,保证共享层纯净。Agent 想"图省事"把业务 hook 提到公共包时,这条规则会阻止它。
Agent 如何知道"该复用哪个"
在 .agent/contexts/ 下放置组件清单快照:
text
.agent/contexts/component-registry.md
内容不是全量组件列表,而是分层清单:
packages/ui-core/下有哪些基础组件、各自 props 契约一句话说明packages/下有哪些业务共享包、适用场景- 各域内有哪些"已标记为可提升候选"的组件
Agent 开始任务前读这份快照,就知道"消息气泡组件已存在于 conversation 域,不要新建""日期格式化在 packages/utils 里,直接 import"。快照可由脚本生成(扫描导出 + 读注释),避免手工维护过期。
复用场景对照表
| 复用场景 | 传统做法 | AI 友好做法 |
|---|---|---|
| 基础组件 | 放全局 components/ |
放 packages/ui-core/,契约稳定 |
| 业务组件跨域用 | 直接挪到公共目录 | 先证明稳定,再提升到 packages/ |
| 业务 hook | 常被抽到全局 hooks/ |
留在域内,跨域用说明该合并域 |
| 工具函数 | utils/ 大杂烩 |
按职责进 packages/utils/ 或 request-client |
| Agent 找复用 | 靠人告知或搜索 | 读 .agent/contexts/ 组件清单快照 |
结论
AI 友好结构不是不要复用,而是把复用从"空间上的集中"改成"分层上的收敛" 。基础件和契约在 packages/ 里集中复用,业务组合在域内自包含、按需提升。
这样做的代价是提升时多一步评估,收益是 Agent 每次改代码时,修改范围和可复用件都是确定的------它不需要理解整个项目的抽象习惯,只需要读快照和遵守依赖方向。传统结构的复用依赖人的判断力,AI 结构的复用依赖目录规则和快照文件,把"该不该抽公共组件"这个判断从人的经验转移成了可执行的流程。
一句话概括:AI 友好目录结构的核心,是把隐性知识显性化、把判断规则固化成文件、把修改边界收敛到目录,让 Agent 在确定的范围内稳定迭代。