Agent 上下文规范——用 AGENTS.md 让 AI 理解项目全貌

编程领域的 Agent 基座落地

如果你读过本书前言中关于 Qoder Agent 基座的介绍，你已经知道 Qoder 是一个四层架构的 Agent 基座平台。

现在，我们把那套架构聚焦到编程领域：

编程领域的 Agent 基座架构

这张图对应本书第二部分的内容体系：

层	编程领域的对应	对应章节
Harness 约束层	编码规范 Rule + 架构约束 + Memory 经验沉淀	06 Rule · 07 Memory · 08 Harness
工具体系	Skill 技能包 + MCP 工具 + 内置工具	05 Skill 技能包
领域子 Agent	CodeReview Agent / 架构分析 Agent / 测试 Agent	02 Plan · 04 Agent 系统
Agent 基座	工作区 AGENTS.md 定义项目架构和规范	本章（01 Agent 上下文规范）

本章要讲的就是第一层——Agent 基座在编程领域如何落地。

具体来说就是：怎么用 AGENTS.md 告诉 AI 你的项目架构怎么分层、代码怎么命名、工具库有什么、规则和技能有哪些。

后面的章节会逐层深入——Skill 讲工具体系、Rule 和 Memory 讲 Harness 约束层、Agent 系统讲子 Agent。

一个朋友的困境

不久前一位朋友问我一个问题：

"每次搞一个新功能，AI 很少去扩展已有的代码，全是新增。架构它也不懂，垃圾代码堆了一堆。怎么让 AI 整体考虑系统的架构？"

这几乎是每个深度使用 AI 编码的人都会遇到的瓶颈。

他的问题不在 AI 本身——Claude、GPT、DeepSeek，哪个模型都不差。问题在于：AI 每次启动新会话时，对你的项目一无所知。

它不知道项目是干什么的，不知道代码怎么组织的，不知道有哪些现成的工具函数，不知道命名规范是什么。它只能靠训练数据里的"通用经验"去猜——猜对了是运气，猜错了就是"又写了一套轮子"。

这个问题有一个非常具体的解决方案：AGENTS.md。

AGENTS.md 的本质

Qoder 每次新建会话时，会自动加载工作区 .qoder/AGENTS.md 文件，将其注入到 AI 的系统提示词中。

这个机制不是我发明的——它来自 Claude 的项目定义功能。Qoder 把它更系统化了：每个工作区都可以有自己的 AGENTS.md，且每次会话自动加载，无需手动指定。

它的本质可以用一句话概括：

工作区 = Agent，AGENTS.md = 这个 Agent 的 System Prompt。

把它跟 Qoder 的其他上下文机制放在一起看，关系非常清晰：

机制	类比	作用范围	解决什么问题
AGENTS.md	入职第一天发的"公司介绍手册"	整个工作区	项目全貌、架构、规则索引
Rule	部门具体的操作 SOP	特定文件或模式	编码约束，怎么写代码
Skill	"你会用什么工具"	特定命令触发	能力注入，重复性工作自动化
Memory	"你之前做过什么"	跨会话	经验回顾，避免重复犯错

Qoder 四大上下文机制

Rule 管的是"代码怎么写"，Skill 管的是"有什么能力可用"，Memory 管的是"历史经验"。但三者都缺一个最基础的东西——这个项目是谁、在干什么、怎么组织的。这就是 AGENTS.md 的职责。

没有 AGENTS.md，Agent 就像一个空降兵——能力很强，但不知道这个团队怎么运作。它只能用自己的"出厂设置"（训练数据的通用模式）来写代码，而这套出厂设置来自 GitHub 上成千上万个不同项目，不是你的项目。

AGENTS.md 的核心作用就是覆盖 AI 的出厂设置。

AGENTS.md 应该包含什么

一个有效的 AGENTS.md 通常包含以下内容。注意顺序很重要——越宏观的信息越靠前，越具体的信息越靠后：

1. 项目简介

用一两句话说清楚这个项目是干什么的。关键点不是"美化的产品介绍"，而是让 AI 知道这个系统的业务边界——它在解决什么问题，核心能力是什么。

2. 系统架构

这是 AGENTS.md 中最核心的部分。需要描述：

