Articles/Tips & Best Practices

✦ Tips & Best Practices/2026-03-30Advanced

Antigravity × Custom Code Generator — Building Project-Specific Code Generation Pipelines with Template Engines + AI Agents

Learn how to build custom code generators by combining Antigravity's AI agents with template engines. Master Hygen, Plop, and custom TypeScript scaffolding integrated with AGENTS.md to elevate your team's code quality and productivity.

Antigravity³⁵⁷ code-generator template scaffolding automation⁹¹ productivity²⁰ advanced²⁰

✦ Premium Article

Setup and context — Why You Need Your Own Code Generator

As projects grow, you'll find yourself repeatedly creating the same file structures — API endpoints, React components, database migrations, test files. When done manually each time, it's not just slow; it leads to subtle inconsistencies as different team members interpret patterns differently.

Antigravity's AI agent can generate code that follows your project's conventions, but relying solely on prompts means repeating the same instructions and dealing with inconsistent outputs. This is where the combination of template engines and AI agents becomes powerful.

Template engines handle the "structure" while AI agents provide "context-aware logic." This two-layer architecture lets you build code generation pipelines tailored specifically to your project. In this guide, we'll walk through comparing major template engines, integrating them with Antigravity's AGENTS.md and custom rules, and building a fully working TypeScript generator from scratch.

Choosing a Template Engine — Hygen vs. Plop vs. Custom Scripts

The first decision when building a code generator is which template engine to use. Let's compare the three main approaches.

Hygen — File-Based Simplicity

Hygen is a generator that works by simply placing template files in your file system. It has a low learning curve and is well-suited for small to mid-sized projects.

# Install and set up Hygen
npm install -g hygen
hygen init self
 
# Create a template
# _templates/component/new/index.tsx.ejs.t

// _templates/component/new/index.tsx.ejs.t
---
to: src/components/<%= name %>/<%= name %>.tsx
---
import React from 'react';
 
interface <%= name %>Props {
  /** Component description */
  children?: React.ReactNode;
}
 
/**
 * <%= name %> component
 * Auto-generated: <%= new Date().toISOString().split('T')[0] %>
 */
export const <%= name %>: React.FC<<%= name %>Props> = ({ children }) => {
  return (
    <div className="<%= h.changeCase.paramCase(name) %>">
      {children}
    </div>
  );
};
 
export default <%= name %>;

Hygen's strength is that templates live as plain files in your repository, making code review and version control straightforward.

Plop — Interactive Prompt-Driven Generation

Plop generates code through interactive prompts, gathering input from the user. It excels when you need complex conditional branching.

// plopfile.ts
import { NodePlopAPI } from 'plop';
 
export default function (plop: NodePlopAPI) {
  plop.setGenerator('api-endpoint', {
    description: 'Generate a REST API endpoint',
    prompts: [
      {
        type: 'input',
        name: 'resource',
        message: 'Resource name (e.g., users, products):',
      },
      {
        type: 'checkbox',
        name: 'methods',
        message: 'HTTP methods to generate:',
        choices: ['GET', 'POST', 'PUT', 'DELETE'],
      },
      {
        type: 'confirm',
        name: 'withAuth',
        message: 'Include authentication middleware?',
        default: true,
      },
    ],
    actions: (data) => {
      const actions = [
        {
          type: 'add',
          path: 'src/api/{{dashCase resource}}/route.ts',
          templateFile: 'templates/api-route.hbs',
        },
        {
          type: 'add',
          path: 'src/api/{{dashCase resource}}/schema.ts',
          templateFile: 'templates/api-schema.hbs',
        },
      ];
      // Only generate test file when methods are selected
      if (data && data.methods && data.methods.length > 0) {
        actions.push({
          type: 'add',
          path: 'src/api/{{dashCase resource}}/route.test.ts',
          templateFile: 'templates/api-test.hbs',
        });
      }
      return actions;
    },
  });
}

Custom TypeScript Scripts — When You Need Full Control

For large-scale projects or specialized requirements, building a generator from scratch in TypeScript gives you complete flexibility.

