跳至主要內容

coding agent mechanical enforcement architecture security

實作

把重要邊界交給程式檢查

將反覆出現的架構、權限、機密、自動產生的檔案與修改範圍要求,改成快速、穩定且附修復路徑的可執行檢查。

難度
進階
預估時間
130 分鐘
更新日期
2026-10-02
文案複核
speak-human-tw
兩輪
本課內容
  1. 01先把定義說清楚
  2. 02現場情境
  3. 03實作範例
  4. 04照著做,每一步都有檢查點
  5. 05實務脈絡
  6. 06動手實作
  7. 07故障診間
  8. 08正式上線前的邊界
  9. 09資料來源與主張限制

這一課會完成什麼

  • 將程式庫要求分成說明文字指引、自動產生的事實與可機械檢查必須成立的條件
  • 實作匯入方向、自動產生的檔案、受保護的路徑、機密與差異預算規則
  • 讓本機、CI 與發布驗收使用相同規則 ID 與結果
  • 用負責人、原因、範圍、到期時間與問題管理暫時例外

開始前先準備

  • • 模組 01 到 05 的地圖、契約、環境、台帳與有型別的回饋
  • • 一份通過的Release Desk 基準版本,可新增 lint、依賴與 diff-policy 檢查

先把定義說清楚

程式強制的安全邊界

由程式強制執行的規則,適合守住能可靠檢查的條件。同樣輸入應得到同樣判定;失敗時要指出規則識別碼、受影響的邊界與安全修正方式,例外則走正式且會到期的流程。文字說明保留意圖與需要人工判斷的內容,產生的地圖呈現目前程式事實。先挑一再造成風險或審查重工的少數條件來自動檢查,再衡量誤判與維護負擔,避免每段說明都變成一條規則。

『Domain logic 不要放 route handler』可以提醒人和 agent,卻擋不住不合法依賴。自治修改量增加後,審查者會反覆抓相同匯入、手改自動產生的客戶端、機密進紀錄、功能外 schema 變更。快速規則能把回饋移到檔案剛改動時,agent 也拿得到具體修復目標。

規則太多也會傷害 harness。Brittle 檢查器擋合法修改,例外永久留著,執行前檢查太慢便鼓勵繞過。每一條規則都要能說明保護什麼、訊號是否可靠、誰維護、如何修、何時刪,不能把規則數量當成熟度。

現場情境

一個快速功能穿過三條看不見的邊界

依賴圖、機密 canary、受保護的檔案與例外都是合成測試資料。

負責人
你是準備放長無人看守的執行的技術主管。
要做的決策
哪些邊界適合快速規則,資料遷移如何通過又不留下永久繞過?
目前狀態
候選版本從 UI 路由匯入資料庫、手改自動產生的客戶端,並把測試資料 token 寫進截圖紀錄。功能可操作,三個問題都由審查者手動發現。
預期成果
規則資料包抓到全部預先設計的違規,回穩定修復代號,只接受一份限定範圍的例外,本機與 CI 驗收憑證一致。

限制條件

  • • 規則不得使用正式環境憑證、網路或模型評判者
  • • 課程本機執行前檢查目標低於十二秒
  • • 合法資料遷移只可拿一份七天且限定單一路徑的例外

實作範例

三條規則取代三次重複審查

證據類型: 具名模擬情境

歷史測試資料差異一直出現 route-to-database 匯入、自動產生的 API 檔案手改與 canary 進測試交付檔案。三項都有說明文字,但每次仍要審查者重查。

Harness 增加 DEP-001 檢查套件方向、GEN-002 檢查自動產生的來源紀錄、SEC-004 掃差異、紀錄、驗收憑證與截圖。資料遷移例外只匹配一個清單路徑、一張問題、一位負責人與七天期限。

預先設計的不良修補差異在本機快速回三個程式碼,修正後通過。CI 使用相同規則版本與測試資料,結果一致。例外到期時自動失敗,直到恢復生成工作流程並移除紀錄。

主張限制

Static 與測試資料檢查無法證明整體架構安全或適切;執行環境授權、端到端評測、威脅審查與發布負責人仍不可省略。

做法

