Day 12 的 Security Agent 完成檢查後，我會先確認修法與剩餘風險，再進入文件更新。

剛開始做這套流程時，我把文件當成每次功能完成後要補齊的工作。實際跑過幾輪後，我發現文件會直接影響下一次開發。下一個 LLM session、接手同仁或 QA，都需要從固定位置了解功能目前怎麼運作。

Step 8 的工作，是把已確認的改動整理回專案文件，讓下一次開發有共同起點。

• DAP 的文件分成使用者手冊與工程師文件。使用者手冊說明操作流程；工程師文件記錄 API 串接、篩選規則與維護細節。
• 098 單據中心改版時，Documentation Agent 曾把 Spec 的決策過程帶進工程師手冊。後續調整後，Spec 保留決策歷史，手冊專注描述現況。
• Documentation Agent 協助同步內容；我確認本次功能已更新到對應文件後，才把內容留下來給下一次使用。

文件更新讓下一次開發有共同起點

程式完成後，專案裡會留下很多資訊：Spec、Plan、Task、Git diff、Scenario、資安審查結果，還有不同版本的操作手冊。這些資訊若散在歷史資料夾與對話紀錄裡，下一次修改仍要花時間重新拼湊。

我希望下一個人或下一個 LLM session 能快速找到三件事：這個功能現在怎麼用、它的資料怎麼走、哪些規則仍然有效。文件更新就是把這些資訊整理成可查詢的現況。

程式與驗證完成
  ↓
我確認資安結果
  ↓
更新手冊與功能索引
  ↓
下一次人員／LLM 讀取目前文件

文件更新需要和本次程式異動、驗收結果與人工確認一起完成，才能成為下一次的參考資料。

098：工程師手冊需要說明現在的系統

第三代的單據中心改版，同時調整頁面、資料整理、流程與文件。功能完成後，Documentation Agent 依 Spec 與程式異動更新工程師手冊。初稿帶入許多 Spec 裡的決策敘事，例如原始需求如何釐清、當時怎麼判斷、採用什麼方案，以及 Spec 編號。

這些內容適合保存在 spec.md 和 plan.md。我日後回頭追查「當時為什麼這樣改」時，會從這兩份文件找答案。

工程師手冊承擔的是另一件事。維護功能時，我需要快速查到現在有哪些入口、資料怎麼處理、API 怎麼串、畫面有哪些篩選邏輯。決策過程直接搬進手冊後，文件讀起來像 changelog，讀者要先看完歷史討論，才能找到現況實作。

後續修正把兩種內容放回各自的位置：Spec 保存歷史，手冊描述現況。

同一個功能需要留下不同層次的資訊。使用者手冊讓同仁知道如何申請與送出；工程師文件讓開發者知道資料如何交換、哪些條件影響畫面；Spec 與 Plan 則保留這次改動的原因。

Documentation Agent 先同步文件，我確認功能是否已更新

DAP 的 Documentation Agent 在 Step 8 會讀取本次的 Spec、Task、Scenario、Git diff 與既有文件，盤點需要同步的內容。

使用者手冊會整理成操作流程。工程師文件會補 API 串接、篩選規則與維護細節。功能索引則更新現況摘要，讓下一次能找到最新的 Spec。

我最先確認的是，本次修改的功能是否已更新到對應文件。接著會看使用者手冊是否清楚說明操作流程，工程師文件是否保留 API 與額外篩選條件等維護資訊。

我最常要求 LLM 修正的情況，是它把 Spec 直接寫成使用者手冊。Spec 裡會有開發討論、功能範圍與驗收條件；使用者手冊則需要轉換成操作步驟、欄位用途與送出後會看到的結果。這個轉換由我確認，因為我知道這份文件會交給哪一類讀者。

Spec / Plan / Task / Scenario / Git diff
                ↓
      Documentation Agent 產生同步清單與初稿
                ↓
   我確認本次功能已更新到對應文件
                ↓
使用者手冊／工程師文件／功能索引

這樣的分工讓 Agent 處理盤點、初稿與重複格式，我負責確認內容是否符合功能、讀者與目前程式。

