How to write a clear engineering job spec

A clear engineering job spec is a one-page document that names the problem you are solving, the day-1 deliverables, the tech stack, the decision authority the role carries, and the weekly compensation. Anything longer is a wishlist; anything vaguer is a recruiter post. Founders who write this spec well get usable shortlists in days. Founders who write "rockstar full-stack ninja" specs spend 60 days screening noise.

This guide gives you the structure, two filled-in sample specs, a good-vs-bad element table, and a quick FAQ. It assumes you are a founder writing the spec yourself, not a recruiter.

Why most job specs fail

Most engineering job specs read like a feature list for a person. "Must have 5+ years of React. Knows AWS. Strong communicator. Bonus: GraphQL, Docker, K8s, Rust." Engineers skim this and learn nothing about the work, the team, or the bar. So either nobody applies, or everybody does, and you sort 400 résumés by gut feel.

The failure is structural. The spec describes the candidate, not the job. A good spec inverts that. It describes the work the person will do in week one, the decisions they will own, and the constraints they must respect. The candidate filter falls out of that, because only people who can do the work will recognise themselves in it.

The second failure mode is hiding pay. If your spec ends with "competitive salary commensurate with experience," half of qualified senior engineers will not even open the email. They have been burned by that phrase before. State the number. We will come back to this.

The 8 sections every spec needs

A working spec fits on one page or one Notion doc. It has these eight sections, in this order:

1. Problem statement. What is broken, slow, or missing? Two sentences.
2. Day-1 deliverables. What lands in week one. Three to five concrete items.
3. Tech stack. Languages, framework, hosting, DB. No "open to options" hedging.
4. Team shape. Who they report to, who they pair with, who they unblock.
5. Decision authority. What they can ship without asking. What needs a check-in.
6. Compensation. Weekly rate or annual salary. Number, not range stew.
7. AI-native expectation. Cursor / Claude / Copilot fluency assumed.
8. Exclusions. What you are not asking for. "No leetcode," "no take-homes longer than 2 hours," "no architecture astronauts."

That's it. No company values paragraph. No "About Us" preamble. Engineers can read your landing page if they care; they need to know the work first.

What goes in each section

1. Problem statement (the why)

Specific failure beats vague mission. Compare:

• Vague: "We are building the future of B2B payments."
• Specific: "Our checkout flow drops 38% of users between payment-method selection and confirmation, and our current backend can't tell us where."

The second one is a job. The first one is a billboard. Engineers want jobs.

If you are pre-launch, the problem statement is "we have a Figma file and a Stripe account; we need a working V1 by July 1." Say that.

2. Day-1 deliverables (the what)

List three to five things that ship in week one. Not week one of onboarding, week one of work. This forces you to be honest about scope.

If you cannot name three week-one deliverables, you do not have a job. You have a research project, and you should hire differently for that (more on this in our PRD guide for non-technical founders).

Good week-one items look like:

• Ship the Stripe webhook handler with idempotency and the 5 event types we care about.
• Refactor the /api/orders route to fix the N+1 query on order line items.
• Add Playwright coverage for the 3 happy-path user flows so we can deploy on Fridays without panic.

Bad week-one items look like:

• "Help shape our engineering culture."
• "Identify and address technical debt."
• "Collaborate cross-functionally."

The bad versions are not deliverables. They are the smell of a founder who has not thought hard enough about what the role does on Monday morning.

3. Tech stack (the how)

Name the stack. Next.js 15, Postgres on Supabase, Vercel hosting, Stripe for payments, Resend for email. If you are open to alternatives, that is fine, but say so explicitly: "We are on Postgres but a senior who pushes for Redis on the queue layer will get heard."

Hiding the stack to "not bias the search" is a mistake. Engineers self-select on stack. A Rails engineer who hates Next.js will waste both your weeks if you only reveal the stack in the third interview.

4. Team shape (the who)

One paragraph. Who do they report to? Who do they pair with? Who do they unblock?

If the answer is "you, alone, reporting to a non-technical founder," say that. It is not a bug; some engineers prefer it. But if you bury that and they expected a 4-person team, you will lose them in week two.

