base-in-reality

base-in-reality

このスキルにおける MUST、MUST NOT、SHOULD、SHOULD NOT、MAY というキーワードは、すべて大文字で記載されている場合に限り、BCP 14（RFC 2119、RFC 8174）に記載された意味で解釈されます。

読み取り専用で、調査に基づくリポジトリ監査です。リポジトリ内の注目すべき設計上の判断ごとに、次の問いに答えます。確かな情報源に照らして証明できる形で、確立された規範、標準、アルゴリズム、またはベストプラクティスに違反しているか？

最も重要なルールは、権威を捏造しないことです。 すべての指摘は、エージェントがセッション中に実際に取得した情報源に結び付ける MUST があります。根拠のない主張は UNCONFIRMED として報告する MUST があり、違反として報告してはなりません。取得した情報源のない違反は、権威の捏造にあたるためです。

使用する場面

コードベース、アーキテクチャ、またはビジネスロジックを、最新の知見やドメイン標準と照らし合わせて妥当性確認したいときに使用します。例：「APR の計算は融資の規範に沿って正しいか？」「暗号技術は NIST に準拠しているか？」「このコンセンサス方式は妥当か？」「ML の評価で既知のデータ漏洩の落とし穴を回避できているか？」などです。あらゆるリポジトリに対応し、そのドメインに適応します。

不変条件（違反しないこと）

1. コードを編集してはなりません。 これは読み取り専用の監査であり、修正するかどうかはすべてユーザーが決めるためです。--annotate が挿入するのはコメントマーカーのみで、ロジックは変更しません。このスキルがデフォルトのパスに作成する唯一のファイルは、docs/base-in-reality/ 配下のレポートです。書き込む前にファイル名をユーザーに伝える MUST があり、ユーザーが作業ツリーを変更したくない場合は、代わりに会話内でレポートを提示する MUST があります。
2. 引用を捏造しないこと。 このセッションで取得した URL／DOI だけを引用する MUST があり、取得の証明も必要です。BIR_EVIDENCE_LOG を設定して取得し、その後 --evidence を使って lint を実行してください。fetched: true はエージェント自身が行う主張です。証拠ログがあることで、その主張を検証できます。根拠がない場合は UNCONFIRMED とします。references/verdict-rubric.md を参照してください。
3. 反証のゲート。 VIOLATION／DEVIATION は、反証の検証を通過しない限り報告してはなりません。これにより、最初の検証者が過剰に解釈した指摘が、レポートに記載される前に見つかります。
4. 黙って切り捨てないこと。 --max-claims によって抽出件数が制限された場合、除外した項目をレポートの「Dropped-claims log」に列挙する MUST があります。

フラグ

• --annotate — 指摘箇所に # BASE-IN-REALITY[<sev>]: <one-line> — see <report> マーカーも挿入します（コードに触れる唯一のモード）。デフォルト：オフ。
• --layer algo|arch|biz — 対象を1つのレイヤーに限定します。デフォルト：3つすべて。
• --domain <x> — 自動検出されたドメインを上書きします。デフォルト：自動。
• --since <ref> — <ref> との差分のみを監査します。デフォルト：リポジトリ全体。
• --max-claims N — 1回の実行での指摘数を制限します。デフォルト：40。

手順

Python インタープリター。 このスキルとそのリファレンスに記載されたコマンドのほとんどは python3 を使用します。最初のコマンドを実行する前に、使用するインタープリターを特定してください。$SKILL_PYTHON が設定されている場合は、それを使用します。設定されていない場合、macOS で command -v python3 の出力が /usr/bin/python3 であり、xcode-select -p が失敗するなら、その python3 はインストール用スタブです。実行せずにスキップしてください。スキップ対象ではなく、<interpreter> -c 'import sys; sys.exit(sys.version_info < (3, 10))' が終了コード 0 で終了するもののうち、python3、python、py -3 の順で最初のものを使用します。すべてのコマンドで python3 の代わりに見つけたインタープリターを記述し、提案する Bash(...) の許可ルールにも同じものを記述してください。uv run または {python} で始まるコマンドは、それぞれの形式のままにします。Bash(...) 許可リストのもとで再開したセッションでは、この確認を省略し、許可リストに記載されたインタープリターを使用してください。どれも条件を満たさない場合、このスキルに Python を使わずに実行するための代替手段が記載されていれば、それに従ってください。記載されていなければ処理を中止し、このスキルには Python 3.10 以降が必要であることをユーザーに伝えてください。

