換成 Warrant,圖紙是一份 specs/stories/<slug>.md:寫下要做什麼、哪些事不做、怎樣算合格,並由人核准。檢查機使用儲存庫自己在 AGENTS.md 指定的唯一驗證命令,不必叫做 make verify。交件時要逐條附上驗收證據,列出跳過或受阻的檢查與殘餘風險;有一條缺少通過證據,就只能說「部分完成」。這些規則的落實仍靠採用端的 CI 與人工審查,詳見 Warrant 現行說明。

想像一下,你家裡來了一個速度超級快、力氣超級大的小機器人助手。

你跟他說:「幫我把客廳樂高城堡的窗戶換成紅色的。」

五秒鐘後,機器人開心地跑回來大喊:「主人,我做好了!」

你興沖沖跑去客廳一看,當場傻眼:

  1. 窗戶確實變紅了,但他順便把城堡後面的城牆拆了,還自作主張多蓋了一個停機坪(邊界失控)。
  2. 窗戶其實裝反了,關不起來。機器人為了證明自己做得很棒,拿出剪刀把卡榫剪斷,硬黏上去(作弊式通過測試)。
  3. 當你問他剛剛動了哪些積木時,他抓抓頭,忘光光了(上下文丟失)。

這就是很多工程師現在跟 AI(例如 Claude、ChatGPT、Cursor)協作寫程式時每天上演的災難。


為什麼會這樣?因為我們犯了兩個大錯誤

  1. 我們只用「嘴巴講講」(模糊的 Prompt),以為機器人能心靈感應。
  2. 我們竟然讓「機器人自己決定是不是做好了」。機器人的天性就是想討好你,遇到卡關時,他最擅長的就是「把規則偷偷改簡單一點,假裝自己成功了」。

為了解決這個問題,舊版 ForgeFlow(後更名為 PraxisBound) 替我們的工作坊定下了三條非常簡單的規矩。


規矩一:給他一張「框起來的圖紙」(有界 Story 契約)

在 ForgeFlow 的世界裡,你想讓機器人動手,不能只在對話框裡隨便丟一句話。你必須把任務裝進一個小資料夾:

  • 要做什麼(Goal):只換窗戶。
  • 絕對不能碰什麼(Scope):城牆、大門、屋頂一律不准動。
  • 怎樣才算合格(Acceptance):窗戶必須能往外推開、颳風不能漏水。
  • 安全小測驗(Security Fixture):如果拿假人去撞窗戶,窗戶不能掉下來。

最重要的是:圖紙一旦畫好,機器人絕對不能自己改圖紙。 遇到不懂或衝突的事情,他必須乖乖停下來問你,這叫做 SPEC_BLOCKED(等主人解答)。


規矩二:唯一的裁判是「自動蓋印章機」(make verify)

這是 ForgeFlow 最厲害的一點:機器人說自己做好了,不算數!

工作坊的正中間放了一台冰冷無情的自動檢查機。當機器人覺得自己拼好積木時,他必須按下按鈕:

make verify

檢查機會自動做四件事:

  1. 量尺寸:積木有沒有對齊邊緣?(代碼排版與風格)
  2. 查卡榫:形狀有沒有接對?(靜態型別檢查)
  3. 推推看:會不會一碰就倒?(單元測試)
  4. 安全檢查:窗戶牢不牢固?(安全性測試)

如果亮紅燈(FAIL):

機器人不能跑來吵你。他必須自己看機器吐出來的錯誤單,回到桌上修理,修好後再按一次檢查機。只要機器沒亮綠燈,他就不能交件。

如果亮綠燈(PASS):

這時候,也不代表積木可以直接黏上城堡!綠燈只代表「機器檢查沒壞」。最後這座城堡好不好看、符不符合你心中的感覺,永遠由身為人類的你親自檢查(Human Review),由你決定要不要把它拼進大城堡(Merge)。


規矩三:換班時留下「積木便條紙」(無狀態 Handoff)

機器人的記憶體有限,有時候忙了一下午,電池快沒電了(Token 額度用完),需要換下一台機器人上場。

以前的機器人換班時只會留下一堆幾千字的碎碎念,新來的機器人根本看不懂。

在 ForgeFlow 裡,換班的機器人必須填一張極度整潔的小卡片(specs/handoff.md):

  • 我剛剛在做哪一張圖紙?
  • 下一個接班的要做哪一張?
  • 桌上哪幾塊積木是我動過的?哪幾塊是無關的?
  • 剛剛檢查機最後亮的是紅燈還是綠燈?

新來的機器人只要花兩秒鐘瞄一眼這張便條紙,就能無縫接軌繼續動工,完全不用重新猜測。


一張圖看懂三個角色的分工

  [人類主人] ──(畫好有界圖紙)──► [AI 機器人]
      ▲                               │
      │ (唯有綠燈才給人類看)          ▼ (拼好後放進檢查機)
      └──────────── [自動驗證機 make verify]
                            │
                            ▼ (亮紅燈?退回重拼!)
  • 你(人類):只負責動腦想點子、核准圖紙、最後欣賞成品。
  • AI 機器人:負責揮汗搬積木、修積木,禁止偷改規則。
  • 檢查機(儲存庫工具):冷酷無情、只認事實的唯一客觀裁判。

總結

AI 很聰明、速度很快,但他就像一個充滿活力但容易分心的小朋友。

你不需要教他怎麼拿工具,你只需要給他一個清楚的積木桌(有界 Story)、一台鐵面無私的檢查機(make verify),以及一張交接便條紙(Handoff)。

這就是舊版 ForgeFlow 的設計方向。若要在現在的專案採用這套工作原則,請從 Warrant 的 Story 範本 開始,先為一個小變更寫下目標、範圍外事項與驗收條件,再交由人核准。