agentleFS
Sign inStart free
guang-lee-cnguang-lee-cn/scaffold-skills/skills/api-design-review/SKILL.md

api-design-review

Skill2 starsChanged 13 days agoMITView on GitHub

公共 API 面的红绿判定：最小面与永久承诺、类型精度（单位/裸标量）、所有权与生命周期表达、错误模型单一性、前置条件表达、限定符纪律、同族对称、扩展语义、ABI 与安装面闭包、线程安全契约、误用成本。评审"这组公开接口能不能冻结"时用；不教怎么写（正向样本看 cpp-exemplars）。触发词：API 设计/接口评审/公开面/导出面/ABI 兼容/安装面/重载设计/参数类型/错误模型一致性/接口冻结。

9 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use accessibility-audit and security-audit.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • GitHubSkill

    accessibility-audit

    Audits actual components and routes against applicable WCAG 2.2 A/AA criteria using consumer-owned design-system evidence and repository tools. Use when asked for an accessibility audit, a11y check, keyboard or focus review, contrast check, or screen-reader verification.

    Also in 3 projects that use this

  • CloudflareSkill

    security-audit

    Security guidance and vulnerability review for codebases, APIs, services, CLI tools, libraries, and daemons. Use for security questions, focused reviews, vulnerability research, security audits, or pen tests. Run the complete workflow only for explicit codebase audit or pen-test requests, full/comprehensive/end-to-end reviews, or requested report artifacts.

    Also in 3 projects that use this

The file

Create a free account to mount
Files
SKILL.md

公共 API 设计评审

定位

判"这组公开面能不能冻结"，不判实现质量、不教怎么写。每个公开符号都是永久承诺——评审的产出是"哪些承诺现在还不该给出"。

术语对齐

词本文口径
公开面使用者能编译到并链接到的全部：安装头 + 导出符号
安装面闭包安装头里出现的类型，其定义必须也在安装头里；否则该入口对外不可用
误用成本用错时的发现时机：编译期 > 运行期 > 线上
扩展新增枚举值、虚函数、重载、字段——各有不同的破坏半径

硬线（违反即红，不参与权衡）

#硬线判据（可机械判断）
A1安装面闭包必须自洽遍历安装头，凡以引用/值出现的自定义类型，其定义是否也在安装清单内；缺一 → 红（该入口对外不可用）
A2公共头不得泄漏第三方类型安装头里出现上游/第三方命名空间（如 eprosima:: / boost::）→ 红（除非该依赖本身是公开契约的一部分并有文档声明）
A3所有权与生命周期必须由签名表达返回裸 T*/T& 而不说明归属或有效期；或以裸指针转移所有权 → 红
A4不得用裸标量表达单位或模式int 表毫秒、bool/int 表枚举语义 → 红（应 duration 或强类型/枚举）
A5已发布签名不得靠"加默认参数"扩展加默认参数会改 mangled name → 隐性 ABI 断；应新增重载 → 违反即红
A6错误模型必须单一同一族接口不得混用"抛异常"与"返回码"；两种并存时必须在头文件写明分界 → 否则红
A7未声明有效期的引用/视图返回 string_view/span/内部引用而未写有效期 → 红
A8公开枚举/虚接口的扩展语义必须声明使用者可 switch 或继承的面上，新增值/纯虚函数是否构成破坏未写 → 红

十二维（判据细则见 references/dimensions.md）

1 最小面 · 2 类型精度 · 3 所有权与生命周期 · 4 错误模型单一性 · 5 前置条件表达 · 6 限定符纪律（const/noexcept/explicit）· 7 一致性与对称 · 8 扩展语义 · 9 ABI 与安装面闭包 · 10 线程安全契约 · 11 可测试性 · 12 误用成本

分级与出报告口径

  • 红 = 触硬线 A1–A8
  • 黄 = 现在能用，但会持续收费（对称性缺失、误用成本高、语义靠约定）
  • 绿不入报告——只出红黄；无红项的维度写进"未覆盖面"说明，不列绿清单

产出格式

[维度] A?/1..12 | 等级 红|黄
判据：<引用的硬线或维度判据原文>
证据：<file:line>（含签名摘录）
影响：<哪个使用场景会失败/误用，或哪个未来变更会被锁死>
建议方向：<指向类型/边界，不写实现步骤>

报告末尾必须给三项：① 命中硬线计数；② 红/黄计数；③ 未覆盖面（哪些维度因信息不足未评）。 另需单列 "已发布承诺清单"：当前公开面的符号/安装头数量——冻结前必须知道自己在承诺多少。

防假绿三条

  1. "文档里写了用法"不赦免 A1——装不出的类型，写多清楚都用不了。
  2. "外部暂时不用这个重载"不赦免——公开即承诺，未来会有人用。
  3. "改起来也就一行"不赦免 A5——破坏半径由使用者的重编译决定，不由改动行数决定。

边界（明确不做）

  • 不评内部实现质量（→ class-design-review）
  • 不评命名风格细则（→ comment-policy）
  • 不评性能数值；只评"签名是否把性能语义藏起来了"（如阻塞/不阻塞未标注）
  • 不把"接口少"当优点：最小面看的是"没有多余承诺"，不是"符号数最少"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free