terramate-best-practices

Terramate のベストプラクティス

Terramate が管理する Terramate CLI、Cloud、Catalyst の包括的なガイドです。スタック管理、オーケストレーション、コード生成、Cloud との統合、Catalyst のコンポーネント／バンドルに関するベストプラクティスと使用パターンを紹介します。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• Terramate スタックを作成、整理するとき
• 複数のスタックにまたがってコマンドをオーケストレーションするとき
• 構成を DRY に保つためにコード生成を使用するとき
• 可観測性を確保するために Terramate Cloud と統合するとき
• Catalyst のコンポーネントやバンドルを作成するとき
• Terramate を使用して CI/CD ワークフローを設定するとき
• スタックの依存関係と実行順序を管理するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	CLI の基本	CRITICAL	cli-
2	CLI のオーケストレーション	HIGH	cli-orchestration-
3	CLI のコード生成	HIGH	cli-codegen-
4	CLI の構成	MEDIUM-HIGH	cli-config-
5	Terramate Cloud	MEDIUM-HIGH	cloud-
6	Terramate Catalyst	MEDIUM	catalyst-
7	CI/CD 統合	MEDIUM	cicd-
8	高度なパターン	LOW-MEDIUM	advanced-

クイックリファレンス

1. CLI の基本（CRITICAL）

• cli-stack-structure - 明確なディレクトリ構造でスタックを整理する
• cli-stack-config - 適切な stack ブロックでスタックを構成する
• cli-stack-metadata - スタックの識別とフィルタリングにメタデータを使用する

2. CLI のオーケストレーション（HIGH）

• cli-orchestration-run - 複数のスタックにまたがって効率的にコマンドを実行する
• cli-orchestration-change-detection - 変更検出を使用して実行範囲を限定する
• cli-orchestration-parallel - 独立したスタックの並列実行を活用する
• cli-orchestration-dependencies - スタックの依存関係と実行順序を管理する

3. CLI のコード生成（HIGH）

• cli-codegen-hcl - DRY な Terraform コードに generate_hcl を使用する
• cli-codegen-file - ファイル生成パターンに generate_file を使用する
• cli-codegen-provider - プロバイダー構成を動的に生成する

4. CLI の構成（MEDIUM-HIGH）

• cli-config-globals - スタック間で共有する構成に globals を使用する
• cli-config-lets - スタック内で計算する値に lets を使用する
• cli-config-metadata - メタデータを活用してスタック情報を管理する

5. Terramate Cloud（MEDIUM-HIGH）

• cloud-integration - Cloud 接続と認証を設定する
• cloud-drift-management - ドリフト検出と調整を設定する
• cloud-observability - スタックの可視性を確保するために Cloud ダッシュボードを使用する

6. Terramate Catalyst（MEDIUM）

• catalyst-components - 再利用可能なコンポーネントのブループリントを作成する
• catalyst-bundles - コンポーネントを構成するバンドルを定義する
• catalyst-instantiation - バンドルを正しくインスタンス化する

7. CI/CD 統合（MEDIUM）

• cicd-github-actions - GitHub Actions ワークフローを設定する
• cicd-preview-workflows - PR のプレビューワークフローを作成する
• cicd-deployment-workflows - デプロイの自動化を構成する

8. 高度なパターン（LOW-MEDIUM）

• advanced-workflows - 複雑なマルチステップワークフローを作成する
• advanced-codegen-patterns - 高度なコード生成手法

使用方法

詳しい説明とコード例については、個々のルールファイルをお読みください。

rules/cli-stack-structure.md
rules/cli-orchestration-run.md
rules/cli-codegen-hcl.md
rules/cloud-integration.md
rules/catalyst-components.md

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの不適切な例／アンチパターン
• 説明付きの適切な例／ベストプラクティス
• 追加のコンテキストと参考資料

完全版ドキュメント

すべてのルールを詳しく解説した完全なガイドについては、AGENTS.md を参照してください。