Discovery and Spec: The Missing Harness in AI-Assisted DeFi Development

A few weeks ago I wrote about the CI pipeline I set up before writing the first contract on American Spend. Ten gates — formatter, static analysis, mutation testing, formal verification — all designed so that when an AI agent writes code, quality doesn't depend on the agent's judgment. The pipeline enforces it.

That's one half of what OpenAI has been calling Harness Engineering: building the environment in which AI agents operate reliably, so the model is just one component and the spec, constraints, and feedback loops are the harness. The CI pipeline is the downstream harness — it catches bad code after it's written.

But there's an upstream harness — and in AI-assisted DeFi development, it's mostly missing.

The problem the pipeline can't solve

A CI pipeline can catch a reentrancy bug. It can't easily catch an incentive structure that looked rational on a whiteboard but becomes a drain target the moment a rational actor looks at it sideways — and when it does, it's usually an auditor who finds it, not a linter.

Most DeFi failures I've seen post-mortem don't trace back to bad code — they trace back to an assumption nobody challenged before the first commit. By the time a test suite or audit surfaces it, the architecture is already built around the flaw. What follows is rounds of refactoring, new audit cycles, and a bill that can make the whole thing financially unviable. These are things you have to reason through before the AI opens the editor.

The upstream harness is the structured process that forces that reasoning — and gives the AI a well-defined context to code against once it's done.

The missing harness: `defi-builder-skills`

I packaged this process as a marketplace of Claude Code skills: defi-builder-skills.

Two skills. Two phases of the build.

defi-protocol-discovery takes you from blank page to a go/no-go decision through seven phases:

Opportunity Discovery — systematic scan when you don't have a specific idea yet
Idea Sharpening — Jobs-to-be-Done framing, 5 Whys, problem/solution separation
Landscape & Analogues — competitive map, what succeeded and why, what failed and how
DeFi Lean Canvas — value proposition, unique mechanism, channels, revenue, bootstrapping path
Economic Viability — sustainable yield audit, TVL scenarios, unit economics, bootstrapping cost
Risk & Assumptions — ranked assumptions, death spiral mapping, validation plan
Go / No-Go — kill criteria first, then synthesis, verdict, and a Protocol Brief

The output is a set of structured documents in .discovery/ in your project. If the verdict is GO, the Protocol Brief feeds directly into the next skill.

defi-spec-driven runs six specification phases before a single line of Solidity:

Research — canonical implementations, post-mortems, known failure modes
Economic Design — invariants, stress tests, oracle and MEV analysis
Architecture — contract system, access control, on/off-chain boundaries
Threat Modeling — per-function attack vectors and mitigations
Interface, Storage & Events — REQ-* slugs, storage layout, error types
Test Specification — fuzz targets, attack scenarios, unit test specs

After the spec, it bootstraps a Foundry project from melanke/foundry-security-template — the same template the CI pipeline post is built around — and guides implementation function by function: implement, test, gate, commit, with two audit passes per contract built in.

Three things that shaped the design

Kill criteria before synthesis. In the go/no-go phase, the skill asks you to define what would make this a clear no before synthesizing whether it's a yes. In practice, almost no one does this — the instinct is to build the case for your own idea. Forcing kill criteria first prevents survivorship bias from creeping into the verdict.

Challenge mode, not document mode. A discovery process that just turns your idea into a polished canvas isn't a discovery process — it's a writing exercise. Every phase has a "most dangerous assumption" check built in. The skill's job is to find the weakest point in your economic model before the AI finds the weakest point in your codebase.

Implicit assumptions are attack vectors. An unresolved ambiguity in the economic model becomes an implicit assumption in the spec. An implicit assumption in the spec is a potential attack vector in the code. Everything has to be resolved explicitly before the go/no-go — nothing gets answered silently with optimism.

Key trade-off: this process is deliberately slow at the front. Discovery takes hours. The spec phases take days. What you're buying is a code phase that moves faster, with fewer reworks, and without the category of failure that shows up months after deploy — the kind the pipeline would never have caught anyway.

How to install

/plugin marketplace add melanke/defi-builder-skills
/plugin install defi-protocol-discovery@defi-builder-skills
/plugin install defi-spec-driven@defi-builder-skills

Repository (CC-BY-4.0): github.com/melanke/defi-builder-skills

Start from any entry point:

/defi-protocol-discovery                        — open exploration, no idea yet
/defi-protocol-discovery something for LPs      — focused on a space
/defi-protocol-discovery A fixed-rate lending vault for protocol treasuries

Final thought

The CI pipeline is the seatbelt. The discovery and spec workflow is the road test you run before you get on the highway. Both are part of the same discipline: building the harness that lets AI move fast without moving recklessly.

Neither replaces good engineering judgment. Both make it easier to apply.

If you're building in DeFi and want to compare notes on this workflow — or on Harness Engineering more broadly — feel free to connect or message me. I'm always open to exchanging ideas with other builders.

Written by Gil, a fullstack developer with over 15 years of experience and a strong focus on practical software architecture and blockchain technology.