be-framework-coding-standard

Files (13)

• SKILL.md
• openai.yaml · agents/
• dotnet-core-csharp.md · references/
• golang-echo.md · references/
• golang-fiber.md · references/
• golang-gin.md · references/
• golang-kratos.md · references/
• java-core.md · references/
• java-spring-boot.md · references/
• pure-golang.md · references/
• python-fastapi.md · references/
• typescript-express.md · references/
• typescript-nestjs.md · references/

SKILL.md (first lines)

# BE Framework Coding Standard

## When to use

You are BE Dev implementing or reviewing backend code after the backend track and stack are declared in the signed-off SRS. This skill standardizes backend implementation without turning a feature task into a framework migration.

## Inputs and outputs

- **Inputs:** task assignment, `docs/SRS.md` headers `Backend-Track:` and `Backend-Framework:`, SRS §3.4.4 API Contract Format, SRS §3.4.5 Source Layout, SRS §3.4.6 Environment Configuration, task US / FR / NFR IDs, architecture, data-contract constraints, external-integration specs, current backend source tree, manifests, and installed framework versions.
- **Outputs:** backend code under the declared backend source root, framework-native handlers/controllers/services/repositories/workers, API contracts when endpoints/messages change, validation/error/observability behavior aligned to SRS/architecture, and focused unit/integration/contract tests.

## Backend track selection

`Backend-Track:` declares the service role:

| Value | Meaning |
|---|---|
| `backend-web` | Web-facing backend: public/internal HTTP API, BFF, web gateway, session-backed web API, or API directly serving frontend clients. |
| `backend-service` | Microservice/runtime service: domain service, worker, consumer, scheduler, service-mesh API, gRPC service, event processor, or internal integration service. |
| `multiple` | More than one backend row exists; select per §3.4.5 Source Layout / architecture container. |
| `N/A` | No backend implementation applies. |

## Framework selection

1. Read `docs/SRS.md` before inspecting manifests. Headers `Backend-Track:` and `Backend-Framework:` are authoritative.
2. If `Backend-Framework:` is one supported value, select that framework reference.
3. If `Backend-Framework:` is `multiple`, select the framework from the §3.4.5 backend row that owns the task's service/container/path. If no row matches or several rows match, halt with `NEEDS_CONTEXT` and cite the candidate rows.
4. If `Backend-Track:` is `multiple`, select the track from the same §3.4.5 backend row. If one framework spans both tracks, the track still controls lifecycle expectations.
5. If either header is `N/A`, do not perform BE implementation; report that no backend applies.
6. If either header is missing, `TBD`, unsupported, or inconsistent with §3.4.5, halt and return the work to BA:
   - greenfield/authored SRS: BA Phase 1.X must ask the user to choose;
   - brownfield/extracted SRS: BA Mode E must detect from source evidence and write the SRS fields.
7. After selecting the reference, inspect manifests/source only as a consistency check. If code evidence contradicts the SRS-selected track/framework, halt and raise an open issue; do not silently switch references.

Read the matching reference before editing:

| Framework | Reference |
|---|---|
| TypeScript with Express | [`references/typescript-express.md`](./references/typescript-express.md) |
| TypeScript with NestJS | [`references/typescript-nestjs.md`](./references/typescript-nestjs.md) |
| Python with FastAPI | [`references/python-fastapi.md`](./references/python-fastapi.md) |
| Java with Spring Boot | [`references/java-spring-boot.md`](./references/java-spring-boot.md) |
| .NET Core C# | [`references/dotnet-core-csharp.md`](./references/dotnet-core-csharp.md) |
| Pure Golang | [`references/pure-golang.md`](./references/pure-golang.md) |
| Java Core | [`references/java-core.md`](./references/java-core.md) |
| Golang with Gin | [`references/golang-gin.md`](./references/golang-gin.md) |
| Golang with Fiber | [`references/golang-fiber.md`](./references/golang-fiber.md) |
| Golang with Echo | [`references/golang-echo.md`](./references/golang-echo.md) |
| Golang with Kratos | [`references/golang-kratos.md`](./references/golang-kratos.md) |

## Universal implementation procedure

1. Inspect nearby backend code before editing. Preserve established folders, naming, dependency injection, persistence abstraction, error envelope, logging, metrics, config, test style, formatter, and lint rules.
2. Read SRS §3.4.6 Environment Configuration before touching database URLs, downstream service endpoints, queue topics, feature flags, credentials, regions, retry/timeout settings, or runtime config paths. Use the declared backend/service-owned key names and existing project config loader; if the task needs a new runtime key, halt and raise an OQ instead of inventing it in code.
3. Map every changed endpoint, worker, job, or service operation to the task's SRS IDs and FR contract. If the FR/schema/error model is incomplete, halt and raise an OQ; do not invent a contract in code.
4. Keep boundaries explicit:
   - transport layer owns request/message parsing, auth context extraction, response/message shape, and status codes;
   - application/service layer owns use-case orchestration and transaction boundaries;
   - domain layer owns invariants and state transitions;
   - repository/infrastructure layer owns persistence, external clients, queues, and adapters.
