---
title: Infraプラグイン
description: /infra:* の4スキル(start/design/implement/review)と、architectパイプラインとの境界線
seo:
  image: /ogp.png
---

`infra`はv0.29.0で追加された4番目のプラグインです。クラウド基盤(Terraform/Kubernetesなどの、サーバーやネットワークをコードで組み立てる仕組み)を扱う場合だけ関わる部品で、
`product`/`architect`のような**パイプラインではありません**。マニフェスト(実行順序を管理する設定ファイル)を持たず、`/architect:pipeline`からは呼ばれず、状態管理ダッシュボードにも表れません。

## ナレッジバンドル

infraの回答はすべて、`knowledge/okf-k8s-tf/`というフォルダに収録された23件の文書が根拠になっています。これは
<Tooltip tip="技術知識を「確認できた事実」「設計上の推奨」「まだ答えが出ていない疑問」の3階層に分けて構造化する、ドキュメントの書き方の規格。" headline="OKF(Open Knowledge Format)" cta="用語集で見る" href="/glossary">OKF</Tooltip>
v0.2という規格に沿った、Terraform・Kubernetes・Helm・Kustomize・Argo CD・GitLab CI/CD・Docker+Cosign・Vault・External Secrets・Prometheus/Grafana・Kyvernoをカバーするナレッジバンドル(あらかじめまとめられた技術知識集)です。

このバンドルは**サブモジュール(他リポジトリへの参照)ではなく、ベンダリング(コピーをこのリポジトリに直接格納すること)されています。取得元リポジトリが削除されているため**で、このリポジトリのコピーが正本(source of record、最終的な正解の置き場所)です。

## コマンド

| コマンド | モデル | 何をするか |
|---|---|---|
| `/infra:start` | sonnet | トリアージ(最初の振り分け)。上のナレッジバンドルの解決・鮮度確認・対象環境とクラウドの確定を行い、適切なモードへ振り分ける |
| `/infra:design` | opus | 構成を決定し、設計文書・環境マトリクス(環境ごとの設定差分を一覧にした表)・<Tooltip tip="なぜその設計を選んだか、他の案をなぜ選ばなかったかを記録する文書。" headline="ADR(Architecture Decision Record)" cta="用語集で見る" href="/glossary">ADR</Tooltip>を出力する |
| `/infra:implement` | sonnet | Terraform / Kubernetesマニフェスト / Helm values(Helmという配布形式向けの設定値) / Kustomizeオーバーレイ(環境ごとの差分だけを重ねる仕組み) / CIを、実際のインフラリポジトリに書き込む |
| `/infra:review` | opus | 既存コードまたは設計文書を評価し、重要度付きのfindings(見つかった問題点の記録)を出力する |

`/infra:start`がバンドル・鮮度・環境・クラウドの4点を確定させてから下流に渡すため、各モードのスキルは同じことを聞き直しません。
design → ユーザー確認 → implementという順で進み、合意していない設計のまま実装が進むことはありません。

## 各スキルの詳しい流れ

上の表は概要です。実際に何をしているかをスキルごとに開いて見られます。

