zcf

# 技术执行指南本文档提供 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 工具读取文件内容。