incu-way-bugs

バグ修正プロセス

推測に頼らずバグを修正するための、ゲートに基づく体系的なワークフローです。まず調査と受付を行い、その後、バグの記録、分析、再現、修正計画、実装、検証、PR レビューへと進みます。重要なゲートは修正計画の確認です。ユーザーが計画を承認する前に、修正コードを書いてはいけません。

---

リポジトリの適格性チェック（何よりも先に）

Phase 0 の前に、現在のリポジトリが ~/.ways/config.yaml の blacklist（形式：incu-base の global-config ルール。常時有効としてインストール済み）に一致するかを確認してください。一致する場合は、このリポジトリが incu-way のブラックリストに登録されていることをユーザーに伝え、今回に限り例外として続行するか、停止するかを尋ねてください。ユーザーが回答するまで、どのフェーズも実行してはいけません。ファイルがない場合、または一致しない場合は、通常どおり続行してください。

---

Phase 0 — 調査と受付

作業に着手する前に、以下を行ってください。

1. PRD.md と docs/ 内の関連ドキュメントを読み、影響を受ける機能を理解します。
2. docs/bugs/ に関連する既存の報告がないか確認します。この問題について、docs/requirements/{slug}/TICKET.md（incu-way-po が作成）がある場合は、まずそれを読み、実現可能性に関する注記とスコープを再導出するのではなく、検証してください。
3. 問題の受付内容を明確にします。
   • 何が壊れていると報告されているか
   • 代わりにどのように動作すべきか
   • 誰が影響を受けるか
   • 環境、深刻度、ビジネスへの影響
   • どの詳細がまだ不足しているか、または未検証か
4. コードベースの状況を把握します。
   • 影響を受ける機能領域またはワークフロー
   • 関連するモジュール、関数、テスト、統合
   • リグレッションの原因となった可能性のある最近のコミットまたはリリース
   • 期待される動作を定めている過去のバグ報告、PRD、決定事項
   • 同じ製品内に、このリグレッションを共有している可能性のある他のリポジトリがないか確認します。hub リポジトリの CLAUDE.md に repos: セクションがあればそれを使用し（こちらが優先）、なければ ~/.ways/config.yaml の linkedRepos（形式：incu-base の global-config ルール。常時有効としてインストール済み）を使用します。
5. ケースに応じて調査の範囲を調整します。
   • 小規模で十分に理解されているバグの場合は、軽量な調査にとどめます。
   • 曖昧な問題、深刻度の高い問題、本番環境に影響する問題の場合は、分析と修正計画に進む前に、より詳しく調査します。
6. バグ報告に重要な詳細が不足している場合は、先に進む前に焦点を絞った確認質問をします。

Phase 0 の終了条件

Phase 1 に進む前に、Claude は以下を説明できる状態である必要があります。

• 現時点で把握している、何が壊れていて、期待される動作が何か
• 誰、または何が影響を受けるか
• 関連する可能性が高いドキュメント、モジュール、コミット、ワークフロー
• 現在置いている前提
• 分析中またはユーザーへの確認を通じて、今後確かめる必要があること

バグ報告がもっともらしく見えるというだけで、期待される動作、根本原因、修正方針を決めつけてはいけません。重要な点が不明確な場合は、その不確実性を明示してください。

---

隔離環境の準備（Phase 0 の直後）

ファイルを作成する前に、作業をどのように隔離するかユーザーに尋ねてください。

現在のチェックアウトで新しいブランチを使って作業しますか？それとも、別の git worktree を作成しますか？

ユーザーの回答に従ってください。 質問したらそこで停止し、ユーザーが選択するまでブランチや worktree を作成してはいけません。

現在のチェックアウトに未コミットの変更がある場合は、ブランチの切り替えや worktree の作成を行う前に停止して確認してください。

オプション A — 現在のチェックアウトでブランチを作成

git switch develop
git pull --ff-only
git switch -c fix/{slug}

BUG.md、ANALYSIS.md、テスト、修正コードなど、すべての作業は現在のチェックアウトのこのブランチで行います。develop または main に直接ファイルを書き込んではいけません。

オプション B — 別の worktree

worktree は .worktrees/ の下にのみ作成してください。パスをユーザーに尋ねてはいけません。

git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/fix-{slug} -b fix/{slug} origin/develop

