如何给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-skillterraform-skill 是一个面向 AI 编码代理的 Terraform / OpenTofu 最佳实践技能包覆盖测试框架、模块开发、状态管理、CI/CD 与安全扫描等生产模式。想给它贡献内容本文基于 CONTRIBUTING.md 与 CLAUDE.md 详解完整贡献流程从 Fork 仓库到 PR 合并重点解析面向 LLM 的消费者规则、TDD 测试铁律与 CI 校验机制帮助你写出能被顺利合并的高质量贡献 5 步快速上手完成你的第一次 terraform-skill 贡献贡献流程与常规开源项目类似但门槛判断更严格Fork 仓库克隆仓库到本地git clone https://gitcode.com/gh_mirrors/te/terraform-skill创建功能分支git checkout -b feature/your-topic按规范修改内容下文详述先测试再提交遵循 TDD 铁律见下文提交 PR附带测试证据⚠️master分支受保护禁止直接推送所有变更必须通过 PR 合入。判断你的内容适不适合贡献项目明确划分了好贡献与不合适的边界✅ 欢迎❌ 不欢迎有社区共识的 Terraform/OpenTofu 最佳实践缺乏共识的个人偏好新版本特性的针对性指引Provider 特定的资源细节应走 Terraform MCP 工具纠正过时或错误信息未经验证的变更更好的示例、模式、测试框架改进与 AI 模型已有知识重复的内容内容落在哪里项目有清晰的分工表详见 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 会被直接拒收 决策表先行手册在后一个主题有多种可行方案时先给决策表目标 | 选用 | 取舍再写步骤绝不能把分支藏在正文末尾。砍掉人类脚手架before/after 对比、Why this matters 段落、教学式旁白——如果步骤里已经写了该做什么这类内容就是冗余。散文压缩成 ❌/✅ 规则凡是以 You should...、Note that...、Keep in mind... 开头的句子改写为祈使句 ❌/✅ 条目一条一个事实。每个制品都要挣得自己的 token代码块和表格必须包含正文中没有的新事实只为完整性存在的内容一律删除。锚点稳定性SKILL.md 通过#anchor链接到参考文件的具体小节重写时必须保留顶层### Heading锚点。检索优先排序章节内部按 LLM 需要的顺序排列——决策表 → 默认流程 → 备选方案 → ❌/✅ 规则。Token 预算每个参考小节目标 400 tokens约 1600 字符超过就拆分或压缩。技巧包括细节下沉到 references渐进式披露、表格优于散文、跨文件引用而非重复内容。Frontmatter 要求SKILL.md 的门面修改 skills/terraform-skill/SKILL.md 时YAML frontmatter 有两个必填字段CONTRIBUTING.md#L33-L66name技能名仅允许字母、数字、连字符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-L160NO CHANGES WITHOUT TESTING FIRST没有测试就没有变更适用于新增内容、编辑、重构甚至简单的文档更新——没有例外。文档的 TDD 三阶段对应 tests/ 目录下的三个文件阶段做什么记录位置 RED禁用技能跑 tests/baseline-scenarios.md 中的场景记录基线行为baseline-results/ GREEN启用技能跑相同场景验证行为改善tests/compliance-verification.md REFACTOR封堵新发现的合理化借口重测直到无懈可击tests/rationalization-table.md测试时在 PR 描述中必须写清测了哪些场景、基线行为无变更时代理怎么做、合规行为有变更后怎么做、以及变更有效的证据。CI 校验与 Conventional CommitsPR 标题决定一切 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 生成禁止手改提交类型直接驱动版本号类型版本升级用途feat!:/BREAKING CHANGE:Major破坏性变更feat:Minor新功能fix:/docs:/chore:/test:/refactor:Patch修复与杂项合并后发布全自动完成工作流计算版本号 → 更新 SKILL.md frontmatter 与 CHANGELOG.md → 打 tag 并创建 Release。贡献者无需管理任何版本号 ✅提交 PR 前检查清单 已识别受影响场景并完成 RED/GREEN 测试决策表在手册之前无冗余 before/after 对比无 Why this matters 类段落均已转为 ❌/✅每个小节 400 tokensSKILL.md 链接的锚点保持稳定PR 标题为合法 Conventional Commits 格式PR 描述含基线 vs 合规对比证据参考文件索引资料路径贡献指南本文主要来源CONTRIBUTING.md开发者规范与 LLM 消费规则CLAUDE.md核心技能文件skills/terraform-skill/SKILL.md参考文件目录8 个专题skills/terraform-skill/references/基线测试场景tests/baseline-scenarios.md合规验证tests/compliance-verification.md合理化借口追踪表tests/rationalization-table.md发布历史CHANGELOG.md一句话总结写给人看的内容要克制写给 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考