ひとくちだけゲート (hanipman-gate)
ひとくちだけ。 まるごと全部、ぶちまけるな。
AIがコードを書き始めてから、ボトルネックが移動した。生成は速くなったが、理解は変わらない。60ファイルのdiffが一度に降ってくると、人間は3分で熟読を諦め、ざっと目を通すだけになる。
このリポジトリは、そのボトルネックを規律ではなく構造に移したツール群です。Claude Codeプラグインマーケットプレイスを通じて配布します。
何をするか
設計議論
│
├─ ledger decide ────────▶ 決定原⼭
│ ├ 現在の設計（確定したもののみ・アトミックに置き換え）
│ └ 決定ログ（append-only・SUPERSEDEDを保持）
│ │
│ current --topicのみ読み取る（ドキュメント全体は読まない）
│ ▼
└─ /impl-pipeline ──▶ スライス分解 ──▶ 委任 ──▶ /review-gate ──▶ /change-walkthrough
│ │
GREENのみ ▼
通過 人間が読むのは
"判断が必要なものN件"
三つのルールだけです。
設計ドキュメントをまるごと読まない。 委任するときにドキュメントパスを渡さず、確定した決定の本文だけをプロンプトに入れる。トークンコストがドキュメントの長さと無関係になる。
ゲートを通過したdiffだけが人間に届く。 診断・規約・設計整合性・範囲逸脱を先に実行する。レビュー時間はdiffの総量ではなく、判断が必要な項目数に比例する。
状態は手で書けない。 複数のリポジトリにまたがる作業の完了状況は、読み取り専用プローブがリモートに直接問い合わせて計測する。わからなければ「未検証」のままにする。嘘の「完了」よりはマシだ。
インストール
/plugin marketplace add 5hseok/hanipman-gate
/plugin install design-pipeline@hanipman-gate
プラグインは3つに分かれています。必要なものだけインストールしてください。
| プラグイン | 内容 | いつ使うか |
|---|---|---|
design-pipeline | 決定原⼭ → スライス → ゲート → レビューガイド | 設計して実装するとき。これが本体 |
track-ledger | 複数リポジトリ・セッションの順序をプローブで実測 | セッションを複数動かしたり、デプロイ順序が絡むとき |
explain-aids | 設計・diff理解のためのインタラクティブHTML | 大きな変更を他人（または未来の自分）に説明する必要があるとき |
session-board | セッション状況を1枚のアーティファクトに | トラック文書までは不要で、「今どこまで進んでいるか」だけ見たいとき |
スキル
design-pipeline
| スキル | 役割 |
|---|---|
design-workflow | ポリシー原本。原⼭ルール・リーディングプロトコル・チェックポイントコミット・リスクティア |
impl-pipeline | オーケストレーター。設計をスライスに切り、ゲートまで実行する |
review-gate | 自動ゲート。診断・規約順守・設計整合性・範囲逸脱 |
change-walkthrough | レビューガイド。変更をリクエストフローの順序で再配置する |
design-reconcile | 原⼭の衛生管理。古い内容を移動する（削除はしない） |
convention-audit | 規約検査。review-gateから実際に呼び出される |
track-ledger
| スキル | 役割 |
|---|---|
track-ledger | トラックの作成・運用 |
track-ledger-policy | 不変ルールとセッション間通信の基準 |
session-board
| スキル | 役割 |
|---|---|
session-board | Claudeセッションレジストリを読み、ボードをアーティファクトとして公開し、同じURLで更新する |
CLIもサーバーも不要。track-ledgerが重く感じられる場合は、こちらから先に使っても構いません。
explain-aids
| スキル | 役割 |
|---|---|
explain-design-html | 実装前。なぜこの方向性なのか、何を捨てたのか |
explain-diff-html | 実装後。何がどう変わったのか |
explain-skills-workflow | 上記2つをいつ提案するかの基準 |
設計上の判断
ゲートは非対称です。 規約違反はREDで止めますが、「設計と違うか」は止めずに判断リストとして渡します。規約はルールベースで確実ですが、設計整合性はLLMの判断であり誤検出が混ざるため、誤検出で正当な実装が止まり続けると人間がゲートを切ってしまうからです。
部分的な失敗を全体の失敗にしない。 raw diffが真実であり、成果物は補助です。成果物の生成に失敗しても、失敗を報告するだけでレビューは止めません。
スライスはコミットではありません。 レビューの境界とコミットの境界を分けています。エージェントはコミットを提案できますが、実行はしません。
説明コメントを書かない。 変更理由をコードコメントに残しません。それはレビューガイドが担います。コメントはコードを汚しますが、ガイドはコードの外にあり、レビューが終われば破棄されます。
要件
- Claude Code
- Python 3（標準ライブラリのみ。サードパーティ依存なし）
- git
以下はオプションですが、あれば大きく変わります。
- codebase-memory MCP —
change-walkthroughの核心的な成果物である「影響を受けるが未修正」（変更されたコードを呼び出しているが、それ自体は変更されていないコード）は、実際のコールチェーンを抽出して初めて得られます。これがないと、この項目全体が欠落します。 gh・aws・terraform— トラックプローブが使用します。ない場合、該当ステップは「未検証」のままになります。
原⼭はどこに置いてもよい
スキルは原⼭がどこにあるか知りません。ledgerだけを呼びます。
ledger current --file <task> --topic <slug> # 確定した決定のみ。ドキュメント全体は読まない
ledger decide --file <task> --topic <slug> --title ... --supersedes D-3
ledger doctor # どのバックエンドがなぜ選ばれたか
デフォルトはリポジトリ内のmarkdown（.claude/design/）です。Obsidian vaultを使っている場合は、~/.claude/ledger.jsonにパスだけ書けば既存のドキュメントをそのまま使えます。
{ "backend": "obsidian", "root": "/path/to/vault" }
詳細はdocs/adapter-contract.mdを参照してください。
まだわかっていないこと
作成者のマシンでは動きますが、以下はまだ確認できていません。
- 他人の環境でゼロからセットアップしたことがない。
markdownバックエンドで空のリポジトリとの往復は確認しましたが、実際にインストールして一サイクルを回したのは作成者の環境だけです。 markdownバックエンドでパイプライン全体を完走したことがない。 アダプターの往復は検証しましたが、impl-pipeline→review-gate→change-walkthroughをmarkdown原⼭で最後まで回したことはありません。- 日本語以外のプロジェクトでどのように読まれるかわからない。 ヘッダーはエイリアスマップで両方を認識しますが、スキル本文・ゲートレポート・ボードUIは日本語です。
- レビュー時間が実際に削減されたか測定したことがない。 設計意図は「diff総量ではなく、判断が必要な項目数に比例する」ですが、前後比較データがありません。
例
examples/に原⼭ドキュメント一式とトラックドキュメント一式があります。どちらも実際のツールで作成し、読み直して検証したものなので、仕様が間違っていることはありません。
ライセンス
MIT。 LICENSEを参照してください。
名前
「ひとくちだけ」。他人が食べているものを全部くれとは言わず、ひとくちだけ欲しいという言葉。このツールがエージェントに対して言っている言葉でもあります。
gateは二つのシステムの共通言語です。パイプライン側にはreview-gateがあり、トラック原⼭側のステップはフィールドそのものがgate: merge / gate: apply / gate: deployです。