ADR

上一篇將 harness engineering 的信任鏈拆成四個環節：Contract（合約）、Evidence（證據）、Attestation（獨立確認）、Authority（授權）。本文接著談第一環：如何把「要做什麼」說清楚、固定下來，讓後面的驗收真的有東西可以對照。 前言 使用 coding agent 時，最容易被低估的問題，往往是它會不會在過程中重新解讀需求，而不只是它會不會寫 code。 需求已經約定好，範圍也說得清清楚楚。agent 開始動工，過程中一路調整、一路「幫忙想得更周到」。等到交出成果，diff 裡的每一段單獨看都很合理 —— 但整體加起來，卻不太是原本要的東西。 範圍悄悄長大了一點、某個原本說好「不做」的地方被順手做了，甚至有些約定在過程中被重新解讀。最後很難指出到底是哪一個時間點出了問題，只知道成果和一開始談的內容已經有一段距離。 這類問題很容易被歸咎於「模型不聽話」。但回頭看流程，問題往往更基本：當初講好的內容，從頭到尾就沒有被固定下來。 需求散落在 issue、聊天記錄、口頭討論裡，而這些內容都可以被重新詮釋。既然「完成的定義」可以事後被改寫，後面的驗收就很難有明確依據 —— 最後甚至可能在不知不覺中接受「這樣好像也算做完了」的結果。 所以信任鏈的第一環，不是驗收，而是合約。 本文不從某個 CLI 指令開始，而是從一套可以放進不同工具與流程的軟體工程方法談起：先宣告邊界，再建立後續可以對照的版本基準。 整篇文章想回答一個問題：如果規格今天被修改，是否能清楚指出哪一個版本曾經被同意、內容是否被動過，以及這次修改是否需要重新驗收？ 為什麼自然語言的規格還不夠？ 自然語言仍然是規格的重要載體。問題在於，不能單獨依靠一份可以自由修改、缺乏版本與識別碼的 prose 作為治理基準。 同一句話，不同人讀、不同時間讀，甚至同一個 agent 在不同 context 下讀，都可能得到不一樣的理解。當執行者可以高速產出，原本看似不大的模糊，就可能被放大成真正的範圍偏移。 治理需要做的，是在自然語言之外補上明確的需求 ID、non-goals、acceptance criteria、版本化快照與合約指紋，讓後續可以比對、重算，也看得出版本是否被改過。 為了方便後續討論，本文把這兩個方法論動作稱為 DECLARE（宣告） 與 BIND（綁定）。它們並非 Harness Engineering、SDD 或業界既有標準中的固定指令；本文用這兩個名稱分開描述「討論需求」和「建立版本基準」。 動作一：DECLARE —— 先把邊界說清楚 DECLARE 可以理解成把「要做什麼、不做什麼」整理清楚的階段。這裡通常會留下幾類內容： Spec（規格文件）：描述這個功能要達成什麼、怎麼驗收，以及什麼情況才算完成。 ADR（Architecture Decision Record，架構決策紀錄）：採用這個方案的理由、放棄了哪些選項，以及這個決定帶來哪些約束。 non-goals（非目標）：這次明確不處理的事情，例如不改既有 API、不處理權限、不做效能最佳化。 「不做什麼」，跟「做什麼」一樣重要。 大多數規格只寫要完成的事情，結果 agent（跟人一樣）會在灰色地帶自由發揮。把 non-goals 和 acceptance criteria 一起寫清楚，才能同時畫出「不做什麼」的邊界，以及可以逐條確認的完成條件。 Agent 可以協助整理規格、找出矛盾或提出修改方案，但不應在未經授權的情況下自行擴大工作範圍，也不能自行把修改後的規格視為新的治理基準。DECLARE 的終點，是由有權限的人確認這份內容可以拿來當作這次工作的合約。 從散文規格到可追蹤需求 在採用 SDD（Spec-Driven Development，規格驅動開發）的工作流裡，規格、計畫與任務文件是主要的產物。已確認的需求可以使用固定識別碼標示，例如：...