CodeBuddy 是否支持 SDD（Spec-Driven Development 规范驱动开发

CodeBuddy 三问题完整解答

1. 是否支持 SDD（Spec-Driven Development 规范驱动开发）

完全原生支持，分两套实现：

1. 内置 SpecKit / OpenSpec 标准SDD工作流
   CodeBuddy CLI / IDE 内置 /openspec、/speckit 系列斜杠命令，完整覆盖 SDD 全流程：需求提案 → 规范定义 → 技术设计 → 任务拆分 → 代码实现 → 归档验收。
   配套目录规范：openspec/changes/[变更名]/design.md 是SDD标准技术设计文件，自动识别加载。
2. opencode-sdd 插件增强
   npm 可安装 opencode-sdd 扩展SDD自动化，一键执行全链路自动开发 prd-auto-implement。

2. design.md：是什么、是否支持

定位：SDD流程专用技术设计文档

• 存放路径：openspec/changes/[feature]/design.md（OpenSpec/SDD标准目录）
• 作用：记录架构、接口、数据库、模块拆分、技术选型，是SDD强制环节文件
• CodeBuddy 自动读取同变更目录下的 design.md，生成代码时严格对齐设计约束，属于SDD流程内部文件，不是全局配置文件。
• 不建议直接放在项目根目录；仅SDD工作流使用，普通对话不会自动加载。

3. agents.md / CODEBUDDY.md：全局智能体配置文件

核心结论

1. 兼容 AGENTS.md（根目录） ，但官方主推 CODEBUDDY.md（优先级更高）
   • 项目根存在 CODEBUDDY.md → 优先加载，忽略 AGENTS.md
   • 无 CODEBUDDY.md 时，自动读取根目录 AGENTS.md
   • 用途：全局项目上下文、团队规范、默认Agent行为、构建命令、架构总览，全局永久生效，所有对话自动加载。
