Vibe coding with Claude Code course Β· Module 11: Spotify clone

A Checklist Before Publishing

8 min read
In this lesson8

Sea Shanty Sounds is the last clone of this part of the course. Along the way you collected a dozen habits: tests and build as proof, reading the diff, /code-review, /security-review, deny rules, .env.example, a preview before production. Each of them has already saved some voyage. The trouble is that before publishing you have to remember all of them at once, and haste always wipes out of memory the one you needed. Pilots have a simple answer: a checklist they read before every takeoff, even if they have flown for twenty years. You will write yours into the project, so that Claude goes through it the same way every time.

What you will learn

  • decide where in the project to write a procedure: in CLAUDE.md, in rules or in a skill;
  • split the list into points that Claude checks and points left for the captain;
  • read the result of the list as a report, not as a stamp;
  • know what no list will catch.

Where to write the list

You have three places. CLAUDE.md from lesson 1_7 loads into every conversation, so ten points about publishing would take attention at every fix of a button. Rules in .claude/rules/ load when Claude works on files that match the paths in the rule's header, and publishing is not about particular files. A skill from lesson 6_1 fits best: according to the documentation only its description stays in context all the time, and the full text loads only on use.

That leaves the question of disable-model-invocation. For /deploy it was mandatory, because that skill deploys. The list deploys nothing and fixes nothing, so you do not set it here: Claude may reach for it on its own when you say "prepare the publication". Even then the deployment still needs your /deploy.

Request for Claude Code

You order the skill like any other file: you say where it lives, what it checks and what it must not do, and Claude writes it and shows it to you to read.

Save a /pre-publish skill in .claude/skills/. The skill deploys
nothing and fixes nothing, it only checks and ends with a table:
point, command, result, PASS or FAIL. Part one is the points you
will check with commands: the commands from CLAUDE.md, a clean
git status, .env files in the repository, variable names in
.env.example, the rules in .claude/settings.json, next.config.ts,
changed test files. Part two is a list for me to tick off: reviews,
/verify, keys in the build, the preview, the promotion and the
way back.

What Claude wrote: the part for Claude

Open .claude/skills/pre-publish/SKILL.md in Cursor. The header has only a name and a description, because it is the description that tells Claude when to reach for the skill:

---
name: pre-publish
description: A checklist before publishing Sea Shanty Sounds. Use when the captain wants to deploy a preview or production.
---

Below the header stands the rule "Deploy nothing and fix nothing", and then seven points for Claude:

1. The check commands from CLAUDE.md: tests, lint, types, build. Each ends in success.
2. git status --short shows nothing. If it shows something, stop.
3. git ls-files | grep -E '(^|/)\.env' shows only .env.example.
4. Every name from grep -rhoE 'process\.env\.[A-Z0-9_]+' app components lib stands in .env.example. A variable with a key has no NEXT_PUBLIC_ prefix.
5. .claude/settings.json has deny rules for .env and .env.* and ask rules for vercel and git push.
6. next.config.ts has no images.domains, and every image address in the code matches images.remotePatterns.
7. List the test files changed in recent commits (git log --oneline --stat -5 -- '*.test.ts' '*.test.tsx') so that the captain reads them.

Each point is a habit from earlier lessons, this time with a command you can check. Point 1 is the handrail from lesson 10_4. Point 3 makes sure no file with variable values slips into Git, and point 4 compares the names in the code with the .env.example from lesson 10_5. git ls-files lists the files tracked by Git, and grep -o cuts only the variable names out of the code. Point 5 checks the locks from lessons 8_4 and 10_5, point 6 the images, and point 7 does not judge but puts the changes in tests in front of your eyes, because a weakened test looks green in a report.

We ran the commands from the list on the project after lesson 10_5. Tests: Test Files 8 passed (8) and Tests 23 passed (23), lint, types and build with no errors, an empty git status --short. git ls-files found only .env.example, and the grep of names returned one, process.env.NEXT_PUBLIC_AUDIO_BASE_URL, which stands in .env.example. grep -n domains next.config.ts found nothing.

Then we checked whether the list catches anything. We played an agent that "while at it" added to the image configuration one line from an old tutorial:

5:    domains: ["picsum.photos"],

This is the output of the command from point 6: a line number and its content. At the same time git status --short showed M next.config.ts, so point 2 failed as well. One change you did not order failed two points, and you learn about it before publishing, not after. Lint and types will not notice such a change, as you saw in lesson 10_5, and the build only warns.

What Claude wrote: the part for the captain

The second part holds the points that Claude cannot or should not pass for you:

