AI 协作开发
本页适用于使用 Codex、Claude Code 等工具阅读和修改 Java 源码。它与产品内的 AI 对话助手不同，不会自动赋予 AI 数据库、服务器或支付操作权限。
先让 AI 读取哪些文件
在 Java 仓库根目录开始：
AGENTS.md：架构边界、契约、安全与验证规则。PRODUCT.md：已提供的能力和明确不包含的范围。README.md：当前启动与部署方式。docs/guides/project-structure.md与任务对应主题。- 实际 Controller、DTO/VO、Service、Mapper/XML、迁移及测试。
官网适合建立路径，源码决定精确字段与行为。向 AI 提供与当前发布版本对应的文档；修改前检查 git status，保留已有工作。
一个可以直接开始的排错任务
例如遇到“Docker 已启动，但 Java 连不上数据库”，先提供环境、错误和运行方式，让 AI 检查启动配置，而不是先要求它修改数据库代码：
我在本机通过 VS Code 的“Java 后端（本地开发）”启动。
MySQL/Redis 使用 sh scripts/deploy.sh dev，错误为【粘贴脱敏的异常】。
请只读检查 launch.json、启动脚本和配置加载规则，先确定实际使用的主机与端口。
不要输出配置中的密码，不要清空数据或重建数据库。
请给出原因、需要修改的位置以及确认修复的方法。得到原因后再决定修改范围。涉及客户服务器、真实付款或数据库维护时，明确可操作的环境和数据，避免把开发环境步骤直接用于生产。
项目技能
仓库 skills/ 是 Java 技能的唯一源目录，其他工具目录链接到这里。
| 技能 | 任务 |
|---|---|
| art-java-dev | 定位代码和选择验证入口 |
| art-java-feature | 新增或扩展业务 |
| art-java-api-contract | 核对共享前端与 Java 接口 |
| art-java-refactor | 保持行为的职责整理 |
| art-java-review | 审查 Java 改动 |
不要求每个小任务依次执行全部技能。根据问题选相关入口，不将技能文件当作忽略用户当前范围的理由。
可直接改写的任务模板
新增业务
在当前 Java 后端新增【业务用例】，使用角色【角色】。
先阅读 AGENTS.md、PRODUCT.md，以及【参考域】的 Controller → Service → Mapper/XML 和测试。
接口输入/输出为【约定】，状态变化为【规则】，数据范围为【范围】。
仅修改【仓库/目录】，共享前端只读用于核对契约。
保持现有响应、分页、日期、错误与权限约定，新增 Flyway 迁移。
完成后说明变更、配置/使用方式、实际验证和未验证部分。定位缺陷
版本/运行方式：【填写】；复现操作：【填写】。
接口：【方法与路径】；HTTP/业务码：【填写】；脱敏错误：【填写】。
预期：【填写】；实际：【填写】。
先沿调用链和相关测试确认原因，不清库、不更换客户密钥。
仅修复该问题，覆盖触发场景与关键拒绝边界。保持行为的重构
只整理【职责范围】，保留接口、字段、错误顺序、默认值、集合语义、事务和锁顺序。
先列真实调用方与回归入口；不改变权限、缓存失效和外部调用时机。
发现业务疑点先记录，不顺带改规则。验证如何选择
以下命令在 Java 根目录运行，Windows 替换 Maven Wrapper 命令。
# 业务模块及依赖单元测试
./mvnw -pl art-modules/art-system -am test
# 全仓测试，包含契约/架构和默认 H2 引擎用例
./mvnw test
# 格式和静态质量检查
./mvnw spotless:check checkstyle:check pmd:check
# 真实依赖与 HTTP 隔离集成验证
node scripts/integration.mjs clean普通单元测试使用 -Dtest 选择，Failsafe 集成测试使用 -Dit.test，不能混用。脚本创建一次性 MySQL/Redis/MinIO；不把 integration-tests profile 指向客户库或共享开发库。
任务只改文档时检查事实、链接、命令和 diff，无需重跑数据库测试。涉及 SQL、锁、迁移、完整认证或存储时，单元/H2 通过不能替代对应真实依赖验证。
具备同级前端和相应 Node 依赖时，check-identity.mjs、check-file.mjs、check-workflow.mjs、check-mall.mjs 可只读核对契约。客户不具备这些参考仓库也能正常启动和构建 Java。
评审 AI 产出
检查它是否读过真实调用方，是否保留客户已有改动；新接口是否补齐权限，迁移是否新增；是否用业务模型隔离 HTTP/Mapper；事务和缓存时机是否保持；是否区分模拟验证与真实部署。
不接受“编译通过所以支付可上线”“超级管理员能访问所以权限完成”“加了事务所以云存储可回滚”等结论。完成说明应列实际执行的验证及限制，不引用历史通过记录冒充本次结果。