Skip to content

roadmap.md

Latest commit

 

History

History
333 lines (248 loc) · 20.4 KB

roadmap.md

File metadata and controls

333 lines (248 loc) · 20.4 KB
Raw

ロードマップ

項目 内容
ドキュメント版数 v0.6
更新日 2026-08-15
主な変更 中長期の節に**対外向けの 4 段階ロードマップ（v0.1〜v0.4）**を追加し、実装単位（M4 / M5）との対応を明記。演習・問題集（知の循環）を組織ダッシュボード（実力の可視化）より先に置く順序と、その根拠（NFR-F2）を記載

全体像

 【v0.1】5 日間 ← 現在地
    Day 1  土台      デプロイ導線と外部依存の実測を先に潰す
    Day 2  コア      2 段階 LLM + MOCK モード + LeakGuard
    Day 3  完走      3 ゲート貫通・ログイン・履歴・スコア
    Day 4  品質      UI 仕上げ・異常系・コスト実測・テスト
    Day 5  仕上げ    リハーサル・動画・記事・README

 【v0.2 以降】
    M4 組織機能      演習・問題集・組織ダッシュボード・評価レポート
    M5 運用品質      テナント分離・監査・公平性の実地検証

対外向けには v0.1〜v0.4 の 4 段階で語る（→ 対外向けの 4 段階ロードマップ）。

v0.1 は個人体験、v0.2 で組織価値。 順序を逆にしない。 利用者が使い続けてくれなければ、管理者が欲しいデータは 1 行も溜まらないため。

v0.1 — 5 日間の計画

実装対象は scope-v0.1.md が正。

進め方の原則

# 原則 理由
1 Day 1 に「デプロイして動く」状態を作る 最後にまとめてデプロイすると、詰まったときに逃げ場がない
2 外部依存の不明点を最初に潰す enebular の event 形式・タイムアウト・OrcaRouter のモデル ID。ここで詰まると全部が止まる
3 MOCK モードを Day 2 に作る 以降 3 日間の開発速度とデモの安全性がここで決まる
4 毎日終わりに「通しで動く」状態を保つ 未完成の枝を持ち越さない。Day 5 に統合作業を残さない
5 1 日ごとに削る判断をする 遅れたら翌日に持ち越さず、その場でスコープを削る

いつ何が触れるようになるか

提出物・デモ構成を作る側が、リハーサルをいつ組めるかを判断するための表。

時点 触れる状態
Day 1 終わり デプロイ済み URL で HTML が表示される（中身はまだない）
Day 2 終わり MOCK モードで API が通る。 LLM なしで問答の流れを確認できる
Day 3 終わり 実 LLM で 1 周通る。 ログイン → 投稿 → Gate A/B/C → スコア
Day 4 終わり 異常系・コスト表示まで含めて完成。テザリングでの実測値が出ている
Day 5 午前 DoD 8 項目を確認済み。この時点の状態が本番

リハーサルを組めるのは Day 3 の終わり以降。 それ以前は MOCK での画面確認のみ。

F 番号 × Day の対応

scope-v0.1.md §2 の F 番号を、日付に落としたもの。

Day F 番号 内容
Day 1 — 土台（デプロイ導線・外部依存の実測）。F 番号に紐づく機能はまだ作らない
Day 2 F04（MOCK / max_tokens）
F03（モデル出し分け）
F05（マスキング・キー秘匿）
F01（2 段階 LLM）		 MOCK を最初に入れ、その上でコアを作る
Day 3 F15（簡易ログイン）
F02（1 画面 UI）
F14（履歴保存 / 永続化）
F01 続き		 ここで通しが成立する
Day 4 F12（異常系の表示）
F11（コストログ・実測）
F13（テスト）
F05 続き（バリデーション・レート制限）		 止まらない・測れる状態にする
Day 5 F06（README）
F07（動画）
F08（記事）		 実装はしない。伝える成果物のみ
完了済み F09（要件定義）/ F10（アーキテクチャ設計） —

F14 / F15 は Day 3 に置いているが、内訳で扱いが違う。

項目 扱い
セッションの永続化（F14 の一部） 必須。 これがないと Gate B の複数ターンが成立しない
履歴一覧・5 軸推移グラフ（FR-24） Day 4 の余力次第。 削る順序 #1
簡易ログイン（F15） 必須。 理由は学習効果ではなくコスト保護（公開 URL に無認証で LLM を置かない）

Day 1 — 土台（外部依存の不確実性を消す）

この日のゴール: デプロイした URL で Hello が表示され、データストアに 1 件書ける。

