Looks Like I’ve Finally Found a Way to Work with Coding Agents – and It’s Much Better Than Spec-Driven Development

A developer has released AgentFlow, a micro-framework designed to improve collaboration between human developers and coding agents. The framework addresses common issues such as context transfer, task understanding, and reviewability of large code changes, aiming to reduce the number of revision cycles and improve code quality.

How much code do you still write by hand? People on my team say no more than 15%. For me, it is closer to 2%. That dramatically raises the bar for generated code: the better the code, the fewer tokens we spend fixing it and the faster we ship features. When agents write almost all the code, every mistake becomes another review cycle, another model call, and more time lost. But how do you get agents to produce good code? For the past ten months, I have been building a complex project from scratch while maintaining several mature commercial and open-source codebases. And I think I have finally found my silver bullet. It was not a magic prompt that suddenly made the model write perfect code. It was a process that stopped it from wandering too far down the wrong path. It works so well that I could not keep quiet about it, so I packaged it as AgentFlow https://github.com/reforma-dev/agentflow — a micro-framework that gives developers and agents a shared way to work through tasks. Disclaimer: I cannot claim that everything in AgentFlow is my invention. The approaches — and possibly even entire fragments of skill text — were collected piece by piece from different sources over time. My contribution was turning them into one coherent process, testing it on real development work with real teams, and throwing out the unnecessary ritual. What is the main reason agent-generated code turns out badly? In my view, it is the same reason human-written code turns out badly. If you work on a large project with a team, you know how difficult it is to transfer context between developers, especially as people come and go. New hires do not know which helpers already exist, which problems have already been solved, or which interfaces and components are already in use. Hell, even developers who have been at the company for eight years may be unaware of most of the decisions buried in the codebase. And then agents enter the picture, and somehow we expect better results from them than from people. But unlike people, agents rarely push back. Give one a task and it will cheerfully start implementing it, usually without asking questions and after only a shallow pass over both the task and the existing architecture. Every new chat with an agent is like a developer's first day at the company. Of course, we have ways to help: AGENTS.md , project documentation, stack-specific skills, perhaps specs from previous work. Your project may have more or less of this, but either way it is only a coarse description of the project or stack. The real problems start when the agent reaches a specific feature in a specific module. It will most likely find the nearest solution it understands and stick to it — even if that solution was wrong from the start. The second problem is understanding the task itself. If you have ever managed developers, you know this problem has always applied to people first. Your developers will almost never implement a task exactly as you pictured it, because their understanding will differ from yours. At the same time, the manager's, lead's, or business's understanding is probably distorted too: nobody knows in advance which problems will surface during development or what the task will look like by the end. The work goes through revision cycles on all sides. Requirements change. Code that was just written gets rewritten as new code appears. Designs and descriptions evolve while individual pieces are being implemented. The problem is not necessarily a bad initial brief: a complete understanding of the task often emerges only while building it. The third problem is transferring context between agents and chats, which becomes especially important when you are building genuinely large features. The fourth problem is the size of the change. An agent can easily modify a hundred files, leaving you with a diff that is almost impossible to review properly. At that point the work is no longer under control: a person looks through the giant diff and effectively accepts it on faith. Built-in planning modes and spec-driven frameworks such as OpenSpec or Spec Kit try to solve these problems, but they come with problems of their own. I used OpenSpec heavily and liked it. It is a fantastic approach, but I constantly had to remember which commands to run and in what order. Getting the team to use it was even harder for the same reason — and because people would rather open an agent and ask it to do something than follow a ritual. The spec-driven approach moves the center of gravity away from code and chat history and toward long-lived specifications. The idea is sound: define the requirements and design first, then write the code. But it creates two major problems: Our systems analyst practically built a cult around this. He started documenting every task this way in a separate repository instead of managing projects in Notion and Linear as before. But that was literally his job. Most developers never made it past /propose . Eventually the specifications directory grew so large that nobody could take responsibility for it or say whether it contained anything useful and current at all. In the end, we deleted it, returned to regular planning mode, and kept looking for a better way to work. The solution we eventually found became the core of all our AI development and the foundation of AgentFlow https://github.com/reforma-dev/agentflow . The original skill came from Matt Pocock and was called /grilling https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md . The idea is to make the agent prove that it understands the task before implementation: restate it, identify the decisions and assumptions already implied, and then interview the user about everything that could materially change the result. Grill models the task as a decision tree. The agent starts with questions whose answers do not depend on other unresolved decisions. For each question, it recommends an answer and presents alternatives. Every answer opens new branches and creates new questions, so an initial round of three can easily become fourteen before the grill closes. It ends only when every important branch has been explored and the user has confirmed the final understanding of the task. There is a fundamental division of responsibility here: finding facts is the agent's job; making decisions is the user's. The agent should not ask which helpers, components, or APIs already exist if it can find them itself. It searches the code, documentation, and web, does its own research, and only then brings the user questions that genuinely require a product or architecture decision. By the end of Grill, the agent has enough shared context to start implementing, and you know what it intends to do. Its questions will probably expose problems you had not considered and would otherwise discover only after half the system had already been built. It feels more like a product manager discussing a task with a strong architect or senior developer — someone who immediately starts asking how each scenario is supposed to work. The skill is universal. It scales across tasks of any complexity, from a small UI or API change to an entire epic spanning several projects and repositories. But /grill is not all of AgentFlow. Grill creates a shared understanding of the task. The rest of the process prevents that understanding from disappearing and stops the implementation from growing into an uncontrollable diff. This is what the workflow now looks like across my teams: A developer asks the agent to research the task that needs to be implemented. You do not even have to describe the task yet; you can simply ask it to investigate the part of the system you are about to change. The goal is to find the relevant modules, files, and documentation and sketch the current architecture. Research may involve the web, an MCP server such as Context7, competitors, or approaches someone else has already implemented. Ordinary research does not require a dedicated skill. Use /research when the findings need to survive the current chat: it saves a map and detailed notes under .agentflow/<feature /research/ so another agent can pick them up after a context switch. You do not necessarily need to read all of it. These are facts about the existing system, preserved for another agent or for context compaction. Describe the task and run /grill , then answer a couple of questions. Then a couple more. Possibly another ten, depending on the complexity of the task and how clear it was to begin with. At this point, you start to feel confident that the agent actually understands what you want. At the end, the user confirms the final reading. The agent then continues the process itself: it either implements one small change or loads /plan . Optional /plan . If the task is large enough to ship as several small PRs, create a plan. Its main purpose is not merely to list implementation steps, but to slice the task into small, controlled PRs. The agent gets a clear checklist, while you can ship the task incrementally and inspect the implementation after every step. Each part can be implemented by a different agent if you want. Every PR must do something useful on its own, leave the project working, and have a clear way to verify it. The plan remains a working document and changes when PR boundaries shift during implementation. If the coding agent has a native planning mode, AgentFlow uses that instead of creating plan.md . Implement the task, optionally using /tdd . Test-driven development works extremely well for many backend tasks. I do not use it for most work, though; we simply implement the next part of the plan. The important part is that the agent implements exactly one PR and nothing beyond it. If the work starts bleeding into the next PR, it updates the plan instead of silently expanding the current diff. Of course, /code-review . I pulled together the best parts of every review skill I could find. Its main job is not just to find bugs, but to shrink and clean the agent's diff: reinvented APIs, duplicate helpers, unnecessary wrappers, pass-through functions, one-off barrel files, dead exports, leftovers from failed refactors, and tests that only test their own mocks. The agent fixes simple, local, behavior-preserving problems itself. It then addresses obvious defects and runs the real verification commands. If the diff touches a critical surface such as authentication, user input, networking, or secrets, and one read is not enough, the skill can bring in one additional read-only reviewer for that specific risk. A human still has to read the diff after the agent review. Only then is the change committed using the project's normal workflow. If the plan contains more PRs, the loop repeats: next PR → implementation → agent review → human review → commit. The size of this loop, not the size of the entire feature, is the unit of control. If the next PR will be implemented in a new chat, or the current context has become noisy, run /handoff . It records what was shipped, how the plan changed, and which single PR comes next. The new chat receives the plan and handoff, giving it the context it needs from the previous agents to continue the work. Finally, optional /document is for cases where the result should become long-lived project documentation. It turns research, a completed plan, or a shipped change into a single documentation page — or updates the existing documentation for that domain — and then removes the temporary working files. It is similar to OpenSpec's archive step, but without requiring every intermediate artifact to live forever. If the project does not need a separate page, skip it. You can also simply keep the entire .agentflow directory out of Git. Grill is the core of the process. The other steps appear only when they solve a specific problem. Skip Research if the area is already clear. Skip Plan for a single small slice. Handoff appears only when context moves. Document appears only when the result should become a long-lived project page. But the order does not change: first we learn the facts, then make decisions, plan the work, implement one PR, review it, and only then move to the next one. The best part is that you usually do not need to run these commands by hand. AgentFlow creates a separate AGENTFLOW.md and links to it from AGENTS.md , so the whole process is already in the agent's context. For anything larger than an obvious fix, the agent gets the workflow directly from the project. After Grill, it loads Plan itself when the work needs multiple PRs, or moves straight to implementing one small change. The remaining skills appear when there is an actual reason to use them. The agent should remember the workflow. The developer should not have to. Quality does not come from one giant document written before the work begins. It comes from a short, repeatable loop: decisions are settled before implementation, the work is limited to one PR-sized slice, and that slice is reviewed by both the agent and a human before the next one starts. AgentFlow does not replace software development with a new ritual. It embeds engineering discipline into the way you already work with an agent, shifting the burden of remembering the process from the human to the machine. Install it with one command: npx @reforma/agentflow init .