A practical guide to building software with AI coding agents — specifically OpenCode and Claude Code.
No theory. No fluff. Just workflows, templates, and checklists you can use today.
This guide started as an experiment. The author had real, practical questions about vibe coding — the kind a solo developer faces before starting their first AI-assisted project.
Those questions became FAQ.md. They were then submitted, unchanged, to the top 10 AI LLMs: ChatGPT, Claude, DeepSeek, Gemini, Grok, Kimi, Mistral, Perplexity, Qwen, and another Mistral model (to ensure diversity). Every raw answer is preserved in ai_answers/.
The answers were then read side by side, consensus patterns extracted, and contradictions resolved. This playbook is that synthesis — not one person's opinion, not one model's advice, but the distilled agreement across 10 different AI systems.
When a section says "all 10 AI models surveyed agree", that is literally what happened.
- 2026-03-30 — new section added: "Roadmap"
- 2026-03-30 — new section added: "Managing Sessions"
- 2026-03-26 — new sections added: "Prompt Engineering", "Debugging with Agents", "Project Types", "Cost and Models"
- 2026-03-26 — initial guide published: sections 01–06 + starter template
# 1. Create a GitHub repo
gh repo create my-first-project --private
git clone https://github.com/yourname/my-first-project.git
cd my-first-project
# 2. Create context files (section 2)
# Create AGENTS.md, docs/PROJECT.md, docs/TASKS.md, .gitignore
# Or copy from starter-template/
# 3. Start a branch
git checkout -b feature/hello-world
# 4. Run the agent
opencode # or: claude
# 5. Tell it what to build
# "Create a simple Python script that prints 'Hello, world!'"
# 6. Review the output, then commit
git add . && git commit -m "feat: hello world script"That's it. Read section 0 first, then proceed through the guide in order.
The mental model — what the AI can and can't do, the human-agent loop, common misconceptions.
How to set up your repo, what to commit vs ignore, and why feature branches matter even when working solo.
The files to create before your first session — AGENTS.md, PROJECT.md, TASKS.md — what goes in them and how long they should be.
Slash commands, agents, MCP servers, CHANGELOG.md, security hygiene, and the habits that separate effective vibe coders from frustrated ones.
The per-session loop: plan first, work in small steps, commit frequently, clear context between tasks. Includes a quick-reference checklist.
Side-by-side feature comparison, tool-specific tips, and how to run both on the same project.
Curated official docs, high-quality guides, and how to stay current as the tooling evolves quickly.
How to write effective prompts — the anatomy of good requests, plan-then-execute patterns, templates for common tasks.
What to do when things break — the explain-before-fix pattern, common failure modes, when to restart vs course-correct.
How to start different projects — web app, API, CLI tool, script, library. Starter checklists for each type.
Managing API costs, choosing the right model for the task, local vs cloud trade-offs, cost-saving strategies.
Resume, fork, and revert sessions — when to continue, when to branch, and how to recover from a bad run.
12. Roadmap 🗺️
A forward-looking guide highlighting planned expansions to cover advanced concepts, practical tutorials, team workflows, and responsible AI usage for vibe coding beginners.
The starter-template/ directory is a generic project scaffold you can copy into any new vibe-coding project.
starter-template/
├── AGENTS.md ← main AI context file (fill in your project details)
├── CHANGELOG.md ← change log stub (Keep a Changelog format)
├── .gitignore ← sensible defaults for AI tools + common stacks
├── README.md ← human-readable project overview
└── docs/
├── PROJECT.md ← project goals, audience, constraints
└── TASKS.md ← task tracker with emoji states
To use it:
# Copy into your new project
cp -r starter-template/. /path/to/your/new-project/
# Edit the placeholders
# Every [FILL IN] or [brackets] item needs your contentContributions are welcome. This guide should stay current as the tools evolve — sections need updating, new tools emerge, and real-world experience improves the advice.
See CONTRIBUTING.md for full guidelines, ways to help, and the PR workflow.
vibe-coding-playbook/
├── sections/ ← guide chapters (the published content)
├── starter-template/ ← copyable project scaffold
├── ai_answers/ ← raw answers from 10 LLMs (the source material)
├── FAQ.md ← the original questions submitted to each LLM
├── docs/ ← AI instruction files (not guide content)
├── .ai/ ← AI agent behavior rules
├── .opencode/ ← OpenCode config and commands
├── AGENTS.md ← agent playbook for working in this repo
├── CHANGELOG.md ← change history for this playbook
└── README.md ← this file
The docs/ directory contains files for AI agents working on this repo — rules, conventions, tasks. The actual guide lives in sections/.
If you find this Vibe Coding Playbook helpful, please consider giving it a ⭐ on GitHub! Your support motivates continued improvements and new features.