Team workflow
Lab setup
First, make sure you have completed the initial setup.
If you are part of a course
-
Open Terminal. Run the update command to make sure you have the latest code.
$ mwc update -
Move to this lab's directory.
$ cd ~/Desktop/making_with_code/pilot/labs/lab_team_workflow
If you are working on your own
-
Move to your MWC directory.
$ cd ~/Desktop/making_with_code -
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:
- Work on a branch, and propose changes with a pull request.
- Resolve a merge conflict.
- Write a task description that an agent can carry out well, and project instructions that guide all agents working in a repository.
- Review and verify a pull request, especially one written by an agent.
- Agree on team norms for AI use.
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-postsPull 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 pullMerge 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:
- What should change, and what shouldn't.
- How to tell when it's done: acceptance criteria, such as "posting an empty message shows an error, and the existing tests still pass."
- Context: which files are involved, and any constraints.
๐ 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:
- Read the diff. Do you understand every change? Is anything changed that shouldn't be?
- Run the tests. Do they pass? Are there tests for the new behavior?
- Try it by hand. Does it actually do what the issue asked?
$ 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:
- What kinds of tasks do we delegate to agents, and what do we keep for ourselves?
- Who reviews each PR, and what must a reviewer check before approving?
- How do we note when a change was written mostly by an agent?
Deliverables
๐ป Answer these questions in questions.md:
- What made the difference between your vague and precise task descriptions?
- What did you check when reviewing the seeded PR? What would you check next time?
- Why might an agent's PR need more careful review than a teammate's?
- Note: The starter repo has the
studio_boardFlask app, tests, andISSUES.md, which lists six issues for mentors to open on each team's shared repository. Mentors still need to create the team repositories and the seeded-bug PR. Gitea supports issues and pull requests, butmwccreates one repository per student, not per team.