Claude Code 几十万行代码依然容易读懂，核心秘诀就是严格切分五层，每一层只守住单一职责，不跨层混逻辑；入口负责启动分发，主循环驱动智能体迭代，工具层封装所有动作，权限层做独立安全闸门，提示词层专门拼装上下文，层与层之间依靠约定接口通信，而不是把配置、安全、执行、提示全部揉在一处，所以新人顺着调用链就能看懂整条任务链路，这也是很多自研 Agent 代码越写越乱、而它维持清晰的关键原因。入口层区分 CLI、VS Code 插件、SDK 嵌入等不同启动形态，只做参数解析、环境初始化、会话挂载，不介入模型推理和工具执行；主循环是调度心脏，接收用户输入、调用模型、收集工具返回，循环直到任务结束；工具层把读文件、编辑、Grep、Bash、MCP 外部能力统一抽象；权限层在工具真正运行前拦截，独立一套允许 / 询问 / 拒绝规则，不会散落在业务代码；提示词层把系统指令、CLAUDE.md、记忆、工具描述模块化组装，避免一大段硬编码字符串散落在各处。想要复刻这种思路，写智能体时就要遵守单向依赖：入口拉起循环，循环请求工具，工具先过权限校验，权限放行之后再把执行结果喂回提示词上下文，禁止反过来让工具直接修改提示词、或者权限逻辑埋进循环内部。总的来说，这套 “各管各” 不是花哨设计，是长期维护大型智能体工程的约束，把变化点隔离：改 UI、改安全策略、调整系统提示、新增工具，都只需要改动对应一层，不会牵一发而动全身。
五层总览对照表
| 分层 | 核心职责 | 典型文件 / 目录 | 关键原则 |
|---|---|---|---|
| 入口层 | 多形态启动、参数解析、初始化、路由到交互 / 一次性任务 | src/entrypoints、main.tsx | 只启动，不含业务逻辑 |
| 循环层 | Agent 主循环、消息流转、上下文压缩、子 Agent 编排 | query.ts、QueryEngine.ts | 驱动 “模型决策 → 工具调用 → 回送结果” |
| 工具层 | 内置工具与 MCP 外部工具实现、统一入参出参协议 | src/tools、MCP 客户端 | 动作收敛，模型只拿声明，不碰实现 |
| 权限层 | 工具调用前置校验、白名单、Hook、熔断、审批弹窗 | permissions.ts、PreToolUse Hook | 拒绝优先，独立于业务循环 |
| 提示词层 | 系统提示、工具 Schema、CLAUDE.md、记忆拼装 | prompts.ts、上下文组装器 | 模块化拼接，集中管理指令 |
每层细节清单
- ✅ 入口层：区分 headless 一次性任务、交互式 REPL、IDE 插件、SDK 调用；加载配置、代理、凭证，然后把控制权交给 QueryEngine；同一个内核支撑多种前端，不会出现多套重复调度逻辑。
- ✅ 循环层：标准流程：提交上下文 → 获取模型输出 → 识别工具调用 → 送审权限 → 执行工具 → 将结果并入对话；内置上下文压缩、超时、重试、子 Agent 派生，是整个智能体的状态机，但不定义任何工具的具体行为。
- ✅ 工具层：内置 Read / Edit / Write / Grep / Glob / Bash；外部能力走 MCP；统一 Schema，模型看到的只是声明；新增工具只需要注册，不用改动主循环；工具返回结果是结构化数据，而不是自由文本。
- ✅ 权限层：按顺序匹配静态规则、自定义 Hook、工具只读标记、安全分类器、熔断；支持自动允许、询问、拒绝三种动作；就算模型 “想调用高危命令”，也无法绕过这一层；权限判定和模型推理解耦，方便企业审计与管控。
- ✅ 提示词层：不再是写死的巨型字符串；拆成角色基线、工具说明、项目 CLAUDE.md、持久记忆、任务上下文；支持缓存、增量更新；调试提示词只改这一层，不会污染调度与安全代码。
和常见乱序 Agent 的对比
- ❌ 典型糟糕写法：权限判断散写在工具函数、提示词硬编码埋在循环、入口直接调用 Bash；改一处到处出错。
- ✅ Claude Code 风格：依赖单向；循环调用工具，工具调用权限校验；提示词作为上下文数据被循环读取；任何一层可以单独替换测试。
可复用的落地经验
- 工具定义和工具执行分离，模型只消费声明。
- 安全校验放在独立前置管道，不要靠模型自觉。
- 系统提示模块化，把项目本地规则（CLAUDE.md）作为独立片段注入。
- 主循环只负责流转，不写业务策略。
- 所有入口收敛到同一个引擎，减少分支。
【相关 FAQ】
问题 1：Claude Code 代码好读，五层架构里的循环层主要做什么？
回答 1：Claude Code 代码好读，循环层是智能体调度核心，负责来回推送消息、识别工具请求、收集返回结果、维持会话迭代，不插手权限和提示词细节。
问题 2：Claude Code 的权限层为什么单独抽成一层，而不是写在工具里面？
回答 2：Claude Code 代码好读，权限独立成一层是为了统一拦截所有工具调用，规则集中、便于审计，避免安全判断散落各处被绕过。
问题 3：Claude Code 的提示词层，是不是只是放一大段固定系统提示？
回答 3：不是，Claude Code 代码好读，提示词层负责模块化拼装，把角色指令、工具描述、项目 CLAUDE.md、记忆片段组合起来，方便单独调试与更新。
问题 4：如果模仿 Claude Code 五层架构自研 Agent，改动工具需要修改主循环吗？
回答 4：不需要，Claude Code 代码好读正是依靠边界隔离，新增或者修改工具只在工具层注册，主循环、提示词、权限层不需要大规模改动。
【参考资料】
[2026-04-01]（Inside Claude Code: Anatomy of a 512K-Line AI Agent）MdJawad
[2026-04-01]（从 Claude Code 看 Harness Engineering）Bojie Li
[2026-09-01]（深度拆解 Claude Code 架构）CSDN
[2026-04]（Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems）arXiv
[2026-11-08]（How the agent loop works）Anthropic Claude Code Docs
【免责声明】
本文基于公开泄露源码解读、官方文档与第三方架构分析；Claude Code 属于 Anthropic 闭源产品，该五层是工程拆解视角，并非官方正式命名的分层规范；自行复刻智能体时，安全、沙箱、权限策略仍需要独立审计。