In this article, I outline the Spek Flow Approach: a simple, effective method for getting reliable code from a powerful, non-deterministic tool. The examples are drawn from medium spicy personal projects because I can share code snippets, but it’s applicable to large scale enterprise systems as well. This system is a financial application, which performs LLM-driven reconciliation of financial data pulled from wildly different sources and then use Gemini agents to post transactions directly to the Zoho Books General Ledger.

The approach involves creating structured Markdown files (.md files) and layers of context to guide the AI's output. I've seen many teams independently converge on different flavors of this method, which strongly suggests it's a crucial, emerging pattern in AI-assisted engineering.

The AI's memory and comprehension are actually exceptionally great; it can determine your complex architecture just by reading your codebase. Funnily enough, this is the first thing most people test when they introduce AI agents into a repository. However, its memory is not static because of the the token limit, the  problem is managing the relevant context. The tool is constantly summarizing its own memory—a message we routinely see popping up on Claude or Co-Pilot—which causes its focus to shift, push out useful context, and lead to degraded repeatability.

The Spek Flow Approach solves this by structuring the exact, most relevant context the AI needs. This allows the non-deterministic tool to focus its power on the task, instead of constantly grasping at all the straws for context. Looks like Mark Down is going main stream.

Tiered Context

The AI agent is really just an extension of your own reasoning ability. So, it makes sense that everyone has their own flavor of doing this. Each team will similarly have its own document strategy that reflects the reasoning, style, and constraints faced by that team, so don't feel bad about carving your own way. There are several "Spek Kits" and similar frameworks coming out now, but I personally find them often overly restrictive to a specific way of thinking and sometimes too complex—at least for the types of problems I'm trying to solve. My approach, developed for myself, focuses on prioritizing context into three distinct layers designed to manage token burn, maximise the Agents comprehension and solve for context erosion. 

Rules & Ways of Working

This file contains the non-negotiable, global rules that define the project's standards, execution environment (execute through podman instead of native python), and lite weight architecture. This content is stored in my copilot-instructions.md file, which is injected into every prompt. Anything that I find myself repeating to the agent is a good signal that it should go into the instructions file. I keep the context light here to manage my token burn and context window length, so I avoid putting business rule-type stuff or going overly crazy on defining architecture. This file is also good for correcting mistakes that the agent routinely makes, like defaulting back to native logic instead of using libraries I've added to my repo for specific actions (e.g., using Bootstrap modals instead of JavaScript alert() boxes).

Project Blueprint

This file contains the broad rules and design philosophy of the system. This content comes from my README.md file. While the README is important at the start, eventually your codebase itself becomes the definitive source of truth. It's best to keep this file as high-level as possible, maybe only including purpose, goals, and global definitions at best. It's also a good idea to use a referencing strategy here to tell the AI where to go find planning files, designs or arhcitecutre acting as a map for anyone—or any agent—dropped into the repository.

Feature Planning

This file contains the deep, feature-specific context that tells the AI precisely what to build. This is where I spend most of my time, as this is the fine-tuning engine where I try to be as unambiguous as possible. I use the AI to help me build this off of pre-defined templates set out in my Tier 1 instruction file. I review and refine this file, sometimes for hours depending on the feature's complexity, because this planning is what gets me to 80% success. This process can usually take days in the traditional approach, and even days more to write output of those plans.  This file contains the final, explicit instruction set, including the Database Design (Entity Relationship Diagrams and Class Diagrams, often described using Mermaid charts—which are great for pinning down unstated assumptions), the File Structure (what it will put where), User Stories (mapped out by the AI and refined by me), and Development Phases (the structured sequence of implementation steps like Phase 1: Authentication & Setup).

Modes of Work

While upfront planning is always a good idea, sometimes you just don’t have enough information, and this is where the AI agent makes a great scratch pad. So I’ve really got two modes of work, depending on the certainty of the problem I’m trying to solve.

When certainty is High (Plan First Mode), the task is straightforward (e.g., generating report features). I create a solid Feature Contract first, which gets me 80% of the way there, then focus the remaining 20% on final refinement. Conversely, when certainty is High Uncertainty (Build an Agentic Flow), I start by prompting and building to see where I get. There is no initial Specification Kit. Once my understanding is refined through that exploration, I scrap the initial code and restart with the Plan First Mode.

Shortcomings

Regardless of the mode, the AI will get most of the code right, but the bits is where the real work—and the real risk—lies. The AI output is sometimes plain bad, especially with the back of forth of discovery where I'm constantly changing the rules as I refine the solution and my thinking.

The inconsistency is clear: for example, the AI might write every database query and data process into one massive controller function—ignoring DRY (Don't Repeat Yourself) principles, even though I defined them in my specification files. At this point, I must step into the developer role, take accountability for the code by reading it, and explicitly correcting the AI's design choices. This requires manual intervention by breaking the complex task into smaller, separate functions and prompting the AI to separate them out.

Final Thoughts

We are still in the very early days of AI. Enterprise standards are, for good reason, really high, and AI will have to meet these standards. This approach seems to be a good step towards getting there. These models are also getting crazy better; the LLM I was using in August is not the same one I use now. This is as bad as these models will ever be, and they are pretty damn powerful already.