Astra之後，AGENTS.md與Skill該怎麼改

你只是要改一個按鈕的文字，AI卻先讀完整份架構文件、檢查資料庫規範、跑了一輪大範圍測試，最後還問你「是否要繼續修改？」

這時候問題未必在模型。更可能是你前一年為了馴服上一代模型而寫下的規則，正在把一件小事變成大型專案。

OpenAI在2026-09-11發表的Rethinking skills and prompts for GPT-6 Astra（於新分頁開啟）（擷取2026-09-13）就是在講這件事：模型每換一代，那些累積下來的指令都值得重看一次，而Astra這一代特別值得。

這篇把那份建議逐條對回官方文件，並且把「提示詞能解決」和「提示詞解決不了」分開。

先講清楚這份建議的邊界#

原文是一篇實務建議，不是實驗報告。它沒有給出「刪掉多少規則、成功率提高多少」的對照數據，所以合理的用法是把它當成值得在你的專案上驗證的方向，而不是可以照搬的定律。

它真正提出的判準只有一個：這條指令補上了什麼模型自己拿不到的東西？

兩種都叫「規則」的東西，價值差很遠。

修改之前，請仔細思考、全面分析，確保沒有任何問題。

這句沒有說什麼叫全面、哪些問題重要、怎麼算通過，模型讀完不會比讀之前更知道要做什麼。

這個服務仍有舊版行動裝置客戶端在用，不可直接移除既有回應欄位。

這是專案事實。模型再聰明也猜不到你公司還有多少舊版客戶端在線上。

整理指令時可以分成三類：專案特有的事實（業務限制、資料定義、相容性要求）要留下並維護；可驗收的品質標準（必須維持的行為、必要檢查）要寫清楚；替模型安排思考與操作順序的固定套路才是優先重審的對象。整理完文件可能變短，也可能只是結構變好——字數不是目標。

分工：三個插槽的載入時機不一樣#

這不是風格問題，是機制問題。三種指令進入模型context的方式完全不同，官方文件都寫得很明確。

AGENTS.md文件（於新分頁開啟）（擷取2026-09-13）說明，Codex啟動時會建一條指引鏈：先讀Codex home目錄的全域檔，再從專案根目錄一路走到你的工作目錄，每層最多取一個檔案，由根往下串接，越靠近工作目錄的越後面、也就越優先。合併後超過project_doc_max_bytes（預設32 KiB）就會停止加入。

Skill則是漸進式揭露。Build skills（於新分頁開啟）（擷取2026-09-13）寫得很具體：初始清單只放每個skill的名稱、描述與檔案路徑，選用後才讀完整的SKILL.md；而那份初始清單最多只能用掉模型context window的2%，context window未知時是8,000個字元。裝太多skill時，Codex會先縮短描述，再不夠就直接省略部分skill並顯示警告。

這條數字是整件事的地基：你寫的skill描述不是想寫多長就多長，它在跟其他所有skill搶同一個2%。

一條指令影響的範圍，應該和它實際適用的範圍接近。這次修搜尋頁的特殊要求不必永久寫進根目錄的AGENTS.md；只有發版才需要的流程，也不該讓每次改錯字都讀一遍。

Skill：描述是用來被選中的，不是用來自我介紹#

原文點名了三個失效模式，第一個就是描述太長、互相矛盾、或過度強調自己該被使用，結果模型載入一堆對當前任務沒用的指令。OpenAI說他們最近也更新了$skill-creator的內建指引來擋這些問題。

官方給的對照是這樣：

不好：Create and validate Postgres schema migrations. Use when working with databases, queries, models, or persistence.
好　：Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout.

差別在於前者會讓模型只要碰到任何跟資料庫沾邊的事就想用它。

所以描述不要寫成廣告。這種寫法幾乎無法拿來決定「現在該不該用」：

提供最完整、最專業、最全面的API開發與最佳實務支援，適用於所有後端開發工作。

改成同時界定工作、觸發條件與不適用範圍：

---
name: api-compatibility-review
description: 審查公開API的相容性。修改路徑、請求欄位或回應格式時使用；純內部重構不適用。
---

因為初始清單可能被縮短，官方建議把關鍵用途與觸發詞放在描述最前面，這樣即使被截短，主機端仍有機會正確比對。

第二個失效模式是沒有做漸進式揭露。原文的說法是：讀一個skill會吃掉context、把你推近compaction，還會引入跟當前任務無關的指引。所以有多條流程的skill，根文件應該是一份最小的路由表，指向各自的參考文件與腳本。

但也不要拆到難用。每一小段都藏在不同檔案，模型得一路追連結才知道基本要求，維護的人也看不到全貌。原則是：一起用到的放一起，只有特定情況才需要的才分出去。

第三個是把skill寫成鉅細靡遺的行程表。原文直說模型理解模糊與細微差異的能力已經好很多，過度具體的指引現在可能反而拖累結果。

