beginner 45 minutes

Good Principles for Vibe Coders

claude-codegit
Guide: Good Principles for Vibe Coders

The most dangerous moment in an AI-coding session isn’t when the model refuses to help. It’s when it says “fixed!” and the thing is subtly broken — and you can’t undo it because there’s no history to go back to.

This guide is for people building real things with Claude Code, Cursor, ChatGPT, or Replit, who haven’t come up through traditional software engineering. You don’t need to learn to code to use it. You need the small number of habits that keep your work safe, your secrets off the internet, and your setup reproducible the next time the AI sits down at the keyboard.

Inside you’ll find 7 principles covering:

  1. Why version control matters more for you than for developers
  2. The minimum viable Git workflow
  3. Secrets — the one rule that matters
  4. .gitignore — what to keep out of history
  5. Folder structure — one project, one folder
  6. Rules files — how to make the AI remember
  7. What NOT to learn yet

🎗️ How to use this guide

You don’t need to read this front-to-back. It’s a reference. The order is roughly “things to set up first” to “things to learn when you hit them.”

The four-step ritual before any new AI-built project:

  1. Make a folder. One project, one folder. Don’t build inside your Desktop.
  2. Put it under version control on day one — before you’ve written anything worth saving. git init takes six seconds.
  3. Add a .gitignore before your first commit. The template further down covers the non-negotiables.
  4. Never paste an API key inline. Put it in an .env file that’s in your .gitignore. The one rule that matters most: the AI can run all of these commands for you. You don’t have to memorise Git syntax. You have to know what to ask for — “commit what we’ve got so far before the next change” is a sentence Claude or Cursor will understand and execute. Your job is to know when to ask, not how to type.

🧭 Git and GitHub — a one-minute primer

Before we get into the habits, two quick definitions, because the rest of this guide uses both words and they’re not the same thing.

Git is a program that lives on your computer. It tracks every change you make to a folder, so you can go backwards in time whenever you need to. The name isn’t an acronym — Linus Torvalds, who built it for the Linux kernel back in 2005, famously named it after British slang for an unpleasant person, mostly as a joke. You don’t need to care about the name. You need to know it’s the engine underneath everything that follows.

GitHub is a website. It stores copies of your Git history in the cloud, adds a social layer on top (issues, pull requests, collaboration), and is where most of the open-source code in the world currently lives. It’s owned by Microsoft, and it’s free for most solo use. Alternatives exist — GitLab, Codeberg, Bitbucket — and for what this guide covers they’re interchangeable.

The short version. Git is the version-control tool. GitHub is one of several places to park copies of your Git history so it’s not only on your laptop. You use Git locally every day. GitHub is optional but worth it for the off-site backup alone.

✨ The Principles

1. 💾 Why version control matters more for you than for developers

The insight.

Traditional developers use version control because teams of them need to coordinate. You — building alone with an AI — need it for a different reason: the AI can break working code in one confident-sounding “fix.” Without version history, you have no way to go back to the version that worked.

Simon Willison has a phrase for the cost of AI-assisted building: cognitive debt. The code runs. You don’t fully understand why. When it stops running, you can’t diagnose it from memory — you need the old version back to compare against.

Version control is how you get the old version back. It’s also how you answer the question “what did I change between the working one and this broken one?” without retracing the last two hours of conversation with the AI.

A note on GitHub specifically. You can use Git without GitHub. You probably shouldn’t, because losing your laptop should not mean losing your work. The distinction still matters though: “I don’t want to put this on GitHub” is a fine preference. “I don’t want to use version control” is a different thing entirely.

Actionable.

  • If you’re building anything you’d be upset about losing, put it under version control today.
  • Use Git locally at minimum; use GitHub (or GitLab, Codeberg, etc.) if you want a backup that survives a broken laptop.
  • Ask your AI: “Put this folder under version control and push it to a private GitHub repo called [name].” It can run every command it needs to. A personal aside. I’ve been relying on backups my whole working life — pulled from them when I’ve needed to, lost nothing important because of them. I know they save real work when something breaks. When you get the chance to bake that safety net into the thing you’re building from day one, there’s no good reason not to.

