@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/01-principles/02-strategic-principles.md

@@ -0,0 +1,286 @@
+# L2: 战略原则
+
+> **定位**: 由第一性原则演绎而来的方向性指导原则
+>
+> **进化分区**: 🔴 冻结区
+
+---
+
+## 一、原则体系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  L2: 战略原则 (Strategic Principles)                          │
+│  ─────────────────────────────────────────────────────────  │
+│  源自 L1 第一性原则，指导 L3 战术原则                            │
+│                                                              │
+│  S1 双层验证 | S2 做审分离 | S3 Harness 工程 | S4 知情猜测      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 追溯关系
+
+```
+L1 第一性原则          L2 战略原则              L3 战术原则
+─────────────────     ──────────────────      ──────────────────
+P1 验证为王    ────→   S1 双层验证      ────→   T3 精准回退
+                       S2 做审分离      ────→   T1 任务分解
+                                               T4 反模式预判
+P2 极简实用    ────→   S3 Harness 工程  ────→   T2 上下文管理
+                                               T6 优先复用
+P3 渐进自主    ────→   S4 知情猜测      ────→   T5 驯服非确定性
+                       安全制动
+```
+
+---
+
+## 二、S1: 双层验证 (Two-Layer Validation)
+
+> **源自**: P1 验证为王
+>
+> **核心规则**: Layer 1 不过，不进 Layer 2
+
+### 2.1 验证层级定义
+
+```
+Layer 1: 确定性验证（机器判断，不可协商）
+├── 编译通过
+├── 测试通过
+├── Lint 通过
+└── 类型检查通过
+
+Layer 2: AI 审查（AI 判断，处理机器判不了的）
+├── 架构合理性
+├── 需求覆盖度
+├── 设计一致性
+└── 安全评估
+```
+
+### 2.2 验证门禁铁律
+
+**无验证证据，不宣称完成**:
+- ✅ 可接受的证据：测试执行日志、构建输出、API 响应
+- ❌ 不可接受："应该能跑"、"我有信心"
+
+**理性化防御**:
+| AI 说辞 | 触发行动 |
+|--------|---------|
+| "should work now" | 必须执行，看到真实输出 |
+| "I'm confident" | 置信度不是证据，必须附带日志 |
+| "I already tested earlier" | 代码已变更，必须重新验证 |
+
+**完整性原则**:
+- AI 的边际成本极低，一次性做对最经济
+- 完整实现是"湖"（可达成），不是"洋"（遥不可及）
+- 不推荐捷径，当完整实现可达成时
+
+### 2.3 渐进式验证
+
+根据代码特征智能选择适用的规范类别：
+- 语法验证：在开发环境执行验证语法
+- 数据验收：多维度检查数据质量（如适用）
+- 影响分析：分析下游影响范围（如适用）
+
+### 2.4 实战应用
+
+```
+编码完成后 →
+  Layer 1: 编译通过 + 测试通过 + lint 通过 →
+  Layer 2: AI 审查（架构合理性/需求覆盖度）→
+  任一不通过 → 进入修复循环（T3 精准回退）
+```
+
+### 2.5 追溯关系
+
+- **上游**: P1 验证为王
+- **下游**:
+  - L3-T3 精准回退
+  - L4-O2 自主修复
+  - L4-Checklists 各阶段检查清单
+
+---
+
+## 三、S2: 做审分离 (Evaluator-Optimizer Separation)
+
+> **源自**: P1 验证为王 + P3 渐进自主
+>
+> **核心规则**: 做和审由不同 AI 实例执行
+
+### 3.1 信息隔离要求
+
+**审查 Agent 只获得**:
+- 产出物（文档/代码）
+- 方案文档
+- 审查标准
+
+**审查 Agent 不获得**:
+- 生成过程
+- 原始需求
+- 对话历史
+
+### 3.2 实现方式
+
+**进化方向**:
+- Phase 1: 同一模型不同 prompt（当前可行）
+- Phase 2: 不同模型互审（对抗性审查）
+- Phase 3: 编译器/测试作为"终极审查者"
+
+**反模式预判**:
+| 反模式 | 症状 | 风险 |
+|--------|------|------|
+| "太简单不用审查" | 跳过审查步骤 | 简单代码也会坏 |
+| "我先全做完再统一审查" | 延迟审查 | 成本指数增长 |
+| "审查通过了所以肯定对" | 盲目信任 | AI 审查不等于正确 |
+| "同一上下文切换角色" | 自我审查 | 失去客观性 |
+
+### 3.3 实战应用
+
+```
+需求分析完成后 →
+  启动 review-agent（独立上下文 + worktree）→
+  审查输入：requirement.md + 需求原始描述 + 审查清单 →
+  审查输出：结构化问题列表 + 修复建议
+```
+
+### 3.4 追溯关系
+
+- **上游**: P1 验证为王、P3 渐进自主
+- **下游**:
+  - L3-T1 多 Agent 编排
+  - L4-Code-Review AI 增强审查
+
+---
+
+## 四、S3: Harness Engineering 三部曲
+
+> **源自**: P2 极简实用
+>
+> **核心规则**: 不满意产出时，改 harness，不改产出
+
+### 4.1 三部曲定义
+
+```
+1. Context Engineering（知识基础）
+   ├── CLAUDE.md 层级设计
+   ├── skill 体系
+   └── 上下文分层（热/温/冷）
+
+2. Architectural Constraints（硬性约束）
+   ├── Hook 护栏
+   ├── 宪法门禁
+   └── 类型系统
+
+3. Garbage Collection（持续清洁）
+   ├── 定期一致性检查
+   └── 规格陈旧检测
+```
+
+### 4.2 实战应用
+
+```
+AI 产出质量差 →
+  分析：harness 缺什么？→
+  改 Context：增加相关 skill 加载 →
+  改 Constraints：增加 Hook 检查 →
+  改 GC：增加定期一致性检查 →
+  重新执行任务
+```
+
+### 4.3 追溯关系
+
+- **上游**: P2 极简实用
+- **下游**:
+  - L3-T2 上下文精确管理
+  - L3-进化机制
+
+---
+
+## 五、S4: 知情猜测 (Informed Guessing)
+
+> **源自**: P3 渐进自主
+>
+> **核心规则**: 最多 3 个 NEEDS CLARIFICATION，其余做合理默认
+
+### 5.1 自主决策边界
+
+| 决策类型 | 谁决定 | 例子 |
+|---------|--------|------|
+| 需求方向 | 人 | 做不做这个功能 |
+| 架构重大变更 | 人 | 换数据库、换框架 |
+| 安全敏感 | 人 | 鉴权方案、数据加密 |
+| 技术选型（栈内） | AI 自主 | 用哪个库、API 设计 |
+| 实现细节 | AI 自主 | 算法选择、代码结构 |
+| 不确定项 | AI 做合理默认 + 标记 | 最多 3 个 NEEDS CLARIFICATION |
+
+### 5.2 知情猜测原则
+
+**无人值守系统不能频繁停下来等人**:
+- 最多 3 个 NEEDS CLARIFICATION 标记
+- 其余做合理默认但不可隐藏假设
+- 合理默认值必须记录在文件中
+
+### 5.3 实战应用
+
+```
+需求歧义识别 →
+  分类扫描（11 个维度）→
+  优先级排序（Impact × Uncertainty）→
+  有界提问（最多 5 个问题，每个附推荐答案）→
+  原子更新（每个回答立即更新到需求文档）
+```
+
+### 5.4 追溯关系
+
+- **上游**: P3 渐进自主
+- **下游**:
+  - L3-T5 驯服非确定性
+  - L2-宪法#11
+
+---
+
+## 六、原则应用矩阵
+
+### 6.1 按错误类型应用
+
+| 错误类型 | 应用原则 | 处理方式 |
+|---------|---------|---------|
+| **验证失败** | S1 双层验证 | Layer 1 失败 → 修复后重测 |
+| **架构问题** | S2 做审分离 | 独立审查 → 生成提案 → 人工确认 |
+| **产出质量差** | S3 Harness 工程 | 分析 harness 缺陷 → 改进 → 重执行 |
+| **需求歧义** | S4 知情猜测 | 合理默认 + 标记（最多 3 个） |
+
+### 6.2 原则检查清单
+
+**执行任务前**:
+- [ ] 已理解双层验证要求（S1）
+- [ ] 已规划做审分离方案（S2）
+- [ ] 已准备必要的 harness（S3）
+- [ ] 已识别可能的不确定项（S4）
+
+**执行任务中**:
+- [ ] Layer 1 验证真实执行（S1）
+- [ ] 审查由独立 Agent 执行（S2）
+- [ ] harness 持续改进（S3）
+- [ ] 不确定项不超过 3 个（S4）
+
+**执行任务后**:
+- [ ] Layer 1+Layer 2 均通过（S1）
+- [ ] 审查记录完整（S2）
+- [ ] harness 改进已记录（S3）
+- [ ] 假设已显式记录（S4）
+
+---
+
+## 七、关联文档
+
+| 文档 | 说明 |
+|------|------|
+| [01-first-principles.md](01-first-principles.md) | L1 第一性原则（P1/P2/P3） |
+| [03-tactical-principles.md](03-tactical-principles.md) | L3 战术原则（T1-T6） |
+| [09-constitution.md](09-constitution.md) | 项目宪法（15 条红线） |
+
+---
+
+**维护者**: AutoSpec 团队
+**进化分区**: 🔴 冻结区
+**关联原则**: P1 验证为王、P2 极简实用、P3 渐进自主

