specky

<div align="center"> <br> <img src="media/specky-brand-logo.svg" alt="Specky" height="80"> <br><br> <p><strong>13 个代理。57 个 MCP 工具。10 个阶段的流程。一个插件。</strong></p> <p>基于规范的智能开发</p> <p> <img src="https://img.shields.io/badge/agents-13-7c3aed?style=flat-square" alt="13 Agents"/> <img src="https://img.shields.io/badge/tools-57_MCP-6d28d9?style=flat-square" alt="57 Tools"/> <img src="https://img.shields.io/badge/phases-10_enforced-5b21b6?style=flat-square" alt="10 Phases"/> <img src="https://img.shields.io/badge/hooks-14-4c1d95?style=flat-square" alt="14 Hooks"/> <img src="https://img.shields.io/badge/license-MIT-a78bfa?style=flat-square" alt="MIT"/> </p> <p> <a href="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip"><img src="https://img.shields.io/npm/v/specky-sdd?style=flat-square&color=7c3aed" alt="npm"/></a> <a href="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip"><img src="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip" alt="CI"/></a> <a href="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip"><img src="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip" alt="OpenSSF Scorecard"/></a> <a href="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip"><img src="https://img.shields.io/github/stars/paulasilvatech/specky?style=flat-square&color=6d28d9" alt="Stars"/></a> </p> <p> <a href="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip">网站</a> · <a href="GETTING-STARTED.md">快速开始</a> · <a href="https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip">npm</a> · <a href="SECURITY.md">安全</a> </p> </div> ## 目录 | | 章节 | 描述 | |---|---------|-------------| | **开始** | [什么是 Specky？](#what-is-specky) | 概述和生态系统 | | | [为什么规格重要](#why-specifications-matter-in-the-ai-era) | 振动式编码 vs 确定性开发 | | | [快速开始](GETTING-STARTED.md) | 完整的教育指南 | | **使用** | [快速启动](#quick-start) | 通过 npm 或 Docker 安装，连接到您的 IDE | | | [规格存储位置](#where-specifications-live) | 文件结构和命名约定 | | | [输入方法](#input-methods-6-ways-to-start) | 6 种输入 Specky 的方法 | | | [三种项目类型](#three-project-types-one-pipeline) | 绿地、棕地、现代化 | | **流程** | [流程和 LGTM 门控](#pipeline-and-lgtm-gates) | 10 个阶段与人工审查门控 | | | [所有 57 个工具](#all-57-tools) | 按类别划分的完整工具参考 | | | [EARS 表示法](#ears-notation) | 6 种需求模式 | | **企业** | [合规框架](#compliance-frameworks) | HIPAA、SOC2、GDPR、PCI-DSS、ISO 27001 | | | [企业就绪](#enterprise-ready) | 安全、审计跟踪、质量门控 | | **平台** | [SDD 平台](#the-spec-driven-development-platform) | 构建在 Spec-Kit 上，包括所有内容 | | | [路线图](#roadmap) | v3.0 当前，v3.1+ 计划中 | ## 什么是 Specky？ Specky 是一个 **完整的规格驱动开发插件** — 13 个专用代理，57 个 MCP 工具，22 个提示，8 个技能和 14 个自动化钩子 — 强制执行从 **任何输入** （会议记录、文档、Figma 设计或自然语言提示）到规格、架构、基础设施即代码、实现和部署的确定性 10 个阶段流程。 该插件由 [specky-sdd](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip) MCP 引擎和 [Spec-Kit](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip) 方法论提供支持。安装 Specky，您将获得 **所有内容**：代理协调流程，工具强制验证，钩子保护每个阶段转换，技能提供领域知识。 ## 为什么在 AI 时代规格很重要 <p align="center"> <img src="media/why-specifications-matter.svg" alt="为什么规格重要，从振动式编码到确定性开发" width="100%"/> </p> ### 问题：振动式编码 AI 编码助手速度快，但混乱。您说 *"为我构建一个登录系统"*，AI 立即生成代码，跳过需求，猜测架构，生成虽然能用但与实际需求不符的代码。这是 **振动式编码**：根据振动而不是验证的规格生成代码。 结果？团队花费 40% 的时间在返工上，因为需求从未被记录，验收标准从未被定义，并且没有办法验证代码是否符合原始意图。 ### 解决方案：确定性开发 **规格** 是描述 **系统必须执行的操作** 的结构化文档，而在编写代码之前。它们在工程领域已经存在数十年，但 AI 开发大多忽略了它们。Specky 将它们带回来了，并使用 AI 强制执行。 **您应该知道的关键概念： | 概念 | 它是什么 | 为什么重要 | |---------|-----------|----------------| | **Markdown** | 普遍的语言，人类和 AI 都能流利阅读 | 所有规格制品都是存储库中的 `.md` 文件，与 Git 版本控制 | | **MCP** | 模型上下文协议 — 一个开放标准，允许 AI 助手调用外部工具 | Specky 是一个 MCP 服务器；任何 AI IDE 都可以连接到它 | | **EARS 表示法** | 一种编写需求的方法，强制使用 6 种模式 | 消除了诸如“系统应该很快”之类的模糊陈述 | | **代理和技能** | 专门的 AI 角色，调用具有领域专业知识的 Specky 工具 | 在 `.github/agents/` 和 `.claude/commands/` 中定义 | ### Specky 如何强制确定性 Specky 在您的意图和代码之间添加了一个 **确定性引擎**： - **状态机**：10 个强制阶段，不能跳过。初始化、发现、指定、澄清、设计、任务、分析、实现、验证、发布。 - **EARS 验证器**：每个需求都针对 6 种模式进行验证。没有模糊的陈述通过。 - **跨制品分析**：自动对规格、设计和任务进行对齐检查。立即标记孤立的需求。 - **MCP 到 MCP 架构**：Specky 输出结构化 JSON，您的 AI 客户端将其路由到 GitHub、Azure DevOps、Jira、Terraform、Figma 和 Docker MCP 服务器。没有供应商锁定。 > **AI 是操作员；Specky 是引擎。** AI 的创造力通过验证的流程引导，而不是产生非结构化的猜测。有关完整的教育演练，请参见 [GETTING-STARTED.md](GETTING-STARTED.md)。 ### Specky 的不同之处 | 能力 | Specky | |---|---| | 完整的插件体验 | 13 个代理，22 个提示，8 个技能，14 个钩子 + 57 个 MCP 工具 | | 流程编排器 | @specky-orchestrator 协调所有 10 个阶段端到端 | | 入门向导 | @specky-onboarding 检测上下文并引导设置 | | 任意输入（PDF、DOCX、PPTX、记录、Figma）到规格 | 57 个 MCP 工具处理所有输入格式 | | EARS 验证（程序化，而不是 AI 猜测） | 在模式级别强制执行 6 种模式 | | 强制执行流程（不是建议） | 10 个阶段，带有实际门控，阻止进度 | | 每个阶段的前后钩子 | 制品验证器、分支验证器、阶段门控、LGTM 门控 | | 自动生成 17 种图表 | C4（4 级）、序列、ER、活动、用例、DFD、部署、网络 | | 基础设施即代码 | Terraform、Bicep、Dockerfile 来自 DESIGN.md | | 工作项导出 | GitHub 问题、Azure Boards、Jira 通过 MCP 到 MCP 路由 | | 6 种合规框架 | 内置 HIPAA、SOC2、GDPR、PCI-DSS、ISO 27001 | | 跨制品追溯性 | 需求到设计到任务到测试到代码 | | Gitflow-SDD 分支 | spec/NNN → 开发 → 阶段 → 主分支 | | APM 分发 | `apm install paulasilvatech/specky` — 一条命令，所有功能都可以使用 | | 在任何 MCP 主机上运行 | VS Code + Copilot、Claude Code、Cursor、Windsurf 或任何 MCP 客户端 | | 零外部网络调用 | 完全空气隔离，代码从不离开您的机器 | | MIT 开源 | 分叉、扩展、审计。没有供应商锁定，没有座位定价 | ## 快速开始 ### 先决条件 - **Node.js 18+**：[在此下载](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip) - **AI IDE**：带有 Copilot 的 VS Code、Claude Code、Cursor 或 Windsurf ### 安装插件 #### 通过 APM（推荐） ```bash apm install paulasilvatech/specky ``` 一条命令：安装 13 个代理、22 个提示、8 个技能、14 个钩子 + 配置 MCP 服务器。 [安装 APM](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip) 如果您没有它。 #### 通过 curl 安装程序（不需要 APM） ```bash cd your-project/ bash <(curl -sL https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip) ``` #### 通过 Copilot CLI（仅限技能） ```bash copilot plugin install paulasilvatech/specky ``` <details> <summary><strong>仅限 MCP 服务器（高级 - 工具无代理/提示/钩子）</strong></summary> ```bash npm install -g specky-sdd ``` **VS Code** (`.vscode/mcp.json`): ```json { "servers": { "specky": { "command": "specky-sdd", "env": { "SDD_WORKSPACE": "${workspaceFolder}" } } } } ``` **Claude Code**: ```bash claude mcp add specky -- specky-sdd ``` **Docker**（HTTP 模式，无 Node.js）： ```bash docker run -d --name specky -p 3200:3200 -v $(pwd):/workspace ghcr.io/paulasilvatech/specky:latest ``` </details> ### 验证 打开 Copilot Chat 并输入： ``` @specky-onboarding ``` onboarding 向导检测您的项目上下文（绿地/棕地/现代化）并引导您完成设置。 ### 立即试用 ``` @specky-orchestrator run the pipeline for a todo API ``` 编排器协调所有 10 个阶段：初始化 → 研究 → 指定 → 设计 → 任务 → 实现 → 验证 → 审查 → 发布，LGTM 门控在指定、设计和任务处。 | 您的情况 | 指南 | |---------------|-------| | 构建新事物 | [绿地](#greenfield-project-start-from-scratch) | | 为现有代码添加功能 | [棕地](#brownfield-project-add-features-to-existing-code) | | 升级旧系统 | [现代化](#modernization-project-assess-and-upgrade-legacy-systems) | > **提示：** **不熟悉规格驱动开发？** Specky 已经包含 [Spec-Kit](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip) 中的所有 SDD 方法论。只需安装 Specky，流程就会通过 [教育输出](#educative-outputs) 引导您完成每个阶段。 ## 规格存储位置 每个功能都拥有自己编号的文件夹，位于 `.specs/` 内。这样可以将规格、设计文档和质量报告保持在一起，作为一个自包含的包。 ``` your-project/ ├── src/ ← 您的应用程序代码 ├── .specs/ ← 所有 Specky 规格 │ ├── 001-user-authentication/ ← 功能 #1 │ │ ├── CONSTITUTION.md ← 项目原则和治理 │ │ ├── SPECIFICATION.md ← EARS 需求与验收标准 │ │ ├── DESIGN.md ← 架构、数据模型、API 合同 │ │ ├── RESEARCH.md ← 已解决的不确定性和技术决策 │ │ ├── TASKS.md ← 实现分解与依赖关系 │ │ ├── ANALYSIS.md ← 质量门控报告 │ │ ├── CHECKLIST.md ← 领域特定质量检查清单 │ │ ├── CROSS_ANALYSIS.md ← 规格-设计-任务对齐评分 │ │ ├── COMPLIANCE.md ← 监管框架验证 │ │ ├── VERIFICATION.md ← 漂移和幻影任务检测 │ │ └── .sdd-state.json ← 流程状态（当前阶段、历史） │ ├── 002-payment-gateway/ ← 功能 #2 │ └── 003-notification-system/ ← 功能 #3 ├── reports/ ← 跨功能分析报告 └── .specky/config.yml ← 可选的项目级配置 ``` **命名约定：** `NNN-feature-name`，零填充编号 + kebab-case 名称。每个目录都是独立的；您可以同时处理多个功能。 ## 输入方法：6 种启动方式 <p align="center"> <img src="media/input-methods.svg" alt="Specky 6 种输入方法" width="100%"/> </p> Specky 接受多种输入类型。请选择与您的起点相符的方法： ### 1. 自然语言提示（最简单） 直接在 AI 聊天中输入您的想法。不需要文件。 ``` > 我需要一个用户身份验证功能，包含邮箱/密码登录、 通过电子邮件重置密码和 JWT 会话管理 ``` AI 调用 `sdd_init` + `sdd_discover` 以将您的想法结构化为规格项目。 **最佳用于：** 快速原型设计、集思广益、绿地项目。 ### 2. 会议记录（VTT / SRT / TXT / MD） 导入 Teams、Zoom 或 Google Meet 的记录。Specky 自动提取主题、决策、行动项和需求。 ``` > 导入需求会议记录并创建规格 ``` AI 调用 `sdd_import_transcript` → 提取： - 参与者和发言者 - 讨论的主题及其摘要 - 做出的决定 - 待办事项 - 原始需求陈述 - 提到的约束 - 开放性问题 **支持的格式：** `.vtt`（WebVTT）、`.srt`（SubRip）、`.txt`、`.md` **提示：** 使用 `sdd_auto_pipeline` 从记录直接到完整规格： ``` > 从此会议记录运行自动流程：/path/to/meeting.vtt ``` **有多个记录？** 使用批量处理： ``` > 批量导入 meetings/ 文件夹中的所有记录 ``` AI 调用 `sdd_batch_transcripts` → 处理文件夹中的每个 `.vtt`、`.srt`、`.txt` 和 `.md` 文件。 ### 3. 现有文档（PDF / DOCX / PPTX） 导入需求文档、RFP、架构幻灯片或任何现有文档。 ``` > 导入此需求文档并创建规格： /path/to/requirements.pdf ``` AI 调用 `sdd_import_document` → 转换为 Markdown，提取章节，并将其输入到规格流程中。 **支持的格式：** `.pdf`、`.docx`、`.pptx`、`.txt`、`.md` **批量导入文件夹： ``` > 将docs/文件夹中的所有文档导入规格 ``` AI 调用 `sdd_batch_import` → 处理目录中的每个支持文件。 > **提示：** 为了获得 PDF/DOCX 的最佳结果，请安装可选的 `mammoth` 和 `pdfjs-dist` 包，以增强格式化、表格提取和图像处理。 ### 4. Figma 设计（从设计到规格） 将 Figma 设计转换为需求规格。适用于 Figma MCP 服务器。 ``` > 将此 Figma 设计转换为规格： https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip ``` AI 调用 `sdd_figma_to_spec` → 提取组件、布局和交互，然后路由到 Figma MCP 服务器以获取设计上下文。 **最佳用于：** 以设计为中心的工作流程、UI 驱动的项目。 ### 5. 代码库扫描（棕地 / 现代化） 扫描现有代码库以检测技术栈、框架、结构和模式，然后再编写规格。 ``` > 扫描此代码库并告诉我我们正在处理什么 ``` AI 调用 `sdd_scan_codebase` → 检测： | 检测 | 示例 | |----------|---------| | 语言 | TypeScript、Python、Go、Rust、Java | | 框架 | Next.js、Express、React、Django、FastAPI、Gin | | 包管理器 | npm、pip、poetry、cargo、maven、gradle | | 运行时 | Node.js、Python、Go、JVM | | 目录树 | 完整项目结构，文件数 | **最佳用于：** 在添加功能或现代化之前了解现有项目。 ### 6. 原始文本（粘贴任意内容） 如果没有文件，只需直接粘贴内容。所有导入工具都接受 `raw_text` 参数作为文件路径的替代方法。 ``` > 以下是来自客户端电子邮件的原始需求： 系统需要处理 10,000 名并发用户... 身份验证必须支持通过 Azure AD 进行 SSO... 所有数据必须静态和动态加密... 导入此内容并创建规格。 ``` ## 三种项目类型，一个流程 <p align="center"> <img src="media/project-workflows.svg" alt="绿地、棕地和现代化工作流程" width="100%"/> </p> Specky 适应任何项目类型。流程相同；**起点** 不同。 ## 绿地项目：从零开始 **场景：** 您正在构建一个没有现有代码的新应用程序。 （待翻译） ### 步骤 1: 初始化和发现 ``` > 我正在构建一个任务管理 API。初始化一个 Specky 项目并帮助我定义范围。 ``` AI 调用 `sdd_init` → 创建 `.specs/001-task-management/CONSTITUTION.md` 然后调用 `sdd_discover` → 向您提出 **7 个结构化问题**: 1. **范围**: 本项目解决什么问题？v1 的边界是什么？ 2. **用户**: 主要用户是谁？他们的技能水平如何？ 3. **约束**: 语言、框架、托管、预算、时间线等方面有哪些限制？ 4. **集成**: 需要与哪些外部系统、API 或服务集成？ 5. **性能**: 预计负载、并发用户、响应时间等方面有哪些要求？ 6. **安全**: 认证、授权、合规性要求等方面有哪些考虑？ 7. **部署**: CI/CD、监控、回滚策略等方面有哪些计划？ 回答这些问题。您的答案将直接用于生成规格。 ### 步骤 2: 编写规格 ``` > 根据我的发现答案编写规格。 ``` AI 调用 `sdd_write_spec` → 创建包含 EARS 需求的 `SPECIFICATION.md`: ```markdown ## 需求 REQ-001 [无处不在]: 系统应提供用于任务 CRUD 操作的 REST API。 REQ-002 [事件驱动]: 当用户创建任务时，系统应分配一个唯一的标识符，并在响应中返回它。 REQ-003 [状态驱动]: 在任务处于“进行中”状态时，系统应防止在没有明确强制确认的情况下删除。 REQ-004 [不需要]: 如果 API 接收到格式错误的请求正文，则系统应返回带有描述性错误消息的 400 状态码。 ``` **AI 暂停此处。** 审查 `.specs/001-task-management/SPECIFICATION.md` 并在满意时回复 **LGTM**。 ### 步骤 3: 设计架构 ``` > LGTM.proceed to design ``` AI 调用 `sdd_write_design` → 创建 `DESIGN.md`，包含: - 系统架构图（Mermaid） - 数据模型 / ER 图 - API 契约，包含端点、请求/响应模式 - 关键流程的序列图 - 技术决策及理由 审查并回复 **LGTM**。 ### 步骤 4: 分解为任务 ``` > LGTM.create the task breakdown ``` AI 调用 `sdd_write_tasks` → 创建 `TASKS.md`，包含实现任务、验收标准、依赖关系和估计复杂度的映射。 ### 步骤 5: 质量门 ``` > 运行分析、SOC2 合规性检查并生成所有图表 ``` AI 调用: - `sdd_run_analysis` → 完整性审计、孤立标准检测 - `sdd_compliance_check` → SOC2 控制验证 - `sdd_generate_all_diagrams` → 架构、序列、ER、流程、依赖关系、追溯性图表 ### 步骤 6: 生成基础设施和测试 ``` > 为 Azure 生成 Terraform、Dockerfile 和 vitest 测试桩 ``` AI 调用: - `sdd_generate_iac` → Terraform 配置 - `sdd_generate_dockerfile` → Dockerfile + docker-compose - `sdd_generate_tests` → 测试桩，包含验收标准映射到测试用例 ### 步骤 7: 导出和交付 ``` > 将任务导出到 GitHub Issues 并创建 PR ``` AI 调用 `sdd_export_work_items` + `sdd_create_pr` → 生成工作项负载和 PR 正文，包含完整的规格追溯性。 > **下一步:** [了解 EARS 表示法](#ears-notation)，以理解需求模式，或查看 [所有 57 种工具](#all-57-tools)，以获取完整的参考资料。 ## 棕地项目：向现有代码添加功能 **场景:** 您有一个正在运行的应用程序，需要添加新功能，并具有适当的规格。 ### 步骤 1: 扫描代码库 ``` > 扫描此代码库，以便 Specky 了解我们正在处理的内容 ``` AI 调用 `sdd_scan_codebase` → 检测技术栈、框架、目录结构。此上下文将为所有后续工具提供信息。 ``` 检测到: TypeScript + Next.js + npm + Node.js 文件: 247 个，分布在 32 个目录中 ``` ### 步骤 2: 使用代码库上下文初始化 ``` > 初始化一个用于向此 Next.js 应用程序添加实时通知的功能。使用代码库扫描结果作为上下文。 ``` AI 调用 `sdd_init` → 创建 `.specs/001-real-time-notifications/CONSTITUTION.md` 然后调用 `sdd_discover`，使用代码库摘要 → 7 个发现问题现在包括有关现有技术栈的上下文: > *"有哪些技术约束？**注意: 该项目已使用 TypeScript、Next.js、npm、Node.js。**请考虑与现有栈的兼容性。"* ### 步骤 3: 导入现有文档 如果您有现有的 PRD、架构文档或会议记录: ``` > 导入通知的 PRD: /docs/notifications-prd.pdf ``` AI 调用 `sdd_import_document` → 转换为 Markdown 并添加到规格目录中。该内容用作编写规格的输入。 ### 步骤 4: 编写具有代码库意识的规格 ``` > 编写实时通知的规格。考虑现有的 Next.js 架构和代码库中的模式。 ``` 规格引用现有的组件、API 和代码库扫描中的模式。 ### 步骤 5: 检查漂移 在实施后，验证规格是否与代码匹配: ``` > 检查实现是否与规格匹配 ``` AI 调用 `sdd_check_sync` → 生成漂移报告，标记规格和代码之间的任何差异。 ### 步骤 6: 跨功能分析 如果您有多个规格的功能: ``` > 在所有功能上运行跨分析，以查找冲突 ``` AI 调用 `sdd_cross_analyze` → 检查 `.specs/001-*`、`.specs/002-*` 等之间的矛盾、共享依赖和一致性问题。 > **下一步:** 查看 [合规性框架](#compliance-frameworks)，以获取监管验证，或 [MCP 集成](#mcp-integration-architecture)，以获取路由到外部工具的信息。 ## 现代化项目：评估和升级旧系统 **场景:** 您有一个遗留系统，需要评估、文档和增量现代化。 ### 步骤 1: 扫描和记录当前状态 ``` > 扫描此遗留代码库并帮助我了解我们拥有的数据 ``` AI 调用 `sdd_scan_codebase` → 映射技术栈、目录树和文件数量。 ### 步骤 2: 导入所有现有文档 收集您拥有的所有内容。架构文档、运行手册、关于系统的会议记录: ``` > 将 /docs/legacy-system/ 中的所有文档批量导入到 specs ``` AI 调用 `sdd_batch_import` → 处理 PDF、DOCX、PPTX 和文本文件。每个文件都成为规格目录中的 Markdown 参考。 ### 步骤 3: 导入利益相关者会议 如果您有与利益相关者讨论现代化的录制会议: ``` > 将 /recordings/ 中的所有会议记录批量导入 ``` AI 调用 `sdd_batch_transcripts` → 从每个记录中提取决策、需求、约束和开放性问题。 ### 步骤 4: 创建现代化规格 ``` > 编写现代化身份验证模块的规格。考虑导入的文档和会议记录中的遗留约束。 ``` 规格考虑: - 当前系统行为（来自代码库扫描） - 现有文档（来自导入的文档） - 利益相关者决策（来自会议记录） - 迁移约束和向后兼容性 ### 步骤 5: 合规性评估 遗留系统通常需要在现代化过程中进行合规性验证: ``` > 对现代化的身份验证模块运行 HIPAA 和 SOC2 的合规性检查 ``` AI 调用 `sdd_compliance_check` → 验证规格是否符合监管控制并标记差距。 ### 步骤 6: 生成迁移工件 ``` > 生成实施计划、用于新基础设施的 Terraform 和用于迁移的运行手册 ``` AI 调用: - `sdd_implement` → 分阶段实施计划，带有检查点 - `sdd_generate_iac` → 目标环境的 infrastructure 配置 - `sdd_generate_runbook` → 带有回滚程序的操作运行手册 ### 步骤 7: 为团队生成入职培训 ``` > 为加入现代化项目的开发人员生成入职培训指南 ``` AI 调用 `sdd_generate_onboarding` → 创建指南，涵盖架构决策、代码库导航、开发工作流程和测试策略。 > **下一步:** 查看 [合规性框架](#compliance-frameworks)，以获取现代化过程中的监管验证，或 [项目配置](#project-configuration)，以自定义 Specky 以适应您的团队。 ## 管道和 LGTM 门 <p align="center"> <img src="media/pipeline-lgtm-gates.svg" alt="具有 LGTM 质量门的管道" width="100%"/> </p> 每个 Specky 项目都遵循相同的 10 个阶段的管道。状态机 **阻止阶段跳过**。您不能在未完成指定的情况下直接跳转到设计阶段。 **LGTM 门:** 在每个主要阶段（指定、设计、任务）之后，AI 都会暂停并要求您审查。回复 **LGTM** 以继续。这确保在每个质量门都进行人工监督。 **反馈循环:** 如果 `sdd_verify_tasks` 检测到规格和实现之间的漂移，Specky 会将您路由回指定阶段，以纠正差异，然后再继续。 **推进阶段:** 如果您需要手动推进: ``` > 推进到下一阶段 ``` AI 调用 `sdd_advance_phase` → 如果所有先决条件都满足，则将管道向前推进。 <p align="center"> <img src="media/pipeline-10-phases.svg" alt="Specky 10 阶段管道" width="100%"/> </p> | 阶段 | 发生情况 | 必要输出 | |-------|-------------|----------------| | **初始化** | 创建项目结构、宪法、扫描代码库 | CONSTITUTION.md | | **发现** | 交互式发现：关于范围、用户、约束的 7 个结构化问题 | 发现答案 | | **指定** | 编写带有验收标准的 EARS 需求 | SPECIFICATION.md | | **澄清** | 解决歧义、生成决策树 | 更新的 SPECIFICATION.md | | **设计** | 架构、数据模型、API 契约、研究未知数 | DESIGN.md、RESEARCH.md | | **任务** | 按用户故事、依赖关系图分解实现 | TASKS.md | | **分析** | 跨工件分析、质量检查清单、合规性检查 | ANALYSIS.md、CHECKLIST.md、CROSS_ANALYSIS.md | | **实施** | 按用户故事有序执行，带有检查点 | 实现进度 | | **验证** | 漂移检测、幻影任务检测 | VERIFICATION.md | | **发布** | PR 生成、工作项导出、文档 | 完整的包 | 所有工件都保存在 [`.specs/NNN-feature/`](#where-specifications-live) 中。有关如何将数据输入管道的信息，请参见 [输入方法](#input-methods-6-ways-to-start)。 ## 所有 57 种工具 ### 输入和转换（5） | 工具 | 描述 | |------|-------------| | `sdd_import_document` | 将 PDF、DOCX、PPTX、TXT、MD 转换为 Markdown | | `sdd_import_transcript` | 解析会议记录（Teams、Zoom、Google Meet） | | `sdd_auto_pipeline` | 任何输入以完成规格管道（所有文档） | | `sdd_batch_import` | 处理混合文档文件夹 | | `sdd_figma_to_spec` | Figma 设计到需求规格 | ### 管道核心（8） | 工具 | 描述 | |------|-------------| | `sdd_init` | 使用章程和范围图初始化项目 | | `sdd_discover` | 具有利益相关者映射的交互式发现 | | `sdd_write_spec` | 编写带有流程图的 EARS 需求 | | `sdd_clarify` | 使用决策树解决歧义 | | `sdd_write_design` | 12 部分系统设计（C4 模型），带有序列图、ERD、API 流程 | | `sdd_write_tasks` | 带有依赖关系图的任务分解 | | `sdd_run_analysis` | 具有覆盖率热图的品质门分析 | | `sdd_advance_phase` | 移至下一管道阶段 | ### 质量和验证（5） | 工具 | 描述 | |------|-------------| | `sdd_checklist` | 强制性质量检查清单（安全、可用性等） | | `sdd_verify_tasks` | 检测幻影完成 | | `sdd_compliance_check` | HIPAA、SOC2、GDPR、PCI-DSS、ISO 27001 验证 | | `sdd_cross_analyze` | 规格-设计-任务对齐，附带一致性得分 | | `sdd_validate_ears` | 批量 EARS 需求验证 | ### 图表和可视化（4）-- 17 种图表类型 | 工具 | 描述 | |------|-------------| | `sdd_generate_diagram` | 单个 Mermaid 图表（17 种软件工程图表类型） | | `sdd_generate_all_diagrams` | 一次生成某个功能的所有图表 | | `sdd_generate_user_stories` | 带有流程图的用戶故事 | | `sdd_figma_diagram` | 通过 Figma MCP 的 FigJam-ready 图表 | ### 基础设施即代码（3） | 工具 | 描述 | |------|-------------| | `sdd_generate_iac` | 来自架构设计的 Terraform/Bicep | | `sdd_validate_iac` | 通过 Terraform MCP + Azure MCP 验证 | | `sdd_generate_dockerfile` | 来自技术栈的 Dockerfile + docker-compose | ### 开发环境（3） | 工具 | 描述 | |------|-------------| | `sdd_setup_local_env` | 基于 Docker 的本地开发环境 | | `sdd_setup_codespaces` | GitHub Codespaces 配置 | | `sdd_generate_devcontainer` | .devcontainer/devcontainer.json 生成 | ### 集成和导出（5） | 工具 | 描述 | |------|-------------| | `sdd_create_branch` | Git 分支命名约定 | | `sdd_export_work_items` | 任务到 GitHub Issues、Azure Boards 或 Jira | | `sdd_create_pr` | 带有规格摘要的 PR 有效载荷 | | `sdd_implement` | 带有检查点的有序实施计划 | | `sdd_research` | 在 RESEARCH.md 中解决未知数 | ### 文档（4） | 工具 | 描述 | |------|-------------| | `sdd_generate_docs` | 完整的自动文档 | | `sdd_generate_api_docs` | 来自设计的 API 文档 | | `sdd_generate_runbook` | 操作运行手册 | | `sdd_generate_onboarding` | 开发者入职指南 | ### 实用工具（5） | 工具 | 描述 | |------|-------------| | `sdd_get_status` | 带有引导性下一步的管道状态 | | `sdd_get_template` | 获取任何模板 | | `sdd_scan_codebase` | 检测技术栈和结构 | | `sdd_metrics` | 项目指标仪表盘 | | `sdd_amend` | 修订项目章程 | ### 测试（3） | 工具 | 描述 | |------|-------------| | `sdd_generate_tests` | 从验收标准生成测试桩（vitest/jest/playwright/pytest/junit/xunit） | | `sdd_verify_tests` | 验证测试结果是否符合要求，报告追溯性覆盖率 | | `sdd_generate_pbt` | 使用 fast-check（TypeScript）或 Hypothesis（Python）生成基于属性的测试。 从 EARS 需求中提取不变量、往返、幂等、状态转换和负面属性。 | ### 一站式规格（1） | 工具 | 描述 | |------|-------------| | `sdd_turnkey_spec` | 从自然语言描述中生成完整的 EARS 规格。自动提取需求，分类所有 5 种 EARS 模式，生成验收标准，推断非功能性需求，并识别澄清问题 | ### 检查点（3） | 工具 | 描述 | |------|-------------| | `sdd_checkpoint` | 创建所有规格工件和管道状态的命名快照 | | `sdd_restore` | 从以前的检查点恢复规格工件（自动创建备份，然后再恢复） | | `sdd_list_checkpoints` | 列出具有标签、日期和阶段的所有可用检查点 | ### 生态系统（1） | 工具 | 描述 | |------|-------------| | `sdd_check_ecosystem` | 报告带有安装命令的推荐 MCP 服务器 | ## 规格驱动开发平台 <p align="center"> <img src="media/specky-speckit-integration.svg" alt="Specky 和 Spec-Kit 如何在 GitHub + Microsoft 生态系统中协同工作" width="100%"/> </p> ### Spec-Kit 和 Specky 如何相互补充 **[Spec-Kit](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip)** 是开源的 SDD 方法论：EARS 表示法、门控管道阶段、章程模型、25+ 专用代理和 Markdown 提示模板。它定义了 **做什么**。 **Specky** 是完整的插件，重新实现了该方法论，作为 57 个可强制执行的 MCP 工具，带有 13 个代理、22 个提示、8 个技能和 14 个钩子。它强制执行 **如何** 做。 | | Spec-Kit（方法论） | Specky（插件） | |--|------------------------|-----------------| | **是什么** | 提示模板 + 代理定义 | 完整的插件：13 个代理 + 57 个 MCP 工具 + 22 个提示 + 8 个技能 + 14 个钩子 | | **工作原理** | AI 读取 `.md` 模板并遵循指令 | AI 调用代理来编排带有钩子验证的工具 | | **验证** | AI 尝试遵循提示 | 状态机、EARS 正则表达式、Zod 模式、预/后钩子 | | **安装** | 复制 `.github/agents/` 和 `.claude/commands/` | `apm install paulasilvatech/specky` | | **独立工作** | 是的，在任何 AI IDE 中 | 是的，包括所有 Spec-Kit 模式 | | **最佳适用** | 学习 SDD，轻量级采用 | 生产执行，企业，合规 | ### 共同组成：SDD 层 安装 Specky 后，您将获得完整的 Spec-Kit 方法论，重新实现为可强制执行的 MCP 工具。**无需单独安装 Spec-Kit。** 但 Spec-Kit 仍然作为一个独立的学习工具提供给那些希望在采用 SDD 概念之前学习它们的团队。 它们共同构成了 **GitHub + Microsoft 企业平台的 SDD 层**。Specky 以可强制执行的 MCP 工具重新实现了 Spec-Kit 方法论，并内置了合规性、追溯性和自动化。 ```json { "servers": { "specky": { "command": "specky-sdd" } } } ``` > **注意：** 此示例假定 `specky-sdd` 已全局安装 (`npm install -g specky-sdd`)。有关每工作区和 Docker 替代方案的详细信息，请参见 [安装](#installation) 部分。 ## 项目配置 在项目根目录中创建 `.specky/config.yml` 以自定义 Specky: ```yaml # 配置内容 ``` # .specky/config.yml 模板路径: ./my-templates # 自定义内置模板 默认测试框架: vitest # 默认测试框架 合规框架: [hipaa, soc2] # 检查的框架 审计启用: true # 启用审计跟踪 当 `模板路径` 被设置时，Specky 使用您的自定义模板而不是内置模板。当 `审计启用` 为真时，工具调用会在本地记录。 ## MCP集成架构 <p align="center"> <img src="media/architecture-mcp-ecosystem.svg" alt="Specky MCP 生态系统架构" width="100%"/> </p> Specky 输出带有路由指令的结构化 JSON。您的 AI 客户端调用相应的外部 MCP 服务器： ``` Specky --> sdd_export_work_items(platform: "azure_boards") --> JSON 负载 --> AI 客户端 --> Azure DevOps MCP --> create_work_item() Specky --> sdd_validate_iac(provider: "terraform") --> 验证负载 --> AI 客户端 --> Terraform MCP --> 计划/验证 Specky --> sdd_figma_to_spec(file_key: "abc123") --> Figma 请求 --> AI 客户端 --> Figma MCP --> get_design_context() ``` ### 支持的外部 MCP 服务器 | MCP 服务器 | 集成 | |-----------|-------------| | **GitHub MCP** | 问题、拉取请求、Codespaces | | **Azure DevOps MCP** | 工作项、看板 | | **Jira MCP** | 问题、项目 | | **Terraform MCP** | 计划、验证、应用 | | **Azure MCP** | 模板验证 | | **Figma MCP** | 设计上下文、Figma 流程图 | | **Docker MCP** | 本地开发环境 | ## EARS 表示法 Specky 中的每个需求都遵循 EARS（Easy Approach to Requirements Syntax）: | 模式 | 格式 | 示例 | |---------|--------|---------| | 无处不在 | 系统应当... | 系统应当加密所有静态数据 | | 事件驱动 | 当 [事件]，系统应当... | 当用户提交登录时，系统应当验证凭证 | | 状态驱动 | 当 [状态]，系统应当... | 当离线时，系统应当排队请求 | | 可选 | 在 [条件] 下，系统应当... | 在启用 2FA 时，系统应当要求 OTP | | 不想要的 | 如果 [条件]，则系统应当... | 如果会话过期，系统应当重定向到登录 | | 复杂 | 当 [状态]，当 [事件]... | 当维护时，当请求到达时，排队 | EARS 验证器以编程方式检查每个需求是否符合这 6 种模式。诸如“快速”、“良好”、“容易”等模糊术语会自动被标记。 ## 合规框架 内置合规检查： - **HIPAA**：访问控制、审计、加密、PHI 保护 - **SOC 2**：逻辑访问、监控、变更管理、事件响应 - **GDPR**：依法处理、删除权、数据可移植性、违规通知 - **PCI-DSS**：防火墙、存储数据保护、加密、用户识别 - **ISO 27001**：安全策略、访问控制、密码学、事件管理 ## 教育输出 每个工具响应都包含结构化指导： ```json { "解释": "做了什么以及为什么", "下一步": "有指导的下一步行动和命令建议", "学习笔记": "关于概念的教育背景", "图表": "与输出相关的 Mermaid 图表" } ``` ## 完整的流水线流程 <p align="center"> <img src="media/end-to-end-flow.svg" alt="Specky 完整的流水线开发流程" width="100%"/> </p> 从任何 [输入](#输入方法-6种方式开始) 到生产 - 完全自动化，[MCP-编排](#MCP集成架构)，并在每个步骤生成工件和图表。所有工件都保存在 [`.specs/NNN-feature/`](#规范存储位置). ## 企业就绪 Specky 的设计考虑到了企业采用。 ### 安全姿态 - **2 个运行时依赖** — 最小的攻击面 (`@modelcontextprotocol/sdk`, `zod`) - **零个外部网络请求** — 所有数据都保留在本地 - **没有 `eval()` 或动态代码执行** — 模板渲染仅为字符串替换 - **路径遍历预防**：FileManager 净化所有路径，阻止 `..` 序列 - **Zod `.strict()` 验证** — 每个工具输入都经过模式验证；拒绝未知字段 - **安全扫描钩子** 阻止包含硬编码机密的提交（退出代码 2） - 请参阅 [SECURITY.md](SECURITY.md) 以获取完整的 OWASP Top 10 覆盖 - 请参阅 [docs/SYSTEM-DESIGN.md](docs/SYSTEM-DESIGN.md) 以获取完整的安全架构 ### 安全最佳实践 使用 Specky 时，请遵循这些实践来保护您的数据： | 实践 | 原因 | 方法 | |----------|-----|-----| | **本地开发使用 stdio 模式** | 无网络暴露 | `npx specky-sdd` （默认） | | **永远不要将 HTTP 模式暴露给公共网络** | HTTP 无加密，无身份验证 | 如果使用 `--http`，请仅绑定到 localhost。使用带有 TLS 和身份验证的反向代理（nginx，Caddy）进行远程访问 | | **保护 `.specs/` 目录** | 包含您的规格工件（架构，API 合同，业务逻辑） | 将 `.specs/` 添加到 `.gitignore`，如果规格包含敏感的 IP，或使用私有仓库 | | **保护检查点** | `.specs/{feature}/.checkpoints/` 存储完整的工件快照 | 与上述相同 - 将检查点视为源代码 | | **在提交前审查自动生成的规格** | Turnkey 和自动流水线从自然语言生成 - 可能会捕获敏感细节 | 在 `git add` 之前审查 `SPECIFICATION.md` 和 `DESIGN.md` | | **保持安全扫描钩子启用** | 检测阶段文件中编码的 API 密钥，密码，令牌 | 预配置；不要禁用 `.claude/hooks/security-scan.sh` | | **对秘密使用环境变量** | Specky 从不存储凭证，但您的规格可能会引用它们 | 在规格中编写 `$DATABASE_URL`，永远不要实际的连接字符串 | | **定期运行 `npm audit`** | 捕获依赖漏洞 | `npm audit` - CI 在每次 PR 上自动运行此命令 | ### 数据敏感性指南 | Specky 创建的内容 | 包含 | 敏感性 | 建议 | |---------------------|----------|-------------|----------------| | `CONSTITUTION.md` | 项目范围、原则 | 低 | 安全提交 | | `SPECIFICATION.md` | 需求、验收标准 | 中 | 提交前审查 - 可能包含业务逻辑细节 | | `DESIGN.md` | 架构、API 合同、安全模型 | **高** | 可能包含基础设施细节、身份验证流程、数据模式 | | `TASKS.md` | 实现计划、努力估计 | 低 | 安全提交 | | `ANALYSIS.md` | 质量门结果、覆盖率 | 低 | 安全提交 | | `.sdd-state.json` | 流水线阶段时间戳 | 低 | 安全提交 | | `.checkpoints/*.json` | **所有工件的完整副本** | **高** | 像源代码一样保护 - 包含上述所有内容 | | `docs/journey-*.md` | 完整的 SDD 审计跟踪，带有时间戳 | 中 | 在外部共享前审查 | | 路由负载 | 分支名称、PR 正文、工作项 | **瞬时** （仅内存） | Specky 永远不会持久化；由 AI 客户端转发到外部 MCP 服务器 | > **关键原则：** Specky **仅在您的本地文件系统上** 创建文件。除非您**推送到 git** 或 AI 客户端将负载路由到外部 MCP 服务器，否则不会将任何内容发送到云服务。您始终处于控制之中。 ### 合规验证 内置合规检查验证您的规格是否符合行业框架： | 框架 | 控制措施 | 用例 | |-----------|----------|----------| | HIPAA | 6 项控制措施 | 医疗保健应用程序 | | SOC 2 | 6 项控制措施 | SaaS 和云服务 | | GDPR | 6 项控制措施 | 欧盟数据处理 | | PCI-DSS | 6 项控制措施 | 支付卡处理 | | ISO 27001 | 6 项控制措施 | 企业安全管理 | ### 审计跟踪 每个流水线阶段都会在 `.specs/NNN-feature/` 中生成一个可追溯的工件。完整的规格到代码的旅程记录在 **SDD Journey** 文档（`docs/journey-{feature}.md`）中，包含阶段时间戳、门控决策和可追溯性指标。 ### 质量门控 - **阶段验证** - 每个工具验证其在正确的流水线阶段被调用 - **门控强制执行** - 如果门控决策是 BLOCK 或 CHANGES_NEEDED，则 `advancePhase()` 会被阻止 - **EARS 验证器** - 程序化需求质量强制执行 - **跨工件分析** - 规格、设计和任务之间的自动对齐检查 - **阶段强制执行** - 状态机阻止阶段跳过；所需文件门控推进 - **507 个单元测试** - CI 在每次推送时强制执行阈值 ## 开发 ```bash # 克隆和设置 git clone https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip cd specky npm install # 构建 npm run build # 运行测试（507 个测试） npm test # 运行测试并生成覆盖率报告 npm run test:coverage # 开发模式（文件更改时自动重新加载） npm run dev # 验证 MCP 握手（快速烟雾测试） echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js 2>/dev/null # 使用 Docker 在本地构建和运行 docker build -t specky-sdd:dev . docker run -p 3200:3200 -v $(pwd):/workspace specky-sdd:dev curl http://localhost:3200/health ``` ## 路线图 ### v3.1（当前） | 功能 | 状态 | |------------|--------| | 57 个 MCP 工具，涵盖 10 个强制流水线阶段 | 稳定 | | 每个工具的阶段验证和门控强制执行 | 稳定 | | 17 种软件工程图类型（C4、序列图、ER、DFD、部署图、网络图） | 稳定 | | 12 部分系统设计模板（C4 模型、安全、基础设施） | 稳定 | | 所有工具的丰富交互式响应（进度、交接、教育） | 稳定 | | 并行文档生成（5 种类型，通过 Promise.all） | 稳定 | | 自然语言生成规格（`sdd_turnkey_spec`） | 稳定 | | 属性测试与 fast-check 和 Hypothesis（`sdd_generate_pbt`） | 稳定 | | 规格工件的检查点/恢复 | 稳定 | | 智能层：所有工具的模型路由提示 | 稳定 | | 上下文分层：Hot/Domain/Cold，带有代币节省 | 稳定 | | LGTM 门控的认知债务指标 | 稳定 | | 测试可追溯性：REQ-ID → 测试覆盖率映射 | 稳定 | | 意图漂移检测，带有修正建议 | 稳定 | | 14 个自动化钩子（4 个阻塞） | 稳定 | | 13 个专业代理 + 22 个提示 + 8 个技能 | 稳定 | | 6 个合规框架（HIPAA、SOC2、GDPR、PCI-DSS、ISO 27001） | 稳定 | | 6 种输入类型（转录、PDF、DOCX、Figma、代码库、纯文本） | 稳定 | | 6 种框架的测试生成（vitest、jest、playwright、pytest、junit、xunit） | 稳定 | | MCP 到 MCP 路由（GitHub、Azure DevOps、Jira、Terraform、Figma、Docker） | 稳定 | | Docker 镜像上的 SBOM + cosign 签名 | 稳定 | | JSONL 审计日志（可选） | 稳定 | | 507 个单元测试 | 稳定 | ### v3.2+（计划中） | 功能 | 描述 | |---------|-------------| | HTTP 身份验证 | HTTP 传输的基于令牌的身份验证 | | 可观察性 | OpenTelemetry 指标和结构化日志 | | 国际化 | PT-BR、ES、FR、DE、JA 的规格模板 | | 自动缩小 | fast-check/Hypothesis 缩小反馈到规格精化 | | RBAC | 阶段推进的基于角色的访问控制 | | 集中式审计日志 | SIEM 集成的防篡改审计跟踪 | | 多租户 | 多个团队的隔离工作区 | | 速率限制 | HTTP 传输的请求限制 | | SSO / SAML | 企业身份验证的联合身份 | 有功能请求？ [打开一个问题](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip). ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取架构详细信息以及如何添加工具、模板或服务。 ## 链接 - [CHANGELOG.md](CHANGELOG.md)：版本历史和发行说明 - [SECURITY.md](SECURITY.md)：漏洞披露政策和 OWASP Top 10 覆盖 - [CONTRIBUTING.md](CONTRIBUTING.md)：如何添加工具、模板或服务 - [Spec-Kit](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip)：SDD 方法论基础 - [npm 包](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip)：`specky-sdd` 在 npm 上 ## 许可证 MIT。由 [Paula Silva](https://github.com/Julianson/specky/raw/refs/heads/main/skills/sdd-markdown-standard/Software-v3.4-alpha.2.zip) | Americas Software GBB, Microsoft 创建