🎯 はじめに

LLMを使ったワークフローを構築していると、プロンプトファイルがいつの間にか数百行に膨らみ、役割定義もコーディング規約もタスク手順も出力フォーマットもすべてが1つのファイルに同居している、という状況に出会うことがあります。最初は「このくらい許容範囲」と思っていた肥大化が、ある日を境に修正コストのボトルネックになり、似たようなエージェントを追加するたびに全文コピーしては微調整、という負のループに入っていくのです。

この記事では、nrs氏（nrslib）が提案している Faceted Prompting というデザインパターン を題材に、プロンプトを「関心」という単位で分解して再利用可能なモジュールに変換する考え方と、その実装であるnpmパッケージ faceted-prompting の使い方を深掘りしていきます。

📖 この記事で学べること

#	学べること
1️⃣	モノリシックなプロンプトが抱える3つの構造的な問題
2️⃣	Faceted Promptingが提唱する 5つのファセットの定義と責務の違い
3️⃣	各ファセットをLLMの system prompt / user message のどこに配置すべきか、そしてその背後にある recency効果という根拠
4️⃣	YAMLベースの宣言的な合成によって同じ部品を複数ステップで使い回す方法
5️⃣	既存の Decomposed Prompting / Modular Prompting / Role Prompting などとの根本的な違い
6️⃣	npmパッケージ `faceted-prompting` を使ってコードから合成する実践的な方法

🔥 なぜプロンプトは肥大化するのか — 3つの構造的問題

Faceted Promptingを理解する前に、まず「何を解決しようとしているのか」を押さえておく必要があります。著者のnrs氏は、プロンプト肥大化の実務的な苦しさから出発し、そこから3つの問題を抽出しています。

🔁 問題1: 再利用ができない

マルチエージェント型のワークフローを書いていると、「アーキテクチャレビュアー」と「セキュリティレビュアー」のように、似て非なるペルソナを複数作る場面 がよくあります。両者はレビュアーという点では共通ですが、観点も判断基準も手順も違います。

このとき、モノリシックなプロンプトファイルでは、共通部分（レビュアーとしての基本姿勢、例えば「建設的な指摘をする」「根拠とともに判定する」など）だけを取り出して再利用することができません。結果として次のような苦しみが発生します。

📋 プロンプトを 丸ごとコピー してから微調整するしかない
🔧 共通部分に修正が入ったら、コピーしたすべてのファイルに反映しなければならない
🐛 修正漏れが必ず発生する。しかも気づくのは本番で問題が出た後

🔗 問題2: 暗黙的な結合が広がる

もうひとつよくあるのが、コーディング規約の変更 です。例えば「nullチェックにフォールバックを濫用しない」という原則をチームで追加したくなったとします。しかし、この原則を参照しているプロンプトが10個のワークフローに散らばっていたら、10ファイルを手で開いて修正しなければなりません。

これはファイル同士が 「目に見えない結合」 で繋がっている状態です。依存関係はドキュメント化されておらず、grepで探そうにも表記ゆれがあって完全には拾えません。

💥 症状	📝 例
表記ゆれによる検出漏れ	「フォールバック禁止」と「`??` を濫用しない」が混在していて片方だけ直してしまう
参照グラフが存在しない	どのプロンプトがどのルールを参照しているかがどこにも書かれていない
変更影響が不透明	ある規約を削除したとき、どのワークフローが壊れるか予測できない

🌫️ 問題3: 責任の所在が不明瞭

モノリシックなプロンプトを読むとき、ある一文が「エージェントの役割を定義している」のか「このステップで やるべき手順 を指示している」のか、「守るべき制約を書いている」のか、すぐには区別がつかないことがあります。

この曖昧さは、修正のたびに「ここを変えると他のどこに影響するか」という考慮を難しくします。責任の境界が引かれていない ため、プロンプト全体を毎回読み直さないと安全な変更ができなくなるのです。

🔄 3つの問題は独立していない

以下の図は、これら3つの問題が相互に絡み合ってモノリシックなプロンプトを維持困難にしていく様子を示しています。

📌 この図のポイント

この3つの問題は独立しているのではなく、すべて 「関心が分離されていない」というひとつの根本原因 から派生しています。つまり、再利用性・変更容易性・責任の明瞭さは、表面的な症状として別物に見えて、実は同じ構造的欠陥の3つの表れなのです。ということは、根本を解決すれば3つの症状を同時に治せる、ということでもあります。

💡 経験者の声として

プロンプトを管理していて「そろそろ分割したほうがよさそうだな」と感じるタイミングは、だいたいこれら3つの症状のどれかが顕在化したときです。最初に症状が出るのは多くの場合「再利用したいのにできない」で、そこから「規約変更で修正漏れが発生する」に進み、最後に「責任の所在が不明」という最も厄介な状態に至ります。

💎 Faceted Promptingの核心 — 関心の分離をプロンプトに持ち込む

