運用の手引き

Zenreiを日々どう回すか。覚えることは実質2つ——ふだんは何もしない、たまったら判を押す。それだけで成立するように設計されています。

導入

始め方——4ステップ

ZenreiをあなたのGitHubにつなぐ — GitHubの許可画面で、Zenreiに見せるリポジトリを選んで承認する（GitHubには外部サービスへ「選んだリポジトリだけ」のアクセス権を渡す仕組みがあり、これを使う）。承認すると、選んだリポジトリの decisions/*.md をZenreiが読めるようになり、push のたびに索引が自動更新される。決定ファイルはまだ無くてよい
権限はリポジトリ単位で、GitHubの設定からいつでも取り消せる。Zenreiが書き込むのは decisions/ 配下のコミット（承認・起票）だけ。セルフホスト版のデプロイ手順はリポジトリの docs/m1-setup.md、ローカル版（DBなし・stdio）はMCP登録に --root でパスを渡すだけ
エージェントにMCPを登録する — Claude Codeの例:
```
claude mcp add zenrei --scope user --transport http \
  https://<あなたのZenrei>/mcp --header "Authorization: Bearer <トークン>"
```
Cursor等でも同じリモートMCPを登録できる（ツール非依存）
CLAUDE.mdに運用3行を貼る — 次のセクション参照。これがエージェントにループを回させるスイッチ
最初の決定を1件書く — 直近で「蒸し返されて困った決定」を1つ、決定フォーマット（LPの「仕様」参照）で decisions/ に置いてコミットする。効果を最初のセッションから体感できる

日常

ふだんのループは、エージェントが回す

各リポジトリのCLAUDE.md（エージェント向け指示書）に次の3行を入れておくと、エージェントが自分でループを回します。

## 意思決定メモリ（zenrei）
- 作業開始時に get_context（scope: このリポジトリ名）で決定済み事項を把握すること
- 設計・方針を提案する前に check_proposal で照合すること
- 決定が必要な新しい論点は record_decision で起票する（承認するのは人間）

セッション開始 — エージェントが get_context を呼び、決定済み事項と「してはいけないこと」を読み込む
提案の前 — エージェントが check_proposal で照合。却下済み・保留中に当たれば、蒸し返しはここで止まる
新しい論点が出たら — エージェントが record_decision で起票する。作られるのは承認待ち（pending）の候補まで。エージェントは勝手に決めない

承認待ち

あなたの仕事は承認だけ。週に1回、承認キューを開いて本文を読み、「承認する／却下する」を押す（＝リポジトリへのstatus変更コミット）。pendingのまま放置しても害はありません——「まだ決定ではない」として配信されるだけです。

基準

何を決定として記録するか

迷ったらこの一問——「エージェントがこれを知らずに、望まない提案をしてくる可能性があるか？」 Yesなら記録します。

記録する

設計・技術選定の結論。採用したものと、却下した代替案の両方
「今はやらない」と判断したこと（保留）。再検討条件を必ず添えて
方針・原則（例:「MCPツールは5個で固定」）

記録しない

単なるタスク・TODO（タスク管理へ）
実装の経緯・検証ログ（作業ログへ。決定からはリンクで参照）
コードを読めばわかること

作法

良い決定ファイルの条件

check_proposal がエージェントに返すのは主にタイトルと理由。この2つに投資してください。

タイトル1行で決定内容がわかる（「〜する」「〜の導入（却下）」）
## 理由 には結論の言い換えではなく、判断の根拠を書く
却下・保留には ## 再検討条件 を書く。これがあると却下は議論の打ち切りではなく、条件付きの前例になる——条件成立を示した再提案は歓迎できる
経緯の詳細は決定ファイルに書かず、作業ログへのリンクにする（肥大化防止）

決定を覆すとき

ファイルを書き換えて歴史を消さない。必ず新しい決定で上書きします。却下→採用のような引き戻しができないのは意図的な仕様です——「一度却下され、状況が変わって覆された」という履歴全体が前例だからです。

管理画面の決定詳細から「この決定を覆す起票をする」で新決定を起票する（supersedes: [旧id] 付きのpendingになる。エージェントなら record_decision の supersedes 指定）
それを承認すると、旧決定は自動で superseded にコミットされる
旧決定は「失効・後継はこちら」として配信され、履歴も残る

追加

リポジトリを増やすとき

Zenreiの索引対象にリポジトリを追加する（ホスト版: GitHubのアクセス権設定でZenreiに見せるリポジトリを増やすと自動で同期される。ローカル版: MCP登録の --root に追加）
そのリポジトリのCLAUDE.mdに、上の運用3行を貼る
既存メモに埋まっている決定があれば、蒸し返されて困るものから数件だけ decisions/*.md に移す。全部移そうとしない

応急

困ったとき

決定が索引に出ない	frontmatterの不備が原因のことが多い。管理画面の「同期」にエラー内容（どのファイル・何が悪いか）が表示される。直してpushすれば自動で索引に入る
pushしたのに反映されない	webhookの取りこぼし。毎日の自動フル再同期で自己修復されるほか、管理画面の「同期」からいつでも再同期できる
承認ボタンがエラーになる	GitHub上のstatusが既に変わっている（手動編集と競合）。同期後にリロードすれば解消
蒸し返しを取りこぼした	照合は決定論的な字句一致のみ（設計どおり）。取りこぼした実例をメモしておく——それが照合強化（埋め込み検索）を導入するかの判断材料になる
エージェントがツールを呼ばない	そのリポジトリのCLAUDE.mdに運用3行が入っているか確認

禁忌

してはいけないこと

エージェントに status: accepted のファイルを直接作らせる — 承認フローの意味がなくなる。起票は必ず record_decision（pending）経由で
管理画面やDBだけで決定を管理しようとする — 正は常にリポジトリのmd。手で直したいときはmdを編集してコミットする（それが正規の手段）
決定ファイルに経緯を書き溜める — 理由は簡潔に、経緯はリンクで。指示書の肥大化はエージェントを遅くする