Skip to main content

AI-Driven Development with Reviewable Generated APIs

As AI produces more CRUD and business glue code, flexible data-access surfaces create recurring review problems:

  1. Context Fragmentation: AI needs to simultaneously understand DB schemas, SQL macros, and lifetime annotations, making it very easy to mess up generics or trait bounds.
  2. Lack of Patterns (Anti-Pattern): The excessive flexibility of handwritten SQL means AI generates a different solution every time, making it extremely difficult to unify and standardize.
  3. Neglecting Exception Contracts: AI easily forgets to handle boundary conditions such as transaction rollbacks and soft-delete statuses.

TeaQL's generated interfaces and explicit intent/audit boundaries can reduce the number of persistence shapes an AI assistant must produce.

1. Highly Isomorphic "High-Frequency Prompt" Interface​

Large language models excel at pattern matching. TeaQL deliberately constrains the expressive space of the API, creating an extremely isomorphic domain operation language:

Generated queries follow a recurring shape; exact entity, field, facet, and terminal methods are model-specific:

# Model-shape pseudocode; inspect generated methods.
let results = Q::[entity_plural]()
    .with_[field_name]_eq(...)
    .facet_by_[dimension]_as(...)
    .comment("Query business records")
    .purpose("Serve the current business use case")
    .execute_for_list(&ctx).await?;

Generated mutations commonly follow this audited shape; inspect the generated entity for exact update and child-list methods:

# Model-shape pseudocode; inspect generated update/relationship methods.
let mut entity = ...;
entity.set_[field_name](...);
entity.[child_entity_plural]_mut().push(...);
entity.audit_as("Save operation").save(&ctx).await?;

This constrained and predictable generated facade reduces the amount of database-specific code an AI must produce. It does not make guessed method names safe: agents must still inspect generated source, compile, test, and pass human review.

2. Strong Contract Dependency: Making Context Explicit​

Generated query execution and audited persistence accept the runtime context. This makes a missing context easier for the compiler and reviewer to detect. The context still needs correctly verified identity, policy, repositories, and provider resources; its presence alone is not authorization.

3. Built-in .cursorrules and Machine-Readable Docs​

Projects can supply focused guide files to IDE agents in addition to normal documentation. Treat them as prompts, not enforcement, and keep their commands and generated method guidance aligned with the pinned tool versions.

// Snippet from teaql.cursorrules
When the user requests [query list], you must:
1. Read generated query source and use its exact `Q::...()` facade and field methods.
2. Chain the `.comment("business intent")` call, describing the query purpose in English.
3. Put `.purpose("why")` immediately before the exact generated execution terminal; do not guess a pagination terminal.

When the user requests [modify data], you must:
1. Fetch the entity and use the exact generated update/relationship methods.
2. Use `entity.audit_as("Save operation").save(&ctx).await` to persist changes.
3. Writing manual `UPDATE` SQL is strictly prohibited.

Verified Purpose Wrapper Boundary​

teaql-tool-core 1.0.0 contains MustPurpose<T>, which keeps its value private until purpose(...) consumes the wrapper. The inspected sources do not prove that every computation, time, HTTP, file, or other I/O API returns this wrapper, nor do they establish the older universal MustComment<T> examples.

Use compiler enforcement only for a released API that actually returns the wrapper. Arbitrary handwritten Rust and third-party dependencies remain outside that typestate boundary. See Rust Agent Tool Boundary.

4. Eliminating "Grunt Work": Enabling AI to Focus on Business Logic​

In traditional ORM coding, AI consumes a large amount of tokens to generate boilerplate code like "begin transaction -> update main table -> loop update child tables -> handle errors -> commit transaction". Once a token is truncated or logic branches, the code becomes highly error-prone.

With TeaQL's Graph Save capability, application code can modify the object tree and invoke one audited save boundary. The runtime plans graph persistence and delegates transactions to capable providers; applications must still verify provider behavior, retries, authorization, and audit delivery.

5. Startup-Configured Runtime Diagnostics​

When an AI Agent needs to debug the code it has written, it traditionally inserts println! or tracing::info! everywhere. This litters business code and is easily forgotten during commits.

Prefer existing runtime diagnostics before adding temporary logging throughout business code. The agent can enable focused diagnostics through environment variables at startup:

# Enable current generated-workspace SQL output for one generated table.
TEAQL_SQL=_full TEAQL_SQL_TABLES=task_execution_log TEAQL_SINK=_stdout cargo test

Capture the actual output before assuming which SQL, intent, dirty-field, or trace fields are emitted by the selected runtime and subscriber. The similarly named TEAQL_SQL_LOG variables belong to a separate formatter compatibility layer and are not aliases. See Environment Variables.

Summary​

TeaQL is not only a table-querying utility. It is a generated domain API and runtime designed for human and AI-assisted development. Pattern standardization, typed contracts, explicit intent, compilation, tests, and review work together to improve consistency; none of them makes generated changes automatically correct.