flow CLAUDE.md

CLAUDE.md

Guidance for AI agents working in this repository.

Documentation index

docs/index.md is the index of all architecture/design/research docs. Whenever you add, remove, or move a document under docs/, update docs/index.md in the same change.

Before pushing a branch or opening/updating a PR

before push final results to repo - run the full check suite in Docker first, and only push once it is green:

docker compose exec -T web make check_all

check_all mirrors CI in a single pass and never short-circuits — it captures each result and prints a summary of all failures:

• Backend: rails test, rubocop, brakeman
• Frontend: eslint, typescript (tsc), vitest

(CI splits this into be_check_all + fe_check_all; check_all covers both locally.) Don't push a branch or open/update a PR until check_all is green — it catches what a partial, hand-picked test run misses.

Docker is required

NEVER run ruby, bundle, rails, rake, or any gem/node-dependent command directly on the host. This rule applies to Claude itself AND to every subagent Claude spawns — include it explicitly in every subagent prompt.

Rails, tests, and migrations run only inside the web container — the host has no bundled gems, and its node_modules is Linux-built (native bindings fail on the host). If the container isn't running: docker compose up -d.

• Backend tests: docker compose exec -T web bin/rails test <files>
• Frontend tests: docker compose exec -T web ./node_modules/.bin/vitest run <files> (npx is not on the container PATH)
• Full suite before push: docker compose exec -T web make check_all

Never run two backend test invocations at the same time (including from another agent session or a git worktree that shares a Postgres — overlapping runs corrupt each other's aixle_test and the per-worker databases). make-driven runs are flock-serialized; direct bin/rails test runs are not — check nothing else is running first.