Files

T

imacatandClaude Opus 5 85d776da8b Renumber the pipeline substeps to match the paper (5-1 becomes 5a)

prompts/ and runs/ move by git mv; zero padding dropped; the
arbitration and LLM-merge rows in the cost ledger carry no new
name -- their step column reads 已廢棄 with the original name
kept in a new last column.  Archived meta.json files and past
decision-log entries keep the names they were written with.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-18 23:37:32 +08:00

9.0 KiB

Raw Blame History

專案目錄結構

（2026-07-30 討論定案；2026-07-31 更新為 tools/ 子專案與 SQLite 工作儲存架構；2026-08-17 依完成後的現況更新）

pop-fem-audit/
├── README.md                  # 專案說明、重現步驟
├── CLAUDE.md                  # 極簡工作規範（subagent 會讀到，
│                              #   絕不放理論、codebook、預期結果）
├── .gitignore                 # captures/lyrics/、.env、scratch
├── data/                      # 依生命週期分層（文字格式）
│   ├── source/                # 源頭：手放後不動
│   │   └── yearend_hot100_2016_2025.csv   # 原始榜單
│   ├── captures/              # 外部捕捉：只由 fetch 命令與
│   │   │                      #   私人匯入腳本寫入
│   │   ├── artists-wikidata.csv           # Wikidata 快照
│   │   ├── lyrics-provenance.csv          # 歌詞出處
│   │   └── lyrics/                        # 歌詞 .txt 快取
│   │                                      #   （gitignored，版權）
│   ├── manual/                # 人工著作：只由研究者手寫
│   │   ├── coding-corrections.csv         # 編碼與引述的校對表
│   │   └── performer-gender-corrections.csv  # 演唱聲音性別的
│   │                                      #   手工修正
│   └── derived/               # 衍生：只由 build-db 寫入
│       ├── songs.csv          # 歌曲報表（人讀；進 git）
│       └── artists.csv        # 歌手報表（人讀；進 git）
├── prompts/                   # LLM 定義檔（逐字作為 system prompt）
│   └── <步><次步>-<task>.md   # 1-tag.md、3a-code.md、
│                              #   4-group.md、5a-read.md、
│                              #   5b-consolidate.md、
│                              #   5c-synthesize.md、
│                              #   5d-annotate.md
│                              #   （次步以字母標示，與論文正文
│                              #   的步驟編號一致；步內僅一個
│                              #   執行時省略次步）
│                              #   不帶版本號，版本即 git 歷史
│                              #   （編號的所指是工序：確定性
│                              #   的步驟 2 無定義檔仍佔一號）
├── tools/                     # 輔助工具子專案（src-layout）
│   ├── pyproject.toml         #   發行名 pop-fem-audit-tools；
│   │                          #   pip install -e tools/ 安裝
│   ├── README.rst  LICENSE  MANIFEST.in  .env.example  .gitignore
│   ├── docs/                  # Sphinx API 文件
│   ├── instance/              # SQLite 工作儲存（generated、
│   │                          #   gitignored；含歌詞全文）
│   ├── src/pop_fem_audit_tools/
│   │   ├── __main__.py        # 套件 CLI 進入點（分派子命令）
│   │   ├── commands/          # CLI 子命令模組（登記於 __init__）
│   │   │   ├── build_db.py    # build the SQLite working store
│   │   │   │                  #   from the inputs
│   │   │   ├── export_llm_input.py # export the LLM input JSONL
│   │   │   │                       #   (lyrics only) from the
│   │   │   │                       #   working store
│   │   │   ├── fetch_artists.py # fetch artist metadata from
│   │   │   │                    #   Wikidata into the snapshot CSV
│   │   │   ├── fetch_lyrics.py # fetch missing lyrics from the
│   │   │   │                   #   public APIs into the lyrics dir
│   │   │   ├── cluster_keywords.py # pool the tagging runs'
│   │   │   │                       #   keywords and cluster them
│   │   │   │                       #   into the codes (step 2)
│   │   │   ├── tally_codings.py    # settle step 3 by majority
│   │   │   ├── tally_groups.py     # settle step 4 by majority
│   │   │   ├── tally_annotations.py # settle step 5d by majority
│   │   │   └── run_llm.py     # API 執行器：一份定義檔＋一份輸入
│   │   │                      #   →歸檔至指定目錄（Batch API）；
│   │   │                      #   多次執行的計票由獨立子命令承擔
│   │   ├── config.py          # pydantic-settings 設定（.env）
│   │   ├── database.py        # SQLAlchemy engine / session / Base
│   │   ├── models.py          # SQLAlchemy ORM 資料模型
│   │   └── utils.py           # 共用工具（format_duration）
│   └── tests/                 # 單元測試（unittest）
├── runs/                      # 現行執行的完整稽核紀錄（進 git；
│   │                          #   重跑同一 run 須明示 --replace）
│   ├── <步驟名>/              #   一步一個目錄（1-tag、3a-code、
│   │                          #   4-group、5a-read、
│   │                          #   5b-consolidate、
│   │                          #   5c-synthesize、5d-annotate）
│   │   └── run<N>/            #   LLM 步驟：每個 run 一份自我
│   │       ├── prompt.md      #   完備歸檔（定義檔快照）
│   │       ├── output.jsonl   #   該次執行原始輸出
│   │       └── meta.json      #   model ID、temperature、時間戳、
│   │                          #   batch ID、token 用量
│   └── 2-cluster/            # 確定性步驟：無執行變異，
│                              #   不分 run<N> 層
├── results/                   # 論文引用的定案表 CSV（計票子命令
│   │                          #   產出；「可再生仍 commit」的例外）
│   ├── codings.csv            # 步驟 3 定案編碼
│   ├── groups.csv             # 步驟 4 定案編碼群
│   ├── patterns.csv           # 步驟 5c 定案樣態表
│   ├── annotations.csv        # 步驟 5d 定案歌×樣態
│   └── pattern-matrix.csv     # 前四者的人讀寬表
├── docs/
│   ├── research-plan.md       # 研究步驟規劃（本檔之姊妹篇）
│   ├── project-structure.md   # 本檔
│   ├── output-validation.md   # LLM 輸出的契約查核紀錄
│   ├── decision-log.md        # 決策日誌：每次改定義檔的原因
│   ├── run-costs.md           # 每次執行的 token 用量與費用
│   ├── reliability.md         # 信度：量測方式與結果
│   ├── pilot-study.md         # 先導研究的來歷與地位
│   └── methodology.md         # 方法細節（全文方法節底稿；
│                              #   映射分析方法須在看結果前寫定）
└── paper/
    ├── abstract.md            # 摘要
    └── 流行音樂中「女性力量」….odt  # 全文

