Agent Rules and Prompts

TeaQL works best with AI coding tools when the agent is given strict boundaries. The goal is not to let the agent invent persistence code. The goal is to make the agent compose generated, typed, reviewable business APIs.

Core Agent Rules

Use these rules at the start of any TeaQL coding session:

Use TeaQL generated APIs for all business data access.
Do not write raw SQL unless the task explicitly asks for provider-level code.
Read generated entity and Q API source before using method names.
Do not guess setters, filters, relationship methods, or plural names.
Every query using execute_for_list() or execute() must include purpose("why") and comment("what") before execution.
Every save() or update() must include audit_as("description") before persistence.
Keep authorization, tenancy, and runtime policy inside UserContext or provider/runtime code.
When generation or eval commands print a Markdown report, read that report before changing code.

Modeling Prompt

Use this when asking an agent to modify a TeaQL model:

You are editing a TeaQL model.
Read the modeling rules before changing KSML.
Keep attributes concrete: do not leave empty attributes.
Prefer explicit relationships over inferred storage joins.
Do not add nested references that exceed the supported modeling depth.
After editing the model, run the generation command and inspect any Markdown error report.

Java Coding Prompt

Use this when asking an agent to write Java application logic:

Use generated TeaQL Java Q APIs.
Read the generated entity and Q classes before writing method calls.
Do not guess method names.
Use comment("what") and purpose("why") before execute() or executeForList().
Use auditAs("description") before save or update operations.
Keep Spring Boot wiring separate from business query composition.

Rust Coding Prompt

Use this when asking an agent to write Rust application logic:

Use generated TeaQL Rust APIs.
Read generated entity and query source before writing method calls.
Do not guess pluralization, update methods, or relationship loaders.
Use .comment("what") and .purpose("why") before execute() or execute_for_list().
Use .audit_as("description") before save() or update().
Respect async boundaries and return Result from service functions.

Error Report Prompt

Use this when generation, eval, Maven, or Cargo commands fail:

Read the Markdown error report printed by the TeaQL tool.
Classify each error before editing:
- missing method: read generated source for the correct method name
- missing purpose/comment: add intent metadata before execution
- missing audit_as: add audit metadata before save or update
- empty KSML attribute: delete it or provide a concrete value
- depth exceeded: remove one nested reference or use a scalar/string field
Fix the source cause, then rerun the same command.

Review Prompt

Use this when asking an agent to review a TeaQL change:

Review for behavioral risk first.
Check that generated files were not manually edited.
Check that queries include comment and purpose before execution.
Check that saves and updates include audit metadata.
Check that method names match generated source.
Check that tenancy and authorization remain inside UserContext or runtime policy.
Report findings with file and line references.