project-rules-architect

Project Rules Architect

エージェントが実際に従うルールセットを作成します。読み飛ばされて無視されるスタイルガイドではありません。このスキルが防ごうとしている失敗は、誰かが「ルールをすべてまとめて、シニア開発者のように振る舞って」と依頼し、深さにばらつきのあるファイルが15個でき、その半分が互いに矛盾し、どこにも組み込まれず何も読み込まれないまま、半年後には誰もルールを信頼せず、保守しようともしなくなることです。

解決策の形： 汎用、ドメイン別、テクノロジー別の専門ルールテンプレートのライブラリを用意し、丸ごとコピーするのではなく、プロジェクトを調査して選択します。1つの事実は、必ず1つのテンプレートだけに記載します。エージェントが行動を起こす前に必要な情報はすべてエントリーファイルに含め、それ以外は必要に応じて読み込むファイルに記載します。

ドラフトを作成する前に、セッションごとに一度 references/research-summary.md を読んでください。以下のすべての原則を裏付ける根拠が記載されています。この実行で既存のルールを統合する場合、プロジェクトの規約を採用する場合、または別のプロジェクトのパターンを移植する場合は、必ず references/postmortems.md を読んでください。どちらも仮定上のものではなく、実際に過去に発見された失敗です。これらを再検討しないでください。

計画スキルと連携する場合

プロジェクトでも計画スキル（Forge、または .forge/ ディレクトリを管理する同等のスキル）が使われている場合、このスキルは計画スキルによって2回呼び出されます。このスキルは呼び出される側です。ルーティングは行いません。

呼び出し	タイミング	出力するもの
コンテキストの足場	プロジェクト開始時、技術スタックが判明する前	4つのコンテキストファイルのみ
ルールセット	計画スキルが技術スタックとプロジェクトの目的を確定した後	AGENTS.md + ルール一式を対象に組み込んだもの

4つの足場ファイルは、プロジェクトのセッション間メモリです。どちらのスキルも、その後これらのファイルには書き込みません。 これらのファイルはエージェントが管理します。セッションの記録を追記し、決定を記録し、修正内容を記録します。足場の作成後、Forgeもこのスキルもこれらを編集せず、内容のコピーを別途保持することもありません。

これは整理整頓のためではありません。メモリファイルはセッションを重ねるごとに価値が蓄積する唯一の成果物です。そのため、2人の書き手が最も簡単に破壊できる成果物でもあります。一方が追記し、もう一方が上書きしても、ファイル自体は残り、もっともらしく見えるため、損失に気づきません。

