infra 變更走 code 流程

infra 變更的標準路徑是 PR → plan → review diff → 合併 → apply。這個順序的核心責任是把「執行前先看清楚要改什麼」變成強制步驟，而不是 apply 之後才從事故裡發現改錯了。每個環節各自承擔一段審查責任，少掉任一段，infra 就退回到不可審查的狀態。

plan 是整條鏈最關鍵的一環

terraform plan 把當前 state、雲端實際資源、與目標設定三方比對，產出一份「會新增 / 修改 / 刪除哪些資源」的 diff。這份 diff 是 review 的對象：reviewer 直接看 plan 算出來的實際變更，而非讀 HCL 自行想像結果。

plan 輸出裡最關鍵的判讀訊號是操作類型。+ 是新增，~ 是就地更新，- 是銷毀，-/+ 是先銷毀再重建。前兩者多數情境是安全的，後兩者需要逐行細看。改一個看似無害的欄位可能觸發整個資源重建（-/+），例如某些雲資源的 name 或 identifier 是 immutable 屬性，改它的唯一方式就是銷毀再建。對有狀態的服務（RDS、帶資料的 EBS volume），-/+ 代表資料遺失或停機。Review 階段抓到這個 -/+，比 apply 到一半才發現便宜太多。

 1# plan 輸出中要特別警惕的標記
 2# forces replacement  — 某個 immutable 屬性被修改，將觸發銷毀重建
 3# must be replaced    — 跟上面同義，Terraform 新版的表達方式
 4# will be destroyed   — 資源將被刪除
 5
 6  # aws_db_instance.primary must be replaced
 7  -/+ resource "aws_db_instance" "primary" {
 8      ~ identifier = "app-prod" -> "app-production"  # forces replacement
 9        ...
10    }

把 plan 結果貼回 PR

把 plan 結果貼回 PR 是讓 review 真正生效的做法。流程上，PR 觸發 CI 跑 plan，plan 輸出回貼成 PR comment，reviewer 連同程式碼 diff 一起看；approve 後才允許合併，合併才觸發 apply。

這裡有個取捨：plan 與 apply 之間若隔了很久，雲端實際狀態可能已經漂移（有人手動改了、或別的 PR 先 apply 了），導致 apply 時的 plan 跟 review 時看到的不一致。應對方式分保守與務實兩種。保守做法是 apply 前重跑一次 plan 並比對結果 — 一致才繼續，不一致就中斷。務實做法是在合併觸發 apply 時自動跑 plan 並只在無 destroy / replace 時自動執行，有 destroy / replace 就停下來要人確認。多數團隊從務實做法開始，到遇過一次 plan-apply 不一致的事故後才升級到保守做法。

apply 失敗的回退邊界

infra apply 不像程式碼部署可以直接 rollback 到上一版 image — 中途失敗時部分資源已經建立、state 可能處於半完成狀態。例如 apply 建了一個新 subnet 但在建 route table 時 timeout，此時 subnet 存在於雲端和 state 裡，route table 只在雲端不在 state 裡（或反過來），下一次 plan 的計算基礎就不精準。

應對的紀律是：apply 失敗後，先跑一次 terraform plan 確認 state 與現實的差距，再決定是修正 code 重新 apply 還是手動清理殘留資源後 terraform state rm。在清理之前不要再改 code、不要連發第二次 apply — 第二次 apply 在不確定的 state 上跑，可能把問題擴大。

PR 流程的價值在這裡不只是事前審查，也是事後可追溯：每次變更都對應一個 commit 與一個 PR，要回溯時知道是哪次改的、為什麼改、誰 review 的。

fmt 與 validate：最便宜的第一道檢查

fmt 與 validate 是進到任何安全掃描之前的基礎檢查，責任是擋掉格式不一致與語法 / 型別錯誤這類不需要動腦判斷的問題。它們跑得快（通常不到五秒）、沒有誤判空間，適合放在 CI 最前面當作快速 fail 的關卡。

terraform fmt -check 驗證程式碼是否符合標準排版。它本身不影響基礎設施行為，價值在於消除 diff 噪音：當每個人的編輯器縮排習慣不同，PR diff 會混入大量純排版變動，把真正的邏輯變更淹沒，reviewer 更容易看漏。統一格式後，diff 裡剩下的就是語意變更。在本地開發階段配合 editor plugin 或 pre-commit hook 在存檔時自動 fmt，讓 CI 的 fmt check 幾乎不會再 fail — 它存在的意義是攔住那些沒裝 plugin 的人。

validate 則檢查設定在語法與內部一致性上是否成立 — reference 到不存在的變數、型別不匹配、必填參數缺漏、module 呼叫的 source 解析不了，這些在 validate 階段就會報錯，不必等到 plan 連線雲端才發現。validate 需要先跑 terraform init，但可以用 -backend=false 跳過連線 state backend，這樣在 CI 裡不需要雲端憑證就能跑完。

 1# .github/workflows/terraform.yml — plan 前的基礎檢查
 2jobs:
 3  validate:
 4    runs-on: ubuntu-latest
 5    steps:
 6      - uses: actions/checkout@v4
 7      - uses: hashicorp/setup-terraform@v3
 8      - run: terraform fmt -check -recursive
 9      - run: terraform init -backend=false
10      - run: terraform validate

