Always in the middle of something.

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： 在裝任何框架之前，有一層治理是免費的：在專案根目錄放一個 AGENTS.md 或 CLAUDE.md，養成開口要求 evidence 的習慣，開始任務前先說清楚什麼不能動。這三件事不能替代跨 session 的狀態管理，但能擋掉大部分常見問題。這篇說的就是怎麼做、做到什麼程度、在哪裡會失效。 有一段時間我的 Claude Code 工作流裡沒有任何框架，只有對話和一堆臨時 prompt。某天我做了兩個改變：把專案的架構決策寫進一個 CLAUDE.md，還有在每次 AI 說「好了」的時候問一句「commit SHA 是什麼？」 一類問題幾乎消失了：AI 在新 session 裡對著不存在的設計模式寫程式碼的情況，以及我接受了「完成」卻發現什麼都沒變的情況。不是所有問題都解決了。但那兩件事的性價比，讓我後來開始認真想「在裝框架之前，這個層面的治理到底能做多少」。 這篇是AI 代理常見痛點與我們的嘗試的延伸。那篇列了五個反覆出現的問題，這篇專門回答：只靠 prompt 習慣和 skill 選擇，能解決多少？ 記憶檔案：解決跨 session 失憶的最低成本方案 AI 代理在每一個新對話都是空白狀態。它不記得上次的架構決策，不記得你說過不要用哪個 pattern，也不記得你已經有一個 utils/auth.ts，所以它再寫一個新的。這個問題在 IEEE Spectrum 的報導裡有量測數據：長 session 後期，AI 重複生成已存在函式、忽視早期建立的 coding convention 的頻率明顯上升。 三個工具在試圖解決同一個問題： AGENTS.md 是 OpenAI Codex 最初設計的慣例，後來被 Cursor、GitHub Copilot 和 Google Antigravity 等主流工具廣泛採納。它的設計邏輯是：在任何工具讀取它之前，先告訴工具「這個專案是怎麼運作的、你可以做什麼、不可以做什麼」。 CLAUDE.md 是 Anthropic 針對 Claude Code 的版本。Claude Code 在每個新 session 開始時自動注入這個檔案的內容，所以你放在這裡的東西就等於是每次都在對話開頭重新說一遍。 .cursor/rules 是 Cursor 的對應物。原理相同。 ...

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 稀釋的問題。 ...

TL;DR: A “Skill” in production AI is not a saved prompt — it’s a capability abstraction layer with a defined input schema, tool bindings, validation, and retry logic. This post explains why that distinction matters and how Skills fit between raw model calls and higher-level agent orchestration. This post is part of a series on building real AI systems. If you haven’t read the previous piece on moving beyond prompts, that’s a good place to start. ...

TL;DR： 只靠 Prompt 是在做手工藝，不是蓋系統。這篇文章拆解 Prompt → Skill → Workflow → Agent → System 五個層級，用「寫技術文章」的完整案例，說明每個層級解決什麼問題、為什麼上一層不夠用。 前言：別在 Prompt 的死胡同裡打轉 現在只要打開社群媒體，滿地都是「最強 Prompt 指令集」或「這 10 個指令讓 AI 變神級工具」。 剛接觸 AI 的時候，我也沉迷過這種「咒語」的力量。但實戰幾次後你會發現，如果你還在糾結如何微調 Prompt 的那幾個形容詞，那你其實還是在做「手工藝」。這種方式產出的結果不穩定、無法規模化，更重要的是，它非常耗神。 如果你有留意近一兩年的技術演進，你會發現真正的高手已經不再討論怎麼寫咒語了。大家在聊的是 Workflow（工作流）、Agent（代理人） 以及 System（系統）。 這篇文章我想從一個資深開發者與 PM 的視角，拿一個最簡單的任務——**「寫一篇高品質的技術文章」**做案例，帶你看這幾個層級的思維斷層在哪裡。 1. Prompt 層：一次性的「介面」溝通，也是體力活 這是最基礎的使用方式，你打開 ChatGPT，輸入一段話： 「請幫我寫一篇關於 AI Workflow 的技術文章，包含架構說明與範例。」 這就是 Prompt 層。雖然它很強大，但本質上它只是在「調用模型」。它的限制顯而易見： 抽盲盒效應： 成果好壞全看運氣。今天給你 80 分，明天可能只剩 60 分。 孤島式作業： AI 沒辦法讀取你電腦裡的其他資料，也不懂你的審美標準，它只活在那一次的對話框裡。 認知負荷高： 每次遇到新文章，你都要重新把需求、背景、限制條件再描述一遍。 老實說，Prompt 只是個「對話介面」，而非一個「系統」。 它適合處理小型、零碎、一次性的任務（像是修一個小 Bug 或翻譯短句）。但如果你想靠它穩定產出專業內容，那只是在用 AI 換另一種形式的「體力活」罷了。 2. Skill 層：把「手感」封裝成「能力模組」 當你對 AI 寫作有了點心得，你會發現有些要求是重疊的。這時候，你會開始定義一套固定的「寫作標準」。這在開發者眼中，就是所謂的封裝（Encapsulation）。 ...

TL;DR: Minified JSON is unreadable at a glance. This post explains why JSON formatting matters for debugging APIs and config files, and walks through a browser-based formatter that validates and prettifies JSON in real time — no setup needed. If you’ve ever tried reading a minified API response by eye, you know how painful it gets. One long line, no indentation, nested objects buried inside nested objects — it’s basically unreadable. ...

Last updated: April 8, 2026 ／ 最後更新：2026 年 4 月 8 日 English This Privacy Policy explains how kbwen.com (“the Site”) collects, uses, and protects your information when you visit. 1. Information We Collect We do not directly collect personal data. However, third-party services embedded in this Site may collect data as described below. 2. Third-Party Services Giscus (Comments) The comment system is powered by Giscus, which uses GitHub Discussions. If you leave a comment, your interaction is subject to GitHub’s Privacy Policy. No account is required to read comments. ...