{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreicocnku2njbxm5vkb6x67gwv5mloqvovk5nzkjgsno4bcidmgpukm",
    "uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3moigq5kil7g2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreifvlvycgxup7k2ummmmhss4ashoqvzgx33xvbljl4lferpq3r5vli"
    },
    "mimeType": "image/webp",
    "size": 62438
  },
  "path": "/daniel_wu_cac679a2760ba0a/the-code-is-cheap-artifact-now-the-spec-is-the-asset-3b02",
  "publishedAt": "2026-06-17T13:32:46.000Z",
  "site": "https://dev.to",
  "tags": [
    "ai",
    "architecture",
    "agents"
  ],
  "textContent": "Over the past few weeks, one of the biggest shifts in my thinking has been this:\n\n> **I want to spend less time writing specifications and implementation plans by hand, and more time on design.**\n\nThe surprising part is that AI has made that possible — not by replacing engineering judgment, but by changing _where_ that judgment is applied.\n\nToday, 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.\n\n##  From Documentation to Executable Specifications\n\nThe specifications I'm talking about aren't traditional documentation.\n\nThey'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.\n\nThat changes how they look. Instead of narrative descriptions, they focus on:\n\n  * Requirements\n  * Constraints\n  * Acceptance criteria\n  * Verification steps\n\n\n\nIn other words, they're designed to be **executed against** rather than read.\n\nThe audience is no longer a human reader. The audience is the next contributor — whether that's an engineer or an AI agent.\n\n##  Building State Software One Constraint at a Time\n\nThe project I've been focused on recently is rewriting an existing product to follow a new architecture **without changing the existing business logic**.\n\nThat combination creates a challenge that's almost entirely about constraints:\n\n  * A reference architecture that must be followed\n  * A legacy system that remains the source of truth for business behavior\n  * Integrations that return opaque responses we are not allowed to interpret beyond approved boundaries\n  * State-specific rules that cannot be altered\n\n\n\nThis isn't a CRUD application problem.\n\nIt's a **constraint management problem**.\n\nAnd constraints are exactly the kind of information AI can work with effectively — if they're captured clearly.\n\n##  The Workflow: AI Drafts, Humans Approve\n\nOver time, our workflow has evolved into a series of deliberate review gates:\n\n\n\n    Intent → AI Specification → Human Review → AI Implementation Plan → Human Review → AI Code Generation → Testing & Validation\n\n\nI provide:\n\n  * The goal\n  * The requirements\n  * The constraints\n  * The architectural boundaries\n\n\n\nAI generates the first draft of the specification. I review it. AI generates an implementation plan. I review it. Only then does code generation begin.\n\nThe 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.\n\n##  What Good Specifications Look Like\n\nOur specifications are intentionally structured like test plans.\n\nA specification doesn't explain _how_ code works. It defines **observable requirements**.\n\nFor example, a refactoring specification might include:\n\n> No class in the application layer may directly reference DAO implementations.\n\nThe acceptance criteria become executable checks:\n\n  * Application services no longer inject DAO classes\n  * Layering violations return zero matches when searched\n  * Dependency boundaries remain intact\n\n\n\nThe specification defines **what must be true**.\nThe implementation plan defines **how to make it true**.\nThose are different documents serving different purposes — keeping them separate has proven incredibly valuable.\n\n##  The Highest-Leverage Engineering Skill: Identifying Load-Bearing Constraints\n\nThe most important thing I do today isn't writing.\n\nIt's determining which constraints are truly **load-bearing**.\n\n**Architectural foundations** (critical — violating these can break everything):\n\n  * Database initialization strategy\n  * Deployment model\n  * Integration boundaries\n  * Runtime ownership rules\n\n\n\n**Conventions** (useful, but not critical):\n\n  * Package naming\n  * Folder organization\n  * Service naming patterns\n\n\n\nThen 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.\n\nWhen AI produces a specification, my primary review question is simple:\n\n> **Did it correctly identify which constraints are load-bearing?**\n\nThat's still a human judgment call. And it's a far more valuable use of my time than writing the initial draft myself.\n\n##  The Spec Is Long-Term Memory\n\nThis is the realization that changed how I think about AI-assisted development.\n\nIndividual AI sessions are **temporary contributors**. They appear, contribute, and disappear.\n\nThe value doesn't come from any single session being exceptionally intelligent. The value comes from every session sharing the same source of truth:\n\n  * Specifications\n  * Implementation plans\n  * ADRs (Architecture Decision Records)\n  * Conventions\n  * Status tracking\n\n\n\nTogether, these artifacts become the project's **long-term memory**.\n\nThe AI session is temporary. The memory persists.\n\n##  When the Source of Truth Stops Being True\n\nI learned this lesson the hard way.\n\nAt one point, our documentation drifted. An ADR stated that database schemas were initialized through startup scripts rather than Liquibase. However:\n\n  * A changelog still contained schema bootstrap logic\n  * A README described a different strategy\n  * Comments in the code claimed something else entirely\n\n\n\nThree artifacts. Three different stories.\n\nA new contributor — or AI session — reading the repository would inherit the wrong mental model immediately.\n\nThe fix wasn't complicated. We simply asked:\n\n> **What actually happens on a clean environment build?**\n\nThe operational behavior became the arbiter of truth. Once we verified reality, we:\n\n  * Removed obsolete artifacts\n  * Updated documentation\n  * Aligned ADRs and implementation\n  * Refreshed project status tracking\n\n\n\nThe result wasn't cleaner documentation. It was **restored trust in the source of truth**. And that's what allows future contributors to move faster.\n\n##  Our Project Structure\n\nHere's how this translates into the actual repository layout:\n\n\n\n    state-retail/\n    ├── CLAUDE.md                  # THE WORKFLOW — human-review gates. Read first.\n    ├── README.md                  # Entry point: layout, doc map, schema strategy, how to run.\n    ├── status.md                  # Living index of every spec/plan and its state.\n    │\n    ├── specs/                     # The WHAT (and why)\n    │   ├── CONVENTIONS.md         #   Authority — wins on overlap\n    │   ├── architecture.md        #   Layering & naming reference\n    │   ├── global-rules.md        #   Cross-cutting rules\n    │   ├── infra.md               #   DB / Docker / schema-management contract\n    │   └── <module>/<NCEVR-NNN>-<slug>.md\n    │\n    ├── plan/                      # The HOW, mirroring specs/\n    │   └── <module>/<RETAIL-NNN>-<slug>.md\n    │\n    ├── rules/                     # Class-level coding conventions per layer\n    │   └── domain / dao / service / application / api\n    │\n    └── docs/adr/                  # WHY significant decisions were made\n        └── NNNN-<slug>.md         #   Immutable once Accepted; supersede with a new ADR\n\n\n##  Design Is Becoming More Valuable Than Authoring\n\nAI is increasingly capable of generating specifications, plans, and code.\n\nWhat it **cannot** do reliably is determine which constraints matter most to your business.\n\nThat remains a software engineer's responsibility.\n\nFor 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.\n\nBecause increasingly, the code is cheap artifact.\n\n**The specification is the asset.**",
  "title": "The Code Is Cheap Artifact Now The Spec Is the Asset"
}