It works. Enterprise customers love it. But there’s a catch: every new customer goes through a white-glove onboarding where Denise’s team manually authors the test scenarios alongside them. They identify the highest-value flows, tune the inputs to the right level of specificity, and build a working setup that would’ve taken weeks for in-house QA teams to develop in just a day’s time.

That process produces great outcomes and teams are already saving lots of time with Variata. But now Denise is thinking about scale.

So she set out to build the self-serve version including an authoring tool that would help users create their own test scenarios without her team in the room. She’s done discovery across paying customers, free trial users, and casual evaluators. She’s identified a spectrum of user inputs ranging from “just test my site” to granular click-by-click scripts. She’s built three prototype classifiers to guide users toward the sweet spot.

These are all the pieces. The question is how they fit together.

Denise and I help each other as founders, and this month we used her self-service challenge as the topic of our conversation. It gave me a chance to work through a real product planning scenario that will help us build Stoa (our conversational planning tool) and it gave her an outside perspective. This session led us past some strong product principles so I decided to write it up and share it.

The Spectrum Problem

Here’s the tension Denise was staring at. Variata’s AI works best when it gets input at a middle level of abstraction — milestones and expected outcomes, not pixel-level instructions. “Verify the sign-up flow works and the user lands on the dashboard” is better than “click the email field, type test@gmail.com, click the password field, type abc123, click Submit.” The specific version latches onto details that change constantly. The milestone version is durable.

But users don’t naturally land in that middle zone. QA engineers tend to over-specify. Product managers and executives tend to under-specify. And the “just test my site” crowd gives almost nothing to work with.

So the question Denise was trying to answer: how do you build an AI-assisted authoring experience that nudges users toward the level of detail that actually produces reliable tests?

She’d prototyped three approaches. (1) A binary gate that gives a simple yes/no depending on whether your test prompt is sufficient. (2) A gap coach that shows you specifically what’s missing. And (3) a clarifying Q&A coach that asks questions until it has enough to work with.

Before evaluating any of them, though, there’s a more fundamental question we decided to tackle.

Whose Problem Is This?

It’s easy to describe this challenge in system terms: how do we ensure users provide input that maximizes Variata’s success rate? That framing is accurate. It’s also a trap, because it centers the product’s needs rather than the user’s.

Flip it around. What’s the user actually trying to do?

Denise described a Product Leader she’d spoken with- someone who manually runs twenty user flows every morning. An hour of clicking through their own site with a coffee, testing that the promo codes work, the checkout completes, the filters behave. Not because it’s in their job description. Because they feel personally responsible for their site.

That person’s problem isn’t “I need to author test scenarios at the right level of abstraction for an AI system.” Their problem is: I have a process that works, I want it to keep working, and I’d like my morning back.

That reframe matters because it changes what success looks like. The authoring tool isn’t asking users to learn a new skill. It’s asking them to hand over something they already do and trust that it’ll be done right.

Reframe the problem from the user’s side before designing solutions. “How do we get better input for our system” and “how do I get my morning back” lead to very different products.

Who Exactly Are You Building For?

Denise had mapped out several personas: QA testers, product managers, developers, enterprise buyers, self-serve evaluators. She’d segmented by release cadence and personal risk. The users who keep coming back are the ones who have to sign off on revenue-driving releases at least monthly.

But “people who sign off on releases” is still a broad group. And a self-serve product can only have one front door.

The narrowing question: who, specifically, is going to try this tool on their own, fall in love with it, and then fight to get it adopted inside their company?

Not the QA engineer; at least not at first. Some will resist a tool that automates their core job. The person who will champion Variata from the bottom up is the product leader or VP who does QA out of intrinsic motivation. They’re doing it because nobody else will, they care about quality, and they’d happily hand it off to a system they trust.

That person also happens to have the organizational leverage to push deals forward from below while the Variata sales team works with executives from above.

Pick the champion, not the job title. The user most likely to adopt and evangelize your self-serve product isn’t always the one whose role most obviously matches your category. Look for intrinsic motivation plus organizational influence.

What Already Works

Here’s where the conversation got interesting. Before evaluating the three prototypes, it’s worth asking: what happens in the manual version that works so well?

When Denise’s team onboards a new customer by hand, what does the session actually look like? What’s on the screen? Where does the input come from?

Her answer was surprising. Users don’t typically pull up their live product and walk through it together. Instead, they show up with requirements documents from Jira tickets, specs, runbooks, and email attachments describing features they need tested. Sometimes the features don’t even exist in a live environment yet. The user is working from a written description of something they didn’t build and may never have seen running.

So Denise’s team takes that document and, sitting alongside the user, translates it into testable scenarios at the right level of abstraction. They author a few together so the user can see the pattern. Then they send the user off to do the rest as homework.

That’s the workflow. And it reframes the entire product challenge into one sentence: help people turn their requirements documents into testable scenarios.

Not “build a chatbot that asks smart questions.” Not “create a test recorder that watches you click.” Just: take the artifact the user already has and transform it into something Variata can run.

Study your manual process before automating it. The best self-serve products don’t invent new workflows. They bottle the proven ones. If your team already knows what works in the white-glove version, the product’s job is to encode that, not reimagine it from scratch.

The Case Against Questions

Back to the three prototypes: (1) a pass/fail binary gate on your testing inputs, (2) a coach that shows you the gaps between your input and expected structure, and (3) a Q&A workflow. With the problem compressed to “requirements in, testable scenarios out,” each approach looks different.

The binary gate is clearly too blunt. Telling someone “not enough detail, try again” when you have an LLM that can reason about exactly what’s missing is, as Denise put it, “a little bit lazy.”

The clarifying Q&A flow is more sophisticated. It mimics the experience of Claude Code or Codex- thinking, then surfacing questions like “What’s the expected outcome of a successful sign-up?” with selectable options. It feels smart.

But there’s a structural problem with questions: how do you know when to stop asking them? There’s a fine line between “your questions are helpful” and “your questions are annoying,” and that line moves depending on the user’s patience and context. Ask too few and you don’t have enough to work with. Ask too many and the user gives up.

More importantly, questions don’t teach. If the AI asks clarifying questions today, it’ll have to ask clarifying questions again tomorrow. The user never learns what a good testable scenario looks like. Instead they just get walked through one instance.

The gap coaching approach does something different. It shows the user a target that lets them build a mental model; here’s what a complete, well-formed scenario looks like. This, along with highlights of the specific gaps in what they provided can be powerful. Instead of an interrogation, it’s a progress bar toward a visible standard.

That means the user learns the shape of a good scenario. Next time through, they need less help. The product is building user capability, not user dependency.

Show what good looks like instead of interrogating toward it. A coaching UI that reveals the target teaches users to self-serve over time. An open-ended Q&A creates a recurring dependency on the system. The best onboarding doesn’t just get users through — it makes them better.

The Bigger Pattern

Denise walked into this conversation with a clear picture of Variata’s overall story and ROI journey. All we did together was zoom into one specific moment in that journey and get concrete about who’s there, what they’re holding, and what they need next.

The pieces were all present in her research. The Product Leader with the morning coffee ritual. The requirements docs that users show up with. The white-glove process that already works. The insight that coaching beats interrogation.

Sometimes product work isn’t about generating new ideas. It’s about compressing what you already know until the next move becomes obvious.

Want a workspace to have your own product clarity sessions? Try https://somehow.sh

Then a long debate followed about changing roles and AI code quality and the shifting job market. But I don’t think any of that was the real reason for resistance. I asked a simple question: “when did you share your prototype?”

A confused look and then a hesitant, “after I finished building it.”

And there was the problem: what feels like resistance is actually an ask for inclusion.

Not “give me a more detailed specification”, not “fix your prototype’s broken code”, but “bring me along for the ride”.

Think about what happens when a PM drops a fully-formed prototype on an engineer’s desk. The PM has spent hours, maybe days, in conversation with an AI tool, exploring options, hitting dead ends, making tradeoffs, arriving at a solution that feels right to them. They’ve weathered the whole storm of the creative process.

Then they hand over the sunny outcome and say: “Here. Build this.”

The engineer looks at it and feels... something. Not excitement. Something more like being airdropped into the eye of someone else’s brain storm. The air is calm here, but they can see the wreckage of decisions they weren’t part of. Why this data model? Why this flow and not the obvious alternative? What got tried and rejected? What tradeoffs were made, and who decided?

The prototype answers “what.” It doesn’t answer any of the “whys.” And without the “whys,” the engineer can’t do their job because engineering is the art of making good local decisions when you hit unexpected constraints, and you can only do that if you understand the intent behind the thing you’re building.

Nobody likes to be airdropped into the middle of someone else’s storm. But everyone loves a good story — a clear sequence of thinking they can follow, with a beginning, a middle, and a chance to shape the ending.

Every great PM already knows this. It’s why the best PRD reviews have never been signoff sessions. They’re conversations where the team pokes at the solution together: “What happens when the user doesn’t have an account?” “What if the API call fails mid-flow?” “This edge case seems ambiguous; can we nail it down right now?”

Traditionally we justified this discussion in terms of cost. Clarifying questions, surfaced in a review, cost an hour to resolve. The same questions surfaced after engineering is underway cost a week. Surfaced in QA? A month. Now, with the cost of rework plummeting, it feels like these tradeoffs no longer hold. But there was another subtler reason for these meetings.

The PRD review worked because the document felt open. It was words on a page. It was clearly a draft of thinking, not a finished product. People felt invited to push back, ask questions, and shape the direction. The document said, implicitly: “This is what I’m thinking. Help me think better.”

A working prototype sends the opposite signal. It looks done. It runs. It has buttons that click and screens that flow. Even if the PM knows it’s held together with duct tape and AI hallucinations, the engineer sees something that looks finished and hears: “I’ve already decided. Just make it production-ready.”

That’s the resistance. It’s not about the prototype. It’s about being handed a conclusion without the reasoning.

So what do you do? You don’t stop prototyping. The ability to express product thinking as working software is a genuine superpower that we shouldn’t lose.

But you turn over your thinking in stages, even if those stages happened quickly.

At SpecStory, we’ve been working on this problem, and we call the practice an intent review. It’s distinct from a code review. A code review asks: “Did we build it right?” An intent review asks: “Are we building the right thing and does everyone understand why?”

Here’s what that looks like in practice:

Share the problem before the solution. Before anyone sees the prototype, share the customer insight or the problem statement that motivated it. Give the team the same starting point you had. Let them sit with the problem for even a few minutes before you show them your answer.

Show your exploration, not just your conclusion. What did you try that didn’t work? What tradeoffs did you make? What alternatives did you consider? This is the “story” part — the sequence of thinking that makes the conclusion make sense. If you explored three approaches and chose one, show all three. Let the engineer see why this one won.

Name your confidence level. There’s a huge difference between “this is what I think we should build” and “these are two approaches I’m deciding between” and “this is an initial exploration, let’s iterate.” Naming where you are changes how people engage with what you’re showing them.

Invite the storm, don’t shelter people from it. The messiness of the creative process isn’t a bug, it’s where the best engineering input happens. When an engineer sees the problem space, not just the solution, they bring constraints and possibilities that make the product better. That’s not resistance. That’s collaboration.

Our new tools don’t change our humanity. AI can collapse the time between idea and prototype from weeks to hours, but it can’t collapse the human need to understand why before committing to what. An engineer who understands the intent behind a prototype will make a hundred good decisions during implementation that you never anticipated. An engineer who’s just been handed a thing to rebuild will ask you about every single one.

The fastest path to production isn’t a better prototype. It’s a team that shares your understanding of the problem.

So the next time you’re excited to show your team something you built (and you should be), pause for just a moment. Don’t airdrop them into the eye of your storm.

Tell them the story of the storm first. Then show them where you landed. Then ask them where they think you should go.

That’s not slower. That’s how you get there together.

It is a small ritual with larger meaning. Hashimoto is not fighting the rise of AI in open source. He is studying it, learning where it helps, and drawing careful lines around where it does not.

A new rule for a new era

Earlier this year, Mitchell Hashimoto introduced a new requirement to the Ghostty’s contributor guide: every pull request must disclose when AI tools were used. The idea was practical. Too many submissions looked fine on the surface but fell apart under review. He could tell that some contributors had pasted AI code they did not fully understand.

“Before AI, I might get one bad PR every six months,” he said. “Now it feels like every other week.”

The change was not about policing people. It was about context for reviewers who put their time and attention into a review. In the same pull request, he wrote, “The disclosure is to help maintainers assess how much attention to give a PR. While we aren’t obligated to in any way, I try to assist inexperienced contributors and coach them to the finish line. But if it’s just an AI on the other side, I don’t need to put in that effort.”

Behind the policy was a deeper frustration. He had seen an explosion of what he calls “AI slop” - code that looked plausible but lacked understanding. “There’s good-intention slop and bad-intention slop,” he said in his talk with us at SpecStory. “The difference is whether the person tried to understand what they were doing.”

That distinction matters. Hashimoto recalled a contributor who left the community after receiving harsh feedback on a low-quality PR. “Stuff like that makes me feel bad because I think it wouldn’t have happened ten years ago,” he said. “Back then, I would have been more patient. But now that bad contributions happen so often, I lose my patience immediately.”

Within weeks of the rule taking effect, about fifty percent of all Ghostty pull requests included an AI disclosure. The numbers confirmed what he suspected: AI had become a routine part of contribution. The question was no longer if it should be used, but how.

For Maintainers: Disclosure is essential, but it is only the first step. The challenge is helping good-faith contributors without drowning in noise.

For Contributors: Show your work. Help reviewers see your thinking, not just your diff.

Since that initial change, Hashimoto has continued to shape Ghostty’s culture around transparency. In his blog post Vibing a Non-Trivial Ghostty Feature, he described how he uses tools like Amp to design and implement complex features, documenting the messy and experimental steps that most developers hide. The post captured the same philosophy that drives Ghostty’s contributor policy: AI can be part of the process, but contributors should show how it influenced their work so that reviewers can understand the intent behind each change.

Seeing the intent behind the code

What frustrates Hashimoto is not that people use AI, but the absence of visible reasoning.

“As a reviewer, I do not care what the AI said. The AI output is noise. I want to see the contributor’s thinking.”

