入口

進階老師當架構師

跳到…
動畫版
列印

第 2 部・老師當架構師4 分鐘6 / 20

AGENTS.md 與 HANDOFF.md 長什麼樣子

AGENTS.md 與 HANDOFF.md 長什麼樣子:第 2 部動畫第 9 幕的畫面
在動畫版看這一段 ›第 2 部動畫・第 9 幕

兩份文件的寫法不一樣。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 寫最新狀態,每段工作結束都更新。
  • 交接檔裡的「完成」要附證據,也要寫出沒有測到的事。