// scripts/generate.ts
import { mkdir, writeFile, readFile } from 'fs/promises';
import { join } from 'path';
import Handlebars from 'handlebars';
 
interface GeneratorConfig {
  name: string;
  category: 'component' | 'api' | 'hook' | 'service';
  options: {
    withTests: boolean;
    withStorybook: boolean;
    withStyles: boolean;
  };
}
 
async function generate(config: GeneratorConfig): Promise<void> {
  const templateDir = join(__dirname, '../templates', config.category);
  const outputDir = join(__dirname, '../src', config.category + 's', config.name);
 
  await mkdir(outputDir, { recursive: true });
 
  // Load and compile the template
  const templateSource = await readFile(
    join(templateDir, 'index.hbs'),
    'utf-8'
  );
  const template = Handlebars.compile(templateSource);
 
  // Build context
  const context = {
    name: config.name,
    pascalName: toPascalCase(config.name),
    kebabName: toKebabCase(config.name),
    timestamp: new Date().toISOString(),
    ...config.options,
  };
 
  // Generate files
  const output = template(context);
  await writeFile(join(outputDir, 'index.tsx'), output);
 
  console.log(`✅ Generated ${config.category}: ${config.name}`);
}
 
function toPascalCase(str: string): string {
  return str.replace(/(^\w|-\w)/g, (match) =>
    match.replace('-', '').toUpperCase()
  );
}
 
function toKebabCase(str: string): string {
  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
}
 
// Usage:
// npx tsx scripts/generate.ts --name=UserProfile --category=component --withTests

As a general rule: choose Hygen for a handful of simple templates, Plop when you need interactive generation flows, and custom TypeScript scripts when you need complete control.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Master the integration patterns between template engines (Hygen/Plop) and AI agents systematically

✦Build organization-wide code generation pipelines using AGENTS.md and custom rules

✦Get working TypeScript generator implementations with complete testing strategies

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Integration Architecture with Antigravity AI Agents

Template engines alone produce "static scaffolds." By integrating Antigravity's AI agent, you unlock context-aware, intelligent code generation.

The Two-Layer Architecture

┌─────────────────────────────────────────────┐
│         User Request (Natural Language)       │
│  "Create an API endpoint with auth and       │
│   validation"                                │
└───────────────┬─────────────────────────────┘
                │
    ┌───────────▼───────────┐
    │  Antigravity AI Agent │  ← Context + Judgment
    │  (References AGENTS.md)│
    └───────────┬───────────┘
                │ Determines parameters
    ┌───────────▼───────────┐
    │  Template Engine       │  ← Structural guarantee
    │  (Hygen / Plop)       │
    └───────────┬───────────┘
                │ File generation
    ┌───────────▼───────────┐
    │  AI Post-Processing    │  ← Context-specific logic
    │  (Type inference, etc.)│
    └───────────────────────┘

In this two-layer architecture, templates generate the "skeleton" and the AI agent provides the "flesh." Templates guarantee file naming conventions, directory structure, import path consistency, and boilerplate uniformity. The AI agent handles business logic implementation, edge case handling, type definition optimization, and documentation comments.

Defining Generator Rules in AGENTS.md

By embedding code generation guidelines in Antigravity's AGENTS.md, the AI agent understands your templates' intent when generating or modifying code.

<!-- AGENTS.md (excerpt) -->
## Code Generation Guidelines
 
### Required Rules for File Generation
1. Create new components via `scripts/generate.ts`
2. When creating files directly, follow existing template patterns
3. Always run `npm run lint:fix` after generation
 
### Naming Conventions
- Components: PascalCase (e.g., UserProfile)
- File names: kebab-case (e.g., user-profile.tsx)
- Test files: *.test.ts / *.spec.ts
- Hooks: use + PascalCase (e.g., useUserProfile)
 
### Template Locations
- Components: `_templates/component/`
- API routes: `_templates/api/`
- Hooks: `_templates/hook/`
- Services: `_templates/service/`
 
### Post-Generation Checklist
- [ ] No TypeScript type errors
- [ ] No ESLint warnings
- [ ] Corresponding test file exists
- [ ] Added to index.ts exports

