On this page#
Before you install anything#
The correct order is: define repository invariants, restrict permissions, document verification commands, then connect the agent. Settings cannot rescue an undefined operating boundary. If you install first and negotiate safety later, the agent learns that broad access and “the code runs” are acceptable defaults—exactly the wrong contract for production work.
Vibe coding means developing software through natural-language interaction with an AI system. In a real repository, however, prompting is the easy part. The hard part is preserving behavior that may not be visible in the ticket: compatibility guarantees, generated-file rules, migration order, security boundaries, and release assumptions.
An agent also does not “understand the repository” merely because it can read it. A large language model generates likely continuations from context; it does not automatically know which local convention is mandatory or which apparently obsolete branch protects a customer workflow.
That mechanism makes sequence decisive:
| Wrong order | Better order | |---|---| | Grant broad access | Start with the narrowest useful permissions | | Ask for implementation | Require inspection and a plan first | | Let the agent choose validation | Declare exact verification commands | | Review the final diff | Review assumptions before edits | | Keep rules in chat | Commit repository-specific instructions |
The goal of this vibe coding tutorial is not maximum autonomy. It is bounded autonomy: enough freedom to complete a well-scoped task, with repository rules that survive a new chat, a different agent, and a second engineer.
Photo by Boris K. on Pexels.
The steps#
Use the following sequence without skipping ahead. Each step removes a different failure mode: undocumented assumptions, unnecessary access, uncontrolled scope, false confidence, or unreviewable changes. The order turns an AI coding agent from an improvisational interface into a constrained repository participant whose work can be inspected and handed off.
-
Write down the invariants before naming the task.
This prevents the agent from treating hidden compatibility, security, data, or architectural constraints as optional preferences. -
Define the repository map.
This prevents edits in generated directories, vendored code, fixtures, migrations, or packages owned by another workflow. -
Declare the exact validation commands.
This prevents the agent from substituting a convenient check for the one your repository actually trusts. -
Set permissions to the narrowest task-shaped allowlist.
This prevents an implementation request from silently becoming permission to push, deploy, access secrets, or rewrite unrelated files. -
Require inspection and a proposed file list before editing.
This prevents premature patches based on filenames, partial context, or the first plausible code path. -
Cap the change surface.
This prevents “while I’m here” refactors from obscuring the requested behavior and making rollback harder. -
Make completion evidence explicit.
This prevents “done” from meaning only that code was generated without showing the diff, checks, residual risks, and skipped validation.
The Claude Code documentation explains the product’s controls. Your repository instructions must supply the part a vendor cannot know: what is dangerous here, which commands count as evidence, and where the agent must stop.
A working configuration#
Put the operating contract in a committed repository file, not in one engineer’s prompt history. The configuration below is intentionally conservative and tool-readable. Paste it into the instruction file recognized by your agent, then replace bracketed values with real repository facts before granting write access.
# Agent operating contract
<!-- Names the repository so copied instructions are not applied elsewhere. -->
Repository: [REPOSITORY_NAME]
<!-- Gives the agent one objective instead of general permission to improve code. -->
Objective: Implement only the explicitly requested task.
<!-- Forces evidence gathering before modification. -->
Before editing:
1. Read the nearest relevant source, tests, and repository instructions.
2. State the behavior being changed and the invariants that must remain true.
3. List the files you expect to modify.
4. Stop if the task requires files outside that list.
<!-- Converts hidden engineering assumptions into enforceable boundaries. -->
Invariants:
- Preserve [PUBLIC_API_OR_COMPATIBILITY_RULE].
- Preserve [DATA_OR_SECURITY_RULE].
- Do not change [OUT_OF_SCOPE_SUBSYSTEM].
- Do not edit generated, vendored, or lock files unless the task explicitly requires it.
<!-- Prevents opportunistic cleanup from expanding the review surface. -->
Scope:
- Make the smallest coherent change that satisfies the request.
- Do not rename, reformat, upgrade, or refactor unrelated code.
- Do not add dependencies without explicit approval.
<!-- Defines acceptable evidence instead of letting the agent choose an easy check. -->
Required verification:
1. Run: `[TARGETED_TEST_COMMAND]`
2. Run: `[LINT_OR_TYPECHECK_COMMAND]`
3. Run: `[BROADER_CHECK_COMMAND]` only when the change affects shared behavior.
4. Report any command that could not run; never imply that it passed.
<!-- Separates local implementation authority from external side effects. -->
Permissions:
- May read repository files needed for the stated task.
- May edit only the proposed file list.
- May run only the verification commands above and read-only inspection commands.
- Must not read secrets or environment files.
- Must not push, deploy, publish, merge, delete data, or change remote state.
<!-- Makes the result reviewable by someone who did not share the chat. -->
Completion report:
- Summarize the behavioral change.
- List modified files.
- List verification commands and outcomes.
- Identify remaining risks, assumptions, and manual checks.
- Show the final diff for review.Every line has a job. The header prevents accidental reuse; the objective limits authority; “before editing” creates a checkpoint; invariants protect non-obvious behavior; scope keeps the diff reversible; verification defines proof; permissions separate coding from external actions; and the completion report makes handoff possible.
If your team wants these controls packaged with reusable prompts and review gates, the PairFoundry Agent Operating Kit is the direct next step. The key is still the same: adapt the contract to the repository instead of pasting a generic personality prompt.
Photo by Digital Buggu on Pexels.
What to skip#
Skip any tutorial step that increases ceremony without narrowing behavior, permissions, or evidence. A long prompt is not automatically a strong operating contract. If a step does not protect an invariant, reduce the change surface, improve verification, or clarify handoff, it is probably decoration rather than engineering control.
Do not spend time on:
- A grand agent persona. “Act as a senior engineer” does not identify the repository’s compatibility rules.
- A giant global instruction file. Global preferences cannot safely replace local commands, ownership boundaries, and generated-file rules.
- Granting every tool up front. Convenience is not a reason to permit pushes, deployments, secret access, or arbitrary shell execution.
- Teaching the entire architecture before one task. Give the agent the relevant map and require targeted inspection.
- Automating commits immediately. First establish that the diff and verification report are consistently reviewable.
- Adding multiple agents on day one. More agents multiply coordination and conflicting assumptions before the operating contract is stable.
- Copying vendor examples unchanged. Official examples demonstrate features; they do not encode your repository’s hazards.
- Treating a passing test as complete proof. A targeted test can pass while an API, migration, or integration invariant breaks elsewhere.
For narrower lessons before adopting a full workflow, use the free PairFoundry foundations track. The broader agent setup collection is useful when the problem is repository integration rather than prompting.
First real task#
Your first task should be a small, existing defect with a reproducible failure, nearby tests, and no deployment or schema change. That shape exposes whether the agent can inspect, constrain, edit, verify, and report correctly. Do not begin with a rewrite, dependency migration, architectural cleanup, or vague performance request.
A good first request looks like this:
Investigate the failing behavior described in [ISSUE OR TEST].
Before editing, identify the relevant invariant, explain the likely cause,
and list the files you propose to change. Make the smallest coherent fix.
Run the repository-defined targeted checks, report their exact outcomes,
and show the final diff. Stop before any remote action.This task tests the workflow rather than the agent’s ability to produce lots of code. A second engineer should be able to read the committed contract, reproduce the validation, understand why each file changed, and continue without access to the original conversation.
If that handoff fails, do not add more automation. Tighten the repository map, invariants, permissions, or completion report first. Teams comparing more specialized workflows can review the three PairFoundry packs, but no package replaces the need to state what your repository considers safe.
Photo by ThisIsEngineering on Pexels.
Related reading#
- GitHub Copilot CLI install in fifteen minutes, and what to skip
- How to start vibe coding: the order matters more than the settings
FAQ#
How narrow should agent permissions be for normal feature work?#
Allow the reads, edits, and local verification commands required by the named task. Keep secrets, pushes, deployments, publishing, destructive data operations, and unrelated directories outside that boundary. Expand access only when a concrete blocked step justifies it, then review whether the broader permission should remain.
How is this different from following the official setup guide?#
Official documentation explains product capabilities and configuration controls. It cannot define your repository’s invariants, trusted commands, ownership boundaries, or handoff standard. These vibe coding tutorials address that missing operational layer: how to constrain the tool after installation so its output meets a production review bar.
What usually breaks when a second engineer takes over?#
The second engineer lacks assumptions that existed only in the first chat: excluded files, validation choices, accepted risks, and reasons for unusual edits. Commit the operating contract and require a completion report containing changed files, command outcomes, assumptions, and remaining manual checks.
How should I roll back a bad agent change?#
Keep the task surface small, inspect the final diff, and avoid mixing unrelated cleanup into the same change. Revert the bounded patch through your normal version-control workflow, then identify which missing invariant, permission boundary, or verification step allowed the failure before retrying.
When should I not use this workflow?#
Do not delegate a task whose success criteria cannot yet be stated, whose failure could create irreversible external effects, or whose key decisions require unresolved product or architectural judgment. Use the agent for inspection and options first; grant implementation authority only after the boundary is concrete.