AGENTS.md 完整指南：让 Codex CLI 记住你的项目

# 在输入框中输入：
/init

# 项目简介（1-3 句话）
这是一个 SaaS 订阅管理平台，后端为 Node.js + Express + PostgreSQL，
前端为 React + TypeScript，使用 Stripe 处理支付。

## 目录结构
- `src/api/`：Express 路由和控制器
- `src/services/`：业务逻辑层，不含路由
- `src/models/`：Sequelize ORM 模型定义
- `src/frontend/`：React SPA 前端代码
- `tests/`：Jest 单元测试
- `generated/`：**自动生成，禁止手动修改**

## 技术栈
- 运行时：Node.js 22 LTS
- 数据库：PostgreSQL 16（本地用 Docker Compose）
- ORM：Sequelize v6
- 测试：Jest + Supertest
- CI：GitHub Actions

## 代码规范
- 使用 ESLint + Prettier（已在 .eslintrc 中配置，提交前会自动运行）
- 函数必须有 JSDoc 注释（如有参数或返回值）
- 所有数据库操作必须在 `src/services/` 层，不要在路由里直接查数据库
- 不使用 `any` 类型（TypeScript 严格模式）

## 常用命令
```bash
npm run dev          # 启动开发服务器（端口 3000）
npm test             # 运行全部测试
npm run db:migrate   # 执行数据库迁移
docker-compose up -d # 启动本地 PostgreSQL
```

## 禁止事项
- 不要修改 `generated/` 目录下的任何文件
- 不要直接提交到 main 分支，请走 PR 流程
- 不要在代码中硬编码 API Key 或密码
- Stripe webhook 处理逻辑在 `src/api/webhooks.ts`，修改前请确认已理解验签逻辑

## 测试说明
- 单元测试：`npm test`，覆盖 services 和 models 层
- 集成测试需要 Docker Compose 环境运行（`npm run test:integration`）
- 新功能须附带单元测试，测试文件放在 `tests/` 对应子目录

# 项目：用户认证服务
JWT 认证微服务，负责用户注册、登录、Token 刷新。
其他微服务通过 HTTP 调用本服务的 `/auth/verify` 接口验证 Token。

## 技术
Node.js 22 / Express 5 / TypeScript 5.4 / PostgreSQL / Redis（存 refresh token）

## 重要约定
- Token 签名密钥从环境变量 `JWT_SECRET` 读取，绝对不要硬编码
- 所有密码必须用 `bcryptjs` 哈希，轮数为 12
- 数据库连接池配置在 `src/db/pool.ts`，不要新建连接
- 错误响应统一格式：`{ error: string, code: string }`

## 命令
```bash
npm run dev     # ts-node-dev 热重启
npm test        # Jest
npm run build   # tsc 编译到 dist/
```

# 项目：数据处理流水线
处理用户行为日志（CSV/Parquet），生成用户画像特征，输出到 ClickHouse。
每天凌晨 2 点由 Airflow 触发。

## 技术栈
Python 3.12 / Pandas / Polars / ClickHouse-driver / Poetry

## 代码规范
- 使用 Ruff 格式化（`poetry run ruff format .`）
- 类型注解：所有函数参数和返回值必须有类型
- 数据处理优先用 Polars（更快），只有在需要兼容 sklearn 时才用 Pandas
- 不要在 `pipelines/` 目录里放业务逻辑，只放编排代码

## 目录
- `src/processors/`：各类数据处理器
- `src/loaders/`：数据读写（ClickHouse、S3、本地文件）
- `pipelines/`：Airflow DAG 定义
- `tests/`：pytest 测试
- `data/samples/`：本地测试用小样本数据（gitignore）

## 测试
```bash
poetry run pytest          # 全部测试
poetry run pytest -x -q    # 快速失败模式
```

# 项目：全栈 SaaS 平台 Monorepo
pnpm workspace monorepo，包含 web 前端、api 后端、shared 共享库。

## Packages
- `packages/web/`：Next.js 14 前端
- `packages/api/`：Fastify API 服务
- `packages/shared/`：共享类型定义和工具函数

## 全局约定
- 包间依赖通过 `@myapp/shared` 引入，不要跨包直接引用源文件
- 根目录 `pnpm run build` 会按顺序构建所有包
- 提交信息格式：`feat(api): 添加用户头像上传接口`

## 禁止
- 不要在 packages/web 里引入 Node.js 专有模块
- packages/shared 里只放纯函数和类型，不放任何 I/O 逻辑

# API 服务（Fastify）
REST API，负责认证、用户管理、订单处理。PostgreSQL 数据库。

## 特有约定
- 路由定义在 `src/routes/`，每个资源一个文件
- 数据库操作只在 `src/repositories/` 层
- 所有接口必须有 Zod schema 验证（入参和响应）
- 错误处理用 `src/plugins/error-handler.ts`，不要 try/catch 全局 500

## 命令
```bash
pnpm dev           # 启动（热重启）
pnpm test          # Vitest
pnpm db:migrate    # drizzle-kit push
```

# 个人偏好
- 代码注释和变量名使用英文
- 解释方案时先给出结论，再展开细节
- 生成代码时不要省略错误处理逻辑
- 如果任务不明确，先提问确认再开始写代码
- 不要自动安装 npm/pip 包，先告诉我你需要安装什么

## 我的技术偏好
- 前端：React + TypeScript（不用 Vue）
- CSS：Tailwind CSS 优先
- 测试：Vitest 优先于 Jest（新项目）
- 包管理：pnpm 优先

# .github/workflows/codex-changelog.yml
name: Codex 生成 Changelog
on:
  push:
    branches: [main]

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @openai/codex
      - run: |
          # codex exec 会自动读取 AGENTS.md，了解项目规范
          codex exec "根据最新的 git diff 更新 CHANGELOG.md"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}