AGENTS.md@templates · git:20260924.86b013e · 2026-09-24 · sha256 4588b82e282a8dfe

AGENTS.md@templates git:20260924.86b013eA

Immutable. This exact content never changes and is served at /api/v1/blob/4588b82e282a8dfe.

# 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 有没有同步。>