gh-issues-batch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Issues Batch Implementer

GitHub Issues 批量实现器

Vollautomatischer Abarbeitungs-Workflow für alle offenen GitHub Issues. Ziel ist Hands-Off Implementierung: User triggert, Claude meldet sich erst zurück, wenn alle Issues entweder gemerged sind oder als Blocker dokumentiert wurden.

用于全自动处理所有开放 GitHub Issues 的工作流。目标是实现 Hands-Off（免干预）开发：用户只需触发，Claude 仅在所有 Issues 均已合并或被记录为 Blocker 后才会回复。

Kernprinzipien

核心原则

Keine Zwischenmeldungen. Status nur intern als TodoList tracken. Erst am Ende ein Sammel-Report.
Parallelität wo möglich. Unabhängige Issues laufen gleichzeitig als Subagents. Nur dependent Issues laufen seriell.
Test-First. Kein Issue gilt als fertig, bevor Tests und Playwright-Verifikation grün sind.
Atomare Commits. Jedes erfolgreich implementierte Issue bekommt seinen eigenen Commit mit
```
Closes #<nr>
```
im Body.
Failure isoliert. Ein gescheitertes Issue bricht den Batch nicht ab — es wird übersprungen und am Ende reported.

不发送中间消息。 只在内部使用 TodoList 跟踪状态。最后统一发送汇总报告。
尽可能并行。 独立的 Issues 同时作为 Subagents 运行。只有存在依赖关系的 Issues 才串行运行。
测试优先。 在测试和 Playwright 验证通过前，任何 Issue 都不算完成。
原子化提交。 每个成功实现的 Issue 都有独立提交，提交正文包含
```
Closes #<nr>
```
。
隔离故障。 失败的 Issue 不会中止整个批次——将其跳过，并在最后报告。

Workflow

工作流

Phase 1: Issues sammeln & klassifizieren

阶段 1：收集并分类 Issues

bash

gh issue list --state open --json number,title,body,labels,assignees --limit 200 > /tmp/issues.json

Lies die Issues und gruppiere sie:

Dependency-Map bauen: Für jedes Issue prüfen, ob im Body
```
depends on #X
```
,
```
blocked by #X
```
,
```
after #X
```
oder ähnliche Marker stehen. Auch Label wie
```
blocked
```
oder
```
depends-on:X
```
beachten.
Touch-Map bauen: Aus Issue-Body/Labels grob ableiten, welche Dateien/Module berührt werden. Issues, die laut Beschreibung an dieselben Dateien gehen, gelten als konfliktgefährdet und laufen seriell.
Pools bilden: Issues ohne Abhängigkeiten und ohne File-Konflikte → "parallel-pool". Rest → "serial-queue", sortiert nach Topologie. Wenn die Klassifikation unklar ist (z.B. komplexe Cross-Cutting-Concerns), im Zweifel seriell.

bash

gh issue list --state open --json number,title,body,labels,assignees --limit 200 > /tmp/issues.json

读取 Issues 并按以下方式分组：

构建 Dependency-Map： 对每个 Issue，检查其正文中是否存在
```
depends on #X
```
、
```
blocked by #X
```
、
```
after #X
```
或类似标记。同时也要注意
```
blocked
```
或
```
depends-on:X
```
等 Label。
构建 Touch-Map： 根据 Issue 正文和 Label，粗略推断会涉及哪些文件或模块。如果多个 Issues 根据描述会修改相同文件，则视为可能冲突，必须串行运行。
组建 Pools： 无依赖且无文件冲突的 Issues → “parallel-pool”。其余 Issues → “serial-queue”，并按拓扑顺序排序。如果分类不明确（例如涉及复杂的 Cross-Cutting Concerns），则默认选择串行执行。

Phase 2: Branch-Strategie

阶段 2：Branch 策略

Pro Issue ein eigener Branch:

issue/<nummer>-<kebab-case-titel>

. Vom aktuellen branch aus erstellen. Bei parallelen Issues: jedes Subagent arbeitet auf seinem eigenen Branch in einem eigenen Worktree:

bash

git worktree add ../wt-issue-<n> issue/<n>-<slug>

Worktrees verhindern dass parallele Subagents sich gegenseitig den Working-Tree zerschießen.

每个 Issue 使用独立 Branch：

