terraform-aws-annotated-blueprint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Terraform AWS Annotated Blueprint

Terraform AWS 带注释蓝图

要求された構成のTerraformテンプレートを全プロパティに詳細な解説付きで生成するスキル。

本技能可生成符合要求配置、且所有属性均附带详细说明的Terraform模板。

前提条件

以下のMCP serverが必須。利用不可の場合は警告・利用しているAI Agentごとの設定方法を表示し作業を終了する。

必須MCP server:

```
awslabs.terraform-mcp-server
```
- AWSプロバイダードキュメント検索・AWS Well-Architectedガイダンス・セキュリティスキャン
```
aws-knowledge-mcp-server
```
- AWS公式ドキュメント参照用

MCP server設定例:

json

{
  "aws-knowledge-mcp-server": {
    "command": "uvx",
    "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"]
  },
  "awslabs.terraform-mcp-server": {
    "command": "uvx",
    "args": ["awslabs.terraform-mcp-server@latest"],
    "env": {
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}

MCP serverの役割・使い所

```
awslabs.terraform-mcp-server
```
:
- AWSプロバイダードキュメント・実装例の検索
- AWS Well-Architectedガイダンスの参照（設計判断に活用）
- Checkovによるセキュリティスキャン（生成後の検証）
```
aws-knowledge-mcp-server
```
- AWS公式ドキュメント参照

需要以下MCP server。若无法使用，则显示警告及对应AI Agent的设置方法后终止操作。

必需MCP server:

```
awslabs.terraform-mcp-server
```
- AWS提供商文档检索、AWS Well-Architected指南、安全扫描
```
aws-knowledge-mcp-server
```
- 用于参考AWS官方文档

MCP server配置示例:

json

{
  "aws-knowledge-mcp-server": {
    "command": "uvx",
    "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"]
  },
  "awslabs.terraform-mcp-server": {
    "command": "uvx",
    "args": ["awslabs.terraform-mcp-server@latest"],
    "env": {
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}

MCP server的作用与使用场景

```
awslabs.terraform-mcp-server
```
:
- 检索AWS提供商文档及实现示例
- 参考AWS Well-Architected指南（用于设计决策）
- 通过Checkov进行安全扫描（生成后的验证）
```
aws-knowledge-mcp-server
```
- 参考AWS官方文档

重要な原則

重要原则

スキーマが信頼の源泉（Source of Truth）

terraform providers schema -json

から取得したスキーマを正とする。MCPサーバーのドキュメントはスキーマに含まれない補足情報（説明文、設定可能な値の詳細等）の取得に使用する。

Web検索の禁止

インターネット検索は使用しない。情報取得はMCPサーバーのみを使用する。

架构为可信数据源（Source of Truth）

以

terraform providers schema -json

获取的架构为准。MCP server的文档仅用于获取架构未包含的补充信息（如说明、可配置值的详情等）。

禁止使用网络搜索

不得使用互联网搜索。仅可通过MCP server获取信息。

ワークフロー

工作流程

1. 入力の理解

1. 理解输入

ユーザーから

/terraform-aws-annotated-blueprint {概要}

形式で入力を受け取り、作成したいTerraformテンプレートの要件を把握する。

接收用户以

/terraform-aws-annotated-blueprint {概要}

形式提交的输入，明确需要创建的Terraform模板的需求。

2. 作業計画の作成

2. 制定工作计划

チェックボックス付きの計画書を

{プロジェクトルート}/.local/terraform-aws-annotated-blueprint/${provider_version}/

に出力する。

計画書の必須内容:

スキーマ取得（キャッシュがなければ実行）
構築が必要なリソース一覧の生成
各リソースの全プロパティをカテゴリ別にannotation付きで記載
抜け漏れ検証
awslabs.terraform-mcp-serverを用いたCheckovによるセキュリティスキャンおよび指摘事項の修正

質問タグのルール: 独自の判断はせず、意思決定が必要な際は必ずユーザーに質問をする。

判断が必要な箇所は、作業計画書内に

[🤔Question]

タグで質問を追加し、

[✅Answer]

タグで回答フィールドを作成する。 1つのタグにつき質問は1つ。複数の質問はタグを分割する。

markdown

[🤔Question] ここに質問を記載

[✅Answer]

将带有复选框的计划文档输出至

{项目根目录}/.local/terraform-aws-annotated-blueprint/${provider_version}/

路径下。

计划文档必需内容:

获取架构（若缓存不存在则执行）
生成需要构建的资源列表
按类别记录各资源的所有属性并添加注释
遗漏验证
使用awslabs.terraform-mcp-server通过Checkov进行安全扫描并修正指出的问题

提问标签规则: 不得自行判断，当需要做出决策时必须向用户提问。

需要判断的部分，在工作计划文档中添加

[🤔Question]

标签提出问题，并创建

[✅Answer]

标签作为回答字段。每个标签对应一个问题。多个问题需拆分标签。

markdown

[🤔Question] 此处填写问题

[✅Answer]

3. 計画書の更新

3. 更新计划文档

ユーザーからの回答を踏まえて計画書を更新する。質問と回答のペアは削除しない。

根据用户的回答更新计划文档。不得删除问题与回答的配对内容。

4. 作業実行

4. 执行工作

ユーザーから承認を得てから作業を開始する。計画書のチェックボックスを更新しながら進める。

获得用户批准后开始工作。在执行过程中更新计划文档的复选框状态。

スキーマ取得方法

架构获取方法

${プロジェクトルート}/.local/terraform-aws-annotated-blueprint/${provider_version}/schema.json

が既に存在するか確認:

bash

SCHEMA_FILE="${PROJECT_ROOT}/.local/terraform-aws-annotated-blueprint/${provider_version}/schema.json"
if [[ -f "$SCHEMA_FILE" ]]; then
  echo "スキーマファイルが存在します。スキップします。"
else
  echo "スキーマを取得します..."
  # 以下の手順を実行
fi

スキーマが存在しない場合:

プロバイダー設定を作成:

hcl

undefined

检查

${项目根目录}/.local/terraform-aws-annotated-blueprint/${provider_version}/schema.json

是否已存在:

bash

SCHEMA_FILE="${PROJECT_ROOT}/.local/terraform-aws-annotated-blueprint/${provider_version}/schema.json"
if [[ -f "$SCHEMA_FILE" ]]; then
  echo "架构文件已存在，跳过。"
else
  echo "正在获取架构..."
  # 执行以下步骤
fi

当架构不存在时:

创建提供商配置:

hcl

undefined

${プロジェクトルート}/.local/terraform-aws-annotated-blueprint/${provider_version}/providers.tf

${项目根目录}/.local/terraform-aws-annotated-blueprint/${provider_version}/providers.tf

terraform { required_providers { aws = { source = "hashicorp/aws" version = "{provider_version}" } } }


2. スキーマを取得:
```bash
cd ${プロジェクトルート}/.local/terraform-aws-annotated-blueprint/${provider_version}
terraform init
terraform providers schema -json > schema.json

スキーマからリソース情報を抽出:

bash

jq '.provider_schemas["registry.terraform.io/hashicorp/aws"].resource_schemas["{リソース名}"]' schema.json

terraform { required_providers { aws = { source = "hashicorp/aws" version = "{provider_version}" } } }


2. 获取架构:
```bash
cd ${项目根目录}/.local/terraform-aws-annotated-blueprint/${provider_version}
terraform init
terraform providers schema -json > schema.json

从架构中提取资源信息:

bash

jq '.provider_schemas["registry.terraform.io/hashicorp/aws"].resource_schemas["{资源名}"]' schema.json

テンプレート生成ルール

模板生成规则

必須要件

必需要求

スキーマから取得した入力可能な全属性を記載
ネストブロック（block_types）も漏れなく記載
各プロパティにコメントで解説を記載
AWS公式ドキュメントのURLは実在するもののみ記載
推測や誤った情報は絶対に記載しない
利用しないプロパティも削除せずにコメントとして残す

记录从架构中获取的所有可输入属性
不得遗漏嵌套块（block_types）
为每个属性添加注释说明
仅记录真实存在的AWS官方文档URL
绝对不得记录推测或错误信息
即使是不使用的属性也不得删除，需保留为注释

ファイルヘッダー

文件头

hcl

#---------------------------------------------------------------

hcl

#---------------------------------------------------------------

{リソース表示名}

{资源显示名}

#---------------------------------------------------------------

{どのようなAWSリソースをプロビジョニングするかの説明}

{说明该AWS资源的用途}

AWS公式ドキュメント:

AWS官方文档:

- {ドキュメント名}: {URL}

- {文档名}: {URL}

Terraform Registry:

- {URL}

Provider Version: {version}

Generated: {YYYY-MM-DD}

NOTE: 本テンプレートは生成時点の情報に基づきAIが生成しています。

NOTE: 本模板由AI基于生成时的信息创建。

情報が古くなっている可能性、誤りを含む可能性があるため、

信息可能已过时或存在错误，如需准确的最新规格请参考官方文档。

正確な最新仕様は公式ドキュメントを参照してください。

—

#---------------------------------------------------------------

undefined

#---------------------------------------------------------------

undefined

属性の分類

属性分类

テンプレートに含める属性（入力可能）:

```
optional: true
```
を持つ属性
```
required: true
```
を持つ属性

テンプレートから除外する属性（computed only）:

```
computed: true
```
かつ
```
optional
```
がない属性
例:
```
arn
```
,
```
id
```
,
```
tags_all
```

分類確認コマンド:

bash

undefined

模板中需包含的属性（可输入）:

带有
```
optional: true
```
的属性
带有
```
required: true
```
的属性

模板中需排除的属性（仅计算）:

带有
```
computed: true
```
且无
```
optional
```
的属性
示例:
```
arn
```
,
```
id
```
,
```
tags_all
```

分类确认命令:

bash

undefined

入力可能な属性一覧

可输入属性列表

jq -r '.block.attributes | to_entries[] | select(.value.optional == true) | .key' <<< "$SCHEMA"

computed only属性一覧

仅计算属性列表

jq -r '.block.attributes | to_entries[] | select(.value.computed == true and .value.optional != true) | .key' <<< "$SCHEMA"

undefined

jq -r '.block.attributes | to_entries[] | select(.value.computed == true and .value.optional != true) | .key' <<< "$SCHEMA"

undefined

フォーマット

格式

テンプレートの詳細なフォーマットは references/template_example.md を参照。ネストブロックを含むリソースは references/nested_block_example.md も参照。

模板的详细格式请参考references/template_example.md。包含嵌套块的资源还需参考references/nested_block_example.md。

6.1 フォーマットルール

6.1 格式规则

以下のルールを厳守すること。違反はvalidate_template.shで自動検出される。

FR-1: 全コメント日本語

hcl

undefined

请严格遵守以下规则。违反规则的内容会被validate_template.sh自动检测出来。

FR-1: 所有注释使用中文

hcl

undefined

✅ OK

✅ 正确

設定内容: ロググループの名前を指定します。

配置内容: 指定日志组的名称。

❌ NG

❌ 错误

Description: The name of the log group.


**FR-2: 区切り線は `#-------` のみ（`====` 禁止）**
```hcl


**FR-2: 分隔线仅使用`#-------`（禁止使用`====`）**
```hcl

✅ OK

✅ 正确

#---------------------------------------------------------------

基本設定

基本配置

#---------------------------------------------------------------

❌ NG

❌ 错误

============================================================

Basic Configuration

============================================================


**FR-3: プロパティコメントに `設定内容:`, `設定可能な値:`, `省略時:` を使用**
```hcl


**FR-3: 属性注释使用`配置内容:`, `可配置值:`, `省略时:`**
```hcl

✅ OK

✅ 正确

name (Optional, Forces new resource)

設定内容: ロググループの名前を指定します。

配置内容: 指定日志组的名称。

設定可能な値: 1-512文字の文字列

可配置值: 1-512字符的字符串

省略時: Terraformがランダムな一意の名前を生成します。

省略时: Terraform将生成随机唯一名称。

❌ NG

❌ 错误

name (Optional, Forces new resource)

Description: The name of the log group.

Valid values: 1-512 character string

Default: Terraform generates a random unique name.


**FR-4: 機能カテゴリ別グルーピング（Required/Optionalグルーピング禁止）**
```hcl


**FR-4: 按功能类别分组（禁止按Required/Optional分组）**
```hcl

✅ OK: 機能別

✅ 正确: 按功能分组

#-------------------------------------------------------------

暗号化設定

加密配置

#-------------------------------------------------------------

❌ NG: Required/Optionalグルーピング

❌ 错误: 按Required/Optional分组

============================================================

REQUIRED ARGUMENTS

============================================================


**FR-5: ネストブロックヘッダーも `#-----` 統一**
ネストブロックのカテゴリ区切り線もトップレベルと同じ `#-----` 形式を使用。

**FR-6: Attributes Reference 25行以内・コード例禁止**
```hcl


**FR-5: 嵌套块标题也统一使用`#-----`**
嵌套块的类别分隔线需与顶层保持一致的`#-----`格式。

**FR-6: 属性参考（Attributes Reference）控制在25行以内，禁止包含代码示例**
```hcl

✅ OK

✅ 正确

#---------------------------------------------------------------

Attributes Reference (読み取り専用属性)

Attributes Reference (只读属性)

#---------------------------------------------------------------

このリソースは以下の属性をエクスポートします:

本资源将导出以下属性:

- arn: ロググループのARN

- arn: 日志组的ARN

- tags_all: 継承タグを含む全タグマップ

- tags_all: 包含继承标签的完整标签映射

#---------------------------------------------------------------

❌ NG: コード例を含む

❌ 错误: 包含代码示例

output "log_group_arn" {

value = aws_cloudwatch_log_group.example.arn

}


**FR-7: 使用例・ベストプラクティス等の余分なセクション禁止**
テンプレートにはリソース定義とAttributes Referenceのみを記載。使用例、ベストプラクティス、output例等は記載しない。


**FR-7: 禁止添加使用示例、最佳实践等多余章节**
模板中仅可包含资源定义与属性参考内容。不得添加使用示例、最佳实践、output示例等内容。

抜け漏れ検証

遗漏验证

各リソースのテンプレート生成後、検証スクリプトを実行:

bash

bash "${PROJECT_ROOT}/.claude/skills/terraform-aws-annotated-blueprint/lib/validate_template.sh" \
  "${OUTPUT_FILE}" \
  "${RESOURCE_NAME}" \
  "${SCHEMA_FILE}"

FAILが1つでもあれば、該当箇所を修正して再度検証を実行する。全項目PASSになるまで繰り返す。

每个资源的模板生成完成后，执行验证脚本:

bash

bash "${PROJECT_ROOT}/.claude/skills/terraform-aws-annotated-blueprint/lib/validate_template.sh" \
  "${OUTPUT_FILE}" \
  "${RESOURCE_NAME}" \
  "${SCHEMA_FILE}"

若存在任意FAIL项，则修正对应内容后重新执行验证。重复操作直至所有项目均为PASS。

ファイル分割ルール

文件分割规则

以下の内容は別ファイルに分割する：

variables.tf: 入力変数（variable）
locals.tf: ローカル変数（locals）
data.tf: データソース（data）
versions.tf: Terraformバージョン制約とrequired_providers（terraformブロック）
providers.tf: プロバイダー設定（providerブロック）

以下内容需拆分至单独文件：

variables.tf: 输入变量（variable）
locals.tf: 本地变量（locals）
data.tf: 数据源（data）
versions.tf: Terraform版本约束与required_providers（terraform块）
providers.tf: 提供商配置（provider块）

ファイル生成単位

文件生成单位

基本は1リソースにつき1ファイル。ただし以下は1ファイルにまとめる：

IAM role定義（aws_iam_role, aws_iam_policy, aws_iam_role_policy_attachment）
Security groupとそのegress/ingress rule
Route tableとそのルール
Target groupとそのattachment（aws_lb_target_group, aws_lb_target_group_attachment）

ファイル命名規則:

ファイル名に
```
aws
```
は含めない
単一リソース:
```
lambda.tf
```
複数の同一リソース:
```
lambda_parser.tf
```
,
```
lambda_archiver.tf
```

原则上每个资源对应一个文件。但以下内容可合并至一个文件：

IAM角色定义（aws_iam_role, aws_iam_policy, aws_iam_role_policy_attachment）
安全组及其出/入站规则
路由表及其规则
目标组及其关联（aws_lb_target_group, aws_lb_target_group_attachment）

文件命名规则:

文件名中不得包含
```
aws
```
单一资源:
```
lambda.tf
```
多个同类资源:
```
lambda_parser.tf
```
,
```
lambda_archiver.tf
```

依存関係の扱い

依赖关系处理

リソース参照による暗黙的な依存関係を活用する
明示的な
```
depends_on
```
は、暗黙的な依存関係では表現できない場合にのみ使用
不要な
```
depends_on
```
はコードの可読性を下げるため避ける

利用资源引用实现的隐式依赖关系
仅当隐式依赖关系无法表达时，才使用显式的
```
depends_on
```
避免使用不必要的
```
depends_on
```
，以免降低代码可读性

その他ルール

其他规则

IAM policyの定義はdata resourceを使わず、リソースに直接jsonencodeしたポリシーを記載する

IAM策略定义不得使用data resource，需直接在资源中写入经jsonencode处理的策略

Provider最新バージョン取得

获取Provider最新版本

version指定がない場合は以下でTerraform Registry APIから最新バージョンを取得：

bash

curl -s "https://registry.terraform.io/v1/providers/hashicorp/aws" | jq -r '.version'

若未指定版本，则通过以下方式从Terraform Registry API获取最新版本：

bash

curl -s "https://registry.terraform.io/v1/providers/hashicorp/aws" | jq -r '.version'