剛結束「AI Agent 標準化開發基礎」課程後，隔日有位認真的女學員整理了幾個她在實務工作中遇到的問題。我發現她把這些條列的問題（共 5 個）整理得非常好，在取得她的授權同意下（不涉及相關隱私與敏感資訊），這裡也將我的看法與建議整理成較完整的回覆，對於有類似情境、準備導入 AI 協作開發的團隊，應該也能有所幫助。
以下整理學員提出的五個問題。
我會先以簡化標題呈現問題主題，再保留原始提問內容，並逐一說明我的看法與建議。
Q1 既有系統新增功能時，需求文件應更新原文件還是建立新文件再提交給 AI？
學員原始提問：
若系統已正式上線，使用者提出新增功能需求，且該功能可能影響既有作業流程時：
此類變更應持續維護於原有的《功能需求規格書－購物車模組.md》中進行版本更新，
或是僅將新增功能部分獨立整理為新的 .md 文件，再提供 AI 協助處理較為適當？
回覆：建議原則是：
「維持原規格的演進版本，而不是拆散成多份零散文件。」
原因有三：
- 需求文件本質上是系統契約（System Contract） 若同一模組（例如購物車）持續新增功能，建議仍維護在同一份規格文件中（除非新增功能內容非常繁雜，那是可以另以附件關聯，但本質上仍視為同一份文件），以版本或章節方式演進，例如：
購物車模組功能規格.md
├─ v1 基本功能
├─ v1.1 新增批次加入商品
└─ v1.2 新增優惠券計算- 避免知識碎片化 若每次需求都獨立成新文件，長期會導致：
- AI 上下文難以理解整體邏輯
- 人類也很難掌握完整行為
- AI 的最佳使用方式是「完整上下文（Context）」，而不是片段 AI 在分析需求時，需要看到：
- 原功能
- 新需求
- 既有限制 才能推論哪些地方需要修改。
因此較建議的做法是：
- 核心模組規格 → 維持單一文件版本演進
- 跨模組需求 → 建立新的功能提案文件
Q2 舊 WinForms 系統如何透過 AI 協作重構為 Web 架構？
學員原始提問：
若既有系統為 C# WinForms 架構且已上線運作，未來計畫全面改為 Web 架構（例如 React + FastAPI），
若希望透過 AI 協作進行重構或翻寫，建議應採取何種步驟或策略，較能確保品質與效率？
回覆：建議不要直接讓 AI「翻寫整個系統」，而是採取分階段重構策略：
Step 1：先抽出 Domain / Business Rules / 資料存取方式
先整理系統中真正重要的部分：
- 資料模型
- 業務規則
- 使用情境（Use Cases）
這些是系統真正的核心資產。
Step 2：建立新系統的架構骨架
例如：
Frontend
React
Backend
FastAPI
Application Services
Domain
Infrastructure這個骨架應由開發人員先行架構規劃設計，並採以 POC（Proof Of Concept）方式驗證可行性，而不是讓 AI 自由生成。
Step 3：逐步轉譯 Use Case
例如：
WinForms
AddProductToCart()→ 轉為
API
POST /cart/items此時 AI 很適合協助：
- 轉譯 UI 行為
- 產生 API contract
- 生成資料模型
Step 4：逐步功能模組遷移
不要一次遷移整個系統，而是：
Cart module
Order module
Inventory module採逐步功能模組的替換策略。簡單說：
AI 適合協助「轉譯與實作」，
但架構設計與結構分解仍應由開發者主導。**
Q3 前後端規格文件應合併還是分開提供給 AI？
學員原始提問：
> 課程中前後端皆以不同 .md 文件進行功能規範與描述。
> 當有新的功能需求時，應整合為單一需求文件交由 AI 執行，
> 或仍建議以前後端分開的方式，分別提供給 AI 處理較佳？
回覆：「整體需求文件 + 前後端細分規格」
P.S. 這裡可能有一點理解上的落差，我稍微補充說明一下：
> 在課程中前面章節其實有先提供「情境需求描述」與「系統功能規格書」，
> 這是從需求分析的角度來看系統，因此在這個階段通常不會區分前端或後端。
>
> 學員所看到的前後端 .md 文件，其實已經是「系統開發規格」
> 的層次，主要是為了讓 AI 在實作程式碼時，能夠有更清楚的上下文與責任邊界。
feature-cart.md （整體需求）
frontend-cart.md （前端需求）
backend-cart.md （API / Service）原因：
- 1. 整體文件提供上下文
- 2. 分文件方便各自實作
實務上 AI 也較容易理解：
- 前端只需載入 frontend spec
- 後端只需載入 backend spec
Q4 系統文件是否應與程式碼一起放入 Git？
學員原始提問：
> 系統相關文件是否建議與程式碼一併納入 Git 版本控制管理？
回覆：強烈建議放入 Git。
原因如下：
1. 文件本身就是系統資產
在 AI 協作開發中：
AGENTS.md
技術規格
架構說明 都是 AI 的重要上下文。（這也是課程中強調「將 AI 規範版本化」的原因。）
2. 文件需要版本歷史
可以追蹤：
- 需求如何演進
- 哪個版本改了什麼
3. 避免文件與程式碼脫節
同一 repo 能確保：
- 規格
- 程式碼
- 文件
同步演進。
Q5 大型舊專案缺乏文件時，如何導入授課所教授的方法（迭代與漸增）？
學員原始提問：
若為老舊大型專案且缺乏完整文件，應如何套用今日課程所介紹的方法進行重整與導入？
回覆：建議不要嘗試一次補齊所有文件，而是採取：
「逆向建立最小知識結構」
建議步驟如下：
Step 1：先建立一份 system-overview.md
內容只需包含：
- 系統目的
- 主要模組
- 技術架構
Step 2：建立 模組級文件
例如：
modules/
cart.md
order.md
product.md描述：
- 功能
- 資料
- API
Step 3：利用 AI 進行「輔助整理」
例如：
- 解析 controller
- 推測 API
- 產生資料模型文件
但需要工程師審核。
Step 4：逐步導入規範文件
例如：
AGENTS.md
architecture.md
coding-guidelines.md讓 AI 之後能在可控環境下協作。
最後補充一個觀念：
文件不是為了 AI 而寫。 文件是為了「讓系統知識可被管理」。
AI 只是讓這些知識能被更有效率地使用。