Gary Talks Stuff：Brownfield 專案用 AI 改 Code 的安全工作流程

開場閒聊

Gary 從一個很多人都遇過的場景開始：用 AI 做 side project 時，前幾個禮拜功能一個個長出來，感覺只要開口就能完成一切。

但到了第四個禮拜，只是改一個小地方，另一個頁面卻突然掛掉。工程師接手公司的陌生 codebase，也可能遇到同樣的「改 A 壞 B」困境。

這支影片的核心提醒很直接：問題不一定是 AI 不夠強，而是使用 AI 的順序錯了。面對既有專案，要先看懂房子的管線，再讓 AI 按照原本的規矩施工。

懶人包速覽

核心痛點	解決方案 / 關鍵觀點
AI 不熟悉既有專案，容易自行發明新寫法	先定位畫面、元件與資料流，讓 AI 只做分析，不要一開始就修改
空泛需求可能牽動共用 hook 或其他頁面	把既有 coding style、元件與不可修改範圍寫成明確 guardrails
一次生成整個功能，錯誤難以追蹤	把任務拆成規劃、hook、畫面、彈窗等小步驟，每一步都 review
不知道改動是否造成回歸問題	先後執行既有測試，理解 custom error logging，並檢查所有共用 hook 的使用位置

這篇文章整理的，正是「Brownfield 專案用 AI 改 Code 的安全工作流程」：先理解既有系統，再用可驗證的規格與小步驟完成修改。這個順序比單純追求一次生成更多 code 更重要。

這篇文章整理 Gary 提出的五步工作流程，重點不是某一個特定 AI 工具，而是如何把 AI 從「直接動手的陌生工班」變成「先協助勘查、再遵守規格施工的工程夥伴」。

Greenfield 與 Brownfield：AI 面對的是哪一種土地

Greenfield 指的是全新的專案，像一塊沒有建物的空地。架構、命名方式、檔案安排與使用的 pattern 都可以重新決定，因此也是 AI 最容易發揮的場景。

網路上常見的「用 AI 三十分鐘做出一個 app」教學，通常描述的就是 Greenfield。沒有歷史包袱時，AI 可以按照需求從頭設計，不需要先遵守既有規則。

Brownfield 則像是一棟已經有人居住的房子。裡面有既有 code、固定 pattern、尚未解決的 bug，以及沒有寫在文件裡、卻可能牽一髮動全身的資料流與相依關係。

Gary 特別提醒，Greenfield 不會永遠保持在 Greenfield。Vibe coding 持續一個月後，如果沒有刻意維持架構整潔，自己也可能已經不熟悉大部分 code，專案自然就進入 Brownfield 狀態。

因此，真正困難的不是叫 AI 寫出一段看起來合理的 code，而是讓它理解「這棟房子不能怎麼改」。同一個需求在新專案裡可能很簡單，放進既有專案卻可能碰到共用 hook、全域狀態或其他頁面。

兩條路線：AI 輔助開發與純指揮 Agent

Gary 將流程分成兩種使用方式。第一種是 AI 輔助開發：人自己開編輯器、翻檔案、把需要的 code 貼給 AI，請它分析或協助撰寫，最後由人決定是否採用。

第二種是純指揮 agent：把任務與邊界交代清楚，讓 agent 讀整個專案、找檔案、追資料流，再把分析結果交回來驗收。

兩者沒有絕對的標準答案，選擇取決於使用者對 AI 的熟練度、信任程度，以及專案本身的 context 管理與 harness 是否完整。

整套流程分成兩個大階段：前半段是「看懂它」，後半段是「安全地動它」。前兩步偏向探索與勞力工作，後三步則更接近規格、判斷與驗收。

第一步：先定位畫面與元件，不要急著改

要修改商品列表或其他畫面時，第一個問題不是「要寫哪段 code」，而是「這塊畫面到底由哪個檔案渲染」。

在 AI 輔助路線中，Gary 建議使用瀏覽器開發者工具，對目標畫面按右鍵檢查，找出特殊 classname、按鈕文字或測試標籤，再把這個特徵拿回編輯器做全域搜尋。

找到檔案後，可以把商品頁檔案交給 AI，要求它分析畫面結構、列出引入的子元件，並標示哪些元件可能是全站共用。這一步的指令要明確寫上「只分析，不要修改任何 code」。

