pdlc-skills は進捗・変更の影響・品質の傾向をどう見せるのか

前回は品質の鎖について書きました。今回は見えることの話です。AI は午後のあいだに三つの機能を進めます。いまどこまで進んだのか、ここを直すと何に波及するのか、この期間はどうだったのか。それが見えなければ、自動化はブラックボックスの中で回っているのと同じです。pdlc にはこのための道具が三つあります。ステータスラインと /pdlc-status、/pdlc-relate、/pdlc-retro で、それぞれ「いま」「変更の前」「月ごと」という三つの時間軸を受け持ちます。

三つの道具、一つのデータ源

三つに共通しているのは、docs/.pdlc-state/ 配下の状態ファイルしか読まないことです。ドキュメント本文は解析しませんし、推測もしません。第 3 回で、三つの層は同じスコアボードを介して連動していると書きました。この三つの道具が読むのもそのスコアボードで、違うのは答える問いだけです。ステータスラインと /pdlc-status は「いまどこか」、impact は「ここを変えると何に及ぶか」、retro は「この期間はどうだったか」に答えます。

三つの道具は同じ状態ディレクトリを読み、三つの時間軸の問いに答える：ステータスラインはいまの位置、impact は変更前の影響範囲、retro は月ごとの傾向

状態ファイルが正確に書かれているかどうかで、これらが見せるものが本当かどうかが決まります。この点は最後に戻ってきます。

いまどこか：ステータスラインと /pdlc-status

まず、実際のプロジェクトのステータスラインの一行です（段階のラベルは訳してあります。現行版は中国語で表示します）。

● PDLC console-p3 · PRD·設計·TDD·実装·[レビュー]·リリース · →リリース · 🤖 · ✓unit ✓lint ✓cov · ⏱9d

左から順に、機能名、六段階（PRD・設計・TDD・実装・レビュー・リリース）のトラックと現在位置、次のステップ、実行モード（🤖 自律ループ、👤 手動）、三つのチェック結果、現在の段階に留まっている時間です。

ステータスライン一行の六つの項目：機能名、六段階のトラック、次のステップ、実行モード、チェック結果、滞留時間。下は blocked のときの行全体の書式

この一行には、設計上の判断が三つ入っています。

「6 段階中の 4 段階目」とは表示しません。バグ修正は六段階を全部通らないので、数字は誤解を招きます。固定のトラックを出して現在位置を強調する形にしました。
三つのチェック結果は、自律モードのときだけ既定で表示します。手動モードでは自分でテストを回しているので、表示してもノイズです。価値があるのは無人で回しているとき、ループが健全かどうかを一目で確認できることです。
blocked になると行全体の書式が変わります：⛔ PDLC xxx blocked: プロダクト判断が必要 · ⏱12m。ループが止まって人の判断を待っているとき、それが最初に目に入らなければなりません。これがステータスラインの一番の仕事です。

有効化はコマンド一つ、/pdlc-settings statusline です。既存のステータスラインのコマンドの後ろに追記され、元の設定には触りません。/pdlc-status は同じデータのコマンド版で、進行中・完了・やることの提案の三つを出し、関係インデックスがあれば関係ツリーも付けます。並べるだけでなく、確かめにいきます。三つの機能が「レビュー完了、未リリース」のまま 10 日以上止まっていたとき、CHANGELOG と git tag を見にいって、本当にリリースされていないことを確認しました。--stale 3 を付けると、各機能が何日止まっているかを表にします。

道具の仕事は、問題を目の前に出すところまでです。その先どうするかは人が決めます。

ここを変えると何に及ぶか：関係グラフ

機能同士のどれがどれを拡張し、依存し、置き換えるのか。関係は六種類あります。方向を持つものが四つ、拡張（extends）、依存（depends_on）、置き換え（supersedes）、解決（resolves）。対称なものが二つ、競合（conflicts_with）、関連（relates_to）です。手で記入はしません。/pdlc-feature が機能 ID を割り当てるときに既存の機能を走査し、/pdlc-prd が要件文の「〜を基に」「拡張」「依存」「置き換え」といった語を拾って、見つけた関係を理由付きで PRD と状態ファイルに書き込みます。実際のプロジェクトを例にすると、三つのイテレーションがあり、第 2 期と第 3 期はどちらも第 1 期を extends し、第 1 期は最初の MVP を extends しています。

rebuild を一度回すと、状態ファイルを走査してノードとエッジのインデックスを作り、mermaid のグラフも出します。MVP は pdlc 導入前に完成していて状態ファイルがありませんが、「宙に浮いた参照」として弾かず、履歴上の終端ノードとして残しました。

例のプロジェクトの関係グラフ：第 2 期と第 3 期は第 1 期を extends し、第 1 期は MVP を extends する。第 1 期に impact をかけると、赤が直接の下流、緑が履歴ノード

