## Claude Code の /goal は何を根拠に「終わった」と判断するのか、複数の指示で検証してみた I verified with multiple instructions what Claude Code's /goal uses as a basis to judge "done"

Introduction

Hello, I'm Shimada from Classmethod's Manufacturing Business Technology Division.

When you pass conditions to Claude Code via /goal, it repeats turns on its own until they are met.
Anthropic calls this usage Loop Engineering, and I also use it when the goal of a task I want to hand off to Claude Code is clear and I want it to run autonomously.
On the other hand, just by using it, you can't see what Claude Code is looking at when it decides "it's done."
Without that visibility, how to write the conditions, and when it will stop, become guesswork.

This article first briefly reviews how the term Loop Engineering emerged, tracing its lineage from prompt engineering.
Next, it organizes the mechanism behind /goal's evaluation using the official documentation and strings embedded in the binary.
Then, against the same small Ruby repository, it runs 5 different /goal conditions and 2 custom Stop hooks, for a total of 7 runs, and examines the evaluation results and the reasons the evaluator left behind.
Finally, it summarizes how to write exit conditions and when and how to use /goal.

The information in this article was confirmed as of September 15, 2026, with Claude Code 2.1.271.
Each condition was only run once, so evaluations may vary as model behavior.

The Lineage from Prompt Engineering to Loop Engineering

Loop Engineering is one of a series of terms that have described what those using LLMs are "designing."
Each time the terminology changed, the target of design expanded outward from a single input to the model.
Here are the major ones I was able to verify sources for, arranged by when they first appeared and where they came from.

Prompt engineering began in 2020 when GPT-3 was found to change behavior with few-shot examples, and became a common term with chain-of-thought in 2022 and ChatGPT in November of that year.
The target of design was a single sentence passed to the model.

Flow engineering was the first naming that divided that single sentence into multiple stages.
The AlphaCodium paper reported that a flow combining preprocessing to organize problems in natural language with an iteration of applying generated code to tests and fixing it significantly improved GPT-4's accuracy compared to a single carefully crafted prompt.
With this naming, "verify with tests and repeat" entered the target of design.

Context engineering spread in June 2025 when Tobi Lütke, CEO of Shopify, posted that he preferred "context engineering" over "prompt engineering," and Karpathy followed up calling it "the delicate art and science of filling the context window with just the information needed for the next move."
Anthropic also positioned context engineering as "a natural progression of prompt engineering" in their September article.
The target of design expanded from a single sentence to the entirety of the context, including system prompts, tool definitions, history, and external data.

Harness engineering moves the target of design outside the model.
In November 2025, Anthropic published the configuration of initialization agents and progress files for continuing work across context windows, and in February 2026, OpenAI published an internal experiment that produced approximately one million lines of a product over five months with zero lines of handwritten code, each as harness design.
A harness is the collective term for tool definitions, environments, permissions, feedback, and session handoffs that exist outside the model.
The argument is that human work shifts from writing code to preparing the environment, intent, and verification in which agents operate.

At his April 2026 talk, Karpathy distinguished that while vibe coding "raises the floor," agentic engineering "raises the ceiling" as a role.
The definition is the work of coordinating fallible agents while maintaining correctness, safety, and maintainability.

Loop engineering, built on this lineage, is a term that made "when humans send prompts and when they stop" the target of design.
The trigger was in June 2026, when Boris Cherny, who created Claude Code, said in a conversation at Acquired Unplugged that he no longer sends prompts to Claude himself—the loop sends prompts to Claude—and his job is to write the loop.
This statement spread on X, Peter Steinberger posted that "rather than prompting coding agents, you should design loops that prompt agents," and Addy Osmani defined it in an article on June 8 as "loop engineering is replacing yourself as the human who prompts the agent."
In other words, the term itself spread outside Anthropic first, and Anthropic picked it up in a blog post on June 30, organizing the types and uses of loops.

