The Agentic Engineer's
Playbook

1. The Multi-Agent Orchestration Mindset

The fundamental failure mode for engineers transitioning to agentic workflows is treating an agent like a search engine. You do not ask an agent a question; you assign it a well-defined operational envelope. You are no longer writing the code; you are managing the intelligence that writes the code.

The Solution: Plan-Implement-Validate (PIV) & Backgrounding

You must force the agent to separate planning from execution. Write a plan, review the plan, execute a single step, validate it with a test, commit to Git, and repeat. Do not block your main terminal process; leverage background daemons.

# 1. Force architectural planning first
> /plan We need a Node scraper for sports 
scores. Write specs/plan.md.

# 2. Delegate deep refactoring to a daemon
> /background Read specs/plan.md and 
execute Step 1.

> /tasks # Monitor background jobs

# 3. Use dynamic subagents via JSON
> claude --agents '{"reviewer":{"description":
"Strict Python reviewer","prompt":"Review PRs 
for typing strictness and O(n) performance."}}' "Review auth.py"

# 1. Spawn two parallel domain agents
agy agents spawn --name "API-Bot" "Build 
FastAPI routes"

agy agents spawn --name "DB-Bot" "Write 
SQLAlchemy schemas"

# 2. Sync wait-state before testing
agy sync --wait-for "API-Bot, DB-Bot" --then "pytest tests/"

# 3. TUI commands to fix rabbit-holes
/fork "Try this using PostgreSQL instead 
of SQLite."

/rewind # Rolls back the conversation 
history

2. Git & Version Control as the Safety Net

The greatest safety net in agentic development is version control. If an agent spends 10 minutes digging itself into a hole, do not ask it to "fix it." It will just layer hacks over hallucinations. This is known as the Sunk Cost Fallacy. Revert your Git branch and rewrite your prompt.

The Paper Trail Workflow (Commit-Driven Development)

You must train yourself to commit before and after every agent interaction. Agents are perfectly capable of managing version control natively if instructed properly. They can create branches, write conventional commits, and generate PRs.

# Creating a strict, step-by-step Git checkpoint workflow
claude "Read specs/plan.md. Execute Step 1. 
Once you confirm it works via 'npm run build', run 'git checkout -b feat/user-routes', 
stage the changed files, and write a conventional commit message detailing the changes. 

Do NOT proceed to Step 2 until Step 1 is successfully committed to the local tree."

Antigravity Checkpointing & PR Automation

Google Antigravity has a built-in checkpointing system designed specifically for agentic rollback, as well as powerful tools for automating Pull Request creation and code review.

3. Token Economics and Progressive Disclosure

Feeding a massive 500,000-line codebase to an LLM every time you ask for a button color change is computationally reckless. It leads to Context Dilution—the "Lost in the Middle" phenomenon where the AI ignores your core instructions because it is overwhelmed by irrelevant files. Token usage is money. You must manage it.

Context Through Code: Agent-Oriented Comments

Historically, comments were written for humans. Today, they are navigational beacons for agents. Stop writing redundant comments (// increments x by 1) and start defining the blast radius of functions.

# BAD: Redundant human comment
# Calculates the monthly invoice total
def calculate_invoice(base: float, tax: float) -> float:
    return base + (base * tax)

# GOOD: Agent-Optimized Context
# AGENT-CONTEXT: Core billing logic.
# Called exclusively by src/services/stripe_webhook.py. 
# CRITICAL: Do not modify float rounding here; it will break legacy 
# accounting tests in tests/test_ledger.py. Use decimal.Decimal for updates.
def calculate_invoice(base: float, tax: float) -> float:
    return round(base + (base * tax), 2)

System Prompts & Scoping (Claude vs Antigravity)

# Architectural Rules
- Stack: Python 3.12, FastAPI, SQLAlchemy 2.0.
- Strict Typing: All functions MUST have hints.
- No Raw SQL: Always use SQLAlchemy ORM.

# Directory Map
- /src/api -> Route handlers only. No logic.
- /src/core -> Pydantic models & configs.

# 1. Create a project-scoped context profile for DB rules
agy skills add db-standards --file ./docs/db-rules.md

# 2. Attach the skill specifically to a task that requires it
# The agent reads the metadata, recognizes the context, and injects 
# the db-standards without bloating unrelated tasks.
agy run --skills="db-standards" "Refactor the user query in src/crud/user.py"

4. Security, MCP Integration, and Sandboxing

Agents use the Model Context Protocol (MCP) to securely connect to external databases, APIs (like Slack or Jira), and file systems without hardcoding credentials into prompts. This is where agentic AI becomes incredibly powerful—and incredibly dangerous.

Safe Database Interactions via MCP

Never give an agent a write-connection to a production or staging database. They are prone to destructive schema changes (e.g. running DROP TABLE) if they misunderstand a refactor prompt. Always use local Dockerized databases and force the agent to generate migration files rather than executing queries directly.

# Load specific MCP servers via JSON config
claude --strict-mcp-config ./mcp-dev.json

# Ask the agent to inspect using the MCP tool
> Use the postgres MCP tool to inspect 
  the 'users' table schema.

# Instruct it to write, NOT execute
> Write an Alembic migration script in Python 
  to add an 'is_premium' boolean column. 
  Save it to /alembic/versions/. 
  Do NOT run the migration.

OS-Level Sandboxing & Permission Guardrails

We are moving away from "YOLO Mode" (unrestricted execution). You must define exactly what an agent is allowed to do. Giving an agent unrestricted shell access is equivalent to giving a junior developer root access on their first day.

5. Agentic Test-Driven Development (TDD) & Self-Healing

In traditional engineering, tests prevent regressions. In agentic engineering, tests are the steering wheel. If an agent does not have a strict, programmatic way to verify its work, it will confidently lie to you about completing a task.

The "Test-and-Tea" Workflow (Automation Loops)

Do not manually review every syntax error. Write the test, give the agent a loop parameter, and step away to get tea. Shift-left testing is fundamentally required for agentic scale.

# Use -p and --max-turns to create a 
# bounded self-healing loop.

claude -p "Implement the Stripe webhook parser 
in src/billing.py. 

Once complete, run 'pytest tests/test_billing.py'. 
If tests fail, read the traceback, implement a 
fix, and rerun. 

Under NO CIRCUMSTANCES are you allowed to modify 
tests/test_billing.py. You may only modify 
src/billing.py." --max-turns 3

# Antigravity allows for continuous background QA.
# Start a background agent that runs pytest on 
# file save.

agy hooks add test-watcher \
  --trigger="on_file_save src/*.py" \
  --action="agy run 'pytest && ruff check' \
    --auto-fix-limit=2 \
    --lock-files='tests/'"

# If a test fails, it triggers the QA subagent 
# to attempt up to two automatic fixes before 
# notifying you in the terminal.

6. Day-to-Day Operating Scenarios

Theory is useful, but how does this look on a Tuesday morning? Here are common scenarios and the exact commands to orchestrate them.

7. The Agentic Engineer's Master Checklist