ENAC IT4R — agent operating rules¶
This file is the canonical, tool-neutral instruction set for any AI coding
assistant (Claude Code, OpenCode, Cursor, Codex, …) working on an ENAC IT4R
project. CLAUDE.md imports it; SKILL.md routes to it. Edit the rules
here, once.
These are the rules we found load-bearing across our FastAPI + SQLModel + Alembic / Vue + Quasar + TypeScript stack. When this file and your instinct disagree, this file wins. When this file and the project's own rules disagree, the project wins — a consuming repo layers its specifics on top (see "Adopting this" at the bottom).
Source-of-truth hierarchy¶
Read top-down. Lower tiers refine higher tiers, never override them.
- Spec / CRD — scope, mandate, acceptance criteria. Not in the spec, out of scope.
- ADRs — accepted architectural decisions. An accepted ADR binds; a superseded one is history.
- Implementation plans — issue-scoped detail. Check frontmatter
statusbefore trusting. - Code — ground truth. Docs and code disagree → code wins, and file a
docsissue.
Before you code¶
- Find the plan. Grep the plans directory for the issue number or module name and read what shipped. Highest-leverage habit in any of our repos.
- No plan for your issue? Write one first. Every issue ends with a
delivered plan file — small fixes get a short one, backfilled at worst. If
your PR diverges from its plan, update the plan in the same PR. See the
plan-conventionsskill for the file shape. - Mirror, don't invent. New modules copy the shape of an existing module; new endpoints copy a neighboring router. A new pattern needs a written reason (ADR) the existing one can't give.
Architecture invariants¶
Not preferences. Load-bearing.
- Backend is the single source of truth. Every formula, aggregation, and transform lives server-side. The frontend renders backend output — never reimplement a computation client-side. Two implementations drift, and a drifted published number is the worst failure a data product can have.
- Respect the layering — no SQL in routes.
route → service → repo, orroute → workflow → service → repofor multi-step operations. Repos own the SQL, services own the logic, and the transaction belongs to whatever the route delegates to: a route calling services directly owns the commit — a service or repo never commits; a workflow owns its own commits (that is why it exists: multi-step work, possibly several short transactions, possibly handing the heavy part to a background job). Never both in one request path. - A service serves one aggregate; crossing aggregates is a workflow. A service composes its own table family through its repo. The moment an operation orchestrates several aggregates — create-then-fan-out, cascade deletes, cross-entity sync — it is a workflow, named after the operation, not a service calling other services. Side-effect writes hidden inside an unrelated service call (lazily creating a parent row, syncing a sibling) are the silent-fallback family: existence and provisioning are explicit workflow steps, never a branch discovered mid-request. Existing service webs migrate opportunistically — the rule binds new code.
- No silent fallbacks. No "misc" buckets, no swallowed exceptions, no
defaulted-away missing data. A wrong total that looks complete is worse
than a visible error. Fail hard:
raise, don'tlogger.errorand carry on — a log line nobody reads is a silent fallback. - Frontend never checks roles. UI gates on dedicated permission keys; the
backend decides what a role means. Authorization fails closed. Boot-time
config checks live in the app lifespan, not in
Settingsvalidators. - Persisted data survives deploys. Data migrations ship in the same PR as
the code change. Never hand-author Alembic migrations — generate them, then
prune false-positive
drop_indexcalls. Keep manual edits to a generated migration minimal: anything expressible in model code belongs in model code. Browser storage and exported files count too: version them, migrate old versions, and fail loudly on an unknown one. Don't persist a derived value next to its inputs unless it's a deliberate, recomputable cache. - Background pipelines stay idempotent. Ingestion and recompute must be safely re-runnable.
- No backward-compatibility paths. When the new way ships, delete the old way in the same PR. No dual-path bloat.
Safety¶
- Never commit a credential, even in a throwaway script — read it from the environment. A force-push does not unpublish a pushed secret: rotate it first.
- Agents never run queries,
db-*targets, or DB-touching tests against a shared database. Check what.envpoints at first; hand the SQL to a human.
Performance budget¶
- An endpoint answers in < 80 ms locally. Deployed DBs run several times slower than local — measure yours and scale the target accordingly.
- The real goal: page response < 400 ms in the deployed environment, which means a page's combined calls stay near 100 ms locally.
- Minimize XHR calls per page — extend an existing endpoint or batch before adding a new call.
Frontend rules¶
- Follow the project's existing CSS architecture — never add a parallel
styling approach. (For EPFL brand work, use the
epfl-designskill.) - Icons are SVG. Do not add icon fonts.
- All HTTP goes through the centralized client, via a module file in
api/— neverfetch, axios, or raw ky from a component. - Layout lives in
pages/, logic lives incomponents/built for reuse. The page composes, the components carry the logic. - Minimize layers: no new wrappers, stores, or indirection a page can do without. Shared state that must exist goes in Pinia, strongly typed.
- Form, table, and chart values stay consistent — same backend source, stable keys, deterministic ordering. Creating or editing an entry updates visible charts without leaving the page.
- No hardcoded user-facing strings — every label goes through i18n, and all locale files are updated together. Numbers and dates format through the i18n locale, never a hard-coded one.
- Derive with
computed, react in handlers.watchis only a bridge to side effects outside Vue (refetch on locale change), with a comment saying so. - ESLint baseline:
js.configs.recommended,pluginVue.configs['flat/recommended'],vueTsConfigs.recommended, theneslint-config-prettier. Prettier formats. - Visual components show explicit loading/empty/error states — never a silent blank.
Style rules¶
- Python: functions ≤40 lines, ≤2 nesting levels, single responsibility.
Imports at top of file, never inline. No
assertfor runtime narrowing — useif x is None: raise ValueError(...)(bandit strips asserts under-O). - SQLModel: wrap column refs in
col(); importfunc/case/or_/ascfromsqlmodelwhen re-exported there, not fromsqlalchemy. - No type suppressions — no
# type: ignore, no@ts-expect-error/@ts-ignore. Fix the types instead. In the rare case one is truly unavoidable, it carries the specific error code and a one-line reason. - TypeScript:
catch (e: unknown), narrow withinstanceof Error. Vue components hard-capped at 500 lines — extract composables at 400. - No defensive programming: no guards for states the types make impossible.
- Default at the top,
ifguards override it. Avoidif/elsebranching and falsyordefaults. - Comments explain intent (why), not implementation (what); 1–2 lines. Infra glue (Dockerfile, entrypoint, boot file) always says why it exists.
- No real-sounding names in code, tests, or docs — refer to people by role ("a backoffice admin").
Workflow¶
- Releases flow
dev→stage→main. PRs targetdev. Never delete or force-push a protected branch. - Conventional commits (
feat:,fix:, …), body wrapped at 72. A rejected commit leaves its files staged — checkgit show --statbefore pushing. - No AI attribution: no agent
Co-Authored-Byor session trailer, no "Generated with" footer — in commits, PRs, or issues. - Lint + type-check must pass locally before pushing. A plain
tscpass is not sufficient for Vue projects — runvue-tsc. - CI and git hooks call the same check-only targets (
make lint,npm run format:check), defined once. CI never runs a--write, always runs the tests, and is a required check ondevandmain. - Fetch before acting on remote state (rebase, force-push, "up to date"
claims). After a push, check the PR head SHA matches
git ls-remotebefore calling the PR ready. - Backend dependencies change via
uv add/uv remove, never by hand-editingpyproject.toml. - Every bug fix ships with a regression test that fails without the fix, and every change ships with a test on the side it touches.
- Ship small. Several small releases beat one big one; a small release is one you can revert.
- Refactor first, then change behaviour — separate commits, so each diff is either "same behaviour, new shape" or "new behaviour, same shape".
- Same issue, same PR. A stray finding goes into the PR of the issue it belongs to, or is mentioned in one line — never its own side PR.
- Measure before claiming a CI or performance gain; put the before/after numbers in the issue.
- When in doubt, apply the invariant that generalizes: no silent fallbacks. Making the uncertainty visible — a loud error, a blocked PR, a question on the issue — is always the right call.
Adopting this in a project¶
The consuming repo keeps a short local rules file for what is genuinely its
own: commands (make ci, make db-revision), branch exceptions, perf numbers,
module-specific patterns, and anything situational. It links here for the rest
rather than copying — two rulebooks drift, which is the failure mode this file
exists to prevent.