With these definitions in AGENTS.md, when a team member tells Antigravity to "create a new component," the agent automatically follows the generator's rules.

Implementation — Building a React Component Generator

Let's build a working component generator in TypeScript, showing the template-AI integration in practice.

Project Structure

project-root/
├── _templates/
│   ├── component/
│   │   ├── index.tsx.hbs       # Main component
│   │   ├── index.test.tsx.hbs  # Test file
│   │   ├── index.stories.tsx.hbs # Storybook
│   │   └── styles.module.css.hbs # CSS Modules
│   └── api/
│       ├── route.ts.hbs
│       └── schema.ts.hbs
├── scripts/
│   ├── generate.ts             # Generator core
│   └── templates.ts            # Template management
├── .antigravity/
│   └── rules/
│       └── code-generation.md  # Custom rules
└── AGENTS.md

Core Generator Implementation

// scripts/generate.ts
import { mkdir, writeFile, readFile, readdir } from 'fs/promises';
import { join, resolve } from 'path';
import Handlebars from 'handlebars';
 
// ============================================
// Type Definitions
// ============================================
interface ComponentConfig {
  name: string;
  props: PropDefinition[];
  hooks: string[];
  withTests: boolean;
  withStorybook: boolean;
  withStyles: boolean;
}
 
interface PropDefinition {
  name: string;
  type: string;
  required: boolean;
  defaultValue?: string;
  description: string;
}
 
interface GeneratedFile {
  path: string;
  content: string;
}
 
// ============================================
// Register Handlebars Helpers
// ============================================
Handlebars.registerHelper('pascalCase', (str: string) =>
  str.replace(/(^\w|-\w)/g, (m) => m.replace('-', '').toUpperCase())
);
 
Handlebars.registerHelper('camelCase', (str: string) => {
  const pascal = str.replace(/(^\w|-\w)/g, (m) =>
    m.replace('-', '').toUpperCase()
  );
  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
});
 
Handlebars.registerHelper('kebabCase', (str: string) =>
  str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
);
 
Handlebars.registerHelper('ifEquals', function (
  this: unknown,
  arg1: unknown,
  arg2: unknown,
  options: Handlebars.HelperOptions
) {
  return arg1 === arg2 ? options.fn(this) : options.inverse(this);
});
 
// ============================================
// Main Generation Function
// ============================================
async function generateComponent(
  config: ComponentConfig
): Promise<GeneratedFile[]> {
  const templateDir = resolve(__dirname, '../_templates/component');
  const outputDir = resolve(
    __dirname,
    '../src/components',
    toKebabCase(config.name)
  );
 
  // Create the output directory
  await mkdir(outputDir, { recursive: true });
 
  const files: GeneratedFile[] = [];
  const context = buildContext(config);
 
  // Main component (always required)
  files.push(
    await renderTemplate(
      join(templateDir, 'index.tsx.hbs'),
      join(outputDir, `${toKebabCase(config.name)}.tsx`),
      context
    )
  );
 
  // Conditionally generated files
  if (config.withTests) {
    files.push(
      await renderTemplate(
        join(templateDir, 'index.test.tsx.hbs'),
        join(outputDir, `${toKebabCase(config.name)}.test.tsx`),
        context
      )
    );
  }
 
  if (config.withStorybook) {
    files.push(
      await renderTemplate(
        join(templateDir, 'index.stories.tsx.hbs'),
        join(outputDir, `${toKebabCase(config.name)}.stories.tsx`),
        context
      )
    );
  }
 
  // Barrel file
  files.push(
    await generateBarrelFile(outputDir, config.name)
  );
 
  return files;
}
 
function buildContext(config: ComponentConfig): Record<string, unknown> {
  return {
    name: config.name,
    pascalName: toPascalCase(config.name),
    kebabName: toKebabCase(config.name),
    camelName: toCamelCase(config.name),
    props: config.props,
    hooks: config.hooks,
    hasProps: config.props.length > 0,
    requiredProps: config.props.filter((p) => p.required),
    optionalProps: config.props.filter((p) => !p.required),
    timestamp: new Date().toISOString().split('T')[0],
    withStyles: config.withStyles,
  };
}
 
