Teach LLMs the Structural Contract First, Not Just Code

The article discusses how one-shot LLM code generation often fails due to a lack of structural context. It introduces the concept of 'archetypes' - a YAML contract that defines the top-level directory layout, component boundaries, and validation gates for the generated code.

Details

The article explains that one-shot LLM code generation often fails because the model lacks the structural context needed to generate robust, production-ready code. It introduces the concept of 'archetypes' - a YAML-based declarative contract that defines the expected code structure, including top-level directory layout, component boundaries, inter-component contracts, and validation gates that the generated code must pass. The author walks through an example of using an 'hexagonal-api' archetype, where the LLM reads the contract, generates the code, and then self-challenges its own output against the archetype. This approach helps ensure the generated code adheres to the expected structure and quality standards. The article notes that archetypes work best for greenfield projects, as the contract must match the target tech stack, and that frequently changing contracts can drift from the archetype over time.