判讀上，fmt 與 validate 失敗代表的是「這份 code 還沒準備好被認真 review」，屬於作者自己該先修掉的問題，不該佔用 reviewer 注意力。把它們設成 CI 必過的 gate，作者在本地就會先跑、先修，PR 送出時已經是乾淨的。

tflint / checkov / tfsec：抓壞寫法與安全漏洞

fmt 與 validate 確認 code「語法正確」，但語法正確的設定仍然可能是危險的設定。tflint、checkov、tfsec 這類靜態掃描工具承擔的是「語意正確」這層：在不實際建立資源的前提下，從 HCL 裡比對已知的壞寫法與安全反模式，把問題擋在 plan 之前。它們補的是 reviewer 肉眼容易漏掉的盲區 — 人會看漏一個 0.0.0.0/0，規則不會。

三者的側重

checkov 與 tfsec 的覆蓋範圍有重疊（都會掃 S3 公開與 SG 全開），差別在規則來源與報告格式。checkov 的規則對標 CIS benchmark 和多雲合規框架（AWS、Azure、GCP、Kubernetes），tfsec 更專注在 Terraform HCL 結構。兩者跑在一起時，重複的命中可以用其中一個的 skip 標記豁免。

兩個最常攔下的反模式

S3 bucket 對外公開。一個漏設 block_public_access 或 ACL 寫成 public-read 的 bucket，會讓裡面的物件對整個網際網路可讀。這類設定在 HCL 裡只是一兩行，肉眼 review 時很容易因為「看起來像樣板」而放過，但後果是資料外洩。checkov 規則 CKV_AWS_19（S3 bucket 未啟用 server-side encryption）和 CKV_AWS_53（block public access 未全開）會標記這類漏洞：

 1# checkov 會攔下的寫法 — 缺少 block_public_access
 2resource "aws_s3_bucket" "data" {
 3  bucket = "acme-customer-data"
 4}
 5
 6# 正確寫法 — 顯式關閉公開存取
 7resource "aws_s3_bucket_public_access_block" "data" {
 8  bucket                  = aws_s3_bucket.data.id
 9  block_public_acls       = true
10  block_public_policy     = true
11  ignore_public_acls      = true
12  restrict_public_buckets = true
13}

Security group 對全世界開放。一條 ingress 寫成 cidr_blocks = ["0.0.0.0/0"] 加上 port 22 或 3306，等於把 SSH 或資料庫埠暴露給全網掃描器。tfsec 與 checkov 都會標記這種「敏感埠 + 全開 CIDR」的組合。這條規則跟模組三：網路地基講的 security group 收斂原則是同一件事的兩端 — 模組三教怎麼把規則寫對，本章用靜態掃描確保寫錯時擋得下來。

1# 三道掃描串在一起，任一 fail 就中斷
2tflint --recursive
3checkov -d . --quiet --compact
4tfsec . --soft-fail=false

命中是候選不是判決

判讀這些工具的命中時，要區分「真漏洞」與「情境合理的例外」。並非每個 0.0.0.0/0 都是錯 — 一個對外的 HTTPS load balancer 在 port 443 開全網是設計本意。所以掃描的命中是候選不是判決。

多數工具支援用行內註解標記豁免。checkov 用 #checkov:skip=CKV_AWS_260:ALB 443 對外是設計本意，tfsec 用 #tfsec:ignore:aws-elb-alb-not-public。豁免的紀律是：每個 skip 都要寫理由、要在 PR 裡可見。沒有理由的 skip 跟關掉整條規則沒有差別 — review 時看到無理由的 skip 應該當成跟看到裸 0.0.0.0/0 一樣的警報。

把例外顯式化、留下為什麼豁免的紀錄，比關掉整條規則安全。隨時間累積的 skip 也要定期盤點：某個當初合理的例外，在架構演進後可能已經不再合理。

Atlantis 與 GitHub Actions：自動化 plan 與 apply

把上述流程自動化，需要一個能監聽 PR 事件、在對的時機跑 plan 與 apply 的執行層。兩種常見做法是直接用 CI 平台（如 GitHub Actions）寫 workflow，或用 Atlantis 這類專為 Terraform PR 流程設計的工具。

Atlantis

Atlantis 是一個常駐服務，掛在 git 平台的 webhook 上。PR 開啟時它自動跑 plan 並把結果貼回 PR comment，reviewer approve 後在 PR 留言 atlantis apply，它才執行 apply 並回報結果。它的價值在於把「誰能 apply、apply 前要不要 approve、plan 結果在哪看」這些規則收斂成一致的、可設定的流程。

Atlantis 內建的 state lock 語意在多 PR 並行時特別有用：當兩個 PR 都改到同一個 Terraform project，第二個 PR 的 plan 會被 lock 擋住，直到第一個 apply 完成或 PR 關閉。這避免了兩個 PR 各自拿到的 plan 基於不同的 state 快照、apply 時互相覆蓋的問題。用 GitHub Actions 要自己實作這個 lock 邏輯（通常靠 Terraform 自己的 state lock + workflow concurrency group），複雜度高得多。

Atlantis 的代價是它本身是一個要部署、要升級、要保護的常駐服務 — 它持有對雲端的寫入權限，所以它的部署環境必須嚴格控制存取。

GitHub Actions

GitHub Actions workflow 的優點是不必額外維運服務、跟既有 CI 共用同一套 runner。缺點是 apply 的 gating 邏輯要自己用 workflow 條件拼出來。一個完整的 workflow 通常分成兩個 job：PR 觸發 plan job（跑 fmt / validate / scan / plan、把結果貼回 PR），合併到 main 才觸發 apply job。

