ai-ad-spec-kit

name: ai-ad-spec-kit version: "1.0" status: ready_for_production layer: skill owner: wade last_reviewed: 2025-12-17 baseline:

• MASTER.md v3.5
• SoT Freeze v2.6
• PROJECT_RULES.md v3.4 source_reference:
• name: "GitHub Spec-Kit" url: "https://github.com/github/spec-kit" license: "MIT" adapted_features:
  • "Constitution → Specification → Planning → Tasks → Implementation 工作流"
  • "命令化接口设计"
  • "多 AI Agent 支持架构"

<source_attribution> 本 Skill 借鉴自 GitHub 官方开源项目 Spec-Kit:

• GitHub: https://github.com/github/spec-kit
• License: MIT
• 核心理念: 规范先行，代码后行

适配改动:

• 将 Constitution 概念对齐到 MASTER.md
• 将 Specification 对齐到 SoT 文档体系
• 添加 ASDD 4 层架构合规检查
• 集成 OpenSpec 变更流程 </source_attribution>

核心原则:

• 📜 规范先行: 先写规范，再写代码
• 🔗 SoT 对齐: 所有规范必须与 SoT 文档一致
• 📝 任务分解: 大需求拆分为可验证的小任务
• ✅ 持续验证: 每个阶段都有明确的验证点 </mission>

<actions>
  - 读取 docs/sot/MASTER.md
  - 读取 .claude/PROJECT_RULES.md
  - 确认业务边界和不变量
  - 确认永久禁止行为
  - 输出: constitution_context
</actions>

<output_format>
  ## 🏛️ Constitution 确认

  ### 业务边界
  - [从 MASTER.md 提取]

  ### 核心不变量
  - [从 PROJECT_RULES.md 提取]

  ### 禁止行为
  - [列出与当前需求相关的禁止项]

  ### 下一步
  - 执行 `/speckit.specify` 进入规范阶段
</output_format>

<inputs>
  - requirement: 需求描述 (自然语言)
  - constitution_context: 上一阶段输出
</inputs>

<actions>
  - 识别涉及的业务域
  - 查询对应 SoT 文档:
    - STATE_MACHINE.md (状态相关)
    - DATA_SCHEMA.md (数据相关)
    - API_SOT.md (API 相关)
    - BUSINESS_RULES.md (规则相关)
  - 提取相关约束条件
  - 生成: specification_doc
</actions>

<output_format>
  ## 📋 Specification 规范

  ### 需求摘要
  [用户需求的结构化描述]

  ### 涉及 SoT 文档
  | 文档 | 版本 | 相关章节 |
  |------|------|---------|
  | STATE_MACHINE.md | v2.6 | §X |
  | DATA_SCHEMA.md | v5.2 | §X |

  ### 约束条件
  - [从 SoT 提取的约束]

  ### 成功标准
  - [可验证的成功条件]

  ### 下一步
  - 执行 `/speckit.plan` 进入规划阶段
</output_format>

<inputs>
  - specification_doc: 上一阶段输出
</inputs>

<actions>
  - 分析技术栈约束 (FastAPI, Pydantic v2, SQLAlchemy 2.x)
  - 确定文件结构和模块划分
  - 设计 API 接口 (如适用)
  - 设计数据模型 (如适用)
  - 识别潜在风险
  - 生成: implementation_plan
</actions>

<output_format>
  ## 🗺️ Implementation Plan 实现方案

  ### 技术方案
  - 后端: [Router/Service/Schema 设计]
  - 前端: [Hook/API/Component 设计]

  ### 文件清单
  | 文件 | 操作 | 说明 |
  |------|------|------|
  | backend/routers/xxx.py | 新建/修改 | ... |

  ### 依赖关系
  ```
  [依赖图]
  ```

  ### 风险识别
  - [潜在风险及缓解措施]

  ### 下一步
  - 执行 `/speckit.tasks` 生成任务清单
</output_format>

<inputs>
  - implementation_plan: 上一阶段输出
</inputs>

<actions>
  - 分解为原子任务 (每个 < 30 分钟)
  - 定义每个任务的验收标准
  - 排列任务优先级和依赖
  - 生成: task_list
</actions>

<output_format>
  ## ✅ Task List 任务清单

  ### 任务列表

  #### Task 1: [任务名称]
  - **文件**: `path/to/file.py`
  - **操作**: 新建/修改
  - **描述**: [具体操作]
  - **验收标准**: [如何验证完成]
  - **依赖**: [前置任务]

  #### Task 2: ...

  ### 执行顺序
  ```
  Task 1 → Task 2 → Task 3
               ↘
                Task 4
  ```

  ### 下一步
  - 执行 `/speckit.implement` 开始实现
  - 或执行 `/speckit.implement task=1` 实现特定任务
</output_format>

<inputs>
  - task_list: 上一阶段输出
  - task: 可选，指定执行的任务编号
</inputs>

<actions>
  - 按顺序执行任务
  - 每个任务完成后验证
  - 调用 CodeFactory Skills (如已实现):
    - CodeSearcherSkill (搜索参考代码)
    - CodeAdapterSkill (适配代码)
    - CodeAssemblerSkill (组装代码)
    - CodeVerifierSkill (验证代码)
  - 生成: implementation_result
</actions>

<output_format>
  ## 🚀 Implementation Result 实现结果

  ### 已完成任务
  - [x] Task 1: [描述] ✅
  - [x] Task 2: [描述] ✅
  - [ ] Task 3: [描述] ⏳

  ### 生成的文件
  | 文件 | 状态 | 行数 |
  |------|------|------|
  | backend/routers/xxx.py | 新建 | 150 |

  ### 验证结果
  - mypy: ✅ 通过
  - ruff: ✅ 通过
  - SoT Guard: ✅ 通过

  ### 下一步
  - 运行测试: `pytest backend/tests/xxx`
  - 或继续: `/speckit.implement task=3`
</output_format>

<auxiliary_commands> <command id="/speckit.clarify"> <description>澄清规范中的模糊点</description> <usage>/speckit.clarify "状态转换规则不明确"</usage> </command>

<asdd_integration> <mapping> | Spec-Kit 阶段 | ASDD 对应层 | 文档 | |---------------|------------|------| | Constitution | Layer 1: Overview | MASTER.md, PROJECT_RULES.md | | Specification | Layer 2: SoT | STATE_MACHINE.md, DATA_SCHEMA.md, etc. | | Plan | Layer 3: Dev-Guides | API_DEVELOPMENT_FLOW.md | | Tasks | Layer 3: Dev-Guides | 任务清单 | | Implement | Layer 4: Architecture | 代码实现 | </mapping>

/speckit.constitution [确认宪法约束]

/speckit.specify [生成规范文档]

/speckit.plan [制定技术方案]

/speckit.tasks [分解任务清单]

/speckit.implement [执行实现] 」

示例 2: 从中间阶段开始 「 我已经有需求规范了，直接进入规划阶段。

/speckit.plan requirement = "添加日报批量导出，支持按状态和日期筛选，输出 xlsx 格式" 」

示例 3: 单任务执行 「 /speckit.implement task=2 只执行任务清单中的第 2 个任务 」 </usage>

<VERSION_NOTES>

v1.0 (2025-12-17)

• 初始版本
• 基于 GitHub Spec-Kit 适配
• 五阶段工作流: Constitution → Specify → Plan → Tasks → Implement
• 与 ASDD 4 层架构集成
• 添加辅助命令: clarify, analyze, checklist, status </VERSION_NOTES>