# speccrew **Repository Path**: amutek/speccrew ## Basic Information - **Project Name**: speccrew - **Description**: SpecCrew：一款由AI驱动的软件工程框架，可将虚拟 AI 开发团队嵌入你的项目中。支持规范驱动开发（SDD）模式，完整覆盖从产品需求文档（PRD）→功能设计→详细设计→功能开发→系统测试的全工作流程。Harness实战落地。 - **Primary Language**: JavaScript - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 0 - **Created**: 2026-03-21 - **Last Updated**: 2026-04-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: sdd, spec-kit, open-spec, AI变成, AI编程 ## README # SpecCrew - AI 驱动的软件工程化框架

简体中文 | 繁體中文 | English | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt

> 让任何软件项目快速实现工程化落地的虚拟 AI 开发团队 ## 什么是 SpecCrew？ SpecCrew 是一套嵌入式的虚拟 AI 开发团队框架。它将专业的软件工程流程（PRD → Feature Design → System Design → Dev → Test）转化为可复用的 Agent 工作流，帮助开发团队实现规范驱动开发（SDD），特别适合已有项目。通过将 Agent 和 Skill 集成到现有项目，即可快速初始化项目文档体系和虚拟软件团队，按照标准工程流程分步实现功能的新增和修改。 --- ## ✨ 核心亮点 ### 🏭 虚拟软件团队一键生成 **7 个专业 Agent 角色** + **30+ 个 Skill 工作流**，构建完整虚拟软件团队： - **Team Leader** - 全局调度与迭代管理 - **Product Manager** - 需求分析与 PRD 输出 - **Feature Designer** - 功能设计 + API 契约 - **System Designer** - 前端/后端/移动端/桌面端系统设计 - **System Developer** - 多端并行开发 - **Test Manager** - 三阶段测试协调 - **Task Worker** - 子任务并行执行 ### 📐 ISA-95 六段式建模基于国际标准 **ISA-95** 建模方法论，实现业务需求到软件系统的标准化转化： ``` Domain Descriptions → Functions in Domains → Functions of Interest ↓ ↓ ↓ Information Flows → Categories of Information → Information Descriptions ``` - 每个阶段对应明确的 UML 图（用例图、序列图、类图等） - 业务需求"逐级细化"，无信息丢失 - 输出物可直接用于开发 ### 📚 知识库体系三层次知识库架构，确保 AI 始终基于"事实来源"工作： | 层级 | 目录 | 内容 | 作用 | |------|------|------|------| | L1 系统知识 | `knowledge/techs/` | 技术栈、架构、开发规约 | AI 理解项目技术边界 | | L2 业务知识 | `knowledge/bizs/` | 模块功能、业务流程、实体关系 | AI 理解业务逻辑 | | L3 迭代产物 | `iterations/iXXX/` | PRD、设计文档、测试报告 | 当前需求完整追溯链 | ### 🔄 四阶段知识流水线 **自动化知识生成架构**，从源代码自动生成业务/技术文档： ``` Stage 1: 扫描源码 → 生成模块清单 Stage 2: 并行分析 → 提取功能特性（多 Worker 并行） Stage 3: 并行汇总 → 完善模块概览（多 Worker 并行） Stage 4: 系统聚合 → 生成系统全景图 ``` - 支持 **全量同步** 和 **增量同步**（基于 Git diff） - 一人优化，团队共享 ### 🔧 Harness 实战落地框架 **标准化执行框架**，确保设计文档精准转化为可执行的开发指令： - **操作手册原则**：Skill 即 SOP，步骤清晰、连续、自包含 - **输入输出契约**：明确定义接口，像伪代码一样严谨执行 - **逐级披露架构**：信息分层加载，避免一次性上下文过载 - **子 Agent 委派**：复杂任务自动拆分，并行执行确保质量 --- ## 解决 8 个核心问题 ### 1. AI 忽略现有项目文档（知识断层） **问题**：现有 SDD 或 Vibe Coding 方法依赖 AI 实时总结项目，容易遗漏关键上下文，导致开发结果偏离预期。 **解决**：`knowledge/` 知识库作为项目的"事实来源"，沉淀架构设计、功能模块、业务流程等核心信息，确保需求源头不偏差。 ### 2. 需求文档直接转技术文档（内容遗漏） **问题**：从 PRD 直接跳到详细设计，容易遗漏需求细节，开发出的功能与需求脱节。 **解决**：增加 **Feature Design 文档**环节，不考虑技术细节，只聚焦需求骨架： - 包含哪些页面和组件？ - 页面操作流程 - 后端处理逻辑 - 数据存储结构开发阶段只需基于特定技术栈"填肉"，确保功能"贴着骨头（需求）"生长。 ### 3. Agent 搜索范围不确定（不确定性） **问题**：复杂项目中，AI 大范围搜索代码和文档，结果不确定，难以保证一致性。 **解决**：明确的文档目录结构和模板，基于每个 Agent 所需内容设计，实现 **逐级披露、按需加载**，确保确定性。 ### 4. 环节缺失、任务遗漏（流程断裂） **问题**：缺乏完整的工程流程覆盖，容易遗漏关键步骤，质量难以保证。 **解决**：覆盖软件工程全环节： ``` PRD（需求）→ Feature Design（功能设计）→ API Contract（契约） → System Design（系统设计）→ Dev（开发）→ Test（测试） ``` - 每个环节产出物是下一环节的输入 - 每步需人工确认后方可执行 - 所有 Agent 执行都有 todo 清单，完成后自检 ### 5. 团队协作效率低（知识孤岛） **问题**：AI 编程经验难以在团队间共享，重复踩坑。 **解决**：所有 Agents、Skills 和相关文档与源码一起进入 Git 版本管控： - 一人优化，团队共享 - 知识沉淀在代码库中 - 提升团队协同效率 ### 7. 单 Agent 上下文过长（性能瓶颈） **问题**：大型复杂任务超出单 Agent 上下文窗口，导致理解偏差、输出质量下降。 **解决**：**子 Agent 自动调派机制**： - 复杂任务自动识别并拆分为子任务 - 每个子任务由独立子 Agent 执行，上下文隔离 - 父 Agent 协调汇总，确保整体一致性 - 避免单 Agent 上下文膨胀，保障输出质量 ### 8. 需求迭代混乱（管理困难） **问题**：多个需求混杂在同一分支，相互影响，难以追踪和回滚。 **解决**：**每个需求作为独立项目**： - 每个需求创建独立迭代目录 `iterations/iXXX-[需求名]/` - 完整隔离：文档、设计、代码、测试独立管理 - 快速迭代：小粒度交付，快速验证，快速上线 - 灵活归档：完成后归档至 `archive/`，历史清晰可追溯 ### 6. 文档更新滞后（知识腐化） **问题**：项目演进后文档过时，AI 基于错误信息工作。 **解决**：Agent 具有自动更新文档的能力，及时同步项目变化，保持知识库实时准确。 --- ## 核心工作流程 ```mermaid graph LR A[PRD
需求文档] --> B[Feature Design
功能设计] B --> C[API Contract
接口契约] C --> D[System Design
系统设计] D --> E[Dev
开发实现] E --> F[System Test
系统测试] F --> G[Archive
归档] H[Knowledge
知识库] -.-> A H -.-> B H -.-> D H -.-> E E -.-> H F -.-> H ``` ### 各阶段说明 | 阶段 | Agent | 输入 | 输出 | 人工确认 | |------|-------|------|------|----------| | PRD | PM | 用户需求 | 产品需求文档 | ✅ 必需 | | Feature Design | Feature Designer | PRD | 功能设计文档 + 接口契约 | ✅ 必需 | | System Design | System Designer | Feature Spec | 前端/后端设计文档 | ✅ 必需 | | Dev | Dev | Design | 代码 + 任务记录 | ✅ 必需 | | System Test | Test Manager | Dev 产出 + Feature Spec | 测试用例 + 测试代码 + 测试报告 + Bug 报告 | ✅ 必需 | --- ## 与现有方案对比 | 维度 | Vibe Coding | Ralph 循环 | **SpecCrew** | |------|-------------|------------|-------------| | 文档依赖 | 忽略现有文档 | 依赖 AGENTS.md | **结构化知识库** | | 需求传递 | 直接编码 | PRD → 代码 | **PRD → Feature Design → System Design → 代码** | | 人工介入 | ❌ | 启动时 | **每阶段确认** | | 流程完整性 | ❌ | 中等 | **完整工程流程** | | 团队协作 | 难共享 | 个人效率 | **团队知识共享** | | 上下文管理 | 单实例 | 单实例循环 | **子 Agent 自动调派** | | 迭代管理 | 混杂 | 任务列表 | **需求即项目，独立迭代** | | 确定性 | ❌ | 中等 | **高（逐级披露）** | --- ## 快速开始 ### 前置条件 - Node.js >= 16.0.0 - 支持的 IDE：Qoder（默认）、Cursor、Claude Code > **注意**：Cursor 和 Claude Code 的适配尚未在实际 IDE 环境中测试（代码层面已实现并通过 E2E 验证，但未在真实 Cursor/Claude Code 中实测）。 ### 1. 安装 SpecCrew ```bash npm install -g speccrew ``` ### 2. 初始化项目进入你的项目根目录，运行初始化命令： ```bash cd /path/to/your-project # 默认使用 Qoder speccrew init # 或指定 IDE speccrew init --ide qoder speccrew init --ide cursor speccrew init --ide claude ``` 初始化完成后，项目中会生成： - `.qoder/agents/` / `.cursor/agents/` / `.claude/agents/` — 7 个 Agent 角色定义 - `.qoder/skills/` / `.cursor/skills/` / `.claude/skills/` — 30+ 个 Skill 工作流 - `speccrew-workspace/` — 工作区（迭代目录、知识库、文档模板） - `.speccrewrc` — SpecCrew 配置文件后续如需更新指定 IDE 的 Agents 和 Skills： ```bash speccrew update --ide cursor speccrew update --ide claude ``` ### 3. 开始开发流程按照标准工程流程逐步推进： 1. **PRD**：由产品经理 Agent 分析需求，生成产品需求文档 2. **Feature Design**：由功能设计师 Agent 生成功能设计文档 + API 契约 3. **System Design**：由系统设计师 Agent 按端（前端/后端/移动端/桌面端）生成系统设计文档 4. **Dev**：由系统开发者 Agent 按端并行实现开发 5. **System Test**：由测试管理员 Agent 协调三阶段测试（用例设计 → 代码生成 → 执行报告） 6. **Archive**：归档迭代 > 每个阶段产出物需人工确认后方可进入下一阶段。 ### 4. 更新 SpecCrew 当 SpecCrew 发布新版本时，需要两步完成更新： ```bash # Step 1: 更新全局 CLI 工具到最新版本 npm install -g speccrew@latest # Step 2: 同步项目中的 Agents 和 Skills 到最新版本 cd /path/to/your-project speccrew update ``` > **注意**：`npm install -g speccrew@latest` 更新的是 CLI 工具本身，`speccrew update` 更新的是项目中的 Agent 和 Skill 定义文件。两步都需要执行才能完成完整更新。 ### 5. 其他 CLI 命令 ```bash speccrew list # 列出已安装的 agents 和 skills speccrew doctor # 诊断环境和安装状态 speccrew update # 更新 agents 和 skills 到最新版本 speccrew uninstall # 卸载 SpecCrew（--all 同时删除工作区） ``` 📖 **详细使用指南**：安装完成后，查看 [快速开始文档](docs/GETTING-STARTED.md) 了解完整的工作流程和各 Agent 对话指南。 --- ## 目录结构 ``` your-project/ ├── .qoder/ # IDE 配置目录（Qoder 示例） │ ├── agents/ # 7 个角色 Agent │ │ ├── speccrew-team-leader.md # 团队领导：全局调度与迭代管理 │ │ ├── speccrew-product-manager.md # 产品经理：需求分析与 PRD │ │ ├── speccrew-feature-designer.md # 功能设计师：Feature Design + API 契约 │ │ ├── speccrew-system-designer.md # 系统设计师：按端生成系统设计 │ │ ├── speccrew-system-developer.md # 系统开发者：按端并行开发 │ │ ├── speccrew-test-manager.md # 测试管理员：三阶段测试协调 │ │ └── speccrew-task-worker.md # 任务工人：并行子任务执行 │ └── skills/ # 38 个 Skill（按职能分组） │ ├── speccrew-pm-*/ # 产品管理（需求分析、需求评估） │ ├── speccrew-fd-*/ # 功能设计（Feature Design、API 契约） │ ├── speccrew-sd-*/ # 系统设计（前端/后端/移动端/桌面端） │ ├── speccrew-dev-*/ # 开发实现（前端/后端/移动端/桌面端） │ ├── speccrew-test-*/ # 测试（用例设计/代码生成/执行报告） │ ├── speccrew-knowledge-bizs-*/ # 业务知识库（API分析/UI分析/模块分类等） │ ├── speccrew-knowledge-techs-*/ # 技术知识库（技术栈生成/规约/索引等） │ ├── speccrew-knowledge-graph-*/ # 知识图谱（读写查询） │ └── speccrew-*/ # 工具类（诊断/时间戳/工作流等） │ └── speccrew-workspace/ # 工作区（初始化时生成） ├── docs/ # 管理性文档 │ ├── configs/ # 配置文件（平台映射、技术栈映射等） │ ├── rules/ # 规则配置 │ └── solutions/ # 解决方案文档 │ ├── iterations/ # 迭代项目（动态生成） │ └── {序号}-{类型}-{名称}/ │ ├── 00.docs/ # 原始需求文档 │ ├── 01.product-requirement/ # 产品需求文档 │ ├── 02.feature-design/ # 功能设计 │ ├── 03.system-design/ # 系统设计 │ ├── 04.development/ # 开发阶段 │ ├── 05.system-test/ # 系统测试 │ └── 06.delivery/ # 交付阶段 │ ├── iteration-archives/ # 迭代归档 │ └── knowledges/ # 知识库 ├── base/ # 基础/元数据 │ ├── diagnosis-reports/ # 诊断报告 │ ├── sync-state/ # 同步状态 │ └── tech-debts/ # 技术债 ├── bizs/ # 业务知识 │ └── {platform-type}/{module-name}/ └── techs/ # 技术知识 └── {platform-id}/ ``` --- ## 核心设计原则 1. **规范驱动**：先写规范，再由规范"长出"代码 2. **逐级披露**：Agent 从最小入口开始，按需获取信息 3. **人工确认**：每阶段产出需人工确认，避免 AI 跑偏 4. **上下文隔离**：大任务拆分为小粒度、上下文隔离的子任务 5. **子 Agent 协作**：复杂任务自动调派子 Agent，避免单 Agent 上下文膨胀 6. **快速迭代**：每个需求作为独立项目，快速交付、快速验证 7. **知识共享**：所有配置与源码一起 Git 管控 --- ## 适用场景 ### ✅ 推荐使用 - 需要规范流程的中大型项目 - 团队协作的软件开发 - 遗留项目的工程化改造 - 需要长期维护的产品 ### ❌ 不太适合 - 个人快速原型验证 - 探索性、需求极不确定的项目 - 一次性脚本或工具 --- --- ## 更多信息 - **Agent 知识地图**: [speccrew-workspace/docs/agent-knowledge-map.md](./speccrew-workspace/docs/agent-knowledge-map.md) - **npm**: https://www.npmjs.com/package/speccrew - **GitHub**: https://github.com/charlesmu99/speccrew - **Gitee**: https://gitee.com/amutek/speccrew - **Qoder IDE**: https://qoder.com/ --- > **SpecCrew 不是取代开发者，而是自动化那些枯燥的部分，让团队能专注于更有价值的工作。**