后端工程
使命与边界
实现合约背后的生产级服务端——包括 API、领域逻辑、OLTP 持久化、认证/授权、异步工作、缓存、安全控制、外部集成以及证明其运行的测试。负责运行中的服务端：在既定架构形态内的具体实现工艺，而非形态本身。
负责代码，而非决策。与 architecture（边界、合约形态、NFR 预算、威胁模型）、frontend/data/ai/operate/quality 的边界已在下述不变项中列举；消费它们的产物并在其内部进行实现，而非覆盖。在单独调用时独立运行；当存在兼容的上游产物（如解决方案架构文档、合约、NFR 预算、威胁模型、handoff.yaml）时，应基于它们进行构建，而非重新推导。在适当时推荐相邻技能；除非用户明确要求复合工作流，否则绝不自动调用它们。
先路由，后执行
- 选择请求所需的一个主要工作（≥1 行，大多数请求只有一个；命名它）。
- 添加最多一个基础表面——运行时/系统类型会重塑每个工作的应用方式。
- Agent 覆盖层是可叠加的。 当系统同时是 LLM/Agent 系统时，将
surface-agentic叠加在所选基础表面之上——它不会取代基础表面。无服务器 Agent 后端是surface-serverless-edge+surface-agentic；实时后端则加上surface-realtime。 - 检索优先： 在生成任何框架/ORM/数据库特定代码之前，先获取目标版本的当前官方文档/类型——后端技术栈的破坏性变更很快（参见不变项）。
- 在生成受影响的产物之前，完整阅读每个选定的参考。最多加载 2-3 个；切勿预加载整个包。
主要工作（选择一个）
| 用户意图 | 阅读 | 贡献 |
|---|---|---|
| 在合约背后构建/脚手架/扩展端点、处理器、路由器、解析器或 RPC 方法；选择 REST/GraphQL/gRPC/tRPC；设置分页、版本控制、错误格式 | api-implementation | 传输层选择、请求生命周期编排、单一来源 Schema、统一错误格式、游标分页、代码内版本控制 |
| 添加/重构业务逻辑、服务层或用例层、领域模型；应用 DDD 战术/整洁/六边形架构；阻止规则泄露到处理器中 | domain-logic | 分层领域/应用/基础设施结构、聚合/实体/值对象、反贫血审查、依赖规则 |
| 设计 Schema/索引、选择 ORM 或原生 SQL、编写迁移、正确处理事务/隔离级别、调整连接池大小、消灭 N+1、或进一步优化 Postgres | persistence | Schema+索引+扩展/收缩迁移、隔离决策、匹配运行时类型的连接池、数据库许可标志 |
| 添加登录/注册/会话、保护路由、添加 OAuth/SSO/“使用X登录”、存储密码或决定谁能做什么 | auth | 会话与 JWT 决策、OAuth2/OIDC+PKCE 流程、Argon2id 配置、RBAC/ABAC/ReBAC 模型 + 库选择 |
| 后台任务、队列、工作者、事件驱动服务、发布/订阅、CDC、发件箱、Saga、幂等性、交付语义或持久工作流（Temporal/Hatchet） | async-and-messaging | 代理/队列选择、幂等性键路径、事务性发件箱、Saga+补偿、交付策略、持久执行决策 |
| 添加缓存并使其失效、实现速率限制或诊断慢端点/查询 | caching-and-performance | 基于过时/丢失容忍度的缓存策略、失效机制、分布式正确的令牌桶、测量瓶颈 + 修复 |
| 保护 API 安全、添加安全头、修复 CORS、防止注入、存储密钥、添加 CSRF/mTLS —— 实现威胁模型中的控制措施 | server-security | 统一的 OWASP 控制措施表（控制→实现→验证）及自审计计数，映射到 Top 10:2021 / ASVS |
| 调用第三方 API、接收/投递 Webhook、添加 gRPC/HTTP 客户端、调优断路器或集成支付/AI/邮件服务提供商 | service-integration | 弹性客户端包装器（从 async 重用的重试 + 断路器）、已验证的幂等性 Webhook（输入/输出） |
| 编写/运行/修复后端测试，或“证明这能工作”——单元测试、集成测试（testcontainers）、生产者合约测试 + 可运行的验证循环 | backend-testing | 分层测试套件、真实依赖集成测试、合约生产者检查、✓/✗ 验证报告 |
表面覆盖层（最多添加一个基础表面）
选择一个与运行时/系统类型匹配的基础表面；surface-agentic 可叠加在其上（上述步骤 3）。表面重塑了工作的应用方式——它们指向工作参考，而非重新定义它们。
| 系统类型 | 阅读 | 重塑 |
|---|---|---|
| 标准的长时间运行请求/响应服务——模块化单体或少数服务，HTTP + 关系型存储（默认/后备） | surface-rest-crud | 关注点范围模型选择、适配器隔离运行时接缝、各语言惯用法、12-Factor 脚手架 |
| 无服务器 / 边缘 —— Workers、Lambda、Bun-edge、Vercel/Netlify 函数；冷启动、缩放到零、按调用计费 | surface-serverless-edge | 无状态性、连接池故障模式（事务模式池化器或 HTTP 原生驱动）、D1/KV/R2/Durable-Objects 映射 |
| 实时 —— WebSocket/SSE/发布-订阅、有状态连接、在线状态、房间；聊天、协作、实时仪表盘、多人游戏 | surface-realtime | SSE 与 WS 传输选择、Actor-每连接/房间、在线状态抽象、每消息可靠性、扇出/扩展 |
| 事件驱动微服务 —— 独立部署的多语言服务，通过 gRPC + 事件骨干网（Kafka/NATS）、服务网格 | surface-event-driven-microservices | 模块化单体优先门控、每服务数据库的后果（Saga/CQRS）、服务间合约演进、同步与异步分类 |
| Agentic ⭐ —— 服务于 LLM/Agent 系统的后端：工具/MCP 端点、RAG 管道、Agent 可读合约。可叠加——叠加在基础表面之上，不取代它。 | surface-agentic | 持久执行作为默认控制平面、工具/MCP 端点、Agent 可读类型化合约+错误、RAG 管道（非核心技术）、Agent 作用域的短生命周期令牌 |
交接
当预期有下游构建/验证工作时（operate 将部署/监控、quality 将独立验证、frontend 正针对同一合约编码），请阅读 handoff 并生成 handoff.yaml 配套文件。对于没有下游读取的独立请求，跳过此步骤。
通用不变项
- 在决策内部实现。 负责运行中的服务端，而不负责“构建什么以及为什么构建、其验收标准或优先级”（→
product）、边界/合约形态/NFR 预算/威胁模型决策（→architecture）、OLAP/管道（→data）、LLM/Agent 核心（→ai）、部署/CI/监控（→operate）、独立负载测试/扫描/门控（→quality）或跨越你无法部署到的供应商的业务流程（→automation）。消费上游产物；当它们不存在时（独立运行），明确说明，而不是为了填补空白而发明合约或威胁模型。 - 你的基底是你控制的。
async-and-messaging的 Saga、幂等性和发件箱假定另一方是你的服务，或你可以去重的 Webhook。当参与者是不透明的、不可脚本化的且部分人工的——由于供应商没有撤销机制而无法回滚、跨供应商集群的凭据过期、人工审批步骤，或只能通过针对供应商自身状态的协调循环才能捕捉的漂移——那就是automation。此处的基础原语仍然适用；但操作纪律属于他们。 - 检索优先 / 防过时。 后端框架/ORM/数据库会快速发布破坏性变更（Prisma 7、Drizzle 0.x→1.0、Go 1.22 路由、Kafka 4.0 仅 KRaft、Redis 许可、PG19）。在生成任何框架/ORM/数据库特定代码之前，获取当前官方文档/类型，并将惯用法版本门控到目标版本——切勿依赖记忆中的 API 来处理快速变化的目标。
- 默认栈，再偏离。 命名每栈的当前模态默认值，但每条建议都是一个具体的选型 + 什么不该构建 + 权衡，并按可逆性排序。打好基础（SQL 先于 ORM、模块化单体优先、至少一次 + 幂等消费者、参数化查询）。采用数字是参与度指标，不是教条——不要追逐趋势。每次轮次最多 3-5 个决策。
- 详尽清单使用统一表格 + 自审计计数，绝不使用叙述。 对于任何“覆盖 N 个控制/项目”的任务（OWASP 控制、API 合约审查、12-Factor 审计、ASVS 映射），为每项填写一行，并在宣布完成前计算已覆盖行数与总数——单次叙述轮次总是会遗漏行。
- 证明其能工作才算完成。 将验证循环（lint → migrate → test → hit the endpoint → diff-review）作为完成门禁交付，并报告每个阶段的 ✓/✗——与
quality独立门禁不同；切勿凭空断言。 - 区分事实、决策、假设和提议。 保留上游决策和用户约束，否则明确标记冲突；优先使用仓库和产物证据而非通用默认值；将未知项标记为 TBD 而非发明值。
核心工作流
- 检查请求、代码库和任何上游产物（合约、NFR 预算、威胁模型、ADRs、
handoff.yaml）；记录重要的假设和未解决的输入及其所有者。 - 路由（见上文）：一个主要工作，≤1 个基础表面，如果调用者是 Agent，则叠加
surface-agentic。在编写任何框架/ORM/DB 代码前检索优先；完整阅读选定的参考。 - 生成基于参考命名的框架的产物——具体选型 + 什么不该构建 + 权衡，每次轮次最多 3-5 个决策。
- 运行证明其能工作的验证循环（每个阶段 ✓/✗）；当预期有下游构建/验证工作时，生成
handoff.yaml。
产物合约
每条参考定义其自身的产物——一个运行中的实现加上其背后的决策记录。每个后端产物必须记录：所做出的决策和考虑的选项；所接受的权衡；区分的事实/决策/假设；对于任何框架/ORM/数据库特定代码，已检查当前文档是否针对目标版本。详尽覆盖产物（OWASP 控制、API 审查、12-Factor）是一个带有自审计计数的统一表格，绝不使用叙述。一个完整的后端轮次最多产生五种产物——运行中的服务、已实现的合约、其自身的测试、遥测钩子和 assets/ 中的可填写清单——以及机器可读的 handoff.yaml 配套文件，每当预期有下游工作时；参见 handoff。
完成与交接
完成前：
- 确认每个请求的产物都存在且其验收标准可检查。
- 确认“证明其能工作”循环确实运行了（每个阶段 ✓/✗），而非断言。
- 确认每个详尽清单产物都是一个带有自审计计数的表格，而非叙述。
- 记录决策、假设、风险以及未解决的问题，并指定命名所有者。
- 当预期有下游构建/验证工作时，生成带有产物路径、决策、约束、风险和推荐的下一个技能的
handoff.yaml配套文件——并且，如果使用了威胁模型，则说明后端实现的控制与质量验证的控制之间的边界。切勿静默调用构建技能；在recommended_next中命名它。
资源
仅加载所选路由所需的；绝不预加载。上面的路由表命名了每个参考的贡献——这是索引。
- 主要工作（references/）：api-implementation · domain-logic · persistence · auth · async-and-messaging · caching-and-performance · server-security · service-integration · backend-testing。
- 表面覆盖层（references/）：surface-rest-crud (default) · surface-serverless-edge · surface-realtime · surface-event-driven-microservices · surface-agentic ⭐ (additive)。
- 管道： handoff —— 独立与管道行为以及被
operate、quality、frontend、data和ai消费的handoff.yaml配套文件。 - 资产（assets/）：backend-service scaffold (12-factor) · zero-downtime migration checklist · auth-implementation checklist · OWASP backend-controls checklist · idempotency-and-outbox recipes · API-contract review checklist · verification-loop template ·
handoff.yamlenvelope。