使用大模型 Agent 开发中常见的文件结构

随着 Claude Code、Open Code 等 AI 编码工具的普及，在项目根目录下配置 AI 约束文件已经成为提高 Agent 编码准确率的“银弹”。

在实际的大模型 Agent 开发或日常 AI 辅助开发中，最常见也最实用的文件结构非 [project_dir]/.agent 目录和 [project_dir]/agent.md 莫属。

标准的 Agent 项目结构

通常长下面这样子，为什么说是通常呢？因为这些属于事实上的行业标准，是一些知名工具的自主规范或者说共识，目前并没有一个像 W3C 或 IETF 那样由国际标准组织颁布的正式官方规范。

项目根目录/
├── .agent/
│   ├── config.json # Agent 的运行参数、模型选择、API 权限
│   ├── memory/     # 存储 Agent 对这个项目的长期记忆或历史交互 Summary
│   └── tools/      # 本地 MCP（Model Context Protocol）工具的自定义脚本
├── agent.md        # 全局 Agent 提示词与行为准则
└── src/

以我们团队当前的项目为例，由于是一个基于 Sofa Boot 2 + JDK 8 的典型企业级后端系统，业务涉及复杂的“保险条款智能解析”，并且推行了 DDD（领域驱动设计）。为了防止 AI Agent 写代码时瞎搞，我们在项目根目录通过 agent.md 制定了铁律。

# Project Agent Instructions

## 1. 项目上下文
- 这是一个基于 Sofa Boot 2 + JDK 8 的后端项目。
- 核心业务：保险条款智能解析系统。
- 各模块描述：[此处省略...]

## 2. 架构与规范
- 必须遵守 DDD（领域驱动设计）规范。
- 所有 API 返回值必须包裹在 `Result<T>` 中。

## 3. Agent 行为守则
- 在修改任何 Entity 之前，必须先检查对应的 Database Schema。
- 禁止未经允许引入新的第三方 Maven 依赖。
- 经过询问添加的 Maven 依赖必须预先在 parent pom.xml 中声明。

团队协作中的“痛点”

有了这个文件，AI 确实变聪明了。但随之而来的是一个让人无比头痛的团队协作问题：

经常有其他同事令AI本地修改 agent.md，然后直接提交推送，直接覆盖了公共的规范。

沟通了多次“不要覆盖公共 agent.md”，大家口头答应，但实际提交时还是经常顺手把这个文件一起 commit 掉了，令人头痛。

解决办法：建议各位使用 .agent/developer.md ，在 .gitignore 中把 .agent/developer.md 或整个 .agent/ 目录配上。同事们可以在这个动态文件夹里写自己的个人偏好、当前开发任务的局部上下文。

AI Agent（如 Claude Code）在运行时会同时读取这两个文件，既保证了公共底线，又给了个人自由。

上述痛点也就是本文的由来，自己先行记录下，然后例行周会宣讲该内容。