Greetings, traveler!
A build optimization task can take much longer than the code change itself. An agent inspects the build graph, runs a baseline, changes a script, waits for another build, and discovers that the apparent improvement disappears on a second run. A useful investigation might take hours even if each individual edit is small.
The longer that process runs, the more its reliability depends on what surrounds the model. The agent needs a way to preserve its findings, distinguish a failed command from an unfinished one, and stop when further attempts are unlikely to help. It also needs a working environment that can survive interruptions without turning a retry into a duplicate external action.
This article uses a hypothetical iOS build optimization as a running example. The same concerns apply to CI migrations, dependency upgrades, and other tasks where work proceeds through many changes and checks.
Start with a bounded objective
“Make the build faster” gives an agent too much room to decide what to change and when to stop. An assignment should describe the workload being measured, the boundaries of the experiment, and the conditions for accepting a result.
For example, a team might ask an agent to investigate incremental build time for its main iOS scheme after a small Swift source edit. The task permits changes to build scripts and project configuration on an isolated branch. It excludes publishing artifacts, changing release signing, and weakening tests to improve the reported time.
A starting brief could say:
Goal: investigate and reduce incremental build time for the App scheme.
Workload:
- Build once to prepare the build directory.
- Change a comment in a designated Swift source file.
- Build the same scheme and destination again.
Constraints:
- Preserve generated outputs and existing test coverage.
- Do not modify release signing or deployment settings.
- Work on the assigned branch in an isolated checkout.
Acceptance:
- The same workload succeeds before and after the change.
- The improvement is repeatable under comparable conditions.
- Required tests pass on the final revision.
- Report the commands, environment, measurements, and remaining risks.
Stop if the environment is unreliable, a change requires broader approval,
or the investigation reaches its budget without a defensible improvement.
The comment edit is a controlled stimulus, not a universal proxy for developer work. The compiler may handle it differently from a change to implementation or a public interface. A team should include representative edits, such as changing a function body in a leaf module, and measure changes to shared interfaces and clean builds separately. Improving one workload does not prove that the others improved.
The investigation can also end without an optimization. If repeated measurements show no reliable gain, the correct result may be a report that explains what was tried and what remains uncertain.
Separate an agent session from the overall run
Within one session, an agent typically repeats a familiar sequence: inspect the available information, choose an action, call a tool, and use the result to decide what to do next. That inner loop may perform several edits and commands before the agent returns a result.
A longer workflow can put another loop around those sessions. An outer controller starts a session for the next bounded step, checks the outcome, saves progress, and decides whether another session is warranted. A fresh session can receive the current objective, relevant findings, and paths to evidence instead of an ever-growing conversation history.
The controller might select one candidate build script per iteration. The agent inspects its dependencies, proposes a change, runs the prescribed checks, and records the outcome. The controller then either schedules the next candidate or pauses for a decision.
Ralph Loop describes a family of approaches that repeatedly run an agent against a task. Implementations vary: some restart the agent with a fresh context; others reintroduce the task when a session attempts to finish. Files, Git history, and other external state can carry progress between iterations. The repeated prompt alone does not guarantee that an iteration starts with accurate state or that the work is complete.
The outer loop needs an independent completion check and a limit. A successful build, for example, confirms that a particular build command succeeded. It does not establish that a build script still produces correct outputs in every relevant situation. The acceptance decision may combine automated checks, repeated measurements, and human review.
The following pseudocode sketches a bounded controller. It leaves implementation details such as persistence, timeouts, and authorization to the surrounding system:
repeat up to iteration_limit:
reconcile workspace and any unfinished operations
if state is uncertain or approval is required:
pause and report
if time or cost budget is exhausted:
stop and report
run one agent session with the task and current checkpoint
independently run the checks appropriate for that iteration
persist the outcome and update the checkpoint
if completion criteria are satisfied:
report the evidence and stop
report that the iteration limit was reachedThe controller must enforce its limits outside the model session. A prompt asking the agent to stop is useful guidance, but it is not an execution timeout or a spending limit.
Preserve the state needed to resume
A conversation summary can help the next session understand the investigation. A checkpoint has a different job: it records enough operational state to decide where execution can safely continue. A checkpoint may include a summary, but it also needs references to the actual workspace and verification results.
For the build task, a small checkpoint could look like this:
run_id: build-investigation-042
status: measuring
base_revision: 2f184a9
candidate_revision: 91ab37c
workspace: /work/build-investigation-042
current_step: measure_incremental_build
attempt: 2
workload:
scheme: App
configuration: Debug
destination: iOS Simulator, fixed runtime and device
scenario: comment edit in designated source file
artifacts:
baseline: results/baseline.json
candidate: results/candidate-91ab37c.json
latest_log: logs/measurement-02.log
next_action: repeat the candidate measurementThis is an illustrative format, not a configuration for a particular product. A real controller must validate the checkpoint and store it somewhere that survives the failure it is expected to recover from. A checkpoint written only to a temporary runner disk cannot restore work after that disk is lost. Likewise, a commit hash identifies committed code but does not preserve uncommitted changes or generated files.
Use stable artifact storage or a remote branch where appropriate. If work is intentionally uncommitted, capture the patch and relevant untracked files, or treat the checkpoint as incomplete. The checkpoint should record the version of the task configuration and tools as well as the revision; otherwise, the next session may compare results produced under different conditions.
On restart, inspect the actual workspace before continuing. Check that the revision and working tree match the recorded state, confirm that referenced artifacts exist, and check whether a previously launched process or remote job is still running. If the workspace has changed independently, pause and reconcile the difference instead of applying an old plan blindly.
Use an event log to explain how the run got there
A checkpoint describes the current position. An event log preserves the sequence of significant actions that led to it. The distinction is useful when a checkpoint says a measurement is incomplete but a build may already have been started.
An event record might contain a run ID, an operation ID, a timestamp, the revision, the command or job identifier, and the result. Store full logs separately and refer to them by path or artifact ID. A compact session summary can then point to the relevant evidence without feeding every build line back into the model. The following illustration uses JSON Lines, with one JSON object per line:
{"event":"build_started","operation_id":"measure-02","revision":"91ab37c","log":"logs/measurement-02.log"}
{"event":"build_finished","operation_id":"measure-02","exit_code":0,"result":"results/measurement-02.json"}These records are examples, not evidence of a real run. Logs can contain source code, paths, tokens, or customer data, so access controls, retention, and redaction deserve the same attention as other CI artifacts.
An append-only log does not automatically make a workflow recoverable. Recovery requires a defined interpretation of events, reliable persistence, and a strategy for actions that may have happened without a recorded result. The event log helps reconstruct what is known; it cannot prove that an external action did not occur merely because the final event is missing.
Treat uncertain outcomes as a separate state
Consider a CI migration in which an agent submits a test pipeline and loses its connection before receiving the job ID. The request might never have arrived, or the service might have created a job whose response was lost. It is also possible that the service is still processing the request. Retrying immediately can create a second job.
A safer sequence records an operation identifier before submission, then stores the returned external job ID as soon as it is available. If the response is lost, the controller queries the provider using a supported correlation key or other reliable metadata. If the service supports idempotency keys, the same key can be reused for retries of the same logical request. The remote service must enforce that key for it to prevent duplicates.
When the outcome cannot be established, mark it as unknown and pause for reconciliation. Assuming failure is particularly costly for operations such as publishing artifacts, creating releases, or changing shared infrastructure.
Operations differ in their retry behavior:
- Reading a file is usually safe to repeat, although its contents may have changed.
- A local build is generally repeatable, but it can consume resources and alter caches or derived outputs. Use isolated paths and record the environment.
- Submitting a remote pipeline may create a new billable job on every attempt. Check the prior submission first.
- Publishing or deploying can affect other people and should use a separate, explicitly authorized process.
Idempotency means that repeating the same logical operation leaves the relevant system state as it would be after one successful execution. Individual responses do not have to be identical. A retryable workflow should make that property explicit rather than assuming that every command or API call has it.
Recover from failures without repeating every step
Failures require different responses. A temporary network error while fetching a build result may justify a bounded retry with a delay. A compiler error caused by the candidate change calls for diagnosis. A missing signing credential or an unexpected change to a shared environment may require a person to intervene.
A practical controller can distinguish at least these outcomes:
- Completed: the action returned a result and the result was recorded.
- Failed: the action returned a known failure. Classify it before retrying.
- Unknown: the action may still be running or may have completed without a recorded response. Reconcile it first.
- Blocked: progress depends on access, a decision, or an environment repair.
Retries need a maximum attempt count and an overall deadline. Backoff and jitter can reduce pressure on a service during a transient outage. For a deterministic compiler error, running the same build repeatedly without a change rarely adds information; preserve the failure, inspect it, and test a specific hypothesis instead.
Some orchestration systems provide durable execution. Temporal, for example, reconstructs workflow progress from recorded history and can retry activities after a worker failure. Its workflow code must follow replay constraints, and an activity with external side effects can still execute more than once if its completion is not recorded. Idempotent activities or reconciliation remain necessary.
LangGraph offers checkpointed graph state and mechanisms for resuming execution. A persistent checkpointer must be configured for state to survive a process restart. Depending on the graph and interruption point, execution can resume at the beginning of a node, so code in that node may run again. Side effects inside it need their own retry or reconciliation strategy. These tools can reduce the amount of recovery machinery a team writes, but neither can decide whether a repeated deployment or an ambiguous build result is acceptable for the task.
Measure one change at a time
Build performance is noisy. Machine load, thermal conditions, cache state, package resolution, Xcode version, simulator runtime, and background processes can all affect a run. An agent can easily mistake that variation for an improvement.
For the hypothetical investigation, start by recording the machine and toolchain, scheme, configuration, destination, and exact commands. Run several baseline measurements using the same preparation and edit procedure. Preserve both the elapsed time and the build output. Xcode can also provide a build timing summary through xcodebuild:
mkdir -p .build-investigation
xcodebuild \
-workspace App.xcworkspace \
-scheme App \
-configuration Debug \
-destination 'platform=iOS Simulator,name=iPhone 16' \
-derivedDataPath "$PWD/.build-investigation/DerivedData" \
-showBuildTimingSummary \
build > .build-investigation/baseline.log 2>&1
build_status=$?
printf 'Build exit status: %s\n' "$build_status"This command is a Bash template. Use an installed destination and paths appropriate to the project. The status is captured immediately after xcodebuild; check that it is zero before treating the run as a successful measurement. The command alone does not perform the warm-up, source edit, repeated measurements, or tests described above.
Suppose the timing output suggests that a code-generation script runs after every small source edit. The agent inspects the script and its declared inputs and outputs. If those declarations do not reflect the script’s actual dependencies, the agent can propose a correction and test it.
That change needs more than a faster second build. The agent should modify a real input and confirm that generation runs, then perform an unrelated edit and confirm that skipping the script leaves outputs correct. It should also check clean builds and relevant tests. Incorrect input or output declarations can produce stale generated code and make a build appear faster by omitting necessary work.
Compare repeated baseline and candidate runs under comparable conditions. One practical setup uses a separate checkout and DerivedData directory for each revision, avoiding rebuilds caused by switching revisions in the same working tree. For each sample, prepare the relevant checkout and its build directory in the same way, perform the same designated edit, and record the result. Avoid simultaneous builds on the same machine unless contention is part of the workload being tested.
Report individual measurements and a summary such as the median, together with the observed variation. Alternate baseline and candidate measurements when practical. Separate build directories do not eliminate noise, so check that both environments use equivalent toolchains, dependencies, and cache preparation. If the measurements vary too much to distinguish an improvement, or if the environment changed, report the result as inconclusive.
Follow an investigation through an interruption
Consider one hypothetical run using the setup above. The agent records baseline measurements and the revision used to produce them. It identifies a generation script that runs after an unrelated edit, then changes the script’s declared inputs and outputs on the candidate branch.
The agent checks that the script runs when a real input changes and that generated outputs remain correct after an unrelated edit. It saves the check results and starts repeated candidate measurements. After the first measurement, it records the candidate revision, artifact paths, and next action in a checkpoint. The event log records the build start and its exit status.
During the next measurement, the agent process loses access to its execution environment. On restart, the controller checks the working tree and verifies that the checkpoint and saved artifacts still match. It then determines whether the interrupted build process is still running and whether a trustworthy exit status was recorded. If the process has finished without a reliable result, the controller marks that measurement inconclusive and runs a fresh measurement in the isolated environment. If the environment itself cannot be reconciled, it pauses for an engineer.
Once the repeated measurements and required checks are complete, the report identifies the final candidate revision, the workload, individual timings, and the test outcomes. It also describes any incomplete checks. If the candidate did not improve performance reliably, the report retains the results without claiming success.
Decide when to stop or ask for a person
A completion condition belongs outside the agent’s own declaration of success. For this investigation, the controller can require a final successful build, relevant tests, recorded measurements, and a report linked to the final code revision. An engineer still decides whether the change and the evidence are sufficient for the team’s workflow.
The controller should also stop when:
- the time, token, spending, or iteration budget is exhausted;
- the same failure recurs without new diagnostic evidence;
- the working tree or environment no longer matches the checkpoint;
- a required test cannot run or a measurement cannot be trusted;
- the next action exceeds the permitted scope;
- an external operation has an unknown outcome.
A spending limit works only if the system enforcing it can observe and control the relevant charges. A token budget may cover model calls while excluding CI minutes or third-party services. Record those budgets separately, and leave room for final verification and reporting.
Approval should identify the actual decision: the proposed action, target environment, expected effect, evidence, and recovery option. A generic “continue?” prompt gives a reviewer little to evaluate. For example, an agent may prepare a pipeline configuration and test it in a non-production environment, then request approval for a production configuration change if that action is outside its authorized scope.
Choose the amount of machinery the task deserves
A small task that takes one session and has no external side effects may need only a branch, a short plan, and a final verification. Adding a queue, durable workflow engine, and detailed event schema would create more work than it saves.
A long investigation running on a developer’s machine can often start with a task file, an isolated checkout, saved logs, and explicit limits. If runs must survive machine loss, wait for remote jobs, or coordinate several services, persistent storage and a dedicated orchestrator become more valuable. The relevant question is which failures the team needs to survive and who will operate the recovery process.
For the build optimization, a finished report should make the result independently reviewable: which revision was tested, what changed, how the workload was reproduced, which measurements were recorded, and whether required checks passed. If the agent stopped without a defensible improvement, the report should preserve the unsuccessful experiments and the point at which human judgment became necessary. That gives the next engineer a reliable starting point without asking them to reconstruct hours of activity from a chat transcript.
It might be interesting:
- Agent Security: Giving AI Useful Access Without Giving It the Keys
- Multi-Agent Development: When Parallel Work Helps and How to Keep It Under Control
- AI-Assisted Architecture Migration: Keeping Large Refactors Under Control
- AI Code Review: Finding Defects Without Creating More Work
- Systematic Debugging: Finding the Cause Before Changing the Code
