Architecture: Operational Rules

Language: English | 日本語 Last updated: 2026-04-30 (updated 2026-04-30: doc-reviewer ロールバック参照を反映 (#91 follow-up)) EN canonical: 2026-04-30 of wiki/en/Architecture-Operational-Rules.md Audience: エージェント開発者

このページはもとの Architecture.md を3ページに分割したもの（#42）です。自動承認モード・フェーズ実行ループ・トリアージティア・差し戻しルール・sandbox防御レイヤーといったランタイム・運用挙動を扱います。概念モデルとプロトコルは関連ページを参照してください: ドメインモデル、プロトコル。

自動承認モード

プロジェクトルートに .aphelion-auto-approve（またはレガシーの .telescope-auto-approve）ファイルが存在する場合、承認ゲートが自動的に通過されます。これは自動評価システム（Ouroborosエバリュエーター等）向けに設計されています。

ファイルにはオプションで設定オーバーライドを含めることができます：

# トリアージプランのオーバーライド
PLAN: Standard

# PRODUCT_TYPEのオーバーライド
PRODUCT_TYPE: service

# HAS_UIのオーバーライド
HAS_UI: true

自動承認モードの安全制限：

エージェントごとの最大リトライ回数：3回
ロールバック上限: テスト失敗 / レビュー CRITICAL / セキュリティ監査 CRITICAL / ドキュメントレビュー FAIL の差し戻しで共有（合計最大3回）。正規の定義は .claude/orchestrator-rules.md §Rollback Rules → Rollback Limit (Common) を参照。

Flow Orchestrator

Flow Orchestrator（フローオーケストレーター）はそれぞれドメインを管理します。.claude/orchestrator-rules.md で定義された以下の共通動作を共有します：

起動時に orchestrator-rules.md を読み込む
トリアージを実行してプランティアを選択する
トリアージ結果を提示してユーザーの承認を求める（AUTO_APPROVE: true の場合を除く）
Agent ツールの subagent_type を使用して順次エージェントを起動する
各フェーズ後に承認ゲートを実行する（AUTO_APPROVE: true の場合を除く）
AskUserQuestion を使用してリトライ・スキップ・中断のオプションでエラーを処理する

フェーズ実行ループ

[フェーズN開始]
  1. ユーザーへ通知：「▶ Phase N/M: {エージェント}を起動します」
  2. 前段成果物のパスを含む指示でエージェントを起動する
  3. エージェント出力からAGENT_RESULTを読み取る
  4. STATUS: error / blocked / failureに対処する
  5. AUTO_APPROVE: true → 「承認して続行」を自動選択
     AUTO_APPROVE: false → 承認ゲートを表示し、ユーザーを待つ
  6. フェーズN+1へ進む

トリアージティア

各 Flow Orchestrator は起動時にプロジェクトの特性を評価し、4段階のプランティアのいずれかを選択します。詳細は Triage System を参照してください。

flowchart LR
    subgraph Discovery ["Discovery Flow Triage"]
        direction TB
        DMin["Minimal\n1 agent\nPersonal tool / small script"]
        DLit["Light\n3 agents\nPersonal side project"]
        DStd["Standard\n5 agents\nExternal dependencies"]
        DFul["Full\n6 agents\nLarge-scale / complex"]
    end

    subgraph Delivery ["Delivery Flow Triage"]
        direction TB
        VMin["Minimal\n5 agents\nSingle-function tool"]
        VLit["Light\n+reviewer +test-designer\nPersonal side project"]
        VStd["Standard\n+scaffolder +doc-writer\nMulti-file project"]
        VFul["Full\n+releaser\nPublic / OSS"]
    end

    subgraph Operations ["Operations Flow Triage"]
        direction TB
        OLit["Light\n2 agents\nPaaS / single container"]
        OStd["Standard\n+db-ops\nAPI + DB architecture"]
        OFul["Full\n+observability\nHigh availability"]
    end

    subgraph Maintenance ["Maintenance Flow Triage"]
        direction TB
        MPat["Patch\n4 agents\nBug / CVE / 1–3 files"]
        MMin["Minor\n7 agents\nFeature / refactor / 4–10 files"]
        MMaj["Major\n→ delivery-flow\nBreaking / 11+ files"]
    end

注意: security-auditor は全Deliveryプランで実行されます。doc-reviewer は全プラン（Delivery / Discovery / Maintenance）で spec / design / scope / analyst エージェントの後にポスト挿入として実行されます。ux-designer は HAS_UI: true の場合のみ実行されます。

差し戻しルール

差し戻しはテスト失敗、レビューの CRITICAL 指摘、セキュリティ監査の CRITICAL 指摘、およびドキュメントレビューの FAIL 結果によって自動的にトリガーされます。共有の差し戻し上限（4 種すべてを通じて最大 3 回）は .claude/orchestrator-rules.md §Rollback Rules で Rollback Limit (Common) として定義されています。

テスト失敗による差し戻し（Deliveryドメイン）

tester（失敗）
  → test-designer（原因分析）
    → developer（修正実装）
      → tester（再実行）

レビューCRITICALによる差し戻し（Deliveryドメイン）

reviewer（CRITICAL検知）
  → developer（修正）
    → tester（再実行）
      → reviewer（再レビュー）

セキュリティ監査CRITICALによる差し戻し（Deliveryドメイン）

security-auditor（CRITICAL検知）
  → developer（修正）
    → tester（再実行）
      → security-auditor（再監査）

ドキュメントレビューFAIL差し戻し（横断ドメイン；ポスト挿入型）

doc-reviewer（DOC_REVIEW_RESULT: fail）
  → トリガーエージェント（spec-designer / ux-designer / architect /
                        scope-planner / analyst）による修正
    → doc-reviewer（再チェック）

上記の他の 4 種の差し戻しフロー（tester / reviewer / security-auditor に対するプリ挿入型）とは異なり、この差し戻しは上流のマークダウン生成エージェントが完了した後に発動します。トリガーエージェントは doc-reviewer の TRIGGERED_BY フィールドで特定されます。差し戻しプロンプトテンプレートは .claude/orchestrator-rules.md §Doc Review FAIL Rollback Flow を、差し戻し上限超過時の処理は §Approval Gate after Doc Review FAIL を参照してください。

Discoveryの差し戻し：実現不可能な要件

poc-engineer（blocked、BLOCKED_ITEMS > 0）
  → interviewer（ユーザーと代替案を協議）
    → researcher（必要に応じて再調査）
      → poc-engineer（再検証）

sandboxの2層防御

Aphelionは危険なコマンド実行を防ぐために2つの相補的なレイヤーを使用します。sandbox モードの設定詳細は .claude/rules/sandbox-policy.md を参照してください。

flowchart TB
    subgraph Advisory ["Advisory Layer"]
        direction LR
        Policy["sandbox-policy.md\n(auto-loaded rule)\nrisk categories:\nrequired / recommended / optional"]
        Permission["Claude Code\nPermission Mode\nallow / ask / deny"]
        Policy --> Permission
    end

    subgraph Enforcement ["Enforcement Layer"]
        direction LR
        Infra["infra-builder\ngenerates devcontainer"]
        Container[".devcontainer/devcontainer.json\ndocker-compose.dev.yml\n(container isolation)"]
        Infra --> Container
    end

    Command["Bash command\nfrom agent"] --> Advisory
    Advisory --> FallbackCheck{"container\navailable?"}

    FallbackCheck -->|Yes| ContainerExec["container\nexecution"]
    FallbackCheck -->|No| PlatformCheck{"platform\ndetected?"}

    PlatformCheck -->|claude_code| PlatformPerm["platform_permission\n(permission mode)"]
    PlatformCheck -->|unknown| CategoryCheck{"required\ncategory?"}

    CategoryCheck -->|No| Advisory2["advisory_only\n(warning only)"]
    CategoryCheck -->|Yes| Blocked["blocked\n(execution denied)"]

    Enforcement -.->|provides| FallbackCheck

フォールバック順: container → platform_permission → advisory_only → blocked

正規ソース

.claude/rules/aphelion-overview.md — ワークフローモデルと設計原則（自動ロード）
.claude/orchestrator-rules.md — トリアージ、ハンドオフスキーマ、承認ゲート、差し戻しルール
.claude/rules/agent-communication-protocol.md — AGENT_RESULT形式とSTATUSの定義