16-模块三-AI编码规范体系第16讲-AGENTS.md 深度解析 - 如何写出让 AI 生成高质量代码的规范文件

模块三-AI编码规范体系 | 第16讲：AGENTS.md 深度解析 - 如何写出让 AI 生成高质量代码的规范文件

开场：从“提示词即兴发挥”到“可版本化的协作契约”

如果你用过 Cursor、Copilot、Codex CLI 或 Windsurf，你一定经历过同一种挫败：模型明明懂 Python、懂 FastAPI，却在你项目里写出 跨层 import、把 SQL 写进路由、把密钥硬编码进仓库，或者跑出一套你团队根本不用的测试命令。问题往往不在模型能力，而在于 项目上下文没有被结构化地喂给智能体。人类新同事入职会读 README、会看 CI、会问导师；AI 同事也需要一份“入职手册”，而且要 机器可读、人类可审、Git 可追踪。

AGENTS.md 正在成为这类手册的跨工具表达：它由 Linux Foundation 旗下的 Agentic AI Foundation（AAIF，2025 年 12 月前后推动公开） 倡议，目标是把“代理式开发（agentic coding）”所需的 构建/测试命令、代码风格、架构边界、PR 规范、安全红线、常见坑 收敛到一个根目录 Markdown 文件里，让不同厂商的编码代理都能在同一入口读取。支持面已在快速扩张：OpenAI Codex CLI、GitHub Copilot、Cursor、Windsurf、Amp、Devin 等工具或工作流中，都能看到“读取 AGENTS.md / 类似约定”的实践落地（具体启用方式随版本变化，以各工具文档为准）。

本讲是 CodeSentinel（Python + FastAPI + LangChain 的 AI 驱动代码审核与架构治理平台）在模块三的起点：我们要把 架构师的意图 翻译成 AI 可执行的规范，从源头降低“架构液化（architectural liquefaction）”——也就是系统在 AI 加速下看似交付更快，但边界、依赖方向、错误处理与安全策略被悄悄稀释、最终坍塌的现象。读完本讲，你将能写一份 150 行以内、可执行、可评审 的 AGENTS.md，并理解它如何进入代理的工作流。

全局视角：AGENTS.md 在 AI 工作流中的位置

1. AGENTS.md 信息结构（推荐阅读顺序）

flowchart TB
  A["AGENTS.md<br/>单一事实入口"] --> B["项目元信息<br/>语言/运行时/包管理"]
  A --> C["构建与验证<br/>install / lint / test / typecheck"]
  A --> D["目录与架构<br/>分层/禁止事项"]
  A --> E["编码风格<br/>格式化/命名/日志"]
  A --> F["PR 与提交规范<br/>粒度/描述/检查清单"]
  A --> G["安全与合规<br/>密钥/依赖/输入校验"]
  A --> H["常见坑 gotchas<br/>CI 差异/平台陷阱"]

  B --> I["AI 代理读取"]
  C --> I
  D --> I
  E --> I
  F --> I
  G --> I
  H --> I

  I --> J["生成/修改代码"]
  I --> K["运行测试与静态检查"]
  I --> L["提交 PR 说明与风险"]

2. 工具生态与 AGENTS.md 集成（概念视图）

flowchart LR
  subgraph Tools["编码代理 / IDE 助手"]
    T1["Cursor"]
    T2["GitHub Copilot"]
    T3["Codex CLI"]
    T4["Windsurf"]
    T5["Amp / Devin 等"]
  end

  AG["仓库根目录 AGENTS.md"]

  AG --> T1
  AG --> T2
  AG --> T3
  AG --> T4
  AG --> T5

  T1 --> OUT["一致的代码结构与命令"]
  T2 --> OUT
  T3 --> OUT
  T4 --> OUT
  T5 --> OUT

3. “无规范 vs 有规范”对架构边界的影响

