Previously, I wrote an article titled "Thinking About Claude Code's Agent Teams from an Organizational Theory Perspective." It explored how to design Agent Teams, drawing inspiration from Buurtzorg's self-managed organizational model.

To be honest, at the time I wrote that article, I was working from hypotheses—"this is how it should work in theory." I hadn't actually used Agent Teams extensively in my own projects.

Recently, I had the opportunity to bulk review and update 22 CI/CD articles on our company blog using Agent Teams. I went through the entire process from preparation to practice, and there were both successes and honest stumbling blocks. I'd like to document the entire journey as it happened.

Key Takeaway

Let me start with the main point of this article:

With Agent Teams, 80% of success is determined by preparation before you even begin using them.

Conversely, if you prepare well, multiple agents working in parallel can deliver solid results. However, things don't always go as planned, so you need to design for those scenarios as well.

This article covers both the "preparation" and "practice" phases in detail, based on actual session logs.

Why I Decided to Use Agent Teams for Article Maintenance

The "Neglect Problem" in Technical Blogs

Our company blog has over 20 Jenkins-related articles, covering everything from CI/CD basics to advanced topics—a fairly substantial collection.

However, technical articles have a shelf life. For example, Jenkins Blue Ocean was officially deprecated in 2022, yet our blog still recommended "using Blue Ocean." When outdated information like this lingers, it harms readers.

If we only had 5 articles, I could review them manually one by one. But 22 articles is a different story. Opening every article, cross-referencing with current official documentation, identifying problems, making fixes, and verifying the build passes—doing this alone could easily take an entire day.

That's when I remembered my previous article.

Testing My Own Theory

In the Agent Teams article, I wrote about:

I had the theory. But I hadn't put it into practice. This felt a bit dishonest. To take responsibility for my own words, I needed to test them in my own repository first.

I took this as an opportunity to use Agent Teams for the bulk maintenance of our CI/CD articles.

Preparation Phase—Creating the "Soil" for Agent Teams to Operate

Overview of Preparation Work

Before using Agent Teams, I needed to prepare the repository environment. I did four main things:

graph TD
    A[Add Agent Teams<br>guidelines to CLAUDE.md] --> E[Ready for<br>Agent Teams<br>operation]
    B[Create AGENT_TEAMS.md<br>practical guide] --> E
    C[Create integrated<br>validation scripts] --> E
    D[Add validate command<br>to package.json] --> E

Let me explain each step.

1. Add Agent Teams Operational Guidelines to CLAUDE.md

In my previous article, I wrote that "CLAUDE.md serves as MVV (Mission, Vision, Values)." This was putting that into practice.

CLAUDE.md already contained project overview, command references, and content management rules. I added a dedicated Agent Teams section.

The structure of what I added looks like this:

Explicitly State MVV (Mission, Vision, Values)

I articulated the mission: "Maintain and advance a high-quality bilingual technical blog." Agent Teams' agents would make autonomous decisions aligned with this mission. Without needing humans to give detailed instructions every time, sharing this decision-making framework prevents major deviations.

Keep Behavioral Guidelines at the "Principle" Level

This turned out to be surprisingly crucial. Writing rules too granularly stifles agent flexibility. Drawing from Buurtzorg's philosophy of "minimal rules, maximal autonomy," I limited guidelines to just four principles:

  1. Don't break existing functionality (verify with test suite)
  2. Maintain content integrity (verify with validation tools)
  3. Approach large changes incrementally
  4. Consult humans (coach role) when in doubt

Clearly Position the Test Suite

This may have been the most important part of preparation. I positioned the test suite as a "substitute for supervisors."

npm run lint                                    # Code quality verification
npx tsx scripts/check-affiliate-integrity.ts    # Affiliate link integrity
npm run build                                   # Build success verification

After completing work, agents run these three commands for self-verification. Instead of supervisors checking everything, tool results become the "mirror." This is the core idea.

Explicitly State Task Suitability

I also documented that Agent Teams are better suited for Read-Heavy tasks (research/review) versus Write-Heavy tasks (simultaneous edits to the same file). This information significantly affects Claude's judgment accuracy when distributing tasks.

2. Create AGENT_TEAMS.md

