SuperAPI AI 工具集

write-discoverable-code

编程与开发

查看项目

更新于 10-16 01:17

技能介绍

用途:让编码智能体(和人类)能通过纯文本搜索找到并理解代码。智能体靠字符串搜索和命中附近的小窗口读代码,没有悬停提示、跳转定义和跨会话记忆,这些规则让代码一次搜索即可解析。

主要能力与规则:

  1. 命名即搜索查询。导出符号用2–4个词命名,至少含一个领域词,如 diffUserObjects 而非 diff。资料称在约70万行单仓库中,单词导出名全局唯一率61%,三词96%,四词以上98%。通用动词要带宾语,如 sanitizeEmailHtml。每个符号只有一个定义处,不复制函数。不要靠模块路径消歧,把上下文放进符号名。一个概念一种拼写,行为或受众变化时在同一提交内重命名。文件名也要带领域前缀,避免 config.ts、utils.ts 等裸角色名,index.ts 仅作薄再导出入口。
  2. 类型是智能体无法跳过的文档。为原始 ID 加品牌类型,如 z.string().brand<'UserId'>();特权操作用能力令牌参数类型;用可辨识联合建模状态;类型名要能自我解释,避免 any。
  3. 在搜索落点处说明。每个导出加一行文档注释,写明代码本身无法体现的最关键约束(单位、时区、来源时间、归属)。注释中要包含自然语言短语,如“session has expired”,因为 camelCase 标识符无法匹配带空格的短语搜索。保持字符串完整,不用模板插值拼事件名或错误码。错误消息以唯一字面前缀开头。每个文件一个可搜索概念,编排器保持薄。测试与源码同目录。用 @deprecated 标记死路。

使用方式:在编写或重命名代码时应用上述规则,提交前用清单自查:每个新导出名一次搜索能否找到实现;交换新函数两个参数是否会构建失败;调用方必须知道但签名无法表达的信息是否写在定义处;日志/错误字符串是否在源码中逐字存在;是否有行为改变但名称未变;代码移动后原处是否已删除。

适用场景:编写、重命名、移动代码,尤其是大型代码库和面向编码智能体的项目。

限制:资料未提供具体工具集成、安装命令、收费或平台信息。