1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

タスク粒度を「人間がレビューできる単位」に割る — AIエージェント並列運用でコンフリクトを減らす分解法

1
Posted at

はじめに:AIを並列で走らせたら、壊れたのは「粒度」だった

当社(合同会社ジョインクラス、社員はCEO 1人)では、開発・出版・マーケなど複数部署のClaude Codeエージェントをlaunchdで動かしています。最初は「毎分起動・全部署が常時稼働」でした。仕事は進むのですが、同じファイルを複数のエージェントが同時に書き換えて衝突したり、1回の差分が大きすぎて人間(僕)が読めず、承認できないまま溜まったりしました。

過去には、AIが git push --force を実行してブランチが消えたこともあります。差分が大きくて中身を追えないと、こういう事故に気づくのも遅れます。

そこで2026年11月16日に運用を変えました。朝に「1日の計画表」を作り、各部署はその表の1行だけを受け取って動く方式です。この記事では、その仕組みの実装と、タスクを「人間がレビューできる単位」に割るときのルールを紹介します。

この記事で分かること:

  • タスクの粒度を決める3つの基準(差分の大きさではなく「触るファイル」で割る)
  • Markdownの表を作業キューにして、1行ずつ受け取る実装(Python)
  • 同じ部署を二重に起動しない排他(シェル)
  • 着手前に「ファイルが重なるタスク」を見つける検査

1. 粒度の基準:「1行 = 1人が5分で読める差分」

僕が試行錯誤して決めた基準は次の3つです。

基準 内容 理由
成果物が1つ 1タスクで作るもの・直すものは1つ。結果欄にパスを1つ書けること 結果を1行で書けないタスクは大きすぎる
触るファイル群が他と重ならない 同じ日の別タスクと編集対象が重ならないように割る コンフリクトは「同じファイルを同時に触る」ことでしか起きない
1回で終わる 執筆なら「1回1〜2章まで」のように上限を書く 途中で止まった巨大タスクは誰もレビューできない

ポイントは2つ目です。「行数で小さく割る」より「触るファイルで割る」ほうがコンフリクトに直接効きます。小さいタスクが10個あっても、全部が STATE.md を書き換えるなら衝突します。逆に共有ファイル(状態ファイル・ログ)は、エージェントに直接触らせずジョブ側が最後にまとめて書くようにしました。

2. 計画表:Markdownの表をそのまま作業キューにする

計画表は人間が読めることを最優先にして、普通のMarkdownの表にしました。.company/daily-plan/2026-11-19.md はこんな形です。

| # | 部署 | 状態 | 仕事 | 結果 |
|---|---|---|---|---|
| 1 | dev | 完了 | Qiita配信ジョブのリトライ判定を修正 | .company/scripts/qiita-publish.sh |
| 2 | publishing | 進行中 | 新刊: 第3章を執筆(1回1〜2章まで) | |
| 3 | marketing | 未着手 | note記事の週次数値を記録 | |

状態は 未着手 / 進行中 / 完了 / 承認待ち / 見送り / 未完了 の6つだけです。僕は朝この表を見れば、その日に何が起きるかが全部分かります。レビュー対象は「完了」と「承認待ち」の行だけで、結果欄のパスを開けば済みます。

3. 1行ずつ受け取る実装(daily-plan.py)

各部署のジョブは、この表から「自分の部署の最初の未着手」を1つだけ取り、その場で「進行中」に書き換えます。実際に動いているコードです(.company/scripts/lib/daily-plan.py から抜粋)。

import datetime as dt
import sys
from pathlib import Path

PLAN_DIR = Path(__file__).resolve().parents[2] / "daily-plan"


def plan_path():
    return PLAN_DIR / f"{dt.date.today():%Y-%m-%d}.md"


def rows(lines):
    """表の行だけを (行番号, 列のリスト) で返す。列は前後の空白を除く"""
    for i, line in enumerate(lines):
        cells = [c.strip() for c in line.strip().strip("|").split("|")]
        if line.startswith("|") and len(cells) >= 4 and cells[0].isdigit():
            yield i, cells