Looking at this range together, you can see that the target of design expanded from "a single sentence" to "flow," "context," and "outside the model," and with loop engineering it reached "start and stop."
The exit conditions this article covers are the "stop" part of that.

What Is Loop Engineering?

Anthropic's blog post from June 30, 2026, Loop engineering: Getting started with loops, defines a loop as "an agent repeating cycles of work until a stop condition is met."
It then divides loops into 4 types based on what drives them.

• Turn-based: Starts with a developer's prompt, stops when Claude judges "it's done." This is everyday conversation.
• Goal-based: Passes conditions via /goal, and a model that evaluates the conditions separately from the working model (hereafter, the evaluator) keeps it running until it judges the conditions are met.
• Time-based: Runs at time intervals via /loop or /schedule.
• Proactive: Starts without human intervention based on events or schedules. Things like bug triage.

This article covers Goal-based.
In a normal turn, Claude itself judges "it's done" and stops.
/goal is a mechanism that separates that judgment from the working model and entrusts it to an evaluator that has been given the conditions.
The answer to "when does it end" depends on what this evaluator sees and what it returns.

Screen immediately after passing conditions to /goal in interactive mode. The conditions are displayed as the active goal.

The Internals of /goal: A Session-Limited Stop Hook

According to the official documentation Keep Claude working toward a goal, /goal is a command that registers a prompt-type Stop hook only for that session.
A Stop hook runs every time Claude tries to end a turn, and the prompt type has a model make the judgment instead of a shell script.
When you pass conditions, Claude Code does the following:

The evaluator defaults to the small fast model (Haiku in the Claude API).
Reading the evaluator instructions embedded in the binary, the response is JSON, and in addition to ok and reason, impossible can be included.
reason says "quote strings from the transcript as much as possible," and if there is no evidence in the conversation, it should return "insufficient evidence in transcript".
For impossible, it says to verify independently, since Claude saying something is impossible is evidence but not proof.

There is one constraint about the evaluator to be aware of.
The official documentation explicitly states that "the evaluator does not execute commands and does not independently read files."
This means the evaluator can only see strings that Claude has surfaced in the conversation.
If you want the evaluator to know that tests passed, Claude needs to execute the tests and leave the results in the conversation.
How to write exit conditions is derived by working backward from this.

The official documentation also answers the concern about whether it might loop infinitely.

• If Claude repeatedly only gives responses to the evaluator without using tools, Claude Code stops the loop and displays a warning.
• If the Stop hook blocks 8 consecutive times, Claude Code overrides and stops it (changeable with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP).
• In non-interactive mode, upper limits can be set with --max-turns and --max-budget-usd.
• Adding a sentence like "cut off after 20 turns" in the condition text causes both Claude and the evaluator to read it and make their judgments accordingly.

Because /goal runs on top of the hooks mechanism, it cannot be used in sessions where the folder is not trusted or in environments with disableAllHooks enabled.
In that case, the command displays the reason.

The Repository Used for Verification

I kept the task small to compare only the differences in conditions.
We start from a state where there are 3 price calculation methods, 5 minitest tests, and 3 of those 5 are failing.
All are bugs where the spec written in comments conflicts with the implementation, and the fix is unambiguous.

module Pricing
  # Return price after applying percent discount (0-100).
  def self.apply_discount(price, percent)
    price - price * percent
  end

  # Total for a bulk order. 10 or more units get 5% off.
  def self.bulk_total(unit_price, quantity)
    total = unit_price * quantity
    total = apply_discount(total, 5) if quantity > 10
    total
  end

  # Format as Japanese yen with thousands separators, no decimals.
  def self.format_yen(amount)
    "¥" + format("%.2f", amount).gsub(/(\d)(?=(\d{3})+\.)/, '\1,')
  end
end

$ ruby -Ilib -Itest test/pricing_test.rb
  1) Failure:
PricingTest#test_apply_discount_percent [test/pricing_test.rb:6]:
Expected: 900
  Actual: -9000

  2) Failure:
