hanzo-ask

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を返させ、メインセッションの回答に明示する

情報ソース（優先順位順）

1. 蓄積済み知見: ~/work/google_drive/hanzo-ask/knowledge/ 内のドメイン別ファイル
   • ビジネスロジック系: knowledge/*.md
   • DB・テーブル設計系: knowledge/database/*.md
   • 知見ファイルには2種類ある（下記「知見ページの種別」参照）:
     • ユニットナレッジ: 1トピックを調べきった理解の結晶（大半のファイル）
     • クロスナレッジ: 複数のユニットナレッジを束ねた構造ノート（例: ordering-overview.md）
2. ドキュメント: ~/work/foodies/HANZO-DOCS/（サブモジュール）
3. ソースコード: ~/work/foodies/（プロダクトリポジトリ）
4. 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" {ファイルパス}   # mtime を取得
grep "^{ファイルパス}:" .lint-verified        # 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、コード検索など）

データの書き換えなど、破壊的な副作用のある操作は対象外。