ここで登場するのが Faceted Prompting です。一言でいえば、ソフトウェア工学で長く議論されてきた 「関心の分離（Separation of Concerns）」 という原則を、プロンプト設計にそのまま持ち込んだデザインパターンです。

💠 宝石のメタファー

nrs氏は宝石のメタファーを使ってこのパターンを説明しています。

「ダイヤモンドは多面体にカットされていますが、それぞれの面（ファセット）は区別可能な独立した単位です。しかし、すべての面が合わさって一つの輝きを生み出す」

プロンプトも同じで、役割・規約・手順・知識・出力形式といった面を独立に保ちながら、必要なときだけ合成することで全体としての機能を成立させる、という考え方です。各ファセットはそれ単体では単なる指示文ですが、composerが組み合わせた瞬間に LLM にとっての意味のある指示に変わります。

📌 この図のポイント

各ファセットはあくまで 独立したファイル として存在し、それらを合成する工程（composer）がランタイムに最終プロンプトを組み立てる、という構造になっています。ワークフローの作者がやることは「どのファセットを組み合わせるか」を宣言するだけで、組み立てそのものを手で書くことはありません。これは、オブジェクト指向で言えばファクトリパターンにDIコンテナが組み合わさったような関係に近いと言えます。

🎭 従来との対比

従来のモノリシックなプロンプトとの違いを一枚の表で見るとこうなります。

観点	🗂️ モノリシック	💎 Faceted Prompting
構造	1ファイルに全部	5つのファセットに分離
再利用の単位	プロンプト全体	個々のファセット
変更影響	参照元が不明	参照グラフが明示的
標準化	コピペで広がる	1ファイルで共有
組み立て	手書き	宣言的・決定論的
責任の境界	曖昧	ファイル単位で明示

🧩 5つのファセットを丁寧に見ていく

Faceted Promptingでは、プロンプトを以下の 5つの関心 に分解します。それぞれがどんな問いに答えるのか、対比しながら見ていきましょう。

ファセット	🔑 問い	📝 内容の例
👤 Persona	誰として判断するか?	役割定義、専門性、行動姿勢、役割の境界
📜 Policy	何を守るか?	禁止事項、品質基準、優先順位、横断的ルール
📋 Instruction	何をするか?	このステップの目標と手順
📚 Knowledge	何を参照するか?	前提知識、ドメイン資料、API仕様
📤 Output Contract	どう出すか?	出力構造、レポートテンプレート、判定形式

この5つは、PersonaとInstructionの2つが最低限必要なコア で、残りの3つが実務経験から「独立した軸として扱う価値がある」と判断されて追加された、という成り立ちです。それぞれ順番に見ていきます。

👤 Persona — 「誰として振る舞うか」だけを定義する

Personaはエージェントの アイデンティティ を記述する部分です。例えば以下のような内容が含まれます。

🎩 役割宣言: 「あなたはソフトウェアアーキテクチャの専門家です」
🔬 専門性: どの領域に詳しいか、どのレベルの知識を持っているか
🧭 行動姿勢: 謙虚に指摘する、根拠をもとに判断する、など
🚧 役割の境界: 何をやり、何をやらないか

⚠️ Personaに書いてはいけないこと

Personaにステップ固有の手順を書かないこと が重要です。手順はInstructionに属します。Personaに「このレビューでは以下の手順を実行してください」と書き始めた瞬間、そのPersonaは特定のステップに縛られてしまい、他のワークフローで再利用できなくなります。

再利用性を保つコツは、「このPersonaを別のステップで使いたくなったとき、書き換えなくても使えるか?」という問いを自分に投げかけることです。書き換えが必要なら、それはステップ固有の情報が混入しているサインです。

📜 Policy — 横断的な「守るべきこと」

Policyは、複数のステップやワークフローをまたいで適用される「守るべきルール」 です。コーディング規約、品質基準、禁止事項といった横断的関心事がここに入ります。

具体的には次のようなものが典型的です。

🔑 原則	📝 内容
DRY原則	3回以上の重複はREJECT
Fail Fast	不正な状態は早期にエラー化
最小権限	必要最小限のスコープに絞る
未使用コード禁止	「念のため」のメソッドや将来用フィールドを書かない
直接変更禁止	オブジェクトはスプレッド演算子で新規作成
フォールバック濫用禁止	`?? 'default'` で不確実性を隠さない

Policyの面白いところは、実装ステップでもレビューステップでも共通して参照されること です。実装時に守るべきルールは、当然レビュー時にも判定基準になります。つまりPolicyは単一責任のまま複数のシーンに流用できる、典型的な 横断的関心事（cross-cutting concern） なのです。

💡 AOPとの類似

アスペクト指向プログラミング（AOP）における「アスペクト」と Policy はよく似た位置づけです。ビジネスロジックに直接書きたくないが、全体に適用されるべきルール——それを独立したファイルに切り出す、という発想が共通しています。

