Why AI-Generated Code for Your Go Project Compiles But Still Needs a Rewrite

AI-generated code for your Go project typically compiles, but it still requires rewriting. When using AI coding tools like Claude Code or Cursor to add a module, most of the time the code produced will compile and the endpoints respond. However, once you open the frontend, you might realize that the menu item is missing, or the code is written in a different style from the rest of the codebase, making it difficult to distinguish between AI-generated and original code.

The AI model does not have knowledge of your project's current state, which can lead to issues. For instance, using the go-admin open-source Gin + Vue 3 admin framework, which has been public for several years, shows that earlier versions required hand-written Api and Service files for each business module, while the current codebase recommends an Actions-based pattern with three files: model, dto, and router.

Both styles compile, but the model does not differentiate between them, and you may not notice the differences until the codebase is mixed with both styles. The most challenging part is ensuring correct seed data across multiple tables for the module to be usable in the UI. Missing any of these tables leads to silent failures, such as missing menus or buttons that don't work.

To address these issues, separate layers need to be implemented. The first layer is an AGENTS.md file, which contains conventions specific to AI coding tools and is kept short, focusing on rules that cause real failures if ignored. The second layer is a reference implementation that compiles, has tests, and runs in CI, serving as a more reliable source of truth than any spec document.

These two layers help maintain style alignment, but they are not enough on their own. Converting the process of adding a new business module from a paragraph of prose to a structured, invocable Skill, covering table design, migration, Actions-mode scaffolding, and the menu/permission seed data step, can help. The frontend side also has a matching skill for scaffolding a standard list+form page, and both are kept in sync by sharing a permission identifier.

While not every project may require a formal Skill right away, the layering underneath it can be generalized. First, document what's a hard rule with an AGENTS.md-style file, scoped to ignore this or something will break. Keep it short and point at a real, running reference implementation instead of describing the pattern in prose.

Text can eventually lie; code that CI exercises doesn't. Call out the step that's easy to skip and fails silently. In the case of go-admin, this is the permission seed data. Most nontrivial systems have an equivalent hidden dependency. However, not everything needs to be tooled, and genuinely repetitive workflows should be turned into Skills. One-off tasks are better served by documentation.