Skip to content
Skills Library
Programming · Learning & explanation

code-backend

/code-backend

[Orbit 2.4.6 Implementation] How to write backend code: layers, named steps, one error owner, logs without secrets, three test levels. Use when: «как писать сервис», «соглашения кода», «структура бэкенда», «логи без секретов»; backend conventions, service structure, logging.

Licence
MIT
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

[Orbit 2.4.6 Implementation] How to write backend code: layers, named steps, one error owner, logs without secrets, three test levels. Use when: «как писать сервис», «соглашения кода», «структура бэкенда», «логи без секретов»; backend conventions, service structure, logging.

Original author description

[Orbit 2.4.6 Implementation] How to write backend code: layers, named steps, one error owner, logs without secrets, three test levels. Use when: «как писать сервис», «соглашения кода», «структура бэкенда», «логи без секретов»; backend conventions, service structure, logging.

How it works

  1. When to use
  2. Inputs
  3. Procedure
  4. Output
  5. Check
  6. Pitfalls
  7. Portability
  8. What's improved vs the source
  9. Based on
Original SKILL.md headings · 152 lines, 1,318 words
SKILL.md preview
---
name: code-backend
description: '[Orbit 2.4.6 Implementation] How to write backend code: layers, named steps, one error owner, logs without secrets, three test levels. Use when: «как писать сервис», «соглашения кода», «структура бэкенда», «логи без секретов»; backend conventions, service structure, logging.'
---

# code-backend — how to write backend service code

> **Orbit · ② Build · step 2.4.6 Implementation**
> **Input:** service code ← `isolate-branch`
> **Output:** consistent code → next `build-screens`
> **Works with:** `shape-modules`, `review-code`
> **Shared rules:** reply in the user's language per `speak-plain`; generated content defaults to English; act within `stay-in-scope`; artifacts go to `.orbit/` (contract: `ARTIFACTS.md`).

Language-neutral conventions for service code. The repo's own rules win: `CONTRIBUTING.md`,
the linter, and the neighboring modules describe more than this skill can. This skill covers
what the repo does not describe — layers, named steps, error ownership, logging, config and
test levels — so a reader of the code can predict where a change goes.

## When to use

- Starting a service or a module whose structure is not yet decided.
- A new endpoint, job or adapter must fit an existing service without inventing a pattern.
- Reviewing code and the disagreement is about structure, not style.
- A log or error incident shows the conventions were never written down.
- Not when the repo already has explicit conventions in `CONTRIBUTING.md` or an
  architecture doc — read and follow those instead, and use this skill only for gaps.

## Inputs

- The service code and its neighbors: `ls <service>/`, `rg -n "func |def |class " <service>/src | head -40`.
- `CONTRIBUTING.md`, linter config, `Makefile`, `package.json` / `pyproject.toml` /
  `go.mod` — the actual scripts and rules.
- `.orbit/task/<id>/plan.md` — the task's files, check commands and scope.
- The module shape from `shape-modules`: interfaces, boundaries and ownership.
- Existing logs and error handling: `rg -n "logger\.|log\.|raise |throw " <service>/src | head`.
- Missing input: if there are no neighboring modules and no repo rules, ask before
  introducing a structure; a new structure needs consent.

## Procedure

1. **Read the neighbors before writing a line.** The existing module layout is the
   convention. Repeat its structure; propose a new one only with explicit consent, and
   record the decision in `.orbit/task/<id>/plan.md`.
2. **Place code by responsibility, not by file type:**
   - **Edge** (HTTP handler, queue consumer, CLI): parse and validate the **shape** of the
     input, map it to domain types, choose response codes. No business rules here.
   - **Core** (domain): business rules and validation of **meaning**; no framework, ORM or
     transport imports. This layer is testable without a server.
   - **Adapters** (DB, external API, queue): behind interfaces from `shape-modules`; the
     core depends on the interface, never on the client library.
   ```
   src/
     edge/http/orders_handler.ts      parse → map → call core → response code
     core/order/place_order.ts        named steps; pure business rules
     core/order/ports.ts              interfaces the core needs
     adapters/db/order_repository.ts  implements the port; SQL here
     adapters/payments/gateway.ts     timeout + bounded retry live here
   ```
3. **Keep domain types and transport DTOs separate.** The DTO at the edge may have string
   dates and nullable fields; the domain type is strict. A mapper converts between them, so
   a transport change never ripples into business rules.
4. **Write a business flow as a chain of named steps:**
   `ValidateOrder → ReserveStock → ChargePayment → PublishOrderCreated`. Each step is a
   function with an obvious input and output; the flow function reads top to bottom with no
   hidden branching. A step that fails returns a result, it does not throw across layers.
5. **Keep SQL in one place.** Either `.sql` files or one data-access layer — never string
   concatenation spread through handlers. Parameterized queries only.
6. **Give every error one owner.** Handle it where it can actually be handled; otherwise
   propagate with context. Expected business outcomes ("no free mailboxes") are returned
   results, not exceptions. Retries: one shared bounded helper at the integration edge, not
   a retry loop in each caller.
7. **Log events for the person on call at 3 am:** structured fields, `trace_id`, and a clear
   event name — `order.charge.failed reason=timeout attempt=3`. Levels: Error — a human
   must act; Warning — degradation; Info — business events; Debug — local only.
