The idea
Vibe coding means describing what you want in plain English and letting AI write the actual code. You don't need to know how to code. You just need to know what you want the app to do.
How it works
You type something like "add a button that clears the form" into Claude Code or Gemini Code. The AI reads your files, figures out what to change, and does it. You review the result and deploy.
Why it's powerful
You focus on the idea and the outcome — what should the app do, how should it look, what problem does it solve. The AI handles the technical details.
Your job
Be a good director, not a coder. Give clear instructions. Review what the AI builds. Test it. Give feedback. The better you describe what you want, the better the result.
The limits
AI makes mistakes. It sometimes misunderstands what you want or breaks something while fixing something else. Always test after every change before moving on.
The playbook
The PLAYBOOK.md file in your dev-playbook repo is your secret weapon. Paste it at the start of every build prompt so the AI follows your standards automatically from day one.
Claude Code
AI that writes code. You describe what you want in plain English, it writes the files. Same as Gemini Code — use either.
GitHub
Where your code lives. Like Google Drive but for code. Every app has its own folder (called a "repo") here.
Cloudflare
What puts your app on the internet. When you save code to GitHub, Cloudflare automatically makes it live on your website.
Terminal
Text-based control panel. You type commands here to save and upload your code. Looks scary, isn't.
- Make a change — Ask Claude Code or Gemini Code to add a feature or fix a bug. It edits the files directly.
- Push to GitHub — Run 3 terminal commands (see the Git card). This saves your changes to GitHub.
- Cloudflare deploys it — Cloudflare sees the new code automatically and puts it live on your site within 60 seconds. You do nothing.
AI writes code
→
git push
→
Live on site
git add -A
Stage everything. Tells git "I want to save all the changes I just made." The -A means "all files."
git commit -m "..."
Describe the change. Like adding a label to a box. Write something short like "Add Japan flag" inside the quotes.
git push origin main
Upload to GitHub. Sends your saved changes up to the internet. This triggers Cloudflare to deploy.
Tip: Always run all 3 in order. Skipping one means your changes don't go live.
index.html
The app itself. Everything the user sees and all the logic. One file does it all for simple apps.
sw.js
Offline support. Lets the app work without internet and makes it installable on phones like a real app.
manifest.json
App identity. Tells browsers the app's name, icon, and colors for when someone installs it.
CLAUDE.md
Instructions for the AI. Tells Claude Code or Gemini Code what the app does and how to work on it. Always keep this updated.
GEMINI.md
Same as CLAUDE.md. Identical copy for Gemini Code. Both files always have the same content.
1.0.0
Three numbers separated by dots: Major . Minor . Patch
Major
Big overhaul — you rebuilt a large chunk of the app. Bump the first number. Counts as ~40 hours of work.
Minor
New feature added — something the app couldn't do before. Bump the middle number. Counts as ~10 hours.
Patch
Bug fixed or small tweak — nothing new, just something broken got fixed. Bump the last number. Counts as ~1 hour.
Important: Every version bump must also update the cache version in sw.js or users won't see your changes.
What it is
A small line at the bottom of every app showing how much estimated energy and water was used to build it.
How to calculate
Run sustainability.py with your version counts. It spits out the kWh and liters to paste into the footer.
Example
"Used to make this app: 27.60 kWh | Total Water: 69.00 Liters" — this came from 1 major + 4 minor + 12 patch versions.
API
A window into someone else's data. Your app asks a question (e.g. "what's the USD to JPY rate?") and the API answers with fresh data.
No-key APIs
Best option. No signup needed, works forever. BingBongs uses ExchangeRate-API (live rates) and Frankfurter (historical). Free, no limits.
Keyed APIs
Requires signup. You get a secret code (API key) that proves who you are. Store it in a CONFIG block — never paste it publicly.
CSP rule
Every API domain must be listed in your security settings. Missing it causes a silent NetworkError that looks like the API is broken.
NetworkError
Usually a CSP block, not a real network problem. Check that the API's domain is listed in your connect-src security policy.
404 error
The URL you're calling doesn't exist. The API endpoint format is probably wrong — check the docs for the exact URL pattern.
Stale cache
Your change deployed but users still see the old version. Always bump the cache version string in sw.js with every release.
undefined
You're trying to read a value that doesn't exist in the API response. Console.log the raw response first to see the actual structure.
Before you build
Create the GitHub repo first. Set up the Cloudflare Pages connection. Decide on a subdomain (e.g. appname.jaihimself.com).
API planning
List all external APIs upfront. Add every domain to your CSP connect-src before writing any fetch calls. Prevents headaches later.
Security basics
Always wrap user input through escapeHtml() before putting it on screen. Cap number inputs at 999,999,999 to prevent crashes.
Must-have files
index.html, sw.js, manifest.json, CLAUDE.md, GEMINI.md, sustainability.py — every single app, every time, no exceptions.
AI prompt tip
Start every build prompt with the PLAYBOOK.md contents so the AI follows your standards from line one. Paste it at the top.
After first deploy
Hard reload (Ctrl+Shift+R) to bypass the service worker cache. Test on mobile too — things break differently on small screens.