Lean ruleset for a single-package Python library (PyPI distributable),
distilled from a larger application ruleset. Applies to libraries like
pluginforge, manuscripta, or any future PyPI package in the same
spirit.
| File | Purpose | When loaded |
|---|---|---|
rules/coding-standards.md |
Naming, type hints, function design, DRY, Boy Scout | On request, or for code-writing tasks |
rules/code-hygiene.md |
Ruff/black/mypy config, pre-commit, exception hierarchy, logging, docstrings | On request, or before commits |
rules/quality-checks.md |
Test strategy (pytest, mutmut), coverage targets | Before releases, audits, or tests |
rules/ai-workflow.md |
Session start, feature order, communication, documentation protocol | Always (referenced from CLAUDE.md) |
rules/release-workflow.md |
PyPI release, SemVer, CHANGELOG | On release-trigger prompts |
rules/lessons-learned.md |
Library-specific pitfalls, grows over time | On request, or when adjacent to the affected code |
prompts/audit.md |
Drop-in prompt for a systematic library audit | Manual paste |
CLAUDE.md stays under ~8 KB. It points to these files; large rule
files are not auto-loaded. When a rule file is needed, the prompt
should reference it by path (see code-hygiene.md "Error handling").
- Framework-specific rules (FastAPI, Django, Flask, SQLAlchemy)
- Frontend rules (React, TypeScript, CSS)
- Multi-surface release tooling (lock-step versioning across N packages)
- Plugin-lifecycle rules (these belong in the app that consumes the lib)
If the library grows a framework dependency or a second surface, add a dedicated file rather than expanding these.
- Copy
.claude/into the repo root. - Copy
CLAUDE.md.templatetoCLAUDE.mdand fill in the{lib_name},{description},{version}placeholders. - Replace
LibErrorplaceholders inrules/code-hygiene.mdwith the project's exception base class name (e.g.PluginForgeError). - Start with an empty
lessons-learned.md; let real pitfalls fill it.