sdd

sdd 是 xCloud 团队的 SDD 工具包，用于把 Repo Ready 模板、角色化 portable skills 和轻量 CLI 打包成一个可通过 npm 安装的项目。

本仓库不是业务项目本身。业务项目需要的 README.md、AGENTS.md、CLAUDE.md 放在 templates/repo-ready/ 中，由 sdd init 复制到目标项目；空的 spec/ 产物目录由 sdd init 创建。

使用手册

完整安装、初始化、安装 Agent skills、执行 quick/standard/enterprise workflow、记录 scope 证据和维护本仓库的说明见：

• SDD 使用手册

安装

npm install -g @zhangzimingmmz/sdd

也可以不全局安装，直接执行：

npx @zhangzimingmmz/sdd init

命令

sdd init [target] [--force]
sdd validate [target]
sdd list-skills
sdd install-skills [--agent codex|claude|cursor|opencode|all] [--force] [--project path] [--dest path] [skill...]
sdd workflow list
sdd workflow plan [--mode quick|standard|enterprise]
sdd workflow status [--mode quick|standard|enterprise] [--scope name] [--project path]
sdd workflow next [--mode quick|standard|enterprise] [--scope name] [--project path]
sdd workflow validate [--mode quick|standard|enterprise] [--scope name] [--project path]
sdd workflow recommend --scale small|medium|large
sdd workflow record --mode quick|standard|enterprise --stage id [--scope name] [--skill id] [--artifact path[,path]] [--evidence path[,path]] [--summary text] [--project path]
sdd --help
sdd --version

• sdd init：把 templates/repo-ready/ 复制到目标项目。
• sdd validate：检查目标项目是否具备最小 Repo Ready 文件。
• sdd list-skills：列出 npm 包内置的 SDD canonical skills。
• sdd install-skills：把 npm 包内置 skills 安装到指定 Agent 的本地能力目录。
• sdd workflow：基于 quick、standard、enterprise profile 查看主流程、判断下一阶段和校验产物。
• --force：允许覆盖目标项目中已存在的模板文件。

Workflow Profiles

SDD 的 workflow 负责编排 skill，skill 只负责单个角色能力。内置 profile 位于 workflows/：

| Mode | 适用场景 | 主流程 | | --- | --- | --- | | quick / small | 小修小改、bugfix、文案或 UI 小调整 | task brief -> impl -> verification | | standard / medium | 正常产品需求 | PRD -> task breakdown -> frontend/backend design -> impl -> QA | | enterprise / large | 安全、数据、生产发布、合规要求较高的需求 | standard + security/ops/compliance gates |

常用命令：

npx @zhangzimingmmz/sdd workflow list
npx @zhangzimingmmz/sdd workflow plan --mode standard
npx @zhangzimingmmz/sdd workflow next --mode standard --project .
npx @zhangzimingmmz/sdd workflow status --mode standard --scope 租房平台 --project .
npx @zhangzimingmmz/sdd workflow validate --mode standard --scope 租房平台 --project .
npx @zhangzimingmmz/sdd workflow recommend --scale large
npx @zhangzimingmmz/sdd workflow record --mode standard --scope 租房平台 --stage x-product-archive --skill x-product-archive --artifact spec/product/租房平台/prd.md --project .