次の6つのステージを実行します。指定された箇所ではサブエージェントを並行して実行してください（ファンアウト）。Claude Code では、代わりに assets/workflow.mjs を Workflow ツールに渡し、決定論的な高速化手段として使用できます。これは並列ファンアウトを使ってステージ2／4／5を実行します。以下の手順は、どの環境でも使える方法です。 ソースヘルパーの場所を特定する（最初に実行してください）。 同梱の fetch_sources.py は、このスキルのディレクトリを基準とする相対パスで参照されていますが、検証サブエージェント（ステージ 4）はここではなく、対象リポジトリ を作業ディレクトリとして実行されます。そのため、assets/fetch_sources.py のようなパスではサブエージェントがファイルを見つけられません。サブエージェントを起動する前に、ヘルパーの絶対パスを一度解決し、各サブエージェントのプロンプトに渡してください。

• このスキルのベースディレクトリ（スキルの読み込み時にハーネスから提供されます）を使用し、FETCH="$SKILL_DIR/assets/fetch_sources.py" を設定します。
• ベースディレクトリが分からない場合は、次のコマンドで特定します。 FETCH=$(find ~/.claude ~/.config ~/.agents -path '*base-in-reality*/assets/fetch_sources.py' 2>/dev/null | head -1)
• パスが解決されることを確認します。python3 "$FETCH" --source openalex --query test --limit 1 を実行すると、JSON が出力されるはずです。（uv run "$FETCH" でも同じです。このスクリプトの依存関係は dependencies = [] と宣言されており、標準ライブラリのみをインポートするため、python3 はどの環境でも動作し、uv は必須ではありません。）
• 相対パスの assets/ で始まる形式では対象リポジトリから解決できないため、サブエージェントには $FETCH の絶対パスをそのまま渡す必要があります。
• フェッチを開始する前に、エビデンスログを開き、すべてのサブエージェントが継承できるようにエクスポートしてください。 export BIR_EVIDENCE_LOG="$(mktemp -t bir-evidence-XXXXXX.jsonl)"。各取得で実際に返された URL／DOI が追記され、ステージ 6 でレポートと照合されます。これを行わないと、fetched: true フラグはエージェント自身の申告にすぎず、リンターもそのように判断します。

1. 対象範囲とドメインの検出。 言語、依存関係マニフェスト、ディレクトリ構成、README／ドキュメント、DB スキーマ／マイグレーション、設定を調査します。references/domains.md の検出シグナルを使ってドメインを分類し、規範の対象領域を確定します。--domain と --since を遵守します。ドメインマップを作成します。

2. 主張の抽出（ファンアウト）。 リポジトリの各領域をサブエージェントに割り当てます。それぞれ、{layer (algo|arch|biz), location (file:line), confidence, domain-tag} のタグが付いた、個別の反証可能な主張を返します。主張とは、コードが何を行うかについて検証可能な記述です（例：「パスワードのハッシュ化に MD5 を使用している」「リクエスト処理経路で 12 のサービスに同期的にファンアウトする」「APR を単利として計算している」）。統合して重複を除きます。--max-claims を適用し、超過分は Dropped-claims ログに記録します。

3. ソースのルーティング。 各主張について、references/source-routing.md に従って優先順位付きのソース計画を選びます（アルゴリズム→arxiv／Semantic Scholar、セキュリティ→NIST／RFC／OWASP、医療→PubMed、フィンテック→規制当局＋標準、一般→Scholar／JSTOR／OpenAlex）。

4. 検証（ファンアウト、根拠に基づく）。 各主張について、サブエージェントを起動し、まず同梱のソースヘルパーを上記で解決した絶対パス $FETCH から使って、キー不要の API にクエリを送信します（python3 "$FETCH" --source <s> --query "<q>" --limit <n>。絶対パスをそのままサブエージェントに渡してください。スキル相対の assets/ で始まるパスでは対象リポジトリから解決できません）。次に、標準規格や有料記事について WebSearch／WebFetch を使います。UNCONFIRMED より強い判定をする前に、少なくとも 1 件の取得済みソースを確保する必要があります。assets/findings.schema.json に準拠した調査結果を出力します。verdict ∈ {VIOLATION,DEVIATION,OUTDATED,UNCONFIRMED}、severity ∈ {critical,high,medium,low}、citations[]（取得した URL／DOI と根拠となる引用をそれぞれ含め、要旨のみ閲覧できた場合は abstract_only を付ける）、recommended_fix を含めます。

