Agentic development

Principle

Agentic means the system can plan, use tools, and iterate across multiple steps — not just complete the next line. The product risk is not that agents fail; it is that they succeed at the wrong thing while you were not looking.

Agentic development keeps humans at decision gates: architecture, data deletion, payments, external side effects, and merge to production. Everything else is negotiable automation.

The decision

  ┌─────────────────────────────────────┐
│  Agent loop (plan → act → observe)  │
│  allowed: src/, tests/, docs/       │
└──────────────┬──────────────────────┘
│ proposes
▼
Human gates: schema · billing · deploy · secrets
│
▼
merge / ship

Gates worth enforcing

Encode forbidden paths in AGENTS.md and CI — not just chat reminders.

A minimal agentic workflow

1. Ticket with acceptance criteria and file scope.
2. Agent plan — you approve or edit before code runs.
3. Implementation in allowed directories.
4. Automated verify — lint, test, build (agent runs; you trust but spot-check).
5. Human review on diff size and gate files.
6. Merge — you or CI; agent does not push to prod alone.

Inspectability

• Logs — what tools ran, in what order.
• Small PRs — one ticket per branch when possible.
• Repro commands — npm test, npm run build in the ticket.
• Rollback — feature flags or revert plan for agent-shipped work.

If you cannot reconstruct what happened from git + CI, the agent had too much rope.

Workflow

1. Maintain templates/agent-boundary.md per repo — allowed, forbidden, verify commands.
2. Start agent on plan-only for unfamiliar tasks; approve plan.
3. Cap diff size — stop and split if >400 lines unless migration.
4. Run gates manually for forbidden zones even if “already done.”
5. After merge, update boundaries when the agent surprised you.

Tooling

Claude Code, Cursor agent mode, Devin-class runners, custom scripts with MCP — same rules. Longer autonomy demands narrower scope and stricter verify.

Common mistakes

• Unattended overnight runs on main.
• Agents editing lockfiles and CI config casually.
• No plan approval — debugging hallucinated architecture later.
• Treating green tests as proof of correct product behavior.

Scenario (composite)

A small product team used an agent to refactor twelve API handlers into a shared middleware pattern. The agent proposed deleting a deprecated table column in the same PR — caught at human gate because migrations were forbidden without review. Plan-only mode saved two hours of rollback.

They merged in three PRs: middleware extraction, test updates, docs. CI required build and integration tests. A follow-up overnight run on main without gates shipped a lockfile bump that broke deploy — added to the forbidden list and AGENTS.md.

Artifacts

• AGENTS.md — repo conventions + pointer to boundary template.
• CI required checks — build, lint, test on every agent PR.
• Incident note when an agent breaks prod — update forbidden list.

Falsify this

• Agent ran on main overnight with no plan approval — inspectability is already gone.
• Green CI but no human read the diff in forbidden zones (package.json, workflows, env).
• One 2,000-line PR “because the agent finished” — cannot review, cannot revert cleanly.
• You delegated customer-facing release notes to the agent without edit.
• You cannot answer “what tools did it run?” from git and CI logs alone.

Further reading

• Chapter 09 — AI pair programming
• Chapter 11 — Architecture decisions
• Chapter 13 — Deployment