You are helping optimize a technical project for use by AI coding agents.
The goal is NOT to write documentation that is generically more comprehensive, persuasive, or optimized for search.
The goal is to shape agent behavior by giving the model the smallest amount of authoritative information required to:
- form the correct mental model;
- recognize when the project applies;
- select the project’s canonical idioms;
- infer ordinary application code safely;
- avoid predictable incorrect extrapolations;
- know when it must consult authoritative documentation instead of guessing.
We are treating documentation, examples, metadata, and agent-specific resources as part of the project’s effective interface to AI.
Capable coding models often do not need exhaustive API instruction.
Once they understand the project’s mental model and a small number of correctness-critical invariants, they can infer much of the rest from:
- ordinary language semantics;
- existing examples;
- type signatures;
- local code;
- familiar platform APIs.
The optimization target is therefore not:
Give the model everything it might need.
It is:
Give the model the few non-obvious facts it cannot safely infer, make those facts easy to retrieve, and verify that the model behaves correctly afterward.
This creates a pipeline:
mental model
→ canonical invariants
→ canonical idioms
→ ordinary inference
→ implementation
→ behavioral verification
The first priority is to install the smallest correct model of how the system works.
Do not begin with a feature inventory.
Ask:
What must the agent understand for unfamiliar code in this project to make sense?
The mental model should explain causal structure, for example:
ownership
→ lifetime
→ cancellation
→ cleanup
or:
source artifact
→ transformation
→ runtime interpretation
→ observable result
The model should let the agent infer consequences rather than memorize isolated rules.
A good mental model compresses many API facts into one reusable idea.
Assume a capable coding agent can infer:
- ordinary language syntax;
- loops and local control flow;
- common data structures;
- obvious TypeScript relationships;
- straightforward application glue;
- patterns directly visible in examples.
Spend documentation bandwidth on things it cannot safely infer:
lifecycle
scope
ownership
authority
effect boundaries
failure behavior
teardown ordering
replay
durability
cancellation semantics
resource lifetime
evaluation timing
lazy vs eager behavior
canonical integration patterns
Do not explain obvious syntax merely because documentation traditionally does so.
When several primitives can technically be combined to solve a problem, document the intended composition explicitly.
Agents are good at composition, but that becomes dangerous when correctness depends on non-obvious interactions between individually valid primitives.
For every important boundary, ask:
Is there one pattern we want agents to reach for by default?
If yes, show that exact pattern.
Prefer:
problem
→ canonical idiom
→ non-obvious semantic consequence
Avoid:
primitive A
primitive B
primitive C
→ agent must discover the safe composition itself
Especially document patterns where:
- cleanup ordering matters;
- cancellation crosses into a foreign API;
- a returned value can outlive an effect;
- scope boundaries change semantics;
- correct-looking code can silently violate an invariant.
When the project provides a higher-level helper or extension for a common case, use progressive disclosure.
Teach:
general mechanism
→ concrete native example
→ packaged convenience
For example:
lifetime
→ AbortSignal
→ Promise API
→ adapter
then:
If you do this frequently, package X already wraps the pattern.
Do not teach the convenience package in a way that prevents the agent from transferring the underlying rule to other APIs.
Examples are not decoration.
Agents generalize aggressively from examples, so every example teaches more than its prose says.
For every example, ask:
- What behavior will an agent infer from this?
- Is that inference correct beyond this example?
- Does it accidentally normalize an anti-pattern?
- Does it omit a required lifecycle or failure boundary?
- Does it use the current canonical API?
- Could an agent copy it literally and obtain correct behavior?
A stale example is particularly dangerous because models often trust executable-looking code more than explanatory prose.
Fix contradictory examples before adding more explanation.
Maintain a high-density agent resource such as AGENTS.md when useful.
Its job is not to duplicate the documentation.
Its job is to state the correctness-critical rules that an agent must not infer incorrectly.
Good content includes:
- core invariants;
- canonical terminology;
- important semantic distinctions;
- public APIs that should be preferred;
- APIs or patterns that must not be invented;
- anti-patterns;
- lifecycle rules;
- boundaries between values and effects;
- what to consult when uncertain.
Think of it as the smallest authoritative semantic kernel required for competent work in the project.
It should explicitly tell agents:
Ground claims in the public API. Do not invent APIs or import semantics from superficially similar ecosystems.
Correct documentation that cannot be found at the moment it is needed is still a failure.
For every recurring agent task, inspect the retrieval path:
problem
→ concept
→ documentation page
→ canonical idiom
→ API reference
→ optional extension
Minimize unnecessary hops.
Put concepts where a reader would look for the problem, not merely where the underlying implementation happens to live.
Examples:
- Promise interoperability belongs near Promise/Operation interop, not only on an advanced Scope page.
- Bounded concurrency should lead naturally to the package that provides bounded concurrency.
- A commonly used extension should be discoverable from the core concept it extends.
Do not reorganize documentation speculatively. Change information architecture only when observed agent behavior shows a discovery problem.
Do not evaluate success by asking:
Is this library easy to use?
or:
Would you recommend it?
Models carry ecosystem priors that can dominate these answers.
Instead give them realistic work.
Use tasks that force the relevant semantics to matter.
For example:
- cancellation during active I/O;
- sibling failure;
- nested resource ownership;
- partial-file cleanup;
- bounded concurrency;
- signal handling;
- context propagation.
Then measure:
- Did the agent choose the intended primitives?
- Did it invent APIs?
- Did it write custom infrastructure that a canonical idiom makes unnecessary?
- Did it violate lifecycle semantics?
- Did it inspect implementation source?
- Did it need empirical reverse-engineering?
- Did tests expose silent correctness bugs?
- How much project-specific knowledge was actually required?
Observed behavior is stronger evidence than self-reported preference.
Models may evaluate an unfamiliar project pessimistically before using it while performing very well once they have the mental model.
Test these separately.
Ask what the project is and what problem it solves.
Give the problem without naming the project.
Does the project enter the candidate set?
Give the project documentation and a novel implementation task.
Can the model use it correctly?
Only after implementation, ask:
- How difficult was the mental model?
- How difficult was discovering the idioms?
- How difficult was writing the application?
- How difficult was debugging?
- Which costs recur?
- Which were one-time?
Do not ask these questions before implementation. That primes the evaluator.
Do not continue educating one agent and then treat later performance as a cold evaluation.
A model cannot unlearn facts from earlier in the conversation.
For meaningful tests:
- start a fresh session;
- provide only the information available to a real user/agent;
- do not reveal the hypothesis;
- do not tell it what mistake previous agents made;
- do not correct it while it works;
- save the complete transcript.
When possible, repeat the same task across different model families.
Convergence matters more than any one result.
When an agent struggles, classify the failure.
The agent misunderstood how the project fundamentally works.
Likely response:
- improve the conceptual explanation;
- reorder the curriculum;
- improve the first example.
The right API or idiom exists but the agent could not find it.
Likely response:
- improve cross-links;
- move the canonical example;
- expose the extension from the relevant concept;
- improve agent indexes.
The material is incorrect, contradictory, stale, or incomplete.
Likely response:
- fix the exact incorrect example or invariant.
Multiple strong agents understand the model and documentation but independently compose the API incorrectly in the same way.
Do not immediately assume this is documentation.
Repeated failure after documentation improvement is evidence that the API shape itself may permit an unsafe composition too easily.
Escalate this separately for product/API consideration.
The agent understands the design but dislikes generators, ecosystem size, typing model, etc.
Do not rewrite documentation merely to eliminate correctly understood disagreement.
One strange output is noise.
Repeated independent failure is signal.
Make a change when:
- multiple agents form the same incorrect mental model;
- multiple agents invent the same unnecessary abstraction;
- multiple agents miss the same canonical package;
- multiple agents hit the same teardown/cancellation bug;
- the same API interaction repeatedly requires source inspection;
- a critical fact is repeatedly learned only through experimentation.
Do not optimize against every hallucination an individual model produces.
When an agent fails to find or understand something, first ask whether the solution is:
- moving an example;
- improving a link;
- placing the concept earlier;
- removing a stale example;
- naming one canonical idiom;
- linking a core concept to an extension;
- strengthening
AGENTS.md.
Do not reflexively add paragraphs.
The best fix often reduces inference distance rather than increases text volume.
Treat documentation work experimentally.
If agents repeatedly fail at:
mental model
→ Promise boundary
→ teardown ordering
→ extension discovery
do not fix all four simultaneously.
Instead:
change A
→ fresh agent
→ same task
→ observe
Then decide whether change B is still necessary.
This preserves causal information.
Otherwise you may improve behavior without learning why.
Whenever possible, rerun exactly the same implementation task after a documentation intervention.
Do not make the test easier.
Compare:
before:
mental model ✓
canonical idiom ✗
custom abstraction
debugging
source inspection
after:
mental model ✓
canonical idiom ✓
implementation
tests pass
This gives much stronger evidence than asking whether the new documentation “looks clearer.”
A program that looks structurally correct may still violate lifecycle guarantees.
Require behavioral tests for non-obvious properties:
- work stops after cancellation;
- no side effects occur after shutdown reports completion;
- cleanup finishes before parent completion;
- partial resources disappear;
- concurrency limits hold;
- sibling failures propagate correctly;
- no orphan task keeps the process alive.
Tests are part of the agent-training environment because they provide feedback where static reasoning is insufficient.
This distinction is essential when evaluating adoption difficulty.
Ask agents to separate:
mental-model acquisition
API/idiom discovery
application implementation
debugging
foreign-API integration
Then ask which costs recur.
A project can have:
high first-task discovery cost
+
very low subsequent-task cost
That is different from a programming model whose complexity taxes every line of code.
Do not collapse both into “learning curve.”
Once the agent has the mental model and canonical idioms, do not over-train it.
The desired state is:
small authoritative context
+
general programming ability
=
correct project-specific implementation
If documentation has to prescribe every common application pattern, the conceptual model is probably not doing enough work.
The strongest signal is when an agent says, in effect:
I needed only a handful of project-specific facts; the rest followed from the model and ordinary JavaScript.
A successful progression often looks like:
early:
"I don't understand what this does."
later:
"I understand it but cannot find the correct idiom."
later:
"I found the idiom but this boundary is underspecified."
later:
"I can use it correctly, but I dislike the tradeoff."
Each transition means the earlier layer is increasingly healthy.
Do not keep changing the homepage to solve documentation problems.
Do not keep changing documentation to eliminate legitimate product objections.
Every evaluation finding belongs in one of:
Homepage / positioning
Core documentation
API reference
Agent resources
Examples
Extension discovery
API design
Product design
Testing/tooling
Research
Do not use copy to hide an API problem.
Do not redesign an API merely because one agent failed to find documentation.
We are not trying to persuade an AI that the project is good.
We are trying to create an environment in which a capable agent can independently reconstruct the project’s actual design and behave correctly.
The desired relationship is:
project architecture
↓
authoritative mental model
↓
small set of invariants
↓
canonical examples
↓
agent inference
↓
correct behavior
Documentation should train behavior by making the correct reasoning path short, authoritative, and repeatable.
For every documentation or information-architecture change, report:
-
Observed agent failure
- What did one or more agents actually do wrong?
-
Failure category
- Mental model, discovery, documentation defect, API design, or tradeoff?
-
Required knowledge
- What exact fact was missing?
-
Current location
- Where is that fact currently documented, if anywhere?
-
Best conceptual owner
- Where would an agent naturally look for it?
-
Smallest intervention
- Link, move, example correction, canonical idiom, agent rule, or something else?
-
Do-not-change boundary
- What nearby documentation is already doing its job?
-
Retest
- What exact previous task should be rerun with a fresh agent?
Do not recommend broader changes until the smallest intervention has been tested.