生成 Terragrunt HCL 配置时：按架构模式生成…

需要创建或脚手架 Terragrunt 配置（根配置、子模块、多环境布局、Stacks、Feature Flags、Exclude/Errors 块、OpenTofu Engine）时使用。

适用场景

解决思路

1. 判断用户请求的配置类型：root.hcl、terragrunt.hcl、terragrunt.stack.hcl、多环境布局、dependency 接线、模块源（本地/Git/tfr:///）、catalog/units 等。
2. 支持并优先使用 Terragrunt 2025 特性：Stacks（terragrunt.stack.hcl，v0.78.0 起 GA）、feature 块、exclude 块、errors 块、OpenTofu engine。
3. 根配置命名默认推荐 root.hcl 而不是 terragrunt.hcl；include 默认写 find_in_parent_folders("root.hcl")；仅当明确针对旧版根文件 terragrunt.hcl 时才用 find_in_parent_folders()。
4. 写任何文件前必须确定架构模式：Pattern A 多环境+环境无关根；Pattern B 单环境或环境感知根；Pattern C 共享环境变量 _env 目录。
5. Pattern A 中 root.hcl 必须环境无关：不能 read_terragrunt_config(find_in_parent_folders("env.hcl"))；不能引用来自 env.hcl 的 local.environment 或 local.aws_region；可用静态值或 get_env()；状态键用 path_relative_to_include()；子模块负责读取 env.hcl。
6. Pattern B 中 root.hcl 可通过 get_env() 或解析 path_relative_to_include() 的目录部分来检测环境。
7. Pattern C 中每个环境的 env.hcl 从 _env/ 读取对应文件（例如 prod/env.hcl 读 _env/prod.hcl），并把变量重新导出到 locals 供子模块使用。
8. 生成前必须完成并输出架构模式选择清单：识别模式 A/B/C；标明 root.hcl 是 environment-agnostic 还是 environment-aware；写明 env.hcl 位置；写明子模块访问 env 的方式；验证没有文件引用其位置不存在的路径。
9. 提供快速变量定义示例：env.hcl 的 locals 包含 environment、aws_region、project；account.hcl 包含 account_id、account_name；region.hcl 包含 aws_region。
10. 生成根配置前必须读取 assets/templates/root/terragrunt.hcl，并参考 references/common-patterns.md 的 Root Configuration Patterns。
11. 根配置中替换占位符：[BUCKET_NAME]、[AWS_REGION]、[DYNAMODB_TABLE]、[TERRAFORM_VERSION]、[PROVIDER_NAME]、[PROVIDER_SOURCE]、[PROVIDER_VERSION]、[ENVIRONMENT]、[PROJECT_NAME]。
12. 根配置设计原则：环境无关为默认；provider/backend region 用静态值或 get_env()；状态键用 path_relative_to_include()；provider tags 可静态，环境特定 tags 放子模块。
13. 生成子模块配置前必须读取 assets/templates/child/terragrunt.hcl，并参考 Child Module Patterns。
14. 子模块的 module source 可用本地相对路径、git::https://github.com/org/repo.git//path?ref=v1.0.0、tfr:///terraform-aws-modules/vpc/aws?version=5.1.0。
15. 生成独立模块前必须读取 assets/templates/module/terragrunt.hcl。
16. 使用规范占位符替换映射：[AWS_REGION] 替换为 us-east-1 等；[ENVIRONMENT] 保持小写；[PROJECT_NAME] 用于 tags 和名称；[BUCKET_NAME] 和 [DYNAMODB_TABLE] 必须已存在；[PROVIDER_SOURCE] 用全限定源；[TERRAFORM_VERSION] 同时用于 terraform_version_constraint 和 required_version，且与模块约束兼容。旧别名 [REGION] 当作 [AWS_REGION] 并替换。
17. 生成多环境基础设施前确定架构模式，读取 root、env、child 相关模板，验证 env.hcl 放置和访问模式；典型 Pattern A 结构为 infrastructure/root.hcl、dev/env.hcl、dev/vpc/terragrunt.hcl、prod/env.hcl、prod/vpc/terragrunt.hcl。
18. 生成 Terragrunt Stacks 前读取 assets/templates/stack/terragrunt.stack.hcl 和 assets/templates/catalog/terragrunt.hcl，并参考 Stacks Patterns；保持 no_dot_terragrunt_stack 模式在依赖链中一致，不要混用直接路径和 .terragrunt-stack 生成。
19. 使用 stack 命令：terragrunt stack generate、terragrunt stack run plan、terragrunt stack run apply、terragrunt stack output、terragrunt stack clean。
20. 生成 Feature Flags 前读取文档和 Feature Flags Patterns；feature 的 default 必须是静态布尔/字符串/数字，不能引用 local.*；用法：terragrunt apply --feature enable_monitoring=true 或 export TG_FEATURE="enable_monitoring=true"；不同环境用不同静态默认值。
21. 生成 Exclude Blocks（替代 skip）：actions 可用 plan、apply、destroy、all、all_except_output；生产关键资源添加 exclude 阻止 destroy，并配合 prevent_destroy = true。
22. 生成 Errors Blocks（替代 retryable_errors）。
23. 生成 OpenTofu Engine 配置，参考 OpenTofu Engine Patterns。
24. 处理自定义 provider/module 时：识别 provider 名称、source、version；用 WebSearch 搜索 [provider] terraform provider [version] documentation；若有 Context7 MCP 则用结构化文档；生成 required_providers；在注释中记录认证要求。
25. 生成工作流 Step 1：理解需求——配置类型、单/多环境、模块依赖、将用的 providers/modules。
26. 生成工作流 Step 2：确定架构模式，按场景表选择 Pattern A/B/C，完成并输出架构模式选择清单，然后再写文件。
27. 生成工作流 Step 3：读取必需模板——root、env、child、module、stack、catalog 对应模板；同时读 references/common-patterns.md。
28. 生成工作流 Step 4：按验证策略生成。多环境项目顺序：先生成 root.hcl，内联检查无 read_terragrunt_config(find_in_parent_folders("env.hcl"))（若环境无关）、remote_state 有 encrypt = true、使用 errors 块而非 retryable_errors。
29. 然后生成每个环境的 env.hcl，内联检查 locals 包含 environment、aws_region、模块变量，且不引用该目录不存在的文件。
30. 然后生成无依赖的子模块（如 VPC），内联检查 include 用 find_in_parent_folders("root.hcl")、有 read_terragrunt_config(find_in_parent_folders("env.hcl"))、terraform.source 语法有效（tfr:///、git:: 或相对路径）。
31. 然后生成有依赖的模块（如 RDS、EKS），内联检查 dependency 块有 mock_outputs、mock_outputs_allowed_terraform_commands 包含 ["validate", "plan", "destroy"]、生产模块有 prevent_destroy = true 和/或 exclude 块。
32. 所有文件生成后运行批量验证：terragrunt hcl fmt --check 和 terragrunt dag graph；并调用 Skill(devops-skills:terragrunt-validator) 做全面验证。
33. 生成工作流 Step 5：验证失败时分析错误（路径解析、缺失变量、语法错误），修复具体文件，重新验证，重复直到所有错误解决。
34. 生成工作流 Step 6：按展示要求呈现结果。
35. 验证工作流：每个生成的配置都必须验证。生成 root.hcl 后 cd 到目录运行 terragrunt hcl fmt --check。生成每个子模块后 cd 到模块目录运行 terragrunt hcl fmt --check；若无依赖再运行 terragrunt hcl validate --inputs。
36. 所有文件生成后做完整验证：调用 Skill(devops-skills:terragrunt-validator)；失败则分析、修复、重新验证直到全部通过；成功则展示配置和使用说明。仅对部分片段、文档示例或用户明确要求可跳过验证。
37. 验证回退顺序：若 terragrunt 不可用，运行静态检查 rg -n 查找未替换占位符和 find_in_parent_folders("env.hcl") 误用，并报告运行时验证待定；若验证器技能不可用，直接运行 terragrunt hcl fmt --check 和 terragrunt dag graph；若 tree 不可用，用 find . -maxdepth 4 -type f | sort。
38. 展示要求 1：用 tree <infrastructure-directory> 展示目录结构摘要。
39. 展示要求 2：用表格列出所有生成文件及其用途。
40. 展示要求 3：展示用法说明，包括先决条件（AWS 凭证、S3 桶 <BUCKET_NAME>、DynamoDB 表 <TABLE_NAME>）和命令：cd <INFRASTRUCTURE_DIR>；terragrunt run --all init；cd <ENV>/vpc && terragrunt plan；terragrunt run --all plan；terragrunt run --all apply；terragrunt run --all destroy。
41. 展示要求 4：展示占位符替换和密钥检查：所有占位符替换、无旧别名、terraform.source 指向真实源且版本固定、无明文凭证、敏感值来自环境变量/密钥管理器/CI 变量、示例值非敏感。
42. 展示要求 5：展示环境特定说明：必需环境变量表（AWS_PROFILE、AWS_REGION）、先决条件（S3 桶、DynamoDB 表、IAM 权限）、生产保护表（prevent_destroy、exclude）。
43. 展示要求 6：可选给出下一步建议。
44. 最佳实践：用 include 继承根配置；为依赖提供 mock outputs；启用状态加密 encrypt = true；用 generate 块配置 provider；本地/Git 模块用有界版本约束 ~> 5.0；永不硬编码凭证；配置瞬态错误重试；使用注册表模块时可省略 required_providers 避免冲突。
45. 避免反模式：硬编码 account IDs、regions、环境名；缺少 mock outputs；跨模块重复配置；未加密状态；缺失或宽松版本约束（注册表模块除外）；root.hcl 读取不存在的 env.hcl。
46. 弃用属性替换：skip → exclude block；retryable_errors → errors.retry block；run-all → run --all；--terragrunt-* → 无前缀标志；TERRAGRUNT_* → TG_* 环境变量。
47. 生成前按顺序读取：references/common-patterns.md、../terragrunt-validator/references/best_practices.md、相关模板文件。
48. 架构决策树：多环境且共享根 → Pattern A；多环境且不共享根 → 每个环境单独 root.hcl；单环境且需环境检测 → Pattern B；单环境简单 → Pattern B。
49. 验证序列：terragrunt hcl fmt --check；terragrunt hcl validate --inputs；调用 Skill(devops-skills:terragrunt-validator)；修复后重复直到干净。
50. 完成标准：完成并展示架构清单；生成文件一致使用现代 root include 语法（除非明确要求旧版）；注册表源用 tfr:///NAMESPACE/NAME/PROVIDER?version=X.Y.Z；依赖块仅在实际需要时添加；所有占位符替换并报告密钥检查；验证成功或回退检查运行并记录限制。
51. 常见问题：root.hcl 找不到 env.hcl 导致 null 属性错误时，让 root.hcl 环境无关，不用 read_terragrunt_config(find_in_parent_folders("env.hcl"))，改用静态值或 get_env()。
52. 常见问题：provider 与 registry 模块冲突时，移除冲突 generate 块、用 if_exists = "skip" 跳过 versions.tf、清除 .terragrunt-cache 后 terragrunt init。
53. 常见问题：feature flag 报 Unknown variable local 时，确保 feature default 是静态值。
54. 常见问题：子模块找不到 env.hcl 时，确保 env.hcl 存在于环境目录（如 dev/env.hcl）。

适用边界 · 注意事项

• 非 Terragrunt/Terraform 基础设施项目。
• 用户明确要求旧版 terragrunt.hcl 根文件且不允许迁移到 root.hcl。
• 只需要零散片段或文档示例，且用户明确不需要验证。