Community程式設計與開發github.com

george-andrikopoulos/global

一套跨專案與語言的工程規約,涵蓋:保證需要讀者、判斷需經管道、驗證繼承的主張、文件時效性、衡量主張而非子集、不得無聲耗時、偏向透過建構實現、修復虛假成品、訊號需有後果、透過生產路徑驗證、偵測器排除自身定義、模糊寫入目標即提問、錨點超出受檢方範圍、委派扇出、比對已知狀態等。

global 是什麼?

這套全球工程規約(global rules)適用於所有專案與語言,由多條獨立但相互關聯的規則組成,旨在預防AI代理在執行工具操作時產生的常見問題,如副作用、安全性漏洞與資料損毀。它支援Claude Code、Cursor、Codex等AI代理平台,每個規則都提供明確的故障模式檢查與實作指引。例如:「模糊寫入目標即提問」要求在寫入共享狀態前明確命名受影響的物件;「偵測器排除自身定義」確保掃描工具不會匹配到自身文字;「比對已知狀態」則引導代理在除錯時從差異最小處著手。這套規約透過可操作的限制條件取代抽象原則,幫助開發者與代理理解何時該提問、何時該驗證,從而產出更可靠的成果。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/george-andrikopoulos/relearn/tree/HEAD/claude-pack/skills/global

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

全域規則

當請求未明確指定寫入的對象時,先提問再操作 [R:模糊寫入目標即提問]

摘自《Task Success Is Not Enough: Side-effect-Aware Evaluation of Tool-Using Language Model Agents》(SABench),NeurIPS 2026 海報論文,https://neurips.cc/virtual/2026/poster/138911 (arXiv:2610.34167,列於 cs.AI 2026-10-27) -- 摘要閱讀日期 2026-10-27。

在執行任何會改變工作複本以外狀態的動作前——例如發送、張貼、邀請、編輯共享記錄、刪除、關閉——請明確指出它將觸及的具體目標,並檢查請求中是否一一指名。如果沒有,請提問。不要藉由選擇最合理的解讀來自行消除歧義。

三種情況,本質相同:

  • 錯誤的對象。 兩個行事曆、兩個討論串、兩個工單都符合描述,卻選了其中一個。
  • 範圍擴大。 「回覆 Sam」變成全部回覆;「修正此活動的日期」變成編輯整個週期性系列。
  • 非預期的收件人。 轉寄、邀請或提及到達了請求從未指定的人。

達成目標並不代表問題解決。一個既發送了正確訊息又更新了另一條記錄的操作,在只評量完成度的檢查中看起來是完整的——這就是此類錯誤能躲過審查的原因:成功的證據同時也掩蓋了副作用。

成本不對稱,因此閾值也不對稱。提問耗費一個回合;而寫入錯誤對象往往不可逆,且會影響到未提出任何要求的人。若操作是唯讀的,或僅限於工作階段擁有的檔案(可由版本控制還原),則自行選擇解讀並說明即可。但若會影響他人或共享狀態,則不可為之。

操作前的故障模式檢查:此次寫入會觸及哪些對象,請求中又明確指名了哪些? 如果對其中任何一個的誠實答案是「它是可能性較高的一個」,那就是該提問的時候了。

相關但刻意分開的規則:[R:不得無聲耗時] 是代替使用者決定任務的價值;而此規則是代替他們決定任務的對象。

將檢查的信賴錨點置於受檢方無法觸及之處 [R:錨點超出受檢方範圍]

任何用以保護某事物免於某方侵害的檢查,都會將該方的輸入與一個錨點進行比對:例如公鑰、允許清單、權限、政策、雜湊鏈頭部。檢查的強度完全取決於錨點的位置。如果受檢方能夠寫入這個錨點,那麼這個檢查就等於是在用對手的資料來驗證對手——對他們而言,這個檢查就像對你一樣容易通過。

