DEV Community: Jeremy Strong

I can't read code, so I had to give my AI a map

Jeremy Strong — Mon, 27 Oct 2025 13:39:46 +0000

Ever had an AI coding assistant confidently refactor your code into an architectural nightmare? For most developers, that's a frustrating roadblock. For me, it's a total project failure, because I operate completely blind.

I literally cannot read or write code.

I'm an electrical engineer by training, not a developer. My role is to architect and direct an AI that serves as my sole implementer. Despite this fundamental limitation, I have successfully architected and built complex applications all the same.

This is only possible because I developed a system to give the AI a perfect architectural map. By embedding a signpost and a machine-readable contract in every file, the AI always knows where it is and what the rules are. This clarity prevents it from getting lost, a non-negotiable requirement for my workflow.
The secret isn't a better prompt; it's a better map.

1. The Starting Point: The Traditional Docstring

We all know what good "human" documentation looks like. A traditional docstring for a state management store might look something like this:

/**
 * Zustand store for managing global user authentication state.
 *
 * This store serves as the client-side single source of truth for
 * the user's identity and session status, providing access to
 * the current `AppUser` and authentication `AuthState`.
 *
 * @returns A Zustand store hook (`useAuthStore`) that provides
 *          authentication state and actions.
 * @exports AppUser, AuthState, useAuthStore
 */

This tells a developer what the code does, what it returns, and what it exports. It's clear and helpful for a human, but for an AI, it's a breadcrumb, not a blueprint. It lacks architectural framing. It doesn't declare the file's precise role, its explicit boundaries, or its contractual obligations within the larger system. Without that context, the AI guesses—and hallucinations begin.

2. The Evolution: The Illuminated File Preamble

A file preamble is a structured, machine-readable contract that lives at the top of every file. It’s the first thing an AI sees, and it encodes the file's architectural DNA. While the examples here are in TypeScript, this is a language-agnostic pattern that can be adapted to any stack—think docstrings in Python, module comments in Go, or crate-level documentation in Rust.

The key is a consistent structure, defined in a formal Coding Standard document that you provide to the AI as context. Here are the core fields that make it work:

@file: The full path, acting as the AI's anchor to know exactly where it is.
@stamp: A timestamp to track freshness and prevent context conflicts.
@architectural-role: Declares the systemic function using a term from a controlled vocabulary (e.g., State Management, UI Component).
@description: A summary of the file’s purpose.
@api-declaration: A list of the key symbols (components, functions, types) the file exports.
@core-principles: A list of its most important rules and responsibilities, using keywords like IS, MUST, OWNS, and DELEGATES.
@contract: A set of assertions about its behavior—its purity, state ownership, and I/O operations.

Here is that same state management file, now illuminated by a preamble generated according to that standard:

/**
 * @file src/features/auth/useAuthStore.ts
 * @stamp {"ts":"2025-10-21T14:00:00Z"}
 * @architectural-role State Management
 *
 * @description
 * Defines the central Zustand store for managing global user authentication
 * state. It serves as the client-side single source of truth for the
 * user's identity and session status.
 *
 * @core-principles
 * 1. IS the single source of truth for the current user's identity and
 *    auth status.
 * 2. OWNS the `AppUser` domain model for the client application.
 * 3. MUST only be mutated by the `useFirebaseAuthListener` hook to ensure
 *    a single, unidirectional data flow from the external auth service.
 *
 * @api-declaration
 *   - `AppUser`: The interface defining the application-specific user
 *     model.
 *   - `AuthState`: The interface defining the store's state and actions.
 *   - `useAuthStore`: The exported Zustand store hook.
 *
 * @contract
 *   assertions:
 *     purity: mutates # This is a state store; its purpose is to manage
 *     mutable state.
 *     state_ownership: [status, user] # It exclusively owns the global
 *     auth state.
 *     external_io: none # It is a pure, in-memory store and MUST NOT
 *     perform any I/O.
 */

