To plan or yolo, and everything in between
When it comes to planning out a new feature (aka. developing the spec), there are a lot of great techniques and advice out there. There are also a lot of pitfalls with adopting more of these techniques than is useful for your day-to-day work. I just read a long but good post from Addy Osmani on writing good specs. That post goes into a lot of the different considerations and a structured process for coming up with these plans. Most times, developers don’t need to go this crazy and adopt all of this for their own workflow. I personally think it would be hell to have to plan this way for the majority of my own work.
As developers driving these coding agents, we have a wide range of possibilities: don’t even build a plan at all, all the way towards a plan consisting of a fully fleshed out multi-page technical brief. Putting a significant amount of your own time and effort into making the best plan doesn’t always translate to even better code. For simple things you’ll want simple solutions, and agents can be great at that since there’s only a small amount of possibilities of how it would be built. But the bigger and more complex the thing to be built is, the more decisions and guidance agents will need to have or else they can go off the rails and build something you don’t like. This is relevant anywhere - whether you’re working on your own side project, building fast at a startup, or jumping through dozens of different requirements at a large company. The context of what you’re building and what all the nonfunctional requirements are will affect how much time and effort goes into the planning phase.
In personal projects, the quality and end result of the agent generated code is up to you, so the quality and effort barrier can be just about zero if you really wanted to. Just yolo ship whatever code it creates if it works, and don’t even bother looking at it. At startups, there are likely only a few requirements and quality bars that really matter (eg. the feature works, it doesn’t break the entire app, the code doesn’t look like a ball of spaghetti already). Then at large companies teams probably have to jump through hoops of people reviewing their plans, and take into consideration stuff such as UI design practices, localization, coding standards, technology choices, compliance, etc.
As you can see, the planning phase for a personal project can be very small and to the point compared to also nailing down all nonfunctional requirements at a large company. Therefore, large companies and startups who already have well-ingrained processes and requirements lack the nimbleness of someone who can yolo everything on their own side projects. Consider detailing the requirements that are easier for an agent to follow into rules files and use them in your planning workflow. You may also consider reevaluating if some other requirements are actually necessary or too strict for this new agent-driven development world we’re all thrust into.
As I’m writing this, I came across Geoffrey Huntley’s post on “model weight first companies” - companies in which they don’t have to exhaustively instruct an agent to give it what they need since the default answer given likely will work best for their purposes. Non-model weight first companies have codebases, processes, and practices built up over years and will often have to provide a lot of requirements and context to the agent to get it to output what suits their needs. Think a one-liner prompt for building a new feature in a CLI tool vs having engrained practices and developer ergonomics that need to be adhered to for the same new feature in the CLI tool. This is another great way to describe how much more difficult and slow larger companies have it at using agentic coding tools. Best for a company, or even a team, to adopt or get eaten by your competitors.
Planning with agents
The best part of agents is having it take your learned practices, either through a prompt or previously written doc, and applying that to the current problem. You can quickly apply your or your team’s UI design best practices to a plan if it requires any UI work. The same goes for any other functional and nonfunctional requirements too, eg. every metric and report must take in the user’s preferred timezone and output the data according to that.
Some teams have these planning rules broken out into their own documentation, others may have them always included in their agent’s context. Wherever it is, it guides the agent to automatically take these into consideration when writing the plan. Then all you have to do is review it. This can negate the impact that people and teams have when needing to plan out medium to large projects since the best practices can be applied by the agents, and quality can stay consistent if it’s easy for developers to do this each time they create plans.
On manually crafting the right context and instructions for each agent to use
Part of Addy’s post went into breaking down the spec into smaller tasks that are simpler for the coding agents to take and work on. This is good practice, but lean into agents doing this for you. The trap this post uses as an example (which some basic prompting and use of Beads could easily solve) is manually feeding the agent the right snippets of context and instructions for each task of the plan, eg.
after the spec is written, your next move might be: “Step 1: Implement the database schema.” You feed the agent the Database section of the spec only, plus any global constraints from the spec (like tech stack). The agent works on that. Then for Step 2, “Now implement the authentication feature”, you provide the Auth section of the spec and maybe the relevant parts of the schema if needed.
This level of involvement of directly providing the right context and instructions to an agent is too low level. You’re constrained by the speed at which you can copy/paste or manually type the context and instructions into the agent’s prompt. You may also be reaching a limit of how many agents you can drive by hand at a single time.
In this post on how Beads can speed up your workflow, I mentioned that Beads, a lightweight issue tracker built for agentic use, is great for managing the context and instructions for each plan’s task. An agent can be prompted to take the plan and embed the exact context and instructions that each task needs. Then when its time to build, a fresh agent picks up the task and has all the context it needs to successfully complete the task with the necessary quality.
You can even automate multiple parts of this planning and building process, saving valuable time to focus on higher-level activities like planning and reviewing the resulting code. Agents can apply your best practices to plans, are able to break down plans recursively into smaller and smaller tasks with the necessary context they need. The prompts to do this are pretty simple. Check out that aforementioned Beads post for a lot of tips.
Agents can do a lot more things than just write code. As mentioned earlier, they can effectively build plans that work with your codebase and best practices, and even do the gruntwork of breaking plans down into small tasks that agents can successfully implement. Give it a shot with your own workflows and best practices, you’ll see a lot of it can be automated, freeing you up to work on even more things.