DEV Community: Heitor Vasconcelos

Splitting Planning and Execution in a Claude Code and DeepSeek Pipeline

Heitor Vasconcelos — Mon, 06 Jul 2026 17:57:45 +0000

Somewhere around the third feature request in a row, I noticed I was burning a full Claude Code session on work that did not need it. Adding a pagination parameter to an endpoint. Renaming a serializer field across four files. Tasks with a clear answer and almost no judgment involved, running through the same model I use to decide whether a migration is safe or whether a query pattern will lock a table in production.

That mismatch is what pushed me toward a two model pipeline: Claude Code handles planning and review, where judgment actually matters, and OpenCode running DeepSeek handles the mechanical part of writing the diff. This article walks through the architecture, the one gotcha that will silently break the whole thing, and the review loop that makes the split safe enough to trust.

Why split the roles at all

The instinct is to assume more capable equals better for every step, but planning, implementing, and reviewing are different kinds of work. Planning means reading a codebase and deciding what actually needs to change, which requires holding context and making judgment calls about side effects. Reviewing means catching the same kinds of mistakes: a serializer that silently drops a field, a queryset that N plus ones under load, a migration that is not reversible.

Implementing, once the plan is explicit and unambiguous, is closer to transcription. Take file A, add field B, follow the pattern already used in file C. A weaker or cheaper model can do this reliably as long as the instructions leave nothing to interpretation. DeepSeek V3 through OpenCode's free tier is good enough for that job, and it costs nothing in the cases where Claude Code's context window would otherwise get spent on boilerplate edits.

The trade is not quality for cost. It is deciding which step in the pipeline actually needs the more expensive judgment, and only paying for that.

The architecture

The pipeline is a Python orchestrator with three stages: plan, execute, review. Each stage shells out to a CLI tool and passes structured text between them.

agent-pipeline/
├── pipeline.py          # main loop
├── agents/
│   ├── planner.py       # calls claude -p to generate the plan
│   ├── executor.py      # calls opencode run to implement it
│   └── reviewer.py      # calls claude -p to review the diff
├── utils/
│   ├── git.py           # git diff and git status helpers
│   └── output.py        # stage separators for readable logs
└── config.py

The main loop is intentionally small. It does not try to be clever about parsing the plan, it just passes it along as text and lets each stage do one job.

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path

from agents.executor import run_executor
from agents.planner import run_planner
from agents.reviewer import ReviewResult, run_reviewer
from utils.git import get_diff


@dataclass
class PipelineConfig:
    project_path: Path
    max_retries: int = 3


def run_pipeline(request: str, config: PipelineConfig) -> None:
    plan: str = run_planner(request, config.project_path)
    print(f"PLAN:\n{plan}\n")

    feedback: str | None = None
    for attempt in range(1, config.max_retries + 1):
        prompt: str = plan if feedback is None else f"{plan}\n\nFix these issues:\n{feedback}"
        run_executor(prompt, config.project_path)

        diff: str = get_diff(config.project_path)
        result: ReviewResult = run_reviewer(diff, config.project_path)

        if result.approved:
            print("RESULT: approved")
            return

        print(f"REVIEW attempt {attempt}: issues found\n{result.issues}")
        feedback = result.issues

    print("RESULT: max retries reached without approval")

The planner and reviewer both call claude -p, Claude Code's non-interactive print mode, which returns a single response instead of opening a session. The executor calls opencode run --agent autoexec --model deepseek/deepseek-chat-v3-0324, passing the full plan as the prompt.

The gotcha: headless mode still asks for permission

The first time I ran this end to end, it hung. Not crashed, just sat there. OpenCode's default agent, even invoked through opencode run in a script, still pauses on write and delete operations to ask for confirmation. In an interactive terminal that is a reasonable default. In a subprocess call with no one watching the terminal, it is a deadlock that looks like a frozen process with no error message.

The fix is a custom OpenCode agent with permissions granted up front, so it never needs to ask.

---
name: autoexec
permissions:
  write: allow
  edit: allow
  delete: allow
  bash: allow
