用途:在 HLD 获批后的设计阶段,为某个功能编写后端低层设计(LLD)。它是设计产物而非代码,禁止编辑应用代码;强调准确优先于广度,每条依赖的约束都要用 file:line 引用,不得猜测。不负责实现,也不设计前端;跨仓库契约不在此编写,本技能只描述自身技术栈将暴露的 API/事件,之后由 /api-contract 把两份 LLD 合并为正式 OpenAPI 契约。
输入:feature、feature_slug、approved hld_path。产物路径由技能自行从 skills.config.yaml → artifacts.lld 解析,{slug} = feature_slug,即 .maestro/<slug>/lld/backend.md,调用方不传路径。
主要步骤:只读地在代码中定位该功能涉及的服务,阅读路由/控制器→服务/领域→持久化等关键层,以及数据模型与迁移工具、现有端点/事件、DTO、错误封装、认证/角色、任务/队列、外部集成、限流/幂等模式、日志/指标、测试/夹具与主流约定,仅记录约束设计的内容并附 file:line 证据;进行组件与序列设计(模块职责、关键路径的正常与主要错误调用序列、新代码插入位置);给出数据模型与迁移计划(实体、关系、索引,expand→migrate→contract 及回滚与回填);列出要暴露的 API/事件(方法/路径或事件/主题、请求响应 DTO、状态码、错误封装、认证与逐操作权限、逐字段校验、分页与上限、限流 429 与 retry-after、幂等键、并发/版本、向后兼容);做威胁建模与可观测性、超时/重试/降级、性能设计;编写测试计划(单元+集成,含契约负路径);写 LLD 并用平实语言标注所有破坏性变更;最后一次性写出 .maestro/<slug>/backend/tasks.json 任务 DAG。
LLD 必须覆盖:上下文与约束(引用代码)、组件/序列设计、数据模型与迁移计划、暴露的 API/事件、错误处理、安全与隐私(授权、租户、PII、密钥处理)、可观测性、性能、可靠性(超时、重试、幂等、部分失败)、测试计划、发布/回退。
必须定义的边界情况:空/缺失/null 输入;最大与超大载荷;重复提交;同一实体并发更新与丢失更新防护;跨服务部分失败、重试与幂等、超时及回退;分页边界(首/末/空页、排序不稳定);授权拒绝、令牌过期、权限不足、跨租户访问;限流耗尽、下游依赖宕机或缓慢;迁移中途失败、大数据集回填、回滚安全;单仓与多仓、生成代码、vendored/遗留区域、无测试区域。
外部技能:读取 skills.config.yaml → lld.external.research(技能名如 deep-research 或 none);若设置则用于研究不熟悉的库、协议或合规,须返回可引用的有来源结论;若为 none 则仅依据代码与 HLD 设计。
tasks.json:须符合 workflows/tasks.schema.json,是后端实现阶段并行展开的计划,基于刚写的 LLD 并复用已读文件,不重读代码库。一次性在内存中组装完整结构后单次 Write 写出,不要用连续 Edit 逐步增长;随后运行 python3 workflows/validate_tasks.py .maestro/<slug>/backend/tasks.json,须打印 OK,失败则做一次修正 Edit 或单次重写 Write 并重新校验。字段包括 context_manifest.read_once(任务要编辑的代码文件)、reference(本 LLD 路径、待定契约路径、CLAUDE.md/AGENTS.md);每个 ≤1 提交的切片一个 tasks[] 条目,含 id、group_id、title、depends_on(仅组内)、reads、writes、test(先写的失败测试)、standards、needs_human_gate(DB 迁移、认证/权限、支付、生产配置或依赖变更时为 true)。分组规则:两个任务共享 group_id 当且仅当一方依赖另一方或写入同一文件,否则分属不同组;再填 slices[],每组一条,task_ids 按依赖顺序。
输出:写入 .maestro/<slug>/lld/backend.md,各节约束均引用 file:line;返回 lld_path、tasks_path 及影响契约的决策/约束简短列表。完成标准:各节齐全;API 面足够具体可形式化;迁移可逆;边界情况已明确(不得写 TBD);破坏性变更已标注;不实现(实现由契约批准后的 /backend-impl 负责)。