structure｜1️⃣ 三级笔记、思想框架

🏗️ 思想框架

核心论点：Claude Code 不是一个 AI 编程助手，而是一个以 LLM 为内核的操作系统。51.2 万行代码中，真正调用 LLM API 的部分不到 5%，其余 95% 是安全、权限、上下文管理、错误恢复、多 Agent 协调等「脚手架」。

文章缘起：2026年3月31日，安全研究者 Chaofan Shou 发现 Anthropic 发布到 npm 的 Claude Code 包中 source map 文件没有被剥离，完整 TypeScript 源码（51.2万行，1903个文件）暴露在公网。作者带着三个问题去读源码：

1. Claude Code 和其他 AI 编程工具有什么本质区别？
2. 为什么它写代码的**「手感」就是比别人好**？
3. 51万行代码里到底藏着什么？

📝 大纲笔记

一、三种安全哲学——一个「雇远程程序员」的比喻

• Cursor 的做法：让程序员坐你旁边，每次敲命令前你看一眼点「允许」。简单粗暴，但你得一直盯着
• GitHub Copilot Agent 的做法：给一台全新虚拟机，随便折腾，搞完提交代码你审核合并。安全，但看不到你本地环境
• Claude Code 的做法：让他直接用你的电脑，但配一套极其精密的安检系统——能做什么、不能做什么、哪些需要你点头、哪些可以自己来，甚至 rm -rf 要经过 9 层审查
• 为什么选最难的路？ 只有这样，AI 才能用你的终端、你的环境、你的配置来干活——这才是「真正帮你写代码」，而不是「在干净房间里写一段代码复制过来」
• 代价：为此写了 51 万行代码

二、实际架构——不是 LLM wrapper，是完整的执行管线

• 大多数人以为的 AI 编程工具：用户输入 → 调用 LLM API → 返回结果 → 显示
• Claude Code 实际的执行流程：
  1. 动态组装 7 层系统提示词
  2. 注入 Git 状态、项目约定、历史记忆
  3. 42 个工具各自附带使用手册
  4. LLM 决定使用哪个工具
  5. 9 层安全审查（AST 解析、ML 分类器、沙箱检查…）
  6. 权限竞争解析（本地键盘 / IDE / Hook / AI 分类器同时竞争）
  7. 200ms 防误触延迟
  8. 执行工具 → 结果流式返回
  9. 上下文接近极限 → 三层压缩
  10. 需要并行 → 生成子 Agent 蜂群
  11. 循环直到任务完成

三、提示词系统——不是「写」出来的，是「拼装」出来的

• 缓存分界线设计（SYSTEM_PROMPT_DYNAMIC_BOUNDARY）：
  • 分界线上方：静态内容（可缓存），如基础指令、工具说明、风格指南
  • 分界线下方：动态内容（每次不同），如 Git 分支、CLAUDE.md 配置、用户偏好记忆
• 本质：把提示词当成编译器的输出来优化。静态部分 = 编译后的二进制，动态部分 = 运行时参数
• 好处：省钱（静态部分走缓存不重复计费）、快（缓存命中跳过处理）、灵活（动态部分感知当前环境）
• 每个工具都有独立的「使用手册」（prompt.ts）：专门写给 LLM 看的行为准则
  • 例：BashTool 的 prompt.ts 约 370 行，明确写了 Git Safety Protocol：不准 push --force、不准 reset --hard、不准跳过 hooks
  • 这就是为什么 Claude Code 不会擅自 git push --force——不是模型更聪明，是提示词里已经把规矩讲清楚了
• 内部版本 vs 外部版本：USER_TYPE === 'ant'（Anthropic 内部员工）有更详细的代码风格指引、更激进的输出策略、A/B 测试中的实验功能
  • 说明 Anthropic 自己是 Claude Code 最大的用户，用自己的产品开发自己的产品

四、42 个工具——延迟加载 + fail-closed 安全设计

• 延迟加载：大部分工具不是一开始就加载，而是当 LLM 需要时通过 ToolSearchTool 按需注入
  • 原因：每多一个工具，系统提示词多一段描述，token 多花一份钱
