這一課會完成什麼
- 區分穩定指令、可由程式產生的程式庫事實、任務狀態與暫時診斷
- 設計由根目錄到套件的漸進式知識路徑，避免一份巨型說明檔
- 讓架構圖、路由資產清單、負責人與命令都能檢查時效
- 用全新環境啟動任務衡量找檔、選命令、理解邊界與人工介入
開始前先準備
- • 模組 01 的任務契約與案例表
- • 能讀取 Release Desk 的程式碼、套件腳本、資料遷移、測試與 Git 歷史
先把定義說清楚
程式庫與正式紀錄
程式庫中的正式紀錄，要和程式一起版本控制，讓工程師與 Agent 都能逐層讀取。根目錄提供通用入口與安全邊界，套件附近的說明交代局部責任和驗證方式。路由、schema、公開匯出等易變資訊由程式產生，並綁定來源提交版本；當前任務狀態另存工作台帳。聊天摘要、個人筆記與舊 wiki 能提供線索，完成事實仍要以對應版本的來源和驗證證據確認。
Agent 在陌生程式庫的第一個成本不是打字，而是建立正確心智模型。若架構知識分散在口頭、舊文件與程式碼審查，工作階段會重複搜尋、誤判負責人、從相似但錯誤的套件複製模式，最後用大範圍修改補救。
把知識搬進程式庫並不等於把所有內容塞進 AGENTS.md。長文件會吃掉脈絡，也容易互相衝突。較穩定的做法是建立入口、局部說明與可產生事實，讓 agent 需要時才讀細節，並由 harness 健康狀態主動發現斷掉的連結與過期地圖。
現場情境
三份架構說明，各自指向不同負責人
文件內容、路徑、全新環境啟動時間與結果為課程測試資料。
- 負責人
- 你是負責讓程式撰寫 agent 進入Release Desk 程式庫的平台工程師。
- 要做的決策
- 哪一份知識應被刪除、連結、生成或下放到套件，才能建立一條可信入口？
- 目前狀態
- README 說路由直接存取資料庫；舊 wiki 說所有狀態轉移都在 services；實際來源已移到領域套件。新工作階段在三處之間搜尋，最後修改已淘汰的輔助函式。
- 預期成果
- 程式庫根目錄、領域套件與自動產生的地圖形成一致路徑，全新工作階段能獨立找到工作面與驗收命令。
限制條件
- • 不得把整個來源目錄樹複製進提示詞
- • 自動產生的事實必須帶來源提交版本與產生器版本
- • 局部說明不能放正式環境機密或測試資料密碼明文
實作範例
刪掉兩份說明，比再加一份有效
證據類型: 具名模擬情境團隊原本想新增第四份總覽。資產清單顯示 README 與 wiki 都在重述易變的套件結構，而且沒有負責人或更新觸發。實際的狀態機型別、路由登錄清單與資料遷移清單已能產生必要事實。
根層 AGENTS 只保留安全邊界、標準啟動、任務狀態位置與 architecture-map 命令。領域套件新增局部負責人、必須成立的條件與聚焦的檢查。指令稿從來源產出路由、狀態轉移、自動產生的檔案與測試地圖，附提交版本和雜湊。舊 wiki 改成指向程式庫，重複 README 段落刪除。
全新工作階段在測試資料中先讀根入口，再依地圖到領域套件，不再修改淘汰輔助函式。它能說出審查者權限來源、合法轉換與完整評測命令，沒有人工提示。這是單一合成測試結果，仍需持續看地圖時效與介入次數。
主張限制
自動產生的地圖只能呈現產生器能讀到的結構，無法取代領域理由、例外決策與安全審查。負責人仍要維護高層意圖。
做法
照著做，每一步都有檢查點
現場情境
哪一份知識應被刪除、連結、生成或下放到套件，才能建立一條可信入口？
- 01盤點資訊與正式依據
- 02設計漸進式入口
- 03產生易變事實
驗收條件
程式庫能自己交代工作入口、局部邊界與當前結構；易變內容會在過期時失敗，全新工作階段也能找到正確實作與驗收路徑。
- 01
盤點資訊與正式依據
把啟動、架構、狀態、資料、權限、測試、自動產生的檔案與負責人分類；逐項標正式可信的來源、更新頻率與消費者。刪掉沒有負責人、重複且已過期的內容，保留歷史理由則移到決策紀錄。
檢查點 · 每項必要知識只有一份正式依據，其他位置以連結或自動產生的檢視呈現。
- 02
設計漸進式入口
根層只放跨程式庫規則、初始化、狀態與導航。領域套件放狀態轉移必須成立的條件、負責人、禁止依賴與聚焦的檢查。說明每一層何時讀，避免工作階段一開始載入所有細節。
檢查點 · 一位未參與設計的工程師能從根入口找到領域工作面，沒有遇到互相衝突的指令。
- 03
產生易變事實
從來源建路由、狀態轉移、資料遷移、自動產生的檔案、公開匯出與測試資產清單，輸出來源提交版本、產生器版本、產生時間與內容雜湊。加入過期、缺漏路徑與有未提交變更的來源測試資料。
檢查點 · 來源改變但地圖未更新會 fail；相同提交版本重跑產生穩定輸出。
- 04
讓全新工作階段理解程式庫
開全新工作階段，只給標準入口，要求它指出正確檔案、合法狀態、啟動與驗收路徑。記錄時間、讀取檔案、錯誤假設、人工提示與答案證據，再對照基準。
檢查點 · 全新工作階段不靠舊對話或私人知識，也能交出附來源的理解測試紀錄。
實務脈絡
展示版之後
先做知識資產清單
列出請求狀態轉移需要的資訊：啟動方式、領域狀態定義、路由及 UI 負責人、資料遷移、測試帳戶登入、稽核查詢、自動產生檔案，以及完整驗收指令。每項記負責人、來源、穩定程度、更新條件與存放位置。
穩定原則放根層，套件特有規則靠近來源，容易變的資產清單用指令稿生成，單次工作進度交給台帳。不要複製完整 API 或 schema 到說明檔；應該連到正式可信的定義，或輸出帶提交版本的精簡索引。
用全新工作階段測可讀性
全新環境啟動測試只給程式庫路徑與標準入口，不提供舊對話紀錄。要求工作階段找到狀態轉移、列出合法權限、啟動測試資料、指出驗收命令，先不寫程式。記錄第一次正確檔案的時間、錯誤搜尋、讀取量與人工提示。
由審查者對照來源和契約核對答案。地圖指到不存在的路徑，代表正式紀錄失效；說明與程式衝突時，先修原始定義或產生流程，再更新索引，不在提示詞中補一句暫時繞過。
交付補強
程式庫地圖讓人更快找到正式依據。每個節點列用途、負責人、入口、禁止依賴、相關檢查與產生時的提交版本。若仍須全文搜尋才知道誰負責狀態轉移，地圖就缺了決策資訊。完整複製型別與 API 又容易過期；索引應指向原定義，另附少量無法從語法推導的理由，減少維護兩份事實的負擔。
全新環境啟動量測不只記找到第一個檔案的時間，也記錯誤假設如何被修正。工作階段是否打開已淘汰套件、是否把 UI 當領域負責人、是否執行不相關的全套測試、是否需要人工說明自動產生的檔案。這些紀錄會告訴你該修導航、局部說明還是工具清單。若只看最後答案正確，就會漏掉高成本的繞路，下一個大型任務仍會在同一處浪費脈絡。
知識時效要有明確失敗模式。產生器讀目前來源，輸出來源提交版本、內容雜湊、工具版本與產生時間；相關路徑改動時，CI 驗地圖是否同步。若產生器本身壞掉，狀態是失敗的，不可沿用舊檔並標目前。歷史決策紀錄可以保留舊架構理由，但頁首要標 replacedBy 或 supersededAt，避免搜尋結果把過期設計當現況。
動手實作
建立漸進式程式庫知識地圖
盤點請求狀態轉移需要的知識，處理衝突文件，新增根目錄入口、領域套件說明與自動產生的地圖，再請全新工作階段驗證能否理解程式庫。
準備項目
- • 保留目前文件與 agent 走錯路徑的基準證據
- • 確認產生器只讀程式庫並把輸出寫到明確受控路徑
本課產出
知識清單、根目錄入口、套件指引、自動產生的架構地圖、來源提交版本與產生器雜湊、失效連結檢查、全新工作階段的理解測試紀錄，以及維護負責人表。
起始模板: Repository knowledge manifest
YAMLtopic,current_location,normative,owner,freshness,mechanical_source,target_location,action
startup,fixture/private-issue.md,yes,platform,stale,,AGENTS.md,move
review-state,docs/status-notes.md,yes,product,conflict,src/domain/review.ts,docs/product/review-state.md,reconcile
architecture,README.md,yes,engineering,unknown,,docs/architecture/index.md,extract
active-task,chat-fixture.txt,yes,task-owner,current,,docs/plans/active/request-changes.md,move可下載的實作檔
Knowledge ownership inventory
repository-knowledge.csv · CSV
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-02-receipt.json · JSON
A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.
驗收指令
npm run harness:knowledge -- --entry AGENTS.md --inventory repository-knowledge.csv預期 receipt
PASS he-02 repository-map
questions=5 answersFound=5 conflicts=0
entry=map normativeOwners=complete預期結果
程式庫能自己交代工作入口、局部邊界與當前結構；易變內容會在過期時失敗，全新工作階段也能找到正確實作與驗收路徑。
留給下一課
初始化程序、交接與所有工具都要連回這份知識清單。後續維護複雜度健康狀態會持續驗指令連結、自動產生的地圖、負責人與測試資料是否仍有效。
驗收條件
- 01必要知識都有正式依據、負責人、存放位置與更新條件
- 02自動產生的地圖綁來源提交版本、產生器版本與雜湊，過期測試資料會 fail
- 03根層與套件說明沒有衝突、秘密或大段重複來源
- 04全新環境啟動工作階段能指出正確負責人、檔案、權限與驗收命令，人工介入如實記錄
常見故障
故障診間
F1AGENTS 變成數百行手冊，工作階段仍找不到局部規則。
- 先檢查
- 看內容重複、讀取順序、套件距離、易變事實與脈絡用量。
- 可能原因
- 所有知識集中根層，沒有漸進式結構與權威連結。
- 修復方式
- 保留根入口，局部知識下放，易變資產清單改由產生器產生。
- 下次怎麼避免
- 設定負責人與內容類型，定期檢查重複與全新環境啟動路徑。
F2架構地圖指向已刪除路由。
- 先檢查
- 核對來源提交版本、產生器雜湊、path-change 觸發條件與最後成功驗收憑證。
- 可能原因
- 地圖以手工維護或生成失敗沒有變成阻擋執行的狀態。
- 修復方式
- 從目前提交版本重建地圖、修正更新條件，並把過期地圖加入回歸測試。
- 下次怎麼避免
- 相關路徑變更必須通過地圖時效驗收門檻。
F3說明檔放了測試資料密碼，後來流進執行軌跡。
- 先檢查
- 掃程式庫歷史紀錄、提示詞、紀錄、驗收憑證與截圖 canary。
- 可能原因
- 把機密當成新工作階段的導覽資料，沒有透過安全的初始化程序提供必要身分。
- 修復方式
- 撤銷值、清理暴露面、改用執行環境身分與已遮蔽敏感資訊的驗收憑證。
- 下次怎麼避免
- 機密 scan 涵蓋說明文件、自動產生的地圖、紀錄、交付檔案與 Git 差異。
展示版之後
正式上線前的邊界
- 01程式庫知識依穩定原則、局部規則、自動產生的事實、任務狀態與歷史決策分層
- 02每個正式可信的交付檔案有負責人、版本、更新觸發、時效與移除方法
- 03根入口簡短且能導向套件、狀態、初始化程序、規則、評測與操作手冊
- 04自動產生的地圖從來源建立並綁提交版本、產生器、雜湊與失敗狀態
- 05文件與交付檔案不含秘密、真實敏感資料或不必要的原始輸出
- 06全新環境啟動理解程式庫與失效連結、stale-map、conflicting-instruction 測試資料定期執行
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。
- [1]Harness engineering：在 agent-first 開發環境中運用 Codex知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
OpenAI · 公開案例 · 2026-08-26
- [2]Harness Engineering 學習指南repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理
deusyu · 公開案例 · 2026-08-26
- [3]長時間執行 agent 的有效 harnessinitializer 模式 · feature ledger · session 交接 · 端到端驗證
Anthropic · 已發表研究 · 2026-08-26
- [4]Learn Harness Engineering專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
Walking Labs · 公開案例 · 2026-08-26
- [5]Andrej Karpathy 的 AI Engineering PlaybookSoftware 3.0 觀點 · spec、diff、eval 實作 · 平行 session · repository 指令
AI Builder Club · 公開案例 · 2026-08-26
延伸的 Tenten 資源