In my previous article, "Bulk-Reviewing 22 Technical Blog Articles with Claude Code's Agent Teams," I concluded by writing that I wanted to try the feature on a larger-scale task next. But before that, there was something else I needed to do.
Setting up an Agent Teams environment in another repository. And then, encountering the same problem again.
To be honest, I didn't follow the guidelines I had written in the previous article about "what you should do." This is that story.
Key Takeaway
Let me summarize the main point of this article upfront.
The most important role required of an Agent Teams leader is to "observe" the agents.
In my previous article, I wrote that "preparation determines 80%." I still believe that's correct. However, I had overlooked something crucial in the "operation phase" after preparation is complete. Rather than launching agents and leaving them alone, it's extremely important to periodically check on them and notice when members are struggling. This turned out to be more important than I imagined.
Expanding to Another Repository — Same Setup Again
Why Introduce It to Another Repository?
The previous time I used Agent Teams was on our company blog's repository. This time, I decided to set up the same environment in a different project.
The reason was simple: I wanted to confirm whether the best practices I wrote about in the previous article were truly reproducible. Would the same procedures work when applied to a different project?
What I Did
I performed the same four preparation steps as before.
graph TD
A[Add Agent Teams<br>Guidelines to CLAUDE.md] --> E[Agent Teams<br>Ready to Operate]
B[Create<br>AGENT_TEAMS.md<br>Practical Guide] --> E
C[Create<br>Integrated Validation<br>Script] --> E
D[Add validate<br>Command to<br>package.json] --> E
Specifically, I added MVV (Mission, Vision, Values) and action guidelines to CLAUDE.md, created a new AGENT_TEAMS.md file, prepared both Bash and PowerShell versions of the integrated validation script, and added a npm run validate command.
I simply followed what I had done previously. This part was straightforward—having done it once, I knew what to write and what was needed. Like riding a bicycle, the second time is much easier to get started.
Practice — Fixing Tests with Agent Teams
The Situation
In this repository, tests had been failing due to several recent PRs. The source code was correct, but the tests needed fixing.
Running the tests showed 8 failures across 5 test files:
- Timestamp timezone conversion issue (1)
- Windows path separator issue (3)
- Prompt file language instruction vs expected value mismatch (3)
- Test error due to build failure (1)
I decided to fix these in parallel using Agent Teams.
Team Composition
I launched four agents:
| Agent Name | Responsibility |
|---|---|
| timestamp-fixer | Fix timestamp test |
| path-fixer | Fix Windows path separator issues (3) |
| prompt-fixer | Fix prompt language test mismatches (3) |
| build-fixer | Investigate and fix build failure |
Based on previous experience, I set the task granularity to "one agent, one theme." In the previous attempt, assigning 3 articles to one agent led to unresponsiveness, so I grouped related fixes while keeping themes separate per agent.
Three Succeeded, One Went Silent
timestamp-fixer, build-fixer, and prompt-fixer all completed successfully.
The problem was path-fixer.
While the other three agents reported completion one after another, path-fixer remained silent. Checking the task status showed it was still pending. This was exactly the same scenario as in the previous article.
The Same Mistake Happened Again
Team Leader (Claude) Response
When I noticed that path-fixer might not be working, I told Claude (the Team Leader). Claude sent one message to path-fixer, saw no response, and concluded, "This is the same unresponsiveness issue as before."
Then, Claude immediately launched a new agent, path-fixer-2, to take over the task. path-fixer-2 completed the work without problems, and all tests passed.
If it ended here, this would be a story about "applying patterns learned from the previous experience."
But Then
After all tasks were completed, when trying to shut down the unresponsive path-fixer, something happened.
Claude manually removed it from the team configuration and sent a shutdown request. However, the path-fixer process was still visible on my screen. I tried pressing the Escape key, and then—
path-fixer started moving.
It said, "Reporting to team lead and waiting for instructions from team lead."
In other words, path-fixer wasn't "unresponsive." It was simply waiting in some state. It was in a state where it would respond if contacted, but the Team Leader had launched a new agent without checking.
Team Leader Didn't Follow Its Own Guidelines
At that moment, I realized something.
CLAUDE.md included a step to "contact the agent." But what the Team Leader actually did was immediately conclude "unresponsive" the moment it saw a task stuck in pending, and immediately launch a replacement agent.
When I asked Claude, "Shouldn't you have contacted it first?" the response was, "You're right." It hadn't practiced its own written guidelines.
Honestly, at this point, I felt that just writing guidelines in CLAUDE.md isn't sufficient. Even if it's written down, it's meaningless if it's not referenced at the moment of actual decision-making. I updated CLAUDE.md this time to emphasize "contact first" more strongly, but I still don't know if this will actually change the Team Leader's behavior next time.
The True Role of Team Leader
"Observation" Rather Than "Management"
Through this experience, I realized another important thing.
As a Team Leader role, it's necessary to occasionally check on each agent's situation. Some members may find themselves unable to report on their own.
I realized this happens with agents too, just like with human teams. That hit home.
When you think about it, it's obvious. Even in human teams, "no report doesn't mean no problem." Some members are in situations where they want to report but can't. A manager's role isn't to issue instructions and wait for results, but to observe members, and reach out if they seem to be struggling.
This is exactly the Buurtzorg coach philosophy I wrote about in the previous article:
- Don't solve problems for them; facilitate discussion
- Watch over team members and support when stuck
- Leave final decisions to the field (agents)
What I had written as guidelines in CLAUDE.md wasn't functioning in actual operation. The gap between "written down" and "actually practiced" is larger than I thought.
The Obvious: "Contact First"
Based on this experience, I updated the troubleshooting section in CLAUDE.md.
Here's the key change:
Before (Bad Example):
- Check TaskList and see it's still pending
- Conclude "unresponsive"
- Immediately launch a new agent
After (Correct Procedure):
- Detect anomaly in TaskList
- Contact agent with SendMessage — "How's progress? Are you stuck on anything?"
- If response received, continue. If not, check again after a few minutes
- Only then, if still no response, consider launching a new agent
Launching a new agent is a last resort. Contact first.
It sounds obvious when written out, but surprisingly, this is the crux. However, this is just a revision derived from this experience—whether the Team Leader will actually follow these steps next time I use Agent Teams hasn't been verified yet.
"Team Leader (Coach) Role" Added to CLAUDE.md
Based on these lessons, I added a new section to CLAUDE.md.
graph TB
subgraph "Team Leader (Coach) Role"
A[Regular Status Checks] --> B[Contact Agents]
B --> C{Response?}
C -->|Yes| D[Continue Observing]
C -->|No| E[Contact Again]
E --> F{Still No Response?}
F -->|Yes| G[Launch Replacement Agent<br>Last Resort]
F -->|No| D
end
Specific Content
Three Important Principles:
- Don't dictate how to work: Respect each agent's autonomy
- Set up environment and systems: Focus on task design, tool provision, and removing obstacles
- Observe and intervene as needed: Not neglect, but support at appropriate timing
Concrete Actions:
- Check task progress with TaskList every 15-30 minutes
- If tasks remain pending or in_progress for long periods, check status with SendMessage
- Notice agents that have become unable to report on their own
- After all tasks complete, run integrated validation with
npm run validate
Governance Layers Revised
In the previous article, I designed quality assurance as 3 layers, but based on this experience, I revised it to 4 layers:
| Layer | Role | Before | After |
|---|---|---|---|
| First Layer | Test Suite (Automated Verification) | Same | Same |
| Second Layer | Peer Review (Between Agents) | Same | Same |
| Third Layer | Team Leader Spot Checks | None | Newly Added |
| Fourth Layer | Human Final Responsibility | Third Layer | Moved to Fourth Layer |
I separated "human spot checks" from "Team Leader spot checks." The Team Leader (Claude itself) periodically checks on agents, while humans hold ultimate responsibility for quality on top of that.
Reflection — What Second Time Revealed
Reproducibility Confirmed
- The preparation pattern of CLAUDE.md + AGENT_TEAMS.md + validate command worked as-is in the different repository
- Autonomous agent work operates stably when preparation is complete
- Recovery from unresponsiveness (task splitting, replacement agents) also functions
New Lessons
- Agents may be in "waiting state" rather than "unresponsive". Don't give up immediately
- The most important job of Team Leader is "observation". Not issuing instructions and waiting, but watching
- Guidelines written in CLAUDE.md may not be referenced in actual operation. Writing alone isn't enough—you need to revise after failures and clarify points that need stronger emphasis
However, whether next time will improve from reflecting these lessons in CLAUDE.md requires verification in another opportunity. How much CLAUDE.md descriptions influence agent decisions—this itself is an experimental theme.
Evolution from Previous Article (Hypothesis)
In the previous article, I wrote that "preparation determines 80%." From this experience, I'm feeling that a large part of the remaining 20% might be "observation during operation."
Preparation (CLAUDE.md, test suite, validation commands) creates the foundation, and observation during operation (regular checks, reaching out, early detection) supports outcomes. Only when both wheels align can Agent Teams stably deliver value. However, this is still at the hypothesis stage. Whether Team Leader behavior will improve with CLAUDE.md additions, whether the observation system will actually function—these need verification in the next practice.
Summary
Let me repeat what I wanted to convey most in this article:
The most important role required of an Agent Teams leader is to "observe" the agents.
If you think an agent is unresponsive, contact it first. Launching a new agent is the last resort. Noticing struggling members is the real job of a team leader.
This is about AI agent operation, but I feel it connects to human team management as well. "No report doesn't mean no problem." Observe, reach out, and support as needed. It's exactly the Buurtzorg coach role.
I'm honestly frustrated that the guidelines written in CLAUDE.md weren't followed in actual operation, but that's exactly why I added a "Team Leader (Coach) Role" section and more strongly emphasized the importance of "contact first." However, I still don't know if this update will actually change Team Leader behavior. Guidelines aren't finished once written—they need to be verified in actual operation, revised, and continuously improved. To be honest, even though this may result in disorganized writing, I'll probably overlook something again. That's just part of the process of improving bit by bit through practice.
In my previous article, I wrote about "another puzzle piece fitting in," but the piece I found this time was "observation." Preparation, practice, and observation. Whether this piece properly fits will be confirmed in the next practice.
References
For those who want to learn more about AI agents, I recommend the following books. From development to operations and practical applications, these will help you understand the themes covered in this article more deeply.
[📦 商品リンク: moshimo-card-tpujl]
[📦 商品リンク: moshimo-card-19J42]
[📦 商品リンク: moshimo-card-tP9XC]
Additionally, for understanding the "coach role" theme of this article, "Reinventing Organizations" is particularly helpful.
[📦 商品リンク: moshimo-book-teal-organization]
For a more accessible introduction, the illustrated version is also recommended.
[📦 商品リンク: moshimo-book-teal-organization-illustrated]