---

You implement the plan exactly as given. Do not ask for confirmation
before writing, editing, or deleting files within the project directory.

Saved at ~/.config/opencode/agents/autoexec.md, this agent runs to completion without blocking. It is worth being deliberate about scope here: full write and delete permissions inside an automated loop only make sense if the executor's target directory is a project you can safely revert with git, and if the plan it receives is specific enough that there is not much room for it to improvise its way into deleting something you needed.

The review loop and why it needs a strict protocol

The reviewer's job is to look at the diff and decide, not to have a conversation about it. That means its output needs to be machine parseable, not a paragraph of hedged observations. I settled on a fixed protocol: the reviewer must respond with either APPROVED or ISSUES: followed by a list.

from __future__ import annotations

import subprocess
from dataclasses import dataclass
from pathlib import Path


@dataclass
class ReviewResult:
    approved: bool
    issues: str


def run_reviewer(diff: str, project_path: Path) -> ReviewResult:
    prompt: str = (
        "Review this diff for correctness, side effects, and style consistency "
        "with the rest of the codebase. Respond with exactly one of two formats: "
        "'APPROVED' on its own, or 'ISSUES:' followed by a numbered list.\n\n"
        f"{diff}"
    )
    result = subprocess.run(
        ["claude", "-p", prompt],
        cwd=project_path,
        capture_output=True,
        text=True,
        timeout=120,
    )
    output: str = result.stdout.strip()
    if output.startswith("APPROVED"):
        return ReviewResult(approved=True, issues="")
    return ReviewResult(approved=False, issues=output.removeprefix("ISSUES:").strip())

Capping retries at three matters more than it seems. Without a ceiling, a plan that was ambiguous in a way neither model catches will loop indefinitely, each iteration burning a Claude Code call for review. Three attempts is usually enough to distinguish a fixable implementation slip from a plan that needs a human to rewrite it.

Common pitfalls

OpenCode has no memory between invocations, so the plan handed to the executor has to be fully self-contained. It cannot say "as discussed above," because there is no above from OpenCode's perspective. Every file path, every exact instruction, has to be spelled out as if this were the executor's first and only message, because it is.

The diff you pass to the reviewer needs to be the actual git diff output, not a summary of what changed. A summary written by the executor is exactly what you are trying to verify, so feeding it back as the thing being reviewed defeats the point.

DeepSeek's free tier on OpenCode also has rate limits that show up as a stall rather than a clear error in some client versions, which looks identical to the permission deadlock described above. Worth checking opencode logs directly if the executor step hangs after the agent config is already fixed.

Where this leaves the pipeline

Stage	Model	Job
Plan	Claude Code	Read the codebase, decide what changes
Execute	DeepSeek via OpenCode	Write the diff exactly as planned
Review	Claude Code	Catch mistakes, approve or send back

The next step worth adding is cost and token tracking per stage, so the split pays for itself in something more concrete than intuition. Once that is in place, the same pattern extends past a single request, feeding a small backlog of tickets through the loop overnight and reviewing only the ones that came back with unresolved issues.

Using Claude Code in a Django Workflow: What Actually Works

Heitor Vasconcelos — Mon, 29 Jun 2026 11:20:52 +0000

Most AI coding tools fall apart on real Django projects. Not because they can't write Python, but because Django projects have structure that generic LLMs don't know about: your specific app layout, which managers exist, how your serializers inherit from a base class you wrote six months ago, and the fact that nobody should touch the payments app without running the full test suite first.

Claude Code handles this differently. It reads your project before it writes anything. But "differently" does not mean "correctly by default." The workflow matters as much as the tool.

This article covers what actually works when using Claude Code on a Django project: how to set up context properly, what tasks are worth delegating, how to structure sessions to avoid entropy, and where the tool will quietly make mistakes if you let it.

CLAUDE.md as a Contract

Claude Code reads a CLAUDE.md file at the root of your project before doing anything else. Most tutorials treat this as optional configuration. It is not. For a Django project, this file is where you prevent the model from guessing.

