his/.qoder/skills/constraint-design/SKILL.md

name, description

name	description
constraint-design	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. 架构约束

定义系统结构和组件关系：

architecture:
  required_interface: "PaymentProcessor"  # 必须实现
  file_location: "src/payment/"           # 文件位置
  naming_convention: "{name}_processor.py"
  forbidden_patterns:
    - "god_class"     # 禁止上帝类
    - "circular_dep"  # 禁止循环依赖

2. 代码质量约束

定义代码质量和风格标准：

code_quality:
  max_complexity: 10          # 圈复杂度上限
  max_line_length: 120        # Java / 100（Vue）
  type_hints: "required"      # 必须类型提示
  docstrings: "public_only"   # 公共方法需要文档
  test_coverage: 90           # 覆盖率目标

3. 安全约束

防止 Agent 引入安全隐患：

security:
  no_hardcoded_secrets: true
  use_vault_for_credentials: true
  input_sanitization: "strict"
  forbidden_functions:
    - "eval()"
    - "exec()"

4. 业务规则

领域特定的约束：

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 模式

声明式（推荐）

constraint:
  type: "must" | "must_not" | "should" | "may"
  scope: "file" | "class" | "method" | "project"
  rule: "具体规则"
  verification: "如何验证"

命令式（脚本）

# validate_constraints.py
def check_naming(file_path):
    if not file_path.endswith("_processor.py"):
        raise Violation("命名不规范")

⚠️ 常见陷阱

陷阱	表现	解决
过度约束	Agent 无法完成任务	从最小约束集开始
约束冲突	约束 A 要求 X，约束 B 禁止 X	建立优先级链
无法验证	约束定义模糊，无法自动化检查	每条约束都必须可验证
静态不变	项目演进后约束过时	定期复审约束集