flowchart TB
  subgraph Without["缺少 AGENTS.md"]
    W1["模型凭通用经验猜测"]
    W2["目录结构被随意扩展"]
    W3["错误处理风格不一致"]
    W4["测试命令不可复现"]
  end

  subgraph With["存在高质量 AGENTS.md"]
    P1["明确分层与禁止项"]
    P2["固定验证闭环"]
    P3["安全默认策略一致"]
    P4["PR 描述包含风险面"]
  end

  Without --> X["架构液化：快但碎"]
  With --> Y["架构治理：慢半步但更稳"]

核心原理：AGENTS.md 写什么、怎么写才“对 AI 有用”

1. AGENTS.md 的本质：把隐性团队知识显性化

传统软件工程里，大量规则存在于 老员工的脑子、口头约定、零散的 wiki、某次 code review 的评论区。AI 代理不会自动继承这些，它优先读取：仓库文件、打开的标签页、对话提示词。AGENTS.md 的价值在于：把 最高频、最高风险、最影响自动化 的规则，压缩到代理 默认就会去找 的位置（仓库根目录），并用 可执行 的语句描述。

“可执行”意味着三类内容必须有：

命令级精确：写 uv run pytest -q 而不是“运行测试”；写 ruff check . 而不是“注意代码风格”。
架构级禁止：明确写“presentation 不得 import infrastructure 的具体实现类”，而不是泛泛谈“要分层”。
失败时怎么做：例如“若 Docker 不可用，集成测试应跳过并打印原因”，避免代理在 CI 里钻牛角尖。

2. 关键内容域（建议按优先级排列）

（1）构建 / 测试 / 静态分析命令
这是代理自我纠错的抓手。没有它，模型会瞎猜 pytest 路径、make 目标、或错误地使用全局 Python。请写清：依赖安装、格式化、lint、类型检查、单测、集成测（以及是否需要 Docker）。

（2）代码风格与可读性约定
包括：格式化工具（Ruff/Black）、import 排序规则、日志规范（结构化字段）、异常类型（领域异常 vs HTTP 映射分层）。

（3）项目架构与模块边界
用简短段落 + 列表说明：领域层、应用层、基础设施层、展示层各自放什么；跨层依赖方向；新增功能时应先改哪一层。

（4）PR 与协作规范
例如：提交粒度、描述模板、必须附带的测试结果、哪些变更需要架构评审标签。对 AI 来说，这能显著减少“巨型 diff”。

（5）安全默认
禁止硬编码密钥、禁止记录敏感字段、SQL 必须参数化、对外输入必须校验、CORS 不允许 * 配 credentials（按你项目真实策略写）。

（6）gotchas（团队踩坑）
例如 Windows 路径、Poetry vs uv、pre-commit 与 CI 版本不一致等。gotchas 是 AGENTS.md 里 性价比最高 的部分：一两行就能避免代理反复试错。

3. 最佳实践：短、纯 Markdown、可审查、可版本化

控制在约 150 行以内：超过后建议拆到 docs/ 并在 AGENTS.md 里给链接；根文件保持“代理必读摘要”。
纯 Markdown：避免复杂宏；标题层级稳定（## 为主要章节），方便工具解析。
可操作的祈使句：用“必须 / 不得 / 优先”而不是散文。
与 CI 对齐：AGENTS.md 里的命令应与 GitHub Actions / GitLab CI 一致，否则代理本地绿、CI 红，信任会崩塌。
纳入 code review：把 AGENTS.md 当作 架构制品，变更要走评审，而不是让某个人私下改两句。

4. AGENTS.md 如何抑制“架构液化”

架构液化的典型症状是：交付速度上升的同时，依赖方向开始绕路、错误处理开始沉默吞异常、测试开始依赖随机全局状态、安全策略开始让位于“先跑起来”。AGENTS.md 不是银弹，但它提供了 低成本的一致性杠杆：

代理每次生成代码前更容易被规则“拉回到主干架构”；
人类评审可以用 AGENTS.md 作为 异议依据（“这条违反 AGENTS.md 第 3 节”比“我感觉不好”更有效）；
规范变更可 diff，可回滚，可审计——这是治理平台（如 CodeSentinel）未来做规则检查器的上游输入。

5. 把规范写成“可测试的句子”：从愿景到验收标准

