Markdownとgrepだけで改修案件のバックログを「いつでも引き継げる」状態に保つ

概要

レガシーシステムの移行・改修案件では、専用の課題管理ツールを導入する前に「課題が発散して全体像を誰も把握できない」状態に陥りがちです。特に複数リポジトリ（submodule 込み）にまたがると、「これは直したはず」「まだマージされていない」という認識のズレが日常化します。

この記事では、専用ツールを使わず リポジトリ内の Markdown 1枚（backlog）+ git + grep だけで、次を成立させる運用を紹介します。

• 課題の状態が一目で分かる
• 進捗を機械的に集計できる
• いつ引き継いでも「次に何をすれば動くか」が分かる

言語・フレームワーク非依存の手法なので、そのまま流用できます。

発生した問題

改修を進める中で、次の「認識のズレ」が繰り返し起きていました。

1. 完了漏れ：コード上は直っているのに、backlog では「未対応」のまま放置される
2. 古い記述の残存：調査当時は正しかった記述が、コードの変化で誤りになっている（例：「参照は0件」と書いたが、実際は別経路で参照されていた）
3. 優先度の思い込み：「危なそう」という印象だけで優先度＝高にした項目が、実測すると発火しない／そもそも到達不可だった
4. 引き継げない：残件リストはあるが、「何をすれば動くのか」が本人の頭の中にしかない

個々は小さなミスでも、積み重なると「backlog が信用できない → 毎回コードを読み直す」という最悪のループに陥ります。

原因

根本原因は、backlog（ドキュメント）とコードが独立に動いてしまうことです。コードは PR とマージで進み、backlog は人の手で更新される。両者を突き合わせる仕組みがなければ、必ず乖離します。

ドキュメントを正本（source of truth）として扱うなら、正本を定期的にコードと照合する工程を運用に組み込む必要があります。

対応方法

1. 状態を「行頭マーカー」で表現する

各課題の見出し先頭に、状態を表すマーカーを1文字付けます。ルールは必ず明文化します。

マーカー	意味
★	新規起票（未着手）
⭐	実測で確認済みの事実
⚠️	訂正・注意（過去の記述を修正）
✅	完了（マージ済み）
⏸	保留（判断待ち・依存待ち）
❌	対応不要と結論

マーカーを行頭に固定することで、後述の grep 集計がそのまま効きます。

## ✅F-11 リストAPIの権限チェックを是正
- PR #120 マージ済み・submodule 参照を更新
- 確認方法: dev 環境で他テナントのIDを指定し 403 を確認

## ★F-31 空応答が 200 [] に化ける経路の調査
- 外部連携層が空応答を HTTP 200 の `[]` に変換している疑い
- 未着手

2. 進捗を grep で機械集計する

行頭マーカーが統一されていれば、進捗は grep で数えられます。「件数コマンド」を Makefile などに固定しておきます。

grep -oE '^## (★|⭐|⚠️|✅|⏸|❌)' docs/backlog.md \
  | sed -E 's/^## //' \
  | sort | uniq -c | sort -rn

出力例：

  18 ✅
   9 ★
   4 ⏸
   2 ⚠️
   1 ❌

表計算ソフトを開かずに、毎回同じ基準で「完了／残／保留」の比率を言えるのが効きます。

3. 定期的に「棚卸し」する（コードと突合）

ここが本命です。週次など区切りで、全項目をコードと照合する工程を入れます。

• backlog で「未対応」だがコード上は直っている → ✅ に更新
• 「参照0件」など断定した記述 → 実際に grep し直して検証、誤っていれば ⚠️ で訂正
• 印象で高くした優先度 → 実測で「発火しない／到達不可」なら格下げ

# 「参照は0件」と書いた対象を、コード全体で数え直す
grep -rn "targetSymbol" --include=*.php src/ | wc -l

棚卸しは git のコミットメッセージにも残し、「いつ・何を是正したか」を追えるようにします。

[docs] backlog 全件をコードと突合し棚卸し: 完了漏れを回収・件数コマンドを是正・新規項目を起票

4. 優先度は「印象」でなく「実測」で決める

移行案件では「認証方式と標準の権限チェックが二重にかかっている」など、危なそうに見える構造がよく見つかります。しかし実際に叩いてみるとそのコードパスに到達しないことも多い。

• 「発火しないことを実測」→ 優先度 中→低
• 「現状は到達不可」→ 優先度 高→中

優先度を動かすたびに「なぜ動かしたか（実測結果）」を1行残せば、将来の自分や引き継ぎ相手が判断を再現できます。

5. 引き継ぎ資料は「残件の分類」＋「次に何をすれば動くか」

引き継ぎで最も価値があるのは残件リストそのものではなく、「次の一手」です。

## 引き継ぎメモ（残件の分類）

### すぐ着手できる（依存なし）
- F-31 空応答の 200 [] 化: 外部連携層の変換箇所を特定 → 空配列と「該当なし」を区別

### 確認待ち（先方判断が必要）
- F-78 保留項目: 仕様の是非を先方に確認（質問文は送れる形で用意済み）

### 保留（依存先の完了待ち）
- F-38 段3: 共有モデルのスキーマ確定後に着手

実装例：確認待ちを「そのまま送れる形」で溜める

確認待ち項目は、質問文と実測値をセットにして1箇所に集約すると、先方への連絡がコピペで済みます。

## 確認待ち（そのまま送れる形）

1. リストAPIは削除済みレコードを含めますか？
   - 実測: 現状は論理削除フラグを見ておらず全件返しています
2. 空応答のときのステータスは 200 と 404 のどちらを期待しますか？
   - 実測: 現在は 200 + `[]` を返しています

確認方法

1. 件数コマンドの合計が全項目数と一致する（マーカー付け漏れがない）
2. 直近の「棚卸しコミット」から一定期間以上空いていない
3. 任意の残件を1つ選び、「次にやること」がそのまま着手できる粒度になっている

注意点

• マーカーの表記ゆれは集計を壊す。全角／半角や絵文字のバリエーションを混ぜず、規約を1箇所に明文化する
• 完了は必ずマージ済みの証跡（PR番号・commit）とセットにする。「直したつもり」を✅にしない
• submodule 参照の更新も1コミットとして残す。親リポジトリがどの時点の子を指すかが後で効いてくる
• チケット数が数百規模になれば専用ツールへの移行を検討する。本手法は「専用ツールを立てるまでもない／立てられない現場」の即効策

まとめ

• ドキュメントを正本にするなら、正本をコードと突合する工程を運用に組み込む
• 状態は行頭マーカーで表し、grep で機械集計する
• 優先度は実測で動かし、動かした理由を1行残す
• 引き継ぎの価値は残件リストではなく「次に何をすれば動くか」
• Markdown 1枚 + git + grep で「いつでも引き継げる」状態は作れる