Repository: https://github.com/stephenli2000/Structured_Vibe_Coding
License: BSD. Use at your own risk; PRs welcome. Keep changes tiny, logs clear, and defaults sensible.
Author's experience:
Using this methodology, I've generated 99% of production code with Claude, Gemini, and GPT — across both small features and large complex tasks — over the past 1.5 years, on a monthly subscription budget of $20–$60. My background: decades in C/C++, Linux, Git, Python, and AI.
- 1. Philosophy: Structured Vibe Coding
- 2. The Blueprint Method
- 3. Vibe Coding Tools
- 4. Workflow Examples
- 5. FAQ
This toolkit is for software engineers comfortable with the command line.
- Chat-only workflow: AI is changing fast — don't lock yourself in to any one model or tool.
- Requirements, design, and coding: Have AI confirm each stage before moving to the next.
- Git and diff: Communicate with the AI through git history and diffs so it can reason over the exact context you see.
For small features, you don't need the Blueprint Method — jump straight to Vibe Coding Tools.
For larger features, asking an AI to design architecture and write code at the same time often leads to hallucinations and context drift. Use The Blueprint Method: a three-phase methodology that shifts AI from a guessing machine to a precise execution engine.
- Minimize cost. Flat-rate chat subscriptions instead of token-metered agentic tools — predictable spend for solo developers, students, contractors, and small teams.
- Switch models freely. The same text bundle drops into any chat — Private AI (self-hosted Llama, DeepSeek, Qwen), Claude, GPT, Gemini — so you pick the best model per task without changing tools.
- Learn a portable discipline. The Blueprint Method (requirements → design → code, with verification gates) outlives any specific tool or model.
A methodology that gets explicit confirmation at each step: requirements → design → coding. Humans and AI stay aligned without rework or context drift.
Move your design, requirement, and test documents into Markdown format, DESIGN.md in the repository.
VS Code, with a few extensions, gives you a Word/Google Docs-like editing experience for Markdown:
- Export Google Docs to HTML ZIP, then convert the HTML into Markdown with Pandoc:
pandoc GoogleDocExport.html --wrap=none --markdown-headings=atx -f html-native_divs-native_spans -t gfm-smart --extract-media=. -o CleanedDocExport.md - Use Mermaid
sequenceDiagramfor inline interaction sequences. - Use Mermaid
graph TDfor inline flowcharts and architecture diagrams. - Use drawio for diagrams, then export to SVG and embed inline in your Markdown.
- Use GitHub Flavored Markdown (GFM) for tables.
- Use the Markdown All-in-One extension for section numbering and the Table of Contents.
Feed the AI your change request and ask it to audit for edge cases before any code is written.
Audit
change_request_prompt.mdfor clarity, missing edge cases, and logical gaps. Rewrite it into strict Given-When-Then acceptance criteria, and propose updates tochange_request_prompt.mdreflecting the new scope. Wait for my approval before writing any code. Do not include details already implemented in the codebase.The Ground Truth Principle: Treat the codebase as the absolute source of truth. Markdown design files are historic intent. If they clash, the code wins.
Have the AI map out how the change request integrates into the codebase by updating your design docs (DESIGN.md or any Mermaid diagrams).
Based on the approved
change_request_prompt.mdand the codebase context, updateDESIGN.md. Wait for my approval. Then generate a strict step-by-stepcoding_prompt.mdfor execution. Wait for my approval. Do not include incoding_prompt.mdany details already implemented in the codebase.The Ground Truth Principle: Treat your codebase as the absolute source of truth. Design docs are historic intent. If they clash, the code wins.
Feed the AI the generated coding_prompt.md and force it to code incrementally.
Execute step 1 of the
coding_prompt.md. Write complete, production-ready code with no placeholders. Stop and wait for me to verify the tests pass before moving to step 2.
Keep it simple. These small scripts package the right text or code so you can drop a file, folder, or file type into a chat-based AI. No lock-in to any model or tool.
python3 -m venv venv && source venv/bin/activate
# run any tool with: python3 <tool>.py [args]- Run a tool below to generate a single text file.
- Attach or paste that file into your coding chat.
- Prompt the AI for what you want — review, refactor, tests, bug fix, or a Blueprint Method phase.
Snapshot all text files in a repo.
What: Recursively collects text-like files (.py, .md, .json, etc.), skips noisy folders (.git/, node_modules/, dist/, etc.), and writes one bundle with a header per file.
Why: Share the whole project context in chat without zipping.
Usage:
python3 concatenate_text_files.py path/to/project
# → creates ./<project>.txt containing all included files with headersThe script supports --code-only and --py-only options to reduce the number of files included in the package.
Bundle a script plus its local imports.
What: Traces local Python imports starting from one or more entry scripts and concatenates those files into a single text artifact.
Why: Give AI the exact Python dependency closure it needs for reasoning, without external packages.
Usage:
python3 concatenate_python_files.py project_root/ path/to/main.py [another.py ...]
# → writes project_root_concatenated.txtPackage the files changed in a commit or range.
What: Finds files changed in one commit (or between two commits) and writes their contents to a single text file with commit headers.
Why: Share focused diffs for targeted reviews or debugging.
Usage:
# Single commit
python3 save_commits.py --this f9e8d7c
# Range (base..this)
python3 save_commits.py --base a1b2c3d --this f9e8d7c
# → writes <this>.txt or base-this.txtQuick repo inventory.
What: Scans a directory, groups files by type, totals sizes, and shows a small table (count, total size, example largest file). No bundle output — just fast insight.
Why: Decide what to package (and what to ignore) before chatting.
Usage:
python3 analyze_folder.py # analyze current folder
python3 analyze_folder.py path/to/dir # analyze a specific directorypython3 concatenate_text_files.py ./myapp→myapp.txt- Attach
myapp.txtin chat. - Ask: "Review for structure, add tests for X, and propose a minimal refactor."
python3 concatenate_python_files.py ./tools ./tools/runner.py→tools_concatenated.txt- Attach; ask: "There's a crash when input is empty. Fix it and add doctests."
python3 save_commits.py --base abc123 --this def456→abc123-def456.txt- Attach; ask: "Explain risk, edge cases, and missing tests in this change."
python3 concatenate_text_files.py ./myapp --code-only→myapp_code.txt- Attach
myapp_code.txtalong with yourrequirement_prompt.md. - Follow the prompts in Section The Blueprint Method to design and execute without context drift.
Why text instead of zip? Text is immediately visible and searchable in chat, avoids unzip friction, and keeps you and the AI tightly in sync.
Does this include third-party dependencies? No — these tools focus on your source and local imports. Mention external packages in your prompt or attach your change_request_prompt.md.