Recap — When Agents Help vs Single-File Edits

# When Agents Help vs Single-File Edits Agent mode (Claude Code, Cursor agent, Aider) is genuinely different from per-file editing. Understanding when it shines vs fumbles is key to using it well. ## What's an agent An AI that can: - Read multiple files autonomously. - Make edits across the codebase. - Run commands (tests, linters, git). - See output; iterate based on results. - Work for minutes per task. You delegate; AI executes; you review. ## When agents shine ### Multi-file refactor > "Add type hints to all functions in src/auth/. Run pyright to verify." Agent: reads each file, adds hints, runs pyright, fixes errors flagged, commits. You'd spend an hour on 10 files; agent does it in 5 min. ### Test backfill > "Add tests for all functions in src/services/ that don't have tests. Use pytest patterns from tests/test_users.py. Run the test suite to make sure all pass." Agent: lists functions, identifies missing tests, generates, runs, iterates on failures. ### Migration / pattern application > "Migrate all routes from FastAPI's old `@app.get` to the new APIRouter pattern. Update tests accordingly." Agent applies mechanically across the codebase. ### Bulk dependency updates > "Update Pydantic from v1 to v2 syntax everywhere. The migration guide is at [link]. Run tests after." Agent applies the migration patterns; tests verify. ### Incident response (with care) > "We're seeing 5xx errors on /api/orders. Check recent commits; run the test suite; investigate." Agent investigates while you watch. Best when constrained (read-only mode initially). ## When agents struggle ### Complex new features "Build a recommendations engine." Too open-ended; agent goes in circles or generates generic stuff. ### Architectural decisions "Decide if we should use microservices." Agent gives generic advice without your context. ### Performance optimization without specs "Make this fast." Without profile data and constraints, agent guesses. ### Security review "Find the security issues." Agent finds the obvious ones; misses subtle ones. ### Cross-team coordination Agents don't communicate with humans they need info from. Stuck. ## Agentic workflow pattern ``` 1. Define the task clearly. - What's done = success criteria. - Constraints (don't change behavior; tests must pass). - Files / areas to focus on. 2. Set the agent loose. - Run in a worktree / branch. - Let it work autonomously. 3. Monitor. - Tail the log occasionally. - Don't micromanage (defeats the point). 4. Review the output. - Diff: what changed? - Tests: do they pass? - Spot-check: does the code make sense? 5. Accept, refine, or restart. - Mostly good? Accept; ask for small fixes. - Wrong approach? Restart with clearer prompt. - Subtly off? Refine specific parts. ``` ## Setting boundaries For safety, scope what agents can do: ### Sandbox Run in a git worktree or temp branch. Worst case: throw it away. ### Read-only mode initially Many agents support exploration without writes. Investigate first; act second. ### Allowlist tools "You can run pytest, ruff, pyright. Don't push to remote. Don't delete files." ### Scope of files "Work only in src/auth/. Don't touch tests/ or docs/." ## Trust calibration with agents Start low-trust: - Read-only / dry-run mode. - Watch closely. - Verify everything. Build to higher-trust: - Let it write to scoped directories. - Run tests autonomously. - Commit small changes. Don't grant high trust until you've seen the agent's quality on smaller tasks. ## Communicating mid-task Most agents pause periodically or when stuck. You can redirect: > "Stop. The approach is wrong. Don't add fields to Pydantic; modify the SQLAlchemy model instead." Course-correct early; saves rework. ## When agent gets stuck in a loop Sometimes agents retry the same thing or oscillate between approaches. Recognize: - Same file being edited and reverted. - "Trying approach X" → "Trying approach Y" → "Back to X". - Output not progressing toward done. Stop the agent. Provide clearer direction OR break into smaller tasks. ## Single-file vs multi-file decision Use multi-file (agent): - Same change across many files. - Tasks where iteration matters (try; test; fix). - Bulk operations. - Long-running work you can offload. Use single-file (chat / inline): - One specific change. - Need to think and direct. - Code you're actively understanding. - Quick fixes. Both have their place. ## Cost considerations Agent mode burns tokens fast (lots of reading, planning, retries). Typical task costs: - Small refactor: $0.50 - $2. - Medium feature: $2 - $10. - Multi-day project: $20 - $100. Budget accordingly. For students: be aware. For professionals: cheap relative to time. ## Verification habits After agent completes: 1. **`git diff`**: see all changes; spot-check. 2. **Run tests**: do they pass? Did the agent add tests too? 3. **Run the application**: does it actually work? 4. **Read the