このスキルが管理するもの	計画スキルが管理するもの
AGENTS.md、SESSION_LOG.md、DECISIONS.md、LEARNINGS.md の構成を一度だけ定義	プロダクト、技術スタック、アーキテクチャ、計画
AGENTS.md、{{rules dir}}/*.md — 従うべき内容	.forge/*.md — 構築するものとプロジェクトの場所
組み込みファイル（opencode.json、.cursor/ など）	state.json — ステータス、パス、ID、ハッシュ
—	.forge/audit/ — 計画プロセスで発生したインシデント

ルール：1つの事実は1つのファイルだけに記載し、決定には担当者を定めます。 計画スキルの状態ファイルが保持するのはコピーではなくポインターです。文章を含む状態ファイルは状態ファイルではありません。規律のない文書であり、並べ替えもインデックス化もできず、問題があっても何の兆候もありません。

このスキル自身の作業に関する2つの帰結：

• 修正には記録先を明記します。 LEARNINGS.md に記録する内容には、どのルールファイルへ昇格させるかを記載します。移行先のない修正は昇格できません。postmortems.md のケース5を参照してください。
• 2回の呼び出しは独立しており、片方がもう片方を意味することはありません。 プロジェクトに足場があり、ルールがない場合があります。これは2回の呼び出しの間にある通常の状態であり、未完成のルールセットではありません。逆に、足場はなくルールだけがあるプロジェクトもあります。これは、このスキルを単独で使う場合には一般的な状態です。どちらの欠落も、報告すべき不備ではありません。

---

6つの原則

このスキルが作成するものは、すべてこれらの原則に従います。ドラフトが原則に反する場合は、原則ではなくドラフトを修正してください。

1. 2層ではなく3層に分けた、文書ではなく運用ポリシー。 削除するかどうかを決める前に、すべての文を必ず次のいずれか1つに分類します。

   ティア	テスト	例	対応
   チュートリアルの説明	モデルが学習データから知っている内容を説明している	サーバーコンポーネントとは何かを示す20行の例	削除
   運用上の説明	「Xのとき、エージェントは何をすべきか？」または「Xは許容されるか？」に答えている — バッククォートで囲まれたコマンドがなくても該当します	「行数ではなく責任ごとに分割します — 単一の責任を担う250行のファイルでも問題ありません」	残します。 可能であれば、より簡潔に書き直してください。削除してはいけません。
   検証可能なコマンド	成功または失敗の結果が得られる、文字どおり実行可能な呼び出し	npm run lint が終了コード0で終了する	残す

   中間のティアの判断基準は、エージェントがこれに違反する状況を想像できるかです。想像できるなら、コマンドがあるかどうかにかかわらず、それはドキュメントではなく判断ルールです。「クリーンなコードを重視します」は該当しません — 違反のしようがないからです。「行数ではなく責任ごとに分割します」は該当します — エージェントは件数に合わせるためだけに、250行のファイルを誤って分割しかねません。

2. 1つの事実は1か所に記載します。 同じルールを2つのファイルに記載してはいけません。複数の領域に関わるルールは、必ず1つのテンプレートに記載し、それ以外の場所からは名前で参照します。これはスパゲッティ化の最大の原因です — 個々のルールが悪いのではなく、同じルールが時間とともに異なる表現に分かれ、食い違っていくことです。監査は grep で行い、主観で判断しません。また、相互参照にはファイル名ではなくセクション名を指定します。「security.md を参照」は不十分です。「security.md §トークンの取り扱いを参照」なら、ファイルをリファクタリングしても参照が維持されます。

3. 優先順位は積み上げるのではなく、順位を付けます。 順位が示されていない「迅速にリリース」「網羅率を高める」「CIの予算は5分」は、エージェントが暗黙のうちにどれかを選び、後からそのことが判明する状態を招きます。競合する可能性があるルールの組み合わせには、すべてエントリーファイルで明確な順序を付け、他のファイルからはその順序を参照します。

4. 骨組みから始め、修正をもとに育てます — 新規のルールセットに限ります。状況は2つではなく、4つあります。

   • コンテキストの骨組み（スタックが判明する前に、名前を指定して依頼された場合）：メモリとコンテキストの構造を出力し、そこで停止します。ルールも、ルールセットも、スタックの調査も行いません。以下の「§ コンテキストの骨組み」を参照してください — これはプランニングスキルが最初に呼び出すモードで、どちらの方向に間違っても大きなコストがかかります。
   • ブートストラップ（既存のルールがない場合）：簡潔で正確な骨組みと、継続的に更新する学びのセクションを用意します。初日からあらゆる仮定上のルールを列挙してはいけません — まだ起きていない状況を推測することになり、ランダムさの問題を招きます。
   • 統合（既存のルールを再編成する場合）：既存のルールはどれも、すでに得られた教訓を表しています。再編成と重複排除を行います。内容を選別して減らしてはいけません。 ここで「簡潔に始める」という圧力をかけると、postmortems.md のケース1で起きたような、内容が知らぬ間に失われる事態を招きます。確認なしで削除できるのは、チュートリアルの説明と完全な重複だけです。
   • 導入（既存のコードがあり、既存のルールがある場合もない場合も該当）：references/existing-project-protocol.md をすべて実行します。コードが実際に採用している規約を検出し、そのうえで保持または移行します。これは以前のスキルで扱われていなかったケースであり、動作中のコードベースと矛盾するルールを生み出すケースでもあります。

5. パターンの移植は、内容の移植ではありません。 移植可能なのはパターンです — 何をきっかけにチェックを行うか、何を検証するか、どのファイルに記録するか、といった点です。具体的な内容は移植できません。ファイル名、ライブラリ名、フレームワークの規約は元のプロジェクトに属するため、このプロジェクトの実際のスタックに基づいて改めて導き出す必要があります。このプロジェクトに存在しないファイル、ライブラリ、ツールを参照するルールファイルは、汚染されています（postmortems.md のケース2 — なお、ライブラリ名を grep してもプロセスに関する語彙は検出できないため、別途確認が必要です）。その帰結として、痛い経験から学んだことがあります。生成されたルールファイルで、その元になったテンプレートやプロファイルに言及してはいけません。 残った「プロファイルに従って」という記述や、誤ったスタックのフレームワーク記号は、どちらも汚染であり、宙に浮いた参照でもあります。

6. 予算は説明文には上限、ゲートには下限です。 これは別々のルールです。この2つを混同すると、主張は網羅しているのに、適用する仕組みが何もないセットになってしまいます。

   内容	予算	テスト
   説明文 — 根拠、枠組み、例、経緯	上限です。まずここを削ります	この文がなくてもエージェントの行動は変わりませんか？
   ゲート — しきい値、コマンド、終了コード、禁止リスト	下限です。決して削りません	違反したときにゼロ以外で終了しますか？

   ゼロ以外で終了しないゲートは、ゲートではありません。 それは単なる文であり、ほかのすべての文と同じ運命をたどります。疲れているエージェントや、急いでいるエージェント、あるいは「とにかくこれを終わらせて」と指示されたエージェントは、その文を読み飛ばします。しきい値、コマンド、禁止リストは、どのルールファイルでも最も安価な内容です。それぞれ1行で済み、そのプレッシャーの中でも残る唯一のものです。

   したがって、セットが予算を超えている場合は、まずチュートリアルの説明文を削り、それがなければ、運用上の内容を削るのではなく、対象を絞ったファイルを追加してください。 予算を下回っている場合も、さらに削ってよいという意味ではありません。何が欠けているのかを確認すべきサインです。生成されたセットが薄いときによくある理由は、圧力弁が作動したことです（§ Step 0b を参照）。

6b. 予算は対象ごとに設定し、測定する必要があります。読み返しテストでは検出できません。

research-summary.md の約500行という目安は、Cursor 独自のガイダンスであり、アクティベーションモードを前提としています。対象を絞ったファイルは、そのファイルに含まれるファイルが開かれたときにのみ読み込まれます。スコープ設定のない対象には適用できません。

対象	スコープ設定	予算
Cursor .mdc	4つのアクティベーションモード	常時適用される内容は約500行	mdc-frontmatter-spec.md
OpenCode instructions glob	なし — すべてのファイルが毎回のセッションで読み込まれる	ルールディレクトリ全体の厳密な合計	Step 3b
AGENTS.md のみ	なし	1ファイル。1ファイルに収まらなくなったら対象を変更	—

スコープ設定のない対象では、ファイルを分割しても何も節約できません。 glob はどちらの場合も読み込みます。調整できるのは合計量と、トリガーを条件とする内容を無条件に読み込まれるファイルに入れないことだけです。

また、Step 6 の読み返しテストでは、大きすぎるセットを検出できません。 エントリーファイルをもとに回答しますが、これは短く、重要な内容が先頭に配置されています。予算の2倍を超えるセットでもテストに合格します。Step 3b で合計量を別途測定してください。測定しないのなら、何も把握できません。

コンテキストの足場

計画スキルは、スタックが決まる前にこのモードを呼び出します。これは早期終了です。4つのコンテキストファイルを出力し、ルールは出力せず、停止します。

出力するもの	出力しないもの
AGENTS.md — エージェントが行動する前に必要とするコンテキスト、および以下の3ファイルそれぞれのトリガー	ルールファイル
SESSION_LOG.md — 発生したこと。セッションごとに追記	.opencode/rules/
DECISIONS.md — 決定事項と、質問形式の未解決の質問	スタックの選択
LEARNINGS.md — 修正内容。それぞれ、どこに反映するかを明記	プローブ結果

フォーマットは規範です — 再設計せず、そのまま再現してください

4つのファイルは固定の形式です。プロジェクトごとに形式が変わるメモは、2回目のセッションでは誰にも読めないからです。形式は templates/memory/ にすべて記載されています。このディレクトリは単なる例ではなく、仕様です。

フォーマットはかつて維持され、その後失われました。provenance/synthesis-provenance.md には、8フィールドの SESSION_LOG.md と6フィールドのADR形式が「そのまま維持」され、「エントリーファイルと並べて出力」されていたと記録されています。templates/ ディレクトリは一度も出力されませんでした。その結果は予測ではなく、実測されました。Phase 0からPhase 5までを通して実施したプロジェクトで、スキャフォールドが生成したのは4項目のジャーナル、確定した決定がゼロの質問のみの DECISIONS.md、そしてエントリーがゼロの LEARNINGS.md でした。フォーマットは知られており、文書化もされていましたが、規範ではなかったため、プロジェクトごとに独自の形式になっていました。

ファイル	形式	最も失われやすいフィールド
SESSION_LOG.md	順番が決まった8つのフィールド：STARTED FROM · DECIDED · REJECTED · BLOCKED · FILES TOUCHED · STATUS · NEXT SESSION SHOULD · NEXT SESSION SHOULD NOT	REJECTED — 以下を参照
DECISIONS.md	## ADR-<NNN>: <title> と6つのフィールド：Date · Statut · Contexte · Décision · Alternatives considérées · Conséquences	Alternatives considérées
LEARNINGS.md	修正1件につき1行。問題を対比形式で記述し、その後に → domaine: … | Seen: … を付けます	対比形式
AGENTS.md	コンテキスト、その後に説明とトリガーを含むインデックス	トリガー

REJECTED は、それ自体で価値を生むフィールドです。 それ以外のフィールドには実施したことが記録されますが、REJECTED には却下したこととその理由が記録されます。また、後のセッションでそれを再提案するのを防げるのは、このフィールドだけです。これがないジャーナルでは、過去の議論が蒸し返されます。上記の実測対象のプロジェクトでは、却下された内容は、契約上の対象外（会計、カード決済）、意図的に計画から外された6つのスライス、client-liaison が却下した16項目、そして創作された2つのエージェントパスでした。4つのカテゴリーすべてが重要な役割を担っていましたが、いずれも記録する場所がありませんでした。

確定した決定は、確定したものとして扱います。 DECISIONS.md は、確定した決定を追記のみで記録する台帳です。「追記のみ」と「確定」を組み合わせると、誤りだと判明した決定は、古い決定を明示した新しいADRによって置き換えられ、黙って書き換えられることはありません。Statut: Actif または Statut: Supersédé par ADR-<NNN> とします。すべてのエントリーに Statut: 行が必要です。これがないエントリーは置き換えられず、したがって修正できないためです。

プロジェクトがまだ答えを出せない質問も、質問として DECISIONS.md に記載し、それぞれに確定させるトリガーを付けます。ただし、台帳の役割は確定した決定を記録することです。未確定の質問だけがあり、確定した決定がない DECISIONS.md には、将来のセッションを拘束する記録が何もありません。

インデックスの二つの要素と、通常欠けているほう

AGENTS.md には、ファイルごとに1行を設けた表があります。各行には二つの要素が必要ですが、それらは同じものではありません。

要素	答える質問	欠けている場合
説明	このファイルには何を入れるのか？	ファイルが謎のままになります
トリガー	何がきっかけで、いつ書き込むのか？	ファイルがいつまでも空のままになります

説明があってトリガーがない行は、表が完成しているように見えるため、最もよくある間違いです。しかし、実際には完成していません。これは4つの入れ物を並べただけのインデックスで、それらを埋める指示がありません。その結果、記憶は作られ、構造も整い、名前も正しいのに、永久に空のままになります。進歩しているように見えるぶん、記憶がないよりも悪い状態です。

トリガーはカテゴリではなく条件です。「修正」は説明です。「同じ間違いを2回したとき」がトリガーです。3つすべてにトリガーが必要です。また、ファイルを読み返してその時が来たか判断しなくても、エージェントが自分で認識できるタイミングでなければなりません。

AGENTS.md 自体にはトリガーは必要ありません。読み込まれるファイルであり、残りの3つを動かすものだからです。

**スキャフォールドに判断ではなく質問を置く理由。**これは、場所ではなく時間に対して原則2を適用したものです。スタックが判明する前に記録された判断は判断ではなく、判断の服を着た推測です。PRA 独自のルールである「出典を示せない主張は、留保付きのルールにするのではなく、質問、提案中の ADR、または未確認のエントリーにする」も同じルールです。そのため、DECISIONS.md は、プロジェクトがまだ答えられない質問から始まり、最初のエントリーの Status: は Open になります。

**スキャフォールドがルールセットではない理由。**ルールセットは、スタックが判明してから、そのスタックに基づいて生成されます。すでにルールを含むスキャフォールドは、全面的に書き直すか、さらに悪い場合はルールセットと共存して二重に読み込まれることになります。1つの事実には1つの置き場所を割り当てます。この時点で記録する事実は質問です。

**その後これらのファイルに書き込むのは、このスキルでも計画スキルでもありません。**これらはプロジェクトのセッションをまたぐ記憶です。エージェントが維持します。このスキルの役割は、4つのファイルが存在し、構造的に整った状態になった時点で完了です。つまり、見出しがあり、それぞれに修正を記録する正規の場所が1つずつある状態です。

完了を宣言する前に検証してください。失敗は表面化せず、誤ったスキャフォールドは空のスキャフォールドとまったく同じように見えるからです。

1. 4つのファイルがすべてプロジェクトのルートにあり、見出しが設定されています。
2. **AGENTS.md では、3つのファイルそれぞれについて、何を記録するかと、書き込む条件の両方が示されています。**説明だけでトリガーがなければ、埋める指示のない入れ物です。
3. LEARNINGS.md には修正を追記する場所がちょうど1つあります。2つの候補を設けている場合、監査ではすでに不合格です。エージェントが読むのは、古い内容が残っているほうだからです。
4. DECISIONS.md の各エントリーには Status: 行があります。スキャフォールド自体のエントリーは Open です。
5. どのファイルにも、ルール、しきい値、コマンド、バージョンの固定が含まれていません。含まれている場合、スキャフォールドが2つ目のルールセットになっています。
6. 4つのファイル間の相互参照には、正確な大文字表記のファイル名が使われています。AGENTS.md では DECISIONS.md を参照し、decisions.md とはしません。大文字と小文字を区別するファイルシステムでは、小文字の名前は何も指さず、参照をたどったとき、つまり数か月後に、気づかれないまま失敗します。表だけでなく説明文も確認してください。両方に別々の誤りが入り込む可能性があります。
7. **条件分岐が解決されています。**以下を参照してください。

このモードにある唯一の条件分岐と、その理由

templates/memory/ には、AGENTS.md と SESSION_LOG.md の所有権テーブルに、それぞれ単一の {{#if forge-present}} ブロックがあります。

ファイルシステムを調べて判定します。プロジェクトのルートに .forge/ ディレクトリがあればブロックを残し、なければ削除します。 テンプレートエンジンはなく、導入すれば保守対象がもう一つ増えるだけです。

これがすべてです。 以前はこれらのブロックが無条件だったため、.forge/ がまったくないプロジェクト、つまりこのスキルを単独で使う場合の一般的なケースでも、スタックが存在する場所として .forge/conventions.md、.forge/architecture.md、.forge/state.json、.forge/audit/issues.md を記載していました。これは、コストのかからない単なるリンク切れではありません。毎回最初に読み込まれるファイルにある誤った指示であり、プロジェクトの全体像を構築する段階で、実際には存在しない場所にスタックがあるとエージェントに伝えてしまいます。

単独での利用が一般的なケースなので、ほかに何もなくても正しく読める必要があるのは、単独利用の分岐です。

両方向を確認してください。 .forge/ のないプロジェクト向けにスキャフォールドを生成し、.forge という文字列が残っていないことを確認します。次に、.forge/ のあるプロジェクト向けに生成し、参照が含まれていることを確認します。rules-selftest.js の §no_forge_coupling は最初の方向を自動的に検証します。2つ目の方向については、実行対象となるプロジェクトがないため、読み合わせで確認します。

テンプレートライブラリ

references/templates/ — 3つの階層があります。ここから選択します。一括でコピーすることはなく、実行中に編集することもありません。

階層	ディレクトリ	生成されるもの
コア	templates/core/	常に生成。8ファイル：エントリーファイル、アーキテクチャ、ワークフロー、git ワークフロー、品質ゲート、コードレビュー、コーディング規約、セキュリティ
ドメイン	templates/domain/	検出結果に応じて選択。11ファイル：データと状態、エラーと非同期状態、フォーム、UI コンポーネント、アクセシビリティ、テスト、依存関係のセキュリティ、パフォーマンス、i18n、デザインシステム、外部システムとの契約
テクノロジー	templates/tech/	検出結果に応じて選択。8つのオーバーレイに加え、tech/variants/ に4つのバリアント差分

コアファイルが8つである理由と、9つ目に求められる正当性。 これらは、あらゆる言語のあらゆるプロジェクトで通用するルール、または、ほかのルールを強制できるかどうかを決めるルールです。重要なのは後半です。quality-gates.md は、残りのルールを検証可能にするコマンドを管理します。これがなければ、何も検証できないルールの集合になってしまいます。それを防ぐことが、このスキルの目的です。

9つ目にも同じ基準が求められます。「良いトピックである」だけでは基準を満たしません。基準は次のとおりです。すべてのプロジェクトで、行動する前にそれが必要か、または正しく行動できたかを確認する前に必要か。

選択は判断ではなく、対応表の参照です。 references/stack-detection.md が対応表であり、生成された各テンプレートには、その選択を引き起こしたシグナルが記録されます。省略された各テンプレートには、それを除外した行が記録されます。「テストランナーが設定されていない」は明示する価値のある検出結果です。何も記載しないのは許容される理由ではありません。

バリアントは置き換えではなく、差分です。 バリアントには、どのファイルをどのように変更するかを記述します。2つのバリアントを適用する場合は、2つの差分ファイルを適用します。組み合わせたバリアントを作成してはいけません。また、差分の中で変更対象の内容を再記述してはいけません。

テンプレートがなぜそのような構成なのかを知る必要がある場合 — テンプレートの変更、追加、または変更によって何が削除されるかの確認をするとき — は、provenance/synthesis-provenance.md を読んでください。3つのソースプロジェクトの各ルールがどのテンプレートに対応するかに加え、統合、重複排除、削除された内容、およびプロジェクト固有として残された内容がまとめられています。

実行時には誰も読みません。 これは、このライブラリを生み出した統合作業の監査記録であり、441行にわたる履歴です。これを references/ に置き、実行のたびに読むよう指示していたのは誤りでした。ライブラリ内のファイルはエージェントが読むファイルであり、このファイルには繰り返し参照する価値がありません。

ワークフロー

ステップ 0b — スキャンを実行し、その結果に判断させる

ステップ 1 の前に、また、しきい値を設定する前に必ず実行してください。 手順は references/baseline-scan.md にあります。読んで説明するのではなく、実行してください。

スキャンでは、1 回の実行で次の 3 つの問いに答えます。以前はそのすべてに推測で答えていました。

1. 正確な技術スタックは何か？ — マニフェストから特定します。マニフェストの印象から判断するのではありません。
2. プロジェクトは現時点で正常か？ — すべてのゲートを実行し、出力を記録します。リントがすでに失敗しているプロジェクトにルールセットを書くなら、その事実を明記する必要があります。そうしないと、完了の定義は最初から不合格となり、初日から無視されてしまいます。
3. greenfield か ratchet か？ — スキャンから導きます。質問してはいけません。 質問するとモードは好みになります。導き出せば結果となり、同じリポジトリで 2 回実行した場合、結果は同一になります。

インタビューで決めるモードは、エージェントの気分や質問の言い回しによって変わります。同じテンプレートライブラリを使いながら、あるプロジェクトでは 6 ファイル、別のプロジェクトでは 17 ファイルのルールセットが作られたのは、このばらつきが原因でした。

結果は docs/quality-baseline.md に記録してください。これはプロジェクトの成果物であり、ルールセットの一部ではありません。また、プロトコルに記載された 6 行形式で報告してください。

「コマンドがインストールされていない」ことも結果です。 absent として記録し、インストールを提案したうえで、そのステータスを付けてゲートを出力してください。コマンドが出力していない数値を、ベースラインとして記録してはいけません。

ステップ 1 — 調査してから、インタビューする

呼び出し元がコンテキストのひな形を求めている場合は、ここで止めてください。 § コンテキストのひな形を実行します。調査、スキャン、インタビューは行わず、技術スタックも提示しないでください。技術スタックが決まっていないプロジェクトを調査すると、マニフェストとの一致と、照合対象のないドメイン行の表が生成されます。それは、避けることを目的としている、何もないことについての自信満々なレポートです。

それ以外の場合は、スキャンで特定された技術スタックを使って検出プローブ（stack-detection.md）を実行し、表と照合して、テンプレートの候補セットを提示してください。リポジトリにすでに記載されていることは尋ねないでください。

次に、プローブでは解決できない項目だけを尋ねてください。 通常、質問は 1 つか 2 つです。

• ターゲット形式 — 推測できない唯一の項目です。references/target-formats.md を参照してください。ユーザーが希望する構成をすでに述べている場合、それが仕様です。改善すべきデフォルトではありません。
• Git 戦略 — trunk-based、git-flow、release-train のいずれかです。これも導き出せません。どちらの分岐戦略にもコストがかかり、取り消しに必要な労力も同じではないためです。希望がなければ trunk-based を選び、DECISIONS.md に記録してください。「戦略なし」だけが、誰でも元に戻せる選択肢です。
• 検出ではなく判断が必要なバリエーション — ルーター、レンダリング戦略、状態管理ライブラリを使うかどうかなどです。コンポーネントライブラリの軸はインストール状況で決まりますが、データアクセスの軸は判断事項なので、尋ねてください。
• モノレポか単一アプリか。モノレポの場合は、対象にするパッケージも尋ねてください（references/monorepo-strategy.md）。
• チーム開発か個人開発か — 初日にどれだけのひな形が必要かに影響します。
• すでに決まっていること — 決定済みの事項、既存のメモリシステム、設計契約、デプロイ方法などです。

ユーザーが「X 向けに適切なものを生成して」と言った場合は、インタビューを強制しないでください。 補う前提を明示して進めてください。確認するのは、黙って進めると誤ったアーキテクチャになる項目だけです。該当するのはターゲット形式です。

しきい値については尋ねないでください。 しきい値は baseline-scan.md の §モードの選択で決まります。質問すると、スキャンが解消するために導入された、まさにそのばらつきが再び生じます。

ステップ 2 — 実際のソースと照合する

技術固有のルールを書く前に、references/documentation-sources.md の 優先順位に従って確認してください。 まずプロジェクトそのものを確認します。マニフェストに記載された正確なバージョン、インストール済みのソース、同梱されている型定義です。次に、エージェント向けにフレームワークが同梱しているものを確認します。その次に、設定済みの MCP サーバーを、推測ではなく実際に確認します。続いて、固定された正確なバージョンに対応する公式ドキュメントを確認します。その次に、インストール済み CLI のヘルプを確認します。ウェブ検索は最後です。

技術固有の主張にはすべて、確認元の優先順位を示す印を付ける必要があります。 または、ADR を伴うプロジェクトの決定として記します。根拠を確認できない主張は、質問、提案する ADR、または external-system-contracts.md に記載する未確認の項目にします。曖昧な表現を付けてルールにしてはいけません。 「おそらく X ですが、確認してください」という表現は、ルールの権威と推測の不確かさを併せ持ち、エージェントはそれに従って動きます。

フレームワークに詳しいからといって、このステップを省略してはいけません。 防ぐべき失敗は目に見えないものです。コードはコンパイルでき、慣用的に見えますが、2 リリース前に移動した API を呼び出しています。

ステップ 3 — モードを選ぶ

モード判定（existing-project-protocol.md §Mode detection）を実行します。これは照合です。

• 指示ファイルがない場合 → ステップ 4。
• 指示ファイルがある場合 → 既存プロジェクト向けのプロトコルを完全に実行します。 特に、ステップ A：ルールを 1 つでも書く前に、プロジェクトで実際に使われている規約を検出します。 マニフェストではなくコードを読みます。各規約を file:line 参照付きで記録します。ギャップレポートを作成してユーザーに提示し、各項目について、プロジェクトの規約を維持するか、移行を段階的に進めるかを選んでもらいます。動作している実装と矛盾するルールは、ルールがないよりも悪いものです。 エージェントはルールに従ってコードを壊すか、コードに従ってファイル全体を信用しなくなるかのどちらかです。

README はあるが指示ファイルがないプロジェクトは、導入ではなくブートストラップです。 README はドキュメントであり、ルールではありません。

まだコードがないプロジェクトの場合： 検出プローブで照合されるのはマニフェストだけです。フォーム、テストランナー、ローカライズ層、デザイン契約、外部システムといった条件付きドメインのシグナルは、いずれも既存のコードを必要とします。そのため初日のプローブでは、コア層とマニフェストに記載されたものだけが検出され、ドメインの選択は照合ではなく質問になります。照合対象のない表を提示するのではなく、そのことを明確に伝えてください。また、初日に検出されなかった項目を調査結果として報告しないでください。コードがまだない段階で「テストランナーが設定されていない」と言っても、事実ではありますが価値はありません。

ステップ 3b — 提出前に一式の規模を測る

# the target's actual instruction surface
find .opencode/rules -name '*.md' -exec cat {} + | wc -l
wc -l AGENTS.md

ステップ 1 で選んだ対象（原則 6b）の予算と比較します。予算を超えている場合：

• トリガーに基づく内容を、常時読み込まれるファイルの外に移します。 差分が認証に触れる場合だけ、またはモノレポ内の特定のサービス内だけに適用されるセクションは、適用されないセッションでも毎回コストが発生します。これは、glob で読み込まれる対象に対して有効な唯一の手段です。
• ルール自体ではなく、説明を簡潔にします。 ルールから削るなら、しきい値、コマンド、禁止事項より先に、正当化の文言を削ります。
• ルール全体を削るのは最後にし、削るのはチュートリアル的な説明だけにします。 予算は上限であり、目標ではありません。ただし、上限の 2 倍に達する一式は、丁寧さではなく不備です。

ステップ 4 — 草案を作成する

選択した各テンプレートを埋めます。正しく行うべき点は 3 つです。

• セクションの順序は固定されており、優先順位も決まっています：コマンド → 完了の定義 → エスカレーション → タスク別のセクション → バージョンと禁止パターン → 最後にスタイル。エージェントが書式を知る必要が生じる前に、ビルド方法を知る必要があります。スタイルは最後であり、最初に削られる項目です。
• 箇条書きを並べるのではなく、タスク別のセクションにする — 「X を書くとき」「X をレビューするとき」のようにします。運用上の判断ルールはここに記載し、箇条書きを並べただけのリストでは真っ先に失われます。
• コードサンプルを貼り付けるのではなく、コードベース内にすでにある正規の例を 1 つ示すようにします。貼り付けたコードは気づかないうちに古くなりますが、ファイルへの参照はそうなりません。
• ルールには、その理由を 1 つの節で添えます。 テンプレートの GENERATOR NOTES ブロックは出力時に削除されるため、テンプレートで想定されていないケースにルールを適用するうえでエージェントが必要とする情報は、ルール自体に記載する必要があります（rule-file-template.md §The Generator Notes contract）。導出の説明はノートに、適用方法はルールに記載します。

3 つの操作は互換性がありません — 何かをマージする前に、どの操作を行うのか確認してください。

操作	何が起きるか	いつ行うか
吸収	内容全体を同程度の深さで移行し、移行先に内容が反映されたため、移行元を削除します	移行元のルールが本当に移行先のスコープに属する場合
参照	移行元はそのまま残し、移行先から名前とセクションを指定して参照します	移行元がインラインで記載するには大きすぎる、または具体的すぎる場合
削除して一度だけ言及	grep コマンドや一行の記述に、実質的なルールを置き換えること	絶対にしないでください。 これは構造上の変更に見せかけた、気づかれにくい内容の欠落です

何かを吸収したら、すぐに検証します — 次のファイルに進む前に、移行元をまだ開いている間に行ってください。

1. 移行元にある個々のルールをすべて列挙します。番号付き項目、しきい値、禁止パターン、判断ルールです。コマンドだけではありません。
2. それぞれが移行先にも同程度の深さで記載されていることを確認します。さらっと触れるだけではなく、完全な文またはルールを強制するコマンドとして記載されている必要があります。
3. ルールの数が減ったなら、何かが失われています。要約されたのではありません。 94 行の移行元が移行先で 3 つの箇条書きになるのは、成功ではなく危険信号です。

ステップ 5 — 監査

パート A はコマンドです。何かを読む前に実行してください。

node "$PRA/scripts/rules-selftest.js" <project>

配線、インデックス、プレースホルダー、相互参照、矛盾するしきい値、.forge/ との結合、汚染、強制できない文章、ゲート、予算という、10 項目のチェックを決定的に行います。失敗は欠陥であり、議論の余地はありません。 修正して再実行してください。 スクリプト自体のセルフテスト（node "$PRA/scripts/selftest.js"）で、各チェックが主張どおりのものを検出することを確認できます。そのため、合格は形式的な手続きではなく、証拠になります。

次にパート B、references/audit-checklist.md の判断を要する部分に進みます。これを自動化してはいけません。また、実施していないのに検証済みとして報告してはいけません。他のチェックでは検出できない問題を見つけるセクションです。

• コンテンツの保持 — 統合の場合。冗長性と矛盾のチェックでは、新しいセットをそれ自体と比較します。3 分の 1 のルールが失われていても、セットに冗長性がまったくないことはあり得ます。照合件数が必要です。「N 件のルールを保持、M 件を相互参照付きで統合、K 行のチュートリアル形式の文章を削除（一覧に記載）」。この件数を示せないなら、確認したことにはなりません。
• プロジェクト間の汚染 — 採用または移植の場合。パート A では機械的な形式を検出します。こちらでは、借用したアイデアがこのプロジェクトの用語で表現されているため、固有のものに見えてしまうという意味的な汚染を検出します。
• コードとの矛盾 — 採用の場合。各ルールについて、コードがすでに重要な箇所で逆の動作をしていないことを確認します。これを検出できる他のチェックはありません。ルールセットをそれ自体ではなくコードベースと比較するためです。
• 出典 — 技術固有の主張はすべて、ラダーの段階または ADR までたどれるようにします。
• 昇格 — external-system-contracts.md があるプロジェクトの場合。矛盾するルールの隣に、未対応の所見が置かれていないこと。また、複数のセッションにわたって一般的に当てはまっている所見が、ルールファイルに反映されずに残っていないことを確認します。
• 乖離 — 統合の場合、または移行を伴う採用の場合。検出された乖離はすべて、保持されたルールか移行対象のどちらかである必要があります。説明のつかない乖離は、暗黙のうちに削除されたルールです。

次の点も確認してください： 「常に適用する」ルールが、密かに対象を限定されているのではなく、本当にすべてのセッションに適用されること。優先順位が競合するすべての組み合わせに順位が付けられていること。すべてのチェック可能性テスト（コマンド、glob による一致、禁止リストの照合、または原則 1 の「エージェントはこれに違反するか？」テスト）に失敗する指示がないこと。失敗する指示はすぐに削除せず、書き直してください。 ファイルごとの行数が上限として扱われていること。すべてのファイルがインデックスから参照されていること。生成されたインデックスに、生成されたすべてのファイルが記載され、それ以外は記載されていないこと。

ステップ 6 — 接続し、成果物を渡して、ループを設定する

対象の形式に接続してください。これは追加対応ではなく、成果物の一部です。 ツールに読み込ませるファイルを用意せずに Markdown を生成しても、完全に見えるだけでまったく機能しないルールセットになります（target-formats.md）。

上書きせず、マージしてください。 既存の設定ファイルには、ユーザーのモデル、プロバイダー、ツールの設定が含まれています。キーを追加し、ファイル全体を置き換えないでください。

完了を宣言する前に接続を検証してください。設定ファイルが解析できること、参照先のパスがすべて存在することを確認します。一致するものがない glob も、有効な設定ではありますが、何も読み込みません。

その後、ユーザーに次の3点を伝えてください。

1. 継続的な学びを記録するセクションの場所 — 一元化した場所を1つだけ用意します。エージェントが同じ間違いを 2回 したときに訂正を追加し、推測で追加してはいけません。プロジェクトにすでにセッションをまたぐメモリーシステムがある場合は、別の仕組みを作らず、学びをそこに組み込んでください。
2. 読み戻しテスト。 新しいセッションで、エージェントにビルドコマンド、完了の定義、特定の領域に適用されるルールファイルを尋ねます。答えられない場合は、ファイルが長すぎる、曖昧すぎる、または検出されていません。内容を追加する前に修正してください。接続が壊れている状態でルールを増やしても、読み込まれないルールが増えるだけです。採用モードでは、4つ目の質問として「このプロジェクト独自のパターンは何か」を尋ねます。答えがプロジェクトではなくテンプレートについて説明している場合、ルールに問題があります。
3. 監査結果。ステップ 5 の照合形式で提示します。

テンプレートに誤りがあった場合 — 技術オーバーレイの仕組みが適用されなかった場合や、ドメインテンプレートのルールが実際のプロジェクトで機能しなかった場合は、納品した出力だけでなく、テンプレートファイルを修正してください。 次のプロジェクトがコピーするのはテンプレートです。そこに反映されない修正は誰の役にも立たず、同じ欠陥が再び納品されます。

モード別の参照ファイル

誤った範囲を読むと、同じタスクを2回実行しても出力が異なります。モードが変わるか、行に「必要に応じて」とある場合を除き、この表にあるファイルだけを正確に読み、それ以外は読まないでください。

ファイル	コンテキストの土台作り	初期設定	統合	導入
SKILL.md	✔	✔	✔	✔
baseline-scan.md	—	✔	✔	✔
postmortems.md	—	✔	✔	✔
stack-detection.md	—	✔	✔	✔
documentation-sources.md	—	✔	✔	✔
target-formats.md	—	✔	✔	✔
monorepo-strategy.md	—	モノレポ	モノレポ	モノレポ
research-summary.md	—	✔	—	—
existing-project-protocol.md	—	—	—	✔
audit-checklist.md	§ 上記を確認	ステップ5	ステップ5	ステップ5
rule-file-template.md	—	必要に応じて	必要に応じて	必要に応じて
architecture-decision-guide.md	—	必要に応じて	必要に応じて	必要に応じて
mdc-frontmatter-spec.md	—	Cursor のみ	Cursor のみ	Cursor のみ
provenance/synthesis-provenance.md	決して読まない	決して読まない	決して読まない	決して読まない

ルールを出力するすべてのモードで、baseline-scan.md を読みます。また、モードを判定する前に読みます。スキャンによって品質モードが決まり、判定対象がすでに決定した後に読むプロトコルは、誤った理由で読まれたことになります。

意図的に、土台作りで読むファイルはほとんどありません。 4つのファイルは、1つの判断――修正をどこに記載し、質問をどこに記載するか――に基づいて作成されます。参照するものが増えるほど、誤ってルールを取り込む可能性も高まります。postmortems.md は、プロジェクトの内容を出力する際に混入のリスクがあるため読みません。このモードでは何も出力しません。

postmortems.md は必ず読みます。 テンプレートをプロジェクトにコピーすることは、プロジェクト間での移植そのものです――まさにケース2が扱う操作です。そのため、純粋に追加だけを行うように見える初期設定を含め、すべてのモードに混入防止ルールが適用されます。

実行中に synthesis-provenance.md を読むことは決してありません。 これは、このライブラリを作成した一度限りの統合処理に関する監査記録です。ライブラリの保守――テンプレートの追加や、ルールが普遍的かどうかの判断――を行う際に読みます。

参照ファイル

すべてのファイルと、それぞれの用途です。上の表では いつ 使うかを示し、ここでは必要に応じて参照する各項目について、何のために 使うかを説明します。

• templates/ — テンプレートライブラリです。core/ は常に使用し、domain/ と tech/ は検出結果に応じて使用し、tech/variants/ は差分として使用します。
• baseline-scan.md — ドラフト作成前に実行する測定パスです。スタックの種類、プロジェクトがグリーンかどうか、greenfield と ratchet のどちらかを確認します。品質モードとベースライン成果物を管理します。
• stack-detection.md — 選択表、除外項目、報告要件を記載します。レイアウトについては monorepo-strategy.md を参照します。
• monorepo-strategy.md — リポジトリのパッケージマップ、ビルドツール、パッケージごとのコマンド検出、ルートとパッケージの所有権ルールを記載します。
• existing-project-protocol.md — モードの検出、軽量および完全な規約検出パス、ギャップレポート、維持と移行の判断、移行ステージを記載します。
• documentation-sources.md — 検証の段階、引用要件、そしてツール選択ルールを記載します（ツールがゲートになるのは、インストール済みで、メンテナンスされており、ゼロ以外の終了コードを返す場合のみです）。
• target-formats.md — 環境ごとのエントリーファイル、ルールの配置場所、配線ファイル、フックの設定を記載します。モノレポの配線を管理します。
• rule-file-template.md — セクションの骨組みと順序、セクションのタグ付け規約、テンプレートに決して含めてはならない内容を記載します。
• architecture-decision-guide.md — ファイル構成と有効化モードに関する判断ツリーです。形式に関する質問は target-formats.md に委ねます。
• audit-checklist.md — パート A はスクリプト、パート B は判断です。
• postmortems.md — 実際に発見された失敗と、それぞれに対して行われた修正を記載します。すべてのモードで読みます。
• research-summary.md — 原則の根拠となるエビデンスを記載します。ブートストラップ時に、セッションごとに一度読みます。
• mdc-frontmatter-spec.md — Cursor の .mdc フロントマター、4 つの有効化モード、優先順位を記載します。
• ../provenance/synthesis-provenance.md — すべてのソースルールをテンプレートに対応付け、統合、重複排除、削除した内容、およびプロジェクト固有として残した内容を示します。手作業でメンテナンスします。実行時には決して読みません。

スクリプト

スクリプト	内容	実行タイミング
scripts/rules-selftest.js	納品するルールセットに対する、判定可能な 10 項目のチェック：配線、インデックス、プレースホルダー、相互参照、矛盾するしきい値、.forge/ の結合、汚染、強制できない文章、ゲート、予算	ステップ 5、およびステップ 6 の後に再度実行
scripts/selftest.js	合成した破損セットに対して、上記 10 項目のチェックがそれぞれ主張どおりの検出を行うことを証明します	チェックを変更する前

監査チェックリストを信頼できなかったため、このスクリプトが存在します。 そこに記載されていた要件はすべて判定可能なものでした。そして、判定可能な要件を文章で書くだけでは、何も実行せずにエージェントが満たしたと報告できてしまいます。測定の結果、内部整合性があり、配線も適切で、品質ゲートがすべて欠けているルールセットが納品され、それが記載どおりの監査に合格していました。

どちらかのスクリプトを編集した後は、scripts/selftest.js を実行してください。 チェックがいつの間にか寛容すぎるものになっていると、何に対しても「すべて問題なし」と報告します。ツール自体は動作しているため、その失敗は見えないままになります。