Building a Personalized Agent Team and Harness

Why Build a Personalized Agent Team and Harness?

When you drive a complex project with Vibe Coding, a single Agent soon hits a capability bottleneck. First, the context window fills up with low-value information until the task stalls. Second, search, planning, and coding all run in one process, which is inefficient and error-prone. Finally, there is the safety problem: without a global plan, rework is likely; without permission isolation, an Agent can trigger dangerous operations.

An Agent Team separates the roles. Planning and execution get separate owners, and reading and writing stay apart. That eases the first two problems considerably. The Harness sits a level above and governs the team. It allocates permissions, matches models, manages context, and constrains behavior. But an off-the-shelf solution rarely drops in cleanly. Every project has its own tech stack, engineering conventions, task types, and development process. So a one-size-fits-all approach rarely works.

Fortunately, building your own is not complicated. Open a multi-Agent IDE or CLI (such as Claude Code or OpenCode) and do three things in order: design the architecture and roles, manage permissions, models, and context, and add a Plan workflow. There is also a faster way: import a ready-made Team + Harness framework and tailor it to your project.

Step 1: Design the Architecture and Roles

Start Simple

You do not have to build the full multi-role team from the start. Start with one Agent (call it Builder), roughly the same as the default Build Agent in most AI coding tools. As tasks get more complex, split out roles as needed. At the implementation level, a role is a Sub-agent that receives the specific tasks Builder delegates:

• Builder handles all the work. When its context gets tight or it slows down, consider splitting off some responsibilities.
• Add read-only roles Explorer / Researcher to handle search and information gathering, taking retrieval work off the main Agent.
• Add Coder to handle implementation and code changes, improving code quality and coherence.
• Add Planner to plan and break down complex multi-file or multi-step tasks.
• Add Reviewer, General, and other roles as needed, for review, general assistance, or permission isolation.

“The best agent architecture is the one you don’t need to build. Start simple. Add complexity only when metrics prove it helps.”

— Reliable Data Engineering

Core Design Principles

• Separate planning from execution. Planning (deciding what to do and how to split the work) and execution (actually implementing and changing code) are two different cognitive activities. Give them to different roles to avoid frequent context switching and mistakes.
• Separate reading from writing. The risk and cost of searching and reading information differ sharply from those of writing code. A bad read wastes time at worst; a bad write can damage the project. So give retrieval work to read-only roles, and give code changes to roles with write access and a review process.
• Separate internal from external. Searching your own codebase and searching the internet call for different tools and strategies. Codebase search depends on understanding the project structure (Glob/Grep/Read), while internet search leans more on keywords, judging sources, and putting information together. Mix the two in one role and you get a bloated toolset or strategies that interfere with each other. Design them separately and manage them independently.

Builder’s Routing Decision

Builder is the decision-maker for the whole team, so give it the most capable general-purpose model (for example, Claude Opus). It almost never writes code directly. Its core job is to route work: decide who does what, and delegate each piece to the most suitable role.

Here is a typical routing table:

Your job is to describe each Agent’s responsibilities clearly. The model behind Builder decides who gets the work. As you run the team, adjust the routing rules and thresholds based on actual results. Once you have enough experience, you can add quantitative metrics such as delegation success rate, rollback count, and task completion time to keep refining how work is divided.

Additional Behavior Rules

Start by adding these rules to the Builder prompt. Leave the exact numbers to the model, then refine them as you go:

• Prefer Delegation: When unsure, delegate first, so Builder does not degrade into an all-purpose Agent with its context flooded with details.
• 3-Failure-Stop: If the same subtask fails three times in a row, stop and ask the user. Do not retry forever.
• Plan Before Action: If a task touches five or more files or spans multiple steps, hand it to Planner first to make a plan. Do not try to finish it in one go.
• Confirm Before Declaring Done: Before you declare the work done, confirm that every part is handled, the code has been reviewed, and the tests pass.

Role Overview

At the implementation level, a role is a Sub-agent that takes the tasks Builder delegates. There is no fixed number of roles. When one kind of task comes up often and has its own capability or permission requirements, give it its own role:

