AGENTS.md — AI 辅助开发协作规范

本文件定义 AI 辅助开发（Windsurf Cascade / 其他 AI Agent）在本项目中的协作规则。所有 AI Agent 必须同时遵守 .windsurfrules、.windsurfrules.DEV-RULES 和本文件。

1. 文档阅读顺序

开始任何开发任务前，AI Agent 必须按以下顺序阅读文档：

.windsurfrules — 精简规则，了解技术栈和禁止事项
.windsurfrules.DEV-RULES §0 — 文档骨架，了解项目文档结构
pmdocs/2-task.md — 查看当前任务状态和进度
pmdocs/1-prd-finance-v1.md — 了解要开发的功能需求
pmdocs/changes/CHANGELOG.md — 查看需求变更历史
run.md — 了解如何启动和测试
对应模块的现有代码 — 了解代码风格和模式

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

测试命令

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

4.1 KiB Raw Permalink Blame History Unescape Escape

AGENTS.md — AI 辅助开发协作规范

1. 文档阅读顺序

2. 代码修改原则

2.1 最小改动

2.2 遵循现有模式

2.3 同步更新文档

3. 任务管理

3.1 任务状态标记

3.2 任务编号

4. 测试纪律

测试命令

5. 提交规范

5.1 Git 提交信息

5.2 禁止提交

6. 已知问题

7. AI Agent 行为约束

4.1 KiB

Raw Permalink Blame History