2. ✅ The minimum viable Git workflow

The insight.

Most Git tutorials teach you twenty commands on day one, and you only need four. The others exist for problems you don’t have yet (and probably won’t for a while).

The four moves that cover 90% of solo use:

  • git init — turn a folder into a Git project. Done once, on day one.
  • git add . — stage everything you’ve changed.
  • git commit -m "what changed" — save a snapshot with a message describing what’s different.
  • git push — send your snapshots to GitHub (if you’re using it). That’s the whole workflow. Every time you’ve done a chunk of work and it’s in a good state, run git add . then git commit -m "...". If you’re using GitHub, git push once in a while to back it up.

The three times you’ll be glad you set this up.

  1. The AI’s “small fix” breaks everything. You ran some changes, they compiled, and now nothing works. You run one command to go back to the last working snapshot. Minutes, not hours.
  2. You want to try a risky idea without committing to it. Make a commit, try the idea, keep it if it works, discard it if it doesn’t. No ambiguity about what the “before” state was.
  3. You need to ask someone for help. Now you can send them a link or a diff showing exactly what changed. They don’t have to guess what you did. Let the AI drive.

Claude Code, Cursor, Codex, Gemini CLI — all of them can run Git commands directly. You don’t need a terminal skill. You need one sentence: “Commit what we’ve got and describe the change.” They will do the rest. Most vibe coders don’t realise this, and type Git commands by hand when they don’t have to.

Actionable.

  • After any meaningful chunk of work (a new feature, a working fix, end of a session): commit.
  • Write the commit message in plain language. “Added dark mode toggle” is better than “changes.”
  • If you’re using GitHub, push once or twice a day. That’s your off-site backup. My own rhythm. When I’m building with Claude Code, I commit at the end of a feature, at the end of a session, or whenever it feels right — whenever the work’s at a natural stopping point I wouldn’t want to lose. If you’re starting out, feature-boundary is the cleaner rule: most vibe-coding sessions are one feature at a time anyway, because that’s how the AI’s context window wants to be fed.

3. 🔐 Secrets — the one rule that matters

The insight.

API keys, access tokens, database passwords, OAuth credentials — these are secrets. They’re what separates you-using-a-service from anyone-in-the-world-using-it-as-you.

The one rule: secrets never go into code, and they never go into Git history.

Both parts matter. A secret that’s only in your code file but gets committed to GitHub is still leaked. A secret that’s only in your prompt to Claude is fine — until Claude writes a file containing it and you commit the file.

Why it matters more than you’d think.

  • Git history is forever. Delete a secret from a file, commit the deletion, push — the secret is still in the history. Anyone with access to the repo can dig it out. “Rewriting history” to remove it is possible but painful, and by the time you’ve done it, assume the secret is burned.
  • Public repos are scraped in real-time. There are bots watching new commits to public GitHub repos looking for API keys. Published keys get abused within minutes.
  • Even private repos leak. Someone gets added to the repo, screen-shares, makes a backup. The surface is bigger than you think. The fix: environment variables.

A file called .env at the root of your project, containing lines like:

OPENAI_API_KEY=sk-abc123...
BASECAMP_TOKEN=xyz789...
DATABASE_URL=postgres://...

Your code reads from .env at runtime. .env is listed in your .gitignore (see next principle), so it never gets committed. Every machine you work on gets its own .env file, filled in locally, never shared.

Actionable.

  • Never paste an API key directly into code, into a prompt that gets saved into a file, or into a commit message. If you already have: rotate the key immediately at the provider’s dashboard, then put the new one in .env.
  • Ask your AI: “Move every secret in this project into a .env file and update the code to read from it. Add .env to .gitignore.” It’ll do the refactor.

4. 🚫 .gitignore — what to keep out of history

The insight.

A .gitignore file tells Git “don’t track these.” Everything listed in it is invisible to commits. You want three categories of thing in there: secrets, machine-generated junk, and noise.

