企业官网建设流程全解析

Terraform AWS Provider 的 AI Agent 协作指南：AGENTS.md 驱动的开发规范与实践

【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws

本篇文章以开源仓库 terraform-provider-aws 根目录下的 AGENTS.md 为纲领，系统讲解该仓库如何为 AI 编码 Agent 建立一套可执行的协作开发规范：从角色分工（contributor / maintainer / tcm）、技能（Skills）加载机制，到代码结构、双插件框架、编码规范与完整的开发工作流。读完本文，你将掌握在这类大型 Go 开源项目中使用 Agent 高效完成贡献、代码评审、问题分类等任务的标准化路径，以及仓库在构建、测试、代码生成、CHANGELOG 与 AI 使用披露等方面的硬性约束。

一、AGENTS.md 是什么：给 Agent 的仓库"说明书"

AGENTS.md 是仓库为 AI 编码 Agent 提供的指引文件，与面向人类的贡献文档不同，它的读者是 AI Agent 本身，目的是让 Agent 在操作该仓库代码时遵循一致、可验证的工作方式。文件开头即说明：

This file provides guidance to AI coding agents when working with code in this repository.

该文件定位在仓库根目录（AGENTS.md），内容覆盖六个维度：仓库概览、Agent 注册表、Skills 技能系统、技术栈、代码结构与约定、开发工作流与边界。这六个维度共同构成 Agent 在本仓库中"能做什么、按什么标准做、哪些绝对不能做"的完整约束集。

二、仓库概览：Go 编写的 AWS Provider

AGENTS.md 明确指出，本仓库是 Go 语言实现的 Terraform AWS Provider（模块路径为github.com/hashicorp/terraform-provider-aws），其核心职责是将 AWS API 资源映射为 Terraform 资源，包括：

• resources（资源）：可创建、读取、更新、删除的基础设施对象；
• data sources（数据源）：只读查询 AWS 现有资源；
• ephemeral resources（临时资源）：在单个 Terraform 操作周期内存在、不持久化的资源；
• actions（动作）：执行一次性操作而不是管理对象的资源类型。

这四类统称为"resources"。主语言是 Go；HCL 主要出现在 internal/ 目录下的验收测试配置和 website/docs 的文档中。

从源码结构也可以印证这一概述：main.go 作为入口通过tfprotov5/tf5server启动 provider 服务器，并调用provider.ProtoV5ProviderServerFactory完成初始化；internal/service/ 下按 AWS 服务划分了近 200 个子包（如ec2、iam、s3、lambda等），每个子包内是具体资源、数据源、列表资源的实现与验收测试。

三、Agent 注册表：三种专职角色

AGENTS.md 规定，本仓库使用"专职人物"（personas）来承接不同类型的任务，人物定义文件存放于 .agents/ 目录：

注册表使用规则

• 始终使用被要求的角色处理任务；
• 未指定角色时，默认使用@contributor；
• 角色定义了带视角和责任的岗位，角色可以调用 skills。

从 .agents/contributor.md 可以看到角色的具体约束：contributor 被定义为"专注于 AWS 服务的资深 Go 开发者"，风格直接、简洁、聚焦代码实现，不得评审 PR（评审职责移交给@maintainer）；.agents/maintainer.md 则要求评审时从正确性（边界情况、测试是否真正验证行为）、可读性、架构标准一致性、安全性（密钥不入库、依赖漏洞）、性能（无界循环、无约束数据拉取）五个维度把关，且不直接贡献 PR。角色之间的职责隔离清晰，避免 Agent 在同一任务中既当运动员又当裁判。

四、Skills 技能系统：按任务加载的"操作手册"

Skills 是 AGENTS.md 中引入的一套扩展机制，从./.agents/skills加载，每个 skill 为特定任务提供分步指令、代码模式与护栏（guardrails）。完整的技能注册表如下（skill 文件均位于 .agents/skills/）：

技能系统如何运作：以 PR 评审为例

.agents/skills/review-pr/SKILL.md 展示了技能系统的完整工作方式：