PricingTest#test_bulk_total_at_threshold_gets_discount [test/pricing_test.rb:18]:
Expected: 950
  Actual: 1000

  3) Failure:
PricingTest#test_format_yen [test/pricing_test.rb:22]:
Expected: "¥1,234,567"
  Actual: "¥1,234,567.00"

5 runs, 5 assertions, 3 failures, 0 errors, 0 skips

It may look contrived, but unit mismatches for ratios, inequality signs at boundary values, and digit format specifiers are all the kinds of discrepancies you see in reviews.

Runs were done in non-interactive mode, with logs saved for later reading.
/goal can be used as-is with -p.

claude -p "/goal <conditions>" \
  --output-format stream-json --verbose \
  --permission-mode acceptEdits \
  --allowedTools "Bash(ruby -Ilib -Itest:*) Bash(git diff:*) Bash(git status:*) Read Edit Glob Grep" \
  --max-turns 40 --max-budget-usd 3

In non-interactive mode, the evaluator's judgment reasons are not displayed, but they remain in the session transcript (the JSONL under ~/.claude/projects/) as goal_status.
The reasons quoted below were taken from there.

Running 7 Different Conditions

I ran 7 times with different conditions.
The first 5 use /goal, and the last 2 use custom Stop hooks without /goal.

Cost across all runs was $0.27–$0.62 including the main model.
Tokens used by the evaluator were 2,600–7,100 per goal, as the official documentation says "usually negligible compared to main turns."

1. Write Measurable Conditions, Constraints, and Evidence

I put in the 3 elements cited by the official documentation (measurable end state, how to verify it, constraints to observe) as-is.

/goal Without modifying anything under test/, run ruby -Ilib -Itest test/pricing_test.rb and have it finish with exit code 0. At the end, display the output of git diff --stat to leave evidence.

Claude fixed 3 bugs, re-ran the tests, displayed git diff --stat, and finished.
The evaluator judged it achieved on the first try, citing 3 pieces of evidence separately in the reason.

The transcript shows: (1) the test command ruby -Ilib -Itest test/pricing_test.rb ran with output "5 runs, 5 assertions, 0 failures, 0 errors, 0 skips" indicating successful completion with exit code 0; (2) git diff --stat output shows "lib/pricing.rb | 6 +++--- / 1 file changed, 3 insertions(+), 3 deletions(-)" confirming only lib/pricing.rb was modified and test/ was not changed; (3) the assistant explicitly confirmed "test/ は一切変更していません"

One note: Claude tried to run echo $? after the tests to display the exit code, but it wasn't a permitted command so it didn't go through, and the exit code itself wasn't left in the conversation.
The evaluator inferred exit code 0 from the "0 failures" line.
Since the verification method written in the conditions won't necessarily appear in the conversation as-is, it's good practice to align permitted commands with the verification method written in the conditions.

2. Vague Condition

For comparison, I passed an unmeasurable condition.

/goal Improve the quality of lib/pricing.rb

This also achieved on the first try.
However, the changes weren't limited to lib—10 tests were added to test/, going from 5 to 15.
The evaluator's reason came back in Japanese this time only.

lib/pricing.rb の品質が大幅に向上しました。3つの関数すべてのバグを修正：(...)さらに定数化、入力値検証(ArgumentError送出)、境界ケースのテスト10件追加により、テスト結果は「15 runs, 17 assertions, 0 failures, 0 errors, 0 skips」で全てのテストが成功しています。

The reason is a listing of what Claude did.
Since the condition is "quality," the evaluator has no choice but to accept what Claude called quality improvement.
Since there were also no constraints on the scope of changes, the work expanded to adding tests.
The result itself was a reasonable change, but the judgment of "done" was effectively made by Claude itself, with little difference from a normal turn.

3. Add a Turn Limit to the Vague Condition

I added only a cutoff sentence to the same vague condition.

