Analysis ｜ Claude Code 设计哲学¶
目的：从 50 万行代码里提取"反复出现的模式" = 设计哲学。 关联：所有 7 个阶段文档 + topics/ 专题。
1. 核心哲学（10 条）¶
1.1 "Ink 在 TUI 跑 React" —— 范式平移¶
Claude Code 不是"用 React 重写 CLI"——它是 "把 Web React 整套范式平移到 TTY"。
| Web | TUI (Claude Code) |
|---|---|
| React 组件树 | Ink 组件树 |
| DOM | Y 输出（ANSI 转义码） |
| CSS 布局 | Yoga flexbox |
useState |
useAppState(selector) |
useEffect |
自定义 hooks 85 个 |
| Redux/Zustand | 自研 60 行 store |
| React Router | 键位系统 3 层 |
| Suspense | use() + Suspense |
| Web Workers | InProcess MCP transport |
| 浏览器 | 终端模拟器 |
意义：任何 Web 前端工程师 = 半个 Claude Code 工程师。
1.2 "async function 是反应式底座" —— 标准优于库*¶
不用 RxJS、不用 EventEmitter、不用 callback —— 用 TC39 标准的 async function*。
理由： - 零依赖 - 跨运行时一致（Node/Bun/Deno） - backpressure 友好 - 取消友好（for-await break） - 可读性高
80% 的核心代码（query、tool.call、API client、MCP transport）都用这个模式。
1.3 "60 行 store + 50 行 React 桥 = 完整状态管理" —— 最小够用¶
不用 Redux Toolkit（3000+ 行）。
不用 MobX（复杂）。
60 行 + 199 行 Provider = 完整状态管理。
意味着： - 不需要中间件市场 - 不需要 dev tools 扩展 - 团队的代码就能维护
"够用就好"是 Claude Code 的工程哲学。
1.4 "DCE 编译时门控" —— 多产品线共用一份代码¶
100+ feature('XXX') 旗标 + process.env.USER_TYPE === 'ant'。
意义： - 公开版 + Ant 内部版 + 实验版 + Demo 版 = 同一份代码 - 不需要"分支管理"痛苦 - 编译时消除 = 性能 + 包大小双优化
类比：Feature Phone vs Smartphone 的多型号管理。Claude Code 用代码组织解决。
1.5 "类型是中央集线器" —— 领域驱动设计¶
AppState 类型导入项目里 30+ 业务模块的所有类型。
读 AppStateStore.ts 顶部 import = 读完整个项目业务领域。
// src/state/AppStateStore.ts 头部
import type { ... } from '../services/mcp/types.js'
import type { ... } from '../tools/AgentTool/...'
import type { ... } from '../utils/permissions/...'
// ... 30+ 业务模块
意义：类型 = 文档。类型 = 业务领域图。
1.6 "Ink fork + N-API 模板" —— 基础设施内嵌¶
仓库没有 package.json / node_modules。
- Ink 整 fork（50+ 文件 / 13306 行）
- N-API 模块 TS 侧类型内嵌（7 个模块）
意义：
- 不依赖外部 npm 包的版本兼容
- 可以定制 Ink 内部（CLAUDE Code 实际改了 use-input）
- N-API 平台细节可控
类比：Linux 内核的内置驱动，而不是模块化。
1.7 "性能考古" —— 注释即历史¶
StructuredDiff.tsx 顶部的 50 行注释引用了 PR 编号 #21439 / #20378。
意义： - 性能优化是"踩坑→修坑→再踩"循环 - 注释解释为什么（不是什么） - 未来维护者不需要翻 git log
类比：考古学家根据陶器碎片还原历史。读代码注释 = 读软件工程演进史。
1.8 "TypeScript 联合类型 + 类型守卫" —— 状态机的类型化¶
Message = UserMessage | AssistantMessage | ToolUseMessage | ...
isTerminalTaskStatus(status): status is 'completed' | 'failed' | 'killed'
意义：
- 状态机用 TypeScript 表达 + 强制
- if (status === 'pending') 后 TypeScript 知道是 running | ...
- 类型即文档 + 类型即运行时检查
1.9 "backpressure 来自事件循环" —— JavaScript 的力量¶
不用复杂流控库：
- 消费者慢 → 生产者 yield 后阻塞
- 事件循环自然 backpressure
- for await 是自然消费者
这是 Node.js 12 年前就具备的能力，只是大多数项目没用好。
1.10 "依赖显式 + 注入" —— 避免循环依赖的纪律¶
项目里反复出现"inlined X 打破循环依赖"注释。
解决方案：
1. 类型提到独立文件（types/permissions.js）
2. 复制代码 + "keep in sync"（少量可接受）
3. 运行时检查（isXxx(task) 用 type guard）
意义：大型项目必然有循环依赖，纪律比"完美的依赖图"重要。
2. 反模式（Claude Code 故意不做的事）¶
2.1 不用 Redux¶
60 行 store 已经够用。
2.2 不用 RxJS¶
async function* 已经够用。
2.3 不用 Express/Koa¶
Bridge 用原生 WebSocket / stdio。
2.4 不用 React Router¶
键位系统自研（更灵活）。
2.5 不用 styled-components¶
ThemedBox / ThemedText 是简单包装。
2.6 不用 i18n 库¶
英文为主（这是 CLI 工具的常见选择）。
2.7 不用 ORM¶
sessionStorage.ts 自管 JSON 持久化。
2.8 不用 Material UI / Radix¶
design-system/ 自研 14 个组件。
意义：Claude Code 选了"自研 + 标准" 而非"用生态库"。
代价：要维护 50 万行代码。
收益：完全可控 + 性能最优 + 学习价值最高。
3. 性能哲学¶
3.1 "module-level cache > useMemo"¶
Markdown.tsx 的 tokenCache 注释说 "useMemo doesn't survive unmount→remount"。
意义： - React 生命周期不可靠 - 长列表/虚拟列表场景必踩 - module-level Map + LRU 是唯一可靠方案
3.2 "正则短路 > 让计算更快"¶
MD_MARKER_REGEX.test() 比 marked.lexer() 快 300 倍。
跳过不需要的计算，比"让计算更快"更有效。
3.3 "WeakMap > Map"（在合适场景）¶
StructuredDiff.tsx 用 WeakMap 缓存 NAPI 高亮。
- patch 对象 GC 时缓存自动清
- 不会内存泄漏
- 适合"短命对象 + 高频缓存"
3.4 "性能注释即历史"¶
StructuredDiff.tsx 顶部的 50 行 PR 编号注释
- #20378 之前怎么做的
- #21439 为什么改回来
- 未来读代码的人知道为什么
4. 安全哲学¶
4.1 "纵深防御 4 层"¶
BashTool： - Layer 1: 解析（理解命令） - Layer 2: 路径（理解操作什么） - Layer 3: 危险（理解是否安全） - Layer 4: 沙箱（兜底隔离）
意义：单层永远会被绕过。多层 = 攻击者要绕过 4 次。
4.2 "工具白名单 + 通配符"¶
bashPermissions.ts 2621 行 = 通配符规则引擎。
- 用户可配允许 / 拒绝 / 询问
- 通配符语法（* / ? / [abc]）
- 多源优先级（policy > project > user）
意义：安全决策是"用户可控 + 团队规则"。
4.3 "敏感信息检测"¶
commitValidation.ts 检测 BEGIN PRIVATE KEY、api_key= 等。
- 不让 LLM 误 commit 密钥
- 不让 LLM 写带密钥的 commit message
4.4 "DCE 隔离实验性功能"¶
实验性 feature 旗标 = 不会进公开版。 - 用户不会因为"实验性 bug" 受害 - 内部可以快速试错
5. 可扩展性哲学¶
5.1 "MCP 是最重要的扩展点"¶
加新工具 = 装 MCP server = 0 行 Claude Code 改动。 MCP 协议 = "Claude Code 的 npm"。
5.2 "Plugins 完整扩展"¶
Plugin 目录 = 完整 TypeScript 模块。 Plugin 适合"长期 + 重量级"扩展。
5.3 "Skills 轻量扩展"¶
Skill = Markdown + 资源。 Skill 适合"短期 + 轻量"任务 prompt 模板。
5.4 "Commands 斜杠扩展"¶
Command = 子目录 + 入口文件。
Command 适合"用户主动触发"的场景（/commit /compact）。
5.5 "Tools LLM 扩展"¶
Tool = 7 文件结构。 Tool 适合"LLM 主动调用"的场景。
5 层扩展点 = 任何场景都有合适的扩展方式。
6. 工程纪律¶
6.1 "循环依赖 = 魔鬼"¶
注释里反复出现 "inlined X 打破循环" / "importing creates a cycle"。
纪律： 1. 类型提到独立文件 2. 必要时复制代码 3. 运行时检查
6.2 "Top-level side-effect 禁止"¶
ESLint 规则 custom-rules/no-top-level-side-effects。
启动优化是显式例外（加 // eslint-disable）。
6.3 "ESLint disable 必带理由"¶
每条 // eslint-disable-next-line 都解释了为什么。
6.4 "Ant-only 标记保持顺序"¶
// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
告诉 biome "别动这个顺序"。
6.5 "模块边界显式声明"¶
types/ 子目录专门用于"中央类型"，打破循环依赖。
7. 跨学科类比¶
7.1 Claude Code 像什么？¶
| 行业 | 类比 | 共同点 |
|---|---|---|
| 操作系统 | Linux kernel | 大型、深度、模块化、跨平台 |
| 数据库 | PostgreSQL | 自研 60 行核心（vs 3000 行生态） |
| 编辑器 | VSCode | 巨型 monorepo + 完整 IDE 集成 |
| 编译器 | GCC | Tree-sitter AST 解析、复杂的中间表示 |
| 浏览器 | Chrome | 多进程架构、严格隔离、复杂 IPC |
| 游戏引擎 | Unity | "一切皆组件"哲学 |
7.2 Claude Code 不像什么？¶
- ❌ 不像 npm 包（太大了）
- ❌ 不像 React app（更底层）
- ❌ 不像 Web 应用（更系统级）
7.3 设计哲学综合¶
8. 启示（对其他项目）¶
8.1 "标准 > 库"¶
React / TypeScript / Node 标准 API > 任何第三方库。
8.2 "够用就好"¶
不要追求"最强大的方案"。60 行能解决的就别用 3000 行。
8.3 "类型即文档"¶
TypeScript 联合类型 + 类型守卫 = 状态机的"自文档"。
8.4 "纵深防御"¶
安全不能用单层解决。至少 3-4 层。
8.5 "扩展是协议"¶
MCP / Plugin / Skill / Command / Tool = 5 层扩展。
协议比硬编码好。
8.6 "性能考古"¶
注释解释 why + 引用 PR。
未来维护者不需要考古。
8.7 "模块化要克制"¶
适度拆模块。
不要为了"看起来整洁"过度拆。
8.8 "TypeScript 是朋友"¶
类型系统 = 编译时正确性 + 文档 + IDE 支持。
不要写 any。
9. 关键洞察¶
9.1 "好的设计 = 反复出现的模式"¶
读了 50 万行，模式就 10 条。
好代码是"反复出现的简单模式"，差代码是"每个地方都独特的复杂逻辑"。
9.2 "限制 = 创造"¶
Claude Code 不用 npm = 必须内嵌 = 学会写"自包含代码"。
没有依赖反而更可控。
9.3 "代码是产品的一部分"¶
注释 / 类型 / 文件结构 / 命名 = 产品体验。
代码质量 = 用户体验。
9.4 "文档化是纪律"¶
每个 feature('X') 都说明含义。
每个 inlined X 都说"keep in sync"。
纪律 = 可维护性。
10. 推荐阅读顺序¶
如果你想学 Claude Code 的设计哲学： 1. ✅ 读 00-index.md 整体方案 2. ✅ 读 topics/async-generator-pattern.md 3. ✅ 读 topics/dce-feature-flags.md 4. ✅ 读 topics/coding-style-conventions.md 5. ✅ 读 topics/structured-diff-perf-archaeology.md 6. ✅ 读 topics/bash-security-model.md 7. ✅ 读 topics/native-napi-integration.md