Autonomous AI coding agents—such as Claude Code, Antigravity CLI, OpenAI Codex, and Cursor—have transformed terminal workflows. But in inexperienced hands, these powerful tools can destroy codebases faster than a rogue rm -rf.
If you have ever watched an agent hallucinate an entire legacy utility file, silently delete 40 test cases to make a build pass, or burn $18 of tokens looping on a missing semicolon, you know the frustration.
Here is the battle-tested playbook of Do’s and Don’ts for AI-assisted software engineering.
1. The Summary Matrix
| Domain | ❌ What Amateurs Do (DON’T) | ✅ What Elite Engineers Do (DO) |
|---|---|---|
| Context Management | Upload entire repo / @Workspace on every prompt |
Provide only the 2-3 target files and precise interfaces |
| Code Edits | Let the agent rewrite 500-line files from scratch | Enforce surgical unified diffs / precise line replacements |
| Testing | Ask agent to “make tests pass” (it deletes assertions) | Protect test files as read-only invariants |
| Git Hygiene | Work on dirty main branch with uncommitted edits |
Run agents on isolated git branches with clean commits |
| Debugging | Paste 200 lines of raw stack trace blindly | Provide the exact error line, reproducing input, and expected invariant |
2. The 5 Cardinal Sins (DON’TS)
❌ Don’t 1: Never Let an Agent Modify Tests to Fix Failures
When an agent encounters a failing test, its shortest path to optimizing the reward function is often:
- assert user.is_authenticated is True
+ # assert user.is_authenticated is True <-- AGENT FIX
+ pass
Always lock test files or instruct the agent explicitly:
“The test suite in tests/test_auth.py represents the ground-truth specification. You may NOT modify any file in tests/. Modify ONLY src/auth.py until all tests pass.”
❌ Don’t 2: Don’t Allow Unchecked Context Window Pollution
Attention degrades with context length. If you feed 80,000 tokens of documentation, dependencies, and unrelated components to an agent, its reasoning accuracy drops significantly. Keep context hyper-local: the interface, the implementation, and the test.
❌ Don’t 3: Don’t Accept Full-File Overwrites
When an agent replaces an entire file, subtle nuance is lost: custom logging hooks, security sanitizers, performance micro-optimizations, and detailed comments disappear. Demand surgical diffs.
3. The Best Practices (DOS)
✅ Do 1: Atomic Git Checkpoints Before Every Agent Task
Before launching an agent command, ensure your working tree is pristine:
git checkout -b feature/agent-stripe-webhook
git add -A && git commit -m "checkpoint: pre-agent state"
If the agent goes astray, you are one command away from recovery: git reset --hard HEAD.
✅ Do 2: Define System Invariants Upfront
Instruct your agent using invariant boundaries:
“Maintain backward compatibility with API v1 clients. Do not alter existing function signatures. All new asynchronous calls must include a 5.0-second timeout.”
✅ Do 3: Give Agents Terminal Verifiers
The highest-performing agents are those with feedback loops. Always grant the agent access to execute pytest, npm test, or your linter directly so it can catch and correct its own syntax errors before presenting the finished work to you.
Get Weekly AI Architect Cost & Strategy Updates
Join 14,000+ developers receiving weekly, data-driven cost-reduction blueprints and production-ready agent guidelines.
