Kubernetes AGENTS.md 深度解读：AI Agent 协作规则、生成文件约束与 make 工作流

AGENTS.md 是 Kubernetes 仓库根目录下专为 AI 编码代理（Coding Agent）编写的行为契约，它与 CONTRIBUTING.md 面向人类贡献者的规范互补，用极简的语言规定了 Agent 在此仓库中"什么不能做、什么必须做、用什么命令做"。读完本篇，你将完整理解该文档定义的四大硬约束（生成文件只读、依赖文件生成化、staging 权威化、Boilerplate 强制化）、贡献流程要求，并能熟练运用 make test / make test-integration / make verify / make update 四条核心工作流命令，同时掌握每条规则背后对应脚本（如 hack/pin-dependency.sh、hack/make-rules/verify.sh）的真实实现逻辑。

AGENTS.md 的定位：给 AI Agent 的"仓库操作守则"

AGENTS.md 全文虽短，但信息密度很高，共包含五个板块：

1. Communication Preferences（沟通偏好）：输出风格与注释规范；
2. Constraints（硬约束）：四条不可违反的技术限制；
3. Contributor Guidelines（贡献者准则）：PR 与提交信息的纪律；
4. Commands（命令）：四条常用 make 工作流；
5. Style（代码风格）：Go 包命名约定。

这类文件的典型用法是：当 LLM 驱动的编程工具在仓库根目录发现 AGENTS.md 时，会自动将其内容注入上下文，作为系统级指令约束其行为。因此 Kubernetes 将其写得"干、短、无废话"——文档第一条就要求"Skip preambles and postambles"（跳过开场白和结束语），这本身就体现了它对 Agent 输出的期望。

沟通偏好：注释解释"为什么"，错误信息必须可执行

AGENTS.md 的 Communication Preferences 章节给出三条风格要求：

• 干练、简洁、带一点冷幽默；不奉承、不硬玩梗（Dry, concise, low-key humor. No flattery, no forced memes.）；
• 注释解释"为什么"，而不是"是什么"（Comments explain "why", not "what"）；
• 错误信息必须具体、可操作（Error messages: actionable and specific. No vague "something went wrong" output.）。

第三条值得对照仓库源码体会。hack/make-rules/test.sh 中对非法参数的报错就是范本：hack/pin-dependency.sh 在参数不合法时不会说"something went wrong"，而是直接打印完整用法和示例（见下文）。同样，Makefile 对已废弃变量 KUBE_GOFLAGS 的处理也是"可操作的错误信息"的典范——它先提示 KUBE_GOFLAGS is now deprecated. Please use GOFLAGS instead.，在两个变量同时存在时则直接 $(error Both KUBE_GOFLAGS and GOFLAGS are set. Please use just GOFLAGS) 报错退出，明确告诉使用者下一步该做什么。

四条硬约束及其源码级依据

约束一：生成文件只读，一律通过 make update 再生成

AGENTS.md 规定：zz_generated.* 与 generated.pb.go 永远不得手改，需要变更时运行 make update。这与 Kubernetes 的 codegen 体系一致：API 类型变更后，DeepCopy、client、lister 等代码都由代码生成器产出，手改会在下次生成时被覆盖。

make update 的真实行为定义在 hack/make-rules/update.sh，它会依次执行一组 update 脚本（BASH_TARGETS）：

update-codegen                          # 重新生成 client/lister/informer 等
update-featuregates                     # 重新生成 feature gate 常量
update-generated-api-compatibility-data
update-generated-docs
update-openapi-spec
update-gofmt                            # 统一格式化
update-golangci-lint-config

两个实现细节值得注意：

• 默认是短路模式（short-circuit）：某个脚本失败即 exit 1；需要强制全部执行时用 FORCE_ALL=true（见 update.sh）；
• 默认 SILENT=true，日志被吞掉，调试时可 SILENT=false 打开输出。

与之配套的验证侧脚本是 hack/verify-codegen.sh，它在 make verify 中检查生成文件是否与源码同步——这正是"手改生成文件"会被 CI 拦截的原因。

约束二：go.mod / go.work 是生成物，禁止 go mod tidy

