Over the past few weeks, one of the biggest shifts in my thinking has been this:
I want to spend less time writing specifications and implementation plans by hand, and more time on design.
The surprising part is that AI has made that possible — not by replacing engineering judgment, but by changing where that judgment is applied.
Today, I increasingly let AI draft specifications, implementation plans, and even code. My job has shifted toward defining intent, identifying constraints, and reviewing decisions. The writing itself has become the least valuable part of the process.
From Documentation to Executable Specifications
The specifications I'm talking about aren't traditional documentation.
They're not written for future engineers casually browsing a wiki. They're written for the next AI session that needs to continue the work without requiring me to re-explain everything from scratch.
That changes how they look. Instead of narrative descriptions, they focus on:
- Requirements
- Constraints
- Acceptance criteria
- Verification steps
In other words, they're designed to be executed against rather than read.
The audience is no longer a human reader. The audience is the next contributor — whether that's an engineer or an AI agent.
Building State Software One Constraint at a Time
The project I've been focused on recently is rewriting an existing product to follow a new architecture without changing the existing business logic.
That combination creates a challenge that's almost entirely about constraints:
- A reference architecture that must be followed
- A legacy system that remains the source of truth for business behavior
- Integrations that return opaque responses we are not allowed to interpret beyond approved boundaries
- State-specific rules that cannot be altered
This isn't a CRUD application problem.
It's a constraint management problem.
And constraints are exactly the kind of information AI can work with effectively — if they're captured clearly.
The Workflow: AI Drafts, Humans Approve
Over time, our workflow has evolved into a series of deliberate review gates:
Intent → AI Specification → Human Review → AI Implementation Plan → Human Review → AI Code Generation → Testing & Validation
I provide:
- The goal
- The requirements
- The constraints
- The architectural boundaries
AI generates the first draft of the specification. I review it. AI generates an implementation plan. I review it. Only then does code generation begin.
The result is that I'm writing far less than before. But I'm reviewing far more carefully. And that's where most of the engineering value now lives.
What Good Specifications Look Like
Our specifications are intentionally structured like test plans.
A specification doesn't explain how code works. It defines observable requirements.
For example, a refactoring specification might include:
No class in the application layer may directly reference DAO implementations.
The acceptance criteria become executable checks:
- Application services no longer inject DAO classes
- Layering violations return zero matches when searched
- Dependency boundaries remain intact
The specification defines what must be true.
The implementation plan defines how to make it true.
Those are different documents serving different purposes — keeping them separate has proven incredibly valuable.
The Highest-Leverage Engineering Skill: Identifying Load-Bearing Constraints
The most important thing I do today isn't writing.
It's determining which constraints are truly load-bearing.
Architectural foundations (critical — violating these can break everything):
- Database initialization strategy
- Deployment model
- Integration boundaries
- Runtime ownership rules
Conventions (useful, but not critical):
- Package naming
- Folder organization
- Service naming patterns
Then there are intentional deviations — things that appear wrong but exist for legitimate operational reasons. Those can be the most dangerous. A well-intentioned cleanup can accidentally break a production system because it removes something that looked like technical debt but was actually preserving compatibility.
When AI produces a specification, my primary review question is simple:
Did it correctly identify which constraints are load-bearing?
That's still a human judgment call. And it's a far more valuable use of my time than writing the initial draft myself.
The Spec Is Long-Term Memory
This is the realization that changed how I think about AI-assisted development.
Individual AI sessions are temporary contributors. They appear, contribute, and disappear.
The value doesn't come from any single session being exceptionally intelligent. The value comes from every session sharing the same source of truth:
- Specifications
- Implementation plans
- ADRs (Architecture Decision Records)
- Conventions
- Status tracking
Together, these artifacts become the project's long-term memory.
The AI session is temporary. The memory persists.
When the Source of Truth Stops Being True
I learned this lesson the hard way.
At one point, our documentation drifted. An ADR stated that database schemas were initialized through startup scripts rather than Liquibase. However:
- A changelog still contained schema bootstrap logic
- A README described a different strategy
- Comments in the code claimed something else entirely
Three artifacts. Three different stories.
A new contributor — or AI session — reading the repository would inherit the wrong mental model immediately.
The fix wasn't complicated. We simply asked:
What actually happens on a clean environment build?
The operational behavior became the arbiter of truth. Once we verified reality, we:
- Removed obsolete artifacts
- Updated documentation
- Aligned ADRs and implementation
- Refreshed project status tracking
The result wasn't cleaner documentation. It was restored trust in the source of truth. And that's what allows future contributors to move faster.
Our Project Structure
Here's how this translates into the actual repository layout without the microservice modules:
state-retail/
├── CLAUDE.md # THE WORKFLOW — human-review gates. Read first.
├── README.md # Entry point: layout, doc map, schema strategy, how to run.
├── status.md # Living index of every spec/plan and its state.
│
├── specs/ # The WHAT (and why)
│ ├── CONVENTIONS.md # Authority — wins on overlap
│ ├── architecture.md # Layering & naming reference
│ ├── global-rules.md # Cross-cutting rules
│ ├── infra.md # DB / Docker / schema-management contract
│ └── <module>/<RR-NNN>-<slug>.md
│
├── plan/ # The HOW, mirroring specs/
│ └── <module>/<RETAIL-NNN>-<slug>.md
│
├── rules/ # Class-level coding conventions per layer
│ └── domain / dao / service / application / api
│
└── docs/adr/ # WHY significant decisions were made
└── NNNN-<slug>.md # Immutable once Accepted; supersede with a new ADR
Design Is Becoming More Valuable Than Authoring
AI is increasingly capable of generating specifications, plans, and code.
What it cannot do reliably is determine which constraints matter most to your business.
That remains a software engineer's responsibility.
For organizations building complex, highly regulated systems, this is more than a productivity improvement. It's a way to accumulate executable knowledge over time — every new project starts with shared memory rather than a blank page.
Because increasingly, the code is cheap artifact.
The specification is the asset.