def set_state(lines, i, cells, state):
    cells[2] = state
    lines[i] = "| " + " | ".join(cells) + " |"


def main():
    cmd, *args = sys.argv[1:] or ["path"]
    path = plan_path()
    if not path.exists():
        return 1
    lines = path.read_text(encoding="utf-8").splitlines()

    if cmd == "next":
        for i, cells in rows(lines):
            if cells[1] == args[0] and cells[2] == "未着手":
                set_state(lines, i, cells, "進行中")
                path.write_text("\n".join(lines) + "\n", encoding="utf-8")
                print(f"{cells[0]}\t{cells[3]}")
                return 0
        return 1

    if cmd == "finish":
        # 担当が状態を書かずに終わったら「未完了」にする(自動でやり直さない)
        for i, cells in rows(lines):
            if cells[0] == args[0] and cells[2] == "進行中":
                set_state(lines, i, cells, "未完了")
                path.write_text("\n".join(lines) + "\n", encoding="utf-8")
        return 0


if __name__ == "__main__":
    sys.exit(main())

使い方:

$ python3 .company/scripts/lib/daily-plan.py next dev
1	Qiita配信ジョブのリトライ判定を修正
$ echo $?
0
# 未着手が無ければ何も出さず終了コード1

設計で効いたのは finish の動きです。エージェントが状態を書かずに終わったとき、自動でやり直さず「未完了」で止めます。自動リトライすると、同じ失敗を何度も繰り返して差分だけが膨らむからです。止まった行は翌朝の計画で人間(または計画担当エージェント)が割り直します。

4. 二重起動を防ぐ排他とプロンプトでの範囲指定(idle-work.sh)

呼び出し側のシェルです(.company/scripts/idle-work.sh から抜粋)。

label="idle-$dept"
log="$SCRIPT_DIR/logs/$label.log"

# 同じ部署で二重に走らせない(mkdir は存在すれば失敗する=アトミックなロック)
lock="/tmp/one-ceo-$label.lock"
if ! mkdir "$lock" 2>/dev/null; then
  echo "$(date): 既に実行中のためスキップ" >> "$log"
  exit 0
fi
# 一時ファイルはプロジェクト内の専用ディレクトリに限定し、片付けはジョブ側で行う
IDLE_TMP="$PROJECT_ROOT/.company/tmp/$label"
mkdir -p "$IDLE_TMP"
trap 'rm -rf "$IDLE_TMP"; rmdir "$lock"' EXIT