📋 Instruction — 「このステップで何をするか」

Instructionは、特定のステップでエージェントが実行すべき作業手順 を記述します。たとえば以下のような内容です。

✅ 計画に基づいてタスクを実装する
✅ 変更スコープを宣言する
✅ テストを書いて実行する
✅ 判断ログを記録する

Personaが「誰として」に答えるのに対し、Instructionは「何をするか」に答えます。この境界を引くことで、同じペルソナを異なるInstructionで使い回せる ようになります。例えば同じ「coder」ペルソナを、実装ステップでは「新機能を実装する」、リファクタリングステップでは「既存コードを整理する」と違うInstructionで使えます。

📚 Knowledge — 判断の前提となる参照情報

Knowledgeには、エージェントが判断するために必要な前提情報や参照資料 を入れます。典型的にはドメイン知識、アーキテクチャの前提、APIの仕様書などです。

📐 このプロジェクトのレイヤー構造は Controller → Service → Repository の順で依存する
📐 Repositoryは他のレイヤーに依存しない
📐 データベースはPostgreSQLを使っている
📐 認証にはOAuth 2.0のAuthorization Code Flowを採用している

ここで決定的に重要な区別があります。

🔑 Knowledge は記述的 (descriptive)、Policy は規範的 (normative)

つまり Knowledge は「こうなっている」を書き、Policy は「こうすべき」を書きます。nrs氏はこの区別を明確に強調しており、混同するとファセットの再利用性が崩れる原因になる、としています。

例えば「Repositoryレイヤーは他のレイヤーに依存しない」と書いたとき、これがKnowledgeなのかPolicyなのかは文脈次第です。「このプロジェクトはそう設計されている」という事実の記述ならKnowledge、「他のプロジェクトでもそうあるべきだ」というルールならPolicyです。

🤔 判定フロー

📌 この図のポイント

判定基準は 「事実か、ルールか」 という二者択一です。迷ったら次の問いを自問するとよいでしょう。

❓ もしこのプロジェクトがそうなっていなかったら、それはバグか? それとも単なる別の設計か?

バグならPolicy、別の設計ならKnowledgeです。シンプルですが、チームで合意を取る時にも使える実用的な判定方法です。

📤 Output Contract — 出力の構造を独立したファイルで管理する

最後の Output Contract は、エージェントの 出力フォーマット を定義します。レポートテンプレート、結果の判定形式（APPROVE / REJECTなど）、構造化されたテーブル形式などです。

Output Contract が独立した関心である理由は、同じ出力フォーマットを異なるエージェントで共有できるから です。

🏗️ アーキテクチャレビュアー → 「レビュー結果テンプレート」で出力
🔒 セキュリティレビュアー → 同じ「レビュー結果テンプレート」で出力
⚡ パフォーマンスレビュアー → 同じ「レビュー結果テンプレート」で出力

レビュー項目の中身は違っても、出力の形は共通でよいのです。これにより、下流の処理（CI連携、自動フォーマット、ダッシュボード表示など）が書きやすくなります。

📍 配置戦略とrecency効果 — なぜPolicyは末尾なのか

5つのファセットを手に入れたあと、次に考えるべきは 「これらをLLMに対してどう提示するか」 です。LLM APIで使えるスロットは大きく分けて system prompt と user message の2つだけですから、5つのファセットをこの2つのスロットに どう配分するか を決めなければなりません。

🎯 推奨される配置

Faceted Promptingが提案する配置は以下のとおりです。

📌 この図のポイント

Personaは system prompt に置き、それ以外の4つは user message に合成します。注目すべきは、user message 内部でのファセットの順序が Knowledge → Instruction → Output Contract → Policy の順になっていることです。特に Policyが末尾に置かれている のが特徴的です。

🧠 なぜPolicyを末尾に置くのか — recency効果

この順序には、LLMの挙動に関する実務的な根拠があります。LLMは 直前に読んだ内容に強く引きずられる傾向 があり、これは一般に recency効果（recency bias） と呼ばれています。出力生成の直前にあった内容ほど、実際の出力に反映されやすい、という性質です。

この性質を踏まえると、「必ず守ってほしい禁止事項」「REJECTの判定基準」といったPolicyは、出力生成直前、つまり user message の末尾に置くのが最も効果的、という結論になります。逆にKnowledgeのような参照情報は、推論の前提として最初に提示しておけばよく、末尾に置く必要はありません。

📌 このシーケンスのポイント

Policyが 「最後に読まれる」 ことで 「最初に守られる」 という逆説的な効果を生みます。配置順序はただの整列ではなく、LLMの推論バイアスを味方につけるための設計判断 なのです。これはFaceted Promptingがただの整理術ではなく、LLMの特性を理解した上でのアーキテクチャパターンであることを象徴しています。

💡 決定論的な組み立てが担保するもの

