Skip to main content

AI Agentic Coding Artifacts

TeaQL is built from the ground up to be an AI-native framework. When teaql-forge-rs (or cargo-teaql) generates your project, it doesn't just output source code for human compilation. It generates a dedicated set of artifacts specifically designed to give AI agents (like Cursor, GitHub Copilot, and custom LLM assistants) perfect context.

This drastically reduces AI hallucinations and ensures the agent always uses the correct APIs.

1. .teaql/AGENTS.md (The Dynamic AI Manual)​

The most important artifact for AI programming is the .teaql/AGENTS.md file.

This is a dynamically generated, highly-detailed Markdown file that serves as a custom "System Prompt" or "Rulebook" for your AI assistant.

What it does:

  • Entity Dictionary: Contains the full list of your domain entities, their exact property names, types, and relations.
  • API Signatures: Documents exactly how the Q::entities() and E:: expressions are generated for your specific schema, meaning the AI doesn't have to guess the method names.
  • Usage Rules: Enforces the "Triple-Intent" semantic chain rules (e.g., reminding the AI to always use .comment().purpose().execute_for_xxx(&ctx)).
  • Live Refresh: Because it is generated dynamically based on your schema.tql, it is always up to date.

How to use it: When using an AI assistant like Cursor, you simply tag @.teaql/AGENTS.md in your prompt. The AI will instantly know the exact shape of your entire domain.

2. .teaql/schema.ast.json (Structured Metadata)​

Alongside the markdown manual, a structured JSON file is generated containing the Abstract Syntax Tree (AST) of your domain model.

What it does:

  • Provides machine-readable structure of all entities, fields, enums, and relation constraints.
  • Used by more advanced, programmatic agent frameworks (like teaql-agent-kit) to dynamically analyze the codebase, validate AI-generated code against the schema, or feed specific context into RAG (Retrieval-Augmented Generation) pipelines.

3. schema.tql (The Single Source of Truth)​

While you write schema.tql yourself, it serves as the ultimate high-level artifact for AI.

What it does:

  • Intent Declarative: It completely decouples business models from raw SQL migrations.
  • Instead of asking an AI to "write a Flyway migration script to add a user_id to the orders table and add a foreign key with cascade delete", you ask the AI to "Update schema.tql to associate an Order with a User".
  • The AI simply modifies the .tql file, and TeaQL handles all the underlying Rust structural changes, SQL DDL generation, and mapping automatically.

4. src/generated/ (The Strict API Surface)​

While these are standard Rust source files, their design is uniquely tailored for AI.

What they do:

  • Type-Safe Predictability: The generated API (e.g., Q::users().with_status_is("ACTIVE")) is rigid. There are no loose SQL strings for the AI to hallucinate.
  • Structured Logic Bug Panics: If the AI attempts to traverse a relation it forgot to load (E::user(&user).get_platform()), the generated code doesn't just crash. It throws a structured panic with a <broken> marker and a suggested_fix (e.g., .select_platform()).
  • If the AI executes a test that fails, it parses this exact panic output and can self-heal its own query seamlessly.

Summary​

When developing with TeaQL, you are essentially pair-programming with an AI that has perfect memory of your database schema.

By feeding .teaql/AGENTS.md to your assistant, using schema.tql for architectural changes, and letting the Structured Panics auto-correct the AI's logic, you achieve a level of agentic coding reliability that traditional ORMs cannot match.