philosophy

Claude Code 的设计哲学体现了 Anthropic 对 AI 编程助手的独特理解。

核心原则

1. 终端即 IDE

理念: 开发者的工作流应该保持连贯,而不是在多个工具间切换。

实践:

  • 所有功能都在终端中完成

  • 使用 React + Ink 构建富交互界面

  • 支持文件编辑、代码审查、测试运行等完整开发流程

影响:

  • 启动速度至关重要(< 1 秒)

  • UI 必须适应不同终端尺寸

  • 键盘交互优先

2. 安全第一的自主性

理念: AI 应该能够自主工作,但必须在安全边界内。

实践:

  • 三层权限模型:规则层、模式层、工具层

  • 2600+ 行 Bash 命令权限检查

  • 分类器辅助的智能审批

  • 用户可以随时中断和回滚

权限层级:

3. 上下文是稀缺资源

理念: Token 预算有限,必须激进地管理上下文。

实践:

  • 五层压缩策略

  • 动态内容裁剪

  • 缓存边界优化

  • 工具结果预算控制

压缩层级:

  1. Tool Result Budget - 限制单个工具结果大小

  2. Snip - 裁剪文件内容,保留相关部分

  3. Microcompact - 压缩工具调用历史

  4. Context Collapse - 折叠旧对话轮次

  5. Auto Compact - 自动触发压缩

4. 启动性能是产品体验

理念: 首次交互时间直接影响用户感知。

实践:

  • 多级 fast-path 优化

  • 延迟加载非关键模块

  • 并行预取配置和状态

  • 避免同步 I/O

优化效果:

  • 冷启动: < 1 秒

  • 热启动: < 300ms

  • 首次 AI 响应: < 2 秒

5. Feature Flag 驱动的渐进式发布

理念: 新功能应该可以安全地逐步推出。

实践:

  • 所有新功能都有 feature flag

  • 支持用户级和工作区级配置

  • 可以快速回滚问题功能

示例:

设计权衡

性能 vs 功能

Claude Code 在多个场景下优先选择性能:

  • 启动速度 > 功能完整性

    • 延迟加载 Skills 和 Plugins

    • 按需加载 MCP 服务器

  • 响应速度 > 完美准确性

    • 使用 fuzzy search 而非精确匹配

    • 投机性执行工具调用

自主性 vs 安全性

Claude Code 不追求完全自主,而是在安全边界内最大化自主性:

  • 允许: 读取文件、搜索代码、运行只读命令

  • 需要确认: 写入文件、运行危险命令、网络请求

  • 禁止: 删除系统文件、修改权限、执行恶意代码

灵活性 vs 复杂性

工具系统设计体现了这一权衡:

  • 简单工具: 单一职责,易于理解和使用

  • 复合工具: 通过组合简单工具实现复杂功能

  • 扩展机制: Skills、Plugins、MCP、Hooks 提供灵活性

架构原则

1. 单向数据流

  • 状态是唯一的真相来源

  • UI 是状态的纯函数

  • 避免双向绑定的复杂性

2. 组合优于继承

3. 类型安全

4. 错误处理优先

模块职责

Core (核心)

  • query.ts - Query Loop 实现

  • Tool.ts - 工具接口定义

  • Task.ts - Spec 任务系统

  • state/ - 状态管理

Services (服务)

  • compact/ - 上下文压缩

  • tools/ - 工具执行

  • permissions/ - 权限检查

  • mcp/ - MCP 集成

  • coordinator/ - Agent 协调

Tools (工具)

  • FileEditTool/ - 文件编辑

  • BashTool/ - Shell 执行

  • AgentTool/ - 子 Agent

  • ReadCodeTool/ - 代码阅读

  • 其他 25+ 工具

UI (用户界面)

  • components/ - React 组件

  • hooks/ - React Hooks

  • styles/ - 终端样式

Extensions (扩展)

  • skills/ - Skills 系统

  • plugins/ - Plugins 系统

  • hooks/ - Hooks 系统

依赖关系图

关键点:

  • 单向依赖,避免循环

  • Services 是共享层

  • Utils 是纯函数库

扩展点

Claude Code 提供了多个扩展点:

  1. 自定义工具 - 实现 Tool 接口

  2. Skills - Markdown 格式的上下文注入

  3. Plugins - TypeScript 插件

  4. MCP 服务器 - 外部工具集成

  5. Hooks - 事件驱动的自动化

下一步