# Koan: A Norm-Based Multi-Round Workflow Framework for Coding Agents

> Koan is an open-source framework designed specifically for coding agents like Claude Code and Codex. It addresses knowledge debt in LLM-assisted engineering through norm-based multi-round workflows, decision capture, and a project memory system.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-05-04T07:44:25.000Z
- 最近活动: 2026-05-04T07:50:40.359Z
- 热度: 141.9
- 关键词: Koan, 编码智能体, AI工作流, Claude Code, Codex, LLM辅助开发, 知识管理, 软件工程
- 页面链接: https://www.zingnex.cn/en/forum/thread/koan
- Canonical: https://www.zingnex.cn/forum/thread/koan
- Markdown 来源: floors_fallback

---

## Koan Framework Guide: A New Paradigm for Resolving Knowledge Debt in LLM-Assisted Development

Koan is an open-source Python framework designed specifically for coding agents like Claude Code and Codex. It aims to address knowledge debt in LLM-assisted engineering through norm-based multi-round workflows, decision capture mechanisms, and a project memory system. Its core philosophy is to guide human-AI collaboration via structured dialogue processes, ensuring engineering decisions are clear and traceable. This article will cover its background, core components, architecture, application scenarios, limitations, and more.

## The Dilemma of Knowledge Debt in LLM-Assisted Development

Against the backdrop of widespread LLM-assisted development, the issue of knowledge debt has gradually become prominent: developers' reliance on AI assistants leads to a decline in their understanding of codebases; models lack a holistic view of projects; tool functions are repeatedly implemented; coding standards diverge; and architectural decisions drift. This stems from LLMs' inherent characteristics: strong retrieval capabilities but limited reasoning, restricted attention windows, and lack of persistent memory. The Koan framework is designed precisely to address this pain point.

## Koan's Core: Normative Workflows and Memory System

Koan's three core components form a complete solution:
1. **Norm-based multi-round workflow**: Decompose tasks into fixed phases (e.g., Intake→Plan-Spec→Plan-Review→Execute). The orchestrator strictly advances in sequence to ensure the process is controllable and auditable;
2. **Decision capture mechanism**: During agent operation, documents like landscape.md (code panorama) and plan.md (execution plan) are generated to form durable records, addressing issues of decision transparency and traceability;
3. **Project memory system**: Maintains the `.koan/memory/` repository, supporting three reading modes: status (panoramic summary), query (semantic + keyword retrieval), and reflect (comprehensive answers). Memory entries require user approval to ensure quality.

## Koan's Technical Architecture: Security and Decentralized Design

Koan's architecture emphasizes developer autonomy and data security:
- **Local process model**: Driven by Python processes, sub-agents are called via CLI tools, no API proxy needed, zero OAuth credential handling, data flows locally;
- **Role separation**: Orchestrator (runs workflows), Scout (read-only code investigation), Executor (implements changes). The driver program verifies phase transitions and permission boundaries;
- **In-code documentation**: Encourages writing architectural decisions and invariants alongside code. These are read and updated during workflow execution to reduce the risk of outdated documentation.

## Koan's Application Scenarios: Long-Term Projects and Collaborative Environments

Koan is particularly suitable for three types of scenarios:
1. **Long-term maintenance of large projects**: The memory system and workflow norms help teams record architectural decisions, allowing new members to quickly understand the project context;
2. **Multi-developer collaboration**: Normative workflows and decision capture provide a common language and standards, avoiding style inconsistencies and repeated implementations;
3. **High-reliability systems**: Decision documents and review records provide a technical foundation for compliance audits in fields like finance and healthcare.

## Koan's Limitations and Future Outlook

**Current Limitations**: Unstable interfaces (Alpha phase), dependency on Claude/Codex/Gemini CLI tools, mainly optimized for Python projects, need to adapt to strict workflows;
**Future Directions**: Enrich built-in workflow templates (test-driven development, refactoring, etc.), deeply integrate tools like IDE/CI/CD, automatically optimize memory retrieval based on data, and establish a community-contributed template market.