package/knowledge/01-principles/03-tactical-principles.md

@@ -0,0 +1,385 @@
+# L3: 战术原则
+
+> **定位**: 由战略原则展开而来的执行策略指导原则
+>
+> **进化分区**: 🟡 受控区（自动提议 + 人工批准）
+
+---
+
+## 一、原则体系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  L3: 战术原则 (Tactical Principles)                           │
+│  ─────────────────────────────────────────────────────────  │
+│  源自 L2 战略原则，指导 L4 操作原则                            │
+│                                                              │
+│  T1 任务分解 | T2 上下文管理 | T3 精准回退                    │
+│  T4 反模式预判 | T5 驯服非确定性 | T6 优先复用                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 追溯关系
+
+```
+L2 战略原则              L3 战术原则              L4 操作原则
+─────────────────      ──────────────────      ──────────────────
+S1 双层验证      ────→   T3 精准回退      ────→   O2 自主修复
+S2 做审分离      ────→   T1 任务分解      ────→   O4 检查清单
+                       T4 反模式预判
+
+S3 Harness 工程  ────→   T2 上下文管理    ────→   O1 编码规范
+                       T6 优先复用
+
+S4 知情猜测      ────→   T5 驯服非确定性  ────→   O3 宪法门禁
+```
+
+---
+
+## 二、T1: 任务分解质量 (ATOMIC 原则)
+
+> **源自**: S2 做审分离 + S4 知情猜测
+>
+> **核心规则**: 任务分解质量决定自主成功率
+
+### 2.1 三视角拆分触发条件
+
+```
+视角 1: 系统边界 → 涉及多子系统？→ 按系统拆 Phase，明确系统间依赖
+视角 2: 任务规模 → 预估 > 16 小时？→ 在 Phase 内按功能拆 Task（每任务 2-4h）
+视角 3: 阶段依赖 → 有明确阶段约束？→ 按 AI 验证→后端→前端 顺序排列
+
+任一满足 → 必须拆解
+```
+
+### 2.2 ATOMIC 原则
+
+每个任务必须满足：
+
+| 字母 | 含义 | 检查点 |
+|------|------|--------|
+| **A**utonomous | 可独立执行 | 不依赖其他任务的中间状态 |
+| **T**estable | 有明确的验证标准 | 不是"看起来对" |
+| **O**bservable | 执行结果可观测 | 有输出、有日志 |
+| **M**odest | 2-4 小时工作量 | 当前 AI sweet spot |
+| **I**nformed | 包含完整上下文 | 不假设执行者知道任何背景 |
+| **C**onstrained | 明确边界 | 做什么、不做什么、不能碰什么 |
+
+### 2.3 依赖类型与并行判断
+
+**依赖类型**:
+```
+→data     数据依赖：上游产出作为下游输入（如：API 定义 → 前端对接）
+→logic    逻辑依赖：业务流程顺序约束（如：创建用户 → 分配权限）
+→res      资源依赖：共享资源需串行访问（如：数据库迁移）
+→contract 契约解耦：通过定义标准产出物解耦（如：API 契约 → 双方并行）
+→mock     Mock 并行：下游基于 Mock 开发，上游完成后联调
+```
+
+**并行判断四问**:
+```
+1. 是否无共享写入资源？→ 是则可并行
+2. 是否无执行顺序约束？→ 是则可并行
+3. 失败是否互不影响？→ 是则可并行
+4. 合并成本是否低？→ 是则可并行
+```
+
+**解耦并行判断**:
+```
+1. 是否可定义标准产出物？（API 契约、数据 Schema、接口定义）
+2. 下游是否可基于标准独立验证？（Mock 测试、Schema 校验）
+3. 联调成本是否可控？
+→ 三者都满足 → 可解耦并行
+```
+
+### 2.4 可解耦场景
+
+**可解耦并行**:
+- 后端↔前端：API 契约（OpenAPI）→ 后端实现 ∥ 前端 Mock
+- 后端↔移动端：API 契约 → 后端实现 ∥ 移动端 Mock
+- 数据↔后端：数据 Schema → 数据管道 ∥ 后端接口
+- AI↔后端：模型接口定义 → 模型训练 ∥ 后端服务
+
+**不可解耦场景**:
+- 数据库迁移（资源依赖）
+- 核心业务流程顺序（逻辑依赖：订单→支付→发货）
+- AI 效果验证（逻辑依赖：效果不达标则后续无意义）
+
+### 2.5 任务编排模式
+
+```
+串行模式（不可解耦依赖）:
+  P1 →data→ P2 →logic→ P3
+
+解耦并行模式（契约解耦）:
+  [契约定义] →contract→ P2 实现 ∥ P3 实现 → 联调
+
+原生并行模式（无依赖）:
+  P2 →data→ P3 [P] ┐
+                  ├→ 集成
+       →data→ P4 [P] ┘
+```
+
+### 2.6 追溯关系
+
+- **上游**: S2 做审分离、S4 知情猜测
+- **下游**: L4-Process 各阶段流程
+
+---
+
+## 三、T2: 上下文精确管理
+
+> **源自**: S3 Harness Engineering
+>
+> **核心规则**: 热/温/冷分层，按需加载
+
+### 2.1 三层知识架构
+
+```
+热层（始终加载）
+├── 项目宪法
+├── 核心规范
+└── 当前任务上下文
+
+温层（按需加载）
+├── 角色 profile
+├── 阶段 skill
+└── 领域知识
+
+冷层（检索加载）
+├── 详细文档
+├── 历史案例
+└── 完整代码
+```
+
+### 2.2 管理规则
+
+**阶段间传递**:
+- 传递精炼的结构化契约，不传原文
+- 每个 agent 独立上下文 + worktree 隔离
+- 关键决策写入文件（不留在对话中）
+
+**压缩策略**:
+- 60-70% 容量主动压缩
+- 优先观察遮蔽，慎用 LLM 摘要（摘要幻觉会传播）
+
+**预置知识**:
+- 执行任务前检查是否有相关领域知识文件
+- 有则读取融入上下文
+
+### 2.3 追溯关系
+
+- **上游**: S3 Harness Engineering
+- **下游**: L4-Skill 体系、L4-Environment 知识
+
+---
+
+## 四、T3: 精准回退 (Precision Rollback)
+
+> **源自**: S1 双层验证 + P1 验证为王
+>
+> **核心规则**: 只重处理失败项，不全量重做
+
+### 4.1 三级嵌套自愈
+
+```
+Level 1: 内联重试
+  └── 生成失败立即单次重试
+
+Level 2: 修正循环（最多 3 次）
+  ├── 结构化诊断反馈
+  ├── 定向修复
+  └── 重验证
+
+Level 3: 人工升级
+  ├── 提交 3 次产出
+  ├── 提交 3 次诊断
+  └── AI 的"为什么反复不过"分析
+```
+
+### 4.2 实战应用
+
+```
+验证失败 →
+  错误分类 →
+  Level 1: 内联重试 →
+  仍失败 →
+  Level 2: 修正循环（诊断→修复→验证，最多 3 次）→
+  仍失败 →
+  Level 3: 升级人工（附完整诊断）
+```
+
+### 4.3 追溯关系
+
+- **上游**: S1 双层验证、P1 验证为王
+- **下游**: L4-Auto-Fix-Loop 自主修复机制
+
+---
+
+## 五、T4: 反模式预判 (Anti-Pattern Inoculation)
+
+> **源自**: S1 双层验证 + S4 知情猜测
+>
+> **核心规则**: 在每个 skill 中预判 AI 会"偷懒"或"走捷径"的所有路径并堵死
+
+### 5.1 通用反模式清单
+
+| 反模式 | 症状 | 预防方式 |
+|--------|------|---------|
+| 蛮力修复 | @JsonIgnore、跳过测试、增加内存 | 强制验证门禁 |
+| 虚假成功声明 | 红色测试时称完成 | Layer 1 必须真实执行 |
+| 假设填充不一致 | 优先级字段在不同运行间变化 | 假设管理协议 |
+| 范围蔓延 | 从术语自动推导未要求的业务逻辑 | 明确边界约束 |
+| 假设漂移 | 业务逻辑假设无声改变 | 阶段间传递结构化契约 |
+| 重复造轮子 | 不搜索现有实现就新建 | T6 优先复用 |
+
+### 5.2 追溯关系
+
+- **上游**: S1 双层验证、S4 知情猜测
+- **下游**: L4-Checklists 各阶段检查清单
+
+---
+
+## 六、T5: 驯服非确定性 (Taming Non-Determinism)
+
+> **源自**: P3 渐进自主 + S4 知情猜测
+>
+> **核心规则**: 非确定性不是 bug，是 LLM 的本质特征。不能消除，只能管理。
+
+### 6.1 四道防线
+
+```
+防线 1: 约束输出空间
+├── 结构化输出格式（JSON Schema / 模板填充）
+├── 明确的"做什么 + 不做什么"边界
+├── 反模式清单堵死捷径路径
+└── 枚举所有合法选项（而不是开放式生成）
+
+防线 2: 锚定一致性
+├── 关键假设必须显式记录在文件中（不留在对话中）
+├── 阶段间传递结构化契约（防止假设漂移）
+├── 宪法门禁确保核心不变量
+└── 同一需求多次执行的结果差异必须在可接受范围内
+
+防线 3: 确定性验证兜底
+├── 编译器/类型系统/测试/lint——这些是确定性的
+├── 即使 AI 产出不同的代码，只要通过确定性验证就可接受
+└── "不同的路径到达同一个正确结果"是可以的
+
+防线 4: 人工审查关键决策
+├── 架构决策、安全方案、需求理解——这些不能容忍非确定性
+├── 用结构化 checklist（不是开放式审查）减少人工负担
+└── 人审的不是代码，而是决策和假设
+```
+
+### 6.2 假设管理协议
+
+```
+每个阶段的输出必须包含 `## 关键假设` 章节
+假设分为"已确认"和"待确认"
+待确认假设超过 3 个 → 升级为人工确认
+假设变更必须显式记录原因和影响范围
+```
+
+### 6.3 追溯关系
+
+- **上游**: P3 渐进自主、S4 知情猜测
+- **下游**: L4-Templates 模板、L4-Constitution 宪法门禁
+
+---
+
+## 七、T6: 优先复用项目现有能力
+
+> **源自**: P2 极简实用 + S3 Harness Engineering
+>
+> **核心规则**: 先搜索后实现，禁止硬编码
+
+### 7.1 强制要求
+
+**修复/实现前必须扫描**:
+- 扫描项目已有的 AOP 框架、Helper 工具类、Util 类
+- 扫描 environment 知识文件，了解项目使用的中间件和组件
+- 识别项目已有的技术选型和架构模式
+
+**禁止硬编码**:
+- 不可在代码中硬编码目录名、包名、类名、配置项
+- 必须从环境知识文件、配置文件中动态读取
+- 支持不同项目的差异化配置
+
+**复用优先于新建**:
+- 项目已有 AOP 框架 → 使用 AOP 切面方式，不手动埋点
+- 项目已有 Helper 工具 → 调用 Helper 方法，不重复实现
+- 项目已有 Util 类 → 使用 Util 工具，不自己造轮子
+
+### 7.2 设计原则约束
+
+- 面向接口编程（依赖倒转原则）
+- 对扩展开放、对修改关闭（开闭原则）
+- 变化点封装隔离（面向变化设计）
+- 高内聚低耦合
+- 单一职责
+
+### 7.3 违反示例（禁止行为）
+
+| ❌ 禁止行为 | ✅ 正确做法 |
+|-----------|-----------|
+| 项目已有 `AgentTracingHelper`，却自己新建一个埋点类 | 复用项目已有的 `AgentTracingHelper` |
+| 项目已有 AOP 切面模式，却直接在业务代码中硬编码埋点 | 使用项目已有的 AOP 切面模式进行埋点 |
+| 在代码中硬编码 `pom.xml`、`src/main/java` 等路径 | 从配置文件或环境知识中动态读取路径 |
+| 项目已有 `LogUtil`，却直接使用 `logger.info()` | 使用 `LogUtil.info()` |
+| 不考虑项目已有的技术栈，直接引入新的依赖 | 先读取 environment 了解项目技术栈 |
+
+### 7.4 追溯关系
+
+- **上游**: P2 极简实用、S3 Harness Engineering
+- **下游**: L4-Coding-Style 编码规范
+
+---
+
+## 八、原则应用矩阵
+
+### 8.1 按阶段应用
+
+| 阶段 | 核心原则 | 支撑原则 |
+|------|---------|---------|
+| **需求分析** | T1 任务分解 | S4 知情猜测、T5 驯服非确定性 |
+| **方案设计** | T1 任务分解、T6 优先复用 | S2 做审分离、T4 反模式预判 |
+| **编码实现** | T6 优先复用 | T3 精准回退、T4 反模式预判 |
+| **代码审查** | T4 反模式预判 | S2 做审分离 |
+| **测试** | T3 精准回退 | S1 双层验证 |
+| **错误修复** | T3 精准回退 | T4 反模式预判 |
+
+### 8.2 原则检查清单
+
+**执行任务前**:
+- [ ] 任务已按 ATOMIC 原则分解（T1）
+- [ ] 上下文已按需加载（T2）
+- [ ] 已扫描项目现有能力（T6）
+- [ ] 已识别可能的反模式（T4）
+
+**执行任务中**:
+- [ ] 只重处理失败项（T3）
+- [ ] 假设已显式记录（T5）
+- [ ] 优先复用现有能力（T6）
+- [ ] 未触发反模式（T4）
+
+**执行任务后**:
+- [ ] 修复循环未超过 3 次（T3）
+- [ ] 不确定项不超过 3 个（T5）
+- [ ] 未重复造轮子（T6）
+
+---
+
+## 九、关联文档
+
+| 文档 | 说明 |
+|------|------|
+| [02-strategic-principles.md](02-strategic-principles.md) | L2 战略原则（S1-S4） |
+| [04-operational-principles.md](04-operational-principles.md) | L4 操作原则（O1-O4） |
+| [05-domain-principles.md](05-domain-principles.md) | 领域实践原则 |
+
+---
+
+**维护者**: AutoSpec 团队
+**进化分区**: 🟡 受控区
+**关联原则**: S1 双层验证、S2 做审分离、S3 Harness 工程、S4 知情猜测