Aperture — エージェント前のコンテキストゲート

Aperture は決定論的なコンテキストプランナーです。タスク説明とリポジトリに対して実行され、エージェントが読み込むべきファイル（どの形式で読み込むか）、何が不足しているか、およびタスク全体の実行可能性が本当にあるかどうかについて、スコア付けされた予算配分済みのハッシュ化マニフェストを生成します。計画パスに LLM 呼び出しは含まれません。同じ入力 → バイト単位で同じハッシュ。

これは ゲートツール で、speccritic と plancritic と並んで位置付けられます：

SPEC.md → speccritic → PLAN.md → plancritic → [APERTURE] → CODE → realitycheck → prism → clarion

Aperture の役割は、以下のようなタスクのコーディング開始を拒否することです：

• 実行可能性をもつのに十分なアンカーがない、
• トークン予算に収まらない、
• スペック、テスト、設定、ランタイムパス、またはそのタスクが明らかに必要とする外部コントラクトが不足している、
• パッケージ間の所有権が曖昧である。

aperture の実行可能性が低すぎるか、ブロッキングギャップが発火した場合、エージェントを起動しないでください。タスクを不足している入力を所有している上流ステージに戻してください。

---

呼び出すタイミング

タスク開始時に aperture を呼び出します。具体的には：

1. PLAN.md が plancritic をクリアし、コーディングタスクが開始しようとしている。
2. ユーザーが「実装しましょう」「コーディングを始める」「エージェントを実行する」「Claude Code を実行する」などのバリエーションを言った。
3. ユーザーがタスクが実行可能かどうか、十分なコンテキストがあるかどうか、またはエージェントが脱線し続けている理由を尋ねた。
4. ユーザーが長いエージェント実行の前にトークン予算の余裕をチェックしたい。
5. 前回のエージェント実行が失敗し、原因がコンテキスト枯渇またはコンテキストオーバーロードである可能性がある。

aperture を呼び出す必要はありません：

• コンテキストが明白な単純な単一ファイル編集。
• リポジトリに触れないタスク（純粋な Q&A、スペック作成、計画）。
• エージェント自体の実行 — aperture はエージェント前に実行されるか、aperture run 経由でオーケストレートされます。

---

ワークフロー

1. タスクファイルを作成または特定する

タスクファイルが入力です。以下を説明する Markdown ファイルまたはインラインテキストである必要があります：

• どのような変更が必要か、
• どのシンボル、パス、またはパッケージが関係しているか（アンカー）、
• 成功基準は何か（テスト、動作など）。

承認された PLAN.md から導出された TASK.md を優先してください。ユーザーが 1 行で与えた場合は、最初にそれをタスクファイルに展開するか、-p 経由で渡してください。

2. 計画

以下を実行してください：

aperture plan TASK.md \
  --model <model-id> \
  --budget <token-ceiling> \
  --format json \
  --out .aperture/manifests/latest.json

モデルディスパッチが重要です — cl100k_base / o200k_base / p50k_base / r50k_base トークナイザーが OpenAI ファミリー向けに組み込まれており、Claude と不明なものは保守的な ceil(len/3.5) にフォールバックします。タスクが Claude バウンドの場合、予算余裕は悲観的に報告されることが予想されます。これはバグではなく、安全です。

Claude Code の現在のデフォルトの場合、--model claude-sonnet-4-6 と予約用の余裕を残した予算を使用してください（指示 + 推論 + ツール出力 + 拡張）。.aperture.yaml の defaults.reserve でこれを制御します — CLI でオーバーライドする前に確認してください。

3. 説明

実行するかどうかを決定する前に、推論をレンダリングしてください：

aperture explain TASK.md

これは選択決定、読み込みモード、除外、ギャップを平文で説明します。読んでください。スキャンしないでください。最もスコアが高いファイルがタスクが実際に関するファイルでない場合、タスクテキストはおそらく不十分に指定されています — ステップ 1 に戻ってアンカーを追加してください。

4. 決定

マニフェストの 3 つを確認してください：

feasibility.score（0.0–1.0）：

• ≥ 0.85 — 高い。進める。
• 0.65 – 0.84 — 中程度。ブロッキングギャップがなければ進める、そうでなければ最初にギャップを修正してください。
• 0.40 – 0.64 — 弱い。エージェントを実行しないでください。最も低いサブシグナルに対処してください。
• < 0.40 — 低い。タスクが不十分に指定されているか、予算が実行不可能か、曖昧です。書き直してください。

