shirusu 使い方ガイド

日常の使い方を場面別にまとめた実践ガイド。仕様の詳細は README、
思想は philosophy.md を参照。

0. 初期セットアップ (最初の5分)

cd ~/dev/AIWorkbenchOrchestrator
npm install && npm run build
npm link                 # どこからでも shirusu で起動できる

shirusu list runners       # 使えるAIを確認 (✓が1つも無くても mock で動く)
shirusu validate           # 設定ファイルの整合性チェック

AI CLI (claude / codex / agy) がインストール・ログイン済みなら自動で使われる。
何も無ければ --runner mock で仕組みだけ試せる。

1. 基本の型: プロジェクトに入って、話しかける

cd ~/work/client-a       # ← 作業したい案件のフォルダへ
shirusu

起動画面で「使えるAI」と「ナレッジ件数」を確認したら、やりたいことを普通の日本語で
書くだけ。受付係 (Concierge) が3択で捌く:

その場で答えられる質問 → すぐ返事が来る
情報が足りない → 質問される (最大3つ)。答えると次へ進む
作業依頼 → タスク化され、確認画面が出る

─ このタスクを作成・実行します ─────────
  Title: 請求書催促メールの作成
  Scope: restricted   External AI: あり
  ...
実行しますか? [y/N/edit/draft]:

y = 実行 / N = やめる / edit = タスクを手で直してから / draft = タスクだけ保存して後で
実行が終わると final.md (成果物) が画面に表示される。成果物は常に「下書き」— 送信やコピペ利用の前に必ず目を通す

2. 場面別レシピ

メール・文面を作る

shirusu › 取引先に請求書の催促メールを送りたい。先月も催促してる。柔らかめで

条件 (宛先・トーン・背景) を先に言うほど一発で決まる。足りなければ聞かれる。

さっきの成果物を直す (追い込み修正)

shirusu › さっきのメール、もう少し丁寧にして締めの一文を足して

直前の run の final.md が自動でタスクに引き継がれる。セッションを閉じた後なら
shirusu -c で前回の会話の続きから再開できる。

比較・選定の判断材料が欲しい

shirusu › NASをクラウドに移行するか迷ってる。判断材料をまとめて

decide ワークフロー (調査→比較表→リスク→レビュー) が走る。
結論を出すのは自分。final.md は「条件つき推奨」までしか書かない。

プロジェクトのファイルを読ませて整理する

cd ~/work/client-a && shirusu --scope public   # ← ファイルを読ませる宣言が必要
shirusu › このdocsフォルダの仕様書を読んで、今の運用フローを整理して

ファイルの中身まで読ませるには --scope public (対話中は /scope public) が必要。
既定の restricted は「明示的に渡したものだけ外部AIへ」の安全側なので、
ファイル一覧は受付係に伝わるが、中身は読めない (読めない場合は実行前に警告が出る)。
public を宣言すると、AIランナーがそのフォルダを読み取り専用で参照できる。

機密データを扱う (外部AIに出したくない)

shirusu --scope private          # このセッションは外部AIに一切送らない

private では claude / codex / antigravity が候補から自動的に外れる。
実用にはローカルLLMを推奨: ollama を導入し
export AI_ORCH_LOCAL_MODEL=<モデル名> を設定すると private でも実AIが使える。

Backlog の課題からタスクを作る

# 事前に: .shirusu/config.yml に base_url、GUI の Connectors で token を設定
shirusu source backlog https://<space>.backlog.jp/view/PROJ-123           # 中身を確認
shirusu source backlog https://<space>.backlog.jp/view/PROJ-123 --save all # ナレッジ化
shirusu
shirusu › PROJ-123 の課題内容をもとに、先方への回答文面を作って

取得した情報は自動ではAIに渡らない。--save で保存したものだけが使われる。

重要なタスクで品質を上げる (depth)