分层结构：系统分成哪几层，层之间的调用方向
依赖规则：哪些层可以调用哪些层，禁止反向依赖和跨层调用
核心约定：如主键类型、异常处理策略、依赖注入方式

AI 有了架构信息之后，每次新增功能才知道"代码该放哪一层"。

3. 命名规范

AI 有一个非常顽固的坏习惯——每写一个模块就发明一套新的命名风格。今天叫 PluginCreateRequest，明天叫 createPluginDto，后面又变成 plugin_creation_req。

命名规范就是要告诉 AI：这个项目里，每类文件应该叫什么名字。

通常按层级/类型列出命名模板和示例即可。

4. 目录结构

不需要把整个文件树列出来——AI 有工具可以自己查看。但需要告诉 AI 项目是按什么逻辑组织代码的。例如：

后端按什么分层（Controller → Service → Repository）
前端按什么组织（pages → components → hooks → api）
测试放在哪个目录
文档放在哪个目录

有了这个信息，AI 新增文件时才知道"应该放在哪"。

5. Rule 索引

如果你的项目 .qoder/rules/ 目录下有多条 Rule，需要在 AGENTS.md 中列出每条 Rule 的用途。这不是 Rule 本身的定义（Rule 已经有了），而是一个索引目录，让 AI 知道"有哪些 Rule 可用"。

AI 在编码时会在 AGENTS.md 中看到 Rule 索引，然后主动去加载对应文件。

6. Skill 索引

同样，列出 .qoder/skills/ 下有哪些 Skill，每条的命令和用途。AI 知道有什么能力可用，在合适的场景才会主动调用。

7. 基础工具库索引

这是最容易被忽略但价值最大的部分。AI 不知道项目里已经有哪些工具函数时，每遇到一个新需求就自己写一个——结果就是同一个功能被不同会话重复实现了三五遍。

需要列出项目中的工具类/扩展方法，每个类的核心功能。AI 看到后，遇到类似需求时就知道"这个已经有现成的了"。

8. 测试/构建命令

快速执行测试和构建的命令。AI 完成编码后可以自动验证，不需要你手动指挥。

案例：从真实项目的 AGENTS.md 看如何定义上下文

下面是我在 Automator Client 项目中使用的 AGENTS.md。这个项目是一个包含 WPF 桌面客户端和 Web 前端的自动化工具，后端基于 ASP.NET Core 的五层架构。我们逐段拆解它，看每一段解决了 AI 的什么盲区。

第一段：项目简介

markdown

# Automator Client 项目上下文

## 项目简介
Automator Client 是一个桌面端自动化工具，包含 WPF 桌面客户端（Desktop）
和 Web 前端（Web），后端基于 ASP.NET Core + Coze 五层架构。

解决的问题：AI 知道这个项目的身份。介绍中的关键词"桌面端自动化工具""WPF 桌面客户端""ASP.NET Core 五层架构"——AI 看到这些词，脑中激活的编码模式就从一个"通用编码模式"切换到了"C# WPF + ASP.NET Core 企业级开发模式"。

如果没有这一句，AI 可能按 Node.js Web 应用的模板来生成 C# 代码。

第二段：系统架构 + 依赖原则 + 命名规范

markdown

## 后端架构（五层）

API 层 (Coze/Api)        — HTTP请求处理、参数校验、响应转换
  → Application 层        — 业务流程编排、VO转换
    → Domain 层           — 核心业务逻辑
      → Repository 层     — 数据库CRUD
        → Model 层        — EF Core 实体定义

### 依赖原则
- **禁止反向依赖和跨层调用**
- API → Application → Domain → Repository → Model
- Application 和 Domain 层只使用实现类，不定义接口
- 不捕获异常，全部向上抛出
- 主键ID 统一使用 int，时间戳使用 DateTime

### 命名规范
| 层级 | 类型 | 示例 |
|------|------|------|
| API | {模块名}Controller | PluginController |
| API | {模块名}{功能名}Request | PluginCreateRequest |
| Application | {模块名}ApplicationService | PluginApplicationService |
| ... | ... | ... |

解决的问题：AI 知道了"代码往哪放、叫什么名字、怎么调用"。

这其实回答了朋友遇到的核心问题——"AI 很少去扩展已有代码"的根因就是 AI 不知道已有的代码是按什么架构组织的。它不知道某个功能应该加到哪一层、什么类名下，就只能新建一个文件。

