vibe-coding

# Vibe coding methodology

Practical strategies for building software effectively with AI coding assistants.

> **Tool landscape moves fast.** This skill was last swept 2026-05-08. The methodology (planning, version control, testing, bug-fixing) is stable; the specific tool names, instruction-file conventions, and pricing details drift quarterly. Treat the named tools as representative, not exhaustive.

## Planning process

Start by working with the AI to write a detailed implementation plan in a markdown file.

**Scope management**: Review and refine the plan—delete unnecessary items, mark complex features as "won't do," and keep a separate section for ideas to implement later. This prevents scope creep and maintains focus.

**Incremental implementation**: Work section by section rather than building everything at once. Have the AI mark sections complete after successful implementation, and commit each working section to git before moving to the next.

**Track progress visibly**: Use todo lists, markdown checklists, or inline status markers so both you and the AI can see what's done and what remains. This prevents re-implementing completed work and keeps sessions focused.

## Version control strategies

Git is your safety net — don't rely solely on the AI tool's revert functionality.

**Branch per attempt**: Begin each new feature on a fresh feature branch (`git switch -c feature/xyz`) and commit small chunks as the AI makes progress. The branch boundary is your "if this goes off the rails, throw it away" boundary — you discard the branch, not your working tree.

**When the AI goes down a bad path**: Prefer reversible commands. `git restore .` discards uncommitted changes; `git stash` parks them; `git switch -` jumps back to your previous branch. Reach for `git reset --hard HEAD` only when you've confirmed there's nothing in the working tree worth keeping — destructive commands skip the reflog niceties and can swallow uncommitted experiments. (If the agent has been creating new files, a separate `git clean -fd` is also part of "really, throw it all away" — same caveats.)

**Clean re-implementation**: When you finally find a working solution after several attempts, branch from main, implement it fresh, and discard the throwaway branch. Multiple failed AI attempts leave layers of dead code that compound future confusion — a clean re-implementation of a known-good solution is faster and more maintainable than untangling the spaghetti.

## Testing framework

Prioritize end-to-end integration tests over unit tests. Focus on simulating user behavior—testing features by simulating someone clicking through the site or app.

**Regression prevention**: LLMs often make unnecessary changes to unrelated logic. Tests catch these regressions before they compound.

**Tests as guardrails**: Consider starting with test cases to provide clear boundaries for what the AI should and shouldn't change. Ensure tests pass before moving to the next feature.

## Effective bug fixing

**Error messages**: Simply copy-pasting error messages is often enough context for the AI to identify and fix issues.

**Analyze before coding**: Ask the AI to consider multiple possible causes before jumping to implementation. This prevents chasing the wrong problem.

**Reset after failures**: Start with a clean slate after each unsuccessful fix attempt rather than layering fixes on top of broken code.

**Strategic logging**: Add logging statements to better understand what's happening when bugs are opaque.

**Switch models**: Try different AI models when one gets stuck on a problem.

## AI tool landscape (as of 2026-05)

The current tools cluster into four shapes. Pick by where you work, not by hype.

| Shape | Examples | When |
|---|---|---|
| CLI agents | Claude Code, Aider, Codex CLI, Gemini CLI, GitHub Copilot CLI, opencode, Goose | Repo-wide changes, multi-file refactors, automation, headless / cron use |
| Standalone IDEs | Cursor, Windsurf, Zed, Kiro | Day-to-day editing with chat + autocomplete tightly integrated |
| IDE extensions | GitHub Copilot, Continue, Cline, Roo Code, Amazon Q | Stay in your existing editor (VS Code, JetBrains, Neovim) |
| Cloud agents | Devin, OpenHands, Jules, GitHub Copilot Coding Agent | Async / background work via PR, no local terminal needed |

A common stack many developers converge on: **Cursor or Copilot for daily editing + Claude Code (or Codex CLI) for repo-wide / agentic tasks**. They're complementary — fast inline edits in the IDE, longer agentic loops at the terminal.

## AI tool optimization

**Instruction files**: Write project-specific context for your AI assistants. Conventions have splintered, but several tools converge on `AGENTS.md` as a shared format. Current naming as of 2026-05:

| Tool | File(s) | Notes |
|---|---|---|
| Claude Code | `CLAUDE.md` (per-directory, nested) | Loaded automatically; see [docs.anthropic.com/en/docs/claude-code/memory](https://docs.anthropic.com/en/docs/claude-code/memory) |
| Cursor | `.cursor/rules/*.mdc` (modern) — Markdown + YAML frontmatter (`description`, `globs`, `alwaysApply`) | Legacy `.cursorrules` single-file still works but Cursor recommends migrating |
| Windsurf | `.windsurfrules` or `.windsurf/rules/*.md` | Same dual pattern as Cursor |
| GitHub Copilot | `.github/copilot-instructions.md` | Single repo-level file, ~4k char practical cap |
| Cline | `.clinerules` | Single file |
| Aider | `.aider.conf.yml` (config) + chat history files | Git-native; reads `CONVENTIONS.md` if you point it there |
| Continue | `.continue/config.json` | JSON config; per-repo |
| Codex CLI / Gemini CLI / Aider / Continue | `AGENTS.md` (vendor-neutral fallback) | Becoming the cross-tool common denominator |

When working across multiple tools, keep the canonical guidance in `AGENTS.md` and reference it from tool-specific files (`CLAUDE.md`: "Also read AGENTS.md."). That avoids drift between siblings.

**Local documentation**: Download API documentation to y