diff --git a/CLAUDE.md b/CLAUDE.md index 3562b45..21a3713 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,7 @@ - LLM analysis runs via Python scripts calling the Anthropic Messages API: model `claude-sonnet-4-6`, `temperature=0`, thinking disabled, Batch API where possible. -- Prompt definition files live in `prompts/_v.md` and +- Prompt definition files live in `prompts/-v.md` and are passed verbatim as the system prompt. - Every LLM step runs the same definition file twice, then a separate arbitration step reconciles the two outputs @@ -36,4 +36,4 @@ cites); `runs/` holds raw audit records. The paper cites `results/` only. - Any change to a definition file, the codebook, or the plan is - recorded in `docs/decision_log.md` with date and reason. + recorded in `docs/decision-log.md` with date and reason. diff --git a/README.md b/README.md index 1d21574..31d8b88 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ Hot 100(2016–2025)為例的內容分析。 ## 目錄結構 -見 `docs/project_structure.md`。研究步驟規劃見 -`docs/research_plan.md`;方法細節見 `docs/methodology.md`; +見 `docs/project-structure.md`。研究步驟規劃見 +`docs/research-plan.md`;方法細節見 `docs/methodology.md`; 人工編碼手冊見 `docs/codebook.md`;決策日誌見 -`docs/decision_log.md`。 +`docs/decision-log.md`。 ## 重現方式 @@ -18,7 +18,7 @@ Hot 100(2016–2025)為例的內容分析。 `pip install -e tools/`。 2. 自 `tools/.env.example` 建立 `tools/.env`,寫入 Anthropic API 金鑰。 -3. 依 `docs/research_plan.md` 的階段順序,於 `tools/` 目錄下 +3. 依 `docs/research-plan.md` 的階段順序,於 `tools/` 目錄下 執行子命令,必要輸入以位置引數、選擇性輸入以選項給定(如 `pop-fem-audit-tools build-db ../data/source/yearend_hot100_2016_2025.csv diff --git a/docs/decision_log.md b/docs/decision-log.md similarity index 96% rename from docs/decision_log.md rename to docs/decision-log.md index 3baccc5..8884eac 100644 --- a/docs/decision_log.md +++ b/docs/decision-log.md @@ -224,6 +224,13 @@ `find_violations` 刪除。理由:檢查跟著產生資料的工作走, main 不再有驗證分支;逐筆即時失敗使錯誤指向出錯的那筆 署名。 +- **Markdown 檔名一律以 dash 連接**(decision-log.md、 + research-plan.md、project-structure.md 等;與 data/ 層 + CSV 檔名慣例一致),定義檔命名慣例同步改為 + `prompts/-v.md`(如 screen-v1.md),版本庫外的 + 私人工作檔一併改名;`conference_abstract.md` 改名並搬入 + `paper/`——它是本次年會實際送出的摘要,與全文同屬投稿 + 血脈,不是 `docs/` 的內部工作文件。全 repo 指涉同步更新。 - **fetch-lyrics 移除缺漏報表**:刪去 `missing_csv` 位置引數 與缺漏報表 CSV 輸出。理由:該報表只寫不讀(指令從未讀取 它),缺漏數字每次執行皆由工作儲存比對歌詞目錄重新算出; diff --git a/docs/project_structure.md b/docs/project-structure.md similarity index 91% rename from docs/project_structure.md rename to docs/project-structure.md index e4f561a..4b8d395 100644 --- a/docs/project_structure.md +++ b/docs/project-structure.md @@ -9,7 +9,6 @@ pop-fem-audit/ ├── CLAUDE.md # 極簡工作規範(subagent 會讀到, │ # 絕不放理論、codebook、預期結果) ├── .gitignore # captures/lyrics/、.env、scratch -├── conference_abstract.md # pilot 摘要(投稿版) ├── data/ # 依生命週期分層(文字格式) │ ├── source/ # 源頭:手放後不動 │ │ └── yearend_hot100_2016_2025.csv # 原始榜單 @@ -25,7 +24,7 @@ pop-fem-audit/ │ ├── songs.csv # 歌曲報表(人讀;進 git) │ └── artists.csv # 歌手報表(人讀;進 git) ├── prompts/ # LLM 定義檔(逐字作為 system prompt) -│ └── _v.md # 版本化:screen_v1.md、judge_v2.md… +│ └── -v.md # 版本化:screen-v1.md、judge-v2.md… ├── tools/ # 輔助工具子專案(src-layout) │ ├── pyproject.toml # 發行名 pop-fem-audit-tools; │ │ # pip install -e tools/ 安裝 @@ -60,14 +59,15 @@ pop-fem-audit/ ├── results/ # 論文引用的報表 CSV(export 產出; │ # 「可再生仍 commit」的唯一例外) ├── docs/ -│ ├── research_plan.md # 研究步驟規劃(本檔之姊妹篇) -│ ├── project_structure.md # 本檔 +│ ├── research-plan.md # 研究步驟規劃(本檔之姊妹篇) +│ ├── project-structure.md # 本檔 │ ├── codebook.md # 人工編碼手冊(版本由 git 管理) -│ ├── decision_log.md # 決策日誌:每次改定義檔的原因 +│ ├── decision-log.md # 決策日誌:每次改定義檔的原因 │ └── methodology.md # 方法細節(全文方法節底稿; │ # 映射分析方法須在看結果前寫定) └── paper/ - └── full_paper.md # 全文 + ├── abstract.md # 摘要 + └── full-paper.md # 全文 ``` ## 設計理由 @@ -77,13 +77,13 @@ pop-fem-audit/ - **`runs/`(原始稽核資料)與 `results/`(最終表)分離**: 論文只引 `results/`,其來源可回溯至 `runs/`。 - **`prompts/` 用檔名版本化**(不只靠 git 歷史):定義檔版本是 - 論文附錄的引用單位,須可直接指名(如 judge_v2.md)。 + 論文附錄的引用單位,須可直接指名(如 judge-v2.md)。 - **Commit 判準**:能由「committed 輸入+程式」決定性再生者不 commit(SQLite 工作儲存、LLM 輸入檔);源頭、捕捉、人工著作 一律以文字 commit。「可再生仍 commit」的例外有二: `results/` 報表(引用穩定性、審稿人零門檻、撰稿期可 diff) 與 `data/derived/` 人讀報表(與工作儲存同一動作產出,稽核 - 鏈無中間空缺)。詳見 `research_plan.md`「資料儲存與模型」。 + 鏈無中間空缺)。詳見 `research-plan.md`「資料儲存與模型」。 - **設定**經 pydantic-settings 統一:`.env`(gitignored,範本 `tools/.env.example`)供應 `SQLALCHEMY_DATABASE_URL` 與 `ANTHROPIC_API_KEY`,絕不寫入 repo。 diff --git a/docs/research_plan.md b/docs/research-plan.md similarity index 98% rename from docs/research_plan.md rename to docs/research-plan.md index 76a5d0d..cac106c 100644 --- a/docs/research_plan.md +++ b/docs/research-plan.md @@ -1,13 +1,13 @@ # 研究步驟規劃 (2026-07-30 討論定案、2026-07-31 增補資料架構; -後續變更請記入 `decision_log.md`) +後續變更請記入 `decision-log.md`) ## 總體框架 - **研究敘事**:全文為獨立完整的正式研究(2016–2025 十年語料 共 1000 筆榜單紀錄,凍結程序後全量執行),**不與先導研究 - (conference_abstract.md)做比較**;全文數字一律以正式研究 + 做比較**;全文數字一律以正式研究 結果為準。先導研究僅作為 codebook v0 與假說的內部來源, 記於決策日誌,不進入論文敘事。 - **執行原則**:主會話只做討論;所有分析由 deterministic script diff --git a/conference_abstract.md b/paper/abstract.md similarity index 100% rename from conference_abstract.md rename to paper/abstract.md