issue/<nummer>-<kebab-case-titel>

。从当前 Branch 创建。对于并行 Issues，每个 Subagent 在自己的 Branch 和自己的 Worktree 中工作：

bash

git worktree add ../wt-issue-<n> issue/<n>-<slug>

Worktree 可防止并行 Subagents 相互破坏 Working Tree。

Phase 3: Implementierung pro Issue

阶段 3：逐个实现 Issue

Für jedes Issue (egal ob parallel oder seriell) gilt derselbe innere Loop. Bei Parallelausführung wird der gesamte Loop in einen Subagent gepackt (Task tool), bei seriellen Issues läuft er im Hauptkontext.

Innerer Loop:

Read & Plan. Issue-Body lesen, Akzeptanzkriterien extrahieren, Implementierungsplan in 3-7 Schritten skizzieren.
/tdd
aufrufen. Damit werden zuerst die Tests geschrieben, die die Akzeptanzkriterien abdecken. Tests sollen rot laufen.
Implementieren. Minimal-Code schreiben, der die Tests grün macht. Noch nicht refaktorieren.
Unit-Tests laufen lassen. Wenn rot → zurück zu Schritt 3. Maximal 5 Implementierungs-Iterationen, dann
```
/diagnosing-bugs
```
.
/caveman
aufrufen. Code radikal vereinfachen — weniger Abstraktion, kürzere Funktionen, direkterer Pfad. Tests müssen grün bleiben.
Playwright-MCP Verifikation. Falls UI-Touchpoint vorhanden (Issue-Label
```
ui
```
,
```
frontend
```
,
```
e2e
```
oder UI-Komponenten im Diff): End-to-End-Flow über Playwright-MCP durchspielen. Screenshots vergleichen wo sinnvoll. Bei nicht-UI-Issues (z.B. CLI-Tool, Backend-Service): Playwright entfällt, stattdessen entsprechende Integration-Tests laufen lassen.
Bei Fehler in 4 oder 6 →
/diagnosing-bugs
. Diagnose-Output lesen, gezielten Fix einbauen, Loop ab Schritt 4 wiederholen. Maximal 3 Diagnose-Runden pro Issue, dann das Issue als "blocked" markieren und überspringen.
Commit. Bei Erfolg: alle Änderungen stagen und committen.

对于每个 Issue（无论并行还是串行），内层 Loop 都相同。在并行执行时，整个 Loop 被打包进一个 Subagent（Task 工具）；串行 Issues 则在主上下文中执行。

内层 Loop：

读取与规划。 阅读 Issue 正文，提取 Acceptance Criteria，并以 3–7 个步骤勾勒实现计划。
调用
/tdd
。先编写覆盖 Acceptance Criteria 的测试。测试应先处于失败状态（red）。
实现。 编写使测试通过（green）的最小代码。此时还不进行重构。
运行 Unit-Tests。 如果测试为 red，则返回步骤 3。最多进行 5 次实现迭代，之后调用
```
/diagnosing-bugs
```
。
调用
/caveman
。激进地简化代码——减少抽象、缩短函数、采用更直接的执行路径。测试必须继续通过。
Playwright-MCP 验证。 如果存在 UI Touchpoint（Issue Label 为
```
ui
```
、
```
frontend
```
、
```
e2e
```
，或 diff 中包含 UI 组件）：通过 Playwright-MCP 走通 E2E Flow。在合理时比较 Screenshots。对于非 UI Issues（例如 CLI-Tool、Backend-Service），跳过 Playwright，改为运行相应的 Integration-Tests。
如果步骤 4 或 6 出错 →
/diagnosing-bugs
。读取诊断输出，加入针对性 Fix，然后从步骤 4 重新开始 Loop。每个 Issue 最多进行 3 轮诊断，之后将该 Issue 标记为“blocked”并跳过。
Commit。 成功后：暂存所有更改并 commit。

Commit-Format

Commit 格式

<type>(<scope>): <kurzbeschreibung>
 
<längere beschreibung was umgesetzt wurde>
 
Closes #<issue-nummer>

<type>

aus:

feat

fix

refactor

test

docs

chore

<scope>

aus dem Issue-Kontext ableiten (Modul, Komponente, etc.).

Beispiel:

feat(auth): JWT refresh token rotation
 
