From 361ca7872e1858ac913e48bb904067029475f007 Mon Sep 17 00:00:00 2001 From: npeter83 Date: Sun, 23 Aug 2026 17:16:46 +0200 Subject: [PATCH] docs: add collaboration section to CLAUDE.md, document ruff format gate - CLAUDE.md: new "Collaboration" section (plan-first, options-with-marked- optimal-and-why, mockups for design decisions, challenge unsound requests, visual UAT before done, terse otherwise). - CLAUDE.md: clarify release is user-owned in timing, agent-run in execution. - CLAUDE.md + docs/development.md: document the ruff format --check gate step (already enforced in .gitea/workflows/check.yml, was missing from the docs). - CLAUDE.md: refresh the stale footer to point at the now-existing docs/development.md and backend/app/README.md. --- CLAUDE.md | 38 ++++++++++++++++++++++++++++++-------- docs/development.md | 3 ++- 2 files changed, 32 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a4a5cde8..8db5c549 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,12 +12,12 @@ provider. ## The gate — never merge or ship red -The local gate is **ruff + typecheck (3 tsc projects) + eslint + prettier --check + knip + vitest + -pytest**. It runs on every `publish`, which **refuses to build on failure — there is deliberately no +The local gate is **ruff (`check` + `format --check`) + typecheck (3 tsc projects) + eslint + prettier +--check + knip + vitest + pytest**. It runs on every `publish`, which **refuses to build on failure — there is deliberately no `--skip` flag.** Run it and get it green **before** any merge, release, or handing work to review. - Full gate (agents with the private ops dispatcher): `siftlode check`. -- Directly, without the dispatcher: `cd frontend && npm run typecheck && npm run lint && npm run knip && npm run test`, plus backend `ruff check backend` and `pytest` (the DB-lane needs Postgres). +- Directly, without the dispatcher: `cd frontend && npm run typecheck && npm run lint && npm run knip && npm run test`, plus backend `ruff check backend` + `ruff format --check backend` and `pytest` (the DB-lane needs Postgres). - New DB-backed test? It must actually run, not silently skip — assume `SIFTLODE_TEST_REQUIRE_DB=1`. ## Workflow @@ -26,12 +26,33 @@ pytest**. It runs on every `publish`, which **refuses to build on failure — th keep commits logical and Conventional-Commit-styled. - **No AI attribution in commits.** No `Co-Authored-By` trailer, no "generated by" lines. (This file being AI-written is the intended, visible exception; commits are not.) -- **Release is a deliberate, user-owned step** (`siftlode release` from the feature branch: merge to - `main` → publish → deploy → verify `/api/version`). Do not self-ship; bring work to a green, - committed state and stop for the user's go-ahead. +- **Release: user-owned in timing, agent-run in execution.** The user decides *when* to ship; on their + go-ahead *you* run `siftlode release` from the feature branch (merge to `main` → publish → deploy → + verify `/api/version`). Never self-ship — bring work to a green, committed state and stop for the + go-ahead first, then run it yourself. - **Public repo.** Keep ops/topology/secrets out — those live in a separate private repo. Nothing here should assume or leak them. +## Collaboration — how to work with the human + +The human is the product owner: they bring ideas and requirements. You are the technical lead — you own +how it gets built. Concretely: + +- **Plan before you build.** For anything non-trivial, present a short plan (sprint-level for larger + work) and get a go-ahead before writing code. +- **Offer choices, mark the optimal — and explain the trade-off.** When several solutions are viable, + list them and mark the recommended one. This is the *one* place to spend extra words: give the *why* + behind each option and the weight of the decision. These decision points are where the product owner + engages with the build and learns from it, so make them understandable — a reasoned menu, not a bare one. +- **Mockups for design/UX decisions.** For any visual or interaction choice, show mockup options to + choose from before building. +- **Challenge unsound requests.** If a request is technically ill-advised and you can back it with real + arguments, push back or propose an alternative — don't comply blindly. +- **Verify UI in the browser before calling it done.** tsc/unit/DOM tests miss visual and interaction + bugs; do a real visual check of any UI change. +- **Be terse everywhere else.** Outside those decision points, lead with the answer or decision. During + implementation and debugging especially: no restating the same point reworded, no filler. + ## Architecture shape (don't fight it) `routes/*` (HTTP only: validation, auth-dependency, serialization) → domain packages `sync/`, `plex/`, @@ -79,5 +100,6 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory --- -*A fuller written-conventions doc (`docs/development.md`) is planned; once it lands, this file slims to a -pointer plus the gate/workflow/no-attribution rules. Until then, the table above is the source of truth.* +*Run-it-locally and the full gate commands live in [`docs/development.md`](docs/development.md); backend +code conventions in [`backend/app/README.md`](backend/app/README.md). This file stays the source of +truth for the canonical-patterns table and the gate/workflow/collaboration rules above.* diff --git a/docs/development.md b/docs/development.md index cc37bc1d..c82a5d9a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -29,8 +29,9 @@ A change is done when all of this is green. CI runs the same checks server-side **Backend** ```bash -# lint +# lint + format check python -m ruff check --config backend/ruff.toml backend scripts +python -m ruff format --check --config backend/ruff.toml backend scripts # tests — pure-logic + the DB-backed integration lane, against an ephemeral Postgres. # The backend tree is bind-mounted, so it always tests your working files.