CLAUDE.md covers "principles and policies," while AGENT_TEAMS.md is the "concrete procedure manual."

It contains environment variable setup, concrete task examples (bilingual consistency checks, SEO audits, etc.), validation workflows, and troubleshooting steps.

It serves as a "handbook" agents can reference when they're uncertain.

3. Create Integrated Validation Script

I created a script that runs all individual check commands in one go, with both Bash and PowerShell versions.

This is because I develop on Windows. I wanted agents to be able to execute validations in either environment.

4. Add Validate Command to package.json

{
  "validate": "npm run lint && npx tsx scripts/check-affiliate-integrity.ts && npm run build:dev",
  "validate:affiliates": "npx tsx scripts/check-affiliate-integrity.ts"
}

Running npm run validate executes all validations at once. I can simply tell agents "run npm run validate when you're done," which simplifies instructions.

After Completing Preparation

The commit diff was 6 files changed, 562 insertions(+). Quite substantial.

Looking back, I can confidently say the time spent on this preparation was not wasted. In the practice phase described later, the agents operated quite autonomously because this foundation was in place.

It's like riding a bicycle—the initial "push-off" is the hardest, but once you've set it up, it gets easier next time.

Practice Phase—Bulk Reviewing and Fixing 22 Articles

Starting Agent Teams and Role Distribution

With preparation complete, it was time to actually run Agent Teams.

I first told Claude: "The CI/CD category articles may contain outdated information. I want to update them to the latest information." Claude then proposed the following team structure:

Review Phase (4 agents)

Agent Name Responsibility
metadata-analyzer Extract metadata from all 22 articles
reviewer-1 Review article group 1 (articles 1-7)
reviewer-2 Review article group 2 (articles 8-14)
reviewer-3 Review article group 3 (articles 15-22)

Dividing 22 articles into 3 groups with dedicated reviewers for each. Running in parallel is much faster than one person reviewing all 22.

What's noteworthy here is that Claude itself proposed this role distribution. I think this reflects the effectiveness of writing "Read-Heavy tasks are suitable for Agent Teams" in CLAUDE.md. Without humans needing to specify "Agent A does 1-7, B does 8-14..." in detail, Claude can figure out the distribution itself when the policy is shared.

Review Results—Issues Found

Reports from all three reviewers came in. Here's the summary:

High Priority (5 articles)

Medium Priority (3 articles)

Good Condition (14 articles)

The remaining 14 articles had no current issues. Several recently updated articles were in good shape.

Honestly, I hadn't realized Blue Ocean deprecation affected 3 articles. If it was just one article, I might have noticed myself. But having reviewers check all articles in parallel allowed us to accurately identify the full impact scope.

Fix Phase—The Real Work Begins

Based on review results, we entered the fix phase. This time, I organized 3 fix teams:

graph LR
    subgraph Fix Teams
        F1[blue-ocean-fixer<br>Blue Ocean<br>deprecation fix<br>3 articles]
        F2[api-fixer<br>External API<br>fix<br>2 articles]
        F3[medium-priority-fixer<br>Medium priority<br>fixes<br>3 articles]
    end
    F1 --> V[Validation]
    F2 --> V
    F3 --> V

blue-ocean-fixer work (success)

Fixed Blue Ocean-related sections in 3 articles. Added deprecation warnings and alternative suggestions to the API article. Removed Blue Ocean section from build artifacts article and emphasized Classic UI. Rewrote log verification article to remove Blue Ocean descriptions and recommend Console Output and Classic UI Pipeline Steps instead.

api-fixer work (success)

Replaced defunct time API with worldtimeapi.org, and replaced inaccessible image API with placekitten.com. This agent also ran build verification itself.

medium-priority-fixer work (failed)

Here's the trap.

medium-priority-fixer never returned a response. I waited a while, then asked "Are you stuck?" but got no reaction.

What Didn't Work—The Agent "Non-Responsiveness" Problem

What Happened

When I assigned the medium-priority-fixer agent to fix 3 medium-priority articles, it didn't respond.

"Not responding" means no error messages returned—just silence. No timeout messages either. From the outside, it was impossible to know what was happening.

First Response (failed)

I launched a new agent (medium-priority-fixer-2) to take over the task. However, this one also went silent.

