AGENTS.md — Sourceglass におけるAIエージェントの行動規約

このリポジトリで作業するすべてのAIエージェント（CodeX / Claude Code / その他）が従う規約。 作業を始める前に必ず全部読むこと。

0. 最初に読むもの

設計はすでに確定している。ゼロから考え直さないこと。

ファイル	内容
`ai_tasks/README.md`	最初にこれを読む。ドキュメントの索引と、どこに何を書くかのルール
`ai_tasks/context_snapshot.md`	現在地・直近の作業・次の一手
`ai_tasks/decisions.md`	決定台帳。「なぜそうなっているのか」の唯一の入口
`ai_tasks/20260804_sourceglass_mvp_design/task.md`	要件・技術調査結果・技術選定の根拠
`ai_tasks/20260804_sourceglass_mvp_design/implementation_plan.md`	Phase 0〜6 の作業指示
`ai_tasks/20260804_sourceglass_mvp_design/roadmap.md`	v0.1 / v0.2 / v0.3 の方針
`ai_tasks/20260804_sourceglass_mvp_design/copy.md`	UI 文言の確定版
`ai_tasks/20260804_sourceglass_mvp_design/design.md`	ビジュアル仕様（トークン・反転・アイコン）
`ai_tasks/20260804_sourceglass_mvp_design/fixtures.md`	テストフィクスチャ仕様

設計判断に異論がある場合は、実装する前に人間に相談する。 黙って別の設計にしない。

1. 絶対に破ってはいけないルール

これはプロダクトの存在理由に関わる。「良かれと思って」でも破らない。

1.1 推測しない

禁止	なぜ
確率・スコア・パーセント表示（`AI probability: 87%` 等）	推測を事実として提示することになる
「AI生成ではありません」「安全です」「問題ありません」	来歴情報の不在は不使用の証明ではない
画像の内容・画素から AI を判定する処理	Sourceglass は永久に AI 判定器にならない
画像分類モデル・ヒューリスティックによる画質判定	同上

ウォーターマークのデコード（v0.2 以降）は例外ではなく、そもそも推測ではない。 誤り訂正が通る形でペイロードを復元できたかどうかの離散的な事実であり、確率表示は不要。

1.2 外部にデータを出さない

画像・メタデータ・解析結果を、いかなる外部サービスにも送信しない
LLM API / AI検出 API を呼ばない
実行時にネットワークを必要とする依存ライブラリを追加しない
WASM・モデル等のアセットは必ず同一オリジンから配信する（第三者 CDN 禁止）
- 画像が漏れなくても「誰がいつ使ったか」は漏れる。これも避ける
アクセス解析を将来入れる場合も、画像・メタデータ・解析結果は絶対に収集しない

1.3 禁止語

製品名・機能名・変数名・UI 文言・README のいずれでも使わない。

禁止	理由
`Proof` / `Verify` / `Authentic` / `Proven`	「証明した」と読まれる
`Detect`（AI検出の意味で）	AI 検出器だと誤解される。メタデータについては `found` を使う
「安全」「問題なし」「クリーン」	判定していないものを判定したことになる
`%` を伴うあらゆる表現	確率表示の禁止

適用範囲 — 禁止するのは「主張」であって「否定」ではない

このルールが止めたいのは Sourceglass がそれをしたと読める用法である。

用法	可否
製品名 / 機能名 / 変数名 / UI のラベル・見出し	常に禁止
「〜を証明しました」「検証済みです」	禁止（主張）
「〜を証明するものではありません」「AI ではないと断定しません」	必須（限界の説明）
「`AI probability: 87%` のような表示は行いません」	必須（何をしないかの明示）

否定文で限界を述べるために禁止語を使うのは、ルールの目的そのものである。 ここで言い換えると免責が弱くなり、ルールが意図と逆に働く。

判断に迷ったら: その文はこちらの能力を大きく見せているか、小さく見せているか。 小さく見せているなら、禁止語が入っていても正しい。

1.4 UI の見せ方

✓ と緑を使わない。 記号と色は文言より速く強く伝わり、「安全のお墨付き」と誤読される
色を使うのは AI 関連の記録が見つかった場合だけ
NO_PROVENANCE_INFORMATION は破線、NO_AI_RELATED_PROVENANCE_FOUND は実線で区別する（この2つの混同が最大のリスク）
免責文言は結果の直下に常時表示し、折りたためないようにする
Summary の空欄は空白にせず — で埋める（空白は「調べていない」に見える）

