# Ships a change with a coding agent through plan, implement and verify

> Competency coding-with-agents/ships-with-agent

Page: https://schubergphilis.github.io/ai-training/competencies/coding-with-agents/ships-with-agent/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

*Coding with agents* · competency `coding-with-agents/ships-with-agent`

**Taught in:** the [Coding with agents](https://schubergphilis.github.io/ai-training/coding-with-agents/) course

**Draws on:** [Running a coding agent](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/first-session/), [Plan, implement, verify](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/workflow/), [Context engineering for code](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/context/)

## Learning objectives

### Runs a session from setup to a reviewed diff (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner has the agent describe the codebase and confirm the plan before it edits anything. | A wrong model of the repository produces a confident change in the wrong place, and it is cheaper to correct a sentence than a diff (Claude Code 101, Claude Academy). | The learner asks "where is the config loaded and which tests cover it?" and checks the answer against the tree before saying "go ahead". |
| Every session ends with the learner reading the full diff. | The summary is the agent's account of what it meant to do, and the diff is what it did. | The summary says "added validation", and the diff also shows a deleted test, which the learner catches and asks about. |
| The learner keeps a session to one task and starts a new one when the task changes. | A long session carries stale assumptions in context, and the agent keeps acting on the earlier task's constraints. | After the bug fix is committed, the learner opens a fresh session for the refactor instead of typing "now also" into the same one. |

Served by: [Your first session with a coding agent](https://schubergphilis.github.io/ai-training/coding-with-agents/first-session/), [Keeping API keys out of the agent's reach](https://schubergphilis.github.io/ai-training/coding-with-agents/keys-and-secrets/), [Plan first, then drive the change from a failing test](https://schubergphilis.github.io/ai-training/coding-with-agents/plan-then-test/), [Sandboxing a coding agent](https://schubergphilis.github.io/ai-training/coding-with-agents/sandboxing/)

### Works in small increments, sequenced for early feedback (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| Each increment leaves the system working and adds one thing that can be shown. | A working state after every step means a mistake is found in a small diff and the last good state is one step back. | The learner asks for "the endpoint returning a hard-coded response first, then the real query, then the caching", and runs the app after each. |
| The learner sequences increments so the riskiest assumption is tested first. | Finding out on day one that the external API does not return what you expected is cheap, and on day five it is not. | The integration with the payment provider is the first increment, because its behavior is the least known. |
| An increment is committed when its check passes, before the next one starts. | A commit per increment gives a point to return to and a diff a reviewer can read. | Three small pull requests with green tests replace one large one at the end of the week. |

Served by: [Working from a spec in small increments](https://schubergphilis.github.io/ai-training/coding-with-agents/spec-driven-increments/)

### Keeps every change reversible (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| Every change is on a branch and in commits small enough to revert one at a time. | Reverting is the cheapest fix there is, and only if the change is isolated. | The learner has the agent commit after each passing increment instead of one commit at the end. |
| Data and schema changes are designed with the way back written down before they run. | Code reverts in a second, and a migrated table does not. | The migration adds the new column, the code writes both columns, and then a backfill fills the old rows. Dropping the old column is a separate change a week later, after the code has run on the new one. |
| The learner prefers a change that can be turned off to one that can only be undone. | A feature flag or a configuration switch reverses in seconds and without a deploy. | The new ranking algorithm ships behind a flag that is off by default, and is enabled for internal users first. |

Served by: [Keeping every agent change easy to undo](https://schubergphilis.github.io/ai-training/coding-with-agents/reversible-changes/)

### Gives the agent the files, constraints and limits the task needs (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner names the files the task touches and the files it must not touch. | Left to search, an agent finds the nearest plausible file, and the nearest one is often the wrong one. | "Change the retry logic in `src/http/client.ts`; the tests are in `tests/http/`; leave `src/http/legacy/` alone" instead of "fix the retries". |
| Constraints that are not in the code are stated in the brief: style, compatibility, what must keep working. | The agent cannot infer a rule it cannot see, and a project convention lives in people's heads until it is written down. | The learner adds "this must stay compatible with Node 20 and must not add a dependency" because neither fact is visible in the file being edited. |
| The learner gives the verification command along with the task. | An agent that knows how the work will be checked runs the check itself and reports honestly against it. | "Done when `npm test -- http` passes and the lint task is clean" lets the agent close its own loop before handing back. |

Served by: [Your first session with a coding agent](https://schubergphilis.github.io/ai-training/coding-with-agents/first-session/), [Writing project instructions the agent reads every session](https://schubergphilis.github.io/ai-training/coding-with-agents/project-instructions/), [Telling the agent where the task is and where it stops](https://schubergphilis.github.io/ai-training/coding-with-agents/scoping-and-referencing/)

### Keeps their own understanding of the code as the agent produces more of it (expert)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner can explain, without looking, how the parts the agent wrote fit into the system and why they were built that way. | An engineer who cannot explain the system cannot review changes to it, and the agent's next change goes unchecked. | Asked in a design review why the cache is keyed by user rather than by request, the learner answers from their own understanding without opening a transcript. |
| The learner reads agent-written code with the same attention as a colleague's, and asks the agent to explain anything they do not follow. | Understanding is built while reading, so skipping the reading skips the understanding. | The learner stops at a regular expression they cannot parse and asks for a plain-language explanation and a test that documents it. |
| The learner keeps the architecture decisions and the reasons for them in a place the agent also reads. | A decision that is only in someone's head gets contradicted by the next session. | The project's `docs/decisions/` folder records why the queue is in-process, and the project instructions point the agent at it. |

Served by: [Staying the engineer who understands the system](https://schubergphilis.github.io/ai-training/coding-with-agents/keeping-understanding/), [Writing project instructions the agent reads every session](https://schubergphilis.github.io/ai-training/coding-with-agents/project-instructions/)

### Chooses deliberately what each phase of work starts with, including the starting context (expert)

| Claim | Why | Example |
| ----- | --- | ------- |
| At the end of a phase the learner decides whether to carry on, clear, compact, hand off or delegate, and can say why. | The next phase needs either the history or a clean window, and carrying on by default keeps everything whether it helps or not (Best practices for Claude Code, Claude Code documentation). | After the design interview produces a spec, the learner starts a fresh session with the spec file instead of implementing in the long planning session. |
| The learner checks a project's starting context with the context command and removes what does not earn its place. | The starting context is sent with every request and leaves less room for the task (Explore the context window, Claude Code documentation). | The breakdown shows three servers nobody uses and a 400-line instruction file, so the learner disconnects the servers and moves two sections into skills. |
| Before clearing or compacting, the learner writes down what the next phase must keep. | Compaction keeps a summary and drops the detail, and clearing drops everything. | The learner has the agent write the changed files and the open decisions into a handoff file, reads it, and then clears the session. |

Served by: [What each phase starts with](https://schubergphilis.github.io/ai-training/coding-with-agents/what-a-phase-starts-with/)

## Alignment

| Framework | Code | Asks | Objectives here |
| --------- | ---- | ---- | --------------- |
| Ng, AI engineering skills map | Using coding agents | Plan, execute, verify, monitor at calibrated autonomy | runs-a-session, works-in-increments, keeps-change-reversible, gives-the-right-context, keeps-understanding |
| AI Fluency 4D (Dakan and Feller) | Description | State the goal, context and wanted output clearly, and refine it | gives-the-right-context |
| Brilliant Coding with AI | SPC-5, BLD-1 | Manage constraints; direct an agent to a specification | gives-the-right-context |
| Brilliant Coding with AI | INC-1, INC-2, INC-5 | Working increments, early feedback, reversibility | works-in-increments, keeps-change-reversible |
| Brilliant Coding with AI | INC-3, INC-4 | Maintain understanding and coherence | keeps-understanding |

## References

- Claude Code 101, Claude Academy, https://academy.claude.com/courses/claude-code-101
- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices
- Explore the context window, Claude Code documentation, https://code.claude.com/docs/en/context-window