AI 编码工作流

StackRivet 交付 AI 护栏，让 AI 编码工具待在架构内。本指南讲你每天怎么实际和它们配合。

工具先读规则

先读你要修改的仓库里的 AI 可读指南、工程标准和模块规则。工具专属说明可以补充工作流，但应指回同一套公开规则。

提案驱动的功能开发

产出正确代码的模式：

1. 引用规则或 issue。 把工具指向相关公开文档——例如”实现资产元数据端点”→ 它读 Asset Service 概念、API 约定和仓库开发规范。
2. 先提案再写。 任何非平凡改动，先让它起草 issue/RFC 摘要，写清范围、非目标和验证步骤。
3. 实现 对照所引用的规则。
4. 验证——运行仓库中记录的验证命令。
5. 提交，带可复现的 Verified: 行，引用测试输出。

如果工具产出 200 行文件却没引用是哪条规则、issue 或公开文档支撑它，停下来问”哪条需求门控这个？“。无引用的样板代码是危险信号。

模块边界模式

当一个模块需要另一个模块的数据时，工具不能用 Mapper 调用横跨过去。正确做法：

• 在所属模块的 api 包声明一个 SPI 接口。
• 消费方模块只依赖该 SPI。
• 所属模块提供实现。

这正是让 stackrivet-security 与 stackrivet-system 解耦的 SystemUserDirectory 模式（见架构）。

设计系统模式

生成前端时，工具必须产出使用 StackRivet 设计系统 的组件——StackRivet 的 ElTable/ElButton 覆盖、#5E63E0 主色、6px 圆角、ghost 变体操作按钮、数字列 tabular-nums——而不是默认的 Element Plus 蓝。

模块”做完”的含义

一个完整业务模块交付全部层——数据库迁移、后端（entity → mapper → service → controller、DTO/VO）、OpenAPI 注解、每个受保护端点的 @PreAuthorize、前端（列表 + 表单 + API client + 路由）、manifest 里的权限 seed、zh-CN + en-US i18n key 和测试。能编译但缺一层的代码是不完整的。

验证清单

让工具在宣布模块完成前跑：

mvn -pl stackrivet-<module> -am verify          # 编译 + 测试
mvn -pl stackrivet-app test -Dtest=ArchitectureTest   # 边界
cd ../stackrivet-admin-ui && pnpm typecheck && pnpm build
curl http://localhost:8080/v3/api-docs | jq '.tags[]'   # 模块在 OpenAPI 中

需要纠偏的反模式

• 只读不写——如果工具连续几轮只探索而没代码或清晰 gap 报告，让它去提实现方案。
• 默认 Element Plus 样式——<el-button type="primary"> 不带 token 覆盖是禁止的，把它指回设计系统文档。
• 绕过分层——Controller 调 Mapper、或 Controller 返回实体，都过不了架构门禁。