設計理由

runs/ 自我完備：每個執行目錄含定義檔快照 + 原始輸出 + meta，讀者不需 git 考古即可稽核任一筆結果。
runs/（原始稽核資料）與 results/（最終表）分離：論文只引 results/，其來源可回溯至 runs/。
prompts/ 檔名不帶版本號：版本即 git 歷史，失敗的版本不保留；論文引用的單位是 runs/ 內隨執行保存的定義檔快照（每個執行目錄自我完備），不需檔名可指的版本名。
工作儲存的資料表：songs（含 performer_gender＝演唱聲音的性別）、chart_entries、artists、song_artists、 codings（定案編碼：一歌一標籤一列，quotes 存該標籤所據的歌詞引述，多句以 | 相接）、groups（語意編碼群）、 patterns（深讀樣態）、annotations（歌×樣態定案矩陣）。各定案表經 build-db 的 --codings、--groups、 --patterns、--annotations 匯入，性別修正經 --gender-corrections 套用，與其餘資料同一交易，儲存不會半建；詳見 research-plan.md「資料儲存與模型」。
Commit 判準：能由「committed 輸入＋程式」決定性再生者不 commit（SQLite 工作儲存、LLM 輸入檔）；源頭、捕捉、人工著作一律以文字 commit。「可再生仍 commit」的例外有二： results/ 報表（引用穩定性、審稿人零門檻、撰稿期可 diff）與 data/derived/ 人讀報表（與工作儲存同一動作產出，稽核鏈無中間空缺）。詳見 research-plan.md「資料儲存與模型」。
設定經 pydantic-settings 統一：.env（gitignored，範本 tools/.env.example）供應 SQLALCHEMY_DATABASE_URL 與 ANTHROPIC_API_KEY，絕不寫入 repo。
CLAUDE.md 極簡：實測證實 Claude Code subagent 會繼承專案 CLAUDE.md 全文，故其中只放工作流程規則，領域知識一律放 docs/（subagent 不會自動讀到）。

9.0 KiB Raw Blame History Unescape Escape

專案目錄結構

設計理由

9.0 KiB

Raw Blame History