Kubernetes 采用多模块 + Go workspace 结构：根 go.mod、go.work 以及 staging/src/k8s.io/* 下数十个模块的 go.mod 之间存在严格的版本联动关系，直接 go mod tidy 会破坏这种联动。AGENTS.md 指明的正确姿势是两件套：

hack/pin-dependency.sh <模块> <SHA或Tag>   # 定点升级某个依赖
hack/update-vendor.sh                      # 重建 vendor 目录与各 go.mod

hack/pin-dependency.sh 头部注释给出了准确用法与示例：

# 用法：hack/pin-dependency.sh $MODULE $SHA-OR-TAG
# 示例：hack/pin-dependency.sh github.com/docker/docker 501cb131a7b7
# 支持替换为 fork（仅用于测试，注释明确警告"结果永远不要合入 Kubernetes"）：
#   hack/pin-dependency.sh github.com/docker/docker=github.com/johndoe/docker my-experimental-branch

从源码看，该脚本的完整流程是：先 go mod download -json 解析出目标版本的规范 revision（L72-L81），再 go mod edit -require 写入依赖（L83-L85），若涉及 replace 还会遍历所有 staging 仓库的 go.mod 逐个写入 replace 指令以保证间接依赖一致（L93-L110）。脚本最后一行输出：Run hack/update-vendor.sh to rebuild the vendor directory——即官方指定的收尾动作，而非 go mod tidy。

约束三：staging 是 k8s.io/* 的唯一事实来源

AGENTS.md 规定：k8s.io/* 以 staging/src/k8s.io/ 为准，且 staging 代码永远不能反向 import k8s.io/kubernetes。

staging/README.md 对此有权威说明：

"The code in the staging/ directory is authoritative, i.e. the only copy of the code. You can directly modify such code."（staging/ 中的代码是权威的，即唯一副本，可直接修改）

该目录当前暂存了 30 个模块，包括 k8s.io/api、k8s.io/apimachinery、k8s.io/client-go、k8s.io/apiserver、k8s.io/kubectl 等（完整清单见 staging/README.md）。Kubernetes 代码通过 Go workspace 与 module replace 语句将这些导入解析到本地 staging 目录，例如 k8s.io/client-go/dynamic 实际解析到 staging/src/k8s.io/client-go/dynamic（staging/README.md）。"staging 不得 import kubernetes"这一方向性约束则从源码结构上防止了循环依赖——因为 k8s.io/kubernetes 根模块本身就是聚合方，若被 staging 反引，模块图将成环。

约束四：所有 .go 文件必须带 Boilerplate 许可头

AGENTS.md 要求每个 .go 文件都携带来自 hack/boilerplate/boilerplate.go.txt 的许可头，即 Apache 2.0 声明加 Copyright The Kubernetes Authors. 注释块，完整内容仅 15 行：

/*
Copyright The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

这条规则的执行者是 hack/verify-boilerplate.sh，它会扫描全部源文件核对文件头，且被列入 make quick-verify 的快速检查集（hack/make-rules/verify.sh 的 QUICK_PATTERNS），意味着它在 CI 中属于秒级必查项。

贡献者准则：AI 披露与提交信息纪律

AGENTS.md 的 Contributor Guidelines 共六条，逐条都可直接落地为 PR 检查项：

规则	要点
变更聚焦	Keep changes focused and reviewable，一次 PR 解决一个问题
测试同步	Add or update relevant tests
AI 披露	创建或提交 PR 时必须声明是否使用了 AI，并简要说明使用方式
人类兜底	提醒人类作者：其对所有提交的变更负责，并指引其阅读 CONTRIBUTING.md
提交信息禁项一	不要在 commit message 中放 @mentions 或 fixes #... 关键字
提交信息禁项二	不要添加 Co-authored-by: 尾注

其中"AI 披露"条款是这份文档区别于传统 CONTRIBUTING 规范的新意：它不禁止 AI 辅助开发，而是要求透明化披露方式与程度，同时保留人类作者对代码的最终责任。commit message 两条禁令则服务于 Kubernetes 的 cherry-pick 与发布工具链——fixes #... 会被自动化系统误触发关单，Co-authored-by: 会干扰作者归属统计。

命令工作流：四条 make 命令的完整用法

AGENTS.md 给出的 Commands 章节是文档中最具实操价值的部分。它首先指出入口：make help 可列出全部目标（由 Makefile 的 help 目标经 hack/make-rules/make-help.sh 生成）。下面逐条展开，并补充脚本内部的关键参数。

单元测试：make test

make test WHAT=./pkg/kubelet GOFLAGS=-v     # 只测一个包，-v 输出细节

• WHAT：要测试的目录，省略时"全测"——实际上是通过 hack/make-rules/test.sh 的 kube::test::find_go_packages 枚举 workspace 中所有含测试文件的包，并自动排除 test/e2e*、staging 下的 integration 测试等非单元测试目录；
• GOFLAGS=-v：追加透传给 go test 的编译/运行标志（Makefile 将 GOFLAGS 定义为官方输入变量，KUBE_GOFLAGS 已废弃）。

从 test.sh 的实现看，该工作流默认携带了一批常被忽略的参数：

KUBE_TIMEOUT=${KUBE_TIMEOUT:--timeout=180s}   # 单包测试默认 180s 超时
KUBE_COVER=${KUBE_COVER:-n}                  # 置 'y' 收集覆盖率
KUBE_RACE=${KUBE_RACE-"-race"}               # 默认开启竞态检测，KUBE_RACE="" 可关闭

测试结果通过 gotestsum 以 pkgname-and-test-fails 格式输出，若设置了 KUBE_JUNIT_REPORT_DIR 会额外产出精简后的 JUnit XML（经 cmd/prune-junit-xml 裁剪到顶层用例）。

集成测试：make test-integration

make test-integration WHAT=./test/integration/scheduler

Makefile 中该目标将 KUBE_TEST_ARGS 原样（保留 $ 转义）传给 hack/make-rules/test-integration.sh。Makefile 自带的帮助注释给出了更精细的用法：

make test-integration WHAT=./test/integration/kubelet GOFLAGS="-v -coverpkg=./pkg/kubelet/..." KUBE_COVER="y"
make test-integration WHAT=./test/integration/pods GOFLAGS="-v" KUBE_TEST_ARGS='-run ^TestPodUpdateActiveDeadlineSeconds$$'

KUBE_TEST_ARGS 支持 -run 正则精确到单个集成测试函数，$$ 是为了让 Make 变量展开后仍保留正则的 $ 锚点。

全量校验：make verify

make verify                                 # 运行全部 presubmission 检查

Makefile 将其映射到 hack/make-rules/verify.sh，后者遍历 ./go.mod 与 staging/**/go.mod 发现的每个模块，执行其 hack/verify-*.sh（及 .py）检查脚本。关键机制：