因此,在信任任何此類檢查之前,請問:誰可以寫入它比對的內容?受檢方是否在其中? 追蹤所有路徑的寫入權限,而不僅是 API 提供的那些。表面上沒有端點可操作的表格,任何能開啟檔案的行程仍可寫入;設定檔可由相同使用者執行的一切程序修改;外掛在自己命名空間中儲存的值,外掛可以自己更改。如果受檢方能透過任何路徑接觸到錨點,那麼無論密碼學或多比對邏輯多麼正確,這個保證都是無效的。

將錨點置於受檢方無法觸及之處:例如硬體(從裝置讀取的 TPM 持有金鑰)、獨立的信任域、已簽署或帶外來源,或是編譯在受檢方無法控制的二進位檔中。如果尚無這樣的位置,請在威脅模型中說明哪些方是這個檢查無法阻止的,而不是讓檢查暗示它能阻止它們。

關鍵跡象是保證以「X 不能做 Y,因為 Z 已被驗證」的形式陳述:在寫出這句話之前,先檢查 Z 的參考值存在於何處。不可偽造性的主張,本質上是對錶點寫入權限的主張;而當此寫入權限未被追蹤時,這個主張就是虛假的。

這是 [R:虛假成品] 的安全設計對應:後者捕捉的是接受任何事物都能產生的證據的檢查;前者則捕捉參考值能被檢查鎖定對象產生的檢查。與 [R:保證需要讀者] 和 [R:驗證繼承的主張] 同屬一系:都是缺乏追溯基礎的陳述性保證。

故障模式檢查:這個檢查所限制的一方,是否能透過任何路徑寫入該檢查比對的數值? 如果可以,或者你尚未追蹤確認,那麼這個檢查還不算是一項控制措施。

建立檔案前檢查是否有大小寫不同的同名檔案 [R:大小寫衝突]

同時由鉤子 no-case-collision 強制執行。

在建立任何檔案前,檢查是否存在僅因大小寫或 Unicode 正規化方式不同而異的同名檔案。當儲存庫在區分大小寫與不區分大小寫的檔案系統之間同步時,不區分大小寫的語意為強制約束:兩個這樣的名稱實際上是同一個檔案,後寫入者會覆蓋前者。

應合併到現有檔案中(加上段落標題),而不是建立衝突的名稱。直覺上想建立一個使用正確大小寫的新檔案是錯誤的——這個慣例不值得讓另一台機器上的檔案因靜默覆蓋而消失。

損害在執行作業的環境中是不可見的。在創作端的檔案系統上,兩個檔案都存在,一切看似正常;衝突只會在同步後顯現,內容無故消失,沒有差異記錄,也無錯誤可追溯。

本規則已升級:一個即時鉤子現在能確定性地阻止此衝突,因此指令層面無需再為該路徑處理。但它仍適用於鉤子未涵蓋的所有建立路徑——例如 shell 重導向、git 操作、其他工具——因此仍保留此指導,而非移除。

重複文件中關於世界的繼承主張前,先驗證之 [R:驗證繼承的主張]

自撰寫以來已發生 1 次;最近一次為 2026-10-26。

在重複文件中關於即時狀態的事實性主張前,請查詢該狀態。

文件可以告訴你兩種不同的事情,它們不應獲得同等信任。關於意圖的主張——為什麼門檻是 18、什麼被拒絕及其原因、哪個不變量是檔案存在的理由——僅以散文形式記錄,文件是權威來源。關於世界的主張——某感測器不存在、某服務已停用、計數為 23、某能力未被強制執行——描述的是可直接觀察的事物,文件只是沒有有效期的快取讀數。

未經觀察就重複第二種主張,會讓一個過時或從未真實的主張被洗白成一份新報告。這比原始錯誤更糟,因為主張現在附帶了今天的日期,以及剛被「檢查過」的權威性,而且報告是讀者會據以行動的內容。撰寫者當時可能是對的,可能是在猜測,也可能從別處複製而來;當你閱讀時,這些都已不可見,而一個被複製到四份文件中的主張,看起來像是得到四倍的佐證,實際上卻只基於一個未經驗證的斷言。

