SUMMARY:
AI DX Infrastructure turns general-purpose AI into a project-aware coding partner that writes better code, follows your standards, and saves real money on tokens.
Table of contents
AI DX Infrastructure — So What Exactly Is That?
DX means Developer Experience. The set of AI-related files in a programming project — skills, custom agents, docs, custom lint rules, and so on — can be called AI DX Infrastructure to distinguish it from general AI Infrastructure, which, for many people, brings to mind cloud infrastructure, DevOps, etc. In contrast, AI DX Infrastructure is the set of markdown, configuration, and code files that enhance the Developer Experience of a project by giving the AI superpowers, or at least a bit more intelligence than it would have without them.
Other names for AI DX Infrastructure include “AI System,” which seems a little generic. Karpathy’s gist refers to a concept similar to an “LLM Wiki.” For this article, we’ll use the term “AI DX Infrastructure”-this is not yet an industry-standard term.
Using an IDE such as VS Code with an AI extension such as Copilot, Claude, or Codex is a powerful combination of tools that can completely transform how you write code.
AI in the hands of amateurs produces vast quantities of unmaintainable slop: instant tech-debt the moment it was generated. On top of that, carelessly used AI can be very expensive in both tokens and dollars. The sky is the limit in terms of how much you could conceivably spend.
In contrast, mindfully setting up AI DX Infrastructure can:
- Help AI guide a human to write better code
- Help a human guide AI to write better code
- Help an AI zero in on best practices or patterns much sooner
- Conserve tokens and therefore save real money
But setting AI DX up is just the beginning. We need to build a developer culture in which updating the AI DX Infrastructure is as routine as writing unit tests for new code. Each time we use AI to do something, and it makes a mistake, it’s an opportunity — an opportunity to explore the existing infrastructure, correct it, and expand it to at least attempt to prevent the same mistake from happening again.
The AI-Correction Feedback Loop
Turning Friction into Infrastructure
In a standard workflow, when an AI makes a mistake, the developer’s instinct is to manually fix the code and move on. This is a missed opportunity. In an AI DX Infrastructure model, every AI error is treated as a system failure that requires a permanent fix in the Intelligence Layer. By treating your docs, skills, custom agents, etc., as a portable Intelligence Layer, you ensure the AI converges on your professional standard more reliably over time. This transforms the AI from a generalist into a specialized extension of your own engineering philosophy.
The Anatomy of the Intelligence Layer
To build a robust AI DX infrastructure, we organize our AI-related files into functional ‘systems’ that compose the project’s Intelligence Layer. This structure ensures the AI moves beyond generating generic code and instead operates as a specialized extension of your unique architectural DNA.
1. The Skeleton (Enforcement)
Components: tsconfig.json, lint configs, Custom Lint Rules, and potentially other static code analysis tools.
Function: This is the rigid structure. It provides the “hard” guardrails that physically prevent the AI from generating “slop.” If the skeleton is weak (e.g., permissive types), the entire output collapses. Strict rules make AI-generated code easier to constrain, validate, and correct. Additionally, strict rules are easier for humans to follow when AI helps guide them.
Custom lint rules take this to the next level, and have the additional benefit that custom messages in the custom lint rules signal to the AI what it is doing wrong and what it can consider doing instead. The barrier to writing custom lint rules is now much lower with the help of generative AI.
2. The Central Nervous System (Global Directives)
Components: copilot-instructions.md, .cursorrules, AGENT.md.
Function: This is the “brain.” It handles conscious, high-level decision-making. It tells the AI who it is and how it should generally behave across the entire project.
However, be aware: just as the biological nervous system uses synaptic pruning to clear out weak connections between neurons, these files (and skills and custom agents) must also be frequently pruned over time as more and more are added to them.
These files are often loaded directly into the AI context for every request and, therefore, must be extremely slim, or AI performance can degrade significantly. Ideally, these global AI files should be no more than 50-150 lines of text. Think of these files as quick indexes whose primary job is to point out the existence of skills, docs, custom agents, and so on.
3. The Autonomic Nervous System (Local Context)
Components: “Why” comments within the source code. Also: descriptive symbol names that follow naming conventions.
Function: These are the “reflexes.” Just as your autonomic system controls your heart rate without you thinking about it, high-quality “Why” comments provide just-in-time, localized instructions that guide the AI’s immediate “reflex” when editing a specific function. They ensure the AI doesn’t break an intentional edge case or misinterpret a complex logic gate during a quick refactor. Do not waste tokens on useless “What” comments that explain what the code is doing. The AI can already figure it out, and it’s just noise that clogs context and degrades the AI’s capabilities.
Symbols with non-obvious “Why” use JSDoc to help both humans and AI understand. In TypeScript files, do not waste tokens in JSDoc comments to describe types. That’s a form of “What?” The AI already knows how to get types in TypeScript files.
The Key Differences between “What” and “Why” Code Comments
| Feature | “What” | “Why” |
|---|---|---|
| Focus | Syntax and Execution | Intent and Constraints |
| Audience | Beginners / Junior devs | Your Future Self / Specialized AI |
| AI Impact | Noise; leads to generic code | Signal; leads to “DNA-aware” code |
| Value | Low (code should be self-documenting) | High (logic is often invisible) |
Systematic and descriptive naming for symbols (variables and functions) is also strongly recommended. Here are some examples of symbol naming conventions:
| Prefix | Category | Signal to AI |
|---|---|---|
compute* | Heavy Logic | “This is a calculation; handle with care regarding performance.” |
fetch* | Network | “This is async; expect latency and handle errors.” |
is* / has* | State / Fact | “This is a binary condition for logic gates.” |
should* | Intent | “This is a configuration or preference.” |
ensure* | Side-effect | “This function guarantees a state; it might mutate or initialize.” |
4. The Motor Skills (Actionable Capabilities)
Components: Custom Skills, specialized Custom Agents, and automation scripts.
Function: This is how the AI interacts with your specific environment. Enables AI to execute complex, domain-specific tasks.
Skills should be extremely slim — not much more than 200-300 lines of text each. Therefore, skills should mostly be very brief mentions of topics, with deep links to the relevant doc and/or to lower-level skills. Skills can be hierarchical: a higher-level skill can point to lower-level skills, which can point to even lower-level skills, etc. It helps to pair skills with a doc of the same name, and to deep-link (with root-relative links with # anchors) from that skill into the doc.
Custom agents also have their own best practices. One key point about a custom agent is that it defines the set of tools available to the AI that uses it. These custom agents are no longer manually selected by a human for an AI to use. Nowadays, a higher-level agent can automatically set up subagents for a project’s custom agents, depending on your project’s settings and trust levels.
5. The Memory (Contextual Knowledge)
Components: Docs, Architectural Decision Records (ADRs), Technical Specs.
Function: This is the deep storage. It provides the “Why” behind the “What.” By referencing past decisions and project history, the AI avoids architectural regression and remains aligned with the project’s long-term vision.
Docs in markdown format can be quite large—ideally, not much more than 1000 lines. They are generally not shoved into an AI’s context all at once; instead, bits of them are intelligently inserted into it under the hood using RAG (Retrieval-Augmented Generation). This means there is really no downside to being as descriptive and explicit as possible in your docs, as long as they are internally consistent, well-structured, and indexed with a Table of Contents.
“Decision trees” inside docs are especially valuable — they help the AI (and any human reading) systematically discover best practices or patterns.
Do not let your docs get stale! If you, as a human, don’t have time to periodically review them to keep them up to date and self-consistent, at least use AI to do that. Bad docs are a frequent cause of AI degradation.
Remember: your custom agents, skills, docs, etc., can only help nudge AI to converge toward best practices non-deterministically. If you can refactor your idea using custom lint rules or static code analysis, that is really the only way to guarantee 100% deterministic best practices — and it will save you time and tokens too.
6. The Immune System (Validation)
Components: Unit Tests, Integration Tests, E2E Tests.
Function: This is the project’s defense mechanism. Like white blood cells, it identifies and “attacks” foreign or malformed code (hallucinations) before they can integrate into the project’s body. A failing test is a signal that the Intelligence Layer needs more clarity to prevent the same mistake from recurring.
The most important value of automated testing is not so much that it can find and prevent bugs, but that it provides a deeper, richer intelligence layer for the AI to learn from. Tests also provide an excellent and relatively safe opportunity to use generative AI code to the max — AI set loose on a project building automated Playwright integration tests has been known to find real bugs that QA teams had not yet discovered.
Conclusion: The Maturity of the Intelligence Layer
AI DX Infrastructure is not a one-time configuration, but a fundamental shift in how we maintain architectural integrity. By organizing our project around these anatomical systems, we move from reactive fixes to proactive infrastructure.
- From Slop to Standard: We treat every AI hallucination or logic error as a signal that our “DNA” — the Intelligence Layer — is incomplete.
- The Compounding Effect: As the Autonomic Nervous System (comments/naming) and Memory (docs/ADRs) grow, the AI’s performance doesn’t just improve; it converges on your specific professional standard.
- The Far Path: Ultimately, this discipline enables a state where the AI acts as a high-fidelity partner capable of “Zero-Cost Refactoring” and autonomous feature parity, safely guarded by the project’s Immune System (tests). The goal of this infrastructure is to ensure that our tools are as sophisticated as the problems we are solving. We don’t just write code anymore; we build the systems that write code correctly.
- Horizontal Gene Transfer: The Intelligence Layer is portable. Successful architectural patterns and AI-correction loops developed in one project become the “Conserved DNA” for the next, ensuring that your entire portfolio evolves at a compounding rate.