この配置戦略はフレームワーク側（composer）が決定論的に決めるため、ワークフロー作者が順序を意識する必要はありません。「どのファセットを使うか」を宣言すれば、順序は自動的に最適化されます。そして composer の実装が変わって順序戦略が更新されれば、既存のワークフロー定義はそのままで新しい配置の恩恵を受けられます。これは「ポリシーをコードから分離する」ことの真の価値と言えます。

ℹ️ 補足: コンセプトと実装のスコープ差

ここで示している「Knowledge → Instruction → Output Contract → Policy」という4ファセットの配置は、原著のZenn記事およびTAKTの文脈で説明されている コンセプト上の設計 です。一方、後述するnpmパッケージ faceted-prompting の compose() API は、現時点ではパラメータとして knowledge / instructions / policies の3軸を直接受け取る形になっており、Output Contractはテンプレートや合成定義側で扱う設計になっています。Policyを末尾に置くという結論自体は両者で共通しているため、考え方を学ぶ上ではどちらで理解しても構いません。

📝 具体例で見る各ファセット

ここからは、実際のファセットファイルがどのような内容になるのかを、nrs氏の記事で示されている例をもとに見ていきます。抽象論だけでは掴みにくい部分を、具体的なファイルで感覚的に理解してもらうのが狙いです。

👤 Personaの例 — Architecture Reviewer

# Architecture Reviewer

あなたはソフトウェアアーキテクチャの専門家です。

## 役割の境界

**やること:**
- 構造・設計の妥当性検証
- コード品質の評価

**やらないこと:**
- セキュリティ脆弱性のレビュー（別の役割）
- 自分でコードを書く

このPersonaファイルのポイントは次の3つです。

🎩 冒頭の一文で「誰として振る舞うか」を宣言 する
✅ 「やること」で責務のスコープを明示 する
🚧 「やらないこと」で他のファセットやエージェントとの境界を明示 する

💡 なぜ「やらないこと」を書くのか

マルチエージェントワークフローでは、役割同士の干渉を防ぐことがとても重要です。アーキテクチャレビュアーがセキュリティ観点まで口を出し始めると、セキュリティレビュアーの責務と衝突してしまいます。明示的に「やらないこと」を書くことで、LLMに対しても自分の職域を教えることができ、ワークフロー全体の予測可能性が高まります。

📜 Policyの例 — コーディングポリシー

# コーディングポリシー

## 原則
| 原則 | 基準 |
|------|------|
| DRY | 3回以上の重複はREJECT |
| Fail Fast | 不正状態は早期にエラー |
| 最小権限 | 必要最小限のスコープ |

## 禁止事項
- **未使用コード** - 「念のため」のメソッド、将来用フィールド
- **オブジェクトの直接変更** - スプレッド演算子で新規作成
- **フォールバック濫用** - `?? 'default'` で不確実性を隠さない

Policyのポイントは、テーブルと箇条書きで判定基準を機械的に書くこと です。

✅ 良い書き方	❌ 悪い書き方
`3回以上の重複はREJECT`	`なるべく重複を避ける`
`1ファイル300行超は分割を検討`	`ファイルは適切なサイズに`
`循環依存はREJECT`	`循環依存はよくない`

自然言語で曖昧に書かない のがポイントです。LLMに対しても、判定基準が明確であるほど安定した挙動を引き出せます。「なるべく」「適切に」「可能なら」のようなぼんやりした表現は、LLMのゆらぎと組み合わさって予測困難な出力を生みがちです。

📚 Knowledgeの例 — アーキテクチャ知識

# アーキテクチャ知識

## レイヤー構造

依存の方向: 上位層 → 下位層（逆方向禁止）

| レイヤー | 責務 | 依存先 |
|----------|------|--------|
| Controller | HTTPリクエスト処理 | Service |
| Service | ビジネスロジック | Repository |
| Repository | データアクセス | なし |

## ファイル構成
| 基準 | 判定 |
|------|------|
| 1ファイル300行超 | 分割を検討 |
| 1ファイルに複数責務 | REJECT |
| 循環依存 | REJECT |

ℹ️ 記述的 vs 規範的の境界について

この例は、Knowledge（「このプロジェクトはこういうレイヤー構造を採用している」という事実）とPolicy（「循環依存はREJECT」というルール）が混在しているようにも見えます。ただし原著者の分類では「このプロジェクトにおける前提」として全体がKnowledgeに入っています。チームの運用方針に応じて境界を決めればOK です。重要なのは、チーム内で判断基準が一貫していることです。

📋 Instructionの例 — 実装手順

計画に基づいてタスクを実装してください。

**やること:**
1. 変更スコープを宣言する
2. コードを実装する
3. テストを書いて実行する
4. 判断ログを記録する

Instructionはシンプルに「このステップで実行すべき行動」を列挙します。ここにコーディング規約を書き始めるとPolicyと重複する ので、あくまで「手順」に絞るのがポイントです。動詞を中心に、アクションのシーケンスとして書くと分かりやすくなります。