AGENTS.md：不要拿它累積歷次不滿#

想像一份逐年長大的AGENTS.md：AI漏看過架構文件，就加「每次修改都先讀架構」；少跑過測試，就加「任何修改都跑完整測試」；擅自擴大過修改，就再加「所有動作都要先問」。

每一條都有合理的起點，放在一起卻不是合理的工作方式。

原文對這件事的用詞很直接：為了改一個錯字而要求先讀一疊文件或整份repo地圖是過頭的，Astra有能力自己判斷該讀什麼。官方給的改法是把「每次都讀」換成條件式的文件索引：

不好：Before every edit, read architecture.md, database.md, and deployment.md.
好　：Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.

判斷重點從此是任務與文件的關係，不是有沒有完成「讀過全部文件」這個儀式。順帶一提，原文也提醒：既然要指過去，那些文件本身就得維持更新。

測試那條同理。原文的說法是，以前的模型需要被催促才會跑測試與自我檢查，Astra會自己做，所以同一批指令現在會導致不必要的測試。

反過來，AGENTS.md也可以用來給出許可。原文明說Astra雖然徹底，但對於「要做到多遠」比較保守，有時需要推一把，並示範了一段可以直接借用的授權語句：

The local tests use disposable fixtures and have no production access. Run them, fix failures caused by the requested change, and rerun affected tests without asking for approval at each step.

注意這句話的前半段是環境事實。如果你的本機測試其實會打到真實服務，那這段話就不是授權，是謊報。

邊界措辭：Astra會把你的重話當真#

這是原文裡最容易被忽略的一節。如果你當初是為了阻止上一代模型自作主張而寫下強硬措辭，換到Astra之後要重看一次——原文的說法是，Astra可能把它看得太重，在你其實樂見它繼續的地方停下來。

同一節也提醒了另一面：Astra是他們最對齊的模型，在不確定安全的情況下不會動手，所以可以用相應的態度對待它。

持續性（persistence）那一節則指出，習慣了GPT-5.6 Sol一路做下去的人，會覺得Astra比較容易在第一版實作完成後回來要你審核。原文的建議是：在開始之前定義完成。如果任務包含「把實作跑起來、看結果、修掉壞的」，就把那些寫進需求；而且要注意，一句「第一版做完先停下來給我看」本身就會把模型拉向更早的停止點——值得確認那是不是你真的需要的一次決策。

完成的定義：官方已經給了三個欄位#

「幫我把搜尋功能做好」留了太多解讀空間：完成第一版算不算？要不要啟動頁面看？測試失敗要不要修？要不要部署？

Long-running work（於新分頁開啟）（擷取2026-09-13）直接給了寫法：一個能讓模型自己驗證進度的目標，包含三件事——Outcome（要的結果，不只是活動）、Constraints（必要工具、邊界、相容性需求、要避開的做法）、Verification（測試、量測或審查標準，用來證明工作完成）。官方的範例是這樣：

Migrate this codebase from JavaScript to TypeScript. Preserve existing behavior,
compile in strict mode without explicit `any` types, and make the full test suite pass.

把這個形狀套到一次修bug的任務上：

請修復搜尋頁切換分頁後，畫面仍顯示上一頁結果的問題。
 
範圍：
沿用現有的資料取得方式與公開API，不做無關重構。
 
完成標準：
確認問題成因、完成修正，補上能防止它再發生的驗證。
環境允許時啟動頁面，實際檢查切頁與重新搜尋的行為。
 
可自行執行：
在目前工作區修改必要程式碼，執行已確認隔離的本地驗證。
 
需要停下確認：
必須變更公開API、操作正式環境，或執行未授權的外部寫入時，
先整理成可審查的方案，不要直接執行。
 
交付：
說明修正內容、實際執行的驗證與結果。
有環境限制就列出未驗證的部分，不要把它寫成已通過。

這份提示詞沒有規定先搜哪個檔案、呼叫幾次工具、分析幾輪，它只描述可觀察的結果。兩個容易漏掉的設計：允許繼續的範圍與必須停下的條件是一起寫的，不必在「每件事都問」與「永遠不要問」之間二選一；完成不是無限改善，滿足需求並通過約定的驗證就可以交付，卡住時要說清楚卡在哪，而不是無限重試。

「一直做到完美」沒有可判定的終點，「完成哪些行為、通過哪些驗證」才有。

提示詞管不了權限，這件事不能混#

原文說Astra判斷力更好、可以據此調整措辭。這是對的，但要記得那是模型的判斷，跟系統的存取權限是兩個層次。

Permissions文件（於新分頁開啟）與Sandbox文件（於新分頁開啟）（皆擷取2026-09-13）把這件事分得很清楚：sandbox定義技術邊界——哪些檔案能改、能不能用網路；approval policy決定越過邊界時要不要停下來問。改變誰來審核不會擴大sandbox（例如Codex的Approve for me維持同一個工作區邊界，只是把跨界請求送去自動審核）。

