Team workflow

Lab setup

First, make sure you have completed the initial setup.

If you are part of a course

  1. Open Terminal. Run the update command to make sure you have the latest code.
    $ mwc update
  2. Move to this lab's directory.
    $ cd ~/Desktop/making_with_code/pilot/labs/lab_team_workflow
    

If you are working on your own

  1. Move to your MWC directory.
    $ cd ~/Desktop/making_with_code
    
  2. Get a copy of this lab's materials.
    git clone https://git.makingwithcode.org/founders-studio/lab_team_workflow.git

So far, you've mostly worked in your own repository. Real software is built by teams, and increasingly by teams of people and AI agents, all changing the same code at the same time. In this lab, you will learn how teams keep that from turning into chaos: working on branches, proposing changes as pull requests, delegating well-defined tasks to agents, and reviewing every change before it's merged, no matter who (or what) wrote it.

By the end of this lab, you will be able to:

The team project

๐Ÿ‘ Your team shares a repository containing a small web app, studio_board, a message board for the studio. Read README.md to see what it does and how to run it, then start it.

$ python app.py

๐Ÿ‘ Look at the list of issues on the repository's page on git.makingwithcode.org. Each issue describes a bug or a feature request.

๐Ÿ’ป As a team, divide up the issues so that each person has one.

Branches

If everyone edits main at the same time, changes collide and nobody can tell what's working. Instead, each person works on a branch: a separate line of development that starts from main and can be merged back later.

๐Ÿ’ป Create a branch for your issue, named after it.

$ git switch -c fix-empty-posts

๐Ÿ’ป Make your change (you'll use an agent in the next section; for now, make a small change by hand), commit it, and push the branch.

$ git push -u origin fix-empty-posts

Pull requests

A pull request (PR) is a proposal to merge a branch into main. It shows exactly what changed, and gives teammates a place to review and discuss the change before it's merged.

๐Ÿ’ป On the repository's page, open a pull request for your branch. Link it to the issue it addresses.

๐Ÿ’ป Have a teammate review and approve your PR, then merge it.

๐Ÿ’ป Now everyone else needs your change. Switch back to main and pull.

$ git switch main
$ git pull

Merge conflicts

When two people change the same lines on different branches, git can't decide which version to keep. This is a merge conflict.

๐Ÿ’ป Create a conflict on purpose. Two teammates should each make a branch and change the same line of templates/index.html in different ways. Merge the first one. Then try to merge the second.

$ git switch second-branch
$ git merge main
CONFLICT (content): Merge conflict in templates/index.html

๐Ÿ‘ Open the file. Git has marked both versions:

<<<<<<< HEAD
<h1>Studio Board</h1>
=======
<h1>Founders Studio Message Board</h1>
>>>>>>> main

๐Ÿ’ป Decide together what the line should be, edit the file to keep only that version (removing the markers), then commit.

Delegating to agents

Agents can work on issues too. But an agent can only do as well as the task it's given.

๐Ÿ’ป Pick an open issue. Try delegating it to Claude Code twice, on two different branches: once with a vague description ("fix the posts thing") and once with a precise one, including:

๐Ÿ‘ Compare the two results with git diff main. Which is closer to what you wanted? Which changed more than it needed to?

Instructions you'd give every agent working in a repository belong in a project instructions file. Claude Code reads CLAUDE.md at the start of every session.

๐Ÿ’ป As a team, write CLAUDE.md for studio_board: what the project is, how to run it and its tests, coding conventions, and rules (for example, "never push to main," or "always run the tests before committing"). Commit it through a PR.

Review and verification

Every change needs review before it's merged, and changes written by agents need it most: agents produce plausible-looking code very quickly, and it's easy to approve without really checking.

When you review a PR:

$ git fetch
$ git switch agent-fix-empty-posts
$ python -m pytest
$ python app.py

๐Ÿ’ป Your mentor has opened a PR on your team's repository that contains a subtle bug. Review it. Can your team find the bug before anyone merges it?

Team norms

๐Ÿ’ป As a team, write NORMS.md, answering:

Deliverables

๐Ÿ’ป Answer these questions in questions.md:

  1. What made the difference between your vague and precise task descriptions?
  2. What did you check when reviewing the seeded PR? What would you check next time?
  3. Why might an agent's PR need more careful review than a teammate's?