Skip to content

docs: slim CLAUDE.md to what the code and docs don't say - #404

Merged
allen0099 merged 1 commit into
masterfrom
docs/slim-claude-md
Sep 29, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/slim-claude-md

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Rewrites CLAUDE.md from about 12 KB (126 lines) to about 4.6 KB. It keeps only what an agent cannot learn from one file, one grep or --help: invariants that span modules, test pitfalls and contribution conventions. It points to docs/ for the rest.

Kept (condensed)

  • Commands. Plain uv run pytest does not enforce the 90% floor. Redis and Memcached tests are opt-in and flush their server. tox -e lowest. The docs build needs the docs group. CI also runs mypy tests/mypy scripts, which pre-commit does not.
  • Invariants:
    • cache key format and separator escaping;
    • @cache fails open;
    • which callers fall back to MemoryBackend and which call BackendProxy.get();
    • Memcached key enumeration is a no-op, while clear() runs flush_all;
    • every backend must override the atomic primitives;
    • TTL/delta validation runs before I/O;
    • key prefixes.
  • Tests:
    • filterwarnings = error;
    • close_network_clients;
    • examples/ are tested and included in the docs;
    • checking that a test can fail.
  • Conventions:
    • changelog fragments;
    • zh-TW docs mirroring;
    • no hand-edited version;
    • deprecate first, remove in the next minor.

Removed, and where to find it instead

Removed Source
Per-subsystem descriptions (cache flow, CacheManager, sessions, state, lock) Module docstrings; docs/
Per-backend implementation details (Lua scripts, CAS retries, pooling) fastapi_cachex/backends/*.py docstrings; docs/BACKENDS.md "Atomic backend primitives"
Generic commands (run one test, ruff, mypy, tox per version) docs/DEVELOPMENT.md; tox.ini; --help
ruff / mypy / pydocstyle config details pyproject.toml; enforced by pre-commit
pytest options beyond filterwarnings pyproject.toml [tool.pytest.ini_options]
Mentions of SessionMiddleware, the UserSessionDep alias and the memcache extra Stale: removed in 0.4.0 (#398–#403)

@allen0099 allen0099 added documentation Improvements or additions to documentation developer-experience Surprising behaviour, missing warnings or unclear errors for library users labels Sep 29, 2026
@allen0099
allen0099 merged commit c88a45d into master Sep 29, 2026
14 checks passed
@allen0099
allen0099 deleted the docs/slim-claude-md branch September 29, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

developer-experience Surprising behaviour, missing warnings or unclear errors for library users documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant