SuperAPI AI 工具集

project-context

编程与开发

查看项目

更新于 10-16 22:15

技能介绍

用途

project-context 是一套项目上下文文件的编写与维护规范,用于记录代码本身无法表达的决策信息。它适用于在会话中首次进行代码操作之前,以及任务进入新领域时调用,帮助 AI 或协作者理解项目的术语、约定、设计原因和已知陷阱。

主要能力

该规范定义了四类值得写入上下文的内容:

  • word(术语):项目为其固定了含义的词语。
  • rule(规则):没有 linter 或类型检查器强制执行的约定。
  • reason(原因):代码无法展示的形态选择理由。
  • fence(围栏/陷阱):陷阱所在、触发位置(file:symbol)以及围栏存在的理由。

核心判断标准是:如果通过阅读代码就能学到,就只在“Where it lives”下链接路径,不写散文。Git 保存历史,skills CLI 保存安装状态,package.json 保存命令,这些都是事实来源,直接指向它们即可。文件超过约 150 行时,说明它包含两个领域或在复述代码,应拆分或删减。

使用方式

  • 在会话中首次代码操作前调用,并在任务进入新领域时再次调用。
  • 每个会话加载 glossary.md;当任务进入某个领域时加载对应的领域文件。
  • 引用表中的一行可以指向仓库中的任意路径;文件是否可加载由该表决定,而非是否位于此文件夹内。
  • 领域文件默认是已确定的,除非其头部另有说明:provisional 表示可以基于它构建,但将其细节保持在一个接缝之后;exploratory 表示在基于它构建之前先与其辩论。
  • 当任务改变决策时,需在同一 pull request 中更新对应领域文件。当代码与领域文件不一致时,询问负责人哪一方有误。
  • 提供 /audit-project-context 命令来强制执行上述所有规则。

适用场景

适用于需要长期维护、多人协作或 AI 辅助开发的项目,尤其是那些存在大量隐性约定、设计决策和易踩陷阱的代码库。通过将决策与代码分离,使上下文文件成为决策的上游来源,代码作为其实现。

限制

资料未提供该规范的具体安装命令、支持的平台、收费模式或实际使用效果。文件长度建议约 150 行以内,超出则需拆分或删减。领域文件的 provisional 和 exploratory 状态需要人工维护和判断。