• 极简模式：设置 CLAUDE_CODE_SIMPLE=true，只剩三个工具（Bash、读文件、改文件）——给极简主义者的后门
• fail-closed 安全默认：
  • isConcurrencySafe 默认 false，isReadOnly 默认 false
  • 如果工具作者忘了声明安全属性，系统假设它是「不安全的、会写入的」
  • 宁可过度保守，也不漏掉一个风险
• 「先读后改」铁律：FileEditTool 会检查你是否已用 FileReadTool 读过文件，没读过直接报错不让改
  • 这就是为什么 Claude Code 不会「凭空写一段代码覆盖你的文件」——被强制要求先理解再修改

五、记忆系统——为什么它能「记住你」

• AI 驱动的记忆检索：用另一个 AI（Claude Sonnet）决定「哪些记忆和当前对话相关」
  • 不是关键词匹配，不是向量搜索——让小模型快速扫描所有记忆文件，选出最多 5 个最相关的注入上下文
  • 策略：精确度优先于召回率——宁可漏掉可能有用的记忆，也不塞进不相关的记忆污染上下文
• KAIROS 模式：夜间「做梦」
  • 长会话中的记忆存在按日期的追加式日志中
  • /dream 技能在低活跃期运行，把原始日志蒸馏成结构化的主题文件（用户偏好、项目背景等）
  • AI 在「睡觉」的时候整理记忆——不是工程，是仿生学

六、多 Agent 蜂群——不是一个 Agent，是一群

• 子 Agent 机制：复杂任务时，主 Agent 会生成子 Agent，可指定模型（sonnet/opus/haiku）、可后台运行
• 严格的「自我意识」注入：防止子 Agent 递归生成更多子 Agent
  • 核心指令：「你是一个工人，不是经理。别想着再雇人，自己干活。」
  • 回复必须以「Scope:」开头，不超过 500 词
• Coordinator 模式（经理模式）：Claude Code 变成纯任务编排者
  • Phase 1 Research → 3 个 worker 并行搜索代码库
  • Phase 2 Synthesis → 主 Agent 综合理解
  • Phase 3 Implementation → 2 个 worker 分别修改不同文件
  • Phase 4 Verification → 1 个 worker 跑测试
  • 核心原则：「Parallelism is your superpower」——只读任务并行，写文件按文件分组串行
• Prompt Cache 极致优化：所有 fork 子代理的工具结果用相同占位符文本，最大化字节级前缀匹配的缓存命中率

七、三层上下文压缩——让对话「永不超限」

• 第一层：微压缩（最小代价）——只动旧的工具调用结果，把「10分钟前读的500行文件」替换成 [Old tool result content cleared]，对话主线完全保留
• 第二层：自动压缩（主动收缩）——token 消耗接近上下文窗口 87% 时自动触发；熔断器设计，连续 3 次压缩失败后停止尝试
• 第三层：完全压缩（AI 总结）——让 AI 对整段对话生成摘要替换所有历史消息；严厉前置指令禁止总结过程中调用任何工具

八、四大启示

1. AI Agent 的 90% 工作量在「AI」之外：安全检查、权限系统、上下文管理、错误恢复、多 Agent 协调、UI 交互、性能优化。不是模型够不够聪明，是你的脚手架够不够结实
2. 好的提示词工程是系统工程：7 层动态组装、每个工具独立使用手册、缓存边界精确划分、内外版本不同指令集、工具排序固定保持缓存稳定。是工程化的提示词管理，不是手工艺
3. 为失败而设计：每一个外部依赖都有对应的失败策略
4. Anthropic 把 Claude Code 当操作系统在做：42 个工具 = 系统调用、权限系统 = 用户权限管理、技能系统 = 应用商店、MCP 协议 = 设备驱动、Agent 蜂群 = 进程管理、上下文压缩 = 内存管理、Transcript 持久化 = 文件系统

一句话总结：要让 AI 真正有用，你不能把它关在笼子里，也不能放它裸奔——你得给它建一套完整的信任体系。而这套信任体系的代价，是 51 万行代码。

concepts｜2️⃣ 关键概念、概念网络

agentic reading｜3️⃣ 费曼 x3