8. **Ban secrets and personal data from logs:** never tokens, passwords, URLs containing
   tokens, email bodies or personal data. Debug logs reach production whenever the level is
   not overridden, so the ban applies to Debug too.
9. **Treat configuration as validated input.** A constant becomes a setting only if it
   really differs between environments; validate all config at startup and fail fast with a
   clear message, never at first use.
10. **Test at three levels:** pure unit tests on core logic (most), unit tests with stubs on
    orchestration (fewer), a thin layer of integration tests on real infrastructure (a few,
    e.g. Testcontainers). Run lint and the suite before handing off; append the output to
    `.orbit/task/<id>/evidence.md`.

## Output

Consistent service code in the repo (edge / core / adapters / config / tests), plus the
evidence entry:

```markdown
## 2026-11-08 19:05 — orders module conventions
$ npm run lint → 0 errors
$ npm test -- orders → 28 passed (24 unit, 3 orchestration, 1 integration)
Structure: edge/http/orders_handler.ts → core/order/place_order.ts (named steps)
Logs: `order.charge.failed reason=timeout attempt=3` with trace_id; no token/email fields
Config: 3 new settings validated at startup; no env read outside config module
```

Next: `build-screens` for the UI that consumes the API; `review-code` checks the diff.

## Check

```bash
npm run lint                                  # or ruff, golangci-lint — exit 0
npm test -- <module>                          # or pytest -q, go test ./... — all green
rg -n "token|password|secret|Authorization" <service>/src --glob '*log*'   # must be empty
rg -n "SELECT .*\+|query\(.*\+" <service>/src | head                        # no string-built SQL
rg -n "trace_id|reason=|attempt=" <service>/src | head                      # structured events
rg -n "process\.env|os\.environ" <service>/src --glob '!**/config*'        # config read once
```

Pass rule: lint and tests pass; no secret or personal-data field appears on a log path; SQL
is parameterized and lives in one layer; every business flow is a named-step chain; config
is read and validated in one place; the three test levels are present and the evidence entry
records them. `review-code` reads the same diff and the same evidence.

## Pitfalls

- **Framework types leaking into the core.** A domain function importing an HTTP request or
  an ORM session cannot be tested without a server; keep the core transport-free.
- **Fat handlers.** Validation, business rules and persistence in one function: no test can
  isolate the rule. Edge parses, core decides, adapter saves.
- **`catch (e) {}` in every layer.** An error with three owners is handled nowhere;
  one owner, propagated with context elsewhere.
- **Retry loops sprinkled around.** Three different retry policies and one infinite loop;
  a single bounded helper at the integration edge.
- **Secrets and email bodies in logs.** The classic leak: a debug log of the request object
  contains the token; log the event and ids, not the payload.
- **Config read at call sites.** `process.env` scattered across the code fails late and
  differently per environment; read and validate once at startup.
- **Only integration tests.** Slow, flaky and unable to localize a failure; the majority
  belongs at the pure unit level.
- **Copying a structure from a blog.** If the neighbors use another shape, the new module
  becomes a foreign body; repeat the local convention.

## Portability

Language-neutral by design; the commands map to npm, pytest, go test, ruff, golangci-lint
and friends — use what the repo uses. No subagents or slash commands. The artifacts are the
code plus `.orbit/task/<id>/evidence.md`, so a review or another session can verify the
conventions without reading this skill.

## What's improved vs the source

- An explicit ban on secrets, tokens, token-bearing links and email bodies in logs, Debug
  included — a common real leak (found when testing the pack on a live service).
- Rule "neighboring code and repo rules beat this skill".
- Named-step flows, error ownership and retry locality are checkable rules, not style tips.
- Evidence records structure, log shape and config so `review-code` can verify the
  conventions instead of re-litigating them.

## Based on

- [backend-skills](https://github.com/si1verwind17/backend-skills) — method «backend-code-conventions» (MIT). Rewritten in our own words and improved — see "What's improved".

Versions

The database has no other skills named code-backend.

Database snapshot: 13.11.2026 · package version eedf78afbb1e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100backend-architecture-principles
    Language-agnostic backend architecture and code-quality rules. Use when designing services, structuring a backend codebase, writing business logic, handling errors, configuration, logging, background jobs, or reviewing backend code for maintainability.
  • 98backend-dev-guidelines
    Backend architecture principles, layering, error handling, logging patterns for NestJS. Use when designing NestJS modules, writing service logic, structuring error handling, or setting up structured logging.
  • 100local-awesome-code-standards-c28c96db
    Universal coding standards — naming, structure, immutability, error handling, type safety, backend layering, frontend architecture — that fill the gaps after the project's own conventions. Use when starting a module, refactoring to team conventions, setting up lint rules,…
  • 100backend
    Backend development patterns for services, error handling, logging, caching. Use when building backend services, APIs, or microservices.
  • 100backend-test
    Generate backend tests (unit, integration, mocks) for existing code. Auto-invoke when user says "write test for", "add test", "test this", or "create test".
  • 90backend-craft
    Backend engineering standards — API design, layering, database patterns, caching, error handling, auth, background jobs, logging, and the production-readiness checklist. Use when building any server-side code (endpoints, services, models, migrations, jobs).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.