1
Here is how we are planning. We iterate with our team and agents on one plan document.
It starts with some of the key things in a PRD but shorter and to the point: goals, use cases, jobs to be done, differentiators, strategy, succcess.
Then, in the same document, we include architecture diagrams in excalidraw or mermaid.
Then we describe the implementation approach but without any code, the approach.
Goal is as short as possible while being thorough... usually a few pages.
Now, we have one unified document that we/agents can use to build. The agents use this plus a full testing plan plus the code. And we get much better results.
It is nice because a human can and will read a few page document and the agents will keep it up-to-date with what is implemented.
- Plan: Write a plan in markdown. Edit this. Iterate. The plan isn’t a throwaway note. It tracks status as work progresses (draft -> in-development -> in-review -> completed), versions with git alongside the code, and serves as the single source of truth. When the agent later implements, it reads this document. When we review the work, we compare against it.
- Diagram: Have the agent enrich the plan with architecture diagrams and data models. Edit this. Iterate. These artifacts live alongside the plan and the code. When the agent later implements, it doesn’t need us to re-explain the architecture or the schema. It reads them directly.
- Mockup: For anything with a UI, we create mockups before touching code. We generate interactive html/javascript most of the time. This replaces the Figma-to-engineering handoff entirely. When the agent implements the UI, it already knows what it should look like. No exporting, no describing screenshots in words, no “make it look like the design.”
- Tests: We have the agent write tests based on the plan, diagrams, and mockup. We review them, add edge cases, and now we have an executable definition of “done.”
- Implement: Now we tell the agent: “Implement the notification system. Run tests after each major change. Keep going until all tests pass.” The agent works iteratively. Implements the database migration from the data model. Runs tests — schema tests pass. Builds the WebSocket server. Implements the frontend. Runs Playwright and catches a CSS issue from the screenshot, fixes it, reruns. Eventually: all green.
- Review the work. When the agent finishes, we review. We click through the changes, see exactly what was added, modified, or removed, and compare it against the plan and mockup.
- Commit
- Update the Plan: After committing, we close the loop. We ask the agent to update the plan: status moves from in-development to completed, acceptance criteria get checked off, and any implementation notes get added. If anything doesn't match, either the plan gets updated or we rework the code.
- Update Docs and Website: The agent updates our documentation and our website, keeping everything in sync and up-to-date
What I like about this and why it works is that each step produces context that the next step consumes. By the time the agent starts writing code, it has the spec, the architecture diagram, the database schema, the mockup, and the test suite. Once its done coding, we update everything giving us clean context to build on.
- AI increases the gap between the motivated/curious and the lazy/fatalistic. When I'm motivated/curious, I learn and grow. When I'm lazy/fatalistic, I forget and shrink. I can have agents write code and do all sorts of stuff, but in every interaction I want to be involved and learning by asking questions. Stay curious. Don't be lazy.
- AI can be a catalyst that provides me with the activation energy I need to learn new things and do higher quality work. I'm coding now. I can work in git now. I am doing much higher quality marketing. Lean into this.
- AI enables every person, even the most junior, to become a leader and manager of agents. Many of the same principles of good leadership and management apply. I want to lead my agents well, but even more I want to lead teams of people well, so keep honing this.
- AI can improve many systems and processes. For 30 years, many professions have been slave to the database. The doctor isn't looking at you, she's typing into Epic. AI can make this much better.
- But, like the database, we will all have to use AI whether we want to or not and we will be shaped by it. I don't want to write like AI. (Here is the real truth. It's not this. It's that) I am moving 5x faster than I was 2 years ago which is so cool, but I'm not sure I have a choice. I am tempted to look at my mobile app during family time to make sure my agents are moving. Resist. Don't let it change me :) I'm not sure how much that is possible except maybe with friends.
- AI is very much a human achievement, cool math that compresses and makes available all human knowledge. Don't worship AI. Don't fear it. Work to make it a tool at the service of people.
- AI is not a person so don't build a relationship with it. Refer to it as it to help myself remember this. Every day invest in at least one friendship.
- The line between what is me and what is my avatars/bots should be clear.
- Extrapolation is difficult to get right. Most people who see the future super clearly are trying to sell me something or get me to submit to their future. Imagine the future I want and work to realize it.
- Work is meaningful for me and for most people. The goal is not to eliminate human work. Work to help many people have meaningful work to do.