Vibes don't ship.

Let’s talk about what it takes to build shippable, maintainable code with AI, no vibing. This series distills what actually worked and what didn’t while I built a personal project of mine, Artist Dashboard, through prompts and read-only access to all files. If you’ve been unimpressed by AI or focused elsewhere, then this series is for you. We drop the hype and buzzwords and focus on what actually makes progress from proven results. Vibes don’t ship. Discipline does.

In this first post, I outline the key components of a stable AI development environment, line up terms used across both industries, and outline the general approach.

Even if you are familiar with all of these concepts and actively use them, I still encourage you to stick around for this series. I promise you will learn something.

What changes with this approach (for skeptics)

• Gates, not guesses. Test-driven development is key to ensuring the generated logic is functioning and meets the spec. If you can't test it, assume it’s broken.

• Read‑only first. Agents start read‑only; write access is staged, time‑boxed, and audited.

• Least‑privilege tools. Tool calls run with scoped keys and human approvals on risky paths.

Trust boundaries (how we keep risk contained)

• Data: Protect PII, limit access, track agent workflows with audit logs

• Keys: Least‑privilege, short‑lived tokens; exclude sensitive files from context and from access.

• Write access: Agents start with zero trust permissions and have them added as required.

• Audit: Correlation IDs on tool calls; every action ties back to a commit and PR.

• Version Control: Repository versioning for change control and restore points for failures.

What is Artist Dashboard (and why it wasn’t trivial)

Artist Dashboard is a cloud‑native, containerized web app that lets artists upload once and publish everywhere. It’s a long-standing personal project that became my testbed a year ago, when I needed a real product and repository to test Agentic software development in real-world use cases properly.

Under the hood:

• Frontend: React + TypeScript + Tailwind

• Backend: FastAPI + PostgreSQL + Redis

• Media: Globally distributed object storage + a high‑throughput upload engine for large files

• Infra/DevOps: Terraform → DigitalOcean Kubernetes (DOKS)

• Quality gates: 200+ unit/integration tests; 20 Playwright E2E tests tied to user stories

• Scale target: Designed for ~10k global users (we didn’t fully load‑test before pausing)

• Metrics: 60,000 lines of code across all components, with about 75 active API endpoints.

We’ll use real incidents and refactors from this project to explain what to keep, what to cut, and how to avoid vibe‑coding yourself into a wall. We will also cover debugging and troubleshooting live environments using agentic approaches, along with what works and doesn’t.

The developer‑to‑agentic translator (same engineering, different jargon)

📄 Bring a spec, not a vibe
Developer terms: Design doc · Product Requirements Document (PRD) · Architecture Decision Record (ADR)
Agentic lingo: Task spec · Workflow graph · Supervisor/prompt
Use it like this: Treat the PRD/ADR as the contract. Instruct agents (via prompt/supervisor) to review and follow the PRD exactly. ADRs keep decisions stable so agents don’t relitigate them later.

✅ Make tests the gate
Developer terms: Unit · Integration · E2E tests
Agentic lingo: Offline · Online evals
Use it like this: Keep the test pyramid and define evals in the PRD alongside acceptance criteria. Evals augment, not replace, E2E, but both are required checks in CI. If it isn’t passing, it doesn’t progress.

🔒 Protect ‘main’
Developer terms: Protected branches · Required status checks
Agentic lingo: Gated runs (evaluation pass required)
Use it like this: Add your eval job and Playwright E2E to your testing workflow. Reference those gates in the PRD. Define per‑agent rules: work is “done” only when the tests pass.

🧭 Keep humans in the loop (HITL)
Developer terms: Feature flags · Code review · “Ask Steve”
Agentic lingo: HITL interrupts · Guardrails · Tool approvals
Use it like this: Specify where HITL applies (risky writes, external calls). Use approval interrupts for tool calls and enforce surgical diffs. HITL is both a gatekeeper and a safety net.

📜 Contract your tools
Developer terms: RBAC · OpenAPI/JSON Schema · Contract tests (e.g., Pact) · SemVer
Agentic lingo: Structured outputs · Function/Tool calling · MCP connectors
Use it like this: Define allowed tools per agent/team/product and enforce least‑privilege RBAC and auto-approved commands. Require schemas and structured outputs; version changes; add contract tests. Adopt MCP only when cross‑client portability/discoverability is worth the abstraction. Prefer direct SDKs/CLI by default.

Bottom line: Agentic AI doesn’t replace engineering discipline; it expects it.

Week‑one checklist (make this real)

You should see immediate results if you implement these in your environment. Start local and simple. Test, then tweak lightly and test again. Don't worry if you're not sure how to; we will cover these throughout the series.

🧾 Spec‑first
Add a one‑page PRD and a lightweight ADR to your repo. Every feature starts here; every workflow and agent graph answers to it. Keep docs short and focused so they don’t rot.

🧑‍🏫 Define user stories
Add user stories to the PRD for core features and workflows. They’re spec‑driven and complete (happy path + at least one failure path).

🔁 User stories → tests & evals
Keep the test pyramid (mostly unit, some integration, a thin E2E layer). Derive Playwright E2E tests from stories and define evals in the PRD acceptance criteria section for each story. Both are merge gates.

🧪 TDD with evals
Build evals to spec for each user story, then implement the feature on a branch until tests + evals pass. Add a small rules file per task with the TDD flow and “done” criteria.

🧭 Guard the context
Use HITL interrupts to approve sensitive tool calls and enforce surgical diffs (freeze high‑risk files). “Please approve the deployment of branch “dev“ to production“

🔧 Control your tools (stretch)
Add only the tools/MCPs you actually need; remove the rest. Limit auto‑approval to safe, least‑privilege tools. Assess whether your team needs an MCP server at all, treat it like a private npm/PyPI with versioning and contracts. Prefer direct SDK/CLI when it’s simpler.

Why managers should care (three quick wins)

📈 Predictable delivery (and happier seniors)
PRDs + required checks cut noise, reduce regressions, and shrink PR review thrash, freeing senior engineers to solve real problems. Expect better lead time and lower change‑failure rates.

🧑‍🤝‍🧑 Developer‑first adoption
The teams who use this should design it. Set clear non‑negotiables (spec‑first, tests‑as‑gates, tool approvals) and let them run. This series fills any gaps.

🛠️ Back in the trenches safely!
AI lowers the cost to prototype and raises the bar on feedback. Even if you haven’t coded in years, you can build PoC/PoV apps, drive PRD workflows, review acceptance criteria, and run eval checks to validate outcomes.

Paid subscribers: the Starter Pack

Get the artifacts that worked for me and my teams as they are released:

• PRD + ADR templates (Markdown) with real examples

• Playwright E2E test cases (user registration, video file upload, login to dashboard, etc.)

• Effective Prompt kit (build, test, fix and troubleshoot prompts)

• Tool configuration and config files

• Guardrails bundle (rules file + pre‑commit hooks + example test cases)

• Anything I can’t fit in the deep dive post, I’ll share here.

What’s next

• PRD Fundamentals for Agentic Teams — spec‑first, with the exact PRD/ADR skeleton I use (templates included).

• Testing as the Gatekeeper — pairing evals with Playwright for real‑world stability.

• MCP Reality Check — where it helps, where it hurts, and how to contract it safely.

I’ll mix in templates, prompts, and code snippets from Artist Dashboard so you can paste, adapt, and ship.

👉 If this resonates, share it with your team and subscribe for the deep‑dive Starter Pack and ongoing case studies.