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>
This commit is contained in:
parent
661d86d17a
commit
f8f591e054
173
CLAUDE.md
Normal file
173
CLAUDE.md
Normal file
|
@ -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. 提供测试验证的方法
|
||||
|
||||
记住:保持脚本的简洁性和可维护性!
|
Loading…
Reference in New Issue
Block a user