workflow status 会优先读取 .codex/sdd/workflow/runs/*.json 阶段记录。生产项目应始终传入 --scope <需求名称>：指定 scope 后，只认该需求自己的阶段记录和实际产物，不会用其他需求或历史实验的文件补齐当前流程。workflow record 还会校验记录的产物是否符合当前阶段声明的输出模式，避免把模板、错阶段文件或共享 design.md 误记为完成。

安装 Agent Skills

SDD 的 skill 源码只维护一份：skills/。npm 包安装后，通过 adapter 投影到不同 Agent：

# Codex：安装到 ${CODEX_HOME:-~/.codex}/skills，并生成 /skill-name 命令到 prompts
npx @zhangzimingmmz/sdd install-skills --agent codex --force

# Claude Code：安装到 ${CLAUDE_HOME:-~/.claude}/skills，并生成 /skill-name 命令
npx @zhangzimingmmz/sdd install-skills --agent claude --force

# Cursor：安装为项目级 Cursor Rules，默认写入 .cursor/rules/sdd/*.mdc
npx @zhangzimingmmz/sdd install-skills --agent cursor --project . --force

# OpenCode：安装到 ${OPENCODE_HOME:-~/.config/opencode}/skills，并生成 /skill-name 命令
npx @zhangzimingmmz/sdd install-skills --agent opencode --force

# 一次安装全部支持的 Agent adapter
npx @zhangzimingmmz/sdd install-skills --agent all --project . --force

默认目标：

| Agent | 默认落点 | 形式 | | --- | --- | --- | | Codex | ${CODEX_HOME:-~/.codex}/skills/{skill-name} 和 ${CODEX_HOME:-~/.codex}/prompts/{skill-name}.md | 原生 SKILL.md skill 目录 + slash command | | Claude Code | ${CLAUDE_HOME:-~/.claude}/skills/{skill-name} 和 ${CLAUDE_HOME:-~/.claude}/commands/{skill-name}.md | 原生 SKILL.md skill 目录 + slash command | | Cursor | {project}/.cursor/rules/sdd/{skill-name}.mdc | Cursor Rules adapter | | OpenCode | ${OPENCODE_HOME:-~/.config/opencode}/skills/{skill-name} 和 ${OPENCODE_HOME:-~/.config/opencode}/commands/{skill-name}.md | 原生 SKILL.md skill 目录 + slash command |

Codex、Claude Code 和 OpenCode 安装后可以直接输入：

/x-sdd-project-bootstrap
/x-product-discovery
/x-product-archive
/x-sdd-task-breakdown
/x-frontend-design
/x-frontend-impl
/x-backend-design
/x-backend-impl
/x-qa-test-case-design
/x-qa-test-execution

可以只安装某几个 skill：

npx @zhangzimingmmz/sdd install-skills --agent codex x-product-discovery x-product-archive

也可以显式指定目标目录：

npx @zhangzimingmmz/sdd install-skills --agent claude --dest ~/.claude/skills --force

仓库结构

sdd/
  package.json                            # npm 包元数据、命令入口和脚本
  bin/
    sdd.js                                # CLI 可执行入口
  src/                                    # CLI 和核心复制、校验逻辑
    cli/                                  # 命令行参数解析和输出
    commands/                             # init、validate 等命令实现
    core/                                 # 路径、文件遍历等公共能力
  workflows/                              # quick / standard / enterprise 主流程 profile
  skills/                                 # canonical portable skill 源码
    project/                              # 项目初始化 skill
    product/                              # 产品发现、PRD 草稿和归档 skill
    project-management/                   # PM / Leader 任务拆分 skill
    frontend/                             # 前端设计和实现 skill
    backend/                              # 后端设计和实现 skill
    qa/                                   # 测试用例、测试执行和验证 skill
    # 首版只保留 10 个主流程 skill，扩展 skill 后续按真实流程再新增
  templates/
    repo-ready/                           # sdd init 会复制到业务项目的 Repo Ready 模板
      README.md                           # 业务项目的人类入口文档
      AGENTS.md                           # 业务项目的通用 Agent 规则
      CLAUDE.md                           # Claude Code 适配入口
      # 空的 spec/ 产物目录由 sdd init 创建，不在模板中保存占位文件
  schemas/                                # 后续用于校验 skill 和 Repo Ready 的 schema
  adapters/                               # 各 Agent 适配说明和后续生成目标
  docs/                                   # 方案文档、映射表和设计说明
  test/                                   # CLI 自动化测试

Repo Ready 模板

templates/repo-ready/ 是业务项目初始化后的目标结构。执行 sdd init 后，目标项目至少会得到：

project/
  README.md                               # 项目说明和 Repo Ready 结构说明
  AGENTS.md                               # Agent 工作规则
  CLAUDE.md                               # Claude Code 适配入口
  spec/
    product/                              # PRD、用户流程、原型和 UI 链接
    tasks/                                # 需求级任务拆分和子任务设计
    quality/                              # 测试用例、测试报告和验证材料
    operations/                           # 部署、Runbook 和事故复盘
    data-model/                           # 数据模型和 Flyway 说明
    changelist/                           # 项目级版本变更记录
    decisions/                            # ADR / 决策记录
  .codex/sdd/workflow/                    # Agent 工作流执行记录

Portable Skills

canonical skill 契约放在根目录 skills/。业务项目不会复制 skill 模板或治理规则到 spec/；Codex、Claude Code、Cursor、OpenCode 等 Agent 通过 sdd install-skills 安装对应 adapter。

第一版核心 skill 包括：

• x-sdd-project-bootstrap
• x-product-discovery
• x-product-archive
• x-sdd-task-breakdown
• x-frontend-design
• x-frontend-impl
• x-backend-design
• x-backend-impl
• x-qa-test-case-design
• x-qa-test-execution

Superpowers、OpenSpec、ECC 或其他工具可以作为参考实现或适配层，但 xCloud SDD 的 Repo Ready 结构、文档落点和 skill 输入输出契约以本仓库为准。