@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/principles/design-philosophy.md

@@ -1,877 +0,0 @@
-# AI 端到端自动化研发——设计哲学与核心原则
-
-> 定位：框架建设的纲领性文件，所有设计决策必须能追溯到本文的原则
->
-> **版本**: v2.0
-> **最后更新**: 2026-03-26
-> **基于**: 业界研发框架核心架构、插件市场体系、知识管理实践
->
-> ## 核心设计模式
->
-> ### 两步生成（Two-Phase Generation）
->
-> 设计文档采用两步生成模式：
-> 1. **Phase 1: 大纲生成** - 先成功能点列表，全部标记为未完成 `- [ ]`
-> 2. **Phase 2: 逐个细化** - 逐个功能点写详细设计，每完成一个就打钩 `- [x]`
->
-> 优势：
-> - 用户先确认大纲方向，避免整体返工
-> - 逐个细化可中断，完成部分可直接使用
-> - 进度可视化，用户随时知道完成度
->
-> ### 渐进式披露（Progressive Disclosure）
->
-> 知识分层管理：
-> ```
-> Layer 1: Metadata（技能描述） → 触发条件
-> Layer 2: SKILL.md（核心逻辑） → 执行步骤
-> Layer 3: References（参考文档） → 详细规范
-> ```
->
-> 优势：
-> - 上下文精确管理，只加载必要的
-> - AI 按需加载，避免信息过载
-> - 人类易读，层次清晰
->
-> ### 模板即约束（Template-as-Constraint）
->
-> 模板设计包含：
-> - 强制字段（不填=schema 校验不通过）
-> - 不确定性标记（`[NEEDS CLARIFICATION]`，最多 3 个）
-> - 嵌入式自检清单（生产者完成后自检）
-> - 抽象层级分离（需求=WHAT/WHY，设计=HOW，实现=代码）
->
-> ### 做审分离（Evaluator-Optimizer Separation）
->
-> 做和审由不同 AI 实例执行，通过 Agent 工具实现信息隔离：
-> - 审查 Agent 只获得：产出物 + 方案文档 + 审查标准
-> - 不获得：生成过程、原始需求、对话历史
-> - 确保审查客观性
->
-> ### Harness Engineering 三部曲
->
-> 不满意产出时，**改 harness**，不改产出：
-> 1. **Context Engineering** - 知识基础：CLAUDE.md 层级、skill 体系、上下文分层
-> 2. **Architectural Constraints** - 硬性约束：Hook 护栏、宪法门禁、类型系统
-> 3. **Garbage Collection** - 持续清洁：定期一致性检查、规格陈旧检测
-
----
-
-## 一句话定位
-
-**无人值守的自动化产品研发**——AI 驱动全流程，人只在关键决策点介入。
-
-不是"让人用 AI 写代码更快"，而是"让 AI 自主完成从需求到交付的全过程"。
-
----
-
-## 第一性原则：三棱锥
-
-```
-        验证为王
-       /        \
-      /          \
-  极简实用 ———— 渐进自主
-```
-
-### P1: 验证为王（Verification-First）
-
-> "加速验证循环，而不是等待模型改进。"
-> "当 agent 犯难时，把它当作信号：识别缺什么。"
-
-**含义**：
-- 确定性验证（编译器/测试/lint）> AI 审查 > AI 自审
-- 每一步必须出示可验证的证据，不接受"我做完了"
-- 框架的核心投入应在验证基础设施，不在生成能力
-
-**验证门禁铁律（Iron Law）**：
-- **无验证证据，不宣称完成** — 可接受的证据：测试执行日志、构建输出、API 响应。不可接受："应该能跑"、"我有信心"
-- **理性化防御** — 以下说辞触发强制验证：
-  - "should work now" → 必须执行，看到真实输出
-  - "I'm confident" → 置信度不是证据，必须附带日志
-  - "I already tested earlier" → 代码已变更，必须重新验证
-- **完整性是廉价的** — AI 的边际成本极低，一次性做对最经济。完整实现是"湖"（可达成），不是"洋"（遥不可及）。不推荐捷径，当完整实现可达成时
-
-**验证原则**：
-- AST+ 编译器验证确保编译成功
-- 证据驱动交付，每步出示审计日志
-- 没有失败测试就不能写代码
-- 虚假成功声明是系统性失败模式
-
-### P2: 极简实用（Minimal Viable Process）
-
-> "使用者 5 分钟内能理解结构并开始使用。"
-> "Find the simplest solution possible."
-
-**含义**：
-- 能一个文件说清的不拆两个
-- 能用 markdown/yaml 定义的不写代码
-- 一种工作流不适合所有问题——按复杂度动态调整流程深度
-- 高频使用的提前建设，低频的用到再建
-- 审查输出必须极简结构化，不生成冗长 markdown
-- 渐进式加载，只在需要时才加载
-- 过度设计导致维护成本高
-
-### P3: 渐进自主（Progressive Autonomy）
-
-> "Human On the Loop——不检查产出物，而是工程化 harness。"
-> "信任曲线是真实的。"
-
-**含义**：
-- 从"人审每步"到"人只管 harness"的渐进路径
-- AI 先在受约束领域证明可靠，再扩展自主范围
-- 当前 sweet spot：4-8 小时粒度的明确范围任务
-- 不确定时做合理默认值并标记（知情猜测），不停下来等人
-- AI 自主能力持续增长
-- 用户对自动化的接受度逐步提高
-- 特定领域可显著提升效率
-
----
-
-## 设计原则（按优先级）
-
-### DP1: 双层验证（确定性 + AI 审查）
-
-```
-Layer 1: 确定性验证
-  编译通过 → 测试通过 → lint 通过 → 类型检查通过
-  机器判断，不可协商，Exit 2 阻止
-
-Layer 2: AI 审查
-  架构合理性 → 需求覆盖度 → 设计一致性 → 安全评估
-  AI 判断，处理机器判不了的
-```
-
-**渐进式验证**：
-- 规范检查：根据代码特征智能选择适用的规范类别
-- 语法验证：在开发环境执行验证语法
-- 数据验收：多维度检查数据质量（如适用）
-- 影响分析：分析下游影响范围（如适用）
-
-**严重问题判定标准**（触发问题归因阶段）：
-- 核心指标缺失或重复
-- 违反业务规则的强规则
-- 数据量波动超过阈值
-- 计算逻辑错误
-- 影响下游业务使用
-
-**规则**：Layer 1 不过，不进 Layer 2。Layer 2 不过，给出结构化修复建议。
-
-### DP2: 做审分离（Evaluator-Optimizer）
-
-做和审是两种不同能力，由不同 AI 实例执行。
-
-**进化方向**：
-- Phase 1: 同一模型不同 prompt（当前可行）
-- Phase 2: 不同模型互审（对抗性审查）
-- Phase 3: 编译器/测试作为"终极审查者"
-
-**反模式预判**：
-- "太简单不用审查" → 简单代码也会坏
-- "我先全做完再统一审查" → 成本指数增长
-- "审查通过了所以肯定对" → AI 审查不等于正确
-
-
-### DP3: Harness Engineering 三部曲
-
-```
-Context Engineering     → 知识基础：CLAUDE.md 层级、skill 体系、上下文分层
-Architectural Constraints → 硬性约束：Hook 护栏、宪法门禁、类型系统
-Garbage Collection      → 持续清洁：定期一致性检查、规格陈旧检测
-```
-
-不满意产出时，**改 harness**，不改产出。
-
-
-### DP4: 上下文精确管理
-
-```
-热层（始终加载）  → 项目宪法、核心规范、当前任务上下文
-温层（按需加载）  → 角色 profile、阶段 skill、领域知识
-冷层（检索加载）  → 详细文档、历史案例、完整代码
-```
-
-**规则**：
-- 阶段间传递精炼的结构化契约，不传原文
-- 每个 agent 独立上下文+worktree 隔离
-- 关键决策写入文件（不留在对话中）——压缩后自动恢复
-- 60-70% 容量主动压缩
-- 优先观察遮蔽，慎用 LLM 摘要（摘要幻觉会传播）
-- 预置知识自动加载：执行任务前检查是否有相关领域知识文件，有则读取融入上下文
-
-
-### DP5: 强制预学习 + 检查点机制
-
-任务执行前必须完成知识准备，执行过程中必须输出进度检查点。
-
-**强制预学习**：
-- 执行任何开发任务前，必须先学习相关规范和领域知识
-- 预学习阶段不可跳过
-- 预学习后需记忆关键规则
-
-**检查点机制**：
-- 每个关键步骤设置强制输出检查点
-- 检查点必须包含：步骤名称、状态（进行中/已完成）、进度（x/y）、产出物
-- 禁止跳过检查点
-- 禁止只输出结论不输出过程
-
-**执行检查点示例**：
-```
-=== 执行检查点 ===
-步骤：需求分析
-状态：已完成
-进度：2/5
-产出物：requirement.md
-```
-
-
-### DP6: 追溯深度 + 差异对比
-
-任务执行需要明确的追溯深度和代码差异对比能力。
-
-**追溯深度要求**：
-- 上下游追溯必须按指定深度进行
-- 遇到停止条件才结束追溯
-- 上游追溯停止条件：到达数据源层、自依赖、循环依赖
-- 必须逐层递归追溯，输出每层结果
-
-**差异对比机制**：
-- 更新现有代码时，必须对比新旧版本差异
-- 对比维度：新增、修改、删除
-- 输出结构化差异报告
-
-
-### DP7: 知情猜测 > 无限提问
-
-无人值守系统不能频繁停下来等人。
-
-**自主决策边界**：
-| 决策类型 | 谁决定 | 例子 |
-|---------|--------|------|
-| 需求方向 | 人 | 做不做这个功能 |
-| 架构重大变更 | 人 | 换数据库、换框架 |
-| 安全敏感 | 人 | 鉴权方案、数据加密 |
-| 技术选型（栈内） | AI 自主 | 用哪个库、API 设计 |
-| 实现细节 | AI 自主 | 算法选择、代码结构 |
-| 不确定项 | AI 做合理默认 + 标记 | 最多 3 个 NEEDS CLARIFICATION |
-
-
-### DP8: 精准回退，不全量重做
-
-**三级嵌套自愈**：
-```
-Level 1: 内联重试 — 生成失败立即单次重试
-Level 2: 修正循环 — 结构化诊断反馈 → 定向修复 → 重验证（最多 3 次）
-Level 3: 人工升级 — 提交 3 次产出+3 次诊断+AI 的"为什么反复不过"分析
-```
-
-**规则**：只重处理失败项，不全量重做。
-
-
-### DP9: 反模式预判（Anti-Pattern Inoculation）
-
-在每个 skill 中预判 AI 会"偷懒"或"走捷径"的所有路径并堵死。
-
-**通用反模式清单**：
-1. 蛮力修复（@JsonIgnore、跳过测试、增加内存）
-2. 虚假成功声明（红色测试时称完成）
-3. 假设填充不一致（优先级字段在不同运行间变化）
-4. 范围蔓延（从术语自动推导未要求的业务逻辑）
-5. 假设漂移（业务逻辑假设无声改变）
-6. 重复造轮子（不搜索现有实现就新建）
-
-
-### DP10: CSO 原则（Claude Search Optimization）
-
-skill 的 description 只写触发条件，不写工作流摘要。
-
-**规则**：
-- 如果 description 含工作流内容，AI 会直接按 description 执行而跳过完整 skill
-- 包含 WHAT 和 WHEN
-- 第三人称
-- 创造信息差——迫使 AI 加载完整正文才能执行
-
-
-### DP11: 多 Agent 编排——Orchestrator-Workers 架构
-
-> "编排器本身也是 agent——智能调度而非死板队列。"
-
-无人值守系统不是单 agent 串行跑完全流程，而是**编排器协调多个专业 worker 并行工作**。
-
-**三层编排架构**：
-```
-┌─────────────────────────────────────────────────┐
-│  Orchestrator（编排器）                           │
-│  · 任务分解与分配                                 │
-│  · 状态监控（状态机驱动，不是轮询）                 │
-│  · 自动反应（声明式：出了什么→做什么）              │
-│  · 异常升级（超时→重试→人工）                      │
-│  · 自适应重规划（遇到问题不只重试，换策略）          │
-├─────────────────────────────────────────────────┤
-│  Workers（工人）                                  │
-│  · 每个 worker 独立上下文 + git worktree 隔离         │
-│  · 做类 worker 和审类 worker 分离                     │
-│  · worker 间通过文件系统 + 结构化引用通信              │
-│  · 支持并行 fan-out（独立任务同时执行）              │
-├─────────────────────────────────────────────────┤
-│  反应引擎（Reaction Engine）                      │
-│  · 声明式 YAML 定义事件→动作映射                    │
-│  · ci-failed → 自动修复（最多 N 次）→ 升级人工       │
-│  · review-requested → 路由到审类 worker            │
-│  · stuck → 看门狗检测 → 升级                      │
-└─────────────────────────────────────────────────┘
-```
-
-**Worker 间通信规则**：
-- 传**文件路径引用**，不传内容本身（业界实践）
-- 共享文件提前识别并分配给单一 worker（避免 merge 冲突）
-- 顺序合并：先 merge 一个 worker 的 work，rebase 其余
-
-**状态机生命周期**：
-```
-spawning → working → pr_open → ci_running
-    → ci_passed → review_pending → approved → merged
-    → ci_failed → auto_fix → ci_running（重试）
-    → stuck → escalate_human
-```
-
-**进化路线**：
-- Phase 1: 单 agent 顺序执行（当前 pipeline-runner）
-- Phase 2: Orchestrator + Workers，支持做审并行
-- Phase 3: 反应引擎 + 状态机 + 多层看门狗
-
-
-### DP12: 安全与紧急制动（Safety by Design）
-
-> "任何 agent 可以因质量/安全问题停止所有工作。"
-> "80% 的工具调用至少有一个安全护栏；仅 0.8% 的动作不可逆。"
-
-无人值守不等于无人监管。系统必须有多层安全网。
-
-**四层安全模型**：
-```
-Layer 1: 宪法门禁（Constitution Gate）
-  · 项目级不可违反的红线（安全、合规、数据保护）
-  · 所有阶段产出必须通过宪法合规检查
-  · 宪法用语义版本控制：MAJOR=原则删除/重定义
-  · 自动检查，不依赖 AI 判断
-
-Layer 2: 权限控制（Permission Boundaries）
-  · 每个 agent 只能使用它该用的工具（SAFe 实践）
-  · 做类 agent 不能删除文件/修改配置
-  · 审类 agent 只读不写
-  · 外部 API 调用需要显式授权
-
-Layer 3: 停线权（Stop-the-Line）
-  · 任何 agent 检测到以下情况必须停止全流程：
-    - 安全漏洞（SQL 注入、XSS、凭证泄露）
-    - 数据丢失风险
-    - 测试覆盖率低于阈值
-    - 编译错误无法在 3 次内修复
-  · 停线后通知人工，附带完整诊断
-
-Layer 4: 看门狗（Watchdog）
-  · 机械层：超时检测、资源监控、心跳检查
-  · AI 层：定期审查 agent 行为是否偏离目标
-  · 升级链：自动修复 → AI 分诊 → 人工介入
-```
-
-**不可逆动作白名单**：
-- 代码生成/修改 → 可逆（git revert）
-- 文件创建 → 可逆
-- 数据库迁移 → **不可逆，必须人工确认**
-- 外部 API 调用 → **视情况，发送类不可逆**
-- 部署上线 → **不可逆，必须人工确认**
-
-
-### DP13: 任务分解质量（Decomposition is Destiny）
-
-> "任务分解质量决定自主成功率。"
-> "假设执行者是一个没有代码库上下文、品味可疑、不喜欢测试的热情初级工程师。"
-
-任务分解是无人值守成功的**最关键因素**——分解不好，后面全白费。
-
-**三视角拆分触发条件**：
-```
-视角 1: 系统边界 → 涉及多子系统？→ 按系统拆 Phase，明确系统间依赖
-视角 2: 任务规模 → 预估 > 16 小时？→ 在 Phase 内按功能拆 Task（每任务 2-4h）
-视角 3: 阶段依赖 → 有明确阶段约束？→ 按 AI 验证→后端→前端 顺序排列
-
-任一满足 → 必须拆解
-```
-
-**分解质量标准**：
-```
-每个任务必须满足（ATOMIC 原则）：
-  A — Autonomous：可独立执行，不依赖其他任务的中间状态
-  T — Testable：有明确的验证标准（不是"看起来对"）
-  O — Observable：执行结果可观测（有输出、有日志）
-  M — Modest：2-4 小时工作量（当前 AI sweet spot）
-  I — Informed：包含完整上下文（不假设执行者知道任何背景）
-  C — Constrained：明确边界（做什么、不做什么、不能碰什么）
-```
-
-**分解层级**：
-```
-Phase（阶段/子系统，预估 4-16 小时）
-  └── Task（具体任务，2-4 小时）
-       └── Sub-task（如需要，最大深度 2 层）
-```
-
-**lineage 上下文**：
-每个子任务携带：
-- 祖先任务链（我从哪来）
-- 兄弟任务列表（旁边有谁在干什么）
-- 约束条件（不能碰的文件/模块）
-
-**依赖识别与并行判断**：
-```
-依赖类型：
-  →data     数据依赖：上游产出作为下游输入（如：API 定义 → 前端对接）
-  →logic    逻辑依赖：业务流程顺序约束（如：创建用户 → 分配权限）
-  →res      资源依赖：共享资源需串行访问（如：数据库迁移）
-  →contract 契约解耦：通过定义标准产出物解耦（如：API 契约 → 双方并行）
-  →mock     Mock 并行：下游基于 Mock 开发，上游完成后联调
-
-并行判断四问：
-  1. 是否无共享写入资源？ → 是则可并行
-  2. 是否无执行顺序约束？ → 是则可并行
-  3. 失败是否互不影响？  → 是则可并行
-  4. 合并成本是否低？    → 是则可并行
-
-解耦并行判断：
-  1. 是否可定义标准产出物？（API 契约、数据 Schema、接口定义）
-  2. 下游是否可基于标准独立验证？（Mock 测试、Schema 校验）
-  3. 联调成本是否可控？
-  → 三者都满足 → 可解耦并行
-```
-
-**面向标准解耦并行**：
-```
-传统串行：
-  [后端 API 实现] →data→ [前端开发]
-  后端完成后前端才能开始
-
-解耦并行：
-  [API 契约定义] ─┬─→ [后端实现]
-                └─→ [前端 Mock 开发] → [联调验证]
-  契约定义后双方并行，最后联调
-
-可解耦场景：
-  后端↔前端：API 契约（OpenAPI）→ 后端实现 ∥ 前端 Mock
-  后端↔移动端：API 契约 → 后端实现 ∥ 移动端 Mock
-  数据↔后端：数据 Schema → 数据管道 ∥ 后端接口
-  AI↔后端：模型接口定义 → 模型训练 ∥ 后端服务
-
-不可解耦场景：
-  - 数据库迁移（资源依赖）
-  - 核心业务流程顺序（逻辑依赖：订单→支付→发货）
-  - AI 效果验证（逻辑依赖：效果不达标则后续无意义）
-```
-
-**任务编排模式**：
-```
-串行模式（不可解耦依赖）：
-  P1 →data→ P2 →logic→ P3
-
-解耦并行模式（契约解耦）：
-  [契约定义] →contract→ P2 实现 ∥ P3 实现 → 联调
-
-原生并行模式（无依赖）：
-  P2 →data→ P3 [P] ┐
-                  ├→ 集成
-       →data→ P4 [P] ┘
-```
-
-
-### DP14: 驯服非确定性（Taming Non-Determinism）
-
-> "LLM 是精灵——通过利用规格漏洞来实现愿望。"
-> "始终存在不可忽略的概率，它做了我们不想要的事。"
-
-非确定性不是 bug，是 LLM 的本质特征。不能消除，只能管理。
-
-**管理策略（四道防线）**：
-```
-防线 1: 约束输出空间
-  · 结构化输出格式（JSON Schema / 模板填充）
-  · 明确的"做什么 + 不做什么"边界
-  · 反模式清单堵死捷径路径
-  · 枚举所有合法选项（而不是开放式生成）
-
-防线 2: 锚定一致性
-  · 关键假设必须显式记录在文件中（不留在对话中）
-  · 阶段间传递结构化契约（防止假设漂移）
-  · 宪法门禁确保核心不变量
-  · 同一需求多次执行的结果差异必须在可接受范围内
-
-防线 3: 确定性验证兜底
-  · 编译器/类型系统/测试/lint——这些是确定性的
-  · 即使 AI 产出不同的代码，只要通过确定性验证就可接受
-  · "不同的路径到达同一个正确结果"是可以的
-
-防线 4: 人工审查关键决策
-  · 架构决策、安全方案、需求理解——这些不能容忍非确定性
-  · 用结构化 checklist（不是开放式审查）减少人工负担
-  · 人审的不是代码，而是**决策和假设**
-```
-
-**假设管理协议**：
-- 每个阶段的输出必须包含`## 关键假设`章节
-- 假设分为"已确认"和"待确认"
-- 待确认假设超过 3 个 → 升级为人工确认
-- 假设变更必须显式记录原因和影响范围
-
-
-### DP15: 系统进化——Agentic 飞轮
-
-> "通过工程化 harness，我们得到反脆弱的持续自我改进系统。"
-
-框架不是一次性搭建完，而是一个持续变好的飞轮。
-
-**三层进化机制**：
-```
-Layer 1: 实践回流（Practice Loop）— 每次执行后
-  · 做完就检查，有料就沉淀
-  · distiller: 可执行的模式 → skills/
-  · extractor: 认知性的经验 → methodology/
-  · 好/坏案例 → evaluation/benchmarks/
-  · 同类问题 3 次 → 必须产出 skill
-
-Layer 2: Harness 进化（Harness Loop）— 每周
-  · 不满意产出 → 分析"harness 缺什么" → 改 harness
-  · Agent 建议 harness 改进 → 人审核 → 纳入或拒绝
-  · 规格与代码一致性检查（Garbage Collection）
-  · 每周 1-2 小时维护（Codified Context 论文验证的必要投入）
-
-Layer 3: 框架升级（Architecture Loop）— 每季度
-  · 框架级 review：原则是否仍然正确？
-  · 新的行业最佳实践是否应纳入？
-  · 自主边界是否可以扩展？（渐进自主的实际推进）
-  · 模型能力提升后，哪些"必须人工"可以降级为"AI 自主"？
-```
-
-**进化加速器**：
-```
-候选方案生成（LLM）→ 自动评估（编译器/测试/指标）→ 选择最优 → 下一代
-```
-在 skill 迭代中应用：多个 skill 变体并行测试 → 选效果最好的 → 淘汰其他。
-
-
-### DP16: 成本经济学（Token Economics）
-
-> "多 agent≈15 倍于 chat 的 token 消耗。必须瞄准高价值任务。"
-
-无人值守 ≠ 不计成本。必须有成本意识的架构设计。
-
-**模型分层策略**：
-| 任务类型 | 模型选择 | 原因 |
-|---------|---------|------|
-| 代码搜索/分析 | 轻量模型 | 机械任务，不需要深度推理 |
-| 代码生成/实现 | 平衡模型 | 需要质量但量大 |
-| 架构设计/复杂审查 | 顶级模型 | 关键决策不能省 |
-| 简单格式校验 | 确定性工具（零 LLM 成本） | lint/编译器/类型检查 |
-
-**成本优化策略**：
-1. **Prompt 缓存**：相同上下文的任务排队执行，复用缓存
-2. **确定性优先**：能用编译器/测试验证的不用 LLM 审查（省 15 倍 +）
-3. **精准回退**：只重处理失败项，不全量重做
-4. **上下文精炼**：传摘要不传原文，减少 token 消耗
-5. **任务粒度优化**：太大=上下文溢出浪费，太小=编排开销浪费。sweet spot: 2-4 小时
-
-**成本可见性**：每个任务完成后记录 token 消耗，按阶段/角色/skill 维度统计，识别成本热点。
-
-
-### DP17: Brownfield 适配——现有代码优先
-
-> 现实中 95%+ 的工作是在现有代码库上，不是从零开始。
-
-**Brownfield 三步法**：
-```
-Step 1: Onboard（理解现有系统）
-  · 自动扫描代码库结构（tree-sitter 解析）
-  · 生成项目知识图谱（模块关系、依赖、热点）
-  · 识别技术栈、框架版本、代码风格
-  · 输出：project-context.md（热层上下文）
-
-Step 2: Delta 分析（精确影响范围）
-  · 新需求 → 识别受影响的模块/文件/接口
-  · 只修改受影响部分，不重写无关代码
-  · 保留已有代码的风格和模式（不"改善"不需要改的）
-
-Step 3: 一致性验证
-  · 变更后运行全量测试（确保不破坏已有功能）
-  · 检查与已有代码风格的一致性
-  · 验证 API 契约不被意外破坏
-```
-
-**"先搜索后实现"铁律**：
-- 实现任何功能前，先搜索代码库是否已有类似实现
-- 有 → 复用或扩展
-- 无 → 按已有代码的模式和风格实现
-- 绝不重复造轮子
-
-
----
-
-## 设计原则总览
-
-```
-第一性原则（三棱锥）
-  P1: 验证为王
-  P2: 极简实用
-  P3: 渐进自主
-
-执行层原则（怎么做好每一步）
-  DP1: 双层验证（确定性+AI）
-  DP2: 做审分离
-  DP3: Harness Engineering 三部曲
-  DP4: 上下文精确管理
-  DP5: 知情猜测 > 无限提问
-  DP6: 精准回退不全量重做
-  DP7: 反模式预判
-  DP8: CSO 原则
-
-系统层原则（整个系统怎么运转）
-  DP9:  多 Agent 编排（Orchestrator-Workers）
-  DP10: 安全与紧急制动
-  DP11: 任务分解质量（ATOMIC 原则）
-  DP12: 驯服非确定性
-
-进化层原则（系统怎么变得越来越好）
-  DP13: Agentic 飞轮（三层进化）
-  DP14: 成本经济学
-  DP15: Brownfield 适配
-
-预防层原则（从源头减少缺陷）
-  DP16: 模板即约束（Template-as-Constraint）
-  DP17: 结构化澄清协议
-  DP18: 跨产物一致性分析
-```
-
-### DP18: 模板即约束（Template-as-Constraint）
-
-> "在验证之前就约束输出质量——预防优于检测。"
-
-传统做法是先让 AI 自由生成，再用验证层捕获问题。**更好的做法是从源头约束输出空间**，让 AI"很难生成坏的产出"。
-
-**约束模板设计原则**：
-```
-每个阶段的产出模板必须包含：
-  1. 强制字段（不填=schema 校验不通过）
-  2. 不确定性标记（[NEEDS CLARIFICATION]，最多 3 个）
-  3. 嵌入式自检清单（生产者完成后自检，审查者独立检）
-  4. 抽象层级分离（需求=WHAT/WHY，设计=HOW，实现=代码）
-  5. 层级化详情管理（主文档保持可导航，细节放子目录）
-```
-
-**与 DP1 的关系**：DP1 是"出了问题能抓住"（验证），DP16 是"让问题很难出"（预防）。两者互补，不替代。
-
-
-### DP19: 结构化澄清协议（Structured Clarification）
-
-> "不是问越多越好，而是问对的问题，问有限个。"
-
-需求阶段的歧义不应该靠"多沟通"解决，而应该有**结构化的澄清机制**。
-
-**澄清协议**：
-```
-Step 1: 分类扫描（11 个维度）
-  功能范围、数据模型、UX 流程、非功能需求、集成接口、
-  边界案例、约束条件、术语定义、优先级、风险项、验收标准
-
-Step 2: 优先级排序
-  Impact × Uncertainty → 选择影响最大且最不确定的问题
-
-Step 3: 有界提问
-  最多 5 个问题，逐个提问
-  每个问题附带 AI 推荐答案（含推理过程）
-  用户可接受推荐或给出不同答案
-
-Step 4: 原子更新
-  每个回答立即更新到需求文档（不是批量更新）
-  支持提前终止（用户觉得够了就停）
-```
-
-**与 DP5 的关系**：DP5 说"知情猜测 > 无限提问"，DP17 说"提问要结构化且有界"。两者互补——合理默认值（DP5）+ 关键歧义主动澄清（DP17）。
-
-
-### DP20: 跨产物一致性分析（Cross-Artifact Consistency）
-
-> "需求说 A，设计做 B，代码写 C——这是 AI 驱动开发最常见的失败模式。"
-
-流水线各阶段产出的不是孤立文档，而是**一组必须一致的产物**。一致性不能靠人肉对比，必须有系统化检测。
-
-**六维一致性检测**：
-```
-1. 重复检测 — 同一逻辑在不同产物中重复定义（冲突风险）
-2. 歧义检测 — 模糊形容词无量化标准（"快速"→ 多快？）
-3. 规格不全 — 动词无宾语/无预期结果（"处理数据"→ 什么数据？怎么处理？）
-4. 宪法对齐 — 产物是否违反宪法原则（自动标记 CRITICAL）
-5. 覆盖缺口 — 需求有对应设计？设计有对应代码？代码有对应测试？
-6. 术语漂移 — 同一概念在不同产物中用不同名称
-```
-
-**与 DP12 的关系**：DP12 管理单个阶段内的非确定性（假设管理），DP18 管理阶段间的一致性（跨产物检测）。
-
-**执行时机**：
-- 每个阶段完成后，自动与上游产物做一致性检查
-- 全流程完成前，跑一次全量一致性分析
-- 纳入 Layer 2 审查的标准检查项
-
-
-### DP21: 领域驱动设计原则（Domain-Driven Design）
-
-> "复杂系统的核心是领域模型，不是技术架构。"
-> "统一语言是团队协作的基础。"
-
-领域驱动设计（DDD）是一种应对复杂业务系统的方法论，核心思想是将领域模型作为系统的核心。
-
-**适用场景判断**：
-```
-领域复杂度评估：
-  高（核心业务、多概念、复杂规则）→ 推荐DDD
-  中（有业务逻辑但可控）→ 可选DDD
-  低（CRUD为主）→ 不推荐DDD
-
-判断标准：
-  1. 业务概念数量 > 20个？
-  2. 业务规则复杂度 > 简单CRUD？
-  3. 需要跨团队协作？
-  4. 预期生命周期 > 2年？
-  → 满足2个以上 → 考虑DDD
-```
-
-**DDD核心概念**：
-
-| 层次 | 概念 | 作用 |
-|------|------|------|
-| 战略设计 | 限界上下文 | 划分系统边界，定义语言一致性范围 |
-| 战略设计 | 上下文映射 | 描述上下文间关系，选择集成模式 |
-| 战术设计 | 聚合 | 定义一致性边界，事务原子性保证 |
-| 战术设计 | 领域事件 | 聚合间通信，最终一致性实现 |
-| 战术设计 | 统一语言 | 消除沟通歧义，代码与业务术语一致 |
-
-**DDD与现有原则的融合**：
-
-| DDD概念 | 对应原则 | 融合方式 |
-|---------|---------|---------|
-| 限界上下文 | DP13 任务分解 | 按上下文拆分系统边界 |
-| 聚合 | DP12 非确定性管理 | 聚合边界 = 一致性边界 |
-| 统一语言 | DP18 跨产物一致性 | 术语表消除漂移 |
-| 领域事件 | DP11 多Agent编排 | 事件驱动解耦 |
-| 防腐层 | DP3 Harness工程 | 隔离外部依赖 |
-
-**DDD实施要点**：
-
-1. **战略设计先行**：先划分限界上下文，再设计聚合
-2. **统一语言优先**：术语不一致时先解决术语问题
-3. **小聚合原则**：聚合应保持小规模，减少并发冲突
-4. **事件驱动解耦**：聚合间通过领域事件通信
-5. **适度设计**：简单场景不过度设计
-
-**反模式警示**：
-
-| 反模式 | 症状 | 风险 |
-|--------|------|------|
-| 贫血模型 | 只有getter/setter | 业务逻辑散落 |
-| 大聚合 | 聚合包含过多实体 | 并发冲突、性能问题 |
-| 领域服务滥用 | 服务承载所有逻辑 | 过程式代码 |
-| 忽略统一语言 | 代码与业务术语不一致 | 沟通成本高 |
-
-**与DP16模板即约束的关系**：DP16强调模板约束产出质量，DDD模板（`templates/domain-driven-design.md`）提供了战略设计到战术设计的完整约束结构，帮助AI生成符合DDD规范的产出物。
-
-
----
-
-## 架构选型原则
-
-### 技术选型标准
-
-| 维度 | 标准 | 理由 |
-|------|------|------|
-| 定义方式 | Markdown/YAML 优先，代码最小化 | 维护成本远低于代码 |
-| 执行环境 | Claude Code 原生 | 不造轮子，利用平台最强能力 |
-| 状态管理 | 文件系统即状态 | 经验证的最简方案 |
-| Agent 通信 | 文件系统 + 结构化引用 | 业界实践：传引用不传内容 |
-| 隔离机制 | Git Worktree | 经验证的信息隔离方案 |
-| 扩展机制 | MCP 协议 | 标准化，不改核心框架就能扩展 |
-
-### 不做什么（显式排除）
-
-| 不做 | 原因 |
-|------|------|
-| 多 AI 工具适配 | 锁定单一生态，避免适配成本 |
-| 自建 DAG 引擎 | 只有 2-6 个阶段的流水线，线性 + 分支足够 |
-| 自建向量数据库 | 用 MCP 接入现有方案 |
-| BDD/Scenario 格式 | 验证了增加认知负担且没有下游消费者 |
-| Spec-as-source | 当前不成熟（Tessl 非确定性问题），保持 Spec-anchored |
-
----
-
-## 度量与反馈
-
-### 北极星指标
-
-**自主完成率**：在不需要人工介入的情况下，成功通过所有验证门禁的任务占比。
-
-### 过程指标
-
-| 指标 | 含义 | 目标 |
-|------|------|------|
-| 首次验证通过率 | 做类 skill 产出一次过审的比例 | >60% |
-| 平均回退次数 | 每个阶段的平均回退次数 | <1.5 |
-| 人工介入率 | 升级到人工的任务占比 | <20% |
-| 验证循环时间 | 做→审→结果的平均时间 | 持续缩短 |
-| 上下文利用率 | 上下文窗口使用百分比峰值 | <70% |
-| Token 成本/任务 | 完成一个任务的平均 token 消耗 | 持续降低 |
-
-### 回流机制
-
-```
-Practice Log 积累 → 5 条触发 methodology 审查
-                 → 同类问题 3 次 → 必须产出 skill 或更新 methodology
-                 → 失败模式 → 更新反模式清单
-                 → 成功模式 → 更新最佳实践
-
-Harness 改进飞轮：
-  不满意产出 → 分析原因 → 改 harness → 验证改进 → 记录到 practice-log
-```
-
----
-
-## 与现有框架（PROPOSAL.md）的对应关系
-
-### 执行层原则
-| 本文原则 | PROPOSAL.md 中的对应 | 状态 |
-|---------|-------------------|------|
-| DP1 双层验证 | 质量关卡 | ⚠️ 需增加确定性验证层（编译/测试/lint） |
-| DP2 做审分离 | 做审分离 | ✅ 一致 |
-| DP3 Harness 三部曲 | — | ❌ 新增 |
-| DP4 上下文精确管理 | — | ❌ 新增 |
-| DP5 知情猜测 | 人工介入点 | ⚠️ 需细化自主决策边界表 |
-| DP6 精准回退 | 回退机制 | ⚠️ 需优化为"只重处理失败项" |
-| DP7 反模式预判 | — | ❌ 新增：每个 skill 必须包含反模式清单 |
-| DP8 CSO 原则 | — | ❌ 新增：skill description 格式规范 |
-
-### 系统层原则
-| 本文原则 | PROPOSAL.md 中的对应 | 状态 |
-|---------|-------------------|------|
-| DP9 多 Agent 编排 | pipeline-runner（简版） | ⚠️ 需进化为 Orchestrator-Workers+ 状态机 + 反应引擎 |
-| DP10 安全与紧急制动 | — | ❌ 新增：四层安全模型 + 停线权 + 不可逆白名单 |
-| DP11 任务分解质量 | — | ❌ 新增：ATOMIC 原则+lineage+ 独立可测切片 |
-| DP12 驯服非确定性 | — | ❌ 新增：四道防线 + 假设管理协议 |
-
-### 进化层原则
-| 本文原则 | PROPOSAL.md 中的对应 | 状态 |
-|---------|-------------------|------|
-| DP13 Agentic 飞轮 | 回流规则 + 进化节奏 | ⚠️ 需深化为三层进化（实践/Harness/架构） |
-| DP14 成本经济学 | — | ❌ 新增：模型分层 + 成本优化策略 |
-| DP15 Brownfield 适配 | — | ❌ 新增：Onboard+Delta 分析 + 一致性验证 |
-
-### 度量体系
-| 本文原则 | PROPOSAL.md 中的对应 | 状态 |
-|---------|-------------------|------|
-| 北极星 + 过程指标 | — | ❌ 新增 |
-
----