When he opens a PR, he looks for signs of understanding: the prompts, the decisions, the corrections along the way. Bad PRs, he said, tend to show a “slop zone” where the contributor is clearly fishing for code without comprehension. “I want to see that you understand what you’re doing, or at least trying to.”

Well-structured AI sessions, by contrast, build trust. They reveal thought process and intention. For Hashimoto, that trail of reasoning is what separates a responsible contributor from a careless one. The checkbox saying “AI used” is not enough. What matters is the visible proof that a human actually thought through the work.

For Contributors: Don’t just say you used AI. Show how you used it. Your prompts tell the story of your thinking.

Learning to drive with AI

Hashimoto is not only a maintainer, reviewing AI-assisted work. He uses AI daily and experiments with different workflows. For planning and exploration, he often runs multiple coding agents side by side, comparing their results. “Usually no one agent wins,” he said. “One captures the main idea. Another remembers an edge case. I pull the best parts together by hand.”

This ensemble approach costs more time and compute, but it helps him triangulate solutions. It also highlights a broader truth: AI is not a single oracle, but a chorus of imperfect advisors.

When it comes to implementation, he enforces one rule on himself. “If the AI writes something I do not understand, I stop and study it,” he said. “I try to recreate it myself. If I cannot reach the same diff, I need to learn more.”

Despite being an experienced systems programmer, he calls himself “a very inexperienced JavaScript front-end person.” When the AI generates front-end code, he reads through it line by line to understand the imports, data flow, and dependencies before committing anything.

He treats AI not as an answer machine but as a learning accelerator. It lets him build something real first, then study it deeply enough to make it his own.

For Contributors: Never commit code you cannot explain. AI should help you learn faster, not think less.

Better scaffolding for contributors

Rather than hope contributors discover effective workflows by chance, Hashimoto has started shipping small helper tools directly in the Ghostty repository.

One of his favourites is a custom Amp slash command he built that fetches GitHub issues and reformats them into clean Markdown for AI planning sessions. “I use it five times a day,” he said. Commands like this give contributors a clean starting point for structured reasoning before they even begin generating code.

Hashimoto draws a line between tooling that guides good habits and tools that just generate noise. “The engagement-bait trend of massive prompt libraries,” he said, “that’s just noise.”

Scaffolding, for him, is not about automation but about making good behavior easy and visible. The right structure helps contributors think more clearly and makes their reasoning visible to others. When the repository itself encodes these habits, people do not just read the guidelines, they practice them with every contribution.

For Maintainers: Don’t just write contribution rules or guidelines. Build and ship the actual tools that embody your project’s best practices for AI-assisted contribution.

The next generation of developer tooling

Prompt blame: tracing code back to intent

Hashimoto’s vision for better tooling starts with accountability. He envisions a future system where version control can tell you not just who wrote a line of code, but why.

“It would be useful to point at a line of code and say what part generated this,” he said.

He calls one idea “prompt blame,” a nod to git blame. Instead of only showing who wrote a line, it would show which prompt created it and where the human stepped in. That kind of trace and visibility answers a familiar review question. Why did this change happen in the first place?

“Current AI tools show all the machine diffs but hide the human ones,” he said. “You lose the part where the human is actually thinking.”

Annotating AI sessions: the human commentary layer

For Hashimoto, visibility is not just about machine behavior but also human intent. He advocates for annotation, giving humans a way to mark parts of an AI session with notes such as: “This part was experimental. This part was me learning. This part actually informed the final PR.” It’s the difference between showing just your final answer and showing your thought process.. These annotations exist for the next human who reads the code.

Interleaving human and AI edits

The other gap he points to is temporal. Most coding tools show the AI’s diffs but not the developer’s.

“It shows all the AI diffs but doesn’t show the human diffs,” he said. “You lose the part where the human is actually thinking.”

Hashimoto imagines a unified history that interleaves both, where every refactor, correction, or course change by a person sits alongside the AI’s suggestions. Code review would then show a full collaboration, not a one-sided transcript.

The opening beyond Git

Experience with AI-assisted reviews has pushed Hashimoto toward a larger conclusion. Traditional version control was not designed for rapid human and machine collaboration.

“If someone wanted to invent a new version control system, this is the biggest opening since Git,” he said.

Git tracks authors and commits. It does not track the reasoning or conversations that produced them.

Git was built for snapshots, not for continuous, conversational iteration between humans and machines. Hashimoto’s advice to the team behind Jujutsu, where he serves as an advisor, reflects this thinking: make it agent-friendly. In his words, a modern system should “over-aggressively create commits”, capturing every micro-diff so humans and agents can safely experiment, revert, and compare ideas.

The real opportunity, he says, lies in metadata. “How do you attach the prompts? How do you attach co-authorship?” Git was not built to track the dialogue that produces a change. A new system could.

Intent: version control for the AI era

That question: how to attach prompts, reasoning, and co-authorship to real code history is exactly what SpecStory’s upcoming project Intent is designed to solve.

Intent is a new version control system built from the ground up for AI-assisted development. It automatically captures every AI conversation, links it to code changes, and creates a searchable decision timeline. Built on CRDTs (Conflict-free Replicated Data Types), it synchronizes work continuously without merge conflicts.

Where Git relies on human discipline to document changes, Intent captures context automatically. Imagine asking months later, “Why did we choose JWT instead of sessions?” and seeing the full conversation that led there: the alternatives discussed, the reasoning behind the choice, and the exact lines of code that came from it.

Key capabilities include:

• Automatic versioning: Every save becomes a versioned checkpoint.

• AI conversation tracking: Links code diffs to their originating chat sessions.

• Conversational search: Queries like “When did we add authentication?” return the full decision trail.

• CRDT-based sync: Real-time collaboration with no merge conflicts.

• Human-in-the-loop history: Interleaves AI-generated and human edits into one continuous timeline.

In many ways, Intent turns Hashimoto’s wishlist: prompt blame, session annotation, human-AI interleaving into infrastructure. It makes reasoning first-class, so context never gets lost.

For Maintainers: Version control should capture not just the code, but the conversations that shaped it.

For Contributors: The best contribution is one that shows how you thought not just what you typed.

The future of transparent collaboration

After hundreds of AI-assisted reviews, Hashimoto’s view is clear. Open source does not have an AI problem. It has a transparency problem. The goal is not to forbid AI. The goal is to make the human judgment in the loop visible.

He imagines a norm where sharing AI sessions is as common as sharing diffs, where maintainers can check not only what changed but why, and where contributors can demonstrate the care behind their work. “If people shared their sessions, it would help a lot,” he said. “I would have loved to see how my open source heroes actually built a feature.”

Culture and tooling will meet in the middle. Disclosure sets expectations. Reasoning trails and richer metadata make those expectations practical. That is the direction SpecStory is betting on. When the thinking travels with the code, teams move faster, communities stay healthier, and code review becomes a conversation grounded in intent rather than guesswork.

This is the story of how SpecStory turned that moment from disaster into recovery.

Building AI at Scale

One of our user, an ML Engineer at a leading LLM company spends his days building and training large language models. His workflow involves running agent-driven coding experiments at scale. Dozens of sandboxes, multiple sub-agents, millions of tokens being processed. It’s a high-output environment where mistakes are costly.

In the middle of one of these experiments, the coding agent deleted the entire repository.

The Accident

“In some shocking way, we had one agent running and it deleted the repo. At the same time, we had issues reading from GitHub, so we couldn’t just pull it back.”

It wasn’t just a missing file or a bad commit. The repository was gone and the work they had been building just vanished. At the same time, they had issues reading from GitHub, so GitHub recovery wasn’t an option either. The codebase looked permanently lost.

For a team building foundational AI models, this was the kind of setback that could derail weeks of work.

Recovery Through SpecStory

Instead of starting from scratch, the engineer turned to SpecStory.

“We put in the SpecStory histories that had recorded everything and asked our AI, Can you recreate all the code? It actually rebuilt the whole repo. That basically saved us.”

Because SpecStory had been running in the background, every AI-assisted coding session which had every prompt, correction, tool call, and code output, was preserved as a Markdown history with timestamp.

Those histories weren’t just records of what the agent produced. They captured the entire development flow:

• The commands and tool calls that had shaped the code

• The corrections when the AI got something wrong

• The design decisions debated and accepted along the way

Those histories didn’t just log the code, but the reasoning that produced the code and together, those were enough context for the AI to regeneratethe entire lost repo. What began as a simple history log became an accidental backup system.

Continuity in Fragile Environments

For this engineer, the benefits didn’t end there. His day-to-day workflow involves SSHing into GPU clusters where development pods frequently reset. Every reset wipes out Cursor’s chat history, forcing developers to restart without any context.

SpecStory changed that. By maintaining histories across all folders, it let him reconnect, resync, and immediately pick up where he left off. Even when the infrastructure churned underneath, SpecStory gave him continuity.

From Logs to LLM Training Data

The most unexpected use case came when SpecStory became part of the LLM training pipeline:

• Each sandbox run generated long traces of AI reasoning and code

• After each run, SpecStory synced and captured those traces

• The logs were converted into user-assistant format and fed directly into post-training datasets for their models.

What began as a convenience for developers grew into infrastructure for LLM training, providing high-quality synthetic conversations rooted in real coding tasks.

Lessons From the Workflow

This engineer’s story shows the multiple dimensions of value that SpecStory brings:

• Disaster Recovery: When an AI agent wiped a repo, SpecStory’s preserved histories made recovery possible.

• Persistent Context: In unstable dev environments, SpecStory acts as a durable memory layer when other tools lose state.

• Data Pipeline: At massive scale, SpecStory logs double as structured training data for fine-tuning LLMs.

The Bigger Picture

This story highlights a truth about AI-assisted coding: speed alone is not enough. Things go wrong, agents misfire, and tools fail. When that happens, the difference between starting over and moving forward depends on whether you have preserved the reasoning behind your code.

SpecStory does more than capture prompts. It records the why by preserving the flow of ideas, corrections, and intent. For our user, that record turned into a lifeline. For other teams, it can mean faster reviews, reproducible experiments, and protection against invisible technical debt.

As AI accelerates how we write code, understanding the choices behind that code becomes even more important. SpecStory ensures that the reasoning is not lost, and in moments like this, it can even save the code itself. Resilience in AI coding comes from context, and that is what SpecStory preserves.

Learn more:
SpecStory Docs: https://docs.specstory.com/
GitHub: https://github.com/specstoryai/getspecstory

The question is not whether AI belongs in open source, it’s already there. The real question is how to use it responsibly so that your contributions add value rather than create extra work.

If You’re Contributing with AI

The key to contributing responsibly is transparency. Maintainers do not need you to hide your tools, they need to understand your process.

• Always disclose what you used: Put it directly in your pull request description. Be specific: “Used Claude Code to generate the initial algorithm, wrote tests manually.” If you used AI for comments or documentation, say that too. Honesty sets the right expectations and builds trust.

• Show your process: Sharing your chat history can be surprisingly useful. Export your conversation from Cursor or Claude Code and link it in your PR. Tools like SpecStory make this simple by automatically saving your full session. Maintainers can then see how you arrived at your solution, which makes reviews faster and also helps others learn from your approach.

• Check the quality yourself: AI is not a substitute for your judgment. Review every line, write and test the edge cases. If something feels unclear, ask your assistant to explain it until you understand. Use that review as a chance to learn and strengthen your own reasoning. If you still cannot explain the code in your own words, it is not ready to submit. This is what separates helpful contributions from noise.

Here is a simple way to phrase disclosure in your PR:

• Minimal: “Claude Code assisted with this implementation.”

• Better: “Used ChatGPT to understand the codebase, implemented the solution manually.”

• Best: “Cursor suggested this approach (see linked chat history saved in SpecStory), and I modified it significantly to fit our use case.”

If You’re a Maintainer

Maintainers need to guide contributors clearly. Otherwise, every review risks turning into a guessing game about where the code came from.

• Set expectations up front: Add an AI section to your CONTRIBUTING.md. Explain that disclosure is required and why it matters. Point to examples of what good AI-assisted contributions look like. Mitchell Hashimoto’s Ghostty project is a good model: it requires disclosure and treats it as a normal part of collaboration.

• Review with care: Watch for telltale signs of low-effort AI code through inconsistent styles, over-complicated functions, or generic comments. When in doubt, ask for clarification. It is perfectly acceptable to reject contributions that add more burden than value. Remember, you are building for people, not training a model.

• Build community norms: The healthiest projects treat disclosure as routine, not shameful. Encourage contributors to share how they used AI, celebrate high-quality examples, and make sure newer developers learn what responsible usage looks like.

A Practical Guide to Disclosure

Not every use of AI requires disclosure. Simple autocomplete, syntax fixes, or variable name suggestions are part of everyday tooling. What does require disclosure is any substantial code generation, help with debugging, documentation, or architectural decisions. If AI shaped the contribution in a meaningful way, let others know.

Making It Work for Everyone

For contributors, treat AI like a junior developer. Let it propose ideas, but supervise carefully. Learn from what it suggests and build your own skills alongside it. Remember that on the other side of your pull request is a human maintainer with limited time.

For projects, AI-assisted contributions can become opportunities for growth. Share prompting strategies that work well. Build lightweight project guides so AI tools have the right context. And when a contributor does it right, highlight their PR as a positive example.

The Path Forward

AI is not replacing open source contributors. It is giving them new ways to participate. The challenge is making sure that speed does not come at the cost of quality. Sustainable collaboration depends on transparency, respect, and careful review.

Tools like SpecStory help by preserving not just the code, but the reasoning behind it. That context makes contributions easier to review, easier to learn from, and easier to trust.

The principle is simple: use AI as an assistant, not as a shortcut. Be clear about when and how you used it, check the quality yourself, and always remember there are people on the other side of your pull request.

That way you are not just making a contribution but you are helping projects thrive, and that is how you become the hero of the projects you care about.

Most people think AI coding is all about speed and treat their AI coding sessions as disposable. You generate the code you need, close the tab, and move on.

Isaac, one of the early SpecStory users, took a different path. After finishing a build session, he looked back at the SpecStory history and realized it wasn’t just a log of prompts and responses. It was a record of false starts, arguments with his AI pair programmer, and the reasoning behind each decision.

