rpiv-pi完全解説 ── AIに「仕事の型」を教える6ステップパイプライン

出典: note.com / 2026-05-14

はじめに：AIに「仕事の型」を教える

AIにコードを書かせると、一見ちゃんと動くコードが一瞬で出てくる。コンパイルも通る。テストも通る。しかし、しばらくして気づく。「このコード、なんか違う…」と。

既存のコードベースの暗黙のルールを守っていない。後から読む人が「なぜこの書き方を？」と首をかしげる。動いてはいるが、チームの生産性をじわじわ蝕む「負の価値」を生んでいる。

rpiv-pi（Research → Plan → Implement → Verify → Pi）は、この問題に対する一つの答えだ。piコーディングエージェント上で動作する、研究→設計→出荷のパイプラインスキルである。

開発者（あなた）は「ドライバー」としてループに残る。AIはコードを書く。パイプラインは「いつ質問するか」「いつ判断を仰ぐか」を管理する。

つまり、AIに「仕事の型」を教えるツールだ。

──

作ったのは **Sergii Guslystyi（@juicesharp）**氏。Codemasters InternationalのCTOで20年のソフトウェアアーキテクト。個人プロジェクトとして2026年4月にスタート、MITライセンス。

公式サイト: rpiv-pi.com

なぜ必要か：「正しいコード」と「良いコード」の違い

rpiv-piのREADMEに、開発者の背筋が伸びる一節がある。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

「LLMs produce correct code, not aligned code. The output compiles

and passes tests, but it isn’t enterprise-grade in the way human

engineers produce: fitting the codebase’s existing patterns,

respecting conventions that aren’t written down anywhere, making

the boring choices mature systems rely on, staying reviewable and

extensible by the next person who touches it.」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

つまり──

「LLMは『正しいコード』は書けるが、『適合したコード』は書けない」

コンパイルは通る。しかしコードベースの「空気」を読めない。チームの暗黙の規約、守るべきパターン、存在してはいけない重複──そういうものをLLMは知らない。結果、動くけれど後から読む人の生産性を削る「負の価値」が蓄積される。

rpiv-piはこの擦れ違いを防ぐために設計された。人間はアーキテクチャを決め、AIはコードを書き、パイプラインがその間のコミュニケーションを構造化する。

全体像：6ステップのパイプライン

rpiv-piのコアは、以下の6つのスキルからなるパイプラインだ。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 1　　　Step 2　　　Step 3　　　Step 4　　　Step 5　　Step 6

要件発掘 →　並列調査 → 垂直設計 → 計画生成 → 実装　→　検証

discover　 research　 design　　plan　　　implement validate

│　　　　　　　│

┌──┴──┐　　 ┌──┴──┐

explore　　blueprint　 revise　　commit

（選択肢比較）（軽量計画）（計画修正）（コミット生成）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

各ステップの出力（アーティファクト）はすべて thoughts/shared/ の下に蓄積される。いつでも戻れて、なぜその判断をしたか追跡できる。

Step 1：/skill:discover ── 要件を掘り起こす

最初のステップは「何を作りたいか」を明確にすること。rpiv-piはここで1問ずつ質問を投げてくるスタイルを取る。「あなたは何を望みますか？」という根本意図から始まり、その答えに応じて段階的に深掘りする。

例えばこんな対話になる：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

AI：「動画パイプラインv3、何を改善したいですか？」

あなた：「品質を上げたい」

AI：「具体的にどの品質軸ですか？画質／音質／字幕／演出／速度」

あなた：「字幕の品質と演出」

AI：「コードベースを見たところ、現在Pillowで字幕を重ねてます。

ffmpegのdrawtextが未対応なので、これをffmpegネイティブに

変えるのが最初の一手になりそうです。進めますか？」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

この対話を通じて、ゴール・非ゴール・機能要件・受入基準・意思決定ログが構造化された文書（Feature Requirements Document）にまとまる。

出力先: thoughts/shared/discover/{日時}_{機能名}.md

Step 2：/skill:research ── 並列調査

要件が固まったら、コードベースの調査に入る。ここでrpiv-piは複数のサブエージェントを並列起動する。各エージェントが独立してファイルを読み、構造化された回答を持ち帰る。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

並列で動く3種の調査エージェント

scope-tracer

「どこを調査すべきか」スコープ策定

precedent-locator

git logから同種の過去変更を検索

codebase-analyzer

「特定のコード領域」を深掘り

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

出力は、未解決質問への回答、コードベースの事実（ファイル:行番号付き）、先行事例と教訓を含む調査文書になる。

出力先: thoughts/shared/research/{日時}_{機能名}.md

Step 3：/skill:design ── 垂直スライスに分解

調査結果を元に、機能を**独立してリリース可能な最小単位（垂直スライス）**に分解する。

従来の「バックエンドだけ」「フロントエンドだけ」という水平分割ではなく、1つのスライスでエンドツーエンドの価値が出る単位だ。

動画パイプラインの改善を例にすると：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 1: ffmpeg字幕サポート（drawtext代替）

→ このPhaseだけで「字幕がffmpegネイティブになった」という価値

Phase 2: 複数画像のクロスフェード

Phase 3: BGM自動音量調整（サイドチェイン圧縮）

Phase 4: 4K出力対応

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

各Phaseは単独でリリース可能。設計段階で「どこまでやるか」を柔軟に決められる。

出力先: thoughts/shared/designs/{日時}_{機能名}.md

Step 4：/skill:plan ── コードを含む実装計画

設計が決まったら、各スライスごとに完全なコードを含む実装計画を書く。ここがrpiv-piの真骨頂だ。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase N: ffmpeg字幕サポート

変更ファイル:

