# AGENT.md

给专业 Agent 的开发规范。本文件约束所有由 AI Agent 执行的项目开发、整理、修复、文档和交付工作。

---

## 1. 开工前强制阅读流程

每一个用户需求开始操刀前，Agent 必须先阅读并理解项目文档。没有完成本节阅读，不得开始修改文件。

### 1.1 必读根目录文档

每次需求开始前必须阅读：

- `README.md`
- `docs/ARCHITECTURE.md`
- `docs/API.md`

如任务明显涉及启动、环境、部署或本地运行，还必须阅读：

- `docs/QUICK_START.md`（若存在）

### 1.2 必读模块文档

如果任务涉及某个二级核心模块，Agent 必须阅读该模块目录文档，以 `**/docs/README.md` 和 `**/docs/ARCHITECTURE.md` 为主，例如：

- 前端任务：阅读 `**/frontend/docs/README.md`、`**/frontend/docs/ARCHITECTURE.md`
- 后端任务：阅读 `**/backend/docs/README.md`、`**/backend/docs/ARCHITECTURE.md`
- 其他任务同理

如任务涉及模块启动、环境变量、脚本或部署，还必须阅读该模块的：

- `**/docs/QUICK_START.md`（若存在）
- `**/.env.example`（若存在）
- 相关脚本

如任务涉及容器化部署，还必须阅读：

- `**/Dockerfile`
- `**/docker-compose.yml`
- `**/.dockerignore`

### 1.3 阅读后的执行要求

Agent 必须把文档中确认的项目结构、API 约定、模块边界、环境变量和已有工作流作为实现约束。不得凭记忆、猜测或通用经验覆盖本项目文档。

与最新的实际源码/配置/目录树结构相比，**文档缺失、过时或互相矛盾时有发生**，一切信息必须以最新的实际现有代码内容为准，如遇此类情况，Agent 必须先说明冲突，再基于当前代码和用户最新要求做最小必要变更。

---

## 2. 核心职责

Agent 的目标不是“尽快改完”，而是在本地完成可追踪、可回滚、可审查的工程变更。

必须做到：

- 先理解当前仓库结构、现有代码风格、已有文档和用户的最新要求。
- 只修改与任务直接相关的文件，不做无关重构。
- 每次改动后进行必要的本地验证，例如结构检查、类型检查、测试、构建或人工可读核对。
- 在回复用户时说明做了什么、哪些检查通过、哪些检查无法执行以及原因。

---

## 3. 所有工作或修改必须要与本地 Git 仓库同步

### 3.1 必须本地提交所有变更

对于任何本地文件的修改或增删，**必须全部进行git仓库同步检查**，理解是否应当将新增文件添加到gitignore/dockerignore，或者添加到commit

```bash
git diff 
git add <changed-files>
git commit -m "<clear local commit message>"
```

执行原则：

- 一个逻辑变更一个提交。
- 文档整理、结构调整、功能修改、修复问题应尽量分开提交。
- 提交信息必须说明真实意图，不允许使用 `update`、`fix`、`misc` 这类无法审查的消息。
- 提交前必须检查变更范围，避免把 `.env`、构建产物、依赖目录、缓存、本地数据库等内容纳入提交。
- 如果当前环境缺少 Git 命令，应明确告知用户，并继续保证文件变更本身可审查。

### 3.2 永远禁止任何 untracked 文件存在

对于任何含有文件改动的工作，必须在工作完成后**立即检查git status**
必须确保不存在“untracked files”或“uncommited且not-ignored files”

你需要思考预期之外的untracked files的来源，典型的来源是运行configure类操作后自动生成的config文件，需要你自行判断是否添加到ignore或commit

如果存在 **非常确定与你先前工作完全无关的文件改动** ，则需要在其他工作全部完成后的最后询问用户如何后续处理

### 3.3 Agent 高效且谨慎的 push 原则

为方便开发与运维，Agent 可以执行push工作，但 **需要遵守以下的 push 规则**

其一，Agent 可以对 **非 main 分支（或：非特定的生产分支）** 执行远程推送命令，包括但不限于：

```bash
git push -u xxx <feature-branch>
```

其二，Agent 可以 **在经过用户当下最新的显式授权时（该授权可能在附近的上下文中提出，此时无需询问）** 对 **main 分支（或：特定的生产分支）** 执行远程推送命令，包括但不限于：

```bash
git push
git push -u xxx main
```

其三，Agent 严令禁止在 **未二次确认授权时** 执行任何破坏性的远程推送命令，包括但不限于：

```bash
git push --force
git push --force-with-lease
```

原因：

- 远程分支会影响多人协作和发布流水线。
- 推送可能触发 CI/CD、部署、合并规则或生产流程。
- 远程发布权必须由人类开发者或项目维护者控制。

Agent 在本地完成 commit后，是否 push、何时 push、push 到哪个远程分支，必须由 Human 决定并执行。

再次强调，该 Human 授权在不清晰时需要立即停止工作并询问，在授权清晰时无需询问，直接执行，执行后需要详细汇报 push 工作的细节和涉及范围

---

## 4. 分支工作流

本项目采用面向多人协作的标准环境流（自 v0.11.0 起启用的 **dev → staging → production** 方案）：

```text
feature/<issue>-<name>（基于 staging）→ staging（集成验证）→ main（生产发布）
```

Agent 必须默认理解以下含义：

- `feature/<issue>-<name>`：特性 / 开发分支，**基于 `staging` 开出**，一切改动的工作区。
- `staging`：集成验证分支，对应预生产或测试环境；特性分支验证通过后**立即合并**（无需人工审批）。
- `main`：生产发布分支，只接受已经验证并批准（人类开发者显式许可）的变更；发布 tag 从 `main` 打出。

Agent 的工作边界：

- 可以在 `feature/*` 分支上修改、暂存、提交，并可推送 `feature/*` 与 `staging` 分支（见 §3.3）。
- 工作完毕且本地验证通过后，可**立即把 `feature/*` 合并到 `staging`**，无需人工审批。
- **合并到 `main` 或推送 `main` 必须经过人类开发者显式许可**；授权不清晰时立即停止并询问。
- 严禁对任何远程分支执行破坏性推送（`--force` / `--force-with-lease`）。
- 涉及 `main`（生产）的操作必须先说明风险，并只在本地准备变更、等待授权。

---

## 5. ！！！本地开发规范

！！！修改前：

- 完成“开工前强制阅读流程”。
- 查看相关配置文件、入口文件、类型定义和调用链。
- 确认任务范围，避免误改其他模块。
- 检查当前工作区是否已有用户未提交改动，不得回滚不属于自己的改动。

！！！修改中：

- 保持改动小而清晰。
- 复用现有模式和依赖，不轻易引入新框架。
- 不把密钥、令牌、私有地址、个人机器路径写入仓库文档或源码。
- 不提交 `.env` 的真实内容，只维护 `.env.example` 模板。

！！！修改后：

- 执行与改动匹配的验证。
- 检查目录结构是否符合项目约定。
- **必须进行依赖列表文件与编译/部署等配置文件或脚本的更新**，严格遵循当前代码内容，不要缺失或包含旧内容
- **必须进行文档更新**，文档范围为全局文档与你修改涉及模块（前端/后端/开发者前端）的修改，严格按照你的代码修改与当前最新的代码内容更新文档，不要缺失或包含旧内容
- **必须进行git仓库同步**，本地 `git add` 和 `git commit`，保持审查边界清晰。
- 回复用户时列出文件、验证结果和未完成风险。