パターンの構成

パターンは意図的にシンプルな作りになっています。種別を持つ少数のピースと、表示、バージョン管理、プロジェクトとのマッチングに必要なメタデータをひとまとめにしたものです。この構造を理解しておくと、インポートしたときに何が手に入るのかがはっきりわかります。

パターンはピースの集まり

すべてのパターンはピースのリストを持っています。各ピースは必ず1つのメモリ、1つのルール、または1つのスキルのいずれかで、自分の配置先を把握しています。

ピースは次の項目を宣言します。

• kind: memory、rule、skillのいずれか。インポート時にどのコンテンツ種別になるかを決めます。
• nodePath: ピースが属するワークスペース相対のパス。たとえば/app、/services/billing、ルートなら/です。ピースはこのスコープで配信されます。
• title: メモリのタイトル、ルール名、またはスキル名。
• summary: バンドルの一覧に表示される1行の説明で、本文とは別に持ちます。
• body: 完全なMarkdown本文。これがそのまま、一切変換されずにワークスペースへ書き込まれます。

各ピースが自分のパスを指定しているため、パターンは構造上パス単位になっています。バンドルはどこかに振り分ける必要がある1つのドキュメントではなく、行き先をすでに知っているピースの集まりです。

種別ごとのメタデータ

一部のピースは、そのコンテンツ種別に応じた追加フィールドを持ち、これらはインポート後もそのまま保持されます。

• ルールのピースはスコープ種別(folder、file_type、project)と優先度(high、medium、low)を設定します。これらを省略したルールは、優先度mediumのプロジェクトルールとしてインポートされます。インポートしたルールは両方を保持するため、パターン由来の優先度highのフォルダルールは、自分で書いたルールとまったく同じように表示されます。
• スキルのピースはスキル名と任意のタグを持ち、1行の概要がスキルの説明になります。インポート時にはスキルにpattern:<slug>タグも付くため、あるパターンが持ち込んだスキルをまとめて探せます。インポート後のスキルは、他のワークスペーススキルと同じように名前で検索、呼び出しができます。
• メモリのピースには追加のメタデータは不要で、本文とパスだけで十分です。

ルールのピースは強制モード(advisoryまたはstrict)も持っており、手動コピー用の内容では各ルールにこのラベルが付いています。ただしインポートでは引き継がれません。カタログ上のラベルにかかわらず、インポートしたルールはコンテキストとして添えられるadvisoryルールとして取り込まれます。編集をブロックするには、他のルールと同様に、人が承認した実行可能な制約が必要です。詳しくはガードレールとしてのルールを参照してください。こうすることで、ブロックするかどうかはカタログが勝手に有効にするものではなく、チームの誰かが判断することになります。

スコープ、優先度、強制の基本的な意味については、基本概念を参照してください。

件数とパスは算出される

パターンが自分の概要を手作業で管理することはありません。各カタログページやパッケージのREADMEに表示される「4 Rules, 2 Memories, 1 Skill」という行や配置先パスの一覧は、ピースから計算されます。そのため、表示される内容がバンドルの実際の中身とずれることはありません。パターンにルールを追加すれば、件数は自動で更新されます。

バージョン管理と鮮度

各パターンにはバージョンと日付が付いており、何を取り入れるのか、最後にいつ変更されたのかがわかります。

• version は1.0.1のような表示用のバージョンです。カタログページとインポートのプレビューに表示されます。インポートトークンには含まれません。::pathrule:package:<slug>は常に、使っているクライアントに同梱されたバージョンを指します。
• updatedAt は最後に内容が変更された日付です。カタログページの「Updated」の日付であり、サイトマップの最終更新日でもあります。
• changelog は人が読める形のエントリを新しい順に並べたリストで、バージョン間の変更点を記録しています。カタログのすべてのパターンが変更履歴を持っており、オープンパッケージで読めます。

インポートは一度きりの初期投入なので、バージョン管理が重要になります(パターンのインポートを参照)。手元のコピーが知らないうちに変わることはなく、Pathruleはどのバージョンをインポートしたかを追跡せず、新しいバージョンが公開されても通知しません。カタログページのバージョンと更新日をインポートした時期と比べ、変更履歴で何が変わったかを確認してください。新しいバージョンを取り込む方法はパターンのインポートで説明しています。

表示用メタデータ

パターンはピースのほかに、カタログでの表示に必要な情報を持っています。名前、1行のキャッチコピー、より長い説明、カテゴリ（Framework、Frontend、Backend、Billing、Infra、Workflow、AI、Securityのいずれか）、アイコンです。カタログのすべてのパターンは、解決する課題、想定する利用者、そしてアシスタントに起こさせないミスの一覧によって、自分が何者かを説明しています。カタログページでは、この3つが「Why this pattern」の下に表示されます。

マッチング用メタデータ

パターンはappliesToブロックで、どのようなプロジェクトに合うかを宣言できます。関連するパス、スタックタグ(たとえばnextjs、react)、依存パッケージ名です。カタログのすべてのパターンがこれを宣言しています。Webのカタログは検索にスタックタグを使います。インポートのプレビューは同じブロックをアシスタントに渡し、アシスタントは何かを書き込む前にプロジェクトのツリーやスタックと照らし合わせ、パターンが合わないように見える場合は確認を求めます。

オープンパッケージ

カタログは、npmでApache-2.0のもと公開されている単一のオープンパッケージ@pathrule/patternsに支えられています。このパッケージは純粋でシリアライズ可能で、パターンの定義、その型、いくつかのヘルパー関数を含み、UIやCloudのコードには依存していません。そのためプレーンなデータとして読むことができ、あらゆるサーフェスがまったく同じバンドルを利用できます。

パターンの追加は、このパッケージに新しいエントリを1つ登録するだけです。パッケージが唯一の情報源なので、Webサイトのカタログ、インポート用のツール、Markdown表示はすべて同じ内容を描画します。Pathrule MCPサーバーはパッケージの独自のコピーを持っています。そのため、新しく公開されたパターンは、使用しているPathruleのリリースにそれが含まれた時点でインポートできるようになります。

次に読むもの

• パターンのインポートでは、バンドルがワークスペースに書き込まれる流れと削除の方法を説明しています。
• パターンの概要は、まだ読んでいない場合に全体像をつかむためのページです。
• ルールの書き方とスキルの書き方では、各ピース種別を詳しく扱っています。