icm-architect

ICM 架构师

构建由文件夹结构负责编排的工作区。一个 Agent 在恰当时机读取合适的文件，就能替代多 Agent 框架：编号文件夹承载顺序，层级划分上下文范围，纯 Markdown 文件承载状态。任何人都能打开任意文件夹，查看系统当前状态，因为状态就是文件。路由文件就是目录：它们小巧且稳定，指向内容所在的位置。

方法：可解释上下文方法论（Van Clief & McDermott，arXiv:2603.16021，采用 MIT 许可证）。它适用于任何能够读取文件的 Agent 或模型：工作区中的任何内容都不依赖某个供应商的工具。

不变量

每个 ICM 都从以下十条原则开始。它们是默认规则：当你知道什么有效，并需要进行细致调整时，可以有意打破其中一条，并在最近的 CONTEXT.md 或 AGENTS.md 中说明原因。

1. 一个文件夹，一个职责（Unix、Parnas）。每个文件夹只执行一个步骤或容纳一种内容，并在自身内部的文件中说明用途。结构本身就是文档。
2. 小巧、稳定的入口文件。 根目录下的 AGENTS.md 只回答“我在哪里、所有内容存放在哪里、任务 X 应该去哪里”。少于约 60 行；它负责路由，绝不承载内容。寻找其他文件名的工具只会得到指向该文件的一行说明，不会有第二份副本（参见 references/core.md 的“命名”）。
3. 编号表示顺序。 在顺序重要时使用 01_、02_ 等。
4. 每个工作文件夹都有契约。 一个 CONTEXT.md：说明它读取什么（输入）、执行什么（流程）、写入什么（输出）以及如何检查。参见 assets/templates/stage-CONTEXT.md。
5. 工厂与产品（持续交付）。参考资料（规则、语气、架构、模板：在各次运行间保持稳定）与工作产物（输出、草稿：每次运行都会产生新内容）分开存放，因为它们对模型的作用不同：参考资料用于约束，输入则是处理对象。工厂只需配置一次；产品是每次运行生成的内容。
6. 每个步骤都以检查结束（Horvitz、Shneiderman）。每项输出都是人可以打开、编辑和保存的纯文件。在通过阶段于 ## Check 下指定的检查之前，不会进入下一步：检查者可以是人、脚本或小型模型。非人工检查需要在输出旁写入 check.md，第一行写 pass 或 fail: <why>；失败则在此处停止运行。停止正是目的：在这里发现的错误转向不会在后续步骤中被放大。
7. 只加载当前步骤所需内容。 步骤只读取自己的契约、参考资料和输入，而不是整个工作区：控制在约 8,000 个令牌以内。要预防，不要压缩。
8. 纯文本、可链接、可查询（Kernighan、Pike）。使用 Markdown + YAML frontmatter。链接构成图谱；frontmatter 标签使其可查询。每条事实只保留一个存放位置；链接胜过副本。链接和输入路径均使用相对路径，且必须能解析；仅在声明为 Obsidian 库时使用维基链接。第一个标题应说明文件名称及其职责，因此 grep -rm1 '^# ' . 可以列出任意目录树中的文件。
9. **状态保存在磁盘上：**通过文件是否存在来表示，或在其描述的文件中写入一行状态。生成的索引（_index.md、文件映射）通过脚本重建，绝不手动编辑。
10. 通过复制来实例化。 新的工作单元应复制模板，而不是从空白页开始。模板存放在 _templates/，脚本存放在 _tools/。

选择模式

• 构建：根据已描述的流程、想法或问题进行构建。
• 重构：对现有文件夹、代码仓库或库进行整理，使其具备 ICM 结构。

有些形式自带流水线（系统映射；基于来源构建知识包）。其参考资料会说明它替代了哪些步骤。

三种基本构件

每个 ICM 都由三种内容构成：

• 序列：带编号的文件夹；每个步骤的 output/ 都是下一步骤的输入。
• 资料架：包含同类型文件的文件夹，每个文件都由同一个模板复制而来。
• 目录：一个只向下指引、不存储内容的小文件：AGENTS.md、一个 CONTEXT.md、生成的索引或图谱。

