# 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**：`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/函数/参数 - **不越权**：不修改未经授权的文件，不执行有副作用的命令 - **不遗漏**：修改代码后同步更新相关文档和测试 - **不简化**：不跳过错误处理、不删除边界检查、不忽略安全校验 - **用中文沟通**：所有回复和注释使用中文