The file serves one purpose: telling Claude Code what it cannot infer from the code alone. That includes your conventions, your constraints, and the things that would take a new engineer two weeks to learn by breaking them.

Here is a minimal but useful CLAUDE.md for a DRF and Celery project:

# Project Context

## Structure
- Core business logic lives in `apps/`. Each app is self-contained.
- Shared utilities go in `core/`. Never import from one app into another directly.
- All serializers inherit from `core.serializers.BaseModelSerializer`.
- Celery tasks are defined in `tasks.py` inside each app, not in views.

## Conventions
- Use `select_related` and `prefetch_related` explicitly. Never rely on lazy loading in views.
- All API views inherit from `core.views.BaseAPIView`, which handles error formatting.
- Migrations must be generated with `python manage.py makemigrations --check` before committing.

## Commands
- Run tests: `pytest apps/ -x --reuse-db`
- Lint: `ruff check . && mypy apps/`
- Never run `manage.py migrate` directly. Use the deployment script.

## Off-limits
- Do not modify anything in `apps/payments/` without explicit instruction.
- Do not touch `settings/production.py`.

Keep it short. The model reads the whole thing on every session start, so a 400-line CLAUDE.md with duplicated information is worse than a focused 40-line one. Write it for a competent engineer who needs project-specific context, not for someone who needs Django explained to them.

One opinion worth having: the Off-limits section is the most important part. Claude Code will helpfully refactor things it was not asked to refactor. Specifying what is untouchable is not paranoia, it is good engineering hygiene.

What to Delegate and What Not To

Claude Code is genuinely good at a specific category of Django tasks: things that are structurally predictable but tedious to type out correctly.

Delegate these:

Serializers for existing models, especially when the model has many fields or nested relations. The model writes the correct Meta, handles read_only_fields, and gets source= right on renamed fields.
ViewSet boilerplate with filterset_fields, search_fields, and ordering_fields.
Management commands. The structure is always the same; the logic is what varies.
Unit tests for views and serializers when you describe the expected behavior. The model writes the setup and the assertions; you verify the logic matches your domain.
Simple migrations after schema changes you have already made to the model.

Do not delegate these:

Schema decisions. If you ask Claude Code to "add a table for tracking user activity," it will produce something that works, but the schema it chooses will reflect generic best practices, not your domain. What belongs in a UserActivity row depends on how your system defines an "activity," what your reporting queries need to aggregate, and whether you have already solved this in a different table that the model does not know is related. That context does not live in the codebase; it lives in your head.

Celery task design involving side effects. The model will write a task that looks correct. If the task involves conditional branching based on external state, retries with backoff, or chaining with chord or chain, verify carefully. The model has no way to know whether your broker is configured to acknowledge tasks before or after execution, and that changes what "retry" means in practice.

Anything that depends on the current state of the database. If you are asking for a data migration or a queryset that depends on production data characteristics, you need to write that yourself or provide explicit counts and distributions. The model will write something that is logically valid but potentially catastrophic on a table with 20 million rows.

Structuring Sessions

The failure mode that nobody talks about: sessions that run too long. Claude Code maintains a context window, and as that window fills with tool calls, file reads, and intermediate outputs, the model starts optimizing for the immediate task rather than the overall constraints you set at the start.

A session that starts with "remember to always use select_related" and runs for 90 minutes will, somewhere around minute 60, generate a queryset without it. Not because the model forgot, but because the instruction is now far enough back in the context that it competes with everything else.

The practical fix is to treat each session as having a single objective, stated before you start.

Before starting a session, define:

What you are building (one sentence)
Which files will be modified
What done looks like (the test that passes, the endpoint that responds correctly)

For a complete endpoint, a session might look like this:

Goal: Add a GET /api/v1/reports/{report_id}/summary/ endpoint.
Files in scope: apps/reports/models.py (read only), apps/reports/serializers.py, 
apps/reports/views.py, apps/reports/urls.py, apps/reports/tests/test_views.py
Done when: test_report_summary_returns_correct_totals passes.

