Agentic Coding: Working With Claude Code, Codex, and Cursor

You already know how to write software. This module is about the tool that changed how software gets written in the last two years, and it comes first in this path for a practical reason: every module after it goes faster if you can delegate the mechanical parts to a coding agent and spend your attention on the parts that require judgment.

A coding agent (Claude Code, Codex, Cursor's agent mode, and a growing list of others) is not autocomplete. It takes a task, explores the repository, edits files, runs commands and tests, reads the results, and iterates until it thinks the task is done. The skill is not prompting. It is specifying work, shaping the environment the agent works in, and reviewing what comes back with the right level of skepticism.

The Loop You Are Supervising

Every coding agent runs the same three-phase loop, and once you see it you can predict where it will go wrong.

1. Gather context. Read the task, read the relevant files, search the codebase, read the project's context file.
2. Take action. Edit a file, run a command, run the tests, call a tool.
3. Verify. Look at the result. Tests pass? Command errored? Output looks right? Decide whether to loop again or report.

The loop is only as good as its verification step. An agent with no way to check its work (no tests, no type checker, no way to run the code) will report success based on whether the code looks right, which is exactly the failure mode you cannot afford. So the first thing an experienced engineer does before delegating is make sure the agent has a way to verify: a test command, a linter, a script that exercises the change. If none exists, the first task you give the agent is to create one.

Context Files: CLAUDE.md and AGENTS.md

Agents start every session cold. They read a context file at the repository root before doing anything else: CLAUDE.md for Claude Code, AGENTS.md as the cross-tool convention used by Codex and others, .cursor/rules for Cursor. Many teams keep one file and symlink the rest.

A context file is the single highest-leverage artifact in agentic coding. It is not documentation for humans (the README is that). It is the operating instructions for a very capable contractor who has never seen your codebase and will forget everything at the end of the session.

markdownCopy
# CLAUDE.md

## What this is
Spring Boot API + React frontend for a learning platform. Postgres via Flyway.

## Commands
- Backend tests: `cd backend && mvn -q test`
- Frontend typecheck: `cd frontend && npx tsc -b`
- Never run `mvn spring-boot:run` yourself; ask me to start it.

## Rules
- Schema changes go in a new Flyway migration. Never edit an applied migration.
- Post content must not start with an H1.
- No em dashes in content.
- Match the existing code style; do not add comments that restate the code.

## Where things are
- Controllers: backend/src/main/java/.../controller
- API client: frontend/src/api/blogApi.ts

What belongs in it: commands, invariants, conventions the agent cannot infer, and the location of things it would otherwise search for. What does not: anything the agent can read from the code, long prose, or aspirational architecture. Keep it under a couple of hundred lines; agents weight everything in it, and a bloated file dilutes the rules that matter.

The file is version controlled and it evolves. Every time the agent makes a mistake that a rule would have prevented, the rule goes in the file. That is the same "never make that mistake again" loop you will meet in the harness engineering module, applied to your own workflow.

Skills, Subagents, and Hooks

Three mechanisms let you shape the agent beyond the context file.

Skills are reusable instructions for a recurring task, stored as a file the agent loads when the task matches. A skill for "write a Flyway migration" would spell out the naming convention, the dollar-quoting rule for content, the reading-time formula, and the verification query to run afterward. Skills turn tribal knowledge into something the agent applies consistently.

Subagents are separate agent instances with their own context window, tool set, and instructions, launched by the main agent for a scoped task. The main benefit is context isolation: a subagent that reads forty files to answer "where is the tax rate computed" returns one paragraph, and the forty files never enter the main context. Use subagents for exploration, review, and parallel independent work. Do not reach for multi-agent setups by default; for most development tasks a single agent with good context beats several agents coordinating, and the coordination overhead is real.

Hooks run your own commands at points in the loop: before a tool call, after a file edit, when the agent stops. A hook that runs the formatter after every edit, or blocks any command containing rm -rf, is a deterministic guarantee where a rule in the context file is only a strong suggestion. Anything you would never want the agent to do goes in a hook, not a rule.

Permission Modes

Every serious coding agent has a permission model: what it may do without asking. Read-only, edit files, run commands, network access. Two habits:

• Start restrictive per project. Let the agent read and propose; approve edits and commands until you trust it on that codebase. Loosen per project, never globally.
• Irreversible actions always ask. Force-pushing, deleting branches, dropping tables, deploying, sending anything. If the agent's environment lets it do those without a prompt, you have removed the only safety net that survives a bad instruction or a prompt injection in a file it read.

Many agents also offer a plan mode: the agent explores and proposes a plan without editing anything. For any task that touches more than a few files, ask for the plan first, edit the plan, then let it execute. Reviewing a plan is cheaper than reviewing a diff.

Spec-Driven Development

The biggest quality lever is the task description. A weak task ("make search faster") produces a plausible change to the wrong thing. A strong task has four parts:

1. The observable problem. "Search for a common term takes 4s on the posts page."
2. The definition of done. "Under 300ms p95 on the local dataset, measured with the existing benchmark script."
3. The constraints. "No new dependencies. Do not change the API response shape."
4. The verification. "Run npm run bench:search before and after and include both numbers."

Engineers who get good results from agents write specs like this reflexively. The spec is also the review checklist: if the agent's report does not address every line, it is not done.

Reviewing Agent Output

Review an agent's work like a pull request from a fast, well-read, overconfident new hire.

• Read the diff, not the summary. The summary is the agent's belief about what it did.
• Check the file list against the spec. Files outside the expected set are the first place bugs hide, and the first sign of over-reach.
• Look for test edits you did not ask for. An agent that cannot make a test pass will sometimes change the test.
• Run the verification yourself. Once. Then trust the agent's runs for the rest of the session on that task.
• Ask for one justification. "Why did you change the cache TTL?" A reason is good. A restatement means it did not know.

When you find a problem, send it back to the agent with what you found rather than fixing it yourself. You stay in the reviewer's seat, and the correction often reveals a missing rule for the context file.

Where Agents Go Wrong

• Confident wrong. Same tone whether it succeeded or fixed the wrong thing.
• Scope creep. Asked to fix one function, refactors three files. Constrain in the spec; check the file list.
• Fake verification. Weakened tests, skipped tests, "should work" in the summary.
• Stale knowledge. Uses an API that was deprecated after its training data. A rule in the context file ("we use the v2 client") fixes this permanently.
• Loops. Retrying the same failing command. If it has run for a while on a small task, stop it and read the transcript.
• Ignoring the context file. Usually because the file is too long or the rule is buried. Short files, rules first.

Common Mistakes and Bad Instincts

• Treating it as autocomplete. Reading every action in real time does not scale; review outcomes.
• No verification path. Delegating to an agent that cannot run the tests.
• A 600-line CLAUDE.md. Rules drown.
• Global "allow everything." Saves seconds, costs you the one time it matters.
• Multi-agent by default. One agent with good context beats three coordinating for most tasks.
• Fixing it yourself. You lose the correction signal and take on code you did not write.

Where to Go Next

• python-for-experienced-engineers: you will use the agent for the rest of this path; the next module is a good first delegation target
• harness-engineering-the-runtime-around-the-model: the same permission, verification, and tracing ideas, applied to agents you build
• agent-evals-trajectories-tool-calls-and-regression-suites: how to grade an agent's trajectory, including a coding agent's

What to Practice Next

Pick a real repository. Write a CLAUDE.md under 100 lines with commands, invariants, and locations. Write one skill for a recurring task in that repo. Then delegate a small, well-specified change with a four-part spec, review it with the checklist above, and record every correction you made as a candidate rule for the context file. Ship the PR with a short note on what the agent did and what you changed.