無論哪種執行層，自動化的 apply 都需要對雲端的寫入權限，而這個權限怎麼來是整條管線的安全根基。這裡正是模組二：身分與憑證地基鋪設的 OIDC 兌現的地方 — 管線不該存放長期的 access key，而是在 runner 執行時用 OIDC 向雲端換取短期 token。

 1# 合併到主幹後，用 OIDC 換短期憑證再 apply（呼應模組二）
 2jobs:
 3  apply:
 4    if: github.ref == 'refs/heads/main'
 5    runs-on: ubuntu-latest
 6    permissions:
 7      id-token: write   # 允許 runner 取得 OIDC token
 8      contents: read
 9    steps:
10      - uses: actions/checkout@v4
11      - uses: aws-actions/configure-aws-credentials@v4
12        with:
13          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
14          aws-region: ap-northeast-1
15      - uses: hashicorp/setup-terraform@v3
16      - run: terraform init
17      - run: terraform apply -auto-approve

選型判準

判讀自動 apply 的邊界：對會觸發資源重建或刪除的高風險 plan，多數團隊會保留人工 apply 的關卡（Atlantis 的手動 atlantis apply、或 workflow 加 environment protection rule 要人按確認），不讓這類變更在合併瞬間無人看管地執行。自動化的目的是消除重複勞動與人為遺漏，不是把判斷也一起省掉。

知識留在 code，而不是留在個人腦中

走完整套 PR 流程後，infra 的真正收穫是知識從個人的記憶移到了 repo 裡。每一次「為什麼這個 security group 開這個埠」「為什麼這台機器選這個 instance type」的決策，都以 code + PR 描述 + review 討論的形式留下，新人讀 repo 就能還原當初的判斷，不必去問那個「只有他懂 infra」的人。基礎設施可被閱讀，等於它可被交接。PR 流程上線後，管理層可以從 repo 的 PR merge 歷史與 plan comment 確認所有 infra 變更都經過提案與審查——這本身就是稽核要求的變更紀錄證據，不需要額外產出。

git revert 的能力與邊界

可 revert 是 PR 流程最直接的兌現。當某次變更引發問題，回退手段是 git revert 那個 commit 再走一次 PR 流程，讓基礎設施回到變更前的設定 — 跟回退一段壞掉的程式碼是同一個動作。對照手動操作的舊狀態：回退靠的是當事人記得自己改了什麼、手動在 Console 改回去，記錯或人不在就無從回退。把變更歷史留在 git，回退就從「依賴某人的記憶」變成「依賴版本紀錄」。

這份 revert 能力的邊界要講清楚。revert code 救得回的是「設定」，救不回已經被銷毀的狀態與資料：

• revert 掉一個刪除 RDS 的 commit，只是讓設定回到「該資源應該存在」。apply 時 Terraform 會試圖建一個新的空資料庫 — 但被刪掉的資料庫裡的資料不會跟著回來。
• rename 或 replace 類的變更 revert 後，可能再觸發一次資源重建 — 因為 identifier 又改回去了，而 identifier 是 immutable 屬性。
• apply 到一半失敗的 state 不能直接 revert code 修復，得先處理 state 與雲端現實的不一致。

stateful 變更的真正回退仍然靠備份與快照，這正是模組五：核心服務上 IaC stateful 處理與模組八：治理好習慣 secret / state 保護要顧的事。把 git revert 當「設定層回退」就誠實，把它當「資料層回退」就會在事故裡踩空。

知識共享的判讀訊號

判讀一個團隊是否確實把知識留在 code 的訊號：當主要負責 infra 的人請假，其他人能不能只靠讀 repo 就理解現狀並安全地改一個小設定。如果答案是「得等他回來」，那不論工具鏈多完整，知識還在個人腦中，PR 流程只是形式。這個訊號比任何工具設定都更能反映 infra 的成熟度。

讓知識真正從個人腦中搬進 repo 的方式，除了 PR 流程本身，還需要組織層的配合 — 刻意的 review 輪替、on-call 輪值、配對操作。這條路線在模組九：怎麼把 infra 推動起來展開到組織層。本章解決的是技術機制 — code 留得住知識；模組九解決的是怎麼讓團隊實際願意走這套流程、把知識交出來。

跨分類引用

• → CI/CD 教學：infra 管線用的就是這套驗證 / 發布 gate，plan / apply 對應 build / deploy 階段
• → 模組二：身分與憑證地基：管線用 OIDC 取得 apply 權限，本章是該章 OIDC 設計的回報兌現處
• → 模組三：網路地基：security group 收斂原則，本章用 tfsec / checkov 在 CI 攔下寫錯的全開規則
• → 模組五：核心服務上 IaC：stateful 資源的保護策略，git revert 救不回資料層
• → 模組八：治理好習慣：secret / state 保護
• → 模組九：怎麼把 infra 推動起來：本章把知識留在 code 的技術機制，在該章展開成組織層的採用與知識共享
• → backend 模組七：資安與資料保護：S3 公開、敏感埠全開這類掃描攔截的反模式，對應的資料保護原則
• → 團隊權限分級：權限變更走 PR 流程，讓 policy 調整有審查紀錄
• → 職務交接設計：PR 歷史是交接時的知識載體
• → Terraform CI Pipeline 設定指南：GitHub Actions 完整 workflow
• → checkov 與 tfsec 規則配置：規則選擇、豁免管理、CI 整合

