Setting Up Your AI Workspace

Vibe coding is a partnership. You bring the intent and judgment; the AI brings speed and tireless typing. But like any partnership, it works best with a shared environment, clear ground rules, and a safe place to make mistakes. This chapter is about building that environment before you write a single feature.

A good workspace does three things: it gives the AI the context it needs to make smart changes, it lets you see the results of those changes fast, and it makes every change easy to undo. Get these right and the AI feels like a senior collaborator. Get them wrong and it feels like a slot machine.

Choose an AI-Native Editor or Assistant

Your first decision is where the AI lives. There are roughly three categories today, and you don't have to commit forever.

• AI-native editors (Cursor, Windsurf): a familiar code editor with the AI deeply wired in. Best if you want to see and touch the code while the AI works alongside you.
• Terminal/CLI agents (Claude Code, Codex CLI, Gemini CLI, Aider): the AI runs as a command-line agent that reads files, edits them, and runs commands. Best for letting the AI work more autonomously across many files.
• IDE plugins (GitHub Copilot, Continue, JetBrains AI): bolt-on assistance inside an editor you already love.

For shipping real software, pick one that can read your whole project, edit multiple files, and run commands (tests, builds, linters) on its own. The ability to run and check its own work is what separates a helpful assistant from an autocomplete toy. Don't agonize over the choice; the skills in this book transfer between tools.

Structure Your Project So the AI Can Navigate It

AI models reason about your code by reading it. A messy, sprawling, inconsistent project is as hard for them as it is for you. You don't need a perfect architecture, but a few habits pay off immediately:

• Keep a predictable layout. Source in one place, tests beside or mirroring the source, config at the root.
• Use clear, descriptive names. calculateMonthlyInvoiceTotal beats calc2. The AI uses names as clues.
• Favor smaller files. A 200-line file is easier to change correctly than a 2,000-line one, for both of you.
• Co-locate related things. When a feature's code, styles, and tests sit together, the AI gathers context in one read.

A typical, AI-friendly layout might look like this:

my-app/
├── AGENTS.md            # project rules & context for the AI
├── README.md            # what the project is, how to run it
├── .env.example         # documents needed secrets (no real values)
├── .gitignore           # excludes .env, build output, node_modules
├── package.json         # scripts: dev, test, lint, build
├── src/
│   ├── features/
│   │   └── invoices/    # code + tests for one feature, together
│   ├── lib/             # shared helpers
│   └── index.ts         # entry point
└── tests/               # cross-cutting / integration tests

Write a Context File (AGENTS.md)

The single highest-leverage thing you can do is write a context file the AI reads automatically. Different tools look for different names — AGENTS.md, CLAUDE.md, .cursorrules, or a .github/copilot-instructions.md — but the idea is identical: a living document that tells the AI how your project works and how you want it to behave.

Without it, the AI guesses. With it, the AI stops reformatting your code, stops inventing libraries you don't use, and stops re-explaining decisions you already made.

A practical starter file:

# Project: Invoice Manager

## What this is
A small web app for freelancers to create and track invoices.

## Tech stack
- TypeScript + React (Vite)
- Tailwind for styling
- SQLite via Prisma
- Vitest for tests

## Commands
- Install: `npm install`
- Run dev server: `npm run dev`
- Run tests: `npm test`
- Lint: `npm run lint`

## Conventions
- Use functional components and hooks; no class components.
- Keep components small; one component per file.
- Write a test for every new function in `src/lib`.
- Never edit files in `src/generated/` — they are auto-generated.

## Don'ts
- Don't add new dependencies without flagging it first.
- Don't commit secrets; use environment variables.

Keep it short and keep it current. When the AI repeatedly makes the same wrong assumption, that's your signal to add a line. Treat the context file as a record of every lesson you'd otherwise have to repeat.

Make Version Control a Reflex

Version control is your safety net, and with AI it becomes essential. The AI can change ten files in five seconds — you need a clean way to inspect, keep, or throw away that work.

• Commit often, in small chunks. Before you ask for a big change, commit what works. A clean working tree means you can always get back to it.
• Read the diff before committing. This is your real review step. You don't have to understand every line, but you should understand what changed and why.
• Use branches for risky work. Spin up a branch, let the AI go wild, and merge only if you like the result. If not, delete it — no harm done.
• Write honest commit messages. Future-you and the AI both read history to understand intent.

The mental shift: commits aren't bureaucracy, they're checkpoints in a game. Save before the boss fight.

Keep the Feedback Loop Tight

The faster you can see whether a change works, the faster you and the AI converge on something correct. A slow loop — where you wait minutes to know if something broke — quietly multiplies every mistake.

• Make "run it" a single command. npm run dev, make test, whatever it is, document it in your context file so the AI can run it too.
• Lean on fast tests. Even a handful of unit tests give the AI a way to verify its own work without you babysitting.
• Use a linter and formatter. They catch a whole class of errors instantly and keep style arguments out of your reviews.
• Show errors back to the AI. When something breaks, paste the actual error message. Specific feedback produces specific fixes; "it doesn't work" produces guesses.

When the AI can edit, run, see the failure, and fix it on its own, you've built a loop that does real work while you stay in the director's chair.

