AI に答えを出させるのではなく、AI に問いを出させる。 業務を止めずにデバッグ能力を鍛え、その実力を評価できる形で可視化する、組織のための仕組み。
生成 AI で開発速度は上がりました。一方、組織の人材面では逆流が起きています。
- エラーが出たら AI に貼り付け、修正コードをもらう
- 動いたので次へ。なぜ壊れ、なぜ直ったかは分からないまま
- 次も同じ場所で詰まる
その結果、経営・人事の側に 3 つの困りごとが生まれます。
| # | 組織側の困りごと |
|---|---|
| 1 | メンバーの実力が見えない。 AI が下駄を履かせるため、成果物から地力を測れない |
| 2 | 育成が属人化している。 「エラーの読み方」を教えられるのは一部のシニアだけ |
| 3 | 評価の根拠が主観に寄る。 技術力の評価が印象と自己申告に依存している |
SocraMetry は、AI を「答えを出す道具」から「問いを出す道具」に反転させ、 デバッグ能力を業務の中で鍛え、同時に客観的に計測します。
| 対象 | 得られるもの |
|---|---|
| エンジニア（利用者） | 業務のエラーが解決する。かつ、次から自力で解けるようになる |
| 組織（導入者） | メンバーのデバッグ能力が数値で可視化され、育成と評価の根拠になる |
利用者にとっては業務支援ツール、組織にとっては人材可視化基盤。 この二重性が本製品の核です。
利用者は AI に直接質問できません。チャット欄はありません。 できるのはエラーを投げることと、提示された選択肢を選ぶことだけです。
✗ 従来 利用者 ──質問──▶ AI ──答え──▶ 利用者
✓ SocraMetry 利用者 ──エラー──▶ AI エージェント
│（内部で原因を特定するが言わない）
利用者 ◀──問い────────┘
│
└──思考──▶ 自力で到達
これは制限ではなく設計です。「AI に聞けば済む」という逃げ道を構造的に塞ぎます。
答えは最後まで隠すのではなく、本人が到達を試みた後に開示します。
┌─ Gate A ── ヒントのみ（設問なし） ──────────────┐ ★★★ 自力解決
│ 「エラーメッセージの後半に注目してみてください」 │
└────────────────────┬───────────────────────────┘
│ 進まない / 利用者の要求（条件付き）
┌─ Gate B ─────────▼───────────────────────────┐ ★★ 誘導ありで到達
│ 選択式の設問 Lv1 観察 → Lv5 修正 │
│ 「何が undefined だと言っていますか？ A/B/C/D」 │
└────────────────────┬───────────────────────────┘
│ 通過しても未到達
┌─ Gate C ─────────▼───────────────────────────┐ ★ 開示による解決
│ 原因・根拠・修正方針・再発防止策を開示 │
│ ＋ 振り返り 1 問（必須） │
└────────────────────────────────────────────────┘
どのゲートで解決したかが、そのまま評価値の主軸になります。 学習体験の設計と評価指標の設計が、ここで一本の線につながっています。
Gate C を用意するのは、業務を止めないためです。 開示を罰する設計にすると、利用者はツールを使わず直接 AI に聞きに行きます。 開示は敗北ではなく、正しい着地点の一つとして扱います。
| モード | 入力 | 目的 | 評価での役割 |
|---|---|---|---|
| 実務モード | 自分が遭遇したエラー | 業務支援 | 取り組み量と成長の観察。点数の横比較には使わない |
| 演習モード | 組織が割り当てた共通問題 | 育成・評価 | 横比較の主軸。同一条件のため評価値として成立する |
実務のエラーは難易度も文脈もバラバラなので、そのスコアで人を並べると不公平になります。 比較は演習モードで、成長の観察は実務モードで行います。
実務モードの問答は、匿名化・汎用化のうえ社内の問題集に蓄積できます。
実際に起きたエラー ──▶ 問答セッション ──▶ 匿名化・汎用化
│
新メンバーの演習問題 ◀── 社内問題集 ◀──┘
「うちの現場で実際に起きたエラー」が、そのまま「うちの新人が解くべき問題」になります。 外部の汎用教材では扱えない、その組織固有のつまずきどころが資産化されます。
熟練者が無意識に行うデバッグのプロセスを 5 段階に分解し、それぞれを独立した能力として測ります。
| 軸 | 測っているもの | 質問の例 |
|---|---|---|
| 観察 Observe | エラーを正確に読めるか | 「このメッセージは何が undefined だと言っていますか？」 |
| 切り分け Localize | 問題箇所を絞れるか | 「エラーが出る直前に、どの設定ファイルを変更しましたか？」 |
| 仮説 Hypothesize | 原因を推論できるか | 「ログ 3 行目のパラメータは、期待通りの型ですか？」 |
| 検証 Verify | 仮説を確かめられるか | 「その仮説が正しいと確認するには、まず何を出力しますか？」 |
| 修正 Fix | 再発しない直し方を選べるか | 「二度と起こさないために、どこに何を足しますか？」 |
5 軸に分けるのは、「技術力が高い / 低い」ではなく 「どこが強く、どこを伸ばすべきか」を言える形にするためです。
指標は、評価に使われた瞬間に歪みます（Goodhart の法則）。対策を設計に埋め込んでいます。
| 起きうること | 対策 |
|---|---|
| 詰まっても開示を使わず放置する | 開示による減点を小さく（係数 1.00 → 0.75）。業務停止の方が組織の損失 |
| 簡単なエラーばかり投げる | 難易度による正規化。難しい問題に挑むと係数が上がる |
| 経験年数の差がそのまま順位になる | 成長率を主指標にする。絶対値は補助 |
| 説明できない数値で人が評価される | 算出根拠を本人がいつでも確認できる。総合点だけの出力を許さない |
詳細は evaluation-model.md。ここが本製品のもう一つの中核です。
AI を使うこと自体が目的ではないため、使う場所と使わない場所を分けています。
| AI でなければできないこと | なぜルールベースで代替できないか |
|---|---|
| エラーから原因を推定する | エラーの種類は事実上無限。正規表現の辞書では未知のエラーや複合原因に対応できない |
| 今この人がどこを見落としているかに合わせて問いを作る | 同じエラーでも、直前の変更・使用 FW・これまでの回答で次に問うべきことが変わる。問いの個別化であり、テンプレートの選択では成立しない |
| もっともらしい誤答選択肢を作る | 誤答が馬鹿げていると消去法で解けてしまう。その文脈でありえた誤解を生成する必要がある |
| 自由記述の原因宣言が本質を捉えているか判定する | 「items が空だった」と「API が返る前に描画された」は同じことを指しうる。文字列一致では判定できない |
| あえて AI を使わないこと | 理由 |
|---|---|
| 答えが漏れていないかの検査（LeakGuard） | LLM に確認させると検査自体が確率的になる。ここは決定的なルールで行う |
| 秘匿情報のマスキング | LLM に送る前に処理する必要があるため、そもそも使えない |
| スコアの算出 | 同じデータから常に同じ値が出る必要がある（純関数） |
| レイヤ | 採用 |
|---|---|
| フロントエンド | フレームワークなし。HTML + CSS + 素の JavaScript（ビルドは esbuild のバンドルのみ。マスキング関数を FE / BE で共有するため） |
| バックエンド | enebular クラウド実行環境（ZIP / Node.js 22.x）+ Hono / TypeScript |
| データストア | enebular データストア（@uhuru/enebular-sdk） |
| LLM ゲートウェイ | OrcaRouter（OpenAI 互換） |
| CI / CD | GitHub Actions + @uhuru/enebular-cli（ZIP デプロイ自動化） |
| モノレポ | pnpm workspaces + Turborepo |
LLM へのアクセスはすべて OrcaRouter 経由に統一します。API キーはクラウド実行環境の 環境変数にのみ保持し、フロントエンドから LLM を直接叩くことはありません。
| # | 工夫 | 効果 |
|---|---|---|
| 1 | 2 段階 LLM で答えを構造的に隠す | 1 段目（高品質）が原因を特定し、2 段目（安価）には着眼点だけを渡す。2 段目は答えを知らないまま問いを作るため、漏洩を確率ではなく設計で防げる |
| 2 | モデル出し分けがそのままコスト設計になる | 高品質モデルは 1 回、安価モデルは 10〜15 回。回数 × 単価で投資先が決まる。実測で 45% のコスト削減（設問数により 45〜68% に変動 / cost-model.md §5.2） |
| 3 | フロントを関数から同一オリジンで配信 | CORS・Cookie の SameSite 問題・デプロイ 2 系統・API ベース URL がまとめて消える |
| 4 | 診断を別リクエストに分離 | 実行環境はレスポンスをバッファするため SSE が使えない。重い診断を、利用者がヒントを読んでいる間に裏で走らせる |
| 5 | MOCK モード | LLM なしで全導線が動く。開発速度・テスト・デモの安定性・コストのすべてに効く |
| 6 | 答えは別テーブルに隔離 | KV ストアは getItem がアイテム全体を返すため、テーブル分離が唯一の隔離手段 |
詳細は architecture.md §2。
| 制約 | 設計への影響 |
|---|---|
| AWS Lambda ベースでレスポンスをバッファする | ストリーミングを廃止。内部診断を別リクエストに分離 |
| データストアはメインキー + サブキーの KV（JOIN・集計なし） | アクセスパターン起点のキー設計へ。集計は事前計算 |
ZIP はルート直下に CommonJS の index.js が必要 |
pnpm の symlink が載らないため esbuild で単一 CJS にバンドル |
| データストアのアクセス回数に月次上限 | 1 セッションを少数アイテムに集約 |
| 前提 | バージョン |
|---|---|
| Node.js | 22.x |
| pnpm | 11.x |
pnpm はリポジトリに同梱されないため、先にグローバルインストールが必要です。
npm install -g pnpm@11
pnpm --version # 11.x が表示されれば OKNode.js 同梱の Corepack を使う場合は
corepack enable pnpmでも構いません。package.jsonのpackageManager（pnpm@11.11.0）が読まれ、同じ版が自動で使われます。
git clone https://github.com/junichikatsu/SocraMetry.git
cd SocraMetry
pnpm install
cp .env.example .env # MOCK_MODE=true が既定
pnpm dev:web # フロントのバンドル（監視ビルド。別ターミナルで）
pnpm dev # http://localhost:8787これで画面と GET /v1/health は開きます。
pnpm dev:webを先に一度は流してください。apps/web/public/app.jsはapps/web/src/からの生成物で、git 管理していません （ADR-013）。 デプロイ用のbuild:zipは内部で自動的にビルドするため、この手順はローカル開発だけの話です。
MOCK_MODE=true が消すのは LLM の呼び出しだけです（ADR-014）。
データストアは enebular が実行環境に注入する接続情報を使うため、
ローカルで API を通しで叩くには enebular のデータストアに接続できる状態が必要です。
接続情報がない状態で API を叩くと 503 DATASTORE_UNAVAILABLE が返ります
（起動と /v1/health は落ちません）。
MOCK モードでの導線確認は自動テストで行います。
pnpm test # 326 件。LLM もデータストアも呼ばないため課金ゼロapps/function/src/api.test.ts が、データストアを同じインターフェースの代替に
差し替えたうえで、ログイン → 3 ゲート → スコアまでを通しで検証しています。
なぜ MOCK を既定にしているか: OrcaRouter の API キーは配布できないため、 実 LLM を前提にすると第三者は原理的に起動できません。 MOCK モードは固定の診断・ヒント・設問を返すので、 開発中の LLM 課金がゼロになり、自動テストも決定的になります （scope-v0.1.md §4.3）。
これは DoD #7 「README だけを読んで、API キーなしに
MOCK_MODE=trueでローカル起動できる」を 完全には満たしていません。 データストアにインメモリ実装を持たない判断をしたためです （ADR-014 の適用範囲を LLM に限定している）。やっていないことを「やった」と書かない方針に従い、 ここは正直に記載しています。
OrcaRouter の API キーと、enebular のデータストアが必要です。 環境変数の一覧は .env.example、設定手順は deployment.md §3.3 を参照してください。
1 セッションあたり 4.9〜6.8 円です（1 USD = 165 円）。 到達ゲートで変わり、Gate A で自力解決すると 4.9 円、Gate C まで到達すると 6.8 円です。 OrcaRouter の請求と突き合わせ済み（差 6%）。 （cost-model.md §5.4）。
実装対象は scope-v0.1.md が正です。 他は将来像を含みます。
| ドキュメント | 内容 |
|---|---|
| v0.1 スコープ | 直近で作るもの / 作らないもの・設計判断・完了の定義 |
| 要件定義書 | 課題・ペルソナ・機能要件・非機能要件・AI の必然性・ビジネス成立性 |
| アーキテクチャと技術選定 | 構成図・ADR 14 件・キャパシティ試算・フォルダ構成 |
| ソクラテス式エンジン仕様 | 3 ゲート・二層 LLM 構成・答え漏洩ガード |
| コストモデル | モデル出し分け・max_tokens・単価ログ・実測コスト表 |
| セキュリティ方針 | キー秘匿・入力バリデーション・マスキング・ログ方針 |
| 評価モデル | スコア算出・公平性の設計・組織ダッシュボード（v0.2） |
| データモデル | データストアのキー設計・冪等性 |
| API 仕様 | エンドポイント・エラー・冪等性 |
| デプロイ | ZIP の作り方・enebular セットアップ・GitHub Actions |
| ロードマップ | 日次計画・削る順序・中長期計画・リスク |
v0.1 は実装済みで、実際の LLM につないで動作を確認しています。
| 状況 | |
|---|---|
| バックエンド API | ✅ 3 ゲート・簡易ログイン・スコア・履歴・コストログ |
| フロントエンド | ✅ 正式画面（チャット形式の UI・マスキングのプレビュー表示 / #27） |
| デプロイ | ✅ enebular クラウド実行環境（手動実行のワークフロー） |
| 自動テスト | ✅ 326 件 |
| 実測コスト | ✅ 1 セッション 4.9〜6.8 円（cost-model.md §5.4） |
v0.2 の組織機能（演習モード・問題集・組織ダッシュボード・ロール管理）は 予定どおり未実装です。実装対象の判断は scope-v0.1.md が正です。
今後の計画は ロードマップ を参照してください。
MIT