# 計画表の最初の未着手を「進行中」にして受け取る。無ければ何もしない
item=$(python3 "$SCRIPT_DIR/lib/daily-plan.py" next "$dept") || exit 0
num=${item%%$'\t'*}
task=${item#*$'\t'}

そしてエージェントへのプロンプトで、計画外の仕事に手を出さないことを明示しています。

common="
終わったら計画表 ${plan_rel} の #${num} の行の状態を「完了 / 承認待ち / 見送り / 未完了」のどれかに書き換え、結果欄に1行(成果物のパス)を書いてください。
計画表のほかの行と、計画に無い仕事には手を出さないでください。
一時ファイル・検証用の作業場所(git worktree・uv init・再現環境)は ${IDLE_TMP} だけを使ってください。"

「ついでにこれも直しておきました」を禁止するのが、レビュー可能な差分を保ついちばん安い方法でした。

落とし穴

  • flock はmacOSに標準では無い。mkdir ロックなら追加インストール不要です。ただし kill -9 で落ちると trap が動かずロックが残るので、ログに「スキップ」が続いたら /tmp/one-ceo-*.lock を確認します。
  • 共有ファイルをエージェントに直接書かせない。当社では部署の STATE.md 更新は別ジョブが集計して書きます。全エージェントが同じファイルを触る構成は、粒度をいくら細かくしても衝突します。
  • pushの衝突は「直さず止める」。開発部だけ git push を許していますが、プロンプトで「リモートが先に進んでいたら fetch して rebase し、衝突したら push せず『未完了』にして理由を書く」と指示しています。AIに衝突解消をさせると、レビューしていない変更が混ざります。

5. 着手前に「ファイルが重なるタスク」を見つける

粒度の基準2(触るファイルが重ならない)は、計画を作る段階で確かめたいところです。以下はこの記事のために書いた小さな検査で、計画表の「仕事」欄に書かれたパスを拾い、同じパスを含む行が2つ以上あれば警告します。

#!/usr/bin/env python3
"""計画表で同じファイルを触るタスクを検出する。使い方: plan-overlap.py <計画表.md>"""
import re
import sys
from collections import defaultdict

PATH_PATTERN = re.compile(r"[\w./-]+\.(?:md|sh|py|ts|yaml|json)")

owners = defaultdict(list)
for line in open(sys.argv[1], encoding="utf-8"):
    cells = [c.strip() for c in line.strip().strip("|").split("|")]
    if not (line.startswith("|") and len(cells) >= 4 and cells[0].isdigit()):
        continue
    if cells[2] != "未着手":
        continue
    for path in set(PATH_PATTERN.findall(cells[3])):
        owners[path].append(cells[0])

conflicts = {p: nums for p, nums in owners.items() if len(nums) > 1}
for path, nums in conflicts.items():
    print(f"重複: {path} ← #{', #'.join(nums)}")
sys.exit(1 if conflicts else 0)
$ python3 plan-overlap.py .company/daily-plan/2026-11-19.md
重複: .company/scripts/qiita-publish.sh ← #4, #7
$ echo $?
1

終了コード1のときは、片方を翌日に回すか、2つを1行にまとめます。仕事欄にパスを書く習慣がないと拾えないので、「仕事欄には触るファイルを書く」こと自体をルールにするのが前提です。

6. 検証方法:割り方が効いているかを数字で見る

運用を変えたら、次の3つで効果を確かめています。

# 1) 今日の計画の状態別件数(未完了が多い=粒度が大きすぎる)
grep -E '^\| [0-9]+ ' .company/daily-plan/$(date +%F).md | awk -F'|' '{gsub(/ /,"",$4); print $4}' | sort | uniq -c

# 2) 二重起動でスキップされた回数
grep -c "既に実行中のためスキップ" .company/scripts/logs/idle-*.log

# 3) 1コミットあたりの変更ファイル数(直近20件)
git log -20 --pretty=format:'%h %s' --shortstat | grep -E 'files? changed'

僕が見ている目安は「未完了が全体の2割を超えたら、翌日の割り方を細かくする」です。体感として一番変わったのは、承認待ちが溜まらなくなったことでした。差分が1つの成果物に閉じているので、朝の確認が結果欄のパスを順に開くだけで終わります。

まとめ

  • タスクは行数より触るファイルで割る。共有ファイルはエージェントに書かせない
  • Markdownの表を作業キューにすると、人間のレビュー画面とAIのキューが一致する
  • 1行ずつ受け取り、失敗したら自動でやり直さず止める
  • 計画外の仕事・衝突の自動解消を禁止して、差分をレビュー可能な大きさに保つ

経営の目線で言うと、AIに仕事を任せるほど、ボトルネックは「AIの速さ」ではなく「人間が確かめられる量」になります。1人会社でAIを何部署も動かして分かったのは、タスクの割り方がそのまま承認のスピードを決める、ということでした。

参考:書籍

複数のエージェントに仕事を分けて並列で動かす設計(役割分担・排他・承認フロー)は、拙著『Claude Codeマルチエージェント開発』で詳しく解説しています。

書籍一覧: https://zenn.dev/joinclass?tab=books
社内で同じような仕組みを作りたいが手が回らない場合は、合同会社ジョインクラスで中小企業向けの業務システム開発・DX支援(国内)を受けています。
👉 業務システム・DXの無料相談

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?