yzhao062/agent-style

Agent Style 的要素 – 是什么

agent-style 是一个轻量级、语言无关的库（可在 PyPI 和 npm 上获取），提供给 AI 编码与写作代理的 21 条写作规则。这些规则结合了经典风格建议（斯特伦克与怀特、奥威尔、平克、戈彭与斯旺）以及作者在 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 生成技术文档的 清晰度与一致性，而非构建新模型或训练流水线。