ICM Methodology: Directory Structure as AI Agent Architecture

⚡ The Gist in 5 Seconds - What it is: Interpretable Context Methodology (ICM) replaces framework-level orchestration with orchestration via file system structure: Markdown files contain prompts and context for each pipeline step. - Where it's available: a summary of the original article by Jake Van Clief and David McDermott was published on Habr by artem_dobrovinskiy on October 4. - Limitation: the approach is designed for sequential processes with human review; for complex multi-task systems, classic frameworks like CrewAI, LangChain, and AutoGen are a better fit. ### 🔍 What Was Found ICM is built on five principles: one stage — one task; text as the interface (stages communicate via markdown and json); loading context in layers; a stage's artifact can be edited by a human; configuring the factory, not the product (configuration is reused across runs). The workspace architecture is a 5-layer context hierarchy: layer 0 (AGENTS.md, ~800 tokens) answers the question "where am I?", layer 1 (CONTEXT.md, ~300 tokens) — "where do I go?", layer 2 (the current stage's CONTEXT.md, 200–500 tokens) — "what do I do?", layer 3 (reference material, 500–2000 tokens) — "what rules do I follow?", layer 4 — work artifacts the agent operates on. An example workspace: a workspace/ directory with AGENTS.md, CONTEXT.md, and stages/ folders (e.g., 01_research, 02_script, 03_production), each containing its own CONTEXT.md, references/, and output/. The /output of the previous step becomes the input of the next. An artifact edited by the user is used as is. Layer 2 and 3 files define contracts and constraints so the agent doesn't load all files into context or decide on its own what matters. ### 💡 Why It Matters The key practical effect is shrinking the context window. According to the author, when implementing the approach, each pipeline stage loads no more than ~5.6k tokens for a task that would require 42k tokens in a monolithic solution. Since long context inevitably degrades accuracy, this kind of relevance control directly improves model performance. Plus, every step is readable, verifiable, and editable by a human, which implements the principles of mixed-initiative and direct manipulation. ### 🧩 Context The author of the summary notes that the current approach to AI agent orchestration is usually built on frameworks (CrewAI, LangChain, AutoGen) that handle context passing, memory, error handling, and step coordination. For complex multi-task systems this is justified, but for sequential processes with human oversight such frameworks add enormous engineering overhead. ICM takes as its foundation the Unix-pipeline idea and Dijkstra's separation of dependencies: modules hide details from each other, each is responsible for a single task, and the developer only needs to define the order of execution.

🔗 Read on habr.com