# AGENTS.md

primary use Chinese!!!

## Codex 规则位置

- 项目级规则写在 Codex 实际会读取的指令文件里；本仓库使用根目录 `AGENTS.md`。
- 如果以后新增更深层目录的 `AGENTS.md`，并且 Codex 会在对应上下文读取它，相关局部规则要写在那个目录的 `AGENTS.md`。

## 版本与升级日志

- 每个模块独立维护版本号，记录在各自 `Cargo.toml` 的 `package.version`。
- `ias-main` 的版本号代表整体项目版本，记录在根目录 `VERSION`。
- 版本号、`VERSION`、`CHANGELOG.md` 和 `ias_upgrade_logs` 记录在准备提交代码或用户明确要求收尾时统一处理；纯工作中间态不强制立即更新。
- 只升级本次提交中实际发生代码、行为、配置或数据库结构变化的模块版本号；未改动模块保持原版本。
- `ias-main` 作为整体项目版本，只要本次提交包含用户可感知的代码、行为、配置或数据库变化，就同步提升 `ias-main` 和根目录 `VERSION`。
- 同步更新 `CHANGELOG.md`，并通过 `ias-db/migrations` 将升级记录写入 `ias_upgrade_logs`；仅新增升级日志迁移不视为 `ias-db` 模块功能变更，不单独触发 `ias-db` 版本升级。
- `ias_upgrade_logs` 的 `version` 对应 `ias-main` 整体版本，`modules` JSONB 字段记录各模块版本。
- `CHANGELOG.md` 与 `ias_upgrade_logs` 的版本、日期和变更要保持一致。
- 升级日志应使用中文撰写，记录用户可感知变化、数据库迁移、配置项变化和关键验证结果。
- 纯讨论、方案设计或没有落地文件变更的代码审查，不需要升级版本。