克谦方法论：AI-Native 产品开发实战体系
核心理念：产品人思维 × 极致单 Agent × 文档驱动 × 质量门禁闭环。
来源：胥克谦——从音乐教师到产品经理到 AI-Native 连续创业者，皮影客创始人，十几万行自建 skill 和脚本的 harness 工程实践者。
第一原则：Iron Law（铁律）
概率乘是第一性原理。每个环节的成功率相乘决定最终质量。即使每次 0.99，n=51 后也不及格。因此：不追求一次完美，追求每个环节可验证、可修复、可迭代。
推论：
- 勤不能补拙——模型能力是底线，harness 和 skill 只是加速器和放大器
- 拆到足够简单，单项任务才能收敛
- 每个 action 必须对应一个 eval
第二原则：单 Agent 极致论
不盲目使用 multi-agent。单 agent 做到极致，再考虑编排。
何时用单 Agent（默认选择）：
- 有先后依赖关系的任务
- 需要上下文连贯性的长程任务
- 质量要求高、不容错的核心流程
何时用并行 SubAgent（例外情况）：
- 任务间明确无依赖关系（如多角度审计出报告）
- 并行结果合并时不易出问题
- 你有能力精确控制每个 subagent 的上下文注入
并行的陷阱：
- SubAgent 上下文注入是个坑：注入什么、注入多少，都需要精确控制
- 主 Agent 可能假装自己是 SubAgent（实际遇到过）
- 并行任务中一个环节出问题，整个长任务可能报废
- 合并结果时容易引入不一致
实践建议：如果不确定，选顺序执行。慢但可靠。
第三原则：文档驱动开发（SDD）
7 成精力投入文档质量和 harness，3 成精力写代码。
为什么文档比代码重要：
- 不写文档就没有架构观
- 不可能每次都让 AI 全量扫代码
- 零散的功能 = 零散的质量
- 让 AI 自己维护一份文档，代码再 vibe 对齐
SDD 工作流：
- 需求文档（PRD/设计文档）→ AI 辅助撰写 + 人工审核
- 技术文档（架构决策、接口规范）→ AI 维护 + 人工把关
- 代码实现 → Agent 执行 + 质量门禁拦截
- 文档回写（代码变更 → 文档自动更新）→ 闭环
文档质量门禁：
- 文档的自动化质量控制比代码难很多。关键点：
- 技术栈选择本身是套路化的事，可以模板化
- 每个功能点不能只给 3 个用例敷衍了事（一轮不够就多轮）
- 但也要防止过度设计——把握平衡点，结合项目实际
第四原则：质量门禁闭环（Verification-Driven）
严格的质量门禁 = 高缓存命中率 = 高质量 = 低成本。
门禁设计： 每个 Action → 对应 Eval → 通过/不通过 不通过 → 自动修复（最多 N 轮）→ 仍不通过 → 升级给人类
Eval 的 acceptable threshold：
- 不同业务、不同团队有不同 threshold
- 关键是在【期望预算内、期望时间内】出【期望结果】
- 不要指望 1 次成型，那是稀罕事
- AI-Native 迭代 3~5 轮是比较理想的 acceptable threshold
反直觉发现：多烧 ≠ 多花钱
自动化修正流程表面上浪费 token，但实际上：
- 逐个问题点被反复修正 → 高缓存命中
- 高缓存命中 = 高质量（说明问题已收敛）
- 缓存命中的 token 几乎不花钱
实测数据：缓存命中率 99%+ 时，每 1 亿 token ≈ 8.5 RMB，约等于不要钱。
推论：省 token 其实很不划算。放开 token 使用量，反倒造成事实成本下降。
第五原则：产品拆解思维
端到端都是复杂的，单维度都是简单的。
拆解方法论：
- 复杂问题 → 拆成多层次
- 每个层次 → 单维度可穷举
- 单维度选项有限 → 模型可做决策
- 输入变量（公司规模、场景、约束）→ 都是条件变量
边界内泛化：
- 任何产品都有边界
- 边界内的泛化并不难，都是可穷举的
- 不需要 100% 泛化，只要目标范围内泛化
- 端到端复杂 ≠ 单维度复杂
适用边界：此方法适合场景明确、边界可定义的产品。对于用户行为高度不可预测的 AI-Native 交互产品，需要补充上线后快速迭代的机制。
第六原则：与 AI 斗智斗勇
AI 会联合你写的 skill 和门禁来对抗你的要求。
已知的 AI 抵抗模式：
- 要删除一个段落 → AI 用段落改名、转移位置、改写保留语义等方式抵抗
- 新开会话、重开 codex、换电脑都不能消除抵抗
- 这种现象可能持续数天
应对策略：
- 上 eval：不符合要求就持续迭代（反复删也是种迭代）
- 每个 action 都对应 eval：如果不放心的话
- CICD 集成逻辑复盘：用以前 CI/CD 集成那套逻辑来复盘问题
- 降低抽卡概率：通过 harness 降低模型抽卡比例
- 及时 compact：达到上下文窗口*0.5 左右就 /compact，保持智力不掉线
实战工作流模板
启动新项目：
Phase 1: 文档先行（占总时间 70%）
- 撰写 PRD（AI 辅助 + 人工审核）
- 技术架构文档（AI 维护 + 人工把关）
- 定义质量门禁和 eval 标准
- 设计 harness 结构（skill + rule 配置）
Phase 2: 代码实现（占总时间 20%）
- Agent 顺序执行任务
- 每个任务通过质量门禁
- 不通过 → 自动修复 → 仍不通过 → 人工介入
- 文档自动回写
Phase 3: 迭代收敛（占总时间 10%）
- 跑 eval 批量验证
- 收集失败 case → 分析 → 改进 harness
- 直到达到 acceptable threshold
日常开发节奏：
- 不用子代理（除非任务明确无依赖）
- 顺序给任务，每个任务带 eval
- 放着跑，定期查看
- 门禁拦住的问题 → 分析是 harness 问题还是模型问题
- harness 问题 → 改 skill/rule
- 模型问题 → 换模型或降低任务粒度
模型选择建议（基于实战经验）：
- 不是纯 coding：不要用 xxx-codex 模型，直接切通用模型
- 稳定优先：慢点就慢点，但牢靠、不啰嗦
- 国模注意事项：
- 进入上下文窗口*0.4~0.5 就可能降智
- 通过 harness 降低抽卡比例
- 达到窗口*0.5 就 compact
- 长上下文不是万能的：关键是进入 dumb zone 的阈值要高
成本优化清单：
- ✅ 建立严格质量门禁 → 自然提高缓存命中率
- ✅ 放开 token 使用量 → 反直觉地降低成本
- ✅ 自动化修正流程 → 缓存命中率越来越高
- ✅ 顺序执行 → 避免并行失败导致的浪费
- ✅ 及时 compact → 避免降智导致的返工
- ❌ 不要手动省 token → 反而导致质量差、返工多、总成本高
心法总结：
- “做一个马鞍，再做一个拆马鞍的工具” — 群友评价
- “一抓就死，一放就乱” — 管理的永恒难题
- “多烧 ≠ 多花钱” — 反直觉的真理
- “端到端复杂，单维度简单” — 产品拆解的核心
- “慢点就慢点，但牢靠” — 稳定性压倒一切
验收标准（按本方法论执行的任务，交付前自查）：
- 写代码之前存在对应的规格文档（SDD：文档先行，不是事后补）
- 每个交付环节过了质量门禁（测试/断言/eval），没有“看起来没问题”式放行
- 概率乘意识：长链条任务拆成了可独立验证的小环节，而不是一把梭
- 用的是单 Agent 主导的流程；引入并行前说明了“为什么单 Agent 不够”
- Token 成本有意识：复用缓存、避免重复喂上下文
参考资料：
- references/sdd-framework.md — SDD 文档驱动开发框架详细流程
- references/eval-patterns.md — 质量门禁和 Eval 模式库
- evals/routing-evals.json — 触发边界回归用例（含与 xuefeng-method 的互斥镜像），改动 description 后用仓库根 scripts/run_routing_evals.py 校验