知识库

AI Coding SDD开发规范_03_最佳实践与常见问题

markdown
2026年7月17日阅读约 7 分钟1,368 字

更新于 2026年7月17日

AI Coding SDD开发规范_03_最佳实践与常见问题

一、核心开发原则

1.1 SDD开发十大黄金原则

序号 原则 说明
1 规范先行 在编码之前，必须先建立项目规范，让AI理解代码风格和技术约束
2 文档驱动 通过Spec文档传递需求，确保AI准确理解业务逻辑
3 上下文完整 为AI提供足够的项目上下文，减少幻觉和错误
4 渐进式构建 从简单任务开始，逐步验证AI能力后再承接复杂需求
5 人工审核 AI输出必须经过人工审核，不可盲目信任
6 原子化任务 将大需求拆解为小任务，每次只做一个功能点
7 迭代优化 根据生成效果动态调整提示词和规范
8 知识沉淀 将好的实践总结为Skills和Rules，实现知识复用
9 度量反馈 记录AI Coding效能数据，持续优化流程
10 安全第一 所有代码必须经过安全扫描和审核

1.2 需求态核心原则

智能原型设计原则

  1. 单功能单页面：每次生成范围建议单功能、单页面，避免需求过于复杂
  2. 风格明确：在需求文档中明确指定UI风格，技能会自动推荐最合适的
  3. 交互清晰：详细描述组件的交互逻辑和状态变化
  4. 中文优先：非功能性需求中明确"按照中文展示"

UI-UX-PRO-MAX 使用技巧

# 需求文档示例

## 1. 需求描述
想生成一个服务器监控软件，支持监控公司及家庭的服务器信息。

## 2. 功能设计

### 主机监控界面
- 核心指标：CPU（分核心频率/温度）、内存、网络等
- 异常告警窗：以醒目颜色展示当前触发阈值的监控项
- 支持深色模式和浅色模式

## 3. 非功能性需求
- 按照中文展示
- 支持深色模式与浅色模式切换

推荐样式风格：

  • 毛玻璃效果（Glassmorphism）：现代感界面
  • 暗黑模式（Dark Mode）：数据监控类应用
  • 极简主义（Minimalism）：简洁高效的工具类应用

1.3 设计态核心原则

Spec文档编写原则

  1. 核心逻辑人工写：方法概述、处理流程等核心内容必须人工编写
  2. 结构化章节AI补：相对标准化的章节可由AI辅助生成
  3. 人工审核确认：AI补全内容必须经过评审才能使用
  4. 模板统一规范：使用统一的文档模板，保证格式一致性

架构合规检查原则

⚠️ 注意：架构合规智能核查会对整个工程代码进行扫描识别，非常占用Token，建议通过包月模式的 Lingma IDE 或 Claude Code Agent 模式执行。

检查时机：

  • 新项目启动时
  • 重大架构变更后
  • 代码审计前

二、前端智能开发最佳实践

2.1 Figma 高保真开发流程

Figma开发流程图

适用场景

  • 大型项目，界面部分由UED主导设计高保真原型
  • 需要严格遵循Figma设计规范
  • 对视觉还原度要求高的项目

关键步骤

步骤1：Figma MCP 配置

  1. 安装 Figma 桌面应用程序
  2. 在本地打开设计稿，开启 DEV 模式
  3. 点击 "Enable desktop MCP server" 开启MCP服务
  4. 获取 MCP server 地址：http://127.0.0.1:3845/mcp

步骤2：任务文档编写

# 前端评测集需求设计文档

## 接口文档
[接口文档](设计文档.md)

## to-dos

### 1. 测评集列表查询
- 组件类型：有左侧菜单的页面
- 使用 Figma MCP 把文件转为代码：https://www.figma.com/design/xxx
- 文件路径：src/views/evaluation/list.vue
- 页面路由：/evaluation/list
- 说明：
  - 使用figma mcp服务将设计稿转换为代码
  - 新建评测集：主要按钮，点击打开弹窗
  - 评测集列表：使用接口文档中的接口

注意事项：

  • 需求文档中如果有图片，必须使用支持多模态的大模型
  • 要还原的页面设计稿在Figma中必须处于打开状态，不能关闭