有了架构描述，AI 在选择"新增还是扩展"时有了决策依据：

如果是新的业务模块 → 在对应层新建类
如果是已有模块的增强 → 找到对应层的已有类，扩展方法

第三段：前端模块结构 + 命名空间

markdown

## 前端模块结构（Rush Monorepo）

### 包命名空间
| 前缀 | 用途 |
|------|------|
| @coze-automation/* | 自动化功能 |
| @coze-common/* | 通用组件 |
| @coze-studio/* | 工作室业务 |
| ... | ... |

### 标准目录结构
frontend/packages/{scope}/{module-name}/
├── src/
│   ├── index.ts              # 主入口
│   ├── api/                  # API 调用层
│   ├── components/           # 页面/组件
│   ├── hooks/                # 自定义 Hooks
│   ├── types/                # 类型定义
│   └── utils/                # 工具函数

解决的问题：AI 知道了前端代码的组织规则。有了命名空间的约束，AI 知道新功能应该属于哪个 scope、放在哪个目录下。

没有这段，AI 可能直接在 src/ 根目录下新建文件，或者自己发明一套目录结构。

第四段：Skill 索引

markdown

## 可用 Skill（/ 命令）
| 命令 | 用途 |
|------|------|
| /requirement | 通用需求文档，自动生成规范命名的 .md 文件 |
| /web-server-requirement | Web.Server 后端完整需求开发 |
| /create-csharp-module | 创建 C# 模块架构，自动生成模板代码 |

解决的问题：AI 知道有什么能力可用。在合适的场景下，AI 会主动建议"这个需求我们先用 /requirement 生成文档"或者"这个模块用 /create-csharp-module 来创建"。

没有这个索引，Skill 就纯粹是人工触发的命令，AI 不会主动利用已有的自动化能力。

第五段：基础类库快速索引

markdown

## 基础类库快速索引

### Framework.Helper
| 类 | 功能 |
|---|------|
| ObjectPropertySetter | 设置对象属性，支持嵌套路径 |
| ObjectPropertyExtractor | 提取对象属性 |
| JsonHelper | JSON 序列化/反序列化，支持蛇形命名 |

### Framework.Extensions
| 类 | 功能 |
|---|------|
| StringExtensions | 字符串分割/提取/修剪 |
| DictionaryExtensions | 字典批量操作/合并 |
| ExceptionExtensions | 异常详细信息打印 ex.Dump() |

解决的问题：这是最容易被忽略但价值最大的部分。AI 不知道项目里已经有什么工具类，遇到一个"提取对象属性"的需求，它不会去用现成的 ObjectPropertyExtractor，而是自己再写一个。

就像你团队里来了一个能力很强的新人，但他不知道你们的工具库里有啥，每次需求都从头造轮子——AGENTS.md 的基础类库索引就是给 AI 的"已有工具清单"。

第六段：测试命令

markdown

## 测试

### 快速执行
web-test                      # 跳过编译直接运行
web-test -Module Coze -Controller WorkflowController -Api TestRun

解决的问题：AI 完成编码后知道怎么验证。写完代码直接跑测试，不需要你一句一句地指挥。

用 AI 生成 AGENTS.md

前面花了大量篇幅讲 AGENTS.md 应该长什么样——项目简介、系统架构、命名规范……但如果你准备手动写这些东西，那就走偏了。

AGENTS.md 不是用手写的，是用 AI 生成的。

为什么让 AI 写比手动写更好

很多人第一次接触 AGENTS.md，会打开编辑器开始敲：

项目简介……嗯我项目是做什么的来着？架构……有五层，但命名规则是啥我记不清了…… 工具类……有哪些 Helper 来着，我去翻翻……

然后写着写着就放弃了——"太麻烦了，回头再说"。

AI 没有这个问题。

AI 可以直接读你的代码——目录结构、分层、命名模式、基类、接口，AI 扫描一遍就知道
AI 比你更清楚自己需要什么——它知道自己的上下文盲区在哪，缺少什么信息就会做出什么错误决策
AI 生成的 AGENTS.md 比人写的更精确——人可能漏掉某个工具类，或者写错命名规则，AI 直接从代码中提取

所以正确的做法是：让 AI 分析项目代码，自动生成 AGENTS.md，你做审查和微调。

四步法

让 AI 生成 AGENTS.md 只需要四步，全部在 Qoder 的对话中完成：

第一步：扫描项目全貌

给 AI 一个指令，让其扫描工作区的目录结构：

请扫描当前工作区的目录结构，列出所有顶层目录和核心模块目录。

AI 会调用工具查看文件树，了解项目的整体布局。

第二步：分析架构

让 AI 读取关键架构文件，提取分层和模块划分：

请读取以下文件，分析项目的架构分层、模块划分、依赖关系：
src/**/Module.cs（模块注册文件）
src/**/Controller.cs（API 入口）
src/**/Service.cs（业务逻辑）
src/**/Repository.cs（数据访问）
src/**/Entity.cs（实体定义）
列出每层的职责、命名模式、依赖方向。

