## 变更内容

- 变更 1
- 变更 2

## 代码库理解（Feature）

- 已有的 helper/util：xxx
- 影响的功能：xxx
- 最小修改范围：xxx

## Bug 根因分析（Fix）

- Bug 表现：xxx
- 触发条件：xxx
- 根因位置：xxx
- 修复方案：xxx

## 测试

- [ ] 单元测试通过
- [ ] 类型检查通过
- [ ] Lint 通过
- [ ] Code Review 通过

## 相关 Issue

Closes #{issue-number}

Git 工作流技能

安全的 Git 开发流程，通过子代理执行。

---

⚠️ 核心规则（不可违反）

┌─────────────────────────────────────────────────────────┐
│ ❌ 禁止直接推送到 main 分支 │
│ ❌ 禁止跳过 PR 流程 │
│ ❌ 禁止在未理解代码库的情况下开发新功能 │
│ ❌ 禁止在未找到 Bug 根因的情况下修复 Bug │
│ │
│ ✅ 必须从 develop 创建新分支 │
│ ✅ 必须通过 PR 合并到 develop │
│ ✅ 必须使用 code-review 技能审查代码 │
└─────────────────────────────────────────────────────────┘

安全提示： 本技能应在项目根目录（git 仓库）下执行，当前工作目录会被限制在项目目录内。

---

🔍 触发判断（重要！）

执行任何代码修改前，先评估是否触发此技能：

┌─────────────────────────────────────────────────────────┐
│ 步骤 1：用户是否使用了触发词？ │
│ - 开发、实现、新功能、修复、提交 PR │
│ │
│ 步骤 2：评估复杂度 │
│ - 预估工作量 > 30 分钟？ │
│ - 涉及 > 3 个文件？ │
│ │
│ 判断： │
│ ✅ 触发词 + (高复杂度 OR 多文件) → 使用此技能 │
│ ❌ 无触发词 或 简单修改 → 直接执行 │
└─────────────────────────────────────────────────────────┘

简单修改示例（不触发）：

• - 修复正则表达式（1 个文件，5 分钟）
• 修改配置文件（1 个文件，2 分钟）
• 文档拼写错误修复（1 个文件，1 分钟）

复杂修改示例（触发）：

• - 新增功能模块（3 个以上文件，1 小时以上）
• 重构架构（5 个以上文件，2 小时以上）
• 复杂 Bug 修复（需要调试定位，30 分钟以上）

---

执行方式

⚠️ 所有开发任务必须通过子代理执行：

javascript
sessions_spawn({
runtime: subagent,
mode: run,
task: {任务描述}
});

模型配置（可选）：

• - 默认使用系统配置的模型
• 如需指定模型，可在任务描述中说明，例如：使用思考模式审查代码

---

完整流程

阶段 1：任务分析

1. 1. 确定任务类型（功能 / 修复 / 文档 / 重构）
2. 生成分支名称（feature/xxx, fix/xxx）
3. 确认目标分支 = develop（永远是 develop！）

阶段 2：代码库理解（功能开发必须执行）

⚠️ 对于新功能，必须先充分理解当前代码库：

┌─────────────────────────────────────────────────────────┐
│ 检查清单： │
│ │
│ □ 是否已有类似的辅助/工具方法？ │
│ □ 会影响哪些现有功能？ │
│ □ 需要修改哪些文件？ │
│ □ 哪些代码是不必要修改的？ │
│ │
│ 避免： │
│ ❌ 重复实现辅助/工具方法 │
│ ❌ 影响当前功能 │
│ ❌ 修改不必要的代码 │
└─────────────────────────────────────────────────────────┘

执行步骤：

1. 1. 搜索相关代码文件（grep, find）
2. 阅读相关模块的实现
3. 识别可复用的辅助/工具方法
4. 确定最小修改范围

阶段 3：Bug 根因调研（修复必须执行）

⚠️ 对于 Bug 修复，必须完全充分调研找到 Bug 的产生原因：

┌─────────────────────────────────────────────────────────┐
│ 调研清单： │
│ │
│ □ Bug 的具体表现是什么？ │
│ □ Bug 在什么条件下触发？ │
│ □ Bug 的根因在哪里？（代码位置） │
│ □ 修复方案是什么？是否会影响其他功能？ │
│ │
│ 禁止： │
│ ❌ 在未找到根因的情况下修复 │
│ ❌ 只修复表面症状而不修复根因 │
└─────────────────────────────────────────────────────────┘

执行步骤：

1. 1. 复现 Bug（如果能）
2. 定位 Bug 代码位置
3. 分析根因
4. 设计修复方案
5. 评估影响范围

阶段 4：分支创建

bash

1. 确保 develop 是最新的

git checkout develop
git pull origin develop

2. 创建新分支（规范命名）

git checkout -b {类型}/{名称}

示例

feature/identity-persistence

fix/cors-validation

docs/api-reference

阶段 5：开发实施

必须包含：

• - ✅ 代码实现（最小修改范围）
• ✅ 单元测试
• ✅ 文档更新（API、README、CHANGELOG）
• ✅ 类型检查通过
• ✅ 代码规范检查通过

注意业务边界：

• - 只修改必要的代码
• 不影响无关功能
• 测试覆盖新逻辑和边界情况

阶段 6：代码审查（必须执行）

⚠️ 实现完成后，必须使用 code-review 技能进行自动审查：

javascript
// 触发 code-review 技能
sessions_spawn({
runtime: subagent,
mode: run,
task: 使用 code-review 技能审查当前变更：
- 分支: {分支名称}
- 对比: develop...HEAD
});

审查循环：

1. 1. 运行 code-review
2. 修复发现的问题
3. 再次审查，直到无新问题

阶段 7：提交 PR

审查通过后提交 PR 到 develop：

bash

推送分支

git push origin {分支名称}

创建 PR

gh pr create --base develop --head {分支名称} \ --title {类型}: {简短描述} \ --body {PR 描述}

PR 描述模板：
markdown

变更内容

• - 变更 1
• 变更 2

代码库理解（功能开发）

• - 已有的辅助/工具方法：xxx
• 影响的功能：xxx
• 最小修改范围：xxx

Bug 根因分析（修复）

• - Bug 表现：xxx
• 触发条件：xxx
• 根因位置：xxx
• 修复方案：xxx

测试

• - [ ] 单元测试通过
• [ ] 类型检查通过
• [ ] 代码规范检查通过
• [ ] 代码审查通过

相关 Issue

Closes #{问题编号}

---

流程结束

提交 PR 后流程结束。

后续由用户决定：

• - 手动审查 PR
• 让其他代理审查 PR
• 合并 PR

---

分支命名规范

类型	格式	示例
功能开发	feature/{名称}	feature/identity-persistence
修复

fix/{名称} | fix/cors-validation |
| 文档 | docs/{名称} | docs/api-reference |
| 重构 | refactor/{名称} | refactor/message-queue |

命名规则：

• - 使用短横线命名法（小写 + 连字符）
• 简短但描述性强

---

提交信息规范

遵循 约定式提交：

{类型}({范围}): {描述}

[可选正文]

[可选页脚]

类型：

类型	用途
feat	新功能
fix

Bug 修复 |
| docs | 文档更新 |
| refactor | 重构 |
| test | 测试相关 |
| chore | 构建/工具/依赖 |

---

子代理任务模板

启动开发任务时使用此模板：

javascript
sessions_spawn({
runtime: subagent,
mode: run,
cwd: {项目目录},
task: 你是 Git 工作流开发助手。

任务信息

• - 类型：{功能开发|修复}
• 描述：{任务描述}
• 分支名称：{分支名称}

⚠️ 如果是功能开发，必须先理解代码库：

1. 1. 搜索相关代码文件
2. 阅读相关模块实现
3. 识别可复用的辅助/工具方法