# json_shield: Engineering an AI-Ready Dart Package > Source: > Published: 2026-07-16 08:37:03+00:00 Code generation has shifted. The majority of code calling a new pub.dev package is no longer typed by a human reading the documentation; it is generated by LLMs (Copilot, Cursor, Claude) operating within an IDE. If an AI assistant hallucinates your API, the human developer will blame your package and remove it. Building a package in 2026 requires engineering for two distinct consumers: the compiler and the LLM context window. This post details the architecture of making `json_shield` AI-ready. It deconstructs the four artifacts that reach a consumer's AI, the one artifact that steers a contributor's agent, and the deterministic rules for writing them. When a developer prompts an assistant to "use json_shield to parse this response", the LLM does not browse the repository. It relies on Retrieval-Augmented Generation (RAG) and its pre-trained weights. Because the package is new, pre-trained weights are zero. You control exactly four artifacts that the IDE's RAG pipeline will index and inject into the prompt context. A README is no longer a sales pitch; it is the primary context injection for an LLM. LLMs prioritize code blocks and structural formatting over prose. **The Rule:** Optimize for token density. `json_shield` 's README explicitly states: "No HTTP, no retries, no code generation." This prevents the model from attempting to chain `guard.decode` into a `Dio` interceptor pipeline that doesn't exist.`example/` Directory: The Integration Vector The IDE's language server indexes the `example/` folder. When an AI agent searches the local workspace for usage patterns, this folder is the highest-weight reference. **The Rule:** The example must be a self-contained, compilable representation of the exact production use case. Do not write synthetic `Foo` /`Bar` examples. `json_shield` provides a full mock HTTP response, a standard `quicktype` generated model, and the exact try/catch block for aggregate error reporting. The AI copies the structural logic from here, not the README. `///` ): Inline RAG Injection When a user hovers over a method or an AI agent requests definitions, the Dart analyzer extracts the `///` comments. **The Rule:** Doc comments must dictate the contract and the failure mode. A comment like `/// Decodes the JSON` is zero-value data. The LLM needs to know the type constraints and exceptions. ``` /// Decodes a single object from a JSON map. /// Throws [DecodeException] if the [data] shape mismatches the expected input /// before [factory] is invoked. /// Set [guard.verbose = true] to print payloads to the console. ``` This forces the AI to wrap the call in a `try/catch` specifically targeting `DecodeException` , preventing generic `catch (e)` block generation. `pubspec.yaml` Description: The Search Heuristic The 255-character description is the primary string indexed by pub.dev's search and external web scrapers. Do not use it for branding. Use it as an array of technical keywords. `json_shield` description: "A zero-dependency structural guard for fromJson factories. Turns anonymous map casting crashes into actionable, typed error reports with stack traces." When another developer forks your repository to add a feature, they will likely use an agentic IDE (like Cursor) to write the PR. Left unconstrained, the agent will introduce external dependencies or break your architectural rules because doing so is statistically common in its training data. `rules.md` / `.cursorrules` Artifact You must provide a machine-readable directive file in the root directory. This acts as a system prompt override for any agent modifying the codebase. For `json_shield` , the constraints defined in Part 1 are codified as hard rules: ``` # Architecture Constraints - Zero dependencies. Do not add packages to pubspec.yaml. - Pure Dart. Do not use flutter or dart:ui imports. - No code generation. - All modifications must preserve the exact argument order in public APIs: (factory, json). ``` When an agent is prompted to "add an HTTP client to fetch the schema," this file forces it to reject the prompt, citing the zero-dependency architecture. API design is no longer just about human ergonomics; it is about machine predictability. A package that is easy for an LLM to parse, index, and generate accurate code for will achieve adoption. A package that relies on human intuition to fill the gaps in its documentation will fail at the generation step. Define the rules, strip the context overhead, and write machine-readable context.