Coder (code execution). Pick a model that writes code well, at a cost you can accept. It carries out tasks that have already been analyzed. It cannot call Task (no recursive delegation) and cannot use Skill. Hard constraints: it cannot “pass tests” by deleting existing tests; it cannot leave TODO or empty function bodies as the final deliverable; and it must run the tests and report concrete results.

Explorer (internal analysis). Read-only search across the codebase. Toolset: Glob / Grep / Read. The output must include a Not found section that explicitly lists anything searched for but not found.

Researcher (external research). Read-only research on the internet. Toolset: web search / URL reading / GitHub browsing. Every URL and citation must appear in the final message. The language you search in affects result quality. Prefer English, because English technical material is usually more comprehensive and reliable. Cross-check multiple sources to avoid hallucinations and misinformation.

Reviewer (review and quality check). Run it on a code-specific model with thinking enabled. Review priority: Completeness > Correctness > Quality. The output must be exactly one of PASS / WARN / FAIL. It can also review a Plan.

Shared design for read-only roles. Explorer, Researcher, and Reviewer have neither edit nor bash permission. The point is to isolate side effects: a read-only operation must never change a file by accident.

General (general role). It can run more steps on its own than any other role, has the full toolset, and can dispatch Sub-agents. Use it for tasks that can be split off but are hard to classify, and for complex work that crosses domains.

Compaction (context compression). Run it on a long-context model with thinking enabled, so it can decide which messages to keep.

Step 2: Manage Permissions, Models, and Context

Permissions: Least Privilege

Each role keeps only the minimum permission set it needs to do its job:

Many AI Agents tend to do as much as they can. Give an Agent edit permission and it may edit files in passing while it researches. Give it task permission and it may keep delegating even simple questions. So limit permissions explicitly, and let each role do only what it should.

A typical example: give Coder task permission and hand it a hard problem. Rather than work on it, it calls Researcher to search and Explorer to inspect the code. That throws off Builder’s routing, wastes tokens, and leaves Builder in the dark. The right approach: Coder handles only what it can solve directly by coding. When coding cannot take it any further, it hands the problem back to Builder.

Model Matching

Different tasks need different levels of intelligence. The most expensive model should be reserved for the tasks that need the most judgment.

When you configure the team, also consider mixing model providers and setting up fallbacks for failures. Both help you compare results while tuning, optimize cost, and reduce single-point-of-failure risk.

Context Management and Information Isolation

Context is the scarcest resource, and a tight context window makes model performance degrade quickly. So make every bit of the context window count:

1. A Sub-agent communicates with Builder only through its final message. What happens in between stays invisible to Builder. Builder only needs to know “Task done. Result: XXX.” If something unexpected happens, the Sub-agent adds more detail about the process.
2. Compaction can combine three strategies at once: auto (automatic trigger), prune (proactive trimming), and reserved (headroom).

Step 3: Add a Plan Workflow to Handle More Complex Tasks

Why Plan Before You Execute

Send a complex task straight to Builder without a plan, and you run into four common problems:

1. The context window is not big enough. Already covered; I will not repeat it.
2. No global view. The Agent sees the first file and starts editing. Only when it reaches the third file does it realize the change conflicts with earlier work, and it has to go back and redo it.
3. Unrecoverable. Halfway through, the context fills up, or the run is interrupted (the network drops, the machine shuts down, or you run out of tokens). Progress is lost, and you have to start from scratch.
4. Unreviewable. You do not know what the Agent plans to do, so you can only wait for it to finish and look at the result. If the direction is wrong, you have already paid the price.

The Plan-Execute two-phase workflow solves these problems directly. So alongside Builder, we add a Planner whose only job is to plan.

Planner Agent

Planner takes on complex tasks and outputs a structured Plan file. Persisting the Plan as a file brings four benefits:

• You will not lose the big picture when the context window runs out.
• You can resume from the file after an interruption.
• Both machines and people can review it.
• You can edit it before execution starts (human-in-the-loop).