That history turned out to be more than a transcript. It became the outline of a blog post.

“The code shows what I built. The conversation shows why and how.” — Isaac Flath

What Isaac Did With His History

Isaac realized his SpecStory history was more than just a transcript. It captured the full flow of his coding session: the back-and-forth corrections, the points where the AI got things wrong, and the debates where he had to defend or rethink his design choices. He turned those conversation history into a blog post.

Here is how the history helped him:

• Concrete examples: The conversation transcript preserved the exact prompts and corrections he used, giving his writing authenticity and clarity.

• Capturing the process: The history included tool calls, failed attempts, and course corrections. These became vivid examples in his article, things he would have forgotten without a record.

• A natural outline: The decisions and debates formed a structure he could build on directly.

• Faster writing. With the history as source material, all he needed was to add his reflections and polish the language. The heavy lifting was already done.

You can read Isaac’s full breakdown here: Turning an AI Conversation into a Blog Post.

What Isaac’s Story Shows

Isaac’s experience highlights something every developer can use: AI sessions are not throwaway. With SpecStory, they can become valuable assets.

• Histories preserve intent. They capture not just the output but the thinking that shaped it.

• Details make stories stronger. Prompts and debates can be pulled directly into writing, tutorials, or documentation.

• Logs become raw material. A single AI session can produce both working code and a draft article to share.

Conclusion

SpecStory preserves the reasoning behind your code. This is the real value of SpecStory. It does more than log your AI prompts. It captures the decisions, debates, and intent that normally vanish once the tab is closed. That record is what makes your work reusable, reviewable, and teachable.

Most coding tools help you move faster in the moment. SpecStory ensures that the knowledge behind your work is not lost to the moment. It transforms AI sessions from disposable interactions into durable context you and your team can rely on weeks or months later.

The result is more than efficiency. It is a stronger codebase, faster reviews, smoother onboarding, and a shared memory of why things were built the way they were.

In a world where AI keeps accelerating how we write code, SpecStory safeguards something enduring: the understanding and intent that make code maintainable. Speed matters, but context endures.

Learn more:
SpecStory Docs: https://docs.specstory.com/
GitHub: https://github.com/specstoryai/getspecstory

• For strategy: Stop pretending backlogs are roadmaps. Use a venture-style model to drive big bets and clarity.

• For well-understood work: Skip the Agile theater and overhead. Shape Up + Lean, or just plan properly.

• For optimization: Switch gears into growth hacking with metrics, hypotheses, and experiments.
  
  

The goal isn’t to “be Agile.” It’s to choose the right tool, at the right time, for the right job.

In the world of software development, Agile has long been hailed as the ultimate solution to our productivity woes. It’s the Swiss Army knife of methodologies, the panacea for all project management ills. But here’s a hard truth: Agile is a hammer and sometimes we need a different tool.

The Rise of Agile: A Brief History

To understand why Agile has become such a blunt instrument, we need to look at its origins. Back in the 1990s, when grunge was king and the internet was just learning to crawl, software development was dominated by the waterfall model. Imagine building software like constructing a skyscraper: meticulous planning, rigid phases, and a prayer that nothing changes along the way.

Waterfall promised thorough upfront planning and cost estimation. It was the comfort blanket for businesses making investment decisions. Should we build new product Y or expand features of product X? Just look at the detailed Gantt chart and you’ll know!

But there was a tiny problem: software isn’t a skyscraper that can be fully architected up front. Requirements change, technologies evolve, and markets shift faster than you can say “Y2K bug”. Learning must be baked into parts of the process. Waterfall projects often ended up delivering outdated solutions to problems that no longer existed.

Enter Agile, the rebellious teenager of software methodologies. Born from the Agile Manifesto in 2001, it promised flexibility, customer collaboration, and the ability to respond to change. It was a breath of fresh air in a world of suffocating processes.

The Agile Advantage: When the Sledgehammer Hits the Nail

Let’s be clear: Agile, when applied correctly, can be incredibly powerful. Imagine a team working on a new feature for a rapidly evolving market. Requirements are fuzzy, user needs are still being discovered, and the competition is breathing down your neck.

In this scenario, Scrum (the most popular Agile framework) shines. Two-week sprints allow for rapid learning. Daily stand-ups keep everyone aligned. Sprint reviews provide regular checkpoints with stakeholders. It’s a beautiful dance of collaboration and adaptation.

But here’s the rub: not all projects are created equal. Sometimes, the rapid changes in requirements stem from internal dysfunction, unclear company direction, or simply a lack of proper planning. And this is where our Agile hammer starts to crack the foundation instead of building it.

When Agile Goes Awry: The Pitfalls of Misapplication

In my years as a product leader across companies of all sizes, I’ve seen Agile misapplied over and over again. Here are the common pitfalls:

1. The Two-Week Tunnel Vision: Teams become so focused on the sprint cycle that they lose sight of the bigger picture. They’re driving on a backcountry road at night with only a flashlight to guide their way.

2. Agile Theater: Daily stand-ups become status reports. Sprint planning becomes a rushed affair of throwing tickets into a sprint. Retrospectives become venting sessions with no real improvements.

3. The Planning Paradox: Scrum was designed for execution, not strategic planning. Yet, many organizations try to shoehorn their entire product strategy into this framework. It’s like trying to write a novel using only Post-it notes.

4. One Size Fits None: Agile is often applied indiscriminately, whether the project involves cutting-edge innovation or routine maintenance. We’re using a hammer to both hang a picture and plaster the wall.

The Fatal Flaws: Strategic Myopia and Misplaced Flexibility

The most damaging aspect of Agile’s misapplication comes in two flavors:

Failure Mode 1: Agile for Strategic Planning

One of the worst agile failures I’ve seen is a lack of strategic planning. Teams continually gather input from customers and stakeholders and capture it to their backlog. Then this backlog is used to create the team’s roadmap. This is backwards. Annual or quarterly planning requires a broader perspective, one that Agile’s iterative approach simply isn’t designed to provide.

But the problem goes deeper than just misapplying Agile. The root issue lies in how organizations approach strategic planning altogether. Typical quarterly planning processes cascade down the org chart, with each layer of management asking the one below it, “what’s your strategy and roadmap.” Ultimately this ends with teams themselves, unarmed and unprepared, being asked to answer these questions with little or no company direction or strategy. Here’s where things go off the rails:

1. Unarmed Teams: Teams are asked to strategize without being equipped with the right tools or context. They’re expected to produce a roadmap out of thin air.

2. The Agile Crutch: In the absence of better options, teams fall back on what they know – Agile. They squint at their backlog, trying to divine a strategic roadmap from a list of tasks. And what’s worse, most agile approaches dictate full team participation in all activities, translating into a massive waste of time creating a fake roadmap.

3. Perfunctory Planning: With limited time and resources, this “planning” becomes a box-ticking exercise. Teams want to minimize the time wasted on it and so treat it as an afterthought rather than the critical activity that it is.

4. The Management Cop-Out: Managers and leaders often contribute little more than a crappy template and a litany of Google Docs comments. Their primary role becomes concatenating the results from their teams, adding little strategic value.

5. Misaligned Outcomes: The result? A collection of bottom-up tactical plans masquerading as strategy, often misaligned with the company’s broader goals and market realities.

This approach fundamentally misunderstands the nature of strategic planning. It’s like asking a chef to plan next month’s menu by looking at today’s grocery list.

Failure Mode 2: Agile for Well-Understood Deliverables

Not every project is a journey into the unknown. Sometimes, the requirements are clear, the technology is familiar, and the path is well-trodden. In these cases, the overhead of Agile ceremonies can actually slow things down.

The misapplication of Agile here is more than just a minor inefficiency, it’s a fundamental mismatch that creates a host of issues:

1. Limited Visibility: Agile, particularly Scrum, typically provides visibility only into the next two-week sprint. For well-defined projects, this artificial shortsightedness is unnecessary and counterproductive. We’re choosing to wear blinders when we could have a clear view of the road ahead.

2. False Sense of Flexibility: We treat these projects as if they’re in constant flux, when in reality, they’re not. This mindset often leads to unnecessary pivots and changes, introducing instability where stability would be more beneficial.

3. The Planning Crutch: Agile can become an excuse to avoid thorough upfront planning. We tell ourselves, “We’ll figure it out as we go along,” even when we have enough information to make solid plans from the start. If you start building a deck without a rough plan, just be ready for many trips back to the lumber yard.

4. Misallocated Effort: The time and energy spent on Agile ceremonies (daily stand-ups, sprint planning, retrospectives) for well-understood work is often disproportionate to the value they provide. We don’t need a committee meeting to change the batteries on our smoke detector.

5. Lost Predictability: One of the key benefits of working on well-understood problems is the ability to predict timelines and outcomes more accurately. By defaulting to Agile, we forfeit this advantage, choosing perpetual uncertainty over achievable predictability.

It’s important to note that advocating for more upfront planning doesn’t mean a full return to Waterfall. There’s a middle ground where we push ourselves to ask and answer tough questions early on, without falling into the trap of trying to plan every detail in advance.

By recognizing when a project is well-understood, we can choose a more appropriate methodology that allows for clearer long-term visibility, more accurate predictions, and less ceremonial overhead. This approach not only saves time and resources but also provides the broader organization with the predictability it needs for effective planning and coordination.

The Way Forward: Precision Tools for Precision Work

So, if Agile isn’t always the answer, what is? We need a more nuanced approach, one that matches the methodology to the nature of the work. Based on the successes and failures that I’ve seen and lived, here’s what I propose:

The Venture Model for Strategic Planning

Seeing new product development through the eyes of an investor can provide a more effective framework for strategic planning and innovation. This approach:

• Better characterizes the inherent risks and uncertainties

• Allows for different criteria and metrics at various stages of product maturity

• Provides a framework for making informed bets on innovation

Let’s dive deeper into how the venture model works and how companies can adapt it:

Key Aspects of the Venture Model

1. Clear Stage Awareness: Venture-backed companies know exactly what stage they’re at (pre-seed, seed, Series A, Series B, etc.) and what their next focus should be. This clarity drives their strategy and execution.

2. Fixed Investments: Unlike the open-ended budgets often seen in corporate projects, ventures receive fixed investments tied to specific milestones.

3. Pitching for Resources: Teams must pitch to raise money at key inflection points, forcing them to articulate their progress and future plans clearly.

4. Embracing Failure: Ventures that don’t prove themselves out at a given stage are allowed to fail, ensuring resources are allocated efficiently.

5. Lean Teams: Venture teams are typically just big enough for the task at hand. Roles often blur as people do whatever it takes to move the project forward.

6. Aligned Incentives: Team members are heavily invested in a successful outcome, with personal rewards tied directly to the venture’s success.

7. High Autonomy: While investors (acting as board members) can provide input, they don’t dictate day-to-day operations. Control is exercised primarily through funding decisions and the ability to replace leadership.

Adapting the Venture Model for Companies

When implementing a venture model within a company, it’s crucial to recognize and leverage the unique advantages of the corporate environment while being aware of potential limitations:

1. Simulating Investor Breadth: While startups can pitch to hundreds of potential investors, internal ventures have a limited pool. Companies can simulate this breadth by empowering multiple executives with independent investment budgets.

2. Expanding Pitch Exposure: Real VCs hear thousands of pitches annually. To broaden perspective, companies could consider allowing outsiders to pitch ideas as well. This could be more insightful and more interesting than traditional job interviews.

3. Leveraging Horizontal Assets: Unlike standalone startups, internal ventures can tap into valuable company-wide assets:

• Recognized Brand

• Existing Distribution channels

• Customer Data

• Compliance support

• Ties into existing customer workflows

• Network effects across users and partners

• Amortized overhead (e.g. facilities, HR, legal)

It’s crucial that the entire portfolio of internal ventures leverages these strengths.

• Utilizing Horizontal Support Teams: Companies have an advantage over traditional VC networks in their ability to provide robust internal support. Organize these horizontal teams as services that internal ventures can easily plug into, similar to best-in-class SaaS solutions.

By adopting this venture model approach, companies can foster a more dynamic, accountable, and innovative environment for strategic planning and new product development. It allows for clearer goal-setting, more efficient resource allocation, and a balance between autonomy and accountability that often eludes traditional corporate structures.

Learn more: I haven’t found a great source for details on the Venture Model inside companies. For now, learn all you can about pitching startup ideas and running lean.

Shape Up + Lean When It’s Time to Execute in a Clear Direction

For projects with clearer parameters, a combination of Shape Up and Lean principles can provide a more effective approach than traditional Agile methods.

Shape Up: A Brief Overview

Shape Up is a methodology that emphasizes thoughtful upfront planning (shaping) followed by focused execution. It was developed by 37signals as an alternative to traditional agile methodologies. Here are the key aspects of Shape Up:

1. Shaping is Distinct from Implementing: Shaping is a separate activity that happens before any project begins. It’s about defining the problem, roughing out a solution, and setting boundaries.

2. Blurred Lines Between What and How: Unlike traditional approaches where product managers define “what” and developers figure out “how,” Shape Up encourages a more integrated approach where these lines blur during the shaping process.

3. Dedicated Time for Shaping: Shaping drives the process and is not an afterthought. It gets dedicated time and attention, ensuring that projects are well-defined before they begin.

4. Small Team for Shaping: The entire team doesn’t participate in shaping. Instead, an individual or a very small group does this work, allowing for more focused and efficient planning.

5. Complete Projects, Not Tasks: Teams are given complete projects, not a list of tasks. The shaping process provides clear business challenges, boundaries, and guidelines without prescribing an overly detailed solution.

6. Projects as Commitments: Projects that don’t get completed in the allotted time (typically weeks) don’t automatically continue. This creates a sense of urgency and helps prevent scope creep.

7. Flexible Implementation: While Shape Up provides a framework for planning and scoping, teams have the flexibility to choose their working methodology for the implementation phase.

Integrating Lean Principles

As noted, once a project has been shaped, teams can adopt any methodology they choose. But one especially effective approach is to use Lean principles for the implementation phase. Lean, with its focus on eliminating waste and continuous improvement, complements the Shape Up methodology well. Here’s how they can work together:

