Skip to main content

EP5. Architecture-Driven Generation in Practice

💡 From "Write the Code" to 72 Verification Checks​

"develop jsondb."

A typical AI might cheer "Sure!" and flood the screen with hundreds of lines. Cocrates pleasantly misses our expectation again.

🦉 Cocrates: "What will you use this jsondb for? I'll design the architecture first, get your review and approval, then generate code safely."

Not swinging the axe first (Do)—perfecting the blueprint (Plan) first. That's Cocrates' rule for producing artifacts.

This episode follows one sentence—"build it"—as it becomes six ADRs, one spec, seven source files, and 72 verification items.

🏛️ Step 1. ADR — User Intuition vs. AI's 'Easy Suggestion'​

A pattern emerges in dialogue with Cocrates: AI instinctively proposes what it trained on most—what's easiest to implement. Without a human anchor, you drift toward AI convenience.

This project had three fierce architecture debates (ADRs).

1️⃣ [ADR 1] Storage model: "NoSQL is easier" vs. "I need intuitive paths"​

  • AI's first pitch: MongoDB-style collection-document structure.
  • User's brake: "I need path-addressable storage—Set("episode/e1") → episode/e1.json."
  • Outcome: Broke AI's default; pivoted to folder/file path mapping.

2️⃣ [ADR 2] Architecture: "Library-only is simpler" vs. "Multiple agents will use it"​

  • AI's first pitch: Single-process internal library—easy to handle.
  • User's brake: "What if multiple AI agent processes read and write this DB at once? We need client-server."
  • Outcome: Cocrates admitted the miss and redesigned around REST API server (jsondbd) plus CLI.

3️⃣ [ADR 3] Concurrency: "Lock the whole DB" vs. "Lock per file"​

  • AI's first pitch: DB-level lock—three lines of code; whole DB pauses on write.
  • User's brake: "That's a huge bottleneck on a server! Per-file locks when touching different files."
  • Outcome: Upgraded to a high-performance engine using sync.Map for concurrency.

💡 Lesson: When AI says "this is easy and good," it may be the trap that's easy for it to build. Only humans know real context and scenarios.

📝 Step 2. Spec — One Blueprint​

After ADRs were approved, Cocrates merged decisions into one constitution: spec/jsondb.md.

Self-contained: read this doc alone and you see ten REST endpoints, API signatures, CLI commands, and test requirements at a glance.

⚡ Step 3. Generation — Driven Only by Spec​

With spec locked, Cocrates enabled spec-driven-generation. It forgot the vague opening prompt and coded only from our agreed spec.

  • Output: Seven core Go library files, REST server, CLI, unit and integration tests—go build and go vet clean on first pass.

🔍 Step 4. Verification — A Net of 72 Checks​

Code done doesn't mean celebration. Cocrates ran spec-driven-verification, splitting every spec requirement into an inventory and comparing.

📊 Scoreboard: 70 PASS, 1 FAIL, 1 unverifiable out of 72

One deviation and silent AI defaults surfaced in an otherwise perfect-looking forest.

🚨 Caught deviation​

  • Spec: jsondb schema set /blog/episode → PUT /schema/blog/episode
  • Actual code: Duplicate slash → PUT /schema//blog/episode
  • Server tolerated it—but API consistency broke. Easy to miss without verification.

🤫 Undocumented ASR (silent defaults)​

Six implicit design choices AI made where the spec was silent:

  • Missing URL encoding when combining query parameters; skipping schema re-validation on data updates—and more.

💡 Lesson: "We have a spec—code must be perfect" is naive. Gaps get filled arbitrarily—run verification and keep the spec a living document.

📝 Three-Line Summary​

  1. Doubt AI's 'easiest suggestion.' Business context and performance are human jobs.
  2. Spec is alive. Update it when verification finds missing requirements.
  3. Cocrates' value isn't printing answers. It's pacing architecture through dialogue so you examine every step.

🎬 Coming Up Next​

We've completed a full cycle on Cocrates' design system. Time to go further.

Next: beyond using existing skills—build a new architecture-driven generation skill with Cocrates (e.g. document/report automation). Hands-on skill building.

Before that session, ask yourself:

"Have I ever copy-pasted AI's first code suggestion without a second thought?"

This series introduces the Cocrates Harness framework. Cocrates is an agent harness designed for Socratic dialogue so users keep agency and grow.