impact こそが関係グラフの存在理由です。第 1 期に対して実行すると、出力は三層に分かれます。🔴 直接の影響（第 2 期、第 3 期）、🟡 間接の影響（一段先。今回はなし）、🟢 履歴（MVP、監査用のみ）。提案も付きます。第 1 期はレビュー済みの機能二つに extends されているので、変更するなら第 1 期を supersedes する新しい機能を立てるべきで、その場で書き換えてはいけない。下流のレビュー結果が無効になるからです。

残りのサブコマンドです。query は一つの機能の出入りのエッジを表示し、orphans は関係を一つも持たない機能を探し、validate は五つの規則、宙に浮いた参照、自己参照、循環、矛盾する組、対称関係が両側に記録されているか、を検査します。set だけが状態ファイルに書き込みます。対称関係を一つ追加すると両側のファイルにそれぞれ一行ずつ入り、インデックスが再構築されます。

この期間はどうだったか：ふりかえり

/pdlc-retro は既定で直近 30 日を見て、状態ファイルの履歴をレポートに集計します。納品数、段階ごとのセルフチェック通過率、所要時間の中央値、詰まった箇所。docs/07_reviews/retro/ 配下に月ごとのファイルとして書き出します。

実際に一度回したときの通過率は、要件・設計・TDD の三段階が 100%、実装が 93.8%、レビューが 54.9% でした。分母はセルフチェックの項目数、分子は「通過」と判定された項目です。レビューで通らなかった四割強は、人の判断待ちとして印を付けた項目で、機能あたり 7 件ほどです。

例のプロジェクトのふりかえり：五段階のセルフチェック通過率と所要時間の中央値。人の介入はレビューに集中している

この数字は妥当です。前の四段階で機械が判定できるものは判定し尽くし、判定できないものをレビューに残す。レビューの「通過率」が低いのは、前の段階が仕事をした証拠です。レビューまで 100% だったら、むしろ本当に見たのかを疑います。

所要時間の中央値は、要件 0.0 時間、設計 0.1、TDD 0.6、実装 0.9、レビュー 5.0 です。レビューの 5 時間は割り引いて読む必要があります。レビューに入ってから完了するまでの壁時計の時間で、誰も作業していない夜間も含まれ、正味の作業時間ではありません。

不正なデータの扱いも書いておきます。ある機能で、レビューの完了時刻が実装の完了時刻より前になっていました。タイムスタンプの逆転です。レポートは負の値を出してごまかさず、そのサンプルを除外して「データ異常、書き込みのタイミングを確認」と別立てで記載しました。時間窓を直近 7 日にして再実行すると、窓の中に活動が一つもなく、四つの節すべてが「データなし」と書き、理由を添えました。前回の見せかけのグリーンと同じ規律です。判定できないなら判定できないと書き、緑で塗らない。

限界：記録されたものしか見せない

三つの道具は状態ファイルを読むだけで、コードを確認しにはいきません。状態ファイルは各段階の終わりに AI が書くもので、ずれます。ずれても道具はエラーを出さず、一項目少なく表示したり、一段階少なく数えたりするだけです。例のプロジェクトにも二か所ありました。チェックのキー名は、古い機能では tests_green、新しい機能で初めて規約どおりの tests_pass になっていて、ステータスラインは規約のキーしか読まないため、古い機能のチェック結果は表示されません。履歴に開始時刻がなく、所要時間は隣り合う完了時刻の差でしか計算できません。関係も同じで、立ち上げ時に一度自動で記録されるだけなので、あとで要件が変わったら自分で set します。

つまり三つの道具の前提は、状態ファイルをデータとして維持することです。フィールド、タイムスタンプ、関係を規約どおりに書く。

見えるようになった後で

冒頭の問いに戻ります。AI が午後のあいだに三つの機能を進めるとき、人はどう追いつくのか。三つの道具はそれぞれ一つの問いに答えます。いまどこか、ここを変えると何に及ぶか、この期間はどうだったか。答えはどれも同じ状態ファイルから読み出され、ドキュメントを掘り返す必要も、推測する必要もありません。道具は決めてくれません。止まっている機能を進めるか、ベースラインに手を入れるか、レビューが人に残した項目をどう割り振るか。決めるのは人ですが、決めるときに手元にデータがあります。ステータスラインの項目が一つ欠けていたら、ふりかえりに段階が一つ足りなかったら、まず記録を疑い、それから道具を疑ってください。

次回

三つの道具を説明し終えて、仕組みの話はここまでです。次回は実際のプロジェクトに戻り、最初のコマンドから最後のリリースまでを通して歩き、導入した後にこれがどう使われるのかを見ます。

試してみる：

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

リポジトリはこちら：https://github.com/kanfu-panda/pdlc-skills

役に立ったら star をいただけると励みになります ⭐

あなたのプロジェクトで、いちばん長く誰も触っていない機能は何日止まっていますか。コメント欄で聞かせてください。