At this second failure, I decided "repeating the same approach won't work."

Pivot—Split the Task

Instead of assigning 3 articles to one agent, I switched to assigning one article per agent:

Agent Article Fix Content
fixer-disable-job Job disable article Add Python library compatibility info
fixer-stop-build Build stop article Update old documentation links
fixer-what-is-jenkins Jenkins intro article Add Blue Ocean maintenance mode note

All three completed without issues.

Lessons from This Failure

I still don't know exactly why medium-priority-fixer became non-responsive. Agent Teams is still an experimental feature, so this kind of instability remains.

However, the important point is: design with the assumption that agents may fail.

In this case, I could split the task into three because the original fix content was independent per article. If it had been one large fix task (like bulk converting frontmatter across all articles), splitting wouldn't have been so easy.

This relates to the principle I wrote in my previous article: "prioritize Read-Heavy tasks." Even for fix work, if it's independent per article (loosely coupled), you can split and re-execute on failure. Tightly coupled write tasks make recovery from failure much harder.

Final Validation and Results

Validation Results

After completing fixes for all 8 articles, I ran the validation commands set up during preparation:

npm run lint          # → Only existing lint errors (unrelated to current fixes)
npm run validate:affiliates  # → Only existing issues
npm run build:dev     # → Build successful

No new errors from these fixes. Build passed cleanly.

Having set up npm run validate during preparation made this verification smooth. Without it, I would've needed to remember which commands to run.

Results Summary

Item Count
Articles reviewed 22
Articles fixed 8
Agents deployed 4 reviewers + 5 fixers (including 2 failed)

Fix breakdown:

Reflection—Between Theory and Practice

Were My Previous Hypotheses Correct?

Let me compare the ideas I proposed in my previous article with the actual results:

"CLAUDE.md serves as MVV" → Correct

Writing policies in CLAUDE.md clearly improved agents' autonomous decision-making accuracy. Claude proposing task distribution itself is evidence that MVV is functioning.

"Test suite as concrete behavioral guidelines" → Correct

Having npm run validate enabled agents to self-verify after work. This mechanism—where tools guarantee quality rather than supervisors checking—works very well with Agent Teams.

"Read-Heavy tasks are their strength" → Correct

Parallel review of 22 articles went smoothly. On the other hand, agent non-responsiveness occurred during the fix (Write) phase. Task suitability by nature definitely exists.

"Minimal rules, maximal autonomy" → Mostly correct, but needs supplementation

Showing only principles without detailed procedures allowed agents to operate flexibly. However, "recovery procedures when failure occurs" might have benefited from more concrete documentation.

Areas for Improvement

Agent Health Checks

Detection of the non-responsive agent was delayed. A mechanism like "automatically launch a replacement agent if no response within a certain time" would have made things smoother. This is partly hoping for improvements to Agent Teams itself, and partly something that could be partially addressed by documenting retry policies in CLAUDE.md.

Fix Task Granularity Design

If I had used "1 agent 1 article" from the start, the medium-priority-fixer problem might not have occurred. I learned that task granularity should consider "a size that's easy to re-execute even after failure."

Conclusion

Let me repeat the main point of this article:

With Agent Teams, 80% of success is determined by preparation before you even begin using them.

Writing policies in CLAUDE.md. Setting up test suites. Consolidating validation commands into one. These unglamorous preparations support agent autonomy.

At the same time, agents are not omnipotent. They can become non-responsive or behave unexpectedly. That's why design philosophies like "keep tasks loosely coupled" and "size them to be re-executable on failure" are important.

Agent Teams is still an experimental feature, but I genuinely felt it's a tool that can definitively improve productivity when used right. The organizational theory I wrote about in my previous article wasn't just armchair philosophy. It feels like another puzzle piece has fallen into place.

Next, I'd like to try Agent Teams on a larger-scale task—perhaps a blog-wide accessibility audit.

Further Reading

For those who want to dive deeper into AI agents, here are some recommended books. These cover everything from development and operations to practical applications, helping you build on the themes discussed in this article.

[📦 商品リンク: moshimo-card-tpujl]

[📦 商品リンク: moshimo-card-19J42]

[📦 商品リンク: moshimo-card-tP9XC]