设计原则与产品化
从源码里提炼出 7 条设计原则，加上产品化必须处理的第二天问题。每条原则都有对应的源码实现。
读完前七章的源码，可以提炼出几条贯穿整个系统的设计判断。这些不是事后总结的”设计哲学”，而是从具体实现里反推出来的——先有代码，再有原则。
产品化：处理”第二天”
先说容易被忽视的部分。
第一天让 AI agent 跑起来不难：给模型一套工具，写好 system prompt，跑通一个完整任务流程。难的是第二天——任务中途崩了怎么办？进程没退出怎么清？session 里的脏状态怎么恢复？
runAgent.ts 里有一长串不起眼但关键的函数，专门处理这些问题：
recordSidechainTranscript() 记录子 agent 的完整对话，不只记主流程——调试问题时往往需要翻子 agent 做了什么。writeAgentMetadata() 写元数据，包括任务状态、启动参数、执行时间。registerPerfettoAgent() 挂上性能追踪，把 agent 执行接入 Perfetto tracing 链路。
任务结束后的清理链同样重要：cleanupAgentTracking() 清理追踪状态，killShellTasksForAgent() 终止该 agent 启动的所有 shell 进程，还有 session hooks 清理、克隆文件状态还原、todos entry 清除。缺少任何一步，都可能在下次启动时遇到残留状态干扰。
Bridge 系统（bridge/ 31 个文件）处理远程控制和 IDE 集成，这是产品化的另一个维度——用户不只在命令行里用，还要嵌进 VS Code、JetBrains、网页界面。state/AppState.tsx 和 store.ts 管理全局应用状态。UI 层是 389 个组件文件加 96 个 Ink 文件，完整的 TUI 应用（React + Ink）。Telemetry 覆盖 Datadog、Perfetto tracing、OTel 事件、cost tracker、rate limit 管理。
这些基础设施加起来，比核心 agent 逻辑的代码量还多。产品化的成本就在这里。
7 条设计原则
1. 不信任模型的自觉性
好行为要写成制度，不指望 LLM 每次都”想到”该怎么做。
getSimpleDoingTasksSection() 把”做任务时的行为规范”硬编码进 system prompt——不是偶尔提醒，是每次都注入。getActionsSection() 同理。这些函数的存在说明：设计者清楚模型会遗忘、会漂移、会在不同 turn 里表现不一致，所以把关键约束写死在 prompt 里，不靠模型的”自觉”。
2. 把角色拆开
至少把”做事的人”和”验收的人”分开，两个角色不能是同一个模型实例。
Verification Agent 独立存在，不是主 agent 自我检查。Explore Agent 做信息收集，Plan Agent 做规划，两者分开避免收集阶段的偏见污染规划阶段的判断。角色拆分的代价是多一次 API 调用，收益是决策质量更稳定。
3. 工具调用要有治理
模型说要调工具，中间还要过输入校验、权限检查、风险预判、后处理——toolExecution.ts 的 14 步 pipeline 是这条原则的直接实现。
工具调用不是”模型说什么就执行什么”，而是”模型的意图经过治理之后执行”。这个区别在正常情况下感知不到，在边界情况下决定了命令是被安全执行还是直接造成破坏。
4. 上下文是预算
每个 token 都有成本，能缓存就缓存，能按需加载就不一开始全部塞进去。
SYSTEM_PROMPT_DYNAMIC_BOUNDARY 把 system prompt 切成静态部分和动态部分，静态部分命中缓存，动态部分每次刷新。Fork cache 让子 agent 复用父 agent 的缓存前缀。四道压缩机制优先做轻量操作。这些不是独立的优化点，是同一条原则在不同层次的体现。
5. 安全层要互不绕过
三层防护（classifier / hook / permission）可以相互配合，但任何一层不能绕过另一层。
resolveHookPermissionDecision() 是这条原则的实现核心。Hook 说 allow 不能绕过 settings 的 deny，classifier 的结果不能直接决定最终放行。拒绝在任何层可以快速生效，放行必须所有层都同意。非对称是刻意的设计选择，不是实现疏漏。
6. 生态的关键是模型感知
接了十个插件但模型不知道什么时候该用哪个——那这十个插件等于不存在。
MCP instructions 注入、skill discovery、session-specific guidance、agent 列表注入，解决的都是同一个问题：让模型知道自己现在有什么能力、在什么场景下该用哪个。这不是文档问题，是系统设计问题。感知机制如果缺失，再强大的扩展生态也无法转化为模型行为。
7. 产品化在于处理第二天
第一天跑起来不难。难的是任务中断了怎么续、脏状态怎么清、进程泄漏怎么办、session 怎么恢复。
runAgent.ts 的 cleanup chain、transcript recording、task lifecycle 管理，就是在处理第二天的问题。这些代码不会出现在 demo 里，但它们决定了一个工具能不能在真实环境里持续运行。
七条原则不是并列关系。原则 1（不信任自觉性）和原则 2（拆角色）解决模型行为的可靠性；原则 3（工具治理）和原则 5（安全层互不绕过）解决执行的安全性；原则 4（上下文是预算）解决可持续运行的成本；原则 6（模型感知）解决生态价值能否真正释放；原则 7（处理第二天）是所有原则能落地的基础设施前提。
从”会跑”到”能用”，距离就在这七条原则之间。
参考来源： 本文内容参考 Xiao Tan（@tvytlx）的《Claude Code 源码架构深度解析 V2.0》，基于原报告的分析框架和研究成果整理。