午前 — 外部依存の実測（最優先）

  • OrcaRouter 疎通。GET /v1/models でカタログ取得し、高品質 / 安価のモデル ID を確定（→ Q-1）
  • エコー関数を ZIP デプロイし、HTTP トリガーが渡す event の形式を確認（→ Q-6）
  • タイムアウトの上限値を確認し、20 秒級の処理が通るか確かめる（→ Q-5）
  • envVars で環境変数が読めるか（→ Q-8）
  • connectDataStore + @uhuru/enebular-sdk で put / get / query が動くか

午前でここが崩れたら、その場で設計を変える。 event が非標準なら正規化アダプタを書く。タイムアウトが短ければ処理を分割する。 Day 4 に発覚すると手遅れになる項目を、初日の午前に置いている。

午後 — 骨組み

  • モノレポ初期化（pnpm workspaces + Turborepo）
  • apps/function: Hono + hono/aws-lambda、GET /v1/health
  • 静的ファイル配信（ADR-012）。index.html が表示される
  • build.mjs: esbuild バンドル → ZIP（ADR-008）
  • GitHub Actions からのデプロイを 1 回通す
  • packages/datastore: クライアントとテーブル解決

Day 1 完了条件: デプロイ済み URL を開くと HTML が表示され、/v1/health が 200 を返す。

Day 2 — コア（2 段階 LLM が動く）

この日のゴール: エラーを投げるとヒントが返り、設問が出る（API レベル）。

  • MOCK_MODE を最初に実装（ADR-014）。以降すべてこの上で開発する
  • packages/llm: OrcaRouter クライアント + 用途別モデル設定（F03）
  • packages/core: マスキング（F05）と LeakGuard、単体テスト付き
  • Diagnoser（高品質モデル）: 構造化 JSON で rootCause / focusHints を得る
  • Hinter（安価モデル）: focusHints だけから Gate A のヒントを作る
  • Questioner（安価モデル）: focusHints だけから選択式の設問を作る
  • POST /v1/sessions（Gate A のヒントを返す）
  • POST /v1/sessions/:id/diagnose（先行診断 / ADR-006）
  • max_tokens の設定（F04）

Day 2 完了条件: 実際のエラー 3 件で、Gate A のヒントと Gate B の設問に答えが漏れていない。

漏洩が止まらない場合はここで設計を変える。 Questioner に渡す情報をさらに削るか、 選択肢をテンプレート化する。この判断を Day 3 以降に持ち越さない。

Day 3 — 完走（3 ゲートが通る）

この日のゴール: ログインしてエラーを投げ、Gate C まで到達してスコアが出る。

バックエンド

  • 簡易ログイン: サインアップ / ログイン / JWT Cookie（F15）
  • POST /hints（Gate A）、POST /advance（A → B）
  • POST /answers（Gate B）、POST /conclusion（到達判定）
  • POST /reveal + POST /retrospect（Gate C）
  • packages/core: ゲート遷移・段階遷移・スコアリング（純関数）
  • GET /report（レポート生成 + 保存）
  • 履歴保存と GET /me/sessions（F14）
  • 冪等性の実装（F04 / 連打防止のサーバ側）

フロントエンド

  • 1 画面の状態遷移（ログイン → 投稿 → A → B → C → 結果）
  • Gate A のヒントパネル / Gate B の設問カード / Gate C の解説パネル
  • 5 軸スコアの表示（SVG を手書き。ライブラリを入れない）
  • 先行診断のキックと 202 の再試行

Day 3 完了条件: 通しで 1 周できる。 ここが遅れたら Day 4 の項目を削って必ず達成する。

Day 4 — 品質（止まらない・測れる）

この日のゴール: 何をしても画面が止まらず、コストが数字で出る。

  • 異常系の表示（F12）: LLM 障害 / タイムアウト / 不正入力 / トークン超過 → すべて画面に原因が出て、次の操作ができる
  • 「先輩が考えている」演出（ADR-007）とローディング状態
  • コストログの実装（F11）: 1 リクエストごとに model / tokens / 推定単価
  • 実測コストの計測とコスト表への反映（cost-model.md §5.4）
  • 入力バリデーション（F05）とレート制限（F04）
  • テスト（F13）: マスキング / LeakGuard / スコアリングの単体 + 主要導線
  • UI の仕上げ（PC 前提。レスポンシブはやらない）
  • 実際のエラー 10 件で通し確認。うち最低 3 件はテザリング回線で実施
  • NFR-P1〜P3 をテザリング回線で計測し、数値を記録する

テザリングで測る理由: レスポンスがバッファされて全文が一度に返るため （E1）、回線が細いと体感が一段悪化する。 当日は会場 Wi-Fi ではなくテザリングで動かす前提なので、 会場 Wi-Fi で測った数字は当日の保証にならない。

