Imported from yqx2006-maker/weixinxiaochengxu- (
templates/AGENTS.md). Install upstream withnpx skills add yqx2006-maker/weixinxiaochengxu- --skill templates. Copyright stays with the author.
AGENTS.md · 项目约定（给 AI 的工作说明）
放在项目根目录。任何 AI 助手开工前必读本文件。 如果你的工具会自动加载其他文件名（
CLAUDE.md/.cursorrules等），把本文件内容放过去，或放一个指针文件。
0. 开工前必须做的三件事
- 读
AI-COORDINATION.md—— 所有权表、任务板、消息区。 - 读你即将修改的代码 —— 不要凭猜测写。
- 确认你要改的文件归你 —— 不归你的走消息区提需求。
第 2 条最容易被跳过，也最贵。 AI 最大的浪费不是写错，是写重复。
1. 这个项目是什么
- 项目：
<一句话说明> - 技术栈：
<框架 / 语言 / 后端 / 数据库> - 目标用户：
<谁在用> - 当前阶段：
<开发中 / 打磨 / 提审>
2. 运行与验证
# 安装依赖
<命令>
# 本地运行 / 预览
<命令>
# 跑测试（改完必须跑）
<命令>
# 静态校验（改完必须跑）
<命令>改完代码后必须做的事：跑上面的测试与校验，在收工汇报里写明结果。
3. 目录结构
<目录树，标注每个目录的职责与 owner>
4. 硬约束（不可协商）
4.1 绝对不可以做的事
- ❌ 提交密钥、口令、Token 到源码（包括"没配环境变量时的兜底值"）
- ❌ 修改
AI-COORDINATION.md的除消息区以外的区块 - ❌ 直接修改非 owner 的文件（走消息区）
- ❌ 回滚别人的改动（发现问题告知 owner）
- ❌ 批量删除文件（先检查工作区状态，见 4.3）
- ❌ 在未确认的情况下执行对外发布动作（推送、提交、发布）
4.2 必须做的事
- ✅ 任何"重建对象"的代码，必须展开原对象保留全部字段
- ✅ 任何"累加"操作必须有幂等保护
- ✅ 所有来自网络/存储的字段，读取前必须兜底
- ✅ 新增必填字段时，跑一遍编译让编译器报出所有需补齐的位置
- ✅ 修复数据加工逻辑后，确认"已产生的数据"如何处理
- ✅ 看起来多余的代码，必须在原地注释说明原因
4.3 批量操作前
1. git status # 确认工作区干净或改动已提交
2. 列出完整目标列表 # 不要用通配符批量删
3. 优先用版本控制恢复，而不是"小心别删错"
判断批量删除是否安全的唯一标准：这些文件是否全都已提交。 只要有一个未提交的改动，就不要执行。
5. 代码风格
<缩进 / 引号 / 分号规则><命名约定><注释语言>- 注释要写为什么，不只是做什么
6. 已知的坑（不要再踩）
这一节随项目推进持续追加。新踩到的坑，收工前写进来。
| 位置 | 坑 | 正确做法 |
|---|---|---|
7. 提交与汇报
提交信息格式：
<类型>: <一句话说明>
收工汇报（追加到 AI-COORDINATION.md 的消息区）：
[日期 · 代号] 完成：<文件路径> —— <一句话改动摘要> —— 影响他人：<是/否，是的话说明>
8. 当你不知道该不该做某件事时
先问，不要猜。
以下情况必须询问，不要自行决定：
- 要改的文件不归你
- 涉及删除、覆盖、迁移
- 涉及对外发布
- 涉及价值取舍（"哪个更重要"）
- 涉及平台合规（类目、隐私、权限）
在不确定的地方明确说"我不确定，需要查证"，比给一个自信的答案有价值得多。