最初の機能を通したあと、すぐ次の問題にぶつかります。各ステージごとに止まってこちらの承認を待つので、結局は画面の前に張りついたままです。一周ずつ自分で進めてもらい、その間こちらは別の作業をする——それはできるのか。 できます。ただし「自分で走る」と「一歩ごとに振り返って訊く」の差は、見た目より大きいものでした。

あのとき回っていたのは loop ではなかった

自分のマシンで完全な loop を回したことがあります。とても順調で、60 本あまりの PR を一気に片づけるあいだ、一度もこちらに訊いてきませんでした。だから別のマシンで回し直したとき、ほとんど即座に違和感がありました。

そのときは AI に同じセッションの中で「各ステージを自分でループして進める」ようお願いしていました。確かに前へは進むのですが、一歩ごとにこちらへ戻ってきます。この設計でいいですか。次に進めますか。続けましょうか。

そのとき私が言ったのは、だいたいこういうことです。この loop、前に使っていたものと何か違いませんか。普通の loop はこういう無駄なことを訊き返さず、仕事が終わるまで走り続けます。

問題は訊くこと自体ではなく、訊いてくる内容がすべて決着済みだという点です。PRD も決まり、設計も決まり、テストの書き方も決まっている。それでも確認しに戻ってくる。この種の確認は私を椅子に縛りつけるだけです。次に呼び戻されるのが三分後なのか三十分後なのか分からないので、ほかの作業に移れません。

表面上はループしていますが、実際には私が伴走させられていただけです。

これではっきりしました。偽の loop と本物の loop を分ける線は一本だけ——ループの制御権を誰が握っているか。

モデルが賢いかどうかは関係ありません。プロンプトに「自律的に完了させ、中断しないでください」と書いたかどうかも関係ありません。制御権がモデルの意思の側にあれば偽物、コードの側にあって初めて本物です。

機能一つなら、コマンド一本で足ります

先に譲れない前提から。PRD と設計は人が通し切ること。設計が確定してからでなければ loop に入れません。

ループが速くするのは TDD → 実装 → レビュー という収束の区間であって、「何を作るのかを考え切る」ところではありません。この機能をやるべきか、境界をどこに引くか、いくつに分けるか——どれも判断であって、終了コードを返してくれるコマンドは存在しません。

そこを通したあとは、コマンド一本で済みます。

/pdlc-loop-run F20260825-XXXXXX

その機能が今止まっているステージから始めて、tdd → implement → review を自動で進め、レビュー完了に達するか、詰まって停止するまで走ります。各ステージは新しい subagent に渡され、戻ってきたら状態機械を読んで、進めるか・止めるか・人に返すかを決めます。既定の上限は 4 ステップです。

前提として、前回の test-commands.yml が設定済みであること。 停止判断は実際にコマンドを走らせた終了コードに依っているので、あのファイルがなければ走らせるコマンドもありません。前回のあの一歩を飛ばすと、ここで書いていることはすべて空回りになります。

このコマンドが肩代わりしてくれるのは、最初に手作業で試して失敗した、まさにその部分です。「もう一周やるかどうか」の決定を、モデルの手から取り上げる。 それを三つの設計が支えています。

一つめ、制御フローはコードにあり、モデルの頭の中にはない。 各周でモデルに訊くのは二つだけです。次はどのコマンドか、そしてその一歩を終わらせること。前者の答えはさらにホワイトリストを通り、五つの語しか認められません。一文字でも説明が混じれば濾し取られます。モデルが余計なことを言っても意味がありません。下流がそれを読まないからです。

二つめ、各ステージはクリーンなコンテキストから始まる。 前のステージの迷い、誤解、自分で引き込んだ脱線は、次のステージへ持ち越されません。ステージをまたいで残す必要のあるものは、すべてディスク上の状態機械ファイルにあります——第 3 回で扱ったあのファイルです。セッションは死んでも、状態は失われません。

三つめ、停止判断はファイルを読む。モデルの言い分は読まない。 一歩終わるごとに、ループは「通ったと思いますか」とは訊かず、last_phase_result.ok を読みます。実際にコマンドを走らせた結果がディスクに落ちたものです。第 3 回のあの二つの枠のうち、停止判断が使うのは実行結果だけを入れる方の枠です。

機能が十数個になって、はじめて外部スクリプトの出番です

/pdlc-loop-run はプラグイン内で走るので、機能一つの短い収束に向いています。自分で bash のループを書くこともできます——各周が本当に独立したプロセスになるぶんコンテキストの隔離は厳密で、長時間の実行にも強い——けれどもそのやり方で機能点を一つ回すだけなら、あまり意味がありません。/pdlc-loop-run と同じ仕事を、プロセス境界だけ変えてやっているからです。

スクリプトの本当の居場所は一段外側です。第 3 回で二段構造を描きました。作業を N 個の比較的独立した機能点に分け、外側が機能点ごとにループを一本ずつ、それぞれ自分の worktree で起こす。外側がやるのはループの起動・結果の回収・次バッチの投入であって、個々の機能のステージを進めることではありません。今回はその外側をどう並べるかを補います——依存関係でバッチに分ける、です。

以前のあるプロジェクトは機能点が十数個あり、三つのバッチに分けました。まず土台、次にほかから依存されている機能、最後に互いに無関係な独立機能をまとめて全部。 各バッチの中は並列で走らせ、一バッチ終わるごとに人が確認し、それから次のバッチを起動して、順に全体を収束させていきます。

順序は逆にできません。土台が立っていなければ後ろはすべて砂上の楼閣ですし、依存されている側が終わらなければ、依存する側はただ待つだけです。最後のバッチは誰も待たないので、まとめて全部開くのがいちばん効率的です——機能 ID が「日付＋時分秒」なのはもともと並列のためで、同時に走らせても衝突しません。

はっきりさせておくと、このバッチ編成の層は私が自分で組んだもので、pdlc が用意しているものではありません。 pdlc が与えるのは「機能点一つがどう自力で走り切るか」と、/pdlc-relate の依存グラフで誰が誰に依存しているかを見えるようにすることです。どう分けるか、一バッチに何個入れるかは、依然として判断であり、依然としてループの外側にあります。

四つのガードレール、どれも実際に効く場面を見ています

ガードレールを文書に書くだけなら誰にでもできます。見るべきなのは、それが実際に作動したことがあるかどうかです。

① ハード予算：各周の --max-budget-usd

各周のプロセスに上限を置き、使い切ったらプロセスごと打ち切られます。交渉の余地はありません。これは外部スクリプト形態では必須の設定です。

これは一度の実行で二回作動しました。 最初の周は上限を 5 にしていて、実装の途中で断ち切られました。ディスク上の作りかけを確認し、続きから再開できると分かったので上限を 8 に上げて再実行——また上限に当たり、最終的に 12 で走り切りました。

断ち切られた瞬間について言うべきことは一つです。ディスク上のものは無傷でした。 ドキュメントは書き出され、状態機械には記録が残り、失ったのは「この周が終わらなかった」ことだけで、「全部やり直し」ではありません。ディスクへ書き出すことと記録を残すことが、乱暴なプロセス停止を、続きから再開できる中断に変えています。

数字が誤解されないように一つ断っておきます。5・8・12 は私が各周に設定した上限であって、実際に支払った金額ではありません。 私はサブスクリプションで週あたりの量で計算される形態ですし、そもそも API の単価はベンダーごとに違います。この三つの数字は「だいたいこのくらいの規模」という目安として見てください。実際のコストを出したいなら、トークン消費量を見て、ご自身が使っているベンダーの公式価格で見積もるほうが正確です。

② と ④：ok でなければ止まる、ステップを使い切っても止まる

fail-stop が受け止めるのは、いちばん見落とされやすい種類の不良です。失敗したステージが、次の周に「完了済み」として踏み越えられるというもの。一度踏み越えられると、以降の各周は偽の前提の上に積み上がり、長く走るほど深く狂っていきます。しかも全行程が緑のままです。

ステップ上限が防ぐのは振動です。壊す→直す→また壊す、と各周が作業しているように見えて、実際はその場で足踏みしている状態。既定の 4 ステップ＝収束の三段＋予備の一段。私は一度、保守的に 1 に設定して試し、予定どおり停止しました。

③ blocked エスカレーション：止まるべきときに本当に止まりました

レビューでプロダクトの判断が要る問題が見つかると、状態機械に blocked を書き、停止して人を待ちます。

