| name | workflow/github-issue |
|---|---|
| module | workflow |
| description | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 推送特性分支 → 推送后回复 |
| status | 已实现 |
| scope | 通用 |
| source | 项目自有 |
不遵守此流程会导致:
- 问题分析结论只留在本地,issue 参与者无法同步进展
- 直接在主干工作区改代码,污染工作区、难以回滚和并行处理多个 issue
- 修复完成后 issue 长期悬空,无法追溯「哪个提交解决了哪个 issue」
- 分支、worktree、合并目标不统一,发布时遗漏改动
codingapi/flow-engine 及其关联仓库(如 codingapi/flow-frontend)的所有 GitHub issue。
- 分析可以不开 worktree,改代码必须开:定位阶段只读代码即可;一旦确定要修改,必须新建 git worktree + 特性分支。
- 先回复,再动手:定位到问题后,先在对应 issue 回复根因与处理方案。
- dev 只作为基线,不参与交付:worktree 基于
dev代码创建;修复提交、推送与 issue 关联全部发生在该 issue 的特性分支上。完成后不合并dev,是否合并由人工决定,助手只在任务完成时提示分支与 PR 链接。 - 提交即关联 issue:提交信息使用
Closes #<id>关联;是否已真正关闭取决于是否进入默认分支,未自动关闭时由维护者确认后手动关闭。 - 推送后再回复:特性分支推送到 GitHub 之后,才在 issue 回复修复内容、提交与验证结果;未推送前不得发布完成回复。
- 回复必须可追溯代码:只要回复内容涉及代码改动,就必须附上「仓库 + 分支 + 提交号(SHA)」,有 PR 时附 PR 链接;前后端都有改动时两个仓库分别列出。未涉及代码改动(纯分析、纯文档结论)时才可省略,并说明没有代码提交。
gh issue view <id> --repo codingapi/flow-engine \
--json number,title,state,labels,body,comments,author,createdAt- 使用代码搜索、LSP、文档(
docs/conventions、docs/capabilities)定位根因; - 明确影响范围(后端 / PC 端 / 移动端)、是否涉及前端子模块
flow-frontend; - 判断是否属于已有能力缺陷,优先复用既有机制而非新增。
将以下内容整理为中文评论:
- 问题原因(引用具体类/文件/方法);
- 影响范围(哪些动作、端、版本);
- 处理方案(改动点、交互变化、兼容性);
- 交付方式(基于
dev的特性分支名,完成后由维护者合并); - 若本次回复引用了已经存在的代码提交(例如复用其他 issue 的修复),同样要附上对应分支与提交号,避免读者无法定位代码。
gh issue comment <id> --repo codingapi/flow-engine --body-file /tmp/issue-<id>-analysis.md后端主仓库(.worktrees/ 已被 .gitignore 忽略):
git worktree add .worktrees/issue-<id> -b feature/issue-<id>-<slug> dev
cd .worktrees/issue-<id>前端子模块(flow-frontend/.claude/worktrees/ 已被忽略):
cd flow-frontend
git worktree add .claude/worktrees/issue-<id> -b feature/issue-<id>-<slug> dev
cd .claude/worktrees/issue-<id>
pnpm install --frozen-lockfile --prefer-offline # worktree 无 node_modules命名约定:feature/issue-<issue编号>-<简短英文描述>。
worktree 仅以
dev代码为基线;创建之后的所有提交、推送与 issue 关联都只发生在该特性分支上,dev不参与交付。
- 先补测试(红灯),再实现(绿灯),最后重构;
- 前端:
npx rstest run(单包)、pnpm run test:<package>、pnpm run build:<package>; - 后端:
./mvnw -pl <module> test,必要时./mvnw clean install; - 修改代码后必须本地编译/测试通过,失败项如实报告,不得声称已验证。
git push -u origin feature/issue-<id>-<slug>- 只推送该 issue 的特性分支,
dev保持不动,是否合并由人工决定; - 禁止推送到
dev/main,禁止在本地合并dev; - 任务完成提示中给出分支地址与 PR 链接即可,不代为合并;
- 前后端均有改动时,两个仓库各自推送自己的特性分支;
- 不更新主仓库记录的
flow-frontend子模块指针,除非维护者明确要求; - 推送后可清理本地 worktree(
git worktree remove <path>),分支保留。
提交信息格式:
fix: <一句话描述> (<关联范围>)
<可选的改动说明>
Closes #<id>
Closes #<id>只在提交进入默认分支(main)时由 GitHub 自动关闭;- 推送到特性分支不会关闭 issue;特性分支合并到
dev后仍保持打开,待dev → main合并时自动关闭; - 如需提前关闭,必须由维护者确认后执行
gh issue close <id>,不得擅自关闭。
前置条件:特性分支已推送到 GitHub。未推送前只可说明「修复已提交到本地特性分支,待推送」,不得发布完成结论。
回复内容包含:
-
根因与最终方案(与步骤 3 的差异);
-
变更文件/能力(新增公共 API、交互变化);
-
验证结果(测试用例数、构建结果);
-
代码提交清单(必填,涉及代码改动时):逐仓库列出
仓库 / 分支 / 提交号(SHA) / PR 链接,例如:- codingapi/flow-engine:feature/issue-<id>-<slug> @ 0f1aadb9(PR:#123) - codingapi/flow-frontend:feature/issue-<id>-<slug> @ c12677f(PR:#72)仅有分析结论、没有代码提交时,注明「本次无代码提交」;
-
升级/兼容提示(如有行为变更)。
- 不得向
dev/main推送,不得在本地合并dev(是否合并由人工决定); - 特性分支推送是标准步骤,但推送前必须确认远程分支名,避免误推;
- 不得在主工作区(非 worktree)直接修改业务代码;
- 不得跳过测试与编译验证;
- 不得在特性分支推送前发布完成回复(定位回复不受此限);
- 不得在代码未进入默认分支前擅自关闭 issue;
- 不得用相对路径跨 package 引用(前端规范)。
- issue 已读取并确认现状
- 定位结论已在 issue 回复
- worktree + 特性分支已创建(基于
dev) - 测试先行且全量通过,构建通过
- 特性分支已推送到 GitHub(
dev未改动) - 提交信息包含
Closes #<id> - 推送后已在 issue 回复修复与验证结果
- 回复中已附代码提交清单(仓库 / 分支 / 提交号 / PR 链接;无代码改动已注明)