chore: Spring AI 重构
This commit is contained in:
abel533
@@ -1,16 +1,16 @@
|
||||
# s12: Worktree + Task Isolation
|
||||
# s12: Worktree + Task Isolation (Worktree タスク隔離)
|
||||
|
||||
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
|
||||
|
||||
> *"各自のディレクトリで作業し、互いに干渉しない"* -- タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け。
|
||||
> *"各自のディレクトリで作業し、互いに干渉しない"* -- タスクは目標を管理、worktree はディレクトリを管理、ID で紐付け。
|
||||
>
|
||||
> **Harness 層**: ディレクトリ隔離 -- 決して衝突しない並列実行レーン。
|
||||
|
||||
## 問題
|
||||
|
||||
s11までにエージェントはタスクを自律的に確保して完了できるようになった。しかし全タスクが1つの共有ディレクトリで走る。2つのエージェントが同時に異なるモジュールをリファクタリングすると衝突する: 片方が`config.py`を編集し、もう片方も`config.py`を編集し、未コミットの変更が混ざり合い、どちらもクリーンにロールバックできない。
|
||||
s11 までにエージェントはタスクを自律的に確保して完了できるようになった。しかし全タスクが1つの共有ディレクトリで走る。2つのエージェントが同時に異なるモジュールをリファクタリングすると -- A が `Config.java` を編集し、B も `Config.java` を編集し、未コミットの変更が互いに汚染し、どちらもクリーンにロールバックできない。
|
||||
|
||||
タスクボードは*何をやるか*を追跡するが、*どこでやるか*には関知しない。解決策: 各タスクに専用のgit worktreeディレクトリを与える。タスクが目標を管理し、worktreeが実行コンテキストを管理する。タスクIDで紐付ける。
|
||||
タスクボードは「何をやるか」を追跡するが「どこでやるか」には関知しない。解決策: 各タスクに独立した git worktree ディレクトリを与え、タスク ID で両者を関連付ける。
|
||||
|
||||
## 解決策
|
||||
|
||||
@@ -38,51 +38,74 @@ State machines:
|
||||
|
||||
1. **タスクを作成する。** まず目標を永続化する。
|
||||
|
||||
```python
|
||||
TASKS.create("Implement auth refactor")
|
||||
# -> .tasks/task_1.json status=pending worktree=""
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeTaskManager.java
|
||||
tasks.create("Implement auth refactor", "");
|
||||
// -> .tasks/task_1.json status=pending worktree=""
|
||||
```
|
||||
|
||||
2. **worktreeを作成してタスクに紐付ける。** `task_id`を渡すと、タスクが自動的に`in_progress`に遷移する。
|
||||
2. **worktree を作成してタスクに紐付ける。** `task_id` を渡すと、タスクが自動的に `in_progress` に遷移する。
|
||||
|
||||
```python
|
||||
WORKTREES.create("auth-refactor", task_id=1)
|
||||
# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
|
||||
# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeManager.java
|
||||
worktrees.create("auth-refactor", 1, "HEAD");
|
||||
// -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
|
||||
// -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
|
||||
```
|
||||
|
||||
紐付けは両側に状態を書き込む:
|
||||
|
||||
```python
|
||||
def bind_worktree(self, task_id, worktree):
|
||||
task = self._load(task_id)
|
||||
task["worktree"] = worktree
|
||||
if task["status"] == "pending":
|
||||
task["status"] = "in_progress"
|
||||
self._save(task)
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeTaskManager.java
|
||||
public String bindWorktree(int taskId, String worktree, String owner) {
|
||||
var task = load(taskId);
|
||||
task.put("worktree", worktree);
|
||||
if (owner != null && !owner.isEmpty()) task.put("owner", owner);
|
||||
if ("pending".equals(task.get("status"))) task.put("status", "in_progress");
|
||||
task.put("updated_at", System.currentTimeMillis() / 1000.0);
|
||||
save(task);
|
||||
return mapper.writerWithDefaultPrettyPrinter().writeValueAsString(task);
|
||||
}
|
||||
```
|
||||
|
||||
3. **worktree内でコマンドを実行する。** `cwd`が分離ディレクトリを指す。
|
||||
3. **worktree 内でコマンドを実行する。** `cwd` が隔離ディレクトリを指す。
|
||||
|
||||
```python
|
||||
subprocess.run(command, shell=True, cwd=worktree_path,
|
||||
capture_output=True, text=True, timeout=300)
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeManager.java - run()
|
||||
boolean isWindows = System.getProperty("os.name").toLowerCase().contains("win");
|
||||
ProcessBuilder pb = isWindows
|
||||
? new ProcessBuilder("cmd", "/c", command)
|
||||
: new ProcessBuilder("sh", "-c", command);
|
||||
pb.directory(path.toFile());
|
||||
pb.redirectErrorStream(true);
|
||||
Process p = pb.start();
|
||||
String out = new String(p.getInputStream().readAllBytes()).trim();
|
||||
boolean finished = p.waitFor(300, java.util.concurrent.TimeUnit.SECONDS);
|
||||
```
|
||||
|
||||
4. **終了処理。** 2つの選択肢:
|
||||
- `worktree_keep(name)` -- ディレクトリを保持する。
|
||||
- `worktree_remove(name, complete_task=True)` -- ディレクトリを削除し、紐付けられたタスクを完了し、イベントを発行する。1回の呼び出しで後片付けと完了を処理する。
|
||||
|
||||
```python
|
||||
def remove(self, name, force=False, complete_task=False):
|
||||
self._run_git(["worktree", "remove", wt["path"]])
|
||||
if complete_task and wt.get("task_id") is not None:
|
||||
self.tasks.update(wt["task_id"], status="completed")
|
||||
self.tasks.unbind_worktree(wt["task_id"])
|
||||
self.events.emit("task.completed", ...)
|
||||
```java
|
||||
// src/main/java/io/mybatis/learn/s12/WorktreeManager.java
|
||||
public String remove(String name, boolean force, boolean completeTask) {
|
||||
var wt = findWorktree(name);
|
||||
events.emit("worktree.remove.before", ...);
|
||||
runGit("worktree", "remove", wt.get("path").toString());
|
||||
if (completeTask && wt.get("task_id") != null) {
|
||||
int taskId = ((Number) wt.get("task_id")).intValue();
|
||||
tasks.update(taskId, "completed", null);
|
||||
tasks.unbindWorktree(taskId);
|
||||
events.emit("task.completed",
|
||||
Map.of("id", taskId, "status", "completed"),
|
||||
Map.of("name", name), null);
|
||||
}
|
||||
// index.json を更新: status -> "removed"
|
||||
}
|
||||
```
|
||||
|
||||
5. **イベントストリーム。** ライフサイクルの各ステップが`.worktrees/events.jsonl`に記録される:
|
||||
5. **イベントストリーム。** ライフサイクルの各ステップが `.worktrees/events.jsonl` に記録される:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -93,27 +116,29 @@ def remove(self, name, force=False, complete_task=False):
|
||||
}
|
||||
```
|
||||
|
||||
発行されるイベント: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`。
|
||||
イベントタイプ: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`。
|
||||
|
||||
クラッシュ後も`.tasks/` + `.worktrees/index.json`から状態を再構築できる。会話メモリは揮発性だが、ファイル状態は永続的だ。
|
||||
クラッシュ後も `.tasks/` + `.worktrees/index.json` から状態を再構築できる。会話メモリは揮発性だが、ディスク状態は永続的だ。
|
||||
|
||||
## s11からの変更点
|
||||
## s11 からの変更点
|
||||
|
||||
| Component | Before (s11) | After (s12) |
|
||||
| コンポーネント | 変更前 (s11) | 変更後 (s12) |
|
||||
|--------------------|----------------------------|----------------------------------------------|
|
||||
| Coordination | Task board (owner/status) | Task board + explicit worktree binding |
|
||||
| Execution scope | Shared directory | Task-scoped isolated directory |
|
||||
| Recoverability | Task status only | Task status + worktree index |
|
||||
| Teardown | Task completion | Task completion + explicit keep/remove |
|
||||
| Lifecycle visibility | Implicit in logs | Explicit events in `.worktrees/events.jsonl` |
|
||||
| 協調 | タスクボード (owner/status) | タスクボード + worktree 明示的紐付け |
|
||||
| 実行スコープ | 共有ディレクトリ | タスクごとの隔離ディレクトリ |
|
||||
| 復旧可能性 | タスクステータスのみ | タスクステータス + worktree インデックス |
|
||||
| 終了処理 | タスク完了 | タスク完了 + 明示的 keep/remove |
|
||||
| ライフサイクル可視性 | ログ内に暗黙的 | `.worktrees/events.jsonl` で明示的イベントストリーム |
|
||||
|
||||
## 試してみる
|
||||
|
||||
```sh
|
||||
cd learn-claude-code
|
||||
python agents/s12_worktree_task_isolation.py
|
||||
mvn exec:java -Dexec.mainClass=io.mybatis.learn.s12.S12WorktreeIsolation
|
||||
```
|
||||
|
||||
以下のプロンプトを試してみよう (英語プロンプトの方が LLM に効果的だが、日本語でも可):
|
||||
|
||||
1. `Create tasks for backend auth and frontend login page, then list tasks.`
|
||||
2. `Create worktree "auth-refactor" for task 1, then bind task 2 to a new worktree "ui-login".`
|
||||
3. `Run "git status --short" in worktree "auth-refactor".`
|
||||
|
||||
Reference in New Issue
Block a user