/goal in Codex and Claude Code: why the prompt should be short and the roadmap detailed

Briefly: The /goal command in Codex and Claude Code is not the place for a long TK. Keep the prompt itself as short as possible, and make all the complexity in advance in the documentation and roadmap with checkpoints. Then /goal turns into one line of the type “fulfill the entire roadmap.md implementation plan”, and checkpoints become the very conditions of completion under which the agent checks himself.

• **Problem: ** The long target in the prompt "floats" - after the context is compacted, the agent loses the thread and repeats the steps.
• Resolution: Transfer the plan from the prompt to a file that the agent rereads.
• Formula: documentation → roadmap with checkpoints → short /goal.
• **Bottom line: ** Predictable standalone run instead of "how many hours context is enough.".

## What is /goal and where did it come from

The usual request to an agent is one move: you write, the agent does, stops and waits for the next message. /goal changes mode: you set a target with the condition of completion, and the agent works in a circle plan → act → test → review → iterate until the condition is met.

In Codex, the team arrived in CLI version 0.128.0 (April 30, 2026). Under the hood is not “background autonomy without borders”, but, as OpenAI itself formulates, scoped, user-controlled completion contract: you determine the outcome, Codex works against evidence in the thread, and the goal can be paused, renewed or cleared (/goal pause, /goal resume, /goal status, /goal clear). The target state is stored separately (one target per thread, active / paused / budget_limited / complete statuses), so it experiences a continuation of the session.

In Claude Code, /goal is similar: you set a goal and a measurable completion condition, Claude plans, executes, checks and repeats itself, and a separate fast model decides after each move whether the condition is met or not. This is a built-in version of the very “keep-going” cycles that were previously assembled by hand. Nearby live /loop (scheduled), routines and checkpoint system with rollback through /rewind.

The main thing to understand is that /goal does not "remember your sheet" - it is checked over and over again with the condition of completion. And it depends on where this condition lives.

## Why long /goal is a bad idea

The temptation is obvious: since the agent will work for hours on its own, let’s put in /goal detailed TK on three screens. In practice, it shoots in the foot for three reasons.

Context is compact, and with it the target floats. Long autonomous runs rest on the context limit. With compaction, the agent loses some of the story — and, as users complain in OpenAI threads, begins to re-plan and execute the same steps, losing progress. The more goals you held only in the prompt, the more is lost when compressed.

Prompt is not an anchor. The completion condition is checked on each turn. If it is formulated as a blurry sheet, the little checking model has nothing to cling to: it cannot unequivocally say “ready”. A short, specific condition is tested more reliably than a long one.

**Long prompt cannot be versioned and ruled. You can’t see the whole thing, you can’t gently correct one item without restarting everything. And the plan in the file, you read, edit, commit.

The conclusion is simple: the long text should lie where the agent can read it at any time: in the file. In /goal, the pointer to this file remains.

## Main idea: short /goal + roadmap with checkpoints

The working joint looks like this:

1. Documentation - briefly describe what and why we build, stack and restrictions.
2. ** Roadmap with checkpoints** - cut work into phases, each phase has a measurable condition "ready".
3. Short /goal - one line sends the agent to execute the roadmap plan.

The point is that all the complexity and all the decisions are fixed in the files that the agent rereads, not in a one-time prompt that shrinks and forgets. Checkpoints from the roadmap work as ready-made completion conditions for the testing model: “Phase 3 is closed when X tests are green.” An agent doesn’t have to guess what you think is a success, you’ve written it.

## Step 1. Documentation

Before calling /goal, put a short document (or update AGENTS.md) into the project that answers the questions:

• What we're building and why. ** One or two sentences about the purpose of the feature.
• Stack and boundaries. What technologies, what folders can be touched, what can not be touched.
• ** Rules.** Style, which libraries to prefer, which is forbidden (e.g., "don't add new addictions for no reason").
• **What counts as "done." ** Tests pass, linter clean, assembly green.

It's not a 20-page novel. The task is to remove ambiguity so that the agent does not make product decisions on the go. It’s basically the same principle as spec-driven development: first contract, then code.

## Step 2: Checkpoint roadmap

Roadmap is the heart of the approach. Here the plan turns into a sequence of phases, each of which has a checkpoint. Not "do backend," but specific steps with a completion condition that can be verified by the team.

Example of roadmap.md:

Roadmap: Exporting orders to CSV

Phase 1. Model and migration
- [ ] Add the order export log table
Checkpoint: `npm run migration:lint` passes, migration is applied on a clean database

##Phase 2. Export Service
buildOrdersCsv(period, role)
Rights: Manager only and above, otherwise 403
Checkpoint: `npm test -- orders-export` - all tests are green

Phase 3. Endpoint and limits
- [] POST /api/orders/export
Up to 50,000 lines synchronously, more in the background
Checkpoint: e2e test for 403, empty period and limit passes

Phase 4. Ready.
Checkpoint: build:ci green, coverage not dropped, roadmap fully marked

