write /goals like acceptance criteria.
/goal is now everywhere. Claude Code, Codex, Hermes, and more agents are adopting the same pattern: you set a completion condition, the agent works autonomously until a fast evaluator model confirms the condition is met.
the feature is simple. writing good goals is not.
vague goals fail in two ways: the agent loops forever trying to satisfy an unclear condition, or the evaluator hallucinates success because there's nothing concrete to check against. both burn tokens for nothing.
here's what separates goals that work from goals that break:
๐ด๐ผ๐ผ๐ฑ ๐ด๐ผ๐ฎ๐น๐ ๐ฑ๐ฒ๐๐ฐ๐ฟ๐ถ๐ฏ๐ฒ ๐ฎ๐ป ๐ผ๐ฏ๐๐ฒ๐ฟ๐๐ฎ๐ฏ๐น๐ฒ ๐ฒ๐ป๐ฑ ๐๐๐ฎ๐๐ฒ.
"all tests in test/auth pass and lint is clean" works because the agent can run the tests, print the output, and the evaluator can confirm it from the transcript.
"every call site of the old API migrated and build succeeds" works because there's a verifiable artifact: the build output.
"CHANGELOG.md has an entry for each PR merged this week" works because it points to a concrete file with concrete content.
๐ฏ๐ฎ๐ฑ ๐ด๐ผ๐ฎ๐น๐ ๐ต๐ฎ๐๐ฒ ๐ป๐ผ ๐ณ๐ถ๐ป๐ถ๐๐ต ๐น๐ถ๐ป๐ฒ.
"make the codebase better" fails because better by what metric? "refactor everything" fails because there's no exit condition. "fix the bugs" fails because which bugs, verified how?
the mental model that helps: if a human couldn't tell when the ticket is done, neither can the evaluator.
treat every /goal like a ticket you're assigning to a very literal junior developer who never gets tired. write the exact acceptance criteria you'd put in that ticket.
one more thing: complex multi-step objectives overwhelm it. "redesign auth, add OAuth, write tests, update docs" is four goals pretending to be one. break them into sequential /goal calls where each has a single verifiable finish line.
i wrote a detailed breakdown of /goal (article below) covering the full mechanics.