Vibe Coding Guide v1.0: A Complete Manual for AI-Assisted Development

This document is a guide designed to help not only experienced coders but also non-coders develop apps/services using 'Vibe Coding.' Junior developers with little coding experience and planners can also produce stable results by following these steps.

Core Principle: Instead of having the AI write code immediately, it is better to have it create documents (Design.md, ToDo.md) first before starting development.

0. Overall Flow Summary

[1] Request Concept.md creation

↓

[2] Create Design.md (UI/UX reference document)

↓

[3] Determine Tech Stack (Refer to the decision tree below)

↓

[4] Create ToDo.md (Module-level technical specs + development plan)

↓

[5] Create GitHub Repository and initial commit

↓

[6] Pass app description + Design.md + ToDo.md to Claude Code or Grok Build to start development

↓

[7] Repeat: Implement by module → Test → commit/push

1. Concept.md — Prompt to Start with a Simple Idea

Start by briefly describing the app or service you want to make in 2-3 lines as it comes to mind, in the form of: "I want to make something like this; please create a Concept.md document detailing the procedures and methods to implement it."

Download the generated document and save it as Concept.md.

2. Design.md — Creating UI/Design Reference Documents First

If the app has a UI, it is good to write Design.md first. That is, if there is a service or app you want to reference, or if you already know how to design UI yourself, you can request it by providing images of designs worked on in Figma, etc.

Method

• Choose one actually deployed website that you like. (e.g., linear.app, stripe.com, toss.im, etc.)
• Instruct Claude or Grok to "Analyze the layout structure, color palette, typography, margins/spacing, and component styles of that site and organize it into Design.md."

Prompt Example

Analyze the design of https://linear.app and write a Design.md document. You must include the following items: 1. Overall layout structure (Header/Sidebar/Body/Footer placement) 2. Color palette (Primary, Secondary, Background, Text colors in HEX codes) 3. Typography (Font types, size system, weights) 4. Margins and spacing rules (spacing scale) 5. Styles for major components like buttons, cards, and input forms 6. Dark mode support and color mapping

Tips

• If you have a sense of design, since the generated Design.md content is all described in natural language, you can read it and directly modify/refine it in the direction you want. This document becomes the standard for all subsequent UI implementations.
• If you just say "Make it like this site," the results will vary every time. You must fix it with a document to maintain consistency.

2. Tech Stack Decision Recommendation Tree

Determine the stack first based on the type of service you are trying to create.

Common Server (Backend) Principles

• It must be possible to install and run directly from the CLI in any local environment.
• The language/runtime should be Node.js or Python.
• Use tools verified for stable deployment and support across all OSs for packages/execution environments:
• Python → uv
• Node.js → npm

Database Selection Criteria

Detailed Prompt Instructions (If you have development knowledge)

This project is a web app. Configure the Frontend with React, and it should be possible to test immediately with npm run dev locally, with a structure that allows for stable deployment. Configure the Backend with Node.js, and since a relational DB is needed, use MariaDB. Include a setup script that can be installed/run directly via CLI in the local development environment. Check this content and the Concept.md document to write a ToDo.md document for detailed technical implementation.

• Proceed by attaching the Concept.md document with this prompt or by copying and pasting the contents of the Concept.md document.

But what if I'm a non-developer who doesn't know the above?

Just give integrated instructions like this:

I'm not sure how to run this project, so please recommend a way. Recommend whether a web app is better, if an OS installation method is easier to check during development, or if building as a mobile app is better. If it can be shown in a web browser, configure the Frontend with React; if it needs to be served as a mobile app, configure the Frontend with Flutter. If it's a method that needs to be installed locally, configure it using npm or uv, which can be easily deployed and installed via CLI. Set up a structure that allows for stable deployment. I'm not sure if a Backend is needed, but set up a stable structure for Node.js or deployment/installation. If a DB is needed, use MariaDB if a relational one is required, and if it's just a key-value DB, use AWS DynamoDB locally for development and configure it for easy deployment to AWS. If it's a format that can be installed/run directly via CLI in a local development environment, include all setup scripts. Recommend such a detailed technical stack, check this content and the Concept.md document, and write a ToDo.md document for detailed technical implementation.

