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本文以 TiDBti/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.mdAGENTS 变更评审指南、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.mddocs/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 PrecedenceAGENTS.md 开篇即定义了规范关键词的语义与优先级规则MUST表示强制要求SHOULD表示建议除非存在具体的偏离理由MAY表示可选根AGENTS.md定义全仓库默认值如果更深的路径中存在更具体的AGENTS.md则更深层的文件在其子树范围内具有更高优先级。这是一个根默认 子树覆盖的层叠规则与.gitignore、CODEOWNERS等文件的合并语义类似。设计目的是让各子系统如pkg/ddl/可以在不破坏全局契约的前提下补充本模块的特殊要求同时避免规则碎片化。五条不可协商原则Non-negotiablesAGENTS.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 OverridesAGENTS.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.sumMUST运行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录制集成测试recordingMUST使用 docs/agents/testing-flow.md →Integration tests中的录制命令不是-record-record仅用于显式支持它的单元测试套件RealTiKV 测试MUST后台启动 playground → 运行测试 → 清理 playground/data见 docs/agents/testing-flow.md →RealTiKV testsBug 修复MUST添加回归测试并验证修复前失败、修复后通过纯格式fmt-onlyPRMUST 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 issueSHOULD使用 .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 Gatedocs/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 语法与 ASTtests/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_prepareTiDB 同时维护 Bazel 与 Go 两套构建元数据BUILD.bazel等文件通常由bazel_prepare自动生成。AGENTS.md 规定在以下任一情形成立时构建前必须先运行make bazel_prepare全新 workspace 或全新 cloneBazel 相关文件发生变化例如WORKSPACE、DEPS.bzl、BUILD.bazel、MODULE.bazel、MODULE.bazel.lockPR 中任何 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。推荐的本地构建流程AGENTS.md 给出的标准流程为以下命令均需在仓库根目录执行# 条件步骤仅当本节或 .agents/skills/tidb-bazel-prepare-gate 判定需要时运行 make bazel_prepare# 随后继续常规本地构建步骤 make bazel_bin make gogenerate # 可选重新生成生成代码 go mod tidy # 可选当 go.mod/go.sum 变化时 git fetch origin --prune值得注意的策略细节make bazel_lint_changed被刻意排除在默认本地流程之外因为它在本地尤其是 macOS可能很慢且资源密集除非用户明确要求AgentMUST NOT运行它。这与快速决策矩阵中高成本可选扫描仅在需要时运行的 MUST 规则相互呼应也印证了 Makefile 中bazel_lint_changed依赖bazel_prepare的实现约第 906 行。任务 → 验证矩阵Task - Validation Matrix矩阵的核心思想是使用能证明正确性的最小验证集合包级、集成测试与 RealTiKV 的命令细节均位于 docs/agents/testing-flow.md。完整矩阵如下变更范围最小验证pkg/planner/**规则或逻辑/物理计划针对性 planner 单元测试必要时更新规则 testdatapkg/executor/**SQL 行为针对性单元测试 相关集成测试tests/integrationtestpkg/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 PolicyAGENTS.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/...默认以-tagsintest,deadlock编译运行pushd pkg/package_name go test -run TestName -tagsintest,deadlock popd并明确-tagsintest,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_ADDR127.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; donego test -run TestName -tagsintest,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 GuideGo 与后端代码考虑到 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—技能三层治理框架既是行为准绳也是验证与交付的最低可接受标准。输出文章【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考