Why Shorter Prompts Work Better: Building a Stronger TeaQL Agent Harness

Our most important practical finding today was simple:

The shorter and clearer the prompt, the more effectively the coding agent works.

That does not mean removing constraints. It means moving detailed constraints out of prose and into an executable harness: the TeaQL Generation Service, generated typed APIs, model-aware assist, compiler feedback, and tests.

Today we rebuilt TeaQL Agent Kit around that finding. The agent creates a typed domain contract, the Generation Service evaluates it, generated guidance constrains the implementation, and human review happens in parallel.

The smaller, clearer workflow is now distributed as a standard Agent Skill named build-teaql-app.

The Problem with a Large Prompt Pack

Our earlier Agent Kit accumulated several useful layers:

• a system prompt;
• a task template;
• a large KSML rule catalog;
• short rules and checklists;
• copy-and-paste templates;
• error-fix examples;
• Java and Rust generation playbooks;
• historical evaluation reports and application examples.

Each file was reasonable in isolation. Together, they created a weaker execution model.

An agent could load overlapping instructions, spend context on rules unrelated to the current model, or follow an example that had fallen behind the live Generation Service. Long negative lists were especially fragile. Telling a model to avoid every programming-language or database keyword sounds helpful, but the list is large, changes across targets, and invites hallucinated restrictions.

The backend already knows which rules apply to the submitted model. Duplicating that knowledge in prompts made the harness larger without making it more reliable.

The New Division of Responsibility

We now use a simpler contract:

The Skill owns the stable workflow:

1. understand the requested business outcome;
2. create and save a complete KSML model;
3. evaluate it and repair every Error;
4. signal that the model is ready for review;
5. continue through generation, implementation, tests, and startup;
6. report the result with concrete evidence.

The Generation Service owns detailed and evolving model rules. Its Markdown evaluation report tells the agent what is wrong and what to repair. The agent does not need to memorize a second rule engine.

The generated application owns model-specific coding guidance. Before writing business logic, the agent reads the generated local AGENTS.md and current object-specific assist output instead of guessing method names.

One Correct Example Beats Many Negative Instructions

The modeling context now starts with a small basic contract and one evaluated golden example.

The example demonstrates:

• one root element and one model name;
• org="example" when no organization is specified;
• business objects with module metadata;
• representative values for type inference;
• explicit relationships;
• a reusable constant object for lifecycle state.

The golden model evaluates with zero Errors, zero Warnings, and zero Suggestions.

This is more useful than asking the agent to remember every invalid spelling, reserved word, nesting pattern, or historical workaround. The agent gets a known-good shape, creates the first complete domain model, and lets live evaluation identify the differences that matter.

Evaluation Is Feedback, Not the Product Goal

It is easy to accidentally turn “pass evaluation” into the agent's objective. That is too narrow.

The user's business result remains the goal. Evaluation is a fast quality feedback loop before generation:

1. fix all Errors;
2. preserve sections already reported as sound;
3. repair the largest repeated pattern first;
4. evaluate again after each repair round;
5. use the requirement to decide whether Warnings should be fixed or accepted;
6. treat Suggestions as optional improvements.

Once the model has zero Errors, the agent continues toward the requested runnable or testable application.

Review Is Parallel, Not a Waiting Node

After successful modeling, the coding agent sends one compact signal:

Model Ready
- Model: /absolute/path/to/models/model.xml
- Evaluation: passed — 0 errors, 0 warnings, 0 suggestions

The path is the important artifact. A person can open the actual model and review it immediately.

The signal is not an approval request. While the reviewer inspects the model or running application, the agent continues generating, implementing, compiling, and testing. If feedback arrives, the agent updates the model, evaluates it again, regenerates affected outputs, and continues.

This removes idle time without removing human judgment.

The Generated API Is Part of the Harness

TeaQL does more than produce entity classes. It gives the coding agent a typed, model-derived API surface and explicit operational constraints.

Queries declare both why the data is needed and what operation is being performed:

let merchants = Q::merchants()
    .which_names_contain("tea")
    .purpose("Find merchants for search results")
    .comment("Search merchant names")
    .execute_for_list(&ctx)
    .await?;

Writes carry an audit description:

merchant
    .audit_as("Approve reviewed merchant details")
    .save(&ctx)
    .await?;

The same intent appears in Java through purpose, comment, and auditAs. Exact query and mutation methods still come from the generated guide and assist output. The agent must not invent them.

These requirements form an API constraint harness around non-deterministic coding behavior:

• generated domain libraries stay read-only;
• query intent is explicit;
• mutation intent is auditable;
• identity and request context stay visible;
• guessed API calls become generated-guide or compiler feedback.

Load Information Only When It Becomes Relevant

The Skill uses progressive disclosure.

The golden model is available during modeling. Toolchain commands are loaded only after the model has zero Errors and generation is required. The completion report template is loaded only after the application work is complete.

That sequencing matters. A report schema does not need to occupy context during domain discovery, and Java generation details do not need to occupy context in a Rust-only modeling task.

What the Simplification Changed

The repository was reduced from 44 tracked files to 12:

Measure	Before	After	Change
Tracked files	44	12	-72.7%
Tracked bytes	224,349	26,298	-88.3%
Refactor diff	—	147 added, 5,194 removed	—

The deleted material is recoverable from the archival Git Tag archive/pre-simplification-20260730.

Repository bytes are not the same as actual model token usage, so we do not present the 88.3% reduction as token telemetry. It does, however, materially reduce duplicate instructions and the amount of background content an agent might load accidentally.

The completion report explicitly requires honest measurement:

• report actual token usage when telemetry exists;
• otherwise write not reported;
• label context-saving estimates as Estimated and state their basis;
• count full-catalog loads and evaluation rounds;
• identify mechanical checks completed before human review;
• identify the business decisions that still require human judgment.

Install and Use the Skill

Install the Skill from the TeaQL Agent Kit repository:

npx skills add teaql/teaql-agent-kit --skill build-teaql-app

Then give the coding agent a business requirement:

Use $build-teaql-app to turn this requirement into a validated, runnable
TeaQL application: build merchant onboarding with KYC review and approval.

The Skill supports the complete path from requirement to Java or Rust application. TeaQL's Java and Rust runtimes remain open source, and developers who want to inspect a small open Rust generation service can also explore teaql-forge-rs.

The Larger Lesson

An effective coding-agent harness should not try to encode every future failure inside one prompt.

Give the agent:

• a small stable contract;
• a correct example;
• a deterministic evaluator;
• generated, model-aware API guidance;
• compiler and test feedback;
• explicit audit constraints;
• a clear signal for parallel human review;
• an evidence-based completion report.

That combination is smaller than a giant prompt pack and stronger in practice. The agent spends less effort remembering rules and more effort delivering the business result against a typed, evaluated contract.