如何给terraform-skill贡献内容：开发者指南、LLM消费规则与CI校验全解析

如何给terraform-skill贡献内容：开发者指南、LLM消费规则与CI校验全解析

【免费下载链接】terraform-skillTerraform & OpenTofu Skill for AI Agents - testing, modules, CI/CD, and production patterns项目地址: https://gitcode.com/gh_mirrors/te/terraform-skill

terraform-skill 是一个面向 AI 编码代理的 Terraform / OpenTofu 最佳实践技能包，覆盖测试框架、模块开发、状态管理、CI/CD 与安全扫描等生产模式。想给它贡献内容？本文基于 CONTRIBUTING.md 与 CLAUDE.md 详解完整贡献流程：从 Fork 仓库到 PR 合并，重点解析面向 LLM 的消费者规则、TDD 测试铁律与 CI 校验机制，帮助你写出能被顺利合并的高质量贡献 🚀

5 步快速上手：完成你的第一次 terraform-skill 贡献

贡献流程与常规开源项目类似，但门槛判断更严格：

1. Fork 仓库：克隆仓库到本地

   git clone https://gitcode.com/gh_mirrors/te/terraform-skill

2. 创建功能分支：git checkout -b feature/your-topic
3. 按规范修改内容（下文详述）
4. 先测试再提交：遵循 TDD 铁律（见下文）
5. 提交 PR：附带测试证据

⚠️master分支受保护，禁止直接推送，所有变更必须通过 PR 合入。

判断你的内容适不适合贡献

项目明确划分了"好贡献"与"不合适"的边界：

内容落在哪里，项目有清晰的分工表（详见 CLAUDE.md#L187-L196）：决策框架与核心模式进 skills/terraform-skill/SKILL.md（约 305 行，软上限目标 ~300 行）；详细示例与模板进 skills/terraform-skill/references/ 目录下的 8 个参考文件。

LLM 消费规则全解析：为什么文档要为"机器"而写

这是 terraform-skill 贡献指南中最特别的部分——这份文档的第一读者不是人，而是检索事实来回答问题的 LLM。所有对 SKILL.md 和 references/*.md 的修改都必须遵守 CLAUDE.md#L155-L171 中的 6 条强制规则，违者 PR 会被直接拒收 🙅

1. 决策表先行，手册在后：一个主题有多种可行方案时，先给决策表（目标 | 选用 | 取舍），再写步骤，绝不能把分支藏在正文末尾。
2. 砍掉人类脚手架：before/after 对比、"Why this matters" 段落、教学式旁白——如果步骤里已经写了该做什么，这类内容就是冗余。
3. 散文压缩成 ❌/✅ 规则：凡是以 "You should..."、"Note that..."、"Keep in mind..." 开头的句子，改写为祈使句 ❌/✅ 条目，一条一个事实。
4. 每个制品都要"挣得"自己的 token：代码块和表格必须包含正文中没有的新事实，只为"完整性"存在的内容一律删除。
5. 锚点稳定性：SKILL.md 通过#anchor链接到参考文件的具体小节，重写时必须保留顶层### Heading锚点。
6. 检索优先排序：章节内部按 LLM 需要的顺序排列——决策表 → 默认流程 → 备选方案 → ❌/✅ 规则。

Token 预算：每个参考小节目标 < 400 tokens（约 1600 字符），超过就拆分或压缩。技巧包括：细节下沉到 references（渐进式披露）、表格优于散文、跨文件引用而非重复内容。

Frontmatter 要求：SKILL.md 的门面

修改 skills/terraform-skill/SKILL.md 时，YAML frontmatter 有两个必填字段（CONTRIBUTING.md#L33-L66）：

• name：技能名，仅允许字母、数字、连字符
• description：≤1024 字符，必须以 "Use when" 开头，写清楚"何时使用"（触发场景与症状），而不是"这个技能做什么"

metadata.version由发布工作流自动同步，永远不要手动编辑版本号（当前版本见 version.json，为 1.17.1）。

描述写法正误对比：

• ✅Use when writing, reviewing, or debugging Terraform/OpenTofu modules, tests, CI, scans, or state ops...
• ❌Comprehensive skill for Terraform development covering testing, modules, CI/CD...

TDD 铁律：先有失败测试，再改文档 🧪

这是项目最核心的要求（CONTRIBUTING.md#L141-L160）：NO CHANGES WITHOUT TESTING FIRST（没有测试就没有变更），适用于新增内容、编辑、重构，甚至"简单"的文档更新——没有例外。

文档的 TDD 三阶段对应 tests/ 目录下的三个文件：

测试时在 PR 描述中必须写清：测了哪些场景、基线行为（无变更时代理怎么做）、合规行为（有变更后怎么做）、以及变更有效的证据。

CI 校验与 Conventional Commits：PR 标题决定一切 🔍

PR 触发的 CI 校验（validate.yml）会拦截以下问题：

• frontmatter 缺失name/description、name含非法字符、description超 1024 字符
• PR 标题不合 Conventional Commits 规范——PR 会被 squash 合并，PR 标题就是发布工作流读取的提交主题，所以标题必须是合法的type: description格式
• SKILL.md 超过 500 行会告警（软目标 ~300 行）
• POWER.md与 SKILL.md 漂移（该文件由 CI 生成，禁止手改）

提交类型直接驱动版本号：

合并后发布全自动完成：工作流计算版本号 → 更新 SKILL.md frontmatter 与 CHANGELOG.md → 打 tag 并创建 Release。贡献者无需管理任何版本号 ✅

提交 PR 前检查清单 📋

• 已识别受影响场景并完成 RED/GREEN 测试
• 决策表在手册之前；无冗余 before/after 对比
• 无 "Why this matters" 类段落，均已转为 ❌/✅
• 每个小节 < 400 tokens
• SKILL.md 链接的锚点保持稳定
• PR 标题为合法 Conventional Commits 格式
• PR 描述含基线 vs 合规对比证据

参考文件索引

一句话总结：写给人看的内容要克制，写给 LLM 看的内容要精准——遵循决策表先行、Token 预算与 TDD 铁律，你的 terraform-skill 贡献就能顺利通过 CI 与评审 🎯

【免费下载链接】terraform-skillTerraform & OpenTofu Skill for AI Agents - testing, modules, CI/CD, and production patterns项目地址: https://gitcode.com/gh_mirrors/te/terraform-skill