The AI System Architecture Behind Managing 15+ Projects Solo — Not a Story, the Technical Details

No story here. Just the architecture.

If you've ever wondered how one person manages that many projects, the answer isn't time management techniques or priority matrices. It's a system. Here's every technical layer of it.

---

Current Numbers

• 17 projects
• 53 agents
• 142 skills (reusable SOPs callable by any agent)
• 8 hook events, 25 hook rules, 34 hook scripts
• 17 official plugins enabled

These aren't numbers I'm proud of. They're what the system naturally accumulated to. Most of the time it runs quietly in the background and I don't need to touch it.

---

Three-Layer Knowledge Architecture

This is the single most important design decision in the whole system. Everything else is an extension of it.

Layer 1: CLAUDE.md = Routing

CLAUDE.md answers one question: When X happens, who do I call?

# Routing logic examples from CLAUDE.md

**Bug routing (CRITICAL)**:
- Any bug, error, fix, debug task → bug-fixer agent + bug-fix-sop skill
- NEVER investigate bugs directly — main agent is forbidden from reading code to analyze bugs
- Even "just a quick look" is prohibited

**Issue-Based Development (CRITICAL)**:
- ALL #N issue work MUST use git-issue-pr-flow agent
- NEVER edit code directly on main/staging

CLAUDE.md stores routing logic, not knowledge. Putting technical details here is a common mistake — it bloats the file and AI attention degrades toward the bottom. Keep it thin.

Layer 2: Agent = Project Cheat Sheet

Each project has its own agent. It stores only what's unique to that project: tech stack, deployment process, which APIs to call, business logic boundaries.

# Structure of the care-home-manager agent

## Project Overview
Nursing home PDCA system. Next.js + FastAPI + GCP Cloud Run.

## Deployment
- Staging: PR merged to staging branch → automatic Cloud Run deploy
- Production: Requires Young's manual confirmation

## Special Rules
- Long-term care data privacy: never log resident names
- Shift scheduling feature must be updated before end of each month

The rule is: agents only store what this project has that others don't. Shared rules are inherited from CLAUDE.md and never duplicated.

This keeps each agent file lean. Every line the AI reads is relevant.

Layer 3: Skill = Full SOP Manual

Skills are reusable standard operating procedures callable by any agent.

One skill, one job. Write it once, reuse across all projects. Agents don't each need to carry their own copy.

---

Window Separation

Two kinds of terminal sessions are always running:

HQ window (young_job_maanger repo): read-only. Check status, create GitHub Issues, dispatch tasks. Never touches code, never commits, never pushes to any project repo.

Frontline windows (individual project repos): execution mode. Write code, run tests, commit, push.

This isn't just convention — it's enforced. The HQ window's CLAUDE.md explicitly states:

❌ Forbidden actions:
- Modifying code in other projects
- Running git commit/push in other project repos
- Proactively asking "Want me to start implementing this?"

The reason: one window can't hold context for 17 projects simultaneously. Forced separation means each window's AI works with clean, focused context.

---

Sync Flow: Parallel Haiku Subagents

When I need the status of all projects, I don't run one agent through 17 repos sequentially. I launch 17 Haiku subagents simultaneously:

Why Haiku? This is a pure read task. No deep reasoning needed. Haiku is fast and cheap. Running Sonnet or Opus on git log parsing is waste.

---

Hook System: Automated Guards

Hooks are the most underrated and most effective part of the whole system.

8 active hook events:

Key hook rules in practice:

A few examples to illustrate what hooks do, without showing implementation:

• Branch protection: Try to push directly to main/staging? Hook blocks it, forces PR workflow
• GCP auto-switch: Different projects use different GCP accounts. Hook auto-switches based on directory — no manual gcloud auth between projects
• Verification guard: Agent says "done" but shows no proof (screenshot, curl response, commit hash)? Blocked until evidence is provided
• Code review tracking: Wrote code but didn't run tests? Logged and flagged

These hooks aren't suggestions — they're physical constraints. AI taking shortcuts under pressure is predictable behavior. Hooks make certain shortcuts technically impossible to execute.

---

Agent Strategy Selection

This is the most commonly misused part.

More agents isn't better. The goal is matching the right strategy to the right scenario:

