52 lines
2.0 KiB
Markdown
52 lines
2.0 KiB
Markdown
# 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.
|