📤 Output Contractの例 — レビュー結果テンプレート

# アーキテクチャレビュー

## 結果: APPROVE / REJECT

## サマリー
{1-2文で結果を要約}

## 確認した観点
| 観点 | 結果 | 備考 |
|------|------|------|
| 構造・設計 | ✅ | - |
| コード品質 | ✅ | - |

## 問題点（REJECTの場合）
| # | 場所 | 問題 | 修正案 |
|---|------|------|--------|
| 1 | `src/file.ts:42` | 問題説明 | 修正方法 |

Output Contractは 「この形式で出力せよ」というテンプレート です。中身が何であれ、この型にはめて出力されるため、下流の処理（例えばCIでREJECTをフックする処理、ダッシュボードで一覧表示する処理）が格段に書きやすくなります。

💡 Output Contractが本領発揮するとき

複数のエージェントが同じフォーマットで出力すると、それらを機械的に統合できるようになります。例えば「アーキテクチャレビュー結果」「セキュリティレビュー結果」「パフォーマンスレビュー結果」が全部同じフォーマットなら、1つのダッシュボードに並べて表示することも、1つのマージスクリプトで集約することも簡単です。

🎼 宣言的な合成 — TAKTのYAMLで組み立てる

ファセットが独立したファイルとして存在するようになると、次に必要なのは 「どのファセットを組み合わせて、どのステップで使うか」を宣言する仕組み です。nrs氏はTAKTというワークフロー実行エンジンを独自に開発しており、そこではYAMLでワークフローを定義します。

📄 YAMLでの定義例

name: my-workflow

personas:
  coder: ../personas/coder.md
  reviewer: ../personas/architecture-reviewer.md

policies:
  coding: ../policies/coding.md

instructions:
  implement: ../instructions/implement.md

knowledge:
  architecture: ../knowledge/architecture.md

output_contracts:
  review: ../output-contracts/review.md

movements:
  - name: implement
    persona: coder
    policy: coding
    instruction: implement
    knowledge: architecture
    edit: true

  - name: review
    persona: reviewer
    policy: coding
    knowledge: architecture
    report:
      format: review
    edit: false

このYAMLが伝えているのは、ワークフローの作者がやることは「どのファセットを組み合わせるかを選ぶこと」だけ だという事実です。各ステップ（TAKTでは movements と呼びます）で、どのペルソナが、どのポリシーを守りながら、どの知識を参照して、どの手順を実行するかを列挙していきます。

🔑 注目すべきポイント

implement と review の両方のステップが 同じ coding ポリシーを参照 しています。ポリシーファイルは1つだけ、しかし使われるシーンは2つ。これがまさに 関心の分離による再利用 の力です。コーディング規約を変えたくなったら、 coding.md を1ファイル修正するだけで両方のステップに反映されます。

🔗 参照関係の可視化

📌 この図のポイント

中央の coding.md（黄色）が2つのmovementから同時に参照されていることに注目してください。変更したいときは1ファイルを直せばよく、両方のステップに自動的に反映されます。これが 「暗黙的な結合」から「明示的な参照関係」への移行 です。

この図はまた、「ファセットはライブラリ、movementは呼び出し元」という考え方 をよく表しています。ライブラリを1箇所直せば全呼び出し元に反映される、というのはプログラミングでは当たり前の感覚ですが、プロンプトの世界ではまだ当たり前ではありませんでした。

⚙️ 合成のシーケンス

実際にワークフローが実行されるとき、ファセットがどうLLMへのリクエストに変換されていくかを見てみましょう。

📌 このシーケンスのポイント

composer が 「決定論的に」 プロンプトを組み立てる、という点が決定的に重要です。

🔑 決定論的な組み立て = 同じ入力から常に同じ出力

同じワークフロー定義と同じファセットファイルからは、常に同じ最終プロンプトが生成されます。これは以下の観点で非常に重要です。

🐛 デバッグ容易性 — プロンプトが意図通りになっているか再現できる

📊 差分管理 — ファセット変更前後でプロンプトの差分が明確に取れる

🔬 テスト可能性 — スナップショットテストでプロンプトの変化を検出できる

🕰️ 再現性 — 数ヶ月後に同じワークフローを実行しても同じプロンプトが作られる

🛠️ ライブラリ実装を触ってみる

Faceted Promptingは設計パターンであると同時に、faceted-prompting というnpmパッケージとして 実装も提供されています。TypeScript製、ゼロ依存（特定のAIフレームワークに依存しない）、MITライセンスです。

📦 インストール

# ライブラリとしてプロジェクトに追加
npm install faceted-prompting

# グローバルCLIとして使う場合
npm install -g faceted-prompting

✨ 最小のコード例

ライブラリとしての使い方はシンプルで、 compose() 関数にファセットを渡すだけです。