3. Admin Dashboard — Essential if there is a server

You might not know if it's a service with a server, but it's usually good to build one so that the developer can personally grasp the operating status and progress of the entire app.

• Projects with a server should include the implementation of an Admin dashboard as a default.
• Minimum items to include in the dashboard:
• Server health check
• Key data status (core metrics like number of subscribers, number of processed cases, etc.)
• Recent errors/logs
• Processing progress of major tasks (batches, queues, etc.)

Prompt Example

If this service includes a server, include an admin dashboard in the development plan. The dashboard should allow checking server status, core metrics, and recent logs/errors. Set the default admin account to 'admin' with password '12345', and include the ability to change the password in the admin dashboard. Check ToDo.md and include this in the development plan if deemed necessary.

4. Finalizing ToDo.md — Module-level Development Plan

The basis of programming is modularization. If you add content to ToDo.md to subdivide into modules before writing code, a good architecture for future maintenance can be created.

Prompt Example

Check the ToDo.md document and verify if it is well-written according to the guide below, and modify/supplement any lacking parts. ToDo.md Requirements: 1. Design the entire system to be modularized with object-oriented design. 2. Specify each module's role, input/output, and data structure clearly to ensure maximum encapsulation. 3. Create an implementation sequence as a checkbox list (starting from modules without dependencies). 4. Include DB schema design. 5. Describe when and how non-technical people can easily test.

Items to verify in the completed ToDo.md:

1. Project Overview (one paragraph)
2. Confirmed Tech Stack (Result of the decision tree in step 2)
3. Module list and detailed technical specifications for each module (Non-technical people may find this difficult to understand)
4. Module name and role
5. Input/Output (API endpoints and request/response formats)
6. Data structure used / DB table (or collection) design
7. Dependency relationships with other modules
8. Implementation sequence (in checkbox form, in order of dependency)
9. Check if each test method is written at a level I can understand.

Important

• You don't necessarily have to read and review the generated ToDo.md yourself. While it seems like things will go well if you prepare perfectly, the core of Vibe Coding is the process of creating a result first and then gradually modifying it to get what you want—that is the most valuable and fun part.

Practice Part: Environment Setup → GitHub → Starting Claude Code Development

Written so that even those installing development tools for the first time can follow along.

• Nevertheless, if it seems too complex and you don't know why you should use it and are bored to death, please go listen to a free lecture at the link below first.

https://nomadcoders.co/git-for-beginners

5. Preparing the Development Environment (Install only 2 things)

We will install two things.

And you need a GitHub account. Sign up for free at https://github.com (complete email verification). Using Claude Code or Grok Build requires a Claude paid plan (Pro/Max/Team) or a Grok paid account.

5-1. 🪟 Windows User Installation Steps

① Install Git

1. Go to https://git-scm.com/download/win in your browser → Download starts automatically.
2. Run the downloaded installer.
3. Many installation options appear; just keep clicking "Next" with all default values.
4. However, when the "Choosing the default editor" screen appears, it's good to select "Use Visual Studio Code as Git's default editor" (if you haven't installed VS Code yet, the default is fine).
5. Verify installation: Run PowerShell from the Start menu and type:

git --version

→ If a version like git version 2.xx.x appears, it's a success. If not, try closing and reopening PowerShell.

② Install VS Code

1. Go to https://code.visualstudio.com → Click Download for Windows.
2. Run the installer → Keep clicking "Next." However, check these two in the options screen:
3. "Add to PATH"
4. "Add 'Open with Code' action to file/directory context menus"
5. Run VS Code after installation. If a Korean language pack installation notification appears on the first screen, you can install it.

5-2. 🍎 Mac User Installation Steps

① Install Git

1. Open Terminal: Cmd + Space → Type "Terminal" → Enter.
2. Type:

git --version

1. If the version appears immediately, it's already installed → Move to ②. If an installation guide popup ("Command Line Developer Tools...") appears, click "Install" and wait. (This is the Git installation).
2. Verify again with git --version after completion.

② Install VS Code