BUG.md、ANALYSIS.md、テスト、修正コードなど、すべての作業はこの worktree 内でのみ行います。

---

状態の追跡 — .ways/state.json

ways/v1alpha1 state contract（正規の .ways/state.json 形式、schemaVersion 2）に従ってください。これは、ways add がプロジェクトに追加する常時有効な state-contract ルールとして提供されるため、すでにコンテキストに含まれています（たどるパスはありません）。このリポジトリ内のメンテナー向けのソースは ways/rulepacks/state-contract/ です。このスキル内でスキーマをコピーしたり、独自に作成したりしないでください。

フロー固有の値：

• flow: bug
• way: incu/bugs · discipline: development（任意で way マニフェストの wayVersion）
• ブランチパターン：fix/{slug}
• 初期 phase：discovery
• isolationType：Phase 0 で選択した分離方法に応じて branch または worktree
• ドキュメント：docs/bugs/{slug}/BUG.md、docs/bugs/{slug}/ANALYSIS.md、docs/bugs/{slug}/FIX_PLAN.md
• ゲート：fix-plan、pr

セッション開始時に、.ways/state.json が存在する場合は読み込んでください。その branch が現在の fix/{slug} ブランチと一致する場合は、現在のフェーズ／次のステップ／保留中のゲートを報告し、その状態から再開してください。ファイルが存在しない場合、または存在していてもその branch が一致しない場合（マージ済みの項目から引き継がれた古いファイル）は、Phase 0 から開始し、選択した分離設定の直後に .ways/state.json を作成または上書きしてください。フェーズを切り替えるたびに、退出するフェーズを lastPhase にも更新してください。

更新ポイント（フェーズ → 書き込む内容）：

タイミング	phase	ドキュメント／ゲート／ステップ
BUG.md の記述完了	document	BUG.md → approved
ANALYSIS.md の記述完了	analysis	ANALYSIS.md → approved
再現テストの追加（失敗）	reproduction	—
FIX_PLAN.md のドラフト作成	fix-plan	FIX_PLAN.md → in-review
ゲート通過（修正計画）	implementation	FIX_PLAN.md → approved；ゲート fix-plan → passed；修正計画から steps を生成し、実行可能な変更ごとに 1 つの項目を作成して、すべて todo にする
実装中	implementation	各ステップを in-progress → done（または blocked）に更新します。フェーズの最後にまとめてではなく、ステップごとに直ちに状態ファイルへ書き込んでください
検証	validation	—
fix→develop の PR を作成	pr	ゲート pr → 引き続き pending；その url に PR のリンクを設定
PR をマージ	done	ゲート pr → passed

.ways/state.json は自分でコミットせず、書き込みのみ行ってください。ユーザーがチェックポイントの保存を希望した場合は、その時点のドキュメント／コードと一緒にコミットする incu-way-prepare-pr の実行を提案してください。

---

フェーズ 1 — バグの記録

保存先：

docs/bugs/{bug-slug}/BUG.md

スラッグの形式： {zero-padded-id}-{kebab-description} 例：001-import-totals-zero、002-contact-dedup-missing

次の ID の確認 — このチェックアウトだけでなく、すでに使用されている可能性がある場所をすべて確認してください。 現在のブランチだけを見るカウンターでは、2 件のバグを並行して作業したり、同じベースから派生した 2 つのワークツリー／ブランチがそれぞれ独立して同じ「次の」番号を算出したりした瞬間に衝突します。これは実際に発生しています（PRD でも同様でした。同じ形式のカウンターはここでも同じ失敗を招きます）。スキャンだけでは防げません。2 つのエージェントが同時にスキャンし、同じ番号を算出してから、それぞれのディレクトリを作成する可能性があります。同じマシン上でこれが起きないよう、スキャンから予約までの間はロックを保持してください。

0. 何かをスキャンする前に、同じマシン上のロックを取得します。

   LOCK="$(git rev-parse --git-common-dir)/incu-way-bug-slug.lock"
   until mkdir "$LOCK" 2>/dev/null; do sleep 0.2; done
   trap 'rmdir "$LOCK"' EXIT
   

   mkdir は一度に 1 つのプロセスだけが成功し、--git-common-dir はこのリポジトリのすべてのワークツリーで同じ共有パスを解決するため、ロックはワークツリー間で共有されます。docs/bugs/ は独自の ID 空間であり、docs/prds/／docs/requirements/ と共有されないため、incu-way-development／incu-way-po とは別のロック名を使用してください。
