「對，但感覺可以更好」的感覺

開始認真設計、實作 agent 之後，我很快就遇到一種難以言明的挫折感：模型做出來的結果，常常和我腦中期待的方向差了一截。

它不是完全做錯，也不是完全做對，是會讓人覺得使用者體驗「卡卡的」。同一個任務，換個時間執行、換個 repo 執行，結果就可能不太一樣；偏偏我又說不清楚，問題究竟出在哪裡。

一開始，我以為只是 prompt 沒寫好，所以把 prompt 改得更精確、更詳細，甚至更囉唆。但這些調整雖然偶爾有效，卻沒有真正解決問題。

後來我發現，問題常常出在 agent 是否拿到了正確的 context：它看不看得到專案慣例？看不看得到真正該看的檔案？

再往後，我才意識到，即使 context 給對了，agent 使用什麼工具、在什麼樣的迴圈裡執行，以及犯錯之後有沒有機會修正，才是真正決定結果是否穩定的關鍵。

這一路走下來，形成了 prompt engineering → context engineering → harness engineering 的自然演進。

每一個階段，都在解決上一個階段難以處理的問題。但同時我也越來越清楚：如果真的想讓 agent 變得「可控」，又不想讓成本失去控制，答案不只是把 prompt 寫得更漂亮，而是要設計它實際運作的整個環境——也就是 harness。

為什麼是 Harness Engineering

Prompt engineering 談的是怎麼下指令，context engineering 談的是怎麼餵資訊，
但這兩者都預設了一件事：agent 的執行方式是固定的、給定的。
Harness engineering 把這個假設拿掉，直接把 agent loop、工具、記憶、回饋機制都當成可以設計、可以拆解、可以量測的東西。

對我來說，這是目前為止概念最完整的一層——它不是取代 prompt 或 context engineering，而是把它們都收進同一個框架裡，讓「可控性」和「成本」變成可以同時被討論和被優化，而不必被視為二選一的難題。

為什麼想寫這個系列

寫這個系列，對我自己來說有兩個目的：

• 講給讀者聽：把 harness engineering 這個目前還沒有標準教材的概念，整理成一套有結構、看得懂的內容，而不是一堆零散技巧。
• 講給自己聽：真正釐清並熟悉一個概念的方法，是逼自己把它寫出來、講清楚。這個系列的產出，某種程度上也是我把 harness engineering 從「有點懂」推進到「真的懂」的過程。

為什麼選 Pi

這系列選 Pi Coding Agent 當作實作載體，原因不複雜：它是開源的，而且刻意做得很極簡。
極簡的好處是，它的 agent loop、工具集，以及 context 載入方式，都沒有藏在大量商業邏輯後面。我可以一層一層把它拆開來看、拆開來改，也可以拆開來量測。

這件事在 Day1 先講到這裡就好，技術上「極簡為什麼等於可歸因」——也就是為什麼這件事對這系列的實驗設計特別重要——留到 Day4 再深入。

這系列會讓你帶走什麼

三十天走完，我希望你帶走的東西，依序是：

1. Harness 的具體技術：Agent Loop、Context 載入、Skills、Tool Runtime、Sandbox 這些元件實際上怎麼設計、怎麼實作。
2. 一套歸因的方法論：下次你的 agent 表現異常，能有意識地區分「是模型的問題、prompt 的問題、harness 的問題，還是環境本身在搞鬼」，而不是憑感覺猜。
3. Pi Coding Agent 的基本操作：跟著系列走一遍，你會知道怎麼裝、怎麼設定、怎麼開始用它做事。

怎麼驗證，不是憑感覺判斷

這個系列不會只用「我覺得這樣比較好」來下結論。

凡是牽涉到「拿掉某個 harness 元件之後會發生什麼事」的主張，都會透過對照實驗來驗證：重複執行多次，觀察整體分布，而不是只看單次結果或平均值。

實驗如何設計、任務如何挑選、數據如何收集，會在系列中段隨著儀器一起建立。

這個系列提出的每一個「更好」，都必須能夠被重新執行與驗證。

明天

Day2 會把鏡頭拉近，先建立一個共同的心智模型：一個 coding agent 收到任務之後，到底在做什麼。這是後面拆解每個 harness 元件的地基。