@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/01-principles/04-operational-principles.md

@@ -0,0 +1,275 @@
+# L4: 操作原则
+
+> **定位**: 战术原则的具体落地，包含明确的行为规范和检查清单
+>
+> **进化分区**: 🟡 受控区（自动提议 + 人工批准）
+
+---
+
+## 一、原则体系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  L4: 操作原则 (Operational Principles)                        │
+│  ─────────────────────────────────────────────────────────  │
+│  源自 L3 战术原则，指导具体行为规范                           │
+│                                                              │
+│  O1 编码规范 | O2 自主修复 | O3 宪法门禁 | O4 检查清单        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 追溯关系
+
+```
+L3 战术原则              L4 操作原则
+─────────────────      ──────────────────
+T6 优先复用      ────→   O1 编码规范
+T3 精准回退      ────→   O2 自主修复
+T5 驯服非确定性  ────→   O3 宪法门禁
+T4 反模式预判    ────→   O4 检查清单
+```
+
+---
+
+## 二、O1: 编码规范 (Coding Style)
+
+> **源自**: T6 优先复用项目现有能力
+>
+> **核心章节**: 详见 `knowledge/07-standards/00-coding-style.md`
+
+### 1.1 核心原则
+
+**复用优先与禁止硬编码**:
+- 实现前先扫描项目现有能力
+- 优先使用项目已有的 Helper、Util 类
+- 按已有代码的模式和风格实现
+- 禁止硬编码目录名、包名、类名、配置项
+
+**一锁二判三更新**（并发场景）:
+```
+1. 一锁：锁定单点资源（单条记录）
+2. 二判：基于锁定的记录最新状态，判断状态、数值
+3. 三更新：判断通过后的处理
+```
+
+**异步异常处理**:
+- 异步方法中必须捕获和处理异常
+- 禁止吞掉异常
+- 使用带返回值的 AsyncResult，上层通过 get() 捕获异常
+
+**ThreadLocal 清理**:
+- 使用完毕后必须在 finally 中调用 remove() 清理
+- 禁止使用 `set(null)` 替代 `remove()`
+
+**LogUtil 优先**:
+- 日志打印必须使用 LogUtil 工具类
+- 自动添加 TraceId
+- 禁止直接使用 logger 或 System.out
+
+### 1.2 SOLID+DDD 原则
+
+| 原则 | 说明 | 应用 |
+|------|------|------|
+| **S**RP 单一职责 | 一个类只有一个职责 | 类设计 |
+| **O**CP 开闭原则 | 对扩展开放，对修改关闭 | 架构设计 |
+| **L**SP 里氏替换 | 子类可替换父类 | 继承设计 |
+| **I**SP 接口隔离 | 客户端不应依赖不需要的接口 | 接口设计 |
+| **D**IP 依赖倒置 | 依赖抽象，不依赖具体 | 依赖管理 |
+
+**DDD 战术设计**:
+- 统一语言：代码命名与业务术语一致
+- 聚合设计：小聚合优于大聚合
+- 领域事件：事件命名用过去时，一旦发生不可修改
+- 充血模型：核心业务逻辑内聚到领域对象
+
+### 1.3 追溯关系
+
+- **上游**: T6 优先复用、T5 驯服非确定性
+- **下游**: `knowledge/07-standards/00-coding-style.md`
+
+---
+
+## 三、O2: 自主修复机制 (Auto-Fix Loop)
+
+> **源自**: S1 双层验证 + T3 精准回退
+>
+> **核心规则**: 分析→决策→执行→验证，最多 3 次循环
+
+### 3.1 修复循环流程
+
+```
+检测障碍 → 分析根因 → 决策策略 → 执行修复 → 验证结果
+    ↑                                      │
+    └──────────── 最多 3 次循环 ─────────────┘
+```
+
+### 3.2 错误分类与修复策略
+
+| 错误类型 | 自主修复策略 | 示例 |
+|---------|------------|------|
+| **依赖类** | 自动添加/安装 | 缺少 npm/Maven 包 |
+| **配置类** | 自动修正配置 | 配置文件错误 |
+| **代码类** | 自动修正代码 | 语法错误、类型错误 |
+| **资源类** | 自动创建/下载 | 文件缺失、目录不存在 |
+| **验证类** | 自动重试/修正 | 测试失败、编译错误 |
+| **逻辑类** | 需人工确认 | 业务逻辑错误、需求歧义 |
+
+### 3.3 修复边界（进化分区）
+
+| 区域 | 内容 | 修复方式 |
+|------|------|---------|
+| 🔴 **冻结区** | 宪法文件、核心原则 | 不可自主修改，直接 BLOCKED |
+| 🟡 **受控区** | 框架核心机制、接口契约 | 需人工批准，生成修复提案 |
+| 🟢 **自由区** | 依赖添加、配置修正、语法错误 | 可自主修复，修复后验证 |
+
+### 3.4 三级修复循环
+
+```
+Level 内联重试:
+  生成失败立即单次重试
+
+Level 修正循环:
+  结构化诊断反馈 → 定向修复 → 重验证（最多 3 次）
+
+Level 人工升级:
+  提交 3 次产出 + 3 次诊断 + AI 的"为什么反复不过"分析
+```
+
+### 3.5 追溯关系
+
+- **上游**: S1 双层验证、T3 精准回退、P1 验证为王
+- **下游**: `knowledge/01-principles/08-auto-fix-principles.md`
+
+---
+
+## 四、O3: 宪法门禁 (Constitution Gate)
+
+> **源自**: P1 验证为王 + P3 渐进自主 + S1 双层验证
+>
+> **核心规则**: 15 条红线，违反即停线
+
+### 4.1 安全红线（不可违反）
+
+| 红线 | 说明 | 违反信号 |
+|------|------|---------|
+| #1 不可逆动作人工确认 | DB 迁移、生产部署、外部 API 调用 | 未经人工确认就执行 |
+| #2 敏感信息不硬编码 | 密钥、密码、Token | 代码中出现明文秘钥 |
+| #3 安全漏洞零容忍 | SQL 注入、XSS、CSRF、越权 | 检测到安全漏洞 |
+
+### 4.2 流程红线（必须执行）
+
+| 红线 | 说明 | 违反信号 |
+|------|------|---------|
+| #4 启动门禁不跳过 | 读 pipeline→读宪法→确认范围 | 未确认就直接开始 |
+| #5-6 Layer 1 真实执行 | 编译/测试/lint 必须真实执行 | 用静态分析替代真实执行 |
+| #7 做审必须分离 | 不同 AI 实例执行 | 同一上下文切换角色 |
+| #8 回退上限 3 次 | 同一问题最多修复 3 次 | 超过 3 次继续修复 |
+| #9 关键假设显式记录 | 假设必须写在文件中 | 假设留在对话中 |
+
+### 4.3 决策红线
+
+| 红线 | 说明 | 违反信号 |
+|------|------|---------|
+| #10 方向性决策人工确认 | 需求方向、架构重大变更 | AI 自主决定方向 |
+| #11 知情猜测有上限 | 最多 3 个 NEEDS CLARIFICATION | 超过 3 个不确定项 |
+
+### 4.4 停线条件（立即停止）
+
+检测到以下情况必须停止全流程：
+- 安全漏洞（SQL 注入、XSS、凭证泄露）
+- 数据丢失风险
+- 测试覆盖率低于阈值
+- 编译错误无法在 3 次内修复
+- AI 自我判断置信度极低
+
+### 4.5 追溯关系
+
+- **上游**: P1 验证为王、P3 渐进自主、S1 双层验证
+- **下游**: `knowledge/01-principles/09-constitution.md`
+
+---
+
+## 五、O4: 检查清单 (Checklists)
+
+> **源自**: T4 反模式预判 + S1 双层验证
+>
+> **核心规则**: 5 阶段清单，嵌入式自检
+
+### 5.1 各阶段检查清单
+
+| 阶段 | 检查清单文件 | 核心检查项 |
+|------|-------------|-----------|
+| **需求分析** | `checklists/requirement.md` | 必填章节、业务完整性、技术可行性 |
+| **方案设计** | `checklists/design.md` | 两步生成、设计质量、架构规范 |
+| **编码实现** | `checklists/code.md` | Layer 1 验证、编码规范、代码质量 |
+| **测试** | `checklists/test.md` | 测试策略、覆盖率、边界场景 |
+| **发布** | `checklists/release.md` | 前置检查、回滚方案、监控告警 |
+
+### 5.2 检查清单设计原则
+
+**嵌入式自检**:
+- 检查清单嵌入到产出模板中
+- 生产者完成后必须先自检
+- 审查者独立检查
+
+**强制字段**:
+- 不填 = schema 校验不通过
+- 不确定性标记（`[NEEDS CLARIFICATION]`，最多 3 个）
+
+### 5.3 追溯关系
+
+- **上游**: T4 反模式预判、S1 双层验证
+- **下游**: `knowledge/04-checklists/` 各阶段清单
+
+---
+
+## 六、原则应用矩阵
+
+### 6.1 按错误类型应用
+
+| 错误类型 | 应用原则 | 处理方式 |
+|---------|---------|---------|
+| **代码规范问题** | O1 编码规范 | 按 coding-style 修正 |
+| **编译/测试失败** | O2 自主修复 | 诊断→修复→验证（最多 3 次） |
+| **安全红线违反** | O3 宪法门禁 | 立即停线→升级人工 |
+| **阶段完成遗漏** | O4 检查清单 | 补全检查项→自检通过 |
+
+### 6.2 原则检查清单
+
+**编码实现前**:
+- [ ] 已扫描项目现有能力（O1）
+- [ ] 已了解项目技术栈（O1）
+- [ ] 已准备必要的知识（O1）
+
+**编码实现中**:
+- [ ] 遵守一锁二判三更新（O1）
+- [ ] 使用 LogUtil 打印日志（O1）
+- [ ] 禁止硬编码（O1）
+- [ ] 遵守 SOLID+DDD 原则（O1）
+
+**遇到错误时**:
+- [ ] 执行自主修复流程（O2）
+- [ ] 修复循环不超过 3 次（O2）
+- [ ] 未违反宪法红线（O3）
+
+**阶段完成时**:
+- [ ] 已完成检查清单自检（O4）
+- [ ] Layer 1 验证通过（O4）
+- [ ] 关键假设已记录（O3）
+
+---
+
+## 七、关联文档
+
+| 文档 | 说明 |
+|------|------|
+| [03-tactical-principles.md](03-tactical-principles.md) | L3 战术原则（T1-T6） |
+| `knowledge/07-standards/00-coding-style.md` | 编码规范详情 |
+| `knowledge/01-principles/09-constitution.md` | 项目宪法详情 |
+| `knowledge/04-checklists/` | 各阶段检查清单 |
+
+---
+
+**维护者**: AutoSpec 团队
+**进化分区**: 🟡 受控区
+**关联原则**: T1 任务分解、T3 精准回退、T4 反模式预判、T5 驯服非确定性、T6 优先复用