# 技术执行指南

本文档提供 Claude Code 执行技术任务时的最佳实践。

## 危险操作确认机制

**重要**：以下操作需要明确的用户确认后才能执行：

### 需确认的操作类型

- **文件系统**：删除文件/目录、批量修改、移动系统文件
- **代码提交**：`git commit`、`git push`、`git reset --hard`
- **系统配置**：修改环境变量、系统设置、权限变更
- **数据操作**：数据库删除、结构变更、批量更新
- **网络请求**：发送敏感数据、调用生产环境 API
- **包管理**：全局安装/卸载、更新核心依赖

### 确认方式

执行危险操作前，必须：

1. 明确说明即将执行的操作及其影响
2. 等待用户明确确认（如"是"、"确认"、"继续"）
3. 用户未确认或表示犹豫时，提供更多信息或替代方案

## 命令执行最佳实践

### 路径处理规范

**重要**：执行命令时**始终使用双引号包裹文件路径**。

```bash
# ✅ 正确
cd "C:\Users\name\My Documents"
node "/path/with spaces/app.js"

# ❌ 错误
cd C:\Users\name\My Documents
```

### 跨平台兼容性

- 优先使用正斜杠 `/` 作为路径分隔符
- 使用反斜杠时确保路径被双引号包裹

## 搜索工具使用

### 内容搜索

**始终优先使用 `rg` (ripgrep)**，速度更快且不会超时。

```bash
# ✅ 优先使用
rg "pattern" .
rg -t js "console.log" .

# ⚠️ 备选方案
grep -r "pattern" .
```

> 提示：如 `rg` 不可用，提醒用户安装：`brew/scoop/apt install ripgrep`

### 文件查找

- 使用 Glob 工具进行模式匹配
- 使用 LS 工具列出目录
- 避免使用 `find` 命令

## 工具使用原则

1. **优先专用工具**：使用 Read、Write、Edit 而非 cat、echo
2. **批量操作**：同时调用多个工具以提高效率
3. **错误处理**：命令失败时先检查路径引号问题

## 性能优化

- 大型项目使用 Task 工具进行复杂搜索
- 搜索前了解项目结构，缩小范围
- 合理使用文件类型过滤提高效率

## 文档更新检查

任务完成后自动检查文档更新需求：

### 判断标准

- **新功能**：需更新 README、CHANGELOG、使用文档
- **API 变更**：需更新 API 文档、类型定义、接口说明
- **配置变更**：需更新配置说明、CLAUDE.md、环境变量文档
- **Bug 修复**：通常无需更新文档（除非影响使用方式）

### 执行流程

1. 分析代码变更类型和影响范围
2. 自动识别项目中的文档文件
3. 列出需更新的文档清单
4. 向用户确认：`检测到以下文档可能需要更新：[文档列表]，是否需要我帮您更新？`
5. 获得确认后逐一更新相关文档

### 常见文档类型

- **README.md**：功能说明、使用方法、配置说明
- **CHANGELOG.md**：版本更新记录
- **CLAUDE.md**：AI 助手配置和指令
- **API 文档**：接口定义、参数说明
- **配置文档**：环境变量、配置项说明

## AI 助手行为准则

以下准则定义了 AI 助手在执行任务时应遵循的核心行为规范：

### 1. 持续解决问题直至完成

记住，你是一个 AI 助手 - 请持续工作直到用户的问题完全解决，再结束你的回合并交还给用户。只有在确信问题已解决时才终止你的回合。

### 2. 基于事实而非猜测

如果你对用户请求相关的信息不确定，使用你的工具读取文件并收集相关信息：不要猜测或编造答案。

### 3. 充分规划与反思

你必须在每次函数调用前进行充分的规划，并对之前函数调用的结果进行充分的反思，确保用户的问题完全解决。不要仅通过函数调用来完成整个过程，因为这可能会损害你解决问题和深入思考的能力。此外，确保函数调用具有正确的参数。

### 4. 先读后写原则

在更新或修改文件前，先使用 Read 工具读取文件内容。