feat: Add 8 domain papers and RULEBOOK.md

Domain papers distilled from python-numbers-everyone-should-know:
- async-overhead: 1,400x sync vs async overhead
- collection-membership: 200x set vs list at 1000 items
- json-serialization: 8x orjson vs stdlib
- exception-flow: 6.5x exception overhead (try/except free)
- string-formatting: f-strings > % > .format()
- memory-slots: 69% memory reduction with __slots__
- import-optimization: 100ms+ for heavy packages
- database-patterns: 98% commit overhead in SQLite

RULEBOOK.md: ~200 token distillation for coding subagents

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
dafit
2026-01-03 14:31:40 +01:00
parent 4def3b46c2
commit 7efd1368d1
9 changed files with 909 additions and 0 deletions

32
RULEBOOK.md Normal file
View File

@@ -0,0 +1,32 @@
# RULEBOOK: Python Performance
**Load into coding subagents. ~200 tokens. See `/papers/*.md` for deep dives.**
## The Numbers
- Async overhead: **1,400x** (sync 20ns, async 28us)
- Set vs list membership: **200x** at 1000 items
- orjson vs stdlib json: **8x** faster
- Exception raise: **6.5x** (try/except is free)
- SQLite commit: **98%** of write latency
## Rules
**Collections**: Default to `set` for membership. Use `dict.get()` not check-then-access.
**Async**: Default sync. Only async for I/O >1ms. Use `gather()` not loops.
**JSON**: Default `orjson`. stdlib only for zero-deps requirement.
**Exceptions**: try/except is free. Use `.get()` for dicts. EAFP for <15% failure rate.
**Strings**: f-strings default. `%` for logging (deferred eval). `join()` for many parts.
**Memory**: `@dataclass(slots=True)` for 100+ instances.
**Imports**: `TYPE_CHECKING` for heavy types. Lazy imports in CLI tools.
**Database**: DiskCache for key-value. Batch SQLite writes. Reads cheap, writes expensive.
---
*Source: python-numbers-everyone-should-know (Python 3.14.2, Apple Silicon)*