🤖 AI Coding Agent Workflow

AI Agent Workflow: Report export endpoint with async Celery job

An AI coding agent workflow is a structured 4-loop pattern (spec → run → review → refine) that extracts senior-engineer-level output from AI assistants while avoiding the 'fluent bad code' trap. Based on observed productivity patterns across 2 years of AI-assisted development, engineers using structured 4-loop workflows ship 3-5x faster than those using AI as autocomplete — and produce code that passes review at similar rates to manually-written code. Your task is ideal for delegated-task pattern because it has clear inputs, outputs, and integration points.

Pattern Classification

Delegated task. You have a clear goal (new endpoint), known integration points (DRF, Celery), and bounded scope. You can specify it fully and let the agent implement with less back-and-forth. Not pair-programming (too much typing for well-defined work). Not bulk-refactor (single feature).

The 4-Loop Structure

Loop 1 — Spec (15-30 min): Write the full specification BEFORE opening Claude Code. Include existing patterns to follow, test expectations, integration requirements.

Loop 2 — Agent run (30-60 min): Give the spec; let agent draft endpoint + tests + Celery task. Ask clarifying questions if needed.

Loop 3 — Review (20-30 min): Review code against spec. Run tests. Check for hallucinations.

Loop 4 — Refine (30-60 min): Iterate with specific feedback. Fix what's wrong. Expand test coverage if thin.

Total: 2-3 hours for MVP, vs. 6-8 hours hand-written. Save 3-5 hours.

The Specification Prompt

Context: I'm working in a Django + DRF + Celery codebase. Existing API patterns use:
- DRF ViewSets with serializers
- Celery tasks in tasks.py per app
- Jobs table for tracking async work (look at reports/models.py)

Task: Add POST /api/v1/reports/export endpoint.

Requirements:
1. Accept JSON body: { "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "format": "csv" | "pdf" }
2. Validate: end_date >= start_date, date range <= 1 year
3. Authenticated endpoint (user must be logged in)
4. Create a ReportJob record with status="pending"
5. Dispatch Celery task generate_report_task(job_id)
6. Return 202 Accepted with { "job_id": "<uuid>", "status": "pending" }

Integration points:
- ReportJob model exists in reports/models.py — use existing pattern
- Celery task should update job status (pending → running → completed/failed)
- Don't implement actual CSV/PDF generation yet — stub with TODO + log statement

Tests required (TDD):
- Unit test: endpoint validation (missing fields, invalid dates, end < start)
- Unit test: endpoint creates job + dispatches task
- Integration test: task updates job status
- All tests using pytest + pytest-django conventions (match existing test/ structure)

Please:
1. First, write the tests (failing)
2. Then write the implementation
3. Show me both in your response
4. List any assumptions you're making

The Review Checklist

After agent produces code:

• [ ] Tests actually test the stated behavior. Not just 'tests exist' — do they verify the requirements?
• [ ] All imports resolve. No hallucinated packages. Check drf_standardized_errors actually exists in your requirements.
• [ ] Follows existing patterns. Does the ViewSet match your other endpoints? If not, flag.
• [ ] Error handling matches codebase conventions. Django exceptions vs. DRF exceptions — consistent?
• [ ] Celery task handles failure gracefully. Retry logic? DLQ?
• [ ] No over-engineering. Did agent add features you didn't ask for (pagination, filtering, extras)? Usually delete those.
• [ ] Migration needed? If ReportJob model is modified, did agent generate migration?
• [ ] Security: endpoint auth correctly enforced? No IDOR? Rate limiting needed?

The 5 Failure Modes (Avoid These)

1. Underspecified prompt. 'Add an endpoint' gives you a generic implementation that doesn't fit your codebase. Spec was your longest time investment — do it well.

2. Accepting first output. Review EVERY file. AI produces plausible code that subtly doesn't match your conventions. Refinement is not optional.

3. Skipping test-first. AI can write tests + code faster than you can, but only if you ASK for tests. Otherwise it often skips them or produces trivial ones.

4. Trusting imports. AI occasionally imports packages that don't exist or don't exist at the version you're using. Run `pip install -r requirements.txt` + run tests — catches this immediately.

5. AI over-engineering. Agent may add pagination, filtering, caching, all not in your spec. Delete the unrequested additions.

The Test-First Protocol

Ask for tests BEFORE implementation in the same prompt:

• 'First, write the tests (failing)'
• 'Then write the implementation to pass them'

This is TDD-like and produces 2-3x better test coverage than implementation-first prompts. Even if you iterate, the tests define the target and shift the agent into a known-good pattern.

If you've already gotten implementation-first output, refuse to accept without tests — 'Now write the tests that verify this implementation covers requirements X, Y, Z.'

Iteration Strategy

When to refine:

• Output matches spec but style is off → refine with specific feedback ('match the ViewSet pattern in reports/views.py — particularly the error response shape')
• Tests missing edge cases → 'Add tests for: empty request body, invalid format string, dates in wrong order'
• Imports wrong → 'The package X isn't in our requirements; use Y pattern from reports/views.py instead'

When to start over (new thread):

• Output diverges significantly from what you asked
• Agent is confused about your codebase patterns after 2 refinements
• Accumulated refinements are making the context muddy

Rule of thumb: if 3 rounds of refinement don't get you close, start over with a better spec.

Your Time-Budget

50% time savings. Better spec = bigger savings.

Key Takeaways

• Spec writing is your highest-leverage activity. 30 min on spec saves 3 hours on implementation.
• Always ask for tests FIRST. Tests-then-implementation produces better output than reversed.
• Review against the spec. Not against 'does it look right' — does it match what you asked for?
• Iterate 2-3 times max per thread. If it's not landing, start over with a tighter spec.