照著做,每一步都有檢查點

Release Desk 規則驗證層次從指引、自動產生的地圖到本機由程式強制執行的檢查、CI 一致性、窄例外與發布驗收憑證。

現場情境

哪些邊界適合快速規則,資料遷移如何通過又不留下永久繞過?

  1. 01選出能用程式檢查的必要條件
  2. 02實作快速檢查與穩定程式碼
  3. 03加入窄例外

驗收條件

程式撰寫工作階段會立即收到五條重要邊界的具體回饋,無法放寬資料遷移例外,推送前後看到同一判定。

這張圖要幫你看懂什麼規則驗證層次能把說明文字、自動產生的事實、本機檢查、CI 驗收門檻與已指定責任的發布決策分層。
  1. 01

    選出能用程式檢查的必要條件

    每個候選版本寫不良狀態、確定性的輸入、預期輸出、誤判風險、負責人與修復。格式或產品判斷若訊號不可靠,就保留給指引與人工審查。

    檢查點 · 五條選定規則都有可靠訊號與負責人;未採用的項目也記下不適合自動檢查的理由。

  2. 02

    實作快速檢查與穩定程式碼

    建立依賴、自動產生的檔案、受保護路徑、機密及修改預算檢查器。從已確認的程式庫根目錄解析路徑,限制輸出並連結證據;失敗回規則 ID 與具體修復方法。

    檢查點 · 每個預先設計的違規只觸發預期規則;乾淨測試資料通過;檢查器不讀任務根目錄之外。

  3. 03

    加入窄例外

    建立資料遷移例外,驗規則 ID、精確路徑、負責人、問題、原因、createdAt 與到期時間。測缺漏欄位、路徑放寬、錯誤的規則與已到期日期。

    檢查點 · 合法資料遷移只在七天範圍內通過;其他自動產生的檔案與格式錯誤例外都被擋。

  4. 04

    證明本機與 CI 一致性

    同一份清單和測試資料分別跑本機檢查與 CI 模擬器,比對規則版本、提交版本、結果、環境及證據雜湊。環境差異造成不一致時修正檢查器,不把差異視為可接受結果。

    檢查點 · Pass、fail、例外測試資料在兩邊一致,本機資料包也維持時間目標。

實務脈絡

展示版之後

G1

建立規則驗證層次

從基準版本與程式碼審查證據開始。需要設計判斷的 expectation 留在指引並附正反例;套件責任歸屬、路由資產清單、schema 狀態與公開匯出交給產生器;只有審查者穩定拒絕、檢查器低歧義的狀態才升成規則。

每條規則記 ID、目的、負責人、範圍、嚴重程度、本機指令、CI 階段、修復提示與例外條件。本機和 CI 顯示相同 ID,使用同版檢查器。若判定不同,先查輸入及環境差異,避免本機通過後在推送時才發現問題。

G2

把例外當成會到期的工作

資料遷移偶爾需要暫時跨依賴或修改受保護的清單。例外要指明精確規則、精確路徑、負責人、原因、問題、createdAt 與 expiresAt。檢查器驗所有欄位,已到期或路徑放寬一律拒絕;一律通用的停用不在任務契約。

規則健康狀態也要量:違規、修復成功、誤判、例外存續時間、執行環境、CI 偏移與繞過嘗試。失去真實邊界的規則應刪除。少而可信的規則,比一長串人人忽略的紅字更有用。

G3

交付補強

差異預算同時檢查範圍與內容。契約先列允許根目錄、受保護檔案、自動產生範圍、資料遷移規則與交付要求,再檢查新增、刪除、改名、二進位檔、lockfile 和依賴變更。十個小檔案可能合理,一個 lockfile 大改也可能增加供應鏈風險。超出預算就回差異摘要並轉人工審查,不讓 Agent 拆成多次提交來繞過門檻。

機密規則要掃的不只有來源。測試資料 canary 可能進終止紀錄、JSON 驗收憑證、瀏覽器截圖中繼資料、執行軌跡、涵蓋程度輸出、修補差異說明與自動產生的說明文件。每個範圍都設保留的 fail 案例,並確認檢查器自己不把命中的完整值印到報告。真正事故還要有撤銷、輪替、歷史紀錄審查與通知流程;課程 canary 通過只能證明已列範圍沒有洩漏,不能宣稱整體沒有秘密風險。

