HW7: Code Handoff

CMU 15-114: Effective Coding with AI

Before Wed 10/28: design your game (without generating code) and write SPEC.md. Come to class with it ready to commit.
Phase 1 (Wed 10/28, in class): build and document. Final commit before you leave the room.
Phase 2 (after Wednesday's class): finish the game given to you. Due Sun 11/1 at 8:00 PM
Time Estimate: ~4 hours total (~30 minutes on the spec, one class period building, ~2 hours on Phase 2)
Deliverables: Two GitHub repositories, each with code, SPEC.md, README.md, and a prompt log, plus one Google form submission
Language and tools: Your choice; we recommend Python or Javascript.

Assignment Overview

The premise: Design a game you'd truly like to play and that isn't something that will be perfect in one or two prompts. Write down what it would take to build it, and build the first hour yourself. Then we'll hand it to a classmate who will spend two hours trying to deliver it without talking to you. You'll do the same for someone else, and after the deadline, you get to play what became of your idea.

Why This Matters: In the workplace, you'll join teams with existing codebases, inherit projects, and hand your own work to whoever comes next. Writing work someone else can continue (and picking up work someone else started) are key skills in software development. This is an informal chance to start building some of those skills.

This assignment also measures your ability to communicate through your repo. If what you get back isn't the game you imagined, try to understand whether the gap was in your spec, your code, or your documentation.

Learning Objectives:

You don't get to explain anything directly. All the important information needs to live in the repository instead. Your partner (chosen by us) will get your spec, your code, your README, and your prompt log, and anything else you've committed.
If you have to miss Monday or Wednesday, email Mike and Taha as soon as you know. We'll need to make sure someone still gets your code and you get theirs.

Your Game

Make any game you want, as long as it's not too basic and someone would enjoy playing it. Figuring out what the game is counts as part of the work.

Scope it to about three hours of building

You get about 45 minutes of coding in Phase 1, and your partner gets about two hours in Phase 2. So specify a game that two people who have never spoken could finish in about three hours of total implementation effort.

Setting a good scope can be challenging. Aim for small, specific, and complete so that they have both direction and a chance to finish it on time.

If you're stuck on an idea

Here are some suggestions:

Try not to just clone something that exists. If you build Pac-Man, your partner can infer most of what you want without reading anything you wrote, and it's easy to one-shot in any case. Your spec needs to be clear about what makes your version different.

Phase 1: Spec, Build, Document

Write the spec on your own time before Wednesday. This is necessary so that you can start and finish your limited build time inside Wednesday's class period, ending with a final commit before you leave. Your partner will get your code that evening, so there's no working on it afterward.

Step 1: Before Wednesday's class, write SPEC.md (about 30 minutes)

Design your game and write the spec at home. Come to class on Wednesday 10/28 with it ready to commit. Showing up undecided costs you your limited phase 1 coding time and may result in a lower grade / sad partner.

Your first commit must contain SPEC.md and no code at all. We'll check with git log. This forces the design decisions to the front and leaves a record that you thought before you typed.

Your spec should contain:

Don't let AI decide what should be in your spec. We know you really really want to do this, but it defeats the purpose of writing a spec for your creative vision, and AI will create constraints that you don't care about and may make life hard for your partner.
Your code will hint at where the game is going, and that's fine. Clean, well-named code that telegraphs its direction is a feature. What your partner can't get from the code is the full picture: everything you wanted but didn't reach, what counts as finished, and which parts matter most. That's what the spec is for.

Step 2: In class on Wednesday, build and document

Basic outline:

That should allow you to create a foundation but not a finished game. Spend it on structure and the core loop so your partner inherits something that runs and can be extended. They inherit your architecture whether it's good or not, and an unstructured thousand-line file pushes their AI toward a rewrite.

Actually reserve those last minutes for documentation. Undocumented code is bad for your partner, since they can't ask you what you meant and aren't allowed to radically change what you wrote.

Step 3: What to leave behind

README.md

This serves both someone who wants to run the game and the developer taking over. Include:

prompt_log.md

Which AI model(s) and tool(s) you used, and your important, non-trivial prompts verbatim rather than AI-written summaries.

Here it does double duty: your partner can read how the code got this way, which is often faster than reverse-engineering it. Write it with them in mind.

Everything in your documentation has to be true. Last semester's inheritors complained most about documentation describing features that didn't exist. Your partner plans their two hours around your README, so if something is broken, say so. Nobody is grading you on how much you finished in an hour.

Then make your final commit, push, and leave the repository alone until after HW7 is due.

Phase 2: Inherit and Deliver (about 2 hours)

Soon after Wednesday's class, we'll email you a link to a different student's Phase 1 repository. You have until Sunday 11/1 at 8:00 PM and about two hours of focused work.

Your job is to deliver the game their spec describes, as far as you can get, on the foundation they left you. Try to spend roughly two hours to make it as good as possible (and it's ok if you go a little over, but keep it reasonable).

You must not contact the original author. Everything you need must come from the repository.

Step 0: Set up your own repo, with their code as the first commit

You'll work in your own new repository rather than theirs, so nobody has to manage GitHub collaborator permissions. Your first commit must be their unmodified code, exactly as you received it. That baseline is how we (and you) can see what you actually changed, so do it before you open a single file.

Using GitHub Desktop

  1. On their repo's GitHub page, click Code → Download ZIP and unzip it somewhere sensible. Downloading rather than cloning means you start with a clean history.
  2. In GitHub Desktop, choose File → Add local repository and pick that folder. Desktop will tell you it isn't a Git repository and offer to create a repository there. Do that.
  3. All of their files will appear as changes to commit. Commit them with a message like Initial commit: unmodified code as received. Do this before you change anything.
  4. Click Publish repository, and uncheck Keep this code private so we can see it.
  5. Now work normally, committing as you go.

Alternate method using the command line

git clone THEIR-REPO-URL inherited-game
cd inherited-game
rm -rf .git                 # detach from their history
git init
git add .
git commit -m "Initial commit: unmodified code as received"
git remote add origin YOUR-NEW-EMPTY-REPO-URL
git push -u origin main

Either way, you end up with a repository you own whose first commit is their work as handed to you. Everything after that is yours.

A suggested two hours

Required: report against the acceptance criteria

Your README must walk the author's acceptance criteria one by one, marking each met, partially met, or not met, with a sentence each. Say why if you skipped one, and say so if one didn't make sense, since that's useful to the person who wrote it.

This is the most important deliverable in Phase 2.

Required: the handoff report

Add HANDOFF_REPORT.md to your Phase 2 repo: a short, honest account of what it was like to inherit this project. This can be short, but DO NOT USE AI TO WRITE THIS.

These reports go back to their authors, along with the finished game. After the deadline we'll route each report to the student who wrote the spec, and we'll discuss the patterns in class. Be honest, specific, and kind: write the report you'd want to receive.

Preserving Their Work

You must keep at least 75% of the original work. You may reorganize, refactor, extend, and fix. You may not quietly discard the foundation and rebuild it in your own image. We compare your final submission against the initial commit of what you received.

Note that we said work, not lines. Some refactoring is ok. Splitting a 400-line file into four sensible modules is fine for example. What you can't do is throw out their logic and write your own. If you restructure anything substantial, say so in your README and say why.

The spirit of the rule: work inside the other person's design. If they used a class, keep using the class. If they named things a certain way, match it.

Your AI will try to violate this rule. Especially if you give it a vague prompt, it will often rewrite whole files, rename things to its own preferences, and discard work it didn't understand. Ask for small, scoped changes, read every diff, and revert anything it rewrote that you didn't ask it to. (Remember to commit frequently so that this is possible.)

What to Submit

Two separate public GitHub repositories.

Repository 1: your Phase 1 project

You submit this one by handing us the link at the start of Wednesday's class.

Repository 2: the project you inherited

These are all separate files. The spec, the README, the handoff report, and the prompt log each have a different audience and a different job. Don't merge them, and don't paste one into the bottom of another.

Google form: Submit both repository links here before Sunday 11/1 at 8:00 PM. We will have collected your Phase 1 link in class, but include it again so both ends of your work are recorded in one place.

Optional, and encouraged if the result is good: if the game you inherited ends up genuinely playable, put it on your portfolio with credit to both authors. "Someone else designed it, I built it from their spec, here's what I added" makes an unusual and compelling portfolio entry.

Grading

Graded on good-faith effort and on the quality of your in-repo communication, not on whether either game ends up finished.

Phase 1 (50 points)

We're looking for a clear enough spec and foundation for a stranger to complete. The acceptance criteria should be specific, checkable, and scoped to the time available. Attend to the code's clarity and structure, and write an accurate README (e.g. "collision detection is broken and here's what I think is wrong" is a very valuable inclusion).

Phase 2 (50 points)

We're looking for evidence that you read the spec, aimed at it, worked inside someone else's design, and reported back usefully. We'll read the acceptance criteria walkthrough and the handoff report most closely. Your commit history should show a sequence of considered changes rather than one large diff.

We know the starting points won't be equal. Some of you will inherit a clear spec and a clean foundation, and others will get a total mess. We take that into account, and a thoughtful report explaining why a project was hard to pick up is itself a strong Phase 2 submission.

On the 75% rule: discarding more than a quarter of the original work rather than building on it will result in a much lower grade. Refactoring that keeps the logic intact isn't discarding, so don't avoid cleaning something up out of fear of the diff. Just document the restructure.

After the deadline

You'll get back your own game in its finished state, along with the handoff report written about it. Play it, read the report, and consider whether the gap between what you imagined and what you received was in the code, the spec, or the documentation.

Tips

Writing a spec someone can build from

Phase 1: building a foundation someone can continue

Phase 2: delivering someone else's game

Using AI well here

Questions? Ask on Ed, attend office hours, or email the instructor. Consult the course AI usage and collaboration policies on the course homepage.