infra 變更走 code 流程

infra 變更的標準路徑是 PR → plan → review diff → 合併 → apply。這個順序的核心責任是把「執行前先看清楚要改什麼」變成強制步驟，而不是 apply 之後才從事故裡發現改錯了。每個環節各自承擔一段審查責任，少掉任一段，infra 就退回到不可審查的狀態。

terraform plan 是這條鏈裡最關鍵的一環。它把當前 state、雲端實際資源、與目標設定三方比對，產出一份「會新增 / 修改 / 刪除哪些資源」的 diff。這份 diff 是 review 的對象：reviewer 直接看 plan 算出來的實際變更，而非讀 HCL 自行想像結果。一個容易被低估的判讀訊號是 plan 裡的 destroy 與 replace（顯示為 -/+）— 改一個看似無害的欄位（例如某些雲資源的 name、或資料庫的 identifier）可能觸發整個資源重建，對有狀態的服務代表資料遺失或停機。Review 階段抓到這個 -/+，比 apply 到一半才發現便宜太多。

把 plan 結果貼回 PR 是讓 review 真正生效的做法。流程上，PR 觸發 CI 跑 plan，plan 輸出回貼成 PR comment，reviewer 連同程式碼 diff 一起看；approve 後才允許合併，合併才觸發 apply。這裡有個取捨：plan 與 apply 之間若隔了很久，雲端實際狀態可能已經漂移（有人手動改了、或別的 PR 先 apply 了），導致 apply 時的 plan 跟 review 時看到的不一致。多數團隊在 apply 階段會重跑一次 plan 並要求它與 review 時一致，代價是流程多一道、但換到「review 看到的就是實際執行的」這個保證。

風險邊界落在 apply 失敗的回退上。infra apply 不像程式碼部署可以直接 rollback 到上一版 image — 中途失敗時部分資源已經建立、state 可能處於半完成狀態。所以 PR 流程的價值不只在事前審查，也在事後可追溯：每次變更都對應一個 commit 與一個 PR，要回溯時知道是哪次改的、為什麼改、誰 review 的。

fmt 與 validate：最便宜的第一道檢查

fmt 與 validate 是進到任何安全掃描之前的基礎檢查，責任是擋掉格式不一致與語法 / 型別錯誤這類不需要動腦判斷的問題。它們跑得快、沒有誤判空間，適合放在 CI 最前面當作快速 fail 的關卡。

terraform fmt -check 驗證程式碼是否符合標準排版。它本身不影響基礎設施行為，價值在於消除 diff 噪音：當每個人的編輯器縮排習慣不同，PR diff 會混入大量純排版變動，把真正的邏輯變更淹沒，reviewer 更容易看漏。統一格式後，diff 裡剩下的就是語意變更。validate 則檢查設定在語法與內部一致性上是否成立 — reference 到不存在的變數、型別不匹配、必填參數缺漏，這些在 validate 階段就會報錯，不必等到 plan 連線雲端才發現。

判讀上，fmt 與 validate 失敗代表的是「這份 code 還沒準備好被認真 review」，屬於作者自己該先修掉的問題，不該佔用 reviewer 注意力。把它們設成 CI 必過的 gate，作者在本地就會先跑、先修，PR 送出時已經是乾淨的。

 1# .github/workflows/terraform.yml — plan 前的基礎檢查
 2jobs:
 3  validate:
 4    runs-on: ubuntu-latest
 5    steps:
 6      - uses: actions/checkout@v4
 7      - uses: hashicorp/setup-terraform@v3
 8      - run: terraform fmt -check -recursive
 9      - run: terraform init -backend=false
10      - run: terraform validate

tflint / checkov / tfsec：抓壞寫法與安全漏洞

fmt 與 validate 確認 code「語法正確」，但語法正確的設定仍然可能是危險的設定。tflint、checkov、tfsec 這類靜態掃描工具承擔的是「語意正確」這層：在不實際建立資源的前提下，從 HCL 裡比對已知的壞寫法與安全反模式，把問題擋在 plan 之前。它們補的是 reviewer 肉眼容易漏掉的盲區 — 人會看漏一個 0.0.0.0/0，規則不會。

這三者的側重不同，組合起來覆蓋面才完整。tflint 偏向 provider 層的正確性與慣例規範：用了已棄用的參數、instance type 在該 region 不存在、命名不符規範。checkov 與 tfsec 偏向安全與合規：掃的是會造成資料外洩或權限過大的設定。兩個最常被它們攔下、也最常釀成真實事故的模式，值得單獨說明。

第一個是 S3 bucket 對外公開。一個漏設 block_public_access 或 ACL 寫成 public-read 的 bucket，會讓裡面的物件對整個網際網路可讀。這類設定在 HCL 裡只是一兩行，肉眼 review 時很容易因為「看起來像樣板」而放過，但後果是資料外洩。checkov 有專門規則比對 bucket 的 public access 設定，命中就讓 CI fail，逼作者在合併前說明或修正。

第二個是 security group 對全世界開放。一條 ingress 寫成 cidr_blocks = ["0.0.0.0/0"] 加上 port 22 或 3306，等於把 SSH 或資料庫埠暴露給全網掃描器。tfsec 與 checkov 都會標記這種「敏感埠 + 全開 CIDR」的組合。這條規則跟模組三：網路地基講的 security group 收斂原則是同一件事的兩端 — 模組三教怎麼把規則寫對，本章用靜態掃描確保寫錯時擋得下來。

