RCF-062 — Sheets 欄位映射前必讀實際分頁結構（IMP-153 升規）
類型：規則變更 日期：2026-06-01 觸發條件：條件 1 — 新增 HARD STOP 規則（🔧 開發模式新增 IMP-153 規則區塊） 相關文件：
C:\Users\USER\Desktop\tzlth-hq\CLAUDE.md（主規則文件，v2.8→v2.9）knowledge/improvements.md（IMP-153 狀態 ⏳→✅）
問題背景
外展系統 GAS 開發期間（2026-05-28），v1.0v1.3 四個版本的模板查找邏輯全部基於設計文件描述的欄位結構，而非 Sheets 實際欄位結構。設計文件記載 A 欄為 TPL-ID（如「退輔會_R1」），實際 Sheets A 欄為 TPL-0112（純序號）、C 欄才是對象類型。
兩者不符導致模板永遠找不到。問題在 Tim 實測 v1.3 後才發現，需要 Tim 提供 SHEET_ID + Claude 透過 CSV export 讀取實際內容才確認根本差異，最終需要 v1.4 根本改寫查找邏輯。
根本模式：設計文件 = 預期（intention）；實際 Sheets = 事實（reality）。兩者在執行過程中可能分歧，且分歧只有在 Tim 實測後才能發現——此時已有多版本累積技術債。
現有機制缺口：CLAUDE.md 🔧 開發模式已有「禁止靠記憶判斷」，但沒有任何規則要求「開發前主動讀取外部資料來源的實際欄位結構」。
設計討論（三輪精煉 + 一輪五層盤點框架）
本規則經四輪嚴謹分析，最終確立以下關鍵設計決策：
| 設計點 | 方案 A | 方案 B（採用） | 排除原因 |
|---|---|---|---|
| 觸發範圍 | 只限 GAS 腳本 | GAS / Python 腳本均適用 | A 遺漏 Python 同類風險 |
| 觸發精確度 | 任何 Sheets 讀取 | 欄位映射型態（硬編碼位置/標頭字串比對） | A 過觸發（全表讀取也算） |
| 觸發時機 | 只限新建 | 新建或修改涉及欄位映射的區段 | A 遺漏修改情境 |
| 讀取方法 | CSV export 或 MCP | 僅 CSV export（Tim 提供 CSV 為私有備選） | HQ 未安裝 Sheets MCP，「MCP 讀取」是幻覺選項 |
| 多分頁情境 | 只讀「目標分頁」 | 代碼依賴的每個分頁各讀一次 | A 遺漏多分頁依賴場景 |
| SHEET_ID 未知 | 無處理 | 查照標注等待 Tim 提供 | 未知時繼續寫邏輯 = 同樣的風險 |
| Sheets 新建 | 無處理 | 查照列計畫欄位清單，Tim 確認後才建立映射 | 類比 IMP-151「無現有 auth」情境 |
| 欄位不符 | 無處理路徑 | 查照標注 ❌ 不符 + 執行計畫必列修正步驟 | 缺少此路徑，「讀了但繼續用錯誤邏輯」仍可能發生 |
最終決策
採用方案 B 設計，建立以下規則文字並寫入 CLAUDE.md 🔧 開發模式（繼 IMP-151 HARD STOP 之後）：
觸發條件：新建或修改 GAS / Python 腳本中涉及 Sheets 欄位映射的程式區段，出現以下任一型態： ① 硬編碼欄位位置（row[N]、getRange('A:A')） ② 標頭名稱字串比對（indexOf / match by column name）
必做：查照前對代碼依賴的每個分頁各讀一次（含標頭行），逐分頁在查照中展示：分頁名稱 + 實際 A~N 欄標頭 + 代碼依賴欄位 vs 實際欄位對應表。
四種情境處理：
- 公開 Sheets → CSV export URL
- 私有 Sheets → 查照標注「需 Tim 提供前幾行 CSV」
- SHEET_ID 未知 → 查照標注「需 Tim 提供 SHEET_ID」
- Sheets 新建 → 查照列計畫欄位清單，Tim 確認後才建立映射
欄位不符處理：查照標注 ❌ + 執行計畫必列修正步驟 + 禁止先寫後調整
影響範圍
| 影響類型 | 具體項目 |
|---|---|
| 修改文件 | CLAUDE.md v2.8→v2.9：快速索引新增 1 行 + 🔧 開發模式新增 IMP-153 HARD STOP 區塊 + 禁止行更新 |
| 修改文件 | knowledge/improvements.md：IMP-153 狀態 ⏳→✅ + IMP-153 重複編號修正（automations.md 條目 → IMP-160） |
| 新增文件 | knowledge/decisions/RCF-062.md（本文件） |
| 更新文件 | knowledge/decisions/README.md +1 行 |
| 更新文件 | dev/tasks.md IMP-153 [x] 完成 |
| 更新文件 | dev/CLAUDE.md 最近修改記錄 +1 行 |
| 觸發部門同步 | 無（主 CLAUDE.md 為 source of truth，部門 CLAUDE.md 通過指針繼承，不需個別 Edit） |
| 影響的 SKILL | 所有涉及 GAS / Sheets 開發的查照流程（目前主要為外展系統） |
驗證方式
下次執行外展系統 GAS 開發任務時，查照中應出現：
- ⛔ IMP-153 觸發標注
- 目標分頁前幾行 CSV 展示（或 Tim 提供 CSV 記錄）
- 代碼依賴欄位 vs 實際欄位對應表
- 若私有 Sheets：查照標注「需 Tim 提供前幾行 CSV」
附記：同時發現 improvements.md 存在多組重複 IMP 編號（IMP-153、IMP-155、IMP-156 各出現兩次），本次已修正 IMP-153 重複條目（automations.md 同步缺口 → 改為 IMP-160）。其他重複編號建議在下次「整理知識庫」SKILL 執行時一併清理。