兩份文件的寫法不一樣。AGENTS.md 是「長期有效的規則」,寫一次,偶爾修訂;HANDOFF.md 是「最新的狀態」,每一段工作結束都要更新。下面兩份示範,改寫自 CM108G 課程工作資料夾的實際文件,篇幅縮短了。
AGENTS.md 示範(節錄改寫)
# 課程每週製作的專案規則 ## 來源優先順序 1. 老師最新的明確指示與本週教學目的。 2. 雲端硬碟的課程同步資料夾。 3. 上一週老師核准的逐字稿與課後檢討。 4. 本專案的 HANDOFF.md 與對應週次的教材。 5. 已發布的課程網站、長個案、短個案。 教材內容一律以網站已發布的版本為準,不用本機的舊資料夾。 ## 逐字稿閘門 老師校正逐字稿並標成「定稿」後,才放進核准逐字稿資料夾。 開始設計第 N 週之前,先檢查第 N−1 週有沒有還沒檢討的定稿逐字稿; 有,就先做課後檢討;沒有定稿,只回報缺少什麼,不產出可發布的教案。 ## 不可以做的事 沒有老師在本輪明確授權,不發布、不寄信、不改外部平台、不刪除檔案。
HANDOFF.md 示範(節錄改寫)
# 課程每週製作|交接 ## 目前狀態(2026-10-05) - 每週製作規格 v0.8 為正式版;第 2 到 5 週的教材動畫已發布。 - 第 6 週教材動畫有一份草稿,尚未審閱、尚未發布。 ## 這一段做了什麼 - 依老師 10/5 的 19 項決定,修改第 5 週表單與教學指引。 ## 還沒做完 / 需要老師決定 - 第 2 週成果的中文名稱,等老師確認。 - 第 6 週教材動畫須在 10/9 前審閱後發布。 ## 從哪裡接 - 要做動畫:只讀動畫製作規格書 v1.1。 - 要發布:照網站儲存庫的規則,發布後讀回公開網址。
示範裡有兩處都在講「以什麼為準」,管的是不同的事。來源優先順序,決定指示互相衝突時聽誰的;「教材內容一律以網站已發布的版本為準」這一句,決定拿教材去做動畫等衍生材料時讀哪一份。要修改教材,還是要改原稿,再重新產生網站並發布。
AGENTS.md 有一個好用的寫法:每一條規則,盡量寫成「Agent 遇到某種情況時要怎麼做」。以上面的逐字稿閘門為例:如果只寫一句「要重視逐字稿」,Agent 不知道該做什麼。示範裡分成兩種情況,各寫一個動作:有還沒檢討的定稿,就先做課後檢討;沒有定稿,就只回報缺少什麼。CM108G 的完整版還多寫了第三種情況:逐字稿的標示互相矛盾。規則寫成「情況與動作」,Agent 知道該做什麼,老師也查得出它有沒有照做。
HANDOFF.md 則要寫到「換一個人或換一個 Agent 也接得下去」。CM108G 的交接檔還有一個習慣:每一項「已完成」都附上證據,例如提交編號(Git 版本紀錄的編號)、檔案位置、檢查結果;「沒有測到的事」也寫出來,例如沒有在 iPhone 上實測。
本頁收穫
- AGENTS.md 寫長期規則,最好寫成「遇到什麼情況,怎麼做」;HANDOFF.md 寫最新狀態,每段工作結束都更新。
- 交接檔裡的「完成」要附證據,也要寫出沒有測到的事。
