yzhao062/agent-style

Agent Style 的要素 – 是什麼

agent-style 是一個輕量級、語言無關的程式庫（可在 PyPI 與 npm 上取得），提供給 AI 編碼與寫作代理的 21 條寫作規則。這些規則結合了經典風格建議（Strunk & White、Orwell、Pinker、Gopen & Swan）以及作者在 2022–2026 年間對 LLM 生成文字的觀察。核心理念是，代理可以在 生成時讀取規則 —— 規則成為系統提示的一部分，使模型在撰寫初稿時就嘗試遵守，而非事後修改文字。

規則的適用範圍

適用文件類型	不適用
API 文件、設計文件、研究論文、補助申請書、README、運行手冊、提交訊息、技術部落格文章、事後分析、問題報告	小說、詩歌、行銷文案、長篇敘事非虛構作品、非英語文字、節奏或情感表達重於精確性的文字

21 條規則分為兩個對等群組：

• RULE‑01 … 12 – 直接取自四本經典風格參考書的權威規則，每條均有精確出處。
• RULE‑A … I – 「現場觀察」規則，捕捉 LLM 常見的特定失誤（如過度使用項目符號、破折號、重複句首、不必要的過渡詞、缺少引用等）。

兩組規則同等重要，無優先級之分。

如何運作

1. 軟性強制（生成時） – 執行 agent-style enable <adapter> 以適配您使用的 AI 工具（Claude Code、GitHub Copilot、Cursor、Aider 等）。CLI 會將一個小規則檔案（或追加標記區塊）寫入工具讀取系統提示的位置。當模型生成文字時，規則已存在於其上下文中，自然引導其向期望的風格靠攏。
2. 技能 / 第二輪審查 – 生成初稿後，執行 agent-style style-review <path>（或在支援技能的主機上呼叫 style-review 技能）。該命令會依據相同的 21 條規則審查初稿，並在您確認後，產生一份潤色後的版本與原始文字並列。

該套件提供多個流行代理的適配器（Claude Code、Codex/AGENTS.md、GitHub Copilot、Cursor、Anthropic Skills、Kiro 等），甚至提供「免安裝」curl 腳本，可直接將規則檔案拉取至 .agent-style 檔案夾。

有效果嗎？

作者提供了一個 合理性基準測試，涵蓋十個固定技術寫作任務（產品描述、設計文件節選、論文相關工作、PR 描述、提交訊息等）。每個任務中，模型分別在載入規則與未載入規則下運行兩次，由機械式審查器統計規則違反次數。

模型（2026）	無規則違規數	有規則違規數	減少率
Claude Opus 4.7	88	47	‑47 %
OpenAI GPT‑5.4（Codex CLI）	48	26	‑46 %
Gemini 3 Flash	65	9	‑86 %
GitHub Copilot（對照組）	52	52	0 %

該基準僅測量部分規則（7 條機械規則），因為審查器運行在「純機械模式」。最大收益來自減少長句（RULE‑12）、避免使用 em/en 破折號（RULE‑B）和消除術語濫用（RULE‑06）。語義規則如引用規範（RULE‑H）和「知識詛咒」（RULE‑01）未被當前基準涵蓋，因此數據僅為 方向性參考，不構成統計顯著性主張。

誰會用它？

• AI 編碼或寫作助手的開發者（Claude Code、Codex、GitHub Copilot、Cursor、Aider、Kiro、Replit 等），希望其代理生成更清晰、更符合慣例的技術文字。
• 這些代理的維護者，需要一種簡單方式將風格指導注入模型提示，或添加生成後審查步驟。

快速開始（Python 範例）

pip install agent-style          # 或 npm i -g agent-style
agent-style enable claude-code   # 為 Claude Code 寫入規則檔案
# 後續，初稿生成後：
agent-style style-review path/to/file.md

README 還提供了每種支援工具創建的檔案清單、未來計畫適配器清單，以及包含 BAD/GOOD 範例的完整 RULES.md。

---

核心結論：agent-style 是一個實用、開源的工具，可將簡潔、文獻支持的風格指南嵌入任何基於 LLM 的寫作代理的提示中，並可選擇性地在生成後運行輕量級規則審查。它專注於提升 AI 生成技術文件的 清晰度與一致性，而非建構新模型或訓練流程。