AI Coding Agents
AI coding agents are autonomous software systems that read, write, execute, and debug code with minimal human intervention. Unlike autocomplete tools that suggest the next token, coding agents operate at the task level — they understand requirements, explore codebases, make architectural decisions, run tests, and iterate until the task is complete.
The shift from autocomplete to agentic coding represents a fundamental change in how software is built. Autocomplete tools like early GitHub Copilot accelerated typing. Coding agents like Claude Code, Cursor, and OpenAI Codex accelerate thinking — they handle the entire development loop from requirement analysis to verified implementation.
info
Modern coding agents use a ReAct (Reasoning + Acting) loop: they observe the environment, think about the next step, act on it, and verify the result. This loop repeats until the task is done or the agent determines it needs human input.
The ReAct Loop
1. Observe — Read files, search code, inspect error logs, gather context about the current state of the system.
2. Think — Analyze observations, form hypotheses, plan the next action, decide which tools to use.
3. Act — Execute the plan: write code, run commands, call APIs, modify files, or query databases.
4. Verify — Check the outcome: did tests pass? Did the build succeed? Did the linter approve? If not, loop back to observe.
| Phase | Agent Action | Human Role |
|---|---|---|
| Observe | Read files, grep codebase, parse AST, check git status | Provide context, point to relevant files |
| Think | Chain-of-thought reasoning, plan decomposition, tool selection | Review plan, approve approach |
| Act | Edit files, run shell commands, call MCP tools, create commits | Approve destructive actions, provide credentials |
| Verify | Run tests, type-check, lint, build, deploy to staging | Accept or reject changes, provide feedback |
note
The coding agent landscape has matured rapidly. Here are the leading platforms, their strengths, and when to use each.
| Agent | Strengths | Pricing | MCP Support | Subagents | Best For |
|---|---|---|---|---|---|
| Claude Code | Deep reasoning, large context, terminal-native, MCP-native | Pro $20/mo, Team $30/user | Native | Yes | Complex refactors, multi-file changes, MCP workflows |
| Cursor | IDE integration, fast autocomplete, multi-model support | Pro $20/mo, Business $40/user | Via plugins | Limited | Rapid prototyping, greenfield projects, pair programming |
| OpenAI Codex | Code execution sandbox, GitHub integration, natural language to code | Usage-based (API) | Limited | No | Script generation, data pipelines, quick automation |
| Devin | Fully autonomous, long-running tasks, self-healing | Enterprise (custom) | Unknown | Yes | Large migrations, overnight tasks, enterprise automation |
| GitHub Copilot Workspace | GitHub-native, issue-to-PR workflow, team collaboration | Included with Copilot Enterprise | No | No | GitHub-centric teams, issue triage, small fixes |
pro tip
The fastest way to get started is with Claude Code or Cursor. Both provide interactive terminal or IDE experiences with minimal configuration. The key to effective agent use is a well-written configuration file that tells the agent about your project conventions.
| 1 | # Install Claude Code (requires Node.js 18+) |
| 2 | npm install -g @anthropic-ai/claude-code |
| 3 | |
| 4 | # Navigate to your project |
| 5 | cd my-project |
| 6 | |
| 7 | # Start interactive session |
| 8 | claude |
| 9 | |
| 10 | # Or run a single task |
| 11 | claude -p "Fix the failing test in src/utils.test.ts" |
| 12 | |
| 13 | # Install Cursor (macOS) |
| 14 | brew install --cask cursor |
| 15 | |
| 16 | # Or download from cursor.sh |
| 17 | # Open project in Cursor |
| 18 | cursor . |
Create a CLAUDE.md or AGENTS.md in your project root. This file is the agent's instruction manual — it defines coding style, testing requirements, architectural constraints, and anything else the agent needs to know.
| 1 | # CLAUDE.md — Project Agent Configuration |
| 2 | |
| 3 | ## Project Overview |
| 4 | Next.js 16 e-commerce platform with TypeScript strict mode, |
| 5 | Tailwind CSS v4, and PostgreSQL via Prisma. |
| 6 | |
| 7 | ## Coding Standards |
| 8 | - TypeScript strict; no any types |
| 9 | - Functional React components only; no class components |
| 10 | - Use Tailwind arbitrary values for one-off styles |
| 11 | - All new components must have Storybook stories |
| 12 | |
| 13 | ## Testing Requirements |
| 14 | - Run `npm test` after every change |
| 15 | - Run `npx tsc --noEmit` before committing |
| 16 | - E2E tests required for checkout flow changes |
| 17 | |
| 18 | ## Architecture Constraints |
| 19 | - App Router only; no Pages Router |
| 20 | - Server Components by default; Client Components only when needed |
| 21 | - Database access only through Prisma client |
| 22 | - No direct SQL in application code |
| 23 | |
| 24 | ## File Structure |
| 25 | - src/app/ — Next.js App Router pages |
| 26 | - src/components/ — Reusable React components |
| 27 | - src/lib/ — Utilities and helpers |
| 28 | - prisma/ — Database schema and migrations |
best practice
Different agents use different configuration files. The ecosystem is converging on AGENTS.md as a standard, but agent-specific files still dominate. Here is what each agent expects.
CLAUDE.md — Claude Code
Read automatically by Claude Code. Supports markdown, code blocks, and nested imports. Can reference other files like ./docs/architecture.md.
| 1 | # CLAUDE.md |
| 2 | See @AGENTS.md for general project context. |
| 3 | |
| 4 | ## Claude-Specific Rules |
| 5 | - Always run tests before marking a task complete |
| 6 | - Use the Read tool before editing any file |
| 7 | - Prefer editing existing files over creating new ones |
| 8 | - When in doubt, ask for clarification — do not guess |
.cursorrules — Cursor
Plain text or markdown file in project root. Cursor reads this for every AI interaction. Supports basic formatting but not nested imports.
| 1 | # .cursorrules |
| 2 | You are an expert TypeScript developer. |
| 3 | |
| 4 | Rules: |
| 5 | - Use strict TypeScript, never any |
| 6 | - Prefer named exports over default exports |
| 7 | - Write tests for all new utilities |
| 8 | - Use Zod for runtime validation |
| 9 | - Follow the existing file structure in src/ |
| 10 | |
| 11 | When editing: |
| 12 | - Read the file first |
| 13 | - Make minimal changes |
| 14 | - Add comments only where logic is not self-evident |
AGENTS.md — Universal Standard
Emerging standard supported by multiple agents. Designed to be agent-agnostic. Place in project root or .agents/ directory.
| 1 | # AGENTS.md |
| 2 | ## Project |
| 3 | E-commerce platform, Next.js 16, TypeScript, Tailwind |
| 4 | |
| 5 | ## Commands |
| 6 | - Build: npm run build |
| 7 | - Test: npm test |
| 8 | - Lint: npm run lint |
| 9 | - Type check: npx tsc --noEmit |
| 10 | |
| 11 | ## Conventions |
| 12 | - TypeScript strict |
| 13 | - Functional components |
| 14 | - Tailwind for styling |
| 15 | - Prisma for database |
| 16 | |
| 17 | ## Boundaries |
| 18 | - Never edit prisma/migrations directly |
| 19 | - Never commit .env files |
| 20 | - Always ask before deleting files |
.windsurfrules — Windsurf
Windsurf's configuration format. Similar to .cursorrules with some Windsurf-specific directives.
| 1 | # .windsurfrules |
| 2 | - Always use TypeScript strict mode |
| 3 | - Follow existing patterns in the codebase |
| 4 | - Write unit tests for new functions |
| 5 | - Use the existing design system components |
| 6 | - Run linter before completing tasks |
info
Advanced coding agents can spawn subagents to work on independent tasks in parallel. This is essential for large refactors, multi-service changes, or research tasks that require exploring multiple approaches simultaneously.
| 1 | // Example: Claude Code spawning parallel subagents |
| 2 | // (Conceptual — actual API varies by agent) |
| 3 | |
| 4 | import { spawnSubagent } from "@anthropic-ai/claude-code"; |
| 5 | |
| 6 | async function migrateToAppRouter() { |
| 7 | // Main agent decomposes the task |
| 8 | const tasks = [ |
| 9 | { |
| 10 | name: "migrate-pages", |
| 11 | prompt: "Migrate src/pages/*.tsx to src/app/ using App Router conventions", |
| 12 | files: ["src/pages/**"], |
| 13 | }, |
| 14 | { |
| 15 | name: "update-imports", |
| 16 | prompt: "Update all import paths to use @/ alias instead of relative paths", |
| 17 | files: ["src/**/*.ts", "src/**/*.tsx"], |
| 18 | }, |
| 19 | { |
| 20 | name: "add-loading-states", |
| 21 | prompt: "Add loading.tsx and error.tsx to all route segments", |
| 22 | files: ["src/app/**"], |
| 23 | }, |
| 24 | ]; |
| 25 | |
| 26 | // Spawn parallel subagents |
| 27 | const results = await Promise.all( |
| 28 | tasks.map((task) => |
| 29 | spawnSubagent({ |
| 30 | name: task.name, |
| 31 | prompt: task.prompt, |
| 32 | allowedFiles: task.files, |
| 33 | maxTurns: 50, |
| 34 | }) |
| 35 | ) |
| 36 | ); |
| 37 | |
| 38 | // Main agent verifies and merges |
| 39 | await runTests(); |
| 40 | await createPullRequest(results); |
| 41 | } |
warning
MCP (Model Context Protocol) enables coding agents to connect to databases, APIs, version control, issue trackers, and custom tools. An MCP-connected agent can query your production database schema, fetch error logs from Sentry, create GitHub issues, and deploy to Vercel — all within the same session.
| 1 | // .claude/settings.json — MCP server configuration |
| 2 | { |
| 3 | "mcpServers": { |
| 4 | "postgres": { |
| 5 | "command": "npx", |
| 6 | "args": ["-y", "@modelcontextprotocol/server-postgres"], |
| 7 | "env": { |
| 8 | "POSTGRES_CONNECTION_STRING": "postgresql://localhost:5432/mydb" |
| 9 | } |
| 10 | }, |
| 11 | "github": { |
| 12 | "command": "npx", |
| 13 | "args": ["-y", "@modelcontextprotocol/server-github"], |
| 14 | "env": { |
| 15 | "GITHUB_TOKEN": "ghp_..." |
| 16 | } |
| 17 | }, |
| 18 | "filesystem": { |
| 19 | "command": "npx", |
| 20 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/src"] |
| 21 | }, |
| 22 | "sentry": { |
| 23 | "command": "npx", |
| 24 | "args": ["-y", "@modelcontextprotocol/server-sentry"], |
| 25 | "env": { |
| 26 | "SENTRY_AUTH_TOKEN": "sntryu_...", |
| 27 | "SENTRY_ORG": "my-org" |
| 28 | } |
| 29 | } |
| 30 | } |
| 31 | } |
With MCP configured, the agent can invoke tools naturally:
| 1 | // Agent workflow using MCP tools |
| 2 | // 1. Check database schema |
| 3 | const schema = await mcp.postgres.query({ |
| 4 | sql: "SELECT table_name, column_name, data_type FROM information_schema.columns WHERE table_schema = 'public'" |
| 5 | }); |
| 6 | |
| 7 | // 2. Find relevant GitHub issues |
| 8 | const issues = await mcp.github.searchIssues({ |
| 9 | query: "repo:myorg/myrepo label:bug state:open" |
| 10 | }); |
| 11 | |
| 12 | // 3. Read error logs |
| 13 | const errors = await mcp.sentry.getEvents({ |
| 14 | query: "level:error", |
| 15 | limit: 10 |
| 16 | }); |
| 17 | |
| 18 | // 4. Fix the bug, run tests, create PR |
| 19 | await editFile("src/lib/auth.ts", fixContent); |
| 20 | await runCommand("npm test"); |
| 21 | await mcp.github.createPullRequest({ |
| 22 | title: "Fix authentication token refresh", |
| 23 | body: `Fixes #${issues[0].number}. Resolves Sentry error ${errors[0].id}`, |
| 24 | head: "fix/auth-refresh", |
| 25 | base: "main" |
| 26 | }); |
pro tip
Coding agents execute arbitrary commands and modify files. This creates significant security surface area. Understanding permission models and sandboxing options is essential for safe production use.
Permission Tiers
Most agents offer tiered permissions: read-only (explore but not edit), workspace-write (edit files but not run commands), and full-access (run any command). Start with the most restrictive tier that accomplishes the task.
File Access Control
Configure allowed directories explicitly. Claude Code respects .gitignore and .claudeignore. Cursor uses workspace boundaries. Never give agents access to ~/.ssh, ~/.aws, or credential files.
Network Isolation
Run agents in containers or VMs with restricted network access. For sensitive codebases, use local-only models or air-gapped environments. MCP servers should use least-privilege credentials with short-lived tokens.
Audit Logging
Enable comprehensive logging of all agent actions. Claude Code logs every file read, edit, and command execution. Review logs before merging agent-generated PRs, especially for infrastructure or security-sensitive code.
Secrets Management
Never hardcode secrets in configuration files. Use environment variables, secret managers, or short-lived OAuth tokens. Agents should access secrets through MCP servers that enforce access control, not by reading .env files directly.
warning
Quantifying agent impact requires tracking both output metrics (what the agent produces) and process metrics (how it changes your workflow). Here are the metrics that matter.
| Metric | How to Measure | Target | Warning Sign |
|---|---|---|---|
| Task Completion Rate | % of assigned tasks completed without human intervention | >70% for routine tasks | <40% — agent needs better context or task decomposition |
| Time to First PR | Minutes from task assignment to pull request opened | <30 min for small features | >2 hours — agent stuck in loops or needs better tooling |
| Human Review Time | Minutes spent reviewing agent output per PR | <15 min for routine changes | >1 hour — agent producing low-quality or over-complex code |
| Defect Rate | Bugs introduced per 1000 lines of agent-generated code | Equal or lower than human baseline | Significantly higher — agent needs better testing instructions |
| Developer Satisfaction | Survey score (1-10) on "agents make my job easier" | >7 average | <5 — agents creating more work than they save |
best practice
Start Small, Expand Gradually
Begin with well-defined, low-risk tasks: writing tests, updating dependencies, fixing linter errors. Expand to feature development only after you trust the agent's output quality and understand its failure modes.
Invest in Configuration
A detailed CLAUDE.md or AGENTS.md is the highest-ROI investment. Include coding standards, architecture diagrams, common pitfalls, and links to key documentation. Update it when the agent makes a mistake.
Use Version Control Aggressively
Commit before starting any agent session. Review diffs carefully — agents can make subtle, wide-ranging changes. Use feature branches for agent work, never commit directly to main.
Decompose Complex Tasks
Break large features into small, verifiable steps. "Add user authentication" is too vague. "Create a login form component with email/password validation" is actionable. Agents excel at focused tasks with clear success criteria.
Maintain Human Oversight
Agents amplify productivity but do not replace judgment. Review all security-sensitive code, database migrations, and architectural decisions. Use agents for implementation, not for requirements or design.
Iterate on Failure
When an agent fails, diagnose why: insufficient context? ambiguous instructions? missing tools? Update your configuration and try again. Each failure is a configuration improvement opportunity.
Community
Get help on Slack, Discord or VIP
Stuck on a guide? Join the community and ask.