RinDig/icm-architect · 上手攻略

  • 仓库：RinDig/icm-architect
  • 链接：https://github.com/RinDig/icm-architect
  • 分类：AI Agent · 架构方法论
  • 作者：Jay
  • 更新：2026-08-08

这是什么

ICM-Architect 是一个 Claude Code 技能（Skill），用于将任何流程、想法或问题设计成 ICM 工作区——即一套文件夹结构作为 Agent 架构。它也可以把一个已有文件夹/代码库重新组织成 ICM 格式。

ICM 全称 Interpretable Context Methodology（可解释的上下文方法论），源自论文 Interpretable Context Methodology: Folder Structure as Agent Architecture（Van Clief & McDermott）。核心思想是：用文件夹编号表示执行顺序，用层级表示上下文作用域，用纯 Markdown 文件存储状态。一个 Agent 读取正确的文件、在正确的时机行动，就能替代一整套多 Agent 框架的工作。

简单说：把「多 Agent 协调代码」换成「文件夹结构」，人类打开任意目录也能直接看懂系统当前状态。

解决什么问题

  • 想要让 AI Agent 按特定流程工作，却不想引入重型多 Agent 框架（CrewAI、LangGraph 等）
  • 现有项目结构混乱，希望重构为 AI 可读、可操作的形式
  • 需要让 AI 在无记忆状态下也能通过文件自行定位、行动并报告状态
  • 想让非技术用户也能理解和审核 AI 的工作流程

快速安装

Claude Code 用户

# 方式一：复制到全局 skills 目录
cp -r /path/to/icm-architect ~/.claude/skills/icm-architect/

# 方式二：放到项目级 skills 目录（项目专属）
mkdir -p .claude/skills/
cp -r /path/to/icm-architect .claude/skills/icm-architect/

安装后在 Claude Code 对话中直接使用指令触发：

ICM this
structure this for agents
build me a workspace for X

Claude.ai 网页/应用用户

使用 skill-creator 打包工具 将 icm-architect/ 文件夹打包为 .skill 文件，或直接 zip 整个文件夹内容，然后通过 Settings → Capabilities → Upload Skill 上传。

核心用法

Build 模式：凭空设计新工作区

描述你的任务，ICM 会：

  1. 从你的描述中提取已有结构（阶段、人工审核节点、稳定内容 vs 每次运行的内容）
  2. 从五种已验证形式中选择最合适的一种
  3. 脚手架最小工作区来承载该结构

典型对话：

请为我的论文修改流程设计一个 ICM 工作区，包含：初稿评估、人工审核、定稿三个阶段。

Restructure 模式：重构已有目录

请审计当前项目目录，将其重组为 ICM 格式。

ICM 会：

  1. 审查每个文件，分类为：catalog（路由）/ contract（合约）/ factory（工厂）/ product（产品）/ dead（废弃）
  2. 提出迁移地图供你批准
  3. 执行迁移并验证

五种组织形式

形式 适用场景
Pipeline 生产线式，顺序执行，适合内容生产流水线
Umbrella 多个 Pipeline 的组合，适合多业务线管理
Record Library 人员/客户/会话记录，适合管理系统
Knowledge Bundle 可导航的知识库，适合研究调研
Context Map 组织结构图，适合复杂组织协作

Walk Test（验证方法）

每种 ICM 结果都通过 Walk Test 验证：一个没有记忆的 Agent，仅凭文件必须能完成自我定位、执行任务、报告状态。

典型适用场景

  • 论文/内容创作流程：从选题到发表的多阶段人工审核流水线
  • 代码审查流程：PR 提交 → AI 初审 → 人工复核 → 合并
  • 客户服务工作流：工单 → AI 分类 → 人工处理 → 归档
  • 多业务线管理：不同产品线各自 Pipeline，统一 Umbrella 管控
  • 个人知识管理：研究资料收集 → 整理 → 写作 → 审核

坑与注意

  1. 不是代码库框架：ICM 是纯文件夹+Markdown 规范，不是一个可安装的库，无需任何运行时依赖
  2. Build 模式依赖描述质量：你描述得越精确，ICM 提取的结构越准确；模糊描述会导致选错形式
  3. Restructure 有破坏风险：对已有项目执行前务必先备份，ICM 会实际修改文件结构
  4. 编号层级是关键约定：01-、02- 前缀表示执行顺序，a-、b- 前缀表示同一阶段内的子步骤；改动前缀即改变执行语义
  5. Walk Test 不等于功能正确：通过 Walk Test 只说明 Agent 能读懂结构，不保证业务逻辑正确
  6. 大型项目需手动分层：ICM 五层架构（CATALOG / CONTRACT / FACTORY / PRODUCT / DEAD）对复杂项目需要手动设计，初次使用建议从简单 Pipeline 开始

与同类对比

工具 定位 复杂度 可读性 适用规模
ICM-Architect 文件夹结构即架构 低 极高（纯文本） 小中型流程
LangGraph DAG 图 + 代码定义 高 中（代码即文档） 复杂多 Agent
CrewAI 角色 + 任务定义 中 中（配置驱动） 中型多 Agent
AutoGen 对话式 Agent 协作 高 低 研究原型
自定义文件夹模板 固定结构 低 中 简单流程

ICM 的核心差异：完全不需要任何框架或库，文件即系统，人类和 AI 共享同一套「源代码」。

一句话推荐结论

如果你的 AI 自动化流程不需要重型框架，只想用一套共享的文件夹结构让人类和 AI 同时看懂、执行、审核——ICM-Architect 是目前最简洁、最诚实的解法。