3. The Workflow Layer: Activating the System

The workflow layer of my system is a deliberate process designed to transform our static contracts into dynamic, architecturally-sound results.
This is accomplished through two core practices:

Assembling the "Context Slice":
Before any dialogue begins, I provide the AI with a curated "blast radius" of relevant files—the file to be changed and its key collaborators. This is the crucial step, and its power comes from a simple fact: every file in this slice also has its own perfect preamble. The AI is not being handed a tangled bundle of code; it is being handed a schematic of pre-labeled components. It doesn't need to guess at their purpose; their functions, contracts, and relationships are all explicitly declared, creating a system where all the moving parts are clearly defined.
Use a Two-Phase Prompt:
With the right files attached, you can now treat the AI as a junior architect. You ask for a plan before you ask for code.

Phase 1: The Proposal. You ask the AI to reason about the problem first.

"Based on the attached files, propose a plan to add a feature that clears the user's session."

Phase 2: The Execution. Once the plan looks good, you give the green light and remind it of the rules.

"That plan is correct. Proceed, and ensure every change is fully compliant with the coding standard."

This workflow is the difference between getting a generic component and a custom-machined part. By forcing the AI to reason about the neighborhood before it acts, it ensures every new piece of code is created with a perfect, innate understanding of its surroundings. The result isn't just functional code; it's code that fits—seamlessly integrated into its place in the architecture from the moment of its creation.

4. The Killer Feature: AIs Maintain Their Own Documentation

Traditional documentation rots. It's a chore for developers, so it inevitably drifts from reality. With this system, the opposite happens. AIs are exceptionally good at keeping preambles fresh. When you ask an AI to refactor a file, it also updates the preamble to reflect the changes. The maintenance isn't a human burden; it's an automated part of the AI's workflow.

5. The Payoff: Clarity at Scale

Of course, implementing a system like this requires an upfront investment. Defining your coding standard and adding the initial preambles takes time. However, this initial effort pays dividends almost immediately. For a system like mine, where every instruction must be perfect, the time saved by avoiding a single major AI-driven error can repay the initial investment tenfold. Think of it not as writing documentation, but as forging the guardrails for a powerful but unpredictable new team member.

Prevents "Context Poisoning": Stale documentation is an infohazard that poisons an AI's suggestions. Because the preamble is a living document, updated by the AI alongside the code, it remains fresh and trustworthy, eliminating this risk entirely.
Unlocks Industrial-Scale Velocity: This system isn't theoretical; it's a production-ready engine. It is the engine that has allowed, in just four months, for the creation of a private application of over 500 files. The open-source results of this high-velocity workflow are fully documented and available for review, demonstrating that this speed does not come at the cost of quality.
Enables Architectural Scalability: The bigger the project, the more essential this becomes. A 10-file project could skip it. At 100 files, it's mandatory. A 500-file project is impossible to manage with an AI assistant without it.
Allows for Surgical Precision: Preambles let me snip parts of the project and feed them to the AI in isolation. Because the file's contract is declared upfront, the bot still knows what's going on without needing to parse the entire codebase.
Unlocks Holistic Reasoning: The AI can scan the @architectural-role and @contract fields across dozens of files in seconds, building a high-level "map" of the system. It understands relationships and dependencies without parsing every line of code, leading to far more intelligent and architecturally-sound suggestions.

6. System Illumination

Think of each preamble as a single candle. It illuminates one file, making its purpose and boundaries clear.

When every file has a preamble, the system becomes a constellation—a network of clearly defined modules, each glowing with intent. An AI coder can traverse this constellation with confidence, understanding not just what each file does, but why it exists and how it connects to the whole. It can navigate, reason, and create with a map, not a blindfold.

The future of AI-driven development isn’t about better prompts—it’s about better systems. The real leverage isn't in finding the magic words to get what you want one time. It's in building a rigorous, scalable map so your AI knows what you want every time.
Stop prompting. Start mapping.