The minimum-viable .gitignore.

Copy this into a file called .gitignore at the root of any new project:

# Secrets — always
.env
.env.local
.env.*.local
*.pem
*.key

# Dependencies (language-dependent — keep the ones you use)
node_modules/
venv/
__pycache__/
.pnp.*

# Build output
dist/
build/
out/
*.egg-info/

# Editor + OS noise
.DS_Store
Thumbs.db
.vscode/
.idea/

# Logs
*.log
npm-debug.log*
yarn-debug.log*

What NOT to ignore.

  • README.md — your future-self notes on what this project is
  • CLAUDE.md / .cursor/rules — your rules files (covered in principle 6)
  • package.json / pyproject.toml — the list of what your project depends on These should all be committed. They’re how anyone (including you in six months) understands what the project is.

Actionable.

  • Create .gitignore before your first commit. If you wait, it’s easy to accidentally commit node_modules/ or an .env file by mistake.
  • If you ever need to check whether a specific file is ignored: git check-ignore -v filename.
  • Ask your AI: “Add a standard .gitignore for a [Python / Node / whatever] project, plus entries for .env and editor files.”

If you’ve already committed a secret by accident: rotate the secret at the provider first. Removing it from Git history afterwards is a separate (harder) job, and until you’ve rotated, the secret is compromised.

5. 📁 Folder structure — one project, one folder

The insight.

The single biggest organisational improvement you can make is: one project lives in one folder, and nothing important lives on your Desktop.

Sounds obvious. It isn’t, and most vibe-coded projects I’ve seen violate it. People have scripts in ~/Downloads, data files in ~/Desktop, and the “main” code in a random folder they can’t find a week later.

The pattern that scales.

Pick a top-level folder for all your code projects — ~/Dev/ works. Inside it, one folder per project:

~/Dev/
├── my-research-assistant/
├── client-dashboard-prototype/
├── newsletter-automation/
└── weekend-experiment/

Inside each project folder, a structure like this (adapt for what you’re building):

my-research-assistant/
├── README.md           # what this is, how to run it
├── .env                # secrets (in .gitignore)
├── .gitignore          # what NOT to track
├── CLAUDE.md           # rules for the AI (see principle 6)
├── src/                # the code
├── data/               # input data files
├── output/             # generated output (in .gitignore)
└── scripts/            # one-off utilities

Not every project needs every folder. The point is: things that belong together are together, and the folder name tells future-you what’s inside without opening it.

The README question.

Every project folder has a README.md at the root. It answers three questions:

  1. What does this project do?
  2. How do I run it?
  3. What do I need to know before changing anything? Even a three-sentence README is worth more than no README. You are writing it for yourself six months from now.

Actionable.

  • Stop saving project files to your Desktop. Today.
  • Make ~/Dev/ if you haven’t already. Move existing projects into it one at a time.
  • Ask your AI: “Make a README for this project covering what it does, how to run it, and any gotchas.” It’s surprisingly good at this because it already knows the code. Pick a convention and stick to it. The specific shape of your folder layout matters less than consistency. If you work alone, settle on a pattern that works for you and stop rearranging it. If you work with anyone else, agree on the standard with them — and make it easy for someone picking up the work later to find what they need. The folder layout is a small contract with your future self and whoever comes next.

6. 📜 Rules files — how to make the AI remember

The insight.

The same information shouldn’t need to be re-explained to your AI every time you open a session. A rules file at the root of your project tells the AI — every time — how to behave in this project. Conventions, dependencies, what to prefer, what to avoid.