很多团队的规范文件读起来像企业文化宣言：正确、宏大、但无法判断一段 PR 是否满足。对 AI 代理而言，这种模糊性会被放大——模型会倾向选择最短路径完成任务。把规范改写成 可测试句子，能显著降低歧义。下面给出三组对照，建议你直接迁移进 AGENTS.md。

（1）愿景式 vs 可测试式

愿景式：“我们要保持良好的架构分层。”
可测试式：“除 app/infrastructure/__init__.py 的装配导出外，任何 app/presentation/**/*.py 不得出现 sqlalchemy 或 redis 的 import。”

第二条虽然看起来“硬”，但它让评审工具、grep、以及代理自检都有了抓手。你也可以在 CI 里用简单脚本守护。

（2）口号式 vs 命令式

口号式：“要注意异常处理。”
命令式：“领域层抛 InvalidTransitionError；应用层不得捕获后吞掉；展示层必须映射为 HTTP 409，并记录 review_id 与 transition 字段的结构化日志。”

注意：命令式并不是要把所有异常类型写死，而是要定义 责任边界：哪里产生、哪里翻译、哪里记录、哪些字段必须出现。

（3）经验式 vs 场景式

经验式：“集成测试可能会不稳定。”
场景式：“当 DOCKER_AVAILABLE=0 时，tests/test_integration.py 必须跳过需要容器的用例，并打印 SKIP: docker not available，不得失败为 ERROR。”

场景式规则直接对应 flaky 的根因：代理在本地反复重试、在 CI 里却失败，本质是环境假设没有写清。

6. 维护策略：谁改、何时改、如何不让文档腐烂

AGENTS.md 最大的敌人是腐烂：第一周写得很认真，三个月后代码早就换了命令，文档还在原地。建议采用“三条铁律”：

谁破坏谁修复：CI 命令变更的 PR，必须同时更新 AGENTS.md；把这一条写进团队的 Definition of Done。
每月五分钟对齐会：负责人打开 CI 配置与 AGENTS.md，逐行比对命令与目录结构，发现漂移立即修。
把 AGENTS.md 当代码评审门槛：不是“顺便看看”，而是必须有第二位评审者确认规范段落仍然真实。

对 CodeSentinel 这种平台型项目，还可以把 AGENTS.md 链接到 架构决策记录（ADR）：当规则来自某次权衡（例如先不用 Outbox、采用先提交再发布事件的教学路径），在 AGENTS.md 用一行指向 ADR 编号即可。代理不一定读 ADR，但人类评审会读，团队记忆也不会丢。

7. 与 CodeSentinel 产品愿景对齐：规范是“可执行的架构意图”

CodeSentinel 的目标是 AI 驱动的代码审核与架构治理。这意味着：规范不仅是给人看的，也是给机器用的。AGENTS.md 在体系里通常扮演 上游意图（intent） 角色，下游可以逐步演化为：

PR 评论模板自动引用相关条目；
静态规则扫描器按条目做 grep/AST 检查；
LLM 在生成修复建议时把条目当作硬约束写进 system prompt。

因此，写 AGENTS.md 时要有意识地区分 “必须遵守” 与 “建议遵守”：必须项用于硬约束；建议项用于风格与可读性。不要把所有愿望都写成必须，否则代理会为了“形式上满足”而产生奇怪代码（例如无意义注释堆砌）。推荐用标签：MUST / SHOULD / MAY，并在团队内统一语义，贴近 RFC 2119 的习惯，但不要求逐字照搬英文。

代码实战：两份完整的 AGENTS.md 示例

1. 通用 Python + FastAPI 项目示例（可直接复制改写）

下列示例刻意保持“常见但严格”的工程习惯：Ruff、pytest、mypy（可选）、分层目录。请按你团队真实命令替换。

# AGENTS.md

## Project
- Language: Python 3.12+
- Framework: FastAPI
- Package manager: uv (preferred) or pip + venv

