Koan：为编码智能体设计的基于规范的多轮工作流框架

Koan是专为Claude Code、Codex等编码智能体设计的开源Python框架，旨在通过基于规范的多轮工作流、决策捕获机制和项目记忆系统，解决LLM辅助工程中的知识债务问题。其核心哲学是通过结构化对话流程引导人机协作，确保工程决策清晰可追溯。本文将从背景、核心组件、架构、场景、局限等方面展开介绍。

在LLM辅助开发普及的背景下，知识债务问题逐渐凸显：开发者依赖AI助手导致对代码库理解下降，模型缺乏项目全貌认知，工具函数重复实现、编码规范分化、架构决策漂移。这源于LLM的固有特性：检索能力强但推理有限、注意力窗口受限、缺乏持久记忆。Koan框架正是针对这一痛点设计。

Koan的三大核心组件构成完整解决方案：

1. 基于规范的多轮工作流：将任务分解为固定阶段（如Intake→Plan-Spec→Plan-Review→Execute），编排器严格按顺序推进，保证过程可控可审计；
2. 决策捕获机制：智能体运行中生成landscape.md（代码全景）、plan.md（执行计划）等文档，形成耐久记录，解决决策透明性与追溯性问题；
3. 项目记忆系统：维护.koan/memory/记忆库，支持status（全景摘要）、query（语义+关键词检索）、reflect（综合回答）三种读取模式，记忆条目需用户批准确保质量。

Koan架构强调开发者自主权与数据安全：

• 本地进程模型：由Python进程驱动，子智能体通过CLI工具调用，无需API代理，零OAuth凭证处理，数据本地流动；
• 角色分离：Orchestrator（运行工作流）、Scout（只读代码调查）、Executor（实施变更），驱动程序验证阶段转换与权限边界；
• 代码内文档：鼓励将架构决策与不变量写在代码旁，工作流执行时读取更新，减少文档过时风险。

Koan特别适合三类场景：

1. 长期维护大型项目：记忆系统与工作流规范帮助团队记录架构决策，新成员可快速理解项目脉络；
2. 多开发者协作：规范工作流与决策捕获提供共同语言与标准，避免风格不一致与重复实现；
3. 高可靠性系统：决策文档与审查记录为金融、医疗等领域的合规审计提供技术基础。

当前局限：接口不稳定（Alpha阶段）、依赖Claude/Codex/Gemini CLI工具、主要优化Python项目、严格工作流需适应； 未来方向：丰富内置工作流模板（测试驱动开发、重构等）、深度集成IDE/CI/CD等工具、基于数据自动优化记忆检索、建立社区贡献模板市场。