Infraプラグイン

/infra:* の4スキル(start/design/implement/review)と、architectパイプラインとの境界線

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

ナレッジバンドル

infraの回答はすべて、knowledge/okf-k8s-tf/というフォルダに収録された23件の文書が根拠になっています。これは OKF 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	構成を決定し、設計文書・環境マトリクス(環境ごとの設定差分を一覧にした表)・ADRを出力する
`/infra:implement`	sonnet	Terraform / Kubernetesマニフェスト / Helm values(Helmという配布形式向けの設定値) / Kustomizeオーバーレイ(環境ごとの差分だけを重ねる仕組み) / CIを、実際のインフラリポジトリに書き込む
`/infra:review`	opus	既存コードまたは設計文書を評価し、重要度付きのfindings(見つかった問題点の記録)を出力する

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

各スキルの詳しい流れ

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

/infra:start — トリアージ(最初の振り分け)

次の4つを確定させてから下流のスキルに渡します。これが決まっていれば、design/implement/reviewは同じことを聞き直しません。

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

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

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

/infra:design — 構成の設計(opus)

出力は設計文書・環境マトリクス・ADRです。実装コードはここでは書きません。

要件を数値にする

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

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

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

所有者分担を決める

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

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

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

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

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

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

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

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

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

/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。

/infra:review — レビュー(opus)

出力は重大度付きのfindings(見つかった問題点の記録)です。各findingは「path → 何が → 影響 → 直し方 → 出典」の形で書かれ、直し方のない指摘は出しません。

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

所有者の重複(1つのリソースを2つ以上の仕組みが管理していないか)
イメージダイジェストの継続性(ビルド→スキャン→署名→デプロイまで同じダイジェストを使っているか)
シークレットの平文露出(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(直したコミットを新たに積む)で戻す

徹底していること

マルチクラウドが前提。 どの回答も単一クラウドを前提にしない。基盤を4つのレイヤーに分け、クラウドごとに書き分けるのは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のレビュー