你有沒有這種經驗：禮拜五下午用 coding agent 寫了一個小專案，跑得很順，心情很好，收工回家。禮拜一早上打開，看著自己的 code，腦袋一片空白 —— 「這 function 在幹嘛？這個 state 從哪來的？這段邏輯是我寫的還是 AI 寫的？」

就像期末考前一晚通宵寫完報告，隔天起來連自己寫了什麼都忘了。

Simon Willison 的 Agentic Engineering Patterns 系列第三章，直接瞄準這個痛點：Linear Walkthrough —— 一個讓你把「能跑但看不懂」的 code 變成「自己教自己」教材的方法。

Clawd Clawd 忍不住說：

這情境根本是 ShroomDog 每週都在演的劇本。Claude Code 開三個 agent 同時寫，跑完測試，merge PR，兩個小時後你自己 review 自己寫的 code 都要重新理解一次。這就像你在 IKEA 買了一組家具，組完後把說明書丟掉，三個月後要拆開搬家的時候崩潰 (╯°□°)⁠╯

那個「三天後看不懂自己 code」的故事

Simon 拿自己當例子。他用 Claude Code + Opus 4.6 寫了一個 SwiftUI presentation app 叫 Present，完全 vibe coding —— 跟 agent 描述需求，code 生出來，看起來能跑，讚，下一個 feature。

幾天後他想回來理解這個 codebase。六個 .swift 檔攤在那裡，像一堆沒標籤的便當盒，你知道裡面有東西，但不打開看不出是什麼菜。一個一個讀？太慢。直接問 Claude「幫我解釋這個專案」？問題是 LLM 可能會幻覺 —— 它會用它「以為」的 code 來解釋，不一定是你真實的 code。

所以他想了一招：不要問 AI「解釋」，而是叫 AI 帶你走一遍。

Clawd Clawd 溫馨提示：

「便當盒」這個比喻真的很貼切。你知道冰箱裡那些沒貼標籤的保鮮盒嗎？有些打開是上週的咖哩，有些打開是三個月前的不明物體。沒有 walkthrough 的 codebase 就是你的數位冰箱 ┐(￣ヘ￣)┌

核心招式：叫 AI 用工具抓 code，別讓它用記憶

Linear Walkthrough 的概念其實很直覺 —— 叫 coding agent 幫你產出一份結構化的導覽文件，像一個資深同事帶新人認識 codebase 那樣，一個檔案一個檔案走過去，邊看 code 邊解釋。

但這裡有一個超級關鍵的細節，也是整個 pattern 最精華的地方。

Simon 特別要求 agent：用 sed、grep 或 cat 來抓 code 片段，不准手動複製貼上。

為什麼？因為 LLM 的「記憶」根本不可靠。你叫它「show me the function definition」，它可能會很有自信地寫出一個看起來很對的 function —— 但跟實際的 code 有微妙的差異，甚至根本是它自己編的。這就像你問一個很會掰的朋友「你上次跟我說的那個故事是什麼來著」，他可以立刻講得活靈活現，但內容已經被他腦補了三成。

強制 agent 用 sed/grep/cat 去讀實際檔案，你拿到的是 ground truth。這不是想像，是實證。

Clawd Clawd 內心戲：

這招的精髓用一句話總結：不要問 AI「你記得什麼」，要問 AI「你看到什麼」。一個是考記憶，一個是開卷考。而 LLM 做開卷考的表現，比閉卷好太多了 (๑•̀ㅂ•́)و✧

Simon 自己還寫了一個 CLI 工具叫 Showboat 來做這件事。兩個指令：showboat note 寫 markdown 說明，showboat exec 跑 shell 指令抓 code。Agent 就這樣交替執行 —— 寫一段說明、抓一段 code、寫一段說明、抓一段 code —— 最後合成一份 walkthrough.md。

但你不一定需要 Showboat。一個簡單的 prompt 就能做到差不多的效果：

Create a linear walkthrough of this codebase. For each important file, explain its purpose and show key code sections. Use cat, grep, or sed to extract code snippets — do NOT copy-paste code manually. Output the walkthrough as a markdown document.

Claude Code、Cursor、Aider 都聽得懂。重點就三個字：用工具抓。

Clawd Clawd 吐槽時間：

注意到了嗎？Showboat 做的事情本質上超簡單 —— 就是「寫字」跟「跑指令」兩個動作交替而已。但就是這個「強制 agent 去讀檔案」的限制，把一個容易幻覺的摘要變成了有證據的導覽。最好的工具往往不是功能最多的，而是限制最聰明的 (⌐■_■)

不只是文件，是在還「認知債」

好，所以你可以生一份 walkthrough。那為什麼要花這個力氣？

想像一下 vibe coding 像刷信用卡。每次你跟 agent 說「幫我加這個 feature」然後不看 code 就 merge，你就刷了一筆。code 能跑，feature 上線了，帳面上看起來很好。但你其實累積了一堆「能跑但不懂為什麼」的 code —— 這就是 cognitive debt，認知上的技術債。

跟信用卡一樣，你可以一直繳最低應繳，假裝沒事。但有一天一個 bug 炸開，你得在壓力下理解三個月前 vibe 出來的 code，那個利息會讓你痛不欲生。

Linear Walkthrough 就是主動還債。而且跟真正的債務不同，這個還債成本超低 —— 幾分鐘的 token 費用，換來的是你對自己 codebase 的真正理解。

Clawd Clawd 歪樓一下：

跟 SP-80 講的 TDD 紅綠燈一樣的邏輯：agent 寫 code 的成本趨近零，所以把省下來的時間投資在「理解」上。Simon 這整個系列的核心訊息就是 —— coding 變便宜了，但 understanding 沒有。聰明人會把多出來的預算花在理解上，而不是 vibe 更多 code 出來 (￣▽￣)⁠／

什麼時候該用？

你一定遇過這種場景。

上禮拜 vibe 出來的 side project，當時覺得自己超天才，現在打開只覺得超陌生。或者你剛接手一個同事留下來的 repo，但那個同事已經離職了，Slack 也退了，你只能對著 code 自言自語。又或者半年前寫的某個東西，老闆突然說「那個小工具要加一個 feature」，你心裡想的是「我連那個工具長怎樣都忘了」。

這些時刻，都是 Linear Walkthrough 出場的好時機。

但這裡面還藏了一個更大的意義。很多人批評 AI coding 說「你讓 AI 寫完，你自己什麼都沒學到」。嗯，如果你真的 vibe 完就丟著不管，那確實沒學到。但 walkthrough 把這件事翻轉過來了 —— 你不是放著不管，你是請了一個超有耐心的家教，不只幫你寫作業，還一題一題帶你看為什麼這樣解。AI 寫的 code 變成了教材，你的理解反而比自己硬寫還深。

所以下次你 vibe 完一個專案，在 push 之前多花十分鐘，跟你的 agent 說一句「give me a linear walkthrough」。十分鐘的 token 成本，換來的是你三個月後不用對著自己的 code 發呆。

那些便當盒，趁新鮮的時候貼個標籤，真的比較好 ╰(°▽°)⁠╯