文件成為 Context 前，要先和程式現況對齊

文件會進入下一次工作的 Context。過期截圖、錯誤欄位說明與舊流程，都會讓 LLM 從錯誤的前提開始修改。

DAP 曾遇過兩個很具體的情況。一次需求文字指定了一個文件位置，實際內容卻在另一份文件裡；另一次頁面改版後，使用者手冊內嵌的截圖仍停在舊版。這些問題都需要先對照實際程式與畫面，再更新文件。

Anthropic 在談 Context Engineering 時，建議保留與當前任務相關、訊號足夠的資訊。Effective context engineering for AI agents 對我來說，文件索引與雙版手冊的作用就是把目前系統的操作、規則與入口整理在找得到的位置。

DAP 沒有針對文件更新前後建立量化測試，因此我不會把這套做法寫成降低模型錯誤率的證明。它先解決一個很實際的協作問題：下一次工作有地方可以查目前版本的說明。

今天可以做的：替一個功能建立最小文件組

今天不需要先建 docs site，也不需要建立 Documentation Agent。選一個剛完成或常被修改的功能，先把下面五份資訊放在固定位置。

spec.md             這次為什麼改、範圍與驗收條件
plan.md             採用什麼做法、影響哪些範圍
scenarios.md        驗收步驟與預期結果
docs/<feature>.md   現在怎麼使用或維護
specs/README.md     功能現況與最新 Spec 入口

接著把這次的 Spec、Scenario、Git diff 與既有文件交給 Claude Code，請它先列出需要同步的文件與初稿。確認內容時，依序檢查功能是否已寫進去、使用者流程是否易懂、工程師資訊是否能支撐維護，以及索引是否指向最新資料。

請讀取本次 spec.md、plan.md、scenarios.md、Git diff 與既有文件。
列出這次需要更新的使用者手冊、工程師文件與功能索引。

使用者手冊說明操作流程、欄位用途與使用者會看到的結果。
工程師文件說明目前的資料流、API／服務串接、篩選或驗證規則。
Spec 與 Plan 保留決策歷史。

請先輸出更新清單與文件初稿，標記無法從程式確認的內容，等待我確認後再寫入。

先讓每一份文件回答不同問題，再讓 AI 協助同步內容。這個順序能讓文件在後續維護時保持可讀性。

Part 2 小結：一個功能，第一次有了完整的開發路徑

Day 06 到 Day 13 的八個步驟，讓單一功能第一次有了一條從需求到文件、人和 AI 都能接手的完整路徑。

跑完這一輪，我手上會多出這些東西：spec.md、plan.md、tasks.md，一組 API contract 或 mock，一份 scenarios.md，一次資安審查紀錄，以及更新到現況的文件。它們不是為了讓專案看起來完整，而是讓下一個人、下一個 session，甚至下一個 Agent，能從同一個地方接手。

098 的文件經驗也讓我把資訊放回各自的位置：Spec 與 Plan 保存決策歷史，使用者手冊說明操作，工程師文件描述目前的技術行為。Documentation Agent 負責盤點與初稿，我確認本次功能是否已更新到對應文件；確認過的內容，才會成為下一次人與 AI 可以依據的 Context。

這條路徑出來後，再來就是要讓他平行迭代

這是第三階段的第一個里程碑，釐清做一個需求所需要的8步驟，目前僅完成一個項目。

第三代到這裡，距離 7 月 31 日上線剩不到三個月。這段時間我要完成剩下 11 項既有功能的頁面調整，加上開發一套完整的編審放流程，還要做兩次 UAT。需求不會排好隊一個一個進來，它們會同時到：有些偏前端，有些動到資料規則，有些是文件工作，其中幾件還會改到同一個檔案。

我試過把這幾件事塞進同一條 Spec → Plan → Task 流程，很快就發現：這條路徑一次只跟得上一個功能。前一件還在驗證，下一件的 Spec 已經在等，文件永遠排在最後才動。

Day 14 從那一週開始講。當需求同時變多，協調本身就變成一件要處理的工作。

參考資料

• Anthropic. Effective context engineering for AI agents, 2025-09-29.