async function renderTemplate(
  templatePath: string,
  outputPath: string,
  context: Record<string, unknown>
): Promise<GeneratedFile> {
  const source = await readFile(templatePath, 'utf-8');
  const template = Handlebars.compile(source);
  const content = template(context);
  await writeFile(outputPath, content, 'utf-8');
  return { path: outputPath, content };
}
 
async function generateBarrelFile(
  dir: string,
  name: string
): Promise<GeneratedFile> {
  const kebab = toKebabCase(name);
  const pascal = toPascalCase(name);
  const content = `export { ${pascal} } from './${kebab}';\nexport type { ${pascal}Props } from './${kebab}';\n`;
  const filePath = join(dir, 'index.ts');
  await writeFile(filePath, content, 'utf-8');
  return { path: filePath, content };
}
 
// Utility functions
function toPascalCase(str: string): string {
  return str.replace(/(^\w|-\w)/g, (m) => m.replace('-', '').toUpperCase());
}
function toKebabCase(str: string): string {
  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
}
function toCamelCase(str: string): string {
  const p = toPascalCase(str);
  return p.charAt(0).toLowerCase() + p.slice(1);
}
 
// Run
// Expected output:
// ✅ Generated: src/components/user-profile/user-profile.tsx
// ✅ Generated: src/components/user-profile/user-profile.test.tsx
// ✅ Generated: src/components/user-profile/index.ts

Controlling Generation Quality with Custom Rule Files

By placing custom rules in Antigravity's .antigravity/rules/ directory, you can precisely control the guidelines the AI agent references during code generation.

<!-- .antigravity/rules/code-generation.md -->
 
# Code Generation Rules
 
## Component Generation
- All components must use the `React.FC<Props>` type
- Props interfaces must always be exported
- No default exports (named exports only)
- When using CSS Modules, class names follow BEM notation
 
## Test Generation
- Use Vitest as the test framework
- Follow `describe` > `it` nesting structure
- Use `@testing-library/react`'s `render` and `screen`
 
## API Route Generation
- Zod schema validation is mandatory
- Error responses must follow RFC 7807 format
- Always include rate limiting middleware

With this rule file in place, here's how Antigravity's agent behaves:

User: "Create a UserSettings component"

Antigravity Agent's thought process:
1. Load code-generation.md rules
2. Check _templates/component/ templates
3. Analyze existing component patterns
4. Generate with React.FC<Props> + named exports per rules
5. Simultaneously generate Vitest test file

Template Versioning and Evolution Strategy

Templates aren't "set and forget." You need systems to evolve them alongside your project.

Template Validation

Prepare a script to verify templates aren't broken, and run it in CI.

// scripts/validate-templates.ts
import { readdir, readFile } from 'fs/promises';
import { join } from 'path';
import Handlebars from 'handlebars';
 
interface ValidationResult {
  template: string;
  valid: boolean;
  error?: string;
}
 
async function validateAllTemplates(): Promise<ValidationResult[]> {
  const templateRoot = join(__dirname, '../_templates');
  const categories = await readdir(templateRoot);
  const results: ValidationResult[] = [];
 
  for (const category of categories) {
    const categoryDir = join(templateRoot, category);
    const files = await readdir(categoryDir);
 
    for (const file of files) {
      if (!file.endsWith('.hbs')) continue;
 
      const filePath = join(categoryDir, file);
      const source = await readFile(filePath, 'utf-8');
 
      try {
        // Compile test
        const template = Handlebars.compile(source, { strict: true });
 
        // Render with dummy data
        const dummyContext = createDummyContext(category);
        template(dummyContext);
 
        results.push({ template: `${category}/${file}`, valid: true });
      } catch (err) {
        results.push({
          template: `${category}/${file}`,
          valid: false,
          error: err instanceof Error ? err.message : String(err),
        });
      }
    }
  }
 
  return results;
}
 
