從即興到可審計：為何你的 AI 協作需要一份工程日誌

我們已習慣將大型語言模型（LLM）視為一個無所不知的對話夥伴，透過問答來輔助編程、除錯與系統設計。但這種互動模式隱藏著一個根本問題：對話是短暫且非結構化的。當 AI 協作缺乏可回溯的歷程，所有產出都只是一種不可審計的即興生產，決策的脈絡隨著對話視窗的關閉而煙消雲散。將對話、決策與操作軌跡沉澱成一份工程日誌，是讓 agent workflow 進入可驗證、可接手、可治理狀態的唯一途徑，這不僅是最佳實踐，更是專業系統開發的必要環節。

為什麼即興的 AI 對話會累積技術債？

在軟體開發的場景中，我們無法接受一位工程師的貢獻是完全無法追蹤的。他的程式碼需要經過版本控制（如 Git），設計決策需要在文件中記錄，工作進度則透過專案管理工具追蹤。這些機制確保了工作的可見性、可追溯性與可交接性。然而，當我們引入 AI 協作者時，卻常常忽略了這些基本原則。

當一位開發者透過與 AI 的數十次對話，最終完成一個複雜的模組時，那些對話本身就是寶貴的資產。它們記錄了需求的演變、技術的權衡、失敗的嘗試，以及最終方案的形成過程。如果這些資訊只存在於開發者的記憶和瀏覽器分頁中，它就具備了技術債的所有特徵：

• 不可審計（Unauditable）：當系統出現問題，我們無法回溯當初 AI 提供了什麼建議、基於哪些假設，也無法評估其建議的品質。這對於需要遵循嚴格合規性與安全標準的專案來說，是個巨大的風險。
• 難以交接（Poor Hand-off）：當專案需要交棒給另一位開發者，新成員無法理解前人是「如何」得到這段程式碼的。他只能看到結果，卻看不到過程，這大幅增加了維護與迭代的成本。
• 知識流失（Knowledge Drain）：每一次成功的 AI 協作經驗，都應該能提煉出可複用的模式或 prompt engineering 技巧。即興的對話讓這些寶貴的隱性知識隨風而逝。

這種工作模式，實際上是將 AI 視為一個外部的黑箱顧問，而非整合進開發流程的系統元件。要解決這個問題，我們需要一種機制，將非結構化的對話轉化為結構化的日誌。

Claude Code 的本地日誌功能，帶來了什麼啟示？

最近，Anthropic 的程式設計專用模型 Claude Code 提供了一個極具啟發性的功能。根據開發者社群的觀察與分析，Claude Code 會自動將使用者與模型的完整對話，以 JSONL（JSON Lines）格式儲存在本地端的 ~/.claude/projects/ 目錄下。

這個看似微小的設計，卻是思維模式上的巨大轉變。它將原本存在於雲端的、短暫的對話，轉化為本地的、持久的結構化資料。每一個對話 session 會儲存成一個獨立的 .jsonl 檔案，而檔案中的每一行就是一則訊息，包含了精確到毫秒的 UTC 時間戳、訊息類型（使用者或助理）、以及完整的訊息內容。

真正的價值不在於對話本身，而在於對話被自動化、結構化地記錄下來。這使得 AI 協作的過程，從一種「記憶」變成了一種可供分析與處理的「數據」。

這種作法為我們打開了新的可能性。我們不再需要手動複製貼上對話內容，而是可以透過程式化的方式，自動解析、篩選並整合這些開發歷程。這正是建立一份可審計工程日誌的基礎。

如何打造一份可操作的 AI 開發日誌？

有了結構化的日誌檔案，我們就能將 AI 互動紀錄與傳統的開發工作流（例如 Git 提交紀錄）結合，打造一份真正有意義的工程日誌。這份日誌能清楚地呈現「為何這麼做」（AI 對話脈絡）與「做了什麼」（程式碼變更）之間的關聯。

實作上，我們可以透過簡單的命令列工具來達成。例如，使用 jq 工具，我們可以輕易地從 JSONL 檔案中篩選出特定時間範圍內所有使用者的輸入（prompts）：

jq 'select(.type == "user") | {timestamp, content: .message.content}' your-session-file.jsonl

接著，我們可以將這個指令的輸出，與特定時間範圍內的 git log 紀錄進行對應。例如，我們可以查詢過去 24 小時內的所有 AI prompts 和 Git commits，並將它們按時間排序。如此一來，一份整合的開發日誌便應運而生，它可能長得像這樣：

• 14:30:15 [AI Prompt]: 「為這個 Django model 設計一個 REST API endpoint，需要支援 GET 和 POST。」
• 14:45:02 [Git Commit]: `feat: add initial API view for Product model`
• 15:10:20 [AI Prompt]: 「很好，現在請為 POST request 加入 validation，確保 price 欄位是正整數。」
• 15:25:50 [Git Commit]: `fix: add validation for price field in Product API`

這份日誌不僅記錄了程式碼的演進，更重要的是，它保留了「為什麼」會有這些演進的決策脈絡。這讓程式碼審查（Code Review）變得更有深度，也讓未來的維護者能快速理解歷史背景。這種可追溯性是專業工程實踐的核心，也是AI 治理框架中強調的關鍵要素。

當 AI Agent 的能力越來越強，能夠執行更複雜的任務鏈（Chain-of-Thought）或與外部工具互動（如 ReAct 框架），一份詳盡、可審計的操作日誌將變得更加不可或缺。它不僅是除錯與優化的基礎，更是確保 AI 系統行為符合預期、安全可靠的基石。

從今天起，我們應該重新審視與 AI 的互動方式。不要再將它視為一次性的對話，而是將每一次互動都當作需要被記錄、被管理的工程日誌。這不僅能提升個人生產力，更是讓整個團隊、整個組織的 AI 協作能力邁向成熟的關鍵一步。

延伸閱讀

• Claude Code の会話履歴を JSONL として横断的に追跡する (日文)
• NIST AI Risk Management Framework
• ReAct: Synergizing Reasoning and Acting in Language Models (arXiv)
• jq Manual

我是江中喬，一位具有 TPM 與產品管理背景的 AI 系統建構者，目前專注於 AI 認知增強系統與多 Agent 協作架構的設計與實踐。