1. 触发条件：用户提供https://github.com/hashicorp/terraform-provider-aws/pull/<N>形式的 PR URL 并要求评审时触发；
2. 提取 PR 编号：用正则/pull/(\d+)从 URL 中提取<PR_NUMBER>；
3. 获取变更文件：拉取 PR 的变更文件与 diff；
4. 路由分类：按路由表将每个变更路径归类——internal/service/**/*.go（非测试）按关注点分给 lifecycle/schema/helpers/identity/tags，*_gen.go分给 review-generated，*_test.go分给 review-tests 系列，website/docs/**/*.markdown分给 review-docs；
5. 加载叶技能：只对变更行应用匹配叶技能的规则；
6. 兼容性检查：变更必须保持 Terraform 状态兼容、升级行为、导入行为与既有用户工作流，schema 变更若强制替换（replacement）、重命名属性或破坏状态迁移必须明确标注（除非有充分理由），且不能依赖任何breaking-change标签；
7. 汇总评审：合并所有发现为一份评审，引用规则并给出修正后的代码。

评审原则强调"兼容性不可谈判"；Go 风格要求现代 Go（slices、maps、cmp、iter、errors.Is/errors.As），仅使用 AWS SDK for Go v2，检测 AWS API 异常用errs.IsA[*awstypes.<Exception>]而非类型断言或strings.Contains；评审语气应具体、准确、直击要点，对make lint、semgrep、格式化工具能自动捕获的机械问题不要手写评论。

五、技术栈

AGENTS.md 明确列出仓库技术栈：

• Go 1.26+与AWS SDK for Go v2（go.mod 中go 1.26.6，依赖github.com/aws/aws-sdk-go-v2 v1.47.0及其大量service/*子模块可印证）；
• Terraform Plugin Framework + Terraform Plugin SDKv2，通过 mux 混合成一个 provider；
• 代码生成器位于 internal/generate/；
• 构建系统为GNU Make（见 GNUmakefile）；
• 测试使用 Go 标准testing包 +terraform-plugin-testing验收测试框架。

值得注意的是，go.mod 中还包含一条特殊的godebug tlsmlkem=0指令，注释说明"禁用后量子 X25519MLKEM768 密钥交换机制，该机制会与 AWS Network Firewall 产生错误"——这类约束同样属于 Agent 在修改依赖时应当知晓的项目级上下文。

六、代码结构：Agent 必须知道的关键目录

AGENTS.md 用一棵目录树标注了"重要部分"，这也是 Agent 定位代码时的第一张地图：

terraform-provider-aws/ ├── .changelog/ # CHANGELOG 条目 ├── internal/ │ ├── acctest/ # 验收测试辅助 │ ├── backoff/ # 底层退避循环实现 │ ├── conns/ # provider 级全局状态，包括 provider 配置 │ ├── enum/ # AWS SDK for Go v2 枚举工具 │ ├── errs/ # Go error 工具 │ │ ├── fwdiag/ # Terraform Plugin Framework Diagnostic 工具 │ │ └── sdkdiag/ # Terraform Plugin SDKv2 Diagnostic 工具 │ ├── flex/ # 通用及 SDKv2 的 flattener/expander │ ├── framework/ # Terraform Plugin Framework 工具 │ │ ├── flex/ # flattener/expander，含 AutoFlex │ │ ├── types/ # 自定义类型实现 │ │ └── validators/ # validator 实现 │ ├── function/ # provider 函数 │ ├── generate/ # 代码生成器 │ ├── iter/ # Go 迭代器工具 │ ├── json/ # JSON 工具 │ ├── maps/ # Go map 工具 │ ├── provider/ # provider 初始化与配置 │ │ ├── framework/ # Plugin Framework 初始化/配置与拦截器 │ │ ├── interceptors/ # 通用拦截器工具 │ │ └── sdkv2/ # Plugin SDKv2 初始化/配置与拦截器 │ ├── reflect/ # Go 反射工具 │ ├── retry/ # 通用重试功能 │ │ └── state.go # 资源等待状态功能 │ ├── sdkv2/ # Terraform Plugin SDKv2 工具 │ ├── service/*/ # 各服务资源实现 │ │ ├── exports.go # 供其他 Go 包使用的函数与变量 │ │ ├── exports_test.go # 供本包验收测试使用的函数与变量 │ │ ├── generate.go # 代码生成指令 │ │ └── sweep.go # 本服务的资源清扫器（sweepers） │ ├── slices/ # Go slice 工具 │ ├── smerr/ # Smarterr 工具 │ ├── sweep/ # 资源清扫工具 │ ├── tags/ # 资源打标签工具 │ ├── types/ # Go 类型 │ ├── vcr/ # VCR 测试工具 │ └── verify/ # SDKv2 特定属性校验 ├── go.mod ├── go.sum ├── GNUmakefile # 构建与测试命令 └── main.go # 入口点

