--- title: "Context Is Infrastructure in Vibe Coding" summary: "A practical manifesto on why agents need context bounded by step, focused prompts, necessary skills, and separate tasks to produce better work." slug: "context-is-infrastructure-in-vibe-coding" language: "en" publishedAt: "2026-06-18" updatedAt: "2026-06-20" tags: - "manifesto" - "context" - "process" - "agents" translationOf: "pt/contexto-e-infraestrutura-no-vibe-coding" translationStatus: "current" --- Vibe coding does not start with the prompt. It starts with context. An agent without context works by approximation. It tries to guess the project, the tone, the constraints, the architecture, and the definition of done. Sometimes it gets it right. Often it only looks like it did. Context is not decoration. It is working infrastructure. Each step needs its own context. Diagnosis does not use the same context as planning. Planning does not use the same context as implementation. Putting everything in the same prompt asks the agent to mix question, decision, and execution. ## What counts as context Context is not dumping everything into the chat. Good context is information that is organized, current, and useful for the task. It can live in: - `AGENTS.md`; - `README.md`; - `PLANS.md`; - documentation in `docs/`; - existing code; - tests; - recorded decisions; - definitions of done; - validation commands. The agent needs to understand the ground it is standing on. Not to obey blindly. To act with less noise. ## The single-chat mistake A bad practice is trying to run all of vibe coding in a single chat, conversation, or task. It looks efficient. It is not. Long conversations accumulate intent, correction, detour, exception, and improvisation. After many turns, no one knows exactly which decision still applies. The agent loses sharpness. So does the person. Exploration, planning, implementation, and review are different phases. Mixing everything into one conversation turns the process into something hard to audit. A prompt has the same problem. Do not ask for diagnosis, planning, and implementation in the same request. Each step should be a separate task, with its own input, goal, and output. A project should not depend on the fragile memory of an open window. It should depend on files, history, validations, and recorded decisions. ## One step per task The best flow is smaller. Simpler. More verifiable. Diagnosis is one task. Planning is another. Implementation is another. They should happen in that order. And they should happen in separate prompts. This rule also applies to every example prompt. A suggested prompt should focus on exactly one step: diagnosis, planning, or implementation. If the prompt is for diagnosis, it should not ask for a plan. If the prompt is for planning, it should not ask for code changes. If the prompt is for implementation, it should start from an approved plan and execute only one part of it. The example needs to teach the boundary. Not merely solve the case. ### Diagnosis Diagnosis exists to understand the current state. It should not plan the whole solution. It should not edit files. ```txt Step: diagnosis. Read AGENTS.md, README.md, and the relevant documents. Do only a diagnosis. Do not implement anything. Do not create a detailed plan yet. List the context found, gaps, risks, and questions. ``` ### Planning Planning exists to turn diagnosis into a work sequence. It should not implement. It should create small, verifiable, ordered steps. ```txt Step: planning. Based on the approved diagnosis, create an incremental plan. Do not change code. Separate the steps by goal, likely files, and validations. Indicate the first step small enough for isolated implementation. ``` ### Implementation Implementation exists to execute a specific step of the plan. It should not reopen the entire diagnosis. It should not reinvent the planning. ```txt Step: implementation. Implement only step 1 of the approved plan. Before editing, say which files you intend to change. Then run the available validations. List changed files, risks, and pending items. ``` These prompts are limited on purpose. Limits do not get in the agent's way. Limits give direction. If the prompt asks for diagnosis, planning, and implementation at the same time, it has already started wrong. Good vibe coding is not one heroic session. It is a sequence of clear cycles. ## Skills are not decoration Skills exist to expand the agent's ability in specific situations. That is the important part: specific. Using a skill without need is a bad practice. It can add too many instructions, call the wrong tools, increase the cost of the task, produce unnecessary files, or move attention away from the real problem. Not every task needs a skill. Fixing a simple text does not require the same apparatus as creating a presentation. Adjusting a post does not require the same flow as investigating a CI failure. Implementing a small layout change does not require turning the task into broad research. The right question is: Does this skill directly help the current step? If the answer is no, do not use it. A good tool also needs the right time. ## Too much context also gets in the way There is another mistake: sending too much context. An agent does not improve just because it received more files, more links, more rules, and more history. It improves when it receives the relevant context. Before asking for any step, it is worth separating: - the goal of that step; - the likely files; - the constraints; - the important examples; - the validation commands; - what must not be changed. The rest can wait. Good context is a deliberate slice. ## How to split a large task When the idea is large, do not ask for everything. Turn it into steps. ```txt 1. Diagnosis: understand the problem, the repository, and the risks. Do not plan in detail. Do not implement. 2. Planning: turn the approved diagnosis into small steps. Do not implement. 3. Implementation: execute only one approved step. 4. Validation: run the available commands and review the result. 5. Record: document decisions, risks, and next steps. 6. Next step: move forward only after the previous step has been validated. ``` This flow protects the project. It also protects your head. You do not need to decide everything in one breath. You need to create the conditions for the next decision to be better. ## A bad prompt ```txt Declared step: diagnosis. Do the diagnosis. Then, in the same task, create the plan and implement everything needed to solve the entire project. ``` This request opens too many doors. The agent will have to diagnose, decide, and execute at the same time. It may look productive at first. But the cost appears later, when every adjustment requires undoing choices that were never really decided. ## A better prompt ```txt Step: diagnosis. Read AGENTS.md and docs/convencoes-conteudo.md. Do only the diagnosis for publishing a new post. Do not plan the implementation. Do not edit files. List the context found, risks, questions, and suggested next steps. ``` This request has boundaries. It separates reading from decision. It separates decision from execution. It prevents a good idea from becoming an automatic change before human review. That is how the agent works better. Not through total freedom. Through enough direction. ## The principle Context is the difference between asking for help and directing work. Skills should enter when they serve the current cycle. Conversations should be small enough to be understood. Tasks should be small enough to be validated. Diagnosis, planning, and implementation should be separated. Always in sequence. Never in the same prompt. The project should carry its own memory. Vibe coding is not letting the machine run. It is creating an environment where it runs in the right direction.