Move CLAUDE.md to docs/conventions.md so subagents do not inherit it
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,78 @@
|
||||
# Project Conventions
|
||||
|
||||
The standing working rules of this project. Formerly the
|
||||
project `CLAUDE.md`; moved here so that Claude Code subagents
|
||||
do not inherit it into their context (blind-reading agents
|
||||
must not see it). A main session working on this project
|
||||
reads this file before touching the pipeline, the data, or
|
||||
the documents.
|
||||
|
||||
## Analysis pipeline
|
||||
|
||||
The pipeline has run to completion; these conventions govern
|
||||
any rerun or extension.
|
||||
|
||||
- LLM analysis runs via Python scripts calling the Anthropic
|
||||
Messages API, Batch API where possible. Steps 1 and 3 run
|
||||
on `claude-sonnet-4-6` with `temperature=0` and thinking
|
||||
disabled; steps 4 and 5 run on `claude-fable-5`, which
|
||||
accepts neither parameter -- step 4 absorbs its sampling
|
||||
variance by the majority vote, step 5 by consolidating the
|
||||
three readings.
|
||||
- Prompt definition files live in
|
||||
`prompts/<step><substep>-<task>.md` (e.g. 1-tag.md,
|
||||
5a-read.md; substeps are lettered, matching the step
|
||||
numbering of the paper; no version suffix -- versions live
|
||||
in git history) and are passed verbatim as the system
|
||||
prompt. The number names a step of the research
|
||||
procedure, not the file: the deterministic vocabulary step
|
||||
(step 2) has no definition file yet holds its own number.
|
||||
- Itemwise LLM judgments (per-song coding in step 3,
|
||||
per-keyword group selection in step 4) run the same
|
||||
definition file three times, independently, over the same
|
||||
input; a deterministic tally then assigns an item (a
|
||||
(song, keyword) or (group, keyword) pair) when at least
|
||||
two of the three runs assign it ("3 runs + majority
|
||||
vote"). Free-generation steps run
|
||||
twice and both outputs are pooled. The step-5 qualitative
|
||||
readings are neither: three independent readings per song,
|
||||
consolidated per song and synthesized across songs by
|
||||
their own definition files -- a qualitative protocol, not
|
||||
a vote (see docs/methodology.md). The vocabulary is
|
||||
built by a deterministic subcommand (embedding +
|
||||
clustering), not by an LLM. If a validation outcome is
|
||||
unexpected, revise the definition file and repeat that
|
||||
cycle; never patch results by hand.
|
||||
- Each run of a step is archived self-contained under the
|
||||
destination directory given explicitly on the `run-llm`
|
||||
command line (by convention `runs/<step>/run<N>/`):
|
||||
prompt snapshot, raw output, and `meta.json` (model ID,
|
||||
parameters, timestamps, batch ID). The runs of a step are
|
||||
that many separate invocations of `run-llm`. Replacing
|
||||
an existing run archive requires an explicit flag;
|
||||
superseded runs live in git history. Deterministic steps
|
||||
archive under `runs/<step>/` with no `run<N>` level.
|
||||
- Token usage and cost of every `run-llm` execution are
|
||||
recorded in `docs/run-costs.md` in the same commit as the
|
||||
run archive.
|
||||
- Scripts read the API key from the `ANTHROPIC_API_KEY`
|
||||
environment variable (`.env`, gitignored).
|
||||
|
||||
## Data rules
|
||||
|
||||
- `data/source/` holds the immutable hand-placed raw files;
|
||||
`data/captures/` is written only by the fetch commands and the
|
||||
private import script; `data/manual/` is written only by the
|
||||
user's own hand; `data/derived/` is written only by the
|
||||
`build-db` subcommand.
|
||||
- Full lyrics are copyrighted: they stay in `data/captures/lyrics/`
|
||||
(gitignored) and must never be committed or reproduced in
|
||||
full anywhere in the repo.
|
||||
|
||||
## Documents
|
||||
|
||||
- `results/` holds the final tallied tables (what the paper
|
||||
cites); `runs/` holds raw audit records. The paper cites
|
||||
`results/` only.
|
||||
- Any change to a definition file or the plan is recorded in
|
||||
`docs/decision-log.md` with date and reason.
|
||||
@@ -932,3 +932,15 @@
|
||||
LLM 合併嘗試 `01-02-01-merge`、步驟 3 的仲裁
|
||||
`03-02-arbitration`)其歸檔已不存在,無現行編號可指,
|
||||
不另發新名,步驟欄逕標「已廢棄」,原名存於末欄。
|
||||
|
||||
- **CLAUDE.md 移為 `docs/conventions.md`**:專案 CLAUDE.md 會
|
||||
全文自動注入每一個 Claude Code subagent 的 context(2026-07-30
|
||||
實測條),步驟 6 的 883 個盲判 agent 因此都看到了工作規範。
|
||||
規範本身無研究語意(無 women-power、無假說),污染有限,但
|
||||
「防脈絡污染」的原則應貫徹到自家工具鏈:docs/ 底下的檔案
|
||||
不會自動注入,搬移後 subagent 除非主動翻閱否則不會看到,
|
||||
盲判 agent 的定義檔並明令不得查閱專案材料。代價是主會話
|
||||
也不再自動載入,須自行先讀 `docs/conventions.md`。內容
|
||||
順帶微調:註明管線已完成、規範適用於重跑;刪去已不存在
|
||||
的 codebook 一詞。進論文的數據一律走 Anthropic API(無
|
||||
檔案系統,機制上不可能讀到),此層防線不受本次搬移影響。
|
||||
|
||||
@@ -6,8 +6,6 @@ SQLite 工作儲存架構；2026-08-17 依完成後的現況更新）
|
||||
```
|
||||
pop-fem-audit/
|
||||
├── README.md # 專案說明、重現步驟
|
||||
├── CLAUDE.md # 極簡工作規範（subagent 會讀到，
|
||||
│ # 絕不放理論、codebook、預期結果）
|
||||
├── .gitignore # captures/lyrics/、.env、scratch
|
||||
├── data/ # 依生命週期分層（文字格式）
|
||||
│ ├── source/ # 源頭：手放後不動
|
||||
@@ -91,6 +89,8 @@ pop-fem-audit/
|
||||
│ ├── annotations.csv # 步驟 5d 定案歌×樣態
|
||||
│ └── pattern-matrix.csv # 前四者的人讀寬表
|
||||
├── docs/
|
||||
│ ├── conventions.md # 常設工作規範（原 CLAUDE.md；
|
||||
│ │ # 移入 docs/ 使 subagent 不繼承）
|
||||
│ ├── research-plan.md # 研究步驟規劃（本檔之姊妹篇）
|
||||
│ ├── project-structure.md # 本檔
|
||||
│ ├── output-validation.md # LLM 輸出的契約查核紀錄
|
||||
@@ -132,6 +132,8 @@ pop-fem-audit/
|
||||
- **設定**經 pydantic-settings 統一：`.env`（gitignored，範本
|
||||
`tools/.env.example`）供應 `SQLALCHEMY_DATABASE_URL` 與
|
||||
`ANTHROPIC_API_KEY`，絕不寫入 repo。
|
||||
- **CLAUDE.md 極簡**：實測證實 Claude Code subagent 會繼承專案
|
||||
CLAUDE.md 全文，故其中只放工作流程規則，領域知識一律放
|
||||
`docs/`（subagent 不會自動讀到）。
|
||||
- **不設 CLAUDE.md**：實測證實 Claude Code subagent 會繼承專案
|
||||
CLAUDE.md 全文（原本因此只放極簡工作規則），2026-08-18 進一步
|
||||
將其移為 `docs/conventions.md`——docs/ 不會自動注入 subagent
|
||||
的 context，盲判型 agent 便不會看到工作規範；主會話動手前
|
||||
自行閱讀之。
|
||||
|
||||
Reference in New Issue
Block a user