Skip to content
Back/Harness Engineering

文件夹即 Agent(The Folder Is the Agent)

View in Graph
Updated 2026-09-24
3 min read
670 words

文件夹即 Agent(The Folder Is the Agent)

来源:2026-04-14 The Folder Is the Agent 作者:Kieran Klaassen(Every AI 邮件助手 Cora 的 GM)

核心洞察

同一个模型,指向不同文件夹,就是不同的 Agent。

一个 Agent 的本质是"一个拥有足够上下文、让你不必每次重新解释一切的模型"。专业化不是模型能力的问题,而是上下文工程的问题。

~/cora/          → Rails 工程师 Agent(开发)
~/cora-agent/    → 运维工程师 Agent(监控/日志/数据库)

文件夹结构决定专业化程度

一个专业化 Agent 文件夹包含:

文件/目录 作用
CLAUDE.md 定义工作方式、约定、部署工作流
docs/developer-docs/ 架构报告、邮件处理管道等机构知识
docs/runbooks/ 运维模式、事故处理手册
docs/investigations/ 事后分析积累
.claude/agents/ 专门化子 Agent
.claude/skills/ 外部系统参考文件("驾驶舱")

开发/运维分离原则

将开发和运维工作分离到两个独立文件夹,防止 Agent 在做运维时意外修改生产代码:

  • 开发 Agent(~/project/):包含完整应用代码,负责构建功能
  • 运维 Agent(~/project-ops/):无应用代码,专注监控。技能包括:
    • 查询 AppSignal 检查错误和性能
    • 追踪 Render 日志
    • 从 Postgres 只读副本查询用户数据
    • 读取 Intercom 工单,关联客户投诉与技术问题
    • 将 GitHub 部署与生产事故关联

调度层(Dispatch Layer)架构

作者用两个命令替代了 20 个终端标签页:

Ruby daemon 监视目录
  → 创建 lead agent
  → lead agent 分解任务,写入文件
  → daemon 读取文件,在正确文件夹生成 worker agent
  → worker 写文件汇报结果
  → daemon 每 60 秒检查状态

两个核心命令:

  • /hey:获取状态报告(每个项目完成了什么、出错了什么、被阻塞了什么)
  • /orchestrate "Fix GitHub issue #1765":创建 lead agent,分解任务,生成 worker,产出 PR

关键设计:基于文件消息传递,没有自定义网络协议,没有复杂框架。

"The dispatch layer is not sophisticated infrastructure. The sophistication lies in the folders underneath it."

规模化失败模式

失败类型 原因 处理方式
编码 bug em dash/弯引号导致 daemon 崩溃(ASCII 编码问题) 手动排查,genuinely hard to find
上下文漂移 数十个 Agent 中有些运行过时版本 定期手动清理,无好的自动化方案
Agent 停滞 过多 API 调用或等待输入,状态永远"working" 仪表板监控 Agent 树

核心原则:不能 Vibe Orchestrate

先构建 → 自己使用直到可预测 → 信任后才交给调度层

跳过这一步会导致 Agent 为已完成的工作开 PR、提重复 issue。这与"不能 vibe code"(需要先规划)、"不能 vibe fix"(生产故障需要系统性排查)形成一套完整的 AI 工程哲学。

与 Compound Engineering 的关系

harness-engineering/compound-engineering 是这套方法论的完整版本:

  • Plan → Work → Review → Compound → Repeat
  • Compound 步骤:捕获解决方案 → 使其可检索 → 更新系统(CLAUDE.md + 新 Agent)→ 验证学习
  • 传统开发在 Review 后停止;Compound Engineering 在 Review 后继续积累

规模化:44 个文件夹 Agent(2026-04-20 更新)

来源:Every 2026-04-20

Kieran Klaassen 目前运行着 44 个文件夹 Agent,通过一个 Ruby 调度层在他睡觉时路由工作。

这是对 2026-04-14 原文(3 个文件夹示例)的显著规模化验证:

  • 原文:2 个核心 Agent(开发 + 运维)
  • 6 天后:44 个专业化 Agent 同时运行
  • 调度层:Ruby daemon,异步路由,无需人工干预

核心结论:这种架构具备真正的规模化能力,不是一次性实验。

相关页面

2026-09-05:文件夹 Agent 的可编排前提

来源:Every — The Folder Is the Agent 重刊版

Kieran Klaassen 对“文件夹即 Agent”的新一轮说明,重点从定义转向可编排条件。文件夹本身提供专业化上下文,dispatch layer 只负责路由、生命周期和状态可见性。作者运行 44 个 Agent,使用 Ruby daemon 监视 spawn request 目录,由 lead Agent 把任务拆成文件,再由 daemon 将 worker 分发到正确的项目文件夹。worker 通过文件报告结果,daemon 每 60 秒检查状态。

