# codespec-sdd **Repository Path**: zyh-soft/codespec-sdd ## Basic Information - **Project Name**: codespec-sdd - **Description**: SDD规范驱动的codespec知识管理技能包。提供完整的规范驱动开发能力，包括目录初始化、工作区创建、规格编写、设计编写、任务生成、代码验证、工作区归档等。支持自然语言分阶段使用和一键式全流程开发。触发场景：需要初始化codespec目录、开始新特性开发、编写规格/设计文档、验证代码一致性、管理codespec知识库时使用。**重要**：首次使用本技能前必须确保项目根目录存在AGENTS.md。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-06-03 - **Last Updated**: 2026-07-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README --- name: codespec-sdd-md-init description: SDD规范驱动的codespec知识管理技能包。提供完整的规范驱动开发能力，包括目录初始化、工作区创建、规格编写、设计编写、任务生成、代码验证、工作区归档等。支持自然语言分阶段使用和一键式全流程开发。触发场景：需要初始化codespec目录、开始新特性开发、编写规格/设计文档、验证代码一致性、管理codespec知识库时使用。**重要**：首次使用本技能前必须确保项目根目录存在AGENTS.md。 --- # Codespec SDD - 规范驱动开发技能包 ## 概述 本技能包提供基于SDD（Spec-Driven Development）规范驱动的codespec知识管理能力，支持从需求到归档的完整开发流程。 **核心特性：** - 🎯 **自然语言触发**：支持对话式交互，自动识别用户意图 - 🚀 **一键式全流程**：从需求到归档的端到端自动化 - 🔍 **上下文感知**：增量开发前自动读取现有代码和文档 - 📊 **代码-设计验证**：自动检查实现是否符合设计 - 📚 **知识积累沉淀**：支持增量开发和归档管理 ## 快速开始 ### 方式1：一键全流程（推荐） ``` 用户：帮我开发用户登录功能 AI：[自动启动codespec-workflow全流程] ``` ### 方式2：分阶段使用 ``` 用户：初始化codespec AI：[调用 codespec-init] 用户：创建工作区US001 用户登录 AI：[调用 codespec-new] 用户：编写规格文档 AI：[调用 codespec-spec] 用户：编写设计文档 AI：[调用 codespec-design] 用户：生成任务清单 AI：[调用 codespec-tasks] 用户：验证代码一致性 AI：[调用 codespec-verify] ``` ## 技能列表 ### 核心技能 | 技能名称 | 功能 | 触发关键词 | |---------|------|-----------| | **codespec-init** | 初始化目录结构 | "初始化codespec"、"init codespec" | | **codespec-context** | 读取项目上下文 | "开发xxx功能"、"了解现有系统"（自动触发） | | **codespec-new** | 创建特性工作区 | "创建工作区"、"new workspace" | | **codespec-spec** | 编写规格文档 | "编写规格"、"write spec" | | **codespec-design** | 编写设计文档 | "编写设计"、"write design" | | **codespec-tasks** | 生成任务清单 | "生成任务"、"generate tasks" | | **codespec-verify** | 验证代码一致性 | "验证代码"、"verify code" | | **codespec-unit-test** | 单元测试规范与生成 | "编写单元测试"、"生成测试代码" | | **codespec-archive** | 归档工作区 | "归档工作区"、"archive workspace" | | **codespec-workflow** | 全流程协调器 | "帮我开发xxx"、"codespec全流程" | ### 技能关系图 ``` codespec-workflow (全流程协调器) ├─→ codespec-init (初始化) ├─→ codespec-context (读取上下文) 🆕 ├─→ codespec-new (创建工作区) ├─→ codespec-spec (编写规格) ├─→ codespec-design (编写设计) ├─→ codespec-tasks (生成任务) ├─→ codespec-unit-test (单元测试) ├─→ codespec-verify (验证一致性) └─→ codespec-archive (归档) ``` ## 全流程工作流 ``` 用户需求 ↓ [阶段1] codespec-init → 初始化目录（首次使用） ↓ [阶段1.5] 🆕 codespec-context → 读取项目上下文（增量开发必须） ↓ [阶段2] codespec-new → 创建工作区 ↓ [阶段3] codespec-spec → 编写规格（做什么） ↓ [阶段4] codespec-design → 编写设计（怎么做） ↓ [阶段5] codespec-tasks → 生成任务（执行步骤） ↓ [阶段6] 编码实现 → 按任务开发 ↓ [阶段7] codespec-unit-test → 编写单元测试 ↓ [阶段8] codespec-verify → 验证一致性 ↓ [阶段9] codespec-archive → 归档工作区 ↓ 流程完成 ✅ ``` ## 目录结构 ``` codespec/ ├── changes/ # 增量变更工作目录 │ ├── -/ # 单个特性开发工作区 │ │ ├── context-report.md # 🆕 项目上下文报告 │ │ ├── delta-spec.md # 增量规格文档 │ │ ├── delta-design.md # 增量设计文档 │ │ ├── tasks.md # 任务清单 │ │ ├── alpha-tests.md # 验收测试 │ │ ├── verify-report.md # 验证报告 │ │ └── proposal.md # 提案 │ └── archives/ # 工作归档目录 │ └── -/ ├── guidelines/ # 规范指南目录 │ ├── coding.md # 编码规范 │ ├── design-checklist.md # 设计规范检查清单 │ ├── dfx/ # DFX规范 │ │ ├── observability.md # 可观测性设计 │ │ ├── reliability.md # 可靠性设计 │ │ └── security.md # 安全设计 │ ├── integration-test.md # 集成测试文档 │ └── unit-test.md # 单元测试规范 ├── specs/ # 全量规格文档目录 │ ├── arch/ │ │ └── debts.md # 技术债务 │ ├── design.md # 全量设计文档 │ ├── spec.md # 全量规格文档 │ ├── verify-report.md # 验证报告 │ └── references/ # 参考文档 ├── service-context.md # 周边交互全集 └── terms.md # 术语表 ``` ## 使用场景 ### 场景1：新项目初始化 ``` 用户：这是一个新项目，请初始化codespec AI：[调用 codespec-init] ✅ 目录初始化完成 用户：创建第一个特性工作区，用户管理功能 AI：[调用 codespec-new] ✅ 工作区创建完成 用户：开始编写规格文档 AI：[调用 codespec-spec] 请描述功能需求... ``` ### 场景2：功能开发全流程 ``` 用户：帮我开发订单支付功能 AI：[调用 codespec-workflow] [阶段1] 检查初始化... [阶段1.5] 🆕 读取项目上下文... - 读取 AGENTS.md - 扫描现有代码 - 检查相似功能 - 生成上下文报告 [阶段2] 创建工作区... [阶段3] 编写规格... [阶段4] 编写设计... [阶段5] 生成任务... [阶段6] 提示编码... [阶段7] 验证一致性... [阶段8] 归档工作区... 🎉 全流程完成！ ``` ### 场景3：代码质量验证 ``` 用户：验证用户登录功能的代码实现 AI：[调用 codespec-verify] 扫描代码库... 对比设计文档... 生成验证报告... ✅ 验证完成！ 综合评级：⚠️ 有条件通过 (85%) 发现问题： 1. User模型缺少last_login字段 ``` ## 核心原则 ### 增量开发必须读取上下文 **原则**：增量开发前，必须先读取现有代码和文档，确保新功能与现有系统保持一致。 **检查清单**： - [ ] 已读取 AGENTS.md（项目知识图谱） - [ ] 已读取全量规格文档（如存在） - [ ] 已读取全量设计文档（如存在） - [ ] 已扫描现有代码库 - [ ] 已检查相似功能 - [ ] 已生成上下文报告 **核心价值**： - ✅ 避免架构冲突 - ✅ 复用现有组件 - ✅ 保持风格一致 - ✅ 减少重复工作 ### 规格与设计分离 **规格文档（spec.md）**： - 关注点：构建什么（What） - 内容：业务规则、验收标准、数据约束 - 受众：产品经理、测试人员、开发人员 **设计文档（design.md）**： - 关注点：如何构建（How） - 内容：系统架构、接口设计、数据模型 - 受众：开发人员 ### 禁止混用内容 | 规格文档允许 | 规格文档禁止 | |------------|------------| | ✅ 业务规则 | ❌ 数据库表结构 | | ✅ 验收标准 | ❌ API路由定义 | | ✅ 用户场景 | ❌ 技术栈选择 | | ✅ 数据约束 | ❌ 实现细节 | ## 工具脚本 ### init_codespec.py **位置**：`scripts/init_codespec.py` **功能**：目录初始化、工作区管理、验证调用 **命令**： ```bash # 初始化目录 python scripts/init_codespec.py <项目路径> # 创建工作区 python scripts/init_codespec.py <项目路径> new # 验证增量设计 python scripts/init_codespec.py <项目路径> verify delta # 验证全量设计 python scripts/init_codespec.py <项目路径> verify # 列出工作区 python scripts/init_codespec.py <项目路径> list # 归档工作区 python scripts/init_codespec.py <项目路径> archive ``` ### verify_codespec.py **位置**：`scripts/verify_codespec.py` **功能**：代码-设计一致性验证 **验证维度**： - 功能模块一致性 - 接口定义一致性 - 数据模型一致性 - 关键流程一致性 ## 前置条件 **重要**：首次使用本技能包前，必须确保项目根目录存在 `AGENTS.md` 文件。 **检查方法**： ``` 检查项目根目录是否存在 AGENTS.md 文件 （注意：是 AGENTS.md，复数，带s） ``` **若不存在**： 1. 调用 `project-knowledge-graph-generator` 技能 2. 使用命令：`/init` 或 `请生成项目知识图谱` 3. 等待知识图谱生成完成 ## 参考文档 ### 模板文档（templates/） - `spec_template.md` - 规格文档模板 - `design_template.md` - 设计文档模板 ### 指南文档（references/） - `SPEC_GUIDE.md` - 规格文档编写指南 - `DESIGN_GUIDE.md` - 设计文档编写指南 - `VERIFY_GUIDE.md` - 验证功能使用指南 - `ARCHITECTURE.md` - 架构设计模板 - `UNIT_TEST.md` - 单元测试规范 ## 最佳实践 ### 1. 推荐工作流程 ``` 需求明确 → codespec-new → codespec-spec → codespec-design → codespec-tasks → 编码实现 → codespec-verify → codespec-archive ``` ### 2. 验证时机 - ✅ 编码完成后立即验证 - ✅ 代码评审前先验证 - ✅ 版本发布前必验证 - ✅ 持续集成自动验证 ### 3. 知识管理 - 定期归档完成的工作区 - 提取通用设计方案 - 更新技术债务清单 - 维护术语表 ## 故障排查 ### 问题1：AGENTS.md不存在 **解决方案**： ``` 调用 project-knowledge-graph-generator 技能生成 ``` ### 问题2：验证报告显示"不通过" **解决方案**： 1. 查看阻断性问题列表 2. 优先修复阻断性问题 3. 重新运行验证 ### 问题3：工作区已存在 **解决方案**： - 使用现有工作区继续开发 - 或删除后重新创建 ## 技术支持 - **文档位置**：`.opencode/skills/codespec-sdd-md-init/` - **脚本位置**：`scripts/` - **模板位置**：`templates/` - **参考文档**：`references/` --- **版本**：2.0 **最后更新**：2026-06-01 **维护者**：Codespec Team