Implementiert Token-Rotation nach RFC 6749 Section 6. Refresh tokens
werden bei jedem Use invalidiert und durch neue ersetzt. Reuse-Detection
loggt Verdachtsfälle.
 
Closes #142

<type>(<scope>): <kurzbeschreibung>

<längere beschreibung was umgesetzt wurde>

Closes #<issue-nummer>

<type>

可选值：

feat

、

fix

、

refactor

、

test

、

docs

、

chore

。

<scope>

根据 Issue 上下文推导（模块、组件等）。

示例：

feat(auth): JWT refresh token rotation

Implementiert Token-Rotation nach RFC 6749 Section 6. Refresh tokens
werden bei jedem Use invalidiert und durch neue ersetzt. Reuse-Detection
loggt Verdachtsfälle.

Closes #142

Phase 4: Merge / Push (optional)

阶段 4：Merge / Push（可选）

Default: Branches lokal lassen, nicht pushen, keine PRs öffnen. Das ist die sicherste Variante.

Branch-Regel (hart): Commits landen immer auf dem Branch, der beim Start aktiv war — niemals direkt auf

main

. Den aktiven Branch einmalig mit

git branch --show-current

ermitteln und alle Commits dorthin schreiben. Kein

git checkout main

, kein

git push

ohne explizite Anweisung des Users.

Wenn der User explizit "pushe alles" oder "öffne PRs" gesagt hat:

```
git push -u origin <branch>
```
pro Branch
```
gh pr create --fill --base main
```
pro Branch Bei Unklarheit: nicht pushen und im Final-Report fragen.

默认：分支保留在本地，不 push，也不打开 PR。 这是最安全的方案。

Branch 规则（强制）： 提交始终落在启动时处于活动状态的 Branch 上——绝不直接提交到

main

。使用

git branch --show-current

一次性确定活动 Branch，并将所有提交写入该 Branch。不执行

git checkout main

，未经用户明确指示绝不执行

git push

。

如果用户明确表示“push 全部内容”或“打开 PRs”：

对每个 Branch 执行
```
git push -u origin <branch>
```
对每个 Branch 执行
```
gh pr create --fill --base main
```
如果情况不明确：不要 push，并在 Final Report 中询问。

Parallelisierung — wie genau

并行化——具体方式

Wenn der parallel-pool nicht leer ist, spawnt Claude für jedes Issue im Pool einen Subagent gleichzeitig im selben Turn. Jeder Subagent bekommt diese Instruction:

Du implementierst GitHub Issue #<NR> in einem isolierten Worktree.
 
Pfad: <worktree-pfad>
Branch: issue/<n>-<slug>
Issue-Body: <body>
Akzeptanzkriterien: <extrahiert>
 
Workflow:
1. Plan in 3-7 Schritten
2. /tdd → Tests rot
3. Implementierung → Tests grün
4. /caveman → vereinfachen, Tests müssen grün bleiben
5. Bei UI-Touchpoint: Playwright-MCP E2E-Verifikation
6. Bei Fehlern: /diagnosing-bugs, max. 3 Runden
7. Commit mit "Closes #<NR>" im Body
 
Liefere zurück: { "issue": <NR>, "status": "success"|"blocked", "commit_sha": "...", "blocker_reason": "..." }

Wichtig: pro Subagent ein eigener Worktree, sonst Race-Conditions auf dem Working-Tree.

Nach dem Sammeln aller parallelen Ergebnisse: serial-queue abarbeiten (im Hauptkontext, da diese Issues laut Klassifikation Konflikte haben könnten — z.B. Schema-Migrationen, geteilte Config-Dateien).

如果 parallel-pool 非空，Claude 在同一轮中为 pool 内每个 Issue 同时 spawn 一个 Subagent。每个 Subagent 收到以下 Instruction：

Du implementierst GitHub Issue #<NR> in einem isolierten Worktree.

Pfad: <worktree-pfad>
Branch: issue/<n>-<slug>
Issue-Body: <body>
Akzeptanzkriterien: <extrahiert>

Workflow:
1. Plan in 3-7 Schritten
2. /tdd → Tests rot
3. Implementierung → Tests grün
4. /caveman → vereinfachen, Tests müssen grün bleiben
5. Bei UI-Touchpoint: Playwright-MCP E2E-Verifikation
6. Bei Fehlern: /diagnosing-bugs, max. 3 Runden
7. Commit mit "Closes #<NR>" im Body