feasibility.sub_signals：分解。coverage が低い場合、タスクが aperture が見つけられなかったかスコア付けできなかったファイルに触れています。anchor_resolution が低い場合、タスクアンカーはリポジトリシンボルにマップされていません。budget_headroom が低い場合、予算が選択されたファイルには窮屈です。task_specificity が低い場合、タスク自体が曖昧です。

gaps[]：severity: "blocking" のギャップは停止です。以下のギャップ修復テーブルを参照してください。

5. 実行（ゲートが合格した場合のみ）

aperture run claude TASK.md \
  --fail-on-gaps \
  --min-feasibility 0.65 \
  --out-dir .aperture/manifests/

--fail-on-gaps はブロッキングギャップが存在する場合、終了コード 8 で終了します。--min-feasibility は閾値以下で終了コード 7 で終了します。これらの終了コードを伝播させてください — これらはゲートが設計通りに動作していることです。バイパスしないでください。

アダプタは以下の環境変数を受け取ります。これを下流ツール（realitycheck、prism、clarion）が読み取ることができます：

APERTURE_MANIFEST_PATH
APERTURE_MANIFEST_MARKDOWN_PATH
APERTURE_TASK_PATH
APERTURE_PROMPT_PATH
APERTURE_REPO_ROOT
APERTURE_MANIFEST_HASH
APERTURE_VERSION

APERTURE_MANIFEST_HASH はパイプラインの残りの部分の結合キーです — すべての下流成果物はそれを参照して、どの計画決定がどの実装を駆動したかを証明できます。

---

ギャップ修復

すべてのギャップカテゴリは特定の上流アクションにマップされます。閾値を下げることでギャップを「回避」しないでください — 入力を修正してください。

ギャップ	対応方法	上流の所有者
missing_spec	SPEC.md / AGENTS.md を書くか特定する。	speccritic
missing_tests	テスト期待値をタスクに追加するか、ターゲットパッケージ用に _test.go スタブを追加する。	タスク作成者
missing_config_context	タスクが config/env/settings に言及している — タスクテキストで特定の設定ファイルを指定してください。	タスク作成者
unresolved_symbol_dependency	タスクが言及するシンボルはリポジトリにエクスポートされていない。シンボルを作成する必要があるか（明示的に言う）、名前が間違っているか。	タスク作成者
ambiguous_ownership	複数のパッケージがトップスコアを競う。パッケージまたはパスアンカーを追加して曖昧さを解消してください。	タスク作成者
missing_runtime_path	タスクがランタイム動作を暗示している（ネットワーク、ファイルシステム、時間、db）が、io:* 副作用タグを持つファイルが選択されていない。ランタイム接触点を指定してください。	タスク作成者
missing_external_contract	タスクが API/RPC/スキーマについて言及しているが、*openapi*/*swagger*/*schema* ファイルが選択されていない。コントラクトを追加するか、パスで参照してください。	タスク作成者またはスペック
oversized_primary_context	予算が窮屈 — --budget を上げるか、タスクを分割するか、.aperture.yaml の reserves を減らしてください。	タスク作成者または設定
task_underspecified	<2 アンカー、またはアクション unknown、または ≥0.60 でスコア付けされた候補がない。具体的なパスとシンボルでタスクを書き直してください。	plancritic またはタスク作成者

一度に複数のギャップがある場合は通常、タスクが最初から曖昧すぎることを意味します — ステージを戻ってください。前方にパッチを当てないでください。

---

終了コード

これらを尊重してください。これらは CI と下流ステージとの契約です：

コード	意味	対応
0	成功	進める。
7	--min-feasibility 以下	タスクまたはリポジトリ状態を修正してください。閾値を下げないでください。
8	ブロッキングギャップ存在	上記テーブルに従ってギャップを解決してください。
9	予算アンダーフロー	予算を上げるか、タスクスコープを狭めるか、reserves を減らしてください。
10	モデルにトークナイザーテーブルなし	サポートされているモデルを使用するか、heuristic-3.5 フォールバックに任せてください。
11	不明なエージェント	.aperture.yaml の agents: ブロックを確認してください。
12	アダプタの起動失敗	アダプタをインストールするか、$PATH を修正してください。
その他	アダプタ独自の終了	エージェント失敗として扱い、aperture 失敗としてではありません。

---

設定

リポジトリルートの .aperture.yaml は権威です。manifest.generation_metadata.config_digest にハッシュ化されるため、設定変更は新しいマニフェストハッシュを生成します（正しい — 決定が異なります）。

一般的なノブ：

