114 lines
3.0 KiB
Markdown
114 lines
3.0 KiB
Markdown
---
|
||
name: constraint-design
|
||
description: Design patterns for writing effective Agent constraints. Use when defining rules, policies, or guardrails for AI code generation. Covers constraint types (architectural/code quality/security/business), DSL patterns, conflict resolution, and progressive trust scaling.
|
||
---
|
||
|
||
# 约束设计 — 让 Agent 在边界内发挥
|
||
|
||
> 好的约束不是束缚，是护栏。它让 Agent 在安全区域内自由发挥。
|
||
|
||
## 📐 四类约束
|
||
|
||
### 1. 架构约束
|
||
定义系统结构和组件关系：
|
||
```yaml
|
||
architecture:
|
||
required_interface: "PaymentProcessor" # 必须实现
|
||
file_location: "src/payment/" # 文件位置
|
||
naming_convention: "{name}_processor.py"
|
||
forbidden_patterns:
|
||
- "god_class" # 禁止上帝类
|
||
- "circular_dep" # 禁止循环依赖
|
||
```
|
||
|
||
### 2. 代码质量约束
|
||
定义代码质量和风格标准：
|
||
```yaml
|
||
code_quality:
|
||
max_complexity: 10 # 圈复杂度上限
|
||
max_line_length: 120 # Java / 100（Vue）
|
||
type_hints: "required" # 必须类型提示
|
||
docstrings: "public_only" # 公共方法需要文档
|
||
test_coverage: 90 # 覆盖率目标
|
||
```
|
||
|
||
### 3. 安全约束
|
||
防止 Agent 引入安全隐患：
|
||
```yaml
|
||
security:
|
||
no_hardcoded_secrets: true
|
||
use_vault_for_credentials: true
|
||
input_sanitization: "strict"
|
||
forbidden_functions:
|
||
- "eval()"
|
||
- "exec()"
|
||
```
|
||
|
||
### 4. 业务规则
|
||
领域特定的约束：
|
||
```yaml
|
||
business:
|
||
data_flow: "full_chain" # 必须走通全链路
|
||
soft_delete: true # 软删除机制
|
||
audit_log: true # 操作审计
|
||
```
|
||
|
||
## 🎯 约束设计原则
|
||
|
||
### 原则 1：可验证
|
||
每条约束必须能被自动化检查：
|
||
```
|
||
✅ "代码覆盖率 > 90%" — 可用 pytest-cov 验证
|
||
❌ "代码质量要高" — 无法验证
|
||
```
|
||
|
||
### 原则 2：无歧义
|
||
约束必须精确，不留解读空间：
|
||
```
|
||
✅ "每函数不超过 50 行"
|
||
❌ "函数不要太长"
|
||
```
|
||
|
||
### 原则 3：优先级排序
|
||
约束冲突时按优先级裁决：
|
||
```
|
||
安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
|
||
```
|
||
|
||
### 原则 4：渐进增强
|
||
从最少的约束开始，按需增加：
|
||
```
|
||
L1: 编译通过
|
||
L2: + 类型提示 + 命名规范
|
||
L3: + 测试覆盖 + 复杂度限制
|
||
L4: + 安全扫描 + 架构合规
|
||
```
|
||
|
||
## 🔧 约束 DSL 模式
|
||
|
||
### 声明式（推荐）
|
||
```yaml
|
||
constraint:
|
||
type: "must" | "must_not" | "should" | "may"
|
||
scope: "file" | "class" | "method" | "project"
|
||
rule: "具体规则"
|
||
verification: "如何验证"
|
||
```
|
||
|
||
### 命令式（脚本）
|
||
```python
|
||
# validate_constraints.py
|
||
def check_naming(file_path):
|
||
if not file_path.endswith("_processor.py"):
|
||
raise Violation("命名不规范")
|
||
```
|
||
|
||
## ⚠️ 常见陷阱
|
||
|
||
| 陷阱 | 表现 | 解决 |
|
||
|---|---|---|
|
||
| 过度约束 | Agent 无法完成任务 | 从最小约束集开始 |
|
||
| 约束冲突 | 约束 A 要求 X，约束 B 禁止 X | 建立优先级链 |
|
||
| 无法验证 | 约束定义模糊，无法自动化检查 | 每条约束都必须可验证 |
|
||
| 静态不变 | 项目演进后约束过时 | 定期复审约束集 |
|