Manage Secrets Carefully

AI tools read your files, and sometimes share context with a remote service. That makes leaked secrets a real risk. Build good habits from day one:

• Never put real keys in code. Use environment variables and a .env file.
• Always gitignore your .env. Commit a .env.example with empty placeholders so the AI knows what's needed without seeing the values.
• Scope keys narrowly and rotate anything that may have been exposed.
• Tell the AI in your context file to never hardcode or commit secrets.

A loud rule like Never read or print the contents of .env in your AGENTS.md is cheap insurance.

A Sane Local Setup Makes AI Changes Safe

Tie it together with an environment where mistakes are cheap and recoverable:

• Work on a branch, not directly on main.
• Keep the working tree clean before big changes so the diff is meaningful.
• Have tests and a dev server ready to run in one command.
• Keep secrets out of the repo and the context file up to date.

With this foundation, the worst case for any AI change is git checkout . and a fresh start. That safety is what lets you move fast and direct boldly — knowing nothing the AI does is truly irreversible. In the next chapter, we'll start using this workspace to actually build.

Live Diagnostics (LSP)

The tightest feedback loop doesn't wait for you to run the code — it catches mistakes the moment they're typed. That's what the Language Server Protocol (LSP) provides: the live "smarts" behind your editor, including real-time errors, type information, go-to-definition, and autocomplete. A language server reads your code as it changes and reports problems before anything runs.

The leverage for vibe coding is to feed those diagnostics back to the AI. Without it, the loop is slow: the AI writes code, you run it, it crashes on a typo or a type error, and you paste the message back by hand. With diagnostics wired in, the agent sees the same red squiggle you do the instant it writes the line — and fixes the type or lint error as it goes, before the code ever runs.

You can give the agent this sight in a few ways:

• Run the language server for your stack (tsserver, rust-analyzer, pyright, and so on) — most AI-native editors do this for you.
• Have the agent run a typecheck or lint command and read the output, or expose diagnostics through an MCP server.
• Treat a clean diagnostics report as part of "done," not an afterthought.

A run-crash-paste cycle becomes a quiet, self-correcting one. The AI grinds less and converges faster.

Extending Your Agent

Out of the box, an AI assistant is generic. The same base model becomes a far better collaborator once you wrap tooling around it — turning a plain chatbot into a harness tuned to your project. The main extension points to know:

• Skills — reusable packaged capabilities (instructions plus scripts) the agent loads on demand, so your domain know-how is available without re-explaining it every session.
• Plugins — bundles that ship skills, commands, hooks, and connectors together as one installable unit.
• MCP (Model Context Protocol) — an open standard for connecting the agent to external tools and data (databases, APIs, your file system) through one common interface.
• Subagents — specialized helper agents the main agent spawns for focused work (search, review, a long side-quest), each with its own context window.
• Hooks — scripts that fire automatically at lifecycle events (before a command runs, after a file is edited), so you can enforce rules or inject context deterministically.
• Slash commands — short named workflows you invoke with /name, collapsing a repeated multi-step request into one keystroke.

You don't need all of these on day one. Start plain, and add a skill or a slash command the moment you notice yourself repeating the same setup. Hooks, in particular, return in the guardrails chapter as a way to enforce your rules instead of just hoping the AI remembers them.

macOS vs Windows

Most AI tooling — CLI agents, scripts, tutorials — quietly assumes a Unix shell. That shapes the practical choice of dev environment.

• macOS is Unix-native. It ships with a real POSIX shell and the same git, ssh, and curl the rest of the dev world uses. Most agents and scripts "just work."
• Windows is fully capable, but the smoothest path is WSL2 (Windows Subsystem for Linux): a real Linux environment inside Windows. Do your AI coding inside WSL2 rather than fighting native PowerShell quirks.

A few gotchas to keep your work portable across both:

• Paths — /home/you/project versus C:\Users\you\project; backslashes and drive letters break scripts. WSL2 sidesteps most of this.
• Line endings — Windows uses CRLF, Unix uses LF. Mismatches cause noisy diffs and broken shell scripts; set core.autocrlf and a .gitattributes to normalize to LF.
• Case-sensitivity — macOS and Windows often treat File.ts and file.ts as the same; Linux and CI do not, so code that builds locally can fail in the cloud. Be consistent with casing in imports and filenames.
• Permissions — Unix file modes (chmod +x) don't map cleanly onto Windows.

Whichever you're on, ask the AI to keep commands portable — forward slashes, LF endings, consistent casing — so its scripts run the same on your laptop and in CI.

TUI vs GUI

AI coding tools come in two shapes, and a productive vibe coder reaches for both. Terminal / TUI agents (Claude Code, Codex CLI, Aider) run in the terminal: fast, scriptable, and composable, great for automation and letting the AI work autonomously across many files. GUI / editor tools (Cursor, Windsurf, IDE extensions) live in a visual editor: discoverable, with inline diffs, click-to-accept, and a gentle on-ramp — easier for reviewing changes.

You don't have to pick one forever. The combination is the point: drive the bulk of the work through a fast TUI agent, then drop into a GUI for visual review or fine-grained edits. Choose a comfortable primary, and remember the skills in this book transfer between them.