Skip to content
The AI Agent Factory

Appendix: versions and pull requests

Approved by
Panaversity ·
18 min read

You can skip this page on your first day. Read it before you share your work with a team. It is for anyone who writes with Claude: notes, policies, reports or book chapters, not only code. The files on this page are markdown files. If markdown is new to you, read Chapter 0.2, Markdown first.

Why AI raises the stakes

Working with AI is different from working with a colleague, in four ways:

  • Speed. Claude can rewrite a long report in minutes. That is useful, but a mistake spreads just as fast.
  • Confidence. AI can present a wrong number, a deleted paragraph or a rule it invented as calmly as a right one.
  • Invisibility. If AI edits the official copy directly, you cannot easily see what changed. You would have to read it all again.
  • Variation. AI picks each word with some chance, so the same request can come back different each time, as Chapter 0.1 explains. A request that gave a good result last week does not promise a good result today, and a rerun can quietly change parts you already checked. So you cannot trust the request. You check each result.

Most apps keep a history, so you can go back. A pull request adds two things: you see only what changed in this run, and the change waits for a person's yes before it becomes official.

Claude did the work. Who sends it?

Where the work happens explains that Claude, on the desk on your computer, cannot push your work to GitHub: "You do that from your own computer."1 At first this looks like a nuisance. It is really a gate. Claude can write your files. It cannot put them in the copy your team shares. A person must do that. On this page, Claude does not even save the versions: you do, after you have read what changed.

So two questions follow. Who decides what reaches the shared copy? And how would anyone know that they checked it first? This page answers both.

Eight words

  • Repository. A folder whose history git keeps. Every saved version of every file stays in it.
  • Main. The official, approved version of the files. This is the copy everyone should trust.
  • Commit. A save point, like the save points in a game. Each commit records which files changed, a one-line reason, who made it and when.
  • Branch. A draft copy for one piece of work. The changes go on a branch, so main stays as it was until someone approves.
  • Push. Sending your commits to the shared copy online, on GitHub. The first push of a new branch is called publishing the branch.
  • Pull request. A request to add a branch to main. It shows exactly which lines changed, and it is where people comment and approve.
  • Review. A person reads the changes in the pull request, then approves them or asks for fixes.
  • Merge. Adding the approved branch to main.

One change, from start to finish

At 10:00 you open GitHub Desktop and make a new branch, add-checklist, from Current Branch, then New Branch.2 Then you open the Claude app. Your team-notes folder is connected, and it is a repository. You ask:

Write payment-run-checklist.md as a short markdown checklist, and add one line to README.md that links to it. Do not commit or push. Suggest a one-line commit message.

At 10:03 Claude reports the two files and suggests "Add payment-run checklist".

At 10:05 you go back to GitHub Desktop. Its Changes tab shows the two files: the new checklist, with every line in green because every line is new, and README.md, with one added line.3 You read both. This is the moment that matters. Then you type Claude's suggested message in the Summary box and click Commit to add-checklist. The commit carries your name, because you read it and saved it.

Then you click Publish branch, which sends the new branch to GitHub.2 You click Preview Pull Request to see all the changes once more, then Create Pull Request, and GitHub Desktop opens the form on github.com in your browser.4 You give it a title and open it.

At 11:00 a colleague opens the pull request and reads the same two files. They leave a comment on one line of the checklist: "Say who approves, not just 'someone'."5 You ask Claude to fix that line. The Changes tab shows the one changed line. You read it, commit it, and click Push origin. The pull request now shows the fix, under the comment that asked for it.

At 11:30 your colleague approves and merges. The checklist is now in main.

Who does what

WhoWhereWhat they doWhat it leaves behind
ClaudeThe desk on your computerWrites the files, suggests a commit messageChanged files in your folder
YouGitHub DesktopMake the branch, read the changes, commit, publish, open the pull requestCommits and a pull request, under your name
A colleaguegithub.comReads the changes, approves, mergesThe approval, with a name and a time

With one setting, nothing reaches the shared copy without two people's yes: yours when you commit and publish, and your colleague's when they merge. That setting is a rule on the main copy that requires an approval before any merge (step 6 below). Without it, the second yes is a habit your team keeps, not a rule GitHub enforces. Either way, everything is recorded. Months later, anyone can open the pull request and see what changed, why, who wrote it, who approved it and when, without asking anyone.

Without a pull requestWith a pull request
AI makes an editIt changes the official copy, and you hope you noticeIt waits on a branch, where you can inspect it
You check the workYou read everything againYou read only the changed lines
Something is wrong after the mergeYou try to remember what it said beforeYou click Revert, and GitHub opens a new pull request that undoes the change, reviewed like any other6
Someone asks why it changedThere is no recordThe reason, the comments and the approval are kept with the change

A pull request can also run automatic checks before anyone merges, such as spelling, broken links or format. This book's own pull requests run two: one for the format of every page, and one for the plan's consistency.

The gate only works if you read before you commit. Committing without reading is like signing a payment without looking at the amount. This is the person at the end of the Panaversity team's method, now with a place to do the check and a record of their yes.

Setting it up once

  1. Create a free GitHub account at github.com.
  2. Install GitHub Desktop and sign in with that account.
  3. Make a repository. In GitHub Desktop, create a new one, or clone your team's, into a folder on your computer.
  4. Connect that folder to the Claude app, as Set up the apps shows.
  5. Check the name and email your commits will carry, in GitHub Desktop's settings. Every commit shows them. To keep your own email address out of the history, use the private "noreply" address GitHub gives you in your email settings.7
  6. Require an approval. On github.com, open the repository's Settings and add a rule for the main branch: a pull request, with at least one approval, before any merge. By default the rule does not apply to the repository's administrators, so include them too. On a free account the rule works for public repositories only. A private repository needs a paid plan: GitHub Pro, Team or Enterprise.8 If you cannot use the rule, agree as a team that nobody merges their own pull request.

When a zip is enough

If you work alone on a one-off job, a zip file, as the team page describes, is enough. Versions earn their cost when a document matters and changes often, or must show who approved each change: a handbook or policy, standard procedures and checklists, a report built from sources, a team's library of prompts, a book.

So draft and keep your work in markdown, and make the Claude doc, the slides or the PDF at the end. Markdown is plain text, so a pull request shows each changed line. A Word file or a PDF shows only that the file changed. This is the rule from Chapter 0.2: you change the page, never a copy. When the markdown changes, make the copy again. If a reviewer comments in the Claude doc or in Word, bring each accepted change back to the markdown, through a pull request. Some work does not fit in markdown, such as a model with formulas or a designed deck. Keep data as a CSV file, which versions well, and for the rest use the app's own version history.

This page shows the idea, not the whole tool. Chapter 12 uses git with a coding agent in depth, and Chapter 15 shows how to review many changes when an AI writes most of them.

Check yourself

Question 1 / 7

0 answered

Claude has written your files on a branch, on the desk on your computer. Who sends them to GitHub?

  1. Where the work happens gives the rule and its source: the desk on your computer can download from GitHub but cannot upload to it, unless your settings allow all websites.↑
  2. As verified on November 16, 2026, GitHub says a branch you create must be published to make it available for collaboration on GitHub. Managing branches in GitHub Desktop, GitHub.↑↑2
  3. As verified on November 16, 2026, GitHub says GitHub Desktop's Changes tab shows the changes to your files as you make them, and that you write a summary and click Commit to BRANCH. Committing and reviewing changes to your project in GitHub Desktop, GitHub.↑
Owner
Panaversity