With that framing, the session stays bounded. The model is less likely to wander into refactoring apps/reports/tasks.py because it noticed something while reading the file.

Use /compact when the session has accomplished something but still has work left. Running /compact mid-session compresses the earlier context while preserving the active state. The right time to use it is after a subtask is complete: after the model has written the serializer and you have approved it, compact before moving to the view. Not before; you lose the reasoning that produced the serializer.

One thing /compact does not preserve well: negative constraints. "Don't use annotate here because of a known PostgreSQL planner issue on our table" will survive a compact less reliably than positive instructions. Re-state constraints explicitly after compacting if they are critical.

Common Pitfalls

Migrations generated without --check

Claude Code will run makemigrations when you ask it to, but it defaults to the basic form. If you have not added --check to your CLAUDE.md commands section, the model will generate migrations that you have not reviewed. Worse, if the project has MIGRATION_MODULES overrides or custom migration directories, the model may generate the migration in the wrong location. Specify the exact command in CLAUDE.md and the model will use it.

Imports from paths that do not exist in your project

The model infers import paths from patterns it sees in the codebase. If your project has an inconsistent import style (some files use relative imports, some use absolute), the model will produce a mix, and occasionally one will be wrong. This is more common in projects that went through a restructuring and have legacy import patterns still in the codebase. mypy catches these; run it as part of your session-end check.

Unrequested rewrites

Ask Claude Code to fix a bug in a view and there is a reasonable chance it will also rename a variable, reorder the methods, and add a docstring you did not ask for. This is not always wrong, but it creates noisy diffs that make code review harder. Add a line to your CLAUDE.md like Make the minimum change necessary to complete the task. It helps. It does not eliminate the behavior entirely, so reviewing the diff before staging remains your responsibility.

What Actually Changes

The speed improvement on isolated tasks is real but not the point. Where Claude Code changes the workflow is on tasks that span multiple files and require holding several constraints in mind simultaneously.

Writing an endpoint from scratch involves the model, the serializer, the view, the URL configuration, and the test. Doing all of that without losing track of a constraint you set at the start (say, "this endpoint must be paginated using the existing ReportPagination class") is where the tool earns its place in the workflow.

The practical next step: pick one recurring task in your project that is tedious but structurally consistent, write a tight CLAUDE.md entry for it, and run a single bounded session. See what comes out before deciding how much of the workflow to change.

Have you integrated Claude Code into a Django project? What broke first? Let me know in the comments.

Optimizing Django ORM Queries: A Practical Guide to select_related and prefetch_related

Heitor Vasconcelos — Mon, 22 Jun 2026 00:02:49 +0000

1. Introduction

Django's ORM is one of its greatest strengths. It abstracts away raw SQL, lets you express database operations in clean Python, and gets you productive fast. But that convenience comes with a hidden cost: if you're not deliberate about how you fetch related objects, you'll silently generate far more queries than you intend — and you won't notice until your app slows to a crawl in production.

The most common culprit is the N+1 query problem: a pattern where fetching a list of N objects triggers an additional query for each one, resulting in N+1 total round-trips to the database. At ten rows it's invisible. At ten thousand rows, it's a disaster.

Django provides two tools to fix this: select_related and prefetch_related. This article explains how each one works internally, when to use which, and how to combine them effectively — with before/after examples and real query counts throughout.

2. Understanding the N+1 Problem

Consider a simple blog with posts and authors. You want to render a list of posts, showing each post's title and its author's name.

Models:

# models.py
from django.db import models


class Author(models.Model):
    name: str = models.CharField(max_length=100)


class Post(models.Model):
    title: "str = models.CharField(max_length=200)"
    author: Author = models.ForeignKey(
        Author,
        on_delete=models.CASCADE,
        related_name="posts",
    )

The naive approach:

# views.py
from django.db import connection
from .models import Post


def list_posts() -> None:
    posts = Post.objects.all()  # Query 1: fetch all posts

    for post in posts:
        print(f"{post.title} by {post.author.name}")
        # ^^^ Query 2, 3, 4, ... N+1: one per post