Different tools use different filenames for the same idea:

  • Claude Code: CLAUDE.md
  • Cursor: .cursor/rules/*.mdc (or the older .cursorrules)
  • Codex / GitHub Copilot: AGENTS.md
  • Gemini CLI: GEMINI.md They all do the same thing: the AI reads this file automatically when it starts working in the folder, and treats what’s in it as context.

What to put in one.

  • What this project is. One paragraph. “This is a personal research assistant that reads RSS feeds and summarises them into a daily email.”
  • What language / framework / stack. “Node 20, TypeScript, Cloudflare Workers.”
  • Conventions you want respected. “Never push to main — always use a branch. Use Conventional Commits. Always ask before running destructive commands.”
  • Secrets rules. “Never paste API keys inline. Use .env. Before running commands with credentials, assume them already in the shell environment.”
  • Testing rules, if any. “Run npm test before suggesting a commit.” The file grows as you learn what the AI needs told once instead of every session.

Actionable.

  • If your project has more than two sessions of history, it needs a rules file. Start simple — five bullets is fine.

  • Ask your AI to help you write the first draft: “Read the code in this folder and draft a CLAUDE.md that covers what this project is, the conventions you’ve been using, and anything worth remembering across sessions.”

  • Commit it. Rules files are for the project, not just your machine. Two rules that have earned their keep in mine.

  • Farm out the donkey work to a local model. Bulk summarising, classifying, or extracting text doesn’t need your subscription LLM — a local model running on your own machine (Ollama with a small Llama or Gemma model) can do it for free. A single line in your rules file — “for mechanical summarisation and classification tasks, route to the local model” — stops you burning API budget on grunt work. If you haven’t set up a local model yet, file this one for later; it’s an upgrade path, not a prerequisite.

  • Don’t claim work is done until you’ve actually checked. A rule like “before telling me a fix worked, run the thing and show me the output” catches the single most common AI-assisted failure mode: the confident “fixed!” that hasn’t been verified. One line. Saves hours.

7. 🚪 What NOT to learn yet

The insight.

Traditional Git tutorials front-load the hardest parts — branches, merges, rebases, pull requests, CI/CD. You don’t need any of it yet. Most of it is there for teams; you’re not a team.

Defer these until you hit them.

  • Branches. You can do everything in one branch (main). When you genuinely need to try two things at once without them interfering, learn branches. Not before.
  • Merge conflicts. Only happen when two people edit the same line. If you’re solo, you won’t hit them.
  • Rebasing. Industrial-grade history cleanup. Wait until someone’s explained why they care about linear history before worrying about this.
  • CI/CD. Automated testing and deployment. Worth it for real products with real users. Not worth it for your weekend experiment.
  • Git hooks. Scripts that run automatically on commit. Useful for teams enforcing rules. Not your problem yet. What about GUI tools?

GitHub Desktop, Tower, GitKraken — they’re all fine. If the terminal feels scary and a GUI would get you using version control at all, use the GUI. Version control you actually use beats the “right” version control you don’t.

What about “AI version control” tools?

You’ll see tools like YOYO advertised as “version control for vibe coders” — local undo buttons that don’t require Git. They exist, and they’re fine as a safety net. They’re not a substitute for Git and GitHub, because they don’t give you the other things on this list (backup, collaboration, history you can share, .gitignore discipline, rules files at the project root). Treat them as an emergency brake, not a chassis.

Actionable.

  • If something on the “defer” list comes up naturally (someone invites you to collaborate, you genuinely need two parallel experiments), that’s when you learn it. Not before.
  • Don’t feel bad about using a GUI. The goal is the habit, not the purity.

📚 Further reading

The pieces that informed this guide, ordered roughly easiest → most opinionated:

  • Tim Van Antwerp — GitHub for Non-Programmers (CC-licensed, no command line required). github.com/tvanantwerp/github-for-non-programmers
  • Anita Cheng — Git for non-developers (and total newbies) (designer-perspective, honest about how much you don’t need to know). anitacheng.com
  • Jason Liu — Version Control for the Vibe Coder (Part 1) (closest prior art to this guide — more terminal-comfortable than this one, but worth reading after). jxnl.co
  • Simon Willison — Vibe engineering (the framing for what “good practice” means when the AI is doing most of the typing). simonw.substack.com
  • Tower — Version Control in the Age of AI (atomic commits, AI-aware commit messages — more technical, mildly commercial). git-tower.com