| name | keqian-method |
| version | 1.1.0 |
| description | 胥克谦式AI-Native产品开发方法论。适用于：(1) 使用AI Agent（Claude Code、Codex、Cursor等）进行产品级软件开发，(2) 设计和优化Harness/Skill体系，(3) 文档驱动开发(SDD)流程，(4) 构建自动化质量门禁和eval机制，(5) Token成本优化与缓存策略，(6) 产品人转型开发者的AI编程实践。触发场景包括"帮我设计开发流程"、"怎么降低token成本"、"怎么提高AI编码质量"、"文档驱动"、"质量门禁"、"harness设计"、"单agent vs multi-agent"、"自动化迭代"、"AI产品开发"、"SDD"、"eval机制"等。即使用户只是说"帮我用AI写代码"或"怎么让agent干活更靠谱"也应触发。注意：如果产品是行为开放、用户输入不可穷举的AI-native类型，请改用 xuefeng-method skill。不用于：单个bug修复或小改动（无需方法论）、PRD需求文档写作（用product-manager）。 |
克谦方法论：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工作流
1. 需求文档（PRD/设计文档）
↓ AI辅助撰写 + 人工审核
2. 技术文档（架构决策、接口规范）
↓ AI维护 + 人工把关
3. 代码实现
↓ Agent执行 + 质量门禁拦截
4. 文档回写（代码变更 → 文档自动更新）
↓ 闭环
文档质量门禁
文档的自动化质量控制比代码难很多。关键点：
- 技术栈选择本身是套路化的事，可以模板化
- 每个功能点不能只给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
日常开发节奏
1. 不用子代理（除非任务明确无依赖）
2. 顺序给任务，每个任务带eval
3. 放着跑，定期查看
4. 门禁拦住的问题 → 分析是harness问题还是模型问题
5. harness问题 → 改skill/rule
6. 模型问题 → 换模型或降低任务粒度
模型选择建议
基于实战经验：
- 不是纯coding：不要用xxx-codex模型，直接切通用模型
- 稳定优先：慢点就慢点，但牢靠、不啰嗦
- 国模注意事项：
- 进入上下文窗口*0.4~0.5就可能降智
- 通过harness降低抽卡比例
- 达到窗口*0.5就compact
- 长上下文不是万能的：关键是进入dumb zone的阈值要高
成本优化清单
- ✅ 建立严格质量门禁 → 自然提高缓存命中率
- ✅ 放开token使用量 → 反直觉地降低成本
- ✅ 自动化修正流程 → 缓存命中率越来越高
- ✅ 顺序执行 → 避免并行失败导致的浪费
- ✅ 及时compact → 避免降智导致的返工
- ❌ 不要手动省token → 反而导致质量差、返工多、总成本高
心法总结
"做一个马鞍，再做一个拆马鞍的工具" — 群友评价
"一抓就死，一放就乱" — 管理的永恒难题
"多烧 ≠ 多花钱" — 反直觉的真理
"端到端复杂，单维度简单" — 产品拆解的核心
"慢点就慢点，但牢靠" — 稳定性压倒一切
验收标准（按本方法论执行的任务，交付前自查）
参考资料
更多方法论细节请查阅：
references/sdd-framework.md — SDD文档驱动开发框架详细流程references/eval-patterns.md — 质量门禁和Eval模式库evals/routing-evals.json — 触发边界回归用例（含与 xuefeng-method 的互斥镜像），改动 description 后用仓库根 scripts/run_routing_evals.py 校验