AI 看完这些文件后，能完整还原出项目的分层架构和命名规则。

第三步：梳理 Skill 和 Rule

让 AI 扫描 .qoder/ 目录：

请扫描 .qoder/skills/ 和 .qoder/rules/ 目录，列出所有可用的 Skill 和 Rule，并简述每条的作用。

第四步：识别基础工具库

让 AI 扫描工具类目录：

请扫描以下目录中的文件，列出所有工具类和扩展方法，每个类用一句话描述核心功能：
src/**/Helper/
src/**/Extensions/
src/**/Utils/

AI 读完这些文件后，就能生成完整的基础工具库索引——类名、功能说明——精确到每个方法都有。

实战演示：AI 分析 Automator Client 生成 AGENTS.md

下面用一个真实案例看整个过程。以 Automator Client 项目为例，看看 AI 是如何通过分析代码库来生成 AGENTS.md 的。

第一步：AI 扫描目录结构后，输出

项目顶层目录：
├── Desktop/              # WPF 桌面客户端
│   ├── App/              # 应用入口
│   ├── Framework/        # 基础框架
│   │   ├── Helper/       # 工具类
│   │   └── Extensions/   # 扩展方法
│   └── Integration/      # 集成层
├── Desktop.Server/       # 后端服务
│   ├── Abstractions/     # 抽象层
│   └── Services/         # 服务实现
├── Web.Server/           # Web 后端
│   └── Coze/             # 五层架构
│       ├── Api/          # API 层
│       ├── Application/  # 应用层
│       ├── Domain/       # 领域层
│       └── ...
├── Web/                  # Web 前端
│   └── packages/         # Rush Monorepo

第二步：AI 分析架构文件后，输出

架构分层（五层）：

API 层 (Coze/Api)
  职责: HTTP 请求处理、参数校验、响应转换
  命名: {模块名}Controller
  示例: PluginController

Application 层 (Coze/Application)
  职责: 业务流程编排、VO 转换
  命名: {模块名}ApplicationService
  示例: PluginApplicationService

Domain 层 (Coze/Domain)
  职责: 核心业务逻辑
  命名: {模块名}DomainService

Repository 层 (Coze/Repository)
  职责: 数据库 CRUD
  命名: I{EntityName}Repository / {EntityName}RepositoryImpl

Model 层 (Coze/Model)
  职责: EF Core 实体定义
  命名: {模块名}Entity

依赖方向: API → Application → Domain → Repository → Model
特殊约定:
  - 禁止反向依赖和跨层调用
  - Application / Domain 只使用实现类，不定义接口
  - 不捕获异常，全部向上抛出
  - 主键 ID 统一使用 int

你看，AI 从代码中提取的架构信息，比大多数架构师手动写的还要精确。因为它读的是代码本身，不是记忆。

第三步：AI 扫描 .qoder 目录后，输出

可用 Skill：
- /requirement → 通用需求文档
- /web-server-requirement → Web.Server 后端需求开发
- /create-csharp-module → 创建 C# 模块

可用 Rule：
- early-return → 卫语句，避免深层嵌套
- exception-handling → 异常透明，不吞异常
- no-fallback → 不做兼容性设计
- naming-convention → C# PascalCase，前端 camelCase
- layer-boundary → 禁止跨层引用
- api-response-format → 统一 API 响应格式

第四步：AI 扫描工具类目录后，输出

