Перейти к основному содержимому

Agent Experience (AX) surfaces

Five derived surfaces make the repo consumable by coding agents: a root AGENTS.md contract, raw-markdown doc variants with Accept negotiation, an /llms.txt…

Agent Experience (AX) surfaces

Generated from pattern-library/registry.json — do not edit by hand; change the registry and run bun run patterns:build.

Category: Docs & Agent Experience · Tier: deep · Maturity: proven (verified 2026-10-10 @ 91f61a76-dirty) · Risk: low — read-only derived surfaces; no new state

Five derived surfaces make the repo consumable by coding agents: a root AGENTS.md contract, raw-markdown doc variants with Accept negotiation, an /llms.txt URL map with in-band prior corrections, MCP tool errors that carry machine-actionable recovery steps, and a generated pattern library (README index + per-pattern docs pages) rendered from the pattern registry.

When to use: Adopt when a repo's primary consumers are AI agents: it turns passive docs into addressable, self-correcting surfaces without any hand-maintained duplicate content.

Avoid when

  • Docs read only by humans or crawlers — Search ignores llms.txt; these surfaces serve agents already fetching the repo
  • No single source of truth to derive from — a hand-synced llms.txt or markdown corpus drifts (Astro removed its llms.txt over that)
  • Docs not served over HTTP — the .md layer, Accept negotiation and /llms.txt need a published docs site; AGENTS.md covers a clone

Alternatives

  • AGENTS.md plus an advertised /llms.txt only — prefer when there is no MCP surface yet — they are the standards that won adoption and the cheapest start
  • An llms-full.txt size ladder — prefer when a framework with millions of consumers can afford to maintain a second, full-text corpus

Docs

Code

  • AGENTS.md — Universal agent contract at the repo root (GitHub · GitLab)
  • src/lib/server/docs/markdown.hook.ts — The .md layer + Accept: text/markdown negotiation (303 + Vary + no-store) (GitHub · GitLab)
  • src/lib/server/docs/llms-txt.ts — /llms.txt built per request from the docs manifest (GitHub · GitLab)
  • src/lib/server/mcp/snippet/engine.ts — validate_snippet rule engine (findings are a success; input never echoed) (GitHub · GitLab)
  • scripts/patterns/build-derived.ts — Pattern-library generator (README region + per-pattern pages) (GitHub · GitLab)
  • src/lib/docs/heading-anchors.server.ts — The one heading slugger: validator, README TOC and rendered page agree (GitHub · GitLab)

Tests

Proof

Invariants

  • Every surface is derived — llms.txt from the docs manifest, .md bodies from the published registry, tool cards from shared JSON, the README Pattern Index and /docs/pattern-library pages from the pattern registry; none is hand-maintained.
  • Every registry-produced MCP error carries a required diag code AND a Next-actions recovery trailer — a new error branch without them is a compile error.
  • Content negotiation is 303 + Vary: Accept + no-store; each cacheable artifact lives at exactly one URL.
  • Tool results are text-only and never echo caller input beyond the bounded id reflection.
  • Instruction files route only to paths that exist and carry no hidden bidi or zero-width characters — a gate, not a review habit; a path named as absent on purpose is an allowance that fails when it goes stale.
  • Every registry #fragment resolves to a heading the page renders, checked through the renderer's own slugger.

Emulation notes

  • Start with AGENTS.md and llms.txt — the standards that won adoption — and advertise them in-page/headers; an unadvertised llms.txt is dead weight.
  • Make recovery hints structural (a required parameter on the error constructor), not a style guideline reviewers must remember.

Depends on

Machine-readable record: agent-experience in pattern-library/registry.json.

← Back to Pattern Library

Думаете, этот паттерн можно сделать лучше? Расскажите как.

Оставить отзыв