Shipping a real project with an agent

Taking a small real project from spec to deployment with an agent: scope, a written spec, vertical slices, CI as the gate, one pull request per slice, honest disclosure and a write-up.

Scoping a project for an agent

Also called MVP, minimum viable product

What: Choosing a project small enough to finish in a few weeks, with a real user, clear features and a way to test each one.
Why: Agents make starting easy and finishing hard. A tight scope is what turns a demo into something shipped.
Example: Good: a booking page for one real tutor, with slots, a form and email confirmation. Too big: "a platform for all tutors in the country".

A written spec

Also called SPEC.md, PRD, plan file

What: A short document in the repository listing users, features, data, out-of-scope items and how each feature will be verified, which you and the agent both work from.
Why: It survives cleared context and new sessions, keeps the agent on track, and becomes the backbone of your write-up.

MARKDOWN

# SPEC.md
## Users: one tutor, their students
## Features (each with "done when")
1. Tutor sets weekly slots. Done when: tests pass
2. Student books a slot. Done when: e2e test passes
## Out of scope: payments, mobile app
## Checks: npm test, npx tsc --noEmit, npm run e2e

Vertical slices

Also called thin slice, end-to-end increment

What: Building one feature at a time through every layer, database, API, UI and tests, so each slice works end to end before the next begins.
Why: Slices give the agent small, testable tasks and give you something working at every step instead of half-built layers.

CI as the gate

Also called continuous integration, required checks

What: Automated checks that run on every push or pull request, tests, type check, lint and security scans, and must pass before anything merges.
Why: CI checks every change the same way, whoever or whatever wrote it. It is the backstop for the reviews you rushed.

YAML

# .github/workflows/ci.yml (excerpt)
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test && npx tsc --noEmit

One pull request per slice

Also called small PR, pull request

What: Opening a separate, small pull request for each slice, with a description of what changed, how it was tested and what the agent did.
Why: Small pull requests get real reviews. They also leave a readable history that shows how you worked, which is what a portfolio reviewer looks at.

Watch out

One giant "initial commit" containing the whole project, which hides every decision you made.

Disclosing AI use

Also called AI attribution, Co-authored-by

What: Stating honestly where and how you used AI tools, in the README, pull request descriptions or commit trailers, and following any required format.
Why: Honesty protects you in courses and jobs, and a clear account of how you steered and checked the tool is itself evidence of skill.
Example: README: "Built with Claude Code for scaffolding and tests. I wrote the booking logic and all migrations, and reviewed every diff."

The project write-up

Also called case study, retrospective, postmortem

What: A short document explaining the problem, your design, what the agent did, what you changed or rejected and why, bugs you caught, and what you would do differently.
Why: Anyone can generate a repository. The write-up shows the judgment behind it, which is what employers want to see.

Watch out

Listing features only. Include the mistakes you caught and the decisions you made.

Go deeper