crowi Crowi Fix (repro-first の軽量バグ修正)
「壊れているものを直す」ための最短経路。crowi-feature の planner/レビューループは 重すぎ、アドホックだと再現なし・根本原因なしの推測修正が混ざる — その中間を定型化する。
crowi-feature との使い分け
| 条件 | 使うもの |
|---|---|
| 挙動が壊れている・期待とのズレが明確・設計判断不要 | crowi-fix |
| 新しい挙動を足す / 契約・スキーマ変更を伴う / 設計判断あり | crowi-feature(必要なら crowi-design から) |
| 修正方針に複数案があり trade-off 判断が要る | いったん止まってユーザーに確認(勝手に選ばない) |
途中で「設計判断が要る」と気づいたら、進めずにその時点で報告して切り替える。
ワークフロー
Step 1: 再現(repro-first)
- 修正より先に、失敗するテストを書く(api は jest + supertest + mongodb-memory-server)。 「バグが直るとこのテストが green になる」が完了の定義。
- テストで再現しづらい UI バグ: 再現手順を記録し、クリティカルフロー
(feature-planner.md の表)に該当し小さく書けるなら
packages/e2e/tests/に足す(無理はしない)。 - 再現できないバグは直さない — 推測修正は禁止。再現条件をユーザーに確認して止まる。
Step 2: 根本原因の特定(systematic-debugging)
症状 → 仮説 → 検証を繰り返し、根本原因を file:line で特定してから修正に入る。 対症療法(症状を隠すだけの分岐)を書かない。
Step 3: 修正 + ゲート
- 最小 diff。関係ないリファクタを混ぜない。
- ゲート:
pnpm --filter @crowi/api type-check(web を触ったら +web)/ 該当テスト(Step 1 のテスト含む)/pnpm lint(errors=0)/ 契約を触ったらpnpm --filter @crowi/api-contract build+pnpm check:openapi。
Step 4: codex 1 パスレビュー(fix or drop)
mkdir -p .reviews/codex-runs/fix-<topic>
# prompt: 「git status --porcelain + git diff HEAD で修正を取得し(untracked は直接読む)、
# 退行・境界・並行の観点で敵対レビューせよ」+ FINDINGS schema (crowi-review と同形)
bash .claude/scripts/codex-run.sh --sandbox read-only --tier terra \
--prompt-file .reviews/codex-runs/fix-<topic>/prompt.md \
--schema-file .reviews/codex-runs/fix-<topic>/schema.json \
--out .reviews/codex-runs/fix-<topic>/out.json --label fix-<topic>
- 重い 3 lens は使わない(1 パスのみ)。
- findings は「直すか捨てる」の二択: 自分でコードに当てて裏取りし、正しければ その場で直してゲート再走。誤り・過大なら捨てる(報告に 1 行)。 どこかへの退避は禁止(fix or drop — 退避先は存在しない)。
- exit 2(codex 不可)/ exit 3(出力が不正 — codex が exit 0 で何も書かなかった場合もここに来る) なら skip して報告(レビュー無しで止めない)。どちらも fix の進行を止めない。
Step 5: commit
fix(<scope>): <what>+ 本文に root cause を 1-3 行。テストは同 commit かtest(<scope>)分割(diff サイズで判断)。- ユーザー可視のバグ修正なら changeset(patch)を追加。内部のみなら不要。
- main 直でも worktree でも可。main 直の場合は commit 前に main write lock を取得し
commit 後に解放(CLAUDE.md「main write lock」参照)。worktree の場合、完了後は
/crowi-complete-feature(task ファイル無し → synthesize が signal を立てる — 既存互換)。 push しない。
鉄則
- 再現なしに直さない / 根本原因なしに直さない
- レビュー指摘は fix or drop(退避先は存在しない)
- 設計判断が要ると気づいたら勝手に進めず crowi-design / ユーザーへ
- push はユーザー指示待ち