Initialize project structure, workflow rules, and research plan

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-30 14:34:40 +08:00
commit fa530b0df1
9 changed files with 1564 additions and 0 deletions
@@ -0,0 +1,29 @@
+# 決策日誌
+
+每筆記錄：日期、決策、理由。定義檔（`prompts/`）、codebook、
+研究計畫的任何修訂都必須在此留下記錄。
+
+## 2026-07-30
+
+- **語料擴大為 2016–2025 十年**（先導研究為 2018–2025）。
+  理由：框架完整、可看年度趨勢。
+- **全文不與先導研究比較**：論文僅呈現正式研究結果，數字
+  一律以正式研究為準；先導研究只作為 codebook v0 與假說的
+  內部來源，記於本日誌，不進入論文敘事。
+- **分析管線採 API script，不用 Claude Code subagent**。理由：
+  實測證實 subagent 會繼承 CLAUDE.md 與環境資訊，context 無法
+  僅憑定義檔重現；API 呼叫的輸入完全受控且可稽核。
+- **模型釘定 `claude-sonnet-4-6`、temperature=0、thinking 關閉**。
+  理由：該組合非決定性最低；條件 A/B 盲點實驗以模型為研究
+  對象，須與 pilot 的 Sonnet 家族銜接。Fable 5 不採用（成本、
+  thinking 不可關閉且不可稽核、無 temperature、混淆核心主張）。
+- **工具性環節的模型於階段 3 以校準樣本實測後決定**：同批
+  校準樣本以 Sonnet 4.6 與 Opus 5 各跑一次，對照人工黃金標準
+  比較一致率，據以決定是否於特定環節升級。
+- **codebook 採 directed content analysis**：理論骨架
+  （top-down）＋開放碼歸納通道（bottom-up），並加做 LLM 純歸納
+  輪與黃金標準的映射分析。映射分析方法須在看到結果前寫入
+  `methodology.md`。
+- **完整歌詞不進 git**（版權）；API 金鑰走 `.env`。
+- **專案目錄維持原名 `pop-fem-audit`**：API 管線下目錄名不會
+  進入模型輸入，無污染疑慮。
@@ -0,0 +1,56 @@
+# 專案目錄結構
+
+（2026-07-30 討論定案版；分析管線已改為 API script 路線，
+定義檔不再放 `.claude/agents/`）
+
+```
+pop-fem-audit/
+├── README.md                  # 專案說明、重現步驟
+├── CLAUDE.md                  # 極簡工作規範（subagent 會讀到，
+│                              #   絕不放理論、codebook、預期結果）
+├── .gitignore                 # data/lyrics/、.env、scratch
+├── conference_abstract.md     # pilot 摘要（投稿版）
+├── data/
+│   ├── yearend_hot100_2016_2025.csv   # 原始榜單（唯一手放原始檔）
+│   ├── songs_unique.csv               # 衍生：去重歌曲表（song id）
+│   ├── artists_gender.csv             # 衍生：演唱者性別後設資料
+│   └── lyrics/                        # 歌詞快取（gitignored，版權）
+├── prompts/                   # LLM 定義檔（逐字作為 system prompt）
+│   └── <task>_v<N>.md         #   版本化：screen_v1.md、judge_v2.md…
+├── scripts/                   # deterministic Python scripts
+│   │                          #   （runner、抓歌詞、統計、圖表）
+│   └── run_llm.py             # API runner：2+1 協定、Batch API、
+│                              #   自動寫入 runs/
+├── runs/                      # 每次執行的完整稽核紀錄（進 git）
+│   └── <階段>/<日期>-<定義檔版本>/
+│       ├── prompt.md          # 當次定義檔快照（自我完備）
+│       ├── run1.jsonl         # 第一次執行原始輸出
+│       ├── run2.jsonl         # 第二次執行原始輸出
+│       ├── arbitration.jsonl  # 仲裁輸出
+│       └── meta.json          # model ID、temperature、時間戳、
+│                              #   batch ID、一致率
+├── results/                   # 仲裁後最終衍生表（論文引用來源）
+├── docs/
+│   ├── research_plan.md       # 研究步驟規劃（本檔之姊妹篇）
+│   ├── project_structure.md   # 本檔
+│   ├── codebook.md            # 人工編碼手冊（版本由 git 管理）
+│   ├── decision_log.md        # 決策日誌：每次改定義檔的原因
+│   └── methodology.md         # 方法細節（全文方法節底稿；
+│                              #   映射分析方法須在看結果前寫定）
+└── paper/
+    └── full_paper.md          # 全文
+```
+
+## 設計理由
+
+- **`runs/` 自我完備**：每個執行目錄含定義檔快照 + 原始輸出 +
+  meta，讀者不需 git 考古即可稽核任一筆結果。
+- **`runs/`（原始稽核資料）與 `results/`（最終表）分離**：
+  論文只引 `results/`，其來源可回溯至 `runs/`。
+- **`prompts/` 用檔名版本化**（不只靠 git 歷史）：定義檔版本是
+  論文附錄的引用單位，須可直接指名（如 judge_v2.md）。
+- **API 金鑰**放 `.env`（gitignored），script 由環境變數讀取，
+  絕不寫入 repo。
+- **CLAUDE.md 極簡**：實測證實 Claude Code subagent 會繼承專案
+  CLAUDE.md 全文，故其中只放工作流程規則，領域知識一律放
+  `docs/`（subagent 不會自動讀到）。
@@ -0,0 +1,66 @@
+# 研究步驟規劃
+
+（2026-07-30 討論定案版；後續變更請記入 `decision_log.md`）
+
+## 總體框架
+
+- **研究敘事**：全文為獨立完整的正式研究（2016–2025 十年語料
+  共 1000 筆榜單紀錄，凍結程序後全量執行），**不與先導研究
+  （conference_abstract.md）做比較**；全文數字一律以正式研究
+  結果為準。先導研究僅作為 codebook v0 與假說的內部來源，
+  記於決策日誌，不進入論文敘事。
+- **執行原則**：主會話只做討論；所有分析由 deterministic script
+  執行。LLM 步驟以 Python script 呼叫 Anthropic Messages API
+  （個人 Console 帳號、Batch API 五折），定義檔逐字作為 system
+  prompt。每個 LLM 步驟「同一定義檔獨立執行兩次 + 一次仲裁」
+  （2+1），仲裁結果不符預期則修訂定義檔重跑整個循環。
+- **模型**：`claude-sonnet-4-6`、temperature=0、thinking 關閉
+  （此組合非決定性最低、成本合理）。條件 A/B 盲點實驗為
+  自足設計：同語料、同模型、僅提示不同，對照黃金標準。
+  其他工具性環節於階段 3 以校準樣本實測 Sonnet 4.6 vs Opus 5
+  的一致率後決定是否升級。
+- **信度與效度分工**：2+1 協定量測穩定性（intra-rater
+  reliability，報告一致率／kappa）；效度靠理論 codebook 與
+  人工黃金標準終審。可重現性定義為「程序透明＋可稽核」：
+  公開定義檔、記錄 model ID 與執行時間、保存全部原始輸出。
+
+## 階段與時程（全文截稿 2026-08-15）
+
+| 階段 | 內容 | 方式 | 時程 |
+|---|---|---|---|
+| 0 | 基礎建設：git init、目錄結構、.gitignore、決策日誌、runner script（含 Batch API）、codebook v0 骨架 | script + 討論 | 7/30–7/31 |
+| 1 | 資料準備：去重唯一歌曲表（song id）、抓歌詞（Lyrics.ovh / LRCLIB，缺漏留 log）、演唱者性別表（Wikidata + 人工核對） | scripts | 7/31–8/2 |
+| 2 | 候選篩選：全部唯一歌曲高召回 women-power 候選篩選（寧可多抓，人工剔除） | API 2+1 | 8/2–8/3 |
+| 3 | 黃金標準：依 codebook 人工逐首判定 genuine/peripheral/fake，附引用歌詞證據表（LLM 只做摘錄，不給判定建議）；先以 10–15 首校準樣本試編並修訂 codebook 後凍結；同批校準樣本實測 Sonnet 4.6 vs Opus 5 一致率 | 人工 + script 輔助 | 8/4–8/8 |
+| 4 | 受控比較（盲點實驗）：條件 A（詞彙層提示）vs 條件 B（框架感知提示），各 2+1，對照黃金標準計算假陽／假陰率 | API | 8/6–8/9 |
+| 4' | 由下而上歸納輪：LLM 對候選歌曲做無理論主題編碼（定義檔不含女性主義詞彙），與黃金標準做映射分析（交叉表；分析方法先寫入 methodology.md 再看結果） | API 2+1 + script | 與 4 並行 |
+| 5 | pussy 修辭分析：script 找含詞歌曲 → LLM 分類（METONYM/ANATOMICAL/COWARD/OTHER + 說話者/指涉對象）2+1 → 人工核定 | script + API | 8/8–8/10 |
+| 6 | 統計與圖表：一致率（kappa）、污染率、類型分布、年度趨勢、映射交叉表 | scripts | 8/10–8/11 |
+| 7 | 撰寫全文＋內部審稿（subagent 以審稿人視角挑毛病，特別是嘻哈女性主義／respectability politics 一題） | 討論 + subagent | 8/10–8/14 |
+
+關鍵路徑：階段 3 人工編碼（僅研究者本人可做），排週末與晚間分批。
+
+## Codebook 原則
+
+- Directed content analysis：理論骨架（top-down）＋紀律化歸納通道
+  （bottom-up：`other-fake` 開放碼 + memo + 決策日誌）。
+- 三層結構：理論構念層（Banet-Weiser、Gill、Goldman、McRobbie、
+  Fredrickson & Roberts、Connell、Mulvey）→ 操作判準層（權力來源
+  測試、frame vs vocabulary、決策樹）→ 類別定義層（A–E 納入／
+  排除判準、例句、near-miss 反例）。
+- 判準層須明文回應嘻哈女性主義（Joan Morgan、Gwendolyn Pough）
+  與性積極女性主義的 respectability politics 質疑：區分「性表達」
+  與「貶低其他女性／以男性指標定義權力」。
+- 流程：v0 → 校準樣本試編 → 修訂 → 凍結 v1 → 全量編碼；
+  中途修訂須記決策日誌並回檢已編歌曲。
+- Positionality statement 寫入論文（53 歲、長年婦運者、資深
+  工程師、離開學術圈多年、因整理榜單而起）。
+
+## 其他已定案事項
+
+- 歌詞受版權保護：完整歌詞不進 git（`data/lyrics/` gitignored），
+  論文與 repo 只留分類所引摘錄。
+- 工程支援（寫 script、style check、審稿）用公司訂閱的
+  Claude Code；進論文的分析 token 由個人 API 帳號支付。
+- Fable 5 不用於 pipeline：成本高、thinking 無法關閉且不可稽核、
+  無 temperature 控制，且會混淆「盲點是提示問題」的核心主張。