freedakgmail
134 lines
4.1 KiB
Markdown
134 lines
4.1 KiB
Markdown
# AGENTS.md — AI 辅助开发协作规范
|
||
|
||
> 本文件定义 AI 辅助开发（Windsurf Cascade / 其他 AI Agent）在本项目中的协作规则。
|
||
> 所有 AI Agent 必须同时遵守 `.windsurfrules`、`.windsurfrules.DEV-RULES` 和本文件。
|
||
|
||
---
|
||
|
||
## 1. 文档阅读顺序
|
||
|
||
开始任何开发任务前，AI Agent 必须按以下顺序阅读文档：
|
||
|
||
1. **`.windsurfrules`** — 精简规则，了解技术栈和禁止事项
|
||
2. **`.windsurfrules.DEV-RULES` §0** — 文档骨架，了解项目文档结构
|
||
3. **`pmdocs/2-task.md`** — 查看当前任务状态和进度
|
||
4. **`pmdocs/1-prd-finance-v1.md`** — 了解要开发的功能需求
|
||
5. **`pmdocs/changes/CHANGELOG.md`** — 查看需求变更历史
|
||
6. **`run.md`** — 了解如何启动和测试
|
||
7. 对应模块的现有代码 — 了解代码风格和模式
|
||
|
||
---
|
||
|
||
## 2. 代码修改原则
|
||
|
||
### 2.1 最小改动
|
||
|
||
- 优先最小化修改，不重写已有代码
|
||
- 不删除与本次修改无关的代码和注释
|
||
- 不创建随机文件，除非任务明确需要
|
||
|
||
### 2.2 遵循现有模式
|
||
|
||
- 后端：遵循模块三件套（Controller + Service + Table）模式
|
||
- 前端：遵循现有页面结构（列表页/详情页/表单页模板）
|
||
- 复用公共组件，禁止重复造轮子
|
||
|
||
### 2.3 同步更新文档
|
||
|
||
- 修改代码涉及行为变更 → 更新 `pmdocs/2-task.md` 任务状态
|
||
- 修改 DB 结构 → 更新 `run.md` 数据库命令
|
||
- 修改技术栈版本 → 更新 `run.md` §1 和 `.windsurfrules`
|
||
- 新增/修改 API → 更新 `pmdocs/1-prd-finance-v1.md`（如有接口说明）
|
||
|
||
---
|
||
|
||
## 3. 任务管理
|
||
|
||
### 3.1 任务状态标记
|
||
|
||
| 标记 | 含义 |
|
||
|------|------|
|
||
| `[ ]` | 未开始 |
|
||
| `[~]` | 进行中 |
|
||
| `[x]` | 已完成 |
|
||
| `[!]` | 阻塞/有问题 |
|
||
|
||
### 3.2 任务编号
|
||
|
||
- `T1-W1-xx`：1期第1周第 xx 个任务
|
||
- `T1-W2-xx`：1期第2周第 xx 个任务
|
||
- `T2-W3-xx`：2期第3周第 xx 个任务
|
||
|
||
---
|
||
|
||
## 4. 测试纪律
|
||
|
||
- 修 bug 必先写复现测试
|
||
- 禁止删测试、禁止 `@skip`/`it.only` 进 PR
|
||
- 后端测试用真实 PostgreSQL（`ruchu_finance_test`），禁止 mock DB
|
||
- 测试覆盖率目标：70% 单元 / 20% 集成 / 10% E2E
|
||
|
||
### 测试命令
|
||
|
||
```bash
|
||
# 后端
|
||
java -cp apps/api/gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain -p apps/api test
|
||
|
||
# 前端单元
|
||
cd apps/web && npm run test
|
||
|
||
# 前端 E2E
|
||
cd apps/web && npm run test:e2e
|
||
```
|
||
|
||
> ⚠️ `./gradlew` 脚本有 bug，用上述 `java -cp` 命令替代。
|
||
|
||
---
|
||
|
||
## 5. 提交规范
|
||
|
||
### 5.1 Git 提交信息
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
```
|
||
|
||
- **type**：`feat`(新功能) / `fix`(修复) / `refactor`(重构) / `docs`(文档) / `test`(测试) / `chore`(杂项)
|
||
- **scope**：模块名（contracts/payments/refunds/commissions/exchanges/insurances/salaries/workers/customers/reconcile/dashboard/auth/users/roles/permissions）
|
||
- **subject**：简短描述（中文）
|
||
|
||
示例：
|
||
```
|
||
feat(contracts): 合同列表页增加月份筛选
|
||
fix(payments): 退款金额校验允许零元
|
||
refactor(auth): 权限码从 user:manage 拆分为细粒度权限
|
||
```
|
||
|
||
### 5.2 禁止提交
|
||
|
||
- 禁止提交 `.env` 文件（仅提交 `.env.example`）
|
||
- 禁止提交 `build/` 目录
|
||
- 禁止提交 `node_modules/`
|
||
- 禁止提交敏感信息（密钥、密码、Token）
|
||
|
||
---
|
||
|
||
## 6. 已知问题
|
||
|
||
| 问题 | 影响 | 解决方案 |
|
||
|---|---|---|
|
||
| `gradlew` 脚本 `escape_args` bug | 后端启动/测试失败 | 用 `java -cp` 命令替代（详见 `.windsurfrules.DEV-RULES` §5.2） |
|
||
| Flyway checksum 不匹配 | 后端启动失败 | 手动更新 `flyway_schema_history`（详见 `.windsurfrules.DEV-RULES` §5.2） |
|
||
| 业务 Controller 缺少 `@PreAuthorize` | 权限控制不完整 | 新增 Controller 必须加 `@PreAuthorize`，存量逐步补充 |
|
||
|
||
---
|
||
|
||
## 7. AI Agent 行为约束
|
||
|
||
- **不猜测**：不确定时用工具查证，不编造 API/函数/参数
|
||
- **不越权**：不修改未经授权的文件，不执行有副作用的命令
|
||
- **不遗漏**：修改代码后同步更新相关文档和测试
|
||
- **不简化**：不跳过错误处理、不删除边界检查、不忽略安全校验
|
||
- **用中文沟通**：所有回复和注释使用中文 |