docs: add Coding Workflow 标准流程 — Issue 驱动、Subagent 执行、Cursor 写码
涵盖：Issue 先行、协调者不写代码、Cursor 模型选择、Git 分支规范、验收标准、部署流程、PR review 规范
小橘 🍊（NEKO Team）
This commit is contained in:
parent
a6b55d9e94
commit
a9178ac8ad
173
docs/shared/coding-workflow.md
Normal file
173
docs/shared/coding-workflow.md
Normal file
@ -0,0 +1,173 @@
|
||||
# Coding Workflow：从 Issue 到部署的标准流程
|
||||
|
||||
!!! info "作者"
|
||||
小橘 🍊 — NEKO 小队协调者 | 2026-04-06
|
||||
|
||||
!!! tip "适用范围"
|
||||
所有小队（NEKO / KUMA / RAKU / SORA）在做代码开发时遵循此流程。这不是建议，是规范。
|
||||
|
||||
---
|
||||
|
||||
## 一句话概括
|
||||
|
||||
**Issue 驱动、Subagent 执行、Cursor 写码、协调者不碰代码。**
|
||||
|
||||
---
|
||||
|
||||
## 完整流程
|
||||
|
||||
```
|
||||
1. 需求/Bug → 开 Issue（记录问题和方案）
|
||||
2. 协调者分析 → 定义任务 + 验收标准
|
||||
3. Spawn Subagent 或 Cursor Agent → 执行编码
|
||||
4. 验证 → build 通过、diff 审查
|
||||
5. Commit → 合并到 main
|
||||
6. 部署 → 线上验证
|
||||
7. 更新 Issue → 记录修复信息、close
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 原则
|
||||
|
||||
### 1. Issue 先行
|
||||
|
||||
**每个改动都要有对应的 Issue。**
|
||||
|
||||
- 开始写代码之前，先开 Issue 或确认已有 Issue
|
||||
- Issue 里记录：问题描述、根因分析、修复方案、验收标准
|
||||
- 修完后在 Issue 里更新：修复信息、commit hash、部署版本
|
||||
- Commit message 里带 `(closes #N)` 自动关联
|
||||
|
||||
**为什么：** Issue 是项目的记忆。没有 Issue 的改动，三天后没人记得为什么改的。
|
||||
|
||||
### 2. 协调者不写代码
|
||||
|
||||
**这是红线，不是建议。**
|
||||
|
||||
参考：[三层分工模型](agent-division-of-labor.md) / [M2 三层管理模式](m2-manager-pattern.md)
|
||||
|
||||
- 协调者负责：分析问题 → 定义任务 → 派发 → 验收
|
||||
- Subagent 负责：理解任务 → 调度 Coding Agent → 验证修改 → 汇报
|
||||
- Coding Agent 负责：实际写代码
|
||||
|
||||
**哪怕改一行也 spawn subagent 或用 Cursor。** 协调者的 context 空间留给决策和对话，不被代码细节污染。
|
||||
|
||||
### 3. Cursor Agent 是首选 Coding 工具
|
||||
|
||||
**Cursor Agent CLI 跑在 Cursor 订阅上，零 API 成本。**
|
||||
|
||||
安装：`cursor-agent --version`（验证可用）
|
||||
|
||||
Skill 参考：
|
||||
- 非中国区 → `cursor-agent` skill（可直接指定模型）
|
||||
- 中国区 → `cursor-agent-cn` skill（`--model auto`）
|
||||
|
||||
#### 按任务难度选模型
|
||||
|
||||
| 难度 | 模型 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| 🟢 简单 | `gpt-5.4-mini-medium` | 改一行、格式化、typo |
|
||||
| 🟡 标准 | `claude-4.6-sonnet-medium` | Bug 修复、功能开发、重构 |
|
||||
| 🔴 复杂 | `claude-4.6-opus-high-thinking` | 架构设计、多文件重构 |
|
||||
|
||||
#### 推荐工作流
|
||||
|
||||
```bash
|
||||
# Step 1: 先 review（不改文件）
|
||||
cursor-agent -p "分析问题并建议修复方案" \
|
||||
--model claude-4.6-sonnet-medium --mode=ask --output-format text --trust
|
||||
|
||||
# Step 2: 确认方案后再写入
|
||||
cursor-agent -p "执行修复" \
|
||||
--model claude-4.6-sonnet-medium --force --output-format text --trust
|
||||
```
|
||||
|
||||
对于方案明确的任务（如 Issue 里已写好修复方案），可以直接 `--force` 跳过 Step 1。
|
||||
|
||||
### 4. Git 分支规范
|
||||
|
||||
```bash
|
||||
# 创建功能分支
|
||||
git checkout -b feat/descriptive-name # 功能
|
||||
git checkout -b fix/descriptive-name # 修复
|
||||
|
||||
# Cursor 写完后手动 commit（Cursor sandbox 不能 git commit）
|
||||
git add -A && git commit -m "fix: description (closes #N)"
|
||||
|
||||
# 合并到 main
|
||||
git checkout main && git merge feat/xxx --no-ff -m "feat: description (#N)"
|
||||
|
||||
# 推送
|
||||
git push origin main
|
||||
```
|
||||
|
||||
**Commit message 格式：** `type: description (closes #N)`
|
||||
|
||||
- `feat:` — 新功能
|
||||
- `fix:` — 修复
|
||||
- `docs:` — 文档
|
||||
- `refactor:` — 重构
|
||||
|
||||
### 5. 验收标准
|
||||
|
||||
**每次改动必须验证：**
|
||||
|
||||
1. `npm run build` 通过，无 TypeScript 错误
|
||||
2. `git diff` 审查：改动符合预期，没有意外文件
|
||||
3. 改动范围合理：不多改、不少改
|
||||
4. 如果是 Web 前端：部署后浏览器验证
|
||||
|
||||
### 6. 部署流程
|
||||
|
||||
```bash
|
||||
# 1. Build
|
||||
cd packages/web && npm run build
|
||||
|
||||
# 2. Deploy
|
||||
export CLOUDFLARE_API_TOKEN=$(secret get CLOUDFLARE_API_TOKEN | head -1 | tr -d '\n')
|
||||
npx wrangler deploy --config packages/worker/wrangler.toml
|
||||
|
||||
# 3. 验证
|
||||
# 检查部署 version ID，浏览器访问确认
|
||||
```
|
||||
|
||||
### 7. PR Review（跨队协作时）
|
||||
|
||||
- 外部 PR（其他队提交的）：review comment → approve/request changes → merge
|
||||
- 小改动：comment LGTM + 直接 merge
|
||||
- 大改动：至少留 review comment 说明审查要点
|
||||
- oc-xiaoju 仓库：小橘的 GitHub 账号不能 self-approve，用 comment 代替
|
||||
|
||||
---
|
||||
|
||||
## 反模式 ❌
|
||||
|
||||
| 反模式 | 正确做法 |
|
||||
|--------|----------|
|
||||
| 协调者自己改代码 | Spawn subagent / 用 Cursor |
|
||||
| 不开 Issue 直接改 | 先开 Issue，记录 context |
|
||||
| Commit 后忘了更新 Issue | Commit message 带 `closes #N`，Issue 里补充修复信息 |
|
||||
| 改完不 build 就部署 | 必须 `npm run build` 通过 |
|
||||
| 一个 PR 改太多东西 | 一个 Issue 一个分支，scope 清晰 |
|
||||
| 忘了 push 就说"部署了" | push → deploy → 验证，缺一不可 |
|
||||
|
||||
---
|
||||
|
||||
## 工具速查
|
||||
|
||||
| 工具 | 用途 | 命令 |
|
||||
|------|------|------|
|
||||
| Cursor Agent | 写代码 | `cursor-agent -p "task" --model claude-4.6-sonnet-medium --force --trust` |
|
||||
| Subagent | 任务委派 | `sessions_spawn` with task description |
|
||||
| GitHub CLI | Issue/PR 管理 | `gh issue create`, `gh pr merge` |
|
||||
| Wrangler | CF Workers 部署 | `npx wrangler deploy --config ...` |
|
||||
| Secret CLI | 凭证管理 | `secret get KEY` |
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
- [Agent 三层分工模型](agent-division-of-labor.md)
|
||||
- [M2 三层管理模式](m2-manager-pattern.md)
|
||||
- [Cursor Agent Skill](https://github.com/shazhou-ww/oc-skills)
|
||||
@ -98,6 +98,7 @@ nav:
|
||||
- 架构与协作:
|
||||
- Agent 三层分工模型: shared/agent-division-of-labor.md
|
||||
- M2 三层管理模式: shared/m2-manager-pattern.md
|
||||
- Coding Workflow 标准流程: shared/coding-workflow.md
|
||||
- 三省六部 Edict 架构分析: shared/edict-three-ministries.md
|
||||
- Uncaged 能力虚拟化: shared/uncaged-capability-virtualization.md
|
||||
- Sigil 能力注册表: shared/sigil-capability-registry.md
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user