mirror of
https://github.com/shareAI-lab/analysis_claude_code.git
synced 2026-09-21 21:03:38 +08:00
feat: consolidate course into 21 lessons
This commit is contained in:
Haoran
@@ -2,7 +2,7 @@
|
||||
|
||||
[English](README.md) · [中文](README.zh.md) · [日本語](README.ja.md)
|
||||
|
||||
s01 → ... → s10 → s11 → `s12` → [s13](../s13_background_tasks/) → s14 → ... → s20 → s21 → s22
|
||||
s01 → ... → s10 → s11 → `s12` → [s13](../s13_background_tasks/) → s14 → ... → s20 → s21
|
||||
|
||||
> *"大きな目標を小さなタスクに分け、順序付け、永続化"* — ファイル永続化タスクグラフ、マルチ Agent 協調の基盤。
|
||||
>
|
||||
@@ -14,7 +14,7 @@ s01 → ... → s10 → s11 → `s12` → [s13](../s13_background_tasks/) → s1
|
||||
|
||||
Agent がプロジェクトを受けた：データベース構築、API 実装、テスト追加。s05 の TodoWrite でリストを作り、まず API を書き始め、途中でデータベーステーブルがないことに気づいて戻る。テスト追加時に API インターフェースのシグネチャがまた変わっている...
|
||||
|
||||
屋根を先に建てて基礎を後から打つことはできない。タスクには順序がある。タスクの依存関係は有向非巡回グラフ（DAG）を形成すべき；教学版は `blockedBy` チェックのみをデモし、循環検出は実装していない。
|
||||
屋根を先に建てて基礎を後から打つことはできない。タスクには順序がある。タスク間の前提依存関係は有向非巡回グラフ（DAG）として表現でき、この章では `blockedBy` でそれらを記録する。
|
||||
|
||||
s05 の TodoWrite は現在のタスクの実行チェックリストで、セッションメモリに保持される。ここで必要なのは**タスクシステム**：各タスクは JSON ファイル、タスク間に `blockedBy` 依存関係、ディスク上でセッションをまたいで永続化。
|
||||
|
||||
@@ -24,7 +24,7 @@ s05 の TodoWrite は現在のタスクの実行チェックリストで、セ
|
||||
|
||||
|
||||
|
||||
教育版は基本 agent loop を維持し、タスクシステムに集中するため S11 の完全なエラーリカバリ（RecoveryState、バックオフ、エスカレーション、reactive compact、フォールバックモデル）を省略。追加：5 つの教育用ツール + `.tasks/` ディレクトリによる永続化 + `blockedBy` 依存チェック。タスクシステムとエラーリカバリは独立したレイヤーで、タスクモジュールは状態を、query recovery はモデル呼び出し失敗を扱う。
|
||||
この章では、5 つのタスクツール、`.tasks/` ディレクトリへの永続化、`blockedBy` の依存チェックを追加する。
|
||||
|
||||
TodoWrite vs Task System：
|
||||
|
||||
@@ -39,8 +39,6 @@ TodoWrite vs Task System：
|
||||
| 粒度 | Agent 自身の手順 | 認識・追跡・アンロックできるタスク |
|
||||
| 更新契約 | リスト全体を置換 | 個別レコードを作成・取得・更新・一覧 |
|
||||
|
||||
教育用 API は `create_task`、`list_tasks`、`get_task`、`claim_task`、`complete_task` としてライフサイクルを明示する。Claude Code の製品サーフェスはこれらを `TaskCreate`、`TaskGet`、`TaskUpdate`、`TaskList` の 4 ツールにまとめ、認識と完了は独立した公式ツールではなく更新操作として扱う。
|
||||
|
||||
---
|
||||
|
||||
## 仕組み
|
||||
@@ -62,7 +60,7 @@ class Task:
|
||||
blockedBy: list[str] # 依存タスク ID のリスト
|
||||
```
|
||||
|
||||
ID は `timestamp + random hex` で生成、シンプルだが十分。CC は順次 ID + highwatermark ファイルで ID 再利用を防止する、より厳密な設計。
|
||||
ID は `timestamp + random hex` で生成する。
|
||||
|
||||
### create_task: タスク作成
|
||||
|
||||
@@ -162,8 +160,6 @@ pending ──claim──→ in_progress ──complete──→ completed
|
||||
- **claim_task**: `pending` → `in_progress`。owner を設定し、作業を開始。
|
||||
- **complete_task**: `in_progress` → `completed`。タスクを完了済みにし、下流をアンロック。
|
||||
|
||||
CC には `in_progress → pending` の release パスがない。teammate が終了または shutdown した場合、CC は未完了タスクの owner をクリアし、status を `pending` にリセットし、他の agent が再認識できるようにする。教学版はこの復旧パスを省略。
|
||||
|
||||
### 組み合わせて実行
|
||||
|
||||
```python
|
||||
@@ -228,58 +224,5 @@ python s12_task_system/code.py
|
||||
|
||||
s13 Background Tasks → 遅い操作はバックグラウンドへ。Agent は他のタスクの処理を続け、バックグラウンドの完了を通知で受け取る。
|
||||
|
||||
<details>
|
||||
<summary>CC ソースコード深掘り</summary>
|
||||
|
||||
> 以下は CC ソースコード `utils/tasks.ts`（862 行）、`tools/TaskCreateTool/TaskCreateTool.ts`（138 行）、`tools/TaskUpdateTool/TaskUpdateTool.ts`（406 行）、`tools/TaskGetTool/TaskGetTool.ts`（128 行）、`tools/TaskListTool/TaskListTool.ts`（116 行）、`hooks/useTaskListWatcher.ts`（221 行）の完全分析に基づく。
|
||||
|
||||
### 一、TaskRecord の完全フィールド
|
||||
|
||||
チュートリアルでは id、subject、status、owner、blockedBy のみ解説。CC は実際に 9 フィールドを持つ（`utils/tasks.ts:76-89`）：
|
||||
|
||||
| フィールド | 型 | 用途 |
|
||||
|------|------|------|
|
||||
| `id` | string | 昇順整数 ID |
|
||||
| `subject` | string | 短いタイトル |
|
||||
| `description` | string | 自由形式の説明 |
|
||||
| `activeForm` | string? | 現在進行形、in_progress 時にスピナーに表示 |
|
||||
| `owner` | string? | 割り当てられた agent ID |
|
||||
| `status` | pending/in_progress/completed | ライフサイクル |
|
||||
| `blocks` | string[] | このタスクがブロックするタスク ID（下流） |
|
||||
| `blockedBy` | string[] | このタスクをブロックするタスク ID（上流） |
|
||||
| `metadata` | Record? | 任意の拡張キーバリューペア |
|
||||
|
||||
保存場所：`~/.claude/tasks/{taskListId}/{id}.json`。タスクごとに 1 ファイル。
|
||||
|
||||
### 二、目的は近いが、機構は独立
|
||||
|
||||
Task ツールと TodoWrite は共存できるが、同じストレージモデルを共有しない。現在の対話型セッションは構造化 Task ツールを既定で使い、TodoWrite は非対話型や Agent SDK などの互換サーフェスに残る。公開範囲はリリースや設定で変わり得る。Task レコードはファイルロック、依存関係、ownership、リアクティブ監視、ライフサイクルフックを追加し、TodoWrite はリスト全体を置換するセッションチェックリストである。
|
||||
|
||||
### 三、並行認識のロック機構
|
||||
|
||||
`claimTask()`（`utils/tasks.ts:541-612`）は二重ロックで競合を防止：
|
||||
|
||||
**タスクファイルロック**：`proper-lockfile` で `{taskId}.json` をロック（最大 30 リトライ、指数バックオフ 5-100ms）。ロック内：
|
||||
1. タスクを再読込（TOCTOU 防止）
|
||||
2. 既に他者が認識済み → `already_claimed`
|
||||
3. 既に完了済み → `already_resolved`
|
||||
4. 上流が未完了 → `blocked`
|
||||
5. owner を設定
|
||||
|
||||
**リストレベルロック**（agent busy チェック時）：`.lock` ファイル、全タスクを原子的に走査し該当 agent が他の open task を持つか確認。
|
||||
|
||||
注意：教学版は認識と作業開始を 1 ステップに統合（claim = owner 設定 + in_progress）；実際の CC の `claimTask` は主に owner 競合を解決し、owner のみを設定して status は変更しない。status の更新は `TaskUpdate` が担当。
|
||||
|
||||
### 四、高水位標による ID 再利用防止
|
||||
|
||||
`.highwatermark` ファイルが過去に割り当てられた最大タスク ID を記録。タスクが削除されても ID は再利用されない。
|
||||
|
||||
### 五、4 つの Task ツール
|
||||
|
||||
CC のタスクシステムは 4 つのツールを持つ（チュートリアルの汎用 Task ツールとは異なる）：`TaskCreate`、`TaskGet`、`TaskUpdate`、`TaskList`。すべて `isConcurrencySafe: true` と `shouldDefer: true` が設定（ツールスキーマは初期プロンプトに含まれず、ToolSearch 後にのみ可視）。
|
||||
|
||||
教学版の `create_task(blockedBy=...)` は作成時に直接依存を宣言する合理な簡略化。実際の CC の `TaskCreate` は subject/description/activeForm/metadata のみを受け付け、依存関係は `TaskUpdate` の `addBlocks/addBlockedBy` で管理される。
|
||||
|
||||
</details>
|
||||
|
||||
<!-- translation-sync: zh@v1, en@v1, ja@v1 -->
|
||||
|
||||
Reference in New Issue
Block a user