編集禁止ファイル

以下はデザイン仕様そのものであり、設計担当が管理している。編集しないこと。 コンポーネントからは、ここで定義されたクラス・コンポーネントを当てるだけにする。

src/styles/tokens.css      色・書体・スケール・余白のトークン
src/styles/base.css        全コンポーネントのスタイル
src/components/Icon.tsx    アイコン（自前 SVG）

新しいクラスやアイコンが必要になった場合は、実装せずに相談する。 これらのファイルはハッシュで保護されており、変更すると design:guard が落ちる。

デザインガード

npm run design:guard    # 規約違反を検査（CI で実行）

検査内容: 色リテラルの直書き / トークンの再定義 / Web フォント読み込み / ✓ などの記号 / テキスト記号（カラー絵文字化） / 4px を超える角丸 / 確率表示 / 「安全」「問題なし」といった断定。

ガードが落ちたら、ガードを緩めるのではなく実装を直すこと。 design-guard-ignore を安易にコメントへ書かない。

ビジュアルは design.md が仕様。装飾ではない。 特に:

強調は地と図の反転であり、色相ではない。反転は見出し行のみ（ブロック全体は禁止）
Web フォントを読み込まない（外部リクエスト = プライバシー要件違反）。システムフォントのみ
テキスト記号（⚠ 等）を使わない。自前 SVG を使う（カラー絵文字化でモノクロが破綻する）
日本語を等幅ブロックに入れない。詳細テーブルに和訳ラベルを置かない

1.5 README は英日を同時に更新する

README.md（英語）と README.ja.md（日本語）は同じ内容を保つ。 片方だけ更新しない。 特に「限界」「プライバシー」「AI判定をしない」の節がずれると、言語によって約束が違うという最悪の状態になる。

1.6 文言を勝手に書き換えない

copy.md の文言は設計思想そのもの。言い換え・要約・「自然な表現への修正」を禁止する。 変更が必要だと判断した場合は、実装せずに人間に相談する。

2. アーキテクチャの境界

2.1 解析エンジンは UI から独立している

src/features/provenance/ は React / DOM / window に依存してはならない。 将来 npm パッケージ・CLI として切り出すための境界である。

File / Blob / ArrayBuffer は Web 標準として使ってよい
canvas による画素デコードなど DOM が必要な処理は src/platform/ に置き、注入する
src/features/inspector/（UI）→ provenance の一方向依存のみ。逆向きの import は禁止

2.2 検出器はプラグインとして足す

新しい来歴ソースを追加するときは:

src/features/provenance/detectors/<id>/ を作る
Detector インターフェースを実装する
engine/registry.ts に1行足す

既存の detector の中に分岐を足して対応しないこと。

2.3 ルールは宣言的テーブルで書く