1. Kanban for Workflow Management: Use a Kanban board to visualize and manage the workflow of the shaped project. This aligns with Lean’s principle of visualizing work and limiting work in progress.

2. Continuous Flow: Instead of fixed sprints, adopt a continuous flow of work, pulling new tasks as capacity becomes available. This reduces the overhead of sprint planning and aligns with the Shape Up ethos of giving teams complete projects.

3. Just-in-Time Planning: While the overall project is shaped upfront, detailed task planning can happen just-in-time, aligning with Lean principles and allowing for adaptability within the project boundaries.

4. Focus on Value: Both Shape Up and Lean emphasize delivering value to the customer and the business. Use this shared focus to guide decision-making throughout the project.

5. Continuous Improvement: Be judicious with team retrospectives to identify areas for process improvement. Lean principles would encourage just enough reflection at just the right time and no more. Rather than wait for or plan separate retros, encourage process improvement at any time.

By combining Shape Up’s thoughtful upfront planning with Lean’s efficient execution principles, teams can benefit from:

• Clearer long-term visibility (typically 6-8 weeks)

• More accurate predictions of project outcomes

• Reduced ceremonial overhead compared to traditional Agile methods

• Improved focus on delivering value

• Greater flexibility in day-to-day work management

This approach not only saves time and resources but also provides the broader organization with the predictability it needs for effective planning and coordination, all while maintaining the flexibility to adapt to changes within the project scope.

Learn more: Shape Up from 37signals and a good article on using Trello to implement Kanban.

Growth hacking for product optimization

When your main objective is to improve adoption or usage of your product, it’s time to switch gears into growth hacking mode. This approach is fundamentally different from new product or feature development, focusing instead on measurable outcomes, hypotheses, and experiments.

Understanding the Product Funnel and AARRR Metrics

At the core of growth hacking is the product funnel, often represented by the “Startup Metrics for Pirates” or AARRR:

1. Acquisition: How do users find you?

2. Activation: Do users have a great first experience?

3. Retention: Do users come back?

4. Referral: Do users tell others?

5. Revenue: Can you monetize?

These metrics provide a framework for understanding and optimizing each stage of the user journey.

The Growth Hacking Process

Here’s how to approach growth hacking effectively:

1. Measure First: Before you can improve, you need to know where you stand. Establish baseline metrics for each stage of your funnel.

2. Create Hypotheses: Formulate ideas about what might improve your metrics. Crucially, define desired outcomes upfront to avoid bias. A good hypothesis includes both the expected positive impact and potential negative effects on other metrics.

3. Prioritize: Use your baseline measurements to prioritize hypotheses that are likely to have the highest impact. Focus on the areas of your funnel that need the most improvement or that align with your current business goals.

4. Run Experiments: Design and execute tangible tests for your hypotheses. This is where the rubber meets the road in growth hacking.

5. Analyze and Iterate: Based on the results of your experiments, refine your approach and start the cycle again.

Tips for Effective Growth Hacking

• Step Back from Your Product: Adopt an outside-in, customer-first view. What’s on your users’ minds? What do they want, regardless of what you want them to want?

• Use Statistics Wisely: Learn enough about statistics to run experiments correctly, or find someone (or a tool) who can. If you can’t run quantitative experiments, qualitative ones can still provide insights.

• Balance Experimentation and Intuition: Just because you can experiment doesn’t mean you should. Use experience and intuition to short-circuit endless experimentation. Sometimes, you can turn a complex A/B/C/D test into a simple A/B test, saving time and resources.

• Know When to Switch Gears: If you find yourself unable to run meaningful experiments, it might be a sign that you’re using the wrong tool at the wrong time. Consider if you’re in a phase where Agile for learning might be more appropriate than optimization experiments.

When to Use Growth Hacking

Growth hacking is most effective when:

• You have a product with a clear value proposition

• You’re looking to optimize specific stages of your funnel

• You have enough users to run statistically significant experiments

• You’re able to implement and measure changes quickly

By adopting this data-driven, experiment-focused approach, you can systematically improve your product’s performance and drive growth. Remember, the key is to stay focused on measurable outcomes and to always keep your users’ needs at the forefront of your optimization efforts.

Learn more: Step-by-step overview of growth hacking. Or, for more depth, the free and paid materials from Reforge are very good.

And Yes, Agile for Accelerated Learning

When the thing you need most is rapid learning in the face of a complex and quick-moving market, an agile approach can be well-suited to the task. However, the term “Agile” has been so overused and misapplied that it’s almost lost all meaning. There are entire books, consultancies, and corporate transformations dedicated to Agile adoption, often with conflicting advice.

Assessing Your Current Approach

If your current approach is working well and genuinely results in rapid learning, stick with it. Make minor tweaks and improvements as most agile methodologies would suggest. But how do you know if you’re getting the learning you need?

Here’s a quick test: Ask one of your agile teams to name the three most surprising things they’ve learned in the past two sprints. If you get nothing substantial back, it could mean one of two things:

1. The team doesn’t actually need to learn and is using the agile sledgehammer unnecessarily.

2. They’re not using agile effectively for learning.

Starting Fresh with Scrum

If you’re not getting the learning you need, consider adopting a new methodology wholesale. For a clean slate, I recommend Scrum. It’s concrete, clear, and well-established. Scrum provides a framework and terminology that your teams can quickly understand, with built-in mechanisms for continual improvement.

Key elements of Scrum include:

• Defined roles: Product Owner, Scrum Master, Scrum Team

• Clear artifacts: Product Backlog, Sprint Backlog, Shippable Product

• Standardized Rituals: Sprint Planning, Daily Standups, Sprint Review

• Continuous learning: Sprint Retrospectives, Improvement and customization

When adopting Scrum, resist the urge to cherry-pick practices at first. Give teams the opportunity to experience all aspects of vanilla Scrum before they drop or alter some parts. This may seem counterintuitive, but it’s actually easier to start with the whole thing and then make thoughtful changes, rather than trying to build up bit by bit.

Tips for Effective Agile Learning

1. Customer Collaboration: Ensure you have a real customer working closely with your agile team. This direct connection is crucial for rapid learning and validation.

2. Measure Learning, Not Just Delivery: Focus on the speed of learning versus the speed of delivery. Agile is about delivering software that aligns with real customer needs, not just about quickly pushing out features.

3. Embrace Uncertainty: Accept that in complex, fast-moving markets, you don’t have all the answers. Use agile practices to explore and learn rapidly.

4. Frequent Reflection: Use sprint retrospectives not just to improve processes, but to explicitly discuss and document learnings about the market, customers, and product.

A Word of Caution

Please, if you take nothing else from this, don’t force all of your teams to start practicing Scrum (or any other agile methodology) today. Acknowledge that different teams are at different phases in their own projects and need to choose the right tools for their specific situations.

Instead:

1. Arm your teams with a variety of tools in their planning toolbox, including the ones we’ve discussed in this article.

2. Help them gain the wisdom to know when to switch tools.

3. Foster a culture where it’s okay to experiment with different methodologies and learn from the results.

Remember, the goal is not to be “Agile” for the sake of it, but to create an environment where teams can learn rapidly and deliver value effectively. Sometimes that means using Scrum, sometimes it doesn’t. The key is having the flexibility and insight to choose the right approach for each unique situation.

Learn more: The Scrum Framework, in detail.

Conclusion: The Right Tool for the Right Job

Agile isn’t inherently flawed; it’s how we’ve been wielding it that’s the problem. It’s time to expand our toolkit. By adopting a more nuanced approach, we can enjoy the benefits of Agile where it truly shines while using more appropriate methods for strategic planning and well-defined projects.

Remember, in the world of product development, one size does not fit all. Sometimes you need a sledgehammer, sometimes a screwdriver, and often, you need both. The key is knowing when to use each.

So the next time someone suggests “Let’s do this project Agile,” take a step back and consider: What’s the right tool for each phase of this project? Your future self (and your team, and your stakeholders) will thank you for choosing the right tools for the right jobs, rather than forcing the entire project into a single methodology.

Don't Harsh Our Vibes

The "vibe" label sells short what's happening with coding agents. "Vibe" implies this technology is a toy—just faster autocomplete or smoother Stack Overflow. When you ship production software, you throw the vibes away and use your same old workflow.

Our experience is different. Agents are meaningfully changing how engineers build production software. Companies are reorganizing around agentic coding—this isn't a toy.

Our friends at Assignar are using agentic coding workflows to build complex construction finance management software. GitHub Copilot coding agent, Cursor Bugbot, and Claude Code /security-review all play a role on the team. -Jake

But the Vibes Aren't Immaculate

We're on the agentic bandwagon, but we can't just wait for big companies to throw billions at their models and call it a day.

Here's why: these models run at an unimaginable scale, but they remain constrained by the data that they have access to. They learn from code, documentation, Stack Overflow posts—anything written down. But if something isn't in the text, the model doesn't know about it.

And so much of what makes software engineering hard was never written down. The crucial context lives in engineers' heads, in Slack threads that get buried, in whiteboard sessions that were never photographed. The models can't learn what was never captured.

Code Is Just an Approximation of Intent

Our codebase isn't the truth—it's just what happens to run. The actual truth is the intent: what we wanted the software to do, what constraints we faced, what tradeoffs we made. When something breaks, you need this intent to fix it properly. Without it, you might fix the bug but break the use case, optimize the wrong thing, or undo a critical workaround.

I’ve used agentic coding tools to build entire new features, like the markdown editor inside BearClaude, only to have it create a regression in the Chat History view (a completely unrelated part of the code base). When “vibing”, manual smoke tests are typically the answer for spotting regressions. But when software engineering with AI assistance, we need something more thoughtful. -Jake

The False Revolution: New Panes of Glass

As engineers, our natural tendency is to solve problems with new layers of abstraction. Let the agents handle the messy details underneath while we work at a higher level. Ambitious projects like plain-lang—which lets you code in plain English sentences—are attempting precisely this, defining a natural language abstraction that simplifies everything below.

It's a compelling vision. But abstraction layers rarely eliminate complexity—they just relocate it.

At Sym, we fell into this trap. We created elegant devtools for just-in-time AWS access. You could request permissions through our clean interface: "I need production database access." Beautiful.

Except first, teams had to untangle their existing AWS permissions. "We have a role called 'WebAppProd' with... who knows what permissions? Created three years ago, modified seventeen times, attached to twelve services." Before using our "simplification," they needed to understand both IAM and our abstraction of IAM. We'd added another pane of glass, not removed the complexity underneath. -Jon

The same pattern awaits AI coding abstractions. As these natural language systems grow complex, they'll need all the same tools any codebase needs. Natural language debuggers. Natural language version control. Natural language merge conflicts. We end up reinventing the wheel at a new level of abstraction, now maintaining two layers of complexity instead of one.

The Real Revolution: A New Abundance

The middle way is paradoxical: it's revolutionary precisely because it's not trying to be revolutionary. It's about finally doing what we always knew we should do: Documentation. Tests. Clear specifications. Design discussions. Architecture decisions. Code reviews that review thinking, not just syntax.

We skip these because they're too expensive. But AI creates a new abundance. When documentation becomes nearly free, you stop rationing it. When test writing takes seconds, not hours, you stop skipping it.

Now when I finish working on something, I ask the agent: "Update the tests and docs." "Can you help me DRY up this code?" This often takes seconds and sometimes uncovers an issue I missed. These tasks used to be the TODOs that haunt a codebase—things we'd "definitely get to in V2." The difference isn't that I'm working faster; it's that I'm actually completing the work. The boring, essential parts that make code maintainable are finally getting done. -Jon

What Actually Changes

What changes:

• Code review becomes intent review—PRs without documentation get rejected

• Context persists across time and team changes

• Standards rise as costs drop—incomplete work becomes unacceptable

• The "nice-to-haves" become table stakes

What doesn't:

• Humans specifying intent—this gets more important, not less

• The complexity of understanding existing systems

• Software evolution and changing requirements

• Bugs, edge cases, and the fundamental challenges of building software

What We Still Need to Figure Out

Feedback Loops

Encoding intent at project start isn't enough. When you explain to an AI what you're building, when you iterate on approaches, when you ask it to explain existing code—all that context usually evaporates. What if it didn't?

What if these artifacts could be validated and refined over time? Fix a bug, update the intent. A new team member discovers gaps; they fill them in. This creates a virtuous cycle instead of entropy. We’ve learned from the agile revolution that overly precise up-front specification doesn’t leave room for learning and iterating. So the best intent-driven workflow needs to allow people to work iteratively and stay in flow while still capturing each new learning and decision.

This is a big part of why we’ve built SpecStory as a connector to existing AI coding tools. It allows developers to stay focused on the task at hand, defining and delivering great software, while recording a clean log of that definition. This way, 2 months from now, when you need to remember “why did I decide to go with a JSON field in my database instead of multiple columns?” you can ask that exact question of your own AI chat history. -Jake

The Real Vibes Will Not Be Televised

The televised version is what gets clicks—programming languages that look like English, YouTube demos of full apps built in an afternoon, breathless threads about replacing all engineers.

However, the real revolution occurs in the unglamorous daily practice. It's in the PR rejected because the documentation doesn't align with the intent. It's in the feedback loop that catches drift between code and docs. It's finally having time to write architecture decision records because agents handle the boilerplate.

Coding agents give us the resources to do all the things we always should have done. If we can encode software engineering components into something agents understand, we can truly "make it so."

How are you refining your simple daily practices to take advantage of the real power of AI-assisted software development?

This piece grew out of a conversation about how AI is actually being used in software development today. We'd love to hear what you're seeing in your own work.

Jon is a founding engineer at Distill, a platform for learning about people and companies. Previously, he co-founded Sym, a devtool for security engineers, and led engineering teams in health tech, infrastructure, and enterprise software.

Jake is the co-founder of SpecStory, a tool that helps developers preserve and share their AI coding sessions. Before SpecStory, Jake led product teams at Docker and DigitalOcean.

Watch the conversation here:

Understanding Intentional vs. Unintentional Underspecification

The critical distinction lies in purposeful design. Intentional underspecification serves as a strategic tool for discovery, while unintentional vagueness leads to unpredictable or suboptimal outputs. This technique requires careful consideration of when precision is essential versus when exploration adds value.