- /code-review and /security-review on this branch; a decision which remarks to accept.
- /verify after the last change.
- A fragment of every key from .env.local searched for in .next/static in my own terminal: zero hits.
- The preview from /deploy opened in the browser: the player, covers, the search.
- Promotion to production in the Vercel dashboard, by hand.
- The way back: which earlier deployment Instant Rollback would restore.

Each of these points has a reason. The reports of /security-review and /code-review are hypotheses to check, as in lessons 2_9 and 8_7, so the decision is yours. You run /verify after the word "done", as in lesson 10_4. Claude will not check for a key in the build, because the deny rule from lesson 8_4 does not let it read .env.local, and that is good: you type a fragment of a key in your own terminal, and a good hit count is zero. The preview, the promotion and the way back are lesson 10_5.

Captain's review

You read the result of the list like a scout's report, not like a stamp:

  1. Every point has a command and a result. "PASS" with no command under it is a promise, not proof.
  2. FAIL stops the voyage. You do not ask to "fix everything". You pick a point and give a narrow request, like with fixes after a security review.
  3. The list does not fix itself. A typical agent mistake is adding a step "for tidiness" that changes something, for example npm audit fix or an automatic commit. Every change in SKILL.md goes through your diff like code.
  4. A header without loopholes. The header has no allowed-tools field, which according to the documentation lets the named tools be used in a turn without asking. A list that only checks needs no consent for anything except commands you will read in the report anyway.
  5. The list grows after slips. Best practices advise adding to the instructions what you have corrected twice already. When a preview lets through a bug that a command could have caught, add a point.

What the list will not catch

Be honest about the list. Tests guard only what someone described in a test: a bug in a path nobody tested will pass through all seven points. A grep finds only a key whose fragment you know, not a secret pasted under another name. A preview has preview variables, so production may behave differently, and the promotion builds the app anew with production variables. The ask and deny rules match the text of a command, not its effect. The list also does not see what happens outside the project: a failure of the recordings host or a change in someone else's API. That is why the last point is always the way back.

Next step

Ask for a commit, for example "The pre-publish skill". From now on every voyage has the same order: /pre-publish, your points from the list, /deploy, the preview in the browser, the promotion in the dashboard and a ready way back. To your mentor you will send a screenshot of the working Sea Shanty Sounds, a screenshot of green tests and your list. In the editor below a checklist is waiting to be walked through: tick the points, switch on agent mistakes and see which point catches them and which does not.

Remember: a checklist does not sail for the captain, but it does not let the captain forget a single line before leaving port.

Code for this lesson: App.jsx
// A checklist before publishing: Claude's points, the captain's points and agent mistakes
import { useState } from 'react';

const MISTAKES = [
  { id: 'domains', label: 'The agent added images.domains to next.config.ts (no commit)' },
  { id: 'weakTest', label: 'The agent weakened the formatTime test and committed' },
  { id: 'publicKey', label: 'The agent used NEXT_PUBLIC_STATS_KEY for a key' },
  { id: 'envFile', label: 'The agent added .env.local to Git' },
  { id: 'untested', label: 'A bug in a path that no test checks' },
];

const CAPTAIN = [
  '/code-review and /security-review: I decide which remarks to accept',
  '/verify after the last change',
  'A fragment of every key searched for in .next/static: zero hits',
  'The preview from /deploy checked in the browser',
  'Promotion to production by hand, in the Vercel dashboard',
  'Way back: I know which deployment Instant Rollback would restore',
];

// Seven points that Claude checks with commands; the result depends on the project state
function claudeChecks(m) {
  return [
    { point: 'Tests, lint, types, build', command: 'commands from CLAUDE.md', pass: true, note: 'Tests 23 passed (23)' },
    { point: 'Clean git status', command: 'git status --short', pass: !m.domains, note: m.domains ? 'M next.config.ts' : 'empty' },
    { point: '.env files in Git', command: "git ls-files | grep -E '(^|/)\\.env'", pass: !m.envFile, note: m.envFile ? '.env.example, .env.local' : '.env.example' },
    {
      point: 'Variable names in .env.example',
      command: "grep -rhoE 'process\\.env\\.[A-Z0-9_]+' app components lib",
      pass: !m.publicKey,
      note: m.publicKey ? 'NEXT_PUBLIC_STATS_KEY: missing from .env.example, a key with NEXT_PUBLIC_' : 'NEXT_PUBLIC_AUDIO_BASE_URL',
    },
    { point: 'deny and ask rules', command: 'cat .claude/settings.json', pass: true, note: 'deny .env, ask vercel and git push' },
    { point: 'No images.domains', command: 'grep -n domains next.config.ts', pass: !m.domains, note: m.domains ? '5:    domains: ["picsum.photos"],' : 'no hits' },
    {
      point: 'Changed test files to read',
      command: "git log --oneline --stat -5 -- '*.test.ts' '*.test.tsx'",
      pass: true,
      note: m.weakTest ? 'lib/format.test.ts changed: read the diff!' : 'components/Queue.test.tsx (the queue test from 10_4)',
    },
  ];
}