## Setup
```bash
uv sync
# or: python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

Commands (must match CI)

uv run ruff format .
uv run ruff check .
uv run pytest -q
# optional:
# uv run mypy app

Layout

app/domain/: entities, value objects, domain errors (no IO)
app/application/: use-cases, ports (Protocols)
app/infrastructure/: DB/Redis/HTTP clients implementing ports
app/presentation/: FastAPI routers, request/response models
tests/: mirrors layers; domain tests must not require Docker

Architecture rules

Dependency direction: presentation -> application -> domain; infrastructure implements application ports.
NEVER import infrastructure concrete classes from presentation.
Routers map exceptions to HTTP; no business rules in routers.

Code style

Prefer explicit names; avoid 1-2 char variables except indexes.
Logging: use structured key/value fields; never log secrets or raw PII.
Errors: raise domain errors inside domain; translate at the edge.

Security

No hardcoded secrets. Use environment variables and secret managers.
Validate all external input at boundaries.
SQL must be parameterized; never string-concat SQL with user input.

PR guidelines

Keep PRs small; include commands run + outcomes in description.
If behavior changes, update tests first (or in the same PR).

Gotchas

Integration tests may require Docker; if unavailable, skip with a clear message.


### 2. CodeSentinel 专用 AGENTS.md（贴合本课程贯穿项目）

```markdown

# AGENTS.md — CodeSentinel (AI Code Review & Architecture Governance)


## Mission
CodeSentinel is a Python service for AI-assisted review and architecture governance:
FastAPI for HTTP APIs, LangChain for LLM workflows (as adapters), PostgreSQL for state,
Redis Streams for domain events (teaching stand-in for Kafka/Outbox).