2. 自定义子Agent不是 AGENTS.md，是独立md文件
   细分角色（代码评审、架构师、测试）存放在 .codebuddy/agents/*.md，带YAML frontmatter，和根目录AGENTS.md完全无关。

三者区分速查表

文件	作用域	使用场景	CodeBuddy支持状态
design.md	单次SDD变更	功能技术设计、架构方案	SDD流程内置，仅openspec目录识别
AGENTS.md	项目全局	基础项目记忆、全局AI规则	兼容遗留，低优先级
CODEBUDDY.md	项目全局	官方标准项目配置、全局上下文	推荐，最高加载优先级
.codebuddy/agents/*.md	子智能体	细分任务专用Agent	原生目录规范，独立角色

最简使用建议

1. 跑SDD规范驱动开发：执行 /openspec:propose，自动生成 openspec/xxx/design.md 写技术方案；
2. 项目全局统一约束：新建根目录 CODEBUDDY.md（不要用AGENTS.md）；
3. 细分专业角色：在 .codebuddy/agents/ 新建独立md子Agent，不要写在AGENTS.md里。

CodeBuddy SpecKit / OpenSpec SDD 完整实操指南

CodeBuddy 内置两套SDD体系：

1. *SpecKit（/speckit. 系列命令）**：GitHub 原生规范驱动开发，侧重分阶段分步构建；
2. OpenSpec（/openspec / /opsx 系列命令） ：腾讯适配优化版，一键全链路流水线，推荐日常开发使用 ；
   二者底层互通，均原生识别 design.md，全局配置读取 AGENTS.md/CODEBUDDY.md。

一、前置环境初始化（必做）

1. 安装依赖

# 1. 安装CodeBuddy CLI
npm install -g @tencent-ai/codebuddy-code
# 2. 全局安装OpenSpec核心框架
npm install -g @fission-ai/openspec@latest
# 验证版本
codebuddy --version
openspec --version

2. 项目初始化（绑定CodeBuddy）

进入项目根目录执行终端命令：

openspec init --tools codebuddy

初始化自动生成目录结构：

项目根目录
├── openspec/
│   ├── config.yaml       # SDD全局配置
│   ├── AGENTS.md         # CodeBuddy SDD专属智能体规则（兼容旧版）
│   ├── specs/            # 长期系统全局规范库
│   └── changes/          # 单次功能变更目录（存放design.md）
└── CODEBUDDY.md          # 项目全局最高优先级配置（推荐替代AGENTS.md）

初始化完成后重启CodeBuddy IDE/对话面板 ，斜杠命令 /openspec:* 自动加载生效。

二、OpenSpec 流水线（最简一键SDD，推荐）

核心命令对照表（CodeBuddy对话框直接输入）

命令	功能	使用场景
/openspec:propose "需求描述"	一键创建变更目录，自动生成全套文档（proposal+spec+design.md+tasks.md）	新增功能、需求开发（最常用）
/openspec:new 变更名	仅创建空变更目录，不生成文档	自定义分步写文档
/openspec:ff 变更名	空目录一键补齐全部规范文档	手动新建目录后快速生成design.md
/openspec:apply	读取当前变更下design.md+tasks.md，自动编码实现	评审完设计方案后写代码
/openspec:verify	校验代码与spec/design.md一致性，生成验收清单	自测、代码评审前校验
/openspec:sync	将本次变更的spec合并进全局openspec/specs/	功能稳定后沉淀系统规范
/openspec:archive	归档完成的变更，移入archive目录，留存完整design.md	功能上线收尾
/openspec:explore	读取所有spec/design文档，梳理项目架构	接手存量项目、需求调研

完整实操流程（6步闭环）

Step1：发起需求，自动生成design.md

在CodeBuddy对话框输入：

/openspec:propose "实现用户权限模块，包含RBAC角色、菜单权限、接口鉴权，基于Go Gin+MySQL"

自动创建目录：openspec/changes/add-rbac-auth/

目录内置核心文件：

add-rbac-auth/
├── proposal.md    # 变更提案：业务目标、改动范围、非功能约束
├── specs/
│   └── spec.md    # 需求规格：用户故事、验收标准、边界场景
├── design.md      # 【你关心的技术设计文档】架构、数据库表、接口、技术选型、风险点
└── tasks.md       # 拆解后的开发任务清单

Step2：人工评审&修改 design.md

1. 打开自动生成的 design.md，修正AI不合理架构、补充数据库字段、补充缓存/异常处理方案；
2. 修改 spec.md 补全产品验收标准；
3. CodeBuddy会自动读取同目录design.md，后续代码生成严格遵循设计约束，不会偏离架构。

Step3：按设计文档自动编码

评审完成后执行：

/openspec:apply

CodeBuddy会串行读取 design.md → tasks.md，逐条完成接口、数据表、业务逻辑、单元测试代码，全程对齐设计文档。

Step4：规范一致性校验

代码写完校验是否和设计一致：

/openspec:verify

输出差异报告：代码与design.md不匹配的地方，自动提示修复。

Step5：沉淀全局规范

功能稳定后，把本次需求合并进项目长期规范库：

/openspec:sync

更新 openspec/specs/ 全局基线，后续所有SDD流程自动复用权限模块规范。

Step6：归档留存完整设计记录

上线完成后归档变更，永久保存design.md用于复盘：

/openspec:archive

变更移入 openspec/changes/archive/add-rbac-auth/，多人协作可追溯历史技术方案。

三、SpecKit 分步式SDD（精细分阶段，适合大型复杂架构）

适用于大型重构、底层架构改造，分阶段逐层确认，命令前缀 /speckit.*：

完整阶段流程

1. 定义项目开发宪章（全局约束）

   /speckit.constitution

生成 constitution.md，统一编码规范、性能指标、安全标准，所有design.md强制遵循。

2. 撰写功能规格Spec

   /speckit.specify "分布式任务调度重构"

生成 spec.md 需求文档，定义所有功能行为、验收条件。

3. 需求自查澄清

   /speckit.checklist
   /speckit.clarify

自动检查需求缺失、模糊点，交互式补齐边界场景。

4. 生成技术方案（design.md）

   /speckit.plan

自动产出 plan.md + design.md，包含数据模型、API契约、部署架构、依赖选型。

5. 任务拆解

   /speckit.tasks

生成可执行任务清单，划分开发里程碑。

6. 批量代码实现

   /speckit.implement

基于design.md完整落地代码。

四、design.md / AGENTS.md / CODEBUDDY.md 区分与配合

1. design.md（SDD单次变更专属）

• 路径：openspec/changes/[变更名]/design.md
• 作用：单次功能的独立技术设计，仅当前SDD流程生效；
• CodeBuddy读取逻辑：执行 /openspec:apply / /speckit.plan 时自动加载，作为代码生成唯一技术依据；
• 不可放在根目录，根目录design.md不会被SDD工作流识别。

2. AGENTS.md（兼容旧版全局配置）

• 路径：项目根目录 / openspec/AGENTS.md
• 作用：定义CodeBuddy全局行为、SDD工作流规则、团队编码规范；
• 优先级：低于 CODEBUDDY.md，项目存在CODEBUDDY.md时自动忽略AGENTS.md。

3. CODEBUDDY.md（官方推荐全局配置）

• 路径：项目根目录；
• 最高优先级，CodeBuddy所有会话自动加载；
• 可写入全局架构约束、SDD强制规范，所有变更的design.md必须对齐该文件规则。

五、常见实操技巧

1. 快速新建空变更手动写design.md

   /openspec:new file-upload-module

   手动编辑design.md后一键补全其他文档

   /openspec:ff file-upload-module

2. 查看所有进行中变更
   终端执行：

openspec list

3. 多人协作规范

• 所有技术决策全部记录在 design.md，提交Git；
• 代码评审优先看 design.md 再看代码diff；
• 归档后的变更永久留存，需求迭代时可直接复用历史design。

4. 切换分步/一键模式

• 快速业务迭代：用 /openspec:propose 一键流水线；
• 底层架构重构：用 /speckit.* 分步确认，降低设计返工。

六、常见问题

1. 斜杠命令不生效：重启CodeBuddy对话面板，终端执行 openspec update 刷新指令；
2. CodeBuddy读取不到design.md：确认文件路径在 openspec/changes/xxx/ 下，不要放在根目录；
3. 全局规范不生效：删除根目录AGENTS.md，新建 CODEBUDDY.md，配置优先级更高。

CodeBuddy CN（腾讯云官方codebuddy.cn）SDD、design.md / agents.md 完整适配说明

一、核心结论（针对国内版 CodeBuddy CN）

1. 同时支持两套SDD：SpecKit、OpenSpec ，国内IDE网页端、本地CLI @tencent-ai/codebuddy-code 全兼容
2. design.md：SDD单次变更专用，原生识别 ，存储在 openspec/changes/[功能名]/design.md
3. agents.md：仅向下兼容旧项目，不推荐；官方标准全局配置是 CODEBUDDY.md，优先级更高
4. 国内版斜杠命令和海外版完全互通，无需修改语法，中文上下文自动适配

二、文件区分（CodeBuddy CN 官方规范）

1. design.md（SDD流程专属，单次功能）

• 路径强制：openspec/changes/xxx/design.md
• 作用：单一需求的架构、数据表、接口、风险技术方案
• 读取时机：执行 /openspec:apply / /speckit.plan 自动加载，AI写代码严格对齐这份设计
• 根目录直接放 design.md 不会被SDD工作流识别

2. AGENTS.md（兼容旧版，不推荐新项目使用）

• 加载规则：项目根目录存在 CODEBUDDY.md 时，直接忽略 AGENTS.md
• 仅当无 CODEBUDDY.md 才自动读取根目录 AGENTS.md
• 历史遗留文件，国内官方文档已不再主推

3. CODEBUDDY.md（CodeBuddy CN 官方标准全局配置）

• 路径：项目根目录，最高优先级，所有会话自动加载
• 用途：全局架构约束、编码规范、技术栈、SDD强制规则
• 所有SDD生成的 design.md、代码实现，都会强制遵守本文件规则

4. 自定义细分Agent文件

存放目录：.codebuddy/agents/*.md（带YAML头部）

用于架构师、测试、评审专用角色，和根目录AGENTS/CODEBUDDY无关，用 @角色名 调用

三、CodeBuddy CN 完整 OpenSpec（推荐轻量SDD）实操流程

前置环境（国内环境可用）

1. 本地CLI安装（网页IDE内置命令，无需安装）

npm install -g @tencent-ai/codebuddy-code
npm install -g @fission-ai/openspec@latest
openspec --version

2. 项目初始化（绑定腾讯CodeBuddy CN）

openspec init --tools codebuddy

自动生成目录：

项目根
├── openspec/
│   ├── config.yaml
│   ├── changes/        # 存放每个功能的design.md
│   └── specs/          # 全局沉淀规范
└── CODEBUDDY.md        # 全局配置（优先用这个，删掉AGENTS.md）

初始化后重启CodeBuddy网页IDE/本地CLI会话，斜杠命令生效。

完整5步SDD流水线（网页聊天框直接输入斜杠指令）

Step1：一键创建变更，自动生成design.md

/openspec:propose "基于Golang Gin实现后台字典管理模块，包含增删改查、缓存、分页"

自动生成目录 openspec/changes/add-dict-module/，内含：

• proposal.md：业务需求
• spec.md：验收标准
• design.md：核心技术架构文档
• tasks.md：开发任务拆解

Step2：人工评审修改 design.md

打开生成的design.md，调整数据库、接口、架构方案；CodeBuddy CN会缓存这份文档作为后续编码唯一依据。

Step3：AI按design.md自动写代码

/openspec:apply

逐条读取design.md+tasks.md，生成业务代码、单元测试，不会偏离设计。

Step4：校验代码与设计一致性

/openspec:verify

输出差异报告，自动修复与design.md不符的代码。

Step5：沉淀规范+归档

# 把本次设计沉淀到全局规范库
/openspec:sync
# 上线完成归档，永久留存design.md
/openspec:archive

四、SpecKit 分步式SDD（适合大型重构，国内版同样支持）

命令前缀 /speckit.*，适合底层架构改造，分阶段确认：

1. /speckit.constitution：生成全局开发宪章（约束所有design.md）
2. /speckit.specify "分布式任务调度重构"：生成需求spec
3. /speckit.plan：产出完整 design.md 技术方案
4. /speckit.tasks：拆分开发任务
5. /speckit.implement：基于design.md批量编码

五、CodeBuddy CN 专属常见问题

1. 斜杠命令不生效（网页IDE）
   刷新CodeBuddy.cn页面，重新打开对话；本地CLI执行 openspec update 刷新指令集。
2. 读不到design.md
   确认文件路径是 openspec/changes/xxx/design.md，不要放在项目根目录。
3. AGENTS.md 不生效
   国内官方优先级：CODEBUDDY.md > AGENTS.md，新项目直接删除AGENTS.md，只用CODEBUDDY.md。
4. 国内网络OpenSpec安装失败
   切换npm淘宝镜像后再安装openspec：

npm config set registry https://registry.npmmirror.com
npm install -g @fission-ai/openspec@latest

5. 网页IDE（codebuddy.cn）无需安装CLI，直接在对话框输入 /openspec: 系列命令即可使用SDD流程。

六、最简最佳实践（CodeBuddy CN 团队规范）

1. 快速业务迭代：用 /openspec:propose 一键流水线，自动产出design.md
2. 全局统一约束：根目录新建 CODEBUDDY.md，弃用AGENTS.md
3. 复杂架构重构：使用 /speckit.* 分步流程，逐层确认设计
4. 细分角色评审：在 .codebuddy/agents/ 新建独立Agent文件，不写在根目录配置
5. 所有技术决策全部落地在 openspec/changes/*/design.md，提交Git留存追溯