Day 3 的焦點放在 AGENTS.md。

它解決的是一個很實際的問題：

不要讓每個新 Session，都重新教 Codex 一次這個 Repository 應該怎麼工作。

例如：

• 修改前先看 working tree
• 不要碰需求外的檔案
• 測試沒跑完不要說完成
• 不要擅自 deploy
• migration、production data、auth semantics 要提高處理層級

這些規則寫進 Repository 之後，確實改善很多。

但我很快又遇到另一個問題。

Codex 知道「該怎麼工作」了。

卻不一定知道：

這個專案現在到底做到哪裡？

AGENTS.md 記得「怎麼做」，但不應該記「現在做到哪」

假設一個功能會跨好幾天完成。

第一個 Session 已經完成：

root cause trace
↓
方案比較
↓
決定採用 B
↓
先完成 backend
↓
targeted tests PASS
↓
frontend 尚未開始

隔天換一個新的 Session。

如果新的 Session 只拿到 Repository 和 AGENTS.md，它知道：

• 修改前要先 preflight
• 要遵守 bounded scope
• 完成前要 verification

但它不知道：

• B 方案是不是已經核准
• backend 是否已完成
• 哪些測試已經跑過
• 還有哪些 open items
• 有沒有已知風險
• 下一步到底是什麼

這些都不是「工作規則」。

它們是：

Project State。

讓 Agent 自己從 Repository 猜，成本不低

最直覺的方式是：

反正 Code 都在 Repo 裡，你自己看。

小專案這樣做沒有問題。

但專案一大，Agent 很可能要重新：

git log
↓
git diff
↓
搜尋相關檔案
↓
讀測試
↓
讀 changelog
↓
找 TODO
↓
猜上一輪做到哪

問題不只是慢。

更麻煩的是：

Repository 通常很會保存結果，但不一定完整保存目前任務的上下文。

例如它看到某段 workaround 還存在，卻不一定知道那是：

1. 暫時 workaround
2. 刻意保留的 compatibility layer
3. 還沒完成的 migration
4. 前一輪忘記清掉的東西

光看 Code，不一定能分辨。

Git 很會記「發生什麼」，但不一定記得「現在要做什麼」

Git 可以告訴 Agent：

• 哪些檔案改過
• 哪次 commit 加了什麼
• branch 現在在哪
• 程式碼實際怎麼演進

但當 Agent 接手大型任務時，通常需要的是：

目前目標是什麼？
目前做到哪？
哪些東西已驗證？
還剩下什麼？
有哪些限制？
下一步是什麼？

如果這些資訊只散落在 commit message、issue、chat、terminal output 和未被正式記錄的判斷裡，

下一個 Session 就得重新拼圖。

所以後來多放了一層：

PROJECT_STATE.md

PROJECT_STATE.md 不是 README

README 通常回答：

這個專案是什麼？

例如：

功能
架構
如何安裝
如何啟動
怎麼貢獻

而 PROJECT_STATE 回答的是：

這個專案「現在」在哪裡？

例如：

# PROJECT STATE

## Current goal
完成新的身份登入流程，但不改既有 authorization semantics。

## Current state
- Worker auth route 已完成
- frontend bootstrap 尚未切換
- migration 不需要
- production 尚未 deploy

## Verified
- worker targeted tests: PASS
- auth regression: PASS

## Open items
- frontend integration
- production smoke test

## Constraints
- 不修改 remote D1
- 不改 Admin / ProxyAdmin 權限

## Next action
先完成 frontend integration，再跑完整 regression。

這種檔案不是用來介紹專案。

它是用來讓下一個 Agent：

少猜一點。

我後來把幾種 Context 刻意分開

做到這裡之後，原本混在一起的資訊也開始被拆開。

AGENTS.md
→ 在這個 Repo 裡「怎麼工作」

PROJECT_STATE.md
→ 專案「現在在哪」

DECISIONS.md
→ 為什麼「做了這個決定」

HANDOFF.md
→ 這一輪「做到哪，下一輪接什麼」

Tests
→ 哪些行為「必須持續成立」

Git
→ 程式碼「實際怎麼演進」

這些東西看起來都在保存 Context，

但用途完全不同。

如果全部塞進 AGENTS.md，

它很快就會變成一份又長、又舊、又難判斷優先級的超級 Prompt。

如果全部只靠聊天，

Session 一換、Context 一壓縮，資訊就可能消失。

Durable Context 不是 Bigger Context Window

很容易直覺認為：

Context window 越大越好。

因為看得到越多，好像就越不容易忘。

但長時間使用之後，會發現這是兩個不同問題。

大的 Context Window 解決的是：

這一輪能同時看多少東西。

PROJECT_STATE 這類 Durable Context 解決的是：

下一輪能不能快速知道什麼最重要。

因此，比較穩定的做法是：

不要每次都把所有歷史塞進去
↓
把重要狀態放到固定位置
↓
需要時再讀

重點不是讓 Agent 記得更多，

而是讓它知道：

現在該去哪裡找正確資訊。

PROJECT_STATE 最大的風險：它會過期

這類 Context 文件也不是寫了就沒事。

假設 Agent 修改了 Code，

但沒有更新 PROJECT_STATE。

下一個 Session 讀到的就是：

一份看起來很正式的錯誤資訊。

有時候這比沒有文件還危險。

所以 PROJECT_STATE 應被視為需要維護的 artifact。

它應該：

• 短
• 明確
• 只保留目前有效資訊
• 狀態改變後要更新
• 過期內容移走，不一路 append

如果它長成：

2026-08-01 做了什麼
2026-08-03 又做了什麼
2026-08-15 改了什麼
2026-09-01 又改了什麼
...

那它已經變成 CHANGELOG。

不是 PROJECT_STATE。

順帶一提，這個檔案也不一定非得叫 PROJECT_STATE.md。

重點不是檔名。

重點是：

有一份短、目前有效、跨 Session 可讀的 durable state artifact。

我現在希望新 Session 先讀這四樣

如果任務會跨 Session，新的 Agent 一進來最好先看到：

1. AGENTS.md
   → 工作規則

2. PROJECT_STATE.md
   → 現在狀態

3. Relevant spec / issue
   → 這次要做什麼

4. Git / tests
   → 驗證目前事實

而不是一開始就：

請重新掃完整個 Repository，告訴我你覺得現在發生什麼事。

這個差異看似只是多一份文件，

但對長任務來說，它直接影響：

• Context 使用量
• 重複探索
• Session 接續速度
• 決策漂移
• Agent 是否重做已經做過的事情

PROJECT_STATE 還是不夠

做到這裡，下一個問題又出現了。

即使我們知道：

「現在採用 B 方案。」

下一個 Agent 還是可能問：

為什麼不是 A？

如果理由沒有留下來，

它很可能重新分析一次，然後很認真地：

又提出 A。

這也是下一步需要 DECISIONS.md 的原因。

因為：

「現在在哪裡」和「為什麼走到這裡」，是兩種不同的 Context。

下一篇

如果 PROJECT_STATE.md 保存的是：

現在採用什麼。

那 DECISIONS.md 保存的就是：

為什麼這樣決定，以及哪些路已經走過、被否決。

要解決的不是讓 Agent 記得更多。

而是讓它：

不要每換一次 Session，就把同一個問題重新發明一次。