defaults:
  model: claude-sonnet-4-6
  budget: 120000
  reserve:
    instructions: 6000
    reasoning:    20000
    tool_output:  12000
    expansion:    10000

thresholds:
  min_feasibility: 0.70
  fail_on_blocking_gaps: true

gaps:
  blocking:            # このリポジトリで特定のギャップをブロッキングに昇格
    - missing_spec
    - oversized_primary_context

scoring:
  weights:             # 1.0 ± 0.001 に合計する必要があります
    mention:  0.25
    filename: 0.12
    symbol:   0.20
    import:   0.12
    package:  0.10
    test:     0.08
    doc:      0.07
    config:   0.06

デフォルトがこのリポジトリで実際に誤作動する具体的な証拠がある場合のみ、scoring.weights を調整してください。ウェイト変更はプロジェクト内のすべてのマニフェストハッシュを変更します — これはカジュアルなノブではありません。

---

セキュリティ体勢

aperture plan と aperture explain はいかなるリポジトリでも安全です — リポジトリ内容でネットワーク呼び出しを行わず、アダプタを決してエクスポーズしません。

aperture run は .aperture.yaml の agents.<name>.command にあるコマンドを実行します。.aperture.yaml を Makefile のように扱ってください：新規クローンまたは PR ブランチから実行する前にレビューしてください。フォーク PR の CI では、run ではなく plan を使用してください。

タスクファイルにシークレットを含めないでください。マージされた run-<id>.md プロンプトは .aperture/manifests/ に永続化され、エージェントに逐語的に供給されます。

---

一般的な呼び出し

簡単な実行可能性チェック、永続化なし：

aperture plan TASK.md --model claude-sonnet-4-6 --budget 120000 --format markdown

完全なパイプライン統合実行：

aperture run claude TASK.md \
  --model claude-sonnet-4-6 \
  --budget 120000 \
  --fail-on-gaps \
  --min-feasibility 0.70 \
  --out-dir .aperture/manifests/

インラインタスク（TASK.md なし）：

aperture plan -p "Add OAuth refresh to internal/oauth/provider.go with unit tests" \
  --model claude-sonnet-4-6 --budget 120000

選択が起きた理由を検査する：

aperture explain TASK.md | less

キャッシュをクリア（ツールアップグレード後またはキャッシュ形式ドリフト時）：

aperture cache clear

---

解釈チートシート

• 同じタスク、同じリポジトリ、同じ設定 → 同じ manifest_hash。 ハッシュが変われば、上流で何かが変わった。これは厄介なことではなく、機能です。
• load_mode: full はエージェントがファイル全体を取得することを意味します。structural_summary はパッケージ/型/インターフェース/関数/インポートのみを提供します。behavioral_summary はインポート + 副作用タグ + エクスポートされた API サーフェス + テスト関係 + サイズバンドを提供します。reachable は読み込まれていません — 発見可能なフォローアップです。
• load_mode: full の一致するトップランクファイルがない relevance_score は通常、予算圧力を意味します。budget_headroom サブシグナルを確認してください。
• side_effects: ["io:network", "io:time", ...] は LLM 推論ではなく決定論的タグです。ピンされた副作用テーブルから来ています（manifest.generation_metadata.side_effect_tables_version のバージョン）。
• 実行可能性が出力で 0.40 で上限 はブロッキングギャップが発火したことを意味します — 上限は設計によるものです。生のスコアは sub_signals にあり、上限はポリシーレイヤーです。

---

アンチパターン

• ゲートを通すために --min-feasibility を下げないでください。 タスクが 0.65 で実行可能でない場合、0.50 でも実行可能ではありません。エージェントは後で失敗し、より多くのトークンを浪費します。
• 「この 1 回だけ」のために --fail-on-gaps をはがさないでください。 ブロッキングギャップは、それらを無視するとの下流コストが修正するとの上流コストを超えるため存在します。
• 実行可能性スコアが向上するようにフラグをいじりながら plan を繰り返し実行しないでください。 スコアは決定論的です — スコアに影響を与えるフラグ変更もマニフェストハッシュを変更し、ゲートをゲーミングしています。タスクまたはリポジトリを修正してください。閾値ではなく。
• reachable ファイルを読み込まれているものとして扱わないでください。 それらは違います。エージェントが 1 つ必要な場合、要求する必要があります — フォローアップロードまたはそれを求めるように教えるエージェントプロンプトを必要とします。
• 信頼できない .aperture.yaml で aperture run を使用しないでください。 agents.<n>.command はシェルです — あなたが書いていない Makefile のように扱ってください。