7418andClaude Opus 4.6
16b0006f98
Add safety rules for git worktree workflows: - Changes scoped to worktree only - No cross-worktree commits or push - Port isolation for dev server - No cross-directory file edits - Check untracked files before merge Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
87 lines
4.8 KiB
Markdown
87 lines
4.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
CodePilot — Claude Code 的桌面 GUI 客户端，基于 Electron + Next.js。
|
||
|
||
> 架构细节见 [ARCHITECTURE.md](./ARCHITECTURE.md)，本文件只包含规则和流程。
|
||
|
||
## 开发规则
|
||
|
||
**提交前必须详尽测试：**
|
||
- 每次提交代码前，必须在开发环境中充分测试所有改动的功能，确认无回归
|
||
- 涉及前端 UI 的改动需要实际启动应用验证（`npm run dev` 或 `npm run electron:dev`）
|
||
- 涉及构建/打包的改动需要完整执行一次打包流程验证产物可用
|
||
- 涉及多平台的改动需要考虑各平台的差异性
|
||
|
||
**UI 改动必须用 CDP 验证（chrome-devtools MCP）：**
|
||
- 修改组件、样式、布局后，必须通过 chrome-devtools MCP 实际验证效果
|
||
- 验证流程：`npm run dev` 启动应用 → 用 CDP 打开 `http://localhost:3000` 对应页面 → 截图确认渲染正确 → 检查 console 无报错
|
||
- 涉及交互的改动（按钮、表单、导航）需通过 CDP 模拟点击/输入并截图验证
|
||
- 修改响应式布局时，用 CDP 的 device emulation 分别验证桌面和移动端视口
|
||
|
||
**新增功能前必须详尽调研：**
|
||
- 新增功能前必须充分调研相关技术方案、API 兼容性、社区最佳实践
|
||
- 涉及 Electron API 需确认目标版本支持情况
|
||
- 涉及第三方库需确认与现有依赖的兼容性
|
||
- 涉及 Claude Code SDK 需确认 SDK 实际支持的功能和调用方式
|
||
- 对不确定的技术点先做 POC 验证，不要直接在主代码中试错
|
||
|
||
**Worktree 隔离规则：**
|
||
- 如果任务设置了 Worktree，所有代码改动只能在该 Worktree 内进行
|
||
- 严格禁止跨 Worktree 提交（不得在主目录提交 Worktree 的改动，反之亦然）
|
||
- 严格禁止 `git push`，除非用户主动提出
|
||
- 启动测试服务（`npm run dev` 等）只从当前 Worktree 启动，不得在其他目录启动
|
||
- 合并回主分支必须由用户主动发起，不得自动合并
|
||
- **端口隔离**：Worktree 启动 dev server 时使用非默认端口（如 `PORT=3001`），避免与主目录冲突
|
||
- **禁止跨目录编辑**：属于 Worktree 任务范围的文件，只在该 Worktree 内编辑，不得在主目录修改
|
||
- **合并前检查 untracked 文件**：合并回主分支前先 `git status` 确认无调试残留、临时文件等
|
||
|
||
**Commit 信息规范：**
|
||
- 标题行使用 conventional commits 格式（feat/fix/refactor/chore 等）
|
||
- body 中按文件或功能分组，说明改了什么、为什么改、影响范围
|
||
- 修复 bug 需说明根因；架构决策需简要说明理由
|
||
|
||
## 自检命令
|
||
|
||
**自检命令（pre-commit hook 会自动执行前三项）：**
|
||
- `npm run test` — typecheck + 单元测试（~4s，无需 dev server）
|
||
- `npm run test:smoke` — 冒烟测试（~15s，需要 dev server）
|
||
- `npm run test:e2e` — 完整 E2E（~60s+，需要 dev server）
|
||
|
||
修改代码后，commit 前至少确保 `npm run test` 通过。
|
||
涉及 UI 改动时额外运行 `npm run test:smoke`。
|
||
|
||
## 改动自查
|
||
|
||
完成代码修改后，在提交前确认：
|
||
1. 改动是否涉及 i18n — 是否需要同步 `src/i18n/en.ts` 和 `zh.ts`
|
||
2. 改动是否涉及数据库 — 是否需要在 `src/lib/db.ts` 更新 schema 迁移
|
||
3. 改动是否涉及类型 — 是否需要更新 `src/types/index.ts`
|
||
4. 改动是否涉及已有文档 — 是否需要更新 `docs/handover/` 中的交接文档
|
||
|
||
## 发版
|
||
|
||
**发版流程：** 更新 package.json version → `npm install` 同步 lock → 提交推送 → `git tag v{版本号} && git push origin v{版本号}` → CI 自动构建发布。不要手动创建 GitHub Release。
|
||
|
||
**发版纪律：** 禁止自动发版。`git push` + `git tag` 必须等用户明确指示后才执行。commit 可以正常进行。
|
||
|
||
**Release Notes 格式：** 标题 `CodePilot v{版本号}`，正文包含：更新内容、Downloads、Installation、Requirements、Changelog。
|
||
|
||
**构建：** macOS 产出 DMG（arm64 + x64），Windows 产出 NSIS 安装包。`scripts/after-pack.js` 重编译 better-sqlite3 为 Electron ABI。构建前清理 `rm -rf release/ .next/`。
|
||
|
||
## 执行计划
|
||
|
||
**中大型功能（跨 3+ 模块、涉及 schema 变更、需分阶段交付）必须先写执行计划再开工。**
|
||
- 活跃计划放 `docs/exec-plans/active/`，完成后移至 `completed/`
|
||
- 纯调研/可行性分析放 `docs/research/`
|
||
- 发现技术债务时记录到 `docs/exec-plans/tech-debt-tracker.md`
|
||
- 模板和规范见 `docs/exec-plans/README.md`
|
||
|
||
## 文档
|
||
|
||
- [ARCHITECTURE.md](./ARCHITECTURE.md) — 项目架构、目录结构、数据流、新功能触及点
|
||
- `docs/exec-plans/` — 执行计划（进度状态 + 决策日志 + 技术债务）
|
||
- `docs/handover/` — 交接文档（架构、数据流、设计决策）
|
||
- `docs/research/` — 调研文档（技术方案、可行性分析）
|
||
|
||
**检索前先读对应目录的 README.md；增删文件后更新索引。**
|