# AGENTS.md

<!--
放在项目根目录。Codex 每次开工前会先读这个文件。
把尖括号 <> 里的内容换成你项目的实际情况；用不上的段落直接删掉。
写短一点、写具体一点：合起来默认最多读 32 KiB，超出部分会被截掉。
写好后验证：codex --ask-for-approval never "总结一下你当前加载了哪些说明"
-->

## 项目是做什么的

<一两句话：这是什么项目，给谁用。>

主要目录：

- `<src/>`：<业务代码>
- `<tests/>`：<测试>
- `<scripts/>`：<部署、数据处理脚本>

## 怎么跑起来

```bash
<安装依赖，例如：npm install>
<本地启动，例如：npm run dev>
```

- 装依赖用 `<npm / pnpm / uv / poetry>`，不要换成别的包管理器。
- 需要的环境变量写在 `<.env.example>` 里。**不要读取、打印或修改 `.env`。**

## 改完怎么检查

每次改完代码，按顺序跑下面的命令，全部通过再说「改好了」：

```bash
<格式和静态检查，例如：npm run lint>
<类型检查，例如：npm run typecheck>
<测试，例如：npm test>
```

- 没跑或跑不了，就直接说没跑，不要写「应该没问题」。
- 修 bug 先写一个能复现的测试，看它失败，再改代码让它通过。

## 写代码的规矩

- 只改和任务有关的文件。顺手看到的问题，列在最后告诉我，不要一起改。
- 跟着项目现有的写法走：命名、目录结构、错误处理方式和周围代码保持一致。
- 不要为了「以后可能用到」加抽象、配置项或新依赖。
- <项目特有的约定，例如：接口统一返回 { code, data, message }。>

## 先问我再做

下面这些事，先说明理由，等我确认：

- 安装新的依赖，或升级大版本
- 删除文件、目录
- 修改数据库结构、迁移文件
- 修改 CI、部署配置
- 任何会调用线上服务、发请求、花钱的操作

## 不要碰

- `<migrations/ 里已经上线的迁移文件>`
- `<自动生成的文件，例如 dist/、*.generated.ts>`
- `<第三方代码，例如 vendor/>`

## 回复方式

- 用简体中文回复；代码、命令、报错保留英文原文。
- 开工前用几句话说清楚打算改哪些文件、为什么。
- 做完列出：改了什么、怎么验证的、还有什么没做。

## Code Review Rules

<!-- 给 GitHub 上的 Codex 代码审查用。只写 CI 查不出来的问题。 -->

- <例如：金额一律用分（整数）计算，看到用浮点数算钱要指出来。>
- <例如：对外接口改了字段，要检查 docs/api.md 有没有同步。>
