TiDB 仓库的 AGENTS.md 解析：面向 AI 编码代理的分层策略、验证矩阵与构建契约-育师

TiDB 仓库的 AGENTS.md 解析：面向 AI 编码代理的分层策略、验证矩阵与构建契约

【免费下载链接】tidbTiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.项目地址: https://gitcode.com/GitHub_Trending/ti/tidb

本文以 TiDB（ti/tidb）仓库根目录的 AGENTS.md 为骨架，系统解读这份面向 AI 编码代理（Coding Agent）与人类贡献者共用的"仓库级协作契约"：从 MUST/SHOULD/MAY 策略分层与执行优先级，到Quick Decision Matrix、Task -> Validation Matrix、Bazel 构建门禁（make bazel_prepare）、failpoint/集成测试/RealTiKV 测试策略，以及提交完成前的Ready验证与Agent Output Contract。读完本文，你将理解在 TiDB 这样一个分布式 SQL 数据库仓库中，如何按变更范围选择最小但足以证明正确性的验证集合，并掌握从"开工前检查"到"结束报告"的全流程规范，以及这些规范与docs/agents/*runbook、PLANS.mdExecPlan、.agents/skills/*技能包之间的职责边界。

定位：这份文档管什么，不管什么

仓库根目录的 AGENTS.md 是该仓库面向"在此仓库中工作的代理"（agents working in this repository）的顶层指导文件。它解决的核心矛盾是：TiDB 是一个分布式 SQL 数据库，任何看似微小的改动都可能改变 SQL 语义、一致性或集群行为，因此 AI 代理在仓库内自主编码时，必须有一套可执行、可验证、无歧义的规则来约束其行为。

与其配套的是一套清晰的文档职责边界（这一边界同时写在 docs/agents/README.md 与 docs/agents/agents-review-guide.md 中）：

策略（Policy）只存放在根AGENTS.md，使用规范性的 MUST/SHOULD/MAY/MUST NOT 关键词；
操作细节（Runbooks）存放在docs/agents/*.md，如 docs/agents/testing-flow.md（命令手册）、docs/agents/architecture-index.md（架构索引）、docs/agents/agents-review-guide.md（AGENTS 变更评审指南）、docs/agents/notes-guide.md（组件笔记规则），这些文件只解释或示例化策略，不引入新的策略范围；
组件笔记位于docs/agents/<component>/，例如docs/agents/ddl/、docs/agents/dxf/、docs/agents/executor/、docs/agents/import-into/；
技能包（Skills）维护在.agents/skills目录，作为入口级工作流引用上述 playbook（详见后文"Skills 的组织与职责"）；
大型改动方案（ExecPlan）的格式与要求定义在仓库根目录的 PLANS.md。

从源码仓库可验证：根目录确实同时存在 AGENTS.md 与 PLANS.md，docs/agents/下存在architecture-index.md、testing-flow.md、agents-review-guide.md、notes-guide.md四个顶层 runbook 与ddl/、dxf/、executor/、import-into/四个组件目录；.agents/skills/下存在 9 个技能包（含README.md、tidb-verify-profile/、tidb-bazel-prepare-gate/、tidb-issue-metadata-guard/、tidb-pr-metadata-guard/等），而 docs/agents/README.md 明确要求"保持根AGENTS.md存放策略级要求、docs/agents/存放操作细节"。

目的与优先级（Purpose and Precedence）

AGENTS.md 开篇即定义了规范关键词的语义与优先级规则：

MUST表示强制要求；
SHOULD表示建议，除非存在具体的偏离理由；
MAY表示可选；
根AGENTS.md定义全仓库默认值；如果更深的路径中存在更具体的AGENTS.md，则更深层的文件在其子树范围内具有更高优先级。

这是一个"根默认 + 子树覆盖"的层叠规则，与.gitignore、CODEOWNERS等文件的合并语义类似。设计目的是让各子系统（如pkg/ddl/）可以在不破坏全局契约的前提下补充本模块的特殊要求，同时避免规则碎片化。

五条不可协商原则（Non-negotiables）

AGENTS.md 列出了所有代理都必须遵守的硬性约束：

正确性优先：TiDB 是分布式 SQL 数据库，看似微小的改动也可能改变 SQL 语义、一致性或集群行为；
禁止投机性行为：不得凭空发明 API、默认值、协议行为或测试工作流（"Do not invent APIs, defaults, protocol behavior, or test workflows."）。这条规则与代码风格中"注释应解释非显而易见的意图"的要求相呼应，都是为了防止 Agent 产生未经代码验证的臆断；
最小化 diff：避免无关的重构、大范围改名或纯格式化 churn，除非被明确要求；
留下可验证证据：运行针对性的检查，并报告确切执行的命令；
尊重生成代码产物：不手改生成代码，而应从源输入重新生成。

第 4 条直接支撑了文末的Agent Output Contract（结束报告必须包含确切的验证命令），第 2 条则贯穿全文——包括 AGENTS.md "Notes" 一节中对 DDL 文档的特别声明（见下文）。

仓储本地交互覆盖规则（Agent Interaction Overrides）

AGENTS.md 规定了一条仓库本地（repo-local）的覆盖规则：对于关于定义、缩写词、符号、错误或其他仓库特有术语的简短非代码问题，代理MUST先搜索当前仓库、读取最近的权威本地定义后再作答，回答时以仓库特有意义为先导；只有当本地证据缺失或用户明确要求更广上下文时，才允许使用通用知识。

这条规则在 TiDB 这种词汇高度自研的代码库中非常关键——例如 SQL 语义相关术语、内部缩写等，其权威含义往往只存在于特定包或doc.go中。配套的 docs/agents/architecture-index.md 进一步给出了"从症状到实现"的检索工作流（按 SQL 关键词 / 错误消息 / 变量名定位实现入口，再就近查找测试）。

ExecPlans：大型功能与重构的设计-执行载体

当要编写复杂功能或进行重大重构时，AGENTS.md 要求使用ExecPlan（从设计贯穿到实现），其定义与格式在仓库根目录 PLANS.md 中给出。

ExecPlan 的核心是"可自包含、可执笔落地的活文档"：

非强制要求（NON-NEGOTIABLE）：每个 ExecPlan 必须完全自包含——包含让一个对仓库毫无了解的新手成功所需的全部上下文与指令；必须随进展持续更新；必须产出"可演示的正确行为"而非仅仅源码编辑；必须用平实语言定义非显而易见的术语；
叙事优先：先讲清"为什么"（用户视角的收益与可观察结果），再讲"编辑什么、运行什么、期望什么"；
强制章节：每个 ExecPlan 必须维护Progress、Surprises & Discoveries、Decision Log、Outcomes & Retrospective四类记录，捕捉实现过程中的意外行为、关键决策及其理由，并在里程碑或完成时撰写复盘；
可验证的里程碑：每个里程碑必须能被独立验证，且逐步逼近整体目标；当需求不确定或风险高时，应加入原型（prototyping）里程碑先行验证可行性；
幂等与安全：步骤应可重复而不产生漂移，中断时应给出恢复路径，危险操作应提供回滚/备份指引。

PLANS.md 还规定：若仓库策略（例如AGENTS.md）比本文档更严格，则遵循更严格的策略并记录到方案中。从文件结构看，ExecPlan 是 AGENTS.md"正确性优先、禁止投机"两大原则在大规模改动上的落地工具：当一个改动大到"丢失上下文就会危害正确性或验证完整性"时，把上下文固化到活文档中。

快速决策矩阵（Quick Decision Matrix）

这是 AGENTS.md 中最常用的操作速查表，把"任务类型 → 必须动作"映射成一行行硬规则。原文表格如下，此处完整保留并补充仓库验证信息：

任务	必须动作
新增/移动/重命名/删除 Go 文件、修改既有 Go 文件的 import 段、在既有`_test.go`中新增匹配`func TestXxx(t testing.T)`的顶层 Go 测试函数、修改 Bazel 文件、更新 Bazel 测试目标、或修改`go.mod`/`go.sum`	MUST运行`make bazel_prepare`，并将产生的 Bazel 元数据变更纳入 PR（例如`BUILD.bazel`、`*/.bazel`、`*/.bzl`）
运行包级单元测试	SHOULD运行针对性测试，避免全包运行，除非确有必要（见 docs/agents/testing-flow.md →`Unit tests`）
使用 failpoint 的包内单元测试	MUST在测试前启用 failpoint、测试后禁用（见 docs/agents/testing-flow.md →`Failpoint decision for unit tests`）
录制集成测试（recording）	MUST使用 docs/agents/testing-flow.md →`Integration tests`中的录制命令（不是`-record`；`-record`仅用于显式支持它的单元测试套件）
RealTiKV 测试	MUST后台启动 playground → 运行测试 → 清理 playground/data（见 docs/agents/testing-flow.md →`RealTiKV tests`）
Bug 修复	MUST添加回归测试，并验证"修复前失败、修复后通过"
纯格式（fmt-only）PR	MUST NOT运行高成本的`realtikvtest`；本地编译即可
本地编码迭代（尚未声称完成）	SHOULD使用 .agents/skills/tidb-verify-profile 中的`WIP`验证档，只跑限定范围的检查
声称任务完成 / PR 就绪	MUST使用 .agents/skills/tidb-verify-profile 的`Ready`验证档；若含代码改动则包含`make lint`。在做出 "fixed"、"done"、"all tests pass"、"ready for review"、"ready for PR" 等最终状态声明之前，`Ready`是强制前置条件
创建或更新 GitHub issue	SHOULD使用 .agents/skills/tidb-issue-metadata-guard 以保持 issue 模板与标签卫生
创建 PR 或编辑 PR 元数据	SHOULD使用 .agents/skills/tidb-pr-metadata-guard 以保持 PR 模板、标题范围与 bot 解析的 checklist 段
收尾前	SHOULD先自审 diff 质量
高成本的可选扫描（如`make bazel_lint_changed`、大范围包运行）	MUST仅在变更范围、CI 复现或用户明确要求需要时运行

从 Makefile 可以核实相关目标的存在与语义：bazel_prepare:位于约第 684 行，注释明确写着 "Update and generate BUILD.bazel files. Please run this before commit."；bazel_bin:（约第 753 行）用于以 Bazel 构建 importer/tidb 二进制；bazel_test:（约第 709 行）依赖bazel-failpoint-enable bazel_prepare，用于以 Bazel 跑全部测试；bazel_lint_changed:（约第 906 行）依赖bazel_prepare。矩阵中"纯格式 PR 不跑 realtikvtest"、"failpoint 测试脚本负责自动启用并兜底禁用"等规则，都是为了把验证成本控制在变更范围真正需要的量级上。

Skills 的组织与职责

矩阵多次引用.agents/skills/*，AGENTS.md 对 Skills 的存放与边界做出了明确约定：

仓库级技能统一维护在.agents/skills目录（相对于仓库根 / 当前工作目录），每个技能文件夹内将技能内容与引用材料放在一起，例如.agents/skills/<skill>/SKILL.md与.agents/skills/<skill>/references/；
.github/skills仅保留为迁移备忘路径，不应作为新技能更新的主要位置；
策略属于AGENTS.md；详细的命令 playbook 应放在docs/agents/*；Skills 提供引用这些 playbook 的入口式工作流；
运维类测试/构建技能在 .agents/skills/README.md 中建立索引，避免在多个文档中重复维护易漂移的清单。

这一设计与"Review Gate"（docs/agents/agents-review-guide.md）中的要求完全一致：详细命令不内联复制到AGENTS.md，而是通过链接指向docs/agents/*，保证单一事实来源。

开工前检查清单（Pre-flight Checklist）

在动手改代码之前，AGENTS.md 要求按顺序完成五步：

复述任务目标与验收标准（Restate the task goal and acceptance criteria）；
定位所属子系统与最近的既有测试：依据Repository Map与Task -> Validation Matrix。若目标包存在doc.go，代理必须先阅读该包级文档，再深入实现文件——这是避免臆断包语义的重要前置；
跑测试/构建前先决定前置条件：参考 docs/agents/testing-flow.md 的 failpoint 决策、以及AGENTS.md → Build Flow → When make bazel_prepare is required；
挑选最小且足以证明正确的验证集合，并准备最终报告项（Agent Output Contract）；
若改动了AGENTS.md或docs/agents/下的文档，收尾前遵循 docs/agents/agents-review-guide.md 的清单。

仓库地图（Repository Map，入口点）

AGENTS.md 给出了快速子系统导航（详细映射与测试面以 docs/agents/architecture-index.md 为准），并规定：模块/路径映射发生变化时先更新 architecture-index.md，本段只在顶层入口点变化时才更新。各入口点为：

pkg/planner/：规划器与优化入口；
pkg/executor/、pkg/expression/：SQL 执行与表达式求值；
pkg/session/、pkg/sessionctx/：会话生命周期与运行时语句上下文；
pkg/ddl/、pkg/infoschema/、pkg/meta/：Schema 与元数据管理；
pkg/store/、pkg/kv/：存储与分布式查询接口；
pkg/statistics/：统计信息与估算行为入口；
pkg/parser/：SQL 语法与 AST；
tests/integrationtest/、tests/realtikvtest/：SQL 集成测试与真实 TiKV 测试面；
cmd/tidb-server/：TiDB server 入口。

docs/agents/architecture-index.md 在此基础上提供了跨模块路径：规划器→执行器→表达式对应查询语义；会话/变量→执行器对应可见运行时行为；DDL→Infoschema/Meta→Domain 对应 Schema 生命周期；Store/KV/DistSQL→执行器对应分布式执行。

Notes 规则与 DDL 模块的特殊约束

AGENTS.md 的 Notes 部分首先要求遵循 docs/agents/notes-guide.md（其要点是：组件笔记位于docs/agents/<component>/、就近复用既有目录、超过 2000 行的笔记按功能拆分并更新引用）。

针对DDL 模块（涉及pkg/ddl/与docs/agents/ddl/的改动）另有强约束：

MUST：在pkg/ddl/下进行任何 DDL 改动前/评审时，先阅读 docs/agents/ddl/README.md，并将其作为执行框架的默认地图；
调试参考：可以查阅docs/agents/ddl/*，但不得将其视为权威；在代码/测试中验证前，一律视为"待验证的假设"（避免幻觉与过期假设）；
文档漂移：若实现与docs/agents/ddl/*不一致，必须更新文档使其贴合现实，并在 PR/issue 中明确指出，不得拖延。

这条规则是"禁止投机性行为"原则在 DDL 这一高危子系统的具体化——DDL 改动直接影响 Schema 演进，错误假设代价极高。

构建流程（Build Flow）

何时必须运行`make bazel_prepare`

TiDB 同时维护 Bazel 与 Go 两套构建元数据，BUILD.bazel等文件通常由bazel_prepare自动生成。AGENTS.md 规定在以下任一情形成立时，构建前必须先运行make bazel_prepare：

全新 workspace 或全新 clone；
Bazel 相关文件发生变化（例如WORKSPACE、DEPS.bzl、BUILD.bazel、MODULE.bazel、MODULE.bazel.lock）；
PR 中任何 Go 源文件被新增/删除/重命名/移动；
任何既有 Go 源文件（含*_test.go）的 import 段发生变化；
代码改动在既有*_test.go中新增了匹配func TestXxx(t *testing.T)的顶层 Go 测试函数；
Go 模块依赖变化（例如go.mod、go.sum），包括引入第三方依赖；
Bazel 测试目标更新（例如shard_count变化、测试srcs列表编辑、或tests/realtikvtest/**/BUILD.bazel被修改）；
出现本地 Bazel 依赖/工具链错误。

针对是否达到该门禁的可操作决策清单，使用 .agents/skills/tidb-bazel-prepare-gate。

任务 → 验证矩阵（Task -> Validation Matrix）

矩阵的核心思想是使用能证明正确性的最小验证集合；包级、集成测试与 RealTiKV 的命令细节均位于 docs/agents/testing-flow.md。完整矩阵如下：

变更范围	最小验证
`pkg/planner/**`规则或逻辑/物理计划	针对性 planner 单元测试，必要时更新规则 testdata
`pkg/executor/**`SQL 行为	针对性单元测试 + 相关集成测试（tests/integrationtest）
`pkg/expression/**`内置函数或类型推断	含边界用例覆盖的针对性 expression 单元测试
`pkg/session/**`/ 变量 / 协议行为	针对性包测试 + 针对用户可见行为的 SQL 集成测试
`pkg/ddl/**`Schema 变更	DDL 专项单元/集成测试及兼容性影响检查
`pkg/store/`/`pkg/kv/`存储行为	针对性单元测试；若行为依赖真实 TiKV 则使用 realtikv 测试
Parser 文件（`pkg/parser/**`）	Parser 专用 Make 目标（`make parser`、`make parser_yacc`、`make parser_fmt`、`make parser_unit_test`）及关联单元测试
变更了 tests/integrationtest/t/	录制并核对重新生成结果的正确性（见 docs/agents/testing-flow.md →`Integration tests`）
变更了 tests/realtikvtest/	启动 playground → 运行限定测试 → 强制清理（见 docs/agents/testing-flow.md →`RealTiKV tests`）

测试策略（Testing Policy）

AGENTS.md 在测试上遵循"先按Task -> Validation Matrix选定所需测试面，再从 playbook 中运行限定命令"的原则，并强调使用 .agents/skills/tidb-verify-profile 选择验证档（WIP/Ready/Heavy）；任何最终状态声明前必须先走Ready（触发短语定义于Quick Decision Matrix）。failpoint、集成录制、RealTiKV 生命周期、回归测试等规则均只在此前章节陈述一次，不在本节重复。

具体命令 playbook 在 docs/agents/testing-flow.md 中有完整说明，与策略的关键衔接点如下：

包级单元测试（/pkg/...）默认以-tags=intest,deadlock编译运行：
```
pushd pkg/<package_name> go test -run <TestName> -tags=intest,deadlock popd
```
并明确"-tags=intest,deadlock并不会启用 failpoint"。
failpoint 判定与启用：先在包内检索failpoint.与testfailpoint.（Bazel 场景还需检查BUILD.bazel中的@com_github_pingcap_failpoint//:failpoint依赖）；命中则需启用 failpoint 运行，推荐通过 tools/check/failpoint-go-test.sh 执行：
```
./tools/check/failpoint-go-test.sh pkg/<package_name> -run <TestName>
```
该脚本会自动启用 failpoint、运行go test，并在清理阶段始终禁用failpoint；底层启停路径由 tools/check/failpoint-state.sh 串行化，同一 worktree 中并行的 agent 任务不得直接调用tools/bin/failpoint-ctl。若走 Bazel 则先make bazel-failpoint-enable、测试后make bazel-failpoint-disable；使用make bazel_test时无需单独 enable（其已依赖 enable），但结束后仍需 disable。
集成测试（tests/integrationtest）：测试输入在 tests/integrationtest/t、期望结果在 tests/integrationtest/r，录制命令为：
```
pushd tests/integrationtest ./run-tests.sh -r <TestName> popd
```
命名映射示例：修改了t/planner/core/binary_plan.test，则TestName为planner/core/binary_plan。变更后需人工核对r/下每个 diff 是否符合预期。
RealTiKV 测试（tests/realtikvtest）：适用于需要真实 TiKV/TiUP Playground 行为的情形。标准流程为后台启动 playground、健康检查 PD 端点、跑限定测试、最后强制清理并确认端点不可达：
```
tiup playground --mode tikv-slim --tag realtikvtest & PLAYGROUND_PID=$!
```
```
PD_ADDR=127.0.0.1:2379 curl -f "http://${PD_ADDR}/pd/api/v1/version" until curl -sf "http://${PD_ADDR}/pd/api/v1/version" >/dev/null; do sleep 1; done
```
```
go test -run <TestName> -tags=intest,deadlock ./tests/realtikvtest/<dir>/...
```
```
[ -n "${PLAYGROUND_PID:-}" ] && kill "${PLAYGROUND_PID}" 2>/dev/null || true [ -n "${PLAYGROUND_PID:-}" ] && wait "${PLAYGROUND_PID}" 2>/dev/null || true rm -rf "${HOME}/.tiup/data/realtikvtest"
```
清理完成后需用! curl -sf "http://${PD_ADDR}/pd/api/v1/version"确认 PD 已不可达。docs/agents/testing-flow.md 还给出了带trap cleanup EXIT INT TERM的"清理安全模板"，推荐用于长时间的本地调试；PD 端口被占用时可改用--pd.port 12379或--port-offset 10000，并将PD_ADDR与-args -tikv-path相应替换。纯格式 PR 遵循矩阵规则跳过 realtikvtest。此外tests/realtikvtest/scripts/classic/与tests/realtikvtest/scripts/next-gen/提供替代工作流。

代码风格指南（Code Style Guide）

Go 与后端代码

考虑到 TiDB 的复杂度，代码应让只具备基本 TiDB 常识的未来读者（包括非本子系统/特性专家）也能维护；
先遵循包内既有约定，与邻近文件保持一致；
代码应通过清晰的命名与结构做到自文档化：实现知名算法时命名应足够清晰以识别其思路；若命名不足以表达意图，加简短注释；
改动保持聚焦，同一 PR 内避免无关重构/改名/移动；
错误处理要可操作、带上下文，避免静默吞错；
新源文件（如*.go）需包含 TiDB 标准 license 头（copyright + Apache 2.0），从邻近文件复制并更新年份；
注释应解释非显而易见的意图、约束、不变量、并发保证、SQL/兼容性契约或重要性能权衡，不应复述代码已明示的内容；
保持导出符号的 doc comment，倾向语义约束而非名称复述。

测试与 testdata

倾向扩展既有测试套件与 fixtures，而非新建脚手架；
保持测试改动最小且确定，避免大范围 golden/testdata churn（除非必须）；
录制输出后，在报告完成前核验变更的结果文件。

文档与命令片段

文档中的命令应能在仓库根目录直接复制粘贴，除非明确限定作用域；
使用显式占位符，如<package_name>、<TestName>、<dir>；
文档更新应在相关文档间保持术语、策略措辞与命令约定一致；
指引要可执行、具体，避免含混措辞。

Agent 输出契约（Agent Output Contract）

任务结束时，Agent 的报告必须包含五项内容，确保可复核、可追溯：

变更的文件（Files changed）；
使用的验证档（WIP/Ready/Heavy）及选用理由；
风险：正确性、兼容性、性能三个维度；
用于验证的确切命令（Exact commands run for validation）；
未在本地验证的内容（What was not verified locally）。

配合"留下可验证证据"的不可协商原则，输出契约要求代理明确交代自己没有验证什么，避免把"本地没跑过"误报为"全部通过"。

配套文档联动：把规范串成一条可执行的开发链路

综合 AGENTS.md 与其配套文档，一个标准改动的完整链路如下：

开工：复述目标与验收标准（Pre-flight Checklist）→ 依据 docs/agents/architecture-index.md 定位子系统与既有测试，若目标包有doc.go先读它；
规划：大型改动按 PLANS.md 撰写并维护 ExecPlan（含Progress/Decision Log等强制章节）；
构建：按Build Flow判定是否需要make bazel_prepare，再make bazel_bin/make gogenerate；
验证：依据Task -> Validation Matrix挑选最小验证面，从 docs/agents/testing-flow.md 取命令；failpoint 命中则经 tools/check/failpoint-go-test.sh 跑、改集成测试用run-tests.sh -r录制、需要真实 TiKV 则启动/清理 playground，并选用 .agents/skills/tidb-verify-profile 的WIP/Ready档；
收尾：若改动涉及AGENTS.md/docs/agents/*，过 docs/agents/agents-review-guide.md 的评审清单；Bug 修复附"修复前失败/修复后通过"的回归证据；最后按Agent Output Contract输出五项报告。

在这条链路上，根 AGENTS.md 始终扮演"规范唯一来源"（policy single source of truth）的角色，docs/agents/testing-flow.md 等 runbook 提供可复制命令，PLANS.md 承载大型改动的上下文记忆，.agents/skills/*作为入口式工作流把策略与命令衔接起来。对于任何要在 TiDB 这类高一致性、高复杂度数据库中安全自主编码的 AI 代理而言，这套"策略—runbook—技能"三层治理框架既是行为准绳，也是验证与交付的最低可接受标准。

<输出文章>

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

TiDB 仓库的 AGENTS.md 解析：面向 AI 编码代理的分层策略、验证矩阵与构建契约