data-analysis

データ分析ワークフロー

R でエンドツーエンドのデータ分析を実行します。データの読み込み、探索、分析を行い、出版可能な品質の出力を作成します。

入力： $ARGUMENTS — データセットのパス（例：data/county_panel.csv）、または分析目標の説明（例：「CPS データを使用して、州固定効果を含め、賃金を教育年数に回帰する」）。

---

制約

• .claude/rules/r-code-conventions.md の R コード規約に従ってください
• すべてのスクリプトを、わかりやすい名前を付けて scripts/R/ に保存してください
• すべての出力（図、表、RDS）を output/ に保存してください
• 計算したオブジェクトはすべて saveRDS() を使用して保存してください — Quarto のスライドで必要になる場合があります
• すべての図に プロジェクトのテーマを使用してください（.claude/rules/ にカスタムテーマがあるか確認してください）
• 結果を提示する前に、生成したスクリプトに対して r-reviewer を実行してください

---

ワークフローのフェーズ

フェーズ 0：事前確認レポート

分析コードを書く前に、入力を確認したことを示す事前確認レポートを作成してください。 これにより、エージェントが変数名を捏造したり、プロジェクトの規約を無視したりするよくある失敗を防げます。

出力ブロック（フェーズ 1 の前に、ユーザーへの回答内に記載）：

## Pre-Flight Report

**Dataset:** [path]
- Variables found: [list from head()/names()]
- Rows: [count]
- Key types: [e.g., "outcome=numeric, treatment=binary, state=factor"]
- Missing-data summary: [% missing per key var]

**Project conventions read:**
- `.claude/rules/r-code-conventions.md` — [one-line summary of most relevant rule]
- `.claude/rules/content-invariants.md` — [INV-9, INV-10, INV-11, INV-12 applicable]

**Task interpretation:** [one sentence restating what the user asked for]

**Plan:** [3-5 bullet outline of the R script structure]

入力を読み込めない場合（ファイルが見つからない、形式を読み取れないなど）は、作業を中止し、先にユーザーに確認してください。

フェーズ 1：セットアップとデータの読み込み

1. 適切なヘッダー（タイトル、作成者、目的、入力、出力）を含む R スクリプトを作成します
2. 必要なパッケージを先頭で読み込みます（library() を使用し、require() は使用しないでください）
3. r-code-conventions.md に従い、YYYYMMDD 形式でシードを先頭に一度だけ設定します。例：set.seed(20260415)（INV-9）
4. データセットを読み込み、内容を確認します

フェーズ 2：探索的データ分析

診断用の出力を作成します：

• 要約統計量： summary()、欠損率、変数の型
• 分布： 主要な連続変数のヒストグラム
• 関係性： 散布図、相関行列
• 時系列パターン： パネルデータの場合は、時間の経過に伴う傾向をプロットします
• グループ比較： 処置群と対照群がある場合は、処置前の平均値を比較します

すべての診断用図を output/diagnostics/ に保存してください。

フェーズ 3：主分析

研究上の問いに応じて、以下を実施します：

• 回帰分析： パネルデータには fixest、クロスセクションデータには lm／glm を使用します
• 標準誤差： 適切なレベルでクラスタリングし、その理由を記録します
• 複数の仕様： シンプルなモデルから始め、統制変数を段階的に追加します
• 効果量： 生の係数と併せて標準化効果も報告します

仕様台帳 — 採用・不採用を問わず、すべての実行を記録

このフェーズで推定したすべての仕様について、採用しなかったものや失敗したものも含め、実行時に quality_reports/spec-ledger.md に行を追加します。これは、査読者の「ほかに何を試したのか」という問いに応える記録です。探索を禁止するのではなく、その過程を可視化し、どの仕様を実行するかについて助言せずに仕様を記録します。

• 追記のみ。 行を編集または削除してはいけません。修正は新しい行として追加します。コミット済みの行を変更するコミットは、リポジトリ衛生チェックに失敗します。
• Status には kept、dropped、または failed を指定します。採用しなかった場合は、Why に理由を記載します。
• Estimate は任意です。利用制限のあるデータでは、数値が開示審査（confidential-data.md）を通過するまで空欄にします。
• 数式内の | は \| にエスケープしてください。エスケープしないとテーブルが崩れます。バッククォートを含む仕様（`x' のような Stata のローカルマクロなど）は、ダブルバッククォートで囲みます：`` reg y `controls' ``。

LEDGER=quality_reports/spec-ledger.md
[ -f "$LEDGER" ] || printf '%s\n' "# Specification ledger" "" \
  "Every specification estimated, kept or not, one row each, appended as it is run. Never edit a past row; a correction is a new row." "" \
  "| Date | Commit | Script:line | Outcome | Specification | Sample | Status | Why | Estimate |" \
  "|---|---|---|---|---|---|---|---|---|" > "$LEDGER"
