| name | sdd-framework |
| description | SDD (Specification-Driven Development) 框架技能包。AI Agent 开发流程规范，强调规格是_source of truth，代码服务于规格。
触发场景：收到功能请求时、任务规划时、代码审查时、跨团队协作时、重构前分析时。
适用角色：Prometheus(规划者)、Metis(计划审查)、Momus(质量审核)、Atlas(执行者)、Oracle(架构咨询)。
|
SDD Framework Skill
核心理念
Spec is Source of Truth — 规格是唯一的事实来源，代码必须服务于规格。
不是"写完代码再补文档"，而是"规格先行，代码验证规格"。
级别矩阵
| 级别 | 场景 | 核心要求 |
|---|
| L0 | typo/常量改名/注释修改 | 改完 → 安全扫描 → 审查卡片，5 分钟内完成 |
| L1 | 小 bug（根因明确，1-3 文件） | L0 + 回归测试 |
| L2 | 小功能（1-5 文件，需求清晰） | brainstorming 澄清 → L1 + TDD 单测 |
| L3 | 中型功能（3-10 文件，有设计选择） | L2 + Plan + Blueprint 验证 + 两阶段审查 |
| L4 | 大型功能（8+ 文件，新模块/跨系统） | L3 + Final Wave 四维验收 + UI Control 全场景 |
| 🚨 | 线上故障 | 先修，安全扫描降为 warning，24h 内补审查卡片 |
行为约束（7 条）
| 规则 | 说明 | 适用级别 |
|---|
| SCOPE | 只改 task scope 内的文件。diff 出现范围外文件需报告 scope creep。 | 全部 |
| READ | 改任何文件前先读。不了解代码就拒绝执行。 | L2+ |
| DILIGENCE | 改了函数/类型/导出后，grep 所有引用点确认兼容。 | L2+ |
| VERIFY | 改完跑 lint + 测试。失败不报告完成。 | 全部 |
| REVIEW | 完成后 30 秒自查 diff，逐条确认无遗漏。 | L3+ |
| SIMPLE | 不引入新抽象/工具函数/类型，除非 task 明确要求。 | 全部 |
| CASCADE | 改了初始化检查清理路径。改了清理检查恢复。 | L2+ |
需求唤起模式（5 步）
收到功能请求时，不要直接写代码：
- 后退 — 先搞清楚真正要解决什么
- 追问 — L2+: 2-3 个问题澄清边界：做什么？不做什么？有约束吗？
- 分段 — 把设计分成可消化的小段，每段确认后再往下
- 总结 — 用一句话 + 边界清单让用户确认
- 不做 — 用户确认前不写代码、不画架构、不给方案
输出格式：
> 我的理解: [一句话]
> 边界: ✅做 / ❌不做
> 需要你确认: [最多 1-2 个问题]
审查卡片模板
{
"summary": "做了什么（一句话）",
"decisions": [{"what": "选了 X 而非 Y", "why": "一行理由"}],
"changes": [{"file": "path", "desc": "改了什么"}],
"verification": {"lint":"pass","build":"pass","tests":"n/n","blueprint":"n deviations"}
}
L0/L1 简化版只需 summary + changes。
代码理解工具优先级
| 优先级 | 工具 | 用途 |
|---|
| 1 | semantic_search_nodes | 语义搜索函数/类在哪 |
| 2 | get_impact_radius | 改之前查影响面 |
| 3 | query_graph (callers_of) | 追溯调用链 |
| 4 | get_architecture_overview | 了解架构 |
| 5 | glob | 找文件名匹配 |
| 6 | grep | 文本搜索（最后手段） |
不要用 grep/read 去发现已经可以通过图工具一次拿到的东西。
任务管理规则
| 级别 | 计划要求 |
|---|
| L0-L1 | 直接改，不需要 Plan |
| L2+ | 创建 todo list，标记 in_progress → completed |
| L3+ | Plan Markdown + Blueprint Target Graph（人工签署后方可执行） |
过程文档 Checkpoint
| 级别 | 需要文档 |
|---|
| L0-L1 | 审查卡片（唯一产出） |
| L2 | 审查卡片 + 轻量 Plan（如有） |
| L3+ | Plan + Blueprint diff + 审查卡片 + 决策记录 |
所有文档写入 docs/{module}/ 或 .sisyphus/。会话结束自动执行 Design Sync。
语言 Profile 选择
根据实际使用的语言加载对应参考文件：
| 语言 | 参考文件 |
|---|
| TypeScript/React | references/typescript-profile.md |
| Java/Kotlin | references/java-profile.md |
| 其他语言 | 直接使用本 SKILL.md 的核心规则 |
参考文件导航
| 文件 | 何时阅读 |
|---|
references/sdd-improvement-plan.md | 需要完整分级矩阵、资产维护体系时 |
references/evaluation-framework.md | 需要评价框架定义时 |
references/cross-project-comparison.md | 六项目横向对比时 |
references/typescript-profile.md | TypeScript/React 项目时 |
references/java-profile.md | Java/Kotlin 项目时 |
references/global-agents-config.md | Agent 角色配置时 |
