Problem Statement

Technical specifications -- from W3C Recommendations to API documentation to sustainability guidelines -- are written for human developers. They use natural language prose, rely on contextual understanding, assume knowledge of intent, and often require professional judgment to interpret and apply correctly.

AI coding assistants and autonomous agents are now a primary interface between specifications and implementation. When a developer asks an AI assistant to "build a form," the assistant draws on patterns learned from training data, not from the current version of the HTML specification or WCAG success criteria. The result is code that reflects the statistical distribution of the training corpus -- which, as documented by [[WEBAIM-MILLION]] and [[WEB-ALMANAC-A11Y]], is overwhelmingly non-compliant with existing standards. The Web Almanac 2025 reports that automated testing tools can only check a subset of WCAG Success Criteria, and comparative audits show that all major tools detect fewer than 50% of accessibility errors. When 95.9% of homepages fail WCAG 2.2 Level A/AA and the average page contains 51 accessibility errors, the training corpus itself encodes non-compliance as the default.

The Feedback Loop Problem

[[DEAD-FRAMEWORK]] identifies a self-reinforcing feedback loop in AI-mediated web development. The analysis, focused on framework adoption, describes two interlocking cycles:

Loop 1 (training data): Dominant patterns on the existing web enter LLM training corpora. LLMs output those dominant patterns by default. New sites built with LLMs reproduce those patterns. The expanded corpus reinforces the same patterns in future training cycles.

Loop 2 (tooling): Coding tools hardcode specific frameworks and patterns into their system prompts. Developers expect those patterns. Tools that deviate lose market share. System prompt choices become self-fulfilling.