Day 4 完了条件: 意図的に壊しても（キーを無効化する等）画面が止まらない。 かつ、テザリング回線で NFR-P1〜P3 を満たしている。

Day 5 — 仕上げ（伝わる状態にする）

この日のゴール: 他人が見て理解でき、他人が動かせる状態。

午前 — 完了の定義を潰す

  • DoD 8 項目を 1 つずつ確認する（scope-v0.1.md §7） → リハーサルと同じ枠でやると流れるため、独立した項目として先に潰す

午後 — 伝わる状態にする

  • デモのリハーサル 3 回以上（scope-v0.1.md §6） → うち最低 1 回はテザリング回線で実施する
  • プロダクト紹介動画の収録（F07）
  • 技術解説記事の執筆（F08）— 設計判断・モデル出し分け・実測コスト
  • README の仕上げ（F06）— 構成図・セットアップ手順・工夫点
  • ドキュメントの最終整合（実装と設計書のずれを直す）
  • 予備時間

Day 5 に実装を残さない。 機能追加の誘惑が最も強い日だが、 ここで触ると壊れたまま終わる。Day 4 で機能を凍結する。

遅れたときに削る順序

上から順に削る。下 3 つは削らない。

順 削る対象 影響
1 履歴一覧の画面（API だけ残す） 1 セッションのデモには影響しない
2 5 軸スコアのレーダー表示 → 数値のリスト表示 見栄えは落ちるが情報は伝わる
3 Gate A のヒント Lv2 / Lv3 → Lv1 のみ ゲート構造自体は残る
4 Gate B の段階を Lv1〜5 → Lv1〜3 5 軸スコアが 3 軸になる
5 簡易ログイン → 固定ユーザー F15 Must だが、コアが動かないよりまし
— 3 ゲートの貫通 ❌ 削らない。これが製品そのもの
— LeakGuard とマスキング ❌ 削らない。壊れると製品価値と安全性が消える
— MOCK モード ❌ 削らない。デモの保険

v0.2 以降（中長期）

v0.1（上記の 5 日間）で扱わなかった要素を、ここから積む。 各項目の詳細な背景は requirements.md と evaluation-model.md を参照。

対外向けの 4 段階ロードマップ

製品ストーリーとしては次の 4 段階で語る（資料・ブース・審査での説明はこの粒度）。 実装単位（M4 / M5）との対応を併記する。

段階 語り 実装との対応
v0.1 個人の「自走力」の確立 3 ゲート方式の AI メンターで「答えを教えず問いで導く」体験を実装し、デバッグ脳を鍛えます 実装済み（上記 5 日間）
v0.2 組織の「知」の循環 実務の問答から溜まったナレッジを匿名化して社内問題集へ。現場で実際に起きたエラーが、新人の演習教材として還流します M4 のうち「演習と問題集」（FR-34〜37）
v0.3 組織の「実力」の可視化 管理者ダッシュボードで 5 軸スコアの計測・評価を実現。演習モードの同一条件の実績だから、公平な横比較が成立します。見えた弱点には問題集からトレーニングを割り当てられます M4 のうち「組織」（ダッシュボード・評価レポート）
v0.4 開発の「日常」への融合 IDE 拡張や GitHub 連携でエンジニアの日常にシームレスにつながり、実務のあらゆる瞬間を「最高の教材」へ変えます v2 以降（IDE 拡張 / CLI ほか）

演習・問題集（v0.2）をダッシュボード（v0.3）より先に置くのは、 横比較できるスコアが同一問題・同一条件の演習実績の上にしか成立しないため（NFR-F2）。 弱点に合わせたトレーニング割り当ては、v0.2 の問題集 × v0.3 の可視化が揃って初めて回る。 M5（運用品質）は特定の段階に紐づかず、外部提供の前提として横断的に積む。

M4: 組織機能（BtoB 製品として成立させる）

目的: 管理者が「導入する理由」を得る。ここで初めて BtoB 製品になる。

演習と問題集

  • question_bank: 問題の登録・編集・タグ付け（FR-34）
  • 演習モードのセッション（question_bank の診断を使い Diagnoser を呼ばない）
  • assignments: 割り当てと進捗管理（FR-36 / FR-37）
  • 実務セッション → 問題集の変換と匿名化（FR-35 / → Q-13）
  • 難易度の設定（v1 は手動 / → Q-10）

組織

  • ロール管理（member / lead / admin）と閲覧範囲制御（NFR-S6）
  • メンバー招待・チーム設定
  • 組織ダッシュボード（member_stats を 1 クエリで集計）
  • 組織の弱点サマリを初期表示にする（evaluation-model.md §5.2）
  • 組織設定（ランキング可否・保持期間）
  • ランキング（既定 無効 / → Q-11）
  • 評価レポート出力（FR-27 / → Q-12）

