Back to Details

terramate-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Terramate Best Practices

Terramate 最佳实践

Comprehensive guide for Terramate CLI, Cloud, and Catalyst, maintained by Terramate. Contains best practices and usage patterns for stack management, orchestration, code generation, Cloud integration, and Catalyst components/bundles.
由Terramate维护的Terramate CLI、Cloud及Catalyst综合指南，涵盖堆栈管理、编排、代码生成、Cloud集成以及Catalyst组件/包的最佳实践与使用模式。

When to Apply

适用场景

Reference these guidelines when:
  • Creating and organizing Terramate stacks
  • Orchestrating commands across multiple stacks
  • Using code generation to keep configurations DRY
  • Integrating with Terramate Cloud for observability
  • Creating Catalyst components and bundles
  • Setting up CI/CD workflows with Terramate
  • Managing stack dependencies and execution order
在以下场景中可参考本指南：
  • 创建与组织Terramate堆栈
  • 跨多个堆栈编排命令
  • 使用代码生成保持配置DRY（Don't Repeat Yourself）
  • 集成Terramate Cloud以实现可观测性
  • 创建Catalyst组件与包
  • 基于Terramate搭建CI/CD工作流
  • 管理堆栈依赖与执行顺序

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1CLI FundamentalsCRITICAL
cli-
2CLI OrchestrationHIGH
cli-orchestration-
3CLI Code GenerationHIGH
cli-codegen-
4CLI ConfigurationMEDIUM-HIGH
cli-config-
5Terramate CloudMEDIUM-HIGH
cloud-
6Terramate CatalystMEDIUM
catalyst-
7CI/CD IntegrationMEDIUM
cicd-
8Advanced PatternsLOW-MEDIUM
advanced-
优先级类别影响程度前缀
1CLI基础关键
cli-
2CLI编排高
cli-orchestration-
3CLI代码生成高
cli-codegen-
4CLI配置中高
cli-config-
5Terramate Cloud中高
cloud-
6Terramate Catalyst中
catalyst-
7CI/CD集成中
cicd-
8高级模式中低
advanced-

Quick Reference

快速参考

1. CLI Fundamentals (CRITICAL)

1. CLI基础（关键）

  • cli-stack-structure
    - Organize stacks with clear directory structure
  • cli-stack-config
    - Configure stacks with proper stack blocks
  • cli-stack-metadata
    - Use metadata for stack identification and filtering
  • cli-stack-structure
    - 采用清晰的目录结构组织堆栈
  • cli-stack-config
    - 使用正确的堆栈块配置堆栈
  • cli-stack-metadata
    - 利用元数据进行堆栈识别与过滤

2. CLI Orchestration (HIGH)

2. CLI编排（高）

  • cli-orchestration-run
    - Run commands across stacks efficiently
  • cli-orchestration-change-detection
    - Use change detection to limit execution scope
  • cli-orchestration-parallel
    - Leverage parallel execution for independent stacks
  • cli-orchestration-dependencies
    - Manage stack dependencies and execution order
  • cli-orchestration-run
    - 高效跨堆栈运行命令
  • cli-orchestration-change-detection
    - 使用变更检测限制执行范围
  • cli-orchestration-parallel
    - 对独立堆栈采用并行执行
  • cli-orchestration-dependencies
    - 管理堆栈依赖与执行顺序

3. CLI Code Generation (HIGH)

3. CLI代码生成（高）

  • cli-codegen-hcl
    - Use generate_hcl for DRY Terraform code
  • cli-codegen-file
    - Use generate_file for file generation patterns
  • cli-codegen-provider
    - Generate provider configurations dynamically
  • cli-codegen-hcl
    - 使用generate_hcl实现DRY的Terraform代码
  • cli-codegen-file
    - 使用generate_file实现文件生成模式
  • cli-codegen-provider
    - 动态生成提供商配置

4. CLI Configuration (MEDIUM-HIGH)

4. CLI配置（中高）

  • cli-config-globals
    - Use globals for shared configuration across stacks
  • cli-config-lets
    - Use lets for stack-local computed values
  • cli-config-metadata
    - Leverage metadata for stack information
  • cli-config-globals
    - 使用全局配置实现跨堆栈共享配置
  • cli-config-lets
    - 使用lets定义堆栈本地计算值
  • cli-config-metadata
    - 利用元数据获取堆栈信息

5. Terramate Cloud (MEDIUM-HIGH)

5. Terramate Cloud（中高）

  • cloud-integration
    - Set up Cloud connection and authentication
  • cloud-drift-management
    - Configure drift detection and reconciliation
  • cloud-observability
    - Use Cloud dashboard for stack visibility
  • cloud-integration
    - 搭建Cloud连接与认证
  • cloud-drift-management
    - 配置漂移检测与协调
  • cloud-observability
    - 使用Cloud仪表盘实现堆栈可见性

6. Terramate Catalyst (MEDIUM)

6. Terramate Catalyst（中）

  • catalyst-components
    - Create reusable component blueprints
  • catalyst-bundles
    - Define bundles for component composition
  • catalyst-instantiation
    - Instantiate bundles correctly
  • catalyst-components
    - 创建可复用的组件蓝图
  • catalyst-bundles
    - 定义用于组件组合的包
  • catalyst-instantiation
    - 正确实例化包

7. CI/CD Integration (MEDIUM)

7. CI/CD集成（中）

  • cicd-github-actions
    - Set up GitHub Actions workflows
  • cicd-preview-workflows
    - Create preview workflows for PRs
  • cicd-deployment-workflows
    - Configure deployment automation
  • cicd-github-actions
    - 搭建GitHub Actions工作流
  • cicd-preview-workflows
    - 为PR创建预览工作流
  • cicd-deployment-workflows
    - 配置部署自动化

8. Advanced Patterns (LOW-MEDIUM)

8. 高级模式（中低）

  • advanced-workflows
    - Create complex multi-step workflows
  • advanced-codegen-patterns
    - Advanced code generation techniques
  • advanced-workflows
    - 创建复杂的多步骤工作流
  • advanced-codegen-patterns
    - 高级代码生成技术

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:
rules/cli-stack-structure.md
rules/cli-orchestration-run.md
rules/cli-codegen-hcl.md
rules/cloud-integration.md
rules/catalyst-components.md
Each rule file contains:
  • Brief explanation of why it matters
  • Incorrect/anti-pattern example with explanation
  • Correct/best practice example with explanation
  • Additional context and references
阅读单个规则文件获取详细说明与代码示例：
rules/cli-stack-structure.md
rules/cli-orchestration-run.md
rules/cli-codegen-hcl.md
rules/cloud-integration.md
rules/catalyst-components.md
每个规则文件包含：
  • 简要说明该规则的重要性
  • 错误/反模式示例及解释
  • 正确/最佳实践示例及解释
  • 额外背景信息与参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded: 
AGENTS.md
如需查看包含所有扩展规则的完整指南，请参考：
AGENTS.md