マルチサーフェスのハーネス規約

下流のコントリビューター向けの、正規かつ規範的なリファレンス。 本ドキュメントは、プロジェクト仕様のマルチサーフェスのハーネス規約のセクション（仕様 §0.6 + §2.8 + §4.7）を反映したものであり、公開リポジトリに同梱される単独のリファレンスです。アーキテクチャ上の根拠は ADR-0003 に記録されています。

1. なぜ複数なのかCopy Anchor Link

現代のエンジニアリングのサーフェスには、複数のハーネス — チャットコンソール、IDE 内の補完エンジン、ペアプログラミングのコンパニオン、プルリクエストのレビュアー — が触れます。それぞれが、自分専用の正規の設定ファイルを読み取ります。プロジェクトがそのようなファイルを 1 つしか出荷しない場合、残りのランタイムは、明文化されていない規約に対して黙って独自に振る舞い、リポジトリ内の記憶の欠落は、ただちに露呈します。

サーフェスが欠けていることの代償は、機械生成コードにおける気づかれないドリフトです — 目に見えないまま蓄積するため、最悪の種類の欠陥です。機械生成されるアーティファクトはどれも乖離を積み重ね、人間のレビュアーが矛盾に気づく頃には、コードベースには何週間分もの一貫しない規約が残っています。

ハーネスランタイムの設定は、デプロイの現実として複数になります。公開されるエコシステムは、§3 の 3 つの必須サーフェス — AGENTS.md、チャットコンソールのランタイム向けの振る舞いメモリファイル（CLAUDE.md）、IDE 内補完ランタイム向けのリポジトリスコープの指示ファイル — を出荷しなければなりません（MUST）。これらのサーフェスは相互に整合していなければならず（MUST）— 矛盾もドリフトもなく — 同じ規律を共同でエンコードしなければなりません（MUST）。

2. 整合性契約Copy Anchor Link

スコープ内（§3）のすべての規約サーフェスは、プロジェクトの単一の規約仕様を表現するチャネルです。仕様は次のように分解されます:

• 共有セクション — 計画ディシプリン、構造化照会（またはサーフェス上の同等手段）、著作者ヘッダー、命名、アンチパターン、モーダル階層。これらは、必須のすべてのサーフェスに現れなければならず（MUST）、サーフェス間で意味的に等価でなければなりません（MUST）。
• サーフェス固有のセクション — 能力の位置づけ、ツール呼び出しのパターン、コード生成とチャットの違い。これらはサーフェス間で異なっていてもかまいません（MAY）が、共有セクションと矛盾してはなりません（MUST NOT）。

multi-surface-coherence バリデーター（§7）は、すべての CI 実行と pre-commit で実行され、契約を検証します。

これらのサーフェスは、1 つの仕様を表現する、異なるチャネルです。共有セクションは、サーフェス間で — 意味的に、また可能な場合は字句的にも — 一致しなければなりません（MUST）。サーフェス固有のセクションは、共有セクションと矛盾してはなりません（MUST NOT）。

3. スコープ内のサーフェスCopy Anchor Link

このリポジトリでは、オプトインのサーフェスは、主張リストのフィクスチャ（tests/fixtures/multi-surface-claims.yaml）が optional-in の下に列挙しているものです。使用されないベンダー固有のルート設定は、意図的に置かれていません。ツール固有の設定ファイルは、そのツールがこのリポジトリのアクティブな編集サーフェスである場合にのみ追加されます。

4. IDE 内指示ファイルのセクション一覧Copy Anchor Link

.github/ 配下のリポジトリスコープの指示ファイルは、次のセクションを、この順序で含まなければなりません（MUST）（各セクションは、下記のとおりの見出しテキストを使います。セクション本文は、テンプレートから機械的に埋め込むのではなく執筆しますが、いずれも列挙された主張を網羅しなければなりません（MUST））:

1. Project Context — 1 段落: このリポジトリが何であるか、誰が使うか、トップレベルの構成。具体的であること。マーケティング的な表現は使わない。
2. Coding Conventions — 命名、モーダル階層、フロントマター、Markdown のスタイル、デフォルトから外れる箇所での言語固有のスタイル上の要点。

3. File Headers — ランタイムが生成するすべてのファイルは、site/content/docs/reference/authorship-header.mdx に従い、ファイルタイプに合ったコメントの形式で、正規の単一の SPDX-License-Identifier: MIT 行から始まらなければなりません（MUST）。scripts/inject-header.* と site/content/docs/reference/authorship-header.mdx への参照。

