QQQuestionAI

いま書いたコードの差分から記述式5問を出題し、 「本当に分かって実装しているか」を確認する学習支援AIです。 答えは教えず、段階的なヒントだけを提示します。 コミットはしないので、いつでも気軽に実行できます。

特徴

• 1〜2問目は知識問題、3〜5問目は書いたコードに由来する問題 が出ます。 前半で前提知識を、後半でいま書いた実装そのものへの理解を確認します。
• 問題には難易度があり、正解するごとに上がり、間違えるごとに下がります。 実力に合わせて出題が調整されます。
• 一度間違えた問題は、もう一度出題されやすくなります。 取りこぼした理解を繰り返し確認できます。
• 答えは教えず、不正解なら段階的なヒント、降参なら解説を提示します。

下は実際の出題画面（第3問／難易度2・書いたコードに由来する問題）の例です。

想定用途と、想定していない用途

このツールは、コードを書いた本人が、自分の理解度を自分で確かめるための自習用ツールです。 出題・判定・ヒント・解説はすべて AI（大規模言語モデル）が生成するため、判定は誤ることがあります。 正解を不正解と判定することも、その逆もあります。

次の用途には使用しないでください。そのように設計されておらず、必要な検証も受けていません。

• 学校・研修における成績評価、単位認定、修了判定
• 採用選考、人事評価、査定など、人の処遇を決める判断
• 本人以外が、他者の能力を測定・記録・比較する目的

なぜ明記しているか: EU AI Act では、教育・職業訓練の場で学習成果の評価に用いられる AI システムは 高リスクに分類され得ます。その場合、導入する側（学校・企業など）に適合性評価や人的監督といった 義務が生じます。本ツールは自習用途を前提としており、高リスク用途向けの適合性評価は受けていません。 組織として学習者の評価に導入することを検討している場合は、まず自組織の法務にご確認ください。

外部に送信されるデータ

問題を作るために、この拡張はあなたのコードを外部の AI サービスに送信します。 導入前に必ずお読みください。

• 送信はあなたのマシンから、あなた自身の API キーで直接行われます。 この拡張の作者のサーバーは経由しないため、作者があなたのコードを見ることはできません。
• 対話履歴・苦手傾向・ログはあなたのマシン内にのみ保存されます（外部送信されません）。
• 社外にソースコードを出せないリポジトリでは使用しないでください。 業務で使う場合は、お勤め先の規程と Google の API 利用規約を確認してください。

Web 検索について: 通常のインストールでは検索ライブラリ (ddgs) が入らないため、 Web 検索は発生しません。設定 qqquestion.pythonPath で ddgs 入りの Python を指定した場合、 または環境変数 TAVILY_API_KEY を設定した場合にのみ行われます。 明示的に止めるには環境変数 QQQ_NO_SEARCH=1 を設定してください。

デモモード (qqquestion.fakeLlm) について: Gemini へのコード送信は行われませんが、 上の条件に当てはまる環境では Web 検索だけは動きます（コードは送られません）。

費用について

Gemini API の利用料金は、あなたが設定した API キーに対して課金され、あなたの負担になります。 この拡張は無料ですが、利用料を拡張の作者が負担することはありません。

• 既定では gemini-3.5-flash を使用します（環境変数 QQQ_MODEL で変更できます）。
• 1回のコミットにつき、複数回の API 呼び出しが発生します（出題で1回、解答の判定で5問ぶん、 さらにヒントや解説を求めるたびに追加で呼び出されます）。コミットのたびに積み上がる点にご注意ください。
• 無料枠の有無・単価・レート上限は Google が随時変更するため、 最新の情報は必ず Gemini API の料金ページでご確認ください。
• 使いすぎが心配な場合は、Google Cloud / AI Studio 側で予算アラートや上限を設定できます。 課金の管理はキーの所有者であるあなた自身の責任で行ってください。
• 料金をかけずに動作だけ試したい場合は、設定 qqquestion.fakeLlm を有効にしてください（呼び出しゼロ）。

セットアップ

準備は3ステップです。リポジトリの clone は不要です（Python バックエンドは拡張に同梱されています）。

はじめに: コマンドパレットの使い方

セットアップは VSCode のコマンドパレットから行います。これは VSCode の機能を名前で検索して 呼び出す窓で、ターミナルとは関係ありません（git commit のように打ち込むものではなく、 メニューから項目を選ぶ操作です）。

1. VSCode で Cmd+Shift+P を押す （Windows/Linux は Ctrl+Shift+P）。画面の上部中央に検索窓が出ます
2. QQQuestion と入力すると、この拡張の項目だけに絞り込まれます
3. 目的の項目を選んで Enter

以下で「コマンドパレットから〈○○〉を選ぶ」と書いてある箇所は、すべてこの操作を指します。

1. Python 3.11 以上を入れる

ターミナルで python3 --version と打ち、3.11 以上が表示されれば OK です。 無ければ python.org 等から入れてください。

VSCode の初回起動時に、拡張が専用の仮想環境を自動作成して依存をインストールします （数十秒かかります。2回目以降は再利用されるので待ち時間はありません）。

2. API キーを設定する

このキーの利用料はあなたの負担になります（費用について）。

1. Google AI Studio で Gemini の API キーを取得する （AIza... で始まる文字列です）
2. コマンドパレットから「QQQuestionAI: API キーを設定」を選ぶ
3. キーの入力欄が出るので、貼り付けて Enter

