通用工程边界

本参考适用于任何有实现工作的项目，不依赖 Agent、短信登录、特定框架或多服务部署。目标是让当前需求以最小完整设计落地，并防止代码、文档、数据和交付在边界处失控。

先划定任务范围

开始实现前，用已有上下文回答五件事：

用户完成后可观察到什么结果？
本次必须修改哪些真实链路，哪些相邻内容明确不在范围内？
是否涉及身份、用户数据、持久化写入、外部调用、发布或删除？
哪些选择可逆且可直接决定，哪些需要负责人明确授权？
用什么最小证据证明结果已完成？

将第 1、2 项作为实现边界，而不是把参考项目、待办、相邻缺陷或“以后可能需要”自动并入任务。遇到无法可靠推断、且会实质改变产品目标、不可逆数据或对外影响的缺口时再请求方向；普通技术细节不应阻断推进。

用知识归属划分模块

一个边界应将一组总是一起变化、调用方不该了解的细节封装起来。典型归属如下：

边界	对外负责	内部隐藏
界面／客户端	用户意图、草稿、展示与短暂交互状态	布局细节、焦点、缓存投影
BFF（如确有需要）	Cookie／凭据转发、协议适配、上传或流式代理	领域规则、业务写入与数据权威
API／路由	可信身份、请求／响应协议	领域事务和跨资源写入步骤
业务服务	少量业务操作、稳定结果与失败语义	授权、锁、事务、版本、幂等和副作用顺序
数据／存储	Schema、迁移、对象持久化机制	表细节、对象键、清理和存储驱动差异
Worker（如确有需要）	确定的长任务执行与状态	用户意图理解和业务规则复制

不是每个项目都需要这些层。不存在协议转换就不建 BFF；没有长任务就不建 Worker；单一应用没有真实重复就不拆共享包。也不要将一个业务操作拆成必须由调用方按固定顺序编排的多个小函数。

渐进式架构

从当前需求所需的最小模块化单体开始，让业务服务、数据库边界和受保护页面在同一应用中演进。先在所属模块内解决问题，再根据已经发生的变化选择下一步：长任务才增加 Worker；出现实际第二个消费者才共享包；独立部署、网络／安全边界或运维节奏已成为事实时才拆 API 或服务；小型项目的管理能力则先作为同域、同认证的受权限保护路由。

“目录看起来整齐”“接口变多”“未来可能国际化／多租户／多端”都不是拆分证据。每次新增应用、包、服务或基础设施前，说明当前调用者因此不再需要了解什么，现有单体为什么不能正确或简单地处理，以及如何验证没有制造第二个事实来源。若不能回答，保留更小的设计。

明确权威与写入规则

对每项业务事实指定一个权威来源。客户端缓存、搜索索引、分析事件、卡片、通知和派生统计是投影；它们不能反向覆盖权威记录。浏览器不能提交用户 ID、所有权、价格、完成状态或服务器已经得出的结果作为可信值。

所有用户隔离、权限检查、写入校验、事务、幂等、版本冲突和外部副作用应落在服务端业务边界。API、BFF、Worker、CLI 或按需存在的 Tool 调用同一个服务，不各自复制规则。读取公共内容、私人资料和本轮指定范围时，先过滤访问权，再检索或读取。

写操作要定义重复、并发、取消与响应丢失的含义。使用请求标识、唯一约束、版本号或事务表达真实不变量；不要用“前端不会重复点”或内存变量保证正确性。跨数据库与文件存储无法原子化时，优先保护已经提交的引用；无法确认归属时保留对象和诊断，不能贸然删除。

接口、数据与错误边界

在 HTTP、队列、文件、外部服务和进程边界校验输入。未知字段、缺字段、非法 JSON、越权引用和不合法状态应尽早失败；不能静默转换为空对象或成功结果。接口应说明输入、输出、权限和可见失败类别，但不泄露上游错误正文、密钥或其他用户资料。

业务错误、无结果、版本冲突、未授权、可重试外部故障和不可恢复故障应可区分。只重试真正可重试的操作；后台投递可重试不等于外部调用或业务副作用恰好一次。取消不撤销已经提交的事实，界面应如实显示最终状态。

防止越界与过度设计

以下模式默认拒绝，除非当前需求能说明收益：

为假想客户端、供应商、第三个业务领域或未来性能问题建平台、抽象层、配置开关或兼容分支；
仅为了目录对称、文件行数或技术潮流拆包、拆服务或引入依赖；
通过假数据、假按钮、前端 mock 或未接后端的页面宣称能力完成；
把页面位置、点击来源、模型输出或缓存当作授权和业务事实；
为一个局部问题重写无关模块、全量迁移数据或扩大测试范围；
把参考项目的服务商、环境策略、发布门禁和产品流程原样照搬。

新增复杂性前，回答：它解决哪个已存在的问题？调用方因此少知道什么？不加它是否无法正确交付？如何验证它没有增加第二个事实来源？若回答只是“以后可能需要”，选择更小的实现。

文档与交付边界

每个项目的根目录 AGENTS.md 记录可执行的项目约定和授权边界，并明确禁止 Agent 把参考项目、邻近问题、假想未来需求或个人偏好并入当前任务。它还要规定项目实际使用的迁移产物与验证方式，避免 Schema 只改代码却没有可审阅、可发布的迁移 SQL。当前架构、开发、部署或领域契约各有唯一事实来源；计划、决策和验收记录标明日期与状态。代码变更只更新真正受影响的文档，不能用大量新文档替代实现，也不能让历史计划冒充当前能力。

交付时说明实际改变的用户结果、关键边界、验证证据和仍未完成项。不要因编译通过、Dockerfile 存在、替身成功或页面可打开，就声称生产、外部集成或用户验收已经完成。