@chongyan/autospec 1.0.2 → 1.0.3

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

@@ -1,286 +0,0 @@
-# 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

@@ -1,385 +0,0 @@
-# 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 知情猜测