AI 專家禁止 Agent 寫註解，背後是逼迫模型寫出「自解釋」程式碼的工程哲學。本文整理 GitHub 上最主流的 no-comments 開源 Skill、核心轉換機制，以及可直接導入本機的 SKILL.md 範本與常駐系統 Prompt。
AI 模型在生成程式碼時，常會留下大量解釋語法、重複命名意圖的「廢話註解」（俗稱 AI Slop / AI Tells），甚至用註解來掩蓋寫得不好的 workaround 或糟糕的命名。許多 AI 專家因此嚴格禁止自己的 Agent 在程式碼中加入任何註解，這背後其實是一套紮實的工程哲學：強制要求 No Comments，本質上是逼迫 Agent 透過重構（Refactoring）、精確命名與型別系統，寫出「自解釋（Self-documenting）」的程式碼，並把真正的業務限制轉換成測試、Assertion 或 Linter 規則。
本文整理 GitHub 社群中針對此需求發展出的成熟開源 Skill 套件與 Prompt 規範，並提供一份可直接放入本地環境的完整 SKILL.md 範本。
GitHub 上最知名的相關開源 Repo 與架構
社群在實踐「無註解原則」時，發現一個關鍵現象：「寫 code 的 Agent 會本能地為自己寫的註解辯護」。即使在全域設定檔寫了禁令，模型在長 context 下還是可能破戒。因此目前最頂尖的做法，除了靜態規則外，還會搭配專門負責獵殺註解的獨立 Skill 或 Subagent。
| 專案 / Repo 名稱 | 定位與核心特色 | 安裝 / 導入指令參考 |
|---|---|---|
cursor/plugins (pstack)(社群移植版： backnotprop/pstack、michael-denyer/pstack-claude) |
最硬核的 Subagent 架構。 內建名為 /no-comments 的 Skill 以及一個叫 comment-sicko 的 Subagent（官方描述：「一個熱愛刪除、痛恨 workaround 程式碼的狂熱註解厭惡者」）。它不讓原 Agent 自己清註解，而是派 Subagent 審查 diff，把「必須靠註解才看得懂的爛 code」標記為 MUST KILL，逼主 Agent 去重構程式碼結構。 |
npx skills add https://github.com/backnotprop/pstack --skill no-comments |
TheOnlyFusionCube/potetos-for-everyone(Skill: no-comments) |
輕量、高通用性的單一檔案 Skill。 專注於 5 步驟清理流程：清除解釋語法的廢話、消滅 AI 痕跡（AI tells），並強制將「不可刪除的業務規則註解」轉換為 Type、Test、Assertion 或 Lint 規則。 | npx -y skills add TheOnlyFusionCube/potetos-for-everyone --skill no-comments --agent claude-code |
AGENTS.md / CLAUDE.md 社群規範(如 millionco/claude-doctor、fedemelo/claude-config) |
常駐型全域防護欄（Always-on Guardrails）。 直接寫在專案根目錄或 ~/.claude/CLAUDE.md，在寫 code 的當下攔截註解生成。 |
直接複製下方 Prompt 區塊至全域設定檔 |
為什麼大神們的 Prompt 不只寫「禁止寫註解」？
如果你只寫 Do not write any comments，Agent 常會把真正重要的外部限制（例如某個 API 的怪異行為）直接刪掉，或是寫出沒人看得懂的單字母變數。參考上述開源 Repo 的設計，一個工業級的 no-comments Skill 必須包含三個核心轉換機制：
- 以重構代替解釋（Refactor over Explain）： 當 Agent 覺得某段邏輯複雜到想寫註解時，觸發規則強制它把該段落抽成一個命名極度精確的 Helper Function 或具名變數。
- 將限制條件編碼化（Encode Constraints into Code）： 如果註解寫著
// 絕對不能為負數或// 必須先呼叫 init，Skill 會要求 Agent 把這行註解刪掉，改寫成 Type 定義、Runtime Assertion、Unit Test 或 Custom Lint。 - 極少數的白名單（Strict Keep-List）： 只允許保留法規/License 標頭、無法修改的第三方系統 Bug 說明（需附上 Issue 連結），以及對外公開 SDK 的必要簽章文件（若為內部專案甚至連 JSDoc/Docstring 一併禁止）。
直接可用的本地 SKILL.md 整合範本
這份範本融合了 pstack（comment-sicko 的 MUST KILL 重構邏輯）與 TheOnlyFusionCube 的五步轉換法。你可以直接將它存成 ~/.claude/skills/no-comments/SKILL.md（或 .cursor/skills/no-comments/SKILL.md 等支援 Agent Skills 標準的目錄）：
---
name: no-comments
description: Enforce strict zero-comment, self-documenting code standards. Use whenever writing new code, refactoring, or cleaning up diffs/PRs to strip redundant comments, AI tells, and workaround explanations.
---
# Zero-Comment & Self-Documenting Code Policy
You are operating under a strict **No Comments** engineering contract. Comments rot, lie, and excuse bad code structure. Your goal is to write and maintain code whose intent, flow, and constraints are 100% transparent through structure, naming, and types alone.
## 1. Absolute Prohibitions (What You Must Never Write)
- **No narration or "AI tells":** Never write comments that narrate steps (`// Step 1: Fetch user`, `// Validate input`, `// Return result`).
- **No syntax or logic restatements:** Never explain *what* or *how* the code is doing something.
- **No history or diff markers:** Never leave comments like `// Added by AI`, `// Fixed bug`, `// Changed from X to Y`, or `// Here is the updated code`.
- **No dead code or TODOs:** Never leave commented-out code blocks or speculative `// TODO` / `// FIXME` notes.
- **No workaround apologies:** Never write comments excusing a hack. Fix the root cause instead.
## 2. Mandatory Action Protocol (How to Handle Complexity)
Whenever you feel the urge to write a comment—or when reviewing existing comments in a diff—execute these replacements instead:
1. **Urge to explain complex logic (MUST REFACTOR):**
- Extract the block into a small, single-purpose function whose name states the exact intent, or introduce descriptive intermediate variables.
2. **Urge to warn about a constraint (`"do not remove"`, `"must be called before X"`):**
- **Encode the constraint:** Convert the warning into a compile-time Type, a runtime Assertion/Guard clause, a dedicated Unit Test, or a Linter rule, then delete the comment.
3. **Urge to document a workaround:**
- Fix the underlying architectural issue in scope. Look at the code shape and reshape it so the surprise disappears.
## 3. The Only Permitted Exceptions (Strict Keep-List)
A comment may survive **only** if it documents an external reality we cannot control in our own code:
- Mandatory legal / license headers required by repository policy.
- Links to external upstream bug trackers, RFCs, or hardware/OS quirks that cannot be abstracted away (must include a verifiable URL or identifier, e.g., `// Workaround for WebKit bug https://bugs.webkit.org/...`).
- Required compiler/linter directives (only when fixing the underlying type/lint issue is strictly impossible due to third-party types).
## 4. Verification Workflow
Before finalizing any file edit or git diff:
1. Scan all added or modified lines for comment tokens (`//`, `/*`, `#`, `--`, `"""`).
2. Strip every comment that fails the Strict Keep-List test.
3. Verify that removing the comment did not obscure intent—if it did, rename the surrounding symbols or extract functions until the code reads effortlessly on its own.
針對「常駐系統 Prompt」的精簡版片段
除了作為獨立 Skill 呼叫外，如果你希望 Agent 在每一次日常寫 code 時都預設遵守，建議在你的全域 CLAUDE.md、AGENTS.md 或 .cursorrules 加上這段高密度的指令（語氣越強硬、邊界越明確，LLM 越不會破戒）：
## Code Style: Strict Zero-Comment Policy
- **NEVER write code comments** (`//`, `#`, `/* */`, docstrings) unless explicitly requested by the user.
- **No narration:** Do not leave breadcrumb comments explaining your thought process, steps, or changes.
- **Refactor instead of explaining:** If logic isn't immediately obvious, extract a well-named function or descriptive variable.
- **Encode constraints:** Express invariants through strict types, assertions, or tests—never through warning comments.
結語
導入「無註解」原則不是為了省下幾行字，而是為了提升 AI 生成程式碼的整體品質。透過上述開源 Skill 與 Prompt 規範，你可以讓 Agent 寫出結構更清晰、命名更精確、限制條件更明確的程式碼，同時大幅減少 AI 痕跡。建議先從輕量的 potetos-for-everyone 開始，再視需求導入 pstack 的 Subagent 審查機制，並將常駐規則寫入全域設定檔，讓無註解成為 Agent 的預設行為。