這是 [R:文件時效性] 的讀者端。該規則要求撰寫者將文件的更新與其描述的事物變更放在同一次更動中,但它有時會失效——因此讀者是最後一個還能捕捉錯誤的位置。它也是 [R:衡量主張而非子集] 的鏡像:後者在你即將覆寫一個記錄數值時保護你;前者則在你即將重複它時保護你。兩者共同確保記錄的數字不會在任一方向上未經審查就直接傳遞。

此檢查成本低廉且範圍有限。你並非重新推導整份文件,而是抽樣檢查你將以自己的名義提出的特定主張,且僅限於那些關於可觀察狀態的主張。

故障模式檢查:這是一個關於世界的主張嗎?我能夠觀察世界嗎? 如果兩者皆是,那麼文件只是一個假設,你的報告需要的是觀察結果,而非引用。如果你無法觀察它,請附帶其來源重複——例如「TODO.md 記錄 X,未經驗證」——而非直接斷言。

工作被列舉後,委派扇出 [R:委派扇出]

編譯器驅動的修復在你推斷問題根源時,確實是序列化的:每次修復都會改變下一個錯誤的位置。但當建置、閘道或計劃已經列舉出 N 個獨立的後續項目時,這個狀態就不再序列化了。從此時起,編輯之間不再相互依賴,逐一處理它們不會帶來任何額外收益。扇出的時機是在清單產生之後,而非之前。

同樣的模式也適用於:每次發布時更新的一組文件、針對同一合約閱讀多個檔案的審查,以及需要多個獨立來源的研究。

當委派被禁用時,請提出選擇——而不只是告知成本。 此規則經常被覆寫:工作階段的限制政策可能完全禁止委派,且該政策預設優先。但這並不會讓成本消失,而在你已經做出選擇後才發出的通知,只是資訊而非決策。在第一次真正的扇出時,用一句話說明分岔點——會委派什麼、大致取代多少序列往返次數、以及如何啟用——然後在未獲指示前繼續序列執行,且不再重複此提議。指向某個設定的開關不算數:要求別人去修改的全域切換是制度變革,而非針對此任務的選擇。

故障模式檢查:是否有人已經為我列出了這份工作? 如果建置、閘道或計劃產生了清單,那麼序列化執行是你用別人的預算做出的選擇。

相關但刻意不合併的規則。[R:不得無聲耗時] 是一般形式——所有關於使用者時間、金錢與周全性之間的權衡。此規則保留給委派這個具體案例,以便兩者攜帶各自的度量:兩個有明確範圍的規則可在審查中區分開來,並各自附帶證據;而一個範圍過廣、同時涵蓋兩種情況的規則則無法被否定。

偵測器排除自身定義 [R:偵測器排除自身定義]

部分由鉤子 no-self-matching-pkill 強制執行(在 Bash 或 PowerShell 指令字串中,針對 pkill -f 和 pgrep -f,透過比對模式與指令自身文字來判斷);該規則的原始一半——掃描與自身原始碼、註解或文件匹配的檔案;ps | grep;從變數中提取的模式;指令字串以外的腳本檔案中的匹配器——僅由此指令約束。

自撰寫以來已發生 1 次;最近一次為 2026-09-26。

任何檢查對象是其自身必須包含的文字的檢查——例如 linter、機密掃描器、政策 grep、規則掃描——都會因建構方式而匹配到自身。請將偵測器的自身原始碼、註解和 docstring 從其掃描中排除,在匹配前移除註解,並將路徑正規化為佔位符,以避免關於某模式的文件的描述被誤認為是該模式的實例。

原因並非整潔。一個永遠紅燈的檢查會被忽略,而被忽略的檢查比沒有檢查更糟,因為系統看起來仍受到防護。警報疲勞是負面價值,而非中性:它耗費了真正發現所需的注意力,並訓練讀者跳過將來某天會至關重要的輸出。

