The AI writes the code.
You're the architect.
Draw the system, the shape of the code and the screens. Hunch hands them to your AI as a plan it follows, and checks what it wrote.
Encore: tickets for small venues, where sales open at 10:00 and thousands of fans arrive in the same minute. Drawn in Hunch; the same app runs down this page. Follow it
Draw the system.
The parts, what talks to what, and the boundaries around them. Every box knows what it is: a cache holds, a queue lines work up, a payment provider can go down.
Ask how many people arrive at the busiest moment, and the answer comes in words, with the fix.
10K people at 10:00
At 10K people, Tickets API gives out first: it gets 1.3× what it can take.
Pages take about 4.9 s in the slow case.
The fix, one click
Run 4 copies of Tickets API.
Holds 10K people at the busiest moment. The fullest part people wait for is Tickets API, at 63%.
If Payments goes down
Fan: an error on every request that needs Payments.
And these stop getting work: Ticket jobs, Ticket issuer, Ticket PDFs, Email.
Choose the shape of the code.
Onion, Clean architecture, Hexagonal, Layered, Feature-Sliced Design, MVC, Modular monolith, Vertical slices, or your own layers. Inside the Tickets API box, the code is hexagonal: the use cases talk to ports, and Postgres, Redis, Stripe and SQS plug in from outside.
Every import is checked against that shape, on the board, on the command line and in CI. When an AI takes a shortcut, the arrow turns red.
1import { Order } from "../../domain/order";2import { stripe } from "../../adapters/stripe/client";34export async function payForHold(input: { holdId: string }) {5 const order = Order.fromHold(input.holdId);6 await stripe.paymentIntents.create({ amount: order.total, currency: "brl" });7 return order;8}
Pay for a hold (ports) may not import StripePayments (adapters)
Sketch the screens.
Encore has 5 screens, drawn by hand: the fan's on a phone, the organizer's on a desktop. What is on each one, in order, and where each button goes. The fields are the order's fields; the buttons call the endpoints of the Tickets API, and Hunch checks that they exist.
The look goes to the AI as words and tokens. Hunch never paints the sketch.
Hand it to the AI.
One button turns the three boards into what your AI needs: a prompt for a chat, or a folder for an assistant with a terminal, with the stories, the API, the screens and where each piece of code goes.
What the boards leave open is asked before the AI starts, so it doesn't fill the gaps on its own.
What it would have to guess, asked first
- Which key does Payments need, and where does it come from?
- Which key does Email need, and where does it come from?
- Which key does Ticket PDFs need, and where does it come from?
- Where will it run?
The prompt you paste
Read AGENTS.md in this folder and build what it describes. It has the whole spec; docs/ and tasks/ are there for detail.
The folder it builds from · 53 files
- .dependency-cruiser.cjs
- .env.example
- AGENTS.mdthe one file it reads first
- CLAUDE.md
- OPEN_QUESTIONS.md
- board.hunch
- eslint.boundaries.mjs
- hunch.json
- hunch.schema.json
- .claude/skills/hunch/ SKILL.md
- boards/ 3 files: api.hunch, app.hunch, dashboard.hunch
- docs/ 19 files: api.md, architecture.md, conventions.md, …
- docs/adr/ 4 files: 0001-a-hold-lasts-10-minutes-in-redis-a-seat-is-sold-only-when-th.md, 0002-payment-calls-carry-an-idempotency-key-and-payment-webhooks.md, 0003-tickets-are-made-after-the-payment-by-a-worker-behind-a-queu.md, …
- docs/screens/ 4 files: checkout.md, show.md, shows.md, …
- scripts/ check-shape.mjs
- tasks/ 11 files: 001-setup.md, 002-data-model.md, 003-auth.md, …
- tests/ screens.spec.ts
Your AI, in the loop.
The board isn't a drawing you hand over once. Your AI can draw it, review it, read it and keep it up to date, while you decide.
From a chat: Draft with your AI
Describe the app and the AI you already use draws the first board. Or ask it to review the board, or to sketch the screens from the stories. Hunch writes the request; you paste the answer back and see what would change before anything does.
From the terminal: the board as an MCP server
Your assistant reads the board, updates it when the design changes, asks what the board leaves open, and checks every import before it finishes. It runs on your machine.
mkdir -p .hunch && curl -fsSL https://hunch-smoky.vercel.app/hunch.mjs -o .hunch/hunch.mjs claude mcp add hunch -- node .hunch/hunch.mjs mcp
We measured it.
The same app, an expense approvals API, built three times by the same model: from Hunch's files, from a paragraph, and from a paragraph after the AI interviewed the person. The paragraph was cheaper and got 5 status codes and 3 rules wrong. With Hunch, 0 of 19 imports left the shape, and nobody was asked a single question.
| Measure | Hunchthe board | Interview firsta paragraph, then questions | A paragrapha paragraph |
|---|---|---|---|
| Business rules followed | 34/34 | 34/34 | 31/34 |
| Status codes as agreed | 12/12 | 12/12 | 7/12 |
| Questions you answer | 0 | 36 | 0 |
| Longest function | 34 lines | 84 lines | 146 lines |
| Tokens | 82.4K | 224K | 43.7K |
One run per arm, one model, designed and scored by Hunch's author. The full report
A board is a text file.
Short enough to type, regular enough for an assistant to write, and reviewed in a pull request like the rest of the repo. Edit the text and the board follows.
board.hunch, edit it
5 boxes · try adding: pay: Payment provider "Payments" "Stripe"
Questions.
- Does Hunch write the code?
- No. The AI you already use does. Build with AI gives it the plan: what to build, the stories with acceptance criteria, the screens, the data, where each piece of code goes. Hunch checks the imports against the shape you chose.
- Which AI does it work with?
- Any. Hunch never calls an AI: it prepares the prompt or the folder, and you paste it into Claude, ChatGPT, Gemini, Lovable, v0, Bolt, Claude Code, Cursor or Codex.
- Can I start from what I already have?
- Yes. An Excalidraw drawing, a docker-compose file, Kubernetes manifests, Terraform, a Mermaid chart or a few sentences become a first board. A GitHub repository (TypeScript or JavaScript) becomes its code board.
- Where are my boards?
- In this browser and in the .hunch files you save, next to your code. There is no account and no server holding them. The dashboard backs up every board to one zip.
- Can my AI assistant use the board directly?
- Yes. The Hunch CLI is one file that runs with Node, and it is also an MCP server: Claude Code, Cursor or Codex can read the board, change it, list what it leaves open, check the code and regenerate the pack, on your machine.
- Is it free?
- Yes. It runs in your browser and there is nothing to sign up for.