架構規則需要跟責任歸屬地圖對齊。DEP-001 讀套件工作圖與公開匯出,而不是靠字串搜尋匯入路徑。允許依賴變更時先更新架構決策、負責人與保留的測試資料,再改規則清單。若 agent 直接編輯自動產生的工作圖,GEN-002 應先擋;正確流程是改正式可信的設定或來源,再執行產生器。這能維持規則、地圖與實際程式碼同一套真相。

例外審查要看使用紀錄。某條例外在七天內被三個無關任務匹配,即使尚未到期也可能範圍過寬;健康狀態報告應列已匹配的提交版本、路徑與 actors。負責人可選縮小、提早撤銷或正式修改必須成立的條件。期限到了不能自動續期,更不能因 CI 壓力改成警告;新例外必須重新說明原因與風險,並重跑受影響的關鍵測試資料。

保護路徑規則要區分禁止修改與需額外核准。測試資料的憑證設定、部署清單與資料刪除程序可以完全禁止 agent 觸碰;核心狀態機或資料遷移登錄清單可能允許修改,但必須有對應合約、負責人審查與完整回歸。檢查器回傳規則類型、需要的證據與申請位置,不建議 agent 移動檔案或改名來避開 glob。重新命名、symlink 與自動產生的輸出也要解析到實際目標,避免表面路徑不同便穿過保護。

規則失敗的修復文字本身要受測。若依賴方向錯誤,提示應指向公開服務或領域邊界,不要只說禁止匯入;自動產生的檔案被改,提示要指出正式可信的來源與生成指令;機密命中則只顯示檔案、類型與遮蔽片段,不能重印完整值。全新 agent 依提示修復後,除了原規則通過,也要跑相關功能,避免為了消掉紅字而刪除必要行為。

發布前抽查規則是否真的阻擋實際執行路徑。某些檢查只掃 Git 差異,卻漏掉執行環境產生的紀錄或截圖;另一些只在 CI 跑,agent 本機無法取得及時回饋。將必須成立的條件對到產生、提交、建置、執行與歸檔各階段,選最早且可靠的位置攔截,較晚階段再做整體防線。多層檢查可以共用規則 ID,但各自證明的表面要在驗收憑證寫清楚。

規則變更也要像功能變更一樣經過之前/之後測試資料。新增規則先在歷史乾淨變更上跑,估誤判與修復時間;放寬規則則重播曾被它擋下的違規修補差異,確認仍有其他控制或已由正式架構決策接受。負責人簽的是具體差異與殘餘風險,不是一個規則檔案已被修改的事實。若新規則讓本機執行前檢查超過團隊可接受時間,拆成快速阻擋執行的與較慢建議項目/CI 層,不能直接鼓勵跳過整包檢查。規則發佈後觀察一個週期,再決定保留、調整或撤回。

每次規則發佈都附一個最小壞修補差異與一個合法邊界修補差異。前者證明它真的攔住風險,後者防止維護者只測失敗路徑,卻讓正常工作全被誤傷。

動手實作

建立 Release Desk 的程式規則檢查包

實作依賴、自動產生的檔案、受保護路徑、機密偵測字串與修改範圍預算五條規則。埋入失敗案例,加入一份會到期的例外,再比較本機與 CI 結果。

準備項目

  • • 從實際審查發現選目標訊號與負責人,不為了湊數造規則
  • • 保存目前依賴圖、自動產生的清單、受保護路徑、canary 與執行環境基準版本

本課產出

有版本的規則清單、五個檢查器、通過與失敗案例、一份有期限的例外、修復說明,以及本機與 CI 的一致性憑證。

起始模板: Mechanical rule manifest

YAML
rules:
  - id: DEP-001
    owner: platform
    severity: blocking
    scope: ["src/app/**", "src/domain/**", "src/data/**"]
    check: "node scripts/check-dependencies.mjs"
    exceptionRequired: ["owner", "reason", "issue", "expiresAt", "paths"]

可下載的實作檔