• WHAT 过滤：make verify WHAT="gofmt typecheck" 只跑指定检查（名称去掉 verify- 前缀）；
• 快速模式：make quick-verify 等价于 QUICK=true，只执行 QUICK_PATTERNS 中约 15 个理想耗时低于 10 秒的检查（verify-boilerplate、verify-gofmt、verify-imports、verify-pkg-names 等）；
• 自动排除：verify-*-dockerized.sh、verify-golangci-lint-pr*.sh 等本就运行在独立 CI 作业的脚本会被跳过（EXCLUDED_PATTERNS）；
• 失败项会汇总打印 FAILED TESTS 清单，方便逐一修复。

全量再生成：make update

make update                                 # 运行全部生成器与格式化工具

如前所述，它执行 hack/make-rules/update.sh 中的 7 个脚本，是满足"生成文件只读"约束的唯一正道：任何 zz_generated.*、OpenAPI spec、feature gate 常量、文档的变更都应走这里，而非手工编辑。

代码风格：包命名一条规则

AGENTS.md 的 Style 章节仅一条：包名小写、单个单词、且与所在目录同名（Packages: lowercase, single word, match directory.）。这条规则由 hack/verify-pkg-names.sh 在 CI 中强制校验（同样列入 quick 检查集）。它避免了 Go 中 import pod "k8s.io/.../pods" 之类的别名混乱，也是阅读 Kubernetes 源码时"包名即目录名"这一直觉的来源。

实践速查表

场景	正确做法	禁止做法
修改了 API 类型	make update 再生成	手改 zz_generated.* / generated.pb.go
升级某个依赖	hack/pin-dependency.sh <module> <sha> + hack/update-vendor.sh	go mod tidy 手改 go.mod / go.work
修改 k8s.io/client-go 等模块	直接改 staging/src/k8s.io/<repo>	在 staging 中 import k8s.io/kubernetes
新建 .go 文件	复制 boilerplate.go.txt 许可头	省略或自拟许可头
本地验证	make quick-verify → make test WHAT=./pkg/... → make verify	只跑部分检查就提 PR
提交 PR	说明聚焦变更、补充测试、披露 AI 使用方式	commit message 写 @mention / fixes #... / Co-authored-by:

AGENTS.md 的价值不在于它讲了什么新知识，而在于它把 Kubernetes 这套"生成物不可手改、依赖必须脚本化、staging 单向依赖"的工程体系压缩成了 Agent 可执行的硬规则。理解它背后的脚本实现（Makefile、hack/make-rules/、hack/pin-dependency.sh），才能在这些规则之上做出正确的工程判断。