if REV=$(git rev-parse --short HEAD 2>/dev/null); then       # -dirty = anything uncommitted outside quality_reports/, untracked files included
  [ -n "$(git status --porcelain -- . ':(exclude)quality_reports' 2>/dev/null)" ] && REV="$REV-dirty"
else
  REV="no-commit"
fi
printf '| %s | %s ' "$(date +%F)" "$REV" >> "$LEDGER"          # one printf + one heredoc per specification
cat >> "$LEDGER" <<'EOF'
| scripts/R/03_analyze.R:42 | log_wage | `feols(log_wage ~ treat + age \| id + year, cluster = ~id)` | panel 2010-2019 | kept | main specification | 0.082 (0.021) |
EOF

フェーズ 4：出版可能な品質の出力

表：

• 回帰表には modelsummary（推奨）または stargazer を使用します
• 係数、SE、有意性を示すアスタリスク、N、R 二乗など、標準的な要素をすべて含めます
• LaTeX への組み込み用に .tex、すばやく確認できるように .html としてエクスポートします

図：

• プロジェクトのテーマを適用した ggplot2 を使用します
• Beamer との互換性のため、bg = "transparent" を設定します
• 適切な軸ラベル（文頭のみ大文字、単位を含む）を付けます
• 寸法を明示してエクスポートします：ggsave(width = X, height = Y)
• .pdf と .png の両方で保存します

フェーズ 5：保存とレビュー

1. すべての主要なオブジェクト（回帰結果、要約テーブル、処理済みデータ）に対して saveRDS() を使用します
2. 必要に応じて dir.create(..., recursive = TRUE) で output/ のサブディレクトリを作成します
3. 生成したスクリプトに対して r-reviewer エージェントを実行します：

Delegate to the r-reviewer agent:
"Review the script at scripts/R/[script_name].R"

4. レビューで指摘された Critical または High の問題に対処します。

---

スクリプトの構成

次のテンプレートに従ってください：

# ============================================================
# [Descriptive Title]
# Author: [from project context]
# Purpose: [What this script does]
# Inputs: [Data files]
# Outputs: [Figures, tables, RDS files]
# ============================================================

# 0. Setup ----
library(tidyverse)
library(fixest)
library(modelsummary)

set.seed(20260415)  # YYYYMMDD per r-code-conventions.md (INV-9)

dir.create("output/analysis", recursive = TRUE, showWarnings = FALSE)

# 1. Data Loading ----
# [Load and clean data]

# 2. Exploratory Analysis ----
# [Summary stats, diagnostic plots]

# 3. Main Analysis ----
# [Regressions, estimation]

# 4. Tables and Figures ----
# [Publication-ready output]

# 5. Export ----
# [saveRDS for all objects, ggsave for all figures]

---

重要

• 推測せず、指定どおりに再現してください。 ユーザーが回帰分析を指定した場合は、そのとおりに実行します。
• 作業内容を示してください。 回帰分析に進む前に要約統計量を出力します。
• 問題がないか確認してください。 多重共線性、外れ値、完全予測を確認します。
• 相対パスを使用してください。 すべてのパスをリポジトリのルートからの相対パスにします。
• 値をハードコードしないでください。 サンプルの制限や日付範囲などには変数を使用します。

実行時間の長いフィット：Monitor ツールを使用（2026 年 4 月）

数分以上かかる回帰分析、シミュレーション、ブートストラップループは、Bash で run_in_background: true を指定して起動し、Anthropic の Monitor ツールを使用して R の標準出力をリアルタイムで会話にストリーミングします。手順：

1. Bash で run_in_background: true を指定してバックグラウンドで起動し、すべての出力をログに送ります：mkdir -p output && Rscript scripts/R/03_analyze.R > output/03_analyze.log 2>&1。プロセスが終了すると、バックグラウンドジョブが自動的に通知します。
2. マイルストーンと失敗を抽出するコマンドで Monitor を開始し、ログを追跡します。例：tail -f output/03_analyze.log | grep --line-buffered -E "Coefficients table written|Error|Execution halted"。Monitor には job-id パラメーターがありません。独自の command の標準出力がイベントストリームになります。tail -f は終了しないため、予想実行時間より長い timeout_ms を設定するか、persistent: true を指定し、ジョブ完了後に TaskStop で Monitor を停止します。
3. ストリームから得られた内容に基づいて、続行するか方針を修正します。

これにより、ポーリングループのアンチパターン（sleep 30; check; sleep 30; check）を避け、アイドル状態で待機中にキャッシュを無駄に消費することもありません。ガイドのコストを意識した並列処理のセクションと組み合わせると、特に有用です。