Practical Applications for Underspecified Prompts

1. Data Model Design

• Instead of: "Create a PostgreSQL schema with users, posts, and comments tables"

• Try: "Design a data structure for a community discussion platform"

• Benefit: AI may suggest alternative approaches like graph databases for relationship-heavy data or document stores for flexible content structures

2. UI/UX Design Exploration

• Instead of: "Create a React form with email and password fields using Material-UI"

• Try: "Design an onboarding experience for a meditation app"

• Benefit: AI might propose progressive disclosure patterns, biometric authentication options, visual breathing exercises during loading, or gamification elements you hadn't considered

3. Sample Data Generation

• Instead of: "Generate 10 user records with name, email, age, and registration date"

• Try: "Create realistic sample data for a fitness tracking application"

• Benefit: AI often includes relevant patterns you might overlook, like seasonal variations, user behavior clusters, edge cases

4. Architecture Decisions

• Instead of: "Implement this as a REST API with PostgreSQL"

• Try: "This system needs to handle real-time collaboration for distributed teams"

• Benefit: Opens possibilities for WebSocket implementations, event-driven architectures, or hybrid approaches

5. Technology Stack Selection

• Instead of: "Use React with Redux for state management"

• Try: "Build an interactive dashboard for data visualization"

• Benefit: May surface alternatives like Vue with Pinia or even specialized visualization frameworks

Implementation Strategy

1. Identify Exploration Opportunities

   • Early-stage design decisions

   • Proof-of-concept development

   • Architecture evaluation phases

   • Creative problem-solving scenarios

2. Run Parallel Experiments

   • Submit the same underspecified prompt multiple times

   • Collect diverse approaches

   • Request comparative analysis of the generated solutions

3. Apply Constraints Post-Generation

   • After receiving initial suggestions, introduce your specific requirements

   • Ask the AI to evaluate options against your constraints

   • Iterate based on insights gained

4. Engage in Clarifying Dialogue

   • After receiving an initial proposal, prompt the AI to ask clarifying questions

   • Example follow-up: "What questions would you need answered to determine if this approach or an alternative would work better for my specific context?"

   • This technique surfaces hidden assumptions and unconsidered constraints

   • The AI's questions often reveal critical factors you hadn't explicitly considered

Framework for Decision Making

Consider these questions when deciding specification level:

• Is this a greenfield opportunity or constrained by existing systems?

• Would alternative approaches provide significant value?

• Are there established patterns that must be followed?

• Is this exploratory work or production implementation?

Practical Example: Storage Solution Selection

Rather than specifying "implement SQLite for local storage," consider:

1. Describe the context: "Small application, local deployment, structured data with relationships"

2. Review AI suggestions: might propose SQLite, but also IndexedDB for browser-based apps, or embedded key-value stores

3. Engage in dialogue: "What questions would help determine the best storage solution for this use case?"

4. Evaluate trade-offs: request analysis of each option based on the clarified requirements

5. Make informed decision: choose based on comprehensive understanding rather than initial assumptions

Key Takeaways

• Underspecification is a tool, not a default approach

• Use it deliberately during exploration and design phases

• Leverage AI as a thought partner for discovering possibilities

• Engage in iterative dialogue to uncover hidden requirements

• Always validate suggestions against your specific requirements

This balanced approach to prompt engineering enables developers to harness AI's creative potential while maintaining control over critical decisions. The goal is not to abdicate responsibility but to expand the solution space before converging on optimal implementations. By treating AI as a collaborative partner that can both propose solutions and help refine requirements, we create a more robust decision-making process that combines human insight with machine exploration.

At one point I was a "serious hobbiest" photographer. I had grown up in a house with a darkroom, made an early switch to digital, and have had an SLR for most of my life.

But the proliferation of photographs - orders and orders of magnitudes more than there had been just a decade before left me creatively paralyzed, overwhelmed by the sense that every possible image had already been captured countless times.

Then I came to realize that the jagged edge that defined photography as art, had changed. The next photo artist wouldn't produce novelty in the same way Ansel Adams had decades before. Instead, projects that made use of millions of photographs became interesting, like Photosynth from Microsoft Research:

Which eventually was used in Microsoft Flight Simulator to create buildings and terrain across the entire world.

I even started a company at this jagged edge— Art Moments let people turn their snapshots into artwork by printing them on watercolor paper and canvas (now a common offering from Shutterfly and others).

Entire forms of media, like Instagram, opened up and we found new ways to communicate with each other.

We're at the Photosynth moment for software.

And just as photography evolved from a specialized craft to a ubiquitous medium of expression, software development is undergoing a similar transformation.

Today, the barriers to creating software are dissolving. Tools that once required deep technical expertise now welcome newcomers with intuitive interfaces and assistive capabilities. The proliferation of AI code generation assistants, and large language models has democratized creation in ways unimaginable just a few years ago.

But this doesn't mean the end of craft—rather, it signals a shift in what we value. Just as the photographer's eye became more crucial than darkroom techniques, today's software creators are valued for their vision, problem-solving abilities, and human-centered design thinking over syntax mastery.

The most interesting software emerging today isn't distinguished merely by its technical implementation but by how deeply it understands human needs and contexts. The new literacy isn't just writing code—it's writing code that matters.

Some lament this change, just as photographers once mourned the loss of exclusivity. But I've come to see it differently. When millions can build, the question becomes not "Can you make software?" but "What will you make, and why does it matter?"

This democratization opens doors to voices previously excluded from the conversation. People with domain expertise but without traditional coding backgrounds can now build solutions to problems they intimately understand. Healthcare workers creating patient management systems. Teachers developing custom learning tools. Community organizers building platforms for collective action.

The future belongs not to those who can write the most elegant algorithms, but to those who can imagine new possibilities at the intersection of human needs and technological capabilities.

So rather than feeling sad or unmotivated by this sea change, I've found renewed purpose. Just as photography evolved into new art forms and communication channels, software development is becoming something richer, more diverse, and potentially more meaningful than before.

The skills that matter now are empathy, systems thinking, ethical reasoning, and creative problem-solving. Technical knowledge remains important, but as a means rather than an end.

Empathy: Consider the story of Ava, who built an app to help seniors manage medications. Her first version, though technically flawless, confused its target users. Rather than blaming "user error," she spent a week observing her grandmother navigate the interface. She discovered assumptions she'd made about comfort with technology that simply weren't true. The redesigned app eliminated technical jargon, increased touch targets, and incorporated familiar physical metaphors like a pill box. Usage soared not because Ava wrote better code, but because she stepped outside her own perspective.

Systems thinking: Take Marco, who was tasked with creating yet another customer management portal. Instead of building everything from scratch, he mapped the ecosystem of available tools and services. He orchestrated APIs from existing payment processors, integrated an open-source analytics platform, and leveraged authentication services rather than reinventing them. The result wasn't just a CRUD app, but an interconnected system that shared data across previously siloed departments. Marco's value wasn't in writing every line of code, but in understanding how pieces could work together to create something greater than the sum of its parts.

Ethical reasoning: When Priya's team built an AI-powered hiring tool for a large corporation, initial tests showed it favored candidates from prestigious universities and those with traditionally male names in technical roles. Rather than deploying what seemed "objectively" effective, Priya insisted on examining these patterns. She advocated for rethinking what metrics constituted a "good" employee and diversifying the training data. The revised system identified candidates who had been historically overlooked yet performed excellently. The most valuable line of code Priya wrote wasn't an algorithm—it was a question about who their system might be leaving behind.

Problem-solving: Jamal was developing software for a hospital when he noticed nurses spending hours manually entering data from one system to another. The conventional approach would have been to automate this specific task. But by asking "why does this transfer need to happen at all?" Jamal discovered two systems that should have been talking to each other but weren't. Rather than coding a sophisticated transfer tool, he created a simple integration between existing systems. The solution required relatively little code but saved thousands of hours and reduced errors. The most important problem he solved wasn't at the code level, but at the workflow level.

We're just beginning to see what this new era might bring. My vision for this future is both practical and transformative:

• Interfaces will feel intuitive not because they follow universal design principles, but because they're created by the very people who use them daily

• Software will become ephemeral and situational—like snapshots, applications can serve their purpose for a moment without needing to be preserved in a digital museum

• Complex systems will emerge through composition, as we build increasingly sophisticated solutions atop existing technologies rather than starting from scratch

• Hyper-personalized software will proliferate, with applications tailored not just to demographic segments but to individuals and specific communities

• We'll witness the rise of software ecosystems where millions of specialized applications can seamlessly work together, creating capabilities greater than any single platform

How to Adapt Now

So how do you navigate this shift? How do you ensure you're riding this wave rather than being swept under by it?

Embrace the disposable nature of code. Your work isn't precious—it's a means to an end. The artifact that matters is the solution, not the implementation. This mindset frees you to create multiple rapid prototypes, test hypotheses quickly, and pivot without emotional attachment to what you've built.

Learn to build, regardless of your background. There's no longer an excuse to be merely a consumer of technology. Even if you never intend to code professionally, understanding how to create simple tools gives you agency in a software-mediated world. Start small—automate a repetitive task, build a simple app to solve your own problem.

Practice just-in-time skill acquisition. Focus on making things you care about, and learn what you need as you go. The person who attempts to master everything before creating anything will be perpetually preparing. Instead, set ambitious goals and let necessity guide your learning path.

Like photography before it, software is becoming a medium through which we understand and reshape our world—not just a technical discipline, but a form of expression, connection, and transformation available to all.

The future is being written in more voices than ever before. Make sure yours is among them.

AI tools like Cursor, Cody, and Copilot make it easier than ever to enter the zone and stay there. You can go from idea to prototype in hours. It feels amazing, almost like flying.

But here’s the thing we’ve learned firsthand: Just because one person is flying doesn't mean the whole team is moving forward.

At SpecStory, we’ve seen this dynamic play out on our own team.

One person might hit a hot streak with AI and prototype something over a weekend, creating a sense that we’re nearly finished.

But “done” is a mirage.

Because getting code into production means that it meets the bar, that it fits the plan, that works with the rest of our system. And it still takes lots of coordination. And AI doesn’t (yet) handle:

• Prioritization

• Clear outcomes

• Communication between teammates

• Roles and responsibilities

• Quality and supportability expectations

A couple months ago, we rapidly prototyped our sharing functionality in just a few days.

We were pumped. It worked.

But it still took two more weeks before we could ship it.

Not because of blockers, but because the rest of the team needed time to process the work from their own perspectives: how it impacted design, how it fit into the broader experience, and how it would be supported.

So yeah, personal flow is real. But team flow? That’s the next frontier.

I spoke with dev teams at Assignar and Instacart. They share the same feeling.

AI tools are delivering at the individual level.

But teams are still tripping over the same coordination problems we’ve always had.

We think team flow looks different.

It’s not just everyone in personal flow at the same time. It’s shared clarity. Shared pace. Shared outcomes.

It involves:

1. Clearly preserving intent so teammates can easily follow your path

2. Reducing friction between shaping ideas and building solutions

3. Sharing ownership instead of merely handing off tasks

SpecStory is our bet that team flow is the unlock.

The magic isn’t just in how fast you can move. It’s in how fast we can move together.

🔌 Does this resonate? We’re actively recruiting Design Partners who believe human review matters more than ever. Help shape the next evolution of our product!

But I believe we're headed for an even leaner future: the one-pizza team.

Why Teams Will Shrink

Let me be clear: I'm not in the "AI will take all our jobs" camp. In fact, I believe the opposite. Thanks to Jevons paradox - where technological efficiency improvements increase (rather than decrease) total resource consumption - we'll likely build more software than ever before, requiring more developers than we have today.

Ray Kurzweil predicts we're on a path to "imbue every atom in the universe with intelligence." Even if he's only half right, we have an unfathomable amount of software yet to build.

But the teams building it? They're about to transform dramatically.

The New Team Composition

Within a year, I predict a part-time designer, 1 PM, and just 1-2 engineers will accomplish what today's two-pizza teams deliver. Why? AI is changing the productivity equation.

AI tools aren't just assisting with writing, designing, and coding - they're creating such a significant efficiency boost that our entire workflow paradigm must evolve to keep pace. The bottleneck is shifting from engineering capacity to something else entirely: attention and intent.

The Mathematics of Small Teams

Smaller teams have always been more efficient per person, largely because of communication overhead. Metcalfe's law helps explain this: the number of potential connections between team members grows exponentially with team size.

In a 10-person team, there are 45 possible communication channels. Cut that to 4 people? Just 6 channels - a dramatic reduction in coordination complexity.

But efficiency isn't the only benefit. Smaller teams typically experience:

Higher motivation and ownership - With fewer people, individual contributions have greater visibility and impact

Reduced free-riding - There's nowhere to hide in a small team

Faster decision-making - Fewer stakeholders means quicker alignment

Remember Instagram? Three founders outpaced Facebook's entire photo-sharing teams because they combined these small-team advantages with a clean slate.

The Small Team Challenges (And Solutions)

Of course, smaller teams face significant challenges too. Two key problems:

1. Blind spots: falling prey to tunnel vision and the belief that “if you build it they will come.
   Solution: Get out of the building - regularly engage with users, stakeholders, and other teams to maintain perspective

2. The build/maintain trap: small teams that move fast can produce a lot in a small period of time, only some of which is actually valuable.
   Solution: Don't get precious about code you've written. Be willing to restart when you hit local maxima. As your product grows quickly, resist the urge to maintain everything you've built.

Scaling Beyond One Team

Here's where things get interesting. Individual teams will be smaller and more productive, but how do multiple teams coordinate to deliver something greater than what any single team could accomplish?

Success requires mastering two critical skills:

Decomposition

Breaking big problems into truly independent smaller ones allows teams to maintain their small-team advantages. Done poorly, multiple teams become one big, slow team with exponential communication channels.

Synthesis

This is the make-or-break skill. Teams must combine their separate products into coherent offerings with shared distribution channels. Without synthesis, you end up with disconnected products - essentially a venture capital portfolio rather than a unified business.

The most successful tech companies - Amazon, Apple, and IBM (in its prime) - mastered this synthesis. They created coherent ecosystems where products enhance each other through shared distribution, user bases, and data.

