hustyladislav/writing-for-agents

供代理使用的任何文檔的撰寫參考：技能、AGENTS.md / CLAUDE.md、透過指標連結的文件。包裝方式不同，但寫法本身並無二致：相同的槓桿讓每份文件都可預測，因為代理每次運行時遵循的是相同的流程，而非產出相同的輸出。

若你正在撰寫的是技能文件，請閱讀 SKILL-MECHANICS.md 以了解前端設定、調用選擇與路由器技能。

上下文指標

上下文指標 是存在於代理上下文中的一個參考，指名某個不在上下文中的材料，並編碼觸發讀取它的條件。技能的描述是一個指標；AGENTS.md 中指向某份文件的某一行也是相同的物件。指標的措辭，而非其目標，決定了代理何時以及多可靠地讀取該材料。一個措辭薄弱的指標背後若藏著不可或缺的目標，便會導致變異性錯誤（variance bug）：應先強化措辭，只有在強化失敗時才考慮將材料內聯。

指標有兩項工作：說明材料內容為何，以及列出應觸發讀取它的分支（branch 是該文件處理的不同案例，不同的運行會走不同的路徑）。始終載入的指標中的每個字在每次輪次都需要付出代價，因此其修剪標準比內文更嚴格：

• 前置主導詞：指標正是在此發揮觸發作用。
• 每個分支一個觸發點。 將同一分支的不同名稱視為同一分支書寫兩次；將其合併，僅保留真正不同的分支。
• 刪除內文已承載的相同資訊。

兩種載入負擔

你新增的每一份文件與每個指標都會消耗以下兩種預算之一：

• 上下文負載（Context load） 指的是始終載入的材料在代理視窗中佔用的成本：AGENTS.md 中的一行、一個技能描述，或任何每個輪次都存在於上下文中、無論是否被觸發都會消耗 token 與注意力的內容。
• 認知負載（Cognitive load） 指的是對人類而言的成本：有哪些文件存在、何時該調用哪一份。人類本身就是索引。這不是一個需要最小化的成本：它是人類能動性的代價；應將其花在人類判斷真正重要的地方，在判斷無關緊要處則移除它。

僅透過指標才能讀取的材料，以指標本身那行文字為代價，逃脫了上下文負載；完全沒有指標的材料則完全依賴認知負載。

資訊層級

一份文件由兩種內容類型構成：步驟（代理執行的有序動作）與參考（按需查閱的定義、規則、事實）。兩者可以自由混合：全部是步驟（食譜）、全部是參考（審查規則、本技能），或兩者兼有。核心決策在於每個片段應落在資訊層級的哪個位置——這是一個按代理對材料需求的即時性排序的階梯：

1. 內聯步驟 是第一層：代理依序執行的事項。
2. 內聯參考 是按需查閱的內容。通常可以是合法的扁平同級集合（例如某篇審查的所有規則都在同一級），這並非壞事或壞味道。
3. 揭露參考 被推到單獨的文件中，透過上下文指標觸發，僅在指標被觸發時才載入。範圍從同一資料夾的同級文件，到完全外部、任何文件都可指向的參考。

向下推送太少會使上層膨脹；推送太多則會將代理實際需要的材料隱藏起來。這個張力就是整個決策的核心。

漸進揭露（Progressive disclosure） 是指順著階梯向下移動（從主文件移到指標之後），讓上層保持可讀。這主要不是為了優化 token，而是為了保護層級結構。分支測試是判斷是否需要揭露的最乾淨方式：將每個分支都需要的內容內聯，將只有部分分支會用到的內容推到指標之後。當一份文件包含步驟時，本應揭露的內聯參考會將步驟掩埋，使得執行步驟變成擲硬幣般的隨機行為：這不僅是清晰度問題，更是變異性的槓桿。

關聯共置（Co-location） 是文件內部的配套原則：層級決定了內容應放在多深的位置，而關聯共置則決定了放在該位置後，哪些內容應彼此相鄰。應將一個概念的定義、規則與注意事項放在同一個標題下，而不是分散各處，這樣當代理讀取其中一部分時，鄰近的內容也會一併被讀到。檢驗標準是：文件讀起來應像專門為代理撰寫的文件。分組的內容讀起來就是這樣；分散的內容則不然。（這與重複不同：重複是將同一個意思放在兩個地方；分散則是將一個意義打碎成許多片段。）

過度蔓延（Sprawl） 是這裡的失敗模式：文件太長，即使每一行都是活的且獨一無二。注意力會隨著過多的內容而稀釋，每多一行就多一個需要維持相關性的負擔。解決方法是層級結構：將參考揭露到指標之後，並按分支或序列拆分，讓每條路徑只攜帶其真正需要的內容。

步驟與完成標準

每個步驟都以一個完成標準結束——告訴代理工作已完成的條件。兩個特性使其成為槓桿：

