Vibe coding with Claude Code course Β· Module 15: Advanced Claude Code

An agent on watch: scripts for review, documentation, tests and commits

10 min read
In this lesson9

Look into the hold of Treasure Map. In lib/ lie fourteen files of code, and nine of them have no tests. README.md still talks about create-next-app, though the project has a database, API routes and image search. And the commit messages from last week probably read "fix", "fix2" and "tweaks". None of this work is hard, every bit of it is boring, and you keep putting each off. Such night-watch duties you hand to scripts, and you stay with what a script cannot do: the decision.

What you already know

In lesson 14_1 you learned the pipe, the > redirect, the --tools and --model flags, and that -p without consent will write nothing. From lesson 10_4 you know that a test you never saw red may have guarded nothing, and from lesson 1_5 that the first line of a commit message says "what" in 50 characters. In lesson 12_7 Claude landed in GitHub Actions. Now you put these blocks together into three scripts, and you write them with the hands of Claude Code.

Request for Claude Code: documentation

Start with documentation, because its mistakes cost the least. In a Claude Code session write:

Request for Claude Code:

Write the script scripts/generate-docs.sh: three claude -p calls with --model sonnet
and --max-turns 10. The results: docs/API.md from the routes in app/api, docs/COMPONENTS.md
from components/ and the README.md of the whole project, each saved with the > redirect.
When a call fails, the old file must stay. Do not run the script, show it to me.

The last sentence matters: you read a script first and only then run it.

What Claude wrote: generate-docs.sh

In Cursor open scripts/generate-docs.sh. At the top stands a variable with a rule shared by all the calls:

ONLY="Return only the content of a Markdown file, with no fences around the whole thing and no sentences of your own."
mkdir -p docs

Everything Claude prints lands in the file: the sentence "Here is the documentation:" too, and the three fence characters around the whole. This rule says the result must be a ready file, not a message about a file. mkdir -p creates the docs folder and does nothing when it already exists. The first call:

claude -p "Describe the routes in app/api: method, address, input, responses and error codes. $ONLY" \
  --model sonnet --max-turns 10 > docs/API.md.tmp && mv docs/API.md.tmp docs/API.md

The answer goes to a .tmp file first, because > empties the file before Claude even begins. && runs mv only when claude ended with success, so a run cut off by the turn limit will not overwrite a good docs/API.md with an error message. The next two calls have the same shape:

claude -p "Describe the components in components/: role, props and a usage example. $ONLY" \
  --model sonnet --max-turns 10 > docs/COMPONENTS.md.tmp && mv docs/COMPONENTS.md.tmp docs/COMPONENTS.md

claude -p "Write the project README: description, how to run it, tests, database, directory structure. $ONLY" \
  --model sonnet --max-turns 10 > README.md.tmp && mv README.md.tmp README.md

With the README this order has a second gain: Claude can read the old file, because > empties only README.md.tmp. No call changes the code: in -p mode without consent Claude only reads, and the files are written by your terminal.

There is a second way: ask "save the result in docs/API.md" and add --permission-mode acceptEdits. Then Claude creates and edits files in the project itself, but any files, not only these three. Run such a script only on a clean tree, when git status shows nothing: then the diff in Source Control is exactly the work of the script, and git restore undoes every change. I recommend the redirect, because it is the script that decides where the result goes.

Request for Claude Code: tests

Now the nine files without tests. The project uses Vitest, so that is what you ask for:

Write scripts/generate-tests.sh: for every .ts file in lib/ without a .test.ts file,
call claude -p asking for Vitest tests and save the result next to it. Skip files
that already have tests and files with no exported functions. A failed run must not leave a test file behind.
Do not run the script, show it to me.

What Claude wrote: generate-tests.sh

The script is a loop, that is, the same order repeated for every file. The first fragment picks the files and skips those with tests:

for FILE in $(find lib -name "*.ts" ! -name "*.test.ts"); do
  TEST_FILE="${FILE%.ts}.test.ts"
  if [ -f "$TEST_FILE" ]; then
    continue
  fi

find lib -name "*.ts" fishes out the TypeScript files, and ! -name "*.test.ts" rejects the tests themselves. for ... do puts one path into the FILE variable on every turn. ${FILE%.ts} cuts off the .ts ending, so lib/plural.ts becomes lib/plural.test.ts. [ -f "$TEST_FILE" ] asks whether such a file exists, and continue jumps to the next turn. Your tests stay untouched, and you can run the script as often as you like. The second filter weeds out files with nothing to test:

  if ! grep -q "export .*function" "$FILE"; then
    echo "Skipping $FILE: it exports no functions"
    continue
  fi