1. Go to https://code.visualstudio.com → Click Download for macOS.
2. Unzip the downloaded file and drag Visual Studio Code.app to the Applications folder. (Important! Don't use it directly from the Downloads folder).
3. Run VS Code from Applications.

5-3. (Common) Registering My Name in Git — First Time Only

This setting is to leave a record of "who worked on it" in commits. In PowerShell (Windows) or Terminal (Mac):

git config --global user.name "Your Name" git config --global user.email "your-github-email@example.com"

Enter the same email you used to sign up for GitHub.

6. Creating a GitHub Repository and Connecting to My PC with VS Code

Think of a "Repository" as a cloud folder that holds one project. The flow is: Create an empty repository on the GitHub website → Clone it to my PC with VS Code → Upload planning documents → Connect that repository to Claude Code web.

6-1. Creating a Repository on the GitHub Website

1. Log in to https://github.com.
2. Click the + button in the top right → New repository.
3. Enter as follows:
4. Repository name: Project name (English, hyphens instead of spaces. e.g., my-first-app)
5. Select Private (Company projects must be Private!)
6. Check the "Add a README file" checkbox ✅ ← Beginners must check this. This makes the next step (clone) simpler.
7. Click Create repository.
8. On the created repository page, click the green <> Code button → Copy the address in the HTTPS tab.

6-2. Cloning to My PC with VS Code

1. Run VS Code.
2. Ctrl + Shift + P (Cmd + Shift + P on Mac) → Command palette opens.
3. Type clone → Select "Git: Clone".
4. Paste the copied repository address and press Enter.
5. You can also select "Clone from GitHub" → If the browser opens and asks for GitHub login/authorization, approve it. (First time only).
6. Select a location to save the project (e.g., it's good to create a Documents/Projects folder).
7. When cloning is finished, an "Open" notification appears in the bottom right → Click it.
8. If you see README.md in the file explorer on the left, success! 🎉 This folder is now the working folder connected between my PC and GitHub.

6-3. Uploading Planning Documents — Concept.md, Design.md, ToDo.md

Claude Code web can read files inside the repository. So, putting planning documents in the repository is the same as "uploading documents."

1. Right-click in an empty space in the VS Code file explorer → New File → Enter the name Concept.md.
2. Paste the app description you prepared and save (Ctrl+S / Cmd+S).
3. Create and insert Design.md (if there's a UI) and ToDo.md files in the same way.
4. Now upload to GitHub (commit & push) — using the method in 6-4.

6-4. Committing and Pushing in VS Code — Mouse Only

1. When you save a file, a number badge appears on the branch-shaped icon (Source Control) on the left of VS Code.
2. Click that icon → You will see a list of changed files.
3. In the message input box at the top, write one line about what you did. (e.g., Added planning documents).
4. Click the ✔ Commit button → Save completed on my PC.
5. If a "There are no staged changes" popup appears, click "Yes" to commit everything.
6. Then click the Sync Changes button → Upload (push) to GitHub completed.
7. Refresh the repository on the GitHub website to see the Concept.md you just uploaded. Now Claude Code web can also read this document.

Pulling (downloading) is also done on the same screen: If there are changes Claude uploaded in the cloud, the Sync Changes button will handle both downloading and uploading.

7. Connecting the Repository to Claude Code Web and Starting Development

Now open Claude Code web in your browser and connect the GitHub repository you just made.

7-1. Connecting Claude Code Web ↔ GitHub Repository (First Time Only)

1. Access https://claude.ai/code → Log in with your Claude account.
2. When you first access it, a Connect GitHub guide appears → Follow the guide.
3. You will be moved to the GitHub page, and the Claude GitHub App installation screen will appear:
4. Select your GitHub account (or organization).
5. Select access range: It is recommended to select "Only select repositories" and specify the repository made in 6-1.
6. Click Install / Authorize.
7. Returning to Claude completes the connection. If the Environment settings screen appears, leave it at Default.
8. When starting a new session (task), select your repository from the repository selection list, enter a prompt, and the task begins.

7-2. Understanding How Claude Code and Grok Build Web Work (Important!)

Claude Code and Grok Build web work on a virtual computer in the cloud, not on my PC. The flow is:

① I enter a prompt

↓

② Claude Code/Grok Build clones my repository in the cloud and writes code

↓

③ Pushes the result to GitHub as a "new task branch"

↓

④ I pull that branch to my PC to test, or check changes via Pull Request on GitHub

↓

⑤ If I like it, merge into main.

• Since it always uploads results to a new branch without touching the main branch directly, there's no worry about existing code breaking. (Grok Build works on the main branch but can be undone, so don't worry about mistakes).

7-4. Development Start Prompt

Once the three documents (Concept.md / Design.md / ToDo.md) are ready in main, finally start development in a new session.

Develop this project. Proceed based on the following documents in the repository: - Concept.md: Description of the app to be made - ToDo.md: Module-level development plan (implement in this order) - Design.md: Design standards (all UI follows this document)

Working Rules: 1. Proceed one module at a time according to the implementation order in ToDo.md. 2. When a testable unit is completed, let me know how to run/test it on my local PC via README or response. Since I'm a non-developer, explain it well as if teaching a beginner. 3. Mark completed items with a checkmark in ToDo.md. 4. Tell me the task branch name and push with an easy-to-remember commit message. 5. If there are unclear parts, don't guess; ask me.

7-5. Cycle Repeated During Development

① Web Claude Code implements one module in a task branch → push

↓

② Pull that task branch to my PC (VS Code) and run/test it directly

↓

③ If there's a problem → Copy the entire error message and paste it into the web session

If there's no problem → "Good, continue with the next development"

↓

Return to ① for the next module

↓

④ Once all features are completed and tests passed

→ Merge into the main branch via Pull Request

→ Deployment is always based on main

8. Branch — Testing in Task Branches and Merging to main for Deployment

8-1. What is a branch?

• main branch = The finished product display that always works well. Deployment is always based on main.
• Task branch (e.g., claude/feature-login) = A construction site made by copying main. You can build and break things here as much as you want; main is safe.

Claude Code web always creates a new task branch and pushes the results. So, there are just three things you need to know:

1. How to check which branch my folder is currently on.
2. How to pull the task branch pushed by Claude to my PC for testing.
3. How to merge into main and deploy when finished.

8-2. Checking Which Branch You Are On

• Look at the status bar at the very bottom left of the VS Code screen. The branch name is displayed next to the branch icon. (e.g., main or claude/feature-login).

8-3. Pulling Task Branches Created by Claude Code/Grok Build to My PC for Testing

When web Claude Code says "I pushed to branch OO," bring that branch to my PC to test. Grok Build has a 'Push to Github' button in the top right of the web screen, so press this to push.

With VS Code (Mouse Only):

1. Click the branch name at the bottom left → Branch list opens.
2. If the new branch isn't visible, run ... menu → Fetch in the Source Control tab and try again.
3. Select Claude's task branch starting with origin/claude/... from the list → Your folder changes to that branch state.

8-4. Merging into main When Finished — Pull Request

If features are completed and tests passed in the task branch, merge into main via Pull Request (PR) on the GitHub website.

1. Access your repository on GitHub → Click the Pull requests tab.
2. Click the PR Claude made. If none, New pull request → base: main, compare: select task branch → Create pull request.
3. Click Merge pull request → Confirm merge → Reflected in main!
4. Update your PC's main to the latest:
5. Click branch at bottom left of VS Code → Select main → Sync Changes in Source Control tab.

9. Prompting Tips (Common)

The quality of Vibe Coding is proportional to the quality of the prompts.

1. Specify what NOT to do — "Don't modify code arbitrarily until I approve," "Don't add libraries, use only the existing stack."
2. One module at a time — Quality drops if you ask for the whole app in one prompt. Ask in small chunks according to the ToDo.md order.
3. Paste errors as they are — Don't summarize error messages; copy the entire terminal output.
4. Let Claude ask if it's ambiguous — Include "If there are unclear parts, don't guess; ask me" in the prompt.
5. Communicate based on documents — "As I said earlier" ❌ → "According to the Design.md design" ✅. Documents in the repository are much more stable than conversation memory.

The end.

As the ancient Morpheus said:

"Neo. I can only show you the door. You're the one that has to walk through it."