これが実際に作動した一回で、この仕組みは信用できると思えました。

レビュー中、その周で追加された三つの設定フィールドが、バックエンドのどこからも消費されていないことが見つかりました。コードは正しく、テストも緑です。これはバグではなく、プロダクトレベルの欠落でした。フィールドを削るべきなのか、それとも経路が未完成で足すべきなのか。これは AI が私の代わりに決めていい問いではありません。

推測もせず、テストを緑に保つためにフィールドをこっそり消すこともせず——blocked を書き、停止し、問いをこちらへ返してきました。私はフィールドを残して消費経路を足すと決め、続きを走らせました。再レビューでは思わぬおまけもありました。その経路実装に紛れていた本物のバグを 2 件、ついでに直していったのです。

止まるべきところで止まり、見るべきところを見た。私が欲しかったのはこれです。

この一回で何が出てきたか

対象はあるコンソール系プロジェクトの三期分の反復で、バックエンドのエンドポイント群が 4 つ、フロントエンドのページが 3 つ、それに通知ルール一式。TDD → 実装 → レビュー を最初から最後まで無人で走り切り、テストは 301 件すべて通過、カバレッジは 87% 超でした。

人が関与したのは全部で三回だけ。予算を延長するときの確認判断が二回と、blocked のときのプロダクト判断が一回です。

これは午後一回分の仕事量で、実際以上に大きく語るつもりはありません。ただ loop のあいだ、それは私に対して完全に沈黙していました。戻ってきて目にするのは「次のこれをやりますか」の列ではなく、一つの終状態です。速いことが本質ではありません。私がその場にいなくてよい、というのが本質です。

人と機械の自動化の境界

判断基準は第 2 回から変わっていません。自動でエラーを見つけられるものだけを、ループに渡す。 この線で引くと、永久に渡せないものが二つあります。

• 何を作るのかを考え切ること（人の判断が要る）。 PRD と設計は人が通すこと。これは loop に入るための前提であって、推奨事項ではありません。
• リリース。 ループの終状態はレビュー完了で、そこで止まり、出すかどうかは人が決めます。--autonomous はリリースとデプロイには一切効きません——出してしまえば取り戻せないからです。

ここまでが「どの作業を渡せるか」の線引きです。これと対になる問いがもう一つあります。渡したあと、暴走しない保証はどこから来るのか。

第 1 回でプロンプトエンジニアリングを扱ったとき、その層の天井をこう書きました。それはソフトな制約であり、モデルが完全に従うとは限らず、その場で気づけるとも限らない、と。当時はただの原則でしたが、今回それに実例が付きました。

「節約して、消費に気をつけて」とプロンプトに書くのは簡単ですが、それはプロンプト層のやり方です——導くことはできても、保証はできません。--max-budget-usd はプロセス層のやり方で、何が書かれているかを読まず、上限で切ります。今回の二度の超過は、二度とも後者に止められたのであって、前者に諭されたのではありません。

「導きはするが保証しない」ものは、最終的にどれも一段上へ移すことになります。 今回はプロセスの引数まで移りました。

次回

この記事から一つだけ持ち帰るとしたら、これにしたいと思います。loop が本物か偽物かを見分けるには、一点だけ見ればいい——制御フローがコードの側にあるのか、モデルの意思の側にあるのか。 振り返って訊いてくるループは、ループではありません。

次回は品質の話です。このパイプラインは速く、見張りも要らない。ではその産物は何を根拠に信用できるのか。テストの赤信号ゲート、レビューのゲート、カバレッジがそれぞれ何を止めていて、合わせても何を止められないのかを扱います。

試してみる：

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

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

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

この四つのガードレールは、あの実行の記録をそのまま一つずつ書き起こしたものです。断ち切られたところも、詰まったところも含めて。「なるほど、これは信用できそうだ」と思ってもらえたなら、いいねで教えてください。ご自身で loop を回したことがある方は——うまくいった話でも、こじれた話でも——コメント欄でぜひ聞かせてください。

前の三回は図面でした。三層がそれぞれ何で、どこに落ち、どう噛み合うか。今回は向きを変えます——その図面を自分のプロジェクトに落とす回です。読み終えたら、導入できて、どのコマンドから始めればいいか分かって、機能を一つ最後まで通せるはずです。途中に飛ばされがちな一手があるので、そこだけ独立して扱います。飛ばすと前回の設計が丸ごと空回りするからです。

理論の部分はだいたい話し終えました。ここからは pdlc-skills が実際のプロジェクトの中でどう回るのかを見ていきます。

多くの人がまず同じ疑問を持ちます。先にテストを揃えるべきか。ドキュメントを先に全部書くのか。二、三年動いていて、コードが積み上がっていて、誰もあまり触りたがらない古いプロジェクトを取り込むとしたら、初日から技術的負債の返済が要るのか。

先に答えを言います。どれも要りません。導入は一行、一分で終わります。

本当に詰まるのは別のところです——導入し終わったあとの「で、次は？」。私が最初のプロジェクトを取り込んだときも、/pdlc- で始まるコマンドが一画面に並んでいるのを眺めたまま、どれを打てばいいのか分からず固まりました。この記事はその「で、次は？」に答えるものです。どのコマンドから始めるのか、そして絶対に飛ばしてはいけないのはどの一手か。

導入：一行のコマンド、二つの置き場所

# グローバル：このマシンの全プロジェクトで使える
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

# プロジェクト単位：このリポジトリの中だけで効く
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --project /path/to/my-project

前の三回で出していたのはずっとグローバルのほうでした。いちばん短く、失敗しにくいからです。ここではどんなときにプロジェクト単位が効くかを書きます。

二つの違いは置き場所だけです。~/.claude/plugins/pdlc/ か、<プロジェクト>/.claude/plugins/pdlc/ か。ただしそこから来る差は実際的です——プロジェクト単位で入れると、バージョンがリポジトリについて回ります。チームの誰かが clone すれば手元と同じバージョンになりますし、複数のプロジェクトを並行して開いていても、一度のグローバル更新で全部が同時に動いてしまうことがありません。

一人、一台、プロジェクトもそう多くない——ならグローバルで十分です。悩む必要はありません。

入ったかどうかは二段階で確認します。

ls ~/.claude/plugins/pdlc/            # グローバルで入れた場合
ls <プロジェクト>/.claude/plugins/pdlc/  # プロジェクト単位で入れた場合

skills/ references/ VERSION あたりが見えていれば大丈夫です。あとは Claude Code で /pdlc- と打って、候補に 38 個のコマンドが並べば導入完了です。

あなたはどの出発点にいるか

38 個が一度に並ぶと確かに気後れしますが、最初に覚えるのは三つだけで十分です。どれを選ぶかは、いま手元に何があるかで決まります。

新規プロジェクトは /pdlc-bootstrap です。一行の説明を渡すと、技術スタックを選び、ディレクトリの骨組みとドキュメントの下書きを作ります。「X を作りたい」がまだ着想の段階のときに向いています。

既存プロジェクトが大半の人の状況で、いちばん見てほしい行でもあります。最初のコマンドは /pdlc-adopt scan。そして scan は全工程が読み取り専用です——技術スタック、サービス構成、データベース、既存テストを調べて、導入レポートとヘルスチェックを出すだけで、一バイトも書き換えません。

この設計は機能そのものより語る価値があると思っています。動いている古いコードを AI に触らせるのは、誰だって躊躇します。だから「見る」と「触る」を二つのコマンドに割りました。まず scan でレポートを出し、読んで納得してから /pdlc-adopt init でベースライン文書を生成する。試すコストがゼロになります。

ここだけは飛ばさない：先に「何をもって通ったとするか」を決める

この記事でいちばん重要な節です。

前回、状態ファイルの二つの枠の話をしました。一つ目の枠に入れてよいのは実際にコマンドを走らせて得た終了コードだけで、モデルの自己申告は二つ目の枠に切り離され、停止判定には決して関与しません。

すると疑問が出ます——その「コマンド」はどこから来るのか。

答えが /pdlc-test-setup です。やることは四つ。技術スタックの探索、コマンドが本当に走るかを一つずつ検証、docs/00_standards/test-commands.yml への書き込み、そしてテストディレクトリとローカルフックの用意。

