Add CLAUDE.md: comprehensive development guide

- Detailed instructions for updating scripts when adding apps
- Clear workflow for Homebrew application management
- Testing guidelines and best practices
- Commit message format standards
- Error handling and compatibility notes
- Step-by-step guide for common tasks

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

2025-06-28 11:34:16 +10:00

3.9 KiB

Raw Blame History

Claude Code 工作指南

这是一个 macOS 自动化设置脚本项目，包含应用安装、开发环境配置等功能。

项目结构

install.sh - 主安装脚本，包含所有功能
README.md - 用户使用文档
CLAUDE.md - 本文件，Claude 的工作指南

重要提醒

🚨 添加新应用时必须同步更新

当通过 Homebrew 安装新应用时，必须同时更新 install.sh 脚本：

查找应用列表位置：在 install.sh 中找到 apps=() 数组（约在第 105 行）
添加新应用：按格式添加到数组中
```
"app-name"              # 应用描述
```
测试安装：确保新应用可以通过 brew install --cask app-name 正常安装

提交更改：

git -C ~/.mac-setup add install.sh
git -C ~/.mac-setup commit -m "Add new app: app-name"
git -C ~/.mac-setup push

📝 应用列表格式

apps=(
    "existing-app"        # 现有应用 - 描述
    "new-app"            # 新应用 - 描述
    "another-app"        # 另一个应用 - 描述
)

🔍 验证步骤

添加新应用后请验证：

Homebrew 包名正确：

brew search app-name
brew info --cask app-name

脚本语法正确：
```
bash -n ~/.mac-setup/install.sh
```

安装测试：

# 测试单个应用安装
brew install --cask app-name
brew uninstall --cask app-name

常见任务

添加命令行工具

如果要添加命令行工具（不是 cask 应用），请在 install_cli_tools() 函数中添加：

# 在 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

添加配置步骤

如果需要添加新的配置步骤，可以：

创建新的函数
在相应的安装流程中调用
确保在 full_install() 函数中包含

修改别名配置

在 setup_aliases() 函数中添加新的别名：

# 在 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 -n ~/.mac-setup/install.sh

# 运行特定选项
bash ~/.mac-setup/install.sh
# 选择相应的测试选项

# 完整安装测试（谨慎使用）
bash ~/.mac-setup/install.sh --full

远程测试

# 测试一键安装命令
bash -c "$(curl -fsSL https://git.nas.astrian.moe/Astrian/mac-setup/raw/branch/main/install.sh)"

注意事项

权限敏感：脚本涉及 sudo 权限，修改时要小心
网络依赖：所有安装都依赖网络，确保 URL 正确
兼容性：考虑 Apple Silicon 和 Intel Mac 的兼容性
错误处理：添加适当的错误检查和用户提示
幂等性：确保脚本可以重复运行而不出错

帮助用户

当用户询问如何添加应用时：

首先帮助查找正确的 Homebrew 包名
确认是 cask 应用还是命令行工具
在正确位置添加到脚本
提交更改到 Git
提供测试验证的方法

记住：保持脚本的简洁性和可维护性！

3.9 KiB Raw Blame History Unescape Escape