1. このチェックアウトの docs/bugs/ ですでに使用されている ID を一覧表示します。
2. このリポジトリのほかのすべてのワークツリーを一覧表示し（git worktree list）、それらの docs/bugs/ も確認します。別のワークツリーのバグ文書は、ここで git status を実行しても表示されませんが、ディスク上には存在します。
3. デフォルトブランチを取得し（git fetch origin {default}）、そこにすでにマージされている項目を一覧表示します（git ls-tree --name-only origin/{default} -- docs/bugs/）。このブランチの作成後に別の人がマージした ID は、まだローカルのツリーにはありません。

3 つすべてから見つかった ID のうち、最も大きい ID の 1 つ次を選び、ロックを解除する前にただちに docs/bugs/{id}-{slug}/ を作成します（空のプレースホルダーファイルだけでも予約できます）。その後にのみロックを解除してください（上記の trap が失敗時も含めて自動的に処理します）。同じマシン上での競合を実際に防ぐのは、スキャンだけではなく、ロックを保持したまま行うこの予約です。

BUG.md の構成

# Bug — {Short Description}

## Status
Reported | Analyzing | Fix Planned | Fixing | Fixed

## Description
What is happening vs. what should happen.

## Steps to reproduce
1.
2.

## Expected behavior

## Actual behavior

## Context
- Environment: local / staging / production
- Affected commit / version:
- Affected users or records:
- Severity: Low / Medium / High / Critical

## Logs / stack trace

---

フェーズ 2 — 分析

保存先：

docs/bugs/{bug-slug}/ANALYSIS.md

ANALYSIS.md の構成

# Analysis — {Bug Description}

## Root cause
What is the actual underlying cause.

## Affected code
Files, functions, or modules involved.

## Impact
How many users/records affected. Any data integrity risk.

## Reproduction path
How to reliably trigger the bug.

分析と再現の証拠で裏付けられるまでは、推測される根本原因を確定事項として扱わないでください。

---

フェーズ 3 — 再現テスト

修正コードを書く前に、バグが原因で失敗するテストを書いてください。

1. 壊れている動作を検証するユニットテストまたは e2e テストを書きます。
2. 実行します。現在のコードベースで失敗しなければなりません。
3. コミットするために incu-way-prepare-pr の実行を提案します（test(fix-{slug}): add reproduction test for {bug description}）。自分でコミットしてはいけません。

pnpm test  # Must FAIL — confirms the bug is reproduced

再現テストが成功するようになることが、「修正済み」の定義です。

バグをテストで再現できない場合は、その理由を ANALYSIS.md に記録し、先に進む前にユーザーに伝えてください。

再現フェーズに修正を紛れ込ませてはいけません。ここでの目的は、現在の動作に問題があることを証明することです。

---

フェーズ 4 — 修正計画

保存先：

docs/bugs/{bug-slug}/FIX_PLAN.md

FIX_PLAN.md の構成

# Fix Plan — {Bug Description}

## Branch / worktree
Branch: fix/{slug}
Isolation mode: current checkout branch | separate worktree

## Root cause (one line)

## Fix approach
What will be changed and why.

## Files affected

## Risks / side effects
Could this fix break anything else?

## Rollback
How to revert if the fix introduces a regression.

ゲート — 修正計画の確認

修正計画を書いた後：

• 次のように伝えます：「修正計画を docs/bugs/{slug}/FIX_PLAN.md に用意しました。コーディングを始める前に確認してください。」
• 停止します。ユーザーが OK と言うまで、修正コードを書いてはいけません。

---

フェーズ 5 — 実装

ユーザーが修正計画を承認した後：

ルール

• 修正計画に記載された内容だけを修正します。追加のクリーンアップは行いません。
• 各チェックポイントで pnpm typecheck && pnpm lint && pnpm test を実行し、その後、コミットのために incu-way-prepare-pr の実行を提案します。自分でコミットしてはいけません。
• フェーズ 3 の再現テストは、修正後に成功しなければなりません。
• 既存のテストにリグレッションがないこと。