grep -q searches for text quietly and answers only with success or failure, and ! flips the answer. In our project lib/types.ts with nothing but types and lib/prisma.ts with the database client dropped out: a test for them would be a dummy. Next, the actual call:

  echo "Writing tests: $TEST_FILE"
  claude -p "Write Vitest tests for @$FILE: every exported function and the edge cases.
Return TypeScript code only, with no Markdown fences and no explanations." \
    --model sonnet --max-turns 5 > "$TEST_FILE.tmp" || continue
  mv "$TEST_FILE.tmp" "$TEST_FILE"

The terminal substitutes the path for $FILE before Claude sees the sentence, so @ points at a different file on every turn. || continue moves on to the next file when claude fails: only the .tmp stays, and the next run will try again. Had the result gone straight into .test.ts, a failed file would have blocked the test forever, because [ -f ] would count it as done. The last fragment catches the agent's most common mistake:

  if grep -q '^```' "$TEST_FILE"; then
    echo "Markdown fences in $TEST_FILE: remove them before running the tests"
  fi
done

When Claude wraps the code in Markdown fences, the file stops being TypeScript. On a dummy with fences, Vitest reported TypeError: "" is not a function in our project and ran not a single test. The same script works with Jest: change the word Vitest to Jest in the request, and in a project with code in src/ the path in find too.

Captain's review

Run bash scripts/generate-tests.sh and, before you add anything to a commit, check:

  1. Each test file separately: npm run test -- --run lib/plural.test.ts. In our run Claude wrote 34 cases for lib/plural.ts and all of them passed.
  2. The test goes red: break the function for a moment, as in lesson 10_4. In lib/plural.ts we swapped forms.few for forms.many and 11 of the 34 tests turned red. Then git restore lib/plural.ts. A test that passes despite a broken function is a dummy.
  3. An essay instead of code: the fence guard will not catch an answer written in prose, like the one in lesson 14_1 when the write was blocked. Only running the test catches it, so point 1 is mandatory.

Request for Claude Code: commit

The third script ends with your signature:

Write scripts/smart-commit.sh: from the staged diff, claude -p proposes a commit message
in the Conventional Commits format, the script shows it and makes the commit only after I type y.
An empty staging area ends the script without calling Claude. Do not run the script.

Conventional Commits is an agreement about the shape of a message: type(scope): description, where the type is, for example, feat for a new feature, fix for a repair, or test and docs.

What Claude wrote: smart-commit.sh

First, the guard against an empty staging area:

DIFF=$(git diff --cached)
if [ -z "$DIFF" ]; then
  echo "The staging area is empty. First: git add <files>"
  exit 1
fi

$(...) runs a command and puts its output into a variable. [ -z "$DIFF" ] asks whether the variable is empty, and exit 1 ends the script with an error code before you pay for a message about nothing. Then the proposal:

MESSAGE=$(echo "$DIFF" | claude -p "Write a commit message in the Conventional Commits format: type(scope): description, in English, first line up to 50 characters. Return the message only." \
  --model sonnet --tools "" --max-turns 2)

The diff flows through the pipe, and the answer lands in MESSAGE. --tools "" is enough, because for the message Claude needs only the diff. Finally, the consent:

echo "Proposal: $MESSAGE"
read -r -p "Commit with this message? (y/n) " ANSWER

if [ "$ANSWER" = "y" ]; then
  git commit -m "$MESSAGE"
else
  echo "Cancelled, nothing was saved."
fi

read stops the script and waits for your answer from the keyboard, and git commit -m starts only after y. Any other answer saves nothing. This is no decoration: the message may leave out something only you can see, for example that the change to the tag limit was deliberate. A human signs the commit, always.

Next step: a watch in CI

You know the workflow with @claude from lesson 12_7. What is new is a review that leaves remarks at specific lines of a pull request. The documentation shows it as a step of the action with the official code-review plugin:

          plugins: "code-review@claude-plugins-official"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Above it, in the same step, stands plugin_marketplaces with the address of the official marketplace. --comment orders the review to be published in the pull request: a comment at every line with a problem, or one summary comment. claude_args must name the comment tool, because the action runs it only when --allowedTools names it. In a public repository GitHub does not give secrets to runs from forks, so the review will start only for branches from your own repository.