Planner can only read and write inside a single fixed directory (for example, ./plans/, with plan files such as ./plans/<name>.md). That physically isolates planning from execution.

Designing the Plan File Structure

A Plan file is a structured execution checklist with three core design points:

Thinking in batches. Tasks in the same batch are independent and can run in parallel. Later batches depend on earlier ones and must run in order. Parallelism can yield a substantial speedup, but only if you get the dependencies right. That judgment belongs to Planner and should be made at the planning stage.

The five elements of a Task:

1. Specified role: which Sub-agent carries it out.
2. Description: a concrete statement of the task, including the specific files and expected behavior.
3. Files involved: the list of files to create, modify, or read.
4. Verification condition: an explicit way to check.
5. Status marker: pending / in-progress / completed / blocked.

Mandatory final verification Batch. The last Batch of every Plan must include integration tests and a final review. One task passing does not mean the whole thing is correct. Task A changes an interface, and Task B still calls the old one. Each passes its own tests, but put the two together and it breaks.

Executing the Plan

Running the plan is essentially managing a state machine, driving tasks in the Plan file from pending to completed. You can implement it as a simple Skill.

The core execution flow:

1. Load the Plan file and scan the status of all tasks.
2. Find the first incomplete Batch and start on it.
3. For each task: first mark it in-progress and write the status to the file → delegate it to a Sub-agent → update the status when the result comes back → write the status to the file immediately.
4. Batch Gate: do not move to the next Batch until the current one is fully done.
5. Run the verification Batch last.

Checkpoint recovery: if you find a task marked in-progress in the Plan file, the previous run was interrupted. Here is how to recover:

1. Find all interrupted tasks.
2. Have Explorer assess the damage: Are the files complete? Are there TODO placeholders? Does the project compile?
3. Act on the assessment: completed → Reviewer verifies; partly done → Coder picks up the rest; damaged → Coder repairs.

The core principle: never assume interrupted work is done.

Additional Execution Rules

• Scope Per Delegation: A single delegation to Coder covers at most five files. Beyond that, split the work.
• Done Means Verified: Done means the verification condition is met, not that “the code was written” or “every task was delegated.”
• Persist Progress Eagerly: Write every status change to the file immediately.
• Specification Drift Check: After all Batches have run, reread the Goal and Verification Criteria word by word, compare them against what was actually built, and check whether features were quietly added, requirements were dropped, or behavior drifted from what was originally asked.

Going Further: The Ralph Loop

If the project is bigger, the goal is clear, and you need the AI to work independently for a long time, you can add the Ralph Loop on top of this setup.

In March 2026, Anthropic accidentally leaked Claude Code’s full 512,000-line TypeScript source code. A Korean developer named Sigrid Jin used the Ralph Loop to rewrite the whole codebase from TypeScript to Python in two hours, without writing a single line of code by hand. Agents did all of it, iterating on their own until the whole thing ran end to end.

The core idea: break the requirements into a set of independent items, handle only one per iteration, and move to the next only when verification passes. Each iteration starts with a fresh Agent context. Memory travels between iterations in files (git history, the progress log, requirement status), not in accumulated context, so context does not degrade over a long run. The loop works like this:

1. List every item and mark it passed or failed.
2. Start a fresh Agent context and pick the highest-priority item that has not passed.
3. Implement it, run the verification, and mark it complete if it passes.
4. Append this round’s lessons to the progress log, so the next iteration can use them.
5. Repeat until every item passes, or until you hit the iteration limit.

The Ralph Loop can be implemented as a Skill. Once invoked, Builder drives the existing Agent Team through the loop.

Conclusion

Building an Agent Team is not fundamentally about writing prompts. It is architecture design, no different from designing microservices or deciding how a team splits its work. The interesting part is that once you actually start splitting roles, drawing permission boundaries, and designing state transitions, you will find the same experience also helps you understand a lot about how human teams collaborate: why responsibility boundaries have to be clear, why process state must be persisted, and why review and testing cannot be skipped. An Agent is a mirror. What it reflects is your understanding of how work should be organized.