EverOS/.claude/rules/module-docstring.md

paths
src/everos/infra/**/*.py src/everos/memory/**/*.py src/everos/service/**/*.py src/everos/component/**/*.py src/everos/core/**/*.py

Module docstring rule

Every non-trivial module in the domain/infra layers opens with a docstring that explains intent and contract, not just a one-line label.

A good module docstring states:

• What the module is responsible for (one sentence).
• The load-bearing invariants — the rules a reader must know to change it safely (partition keys, what is/isn't written, defaults, ignored flags).
• External usage when the module is a package facade (a short import example).

Example (abbreviated, from memory/search/manager.py):

"""SearchManager — top-level orchestrator for POST /api/v1/memory/search.

Hard partition by owner_type: user → episodes (+ profiles), agent →
agent_cases + agent_skills. The manager never writes to storage; it only
reads LanceDB + markdown.
"""

Prefer prose that would save the next engineer a debugging session over boilerplate. If a module is genuinely trivial (a 3-line constant), a one-liner is fine — but most modules here are not.