Agentic OS

TL;DR: “No evidence, no completion” is a single structural principle: a task isn’t done until the agent produces an artifact that exists outside the conversation and can be checked independently. It sounds trivial. In practice it closes most of the common agent failure modes in one rule, because the act of specifying what evidence looks like, before the task runs, forces you to define what “done” actually means. In the previous post in this series I described an agent that said a feature was done (commit SHA requested, none existed, two of three modules unchanged). The failure had a name: no external completion criterion existed, so the agent supplied its own. That gap has a one-rule fix. ...

TL;DR： Work Log 是一個很無聊的東西：一份 markdown 檔案，記錄這個任務做到哪裡、做了哪些決定、下個 session 要從哪裡繼續。它沒有解決 AI 的記憶問題，只是繞過它。但在我們找到更好的方法之前，它有效。 在那篇談治理基礎的文章裡，我說過 AI「只活在那一次的對話框裡」。這個說法的代價，在你真正開始用 AI 代理做持續開發的時候才會變得具體。 你跟 AI 花了一個小時討論這個 feature 要走哪個設計模式、為什麼不用另一個方案、資料庫的 schema 要怎麼調整。全部討論清楚了，開始實作。隔天開新對話，繼續做。AI 從頭來：哪個設計模式？資料庫？我不知道你說的是什麼。 這不是 Claude 的問題，也不是任何特定模型的問題。它就是這樣運作的。上一篇說到記憶檔案（CLAUDE.md、AGENTS.md）可以幫助 AI 記住專案的架構規則。但那解決的是「規則要記住」的問題，不是「這個任務做到哪裡」的問題。Work Log 是後者。 兩層記憶，兩個問題 先說清楚兩個東西的差別，因為我發現自己最初混在一起想。 專案記憶：這個專案的架構是什麼、用了哪些 ADR、活躍的任務清單在哪裡、哪些 skill 可以用。這是全域的、靜態的，跟任何一個具體任務無關。你不常去動它，但每次開新 session，AI 需要讀它才知道自己在什麼脈絡裡。 任務記憶（Work Log）：這個任務做到哪個 phase、做了哪些決定、下一個 session 要從哪裡繼續。它是動態的、per-task 的。一個任務一個檔案，在 Agentic OS 裡放在 .agentcortex/context/work/<task-key>.md（完整結構見 repo）。 混在一起的後果是：要麼全域狀態被塞滿具體任務細節（之後沒人看得懂），要麼任務進度沒地方記（每次都從頭）。分開之後，兩個問題各有各的解。 Work Log 長什麼樣子 下面是一個簡化版的實際樣子（來自 github.com/KbWen/agentic-os）： # Work Log: feat/email-verification ## Header - Branch: feat/email-verification - Classification: feature - Current Phase: implement - Checkpoint SHA: a3f9c12 ## Task Description 新增 email OTP 驗證流程。使用者第一次登入後需完成驗證， 未驗證帳號只能讀取，不能寫入。 ## Phase Sequence | Phase | Status | Notes | |-----------|-------------|--------------------------| | bootstrap | completed | 分類為 feature | | plan | completed | 確認走 OTP 不走 magic link | | implement | in-progress | auth module 完成，email 發送待測 | | review | pending | | ## Gate Evidence - Gate: plan | Verdict: pass | At: 2026-05-10T14:00Z - Gate: implement | Verdict: FAIL | Reason: email sending untested, scope not complete | At: 2026-05-11T09:00Z ## Phase Summary - plan: 討論了 OTP vs magic link。決定用 OTP，因為我們的 email provider 有速率限制，magic link 的 retry 設計複雜度更高。 這個決定要記住，下個 session 不要再討論。 關鍵不在格式，在那個 Phase Summary。每個完成的 phase，AI 要用一段話說：做了什麼決定、為什麼這樣決定、有什麼取捨。 ...

TL;DR: The governance problems that make AI agents unpredictable (unverified completions, state loss between sessions, unconstrained scope) are structurally identical to problems distributed systems engineering solved with audit logs, delivery acknowledgment, state machines, and least-privilege access. The one genuine difference is non-determinism: an agent given the same open-ended task twice will do something different, which means governance needs to front-load constraints rather than just catch failures after. But the rest of the pattern library applies directly. ...

