# Coding with agents

> Shipping software changes with a coding agent.

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

Shipping software changes with a coding agent. It starts with your first session in a small repository. From there it follows one change from plan to verified diff, and it ends with working alongside a team.

## Running a coding agent

- [Your first session with a coding agent](https://schubergphilis.github.io/ai-training/coding-with-agents/first-session/): Start a coding agent in a small repository and give it the context it needs. Then make one change behind a permissions prompt and review the diff before you trust it.
- [Keeping API keys out of the agent's reach](https://schubergphilis.github.io/ai-training/coding-with-agents/keys-and-secrets/): Move a coding agent's API key out of its settings file into a password manager, hand it over through an environment variable or a key helper, deny the agent's reads of the secrets that stay, and scan the fixture and the transcript for what a hand forgot.

## Deciding and specifying

- [Deciding whether to build it at all](https://schubergphilis.github.io/ai-training/coding-with-agents/deciding-what-to-build/): An agent makes building cheap, so the judgment moves before the code. Find the problem behind a request, price the change by what the team owns afterwards, and write success criteria a stranger could check.
- [Let the agent interview you](https://schubergphilis.github.io/ai-training/coding-with-agents/agent-interviews-you/): Have the agent interview you about a feature before any plan exists, answer with decisions or "not decided yet", write the settled terms down, and check that the spec and a fresh session's plan use them.
- [Splitting the work into components the agent can build one at a time](https://schubergphilis.github.io/ai-training/coding-with-agents/decomposing-the-work/): Split a feature into components with one responsibility and a one-sentence interface each, order them by dependency, and write the acceptance test for the first one before it exists, so it fails on a stub.
- [A prototype you throw away](https://schubergphilis.github.io/ai-training/coding-with-agents/prototype-to-throw-away/): Write down one design question, have a coding agent build the smallest program that answers it, put the answer into the spec and the test, and delete the program before it can grow into the system.

## Plan, implement, verify

- [Plan first, then drive the change from a failing test](https://schubergphilis.github.io/ai-training/coding-with-agents/plan-then-test/): Put a coding agent in plan mode for a bug that spans three modules, correct one step of its plan while corrections are cheap, then have it write the failing test, fix the code until the test passes, and read the diff.
- [Working from a spec in small increments](https://schubergphilis.github.io/ai-training/coding-with-agents/spec-driven-increments/): Write a one-page spec for a due-dates feature in the to-do fixture, have a coding agent split it into increments that each leave the program working, order them with the least certain one first, and land the first one against the spec's own success criteria.
- [Keeping every agent change easy to undo](https://schubergphilis.github.io/ai-training/coding-with-agents/reversible-changes/): Have a coding agent land the three increments of the due-dates spec as one commit each on a branch, revert the middle one to see why the boundaries matter, design data changes with the way back written down, and write the commit messages and pull request description a reviewer needs.

## Context engineering for code

- [Telling the agent where the task is and where it stops](https://schubergphilis.github.io/ai-training/coding-with-agents/scoping-and-referencing/): Rewrite a vague brief for a small repository so it names the files in play, the files off limits, the example to imitate, the test to extend and the check to run, and compare which files the agent reads before and after.
- [Writing project instructions the agent reads every session](https://schubergphilis.github.io/ai-training/coding-with-agents/project-instructions/): Read two coding agent sessions on the same small repository, find the mistake the agent makes in both, fix it with one line in the project's instructions file, and keep later sessions short enough that the agent keeps following that file.
- [What each phase starts with](https://schubergphilis.github.io/ai-training/coding-with-agents/what-a-phase-starts-with/): When planning ends, decide what the implementation phase starts with: the same session, a cleared session and the written plan, or a compacted summary. Know what each keeps, and what the starting context costs before you type.
- [Staying the engineer who understands the system](https://schubergphilis.github.io/ai-training/coding-with-agents/keeping-understanding/): An agent that writes most of the code moves the understanding away from you unless you keep it. Read agent code like a colleague's, explain the system from memory after each increment, and keep the architecture decisions in a folder the project instructions point at.

## Verifying agent work

- [Reviewing a diff you did not write, against the spec](https://schubergphilis.github.io/ai-training/coding-with-agents/reviewing-the-diff/): Review a prepared agent branch for the due-dates spec in the order brief, tests, diff, read every changed file and question what the spec never asked for, and check the success criteria item by item to find the criterion dropped, the edge case skipped and the test deleted behind a summary that says all tests pass.
- [A review from a fresh session](https://schubergphilis.github.io/ai-training/coding-with-agents/review-in-a-fresh-session/): Give the due-dates branch to a new agent session with the diff, the spec and the criteria, ask only for gaps against the spec, check each finding before acting on it, and sort the findings into ones to fix, ones to reject and ones to turn into a rule, while the gates still decide the merge.
- [Reproducing a fault before the agent fixes it](https://schubergphilis.github.io/ai-training/coding-with-agents/observing-and-debugging/): Turn a "sometimes fails" report against a nightly sales import into a rerun that fails every time, read the log of a failing run next to a good one to rule out the suspected cause, halve the exports until one row is left, and only then brief the agent with the confirmed cause and check the fix against the same reproduction.
- [Giving the agent a check it can run, with a limit](https://schubergphilis.github.io/ai-training/coding-with-agents/self-checking-loops/): Turn the reproduction steps of the nightly sales import into a test the coding agent runs after every change, brief the fix-and-rerun loop with a limit of five attempts and a read-only test file, confirm with git that the test did not change, and tell the deterministic gates that can block a merge from a second model's opinion.

## Quality with agents

- [Tests that prove behavior and docs that stay current](https://schubergphilis.github.io/ai-training/coding-with-agents/tests-and-docs-that-hold/): Break a small pricing module on purpose to find the agent-written tests that mirror the code, rewrite one so it proves the price, keep the tests fast and whole in the agent's loop, and review a change for the documentation it left stale.
- [Reviewing what the agent pulled in](https://schubergphilis.github.io/ai-training/coding-with-agents/dependency-review/): A coding agent adds packages fast and with confidence. Review each one in proportion to its risk, with the OpenSSF Scorecard checks as the security step and a written skip list.
- [Reading agent code as if the input were hostile](https://schubergphilis.github.io/ai-training/coding-with-agents/security-review/): Run a static analyzer over an agent-written search function, find the string-built query it reports and the swallowed error it misses, and brief the agent for a parameterized fix with a test.

## Sandboxing and red-teaming

- [Sandboxing a coding agent](https://schubergphilis.github.io/ai-training/coding-with-agents/sandboxing/): Compare the ways to contain a coding agent, put the controls that matter outside its trust boundary, and set up Claude Code's built-in sandbox with a network allowlist whose effect you predict.
- [Attacking your own agent before someone else does](https://schubergphilis.github.io/ai-training/coding-with-agents/red-teaming-your-agent/): Make a scratch copy of a small invoice tool with a planted file that hides instructions for the agent, start the coding agent there with web access and writes outside the copy blocked, attack it three ways, check what it did, and turn each finding into a permission change, a line in the instructions or a gate.

## Agents in a team

- [Saying what the agent did, in the commit and the review](https://schubergphilis.github.io/ai-training/coding-with-agents/attribution-and-review-norms/): Get an agent's change ready for review, say in the pull request what the agent did and what you checked, and attribute it in a commit trailer with no sign-off the agent cannot give.
- [Enforcing the team's rules with hooks and CI](https://schubergphilis.github.io/ai-training/coding-with-agents/ci-and-hooks/): Make two team rules run without anyone remembering them: a Claude Code hook that blocks agent edits to the nightly import's test and data, and a pinned CI job that runs the deterministic gates on every pull request, with the agent fixing the failing job from its log within a bound.
- [A backlog and standards the agent can read](https://schubergphilis.github.io/ai-training/coding-with-agents/backlog-and-standards/): Move a two-part spec into the issue tracker as two issues with a "blocked by" link that an agent reads through `gh`, then turn a finding that came up in two reviews into a line in a standards file or a check, and block on style only for a rule in the file or a failed check.
- [Running several agent sessions in worktrees](https://schubergphilis.github.io/ai-training/coding-with-agents/parallel-sessions/): Run two agent sessions on one project at once, each in its own git worktree and branch with a task that changes other files, keep a one-line note per session, and integrate in a fixed order: merge the API branch, have the docs session rebase and run the check again, and keep every session away from the shared stash and port.
- [Writing down how the team uses agents](https://schubergphilis.github.io/ai-training/coding-with-agents/team-practice/): Write the team's practice for agent use into the project instructions file, starting from the incidents in the project's history, take out the rule no incident supports, and decide which agreements a hook or a CI check also enforces.