backend-development

Backend Development

Overview

本 Skill 是 1flowbase 后端实现期的边界守门员，不负责替代需求对齐或 QA 验收。进入这里时，默认已经有清晰目标、范围、成功标准和用户拍板点；本 Skill 只负责把已确认的 backend / API / Rust 任务按项目规则落到 api/。

Entry Contract

• 需求仍有数据、contract、migration、权限、状态归属、架构方向或跨模块职责选择时，先回 problem-framing。
• 涉及可测试行为变化时，先联动 test-driven-development；不能走 TDD 时，交付说明必须写明替代验证。
• 用户要求自检、验收、回归、质量报告或证据结论时，切到 qa-evaluation。
• 后端 API / 状态入口缺少已确认的接口预期、验收证据或测试设计时，不在实现期补需求；回到 problem-framing / test-driven-development。
• 进入 api/ 前先读 api/AGENTS.md；存在更近的 AGENTS.md 时按最近规则执行。

When to Use

• 设计已确认后的接口、动作入口、模块边界、route / service / repository / adapter 实现。
• 调整状态流转、关键领域对象、写路径、事务边界或一致性规则。
• 实现 Rust / Axum API、storage adapter、migration、mapper、worker、runtime 后端逻辑。
• 收口多个模块直接改同一关键状态的问题。
• 处理 HostExtension / RuntimeExtension / CapabilityPlugin / Resource Action Kernel 的后端实现边界。

不要用于

• 纯视觉、交互、信息架构设计。
• 纯需求澄清、方案选择、issue shaping 或 ADR。
• 纯 QA 报告、回归结论或质量门禁路由。

Core Invariants

• 稳定核心决定“该不该做”；边界适配层负责“怎么做到”；关键状态只能从清晰唯一入口改变。
• 核心业务规则不得直接依赖外部协议格式、存储细节、provider stdout / stderr 或临时 UI 形态。
• 能力边界优先使用能力名，具体实现留在 adapter / repository / driver。
• API 输入保持短、平、单动作；新接口、service、repository 方法必须命名具体。
• 状态集合、流转规则、动作约束、幂等语义和错误边界必须显式。
• Rust 实现要用类型表达核心不变量、显式传播错误、封装状态转换，并把阻塞 IO、锁、事务和外部副作用放在清晰边界内。
• 系统内置数据模型、运行时读模型或 model_definitions / model_fields / scope_data_model_grants 改动必须区分 system-owned contract 与 user-owned metadata；不可用 migration / reconcile 覆盖用户或管理员 metadata。
• 后台注册设置项是后端拥有的安全对象，不是前端页面权限；稳定 feature_id 同时拥有 console surface 与 Settings API scope，角色只授权 feature_id，不再展开一组可编辑 action grant。
• Settings API 在 Core 启动或 HostExtension 加载时绑定到唯一注册项；请求只校验绑定后的 feature_id 与领域数据约束，不按页面 URL 推断权限，也不在请求期扫描或动态拼装 action 集合。
• 未注册、重复归属或引用 inactive feature 的 Settings API 必须 fail closed；不得保留 allow-by-default、前端兜底或管理员可编辑的 route-to-permission 表。
• 新抽象、公共接口、bool/flag 参数、helper/manager/utils、pass-through service 或重复 defensive check，先读 ../_shared/design-rules.md；命中则回到 problem-framing 做更小 redesign。

Implementation Routing

• AI-friendly API rules: references/api-design.md。
• State and consistency review: references/state-and-consistency.md。
• Stable core vs adapter rules: references/boundary-design.md。
• Local implementation rules: references/implementation-rules.md。
• Rust backend practice rules: references/rust-backend-practices.md。
• Builtin data model contract / metadata overlay rules: references/builtin-data-model-contract.md，命中系统内置表、runtime read models、数据建模定义 metadata、字段描述、scope grant 或 API exposure 时读取。
• Console settings registration: references/console-settings-registration.md，命中后台设置注册、Settings API、角色设置授权、HostExtension console surface 或对应 CLI / inventory 时读取。
• Anti-decay patterns: references/anti-patterns.md。
• Pressure scenarios: references/examples.md。
• Agent Flow runtime node payload contract: references/agentflow-runtime-node-payload.md，仅在调整运行日志、debug artifact、节点输入/数据处理/输出接口时读取。