AI coding workflow

StackRivet ships AI guardrails so AI coding tools stay inside the architecture. This guide is how you actually work with them day to day.

The tools read the rules first

Start with the repository’s AI-readable guide, engineering standards and module rules. Tool-specific notes can add workflow details, but they should point back to the same public rules.

Proposal-driven feature work

The pattern that produces correct code:

1. Cite the rule or issue. Point the tool at the relevant public docs — e.g. “Implement the asset metadata endpoint” → it reads the Asset Service concept, API conventions and repo development standards.
2. Propose before writing. For anything non-trivial, have it draft an issue/RFC summary with scope, non-goals and verification steps first.
3. Implement against the cited rules.
4. Verify — run the repository’s documented verification commands.
5. Commit with a reproducible Verified: line citing the test output.

If a tool generates a 200-line file without citing which rule, issue or public doc justifies it, stop and ask “which requirement gates this?” Boilerplate without a citation is a red flag.

Module-boundary pattern

When a module needs data from another module, the tool must not reach across with a Mapper call. The correct move:

• Declare an SPI interface in the owning module’s api package.
• The consuming module depends on the SPI only.
• The owning module provides the implementation.

This is exactly the SystemUserDirectory pattern that keeps stackrivet-security decoupled from stackrivet-system (see Architecture).

Design-system pattern

When generating frontend, the tool must use the StackRivet design system — the StackRivet ElTable/ElButton overrides, the #5E63E0 accent, 6px radius, ghost-variant action buttons, tabular-nums on numeric columns — not default Element Plus blue.

What “done” means for a module

A complete business module ships all layers — database migration, backend (entity → mapper → service → controller, DTO/VO), OpenAPI annotations, @PreAuthorize on every protected endpoint, frontend (list + form + API client + route), permission seed in the manifest, zh-CN + en-US i18n keys, and tests. Code that compiles but is missing a layer is incomplete.

Verification checklist

Have the tool run these before declaring a module done:

mvn -pl stackrivet-<module> -am verify          # compile + test
mvn -pl stackrivet-app test -Dtest=ArchitectureTest   # boundaries
cd ../stackrivet-admin-ui && pnpm typecheck && pnpm build
curl http://localhost:8080/v3/api-docs | jq '.tags[]'   # module in OpenAPI

Anti-patterns to redirect

• Reading without writing — if the tool explores for several turns without code or a clear gap report, tell it to propose an implementation.
• Default Element Plus styling — <el-button type="primary"> with no token override is forbidden; point it back at the design-system doc.
• Bypassing layers — a Controller calling a Mapper, or an entity returned from a Controller, fails the architecture gate.