Featured

Vibe Coding: Snapshot

tzangms

• 8 min read
Vibe Coding: Snapshot

最早我在小海報 61 提出了 Snapshot 這個概念，最近回頭一看發現以前寫的似乎不是那麼完整，再來是最近半年把 snapshot 這件事又延伸了一輪，但在寫文章時發現篇幅太長，覺得需要先有一個前導文，於是就有了這一篇。

什麼是 Snapshot?

Snapshot 是一個快照檔案，包含了程式的功能跟輪廓，
是給 AI 的一份地圖

Snapshot 的功能跟用途主要有下面這些:

  1. 讓 AI 知道現在有哪些東西
  2. 什麼東西在哪個檔案裡
  3. 哪個東西是什麼用途

再來 snapshot 應該具備一個重點:

Snapshot 的檔案應該盡量小、不佔用太多 context 空間。

這樣一來 AI 透過 snapshot 就能夠省去非常多的搜尋跟讀取檔案的時間，讓 AI 可以快速進行檔案、功能的定位。

那 snapshot 檔案要長成什麼樣子? 大概是這個樣子：

snapshot.json: 這個是 prettify 過後的樣子，實際的檔案應該是去除掉空白跟換行

上圖以 (django 的) view 為例子，不熟悉 Django 的人可以把這個當成是 controller，這個檔案標示了各種頁面功能，然後用 docstring 來作為對應的說明。

這樣一來 AI 就能夠透過這個知道像是 ... 「服務條款」在哪裡，叫作什麼名字，template 是哪一個?

透過這樣的內容，AI 只讀取這個 Snapshot 檔案，讀取一次就能夠知道整個專案的樣貌，能夠大幅降低搜尋跟讀取檔案的時間。而不是搜尋、讀取了一堆檔案才知道。

為什麼會開始做 Snapshot?

2025 年開始，在進行了 3 個月的 Vibe Coding 之後，在小海報裡面整理了以下幾個 Vibe Coding 的心得:

  • 開發新東西很快 / 修改舊東西有點慢
  • AI 有時會不知道有什麼既有功能，開始開發重複功能
  • 開發了一個月之後的維護難度提升
  • 文件很重要，但維護文件還是有點麻煩

而有經驗的開發者可能都已經注意到，當專案規模擴大後，AI 處理效率會開始下降，因為:

  1. 搜尋的檔案變多，搜尋的時間開始倍增
  2. 讀取單一檔案的時間開始變長，因為檔案開始變很大了

AI 需要大量掃描既有程式碼，甚至在沒有完整掃描的情況下，AI 可能就開始開發「已經存在的重複功能」，而非利用既有功能來進行擴充。

過去在透過 AI 開發時，為了提升效率，需要不斷為 AI 提供上下文（context），標示檔案或功能範圍，協助 AI 快速定位資源，也避免重複開發。顯而易見的是，隨著檔案規模擴大，AI 的處理速度減慢，功能查找也變得更加耗時。

過去寫了 README.md 或者是 TODO.md 以為夠用，但很顯然的只準備給人類看的文件已經不夠了。

所以我覺得需要產生一份給 AI 看的文件，便開始思考做 snapshot 這件事。

開始開發 Snapshot 產生器

不過上面的想法想了一陣子，但實在是沒動力去開發做實驗，直到某天開發某個專案 - Transivox 的功能時，這個服務原本已經有下載 youtube, podcast 等功能，某天打算加上 twitter space 的支援，可想而知，大部分的功能應該都是修改既有功能就可以達成了，結果 AI 卻打算把所有的功能都重新開發。

我看到下圖的當下我就決定打算暫停開發，先把搞定 Snapshot 後再繼續往下。

下面這張圖就是我碰到全部東西都要重新開發的狀況:

AI 規劃的方向是把所有的功能都自己重新做一遍

後來按照這篇文章所提到的方式，寫了一個 snapshot 產生器，生成 snapshot 並叫 AI 讀取，所有東西就像下圖一樣，開始按照預期的運作，也證實了我的想法，有夠開心!

讀取 snapshot 後，全部變成修改既有功能，不需額外提供 context

從此之後 snapshot 變成是我的必備文件了。提供 snapshot 並設定了 .cursorrules / CLAUDE.md 記得讀取 snapshot.json ，後續開發都省下了非常多的力氣跟時間。

透過程式來產生 snapshot

有人問我說，為什麼是透過程式來產生 snapshot?

我說直接利用 AI 做 snapshot 這件事並不現實，我常說「要知道 AI 擅長跟不擅長什麼」，做 snapshot 這件事，讀取大量檔案並不是 AI 所擅長的事，這也是為什麼專案變大的時候，AI 的需要的時間會越來越久。

所以請 AI 寫程式來做 snapshot 才是正解，而且後續隨著專案更新，也不用擔心 snapshot 更新問題，因為透過程式生成 snapshot，通常不用幾秒就能夠搞定，但如果透過 AI 可能會需要 10 倍或是百倍的時間。

而我最一開始給 AI 的 prompt 是這樣的:

請寫一隻 python 程式來掃描這個專案做 snapshot 文件，
這個文件能後續讓 AI 閱讀，可以知道有哪些既有的功能/function等，
可以快速了解並重複使用既有功能，並且不重複開發功能。
只需要讓 AI 容易閱讀即可，不必讓人類容易閱讀。
盡量讓檔案維持精簡，希望不要佔用太多 token。

我最一開始用來產生 snapshot generator 的 prompt

有了 snapshot 能夠快多少?

後來我還寫了程式來做實驗，下面這個是實驗的結果，可以清楚看到呼叫了幾次工具，搜尋了幾個檔案跟整個步驟。

如果你觀察過這些 AI 開發的運作的話，不難發現像是 Claude 就會需要先猜測關鍵字來進行多個步驟的搜尋，如果你用的字沒有對上的話，時間就會花上更久。

而根據這個測試結果，有 snapshot 協助定位的結果是快上 75% !

光是 snapshot 就能夠幫你在下指令請 AI 開發時，每次都省去好幾分鐘的時間。想像一下你一天會做多少次這件事，長期下來可以省下多少時間。

更重要的是，還能夠降低開發錯誤，避免開發重複功能，後續造成鬼打牆的狀況，省下的不只是定位的時間。而且可以讓思緒不會整個停擺，這件事非常的重要。

以上就是做 snapshot 的好處跟整個心路歷程，至於為什麼只講心法，不直接提供程式出來，是因為大家用來開發的程式語言都不一樣，很難應用到所有人跟語言的場景。

再來近期我又大大的的加強了 snapshot 的做法，做了一個升級版的 snapshot 2.0，這個版本佔用了更少的 context，而且定位更加精準的做法，等我寫下一篇 Snapshot 2.0 吧!

想知道更多進階版本的想法的話，也請留言讓我知道!