Pistis

Write a good task

Write tasks an agent can finish without guessing.

A good task says what is wrong, where to look and how to tell it's done. The agent can't ask you what you meant while you're away, so put that in the task.

Fix a failing test

Instead of
task
Tests are failing, fix them.
  • Doesn't say which tests.
  • Doesn't say whether the code or the test is wrong.
Write
task
The test "retries three times before failing" in src/retry.test.ts fails.
Error: expected 3 attempts, got 2.
Run it with: npm test -- retry
Fix the code in src/retry.ts, not the test. Done when npm test passes.
  • Names the test and the file.
  • Gives the exact error.
  • Says how to run it and what "done" means.
  • Says what must not change.

Upgrade a dependency

Instead of
task
Update our dependencies.
  • Could touch hundreds of packages.
  • No way to tell when it's done.
Write
task
Upgrade zod from 3.23 to 4 in packages/api.
Follow the upgrade notes in the zod changelog.
Fix type errors and failing tests. Don't upgrade anything else.
Done when pnpm typecheck and pnpm test pass.
  • Names the package, the versions and the place.
  • Limits the scope.
  • Gives the checks to run.

Fix a flaky test

Instead of
task
The socket test is flaky.
  • The agent may run it once, see it pass and stop.
Write
task
The test "reconnects after a drop" in test/socket.test.ts fails about one run in ten.
Run it 50 times with: for i in $(seq 50); do npm test -- socket || break; done
Find the race and fix it. Explain the cause in the pull request.
  • Says how often it fails.
  • Gives a command that reproduces it.
  • Asks for the cause, not only a fix.

Habits that help

  • Name files, functions and commands. The agent finds them faster.
  • Give a check the agent can run: a test, a type check, a build.
  • Say what not to touch.
  • Keep one task per session. Start another session for the next one.
  • Put lasting advice in the agent, not every task: how to run the tests, the code style. See Agents.

When to use agents

Pick tasks a background agent finishes well, and spot the ones it doesn't.

Sessions

Start a task, follow it and get the result.

On this page

Fix a failing testUpgrade a dependencyFix a flaky testHabits that help