Scenario	Strategy	Reason
Read 1-3 files, answer a question	Direct tools	No agent needed
Scan all 17 project statuses	Task() subagents	Parallel, independent, no cross-talk
Bug investigation → fix → verify	Single Task()	Sequential, no parallelism benefit
Backend change affects frontend	Agent Teams	Requires intelligence sharing

Agent Teams (agents coordinating with each other) cost roughly 3.5x the tokens of Task() subagents. Using them when cross-agent coordination isn't actually needed is pure overhead.

---

Bug Routing: A Painful Postmortem

The incident on 2026-02-16: A frontend bug came in. I (the main agent) started reading source code to analyze it directly. Ten minutes of code reading with no browser open and no reproduction attempt. The user could have spotted the visible bug in 30 seconds by just opening the page.

That incident produced this rule in CLAUDE.md:

Current bug routing:

The main agent doesn't read code. It doesn't analyze. It dispatches. This feels wrong intuitively, but the outcomes are consistently better than "let me just look at it first."

Frontend bug verification runs in two phases:

• Phase 1 (mandatory): quick-verify skill — Chrome MCP fast check (2-5 min)
• Phase 2 (when needed): frontend-bug-verification — Playwright full check (10-15 min)

---

Issue-Based Development: Another Postmortem

The incident on 2026-02-22: Issue #31 was a UI fix. The change went directly onto main — no worktree, no feature branch, no PR, no staging preview. CLAUDE.md at the time didn't explicitly require feature branches. No hook blocked it.

The rule now:

git-issue-pr-flow is a flow agent: give it any #N issue and it automatically creates the worktree, creates the branch, pushes, and opens a PR. The implementation agents (backend-developer, frontend-developer) only write code — they handle no git workflow at all. Separation of concerns at the agent level.

---

Single Source of Truth

All project metadata lives in one file: projects-registry.json.

{
  "projects": [
    { "id": "project-a", "status": "active", ... },
    { "id": "project-b", "status": "active", ... },
    { "id": "project-c", "status": "shelved", ... }
  ]
}

Each entry contains the project's path, repo, deployment config, and status. Every agent reads from this single file — no agent is allowed to hardcode any value in its own definition.

Change one thing here, everything updates.

---

What's Working, What Isn't

Working well:

• CLAUDE.md as router, not knowledge base. The first version stuffed everything into CLAUDE.md. AI attention dropped off by the end. Now CLAUDE.md only holds routing logic and boundary rules. Details live in agents and skills.
• Hooks as physical constraints, not reminders. A note saying "remember to open a PR" does nothing. A hook that blocks the push does.
• Agent inheritance. Shared rules live in CLAUDE.md. Agents store only project-specific knowledge. 53 agents stay maintainable because of this.
• Haiku for sync tasks. Fast, cheap, sufficient. Using Sonnet to parse git log is overkill.

Initially underperforming, later closed the loop:

• Plan Mode usage was too low. 361 sessions, used exactly once. The problem wasn't laziness — there was no hook forcing it. Later, an explicit rule was added to CLAUDE.md: tasks touching 3+ files must enter Plan Mode. Combined with the stop-verification-guard hook that blocks completion claims without evidence, overall quality improved noticeably
• TDD usage. backend-developer was called 48 times with near-zero test coverage. Later, a pre-test-quality-reminder hook was added: before writing test files, it auto-reminds to read the model first — preventing mocks of nonexistent fields (from the Issue #208 postmortem). A post-test-quality-check hook validates test quality after writing
• Code review agent. Built but unused. Later closed with two hooks: pre-tool-use-commit-guard checks for a code review marker before git commit (warns if missing), and post-tool-use-code-review-tracker auto-creates the marker when the code-reviewer agent completes. No review marker before commit = blocked

The pattern: every underperforming feature was eventually fixed by adding a hook. Rules in CLAUDE.md are reminders. Hooks are physical constraints — this conclusion was validated across all three cases

---

The system wasn't designed all at once. Every rule in CLAUDE.md, every hook, every agent responsibility boundary has a specific incident or efficiency problem behind it. This article is the current state of the system laid out in the open — not "you should build this," but a working reference point.

If you're building something similar, I'm happy to compare notes.

---

Young Tsai is a freelance AI developer managing diverse client projects. This article reflects the system as of 2026-03-16.