5. 反証（ファンアウト、敵対的）。 VIOLATION／DEVIATION の候補ごとに、references/verdict-rubric.md に従い、異なる観点（正確性、引用の適用可能性、重大度）から独立した反証担当を起動します。それぞれ、まず懐疑的な立場を取ります。重大度が medium／low の調査結果については、3 人中 2 人以上が反証した場合、またはそれ以外の重大度（critical、high、未指定、未知のいずれか）の調査結果については、反証担当が 1 人でも反証した場合、UNCONFIRMED に格下げします。何も返さない反証担当も、反証したものとして数えます。調査結果が残るかどうかにかかわらず、投票結果を調査結果の refutation フィールドに記録します。

6. 統合します。 レポートを作成する前に、統合した検出結果の配列を、付属のコントラクトリンターで検証します。検出結果を一時 JSON ファイルに書き込み、次を実行してください。 python3 "$SKILL_DIR/assets/report_lint.py" <findings.json> --evidence "$BIR_EVIDENCE_LOG". このリンターは、スキーマの列挙値と根拠付けの不変条件を決定的に検証します（取得済みの引用がない VIOLATION／DEVIATION は却下されます。出力する前に UNCONFIRMED に格下げしてください）。また、--evidence を指定すると、fetched: true の各引用を、実際に取得処理で返された URL と照合します。そのため、もっともらしく見えても取得されていない DOI は、根拠があるものとして処理されず、失敗します。反証も検証します。記録された refutation がない VIOLATION／DEVIATION、またはステージ 5 の投票で格下げが指示されている VIOLATION／DEVIATION が残っている場合は、却下されます。PASS は、記録された投票と判定が一致していることを意味します。投票が誠実に行われたことを意味するものではありません。--evidence を付けて必ず実行してください。結果行には実行モードが示されます。これを付けずにリンターを実行した場合、検証されるのは形式だけです。すべての ERROR: 行を修正してから、assets/report-skeleton.md に記入してください。docs/base-in-reality/<YYYY-MM-DD>-audit.md へのレポート作成は、このスキルで --annotate 以外に想定される唯一の書き込みです。作成前に必ずその旨を伝えてください。ユーザーが作業ツリーを変更しないことを希望する場合は、代わりに会話内でレポートを出力してください。レポートには、エグゼクティブサマリー、ドメインマップ、検出結果（重大度、次にレイヤーの順で並べます）、出典の付録、却下した主張のログを含めます。--annotate を指定した場合は、各検出結果の位置にコメントマーカーを挿入してください。

出力スタイル。 レポートとユーザー向けの説明は、ASD-STE100 簡易英語の基準を約 80％適用して書いてください。短い文を使い、一般的な語を選び、能動態で書いてください。各手順では、アクションを 1 つだけ示してください。

参考資料

• references/source-routing.md — 主張クラスと出典クラスの対応表、API の使用方法、エチケット。
• references/verdict-rubric.md — 判定の分類、重大度、根拠付けのルール、反証。
• references/domains.md — ドメイン検出のシグナルと、ドメインごとの標準的な表面規範。

アセット

• assets/fetch_sources.py — 学術情報源をキーなしで検索するヘルパー（stdlib、uv run）。
• assets/findings.schema.json — サブエージェントが出力する検出結果のスキーマ検証用ファイル。
• assets/report_lint.py — スキーマ、根拠付けの不変条件、反証ルールに基づいて検出結果を判定する stdlib リンター（ステージ 6）。
• assets/report-skeleton.md — ステージ 6 で記入するレポートテンプレート。
• assets/workflow.mjs — 任意で使える Claude Code Workflow アクセラレーター。

エッジケース

• 出典の網羅性にばらつきがある場合。 arxiv／PubMed は充実しています。JSTOR／ISO は要旨からしか確認できません。そのような引用には abstract_only と記し、根拠の深さが分かるようにしてください。
• ドメインを誤検出した場合。 ドメインマップはレポートの先頭に示してください。--domain で上書きできます。
• 大規模なリポジトリ。 ディープモードでは、主張ごとに検証と反証の両方へ処理が分岐し、トークンを多く消費します。--layer、--since、またはより小さい --max-claims で対象範囲を絞ってください。
• 「ベストプラクティス」に異論がある場合。 正当化できる逸脱には VIOLATION ではなく DEVIATION を優先してください。反証パスは、スキルが唯一の正しい方法を断定しないようにするためのものです。