リポジトリはこの一手の位置づけをはっきり書いています。全体の急所は「checks は終了コードしか認めず、モデルの自己申告は絶対に使わない」であり、しかしそこに至るまで、このファイルを立ち上げてくれるものは何も無い。それが無ければ客観化の経路まるごとが空になる、と。

ここには譲れない規律が一つあります。このファイルに書き込むコマンドは、必ず一度は実際に走らせ、終了コードを自分の目で見ていること。推測で書いたものは載せません。理由は、私がいちばん注目に値すると思っている一文です——

「一見正しそうだが走らない」コマンドは、空にしておくより悪い。

空なら、下流はこの段階に判定材料が無いと理解して、素直に空のままにします。走らない偽のコマンドは、各段階に偽の checks を渡し、それでもレポートは緑になります。この理屈には鏡像もあります。最も危険な「自動修復」は、いったん立っていたが壊れたチェックを黙って空にすること——ゲートはその場で緩み、こちらからは見えません。

では飛ばすとどうなるか。走らせるコマンドが無い → 一つ目の枠は規約上どうしても空 → 停止判定に根拠が無い → 「客観的な検証」だと思っていたものが、最初からずっとモデルの自己満足だった、ということになります。前回の設計の土台は、この一手にあります。

ついでに言うと、このファイルは古くなります。スクリプトの改名、ツールの世代交代、サブプロジェクトの増減で実態とずれます。張り付いて見ている必要はありません。下流の段階が「コマンドが走らない」に出くわすと知らせてくれるので、そのときに /pdlc-test-setup --refresh を回せば十分です。

最初の機能を通す

土台ができたら、着手は一言で済みます。

/pdlc-feature ログインに電話番号認証を追加

あとは PRD → 設計 → TDD → 実装 → レビューと進み、各段階で一度止まって引き継ぎます。バグ修正も同じ形で /pdlc-fix、いまどこまで来たかを見たいなら /pdlc-status。

日常はこの三つで足ります。 残りの 35 個は細かく制御したくなったとき——設計の段階だけやり直したい、コードレビューだけ一度かけたい、データベース設計を足したい——に掘りにいくものです。そのとき探せば間に合います。

ディスクに増えるもの、git に入れるべきもの

一周まわると docs/ の下に一式のディレクトリが増えます。要件、設計、テスト、デプロイ、レビューがそれぞれの位置に並び、加えて docs/.pdlc-state/ に機能ごとの JSON が一つずつ入ります。

前者は文書なので、コミットするかは好みで構いません。ただし一つだけ、必ず入れるべきものがあります。

docs/.pdlc-state/ は git にコミットしてください。.gitignore に入れてはいけません。

見た目はキャッシュそのものです。ドット始まりのディレクトリに、機械が読む JSON の束。つい素通りしたくなります。しかしこれはキャッシュではなく、引き継ぎ物です。セッションを変える、マシンを変える、人が変わって引き継ぐ——そのときに「この機能はどこまで進んで、前の段階は通ったのか」を言えるのは、これしかありません。git に入れないのは、セッションを開き直すたびに記憶を失うのと同じですし、チームでは相手からこちらの進捗が見えません。

リポジトリはこれを「プロジェクト納品の監査記録」と位置づけています。監査記録として扱えば、無視しようとは思わなくなります。

既存プロジェクトを取り込むときの二つの規律

古いコードベースから入ってきた場合、単独で知っておく価値のある規律が二つあります。この二つが、そもそも現実的かどうかを決めるからです。

一つ、文書だけを作り、コードには触らない。 取り込みの過程で業務コードは一行も変更せず、ベースライン文書を逆生成するだけです。

二つ、増分で取り込む。 既存コードはまとめて「ベースライン済み」と印を付け、新しい機能だけが完全なフローを通ります。過去の負債を先に返せとは言われません。

効いているのは二つ目です。プロセス系のツールが初日に死ぬのを何度も見てきました。取り込んだ途端に既存の違反が数百件出て、その数字を見た時点で人は諦めます。既存を囲って新規だけ管理する——それがこのフローに二日目を迎えさせる条件です。

使わないほうがいい場面

境界も書いておきます。使い捨てのスクリプト、動かして消すデモ、純粋なドキュメントリポジトリ——そこでは使わないほうがいい。プロセスのコストが回収できません。これは長く生き、引き継がれ、品質に責任を負うプロジェクトのためのものです。

判断は単純です。このプロジェクトを三か月後に開く人がいるか。 いるなら価値があり、いないなら手を出さないほうがいい。

ひと通り、そのままなぞる

ここまでを一枚のリストに畳みます。そのまま実行できます。

1. 入れる：curl … | bash -s -- --global（複数プロジェクトやチーム作業なら --project <パス> に替える）
2. 確かめる：ls ~/.claude/plugins/pdlc/、そして Claude Code で /pdlc- を打って 38 個並ぶか見る
3. 出発点を見極める：新規なら /pdlc-bootstrap、既存なら /pdlc-adopt scan でレポートを読み、納得したら /pdlc-adopt init
4. 土台を立てる：/pdlc-test-setup——ここは飛ばさない。以降の「通ったかどうか」が本物か偽物かを決める一手です
5. 着手する：/pdlc-feature 一行の要件、進捗はいつでも /pdlc-status
6. コミットする：docs/.pdlc-state/ も一緒に入れる

4 だけが「後回しにできそうで、できない」ものです。あとは順番どおりで構いません。

次回：放っておいても自分で進めるのか

導入し、始め、土台を立て、最初の機能を通す——一本の線が終わりました。この記事から一つだけ持ち帰るとしたら、これにしたいと思います。走り出す前に「何をもって通ったとするか」を決めておく。 順序が逆になると、その後の自動化はすべて空回りになります。

次回はこの連載の本命です。導入も済み、動いてもいる。では、見張っていなくても一周ずつ自分で進められるのか。 収束ループの仕組み、契約、そして譲れない四つのガードレールを扱います——口で言い聞かせても Token 消費が止まらず、最後は硬い予算に受け止めてもらった、私自身の失敗も含めて。

試してみる：

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

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

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

この記事は自分が実際にプロジェクトを取り込んだ順序どおりに書きました。詰まった箇所ほど言葉を足しています。通せたら教えてください。どこかで止まった場合もぜひ教えてください、次の版に反映します。

前回の最後に物差しを一つ置きました。あるツールの三層が本当に結合しているかは、同じ状態を共有しているかで判断できる、と。今回はそれを具体的な形にします——三層は最初から最後まで一度も互いを呼び出していません。ディスク上の一つのファイルを介して引き継ぐだけです。さらに、当時は予想していなかった副作用もあります。そのファイルが機能ごとに分かれているおかげで、このパイプラインは縦に一本走るだけでなく、横に広げて何本も同時に走らせられます。

前回は、三層が pdlc-skills のどこに落ちているかを整理しました。全コマンドが共有するルールがプロンプト層、自動で前に進む区間が Loop 層、段階の順序と関係グラフが Graph 層です。

ただし、誰が何を担当しているかを知ることと、それらがどう組み合わさっているかを知ることは別の話です。

その流れで考えると、いちばん手っ取り早いのはコードの中で呼び出し行を探すことです。Graph はどこで Loop を呼んでいるのか、Loop はどこでプロンプト層を呼んでいるのか。しかし見つかりません——この三層が互いを参照している行は、一行も存在しないからです。

では、どうやって一緒に仕事をしているのでしょうか。

鍵は「呼び出し」ではなく「効くタイミング」

三層が互いを知らなくて済むのは、そもそも効くタイミングが重なっていないからです。

たとえるなら、Graph は入口でチケットを切り、プロンプト層は会場の中で話し、Loop は場外で残り何公演かを数えています。三人は一度も口をきいていません。頼りにしているのは同じスコアボードです。

そのスコアボードが、ディスク上のあのファイルです。

一つの機能を最後まで追いかける

抽象論はここまでにして、実際の機能を一拍ずつ追いかけます。

第一拍、始動。 新しい機能が立ち上がった直後、ディスクには何もありません。この段階で受け止められるコマンドは一つだけ——要件を書くコマンドです。なぜか。他のコマンドはすべて、自分に必要な前段のドキュメントを宣言しているからです。設計には要件が要り、テストには設計が要る。前提条件がどれ一つ満たされていません。これは「まず要件を書きましょう」という助言ではなく、前段の成果物がなければこの扉を通れないという話です。 ここで効いているのが Graph で、その仕事は「通すか通さないか」だけです。