The Bottom Line

The AI revolution isn't just changing what we build but how we organize to build it. The one-pizza team is coming - smaller, more focused, and empowered by AI assistants to deliver what once required twice the headcount.

Companies that learn to orchestrate these hyper-efficient teams through skilled decomposition and synthesis won't just survive - they'll define the next era of product development.

What do you think? Have you seen evidence of this shift in your organization? I'd love to hear your thoughts.

One question we ask ourselves is what are we building that’s defensible? What’s actually worth building. Especially given that in many cases, software that used to take weeks or months to code and ship can now be built in days or hours. Along these lines, Lenny shared a video from Alex Komoroske where he argues that in the age of AI, taste is the most important thing.

I’d like to take a slightly different angle on this because taste is subjective, taste is inactionable, taste is whimsical, and taste is something you have or you don’t.

Something more concrete than taste, and something that we can all practice, is caring. Caring deeply about who we’re building for, what they’re trying to accomplish, the pains, challenges, and triumphs they face, and the small interactions that make all of these things better.

Taste

• Comes from within.

• If you don’t like it, tough.

• Can change as the wind blows.

• Form > Function

Caring

• Focuses on others.

• If you don’t like it, tell me.

• Can be steadfast as everything else changes.

• Function > Form

PostHog, which we use for free today, proactively sent me this email which anticipates my concerns and addresses them directly and helpfully.

Caring is a way to generate long term value. One of the best examples of this is Amazon, a company obsessed with caring (about customers). In most cases you’d be hard pressed to argue that Amazon has great taste— their UI designs have been utilitarian since day 1, AWS services all emphasize function over form, and their brand identity is practically nonexistent. Yet, despite this lack of aesthetic refinement, Amazon’s relentless obsession with customers has made it one of the most successful companies in history.

Now I’m presenting these at odds with each other and making the case for caring. But we can find examples of companies that have won on taste alone— every successful luxury brand. And we can find examples of companies that have a blend of both. Apple is known for its taste (along with its “you’re holding it wrong” attitude), but they clearly care about all the details that make their products usable and useful for their customers.

But here’s the rub— you can’t care about everything. When I talk about Amazon as a caring company, I mean that strictly with respect to their customers. They are notoriously uncaring about their warehouse workers and their employees. Or said another way, for better or worse they put their customers’ needs far ahead of their employees’.

For SpecStory, caring is our approach. Specifically, we care deeply about the people who are breaking new ground today using AI code generation to build software. And this means sweating over issues they encounter when using our extension in the wild (even if that means that they’re saving multi-directory Workspaces as files while running Cursor on Windows with WSL). In fact we think of fixing real world issues as one way of creating value in SpecStory above and beyond what anyone could do if they just prompted an AI coding agent to “make a Cursor extension to save and share chat histories.”

But things move fast, and the world evolves quickly, so we need to get even clearer about what we care about. What happens when software is built in new ways, beyond the current AI codegen tools? What happens if we’re wrong about the timeframe for the widespread adoption of coding agents? What happens when different groups of AI-powered software builders have diverging needs?

We all need to figure out our path to creating long term value, and there are examples to draw on where tastemaking or caring, obsessively, have lead to that value. But I’d argue that “be tasteful” is less actionable than “be caring”.

But as Andy Grove warns, only the paranoid survive. I’m paranoid about whether we’re climbing the right hill.

Are we doing this?

Only to find out we’re really here?

We talk about it as a team frequently.

We know there’s much more to solve beyond helping individuals save and share their Cursor composer histories. That’s not the question.

The critical questions surround whether our Cursor extension will lead us to the tallest peak or not. Will we fall victim to the inertia of initial success? Will we be able to achieve our vision?

Our vision stated simply: SpecStory helps entrepreneurial teams use all their tools and talents to build valuable software faster, together.

The team knows hill climbing1 only to reach a local maxima is a death knell for any VC backed startup.

If you’ve ever hiked, you know this approach will leave you higher than you started, but it runs the risk of stranding you on a false peak. This matters for SpecStory and other startups like us because we have limited runway to find product-market fit for a high value customer pain point.

Unlike the casual hiker who can backtrack to find their way to the summit, we’re on a much higher stakes climb with limited oxygen and provisions— getting as high as we can with our scant resources will determine our ultimate success.

Now back to our vision: SpecStory helps entrepreneurial teams use all their tools and talents to build valuable software faster, together.

That last word says it all.

In our case, the deadly local maxima would be to become the best toolkit in the world for individual software composers.

And so we remind ourselves that helping them is just one step along the way toward helping teams. Those emerging teams — like us — that use AI code generation tools (Cursor, Windsurf, Copilot, etc), together, every day across a mix of newly forming roles.

To that end, we’re working to build more and more great features into SpecStory that teams can use together to accelerate the benefits of AI coding when used in more complex real-world projects and workflows.

Keep an eye out for the first of these: a /cursor/rules generator that will both individuals and teams keep their AI assistants aligned with their intentions and decisions.

Newsletter subscribers will get a unique code to gain early access to the beta version of this feature. Happy climbing!

Really small.

I was lucky enough to chat with Olav recently and their journey is proof that anyone can build a passionate following by starting small, focusing on the right platforms, and doubling down on real relationships.

Here’s how they did it.

1. Start Small—and Keep It Personal

Tana’s story began with Olav personally sending 400 DMs on Reddit. Only four people responded, but that didn’t matter. Those four became Tana’s first “true fans.” Early on, Olav and his team did things that weren’t scalable—like intense one-on-one support. By investing heavily in just a handful of users, they built an authentic foundation for the wider community.

Treat your early members like diamonds—nurture them and they’ll help shape your product in ways you never imagined.

2. Choose Your Platforms Strategically

Not every platform will fit your audience or brand. Tana passed on Discord to reach beyond developers and gamers, opting for Slack instead—even though Slack’s free version limits messages to 90 days. Sometimes you just need to embrace platform imperfections and pick one place to go all in, rather than trying to be everywhere at once.

3. Create Scarcity

There’s nothing quite like the allure of “you can’t have it yet.”

Tana grew a massive waitlist of 160,000 people and let individuals skip the line by joining the community and introducing themselves. Scarcity not only builds hype but raises perceived value—so consider whether charging for your product or access might actually boost interest over a free giveaway.

4. Build Community Structure and Roles

Not everyone in your community engages the same way. Tana created different tiers:

• Navigators: Power users who help run the community.

• Ambassadors: Content creators who develop courses, templates, and resources.

• Core Members: The bulk of the community, who participate at varying levels.

Reward top contributors with exclusive features, behind-the-scenes info, or direct meetings with the team. Monetary or swag incentives?

Not mandatory if you’re providing genuine value and recognition.

5. Let Your Community Evolve

A community that starts as product-focused can grow into something bigger—a place where people come to improve themselves and connect with others. Tana added channels around personal growth, as well as identity-specific groups (ADHD, regional channels) so people could find peers with shared interests. Feature requests and feedback got their own space to keep conversations organized.

6. Manage External Presence With Care

You can’t control every external platform, but you can engage thoughtfully. Tana targeted X (formerly Twitter) and LinkedIn for their tech-savvy manager audience. On Reddit, they collaborated with moderators instead of trying to take over. And because Slack doesn’t store older messages, they made it a habit to export and archive everything to BigQuery every 30 days to preserve valuable insights.

7. Keep Leaders Involved

Community thrives when leadership is front and center. Olav—co-founder himself—is active and visible. A simple greeting to every new member goes a long way toward showing people you value them. When you do roll out major changes, expect an outcry. Negative feedback isn’t necessarily bad—silence is worse. Encourage your team not to take criticism personally; it means people care.

8. Choose Tools That Serve You

While there are countless community tools out there, find the ones that align with your goals. Tana uses CommonRoom for its robust notification and engagement features. Don’t jump on every shiny new platform—pick what keeps you responsive and informed.

9. Foster Member-Led Content

One of the biggest wins for Tana was letting community members take the lead on courses, templates, and tutorials. Support your creators with early features and insider knowledge, rather than just handing out money. People love to tell the story of “being early” and growing alongside a brand or product.

10. Embrace Growth Systems

Scaling means organizing your community. Tana rolled out their “Navigator” program to manage the load as membership soared, recognizing that high engagement also means more vocal feedback. Remember that most uproar around changes is temporary—once users adapt to a new flow, things settle.

The biggest takeaway? Deep, authentic connections beat shallow numbers every time.

Your Turn: Build a Community That Lasts

Ready to cultivate a connected, enthusiastic community of your own?

Don’t wait until everything is perfect.

Start with a few true fans, treat them like diamonds, and be present as a leader.

Master a single platform, encourage user-driven content, and harness the power of scarcity when it makes sense.

Call to Action

1. Pick a single platform to focus on this month—commit to daily interactions and personalized engagement.

2. Identify your “true fans” and give them exclusive value or responsibilities, like moderating discussions or testing new features.

3. Embrace feedback—positive or negative—because it means people care enough to speak up.

Implement these steps, and watch your community transform from a handful of fans into a thriving, engaged network of advocates. Now is the time to act—go build your own Tana-style community success story!

Chances are if you’re reading this, you already know something about Software Composition.

Maybe you’ve even blasted ideas into Claude Artifacts, ChatGPT Canvas, V0.dev, Lovable.dev, Bolt.new or if you’re off the waitlist, GitHub Spark. If you’ve only tapped into these chat-oriented programming tools to churn out quick React apps, you’re missing the bigger picture.

You’ve heard about Co-Pilot, Cursor, and Codieum.

Your mettle grows as you graduate from locked-down PaaS environments to your go-to AI IDE.

So what’s next?

How do you start, how do you progress, and in what modes does Software Composition truly excel?

The Six Modes of Software Composition

At SpecStory, , myself and the team software compose daily — and not just for raw implementation.

Below is our opinionated breakdown of six distinct modes, how they connect, and how you should think while operating in each.

Mode 1 — Idea Refinement

Core Challenge: Picture yourself as an Enterprise PM hearing, “We need AI!” Your real job is to ask, “What problem are we solving?” Idea Refinement in the context of software composing means turning lofty, easy-to-dismiss dreams into practical, buildable proposals.

The Mission: Turn “we need AI” into “we need to classify support tickets into three priority levels with 90% accuracy”. For those classified at low levels, route them to an AI support agent that is able to assist the customer or user.

Software Composing Refinement

• Use Claude/GPT or even Cursor (with access to the underlying models) to expand vague requirements into detailed user stories

• Generate edge cases and potential failure modes for each part of the feature

• Take that technical objective and use AI to generate scenario analyses that tie back into your high level business objectives

Action (Today): Pick your most ambiguous requirement and use an AI editor to spin out five different interpretations. Narrow it down to three testable outcomes.

Mode 2 — Prototyping

Core Challenge: Building to learn isn’t the same as building to last. Most get stuck perfecting their prototypes. Don’t. Your job is to prove or disprove your riskiest assumptions as quickly as possible—like, within hours.

The Mission: Hack together a working prototype in a single day that nails the core value proposition. Use synthetic data for realism (even if everything’s duct-taped behind the scenes).

Software Composing Refinement

• Let AI generate realistic synthetic data with a compelling narrative.

• Build quick UIs that zero in on the critical path; ignore edge cases.

• Create fake APIs returning pristine data for your happy path.

• Have AI produce diverse test scenarios to stress your assumptions.

Action (Today): Take your riskiest feature. Build a throwaway prototype with AI-generated test data. Show it to a stakeholder tomorrow.

Mode 3 — Disposable apps

Core Challenge: When Greg talks about "disposable apps," he’s highlighting that sometimes code serves best by dying young. These apps go further than prototypes—they’re actually deployed and used but skip all the usual production guardrails. They prove paths to production while staying intentionally short-lived.

The Mission: Ship usable software without production overhead. Forget lint rules, build optimizations, or CI/CD pipelines. Deploy fast to test environments. Learn from real usage, then toss it when you’re done.

Software Composing Refinement

• Break normal rules on purpose—document what standards you’re ignoring and why.

• Deploy manually—no CI/CD pipeline required.

• Replace code review with pair programming.

• Embrace messiness; chase learning instead of cleanliness.

• Have AI generate multiple architectural variants at speed.

• Document insights about the problem domain, not just the code.

Action (Today): Pick a feature bogged down in analysis paralysis. Build and deploy a throwaway version that ignores your usual best practices. Get it in front of users in under a week. Use AI to move fast and note everything you learn.

Mode 4 - Production Code

Core Challenge: Production code meets real users, real scale, and real consequences. You can (and should) use AI here—just don’t be naïve. “Trust but verify” is the name of the game.

The Mission: Survive contact with reality while staying maintainable.

Software Composing Refinement

• Have AI scan your code for potential scaling issues.

• Generate comprehensive test scenarios based on actual production patterns.

• Ask AI to review error handling and propose more robust edge cases.

• Build monitoring and observability from the jump.

Action (Today): Take your most successful prototype and list all the ways it’d break in production. Use AI to uncover additional failure points. Then do the real work:

1. Read every block of AI-generated code. If you don’t understand it, ask. AI often improves when challenged.

2. Write comments. If you can’t explain it, you don’t truly get it.

3. Think through security, performance, and maintainability.

4. Validate package versions. AI can get them wrong due to cutoff dates—Google is your friend.

Mode 5 - Operations & Deployment

Core Challenge: Understanding how to get from local dev to cloud config is crucial. The challenge isn’t just shipping code to production but fully grasping the operational tapestry. Your advantage? AI can funnel the collective knowledge of ops teams worldwide right into your workflow.

The Mission: Bridge development and operations. Make deployment and maintenance as core to your project as the code itself. And remember, coding-focused AI might not always have the best or newest answers for operational questions—sometimes ChatGPT in browsing mode is more relevant.

Software Composing Refinement

• Let AI interpret complicated cloud documentation into plain-English steps.

• Generate Infrastructure-as-Code templates that align with your real needs.

• Build dashboards with actual system health metrics, not just uptime checks.

• Explain not just what you did, but why you did it this way.

Action (Today): Identify one manual step in your deployment process. Use AI in web-browsing mode to find a modern way to automate it. Whip up a proof of concept. Document the how and why.