4. Plans Discipline — ランタイムは、ハーネスの設定ディレクトリ（たとえば ~/.claude/plans/ や ~/.codex/.plans/）やその他のグローバルなプランの場所に書き込むコードやスクリプトを生成してはなりません（MUST NOT）。計画アーティファクトは、site/content/docs/reference/plans-discipline.mdx に従って <project-root>/.apothem/plans/ に置かれます（レガシーの <project-root>/.plans/ ツリーは apothem migrate-workspace でアップグレードします）。
5. Structured Inquiry Behavior — ランタイムは、確信が持てないとき、黙って捏造してはなりません（MUST NOT）。代わりに、明確に示された確認ブロック（例: # TODO(clarify): <question> コメント）を挿入し、サーフェスが許す場合はチャットで質問を提示します。API をでっち上げない、モデル名をでっち上げない、ファイルパスをでっち上げない。
6. Forbidden Patterns — 明示的な禁止事項: マーケティング的な形容詞を使わない、ぼかしの埋め草を使わない、console.log によるデバッグの残骸を残さない、ユーザーのホームへの絶対パスをハードコードしない、シークレットをコミットしない、.apothem/plans/（またはレガシーの .plans/）配下のファイルをコミットしない、正規のプロジェクト指示ファイルと矛盾しない。
7. Output Format — 生成されるコードと文章は、統一された会話出力の規約に従います: 確定性、統一されたセクション構成、密度、要約の規律、引用。コードについては: 公開サーフェスが文書化されていること、言語が型をサポートする場合は型付けされていること、テストの足場がある場合はテストされていること。
8. Review Checklist — レビュアー（人間、またはプルリクエストレビューモードのランタイム）が、承認する前に検証しなければならない（MUST）事項: ヘッダーがあること、命名が準拠していること、.apothem/plans/ への書き込みがないこと、正規のプロジェクト指示ファイルとの矛盾がないこと、バリデーターがローカルでグリーンであること。
9. Pointers — AGENTS.md、CLAUDE.md、site/content/docs/reference/plans-discipline.mdx、site/content/docs/reference/authorship-header.mdx、この規約ドキュメント、src/apothem/schemas/、CONTRIBUTING.md へのリンク。

このファイルは、site/content/docs/reference/authorship-header.mdx §2 に従い、正規の著作者ヘッダーの SPDX 行（Markdown 形式）から始まります — 可視にするか不可視にするかは、プロジェクトが選択したヘッダー可視性ポリシーに従います。

IDE 内指示ファイルは、AGENTS.md や CLAUDE.md の逐語的なコピーではありません。AGENTS.md は正規のプロジェクト指示サーフェスであり、CLAUDE.md はそれを Claude Code 向けに反映したもので、IDE 内指示ファイルは、開発者が受け入れるか却下する提案を出す、エディター内のコード補完ランタイム向けの語り口で書かれます。情報（規律、規約、アンチパターン）は同一であり、枠組みが異なります。

5. 主張リストのリファレンスCopy Anchor Link

tests/fixtures/multi-surface-claims.yaml にあるフィクスチャは、共有される各主張を列挙します。エントリの例:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

バリデーターは各サーフェスをパースし、各主張がそのサーフェスに存在するかどうかを（見出し階層 + 本文のキーワード抽出によって）探し、見つからない主張や矛盾が 1 つでもあれば失敗します。

6. 調停ルールCopy Anchor Link

共有される主張について、2 つのサーフェスが矛盾していると検出された場合、デフォルトの調停は次のとおりです:

AGENTS.md は正規のプロジェクトの声です。矛盾するサーフェスはいずれも、AGENTS.md の意味を、そのサーフェスにふさわしい枠組みで反映するように書き直されます。

サーフェス固有のオーバーライドが許可されるのは、意図的な乖離を説明する ADR を指す、ファイル内の明示的な <!-- coherence-override: <claim-id> --> マーカーがある場合に限られます。オーバーライドマーカー自体も、バリデーターの許可リストに列挙され、CI レポートに表示されます。

このリポジトリで承認された調停戦略は agents-md-wins です: AGENTS.md が正規であり、アクティブなすべてのハーネスのミラーは、意味的に等価な状態を保ちます。

7. バリデーターCopy Anchor Link

3 つのバリデーターが、整合性契約を共同で実装します:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• 1 つ目は、IDE 内指示ファイルが存在し、パースでき、§4 に列挙された正規のセクションをすべて含み、正規の SPDX-License-Identifier: MIT 行（Markdown 形式）から始まることを検証します。
• 2 つ目は、各サーフェスの正規のセクションをパースし、共有セクションが、正規化された比較器のもとで互いに一貫していることを検証します（大文字と小文字を区別せず、空白の違いを許容し、字句上の言い換えは認めるが、フィクスチャで定義された主張リストについては意味的な等価性を要求する）。
• 3 つ目が検証するのは、ルートの LICENSE が、解析可能な Copyright (c) <name> 行を含むことだけです。ファイルごとのヘッダーは読み取りません。ファイルごとのヘッダーは著作者名を含まないためです。

8. サーフェスのライフサイクルCopy Anchor Link

• サーフェスを追加する。 オペレーターが、構造化照会チャネルを通じてオプトインします。ジェネレーターは、主張リストに照らしてサーフェスを作成し、バリデーターを実行し、サーフェス固有のオーバーライドが必要な場合は ADR を起票します。
• サーフェスを削除する。 構造化照会で削除を確認し、ADR に根拠を記録し、バリデーターの required-in リストを改訂します。
• ドリフトの検出。 主張リストから逸脱するコミットは、pre-commit / CI によって拒否されます。コミットの作成者は、整合性を回復するためにサーフェスを書き直します。

関連項目Copy Anchor Link

• ADR-0003 — アーキテクチャ上の根拠と、検討した代替案。
• tests/fixtures/multi-surface-claims.yaml — 正規の主張リストのフィクスチャ。
• AGENTS.md — 正規のプロジェクトの声。
• CLAUDE.md — Claude Code 向けのミラー。
• site/content/docs/reference/plans-discipline.mdx — 計画ディシプリンという共有主張の正規リファレンス。
• site/content/docs/reference/authorship-header.mdx — 著作者ヘッダーという共有主張の正規リファレンス。
• プロジェクト仕様 §0.6 + §2.8 + §4.7 — ここに反映している正規の全文。