持續三個月的努力，DAP 在7/31正式開放上線了。

系統上線後，需求還是持續進來。回頭整理這三個月的開發紀錄，specs/ 已經累積 107 個編號資料夾，我在想，這些規格都代表每一次修改所留下痕跡。Agent 接到下一個任務時，會對應一份執行的文件。

• Spec 適合記錄一次變更，功能現況需要另一個入口收斂。
• 我用 Diátaxis 的四種文件需求，重新區分教學、操作方法、固定規格與設計原因。
• CLAUDE.md、Agent 文件、Skill、Spec 與 Test 各有不同責任，全部塞進同一份文件會愈來愈難找。
• 文件整理的目標，是讓人與 Agent 都能從短入口找到這次任務需要的資料。

107 份變更紀錄，無法直接回答現在長什麼樣

DAP 的 Spec 採用「一次變更一個資料夾」。這個做法很適合追歷史，也保留了當時的需求、Plan、任務與驗收情境。

問題出在同一個功能持續修改。

「我的單據中心」先在 098 拆成三個側邊欄入口，到了 102 又把原頁面調整回四個分頁，接著 103 再加入搜尋列與統計數字。Agent 如果只搜尋到 098，會以為頁面只剩待處理清單；讀到 102 才知道四個分頁已經回來。

spec.md 記錄的是「那一次改了什麼」。它是一份變更歷史，功能目前的完整樣子分散在多次修改裡。

我後來在 specs/README.md 加了一層功能索引，把 107 個資料夾收斂成 13 個主要功能與幾個共用機制。每個功能先寫現況摘要，再依新到舊列出相關 Spec。

這一層解決了第一個問題：Agent 可以先找功能，再往下追變更。

整理時又看到第二個問題。_shared/pages-overview.md 還停在 5 月的「Phase 2 建立中」，系統卻已經上線；endpoint_mapping.md、API Contract 與 Data Model 也有各自的更新節奏。文件存在，內容不一定代表現在。

整理工作因此多了三個欄位：每種資訊應該放在哪裡、誰負責更新，以及哪一份才是來源。

用四種需求整理長期文件

我採用 Diátaxis 來整理長期知識。它把技術文件分成四類：Tutorial、How-to、Reference 與 Explanation。四類文件各自對應一種閱讀目的。(Diátaxis)

放到 DAP，大致會變成這樣：

這四類負責長期知識。原本的 Spec 繼續保留，負責記錄某一次需求為什麼發生、當時改了哪些範圍、如何驗收。

107 份 Spec 保留原本位置與歷史脈絡。我在它們上方建立文件地圖，再把重複出現、已經穩定的知識提煉到長期文件。

SDD、Agent 文件與 Skill 各自保存什麼

整理文件時，我把目前使用的幾種檔案重新排了一次。

短入口
CLAUDE.md／AGENTS.md
  ↓ 指向需要的文件

單次變更
spec.md → plan.md → tasks.md → scenarios.md

角色邊界
.claude/agents/*.md

可重複流程
.claude/skills/*/SKILL.md

長期知識
Tutorial／How-to／Reference／Explanation

可執行事實
Test／Schema／Lint／CI

CLAUDE.md 適合當入口，放工作流程、硬性限制與文件位置。詳細業務規則留在各自的來源文件。

Agent 文件是一份角色契約。前端 Agent 需要知道輸入來源、可以修改的範圍、硬性規則、驗證方式與停止條件。它的核心是可執行的工作邊界。

Skill 保存可重複的操作程序。/orchestrate 讀取任務、判斷角色、分析檔案衝突、安排批次，再停下來等待確認。這種內容屬於 How-to，但它的主要讀者是 Agent，因此使用固定欄位與明確步驟。

Test、Schema、Lint 與 CI 保存可以被機器檢查的規則。互斥條件曾經出錯，修正後若只在 Explanation 寫一段心得，下一次仍可能再犯；把條件放進測試，Agent 才能在完成前得到明確結果。

CLAUDE.md 只當文件地圖

文件開始增加後，很容易把所有提醒都補進 CLAUDE.md。檔案會變長，重複規則也會開始互相衝突。

OpenAI 分享 Agent-first repository 的做法時，提到他們曾使用一份很大的 AGENTS.md，最後改成短入口搭配結構化 docs/。Agent 先讀地圖，再依任務逐層取得需要的內容。(OpenAI, Harness engineering)

AGENTS.md 也提供跨工具可讀的專案指令格式，內容通常包含建置、測試、程式風格與安全注意事項；大型專案可以在不同目錄放置局部規則。(AGENTS.md)

DAP 目前使用 CLAUDE.md，做法可以保持簡單：

## 任務開始前

- 功能現況：先讀 `specs/README.md`
- 本次變更：讀對應的 `spec.md`、`plan.md`、`tasks.md`
- API 與資料結構：讀 `docs/reference/`
- 重複操作：使用 `.claude/skills/`
- 設計原因：讀 `docs/explanation/decisions/`
- 完成條件：執行對應測試與驗證指令

入口只負責導航。細節回到各自的來源，更新時也比較容易找到負責位置。

我替文件建立一張分流表

之後每次完成需求，我可以用這張表判斷新資訊要去哪裡：

這張表也補上一個維護欄位：負責人、適用範圍、最後驗證日期與來源。pages-overview.md 顯示的「Phase 2 建立中」就能被辨識成待確認內容，Agent 也能依日期與來源判斷是否需要重新查證。

今天可以先做的事

先從 Agent 最常找錯的地方開始：

1. 列出目前所有文件與用途。
2. 標記它屬於單次變更、角色契約、操作流程、長期知識或可執行規則。
3. 找出同一資訊出現兩次以上的位置。
4. 指定其中一份為來源，其他地方改成連結。
5. 在入口文件寫清楚「遇到哪種任務，要往哪裡找」。

可以先產出一張最小文件地圖：

| 資訊類型 | 主要入口 | 來源 | 負責人 | 最後驗證 | 更新時機 |
| --- | --- | --- | --- | --- | --- |
| 功能現況 |  |  |  |  |  |
| API 規格 |  |  |  |  |  |
| Agent 規則 |  |  |  |  |  |
| 操作流程 |  |  |  |  |  |
| 設計決策 |  |  |  |  |  |

上線後，我開始整理 Agent 的知識入口

前三個月，我在意每次需求能否留下 Spec、Plan、Task 與 Scenario。累積超過 100 份後，我開始關心下一個人或 Agent 能否找到現在有效的答案。

這次整理讓 SDD 的位置更清楚。它管理一次變更；Diátaxis 管理長期知識；Agent Contract 管理角色邊界；Skill 保存可重複流程；Test 與 Schema 保存能被執行的規則。

文件地圖完成後，下一個問題也浮出來了。第三代 DAP 的 Agent 都在協助我開發頁面。第四代，我想讓 Agent 站到使用者這一側，理解每個功能需要哪些資料，協助完成一張申請單。

Day 26，開始畫第四代 DAP 的第一張設計圖。