@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/01-principles/00-principles-hierarchy.md

@@ -0,0 +1,247 @@
+# AutoSpec 原则体系总纲
+
+> **定位**: 框架的"原则操作系统"索引，所有执行决策必须能追溯到本文的原则
+>
+> **版本**: v2.0
+> **最后更新**: 2026-03-27
+> **进化分区**: 🔴 冻结区
+
+---
+
+## 一、原则体系总览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  L1: 第一性原则 (First Principles) — 不可违背的"物理定律"      │
+│  ─────────────────────────────────────────────────────────  │
+│  验证为王 | 极简实用 | 渐进自主                                │
+│  → 位于：01-first-principles.md                               │
+└─────────────────────────────────────────────────────────────┘
+                              │ 演绎
+┌─────────────────────────────────────────────────────────────┐
+│  L2: 战略原则 (Strategic Principles) — 方向性指导              │
+│  ─────────────────────────────────────────────────────────  │
+│  双层验证 | 做审分离 | Harness 工程 | 知情猜测                  │
+│  → 位于：02-strategic-principles.md                           │
+└─────────────────────────────────────────────────────────────┘
+                              │ 展开
+┌─────────────────────────────────────────────────────────────┐
+│  L3: 战术原则 (Tactical Principles) — 执行策略指导             │
+│  ─────────────────────────────────────────────────────────  │
+│  任务分解 | 上下文管理 | 精准回退 | 反模式预判 | 驯服非确定性    │
+│  → 位于：03-tactical-principles.md                            │
+└─────────────────────────────────────────────────────────────┘
+                              │ 落地
+┌─────────────────────────────────────────────────────────────┐
+│  L4: 操作原则 (Operational Principles) — 具体行为规范          │
+│  ─────────────────────────────────────────────────────────  │
+│  编码规范 | 自主修复 | 宪法门禁 | 检查清单                     │
+│  → 位于：04-operational-principles.md                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、原则文件导航
+
+| 文件 | 层次 | 内容说明 |
+|------|------|---------|
+| [00-principles-hierarchy.md](00-principles-hierarchy.md) | 总纲 | 原则体系索引、追溯链、应用矩阵 |
+| [01-first-principles.md](01-first-principles.md) | L1 | 第一性原则（P1-P3 三棱锥） |
+| [02-strategic-principles.md](02-strategic-principles.md) | L2 | 战略原则（S1-S4） |
+| [03-tactical-principles.md](03-tactical-principles.md) | L3 | 战术原则（T1-T6） |
+| [04-operational-principles.md](04-operational-principles.md) | L4 | 操作原则（O1-O4） |
+| [05-domain-principles.md](05-domain-principles.md) | 领域 | 领域实践原则（DDD/系统/需求/编码/CR/知识管理） |
+| [06-methodology-principles.md](06-methodology-principles.md) | 通用 | 通用方法论原则（P1-P44） |
+| [07-cognitive-principles.md](07-cognitive-principles.md) | 认知 | 认知增强原则（CP1-CP10） |
+| [08-auto-fix-principles.md](08-auto-fix-principles.md) | 专题 | 自主修复原则（实战经验提炼） |
+| [09-constitution.md](09-constitution.md) | 宪法 | 15 条红线（违反即停线） |
+| [10-evolution-mechanism.md](10-evolution-mechanism.md) | 进化 | 三层进化机制 |
+
+---
+
+## 三、原则追溯链
+
+### 3.1 L1→L2→L3→L4 完整追溯
+
+```
+L1 第一性原则（三棱锥）
+├── P1 验证为王
+│   ├── → L2-S1 双层验证
+│   │   └── → L3-T3 精准回退
+│   │       └── → L4-O2 自主修复
+│   ├── → L2-DP5 强制预学习 + 检查点
+│   └── → L2-宪法#5-6 Layer 1 必须真实执行
+│
+├── P2 极简实用
+│   ├── → L2-S3 Harness Engineering
+│   │   └── → L3-T2 上下文精确管理
+│   ├── → L2-DP16 成本经济学
+│   └── → L3-T1 任务分解质量（ATOMIC 原则）
+│
+└── P3 渐进自主
+    ├── → L2-宪法#10-11 方向性决策人工确认
+    ├── → L2-S4 知情猜测
+    │   └── → L3-T5 驯服非确定性
+    └── → L2-DP12 安全与紧急制动
+```
+
+### 3.2 原则应用矩阵
+
+| 阶段 | 核心原则 | 支撑原则 |
+|------|---------|---------|
+| **需求分析** | S4 知情猜测、T1 任务分解 | CP1 合伙人模式、CP3 先问后做、T5 驯服非确定性 |
+| **方案设计** | T1 任务分解、T6 优先复用 | S2 做审分离、T4 反模式预判、DDD 原则 |
+| **编码实现** | O1 编码规范、O2 自主修复 | S1 双层验证、T3 精准回退、SOLID 原则 |
+| **代码审查** | S2 做审分离、O4 检查清单 | T4 反模式预判、AI 增强审查 |
+| **测试** | S1 双层验证、O4 检查清单 | P1 验证为王、测试覆盖原则 |
+| **交付部署** | O3 宪法门禁、O4 检查清单 | P3 渐进自主、回滚方案原则 |
+
+### 3.3 原则速查表
+
+#### L1: 第一性原则（3 条）
+
+| 原则 | 一句话 | 应用场景 |
+|------|--------|---------|
+| P1 验证为王 | 确定性验证 > AI 审查 > AI 自审 | 所有产出物验证 |
+| P2 极简实用 | 能一个文件说清的不拆两个 | 知识管理、任务分解 |
+| P3 渐进自主 | 从"人审每步"到"人只管 harness" | 自主决策边界 |
+
+#### L2: 战略原则（4 条）
+
+| 原则 | 一句话 | 应用场景 |
+|------|--------|---------|
+| S1 双层验证 | Layer 1 不过，不进 Layer 2 | 所有阶段完成前 |
+| S2 做审分离 | 做和审由不同 AI 实例执行 | 审查任务启动 |
+| S3 Harness 工程 | 不满意产出时，改 harness | 产出质量差时 |
+| S4 知情猜测 | 最多 3 个 NEEDS CLARIFICATION | 需求歧义处理 |
+
+#### L3: 战术原则（6 条）
+
+| 原则 | 一句话 | 应用场景 |
+|------|--------|---------|
+| T1 任务分解 | ATOMIC 原则，2-4 小时粒度 | 任务拆解 |
+| T2 上下文管理 | 热/温/冷分层，按需加载 | 知识加载 |
+| T3 精准回退 | 只重处理失败项，不全量重做 | 修复循环 |
+| T4 反模式预判 | 堵死 6 种捷径路径 | skill 设计 |
+| T5 驯服非确定性 | 四道防线，假设管理 | 关键决策 |
+| T6 优先复用 | 先搜索后实现，禁止硬编码 | 编码/修复 |
+
+#### L4: 操作原则（4 条）
+
+| 原则 | 一句话 | 应用场景 |
+|------|--------|---------|
+| O1 编码规范 | SOLID+DDD，一锁二判三更新 | 代码编写 |
+| O2 自主修复 | 分析→决策→执行→验证，最多 3 次 | 错误处理 |
+| O3 宪法门禁 | 15 条红线，违反即停线 | 全流程 |
+| O4 检查清单 | 5 阶段清单，嵌入式自检 | 阶段完成 |
+
+---
+
+## 四、原则追溯示例
+
+### 场景 1: Maven 依赖缺失
+
+```
+错误发生
+    ↓
+L4-O2 自主修复机制 → 错误分类（依赖类）
+    ↓
+L3-T6 优先复用项目现有能力 → 扫描现有 pom.xml
+    ↓
+L3-T3 精准回退 → Level 2 修正循环
+    ↓
+L2-S1 双层验证 → 重新执行原命令验证
+    ↓
+L1-P1 验证为王 → 验证结果通过
+    ↓
+记录 practice-log → L3-进化机制
+```
+
+### 场景 2: 需求歧义澄清
+
+```
+需求歧义识别
+    ↓
+L2-S4 知情猜测 > 无限提问 → 做合理默认 + 标记
+    ↓
+L3-T5 驯服非确定性 → 防线 2 锚定一致性
+    ↓
+L2-宪法#11 → 最多 3 个 NEEDS CLARIFICATION
+    ↓
+L3-T4 反模式预判 → 防止假设漂移
+    ↓
+L4-templates → 写入需求文档
+```
+
+---
+
+## 五、进化分区
+
+| 分区 | 说明 | 变更方式 |
+|------|------|---------|
+| 🔴 **冻结区** | 宪法、进化规则、核心原则、设计哲学 | 人工变更，需经过完整的 review 流程 |
+| 🟡 **受控区** | 流程定义、通用 skills、检查清单、编码规范 | 自动提议 + 人工批准 |
+| 🟢 **自由区** | domain skills、benchmarks、支撑技能 | 自动进化 + validator 验证 |
+| 🔵 **环境知识区** | 中间件、组件、集成知识 | 项目级自动优化 |
+
+---
+
+## 六、使用指南
+
+### 6.1 快速定位原则
+
+**场景**: 遇到 X 问题，应该遵循什么原则？
+
+1. 识别问题类型（验证/自主/知识/修复/...）
+2. 查本节原则速查表
+3. 追溯上游原则（理解为什么）
+4. 查看下游操作规范（知道怎么做）
+
+**示例**:
+```
+问题："AI 总是重复造轮子，不扫描现有代码"
+→ 问题类型：知识管理/复用
+→ 速查表：T6 优先复用项目现有能力
+→ 上游原则：P2 极简实用、S3 Harness Engineering
+→ 下游操作：04-operational-principles.md 编码规范、08-auto-fix-principles.md AFP3
+```
+
+### 6.2 原则应用检查点
+
+**执行任务前**:
+- [ ] 已读取本文档，理解相关原则
+- [ ] 已识别任务类型和适用原则
+- [ ] 已准备好必要的知识（热层/温层）
+
+**执行任务中**:
+- [ ] 遵循 ATOMIC 原则分解任务
+- [ ] 遵循知情猜测原则（最多 3 个不确定项）
+- [ ] 遵循做审分离原则（审查启动独立 Agent）
+
+**执行任务后**:
+- [ ] 遵循双层验证原则（Layer 1+Layer 2）
+- [ ] 遵循检查清单原则（阶段自检）
+- [ ] 遵循实践日志原则（记录经验）
+
+---
+
+## 七、关联文档
+
+| 文档 | 说明 |
+|------|------|
+| [01-first-principles.md](01-first-principles.md) | L1 第一性原则（三棱锥 P1/P2/P3） |
+| [02-strategic-principles.md](02-strategic-principles.md) | L2 战略原则（S1-S4） |
+| [03-tactical-principles.md](03-tactical-principles.md) | L3 战术原则（T1-T6） |
+| [04-operational-principles.md](04-operational-principles.md) | L4 操作原则（O1-O4） |
+| [05-domain-principles.md](05-domain-principles.md) | 领域实践原则 |
+| [06-methodology-principles.md](06-methodology-principles.md) | 通用方法论原则（P1-P44） |
+| [07-cognitive-principles.md](07-cognitive-principles.md) | 认知增强原则（CP1-CP10） |
+| [08-auto-fix-principles.md](08-auto-fix-principles.md) | 自主修复原则 |
+| [09-constitution.md](09-constitution.md) | 项目宪法（15 条红线） |
+| [10-evolution-mechanism.md](10-evolution-mechanism.md) | 三层进化机制 |
+
+---
+
+**维护者**: AutoSpec 团队
+**反馈渠道**: 知识库 Git 仓库 Issue