1# 三道掃描串在一起，任一 fail 就中斷
2tflint --recursive
3checkov -d . --quiet --compact
4tfsec . --soft-fail=false

判讀這些工具的命中時，要區分「真漏洞」與「情境合理的例外」。並非每個 0.0.0.0/0 都是錯 — 一個對外的 HTTPS load balancer 在 port 443 開全網是設計本意。所以這些掃描的命中是候選不是判決：多數工具支援用行內註解標記豁免（例如 checkov 的 #checkov:skip），代價是豁免要寫理由、要被 review，避免變成無聲略過。把例外顯式化、留下為什麼豁免的紀錄，比關掉整條規則安全。

Atlantis 與 GitHub Actions：自動化 plan 與 apply

把上述流程自動化，需要一個能監聽 PR 事件、在對的時機跑 plan 與 apply 的執行層。兩種常見做法是直接用 CI 平台（如 GitHub Actions）寫 workflow，或用 Atlantis 這類專為 Terraform PR 流程設計的工具。Atlantis 是一個常駐服務，掛在 git 平台的 webhook 上：PR 開啟時它自動跑 plan 並把結果貼回 PR comment，reviewer approve 後在 PR 留言 atlantis apply，它才執行 apply 並回報結果。它的價值在於把「誰能 apply、apply 前要不要 approve、plan 結果在哪看」這些規則收斂成一致的、可設定的流程，而不是散落在各 repo 各自的 workflow 腳本裡。

選哪一種是機會成本的取捨。GitHub Actions workflow 的優點是不必額外維運一個服務、跟既有 CI 共用同一套權限與 runner；缺點是 apply 的 gating 邏輯（approve 後才能 apply、apply lock 避免兩個 PR 同時改同一份 state）要自己用 workflow 條件拼出來。Atlantis 的優點是這些 gating 與 state lock 是內建語意、跨多 repo 一致；缺點是它本身是一個要部署、要升級、要保護的常駐服務。團隊 repo 少、流程簡單時 Actions 划算；管理大量 Terraform repo、需要統一 apply 治理時 Atlantis 划算。

無論哪種執行層，自動化的 apply 都需要對雲端的寫入權限，而這個權限怎麼來是整條管線的安全根基。這裡正是模組二：身分與憑證地基鋪設的 OIDC 兌現的地方 — 管線不該存放長期的 access key，而是在 runner 執行時用 OIDC 向雲端換取短期 token。模組二講的是怎麼建立這個信任關係，本章是它的回報處：因為有了 OIDC，自動 apply 才能在不持有靜態憑證的前提下安全執行，憑證外洩的攻擊面從「一把長期金鑰」縮到「單次執行的短期 token」。

 1# 合併到主幹後，用 OIDC 換短期憑證再 apply（呼應模組二）
 2jobs:
 3  apply:
 4    if: github.ref == 'refs/heads/main'
 5    runs-on: ubuntu-latest
 6    permissions:
 7      id-token: write   # 允許 runner 取得 OIDC token
 8      contents: read
 9    steps:
10      - uses: actions/checkout@v4
11      - uses: aws-actions/configure-aws-credentials@v4
12        with:
13          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
14          aws-region: ap-northeast-1
15      - uses: hashicorp/setup-terraform@v3
16      - run: terraform init
17      - run: terraform apply -auto-approve

判讀自動 apply 的邊界時，要留意它不適合所有變更。對會觸發資源重建或刪除的高風險 plan，多數團隊會保留人工 apply 的關卡（Atlantis 的手動 atlantis apply、或 workflow 加 environment protection rule 要人按確認），不讓這類變更在合併瞬間無人看管地執行。自動化的目的是消除重複勞動與人為遺漏，不是把判斷也一起省掉。

知識留在 code，而不是留在個人腦中

走完整套 PR 流程後，infra 的真正收穫是知識從個人的記憶移到了 repo 裡。每一次「為什麼這個 security group 開這個埠」「為什麼這台機器選這個 instance type」的決策，都以 code + PR 描述 + review 討論的形式留下，新人讀 repo 就能還原當初的判斷，不必去問那個「只有他懂 infra」的人。這是這個模組從第一章開始累積的目的地：基礎設施可被閱讀，等於它可被交接。

可 revert 是這套機制最直接的兌現。當某次變更引發問題，回退手段是 git revert 那個 commit 再走一次 PR 流程，讓基礎設施回到變更前的設定 — 跟回退一段壞掉的程式碼是同一個動作。對照「只有我懂 infra」的舊狀態：那時候回退靠的是當事人記得自己改了什麼、手動在 console 改回去，記錯或人不在就無從回退。把變更歷史留在 git，回退就從「依賴某人的記憶」變成「依賴版本紀錄」。

這份 revert 能力的邊界要講清楚，跟本章前面講的 apply 半完成 state 是同一個誠實。revert code 救得回的是「設定」，救不回已經被銷毀的狀態與資料：revert 掉一個刪除 stateful 資源的 commit，只是讓設定回到「該資源存在」，但被刪掉的資料庫內容不會跟著回來；rename 或 replace 類的變更 revert 後，可能再觸發一次資源重建。所以 stateful 變更的真正回退仍然靠備份與快照，這正是模組五 stateful 處理與模組八 secret / state 保護要顧的事。把 git revert 當「設定層回退」就誠實，把它當「資料層回退」就會在事故裡踩空。