Liefere zurück: { "issue": <NR>, "status": "success"|"blocked", "commit_sha": "...", "blocker_reason": "..." }

重要：每个 Subagent 必须使用独立 Worktree，否则会对 Working Tree 造成 Race-Conditions。

收集完所有并行结果后，在主上下文中处理 serial-queue，因为按分类这些 Issues 可能存在冲突——例如 Schema 迁移、共享 Config 文件等。

Slash-Command-Nutzung

Slash-Command 使用方式

Diese Commands werden vorausgesetzt und gehören zum Standard-Setup:

/tdd
— Test-Driven-Development-Workflow. Schreibt zuerst failing Tests basierend auf Akzeptanzkriterien.
/diagnosing-bugs
— Fehleranalyse-Workflow. Liest Stack-Trace / Test-Output, identifiziert Root-Cause, schlägt gezielten Fix vor.
/caveman
— Code-Simplification-Workflow. "Make it dumb." Entfernt unnötige Abstraktion, kürzt Funktionen, reduziert Indirektion. Diese Commands existieren im User-Setup. Falls einer fehlt: einmal beim ersten Issue feststellen, dann im Final-Report melden ("
```
/caveman
```
nicht verfügbar, Simplification übersprungen") und stattdessen den entsprechenden Schritt manuell durchführen.

以下 Commands 视为已预装，属于标准 Setup：

/tdd
— Test-Driven-Development 工作流。先根据 Acceptance Criteria 编写 failing Tests。
/diagnosing-bugs
— 错误分析工作流。读取 Stack-Trace / Test-Output，识别 Root-Cause，并提出有针对性的 Fix 建议。
/caveman
— Code-Simplification 工作流。“把代码做简单。”移除不必要的抽象、缩短函数并减少间接层。这些 Commands 存在于用户的 Setup 中。如果缺少其中任何一个：在第一个 Issue 时检测一次，然后在 Final Report 中报告（“
```
/caveman
```
不可用，已跳过简化步骤”），并改为手动执行相应步骤。

Wann den User doch unterbrechen

何时仍需中断用户

Trotz "no zwischenmeldungen"-Prinzip gibt es harte Stopp-Bedingungen:

Destruktive Operation nötig:
```
git push --force
```
, Drop von Datenbank-Tabellen, Löschen von > 50 Dateien.
Secrets / Credentials gefragt: Ein Issue verlangt API-Keys, Passwörter, Zugangsdaten die nicht da sind.
Mehr als 50% der Issues blocked: Wenn nach den ersten 5 Issues schon 3 blocked sind, ist die Repo-Situation unklar — Stop und Report.
Repo nicht clean beim Start: Uncommitted changes auf dem Start-Branch. Abbrechen, User soll erst aufräumen. Bei diesen Bedingungen: Sofort stoppen, Bisher-Status reporten, auf User warten.

尽管遵循“不发送中间消息”原则，但存在硬性停止条件：

需要执行破坏性操作：
```
git push --force
```
、删除数据库表、删除超过 50 个文件。
需要 Secrets / Credentials： 某个 Issue 要求提供当前不存在的 API-Keys、Passwords 或访问凭据。
超过 50% 的 Issues 被阻塞： 如果处理完前 5 个 Issues 后已有 3 个 blocked，说明 Repo 状态不清晰——停止并报告。
启动时 Repo 不 clean： 启动 Branch 上存在 Uncommitted Changes。中止执行，让用户先整理工作区。在这些情况下：立即停止，报告当前状态并等待用户。

Final Report

Nach Abschluss aller Issues — einmaliger zusammenfassender Bericht in dieser Struktur:

Batch abgeschlossen: <X> von <Y> Issues implementiert.
 
✓ Erfolgreich (parallel):
  #142  feat(auth): JWT refresh — commit abc1234
  #156  fix(api): pagination off-by-one — commit def5678
  ...
 
✓ Erfolgreich (seriell):
  #161  refactor(db): schema migration — commit 9ab0123
  ...
 
✗ Blocked:
  #173  E2E test schlägt fehl in Playwright, Element-Selector instabil
        nach 3 Diagnose-Runden. Manueller Blick nötig.
 
Branches lokal, nicht gepusht. Soll ich PRs öffnen?

Keine weiteren Erklärungen, kein Plauderton, kein Lob für sich selbst. Der User will den Status sehen, sonst nichts.

所有 Issues 完成后——按以下结构发送一次汇总报告：

Batch abgeschlossen: <X> von <Y> Issues implementiert.

✓ Erfolgreich (parallel):
  #142  feat(auth): JWT refresh — commit abc1234
  #156  fix(api): pagination off-by-one — commit def5678
  ...

✓ Erfolgreich (seriell):
  #161  refactor(db): schema migration — commit 9ab0123
  ...

✗ Blocked:
  #173  E2E test schlägt fehl in Playwright, Element-Selector instabil
        nach 3 Diagnose-Runden. Manueller Blick nötig.

Branches lokal, nicht gepusht. Soll ich PRs öffnen?

不要提供进一步解释，不要闲聊，也不要自我表扬。用户只想看到状态。

Edge Cases

Keine offenen Issues: Direkt melden "Keine offenen Issues — nichts zu tun." Kein Workflow starten.
gh
nicht authentifiziert: Erkennen am Fehler, User auffordern
```
gh auth login
```
zu laufen, abbrechen.
Issue ohne klare Akzeptanzkriterien: Plan-Phase aus Issue-Titel + Body interpolieren, im Commit-Body dokumentieren wie interpretiert wurde. Nicht nachfragen.
Issue-Body verweist auf externe Spec (Figma, Notion): Wenn nicht zugreifbar, beste Interpretation aus dem Issue-Text + Repo-Konventionen ableiten. Im Blocker-Report vermerken falls nötig.
Test-Suite läuft im Repo gar nicht: Erst
```
npm test
```
/
```
pnpm test
```
/
```
pytest
```
/ etc. einmal verifizieren bevor parallele Subagents losgeschickt werden. Wenn die Test-Suite kaputt ist, ist das ein Stopp-Grund.

没有开放 Issues： 直接报告“无开放 Issues——无需操作。”不启动工作流。
gh
未认证：根据错误检测到未认证状态，要求用户运行
```
gh auth login
```
，然后中止。
Issue 没有明确的 Acceptance Criteria： 在 Plan-Phase 中根据 Issue 标题和正文推演内容，并在 Commit 正文中记录对需求的理解方式。不要询问。
Issue 正文引用外部 Spec（Figma、Notion）： 如果无法访问，则根据 Issue 正文和 Repo 约定推导出最佳理解。必要时在 Blocker Report 中注明。
Repo 的 Test-Suite 无法运行： 在启动并行 Subagents 之前，先运行一次
```
npm test
```
/
```
pnpm test
```
/
```
pytest
```
/ 等命令验证 Test-Suite。如果 Test-Suite 已损坏，则停止执行。

Anti-Patterns

NICHT den User nach jedem Issue fragen ob er weitermachen will.
NICHT "ich denke das ist eine gute Idee" — einfach machen.
NICHT Commits mit "Co-Authored-By: Claude" — der User will saubere Commits ohne AI-Branding, außer er hat es explizit gewünscht.
NICHT direkt auf
```
main
```
committen — immer auf dem aktiven Branch committen (
```
git branch --show-current
```
prüfen).
NICHT pushen ohne explizite Anweisung des Users.
NICHT
```
git push --force
```
ohne User-Bestätigung.
NICHT PRs öffnen ohne explizite Anweisung.
NICHT den Caveman-Schritt überspringen "weil der Code schon einfach ist" —
```
/caveman
```
aufrufen, der Command entscheidet.

不要在每个 Issue 完成后都询问用户是否继续。
不要说“我认为这是个好主意”——直接执行。
不要创建包含“Co-Authored-By: Claude”的 Commits——除非用户明确要求，否则用户希望提交保持干净且不带 AI-Branding。
不要直接 commit 到
```
main
```
——始终 commit 到启动时活动的 Branch（使用
```
git branch --show-current
```
检查）。
不要在未获用户明确指示时 push。
不要在未获用户确认时执行
```
git push --force
```
。
不要在未获用户明确指示时打开 PR。
不要以“代码本来就很简单”为理由跳过 Caveman 步骤——调用
```
/caveman
```
，由该 Command 决定。