アンケート設計・オンライン収集システム生成器
「アンケートの要件」を、すぐに使える3点セットに変換します。
- Wordアンケート（整った書式で印刷・配布可能）
- オンライン回答サイト（スマホでQRコードをスキャンして即回答、依存関係ゼロ、ダブルクリックで起動）
- 管理ダッシュボード（各質問の自動集計グラフ＋明細＋ワンクリックExcelエクスポート＋回答用QRコード）
全工程でサードパーティ製ライブラリへの依存はありません（Python標準ライブラリのみ）。生成物は任意のPCにコピーしてすぐに実行できます。
いつ使うか
- ユーザーが録音／口頭／テキストで要件を伝え、「アンケートを設計して」「録音からアンケートを作成して」と依頼してきた場合。
- ユーザーが既に質問項目を持っており、それをオンラインアンケート／QRコードで回答できるサイトにし、データを自動集計したい場合。
- ユーザーが「調査アンケート＋管理画面」の完全なソリューションを求めている場合。
実行手順（SOP）
第1ステップ 要件の取得と理解
- 録音：まず音声をテキストに変換します（
speech-to-textスキルやfetchによる音声ファイルの直接取得を使用）。 そこから抽出するもの：アンケートのテーマ、対象者、セクション（次元）数、各次元の具体的な質問、質問タイプの好み（単一選択／複数選択／リッカート尺度／自由記述）。 - テキスト：ユーザーから提供されたアウトラインをそのまま読み取ります。
- 不明な点（例：「基本情報」セクションを追加するか、どの組織を対象とするか）は、慣例に従って補完し、納品時にその旨を説明するか、ユーザーに確認します。
第2ステップ アンケート仕様書 questions.json の作成
references/spec-format.mdの形式に従い、アンケートをJSONで記述します。
- 最上位：
title（タイトル）、subtitle、intro（冒頭文）、footer、scale_options（リッカート尺度の5段階）、sections。 - 各セクションの下に
questions[]。各質問にはid、type、title、requiredを含め、選択式の質問にはoptionsを含めます。 - 質問タイプ：
single（単一選択）｜multi（複数選択）｜scale（リッカート尺度、選択肢はscale_optionsを参照）｜text（自由記述）。 allow_other: trueは自動的に「その他（具体的に）」オプションを追加します。exclusive: ["いずれも使用したことがない"]は、そのオプションが他のすべてのオプションと排他的であることを示します。- 推奨：正式なアンケートでは、まず簡潔な「基本情報」セクション（学年／教科／教職経験年数など）を追加し、その後のクロス分析に備えるとよいでしょう。
設計のポイント：質問文は平叙文で、誘導を避ける。選択肢は網羅的かつ排他的にする。リッカート尺度の段階は統一する。質問数は3〜5分で回答できる量に抑える。
第3ステップ 3点セットのワンクリック生成
python3 scripts/build_survey.py --spec questions.json --out <出力ディレクトリ>
# 最終的な回答URLが既にわかっている場合は、--url http://xxx/ を追加してQRコードを直接生成
生成物：
<出力ディレクトリ>/
├── <アンケートタイトル>.docx 書式設定済みのWordアンケート
└── オンラインアンケートシステム/
├── server.py 回答ページ＋管理画面＋API（依存関係ゼロ）
├── questions.json このアンケートの質問
├── 起動_Windows.bat / 起動_Mac_Linux.sh ワンクリック起動
├── make_qr.py QRコード個別生成
├── vendor/qrcode/ 内蔵QRコード生成
└── 使い方.md
第4ステップ 自己チェック（必須）
- 生成された
オンラインアンケートシステム/questions.jsonを開き、質問、選択肢、必須マークが正しいことを確認します。 - システムを起動し、スモークテストを実行します。
cd オンラインアンケートシステム && PORT=8123 python3 server.py & curl -s http://127.0.0.1:8123/ | head # 回答ページが開けること curl -s -X POST http://127.0.0.1:8123/submit --data-urlencode "q1=..." # 送信してデータ格納 curl -s http://127.0.0.1:8123/api/stats | head # 統計が正常であること - Word文書内で各質問の質問文と選択肢がページ分割されて表示されていないことを確認します（スクリプトで
keep-with-nextは設定済み）。
第5ステップ 納品とデプロイ手順の説明
ユーザーに以下の内容を説明します。
- 3点セットのそれぞれの使い方。QRコードは管理画面ページに自動表示されます（
http://PCのIPアドレス:8000/admin）。 - 先生方はどうやってアクセスするか：同じWi-Fiに接続してQRコードをスキャンすればすぐに回答できます（校内で最も一般的な使い方）。インターネット経由でアクセスさせるには、公開IPアドレスを持つサーバーに配置する必要があります。
- 詳細は
references/deploy-guide.mdを参照してください。また、この中の説明文はそのまま流用できます。 provide_fileを使用して、Wordアンケートと、パッケージ化した「オンラインアンケートシステム」の圧縮ファイルをユーザーにダウンロード提供できます。
第6ステップ（オプション） 保管庫へのアーカイブ
必要に応じて、upload-to-kbスキルを使用し、Wordアンケートとシステムの圧縮ファイルをユーザー指定の知識ベースに保存します。
重要なポイントと経験則
- 依存関係ゼロが最大の強み：Python標準ライブラリと内蔵の
vendor/qrcodeのみを使用するため、ユーザーはpipで何もインストールする必要はありません。 Word文書の生成にのみpython-docxが必要です（生成側の環境にあればよい）。 - 回答ページはプレーンなHTMLフォーム＋少しのJavaScript：送信は
POST /submitで行われ、サーバーサイドで必須項目をチェックします（未入力項目がある場合、既に入力した内容を保持したまま該当項目が赤く強調表示されます）。 - QRコードはサーバーサイドでSVGとしてリアルタイム生成（
/api/qr.svg?url=...）。管理画面ページは現在のアクセスURLから自動的にQRコードを生成するため、ネットワークが変わったりURLが変更になっても、再パッケージ化せずに新しいコードが生成されます。 - データは
data/responses.db（SQLite）に保存されます。バックアップはこのファイルのコピー、リセットはこのファイルの削除で行います。 - ローカルネットワークでアクセスできない場合、90%はPCのファイアウォールがPythonをブロックしていることが原因です。ユーザーに許可するよう促してください。
- ポートが既に使用されている場合は、
PORT=8080 python3 server.pyのようにしてポートを変更できます。
ディレクトリ構成
survey-design-collector/
├── SKILL.md
├── scripts/
│ ├── build_survey.py ワンクリック生成（仕様書→Word＋Webサイト＋QRコード）
│ ├── spec_to_word.py questions.jsonからWordアンケートを生成
│ └── make_qr.py URLからQRコードPNGを生成
├── assets/app/ オンラインアンケートシステムのテンプレート（server.py / 起動スクリプト / vendor/qrcode）
└── references/
├── spec-format.md questions.jsonの仕様説明＋録音からアンケートへの変換方法
└── deploy-guide.md デプロイと対外説明用テンプレート