2.2 需求设计开发流程

适用场景

  • 小型项目
  • 不依赖高保真设计
  • 已有项目规范可以参考

操作流程

  1. 配置项目规则

    • 参考已有项目编写项目规范
    • 添加到 Rules 配置中

  2. 编写开发设计文档

    # 前端需求设计文档

## 约束条件
- 严格按照任务中指定的文件路径生成文件
- 严格遵守项目要求生成代码

## 需求
- 类型：新增需求
- 文件路径：/src/views/ai/diffMgrView.vue
- 需求说明：
  - 写一个对账差异查询页面
  - 包括查询条件、查询列表
  - 列表中的数据可以查看详情，可以处理差异数据

  3. 智能生成代码

    • 将开发设计文档添加到对话框
    • 输入启动提示语
    • 检查生成代码，支持批量接受和文件独立接受

2.3 低保真开发流程

适用场景

  • 快速原型验证
  • 手绘简图或简图描述
  • 不需要精确视觉还原的项目

操作流程

  1. 准备材料

    • 低保真图（手绘图或简图）
    • 设计文档（描述组件布局和交互）

  2. 编写设计文档

    # 低保真-功能设计文档

## 1. 页面布局
- 顶部导航栏
- 左侧菜单
- 右侧内容区

## 2. 功能模块
- 用户列表展示
- 搜索过滤
- 分页控制

## 3. 交互说明
- 点击行展开详情
- 双击编辑

  3. 智能生成

    根据设计文档，开发组织架构管理页面组件，根据需要添加mock模拟数据

2.4 私有技术栈开发

私有Vue组件库开发

配置步骤：

  1. 添加项目级规范（参考已有项目规范）
  2. 创建 skills 技能
    • Trae：.trae/skills 目录
    • Qoder：.qoder/skills 目录
  3. 编写开发设计文档
  4. 智能生成代码

参考案例：

  • 参考已有私有技术栈前端项目

私有全栈框架开发

特点：全栈一体化开发模式，能同时生成前端界面和后端业务逻辑代码

配置步骤：

  1. 下载私有技术栈的 Skills
  2. 编写前端页面规则（page_rules）
  3. 编写后端规则（common_rule）
  4. 创建业务规范 Skills（如 ddl_to_java_generator）
  5. 编写任务文档
  6. 智能生成代码

参考案例：

  • 参考已有私有技术栈全栈项目

三、后端智能开发最佳实践

3.1 Java 开源技术栈开发

Java开发流程图

配置规则

将后端项目规则里的《code-style1》、《code-style2》的内容分别复制到个人设置的规则里。

# 规则配置说明

## 添加方式
1. 在 .trae/rules 文件下创建规则文件
2. 复制 code-style1.md 内容
3. 复制 code-style2.md 内容

## 规则内容（根据项目调整）
- 代码格式化规范
- 命名规范
- 注释规范
- 异常处理规范

生成代码

  1. 业务方法开发

    拖拽：开发设计文档 + 数据模型
提示词：请按照规范生成业务方法代码

  2. 业务接口开发

    拖拽：开发设计文档 + 数据模型 + 接口定义
提示词：请按照规范生成业务接口代码

3.2 私有技术栈开发

私有后端框架开发

配置步骤：

  1. 编写符合项目的规则文件（common_rule）
  2. 设置为始终生效
  3. 创建 Skills 技能（如 plus-dev）
  4. 编写任务文档
  5. 智能生成代码

参考案例：

  • 参考已有私有后端框架项目模板

3.3 C++ 开发

Openspec 工作流

需求规格文档 → 需求分析 → 详细设计 → 制定开发任务 → 编码
    │              │            │            │         │
    ▼              ▼            ▼            ▼         ▼
 requirement.md  research.md  design.md   tasks.md   代码

工作流指令

步骤 图灵指令 灵码指令
创建变更 /opsx-new.md /openspec-new-change
继续执行 /opsx-continue.md /openspec-continue-change
实施代码 /opsx-apply.md /openspec-apply-change
归档 /opsx-archive.md /openspec-archive-change