export default function App() {
  const [mistakes, setMistakes] = useState({});
  const [report, setReport] = useState(null);
  const [captain, setCaptain] = useState(CAPTAIN.map(() => false));

  function toggleMistake(id, on) {
    setMistakes((m) => ({ ...m, [id]: on }));
    setReport(null);
  }

  function runChecklist() {
    setReport(claudeChecks(mistakes));
  }

  const claudeOk = report && report.every((r) => r.pass);
  const captainOk = captain.every(Boolean);

  return (
    <div className="min-h-screen bg-gray-950 p-4 text-white">
      <div className="mx-auto max-w-xl space-y-4">
        <h1 className="text-lg font-semibold">/pre-publish</h1>

        <div className="space-y-1 rounded-xl bg-gray-900 p-3 text-sm">
          <p className="text-gray-400">Agent mistakes to switch on</p>
          {MISTAKES.map((m) => (
            <label key={m.id} className="flex items-center gap-2">
              <input type="checkbox" checked={Boolean(mistakes[m.id])} onChange={(e) => toggleMistake(m.id, e.target.checked)} />
              {m.label}
            </label>
          ))}
        </div>

        <button type="button" onClick={runChecklist} className="rounded-full bg-white px-4 py-2 font-semibold text-black">
          Run /pre-publish
        </button>

        {report && (
          <div className="overflow-x-auto rounded-xl bg-black p-3 text-xs">
            <table className="w-full text-left">
              <thead className="text-gray-400">
                <tr><th className="pr-2">Point</th><th className="pr-2">Command</th><th className="pr-2">Result</th><th>Verdict</th></tr>
              </thead>
              <tbody>
                {report.map((r) => (
                  <tr key={r.point} className="align-top">
                    <td className="pr-2">{r.point}</td>
                    <td className="pr-2 font-mono text-gray-400">{r.command}</td>
                    <td className="pr-2">{r.note}</td>
                    <td className={r.pass ? 'text-green-400' : 'text-red-400'}>{r.pass ? 'PASS' : 'FAIL'}</td>
                  </tr>
                ))}
              </tbody>
            </table>
          </div>
        )}

        <div className="space-y-1 rounded-xl bg-gray-900 p-3 text-sm">
          <p className="text-gray-400">Checked by the captain</p>
          {CAPTAIN.map((item, i) => (
            <label key={item} className="flex items-center gap-2">
              <input
                type="checkbox"
                checked={captain[i]}
                onChange={(e) => setCaptain((list) => list.map((v, j) => (j === i ? e.target.checked : v)))}
              />
              {item}
            </label>
          ))}
        </div>

        {report && !claudeOk && (
          <p className="rounded-xl bg-red-900 p-3 text-sm">Voyage on hold: pick one FAIL point and give a narrow request.</p>
        )}
        {report && claudeOk && mistakes.weakTest && (
          <p className="rounded-xl bg-amber-900 p-3 text-sm">All green, but point 7 points at a changed test. A green report is not proof until you read the diff.</p>
        )}
        {report && claudeOk && mistakes.untested && (
          <p className="rounded-xl bg-amber-900 p-3 text-sm">The list does not see this: a bug in an untested path will show only in the browser preview or with the crew. That is why you have a way back.</p>
        )}
        {report && claudeOk && captainOk && (
          <p className="rounded-xl bg-green-900 p-3 text-sm">You can run /deploy, and after checking the preview promote it by hand.</p>
        )}
      </div>
    </div>
  );
}

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. The project has tests, lint and a build. Which line do Claude Code best practices call the most valuable in CLAUDE.md?

  2. 2. Claude reports green tests, and Source Control shows a change in lib/format.test.ts that you did not ask for. What do you do?

These are 2 of 7 questions for this lesson. Solve the rest in the game.

Hands-on tasks in the game

  • Vertical ordering

    Order the steps of working with a new behavior test:

  • Vertical ordering

    Order the voyage from the checklist to production:

  1. QuestionThe most valuable line of CLAUDE.md
  2. QuestionA test changed in the diff
  3. Put in orderThe loop of a new test
  4. QuestionWhat /goal does
  5. QuestionWhy /verify
  6. Put in orderOrder before publishing
  7. Questiondisable-model-invocation in /deploy
  8. QuestionA production deployment in auto mode
  9. QuestionWhat the list will not catch
  10. Project to submitSend Sea Shanty Sounds to mentor
  11. VideoModule summary

Useful articles