Mode 6 - Troubleshoot and Debug

Core Challenge: Debugging in software composition demands a partnership between human insight and AI guidance. Plain error messages aren’t enough. Your mission is to build systems that leave behind helpful breadcrumbs—logs, metrics, and context—so debugging becomes a guided investigation, not a blindfolded search.

The Mission: Transform debugging from reactive firefighting into proactive system understanding. Leave a clear trail for anyone—human or AI—who might need to explore the system’s past behavior. Make logs that tell stories, not just record problems.

Software Composing Refinement

• Build Rich Context:

  • Capture screenshots, environment details, and recent changes

  • Track system changes over time with semantic versioning

  • Document environment differences early.

• Strategic Logging:

  • Log with breadcrumbs that AI (and humans) can follow.

  • Show state transitions with before/after context.

  • Capture relevant business context in technical logs

• Semantic Logging Patterns:

  • Replace "Error in user authentication" with "Failed to verify JWT token for user {id} with error {specific_error}"

  • Add business context: "Premium feature {feature} access denied for free tier user {id}"

  • Include actionable data: "Rate limit exceeded: current rate {current} exceeds limit {limit} for API key {key}"

  • Log successful operations too: "Successfully processed {count} records in batch {id} taking {duration} ms"

Action (Today): Take your most frequent error and rewrite its logging to deliver a complete narrative:

1. Add rich context about when and where it occurs

2. Include relevant business and technical details

3. Create clear correlation between related events

4. Use AI to generate comprehensive test cases that would trigger this error

5. Document the pattern in your team's debugging playbook

Making the Modes Work

If you’re still treating AI like a code vending machine, you’re missing the point. Every mode in software composition calls for a different relationship with your AI tools. Sometimes it’s about speedy exploration; other times, it’s methodical verification and deep understanding.

The magic isn’t in the prompt alone—it’s knowing which mode you’re in and adjusting your approach accordingly. AI IDEs and LLMs aren’t a single hammer. They’re a versatile toolkit you adapt to the job:

• In Idea Refinement: AI is your sparring partner, challenging assumptions and generating fresh angles.

• In Prototyping: AI gives you rapid generation and synthetic data on demand.

• In Disposable Apps: Let AI churn out multiple approaches fast—no polishing needed.

• In Production: Collaborate with AI for thorough analysis and to spot tricky edge cases.

• In Operations: Lean on AI (especially with web-browsing) for up-to-date operational wisdom.

• In Debugging: Work alongside AI to craft and interpret rich, semantic debugging logs.

Next time you open your IDE, ask yourself: Which mode am I in?

And how should that change the way I work with AI?

Your future self will thank you for the clarity.

Why would you want to do this? Because sometimes you just want to communicate an idea quickly without having to deal with the headache of a database. Colin Matthews says it well in a recent post about Cursor and other tools:

But what’s cooler is that you can use these tools to build functional prototypes from a Figma design, convert a rough hand-drawn sketch to a working app, translate a PRD document into an interactive prototype, or even build a usable internal tool for your team, with no coding ability

Getting Started

Install Cursor and get your laptop setup for composing a Node app.

Follow the instructions for creating a new NextJS app with ShadCN. Specifically:

npx shadcn@latest init -d

And then when prompted, create a new project, sample-cars:

✔ The path /Users/name/dev/specstoryai does not contain a package.json file. Would you like to start a new Next.js project? … yes
✔ What is your project named? … sample-cars

Add two simple components, button and card:

cd sample-cars
npx shadcn@latest add button card

And open your new project in Cursor:

cursor .

(If you haven’t already setup the cursor command on your machine, you can do so now inside Cursor by typing Ctrl/CMD-Shift-P to bring up the Palette and then running Shell Command: Install ‘cursor’ command).

Start the development server:

npm run dev 

You should see the Next.js sample app if you visit http://localhost:3000.

Composing your prototype

Now, you can prompt your way to a placeholder prototype, probably in one shot. Here’s what I did with Cursor composer in agent mode:

Change this application, replacing @page.tsx with a UI that displays the heading "Collectible Cars" and then a list of 10 ShadCN cards that say "Car 1", "Car 2", etc.

I made a specific mention of @page.tsx to get Cursor focused on the one file I wanted it to change. For the NextJS sample app, page.tsx contains almost everything that gets displayed, and by focusing Cursor on it we can avoid the creation of extra files, keeping the prototype simple and clean (from a project directory and file organization perspective).

I also explicitly referenced “ShadCN cards” because I like the styling of the UI components in that library. To keep Cursor focused, it helps to tell it which components you’d like on your page. Knowing ahead of time that I’d be using the card, I already installed it (above). If you ask Cursor to use a ShadCN component that’s not installed yet, it should walk you through installing it. Though in my experience, Cursor (with Claude 3.5 Sonnet) often suggests the wrong install command. If you get stuck on this, correct the AI by letting it know that the current ShadCN CLI component install command is npx shadcn@latest add. It’s even a good idea to add this to your .cursorrules file.

After letting the composer agent run and accepting the edits, my application looks like this (yours may differ):

Creating sample data

This is a great start, but as you can see the placeholder cards are all identical. This doesn’t really get the concept across. Let’s prompt for some sample data:

Add a new file that will hold JSON sample data for our application. Create an array of 10 cars using examples of classic cars from the 1950s and 1960s. For each car, store the make, model, engine type, years of manufacture, and a one sentence description.

I’m pretty intentional here about asking for a new file, mainly to keep my project and directories clean, and about asking for JSON data which is a widely used standard format for saving data. I gave Cursor some specifics to guide the creation of sample data, including the properties I wanted (make, model, etc). But you can also often get good, if sometimes surprising, results with open-ended requests, like Create an array of data for 10 classic cars. Finally, asking for an array in this prompt was intentional. We likely would’ve gotten the same results asking for a list of cars or just sample data for 10 cars. But in this case I knew specifically what I wanted for this tutorial. In general, it’s worth experimenting with the level of specificity of your requests. Being overly specific, especially on a topic you don’t yet know well, can steer the AI in the wrong direction and prevent it from making better recommendations.

Displaying the sample data

In this case, Cursor did a great job of generating a sample data file for us, but it didn’t make the leap to placing this sample data onto the page for us (in /app/page.tsx), so when we view the page we won’t see any change.

Reading Cursor’s response carefully, we see that it did at least ask if we’d like it to make the update to the main page to use this data. If your Cursor session also deferred making use of the sample data, you can use a prompt similar to this one to get it to finish the task:

Using this data, update the cards on our main page.

You might inevitably hit some hallucinations like we did with the Cadillac Eldorado, which was actually manufactured from 1952-2002. Fact check and manually correct the data file Cursor produced, until you’re satisfied.

Images - the SVG placeholder trick

Now some images would be nice. The fastest approach is to have Cursor generate a placeholder SVG for you and then display that on all the cards.

Generate a new SVG file in /public that is a placeholder image we can display for all the car cards. Use it on all the cards on the page.

For our type of application, a NextJS web app, any files in the /public folder will be available through the web server. For example, if you place image.png into the /public folder you’ll be able to access it at a URL like http://localhost:3000/image.png.

Not very stylish, but at least it gets across some of the spacing and layout for our prototype. To take this to the next level, we can get images for each of these classic cars and copy them into the /public folder.

Real images - the naming convention trick

I attempted to use ChatGPT with “Search the Web” enabled to "find an image for each one of these 10 classic cars”. But the results were mixed, and more often than not it hallucinated dead links. A more accurate approach is to use the Creative Commons Search Portal and paste in the name of each car in your sample data set. Download each image, rename it to something like make-model.jpg or make-model.png (e.g. chevrolet-corvette-c1.jpg) and copy it into the /public directory in the top of your sample-cars project. This will let Cursor connect the JSON data with the right images.

If you’ve named the files to match the make and model in your JSON data, it’s now easy to prompt Cursor to reference them:

The @public directory now has real images for some of the cars. Update the sample JSON data file to include links to images if available or to the placeholder SVG if not. Make these new images render on the cards on the page.

Making sample data interactive

Now let’s add the ability for the user to pick their favorite cars.

We want to let the user select their favorite cars and bring them to the top of the page. Add a ShadCN button to each card with an icon for "favorite".

This might work for you, but I hit the following error when Cursor tried to import the icon for the button.

Though the Cursor composer agent can automatically handle linter (coding-time) errors, it can’t handle build-time errors like this one without your help. Copy and paste the entire error into your Cursor prompt and it should be able to resolve it for you.

Build Error
Failed to compile 
Next.js (14.2.16) is outdated (learn more) 
./app/page.tsx
Error:
    × You're importing a component ...

1

And now you can click a heart to mark one of the cars as your favorite and move it to the top of the page!

See the full Cursor history for this project and stay tuned for more data topics such as using HTML Web Storage (localStorage), and composing scripts to gather sample data.

600 users, no analytics.

Right before the holidays we launched the first product iteration of SpecStory — an extension for Cursor — and more than 600 people have installed it: great!

What we were missing, however; were usage analytics on the extension itself so we could know (anonymously) when people were activating it: not so great!

So picture this: a product leader, seasoned engineer and AI assistant enter a zoom room. All with the expectation of adding analytics via PostHog to the extension for the next release.

Like many modern software composers I first approached this task solo with Cursor’s Composer as my guide. The code flowed effortlessly, each prompt brought new functionality to life. Smoke tests worked, events flowed into PostHog, and everything seemed like smooth sailing.

Until the moment of truth: the pull request.

When Worlds Collide

Reality has a way of humbling our assumptions: my 60 minute composition session created a pull request that, as we started digging in, we realized would take more than 5x as long to review.

As Sean, our CTO and I sat in that Zoom room together, he began asking questions about specific lines of code.

And I found myself in an unusual position: unable to explain any of the details of what I had created.

This moment crystallized for us the new gap created via AI-assisted development: intent and implementation doesn't vanish with AI—it just shifts. While I could articulate what I wanted the software to do, I personally had lost the thread connecting each line of code to its original purpose.

Not wanting to let this pain point go to waste, Sean and I spent the next day experimenting with a decidedly different approach.

Trio Programming

Instead of going solo from the beginning, we decided to connect product intent with engineering wisdom while allowing Composer to act as our implementation partner.

As the quick video shows, we moved in small deliberate steps and caught potential regressions that had previously made the pull request opaque and could have turned into hard-to-rectify production issues.

The good news? We ultimately got the analytics shipped (check out version 0.2.4 here) and learned a few things that will probably resonate with you:

• For rapid prototypes and demonstrations, solo AI software composition shines

• For production features, our trio programming approach provides the right balance while still allowing us to “eat our own dogfood”

• For technical intents (like improved code quality linting or enhanced CI), traditional engineering often remains the most efficient path

Substitutes for the second human partner?

While the trio approach with myself, Sean and Cursor worked well, we can’t help but think about the future. The time we spent together given the tools currently at our disposal was clunky and doing trio programming likely won’t scale at the same rate that we intend to grow.

In parallel, we’ve been debating if another AI could serve as a stand-in. While it is still early days, , began pulling on that thread before the holidays. The experiment wasn’t for a SpecStory production feature but it is a fascinating glimpse into a to-be-further-verified promise.

To help our distribution efforts, Greg is building an AI Code Editor ranking app. It sources data from Reddit and uses ChatGPT to analyze the sentiment. He had the idea to use Google’s new realtime streaming functionality to “watch his screen” as he composed and offer suggestions on the code — as it was being generated — using Cursor and Claude.

While the demo above was mostly happy path it points to the exciting possibility of AI not only being a code generator but an active review partner. While currently also clunky to manage, it appears to be the best “test” option sans connecting ChatGPT directly to Cursor through their “Work with Apps” beta feature.

In his words:

It was great to be able to work in familiar modalities and have the second AI keep up. I was impressed with how easily it was to be able to direct Gemini at parts of the screen and get very specific feedback on Cursor’s implementation of my intent. The jury is still out on whether it will be able to aid my efforts on more complicated software composing.

So there you have it: as we continue to build SpecStory, we’re committed to consistently sharing these type of learnings.

We believe that no matter if you’re a solo composer, part of a larger team, or somewhere in between, finding the right balance between AI assistance and human judgement will be continue to be crucial in the months and years ahead.

For the rest of us, this video is a start from zero, what’s the Terminal, how do I build and launch a simple website in under an hour kind of tutorial.

We’ll walk you through setting up a clean Mac or Windows environment and installing essential tools like Cursor, Node.js, npm, and Homebrew needed for software composition.

You’ll learn:

• How to configure your development environment from scratch.

• Setting up a Next.js project with ShadCN component library.

• Using Cursor’s AI capabilities to write and debug code effortlessly.

• Debugging common issues and leveraging documentation.

• Sharing your project using GitHub.

By the end of this video, you’ll have a fully functional project and a foundational understanding of using AI tools for software development—even if you’re not a coder. Perfect for anyone ready to explore the world of AI-powered app creation.

Also, shameless plug, the last few minutes are a demo of the SpecStory Extension for Cursor that we recently launched to help you save and share your AI composer and chat history.

For Mac Users

For Windows Users

Additional Notes

Full Cursor Chat History

• https://share.specstory.com/stories/20072845-d03c-4961-b276-167fe6eeb2ad

🔗 Links

• https://www.cursor.com/

• https://brew.sh/

• https://formulae.brew.sh/formula/node

• https://ui.shadcn.com/docs/installation/next

• https://github.com/

• https://vercel.com/

• https://specstory.com

Transcript

This is a video about SpecStory which helps you when you're doing AI-driven development using a tool called Cursor. If you haven't been doing AI-driven development and you're just getting started, this video is for you. It will help you get set up with Cursor that'll let you do software development even if you're not a software engineer or coder.

This will be a RAW video - we're not going to fast forward past the bumpy parts. We've got a clean Mac install with just a few pieces of software already installed. This should give you a sense of what it'll take to get started from scratch building software with Cursor and Spec Story.

The first step is getting Cursor installed and set up. You can go to cursor.com and download for your operating system, in this case Mac. We'll have another video for Windows in the future. Once you've got Cursor installed you can just run it like any other tool. On Mac I use command space to start applications but you can go to your Applications folder.