## Setup
```bash
cd codesentinel-clean-lab
python -m venv .venv
.\.venv\Scripts\activate  # Windows

# source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

Verify (local)

ruff format app tests
ruff check app tests
pytest -q

Verify (docker)

docker compose up --build
# Open http://127.0.0.1:8000/docs

Repository layout

app/domain/: aggregates, domain events, invariants (no FastAPI, no SQLAlchemy)
app/application/: use cases + ports (Protocol)
app/infrastructure/: ORM models, repositories, redis publisher, db engine
app/presentation/: FastAPI routers + HTTP error mapping
tests/test_domain.py: pure domain tests
tests/test_integration.py: API tests (may require services)

Non-negotiables

Domain layer imports nothing from outer layers.
Application layer depends on domain + ports only.
Presentation calls use cases; maps domain errors to HTTP.
LLM calls live behind ports/adapters (no raw OpenAI client in domain).

API rules

Use explicit DTO models for request/response.
Return correct status codes: 400/404/409 as appropriate.

Testing rules

New use cases require tests (domain or integration).
Do not assert on exact error message strings unless stable contract.

Security

Never embed API keys in code or tests committed to git.
Redact secrets in logs; avoid logging full prompts if they may contain PII.

PR checklist

ruff check passes
pytest passes
Layering rules respected
Updated docs if public behavior changed

Gotchas

Windows paths: use .\.venv\Scripts\activate
If integration tests fail locally, confirm docker services and ports.


### 3. Before / After：没有 AGENTS.md vs 有 AGENTS.md（代表性差异）

**Before（模型常见“通用最优”但不符合你项目）**  
- 在 `presentation/api.py` 直接 `SessionLocal()` 查库  
- 把业务判断写在路由函数里  
- 用 `print` 调试并留在代码里  
- 测试用 `requests` 打真实外网  
- `except Exception: pass`

**After（在 AGENTS.md 约束下更容易收敛）**  
- 路由只调用 `UseCase`，仓储由 `main.py` 装配  
- 领域规则在聚合根方法里，路由只做翻译  
- 使用统一 logger，字段化上下文  
- 测试分层：领域纯测 + 容器集成测（可跳过）  
- 异常要么转换为领域错误，要么在边界记录并映射 HTTP

### 4. 让代理“愿意遵守”：把验证成本降到最低

代理是否遵守 AGENTS.md，取决于两件事：**能否读到**、**读完后能否低成本自证**。实践中你可以把自证成本写到文档里：例如在“Verify”章节明确最短路径——只改 `domain` 时允许只跑 `pytest tests/test_domain.py`；涉及 HTTP 契约时必须跑集成测试。这样代理不会在每次小改动都启动完整 docker 栈，也不会因为“全量太慢”而跳过验证。

另一个关键是 **错误信息可读**：当分层被破坏时，如果 CI 只输出一行 `ImportError`，代理可能随机尝试改 import。更理想的是在自定义检查脚本里输出：“检测到 `presentation` 引用 `infrastructure`，违反 AGENTS.md 第 4 节，请把依赖下放到应用层端口并在 `main.py` 装配。”这类提示对人类与对模型都更友好。

### 5. 与提示词协同：AGENTS.md 不是替代，而是底座

很多同学习惯在聊天窗口里堆很长提示词。AGENTS.md 的价值在于把 **稳定不变** 的部分从提示词里挪走：项目命令、目录结构、安全默认、分层规则，应当长期留在仓库；提示词只保留 **本次任务** 的变量：需求描述、接口草案、边界条件、性能目标。这样你可以显著减少“每次新开对话都要重复一遍规范”的摩擦。

当两者冲突时，建议明确优先级：**仓库 MUST 大于本次任务说明，大于模型自由发挥**。把这句话写进 AGENTS.md 的结尾，往往能减少模型为了完成临时需求而破坏架构的概率。若临时需求确实要破例，应要求工程师显式写出“破例原因与回滚计划”，否则评审拒绝——这条同样适用于人类开发者。

### 6. 规模化场景：多服务仓库如何写 AGENTS.md

如果你的仓库不止一个 FastAPI 服务，根 AGENTS.md 建议只写 **共性 MUST**（安全、提交规范、通用 Python 版本），然后为每个服务提供链接：`services/review/AGENTS.md`、`services/billing/AGENTS.md`。根文件用表格列出服务入口、端口、启动命令，避免代理在错误目录执行 `pytest`。表格对模型解析也很友好：字段固定、信息密度高。

对于共享库（`libs/common/`），要单独写清楚：它是纯函数库还是允许 IO？是否允许依赖 FastAPI？这些边界一旦模糊，代理很容易把“通用工具”写成“什么都可以往里塞的垃圾抽屉”，最终形成隐式全局依赖，架构液化随之而来。

---

## 生产环境实战：落地清单与治理建议

1. **把 AGENTS.md 放进评审模板**：要求改动架构边界时必须同步更新 AGENTS.md。  
2. **与 CI 同源**：在 CI 里调用与文档一致的命令；若 CI 分 job，在 AGENTS.md 用小节区分“必跑 / 可选”。  
3. **对代理暴露最小秘密**：生产密钥不进仓库；AGENTS.md 只描述“从哪里取 secret”，不写值。  
4. **度量改进**：记录四周内与架构相关的 review 评论数量、返工 PR 比例、测试 flaky 次数；规范迭代要以指标说话。  
5. **与 CodeSentinel 联动（预告）**：下一阶段可把 AGENTS.md 段落抽取为可检查规则（例如禁止 `presentation` import `infrastructure`），由平台自动扫描 PR。

### 1. 多团队协作时的“规范所有权”模型

在企业里，AGENTS.md 往往会遇到 **平台组 vs 业务组** 的拉扯：平台希望统一命令与目录模板，业务希望保留历史包袱。建议采用 **“根文件 + 分包覆盖”** 的组合拳：仓库根 AGENTS.md 写全仓 MUST 规则（安全、依赖方向、CI 命令），子包（例如 `services/review/`）允许增加 SHOULD 规则，但不得与根 MUST 冲突。冲突时以根文件为准，并在评审中显式删除子包里的越权条目。

### 2. 供应商锁定与可迁移性：不要把工具私货写进 MUST

生产落地时常见错误是把某个 IDE 插件、某个厂商专有配置文件路径写成 MUST。结果是：团队一旦更换工具链，文档立刻失真。更好的做法是：MUST 描述 **结果**（例如“必须通过 Ruff 检查”），SHOULD 描述 **推荐工具**（例如“本地可用 Cursor 读取仓库规则”）。工具会变，结果应尽量稳定。

### 3. 观测与复盘：用数据证明 AGENTS.md 真的有用

建议你至少跟踪四类指标，连续观察四周：

- **架构类评论密度**：每百行变更中，与分层、依赖方向相关的评论条数是否下降。  
- **返工率**：同一 PR 被请求修改次数是否下降。  
- **CI 首次通过率**：代理生成提交后第一次 CI 通过比例是否上升。  
- **安全类问题漏出率**：进入主干后才被发现的安全问题数量是否下降。

如果指标没有变化，通常不是 AGENTS.md 无效，而是 **命令未对齐**、**规则不够可测试**、或 **评审没有引用规范**。此时应回到“可测试句子”方法重写条目，而不是简单堆更多文字。

### 4. 与发布节奏对齐：规范变更也要 semver

把 AGENTS.md 的重大变更视作 **对外契约变更**（即便用户是内部开发者与代理）。当 MUST 条目增加或命令切换时：

- 在 PR 描述写清楚迁移指南（旧命令 → 新命令）；  
- 对大团队发布简短公告；  
- 若你使用发布标签，考虑在 release note 里点名“规范变更”。

CodeSentinel 作为治理平台，未来可以把“规范变更事件”也纳入审计：谁改了 MUST、为什么改、关联哪次事故或哪次 ADR。这样 AGENTS.md 不只是文档，而是 **治理链条的一环**。

### 5. 事故复盘模板（可直接贴进 wiki）

当线上出现问题且根因与“代理生成代码偏离架构”相关，复盘建议回答五个问题：

1. AGENTS.md 是否已有明确禁止项？如果没有，补什么 MUST？  
2. 如果有，为什么代理仍违反？是未读取、被提示词覆盖、还是工具未启用？  
3. CI 是否本应拦截？若否，补哪条自动化？  
4. 评审为何漏过？是 diff 太大还是缺少分层视角？  
5. 需要 ADR 吗？这次修复是临时还是长期原则？

把答案回写到 AGENTS.md 的 gotchas，能避免团队第二次踩坑。

### 6. 案例演练：用一次 CodeSentinel 需求走完整闭环

假设产品需求是“新增一个查询审核历史的只读接口”。没有 AGENTS.md 时，代理最常见的路径是：在路由里拼 SQL、顺手加几个 `print`、测试用硬编码 `review_id`。有 AGENTS.md 时，推荐闭环是：

1. 先确认变更落在哪一层：查询若是领域规则的一部分，应在聚合或领域服务表达；若只是投影读取，可用应用层查询用例配合仓储方法。  
2. 在 `application/ports.py` 扩展端口（若需要），在 `infrastructure` 实现，在 `presentation` 暴露路由。  
3. 按文档命令运行 `ruff` 与 `pytest`，若集成测试依赖 docker，按 gotchas 处理跳过策略。  
4. PR 描述写清：命令结果、风险点（例如是否新增数据库索引）、是否需要迁移。

这个闭环的价值在于：它把“架构讨论”落实为 **可重复的工程步骤**。你在评审时不再争论“应该怎么分层”，而是检查 PR 是否逐步满足规范。对 AI 代理来说，步骤化描述比抽象原则更容易遵循。

### 7. 常见问答：澄清对 AGENTS.md 的误解

**问：AGENTS.md 会不会让模型变笨，不敢做合理重构？**  
答：不会，前提是 MUST 写边界而不是写实现。你可以禁止跨层 import，但不应规定“必须用某个类名”。边界清晰时，模型仍有大量设计空间。

**问：我们已经有 README 了，还需要 AGENTS.md 吗？**  
答：README 面向人类访客，通常包含产品介绍与快速开始；AGENTS.md 面向代理与开发者日常验证，强调命令、边界与禁忌。两者可以互相链接，但职责不同。

**问：规范会不会更新太频繁导致噪音？**  
答：把变更分两类：MUST 变更应少而慎重；gotchas 可以频繁补充。团队要学会区分“原则”和“踩坑记录”。

**问：开源项目也要写吗？**  
答：建议写。开源贡献者来源更杂，代理辅助提交也更常见。一份短的 AGENTS.md 能显著降低“贡献很好但不符合工程习惯”的摩擦成本，并让 issue 讨论更聚焦、维护者更省心。

---

## 本讲小结：一张脑图带走

```mermaid
mindmap
  root((AGENTS.md))
    背景
      跨工具入口
      AAIF 推动
      代理式开发
    内容
      命令
      架构边界
      风格
      安全
      PR
      gotchas
    实践
      短
      可执行
      与 CI 对齐
      可版本化
    价值
      降架构液化
      提升一致性
      可审计

