Claude Code 自走開発シリーズ第3弾

← 前の記事：人が毎回指示しなくても開発は進む｜Claude Codeを開発チームのように動かす考え方

→ 次の記事：Claude Codeを定期実行しただけでは自走しなかった｜実際に詰まった7つの問題

シリーズの入口：Claude Code・Codexに動作確認まで自走させる｜ビルド・操作・録画・証跡を残す開発フロー

前の記事では、Claude Codeへ毎回「次」を指示せず、担当を持たせて進める考え方を書きました。

今回は、その実践側です。

前の記事で扱った「探索 / 収束」「完成イメージ」「完成後のズレ検知」は前提として、ここでは複数担当を同じRepositoryでぶつけない設計に絞ります。

自分のプロジェクトでは、実際に次の4レーンへ分けて動かしています。

Server
Web
Client
Integration

最初は、担当を分ければそのまま並行で進められると思っていました。

ところが、同じRepositoryで複数のAIを動かすと、

同じファイルを変更する
同じTaskを拾う
同じbranchを操作する
別々の仕様を正しいと思う
片方が作業中の状態をもう片方が壊す

という問題が出ました。

ここで初めて、担当名を付けるだけでは並行開発にならないと分かりました。

必要だったのは、AI同士の境界です。

この記事では製品固有の構成は出さず、Server / Web / Clientを持つ一般的なシステムとして書いています。

4つの担当に分ける

例として、自分は次のように分けます。

担当	主な責務
Server	API、DB、認証、Server側テスト
Web	管理画面、Web側API接続、型検査
Client	端末UI、Client側API接続、ビルド
Integration	契約整合、横断テスト、統合判断

Server担当がWeb側の問題を見つけても、そのままWebを直しません。

Web担当がAPI不足に気づいても、勝手にServerの契約を変更しません。

担当外の問題は、修正ではなくBlockingとして返します。

AIへ広い変更権限を渡していると、担当外の問題まで続けて修正することがあります。

1セッションなら便利な場面もありますが、並行開発では衝突要因になります。

全員が同じ「正本」を見る

次に必要なのが、何を正しいものとして扱うかです。

例えば、

README
古い設計書
新しいSPEC
現在のコード
過去の実装メモ

が同時に残っていると、担当ごとに別の答えへ到達します。

自分のプロジェクトでは、正本の順序を決めています。

概念としては次のような形です。

AGENTS.md / CLAUDE.md
↓
.ai-workflow配下の開発ルール
↓
資料地図
↓
SPEC（API契約・アーキテクチャ正本を参照）
↓
PLAN
↓
TASK
↓
TEST
↓
REVIEW
↓
保護対象一覧
↓
現在の実装

この順番は、公開済みの第1弾で使っている正本の優先順位と合わせています。

API契約やアーキテクチャはSPECから参照する正本として扱い、現在のコードを最上位には置きません。

実装に不具合がある場合、コードを正としてSPECを書き換えると、不具合が仕様になります。

判断できない差異は、勝手に統合せず止めます。

ここで固定する「正本」と、自走中に更新する「実行状態」は分けています。

人の承認なしで変更しないもの

SPEC
API契約
アーキテクチャ
受入条件
Target画面

自走中に更新してよいもの

READY / RUNNING / DONE
owner
attempt
heartbeat
retry回数
実行結果

仕様を書き換えることと、進捗状態を更新することは別です。

会話履歴を「開発状態」にしない

自走を続けていると、チャットが長くなったり、新しいSessionへ切り替えたりします。

自分も実際に何度もSessionを分けています。

そのたびに長い会話を引き継がないと再開できない状態では、自走には向きません。

そこで、

今どこまで終わったか
何がBLOCKEDか
どのbranchで作業しているか
次に何をするか

を会話だけに持たせないようにしています。

新しいSessionでも、

Repository
正本
Task状態
Git
証跡

を読めば再開できる状態を目指します。

自走可能かを見る簡単なチェックは、

新規Sessionが過去の会話を読まなくても、Repositoryから現在地を判断できるか

です。

できない場合、重要な状態がチャット側へ漏れています。

Taskに「停止条件」を書く

人が毎回見ている開発では、Taskが多少曖昧でも補正できます。

自走では補正してくれる人がいません。

Taskには最低でも次を持たせます。

目的
対象範囲
変更してよい場所
変更してはいけない場所
開始条件
必要な実行環境
完了条件
確認方法
停止条件
依存Task

例えばWeb担当なら、

目的:
  一覧画面をAPIへ接続する

変更範囲:
  Web配下

完了条件:
  build成功
  型検査成功
  API Client経由でデータ取得
  TESTの受入条件を満たす

停止条件:
  API契約に不足がある
  Server側の変更が必要
  未統合Taskへ依存している

のようにします。