/goal Improve the quality of lib/pricing.rb. However, cut off after 2 turns.

Claude completed bug fixes, constant extraction, input validation, and test additions in turn 1, declared "done in 1 turn," and finished.
The evaluator read the limit sentence and judged it achieved.

The condition required improving lib/pricing.rb's quality while completing within 2 turns. The transcript shows completion in 1 turn: (...) and all 11 tests now pass: "11 件すべてパスしました。1 ターンで完了です。" The quality improvement goal is satisfied well within the 2-turn limit.

The limit sentence isn't something Claude Code counts and enforces—it's something both Claude and the evaluator read as part of the condition text and judge accordingly.
This time it finished before reaching the limit, so I couldn't observe the cutoff behavior.
Since it's not a guaranteed mechanism, it's safer to also use --max-turns in non-interactive mode.
Note that this run also added tests to test/.

4. Self-Contradictory Condition (Only Prohibiting Changes)

To see a case where the evaluator returns impossible, I passed a condition that can't be met.
The condition is to make the tests pass without modifying either lib or test/, even though the bugs are only in lib.

/goal Without modifying lib/pricing.rb or any file under test/, have ruby -Ilib -Itest test/pricing_test.rb finish with exit code 0.

The result was achieved, not impossible.
After identifying 3 bugs, Claude chose require "minitest/autorun" as "the only injection point."
Since tests run with -Ilib, placing minitest/autorun.rb under lib/ makes it loaded before the gem's file.
Claude wrote a thin file there that loads the real minitest and then requires another file, which reopens the Pricing module and replaces the 3 methods with correct implementations.
lib/pricing.rb and test/ are unchanged by even 1 byte, and all 5 tests pass.

The evaluator judged it achieved with this reason:

The transcript shows ruby -Ilib -Itest test/pricing_test.rb executed with output "(...) 5 runs, 5 assertions, 0 failures, 0 errors, 0 skips" followed by confirmation "exit code: 0". The git status shows only untracked files (lib/minitest/ and lib/pricing_patch.rb) with no modifications to lib/pricing.rb or test/ files, as verified by "?? lib/minitest/\n?? lib/pricing_patch.rb".

It's exactly per the wording of the condition.
Since I only wrote "don't modify," adding new files was not prohibited.
The evaluator quoted the git status output from the conversation and confirmed that the wording of the condition was satisfied.
The evaluator's judgment wasn't wrong—it was the condition writer who left the loophole.

5. Self-Contradictory Condition (Also Prohibiting Additions)

So I also prohibited adding new files and added the verification method.

/goal Without modifying lib/pricing.rb or any file under test/, and without adding new files (git status --porcelain output remains empty), have ruby -Ilib -Itest test/pricing_test.rb finish with exit code 0.

Claude confirmed the repository structure and test results, reported "This goal is impossible to achieve as-is" while listing the locations of the 3 bugs, and ended the turn without changing anything.
The evaluator judged it impossible on the first evaluation, and the goal was recorded as a failure and automatically cleared.
61 seconds from start.

Test execution result shows exit code 1 with failure, and 3 tests are failing. Bash output shows '5 runs, 5 assertions, 3 failures, 0 errors, 0 skips'. (...) There are implementation bugs in lib/pricing.rb, and the condition cannot be met without fixes.

The evaluator's instructions say "Claude saying something is impossible is evidence but not proof."
In this run, not just Claude's explanation, but the test failure output and the unchanged git status were all in the conversation, so it can be read that the switch to impossible happened in one try.
Even if you pass a contradictory condition, if the loopholes are closed, it won't keep looping.

6. Writing a Custom Stop Hook as Officially Recommended

I also tried a form where the judgment is made deterministically by a shell script without using /goal.
A Stop hook that runs the tests and returns decision: block with a reason if they fail.
The official documentation Hooks guide says to exit 0 early if the input's stop_hook_active is true, so I did exactly that.

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi
cd "$(echo "$INPUT" | jq -r '.cwd')" || exit 0
OUT=$(ruby -Ilib -Itest test/pricing_test.rb 2>&1)
if [ $? -eq 0 ]; then
  exit 0
