oma-backend Skill
实现服务端 API、身份认证和应用数据访问。模式建模和查询调优请使用 oma-db。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
Backend Agent - API & Server Specialist
Scheduling
Goal
Implement or review backend APIs, authentication, database integration, server-side business logic, and migrations using the project's existing backend stack and clean architecture boundaries.
Intent signature
- User asks for API, endpoint, REST, GraphQL, auth, server, migration, repository, service, router, or background job work.
- User needs backend code that coordinates validation, business logic, persistence, transactions, and backing services.
When to use
- Building REST APIs or GraphQL endpoints
- Data access code and migrations that an API change needs
- Authentication and authorization
- Server-side business logic
- Background jobs and queues
When NOT to use
- Frontend UI -> use Frontend Agent
- Mobile-specific code -> use Mobile Agent
- Schema modeling, index design, and query tuning -> use
oma-db
Expected inputs
- Target feature, endpoint, migration, auth flow, or server behavior
- Existing backend stack files such as manifests, routes, services, models, and database config
- API contracts, schemas, validation rules, and persistence requirements
- Required verification commands or project conventions
Expected outputs
- Backend code changes in router, service, repository, model, migration, or test files
- Validated inputs, safe queries, transaction boundaries, and error handling
- Verification status: which checks ran, and what was not verified
Dependencies
- Project stack manifests and existing backend conventions
resources/execution-protocol.md,resources/checklist.md, andresources/orm-reference.md
- Optional stack reference (
stack/, or the matchingvariants//):stack.yaml,tech-stack.md, snippets, and API templates
- Database, queue, cache, mail, auth, or external API resources configured through environment or secret managers
Control-flow features
- Branches by detected stack, ORM/query pattern, auth requirement, migration impact, and transaction scope
- Reads and writes codebase files
- May touch local database migrations or generated code
- Must not hardcode secrets or share unsafe ORM lifecycle objects across concurrent work
Structural Flow
Entry
- Detect the backend stack from project files first.
- Identify affected router, service, repository, model, migration, and test boundaries.
- Load stack-specific references only when needed.
Scenes
- PREPARE: Determine stack, architecture boundaries, and acceptance criteria.
- ACQUIRE: Read existing routes, services, repositories, models, schemas, and config.
- ACT: Implement backend changes with validation, business logic, persistence, and tests.
- VERIFY: Select the relevant lint, type, test, and migration checks and review the applicable checklist items. Run a check only when the user or the active workflow requires it; otherwise report what was not verified.
- FINALIZE: Report changed behavior, verification, and unresolved risks.
Transitions
- If stack files exist, follow them before generic guidance.
- If ORM performance, relationship loading, transactions, or N+1 risk appears, use
resources/orm-reference.md. - If database schema impact is primary and API work is secondary, coordinate with
oma-db. - If auth server setup touches DB adapters or server libraries, keep it in backend scope.
Failure and recovery
- If stack cannot be determined, ask the user or suggest running
/stack-set. - If a required check fails, fix the root cause before handoff.
- If required secrets or services are unavailable, document the blocker and keep code configurable.
Exit
- Success: backend change is implemented, covered by tests, and aligned with local architecture.
- Partial success: blocker, missing dependency, or verification gap is explicit.
Logical Operations
Actions
| Action | SSL primitive | Evidence |
|--------|---------------|----------|
| Detect stack and conventions | READ | Manifests, stack files, existing code |
| Select implementation boundary | SELECT | Router/service/repository pattern |
| Validate inputs and schemas | VALIDATE | Stack validation library |
| Implement business logic | WRITE | Service layer code |
| Implement persistence | WRITE | Repository/model/migration code |
| Call external/backing services | CALL_TOOL | DB, queue, cache, auth, or API clients |
| Run required checks | CALL_TOOL | Checks the user or active workflow requires |
| Report result | NOTIFY | Final summary |
Tools and instruments
- Project language/framework toolchain
- ORM or database client
- Test, lint, typecheck, and migration commands
- Stack-specific templates and snippets when present
Canonical workflow path
Use the configured code-intelligence provider to locate files and inspect symbols
or content. For Serena, use find_file, search_for_pattern,
get_symbols_overview, and find_symbol. Native search is limited to the
provider exclusions and non-code paths permitted by the project's search policy.
Then select the project's verification commands (lint, typecheck, tests, and migrations when schema changes are involved), preferring the verify: commands in stack/stack.yaml when present. Run them only when the user or the active workflow requires it; otherwise report what was not verified.
Resource scope
| Scope | Resource target |
|-------|-----------------|
| CODEBASE | Backend source, tests, schemas, migrations |
| LOCAL_FS | Stack references and generated artifacts |
| PROCESS | Required test, lint, typecheck, and migration commands |
| CREDENTIALS | Environment-managed DB URLs, API keys, secrets |
| NETWORK | External APIs or backing services when required |
Preconditions
- Target behavior and affected backend boundary are identifiable.
- Project stack and verification commands can be inferred or are provided.
- Required credentials remain outside source code.
Effects and side effects
- Mutates backend source files, tests, and possibly migrations.
- May change database schema, API behavior, auth behavior, or service contracts.
- May require generated clients or migration artifacts.
Guardrails
Apply framework, library, architecture, and data-model defaults only when the target project has no established choice. Scoped edits do not authorize a stack migration or unrelated infrastructure.
Architecture Pattern
Router (HTTP) → Service (Business Logic) → Repository (Data Access) → Models
- Router: receives HTTP requests, validates input, calls the Service (injected through the framework's DI), and returns the response
- Service: owns business decisions, Repository composition, and external API calls
- Repository: encapsulates DB CRUD and query logic and returns ORM entities
Core Rules
- Clean architecture: router → service → repository → models
- No business logic in route handlers
- All inputs validated with your stack's validation library
- Parameterized queries only (never string interpolation)
- JWT + Argon2id for auth (bcrypt acceptable for legacy compatibility); rate limit auth endpoints
- Async where supported; type annotations on all signatures
- Custom exceptions via centralized error module (not raw HTTP exceptions)
- Explicit ORM loading strategy: do not rely on default relation loading when query shape matters
- Explicit transaction boundaries: group one business operation into one request/service-scoped unit of work
- Safe ORM lifecycle: do not share mutable ORM session/entity manager/client objects across concurrent work unless the ORM explicitly supports it
- Config from the environment; a fallback is declared, never implied: DB URLs, API keys, secrets, and feature flags come from environment variables or a secret manager, never from source. A missing credential fails with a clear error by default. A deterministic local fallback is written only when the integration is declared key-optional (a key provisioned later, a demo from a clean checkout) or a test/demo mode is explicitly selected: keep the real call and the fallback as separate env-conditional branches, mark the fallback
// TODO(oma-deferred): integrate when key is provisioned, and label its output as simulated. A simulated payment, authentication, mail, or other effect is never reported as a completed real operation, and shipping only the fallback leaves the spec unmet. - Stateless services: no in-memory session or user state between requests; use external stores (DB, Redis, cache) for shared state
- Backing services as resources: DB, queue, cache, mail are swappable attached resources connected via config; Repository layer must not assume a specific instance
Stack Detection
- Project files first: Read existing code, package manifests (pyproject.toml, package.json, Cargo.toml, go.mod, pom.xml, etc.) to determine the tech stack
- Stack reference second: Use
stack/when present; otherwise the matchingvariants//. An installed project with a chosen preset hasstack/and novariants/; the plugin and source layouts havevariants/and nostack/. Treat it as supplementary reference for coding conventions and snippet templates - Neither applies: Ask the user or suggest running
/stack-set
Stack-Specific Reference
File names are relative to the stack reference directory selected above.
- Stack manifest (SSOT):
stack.yaml: structured declaration (language,framework,orm) and theverify:contract.oma verify agent backendruns theverify:block ofstack/stack.yaml. The manifest's JSON Schema isvariants/stack.schema.jsonin the plugin and source layouts; an installed project does not carry it. - Tech stack narrative:
tech-stack.md: human-readable reference only;stack.yamlwins on conflict. - Code snippets (copy-paste ready):
snippets.md - API template:
api-template.*
References
- Local code tools:
../_shared/core/code-intelligence.md(code search/navigation)
- Execution steps (follow for the selected task):
resources/execution-protocol.md - Checklist (check the applicable items before handoff):
resources/checklist.md - ORM reference:
resources/orm-reference.md - Error recovery:
resources/error-playbook.md - Context loading:
../_shared/core/context-loading.md - Clarification:
../_shared/core/clarification-protocol.md - Context budget:
../_shared/core/context-budget.md - Lessons learned:
../_shared/core/lessons-learned.md(matching prior failure or requested retrospective) - Observability handoff:
../oma-observability/SKILL.md§Integrations — propagators/baggage, span conventions, log correlation, PII redaction