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

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.

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 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 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 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.

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.