[ux] User personas + 出力 mode 設計 (agent / researcher / CI / library)

[sotashimozono]

Question

doiget の user persona と、各 persona に対する UX / 出力 mode。

Personas

A. Agent (Claude Desktop / Cursor / Codex / Continue)

• 経路: MCP stdio
• 入出力: structured (JSON-like Result types)
• 期待: 同じ入力 = 同じ出力 (idempotent), error は明示 type で
• non-interactive

B. Researcher (souta 自身、その他物理屋)

• 経路: CLI (doiget fetch ...)
• 入出力: 人間可読 (色付き、絵文字 OK、verbose)
• 期待: 進捗表示、helpful error messages、autocomplete
• interactive

C. CI / Batch processor

• 経路: CLI (doiget batch refs.txt --json)
• 入出力: JSON line / JSON array
• 期待: exit code 厳格、log は stderr、stdout は pure data
• non-interactive, scripted

D. Vault maintainer (BiblioFetch.jl との共有 store を運用する人)

• 経路: library (doiget を Rust crate として直接 use)
• 入出力: typed Rust API
• 期待: stable semver、minimal breaking change、no_std 不要

Output modes

Mode	Trigger	stdout	stderr
default (human)	TTY detected	色付き、絵文字、進捗 bar	warn / error
--json	flag	JSON object / array	log only
--quiet / -q	flag	結果 1 行 (success: path のみ)	error only
MCP context	serve mode	JSON-RPC structured	log only

Open questions

• default 出力に絵文字を入れるか？(Windows console の compatibility)
• progress bar crate: indicatif で確定？
• --quiet と --json の優先順序: --quiet --json で何が出る？
• MCP mode の log は実際の stdout に出ないように tracing-subscriber を厳格化する設計

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth).

立場

4 personas (Agent / Researcher / CI / Library) の分類は 妥当。 4 output modes (default / --json / --quiet / MCP) も基本路線は OK。

但し以下 5 点で、 「TTY 検出による暗黙 mode 切替」 / 「MCP mode の strictness」 / 「persona D (library) の API 範囲」 / 「localization」 / 「失敗 mode の persona 別表現」が underspecified なので、 解像度を上げる提案をします。

1. Mode 決定の暗黙 fallback は事故源

本文では default (human) の trigger が "TTY detected" になっていますが、 実運用で TTY 検出は信頼できない:

環境	stdout は TTY ?
Local terminal	yes
Local terminal + 2>&1 | tee	yes (stdout は依然 TTY)
GitHub Actions	conditional (一部 step は TTY あり)
Docker -it	yes
Docker run (no -it)	no
systemd journal	no
Cron / launchd	no
MCP stdio (subprocess)	no
Test harness (assert_cmd)	no

→ TTY 検出を fallback に降格 し、 explicit override を 1st choice にする:

Mode resolution order:

1. CLI flag --mode={human,json,quiet,mcp} (highest priority)
2. ENV DOIGET_MODE={human,json,quiet,mcp}
3. Subcommand-specific implicit (例: doiget serve → mcp 強制)
4. TTY detection (lowest fallback)
5. Default = quiet (not human, not json) — 安全側にした上で人間 user は flag / env で human を選ぶ

理由: silent failure / corruption を生むのは**「human mode を期待していたら json が出た」**ような無自覚 swap。 Default = quiet なら誤解の余地が小さい。

2. MCP mode は strict isolation が必要

本文 "MCP context: stdout = JSON-RPC structured、 stderr = log only" は正しいが、 実装上の hard requirement として以下を Phase 3 spec に lock:

• tracing-subscriber の global writer を 強制的に stderr に redirect。 serve subcommand で他 mode を指定しても上書き不可
• println! / eprint! の stdout 直書きは禁止 (clippy lint で禁止: clippy::print_stdout deny)
• 進捗 bar / 色 / 絵文字 / banner は すべて off (起動時の version banner も含む)
• panic 時の出力も stderr only。 std::panic::set_hook で強制
• Crate-level の audit: unwrap で発生した panic message が stdout に出ないこと

これは MCP host (Claude Desktop / Cursor) が JSON-RPC parser に noise を食わせると agent が crash する死に方を防ぐ。

3. Persona D (library) の API spec を Phase 0 から lock

本文 "library: typed Rust API、 stable semver" は方針として OK。 但し:

Crate 構成提案

