Working with AI Coding Agents: Workflow, Context, and Guardrails

How a coding agent works#

A coding agent is the agent loop pointed at your repository. Its tools read and search files, edit them, and run commands in a terminal; some connect to more systems through MCP. It works until the task is done, a check fails in a way it cannot fix, or it needs a decision from you.

Everything the agent knows comes from what it can read or run. That gives you three levers: the instructions file it reads every session, the task brief you write, and the checks it can run to know whether it succeeded.

The workflow#

1. Explore. Ask the agent to read the relevant code and explain how it works before changing anything. You catch misunderstandings when they are cheap.
2. Plan. Ask for a short plan: files to touch, approach, risks, how it will verify. Correct it. For larger changes, save the plan in a file so it survives a long session.
3. Implement in small steps, ideally one logical change at a time.
4. Verify with the same commands CI runs: tests, type checking, lint. The agent should run them itself and fix failures.
5. Review the diff as you would a teammate's pull request, then commit.

For small, well-understood changes (a typo, a rename, a new test case), skip straight to implementing. The workflow scales with risk.

Project instructions: AGENTS.md#

An instructions file in the repository root is loaded into every session. It is the onboarding document for your agent: how to build, test, and lint; conventions; architecture; and rules. Several tools read AGENTS.md; Claude Code reads CLAUDE.md, which can simply import the shared file with a line containing @AGENTS.md. (This wiki's own repository does exactly that.)

# Acme Support — agent instructions
 
## Commands
- Install: `npm ci`
- Dev server: `npm run dev` (http://localhost:3000)
- Verify everything before finishing a task: `npm run check` (types, lint, unit tests; ~40 s)
- One test file: `npx vitest run path/to/file.test.ts`
 
## Stack
Next.js App Router, TypeScript strict, Postgres with Drizzle, Anthropic SDK. Server code lives in `src/server/`; UI in `src/app/` and `src/components/`.
 
## Conventions
- Validate all external input with Zod at the boundary (`src/server/schemas.ts`).
- Model calls go through `src/server/llm.ts` (tracing, cost, retries). Never import the SDK directly elsewhere.
- Database access only through `src/server/db/queries.ts`; scope every query to the current user.
- Prefer server components; add `"use client"` only for interactivity.
 
## Rules
- Never commit secrets or read `.env*` files.
- Do not change database migrations that have already run; add a new migration.
- Ask before adding a dependency.
- Keep diffs focused on the task; propose unrelated cleanups separately.

Keep it short and specific. Every line is read on every task, so state what the agent cannot infer from the code: commands, invariants, and the mistakes you have seen it make. When an agent repeats a mistake, add a line.

Writing a task brief#

Agents do what you ask, including the parts you did not mean. A good brief has the same parts as a good ticket:

## Goal
Customers can download all invoices for a year as one ZIP file from Billing → Invoices.
 
## Context
- Invoice PDFs are generated by `renderInvoicePdf()` in `src/server/invoices.ts`.
- The invoices page is `src/app/billing/invoices/page.tsx`.
 
## Constraints
- Stream the ZIP; do not hold all PDFs in memory (some customers have 3,000 invoices).
- Only the signed-in customer's invoices.
 
## Done when
- A "Download year (ZIP)" button appears per year.
- A route handler returns `application/zip` with one PDF per invoice.
- Tests cover: other customers' invoices are excluded; empty year returns 404.
- `npm run check` passes.
 
Start by exploring the code and proposing a plan. Don't write code until I approve it.

The last line is the most important habit in this article: separate planning from implementation for anything non-trivial.

Permissions and safety#

A coding agent runs commands on your machine with your credentials. Configure what it may do without asking. In Claude Code, project settings in .claude/settings.json (checked in) set permissions for the whole team:

{
  "permissions": {
    "allow": ["Bash(npm run check)", "Bash(npm run test:*)", "Bash(npx vitest run:*)", "Bash(git diff:*)", "Bash(git status)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Bash(git push:*)", "Bash(npm publish:*)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "node .claude/hooks/lint-edited-file.ts" }]
      }
    ]
  }
}

• Allow safe, frequent commands (tests, lint, read-only git) so the agent does not stop to ask every time.
• Deny reading secrets and anything irreversible or outward-facing (push, publish, deploy).
• Never give agents production credentials. Use a development database and test API keys.
• For untrusted code or long autonomous runs, use a sandbox: a container or a cloud environment with no access to your secrets.

Hooks: automatic checks after every edit#

The hooks entry above runs a script after every file edit. The script receives the tool call as JSON on standard input. If it exits with code 2, its error output is shown to the agent, which then fixes the problem immediately rather than at the end of the task:

import { spawnSync } from "node:child_process";
 
interface HookInput {
  tool_name: string;
  tool_input: { file_path?: string };
}
 
let raw = "";
for await (const chunk of process.stdin) raw += chunk;
const input = JSON.parse(raw) as HookInput;
const file = input.tool_input.file_path;
 
// Only lint source files; ignore everything else quietly.
if (!file || !/\.(ts|tsx|js|jsx)$/.test(file)) process.exit(0);
 
const result = spawnSync("npx", ["eslint", "--fix", file], { encoding: "utf8", shell: process.platform === "win32" });
if (result.status !== 0) {
  // Exit code 2 sends stderr back to the agent so it can fix the problem right away.
  console.error(`ESLint found problems in ${file}:\n${result.stdout}${result.stderr}`);
  process.exit(2);
}

Deterministic checks in hooks are more reliable than instructions: "always run the linter" in AGENTS.md is a request; a hook is a guarantee.

Reviewing agent output#

You are responsible for every line that ships. Review agent diffs with extra attention to the failure modes agents have:

• Plausible but wrong: code that reads well and handles the case the agent imagined, not the real one. Run it.
• Tests that test nothing: assertions that mirror the implementation, or mocks that make every test pass. Read the assertions.
• Scope creep: unrelated refactors mixed into the change. Ask for them separately.
• Silenced errors: any, // @ts-ignore, empty catch, disabled lint rules, skipped tests. Treat each as a question.
• Invented APIs: a method that does not exist in your library version. Type checking and running the code catch most of these.
• Security shortcuts: missing authorization checks, unvalidated input, secrets in code.

If you would not approve the pull request from a colleague, do not approve it from an agent.

Where agents help most#

Common mistakes#

• One giant prompt, one giant diff. Break work into reviewable steps.
• No verification command. If the agent cannot run checks, it cannot know it succeeded, and neither can you.
• Skipping the plan. Most wasted agent time comes from a misunderstanding that a plan would have revealed.
• Accepting what you do not understand. Ask the agent to explain the change; if you still do not understand it, do not merge it.
• Letting your own skills fade. Read code, debug by hand sometimes, and stay able to judge the agent's work.

Next steps#