這條知識共享的路線會在模組九：怎麼把 infra 推動起來展開到組織層。本章解決的是技術機制 — code 留得住知識；模組九解決的是怎麼讓一個習慣手動操作的團隊真的願意走這套流程、把知識交出來。技術上能審查、能回溯、能交接是前提，但讓團隊實際採用它是另一層問題。

判讀一個團隊是否真的把知識留在 code 的訊號很具體：當主要負責 infra 的人請假，其他人能不能只靠讀 repo 就理解現狀並安全地改一個小設定。如果答案是「得等他回來」，那不論工具鏈多完整，知識還在個人腦中，PR 流程只是形式。這個訊號比任何工具設定都更能反映 infra 的成熟度。

章節文章

跨分類引用

• → CI/CD 教學：infra 管線用的就是這套驗證 / 發布 gate，plan / apply 對應 build / deploy 階段
• → 模組二：身分與憑證地基：管線用 OIDC 取得 apply 權限，本章是該章 OIDC 設計的回報兌現處
• → 模組三：網路地基：security group 收斂原則，本章用 tfsec / checkov 在 CI 攔下寫錯的全開規則
• → 模組九：怎麼把 infra 推動起來：本章把知識留在 code 的技術機制，在該章展開成組織層的採用與知識共享
• → backend 模組七：資安與資料保護：S3 公開、敏感埠全開這類掃描攔截的反模式，對應的資料保護原則

寫作 review 的 surface 包含正文與 metadata surface。 Title、description、frontmatter、heading、link label、MOC 索引條都是讀者入口與 grep 入口；它們和正文共同建立讀者第一個概念錨點。正文通過 multi-pass review 只代表 body surface 收斂，metadata surface 仍要跑同一套意圖、語氣、grep-ability 與索引一致性檢查。

判別問題：「讀者看到這篇文章之前，會先看到哪些文字？這些文字有沒有跟正文跑同一輪 review？」

WARP 分析摘要

反向驗證：有些標題可以保留對照句型，條件是正文需要讀者先排除常見誤解，且標題本身同時給出正向概念錨點。這次的正文已能用「資安作為風險路由系統」直接建立錨點，對照句型放在正文的論證段更穩定。

情境

建立 content/backend/07-security-data-protection/security-as-risk-routing-system.md 時，文章責任已經寫成「把資安從檢查項目轉成工程路由語言」。正文段落也使用了正向定義：資安路由系統先判斷風險落點，再選擇控制面。

問題出現在讀者入口：

• Frontmatter title 使用 資安不是 Checklist：它是風險路由系統
• content/backend/07-security-data-protection/_index.md 的索引條沿用同一個 link label
• Review 討論集中在正文與章節內容，title / MOC hook 沒被列為同一輪檢查對象

這個問題的主因是 review surface enumeration 漏列：執行者知道要跑正向陳述檢查，但心中 scope 等於「正文段落」，沒有把 metadata surface 視為同等重要的文字。

理想做法

第一步：先列出本次產出的所有 surface

寫作前先列出本次會產生或修改的文字位置。例：

 1content/backend/07-security-data-protection/security-as-risk-routing-system.md
 2- frontmatter.title
 3- frontmatter.description
 4- body headings
 5- body paragraphs
 6- link labels
 7
 8content/backend/07-security-data-protection/_index.md
 9- table link label
10- table topic
11- table responsibility

這份清單是 review 的 surface enumeration。它補足 #96 適用範圍要展開成 file enumeration 的單檔內版本：#96 先列「哪些檔」，本卡再列「檔內哪些文字位置」。

第二步：每一輪 frame 都掃所有 surface

Multi-pass review 的每輪 frame 都要套到 surface 清單上：

Surface enumeration 讓「我有跑正向陳述 pass」變成可驗證動作，而不只是抽象自我宣告。

第三步：用 grep 補字面層掃描

正向陳述是語意判斷，但第一層候選可以用 grep 找出：

1rg -n "不行|不可以|不是|不要|無法|不能" \
2  content/backend/07-security-data-protection/security-as-risk-routing-system.md \
3  content/backend/07-security-data-protection/_index.md

grep 命中代表「需要判讀」，不代表自動違規。合法的對照句型要回到 #94 正向改寫要保留對照論據 的判準：有正向錨點、有對照原因、有適用情境。

沒這樣做的麻煩

讀者入口會先傳遞舊 frame

Title 與 MOC hook 是讀者先看到的文字。正文即使已經建立正向概念，入口若仍用負向 hook，讀者第一個 mental model 仍會被帶回「排除某種做法」而非「建立某個責任」。入口 frame 會影響後續閱讀方式。

Search surface 會保留錯誤概念錨點

Title、description、link label 是搜尋結果與 grep 最容易命中的位置。metadata surface 沒跑 grep-ability 與 positive wording，錯誤概念會比正文更容易被找到，長期變成知識庫中的主要入口。

Review 報告會產生 coverage illusion

只寫「已跑 positive wording pass」但沒有列 surface，review 報告會暗示整篇文章已覆蓋。實際上只掃 body surface，metadata surface 仍是未驗證區。這是 #95 Multi-pass scope 要蓋同類風險區 在單檔內的同形問題。

跟其他抽象層原則的關係

