How to build a project like VOD Clipper

1 Start from a real, painful problem

Goal: Know who has the problem, how they solve it today, and the hard limits any solution has to live with.

What to do

1. Write down one real person who has the problem and watch how they handle it today.
2. Count the cost of today's way: hours, steps, money, frustration.
3. List the hard limits: file sizes, formats, what the tools can and can't do.
4. Write the problem in two sentences. If you can't, it isn't clear yet.

2 Find the key idea before writing code

Goal: One idea that gets around the hard limits, and a sketch of how data flows.

What to do

1. Ask what the AI actually needs to decide, not what you have.
2. Look for an existing pattern in other fields that solves a similar shape of problem.
3. Draw the data flow in one line, with sizes.

VOD (6 GB) ──► pack (~15 MB) ──► claude.ai ──► cut list (JSON) ──► clips from the original

3 Write a one-page spec

Goal: A single page that you and the assistant can both work from.

What to do

1. Problem and idea, in a few lines each.
2. Inputs and outputs, with real sizes.
3. Architecture and stack, with one reason per choice.
4. What's in the first version and, just as important, what isn't.
5. The contract between the parts (a JSON format, an API).
6. The demo you want to be able to give.

{"clips": [{"id": "c1", "start": "00:41:10", "end": "00:41:52",
            "title": "The comeback", "reason": "Chat explodes, laughter"}]}

↓ One-page spec (.md)

4 Build the thinnest end-to-end version first

Goal: Something ugly that goes all the way from input to output, with tests.

What to do

1. Wire every stage with the simplest thing that works.
2. Test with real tools on generated material (not mocks of the hard part).
3. Only then make each stage good.

5 Direct the assistant with instruction files

Goal: Each piece of work described well enough that the assistant can do it without asking.

What to do

1. One Markdown file per task: context, what to read first, the exact behaviour, tests, and a "Done when" list.
2. A start file with the rules for every run: don't ask, decide and log; commit small steps; never push; never touch the user's data; write what needs you.
3. Tell it to check what already exists before building.

↓ Instruction file (.md)

6 Keep a progress log the assistant writes

Goal: Any run can stop (usage limits, a crash) and the next one picks up exactly where it was.

What to do

1. A PROGRESS.md with "Resume here" at the top, always current.
2. Per task: decisions and why, test results, what's left.
3. A "Needs you" section at the end for anything only you can do.

↓ Progress log (.md)

7 Test with real material, then listen

Goal: Find what only real use shows, and turn each finding into the next instruction file.

What to do

1. Run it on real inputs, end to end, on the target hardware.
2. Watch someone else use it without help.
3. Write each finding as a task with "Done when".

8 Make it trustworthy

Goal: Privacy, security and licences that hold up to someone reading the code.

What to do

1. Privacy by design: keep data local unless sending it is the point.
2. Do a security review of every local server and file operation.
3. List every third-party component and its licence; follow the GPL if you ship GPL code.
4. Use only synthetic or your own material in anything public.

↓ Review checklist (.md)

9 Package it like a product

Goal: Someone who isn't you can install it, start it and recover from errors.

What to do

1. A real installer for the platform people use.
2. A first run that explains itself: empty states, progress, what to do next.
3. An About screen, logs, and an "Open logs folder" button on errors.
4. Test the installed app, not just the dev build.

10 Publish

Goal: A clean public repo, builds anyone can trace to the code, and a page that makes people download.

What to do

1. Scan everything git would publish for secrets, personal paths and names.
2. Add LICENSE, README, CONTRIBUTING, SECURITY and a code of conduct.
3. Build releases in CI from a tag; publish checksums.
4. A fast landing page with the download in the first screen.

Get-FileHash .\VOD-Clipper-Setup.exe -Algorithm SHA256

↓ Release checklist (.md)

11 Keep improving

Goal: The app gets better from use, and you know what's next.

What to do

1. Put feedback inside the product, right after each result.
2. Let the product learn from that feedback where it can.
3. Keep a short public roadmap.

Tools used

Claude Code (writing the code from instruction files), Claude.ai (choosing the moments), Python with FastAPI, ffmpeg, faster-whisper, OpenCV, Next.js, Electron, Playwright (screenshots and end-to-end tests), PyInstaller and electron-builder (packaging), GitHub Actions (releases).

What I'd do differently

1. Decide on packaging early. The Windows app came in task 3; data paths, settings and the local server all had to be reworked for it.
2. Keep test footage synthetic from day one. Screenshots with real people got into git history, and cleaning that is a history rewrite.
3. Put the main use first. The highlight video was the reason for the app but sat behind "clips" until real use showed it.
4. Build the feedback loop in version one. Ratings, notes and revisions came in task 7; earlier results taught the app nothing.
5. Security-review the local server before the first installer, not before publishing.

Templates

• One-page specEN .mdES .md
• Instruction fileEN .mdES .md
• Start rules for unattended runsEN .mdES .md
• Progress logEN .mdES .md
• Review checklistEN .mdES .md
• Release checklistEN .mdES .md