编写、更新或审核 Terraform Provider…

适用于新增或变更 Terraform Provider 配置、资源、数据源、临时资源、列表资源、函数、动作或指南文档，并需要生成、校验和发布 Terraform Registry 文档的场景。

适用场景

解决思路

1. 确认范围与文档目标。
2. 将代码变更映射到确切的文档目标：provider index、resources、data sources、ephemeral resources、list resources、functions、actions 或 guides。
3. 决定内容来自 schema descriptions、templates，还是两者都用。
4. 先编写 schema descriptions。
5. 为 schema 字段添加精确的面向用户描述，使生成的文档与行为保持一致。
6. 措辞要具体说明参数用途、约束、默认值和 computed 行为。
7. 在 docs/ 中添加或更新模板文件。
8. 只为已实现的 provider 对象创建对应文件。
9. 使用 HashiCorp 推荐的模板路径：docs/index.md.tmpl。
10. 使用 HashiCorp 推荐的模板路径：docs/data-sources/<name>.md.tmpl。
11. 使用 HashiCorp 推荐的模板路径：docs/resources/<name>.md.tmpl。
12. 使用 HashiCorp 推荐的模板路径：docs/ephemeral-resources/<name>.md.tmpl。
13. 使用 HashiCorp 推荐的模板路径：docs/list-resources/<name>.md.tmpl。
14. 使用 HashiCorp 推荐的模板路径：docs/functions/<name>.md.tmpl。
15. 使用 HashiCorp 推荐的模板路径：docs/actions/<name>.md.tmpl（tfplugindocs 在 Terraform v1.14.0+ 生成 action 文档）。
16. 使用 HashiCorp 推荐的模板路径：docs/guides/<name>.md.tmpl。
17. 模板聚焦概览和示例；字段级细节依赖生成的 section。
18. 将 HCL 示例放在 examples/ 目录，每个文件一个示例，用 tffile 拉入模板，而不是内联在模板中（见 references/hashicorp-provider-docs.md 的 Example File Conventions）。
19. 示例不得包含 terraform、provider 或 output block。
20. 对于 action 页面，遵循 references/hashicorp-provider-docs.md 的 Action Pages section 结构：示例必须同时展示 action block 和 action_trigger 生命周期接线，且 action 没有 attribute/output section。
21. 使用 tfplugindocs 生成文档。
22. 优先使用仓库默认配置：go generate ./...。
23. 否则直接运行生成器：go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>。
24. 每次修改 schema 或模板后都重新运行生成。
25. 校验生成的 markdown。
26. 验证 docs/ 中的文件与当前 provider 实现一致。
27. 验证示例是有效 HCL，并反映当前 argument/attribute 名称。
28. 验证文档中的 required/optional/computed 语义与 schema 行为一致。
29. 发布前应用 Registry 发布规则。
30. 使用带 v 前缀的语义化版本 tag（例如 v1.2.3）。
31. 从默认分支创建 release tag。
32. 将 terraform-registry-manifest.json 保留在仓库根目录。
33. 预期 Registry 中的文档会被版本化，并可通过版本选择器切换。
34. 需要时预览或排查发布问题。
35. 当准确性风险高时，使用 HashiCorp preview 流程在发布前检查渲染后的文档。
36. 如果 Registry 中缺少文档，检查 tag 格式、tag 来源分支、manifest 文件是否存在、provider 发布状态。
37. 遵守质量门槛：文档必须行为准确；绝不描述不支持的 argument 或 attribute。
38. 示例保持最小、真实、可运行。
39. 在 provider、resources 和 data sources 之间保持术语和命名一致。
40. 避免在手动模板中重复生成的 argument/attribute block。
41. 尽可能将文档变更与 schema/API 变更放在同一个 PR 中。
42. 按需加载参考：阅读 references/hashicorp-provider-docs.md 获取有来源支持的规则和官方链接。
43. 只加载当前变更所需的 section，以保持上下文精简。

适用边界 · 注意事项

• 不适用于非 Terraform Provider 文档，或不需要 Terraform Registry、tfplugindocs 的项目。
• 当 provider 对象尚未实现，或 schema/API 尚未变更时，不应先创建对应文档或模板。
• 如果无法运行 tfplugindocs，或仓库没有 docs/、examples/ 等必要结构，应先满足工具与仓库配置前提再使用本流程。