Same fundamentals as any other software project — an agent's prompts, tool definitions, and eval datasets all belong in version control alongside the code.
Core concepts
- Git: Non-negotiable baseline for any real project. Git Docs
- GitHub: Hosting, pull requests, and — increasingly — the place MCP servers and agent skills get distributed and discovered.
- Versioning prompts and evals, not just code: A prompt change is a behavior change — treat it with the same review discipline as a code change, ideally with an eval run attached to the PR.
What Is It?
Git and GitHub track code, prompts, tool configs, and evaluation datasets together.
Branches and PRs let you experiment with agent behavior without breaking production defaults.
Tags mark releases when tool manifests or safety policies change.
Why Should I Care?
Regulators and customers ask what changed when an agent misbehaved — git history is the audit trail.
Collaborative agent work without VCS devolves into pasted Google Docs.
Real World Analogy
Git for agents is time travel for your team's brain — prompts, tool schemas, and eval sets are just source files with history.
Visual Mental Model
repo
|-- prompts/
|-- tools/
|-- evals/
PR reviewBeginner Explanation
Use GitHub like any software project. Diff prompt changes, tag releases, and review tool definition PRs with the same seriousness as API changes.
Smallest Possible Example
TRACK = ["prompts", "tools", "evals"]
print("version in git:", ", ".join(TRACK))Common Mistakes
❌ Storing API keys in committed .env files.
Use secrets managers and .env.example templates only.
❌ One-line commit messages for prompt overhauls.
Explain intent so reviewers catch regressions.
❌ No branch protection on main.
Broken tool JSON should not ship without review.
Real Project Example
GitHub Copilot Workspace flows assume git-native agent configs.
Teams at Stripe-scale treat prompt templates as code-owned assets.
Build This Mini Project
Move a prompt and a five-case eval JSON into a repo; open a PR that changes the prompt and show eval diff in description.
Interview Question
What should be versioned besides application code?
System prompts, tool schemas, retrieval configs, eval datasets, and deployment manifests — anything that changes runtime behavior.
Key Takeaways
- Prompts are code — diff them.
- Never commit secrets.
- PRs for behavior changes.
- Tags for releases with policy impact.
Resources
YouTube learning
Core concepts from video walkthroughs:
The 60-second story
Two people edit the specials board. One of them changes “no refunds after 14 days” to “be generous.” Nothing in the Python changed. The next morning the agent refunds a six-month-old order and the git history of the code looks innocent. The behavior lived in a prompt, and the prompt lived in a doc, a dashboard, or someone’s head.
Git is the camera on the board. It is not a personality. It is how you answer “what did the board say on Tuesday?” GitHub is the shop window: pull requests, review, and increasingly the shelf where MCP servers and agent skills get shared. You still need the camera even if the window is pretty.
A prompt change is a behavior change. Review it like code. Better: run the practice exam, the eval set, on the pull request. A green test suite that never loads the prompt is a camera pointed at the wrong wall. Tool schemas and the eval questions belong in the repo too. If the exam lives only in a product UI, it will drift from the board, and you will argue from memory.
Map the board.
- The prompt is a special that customers feel.
- Git is the camera.
- A pull request is asking someone else to read the special before it is served.
- An eval on the PR is tasting the soup from the new special.
- Tool definitions are part of the menu, not a side sticky note.
- “We changed it in the dashboard” is a special with no camera.
prompts/refund.md
evals/refund_cases.jsonl
src/agent.pySame commit. When the refund behavior moves, the diff shows the sentence that moved it. That is the whole practice.
Version control was not invented for agents, which is why people forget to aim it at the parts that actually change behavior. Agents made prompts executable. Executable text without history is a rumor. The fix is dull: files, review, and a check that fails when the new wording fails the old cases.
Mental model: the specials board is code. If a guest can feel it, the camera should see it. A model swap belongs in that diff too, because the board plus a different cook is a different restaurant.
You can explain the page if you would block a prompt edit that has no review, and if you know where the eval cases live. If the specials board can change a refund and git does not show it, the camera is pointed at the wrong wall.