For 100 posts, this produces 101 queries. Django lazily fetches post.author the first time you access it on each object. Each access hits the database separately.

You can verify this with django.db.connection.queries (requires DEBUG = True):

from django.db import connection, reset_queries

reset_queries()
posts = Post.objects.all()
for post in posts:
    _ = post.author.name

print(len(connection.queries))  # 101

In development, django-debug-toolbar gives you a visual breakdown of every query and its duration — highly recommended for catching this early.

3. `select_related` — For ForeignKey and OneToOne

How it works

select_related performs a SQL JOIN and retrieves the related object's data in a single query. When you access post.author, Django reads from the already-fetched data in memory — no additional database hit.

-- What Django generates under the hood:
SELECT post.id, post.title, post.author_id,
       author.id, author.name
FROM blog_post post
INNER JOIN blog_author author ON (post.author_id = author.id);

When to use it

Use select_related for:

ForeignKey relationships
OneToOneField relationships

These are the cases where the related object lives in a separate table and is reachable via a direct JOIN — exactly what select_related is built for.

Before / after

Before (101 queries for 100 posts):

def list_posts_naive() -> None:
    posts = Post.objects.all()
    for post in posts:
        print(f"{post.title} by {post.author.name}")

After (1 query):

def list_posts_optimized() -> None:
    posts = Post.objects.select_related("author")
    for post in posts:
        print(f"{post.title} by {post.author.name}")

You can also traverse multiple levels of ForeignKey in one call:

# Fetches post → author → country in a single JOIN
posts = Post.objects.select_related("author__country")

Limitations

select_related does not work for ManyToManyField or reverse ForeignKey (one-to-many) relationships. A JOIN on those would multiply rows rather than resolve them cleanly. For those cases, use prefetch_related.

4. `prefetch_related` — For ManyToMany and Reverse FK

How it works

prefetch_related takes a different approach: it runs separate queries for each relationship and then merges the results in Python. For a queryset of posts with tags (ManyToMany), Django will:

Fetch all posts — 1 query.
Fetch all tags for those posts in one WHERE id IN (...) query — 1 query.
Map tags back to their posts in memory.

Total: 2 queries, regardless of how many posts or tags you have.

When to use it

Use prefetch_related for:

ManyToManyField relationships
Reverse ForeignKey lookups (e.g., fetching all comments for each post)

Before / after

Models:

class Tag(models.Model):
    name: str = models.CharField(max_length=50)


class Post(models.Model):
    title: str = models.CharField(max_length=200)
    author: Author = models.ForeignKey(Author, on_delete=models.CASCADE)
    tags: models.ManyToManyField = models.ManyToManyField(Tag, related_name="posts")

Before (1 + N queries):

def list_posts_with_tags_naive() -> None:
    posts = Post.objects.all()
    for post in posts:
        tag_names = [tag.name for tag in post.tags.all()]
        print(f"{post.title}: {', '.join(tag_names)}")

After (2 queries):

def list_posts_with_tags_optimized() -> None:
    posts = Post.objects.prefetch_related("tags")
    for post in posts:
        tag_names = [tag.name for tag in post.tags.all()]
        print(f"{post.title}: {', '.join(tag_names)}")

The `Prefetch` object

For finer control — filtering, ordering, or annotating the prefetched queryset — use the Prefetch class:

from django.db.models import Prefetch
from .models import Post, Tag


def list_posts_active_tags() -> None:
    active_tags = Tag.objects.filter(active=True).order_by("name")

    posts = Post.objects.prefetch_related(
        Prefetch("tags", queryset=active_tags, to_attr="active_tags")
    )

    for post in posts:
        # post.active_tags is a plain list, not a queryset
        tag_names = [tag.name for tag in post.active_tags]
        print(f"{post.title}: {', '.join(tag_names)}")

to_attr stores the prefetched result as a Python list on the object, which is slightly faster to access than a queryset and makes the code intent explicit.

5. Combining Both