受け入れ条件:

  • 管理者が組織ダッシュボードを開き、組織の弱い軸を 3 秒以内に把握できる（NFR-P4）
  • 10 名に演習を割り当て、同一問題での比較ができる
  • 評価レポートが成長率を先頭に、5 軸内訳と算出根拠つきで出力される
  • 総合点だけのレポートが出力できないことを確認する（NFR-F5）

M5: 運用品質（外部に提供できる状態にする）

  • production プロジェクトの構築とタグデプロイ
  • テナント分離の検証: 他組織のデータが取得できないことをテストで保証（NFR-S5）
  • 監査ログ（NFR-S9）と、403 試行の記録
  • レート制限（NFR-O3）とトークン予算（NFR-C1）
  • LeakGuard 回帰テスト 50 ケース（NFR-Q1）
  • モデルフォールバック（NFR-O1）と診断失敗時の汎用モード（NFR-O4）
  • データ削除（セッション / 退職者 / 組織解約）（NFR-S7）
  • データ保持ポリシーの実施
  • 公平性の実地検証: 導入企業でスコア分布を確認し、経験年数との相関を見る

受け入れ条件: 導入企業に本番提供でき、評価制度に載せられる状態。

v2 以降

優先 項目 内容
1 監査ログの UI 管理者が「誰が誰の評価を見たか」を画面で追える
2 難易度の自動算出 実績の正答率から difficulty を更新（Q-10）
3 スクリーンショット入力 Vision モデルで画面からエラーを読み取る
4 評価レポートの PDF 出力 人事の運用に合わせた体裁
5 IDE 拡張 / CLI エディタから直接セッションを開始
6 人事システム連携 API 各社の制度設計に合わせた連携（現在は Non-Goal）
7 英語 UI
8 デバッグ以外の領域 3 ゲート方式を設計 / レビュー / テスト設計に展開

リスクと対策

プロダクトのリスク

リスク 影響 対策
LLM が答えを漏らす 製品価値が消滅 Day 2 完了条件で最優先検証。役割分離 + LeakGuard + フォールバックテンプレートの三重防御
Gate A で誰も解けない 3 段階に分ける意味がなくなる Day 4 の実エラー 10 件の通し確認に含める。ヒントの強度を調整
利用者が使わなくなる 評価データが溜まらず、BtoB 価値が消える 業務支援を最優先（P2）。開示を罰しない。v0.1 は個人価値に集中する
「監視ツール」と受け取られる 現場の反発で導入が頓挫 自分のデータは常に自分が見られる。監査ログ。導入時に運用方針を合意（evaluation-model.md §8）
評価に使った途端に指標が歪む 学習効果も評価妥当性も壊れる 難易度正規化・成長率主義・実務モードは非比較・開示の減点を小さく（evaluation-model.md §4）
診断が外れる 見当違いの問いで学習にならない confidence が低い場合は情報を補う質問に切り替える。レポートで正直に出す

技術のリスク

リスク 影響 対策
enebular の event 形式が非標準で Hono が使えない 実装量が増える Day 1 午前に実測（Q-6）。ダメなら正規化アダプタを自作（ADR-009 に記載済み）
タイムアウトが LLM 呼び出しに対して短すぎる 診断・レポート生成が完走しない Day 1 午前に実測（Q-5）。短い場合は分割か高速モデルへ
member_stats の二重加算で評価データが壊れる 評価の信頼性が失われる GET /report を冪等に（api-spec.md §4）。reports から再構築可能にしておく
テナント間のデータ漏洩 事業が終わる キー設計 + ブランド型で構造的に防ぐ（ADR-010）。M5（v0.2 以降）でテストによる保証
データストアのアクセス枠 大規模導入で頭打ち エンタープライズで約 51,000 セッション / 月。1,000 名超で要監視。削減策は Q-7
待ち時間が長い 離脱 診断を別リクエストに分離（ADR-006）。「先輩が考えている」演出（ADR-007）。Day 4 / Day 5 にテザリング回線で実測（NFR-P1〜P3 の計測条件）
エラーに認証情報が混入 情報漏洩 保存前・送信前のマスキング（FR-11）を Day 2 の必須項目とする
顧客名など固有名詞の混入 顧客情報が外部 LLM へ 正規表現では検出できない。 除外語リスト + 送信前プレビューで利用者が伏せる。UI に「自動では消えない」と明記（security.md §3）
問題集への匿名化漏れ 顧客情報が社内に拡散 登録は draft から。人の目視確認を必須（Q-13）