SuperAPI AI 工具集

spec-system-map

编程与开发

查看项目

更新于 10-16 05:52

技能介绍

用途:创建或修订 spec/system-map.md,作为项目高层系统地图。它比通用 ARCHITECTURE.md 更聚焦,只记录项目级结构、边界、流程、存储与外部系统、不变量以及指向更深文档的指针,不承担模块文档、API 参考、运行手册、ADR 日志或实现笔记。

主要能力:按文件状态路由 create 与 amend 模式。create 在文件缺失或用户要求首版地图时使用;amend 在文件已存在且需更新架构形态、边界、流程、不变量或链接时使用。create 模式先读取有限信号(charter.md、README、AGENTS.md/CLAUDE.md、顶层目录、包/配置文件及架构相关文档),并执行 Repo Evidence Pass:检查入口与命令面、包/配置脚本、运行时边界、存储/状态面、外部系统、测试及近期提交/迭代证据,再按 templates/system-map.md 起草,包含 System Shape、Runtime Boundaries、Core Flows、Storage And External Systems、Project-Wide Invariants、Candidate Capability Boundaries、Where To Go Next。棕地项目须将不确定边界标为假设。Candidate Capability Boundaries 用于向 spec-grill 交接具体候选,需注明证据、疑似拥有的契约面及待解不确定性。

使用方式:由技能触发,无独立安装命令。create 结束时输出 Evidence Read 与 Evidence Missing 两类要点;Repo Evidence Pass 是智能体检查清单,证据在对话中报告,不写入地图。amend 只更新项目级形态、边界、流程、存储/外部系统、不变量或指针,把低层模块细节、端点列表、部署命令和临时实现笔记移出;若改动实为能力契约则路由至 spec-grill,若改动 why/良好状态则路由至 spec-charter amend。

限制:不做穷尽式模块文档,子系统细节下沉到链接文档;不得仅凭 README 和顶层目录就起草;地图须让读者 5 分钟内理解项目形态,只写当前事实而非愿景设计;不得包含过时模块级 TODO、端点清单或运行手册命令。