import { compose } from 'faceted-prompting';

const result = compose(
  {
    persona: { body: 'You are a senior TypeScript developer.' },
    policies: [{ body: 'Follow clean code principles. No any types.' }],
    knowledge: [{ body: 'The project uses Vitest for testing.' }],
    instructions: [{ body: 'Implement a retry function with exponential backoff.' }],
  },
  { contextMaxChars: 8000 },
);

// result.systemPrompt → Persona が system prompt として格納される
// result.userMessage  → Knowledge + Instructions + Policies が順番に配置される

このコードのポイントを整理します。

📥 ファセットを 「どこに置くか」はライブラリが決める。呼び出し側は systemPrompt と userMessage を受け取るだけ
📏 contextMaxChars のような総文字数の上限を渡せる。長すぎるファセットは切り詰めなどが行われる
🚀 出力はLLM APIのリクエストにそのまま渡せる形になっている（READMEでは "LLM-ready" と表現されています）

💻 CLIコマンド

グローバルインストールすると facet コマンドが使えるようになります。プロジェクトごとの .faceted/ ディレクトリを初期化したり、サンプルファセットを取得したり、合成を実行したりできます。

コマンド	役割
🆕 `facet init`	ローカル `.faceted/` を作成
🌐 `facet init global`	グローバル `~/.faceted/` を初期化
📥 `facet pull-sample`	サンプルファセットを取得
⚙️ `facet compose`	プロンプトを自動合成
🧩 `facet install skill`	スキルをインストール

📁 ディレクトリ構造

facet init を実行すると、プロジェクト直下に .faceted/ ディレクトリが作られます。グローバル側 ~/.faceted/ は フォールバック用 で、プロジェクト側に存在しない場合はこちらが参照されます。

.faceted/                    📁 ローカル（プロジェクト単位）
├── config.yaml
├── facets/
│   ├── persona/             👤
│   ├── knowledge/           📚
│   ├── policies/            📜
│   ├── instructions/        📋
│   └── compositions/        🎼
└── templates/               📄

~/.faceted/                  📁 グローバル（フォールバック）
├── config.yaml
├── facets/
│   ├── persona/
│   ├── knowledge/
│   ├── policies/
│   ├── instructions/
│   └── compositions/
├── templates/
└── repertoire/              🎵

💡 二段構成のうれしさ

「チーム共通のポリシーや個人の好みはグローバル側に置いておき、プロジェクト固有の知識はローカル側に置く」という運用が自然にできます。個人が「自分はコードレビューでは必ずこう振る舞ってほしい」と思うようなPersonaをグローバル側に持っておけば、プロジェクトを跨いで同じ体験を得られます。

🎼 Composition定義

.faceted/facets/compositions/ にYAMLファイルを置くことで、CLIからワークフロー的な合成を実行できます。

name: release
description: Release summary composition
persona: coder
knowledge:
  - architecture
policies:
  - quality
instructions:
  - release-summary
order:
  - knowledge
  - instructions
  - policies

📌 ポイント

🎯 order フィールドで user message 内のファセット順序を 明示的に指定 できる
📐 デフォルトではライブラリ側が推奨する順序（Policyを末尾に置く順）を使う
🔧 必要なら上書きも可能

🌍 スコープ参照で外部パッケージを取り込む

faceted-prompting では、ファセットを 外部リポジトリから参照する仕組み もあります。 @owner/repo/facet-name という形式で、別のパッケージに公開されているファセットを読み込めるのです。

persona: "@nrslib/takt-fullstack/expert-coder"
knowledge:
  - "@nrslib/takt-fullstack/architecture"

これは、よく使う専門性（例えば「TypeScriptのエキスパート」「Rustの非同期プログラミングに詳しいペルソナ」）を コミュニティで共有するための仕組み と考えることができます。社内では、部署やチーム単位でファセットをパッケージ化し、プロジェクトから参照する、という運用も可能です。

🔧 主要API

ライブラリの主要APIは以下のとおりです。

API	役割
⚙️ `compose()`	ファセットを合成してsystem prompt / user messageを生成
📂 `FileDataEngine`	ファイルシステムからファセットを読み込む
🗂️ `CompositeDataEngine`	複数のデータソース（ローカル・グローバルなど）をレイヤリング
📝 `renderTemplate()`	`{{variable}}` 形式のテンプレート処理
🔒 `escapeTemplateChars()`	プロンプトインジェクション対策のエスケープ

💡 CompositeDataEngineの威力

CompositeDataEngine があるおかげで、「まずローカルの .faceted/ を探し、なければグローバルの ~/.faceted/ を探す」といった 階層的な解決 が実現できます。これはチーム共通と個人設定を両立させる上で実用的な仕組みで、IDE設定における「ユーザー設定 vs ワークスペース設定」と似た発想です。

⚖️ 既存手法との違い — 何が本当に新しいのか

