AAperture
Back/claude code

.claude/ Folder as Production Agent

Updated 2026-04-19
2 min read
270 words

.claude/ Folder as Production Agent

Pawel Huryn 的核心洞察：你每天都在编辑的 .claude/ 文件夹本身就是可部署的生产级 Agent 运行时。从开发到生产无需翻译层。

缺失的模式：Agent as Callable Component

两个主流叙事：

  • Agent 作为产品（Claude Code, Cursor）
  • Agent 作为基础设施（LangGraph, Managed Agents, CrewAI）

中间的空白：Agent 作为应用内部的可调用组件。

你的 web app 处理路由、auth、CRUD。当请求需要推理时，调用 agent。Agent 在沙盒中运行，带着自己的 CLAUDE.md、skills 和 MCP servers。

五大原语

原语 说明
CLAUDE.md Agent 的身份定义。开发时在终端塑造 Claude Code 行为；生产时作为 system prompt 加载
Skills (.claude/skills/) 可复用行为，markdown 格式。开发与生产共用同一文件格式和 loader
MCPs (.claude/mcp.json) 扩展 agent 工具表面。开发配置连接 Chrome/文件系统；生产配置连接搜索 API/数据库。不同服务器，相同契约
Hooks 工具事件触发的函数。PreToolUse 阻止危险操作；PostToolUse 记录 agent 读取的一切
Sub-agents (.claude/agents//) 每个文件夹是自包含 agent：自己的 CLAUDE.md、skills、MCP 配置。添加第二个 agent = 新建文件夹

一切都是文件。一切都能版本控制。一切都在 PR 中 diff。

生产调用方式

for await (const msg of query({
  prompt: question,
  options: {
    cwd: './.claude/agents/knowledge-agent',
    settingSources: ['project'],
    allowedTools: ['Read', 'Glob', 'Grep'],
    maxTurns: 5,
    maxBudgetUsd: 0.15,
    model: 'claude-sonnet-4-6',
    hooks: { /* guardrails */ },
  },
})) {
  // stream text, collect metadata
}

settingSources: ['project'] 是自动加载器：从 cwd 读取 agent 的 CLAUDE.md、skills 和 MCP 配置。与 Claude Code 打开会话时的行为一致。

与替代方案的对比

维度 Agent SDK Managed Agents LangGraph n8n
学习成本 无（肌肉记忆即生产运行时） 新平台 新抽象 节点图
适用场景 已有自托管应用内的请求-响应 agent 需要完整平台能力 复杂状态流 工作流编排
可观测性 Hooks 提供实时 per-response 元数据 + OTEL 导出 平台内置 图节点级别 节点级别

关键注意事项

  • Root CLAUDE.md 是 dev-only：帮助你在 IDE 中维护应用的 CLAUDE.md 不应进入生产。在 postbuild 中移除它。
  • Next.js standalone 非 serverless：SDK 启动完整 Claude Code 运行时，不是轻量 API client。

对 Jean 的启发

你已经在维护的 .claude/ 配置可以直接嵌入到个人产品/服务中。无需学习新框架。

Sources

Linked from