103 lines
5.3 KiB
Markdown
103 lines
5.3 KiB
Markdown
# Skills & Roles (backend)
|
|
|
|
Backend-scoped copy of the root `SKILLS.md` — same five roles, applied to
|
|
`backend/` surfaces (Next.js API gateway, OCR pipeline, Postgres, Docker/deploy)
|
|
during `n`/`next` execution (see `AGENTS.md` Part B, this dir). One agent can play
|
|
all of them in sequence; a multi-agent harness may spawn each as a separate
|
|
subagent for a fresh-context pass. Order matters: Architect → Backend/Frontend →
|
|
QA → Hardware/Compatibility.
|
|
|
|
## 1. Software Architect
|
|
|
|
**Responsibilities**
|
|
- Decide where new backend code lives; keep module boundaries clean (API routes vs.
|
|
`utils/` business logic vs. `db/` layer vs. the Python pipeline in `config/`).
|
|
- Prefer deep modules (few, well-bounded files with simple interfaces) over shallow
|
|
ones — this is what keeps the codebase navigable for an agent.
|
|
- Own the 256-LOC split rule (`AGENTS.md` Part B §B3): when a file crosses the
|
|
threshold, decide the split boundary before anyone patches around it.
|
|
- Keep `plans/next-enhancements.md` (this dir) structured by real backend module
|
|
boundaries, not arbitrary groupings.
|
|
- Owns the existing-project audit (`AGENTS.md` Part B §B0) for backend specifically.
|
|
|
|
**When invoked**: start of every `e`/`enhance` run; start of every `n`/`next` task,
|
|
before implementation begins.
|
|
|
|
**Handoff**: hands the Backend/Frontend roles a target file layout and interface
|
|
contract, not just a task description.
|
|
|
|
## 2. Backend Engineer
|
|
|
|
**Responsibilities**
|
|
- Implement Next.js API route logic, DB access (`src/db/`), and the Python OCR
|
|
pipeline (`config/classify_ocr_server.py`, pipeline API) as the task requires.
|
|
- Wire the mock-vs-live routing required by the Demo/Live switch (`AGENTS.md` Part B
|
|
§B5) and the Cloud/Local endpoint switch (§B6) if/when built — both must resolve
|
|
through the same contract so swapping either setting never changes calling code.
|
|
- Keep business logic out of route handlers (`src/app/api/**/route.ts`); route
|
|
handlers stay thin, matching the existing `utils/parser.ts`-style separation.
|
|
- Use `withTransaction` (`src/db/index.ts`) for any multi-statement write that must
|
|
be atomic — see task 7.1 in the pre-kit history for why this matters here.
|
|
|
|
**When invoked**: any task touching API routes, the DB layer, or the OCR pipeline.
|
|
|
|
**Handoff**: gives Frontend a stable contract (types/response shape) to build
|
|
against; gives QA the list of new/changed endpoints and their expected error modes.
|
|
|
|
## 3. Frontend Engineer
|
|
|
|
**Responsibilities**
|
|
- Implement UI for the task inside `pfm-web-app/src/app/`, including Demo/Live and
|
|
Cloud/Local switcher controls where relevant.
|
|
- Follow this repo's existing page pattern: consolidated single-page flows (root
|
|
`page.tsx`) vs. standalone-purpose route folders (`manual-label/page.tsx`,
|
|
`scan-pfm/page.tsx`) — see backend `CLAUDE.md` for which pattern a given feature
|
|
should follow.
|
|
- Consume the Backend Engineer's contract rather than reaching around it.
|
|
- Keep components small and composable, respecting the 256-LOC rule.
|
|
|
|
**When invoked**: any task with a user-facing surface inside `pfm-web-app/`.
|
|
|
|
**Handoff**: gives QA the golden-path user flow and the edge cases it's aware of.
|
|
|
|
## 4. QA / Test Engineer
|
|
|
|
**Responsibilities**
|
|
- During clarification (`AGENTS.md` Part B §B2a), turn resolved answers into
|
|
concrete acceptance criteria — what "done" verifiably means.
|
|
- Write/extend automated tests (`parser.test.ts` pattern) for the change.
|
|
- For anything touching `parser.ts` or the OCR pipeline, run the accuracy
|
|
regression harness (`node pfm-web-app/scripts/accuracy-check.mts` or `accuracy-check-scan.mts`) and check for
|
|
regressions against the current baseline (see `sources/accuracy_history.jsonl` and `sources/product_accuracy_history.jsonl` for latest metrics), not just "it compiles."
|
|
- Run the **verify build integrity** pass: golden path + edge cases + regression
|
|
check on adjacent features.
|
|
- Reject work back to the relevant role if acceptance criteria aren't met — don't
|
|
patch around a failing check.
|
|
|
|
**When invoked**: acceptance-criteria drafting during §B2a; final verification pass
|
|
before a task is marked `[DONE]`.
|
|
|
|
**Handoff**: reports pass/fail with specifics (what broke, under what input) back to
|
|
whichever role owns that surface.
|
|
|
|
## 5. Hardware & Performance Compatibility Reviewer
|
|
|
|
**Responsibilities**
|
|
- Check the change against this stack's real constraints: single vs. dual-GPU dev
|
|
mode (`docker-compose.yml` runs `npm run dev`, a known throughput ceiling), VRAM
|
|
budget for vLLM (`gpu-memory-utilization` in `config/vllm_config.yaml`), and
|
|
behavior under the Local/on-prem deployment mode from `AGENTS.md` Part B §B6.
|
|
- Flag newly introduced heavy Python/Node dependencies, GPU-specific assumptions, or
|
|
anything that would break the isolated vLLM-server-only environment (no
|
|
`paddlepaddle-gpu` in this venv — see `AGENTS.md` Part A / `docs/vllm-service.md`).
|
|
- Flag anything that would degrade badly on lower-spec hardware or slower networks
|
|
(e.g. the mobile app's 2s polling loop against a slow backend response), and
|
|
suggest a lighter-weight alternative when one exists.
|
|
|
|
**When invoked**: final verification pass, alongside QA, before a task is marked
|
|
`[DONE]`; also whenever a task adds a new dependency or changes the deployment/
|
|
runtime surface.
|
|
|
|
**Handoff**: blocks `[DONE]` status until concerns are resolved or explicitly
|
|
accepted as a documented trade-off in `docs/feature-list.md` (this dir).
|