如果是純指揮 agent，則可以直接要求它找出商品列表由哪個檔案渲染、分析元件結構，並標出共用元件，同樣先禁止修改。

這一步的價值，是把「我怕改壞」的模糊恐懼變成一張地圖。你會知道自己站在哪個房間，也會知道哪些元件是整棟房子的共用資產，不能隨便拆改。

第二步：追清楚資料流與共用依賴

前端最容易出事的地方往往不是畫面，而是資料。第二步要釐清資料從哪個 API 進來、由什麼工具管理、存在哪裡，以及編輯動作如何回到 server。

AI 輔助的做法，是先看 package.json，確認專案使用 Redux、Zustand、React Query 或其他狀態管理方式，再找對應的 store 或 hooks 資料夾。

接著回到畫面元件，找出 dispatch、mutate、setState 等會觸發資料變動的動作，把畫面元件與相關狀態檔案一起交給 AI，要求它用白話文依序解釋完整 data flow。

分析時還要特別確認商品資料 hook 是否在商品頁以外被使用。如果網頁版 AI 看不到完整 codebase，就必須先全域搜尋 hook，把其他使用位置一併提供；能讀整個專案的 agent，則可以直接列出所有相依頁面。

Gary 分享自己很喜歡的一個純指揮技巧：探勘完成後，再要求 agent 把頁面結構、共用元件與 data flow 做成一頁 HTML 架構導覽圖。

這張圖就像建築藍圖，讓人一眼看見資料從哪裡流向哪裡、哪些元件被多個頁面共用，以及哪一條管線可能影響其他功能。

第三步：把需求寫成規格與 Guardrails

完成前兩步後，才進入 Brownfield 與 Greenfield 差異最大的地方：不能再把需求寫成一句空話。

例如「幫我加庫存狀態篩選」在全新專案裡可能足夠，但在既有專案裡，應該補上要讀哪些 hook、共用元件與型別定義，並要求沿用原本的 React Query pattern。

同時要明確指定重用既有 table、modal、select 元件，只准使用專案原本採用的 Tailwind 寫法，不能因為 AI 覺得方便就另造一套。

更重要的是，要把不可碰的範圍寫出來：不要修改全域 routing、全域狀態控管，也不要改動商品頁以外仍在使用的共用 hook。

這些「絕對不要動」的條件，就是把前面看懂的架構轉成 AI 的 guardrails。沒有邊界，AI 只能憑自己的常識猜；有邊界，才有機會在既有 codebase 中保持一致。

Gary 也重新定義 Brownfield 裡的 Clean Code。乾淨不等於依照自己喜歡的方式重寫，而是與前人一致：沿用既有 coding style、命名、資料夾結構與資料取得位置，本身就是最高優先的 Clean Code。

第四步：拆成小塊，每一步都 Review

規格寫完整，也不代表 AI 第一次就會寫對。因此第四步是不讓 AI 一次生成整個功能，而是先提出元件結構與資料流規劃，暫時不要寫 code。

確認方向後，再讓它只修改商品資料 hook，加入庫存篩選參數。這一小塊 review 完，再做篩選畫面，最後才做編輯庫存的彈出視窗。

每一次只做一小塊，錯誤才容易定位，使用者也能在問題擴大前停止。Brownfield 的 review 不只要找 bug，還要檢查改動是否偏離既有寫法。

Review 時要看命名習慣、資料夾結構與抓資料的位置是否一致，也要確認 AI 沒有偷偷動到共用檔案，或重新打造其實早就存在的元件。

AI 可以先擔任第一道 review 防線，例如要求它以資深前端工程師角度檢查 React Query 寫法、共用元件、loading 狀態與 error 狀態是否完整。

但 Gary 強調，AI review 只是初審，終審仍然要由真正承擔 production 後果的人拍板。除非 codebase 已有很好的 harness 與 context 管理，否則重要決策不宜完全外包給 agent。

第五步：測試、錯誤記錄與回歸檢查

最後一步要回答最初的恐懼：這次改動有沒有弄壞別人的功能？Gary 將它拆成三個部分。

第一，先跑專案原本就有的測試。AI 輔助的路線可以在動手前跑一次，確認基線是綠燈，完成修改後再跑一次。

