Conversational Development With Claude Code — Part 7: Designing Sub‑Agents for Planning (Meet **@architect**)

Conversational Development With Claude Code — Part 7: Designing Sub‑Agents for Planning (Meet @architect)

TL;DR — Sub‑agents turn Claude Code from a single “chatty assistant” into a small, specialized engineering team. In this chapter we’ll create an Architect agent that can reuse prior context (via resume), produce a structured implementation plan for a 1–5 star ratings feature, and persist that plan as versioned Markdown specs inside the repo—without losing auditability or control.

This part is about planning as an artifact, not planning as a vibe.

Why sub‑agents matter: one thread can’t hold a whole system forever

A mature codebase is a city.

Even with a large context window, a single conversation tends to drift:

• analysis gets mixed with implementation details,
• decisions fade as new outputs arrive,
• and your “mental map” becomes a pile of chat scroll.

Sub‑agents are the counter‑measure: bounded roles with explicit responsibilities.

Instead of asking the main session to be everything at once, you delegate to a specialist—like you would in a real team:

• an Architect for system design and phased rollout,
• a Backend agent for API and persistence changes,
• a QA agent for test strategy and regressions,
• a Frontend agent for UI integration and state flows.

The trick is not that they write code faster.
The trick is that they think with sharper boundaries.

Step 0 — Recover the project’s mental model with resume

Before you create any agent, you should recover the decisions that already exist.

Claude Code gives you a pragmatic primitive for this:

resume

That command lets you list previous conversations and select the one that contains:

• your earlier impact analysis,
• the repository structure,
• the constraints for the ratings feature (1–5 stars),
• the scope adjustment (no mobile),
• and any architectural conventions you want preserved.

When you resume the right thread, you don’t start from ignorance—you start from continuity.

Engineering insight: Sub‑agents are only as good as the context you feed them.

resume is how you avoid building plans on amnesia.

Step 1 — Open the agent workspace and choose the scope

Claude Code supports managing agents through an “agents” interface.

You’ll create a new one manually (manual is key: it keeps the design intentional).

Goals for this agent

We are building Architect, a planning specialist for the ratings feature:

• create a phased implementation plan,
• identify architectural impact across DB → API → Services → Repos → UI,
• include performance, testing, scalability, and security considerations,
• output a Markdown spec that can be versioned.

Scope: personal vs project

Choose the scope that matches your intent:

• Project scope: best when this repo has shared rules and the team benefits from consistent planning artifacts.
• Personal scope: useful if you want the agent across multiple repos.

For a feature‑planning agent that embeds repo conventions, project scope is usually the right call.

Step 2 — Design the agent definition (YAML front matter + system prompt)

A sub‑agent is not “a model with a name.”
It’s a contract: role + constraints + output format + tooling boundaries.

Most Claude Code setups represent an agent as a Markdown file with:

1. YAML front matter (metadata)
2. System prompt (behavioral spec)

Here’s an example you can adapt.

File: Claude/Agents/architect.md (or whatever folder your Claude Code installation uses for agent definitions)

---
name: architect
description: Specialist in software architecture, system design, and deep technical impact analysis.
model: inherit
color: yellow
---

Why model: inherit?

inherit means the agent uses whatever model your current session is configured for, keeping behavior consistent with your environment. If you prefer explicit selection, set it to your chosen model (e.g., Sonnet/Opus/Haiku equivalents in your environment).

Why color matters

Color is not decoration; it’s a cognitive affordance.
When you invoke @architect, a visible highlight confirms:

• you’re talking to the right agent,
• the right system prompt is active,
• the output should follow the agent’s format and discipline.

Step 3 — The Architect system prompt (write it like you’d brief a senior teammate)

Below is a strong baseline system prompt. It’s dense on purpose: this is an engineering role description, not a motivational quote.

# Agent Architect — Software Architecture Specialist

You are a software architect specialized in:

## Core Expertise
- Clean Architecture: layering, dependency direction, inversion of control
- System Design: scalability, performance, maintainability
- Database Design: relational modeling, indexes, migrations, optimization
- API Design: REST principles, contracts, versioning
- Security Architecture: authentication, authorization, data protection

## Responsibilities
- Deep impact analysis: evaluate architectural consequences of changes
- Database design: propose normalized schemas + indexing strategy
- API contracts: define clear interfaces between components
- Patterns: apply appropriate design patterns consistent with the repo
- Technical documentation: produce high-quality specs and plans

## Project Context: Platziflix
- Architecture: Clean Architecture with FastAPI + Next.js
- Flow: API → Service → Repository → Database
- DB: PostgreSQL with SQLAlchemy ORM
- Frontend: Next.js with TypeScript
- Testing: test pyramid (unit → integration → E2E)

## Method
1) Understand requirements and constraints
2) Impact analysis: identify affected components and risks
3) Solution design: follow existing architecture & patterns
4) Validation: SOLID + clean architecture principles
5) Documentation: produce a clear technical spec

## Output Format (MANDATORY)
Produce a Markdown document with:

# Technical Analysis: <Feature Name>

## Problem
<what we are solving>

## Architectural Impact
- Backend: <models/services/API impacts>
- Frontend: <components/state/UI impacts>
- Database: <tables/relations/indexes/migrations>

## Proposed Solution
<architecture proposal aligned with existing patterns>

