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,51 @@
+# Project Workflow Rules
+
+Keep this file minimal.  It is injected into every Claude Code
+subagent; NEVER put research domain knowledge, theory, coding
+criteria, or expected results here.  Domain material lives in
+`docs/` and is read only when explicitly needed.
+
+## Roles
+
+- The main Claude Code session is for discussion, planning, and
+  writing only.  All analysis is executed by deterministic
+  scripts.
+- Claude Code subagents are used only for engineering support
+  (writing scripts, style checks, reviews) — never as research
+  instruments.
+
+## Analysis pipeline (paper-bound work)
+
+- 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/<task>_v<N>.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
+  ("2 runs + 1 arbitration").  If arbitration output is
+  unexpected, revise the definition file and repeat the whole
+  cycle; never patch results by hand.
+- Every execution is archived self-contained under
+  `runs/<phase>/<date>-<prompt-version>/`: prompt snapshot,
+  raw outputs of both runs, arbitration output, and `meta.json`
+  (model ID, parameters, timestamps, batch IDs).
+- Scripts read the API key from the `ANTHROPIC_API_KEY`
+  environment variable (`.env`, gitignored).  Never hardcode
+  keys.
+
+## Data rules
+
+- `data/yearend_hot100_2016_2025.csv` is the only hand-placed
+  raw file; everything else in `data/` is script-derived.
+- Full lyrics are copyrighted: they stay in `data/lyrics/`
+  (gitignored) and must never be committed or reproduced in
+  full anywhere in the repo.
+
+## Documents
+
+- `results/` holds final arbitrated tables (what the paper
+  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.