Real-world models rarely have just one relationship. Here's a more realistic example — a Post that has an Author (ForeignKey) and Tags (ManyToMany):

from django.db.models import Prefetch
from .models import Post, Tag


def list_posts_full() -> None:
    posts = (
        Post.objects
        .select_related("author")          # JOIN for ForeignKey
        .prefetch_related(                  # Separate query for ManyToMany
            Prefetch(
                "tags",
                queryset=Tag.objects.only("name"),
                to_attr="tag_list",
            )
        )
    )

    for post in posts:
        tag_names = [tag.name for tag in post.tag_list]
        print(f"{post.title} by {post.author.name} — tags: {', '.join(tag_names)}")

Total queries: 2 — one for posts JOIN author, one for all tags. This stays flat no matter how many posts are in the queryset.

You can chain as many select_related and prefetch_related calls as needed. Django deduplicates and optimizes them before sending anything to the database.

6. Common Pitfalls

Using `select_related` on ManyToMany

select_related silently ignores relationships it can't JOIN cleanly. You won't get an error — you'll just get the N+1 behavior back, with no warning.

# ❌ Does nothing for ManyToMany — falls back to per-object queries
posts = Post.objects.select_related("tags")

# ✅ Correct
posts = Post.objects.prefetch_related("tags")

Filtering a prefetched queryset after the fact

Prefetching caches the queryset result. If you apply a filter after the fact on a prefetched relation, Django bypasses the cache and hits the database again:

posts = Post.objects.prefetch_related("tags")

for post in posts:
    # ❌ New query per post — cache is bypassed
    active = post.tags.filter(active=True)

    # ✅ Filter inside the Prefetch object instead

The fix is to push the filter into a Prefetch object as shown in section 4.

Over-fetching with `select_related`

A wide JOIN can pull in more data than you need. If you only use post.author.name, fetching the entire Author row (with bio, avatar URL, created_at, etc.) wastes bandwidth. Combine with only() to limit columns:

posts = Post.objects.select_related("author").only(
    "title", "author__name"
)

7. Conclusion

The choice between select_related and prefetch_related comes down to the relationship type:

Relationship	Tool
`ForeignKey` / `OneToOneField`	`select_related` (SQL JOIN)
`ManyToManyField` / Reverse FK	`prefetch_related` (separate queries + Python merge)
Both in the same queryset	Chain them together

Start by identifying your hot querysets — the ones called on list pages or inside loops. Add django-debug-toolbar to your dev environment and look for duplicate queries. Then apply select_related or prefetch_related as appropriate and watch your query count drop.

Once you've mastered these two tools, the natural next steps are only() and defer() to control which columns are fetched, and annotate() with aggregates to push computation into the database instead of Python. Those techniques, combined with what you've learned here, cover the vast majority of Django ORM performance problems you'll encounter in production.

DEV Community: Heitor Vasconcelos

Splitting Planning and Execution in a Claude Code and DeepSeek Pipeline

Why split the roles at all

The architecture

The gotcha: headless mode still asks for permission

The review loop and why it needs a strict protocol

Common pitfalls

Where this leaves the pipeline

Using Claude Code in a Django Workflow: What Actually Works

CLAUDE.md as a Contract

What to Delegate and What Not To

Structuring Sessions

Common Pitfalls

What Actually Changes

Optimizing Django ORM Queries: A Practical Guide to select_related and prefetch_related

1. Introduction

2. Understanding the N+1 Problem

3. select_related — For ForeignKey and OneToOne

How it works

When to use it

Before / after

Limitations

4. prefetch_related — For ManyToMany and Reverse FK

How it works

When to use it

Before / after

The Prefetch object

5. Combining Both

6. Common Pitfalls

Using select_related on ManyToMany

Filtering a prefetched queryset after the fact

Over-fetching with select_related

7. Conclusion

3. `select_related` — For ForeignKey and OneToOne

4. `prefetch_related` — For ManyToMany and Reverse FK

The `Prefetch` object

Using `select_related` on ManyToMany

Over-fetching with `select_related`