crates/
├── doiget-core      # library API, no I/O policy
│   ├── src/lib.rs   #   Source trait / Store trait / CapabilityProfile
│   └── ...
├── doiget-cli       # binary `doiget` (depends on -core, -mcp)
└── doiget-mcp       # MCP server (depends on -core)

理由:

• doiget-core を library として publish。 doiget-cli / doiget-mcp を 別 binary として分離
• persona D (vault maintainer) は doiget-core のみを Cargo.toml に書けば足りる。 CLI / MCP の deps を引きずり込まない
• semver は doiget-core でのみ厳格に。 CLI / MCP は loose

Public API surface の Phase 0 commitment

pub trait Source { fn fetch(&self, r: &Ref, profile: &CapabilityProfile) -> Result<...>; }
pub trait Store  { fn read(&self, key: &Safekey) -> Result<Option<Metadata>>;
                   fn write(&self, key: &Safekey, m: &Metadata) -> Result<()>; }
pub struct Ref { ... }
pub struct Safekey(String);
pub struct Metadata { ... }
pub struct CapabilityProfile { ... }

これを Phase 0 で公開 spec として固定 (docs/PUBLIC_API.md)。 後続 Phase での拡張は 追加 trait / 追加 method のみ、 既存 signature の breaking change は major bump。

4. Localization は EN only に lock (少なくとも MVP まで)

本文 open question 「絵文字 / Windows console compatibility」 とは別 layer の話として、 本 Discussion で localization を確定すべき:

• error message / log は English only (Phase 0-3)
• README / docs/ に 日本語版を docs/ja/ に補助的に置く程度 (Phase 6+)
• 理由: agent 経路で error message を LLM が解釈する場合、 EN の方が安定する。 multilingual error は parser にとって不利

→ Phase 0 から EN-only コミット。 後で日本語化したくなったら別 Discussion で明示的に reopen。

5. 絵文字 / 進捗 bar の default OFF を提案

本文 open question への reviewer 回答:

• 絵文字: default OFF。 Windows Terminal (古い) / institutional VPN 経由の SSH terminal / VSCode の embedded terminal の一部で表示崩れ。 --emoji flag で opt-in。 DOIGET_EMOJI=1 env でも可
• 進捗 bar: default OFF。 stderr が TTY のときだけ ON。 CI で false-TTY が来たら大量の \r 制御文字が log に流れて読めなくなる。 --progress で明示 ON
• 色: clicolors-control crate を採用、 NO_COLOR env を尊重 (xdg standard)。 default は TTY 検出による fallback (mode 決定とは別 axis、 色は ON でも mode は quiet にできる)

6. --quiet と --json の優先順位

本文 open question への reviewer 回答:

• --quiet と --json を 同時指定可能。 意味は: JSON で minimal な field のみ出力 (e.g. {"path": "..."} だけ)
• --quiet --human の場合は path 1 行 (現 spec)
• --quiet 単独は default = --quiet JSON ではなく --quiet human (実用観点で path 取れる方が使いやすい)
• --mode=mcp は他 flag を全 override (subcommand-specific)

7. Persona 別の失敗 mode 表現

各 persona が「fetch 失敗」を どう知るかが本文では曖昧:

Persona	失敗の知らせ方
Agent (MCP)	structured FetchResult { ok: false, error: { code, message } }、 throw しない
Researcher (CLI human)	colored stderr message + 進捗 bar の該当行赤字、 exit code 1
CI (CLI json)	JSON Lines に {"ok": false, "error": ...}、 stdout は pure JSON のみ、 exit code = 失敗件数 (cap 255)
Library	Result<FetchResult, FetchError> (typed)、 anyhow ではなく thiserror

これを docs/ERRORS.md に taxonomy として書く (どの error code がどの persona でどう見えるか matrix)。

Reviewer Decision proposal

• 4 personas + 4 output modes は keep
• Mode resolution: CLI flag > ENV > subcommand-implicit > TTY > default quiet (TTY を fallback に降格)
• MCP mode は stdout に noise 0 byte を Phase 3 で hard-enforce (clippy lint + tracing redirect + panic hook)
• crate を doiget-core (lib) / doiget-cli / doiget-mcp の 3 分割
• Public API surface を docs/PUBLIC_API.md で Phase 0 から lock
• Localization は EN only (MVP)、 日本語版 docs は別 Discussion で reopen 必要
• 絵文字 / 進捗 bar は default OFF、 NO_COLOR 尊重
• --quiet + --json 同時指定で minimal JSON field
• docs/ERRORS.md で persona × error code matrix

最終 Decision 権は author に留保。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.