The key here is every checkpoint machine-checked. "Tests are green," "assembly passes," "endpoint returns 403" are what the test model can confirm by the conclusion of the command, not by sensation. It is checkpoints that prevent the agent from looping in or declaring “ready” ahead of time.

## Step 3. Short /goal

When the documentation and roadmap are in place, /goal itself becomes almost trivial. The whole idea is already in the files - the team has to point to them and set a stop rule.

Minimum option:

/goal complete the entire roadmap implementation plan. md

Slightly more secure - with a clear stop rule and order:

/goal implement roadmap.md in phases from top to bottom.
After each phase, run her checkpoint and mark the points.
Stop on the first checkpoint that fell - don't go any further.

Note that even the “protected” option is three short sentences. Everything else lives in roadmap.md, which the agent rereads in each phase.

The difference between the tools is small, but it is useful to keep in mind:

• Codex. Check that /goal is included in config.toml, otherwise it will not be on the TUI command list. Control the run through /goal status, /goal pause, /goal resume. Remember the 5 o'clock window and budget_limited status.
• Claude Code. The completion condition after each move is checked by a separate fast model, so formulate checkpoints so that they can be confirmed objectively. Before large runs, make sure that the checkpoint system works and /rewind is your insurance against unsuccessful iteration.

## Why does it work

The “short /goal + roadmap with checkpoints” bundle hits three weak points of autonomous runs at once.

Checkpoints = completion conditions. The testing model doesn’t need to interpret your intentions – it has a specific criterion for whether the team passed or not. This drastically reduces both false “ready” and endless cycles.

The file survives the context compaction. Even when the story compressed and the agent "forgot" the beginning, roadmap.md did not go away. The agent rereads it and restores where he left off, according to marked checkboxes. This is a direct cure for the very loss of progress that users complain about.

The plan is in git: it can be seen, it can be corrected between phases, it can be returned to. Autonomy ceases to be a five-hour black box and becomes a controlled process with entry points.

## Real problems

Even with the roadmap, an autonomous run is not “started and left for the weekend.” That's what really breaks down, from the experience of the community.

• Time limit. Codex has a use window (about 5 hours). Plan the phases so that there are natural stop points between them, then budget_limited will not find you in the middle of an uncomplicated change.
• Drift after compaction. Classic complaint: long run + repeated context compressions → agent loses progress and redoes it. Roadmap with marked checkboxes reduces the risk, but still check the progress with your eyes.
• False "ready." ** If the checkpoint is worded blurry (“works”), the checking model may close the phase in vain. Only machine-testable conditions are saved.
• Silent scope creep. Just in case agent does more than roadmaps. The rule in the prompt helps: “Do only what is in roadmap.md, nothing more.”.
• Uncommitted progress. Ask to mark checkboxes and commit after each closed phase, otherwise a rollback on checkpoints or a break in time will erase the opening hours.

## Checklist before launch /goal

• There is short documentation or current AGENTS.md.
• The roadmap is divided into phases, each has a machine-verified checkpoint.
• The stop rule is clear: where the agent must stop and call you.
• It is indicated that you do not need to do (frame).
• /goal itself is 1-3 short sentences, not TK.
• For Codex: The command is included in config.toml.
• For Claude Code: Checkpoints and /rewind work as insurance.
• The agent commits after each closed phase.

## Frequent questions

If you just give /goal with a detailed TK, wouldn’t it work? ** It works on a short task. On the long one, it will begin to float: the context will shrink, the agent will lose part of the target and can go in circles. The file with the plan cures it because it can be reread.

**How does /goal differ from a conventional prompt? ** The usual prompt is one move and a stop. /goal is a plan → act → test → review cycle that rotates until the completion condition is met. Therefore, the condition should be verifiable, not do well.

What to write in checkpoint? ** What the team can check is “X tests are green”, “build passes”, “endpoint gives 403”. Everything that is checked by eye is a bad checkpoint.

Is it the same as spec-driven development? ** Cognate approaches. SDD is about how to formalize requirements to code. Here, we take the finished plan and give it to the /goal autonomous cycle. Roadmap with checkpoints is a natural continuation of the bake.

Codex or Claude Code?* The mechanics are close. Codex provides explicit target control (pause/resume/status) and requires inclusion in config.toml. Claude Code checks the condition with a separate fast model and is insured by a checkpoint system with /rewind. Choose according to what you already work in.

## Conclusion

/goal is a powerful mode, but it enhances both order and chaos. If you pour a long TK into it, you get an autonomous problem generator, which also loses the thread at a long distance. If you invest in short documentation and roadmap with machine-verified checkpoints, the /goal itself collapses to one honest line: “fulfill the roadmap.md plan.”.

A rule worth remembering: All complexity is in the files, in the prompt, only the pointer. The shorter your /goal and the more detailed the roadmap, the more predictable the outcome.

## What to read next

• Spec-driven development: как писать ТЗ, чтобы ИИ-агент не додумывалXX
• AGENTS.md: единый источник истины для ИИ-агентовXX
• Memory Bank: хранение контекста для ИИ в разработке проектовXX
• Как писать тесты через ИИXX