For a first-engineer role, the team shape paragraph is often: "You report to me (non-technical founder, 8 years in payments ops). No other engineers. You will pair with our designer (contract, 10 hrs/week) and our customer-support lead (full-time) who owns the bug triage queue."

5. Decision authority (the bar)

This is the section most founders skip and the one senior engineers grade you on hardest.

Spell out what the engineer can ship without asking and what needs a check-in. Examples:

• Can ship without asking: any refactor, any test, any dependency bump, any migration that does not change the public API, any UI change to admin pages.
• Needs a check-in: schema changes on the orders or users table, new third-party services costing >$50/mo, anything that changes the customer-facing checkout flow.

A senior engineer reading this knows immediately whether they will hate the job. A junior engineer reading this learns what "owning scope" actually means in your company. Both are wins.

6. Compensation (the number)

State the number. Weekly, monthly, or annual: pick one, write it.

If you are booking on a marketplace, the number is set by the tier. On Cadence, those are junior at $500/week, mid at $1,000/week, senior at $1,500/week, lead at $2,000/week. If you are hiring full-time, the number is your offer band: "$140k to $180k base plus 0.5% to 1.5% equity."

Founders who write "competitive comp" get exactly the candidates who do not care about comp, which sounds great but in practice means people who are either underqualified or independently wealthy. State the number, you will get a better shortlist.

A good-vs-bad spec elements table

Element	Bad spec	Good spec
Problem	"Build our V2 platform"	"Cut Stripe webhook failure rate from 4% to <0.5%"
Day-1 deliverables	"Improve performance"	"Add Playwright tests for 3 checkout flows; ship by Friday"
Tech stack	"Modern web stack"	"Next.js 15, Postgres on Supabase, Vercel, Stripe"
Team shape	"Join a high-performing team"	"Report to me; pair with 1 designer; no other engineers yet"
Decision authority	"You'll have ownership"	"Ship any refactor; ask before schema changes on orders"
Compensation	"Competitive comp"	"$1,500/week, billed weekly, cancel any week"
AI expectation	(silent)	"We assume daily Cursor + Claude Code use"
Exclusions	(none)	"No leetcode. No 4-hour take-homes. No system-design whiteboarding."

The bad column gets you a 400-résumé pile. The good column gets you 12 engineers who actually want the job.

Two sample specs

Sample 1: First backend engineer (early-stage SaaS)

Problem. Our Stripe billing logic lives in a 600-line app/api/webhook/route.ts file and breaks roughly weekly. We need it rewritten with idempotency, retries, and event-type handlers split into modules.

Day-1 deliverables (week one).

1. Refactor the webhook route into per-event handlers with a single dispatcher.
2. Add idempotency keys backed by Postgres.
3. Backfill Playwright coverage for the 3 highest-value checkout flows.

Tech stack. TypeScript, Next.js 15, Postgres on Supabase, Vercel hosting, Stripe, Resend, Inngest for background jobs. Cursor + Claude Code in the editor.

Team shape. Report to me (founder, technical but stretched). Pair with our part-time designer. Customer-support lead triages bugs and writes them up in Linear.

Decision authority. Ship any refactor, test, or dependency update without asking. Check with me before changing the orders or subscriptions schema, before adding services >$50/mo, and before touching the public checkout flow.

Compensation. Mid tier on Cadence, $1,000/week. Weekly billing, 48-hour free trial, cancel any week.

AI-native expectation. We assume daily Cursor or Claude Code use, prompt-as-spec discipline, and that you can review a Claude-generated PR in under 15 minutes. Every Cadence engineer is vetted on this before they unlock bookings, so this is a baseline.

Exclusions. No leetcode. No take-home longer than the 48-hour paid trial itself. No system-design whiteboarding. We judge from the trial PR.

That spec is 220 words. An engineer who reads it knows by Tuesday whether they want it.

Sample 2: Senior frontend engineer (post-PMF, scaling)

Problem. Our Next.js app has accumulated four state-management libraries (Redux, Zustand, React Query, Jotai) across 18 months of contractor work. New features take 2x longer than they should because nobody knows which one to use.

Day-1 deliverables (week one).

1. Audit the four state libraries; write a one-page recommendation (consolidate to which, deprecate which, on what timeline).
2. Migrate the highest-traffic page (/dashboard) to the chosen approach.
3. Write the team's state-management playbook in our Notion.

