I wanted my next side project to look like the kind of code I'd ship at work — hexagonal architecture, sqlc, depguard, integration tests — without the usual side-project tax of spending three evenings on scaffolding before writing the first line of domain logic. So I built it twice. First, I forked a Go backend template I'd been hardening for months. Then I drove every feature on top of it through a structured AI workflow I call qrspi: question → research → structure → plan → implement.
The product itself is unremarkable on purpose: a QR code generator. Paste a URL, get back a scannable PNG and a /r/:token
redirect, with per-link scan counts and a soft-delete kill switch. The interesting part — the part I'd want a reviewer to look at — is the process that produced it.
Repo: linkc0829/go-qrcode-generator. Every artifact mentioned in this post is committed there. Step zero was actually choosing what to build on. I shortlisted several Go backend templates, walked through each one with Claude to pressure-test the architecture, and landed on the one I'd been hardening for a while: linkc0829/go-backend-template.
The template is a feature-first hexagonal Go backend. Each feature lives in a single package under internal/<feature>/
, and inside that package, domain.go
, service.go
, ports.go
, and the adapters sit side-by-side as separate files. The Go package boundary is the hexagon edge.
What makes it stick is depguard
in .golangci.yml
. The build fails if:
domain.go
imports anything beyond stdlib and shared value objectsservice.go
reaches for a driver or web frameworkhandler_*.go
touches a repo or cache directlyThat last rule is the one that pays the most rent. Cross-feature dependencies are forced through capability ports — feature A defines an interface named after the capability it needs, and the composition root in internal/bootstrap/wire.go
injects feature B's service to satisfy it. The features never know about each other.
This was the first decision I had to actually live with. The template ships with demo user
, order
, and payment
slices. My project has no orders and no payments. The rule is: don't leave dead code as "future scaffolding." Delete the whole slice — the package, the wire block, the SQL queries, the migration tables, the OpenAPI paths, the depguard block. make lint && make test
after each removal flushes out dangling references. By the time I started writing QR code logic, the repo only knew about things that existed.
The functional spec came from a system-design exercise I'd worked through separately:
The high-level design called out the load shape — read-heavy, one write to thousands of reads — and the levers that fall out of it: stateless API behind a gateway, cache qr_token → image_url
, CDN the PNGs, index on qr_token
. Tokens were originally specified as base62(SHA-256(url + user_secret))
.
For the local build, I wrote down explicit deviations from the spec rather than pretending they didn't exist:
crypto/rand
→ base64url
. Loses idempotency for repeated (user, url) pairs but avoids the deterministic-token leak surface.download
bucket policy. Same architectural shape as S3+CloudFront, minus the edge cache.Writing the deviations down up front is the part that makes the design honest. It's also the part that makes a portfolio reviewer's job easier — they can see what was traded and why, not just what got built.
The workflow idea started from Research-Plan-Implement (RPI). QRSPI is an 8-phase extension of it that I picked up from community discussions and adapted for this project.
Once the spec was on paper, every feature went through the same eight phases. Each phase is a slash command backed by a skill, and each one writes its artifact to thoughts/qrspi/<date>-<slug>/
:
/qrspi:1_question
/qrspi:2_research
/qrspi:3_design
/qrspi:4_structure
/qrspi:5_plan
/qrspi:6_worktree
/qrspi:7_implement
/qrspi:8_pr
The MinIO feature shows the whole thing on disk: a ticket.md
pulled from the Notion source via MCP, then questions.md
, research.md
, design.md
, structure.md
, and plan.md
. Each one builds on the last. By the time implementation starts, the agent isn't guessing — it's executing a plan I already agreed with.
The follow-up Redis redirect cache shipped the same way. The plan called out the read-heavy shape, picked a write-behind click-count buffer to avoid hammering Postgres on every scan, and named the cache invariants explicitly. The implementation was almost mechanical because the design phase had already resolved the interesting questions.
The cost is real: each feature carries five or six markdown files of design artifacts. For a single-developer side project, that's overhead I wouldn't tolerate in a freeform sketch.
What it buys:
design.md
, in plan.md
— keeps the next session grounded.The template is on GitHub; the qrspi artifacts are committed alongside the code. If you want to see how a single feature flows from ticket to PR, the MinIO slice is the cleanest example. The architecture ADRs in docs/adr/
cover the two foundational decisions: feature-first hexagonal, and sqlc over an ORM.
Next up: a metrics slice (Prometheus + a Grafana dashboard for redirect latency), and a proper deletion follow-up so the spec's full CRUD surface lands. Both will go through qrspi. That's the point.