推奨コミット形式（incu-way-prepare-pr で使用）

fix({slug}): {short description}

- Root cause: {one line}
- Tests: {what covers the fix}

---

フェーズ 6 — 検証

PR を開く前のチェックリスト：

• フェーズ 3 の再現テストが成功する
• 既存のすべてのテストが成功する（pnpm test、pnpm test:e2e）
• pnpm typecheck が終了コード 0 で終了する
• pnpm lint が終了コード 0 で終了する
• pnpm build が成功する
• 既存のテストにリグレッションがない
• BUG.md のステータスが Fixed に更新されている
• Snyk のコードスキャンに問題がない（新たな問題なし）
• Snyk の依存関係スキャンに問題がない（新たな問題なし）
• SonarQube スキャンに問題がない（新たな問題なし）

セキュリティスキャン

開発スキルと同じ手順です。選択した作業場所に対して、3 つすべてのスキャンを実行してください。この修正のコミットで発生した問題はすべて修正してください。

Snyk SAST:

snyk_code_scan: path=<absolute path to the selected working location>, severity_threshold=low

Snyk SCA:

snyk_sca_scan: path=<absolute path to the selected working location>, severity_threshold=low, all_projects=true

SonarQube:

bash run-sonar.sh

snyk_code_scan、snyk_sca_scan、または run-sonar.sh を利用できない場合は、不足しているツールを docs/bugs/{slug}/ANALYSIS.md に記録し、失敗したコマンドまたはツール名を正確に記載したうえで、インストール／設定するか、利用可能な検証のみで続行するかをユーザーに確認してください。スキャンを実行していない場合、問題がないと報告してはいけません。

修正ループ：問題に対処する → pnpm typecheck && pnpm lint && pnpm test → コミットのために incu-way-prepare-pr の利用を提案する → 再スキャンする → 問題がなくなるまで繰り返す。

---

フェーズ 7 — PR

検証に合格したら、fix/{slug} をプッシュして PR を開くために incu-way-prepare-pr を呼び出すよう提案してください。自分でプッシュしたり、gh pr create を実行したりしてはいけません。

incu-way-prepare-pr で使用する PR のタイトル／本文案：

Title: fix({slug}): {short description}

PR の本文には次の内容を含めてください：

• バグ： docs/bugs/{slug}/BUG.md へのリンク
• 根本原因： 1 行で記載
• 修正： 変更内容とその理由を簡潔に記載
• テスト： 再現テスト名と、追加したその他のカバレッジ
• チェックリスト： typecheck ✅ lint ✅ tests ✅ build ✅ snyk-code ✅ snyk-deps ✅ sonarqube ✅

PR を開いたら、PR の URL をユーザーに共有してください。停止してください。ユーザーの承認を得るまでマージしてはいけません。

---

バグごとのファイル構成

docs/bugs/{bug-slug}/
  BUG.md          # Bug report (Phase 1)
  ANALYSIS.md     # Root cause analysis (Phase 2)
  FIX_PLAN.md     # Fix approach + gate (Phase 4)

---

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	完了まで待つ条件
1	修正計画を作成	"docs/bugs/{slug}/FIX_PLAN.md に修正計画を用意しました。レビューしてください。"	ユーザーが OK と言う
2	検証に合格	PR の修正を fix→develop で行うため、incu-way-prepare-pr の利用を提案する。ユーザーが実行したら URL を共有する	ユーザーが PR を承認する

---

してはいけないこと

• ユーザーが修正計画を承認する前に、修正コードを書かないでください。
• 計画に記載された範囲を超えて修正しないでください。追加の改善は機能ブランチで行ってください。
• 再現テストを省略しないでください。バグを再現できない場合は、その旨を ANALYSIS.md に記載して確認してください。
• ドキュメント、分析、テスト、またはユーザーへの確認による根拠なしに、期待される動作、根本原因、または正しい修正を推測しないでください。
• 不完全なバグ報告を、確実な修正計画に仕立てないでください。まず不足している詳細を明らかにしてください。
• 完了を宣言する前に pnpm typecheck && pnpm lint && pnpm test を省略しないでください。
• 直接マージしてはいけません。必ず PR を経由してください。
• develop や main を直接操作してはいけません。ユーザーが選択した分離モードを使用してください。