package/knowledge/01-principles/01-first-principles.md

@@ -0,0 +1,241 @@
+# L1: 第一性原则
+
+> **定位**: AutoSpec 的"物理定律"，所有上层原则都由此演绎而来
+>
+> **进化分区**: 🔴 冻结区
+
+---
+
+## 一、原则体系
+
+```
+        验证为王 (P1)
+       /        \
+      /          \
+  极简实用 (P2) ———— 渐进自主 (P3)
+```
+
+这三个原则是 AutoSpec 的"物理定律"，不可违背。所有 L2/L3/L4 原则都由此演绎而来。
+
+### 追溯关系
+
+```
+L1 第一性原则          L2 战略原则              L3 战术原则
+─────────────────     ──────────────────      ──────────────────
+P1 验证为王    ────→   S1 双层验证      ────→   T3 精准回退
+                       S2 做审分离
+P2 极简实用    ────→   S3 Harness 工程  ────→   T2 上下文管理
+                                               T6 优先复用
+P3 渐进自主    ────→   S4 知情猜测      ────→   T5 驯服非确定性
+```
+
+---
+
+## 二、P1: 验证为王 (Verification-First)
+
+> "加速验证循环，而不是等待模型改进。"
+> "当 agent 犯难时，把它当作信号：识别缺什么。"
+
+### 核心含义
+
+**确定性验证（编译器/测试/lint）> AI 审查 > AI 自审**
+
+- 每一步必须出示可验证的证据，不接受"我做完了"
+- 框架的核心投入应在验证基础设施，不在生成能力
+- AST+ 编译器验证确保编译成功
+- 证据驱动交付，每步出示审计日志
+- 没有失败测试就不能写代码
+- 虚假成功声明是系统性失败模式
+
+### 验证门禁铁律（Iron Law）
+
+**无验证证据，不宣称完成**:
+- ✅ 可接受的证据：测试执行日志、构建输出、API 响应
+- ❌ 不可接受："应该能跑"、"我有信心"
+
+**理性化防御**:
+| AI 说辞 | 触发行动 |
+|--------|---------|
+| "should work now" | 必须执行，看到真实输出 |
+| "I'm confident" | 置信度不是证据，必须附带日志 |
+| "I already tested earlier" | 代码已变更，必须重新验证 |
+
+**完整性是廉价的**:
+- AI 的边际成本极低，一次性做对最经济
+- 完整实现是"湖"（可达成），不是"洋"（遥不可及）
+- 不推荐捷径，当完整实现可达成时
+
+### 演绎出的上层原则
+
+- → L2-S1: 双层验证（Layer 1 确定性 + Layer 2 AI 审查）
+- → L2-DP5: 强制预学习 + 检查点（验证知识准备）
+- → L2-宪法#5-6: Layer 1 必须真实执行
+- → L3-T3: 精准回退（验证失败后只重处理失败项）
+- → L4-coding: 一锁二判三更新、金额用 Money 类
+
+### 实战应用
+
+```
+遇到依赖缺失错误 →
+  错误分类（依赖类）→
+  自主修复（安装依赖）→
+  验证结果（重新执行原命令）→
+  记录 practice-log
+```
+
+---
+
+## 三、P2: 极简实用 (Minimal Viable Process)
+
+> "使用者 5 分钟内能理解结构并开始使用。"
+> "Find the simplest solution possible."
+
+### 核心含义
+
+**能一个文件说清的不拆两个；能用 markdown/yaml 定义的不写代码**
+
+- 一种工作流不适合所有问题——按复杂度动态调整流程深度
+- 高频使用的提前建设，低频的用到再建
+- 审查输出必须极简结构化，不生成冗长 markdown
+- 渐进式加载，只在需要时才加载
+- 过度设计导致维护成本高
+
+### 演绎出的上层原则
+
+- → L2-S3: Harness Engineering 三部曲（Context/Constraints/GC）
+- → L2-DP4: 上下文精确管理（热/温/冷分层）
+- → L2-DP16: 成本经济学（Token Economics）
+- → L3-T1: 任务分解质量（ATOMIC 原则，2-4 小时粒度）
+- → L4-templates: 模板即约束（强制字段 + 不确定性标记）
+
+### 实战应用
+
+```
+遇到配置问题 →
+  先查 environment 知识（热层）→
+  不够再查 component 知识（温层）→
+  最后搜索代码库（冷层）
+```
+
+---
+
+## 四、P3: 渐进自主 (Progressive Autonomy)
+
+> "Human On the Loop——不检查产出物，而是工程化 harness。"
+> "信任曲线是真实的。"
+
+### 核心含义
+
+**从"人审每步"到"人只管 harness"的渐进路径**
+
+- AI 先在受约束领域证明可靠，再扩展自主范围
+- 当前 sweet spot：4-8 小时粒度的明确范围任务
+- 不确定时做合理默认值并标记（知情猜测），不停下来等人
+- AI 自主能力持续增长
+- 用户对自动化的接受度逐步提高
+- 特定领域可显著提升效率
+
+### 演绎出的上层原则
+
+- → L2-宪法#10-11: 方向性决策人工确认 + 知情猜测有上限
+- → L2-S4: 知情猜测 > 无限提问（自主决策边界表）
+- → L2-DP12: 安全与紧急制动（四层安全模型）
+- → L3-T5: 驯服非确定性（四道防线）
+- → L3-修复边界：冻结区/受控区/自由区
+
+### 实战应用
+
+```
+自主修复决策 →
+  冻结区（宪法文件）→ BLOCKED，直接升级人工
+  受控区（架构变更）→ 生成提案，等待人工批准
+  自由区（依赖缺失）→ 自主修复，修复后验证
+```
+
+---
+
+## 五、核心设计模式
+
+以下是由第一性原则演绎而来的核心设计模式，详细说明见 L2/L3 原则文档。
+
+### 两步生成（Two-Phase Generation）
+
+设计文档采用两步生成模式：
+1. **Phase 1: 大纲生成** - 先成功能点列表，全部标记为未完成 `- [ ]`
+2. **Phase 2: 逐个细化** - 逐个功能点写详细设计，每完成一个就打钩 `- [x]`
+
+优势：
+- 用户先确认大纲方向，避免整体返工
+- 逐个细化可中断，完成部分可直接使用
+- 进度可视化，用户随时知道完成度
+
+### 渐进式披露（Progressive Disclosure）
+
+知识分层管理：
+```
+Layer 1: Metadata（技能描述） → 触发条件
+Layer 2: SKILL.md（核心逻辑） → 执行步骤
+Layer 3: References（参考文档） → 详细规范
+```
+
+### 做审分离（Evaluator-Optimizer Separation）
+
+做和审由不同 AI 实例执行，通过 Agent 工具实现信息隔离：
+- 审查 Agent 只获得：产出物 + 方案文档 + 审查标准
+- 不获得：生成过程、原始需求、对话历史
+
+→ 详见：[02-strategic-principles.md](02-strategic-principles.md#三 s2-做审分离-evaluator-optimizer-separation)
+
+### Harness Engineering 三部曲
+
+不满意产出时，**改 harness**，不改产出：
+1. **Context Engineering** - 知识基础：CLAUDE.md 层级、skill 体系、上下文分层
+2. **Architectural Constraints** - 硬性约束：Hook 护栏、宪法门禁、类型系统
+3. **Garbage Collection** - 持续清洁：定期一致性检查、规格陈旧检测
+
+→ 详见：[02-strategic-principles.md](02-strategic-principles.md#四 s3-harness-engineering-三部曲)
+
+### 模板即约束（Template-as-Constraint）
+
+模板设计包含：
+- 强制字段（不填=schema 校验不通过）
+- 不确定性标记（`[NEEDS CLARIFICATION]`，最多 3 个）
+- 嵌入式自检清单（生产者完成后自检）
+- 抽象层级分离（需求=WHAT/WHY，设计=HOW，实现=代码）
+
+---
+
+## 六、原则应用检查点
+
+**执行任务前**:
+- [ ] 已理解 P1 验证为王（需要出示什么证据）
+- [ ] 已理解 P2 极简实用（是否是最简方案）
+- [ ] 已理解 P3 渐进自主（是否在自主边界内）
+
+**执行任务中**:
+- [ ] 每一步都出示可验证证据（P1）
+- [ ] 选择最简方案（P2）
+- [ ] 不确定时做合理默认 + 标记（P3）
+
+**执行任务后**:
+- [ ] 验证证据完整（P1）
+- [ ] 方案极简实用（P2）
+- [ ] 自主决策在边界内（P3）
+
+---
+
+## 七、关联文档
+
+| 文档 | 说明 |
+|------|------|
+| [02-strategic-principles.md](02-strategic-principles.md) | L2 战略原则（S1-S4） |
+| [03-tactical-principles.md](03-tactical-principles.md) | L3 战术原则（T1-T6） |
+| [04-operational-principles.md](04-operational-principles.md) | L4 操作原则（O1-O4） |
+| [00-principles-hierarchy.md](00-principles-hierarchy.md) | 原则体系总纲 |
+
+---
+
+**维护者**: AutoSpec 团队
+**进化分区**: 🔴 冻结区
+**版本**: v2.0
+**最后更新**: 2026-03-27