Although [[DEAD-FRAMEWORK]] analyses this dynamic for JavaScript frameworks (specifically React's dominance), the same structural problem applies to any normative requirement that is underrepresented in training data. Accessibility patterns, sustainability practices, new web platform APIs, and updated specification requirements all face the same barrier: if the correct pattern is not statistically dominant in the training corpus, the AI system will default to the incorrect pattern it learned from the majority of examples.

The Web Almanac 2025 accessibility chapter explicitly names this risk: there is no reliable way to determine when AI has created or assisted in creating a website, and language models are trained on code and content that often contain accessibility problems [[WEB-ALMANAC-A11Y]]. This means AI systems are not merely failing to improve accessibility -- they risk actively reproducing and scaling existing failures.

A critical additional factor is the system prompt layer. As [[DEAD-FRAMEWORK]] documents, coding tools such as Replit and Bolt explicitly hardcode framework choices into their system prompts. The system prompt overrides both training data and user preferences. There is currently no standard for declaring what a coding tool's system prompt contains, no mechanism for specification authors or standards bodies to request inclusion of normative requirements, and no transparency about what patterns are being privileged or suppressed. This governance gap means that even well-written, machine-consumable specifications may not reach the AI system if the tool provider's system prompt does not include them.

Specifications written solely for human developers cannot break these loops. The requirements must be available in forms that AI systems can operationalise during code generation -- through training data, through context injection at inference time, and through post-generation validation.

Scope

This document addresses the authoring of specifications and guidelines intended for consumption by AI code generation systems. It does not address AI training methodology, model architecture, or the broader question of AI alignment. It focuses on the document layer -- what specification authors can do to make their normative requirements actionable by AI systems at inference time. It also identifies systemic barriers (training data lag, system prompt governance) that limit the effectiveness of any single specification and proposes strategies to address them.

The companion document, Accessibility and Sustainability Principles for AI Code Assistants, applies these guidelines to two specific domains.

Training Data Lag

AI models have a knowledge cutoff determined by when their training data was collected. New specifications, updated APIs, and revised guidelines may not appear in model outputs for 12--18 months after publication. This lag means that even well-written specifications may not reach AI systems through training alone.

Strategies to address this lag include runtime documentation retrieval (via [[CONTEXT-HUB]], MCP documentation servers, or [[LLMS-TXT]]), but these require specifications to be available in machine-consumable formats -- which most are not.

The Comprehension Gap

Human specifications rely on several cognitive capabilities that AI systems approximate but do not reliably possess:

Intent comprehension: Understanding why a requirement exists, not just what it says. A human developer reads "provide text alternatives for non-text content" and understands this enables screen reader access. An AI system may associate alt attributes with images statistically without understanding the purpose.

Contextual judgment: Determining whether a requirement applies in a given situation. Many WCAG success criteria require human assessment of whether content is "meaningful," headings are "logical," or focus order is "intuitive."

Cross-reference resolution: Connecting requirements across multiple documents. A specification may reference normative terms defined elsewhere, assume knowledge of related specifications, or depend on understanding of the broader standards ecosystem.

Professional discretion: Choosing among multiple valid approaches based on context. Specifications often describe what must be achieved without prescribing a single implementation, expecting the developer to exercise judgment.

The Format Gap

Specifications are published in formats optimised for human reading: HTML with complex navigation, PDF documents, prose-heavy W3C Recommendations with examples embedded in running text. These formats present several obstacles for AI consumption:

Normative requirements are embedded in explanatory prose and not easily extractable. Examples may appear far from the requirements they illustrate. The distinction between normative ("MUST") and informative text is conveyed through typographic convention rather than machine-readable structure. Version information may be ambiguous or absent from the document itself.

Express Requirements as Constraints, Not Aspirations

AI systems operate more effectively with constraints (rules that can be checked) than with aspirations (goals that require judgment). Where possible, specification authors should reformulate aspirational requirements as verifiable constraints.

Aspirational: "Content should be perceivable by all users."

Constraint: "Every <img> element MUST have an alt attribute. Decorative images MUST use alt="". Informative images MUST have alt text that describes the image's communicative function in context, not its visual appearance."

Not all requirements can be reduced to constraints. Where professional judgment is required, the specification should say so explicitly and describe the judgment criteria as concretely as possible.

Include Negative Examples

AI systems learn effectively from counter-examples. Every requirement should be accompanied by at least one "DO NOT" example alongside the correct pattern. These negative examples should represent common failure modes observed in real-world code -- the patterns that LLMs are most likely to reproduce from training data.

The [[AIMAC]] benchmark provides a rich source of real failure modes across 28 code generation categories that can inform negative example selection.

Provide Machine-Readable Requirement Blocks

Alongside human-readable prose, specifications should include structured, extractable requirement blocks. These blocks should use a consistent format that AI systems can parse, containing: a unique requirement identifier, the normative level (MUST, SHOULD, MAY), the requirement text as a machine-checkable rule where possible, and references to automated test procedures where they exist.

A suggested format (to be refined through community review):

{
  "id": "REQ-IMG-ALT-001",
  "level": "MUST",
  "scope": "html:img",
  "rule": "Every img element has an alt attribute",
  "test": "axe-core:image-alt",
  "counter-example": "<img src='photo.jpg'>",
  "correct-example": "<img src='photo.jpg' alt='A researcher presenting findings at a conference'>",
  "rationale": "Screen readers announce images using alt text. Without it, the image is invisible to non-visual users."
}
      

Publish Agent-Consumable Summaries

Every specification should publish a companion document in a format optimised for AI consumption. This may take the form of an [[LLMS-TXT]] file, an MCP documentation server, a Context Hub entry ([[CONTEXT-HUB]]), or a dedicated skill file. The companion document should contain:

A concise summary of the specification's purpose and scope. All normative requirements in constraint form. Positive and negative code examples for each requirement. Version and last-updated metadata. References to automated testing tools that can verify compliance.

Version Explicitly for Training-Data Lag

Specifications should include clear version metadata and, where requirements have changed between versions, explicit "what changed" blocks. This helps AI systems that may have learned an earlier version of the specification to identify and correct outdated patterns.

A "migration guide" section, formatted as a set of find-and-replace transformations, is particularly effective for AI consumption. For example: "In version 2.1, user-scalable=no was not explicitly addressed. In version 2.2, viewport restrictions that prevent zooming are a Level AA failure. If generating viewport meta tags, do not include user-scalable=no or maximum-scale=1."

Link Requirements to Automated Tests

Where automated tests exist for a requirement (e.g., axe-core rules for WCAG, Lighthouse audits, sustainability metrics), the specification should reference them directly. This allows AI systems to include post-generation validation as part of their workflow -- generating code, testing it against the linked rules, and correcting failures before presenting output.

Structure for Selective Retrieval

AI systems operate within context window limits. Specifications should be structured so that relevant sections can be retrieved independently without requiring the full document. This means: self-contained requirement sections, minimal cross-document dependencies within individual rules, and clear section-level metadata enabling targeted retrieval via MCP or similar protocols.

Training Data

The specification enters the model's weights during training. This is the most persistent channel but has 12--18 month lag and no version control. Authors cannot control how the specification is represented in training data.

Context Injection at Inference Time

The specification (or a summary) is provided to the model at runtime via system prompts, skill files, MCP servers, [[CONTEXT-HUB]], or [[LLMS-TXT]]. This channel is current, version-controlled, and authoritative, but requires the tool or developer to configure retrieval. This is the most promising channel for normative specifications.

Post-Generation Validation

The AI system generates code and then tests it against automated rules derived from the specification. Failures trigger self-correction. This requires specifications to reference or provide machine-executable test suites.