• #83 Writing 的 multi-pass review：#83 定義 frame 軸，本卡補 surface 軸。Frame 回答「用什麼眼睛看」，surface 回答「哪些文字都要被看」。
• #95 Multi-pass review 的 scope 要蓋同類風險區：#95 處理跨檔 scope，本卡處理單檔內 surface scope。兩者組合成完整 coverage：file scope × surface scope。
• #96 適用範圍要展開成 file enumeration：#96 要求可重現的 file list，本卡要求每個 file 內的 surface list。File enumeration 完成後，還要做 surface enumeration。
• #94 正向改寫要保留對照論據：#94 保留合法對照的推理，本卡定義對照句型出現在 title / MOC hook 時的檢查位置與承接責任。
• #84 Naming 是 iterated artifact：Title、slug、link label 都是命名。它們需要多輪迭代，在生成後持續用 grep-ability 與讀者入口角度收斂。
• #44 Single Source of Truth：正文核心概念與 metadata surface 需要共享同一個概念 SSoT。入口文字與正文語意分裂時，讀者會看到兩個 competing source。

判讀徵兆

當你完成文章或卡片後，看到以下訊號就要補 surface enumeration：

適用範圍與邊界

• 適用：技術文章、report 卡片、知識卡片、README、規格文件、skill reference、MOC / _index.md
• 特別適用：有 frontmatter、sidebar title、SEO description、index table、link label 的內容系統
• 邊界：Metadata surface review 是寫作 pass；它需要語意判讀，grep 只負責提出候選
• 例外：短訊息、一次性草稿、私人 scratch note 可以只保留 title / body 的最小 surface；production 內容與公開知識庫需要全 surface review

可操作檢查

Production 內容交付前，至少跑這三步：

1. 列出這次新增 / 修改檔案的 surface：title、description、heading、body、link label、MOC row。
2. 跑負向詞候選 grep，逐一判讀是否有正向錨點與對照原因。
3. 對照 _index.md 或 MOC，確認索引條、文章標題與正文第一段都指向同一個核心責任。

當跑 multi-reviewer parallel audit（4-reviewer / N-reviewer）、最 high-priority 不是 單一 reviewer flag 的 most severe finding、是 多個 reviewer 從不同軸獨立 flag 的同一 finding。

直覺：

• 單 reviewer flag P0 finding 是 該軸的判斷
• 跨 reviewer convergence flag 是 多軸共同 hit 同一點、信號收斂

機制：N 個獨立 axis 隨機 hit 同一 finding 的機率隨 N 指數下降 — 兩個 axis 偶然 hit 同點機率低、三個 axis hit 同點機率更低。所以 convergence 排除 單 reviewer 主觀 / 偏好 bias、留 系統性 issue。

Case：MySQL 4-reviewer audit

跑 4-reviewer audit（A 寫作規範 / B 跨檔一致性 / C 技術準確性 / D 結構性質疑）對 MySQL 17 篇：

2 軸 convergence 的 finding（缺 weight + frame uniformity）信號特別強 — 兩個 reviewer 從不同 audit 維度（寫作規範軸 vs 跨檔一致性軸）獨立判斷出同一 issue。

對比：PlanetScale FK 是 單 reviewer 找到的 highest-severity finding（invalidates 整段 Phase 1 audit premise）、但是 單軸 flag。

兩種都 P0、但 priority weighting 應該不同：

• 2 軸 convergence finding：structurally important、是 batch level pattern
• 單軸 high-severity finding：technically critical、specific issue

機制：為什麼 convergence 比 severity 重要

1. 單 reviewer flag 有 axis-specific bias

每個 reviewer 用特定 audit 軸（寫作規範 / 一致性 / 技術 / 結構）。單軸 flag 帶該軸的 judgment preference：

• Reviewer A 偏好 寫作風格規範、可能 flag 過嚴
• Reviewer C 偏好 technical correctness、可能 flag 一些 正確但 niche 議題

單軸 flag finding 可能是 該軸 perspective 的 P0、其他軸 perspective 不重要。

2. 跨 axis convergence 排除 axis-specific bias

當兩個 reviewer 從 不同 axis 獨立 flag 同 finding、表示這個 issue 對 多種 judgment perspective 都 reachable — 是 系統性 pattern、不是單一 perspective 的偏好。

舉例：「4 篇 migration playbook 缺 weight」

• Reviewer A 從 寫作規範 角度 flag：missing frontmatter required field
• Reviewer B 從 跨檔一致性 角度 flag：13 篇 deep article 有 weight、4 篇 migration 沒有、不對齊

兩個獨立 reasoning path 到同一 finding、信號收斂、是 結構性問題。

3. Convergence finding 修一次解決多 reviewer flag

實作層：

• 單軸 P0：修 → 解決 1 個 reviewer 的 flag
• 雙軸 convergence：修 → 解決 2 個 reviewer 的 flag

ROI 上 convergence finding 修法效率 2x。

4. Convergence 揭露 audit framework blindspot 的補集

如果某 finding 所有 reviewer 都沒 flag、可能：

• 沒問題（true negative）
• 所有 axis 都看不到（structural blindspot）

如果某 finding 只一 reviewer flag、可能：

• Niche but real（axis-specific catch）
• Axis-specific bias

如果某 finding 多 reviewer flag、強：

• 多 axis 收斂 → 高度 likely true positive
• 排除 axis-specific bias

修法：Cross-reviewer convergence matrix

1. Multi-reviewer audit 後做 convergence matrix

收齊 N 個 reviewer report 後、不是 merge findings list、是建 matrix：

