How to Align AI Coding With Shared Domain Docs

TL;DR

Combine relentless AI interviewing with lightweight domain documentation so the coding agent can reuse shared terminology instead of repeatedly asking what project-specific concepts mean. A context.md glossary captures the language shared by code, developers, and domain experts, while architectural decision records preserve surprising, consequential choices that are difficult to reverse.

Transcript

A few months ago, I wrote a few sentences, about four sentences, that have turned out to be the most influential four sentences I've ever written. I packaged these four sentences up into the Grill Me skill, which is a skill that you can use to get the LLM to interview you relentlessly. It interviews you until you reach a shared understanding, walki... Read More

Key Insights

• Grill Me is an interviewing skill that questions the developer until the developer and AI reach a shared understanding, walking through branches of the design tree and resolving dependencies between decisions before implementation begins.
• The main weakness of Grill Me is that non-obvious knowledge about the codebase and its domain must often be explained again, while useful terminology developed during an interview can disappear because it is not recorded anywhere.
• Ubiquitous language is a shared vocabulary used consistently by the codebase, developers, and domain experts, allowing each group to refer to the same concepts without translating between conflicting or overly verbose descriptions.
• A context.md file is the lightweight documentation layer used to preserve domain terminology, including exact definitions for concepts such as a standalone video, which the repository defines as a video whose lesson ID is null.
• Grill with Docs is the combination of the original relentless interview process and documentation-aware language refinement, enabling the AI to inspect existing definitions, challenge fuzzy wording, discuss examples, cross-reference code, and update documentation during the session.
• A bounded context is a part of an application within which one shared language applies, so a large monorepo can use a context map with multiple contexts while a single-language repository can keep one context.md at its root.
• Architectural decision records are simple Markdown files for non-obvious choices that are difficult to reverse, surprising without context, and produced by genuine trade-offs whose consequences affect later work in the repository.
• Shared documentation reduces the number of words needed to align with an AI coding partner because definitions and prior decisions carry across sessions, and repeated use can help the agent anticipate concepts that previously required lengthy explanation.

Questions & Answers

Q: Why does Grill Me become inefficient for coding projects?

Grill Me can establish a strong shared understanding during one interview, but it does not preserve that understanding by itself. The developer may repeatedly explain project-specific terms, domain assumptions, and non-obvious codebase concepts in later sessions. Even when the developer and agent discover precise language together, that vocabulary can be lost if it is not written into repository documentation.

Q: What is Grill with Docs and how does it work?

Grill with Docs extends the Grill Me interview process with repository documentation. It first looks for an existing context.md file containing shared domain language. During the conversation, it compares wording with the glossary, challenges unclear terms, explores concrete scenarios, cross-references concepts with the code, and updates the documentation as the developer and AI reach clearer agreements.

Q: What should a context.md file contain for AI coding?

A context.md file should contain the shared language used by the application, its developers, and the domain experts who understand the problem being solved. It can briefly describe the repository and define important entities and relationships, such as courses, course repositories, course versions, and standalone videos. Exact definitions give future AI sessions reusable context without requiring repeated explanations.

Q: How does ubiquitous language improve AI coding sessions?

Ubiquitous language gives the developer, domain experts, source code, and AI agent the same names for the same concepts. This reduces verbose explanations and exposes terminology conflicts before they influence implementation. When the agreed language is documented and reused, the AI can understand project-specific requests more quickly and align its questions with definitions established during earlier sessions.

Q: How should shared domain documentation scale in a monorepo?

A large monorepo can use multiple bounded contexts, with each context representing a part of the application that speaks its own shared language. A context map can identify those separate areas and their documentation. If a repository is fairly large but the entire application and its domain experts still use one vocabulary, a single context.md at the repository root can be sufficient.

Q: When should an architectural decision record be created?

An architectural decision record should be created for a choice that is difficult to reverse, would seem surprising without its background, and reflects a real trade-off with downstream consequences. It is not necessary when two options, such as interchangeable libraries, can be swapped easily later. The purpose is to preserve reasoning that a terminology glossary alone cannot adequately express.

Q: Why should language be clarified before implementation details?

Terminology choices can determine how entities relate and how later implementation decisions are framed. In the demonstration, the agent first asks whether one pitch can hold many standalone videos or corresponds to exactly one. It also identifies a collision in the meaning of standalone video. Those answers can influence data relationships, interface sections, and whether pitched and unpitched videos appear together.

Q: How do context.md and ADR files serve different purposes?

A context.md file defines the domain language shared across the codebase, developers, and domain experts, including the meaning of entities and recurring terms. ADR files preserve the reasoning behind consequential architectural choices that are hard to reverse or surprising without context. Used together, they document both what project concepts mean and why important design decisions were made.

Summary & Key Takeaways

• The original Grill Me skill interviews a developer until both sides reach a shared understanding, resolving ambiguities and dependencies across the design tree. Its weakness is that project-specific terms and valuable language agreements may need to be explained again in later sessions because the resulting understanding is not automatically documented for reuse.

• The replacement, Grill with Docs, combines the interviewing process with a context.md document inspired by ubiquitous language and bounded contexts. It checks existing definitions, challenges fuzzy terminology, tests language against concrete scenarios, cross-references the code, and updates the glossary as new concepts become clear during development conversations.

• Architectural decision records complement the glossary by documenting non-obvious decisions that context.md cannot capture. An ADR is appropriate when a choice is difficult to reverse, surprising without context, and based on a meaningful trade-off with downstream consequences. Together, glossaries and ADRs help later AI sessions recover both terminology and design reasoning.