## Implementation Plan (Phases)
1. Phase 1: <DB + critical foundation>
2. Phase 2: <API layer>
3. Phase 3: <Frontend integration>
4. Phase 4: <Testing + hardening>

## Performance Notes
<indexes, query strategy, caching if relevant>

## Testing Strategy
<unit/integration/E2E, what to validate>

## Scalability & Future Extensions
<how this feature evolves safely>

## Risks & Mitigations
<top risks, how to reduce them>

Be concise in wording but deep in reasoning. Prefer clarity over verbosity.
Never invent file paths—request references via @ mentions if needed.

This prompt is intentionally opinionated:

• it narrows the output shape,
• it enforces architectural lens first,
• it prevents “random code dumping,”
• it turns planning into a spec that can be committed.

Step 4 — Tools and permissions (power with guardrails)

A planning agent often needs:

• read access (browse codebase, inspect files)
• limited execution (optional; e.g., run tests or list directories)
• write access (to save the spec)

The principle is simple:

Give the agent the minimum permissions required to produce the artifact you want.

If the agent must write a spec file, avoid “read only” mode—otherwise you’ll get a plan you still have to manually persist.

Step 5 — Restart Claude Code to load the new agent definition

In many setups, Claude Code loads agent definitions at startup.

So after saving the agent file:

1. close Claude Code (or reload the session)
2. re‑open it in your project directory
3. use resume to restore the conversation that contains the ratings context

This is like restarting an application after modifying configuration: boring, but correct.

Step 6 — Invoke the agent: @architect + Tab to lock it in

Once you’re back in the right thread, invoke:

@architect

Then press Tab to ensure the agent is pinned into the active context (and visually highlighted—yellow in our example).

Now give a precise instruction that binds the agent to your existing context:

@architect Use the existing project context and the prior ratings analysis. 
Produce an implementation plan for a 1–5 star rating system focused ONLY on backend + frontend (exclude iOS/Android). 
Output as a spec following your required Markdown format. 
If you need repo details, ask me to reference files using @mentions.

This single prompt enforces:

• continuity (use existing context),
• scope (no mobile),
• output discipline (spec format),
• safety (no invented file paths).

Step 7 — Persist the plan as a versioned spec inside the repo

Planning is only valuable when it is portable:

• reviewable in PRs,
• diff‑able over time,
• readable during onboarding,
• recoverable when the conversation is gone.

A simple convention works extremely well:

• folder: spec/ at repo root
• files: 00-feature-name.md, then 01-..., etc.

Example instruction:

@architect Save this plan in the repository as spec/00-ratings-implementation-plan.md.
If the spec folder doesn’t exist, create it.

Now your plan is not just chat—it’s a living document.

What a good Architect plan typically includes (and why it’s non‑negotiable)

A high‑quality plan for ratings should cover at least:

Database (Phase 1 — critical foundation)

• table design for ratings (and whether you allow multiple ratings per user/course)
• constraints (1–5 range enforced at DB and app layer)
• indexes to avoid slow aggregation queries
• migration strategy (and rollback awareness)

Backend

• models/entities aligned to current domain boundaries
• service‑layer logic (validation, idempotency, update vs create)
• endpoints: create/read/update rating, and course rating summary
• clear contracts and response shapes

Frontend

• UI component for star input
• optimistic updates vs server‑confirmed updates
• how rating affects course detail pages and listings
• handling “no rating yet” states cleanly

Testing

• unit tests for validation (1–5 enforcement)
• integration tests for API + DB
• E2E tests for the rating UI flow (Playwright if that’s the stack)

Performance & scalability

• aggregated rating strategy (compute on read vs store summary)
• index design and query plans
• future extension: rating history, reviews, moderation, analytics

Planning without these is not planning.
It’s a wish.

A note about “Thinking” modes: the UI changes, the principle doesn’t

Depending on your Claude Code version, older commands like:

• think
• think deeply
• ultrathink

may not exist as separate commands anymore.

Some environments replaced them with a single “Thinking On/Off” toggle in /config (often accessible via a shortcut like Alt + T). In other contexts you may still see ultrathink: used as a prefix.

Regardless of the UI, the engineering principle remains stable:

Use stronger reasoning when you need analysis, impact, and design—not when you’re generating boilerplate.

Sub‑agents make this even more practical: instead of flipping thinking for everything, you route deep work to the right specialist.

The real magic of @architect: perspective as a service

There is a quiet psychological benefit to a well‑designed sub‑agent:

When you’re deep in implementation, your brain optimizes for motion.
The plan dissolves.

@architect acts like an external reviewer who keeps you honest:

• it returns you to constraints,
• it restores coherence,
• it forces the sequence.

It doesn’t replace judgment.
It protects it.

Final thoughts

Sub‑agents are not “prompt tricks.”
They are a new unit of engineering organization.

When you can create specialists, resume decisions, and persist plans as versioned artifacts, you stop treating AI as a chat window and start treating it like a disciplined collaborator.

Next chapters will build on this foundation:

• using @architect + @backend + @qa as a coordinated pipeline,
• turning specs into incremental PRs,
• and keeping the system honest through tests, performance constraints, and architectural memory.

— Written by Cristian Sifuentes

Full‑stack engineer · AI‑assisted systems thinker