chore: import upstream snapshot with attribution

2026-07-13 12:12:24 +08:00
commit 33b4ec712e
450 changed files with 80543 additions and 0 deletions
@@ -0,0 +1,96 @@
+# s03: TodoWrite
+
+`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"計画のないエージェントは行き当たりばったり"* -- まずステップを書き出し、それから実行。
+>
+> **Harness 層**: 計画 -- 航路を描かずにモデルを軌道に乗せる。
+
+## 問題
+
+マルチステップのタスクで、モデルは途中で迷子になる。作業を繰り返したり、ステップを飛ばしたり、脱線したりする。長い会話になるほど悪化する -- ツール結果がコンテキストを埋めるにつれ、システムプロンプトの影響力が薄れる。10ステップのリファクタリングでステップ1-3を完了した後、残りを忘れて即興を始めてしまう。
+
+## 解決策
+
+```
+--------+      +-------+      +---------+
+|  User  | ---> |  LLM  | ---> | Tools   |
+| prompt |      |       |      | + todo  |
+--------+      +---+---+      +----+----+
+                    ^                |
+                    |   tool_result  |
+                    +----------------+
+                          |
+              +-----------+-----------+
+              | TodoManager state     |
+              | [ ] task A            |
+              | [>] task B  <- doing  |
+              | [x] task C            |
+              +-----------------------+
+                          |
+              if rounds_since_todo >= 3:
+                inject <reminder> into tool_result
+```
+
+## 仕組み
+
+1. TodoManagerはアイテムのリストをステータス付きで保持する。`in_progress`にできるのは同時に1つだけ。
+
+```python
+class TodoManager:
+    def update(self, items: list) -> str:
+        validated, in_progress_count = [], 0
+        for item in items:
+            status = item.get("status", "pending")
+            if status == "in_progress":
+                in_progress_count += 1
+            validated.append({"id": item["id"], "text": item["text"],
+                              "status": status})
+        if in_progress_count > 1:
+            raise ValueError("Only one task can be in_progress")
+        self.items = validated
+        return self.render()
+```
+
+2. `todo`ツールは他のツールと同様にディスパッチマップに追加される。
+
+```python
+TOOL_HANDLERS = {
+    # ...base tools...
+    "todo": lambda **kw: TODO.update(kw["items"]),
+}
+```
+
+3. nagリマインダーが、モデルが3ラウンド以上`todo`を呼ばなかった場合にナッジを注入する。
+
+```python
+if rounds_since_todo >= 3 and messages:
+    last = messages[-1]
+    if last["role"] == "user" and isinstance(last.get("content"), list):
+        last["content"].insert(0, {
+            "type": "text",
+            "text": "<reminder>Update your todos.</reminder>",
+        })
+```
+
+「一度にin_progressは1つだけ」の制約が逐次的な集中を強制し、nagリマインダーが説明責任を生む。
+
+## s02からの変更点
+
+| Component      | Before (s02)     | After (s03)                |
+|----------------|------------------|----------------------------|
+| Tools          | 4                | 5 (+todo)                  |
+| Planning       | None             | TodoManager with statuses  |
+| Nag injection  | None             | `<reminder>` after 3 rounds|
+| Agent loop     | Simple dispatch  | + rounds_since_todo counter|
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s03_todo_write.py
+```
+
+1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`
+2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py`
+3. `Review all Python files and fix any style issues`