1Finding          | Reviewer A | Reviewer B | Reviewer C | Reviewer D | Convergence
2─────────────────┼────────────┼────────────┼────────────┼────────────┼────────────
3Missing weight   |     P0     |     P0     |            |            |    **2**
4Frame uniformity |     P1     |            |            |     -      |    **2**
5FK claim 過時    |            |            |     P0     |            |    1
6CTE version 錯   |            |            |     P0     |            |    1
7Conn memory 衝突 |            |     P0     |            |            |    1

Convergence column 自動標 priority bump — 2+ 列為 首要 fix、1 列為 依 severity 處理。

2. Priority list 按 convergence 排序、不是純按 severity

修法 priority：

1. 2+ convergence finding（系統性 pattern）— 必修、高 ROI
2. 單軸 + 高 severity finding（如 FK claim 過時 invalidates premise）— 必修、specific
3. 單軸 + 中 severity finding（如 CTE version 錯）— 修、ROI 中等
4. 單軸 + 低 severity finding — 可選

3. Convergence 揭露的 pattern 寫進 retro

2+ convergence finding 通常是 寫作流程 / 模板 級議題、修了該 case 還要回頭看 為什麼會系統性發生：

• Missing weight：寫 migration playbook 模板沒有 weight、是 template gap
• Frame uniformity：「5 個踩雷」frame 在所有 article 重複、是 frame template too rigid

把這些 pattern 寫進 retro / report card、未來不再踩。

跟既有原則的關係

• Sibling Coverage Asymmetry Blindspot in Priority：本卡是 audit finding 的 priority weighting、那卡是 batch coverage 的 priority weighting、不同 layer
• Multi-Pass Review Frame Granularity Blindspot：multi-pass 是 同 reviewer 多輪、本卡是 多 reviewer 平行、不同模式

反向驗證

不該誤用：

• Convergence > severity 不是絕對 — 單軸高 severity finding（如 invalidates premise）仍是必修、不該因為「只一軸 flag」延後
• N=1 reviewer audit 不適用本卡 — 至少 2 個 reviewer 才有 convergence 概念
• 2 個 reviewer 用 同樣 axis 都 flag 不算 convergence — 必須 不同 axis 才是真正收斂
• Reviewer 之間 互相看過彼此 report 後再 flag 不算 convergence — 必須 獨立 parallel 跑

觸發再評估

• N-reviewer audit 跑超過 5 輪後、check convergence finding 的 follow-up rate 是否真比單軸 finding 高
• 出現 3 軸以上 convergence 的 finding 時、是否 trigger framework-level review（不只是 content fix）
• 累積足夠 reviewer convergence case 後、考慮抽出 axis design 原則：哪些 axis 組合的 convergence 最 informative

多輪審查（multi-round-review）的最低輪數是三輪，不是「看 finding 數決定要不要繼續」。Round 3 不是可選的加深，而是覆蓋 Round 1-2 結構性盲區的必要輪。

為什麼

Round 1（compliance / baseline）和 Round 2（cadence / reader journey）用的 frame 都是「從作者端出發」的維度——規範有沒有遵守、句型有沒有重複、讀者走路線順不順。這兩輪能 catch 的問題有一個共同特徵：它們在「文章已經寫出來的內容」裡找錯。

Round 3 的 frame 是「從文章沒寫的東西出發」——enumeration 有沒有漏選項（steelman）、其他系列有沒有反向引用（outbound）、搜尋落地粒度夠不夠（search landing）、知識卡缺口。這類問題在 Round 1-2 的 frame 下結構性不可見，因為 reviewer 在已有內容裡掃描時，不會主動問「這裡應該還有一個選項但沒寫」。

反模式

「Round 2 修完、finding 數下降、覺得差不多了就停」是最常見的反模式。multi-round-review skill 已經明確寫了「停止訊號是 frame 涵蓋、不是 finding 數遞減」，但實際執行時仍然會在 Round 2 結束後問「要不要繼續」——這個提問本身就是 finding 遞減直覺在主導判斷。

Evidence

Dotfile 系列（29 篇 + 知識卡）三輪審查的 finding 分布：

Round 3 的 14 項不是 Round 1-2 的殘餘——它們是全新類型的問題：macOS 原生 tiling 遺漏、yadm/mise 選項缺失、跨系列反向引用斷裂、知識卡缺口。這些問題在 Round 1-2 的 frame 下不會被 catch。

先前的 backend 教學模組 review 也觀察到類似分布：三輪各 catch 不同類型的問題、finding 數不遞減。

修法

把「至少三輪」從「建議」升級為「硬底線」。Round 3 結束後才進入「要不要繼續」的判讀——此時用七軸涵蓋度和「想不出新 frame」作為停止訊號。

跟其他原則的關係

• #114 multi-pass frame 顆粒度盲點 — 同 frame 多輪無增益，多輪價值在 frame 切換
• #148 跨輪 review 停止訊號 — 停止訊號是 frame 涵蓋、不是 finding 遞減
• #126 review 七軸完整度 — 七軸動完是停止條件之一，三輪是動完七軸的最低路徑

判讀徵兆

以下情境代表三輪硬底線正在被繞過：

• Round 2 結束後問「要不要繼續」「到這裡收嗎」
• Round 3 的 frame 規劃被跳過、直接宣布 review 完成
• 用「Round 2 finding 數比 Round 1 少」作為停止依據