Beyond Boilerplate: A Structured Method for AI Software Creation

Jeremy Strong — Sun, 19 Oct 2025 11:23:46 +0000

"Build a full-stack app in a day!"

That’s the headline that kicked off the AI-dev gold rush. But after the hype settled, many were left with the same feeling: underwhelmed.

AI tools can scaffold a React app or generate a CRUD API, but when the task grows complex - when it demands architecture, continuity, or creative judgment-they lose their way. The explanation I've seen again and again is that AI "can’t code anything novel", it's only good for boilerplate.

The limitation isn’t in the AI. It’s in how we ask it to work.

I’m not a developer; I’ve never written a line of JavaScript by hand. Three months ago, I created my first JS file - in my spare time around a full-time day job. Yet I’m in the final stretch of a 500-file JS project built entirely by AI. What makes that possible isn’t coding skill—it’s a structured workflow I call Vision-First Development.

Beyond Autocomplete

In most workflows, the AI is treated like a world-class autocomplete. The developer writes code, and the AI helps fill in the gaps, generating snippets and handling repetition. That’s efficient for incremental progress, but it also means the system’s architecture emerges reactively, not deliberately. When a task grows complex, the AI is forced to infer intent, invent missing context, and make creative leaps on its own.

This is the root of the problem. AI coder pain comes from an unclear vision. When the goals, principles, or desired outcomes aren’t fully defined, every decision the AI makes carries the risk of misalignment and rework.

Phase 1: The Dialogue (Defining the "What")

Vision-First Development solves this by front-loading the most important work. Before a single line of code is written, I start with a conversation.

The goal of this dialogue is to create a shared understanding of the "ideal state"—a complete mental model of how a feature should behave, feel, and integrate with the wider system. It is a code-agnostic exploration of the problem. Sometimes, if the vision is clear, this takes ten minutes. Other times, it becomes a journey of discovery, using the AI as an expert consultant to evaluate trade-offs and find the optimal path.

By the end of this phase, the AI and I share a clear understanding of what "done" looks like, establishing a foundation that makes implementation predictable and aligned.

Phase 2: The Execution (Full-File, One-Shot Generation)

Once the ideal state is defined, implementation shifts from exploration to execution. My role becomes that of an architect, systematically limiting the AI's degrees of freedom to ensure its power is channeled directly toward the pre-defined vision. Two layers of documentation keep the process aligned:

The Constitutional Layer: This layer consists of prebuilt context documents - overarching project principles and coding standards included with every prompt. These documents act as architectural law, eliminating thousands of potential wrong paths upfront.
The Contractual Layer: Docblocks at the head of each file defining purpose, responsibility, and internal principles. This transforms each file into a defined, constrained problem.

With these guardrails in place, the AI takes full ownership of coding. It generates entire files in a single shot rather than completing snippets. This frictionless, one-shot generation is the key to velocity.

The Why

The payoff for this front-loaded investment in clarity is a blistering implementation speed. I can now output complete, complex features at a rate of one fully-coded file every 3 to 5 minutes.

For instance, the last two major updates I shipped were deep, structural refactors that went straight through the project's central files. These updates, which totaled 16 and 30 full files respectively, took just 4 hours and 10 hours to complete.

That’s a sustainable pace of 3-4 complex, fully-integrated files per hour. The source files, containing pure logic, often go through without a single fix. Even the debugging, primarily on test files, is handled entirely by the AI. I still can't read the code, but this system allows me to play to my strengths: designing and optimizing systems. The AI generates, debugs, and perfects itself, guided by a clear vision, at an industrial scale.

This methodology isn't just theory. I built my open-source tool, Context Slicer, using this exact process. It's a key part of my workflow for managing the very context these conversations depend on.
I'll let the results speak for themselves. Explore the live app, inspect the source code, and decide for yourself if this approach is real.

Live demo: contextslicer.web.app
Source Code: GitHub repo