实践案例：存量功能开发

关键经验：

  1. 提前准备基础业务规范（模块功能规范、详单模型规范）
  2. 需求规格文档中，关键信息尽量使用md文档
  3. 尽可能减少无关信息描述，减少上下文
  4. 涉及多模块配合改造的功能，先进行各功能模块的需求拆分

四、代码智能安全

4.1 智能安全扫描

概述

结合通用代码安全规范、历史安全事件沉淀规范，支持按项目扩展安全规范，基于 Coding Agent 智能扫描代码工程，识别潜在安全漏洞，并生成问题报告。

操作步骤（GUI 工具）

  1. 下载对应的代码安全模板
  2. 打开 Trae，打开需要安全扫描的工程
  3. 将下载好的文档拷贝到工程目录
  4. 右键该文档，将文档引用添加到会话中
  5. 在对话框中选择"智能体"模式
  6. 输入提示词：基于此清单逐项检查项目并生成一份标准化的安全扫描报告

操作步骤（Claude Code CLI）

# 在项目根目录执行
claude -p "基于 security-checklist.md 逐项检查本项目，生成安全扫描报告 security-report.md"

生成结果

  • 安全报告文件：security-report-项目名-日期.md
  • 包含问题列表、风险等级、修复建议

4.2 智能安全修复

概述

结合智能安全扫描生成的问题报告，基于 Coding Agent 智能修复对应问题，最终通过人工协作确认完成安全问题修复。

修复流程

扫描报告 → 引用报告 → 输入提示词 → 智能修复 → 人工确认 → 完成修复

操作示例（GUI 工具）

提示词：替我修复3.1
（3.1为报告中的问题编号）

操作示例（Claude Code CLI）

claude -p "根据 security-report.md 修复其中 3.1 描述的安全问题"

修复完成后：

  1. 在对话框中查看变更的文件
  2. 点击变更的文件检查修改内容
  3. 选择是否采纳

五、性能智能优化

5.1 慢接口智能优化

Druid 监控识别

  1. 集成阿里的 Druid 数据库连接池并开启监控
  2. 通过 Druid 监控页面点击"URI监控"
  3. 选中"请求最慢（单次）"按倒序排列
  4. 根据接口信息到后端代码中找到对应代码

智能优化示例

提示词：
"/test-agent/requirements/analyse-task/832/cases" 接口单次请求处理时间花费了 25692ms，请分析一下后端处理逻辑进行优化

优化效果：

  • 优化前：25692ms
  • 优化后：2001ms

5.2 慢SQL智能优化

Druid SQL监控

  1. 通过 Druid 监控页面点击"SQL监控"
  2. 选中"最慢"按倒序排列
  3. 根据 SQL 信息到后端代码中找到对应位置

智能优化示例

提示词：
"SELECT *
FROM recommend_case_step
WHERE case_id IN (?)
ORDER BY case_id, step_index;"
请分析一下这个慢SQL，结合后端代码进行优化

优化要点：

  • 如果能明确慢SQL的文件位置，可直接引用对应文件进行优化
  • 不能明确SQL的文件位置，可输入监控里的SQL信息通过智能体去定位分析优化

六、测试态最佳实践

6.1 前端Mock数据生成

配置步骤

  1. 配置Mock数据规则

    // mock-rules数据样例
export default [
  {
 url: '/api/evaluation-set',
 method: 'post',
 statusCode: 200,
 response: ({ body }) => {
   // 接口返回
 }
  },
]

  2. 添加规则到项目中

    • 选择 Trae 设置 → 规则
    • 添加 Mock 数据规则文件

  3. 生成Mock数据

    • 在提示词上下文中添加接口文档
    • 输入提示词生成 Mock 数据

6.2 后端接口测试数据生成

配置Postman规则

trigger: always_on

该规则在生成Postman接口测试数据时自动生效。

要求：
- 输出必须是纯净的 JSON 对象
- 必须遵循 Postman Collection v2.1 Schema
- 每个接口都必须对应一个 item
- 必须提取：接口名称、HTTP方法、完整URL、路径变量、请求头、请求体、查询参数