On first run you'll see nothing set up and it's asking for you to configure some settings. All these defaults are perfectly fine. I like to say yes and continue if you don't mind sending data back to Cursor to help improve. You can choose privacy mode if you prefer. Cursor is a paid tool, $20 a month and it's well worth it and it's really the only tool that we absolutely need to pay for. All the rest will be able to set up free alternatives.

This is what it looks like when you first get Cursor installed and authenticated before you do anything. Our first step is opening a folder - that's the way that most integrated development environments (which Cursor is) use a folder-based approach for managing projects.

Let's first create a folder. We could open an empty folder, but usually we start from a starting point. The starting point we'll choose is an application framework called Next.js. We're going to make use of what's known as a user interface component library called shadcn. The easiest starting point is to just go straight to the shadcn docs and the installation steps for Next.js.

You could prompt your way through the setup by asking ChatGPT or Claude to help you get a new project set up. But I've found that sometimes these steps can be out of date. In this particular case, I prefer to use the raw documentation at ui.shadcn.com/docs for the Next.js installation.

For running the Next.js installation, I've chosen the NPM version. You can choose any of these, but most of the output of Cursor and Claude favors the most used tools. NPM is one of, if not the most used tool for these particular things. NPM is one of a pair of tools we're going to need.

When we're building UI applications we have lots of choices, but a really good set of standard choices is to use Node. Node is a framework for building websites or interactive web applications. That's what we're going to do here.

Let's try to run the installation command. But the first thing you'll notice is that NPX is not found. So we need to get some tools set up first - at least a minimal set of tools for software development. Two of those are Node and npm. NPX is just one of the commands that's available as part of NPM.

Let's get some tools installed on our Mac. The most widely used tool for installing other development tools on a Mac is called Homebrew. Homebrew tries to make it dead simple to get started - there's just a single command line that you run to install Homebrew itself, which then opens the door to install lots of other applications.

This whole process will only work if you're set up as a Mac administrator on your laptop or desktop. If you don't know what that means, you need to Google "Mac administrator" and make sure you get your account set up properly for that.

After installing Homebrew, don't skip the next steps - we need to run each of these follow-up commands in succession. Now we should be set up so that whenever we want to, we can run the Brew command. The two things we need Brew to install for us are Node and npm - it's just one command.

If you ever get lost, you can ask ChatGPT "how do I install Node using Homebrew?" Either method they suggest is fine. They recommend first running "brew update" (though we just installed it so it should be up to date), then "brew install node". We can then verify our installation by checking the version of Node and npm.

Now that we've got these installed, let's go back to where we started - creating a new application using shadcn. Now that we've got Node and NPM installed, we should be able to run the installation command. When it asks for configuration options, all the defaults make sense, and you can just hit Enter to accept them.

When the first part completes, you can select all the defaults for shadcn. You can read about shadcn and all the options available, but we'll just accept as is. The installation creates a new directory called "hello" in your current location.

Now in Cursor, if you see the option asking if you want to install a command to run Cursor, I would recommend it. Choose to install the command named "cursor". This means you can come to your terminal and run "cursor" on any directory like the hello directory, and it'll just open Cursor straight to that directory for you.

There are two really important things we want to enable when we come into Cursor. One is the terminal - this is the same terminal we were just in, but now it's integrated into Cursor. The other thing is the AI pane over on the right-hand side, which lets us do the magic and use AI to help us write code.

At this point, you can use Cursor and ask it questions like "what command can I run to start this application?" When you use Cursor, you can add context, which means pointing to any of the files in your current project directory or other outside content. One of the simplest ways, especially when you're starting and have a tiny project, is to tell Cursor to include the entire codebase.

You can say "include codebase" to tell Cursor to look at everything here, all the files and folders, when it's trying to answer questions. When we ask about starting the application, it shows multiple commands you can use. The software development community has created four different package managers that do roughly the same thing. We'll just stick to npm for everything.

When it suggests commands, it means to run these commands inside the terminal. You can copy one of them and paste it into the terminal. The command "npm run dev" is one you'll probably end up memorizing because you run it so often.

What this does is run a web server that allows you to interact with the code of this website to see it in your browser. This server will package up all this code and turn it into a website. We can visit the URL it provides in our browser. If you want, you can hold down the command key and click the link to open your browser right there.

The whole site is exactly what the code says should be rendered. Now we can move on and create a site that we actually want, because we wanted a hello site, not one that said Next.js on it.

Now we can use Cursor to do all of the heavy lifting for us. Once we get things to this point and set up, the world is our oyster. I often like to create new composers when I'm onto a new task. You can always get back to your old composers whenever you want. A composer is just like a conversation between you and the AI acting as your engineer.

Let's make the most fun hello world page we can. It's wintertime and I like the holiday season. Let's create a page for the holidays and winter. You can get creative and make some SVGs so the page looks pretty. Don't worry if you don't know what an SVG is - it's just a type of image format that Cursor and Claude are particularly good at rendering.

We'll submit that request and let Cursor Composer do its work by suggesting changes and edits to all of our files. Sure, we could dig in and try to follow along, and there's a lot of learning to be done with that. But sometimes we just want to hit "Accept all" and see what we've got.

One of the nice things is as you make and save changes in the code - or more specifically as Cursor makes changes in the code and you hit Apply all to save them - this server that we're running (remember we started npm run dev) is still running in the background and looking for any changes to our application files. It's immediately incorporating them so that when we come back to the browser and reload, we can see those changes.

Look how fun it is! I couldn't have even imagined this a year ago but Cursor and Claude are able to write the code for a holiday site just like this. Now let's take a minute to add in some more traditional elements of web applications. This will start to get at the reason why we installed shadcn.

If we look at shadcn, it's pretty interesting because what it is is a component library. If you've been to any website or web application, you've probably seen some combination of these already on the page - everything from a simple button that looks nice and styled and works well, to a calendar control or a card where a card is just this sort of rounded rectangle layout that gets used often in modern websites and web apps.

We're going to use cards and buttons in our hello site. The easiest way to do this is to just ask Cursor to help us do that. Let's add two cards to the site that present some holiday greetings.

I'm hoping that Cursor will pick up this word "cards" and know that I mean shadcn cards. In this case it created cards using styling rather than the shadcn components. We can ask it "did you use shadcn for those cards?"

When we try to install the shadcn components, we might run into some errors. That's okay - Cursor and Claude can help us with this. We just copy the error and context, and Cursor will help us resolve it. It realizes that the components aren't installed yet.

We'll need to run some installation commands in the terminal. You have a couple of choices - the easiest of which is to stop what's already running in this terminal. The way to do that is to hold down the control key (not the command key) and hit C. That stops the npm run dev server and then we can run our installation commands.

When we get everything installed and running, we might run into eslint errors when trying to deploy. ESLint is just a tool for trying to create clean code. By default, Next.js and Vercel are configured to really try and have clean code.

We can work through these errors step by step:

• Fix the ESLint configuration

• Install any needed dependencies

• Update configuration files

• Commit and push changes

• Try deploying again

At a certain point we could decide that we need to dig in, learn more about ESLint, learn more about Vercel, do some research of our own, build up our knowledge base. But for now, we can try to have Cursor and Claude help us get past these issues by installing the right dependencies and updating the configuration.

Once we get past our configuration issues, we can deploy our site using Vercel. Vercel works very nicely with the type of application we just built, which is known as a Next.js web application.

Let's get started with Vercel. We can sign up if we haven't already - "working on personal projects" is a good option to select. We can continue with GitHub, and it will go through and authorize Vercel. We need to make sure we install Vercel for our GitHub account and give it access to our repositories.

Our first Vercel GitHub integration was literally just to do the sign into Vercel. That second integration, the install, is what was needed for Vercel to connect to our repositories. We can see that hello repository that we just updated.

We can hit the import button here. Often defaults are your friend, especially when you're working with a Next.js application and Vercel. Those work very well together. Hit the deploy button and Vercel will take everything that we've done, all that code and package it up.

After deployment completes, there are a couple of different URLs. One that we can use for working and commenting on this particular deployment, and one that we can share with the world. The one we can share with the world is what we care about most - that's what the little global icon indicates.

When we click on it, we can see our application up and running. We get a Vercel toolbar and some extra accompaniments because we're logged into Vercel. But if we share this with somebody else, which we can simulate by opening an incognito window, they're just going to see our application, our page - it's going to work, and they're going to have a happy holiday.

Now that we've got our happy holiday site all built, let's learn about what Spec Story can do to help with this flow. We can go to specstory.com - we can see this Cursor extension is exactly what we need.

To install Spec Story directly into Cursor instead of VS Code, you actually have to go through Cursor. Go to the extension marketplace icon up in the top left. Then we can search for Spec Story and install it.

Once we've got Spec Story installed, there are two big things we can do with it: save the entire chat history (not just one conversation, but all composer sessions and chats we've had) or share these out. Spec Story makes it really easy to share these with others.

Let's start with saving. Both commands are run from the command palette inside Cursor. You can get to the command palette a couple of different ways - you can search help for it and see View command palette, or use Shift command P as the keystroke.

If we just type Spec Story in the command palette, we can see our two commands. The first one is to save the composer history. Saving the composer history creates a new markdown file which is then opened for preview. You can close that preview if you don't like it and just want to look through the markdown file.

The file shows all of the history I've had for building out this entire application. All the chats and composer sessions are saved in this file. If we want to really save this, we can hit command S and save it as "Spec Story History.md".

We can even reference this file and ask questions about it, like "Give me a brief summary of everything I did in this project." It helps us remember everything we had to do to get through this development.

If we want to completely unlock this history for others, we can go back to the command palette and use "spec story share composer and chat history." We see down on the left that it's published out this history for me to share with others. When we open it, we get a nice clean view of everything that happened from start to finish in the AI chat history.

It's a great way to share the story of how you created your application.

Picture this: you’re in another weekly Zoom call, your remote team scattered across time zones.

The agenda is ambitious: brainstorm a new product feature, review last week’s customer interviews, and clarify a few sticky points that keep resurfacing.

You’re nodding along, taking mental notes, but halfway through, your mind drifts. Did we just agree on something critical that we might forget tomorrow?

We all know this feeling intimately.

Meetings are like quicksand—constantly pulling you in, yet once you step out, the details slip away.

• What if you could reduce the worry about losing track of those insights?

• What if every conversation could become an asset—easily shared, neatly organized, and available to yield takeaways at a glance?

Working Transparently

My cofounder, Sean, previously created an entire company around the idea of startup transparency. And GitLab’s work in the open has helped me many times throughout my career. Everything from product management job descriptions to product operations best practices are well captured in their living handbook.

At SpecStory we value transparency and working openly with each other.

It’s why we hit “record” on nearly every Zoom call. Real product decisions, customer feedback, internal debates, and co-creation sessions—these moments are valuable and we want to prevent them from slipping into the ether.

Example: below is a three minute highlight reel (edited with descript) of us co-composing our home page last week.

We went from blank slate to it being working and deployed. The share of this experience allows other team members not there to understand “how we built it”.

Upgrading our Recording Stack

For us, Zoom’s built-in recording features were a good start: cloud recordings, transcripts, basic AI summarization. What we like the most is that it’s unobtrusive… it doesn’t invite a “recording bot” into the meeting.

We quickly encountered friction.

Storage gets pricey, organization is bare-bones, and shared links become difficult to manage. We needed a better system and stack—something that could preserve the ease of Zoom’s native recordings without forcing us to juggle storage upgrades or bot integrations.

We evaluated a handful of tools before landing on Grain.

This might sound like an ad for Grain. But I have no connection to Grain other than being a happy user.

There are a bunch of reasons Grain aligns well with our needs. For example, it lets us auto-import every Zoom recording with no special invites.

And once you’re past the basics of getting recording setup, you can use playlists and tags to organize all of your meetings.

It’s also helpful to turn on Grain Workspace access by default for all meetings so you don’t have to manually set it for each video:

You and your team can now grab the transcripts and use AI to extract useful nuggets.

Turn Raw Footage into Insight

Recording alone isn’t enough. You want meaning from all the dialogue.

Example: after our user research interviews, we run each transcript through Claude, with the following prompts (each issued separately). These prompts are a sieve for surfacing signal.

• Extract key takeaways from this research interview

• What was most important for them?

• What were they most excited about?

• For their most challenging story, summarize the following:

  • Problem or challenge

    • The pain points

  • Solutions tried

    • Tools or processes used

  • Outcome

    • Lessons learned or what he'd do differently next time.

• For their most positive story, summarize the following:

  • The problem or challenge

    • The pain points

  • Solutions tried

  • Tools or processes used

• Lessons learned. What would they do differently next time?

• Extract the 3 most salient quotes from the interview

• Make a simple list of every tool or service they mentioned

And this approach produces really interesting learnings. Below is a quote from a conversation I had recently with a software composer in Oslo:

On the empowerment of AI tools: "I felt very powerful because I've always been dabbling with code, but I've always had developers who actually built the stuff I wanted to build, but now it's more direct."

Within minutes, we have a distilled version of the conversation’s essence.

1. We find patterns in user pain points

2. Lock onto the most resonant quotes, and

3. Identify workflows we hadn’t considered.

We use this practice for more than user research.

Internal team meetings contain plenty of hidden gems, too. We might discover a recurring theme everyone keeps circling around, an idea backlog we didn’t realize we had, or a point of contention worth smoothing out before it snowballs.

Recording, organizing, and analyzing helps us turn the stream of chatter into a structured, living knowledge base.

Some may worry it could feel intrusive. But used thoughtfully and transparently, recording becomes as natural as taking notes.

Critical one-on-ones can stay private, but in general, default recording ensures nothing slips through the cracks.

It takes a few weeks to adapt, but soon it’s second nature—hit record, talk freely, trust that nothing valuable will be lost.

Start Now

Know a founder who’s drowning in meeting overload? Share our story and guide.

With the right tools (like Grain and Descript) and a handful of clever prompts, every conversation opportunistically becomes a future resource.

Meetings are now a wellspring of shared understanding, a repository of hard-won lessons, and a catalyst for action.

Stop letting insights slip away.

Start recording, start organizing, and start extracting meaning.

Turn your team’s conversations into living blueprints for the future.