Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
docs: clarify distinction between core concepts and five failure layers
sanbuphyaace33eecf1f
diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 1f38e11..5646231 100644--- a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -35,7 +35,7 @@ Even more common: there's simply no way to verify. No tests, no lint, or verificLong tasks spanning sessions are even worse — all discoveries from the previous session are lost, and every new session has to re-explore the project structure and re-understand the code organization. Agents without persistent state see failure rates spike sharply on tasks exceeding 30 minutes.-## Core Concepts+## Key TerminologyWith these scenarios in mind, these concepts are no longer just jargon:@@ -52,7 +52,7 @@ Core principle: **When things fail, don't swap the model first — check the harConcrete steps:-**Attribute every failure to a specific layer.** Don't just say "the model sucks." Ask: was the task unclear? Was context insufficient? Were there no verification methods? Map each failure to one of the five layers above. Build this habit, and you'll find "the model isn't good enough" appearing less and less in your logs.+**Attribute every failure to a specific layer.** Don't just say "the model sucks." Ask: was the task unclear? Was context insufficient? Were there no verification methods? Map each failure to one of the five failure layers (task specification, context provision, execution environment, verification feedback, state management). Build this habit, and you'll find "the model isn't good enough" appearing less and less in your logs.**Write an explicit Definition of Done for every task.** Don't say "add a search feature." Say:```diff --git a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 871733c..b53a947 100644--- a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -35,7 +35,7 @@ Anthropic провели контролируемый эксперимент. ОДлинные задачи на несколько сессий — ещё хуже: все находки прошлой сессии теряются, и каждая новая сессия заново исследует структуру проекта и заново разбирается в организации кода. У агентов без персистентного состояния процент провалов резко растёт на задачах длиннее 30 минут.-## Ключевые понятия+## Ключевая терминологияКогда вы видите эти сценарии вживую, термины перестают быть просто жаргоном:@@ -52,7 +52,7 @@ Anthropic провели контролируемый эксперимент. ОКонкретные шаги:-**Привязывайте каждый провал к конкретному слою.** Не ограничивайтесь «модель тупит». Спросите: задача была размыта? Контекста не хватало? Не было способов верификации? Сопоставьте каждый провал с одним из пяти слоёв выше. Выработайте эту привычку — и в ваших логах «модель недостаточно хороша» будет всплывать всё реже.+**Привязывайте каждый провал к конкретному слою.** Не ограничивайтесь «модель тупит». Спросите: задача была размыта? Контекста не хватало? Не было способов верификации? Сопоставьте каждый провал с одним из пяти защитных слоёв (спецификация задачи, предоставление контекста, среда исполнения, верификационная обратная связь, управление состоянием). Выработайте эту привычку — и в ваших логах «модель недостаточно хороша» будет всплывать всё реже.**Пишите явный Definition of Done для каждой задачи.** Не «добавь поиск». А:```diff --git a/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex c643739..c2651f5 100644--- a/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -35,7 +35,7 @@ Thậm chí còn phổ biến hơn: đơn giản là không có cách nào đểCác tác vụ dài trải dài qua nhiều phiên còn tệ hơn — tất cả những phát hiện từ phiên trước đều bị mất, và mọi phiên mới phải khám phá lại cấu trúc dự án và hiểu lại cách tổ chức mã. Các agent không có trạng thái liên tục thấy tỷ lệ thất bại tăng vọt trên các tác vụ vượt quá 30 phút.-## Các Khái niệm Cốt lõi+## Giải thích thuật ngữ chínhVới những tình huống này, các khái niệm sau không còn chỉ là thuật ngữ nữa:@@ -52,7 +52,7 @@ Nguyên tắc cốt lõi: **Khi sự cố xảy ra, đừng đổi mô hình trCác bước cụ thể:-**Quy mọi lỗi cho một lớp cụ thể.** Đừng chỉ nói "mô hình không tốt." Hãy hỏi: tác vụ có mơ hồ không? Ngữ cảnh có không đủ không? Không có phương pháp xác minh không? Ánh xạ mỗi lỗi vào một trong năm lớp ở trên. Xây dựng thói quen này, và bạn sẽ thấy "mô hình không đủ tốt" xuất hiện ngày càng ít hơn trong nhật ký của bạn.+**Quy mọi lỗi cho một lớp cụ thể.** Đừng chỉ nói "mô hình không tốt." Hãy hỏi: tác vụ có mơ hồ không? Ngữ cảnh có không đủ không? Không có phương pháp xác minh không? Ánh xạ mỗi lỗi vào một trong năm lớp phòng thủ (đặc tả tác vụ, cung cấp ngữ cảnh, môi trường thực thi, phản hồi xác minh, quản lý trạng thái). Xây dựng thói quen này, và bạn sẽ thấy "mô hình không đủ tốt" xuất hiện ngày càng ít hơn trong nhật ký của bạn.**Viết Định nghĩa Hoàn thành rõ ràng cho mỗi tác vụ.** Đừng nói "thêm tính năng tìm kiếm." Hãy nói:```diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 4f4a084..6ddd128 100644--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -35,7 +35,7 @@ OpenAI 在 2025 年发布的 harness engineering 文章里说得更直白:Code长任务跨会话就更惨了——上次会话的发现全丢了,每个新会话都得重新探索项目结构、理解代码组织。缺乏持久化状态的 agent 在超过 30 分钟的任务中失败率急剧上升。-## 核心概念+## 关键名词解释理解了上面的场景,这些概念就不再是一堆术语了:@@ -52,7 +52,7 @@ OpenAI 在 2025 年发布的 harness engineering 文章里说得更直白:Code具体怎么做:-**每次失败都归因到具体层。** 不要笼统地说"模型不行",而是问:是任务没说清楚?是上下文不够?是没有验证手段?把每次失败归到上面五层中的某一层。养成这个习惯,你会发现"模型不行"这个结论在你的日志里出现得越来越少。+**每次失败都归因到具体层。** 不要笼统地说"模型不行",而是问:是任务没说清楚?是上下文不够?是没有验证手段?把每次失败归到五层防御(任务规范、上下文供给、执行环境、验证反馈、状态管理)中的某一层。养成这个习惯,你会发现"模型不行"这个结论在你的日志里出现得越来越少。**给每个任务写显式的完成定义。** 不要说"加个搜索功能",要说:```