Teams are using detailed HTML specs as the primary input for AI coding agents like Claude Code. The spec links to Linear tickets, includes architecture diagrams and UI mockups, and lets engineers audit changes and hand off work to the agent with clear expectations.
Spec-driven development. What is it? Spec-driven development is spending a ton of time, 80% of your brainpower, you know, with your cross-functional colleagues, with customers, to inform a highly considered input artifact to give to a coding agent for code generation. Spec-driven development has been a meta for a while now, and recently an Anthropic engineer went on a podcast, on Claire Voe's podcast, and demonstrated how they use HTML files to be in the loop as a human to really easily visualize specs and get aligned very quickly with what's gotta change. So I took this meta and for our recent product launch for a customer of ours, I went ahead and created a specification in HTML. You could see that here. What we normally do on the team for our workflows is we start with a ticket in Linear and every single PR follows a particular lifecycle. We have a feature branch cut off of staging for this particular client, and then we'll go and start a PR that is a Papertrail PR and we'll add commits to it. So we, we do that so that we're always inspecting the input artifacts then for code generation. So in this HTML spec file, it's really cool. So what I'm demonstrating here is as a builder, you might be reading a lot of markdown that might be getting tiring. I find it really nice to create an HTML spec file. That's the new meta. You can even have it create these nice architecture diagrams because you have the power of HTML now and some level of frontend to create very readable and highly understandable specs. So it's even showing me the backend data model, which referred to a different ticket. So I could then take this and I go to Linear. And if I want to get the context of that ticket, look at that. Uh, it showed a bunch of options for me to pick from the IDE. And I had chosen option C and it inculcated option C for the user journey. It showed me what's existing. If I go through this, it kind of shows the implementation plan, the exact code changes that are going to happen. So I could scan this as a staff engineer or architect and very quickly understand things. It also showed me the lifecycle of changes. For this, we really had to have a highly considered understanding across systems of state of a particular order to fulfill. This visualization was really nice. It helped me understand like, okay, what's going to get triggered by what, et cetera. What should the user actually see on the screen here and what UI component are they seeing? That way me as a human, I can go in, I can be like, oh wait, this is wrong, this is right, or whatever. And my meta is usually like I'm talking to Claude Code and I'll say, hey, this part of the spec, this part of the spec is wrong. I even had it create different drafts of the UI. These were examples of how users would reach this new screen and what it would look like. And what's really nice about this is because, in this HTML, it would be highly relevant for the next agent handoff to be like, okay, that is the frontend specification. It's got to look like that. Obviously that would be part of the exit criteria or test strategy. So you can go verify that with iOS Simulator, MCP, for example, for end-to-end testing. I've been finding it very, very useful as an AI builder for both PM work, engineering work to better get into the weeds of the nitty gritty on what is the exit criteria and what's the the problem we're solving, what are we actually doing here for this pull request? Jonathan, have you tried this spec-driven HTML meta and what do you think of it?
Yeah, I thought this was a really great example of a lot of moving pieces in the app that you were building. I've used it for backend architecture too. For me, it's a good abstraction layer to talk with the session, with the coding agent. I mean, a lot of times you can get, like, say in our linear backlog, you know, there might be a project and it's got like a lot of interrelated tickets. There's a lot of pieces going on that I don't want to pay a lot of cognition to. And there's other things that are like really important. And I think this kind of abstraction is a way of talking about like the output artifact as a system. You know, you can look at this, you can copy and paste the image back and say like, I don't understand this part or this part's wrong. Or, you know, this doesn't, you forgot to include this source document when you consider this part and you can shape this into an artifact that you understand and the agent understands. And then you're pretty safe to just let it build at that point. Um, and just make sure it does what the spec says. Right. So it's a really powerful abstraction language, in my opinion.
