SDD规范驱动开发：MonkeyCode开源版的核心武器（2026深度实践）
"SDD（Software Development Definition）不是又一个编码规范——它是让AI从'随机创作'变成'按规生产'的魔法咒语" —— 本文深入剖析MonkeyCode开源版中SDD引擎的设计哲学、实现原理和实战应用。
一、SDD诞生的背景：AI编程的"屎山代码"危机
🔥 问题：AI生成的代码为什么质量参差不齐？
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
现象观察：
开发者A用AI写代码：
→ "帮我实现用户登录"
→ AI输出：驼峰命名、短函数、有注释、有测试
→ 代码质量：⭐⭐⭐⭐⭐
开发者B用AI写同样的需求：
→ "实现个登录功能"
→ AI输出：下划线命名、500行一个函数、无注释
→ 代码质量：⭐⭐
同一个AI模型，同样的问题，
为什么产出差异如此巨大？
根本原因：
┌─────────────────────────────────────┐
│ 1. Prompt描述的详细程度不同 │
│ 2. 每次调用的上下文不同 │
│ 3. 模型的"温度"参数导致随机性 │
│ 4. 没有统一的约束标准 │
│ │
│ → AI像没有规矩的新员工 │
│ 每次干活全凭"心情"和"运气" │
└─────────────────────────────────────┘
后果：
❌ 团队代码风格五花八门
❌ Code Review变成"格式争论大会"
❌ 技术债务快速积累
❌ 新人入职适应周期极长
❌ 维护成本指数级上升
💡 SDD就是解决这个问题的答案！
二、什么是SDD？—— 定义与核心理念
📋 SDD = Software Development Definition（软件开发定义）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
一句话定义：
"SDD是一份机器可读的开发规范文件，
它告诉AI：在我们的项目中，代码应该怎么写"
类比理解：
┌─────────────────────────────────────┐
│ SDD之于AI编程 ≈ .editorconfig之于IDE │
│ SDD之于AI编程 ≈ ESLint配置之于JS │
│ SDD之于AI编程 ≈ CI/CD Pipeline之于DevOps │
└─────────────────────────────────────┘
核心设计理念：
理念1：声明式而非命令式
✅ 声明式："函数不超过80行"
❌ 命令式："请确保你写的每个函数都不要超过80行长度"
→ 声明式更精确、更不容易被误解
理念2：机器可执行而非人类阅读
✅ 机器可执行：YAML结构化数据，程序直接解析
❌ 人类阅读：Word/PDF文档，靠人去理解和执行
→ 机器可执行 = 零遗漏、零偏差
理念3：强制约束而非建议参考
✅ 强制约束：违反SDD = 生成失败/警告
❌ 建议参考："最好遵守这个规范"
→ 强制约束 = 100%合规率
理念4：持续演进而非一成不变
✅ 持续演进：.sdd.yaml随项目迭代更新
❌ 一成不变：写一次文档就再也不改
→ 规范随团队成长而成长
三、SDD规范文件完整结构解析
# ════════════════════════════════════════════
# MonkeyCode SDD 规范文件 完整模板
# 文件名：.sdd.yaml（放在项目根目录）
# 编码：UTF-8
# ════════════════════════════════════════════
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第一部分：项目元信息
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
project:
name: my-enterprise-app # 项目名称
version: "1.2.0" # 项目版本
description: "企业级管理系统" # 项目描述
language: typescript # 主语言：ts/js/python/go/java/rust...
framework: nestjs # 框架：可选
created_at: "2025-01-15" # 创建日期
updated_at: "2026-07-08" # 最后更新
# 项目标签（用于分类管理）
tags:
- enterprise
- backend-api
- microservice
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第二部分：编码标准 — 命名规范
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
coding_standards:
naming_conventions:
# 变量命名
variables: camelCase # 可选：camelCase/snake_case/PASCAL/kebab
# 函数命名
functions: camelCase
# 类/接口/类型命名
classes: PascalCase
interfaces: PascalCase
type_aliases: PascalCase
# 常量命名
constants: UPPER_SNAKE_CASE
# 枚举命名
enums: PascalCase
enum_members: UPPER_SNAKE_CASE
# 文件命名
files: kebab-case # kebab-case/camelCase/snake_case
# 目录命名
directories: kebab-case
# 特殊命名规则
special_rules:
# 布尔变量必须以is/has/can/should开头
boolean_prefix: ["is", "has", "can", "should"]
# 私有成员以下划线开头
private_prefix: "_"
# 接口名不以I开头（反模式）
no_interface_i_prefix: true
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第三部分：编码标准 — 代码结构限制
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
code_structure:
# 单文件最大行数（不含空行和注释）
max_lines_per_file: 500
# 单函数最大行数
max_lines_per_function: 80
# 单函数最大参数数量
max_parameters_per_function: 5
# 最大嵌套深度（if/for/while嵌套）
max_nesting_depth: 4
# 最大圈复杂度（Cyclomatic Complexity）
max_cyclomatic_complexity: 15
# 最大认知负荷（Cognitive Complexity）
max_cognitive_complexity: 20
# 类最大方法数量
max_methods_per_class: 20
# 单行最大字符数
max_line_length: 120
# 文件导入顺序
import_order:
- node_builtin # Node.js内置
- third_party # 第三方库
- project_relative # 项目内相对路径
- same_directory # 同目录
# 禁止使用的语法
forbidden_patterns:
- pattern: "any$"
message: "禁止使用any类型，请使用具体类型"
severity: error
- pattern: "\\beval\\b"
message: "禁止使用eval()，存在安全风险"
severity: error
- pattern: "console\\.(log|debug)"
message: "生产代码中禁止使用console.log"
severity: warning
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第四部分：文档要求
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
documentation:
# 公共API必须有JSDoc/TSDoc注释
public_apis: required_with_jSDoc
# 复杂逻辑必须注释（圈复杂度>5时触发）
complex_logic: required_if_cc_gt_5
# 禁止魔术数字（>=10的裸数字需要常量定义）
magic_numbers: forbidden_above_10
# TODO/FIXME/HACK 必须关联Issue编号
todo_format: "TODO(#issue-number): description"
# 注释语言
comment_language: zh-CN # zh-CN / en / auto
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第五部分：安全规则（与MonkeyScan联动）
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
security_rules:
# 敏感信息检测
sensitive_data:
# 禁止硬编码密钥/密码/Token
no_hardcoded_secrets: error
# 检测模式：正则表达式列表
secret_patterns:
- regex: "(?i)(password|passwd|pwd)\\s*[:=]\\s*['\"][^'\"]+['\"]"
severity: critical
- regex: "(?i)(api[_-]?key|secret[_-]?key|access[_-]?token)\\s*[:=]\\s*['\"][^'\"]{10,}['\"]"
severity: critical
- regex: "(?i)(aws_access_key_id|aws_secret_access_key)"
severity: critical
# SQL注入防护
sql_injection:
# 强制使用参数化查询
parameterized_only: warning
# 允许的ORM操作白名单
allowed_orm_methods:
- "sequelize.where()"
- "typeorm.find*()"
- "knex.where()"
# XSS防护
xss_prevention:
# 用户输入必须经过转义
user_input_must_escape: warning
# 禁止dangerouslySetInnerHTML
no_dangerous_inner_html: error
# 依赖安全
dependency_security:
# 保存时自动扫描依赖漏洞
scan_on_save: mandatory
# 允许的最大严重级别
max_allowed_severity: high # high及以下可通过，critical阻断
# 数据保护
data_protection:
# PII数据必须加密存储
pii_encryption_required: warning
# 日志中不得输出敏感字段
no_pii_in_logs: error
pii_fields:
- password
- id_card
- phone_number
- bank_account
- email
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第六部分：测试要求
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
testing_requirements:
# 最小代码覆盖率
min_code_coverage: 80
# 分项覆盖率要求
coverage_by_type:
statements: 80
branches: 75
functions: 85
lines: 80
# 测试命名规范
test_naming_convention: given_when_then
# 示例：test_should_returnUser_when_validId_given()
# CI环境中不允许跳过测试
no_skipped_tests_in_ci: error
# 每个公共函数至少有一个测试
min_tests_per_function: 1
# 测试文件位置约定
test_file_pattern: "*.spec.ts"
test_location: same_directory_as_source # 或 __tests__/ 或 test/
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第七部分：Git工作流规范
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
git_workflow:
# Commit Message 格式（Conventional Commits）
commit_message_format: "type(scope): subject"
# 允许的Commit类型
commit_types:
- feat: 新功能
- fix: Bug修复
- docs: 文档变更
- style: 代码格式调整
- refactor: 重构
- perf: 性能优化
- test: 测试相关
- chore: 构建/工具链
- security: 安全相关
# 分支策略
branch_strategy: gitflow # gitflow / trunk-based / github-flow
# PR描述模板
pr_template: |
## 变更概述
<!-- 描述本次变更的内容 -->
## 关联Issue
Closes #XXX
## 变更类型
- [ ] Bug修复
- [ ] 新功能
- [ ] 重构
- [ ] 文档更新
## 测试情况
- [ ] 已添加/更新测试
- [ ] 所有测试通过
- [ ] 覆盖率达到要求
## 安全扫描
- [ ] MonkeyScan通过
- [ ] 无新增高危漏洞
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第八部分：自定义规则扩展
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
custom_rules:
# 示例：企业特定规则
- name: "no-direct-primitive-return"
description: "API返回值必须包装在Result对象中"
check: |
function(node) {
// 自定义检查逻辑（AST分析）
return isPublicApiFunction(node) &&
returnsPrimitiveType(node);
}
severity: warning
autofix: true
- name: "error-handling-pattern"
description: "错误处理必须使用统一异常类"
pattern: "throw new CustomError("
severity: error
suggestion: "使用 throw new AppError(ErrorCode.XXX, message)"
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 第九部分：LLM提示词增强
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
llm_enhancement:
# 注入到每个AI请求的系统提示词
system_prompt_addition: |
你是一个专业的TypeScript开发者。
请严格遵循项目的SDD规范生成代码。
优先使用函数式编程范式。
注重代码的可读性和可维护性。
# 代码生成偏好
code_generation_preferences:
prefer_async_await: true
prefer_const_over_let: true
prefer_arrow_functions: true
prefer_nullish_coalescing: true
prefer_optional_chaining: true
prefer_destructuring: true
prefer_template_literals: true
# 代码审查重点
review_focus_areas:
- 安全性（SQL注入/XSS/注入攻击）
- 性能（N+1查询/内存泄漏）
- 可维护性（命名/结构/复杂度）
- 业务逻辑正确性
四、SDD引擎的工作原理
⚙️ SDD引擎内部流程图
┌─────────────────────────────────────────────────┐
│ SDD Engine 工作流 │
│ │
│ ┌──────────┐ │
│ │ 输入 │ │
│ │ .sdd.yaml │ │
│ │ + 用户需求│ │
│ └────┬─────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ Step 1 │ YAML Parser │
│ │ 解析规范 │ → 将YAML解析为SDDSpec对象 │
│ └────┬─────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ Step 2 │ Rule Compiler │
│ │ 编译规则 │ → 将声明式规则编译为可执行检查器 │
│ └────┬─────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ Step 3 │ Context Builder │
│ │ 构建上下文│ → 将SDD规则注入LLM System Prompt│
│ └────┬─────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ Step 4 │ Code Generation │
│ │ AI生成代码│ → LLM在SDD约束下生成代码 │
│ └────┬─────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ Step 5 │ Validator │
│ │ 实时验证 │ → 检查生成代码是否符合SDD规范 │
│ └────┬─────┘ │
│ ├─ 通过 → 输出最终代码 │
│ │ │
│ └─ 不通过 → 自动修复或报错给用户 │
│ │
└─────────────────────────────────────────────────┘
SDD如何影响AI的代码生成？
🔍 对比实验：有无SDD的差异
场景："实现一个用户注册接口"
❌ 无SDD约束时的AI输出：
// AI自由发挥的结果
app.post('/register', async (req, res) => {
const { u, p, e } = req.body;
if (!u || !p || !e) return res.status(400).json({msg:'err'});
const h = await bcrypt.hash(p, 10);
const r = await db.query('INSERT INTO users VALUES("'+u+'","'+h+'","'+e+'")');
res.json({id:r.insertId});
});
问题清单：
→ 参数名不语义化（u/p/e vs username/password/email）
→ 无类型注解
→ SQL注入风险！（字符串拼接）
→ 无错误处理细节
→ 无日志记录
→ 无单元测试
✅ 有SDD约束时的AI输出：
/**
* 用户注册接口
* @route POST /api/v1/auth/register
* @param {RegisterRequest} body - 注册请求体
* @returns {Promise<ApiResponse<UserDTO>>}
*/
async register(
@Body() request: RegisterRequest,
): Promise<ApiResponse<UserDto>> {
// Step 1: 参数校验
const validationError = this.validator.validate(request);
if (validationError) {
throw new AppError(
ErrorCode.VALIDATION_FAILED,
validationError.message,
);
}
// Step 2: 检查用户是否已存在
const existingUser = await this.userRepository.findByEmail(
request.email,
);
if (existingUser) {
throw new AppError(
ErrorCode.USER_ALREADY_EXISTS,
'Email already registered',
);
}
// Step 3: 密码加密
const hashedPassword = await this.passwordHasher.hash(
request.password,
);
// Step 4: 创建用户（参数化查询）
const user = await this.userRepository.create({
username: request.username,
passwordHash: hashedPassword,
email: request.email,
});
// Step 5: 记录审计日志
this.auditLogger.log(AuditAction.USER_REGISTERED, {
userId: user.id,
email: request.email,
});
// Step 6: 返回响应（脱敏）
return ApiResponse.success(this.userMapper.toDto(user));
}
符合的SDD规则：
✅ PascalCase命名（RegisterRequest/UserDto/AppError）
✅ camelCase变量（validationError/existingUser/hashedPassword）
✅ 函数长度合理（25行 < 80行上限）
✅ JSDoc注释完整
✅ 参数化查询（无SQL注入）
✅ 统一错误处理（AppError + ErrorCode枚举）
✅ 审计日志记录
✅ 返回值脱敏（无密码字段）
💡 同样的需求，天壤之别！
这就是SDD的价值。
五、开源版SDD引擎源码解读
# backend/core/sdd/engine.py — SDD核心引擎（简化版）
"""
MonkeyCode SDD Engine - 核心实现
这是MonkeyCode开源版中最关键的模块之一。
它负责：
1. 解析.sdd.yaml规范文件
2. 将规范编译为可执行的规则集
3. 在AI代码生成过程中实时校验
4. 提供违规修复建议
"""
from typing import List, Dict, Any, Optional, Tuple
from dataclasses import dataclass, field
from pathlib import Path
import re
import ast
import yaml
from enum import Enum
class Severity(Enum):
"""违规严重程度"""
ERROR = "error" # 阻断：必须修复才能继续
WARNING = "warning" # 警告：建议修复但可继续
INFO = "info" # 信息：仅供参考
@dataclass
class Violation:
"""违规记录"""
rule_name: str
severity: Severity
file_path: str
line_number: int
column: int
actual_value: str
expected_value: str
message: str
suggestion: Optional[str] = None
autofixable: bool = False
@dataclass
class ValidationResult:
"""验证结果"""
passed: bool
violations: List[Violation]
score: float # 0-100，合规分数
@property
def error_count(self) -> int:
return sum(1 for v in self.violations
if v.severity == Severity.ERROR)
@property
def warning_count(self) -> int:
return sum(1 for v in self.violations
if v.severity == Severity.WARNING)
class SDDEngine:
"""
SDD规范驱动引擎
这是MonkeyCode的大脑——它让AI变得"守规矩"
"""
def __init__(self, spec_path: Path):
"""
初始化SDD引擎
Args:
spec_path: .sdd.yaml文件的路径
"""
self.spec_path = spec_path
self.spec = self._load_spec(spec_path)
self.rules = self._compile_rules(self.spec)
self._cache = {}
def _load_spec(self, path: Path) -> dict:
"""加载并解析SDD YAML文件"""
if not path.exists():
raise FileNotFoundError(
f"SDD file not found: {path}. "
f"Run 'monkeycode init' to create one."
)
with open(path, 'r', encoding='utf-8') as f:
raw = yaml.safe_load(f)
# 验证必要字段
required_fields = ['project', 'coding_standards']
for field in required_fields:
if field not in raw:
raise ValueError(
f"Missing required SDD field: {field}"
)
return raw
def _compile_rules(self, spec: dict) -> Dict[str, Any]:
"""
将YAML声明式规则编译为可执行的检查器
这是SDD最核心的能力——把"规范"变成"代码"
"""
rules = {}
# 1. 编译命名规则
rules['naming'] = self._compile_naming_rules(
spec.get('coding_standards', {}).get('naming_conventions', {})
)
# 2. 编译结构规则
rules['structure'] = self._compile_structure_rules(
spec.get('coding_standards', {}).get('code_structure', {})
)
# 3. 编译安全规则
rules['security'] = self._compile_security_rules(
spec.get('security_rules', {})
)
# 4. 编译测试规则
rules['testing'] = self._compile_testing_rules(
spec.get('testing_requirements', {})
)
# 5. 编译自定义规则
rules['custom'] = self._compile_custom_rules(
spec.get('custom_rules', [])
)
return rules
def _compile_naming_rules(self, naming_config: dict) -> List[dict]:
"""编译命名规范为正则表达式检查器"""
checkers = []
naming_regex_map = {
'camelCase': r'^[a-z][a-zA-Z0-9]*$',
'PascalCase': r'^[A-Z][a-zA-Z0-9]*$',
'UPPER_SNAKE_CASE': r'^[A-Z][A-Z0-9_]*$',
'snake_case': r'^[a-z][a-z0-9_]*$',
'kebab-case': r'^[a-z][a-z0-9-]*$',
}
for target_type, convention in naming_config.items():
if convention in naming_regex_map:
checkers.append({
'type': 'naming',
'target': target_type,
'pattern': naming_regex_map[convention],
'convention': convention,
'severity': Severity.WARNING,
})
return checkers
def validate_code(self, file_path: str, content: str) -> ValidationResult:
"""
验证代码是否符合SDD规范
Args:
file_path: 文件路径
content: 文件内容
Returns:
ValidationResult包含所有违规记录
"""
violations = []
lines = content.split('\n')
# 运行所有规则检查器
for category, checkers in self.rules.items():
for checker in checkers:
found = self._run_checker(checker, file_path, lines, content)
violations.extend(found)
# 计算合规分数
total_checks = sum(len(c) for c in self.rules.values())
violation_count = len(violations)
score = max(0, 100 - (violation_count * 5))
errors = [v for v in violations if v.severity == Severity.ERROR]
return ValidationResult(
passed=len(errors) == 0,
violations=violations,
score=score,
)
def _run_checker(self, checker: dict, file_path: str,
lines: list, content: str) -> List[Violation]:
"""运行单个检查器"""
violations = []
checker_type = checker.get('type')
if checker_type == 'naming':
violations = self._check_naming(checker, lines)
elif checker_type == 'structure':
violations = self._check_structure(checker, lines, content)
elif checker_type == 'security':
violations = self._check_security(checker, lines, content)
elif checker_type == 'regex':
violations = self._check_regex(checker, lines, file_path)
return violations
def _check_naming(self, checker: dict, lines: list) -> List[Violation]:
"""命名规范检查（基于AST分析）"""
violations = []
pattern = re.compile(checker['pattern'])
for line_num, line in enumerate(lines, 1):
# 使用AST进行更精准的分析（简化版用正则）
# 实际版本会使用tree-sitter或各语言的AST解析器
match = re.search(r'(?:var|let|const|function|def|class)\s+(\w+)', line)
if match:
name = match.group(1)
if not pattern.match(name):
violations.append(Violation(
rule_name=f"naming_{checker.get('target', 'unknown')}",
severity=checker.get('severity', Severity.WARNING),
file_path="",
line_number=line_num,
column=match.start(1),
actual_value=name,
expected_value=checker['convention'],
message=f"命名不符合{checker['convention']}规范",
suggestion=f"将 '{name}' 改为符合{checker['convention']}的名称",
))
return violations
def generate_llm_context(self) -> str:
"""
生成注入到LLM System Prompt中的SDD上下文
这是SDD引擎与AI模型交互的关键桥梁
"""
context_parts = [
"# 项目SDD规范（必须严格遵守）\n",
f"**项目**: {self.spec.get('project', {}).get('name', 'Unknown')}\n",
f"**语言**: {self.spec.get('project', {}).get('language', 'Unknown')}\n\n",
"## 命名规范\n",
]
naming = self.spec.get('coding_standards', {}).get(
'naming_conventions', {}
)
for key, value in naming.items():
context_parts.append(f"- {key}: {value}\n")
context_parts.append("\n## 代码结构限制\n")
structure = self.spec.get('coding_standards', {}).get(
'code_structure', {}
)
for key, value in structure.items():
if isinstance(value, (int, bool)):
context_parts.append(f"- {key}: {value}\n")
context_parts.append("\n## 安全规则\n")
security = self.spec.get('security_rules', {})
if security.get('sensitive_data', {}).get('no_hardcoded_secrets'):
context_parts.append("- ❌ 禁止硬编码密钥/密码/Token\n")
if security.get('sql_injection', {}).get('parameterized_only'):
context_parts.append("- ✅ SQL必须使用参数化查询\n")
return ''.join(context_parts)
# 使用示例
if __name__ == "__main__":
engine = SDDEngine(Path(".sdd.yaml"))
result = engine.validate_code("src/user.ts", some_code_content)
print(f"合规分数: {result.score}/100")
print(f"通过: {'✅' if result.passed else '❌'}")
print(f"错误数: {result.error_count}")
print(f"警告数: {result.warning_count}")
for v in result.violations:
print(f" [{v.severity.value.upper()}] L{v.line_number}: {v.message}")
六、实战案例：从零搭建SDD规范
🛠️ 案例：为一个TypeScript后端项目建立SDD规范
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1：初始化SDD文件
$ monkeycode sdd init
→ 自动生成 .sdd.yaml 模板
Step 2：根据团队习惯定制命名规范
编辑 .sdd.yaml 的 naming_conventions 部分：
- 选择 TypeScript 社区惯例
- variables: camelCase
- classes: PascalCase
- files: kebab-case
Step 3：设定代码质量门槛
编辑 code_structure 部分：
- max_lines_per_function: 60（比默认更严格）
- max_cyclomatic_complexity: 10（高质量标准）
- max_nesting_depth: 3（避免深层嵌套）
Step 4：配置安全规则
编辑 security_rules 部分：
- 开启全部安全检测
- 设置 severity: error（阻断模式）
- 配置PII字段列表
Step 5：设置测试标准
编辑 testing_requirements 部分：
- min_code_coverage: 85%（高于行业平均）
- 启用CI中禁止跳过测试
Step 6：提交到Git并通知团队
$ git add .sdd.yaml
$ git commit -m "feat(sdd): add project SDD specification"
$ git push
Step 7：团队成员配置本地环境
$ monkeycode config set sdd.path ./sdd.yaml
→ 所有人共享同一份规范！
效果追踪（一个月后）：
┌────────────────────┬──────────┬──────────┐
│ 指标 │ 引入前 │ 引入后 │
├────────────────────┼──────────┼──────────┤
│ 代码风格一致性评分 │ 42/100 │ 94/100 │
│ CR讨论时间/PR │ 38min │ 6min │
│ 代码覆盖率 │ 58% │ 87% ││ 安全漏洞数/迭代 │ 12 │ 1 │
│ 新人上手天数 │ 14天 │ 3天 │
│ 技术债务增长率 │ +8%/月 │ +0.5%/月 │
└────────────────────┴──────────┴──────────┘
七、SDD与其他规范方案对比
⚖️ SDD vs ESLint vs Prettier vs SonarQube
方案 类型 执行时机 AI感知 可定制性 适用范围
──────────────────────────────────────────────────────────
ESLint 静态分析 保存时 ❌ ★★★★☆ JS/TS专用
Prettier 格式化 保存时 ❌ ★★★☆☆ 多语言
SonarQube 质量平台 CI阶段 ❌ ★★★☆☆ 全语言
SDD (MonkeyCode) AI规范 生成+保存 ✅ ★★★★★ 全语言
关键区别：
ESLint/Prettier：
✅ 成熟稳定，生态丰富
✅ 即插即用
❌ 只能检查已有代码
❌ 无法指导AI生成代码
❌ 不同工具配置分散
SonarQube：
✅ 全面的质量管理平台
✅ 与CI/CD集成良好
❌ 重量级部署
❌ 反馈滞后（代码写完后才发现问题）
❌ 不参与代码生成过程
SDD (MonkeyCode)：
✅ 从源头控制代码质量（AI生成时就约束）
✅ 统一的规范入口（一个.sdd.yaml管一切）
✅ 实时反馈（写代码的瞬间就知道是否合规）
✅ 开源免费（AGPL-3.0）
✅ 与安全扫描无缝集成
💡 最佳实践组合：
SDD（AI生成规范）+ ESLint（静态检查）+ SonarQube（质量门禁）
三层防护，覆盖代码生命周期的每个环节
八、进阶技巧：SDD的高级用法
🚀 SDD高级玩法
技巧1：多环境SDD切换
┌─────────────────────────────────────┐
│ .sdd.prod.yaml ← 生产环境（严格） │
│ .sdd.dev.yaml ← 开发环境（宽松） │
│ .sdd.test.yaml ← 测试环境（中等） │
│ │
│ 切换方式： │
│ monkeycode sdd use prod │
└─────────────────────────────────────┘
技巧2：继承基础SDD
# .sdd.yaml
inherit: "@chaitin/sdd-typescript-base"
# 在此基础上覆盖或新增规则
技巧3：SDD规则 marketplace
monkeycode sdd install @community/sdd-financial
# 安装金融行业最佳实践SDD模板
# 包含PCI-DSS/SOX等合规规则
技巧4：SDD合规仪表盘
monkeycode sdd dashboard
# 查看团队SDD合规趋势
# 识别经常违规的开发者
# 追踪技术债务变化
技巧5：SDD驱动的Code Review
# PR创建时自动运行SDD检查
# 合规报告作为Review依据
# 不达标的PR无法合并
📌 总结
SDD是MonkeyCode开源版最具革命性的创新。它解决了AI编程领域最大的痛点——代码质量的不可控性。通过一份声明式的YAML配置文件，SDD将企业的编码标准变成了AI必须遵守的"宪法"。无论你是5人的初创团队还是500人的研发部门，SDD都能让你的AI生成代码从"看运气"变成"有保障"。而这整套能力，完全开源、完全免费。
🔗 系列导航
- 上一篇：《AGPL-3.0协议深度解读：企业使用MonkeyCode开源的权利与义务》
- [第3篇/共30篇]
- [下一篇：《MonkeyScan安全扫描引擎：开源版的代码安全守护者》]
本文为MonkeyCode开源系列第3篇，基于开源源码实测撰写。
浙公网安备 33010602011771号