这次说明补充了从小规模到大规模的人工瓶颈。5 个 Agent 仍可由 terminal tabs 管理,10 个 Agent 开始出现遗漏,44 个 Agent 时需要统一的 /hey 状态报告、/orchestrate 任务入口、tmux panes 和 agent tree。文件通信足以承担最小的队列和回传协议,复杂度主要留在文件夹中的领域知识和工作标准。

作者还把“信任”明确成编排前的阶段。新项目应先 Build it、Use it、Trust it,再 Orchestrate it。规模化失败包括 US-ASCII daemon 被 em dash 和 curly quote 触发崩溃、任务版本漂移、重复工作和 Agent stall。多 Agent 研究的性能收益不能直接推导为编码收益,作者引用的 Anthropic 研究显示,多 Agent 系统约消耗 15 倍 token,适合信息可并行、价值足够高的任务。

Counterpoints & Gaps

  • 44 个 Agent、每 60 秒轮询和文件通信是作者的个人系统描述,不代表所有项目的最优架构。
  • 文章没有给出 context drift、stall 或重复任务的发生率,也没有证明文件通信在更高并发下仍然足够。
  • Anthropic 的 90.2% 研究评测针对研究任务,不能直接作为编码或运营任务的成功率。

Sources (addendum)

Pending Jean review

  • harness-engineering/folder-is-the-agent — ai_draft; suggested action: choose one recurring workflow and test Build it → Use it → Trust it → Orchestrate it with explicit drift and stall checks.

Fatih Arslan 的计划仓库:文件夹即 Agent 的长期任务变体(2026-09-16)

来源:Ben's Bites 2026-09-16

Fatih Arslan 把每个 agent 计划存成人类可读的 Markdown 文件,集中在单个 Git 仓库,目录分 drafts/、next/、open/、done/、discarded/。/plan-add 只捕获想法,/plan-write 补齐背景、决策和验证命令,/plan-dispatch 让 agent 执行并产出 PR,/plan-sync 对照 PR ���计划确认完成。计划增多后由长期运行的 coordinator 读取计划、分派工作、跟踪 Slack、PR 和指标,coordinator 不写代码。

这个案例把"文件夹即 Agent"从上下文专业化扩展到状态外置:一次约 460 条消息的错误循环中,他让旧 Project 写 handoff,新 Project 根据仓库中的 notes 重建状态,很快恢复工作。模型内部记忆适合便利,文件化状态适合恢复、交接和审计。这与本页 Build it → Use it → Trust it → Orchestrate it 的纪律一致:可靠性来自外置的人类可读状态,而不是 agent 记住了什么。

Sources (addendum)

2026-09-24:渐进式披露是文件夹 Agent 的导航层

来源:AI Briefing 2026-09-24 Morning

dotey 的文档实践补充了“文件夹即 Agent”的另一层:文件夹不仅承载任务状态和领域上下文,还需要有可导航的文档层。把文档放入统一 docs/ 目录,用根 README 做索引,再把细节拆成互链的小文件,可以让人和 Agent 都先获得地图,再按需加载局部知识。

这使项目规则从“把所有知识塞进一个 AGENTS.md”转向渐进式披露。AGENTS.md 可以强制功能改动同步相关文档,但不能替代目录结构、链接和人工定期检查。对长程 Agent 来说,文档结构本身就是上下文路由表。

Counterpoints & Gaps

  • 这是个人文档工作流经验,没有证明固定目录或 README 结构适用于所有仓库。
  • 强制文档更新可能增加维护成本;需要用实际导航时间、遗漏率和 Agent 任务成功率评估收益。

Sources (addendum)

Pending Jean review

  • harness-engineering/folder-is-the-agent — ai_draft; choose one active project and compare a monolithic instruction file with indexed, progressively disclosed docs by retrieval errors, stale-rule rate, and task recovery time.

Sources

Synthesized from 8 sources

Evolution

1 event
  1. absorbed

    Derived from source material

    This page is currently synthesized from 8 sources.

    Sources: raw/newsletters/Every/2026-04-14 The Folder Is the Agent.md · raw/newsletters/Every/2026-04-20 The Model Got Stranger.md · /Users/jean/Documents/Obsidian Vault/raw/briefing/AI Briefing/2026-09-24-08-05.md · /Users/jean/Documents/Obsidian Vault/raw/newsletters/Ben's Bites/2026-09-16 Good luck slowing this down.md · /Users/jean/Documents/Obsidian Vault/raw/newsletters/Every/2026-09-05 The Folder Is the Agent.md · raw/briefing/AI Briefing/2026-09-24-08-05.md · raw/newsletters/Ben's Bites/2026-09-16 Good luck slowing this down.md · raw/newsletters/Every/2026-09-05 The Folder Is the Agent.md

Linked from