function createDummyContext(category: string): Record<string, unknown> {
  const base = {
    name: 'TestComponent',
    pascalName: 'TestComponent',
    kebabName: 'test-component',
    camelName: 'testComponent',
    timestamp: '2026-03-30',
  };
 
  switch (category) {
    case 'component':
      return {
        ...base,
        props: [{ name: 'title', type: 'string', required: true, description: 'Title' }],
        hooks: ['useState', 'useEffect'],
        hasProps: true,
        requiredProps: [{ name: 'title', type: 'string', required: true }],
        optionalProps: [],
        withStyles: true,
      };
    case 'api':
      return {
        ...base,
        methods: ['GET', 'POST'],
        withAuth: true,
        resource: 'users',
      };
    default:
      return base;
  }
}
 
// Run
validateAllTemplates().then((results) => {
  const failed = results.filter((r) => !r.valid);
  if (failed.length > 0) {
    console.error('❌ Template validation failed:');
    failed.forEach((r) => console.error(`  ${r.template}: ${r.error}`));
    process.exit(1);
  }
  console.log(`✅ All ${results.length} templates valid`);
});
 
// Expected output:
// ✅ All 6 templates valid

Template Change Impact Analysis

Before modifying a template, an impact analysis script helps assess which generated files would be affected.

// scripts/analyze-template-impact.ts
import { readdir, readFile } from 'fs/promises';
import { join, relative } from 'path';
 
async function analyzeImpact(templateName: string): Promise<void> {
  // Track template versions through header comments
  // in generated files
  const srcDir = join(__dirname, '../src');
  const generatedFiles = await findGeneratedFiles(srcDir);
 
  console.log(`Files generated from template "${templateName}":`);
  console.log(`Total: ${generatedFiles.length} files`);
 
  for (const file of generatedFiles) {
    const relPath = relative(process.cwd(), file.path);
    console.log(`  ${relPath} (v${file.templateVersion})`);
  }
}
 
interface GeneratedFileInfo {
  path: string;
  templateVersion: string;
  generatedAt: string;
}
 
async function findGeneratedFiles(dir: string): Promise<GeneratedFileInfo[]> {
  // Generated files contain this header:
  // // @generated by template v1.2.0 at 2026-03-30
  const results: GeneratedFileInfo[] = [];
  const entries = await readdir(dir, { withFileTypes: true, recursive: true });
 
  for (const entry of entries) {
    if (!entry.isFile() || !entry.name.endsWith('.tsx')) continue;
    const filePath = join(dir, entry.name);
    const content = await readFile(filePath, 'utf-8');
    const match = content.match(
      /@generated by template v([\d.]+) at ([\d-]+)/
    );
    if (match) {
      results.push({
        path: filePath,
        templateVersion: match[1],
        generatedAt: match[2],
      });
    }
  }
 
  return results;
}

Dynamic Template Extension with AI Agents

Static templates can't handle every case. For instance, generating TypeScript interfaces from an external API's schema requires intelligence beyond what templates offer. This is where Antigravity's AI agent steps in.

Pattern 1: Schema-Driven Code Generation

// scripts/schema-driven-generate.ts
import { readFile, writeFile } from 'fs/promises';
import { join } from 'path';
 
/**
 * Generate API clients from an OpenAPI schema.
 * Antigravity's agent analyzes the schema and
 * generates type-safe client code.
 */
async function generateFromSchema(
  schemaPath: string
): Promise<void> {
  const schema = JSON.parse(
    await readFile(schemaPath, 'utf-8')
  );
 
  // Generate client functions for each endpoint
  for (const [path, methods] of Object.entries(schema.paths)) {
    const endpoint = methods as Record<string, unknown>;
    for (const [method, config] of Object.entries(endpoint)) {
      const operationId = (config as { operationId?: string }).operationId;
      if (!operationId) continue;
 
      // Instructions for AI agent
      // Generates type definitions following AGENTS.md rules
      const typeDefinition = generateTypeFromSchema(
        config as Record<string, unknown>
      );
 
      console.log(
        `Generated: ${method.toUpperCase()} ${path} -> ${operationId}`
      );
    }
  }
}
 
function generateTypeFromSchema(
  config: Record<string, unknown>
): string {
  // The AI agent dynamically fills this part
  // Templates provide only the skeleton
  return '// AI agent generates type definitions';
}