下面的形式都是基于这些基本构件的配方。可以自由嵌套；每一层都保留自己的小型目录，用于向下链接并在此处止步。Umbrella 是一个指向多个流水线的目录，根目录中存放它们共享的资料架。如果没有合适的形式，就用这三种基本构件来构建，并在入口文件中为配方命名。

构建模式

1. 从对话中提取结构。 结构已经体现在对方描述工作的方式中：呈现他们的结构，不要强加自己的。每次问几个问题：

• 重复进行的工作单元是什么？（一个事件、一个客户、一份报告、一个人、一个团队？）
• 带我走一遍完整流程，从开始到结束。你会在哪里停下来检查，然后再继续？
• 每次运行时，哪些内容保持不变（语气、规则、品牌、架构），哪些内容每次都是新的？
• 怎样才算“完成”：什么产物会离开工作区？
• 还有谁会参与其中？他们需要找到什么，才能不必问你？

他们停下来的地方就是阶段边界。他们说的“我总是在 Y 之前检查 X”就是检查项。他们说的“它总得听起来像 / 遵循 Z”就是工厂参考资料。

2. 选择形式。 阅读 references/forms.md 并作出选择：

形式	基于	适用场景
流水线	一个序列	相同步骤会反复运行，每次都会产出一份交付物
记录库	一个记录资料架，每条记录都有一行状态	工作单元是会不断累积内容的记录（个人、客户、会话）
知识包	相互链接的笔记资料架，通常由序列从来源中填充	产品就是知识：某人的思维方式，或构建某个产物所依据的想法
上下文图谱	团队、流程和数据资料架，通过 consumes: / produces: 链接	主题是一个组织
系统图谱	名词和动词资料架，加上影响索引，由带关卡的序列填充	一棵之后会由其他 Agent 编辑的树

3. 搭建承载工作所需的最小结构。 从 assets/templates/ 复制起始模板，并将所需脚本从 scripts/ 复制到 _tools/。不要为尚不存在的阶段创建文件夹，不要建立空的“杂项”目录，也不要预先设计层级。三个真实阶段胜过七个想象出来的阶段。如果整个工作只需一个保存好的提示词就能完成，请直说，无需构建工作区。

4. 编写契约。 根目录的 AGENTS.md（身份 + 路由表，来自 assets/templates/entry.md），再加上所有读取其他名称的所有者 Agent 所使用的单行指针，始终包括你正在运行的那个（references/core.md 中的“命名”部分）；根目录的 CONTEXT.md（流水线或架构）、每个工作文件夹中的一个 CONTEXT.md，以及在工厂需要为每位用户配置时创建的 setup/questionnaire.md。输入必须是精确的反引号路径，分为工作输入（本次运行）和参考输入（每次运行）。

5. 使用走查测试进行验证（见下文）。

重构模式

1. 操作前先清点。 列出目录树。对每个区域注明它是什么、上次修改时间，以及有哪些内容引用它。此阶段不要删除或移动任何内容。

2. 找出隐藏的形态。 询问负责人（或推断后确认）：这里重复出现的单元是什么？工作从哪里进入、从哪里离开？混乱之中通常藏着一个真实的流水线、库或地图，只是缺少骨架，逐渐变得杂乱：把它提取出来，而不是替换它。

3. 将每个文件归为以下五种角色之一：

• 目录：标识与路由（成为或提供内容给 AGENTS.md 和索引文件；现有的 CLAUDE.md、GEMINI.md 或类似文件，其内容在第 6 步放入 AGENTS.md 或资料架后，改为一行指向说明）
• 契约：说明某个步骤如何运作（成为 CONTEXT.md）
• 工厂：稳定的参考资料（放入 _shared/）
• 产物：特定运行产生的内容（放入某个阶段的 output/ 或记录文件夹）
• 废弃项：过时、重复或已被取代的内容（建议移入 _archive/，绝不删除），且只有在第 4 步确认没有依赖它的内容后才能这样归类

4. 提议移动前，先查明有哪些内容指向每个文件。 看似未使用并不代表可以处理。检查工作区内的链接、同级目录中的 ../ 路径、符号链接，以及工作区外的使用方：其他仓库、配置、定时任务、硬编码了路径的 Agent 配置。目录树中不会列出工作区外的使用方，因此要询问负责人。仍有使用方的文件应保留；只有在同一次变更中更新了所有使用方，才能移动文件。

