Engineering Precision: Leveraging /grill-with-docs for Domain-Driven Design and ADR Generation in Claude Code

In the rapidly evolving landscape of AI-augmented software engineering, the primary bottleneck is no longer code generation speed, but the fidelity of context. When utilizing agents like Claude Code or Cursor Composer, the "garbage in, garbage out" principle is amplified. A vague project description leads to architectural drift, inconsistent terminology, and ultimately, a codebase that fails to meet the client's original intent.

To combat this, a new specialized skill, /grill-with-docs (developed by Matt Pocock), has emerged as a successor to the popular /grill-me skill. Unlike standard "plan mode" features in AI agents, which often focus on immediate implementation steps, /grill-with-docs focuses on the foundational layer of software engineering: Domain-Driven Design (DDD) and the establishment of a Ubiquistic Language.

The Problem: Semantic Ambiguity in AI Prompting

When developers receive project descriptions—such as those found on Upwork—the text is often riddled with semantic ambiguity. A client might use the terms "photos," "letters," and "documents" interchangeably. To a human developer, the context might imply they are the same; to an AI agent, these are three distinct entities requiring different data structures, storage logic, and UI components.

The /grill-with-docs skill addresses this by forcing a "grilling session." Using Claude Opus 4.7 configured with high effort, the skill parses the provided documentation (or a raw text description) to identify inconsistent vocabulary. It doesn't just ask about database schemas; it asks about the meaning of the entities. By resolving these discrepancies upfront, the developer ensures that the developer, the client, and the AI agent all operate within the same semantic framework.

Artifact Generation: context.md and the Ubiquitous Language

The primary output of a successful grilling session is the creation of structured artifacts. The most critical of these is context.md.

In the context of DDD, context.md serves as the source of truth for the project's Ubiquitous Language. It acts as a glossary that minimizes misconceptions and ambiguity. By generating this document during the initial phase, the developer provides a permanent reference point that can be injected into the prompt of any future agent. This prevents the "snowball effect," where a single misunderstood term leads to a cascade of incorrect architectural decisions.

Capturing Architectural Intent with ADRs

Beyond simple terminology, /grill-with-docs excels at identifying "crossroads of decisions"—points in the specification where a choice must be made that is difficult or expensive to reverse. For these instances, the skill generates Architecture Decision Records (ADRs).

An ADR is a critical piece of engineering documentation that captures:

1. The Decision: What was chosen (e.g., using S3 for asset storage instead of local disk).
2. The Context: Why the decision was made (e.g., scalability requirements).
3. The Trade-offs: The pros and cons of the chosen path.

In a recent implementation test involving a Laravel and Livewire stack, the grilling session generated three distinct ADRs:

• ADR 001 (Assets, Storage, and Serving): Deciding on a specific driver for file storage to avoid the migration pain of moving from local to cloud storage later.

• ADR 002 (Inversion of Specification): Documenting instances where the developer intentionally deviated from the client's original description to follow better technical practices.

• ADR 003 (Independent Person Identification): Establishing the logic for identity management within the system.

By documenting these in the repository, the developer provides "future-proof" context. Whether it is a human developer returning to the project six months later or a different AI agent, the reasoning behind the architecture remains transparent.

The Implementation Pipeline: From Grilling to Composer 2.5

The true power of this workflow is realized when the outputs of the grilling session are fed into an implementation-focused agent, such as Cursor Composer 2.5.

The workflow follows a rigorous four-stage pipeline:

1. The Grilling Phase: Running /grill-with-docs to generate context.md and ADRs (approx. 30 minutes for 15 deep-dive questions).
2. The Planning Phase: Using a custom prompt to slice the project into manageable, numbered phases and sub-tasks. Crucially, this prompt instructs the agent to specify feature tests as acceptance criteria for every task. This ensures the agent has a clear "red/green" metric to validate its own work.
3. The Implementation Phase: Feeding the structured plan and the context.md into Composer 2.5.
4. The Verification Phase: Executing the generated tests to ensure the implementation aligns with the established ADRs and the Ubiquitous Language.

In a recent test, this process took a single project description and transformed it into a highly structured plan consisting of 9 phases and 45 specific tasks in roughly five minutes. When implemented via Composer 2.5, the resulting code maintained high quality across all phases, precisely because the "knowledge gaps" had been closed during the initial grilling session.

Conclusion: The Value of Upfront Rigor

While the /grill-with-docs process requires an upfront investment of time—roughly two minutes per question—the ROI is found in the reduction of technical debt and rework. By treating the AI agent as a collaborator that requires precise semantic boundaries, developers can move from "guessing" to "engineering." The transition from /grill-me to /grill-with-docs represents a shift from simple instruction-following to true architectural orchestration.