diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..82fe00b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,173 @@
+# Claude Code 工作指南
+
+这是一个 macOS 自动化设置脚本项目，包含应用安装、开发环境配置等功能。
+
+## 项目结构
+
+- `install.sh` - 主安装脚本，包含所有功能
+- `README.md` - 用户使用文档
+- `CLAUDE.md` - 本文件，Claude 的工作指南
+
+## 重要提醒
+
+### 🚨 添加新应用时必须同步更新
+
+当通过 Homebrew 安装新应用时，**必须同时更新 `install.sh` 脚本**：
+
+1. **查找应用列表位置**：在 `install.sh` 中找到 `apps=()` 数组（约在第 105 行）
+
+2. **添加新应用**：按格式添加到数组中
+   ```bash
+   "app-name"              # 应用描述
+   ```
+
+3. **测试安装**：确保新应用可以通过 `brew install --cask app-name` 正常安装
+
+4. **提交更改**：
+   ```bash
+   git -C ~/.mac-setup add install.sh
+   git -C ~/.mac-setup commit -m "Add new app: app-name"
+   git -C ~/.mac-setup push
+   ```
+
+### 📝 应用列表格式
+
+```bash
+apps=(
+    "existing-app"        # 现有应用 - 描述
+    "new-app"            # 新应用 - 描述
+    "another-app"        # 另一个应用 - 描述
+)
+```
+
+### 🔍 验证步骤
+
+添加新应用后请验证：
+
+1. **Homebrew 包名正确**：
+   ```bash
+   brew search app-name
+   brew info --cask app-name
+   ```
+
+2. **脚本语法正确**：
+   ```bash
+   bash -n ~/.mac-setup/install.sh
+   ```
+
+3. **安装测试**：
+   ```bash
+   # 测试单个应用安装
+   brew install --cask app-name
+   brew uninstall --cask app-name
+   ```
+
+## 常见任务
+
+### 添加命令行工具
+
+如果要添加命令行工具（不是 cask 应用），请在 `install_cli_tools()` 函数中添加：
+
+```bash
+# 在 install_cli_tools() 函数中添加
+if command -v tool-name &> /dev/null; then
+    print_message "✅ Tool Name 已安装" "$GREEN"
+else
+    brew install tool-name
+    print_message "✅ Tool Name 安装成功！" "$GREEN"
+fi
+```
+
+### 添加配置步骤
+
+如果需要添加新的配置步骤，可以：
+
+1. 创建新的函数
+2. 在相应的安装流程中调用
+3. 确保在 `full_install()` 函数中包含
+
+### 修改别名配置
+
+在 `setup_aliases()` 函数中添加新的别名：
+
+```bash
+# 在 setup_aliases() 函数中添加
+if ! grep -q 'alias newcmd=' "$HOME/.zshrc" 2>/dev/null; then
+    echo '# New command alias' >> "$HOME/.zshrc"
+    echo 'alias newcmd="actual-command"' >> "$HOME/.zshrc"
+fi
+```
+
+## 文件更新协议
+
+### 必须更新的情况
+
+- ✅ 添加新的 Homebrew 应用
+- ✅ 移除不再需要的应用
+- ✅ 修改安装逻辑
+- ✅ 添加新的配置步骤
+- ✅ 修复 bug
+
+### 提交消息格式
+
+```
+类型: 简短描述
+
+详细说明
+- 具体变更1
+- 具体变更2
+
+🤖 Generated with Claude Code
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+类型：
+- `Add:` 添加新功能或应用
+- `Fix:` 修复问题
+- `Update:` 更新现有功能
+- `Remove:` 移除功能或应用
+- `Refactor:` 重构代码
+
+## 测试指南
+
+### 本地测试
+
+```bash
+# 语法检查
+bash -n ~/.mac-setup/install.sh
+
+# 运行特定选项
+bash ~/.mac-setup/install.sh
+# 选择相应的测试选项
+
+# 完整安装测试（谨慎使用）
+bash ~/.mac-setup/install.sh --full
+```
+
+### 远程测试
+
+```bash
+# 测试一键安装命令
+bash -c "$(curl -fsSL https://git.nas.astrian.moe/Astrian/mac-setup/raw/branch/main/install.sh)"
+```
+
+## 注意事项
+
+1. **权限敏感**：脚本涉及 sudo 权限，修改时要小心
+2. **网络依赖**：所有安装都依赖网络，确保 URL 正确
+3. **兼容性**：考虑 Apple Silicon 和 Intel Mac 的兼容性
+4. **错误处理**：添加适当的错误检查和用户提示
+5. **幂等性**：确保脚本可以重复运行而不出错
+
+## 帮助用户
+
+当用户询问如何添加应用时：
+
+1. 首先帮助查找正确的 Homebrew 包名
+2. 确认是 cask 应用还是命令行工具
+3. 在正确位置添加到脚本
+4. 提交更改到 Git
+5. 提供测试验证的方法
+
+记住：保持脚本的简洁性和可维护性！
\ No newline at end of file