用途:API Mindset 把每个软件系统视为拥有一个“概念 API”——系统的 DNA,即一份简洁、人类可读的文档,记录定义软件本质的实体、操作与副作用,并以此作为全部开发工作的北极星。它仅在两种情况下激活:用户明确要求,或项目的 CLAUDE.md 指示。
主要能力:核心原则是动手前先问“本项目的概念 API 文档在哪里”。若存在,则阅读并让工作与之对齐;若不存在,则帮助用户从现有代码库中创建。耦合规则要求每个功能组件(UI 界面、后端服务、CLI 命令)都必须耦合到映射 DNA 操作的实现表面,不得直接访问数据库、内联拼装业务逻辑或自创路径;若所需表面尚不存在,应先将其作为 DNA 的实例化创建出来再耦合。
文档内容与位置:概念 API 不是 OpenAPI/Swagger 规范,而是 Markdown 编写的简明文档,产品经理可在 2 分钟内读懂,放在项目根目录 docs/api/,采用渐进式披露:docs/api/overview.md 为第一层,一览所有实体、操作与不变量;docs/api/entities.md 为第二层,详述每个实体的属性与关系。模板与完整示例见 references/format.md。文档包含实体(持久化领域对象,隐含 ID,无基础设施属性)、值对象(作为操作输入输出的非持久化结构)、操作(以 domain.verb 表示的系统能力及类型签名)、不变量(必须始终成立的业务规则)、副作用(操作执行时发生的通知、事件、审计等)。文档不包含实现细节(schema、路由、类层次)、基础设施关注点(部署、缓存、扩展)、UI/UX 细节以及 ID 字段或基础设施属性(created_at、缓存列)。
使用方式:工作流分为发现、创建、对齐、演进四步。进入项目时搜索 docs/api/overview.md,未找到则提议创建。创建时分析代码库,从领域对象提取实体与值对象,从能力(服务方法、端点、命令)提取操作,从业务规则提取不变量,从反应(通知、事件、触发器)提取副作用,按 references/format.md 的格式起草并与用户迭代。实现功能时先检查其映射到现有操作还是需要新操作;若需新操作,先更新概念 API 文档,再按相同操作名与签名跨层实现。文档是活的:变更须显式提出,不得静默漂移,宜在实现前或同步更新,并考虑对全部实例化层的影响。当系统增长时可按模块拆分 docs/api/ 目录,在操作与实体自然聚类且交叉引用较少时主动建议拆分。
适用场景与限制:适用于希望代码库在各层保持命名一致、结构可预测的团队与项目,尤其适合需要让非工程角色也能理解系统核心能力的场景。反模式包括:不查文档就实现、混入实现细节、命名发散(文档写 transfer 代码就不要叫 moveBalance)、视为可选、过度指定(它不是 OpenAPI)。具体命令、安装方式、收费与价格信息暂未提供。