28 Feb 2026 4 min read

Setting up a project workflow with Claude Code

It’s been quite busy with sessions in the last two weeks. I gave a talk on how we use agents at Info Support and spoke to two teams about ways they can improve their development workflows with agents. The most important theme here: I received a lot of questions about using agents effectively. Let’s take a look at how I do this with Claude Code! I’m quite excited about how well my current approach works, so I’m eager to demystify it because it’s not super complicated.

Hiring an agent for a role on your project

Before I show you how to set up agents, it's good to realize you're now a hiring manager for your team. Except, you don't hire people, you hire AI agents. Having this mindset helped me determine which agents to use for my project.

Hire agents based on what you're building

For a project I'm working on, I needed to set up a development workflow that works for three specific modules:

A server that hosts the backend for the application
A single-page frontend that renders the user interface for the backend
A command-line application for managing content

All three of these modules require a different specialization. Take a look at your own project. Typically, you'll have a frontend developer who's good at building single-page applications and someone else for the backend. Of course, you can work with full-stack developers, but I haven't come across many people who like both frontend and backend and who are exceptional at both.

When you start defining agents in Claude Code, keep this in mind and design agents for the various roles in your project. Based on the module structure for my project, I set up three developer agents with their own specializations.

Don't let agents review their own work

After using the developer agents for a while, I learned that agents, just like humans, shouldn't review their own work, because they were good at building stuff but not at reviewing code. I had to separate the implementation role from the review role. This greatly improved the quality of the work.

Designing agents

You can design agents in Claude Code by creating a markdown file in the .claude/agents directory with a specific structure. The file is typically named <agent-name>.md and follows this structure:

---
name: frontend-developer
description: "...."
model: opus
color: green
memory: project
---

Agent description....

An agent needs a name that helps identify them. It also needs a description of the agent's responsibilities and when Claude Code should use the agent. Finally, you can specify which model to use and the agent's color (for display in the terminal).

Then you need to write instructions for the agent. And this is where it gets a little difficult. Because what can you write here? Well, I have a cool trick here. Instead of writing agent instructions manually, let Claude Code help you!

Use the /agents command inside Claude Code, and let Claude Code generate the agent for you. All you need to do is write an instruction like this:

Help me write backend code in Kotlin for my Quarkus application. 
Focus on writing reusable components as much as possible. 
When writing tests, make sure to follow arrange, act, assert. 
Test one state or behavior per test case. 
Take a functional slicing approach to structuring code. 
Follow the guidance as described in `docs/architecture`.

Claude Code will generate a well-defined set of agent instructions for you. You may need to modify them slightly, but the instructions work very well even without tweaks.

So whenever I need a new agent, I'm using the /agents command to configure it. And when I need to modify an agent, I'll ask Claude to update the agent's instructions instead of writing them myself.

Taking an iterative approach

I found that it is quite hard to cover all your bases in the first iteration. I completely forgot about creating an implementation plan for my specifications.

Make sure to regularly check your process. If you find yourself correcting your agents frequently, it's time to give them a software development course. As mentioned before, you can easily update instructions using Claude Code.

My personal agent setup

After using agents with Claude Code for a few months now, I have found that I keep coming back to the following team setup to implement my workflow:

Architect - Responsible for creating the implementation plan for a specification.
Developer - Responsible for writing the implementation code. I typically have a few of these depending on the module structure for my project. I like to split on frontend/backend at least, and I'll add more if I'm building specialized modules.
Reviewer - Responsible for reviewing the code for any quality issues and adherence to the architecture documentation. I have one reviewer per developer agent. The reviewer typically mirrors the developer agent's instructions.

I'm still working on a CI/CD agent. I'm using a GitOps approach in my current project, and I found it necessary to build the skills to make it work for me. So I may add an agent to help me out.

In addition to these agents, I have a few skills to help me, the team lead:

Specification skill - I use this to write specifications. I'm not using an agent here because writing specs is an interactive process for me.
Record ADR skill - I use this to write architecture decisions down. Again, this is an interactive process that requires creative thinking. So I don't give this to an agent.

I find myself using skills when I need help, and agents when I want to delegate tasks to the computer to solve. And I must say, it's working out really well so far!

Give the new agent team feature a try

If you haven't, I can highly recommend trying out the new agent team feature in Claude Code once you have a working team! A good agent team gets even better with this new feature.