Add CLAUDE.md (#839)

* Add CLAUDE.md project reference

Rewrite of the CLAUDE.md from jg/add_functions_for_per_base_constraint,
restructured to stay accurate as the code evolves: function inventories
and file-level tables are replaced with a stable subpackage map and
guidance on discovering APIs from the code itself. Adds verified facts
the original missed: the Sphinx -W docs CI job, the downstream gnomad_qc
pylint check, the forced local Spark backend in tests/conftest.py, and
the release flow.

* Add local claude mds to gitignore

* Address review feedback and incorporate CLAUDE.md survey responses

Review comments:
- Refer to "Ensembl VEP" throughout (trademark enforcement request)
- Restore the "this is a library, not a pipeline" framing
- Apply suggested wording for the utils and sample_qc layout rows
- Put the docstring summary line on its own line (matches 899 of 936
  docstrings in the repo)
- "All functions must have type annotations on parameters and return values"
- Add the caveat that naive_coalesce often runs very early in pipelines
- Downgrade _localize=False from a recommendation to a caution, noting the
  Hail team has advised against relying on it

From the survey responses:
- Read and confirm, never guess — with the efficiency-claims example
- Reusability/discoverability is the point of this public repo
- The gnomad_methods <-> gnomad_qc boundary and its wrapper cycles
- Lazy evaluation: log after write/checkpoint, not before
- Checkpoints cost storage callers don't know they're paying for
- Avoid shuffles; re-keying shuffles; shuffle traces mislead
- Never repartition() — naive_coalesce to reduce, repartition on read to
  increase
- Partitioning rules of thumb, including many-to-few-partition joins
- Aggregations are costly; make one pass with a single aggregator
- Hail still defaults to GRCh37
- Docstrings: no :raises:, thorough but not wordy
- Tests: range_table, no GCS reads, no near-duplicate tests, and small tests
  do not prove behavior at scale
- Execution paths, cost/cluster conventions, Hail forwards-incompatibility,
  the 0.2.130 -> 0.2.131 regression, and requester-pays egress surprises
- A "Never Do This" section

* Update CLAUDE.md and README.md after group review during institutional knowledge doc

---------

Author: mike-w-wilson

.gitignore

@@ -106,3 +106,7 @@ ENV/
 
 # tokens
 slack_creds.py
+
+# Claude local files
+CLAUDE.local.md
+.claude/settings.local.json