ProjectShowcase: Designing Before Building

A CLI tool for surfacing developer work as structured portfolio data — conceived through sixteen design proposals before a single line of production code was written.

Problem

Developers accumulate years of meaningful work across repositories, commits, and projects, yet consistently struggle to articulate that work in a compelling, structured way. The résumé problem isn’t a shortage of accomplishment — it’s a shortage of systems for capturing and presenting it. ProjectShowcase addresses this by treating a developer’s own project history as a data source, extracting signal and shaping it into portfolio-ready narratives and structured output.

The tool targets macOS developers working in Swift who want a local, command-line-driven workflow for generating showcase content without depending on external services or manual curation.

Approach

ProjectShowcase is a Swift 5.9 package built for macOS, using swift-argument-parser as its sole dependency — a deliberate choice that keeps the tool lightweight, scriptable, and composable with other CLI workflows. The package is organized into three targets: the core ProjectShowcase library, a ShowcaseCLI executable, and a ProjectShowcaseTests suite, separating concerns between the domain logic, the command surface, and verification.

What distinguishes the approach most sharply is what happened before implementation: sixteen design proposals. This is a design-first workflow in the most literal sense — the architecture, key rules, quality gates, and development workflow were all written down and iterated on in CLAUDE.md before commits began. The presence of sections covering Session Start, Development Workflow, Key Rules, Quality Gate, and References suggests a developer who treats the thinking as the hard part and the code as the artifact of that thinking.

Results

The project stands at its initial commit as of May 2026, with the full architecture established and the foundational code in place. One commit, one contributor, one branch — the snapshot of a tool that has been carefully pre-thought and is now at the threshold of active development. The sixteen design proposals represent the primary output of the project’s first phase: a thoroughly considered blueprint ready to be built against.

Judgment Calls

The most telling decision here is the ratio of design artifacts to code commits: sixteen proposals to one commit. This is not indecision or delay — it is a deliberate inversion of the typical “build first, think later” pattern that leads to expensive rewrites. By front-loading architectural decisions into a structured CLAUDE.md with explicit quality gates and workflow rules, the developer created a contract with future work: any implementation has to earn its place against a written standard.

Choosing swift-argument-parser and nothing else as a dependency reflects a similar discipline. Portfolio tooling often accretes integrations — APIs, cloud services, formatting libraries — that add fragility. Keeping the dependency surface minimal means the tool runs wherever Swift runs on macOS, with no authentication, no network requirement, and no third-party drift.

The three-target package structure also signals architectural maturity for a project at day one. Separating the CLI entrypoint from the core library isn’t required at this scale, but it preserves the option to use ProjectShowcase as a library later — testable in isolation, importable by other tools, and not tightly coupled to the argument-parsing layer.

The work visible here is the work of someone who has learned, probably through experience, that the most expensive mistakes happen before the first commit.