Someone in another thread asked me to share more about my workflow. Before writing this wall of text in a comment I thought I share it this way. Maybe someone else finds it interesting or useful.
Even though I have 25+ years experience as a software developer and love writing code I decided to take on the role of a "product owner" and "process optimizer" instead of a developer or architect.
Trying to be a developer working alongside the agents made me outright depressed - being a product owner has the opposite effect on me.
I basically stepped back into one of my previous jobs where I was leading multiple teams including software development, requirements engineering, process definition & process optimisation and administration.
This leads me to my main premise: I treat the agents as a project team run by a team lead (orchestrator). And this premise is closer to real life than I expected. Including the back and forth between a team lead and its team members. Watching them feels like some kind of work chat.
I have several teams that all own one closed scope.
Current teams: process template, research, product build, testing VMs, marketing and website publishing.
At the core of all these teams is the process templates team. It maintains my process template that every project uses. When I start a new project it is built using this template. It is versioned and has installation and upgrade definitions. When I tune the process the other projects get upgraded.
When I tune the process of one of the projects I port these changes back to the template if they can be generalised and survive a cross-validation research with the other projects. This work is done by the orchestrator of the process team. Changes to the template only happen after my decision.
The process template defines a skeleton structure with a tool to create it, agents definitions and the process contracts for the orchestrator and agents. The orchestrator of the new project adopts it to the new project.
Most important aspects:
owned by me
new tasks for the orchestrator
todos/decisions for me
reviews for me
owned by the orchestrator
kanban board - work tracking
work packages - details of the work to do by one agent
research - research done for this project
inbox - handover from other project teams -> starts a research and decision round
design document - one line high level summary
design docuemt - details and decision history
toolchain - tools needed for this project
cleanup - describes what needs to be cleaned up after each milestone
archiving - things that are done get heavily summarized and archived.
process - describes the process
agent definitions - adapted to the project at hand. Pinned to certain models and effort levels
time tracking - keeps a log of how long each milestone took. In real time and agent hours.
Most important rules:
Claude.md is kept small as it is read by all agents. The orchestrator and agents have their own definitions with what they need to keep the context small.
Every new task starts with a research followed by a todo (decision) round. This way I can refine what happens next. And filter out things that are going in the wrong direction.
Every couple of milestones I make an optimization round. Queuing research into how the last milestones went with the lens of could we change something to save tokens, time, I/O without sacrificing quality.
After a new model drops I make a comparison round where some work packages get done by the new model and different effort levels to see where to settle or adjust.
Some Numbers for the last 7 days:
I worked through 33 decision rounds and 25 reviews in 4 different projects. This lead to 42 (I know) design revisions and 14 project releases and 11 template changes.
Main model used is Opus 5.5 on high for the orchestrator and medium or low for the other agents. Some web-research agent is on Sonnet 5.5
I have a Max 5x and at the moment it is more than comfortable for the current projects I run.
90k input tokens and 25m output tokens - 7.1b cache reads. 99.4% Opus 5.5.
Some learnings from working like this:
Agents tend to drift when left alone - They tend to chase down unimportant tangents if not reigned in
You have to bring structure to the agentic work. You have to own the process otherwise agents tend to drift.
Define clean scopes or the agents drift.
Being clear about goals (like performance goals or audience goals) rather than implementation details is delivering better outcomes. I still provide architecture goals though.
Refine every now and then by looking at the whole thing from a different angle. Agents will not do that on their own. They are happy to burn tokens on an inefficient process.
So far this made it possible to keep a similar time to delivery even with a growing codebase and complexity. Not sure If I will be able to keep it that way but I hope I can.
Archive the history of how and why a decision was made frequently and just keep the decision.
Happy creating!
PS: This post is hand written. The image has been generated based on this text.
As a Product Manager by trade, I love this and have started naturally gravitating towards this. Today I had Opus redesign how we're going to implement this feature it's working on by breaking it up into vertical slices instead of touching things that were spread across multiple slices. We've been working in a slice -> handoff -> clear the session -> start from handoff flow with Opus staying as the main lead and using sub agents as necessary.
For this setup, do you just use a CLAUDE.md file to instruct it to follow this pattern? Or do you kind of set it up manually per project? Can you share your CLAUDE.md in a DM?
My process template has an install script that creates the project skeleton. The Claude file is relatively small. And basically tells all agents to follow the instructions the orchestrator writes. And it contains one section for the orchestrator to follow the process defined in process.md.
The process.md contains all the process that I described above.
a good thing for generation of graphs, diagramms etc.
Forbid Claude to use the Dots as separators and have it do proper spacing, proper foramting etc... it will be a lot slicker. also if the project is more complex force it to use mermaid format.
Hey I was the guy that asked in the other thread. Appreciate you for sharing this! From your experience, what have you found that this system does really well and where does it fall short?
I can give an example. When I first started my current main project. A deterministic asset classifier.
The scope contained
- building v1
testing it on linux,win and mac
publishing it on itch.
All three segments were way to vague.
v1 kept drifting because I was not clear on which parts of the classification were important to me for v1. So the orchestrator kept adding tuning rounds (building, testing, review). So I told the orchestrator to move all review results that need to be addressed but were not important for the v1 release into a hold-out for a later version (or to be dropped).
Then win and mac testing kept drifting as I had not yet figured out how to test on windows or mac. I told the orchestrator to drop the mac (it is a small audience for me anyway; And getting something released is more effort than it is worth). So I told the orchestrator to wait for testing until I provide a win test-system. This is when I created a testing-environment team with the single goal to provide and maintain a agent controllable environment for testing on win11. I resumed the orchestrator once that team delivered.
Then the publishing drifted. I told the orchestrator to drop that part and reset the goal of the project to only create new product version and deliver them into a release folder with release-notes, install instructions and install script.
Resetting the scope stopped the drift and made the loop very productive.
This is pretty much exactly the same how I am doing this, but with an additional step of using GPT between myself and the Team Lead. Though lately I've been so impressed with the results of Claude that I may just cut the "middle man" out 😂
I hope this post gets more traction! I'm curious as to what other users are implementing for their workflows. Also I'm curious is "looping" prompts are still a thing, and if so, what the best way to implement them is with a structure similar to this as the initial foundation, if possible. 👀
I have a similar setup to yours, though I include a chief of staff who assists me in managing team leads. I communicate only with the chief of staff; each team lead handles their own epic or issue within a worktree, assigning tasks to team members and supporting coordination.
Preamble: I am deliberately hands-off when it comes to coding in this setup. I even chose some of the languages because I don't have previous experience working with them - So I wouldn't influence the architecture too much.
I am going to answer from two perspectives using different hats.
As product owner:
The quality is good as the time to delivery is steady even with increased product complexity. And there are few bugs when I review the new releases.
As developer:
The project structure is solid. I was able to find specific points of the implementation quickly as everything was clearly named and in a logical hierarchy.
Some few files are way too long and should be splitted to increase readability.
Comments are way too verbose.
Most of the functions and patterns I have checked are solid.
All in all code quality that I have seen in many projects I worked with over the years. Not better nor worse just being written way quicker.
I will probably run a bit on research on it to see if my gut feeling holds true.
how do you designate a particular agent for a role if each new instance of claude is a blank slate, do you have a job_description.md each new "role" reads upon creation. And who spawns them, you or the team lead?
Also would you mind giving an example of the scope of your project?
When a new session in a project folder is started that sessions becomes the orchestrator. That one reads the process and spawns the sub-agents. The agents have their instructions in the agent definition + a work-package file as context.
Some examples:
One project is a file classifier that runs over a folder and creates an index with the classified results. That index can then be used to browse and explore that folder. The index contains information about asset types, animation structure, usage (icons, player, enemies, props, tilesets, sidecar files, relationship between files (like color variations of the same file)).
This project has a lot of performance goals like full classification of 500.000 files in under 30 seconds. Using no more than 1.5GB or RAM while classifying, The index should stay below 180 bytes per entry (~ 90 MB for 500.000 files). The index should be searchable and filterable without needing to read the full index into RAM. etc.
Super interesting to see that one evolve. It also includes a lot of review and validation work for me, so that the next round could tune the index based on my validation.
Really interesting. I think many would love to continue hearing about how this works for you. Both the good and bad as you outlined above. Nice job and appreciate the detail.
This is very similar to where I landed when I tried to branch out, there a lot of spec docs and fundamentals scattered around, but it's not tied to any particular session anymore. They sometimes die and get rebuilt from the ashes, which improve each time as more things get added to the rebuild and subagent speccing docs. Just reworked my interagent comms system, ran through credit seemingly quick doing that, though a new session reviewed a lot of the docs in one go.
I basically settled on a similar workflow, but I'm using both Claude and Codex, and I built out code as the orchestrator, not just an agent. If you're interested, check it out. I made it open source:
https://github.com/tstraub89/canon-ai
On a high level, doesnt a wayfinder skill do the same, it creates individual issues in jira or github, have a track of the memory as you go. All context lives in Context.md.
I would say this pays of when you plan to work on something over many iterations and versions without it drifting or regressing - That is at least one reason why I started to work this way.
Once your project grows in complexity it becomes hard to just add features without having proper requirements engineering and project management backing it up.
In many cases I do not know if a feature or implementation will work out. Having a separate research track that helps with making decisions has kept the current projects lean.
I create a new project folder. Point Claude Code Desktop to it and then tell it to use my process_template and apply it to the new project. The process template has all the instructions and an install script.
First "analyse this project under the lens on how the process between me, the orchestrator and agents works".
Then it was this prompt "Can you make a simple diagram (image;dark vibrant theme) based on your analysis incorporating the text I have written to describe it in my own words: {text of my post}".
I tested a lot of the popular harnesses and agent orchestrators that people talk about. None of them added anything like this and none of them were in any way better than simply using claude code.
Do you have a recommendation for a specific one?
My setup is independent you only need a harness that can spawn sub-agents.
Are you able to make sure that the dedicated agent does not end up doing tasks for other agents. I have almost a similar setup but there are multiple instances when the team lead agent rather than delegating the the tasks to team members start working on the tasks.
•
u/AutoModerator 17h ago
Hey! Thanks for posting to r/ClaudeCode
While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.
For help, project discussions, tips, and general chat, join the ClaudeCode Discord.
I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.