| name | quarto-survey-setup |
| description | Quarto アンケート分析プロジェクトの環境構築。uv + Quarto + Typst PDF パイプラインをゼロからセットアップする。「アンケート分析プロジェクトを作成」「survey project setup」などのリクエストで使用する。 |
| disable-model-invocation | true |
| argument-hint | [project-name] |
Quarto アンケート分析プロジェクト環境構築
CSV アンケートデータを分析するための Quarto + Python プロジェクトをゼロから構築する。
目次
- 前提チェック
- ディレクトリ構成作成
- pyproject.toml 生成
- _quarto.yml 生成
- WSL検出・.mise.toml 生成
- .gitignore/.python-version 生成
- uv sync
- CLAUDE.md 生成
進捗チェックリスト
- [ ] Step 1: 前提チェック（uv, quarto）
- [ ] Step 2: ディレクトリ構成作成
- [ ] Step 3: pyproject.toml + run_commands.py 生成
- [ ] Step 4: _quarto.yml 生成
- [ ] Step 5: WSL検出・.mise.toml 生成（該当時）
- [ ] Step 6: .gitignore, .python-version 生成
- [ ] Step 7: uv sync 実行
- [ ] Step 8: CLAUDE.md 生成
ステップ1: 前提チェック
uv と quarto の存在を確認する。いずれかが存在しない場合、インストール手順を案内して中断する。
uv --version
quarto --version
ステップ2: ディレクトリ構成作成
引数 [project-name] をディレクトリ名として使用する。既にプロジェクトディレクトリにいる場合はカレントディレクトリを使う。
mkdir -p data output/figures output/tables
ステップ3: pyproject.toml 生成
{project-name} を実際のプロジェクト名に置換して作成する:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["."]
[project]
name = "{project-name}"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"pandas>=2.2",
"matplotlib>=3.9",
"matplotlib-fontja>=1.1",
"jupyter>=1.0",
"ipykernel>=6.29",
"nbformat>=5.10",
"nbclient>=0.10",
"python-pptx>=1.0",
]
[project.scripts]
render = "run_commands:render"
preview = "run_commands:preview"
同時に run_commands.py をプロジェクトルートにコピーする:
cp "$SKILL_ROOT/scripts/run_commands.py" .
ステップ4: _quarto.yml 生成
日本語 Typst PDF 出力用の Quarto 設定を作成する:
project:
title: "{project-name}"
type: default
output-dir: output
preview:
port: 4200
format:
typst:
toc: true
toc-depth: 3
number-sections: true
mainfont: "Yu Gothic"
fontsize: 10pt
papersize: a4
margin:
x: 2cm
y: 2cm
lang: ja
columns: 1
execute:
echo: false
warning: false
ステップ5: WSL 検出と .mise.toml 生成
WSL 環境（パスが /mnt/ で始まる）では、venv をユーザーディレクトリに配置する。Windows ファイルシステム上の venv はパフォーマンスが著しく低下するため。
pwd | grep -q "^/mnt/" && echo "WSL" || echo "native"
WSL の場合、.mise.toml を作成する:
[env]
_.python.venv = "{{env.HOME}}/.venvs/{project-name}"
UV_PROJECT_ENVIRONMENT = "{{env.HOME}}/.venvs/{project-name}"
ネイティブ Linux / macOS の場合、.mise.toml は不要（デフォルトの .venv/ を使用）。
ステップ6: .gitignore と .python-version 生成
.gitignore:
# Output
output/
# Python
__pycache__/
*.pyc
.venv/
# Quarto
.quarto/
/.quarto/
# Jupyter
.ipynb_checkpoints/
.python-version:
3.13
ステップ7: uv sync 実行
uv sync
mise を使用している場合は先に mise trust を実行:
mise trust && uv sync
ステップ8: CLAUDE.md 生成
$SKILL_ROOT/templates/CLAUDE.md を参考に、プロジェクト固有の CLAUDE.md を作成する。テンプレート内の汎用記述をプロジェクトの実情に合わせて調整する。
cat "$SKILL_ROOT/templates/CLAUDE.md"
完了確認
以下をユーザーに報告する:
- 作成されたファイル一覧
uv sync の成否- 次のステップ:
data/ に CSV を配置し、/survey-report-builder でレポート構築
注意事項
- Jupyter カーネルはカスタム名を使わず
python3 に自動解決させる（ポータブル性のため）
- WSL 環境では必ず venv をユーザーディレクトリに逃がす
uv run render / uv run preview がすぐ使えることを確認するoutput/ ディレクトリは .gitignore に含める