思考题

你的团队目前“最常被 AI 写错”的三条规则是什么？把它们改写成 可执行 的 AGENTS.md 条目。
如果 AGENTS.md 与某位资深工程师的口头习惯冲突，你应该以哪一个为准？如何把冲突变成 显式决策 写进文档？
对于单体仓库（monorepo），根目录 AGENTS.md 与子包规范如何分层，才能既不让代理读太多，又不遗漏关键禁止项？

下一讲预告

下一讲进入 多工具规范文件的编写策略：.cursor/rules 的 .mdc 与 YAML frontmatter、Claude Code 的 CLAUDE.md、GitHub Copilot 的 .github/copilot-instructions.md、Windsurf 的 .windsurfrules。我们将以 AGENTS.md 为单一事实来源（SSOT） 的思路，演示如何用脚本同步生成各工具格式，并在 CodeSentinel 仓库里按 domain/、infrastructure/、tests/ 分区配置规则，让不同路径自动激活不同约束。

附录：最小“反例片段”供团队讨论（教学用）

下列代码不应出现在 CodeSentinel 主路径（用于评审演练）：

# BAD: router 直接访问数据库（违反分层）
from sqlalchemy.orm import Session
from fastapi import APIRouter, Depends

router = APIRouter()

@router.get("/reviews/{review_id}")
def get_review(review_id: str, db: Session = Depends(...)):
    return db.execute("SELECT * FROM reviews WHERE id = '%s'" % review_id).fetchone()