操作步骤

  1. 将 Postman 接口数据生成规则配置到规则里
  2. 配置为始终生效
  3. 输入提示词生成数据
  4. 导入 Postman 数据文件
提示词：
你是一名资深 Java 全栈工程师，熟悉 Spring Boot、JUnit 5、Mockito 和 CI/CD 实践。
请根据控制器AppointmentController的所有接口信息，生成一个可直接导入 Postman 的 Collection JSON 文件。

6.3 后端单元测试生成

配置步骤

  1. 下载对应的智能单元测试.md
  2. 将其复制到项目中
  3. 和要生成单元测试的 Java 类文件一起引用到智能体处理上下文中

生成示例

提示词：
你是一名资深 Java 全栈工程师，熟悉 Spring Boot、JUnit 5、Mockito 和 CI/CD 实践。
请根据以下 Spring Boot 控制器源码，生成单元测试并自动执行。

执行测试

# 打开终端，切换到脚本的目录
./run-test-and-report.sh

6.4 测试用例智能生成

概述

基于 Spec 需求文档，由 Coding Agent 智能拆解需求，自动生成测试人员可操作的测试用例。

模型推荐：GLM5.1 及更优模型

操作流程

测试用例生成流程图

操作步骤

  1. 导入 test-case-skills 技能包

    project-root/
├── test-cases/
│   ├── common/
│   ├── account-manage/
│   └── ...

  2. 上传需求文档

    • 支持 Word 格式（通过 docx Skill 转换为 md）
    • 支持 Markdown 格式

  3. 生成测试用例

    • 「/」触发引用输入 test-case-generator
    • 输入提示词：按要求生成测试用例md

生成的测试用例示例

ID 用例名称 用例等级 用例类型 前提条件 用例步骤 预期结果
TC-001 订单中心-工单明细-导出-正常数据 L0 功能 已登录MOP后台 进入工单明细→查询→导出 导出成功，文件加密
SEC-001 API接口_未授权漏洞检查 L0 安全性 BurpSuite已配置 拦截请求→删除凭证→放行 返回401/403

用例等级分布：

  • L0：核心功能+核心安全（60.6%）
  • L1：重要功能+边界场景（26.9%）
  • L2：次要功能+性能可靠性（2.9%）

6.5 UI自动化测试

概述

基于 Coding Agent 的智能测试用例设计能力，支持多源输入驱动，实现从需求到验证的端到端闭环。

模型推荐：GLM5.1

输入方式

方式 输入示例
基于URL 测试https://xxx/userList用户维护菜单
基于Spec文档 测试需求文档.md功能
基于代码 测试智能体管理模块功能

操作流程

  1. 导入 skill 技能
  2. 输入提示词测试当前项目功能
    • 优先建议：制定指定单个功能及模块
    • 支持：多个功能或整个小型项目
  3. 人工确认并完善测试用例
  4. 生成前置测试数据
  5. 人工确认前置测试数据
  6. 自动生成测试脚本
  7. 执行 PlayWright 脚本

生成的目录结构

project-root/
├── playwright.config.js          # Playwright 配置文件
├── test-reports-summary/         # 汇总报告目录
├── tests/
│   ├── common-data/
│   │   ├── config.data.js        # 基础配置数据
│   │   └── utils.data.js         # 工具函数
│   ├── login/
│   │   ├── test-cases/           # 测试用例文档
│   │   ├── test-reports/         # 测试报告
│   │   ├── test-data/            # 测试数据
│   │   └── test-scripts/         # 测试脚本
│   └── schedule/
│       └── ...
└── issues.md                     # 共享问题记录

执行测试

npx playwright test

七、常见问题与解决方案

7.1 开发态常见问题

问题 原因 解决方案
Agent模式循环 任务过于复杂或提示词不明确 拆分任务、明确提示词、观察日志手动中断
Token消耗过快 上下文过大、扫描范围过广 使用Lite-SDD模式、限制扫描范围
代码不符合规范 Rules配置缺失或内容不准确 检查Rules配置，更新项目规范
Figma MCP连接失败 Figma未开启MCP服务 确认Figma桌面应用开启MCP服务
Skills不生效 目录位置错误或格式问题 确认Skills目录位置、检查SKILL.md格式
Claude Code无权限修改文件 沙箱模式限制 在项目根目录运行 claude，确认工作目录正确
Codex CLI 变更超出预期 审批模式设置不当 改用 --approval-mode suggest，逐步确认
OpenCode 模型调用失败 API Key 未配置 检查 opencode.json 或环境变量中的 API Key