第二拍、作業。 扉を通るとGraph は退場し、場はプロンプト層のものになります。この一回の呼び出しでモデルが見るのは、そのコマンド自身の本文だけではありません。全コマンドが共有する一式のルール——成果物は必ずディスクに落とす、引き継ぐ前に必ず自己点検する、修正は一度だけで再帰しない——も一緒に見えています。これらのルールは一か所に書かれていて、呼び出し時に展開されます。各コマンドに書き写してあるわけではありません。

出てくるものも自由作文ではありません。ファイル名、置くディレクトリ、含まれる章立てはすべて決まっていますし、ドキュメントの先頭には小さな身元情報が付きます。どの機能に属し、どの段階にいて、前のドキュメントは何か。書式そのものは今回は展開しませんが、意味するところだけ言うと、成果物が自分の座標を持ち歩いているということです。そこから遡れば最初の要件までひと続きに辿れます。

第三拍、締めのディスク書き込み。 ここがいちばん重要な一拍です。主な作業が終わっても流れは終わりではなく、コマンドはあのファイルに一行記録しなければなりません。この区間は終わった、出来はどうだった、次は誰が受け取るのか。このファイルはディスク上にあり、機能ごとに一つです。

第四拍、止めるかどうかの判定。 ここで初めてループが出てきます。しかも読むのはあのファイルだけ——コードも成果物もチャット履歴も見ません。読んだうえで一つの結果を返します。次に走らせるコマンド名か、「完了」か、「詰まった」か。外側のスクリプトはその結果を受け取って次の一本を走らせ、走り終えるとまた第三拍に戻ります。

レビュー完了まで来るとループは停止し、「完了」を出して人を待ちます。リリースとデプロイは決してループの中に入りません——一度出したら引き戻せませんし、影響するのは本番の実ユーザーだからです。

つまり、この鎖の上で本当の引き継ぎは三か所しかなく、そこを渡っていくのはいずれも関数呼び出しではなく、一つの名前です。

• Graph が呼び出しに渡すのは「担当する区間はここだ」；
• 呼び出しがディスクに渡すのは「終わった、結果はこうだ」；
• ディスクがループに渡すのは「続けるかどうか」。

三層のどれも、他のどれにも触れていません。

あのファイルで最も効いている設計

「実際に走らせて得たもの」と「モデルが自分で言っていること」は、別々の枠に入っています。

一つ目の枠に入れてよいのは、本当にコマンドを走らせて得た結果だけです。テストが通ったか、カバレッジは足りているか、lint はきれいか——すべて終了コードから翻訳された真偽値です。走らせるコマンドがそもそも無い段階（ドキュメントしか作らない要件と設計の段階）なら、そこは空のままにします。「この区間はうまくいったと思う」という理由で「通った」と書き込むことは許されません。

二つ目の枠がモデルの自己点検で、何項目が通らなかったかだけを記録します。参考情報であり、止める判定には決して関与しません。

違いはどこに出るか。ループの停止判定は一つ目の枠しか見ません。つまりモデルの自己申告は、「正直に報告してください」という一文ではなく、データ構造のレベルで停止判定の経路から外されているのです。二つ目の枠に何を書こうと、今回のラウンドが止まるかどうかは変わりません。

前回言った「三層が同じ状態を共有している」は、具体的にはこの枠のことです。

本当のループは二段構えになっている

ここで一つ認めておきます。上で描いたループは、内側のループでしかありません。

自分で実際に動かすときの形はこうです——

主管 agent：全体設計 → 互いに独立した N 個の機能に分割
    ↓
外側のスクリプト：機能ごとに一本ずつ起動
    ↓
内側のループ × N（それぞれ別の機能を担当）   ← 同時に走る
    ↓
それぞれ「レビュー完了」か「詰まった」で停止 → 人がまとめてリリースを判断

まず主管 agent が全体設計をして、やるべきことを互いに独立した複数の機能に分割します。外側のスクリプトが機能ごとに内側のループを一本ずつ起動し、それらが並行して進み、それぞれ自分の終点で止まる。最後に人が N 本の結果をまとめて見ます。

なぜ同時に走らせて大丈夫なのか。 前提として、切り出したものが相対的に独立した機能でなければなりません。互いに依存がないからこそ同時に着手できます。その前提の上で、状態ファイルも機能ごとに分かれていて、一機能一ファイル、互いに依存しません。

機能 ID は「日付＋時分秒」で、その日の連番ではありません。リポジトリに理由が明記されています——複数人あるいは複数の AI が同時に着手すると、各自が「その日の最大番号＋1」を取りにいくため必ず衝突し、同名になった状態ファイルは手作業で振り直すしかありません。作成した瞬間の時分秒にすれば、各自が勝手に動いてもまず衝突しません。この ID 形式はもともと並行のために用意したものでした。当時はきちんとした設計だと思っておらず、衝突よけの小技のつもりで入れただけでしたが。

コードの層も隔離が要ります。各機能の内側のループはそれぞれ自分の git worktree で走り、互いに干渉せず、成果物は別々の PR を通ります。

では、なぜ「分割」だけは人、あるいは主管 agent に残さなければならないのか。 前回、判断基準を一つ出しました。誤りを自動で見つけられるものはループへ、そうでないものは人へ。「この要件群をいくつの機能に割るべきか、どれとどれに依存があるか」——間違えてもどのコマンドもエラーを返しません。判断の問題であって、検証の問題ではないからです。だからループの外にあります。

二段の終点も違います。内側の終点はレビュー完了、外側の終点は「N 本すべてが収束したこと」。そしてリリースは変わらず唯一の人手のゲートです。何本同時に走らせようと、最後にボタンを押すのは人です。

このやり方は、自分のコマンドラインツールのプロジェクトで実際に走らせました。どう動かすか、ガードレールをどう設定するか、一晩走らせると何が出てくるか——それは後の回で扱います。今回は形だけを描きます。

次回：自分のプロジェクトで動かすには

この記事から一文だけ持ち帰るとしたら、これにしたいと思います。三層が噛み合うのは互いを呼び出しているからではなく、同じ一つのファイルの別々の枠に、それぞれが書き込んでいるからです。

インターフェイスは関数ではなく名前です。だから一つの層を変えても他の層に波及しませんし、だからこのパイプラインは横に何本も複製できます。

今回は意図的に踏み込みませんでした。あの状態ファイルに具体的にどんなフィールドがあるか、ループのガードレールと上限をどう決めるか、並行で走らせたあとどう畳むか——どれも後の回に回します。まず形をはっきりさせてから、部品を見る。

これで、三層とは何か、それぞれどこに落ちるか、どう噛み合うか、の三本が終わりました。次回は方向を変えます。自分のプロジェクトにどう入れるか、どう始めるか、既存のコードベースをどう取り込むか——この記事の図面から、あなたの端末で本当に走る最初の一行へ。

試してみる：

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

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

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

あの二段構えの図は自分が実際に走らせている形で、描くまでは頭の中にしかありませんでした。具体的な像が持てたなら、いいねをいただけると嬉しいです。周りに「AI に複数のことを同時にやらせたい」と考えている方がいれば、共有していただけると助かります。

三つの概念を切り分けたあとに来る、本当に面白い問いはこれです。三層が同時に揃っている実物はあるのか。この記事では、私自身が作っている pdlc-skills を一つずつ当てていきます。結論を先に言うと、噛み合っているのは偶然です。ただしその偶然には理由があり、その理由こそがこの記事の本題です。

前回は、混同されがちな三つの言葉を切り分けました。

• プロンプトエンジニアリングが扱うのは、この一回モデルにどう伝えるか；
• Loop エンジニアリングが扱うのは、同じことを何回繰り返し、どの条件で止めるか；
• Graph エンジニアリングが扱うのは、経路上のどの工程を飛ばしてはいけないか。

三者は同じ階層になく、三択でもなく、積み重ねられる三層でした。

そこで自然に出てくる問いがあります。三層とも理屈は通っているとして、三層が同時に揃っている実物はあるのか。

一つ当ててみます。私自身が作っている pdlc-skills です。

pdlc-skills とは何か

Claude Code のプラグインで、やっていることは一行で言えます。AI が書くコードを「会話の中のもの」から「ディスクに残るもの」に変える、それだけです。

入れると 38 個のスラッシュコマンドが増え、一つが工程の一段階に対応します。いちばん使うのは /pdlc-feature で、新しい機能はこれで始めます。あとは AI が PRD → 設計 → TDD → 実装 → レビュー → リリースの線に沿って進み、各段階で一度止まって引き継ぎます。