一発回答で済まない仕事 (公開記事・提案資料・重要メール・仕様設計) は、
AIに粘らせる。深さは4段階で、対話なら「じっくり詰めて」「粘って」で deep になる。

shirusu run tasks/public-article.md --depth deep     # 勝利条件→生成→破壊→修正→仕上げ
shirusu run tasks/xxx.md --depth extreme             # deep + 2案選抜 + 3票レビュー
shirusu run tasks/xxx.md --best-of 2                 # 2案生成して採点選抜 (点差も記録)
shirusu run tasks/xxx.md --review-votes 2            # レビューを2票の合議にする

deep では成果物の前に勝利条件と採点基準を作らせ、生成後に別のAIが破壊レビューし、
指摘を潰した改訂版を採点基準で審査する。何を壊しどう直したかは decision-log の
「粘りの工程」節に残る。時間・コストは概ね2〜3倍 — 深くやるべき仕事にだけ使う。

3. KOKUIN (判断の記録) を使う

すべての run に、成果物と一緒に「なぜそのAIに任せたか」の記録が残る。

したいこと	方法
直近の判断ログを見る	対話中に `/trace`
人間確認が必要な点を見る	`/audit` (承認・修正・却下は `/feedback approve 問題なし` 等で記録)
月次の証跡レポートを出す	`shirusu audit export --month 2026-07` → 納品資料にそのまま添付できる
モデルの実績を見る	`shirusu stats` (どのモデルが何点取っているか)

納品への添付が段階0の実践: final.md と一緒に decision-log.md / audit export を
渡せば、「AIをどう使い、人間が何を確認したか」を顧客に示せる。

4. GUI を使う

cd ~/work/client-a && shirusu serve   # → http://127.0.0.1:3777

ターミナルが苦手な場面 (過去runの見返し・ナレッジ整理・設定変更) はGUIが楽
New task 画面から自然言語→タスク化→実行もできる (CLIと同じ安全確認つき)
プロジェクトごとに完全分離。複数案件は --port を変えて同時起動できる

5. ナレッジを育てる

global (<shirusuホーム>/knowledge/): 全案件共通 — メール署名、文体ルール、自社情報
project (<案件>/.shirusu/knowledge/): 案件固有 — 顧客の背景、案件ルール
1ファイル1テーマ、1行目に内容が分かる見出しを書く (索引に使われる)
run の履歴は knowledge/history/ に自動で貯まり、次回の判断に使われる
/knowledge で一覧確認

最初に置くと効く3つ: メール署名テンプレ / 文体・トーンの好み / よく使う定型文。

6. scope / log-level の使い分け

場面	設定
ふだん	既定のまま (restricted / redacted) — 変更不要
AIにプロジェクト全体を見せて作業させたい	`--scope public`
顧客の機密・個人情報・経理データ	`--scope private` (+ ollama)
ログを最小限にしたい共有PC等	`--log-level minimal`

対話中は /scope で確認・変更できる。どの設定でもシークレットのマスクは常時有効。

7. 困ったとき

症状	対処
どのAIが使えるか分からない	`shirusu list runners` / 起動バナー
runが途中で失敗した	表示された `--resume runs/...` で再開
出力の質が低い	条件を具体化して再依頼 / `--best-of 2` / knowledgeに文体・前提を追加
なぜこのモデルが使われた?	`/trace` (decision-log の「モデル選定」に候補→除外→採用の経緯)
ディスクが気になる	`shirusu clean --days 30`
画面が崩れた	ウィンドウリサイズで再描画 / パイプ実行なら正常 (プレーン出力)

8. チートシート

shirusu                 # 対話モード (基本これだけ)
shirusu -c              # 前回の会話の続き
shirusu --auto          # 実行前のy/n確認を省略
shirusu serve           # GUI
shirusu stats           # モデル実績
shirusu audit export    # 月次証跡レポート
/trace /audit /feedback /knowledge /scope /mode /draft /copy /runs /status /help