If you've ever fielded questions about Go project structure—the mundane stuff like where config lives, why there's no pkg/ directory, or the difference between internal/books/ and internal/database/books/—you know how quickly a simple answer turns into a wall of text. Developer Aran got tired of that friction. So they built example-project-structure: a minimal Go HTTP/RPC service backed by PostgreSQL structured specifically to serve dual audiences—human developers and AI coding agents.

The Problem With Project Scaffolding The catalyst came from watching AI coding agents fumble project setup. Ask an agent to scaffold a Go project twice and you'll get two different structures with only passing resemblance. One run produces models/, the next spits out entities/, neither matching what you actually want. It's not that these tools lack capability—it's that they're guessing when they should be following a template. "I kept running into the same friction," Aran writes. "Every time I start a new project, I want it in a structure I already know and like. But AI output is non-deterministic."

Writing Documentation for Machines (and Humans) The solution wasn't just better documentation—it was documentation written with an entirely different reader model. The docs/ directory serves dual purposes: layout.md maps every directory for human comprehension, while design-decisions.md captures reasoning behind choices like "Service not Repository" and "package-by-feature not package-by-layer." But the real innovation is BOOTSTRAP.md—a file written specifically for AI agents that assumes they've already cloned the repo and copied its contents into a new project directory.

Inside the Bootstrap Protocol BOOTSTRAP.md reads like a build script crossed with architectural documentation. It walks through every rename, every file to strip, every conditional branch based on user requirements (OpenAPI only? ConnectRPC only? No database?). Each step lists exactly what to change and everywhere it appears, sparing the agent from rediscovering the structure on its own. Aran paired this with a Claude Code skill that asks users a handful of questions—project name, module path, API style, database choice—and then follows BOOTSTRAP.md to scaffold a new project autonomously.

The Structure Itself The reference project is deliberately small:

- api/ — protobuf and OpenAPI schemas - apigen/ — generated API stubs - cmd/bookstore/ — binary entry point - internal/books/ — domain package (one per feature) - internal/database/ — data access, separated from transport - internal/server/ — HTTP/RPC wiring Notably absent: pkg/, models/, and handlers/. Each omission is a deliberate stance. The fake bookstore domain—books, authors, genres—provides just enough complexity to demonstrate joins and type conversions without drowning in features.

Key Takeaways

  • AI agents thrive on concrete examples over abstract rules—they need a reference repo they can copy and modify mechanically
  • Documentation written for non-deterministic readers (AI) must be exhaustive: list every change, every location where it applies
  • Package-by-feature scales better than package-by-layer as projects grow; Aran argues the absence of common directories like pkg/ is a feature, not an oversight

The Bottom Line

This is the right approach to AI-assisted development—not asking models to hallucinate sensible defaults, but giving them reference implementations they can actually follow. If you're scaffolding Go projects with AI tools and getting inconsistent results, the problem isn't the model—it's that you haven't given it a blueprint yet.