diff --git a/docs/internals/feature-flags.mdx b/docs/internals/feature-flags.mdx
index 1ef05b61a..818b82c71 100644
--- a/docs/internals/feature-flags.mdx
+++ b/docs/internals/feature-flags.mdx
@@ -1,36 +1,28 @@
 ---
-title: "88 个 Feature Flags - 构建时特性门控全解"
-description: "深入剖析 Claude Code 的 88+ 个构建时 feature flags：bun:bundle 编译时门控机制，揭示被编译器删除的隐藏功能模块。"
-keywords: ["feature flags", "特性标志", "构建时门控", "bun:bundle", "条件编译"]
+title: "Feature Flags"
+description: "88+ 个构建时特性门控：理解 feature() 的编译时求值机制、死代码消除和 flags 的分类全景。"
+keywords: ["feature flags", "特性标志", "构建时门控", "条件编译"]
 ---
 
-{/* 本章目标：完整梳理构建时 feature flag 系统的机制和所有 flag 的分类 */}
+## 核心机制
 
-## feature() 是什么
+Claude Code 使用 Bun 打包器的编译时特性门控。代码中通过 `import { feature } from 'bun:bundle'` 导入 `feature()` 函数，在构建时被求值——返回 `true` 的代码保留，返回 `false` 的代码被**死代码消除（DCE）**彻底移除。
 
-Claude Code 使用 Bun 打包器的 `bun:bundle` 模块提供编译时特性门控：
+**设计洞察**：这不是运行时的 if-else——feature flag 在构建时就已经决定了哪些代码存在。外部构建中不存在的功能不是"被禁用"，而是"从未编译进去"。这是一种零运行时开销的特性门控。
 
-```typescript
-// 源码中的用法（src/tools.ts 等）
-import { feature } from 'bun:bundle'
+## 三种使用模式
 
-const SleepTool = feature('PROACTIVE') || feature('KAIROS')
-  ? require('@claude-code-best/builtin-tools/tools/SleepTool/SleepTool.js').SleepTool
-  : null
-```
+### 1. 条件加载工具
 
-在 Anthropic 的内部构建中，`feature()` 在打包时被求值——返回 `true` 的代码会被保留，返回 `false` 的代码会被 **Dead Code Elimination (DCE)** 彻底移除。
+当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。不增加打包体积。
 
-在我们的反编译版本中，`feature` 从 `bun:bundle` 导入（声明在 `src/types/internal-modules.d.ts`），在运行时始终返回 `false`：
+### 2. 条件注册命令
 
-```typescript
-// src/types/internal-modules.d.ts
-declare module 'bun:bundle' {
-  export function feature(name: string): boolean;
-}
-```
+斜杠命令只在对应 flag 启用时注册。用户不会看到不可用的命令。
 
-这意味着所有 88+ 个 feature flag 后的代码**在运行时永远不会执行**，但代码本身完整保留，可以阅读和分析。
+### 3. 条件启用 API 特性
+
+控制发送给 API 的 beta header。未启用的功能不会向服务端声明能力。
 
 ## Flags 分类全景
 
@@ -72,46 +64,14 @@ declare module 'bun:bundle' {
   </Card>
 </CardGroup>
 
-## 代码中的典型模式
-
-Feature flags 在代码中主要有三种使用模式：
-
-### 模式一：条件加载工具
-
-```typescript
-// src/tools.ts — 最常见的模式
-const MonitorTool = feature('MONITOR_TOOL')
-  ? require('@claude-code-best/builtin-tools/tools/MonitorTool/MonitorTool.js').MonitorTool
-  : null
-```
-
-当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。
-
-### 模式二：条件注册命令
-
-```typescript
-// src/commands.ts — 注册斜杠命令
-if (feature('VOICE_MODE')) {
-  commands.push({ name: 'voice', description: '...' })
-}
-```
-
-### 模式三：条件启用 API 特性
-
-```typescript
-// src/constants/betas.ts — 控制发送给 API 的 beta header
-export const AFK_MODE_BETA_HEADER = feature('TRANSCRIPT_CLASSIFIER')
-  ? 'afk-mode-2026-01-31'
-  : ''
-```
-
-<Note>
-由于 `feature()` 在构建时求值，被 DCE 移除的代码不会增加最终打包体积。但在反编译版本中，这些代码全部保留——这正是我们能够进行完整分析的原因。
-</Note>
-
 ## 有趣的发现
 
 - **KAIROS 家族**最庞大——6 个相关 flag 控制从核心功能到推送通知的方方面面
-- **ABLATION_BASELINE** 是用于"科学对照实验"的——它会关闭 thinking、compaction、auto-memory 等高级功能，测量裸 API 调用的基线性能
-- **BUDDY** 是一个 AI 吉祥物/精灵系统——在 `src/buddy/` 目录下有完整实现
+- **ABLATION_BASELINE** 是用于"科学对照实验"的——关闭 thinking、compaction、auto-memory 等高级功能，测量裸 API 调用的基线性能
+- **BUDDY** 是一个 AI 吉祥物/精灵系统
 - **ULTRAPLAN** 和 **ULTRATHINK** 暗示着比当前 extended thinking 更高级的推理模式
+
+## 接下来
+
+- **Ant 特权世界** — 理解 USER_TYPE 门控与 feature flags 的关系
+- **Auto Mode** — 理解 TRANSCRIPT_CLASSIFIER flag 控制的自动权限分类