# `AGENTS.md` 项目规范 每个项目必须在仓库根目录提供 `AGENTS.md`。新建项目时创建；对已有项目进行基础工程改造时，先审阅并补齐缺失约束。它是后续 Agent 开始任务时最先读取的仓库级约定，不是愿景文档，也不是从参考项目原样复制的长清单。生成时根据当前仓库改写技术栈、目录、命令、分支和迁移工具；删除不适用的项目特例，但保留下列通用红线。 ## 必须覆盖的内容 ### 1. 任务范围与授权 - 只完成用户明确要求的结果以及实现该结果必需的改动，不顺手扩展相邻功能、重构无关模块或处理未授权待办。 - 在已授权范围内直接完成实现和必要验证；用户只要求审阅、诊断或方案时，不擅自改代码。 - 常规且可逆的实现选择自行决定。只有无法可靠推断、会实质改变产品范围或产生不可逆结果的信息才需要澄清。 - 推送、发布、权限变更、对外发送、删除数据、轮换密钥和其他破坏性动作分别需要明确授权；本地实现或提交不等于获得这些授权。 - 保护已有未提交内容，不擅自暂存、提交、重置、覆盖或删除任务外改动。 ### 2. 防止过度设计与越界设计 - 采用满足当前需求的最简正确设计，先完成一条可验证的真实链路。新增复杂性必须说明它解决了当前哪个具体问题。 - 不为假想的第二客户端、供应商替换、未来规模、第三个业务领域或未知性能问题预建平台、插件系统、兼容层、配置开关、缓存层、消息总线、共享包或微服务。 - 采用渐进式架构：先在当前模块化单体内以清楚的业务边界完成需求；只有已有代码和运行事实证明需要独立部署、独立 Worker、跨应用复用、独立安全边界或独立运维节奏时，才拆出应用、包或服务。目录数量、接口数量和“将来可能扩展”都不是拆分理由。 - 不因目录对称、文件长度或框架惯例增加纯转发层。模块按知识和变化原因划分，对调用方隐藏授权、事务、并发、存储和失败处理。 - 不把参考项目的产品需求、服务商、环境策略、Agent 设计或部署流程自动带入当前项目。 - 只在当前任务真的改变长期约束时更新文档；不能用设计报告、接口草图或待办列表替代实现。 - 性能优化先取得证据，优先减少重复请求、全量读取和不必要计算；没有已测瓶颈时不得创建“性能模块”或通用缓存框架。 ### 3. 真实的全栈交付 - 需要身份、持久化、业务数据或外部副作用的功能必须实现真实服务端链路，不得以静态页面、前端 mock、假按钮、硬编码成功结果或“后端待接入”冒充完成。 - 服务端是身份、授权、写入和业务结果的权威来源；不信任客户端提交的用户 ID、所有权、价格、完成状态或服务器已计算的结果。 - API、Server Action、Worker、CLI 和按需存在的 Agent Tool 复用同一业务服务，不复制授权、校验、事务、幂等和副作用顺序。 - 未实现能力要明确标注为未实现，不提供看似可用但没有真实效果的入口。 - 小型项目的管理后台是同一应用内的受权限保护能力，使用同一域名、会话和服务端业务服务；有权限的账号可通过约定入口（例如 `/admin`）访问。隐藏导航不是授权，后台页面、Server Action 和 Route Handler 都必须在服务端检查角色或权限。 - 没有已确认的独立组织、部署或安全边界时，不创建单独后台仓库、后台子域、第二套登录、跨域 BFF 或重复的管理 API。 ### 4. 数据库迁移规范 项目使用数据库时，`AGENTS.md` 必须按实际 ORM 和命令写明以下规则： - 所有 Schema 变化都通过版本化迁移交付。使用 Drizzle 时提交生成的 SQL 与迁移元数据；使用 Prisma 时提交 `prisma/migrations/` 中的迁移 SQL 与 Schema 变更。不能只修改 TypeScript Schema 或 `schema.prisma`。 - 生成迁移后必须审阅实际 SQL，确认对象名称、默认值、约束、索引、锁影响和数据兼容性符合预期。自动生成不等于已经审阅。 - 已经在任何共享环境应用的迁移不可改写、删除、重排或复用编号；修正通过新的前向迁移完成。 - 在线变更采用“扩展 → 应用切换／按需回填 → 后续收缩”。新增字段、约束或索引要考虑旧版本应用并存；破坏性删除和重命名不能与依赖切换挤在同一发布步骤。 - 迁移设置合理的锁等待边界。可能重写大表、长时间持锁或批量更新的数据变更必须单独评估，并采用可观测、可恢复的分批方案；不得把大规模回填隐藏在普通应用启动中。 - 生产迁移是明确的发布步骤，不由浏览器请求触发，也不在每个应用副本启动时并发执行。默认不依赖自动 down migration 撤销已上线数据结构。 - 迁移和回填要说明重复执行、部分失败和恢复语义。需要幂等或断点续跑时在实现中明确保证，不能把“通常只运行一次”当作正确性条件。 - 验证至少覆盖从当前已发布 Schema 向前应用迁移；对关键变更再检查约束、索引、已有数据和新旧应用兼容性。交付记录写明实际执行环境与结果。 若项目当前没有数据库，仍应在 `AGENTS.md` 中写明“当前无数据库迁移”；日后引入数据库时再把本节改为实际工具和命令。不要为了满足模板创建空迁移。 ### 5. 配置与密钥 - `AGENTS.md` 写清项目采用模板文件、密钥库还是负责人明确批准的其他配置策略，不能从别的项目推断。 - 密钥不得进入浏览器产物、镜像层、日志、命令输出或文档。检查配置时只输出变量名和缺失状态。 - 测试与生产的数据库、存储、Cookie／认证上下文和外部服务配置相互隔离。 ### 6. Git、二进制资源与数据文件 - 项目必须使用 Git。Git CLI 不可用时按当前系统的标准方式安装／配置；新目录没有仓库边界时初始化 Git，并在首次提交前创建适配实际技术栈的 `.gitignore`。不得把依赖、构建产物、测试输出、日志、运行时环境文件、本地数据库、上传目录或编辑器垃圾文件纳入版本控制。 - 二进制文件不得直接进入 Git，包括项目图片、字体、音视频、文档、压缩包、用户上传、运行时文件、数据库文件和导出备份；小型品牌素材也不例外。保留可审阅的文本源文件、资源清单和处理脚本，不把 Git LFS 当成默认绕过方式。 - 产品需要图片或文件时，生产环境使用 OSS／S3 兼容对象存储；网页栅格图片优先使用压缩后的 WebP 和合适尺寸。数据库保存对象键、归属、类型、大小、校验值和状态等元数据，不把本地路径或公开 URL 当作业务权威。开发和部署不得依赖个人电脑上的资源目录。 - 禁止使用本地 JSON 文件保存用户、订单、会话、任务、内容状态或其他运行时可变业务数据；这些数据进入 PostgreSQL。JSON 文件仅用于静态配置、包元数据、翻译、明确测试夹具或导入导出中间产物，不能被应用当作数据库读写。 - 每项完整改动完成必要验证后，默认创建一次只包含本任务文件的原子本地提交，无需为正常提交再次确认。提交前检查状态、暂存清单和差异，不夹带用户已有改动；推送仍需明确授权。 - 若提交时缺少 Git 作者身份，使用仓库或组织已有配置；没有可靠来源时不能伪造姓名和邮箱，应先取得真实身份信息。 详细规则和 `.gitignore` 基线见 [Git、资源与持久化](git-repository-and-assets.md)，资源处理见[静态资源与对象存储](../performance/static-assets.md)。 ### 7. 开发、验证与交付 - 写明项目实际采用的分支和提交模型，不套用固定流程。小型单人项目可直接在主开发分支工作；多人或受保护发布流程按仓库现实定义。 - 写明可运行的安装、启动、类型检查、测试、构建、迁移生成和迁移执行命令，不保留虚构命令。 - 只要本次改动涉及后端代码、服务端依赖、运行时配置或数据库 Schema，完成实现和必要迁移后必须使用项目标准命令重启本项目对应的本地／测试服务。热更新成功不能代替最终重启；重启后等待真实就绪，并至少验证健康端点和本次受影响的后端链路，避免负责人验收时仍运行旧进程、旧配置或旧 Schema。只操作能确认属于本项目的进程／容器，保留数据卷，不能因为端口占用而终止无关服务。生产服务重启属于发布动作，仍需明确授权。 - 验证与改动风险相称：局部界面试用相关操作，业务逻辑验证关键链路，权限、持久化、迁移和队列验证各自不变量。只有广泛影响或明确要求时运行全量检查。 - 失败要定位或如实记录，不得弱化断言、吞掉错误或扩大超时来制造通过。 - 交付说明实际实现、迁移 SQL、验证结果、限制与未完成项；不能因页面可打开、编译成功或 Dockerfile 存在而声称生产就绪。 ## 推荐结构 根目录 `AGENTS.md` 可保持为以下短结构，并将内容改写为项目事实： ```markdown # 项目工作约定 ## 范围与授权 写入本项目的实施范围、外部动作和破坏性操作边界。 ## 简洁设计与架构边界 写入禁止过度设计、真实全栈链路、当前模块归属和数据权威规则。 ## 技术栈与目录 写入实际采用的框架、ORM、数据库、关键目录、管理后台是否同域，以及何时允许新增包或服务。 ## 数据库迁移 写入实际生成／审阅／提交／执行迁移 SQL 的命令和在线兼容规则；无数据库时明确不适用。 ## Git、资源与数据 写入 Git 初始化、`.gitignore`、本地提交、二进制资源、OSS 和禁止本地 JSON 业务存储的规则。 ## 配置与密钥 写入配置来源、版本控制策略和浏览器／镜像／日志边界。 ## 开发与验证 写入实际分支模型、常用命令、后端改动后的重启与就绪检查、按风险验证和失败处理要求。 ## 文档与交付 写入当前事实来源、需要同步更新的条件和交付记录内容。 ``` 不要在模板后继续堆叠与当前项目无关的“最佳实践”。规则越多不等于约束越好；真正需要严格的是范围、权威数据、迁移可追溯性、秘密边界和外部动作授权。 ## 审阅清单 创建或修改 `AGENTS.md` 后确认： - 文件位于仓库根目录，名称准确； - 目录、命令、分支、ORM 和迁移路径都能在仓库中找到依据； - 明确禁止越界、过度设计、假前端实现和未经授权的外部动作； - 采用渐进式架构，管理后台在小型项目中与主应用同域、同认证且由服务端权限保护； - 数据库项目明确要求保存并审阅迁移 SQL，且禁止改写已应用迁移； - `.gitignore` 与实际工具链一致，迁移 SQL、锁文件和源码没有被误忽略； - 运行时二进制资源进入对象存储，可变业务数据进入 PostgreSQL，没有本地 JSON 数据库； - 正常改动完成后会生成原子本地提交，同时保持推送为独立授权； - 后端改动后会重启本项目服务，等待真实就绪并验证受影响链路，且不会误停无关服务； - 没有真实密钥、用户数据或其他敏感值； - 没把参考项目特有的 Agent、短信、服务商或部署模式写成通用必选项； - 与 `docs/development.md`、架构和部署文档没有矛盾或大段重复。