這一課會完成什麼
- 區分穩定指令、可由程式產生的 repository facts、任務狀態與暫時診斷
- 設計由根目錄到 package 的漸進式知識路徑，避免一份巨型說明檔
- 讓架構圖、route inventory、owner 與命令都能檢查 freshness
- 用 cold-start 任務衡量找檔、選命令、理解邊界與人工介入
開始前先準備
- • 模組 01 的 task contract 與案例表
- • 能讀 Release Desk source、package script、migration、測試與 Git history
先把定義說清楚
Repository 知識系統
Repository system of record 是跟程式一起版本控制、能由 agent 與工程師逐層讀取的工作真相。根目錄只放通用入口與安全邊界；鄰近 package 的說明交代局部責任與驗證；架構圖、route、schema、public export 等易變事實由程式產生並綁 source commit；當前 task state 則放在獨立 ledger。聊天摘要、個人筆記與過期 wiki 可以提供線索，但不能建立 verified。
Agent 在陌生 codebase 的第一個成本不是打字，而是建立正確心智模型。若架構知識分散在口頭、舊文件與 code review，session 會重複搜尋、誤判 owner、從相似但錯誤的 package 複製模式，最後用大範圍修改補救。
把知識搬進 repository 並不等於把所有內容塞進 AGENTS.md。長文件會吃掉 context，也容易互相衝突。較穩定的做法是建立入口、局部說明與可產生 facts，讓 agent 需要時才讀細節，並由 harness health 主動發現斷掉的連結與過期地圖。
現場情境
三份架構說明，各自指向不同 owner
文件內容、路徑、cold-start 時間與結果為課程 fixture。
- 負責人
- 你是負責讓 coding agent 進入 Release Desk repository 的 platform engineer。
- 要做的決策
- 哪一份知識應被刪除、連結、生成或下放到 package，才能建立一條可信入口？
- 目前狀態
- README 說 route 直接存取 database；舊 wiki 說所有 transition 都在 services；實際 source 已移到 domain package。新 session 在三處之間搜尋，最後修改已淘汰的 helper。
- 預期成果
- Repository 根目錄、domain package 與 generated map 形成一致路徑，fresh session 能獨立找到工作面與驗收命令。
限制條件
- • 不得把整個 source tree 複製進 prompt
- • Generated facts 必須帶 source commit 與 generator version
- • 局部說明不能放 production secret 或 fixture password 明文
實作範例
刪掉兩份說明，比再加一份有效
證據類型: 具名模擬情境團隊原本想新增第四份總覽。Inventory 顯示 README 與 wiki 都在重述易變的 package 結構，而且沒有 owner 或更新觸發。實際的 state machine type、route registry 與 migration manifest 已能產生必要 facts。
根層 AGENTS 只保留安全邊界、標準啟動、task state 位置與 architecture-map 命令。Domain package 新增局部 owner、invariant 與 focused checks。Script 從 source 產出 route、transition、generated file 與 test map，附 commit 和 hash。舊 wiki 改成指向 repository，重複 README 段落刪除。
Fresh session 在 fixture 中先讀根入口，再依地圖到 domain package，不再修改淘汰 helper。它能說出 reviewer authority、合法轉換與完整 eval 命令，沒有人工提示。這是單一合成測試結果，仍需持續看 map freshness 與介入次數。
主張限制
Generated map 只能呈現 generator 能讀到的結構，無法取代 domain rationale、例外決策與安全審查。Owner 仍要維護高層意圖。
做法
照著做，每一步都有檢查點
現場情境
哪一份知識應被刪除、連結、生成或下放到 package，才能建立一條可信入口？
- 01盤點資訊與 authority
- 02設計漸進式入口
- 03產生易變 facts
驗收條件
Repository 能自己交代工作入口、局部邊界與當前結構；易變內容會在 stale 時失敗，fresh session 也能找到正確實作與驗收路徑。
- 01
盤點資訊與 authority
把啟動、架構、狀態、資料、權限、測試、generated file 與 owner 分類；逐項標 authoritative source、更新頻率與消費者。刪掉沒有 owner、重複且已過期的內容，保留歷史理由則移到 decision record。
檢查點 · 每項必要知識只有一個 authority，其他位置以連結或 generated view 呈現。
- 02
設計漸進式入口
根層只放跨 repository 規則、初始化、狀態與導航。Domain package 放 transition invariant、owner、禁止依賴與 focused check。說明每一層何時讀，避免 session 一開始載入所有細節。
檢查點 · 一位未參與設計的工程師能從根入口找到 domain 工作面，沒有遇到互相衝突的指令。
- 03
產生易變 facts
從 source 建 route、transition、migration、generated file、public export 與 test inventory，輸出 source commit、generator version、產生時間與內容 hash。加入 stale、missing path 與 dirty source fixture。
檢查點 · Source 改變但 map 未更新會 fail；相同 commit 重跑產生穩定輸出。
- 04
執行 cold-start orientation
開全新 session，只給標準入口，要求它指出正確檔案、合法狀態、啟動與驗收路徑。記錄時間、讀取檔案、錯誤假設、人工提示與答案證據，再對照基準。
檢查點 · Session 不靠 transcript 或私人知識，能交出來源可查的 orientation receipt。
實務脈絡
展示版之後
先做 knowledge inventory
列出完成 request transition 所需的資訊：應用程式如何啟動、domain state 在哪裡定義、route 與 UI 誰負責、database migration 怎麼跑、fixture account 如何登入、audit effect 如何查、哪些檔案由 generator 管理、哪個命令建立 verified。每一筆標 owner、來源、穩定度、更新觸發與適合呈現位置。
穩定原則放根層，package 特有規則靠近 source，容易變的 inventory 用 script 生成，單次工作進度交給 ledger。不要複製完整 API 或 schema 到說明檔；應該連到 authoritative 定義，或輸出帶 commit 的精簡索引。
用 fresh session 測可讀性
Cold-start 測試只給 repository 路徑與標準入口，不提供舊 transcript。要求 session 找到 state transition、列出合法權限、啟動 fixture、指出驗收命令，先不寫程式。記錄第一次正確檔案的時間、錯誤搜尋、讀取量與人工提示。
答案要由 reviewer 對照 source 與 contract，不因 agent 自信就算正確。若地圖指到不存在路徑，視為 system-of-record failure；若說明與程式衝突，先修 authority 與生成流程，不能在 prompt 補一句暫時繞過。
交付補強
Repository map 的目的不是替 source 寫第二份百科，而是降低找到 authority 的步數。每個節點應顯示用途、owner、入口、禁止依賴、focused check 與最後生成 commit。若 agent 仍必須全文搜尋才能知道 transition 誰負責，就表示 map 只有路徑清單，沒有協助做工程決策。相反地，若 map 複製完整 type 與 API，source 改動後便會迅速失真。較好的索引是指向定義並附少量不可由語法推導的理由。
Cold-start 量測不只記找到第一個檔案的時間，也記錯誤假設如何被修正。Session 是否打開已淘汰 package、是否把 UI 當 domain owner、是否執行不相關的全套測試、是否需要人工說明 generated file。這些紀錄會告訴你該修導航、局部說明還是 tool catalog。若只看最後答案正確，就會漏掉高成本的繞路，下一個大型 task 仍會在同一處浪費 context。
知識 freshness 要有明確失敗模式。Generator 讀 current source，輸出 source commit、內容 hash、工具版本與產生時間；relevant paths 改動時，CI 驗 map 是否同步。若 generator 本身壞掉，狀態是 failed，不可沿用舊檔並標 current。歷史 decision record 可以保留舊架構理由，但頁首要標 replacedBy 或 supersededAt，避免搜尋結果把過期設計當現況。
動手實作
建立漸進式 repository knowledge map
盤點完成 request transition 所需知識，刪除衝突文件，新增根入口、domain 局部說明與 generated map，再由全新 session 做 orientation。
準備項目
- • 保留目前文件與 agent 走錯路徑的基準證據
- • 確認 generator 只讀 repository 並把輸出寫到明確受控路徑
本課產出
Knowledge inventory、root entry、package guide、generated architecture map、source commit 與 generator hash、dead-link check、cold-start receipt 與維護 owner 表。
起始模板: 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預期結果
Repository 能自己交代工作入口、局部邊界與當前結構；易變內容會在 stale 時失敗，fresh session 也能找到正確實作與驗收路徑。
留給下一課
Initializer、handoff 與所有工具都要連回這份 knowledge manifest。後續 entropy health 會持續驗 instruction link、generated map、owner 與 fixture 是否仍有效。
驗收條件
- 01必要知識都有 authority、owner、位置與更新觸發
- 02Generated map 綁 source commit、generator version 與 hash，stale fixture 會 fail
- 03根層與 package 說明沒有衝突、秘密或大段重複 source
- 04Cold-start session 能指出正確 owner、檔案、權限與驗收命令，人工介入如實記錄
常見故障
故障診間
F1AGENTS 變成數百行手冊，session 仍找不到局部規則。
- 先檢查
- 看內容重複、讀取順序、package 距離、易變 facts 與 context 用量。
- 可能原因
- 所有知識集中根層，沒有漸進式結構與權威連結。
- 修復方式
- 保留根入口，局部知識下放，易變 inventory 改由 generator 產生。
- 下次怎麼避免
- 設定 owner 與內容類型，定期檢查重複與 cold-start 路徑。
F2Architecture map 指向已刪除 route。
- 先檢查
- 核對 source commit、generator hash、path-change trigger 與最後成功 receipt。
- 可能原因
- 地圖以手工維護或生成失敗沒有變成 blocking status。
- 修復方式
- 從當前 commit 重建並修正 trigger，加入 stale regression fixture。
- 下次怎麼避免
- Relevant path 變更必須通過 map freshness gate。
F3說明檔放了 fixture password，後來流進 trace。
- 先檢查
- 掃 repository history、prompt、log、receipt 與 screenshot canary。
- 可能原因
- 把 secret 當成 orientation 資訊，而不是由安全 initializer 派生的環境資料。
- 修復方式
- 撤銷值、清理暴露面、改用 runtime identity 與 redacted receipt。
- 下次怎麼避免
- Secret scan 涵蓋 docs、generated map、log、artifact 與 Git diff。
展示版之後
正式上線前的邊界
- 01Repository knowledge 依穩定原則、局部規則、generated facts、task state 與歷史 decision 分層
- 02每個 authoritative artifact 有 owner、版本、更新觸發、freshness 與移除方法
- 03根入口簡短且能導向 package、state、initializer、rules、eval 與 runbook
- 04Generated map 從 source 建立並綁 commit、generator、hash 與失敗狀態
- 05文件與 artifact 不含秘密、真實敏感資料或不必要的 raw output
- 06Cold-start orientation 與 dead-link、stale-map、conflicting-instruction fixture 定期執行
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。
- [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 資源