~10 min · vibe coding stand

Prepare a codebase for handover with AI

You just inherited an under-documented segmentation tool. Use an AI coding agent to write a useful README.md and a continuing-work HANDOVER.md.

Get the code

Clone on your laptop, then open the folder in Cursor / your AI coding tool. 

git clone https://github.com/VibeCodingMICCAI/stand2_readme-handover.git

If links still say YOUR_USER, the facilitator needs to publish the repo and update the page config.

Use this repository. Clone / download the demo above, open it in your AI coding tool, then run the prompts on that codebase. The starter README.md is intentionally incomplete — your job is to improve it from evidence in the code.
Example target (optional peek)

You do not need to match this word-for-word. It shows the kind of docs a good pass should produce.

Example README.md Example HANDOVER.md

Tip: try generating first, then compare. Spoiler if you open these before asking the AI.

Do this

  1. 1

    Inspect (1–2 min)

    Can you tell what the tool does, how to run it, how to test it, and what is unfinished?

  2. 2

    Generate README.md

    Ask your AI agent to inspect the repo and improve the README from evidence only.

    You are preparing this repository for handover to another developer or AI coding agent.
Inspect the repository carefully before making any changes.
Create or update README.md so that someone unfamiliar with the project can understand and run it without asking the original developer for help.
Include:
- what the project does
- the main workflow
- expected inputs and outputs
- environment setup and dependencies
- exact commands to run the project
- a minimal working example
- important files and repository structure
- how to test or verify that it works
- known limitations or unsupported cases
Important:
- Base everything on evidence from the repository.
- Do not invent commands, behaviour, or design decisions.
- If something cannot be determined, mark it as "TODO: clarify".
- Prefer exact filenames, paths and commands.
- Keep the README concise and practical.
  3. 3

    Review · inspect → generate → verify

    Did it use real commands? Invent anything? Find limitations? Mark unknowns instead of guessing?

  4. 4

    Create HANDOVER.md

    README explains the project. Handover explains where development currently stands.

    You are handing this repository to another developer or AI coding agent.
Inspect the repository and current implementation.
Create HANDOVER.md to help the next person continue development from the current state.
Include:
1. Current status
   - what currently works
   - what appears incomplete
2. Known issues
   - bugs
   - uncertainties
   - technical debt
   - unresolved questions
3. Next tasks
   - concrete tasks the next developer could continue with
4. Important decisions and constraints
   - implementation choices that should not be accidentally reversed
   - behaviours or interfaces that should be preserved
5. Important files
   - files most relevant to continued development
6. Verification
   - commands/tests to run before and after making changes
Rules:
- Do not repeat general information already covered by README.md.
- Do not invent project history.
- Clearly mark uncertain information as "Needs confirmation".
- Use exact file paths, commands and test names where possible.
- Keep it concise and actionable.
  5. 5

    Test the handover

    Open a fresh chat (or swap laptops) and ask the next agent to answer from the docs only.

    You have just inherited this repository.
Do not make any changes yet.
Read README.md and HANDOVER.md, then tell me:
1. What does this project do?
2. How do I run it?
3. How do I verify that it works?
4. What is the current development status?
5. What should I work on next?
6. What important constraints should I avoid breaking?
7. What information is still missing or ambiguous?
  6. 6

    Close the loop

    Before finishing, update HANDOVER.md with what changed and what should happen next.

    Before finishing this session, update HANDOVER.md.
Summarise:
- what you changed,
- what now works,
- what remains unresolved,
- important decisions made,
- files modified,
- what should happen next,
- and how the next developer or AI agent can verify the current state.
Do not repeat general project information already in README.md.
Keep it concise and actionable.