SuperAPI AI 工具集

writing-rules

编程与开发

查看项目

更新于 10-16 07:18

技能介绍

用途:指导编写 Claude Code 中 .claude/rules/ 规则文件——这是 Claude Code 特有的概念,即带 paths: glob 前置元数据的、始终加载的路径限定指令文件。Codex CLI 与 Antigravity 没有完全等同的 .claude/rules/,其常驻项目指令位于层级记忆文件(Codex 为 AGENTS.md,Antigravity 为 GEMINI.md,两者可指向规范的 AGENTS.md)。其中的“粗体祈使句+理由”写法适用于任何工具的指令文件。CLAUDE.md / AGENTS.md 约定见 writing-plugins,系统提示词见 writing-prompts。

主要能力与写法要点:

  1. 黄金格式:每条规则含三部分——祈使(做什么)、后果(不做会怎样)、机制(为何失败)。机制明显时可写单行规则,需解释时写多行。
  2. 正面表述(粉红大象效应):Claude 会聚焦被禁止之物,“不要用 X”反而让它想到 X,应改写为“使用 Y”。
  3. 可执行性测试:写规则前问“能否在 30 秒代码审查中检查合规”。主观不可测的表述(如“写干净代码”“保持函数小”)应改为可测量版本(如“函数必须少于 40 行,由 eslint max-lines-per-function 强制”)。
  4. 篇幅预算:所有规则合计应少于 500 行,因为规则在每次交互都会加载消耗 token。可减少行数的策略:交由 linter 强制、合并相关规则、删除 Claude 训练已知内容、用表格代替列表。
  5. 路径范围:非通用规则应通过前置元数据 paths 限定(如 paths: ["src/api/**/*.ts"]),可显著降低每次交互的 token 成本。
  6. 冲突预防:两条规则不得矛盾;若可能矛盾,放入同一文件并写明明确条件。新增规则前应搜索现有规则是否相反或覆盖更广。
  7. 附带工作示例:将 800 行、12 个文件精简为 180 行、4 个文件,token 成本从约 3,200 降至约 720。
  8. 质量清单:遵循黄金格式、正面表述、通过可执行性测试、总量少于 500 行、非通用规则限定路径、无冲突、不含训练默认内容、不重复 linter 已强制的规则。

限制:资料针对 Claude Code 的 .claude/rules/,其他工具无完全等同物,但写作技巧可迁移。具体项目适用性需自行判断。