<Accordion>
  <AccordionItem title="/infra:start — トリアージ(最初の振り分け)">
    次の4つを確定させてから下流のスキルに渡します。これが決まっていれば、design/implement/reviewは同じことを聞き直しません。

    1. **ナレッジバンドルの解決と鮮度確認。** `tools/update-okf-bundle.sh status --bundle=k8s-tf`を実行し、`stale_after`(この日付を過ぎたら情報が古くなっている可能性がある、という期限)を超えた文書がないか確認する
    2. **対象環境の確定。** `local` / `test` / `staging` / `production`のどれか。複数ならそれぞれに1セクションずつ用意する
    3. **対象クラウドの確定。** AWS / Azure / GCP。マルチクラウドが前提なので、単一クラウドと決め打ちしない
    4. **モードの確定。** 次の基準でどのスキルに振り分けるかを決める

    | ユーザーがしたいこと | 振り分け先 |
    |---|---|
    | 要件から構成を決めたい・技術選定をしたい | `/infra:design` |
    | Terraform/マニフェスト/CIを書いてほしい・直してほしい | `/infra:implement` |
    | 既存コードや設計文書を評価してほしい | `/infra:review` |

    判断に迷うときは質問を1つだけする。「設計してから実装して」のような複合の依頼は、design → ユーザー確認 → implementの順に必ず分割され、合意していない設計のまま実装が進むことはありません。
  </AccordionItem>

  <AccordionItem title="/infra:design — 構成の設計(opus)">
    出力は設計文書・環境マトリクス・ADRです。**実装コードはここでは書きません。**

    1. **要件を数値にする**

        「高可用性」「速い」のような形容詞は要件として扱いません。可用性目標・RTO/RPO(復旧までの目標時間・失ってよいデータ量)・性能・データ保持期間・予算・規制やデータの保存場所の制約を、数値または「仮の値とその理由」として書きます。

    2. **マルチクラウド・環境の前提を確定する**

        クラウド×環境の表を埋めます。空欄は「そこにはデプロイしない」という意味になるので、書き漏らしのままにしません。

    3. **所有者分担を決める**

        どのリソースをTerraform/Argo CD/CI/手動運用のどれが管理するかを表にし、1つのリソースに2つ以上の管理者がいないか(1リソース1所有者)をすぐに確認します。

    4. **レイヤー(L1〜L4)ごとに設計する**

        L1(クラウド固有)からL4(アプリケーション)まで順に、各レイヤーで「環境をまたいで同一にするもの」と「差があってよいもの」を明記します。

    5. **適用フローと変更影響マトリクスを書く**

        誰が何をどの順で適用するかを書き、「Kubernetesのバージョンを上げたら何を同時に確認すべきか」のような、変更したときに影響が及ぶ範囲を表にします。

    6. **環境差分表とプロモーション経路を設計する**

        環境ごとの違いを1ページにまとめ、環境をまたぐ昇格は**イメージダイジェスト単位**(コンテナイメージの内容そのものから計算される固定のハッシュ値。コードのバージョンやタグより一段細かい単位)で行う経路を設計します。

    7. **決定をADRに記録し、Open Questionsを残す**

        2つ以上の選択肢があった判断はすべてADRに記録します。まだ決められないことは「TBD(未定)」として明記し、空欄のままにしません。
  </AccordionItem>

  <AccordionItem title="/infra:implement — 実装(sonnet)">
    合意済みの設計文書があることが前提です。なければ、所有者分担・対象クラウド・対象環境だけを決める簡易設計を先に行います。
    書き込み先は**実際のインフラリポジトリ**です。architectの`generate-infra-code`が書き込む`generated/`とは別の場所で、両者の違いはこのページ下の境界表を参照してください。

    | 対象 | 必須ルールの例 |
    |---|---|
    | Terraform | バージョンを正確に固定し、`.terraform.lock.hcl`をコミットする。状態(state。今のリソースの実態を記録したファイル)は暗号化・アクセス制御されたリモートバックエンドに置き、Gitには含めない |
    | Kubernetesマニフェスト | 素のPodを直接作らずコントローラ(Deployment等)を使う。readiness/livenessプローブ(生死確認)を設定し、PDB(Pod Disruption Budget。メンテナンス等で同時に落としてよいPod数の上限)を決める |
    | Helm | リポジトリ・チャート・バージョンを固定する。1つのリリースの所有者はTerraformのみにする |
    | Kustomize | base(共通の土台)には環境分岐を書かず、環境ごとの違いはオーバーレイだけに閉じ込める |
    | CI(GitLab CI) | 共有テンプレートはタグやコミットSHAで固定する。長期間有効なクラウドの鍵をCI変数に置かず、OIDC(その場限りの短期間だけ有効な認証情報を発行する仕組み)を使う |
    | Docker | ベースイメージをバージョンとダイジェストで固定する。ビルド直後にダイジェストを記録し、スキャン・署名・デプロイまで同じダイジェストを使い回す |
    | シークレット | Vault + External Secrets Operator(外部のシークレット管理からKubernetesへ値を同期する仕組み)で同期し、平文の秘密情報をGit/values/tfvarsに置かない |

    環境ごとに書き込み先と適用者が変わります。

    | 環境 | 適用者 | バンドルの根拠 |
    |---|---|---|
    | local | 開発者本人 | バンドルの対象外 |
    | test | 手順書またはCIの`kubectl apply` | 実装例あり |
    | staging | Argo CD(GitOpsで自動適用) | 実装例あり |
    | production | Argo CD + 承認 | 実装例なし。stagingの設定に承認・保護・同期ウィンドウを加えたものとして設計する |

    実装のたびに、次を必ず報告します: 対象環境、実行した検証コマンドと結果、変更したリソースの所有者、影響が及ぶ関連箇所、環境間の一致(パリティ)への影響、判断できなかったOpen Questions。
  </AccordionItem>

  <AccordionItem title="/infra:review — レビュー(opus)">
    出力は重大度付きのfindings(見つかった問題点の記録)です。各findingは「path:line → 何が → 影響 → 直し方 → 出典」の形で書かれ、**直し方のない指摘は出しません**。

    **最初に必ず確認する3点。** ここで見つかったものは、他のどの指摘よりも先に書かれます。

    1. 所有者の重複(1つのリソースを2つ以上の仕組みが管理していないか)
    2. イメージダイジェストの継続性(ビルド→スキャン→署名→デプロイまで同じダイジェストを使っているか)
    3. シークレットの平文露出(Git/values/tfvars/CIログ/Dockerレイヤーのどこかに秘密情報が平文で残っていないか)

    その後、IaC・Kubernetes・デリバリー・シークレット・可観測性・ポリシーの領域別チェックを行い、**マルチクラウドの節**と**環境パリティ(環境間の一致)の節**を必ず設けます。

    同じコードでも、環境が違えば評価が変わります(抜粋):

    | 項目 | local | test | staging | production |
    |---|---|---|---|---|
    | レプリカ1・冗長性なし | 許容 | 許容 | 要確認 | **NG** |
    | 直接適用(`kubectl apply`など) | 許容 | 意図した設計 | NG(GitOpsであるべき) | **NG** |
    | Gitへの平文シークレット | **NG** | **NG** | **NG** | **NG** |

    最終行のような「どの環境でも例外なくNG」の項目は、「ローカルだから」という理由で見逃されません。

    重大度はCritical/High/Medium/Low/Infoの5段階で、同じ問題でも環境が下がるほど1段階下がるのが基本ルールです(上記の「どの環境でもNG」の項目は例外)。

    よく見つかる問題パターンの例:
    - Kyvernoの`ClusterPolicy`(v1.20で削除予定の古いポリシー形式)がまだ使われている
    - コンテナイメージのタグをメジャーバージョンだけで固定している(例: `docker:27`)。パッチやダイジェストまでは固定していない
    - ビルド後にタグからダイジェストを再解決している(スキャンした対象とデプロイされる対象がずれる原因になる)
    - Argo CDを手動でロールバックしている。正しくはGitのrevert(取り消し)かforward-fix(直したコミットを新たに積む)で戻す
  </AccordionItem>
