CLAUDE.md

1# CLAUDE.md
2 
3Coding rules for any AI agent (Claude Code, Claude Desktop, Cursor, etc.)
4working in this repository. Follow every time without exception.
5 
6## Module headers
7 
8Every Python module starts with:
9 
10\`\`\`
11"""
12Role: <one line, what this module is>
13Description: <a few lines, what it does and important details>
14Author: Bor
15"""
16\`\`\`
17 
18Do not change the Author field.
19 
20## Prose style
21 
22No em dashes anywhere. Not in code, comments, docstrings, log messages,
23commit messages, or Markdown. Use a comma, a colon, or two sentences.
24 
25No semicolons in prose. Code semicolons follow Python rules.
26 
27Short scientific sentences. No throat-clearing. Forbidden filler:
28"now", "let's", "we'll", "here we", "essentially", "basically",
29"simply", "just". If a comment says "now do X", delete "now".
30 
31## Comments
32 
33Comments explain what is not obvious from the code. They never restate
34the code in English.
35 
36No section dividers like `# ---- Auth ----` or `# ===== Fetch =====`.
37Function names and module structure are the dividers.
38 
39No step narration like `# 1. authenticate`, `# 2. fetch`. The log lines
40already announce these steps at runtime.
41 
42If a comment exists, it earns its space.
43 
44## Logging
45 
46Use `from spw_attrib.logger import get_logger; log = get_logger(__name__)`.
47 
48Never use `print()` in library or diag code. Logger only.
49 
50Format with `%s` placeholders, not f-strings, so the logger can
51lazy-format and so structured log backends work.
52 
53`log.info` for milestones, `log.warning` for recoverable issues,
54`log.error` for failures.
55 
56## Naming
57 
58Functions describe what they do, not how. `fetch_frames` not
59`do_api_fetch`. `enrich_irbem` not `process_with_model`.
60 
61Private helpers prefix with `_`.
62 
63Constants in module scope are UPPER_SNAKE_CASE.
64 
65## Imports
66 
67Standard library, then third-party, then `spw_attrib.*`. Blank line
68between groups. One import per line. No `from x import *`.
69 
70## Type hints
71 
72Modern syntax: `list[int]`, `dict[str, float]`, `int | None`.
73 
74Type all public function signatures. Internal helpers may skip when
75types are obvious from a one-line body.
76 
77## Errors
78 
79Never silently swallow errors. Catch what you can act on, log the rest,
80re-raise when in doubt.
81 
82Library code does not exit the process. Only entry-point scripts may
83call `sys.exit`.
84 
85## Tests
86 
87Tests live in `tests/`, mirror the source layout. Plain `pytest`.
88 
89Test names describe behaviour, not the function:
90`test_engine_attributes_saa_proton_as_environmental` rather than
91`test_attribute`.
92 
93## Things never to do
94 
95- Emoji in code, comments, or commit messages.
96- ASCII art banners.
97- Unicode smart quotes or fancy bullets in code or docs.
98- Placeholder TODOs without an attached GitLab issue number.
99- Modify rule confidences in `attribution/engine.py` without re-running
100  FLP validation against Noeldeke 2017.
101- Modify the import order in `radiation/irene.py` (the order is
102  load-bearing for the Fortran library).
103- Modify the WGS84 conversion in `ephemeris/coords.py` without
104  re-running the FLP onboard-truth check.
105 
106## Defaults and missing data
107 
108A silent default is a lie. If a value cannot be retrieved or computed, the
109right behaviour is one of these, in this preference order:
110 
1111. Return `None` or `pd.NA` and let the caller decide.
1122. Raise an explicit exception with a message naming the missing input.
1133. Log a WARNING and return a sentinel only when the caller has documented
114   that it accepts and handles the sentinel.
115 
116Never do any of these:
117 
118- Substitute a "reasonable" value (e.g. `Dst = 0`, `Bz = 0`, `Kp = 2`) when
119  the real value is missing. Reasonable values mask gaps in input data and
120  produce attribution verdicts that look defensible but are computed from
121  fiction.
122- Use `dict.get(key, fallback)` for scientific quantities. Use
123  `dict.get(key)` and let `None` propagate, or check membership and raise.
124- Wrap a computation in `try/except Exception: return default_value`.
125  Catch only the specific error class you expect, and only when the
126  recovery path is documented.
127- Fill NaN columns with zero before a statistic. `df.fillna(0).mean()`
128  hides missing data inside the mean. Use `df.mean(skipna=True)` and log
129  the gap count, or `df.dropna()` and report `n_valid`.
130 
131There is one explicit exception: a function may have a "quiet baseline"
132mode where defaults are used deliberately and named in the function
133signature. `enrich_density` does this for the NRLMSIS quiet comparison.
134The defaults are bound by an argument default or a documented module
135constant, and the calling code is explicit about choosing the quiet mode.
136Quiet defaults that exist only inside a fallback path do not qualify.
137 
138When you see a default that fails this test, raise an issue, do not fix
139silently. The fix changes behaviour and needs an explicit review.
140 
141## When in doubt
142 
143Ask. Do not invent a convention. If a file in the repo contradicts
144these rules, the file is wrong. Fix it, do not copy it.
145