5. 移动前先提出方案。 展示目标目录树和迁移映射（旧路径、新路径、角色、找到的使用方）。根据第 4 步的调查结果取得批准。这是一套以检查为基础的方法中的一道检查：务必遵守。

6. 迁移：先复制，再验证，最后移除。 首先确认工作区已纳入版本控制或已备份。复制或重命名前，检查目标位置是否已存在大小写折叠后相同的文件名：在 Windows 和 macOS 上，将文件重命名为 CONTEXT.md 会静默覆盖已有的 context.md，而文件清单不会显示这种冲突；所有冲突都必须在审批环节指出。将文件复制到新位置，验证一致性（文件数量和内容哈希；对于压缩的办公文档格式，比较解压后的内容），然后移除原文件，并在有内容引用它的地方留下链接。编写入口文件和契约，并去重，确保每条事实只有一个存放位置。如果此结构会重复使用，请将空白模板与这次已填充的部署分开保存。

7. 执行走查测试。

走查测试

像一个没有记忆的 Agent 一样，从头开始走查：

• 打开根目录。只看入口文件和最多再读两个文件，能否回答我在哪里以及当前任务该去哪里处理？
• 随便选一个工作文件夹。它的契约是否写明了确切的输入路径、任务、输出和检查方式？
• 能否仅根据磁盘上现有的内容判断状态，包括任何 check.md 中的结论？
• 是否有路由文件包含了实际内容？将内容移到资料架，留下指向说明。
• 是否有事实存放在两个位置？选定一个存放位置；从另一个位置链接过去。
• python -I _tools/links.py 是否通过（若没有 Python，是否每个要访问的链接都能正常解析）？重构后，它会显示树内的每个链接和契约输入仍能解析；工作区外的使用方则以负责人在第 4 步提供的清单为准。
• 单个契约及其输入是否控制在约 8,000 个 token 以内？
• 每个被破坏的不变量是否都在其被破坏的位置得到说明？

然后按照该形态的参考资料运行其自身检查。如果某一步失败，就修复结构；不要靠增加说明来解决，而要移动或拆分文件，直到走查顺畅为止。

护栏

• 不要过度搭建结构。 路径依次是：聊天，然后是已保存的提示词或技能，再然后是文件夹和一个 Agent。只有当下一层确实已实现自动化且会反复使用时，才继续往上走。为一件只做过两次的事情建立工作区，是在搭脚手架，不是在设计架构。
• 让它逐渐成熟。 如果某一步是代码，就要注明其命令，并从工作区根目录运行，例如 3. 运行 `python _tools/count_rows.py stages/03_tally/output/rows.csv`：命令就是这一步。某个阶段可以保留 examples/，其中放入一个真实输入，以及一次满意运行所产生的一个良好输出，并将它们列在输入项下。在实际使用的 ICM 中，应合并无人编辑的阶段，给从不失败的脚本添加检查，并拆分不断扩大的契约。
• 了解 ICM 的不足之处。 实时多 Agent 协作、高并发多用户服务，以及自动化的管线中途分支，确实需要框架代码。ICM 适用于顺序执行、经过检查且可重复的工作：大多数知识工作，但并非全部。

参考资料

• references/core.md：五层上下文层级、契约格式、命名和库规则。编写契约或对结构决策有争议时阅读。
• references/forms.md：深入介绍五种形式：骨架、操作方式和失败模式。在构建或重构的第 2 步阅读。
• references/system-map.md：系统图的审计管线。选择该形式时阅读。
• references/bundle-from-sources.md：从转录文本、访谈或研究中构建知识包，并逐条核实所有引文。选择该变体时阅读。
• assets/templates/：可复制的模板。适用于任何形式：entry.md（复制到根目录并命名为 AGENTS.md）、CONTEXT.md、stage-CONTEXT.md、questionnaire.md。上下文图：context-map-node.md、context-map-schema.md。系统图：object.md、process.md。来源知识包：concept.md、source.md、plan.md、claim.md、bundle-schema.md、keep-out.txt。
• scripts/：可选的标准库 Python 脚本，复制到工作区的 _tools/ 中。links.py 检查链接和输入路径是否有效（--graph 还会生成图）；viz.py 将一个或多个图绘制为 viz.html；index.py 根据笔记生成 _index.md；quotes.py 根据来源核查引文，并确保不包含禁用短语。