When you leave Claude alone, the best practices advise a set of three flags: --allowedTools approves exactly what the task needs, --permission-mode dontAsk rejects the rest, and --max-turns stops the run. They add five questions: does the task know what the end looks like, can it check itself, what may it touch, what will stop it, and who approves the result. For our scripts the answer to the last one is always the same: you.

In the editor next door you will run files from lib/ through the generate-tests.sh loop and see which ones it skips, where it leaves a .tmp and which test gives away a dummy.

Remember: the automaton proposes, the sailor decides, and every script ends at your signature.

Code for this lesson: App.tsx
// Simulator of the generate-tests.sh loop: what the script skips, what it writes and which test guards
import { useState } from 'react';

export type Reply = 'code' | 'weak' | 'fenced' | 'essay' | 'error';
export type Status = 'has-test' | 'no-function' | 'written' | 'failed';

export interface LibFile {
  path: string;
  hasTest: boolean;
  exportsFunction: boolean;
}

export interface FileResult {
  path: string;
  status: Status;
  verdict: string;
  guarded: boolean;
}

export const FILES: LibFile[] = [
  { path: 'lib/boards.ts', hasTest: true, exportsFunction: true },
  { path: 'lib/columns.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/imageCheck.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/plural.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/price.ts', hasTest: true, exportsFunction: true },
  { path: 'lib/prisma.ts', hasTest: false, exportsFunction: false },
  { path: 'lib/session.ts', hasTest: false, exportsFunction: true },
  { path: 'lib/types.ts', hasTest: false, exportsFunction: false },
];

const REPLY_LABEL: Record<Reply, string> = {
  code: 'code only, with real assertions',
  weak: 'code only, but expect(1).toBe(1)',
  fenced: 'code in Markdown fences',
  essay: 'a prose description instead of code',
  error: 'error: turn limit',
};

export function testPath(path: string): string {
  return path.replace(/\.ts$/, '.test.ts');
}

const VERDICT: Record<Reply, string> = {
  code: 'Green, and red once the function is broken: the test guards.',
  weak: 'Green even after the function is broken: a dummy, reject it.',
  fenced: 'Vitest: TypeError: "" is not a function, not a single test ran.',
  essay: 'The guard stays silent, because there are no fences. Only running the test will show the syntax error.',
  error: 'Only the .tmp file with the error message stays. The next run will try again.',
};

export function runLoop(files: LibFile[], replies: Record<string, Reply>, existing: string[]) {
  const log: string[] = [];
  const results: FileResult[] = [];
  const created: string[] = [];
  for (const file of files) {
    const test = testPath(file.path);
    if (file.hasTest || existing.includes(test)) {
      results.push({ path: file.path, status: 'has-test', verdict: 'Has a test: continue.', guarded: false });
      continue;
    }
    if (!file.exportsFunction) {
      log.push('Skipping ' + file.path + ': it exports no functions');
      results.push({ path: file.path, status: 'no-function', verdict: 'No functions to test.', guarded: false });
      continue;
    }
    log.push('Writing tests: ' + test);
    const reply = replies[file.path] ?? 'code';
    if (reply === 'error') {
      results.push({ path: file.path, status: 'failed', verdict: VERDICT.error, guarded: false });
      continue;
    }
    created.push(test);
    const guarded = reply === 'fenced';
    if (guarded) log.push('Markdown fences in ' + test + ': remove them before running the tests');
    results.push({ path: file.path, status: 'written', verdict: VERDICT[reply], guarded });
  }
  return { log, results, created };
}

const START: Record<string, Reply> = {
  'lib/columns.ts': 'code',
  'lib/imageCheck.ts': 'fenced',
  'lib/plural.ts': 'code',
  'lib/session.ts': 'weak',
};

const STATUS_CLASS: Record<Status, string> = {
  'has-test': 'text-slate-400',
  'no-function': 'text-slate-400',
  written: 'text-emerald-400',
  failed: 'text-amber-400',
};