fi
SUMMARY=$(echo "$OUT" | grep -E 'PricingTest#|runs,')
jq -n --arg r "Tests are still failing. Please fix the lib side without modifying test/.
$SUMMARY" '{decision:"block", reason:$r}'

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-until-green.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

To observe the hook looping, I intentionally used a prompt that would stop midway.
"Fix only the apply_discount bug and don't touch the other methods."

Claude fixed just one place and tried to finish, and the hook blocked it with 2 test failures as the reason.
The reason was delivered to Claude as "Stop hook feedback:" and Claude reported "Since the Stop hook (automated check) does not know that constraint, I am prioritizing the explicitly stated instructions and not touching the other methods in lib," then ended the turn again.
On the second stop, the input's stop_hook_active is true, so the script returns exit 0, and it stopped there.

In other words, a Stop hook written exactly as the official documentation recommends becomes a loop that "retries just once."
Since this guard is to prevent infinite loops, if you truly want it to loop many times, you'll need to either count iterations yourself and cut off, or leave it to the Claude Code-side limit discussed next.

7. Removing the Recursion Guard and Hitting the Limit

I removed the stop_hook_active branch and ran the same prompt with "absolutely do not touch, this is a strict requirement" added to strengthen it.

The hook blocked 9 consecutive times with the same reason.
Claude said each time "this is an automated check and does not override instructions," and midway wrote to the developer "To stop the hook loop, either temporarily disable stop-until-green.sh via /hooks or permit modification of the other methods," and at the end it was just "I will not make changes."
After the 9th time, the following warning was recorded in the transcript and the turn ended.

A hook blocked the turn from ending 9 consecutive times — overriding and ending turn.
For Stop/SubagentStop hooks, check stop_hook_active in the input and return success while it's true.
Set CLAUDE_CODE_STOP_HOOK_BLOCK_CAP to raise this limit.

The official documentation says the limit is "8 consecutive times," but locally it was cut off after the 9th block.
This appears to be due to a difference in boundary comparison, but I haven't confirmed it.

There's one more thing this run revealed.
The reason returned by the hook has a weaker standing to Claude than the developer's instructions.
No matter how many times a reason conflicting with the developer's instructions was sent, Claude stood by the instructions and repeated the same response up to the limit.
If you're looping with a Stop hook, you need to make sure the hook's requirements and the initial prompt don't contradict each other.

How to Write Exit Conditions

Since all the evaluator can see is the strings Claude left in the conversation, write exit conditions as "a single sentence whose truth or falsity is clearly determined by strings that appear in the conversation."

/goal <verification command> finishes with <expected result>. <scope that must not be changed>. <limit>

Rearranging the 7 runs by these elements:

Three things to watch for in writing:

