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.
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:
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.
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:
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.
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:
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.
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:
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 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):
Conventions (useful, but not critical):
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.
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:
Together, these artifacts become the project's long-term memory.
The AI session is temporary. The memory persists.
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:
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:
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.
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>/<NCEVR-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
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.