The Code Is Ephemeral. The Workflow Is the Artifact.
A new mental model for AI-assisted development.
The 130MB Wake-Up Call
I was building a side project with Cursor and Claude. Twenty minutes of coding, back-and-forth with the AI, a working feature at the end. I wanted to share how I built it — not just the code, but the process.
So I built a tool to capture everything. Every file change. Every diff. Every keystroke.
The result: a 130MB file for a 20-minute session.
It captured changes to node_modules. Build artifacts. Lock files. Thousands of lines of diffs that meant nothing to anyone, including me.
I had built a flight recorder. What I needed was a recipe.
The Insight: Prompts Are the Artifact
Here's what I realized: when you code with AI, the generated code isn't the artifact. It's ephemeral. Non-deterministic. The same prompt produces different code every time — different variable names, different approaches, sometimes entirely different implementations.
And that's fine. That's the point.
The artifact is the workflow. The prompts you wrote. The approach you took. The decisions you made. The iteration that got you to something that works.
Git captures what changed. Chat logs capture the conversation. But neither captures the workflow — the transferable sequence of prompts and actions that someone else could follow to build the same thing.
That's what a buildlog captures.
What Goes Into a Buildlog
A .buildlog file is lightweight by design. It captures:
Prompts (in full)
These are the real artifact. Every prompt you send to the AI is recorded exactly as written. This is what someone else — or another AI — needs to replicate your workflow.
Action summaries
Instead of storing 10,000 lines of diff, a buildlog stores what happened: "Created REST API with four endpoints" or "Added Stripe webhook handler." Human-readable. Agent-parseable.
File operations
Which files were created, modified, or deleted. The names, not the contents. The structure, not the bytes.
Terminal commands
What you ran and whether it worked. npm install stripe → success. npm run build → failed, type error. The rhythm of the session.
Key decisions
Notes and checkpoints. "Used embedded checkout instead of redirect for better UX." The reasoning that doesn't show up in code.
What it doesn't capture: full file contents, line-by-line diffs, node_modules, build artifacts, or anything that inflates the file without adding meaning.
The result is a recipe file — typically a few kilobytes — that captures everything needed to understand and replicate a workflow.
Three Ways to Think About Buildlogs
1. Recipes, Not Recordings
A cooking video shows one person making one meal. A recipe lets anyone make their own version.
Buildlogs are recipes. They capture the workflow at a level of abstraction that's transferable. Follow the same prompts, make the same decisions, get a working result — even if the generated code is different.
2. Package.json for Process
package.json declares what your project needs. It doesn't contain the actual code of your dependencies — just pointers to them.
A buildlog declares how something was built. It doesn't contain the actual code — just the workflow that produces it.
3. Documentation That Executes
Traditional documentation describes what code does. A buildlog describes how it came to exist.
And because buildlogs are structured, they're not just documentation for humans. AI agents can read them too.
The Agent-to-Agent Future
This is where it gets interesting.
If a buildlog is a structured, portable workflow, then it's not just shareable between humans — it's shareable between agents.
Imagine: you publish a buildlog of how you added authentication to a Next.js app. Someone else tells their AI assistant: "Follow this buildlog." The agent reads your workflow, adapts it to their codebase, and executes the same sequence of prompts and actions.
Same recipe. Fresh output.
This isn't theoretical. AI agents can already read structured instructions and execute multi-step workflows. A buildlog is just a standard format for those instructions — one that captures real workflows from real coding sessions.
The future isn't AI replacing developers. It's developers sharing workflows that AI can replicate and adapt. Buildlogs are the transport layer.
When Buildlogs Make Sense
Tutorials and education
Instead of writing a tutorial that's outdated in six months, publish a buildlog. Readers can follow the same workflow and get current results from current models.
Team knowledge sharing
"How did you build that feature?" becomes "Here's the buildlog." New team members can see not just what was built, but how the AI was used to build it.
Portfolio and job hunting
Showing your code is fine. Showing how you work with AI is better. A buildlog demonstrates your prompting skills, your decision-making, your workflow.
Open source contributions
Document how a feature was implemented. Future contributors can follow similar patterns. The buildlog becomes part of the project's institutional knowledge.
Personal archive
Remember how you built that thing six months ago? Your prompts, your approach, the commands that worked? It's in the buildlog.
The Format
A .buildlog file is JSON. Here's what it looks like:
{
"version": "2.0.0",
"format": "slim",
"metadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Add Stripe Subscription Flow",
"description": "Implemented checkout with webhooks",
"createdAt": "2026-02-02T10:30:00Z",
"durationSeconds": 1200,
"editor": "cursor",
"aiProvider": "claude",
"model": "claude-sonnet-4",
"replicable": true
},
"steps": [
{
"id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"type": "prompt",
"timestamp": 0,
"sequence": 0,
"content": "Add Stripe subscription checkout to this Next.js app...",
"context": ["app/page.tsx", "package.json"]
},
{
"id": "b2c3d4e5-f6a7-4b5c-9d0e-1f2a3b4c5d6e",
"type": "action",
"timestamp": 45,
"sequence": 1,
"summary": "Created checkout API route and webhook handler",
"filesCreated": [
"app/api/checkout/route.ts",
"app/api/webhook/route.ts"
],
"packagesAdded": ["stripe"]
},
{
"id": "c3d4e5f6-a7b8-4c5d-0e1f-2a3b4c5d6e7f",
"type": "terminal",
"timestamp": 90,
"sequence": 2,
"command": "npm install stripe",
"outcome": "success"
}
],
"outcome": {
"status": "success",
"summary": "Working subscription flow with test mode",
"filesCreated": 2,
"filesModified": 1,
"canReplicate": true
}
}The format is open and MIT licensed. No vendor lock-in. Your workflows are portable forever.
Getting Started
Capture a workflow
VS Code extension: Install "BuildLog" from the marketplace. Press Ctrl+Shift+R (or Cmd+Shift+R on Mac) to start recording. Use "BuildLog: Add Prompt" to capture key prompts during your session.
With AI agents: Install the buildlog skill with npx skills add buildlogai/skill. Compatible agents (Aider, Cline, etc.) will automatically log their work to a feed file that your VS Code extension picks up.
Share it
Upload to buildlog.ai: Sign in and upload your .buildlog file for a shareable link and web player.
Or keep the file: It's just JSON. Commit it to your repo, email it, or store it anywhere.
Learn from others
Browse public buildlogs: Visit buildlog.ai to see how other developers approach problems.
Download and replay: Every buildlog on the site has a download button. Get the .buildlog file and replay it in your own environment.
The Shift
We're in a transition. The way we code is changing. AI assistants are becoming collaborators, not just autocomplete.
But our tools for sharing and learning haven't caught up. We share code, not process. We document outputs, not workflows.
Buildlog is an attempt to bridge that gap. To create a format for the thing that actually matters when you code with AI: the sequence of prompts and decisions that got you to a working result.
The code is ephemeral. The workflow is the artifact.
Buildlog is open source and free to use. Learn more at buildlog.ai