Skip to content

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.

  1. Spec / CRD — scope, mandate, acceptance criteria. Not in the spec, out of scope.
  2. ADRs — accepted architectural decisions. An accepted ADR binds; a superseded one is history.
  3. Implementation plans — issue-scoped detail. Check frontmatter status before trusting.
  4. Code — ground truth. Docs and code disagree → code wins, and file a docs issue.

Before you code

  1. 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.
  2. 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-conventions skill for the file shape.
  3. 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, or route → workflow → service → repo for 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't logger.error and 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 Settings validators.
  • 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_index calls. 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 .env points 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-design skill.)
  • Icons are SVG. Do not add icon fonts.
  • All HTTP goes through the centralized client, via a module file in api/ — never fetch, axios, or raw ky from a component.
  • Layout lives in pages/, logic lives in components/ 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. watch is 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, then eslint-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 assert for runtime narrowing — use if x is None: raise ValueError(...) (bandit strips asserts under -O).
  • SQLModel: wrap column refs in col(); import func/case/or_/asc from sqlmodel when re-exported there, not from sqlalchemy.
  • 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 with instanceof 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, if guards override it. Avoid if/else branching and falsy or defaults.
  • 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 target dev. Never delete or force-push a protected branch.
  • Conventional commits (feat:, fix:, …), body wrapped at 72. A rejected commit leaves its files staged — check git show --stat before pushing.
  • No AI attribution: no agent Co-Authored-By or session trailer, no "Generated with" footer — in commits, PRs, or issues.
  • Lint + type-check must pass locally before pushing. A plain tsc pass is not sufficient for Vue projects — run vue-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 on dev and main.
  • Fetch before acting on remote state (rebase, force-push, "up to date" claims). After a push, check the PR head SHA matches git ls-remote before calling the PR ready.
  • Backend dependencies change via uv add / uv remove, never by hand-editing pyproject.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.