場景痛點說明：套用三階段 Prompt 盤點報表邏輯的實務陷阱
在沒有完整 PRD 的情況下，透過 AI Agent（如 Antigravity）搭配 MCP 讀取源碼，並採用 三階段 Prompt 驗證法 來逆向梳理系統邏輯。
然而，當面對高複雜度的「報表功能」（通常包含跨表查詢、多維度運算與數十個欄位）時，即便嚴格執行這三個階段，AI 在處理大量程式碼時仍會產生特定的推論盲區，導致產出的規格失真。以下盤點在實作報表逆向工程時，遇到的問題及具體操作解法。
本文實作的前提條件：MCP 程式碼讀取環境建置完成
在開始前請內部工程師已架設好 MCP 伺服器，並完成與 AI Agent（如 Antigravity）的介接。AI Agent 已具備直接存取、搜尋與讀取目標功能所有底層程式碼檔案的權限。
問題一：記憶體壓縮導致細節遺失
在「拆解運算規則」階段，AI 因處理過多報表欄位觸發自動摘要，導致關鍵欄位定義被整併遺失。
報表功能通常包含數十個欄位。當要求 AI 一次性展開整張報表的運算規則時，AI 為了節省 Context Window 與記憶體，會擅自將長篇距的程式碼映射邏輯進行「壓縮」。這會導致產出的文件缺乏實作細節，後續也無法進行「驗證底層欄位」的動作。
具體範例：
透過 MCP 讀取 VendorSettlementReport.java，要求 AI 拆解「供應商月度結算報表」A 到 AD 欄（共 30 欄）的運算規則。
- 預期結果： AI 逐欄列出 A 欄: 訂單編號 (orderId)、M 欄: 平台抽成費 (calcPlatformFee())、Z 欄: 實付淨額 (netPayable) 等 30 行精確定義。
- 實際結果： AI 回覆「A~F 欄：訂單基礎資訊」、「G~Z 欄：各項費用扣減與結算」。底層獨立變數與計算邏輯完全被抹除。
實戰解法：強制分批與防壓縮宣告
在「拆解運算規則」的 Prompt 中必須加上絕對約束，並透過切塊詢問來迴避壓縮機制。
優化版 Prompt：
「我要拆解供應商月度結算報表 A~AD 欄的運算規則。為了避免遺漏，請分批處理，先列出 A~J 欄。嚴禁自行壓縮、省略或合併欄位說明。必須逐欄獨立列出對應的變數，若回答將超出字數限制，請停在完整段落並提示我輸入繼續。」
問題二：全域與局部過濾條件混疊
在「盤點資料來源」與「拆解運算規則」時，AI 無法主動區分資料庫層的絕對限制與報表視圖層的二次篩選。
報表資料具備強烈的層次性。AI 在閱讀源碼時，常將資料層面 SQL 的 WHERE 條件與應用層面 Java 針對特定報表 Sheet 的 if 判斷混為一談。
具體範例：
詢問 AI「結算報表中『本月有效交易額 (GMV)』欄位的過濾條件是什麼？」
- AI 的實際回答： 「訂單狀態不能為已取消，且付款日期必須在當月。」
- 實際災難： 在底層源碼中，「狀態不為取消 (status <> 'CANCELED')」是資料庫查詢層的全域條件，適用於整份結算報表（包含歷史退款、未結算清單）；而「付款日期在當月」只是特定欄位（前端 View 層）用來統計本月 GMV 的局部篩選。混為一談會讓開發者在 SQL 直接寫死日期限制，導致報表上的「歷史未結算」欄位抓不到資料。
實戰解法：分層架構宣告
在拆解規則時，強制 AI 按照系統架構邊界，分層條列過濾條件。
優化版 Prompt：
「請將過濾條件分為以下兩個層次獨立條列：
- DB 查詢層：適用於整份報表資料的基礎全表過濾條件。
- 報表運算層：僅針對『本月有效交易額』該單一欄位進行的二次過濾或日期篩選。」
問題三：底層邏輯過度簡化
在「驗證底層欄位」階段，AI 傾向將複雜的程式條件式翻譯成白話文，隱藏了關鍵的數學公式與業務邊界條件。
盤點報表邏輯的核心是找出精確的邊界。AI 為了降低閱讀門檻，會自動過濾程式碼中生硬的數學公式或多重布林值判斷，包裝成模糊的業務敘述。這種過度轉譯會造成規格盤點的重大漏洞。
電商具體範例：
要求 AI 驗證銷售報表中「VIP 滿額返利單數」的底層規則。
- 原始程式碼： if (userLevel == 'VIP' && (totalOrderAmount - refundAmount - couponDiscount > 5000))
- AI 的實際回答： 「計算符合消費門檻的 VIP 訂單數量。」
- 實際災難： AI 省略了 totalOrderAmount - refundAmount - couponDiscount > 5000 這個極度核心的數學邏輯（總金額扣除退款與優惠券後須大於 5000）。
實戰解法：代碼優先約束
剝奪 AI 直接翻譯的權力，要求先亮出底層程式碼與變數，再進行語意轉換。
優化版 Prompt：
「請列出系統實際運作的判斷條件。必須先列出程式碼或 SQL 中真實的變數名稱與運算式，接著再用白話文解釋其商業邏輯。直接根據系統真實規則回答，不要簡化任何加減乘除邏輯或數值門檻。」
問題四：業務名詞定義未對齊
AI 直接套用系統內部的業務術語，卻未對齊底層程式碼的真實定義，導致後續所有邏輯推論皆建構在錯誤的假設上。
系統分析注重邊界定義。在「盤點資料來源」或「拆解運算規則」時，AI 經常會照搬變數名稱或註解中的業務名詞（例如：新訂單、保留件、有效交易）。若未要求 AI 先下達明確的技術定義，SA 將無法確認這些名詞在資料庫中對應的真實狀態標記。
電商具體範例： 分析報表時，AI 提到某個欄位的計算基準是「缺貨待補件 」。
- AI 的實際回答： 「統計本月所有缺貨待補件的總金額。」
- 實際災難： 什麼是缺貨待補件？在底層程式碼中，它的精確定義是由兩個條件組成：
is_last_reserved == true（上月遺留）且expected_ship_month == current_month（預計本月發貨）。如果 SA 沒有挖出這層定義，工程師在開發 API 時可能只會單看stock_status == 'OUT_OF_STOCK'，導致報表抓錯整批歷史未處理訂單。
實戰解法：前置字典定義在拆解具體欄位前，強制要求 AI 盤點並定義所有出現的業務術語。
優化版 Prompt： 「在分析欄位邏輯前，我發現系統使用了『缺貨待補件』等術語。請先盤點源碼，精確列出這些術語在底層的判斷條件（包含對應的 Entity 欄位、布林值或特定字串）。確認定義無誤後，我們再進行下一步欄位拆解。」
問題五：Confluence 跨頁面引用巨集報錯
主旨：透過 MCP 自動將邏輯寫入 Confluence 時，AI 生成的巨集 XML 格式與 Cloud 版不相容，導致跨頁面引用 (Excerpt Include) 嚴重報錯。
為了落實單一真理來源 (SSOT)，SA 常會將「全域過濾條件」寫在一個主頁面，並在各支報表規格頁面透過 Excerpt Include 巨集動態引用。然而，要求 AI 透過 API 更新 Confluence 頁面時，AI 常會混用舊版 Server 版標籤或純 Markdown，導致頁面持續顯示 Error loading excerpt。
電商具體範例： 要求 AI 將「退款排除規則」獨立寫入主頁面，並在「月度結算報表」頁面中引用。
- 預期結果： 報表頁面成功嵌入退款排除規則。
- 實際災難： AI 使用了
<ac:reference>標籤，或是未在來源頁面的excerpt巨集加上name屬性，導致 Confluence Cloud 無法解析，整份規格書充滿錯誤紅字，必須手動逐一修復。
實戰解法：在 Antigravity 設定全域防呆 Rule (Workspace Rules)
單方面在 Prompt 規範引用格式不僅冗長，AI 也容易遺忘。實務上，應直接在 Antigravity 的系統設定中，建立一組 AI 可判讀的雙向寫入規則，剝奪 AI 自由生成語法的權限。
問題六：單點查證過度耗時
主旨：AI 為了解答單一欄位的資料來源，觸發無邊界的底層全域搜尋 (Global Grep)，導致查證單一問題耗費極長運算時間。
在使用 Agent 進行 Code Review 時，常會遇到需要快速確認某個設定值是「程式寫死」還是「動態撈取自 DB」。若未給定搜尋邊界，AI 會直接在整個 Workspace 或 Repository 執行全域檢索，甚至遞迴讀取不相關的設定檔。
電商具體範例： 詢問 AI「結算報表中的『平台平均抽成比例』是寫死在程式碼裡，還是資料庫欄位？」
- AI 的實際執行路徑： AI 為了求證，啟動 MCP 工具對整個
workspace_vendor_system目錄下達grep與Select-String指令，翻找所有包含FeeRatio的數百個檔案，導致單次對話卡頓超過 3 分鐘。 - 實際災難： 耗費過多不必要的 Token 與等待時間，打斷 SA 梳理邏輯的思路節奏，且可能因讀取過多無關檔案觸發 Context Window 上限。
實戰解法：漏斗式檢索限制既然 SA 無法預先知道目標檔名，就不該強求在 Prompt 中寫死搜尋路徑。替代方案是要求 AI 改變檢索行為模式，將「暴力窮舉」改為「先列清單，再深挖」的兩階段漏斗式探索。
優化版 Prompt： 「請確認『平台平均抽成比例』的數值來源是常數還是動態資料庫欄位。 嚴禁直接執行全域內容搜尋 (Global Grep) 或一次性讀取大量檔案。 請依照以下步驟執行：
- 先搜尋『檔名』或『目錄名稱』包含 Settlement、Report 或 Config 的最相關檔案，列出你打算查看的前 3 個檔案清單。
- 在我回覆同意之前，禁止直接讀取這些檔案的內容。」
三階段 Prompt 驗證法 V2 (防幻覺與防壓縮強化版)
為了解決先前盤點出的記憶體壓縮、過濾條件混疊、邏輯過度簡化、名詞定義未對齊，以及單點查證耗時等問題，將原本的 prompt 進行了升級。
這個 V2 優化版本加入了「強制分層」、「代碼優先」與「防壓縮宣告」，能進一步鎖死 AI 的推論路徑，逼迫它交出符合系統分析規格的精確產出。
階段一：盤點資料來源與定義邊界（找源頭與定錨）
除了確認資料來源，新增「限制搜索範圍」以加速 AI 反應，並強制要求 AI 在一開始就「對齊系統術語的底層定義」，避免後續發生雞同鴨講的推論。
優化版 Prompt：
我要盤點 [目標功能/報表名稱] 的邏輯。
限縮範圍：請限制你的搜索範圍在與此功能最相關的程式碼或 API 內，不要進行全域搜尋。
確認來源：系統是從哪一個模組或資料表撈取資料來產出這個功能的？請單純列出來源就好，先不要解釋計算規則。
名詞對齊：若該功能有使用特定的業務術語（例如：新訂單、可交車、保留件等狀態），請先盤點源碼，精確列出這些術語在底層的判斷條件（如對應的布林值或特定字串）。
確認這些名詞定義無誤後，我們再進行下一步。
階段二：拆解分層運算規則（挖規則與防壓縮）
強制 AI 區分「資料庫撈取層」與「前端/報表運算層」，避免過濾條件混疊。同時加入「代碼優先」與「分批處理」指令，阻止 AI 過度簡化防呆條件或為了省記憶體而擅自壓縮欄位說明。
優化版 Prompt：
針對剛剛拿到的資料，我要了解 [目標區塊/欄位名稱，例如 A~J 欄] 的具體邏輯。為了避免遺漏，請分批處理，嚴禁自行壓縮、省略或合併欄位說明。
請將系統實際的過濾與運算條件分為以下兩個層次條列，並且必須**「先列出程式碼/SQL 中真實的變數名稱與判斷式，再用白話文解釋」**：
DB 查詢層 (Repository Level)：適用於這批資料的基礎過濾條件（如狀態排除、時間限制、部門權限等）。
報表/應用運算層 (Application/View Level)：僅針對特定欄位的二次過濾、狀態篩選或加減乘除。請直接根據系統真實規則回答，不要簡化任何防呆條件或例外處理。
若回答將超出字數限制，請停在完整段落並提示我輸入繼續。
階段三：驗證底層欄位與實體防偽（對實體與戳破幻覺）
延續原版精神，但強化輸出格式。要求 AI 以表格明確對應「業務邏輯 > 實體欄位 > 狀態值」，讓任何捏造的欄位或推論無所遁形。
優化版 Prompt：
在你剛剛提到的判斷條件裡，用到了哪些具體的狀態或標記？
請幫我確認系統底層的資料庫實體 (Entity) 或結構中，確實有這些「欄位名稱」嗎？
請直接以表格形式列出，用來證明這些過濾條件是基於真實存在的狀態標記，而非字面上的語意推論：業務邏輯說明系統真實存在的英文欄位名稱程式碼中對應的真實狀態值 (如 'done', 1, 0, null)
若有任何查不到真實欄位對應的邏輯，請誠實標註「未找到明確欄位，疑似衍生計算」。