「この機能作っといて」と頼むのとの違いは三点です。

• 成果物は必ずディスクに落ちる。PRD も設計もレビュー記録も docs/ の下の実ファイルであって、チャット履歴の一節ではありません。
• 機能ごとに状態を持つ。どの段階まで来たか、前の段階は通ったか、すべてディスクに記録されます。別のセッションで再開しても、自分がどこにいるか分かります。
• テストは先に赤でなければならない。失敗するテストが無ければ実装に進めません。推奨ではなく、硬い関門です。

MIT ライセンス。Claude Code 上での対応が最も手厚く、同じ方法論はアダプタ経由で他の AI コーディングツールでも動きます。

出自はごく平凡です

この三層は私が設計したものではありません。作っていた当時、「Loop エンジニアリング」も「Graph エンジニアリング」という言葉も聞いたことがありませんでした。

ソフトウェア工学に元からある製品開発ライフサイクルを、そのままなぞっただけです。要件、設計、テスト、実装、レビュー、リリース——この流れは業界に何十年も転がっていて、新しいところは一つもありません。私がやったのは、それを AI 向けに翻訳することだけでした。各段階で何をやるのか、何を出すのか、どうなったら通過なのかを一つずつコマンドとして書き、AI が思いついた順ではなく流れに沿って進むようにしただけです。

そこに一つだけ規則を足しました。各段階は必ずディスクに何かを書く、というものです。

• PRD は docs/01_requirements/ へ
• 設計は docs/02_design/ へ
• レビュー記録は docs/07_reviews/ へ
• 機能ごとに状態ファイルも一つ

すべて普通のテキストです。いつでも開けますし、そのラウンドで AI が実際に何を触ったかを git diff で確認できます。

作り終えたあとに、この新しい言葉が流行り始めました。当てて確かめてみると、どこも噛み合っている——合わせて作ったからではなく、勝手にそう育っていたからです。

ではプロンプト、Loop、Graph の順に一層ずつ当てていきます。

🔵 プロンプト層：噛み合うのは「規約は一つだけ」

工程の中で対応するもの。 ソフトウェア工学には古い規則があります。規約書は一つだけ、あちらとこちらで別々に持たない。pdlc に当てはめると、すべてのコマンドが守るべき規則——成果物は必ず落とす、引き継ぎ前に必ず自己点検する、修復は一度だけ——を、各コマンドの中に別々に書いてはいけない、ということになります。

具体的にどうしたか。 共通規則を断片に切り出し、ビルド時に各 skill へ展開します。現在は 13 個の断片が、38 個の skill のうち 36 個にコンパイルされています（入っていない二つは pdlc-loop-next と pdlc-status。軽すぎて共有すべき規則がありません）。六つの不変条件——ファイルは必ずディスクに落とす、段階ごとに必ず記録する（history に追記する）、テストは先に赤である、自己点検は必須、修復は一度だけ、状態は必ず前進する（current_stage が実際に変わること。外側のループが古い状態のまま空回りするのを防ぐため）——は、そのうちの一つの断片に書かれています。一箇所直せば、全体に効きます。

どの層と噛み合ったか。 プロンプトエンジニアリングが扱うのは「今回モデルに何を見せるか」です。ここでやっていることはそれと変わりません。ただコードと同じやり方で管理しているだけ——共通部分を抜き出し、ビルド時に展開し、真実の源を一つにする。

新しい呼び名はプロンプトエンジニアリング、古い規則は単一の真実の源。同じことを二つの語彙で言っている——これが一つ目の偶然です。

🟢 Loop 層：噛み合うのは TDD の赤信号関門

工程の中で対応するもの。 TDD はソフトウェア工学では古株で、規則は一行です。まず失敗するテストを書き、それから実装を書き、テストが緑になるまで続ける。pdlc はこれをそのまま持ち込みました。実装の前に、赤いテストが必ず存在すること。

この規則が付随して連れてきたもの。 テストが実装より先にあるということは、「終わったのかどうか」にモデルと無関係な答えが出るということです。一度走らせて、終了コードが 0 なら通過、それ以外なら未通過。

この答えの値打ちは、モデルを経由しない点にあります。コードを書いたモデルに自分のコードを採点させると、体系的に甘くなります。騙そうとしているのではなく、本当に良く書けたと思っているからです。ですから pdlc では、モデルの自己点検結果は別枠で記録し、参考にとどめ、止まるべきかどうかの根拠には決してしません。

だからこの区間はループに渡せます。tdd → implement → review が自走し、レビューが通るまで回ります。その手前の PRD と設計は渡せません。この機能をやるべきか、いくつのモジュールに割るか、境界をどこに引くかは判断問題で、終了コードを返せるコマンドが存在しないからです。判断問題は人に残す。この線ははっきり引いてあります。

どの層と噛み合ったか。 Loop エンジニアリングには公理として使える一文があります。ループとはタスクに検証を一つ足したもの、検証のないタスクはただの願望である。TDD が与えるのは、まさにその検証です。

私が TDD をやっているのは、ソフトウェア工学が「テストを先に」と言うからであって、ループのために定規を用意したかったからではありません。それでも定規はそこに置いてあった——これが二つ目の偶然です。

ガードレール、上限、予算の決め方は第 5 回で扱います。

🟣 Graph 層：噛み合うのは段階分けとレビュー関門

工程の中で対応するもの。 ライフサイクルという言葉自体が順序を含んでいます。要件は設計の前、設計は実装の前、実装のあとにレビュー、レビューを通ってからリリース。ソフトウェア工学ではこの順序は推奨ではなく規律です。工程を飛ばした代償には、業界が何十年も授業料を払ってきました。

具体的にどうしたか。 各段階の終わりに状態をディスクへ書き、次の段階はまず状態を読み、前提条件を満たさなければ進ませない。テストを飛ばして実装しない、レビューなしでリリースしない。

縦の順序のほかに、横の層もあります。機能と機能の関係です。/pdlc-relate がそれを明示的に記録します。六種類の有向辺——拡張、依存、置換、解決、衝突、関連。そして impact <機能ID> を叩けば、変更の影響半径が一発で出ます。🔴 直接依存しているもの、🟡 一つ隔てたもの、🟢 すでに終わっていて気にしなくていいもの。

ここは正直に言っておきます。 縦のほうは厳密にはグラフではなく、関門をいくつか挟んだ線形のパイプラインです。条件分岐がなく、並列ノードもなく、任意の地点へ巻き戻すこともできません。グラフらしい性質をほぼ持っていない。本当に「グラフ」と呼べるのは横の依存関係図のほうです。向きがあり、辿れて、循環依存を検出でき、存在しない機能を指す参照も見つけられます。

どの層と噛み合ったか。 では縦はなぜ Graph 層と言えるのか。Graph 層の本質は「図に描くこと」ではなく、負の制約——どの経路を通ってはいけないかを宣言することだからです。前回の言い方をもう一度使うなら、線路は旅程を計画しません。ある方向を単に成立させなくするだけです。

段階の関門が縛るのは順序、依存図が縛るのは影響範囲。やっていることは同じです。そして「段階を追って進め、要所でレビューする」という規律は、ソフトウェア工学がとうの昔に工程へ書き込んでいました——これが三つ目の偶然です。

三度重なれば偶然ではない

一度なら偶然と言えます。三度とも噛み合うなら、理由を問うべきでしょう。

私の答えはこうです。この二つは、もともと同じ問題群を解いていた。

三大エンジニアリングは、この二年ほどの AI エージェント実践から抽出された新しい語彙です。一方ソフトウェア工学のあの流れは、何十年もかけて実プロジェクトに繰り返し叩き込まれてできたものです。そして人と AI がエンジニアリングで犯す失敗は、かなりの部分が重なっています。思いついた順に手をつける、規約を何通りも持つ、終わったと言うが検証していない、ここを直すとどこが壊れるか分からない。古い流れがこれらを治すために立てた規則は、AI に翻訳しても効きます。

つまり新しい語彙が語る制約は、古い流れが別の言葉ですでに書き残していたわけです。

これが「自然に噛み合う」の意味です。私が三層を組み込んだのではなく、この古い流れが元から三層を備えていた。ただ今までこの三つの名前で呼ばれていなかっただけです。

