People use the phrase “vibe coding” a lot these days. It sounds like telling an AI what you want and letting it write the code. That is how I started too: “build this feature,” “fix this bug,” or “make this UI prettier.” The approach reaches its limit quickly once a project grows.
AI writes code quickly, but when it loses context it writes strange code even faster. It may ignore the existing structure and invent a new abstraction, mark a document as complete without actually verifying anything, or make a broken test look finished from the outside.
My current approach is different. I build the development environment where the AI will work before I try to improve the prompt.
document structure
-> work routing
-> skills harness
-> small implementation slices
-> verification loop
-> review and push
I think this entire flow is the real substance of vibe coding.
1. Make the Repository Explain Itself
Pasting a long explanation into every AI session does not scale. For a large repository, I decide which documents an agent should read first.
docs/README.md
docs/contributing/roadmap.md
docs/contributing/feature-registry.md
docs/architecture/
docs/agents/
docs/testing/
These files are closer to routers than to a simple project introduction. They first separate the feature being changed—web, API, worker, or database—and then explain which rules apply.
For example, a large web-service repository might set boundaries like this:
apps/web - Next.js UI
apps/api - API server
apps/worker - background worker
packages/db - database schema
packages/llm - LLM provider abstraction
packages/shared - shared contracts
Once those boundaries are fixed in documentation, the AI is less likely to invent a “reasonable-looking” new structure. I do not have to repeat rules such as “do not import the database directly from the frontend,” “put user-facing copy in i18n files,” or “run long worker jobs through Temporal.”
To vibe-code well, the repository's basic context needs to be good before the prompt does.
2. Separate Public and Private Operating Documents
I divide documentation into two layers. Documents in the public repository contain stable information that the product and contributors can read. The current development state, failed attempts, next-session prompts, audit notes, and review responses belong in private operating documents instead.
.private-docs/
docs/superpowers/
Public documentation should be clean. But an AI agent needs messy working context to do a good job: which branch is in progress, which tests actually passed, and which plan was abandoned. Putting all of that in the README ruins the public documentation. Keeping none of it means repeating the same mistakes in the next session.
So I separate product documentation from operating documentation and tell the AI about the difference. It needs to know what belongs in public docs and what should remain maintainer context.
3. Fix the Workflow with a Skills Harness
A skill is a small operating manual that tells an AI what to do in a particular situation. Instead of writing a long instruction every time, I keep rules for each type of work in files.
project-rules
post-feature
parallel-sessions
next-plan
commit-rules
project-rules defines the codebase rules. post-feature makes the agent check documentation, tests, diffs, and status before claiming a feature is finished. parallel-sessions explains how to divide worktrees and file ownership when several agents run at once.
I also use skills from the Superpowers plugin:
writing-plans
test-driven-development
systematic-debugging
verification-before-completion
requesting-code-review
receiving-code-review
using-git-worktrees
The important instruction is not “AI, please do a good job.” It is “follow this procedure in this situation.” Quality in AI coding does not come from model capability alone. The same model can produce completely different results depending on the routine around it.
4. Cut Work into Small Slices
Do not ask an AI to “finish this project.” Cut the work like this instead:
Goal: let an agent propose note updates
1. Add an agent_actions ledger to the database
2. Add preview/apply endpoints to the API
3. Add a review UI to the web app
4. Generate action payloads in the worker
5. Run tests and a smoke check
Assign owned files to each slice.
packages/db/src/schema/agent-actions.ts
apps/api/src/routes/agent-actions.ts
apps/web/src/features/agent-actions/
apps/worker/src/worker/agents/
This is what makes parallel work possible. One session can own the database and API, another the web UI, and a third the worker agent. The speed of vibe coding comes less from how quickly AI types code than from the ability to divide work without collisions.
5. The Verification Loop Matters More Than Implementation
The most dangerous sentence in AI coding is “It is complete.” I therefore put a verification loop before completion.
inspect changed files
-> type check or tests
-> build
-> browser smoke check when needed
-> review git diff
-> update document status
-> commit / push
Every task does not need the full test suite. The verification should be the narrowest one that matches the changed scope. If I changed copy, I check i18n parity and the web build. If I changed API permissions, I check route and security tests. If I changed worker ingestion, I check activity-level tests and the payload contract.
The point is not to believe the words “verified” without seeing the result.
Before claiming success, run the actual command.
If it fails, record the failed command and the cause.
Separate what passed from what you have not verified yet.
Without this loop, vibe coding is simply a fast technical-debt generator.
6. Prompts Get Shorter while the Environment Gets Longer
My prompts have actually become shorter. I used to explain everything at length:
This project has this structure, these rules, and this feature should work like...
Now I can say:
Read the current implementation and continue with the next slice.
Or:
Review this PR, apply only what is needed, and push it.
That is not because the prompt became better. It is because the repository now contains the documents, skills, plans, and verification rules the AI needs to read.
Vibe coding is closer to an operating system than a momentary chat technique. The user gives a short goal. The agent reads the repository context, follows the skills, runs the work, and leaves the verification result behind.
7. What I Think Comes Next
If this flow becomes more general, it could look like a solo-devflow-os. The idea is to bundle the document structure, skills harness, worktree operation, verification loop, and PR routine into one template so a solo developer does not repeat the same setup every time.
AGENTS.md
docs/README.md
docs/contributing/roadmap.md
docs/contributing/feature-registry.md
docs/testing/
docs/superpowers/plans/
.private-docs/
skills/
scripts/verify/
This is not tied to one model or one IDE. Whether you use Codex, Claude Code, or Cursor, the core idea is the same. To help AI work well, a good workshop matters before a good prompt.
Summary
1. Make the repository explain itself
2. Separate public and private operating documents
3. Keep a skills harness for each kind of work
4. Cut features into small slices
5. Enforce a verification loop before completion
6. Leave the result in documentation and git history
This does not make the AI understand everything automatically. It does let one developer operate as if several junior developers were working alongside them. Each session can be imperfect. What matters is that every session reads, builds, verifies, and hands off work in the same way.
I think this is where the difference in development productivity will appear. The question is not who writes the longest prompt. It is who designs the system where AI can work most effectively.