Framework.Helper:
- ObjectPropertySetter → 设置对象属性，支持嵌套路径
- ObjectPropertyExtractor → 提取对象属性
- JsonHelper → JSON 序列化/反序列化，支持蛇形命名

Framework.Extensions:
- StringExtensions → 字符串分割/提取/修剪
- DictionaryExtensions → 字典批量操作/合并
- ExceptionExtensions → ex.Dump() 打印异常详细信息

完整的 Prompt 模板

如果你在自己的项目上操作，可以直接用这个 Prompt：

请帮我生成当前工作区的 AGENTS.md 文件。按以下步骤执行：
扫描工作区目录结构，列出核心模块和目录组织方式
读取关键架构文件（Controller / Service / DI 注册等），分析项目的分层架构、模块划分、依赖关系和命名规范
扫描 .qoder/skills/ 和 .qoder/rules/，列出所有可用的 Skill 和 Rule 及其用途
扫描工具类 / Helper / Extensions 目录，列出所有基础工具类和扩展方法，每个用一句话说明功能
基于以上信息，先生成 AGENTS.md 的内容大纲，让我确认后再写入 .qoder/AGENTS.md

这个 Prompt 的关键在于：让 AI 先给你看大纲，确认后再写入。 因为 AI 可能会遗漏某些特殊规范，你需要在这个时候补充。

补充特殊规范

AI 从代码中能提取出通用规范（分层、命名、工具类），但有些特殊规范只有你知道：

Web Controller 命名规范：比如所有 Web Controller 必须继承某个基类，或必须放在特定命名空间下
数据库规范：比如所有表必须有 gmt_create 和 gmt_modified 字段，所有查询必须走 Repository 层
接口设计规范：比如请求/响应必须使用统一的包装类，错误码必须走枚举
安全规范：比如敏感字段必须加密存储，日志不能打印用户密码

这些 AI 从代码中看不出来——它能看出"当前怎么写的"，但看不出"这是刻意规定的"。所以你的角色不是"写 AGENTS.md"，而是 "审查 AI 生成的 AGENTS.md，补充只有你知道的规范"。

更新也是 AI 做

项目不是静态的。三个月后加了一层新架构、新增了两个 Skill、重构了工具库——AGENTS.md 也需要同步更新。

方法同样简单：

请根据当前工作区的最新状态，更新 AGENTS.md 中的以下部分：
架构描述是否有变化（扫描架构文件）
Skill 和 Rule 是否有新增或删除（扫描 .qoder/ 目录）
基础工具库是否有变化（扫描 Helper/Extensions 目录）
目录结构是否有调整（扫描顶层目录）
只输出需要更新的内容，没有变化的段落保留原样。

AGENTS.md 的维护成本几乎为零——每次需要更新时，让 AI 重新跑一遍扫描即可。

编写高质量 AGENTS.md 的三条原则

原则一：给 AI 看，不是给人看

这是最核心的认知转换。AGENTS.md 不是项目的 README，不是产品介绍文档。它是写给 AI 的系统提示词。

两者的区别：

维度	README（给人看）	AGENTS.md（给 AI 看）
语言风格	自然语言，可读性优先	结构化，精确性优先
详细程度	高亮关键特性	列出所有约束规则
架构描述	顶层架构图	分层细节 + 命名规范 + 依赖规则
工具库	不列或只列主要	全部列出，精确到类名
价值观	吸引用户	约束 Agent

编写时的检查标准很简单：你自己看会觉得"写得太细了""这些命名规范也要写？"——对了，就是给 AI 看的。

原则二：结构精确，不要模糊表达

AI 擅长理解精确的结构化信息，不擅长从模糊的自然语言中推断。

好：Application 层 → {模块名}ApplicationService
差：Application 层的类名根据模块来命名

模糊表达给了 AI"自由发挥"的空间——而 AI 的"自由发挥"就是"按训练数据的经验来编"，结果就是偏离你的项目规范。

原则三：定期更新，跟项目同步

AGENTS.md 是一个"活的"文件。项目架构变了、加了新的 Skill、新增了工具类——这些都应该同步到 AGENTS.md 中。

一个简单的维护规则：每次新增 Rule 或 Skill 时，顺手打开 AGENTS.md 看一眼索引是否需要更新。

AGENTS.md、Rule、Skill 的关系

三者不是替代关系，是不同层面的上下文注入：

