| name | spec-management |
| description | 生成或审计模块的 SPEC.md。使用场景:用户要求"给 XX 模块写 spec"、"审计所有 spec"、"检查 spec 是否过期"。 |
Spec 管理技能
按需为模块生成 SPEC.md,或审计已有 spec 与代码的一致性。
何时使用本技能
- 用户要求"给 XX 写 spec"、"生成 spec"
- 用户要求"审计 spec"、"检查 spec"、"spec 是否过期"
- 新增服务/子系统后需要补 spec
生成 SPEC.md
步骤
- 阅读目标模块源码:重点关注公开 API(export 的类/函数)、类型定义、依赖(import)、README 或文件头注释。
- 参考已有 SPEC 模板:读取
electron/services/agent/SPEC.md 了解格式和详细度基准。
- 撰写 SPEC.md,包含以下章节(设计目标优先,禁止用 API 表冒充):
# <模块名> SPEC
> Last verified: <今天日期>
## 职责
<1-2 句话描述模块做什么>
## 设计目标
<!-- 最重要:来自与用户讨论并确认的思路,不是从代码反推 -->
- **要解决的问题** / **成功标准**
- **关键取舍**(选了什么、放弃了什么、为什么)
- **明确不做**(本期边界)
## 行为契约 / 关键约束
<对外可见行为、不变量、边界条件>
## 文件结构(多文件模块才需要)
<文件列表 + 一句话说明>
## 公开 API
<!-- 实现索引,可随代码更新;不得覆盖「设计目标」 -->
<方法/函数表格:名称 | 用途 | 关键参数>
## 依赖
<该模块依赖的其他服务/模块>
-
遵循原则:
- 设计目标 > 契约 > API 索引;生成/审计时若只有 API 表没有设计目标,视为不合格
- 有用户讨论共识时:先写入「设计目标」再实现;无讨论时:设计目标写「待与用户对齐」,勿用实现细节填充
- 50-150 行,不超过 200 行
- 指向而非复制:类型定义用"见
types.ts"引用,不要抄一遍
- 设计目标写稳定取舍;易变实现细节(函数体步骤、临时命名)不进设计目标
- 用中文撰写
-
放置位置:
- 子系统目录(如
agent/)→ 放在目录下 SPEC.md
- 单文件服务(如
ai.service.ts)→ 放在同级目录,命名为 <SERVICE>_SPEC.md(如 AISERVICE_SPEC.md)
审计 SPEC.md
步骤
- 扫描所有 SPEC 文件:
find electron/services -name '*SPEC.md'
- 逐个对比:读取 spec,然后检查对应源码的公开 API 是否匹配;并检查是否有实质的「设计目标」(非空、非从 API 反推的套话)
- 报告结果:
| Spec 文件 | 状态 | 问题 |
|---|
| agent/SPEC.md | ✅ 同步 | - |
| AISERVICE_SPEC.md | ⚠️ 过期 | 新增了 chatWithVision 方法未记录 |
| foo/SPEC.md | ⚠️ 不合格 | 仅有 API 表,无用户确认的设计目标 |
| config.service.ts | ❌ 缺失 | 无 SPEC.md |
- 修复过期 spec:可自动更新 API/依赖等实现索引;设计目标不得凭空编造——缺失时标 ⚠️ 并询问用户,或标注「待与用户对齐」
- 不自动生成缺失 spec:仅报告缺失情况,让用户决定是否生成
注意事项
- 生成 spec 后不需要跑测试(spec 是纯文档,不影响代码行为)
- 审计时不要修改源码,只修改 SPEC.md
- 如果模块非常简单(< 100 行、只有 1-2 个函数),可以建议用户跳过,不必每个模块都有 spec