「何をするか」より、「どこから先は自分で決めないか」の方が自走では重要でした。

直列か並列かでGitの作業場所を決める

worktreeは「自走だから必須」ではありません。

必要になるのは、複数のSessionが同じ時間に別Taskを進める場合です。

並列自走

Server、Web、Clientを同時に進めるなら、branchと作業場所の両方を分けます。

同じcheckoutを共有すると、一方のcheckoutや未commit差分がもう一方へ影響します。

worktree以外に別cloneでも構いません。

目的は、同時に動く担当へ別々の作業場所を渡すことです。

直列自走

1つのrunnerだけがTaskを順番に処理するなら、

1つの作業ディレクトリ
+
用途別branch
+
同時起動を防ぐrun lock

でも運用できます。

整理すると、

直列自走
→ branch分離 + run lockでも可

並列自走
→ branch + worktree / 別clone

です。

branchを分けても、同じ作業ディレクトリを2つのSessionが同時に使うことはできません。

「branchが別だから安全」ではなく、並列時は作業場所も分離します。

APIは共有境界にする

Server、Web、Clientを並行すると、一番強い接点はAPIです。

ここが曖昧だと、

ServerはAという型を返す
WebはBだと思っている
ClientはCを前提にする

ということが起きます。

そこで、全員が同じAPI契約を見るようにします。

OpenAPIを使うなら、例えば次の形です。

contract-firstで作るか、Server実装からOpenAPIを生成するかはプロジェクト次第です。

OpenAPIは一例です。

自分が揃えたいのはツールではなく、Server / Web / Clientが同じ契約を見て実装している状態です。

Integrationを実装担当から分ける

各担当に、

自分でmainへ統合してください

まで任せることもできます。

自分は分けました。

Server担当はServerとして正しいかを見る。

Web担当はWebとして正しいかを見る。

Client担当はClientとして正しいかを見る。

Integration担当は、

最新main
各feature
API契約
生成Client
build
test
横断動作

をまとめて見ます。

Server担当:
  Serverとして成立するか

Web担当:
  Webとして成立するか

Client担当:
  Clientとして成立するか

Integration担当:
  一緒に動かして成立するか

実装と統合で役割を分けると、実装担当が統合可否まで兼ねずに済みます。

このシリーズでは、公開済みの第1弾と同じく、Integration担当は「mainへ統合可能か」までを判定し、mainへの最終マージは人の承認Gateに残します。

Taskを自分で拾わせる

自走させるには、Taskの状態も必要です。

例です。

READY
RUNNING
DONE
BLOCKED
RETRYABLE
NEEDS_HUMAN

担当はREADYだけを拾います。

RUNNINGなら、新しいセッションはそのTaskを開始しないルールにします。

ただし、Task状態だけで排他を保証できるわけではありません。二重実行対策は、後の記事で扱うロックや所有者確認と組み合わせます。

BLOCKEDなら同じ原因のまま次回また実装を始めません。

NEEDS_HUMANなら人の判断待ちです。

単純なTODOリストより、この方が定期実行と相性がよくなりました。

正常系より異常系を先に考える

初期の自走ルールは、だいたいこうでした。

Taskを探す
↓
実装
↓
build
↓
test
↓
commit
↓
次へ

実際に困ったのは、その外側です。

working treeに知らない差分がある
同じTaskを別セッションが実行中
mainが進んでいる
API契約が一致しない
buildが失敗した
担当外の修正が必要

この状態で「よしなに直す」と、別担当の作業まで巻き込むことがあります。

何度かこうした境界問題を見てから、自分は、

判断できない状態では前へ進まない

を基本にしています。

自走というと「止まらない仕組み」に見えますが、長時間放置するなら、危ないときに止まれる方が大事です。

シリーズの前後記事

← 前の記事：人が毎回指示しなくても開発は進む｜Claude Codeを開発チームのように動かす考え方

→ 次の記事：Claude Codeを定期実行しただけでは自走しなかった｜実際に詰まった7つの問題

シリーズの入口：Claude Code・Codexに動作確認まで自走させる｜ビルド・操作・録画・証跡を残す開発フロー

まとめ

複数のClaude Codeを動かすだけでは、並行開発にはなりません。

必要だったのは、

役割を分ける
正本を固定する
Taskへ停止条件を持たせる
直列 / 並列で作業場所を分ける
APIを共有境界にする
Integrationを別担当にする

という担当間の境界設計でした。

ここまで作ると、各担当が自分で次のTaskを拾って進めやすくなります。

ただし、これで自走基盤が完成したわけではありません。

次に定期実行へ移したところ、

ルーティンは起動したのに、最初の権限確認で止まる

という問題が出ました。

次の記事では、自分のDesktop環境でローカル定期実行を回したときに、実際に詰まったポイントをまとめます。