@bassam.cz
Free guide · BUILD

How to describe an app so AI builds it

The brief behind my keyboard sound app.

i wanted my laptop keyboard to sound like a mechanical one. there's a paid app for that. so i asked ai to build me my own. two days later i had keytone: a mac menu bar app that plays real switch recordings when i type, follows my headphones, and sends nothing anywhere.

honest part first: i'd been using the paid app, so i knew how it works. i didn't open its code or copy it. i told the ai what i wanted, feature by feature, and it built its own from scratch. is building my own version of a paid app fair to the developer? honestly, i'm not sure. so this guide isn't about cloning apps. it's about describing a tool you want for yourself, clearly enough that ai gets it right.

everything below comes from what i actually told it, including the eight rounds of changes after the first build.

what you need

01say what it does, not what it copies

"make me a copy of X" gives the ai nothing to check against. say what you want to happen when you use it.

Copy this
a native mac app. when i type anywhere on my mac, it plays a mechanical keyboard sound. it lives in the menu bar. it keeps running when i close the window.

02describe the feel in your own words

my first build used made-up sounds. they worked but they were weird. what i actually wanted, in my words at the time: "clacky like blue switch, creamy like yellow switch, linear". name the feel, and name a real reference if you have one.

Copy this
sounds: real recordings of mechanical switches, not generated tones. i want a clicky one (like cherry mx blue), a creamy one (like gateron milky yellow) and a smooth linear one. only use recordings with a license that allows it, and keep the license files.

03write the rules that sound obvious

these were all bugs in my build until i wrote them down:

Copy this
- only typing makes sound. clicking a switch or moving a slider is silent
- sound is instant, every press, even the same key fast
- a held key sounds once, like a real keyboard. not again until i let go
- it follows my headphones: unplug them and sound moves to the mac, plug them in and it moves back
- the menu fits its content. equal padding everywhere, also in the icon

the held key one i had to say twice. if you notice yourself repeating a correction, it goes in the brief.

04say what it must never do

Copy this
- never record what i type. the sound engine gets key codes, never letters
- no network code, no accounts, no telemetry, no microphone
- no third-party libraries unless you ask me first

this is the "nothing leaves my laptop" part. you have to ask for it.

05say what's out of version 1

mine left out: login at startup, mouse sounds, anything synced to my calendar or music. a short "not now" list stops the ai building things you didn't ask for.

06ask for proof, not "done"

Copy this
before you tell me it works: build it, open it, and test it. tell me what you checked yourself and what only i can check, like how it sounds and whether my headphones work.

the ai measured its own delay: the first sound after a key press took about 143 milliseconds before the fix and about 19 after. things only i could check, i checked by hand: typing in another app, holding a key, unplugging my headphones and plugging them back in.

the whole brief

Copy this
## what it is
a native mac app. when i type anywhere on my mac, it plays a mechanical keyboard sound. it lives in the menu bar and keeps running when i close the window.

## sounds
real licensed recordings, keep the license files. clicky (cherry mx blue), creamy (gateron milky yellow), smooth linear.

## rules
- only typing makes sound. clicks and sliders are silent
- instant, every press, even the same key fast
- a held key sounds once
- follows my headphones automatically
- menu fits its content, equal padding everywhere

## never
- record what i type
- network, accounts, telemetry, microphone
- third-party libraries without asking

## not in version 1
login at startup, mouse sounds, calendar or music triggers

## done means
built, opened and tested by you. list what you checked and what only i can check.

check it worked

use it for a full day on your own machine, the way you normally would. for me that meant typing in other apps, then unplugging my headphones and plugging them back in.

three ways this breaks

built this way

keytone, my keyboard sound app. ten switch sounds, all from openly licensed recordings, and it lives in my menu bar.