Agent Engineering

The single biggest multiplier is not a tool — it is writing down what 'done' means before the agent starts. Agents are excellent at executing a clear spec and confidently wrong on a vague one. A spec turns a guessing game into a checklist the agent (and your reviewer) can verify.

spec.md        WHAT and WHY: goal, users, constraints, acceptance criteria
   │           (you write or review this — 10 minutes)
   ▼
plan.md        HOW: files, data model, risks  (agent drafts, you approve)
   │
   ▼
tasks.md       small, ordered, independently testable steps
   │
   ▼
implement      one task per run / thread; tests first
   │
   ▼
verify         acceptance criteria → tests → diff review

• GitHub Spec Kit and AWS Kiro popularized this flow (spec → plan → tasks); you can run it with plain Markdown in any tool
• Plan mode in Cursor, Claude Code, and Copilot produces the plan step for you — review it like a design doc
• Keep specs in the repo (docs/specs/) so cloud agents and teammates get the same input

Tests are the most reliable way to tell an agent what correct means — and the fastest way for you to verify it. The trick is ordering and protection: tests first, reviewed by you, then implementation that is not allowed to change them.

1. Ask the agent to write failing tests from the acceptance criteria only — no implementation yet
2. Run them, confirm they fail for the right reason, and review them (this is where your judgment matters most)
3. Commit the tests
4. Ask the agent to make them pass without modifying test files
5. Protect test files with a hook or explicit instruction; re-run the full suite

Step 1: "Write failing Vitest tests for the acceptance criteria in
         docs/specs/pdf-export.md. Do not implement anything.
         Run them and show me the failures."
Step 2: (you review + commit tests)
Step 3: "Make the tests in tests/pdf-export.test.ts pass.
         Do not edit any file under tests/. Run the full suite
         before you finish."

Once tasks are small and specified, the bottleneck becomes you waiting. Top developers run two to four agents at once on independent tasks, each in its own working copy, and spend their time reviewing instead of watching.

git worktree add ../app-export  -b feat/pdf-export
git worktree add ../app-flaky   -b fix/flaky-auth-test
git worktree add ../app-docs    -b docs/api-reference

~/app          main (you review here)
~/app-export   agent A  → PR #1
~/app-flaky    agent B  → PR #2
~/app-docs     agent C  → PR #3

git worktree remove ../app-docs   # after merge

• Only parallelize tasks that do not touch the same files — merge conflicts erase the gains
• Give each worktree its own dev-server port and database to avoid collisions
• Best-of-N: run the same hard task in two worktrees with different models or prompts and keep the better diff
• Your throughput is capped by review speed — keep PRs small

Using the strongest model for everything is slow and expensive; using the cheapest for everything costs you rework. Route by task shape and track what you spend.

• Most tools support per-agent or per-subagent model choice — use a cheap model for explorer subagents
• Cap turns and budgets in headless runs (for example --max-turns in Claude Code)
• Long sessions cost more per turn because context grows — fresh threads are also a cost control
• Review weekly usage dashboards; set team spend alerts

Agents guess fixes fast and wrong when they lack runtime evidence. The superstar move is making the agent reproduce, instrument, and prove the cause before it touches the fix.

1. Reproduce: a failing test or script that shows the bug on demand
2. Hypothesize: list 2–3 candidate causes, each with a way to confirm or rule out
3. Instrument: add targeted logs or breakpoints; collect the output
4. Fix the confirmed cause only; keep the reproduction as a regression test
5. Remove instrumentation; review the diff

Level 5 developers put agents into the delivery pipeline so the team benefits without anyone opening a chat window.

• anthropics/claude-code-action@v1 takes a prompt plus claude_args (for example --max-turns and --allowedTools)
• openai/codex-action@v1 runs codex exec with a sandbox setting and a safety strategy
• Give CI agents least-privilege tokens and read-only tools unless the job must push
• Never let untrusted PR content drive an agent that holds write secrets

Bug report: 'Streak resets at midnight for users in Asia.'

you:   fix the streak bug
agent: The issue is likely timezone handling. I've added a try/catch
       and default to UTC if the date is invalid.
you:   (merges) → bug persists; now errors are silently swallowed

you:   Reproduce first: write a failing test for a user in Asia/Tokyo
       completing a task at 23:30 and 00:30 local. Don't fix yet.
agent: tests/streak.test.ts: 1 failing — streak resets at 00:30 local.
       Evidence: computeStreak() uses new Date().getDate() (server UTC).
you:   commit tests. Now fix without editing tests/.
agent: Use the user's IANA zone via Intl; 1 file changed; suite 212 passed.
reviewer subagent: LGTM — also check the weekly summary job (same pattern).

• Reproduction turned a guess into evidence (server-UTC date math)
• Tests were committed before the fix, so they could not be weakened
• A clean-context reviewer found a second instance of the same bug