Quarto アンケート分析プロジェクト環境構築

CSV アンケートデータを分析するための Quarto + Python プロジェクトをゼロから構築する。

目次

1. [前提チェック](#ステップ1-前提チェック)
2. [ディレクトリ構成作成](#ステップ2-ディレクトリ構成作成)
3. [pyproject.toml 生成](#ステップ3-pyprojecttoml-生成)
4. [quarto.yml 生成](#ステップ4-quartoyml-生成)
5. [WSL検出・.mise.toml 生成](#ステップ5-wsl-検出と-misetoml-生成)
6. [.gitignore/.python-version 生成](#ステップ6-gitignore-と-python-version-生成)
7. [uv sync](#ステップ7-uv-sync-実行)
8. [CLAUDE.md 生成](#ステップ8-claudemd-生成)

進捗チェックリスト

- [ ] 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"

完了確認

以下をユーザーに報告する:

1. 作成されたファイル一覧
2. uv sync の成否
3. 次のステップ: data/ に CSV を配置し、/survey-report-builder でレポート構築

注意事項

• Jupyter カーネルはカスタム名を使わず python3 に自動解決させる（ポータブル性のため）
• WSL 環境では必ず venv をユーザーディレクトリに逃がす
• uv run render / uv run preview がすぐ使えることを確認する
• output/ ディレクトリは .gitignore に含める