AI coding agents are becoming very good at producing large amounts of code and content.<\/p>\n\n\n\n
When an agent changes 20 lines of code, th. You run the application. You spot a mistake. You ask the agent to fix it.<\/p>\n\n\n\n
But what happens when an agent modifies 120 files?<\/p>\n\n\n\n
Or generates 1,000 coding tutorials?<\/p>\n\n\n\n
Or produces 100,000 lines of code and content?<\/p>\n\n\n\n
Suddenly, the human becomes the bottleneck.<\/p>\n\n\n\n
This is a problem I have been facing while building AlgoCademy, an interactive platform that teaches programming and algorithmic thinking through step-by-step coding tutorials.<\/p>\n\n\n\n
A tutorial might teach Two Sum like this:<\/p>\n\n\n\n
for<\/code> loop.<\/li>\n\n\n\n- Calculate the complement.<\/li>\n\n\n\n
- Check whether the complement exists in the map.<\/li>\n\n\n\n
- Store the current number.<\/li>\n\n\n\n
- Return the matching indexes.<\/li>\n<\/ol>\n\n\n\n
AI agents are surprisingly good at generating this type of content.<\/p>\n\n\n\n
The problem is volume.<\/p>\n\n\n\n
Imagine an agent generates 500 tutorials with 10 steps each.<\/p>\n\n\n\n
That is 5,000 individual tutorial steps.<\/p>\n\n\n\n
Even if reviewing one step takes only 20 seconds, manually checking everything would require almost 28 hours of uninterrupted work.<\/p>\n\n\n\n
At that point, what exactly have we automated?<\/p>\n\n\n\n
This led me to a much more important question:<\/p>\n\n\n\n
\nCan AI agents produce large amounts of code or content without a human checking every single output?<\/p>\n<\/blockquote>\n\n\n\n
I think the answer is yes.<\/p>\n\n\n\n
But not by making the agent more careful.<\/p>\n\n\n\n
The real solution is to build a system that is good at detecting bad output<\/strong>.<\/p>\n\n\n\n
\n\n\n\nThe Wrong Goal: Make the Agent Stop Making Mistakes<\/h1>\n\n\n\n
The natural response to unreliable AI output is to improve the prompt.<\/p>\n\n\n\n
You start with:<\/p>\n\n\n\n
Generate a step-by-step coding tutorial.\n<\/code><\/pre>\n\n\n\nThen you find a mistake.<\/p>\n\n\n\n
So you add:<\/p>\n\n\n\n
Make sure every step is technically correct.\n<\/code><\/pre>\n\n\n\nThen another mistake appears.<\/p>\n\n\n\n
Do not introduce variables before explaining them.\n<\/code><\/pre>\n\n\n\nThen:<\/p>\n\n\n\n
Make sure the code from each step is consistent with the previous step.\n<\/code><\/pre>\n\n\n\nThen:<\/p>\n\n\n\n
VERY IMPORTANT: Never reveal code from a future step.\n<\/code><\/pre>\n\n\n\nSix months later, your system prompt looks like the terms and conditions for a mortgage.<\/p>\n\n\n\n
And the agent still occasionally makes mistakes.<\/p>\n\n\n\n
I am not saying prompts do not matter. They obviously do.<\/p>\n\n\n\n
But there is a fundamental difference between:<\/p>\n\n\n\n
\nReducing the probability of an error.<\/p>\n<\/blockquote>\n\n\n\n
and:<\/p>\n\n\n\n
\nBuilding a system that detects errors when they happen.<\/p>\n<\/blockquote>\n\n\n\n
For serious automation, you need both.<\/p>\n\n\n\n
Traditional software engineering already works this way.<\/p>\n\n\n\n
We do not assume programmers never create bugs.<\/p>\n\n\n\n
We use:<\/p>\n\n\n\n
\n- Type systems<\/li>\n\n\n\n
- Compilers<\/li>\n\n\n\n
- Linters<\/li>\n\n\n\n
- Unit tests<\/li>\n\n\n\n
- Integration tests<\/li>\n\n\n\n
- CI pipelines<\/li>\n\n\n\n
- Code review<\/li>\n\n\n\n
- Production monitoring<\/li>\n<\/ul>\n\n\n\n
The developer is not the entire reliability system.<\/p>\n\n\n\n
The engineering process is the reliability system.<\/strong><\/p>\n\n\n\nAI agents need the same thing.<\/p>\n\n\n\n
\n\n\n\nStop Reviewing AI Output. Start Building an AI CI Pipeline<\/h1>\n\n\n\n
The simplest AI workflow looks like this:<\/p>\n\n\n\n
AI generates artifact\n \u2193\nHuman reviews artifact\n \u2193\nPublish\n<\/code><\/pre>\n\n\n\nThe problem is that human review scales linearly with AI output.<\/p>\n\n\n\n
Generate ten times more content and you create ten times more review work.<\/p>\n\n\n\n
A better architecture looks like this:<\/p>\n\n\n\n
AI generates artifact\n \u2193\nDeterministic checks\n \u2193\nSemantic evaluators\n \u2193\nAdversarial execution\n \u2193\nAutomatic repair\n \u2193\nRisk assessment\n \u2193\nPublish or escalate to human\n<\/code><\/pre>\n\n\n\nThe human no longer checks every artifact.<\/p>\n\n\n\n
The human designs and improves the system that decides which artifacts are safe.<\/p>\n\n\n\n
This is very close to how current agent-evaluation guidance is evolving. Anthropic describes agent evaluations as commonly combining code-based, model-based, and human graders, and explicitly recommends deterministic graders where possible, model graders where necessary, and human review as an additional validation layer. escribes a practical agent eval as:<\/p>\n\n\n\n
prompt\n \u2193\ncaptured run: trace + artifacts\n \u2193\nchecks\n \u2193\nscore\n<\/code><\/pre>\n\n\n\nThe goal is to turn “this seems better” into concrete, repeatable tests. of this as AI CI<\/strong>.<\/p>\n\n\n\nTraditional CI asks:<\/p>\n\n\n\n
Does the code compile?\nDo the tests pass?\nDid linting succeed?\n<\/code><\/pre>\n\n\n\nAI CI might ask:<\/p>\n\n\n\n
Is the artifact structurally valid?\nIs the code correct?\nDid the output violate a rule?\nDoes the instruction match the generated code?\nDoes the artifact depend on knowledge it should not require?\nCan another agent successfully execute the instructions?\nHow much disagreement exists between our evaluators?\n<\/code><\/pre>\n\n\n\nThe important mental shift is this:<\/p>\n\n\n\n
\nDo not try to make the generator trustworthy enough that validation becomes unnecessary.<\/p>\n<\/blockquote>\n\n\n\n
Build validation assuming the generator will eventually fail.<\/p>\n\n\n\n
\n\n\n\nMy Specific Problem: Step-by-Step Coding Tutorials<\/h1>\n\n\n\n
Let’s use AlgoCademy as a concrete example.<\/p>\n\n\n\n
The final Two Sum solution might be:<\/p>\n\n\n\n
function twoSum(nums, target) {\n const seen = new Map();\n\n for (let i = 0; i < nums.length; i++) {\n const complement = target - nums[i];\n\n if (seen.has(complement)) {\n return [seen.get(complement), i];\n }\n\n seen.set(nums[i], i);\n }\n\n return [];\n}\n<\/code><\/pre>\n\n\n\nAn AI can explain this solution in a few seconds.<\/p>\n\n\n\n
But AlgoCademy does not just show the final solution.<\/p>\n\n\n\n
The student might start with:<\/p>\n\n\n\n
function twoSum(nums, target) {\n\n}\n<\/code><\/pre>\n\n\n\nStep 1:<\/p>\n\n\n\n
\nCreate a Map called seen<\/code>.<\/p>\n<\/blockquote>\n\n\n\nThe expected transformation is:<\/p>\n\n\n\n
function twoSum(nums, target) {\n const seen = new Map();\n}\n<\/code><\/pre>\n\n\n\nStep 2:<\/p>\n\n\n\n
\nCreate an empty for<\/code> loop that iterates through the indexes of nums<\/code>.<\/p>\n<\/blockquote>\n\n\n\nThe code becomes:<\/p>\n\n\n\n
function twoSum(nums, target) {\n const seen = new Map();\n\n for (let i = 0; i < nums.length; i++) {\n\n }\n}\n<\/code><\/pre>\n\n\n\nStep 3:<\/p>\n\n\n\n
\nInside the loop, calculate the difference between target<\/code> and the current number. Store it in a variable called complement<\/code>.<\/p>\n<\/blockquote>\n\n\n\nAnd so on.<\/p>\n\n\n\n
An AI agent can create a tutorial that looks perfectly reasonable while still making subtle mistakes.<\/p>\n\n\n\n
It might:<\/p>\n\n\n\n
\n- Introduce
complement<\/code> before explaining it.<\/li>\n\n\n\n- Modify unrelated code from the previous step.<\/li>\n\n\n\n
- Skip an important reasoning step.<\/li>\n\n\n\n
- Refer to a Map before the student has learned Maps.<\/li>\n\n\n\n
- Use
seen<\/code> in the instruction but map<\/code> in the code.<\/li>\n\n\n\n- Reveal the next step in the explanation.<\/li>\n\n\n\n
- Make a step so large that the student is effectively writing the whole solution.<\/li>\n\n\n\n
- Create an instruction with several valid interpretations.<\/li>\n\n\n\n
- Produce a technically correct final solution with a terrible learning progression.<\/li>\n<\/ul>\n\n\n\n
A normal unit test cannot detect all of these problems.<\/p>\n\n\n\n
But that does not mean a human has to inspect every tutorial.<\/p>\n\n\n\n
It means different problems require different validators.<\/p>\n\n\n\n
\n\n\n\nFirst: Turn Content Into Structured Artifacts<\/h1>\n\n\n\n
Before validating AI-generated content, make the content easy to validate.<\/p>\n\n\n\n
Do not ask an agent to return one giant Markdown document containing instructions, explanations, and code blocks.<\/p>\n\n\n\n
Instead, ask it to return structured data.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
{\n \"problemId\": \"two-sum\",\n \"language\": \"javascript\",\n \"concepts\": [\n \"arrays\",\n \"hash-maps\"\n ],\n \"initialCode\": \"function twoSum(nums, target) {\\n\\n}\",\n \"finalCode\": \"...\",\n \"steps\": [\n {\n \"id\": \"create-map\",\n \"instruction\": \"Create a Map called `seen`.\",\n \"concept\": \"hash-map\",\n \"previousCode\": \"...\",\n \"expectedCode\": \"...\",\n \"introducedSymbols\": [\n \"seen\"\n ]\n }\n ]\n}\n<\/code><\/pre>\n\n\n\nNow the tutorial is not just text.<\/p>\n\n\n\n
It is an artifact with a contract.<\/p>\n\n\n\n
You can enforce rules such as:<\/p>\n\n\n\n
Every step must have a unique ID.\n\nEvery referenced concept must exist in the concept registry.\n\nEvery declared prerequisite must already be available to the student.\n\nThe final step must reach a valid solution.\n\nA symbol cannot be marked as introduced twice.\n<\/code><\/pre>\n\n\n\nNone of these checks require an LLM.<\/p>\n\n\n\n
Your application already knows whether two IDs are identical.<\/p>\n\n\n\n
Do not ask Claude:<\/p>\n\n\n\n
\nAre all step IDs unique?<\/p>\n<\/blockquote>\n\n\n\n
Write:<\/p>\n\n\n\n
const ids = tutorial.steps.map(step => step.id);\n\nif (new Set(ids).size !== ids.length) {\n throw new Error(\"Duplicate step ID\");\n}\n<\/code><\/pre>\n\n\n\nThis is one of the most important rules I have learned while building AI workflows:<\/p>\n\n\n\n
\nNever use an LLM to check something that ordinary code can check reliably.<\/p>\n<\/blockquote>\n\n\n\n
LLMs should handle ambiguity.<\/p>\n\n\n\n
Software should enforce invariants.<\/p>\n\n\n\n
\n\n\n\nThink of Every Tutorial Step as a State Transition<\/h1>\n\n\n\n
A step-by-step coding tutorial is essentially a sequence of program states:<\/p>\n\n\n\n
S0 \u2192 S1 \u2192 S2 \u2192 S3 \u2192 S4\n<\/code><\/pre>\n\n\n\nEach tutorial instruction describes a transition:<\/p>\n\n\n\n
Sn \u2192 Sn+1\n<\/code><\/pre>\n\n\n\nFor example:<\/p>\n\n\n\n
Previous state:<\/p>\n\n\n\n
function twoSum(nums, target) {\n const seen = new Map();\n}\n<\/code><\/pre>\n\n\n\nNext state:<\/p>\n\n\n\n
function twoSum(nums, target) {\n const seen = new Map();\n\n for (let i = 0; i < nums.length; i++) {\n\n }\n}\n<\/code><\/pre>\n\n\n\nThe transformation is approximately:<\/p>\n\n\n\n
ADD ForStatement\n\ninitializer:\n let i = 0\n\ncondition:\n i < nums.length\n\nincrement:\n i++\n<\/code><\/pre>\n\n\n\nThe instruction says:<\/p>\n\n\n\n
\nCreate an empty for<\/code> loop that iterates through the indexes of nums<\/code>.<\/p>\n<\/blockquote>\n\n\n\nThe instruction and transformation agree.<\/p>\n\n\n\n
Now imagine the instruction says:<\/p>\n\n\n\n
\nLoop through every number in nums<\/code>.<\/p>\n<\/blockquote>\n\n\n\nBut the generated code iterates over indexes.<\/p>\n\n\n\n
That instruction is ambiguous.<\/p>\n\n\n\n
A student might reasonably write:<\/p>\n\n\n\n
for (const num of nums) {\n\n}\n<\/code><\/pre>\n\n\n\nThe final algorithm may still be possible.<\/p>\n\n\n\n
But the generated tutorial expects an index-based loop.<\/p>\n\n\n\n
This is exactly the kind of problem a compiler will not catch.<\/p>\n\n\n\n
So instead of asking:<\/p>\n\n\n\n
\nIs this a good tutorial step?<\/p>\n<\/blockquote>\n\n\n\n
I can ask a much narrower question:<\/p>\n\n\n\n
\nDoes the instruction accurately describe the transformation from the previous program state to the next program state?<\/p>\n<\/blockquote>\n\n\n\n
That is a much easier evaluation problem.<\/p>\n\n\n\n
\n\n\n\nBut Do Not Require Exact AST Equality<\/h1>\n\n\n\n
This is an important detail.<\/p>\n\n\n\n
My first instinct was to compare the student’s Abstract Syntax Tree with the expected AST.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
student AST === expected AST\n<\/code><\/pre>\n\n\n\nI now think that is too rigid for many coding tutorials.<\/p>\n\n\n\n
Consider:<\/p>\n\n\n\n
for (let i = 0; i < nums.length; i++) {\n}\n<\/code><\/pre>\n\n\n\nand:<\/p>\n\n\n\n
for (let index = 0; index < nums.length; index++) {\n}\n<\/code><\/pre>\n\n\n\nThe ASTs are different.<\/p>\n\n\n\n
The transformation may be pedagogically equivalent.<\/p>\n\n\n\n
Or consider:<\/p>\n\n\n\n
const complement = target - nums[i];\n<\/code><\/pre>\n\n\n\nversus:<\/p>\n\n\n\n
const needed = target - nums[i];\n<\/code><\/pre>\n\n\n\nAgain, different structure.<\/p>\n\n\n\n
Potentially the same valid idea.<\/p>\n\n\n\n
Anthropic’s evaluation guidance explicitly warns that deterministic graders can be brittle when valid variations do not match the expected pattern exactly. It also cautions against overly rigid process checks that punish valid approaches an evaluator did not anticipate. etter approach is not:<\/p>\n\n\n\n
Does the AST exactly equal our expected AST?\n<\/code><\/pre>\n\n\n\nIt is:<\/p>\n\n\n\n
Does the program satisfy the structural contract for this step?\n<\/code><\/pre>\n\n\n\nFor example:<\/p>\n\n\n\n
A loop was added.\n\nThe loop traverses nums.\n\nThe loop exposes the current index.\n\nThe loop body is empty.\n\nExisting required statements were not removed.\n<\/code><\/pre>\n\n\n\nThe validator might accept several AST patterns that satisfy those properties.<\/p>\n\n\n\n
This is a major difference.<\/p>\n\n\n\n
You are validating invariants<\/strong>, not formatting.<\/p>\n\n\n\nFor AlgoCademy, this is especially important because a coding-learning platform should avoid teaching students that there is only one textual way to write correct code.<\/p>\n\n\n\n
\n\n\n\nMake Evaluations Atomic<\/h1>\n\n\n\n
One of the worst evaluators you can create is:<\/p>\n\n\n\n
Review this tutorial.\n\nMake sure it is:\n- correct\n- clear\n- educational\n- beginner friendly\n- progressive\n- technically accurate\n\nScore it from 1 to 10.\n<\/code><\/pre>\n\n\n\nSuppose the result is:<\/p>\n\n\n\n
8\/10\n<\/code><\/pre>\n\n\n\nWhat do I do with that?<\/p>\n\n\n\n
Why was it an eight?<\/p>\n\n\n\n
What failed?<\/p>\n\n\n\n
Can an agent automatically repair it?<\/p>\n\n\n\n
Did version two improve?<\/p>\n\n\n\n
Instead, I want atomic validators.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
V001: Tutorial schema is valid\n\nV002: Step IDs are unique\n\nV003: Final solution passes hidden tests\n\nV004: Required checkpoints parse successfully\n\nV005: Symbols are introduced before they are referenced\n\nV006: Instruction matches the code transformation\n\nV007: No unrelated code is modified\n\nV008: Step introduces at most one primary learning objective\n\nV009: Explanation does not reveal future implementation details\n\nV010: Terminology matches the curriculum\n\nV011: Variable references are consistent\n\nV012: Required concepts were previously introduced\n\nV013: The tutorial reaches a correct solution\n\nV014: Complexity explanation matches the implementation\n\nV015: A student can reasonably perform the requested transformation\n<\/code><\/pre>\n\n\n\nThe result might be:<\/p>\n\n\n\n
{\n \"V001\": \"PASS\",\n \"V002\": \"PASS\",\n \"V003\": \"PASS\",\n \"V004\": \"PASS\",\n \"V005\": \"PASS\",\n \"V006\": \"FAIL\",\n \"V007\": \"PASS\",\n \"V008\": \"PASS\",\n \"V009\": \"PASS\",\n \"V010\": \"PASS\",\n \"V011\": \"PASS\",\n \"V012\": \"PASS\",\n \"V013\": \"PASS\",\n \"V014\": \"PASS\",\n \"V015\": {\n \"score\": 0.81\n }\n}\n<\/code><\/pre>\n\n\n\nNow we know exactly what happened.<\/p>\n\n\n\n
This is the agent equivalent of:<\/p>\n\n\n\n
48 tests passed\n2 tests failed\n<\/code><\/pre>\n\n\n\nInstead of:<\/p>\n\n\n\n
Your code feels pretty good.\n<\/code><\/pre>\n\n\n\nOpenAI’s current eval guidance similarly emphasizes defining measurable success and using a small set of concrete checks rather than relying on whether a new version merely “feels better.” alidate Code With Code<\/p>\n\n\n\n
For coding education, we have an enormous advantage.<\/p>\n\n\n\n
Code is much easier to validate than most AI-generated content.<\/p>\n\n\n\n
Use that advantage aggressively.<\/p>\n\n\n\n
For each final solution, I can run:<\/p>\n\n\n\n
Public examples\nHidden tests\nEdge cases\nRandomly generated tests\nReference implementations\n<\/code><\/pre>\n\n\n\nConsider Two Sum.<\/p>\n\n\n\n
Generate:<\/p>\n\n\n\n
const nums = [-3, 7, 2, 11, 5];\nconst target = 9;\n<\/code><\/pre>\n\n\n\nRun both:<\/p>\n\n\n\n
generated solution\nreference solution\n<\/code><\/pre>\n\n\n\nThen validate the result.<\/p>\n\n\n\n
For problems with several valid answers, I do not necessarily need an exact expected output.<\/p>\n\n\n\n
I can validate properties.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
function isValidTwoSumAnswer(\n nums: number[],\n target: number,\n result: number[]\n): boolean {\n if (result.length !== 2) {\n return false;\n }\n\n const [i, j] = result;\n\n if (\n !Number.isInteger(i) ||\n !Number.isInteger(j) ||\n i < 0 ||\n j < 0 ||\n i >= nums.length ||\n j >= nums.length\n ) {\n return false;\n }\n\n if (i === j) {\n return false;\n }\n\n return nums[i] + nums[j] === target;\n}\n<\/code><\/pre>\n\n\n\nThe validator does not know the exact answer.<\/p>\n\n\n\n
It knows what must be true about a correct answer.<\/p>\n\n\n\n
This leads to a much broader principle for AI systems:<\/p>\n\n\n\n
\nInstead of asking whether the AI produced exactly what you expected, identify the properties every acceptable result must satisfy.<\/p>\n<\/blockquote>\n\n\n\n
The more quality requirements you can convert into invariants, the less human review you need.<\/p>\n\n\n\n
\n\n\n\nNot Every Intermediate Step Has to Compile<\/h1>\n\n\n\n
There is another subtle issue with step-by-step coding education.<\/p>\n\n\n\n
It is tempting to create this rule:<\/p>\n\n\n\n
Every intermediate code state must compile.\n<\/code><\/pre>\n\n\n\nThat may work for a specific tutorial format.<\/p>\n\n\n\n
It is not universally correct.<\/p>\n\n\n\n
Some educational systems intentionally let a learner stop at a partially complete expression or temporarily incomplete block.<\/p>\n\n\n\n
For example, a lesson could ask the student to first write:<\/p>\n\n\n\n
if (\n<\/code><\/pre>\n\n\n\nbefore teaching the condition.<\/p>\n\n\n\n
A normal JavaScript parser will reject that state.<\/p>\n\n\n\n
You have several choices.<\/p>\n\n\n\n
You can design AlgoCademy so every completed step is a valid parsing checkpoint.<\/p>\n\n\n\n
Or you can use a tolerant parser.<\/p>\n\n\n\n
Or you can validate the edited region without requiring the whole program to execute.<\/p>\n\n\n\n
The important part is that this should be an explicit product rule.<\/p>\n\n\n\n
Do not accidentally turn:<\/p>\n\n\n\n
\nOur current examples happen to parse.<\/p>\n<\/blockquote>\n\n\n\n
into:<\/p>\n\n\n\n
\nEvery educational programming step must always compile.<\/p>\n<\/blockquote>\n\n\n\n
Your validator should enforce your pedagogy, not silently define it.<\/p>\n\n\n\n
\n\n\n\nUse LLM Judges Only Where Rules Become Semantic<\/h1>\n\n\n\n
Some questions are difficult to answer with ordinary code.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
\nIs this instruction ambiguous?<\/p>\n<\/blockquote>\n\n\n\n
\nDoes this step require a concept the student probably does not understand yet?<\/p>\n<\/blockquote>\n\n\n\n
\nDoes the explanation accidentally reveal how to solve the next step?<\/p>\n<\/blockquote>\n\n\n\n
\nIs this learning step too cognitively large?<\/p>\n<\/blockquote>\n\n\n\n
These are reasonable jobs for an LLM evaluator.<\/p>\n\n\n\n
But there is a trap.<\/p>\n\n\n\n
Do not simply ask:<\/p>\n\n\n\n
Is this a good instruction?\n<\/code><\/pre>\n\n\n\nInstead, give the evaluator a narrow rubric.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
The student knows:\n- variables\n- arrays\n- basic for loops\n\nThe student does NOT know:\n- Maps\n- Sets\n- destructuring\n\nInstruction:\n[INSTRUCTION]\n\nDoes completing this instruction require a programming concept\noutside the student's known concepts?\n\nReturn JSON:\n\n{\n \"pass\": boolean,\n \"unknownConcepts\": [],\n \"evidence\": []\n}\n<\/code><\/pre>\n\n\n\nThe judge has one job.<\/p>\n\n\n\n
I generally prefer binary or narrowly scored questions over broad quality scores.<\/p>\n\n\n\n
Compare:<\/p>\n\n\n\n
Score the tutorial's consistency from 1 to 10.\n<\/code><\/pre>\n\n\n\nwith:<\/p>\n\n\n\n
Does the instruction reference a symbol that is unavailable\nin the previous program state?\n<\/code><\/pre>\n\n\n\nThe second result is much more useful.<\/p>\n\n\n\n
\n\n\n\nDo Not Blindly Trust AI to Judge AI<\/h1>\n\n\n\n
LLM judges are useful.<\/p>\n\n\n\n
They are not objective truth machines.<\/p>\n\n\n\n
Research on LLM-as-a-judge has documented limitations including position, verbosity, and self-enhancement biases. s not mean we should avoid model-based evaluators.<\/p>\n\n\n\n
It means we should treat them as imperfect components.<\/p>\n\n\n\n
Some things I would do:<\/p>\n\n\n\n
Give each evaluator one narrow job<\/h3>\n\n\n\n
A pedagogy evaluator should evaluate pedagogy.<\/p>\n\n\n\n
A technical correctness evaluator should evaluate technical correctness.<\/p>\n\n\n\n
Do not create:<\/p>\n\n\n\n
SUPER REVIEW AGENT\n\nCheck absolutely everything.\n<\/code><\/pre>\n\n\n\nThat is just recreating the original context problem.<\/p>\n\n\n\n
Require structured evidence<\/h3>\n\n\n\n
Instead of:<\/p>\n\n\n\n
{\n \"score\": 0.72\n}\n<\/code><\/pre>\n\n\n\nI prefer:<\/p>\n\n\n\n
{\n \"pass\": false,\n \"stepId\": \"calculate-complement\",\n \"rule\": \"FUTURE_STEP_LEAKAGE\",\n \"evidence\": [\n \"The explanation references seen.has(), which is introduced in the next step.\"\n ]\n}\n<\/code><\/pre>\n\n\n\nMeasure evaluator disagreement<\/h3>\n\n\n\n
Suppose three evaluators return:<\/p>\n\n\n\n
PASS\nPASS\nPASS\n<\/code><\/pre>\n\n\n\nThat is different from:<\/p>\n\n\n\n
PASS\nPASS\nFAIL\n<\/code><\/pre>\n\n\n\nEven if your majority-vote result is still PASS.<\/p>\n\n\n\n
Disagreement itself is information.<\/p>\n\n\n\n
Calibrate judges against humans<\/h3>\n\n\n\n
Take a manually reviewed dataset.<\/p>\n\n\n\n
Run your model judge.<\/p>\n\n\n\n
Measure what it misses.<\/p>\n\n\n\n
A semantic judge should earn trust based on its performance on your specific tutorial defects.<\/p>\n\n\n\n
Do not trust it merely because you used an expensive model.<\/p>\n\n\n\n
\n\n\n\nBuild a Simulated Student Agent<\/h1>\n\n\n\n
This is the validator I find most interesting for AlgoCademy.<\/p>\n\n\n\n
Instead of asking:<\/p>\n\n\n\n
\nIs the instruction clear?<\/p>\n<\/blockquote>\n\n\n\n
Try to execute the instruction.<\/p>\n\n\n\n
Give an agent only:<\/p>\n\n\n\n
Student knowledge\nCurrent code\nTutorial instruction\n<\/code><\/pre>\n\n\n\nDo not show it the expected solution.<\/p>\n\n\n\n
Then say:<\/p>\n\n\n\n
\nModify the code by following the instruction.<\/p>\n<\/blockquote>\n\n\n\n
Imagine the instruction is:<\/p>\n\n\n\n
\nCreate a loop through nums<\/code>.<\/p>\n<\/blockquote>\n\n\n\nThe expected tutorial transformation uses:<\/p>\n\n\n\n
for (let i = 0; i < nums.length; i++) {\n\n}\n<\/code><\/pre>\n\n\n\nBut the simulated student writes:<\/p>\n\n\n\n
for (const num of nums) {\n\n}\n<\/code><\/pre>\n\n\n\nThis does not automatically mean the student’s answer is wrong.<\/p>\n\n\n\n
In fact, that is the important part.<\/p>\n\n\n\n
It may mean the instruction allows more than one reasonable interpretation.<\/p>\n\n\n\n
The evaluator can compare the student’s transformation with the step contract<\/strong>:<\/p>\n\n\n\nRequired:\n- traverse nums\n- expose the current index\n\nStudent result:\n- traverses nums: YES\n- exposes current index: NO\n<\/code><\/pre>\n\n\n\nNow ask:<\/p>\n\n\n\n
\nDid the student ignore an explicit requirement, or did the instruction fail to communicate the requirement?<\/p>\n<\/blockquote>\n\n\n\n
If “index” never appears in the instruction, the problem may be the tutorial.<\/p>\n\n\n\n
The output could be:<\/p>\n\n\n\n
{\n \"result\": \"AMBIGUOUS_INSTRUCTION\",\n \"requiredProperty\": \"INDEX_AVAILABLE\",\n \"studentInterpretation\": \"VALUE_ITERATION\",\n \"reason\": \"The instruction says to loop through nums but does not specify index-based iteration.\"\n}\n<\/code><\/pre>\n\n\n\nThis is much better than asking another AI:<\/p>\n\n\n\n
\nDo you think this instruction is clear?<\/p>\n<\/blockquote>\n\n\n\n
We attempted to follow the instruction and observed what happened.<\/p>\n\n\n\n
This leads to one of my favorite ideas for evaluating AI-generated workflows:<\/p>\n\n\n\n
\nDo not only review instructions. Execute them.<\/p>\n<\/blockquote>\n\n\n\n
If an AI creates installation instructions, run them in a clean container.<\/p>\n\n\n\n
If an AI writes API documentation, give the documentation to an agent that has never seen the implementation and ask it to integrate the API.<\/p>\n\n\n\n
If an AI creates a migration plan, execute the plan in a disposable environment.<\/p>\n\n\n\n
If an AI creates a coding tutorial step, simulate a student performing the step.<\/p>\n\n\n\n
Execution is an evaluator.<\/strong><\/p>\n\n\n\n
\n\n\n\nBuild an Automatic Repair Loop<\/h1>\n\n\n\n
Once your validators are atomic, repair becomes much easier.<\/p>\n\n\n\n
A bad repair prompt looks like:<\/p>\n\n\n\n
There are a few issues with the tutorial.\n\nPlease improve it.\n<\/code><\/pre>\n\n\n\nThe agent may rewrite half the tutorial.<\/p>\n\n\n\n
It may fix one problem and introduce three new ones.<\/p>\n\n\n\n
Instead, give it exact failures:<\/p>\n\n\n\n
{\n \"failures\": [\n {\n \"validator\": \"V006\",\n \"stepId\": \"iterate-array\",\n \"error\": \"The instruction does not specify that the loop must expose the current index.\"\n },\n {\n \"validator\": \"V009\",\n \"stepId\": \"calculate-complement\",\n \"error\": \"The explanation references seen.has(), which is introduced in a future step.\"\n }\n ]\n}\n<\/code><\/pre>\n\n\n\nThen constrain the repair agent:<\/p>\n\n\n\n
Fix only the reported failures.\n\nDo not modify passing steps unless a modification is required\nto maintain consistency.\n\nReturn a patch containing:\n- changed step IDs\n- old values\n- new values\n- validator failures addressed\n<\/code><\/pre>\n\n\n\nThen run the entire validation suite again.<\/p>\n\n\n\n
The loop becomes:<\/p>\n\n\n\n
GENERATE\n \u2193\nVALIDATE\n \u2193\nPASS? \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2192 ACCEPT\n \u2502\n NO\n \u2193\nREPAIR\n \u2193\nVALIDATE\n \u2193\nPASS? \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2192 ACCEPT\n \u2502\n NO\n \u2193\nREPAIR\n<\/code><\/pre>\n\n\n\nBut set a limit.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
Generation: attempt 0\nRepair: attempt 1\nRepair: attempt 2\nRepair: attempt 3\nHuman escalation\n<\/code><\/pre>\n\n\n\nDo not let an agent repair forever.<\/p>\n\n\n\n
An infinite agent loop is not autonomy.<\/p>\n\n\n\n
It is an expensive while (true)<\/code>.<\/p>\n\n\n\nOpenAI has published an example of a broader agent-improvement flywheel where traces, human feedback, and model feedback are converted into reusable evals and then into changes to the surrounding harness. In that example, the harness is explicitly defined as the contract around the model: instructions, tools, routing, output requirements, and validation checks. inition is very close to how I now think about these systems.<\/p>\n\n\n\n
\n\n\n\nThe Secret to Huge Outputs: Never Review the Huge Output as One Thing<\/h1>\n\n\n\n
Suppose Claude Code modifies 120 files.<\/p>\n\n\n\n
One of the worst review prompts is:<\/p>\n\n\n\n
Review all 120 files carefully and tell me whether everything is correct.\n<\/code><\/pre>\n\n\n\nYou have recreated the original problem.<\/p>\n\n\n\n
The review agent now has almost the same context problem as the generation agent.<\/p>\n\n\n\n
Instead, break the artifact into the smallest meaningful evaluation units.<\/p>\n\n\n\n
For a repository:<\/p>\n\n\n\n
Repository\n \u2193\nPackage\n \u2193\nModule\n \u2193\nFile\n \u2193\nFunction\n \u2193\nInvariant\n<\/code><\/pre>\n\n\n\nFor AlgoCademy:<\/p>\n\n\n\n
Curriculum\n \u2193\nTrack\n \u2193\nTutorial\n \u2193\nStep\n \u2193\nState transition\n<\/code><\/pre>\n\n\n\nThen validate at several levels.<\/p>\n\n\n\n
Step-level<\/h3>\n\n\n\nDoes the instruction describe the required code transformation?\n<\/code><\/pre>\n\n\n\nTutorial-level<\/h3>\n\n\n\nDoes the tutorial introduce concepts progressively?\n<\/code><\/pre>\n\n\n\nTrack-level<\/h3>\n\n\n\nDoes this tutorial require concepts that appear later in the track?\n<\/code><\/pre>\n\n\n\nCurriculum-level<\/h3>\n\n\n\nAre prerequisite dependencies acyclic and complete?\n<\/code><\/pre>\n\n\n\nMost checks should receive the minimum context required for their decision.<\/p>\n\n\n\n
This is one reason subagents can be useful in Claude Code. Anthropic’s current documentation explicitly describes subagents as separate context windows with focused prompts and tool access, and recommends them for isolating high-volume operations so logs, file reads, and test output do not flood the main conversation. er principle is not specific to Claude Code:<\/p>\n\n\n\n
\nContext should be treated as a dependency problem, not an ever-growing chat history.<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\nArtifacts Are Better Than Agent Memory<\/h1>\n\n\n\n
It is tempting to keep one enormous Claude Code or Codex session running.<\/p>\n\n\n\n
The agent has all the context.<\/p>\n\n\n\n
At first, this feels powerful.<\/p>\n\n\n\n
Eventually, the session contains:<\/p>\n\n\n\n
200 file reads\n50 tool calls\n17 failed approaches\n8 temporary scripts\n3 architecture changes\nseveral abandoned assumptions\n<\/code><\/pre>\n\n\n\nEverything may technically be somewhere in the context.<\/p>\n\n\n\n
That does not mean the context is useful.<\/p>\n\n\n\n
For high-volume workflows, I prefer explicit artifacts.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
\/tutorials\/two-sum\/spec.json\n\/tutorials\/two-sum\/generated.json\n\/tutorials\/two-sum\/validation.json\n\/tutorials\/two-sum\/repair-1.json\n\/tutorials\/two-sum\/final.json\n<\/code><\/pre>\n\n\n\nAlong with shared definitions:<\/p>\n\n\n\n
\/evals\/tutorial-step-rules.json\n\/concepts\/registry.json\n\/languages\/javascript.json\n\/reference-solutions\/two-sum.js\n<\/code><\/pre>\n\n\n\nThe repair agent does not need the generator’s entire conversation.<\/p>\n\n\n\n
It receives:<\/p>\n\n\n\n
Input artifact\nValidation failures\nRepair contract\nOutput schema\n<\/code><\/pre>\n\n\n\nThat’s it.<\/p>\n\n\n\n
Instead of:<\/p>\n\n\n\n
\nRemember the issue we discussed 45 minutes ago with step 17?<\/p>\n<\/blockquote>\n\n\n\n
The workflow says:<\/p>\n\n\n\n
Read validation.json.\n\nRepair BLOCKER failures.\n\nWrite repair-1.json.\n<\/code><\/pre>\n\n\n\nThe source of truth lives outside the model.<\/p>\n\n\n\n
The model is a worker operating on artifacts.<\/p>\n\n\n\n
That is a far more scalable architecture.<\/p>\n\n\n\n
\n\n\n\nClaude Code Should Not Be the Human Workflow Hidden in a Terminal<\/h1>\n\n\n\n
Claude Code can already support pieces of this architecture.<\/p>\n\n\n\n
Its documentation describes non-interactive execution for CI and batch processing. Its hook system supports automatic lifecycle actions, including command-based checks and agent-based verification. Its Agent SDK exposes the same general tools, agent loop, and context-management model programmatically in Python and TypeScript. e is still an important distinction.<\/p>\n\n\n\n
Imagine I use Claude Code like this:<\/p>\n\n\n\n
Build 20 tutorials.\n\nNow inspect them.\n\nRun the tests.\n\nCheck the instructions.\n\nFix the problems.\n\nReview them again.\n<\/code><\/pre>\n\n\n\nClaude Code is doing a lot of work.<\/p>\n\n\n\n
But the actual workflow still lives in my head.<\/p>\n\n\n\n
I am the harness.<\/strong><\/p>\n\n\n\nI decide:<\/p>\n\n\n\n
when to test\nwhat to inspect\nwhat looks suspicious\nwhen to ask for another review\nwhen to retry\nwhen the result is good enough\n<\/code><\/pre>\n\n\n\nThat works for interactive development.<\/p>\n\n\n\n
It does not scale to thousands of artifacts.<\/p>\n\n\n\n
The decisions need to move into software.<\/p>\n\n\n\n
Conceptually:<\/p>\n\n\n\n
const tutorial = await generateTutorial(spec);\n\nconst deterministicResults =\n await runDeterministicValidators(tutorial);\n\nif (deterministicResults.hasBlocker) {\n return runRepairLoop(tutorial, deterministicResults);\n}\n\nconst semanticResults =\n await runSemanticEvaluators(tutorial);\n\nconst simulationResults =\n await simulateStudent(tutorial);\n\nconst risk = calculateRisk({\n deterministicResults,\n semanticResults,\n simulationResults\n});\n\nif (risk >= HUMAN_REVIEW_THRESHOLD) {\n return sendToHumanReview(tutorial);\n}\n\nreturn publishTutorial(tutorial);\n<\/code><\/pre>\n\n\n\nClaude Code, Codex, or another agent may do some of the work.<\/p>\n\n\n\n
But the workflow exists outside the conversation.<\/p>\n\n\n\n
That is the difference between:<\/p>\n\n\n\n
\nI have an AI coding assistant.<\/p>\n<\/blockquote>\n\n\n\n
and:<\/p>\n\n\n\n
\nI have an AI production system.<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\nDo Not Ask “Did It Pass?” Ask “How Likely Are We to Have Missed Something?”<\/h1>\n\n\n\n
Eventually, every artifact may have dozens of validation signals.<\/p>\n\n\n\n
Some are hard requirements.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
Schema valid REQUIRED\nFinal code passes tests REQUIRED\nNo broken dependency references REQUIRED\nRequired tutorial states exist REQUIRED\n<\/code><\/pre>\n\n\n\nOthers are probabilistic:<\/p>\n\n\n\n
Instruction clarity 0.94\nPedagogical progression 0.91\nBeginner solvability 0.87\nFuture-step leakage 0.03\n<\/code><\/pre>\n\n\n\nI would be careful about making an LLM judge a hard blocker before calibrating it.<\/p>\n\n\n\n
For example:<\/p>\n\n\n\n
LLM says instruction is unclear\n \u2193\nALWAYS REJECT\n<\/code><\/pre>\n\n\n\nmay produce too many false positives.<\/p>\n\n\n\n
Instead, the release decision can combine signals:<\/p>\n\n\n\n
Deterministic failures\nSemantic scores\nEvaluator disagreement\nNumber of repair attempts\nNovel concepts\nTutorial difficulty\nHistorical defect rate for this template\n<\/code><\/pre>\n\n\n\nImagine:<\/p>\n\n\n\n
Risk < 0.10\n Auto approve\n\nRisk 0.10\u20130.30\n Run extra evaluation\n\nRisk > 0.30\n Human review\n<\/code><\/pre>\n\n\n\nThose numbers are only examples.<\/p>\n\n\n\n
The thresholds need to be calibrated using real AlgoCademy tutorials and real defects.<\/p>\n\n\n\n
The architecture is the important part.<\/p>\n\n\n\n
\n\n\n\nYou Still Need Humans, Just in a Different Place<\/h1>\n\n\n\n
I do not think the goal should be zero human involvement.<\/p>\n\n\n\n
The goal should be to move human effort from:<\/p>\n\n\n\n
Review every tutorial.\n<\/code><\/pre>\n\n\n\nto:<\/p>\n\n\n\n
Review the evaluation system.\n<\/code><\/pre>\n\n\n\nHumans should inspect:<\/p>\n\n\n\n
\n- Validator disagreements<\/li>\n\n\n\n
- New tutorial formats<\/li>\n\n\n\n
- New programming languages<\/li>\n\n\n\n
- New learning mechanics<\/li>\n\n\n\n
- High-risk artifacts<\/li>\n\n\n\n
- Random samples of auto-approved content<\/li>\n\n\n\n
- Student-reported problems<\/li>\n<\/ul>\n\n\n\n
Imagine the system publishes 1,000 tutorials.<\/p>\n\n\n\n
You manually audit 50.<\/p>\n\n\n\n
You discover two bad tutorials.<\/p>\n\n\n\n
The least valuable response is:<\/p>\n\n\n\n
\nFix those two tutorials.<\/p>\n<\/blockquote>\n\n\n\n
Of course you should fix them.<\/p>\n\n\n\n
But the more important question is:<\/p>\n\n\n\n
\nWhy did the harness approve them?<\/p>\n<\/blockquote>\n\n\n\n
Suppose the first problem is:<\/p>\n\n\n\n
\nThe instruction says “store the previous value,” but there are two possible values it could mean.<\/p>\n<\/blockquote>\n\n\n\n
Great.<\/p>\n\n\n\n
Create:<\/p>\n\n\n\n
V016: Ambiguous referent detection\n<\/code><\/pre>\n\n\n\nThe second problem is:<\/p>\n\n\n\n
\n