> ## Documentation Index > Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # Vibe Coding > Building software in dialogue with an AI coding agent: the groundwork it requires, the verification that stays with the human, and the supporting techniques. ## Overview Vibe coding is a development approach in which you describe what you want in natural language, let a generative-AI coding agent produce the code, and steer, verify, and refine the result through continuous dialogue. The term is sometimes used for a throwaway-prototype style in which generated code is accepted without being read. This page covers something else: the practice as applied to a production codebase maintained by a team, where a human stays responsible for verifying the output. This page explains the groundwork a coding agent needs before it can perform, the verification responsibilities that stay with the human, and how to handle sessions, context, and custom instructions. ## Prerequisites A coding agent's output quality is bounded by the codebase and process it works in. When AI adoption fails to deliver, the cause may be missing groundwork rather than the tool. The coding agent has nothing consistent to imitate and no guardrails to catch its mistakes. Conventions, tests, and design knowledge are not made obsolete by the coding agent — they are what the coding agent runs on, and what lets you judge its output. Prepare the foundation before expecting results. A coding agent imitates the code it sees. A codebase that follows one consistent style — for example, a published style guide — steers generation toward uniform output, while mixed styles produce mixed results. Tests serve two roles: they are a primary source the coding agent reads to understand the spec, and a guardrail that mechanically catches wrong output before a human does. READMEs, design docs, and coding agent instruction files (such as `AGENTS.md` or tool-specific configuration) are standing context the coding agent receives every session without being pasted into the prompt. A habit of small, focused pull requests keeps coding agent output reviewable. Generation speed is worthless if the change arrives too large to verify. Dead or unused code works against all of the above: the coding agent cannot tell that it is obsolete and will imitate it. Removing it is part of preparing the codebase. ## Verification and the human's responsibility Vibe coding changes who writes the code, not who is responsible for it. The author of a generated change is the human who requested it: before sending it to review, be able to explain every line. Generation speed that produces unexplained changes does not raise productivity — it moves the cost from writing to reviewing, where it grows. Do not rely on eyeballing alone. Hand the coding agent a check that returns pass or fail — the test code, the build, a linter — and instruct it to iterate until the check passes. Then have the coding agent show evidence (the test output, the command it ran and its result) rather than assert success. ## Manage sessions deliberately Treat a session as a unit of context. Keep related changes in the same session so the coding agent retains shared context. Horizontal expansion is the clearest example: get a single instance working and verified, then expand to the remaining places in the same session, where the verified implementation is still visible to the coding agent. The proven example serves as the spec for the repetitive work. ```text Example instruction for the expansion theme={null} Apply the same pattern you just used for UserCard to ProductCard and OrderCard. ``` Start a new session for an unrelated task so stale history does not bleed in. A session's history has the same limitation as human short-term memory: the more irrelevant material it holds, the less reliably the relevant part is used. A working rule: after correcting the coding agent twice on the same issue, stop correcting. The context now holds the failed attempts, and they keep steering the output. Start a new session with a prompt that incorporates what the failures taught you — a clean session with a sharper prompt outperforms a long session with accumulated corrections. ## Keep course corrections cheap A coding agent generates code fast, which means it generates the wrong code fast too. To keep the cost of a wrong direction low, structure the work so any single step is cheap to discard, and commit at a fine grain. Commit in small, coherent steps — finer than you would open a pull request — so you always have a safe point to roll back to. Take a data-model change as an example: proceed in sequence — **define the model → verify it → generate the migration**. ```text Example sequence: adding a table theme={null} 1. Create only the model file and commit it 2. Verify the field names and fix mistakes (e.g. last_name → family_name) 3. Generate and run the migration ``` With this order, a wrong field name caught at step 2 costs a one-file fix. Catch it after generating the migration in one shot, and the correction requires a rollback and changes across multiple files. ## Hand over just enough context The largest factor in output quality is the size and focus of the context handed to the coding agent. A sprawling, multi-part request spreads the coding agent's attention thin and accuracy drops; a narrow task with the right references produces clean, on-target code. The goal: **give the coding agent the smallest context that is still complete enough to do the job.** ```text Bad: too much theme={null} Something's broken in search — fix it. Just in case, here's the full source of search.ts, query-parser.ts, and index.ts (about 1,500 lines), plus the Slack thread from a similar issue we had before. And if anything looks worth refactoring along the way, go ahead. ``` ```text Bad: not enough theme={null} Search is broken, fix it ``` ```text Good: just enough theme={null} Search sometimes returns a 500 error. Error log: 2026-07-07T10:23:45.812Z ERROR GET /api/search?q=tokyo　cafe 500 (12ms) TypeError: Cannot read properties of undefined (reading 'split') at parseQuery (src/search/query-parser.ts:27:35) at searchHandler (src/api/search.ts:18:24) at Layer.handle [as handle_request] (node_modules/express/lib/router/layer.js:95:5) Write a failing test that reproduces it first, then fix it. ``` The first has enough information, but most of it is noise that dilutes attention, and the "refactor along the way" mixes in an unrelated concern. The second is minimal, but with no location and no detail about the symptom it invites an unbounded search. The third hands over only what acting on the task requires: the symptom, the actual error log, and how to proceed. It states no theory about the cause: the log carries the failing request and the failing location as facts, and tracing them to the cause — a keyword containing a full-width space — is the coding agent's job. Structure also matters. A hierarchically organized instruction — goal, then constraints, then concrete references — is parsed more reliably than one long undifferentiated paragraph. ```text A poor instruction theme={null} Add an API for updating a user's role. While you're at it, make roles editable from the UI too, make sure authorization is handled properly, and match the validation to the existing code — something reasonable is fine. ``` ```text Example of a structured instruction theme={null} Goal: add an API endpoint that updates a user's role Constraints: - Scope is PUT /api/users/:id/role only; no UI changes in this task - Use the existing authorization middleware References: - Mirror the routing and input validation of updateUser in src/api/users.ts - Use requireRole from src/middleware/authorize.ts for the permission check ``` When the task needs data the coding agent cannot see — issues, library documentation, design data — provide it through a Model Context Protocol (MCP) server rather than pasting large blobs into the chat. ## Use custom instructions Custom instructions are an instruction file the coding agent reads at the start of every session: build and test commands, style rules that differ from defaults, repository conventions, and known gotchas. They are the concrete form of the "documentation and custom instructions" item in the foundation above. ```markdown AGENTS.md theme={null} # Commands - Build: npm run build - Typecheck: npm run typecheck - Lint: npm run lint (auto-fix: npm run lint -- --fix) - Test a single file: npm run test -- path/to/file.test.ts (prefer over the full suite) - Dev server: npm run dev (http://localhost:3000) # Code style - Use ES modules (import/export), not CommonJS (require) - Use named exports; do not add default exports - Destructure imports when possible (e.g. import { foo } from 'bar') - New UI components follow the structure of src/components/Button/ (colocated test and story) # Testing - Test framework is Vitest; do not use Jest APIs - Place tests next to the source file as .test.ts - Avoid mocks where possible; use the fixtures in tests/fixtures/ # Repository etiquette - Branch naming: feature/- - Commit messages follow Conventional Commits (feat:, fix:, chore:) - Run npm run typecheck and npm run lint before opening a pull request # Architecture - All API access goes through src/lib/api-client.ts; never call fetch directly - State management is TanStack Query; do not introduce Redux # Environment quirks - The dev server requires .env.local; copy it from .env.example - Use Node 22 (managed with mise); npm install fails silently on Node 18 ``` Check the file into git so the team shares it, and keep it short — in an overlong file, individual rules get lost and adherence drops. Knowledge that is only sometimes relevant belongs in a [skill](/ai/skill), which loads on demand instead of occupying every session. ## Related pages Where vibe coding builds in dialogue, agentic workflows delegate implementation to coding agents and scale it in parallel. Encode a recurring workflow once as a skill and invoke it whenever needed.