7.2 前端开发常见问题

问题 原因 解决方案
视觉还原度差 Figma MCP版本问题 使用多模态模型、更新Figma版本
路由配置错误 未按规范编写路由 参考项目规范、明确路由规则
组件样式冲突 样式命名冲突 使用唯一前缀、遵循BEM规范
依赖安装失败 版本冲突或网络问题 检查package.json、配置镜像源

7.3 后端开发常见问题

问题 原因 解决方案
SQL生成错误 数据库规范缺失 提供完整的数据库规范文档
接口定义不准确 Spec文档不完整 补充接口定义、请求参数、响应格式
代码风格不一致 Rules配置不统一 统一代码风格规范、更新Rules
单元测试覆盖率低 未按TDD方式开发 使用单元测试生成工具、完善测试用例

7.4 安全扫描常见问题

问题 原因 解决方案
扫描超时 Token限制或代码量过大 分批次扫描、优化Token使用
误报率高 规则配置过于严格 调整规则阈值、添加白名单
修复建议不适用 上下文不足 提供更多代码上下文

7.5 性能优化常见问题

问题 原因 解决方案
优化后性能下降 优化方案不适合当前场景 人工审核优化方案、回归测试
慢SQL定位困难 SQL分散在多处 使用Druid监控、明确SQL文件位置
缓存策略失效 缓存Key设计问题 规范缓存Key设计、添加版本号

八、效率提升技巧

8.1 提示词优化技巧

好的提示词示例

# 好的提示词
请帮我生成一个用户管理模块的CRUD接口，包括：
1. 用户列表查询（分页、模糊搜索）
2. 用户详情查询
3. 用户创建（参数校验）
4. 用户更新（部分更新）
5. 用户删除（软删除）

技术要求：
- 使用SpringBoot框架
- 返回统一响应格式
- 异常统一处理
- 单元测试覆盖率>80%

不好的提示词示例

# 不好的提示词
帮我写个用户接口

8.2 上下文优化技巧

  1. 减少无关信息：只提供与当前任务相关的上下文
  2. 结构化组织：使用清晰的章节结构组织文档
  3. 版本标注：重要文档标注版本号和日期
  4. 引用索引：建立文档间的交叉引用

8.3 工作流优化技巧

  1. 小步快跑：每次只做一个功能点，快速验证
  2. 及时存档：每个阶段完成后及时保存产出物
  3. 增量开发：基于已有代码增量开发，减少重复
  4. 持续集成：将AI生成代码纳入CI/CD流程

8.4 知识复用技巧

  1. Rules复用：通用规则抽取到项目级配置
  2. Skills沉淀：好的实践封装为Skills
  3. 模板积累：建立业务模板库
  4. 案例分享：定期分享优秀案例

九、度量与反馈

9.1 AI Coding 效能指标

指标 定义 目标
需求响应速度 从需求提出到代码完成的时间 提升50%
代码产出质量 代码评审通过率 >95%
缺陷密度 千行代码缺陷数 <5
AI依赖度 使用AI辅助的任务占比 >80%
知识复用率 复用已有Rules/Skills的任务占比 >60%

9.2 反馈机制

  1. 周度回顾：每周复盘AI Coding使用情况
  2. 问题记录：记录遇到的问题及解决方案
  3. 最佳实践：分享优秀的AI Coding案例
  4. 持续优化：根据反馈持续优化流程和工具

9.3 持续改进

知识飞轮：需求驱动 → 按需沉淀 → 持续扩充 → 深度覆盖

  • 每次需求迭代后，复盘上下文完整性
  • 新发现的知识及时更新到项目上下文
  • 好的实践总结沉淀为 Skills
  • 通过 PR 机制共享项目组知识