5. Validate inputs at the boundary and map validation failures to the declared project error envelope. Never let framework-default validation errors leak if the API contract declares a different shape.
6. Preserve security controls: authentication, authorization, tenant isolation, CSRF/session policy for web backends, mTLS/service auth for service backends, PII masking, and secret handling.
7. Respect architecture §6 data contracts. Run named format conversions at boundaries and avoid writing gate fields unless the task owns the write condition.
8. Make failure behavior deliberate: classify deterministic vs transient errors, use retries only for transient failures, preserve idempotency keys, and route poison messages / DLQ paths as architecture declares.
9. Keep observability consistent: structured logs with correlation/request IDs, metrics for success/failure/latency, traces/spans where the project uses them, and no sensitive data in logs. For any new or changed backend operation, consult [`../backend-logging-traceability/SKILL.md`](../backend-logging-traceability/SKILL.md) and satisfy its ready-for-deploy checklist before signaling completion.
10. Update API contracts under `docs/api-contracts/` when endpoints/messages change, using SRS §3.4.4's declared format. Freeze only when stable.
11. Test at the right layer: unit tests for domain/application logic, framework handler/controller tests for transport mapping, integration tests for DB/queue/external adapter behavior, and contract tests for public API/message changes.
12. When the E2E harness mutates persistence directly, provide a deterministic test-only full-state reset:
    - gate it behind the project's existing test-endpoint/test-environment flag and make it unavailable elsewhere;
    - synchronously reset caches, worker/backfill/poller checkpoints, queues, fake clocks, and other process-global
      state affected by those writes;
    - prefer an aggregate reset endpoint backed by registered resetters, with non-2xx on partial failure;
    - add an integration test that warms an affected cache, directly changes its backing data, invokes reset, and
      verifies the next API read returns the changed data rather than the cached response;
    - keep production invalidation behavior unchanged—this endpoint compensates only for fixtures bypassing normal
      application writes/events.
13. Run format, lint, typecheck/compile, unit tests, and relevant integration/contract tests. If a command cannot run locally, document the blocker and the narrower checks you did run.

## Track-specific rules

### backend-web

- Treat user-facing latency, session behavior, CORS/CSRF, auth redirects, request size limits, pagination, and API error ergonomics as first-class.
- Keep BFF logic thin. It may compose downstream services for frontend needs, but domain ownership stays with the owning service.
- Do not expose internal model fields just because the ORM/DTO contains them.

### backend-service

- Treat service ownership, idempotency, message compatibility, backpressure, retries, health checks, and deploy/runtime isolation as first-class.
- Keep APIs/events backward-compatible unless the SRS/architecture declares a versioned breaking change.
- Avoid shared-database writes across service boundaries unless architecture explicitly allows them.

## Hard rules

- Do not introduce a new backend framework, ORM, validation library, message framework, or test runner unless an ADR or architecture task explicitly approves it.
- Do not choose a framework from package files when `docs/SRS.md` declares a different `Backend-Framework:`. Treat that as SRS/code drift and halt.
- Do not start BE implementation while `Backend-Track:` or `Backend-Framework:` is missing, `TBD`, unsupported, or `multiple` without a matching §3.4.5 row.
- Do not rewrite established project structure to match a reference file. The reference guides decisions inside the existing architecture.
- Do not hardcode API URLs, downstream endpoints, secrets, credentials, tenant IDs, region rules, retry counts, or timeout values outside the project config mechanism. Runtime values must come from the SRS §3.4.6 config keys through the project config loader.
- Do not swallow errors or map all failures to generic 500s when the FR error model declares specific cases.
- Do not bypass type errors, compiler errors, lints, analyzer failures, or tests with broad suppressions.
- Do not expose test reset endpoints when the test-endpoint flag is disabled, and do not implement reset as an
  asynchronous "eventually flushed" poller path.

## References

- [`references/typescript-express.md`](./references/typescript-express.md)
- [`references/typescript-nestjs.md`](./references/typescript-nestjs.md)
- [`references/python-fastapi.md`](./references/python-fastapi.md)
- [`references/java-spring-boot.md`](./references/java-spring-boot.md)
- [`references/dotnet-core-csharp.md`](./references/dotnet-core-csharp.md)
- [`references/pure-golang.md`](./references/pure-golang.md)
- [`references/java-core.md`](./references/java-core.md)
- [`references/golang-gin.md`](./references/golang-gin.md)
- [`references/golang-fiber.md`](./references/golang-fiber.md)
- [`references/golang-echo.md`](./references/golang-echo.md)
- [`references/golang-kratos.md`](./references/golang-kratos.md)
- [`../api-contract-author/SKILL.md`](../api-contract-author/SKILL.md) - API contract authoring and freezing.
- [`../backend-logging-traceability/SKILL.md`](../backend-logging-traceability/SKILL.md) - operator-grade debug/info/warn/error logging and traceability coverage for BE Dev.

From evolplus/talos, Apache-2.0.

More from evolplus/talos