openclaw-cc-rules

# CC Rules - 编程工作流规范 > 借鉴业界顶级 AI 编程工具的工作流模式，为 OpenClaw 注入结构化的软件开发行为规范。 ## 激活条件 当用户涉及以下场景时自动激活本 Skill： - 编写、修改、重构代码 - 项目架构分析和设计 - Git 操作（commit、branch、merge） - 调试和排查 Bug - 代码审查（review） - 项目初始化和配置 ## 核心规则 ### 一、Plan Mode — 先想后做 面对非平凡的编码任务，必须遵循 **探索 → 理解 → 规划 → 确认** 四步流程。 #### 什么时候必须进入 Plan Mode - 添加新功能（不只是修个 typo） - 存在多种实现方案需要选择 - 修改会影响 3 个以上文件 - 需要做架构决策（选什么框架、用什么模式） - 用户需求不够清晰需要先搞明白 - 重构或大规模改动 #### 什么时候可以跳过 Plan Mode - 用户给了非常具体的指令，照做就行 - 只改一两行的小修复 - 纯粹的研究/探索任务 - 用户明确说"直接做"或"不用规划" #### Plan Mode 流程 ``` 1. 只读探索 - 用 Glob/Grep 定位相关文件 - 用 Read 阅读关键代码 - 用 exec 跑 git log/diff/status 了解现状 - ⚠️ 此阶段禁止修改任何文件 2. 理解架构 - 找到类似功能作为参考 - 梳理代码依赖关系 - 识别项目的编码规范和约定 3. 输出方案 - 分步骤描述实现计划 - 标明需要修改哪些文件 - 说明选择某种方案的理由 - 预判可能的风险和挑战 4. 等待确认 - 方案需要用户批准后才动手 - 用户可以要求修改方案 - 用户可以说"直接开始"跳过确认 ``` #### Plan Mode 输出格式 ``` ## 实现方案：[任务名称] ### 背景 简述现状和要解决的问题 ### 方案概述 一句话说清楚怎么做 ### 实施步骤 1. 修改 `path/to/file1.ts` — 做什么，为什么 2. 修改 `path/to/file2.ts` — 做什么，为什么 3. 新建 `path/to/file3.ts` — 做什么，为什么 4. 运行测试验证 ### 关键文件 - `path/to/file1.ts` — 核心逻辑 - `path/to/file2.ts` — 配置入口 ### 风险点 - 某处改动可能影响 XX 功能 ``` --- ### 二、任务追踪 — 做到哪了心里有数 复杂任务（3 步以上）必须创建任务清单。 #### 状态规则 | 状态 | 含义 | 规则 | |------|------|------| | ⏳ 待办 (pending) | 还没开始 | 按优先级排列 | | 🔄 进行中 (in_progress) | 正在做 | **同一时间只能有一个** | | ✅ 完成 (completed) | 做完了 | 完成后立刻标记，不要攒着 | | ❌ 阻塞 (blocked) | 卡住了 | 写清楚卡在什么，怎么解决 | #### 使用规则 - 开始工作前标记为 in_progress - 完成后**立即**标记 completed，不要等做完一批再标 - 遇到阻塞不要硬做，标记 blocked + 新建一个解阻塞任务 - 如果过程中发现新任务，追加到清单里 - 不相关的任务从清单中移除 #### 任务描述格式 每个任务需要两个形式： - **content**: 命令式描述（"修复登录验证逻辑"） - **activeForm**: 进行时描述（"正在修复登录验证逻辑"） --- ### 三、只读探索模式 — 搞懂再动手 当需要理解代码但不需要修改时，进入只读探索模式。 #### 允许的操作 - `read` — 阅读文件内容 - `exec` 中的只读命令：`ls`、`cat`、`head`、`tail`、`find`、`grep` - `exec` 中的 git 只读命令：`status`、`diff`、`log`、`show`、`blame` #### 禁止的操作 - `write` — 创建文件 - `edit` — 修改文件 - `exec` 中的写入命令：`mkdir`、`touch`、`rm`、`cp`、`mv`、`git add`、`git commit` - 重定向写入：`>`、`>>`、`tee` - 安装依赖：`npm install`、`pip install` 等 #### 探索输出 探索完成后总结： - 项目结构概述 - 相关文件列表和各自职责 - 代码调用链路 - 发现的问题或改进建议 --- ### 四、Git 安全协议 — 不作死 #### 绝对禁止（除非用户明确要求） - `git push --force` / `git push -f` - `git reset --hard` - `git checkout .` / `git restore .` - `git clean -f` / `git clean -fd` - `git branch -D` - `git rebase -i`（需要交互式输入） - `--no-verify` / `--no-gpg-sign`（跳过 hooks） - `git commit --amend`（除非用户明确说修改上一次 commit） #### Commit 流程 ``` 1. 并行执行： - git status （查看变更文件） - git diff （查看具体改动） - git log --oneline -10 （了解项目 commit 风格） 2. 分析变更： - 概括改动性质（新功能 / 增强 / 修复 / 重构 / 测试 / 文档） - 排除含敏感信息的文件（.env、credentials.json 等） - 写 1-2 句 commit message，聚焦"为什么改"而不是"改了什么" 3. 执行提交： - 用 git add 按文件名逐个添加（不用 git add -A） - commit message 用 HEREDOC 格式传递 - 提交后 git status 验证 4. 如果 pre-commit hook 失败： - 修复问题 → 重新 stage → 创建新 commit - 不要用 --amend（会覆盖之前的 commit） ``` #### Commit Message 规范 ``` 类型: 简短描述（1行，不超过72字符） - 新功能: feat: 添加用户注册接口 - Bug修复: fix: 修复登录超时未重试的问题 - 重构: refactor: 拆分订单服务为独立模块 - 文档: docs: 更新 API 接口文档 - 测试: test: 补充用户模块单元测试 - 配置: chore: 升级依赖版本 ``` #### 不要提交的文件 - `.env`、`.env.local`、含密钥的配置文件 - `node_modules/`、`__pycache__/`、`venv/` - IDE 配置（`.idea/`、`.vscode/` 除非是团队共享的） - 大型二进制文件（用 .gitignore 排除） --- ### 五、多文件变更策略 — 有序不乱 当一个任务涉及多个文件时： 1. **先改被依赖的**（底层模块、类型定义、工具函数） 2. **再改依赖方**（上层业务逻辑、UI 组件） 3. **最后改配置和入口** 4. 每改完一个逻辑单元就验证一次，不要攒到最后 --- ### 六、代码写完之后 — 善后 完成编码后： 1. 检查是否需要更新相关文档 2. 检查是否有遗漏的 TODO 3. 如果改了接口/类型，检查调用方是否需要同步修改 4. 跑一遍测试（如果项目有的话） 5. 检查 lint / format 是否通过