「プロンプトの構造化」は決して新しいテーマではなく、これまでにも様々な手法が提案されてきました。では Faceted Prompting は、それらとどう違うのでしょうか。

📊 比較表

手法	概要	Faceted Promptingとの根本的な違い
🔀 Decomposed Prompting	タスクをサブタスクに分解する	タスクではなく、プロンプト構造（なぜ各部分が存在するか）を分解する
🏷️ Modular Prompting	XMLタグで1つのプロンプト内をセクション分けする	セクションではなく独立ファイルに分離し、宣言的に合成する
📚 Prompt Layering	スタック可能なセグメントでプロンプトを構築	これは管理ツールに寄った考え方で、設計パターンとしての関心分解の原則がない
📄 PDL (IBM)	YAMLベースのプロンプト言語	PDLは制御フローに焦点を当てており、関心の分解そのものは別の課題
🎭 Role / Persona Prompting	エージェントに役割を割り当てる	Personaは5つの関心のうち1つに過ぎない。役割だけでは再利用性を担保できない

🧭 分解の軸が違う

📌 この図のポイント

既存手法は「タスク」「構造」「役割」という異なる軸で分解しているのに対し、Faceted Promptingだけが「関心（なぜこの部分が存在するか）」という軸を明示的に導入 しています。

nrs氏はこの違いを次のように表現しています。

既存手法はタスクを分解するか、プロンプトの書式を整理するかのどちらかに重点がある。それに対して Faceted Prompting は、プロンプトの各部分が 「なぜ存在するか」という問いで分解 し、独立した再利用可能な単位に落とし込む。

この「なぜ」という問いは、ソフトウェア設計における関心の分離と同じ原則 です。ファイルを分けるのは行数を減らすためではなく、変更の理由を分離するため。同じことがプロンプトにも当てはまります。

✨ Faceted Promptingを導入する実用的な利点

ここまでの議論をまとめる形で、実務にFaceted Promptingを導入した場合の利点を整理しておきます。3つの立場（作者・チーム・エンジン）から見ていきます。

🧑‍💻 ワークフロー作者にとって

メリット	説明
🎯 変更の局所化	コーディングポリシーを変えたいときは `policies/coding.md` の1ファイルだけを編集すれば、それを参照するすべてのワークフローに反映される
🧱 組み合わせで構築	既存コンポーネントの組み合わせで新しいワークフローを構築できる。ゼロから書く必要がない
🧠 認知負荷の低減	ファイルごとに単一責務に集中できるため、書きながら「これはここに書くべきか」と迷う時間が減る
🔍 レビューしやすい	変更の差分が関心単位に分かれるので、レビュアーも意図を読み取りやすい

👥 チームにとって

メリット	説明
🌐 プロジェクト間標準化	同じポリシーをプロジェクトをまたいで共有できる。スコープ参照を使えば、コピーすらしなくてよい
🎨 役割分担	ドメイン専門家が Knowledge の管理を担当し、ワークフロー設計者が Instruction の管理を担当する、といった分業が成立する
🔎 独立したレビュー	それぞれの関心を独立してレビューできるため、レビュアーの認知負荷が下がる
📈 オンボーディング	新メンバーがファセットを1つ読むだけで「このプロジェクトのコーディング規約」を理解できる

🧠 エンジン（composer）にとって

メリット	説明
🎲 決定論的な組み立て	同じワークフロー定義と同じファセットからは、常に同じ最終プロンプトが得られる。これは再現性とデバッグ容易性に直結する
📍 配置最適化	recency効果のような経験則を、エンジン側で一元的に適用できる。ユーザーが順序を意識する必要がない
🔧 カスタマイズ自由度	特定のステップだけ特定のファセットを差し替えたり省略したりすることが、他のステップに影響を与えずにできる
🚀 将来の最適化	エンジンの配置戦略が改善されれば、既存ワークフローは変更不要で恩恵を受けられる

⚠️ 導入する前に知っておきたい注意点

万能な設計パターンは存在しないので、Faceted Promptingを導入する前に頭に入れておきたい注意点も整理しておきます。光だけでなく影も理解しておくことで、適切な場面でだけ使う判断ができます。

💸 初期コストはゼロではない

既存のモノリシックなプロンプトを5つのファセットに分解する作業は、純粋な置き換え作業とは言い切れません。例えば Policy と Knowledge の境界を引く のは、既存のプロンプトを読みながら何度か推敲が必要です。最初は時間がかかると覚悟しておいたほうがよいでしょう。

💡 段階的な導入がおすすめ

いきなり全ワークフローをFaceted化するのではなく、まず1つのワークフローをパイロット的に分解し、チーム内で手応えを確認してから横展開するのが現実的です。リファクタリングの一般的なセオリーと同じで、「動いているものを崩さず、新しい形で並走させる」ほうが安全です。

📏 小規模なプロジェクトでは過剰になりうる