从上树可以看出两个设计要点：一是按服务垂直划分实现（internal/service/*/），每个服务子包自带exports.go、generate.go、sweep.go等配套文件，职责边界清晰；二是公共工具集中在internal/顶层包（conns、retry、tags、types 等），AGENTS.md 因此规定"复用internal/（排除internal/generate/与internal/service/）中的工具包优先于新写工具代码"。

七、重要约束：双框架架构（Dual Framework）

本仓库同时使用两套 Terraform 插件框架：

• Terraform Plugin SDKv2（老资源）：使用schema.Resource、d.Set()、d.Get()；
• Terraform Plugin Framework（新资源）：使用resource.Resource、plan modifiers、AutoFlex。

两条铁律：

• 修改既有资源时，沿用该资源正在使用的框架；
• 创建新资源时，使用 Terraform Plugin Framework。

从代码验证：provider 初始化被拆分为 internal/provider/framework/ 与 internal/provider/sdkv2/ 两个子目录，GNUmakefile 中的schema-validate目标分别对两者执行TestProviderInit，印证了双框架并存且分别校验的架构现实。

八、编码规范（Conventions）

不可协商的规则

• 验证（Verification）是每个 PR 的硬性出口标准（见下文开发工作流），未经验证，任务不算完成；
• 偏好"无聊但显然正确的方案"，只动被要求动的部分；
• 每个 PR 必须能构建、通过测试、无 lint 问题；
• 遵循既有命名、风格与惯用法；避免遗留模式（legacy patterns）；
• 复用仓库现有工具包优先，写新工具代码前必须先穷尽复用可能。

Go 语言使用

• 编辑internal/**下任何 Go 文件前，先加载 go-conventions 技能并遵循它；
• Go 使用 Tab（\t）字符缩进；
• 使用优雅的现代 Go（Go 1.26+）惯用法，如slices.Contains()；
• Go 的细节：不要只构建单个文件，要构建整个包。

.agents/skills/go-conventions/SKILL.md 进一步细化了规范，值得 Agent 与读者注意的要点包括：

• 命名：缩写保持单一大小写（ID、ARN、API、VPC、KMS、URL、HTTP），写applicationID而非applicationId/Arn/Url；MixedCaps而非下划线（测试名TestAccFoo_basic除外）；getter 去掉Get前缀；接收者用一两个字母且全类型一致，禁用this/self；不创建util、common、misc、api、types、interfaces之类的包名；
• 注释：命名与结构优先，注释不弥补难读的代码；删除那些复述代码、为明显操作命名、充当函数内节标题、复述签名、教 Go 语法、或解释应改名的名称的注释；保留记录约束、不变量、意外的 AWS 行为、为何拒绝明显方案的注释；所有导出的声明都要有完整句注释（以名称开头、句号结尾）；
• 组织：函数最廉价可随意创建；文件默认编辑既有文件，不建helpers.go、common.go、utils.go；包是真正的 API 与依赖边界，极少且需强理由；
• 控制流与错误：线性自上而下，异常情况提前 return，无多余else；错误是值，返回并包装上下文；错误字符串小写且不加标点（如"reading bucket policy"）；禁止用_丢弃错误，禁止为普通失败 panic；
• Context：ctx context.Context永远是第一个参数；绝不要把 Context 存进结构体字段；
• 最重要的原则：不引入其他语言的架构——Go 偏好具体代码、显式控制流、局部性、小的消费方驱动接口与适度重复，反对抽象、间接与机制堆砌；两个实现都正确时，选择概念更少的那一个。

错误处理

• 使用 smarterr/smerr 错误工具（对应仓库中的 internal/smerr 与github.com/YakDriver/smarterr依赖）；
• Read 期间用retry.NotFound()检查资源是否缺失（对应 internal/retry）；
• 出错尽早返回；不要越过第一个致命错误继续累积诊断信息。

通用模式

资源文件命名约定

Framework 资源实现模式

新资源采用 Terraform Plugin Framework 模式：

• 实现resource.Resource接口；
• 尽可能用 AutoFlex 做 flatten/expand；
• 用retry.RetryContext处理最终一致性。

AGENTS.md 给出了 Read 方法的骨架：

func (r *thingResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) { // 1. Read model from state // 2. Call AWS API // 3. Handle NotFound → remove from state // 4. AutoFlex response into model // 5. Write model to state }

五个步骤与错误处理规范一一对应：模型从 state 读入、调用 AWS API、用retry.NotFound()处理缺失场景、AutoFlex 将 API 响应展开进模型、最后写回 state。

九、开发工作流（Development Workflow）

总原则

• 先做实质修改与正确性工作，临近提 PR 时再跑 lint：用make quick-fix PKG=<service>收尾。避免"小改动→lint→小改动→lint"的循环；make fmt是廉价的例外，可随时运行；
• 尽量把命令作用域限制在变更的包内——provider 体量巨大；CI 才是构建、lint、semgrep 的 provider 级总闸门。

AI 使用政策

AGENTS.md 要求：当 Agent 帮助准备 PR 时，必须在 PR 描述中披露 AI 的角色，并在标题中加入🤖🤖🤖；完整政策见 docs/ai-usage.md，核心是"无论是否使用 AI，人类对代码负全部责任"。

docs/ai-usage.md 将政策展开为三大原则，同样值得摘录：

• 透明（Transparency）：在 PR 描述中具体说明 AI 扮演的角色（如"用于为新函数生成样板代码"），分享使用的过程或提示词以帮助评审者理解意图；LLM Agent 提交 PR 时标题需含🤖🤖🤖以加速处理；
• 责任（Accountability）：AI 是工具而非独立贡献者；所有 PR 必须由真实的人拥有的账号提交，不接受代码生成机器人账号的提交；假定每一行代码都经过人类评审；贡献者必须足够深入地理解提交的代码，能用自己的话解释逻辑、影响与副作用；
• 质量（Quality）：AI 应辅助流程而非自动化最终决策——AI 很容易生成看起来合理但错误或危险的代码；拒绝"AI 输出直接粘贴"的低质提交，质量、架构与测试标准与人工编写一致。

可运行的命令

AGENTS.md 对命令的使用有明确的批准分级：

• make t与make testacc：运行验收测试并创建真实 AWS 资源，运行前必须获得明确批准；
• 其余make …（验收测试除外）、go …以及只读命令（awk、grep、ls、rg）无需确认即可安全运行。

对照 GNUmakefile 与 docs/makefile-cheat-sheet.md 可以还原这些命令的完整语义：

• make gen PKG=<service>：在修改注解或服务的generate.go之后重新生成代码，作用域限定在internal/service/<service>/...（GNUmakefile 中对应$(GO_VER) generate $(SVC_DIR)/...）；只有修改了names/data/names_data.hcl或internal/generate/下任何内容时才运行 provider 级make gen——它会波及所有服务且耗时数分钟；
• make test PKG=<service>：运行单元测试，T=<pattern>可按名称过滤；非 service 变更用如go test ./internal/conns/...；
• make quick-fix PKG=<service>：默认收尾通道，依次执行copyright-fix、fmt、testacc-lint-fix、fix-imports、modern-fix、semgrep-fix、terraform-fmt、website-terrafmt-fix，若构建损坏则直接失败（因此无需单独构建步骤）；
• make swissshepherd：校验文档变更与 schema 对齐；make swissshepherd-refresh仅在会话开始时运行一次。

关于变量作用域，docs/makefile-cheat-sheet.md 补充了重要细节：PKG与K等价，都是服务包名（如ec2、iam、lambda），会覆盖派生变量PKG_NAME、SVC_DIR、TEST；T是测试名/正则，且当PKG/K都未设置时会自动从测试名探测服务包——例如make t T=TestAccIAMRole_basic会自动定位到iam，无需手写长服务名。这正是 AGENTS.md 中"尽量缩小命令作用域"理念在 Makefile 层的落地。

提交、CHANGELOG 与文档

• 每个 commit 保持小巧、原子、单一目的，提交信息描述变更本身；
• 新特性、bug 修复与增强必须添加.changelog/条目；
• 新特性必须附带新文档，以 docs/end-user-documentation.md 为准。

关于 changelog 条目的格式，docs/changelog-process.md 给出了具体模板：在.changelog/目录下按{PR-NUMBER}.txt命名文件，内容为release-note代码块，例如：

```release-note:enhancement resource/aws_example_thing: Add `not_broken` attribute ```

新资源条目使用release-note:new-resource头且只写资源名；一个 PR 需要多个条目时可在同一文件中放多个代码块。这也解释了 AGENTS.md 中"永不直接编辑CHANGELOG.md，使用.changelog/条目"这一边界规则的来源——CHANGELOG.md 是由 go-changelog 从.changelog/目录聚合生成的产物。

十、边界（Boundaries）：Agent 的禁止清单

AGENTS.md 以"Boundaries"一节收尾，列出了几条硬性禁止事项：

• 绝不直接编辑CHANGELOG.md——使用.changelog/条目；
• 绝不手工编辑生成文件——修改生成器或注解，然后运行make gen PKG=<service>（或 provider 级make gen）；
• 不修改go.mod/go.sum却不运行go mod tidy（GNUmakefile 的deps-check目标会通过git diff --exit-code校验二者与 tidy 结果一致）；
• 不未经明确批准添加新的外部依赖（对应 docs/dependency-updates.md 的流程）；
• website/目录遵循不同约定，详见 docs/end-user-documentation.md。

这些边界本质上是在保护三条仓库生命线：发布记录（CHANGELOG）、生成代码的可复现性（generated code）、依赖树的稳定性（go.mod/go.sum）。

十一、实践视角：Agent 在仓库中的完整工作路径

综合全文，一个 AI Agent 在本仓库完成一次典型贡献的路径可以归纳为：

1. 选角色：未指定时默认@contributor，评审任务切到@maintainer，issue 分类用@tcm；
2. 加载技能：动internal/**的 Go 文件前先加载 go-conventions；新资源参考 new-list-resource / resource-identity 等专项技能；
3. 定位代码：按代码结构树找到internal/service/{service}/对应实现与_test.go、_data_source.go配套文件，文档落在website/docs/r/或website/docs/d/；
4. 确定框架：老资源沿 SDKv2 模式，新资源用 Plugin Framework + AutoFlex；
5. 开发与验证：make gen PKG=<service>再生成 →make test PKG=<service>单元测试 →make quick-fix PKG=<service>收尾，最后make swissshepherd校验文档；
6. 提交与披露：原子化 commit，添加.changelog/<PR_NUMBER>.txt条目（新特性配新文档），PR 描述中披露 AI 角色、标题加🤖🤖🤖，并由人类完成最终审查与提交；
7. 遵守边界：不碰CHANGELOG.md、不手改生成文件、不乱动依赖。

这套路径正是 AGENTS.md 的核心价值：把"大型开源 Go 项目的隐性开发规则"显性化、可执行化，使 AI Agent 与人类贡献者在同一套质量标准下协作——验证是每个任务的硬出口，人类始终对代码负最终责任。

【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws