Coding SOP — 编程工作标准流程

总览

7 阶段线性流程，每个阶段必须按顺序执行。阶段 3-6 必须在 Subagent 中实施。

需求理解 → 创建分支 → 功能设计(Subagent) → 变动评审(Subagent) → 编码(Subagent) → 单元测试(Subagent) → Git 提交推送
  ①          ②            ③                     ④                    ⑤                  ⑥                  ⑦

阶段 ① — 需求理解

1. 仔细阅读需求描述
2. 检查是否缺少基本信息：
   • 目标功能/问题是什么
   • 涉及的代码模块或文件范围
   • 预期效果或验收标准
   • 技术约束（语言、框架、依赖等）
3. 若信息缺失 → 列出缺失项，向用户确认后再继续
4. 若信息充分 → 总结理解，进入阶段 ②

阶段 ② — 创建开发分支

1. 确认当前位于仓库根目录
2. 根据需求类型选择分支前缀：
   • feature/xxx — 新功能
   • fix/xxx — Bug 修复
   • refactor/xxx — 重构
   • chore/xxx — 维护/配置
3. 基于最新主干创建并切换分支：

   git checkout main || git checkout master
   git pull
   git checkout -b <branch-name>
   

4. 记录分支名称，后续阶段使用

阶段 ③ — 功能设计（Subagent）

启动一个 Subagent 进行功能设计，要求：

• 输入：需求描述 + 当前仓库结构
• 输出：设计报告，包括：
  • 需要修改/新增的文件列表
  • 每个文件的改动概要
  • 预期效果描述
• 超时：至少预留 10 分钟（runTimeoutSeconds >= 600）
• 运行模式：runtime="subagent", mode="run"

设计报告输出后，进入阶段 ④。

阶段 ④ — 代码变动评审（Subagent）

启动另一个 Subagent 进行评审，要求：

• 输入：需求描述 + 阶段 ③ 的设计报告
• 任务：
  1. 评审设计报告中规划的改动范围是否与需求匹配
  2. 评估是否存在遗漏或过度设计
  3. 评估技术方案是否合理
• 输出：评审报告，结论为以下之一：
  • ✅ 通过 — 可以进入阶段 ⑤
  • ❌ 不通过 — 列出问题，返回阶段 ③ 重新设计
• 超时：5 分钟即可（runTimeoutSeconds >= 300）

若不通过，携带评审意见重新执行阶段 ③。

阶段 ⑤ — 编码（Subagent）

启动 Subagent 进行正式编码，要求：

• 输入：需求描述 + 阶段 ③ 的设计报告（若经过阶段 ④ 修订，用最新版）
• 超时：至少预留 10 分钟（runTimeoutSeconds >= 600），复杂任务适当增加
• 要求：
  • 按设计报告中的文件列表逐个实现
  • 遵循项目现有代码风格和规范
  • 编写必要的注释

编码完成后进入阶段 ⑥。

阶段 ⑥ — 单元测试（Subagent）

启动 Subagent 执行测试，要求：

• 任务：
  1. 发现并运行项目中已有的全部单元测试
  2. 验证所有测试是否通过
  3. 如有新增代码，补充对应的单元测试
• 超时：根据项目规模设定，至少 10 分钟
• 结果判断：
  • ✅ 全部通过 → 进入阶段 ⑦
  • ❌ 存在失败 → 出具失败报告，携带测试日志返回阶段 ⑤ 重新修改

循环执行阶段 ⑤ → ⑥，直至全部测试通过。

阶段 ⑦ — Git 提交并推送

阶段性总结与提交

• 每个编码阶段完成后（包括阶段 ⑤ 编码和阶段 ⑥ 单元测试中的每一轮循环），必须及时总结本阶段完成的工作内容，并 commit 到仓库。
• 不要累积大量改动后再一次性提交，保持 commit 的粒度和可读性。

整体完成与推送

• 整个需求全部完成后，应及时 push 到远程仓库。

推送前提：编译通过

• 必须先编译通过，才能 push。 推送前必须验证项目编译正常，无编译错误。
• 验证方式：运行项目的标准构建/编译命令，确认零错误。

推送分支规则

• 编译通过 但单元测试存在失败：
  • ❌ 禁止 推送到主分支（main、master 等）
  • ✅ 只允许推送到独立开发分支（feature/*、fix/*、refactor/* 等）
• 编译通过 且 全部测试通过：
  • ✅ 可以推送到任意分支

执行步骤

1. 验证编译：运行项目编译/构建命令，确认无错误
2. 检查变动状态：

   git status
   git diff --stat
   

3. 提交变动：

   git add -A
   git commit -m "<type>: <description>"
   

4. 推送到远程仓库：

   git push -u origin <branch-name>
   

5. 推送结果验证（必须执行）：
   • 检查 git push 命令的退出状态码，确认推送成功
   • 执行 git log origin/<branch-name>..HEAD 确认本地没有未推送的 commit
   • 或执行 git status 确认输出包含 "Your branch is up to date with 'origin/'"
   • 若验证失败：必须输出完整的错误信息，包括：
     • git push 的完整错误输出
     • 可能的原因分析（如：网络问题、权限不足、远程分支冲突、仓库不存在等）
     • 建议的解决方案
   • 推送失败时必须向用户报告，不得静默忽略
   • 向用户确认推送结果时，明确告知「推送成功」或「推送失败 + 原因」
6. 合并到主干（仅当用户明确要求时）：

   git checkout main || git checkout master
   git pull
   git merge <branch-name> --no-ff -m "merge: <branch-name>"
   git push
   

   • 合并推送同样需要执行推送结果验证

⚠️ 推送红线

• 绝对不允许 git push --force 或 --force-with-lease
• 绝对不允许 git rebase（包括 git rebase -i、git pull --rebase 等一切 rebase 变体）
• 绝对不允许 git merge --squash（禁止 squash merge）
• 合并方式：只允许使用 commit + merge 的方式提交和合并代码。开发分支上的每个 commit 必须保留完整历史，合并到主干时必须使用 git merge --no-ff 创建合并提交，严禁通过 rebase 改写历史或通过 squash 压缩 commit。
• 默认不允许 推送到 main 或 master 分支
• 如确需推送至主干，必须获得用户明确确认

推送失败处理流程

流程异常处理

📁 项目文档规范

.sop/ 目录结构

所有编码相关文档统一写入项目根目录的 .sop/ 子目录。若项目已有 .sop/ 目录，遵循用户的目录结构和命名规则，不覆盖。

项目根目录/
├── .sop/
│   ├── SOP.md              ← 编码规范总纲
│   ├── 00-memo/            ← 备忘录、临时记录、沟通纪要
│   ├── 01-requirement/     ← 需求文档、需求变更记录
│   ├── 02-design/          ← 设计文档（架构设计、接口设计、数据模型等）
│   ├── 03-plan/            ← 开发计划、任务分解、排期
│   ├── 04-report/          ← 阶段性报告、总结报告、验收报告
│   ├── 05-issue/           ← 问题记录、缺陷追踪、已知风险
│   └── 06-review/          ← 评审报告（代码评审、设计评审等）

编号规则：00 起跳，01-06 对应开发流程阶段，便于按流程顺序查阅。

文档写入规则

目录由编码流程自动创建和维护。

.sop/SOP.md 编码规范总纲

允许用户在 .sop/SOP.md 中维护项目的编码规范。如果该文件已存在，只读取参考，不修改（除非用户明确要求更新）。

建议包含的内容板块：

# 项目编码规范

## 1. 项目结构规范
- 目录组织方式（如 src/、test/、docs/、config/ 的划分）
- 各目录职责说明

## 2. 命名规范
- 项目/模块命名
- 目录/文件命名
- 变量命名（camelCase / snake_case 等）
- 函数/方法命名
- 常量命名（如 UPPER_SNAKE_CASE）
- 类/接口命名（如 PascalCase）
- 私有成员命名约定（如前缀 _ 等）
- 本地变量命名
- 函数参数命名

## 3. 代码风格
- 缩进、行宽、换行
- 注释规范（文件头注释、函数注释、行内注释）
- 导入/依赖声明顺序

## 4. 版本控制规范
- 分支命名
- commit message 格式
- tag 命名

## 5. 其他约定
- 错误处理规范
- 日志规范
- 安全注意事项

Subagent 参数约定

所有阶段使用的 Subagent 参数：

runtime: "subagent"
mode: "run"

• 阶段 ③、⑤、⑥ 的 runTimeoutSeconds ≥ 600
• 阶段 ④ 的 runTimeoutSeconds ≥ 300
• 通过 task 参数传入详细指令
• 子任务完成后结果自动返回主流程