| name | hanzo-ask |
| description | hanzo・HANZO・foodiesプロダクトの仕様・実装・DBテーブルに関する質問に回答する。蓄積済み知見→ドキュメント→ソースコード→DBの優先順位で参照し、素早く正確に回答して知見を蓄積する。「hanzoの〇〇の仕様は？」「このテーブルの役割は？」「〇〇の実装はどうなってる？」のような質問時に使う |
hanzo-ask コマンド
hanzo プロダクトに関する質問に、素早く正確に回答するためのコマンド。
引数
$ARGUMENTS にユーザーの質問が入る。引数が空の場合は、ユーザーに質問内容を聞く。
質問
$ARGUMENTS
言い訳テーブル（省略禁止事項への先制反論）
以下の思考が浮かんだら、それは手抜きのサインである。右列に従うこと。
| 言い訳 | 現実 |
|---|
| 「回答は済んだので知見の蓄積は省略してよい」 | 蓄積がこのskillの本体価値。ステップ4を完了するまでこのコマンドは未完了 |
| 「小さい質問だったので log 記録は不要」 | 参照のみでも (参照のみ) として1行記録する（ステップ5） |
| 「知見が古そうだが確認は面倒なので黙っておく」 | 最終確認日が1ヶ月超＋コード参照ありなら警告必須（ステップ6） |
| 「キャッシュに書いてあったのでそのまま断定してよい」 | 不確実な部分は明示する。矛盾に気づいたらクロスナレッジに反映する |
| 「関連はテキストで『関連: xxx.md』と書けば十分」 | 必ず [[]] リンク記法を使う |
| 「トンネルもパスワードも揃っているので query-db は読み込まずに psql を直接叩いてよい」 | query-db には実行手順（説明→SQL提示→実行→結果表示）が定義されている。DBを叩く前に毎回 Skill ツールで読み込む |
| 「subagent が叩いたSQLは見えないので回答に書けない」 | subagent には実行した全SQLを返させ、メインセッションの回答に明示する |
情報ソース（優先順位順）
- 蓄積済み知見:
~/work/google_drive/hanzo-ask/knowledge/ 内のドメイン別ファイル
- ビジネスロジック系:
knowledge/*.md
- DB・テーブル設計系:
knowledge/database/*.md
- 知見ファイルには2種類ある（下記「知見ページの種別」参照）:
- ユニットナレッジ: 1トピックを調べきった理解の結晶（大半のファイル）
- クロスナレッジ: 複数のユニットナレッジを束ねた構造ノート（例:
ordering-overview.md）
- ドキュメント:
~/work/foodies/HANZO-DOCS/（サブモジュール）
- ソースコード:
~/work/foodies/（プロダクトリポジトリ）
- DB:
query-db skill で実データを確認（必要に応じて）。必ず Skill ツールで query-db を読み込んでから実行する（psql の直接実行は禁止）
回答フロー
0. Lint モードの判定
質問が --lint で始まる、または「点検」「健全性チェック」等の依頼であれば、回答フローではなく references/lint.md を読んで全件点検モードを実行する。
1. 知見キャッシュの確認
まず ~/work/google_drive/hanzo-ask/INDEX.md を読み、関連するドメインファイルがあれば読み込む。
- DB・テーブルに関する質問の場合は
knowledge/database/ 以下も確認する
- クロスナレッジ（
ordering-overview.md 等）があれば優先的に確認し、[[]] リンク先のユニットナレッジも辿る
キャッシュに十分な情報があれば、それをもとに素早く回答する。
このとき、読み込んだ知見ファイルの最終更新日を控えておく（後述の自発 Lint で使う）。
2. 不足があればソースを調査
キャッシュだけでは不十分な場合、以下を調査する：
- HANZO-DOCS のドキュメント
- foodies リポジトリのソースコード
- 必要に応じて DB（
query-db skill を使用）
調査は Agent ツールを活用して並列で行い、回答速度を優先する。
DB に問い合わせる場合のルール:
- メインセッションで叩く場合: 必ず Skill ツールで
query-db を読み込み、その手順（説明→SQL提示→実行→結果表示）に従う。トンネルやパスワードが既に揃っていても省略しない
- subagent に DB 調査を任せる場合: subagent のプロンプトに「実行した全SQLを結果と共に返すこと」を必ず含める。メインセッションは回答の中で、subagent が実行したSQLをコードブロックで明示する
3. 回答
- 結論を最初に述べる: 回答の冒頭に「結論」と「その根拠の要約」を記載し、詳細はその後に展開する
- 簡潔かつ正確に回答する
- コードやテーブル構造を示す場合はマークダウンで整形する
- 不確実な部分は明示する
- ソースコードを紹介する場合は GitHub URL を付ける:
git -C ~/work/foodies rev-parse HEAD でコミットハッシュを取得する- URL形式:
https://github.com/goals-inc/foodies/blob/{commit_hash}/{ファイルパス}#L{開始行}-L{終了行}
- 例:
https://github.com/goals-inc/foodies/blob/e3712ab0fdea9a9613697194ffea87eb8fe4b4b6/app/models/shop.rb#L10-L20
4. 知見の蓄積
回答後、得られた知見を ~/work/google_drive/hanzo-ask/knowledge/ に自動で蓄積する。
- 既存のドメインファイルがあれば更新（Edit）
- 新しいドメインであればファイルを新規作成（Write）。新規作成時は
references/knowledge-formats.md のフォーマットに従う
- DB・テーブル関連の知見は
knowledge/database/ 以下に保存する
- テーブル構造、リレーション、実際に使ったSQLなどを記録
- ファイルは対象ドメイン別に分割（例:
shops.md, companies.md）
INDEX.md のドメイン一覧も更新する- 関連ファイルは
[[ファイル名]] 記法でリンクする（拡張子は省略。例: [[ordering-overview]]）。テキストの「関連: xxx.md」ではなく必ず [[]] を使う
- 新規ファイルには H1 直下に種別マーカー（
> 種別: unit knowledge / cross knowledge）を付ける
- 複数トピックを横断する知見が溜まってきたら、ユニットナレッジとは別にクロスナレッジを作る/更新する（下記「知見ページの種別」参照）
- 蓄積はバックグラウンドで行い、ユーザーへの回答を遅延させない
5. 操作ログの記録
回答後、~/work/google_drive/hanzo-ask/log.md の先頭付近（最新が上）に1行追記する。
YYYY-MM-DD | {質問の要約（30字程度）} | {作成/更新したファイル, ...}
- 質問にしか答えず知見を更新しなかった場合も、
(参照のみ) として記録してよい
- 日付は会話コンテキストの currentDate を使う
- log の記録もユーザーに通知しない
6. 自発 Lint（回答末尾にさりげなく添える）
通常回答の最後に、以下の2つを控えめにチェックして該当時のみ提案を添える。回答本体は遅延させない。
コード参照とは（陳腐化判定の前提・以下で共通）
知見ファイルがソースコードに依存していることを示す記述。次のいずれかを含めばコード参照ありとみなす:
- ソースパス言及:
app/...・lib/...・web/app/... などのパス、または .rb/.py ファイル名
- GitHub URL:
github.com/goals-inc/foodies/blob/...
検出例:
grep -lEq '(app|lib)/[a-z_/]+\.(rb|py)|github\.com/goals-inc/foodies/blob' {ファイルパス}
最終確認日とは（陳腐化判定の基準日・以下で共通）
ファイルの「鮮度」は mtime だけでなく、--lint でコード乖離なしと確認した日も加味する。
最終確認日 = max(mtimeの日付, .lint-verified に記録された確認日)
.lint-verified は ファイルパス: YYYY-MM-DD の行を持つ（無ければ verified 日なし＝mtime のみで判定）。これにより、点検でクリーン確認したばかりのファイルは mtime が古くても警告しない。
(a) 使ったファイルの陳腐化チェック（毎回）
回答に使った知見ファイルそれぞれについて:
stat -f "%Sm" -t "%Y-%m-%d" {ファイルパス}
grep "^{ファイルパス}:" .lint-verified
- 最終確認日（上の定義）が 1ヶ月以上前 かつ そのファイルがコード参照を含む（上の定義）場合のみ、回答末尾に1行：
⚠ {ファイル名} は約N ヶ月前の知見です。コードが変わっている可能性があります。/hanzo-ask --lint {ファイル名} で点検できます。
- コード参照を含まない（ビジネス概念のみ）ファイルや、最終確認日が1ヶ月以内のファイルでは騒がない
(b) 低頻度の全体サマリ（前回点検から14日経過時に一度だけ）
~/work/google_drive/hanzo-ask/.lint-state を読む（無ければ新規）。last_full_scan: YYYY-MM-DD を持つ。
- 今日（currentDate）が
last_full_scan から 14日以上経過していたら、knowledge/ 全体を軽く走査し、stale（最終確認日が1ヶ月以上前＋コード参照あり）ファイル件数を回答末尾にサマリ表示：
🩺 前回点検から14日経過。コード参照付きの知見 N 件が1ヶ月以上未更新です。/hanzo-ask --lint で全体点検できます。
- 表示したら
.lint-state の last_full_scan を今日の日付に更新する（次の14日間は出さない）
- 14日未満なら何もしない
知見ページの種別
知見は2種類に役割分けする。foodies のコードが一次資料（Raw source）であり、knowledge/ はそれを調べて得た理解の蓄積である点に注意。
- ユニットナレッジ（unit knowledge）: 1つのトピックを調べきった理解の結晶。新しく調べたドメインはまずこれを作る。
- foodies の複数箇所に散らばる実装＋DB/Redash 調査を、1トピックに再構成したもの。「1ソース＝1要約」ではなく、最初から横断的な再構成が入る。
- 価値はコードのコピーではなく、コードを読むだけでは得られないものにある: 閾値・分岐条件・ハマりどころ・調査で確かめた実データの挙動・関連ファイルの地図。
- Zettelkasten の permanent note（atomic note）に相当。
- クロスナレッジ（cross knowledge）: 複数のユニットナレッジを束ねて全体像を合成する構造ノート（例:
ordering-overview.md）。点在する知見が線でつながったときに作る/更新する。各トピックへの地図＋横断的な気づき＋未解決の問いをここに集約する。
- Zettelkasten の structure note に相当。
新規調査や横断的な質問のとき、関連する既存ページを読み返し、新しい知見・矛盾があればクロスナレッジ側に反映する。
種別マーカー: 各知見ファイルは H1 見出しの直下に種別を1行で明示する（フロントマターがある場合も H1 の直下に置く）。新規作成時は必ず付ける。
> 種別: unit knowledge （または cross knowledge）
各種フォーマットのテンプレートは references/knowledge-formats.md を参照（新規作成・再構成時に読む）。
教科書ガイド（ユーザーが明示的に求めたときだけ）
ユーザーが「教科書で勉強したい」「教科書のどこに載ってる？」「教科書で言うとどこ？」などと明示的に言った場合のみ、references/textbook.md を読み、その手順に従って教科書の該当章・節（＋ページ）を案内する。
- 例: 「📖 『HANZO自動発注の教科書』第7章 出数比率（p.52）」
- 自発的には出さない。通常の回答末尾に教科書案内を勝手に添えない
ビジュアライゼーション出力
ユーザーが「図解して」「フロー図を作って」「HTMLで可視化して」などと依頼した場合：
必ず references/visualization.md を読んでから、その仕様（出力先・既存ファイルの扱い・スタイル・ファビコン）に従って出力する。
アウトプット出力
ユーザーが「アウトプットを出して」「SQLを出力して」などと依頼した場合：
~/work/google_drive/hanzo-ask/output/yyyymmdd/ ディレクトリに出力する（yyyymmdd は当日の日付）- ファイル名は内容に応じて適切に命名する（例:
shop_analysis.sql, order_summary.sql）
- 出力前に「このSQLで何を実現するか（結論）」と「アプローチの要約」を伝えてからファイルを出力する
- 出力後、ファイルパスをユーザーに伝える
Lint（知見の健全性チェック）
/hanzo-ask --lint（または「点検して」「健全性チェック」）で起動する全件点検モード。
必ず references/lint.md を読んでから実行する（点検項目5種と出力・修正のルールが書かれている）。
並列調査・大規模点検（subagents / Workflow / agent-teams）
調査が単一セッションでは重い・広いときは並列化する。規模と性質で手段を選ぶ。
- 既定: 単一セッション。たいていの質問はこれで足りる。
- subagents / Workflow（独立ファンアウト）: 多数のファイル／サブシステムを独立に調べる・点検するとき。例:
--lint のコード乖離を全 knowledge ファイルで並列点検する。各ワーカーは結果を返すだけで相互通信は不要。コストは控えめ。独立ファイル編集・順序依存の作業はこちら。
- agent-teams（協調・相互検証）: チーム同士が議論・相互反証しながら詰める複雑な調査のとき。例: 「発注サジェスト不発の原因」を競合仮説で並列検証する／発注フロー全体をフロント・バック・Lambda 横断で多視点レビューする。
- 実験的機能。
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が有効なセッションでのみ使える。無効なら subagents / Workflow にフォールバックする。
- 起動はリーダー（このセッション）が「N人のチームで〜を調査」と spawn する。3〜5人が目安。
- トークンコストが高いため、agent-teams を使う前にユーザーに一言確認してから起動する。
判断の目安: 「結果だけ欲しい／独立に手分け」→ subagents・Workflow。「視点をぶつけ合って結論の確度を上げたい」→ agent-teams。迷ったら subagents から。
注意事項
- SQLを出力する際は
sql-format スキルのルールを必ず適用する（小文字キーワード、行頭カンマ、where 1=1 等）
- 回答速度を最優先する。キャッシュで答えられるならキャッシュから答える
- 知見の蓄積はユーザーに通知しない（バックグラウンドで自動実行）
- Staging DB への接続が必要な場合は、SSHトンネルの状態を確認してから実行する
- 各ドメインファイルは200行以内に収める。超えそうな場合はドメインを分割する
パーミッション
このコマンドの書き込み先は ~/work/google_drive/hanzo-ask/ 配下のみである。
以下の操作は、ユーザーに許可を求めずに自動で実行してよい：
- ファイルの読み込み（
~/work/foodies/ 等のソースコード・ドキュメント）
~/work/google_drive/hanzo-ask/ への書き込み（知見の蓄積・アウトプット出力・ビジュアライゼーション）- データを変更しない読み取り専用の操作全般（grep、glob、コード検索など）
データの書き換えなど、破壊的な副作用のある操作は対象外。