TL;DR: “The agent did something wrong” usually gets diagnosed as a model problem. Most of the time it isn’t. Capability failures (wrong reasoning) and governance failures (no structure to catch wrong reasoning) look identical from the outside but need completely different fixes. This post is about telling them apart, and why most teams are currently solving the wrong one. The agent said the feature was done. I asked for the commit SHA. There wasn’t one. When I checked the branch, two of the three modules it described implementing hadn’t changed. ...

TL;DR： AI 代理失控通常不是模型的問題，而是缺少足夠的結構。這篇整理了我們在實踐中觀察到的幾個痛點，以及 Agentic OS 試著用哪些方向來應對——不保證這是最好的做法，AI 工具本身也還在快速演化。 如果你已經在用 Claude Code、Cursor 或 Copilot 一段時間，你大概知道那種感覺：有時候它快得讓你懷疑自己為什麼還要打字，但有時候你盯著它的輸出，心裡只有一個念頭——「等等，它在幹嘛？」 印象更深的往往是後者。我發現有幾類問題會反覆出現，跟你用哪個模型或哪個工具關係不大，比較像是讓 AI 代理參與真實開發這件事本身帶來的結構性挑戰。 如果你讀過從「下指令」到「蓋系統」，這篇可以看成那個思路的延伸——當你開始用 agent 做真實開發，「結構不夠」這件事的代價變得具體很多。 Agentic OS 是站在很多公開工作的肩膀上做出來的。AGENTS.md 這個慣例最初來自 OpenAI Codex 的設計，後來被 Cursor、GitHub Copilot 等主流 AI 工具廣泛採納；Anthropic 有自己的 CLAUDE.md；Cursor 有 .cursor/rules——各自代表不同工具對「怎麼讓 AI 記住專案規則」這個問題的嘗試。我們參考了這些設計，加上 Hacker News、Reddit 社群裡的實測討論，還有 Pete Hodgson、Addy Osmani、Thorsten Ball 等工程師整理的失效模式分析，試著把它們整合成一套對我們自己有用的東西。這個框架比較像是整合與實驗的產物，不是從零發明的。 幾個反覆出現的痛點 以下整理自我們自己踩過的坑，也有部分來自社群的集體觀察。不是嚴謹的研究，是實踐者的筆記。 輸出難以核查 AI 完成任務後，你拿到的往往是一段文字說「已完成」或「功能已實作」。問題是「完成」的依據是什麼？在單一短對話裡這不是大問題，但一旦任務橫跨多個 session，或者事後需要追溯某個決策的來源，你往往什麼都找不到——沒有 commit SHA、沒有測試輸出、沒有可以指著說「它在這裡」的東西。只有對話紀錄，而對話紀錄不算數。 這個問題後來直接影響了我們的框架設計。Agentic OS 裡有一條規則：就算是「重讀同一份文件」這個動作，也必須留下一筆收據。聽起來很囉嗦，但沒有這個，「我讀過了」和「我沒讀過」在紀錄裡是完全一樣的。 跳過中間步驟 給 AI 一個任務，它的自然傾向是直接往結果走。這在小任務上沒問題。但任務稍微複雜一點——比如需要同時異動前端、後端和資料庫——省掉的「先確認範圍」、「列出影響的模組」這些步驟，往往要在後面以更大的代價補回來。工程師 Pete Hodgson 在他的文章裡提到，當一個問題有很多不同的解法時，AI 選到你心目中那個的機率趨近於零——提前對齊方向，跟模型能力無關，是流程問題。 跨對話的連貫性 在那篇談 Prompt 局限的文章裡，我說過 AI「只活在那一次的對話框裡」。這個限制在用 agent 做持續開發的時候感受更強烈。每次開新對話，你得重新交代背景：這個專案的架構決策是什麼、上次決定用哪種設計模式、之前踩過什麼坑。這不只是麻煩，而是會讓同樣的問題被重新發現、同樣的決策被重新討論。IEEE Spectrum 的一篇報導裡提到，AI 在長 session 的後期，出現重複生成已存在函式、忽視早期建立的 coding convention 等情況的頻率明顯上升——本質上是 context 稀釋的問題。 ...