判定ロジックを parser のコードに散らさない。各ルールテーブルは detectors/*/rules.ts に置き、rules/index.ts が集約する。

2.4 「情報が無い」と「解析に失敗した」を混同しない

SourceResult<T> は present / absent / error / not-checked の4状態。 この区別を潰す実装をしない。 ユーザーに見せる意味がまったく違う。

absent = 調べたが、無かった
not-checked = 調べていない（未対応形式 / 実行を要求されていない）

スキップした detector を absent にしないこと（D-029）。「ウォーターマークを調べたが無かった」と「一度も見ていない」を同じ値で表すのは、このプロダクトが最もやってはいけないことである。

C2PA では実測上、次のように分かれる（implementation_plan.md D5）。

C2PA 無し → reader が null → absent
破損 / 0バイト → 例外 → error

2.5 integrity と signer trust を混同しない

validation_state: "Valid" と signingCredential.untrusted は同時に成立する（実測）。

integrity = ハッシュ・署名の整合が取れているか
signerTrust = 発行者が信頼できるか

この2つを1つのフィールドにまとめない。 まとめた瞬間にこの製品は嘘をつく。 MVP はトラストリストを設定しないので signerTrust は常に 'not-evaluated'。 signingCredential.untrusted を 'not-trusted' にマップしないこと（言い過ぎになる）。

integrity === 'invalid' のとき、C2PA 由来の AI シグナルを explicit にしない。

2.6 プライバシーの保証は CSP に置く

外部通信を止めているのは CSP であって、ライブラリの設定ではない。 remoteManifestFetch: false などは多層防御であり、効かなくても安全な位置づけ。

公開型に無い設定に依存する箇所は detectors/c2pa/settings.ts の1ファイルに閉じる
パッケージ型への declaration merging をしない（アップグレードで静かに壊れる）
README や UI に「SDK の設定で無効化している」と書かない

3. 実装ルール

any 禁止。 strict: true + noUncheckedIndexedAccess: true
例外を握りつぶさない。SourceResult.error に載せて coverage.failed に記録する
非情報系の読み手を想定し、複雑なロジックには JSDoc を書く
既存の命名・構成・トーンに合わせる。不要な大規模リファクタをしない
ProvenanceReport は structured-clone 可能に保つ（Worker 越しに渡すため）
C2PA の WASM リソースは finally で必ず free() する

依存パッケージ

追加は原則禁止。 必要なら理由を添えて人間に相談する。現在の許可リストは implementation_plan.md Phase 1 を参照。

判断基準:

実行時にネットワークを使わないか
ライセンスが MIT 本体と両立するか（MPL-2.0 は無改変利用なら可）
メンテナンスされているか

例外: @types/*（DefinitelyTyped の型定義のみのパッケージ）は個別承認を不要とする。 ビルド時に消えるため、上記3基準のどれにも触れないため。ただし:

必ず devDependencies に置く
実行時コードを含まないことを確認する
@types/node のメジャーは、実際に使う Node のメジャーに合わせる（CI の Node も固定する）

C2PA の API を推測で書かない

@contentauth/c2pa-web の型・JSON 構造は、必ず実物を確認してから実装する。 node_modules の .d.ts を読む、スパイクで実際の出力を取る、のどちらかを行う。「ドキュメントによると」で実装しない。旧 c2pa npm パッケージは deprecated なので使わない。

4. テスト

フィクスチャは fixtures.md の一覧に従う。Phase 2 着手前に揃える
フィクスチャをリサイズ・再保存しない。 再エンコードでテスト対象のメタデータが消える
algorithmicMedia（非AI）を AI 判定しない回帰テストを必ず維持する
実物の AI 生成画像（fixtures/real/）は verdict を厳密にアサートしない （上流サービスの出力変更で CI が壊れる）
変更後は最低限これを通す:

npm run typecheck && npm run test && npm run design:guard && npm run build

プライバシー検証（npm run test:e2e）は、解析パス・依存・CSP に触れたら必ず実行する。

5. Git

git commit / git push / git reset --hard を実行しない。 コミットメッセージ案の提示に留め、実行は人間に任せる
.gitignore を勝手に変更しない
.env / 秘密情報 / トークンを表示・変更しない
ai_tasks/ は gitignore しない（設計判断の記録を残す方針）

6. 作業ログ（ai_tasks プロトコル）

どこに何を書くかは ai_tasks/README.md §3 が正本。 要点:

コードを変更したら、同じ作業の中で ai_tasks/context_snapshot.md を更新する
context_snapshot.md は現在地だけ。常に上書き。60行以内に保つ。伸びてきたら変更履歴になっている。decisions.md へ逃がすこと
含める内容: Current Topic / Working Agreement / Last Actions / Next Step / Resume Prompt
判断・選択・却下した案は ai_tasks/decisions.md に1エントリ追記する。 決定を黙って書き換えない。覆すなら新しい番号で追記し、古い方に取り消し線を引く
同じ根拠を2箇所に書かない。 片方が必ず腐る。 decisions.md は「何を・なぜ・詳細はどこか」だけを持ち、実装の詳細は仕様側に置いてリンクする
各ファイル冒頭の # Last Updated: YYYY-MM-DD HH:mm を更新する
Phase 0 のスパイク結果は spike_result.md に実際の JSON とログを貼る。要約で済ませない

7. 人間への報告

内部の思考過程ではなく、以下を簡潔に:

現状分析 / 影響範囲 / 実装方針 / 変更内容 / 次の作業
変更した主要ファイルと、型チェック・テストの結果
テストが落ちたら落ちたと書く。 通っていないものを通ったと書かない
スキップした作業があれば、何をなぜ飛ばしたか明記する

8. 迷ったときの判断基準

その機能・その文言は、ユーザーに「Sourceglass が判定してくれた」と思わせないか？

思わせるなら、実装せずに相談すること。 Sourceglass の価値は機能の多さではなく、言えないことを言わないという一点にある。

FilesExpand file tree

AGENTS.md

Latest commit

History