Repository navigation
docs: rewrite CLAUDE.md against the current code - #546
Merged
Merged
Conversation
Audit found the previous file had drifted from the codebase and was carrying GitHub-issue history that cost context every session without changing how code gets written here. This rewrite is shorter in words and checked claim by claim against the code, Makefile and CI workflow. Corrections: - Lifecycle hook list was missing register_setup_steps, register_body_limits, register_design_packs and register_audit_links. - Diagnostics (SM0xx) run only in development; production boot is failed by strict discovery, the auth-provider check and SM010, not by the suite. - Migration history has several heads (make migrate runs `upgrade heads`); the Alembic env is host/migrations/env.py. - Inertia render keys use ModuleMeta.name; the i18n namespace and app.state slot use the package name. The two were conflated. - Module settings are DbBackedSettings registered via register_module_settings, not env-driven dataclasses. - No env var is required (SQLite default); Redis uses one SM_REDIS_URL. - `make lint` and the CI job list were incomplete; the hardcoded-string, metadata and README checks are local-only. - gen-pages CSS imports are absolute paths, not a `#module/` alias. - File-size cap exemptions, untranslated-string exemption syntax and the dev-services path were wrong or incomplete. Added: - "Before you push" checklist (gen-pages, lint incl. ruff on .md fences, gen-i18n diff gate, Postgres round trip, CHANGELOG entry). - No-magic-strings constants rule enforced by check_hardcoded_strings.py. - "Adding a module or package" checklist (package-lock, release matrix, docs pages, branch_labels; framework packages wired by hand). - Background tasks, audit links, design packs integration rules; AwareDateTime; session.on_commit; full fixture list. - "Working in parallel": fan out independent slices to subagents with an explicit per-task model, and use the Codex CLI as a read-only second reviewer when it is installed and authenticated. - Pointer to the shipped skills/ directory to keep in sync. Claude-Session: https://claude.ai/code/session_01TJ3Gy55Ngyuj5o4UakoF2v
Deploying simple-module-python with
|
| Latest commit: |
5f603c5
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://b7044a00.simple-module-python.pages.dev |
| Branch Preview URL: | https://ccr-956cd371-ymanmg.simple-module-python.pages.dev |
- `make migration` fails with "Multiple heads"; give the working `revision --autogenerate --head <label>@head` recipe. - The scaffold is not lint-clean (literal render key, magic strings, direct app.state assignment); say so in § Adding a module. - Production boot: name every fatal check (placeholder secrets, localhost broker, SM025 reported, SM010 first-run exception). - Env-reading modules are not only background_tasks; .env/pytest advice states the real mechanism and says to restore the file; redis fixture skips locally and fails only under CI. - Restore dropped rules: configuration lives in the DB, active-tenant routes, tenant_resolver, invalidation TTL floor, CSP provider, SetupAction, menu label fallback, secret never copied to DB, playwright install. - Narrow AwareDateTime to explicit column types; default_tenant stamping; i18n.messages null on every X-Inertia request; rate limit "by default". - Codex: probe with `command -v codex`, no npx, review via `exec -s read-only review --base main`, forbid the bypass flags. - framework/* packages also need the publish-pypi matrix; § Styling link. Claude-Session: https://claude.ai/code/session_01TJ3Gy55Ngyuj5o4UakoF2v
Broaden the Codex rule from "read-only second reviewer" to a parallel subagent for any independent slice. Read-only slices run with `-s read-only`; write slices get their own git worktree via `-C` so two agents never edit one working tree, and their diff is reviewed before it merges into the branch. The bypass flags stay forbidden. Claude-Session: https://claude.ai/code/session_01TJ3Gy55Ngyuj5o4UakoF2v
antosubash
marked this pull request as ready for review
October 19, 2026 04:55
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Resolve the CLAUDE.md conflict by keeping the rewrite and folding in main's additions from #550 and #525: pytest-xdist parallel runs (`-n auto --dist loadgroup`, `PYTEST_WORKERS=0`), the serial Postgres suite, single tests running in-process, the test plugin's reduced password-hash work factor and `SM_TEST_REAL_PASSWORD_HASHING`, and the xdist collection rules (deterministic parametrize ids, per-worker names). Claude-Session: https://claude.ai/code/session_01TJ3Gy55Ngyuj5o4UakoF2v
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
An audit of
CLAUDE.mdagainst the code,Makefileandpr.ymlfound it had drifted: missing lifecycle hooks, a wrong Alembic env path, a claim that diagnostics run in production (they don't), a "linear migration chain" that has four heads, and a per-module settings description that no module follows. It also carried several hundred words of GitHub-issue history that every session paid for in context without it changing how code gets written. Rationale now lives behind links intodocs/, which already covers it.Every concrete claim in the new file was checked against code by three fact-check passes plus one adversarial review, and the corrections from that review are in the second commit. The third commit broadens the Codex rule.
Corrections
register_setup_steps,register_body_limits,register_design_packs,register_audit_links.SM0xx) run only in development; production boot is failed by strict discovery, the auth-provider check, placeholder secrets, a localhost broker andSM010.make migraterunsupgrade heads; env ishost/migrations/env.py.make migrationcurrently fails with "Multiple heads are present"; the file gives the working--head <label>@headrecipe (see follow-ups).ModuleMeta.name; i18n namespace andapp.stateslot use the package name.DbBackedSettingsregistered throughregister_module_settings; env applies only to secrets/process wiring.SM_REDIS_URL.make lintcontents and the CI job list; hardcoded-string, metadata and README checks are local-only.gen-pagesCSS imports are absolute paths; file-size exemptions; untranslated-string exemption syntax; dev-services path is../dev-services.Added
.mdfences,gen-i18ndiff gate, migration review, CHANGELOG entry).check_hardcoded_strings.py).make lint,package-lock.json,release.ymlmatrices, docs pages,branch_labels; framework packages wired by hand.AwareDateTime,session.on_commit, full fixture list.command -v codex && codex login status):codex exec -s read-onlyfor review and fact-check slices,-s workspace-writeonly inside its owngit worktreefor write slices, bypass flags forbidden.skills/directory to keep in sync.Follow-ups found but out of scope here
make migrationis broken while the history has several heads (Makefile:184passes no--head). Either take ahead=<label>argument or merge the heads withalembic merge heads.make new-modulescaffold emits code that failsmake lint: literalinertia.render("<Class>/Create")(scripts/_templates_endpoints.py:106), permission/menu strings without constants orlabel_key, and directapp.state.<pkg>assignment instead ofregister_module_settings(scripts/_templates_module.py:35-39).docs/module-authoring.md§ Multi-module branches ("chains linearly"),skills/simple-module-testing(vitest does collectmodules/**/tests-js; e2e is in PR CI),skills/simple-module-doctorandskills/README.md(codes stop at SM021),skills/simple-module-registries(missing most hooks),docs/release.md(13 vs 20 PyPI packages),docs/framework-conventions.mdand_dev_boot.pydocstring (say diagnostics run in production),.claude/skills/running-the-stack(".env beats process env" is backwards; the leak is the unpinnedvite_dev_urlin the settings fixture).https://claude.ai/code/session_01TJ3Gy55Ngyuj5o4UakoF2v