# User Profile spec
- Show user profile with name, email, join date
- Format join date as "Member since MMM YYYY"
- If no email, show "No email on file"Give this spec to an agent targeting React:
function UserProfile({ user }) {
const joinDate = new Date(user.joinedAt)
.toLocaleDateString('en-US', {
month: 'short', year: 'numeric'
});
return (
<div>
<h2>{user.name}</h2>
<p>{user.email || "No email on file"}</p>
<p>Member since {joinDate}</p>
</div>
);
}Same spec, Vue:
<template>
<div>
<h2>{{ user.name }}</h2>
<p>{{ user.email || "No email on file" }}</p>
<p>Member since {{ formattedJoinDate }}</p>
</div>
</template>
<script>
export default {
computed: {
formattedJoinDate() {
return new Date(this.user.joinedAt)
.toLocaleDateString('en-US', {
month: 'short', year: 'numeric'
});
}
}
}
</script>Same spec, different output. The spec defines what. Architecture determines how. The spec is portable across frameworks, languages, and teams.
With and Without a Spec
Without spec: "Build a user profile page" — Agent invents requirements + implements them. You debug both the requirements AND the code.
With spec: "Build this user profile page" + spec — Agent implements your requirements. You debug only the code.
Without a spec, the agent picks a date format, decides what to show when email is missing, chooses component structure. Every decision it makes is one you didn't review.
With a spec, the agent translates intent to implementation. It doesn't invent.
The Spec Is the Product
Code gets generated, tested, regenerated. Frameworks change. Languages change. The spec persists. It's the source of truth; code is compiled output.
Fred Brooks called this essential vs. accidental complexity. AI handles accidental complexity (boilerplate, syntax, framework wiring). Essential complexity (what the system actually does) stays with you. That's what specs capture.
Tradeoffs
Writing specs takes time upfront. For throwaway prototypes or one-off scripts, just prompting is faster. Specs pay off when code will be maintained, regenerated, or handed to different agents/frameworks over time.
Specs can also become stale if you edit generated code directly without updating the spec. Treat the spec as the thing you maintain, not the code.