キーは VSCode の安全な保管領域（SecretStorage）に保存され、以降は自動でバックエンドに渡されます。 環境変数を自分で設定する必要はありません。設定ファイルにも書かれないので、誤ってコミットする心配もありません。

キー無しで試したいだけなら、設定 qqquestion.fakeLlm を有効にしてください。 ダミーの問題が出るデモモードで動きます。

キーを入れ替える・消すときは、同じ項目をもう一度選んでください （空のまま Enter で削除できます）。

3. 使ってみる（セットアップはこれで完了）

追加のセットアップは不要です。git add してから、コマンドパレットで 「QQQuestionAI: クイズを開始」を選べば出題が始まります。

この拡張は git の挙動を一切変更しません。 クイズはコミットをしませんし、 結果がコミットを妨げることもありません。フックもシェル設定の書き換えも不要です。

既存の Python 環境を使いたい場合は、設定 qqquestion.pythonPath にその Python の 絶対パスを指定してください（自動作成された venv より優先されます）。

このリポジトリ自身を clone して開発している場合は、ワークスペースの backend/ とその .venv が優先的に使われます（同梱物ではなくソースで動きます）。 この場合は backend/.env に GOOGLE_API_KEY=... を書く方法も使えます。

使い方

1. コードを書いて git add する
2. コマンドパレット（Cmd/Ctrl+Shift+P）から「QQQuestionAI: クイズを開始」を選ぶ
3. クイズパネルが開くので、5問に記述式で解答する （不正解なら「ヒント」、降参は「ギブアップ」）
4. 5問完走するとレポートが表示される。コミットは行われません（いつでも中断できます）

ターミナルから使う（quiz コマンド）

VSCode の統合ターミナルでは、そのまま quiz と打つだけで使えます（拡張が自動で PATH を通します）。

git add .
quiz          # ステージ済み差分から出題。コミットはしません

外部のターミナル（iTerm 等）でも使いたい場合は、コマンドパレットから 「QQQuestionAI: ターミナルの quiz コマンドを設定」を選ぶと、シェル設定に 追記する1行が表示されます。

quiz は VSCode が起動しているバックエンドに接続して動きます（API キーは 拡張が安全に保管しているため、ターミナル側にキーを置く必要はありません）。 そのため VSCode を開いていない状態では使えません。

（任意）コミット前に必ず問われるようにしたい場合

強制力が欲しい人向けに、pre-commit フックを用意しています。対象リポジトリを開いて コマンドパレットから「QQQuestionAI: pre-commit フックをインストール」を選んでください （リポジトリごとに1回）。

導入後は、明示的に指定したときだけクイズがコミットをゲートします。

QQQ_QUIZ=1 git commit -m "..."   # 5問完走でコミット続行、中断でコミット中止
git commit -m "..."              # 素の git。クイズは発動しない

素の git commit や git commit -q は影響を受けません。-q は git 本来のフラグ （出力抑制）なので、これを乗っ取る旧来のシェル関数方式は廃止しました。 以前のバージョンで ~/.zshrc に追記された # >>> QQQuestionAI: のブロックが 残っている場合は、削除してください。

コマンドパレットの項目一覧

Cmd+Shift+P →「QQQuestion」で以下が出ます。

設定

API キーはここには含まれません。設定ファイルに平文で残さないため、 コマンドパレットの「QQQuestionAI: API キーを設定」から SecretStorage に保存します。

トラブルシューティング

• 問題が生成されない・すぐ「完走」と表示される場合は、まず API キーを疑う。 キーが未設定のままバックエンドが起動すると「API キーが未設定のため、問題を生成できません」と 警告が出るので、そこから設定できる。キーが原因でなければバックエンドのログ backend/data/server.log（QQQ_DATA_DIR 変更時はそのディレクトリ内）を確認する。 LLM 呼び出しの失敗理由（レート制限・APIキー無効・タイムアウト等）が生のエラー付きで記録される
• 「クイズを開始」しても始まらない場合は、git add でステージ済みの差分があるかを確認する （差分が無いと「ステージ済みの差分がありません」と案内が出る）
• QQQ_QUIZ=1 git commit でゲートが働かない場合は、対象リポジトリで 「QQQuestionAI: pre-commit フックをインストール」を実行済みかを確認する
• 「バックエンド未起動のためスキップします」と出てコミットが通るのは正常な設計（fail-open）。 クイズが受けられないことを理由にコミットを壊さないため。出題したい場合は、 QQQuestionAI 拡張を入れた VSCode でそのリポジトリを開いた状態でコミットする
• 対象リポジトリに backend/ や scripts/ が無いのは正常。バックエンドは拡張に同梱されて おり、拡張が別プロセスで起動する。フック（.git/hooks/pre-commit）が使うのは curl / git / python3 だけで、対象リポジトリにこのプロジェクトのソースを置く必要はない。 また .git/hooks/ は git の管理対象外なので、git ls-files に出てこないのが正常
• 同じログは VSCode の出力パネル「QQQuestionAI」チャンネルにも流れるが、 ウィンドウを閉じると消えるため、後から調べるときはログファイルを見る
• .vsix を再インストールしたときは、開いている全ウィンドウの再読み込みが必要 （リロードするまで古い拡張がメモリ上で動き続ける）