もう一つ、古い流れには無く、実装の途中で自然に現れたものがあります。三層は最終的に同じもの——ディスク上の状態——を共有するようになりました。

グラフはそれを読んでどの段階にいるかを判断し、 ループはそれを読んでこのラウンドで前進したかを判断し、 プロンプトはそれを読んで今回見るべき文脈を得る。

ここから使える物差しが一つ手に入ります。あるツールの三層が本当に統合されているかは、同じ状態を共有しているかで判断できる。 共有していれば統合、それぞれが自前で持っているなら、三つの仕組みが同じリポジトリに同居しているだけです。

次回：それぞれはいつ効いてくるのか

この記事から一文だけ持ち帰るとしたら、これにしたいと思います。AI にエンジニアリングをさせたいなら、新しいフレームワークを発明するより、すでにある工程を持ち出すほうが早い。 その工程は新しくありませんが、それが治してきた病は、AI も同じようにかかります。

三層がどこに落ちているか分かったところで、次の問いはこうなります。一つの機能開発の中で、それぞれはいつ効いてくるのか。 次回は一つの機能を最初から最後まで追いかけ、三層の時間軸と、互いの引き継ぎ方を示します。

試してみる：

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

プロジェクトページ：kanfu-panda.github.io/pdlc ／ ソース：github.com/kanfu-panda/pdlc-skills

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

三層がどう地に足を着くのか、具体的な像が持てたなら、いいねやフォローをいただけると嬉しいです。周りに「AI に工程を守らせたい」と考えている方がいれば、共有していただけると助かります。

プロンプトエンジニアリング、Loop エンジニアリング、Graph エンジニアリング。この三つは最近いつも同じ比較表に並べられ、三択を迫られているように見えます。しかし三者はそもそも同じ階層にいません。それを整理することは、どれか一つを習得するより価値があります。この記事では特定のツールの話はせず、各層が何を管理し、どこに限界があるのかを整理します。最後に、目の前の課題がどの層に属するかを判断するための三つの問いを示します。

三つの言葉、それぞれ別の出自

まずこの三つがどこから出てきたのかを見ておきます。来歴がまったく違うからです。

プロンプトエンジニアリングは、この二年で一度名前を変えています。初期の議論は「一文をどう書くか」でした。どんなペルソナを与えるか、どんな言い回しを使うか。その後、成果を決めているのは言い回しではなく「今回モデルに何を見せたか」だと分かってきました。そこで登場したのが Context Engineering という、より正確な呼び方です。

Loop エンジニアリングは、Ralph のようなやり方がコミュニティで広まる中で形になりました。仕組みは拍子抜けするほど単純です。一行の while ループで同じ指示を繰り返しモデルに渡し、正誤の判定はテストに任せる。十分な回数を回せば、受け入れ基準を通るバージョンが自然に浮かび上がってきます。

Graph エンジニアリングは、LangGraph のようなオーケストレーションフレームワークとともに視野に入ってきました。エージェントの実行経路を明示的に図として描く——誰が誰に渡すのか、差し戻せるのか、どこで必ず止まるのか、という主張です。

三つの流れはそれぞれ別に育ち、最後に同じ表へ並べられました。問題はまさにこの表にあります。三者はそもそも同じ種類のものではありません。

🧱 三者は同じ階層にいない

正しい関係は横並びではなく、積み重ねです。

ここで一つ補足しておかないと、別の落とし穴にはまります。階層関係が成り立つことと、すべての層が必要であることは別です。

「標準の三層アーキテクチャ」が頭に入ってしまうと、どんなタスクにも三層を被せたくなります。実際にはうまく回っているシステムの多くは一層か二層しかありません。

Anthropic が『Building effective agents』で示している原則は実践的です。最も単純な方法から始め、効果がはっきり改善するときだけ複雑さを足す。

つまり正しいメンタルモデルは「三層アーキテクチャ」ではなく、三つの選択可能な入れ子の層。既定では最下層から始め、上に足すには代償が伴うということです。

🔍 各層は結局何を管理しているのか

以下、各層について四点を扱います。何であるか、どうやるか、誤解しやすい要点、そして限界です。

プロンプトエンジニアリング：今回モデルに何を見せるかを決める

すでに「言い回しを整える」段階ではありません。本当に管理すべきなのは、今回モデルに何を見せ、何を見せないか、です。

そう変わった理由は単純で、タスクが複数ラウンドの推論をまたぐようになると一文の言い回しでは足りなくなり、焦点がコンテキスト全体の管理——システム指示、ツール定義、外部データ、履歴メッセージ——へ移るからです。

具体的な手立てはそう多くありません。システムプロンプトは適切な高さで書く必要があります。行動を導けるだけ具体的で、かつあらゆる状況を書き切ってしまわない程度に。細かすぎる規則は想定外の場面に出会うと互いに矛盾し始め、曖昧すぎる規則は何も言っていないのと同じです。ツールの説明はそれぞれの担当をはっきり書く。機能が重なるツールが多いほど、モデルは選び間違えます。出力フォーマットは先に決めておけば、後から正規表現で拾う手間が消えます。例示は多様なものを一組、境界ケースを積み上げるより有効です。

誤解しやすい要点：コンテキストは長ければ良いというものではありません。詰め込むほど中間部分は薄まっていきます。これは実際に起きる劣化であって、「モデルが賢くない」からではありません。注意力には予算があり、どこに使うかはトレードオフです。「多く渡すほど安全」ではありません。今回そもそも見せる必要のないものを見極めるほうが、何を書くかを考えるより早いことがよくあります。

限界：これはソフトな制約です。モデルは必ずしも指示どおりに動くとは限らず、しかもその場では気づけないことがあります。

この層の最大の長所と最大の問題は同じ事実です。一文直せばすぐ効く。だからこそ、モデルが従う気になるかどうかに委ねるしかありません。

Loop エンジニアリング：一つのタスクに、一つの検証を足す

この層には公理として使える一文があります。

A loop is a task with a check. A task without a check is just hope. ループとは、タスクに一つの検証を足したもの。検証のないタスクは、ただの願望である。

Ralph の形は先に触れたとおり、あの一行の while です。しかし本当の設計はループの中にはなく、周辺のファイルにあります。全部で三つ、それぞれ役割が違います。一つは仕様書で、このプロジェクトを何に仕上げるか、何をしてはいけないかを書く。一つは進捗リストで、何が終わり次に何をやるかを記録する。もう一つは毎回そのまま投入される指示で、「先に前の二つを読め、それから一件選んで手をつけろ」とモデルに伝える。ループ自体に技術的な難しさはありません。難しいのはこの三つを正しく書くことです。

誤解しやすい要点：毎ラウンド、コンテキストは完全に洗い流されます。モデルは前のラウンドで何をしたか覚えていません。欠陥のように聞こえますが、これは仕様です。記憶がないおかげで毎回きれいな状態から始まり、前のラウンドの誤った理解を後まで引きずりません。代償として、ラウンドをまたいで残すべきものはすべてディスクに落とす必要があります。それがあの進捗リストです。人間向けのメモではなく、次のラウンドのモデルにとって唯一の記憶です。

停止の信号はどこから来るか：ループは何をもって止まると判断するのか。機械が自動で判定できる信号が要ります。テストの終了コード、コンパイル結果、型チェック。「見た感じ良さそう」では条件判断に書けないので、成立しません。

典型的な失敗は二通りあります。一つは空回りです。モデルは毎ラウンド何かをやった気になっているのに実際には何も進まず、Token だけが燃えていく。もう一つは重複作業です。前のラウンドで完成しているものを見つけられず、まだ無いと判断してもう一度作ってしまう。昨日敷いた配管に気づかず、床を剥がしてもう一度敷き直す職人と同じです。

限界：検証信号のないループは、ゴミを量産しているだけです。しかもその失敗は最も見つけにくい。動き続けているのに、向きが間違っているからです。

Graph エンジニアリング：同じ名前の別物を先に切り分ける

この層はまず用語の曖昧さを解消する必要があります。同じ「グラフ」でも、まったく別の二つを指しています。

• オーケストレーショングラフ：LangGraph の類。フローがどの経路を通るかを描く
• ナレッジグラフ：GraphRAG やコード関係グラフの類。実体どうしの関係を描く

同名別物です。この記事で扱うのは前者、オーケストレーショングラフのほうです。後者はこのシリーズの第 7 回で単独に扱います。

