Blacksmithing: A Development Methodology for AI-Assisted Engineering
One might also call this "document-driven development" or "specification-first AI engineering." I prefer Blacksmithing because it captures the philosophy better - a skilled craftsman shaping raw materials into something greater than their original form. Not someone pushing buttons.
So what is Blacksmithing?
It's a paradigm shift. In traditional software development, code is the product. You gather requirements, write code, review it, deploy it - the codebase is what matters. Blacksmithing inverts this. The design document is the product. Code is a compilation artifact - disposable, regenerable, worth no more than a .pyc file. What matters is the spec.
Here's the workflow.
You work with AI agents. They are not your tools - they are your assistants. This distinction matters.
Step 1: Write the design doc. This is your project's source of truth. It covers every technical detail you can think of - architecture, constraints, edge cases, decisions made, alternatives rejected. Building software? Writing music? A marketing plan? Design doc. You work with AI to fill in the unknowns, pressure-test the decisions, and get the spec tight. This document should be thorough. It will be lengthy. That's the point.
Step 2: Create a handoff. This is a living session document - what you accomplished today, what needs to happen next, known issues, test counts, open questions. It carries context across sessions so neither you nor the AI have to remember anything. Memory is unreliable. Documents aren't.
Here's what a handoff looks like in practice:
## Current state (end of session 12) - Feature X landed: [what changed, why, and what it fixed] - Files changed: [list of files touched this session] - Test counts: 164 unit tests, 0 failures ## Known issues - [Issue description with root cause traced to a specific code path] - [Deferred item with rationale for deferral] ## Next session scope - [Scoped task with concrete implementation steps] - [Alternatives considered, with recommended approach] ## How to verify - [Exact commands to run tests] - [Expected output and what to check]
Every session starts by reading this. Every session ends by updating it. The AI walks into each session with full context and zero memory - because it doesn't need memory. It has the document.
Step 3: Execute. Open a conversational AI. Send it the design doc and the handoff. Walk through your next steps. Select a unit of work. Talk through any design nuances. Then hand that scoped task to your coding AI - the one in your terminal or IDE. It implements and reports back. Review the output with your conversational AI. Was the goal met? If not, iterate. If yes, have the coding AI update the design doc and handoff.
Step 4: Clear and restart. Wipe both AI contexts. Start a fresh session next time. This is critical - it keeps context clean and prevents hallucinations. The AI doesn't need to remember anything because the documents carry everything forward.
That's it. Design doc and handoff are the project. Code is throwaway.
I maintain a codebase with a full test suite and zero context drift across dozens of development sessions. The AI has never lost track of the project, never hallucinated a regression, never contradicted an earlier design decision - because it doesn't have to remember. It reads the spec, does the work, and updates the documents.
Going from this to a traditional software engineering workflow feels like picking up a chisel after using a forge.