• 清晰度：代理是否能分辨已完成與未完成？模糊的邊界（如「達成理解」）會引發提前完成：在步驟真正完成前就結束，注意力飄向「已經完成」這件事。仍在視線中的後續步驟（完成後步驟）提供了拉力；標準的清晰度則是阻力。防禦順序如下：先強化邊界（局部且便宜）；只有在邊界確實無法清晰化且你觀察到倉促完成行為時，才通過分割序列來隱藏後續步驟。隱藏只在真實的上下文邊界（交接、子代理派遣；內聯呼叫會讓後續步驟留在上下文中，無法清除）時才有效。
• 嚴格度：標準要求多少。 「所有已修改的模型都已處理」迫使進行徹底工作，而「產生一份變更清單」則不然。嚴格度驅動了實質工作（代理在工作範圍內進行的挖掘工作，暗含在措辭中而非寫成獨立步驟），且它不限於步驟：「每個規則都已應用」約束了一組扁平參考，就如「每個步驟都已完成」約束了一個序列——這也是為何即使是純參考文件也帶有完整性檢查的標準。

最強的標準既是可檢查的，也是窮盡的。

何時分割

將一份文件分割成兩份會消耗兩種載入負擔中的一種，因此只有在分割確實值得時才進行：

• 按序列：分割一系列步驟，當後續步驟會誘使代理急著完成當前步驟時。將它們移出視線，能驅使代理在當前任務上投入更多實質工作。注意反向效果：合併序列會讓每個步驟的後續步驟暴露在下一個步驟面前，從而引發提前完成。
• 按調用（技能專用）：請參閱 SKILL-MECHANICS.md。

主導詞

主導詞 是一個已存在於模型預訓練中的緊湊概念，代理在執行文件時會用它來思考（例如：lesson、fog of war、tracer bullets）。以 token 的形式重複，而非句子，它會累積出分散式定義，並以最少 token 錨定整個行為區域，方法是招募模型已有的先驗知識。自行創造詞彙也可以，只要定義清晰即可，但自創詞招募不到先驗知識：你必須用定義 token 來支付預訓練詞彙免費提供的東西；因此應優先選用已有詞彙。

主導詞的錨定作用有兩層。在內文中，是執行：每當該詞出現，代理就會表現出相同行為；在扁平參考中，它會將注意力聚焦於一類需要尋找的事物。在指標中，是調用：當同一個詞同時存在於你的提示詞、文件和程式碼庫中時，代理會將這個共享語言連結到材料上，並更可靠地讀取它。

尋找使用主導詞進行重構的機會。一個在三處被詳細闡述的概念，一個用一句話暗示同一個想法的指標。每一個都是亟待收縮為單一 token 的段落：

• 「快速、確定性高、開銷低」→ tight（一個 tight 迴圈）
• 「你信心滿滿的迴圈」→ red，將模糊的門檻轉變為二元的可觀察狀態（若出現 bug，該迴圈變 red；否則不變）。

你獲得雙重好處：更少的 token，以及更銳利的鉤子供代理掛載其思考。假設每份文件都承載著多餘的複述，而這些複述都可以透過主導詞來淘汰。把它們找出來。

否定句 是這個槓桿旁邊的失敗模式：透過禁止來引導行為，會將被禁止的行為拖入上下文中，使其變得更可用，而非更少。「別去想大象」，然後腦中滿滿都是大象；否定詞只是一個弱修飾符，被強烈激活的概念會將其覆蓋，因此禁令讀起來半像是指令去執行該行為。應提示正面：陳述目標行為（例如：「撰寫一行註解」），這樣被禁止的行為就永遠不會被提及。只有在無法正面表述的硬性護欄時，禁令才有其立足之地；即便如此，也應同時搭配正面的目標，讓注意力落在該做什麼上。

修剪

• 將每個意義保持在單一事實來源中：一個權威位置，如此變更行為只需編輯一處。重複（同一個意義出現在多個地方）會增加維護成本與 token，並將意義在層級中的顯著性提升超出其實際等級。（這是主導詞的偶然反例：主導詞是故意重複 token，而非重複意義。）
• 環境也是一個事實來源（package.json 中的腳本、設定檔、目錄結構、--help 輸出），而重述環境的文件就是一個快取：查詢的副本，只有在查詢成本高昂時才有存在的價值。應快取代理無法透過查看找到的內容：未明寫的慣例、選擇背後的原因、設定檔不會坦白的陷阱。將只需查一個檔案、一個命令的訊息留給環境處理，它們在那裡不會過時。
• 檢查每一行的相關性：它是否仍與文件的用途有關？一行文字可能因從未與任務相關（單純的說明文，或應被揭露的分支）而失去相關性，也可能因其所描述的行為或世界已改變而過時。文件越短，越容易保持相關性。缺乏修剪紀律的預設命運是沉積（sediment）：陳舊的層層疊加，因為新增感覺安全、刪除感覺有風險，直到你必須向下挖掘才能找到仍然活著的內容。
• 逐句尋找無效指令（no-ops）：一句模型預設就會遵守的指令，付出了載入成本卻什麼也沒說。檢驗標準（與預設行為相比是否改變了行為）是模型相關的，而非讀者相關的：兩人對某條指令是否為 no-op 的意見分歧，是對預設行為的意見分歧，應透過執行文件來解決，而非透過辯論。當某一句無效時，應刪除整個句子，而非修剪其中的詞語。這個標準同樣適用於主導詞：一個太弱而無法勝過預設行為的詞（當代理已經挺徹底時說「要徹底」）就是一個 no-op，修正方法是使用更強的詞（例如 relentless），而非改用不同的技巧。