模型變強後，初始 Markdown 的重點：從規則清單轉為可驗證的工作地圖
近來「重寫 initial Markdown」的討論，來自新一代模型在理解任務、規劃多步驟工作、使用工具與從錯誤中恢復方面的明顯進步。模型能承接更大的工作單位，也能依檔案、指令與文件自行補齊更多執行細節；人的工作重心因此逐漸從逐步指揮，轉向提供正確的專案脈絡、清楚的邊界與可驗證的成果定義。
早期的 coding agent 與模型較容易遺漏限制、選錯工具、過早宣告完成，或在長任務中失去進度。因此，團隊常將大量「第一步做什麼、第二步做什麼」、「永遠使用某種格式」和舊問題的補丁集中寫進 system prompt、AGENTS.md 或 CLAUDE.md。這些規則曾是提高穩定性的實用方法，但累積後會讓真正重要的專案知識、任務目標與驗收條件被埋在細節裡，也提高每次模型升級後重新校正的成本。
現在需要調整的原因，是把能力較強的模型放進更好的工作環境：initial Markdown 提供一份短而清楚的工作地圖，版本化文件提供可追溯的 source of truth，測試與檢查則提供成果證據。這種設計讓模型保有判斷與執行空間，同時讓專案的安全、品質與可維護性有明確依據。
1. 用短入口檔建立共同工作語言
讓 AGENTS.md、CLAUDE.md 或其他 initial Markdown 承擔四件事：說明專案目標、標出任務邊界、列出常用指令，以及指向重要文件。入口檔維持精煉，agent 才能在每次工作時抓住真正重要的訊號。
OpenAI 的實務做法是將短版 AGENTS.md 當作知識地圖，而不是百科全書；它連到架構、產品規格、執行計畫與品質文件。這種 progressive disclosure 讓 agent 先理解方向，再依任務載入所需細節。
2. 將專案知識做成可查找的 source of truth
把架構、資料模型、API contract、runbook、既有決策與產品規格放在 repo 內、可版本控制且可搜尋的文件。initial Markdown 只需告訴 agent：哪一種問題該讀哪一份資料，以及資料的權威來源在哪裡。
高品質 context 的目標不是「越少越好」，而是「用最少的高訊號資訊，完整描述預期行為」。因此，關鍵限制應保留在入口檔；細節則放在 agent 可即時找到的文件，而不是藏在聊天紀錄或人的記憶中。
3. 把完成標準寫成可驗證的證據
模型能規劃與執行，但專案對「完成」的定義需要明確提供。將驗收轉成可觀察、可重跑的證據：
- 單元測試、整合測試、E2E 與視覺比對
- lint、型別檢查、schema／API contract 驗證
- migration dry-run、release checklist 與 smoke test
- 實際執行的命令、結果，以及未驗證項目的風險說明
這些品質機制比 prompt 措辭更能跨模型沿用。OpenAI 以文件的連結、更新狀態與結構化程度建立機械檢查；Anthropic 的長任務實驗則以 feature list、進度檔、Git 與端到端測試，讓每一個 session 都能接續並驗證前一段工作。
4. 為自主工作提供清楚授權與安全界線
長時間任務要順暢，agent 需要知道哪些事已獲授權、哪些事需要等待確認。把授權寫成具體的工作契約：
| 類別 | 建議授權方式 |
|---|---|
| 任務範圍內、可復原的本機變更 | 直接執行，完成後附上 diff 與驗證結果。 |
| 發現的旁支問題 | 記錄在總結或 backlog，保留給後續獨立處理。 |
| 刪除資料、部署、改權限、對外發送、金錢操作 | 明列需取得確認的門檻與負責人。 |
| 多 session 工作 | 每次留下進度、決策、下一步、已驗證與待驗證項目。 |
這讓 agent 在低風險工作保持節奏，同時在高影響操作前留下足夠的人工控制點。
5. 以任務評測決定規則與 Effort
Effort、模型版本、工具可用性與任務類型都會影響成果。最可靠的做法是建立一組 5–10 個真實且代表性的任務，為每個任務記錄：
- 成功率與驗收結果
- 耗時與 token／費用
- 越界修改、回歸與人工介入次數
- 使用的模型、Effort、工具與 initial Markdown 版本
先保存現況作為 baseline；每次調整一組規則後，重跑相同任務。保留能穩定改善失敗模式的規則，並把可重用的專案知識移到 source of truth。安全、法規與資料保護要求則作為穩定的必要條件持續維護。
一份可直接採用的最小初始檔
# Agent working agreement
## Goal and scope
- 本次任務的功能範圍、允許修改的模組，以及不在範圍內的事項。
## Non-negotiables
- 對外發送、部署、刪除資料、改權限與金錢操作，依既定核准流程處理。
- 使用既有 migration、logging、error-handling 與測試慣例。
## Find the source of truth
- 架構：docs/architecture/index.md
- 資料契約：docs/contracts/
- 執行與驗收：docs/runbooks/verification.md
- 進行中的計畫：docs/exec-plans/active/
## Definition of done
- 完成需求範圍內的變更，並將旁支問題列入後續事項。
- 跑與變更相符的檢查，回報實際命令與結果。
- 清楚列出未驗證項目、原因與風險。
讓 agent 協助重作 initial Markdown
將 agent 納入 initial Markdown 的重作流程，能以目前的 repository、工具與評測結果產出更貼近專案的候選稿。Anthropic 公開提到會用 prompt improver 調整 CLAUDE.md；OpenAI 也以週期性的「doc-gardening」agent 掃描過時文件並提出修正。交付物採用可 review 的候選稿：保留團隊規範，將可發現的專案知識移到文件索引，把品質要求連到可執行檢查。
可直接交給 agent 的 prompt：
請審閱此 repository 的 AGENTS.md／CLAUDE.md 與相關文件，為新一代 coding agent
產生一份 initial Markdown 候選稿。
目標：讓入口檔成為短而高訊號的工作地圖；它必須保留專案事實、不可跨越的安全與
權限界線、常用指令、source-of-truth 索引，以及可驗證的 Definition of Done。
請依序完成：
1. 只讀分析目前 instructions、目錄結構、CI、測試、文件與近期變更。
2. 將每一條現有內容分類為：保留、合併、移至文件、轉為機械檢查、或淘汰；說明理由。
3. 將安全、法規、權限、對外操作與團隊既定規範列為不可自動刪除項目。
4. 產生 `AGENTS.proposed.md`，不要覆寫原檔，也不要修改程式或設定。
5. 提供與原檔的摘要 diff、需人工確認的決策，以及 5–10 個代表性任務的評測計畫。
完成條件：候選稿能指出各種任務的權威資料位置，定義相符的驗收方式，並將可機械化
的規則連到測試、lint、CI 或腳本。
審閱候選稿時，優先確認三件事：專案或組織要求是否完整保留、每個文件連結是否可到達、以及代表性任務的結果是否優於原版。通過後再以 commit 或 pull request 合併；後續可根據真實失敗與 review feedback 繼續迭代。
持續演進的工作方式
- 以真實任務測試目前的 initial Markdown。
- 透過 ablation（移除／還原）找出真正影響品質的規則。
- 將穩定的專案知識版本化，並從入口檔提供清楚索引。
- 將重複出現的品質問題轉為測試、lint、checklist 或工具契約。
- 在模型、工具或權限機制改版後，重新跑代表性評測。
初始 Markdown 最終是一份讓 agent 能可靠工作的起點：它提供方向、邊界、知識入口與驗收標準；專案則以版本化文件與可執行檢查，持續累積可被下一代模型繼承的能力。
參考資料
- 影片：Fable 5.1 怎麼 prompt？5 件今天就該改的事
- OpenAI：Harness engineering: leveraging Codex in an agent-first world
- OpenAI：How OpenAI uses Codex
- Anthropic：Effective context engineering for AI agents
- Anthropic：Effective harnesses for long-running agents
- Anthropic：Claude Code Best Practices（
/init、CLAUDE.md與 prompt improver）