Tech stack. TypeScript, Next.js 15 (App Router), TanStack Query, Tailwind, Radix UI, Vercel, Sentry, PostHog. Cursor required.

Team shape. Report to our staff engineer. Pair with 2 mid frontend engineers and 1 designer. You unblock both mids by owning the state-management decision.

Decision authority. Owns the state-management migration end-to-end, including which library survives. Owns frontend hiring bar for mid roles. Check with staff engineer before changing the build pipeline or our Vercel project structure.

Compensation. Senior tier, $1,500/week on Cadence, or $185k-$215k base + 0.25%-0.5% equity if we convert to full-time after the trial.

AI-native expectation. Daily Cursor + Claude Code. We expect you to use Claude to draft the playbook and review PRs from the mids.

Exclusions. No leetcode. No multi-round panel interviews. We judge from the audit doc you produce in week one.

Same shape, harder role, clearly different ask. Both fit on a page.

The Cadence alternative when the loop is overkill

For an unvalidated MVP or a six-week scope, writing the spec is most of the work. You don't need a 60-day hiring loop on top of it. You can paste the spec into Cadence's booking flow and the platform auto-matches engineers from a 12,800-engineer pool, with a 48-hour paid trial so you evaluate the work, not the résumé. Median time to first commit on Cadence is 27 hours.

If the work is open-ended and you need someone for 18 months, do the full hire. Our piece on first-engineer full-time vs contract covers when each makes sense.

Every engineer on Cadence is AI-native by default, vetted on Cursor, Claude Code, and Copilot fluency in a voice interview before they unlock bookings. So your spec does not need to spell out "must know AI tools." That is a baseline, not a filter.

Book your first engineer from your spec in 2 minutes; the trial is free for the first 48 hours, so if the engineer misreads the spec, you lose nothing.

Common founder mistakes when writing the spec

The five most common mistakes we see:

1. Listing 12 deliverables for week one. That is a quarter, not a week. Cut to 3 to 5.
2. Hiding the stack. Engineers self-select on stack. Say it on line one.
3. "Competitive comp." State the number. You filter on the wrong axis if you hide it.
4. No decision authority section. Senior engineers will pass on the role.
5. Padding with culture talk. Your culture shows in how the work goes, not in a paragraph.

If you avoid these five, your spec will already be better than 80% of what engineers see in their inbox. Two related reads if you are early: common founder mistakes when hiring developers and how to talk to engineers as a non-technical founder.

What to do next

Write a draft of your spec today, in one sitting, before you talk to a recruiter or post to a job board. Use the 8-section structure above. Print it. Read it as if you were the engineer. Ask: "Would I know what I am doing Monday morning?"

If yes, send it out. If no, the spec is not done and you should not be hiring yet. Going to market with a half-spec wastes your weeks and the engineers' weeks.

If you have the spec but not the time to run a 60-day loop, paste it into Cadence's booking flow. You'll get 4 matched engineers in 2 minutes, with a 48-hour free trial to evaluate from a real PR instead of a résumé.

FAQ

How long should an engineering job spec be?

One page or roughly 300 to 500 words. If it runs longer, you are describing the candidate, not the work. Cut until every sentence is either a deliverable, a constraint, or a decision-authority line.

Should I include salary in the job spec?

Yes. State a weekly rate or an annual band. Hiding comp filters out the strongest candidates first, because they have been burned by "competitive" before. State the number and you save three rounds of dancing around it.

What's the difference between a job spec and a PRD?

A PRD describes the product you are building. A job spec describes the person you need and the work they will do in week one. They overlap, but the spec is shorter and centred on the role. The PRD piece covers the product side.

Do I need an engineering spec if I'm booking on a marketplace instead of hiring full-time?

Yes, even more so. A marketplace shortlists faster than a recruiter, so the spec is what filters the match quality. A vague spec on Cadence still gets you 4 engineers, but they will be 4 generalists instead of the right specialist.

What should I leave out of an engineering job spec?

Leave out résumé filters ("5+ years required"), buzzword stacks ("microservices, event-driven, web3-ready"), and culture paragraphs. Replace each with a deliverable. The spec gets shorter and the shortlist gets better.