Start here if AI terminology feels noisy. The goal is a reliable mental model you can use whether the model runs locally or through a hosted provider.
Work through the path
Open a card when you need it. Marking a lesson complete is optional and stays only in this browser.
1Think in messages, context and budgets
An AI request is a context assembled from instructions, conversation, tool results and user input; token limits constrain what the model can see and produce.
The model does not remember your repository or database by default. Your application selects what enters the request, and every selected item competes for context space.
Budget input, output and tool results separately. A large tool dump can crowd out the actual task even when the user prompt is short.
Try it
Take one AI request and label every piece of context: instruction, user input, retrieved data, tool result and output budget.
request = {
"model": "chosen-model",
"messages": [
{"role": "system", "content": "You are a precise code reviewer."},
{"role": "user", "content": "Review this method..."}
],
"max_tokens": 800
}2Choose a model by workload, not reputation
Capability, latency, cost, context, privacy and tool support are separate dimensions of a model decision.
Create a small representative task set before comparing models. Record correctness, latency, output length, failure modes and cost for the same inputs.
A smaller or local model can be the right choice for classification, extraction or routine transformations even when a frontier model is better for ambiguous reasoning.
Try it
Write five real tasks and score two candidate models against the same expected outcome.
const criteria = {
quality: "passes domain test set",
latency: "p95 under budget",
cost: "within monthly limit",
privacy: "allowed data path",
tools: "supports required calls"
};3Validate structured output at the boundary
If your application needs JSON, treat the model response as untrusted input and validate it before using it.
Ask for a narrow schema, parse the response, validate required fields and reject or repair invalid output. The model is generating text that happens to be structured; it is not a database constraint.
Prefer provider-supported structured output when available, but keep application validation because provider behavior and prompts can change.
Try it
Make the model produce a result for three deliberately ambiguous inputs, then decide what should happen when validation fails.
public sealed record TriageResult(
string Category,
int Priority,
IReadOnlyList<string> Reasons);
var result = JsonSerializer.Deserialize<TriageResult>(json)
?? throw new InvalidDataException("Missing AI result");
if (result.Priority is < 1 or > 5)
throw new InvalidDataException("Priority is outside the contract");4Keep the tool loop under application control
A model can propose a tool call, but your application must validate arguments, authorize the action, execute it and decide what result to reveal.
The safe loop is model request, proposed call, schema validation, authorization, execution, redacted result and a final model response. The model does not become your permission system.
Separate read tools from write tools and make destructive actions require explicit human confirmation when the risk is meaningful.
Try it
List every tool your assistant can call and mark read, write, external-side-effect and secret access.
while (turns++ < maxTurns)
{
var response = await model.SendAsync(context);
if (!response.HasToolCalls) return response.Text;
foreach (var call in response.ToolCalls)
{
ValidateSchema(call);
Authorize(currentUser, call);
context.Add(await ExecuteSafely(call));
}
}5Measure AI behavior with a small evaluation set
A useful AI feature needs observable success criteria, representative test cases and redacted traces—not only a thumbs-up demo.
Start with a golden set of real but sanitized inputs and expected properties. Evaluate accuracy, refusal behavior, tool correctness, latency and cost.
Log enough metadata to reproduce a failure while excluding secrets and private customer content. Store prompts and outputs only under a deliberate retention policy.
Try it
Turn three recent AI failures into regression cases before changing the prompt.
var cases = new[]
{
new Case("missing_customer", Expected: "asks for customer id"),
new Case("valid_order", Expected: "calls read_order"),
new Case("destructive_request", Expected: "asks for approval")
};No lesson matches that phrase.
Related tools
Turn the concept into a working example with the browser-based tools.