Pattern 2: Learning Patterns from Existing Code

Antigravity's agent can analyze your existing codebase and learn project-specific patterns. Leverage this to dynamically improve your templates.

<!-- Example instruction for Antigravity -->
Analyze src/components/ in this project and extract
the following patterns:
 
1. Most frequently used React hook combinations
2. Prop naming patterns (on* event handlers, etc.)
3. Error handling patterns
4. Comment / JSDoc conventions
 
Output the results to _templates/component/patterns.json.

This approach makes templates "living documents" that continuously adapt to your project's actual patterns.

Testing Strategy — Testing the Generator Itself

A code generator produces other code, so you need a testing strategy that verifies the "generated code is correct."

// scripts/__tests__/generate.test.ts
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { mkdir, rm, readFile } from 'fs/promises';
import { join } from 'path';
import { generateComponent } from '../generate';
 
const TEST_OUTPUT_DIR = join(__dirname, '../../.test-output');
 
describe('Component Generator', () => {
  beforeEach(async () => {
    await mkdir(TEST_OUTPUT_DIR, { recursive: true });
  });
 
  afterEach(async () => {
    await rm(TEST_OUTPUT_DIR, { recursive: true, force: true });
  });
 
  it('generates basic component files', async () => {
    const files = await generateComponent({
      name: 'TestButton',
      props: [
        {
          name: 'label',
          type: 'string',
          required: true,
          description: 'Button label',
        },
      ],
      hooks: [],
      withTests: true,
      withStorybook: false,
      withStyles: false,
    });
 
    // Verify generated file count
    expect(files).toHaveLength(3); // component + test + barrel
 
    // Verify main component content
    const mainFile = files.find((f) =>
      f.path.endsWith('test-button.tsx')
    );
    expect(mainFile).toBeDefined();
    expect(mainFile?.content).toContain('interface TestButtonProps');
    expect(mainFile?.content).toContain('export const TestButton');
  });
 
  it('generates correct Props type definitions', async () => {
    const files = await generateComponent({
      name: 'DataTable',
      props: [
        {
          name: 'data',
          type: 'Record<string, unknown>[]',
          required: true,
          description: 'Table data',
        },
        {
          name: 'onSort',
          type: '(column: string) => void',
          required: false,
          description: 'Sort handler',
        },
      ],
      hooks: ['useState', 'useMemo'],
      withTests: false,
      withStorybook: false,
      withStyles: true,
    });
 
    const mainFile = files.find((f) =>
      f.path.endsWith('data-table.tsx')
    );
    expect(mainFile?.content).toContain('data: Record<string, unknown>[]');
    expect(mainFile?.content).toContain('onSort?: (column: string) => void');
  });
 
  it('generates TypeScript-compilable code', async () => {
    // Compile-check generated code with tsc
    // Critical for CI regression testing
    const files = await generateComponent({
      name: 'ValidComponent',
      props: [],
      hooks: [],
      withTests: false,
      withStorybook: false,
      withStyles: false,
    });
 
    // Run tsc --noEmit for type checking only
    // In actual CI, use exec('npx tsc --noEmit')
    expect(files.length).toBeGreaterThan(0);
  });
});
 
// Expected output:
// ✓ generates basic component files (12ms)
// ✓ generates correct Props type definitions (8ms)
// ✓ generates TypeScript-compilable code (5ms)

CI/CD Pipeline Integration

Integrating your generator into CI/CD ensures continuous template quality.

# .github/workflows/template-ci.yml
name: Template CI
 
on:
  push:
    paths:
      - '_templates/**'
      - 'scripts/generate.ts'
      - 'scripts/templates.ts'
 
jobs:
  validate-templates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Validate templates
        run: npx tsx scripts/validate-templates.ts
      - name: Run generator tests
        run: npx vitest run scripts/__tests__/
      - name: Type-check generated code
        run: |
          npx tsx scripts/generate.ts --name=CITestComponent --category=component --withTests
          npx tsc --noEmit
          rm -rf src/components/ci-test-component

Correct on Day One, Drifted by Month Three

