I Used Parallel Subagents in Claude Code to Audit My Android App — Here's How It Works
Skills encode what Claude knows. Hooks enforce what Claude can do. But there's a third primitive that completes the picture: subagents — specialized agents you can launch in parallel to independently inspect your codebase and report back.
I set up two of them for my AI News App and ran them simultaneously with a single prompt: one to audit Clean Architecture boundaries, one to audit Compose UI violations. Here's how the whole thing is structured and why it works.
What Are Claude Code Subagents?
In Claude Code, you can define project-scoped agents under .claude/agents/. Each agent has a specific role, a focused system prompt, and a restricted set of tools. Mine are read-only — they're auditors, not auto-fixers.
My project has two:
arch-guard-agent — audits whether presentation layer files import from the data layer, a Clean Architecture violation
verify-ui-agent — audits Compose composables against UI guidelines: hardcoded colors, missing keys in lazy lists, improper state handling
Because they're independent, both can be launched in a single message. Claude spins them up concurrently — each reads the files relevant to its domain, applies its checklist, and reports findings independently. Results come back together.
How to Set Up Project Subagents
Each agent is a single markdown file at .claude/agents/<agent-name>.md:
---
name: arch-guard-agent
description: Checks architectural violations — presentation importing data, or domain importing Android SDK
allowed_tools: Read, Grep, Glob
---
You are a Clean Architecture auditor for an Android project.
Check for layer boundary violations and report each one with
the file path, line number, and what the correct fix should be.
Three things matter in this definition:
description — This is what Claude reads to decide which agent to use. The more precise it is, the more reliably Claude selects the right agent for a given task. Write it like a job title: specific, scoped, unambiguous.
allowed_tools — Restricts what the agent can do. Read, Grep, Glob means it can read and search but cannot edit anything. For an audit agent, that restriction is the point.
The system prompt — This is where you encode your team's standards. What counts as a violation? What does a valid report look like? How should findings be structured? The more concrete and specific, the better the output.
Why Parallel Subagents
The sequential alternative — asking Claude to "check architecture then check UI" — uses more context, takes longer, and risks the second analysis being influenced by the first. Parallel subagents are isolated: each starts fresh, reads the files it cares about, and reports without the other's context bleeding in.
For audits, that isolation is what you want. You get two independent reads on the same codebase, in the time it would take to do one.
The output from each agent is structured and self-contained — a clean list of findings with file paths, line numbers, and what the problem is. Actionable, not vague.
The Full Stack: Skills → Hooks → Subagents
After building out all three primitives in this project, here's the mental model I've settled on:
Skills are documentation made executable. Hooks are guardrails that fire at edit time. Subagents are specialized reviewers you dispatch on demand.
Together they give you layered quality enforcement: hooks catch violations in real time as Claude edits files, subagents audit anything that predates or bypasses the hooks, and skills give Claude the domain knowledge to fix what it finds. Each layer does something the others can't.
Setting Up the Audit Run
Once the agents are defined, invoking them in parallel is just a matter of asking Claude to run both in a single prompt:
can you verify the architecture changes and compose ui using subagents
Claude identifies the two relevant agents from their descriptions, launches them concurrently, and returns both reports when they finish. No manual coordination. No sequential waiting.
The reports are structured consistently — each agent follows the format defined in its system prompt — so findings are easy to scan, prioritize, and act on.
Why This Matters
Manual audits are valuable but expensive. Running through every file, checking every import, verifying every composable against a checklist — it's the kind of mechanical work that's easy to skip under deadline pressure.
Subagents make comprehensive audits free to run. Define the checklist once in the agent's system prompt. Invoke whenever you want a full pass. The cost drops from "half a day" to "two minutes and one prompt."
For teams enforcing Clean Architecture, specific Compose patterns, or any other non-negotiable standard, this is how you make those standards continuously verifiable — not just documented.
Try It Yourself
Create .claude/agents/ in your project
Write one agent per audit dimension — keep each focused and specific
Use allowed_tools: Read, Grep, Glob for read-only auditors
Write a precise description field — that's how Claude picks the right agent
Invoke both in a single prompt and let them run in parallel