</Accordion>

## 徹底していること

- **マルチクラウドが前提。** どの回答も単一クラウドを前提にしない。基盤を4つの
  <Tooltip tip="infra固有の4段の分類。L1はクラウド固有(VPC/IAMなど、統一しない)、L2はKubernetes抽象化(Deployment/Serviceなど、完全共通)、L3はプラットフォーム部品(Argo CD/Vaultなど、値だけ差異)、L4はアプリケーション(完全共通)。" headline="レイヤー(L1〜L4)" cta="用語集で見る" href="/glossary">レイヤー</Tooltip>
  に分け、クラウドごとに書き分けるのはL1だけにする。L2〜L4にはクラウド分岐を持ち込まない。3つ以上の差異を共通の形で表現できない場合は、抽象化ではなく分離を選ぶ
- **4つの環境。** base(土台になる共通設定)・chart(Helmのパッケージ)・イメージダイジェスト(コンテナイメージの内容から計算される固定のハッシュ値。テストした実行バイナリと本番で動くものが同一であることを保証する)はどの環境でも同一で、環境ごとの違いは**オーバーレイの中身だけに閉じ込める**。`if env == "production"`のような分岐をbaseに書かない
- **1つのリソースに1人の所有者。** Terraform/Argo CD/CI/手動運用のうち2つ以上が同じリソースを管理している状態は、レビューで最優先のfindingになる。所有者マップ(どのリソースをどの仕組みが管理しているかの一覧表)を最初に作らないと、他のfindingsに優先度をつけられない
- **バンドルが根拠。** 主張には`[foundation/terraform.md]`のような出典が付き、バンドルが扱っていないことは「扱っていない」と明言する

環境の扱いには非対称性があります。`local`はバンドルに一切登場せず、`production`は観測された実装例がありません。そのため`test`/`staging`と同じ確信度では示されません。
productionは「staging + 承認・保護・同期ウィンドウ」として設計され、ADRとして記録されるものであり、既に存在するかのようには書かれません。

## architectパイプラインとの境界

infraのスキルはarchitectの3つのスキルと意図的に重なっています。境界線を分けることで、2つの仕組みが同じアーティファクトを書き合わないようにしています。

| architect | infra | 境界 |
|---|---|---|
| `design-infrastructure` | `/infra:design` | 論理設計 vs 具体設計 |
| `generate-infra-code`(→`generated/`) | `/infra:implement` | スキャフォルディング(足場となるコード) vs 実際のインフラリポジトリへのマージ前提のコード |
| `review-operations` | `/infra:review` | 設計文書のレビュー vs Terraform・マニフェスト・CIのレビュー |

<Panel title="関連ページ">
architectパイプラインの品質・運用系スキル(`design-security`など)は[Architectパイプライン](/skills/architect-pipeline)を、
プラグインのインストール構成は[導入方法](/getting-started/installation)を参照してください。
</Panel>