pipeline_v2.py:150-200（MODIFY）

成功基準（自動）:

python -m pytest -xq → 全テスト通過
出力動画に字幕が重なっていること

成功基準（手動）:

フォントの見た目が適切

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

各Phaseのコードは、生成された直後に自動検証（slice-verifier）が走る。その後「このPhase、承認しますか？」というマイクロチェックポイントで人間の確認が入る。承認されたコードだけが計画書に書き込まれる。

この仕組みにより、「書き終わってから間違いに気づく」を防ぐ。

出力先: thoughts/shared/plans/{日時}_{機能名}.md

Step 5：/skill:implement ── 計画を実行

計画書を読みながらPhaseを1つずつ実行する。各Phaseの流れ：計画書のコードを読む → 実際のコードベースを読む → コードを書く → 成功基準を自動検証 → チェックを入れて次へ。

もし計画とコードベースの間に乖離があれば、その場で質問が来る：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

「Phase 2でffmpegのdrawtextを使う計画でしたが、

この環境にffmpegがインストールされていません。

どうしますか？ ①計画通り進める ②スキップする ③計画を修正する」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

rpiv-piのCI/CD的アプローチ：各Phaseの実装が終わるたびに自動検証が走る。「全部書き終わってから気づいた」が起きにくい設計だ。

Step 6：/skill:validate ── 検証レポート

実装が完了したら、すべての成功基準を独立した視点で検証する。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

検証レポート

✓ Phase 1: ffmpeg字幕 — 完了、テスト通過

✓ Phase 2: クロスフェード — 完了

⚠ Phase 3: BGM調整 — 音量-3dB固定（計画では動的調整）

✗ Phase 4: 4K出力 — 未実装

推奨: Phase 3の動的調整を追加、Phase 4の見積もり再評価

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ここで重要なのは、実装を担当したAIとは別の視点で検証すること。同じAIが自分で書いて自分で検証すると、思い込みのバグを見逃す。rpiv-piは強制リフレッシュされた文脈で検証エージェントを動かす。

サブスキル一覧

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

explore（選択肢比較）

複数の実装方法をメリット・デメリットで比較。設計前の意思決定に。

blueprint（軽量計画）

設計＋計画を1回で生成。小〜中規模タスク向けのショートカット。

revise（計画修正）

実装中に気づいた問題を計画に追記。書き直さず、履歴が残る編集。

commit（コミット生成）

変更を分析し、論理的なコミットに分割＋メッセージを生成。

changelog（チェンジログ更新）

前回リリースからのコミットを分析し、CHANGELOG.mdを自動生成。

code-review（コードレビュー）

6波の並列エージェントで多角的レビュー（品質/セキュリティ/依存関係）。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ある時とない時の違い ── 寿司職人の比喩

一番わかりやすい説明として。

rpiv-piなし = 回転寿司のシャリロボット

速い。いつでも同じ形のシャリを握る。悪くない。しかし、その日の魚の脂乗り（＝コードベースの状態）を考慮しない。ネタが変わっても同じシャリ。合ってないことには気づかない。

rpiv-piあり = 寿司職人の弟子に師匠が付く

弟子（LLM）がシャリを握る。速い。師匠（パイプライン）が「その魚には少し小さめのシャリで」「今日は温度を上げて」と指示する。弟子は「なぜ？」と聞かれた時だけ答える。完成した寿司を師匠がチェックする。

結果：

・ロボットよりずっと良い寿司（＝適合したコード）

・弟子だけで全部やるよりずっと速い

・師匠は全部の寿司を自分で握らなくていい

いま手触りで実感している方も多いだろう。「動くけどなんか違う」──その違和感こそ、アライメント・デット（適合負債）だ。

使うタイミングの目安

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

規模　　　　　　推奨パス　　　　　　　　　　所要時間

───────────────────────────────────────

簡単なバグ修正　直接直す or commit で完結　　約2分

どう直すか迷う　explore → 実装　　　　　　　約5分

小〜中機能　　　blueprint → implement　　　約15分

（6ファイル未満）　→ validate

複雑な機能　　　discover → research →　　　約30分〜

（6ファイル以上）　design → plan →

implement → validate

コードベース参入 annotate-guidance　　　　　約10分

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

rpiv-piの特長は、必要な時にだけ重いパイプラインを使い、それ以外は軽量パスを使う設計。オーバーキルにならない。

インストールとセットアップ

piコーディングエージェントが入っていれば、npm一発。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

インストール

pi install npm:@juicesharp/rpiv-pi

使う（piのTUI内で以下を入力）

/skill:discover 動画パイプラインv3 品質改善

Hermes Agentからの利用

ln -sf ~/.pi/agent/skills/* ~/.hermes/skills/rpiv-pi/

設定に追加: skills.external_dirsにパスを指定

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

あとは質問に答えていくだけで、research → design → plan → implement → validate と自動進行する。

おわりに：アライメント・デットと向き合う

rpiv-piが解決しようとしている問題は、これからますます重要になる。

LLMが生成するコードの量は爆発的に増える。その中で「とりあえず動く」コードと「チームの財産になる」コードの差は、組織の生産性を分ける。

rpiv-piはその答えの一つだ。人間をドライバーに据え、AIを作業者にし、パイプラインがその間を構造化する。

コードベースに「負の価値」を積まないために。後から来る誰かの時間を奪わないために。

──

参考リンク：

・公式サイト: rpiv-pi.com

・GitHub: github.com/juicesharp/rpiv-mono

・作者 X（Twitter）: @juicesharp（Sergii Guslystyi）

この記事は note.com から KTBLOG に移行されました。元記事: https://note.com/famous_prawn2009/n/n5e59333d9f24