Mechanical rule manifest

mechanical-rules.yml · YAML

An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.

Run receipt template

he-06-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:rules -- --manifest .harness/mechanical-rules.yml --parity

預期 receipt

PASS he-06 mechanical-enforcement
rules=5 seededViolationsCaught=5
localCiMismatches=0 invalidExceptionsAccepted=0

預期結果

程式撰寫工作階段會立即收到五條重要邊界的具體回饋,無法放寬資料遷移例外,推送前後看到同一判定。

留給下一課

規則包是驗證流程的第一層。檢查結果、誤判與例外存續時間也納入可觀測性、平行協作決策和總整專案 Harness Card。

驗收條件

  1. 01五個預先設計的違規皆回預期規則 ID、證據、負責人與修復
  2. 02乾淨測試資料通過且本機資料包低於課程執行環境目標
  3. 03例外驗證器拒絕缺負責人或議題、已到期、路徑放寬,以及套用錯誤規則的紀錄
  4. 04本機與 CI 結果、規則版本、提交版本與證據雜湊相符

常見故障

故障診間

F1Agent 經常加 ignore 註解才能做合法修改。
先檢查
檢查誤判測試資料、繞過、範圍、parser 假設與負責人回應。
可能原因
規則守的是廣泛 proxy,不是真正必須成立的條件,或沒有可維護例外。
修復方式
透過已指定責任的變更暫停該規則、縮小訊號、補合法測試資料,清除未授權繞過。
下次怎麼避免
逐規則追誤判與修復時間,規則變更必須有負責人和測試。
F2本機通過,CI 報不同依賴違規。
先檢查
比較套件、清單雜湊、工作中目錄、自動產生的狀態、執行環境與 ignored 檔案。
可能原因
兩邊用不同實作或程式庫根目錄解析方式。
修復方式
統一有版本的檢查器入口與明確根目錄,將不一致情況加入測試。
下次怎麼避免
兩份驗收憑證都發布規則版本與輸入雜湊。
F3暫時例外過了幾個月仍可使用。
先檢查
核對負責人、建立及到期時間、適用路徑、使用次數與關聯議題。
可能原因
例外只是註解或全域旗標,沒有會強制阻擋的到期檢查。
修復方式
使紀錄到期,恢復必須成立的條件或開已審查的規則變更。
下次怎麼避免
已到期紀錄自動 fail,harness 健康狀態顯示例外存續時間。

展示版之後

正式上線前的邊界

  1. 01每條規則有必須成立的條件、訊號、範圍、嚴重程度、負責人與修復路徑
  2. 02路徑與環境身分安全解析,不使用廣泛根目錄、空變數或無人負責的程序
  3. 03本機、CI、發布使用相同有版本紀錄的檢查器與驗收憑證
  4. 04例外需要精確規則/路徑、負責人、原因、問題、建立時間與強制執行的到期時間
  5. 05測試資料包含合法變更、預先設計的違規、格式錯誤例外、偏移與敏感資訊遮蔽
  6. 06規則健康狀態追執行環境、違規、誤判、修復、繞過與例外存續時間

證據類型

資料來源與主張限制

資料來源只支撐本課標示的主張,不代表換一個系統也會得到相同結果。

  1. [1]知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
  2. [2]
    Harness Engineering 學習指南

    deusyu · 公開案例 · 2026-08-26

    repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理
  3. [3]
    Learn Harness Engineering

    Walking Labs · 公開案例 · 2026-08-26

    專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
  4. [4]
    Harness Engineering Guide

    Nexu · 公開案例 · 2026-08-26

    執行環境邊界 · 工具系統 · sandbox · 復原模式
  5. [5]
    長時間執行 agent 的有效 harness

    Anthropic · 已發表研究 · 2026-08-26

    initializer 模式 · feature ledger · session 交接 · 端到端驗證

延伸的 Tenten 資源

當本機 harness 要接進真實程式庫

帶著驗收憑證、失敗案例,以及那條還拿不準的控制邊界來。

在團隊拉長 agent 自治時間前,Tenten 可以一起檢查程式庫可讀性、權限、評測器涵蓋、worktree 隔離、復原與上線證據。