此原則也延伸至因正當理由引用該模式的任何內容。一個解釋某惡意字串已被移除的修正說明,若其中包含該惡意字串,就會在它本應滿足的掃描中成為永久的誤報——因此請描述該字串,而非複製它;若確實需要複製,請將其放在掃描規則而非運氣所能涵蓋的位置。

在發佈任何掃描前請問:這個檢查會出現在它自己的語料庫中嗎?如果會,它在一個乾淨的目錄樹上會輸出什麼? 如果乾淨目錄樹輸出不是空的,那麼這個檢查還無法正常運作,無論其邏輯多麼正確。

行程表也是一個語料庫。 pkill -f PAT、pgrep -f PAT 和 ps | grep PAT 會匹配所有行程的完整指令列——包括執行它們的 shell,而當指令以字串形式傳遞時(例如 bash -c、bash -lc、wsl.exe -- bash -lc、ssh host '...',以及每個透過 shell 執行指令的代理工具),其 argv 會照搬 PAT。在這種情況下,危害不是警報疲勞,而是 shell 自殺,或等待迴圈永遠等待自己。請撰寫模式使其自身文字無法匹配它——例如 [r]elease/frame 會匹配 release/frame 但不會匹配自身——或者使用 pgrep -x 來比對確切的行程名稱,或是使用你在啟動行程時紀錄的 PID。乾淨目錄樹的問題變成:在其他任何程式執行之前,這個比對器會找到什麼? 如果答案不是「什麼都沒有」,那麼它就找到了自己。

當某事物曾經正常運作時,先測試自那時以來的變更 [R:比對已知的良好狀態]

當某事物曾經正常運作時,找出自那時以來的變更,並優先測試那些變更。

一個回歸問題在其背後存在一個已知的良好狀態,而這個狀態是診斷中最有價值的事實:從那時到現在所有未變更的部分,對於這個症狀而言,都已經被排除嫌疑。調整那些保持不變的部分,是在浪費力氣於證據顯示問題不存在之處;而每個看似有幫助的調整,只會讓搜尋更漫長,因為它看似進展。

因此,在調整任何東西之前,請記錄下正常組態與故障組態之間的差異——硬體、設定、版本、控制器、人員、天氣——並根據將其消除的成本高低排序。然後,一次針對一個差異,執行最簡單的實驗來重建已知的良好狀態:還原它、繞過它,或強制使其回到舊行為。這樣的一個實驗就能排除一整個家族的理論,而這些理論若只靠調整,永遠只能略知皮毛。

如果擁有者自主提供了一個已知的良好狀態(例如「舊款恆溫器可以運作」、「升級之前都正常」),請將其視為…

[因翻譯需求而截斷]

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

george-andrikopoulos/domain-java

Engineering discipline for working in java. Covers: a speculated path deoptimises when the input changes; a view is not a copy; a wrapper type is not free here; close what you open; design for inheritance or forbid it; equality is one contract; exceptions name what failed; identity is not equality for boxes; no reference to internals escapes; null is not a value; publish safely or not at all; seal the alternatives; serializable is a second constructor

george-andrikopoulos/domain-low-latency

Engineering discipline for working in low-latency. Covers: attack the design in a second pass; a measurement matches the regime it reports; a queue without a bound has no overload behaviour; a structure keeps the regime it was proved under; allocated is not resident; answer the requirement at its layer; no allocation on the hot path; no coordinated omission; no false sharing on a hot line; no retry loop on a contended path; no stall inside a publication window; no syscall on a bounded path;...

george-andrikopoulos/domain-rust

Engineering discipline for working in rust. Covers: design types first; borrow in signatures; module visibility is deliberate; must use on consequential returns; newtype liberally; parse wide then range check; seal closed trait sets; typestate builder for required fields; typestate for protocols; verify the abstraction compiled away; async all the way; errors name what failed; justify every clone; no let underscore on a local; parse dont validate; private fields only; xplat fixtures; no...

相關技能