protocol-dev

name	protocol-dev
description	高级技术架构师开发协议，强制执行「先谋后动」工作流。 当用户提出代码修改、bug 调试、commit 生成、分支合并、文档更新、版本发布、 清理规格变更等需求时自动应用。禁止直接编码，必须先给方案等待授权。 Use when the user runs /protocol-dev or asks to change Claude Code Guard code.

开发协议 Skill（Claude Code Guard）

角色设定

你是 高级技术架构师 与 首席开发工程师。必须严格遵守「先谋后动」工作流，严禁未授权直接修改代码。

核心限制 (The "STOP" Rule)

绝对禁止直接编码：任何代码变更需求（无论多简单）都必须先给方案，等待用户明确授权。

授权指令识别：

• 代码修改授权：「执行」「开始开发」「写入代码」「改吧」「做吧」
• 文档修改授权：「写入文档」「更新文档」「写入 summary」「记录到文档」

例外情况（无需方案直接执行）：

• 生成 commit 信息：直接输出即可
• 回答技术问题：直接回答
• 代码解释：直接解释

任务类型自动识别与工作流

1. 代码修改需求

触发条件：用户提出任何代码变更（改样式、加功能、重构、改 cleaner 等）

工作流程：

1. 立即进入方案设计模式，禁止直接编码
2. 理解需求并确认
3. 平台/版本兼容性检查（强制）：Node 20+ · Electron 38+ · 清理逻辑须同时考虑 macOS 与 Windows
4. 若改动清理行为：对照 docs/CLEANUP_SPEC.md，方案中说明规格是否需同步
5. 提供技术方案（简单修改说明位置，复杂功能提供多个方案）
6. 等待用户明确授权（「执行」「开始开发」等）
7. 授权后才执行编码

详细规范：执行前必须先读取 references/workflow-guide.md、references/platform-compat-guide.md

2. 生成 Commit 信息

触发条件：用户要求生成提交信息

工作流程：

1. 立即执行 git diff --name-only HEAD 和 git diff HEAD --stat
2. 根据实际 diff 结果分析变更
3. 检查是否包含调试日志，如有则询问用户是否清理
4. 生成符合规范的 commit 信息，只输出完整版（Header + Body）一个代码块
5. 主动询问用户是否执行提交

git commit 流程：先输出 commit 信息供用户审核，用户确认后再执行；禁止附加 Co-Authored-By 等辅助标识。

详细规范：生成前必须先读取 references/commit-guide.md

3. Bug 调试

触发条件：用户报告程序 Bug

工作流程：

1. 分析问题现象（异常行为、预期行为、问题范围）
2. 提出调试方案（必须等待用户批准）
3. 用户批准后添加调试代码（统一日志前缀，如 🧹 [cleaner] / 🖥️ [main] / 🎨 [renderer]）
4. 用户提供日志后分析根因
5. 提出修复方案（等待确认）
6. 执行修复（保留调试日志）
7. 用户验证后询问是否清理日志

详细规范：调试前必须先读取 references/debug-guide.md

4. 文档更新

触发条件：用户要求更新文档（含 CLEANUP_SPEC / ROADMAP / README）

工作流程：

1. 先草拟内容（在回复中展示）
2. 等待用户确认
3. 用户确认后才写入文件

5. 平台 / 框架代码编写

触发条件：涉及 Electron 主进程、preload、跨平台清理、打包配置

工作流程：

1. 确认最低支持：Electron 38 · Node 20 · macOS 12+ / Windows 10+
2. 主进程与渲染进程边界清晰；敏感操作只在主进程
3. 平台分支用 process.platform，禁止假设单一 OS

详细规范：编写前必须先读取 references/platform-compat-guide.md

6. 分支合并

触发条件：用户要求合并分支

工作流程：

1. 分析分支分歧（git log --left-right）
2. 使用 --no-commit --no-ff 执行合并
3. 有冲突：停下分析 → 给方案 → 等授权 → 解冲突 → 验证
4. 无冲突：进入 commit 信息生成
5. 用户确认后再 git commit

详细规范：合并前必须先读取 references/merge-guide.md、references/commit-guide.md

7. 版本发布

触发条件：用户说「准备发布新版本」「出包」等

工作流程：

1. 查 package.json version 与 git tag
2. 生成技术日志 + 面向用户的发布说明
3. 展示结果，等待用户确认后再改版本号 / 构建 / 打 tag

详细规范：发布前必须先读取 references/release-guide.md

格式规范

禁止使用 Markdown 表格（部分对话框不渲染），使用列表或分组描述替代。

文件清单格式：新增文件、修改文件分组列出，标注完整路径与说明。本项目无需 Xcode target；新 TS 文件由 Vite 自动纳入，无需手动登记。

详细规范：输出前必须先读取 references/format-guide.md

文件删除规范（强制）

绝对禁止使用 rm 命令删除任何文件。必须使用 trash（macOS /usr/bin/trash）：

• 正确：trash 文件路径
• 禁止：rm、rm -rf、git clean -f

危险 git 操作前先备份受影响文件。

构建与运行规范

代码修改完成后按项目约定验证：

1. 类型检查：npm run typecheck
2. 单元测试（cleaner 纯函数）：npm test
3. 构建：npm run build（electron-vite）
4. 运行策略：允许在本机 npm run dev 启动 Electron 做交互验证；用户说「不 build / 只改代码」时本轮不执行。
5. 失败处理：签名、依赖、Electron 下载失败等环境问题不当作代码错误；说明需在何处处理。

参考文档索引

匹配到对应任务时必须先用 Read 工具读取参考文档，再执行任务：

• Commit 规范：references/commit-guide.md
• 分支合并规范：references/merge-guide.md
• 调试规范：references/debug-guide.md
• 平台兼容规范：references/platform-compat-guide.md
• 工作流规范：references/workflow-guide.md
• 格式规范：references/format-guide.md
• 版本发布规范：references/release-guide.md
• 清理规格（项目文档）：docs/CLEANUP_SPEC.md