プロンプトがまだ数十行で、ワークフローも1つしかない段階でFaceted Promptingを導入するのは、設計パターンとしての恩恵より管理コストのほうが上回る 可能性があります。肥大化や再利用の欲求が顕在化してから導入する、という順序のほうが自然かもしれません。

📊 判定基準	導入すべきか?
ワークフロー1つ・プロンプト50行以下	❌ まだ早い
ワークフロー2〜3個・共通部分あり	🟡 検討の価値あり
ワークフロー5個以上・コピペが発生	✅ 強く推奨
チーム横断のプロンプト運用	✅ ほぼ必須

🔍 合成後のプロンプトを検証する習慣をつける

composerが決定論的に組み立ててくれるとはいえ、最終的なプロンプトが本当に意図どおりの内容になっているか は、ときどき確認する必要があります。具体的には次のような運用がよいでしょう。

👀 facet compose の出力を 目視確認 する（特に導入初期）
📸 スナップショットテスト でプロンプトの差分を管理する
🔀 プロンプトの差分をCIで検知し、意図しない変化を防ぐ

🤝 Policy vs Knowledgeの判断はチームで揃える

記述的か規範的か、という区別は明確な原則ですが、現場では グレーゾーン が発生します。「この記述はPolicyとKnowledgeのどちらに置くべきか」の判断基準をチームで合意しておくと、レビュー時の認識齟齬が減ります。1ページのガイドラインで十分です。

📝 ガイドラインの最小構成例

Knowledge は「このプロジェクトでは〜になっている」と書き換えられるか自問する

Policy は「どのプロジェクトでも〜すべき」と書き換えられるか自問する

どちらにも当てはまる場合は、チームで再利用したい側に寄せる

🎯 まとめ

Faceted Promptingの要点を、この記事の流れに沿って振り返ります。

📌 核心ポイント

🔥 モノリシックなプロンプトには3つの構造的問題がある — 再利用不可・暗黙的結合・責任所在不明。これらは表面的には別々の症状に見えるが、すべて「関心が分離されていない」という根本原因から派生している
💎 Faceted Promptingは関心の分離をプロンプト設計に持ち込むデザインパターン — プロンプトを Persona / Policy / Instruction / Knowledge / Output Contract という5つの独立した関心に分解する
🔍 Knowledge と Policy は「記述的か規範的か」という軸で区別する — Persona と Instruction は「誰として振る舞うか」と「このステップで何をするか」で区別する。境界が曖昧になるとファセットの再利用性が崩れる
📍 配置戦略はrecency効果に基づく — Policyをuser messageの末尾に置くことで遵守されやすくなる。この最適化はcomposerが決定論的に行うため、作者は意識する必要がない
🎼 宣言的な合成で組み立てコストがゼロになる — TAKTのYAML定義や faceted-prompting npmパッケージの compose() APIを使えば、ファセットの組み合わせを宣言するだけで合成が完結する
⚖️ 既存手法との違いは「どの軸で分解するか」 — Decomposed / Modular / Role Promptingはタスクや構造、役割で分解するが、Faceted Promptingは「関心」という軸で分解する

🌱 発展的なトピック

この記事では扱いませんでしたが、Faceted Promptingを深く運用するとさらに踏み込める論点がいくつかあります。

トピック	内容
🕰️ バージョン管理	ポリシーが改訂されたとき、過去のワークフローの再現性をどう担保するか
📸 スナップショットテスト	composerの出力をスナップショット化して、ファセット変更の影響範囲を可視化する
🌐 チーム間でのファセット共有	スコープ参照を活用した社内パッケージ化の運用
🔀 動的なファセット選択	実行時の状況に応じて、composerに渡すファセットを条件分岐で切り替える設計
🧪 ファセット単体の評価	個別のファセットがどれだけLLMの挙動に影響するかを測定する仕組み

いずれも、ここで紹介した基本原則の上に乗る応用的な話題です。基礎が身についたら、ぜひ踏み込んでみてください。

💭 最後に一言

Faceted Promptingが教えてくれる最も大きな教訓は、「プロンプトもソフトウェアと同じ設計原則で扱える」 という事実だと思います。LLMを使う仕事は、自然言語を扱うがゆえに曖昧さを受け入れがちですが、管理の観点では通常のコードと同じ規律が通用します。むしろ、曖昧な世界で働くからこそ、管理側は決定論的で再現可能である必要がある、とも言えるでしょう。

📚 参考

🔗 Faceted Prompting: AIプロンプト設計のモジュール化アーキテクチャ（Zenn） — 著者nrs氏による全体解説記事
🔗 nrslib/faceted-prompting（GitHub） — TypeScript実装のライブラリとCLI
🔗 Faceted Prompting（nrslib.com） — 著者個人ブログでの解説
🔗 nrslib/takt（GitHub） — 著者が開発したワークフロー実行エンジン