純指揮路線則要把測試變成 agent 的固定動作：動手前先回報結果，每完成一小塊改動就再跑一次。如果專案完全沒有測試，這也是請 AI 補上幾條關鍵測試的好時機。

第二，要理解專案自己的 custom error logging。既有專案可能使用包裝過的 logger、統一的 error code，或固定送往某個後台的格式；這些規矩常是沒有文件化的部落知識。

可以要求 AI 讀 logger 檔案，回答錯誤最後送到哪裡、一筆 log 的格式，以及哪些欄位是必填，再示範庫存編輯功能應如何沿用同一套 logging。

如果只隨手寫一個 console error，錯誤可能根本不會進入團隊平常監看的系統。依照既有格式補上 error code 與 metadata，之後 debug 才找得到線索。

第三，檢查 regression。若商品資料 hook 同時被其他頁面使用，就要逐一確認改動沒有改變原本行為、回傳型別、參數或預設值，也要確認相關既有測試是否涵蓋這些位置。

QA 精選

Q1：為什麼 AI 在 Greenfield 表現很好，到了 Brownfield 卻容易改 A 壞 B？

Greenfield 沒有既有規則，AI 可以自行決定架構與寫法；Brownfield 則有共用元件、資料流、命名習慣與未文件化的依賴。若沒有先理解這些邊界，AI 可能改動共用 hook 的資料格式，讓商品頁修好卻使訂單頁失效。

Q2：Brownfield 專案的第一步應該先做什麼？

先定位目標畫面由哪個檔案渲染。可以用瀏覽器開發者工具找出特殊 classname、按鈕文字或測試標籤，再回到編輯器全域搜尋；也可以直接請能讀完整 codebase 的 agent 找出檔案，但指令必須要求只分析、不修改。

Q3：第二步為什麼一定要追 data flow？

因為畫面只呈現結果，真正可能牽動其他功能的是資料。要確認 API 來源、狀態管理工具、hook、mutate 或 setState 的連接方式，也要查同一個 hook 是否在其他頁面使用，才能預先看到回歸風險。

Q4：如何把「幫我加庫存篩選」改寫成安全需求？

要補上既有規則與禁止事項，例如先讀商品 hook、共用元件資料夾與型別定義，沿用 React Query pattern、重用既有 table、modal、select 與 Tailwind，並禁止修改全域 routing、全域狀態與其他頁面共用的 hook。

Q5：為什麼不能讓 AI 一次生成整個功能？

一次生成會讓問題難以定位，也不容易知道是哪個決策造成副作用。更安全的順序是先做規劃，再改 hook、篩選畫面與編輯彈窗，每一小塊完成後都由人 review，確認一致才進到下一步。

Q6：改完 code 後，除了跑測試還要檢查什麼？

要理解既有 custom error logging，確保錯誤使用專案原本的格式、error code 與 metadata；另外要列出共用 hook 的所有使用位置，確認回傳型別、參數、預設值與原本行為沒有被改變。

主編隨筆

這支影片最值得留下的，不是某一個 prompt，而是「先理解，再授權」這個工作節奏。AI 的產出速度越快，越不能用速度取代邊界；尤其在既有專案裡，一段看似漂亮的重構，可能只是把風險轉移到另一個頁面。

從風險管理角度看，分段修改與測試基線其實是在建立可回復性。每次只推進一小塊，遇到問題時才知道該回到哪個節點；每次都跑測試，才知道系統的狀態是否真的變差。這也提醒使用者，AI 的價值不只在寫 code，更在於協助把陌生系統整理成可以被人判斷的資訊。

當 codebase 的文件、測試與 harness 越完整，純指揮 agent 的範圍才有機會擴大。這不是盲目信任工具，而是先把團隊的規則變成它能讀懂、能驗證的 context。

結語

面對 Brownfield 專案，安全使用 AI 的五步驟可以濃縮成一條線：先定位畫面，再追資料流；把既有規則寫成 guardrails；把功能拆小並逐步 review；最後用測試、錯誤記錄與回歸檢查確認沒有改 A 壞 B。

同一個需求、同一個 AI，結果差異往往不在模型本身，而在使用者有沒有先帶它看懂這棟房子。對 AI 原生工作者來說，知道何時需要 agent 探索與解釋，而不是立刻動手，是從 vibe coder 走向 agentic engineer 的重要里程碑。