AI 協作工作流

约 1808 字大约 6 分钟

AI WORKFLOW · FROM PROMPT TO PROOF

“讓 AI 寫一個功能”不是工作流，只是一次請求。可重複的工作流必須包含：正確的上下文、明確的邊界、最小的改動、可執行的驗收。這一頁給出一套可以直接照做的六步循環。

一、六步循環

① 定位邊界  →  ② 組裝上下文  →  ③ 先要計劃
                                      │
                                      ▼
⑥ 記錄決策  ←  ⑤ 審查與驗收  ←  ④ 小步實現

步驟	你要做的事	產出
① 定位邊界	判斷屬於哪個域、是否需要新模塊	一個明確的落點
② 組裝上下文	只給相關規範、實體、控制器、測試	一份可複用的上下文包
③ 先要計劃	讓 AI 輸出文件清單與改動理由	可審查的計劃
④ 小步實現	一次只改一個關注點	可編譯、可回滾的 diff
⑤ 審查與驗收	跑編譯、單測、架構測試	通過或明確的失敗原因
⑥ 記錄決策	更新 README / AGENTS / 事件登記	下一次可複用的知識

二、上下文包：少而準，比多更重要

不要把所有文檔一股腦塞給模型。一個有效的上下文包通常只有五類文件：

tg-context/
├── 01-task.md              這次要改什麼、不改什麼
├── 02-rules.md             AGENTS.md 中與本任務相關的硬約束
├── 03-module.md            目標模塊 README（職責、表前綴、已有能力）
├── 04-templates/           同域 entity / controller / service 各一份
└── 05-contracts/           相關 *-api 接口、事件契約、DTO

取文件的順序

docs/README.md —— 確認閲讀路徑；
AGENTS.md —— 找與本次任務相關的硬性規則；
目標模塊 README —— 確認職責與已有實現；
同域實體、Controller、Service —— 讓生成結果“像這個倉庫”；
相關 *-api 契約 —— 確認跨模塊調用方式；
現有測試 —— 確認驗收標準。

不該放進上下文的東西

與任務無關的幾十個 Controller；
生產配置、密鑰、真實用户數據；
已經廢棄的舊版本代碼；
沒有邊界的“整個倉庫壓縮包”。

上下文不是越多越好

上下文越長，模型越容易抓住錯誤的重心。把“相關”控制在 5～8 個文件，比塞進 50 個文件更有效。

三、先要計劃，不要先要代碼

計劃提示詞模板

你是 TG-boot 的開發助手。請先只輸出計劃，不要寫代碼。

任務：{一句話描述需求}

約束：
- 跨模塊只能使用 *-api 契約或 MQ 事件；
- 實體繼承 BaseEntity，業務主鍵使用 *Code；
- 狀態字段遵循 *StatusCode / *ProcessCode 約定；
- 不新增跨域 *-biz 依賴；
- 不修改與任務無關的文件。

請輸出：
1. 歸屬模塊與理由；
2. 需要新增/修改的文件清單；
3. 每個文件改什麼、為什麼；
4. 是否需要新契約或新事件；
5. 驗收命令與預期結果；
6. 你不確定、需要我確認的點。

審查計劃的四個問題

它是否把代碼放進了錯誤的域？
它是否發明了框架裏不存在的機制？
它是否遺漏了契約、事件登記或冪等？
它是否把“順手重構”混進了本次任務？

只要有一個答案是“是”，先改計劃，不要進入實現。

四、實現：一次只做一件事

推薦把實現拆成可獨立驗證的小步：

只加實體與 Mapper，編譯；
只加 Service 與單元測試，跑測試；
只加 Controller 與接口文檔，啓動驗證；
只加事件契約與消費者，跑集成測試；
只加 runner 裝配，跑架構測試。

每一步都保持可編譯、可回滾。不要一次性生成二十個文件，再祈禱它們能一起工作。

實現提示詞模板

按已確認的計劃實施第 {N} 步。

只允許修改這些文件：
- {file1}
- {file2}

必須遵守：
- {從 AGENTS.md 摘錄的 3～5 條硬約束}

輸出要求：
- 先給出 diff 摘要；
- 再給出完整文件內容；
- 最後列出你實際執行過的驗收命令。

如果發現計劃與倉庫現狀衝突，停止並説明，不要自行擴大改動範圍。

五、把 AGENTS.md 當成“可執行規範”

TG-boot 的 AGENTS.md 不是寫給人類看的歡迎頁，而是給 AI 的硬約束清單。典型規則包括：

規則	錯誤示例	正確做法
實體繼承 `BaseEntity`	自己寫 `createTime`	繼承統一基類
雙主鍵	對外暴露 `id`	對外使用 `xxxCode`
布爾狀態	`status = "YES"`	`"1"` / `"0"`，null 視為否
流程狀態	把“審核中”塞進 `*StatusCode`	使用 `*ProcessCode`
字典字段	用 `*Constants` 靜態類	枚舉 `implements BaseEnum`
跨模塊調用	注入他域 `*ServiceImpl`	注入 `Api**Service`
事務消息	事務內直接 publish	`publishAfterCommit`

在提示詞裏不要寫“請遵守規範”，而要寫具體規則 + 具體反例。模型對反例的敏感度通常更高。

六、驗收：讓“完成”有證據

一個功能至少要通過四類檢查：

層級	命令 / 動作	通過標準
編譯	`mvn -q -DskipTests compile`	無編譯錯誤
單測	目標模塊測試	新增邏輯有覆蓋
架構	`mvn -pl spring-boot-starter-architecture-tests -am test`	無越界
運行	啓動 runner，調用接口	返回符合契約

如果是前端或跨端任務，再補：

類型檢查；
關鍵頁面的移動端截圖；
空態、錯誤態、加載態；
接口失敗時的降級。

讓 AI 自己寫驗收命令

在計劃階段就要求它列出“準備執行哪些命令、預期輸出是什麼”。實現完成後，再讓它逐條報告實際結果。這樣更容易發現“看起來完成、其實沒跑”的情況。

七、審查清單

改動是否只落在計劃允許的文件裏？
是否新增了不必要的抽象或依賴？
實體、字段、枚舉是否符合命名與狀態約定？
跨模塊調用是否只經過契約？
事件是否在事務提交後發佈，消費者是否冪等？
是否補充了測試、README 或事件登記？
是否泄漏了密鑰、真實數據或本地路徑？

八、一個反例

需求：給“活動報名”加一個導出 Excel 的接口。

錯誤做法：

在 campaign-biz 裏直接引入 spring-boot-starter-excel-biz；
自己寫 POI 工具類；
在 Controller 裏拼 SQL 查詢報名人；
把導出邏輯塞進 system。

正確做法：

複用 spring-boot-starter-excel 的模板能力；
報名數據留在 campaign 域；
導出用例放在 campaign-biz，通過本域 Service 取數；
如果導出需要跨域用户信息，調用 ApiSysUserService，不直接查 sys_user；
補一條集成測試，驗證模板字段與數據映射。

AI 的效率來自生成速度，AI 的可靠性來自反饋速度。工作流的意義，是讓每一次生成都儘快碰到邊界。 SMALL DIFF · FAST FEEDBACK