应当改为：路由调用 GetReviewUseCase，仓储使用参数化查询，SQL 细节隐藏在 infrastructure。

16-模块三-AI编码规范体系 第16讲-AGENTS.md 深度解析 - 如何写出让 AI 生成高质量代码的规范文件

模块三-AI编码规范体系 | 第16讲：AGENTS.md 深度解析 - 如何写出让 AI 生成高质量代码的规范文件

开场：从“提示词即兴发挥”到“可版本化的协作契约”

全局视角：AGENTS.md 在 AI 工作流中的位置

1. AGENTS.md 信息结构（推荐阅读顺序）

2. 工具生态与 AGENTS.md 集成（概念视图）

3. “无规范 vs 有规范”对架构边界的影响

核心原理：AGENTS.md 写什么、怎么写才“对 AI 有用”

1. AGENTS.md 的本质：把隐性团队知识显性化

2. 关键内容域（建议按优先级排列）

3. 最佳实践：短、纯 Markdown、可审查、可版本化

4. AGENTS.md 如何抑制“架构液化”

5. 把规范写成“可测试的句子”：从愿景到验收标准

6. 维护策略：谁改、何时改、如何不让文档腐烂

7. 与 CodeSentinel 产品愿景对齐：规范是“可执行的架构意图”

代码实战：两份完整的 AGENTS.md 示例

1. 通用 Python + FastAPI 项目示例（可直接复制改写）

Commands (must match CI)

Layout

Architecture rules

Code style

Security

PR guidelines

Gotchas

Verify (local)

Verify (docker)

Repository layout

Non-negotiables

API rules

Testing rules

Security

PR checklist

Gotchas

思考题

下一讲预告

附录：最小“反例片段”供团队讨论（教学用）

16-模块三-AI编码规范体系第16讲-AGENTS.md 深度解析 - 如何写出让 AI 生成高质量代码的规范文件