Set up Git and VS Code with a free agent such as Cline, connect a free model key, write a one-page spec and an AGENTS.md file, ask the agent for a plan before any code, then build one feature at a time. After each step run the app, read the diff, run the tests and commit. Add Supabase for data and sign-in, and deploy on Cloudflare Pages.
Tools you need
The 11 steps
Set up the folder and Git
Create a folder and start version control. Git is your undo button when the agent makes a mess.
mkdir bookmarks && cd bookmarks
git init
printf "node_modules\n.env*\ndist\n" > .gitignore
git add . && git commit -m "Start project"Install the agent and connect a free model
Install VS Code, then the Cline extension. In Cline's settings choose a provider: Google Gemini with a free key from AI Studio, or OpenRouter with a free model. Both free routes have daily limits and can use your prompts for training, so never paste secrets. See the free LLM API limits.
Write the spec
Create SPEC.md and keep it to one page:
App: Bookmarks. Who: students saving study links.
Must have: sign in, save a link with title and tags, search, delete.
Not now: sharing, browser extension, folders.
Stack: React with Vite, Supabase for sign-in and data.
Rules that must never break: a user only ever sees their own bookmarks;
no secret keys in browser code.The agent will follow what you write, so vague specs produce vague apps.
Write AGENTS.md
Create AGENTS.md with how to install, run, test and build, and the rules above. Many agents read this file automatically. The AGENTS.md guide has a template. Commit both files.
Ask for a plan, not code
Open the agent in Plan mode and send:
Read SPEC.md and AGENTS.md. Propose a numbered plan of small steps to build this app.
For each step name the files you will create or change and how I can check it works.
Do not write any code yet.Read the plan. Remove anything not in the spec and reorder so the app runs after every step.
Build step one and review the diff
Switch to Act mode and approve only step one: scaffold the Vite and React app. Run npm install and npm run dev yourself. Then look at what changed:
git status
git diffIf you cannot explain a change, ask the agent to explain it before you commit. Commit with a clear message.
Add features one at a time
For each remaining step: ask for one feature, run the app, try to break it, read the diff, commit. Keep prompts small and name the files. If the agent starts rewriting unrelated files, stop it, run git restore . and ask again more narrowly.
Add the database and sign-in
Create a free Supabase project, a bookmarks table with a user_id column, and row-level security so users read only their own rows. The first web app guide has the exact SQL. Put the project URL and publishable key in .env.local, never in the code.
Write tests for the rules that matter
Ask the agent to add Vitest and write tests for adding, searching and deleting bookmarks. Then break a rule on purpose, for example remove the user filter, and confirm a test fails. If no test fails, the tests are not protecting you.
Run an independent review
Start a fresh agent session and ask: Review this repository against SPEC.md. List bugs, missing error handling and any security problems, but do not change code. Fix the real findings one by one. Then run the security checklist.
Deploy and write the README
Push to GitHub and deploy on Cloudflare Pages with npm run build and output dist. The shipping guide covers domains, email and alerts. In the README, list what the agent wrote, what you wrote and what you checked.
Make it yours
- Add tags with a filter and a count per tag.
- Add an import from a CSV of links.
- Rebuild one screen yourself with no agent and compare the time and bugs.
- Run the same plan with a second agent or model and compare the diffs.
Troubleshooting
| Problem | Fix |
|---|---|
| The agent stops with a rate-limit or 429 error | You hit the free daily limit. Wait for the reset, switch to a different free route, or use a smaller model for simple edits. |
| The agent ignores my rules | Put the rules in AGENTS.md and restate the one that matters in the prompt. Start a new session if the conversation has grown very long. |
| It rewrote files I did not mention | Run git restore ., then ask again with the exact file names and tell it not to touch anything else. |
| Tests pass but the app is wrong | The tests are checking the wrong thing. Write the failing case yourself first, then ask the agent to make it pass. |
| It installed a package I do not recognise | Check the package name on npmjs.com before you keep it. AI tools sometimes suggest packages that do not exist or that are lookalikes. |
Frequently asked questions
What is spec-driven development?
Writing down what you want, the rules and a plan before the AI writes code, then having the agent build from that spec in small steps. It cuts guessing and makes each change easy to review.
Which free agent should I use?
Cline in VS Code is a good start because it asks approval before each step. OpenCode and Kilo Code are alternatives; see the free coding agents list.
How do I stop the agent making a mess?
Commit after every working step, keep tasks small and read each diff. Git lets you undo any bad change in seconds.
Do I need to understand the code the agent writes?
Yes. You are the reviewer. If you cannot explain a change, ask the agent to explain it or leave it out.
Learn this with mentors
Programmes for builders and engineers with admissions open: live classes, mentors and project work.