オーケストレーショングラフがやっているのは、「この仕事をどの順で進めるか」を頭の中から紙の上へ移すことです。誰が誰の仕事を受け取るか、どの工程なら差し戻せるか、どこで必ず止まって人の承認を待つか。

よく使われる形は五つで、それぞれ向く仕事が違います。

• 直列：一歩終えたら次へ。コードを書くのがまさにこれで、設計 → テスト → 実装の順に進みます。
• ルーティング：まず種類を判定し、それから担当を決める。問い合わせが来たら分類し、返金は返金フロー、障害は障害フローへ。
• 並列：互いに独立した作業を同時に走らせ、最後に統合する。同じ差分をセキュリティ・性能・可読性で別々に見て、指摘をまとめる。
• オーケストレーターとワーカー：一人が分解して割り振り、複数が黙々と実行する。
• 評価と改善：出来上がったものを一度レビューに通し、基準に満たなければ差し戻す。

実際のシステムはたいていこの五つの組み合わせです。新しい形を発明する必要はありません。

図を描くことには、見落とされがちな利点が二つあります。一つは復旧できること。各ノードでチェックポイントを取れるので、落ちても最後の地点から再開でき、最初からやり直さずに済みます。もう一つは監査できること。後から「なぜその経路を通ったのか」を説明できます。説明を求められる場面では効いてきます。

誤解しやすい要点：グラフが定めるのは「どの経路を通ってはいけないか」であって、「どうやるか」ではありません。これは重要なので後で単独に扱います。

限界：事前に想定できたことしか表現できません。その場で判断が要るもの、見たことのない状況には、図は何の役にも立ちません。さらに隠れたコストがあります。一度描いた図はそのまま負債になり、現実が変われば描き直しになる。図の描き直しは一文の書き換えよりずっと高くつくので、着手前によく設計しておく必要があります。

🏠 リフォームに置き換えてみる

三層を一つの喩えで通しておきます。

三者の性格を三文で。

プロンプトは指示出しです。 「主寝室の北向きの壁、オフホワイト、二度塗り、際はマスキング」。コストはゼロ、即座に効きます。ただし職人が「これで十分だろう」と判断する余地があり、その場では気づけません。

Loop はやり直しの仕組みです。 指示だけでは足りず、検査が要ります。ここで効いているのは「やり直し」ではなく直定規のほうです。定規のないやり直しは、ただの二度手間です。

Graph は施工順序です。 壁を何色に塗るかは決めません。「防水をやらずにタイルを貼る」を、工程として不可能にするだけです。

三者の分担を一文で言うと、順序が「やってはいけないこと」を封じ、やり直しが基準まで押し上げ、指示が具体的なやり方を決める、ということです。

⚖️ 三つの性格、三通りの壊れ方

コストの行について：エージェントで約 4x、マルチエージェントで約 15x は Anthropic の公開情報によるもの、Graph の 2–3x は公開資料で流通している概算です。いずれも桁感の参考であり、実測値ではありません。

この表で最も考える価値があるのは最後の行です。三つの壊れ方はまったく違います。プロンプトの失敗は見える——従わなかった結果がそこにあります。Loop の失敗は見えない——動き続けていて、向きだけが違う。Graph の失敗は直せない——図が固まっていて、現実のほうが動いた。

後ろの二つは最初の一つよりずっと厄介で、しかもそれは層を足したからこそ現れた新しい問題です。「上に足すには代償が伴う」というのは、具体的にはこういう意味です。

🚧 誤解しやすい二つのこと

Graph は計画しない。負の制約をかけている

三層を「Graph が計画し、Loop が実行し、Prompt が実装する」という指揮系統として読みたくなります。しかし図はどうやるかについて一言も言っていません。宣言しているのは「テストを飛ばして実装に入ってはいけない」だけです。この設計をどのモジュールに分けるか、実装をどのファイルから書くか——そちらが本当の計画で、それは下の二層で起きています。

別の言い方をすると、こうなります。

線路が決めるのはどこへ行けるか、どこで必ず止まるかであって、その外出の目的には関与しません。 エンジンはただ前へ押し出すだけです。終点まで、あるいは停止信号にぶつかるまで。 ハンドルは線路が許す範囲の中で、具体的な進み方を決めます。

線路が旅程を計画してくれることはありません。「横へ逸れる」を成立させなくしているだけです。

階層が上がるほど、能力は弱くなる

「上位層・下位層」という言い方に引きずられると、上のほうが重要に思えます。実際は逆で、制御力が強いほど表現力は弱くなります。Graph は事前に想定できたことしか表現できず、現実が図の想像を超えた瞬間、何の助けにもなりません。

もう一段踏み込むと、この三層はどれ一つとして何かを「実装して」いません。実際に作業しているのは常にモデル自身で、三層はその振る舞いを形づくる三つの手段にすぎません。Graph は構造で、Loop は反復と検証で、プロンプトは言語で。

つまり、モデルが強くなるほど上の二層の必要性は縮んでいきます。この仕組み一式の価値は、ある意味でモデルの現時点の弱点を補うところにあります。

✅ 選定のための三つの問い

この記事から一つだけ持ち帰るとしたら、次の三つの問いにしてください。

第一問：間違ったとき、機械が自動で気づけるか。

気づける → Loop を使う。テスト、コンパイラ、型システムが直定規になります。 気づけない → どんなに魅力的に見えても使わない。検証信号のないループはゴミの量産です。

判断基準は素朴です。「正しくできた」を、終了コードを返すコマンドとして書けるか。書けるなら回せます。書けないなら回さないことです。

第二問：今この場でフローチャートを描けるか。

描けて、しかもこのフローを繰り返し使う・監査する・人の承認点を残す必要がある → Graph を使う。 描けない → 無理に描かない。

ここでいう「描けない」とは、そもそも何ステップで終わるか言えない種類の仕事です。三歩で終わるかもしれないし、二十回行き来するかもしれない。途中で何に出会うか次第です。この種の仕事は本来モデル自身に進みながら判断させるべきで、無理に図を被せると縛るだけになります。Anthropic の推奨も同じ趣旨です。ステップ数が読めないオープンな問題はエージェントに任せ、固定フローを当てはめない。

もう一点。問うているのは「今描けるか」であって「いずれ描けるか」ではありません。先に考え抜いてから描いた図だけが制約として機能します。走りながら継ぎ足した図は、混乱を別の形式で記録し直しただけです。

第三問：上の二つはどちらも要らないか。

ならプロンプトエンジニアリングで十分です。これは妥協ではなく、正解です。 単発の分類タスクにループとオーケストレーションを被せても、遅く、高く、デバッグしにくくなるだけです。

次回：三層が同時に育った実物はあるのか

概念の話はここまでです。最後に一文だけ残しておきます。この文はシリーズ全体を貫きます。

プロンプトの層ができるのは「要求」までで、「保証」は与えられません。「Token を節約しろ」と書けばモデルはたいてい従いますが、本当に超過したとき止める手立てはありません。その一文には強制力がないからです。

保証が欲しいなら、層を変えた手段が要ります。たとえば「この一回で一定額を超えたら自動停止」というハードなラインを引く。この線はモデルと交渉せず、モデルの意思も問いません。

つまり、欲しいものが「保証」なら、プロンプトの層はそれを与えられない。一つ上に移す必要がある。

次回は具体的なものを扱います。私が作っている pdlc-skills が、なぜこの三層に自然に収まっているのか、という話です。

試してみる：

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

プロジェクトページ：kanfu-panda.github.io/pdlc ／ ソース：github.com/kanfu-panda/pdlc-skills

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

三つの言葉の違いが整理できたなら、いいねやフォローをいただけると嬉しいです。周りに同じところで混乱している方がいれば、共有していただけると助かります。

こんなことはありませんか：

• AI に新機能を依頼すると「できました」と返ってくる。しかし PRD はそのチャット履歴の中だけにある。ウィンドウを閉じれば消える。「あの設計、なぜそうしたっけ」を後日確認しようにも、git のコミットメッセージしか残っていない。
• 実装後にテストを書かせると、通過率 100% の「テスト」を平気で作る。なぜなら実装済みのコードに合わせて書かれただけだから。設計を制約していない。
• 設計ステップを飛ばして直接コードを書く。アーキテクチャの腐敗は静かに進行。3 か月後に新機能を追加しようとしたら、コードは当初の設計図とは別物になっている。
• セッションをまたぐと記憶ゼロ。「機能 X、どこまで進んでた？」 — あなたの頭の中だけが頼り。