所以自主工作應該這樣設計：在隔離的工作區裡，AI可以完成已授權的修改與驗證，也可以先把部署要用的東西準備好；真正碰到正式環境或外部寫入的那一步，由權限與審批機制擋。

不能只在提示詞寫「不要碰正式環境」，同時把不受限的正式憑證交給它，然後期待模型每次都做對。

改得好不好，看交付結果，不是看token變少#

整理完指令，輸入長度下降是最容易觀察的變化，但那不是成效。實際該看的是完成一次合格交付的總成本：模型與工具用量、等待時間、人工審查，以及後續返工。一份變短卻讓AI更常選錯skill、漏掉要求、需要你補三次話的指引，並不划算。

順帶澄清一個常見誤解：Prompt caching（於新分頁開啟）（擷取2026-09-13）重用的是前綴token的KV狀態，快取命中時那段輸入付較低的cached input費率（官方說最高折到一折），但模型仍然要處理新的輸入、仍然照著那份內容生成回應。它不會幫你消化掉指令本身的矛盾，也不能拿字數差直接換算成省下多少錢。而且重用要求整段前綴完全一致——前面的內容一改，後面的快取就接不上了。

真正的驗證方式官方也寫過。Testing Agent Skills Systematically with Evals（於新分頁開啟）（擷取2026-09-13）把skill的eval講成輕量的端對端測試：一個prompt、一次被記錄下來的執行、一小組檢查、一個可以跨時間比較的分數。它點名的回歸型態正好就是這篇在講的東西——skill沒被觸發、跳過必要步驟、留下多餘檔案。

其中最值得抄的一招是：測試集裡要放should_trigger=false的案例。那篇的例子是一個setup-demo-app的skill，「幫現有的app加上Tailwind」這種相鄰請求很容易誤觸發它的描述，於是模型去scaffold了一個新專案，而使用者要的只是改現有的。沒有反例，你只會測到「有沒有觸發」，測不到「有沒有亂觸發」。

實作時先固定模型、推理強度（reasoning effort）、工具、權限與程式碼起點，再比較原版與改版指引。案例不必多，但要涵蓋簡單修改、一般功能、跨模組問題、需求不完整，以及必須停下來等授權的工作。不要把「完全不詢問」當成成功——正確辨識出需要人類決策的地方，本來就是驗收的一部分。

原文最後也提到，換模型是清理門戶的好時機，但你不必全部手動重看——可以請Astra照著那篇文章的內容做一次稽核。

多模型的repository要小心#

原文有一句容易被跳過但很重要的提醒：repository裡的skill也會指導其他貢獻者的agent，而那些agent可能跑不同模型；對Sol或Luna有幫助的指引，可能會過度限制Astra。

所以如果同一份專案指引會被不同模型讀，業務要求、安全邊界與交付標準要維持一致，模型專屬的行為調整另外測。不要因為某個模型已經穩定做對某個步驟，就把所有模型共用的那條要求刪掉；也不要以為在Markdown裡寫個「Astra專用」標題，其他模型就會自動跳過——模型專屬的內容要不要載入，是由設定與執行流程決定的。

可以直接用的稽核提示詞#

不必一次重寫所有文件。比較穩的第一步是拿到一份有來源、能比較、可回復的修改建議：

請稽核此專案目前可見的AGENTS.md、Skills與共用任務提示詞。
這次只提出可審查的修改建議，不要直接修改檔案或權限設定。
 
先列出你實際讀取的指引來源與各自的適用範圍。
無法取得的全域、組織或工具端設定，標示為未檢查。
 
檢查重點：
過於寬泛的skill觸發描述。
不分任務大小都強制讀取的文件。
互相矛盾、重複或沒有明確用途的規則。
會讓工作過早停止，或讓範圍無限擴大的要求。
缺少可驗收的完成條件與明確授權邊界的地方。
 
每項建議請附上：
檔案位置、原文、目前用途、具體問題、建議改寫，
以及改完之後該用什麼任務驗證沒有退步。
 
請區分三類：
應保留的專案事實與必要限制；
可以改成條件式載入的內容；
需要實測才能決定要不要移除的模型行為指引。
 
不要只因為內容長就刪除。
不要自行降低安全限制、相容性要求或必要驗收標準。
環境事實無法確認時標示待確認，不要假設成立。
 
最後提出一個小範圍、可回復的第一批調整方案。

拿到建議後分批改：先動skill描述，測一輪；再處理文件載入與停止條件。一次改一類，才知道改善或退步是哪一步造成的。

一句話#

把累積下來的指令當成需要維護的工程資產，不是越積越有價值的經驗清單——專案事實留著、驗收標準寫清楚、權限邊界交給權限系統，其餘的每換一代模型就重看一次。