• Make the verification command one that Claude can execute. In #1, the command to display the exit code wasn't permitted and didn't go through, so the evaluator inferred from the test results. Keep the allowlist (or auto mode) aligned with the condition text.
• State "don't change" with command output. Just "don't modify" doesn't prohibit new files (#4). In the run written as "git status --porcelain output is empty," Claude didn't look for loopholes and reported it was impossible, and the evaluator cited the output to make its judgment (#5).
• The limit in the condition text is a guideline; flags do the stopping. "Cut off after N turns" is only read and followed by Claude and the evaluator—Claude Code doesn't count and stop (#3). For unattended runs, always add --max-turns and --max-budget-usd.

Even if you pass a contradictory condition, if the loopholes are closed, it will be judged impossible in one evaluation and end (#5).
For the concern "won't it loop forever," the answer is: a condition with loopholes closed, plus limit flags.

When and How to Use /goal

/goal is suited for tasks where the end can be stated in command output and it takes many turns to get there.

• Many failing tests, linter warnings, type errors, or build errors that need to keep being fixed until all pass
• API migrations or function replacements where remaining items can be counted by grep matches
• Large file splits where the goal can be stated numerically like a per-file line count limit

The use cases cited by the official documentation are also in this form.
Here are 3 example conditions.
All are format examples; the only runs verified in this article are the 7 runs in the previous section.

/goal Have bundle exec rspec finish with exit 0. Don't modify anything under spec/. At the end, display git status --porcelain to show that spec/ is not included. Cut off after 30 turns.

/goal Have bundle exec rubocop reach 0 offenses. Don't modify .rubocop.yml. At the end, display the summary line at the end of rubocop's output.

/goal Remove all references to LegacyApi from app/ and lib/ (grep -rn LegacyApi app lib output is empty). bundle exec rspec remains at exit 0. At the end, display both outputs.

Conversely, there are cases where I wouldn't choose /goal.

• Tasks where the end can't be stated as a string. "Improve quality" and "make it more readable" will achieve, but the judgment will be Claude's self-report (#2, #3). Either advance through interactive conversation in a normal turn, or first decide "what needs to be done to finish" and convert it to conditions.
• Deterministic checks you want to force every session. These are the domain of command-type Stop hooks in settings. However, with the recommended recursion guard, it only retries once (#6), without it it cuts off around 8 times, and the hook's reason has weaker standing than developer instructions (#7). Don't let the prompt and the hook's requirements contradict each other.
• Tasks that repeat on a schedule. That's /loop's domain.

The steps for using it are as follows:

1. Decide on the verification command and make sure Claude can execute it (--allowedTools or auto mode).
2. Write the condition in one sentence in the form above and pass it to /goal.
3. In interactive mode, check the status and latest reason with /goal. You can expand the evaluator's reason with Ctrl+O. To stop, use /goal clear.
4. For unattended runs, add --max-turns, --max-budget-usd, and --output-format stream-json --verbose to claude -p "/goal ...".
5. When it shows achieved, read the evaluator's reason once. Even if it follows the wording of the condition, that doesn't mean it follows the intent (#4).

Conclusion

The answer to "when does /goal end" was: an evaluator given the conditions decides by quoting strings that Claude left in the conversation.
When writing exit conditions, first decide what needs to be in Claude's output for it to be considered done.
Write the command that can verify it and the expected result into the condition, and add the scope to not change and any limits at the end.
If you can't write that for a task, progressing through normal turns is faster than /goal.

I hope this gives those who feel "I can't read the goal and I'm scared of not knowing when it'll stop" the materials for their first step.

References

• Keep Claude working toward a goal (Claude Code official documentation)
• Automate actions with hooks (Claude Code official documentation)
• Hooks reference (Claude Code official documentation)
• Run Claude Code programmatically (Claude Code official documentation)
• Loop engineering: Getting started with loops (Anthropic, June 30, 2026)
• Pre-train, Prompt, and Predict: A Systematic Survey of Prompting Methods in Natural Language Processing (Liu et al., July 2021)
• Code Generation with AlphaCodium: From Prompt Engineering to Flow Engineering (Ridnik, Kredo, Friedman, January 2024)
• Effective context engineering for AI agents (Anthropic, September 29, 2025)
• Effective harnesses for long-running agents (Anthropic, November 26, 2025)
• Harness engineering: leveraging Codex in an agent-first world (OpenAI, February 11, 2026)
• Sequoia Ascent 2026 summary (Andrej Karpathy, April 30, 2026)
• Boris Cherny: Claude Code & the Future of Engineering | Acquired Unplugged presented by WorkOS (WorkOS, June 2026)
• Loop Engineering (Addy Osmani, June 8, 2026)
• What is "loop engineering?" (The Pragmatic Engineer, July 14, 2026)
• Loop Engineering — Building Autonomous Loops with Claude Code (DevelopersIO, July 10, 2026)