これらの本質は何か：AI アシスタントはエンジニアリングプロセスを「ソフトな約束事」として扱う — スキップ可能、忘却可能。

PDLC（Product Development Life Cycle）は Claude Code プラグインで、目的は一言で：そのソフトな約束をハードな契約に格上げする。PDLC のワークフローに入ると AI は PRD をスキップできない、テスト無しに実装できない、現在のステージを忘れられない。

実装：3 層構成 + Iron Law + 状態マシン

31 個のコマンド、3 層構成

日常では第 1 層が主役：

# Claude Code 内で
/pdlc-feature ログインに画像認証を追加

このコマンド一つで PDLC が PRD → 設計 → TDD レッドライト → 実装 → レビュー → リリースまでをつなぎます。すべてのステージは Iron Law を満たすことを強制されます。

Iron Law：5 つの不変条件

成果物を生成する第 1 層 / 第 2 層のすべてのステージは以下を満たす必要があります：

1. 成果物がディスクに保存 — チャット出力だけではない、docs/ 配下に実ファイル
2. 状態マシンが更新 — 完了したすべてのステージが docs/.pdlc-state/<feature-id>.json を書く
3. テストファースト — 失敗するテストが無い限り実装はブロック（TDD レッドライト）
4. セルフチェック — 各ステージはハンドオフ前に自己監査を実行
5. 自動修復は 1 回のみ — 自動修復は最大 1 回、解決しない問題は人間にエスカレート

これらは推奨ではなく強制。第 1 層 / 第 2 層の成果物生成ステージはこれを飛ばせません — 飛ばせばセルフチェックが失敗する。

状態マシン：機能ごとに 1 つ

新機能ごと（/pdlc-feature ...）に PDLC は F20260515-01 のような ID を発行し、対応するファイルを作成：

docs/.pdlc-state/F20260515-01.json

中身はこんな感じ：

{
  "feature_id": "F20260515-01",
  "slug": "captcha-login",
  "current_stage": "implement",
  "history": [
    {"stage": "prd", "ts": "2026-05-15T10:30:00Z", "self_audit": "8/8 passed"},
    {"stage": "design", "ts": "2026-05-15T11:05:00Z", "self_audit": "6/6 passed"},
    {"stage": "tdd", "ts": "2026-05-15T11:40:00Z", "tests_written": 14, "all_failing": true}
  ],
  "next_step": "/pdlc-implement"
}

メリットは？機能ごとのセッション横断の継続性。明日 Claude Code を開き /pdlc-status を実行すれば「F20260515-01 は implement ステージ、次は review」と分かる。あなたの記憶にも、AI のコンテキストウィンドウにも依存しません。

ターゲットプロジェクトのディレクトリ

PDLC はプロジェクト内の以下を読み書きします：

docs/00_standards/coding/                          # コーディング規約（読み取り専用）
docs/01_requirements/prd/                          # PRD
docs/02_design/{api,database,architecture,ui-ux}/  # 技術設計
docs/03_development/                               # 開発者マニュアル
docs/04_testing/{unit-tests,e2e-tests,defects,...} # テスト & 欠陥
docs/05_deployment/                                # デプロイドキュメント
docs/06_tasks/                                     # ステージ内タスク追跡
docs/07_reviews/{doc,code,design,retro}/           # レビュー記録
docs/.pdlc-state/<feature-id>.json                 # 機能ごとの状態マシン

すべてがディスク上の実ファイル。1 週間前に AI が PRD ステージで何を書いたかを git diff で見られます。

応用：3 つの典型シナリオ

シナリオ 1：機能をエンドツーエンドで実装

# Claude Code 内で
/pdlc-feature ログインに電話番号認証を追加

PDLC が自動的にチェーン：

→ 機能 ID F20260515-01 を割当て（user-auth-phone）
→ ステージ 1：PRD 作成
   ✓ docs/01_requirements/prd/F20260515-01-user-auth-phone-prd.md
   ✓ セルフチェック 8/8 通過
→ ステージ 2：技術設計
   ✓ docs/02_design/api/F20260515-01-user-auth-phone-api.md
   ✓ docs/02_design/database/F20260515-01-user-auth-phone-db.md
→ ステージ 3：TDD レッドライト
   ✓ 14 個のテストを記述、全て期待通り失敗
→ ステージ 4：実装
   ✓ 14/14 テストがグリーンに
→ ステージ 5：コードレビュー + 自動修復
   ✓ lint 問題 3 件を自動修正
   ✓ docs/07_reviews/code/F20260515-01-user-auth-phone-review.md
→ ステージ 6：ハンドオフ
   📦 docs/.pdlc-state/F20260515-01.json 更新済み
   👉 次：/pdlc-ship

このフローの後、git ワーキングツリーには：1 つの PRD、2 つの設計ドキュメント、N 個のテストファイル、1 つのレビュー記録、1 つの状態マシン更新、加えて実際のコード変更。すべて実ファイル、チャットだけではありません。

シナリオ 2：監査可能なバグ修正

/pdlc-fix 空リストでのページネーションクラッシュ

PDLC は「ざっと見て 2 行変える」ではなく、こう進みます：

1. 特定：コードを検索し原因の候補を絞る
2. 再現：まず安定して再現するテストを書く（docs/04_testing/defects/ 配下）
3. 修正：その後初めてコードを変更
4. 検証：再現テストがグリーンに
5. 記録：欠陥レポートをアーカイブ

半年後に類似のバグが出たら、過去の欠陥記録を grep して前回の修正法が分かります。

シナリオ 3：プロジェクト全体の進捗を一目で

/pdlc-status

おおよその出力：

Project PDLC status (read from docs/.pdlc-state/):

F20260512-01  user-auth-phone     ✓ shipped
F20260513-01  captcha-login       ⏵ in review
F20260514-01  password-reset      ⚠ stuck in TDD (3 tests failing)
F20260515-01  email-verify        ⏵ in PRD

AI を追いかけて「どこまで進んだ？」と聞かなくて済みます — 状態マシンを読むだけ。

効果：実際に得られるもの

1. エンジニアリングドキュメントがコードと一緒にディスクに残る

すべての PRD、設計、レビュー記録は git 履歴の中の実ファイル。1 年後に「なぜこの設計にしたか / どんな検討経て決めたか / レビューで何が指摘されたか」を正確に追跡できます。長期保守性の質的向上。

2. TDD が口先だけでなく実際に行われる

実装は失敗するテストにブロックされます。AI がスキップしたい？できません — ルールであるだけでなく、状態マシンによって強制されているから。

3. 自動修復の暴走リスクが封じ込められる

多くの AI ツールには静かな問題があります：修正 → 確認 → 直っていない → また修正 → 別の所が壊れる → また修正… トークンと時間を燃やす無限ループ。PDLC は「自動修復は最大 1 回」と強制し、AI が詰まったら止まって人間に委ねます。

4. セッション横断のエンジニアリング継続性

今日 implement ステージまで進んだ。明日 /pdlc-status で次のステップが分かる。会話のコンテキストウィンドウにも、あなたの記憶にも依存しません。

5. レガシープロジェクトも取り込める

新規プロジェクトはゼロから構造を立てるのが容易。レガシーは難しいケース。PDLC には /pdlc-adopt があり、既存コードベースを調査し、コードを書き換えずに、足りない標準 / 設計ドキュメント / ディレクトリ構造を補完して、プロジェクトを PDLC ステージに引き継げる地点まで持っていきます。

始めるには

完全なインストール手順、コマンド一覧、カスタマイズ方法、FAQ は PDLC 製品ページ とリポジトリにあります。

ワンライナー：

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

その後 Claude Code 内で：

/pdlc-feature <一文で要件を記述>

リポジトリ：github.com/kanfu-panda/pdlc-skills（MIT）

設計哲学を少し

PDLC は「AI アシスタントを足す」ものではなく、AI 以前のエンジニアリング思考の延長です：

ソフトウェアエンジニアリングが数十年にわたり積み上げた核心は「プロセス規律」です。AI が登場しても規律は消えるどころか、AI がすり抜けられないツールで強制されるべき。

「AI がコードを書き終えた = プロジェクト納品」が危険な単純化だと感じるなら、PDLC はおそらくあなたが探していたものです。

ぜひお試しください。質問は GitHub Discussions へ、または プロフィールページ からご連絡を。