export default function App() {
  const [replies, setReplies] = useState<Record<string, Reply>>(START);
  const [runs, setRuns] = useState(0);
  const first = runLoop(FILES, replies, []);
  const second = runLoop(FILES, replies, first.created);
  const shown = runs === 0 ? null : runs === 1 ? first : second;

  return (
    <div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
      <h1 className="text-xl font-bold">The generate-tests.sh loop on lib/ in Treasure Map</h1>
      <p className="text-sm text-slate-300">Choose what Claude answers for the files without tests, and run the script.</p>
      <ul className="space-y-1 text-sm">
        {FILES.map((file) => (
          <li key={file.path} className="flex flex-wrap items-center gap-2">
            <code className="w-40 font-mono">{file.path}</code>
            {file.hasTest ? (
              <span className="text-slate-400">already has {testPath(file.path)}</span>
            ) : !file.exportsFunction ? (
              <span className="text-slate-400">exports no functions</span>
            ) : (
              <select
                className="rounded border border-slate-600 bg-slate-900 p-1"
                value={replies[file.path] ?? 'code'}
                onChange={(e) => {
                  setReplies({ ...replies, [file.path]: e.target.value as Reply });
                  setRuns(0);
                }}
              >
                {(Object.keys(REPLY_LABEL) as Reply[]).map((r) => (
                  <option key={r} value={r}>{REPLY_LABEL[r]}</option>
                ))}
              </select>
            )}
          </li>
        ))}
      </ul>
      <div className="flex gap-2">
        <button type="button" className="rounded bg-emerald-700 px-3 py-1" onClick={() => setRuns(1)}>bash scripts/generate-tests.sh</button>
        <button type="button" className="rounded bg-slate-700 px-3 py-1" disabled={runs === 0} onClick={() => setRuns(2)}>Run a second time</button>
      </div>
      {shown && (
        <>
          <pre className="rounded bg-slate-900 p-2 font-mono text-xs">{shown.log.length ? shown.log.join('\n') : '(the script printed nothing: everything has tests)'}</pre>
          <ol className="space-y-1 text-sm">
            {shown.results.map((r) => (
              <li key={r.path} className="rounded border border-slate-800 p-2">
                <strong className={STATUS_CLASS[r.status]}>{r.path}</strong> {r.verdict}
              </li>
            ))}
          </ol>
          <p role="status" className="font-semibold">
            {runs === 1
              ? 'Run every new test and break its function for a moment: only then do you know which one guards.'
              : 'The second run skips the files that already have tests and retries only the failed ones.'}
          </p>
        </>
      )}
    </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. Why do the commands in generate-docs.sh end with the rule "Return only the content of a Markdown file, with no fences around the whole thing and no sentences of your own"?

  2. 2. What makes the official review in GitHub Actions leave remarks at specific lines of a pull request?

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

Hands-on tasks in the game

  • Horizontal ordering

    Arrange the line from smart-commit.sh that saves the proposed commit message in the MESSAGE variable:

  • Code editor

    In commands.sh write the generate-docs.sh script that uses claude -p to create three files: docs/API.md, docs/COMPONENTS.md and README.md. Save each answer to its file with the > redirect.

  • Horizontal ordering

    Arrange the call from generate-docs.sh that replaces docs/API.md only after a successful run:

  • Vertical ordering

    Arrange the loop lines from generate-tests.sh from top to bottom:

  • Code editor

    In commands.sh write the generate-tests.sh script: find the .ts files in src (find), skip those that already have a .test.ts file ([ -f ... ]) and call claude -p for the rest, asking for Jest tests.

  • Vertical ordering

    Arrange the steps of the smart-commit.sh script:

  • Horizontal ordering

    Arrange the line from generate-tests.sh that picks files without exported functions so they can be skipped:

  • Vertical ordering

    Arrange the work with generate-tests.sh, from the run to the commit:

  1. QuestionQuiz: The file only, no message
  2. QuestionQuiz: Line comments in CI
  3. Put in orderOrdering: A commit message into a variable
  4. Coding taskPractice: Docs generator
  5. QuestionQuiz: The Markdown fence guard
  6. Put in orderOrdering: Writing through a temporary file
  7. QuestionQuiz: The test file name
  8. Put in orderOrdering: The lines of generate-tests.sh
  9. Coding taskPractice: Tests for files without tests
  10. Put in orderOrdering: The smart-commit script
  11. QuestionQuiz: Flags for unattended work
  12. Put in orderOrdering: A filter for files without functions
  13. Put in orderOrdering: From script to checked tests

Useful articles