AGENTS.md（宏观）
  ├── 描述项目全貌
  ├── 列出所有 Rule 的索引和用途
  └── 列出所有 Skill 的索引和用途
        ↓
Rule（中观）
  ├── 具体编码约束
  ├── 按文件模式自动触发
  └── 覆盖 AI 的编码天性（嵌套/吞咽/过度设计）
        ↓
Skill（微观）
  ├── 可复用的工作流
  ├── 手动或 AI 主动触发
  └── 封装重复性任务（创建模块/生成文档/部署）

AGENTS.md 是顶层索引，Rule 和 Skill 是具体实现。AI 在 AGENTS.md 中看到"有 ×× 协议"，然后去 .qoder/rules/ 加载具体内容。

回到本章开头的架构图

回顾本章开头那张"编程领域的 Agent 基座架构"图，你现在应该能理解：

AGENTS.md 是 Lead Agent 的 System Prompt——回答了"我是谁、我在做什么、边界在哪"
编程领域的 AGENTS.md 描述的是分层架构、命名规范、工具库索引——这正是本章讲的内容
这套模式不止于编程——自媒体领域的 AGENTS.md 描述的是内容方向和个人IP画像，出书领域的 AGENTS.md 描述的是配图规范和书稿结构

底层逻辑一致：AGENTS.md 回答 AI 进入这个工作区时必须知道的三个问题——"这是谁？"、"这在哪里？"、"有什么规矩？"

Agent 上下文规范——用 AGENTS.md 让 AI 理解项目全貌 ​

编程领域的 Agent 基座落地 ​

一个朋友的困境 ​

AGENTS.md 的本质 ​

AGENTS.md 应该包含什么 ​

1. 项目简介 ​

2. 系统架构 ​

3. 命名规范 ​

4. 目录结构 ​

5. Rule 索引 ​

6. Skill 索引 ​

7. 基础工具库索引 ​

8. 测试/构建命令 ​

案例：从真实项目的 AGENTS.md 看如何定义上下文 ​

第一段：项目简介 ​

第二段：系统架构 + 依赖原则 + 命名规范 ​

第三段：前端模块结构 + 命名空间 ​

第四段：Skill 索引 ​

第五段：基础类库快速索引 ​

第六段：测试命令 ​

用 AI 生成 AGENTS.md ​

为什么让 AI 写比手动写更好 ​

四步法 ​

第一步：扫描项目全貌 ​

第二步：分析架构 ​

第三步：梳理 Skill 和 Rule ​

第四步：识别基础工具库 ​

实战演示：AI 分析 Automator Client 生成 AGENTS.md ​

完整的 Prompt 模板 ​

补充特殊规范 ​

更新也是 AI 做 ​

编写高质量 AGENTS.md 的三条原则 ​

原则一：给 AI 看，不是给人看 ​

原则二：结构精确，不要模糊表达 ​

原则三：定期更新，跟项目同步 ​

AGENTS.md、Rule、Skill 的关系 ​

回到本章开头的架构图 ​

Agent 上下文规范——用 AGENTS.md 让 AI 理解项目全貌

编程领域的 Agent 基座落地

一个朋友的困境

AGENTS.md 的本质

AGENTS.md 应该包含什么

1. 项目简介

2. 系统架构

3. 命名规范

4. 目录结构

5. Rule 索引

6. Skill 索引

7. 基础工具库索引

8. 测试/构建命令

案例：从真实项目的 AGENTS.md 看如何定义上下文

第一段：项目简介

第二段：系统架构 + 依赖原则 + 命名规范

第三段：前端模块结构 + 命名空间

第四段：Skill 索引

第五段：基础类库快速索引

第六段：测试命令

用 AI 生成 AGENTS.md

为什么让 AI 写比手动写更好

四步法

第一步：扫描项目全貌

第二步：分析架构

第三步：梳理 Skill 和 Rule

第四步：识别基础工具库

实战演示：AI 分析 Automator Client 生成 AGENTS.md

完整的 Prompt 模板

补充特殊规范

更新也是 AI 做

编写高质量 AGENTS.md 的三条原则

原则一：给 AI 看，不是给人看

原则二：结构精确，不要模糊表达

原则三：定期更新，跟项目同步

AGENTS.md、Rule、Skill 的关系

回到本章开头的架构图