@chongyan/autospec 1.0.2 → 1.0.4

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

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

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