The first few weeks after adding a generator feel great. The trouble starts later.

As an indie developer shipping and maintaining my own apps, I have four projects sharing the same component template. About three months in, I noticed that a component generated in one project was written noticeably differently from its counterpart in another.

The template wasn't the culprit. The edits people (and agents) made after generation had never flowed back into the template. The template was still at v1 while the actual code had quietly moved to something like v1.3.

I call this drift. The hard part of running a generator turned out not to be writing the first template — it was noticing drift on an ongoing basis.

Detecting Drift Mechanically

The approach is simple: take each generated file, re-render it through the current template, and diff the result against what's on disk. Whatever differs has drifted away from the template.

Normalize formatting before comparing. Skip that step and every file shows up as changed because of blank lines and quote styles, which makes the report useless.

// scripts/detect-drift.ts
import { readFile, readdir } from 'fs/promises';
import { join, relative } from 'path';
import Handlebars from 'handlebars';
 
interface DriftReport {
  file: string;
  templateVersion: string;
  changedLines: number;
  totalLines: number;
  ratio: number;
}
 
/**
 * Flatten formatting noise.
 * Without this, blank lines and quote style alone mark every file as drifted.
 */
function normalize(src: string): string {
  return src
    .replace(/\/\/ @generated by template v[\d.]+ at [\d-]+\n/g, '')
    .replace(/'/g, '"')
    .replace(/;\s*$/gm, '')
    .split('\n')
    .map((l) => l.trimEnd())
    .filter((l) => l.length > 0)
    .join('\n');
}
 
function countChangedLines(a: string, b: string): number {
  const setB = new Set(b.split('\n'));
  return a.split('\n').filter((l) => !setB.has(l)).length;
}
 
export async function detectDrift(
  srcDir: string,
  templatePath: string,
  contextOf: (file: string) => Record<string, unknown>
): Promise<DriftReport[]> {
  const templateSource = await readFile(templatePath, 'utf-8');
  const template = Handlebars.compile(templateSource);
 
  const entries = await readdir(srcDir, {
    withFileTypes: true,
    recursive: true,
  });
 
  const reports: DriftReport[] = [];
 
  for (const entry of entries) {
    if (!entry.isFile() || !entry.name.endsWith('.tsx')) continue;
 
    const filePath = join(entry.parentPath ?? srcDir, entry.name);
    const actual = await readFile(filePath, 'utf-8');
 
    // Files not marked as generated are out of scope
    const stamp = actual.match(/@generated by template v([\d.]+)/);
    if (!stamp) continue;
 
    const expected = template(contextOf(filePath));
    const na = normalize(actual);
    const ne = normalize(expected);
 
    const totalLines = ne.split('\n').length;
    const changedLines = countChangedLines(na, ne);
 
    reports.push({
      file: relative(process.cwd(), filePath),
      templateVersion: stamp[1],
      changedLines,
      totalLines,
      ratio: totalLines === 0 ? 0 : changedLines / totalLines,
    });
  }
 
  return reports.sort((x, y) => y.ratio - x.ratio);
}
 
// Sample output:
// src/components/user-profile/user-profile.tsx  v1.0  42/58 lines (72%)
// src/components/data-table/data-table.tsx      v1.0  11/61 lines (18%)
// src/components/badge/badge.tsx                v1.2   2/47 lines ( 4%)

Triage by Drift Ratio

Trying to fix everything the report surfaces will stall you. I bucket results by ratio instead.

Drift ratio	What it usually means	What I do
Under 5%	Formatting and comment noise	Ignore it; raise the detection threshold
5–30%	Additions specific to that one file	Leave it; drop the generated marker so it exits the managed set
Over 30%	The template itself is probably stale	Read the diff; fold anything shared back into the template

The first run across four projects and 61 generated files flagged 9 files over 30%. Reading them, 6 contained the same addition: a loading-state branch and an aria-busy attribute.

That's a template gap, not a discipline problem. I folded those 6 edits into template v1.1, and the same scan a month later returned zero files over 30%.

What actually paid off wasn't the generator — it was having a mechanism that tells me the template has gone stale. I run it monthly.

Removing Templates Is Harder Than Adding Them

Running drift detection surfaced something else: I simply had too many templates.

Across those four projects, the collection had grown to nine — component, API route, hook, service, middleware, job, migration, E2E test, and config file.

Counting three months of generation logs, only six were actually in use. The remaining three (middleware, job, config file) had each been invoked exactly once in that window.

A template you use once a quarter leaves you with maintenance cost and nothing else. Worse, low-frequency templates go stale without anyone noticing, so they're broken the moment you finally need them. The job template stopped working the day I renamed a Handlebars helper, and nobody found out for two months.

I deleted those three and switched to having the agent reference an existing file when the need comes up. Fewer templates also means faster validation runs and a smaller drift-detection surface.

My rule of thumb now: does it get invoked at least three times a quarter? Below that, a single line in AGENTS.md is cheaper than a template.

Where Agents Tend to Break Things

Ask an Antigravity agent to add a component and it follows the template path faithfully. The gaps appear wherever the work doesn't end with a single file.

Three failures kept recurring in my setup:

Missing barrel export. The component itself generates correctly, but the index.ts export never gets added. The build passes and only the import fails, so you find out late.
Test names drifting off the rule. Even with AGENTS.md specifying a naming convention, the agent's defaults sometimes win. Adding more instruction text didn't fix it.
One-sided schema updates. route.ts gets updated while schema.ts stays on the old shape.

For 1 and 3, adding a check beat adding instructions. One script runs after generation and again at pre-push.

// scripts/verify-generated.ts
import { readFile, readdir } from 'fs/promises';
import { join } from 'path';
 
interface Violation {
  kind: 'missing-export' | 'schema-stale';
  file: string;
  detail: string;
}
 
export async function verifyGenerated(
  componentsDir: string
): Promise<Violation[]> {
  const violations: Violation[] = [];
  const dirs = await readdir(componentsDir, { withFileTypes: true });
 
  for (const dir of dirs) {
    if (!dir.isDirectory()) continue;
 
    const barrelPath = join(componentsDir, dir.name, 'index.ts');
    let barrel = '';
    try {
      barrel = await readFile(barrelPath, 'utf-8');
    } catch {
      violations.push({
        kind: 'missing-export',
        file: barrelPath,
        detail: 'index.ts does not exist',
      });
      continue;
    }
 
    const files = await readdir(join(componentsDir, dir.name));
    const impl = files.filter(
      (f) => f.endsWith('.tsx') && !f.endsWith('.test.tsx')
    );
 
    for (const f of impl) {
      const base = f.replace(/\.tsx$/, '');
      if (!barrel.includes(`./${base}`)) {
        violations.push({
          kind: 'missing-export',
          file: barrelPath,
          detail: `${base} is not re-exported`,
        });
      }
    }
  }
 
  return violations;
}
 
// package.json:
//   "postgenerate": "tsx scripts/verify-generated.ts"
// call the same script from .git/hooks/pre-push

Item 2 wasn't worth a check, so I removed the rule instead. Leaving a rule in AGENTS.md that never gets followed erodes how well the remaining rules land. Write instructions you can verify are being followed. Once I made that cut, the number of times I had to hand-edit generated output dropped visibly.

If the "more instructions, less compliance" pattern sounds familiar, The More I Wrote in AGENTS.md, the Less Got Followed covers how to measure adherence.

Summary

Start with one small template — a single component type is plenty. Add one or two lines of guidance to AGENTS.md and .antigravity/rules/, then watch whether generation stays stable.

From there, pick at least one of the three safeguards covered here and add it early: template validation, generated-output verification, and drift detection. A mechanism that tells you the template has aged pays off more than another template does.

For AGENTS.md design itself, see Antigravity Context Design — Make AI Actually Understand Your Project with AGENTS.md and Knowledge Items. To enforce post-generation checks before code leaves your machine, Stopping an AI Agent from Skipping Quality Checks walks through a two-layer push gate.

As a next step, pick one generated file you already have, re-render it through its template, and look at the diff. Just knowing how many lines have moved tells you what belongs back in the template.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.