Skip to content

Harness engineering beginner tutorial, from 0 to 1

feat: translate all English code blocks in localized READMEs

sanbuphy7ae2db55c8f7
diff --git a/README-AR.md b/README-AR.md
index 3992990..1469765 100644
--- a/README-AR.md
+++ b/README-AR.md
@@ -84,22 +84,22 @@
**هذه الدورة تعلّمك كيف تبني تلك البيئة.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ نمط الحزام
+ ===========
+
+ أنت --> تعطي مهمة --> الوكيل يقرأ ملفات الحزام --> الوكيل ينفذ
+ |
+ الحزام يحكم كل خطوة:
+ |
+ +--> التعليمات: ماذا يفعل، بأي ترتيب
+ +--> النطاق: ميزة واحدة في كل مرة، بلا تجاوز
+ +--> الحالة: سجل التقدم، قائمة الميزات، سجل git
+ +--> التحقق: اختبارات، تنسيق، فحص أنواع، تشغيل تجريبي
+ +--> دورة الحياة: تهيئة في البداية، حالة نظيفة في النهاية
+ |
+ v
+ الوكيل يتوقف فقط عندما
+ يجتاز التحقق
```
---
@@ -112,32 +112,32 @@
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ الحزام │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ التعليمات │ │ الحالة │ │ التحقق │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ اختبارات + تنسيق │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ فحص أنواع │ │
+ │ │ feature_list │ │ سجل git │ │ تشغيل تجريبي │ │
+ │ │ docs/ │ │ تسليم جلسة │ │ خط أنابيب شامل │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ النطاق │ │ دورة حياة الجلسة │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ ميزة واحدة │ │ init.sh في البداية │ │
+ │ │ في كل مرة │ │ قائمة حالة نظيفة في النهاية │ │
+ │ │ تعريف │ │ ملاحظة تسليم للجلسة التالية │ │
+ │ │ الإتمام │ │ التزام فقط عندما يكون آمناً للاستئناف │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ النموذج يقرر أي كود يكتبه.
+ الحزام يحكم متى وأين وكيف يكتبه.
+ الحزام لا يجعل النموذج أذكى.
+ بل يجعل مخرجات النموذج موثوقة.
```
لكل نظام فرعي وظيفة واحدة:
@@ -157,24 +157,24 @@
حالياً، الإجابة هي: ليس بدون حزام.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ بدون حزام مع حزام
+ ========= ======
+
+ الجلسة 1: الوكيل يكتب كوداً الجلسة 1: الوكيل يقرأ التعليمات
+ الوكيل يكسر الاختبارات الوكيل يشغّل init.sh
+ الوكيل يقول "تم" الوكيل يعمل على ميزة واحدة
+ أنت تصلحه يدوياً الوكيل يتحقق قبل أن يدّعي الإتمام
+ الوكيل يحدّث سجل التقدم
+ الجلسة 2: الوكيل يبدأ من الصفر الوكيل يلتزم حالة نظيفة
+ الوكيل ليس لديه ذاكرة
+ لما حدث سابقاً الجلسة 2: الوكيل يقرأ سجل التقدم
+ الوكيل يعيد العمل الوكيل يكمل من حيث توقف بالضبط
+ أو يقوم بشيء آخر تماماً الوكيل يواصل الميزة غير المكتملة
+ أنت تصلحه مرة أخرى أنت تراجع، لا تنقذ
+
+ النتيجة: أنت تقضي وقتاً أطول النتيجة: الوكيل يقوم بالعمل،
+ في الإصلاح مما لو كنت وأنت تتحقق من النتيجة
+ فعلت ذلك بنفسك
```
الأسئلة التي تهتم بها هذه الدورة فعلياً:
@@ -205,13 +205,13 @@
الفكرة بسيطة: بدلاً من مجرد كتابة الموجهات، أعطِ وكيلك مجموعة من الملفات المنظمة التي تحدد ما يجب فعله، ما تم إنجازه، وكيفية التحقق من العمل. هذه الملفات تعيش داخل مستودعك، لذا تبدأ كل جلسة من نفس الحالة.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ الجذر الرئيسي لمشروعك
+ ├── AGENTS.md <-- دليل تشغيل الوكيل
+ ├── CLAUDE.md <-- (بديل، إذا كنت تستخدم Claude Code)
+ ├── init.sh <-- يشغّل التثبيت + التحقق + البدء
+ ├── feature_list.json <-- الميزات الموجودة، أيها مكتمل
+ ├── claude-progress.md <-- ما حدث في كل جلسة
+ └── src/ <-- الكود الفعلي الخاص بك
```
احصل على القوالب الأولية من [مكتبة الموارد](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) وأضفها إلى مشروعك. هذا كل شيء. أربعة ملفات، وستكون جلسات وكيلك أكثر استقراراً بشكل ملحوظ مقارنة بالاعتماد على الموجهات وحدها.
@@ -224,28 +224,28 @@
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ تطبيق سطح مكتب لقاعدة المعرفة │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ قائمة المستندات│ │ لوحة الأسئلة والأجوبة ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ س: ما هي هندسة الحزام؟ ││
+ │ │ doc-002.md │ │ ج: البيئة المبنية ││
+ │ │ doc-003.md │ │ حول نموذج وكيل... ││
+ │ │ ... │ │ [استشهاد: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ شريط الحالة: 42 مستند | 38 مفهرس | آخر مزامنة 3د ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ الميزات الأساسية:
+ ├── استيراد المستندات المحلية
+ ├── إدارة مكتبة المستندات
+ ├── معالجة وفهرسة المستندات
+ ├── تشغيل أسئلة وأجوبة مدعومة بالذكاء الاصطناعي على المحتوى المستورد
+ └── إرجاع إجابات مبنية على أدلة مع استشهادات
```
تم اختيار هذا المشروع لأنه يجمع بين قيمة عملية قوية، تعقيد كافٍ في المنتج الحقيقي، وبيئة جيدة لمراقبة تحسينات الحزام قبل وبعد.
@@ -259,47 +259,48 @@
الدورة مصممة لتُنفذ بالترتيب. كل مرحلة تبني على سابقتها.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ المرحلة 1: شاهد المشكلة المرحلة 2: هيكل المستودع
+ ======================= ========================
+
+ L01 النماذج القوية ≠ تنفيذ L03 المستودع كمصدر
+ موثوق وحيد للحقيقة
+ L02 ماذا يعني الحزام فعلياً
+ L04 قسّم التعليمات عبر
+ | ملفات، لا ملف ضخم واحد
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 بالموجهات فقط مقابل |
+ القواعد أولاً v
+ P02 مساحة عمل قابلة للقراءة
+ بواسطة الوكيل
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ المرحلة 3: ربط الجلسات المرحلة 4: التغذية الراجعة والنطاق
+ ========================== ==================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 أبقِ السياق حياً L07 ارسم حدود مهام واضحة
+ عبر الجلسات
+ L08 قوائم الميزات كعناصر
+ L06 التهيئة قبل كل أساسية للحزام
+ جلسة وكيل
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 تغذية راجعة وقت التشغيل
+ P03 استمرارية متعددة الجلسات لتصحيح سلوك الوكيل
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ المرحلة 5: التحقق المرحلة 6: اجمع كل شيء
+ ===================== ========================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 أوقف الوكلاء عن L11 اجعل بيئة تشغيل الوكيل
+ إعلان النصر مبكراً قابلة للملاحظة
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 تشغيل خط أنابيب كامل = L12 تسليم نظيف في نهاية
+ تحقق حقيقي كل جلسة
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 الوكيل يتحقق من عمله بنفسه P06 ابنِ حزاماً كاملاً
+ (مشروع التخرج)
```
كل مرحلة تستغرق حوالي أسبوع إذا كنت تعمل بدوام جزئي. إذا كنت تريد السرعة، يمكن إنجاز المراحل 1-3 في عطلة نهاية أسبوع طويلة.
@@ -339,28 +340,28 @@
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | ابنِ حزاماً كاملاً من الصفر (مشروع التخرج) | حزام كامل: جميع الآليات + قابلية الملاحظة + دراسة الاستئصال |
```text
- PROJECT EVOLUTION
- =================
+ تطور المشاريع
+ =============
- P01 Prompt-only vs. rules-first You see the problem
+ P01 بالموجهات فقط مقابل القواعد أولاً أنت ترى المشكلة
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 مساحة عمل قابلة للقراءة بواسطة الوكيل أنت تعيد هيكلة المستودع
|
v
- P03 Multi-session continuity You connect sessions
+ P03 استمرارية متعددة الجلسات أنت تربط الجلسات
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 تغذية راجعة وقت التشغيل والنطاق أنت تضيف حلقات التغذية الراجعة
|
v
- P05 Self-verification You make the agent check itself
+ P05 التحقق الذاتي أنت تجعل الوكيل يتحقق من نفسه
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 حزام كامل (مشروع التخرج) أنت تبني النظام الكامل
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ حل كل مشروع يصبح بداية المشروع التالي.
+ التطبيق يتطور. مهاراتك في الحزام تنمو معه.
```
### مكتبة الموارد
@@ -385,44 +386,44 @@
إحدى الأفكار الأساسية في هذه الدورة: **يجب أن تتبع جلسة الوكيل دورة حياة منظمة، وليست عشوائية.** إليك كيف تبدو:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ دورة حياة جلسة الوكيل
+ =====================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ البداية │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. الوكيل يقرأ AGENTS.md / CLAUDE.md │
+ │ 2. الوكيل يشغّل init.sh (تثبيت، تحقق، فحص صحي) │
+ │ 3. الوكيل يقرأ claude-progress.md (ما حدث في المرة السابقة) │
+ │ 4. الوكيل يقرأ feature_list.json (ما تم إنجازه، ما هو التالي) │
+ │ 5. الوكيل يفحص سجل git (التغييرات الأخيرة) │
│ │
- │ SELECT │
+ │ الاختيار │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. الوكيل يختار ميزة واحدة غير مكتملة بالضبط │
+ │ 7. الوكيل يعمل على تلك الميزة فقط │
│ │
- │ EXECUTE │
+ │ التنفيذ │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. الوكيل ينفّذ الميزة │
+ │ 9. الوكيل يشغّل التحقق (اختبارات، تنسيق، فحص أنواع) │
+ │ 10. إذا فشل التحقق: إصلاح وإعادة التشغيل │
+ │ 11. إذا نجح التحقق: تسجيل الدليل │
│ │
- │ WRAP UP │
+ │ الختام │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. الوكيل يحدّث claude-progress.md │
+ │ 13. الوكيل يحدّث feature_list.json │
+ │ 14. الوكيل يسجّل ما زال معطلاً أو غير مُتحقق منه │
+ │ 15. الوكيل يلتزم (فقط عندما يكون آمناً للاستئناف) │
+ │ 16. الوكيل يترك مسار إعادة تشغيل نظيف للجلسة التالية │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ الحزام يحكم كل انتقال في دورة الحياة هذه.
+ النموذج يقرر أي كود يكتبه في كل خطوة.
+ بدون الحزام، الخطوة 9 تصبح "الوكيل يقول يبدو جيداً."
+ مع الحزام، الخطوة 9 هي "الاختبارات تجتاز، التنسيق نظيف، الأنواع صحيحة."
```
---
diff --git a/README-CN.md b/README-CN.md
index df7d672..46338e9 100644
--- a/README-CN.md
+++ b/README-CN.md
@@ -15,361 +15,356 @@
# Learn Harness Engineering
-> **这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 AI 编程智能体(Coding Agents)更可靠地工作。**
+> **一门基于项目的课程,教你构建让 AI 编程代理可靠工作的环境、状态管理、验证和控制机制。**
-Learn Harness Engineering 是一门专注于 AI 编程智能体工程化落地的课程。本课程深度研究并总结了业内最前沿的 Harness Engineering(工具马具/脚手架工程)理论与实践,参考资料包括:
+Learn Harness Engineering 是一门专注于 AI 编程代理工程化的课程。我们深入研究和综合了业界最先进的 Harness Engineering 理论与实践。我们的核心参考资料包括:
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
-[**官方网站及多语言文档**](https://walkinglabs.github.io/learn-harness-engineering/) | [**English README**](./README.md)
-
-> **快速上手?** [`skills/harness-creator/`](./skills/) 技能可以帮你在几分钟内为自己的项目搭建一套生产级的 harness(AGENTS.md、功能清单、init.sh、验证工作流)。
+> **快速开始?** [`skills/harness-creator/`](../../skills/) 技能可以帮助你在几分钟内为自己的项目搭建生产级别的 Harness(AGENTS.md、功能列表、init.sh、验证工作流)。
---
## 目录
-- [✨ 界面速览](#-界面速览)
-- [Harness Engineering 到底是什么](#harness-engineering-到底是什么)
-- [快速开始:今天就能改善你的 agent](#快速开始今天就能改善你的-agent)
-- [贯穿项目:一个真实的应用](#贯穿项目一个真实的应用)
+- [视觉预览](#视觉预览)
+- [Harness Engineering 到底是什么意思](#harness-engineering-到底是什么意思)
+- [快速开始:今天就改善你的代理](#快速开始今天就改善你的代理)
+- [毕业项目:一个真实的应用](#毕业项目一个真实的应用)
- [学习路径](#学习路径)
- [课程大纲](#课程大纲)
-- [Skills](#skills)
+- [技能](#技能)
- [其他课程](#其他课程)
---
-## ✨ 界面速览
+## 视觉预览
-### 🏠 课程主页
-> 包含完整的课程大纲与核心理念介绍,清晰的学习路径助你快速入门。
+### 课程主页
+> 全面的课程大纲和核心理念介绍,为你提供清晰的学习起点。
-![课程主页预览](./docs/public/screenshots/readme/zh-home.png)
+![课程主页预览](../../docs/public/screenshots/readme/en-home.png)
-### 📖 沉浸式讲义
-> 结合真实痛点与实战项目(如 Project 01)的深度解析,提供沉浸式的阅读与学习体验。
+### 沉浸式讲座
+> 深入剖析真实痛点,配合动手项目(如项目 01),带来沉浸式学习体验。
-![课程讲义预览](./docs/public/screenshots/readme/zh-lecture-01.png)
+![课程讲座预览](../../docs/public/screenshots/readme/en-lecture-01.png)
-### 🗂️ 开箱即用的资料库
-> 整理了可直接复用的中文模板与参考配置,专治 AI Agent 在多轮开发中的“做一半停下”、“上下文断裂”等疑难杂症。
+### 即用资源库
+> 专为解决多轮 AI 代理开发中的常见问题而设计的模板和参考配置,例如上下文丢失和过早完成任务。
-![扩展资料库预览](./docs/public/screenshots/readme/zh-resources.png)
+![资源库预览](../../docs/public/screenshots/readme/en-resources.png)
-## PDF 构建与 Release 流水线
+## PDF 课程手册
-仓库里现在已经补上了课程 PDF 的构建链路。
+本仓库包含课程内容的 PDF 构建流水线。
-- 本地执行 `npm run pdf:build`,会生成当前脚本配置的课程 PDF。
-- 输出目录是 `artifacts/pdfs/`。
-- 如果需要刷新 README 里的截图,执行 `npm run screenshots:readme`。
-- GitHub Actions 工作流 [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) 可以自动构建 PDF,并把产物上传到 GitHub Release。
+- 运行 `npm run pdf:build` 可在本地生成英文和中文 PDF。
+- 输出文件写入 `artifacts/pdfs/` 目录。
+- 如果你想刷新 README 预览图片,可运行 `npm run screenshots:readme`。
+- GitHub Actions 工作流 [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) 可以构建 PDF 并发布到 GitHub Releases。
---
-## 模型很强,但 Harness 让它靠谱
+## 模型很聪明,Harness 让它可靠
-有一个很多人交过学费才明白的事实:**世界上最强的模型,如果没有一个合适的工作环境,依然会在真实工程任务中翻车。**
+大多数人都曾付出过惨痛代价才认识到一个残酷的事实:**世界上最强大的模型,如果你不为它构建合适的环境,它在真正的工程任务上依然会失败。**
-你多半见过这种情况。你给 Claude 或 GPT 一个任务,它看起来干得不错——读文件、写代码、很努力。然后出问题了。它跳过了一个步骤。它搞坏了一个测试。它说"完成了"但实际上什么都没跑通。你花在收拾烂摊子上的时间比自己做还多。
+你可能亲身经历过。你给 Claude 或 GPT 一个仓库中的任务。开始一切顺利——读文件、写代码、看起来很高效。然后出了问题。它跳过了一个步骤。它破坏了一个测试。它说"完成了",但实际上什么都不能用。你花在清理上的时间比自己做还多。
-这不是模型的问题,这是 harness 的问题。
+这不是模型的问题。这是 Harness 的问题。
-证据很明确。Anthropic 做过一组对照实验:同一个模型(Opus 4.5),同一段提示词("做一个 2D 复古游戏编辑器")。没有 harness 的情况下,20 分钟花了 $9,结果游戏核心功能跑不起来。加上完整 harness(planner + generator + evaluator 三 agent 架构),6 小时花了 $200,做出来的游戏可以正常游玩。模型没换,换的是 harness。
+证据很明确。Anthropic 做了一个对照实验:同一个模型(Opus 4.5),同一个提示词("构建一个 2D 复古游戏编辑器")。没有 Harness 时,它在 20 分钟内花了 9 美元,产出了一个不能用的东西。有了完整的 Harness(规划器 + 生成器 + 评估器),它在 6 小时内花了 200 美元,构建了一个你真的能玩的游戏。模型没有变。变的是 Harness。
-OpenAI 用 Codex 也得出了同样结论:在一个 harness 搭得好的仓库里,同一个模型从"不可靠"变成"可靠"——不是"好了一点",是质变。
+OpenAI 在 Codex 上也报告了同样的事情:在一个良好 Harness 的仓库中,同一个模型从"不可靠"变成了"可靠"。这不是边际提升——这是质变。
-**这门课教你怎么搭建那个环境。**
+**这门课程教你如何构建那个环境。**
```text
- HARNESS 模式
- ============
-
- 你 --> 给出任务 --> agent 读取 harness 文件 --> agent 开始执行
- |
- harness 管控每一步:
- |
- +--> 指令:做什么、按什么顺序
- +--> 范围:一次一个功能,不越界
- +--> 状态:进度日志、功能清单、git 历史
- +--> 验证:测试、lint、类型检查、冒烟测试
- +--> 周期:开工时初始化,结束时留交接
- |
- v
- agent 只在验证通过后
- 才会停下来
+ HARNESS 模式
+ =============
+
+ 你 --> 给出任务 --> 代理读取 harness 文件 --> 代理执行
+ |
+ harness 管控每一个步骤:
+ |
+ +--> 指令:做什么,按什么顺序
+ +--> 范围:一次一个功能,不越界
+ +--> 状态:进度日志、功能列表、git 历史
+ +--> 验证:测试、lint、类型检查、冒烟测试
+ +--> 生命周期:开始时初始化,结束时清理状态
+ |
+ v
+ 代理只在验证通过时
+ 才会停止
```
---
-## Harness Engineering 到底是什么
+## Harness Engineering 到底是什么意思
-Harness engineering 是围绕模型搭建一整套工作环境,让它产出可靠的结果。不只是写更好的提示词,而是设计模型运行所在的系统。
+Harness Engineering 是围绕模型构建一个完整的工作环境,使其产生可靠的结果。它不是关于写更好的提示词。它是关于设计模型运行其中的系统。
-一个 harness 包含五个子系统:
+一个 Harness 有五个子系统:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ HARNESS │
+ │ HARNESS 系统 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ 指令 │ │ 状态 │ │ 验证 │ │
+ │ │ 指令 │ │ 状态 │ │ 验证 │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ 测试 + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ 类型检查 │ │
+ │ │ feature_list │ │ git log │ │ 冒烟测试 │ │
+ │ │ docs/ │ │ 会话交接 │ │ 端到端流水线 │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ 范围 │ │ 会话生命周期 │ │
+ │ │ 范围 │ │ 会话生命周期 │ │
│ │ │ │ │ │
- │ │ 一次一个 │ │ 开工时跑 init.sh │ │
- │ │ 功能 │ │ 结束时跑清理检查清单 │ │
- │ │ 显式的完成 │ │ 给下次会话留交接笔记 │ │
- │ │ 定义 │ │ 只在可以安全恢复时才 commit │ │
+ │ │ 一次一个功能 │ │ 开始时运行 init.sh │ │
+ │ │ 明确完成的 │ │ 结束时执行清理检查清单 │ │
+ │ │ 定义 │ │ 为下一次会话留下交接说明 │ │
+ │ │ │ │ 只在安全可恢复时才提交 │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
模型决定写什么代码。
- Harness 管控什么时候写、在哪里写、怎么写。
- Harness 不会让模型变聪明。
- 它让模型的产出变可靠。
+ HARNESS 管控何时、何地以及如何写。
+ Harness 不会让模型更聪明。
+ 它让模型的输出更可靠。
```
每个子系统各司其职:
-- **指令** — 告诉 agent 做什么、按什么顺序、开工前先读什么。不是一个巨大的文件,而是渐进式展开的结构,agent 按需导航。
-- **状态** — 跟踪做了什么、正在做什么、下一步是什么。持久化到磁盘,下次会话从上次停下的地方继续。
-- **验证** — 只有通过的测试套件才算数。agent 不能没有可运行的证据就说"做完了"。
-- **范围** — 约束 agent 一次只做一个功能。不多做,不少做,不偷偷改功能清单掩盖未完成的工作。
-- **会话生命周期** — 开始时初始化,结束时清理,给下次会话留一条干净的重启路径。
+- **指令**——告诉代理做什么、按什么顺序、开始前读什么。不是一个巨大的文件,而是一个渐进式披露结构,代理按需导航。
+- **状态**——追踪已完成的工作、正在进行的工作和下一步。持久化到磁盘,使下一次会话可以准确地从上次离开的地方继续。
+- **验证**——只有通过的测试套件才算数。代理不能在没有可运行证据的情况下宣布完成。
+- **范围**——将代理限制在一次只做一个功能。不越界。不同时做三个半成品。不重写功能列表来掩盖未完成的工作。
+- **会话生命周期**——开始时初始化。结束时清理。为下一次会话留下干净的重启路径。
---
-## 为什么要有这门课
+## 为什么会有这门课程
-问题不是"模型能不能写代码"。能写。问题是:**能不能在真实的仓库里,跨越多次会话,不需要人一直盯着,就可靠地完成真实的工程任务?**
+问题不是"模型能不能写代码?"它们能。问题是:**它们能否在没有持续人工监督的情况下,在真实的仓库中、跨多个会话、可靠地完成真正的工程任务?**
-现在的答案是:没有 harness 就不行。
+目前,答案是:没有 Harness 就不行。
```text
- 没有 HARNESS 有 HARNESS
- ============== ===========
-
- 会话 1: agent 写代码 会话 1: agent 读指令
- agent 搞坏测试 agent 跑 init.sh
- agent 说"做完了" agent 一次只做一个功能
- 你手动修复 agent 验证后才说完成
- agent 更新进度日志
- 会话 2: agent 从头开始 agent 干净地 commit
- agent 没有上次
- 的记忆 会话 2: agent 读进度日志
- agent 重新做一遍 agent 从上次停下的地方继续
- 或者做了完全不同的东西 agent 继续未完成的功能
- 你再修一次 你是审查,不是救火
-
- 结果:你花的时间比 结果:agent 干活,
+ 没有 HARNESS 有 HARNESS
+ ============== ===========
+
+ 会话 1:代理写代码 会话 1:代理读取指令
+ 代理破坏了测试 代理运行 init.sh
+ 代理说"完成了" 代理只做一个功能
+ 你手动修复 代理在声明完成前先验证
+ 代理更新进度日志
+ 会话 2:代理从零开始 代理提交干净的状态
+ 代理不记得之前
+ 发生了什么 会话 2:代理读取进度日志
+ 代理重做已完成的工作 代理准确从上次离开处继续
+ 或者做完全不同的事情 代理继续未完成的功能
+ 你再次修复 你是审查者,不是救援者
+
+ 结果:你花的时间比 结果:代理完成工作,
自己做还多 你验证结果
```
-课程真正关心的问题:
+这门课程真正关心的问题:
-- 哪些 harness 设计会提升任务完成率?
-- 哪些设计会减少返工和错误完成?
-- 哪些机制能让长时任务更稳定地持续推进?
-- 哪些结构能让系统在多轮 agent 运行后仍然可维护?
+- 哪些 Harness 设计能提高任务完成率?
+- 哪些设计能减少返工和错误完成?
+- 哪些机制能让长时间运行的任务稳步推进?
+- 哪些结构能让系统在多次代理运行后仍然可维护?
---
-## 课程大纲与文档
+## 课程内容与文档
-关于完整的课程内容,请直接访问 **[官方文档站点 (VitePress)](https://walkinglabs.github.io/learn-harness-engineering/zh/)**。
+完整的课程材料,请访问**[文档网站](https://walkinglabs.github.io/learn-harness-engineering/)**。
-本课程分为三个主要部分:
+课程分为三个部分:
-1. **讲义 (Lectures)**:12 个概念单元,深度解析 Harness 设计的理论基础。
-2. **项目 (Projects)**:6 个循序渐进的实战项目,带你从零开始搭建可靠的 Agent 工作环境。
-3. **资料库 (Resource Library)**:开箱即用的中英文模板(如 `AGENTS.md`、`feature_list.json`、`init.sh`),今天就可以直接复制到你自己的项目中使用。
+1. **讲座**:12 个概念单元,讲解 Harness Engineering 背后的理论。
+2. **项目**:6 个动手项目,你将从零构建一个代理工作空间。
+3. **资源库**:可直接使用的模板(`AGENTS.md`、`feature_list.json`、`init.sh` 等),今天就能用在你自己的仓库中。
---
-## 快速开始:今天就能改善你的 agent
+## 快速开始:今天就改善你的代理
-不用读完 12 个讲义再动手。如果你已经在用 coding agent 做项目,下面这些能立刻改善效果。
+你不需要先读完所有 12 个讲座才能开始获得价值。如果你已经在真实项目中使用编程代理,以下是如何立刻改善它。
-思路很简单:不是光写提示词,而是在仓库里放一组结构化的文件——告诉 agent 该做什么、做完了什么、怎么验证。这些文件就放在项目里,每次会话都从同一个状态开始。
+思路很简单:与其只写提示词,不如给你的代理一组结构化文件,定义做什么、已做了什么、以及如何验证工作。这些文件存在于你的仓库中,所以每次会话都从相同的状态开始。
```text
你的项目根目录
- ├── AGENTS.md <-- agent 的操作手册
- ├── CLAUDE.md <-- (备选,如果你用 Claude Code)
- ├── init.sh <-- 一条命令完成安装 + 验证 + 启动
- ├── feature_list.json <-- 有哪些功能、哪些已完成
- ├── claude-progress.md <-- 每次会话做了什么
- └── src/ <-- 你的代码
+ ├── AGENTS.md <-- 代理的操作手册
+ ├── CLAUDE.md <-- (替代方案,如果你使用 Claude Code)
+ ├── init.sh <-- 运行安装 + 验证 + 启动
+ ├── feature_list.json <-- 哪些功能存在,哪些已完成
+ ├── claude-progress.md <-- 每次会话发生了什么
+ └── src/ <-- 你的实际代码
```
-**第一步.** 直接前往 [资料库](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) 拿到上述文件的模板代码,然后放进你的项目根目录。
-
-就这么简单。四个文件,最小起步就够了。你的 Agent 表现会比光靠一段提示词稳定得多。
+从[资源库](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)获取入门模板,放入你的项目。就这样。四个文件,你的代理会话就会比仅靠提示词稳定得多。
---
-## 贯穿项目:一个真实的应用
+## 毕业项目:一个真实的应用
-全部 6 个课程项目都围绕同一个产品:**一个基于 Electron 的个人知识库桌面应用**。
+全部六个课程项目围绕同一个产品展开:**一个基于 Electron 的个人知识库桌面应用**。
```text
┌─────────────────────────────────────────────────────┐
- │ 知识库桌面应用 │
+ │ 知识库桌面应用 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ 文档列表 │ │ 问答面板 ││
+ │ │ 文档列表 │ │ 问答面板 ││
│ │ │ │ ││
- │ │ doc-001.md │ │ 问:什么是 harness eng? ││
- │ │ doc-002.md │ │ 答:围绕 agent 模型搭建的 ││
- │ │ doc-003.md │ │ 工作环境... ││
- │ │ ... │ │ [引用:doc-002.md] ││
+ │ │ doc-001.md │ │ 问:什么是 Harness Eng? ││
+ │ │ doc-002.md │ │ 答:围绕代理模型构建的 ││
+ │ │ doc-003.md │ │ 环境... ││
+ │ │ ... │ │ [引用: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ 状态栏:42 篇文档 | 38 篇已索引 | 上次同步 3分钟 ││
+ │ │ 状态栏:42 篇文档 | 38 篇已索引 | 上次同步 3 分钟前 ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
核心功能:
├── 导入本地文档
├── 管理文档库
- ├── 处理与索引文档
- ├── 对导入内容发起 AI 问答
- └── 返回带引用且可追溯的回答
+ ├── 处理和索引文档
+ ├── 基于导入内容运行 AI 驱动的问答
+ └── 返回带引用的有据答案
```
-选择这个项目是因为它同时具备:很强的实际价值感、足够真实的产品复杂度、以及很适合观察 harness 优化前后的效果差异。
+选择这个项目是因为它兼具实用价值、足够的真实产品复杂度,以及一个适合观察 Harness 改进前后对比的良好场景。
-每个课程项目的 starter/solution 是这个 Electron 应用在对应演化阶段的完整副本。P(N+1) 的 starter 从 P(N) 的 solution 衍生而来——应用跟着你的 harness 技能一起进化。
+每个课程项目的 starter/solution 都是此 Electron 应用在相应进化阶段的完整副本。P(N+1) 的 starter 派生自 P(N) 的 solution——随着你的 Harness 技能增长,应用也在进化。
---
## 学习路径
-这门课按顺序来效果最好,每一阶段都建立在前一个的基础上。
+课程按顺序设计。每个阶段建立在前一个之上。
```text
- 阶段 1:看到问题 阶段 2:组织仓库
- =================== ===================
+ 阶段 1:看到问题 阶段 2:结构化仓库
+ ======================= ==========================
- L01 模型强 ≠ 执行可靠 L03 仓库作为唯一
- 事实来源
- L02 Harness 到底是什么
- L04 把指令拆分到
- | 不同文件里
- v
- P01 只写提示词 |
- vs 定好规则 v
- P02 agent 可读的工作空间
+ L01 强模型 ≠ 可靠执行 L03 仓库作为唯一的
+ 真实来源
+ L02 Harness 到底意味着什么
+ L04 将指令分散到多个文件,
+ 而不是一个巨大文件
+ |
+ v |
+ P01 仅提示词 vs. v
+ 规则优先对比
+ P02 代理可读的工作空间
- 阶段 3:连接会话 阶段 4:反馈与范围
- =================== ===================
+ 阶段 3:连接会话 阶段 4:反馈与范围
+ ========================== =========================
- L05 让跨会话任务 L07 划清任务边界
- 保持连续
- L08 功能清单作为
- L06 每次开工前 harness 原语
- 先初始化
- |
- | v
- v P04 运行反馈修正
- P03 多会话连续性 agent 行为
+ L05 让上下文跨会话保持活跃 L07 划清任务边界
+ L06 每次代理会话前初始化 L08 功能列表作为 Harness
+ 基本单元
+ | |
+ v v
+ P03 多会话连续性 P04 运行时反馈
+ 纠正代理行为
- 阶段 5:验证 阶段 6:全部串起来
- =================== ===================
- L09 防止 agent 提前 L11 让 agent 运行
- 宣告完成 过程可观测
+ 阶段 5:验证 阶段 6:整合一切
+ ===================== ============================
- L10 跑通完整流程 L12 每次会话结束
- 才算真的验证 前做好交接
+ L09 阻止代理过早 L11 让代理的运行时
+ 宣布完成 可观测
+ L10 完整流水线运行 = L12 每次会话结束时
+ 真正的验证 干净交接
| |
v v
- P05 agent 自己验证工作 P06 搭建完整 harness
- (综合项目)
+ P05 代理验证自己的工作 P06 构建完整的 Harness
+ (毕业项目)
```
-每个阶段大约一周(兼职节奏)。想快的话,前三个阶段一个周末就能跑完。
+如果你是业余时间学习,每个阶段大约需要一周。如果你想加快速度,阶段 1-3 可以在一个长周末完成。
---
## 课程大纲
-### 讲义 — 12 个概念单元,每个只回答一个核心问题
+### 讲座——12 个概念单元,每个回答一个核心问题
-*点击访问 [文档站点](https://walkinglabs.github.io/learn-harness-engineering/zh/) 阅读全部讲义。*
+*在[文档网站](https://walkinglabs.github.io/learn-harness-engineering/)上阅读每讲完整文本。*
-| 讲义 | 核心问题 | 关键概念 |
-| ---- | -------- | -------- |
-| [L01](./docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 模型能力强,不等于执行可靠 | 基准测试与真实工程之间的能力鸿沟 |
-| [L02](./docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md) | Harness 到底是什么 | 五个子系统:指令、状态、验证、范围、生命周期 |
-| [L03](./docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 让仓库成为唯一事实来源 | agent 看不到的东西,对它来说就不存在 |
-| [L04](./docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 为什么一个巨大的指令文件会失败 | 渐进式展开:给地图,不给百科全书 |
-| [L05](./docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 为什么长时任务会丢失上下文 | 把进度持久化到磁盘,从停下的地方继续 |
-| [L06](./docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 为什么初始化需要单独一个阶段 | agent 开始工作前先验证环境是否健康 |
-| [L07](./docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 为什么 agent 会多做或少做 | 一次一个功能,显式的完成定义 |
-| [L08](./docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 为什么功能清单是 harness 原语 | 机器可读的范围边界,agent 无法忽略 |
-| [L09](./docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 为什么 agent 会提前宣告完成 | 验证缺口:自信 ≠ 正确 |
-| [L10](./docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 为什么端到端测试会改变结果 | 只有跑通完整流程才算真正验证 |
-| [L11](./docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 为什么可观测性属于 harness | 看不到 agent 做了什么,就修不了它搞坏的东西 |
-| [L12](./docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 为什么每次会话都要留干净状态 | 下次会话的成功,取决于这次会话的清理 |
+| 讲次 | 问题 | 核心观点 |
+|------|------|----------|
+| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 为什么强模型在真实任务上仍然会失败? | 基准测试与真实工程之间的能力差距 |
+| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" 到底是什么意思? | 五个子系统:指令、状态、验证、范围、生命周期 |
+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 为什么仓库必须是唯一的真实来源? | 如果代理看不到它,它就不存在 |
+| [L04](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 为什么一个巨大的指令文件会失败? | 渐进式披露:给一张地图,不是一本百科全书 |
+| [L05](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 为什么长时间运行的任务会失去连续性? | 将进度持久化到磁盘;从上次离开处继续 |
+| [L06](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 为什么初始化需要单独的阶段? | 在代理开始工作前验证环境是否健康 |
+| [L07](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 为什么代理会越界和欠完成? | 一次一个功能;明确的完成定义 |
+| [L08](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 为什么功能列表是 Harness 基本单元? | 代理无法忽视的机器可读范围边界 |
+| [L09](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 为什么代理过早宣布完成? | 验证缺口:信心 ≠ 正确 |
+| [L10](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 为什么端到端测试能改变结果? | 只有完整的流水线运行才算真正的验证 |
+| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 为什么可观测性应该属于 Harness? | 如果你看不到代理做了什么,你就无法修复它破坏的东西 |
+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 为什么每次会话都必须留下干净的状态? | 下一次会话的成功取决于这一次会话的清理 |
-### 项目 — 6 个实践项目,把讲义方法落实到同一个 Electron 应用上
+### 项目——6 个动手项目,将讲座方法应用到同一个 Electron 应用上
| 项目 | 你要做什么 | Harness 机制 |
-| ---- | ---------- | ------------ |
-| [P01](./docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md) | 跑两次同样的任务:只写提示词 vs 定好规则 | 最小 harness:AGENTS.md + init.sh + feature_list.json |
-| [P02](./docs/zh/projects/project-02-agent-readable-workspace/index.md) | 重组项目结构,让 agent 能读懂 | agent 可读的工作空间 + 持久化状态文件 |
-| [P03](./docs/zh/projects/project-03-multi-session-continuity/index.md) | 让 agent 关掉再打开还能接着干 | 进度日志 + 会话交接 + 多会话连续性 |
-| [P04](./docs/zh/projects/project-04-incremental-indexing/index.md) | 防止 agent 做多了或做少了 | 运行反馈 + 范围控制 + 增量索引 |
-| [P05](./docs/zh/projects/project-05-grounded-qa-verification/index.md) | 让 agent 自己验证自己的工作 | 自验证 + 带引用的问答 + 基于证据的完成判定 |
-| [P06](./docs/zh/projects/project-06-runtime-observability-and-debugging/index.md) | 从零搭建一套完整的 harness(综合项目) | 完整 harness:全部机制 + 可观测性 + 消融实验 |
+|------|-----------|--------------|
+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | 同一个任务运行两次:仅提示词 vs. 规则优先 | 最小 Harness:AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/projects/project-02-agent-readable-workspace/index.md) | 重构仓库使代理可读 | 代理可读工作空间 + 持久化状态文件 |
+| [P03](../../docs/projects/project-03-multi-session-continuity/index.md) | 让代理从上次离开处继续 | 进度日志 + 会话交接 + 多会话连续性 |
+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | 阻止代理做得太多或太少 | 运行时反馈 + 范围控制 + 增量索引 |
+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | 让代理验证自己的工作 | 自验证 + 有据问答 + 基于证据的完成 |
+| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | 从零构建完整的 Harness(毕业项目) | 完整 Harness:所有机制 + 可观测性 + 消融实验 |
```text
项目演进
- ========
+ =================
- P01 只写提示词 vs 定好规则 你看到问题
+ P01 仅提示词 vs. 规则优先 你看到问题
|
v
- P02 agent 可读的工作空间 你重组仓库
+ P02 代理可读工作空间 你重构仓库
|
v
- P03 多会话连续性 你连接会话
+ P03 多会话连续性 你连接会话
|
v
- P04 运行反馈与范围控制 你加上反馈循环
+ P04 运行时反馈与范围 你添加反馈循环
|
v
- P05 自验证 你让 agent 检查自己
+ P05 自验证 你让代理检查自己
|
v
- P06 完整 harness(综合项目) 你搭建完整系统
+ P06 完整 Harness(毕业项目) 你构建完整系统
每个项目的 solution 成为下一个项目的 starter。
- 应用跟着你的 harness 技能一起进化。
+ 应用在演进。你的 Harness 技能随之增长。
```
-### 资料库
+### 资源库
-- [中文资料库](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
-- [英文资料库](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — English templates, checklists, and method references
+- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references
+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考
- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス
- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료
@@ -383,87 +378,87 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可
---
-## Agent 会话生命周期
+## 代理会话生命周期
-这门课的一个核心理念:**agent 的会话应该遵循结构化的生命周期,而不是自由发挥。** 它长这样:
+这门课程的核心观点之一:**代理的会话应该遵循结构化的生命周期,而不是放任自流。** 如下所示:
```text
- AGENT 会话生命周期
- =================
+ 代理会话生命周期
+ ======================
┌──────────────────────────────────────────────────────────────────┐
- │ 开工 │
+ │ 启动 │
│ │
- │ 1. agent 读取 AGENTS.md / CLAUDE.md │
- │ 2. agent 运行 init.sh(安装、验证、健康检查) │
- │ 3. agent 读取 claude-progress.md(上次做了什么) │
- │ 4. agent 读取 feature_list.json(做完哪些、接下来做哪个) │
- │ 5. agent 检查 git log(最近的改动) │
+ │ 1. 代理读取 AGENTS.md / CLAUDE.md │
+ │ 2. 代理运行 init.sh(安装、验证、健康检查) │
+ │ 3. 代理读取 claude-progress.md(上次发生了什么) │
+ │ 4. 代理读取 feature_list.json(哪些完成,哪些待做) │
+ │ 5. 代理检查 git log(最近的变更) │
│ │
│ 选择 │
│ │
- │ 6. agent 选定且只选一个未完成的功能 │
- │ 7. agent 只做这一个功能 │
+ │ 6. 代理精确选择一个未完成的功能 │
+ │ 7. 代理只做那个功能 │
│ │
│ 执行 │
│ │
- │ 8. agent 实现这个功能 │
- │ 9. agent 运行验证(测试、lint、类型检查) │
- │ 10. 如果验证失败:修复后重跑 │
+ │ 8. 代理实现功能 │
+ │ 9. 代理运行验证(测试、lint、类型检查) │
+ │ 10. 如果验证失败:修复并重新运行 │
│ 11. 如果验证通过:记录证据 │
│ │
│ 收尾 │
│ │
- │ 12. agent 更新 claude-progress.md │
- │ 13. agent 更新 feature_list.json │
- │ 14. agent 记录还没做完和还没验证的东西 │
- │ 15. agent commit(只在可以安全恢复时) │
- │ 16. agent 给下次会话留干净的重启路径 │
+ │ 12. 代理更新 claude-progress.md │
+ │ 13. 代理更新 feature_list.json │
+ │ 14. 代理记录仍然有问题或未验证的内容 │
+ │ 15. 代理提交(仅在安全可恢复时) │
+ │ 16. 代理为下一次会话留下干净的重启路径 │
│ │
└──────────────────────────────────────────────────────────────────┘
- Harness 管控这个生命周期里的每一次状态转换。
+ Harness 管控这个生命周期中的每一次转换。
模型决定每一步写什么代码。
- 没有 harness 时,第 9 步变成"agent 说看起来没问题"。
- 有 harness 时,第 9 步是"测试通过、lint 干净、类型检查通过"。
+ 没有 Harness,第 9 步变成"代理说看起来没问题"。
+ 有了 Harness,第 9 步是"测试通过,lint 干净,类型检查通过"。
```
---
## 适合谁
-这门课适合:
+本课程适合:
-- 已经在使用 coding agent、希望提升稳定性和质量的工程师
-- 想系统理解 harness 设计的研究者或构建者
-- 需要理解"环境设计如何影响 agent 表现"的技术负责人
+- 已经在使用编程代理、希望获得更好稳定性和质量的工程师
+- 希望系统理解 Harness 设计的研究者或构建者
+- 需要了解环境设计如何影响代理性能的技术负责人
-这门课不适合:
+本课程不适合:
-- 只想要一个零代码 AI 入门的人
-- 只关心 prompt,而不打算做真实实现的人
-- 不准备让 agent 在真实仓库里工作的学习者
+- 寻找零代码 AI 入门的人
+- 只关心提示词、不打算构建实际实现的人
+- 不准备让代理在真实仓库中工作的学习者
---
## 环境要求
-这是一门真正需要动手跑 coding agent 的课程。
+这是一门你需要实际运行编程代理的课程。
-你至少需要具备一个这类工具:
+你至少需要以下工具之一:
- Claude Code
- Codex
-- 其他支持文件编辑、命令执行、多步任务的 IDE / CLI coding agent
+- 其他支持文件编辑、命令执行和多步骤任务的 IDE 或 CLI 编程代理
-课程默认你可以:
+本课程假设你能够:
- 打开本地仓库
-- 允许 agent 编辑文件
-- 允许 agent 运行命令
-- 检查输出并重复执行任务
+- 允许代理编辑文件
+- 允许代理运行命令
+- 检查输出并重新运行任务
-如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程项目。
+如果你没有这样的工具,你仍然可以阅读课程内容,但无法按设计完成项目。
---
@@ -473,35 +468,35 @@ Harness engineering 是围绕模型搭建一整套工作环境,让它产出可
```sh
npm install
-npm run docs:dev # 开发服务器(热更新)
+npm run docs:dev # 带热重载的开发服务器
npm run docs:build # 生产构建
-npm run docs:preview # 预览构建结果
+npm run docs:preview # 预览构建后的站点
```
-然后在浏览器里打开 VitePress 输出的本地地址即可。
+然后在浏览器中打开 VitePress 输出的本地 URL。
---
-## 先修要求
+## 先决条件
必需:
- 熟悉终端、git 和本地开发环境
-- 至少会读写一种常见应用栈中的代码
-- 有基本的软件调试经验,知道如何看日志、测试和运行行为
-- 能投入足够时间完成偏实现型的课程任务
+- 能够使用至少一种常见应用技术栈读写代码
+- 基本的软件调试经验(阅读日志、测试和运行时行为)
+- 足够的时间投入到以实现为核心的课程中
-有帮助但非强制:
+有帮助但非必需:
-- 用过 Electron、桌面应用或本地优先工具
-- 有测试、日志、软件架构方面的经验
-- 已经接触过 Codex、Claude Code 或类似 coding agent
+- 有 Electron、桌面应用或本地优先工具的经验
+- 有测试、日志或软件架构方面的背景
+- 之前接触过 Codex、Claude Code 或类似的编程代理
---
-## 核心参考资料
+## 核心参考
-主参考:
+主要参考:
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
@@ -512,7 +507,7 @@ npm run docs:preview # 预览构建结果
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-完整分层参考列表见 [`docs/zh/resources/reference/`](./docs/zh/resources/reference/index.md)。
+完整分层参考列表请见 [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md)。
---
@@ -520,56 +515,59 @@ npm run docs:preview # 预览构建结果
```text
learn-harness-engineering/
-├── docs/ # VitePress 文档站
-│ ├── index.md # 语言选择页
-│ ├── zh/ # 中文完整内容
-│ │ ├── lectures/ # 12 个讲义(index.md + code/ 示例)
-│ │ ├── projects/ # 6 个项目
-│ │ └── resources/ # 模板、参考、高级资源包
-│ └── en/ # 英文完整内容
-│ ├── lectures/ # 12 lectures
-│ ├── projects/ # 6 projects
-│ └── resources/ # templates, references, advanced pack
+├── docs/ # VitePress 文档站点
+│ ├── lectures/ # 12 个讲座(index.md + code/ 示例)
+│ │ ├── lecture-01-*/
+│ │ ├── lecture-02-*/
+│ │ └── ... (共 12 个)
+│ ├── projects/ # 6 个项目描述
+│ │ ├── project-01-*/
+│ │ └── ... (共 6 个)
+│ └── resources/ # 多语言模板和参考
+│ ├── en/ # 英文模板、检查清单、指南
+│ ├── zh/ # 中文模板、检查清单、指南
+│ ├── ru/ # 俄文模板、检查清单、指南
+│ └── vi/ # 越南文模板、检查清单、指南
├── projects/
-│ ├── shared/ # Electron + TypeScript + React 共享基础
-│ └── project-NN/ # 每个项目的 starter/ 和 solution/
-├── skills/ # 可复用的 AI agent 技能
-│ └── harness-creator/ # Harness 工程技能
+│ ├── shared/ # 共享的 Electron + TypeScript + React 基础
+│ └── project-NN/ # 每个项目的 starter/ 和 solution/ 目录
+├── skills/ # 可复用的 AI 代理技能
+│ └── harness-creator/ # Harness Engineering 技能
├── package.json # VitePress + 开发工具
-└── CLAUDE.md # Claude Code 指令文件
+└── CLAUDE.md # 本仓库的 Claude Code 指令
```
---
## 课程组织方式
-- 每个讲义聚焦一个问题
-- 整门课配套 6 个项目
-- 每个项目都要求 agent 真正干活
-- 每个项目都要做弱 harness / 强 harness 对照
-- 我们关心的是效果变化,而不是"写了多少说明文档"
+- 每个讲座聚焦一个问题
+- 课程包含 6 个项目
+- 每个项目都要求代理做真实的工作
+- 每个项目都比较弱 Harness 和强 Harness 的结果
+- 重要的是可测量的差异,不是写了多少文档
---
-## Skills
+## 技能
-本仓库还包含可复用的 AI Agent 技能(Skills),你可以将它们直接安装到你的 IDE 或 Agent 工作区中。
+本仓库还包含可复用的 AI 代理技能,你可以直接安装到你的 IDE 或代理工作空间中。
-- [**harness-creator**](./skills/harness-creator/):帮助你在几分钟内为自己的项目搭建一套生产级 harness(脚手架)的技能。
+- [**harness-creator**](../../skills/harness-creator/):一个帮助你在几分钟内为自己的项目搭建生产级别 Harness 的技能。
---
## 其他课程
-我们的团队还制作了其他课程!请查看:
+我们的团队还创建了其他课程!欢迎查看:
[![Hands-on Modern RL](https://img.shields.io/badge/HANDS--ON_MODERN_RL-0052cc?style=for-the-badge)](https://github.com/walkinglabs/hands-on-modern-rl)
-**Hands-on Modern RL**: An open-source, hands-on curriculum bridging the gap from basic RL concepts to LLM alignment, RLVR, and advanced Agentic systems.
+**Hands-on Modern RL**:一个开源的动手课程,从基础强化学习概念到 LLM 对齐、RLVR 和高级 Agentic 系统,架起理论与实践的桥梁。
---
-## Star History
+## Star 历史
[![Star History Chart](https://api.star-history.com/svg?repos=walkinglabs/learn-harness-engineering&type=date&legend=top-left)](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)
@@ -577,4 +575,4 @@ learn-harness-engineering/
## 致谢
-本课程的灵感和部分思路来自 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) —— 一个从零开始搭建 agent 的渐进式教程,从单个循环到隔离的自主执行。
+本课程受到 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) 的启发并借鉴了其中的理念——那是一份从单循环到隔离自主执行的渐进式代理构建指南。
diff --git a/README-DE.md b/README-DE.md
index 74b818f..87a05a1 100644
--- a/README-DE.md
+++ b/README-DE.md
@@ -84,22 +84,22 @@ OpenAI berichtete dasselbe mit Codex: in einem gut geharnischten Repository wech
**Dieser Kurs bringt Ihnen bei, wie Sie diese Umgebung aufbauen.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ DAS HARNESS-MUSTER
+ ==================
+
+ Sie --> Aufgabe geben --> Agent liest Harness-Dateien --> Agent führt aus
+ |
+ Harness steuert jeden Schritt:
+ |
+ +--> Anweisungen: was zu tun ist, in welcher Reihenfolge
+ +--> Umfang: ein Feature nach dem anderen, keine Übergriffe
+ +--> Zustand: Fortschrittslog, Feature-Liste, Git-Verlauf
+ +--> Verifizierung: Tests, Lint, Typprüfung, Smoke-Runs
+ +--> Lebenszyklus: Initialisierung am Start, sauberer Zustand am Ende
+ |
+ v
+ Agent stoppt nur, wenn
+ Verifizierung bestanden ist
```
---
@@ -112,32 +112,32 @@ Ein Harness hat fünf Subsysteme:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ DAS HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Anweisungen │ │ Zustand │ │ Verifizierung │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ Tests + Lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ Typprüfung │ │
+ │ │ feature_list │ │ git log │ │ Smoke-Runs │ │
+ │ │ docs/ │ │ Session-Übg. │ │ E2E-Pipeline │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Umfang │ │ Session-Lebenszyklus │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ ein Feature │ │ init.sh am Start │ │
+ │ │ nach dem and.│ │ Clean-State-Checkliste am Ende │ │
+ │ │ Definition │ │ Übergabenotiz für nächste Session │ │
+ │ │ von Fertig │ │ Commit nur wenn sicher fortsetzbar │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ Das MODELL entscheidet, welcher Code geschrieben wird.
+ Das HARNESS steuert, wann, wo und wie es geschrieben wird.
+ Das Harness macht das Modell nicht schlauer.
+ Es macht die Ausgabe des Modells zuverlässig.
```
Jedes Subsystem hat eine Aufgabe:
@@ -157,24 +157,24 @@ Die Frage ist nicht „Können Modelle Code schreiben?" Sie können. Die Frage i
Im Moment lautet die Antwort: nicht ohne ein Harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ OHNE HARNESS MIT HARNESS
+ =========== ===========
+
+ Session 1: Agent schreibt Code Session 1: Agent liest Anweisungen
+ Agent zerstört Tests Agent führt init.sh aus
+ Agent sagt "fertig" Agent arbeitet an einem Feature
+ Sie reparieren manuell Agent verifiziert vor Fertig-Meldung
+ Agent aktualisiert Fortschrittslog
+ Session 2: Agent startet neu Agent committet sauberen Zustand
+ Agent hat keine Erinnerung
+ an vorherige Session Session 2: Agent liest Fortschrittslog
+ Agent macht Arbeit neu Agent setzt genau dort fort
+ oder macht etwas ganz anderes Agent bearbeitet das unfertige Feature
+ Sie reparieren wieder Sie überprüfen, statt zu retten
+
+ Ergebnis: Sie verbringen mehr Zeit Ergebnis: Agent erledigt die Arbeit,
+ mit Aufräumen, als wenn Sie verifizieren das Ergebnis
+ Sie es selbst gemacht hätten
```
Die Fragen, die dieser Kurs wirklich interessieren:
@@ -205,7 +205,7 @@ Sie müssen nicht alle 12 Vorlesungen lesen, bevor Sie einen Nutzen ziehen. Wenn
Die Idee ist einfach: Anstatt nur Prompts zu schreiben, geben Sie Ihrem Agenten einen Satz strukturierter Dateien, die definieren, was zu tun ist, was bereits erledigt ist und wie die Arbeit verifiziert wird. Diese Dateien befinden sich in Ihrem Repo, sodass jede Session vom gleichen Zustand ausgeht.
```text
- YOUR PROJECT ROOT
+ IHR PROJEKT-ROOT
├── AGENTS.md <-- das Betriebshandbuch des Agenten
├── CLAUDE.md <-- (Alternative, wenn Sie Claude Code verwenden)
├── init.sh <-- führt install + verify + start aus
@@ -224,28 +224,28 @@ Alle sechs Kursprojekte drehen sich um dasselbe Produkt: **eine Electron-basiert
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Wissensdatenbank-Desktop-App │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Dokumenten- │ │ F&A-Panel ││
+ │ │ liste │ │ ││
+ │ │ doc-001.md │ │ F: Was ist Harness Eng.? ││
+ │ │ doc-002.md │ │ A: Die Umgebung, die um ││
+ │ │ doc-003.md │ │ ein Agentenmodell... ││
+ │ │ ... │ │ [Zitat: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Statusleiste: 42 Doks | 38 indiziert | letzte Sync 3m ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Kernfunktionen:
+ ├── Lokale Dokumente importieren
+ ├── Eine Dokumentenbibliothek verwalten
+ ├── Dokumente verarbeiten und indizieren
+ ├── KI-gestützte F&A über importierte Inhalte ausführen
+ └── Fundierte Antworten mit Quellnachweisen liefern
```
Dieses Projekt wurde gewählt, weil es hohen praktischen Nutzen, ausreichende reale Produktkomplexität und ein gutes Szenario für die Beobachtung von Harness-Verbesserungen (Vorher/Nachher) verbindet.
@@ -259,47 +259,47 @@ Jedes Kursprojekt (Starter/Lösung) ist eine vollständige Kopie dieser Electron
Der Kurs ist für die chronologische Abarbeitung konzipiert. Jede Phase baut auf der vorherigen auf.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ Phase 1: DAS PROBLEM ERKENNEN Phase 2: DAS REPO STRUKTURIEREN
+ ============================== ===============================
+
+ L01 Starke Modelle ≠ zuverlässige L03 Repository als einzige
+ Ausführung Wahrheitsquelle
+ L02 Was ein Harness wirklich bedeutet
+ L04 Anweisungen auf mehrere
+ | Dateien aufteilen, nicht eine riesige
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Nur-Prompt vs. |
+ regelbasierter Vergleich v
+ P02 Agentenlesbarer Arbeitsbereich
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ Phase 3: SESSIONS VERBINDEN Phase 4: FEEDBACK & UMFANG
+ =========================== =========================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Kontext über Sessions hinweg L07 Klare Aufgabengrenzen ziehen
+ lebendig halten
+ L08 Feature-Listen als Harness-
+ L06 Vor jeder Agenten-Session Primitive
+ initialisieren
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Laufzeit-Feedback zur
+ P03 Multi-Session-Kontinuität Korrektur des Agentenverhaltens
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ Phase 5: VERIFIZIERUNG Phase 6: ALLES ZUSAMMENFÜHREN
+ ======================= ==============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 Agenten davon abhalten, L11 Laufzeit des Agenten
+ zu früh Erfolg zu melden beobachtbar machen
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 Vollständiger Pipeline-Lauf = L12 Saubere Übergabe am Ende
+ echte Verifizierung jeder Session
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 Agent verifiziert seine P06 Ein vollständiges Harness
+ eigene Arbeit aufbauen (Abschlussprojekt)
```
Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller vorgehen möchten, können die Phasen 1–3 an einem langen Wochenende absolviert werden.
@@ -339,28 +339,28 @@ Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Ein vollständiges Harness von Grund auf neu aufbauen (Abschlussprojekt) | Vollständiges Harness: alle Mechanismen + Observability + Ablationsstudie |
```text
- PROJECT EVOLUTION
- =================
+ PROJEKTENTWICKLUNG
+ ==================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Nur-Prompt vs. regelbasiert Sie erkennen das Problem
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Agentenlesbarer Arbeitsbereich Sie restrukturieren das Repo
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Multi-Session-Kontinuität Sie verbinden Sessions
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Laufzeit-Feedback & Umfang Sie fügen Feedback-Schleifen hinzu
|
v
- P05 Self-verification You make the agent check itself
+ P05 Selbstverifizierung Sie lassen den Agenten sich selbst prüfen
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Vollständiges Harness (Abschluss) Sie bauen das Gesamtsystem
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Die Lösung jedes Projekts wird zum Starter des nächsten Projekts.
+ Die App entwickelt sich weiter. Ihre Harness-Fähigkeiten wachsen mit.
```
### Vorlagen-Bibliothek
@@ -385,44 +385,44 @@ Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller
Eine der Kernideen dieses Kurses: **Die Session eines Agenten sollte einem strukturierten Lebenszyklus folgen, keinem Freifür-alle.** So sieht das aus:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ AGENTEN-SESSION-LEBENSZYKLUS
+ ============================
┌──────────────────────────────────────────────────────────────────┐
│ START │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agent liest AGENTS.md / CLAUDE.md │
+ │ 2. Agent führt init.sh aus (Installieren, Verifizieren, Check) │
+ │ 3. Agent liest claude-progress.md (was letztes Mal passierte) │
+ │ 4. Agent liest feature_list.json (was erledigt, was als Nächstes)│
+ │ 5. Agent prüft git log (letzte Änderungen) │
│ │
- │ SELECT │
+ │ AUSWAHL │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agent wählt genau EIN unfertiges Feature aus │
+ │ 7. Agent arbeitet nur an diesem Feature │
│ │
- │ EXECUTE │
+ │ AUSFÜHRUNG │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agent implementiert das Feature │
+ │ 9. Agent führt Verifizierung aus (Tests, Lint, Typprüfung) │
+ │ 10. Wenn Verifizierung fehlschlägt: korrigieren und neu ausf. │
+ │ 11. Wenn Verifizierung bestanden: Beweise dokumentieren │
│ │
- │ WRAP UP │
+ │ ABSCHLUSS │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agent aktualisiert claude-progress.md │
+ │ 13. Agent aktualisiert feature_list.json │
+ │ 14. Agent dokumentiert, was noch kaputt oder unverifiziert ist │
+ │ 15. Agent committet (nur wenn sicher fortsetzbar) │
+ │ 16. Agent hinterlässt sauberen Neustartpfad für nächste Session│
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Das Harness steuert jeden Übergang in diesem Lebenszyklus.
+ Das Modell entscheidet, welcher Code bei jedem Schritt geschrieben wird.
+ Ohne Harness wird Schritt 9 zu „Agent sagt, es sieht gut aus."
+ Mit Harness ist Schritt 9: „Tests bestanden, Lint sauber, Typen geprüft."
```
---
diff --git a/README-ES.md b/README-ES.md
index fa5e8f4..e391414 100644
--- a/README-ES.md
+++ b/README-ES.md
@@ -84,22 +84,22 @@ OpenAI reportó lo mismo con Codex: en un repositorio bien equipado con un harne
**Este curso te enseña cómo construir ese entorno.**
```text
- THE HARNESS PATTERN
- ====================
+ EL PATRÓN DEL HARNESS
+ =====================
- You --> give task --> Agent reads harness files --> Agent executes
+ Tú --> das tarea --> Agente lee archivos del harness --> Agente ejecuta
+ |
+ el harness gobierna cada paso:
|
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ +--> Instrucciones: qué hacer, en qué orden
+ +--> Alcance: una funcionalidad a la vez, sin excederse
+ +--> Estado: registro de progreso, lista de funcionalidades, historial git
+ +--> Verificación: tests, lint, verificación de tipos, pruebas de humo
+ +--> Ciclo de vida: inicio al arrancar, estado limpio al finalizar
+ |
+ v
+ El agente se detiene solo cuando
+ la verificación pasa
```
---
@@ -112,32 +112,32 @@ Un harness tiene cinco subsistemas:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ EL HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Instrucciones │ │ Estado │ │ Verificación │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ verif. de tipos │ │
+ │ │ feature_list │ │ git log │ │ pruebas de humo │ │
+ │ │ docs/ │ │ handoff ses. │ │ pipeline e2e │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Alcance │ │ Ciclo de Vida de Sesión │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ una func. │ │ init.sh al inicio │ │
+ │ │ a la vez │ │ checklist de estado limpio al final │ │
+ │ │ definición │ │ nota de entrega para sig. sesión │ │
+ │ │ de hecho │ │ commit solo cuando es seguro reanudar│ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ El MODELO decide qué código escribir.
+ El HARNESS gobierna cuándo, dónde y cómo lo escribe.
+ El harness no hace al modelo más inteligente.
+ Hace que la salida del modelo sea fiable.
```
Cada subsistema tiene una única responsabilidad:
@@ -157,24 +157,24 @@ La pregunta no es "pueden los modelos escribir código?" Pueden. La pregunta es:
En este momento, la respuesta es: no sin un harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ SIN HARNESS CON HARNESS
+ =========== ===========
+
+ Sesión 1: agente escribe código Sesión 1: agente lee instrucciones
+ agente rompe tests agente ejecuta init.sh
+ agente dice "listo" agente trabaja en una funcionalidad
+ tú lo arreglas manualmente agente verifica antes de decir "listo"
+ agente actualiza registro de progreso
+ Sesión 2: agente empieza de cero agente hace commit de estado limpio
+ agente no tiene memoria
+ de lo que pasó antes Sesión 2: agente lee registro de progreso
+ agente rehace el trabajo agente continúa exactamente donde lo dejó
+ o hace algo totalmente distinto agente sigue con la funcionalidad pendiente
+ tú lo arreglas otra vez tú revisas, no rescatas
+
+ Resultado: pasas más tiempo Resultado: el agente hace el trabajo,
+ arreglando que si lo tú verificas el resultado
+ hubieras hecho tú mismo
```
Las preguntas que realmente importan en este curso:
@@ -205,13 +205,13 @@ No necesitas leer las 12 clases antes de empezar a obtener valor. Si ya estás u
La idea es simple: en lugar de solo escribir prompts, dale a tu agente un conjunto de archivos estructurados que definan qué hacer, qué se ha hecho y cómo verificar el trabajo. Estos archivos viven dentro de tu repositorio, así que cada sesión comienza desde el mismo estado.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ RAÍZ DE TU PROYECTO
+ ├── AGENTS.md <-- el manual de operación del agente
+ ├── CLAUDE.md <-- (alternativa, si usas Claude Code)
+ ├── init.sh <-- ejecuta install + verify + start
+ ├── feature_list.json <-- qué funcionalidades existen, cuáles están listas
+ ├── claude-progress.md <-- qué pasó en cada sesión
+ └── src/ <-- tu código real
```
Obtén las plantillas iniciales de la [Biblioteca de Recursos](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) y colócalas en tu proyecto. Eso es todo. Cuatro archivos, y tus sesiones de agente ya serán significativamente más estables que ejecutándolas solo con prompts.
@@ -224,28 +224,29 @@ Los seis proyectos del curso giran en torno al mismo producto: **una aplicación
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ App de Escritorio Base de Conocimiento │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ Lista de │ │ Panel de Preguntas y ││
+ │ │ Documentos │ │ Respuestas ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ P: Qué es harness eng? ││
+ │ │ doc-002.md │ │ R: El entorno construido ││
+ │ │ doc-003.md │ │ alrededor de un agente...││
+ │ │ ... │ │ [cita: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Barra de estado: 42 docs | 38 indexados | últ. 3m│
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Funcionalidades principales:
+ ├── Importar documentos locales
+ ├── Gestionar una biblioteca de documentos
+ ├── Procesar e indexar documentos
+ ├── Ejecutar P&R con IA sobre el contenido importado
+ └── Devolver respuestas fundamentadas con citas
```
Este proyecto fue elegido porque combina un fuerte valor práctico, suficiente complejidad de producto del mundo real y un buen entorno para observar mejoras antes y después del harness.
@@ -259,47 +260,48 @@ El starter/solution de cada proyecto del curso es una copia completa de esta apl
El curso está diseñado para realizarse en orden. Cada fase se construye sobre la anterior.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ Fase 1: VER EL PROBLEMA Fase 2: ESTRUCTURAR EL REPO
+ ========================= ==========================
+
+ L01 Modelos potentes ≠ ejecución L03 Repositorio como única
+ fiable fuente de verdad
+ L02 Qué significa realmente harness
+ L04 Dividir instrucciones en
+ | archivos, no un archivo gigante
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Solo prompts vs. |
+ comparación con reglas primero v
+ P02 Espacio de trabajo legible
+ por el agente
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ Fase 3: CONECTAR SESIONES Fase 4: RETROALIMENTACIÓN Y ALCANCE
+ ========================== ====================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Mantener el contexto vivo L07 Dibujar límites claros de tarea
+ entre sesiones
+ L08 Listas de funcionalidades como
+ L06 Inicializar antes de cada primitivas del harness
+ sesión del agente
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Retroalimentación en tiempo de
+ P03 Continuidad multi-sesión ejecución para corregir el agente
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
+ Fase 5: VERIFICACIÓN Fase 6: PONERLO TODO JUNTO
===================== ============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 Evitar que los agentes L11 Hacer observable el runtime
+ declaren victoria pronto del agente
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 Ejecución completa del L12 Entrega limpia al final de
+ pipeline = verificación real cada sesión
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 El agente verifica su P06 Construir un harness completo
+ propio trabajo (proyecto final)
```
Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quieres ir más rápido, las fases 1-3 se pueden completar en un fin de semana largo.
@@ -339,28 +341,31 @@ Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quier
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Construir un harness completo desde cero (proyecto final) | Harness completo: todos los mecanismos + observabilidad + estudio de ablación |
```text
- PROJECT EVOLUTION
- =================
+ EVOLUCIÓN DEL PROYECTO
+ ======================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Solo prompts vs. reglas primero Tú ves el problema
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Espacio de trabajo legible Tú reestructuras el repo
+ por el agente
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Continuidad multi-sesión Tú conectas las sesiones
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Retroalimentación y alcance Tú agregas ciclos de
+ en tiempo de ejecución retroalimentación
|
v
- P05 Self-verification You make the agent check itself
+ P05 Auto-verificación Tú haces que el agente
+ se verifique a sí mismo
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Harness completo (proyecto final) Tú construyes el sistema completo
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ La solución de cada proyecto se convierte en el starter del siguiente.
+ La app evoluciona. Tus habilidades de harness crecen con ella.
```
### Biblioteca de Recursos
@@ -385,44 +390,44 @@ Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quier
Una de las ideas centrales de este curso: **la sesión del agente debe seguir un ciclo de vida estructurado, no un libre intercambio.** Así es como se ve:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ CICLO DE VIDA DE LA SESIÓN DEL AGENTE
+ =====================================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ INICIO │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agente lee AGENTS.md / CLAUDE.md │
+ │ 2. Agente ejecuta init.sh (install, verify, health check) │
+ │ 3. Agente lee claude-progress.md (qué pasó la última vez) │
+ │ 4. Agente lee feature_list.json (qué está listo, qué sigue) │
+ │ 5. Agente revisa git log (cambios recientes) │
│ │
- │ SELECT │
+ │ SELECCIONAR │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agente elige exactamente UNA funcionalidad pendiente │
+ │ 7. Agente trabaja solo en esa funcionalidad │
│ │
- │ EXECUTE │
+ │ EJECUTAR │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agente implementa la funcionalidad │
+ │ 9. Agente ejecuta verificación (tests, lint, verif. de tipos) │
+ │ 10. Si la verificación falla: corregir y volver a ejecutar │
+ │ 11. Si la verificación pasa: registrar evidencia │
│ │
- │ WRAP UP │
+ │ CERRAR │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agente actualiza claude-progress.md │
+ │ 13. Agente actualiza feature_list.json │
+ │ 14. Agente registra qué sigue roto o sin verificar │
+ │ 15. Agente hace commit (solo cuando es seguro reanudar) │
+ │ 16. Agente deja una ruta de reinicio limpia para la sig. sesión│
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ El harness gobierna cada transición en este ciclo de vida.
+ El modelo decide qué código escribir en cada paso.
+ Sin el harness, el paso 9 se convierte en "el agente dice que se ve bien."
+ Con el harness, el paso 9 es "los tests pasan, el lint está limpio, los tipos verifican."
```
---
diff --git a/README-FR.md b/README-FR.md
index 81db7a6..a9aa125 100644
--- a/README-FR.md
+++ b/README-FR.md
@@ -84,22 +84,22 @@ OpenAI a rapporté la même chose avec Codex : dans un dépôt bien équipé d'u
**Ce cours vous apprend à construire cet environnement.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ LE MODÈLE HARNESS
+ =================
+
+ Vous --> donnez une tâche --> L'agent lit les fichiers harness --> L'agent exécute
+ |
+ Le harness gouverne chaque étape :
+ |
+ +--> Instructions : quoi faire, dans quel ordre
+ +--> Portée : une fonctionnalité à la fois, pas de surcharge
+ +--> État : journal de progression, liste de fonctionnalités, historique git
+ +--> Vérification : tests, lint, vérification de types, essais de fumée
+ +--> Cycle de vie : initialisation au démarrage, état propre à la fin
+ |
+ v
+ L'agent s'arrête uniquement quand
+ la vérification réussit
```
---
@@ -112,32 +112,32 @@ Un harness comporte cinq sous-systèmes :
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ LE HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Instructions │ │ État │ │ Vérification │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ vérif. de types │ │
+ │ │ feature_list │ │ git log │ │ essais de fumée │ │
+ │ │ docs/ │ │ transfert │ │ pipeline e2e │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Portée │ │ Cycle de vie de session │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ une seule │ │ init.sh au démarrage │ │
+ │ │ fonctionnalité│ │ liste de contrôle état propre à fin │ │
+ │ │ définition │ │ note de transfert pour prochaine │ │
+ │ │ de « terminé »│ │ commit uniquement si reprise sûre │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ Le MODÈLE décide quel code écrire.
+ Le HARNESS gouverne quand, où et comment il l'écrit.
+ Le harness ne rend pas le modèle plus intelligent.
+ Il rend la sortie du modèle fiable.
```
Chaque sous-système a une seule responsabilité :
@@ -157,24 +157,24 @@ La question n'est pas « les modèles peuvent-ils écrire du code ? » Ils le pe
Pour l'instant, la réponse est : pas sans un harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ SANS HARNESS AVEC HARNESS
+ =========== ============
+
+ Session 1 : l'agent écrit du code Session 1 : l'agent lit les instructions
+ l'agent casse les tests l'agent exécute init.sh
+ l'agent dit « terminé » l'agent travaille sur une fonctionnalité
+ vous corrigez manuellement l'agent vérifie avant de déclarer « terminé »
+ l'agent met à jour le journal de progression
+ Session 2 : l'agent repart de zéro l'agent commit un état propre
+ l'agent n'a aucun souvenir
+ de ce qui s'est passé avant Session 2 : l'agent lit le journal de progression
+ l'agent refait le travail l'agent reprend exactement là où il s'est arrêté
+ ou fait autre chose totalement l'agent continue la fonctionnalité inachevée
+ vous corrigez encore vous révisez, vous ne sauvez pas
+
+ Résultat : vous passez plus de temps Résultat : l'agent fait le travail,
+ à nettoyer qu si vous vous vérifiez le résultat
+ l'aviez fait vous-même
```
Les questions auxquelles ce cours s'intéresse réellement :
@@ -205,13 +205,13 @@ Vous n'avez pas besoin de lire les 12 cours avant de commencer à en tirer profi
L'idée est simple : au lieu de simplement écrire des prompts, donnez à votre agent un ensemble de fichiers structurés qui définissent ce qu'il faut faire, ce qui a été fait et comment vérifier le travail. Ces fichiers résident dans votre dépôt, donc chaque session démarre depuis le même état.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ RACINE DE VOTRE PROJET
+ ├── AGENTS.md <-- le manuel de fonctionnement de l'agent
+ ├── CLAUDE.md <-- (alternative, si vous utilisez Claude Code)
+ ├── init.sh <-- exécute installation + vérification + démarrage
+ ├── feature_list.json <-- quelles fonctionnalités existent, lesquelles sont terminées
+ ├── claude-progress.md <-- ce qui s'est passé à chaque session
+ └── src/ <-- votre code réel
```
Récupérez les modèles de démarrage depuis la [Bibliothèque de Ressources](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) et déposez-les dans votre projet. C'est tout. Quatre fichiers, et vos sessions d'agent seront déjà nettement plus stables qu'avec des prompts seuls.
@@ -224,28 +224,28 @@ Les six projets du cours gravitent autour du même produit : **une application d
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Application Bureau de Base de Connaissances │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Liste de │ │ Panneau Q&R ││
+ │ │ documents │ │ ││
+ │ │ doc-001.md │ │ Q : Qu'est-ce que le harness││
+ │ │ doc-002.md │ │ R : L'environnement construit││
+ │ │ doc-003.md │ │ autour d'un modèle d'agent││
+ │ │ ... │ │ [citation : doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Barre d'état : 42 docs | 38 indexés | sync 3m ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Fonctionnalités principales :
+ ├── Importer des documents locaux
+ ├── Gérer une bibliothèque de documents
+ ├── Traiter et indexer des documents
+ ├── Exécuter des Q&R alimentées par l'IA sur le contenu importé
+ └── Retourner des réponses fondées avec des citations
```
Ce projet a été choisi car il combine une forte valeur pratique, une complexité produit suffisante pour le monde réel et un bon cadre pour observer les améliorations avant/après harness.
@@ -259,47 +259,47 @@ Le starter/solution de chaque projet du cours est une copie complète de cette a
Le cours est conçu pour être suivi dans l'ordre. Chaque phase s'appuie sur la précédente.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
- v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
-
-
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
-
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
- |
- | v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
-
-
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
-
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
-
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
-
- | |
- v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ Phase 1 : VOIR LE PROBLÈME Phase 2 : STRUCTURER LE DÉPÔT
+ =========================== =============================
+
+ L01 Des modèles performants ≠ L03 Le dépôt comme unique
+ une exécution fiable source de vérité
+ L02 Ce que signifie réellement
+ un harness L04 Répartir les instructions entre
+ plusieurs fichiers, pas un seul fichier géant
+ |
+ v |
+ P01 Comparaison prompts seuls v
+ vs. règles d'abord P02 Espace de travail lisible par l'agent
+
+
+ Phase 3 : CONNECTER LES SESSIONS Phase 4 : RETOUR & PORTÉE
+ ================================= =========================
+
+ L05 Maintenir le contexte L07 Définir des limites de tâches claires
+ entre les sessions
+ L08 Les listes de fonctionnalités comme
+ L06 Initialiser avant chaque primitives du harness
+ session d'agent
+ |
+ | v
+ v P04 Retour d'exécution pour
+ P03 Continuité multi-sessions corriger le comportement de l'agent
+
+
+ Phase 5 : VÉRIFICATION Phase 6 : TOUT ASSEMBLER
+ ====================== ========================
+
+ L09 Empêcher les agents de L11 Rendre l'exécution de l'agent
+ déclarer victoire trop tôt observable
+
+ L10 Une exécution complète du L12 Transfert propre à la fin de
+ pipeline = vraie vérification chaque session
+
+ | |
+ v v
+ P05 L'agent vérifie son propre travail P06 Construire un harness complet
+ (projet final)
```
Chaque phase prend environ une semaine si vous suivez le cours à temps partiel. Si vous souhaitez aller plus vite, les phases 1 à 3 peuvent être effectuées en un long week-end.
@@ -339,28 +339,29 @@ Chaque phase prend environ une semaine si vous suivez le cours à temps partiel.
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Construire un harness complet à partir de zéro (projet final) | Harness complet : tous les mécanismes + observabilité + étude d'ablation |
```text
- PROJECT EVOLUTION
- =================
+ ÉVOLUTION DES PROJETS
+ =====================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Prompts seuls vs. règles d'abord Vous voyez le problème
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Espace de travail lisible Vous restructurez le dépôt
+ par l'agent
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Continuité multi-sessions Vous connectez les sessions
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Retour d'exécution & portée Vous ajoutez des boucles de retour
|
v
- P05 Self-verification You make the agent check itself
+ P05 Auto-vérification Vous faites en sorte que l'agent se vérifie
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Harness complet (projet final) Vous construisez le système complet
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ La solution de chaque projet devient le starter du projet suivant.
+ L'application évolue. Vos compétences en harness grandissent avec elle.
```
### Bibliothèque de Ressources
@@ -385,44 +386,44 @@ Chaque phase prend environ une semaine si vous suivez le cours à temps partiel.
L'une des idées centrales de ce cours : **la session de l'agent doit suivre un cycle de vie structuré, pas être laissée au hasard.** Voici à quoi cela ressemble :
```text
- AGENT SESSION LIFECYCLE
- ======================
+ CYCLE DE VIE DE LA SESSION DE L'AGENT
+ ======================================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ DÉMARRAGE │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. L'agent lit AGENTS.md / CLAUDE.md │
+ │ 2. L'agent exécute init.sh (installation, vérif., contrôle) │
+ │ 3. L'agent lit claude-progress.md (ce qui s'est passé) │
+ │ 4. L'agent lit feature_list.json (terminé, à faire) │
+ │ 5. L'agent vérifie git log (changements récents) │
│ │
- │ SELECT │
+ │ SÉLECTION │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. L'agent choisit exactement UNE fonctionnalité inachevée │
+ │ 7. L'agent travaille uniquement sur cette fonctionnalité │
│ │
- │ EXECUTE │
+ │ EXÉCUTION │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. L'agent implémente la fonctionnalité │
+ │ 9. L'agent exécute la vérification (tests, lint, types) │
+ │ 10. Si la vérification échoue : corriger et relancer │
+ │ 11. Si la vérification réussit : enregistrer la preuve │
│ │
- │ WRAP UP │
+ │ CLÔTURE │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. L'agent met à jour claude-progress.md │
+ │ 13. L'agent met à jour feature_list.json │
+ │ 14. L'agent enregistre ce qui reste cassé ou non vérifié │
+ │ 15. L'agent commit (uniquement si la reprise est sûre) │
+ │ 16. L'agent laisse un chemin de redémarrage propre │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Le harness gouverne chaque transition dans ce cycle de vie.
+ Le modèle décide quel code écrire à chaque étape.
+ Sans le harness, l'étape 9 devient « l'agent dit que ça a l'air correct ».
+ Avec le harness, l'étape 9 est « les tests passent, le lint est propre, les types sont valides ».
```
---
diff --git a/README-JA.md b/README-JA.md
index 3ae645d..96eb201 100644
--- a/README-JA.md
+++ b/README-JA.md
@@ -84,22 +84,22 @@ OpenAI も Codex で同じことを報告しています:適切にハーネス
**このコースは、その環境の構築方法を教えます。**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ ハーネスパターン
+ ================
+
+ あなた --> タスクを与える --> エージェントがハーネスファイルを読む --> エージェントが実行
+ |
+ ハーネスが全ステップを管理:
+ |
+ +--> 指示:何を、どの順序で行うか
+ +--> スコープ:一度に一つの機能、過剰な範囲拡大なし
+ +--> 状態:進捗ログ、機能リスト、git履歴
+ +--> 検証:テスト、lint、型チェック、スモーク実行
+ +--> ライフサイクル:開始時に初期化、終了時にクリーンな状態
+ |
+ v
+ エージェントは検証が
+ 通過した時のみ停止
```
---
@@ -112,32 +112,32 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ ハーネス │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ 指示 │ │ 状態 │ │ 検証 │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ テスト + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ 型チェック │ │
+ │ │ feature_list │ │ git log │ │ スモーク実行 │ │
+ │ │ docs/ │ │ セションハンドオフ│ │ e2eパイプライン │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ スコープ │ │ セッションライフサイクル │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ 一度に │ │ 開始時にinit.shを実行 │ │
+ │ │ 一つの機能 │ │ 終了時にクリーン状態チェックリスト │ │
+ │ │ 完了の定義 │ │ 次セッションへのハンドオフノート │ │
+ │ │ │ │ 再開安全な場合のみコミット │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ モデルは書くコードを決定する。
+ ハーネスはいつ、どこで、どう書くかを管理する。
+ ハーネスはモデルを賢くするわけではない。
+ モデルの出力を信頼性のあるものにする。
```
各サブシステムには一つの役割があります:
@@ -157,24 +157,23 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
現時点での答えは:ハーネスなしでは無理です。
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ ハーネスなし ハーネスあり
+ ========== ==========
+
+ セッション1: エージェントがコードを書く セッション1: エージェントが指示を読む
+ エージェントがテストを壊す エージェントがinit.shを実行
+ エージェントが「完了」と言う エージェントが一つの機能に取り組む
+ あなたが手動で修正 エージェントが完了宣言前に検証
+ エージェントが進捗ログを更新
+ セッション2: エージェントがゼロから開始 エージェントがクリーンな状態でコミット
+ エージェントは前回の記憶がない
+ セッション2: エージェントが進捗ログを読む
+ エージェントが同じ作業をやり直す エージェントが前回の続きから正確に再開
+ または全く別のことをする エージェントが未完了の機能を継続
+ あなたがまた修正 あなたは確認する、修正するのではない
+
+ 結果: 自分でやるよりも 結果: エージェントが作業を行い、
+ 修正に多くの時間を費やす あなたは結果を検証する
```
このコースが本当に重視している問い:
@@ -205,7 +204,7 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
アイデアはシンプルです:プロンプトを書く代わりに、何をすべきか、何が完了しているか、作業をどう検証するかを定義する構造化ファイルのセットをエージェントに与えます。これらのファイルはリポジトリ内に存在するため、すべてのセッションが同じ状態から始まります。
```text
- YOUR PROJECT ROOT
+ あなたのプロジェクトルート
├── AGENTS.md <-- エージェントの操作マニュアル
├── CLAUDE.md <-- (代替、Claude Code を使用する場合)
├── init.sh <-- install + verify + start を実行
@@ -224,28 +223,29 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ ナレッジベースデスクトップアプリ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ ドキュメント │ │ Q&Aパネル ││
+ │ │ リスト │ │ ││
+ │ │ doc-001.md │ │ Q: ハーネスエンジニアリング ││
+ │ │ doc-002.md │ │ とは何か? ││
+ │ │ doc-003.md │ │ A: エージェントモデルの ││
+ │ │ ... │ │ 周囲に構築された環境... ││
+ │ │ │ │ [引用元: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ ステータスバー: 42文書 | 38件インデックス済 | 最終同期 3分前││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ コア機能:
+ ├── ローカルドキュメントのインポート
+ ├── ドキュメントライブラリの管理
+ ├── ドキュメントの処理とインデックス作成
+ ├── インポートしたコンテンツに対するAI搭載Q&Aの実行
+ └── 引用付きの根拠ある回答の返却
```
このプロジェクトが選ばれたのは、実用的な価値、十分な現実世界の製品複雑さ、ハーネス改善の前後を観察するのに適した設定を組み合わせているからです。
@@ -259,47 +259,47 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
このコースは順番に進めるように設計されています。各フェーズは前のフェーズの上に構築されます。
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ フェーズ1: 問題を見る フェーズ2: リポジトリを構造化
+ ================================= =================================
+
+ L01 強力なモデル ≠ 確実な実行 L03 リポジトリを唯一の
+ 信頼できる情報源にする
+ L02 ハーネスが実際に意味するもの
+ L04 指示を複数ファイルに分割、
+ | 一つの巨大ファイルにしない
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 プロンプトのみ vs. |
+ ルール優先の比較 v
+ P02 エージェント可読ワークスペース
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ フェーズ3: セッションを接続 フェーズ4: フィードバックとスコープ
+ ================================= ====================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
- |
- | v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ L05 セッション間で L07 明確なタスク境界を引く
+ コンテキストを維持
+ L08 機能リストをハーネスの
+ L06 毎回のエージェント プリミティブとして使う
+ セッション前に初期化
+ |
+ | v
+ v P04 エージェントの動作を修正する
+ P03 マルチセッション連続性 ランタイムフィードバック
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ フェーズ5: 検証 フェーズ6: すべてを統合
+ ===================== ============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 エージェントが早すぎる L11 エージェントのランタイムを
+ 完了宣言をするのを防ぐ 観測可能にする
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 フルパイプライン実行 = L12 全セッションの終了時に
+ 本当の検証 クリーンなハンドオフ
- | |
- v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ | |
+ v v
+ P05 エージェントが自分の作業を検証 P06 完全なハーネスを構築
+ (カプロジェクト)
```
パートタイムで進める場合、各フェーズは約1週間です。より速く進めたい場合、フェーズ1〜3は長い週末で完了できます。
@@ -339,28 +339,28 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | ゼロから完全なハーネスを構築する(カプロジェクト) | フルハーネス:全メカニズム + オブザーバビリティ + アブレーションスタディ |
```text
- PROJECT EVOLUTION
- =================
+ プロジェクトの進化
+ ==================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 プロンプトのみ vs. ルール優先 問題を目撃する
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 エージェント可読ワークスペース リポジトリを再構築する
|
v
- P03 Multi-session continuity You connect sessions
+ P03 マルチセッション連続性 セッションを接続する
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 ランタイムフィードバックとスコープ フィードバックループを追加する
|
v
- P05 Self-verification You make the agent check itself
+ P05 自己検証 エージェントに自己チェックさせる
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 完全なハーネス(カプロジェクト) 完全なシステムを構築する
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ 各プロジェクトのソリューションが次のプロジェクトのスターターになる。
+ アプリは進化する。あなたのハーネスキルも共に成長する。
```
### リソースライブラリ
@@ -385,44 +385,44 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
このコースのコアアイデアの一つ:**エージェントのセッションは自由放任ではなく、構造化されたライフサイクルに従うべきです。** どのようなものか:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ エージェントセッションライフサイクル
+ ====================================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ 開始 │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. エージェントがAGENTS.md / CLAUDE.mdを読む │
+ │ 2. エージェントがinit.shを実行(インストール、検証、ヘルスチェック)│
+ │ 3. エージェントがclaude-progress.mdを読む(前回の内容) │
+ │ 4. エージェントがfeature_list.jsonを読む(完了済み、次の作業) │
+ │ 5. エージェントがgit logを確認(最近の変更) │
│ │
- │ SELECT │
+ │ 選択 │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. エージェントは未完了の機能を正確に1つだけ選択 │
+ │ 7. エージェントはその機能のみに取り組む │
│ │
- │ EXECUTE │
+ │ 実行 │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. エージェントが機能を実装する │
+ │ 9. エージェントが検証を実行(テスト、lint、型チェック) │
+ │ 10. 検証失敗時:修正して再実行 │
+ │ 11. 検証通過時:証拠を記録 │
│ │
- │ WRAP UP │
+ │ 仕上げ │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. エージェントがclaude-progress.mdを更新 │
+ │ 13. エージェントがfeature_list.jsonを更新 │
+ │ 14. エージェントがまだ壊れている、または未検証の項目を記録 │
+ │ 15. エージェントがコミット(再開安全な場合のみ) │
+ │ 16. エージェントが次セッション用のクリーンな再起動パスを残す │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ ハーネスはこのライフサイクルの全移行を管理する。
+ モデルは各ステップで書くコードを決定する。
+ ハーネスなしでは、ステップ9は「エージェントが大丈夫そうだと言う」になる。
+ ハーネスありでは、ステップ9は「テスト通過、lintクリーン、型チェックOK」になる。
```
---
diff --git a/README-KO.md b/README-KO.md
index 53da38d..09680c4 100644
--- a/README-KO.md
+++ b/README-KO.md
@@ -15,348 +15,359 @@
# Learn Harness Engineering
-> **AI 코딩 에이전트(coding agent)가 안정적으로 동작하도록 환경, 상태 관리, 검증(verification), 제어 메커니즘을 구축하는 프로젝트 기반 강의입니다.**
+> **AI 코딩 에이전트가 안정적으로 작동하도록 만드는 환경, 상태 관리, 검증 및 제어 메커니즘을 구축하는 프로젝트 기반 강좌입니다.**
-Learn Harness Engineering은 AI 코딩 에이전트 공학에 전념하는 강의입니다. 업계에서 가장 앞선 하네스 엔지니어링(Harness Engineering) 이론과 실천을 깊이 연구하여 종합했습니다. 핵심 참고 자료는 다음과 같습니다.
+Learn Harness Engineering은 AI 코딩 에이전트의 엔지니어링에 집중하는 강좌입니다. 업계에서 가장 선진적인 Harness Engineering 이론과 실무를 심층적으로 연구하고 종합했습니다. 핵심 참고 자료는 다음과 같습니다:
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
-> **빠르게 시작하려면?** [`skills/harness-creator/`](./skills/) 스킬(skill)을 사용하면 몇 분 만에 프로덕션 수준의 하네스(AGENTS.md, 기능 목록, init.sh, 검증 워크플로우)를 직접 프로젝트에 스캐폴딩(scaffold)할 수 있습니다.
+> **빠른 시작?** [`skills/harness-creator/`](../../skills/) 스킬을 사용하면 몇 분 만에 여러분의 프로젝트에 프로덕션급 하니스(AGENTS.md, 기능 목록, init.sh, 검증 워크플로우)를 스캐폴딩할 수 있습니다.
---
-## 시각적 미리보기
+## 목차
-### 강의 홈페이지
-> 핵심 철학을 소개하고 시작 경로를 명확히 제시하는 종합 강의 개요입니다.
+- [✨ 시각적 미리보기](#-시각적-미리보기)
+- [Harness Engineering의 진정한 의미](#harness-engineering의-진정한-의미)
+- [빠른 시작: 오늘 바로 에이전트 개선하기](#빠른-시작-오늘-바로-에이전트-개선하기)
+- [캡스톤 프로젝트: 실제 앱](#캡스톤-프로젝트-실제-앱)
+- [학습 경로](#학습-경로)
+- [강의 개요](#강의-개요)
+- [스킬](#스킬)
+- [다른 강좌](#다른-강좌)
-![강의 홈페이지 미리보기](./docs/public/screenshots/readme/en-home.png)
+---
+
+## ✨ 시각적 미리보기
+
+### 🏠 강좌 홈페이지
+> 포괄적인 강좌 개요와 핵심 철학에 대한 소개로, 시작하기 위한 명확한 경로를 제공합니다.
-### 몰입형 강의
-> 실제 문제 상황을 심층적으로 분석하고 실습 프로젝트(예: Project 01)를 통해 몰입 학습 경험을 제공합니다.
+![강좌 홈페이지 미리보기](../../docs/public/screenshots/readme/zh-home.png)
-![강의 미리보기](./docs/public/screenshots/readme/en-lecture-01.png)
+### 📖 몰입형 강의
+> 실제 문제점에 대한 심층 분석과 실습 프로젝트(예: Project 01)를 통한 몰입형 학습 경험.
-### 즉시 사용 가능한 리소스 라이브러리
-> 다중 턴 AI 에이전트 개발 시 흔히 발생하는 컨텍스트(context) 손실, 과도한 완료 선언 등의 문제를 해결하기 위해 설계된 템플릿과 참고 설정 모음입니다.
+![강좌 강의 미리보기](../../docs/public/screenshots/readme/zh-lecture-01.png)
-![리소스 라이브러리 미리보기](./docs/public/screenshots/readme/en-resources.png)
+### 🗂️ 바로 사용 가능한 리소스 라이브러리
+> 다중 턴 AI 에이전트 개발에서 발생하는 컨텍스트 손실, 조기 작업 완료 등 일반적인 문제를 해결하기 위해 설계된 템플릿과 참조 구성.
-## PDF 강의 교재
+![리소스 라이브러리 미리보기](../../docs/public/screenshots/readme/zh-resources.png)
-저장소에는 강의 콘텐츠를 위한 PDF 빌드 파이프라인이 포함되어 있습니다.
+## PDF 강좌 자료
-- `npm run pdf:build` 명령으로 현재 스크립트에 설정된 강의 PDF를 로컬에서 생성할 수 있습니다.
+이 저장소에는 강좌 콘텐츠를 위한 PDF 빌드 파이프라인이 포함되어 있습니다.
+
+- `npm run pdf:build`를 실행하여 영어 및 중국어 PDF를 로컬에서 생성합니다.
- 출력 파일은 `artifacts/pdfs/`에 저장됩니다.
-- README 미리보기 이미지를 갱신하려면 `npm run screenshots:readme`를 실행하십시오.
-- GitHub Actions 워크플로우 [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml)을 통해 PDF를 빌드하고 GitHub Releases에 게시할 수 있습니다.
+- README 미리보기 이미지를 새로고침하려면 `npm run screenshots:readme`를 실행하세요.
+- GitHub Actions 워크플로우 [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml)를 통해 PDF를 빌드하고 GitHub Releases에 게시할 수 있습니다.
---
-## 모델은 스마트하고, 하네스가 안정성을 만든다
+## 모델은 똑똑하고, 하니스가 안정성을 만듭니다
-대부분의 사람들이 직접 경험한 뒤에야 깨닫는 냉혹한 진실이 있습니다. **세상에서 가장 강력한 모델도 적절한 환경 없이는 실제 엔지니어링 작업에서 실패합니다.**
+대부분의 사람들이 어려운 방식으로 깨닫는 뼈아픈 사실이 있습니다: **세계에서 가장 강력한 모델이라도 주변에 적절한 환경을 구축하지 않으면 실제 엔지니어링 작업에서 여전히 실패합니다.**
-아마 직접 겪어보셨을 것입니다. Claude나 GPT에게 저장소(repository)에서 작업을 맡깁니다. 처음에는 잘 진행됩니다 — 파일을 읽고, 코드를 작성하고, 생산적으로 보입니다. 그러다 뭔가 잘못됩니다. 단계를 건너뜁니다. 테스트를 망칩니다. "완료"라고 하지만 실제로는 아무것도 동작하지 않습니다. 직접 했더라면 더 빨랐을 시간을 수습에 써버립니다.
+직접 겪어보셨을 것입니다. 여러분의 저장소에서 Claude나 GPT에 작업을 맡깁니다. 처음에는 잘 진행됩니다 — 파일을 읽고, 코드를 작성하고, 생산적으로 보입니다. 그러다 무언가 잘못됩니다. 단계를 건너뜁니다. 테스트를 망가뜨립니다. "완료"라고 말하지만 실제로는 아무것도 작동하지 않습니다. 직접 했더라면 더 빨랐을 작업을 수정하는 데 더 많은 시간을 쓰게 됩니다.
-이것은 모델 문제가 아닙니다. 하네스 문제입니다.
+이것은 모델의 문제가 아닙니다. 하니스의 문제입니다.
-증거는 명확합니다. Anthropic이 통제된 실험을 수행했습니다. 동일한 모델(Opus 4.5), 동일한 프롬프트("2D 레트로 게임 에디터 만들기"). 하네스 없이는 20분 동안 $9를 사용했으나 동작하지 않는 결과물이 나왔습니다. 완전한 하네스(플래너 + 생성기 + 평가기)를 사용했을 때는 6시간 동안 $200을 사용해 실제로 플레이할 수 있는 게임을 만들었습니다. 모델은 바뀌지 않았습니다. 하네스가 바뀌었습니다.
+증거는 명확합니다. Anthropic은 통제된 실험을 진행했습니다: 동일한 모델(Opus 4.5), 동일한 프롬프트("2D 레트로 게임 에디터 구축"). 하니스 없이는 20분 만에 $9를 소비하고 작동하지 않는 결과물을 만들었습니다. 전체 하니스(플래너 + 제너레이터 + 평가자)를 갖추면 6시간 동안 $200를 소비하고 실제로 플레이할 수 있는 게임을 구축했습니다. 모델은 변하지 않았습니다. 하니스가 달랐습니다.
-OpenAI도 Codex로 동일한 사실을 보고했습니다. 잘 갖추어진 저장소에서는 동일한 모델이 "불안정"에서 "안정적"으로 전환됩니다. 미미한 개선이 아니라 질적 변화입니다.
+OpenAI도 Codex에서 동일한 결과를 보고했습니다: 잘 구축된 하니스가 있는 저장소에서는 동일한 모델이 "불안정"에서 "안정적"으로 변합니다. 미미한 개선이 아닌 질적인 전환입니다.
-**이 강의는 그 환경을 구축하는 방법을 가르칩니다.**
+**이 강좌는 그 환경을 구축하는 방법을 가르칩니다.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ 하니스 패턴
+ ==========
+
+ 사용자 --> 작업 전달 --> 에이전트가 하니스 파일 읽음 --> 에이전트 실행
+ |
+ 하니스가 모든 단계를 제어:
+ |
+ +--> 지시 사항: 무엇을, 어떤 순서로 할 것인가
+ +--> 범위: 한 번에 하나의 기능, 과도한 작업 금지
+ +--> 상태: 진행 로그, 기능 목록, git 기록
+ +--> 검증: 테스트, 린트, 타입 검사, 스모크 실행
+ +--> 수명 주기: 시작 시 초기화, 종료 시 깔끔한 상태
+ |
+ v
+ 에이전트는 검증을 통과한 경우에만
+ 실행을 중지합니다
```
---
-## 하네스 엔지니어링이란 실제로 무엇인가
+## Harness Engineering의 진정한 의미
-하네스 엔지니어링(Harness Engineering)은 모델이 안정적인 결과를 낼 수 있도록 모델 주변에 완전한 작업 환경을 구축하는 것입니다. 더 나은 프롬프트를 작성하는 것이 아닙니다. 모델이 운영되는 시스템을 설계하는 것입니다.
+Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완전한 작업 환경을 구축하는 것입니다. 더 나은 프롬프트를 작성하는 것이 아닙니다. 모델이 작동하는 시스템 자체를 설계하는 것입니다.
-하네스에는 다섯 가지 하위 시스템이 있습니다.
+하니스에는 다섯 가지 하위 시스템이 있습니다:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ 하니스 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ 지시 사항 │ │ 상태 │ │ 검증 │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ 테스트 + 린트 │ │
+ │ │ CLAUDE.md │ │ 기능 목록 │ │ 타입 검사 │ │
+ │ │ 기능 목록 │ │ git log │ │ 스모크 실행 │ │
+ │ │ docs/ │ │ 세션 인계 │ │ e2e 파이프라인 │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ 범위 │ │ 세션 수명 주기 │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ 한 번에 │ │ 시작 시 init.sh 실행 │ │
+ │ │ 하나의 기능 │ │ 종료 시 깔끔한 상태 체크리스트 │ │
+ │ │ 완료 정의 │ │ 다음 세션을 위한 인계 노트 │ │
+ │ │ │ │ 안전하게 재개 가능할 때만 커밋 │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ 모델은 어떤 코드를 작성할지 결정합니다.
+ 하니스는 언제, 어디서, 어떻게 작성할지 제어합니다.
+ 하니스는 모델을 더 똑똑하게 만들지 않습니다.
+ 모델의 출력을 안정적으로 만듭니다.
```
-각 하위 시스템에는 하나의 역할이 있습니다.
+각 하위 시스템은 하나의 역할을 담당합니다:
-- **지시사항(Instructions)** — 에이전트에게 무엇을 어떤 순서로 할지, 시작 전에 무엇을 읽어야 하는지 알려줍니다. 하나의 거대한 파일이 아니라, 에이전트가 필요할 때 탐색하는 점진적 공개(progressive disclosure) 구조입니다.
-- **상태(State)** — 완료된 것, 진행 중인 것, 다음 작업을 추적합니다. 디스크에 영속화(persist)되어 다음 세션이 이전 세션이 끝난 정확한 위치에서 이어받을 수 있습니다.
-- **검증(Verification)** — 통과하는 테스트 스위트만이 증거로 인정됩니다. 에이전트는 실행 가능한 증거 없이는 완료를 선언할 수 없습니다.
-- **범위(Scope)** — 에이전트를 한 번에 하나의 기능으로 제한합니다. 범위 초과(overreach) 없음. 세 가지를 반쯤 완성하는 일 없음. 미완성 작업을 숨기기 위해 기능 목록을 재작성하는 일 없음.
-- **세션 라이프사이클(Session Lifecycle)** — 시작 시 초기화합니다. 종료 시 정리합니다. 다음 세션을 위한 깨끗한 재시작 경로를 남깁니다.
+- **지시 사항(Instructions)** — 에이전트에게 무엇을, 어떤 순서로, 시작하기 전에 무엇을 읽어야 하는지 알려줍니다. 거대한 단일 파일이 아닌, 에이전트가 필요에 따라 탐색하는 점진적 공개 구조입니다.
+- **상태(State)** — 완료된 작업, 진행 중인 작업, 다음 작업을 추적합니다. 디스크에 영속화되어 다음 세션이 정확히 이전 세션이 중단된 지점에서 이어집니다.
+- **검증(Verification)** — 통과하는 테스트 스위트만 증거로 인정됩니다. 에이전트는 실행 가능한 증명 없이 완료를 선언할 수 없습니다.
+- **범위(Scope)** — 에이전트를 한 번에 하나의 기능으로 제한합니다. 과도한 작업 금지. 세 가지를 반쯤 완성하는 것 금지. 미완료 작업을 숨기기 위해 기능 목록을 재작성하는 것 금지.
+- **세션 수명 주기(Session Lifecycle)** — 시작할 때 초기화. 끝날 때 정리. 다음 세션을 위한 깔끔한 재시작 경로를 남깁니다.
---
-## 이 강의가 존재하는 이유
+## 이 강좌가 존재하는 이유
-질문은 "모델이 코드를 작성할 수 있는가?"가 아닙니다. 모델은 쓸 수 있습니다. 질문은 이것입니다. **모델이 실제 저장소에서 여러 세션에 걸쳐 지속적인 인간 감독 없이 실제 엔지니어링 작업을 안정적으로 완수할 수 있는가?**
+질문은 "모델이 코드를 작성할 수 있는가?"가 아닙니다. 작성할 수 있습니다. 진짜 질문은: **실제 저장소 내에서 여러 세션에 걸쳐 지속적인 인간 감독 없이 실제 엔지니어링 작업을 안정적으로 완료할 수 있는가?**입니다.
-현재 답은 이렇습니다. 하네스 없이는 그렇지 않습니다.
+현재 답은: 하니스 없이는 불가능합니다.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ 하니스 없음 하니스 있음
+ ========= ========
+
+ 세션 1: 에이전트가 코드를 작성 세션 1: 에이전트가 지시 사항을 읽음
+ 에이전트가 테스트를 망가뜨림 에이전트가 init.sh를 실행
+ 에이전트가 "완료"라고 선언 에이전트가 하나의 기능에 집중
+ 사용자가 직접 수정 에이전트가 완료 선언 전 검증
+ 에이전트가 진행 로그를 업데이트
+ 세션 2: 에이전트가 처음부터 시작 에이전트가 깔끔한 상태로 커밋
+ 에이전트에게 이전 기록 없음
+ 에이전트가 작업을 다시 시작 세션 2: 에이전트가 진행 로그를 읽음
+ 또는 전혀 다른 작업을 수행 에이전트가 정확히 중단한 지점부터 이어서 작업
+ 사용자가 또다시 수정 에이전트가 미완료 기능을 계속 진행
+ 사용자는 검토만, 구조 작업은 불필요
+
+ 결과: 직접 했더라면 더 빨랐을 결과: 에이전트가 작업을 수행하고,
+ 작업을 수정하는 데 더 많은 사용자가 결과를 검증
+ 시간을 소비
```
-이 강의가 실제로 다루는 질문들:
+이 강좌가 실제로 다루는 질문들:
-- 어떤 하네스 설계가 작업 완료율을 개선하는가?
-- 어떤 설계가 재작업과 잘못된 완료를 줄이는가?
-- 어떤 메커니즘이 장시간 작업을 꾸준히 진행시키는가?
-- 어떤 구조가 여러 번의 에이전트 실행 후에도 시스템을 유지 관리 가능하게 유지하는가?
+- 어떤 하니스 설계가 작업 완료율을 향상시키는가?
+- 어떤 설계가 재작업 및 잘못된 완료를 줄이는가?
+- 어떤 메커니즘이 장기 실행 작업을 꾸준히 진행되게 유지하는가?
+- 어떤 구조가 여러 에이전트 실행 후에도 시스템을 유지보수 가능하게 만드는가?
---
-## 강의 커리큘럼 및 문서
+## 강의 과정 및 문서
-전체 강의 자료는 **[문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)**에서 확인하십시오.
+전체 강의 자료는 **[문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)**를 방문하세요.
-커리큘럼은 세 부분으로 나뉩니다.
+과정은 세 부분으로 나뉩니다:
-1. **강의(Lectures)**: 하네스 엔지니어링의 이론을 설명하는 12개 개념 단원.
-2. **프로젝트(Projects)**: 처음부터 에이전트 워크스페이스를 구축하는 6개 실습 프로젝트.
-3. **리소스 라이브러리(Resource Library)**: 지금 바로 자신의 저장소에서 사용할 수 있는 복사 준비 완료 템플릿(`AGENTS.md`, `feature_list.json`, `init.sh` 등).
+1. **강의(Lectures)**: Harness engineering 이론을 설명하는 12개의 개념적 단원.
+2. **프로젝트(Projects)**: 처음부터 에이전트 작업 공간을 구축하는 6개의 실습 프로젝트.
+3. **리소스 라이브러리**: 여러분의 저장소에 오늘 바로 사용할 수 있는 복사 가능 템플릿(`AGENTS.md`, `feature_list.json`, `init.sh` 등).
---
-## 빠른 시작: 지금 당장 에이전트를 개선하기
+## 빠른 시작: 오늘 바로 에이전트 개선하기
-가치를 얻기 위해 12개 강의를 모두 읽을 필요는 없습니다. 이미 실제 프로젝트에서 코딩 에이전트를 사용하고 있다면, 지금 바로 개선하는 방법이 있습니다.
+12개의 강의를 모두 읽고 나서 가치를 얻기 시작할 필요가 없습니다. 이미 실제 프로젝트에서 코딩 에이전트를 사용하고 있다면, 지금 당장 개선하는 방법은 다음과 같습니다.
-아이디어는 간단합니다. 프롬프트만 작성하는 대신, 에이전트에게 무엇을 해야 하는지, 무엇이 완료되었는지, 작업을 어떻게 검증하는지를 정의하는 구조화된 파일 집합을 제공하십시오. 이 파일들은 저장소 내부에 위치하므로 모든 세션이 동일한 상태에서 시작합니다.
+핵심 아이디어는 간단합니다: 프롬프트만 작성하는 대신, 무엇을 해야 하는지, 무엇이 완료되었는지, 작업을 어떻게 검증할지 정의하는 구조화된 파일 세트를 에이전트에 제공하세요. 이 파일들은 저장소 내에 있으므로 모든 세션이 동일한 상태에서 시작합니다.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ 프로젝트 루트 디렉토리
+ ├── AGENTS.md <-- 에이전트의 운영 매뉴얼
+ ├── CLAUDE.md <-- (대체, Claude Code 사용 시)
+ ├── init.sh <-- 설치 + 검증 + 시작 실행
+ ├── feature_list.json <-- 어떤 기능이 있는지, 무엇이 완료되었는지
+ ├── claude-progress.md <-- 각 세션에서 무슨 일이 있었는지
+ └── src/ <-- 실제 코드
```
-[리소스 라이브러리](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)에서 시작 템플릿을 가져와 프로젝트에 추가하십시오. 네 개의 파일만으로도 에이전트 세션이 프롬프트만으로 실행하는 것보다 훨씬 안정적이 될 것입니다.
+[리소스 라이브러리](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)에서 스타터 템플릿을 가져와 프로젝트에 넣으세요. 그게 전부입니다. 네 개의 파일만으로 프롬프트만 사용할 때보다 에이전트 세션이 훨씬 더 안정적일 것입니다.
---
## 캡스톤 프로젝트: 실제 앱
-6개의 강의 프로젝트는 모두 동일한 제품을 중심으로 전개됩니다. **Electron 기반 개인 지식 베이스(knowledge base) 데스크탑 앱**입니다.
+6개의 강좌 프로젝트는 모두 동일한 제품을 중심으로 전개됩니다: **Electron 기반 개인 지식 베이스 데스크톱 앱**.
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ 지식 베이스 데스크톱 앱 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ 문서 목록 │ │ Q&A 패널 ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ 질문: 하니스 엔지니어링이란? ││
+ │ │ doc-002.md │ │ 답변: 에이전트 모델 주변에 ││
+ │ │ doc-003.md │ │ 구축된 환경... ││
+ │ │ ... │ │ [출처: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ 상태 표시줄: 42개 문서 | 38개 인덱싱 | 마지막 동기화 3분 전 ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ 핵심 기능:
+ ├── 로컬 문서 가져오기
+ ├── 문서 라이브러리 관리
+ ├── 문서 처리 및 인덱싱
+ ├── 가져온 콘텐츠에 대한 AI 기반 Q&A 실행
+ └── 출처가 포함된 근거 기반 답변 반환
```
-이 프로젝트는 강력한 실용적 가치, 충분한 실제 제품 복잡성, 그리고 하네스 개선 전후를 관찰하기에 적합한 환경을 갖추고 있어 선택되었습니다.
+이 프로젝트는 강력한 실용적 가치, 충분한 실제 제품 복잡성, 그리고 하니스 개선 전후를 관찰하기 좋은 환경을 결합하고 있어 선택되었습니다.
-각 강의 프로젝트의 시작점/풀이는 해당 진화 단계의 이 Electron 앱의 완전한 복사본입니다. P(N+1)의 시작점은 P(N)의 풀이에서 파생됩니다 — 앱은 하네스 기술이 성장함에 따라 함께 진화합니다.
+각 강좌 프로젝트의 스타터/솔루션은 해당 진화 단계의 Electron 앱 전체 사본입니다. P(N+1)의 스타터는 P(N)의 솔루션에서 파생됩니다 — 앱은 여러분의 하니스 기술이 성장함에 따라 함께 진화합니다.
---
## 학습 경로
-강의는 순서대로 진행하도록 설계되었습니다. 각 단계는 이전 단계 위에 구축됩니다.
+이 강좌는 순서대로 진행하도록 설계되었습니다. 각 단계는 이전 단계를 기반으로 구축됩니다.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models != reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ 1단계: 문제 인식 2단계: 저장소 구조화
+ ================ ================
+
+ L01 강력한 모델 ≠ 안정적 실행 L03 저장소를 단일 진실 공급원으로
+ L02 하니스가 실제로 의미하는 것
+ L04 거대한 단일 파일 대신
+ | 여러 파일로 지시 사항 분할
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 프롬프트만 vs. |
+ 규칙 우선 비교 v
+ P02 에이전트 판독 가능 작업 공간
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ 3단계: 세션 연결 4단계: 피드백 및 범위
+ ================ ==================
+
+ L05 세션 간 컨텍스트 유지 L07 명확한 작업 경계 설정
+ L06 모든 에이전트 세션 전
+ 초기화 L08 기능 목록을 하니스 프리미티브로
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 에이전트 동작 교정을 위한
+ P03 다중 세션 연속성 런타임 피드백
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ 5단계: 검증 6단계: 모든 것을 종합
+ ========== ==================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 에이전트가 너무 일찍 L11 에이전트의 런타임을
+ 완료를 선언하지 못하게 방지 관측 가능하게 만들기
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 전체 파이프라인 실행 = L12 모든 세션 종료 시
+ 진정한 검증 깔끔한 인계
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 에이전트가 자체 검증 P06 완전한 하니스 구축
+ (캡스톤 프로젝트)
```
-파트타임으로 진행한다면 각 단계는 약 1주일이 걸립니다. 더 빠르게 진행하려면 1–3단계를 긴 주말 동안 완료할 수 있습니다.
+파트타임으로 진행하면 각 단계는 약 1주일이 소요됩니다. 더 빠르게 진행하고 싶다면 1~3단계는 긴 주말에 완료할 수 있습니다.
---
-## 실라버스
+## 강의 개요
-### 강의 — 12개 개념 단원, 각각 하나의 핵심 질문에 답변
+### 강의 — 각각 하나의 핵심 질문에 답하는 12개의 개념적 단원
-*각 강의의 전체 텍스트는 [문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)에서 읽을 수 있습니다.*
+*각 강의의 전체 내용은 [문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)에서 읽을 수 있습니다.*
| 세션 | 질문 | 핵심 아이디어 |
-|------|------|--------------|
-| [L01](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 강력한 모델이 실제 작업에서 왜 여전히 실패하는가? | 벤치마크와 실제 엔지니어링 사이의 역량 격차 |
-| [L02](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "하네스"는 실제로 무엇을 의미하는가? | 다섯 가지 하위 시스템: 지시사항, 상태, 검증, 범위, 라이프사이클 |
-| [L03](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 왜 저장소가 단일 진실 원천(Single Source of Truth)이어야 하는가? | 에이전트가 볼 수 없으면 존재하지 않는다 |
-| [L04](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 하나의 거대한 지시 파일이 왜 실패하는가? | 점진적 공개: 백과사전이 아닌 지도를 제공하라 |
-| [L05](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 장시간 작업이 왜 연속성(continuity)을 잃는가? | 진행 상황을 디스크에 영속화하고, 중단된 곳에서 재개하라 |
-| [L06](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 초기화가 왜 자체 단계가 필요한가? | 에이전트가 작업을 시작하기 전에 환경이 정상임을 검증하라 |
-| [L07](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 에이전트가 왜 범위를 초과하고 미완성으로 끝나는가? | 한 번에 하나의 기능; 완료의 명시적 정의 |
-| [L08](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 기능 목록이 왜 하네스의 기본 구성 요소인가? | 에이전트가 무시할 수 없는 기계 가독형 범위 경계 |
-| [L09](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 에이전트가 왜 너무 일찍 완료를 선언하는가? | 검증 격차: 신뢰감 ≠ 정확성 |
-| [L10](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 엔드-투-엔드 테스트가 왜 결과를 바꾸는가? | 전체 파이프라인 실행만이 실제 검증으로 인정된다 |
-| [L11](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 가관측성(observability)이 왜 하네스 내부에 있어야 하는가? | 에이전트가 무엇을 했는지 볼 수 없으면 무엇이 잘못되었는지 고칠 수 없다 |
-| [L12](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 왜 모든 세션이 깨끗한 상태를 남겨야 하는가? | 다음 세션의 성공은 이 세션의 정리에 달려 있다 |
-
-### 프로젝트 — 동일한 Electron 앱에 강의 방법을 적용하는 6개 실습 프로젝트
-
-| 프로젝트 | 수행 내용 | 하네스 메커니즘 |
-|---------|----------|----------------|
-| [P01](./docs/projects/project-01-baseline-vs-minimal-harness/index.md) | 동일한 작업을 두 번 실행: 프롬프트만 사용 vs. 규칙 우선 | 최소 하네스: AGENTS.md + init.sh + feature_list.json |
-| [P02](./docs/projects/project-02-agent-readable-workspace/index.md) | 에이전트가 읽을 수 있도록 저장소 재구성 | 에이전트 가독형 워크스페이스 + 영속 상태 파일 |
-| [P03](./docs/projects/project-03-multi-session-continuity/index.md) | 에이전트가 중단된 곳에서 이어받도록 만들기 | 진행 로그 + 세션 핸드오프(handoff) + 다중 세션 연속성 |
-| [P04](./docs/projects/project-04-incremental-indexing/index.md) | 에이전트가 너무 많거나 너무 적게 하지 않도록 막기 | 런타임 피드백 + 범위 제어 + 점진적 인덱싱 |
-| [P05](./docs/projects/project-05-grounded-qa-verification/index.md) | 에이전트가 자신의 작업을 검증하도록 만들기 | 자기 검증 + 근거 기반 Q&A + 증거 기반 완료 |
-| [P06](./docs/projects/project-06-runtime-observability-and-debugging/index.md) | 처음부터 완전한 하네스 구축 (캡스톤 프로젝트) | 완전한 하네스: 모든 메커니즘 + 가관측성 + 절제 연구 |
+|---------|----------|-----------|
+| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 왜 강력한 모델도 실제 작업에서 여전히 실패하는가? | 벤치마크와 실제 엔지니어링 사이의 역량 격차 |
+| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "하니스"는 실제로 무엇을 의미하는가? | 다섯 가지 하위 시스템: 지시 사항, 상태, 검증, 범위, 수명 주기 |
+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 왜 저장소가 단일 진실 공급원이어야 하는가? | 에이전트가 볼 수 없다면 존재하지 않는 것과 같다 |
+| [L04](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 왜 거대한 단일 지시 파일은 실패하는가? | 점진적 공개: 백과사전이 아닌 지도를 제공하라 |
+| [L05](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 왜 장기 실행 작업은 연속성을 잃는가? | 진행 상황을 디스크에 영속화; 중단된 지점에서 이어하기 |
+| [L06](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 왜 초기화에 전용 단계가 필요한가? | 에이전트가 작업을 시작하기 전에 환경이 정상인지 확인 |
+| [L07](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 왜 에이전트는 과도하게 작업하고 불완전하게 마무리하는가? | 한 번에 하나의 기능; 명시적인 완료 정의 |
+| [L08](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 왜 기능 목록이 하니스 프리미티브인가? | 에이전트가 무시할 수 없는 기계 판독 가능 범위 경계 |
+| [L09](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 왜 에이전트는 너무 일찍 완료를 선언하는가? | 검증 격차: 자신감 ≠ 정확성 |
+| [L10](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 왜 엔드투엔드 테스트가 결과를 바꾸는가? | 전체 파이프라인 실행만이 진정한 검증으로 인정된다 |
+| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 왜 관측 가능성이 하니스 내에 있어야 하는가? | 에이전트가 무엇을 했는지 볼 수 없으면, 무엇을 망가뜨렸는지 고칠 수 없다 |
+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 왜 모든 세션은 깔끔한 상태를 남겨야 하는가? | 다음 세션의 성공은 이번 세션의 정리에 달려 있다 |
+
+### 프로젝트 — 동일한 Electron 앱에 강의 방법론을 적용하는 6개의 실습 프로젝트
+
+| 프로젝트 | 수행 내용 | 하니스 메커니즘 |
+|---------|------------|-------------------|
+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | 동일한 작업을 두 번 실행: 프롬프트만 vs. 규칙 우선 | 최소 하니스: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/projects/project-02-agent-readable-workspace/index.md) | 에이전트가 읽을 수 있도록 저장소 재구성 | 에이전트 판독 가능 작업 공간 + 영속적 상태 파일 |
+| [P03](../../docs/projects/project-03-multi-session-continuity/index.md) | 에이전트가 중단된 지점에서 이어가도록 만들기 | 진행 로그 + 세션 인계 + 다중 세션 연속성 |
+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | 에이전트가 너무 많거나 너무 적게 작업하지 않도록 방지 | 런타임 피드백 + 범위 제어 + 점진적 인덱싱 |
+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | 에이전트가 자신의 작업을 검증하도록 만들기 | 자체 검증 + 근거 기반 Q&A + 증거 기반 완료 |
+| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | 처음부터 완전한 하니스 구축 (캡스톤) | 전체 하니스: 모든 메커니즘 + 관측 가능성 + 어블레이션 스터디 |
```text
- PROJECT EVOLUTION
- =================
+ 프로젝트 발전 과정
+ ==================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 프롬프트만 vs. 규칙 우선 문제를 직접 확인합니다
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 에이전트 판독 가능 작업 공간 저장소를 재구성합니다
|
v
- P03 Multi-session continuity You connect sessions
+ P03 다중 세션 연속성 세션을 연결합니다
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 런타임 피드백 및 범위 피드백 루프를 추가합니다
|
v
- P05 Self-verification You make the agent check itself
+ P05 자체 검증 에이전트가 스스로 검증하게 만듭니다
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 완전한 하니스 (캡스톤) 전체 시스템을 구축합니다
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ 각 프로젝트의 솔루션이 다음 프로젝트의 스타터가 됩니다.
+ 앱이 발전합니다. 여러분의 하니스 기술도 함께 성장합니다.
```
### 리소스 라이브러리
-- [한국어 리소스 라이브러리](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료
- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references
- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考
- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス
+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료
- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias
- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références
- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники
@@ -367,135 +378,136 @@ OpenAI도 Codex로 동일한 사실을 보고했습니다. 잘 갖추어진 저
---
-## 에이전트 세션 라이프사이클
+## 에이전트 세션 수명 주기
-이 강의의 핵심 아이디어 중 하나: **에이전트 세션은 자유로운 흐름이 아니라 구조화된 라이프사이클을 따라야 합니다.** 다음은 그 모습입니다.
+이 강좌의 핵심 아이디어 중 하나: **에이전트의 세션은 자유 방임이 아닌 구조화된 수명 주기를 따라야 합니다.** 그 모습은 다음과 같습니다:
```text
- AGENT SESSION LIFECYCLE
+ 에이전트 세션 수명 주기
======================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ 시작 │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. 에이전트가 AGENTS.md / CLAUDE.md를 읽음 │
+ │ 2. 에이전트가 init.sh를 실행 (설치, 검증, 상태 확인) │
+ │ 3. 에이전트가 claude-progress.md를 읽음 (이전 세션 기록) │
+ │ 4. 에이전트가 feature_list.json을 읽음 (완료된 항목, 다음 항목) │
+ │ 5. 에이전트가 git log를 확인 (최근 변경 사항) │
│ │
- │ SELECT │
+ │ 선택 │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. 에이전트가 정확히 하나의 미완료 기능을 선택 │
+ │ 7. 에이전트가 해당 기능에만 작업 │
│ │
- │ EXECUTE │
+ │ 실행 │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. 에이전트가 기능을 구현 │
+ │ 9. 에이전트가 검증을 실행 (테스트, 린트, 타입 검사) │
+ │ 10. 검증 실패 시: 수정 후 재실행 │
+ │ 11. 검증 통과 시: 증거를 기록 │
│ │
- │ WRAP UP │
+ │ 마무리 │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. 에이전트가 claude-progress.md를 업데이트 │
+ │ 13. 에이전트가 feature_list.json을 업데이트 │
+ │ 14. 에이전트가 여전히 망가져 있거나 미검증된 항목을 기록 │
+ │ 15. 에이전트가 커밋 (안전하게 재개 가능할 때만) │
+ │ 16. 에이전트가 다음 세션을 위한 깔끔한 재시작 경로를 남김 │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ 하니스가 이 수명 주기의 모든 전환을 제어합니다.
+ 모델은 각 단계에서 어떤 코드를 작성할지 결정합니다.
+ 하니스가 없으면 9단계는 "에이전트가 괜찮아 보인다고 말함"이 됩니다.
+ 하니스가 있으면 9단계는 "테스트 통과, 린트 깔끔함, 타입 검사 통과"가 됩니다.
```
---
-## 대상 독자
+## 이 강좌의 대상
-이 강의는 다음 분들을 위한 것입니다.
+이 강좌는 다음 분들을 위한 것입니다:
-- 더 나은 안정성과 품질을 원하는 코딩 에이전트 사용자
-- 하네스 설계에 대한 체계적인 이해를 원하는 연구자 또는 빌더
-- 환경 설계가 에이전트 성능에 미치는 영향을 이해해야 하는 기술 리드
+- 이미 코딩 에이전트를 사용 중이며 더 나은 안정성과 품질을 원하는 엔지니어
+- 하니스 설계에 대한 체계적인 이해를 원하는 연구자 또는 빌더
+- 환경 설계가 에이전트 성능에 미치는 영향을 이해해야 하는 기술 리더
-이 강의는 다음 분들을 위한 것이 아닙니다.
+이 강좌는 다음 분들에게 적합하지 않습니다:
- 코드 없는 AI 입문을 찾는 분
-- 프롬프트에만 관심이 있고 실제 구현을 구축할 계획이 없는 분
-- 에이전트가 실제 저장소에서 작업하도록 허용할 준비가 되어 있지 않은 학습자
+- 프롬프트에만 관심이 있고 실제 구현을 계획하지 않는 분
+- 에이전트가 실제 저장소 내에서 작업하도록 할 준비가 되지 않은 학습자
---
## 요구 사항
-이 강의는 실제로 코딩 에이전트를 실행하는 강의입니다.
+이 강좌는 실제로 코딩 에이전트를 실행하는 강좌입니다.
-다음 도구 중 최소 하나가 필요합니다.
+다음 도구 중 최소 하나가 필요합니다:
- Claude Code
- Codex
- 파일 편집, 명령 실행, 다단계 작업을 지원하는 다른 IDE 또는 CLI 코딩 에이전트
-강의는 다음이 가능하다고 가정합니다.
+이 강좌는 다음이 가능하다고 가정합니다:
- 로컬 저장소 열기
- 에이전트가 파일을 편집하도록 허용
- 에이전트가 명령을 실행하도록 허용
-- 출력을 검사하고 작업 재실행
+- 출력을 검사하고 작업을 재실행
-그러한 도구가 없어도 강의 콘텐츠를 읽을 수 있지만 의도한 대로 프로젝트를 완료할 수는 없습니다.
+해당 도구가 없는 경우에도 강좌 내용을 읽을 수 있지만, 의도된 대로 프로젝트를 완료할 수는 없습니다.
---
## 로컬 미리보기
-이 저장소는 VitePress를 문서 뷰어로 사용합니다.
+이 저장소는 문서 뷰어로 VitePress를 사용합니다.
```sh
npm install
-npm run docs:dev # 핫 리로드가 있는 개발 서버
+npm run docs:dev # 핫 리로드가 포함된 개발 서버
npm run docs:build # 프로덕션 빌드
npm run docs:preview # 빌드된 사이트 미리보기
```
-VitePress가 출력하는 로컬 URL을 브라우저에서 여십시오.
+그런 다음 브라우저에서 VitePress가 출력하는 로컬 URL을 여세요.
---
-## 사전 요건
+## 사전 요구 사항
필수:
-- 터미널, git, 로컬 개발 환경에 대한 친숙함
-- 일반적인 애플리케이션 스택에서 코드를 읽고 쓸 수 있는 능력
+- 터미널, git, 로컬 개발 환경에 대한 친숙도
+- 최소 하나의 일반적인 애플리케이션 스택에서 코드 읽기 및 쓰기 능력
- 기본적인 소프트웨어 디버깅 경험 (로그, 테스트, 런타임 동작 읽기)
-- 구현 중심 강의에 전념할 충분한 시간
+- 구현 중심의 강좌 작업에 투자할 충분한 시간
도움이 되지만 필수는 아님:
-- Electron, 데스크탑 앱, 또는 로컬 우선 도구 경험
-- 테스트, 로깅, 또는 소프트웨어 아키텍처 배경
-- Codex, Claude Code, 또는 유사한 코딩 에이전트에 대한 사전 노출
+- Electron, 데스크톱 앱 또는 로컬 우선 도구에 대한 경험
+- 테스팅, 로깅 또는 소프트웨어 아키텍처에 대한 배경지식
+- Codex, Claude Code 또는 유사한 코딩 에이전트에 대한 사전 경험
---
## 핵심 참고 자료
-주요:
+주요 자료:
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)
+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)
+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-보충:
-
-- [LangChain: The Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)
-- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
-- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
+계층화된 전체 참고 문헌 목록은 [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md)에서 확인하세요.
---
@@ -511,38 +523,56 @@ learn-harness-engineering/
│ ├── projects/ # 6개 프로젝트 설명
│ │ ├── project-01-*/
│ │ └── ... (총 6개)
-│ └── resources/ # 다국어 템플릿 및 참고 자료
+│ └── resources/ # 다국어 템플릿 및 참조 자료
│ ├── en/ # 영어 템플릿, 체크리스트, 가이드
│ ├── zh/ # 중국어 템플릿, 체크리스트, 가이드
│ ├── ru/ # 러시아어 템플릿, 체크리스트, 가이드
│ └── vi/ # 베트남어 템플릿, 체크리스트, 가이드
├── projects/
│ ├── shared/ # 공유 Electron + TypeScript + React 기반
-│ └── project-NN/ # 프로젝트별 starter/ 및 solution/ 디렉터리
+│ └── project-NN/ # 프로젝트별 starter/ 및 solution/ 디렉토리
├── skills/ # 재사용 가능한 AI 에이전트 스킬
-│ └── harness-creator/ # 하네스 엔지니어링 스킬
+│ └── harness-creator/ # Harness engineering 스킬
├── package.json # VitePress + 개발 도구
-└── CLAUDE.md # 이 저장소에 대한 Claude Code 지시사항
+└── CLAUDE.md # 이 저장소의 Claude Code 지침
```
---
-## 강의 구성 방식
+## 강좌 구성 방식
- 각 강의는 하나의 질문에 집중합니다
-- 강의는 6개의 프로젝트를 포함합니다
+- 강좌에는 6개의 프로젝트가 포함됩니다
- 모든 프로젝트는 에이전트가 실제 작업을 수행하도록 요구합니다
-- 모든 프로젝트는 약한 하네스 대 강한 하네스 결과를 비교합니다
+- 모든 프로젝트는 약한 하니스와 강한 하니스의 결과를 비교합니다
- 중요한 것은 작성된 문서의 양이 아니라 측정된 차이입니다
---
-## Star History
+## 스킬
+
+이 저장소에는 IDE나 에이전트 작업 공간에 직접 설치할 수 있는 재사용 가능한 AI 에이전트 스킬도 포함되어 있습니다.
+
+- [**harness-creator**](../../skills/harness-creator/): 몇 분 만에 여러분의 프로젝트에 프로덕션급 하니스를 스캐폴딩하는 스킬.
+
+---
+
+## 다른 강좌
+
+저희 팀은 다른 강좌도 만들었습니다! 확인해 보세요:
+
+[![Hands-on Modern RL](https://img.shields.io/badge/HANDS--ON_MODERN_RL-0052cc?style=for-the-badge)](https://github.com/walkinglabs/hands-on-modern-rl)
+
+**Hands-on Modern RL**: 기본 RL 개념부터 LLM 정렬, RLVR, 고급 에이전트 시스템까지 이어지는 오픈소스 실습 커리큘럼.
+
+---
+
+## 스타 히스토리
[![Star History Chart](https://api.star-history.com/svg?repos=walkinglabs/learn-harness-engineering&type=date&legend=top-left)](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)
---
-## 감사의 말
+## 감사의 글
-이 강의는 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)에서 영감을 받았으며, 아이디어를 차용했습니다. 이 프로젝트는 단일 루프에서 격리된 자율 실행까지 처음부터 에이전트를 구축하기 위한 점진적 가이드입니다.
+이 강좌는 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)에서 영감을 받고 아이디어를 얻었습니다 — 단일 루프에서 격리된 자율 실행까지, 에이전트를 처음부터 구축하는 점진적 가이드입니다.
diff --git a/README-RU.md b/README-RU.md
index 00d0707..003bd0e 100644
--- a/README-RU.md
+++ b/README-RU.md
@@ -84,22 +84,23 @@ OpenAI сообщает то же самое с Codex: в хорошо подг
**Этот курс научит вас, как построить такое окружение.**
```text
- THE HARNESS PATTERN
- ====================
+ ПАТТЕРН HARNESS
+ ================
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
+ Вы --> даёте задачу --> Агент читает файлы harness --> Агент выполняет
+ |
+ harness управляет каждым шагом:
|
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
+ +--> Инструкции: что делать, в каком порядке
+ +--> Область: одна фича за раз, без превышения
+ +--> Состояние: лог прогресса, список фич, история git
+ +--> Верификация: тесты, линт, проверка типов, smoke-запуски
+ +--> Жизненный инициализация при старте, чистое
+ цикл: состояние в конце
|
v
- Agent stops only when
- verification passes
+ Агент останавливается
+ только когда верификация пройдена
```
---
@@ -112,32 +113,34 @@ Harness состоит из пяти подсистем:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Инструкции │ │ Состояние │ │ Верификация │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ тесты + линт │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ проверка типов │ │
+ │ │ feature_list │ │ git log │ │ smoke-запуски │ │
+ │ │ docs/ │ │ передача │ │ e2e pipeline │ │
+ │ │ │ │ сессии │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Область │ │ Жизненный цикл сессии │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ одна фича │ │ init.sh при старте │ │
+ │ │ за раз │ │ чек-лист чистого состояния в конце │ │
+ │ │ определение │ │ заметка-передача для след. сессии │ │
+ │ │ «готово» │ │ коммит только когда безопасно │ │
+ │ │ │ │ для возобновления │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ МОДЕЛЬ решает, какой код писать.
+ HARNESS управляет тем, когда, где и как она его пишет.
+ Harness не делает модель умнее.
+ Он делает вывод модели надёжным.
```
Каждая подсистема выполняет свою задачу:
@@ -157,25 +160,27 @@ Harness состоит из пяти подсистем:
На данный момент ответ: нет без harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
-
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ БЕЗ HARNESS С HARNESS
+ ========== =========
+
+ Сессия 1: агент пишет код Сессия 1: агент читает инструкции
+ агент ломает тесты агент запускает init.sh
+ агент говорит «готово» агент работает над одной фичей
+ вы исправляете вручную агент верифицирует перед тем
+ как сообщить о готовности
+ агент обновляет лог прогресса
+
+ Сессия 2: агент начинает с чистого агент фиксирует чистое состояние
+ листа
+ у агента нет памяти Сессия 2: агент читает лог прогресса
+ о том, что было раньше агент продолжает точно с того места
+ агент переделывает работу где остановился
+ или делает что-то совсем другое агент продолжает незавершённую фичу
+ вы исправляете снова вы проверяете, а не спасаете
+
+ Результат: вы тратите больше Результат: агент делает работу,
+ времени на исправления, вы проверяете результат
+ чем если бы сделали сами
```
Вопросы, которые действительно волнуют этот курс:
@@ -206,10 +211,10 @@ Harness состоит из пяти подсистем:
Идея проста: вместо того чтобы писать только промпты, дайте своему агенту набор структурированных файлов, определяющих, что нужно сделать, что уже сделано и как проверить результат. Эти файлы находятся в вашем репозитории, поэтому каждая сессия стартует из одного и того же состояния.
```text
- YOUR PROJECT ROOT
+ КОРНЕВАЯ ПАПКА ВАШЕГО ПРОЕКТА
├── AGENTS.md <-- операционное руководство агента
├── CLAUDE.md <-- (альтернатива, если вы используете Claude Code)
- ├── init.sh <-- выполняет install + verify + start
+ ├── init.sh <-- выполняет установку + верификацию + запуск
├── feature_list.json <-- какие фичи существуют, какие выполнены
├── claude-progress.md <-- что произошло в каждой сессии
└── src/ <-- ваш фактический код
@@ -225,28 +230,30 @@ Harness состоит из пяти подсистем:
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Десктоп-приложение «База знаний» │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ Список │ │ Панель вопросов ││
+ │ │ документов │ │ и ответов ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ В: Что такое harness eng? ││
+ │ │ doc-002.md │ │ О: Окружение, построенное ││
+ │ │ doc-003.md │ │ вокруг агентной модели...││
+ │ │ ... │ │ [источник: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Строка состояния: 42 док. | 38 индекс. | синхр. ││
+ │ │ 3 мин. назад ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Основные возможности:
+ ├── Импорт локальных документов
+ ├── Управление библиотекой документов
+ ├── Обработка и индексирование документов
+ ├── AI-вопросы и ответы по импортированному контенту
+ └── Обоснованные ответы с источниками
```
Этот проект выбран потому, что он сочетает высокую практическую пользу, достаточную реальную продуктовую сложность и хороший сценарий для наблюдения улучшений harness (до/после).
@@ -260,47 +267,49 @@ Harness состоит из пяти подсистем:
Курс рассчитан на последовательное прохождение. Каждая фаза строится на предыдущей.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
- v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
-
-
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
-
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ Фаза 1: УВИДЕТЬ ПРОБЛЕМУ Фаза 2: СТРУКТУРИРОВАТЬ РЕПОЗИТОРИЙ
+ ========================== ===================================
+
+ L01 Сильные модели ≠ надёжное L03 Репозиторий как единственный
+ выполнение источник истины
+ L02 Что на самом деле означает
+ harness L04 Разнести инструкции по файлам,
+ а не один гигантский файл
+ |
+ v |
+ P01 Только промпт vs. v
+ подход на основе правил P02 Агентно-читаемое рабочее
+ пространство
+
+
+ Фаза 3: СВЯЗАТЬ СЕССИИ Фаза 4: ОБРАТНАЯ СВЯЗЬ И ОБЛАСТЬ
+ ========================= ================================
+
+ L05 Сохранять контекст живым L07 Чёткие границы задач
+ между сессиями
+ L08 Списки фич как примитивы
+ L06 Инициализация перед каждой harness
+ сессией агента
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Runtime-обратная связь
+ P03 Мультисессионная связность для корректировки поведения
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ Фаза 5: ВЕРИФИКАЦИЯ Фаза 6: СОБРАТЬ ВСЁ ВМЕСТЕ
+ =================== ==========================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
-
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L09 Остановить агентов от L11 Сделать runtime агента
+ преждевременного объявления наблюдаемым
+ победы
+ L12 Чистая передача в конце
+ L10 Полный прогон pipeline = каждой сессии
+ настоящая верификация
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 Агент верифицирует P06 Построить полный harness
+ собственную работу (итоговый проект)
```
Каждая фаза занимает примерно неделю при обучении параллельно с основной работой. Если двигаться быстрее, фазы 1–3 можно пройти за длинные выходные.
@@ -340,28 +349,32 @@ Harness состоит из пяти подсистем:
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Построить полный harness с нуля (итоговый проект) | Полный harness: все механизмы + observability + абляционное исследование |
```text
- PROJECT EVOLUTION
+ ЭВОЛЮЦИЯ ПРОЕКТОВ
=================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Только промпт vs. подход Вы видите проблему
+ на основе правил
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Агентно-читаемое рабочее Вы реструктурируете репозиторий
+ пространство
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Мультисессионная связность Вы связываете сессии
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Runtime-обратная связь и Вы добавляете циклы обратной
+ область связи
|
v
- P05 Self-verification You make the agent check itself
+ P05 Самоверификация Вы заставляете агента проверять
+ самого себя
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Полный harness (итоговый) Вы строите полную систему
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Solution каждого проекта становится starter'ом следующего.
+ Приложение эволюционирует. Ваши навыки harness растут вместе с ним.
```
### Библиотека шаблонов
@@ -386,44 +399,44 @@ Harness состоит из пяти подсистем:
Одна из ключевых идей этого курса: **сессия агента должна следовать структурированному жизненному циклу, а не быть свободным плаванием.** Вот как это выглядит:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ ЖИЗНЕННЫЙ ЦИКЛ СЕССИИ АГЕНТА
+ =============================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ СТАРТ │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Агент читает AGENTS.md / CLAUDE.md │
+ │ 2. Агент запускает init.sh (установка, верификация, проверка) │
+ │ 3. Агент читает claude-progress.md (что было в прошлый раз) │
+ │ 4. Агент читает feature_list.json (что готово, что дальше) │
+ │ 5. Агент проверяет git log (недавние изменения) │
│ │
- │ SELECT │
+ │ ВЫБОР │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Агент выбирает ровно ОДНУ незавершённую фичу │
+ │ 7. Агент работает только над этой фичей │
│ │
- │ EXECUTE │
+ │ ВЫПОЛНЕНИЕ │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Агент реализует фичу │
+ │ 9. Агент запускает верификацию (тесты, линт, проверка типов) │
+ │ 10. Если верификация не прошла: исправить и запустить снова │
+ │ 11. Если верификация прошла: зафиксировать результат │
│ │
- │ WRAP UP │
+ │ ЗАВЕРШЕНИЕ │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Агент обновляет claude-progress.md │
+ │ 13. Агент обновляет feature_list.json │
+ │ 14. Агент записывает, что всё ещё сломано или не верифицировано│
+ │ 15. Агент делает коммит (только когда безопасно возобновлять) │
+ │ 16. Агент оставляет чистый путь перезапуска для след. сессии │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness управляет каждым переходом в этом жизненном цикле.
+ Модель решает, какой код писать на каждом шаге.
+ Без harness шаг 9 превращается в «агент говорит, что всё выглядит нормально».
+ С harness шаг 9 — это «тесты пройдены, линт чист, типы в порядке».
```
---
diff --git a/README-UZ.md b/README-UZ.md
index a143dfe..f131a93 100644
--- a/README-UZ.md
+++ b/README-UZ.md
@@ -84,22 +84,22 @@ OpenAI Codex bilan xuddi shu haqida xabar berdi: yaxshi harnesslangan repozitori
**Ushbu kurs sizga shu muhitni qanday qurishni oʻrgatadi.**
```text
- THE HARNESS PATTERN
- ====================
+ HARNESS NAMUNASI
+ ================
- You --> give task --> Agent reads harness files --> Agent executes
+ Siz --> vazifa berasiz --> Agent harness fayllarini oʻqiydi --> Agent bajaradi
+ |
+ harness har bir qadamni boshqaradi:
|
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ +--> Koʻrsatmalar: nima qilish, qanday tartibda
+ +--> Doira: bir vaqtda bitta funksiya, haddan oshmaslik
+ +--> Holat: taraqqiyot jurnali, funksiya roʻyxati, git tarixi
+ +--> Tekshiruv: testlar, lint, tur-tekshirish, sinov ishga tushirish
+ +--> Hayot sikli: boshida ishga tushirish, oxirida toza holat
+ |
+ v
+ Agent faqat tekshiruv
+ oʻtganda toʻxtaydi
```
---
@@ -112,32 +112,32 @@ Harnessʼning beshta quyi tizimi bor:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Koʻrsatmalar │ │ Holat │ │ Tekshiruv │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ testlar + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ tur-tekshirish │ │
+ │ │ feature_list │ │ git log │ │ sinov ishga tushirish│ │
+ │ │ docs/ │ │ sessiya uzat │ │ e2e pipeline │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Doira │ │ Sessiya hayot sikli │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ bir vaqtda │ │ boshida init.sh │ │
+ │ │ bitta funksiya│ │ oxirida toza-holat tekshiruv roʻyxati│ │
+ │ │ "tugadi" │ │ keyingi sessiya uchun uzatish yozuvi │ │
+ │ │ taʼrifi │ │ faqat xavfsiz davom ettirishda commit│ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ MODEL qanday kod yozishni hal qiladi.
+ HARNESS qachon, qayerda va qanday yozishni boshqaradi.
+ Harness modelni aqlliroq qilmaydi.
+ U model natijasini ishonchli qiladi.
```
Har bir quyi tizimning oʻz vazifasi bor:
@@ -157,24 +157,24 @@ Savol "Model lar kod yozoladimi?" emas. Yozoladi. Haqiqiy savol: **Ular haqiqiy
Hozircha javob: harnessʼsiz — yoʻq.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ HARNESSʼSIZ HARNESS BILAN
+ ============ ============
+
+ 1-sessiya: agent kod yozadi 1-sessiya: agent koʻrsatmalarni oʻqiydi
+ agent testlarni buzadi agent init.sh ni ishga tushiradi
+ agent "tugadi" deydi agent bitta funksiya ustida ishlaydi
+ siz qoʻlbola tuzatasiz agent "tugadi" deyishdan oldin tekshiradi
+ agent taraqqiyot jurnalini yangilaydi
+ 2-sessiya: agent yangidan boshlaydi agent toza holatni commit qiladi
+ agentning xotirasi yoʻq
+ oldin nima boʻlganini 2-sessiya: agent taraqqiyot jurnalini oʻqiydi
+ agent ishni qayta qiladi agent aynan toʻxtagan joydan davom etadi
+ yoki butunlay boshqa narsa qiladi agent tugallanmagan funksiyani davom ettiradi
+ siz yana tuzatasiz siz koʻrib chiqasiz, qutqarmaysiz
+
+ Natija: siz oʻzingiz qilganingizdan Natija: agent ishni bajaradi,
+ koʻra koʻproq vaqtni siz natijani tekshirasiz
+ tuzatishga sarflaysiz
```
Bu kursni qiziqtiradigan haqiqiy savollar:
@@ -205,10 +205,10 @@ Foyda olish uchun 12 ta maʼruzani ham oʻqish shart emas. Agar siz allaqachon h
Gʻoya oddiy: faqat promptʼlar yozish oʻrniga, agentingizga nima qilish kerak, nima allaqachon qilingan va ish qanday tekshirilishini belgilovchi strukturaviy fayllar toʻplamini bering. Bu fayllar repozitoriyangizda joylashgan, shunda har bir sessiya bir xil holatdan boshlanadi.
```text
- YOUR PROJECT ROOT
+ LOYIHANGIZNING ILDIZ PAPKASI
├── AGENTS.md <-- agentning ish qoʻllanmasi
├── CLAUDE.md <-- (Claude Code ishlatganingizda alternativa)
- ├── init.sh <-- install + verify + start ni bajaradi
+ ├── init.sh <-- oʻrnatish + tekshirish + ishga tushirishni bajaradi
├── feature_list.json <-- qanday funksiyalar mavjud, qaysilari tugallangan
├── claude-progress.md <-- har bir sessiyada nima boʻlgani
└── src/ <-- sizning haqiqiy kodingiz
@@ -224,28 +224,29 @@ Oltita kurs loyihasi bir xil mahsulot atrofida qurilgan: **Electron asosidagi sh
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Bilim bazasi desktop ilovasi │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Hujjatlar │ │ S&S paneli ││
+ │ │ roʻyxati │ │ ││
+ │ │ │ │ S: Harness eng nima? ││
+ │ │ doc-001.md │ │ J: Agent modeli atrofida ││
+ │ │ doc-002.md │ │ qurilgan muhit... ││
+ │ │ doc-003.md │ │ [manba: doc-002.md] ││
+ │ │ ... │ │ ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Holat paneli: 42 hujjat | 38 indekslangan | soʻnggi sinxronizatsiya 3d ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Asosiy funksiyalar:
+ ├── Mahalliy hujjatlarni import qilish
+ ├── Hujjatlar kutubxonasini boshqarish
+ ├── Hujjatlarni qayta ishlash va indekslash
+ ├── Import qilingan kontent ustida KI asosidagi S&S oʻtkazish
+ └── Manbalar bilan asoslangan javoblarni qaytarish
```
Bu loyiha shuning uchun tanlanganki, u yuqori amaliy foyda, yetarli haqiqiy mahsulot murakkabligi va harness yaxshilanishlarini kuzatish uchun yaxshi stsenariyani oʻzida birlashtiradi.
@@ -259,47 +260,47 @@ Har bir kurs loyihasi (boshlangʻich/yechim) ushbu Electron ilovasining mos rivo
Kurs xronologik tartibda bajarish uchun moʻljallangan. Har bir bosqich oldingisiga asoslanadi.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ 1-bosqich: MUAMMONI KOʻRISH 2-bosqich: REPONI TUZISH
+ =========================== ========================
+
+ L01 Kuchli modellar ≠ ishonchli L03 Repo yagona haqiqat
+ bajarish manbai sifatida
+ L02 Harness nima degani haqiqatan
+ L04 Koʻrsatmalarni bitta ulkan
+ | faylga emas, bir nechta faylga boʻlish
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Faqat prompt vs. |
+ qoidalarga asoslangan solishtirish v
+ P02 Agent oʻqiy oladigan ish muhiti
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ 3-bosqich: SESSIYALARNI BOGʻLASH 4-bosqich: FIKR-MULOHAZA VA DOIRA
+ ================================ ================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Kontekstni sessiyalar L07 Aniq vazifa chegaralarini chizish
+ orasida saqlash
+ L08 Funksiya roʻyxatlari harness
+ L06 Har bir agent sessiyasidan primitivlari sifatida
+ oldin ishga tushirish
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
-
-
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ v P04 Agent xatti-harakatini
+ P03 Koʻp sessiyali uzluksizlik tuzatish uchun runtime fikr-mulohaza
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ 5-bosqich: TEKSHIRUV 6-bosqich: HAMMASINI BIRGA JAMQILISH
+ =================== ===================================
- | |
- v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ L09 Agentlarga erta L11 Agent runtime'ini
+ muvaffaqiyat haqida xabar kuzatiladigan qilish
+ berishiga toʻsqinlik qilish
+ L12 Har bir sessiya oxirida
+ L10 Toʻliq pipeline ishga toza uzatish
+ tushirish = haqiqiy tekshiruv
+ |
+ | v
+ v P06 Toʻliq harness qurish
+ P05 Agent oʻz ishini mustaqil tekshiradi (yakuniy loyiha)
```
Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar tezroq borishni xohlasangiz, 1–3 bosqichlarni bitta uzun dam olish kunlarida tugatishingiz mumkin.
@@ -339,28 +340,28 @@ Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Toʻliq harnessʼni noldan qurish (yakuniy loyiha) | Toʻliq harness: barcha mexanizmlar + kuzatuvchanlik + ablyatsiya tadqiqoti |
```text
- PROJECT EVOLUTION
- =================
+ LOYIHA RIVOJLANISHI
+ ===================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Faqat prompt vs. qoidalarga asoslangan Siz muammoni koʻrasiz
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Agent oʻqiy oladigan ish muhiti Siz repolarni qayta tuzasiz
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Koʻp sessiyali uzluksizlik Siz sessiyalarni bogʻlaysiz
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Runtime fikr-mulohaza va doira Siz fikr-mulohaza halqalarini qoʻshasiz
|
v
- P05 Self-verification You make the agent check itself
+ P05 Oʻz-oʻzini tekshirish Siz agentni oʻz-oʻzini tekshirishga majburlaysiz
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Toʻliq harness (yakuniy loyiha) Siz toʻliq tizimni qurasiz
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Har bir loyihaning yechimi keyingi loyihaning boshlangʻichiga aylanadi.
+ Ilova rivojlanadi. Harness koʻnikmalaringiz unga qarab oʻsadi.
```
### Andozalar kutubxonasi
@@ -385,44 +386,44 @@ Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar
Ushbu kursning asosiy gʻoyalaridan biri: **Agent sessiyasi tuzilgan hayot sikliga amal qilishi kerak, emas xohlagancha ishlashiga.** Bu quyidagicha koʻrinadi:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ AGENT SESSIYA HAYOT SIKLI
+ =========================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ BOSHLASH │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agent AGENTS.md / CLAUDE.md faylini oʻqiydi │
+ │ 2. Agent init.sh ni ishga tushiradi (oʻrnatish, tekshirish, sogʻliqni nazorat)│
+ │ 3. Agent claude-progress.md ni oʻqiydi (oxirgi safar nima boʻldi)│
+ │ 4. Agent feature_list.json ni oʻqiydi (nima tugadi, keyin nima)│
+ │ 5. Agent git log ni tekshiradi (soʻnggi oʻzgarishlar) │
│ │
- │ SELECT │
+ │ TANLASH │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agent aynan BITTA tugallanmagan funksiyani tanlaydi │
+ │ 7. Agent faqat shu funksiya ustida ishlaydi │
│ │
- │ EXECUTE │
+ │ BAJARISH │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agent funksiyani amalga oshiradi │
+ │ 9. Agent tekshiruvni ishga tushiradi (testlar, lint, tur-tekshirish)│
+ │ 10. Agar tekshiruv oʻtmasa: tuzatish va qayta ishga tushirish │
+ │ 11. Agar tekshiruv oʻtsa: dalilni qayd etish │
│ │
- │ WRAP UP │
+ │ YAKUNLASH │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agent claude-progress.md ni yangilaydi │
+ │ 13. Agent feature_list.json ni yangilaydi │
+ │ 14. Agent hali buzilgan yoki tekshirilmagan narsalarni qayd etadi│
+ │ 15. Agent commit qiladi (faqat xavfsiz davom ettirishda) │
+ │ 16. Agent keyingi sessiya uchun toza qayta boshlash yoʻlini qoldiradi│
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness ushbu hayot siklidagi har bir oʻtishni boshqaradi.
+ Model har bir qadamda qanday kod yozishni hal qiladi.
+ Harnessʼsiz 9-qadam "agent yaxshi koʻrinadi deydi" ga aylanadi.
+ Harness bilan 9-qadam "testlar oʻtdi, lint toza, turlar tekshirildi" boʻladi.
```
---
diff --git a/README-VI.md b/README-VI.md
index e869e3a..e555f47 100644
--- a/README-VI.md
+++ b/README-VI.md
@@ -84,22 +84,22 @@ OpenAI cũng báo cáo điều tương tự với Codex: trong một kho mã đ
**Khóa học này dạy bạn cách xây dựng môi trường đó.**
```text
- THE HARNESS PATTERN
- ====================
+ MÔ HÌNH HARNESS
+ ===============
- You --> give task --> Agent reads harness files --> Agent executes
+ Bạn --> giao tác vụ --> Agent đọc tệp harness --> Agent thực thi
|
- harness governs every step:
+ harness điều phối mọi bước:
|
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
+ +--> Hướng dẫn: làm gì, theo thứ tự nào
+ +--> Phạm vi: một tính năng mỗi lần, không vượt quá
+ +--> Trạng thái: nhật ký tiến trình, danh sách tính năng, lịch sử git
+ +--> Kiểm chứng: bài kiểm tra, lint, kiểm tra kiểu, chạy thử
+ +--> Vòng đời: khởi tạo lúc bắt đầu, trạng thái sạch lúc kết thúc
|
v
- Agent stops only when
- verification passes
+ Agent chỉ dừng khi
+ kiểm chứng đạt yêu cầu
```
---
@@ -112,32 +112,32 @@ Một harness có năm hệ thống con:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Hướng dẫn │ │ Trạng thái │ │ Kiểm chứng │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ kiểm tra kiểu │ │
+ │ │ feature_list │ │ git log │ │ chạy thử │ │
+ │ │ docs/ │ │ bàn giao phiên│ │ pipeline e2e │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Phạm vi │ │ Vòng đời phiên │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ một tính │ │ init.sh lúc bắt đầu │ │
+ │ │ năng mỗi lần │ │ danh sách kiểm tra sạch lúc kết thúc │ │
+ │ │ định nghĩa │ │ ghi chú bàn giao cho phiên tiếp │ │
+ │ │ "hoàn thành" │ │ commit chỉ khi an toàn để tiếp tục │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ MÔ HÌNH quyết định viết code gì.
+ HARNESS điều phối khi nào, ở đâu và viết như thế nào.
+ Harness không làm mô hình thông minh hơn.
+ Nó làm đầu ra của mô hình đáng tin cậy hơn.
```
Mỗi hệ thống con có một nhiệm vụ duy nhất:
@@ -157,24 +157,24 @@ Câu hỏi không phải là "mô hình có thể viết code không?" Chúng c
Hiện tại, câu trả lời là: không thể nếu không có harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ KHÔNG CÓ HARNESS CÓ HARNESS
+ ================ ==========
+
+ Phiên 1: agent viết code Phiên 1: agent đọc hướng dẫn
+ agent làm hỏng bài kiểm tra agent chạy init.sh
+ agent nói "xong rồi" agent làm một tính năng
+ bạn tự sửa thủ công agent kiểm chứng trước khi nói xong
+ agent cập nhật nhật ký tiến trình
+ Phiên 2: agent bắt đầu lại từ đầu agent commit trạng thái sạch
+ agent không nhớ
+ những gì đã xảy ra trước đó Phiên 2: agent đọc nhật ký tiến trình
+ agent làm lại từ đầu agent tiếp tục chính xác nơi đã dừng
+ hoặc làm hoàn toàn việc khác agent tiếp tục tính năng chưa xong
+ bạn lại phải sửa lại bạn đánh giá, không phải cứu vãn
+
+ Kết quả: bạn dành nhiều thời gian Kết quả: agent làm công việc,
+ dọn dẹp hơn là nếu bạn bạn kiểm chứng kết quả
+ tự làm lấy
```
Những câu hỏi mà khóa học này thực sự quan tâm:
@@ -205,13 +205,13 @@ Bạn không cần phải đọc cả 12 bài giảng trước khi bắt đầu
Ý tưởng rất đơn giản: thay vì chỉ viết prompt, hãy cho agent của bạn một bộ tệp có cấu trúc xác định phải làm gì, những gì đã làm, và cách kiểm chứng công việc. Các tệp này nằm trong kho mã của bạn, vì vậy mỗi phiên bắt đầu từ cùng một trạng thái.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ THƯ MỤC GỐC DỰ ÁN CỦA BẠN
+ ├── AGENTS.md <-- sổ tay vận hành của agent
+ ├── CLAUDE.md <-- (thay thế, nếu dùng Claude Code)
+ ├── init.sh <-- chạy cài đặt + xác minh + khởi động
+ ├── feature_list.json <-- tính năng nào tồn tại, cái nào đã xong
+ ├── claude-progress.md <-- những gì đã xảy ra trong mỗi phiên
+ └── src/ <-- code thực tế của bạn
```
Lấy các mẫu khởi đầu từ [Thư viện tài nguyên](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) và đưa chúng vào dự án của bạn. Đó là tất cả. Bốn tệp, và các phiên agent của bạn sẽ đã ổn định hơn đáng kể so với việc chỉ chạy trên prompt.
@@ -224,28 +224,29 @@ Tất cả sáu dự án khóa học đều xoay quanh cùng một sản phẩm:
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Ứng dụng Desktop Cơ sở Tri thức │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Danh sách tài │ │ Bảng Hỏi-Đáp ││
+ │ │ liệu │ │ ││
+ │ │ doc-001.md │ │ H: Harness engineering là gì?││
+ │ │ doc-002.md │ │ Đ: Môi trường được xây dựng ││
+ │ │ doc-003.md │ │ quanh một mô hình agent...││
+ │ │ ... │ │ [trích dẫn: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Thanh trạng thái: 42 tài liệu | 38 đã lập chỉ │││
+ │ │ mục | đồng bộ lần cuối 3p │││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Tính năng cốt lõi:
+ ├── Nhập tài liệu cục bộ
+ ├── Quản lý thư viện tài liệu
+ ├── Xử lý và lập chỉ mục tài liệu
+ ├── Chạy Hỏi-Đáp AI trên nội dung đã nhập
+ └── Trả lời có căn cứ kèm trích dẫn
```
Dự án này được chọn vì nó kết hợp giá trị thực tế cao, đủ độ phức tạp sản phẩm thực tế, và môi trường tốt để quan sát sự cải thiện harness trước/sau.
@@ -259,47 +260,47 @@ Mỗi starter/solution của dự án khóa học là một bản sao hoàn ch
Khóa học được thiết kế để hoàn thành theo thứ tự. Mỗi giai đoạn xây dựng dựa trên giai đoạn trước.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ Giai đoạn 1: NHÌN VẤN ĐỀ Giai đoạn 2: TỔ CHỨC KHO MÃ
+ ========================= ===========================
+
+ L01 Mô hình mạnh ≠ thực thi L03 Kho mã là nguồn
+ đáng tin cậy chân lý duy nhất
+ L02 Harness thực sự nghĩa là gì
+ L04 Chia hướng dẫn thành nhiều
+ | tệp, không phải một tệp khổng lồ
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Chỉ dùng prompt vs. |
+ ưu tiên quy tắc v
+ P02 Không gian làm việc agent đọc được
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ Giai đoạn 3: KẾT NỐI CÁC PHIÊN Giai đoạn 4: PHẢN HỒI & PHẠM VI
+ ============================== ================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Giữ ngữ cảnh sống L07 Vẽ ranh giới tác vụ rõ ràng
+ qua các phiên
+ L08 Danh sách tính năng như
+ L06 Khởi tạo trước mọi nguyên thủy harness
+ phiên agent
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Phản hồi thời gian chạy
+ P03 Tính liên tục đa phiên sửa hành vi agent
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ Giai đoạn 5: KIỂM CHỨNG Giai đoạn 6: TỔNG HỢP TẤT CẢ
+ ========================= =============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 Ngăn agent tuyên bố L11 Làm thời gian chạy của
+ hoàn thành quá sớm agent có thể quan sát
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 Chạy toàn bộ pipeline = L12 Bàn giao sạch ở cuối
+ kiểm chứng thực sự mọi phiên
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 Agent tự kiểm chứng P06 Xây dựng harness hoàn chỉnh
+ (dự án tổng kết)
```
Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gian. Nếu bạn muốn đi nhanh hơn, các giai đoạn 1-3 có thể hoàn thành trong một cuối tuần dài.
@@ -339,28 +340,31 @@ Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gia
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Xây dựng một harness hoàn chỉnh từ đầu (tổng kết) | Harness đầy đủ: tất cả cơ chế + khả năng quan sát + nghiên cứu ablation |
```text
- PROJECT EVOLUTION
- =================
+ SỰ PHÁT TRIỂN DỰ ÁN
+ ===================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Chỉ dùng prompt vs. ưu tiên Bạn nhìn thấy vấn đề
+ quy tắc
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Không gian làm việc Bạn tái cấu trúc kho mã
+ agent đọc được
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Tính liên tục đa phiên Bạn kết nối các phiên
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Phản hồi & phạm vi Bạn thêm các vòng phản hồi
+ thời gian chạy
|
v
- P05 Self-verification You make the agent check itself
+ P05 Tự kiểm chứng Bạn khiến agent tự kiểm tra
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Harness hoàn chỉnh (tổng kết) Bạn xây dựng hệ thống đầy đủ
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Solution của mỗi dự án trở thành starter của dự án tiếp theo.
+ Ứng dụng phát triển. Kỹ năng harness của bạn lớn lên cùng nó.
```
### Thư viện tài nguyên
@@ -385,44 +389,44 @@ Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gia
Một trong những ý tưởng cốt lõi trong khóa học này: **phiên của agent nên tuân theo một vòng đời có cấu trúc, không phải tự do không kiểm soát.** Đây là cách nó trông như thế này:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ VÒNG ĐỜI PHIÊN AGENT
+ ====================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ BẮT ĐẦU │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agent đọc AGENTS.md / CLAUDE.md │
+ │ 2. Agent chạy init.sh (cài đặt, xác minh, kiểm tra sức khỏe) │
+ │ 3. Agent đọc claude-progress.md (đã xảy ra gì lần trước) │
+ │ 4. Agent đọc feature_list.json (cái gì xong, cái gì tiếp) │
+ │ 5. Agent kiểm tra git log (thay đổi gần đây) │
│ │
- │ SELECT │
+ │ CHỌN TÁC VỤ │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agent chọn chính xác MỘT tính năng chưa hoàn thành │
+ │ 7. Agent chỉ làm việc trên tính năng đó │
│ │
- │ EXECUTE │
+ │ THỰC THI │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agent triển khai tính năng │
+ │ 9. Agent chạy kiểm chứng (bài kiểm tra, lint, kiểm tra kiểu) │
+ │ 10. Nếu kiểm chứng thất bại: sửa và chạy lại │
+ │ 11. Nếu kiểm chứng đạt: ghi nhận bằng chứng │
│ │
- │ WRAP UP │
+ │ KẾT THÚC │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agent cập nhật claude-progress.md │
+ │ 13. Agent cập nhật feature_list.json │
+ │ 14. Agent ghi lại những gì vẫn còn lỗi hoặc chưa kiểm chứng │
+ │ 15. Agent commit (chỉ khi an toàn để tiếp tục) │
+ │ 16. Agent để lại đường khởi động lại sạch cho phiên tiếp │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness điều phối mọi chuyển đổi trong vòng đời này.
+ Mô hình quyết định viết code gì ở mỗi bước.
+ Không có harness, bước 9 trở thành "agent nói trông ổn rồi."
+ Có harness, bước 9 là "bài kiểm tra đạt, lint sạch, kiểu đúng."
```
---
diff --git a/README-ZH-TW.md b/README-ZH-TW.md
index 53f644c..e767fb1 100644
--- a/README-ZH-TW.md
+++ b/README-ZH-TW.md
@@ -84,22 +84,22 @@ OpenAI 也報告了 Codex 的相同結果:在一個 well-harnessed 的儲存
**這門課程教你如何建構那個環境。**
```text
- THE HARNESS PATTERN
- ====================
+ HARNESS 模式
+ ============
- You --> give task --> Agent reads harness files --> Agent executes
+ 你 --> 給定任務 --> 代理讀取 harness 檔案 --> 代理執行
|
- harness governs every step:
+ harness 管控每個步驟:
|
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
+ +--> 指令:該做什麼,以什麼順序
+ +--> 範圍:一次一個功能,不過度延伸
+ +--> 狀態:進度日誌、功能列表、git 歷史
+ +--> 驗證:測試、lint、型別檢查、冒煙測試
+ +--> 生命週期:開始時初始化,結束時乾淨狀態
|
v
- Agent stops only when
- verification passes
+ 代理只在驗證通過時
+ 才會停止
```
---
@@ -112,32 +112,32 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS 系統 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ 指令 │ │ 狀態 │ │ 驗證 │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ 測試 + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ 型別檢查 │ │
+ │ │ feature_list │ │ git log │ │ 冒煙測試 │ │
+ │ │ docs/ │ │ 工作階段交接 │ │ 端到端流程 │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ 範圍 │ │ 工作階段生命週期 │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ 一次一個功能 │ │ 開始時執行 init.sh │ │
+ │ │ 明確的完成 │ │ 結束時使用乾淨狀態檢查清單 │ │
+ │ │ 定義 │ │ 為下一個工作階段留下交接筆記 │ │
+ │ │ │ │ 只在可安全恢復時才提交 │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ 模型決定要寫什麼程式碼。
+ HARNESS 管控何時、在哪裡、以及如何撰寫。
+ Harness 不會讓模型變得更聰明。
+ 它讓模型的輸出變得可靠。
```
每個子系統各有其職責:
@@ -157,24 +157,23 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
目前的答案是:沒有 harness 就不行。
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ 沒有 HARNESS 有 HARNESS
+ ============== ============
+
+ 工作階段 1:代理撰寫程式碼 工作階段 1:代理讀取指令
+ 代理破壞了測試 代理執行 init.sh
+ 代理說「完成了」 代理只做一個功能
+ 你手動修復 代理在宣告完成前先驗證
+ 代理更新進度日誌
+ 工作階段 2:代理從頭開始 代理提交乾淨狀態
+ 代理沒有記憶
+ 不知道之前發生了什麼 工作階段 2:代理讀取進度日誌
+ 代理重做工作 代理精確地從上次停止處接續
+ 或者做完全不同的事情 代理繼續未完成的功能
+ 你再次修復 你是審查,不是搶救
+
+ 結果:你花在清理的時間 結果:代理做工作,
+ 比自己動手做還多 你驗證結果
```
這門課程真正關心的問題:
@@ -205,7 +204,7 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
概念很簡單:與其只寫提示,不如給你的代理一組結構化的檔案,定義該做什麼、已經做了什麼、以及如何驗證工作。這些檔案存在你的儲存庫中,所以每個工作階段都從相同的狀態開始。
```text
- YOUR PROJECT ROOT
+ 你的專案根目錄
├── AGENTS.md <-- 代理的操作手冊
├── CLAUDE.md <-- (替代方案,如果使用 Claude Code)
├── init.sh <-- 執行安裝 + 驗證 + 啟動
@@ -224,28 +223,28 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ 知識庫桌面應用程式 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ 文件列表 │ │ 問答面板 ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ 問:什麼是 harness 工程? ││
+ │ │ doc-002.md │ │ 答:圍繞代理模型建構的 ││
+ │ │ doc-003.md │ │ 環境...... ││
+ │ │ ... │ │ [引用來源:doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ 狀態列:42 篇文件 | 38 篇已索引 | 上次同步 3 分鐘前││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ 核心功能:
+ ├── 匯入本地文件
+ ├── 管理文件庫
+ ├── 處理和索引文件
+ ├── 對匯入內容執行 AI 問答
+ └── 回傳有依據的答案與引用來源
```
選擇這個專案是因為它結合了強大的實用價值、足夠的真實產品複雜度,以及觀察 harness 改善前後差異的良好場景。
@@ -259,47 +258,42 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
課程設計為按順序進行。每個階段建立在前一個階段之上。
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
- v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ 階段 1:看見問題 階段 2:建構儲存庫結構
+ =================== ========================
+ L01 強大的模型 ≠ 可靠的執行 L03 儲存庫作為唯一真實來源
+ L02 Harness 到底是什麼意思
+ L04 將指令分散到多個檔案,
+ | 而非一個巨大檔案
+ v
+ P01 僅提示 vs. 規則優先比較 |
+ v
+ P02 代理可讀的工作空間
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
- |
- | v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ 階段 3:連接工作階段 階段 4:回饋與範圍
+ ======================= ==================
+ L05 跨工作階段保持上下文 L07 劃清任務邊界
+ L06 每次代理工作階段前初始化 L08 功能列表作為 harness
+ 基本元素
+ |
+ v P04 執行時回饋修正
+ P03 多工作階段連續性 代理行為
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ 階段 5:驗證 階段 6:整合所有內容
+ ================= ========================
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L09 阻止代理過早宣告勝利 L11 讓代理的執行時行為
+ 可觀測
+ L10 完整流程執行 = L12 每個工作階段結束時
+ 真正的驗證 乾淨的交接
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 代理驗證自己的工作 P06 建構完整的 harness
+ (畢業專案)
```
如果你是兼職學習,每個階段大約需要一週。如果你想加快速度,階段 1-3 可以在一個長週末完成。
@@ -339,28 +333,28 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | 從零建構一個完整的 harness(畢業專案) | 完整 harness:所有機制 + 可觀測性 + 消融實驗 |
```text
- PROJECT EVOLUTION
- =================
+ 專案演進
+ ========
- P01 Prompt-only vs. rules-first You see the problem
+ P01 僅提示 vs. 規則優先 你看見問題
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 代理可讀的工作空間 你重構儲存庫
|
v
- P03 Multi-session continuity You connect sessions
+ P03 多工作階段連續性 你連接工作階段
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 執行時回饋與範圍控制 你加入回饋迴圈
|
v
- P05 Self-verification You make the agent check itself
+ P05 自我驗證 你讓代理檢查自己
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 完整 harness(畢業專案) 你建構完整系統
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ 每個專案的 solution 成為下一個專案的 starter。
+ 應用程式在演化。你的 harness 技能也隨之成長。
```
### 資源庫
@@ -385,44 +379,44 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
這門課程的核心理念之一:**代理的工作階段應該遵循結構化的生命週期,而不是隨意進行。** 以下是它的樣貌:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ 代理工作階段生命週期
+ ===================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ 開始 │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. 代理讀取 AGENTS.md / CLAUDE.md │
+ │ 2. 代理執行 init.sh(安裝、驗證、健康檢查) │
+ │ 3. 代理讀取 claude-progress.md(上次發生了什麼事) │
+ │ 4. 代理讀取 feature_list.json(什麼已完成,什麼是下一步) │
+ │ 5. 代理檢查 git log(最近的變更) │
│ │
- │ SELECT │
+ │ 選擇 │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. 代理精確挑選一個未完成的功能 │
+ │ 7. 代理只做那個功能 │
│ │
- │ EXECUTE │
+ │ 執行 │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. 代理實作該功能 │
+ │ 9. 代理執行驗證(測試、lint、型別檢查) │
+ │ 10. 如果驗證失敗:修復並重新執行 │
+ │ 11. 如果驗證通過:記錄證據 │
│ │
- │ WRAP UP │
+ │ 收尾 │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. 代理更新 claude-progress.md │
+ │ 13. 代理更新 feature_list.json │
+ │ 14. 代理記錄仍然損壞或未驗證的部分 │
+ │ 15. 代理提交(只在可安全恢復時) │
+ │ 16. 代理為下一個工作階段留下乾淨的重啟路徑 │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness 管控這個生命週期中的每個轉換。
+ 模型決定在每個步驟寫什麼程式碼。
+ 沒有 harness 時,步驟 9 變成「代理說看起來沒問題」。
+ 有了 harness 時,步驟 9 是「測試通過、lint 乾淨、型別檢查通過」。
```
---
diff --git a/docs-readme/ar-SA/README.md b/docs-readme/ar-SA/README.md
index 9264ef2..aca0598 100644
--- a/docs-readme/ar-SA/README.md
+++ b/docs-readme/ar-SA/README.md
@@ -84,22 +84,22 @@
**هذه الدورة تعلّمك كيف تبني تلك البيئة.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ نمط الحزام
+ ===========
+
+ أنت --> تعطي مهمة --> الوكيل يقرأ ملفات الحزام --> الوكيل ينفذ
+ |
+ الحزام يحكم كل خطوة:
+ |
+ +--> التعليمات: ماذا يفعل، بأي ترتيب
+ +--> النطاق: ميزة واحدة في كل مرة، بلا تجاوز
+ +--> الحالة: سجل التقدم، قائمة الميزات، سجل git
+ +--> التحقق: اختبارات، تنسيق، فحص أنواع، تشغيل تجريبي
+ +--> دورة الحياة: تهيئة في البداية، حالة نظيفة في النهاية
+ |
+ v
+ الوكيل يتوقف فقط عندما
+ يجتاز التحقق
```
---
@@ -112,32 +112,32 @@
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ الحزام │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ التعليمات │ │ الحالة │ │ التحقق │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ اختبارات + تنسيق │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ فحص أنواع │ │
+ │ │ feature_list │ │ سجل git │ │ تشغيل تجريبي │ │
+ │ │ docs/ │ │ تسليم جلسة │ │ خط أنابيب شامل │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ النطاق │ │ دورة حياة الجلسة │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ ميزة واحدة │ │ init.sh في البداية │ │
+ │ │ في كل مرة │ │ قائمة حالة نظيفة في النهاية │ │
+ │ │ تعريف │ │ ملاحظة تسليم للجلسة التالية │ │
+ │ │ الإتمام │ │ التزام فقط عندما يكون آمناً للاستئناف │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ النموذج يقرر أي كود يكتبه.
+ الحزام يحكم متى وأين وكيف يكتبه.
+ الحزام لا يجعل النموذج أذكى.
+ بل يجعل مخرجات النموذج موثوقة.
```
لكل نظام فرعي وظيفة واحدة:
@@ -157,24 +157,24 @@
حالياً، الإجابة هي: ليس بدون حزام.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ بدون حزام مع حزام
+ ========= ======
+
+ الجلسة 1: الوكيل يكتب كوداً الجلسة 1: الوكيل يقرأ التعليمات
+ الوكيل يكسر الاختبارات الوكيل يشغّل init.sh
+ الوكيل يقول "تم" الوكيل يعمل على ميزة واحدة
+ أنت تصلحه يدوياً الوكيل يتحقق قبل أن يدّعي الإتمام
+ الوكيل يحدّث سجل التقدم
+ الجلسة 2: الوكيل يبدأ من الصفر الوكيل يلتزم حالة نظيفة
+ الوكيل ليس لديه ذاكرة
+ لما حدث سابقاً الجلسة 2: الوكيل يقرأ سجل التقدم
+ الوكيل يعيد العمل الوكيل يكمل من حيث توقف بالضبط
+ أو يقوم بشيء آخر تماماً الوكيل يواصل الميزة غير المكتملة
+ أنت تصلحه مرة أخرى أنت تراجع، لا تنقذ
+
+ النتيجة: أنت تقضي وقتاً أطول النتيجة: الوكيل يقوم بالعمل،
+ في الإصلاح مما لو كنت وأنت تتحقق من النتيجة
+ فعلت ذلك بنفسك
```
الأسئلة التي تهتم بها هذه الدورة فعلياً:
@@ -205,13 +205,13 @@
الفكرة بسيطة: بدلاً من مجرد كتابة الموجهات، أعطِ وكيلك مجموعة من الملفات المنظمة التي تحدد ما يجب فعله، ما تم إنجازه، وكيفية التحقق من العمل. هذه الملفات تعيش داخل مستودعك، لذا تبدأ كل جلسة من نفس الحالة.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ الجذر الرئيسي لمشروعك
+ ├── AGENTS.md <-- دليل تشغيل الوكيل
+ ├── CLAUDE.md <-- (بديل، إذا كنت تستخدم Claude Code)
+ ├── init.sh <-- يشغّل التثبيت + التحقق + البدء
+ ├── feature_list.json <-- الميزات الموجودة، أيها مكتمل
+ ├── claude-progress.md <-- ما حدث في كل جلسة
+ └── src/ <-- الكود الفعلي الخاص بك
```
احصل على القوالب الأولية من [مكتبة الموارد](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) وأضفها إلى مشروعك. هذا كل شيء. أربعة ملفات، وستكون جلسات وكيلك أكثر استقراراً بشكل ملحوظ مقارنة بالاعتماد على الموجهات وحدها.
@@ -224,28 +224,28 @@
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ تطبيق سطح مكتب لقاعدة المعرفة │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ قائمة المستندات│ │ لوحة الأسئلة والأجوبة ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ س: ما هي هندسة الحزام؟ ││
+ │ │ doc-002.md │ │ ج: البيئة المبنية ││
+ │ │ doc-003.md │ │ حول نموذج وكيل... ││
+ │ │ ... │ │ [استشهاد: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ شريط الحالة: 42 مستند | 38 مفهرس | آخر مزامنة 3د ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ الميزات الأساسية:
+ ├── استيراد المستندات المحلية
+ ├── إدارة مكتبة المستندات
+ ├── معالجة وفهرسة المستندات
+ ├── تشغيل أسئلة وأجوبة مدعومة بالذكاء الاصطناعي على المحتوى المستورد
+ └── إرجاع إجابات مبنية على أدلة مع استشهادات
```
تم اختيار هذا المشروع لأنه يجمع بين قيمة عملية قوية، تعقيد كافٍ في المنتج الحقيقي، وبيئة جيدة لمراقبة تحسينات الحزام قبل وبعد.
@@ -259,47 +259,48 @@
الدورة مصممة لتُنفذ بالترتيب. كل مرحلة تبني على سابقتها.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ المرحلة 1: شاهد المشكلة المرحلة 2: هيكل المستودع
+ ======================= ========================
+
+ L01 النماذج القوية ≠ تنفيذ L03 المستودع كمصدر
+ موثوق وحيد للحقيقة
+ L02 ماذا يعني الحزام فعلياً
+ L04 قسّم التعليمات عبر
+ | ملفات، لا ملف ضخم واحد
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 بالموجهات فقط مقابل |
+ القواعد أولاً v
+ P02 مساحة عمل قابلة للقراءة
+ بواسطة الوكيل
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ المرحلة 3: ربط الجلسات المرحلة 4: التغذية الراجعة والنطاق
+ ========================== ==================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 أبقِ السياق حياً L07 ارسم حدود مهام واضحة
+ عبر الجلسات
+ L08 قوائم الميزات كعناصر
+ L06 التهيئة قبل كل أساسية للحزام
+ جلسة وكيل
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 تغذية راجعة وقت التشغيل
+ P03 استمرارية متعددة الجلسات لتصحيح سلوك الوكيل
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ المرحلة 5: التحقق المرحلة 6: اجمع كل شيء
+ ===================== ========================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 أوقف الوكلاء عن L11 اجعل بيئة تشغيل الوكيل
+ إعلان النصر مبكراً قابلة للملاحظة
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 تشغيل خط أنابيب كامل = L12 تسليم نظيف في نهاية
+ تحقق حقيقي كل جلسة
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 الوكيل يتحقق من عمله بنفسه P06 ابنِ حزاماً كاملاً
+ (مشروع التخرج)
```
كل مرحلة تستغرق حوالي أسبوع إذا كنت تعمل بدوام جزئي. إذا كنت تريد السرعة، يمكن إنجاز المراحل 1-3 في عطلة نهاية أسبوع طويلة.
@@ -339,28 +340,28 @@
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | ابنِ حزاماً كاملاً من الصفر (مشروع التخرج) | حزام كامل: جميع الآليات + قابلية الملاحظة + دراسة الاستئصال |
```text
- PROJECT EVOLUTION
- =================
+ تطور المشاريع
+ =============
- P01 Prompt-only vs. rules-first You see the problem
+ P01 بالموجهات فقط مقابل القواعد أولاً أنت ترى المشكلة
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 مساحة عمل قابلة للقراءة بواسطة الوكيل أنت تعيد هيكلة المستودع
|
v
- P03 Multi-session continuity You connect sessions
+ P03 استمرارية متعددة الجلسات أنت تربط الجلسات
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 تغذية راجعة وقت التشغيل والنطاق أنت تضيف حلقات التغذية الراجعة
|
v
- P05 Self-verification You make the agent check itself
+ P05 التحقق الذاتي أنت تجعل الوكيل يتحقق من نفسه
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 حزام كامل (مشروع التخرج) أنت تبني النظام الكامل
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ حل كل مشروع يصبح بداية المشروع التالي.
+ التطبيق يتطور. مهاراتك في الحزام تنمو معه.
```
### مكتبة الموارد
@@ -385,44 +386,44 @@
إحدى الأفكار الأساسية في هذه الدورة: **يجب أن تتبع جلسة الوكيل دورة حياة منظمة، وليست عشوائية.** إليك كيف تبدو:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ دورة حياة جلسة الوكيل
+ =====================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ البداية │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. الوكيل يقرأ AGENTS.md / CLAUDE.md │
+ │ 2. الوكيل يشغّل init.sh (تثبيت، تحقق، فحص صحي) │
+ │ 3. الوكيل يقرأ claude-progress.md (ما حدث في المرة السابقة) │
+ │ 4. الوكيل يقرأ feature_list.json (ما تم إنجازه، ما هو التالي) │
+ │ 5. الوكيل يفحص سجل git (التغييرات الأخيرة) │
│ │
- │ SELECT │
+ │ الاختيار │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. الوكيل يختار ميزة واحدة غير مكتملة بالضبط │
+ │ 7. الوكيل يعمل على تلك الميزة فقط │
│ │
- │ EXECUTE │
+ │ التنفيذ │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. الوكيل ينفّذ الميزة │
+ │ 9. الوكيل يشغّل التحقق (اختبارات، تنسيق، فحص أنواع) │
+ │ 10. إذا فشل التحقق: إصلاح وإعادة التشغيل │
+ │ 11. إذا نجح التحقق: تسجيل الدليل │
│ │
- │ WRAP UP │
+ │ الختام │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. الوكيل يحدّث claude-progress.md │
+ │ 13. الوكيل يحدّث feature_list.json │
+ │ 14. الوكيل يسجّل ما زال معطلاً أو غير مُتحقق منه │
+ │ 15. الوكيل يلتزم (فقط عندما يكون آمناً للاستئناف) │
+ │ 16. الوكيل يترك مسار إعادة تشغيل نظيف للجلسة التالية │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ الحزام يحكم كل انتقال في دورة الحياة هذه.
+ النموذج يقرر أي كود يكتبه في كل خطوة.
+ بدون الحزام، الخطوة 9 تصبح "الوكيل يقول يبدو جيداً."
+ مع الحزام، الخطوة 9 هي "الاختبارات تجتاز، التنسيق نظيف، الأنواع صحيحة."
```
---
diff --git a/docs-readme/de-DE/README.md b/docs-readme/de-DE/README.md
index 084e35d..9d4aec9 100644
--- a/docs-readme/de-DE/README.md
+++ b/docs-readme/de-DE/README.md
@@ -84,22 +84,22 @@ OpenAI berichtete dasselbe mit Codex: in einem gut geharnischten Repository wech
**Dieser Kurs bringt Ihnen bei, wie Sie diese Umgebung aufbauen.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ DAS HARNESS-MUSTER
+ ==================
+
+ Sie --> Aufgabe geben --> Agent liest Harness-Dateien --> Agent führt aus
+ |
+ Harness steuert jeden Schritt:
+ |
+ +--> Anweisungen: was zu tun ist, in welcher Reihenfolge
+ +--> Umfang: ein Feature nach dem anderen, keine Übergriffe
+ +--> Zustand: Fortschrittslog, Feature-Liste, Git-Verlauf
+ +--> Verifizierung: Tests, Lint, Typprüfung, Smoke-Runs
+ +--> Lebenszyklus: Initialisierung am Start, sauberer Zustand am Ende
+ |
+ v
+ Agent stoppt nur, wenn
+ Verifizierung bestanden ist
```
---
@@ -112,32 +112,32 @@ Ein Harness hat fünf Subsysteme:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ DAS HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Anweisungen │ │ Zustand │ │ Verifizierung │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ Tests + Lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ Typprüfung │ │
+ │ │ feature_list │ │ git log │ │ Smoke-Runs │ │
+ │ │ docs/ │ │ Session-Übg. │ │ E2E-Pipeline │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Umfang │ │ Session-Lebenszyklus │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ ein Feature │ │ init.sh am Start │ │
+ │ │ nach dem and.│ │ Clean-State-Checkliste am Ende │ │
+ │ │ Definition │ │ Übergabenotiz für nächste Session │ │
+ │ │ von Fertig │ │ Commit nur wenn sicher fortsetzbar │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ Das MODELL entscheidet, welcher Code geschrieben wird.
+ Das HARNESS steuert, wann, wo und wie es geschrieben wird.
+ Das Harness macht das Modell nicht schlauer.
+ Es macht die Ausgabe des Modells zuverlässig.
```
Jedes Subsystem hat eine Aufgabe:
@@ -157,24 +157,24 @@ Die Frage ist nicht „Können Modelle Code schreiben?" Sie können. Die Frage i
Im Moment lautet die Antwort: nicht ohne ein Harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ OHNE HARNESS MIT HARNESS
+ =========== ===========
+
+ Session 1: Agent schreibt Code Session 1: Agent liest Anweisungen
+ Agent zerstört Tests Agent führt init.sh aus
+ Agent sagt "fertig" Agent arbeitet an einem Feature
+ Sie reparieren manuell Agent verifiziert vor Fertig-Meldung
+ Agent aktualisiert Fortschrittslog
+ Session 2: Agent startet neu Agent committet sauberen Zustand
+ Agent hat keine Erinnerung
+ an vorherige Session Session 2: Agent liest Fortschrittslog
+ Agent macht Arbeit neu Agent setzt genau dort fort
+ oder macht etwas ganz anderes Agent bearbeitet das unfertige Feature
+ Sie reparieren wieder Sie überprüfen, statt zu retten
+
+ Ergebnis: Sie verbringen mehr Zeit Ergebnis: Agent erledigt die Arbeit,
+ mit Aufräumen, als wenn Sie verifizieren das Ergebnis
+ Sie es selbst gemacht hätten
```
Die Fragen, die dieser Kurs wirklich interessieren:
@@ -205,7 +205,7 @@ Sie müssen nicht alle 12 Vorlesungen lesen, bevor Sie einen Nutzen ziehen. Wenn
Die Idee ist einfach: Anstatt nur Prompts zu schreiben, geben Sie Ihrem Agenten einen Satz strukturierter Dateien, die definieren, was zu tun ist, was bereits erledigt ist und wie die Arbeit verifiziert wird. Diese Dateien befinden sich in Ihrem Repo, sodass jede Session vom gleichen Zustand ausgeht.
```text
- YOUR PROJECT ROOT
+ IHR PROJEKT-ROOT
├── AGENTS.md <-- das Betriebshandbuch des Agenten
├── CLAUDE.md <-- (Alternative, wenn Sie Claude Code verwenden)
├── init.sh <-- führt install + verify + start aus
@@ -224,28 +224,28 @@ Alle sechs Kursprojekte drehen sich um dasselbe Produkt: **eine Electron-basiert
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Wissensdatenbank-Desktop-App │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Dokumenten- │ │ F&A-Panel ││
+ │ │ liste │ │ ││
+ │ │ doc-001.md │ │ F: Was ist Harness Eng.? ││
+ │ │ doc-002.md │ │ A: Die Umgebung, die um ││
+ │ │ doc-003.md │ │ ein Agentenmodell... ││
+ │ │ ... │ │ [Zitat: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Statusleiste: 42 Doks | 38 indiziert | letzte Sync 3m ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Kernfunktionen:
+ ├── Lokale Dokumente importieren
+ ├── Eine Dokumentenbibliothek verwalten
+ ├── Dokumente verarbeiten und indizieren
+ ├── KI-gestützte F&A über importierte Inhalte ausführen
+ └── Fundierte Antworten mit Quellnachweisen liefern
```
Dieses Projekt wurde gewählt, weil es hohen praktischen Nutzen, ausreichende reale Produktkomplexität und ein gutes Szenario für die Beobachtung von Harness-Verbesserungen (Vorher/Nachher) verbindet.
@@ -259,47 +259,47 @@ Jedes Kursprojekt (Starter/Lösung) ist eine vollständige Kopie dieser Electron
Der Kurs ist für die chronologische Abarbeitung konzipiert. Jede Phase baut auf der vorherigen auf.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ Phase 1: DAS PROBLEM ERKENNEN Phase 2: DAS REPO STRUKTURIEREN
+ ============================== ===============================
+
+ L01 Starke Modelle ≠ zuverlässige L03 Repository als einzige
+ Ausführung Wahrheitsquelle
+ L02 Was ein Harness wirklich bedeutet
+ L04 Anweisungen auf mehrere
+ | Dateien aufteilen, nicht eine riesige
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Nur-Prompt vs. |
+ regelbasierter Vergleich v
+ P02 Agentenlesbarer Arbeitsbereich
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ Phase 3: SESSIONS VERBINDEN Phase 4: FEEDBACK & UMFANG
+ =========================== =========================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Kontext über Sessions hinweg L07 Klare Aufgabengrenzen ziehen
+ lebendig halten
+ L08 Feature-Listen als Harness-
+ L06 Vor jeder Agenten-Session Primitive
+ initialisieren
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Laufzeit-Feedback zur
+ P03 Multi-Session-Kontinuität Korrektur des Agentenverhaltens
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ Phase 5: VERIFIZIERUNG Phase 6: ALLES ZUSAMMENFÜHREN
+ ======================= ==============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 Agenten davon abhalten, L11 Laufzeit des Agenten
+ zu früh Erfolg zu melden beobachtbar machen
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 Vollständiger Pipeline-Lauf = L12 Saubere Übergabe am Ende
+ echte Verifizierung jeder Session
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 Agent verifiziert seine P06 Ein vollständiges Harness
+ eigene Arbeit aufbauen (Abschlussprojekt)
```
Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller vorgehen möchten, können die Phasen 1–3 an einem langen Wochenende absolviert werden.
@@ -339,28 +339,28 @@ Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Ein vollständiges Harness von Grund auf neu aufbauen (Abschlussprojekt) | Vollständiges Harness: alle Mechanismen + Observability + Ablationsstudie |
```text
- PROJECT EVOLUTION
- =================
+ PROJEKTENTWICKLUNG
+ ==================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Nur-Prompt vs. regelbasiert Sie erkennen das Problem
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Agentenlesbarer Arbeitsbereich Sie restrukturieren das Repo
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Multi-Session-Kontinuität Sie verbinden Sessions
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Laufzeit-Feedback & Umfang Sie fügen Feedback-Schleifen hinzu
|
v
- P05 Self-verification You make the agent check itself
+ P05 Selbstverifizierung Sie lassen den Agenten sich selbst prüfen
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Vollständiges Harness (Abschluss) Sie bauen das Gesamtsystem
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Die Lösung jedes Projekts wird zum Starter des nächsten Projekts.
+ Die App entwickelt sich weiter. Ihre Harness-Fähigkeiten wachsen mit.
```
### Vorlagen-Bibliothek
@@ -385,44 +385,44 @@ Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller
Eine der Kernideen dieses Kurses: **Die Session eines Agenten sollte einem strukturierten Lebenszyklus folgen, keinem Freifür-alle.** So sieht das aus:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ AGENTEN-SESSION-LEBENSZYKLUS
+ ============================
┌──────────────────────────────────────────────────────────────────┐
│ START │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agent liest AGENTS.md / CLAUDE.md │
+ │ 2. Agent führt init.sh aus (Installieren, Verifizieren, Check) │
+ │ 3. Agent liest claude-progress.md (was letztes Mal passierte) │
+ │ 4. Agent liest feature_list.json (was erledigt, was als Nächstes)│
+ │ 5. Agent prüft git log (letzte Änderungen) │
│ │
- │ SELECT │
+ │ AUSWAHL │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agent wählt genau EIN unfertiges Feature aus │
+ │ 7. Agent arbeitet nur an diesem Feature │
│ │
- │ EXECUTE │
+ │ AUSFÜHRUNG │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agent implementiert das Feature │
+ │ 9. Agent führt Verifizierung aus (Tests, Lint, Typprüfung) │
+ │ 10. Wenn Verifizierung fehlschlägt: korrigieren und neu ausf. │
+ │ 11. Wenn Verifizierung bestanden: Beweise dokumentieren │
│ │
- │ WRAP UP │
+ │ ABSCHLUSS │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agent aktualisiert claude-progress.md │
+ │ 13. Agent aktualisiert feature_list.json │
+ │ 14. Agent dokumentiert, was noch kaputt oder unverifiziert ist │
+ │ 15. Agent committet (nur wenn sicher fortsetzbar) │
+ │ 16. Agent hinterlässt sauberen Neustartpfad für nächste Session│
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Das Harness steuert jeden Übergang in diesem Lebenszyklus.
+ Das Modell entscheidet, welcher Code bei jedem Schritt geschrieben wird.
+ Ohne Harness wird Schritt 9 zu „Agent sagt, es sieht gut aus."
+ Mit Harness ist Schritt 9: „Tests bestanden, Lint sauber, Typen geprüft."
```
---
diff --git a/docs-readme/es-ES/README.md b/docs-readme/es-ES/README.md
index a1d9826..8f6e4c8 100644
--- a/docs-readme/es-ES/README.md
+++ b/docs-readme/es-ES/README.md
@@ -84,22 +84,22 @@ OpenAI reportó lo mismo con Codex: en un repositorio bien equipado con un harne
**Este curso te enseña cómo construir ese entorno.**
```text
- THE HARNESS PATTERN
- ====================
+ EL PATRÓN DEL HARNESS
+ =====================
- You --> give task --> Agent reads harness files --> Agent executes
+ Tú --> das tarea --> Agente lee archivos del harness --> Agente ejecuta
+ |
+ el harness gobierna cada paso:
|
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ +--> Instrucciones: qué hacer, en qué orden
+ +--> Alcance: una funcionalidad a la vez, sin excederse
+ +--> Estado: registro de progreso, lista de funcionalidades, historial git
+ +--> Verificación: tests, lint, verificación de tipos, pruebas de humo
+ +--> Ciclo de vida: inicio al arrancar, estado limpio al finalizar
+ |
+ v
+ El agente se detiene solo cuando
+ la verificación pasa
```
---
@@ -112,32 +112,32 @@ Un harness tiene cinco subsistemas:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ EL HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Instrucciones │ │ Estado │ │ Verificación │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ verif. de tipos │ │
+ │ │ feature_list │ │ git log │ │ pruebas de humo │ │
+ │ │ docs/ │ │ handoff ses. │ │ pipeline e2e │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Alcance │ │ Ciclo de Vida de Sesión │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ una func. │ │ init.sh al inicio │ │
+ │ │ a la vez │ │ checklist de estado limpio al final │ │
+ │ │ definición │ │ nota de entrega para sig. sesión │ │
+ │ │ de hecho │ │ commit solo cuando es seguro reanudar│ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ El MODELO decide qué código escribir.
+ El HARNESS gobierna cuándo, dónde y cómo lo escribe.
+ El harness no hace al modelo más inteligente.
+ Hace que la salida del modelo sea fiable.
```
Cada subsistema tiene una única responsabilidad:
@@ -157,24 +157,24 @@ La pregunta no es "pueden los modelos escribir código?" Pueden. La pregunta es:
En este momento, la respuesta es: no sin un harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ SIN HARNESS CON HARNESS
+ =========== ===========
+
+ Sesión 1: agente escribe código Sesión 1: agente lee instrucciones
+ agente rompe tests agente ejecuta init.sh
+ agente dice "listo" agente trabaja en una funcionalidad
+ tú lo arreglas manualmente agente verifica antes de decir "listo"
+ agente actualiza registro de progreso
+ Sesión 2: agente empieza de cero agente hace commit de estado limpio
+ agente no tiene memoria
+ de lo que pasó antes Sesión 2: agente lee registro de progreso
+ agente rehace el trabajo agente continúa exactamente donde lo dejó
+ o hace algo totalmente distinto agente sigue con la funcionalidad pendiente
+ tú lo arreglas otra vez tú revisas, no rescatas
+
+ Resultado: pasas más tiempo Resultado: el agente hace el trabajo,
+ arreglando que si lo tú verificas el resultado
+ hubieras hecho tú mismo
```
Las preguntas que realmente importan en este curso:
@@ -205,13 +205,13 @@ No necesitas leer las 12 clases antes de empezar a obtener valor. Si ya estás u
La idea es simple: en lugar de solo escribir prompts, dale a tu agente un conjunto de archivos estructurados que definan qué hacer, qué se ha hecho y cómo verificar el trabajo. Estos archivos viven dentro de tu repositorio, así que cada sesión comienza desde el mismo estado.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ RAÍZ DE TU PROYECTO
+ ├── AGENTS.md <-- el manual de operación del agente
+ ├── CLAUDE.md <-- (alternativa, si usas Claude Code)
+ ├── init.sh <-- ejecuta install + verify + start
+ ├── feature_list.json <-- qué funcionalidades existen, cuáles están listas
+ ├── claude-progress.md <-- qué pasó en cada sesión
+ └── src/ <-- tu código real
```
Obtén las plantillas iniciales de la [Biblioteca de Recursos](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) y colócalas en tu proyecto. Eso es todo. Cuatro archivos, y tus sesiones de agente ya serán significativamente más estables que ejecutándolas solo con prompts.
@@ -224,28 +224,29 @@ Los seis proyectos del curso giran en torno al mismo producto: **una aplicación
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ App de Escritorio Base de Conocimiento │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ Lista de │ │ Panel de Preguntas y ││
+ │ │ Documentos │ │ Respuestas ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ P: Qué es harness eng? ││
+ │ │ doc-002.md │ │ R: El entorno construido ││
+ │ │ doc-003.md │ │ alrededor de un agente...││
+ │ │ ... │ │ [cita: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Barra de estado: 42 docs | 38 indexados | últ. 3m│
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Funcionalidades principales:
+ ├── Importar documentos locales
+ ├── Gestionar una biblioteca de documentos
+ ├── Procesar e indexar documentos
+ ├── Ejecutar P&R con IA sobre el contenido importado
+ └── Devolver respuestas fundamentadas con citas
```
Este proyecto fue elegido porque combina un fuerte valor práctico, suficiente complejidad de producto del mundo real y un buen entorno para observar mejoras antes y después del harness.
@@ -259,47 +260,48 @@ El starter/solution de cada proyecto del curso es una copia completa de esta apl
El curso está diseñado para realizarse en orden. Cada fase se construye sobre la anterior.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ Fase 1: VER EL PROBLEMA Fase 2: ESTRUCTURAR EL REPO
+ ========================= ==========================
+
+ L01 Modelos potentes ≠ ejecución L03 Repositorio como única
+ fiable fuente de verdad
+ L02 Qué significa realmente harness
+ L04 Dividir instrucciones en
+ | archivos, no un archivo gigante
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Solo prompts vs. |
+ comparación con reglas primero v
+ P02 Espacio de trabajo legible
+ por el agente
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ Fase 3: CONECTAR SESIONES Fase 4: RETROALIMENTACIÓN Y ALCANCE
+ ========================== ====================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Mantener el contexto vivo L07 Dibujar límites claros de tarea
+ entre sesiones
+ L08 Listas de funcionalidades como
+ L06 Inicializar antes de cada primitivas del harness
+ sesión del agente
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Retroalimentación en tiempo de
+ P03 Continuidad multi-sesión ejecución para corregir el agente
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
+ Fase 5: VERIFICACIÓN Fase 6: PONERLO TODO JUNTO
===================== ============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 Evitar que los agentes L11 Hacer observable el runtime
+ declaren victoria pronto del agente
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 Ejecución completa del L12 Entrega limpia al final de
+ pipeline = verificación real cada sesión
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 El agente verifica su P06 Construir un harness completo
+ propio trabajo (proyecto final)
```
Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quieres ir más rápido, las fases 1-3 se pueden completar en un fin de semana largo.
@@ -339,28 +341,31 @@ Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quier
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Construir un harness completo desde cero (proyecto final) | Harness completo: todos los mecanismos + observabilidad + estudio de ablación |
```text
- PROJECT EVOLUTION
- =================
+ EVOLUCIÓN DEL PROYECTO
+ ======================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Solo prompts vs. reglas primero Tú ves el problema
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Espacio de trabajo legible Tú reestructuras el repo
+ por el agente
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Continuidad multi-sesión Tú conectas las sesiones
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Retroalimentación y alcance Tú agregas ciclos de
+ en tiempo de ejecución retroalimentación
|
v
- P05 Self-verification You make the agent check itself
+ P05 Auto-verificación Tú haces que el agente
+ se verifique a sí mismo
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Harness completo (proyecto final) Tú construyes el sistema completo
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ La solución de cada proyecto se convierte en el starter del siguiente.
+ La app evoluciona. Tus habilidades de harness crecen con ella.
```
### Biblioteca de Recursos
@@ -385,44 +390,44 @@ Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quier
Una de las ideas centrales de este curso: **la sesión del agente debe seguir un ciclo de vida estructurado, no un libre intercambio.** Así es como se ve:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ CICLO DE VIDA DE LA SESIÓN DEL AGENTE
+ =====================================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ INICIO │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agente lee AGENTS.md / CLAUDE.md │
+ │ 2. Agente ejecuta init.sh (install, verify, health check) │
+ │ 3. Agente lee claude-progress.md (qué pasó la última vez) │
+ │ 4. Agente lee feature_list.json (qué está listo, qué sigue) │
+ │ 5. Agente revisa git log (cambios recientes) │
│ │
- │ SELECT │
+ │ SELECCIONAR │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agente elige exactamente UNA funcionalidad pendiente │
+ │ 7. Agente trabaja solo en esa funcionalidad │
│ │
- │ EXECUTE │
+ │ EJECUTAR │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agente implementa la funcionalidad │
+ │ 9. Agente ejecuta verificación (tests, lint, verif. de tipos) │
+ │ 10. Si la verificación falla: corregir y volver a ejecutar │
+ │ 11. Si la verificación pasa: registrar evidencia │
│ │
- │ WRAP UP │
+ │ CERRAR │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agente actualiza claude-progress.md │
+ │ 13. Agente actualiza feature_list.json │
+ │ 14. Agente registra qué sigue roto o sin verificar │
+ │ 15. Agente hace commit (solo cuando es seguro reanudar) │
+ │ 16. Agente deja una ruta de reinicio limpia para la sig. sesión│
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ El harness gobierna cada transición en este ciclo de vida.
+ El modelo decide qué código escribir en cada paso.
+ Sin el harness, el paso 9 se convierte en "el agente dice que se ve bien."
+ Con el harness, el paso 9 es "los tests pasan, el lint está limpio, los tipos verifican."
```
---
diff --git a/docs-readme/fr-FR/README.md b/docs-readme/fr-FR/README.md
index 8475fef..e093b92 100644
--- a/docs-readme/fr-FR/README.md
+++ b/docs-readme/fr-FR/README.md
@@ -84,22 +84,22 @@ OpenAI a rapporté la même chose avec Codex : dans un dépôt bien équipé d'u
**Ce cours vous apprend à construire cet environnement.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ LE MODÈLE HARNESS
+ =================
+
+ Vous --> donnez une tâche --> L'agent lit les fichiers harness --> L'agent exécute
+ |
+ Le harness gouverne chaque étape :
+ |
+ +--> Instructions : quoi faire, dans quel ordre
+ +--> Portée : une fonctionnalité à la fois, pas de surcharge
+ +--> État : journal de progression, liste de fonctionnalités, historique git
+ +--> Vérification : tests, lint, vérification de types, essais de fumée
+ +--> Cycle de vie : initialisation au démarrage, état propre à la fin
+ |
+ v
+ L'agent s'arrête uniquement quand
+ la vérification réussit
```
---
@@ -112,32 +112,32 @@ Un harness comporte cinq sous-systèmes :
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ LE HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Instructions │ │ État │ │ Vérification │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ vérif. de types │ │
+ │ │ feature_list │ │ git log │ │ essais de fumée │ │
+ │ │ docs/ │ │ transfert │ │ pipeline e2e │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Portée │ │ Cycle de vie de session │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ une seule │ │ init.sh au démarrage │ │
+ │ │ fonctionnalité│ │ liste de contrôle état propre à fin │ │
+ │ │ définition │ │ note de transfert pour prochaine │ │
+ │ │ de « terminé »│ │ commit uniquement si reprise sûre │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ Le MODÈLE décide quel code écrire.
+ Le HARNESS gouverne quand, où et comment il l'écrit.
+ Le harness ne rend pas le modèle plus intelligent.
+ Il rend la sortie du modèle fiable.
```
Chaque sous-système a une seule responsabilité :
@@ -157,24 +157,24 @@ La question n'est pas « les modèles peuvent-ils écrire du code ? » Ils le pe
Pour l'instant, la réponse est : pas sans un harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ SANS HARNESS AVEC HARNESS
+ =========== ============
+
+ Session 1 : l'agent écrit du code Session 1 : l'agent lit les instructions
+ l'agent casse les tests l'agent exécute init.sh
+ l'agent dit « terminé » l'agent travaille sur une fonctionnalité
+ vous corrigez manuellement l'agent vérifie avant de déclarer « terminé »
+ l'agent met à jour le journal de progression
+ Session 2 : l'agent repart de zéro l'agent commit un état propre
+ l'agent n'a aucun souvenir
+ de ce qui s'est passé avant Session 2 : l'agent lit le journal de progression
+ l'agent refait le travail l'agent reprend exactement là où il s'est arrêté
+ ou fait autre chose totalement l'agent continue la fonctionnalité inachevée
+ vous corrigez encore vous révisez, vous ne sauvez pas
+
+ Résultat : vous passez plus de temps Résultat : l'agent fait le travail,
+ à nettoyer qu si vous vous vérifiez le résultat
+ l'aviez fait vous-même
```
Les questions auxquelles ce cours s'intéresse réellement :
@@ -205,13 +205,13 @@ Vous n'avez pas besoin de lire les 12 cours avant de commencer à en tirer profi
L'idée est simple : au lieu de simplement écrire des prompts, donnez à votre agent un ensemble de fichiers structurés qui définissent ce qu'il faut faire, ce qui a été fait et comment vérifier le travail. Ces fichiers résident dans votre dépôt, donc chaque session démarre depuis le même état.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ RACINE DE VOTRE PROJET
+ ├── AGENTS.md <-- le manuel de fonctionnement de l'agent
+ ├── CLAUDE.md <-- (alternative, si vous utilisez Claude Code)
+ ├── init.sh <-- exécute installation + vérification + démarrage
+ ├── feature_list.json <-- quelles fonctionnalités existent, lesquelles sont terminées
+ ├── claude-progress.md <-- ce qui s'est passé à chaque session
+ └── src/ <-- votre code réel
```
Récupérez les modèles de démarrage depuis la [Bibliothèque de Ressources](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) et déposez-les dans votre projet. C'est tout. Quatre fichiers, et vos sessions d'agent seront déjà nettement plus stables qu'avec des prompts seuls.
@@ -224,28 +224,28 @@ Les six projets du cours gravitent autour du même produit : **une application d
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Application Bureau de Base de Connaissances │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Liste de │ │ Panneau Q&R ││
+ │ │ documents │ │ ││
+ │ │ doc-001.md │ │ Q : Qu'est-ce que le harness││
+ │ │ doc-002.md │ │ R : L'environnement construit││
+ │ │ doc-003.md │ │ autour d'un modèle d'agent││
+ │ │ ... │ │ [citation : doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Barre d'état : 42 docs | 38 indexés | sync 3m ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Fonctionnalités principales :
+ ├── Importer des documents locaux
+ ├── Gérer une bibliothèque de documents
+ ├── Traiter et indexer des documents
+ ├── Exécuter des Q&R alimentées par l'IA sur le contenu importé
+ └── Retourner des réponses fondées avec des citations
```
Ce projet a été choisi car il combine une forte valeur pratique, une complexité produit suffisante pour le monde réel et un bon cadre pour observer les améliorations avant/après harness.
@@ -259,47 +259,47 @@ Le starter/solution de chaque projet du cours est une copie complète de cette a
Le cours est conçu pour être suivi dans l'ordre. Chaque phase s'appuie sur la précédente.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
- v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
-
-
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
-
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
- |
- | v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
-
-
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
-
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
-
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
-
- | |
- v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ Phase 1 : VOIR LE PROBLÈME Phase 2 : STRUCTURER LE DÉPÔT
+ =========================== =============================
+
+ L01 Des modèles performants ≠ L03 Le dépôt comme unique
+ une exécution fiable source de vérité
+ L02 Ce que signifie réellement
+ un harness L04 Répartir les instructions entre
+ plusieurs fichiers, pas un seul fichier géant
+ |
+ v |
+ P01 Comparaison prompts seuls v
+ vs. règles d'abord P02 Espace de travail lisible par l'agent
+
+
+ Phase 3 : CONNECTER LES SESSIONS Phase 4 : RETOUR & PORTÉE
+ ================================= =========================
+
+ L05 Maintenir le contexte L07 Définir des limites de tâches claires
+ entre les sessions
+ L08 Les listes de fonctionnalités comme
+ L06 Initialiser avant chaque primitives du harness
+ session d'agent
+ |
+ | v
+ v P04 Retour d'exécution pour
+ P03 Continuité multi-sessions corriger le comportement de l'agent
+
+
+ Phase 5 : VÉRIFICATION Phase 6 : TOUT ASSEMBLER
+ ====================== ========================
+
+ L09 Empêcher les agents de L11 Rendre l'exécution de l'agent
+ déclarer victoire trop tôt observable
+
+ L10 Une exécution complète du L12 Transfert propre à la fin de
+ pipeline = vraie vérification chaque session
+
+ | |
+ v v
+ P05 L'agent vérifie son propre travail P06 Construire un harness complet
+ (projet final)
```
Chaque phase prend environ une semaine si vous suivez le cours à temps partiel. Si vous souhaitez aller plus vite, les phases 1 à 3 peuvent être effectuées en un long week-end.
@@ -339,28 +339,29 @@ Chaque phase prend environ une semaine si vous suivez le cours à temps partiel.
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Construire un harness complet à partir de zéro (projet final) | Harness complet : tous les mécanismes + observabilité + étude d'ablation |
```text
- PROJECT EVOLUTION
- =================
+ ÉVOLUTION DES PROJETS
+ =====================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Prompts seuls vs. règles d'abord Vous voyez le problème
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Espace de travail lisible Vous restructurez le dépôt
+ par l'agent
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Continuité multi-sessions Vous connectez les sessions
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Retour d'exécution & portée Vous ajoutez des boucles de retour
|
v
- P05 Self-verification You make the agent check itself
+ P05 Auto-vérification Vous faites en sorte que l'agent se vérifie
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Harness complet (projet final) Vous construisez le système complet
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ La solution de chaque projet devient le starter du projet suivant.
+ L'application évolue. Vos compétences en harness grandissent avec elle.
```
### Bibliothèque de Ressources
@@ -385,44 +386,44 @@ Chaque phase prend environ une semaine si vous suivez le cours à temps partiel.
L'une des idées centrales de ce cours : **la session de l'agent doit suivre un cycle de vie structuré, pas être laissée au hasard.** Voici à quoi cela ressemble :
```text
- AGENT SESSION LIFECYCLE
- ======================
+ CYCLE DE VIE DE LA SESSION DE L'AGENT
+ ======================================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ DÉMARRAGE │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. L'agent lit AGENTS.md / CLAUDE.md │
+ │ 2. L'agent exécute init.sh (installation, vérif., contrôle) │
+ │ 3. L'agent lit claude-progress.md (ce qui s'est passé) │
+ │ 4. L'agent lit feature_list.json (terminé, à faire) │
+ │ 5. L'agent vérifie git log (changements récents) │
│ │
- │ SELECT │
+ │ SÉLECTION │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. L'agent choisit exactement UNE fonctionnalité inachevée │
+ │ 7. L'agent travaille uniquement sur cette fonctionnalité │
│ │
- │ EXECUTE │
+ │ EXÉCUTION │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. L'agent implémente la fonctionnalité │
+ │ 9. L'agent exécute la vérification (tests, lint, types) │
+ │ 10. Si la vérification échoue : corriger et relancer │
+ │ 11. Si la vérification réussit : enregistrer la preuve │
│ │
- │ WRAP UP │
+ │ CLÔTURE │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. L'agent met à jour claude-progress.md │
+ │ 13. L'agent met à jour feature_list.json │
+ │ 14. L'agent enregistre ce qui reste cassé ou non vérifié │
+ │ 15. L'agent commit (uniquement si la reprise est sûre) │
+ │ 16. L'agent laisse un chemin de redémarrage propre │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Le harness gouverne chaque transition dans ce cycle de vie.
+ Le modèle décide quel code écrire à chaque étape.
+ Sans le harness, l'étape 9 devient « l'agent dit que ça a l'air correct ».
+ Avec le harness, l'étape 9 est « les tests passent, le lint est propre, les types sont valides ».
```
---
diff --git a/docs-readme/ja-JP/README.md b/docs-readme/ja-JP/README.md
index f54ceee..15e1fe9 100644
--- a/docs-readme/ja-JP/README.md
+++ b/docs-readme/ja-JP/README.md
@@ -84,22 +84,22 @@ OpenAI も Codex で同じことを報告しています:適切にハーネス
**このコースは、その環境の構築方法を教えます。**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ ハーネスパターン
+ ================
+
+ あなた --> タスクを与える --> エージェントがハーネスファイルを読む --> エージェントが実行
+ |
+ ハーネスが全ステップを管理:
+ |
+ +--> 指示:何を、どの順序で行うか
+ +--> スコープ:一度に一つの機能、過剰な範囲拡大なし
+ +--> 状態:進捗ログ、機能リスト、git履歴
+ +--> 検証:テスト、lint、型チェック、スモーク実行
+ +--> ライフサイクル:開始時に初期化、終了時にクリーンな状態
+ |
+ v
+ エージェントは検証が
+ 通過した時のみ停止
```
---
@@ -112,32 +112,32 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ ハーネス │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ 指示 │ │ 状態 │ │ 検証 │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ テスト + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ 型チェック │ │
+ │ │ feature_list │ │ git log │ │ スモーク実行 │ │
+ │ │ docs/ │ │ セションハンドオフ│ │ e2eパイプライン │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ スコープ │ │ セッションライフサイクル │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ 一度に │ │ 開始時にinit.shを実行 │ │
+ │ │ 一つの機能 │ │ 終了時にクリーン状態チェックリスト │ │
+ │ │ 完了の定義 │ │ 次セッションへのハンドオフノート │ │
+ │ │ │ │ 再開安全な場合のみコミット │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ モデルは書くコードを決定する。
+ ハーネスはいつ、どこで、どう書くかを管理する。
+ ハーネスはモデルを賢くするわけではない。
+ モデルの出力を信頼性のあるものにする。
```
各サブシステムには一つの役割があります:
@@ -157,24 +157,23 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
現時点での答えは:ハーネスなしでは無理です。
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ ハーネスなし ハーネスあり
+ ========== ==========
+
+ セッション1: エージェントがコードを書く セッション1: エージェントが指示を読む
+ エージェントがテストを壊す エージェントがinit.shを実行
+ エージェントが「完了」と言う エージェントが一つの機能に取り組む
+ あなたが手動で修正 エージェントが完了宣言前に検証
+ エージェントが進捗ログを更新
+ セッション2: エージェントがゼロから開始 エージェントがクリーンな状態でコミット
+ エージェントは前回の記憶がない
+ セッション2: エージェントが進捗ログを読む
+ エージェントが同じ作業をやり直す エージェントが前回の続きから正確に再開
+ または全く別のことをする エージェントが未完了の機能を継続
+ あなたがまた修正 あなたは確認する、修正するのではない
+
+ 結果: 自分でやるよりも 結果: エージェントが作業を行い、
+ 修正に多くの時間を費やす あなたは結果を検証する
```
このコースが本当に重視している問い:
@@ -205,7 +204,7 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
アイデアはシンプルです:プロンプトを書く代わりに、何をすべきか、何が完了しているか、作業をどう検証するかを定義する構造化ファイルのセットをエージェントに与えます。これらのファイルはリポジトリ内に存在するため、すべてのセッションが同じ状態から始まります。
```text
- YOUR PROJECT ROOT
+ あなたのプロジェクトルート
├── AGENTS.md <-- エージェントの操作マニュアル
├── CLAUDE.md <-- (代替、Claude Code を使用する場合)
├── init.sh <-- install + verify + start を実行
@@ -224,28 +223,29 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ ナレッジベースデスクトップアプリ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ ドキュメント │ │ Q&Aパネル ││
+ │ │ リスト │ │ ││
+ │ │ doc-001.md │ │ Q: ハーネスエンジニアリング ││
+ │ │ doc-002.md │ │ とは何か? ││
+ │ │ doc-003.md │ │ A: エージェントモデルの ││
+ │ │ ... │ │ 周囲に構築された環境... ││
+ │ │ │ │ [引用元: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ ステータスバー: 42文書 | 38件インデックス済 | 最終同期 3分前││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ コア機能:
+ ├── ローカルドキュメントのインポート
+ ├── ドキュメントライブラリの管理
+ ├── ドキュメントの処理とインデックス作成
+ ├── インポートしたコンテンツに対するAI搭載Q&Aの実行
+ └── 引用付きの根拠ある回答の返却
```
このプロジェクトが選ばれたのは、実用的な価値、十分な現実世界の製品複雑さ、ハーネス改善の前後を観察するのに適した設定を組み合わせているからです。
@@ -259,47 +259,47 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
このコースは順番に進めるように設計されています。各フェーズは前のフェーズの上に構築されます。
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ フェーズ1: 問題を見る フェーズ2: リポジトリを構造化
+ ================================= =================================
+
+ L01 強力なモデル ≠ 確実な実行 L03 リポジトリを唯一の
+ 信頼できる情報源にする
+ L02 ハーネスが実際に意味するもの
+ L04 指示を複数ファイルに分割、
+ | 一つの巨大ファイルにしない
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 プロンプトのみ vs. |
+ ルール優先の比較 v
+ P02 エージェント可読ワークスペース
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ フェーズ3: セッションを接続 フェーズ4: フィードバックとスコープ
+ ================================= ====================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
- |
- | v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ L05 セッション間で L07 明確なタスク境界を引く
+ コンテキストを維持
+ L08 機能リストをハーネスの
+ L06 毎回のエージェント プリミティブとして使う
+ セッション前に初期化
+ |
+ | v
+ v P04 エージェントの動作を修正する
+ P03 マルチセッション連続性 ランタイムフィードバック
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ フェーズ5: 検証 フェーズ6: すべてを統合
+ ===================== ============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 エージェントが早すぎる L11 エージェントのランタイムを
+ 完了宣言をするのを防ぐ 観測可能にする
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 フルパイプライン実行 = L12 全セッションの終了時に
+ 本当の検証 クリーンなハンドオフ
- | |
- v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ | |
+ v v
+ P05 エージェントが自分の作業を検証 P06 完全なハーネスを構築
+ (カプロジェクト)
```
パートタイムで進める場合、各フェーズは約1週間です。より速く進めたい場合、フェーズ1〜3は長い週末で完了できます。
@@ -339,28 +339,28 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | ゼロから完全なハーネスを構築する(カプロジェクト) | フルハーネス:全メカニズム + オブザーバビリティ + アブレーションスタディ |
```text
- PROJECT EVOLUTION
- =================
+ プロジェクトの進化
+ ==================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 プロンプトのみ vs. ルール優先 問題を目撃する
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 エージェント可読ワークスペース リポジトリを再構築する
|
v
- P03 Multi-session continuity You connect sessions
+ P03 マルチセッション連続性 セッションを接続する
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 ランタイムフィードバックとスコープ フィードバックループを追加する
|
v
- P05 Self-verification You make the agent check itself
+ P05 自己検証 エージェントに自己チェックさせる
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 完全なハーネス(カプロジェクト) 完全なシステムを構築する
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ 各プロジェクトのソリューションが次のプロジェクトのスターターになる。
+ アプリは進化する。あなたのハーネスキルも共に成長する。
```
### リソースライブラリ
@@ -385,44 +385,44 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
このコースのコアアイデアの一つ:**エージェントのセッションは自由放任ではなく、構造化されたライフサイクルに従うべきです。** どのようなものか:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ エージェントセッションライフサイクル
+ ====================================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ 開始 │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. エージェントがAGENTS.md / CLAUDE.mdを読む │
+ │ 2. エージェントがinit.shを実行(インストール、検証、ヘルスチェック)│
+ │ 3. エージェントがclaude-progress.mdを読む(前回の内容) │
+ │ 4. エージェントがfeature_list.jsonを読む(完了済み、次の作業) │
+ │ 5. エージェントがgit logを確認(最近の変更) │
│ │
- │ SELECT │
+ │ 選択 │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. エージェントは未完了の機能を正確に1つだけ選択 │
+ │ 7. エージェントはその機能のみに取り組む │
│ │
- │ EXECUTE │
+ │ 実行 │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. エージェントが機能を実装する │
+ │ 9. エージェントが検証を実行(テスト、lint、型チェック) │
+ │ 10. 検証失敗時:修正して再実行 │
+ │ 11. 検証通過時:証拠を記録 │
│ │
- │ WRAP UP │
+ │ 仕上げ │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. エージェントがclaude-progress.mdを更新 │
+ │ 13. エージェントがfeature_list.jsonを更新 │
+ │ 14. エージェントがまだ壊れている、または未検証の項目を記録 │
+ │ 15. エージェントがコミット(再開安全な場合のみ) │
+ │ 16. エージェントが次セッション用のクリーンな再起動パスを残す │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ ハーネスはこのライフサイクルの全移行を管理する。
+ モデルは各ステップで書くコードを決定する。
+ ハーネスなしでは、ステップ9は「エージェントが大丈夫そうだと言う」になる。
+ ハーネスありでは、ステップ9は「テスト通過、lintクリーン、型チェックOK」になる。
```
---
diff --git a/docs-readme/ko-KR/README.md b/docs-readme/ko-KR/README.md
index 06b5f01..2cd4b98 100644
--- a/docs-readme/ko-KR/README.md
+++ b/docs-readme/ko-KR/README.md
@@ -84,22 +84,22 @@ OpenAI도 Codex에서 동일한 결과를 보고했습니다: 잘 구축된 하
**이 강좌는 그 환경을 구축하는 방법을 가르칩니다.**
```text
- THE HARNESS PATTERN
- ====================
-
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ 하니스 패턴
+ ==========
+
+ 사용자 --> 작업 전달 --> 에이전트가 하니스 파일 읽음 --> 에이전트 실행
+ |
+ 하니스가 모든 단계를 제어:
+ |
+ +--> 지시 사항: 무엇을, 어떤 순서로 할 것인가
+ +--> 범위: 한 번에 하나의 기능, 과도한 작업 금지
+ +--> 상태: 진행 로그, 기능 목록, git 기록
+ +--> 검증: 테스트, 린트, 타입 검사, 스모크 실행
+ +--> 수명 주기: 시작 시 초기화, 종료 시 깔끔한 상태
+ |
+ v
+ 에이전트는 검증을 통과한 경우에만
+ 실행을 중지합니다
```
---
@@ -112,32 +112,32 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ 하니스 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ 지시 사항 │ │ 상태 │ │ 검증 │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ 테스트 + 린트 │ │
+ │ │ CLAUDE.md │ │ 기능 목록 │ │ 타입 검사 │ │
+ │ │ 기능 목록 │ │ git log │ │ 스모크 실행 │ │
+ │ │ docs/ │ │ 세션 인계 │ │ e2e 파이프라인 │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ 범위 │ │ 세션 수명 주기 │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ 한 번에 │ │ 시작 시 init.sh 실행 │ │
+ │ │ 하나의 기능 │ │ 종료 시 깔끔한 상태 체크리스트 │ │
+ │ │ 완료 정의 │ │ 다음 세션을 위한 인계 노트 │ │
+ │ │ │ │ 안전하게 재개 가능할 때만 커밋 │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ 모델은 어떤 코드를 작성할지 결정합니다.
+ 하니스는 언제, 어디서, 어떻게 작성할지 제어합니다.
+ 하니스는 모델을 더 똑똑하게 만들지 않습니다.
+ 모델의 출력을 안정적으로 만듭니다.
```
각 하위 시스템은 하나의 역할을 담당합니다:
@@ -157,24 +157,24 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
현재 답은: 하니스 없이는 불가능합니다.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ 하니스 없음 하니스 있음
+ ========= ========
+
+ 세션 1: 에이전트가 코드를 작성 세션 1: 에이전트가 지시 사항을 읽음
+ 에이전트가 테스트를 망가뜨림 에이전트가 init.sh를 실행
+ 에이전트가 "완료"라고 선언 에이전트가 하나의 기능에 집중
+ 사용자가 직접 수정 에이전트가 완료 선언 전 검증
+ 에이전트가 진행 로그를 업데이트
+ 세션 2: 에이전트가 처음부터 시작 에이전트가 깔끔한 상태로 커밋
+ 에이전트에게 이전 기록 없음
+ 에이전트가 작업을 다시 시작 세션 2: 에이전트가 진행 로그를 읽음
+ 또는 전혀 다른 작업을 수행 에이전트가 정확히 중단한 지점부터 이어서 작업
+ 사용자가 또다시 수정 에이전트가 미완료 기능을 계속 진행
+ 사용자는 검토만, 구조 작업은 불필요
+
+ 결과: 직접 했더라면 더 빨랐을 결과: 에이전트가 작업을 수행하고,
+ 작업을 수정하는 데 더 많은 사용자가 결과를 검증
+ 시간을 소비
```
이 강좌가 실제로 다루는 질문들:
@@ -205,7 +205,7 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
핵심 아이디어는 간단합니다: 프롬프트만 작성하는 대신, 무엇을 해야 하는지, 무엇이 완료되었는지, 작업을 어떻게 검증할지 정의하는 구조화된 파일 세트를 에이전트에 제공하세요. 이 파일들은 저장소 내에 있으므로 모든 세션이 동일한 상태에서 시작합니다.
```text
- YOUR PROJECT ROOT
+ 프로젝트 루트 디렉토리
├── AGENTS.md <-- 에이전트의 운영 매뉴얼
├── CLAUDE.md <-- (대체, Claude Code 사용 시)
├── init.sh <-- 설치 + 검증 + 시작 실행
@@ -224,28 +224,28 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ 지식 베이스 데스크톱 앱 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ 문서 목록 │ │ Q&A 패널 ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ 질문: 하니스 엔지니어링이란? ││
+ │ │ doc-002.md │ │ 답변: 에이전트 모델 주변에 ││
+ │ │ doc-003.md │ │ 구축된 환경... ││
+ │ │ ... │ │ [출처: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ 상태 표시줄: 42개 문서 | 38개 인덱싱 | 마지막 동기화 3분 전 ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ 핵심 기능:
+ ├── 로컬 문서 가져오기
+ ├── 문서 라이브러리 관리
+ ├── 문서 처리 및 인덱싱
+ ├── 가져온 콘텐츠에 대한 AI 기반 Q&A 실행
+ └── 출처가 포함된 근거 기반 답변 반환
```
이 프로젝트는 강력한 실용적 가치, 충분한 실제 제품 복잡성, 그리고 하니스 개선 전후를 관찰하기 좋은 환경을 결합하고 있어 선택되었습니다.
@@ -259,47 +259,45 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
이 강좌는 순서대로 진행하도록 설계되었습니다. 각 단계는 이전 단계를 기반으로 구축됩니다.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ 1단계: 문제 인식 2단계: 저장소 구조화
+ ================ ================
+
+ L01 강력한 모델 ≠ 안정적 실행 L03 저장소를 단일 진실 공급원으로
+ L02 하니스가 실제로 의미하는 것
+ L04 거대한 단일 파일 대신
+ | 여러 파일로 지시 사항 분할
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 프롬프트만 vs. |
+ 규칙 우선 비교 v
+ P02 에이전트 판독 가능 작업 공간
+
+ 3단계: 세션 연결 4단계: 피드백 및 범위
+ ================ ==================
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ L05 세션 간 컨텍스트 유지 L07 명확한 작업 경계 설정
+ L06 모든 에이전트 세션 전
+ 초기화 L08 기능 목록을 하니스 프리미티브로
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 에이전트 동작 교정을 위한
+ P03 다중 세션 연속성 런타임 피드백
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ 5단계: 검증 6단계: 모든 것을 종합
+ ========== ==================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 에이전트가 너무 일찍 L11 에이전트의 런타임을
+ 완료를 선언하지 못하게 방지 관측 가능하게 만들기
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 전체 파이프라인 실행 = L12 모든 세션 종료 시
+ 진정한 검증 깔끔한 인계
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 에이전트가 자체 검증 P06 완전한 하니스 구축
+ (캡스톤 프로젝트)
```
파트타임으로 진행하면 각 단계는 약 1주일이 소요됩니다. 더 빠르게 진행하고 싶다면 1~3단계는 긴 주말에 완료할 수 있습니다.
@@ -339,28 +337,28 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | 처음부터 완전한 하니스 구축 (캡스톤) | 전체 하니스: 모든 메커니즘 + 관측 가능성 + 어블레이션 스터디 |
```text
- PROJECT EVOLUTION
- =================
+ 프로젝트 발전 과정
+ ==================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 프롬프트만 vs. 규칙 우선 문제를 직접 확인합니다
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 에이전트 판독 가능 작업 공간 저장소를 재구성합니다
|
v
- P03 Multi-session continuity You connect sessions
+ P03 다중 세션 연속성 세션을 연결합니다
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 런타임 피드백 및 범위 피드백 루프를 추가합니다
|
v
- P05 Self-verification You make the agent check itself
+ P05 자체 검증 에이전트가 스스로 검증하게 만듭니다
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 완전한 하니스 (캡스톤) 전체 시스템을 구축합니다
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ 각 프로젝트의 솔루션이 다음 프로젝트의 스타터가 됩니다.
+ 앱이 발전합니다. 여러분의 하니스 기술도 함께 성장합니다.
```
### 리소스 라이브러리
@@ -385,44 +383,44 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
이 강좌의 핵심 아이디어 중 하나: **에이전트의 세션은 자유 방임이 아닌 구조화된 수명 주기를 따라야 합니다.** 그 모습은 다음과 같습니다:
```text
- AGENT SESSION LIFECYCLE
+ 에이전트 세션 수명 주기
======================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ 시작 │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. 에이전트가 AGENTS.md / CLAUDE.md를 읽음 │
+ │ 2. 에이전트가 init.sh를 실행 (설치, 검증, 상태 확인) │
+ │ 3. 에이전트가 claude-progress.md를 읽음 (이전 세션 기록) │
+ │ 4. 에이전트가 feature_list.json을 읽음 (완료된 항목, 다음 항목) │
+ │ 5. 에이전트가 git log를 확인 (최근 변경 사항) │
│ │
- │ SELECT │
+ │ 선택 │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. 에이전트가 정확히 하나의 미완료 기능을 선택 │
+ │ 7. 에이전트가 해당 기능에만 작업 │
│ │
- │ EXECUTE │
+ │ 실행 │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. 에이전트가 기능을 구현 │
+ │ 9. 에이전트가 검증을 실행 (테스트, 린트, 타입 검사) │
+ │ 10. 검증 실패 시: 수정 후 재실행 │
+ │ 11. 검증 통과 시: 증거를 기록 │
│ │
- │ WRAP UP │
+ │ 마무리 │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. 에이전트가 claude-progress.md를 업데이트 │
+ │ 13. 에이전트가 feature_list.json을 업데이트 │
+ │ 14. 에이전트가 여전히 망가져 있거나 미검증된 항목을 기록 │
+ │ 15. 에이전트가 커밋 (안전하게 재개 가능할 때만) │
+ │ 16. 에이전트가 다음 세션을 위한 깔끔한 재시작 경로를 남김 │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ 하니스가 이 수명 주기의 모든 전환을 제어합니다.
+ 모델은 각 단계에서 어떤 코드를 작성할지 결정합니다.
+ 하니스가 없으면 9단계는 "에이전트가 괜찮아 보인다고 말함"이 됩니다.
+ 하니스가 있으면 9단계는 "테스트 통과, 린트 깔끔함, 타입 검사 통과"가 됩니다.
```
---
diff --git a/docs-readme/ru-RU/README.md b/docs-readme/ru-RU/README.md
index e7f939a..810e211 100644
--- a/docs-readme/ru-RU/README.md
+++ b/docs-readme/ru-RU/README.md
@@ -84,22 +84,23 @@ OpenAI сообщает то же самое с Codex: в хорошо подг
**Этот курс научит вас, как построить такое окружение.**
```text
- THE HARNESS PATTERN
- ====================
+ ПАТТЕРН HARNESS
+ ================
- You --> give task --> Agent reads harness files --> Agent executes
- |
- harness governs every step:
+ Вы --> даёте задачу --> Агент читает файлы harness --> Агент выполняет
+ |
+ harness управляет каждым шагом:
|
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
+ +--> Инструкции: что делать, в каком порядке
+ +--> Область: одна фича за раз, без превышения
+ +--> Состояние: лог прогресса, список фич, история git
+ +--> Верификация: тесты, линт, проверка типов, smoke-запуски
+ +--> Жизненный инициализация при старте, чистое
+ цикл: состояние в конце
|
v
- Agent stops only when
- verification passes
+ Агент останавливается
+ только когда верификация пройдена
```
---
@@ -112,32 +113,34 @@ Harness состоит из пяти подсистем:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Инструкции │ │ Состояние │ │ Верификация │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ тесты + линт │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ проверка типов │ │
+ │ │ feature_list │ │ git log │ │ smoke-запуски │ │
+ │ │ docs/ │ │ передача │ │ e2e pipeline │ │
+ │ │ │ │ сессии │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Область │ │ Жизненный цикл сессии │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ одна фича │ │ init.sh при старте │ │
+ │ │ за раз │ │ чек-лист чистого состояния в конце │ │
+ │ │ определение │ │ заметка-передача для след. сессии │ │
+ │ │ «готово» │ │ коммит только когда безопасно │ │
+ │ │ │ │ для возобновления │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ МОДЕЛЬ решает, какой код писать.
+ HARNESS управляет тем, когда, где и как она его пишет.
+ Harness не делает модель умнее.
+ Он делает вывод модели надёжным.
```
Каждая подсистема выполняет свою задачу:
@@ -157,25 +160,27 @@ Harness состоит из пяти подсистем:
На данный момент ответ: нет без harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
-
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ БЕЗ HARNESS С HARNESS
+ ========== =========
+
+ Сессия 1: агент пишет код Сессия 1: агент читает инструкции
+ агент ломает тесты агент запускает init.sh
+ агент говорит «готово» агент работает над одной фичей
+ вы исправляете вручную агент верифицирует перед тем
+ как сообщить о готовности
+ агент обновляет лог прогресса
+
+ Сессия 2: агент начинает с чистого агент фиксирует чистое состояние
+ листа
+ у агента нет памяти Сессия 2: агент читает лог прогресса
+ о том, что было раньше агент продолжает точно с того места
+ агент переделывает работу где остановился
+ или делает что-то совсем другое агент продолжает незавершённую фичу
+ вы исправляете снова вы проверяете, а не спасаете
+
+ Результат: вы тратите больше Результат: агент делает работу,
+ времени на исправления, вы проверяете результат
+ чем если бы сделали сами
```
Вопросы, которые действительно волнуют этот курс:
@@ -206,10 +211,10 @@ Harness состоит из пяти подсистем:
Идея проста: вместо того чтобы писать только промпты, дайте своему агенту набор структурированных файлов, определяющих, что нужно сделать, что уже сделано и как проверить результат. Эти файлы находятся в вашем репозитории, поэтому каждая сессия стартует из одного и того же состояния.
```text
- YOUR PROJECT ROOT
+ КОРНЕВАЯ ПАПКА ВАШЕГО ПРОЕКТА
├── AGENTS.md <-- операционное руководство агента
├── CLAUDE.md <-- (альтернатива, если вы используете Claude Code)
- ├── init.sh <-- выполняет install + verify + start
+ ├── init.sh <-- выполняет установку + верификацию + запуск
├── feature_list.json <-- какие фичи существуют, какие выполнены
├── claude-progress.md <-- что произошло в каждой сессии
└── src/ <-- ваш фактический код
@@ -225,28 +230,30 @@ Harness состоит из пяти подсистем:
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Десктоп-приложение «База знаний» │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ Список │ │ Панель вопросов ││
+ │ │ документов │ │ и ответов ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ В: Что такое harness eng? ││
+ │ │ doc-002.md │ │ О: Окружение, построенное ││
+ │ │ doc-003.md │ │ вокруг агентной модели...││
+ │ │ ... │ │ [источник: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Строка состояния: 42 док. | 38 индекс. | синхр. ││
+ │ │ 3 мин. назад ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Основные возможности:
+ ├── Импорт локальных документов
+ ├── Управление библиотекой документов
+ ├── Обработка и индексирование документов
+ ├── AI-вопросы и ответы по импортированному контенту
+ └── Обоснованные ответы с источниками
```
Этот проект выбран потому, что он сочетает высокую практическую пользу, достаточную реальную продуктовую сложность и хороший сценарий для наблюдения улучшений harness (до/после).
@@ -260,47 +267,49 @@ Harness состоит из пяти подсистем:
Курс рассчитан на последовательное прохождение. Каждая фаза строится на предыдущей.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
- v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
-
-
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
-
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ Фаза 1: УВИДЕТЬ ПРОБЛЕМУ Фаза 2: СТРУКТУРИРОВАТЬ РЕПОЗИТОРИЙ
+ ========================== ===================================
+
+ L01 Сильные модели ≠ надёжное L03 Репозиторий как единственный
+ выполнение источник истины
+ L02 Что на самом деле означает
+ harness L04 Разнести инструкции по файлам,
+ а не один гигантский файл
+ |
+ v |
+ P01 Только промпт vs. v
+ подход на основе правил P02 Агентно-читаемое рабочее
+ пространство
+
+
+ Фаза 3: СВЯЗАТЬ СЕССИИ Фаза 4: ОБРАТНАЯ СВЯЗЬ И ОБЛАСТЬ
+ ========================= ================================
+
+ L05 Сохранять контекст живым L07 Чёткие границы задач
+ между сессиями
+ L08 Списки фич как примитивы
+ L06 Инициализация перед каждой harness
+ сессией агента
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Runtime-обратная связь
+ P03 Мультисессионная связность для корректировки поведения
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ Фаза 5: ВЕРИФИКАЦИЯ Фаза 6: СОБРАТЬ ВСЁ ВМЕСТЕ
+ =================== ==========================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
-
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L09 Остановить агентов от L11 Сделать runtime агента
+ преждевременного объявления наблюдаемым
+ победы
+ L12 Чистая передача в конце
+ L10 Полный прогон pipeline = каждой сессии
+ настоящая верификация
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 Агент верифицирует P06 Построить полный harness
+ собственную работу (итоговый проект)
```
Каждая фаза занимает примерно неделю при обучении параллельно с основной работой. Если двигаться быстрее, фазы 1–3 можно пройти за длинные выходные.
@@ -340,28 +349,32 @@ Harness состоит из пяти подсистем:
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Построить полный harness с нуля (итоговый проект) | Полный harness: все механизмы + observability + абляционное исследование |
```text
- PROJECT EVOLUTION
+ ЭВОЛЮЦИЯ ПРОЕКТОВ
=================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Только промпт vs. подход Вы видите проблему
+ на основе правил
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Агентно-читаемое рабочее Вы реструктурируете репозиторий
+ пространство
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Мультисессионная связность Вы связываете сессии
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Runtime-обратная связь и Вы добавляете циклы обратной
+ область связи
|
v
- P05 Self-verification You make the agent check itself
+ P05 Самоверификация Вы заставляете агента проверять
+ самого себя
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Полный harness (итоговый) Вы строите полную систему
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Solution каждого проекта становится starter'ом следующего.
+ Приложение эволюционирует. Ваши навыки harness растут вместе с ним.
```
### Библиотека шаблонов
@@ -386,44 +399,44 @@ Harness состоит из пяти подсистем:
Одна из ключевых идей этого курса: **сессия агента должна следовать структурированному жизненному циклу, а не быть свободным плаванием.** Вот как это выглядит:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ ЖИЗНЕННЫЙ ЦИКЛ СЕССИИ АГЕНТА
+ =============================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ СТАРТ │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Агент читает AGENTS.md / CLAUDE.md │
+ │ 2. Агент запускает init.sh (установка, верификация, проверка) │
+ │ 3. Агент читает claude-progress.md (что было в прошлый раз) │
+ │ 4. Агент читает feature_list.json (что готово, что дальше) │
+ │ 5. Агент проверяет git log (недавние изменения) │
│ │
- │ SELECT │
+ │ ВЫБОР │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Агент выбирает ровно ОДНУ незавершённую фичу │
+ │ 7. Агент работает только над этой фичей │
│ │
- │ EXECUTE │
+ │ ВЫПОЛНЕНИЕ │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Агент реализует фичу │
+ │ 9. Агент запускает верификацию (тесты, линт, проверка типов) │
+ │ 10. Если верификация не прошла: исправить и запустить снова │
+ │ 11. Если верификация прошла: зафиксировать результат │
│ │
- │ WRAP UP │
+ │ ЗАВЕРШЕНИЕ │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Агент обновляет claude-progress.md │
+ │ 13. Агент обновляет feature_list.json │
+ │ 14. Агент записывает, что всё ещё сломано или не верифицировано│
+ │ 15. Агент делает коммит (только когда безопасно возобновлять) │
+ │ 16. Агент оставляет чистый путь перезапуска для след. сессии │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness управляет каждым переходом в этом жизненном цикле.
+ Модель решает, какой код писать на каждом шаге.
+ Без harness шаг 9 превращается в «агент говорит, что всё выглядит нормально».
+ С harness шаг 9 — это «тесты пройдены, линт чист, типы в порядке».
```
---
diff --git a/docs-readme/uz-UZ/README.md b/docs-readme/uz-UZ/README.md
index 6c84503..7d12c47 100644
--- a/docs-readme/uz-UZ/README.md
+++ b/docs-readme/uz-UZ/README.md
@@ -84,22 +84,22 @@ OpenAI Codex bilan xuddi shu haqida xabar berdi: yaxshi harnesslangan repozitori
**Ushbu kurs sizga shu muhitni qanday qurishni oʻrgatadi.**
```text
- THE HARNESS PATTERN
- ====================
+ HARNESS NAMUNASI
+ ================
- You --> give task --> Agent reads harness files --> Agent executes
+ Siz --> vazifa berasiz --> Agent harness fayllarini oʻqiydi --> Agent bajaradi
+ |
+ harness har bir qadamni boshqaradi:
|
- harness governs every step:
- |
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
- |
- v
- Agent stops only when
- verification passes
+ +--> Koʻrsatmalar: nima qilish, qanday tartibda
+ +--> Doira: bir vaqtda bitta funksiya, haddan oshmaslik
+ +--> Holat: taraqqiyot jurnali, funksiya roʻyxati, git tarixi
+ +--> Tekshiruv: testlar, lint, tur-tekshirish, sinov ishga tushirish
+ +--> Hayot sikli: boshida ishga tushirish, oxirida toza holat
+ |
+ v
+ Agent faqat tekshiruv
+ oʻtganda toʻxtaydi
```
---
@@ -112,32 +112,32 @@ Harnessʼning beshta quyi tizimi bor:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Koʻrsatmalar │ │ Holat │ │ Tekshiruv │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ testlar + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ tur-tekshirish │ │
+ │ │ feature_list │ │ git log │ │ sinov ishga tushirish│ │
+ │ │ docs/ │ │ sessiya uzat │ │ e2e pipeline │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Doira │ │ Sessiya hayot sikli │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ bir vaqtda │ │ boshida init.sh │ │
+ │ │ bitta funksiya│ │ oxirida toza-holat tekshiruv roʻyxati│ │
+ │ │ "tugadi" │ │ keyingi sessiya uchun uzatish yozuvi │ │
+ │ │ taʼrifi │ │ faqat xavfsiz davom ettirishda commit│ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ MODEL qanday kod yozishni hal qiladi.
+ HARNESS qachon, qayerda va qanday yozishni boshqaradi.
+ Harness modelni aqlliroq qilmaydi.
+ U model natijasini ishonchli qiladi.
```
Har bir quyi tizimning oʻz vazifasi bor:
@@ -157,24 +157,24 @@ Savol "Model lar kod yozoladimi?" emas. Yozoladi. Haqiqiy savol: **Ular haqiqiy
Hozircha javob: harnessʼsiz — yoʻq.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ HARNESSʼSIZ HARNESS BILAN
+ ============ ============
+
+ 1-sessiya: agent kod yozadi 1-sessiya: agent koʻrsatmalarni oʻqiydi
+ agent testlarni buzadi agent init.sh ni ishga tushiradi
+ agent "tugadi" deydi agent bitta funksiya ustida ishlaydi
+ siz qoʻlbola tuzatasiz agent "tugadi" deyishdan oldin tekshiradi
+ agent taraqqiyot jurnalini yangilaydi
+ 2-sessiya: agent yangidan boshlaydi agent toza holatni commit qiladi
+ agentning xotirasi yoʻq
+ oldin nima boʻlganini 2-sessiya: agent taraqqiyot jurnalini oʻqiydi
+ agent ishni qayta qiladi agent aynan toʻxtagan joydan davom etadi
+ yoki butunlay boshqa narsa qiladi agent tugallanmagan funksiyani davom ettiradi
+ siz yana tuzatasiz siz koʻrib chiqasiz, qutqarmaysiz
+
+ Natija: siz oʻzingiz qilganingizdan Natija: agent ishni bajaradi,
+ koʻra koʻproq vaqtni siz natijani tekshirasiz
+ tuzatishga sarflaysiz
```
Bu kursni qiziqtiradigan haqiqiy savollar:
@@ -205,10 +205,10 @@ Foyda olish uchun 12 ta maʼruzani ham oʻqish shart emas. Agar siz allaqachon h
Gʻoya oddiy: faqat promptʼlar yozish oʻrniga, agentingizga nima qilish kerak, nima allaqachon qilingan va ish qanday tekshirilishini belgilovchi strukturaviy fayllar toʻplamini bering. Bu fayllar repozitoriyangizda joylashgan, shunda har bir sessiya bir xil holatdan boshlanadi.
```text
- YOUR PROJECT ROOT
+ LOYIHANGIZNING ILDIZ PAPKASI
├── AGENTS.md <-- agentning ish qoʻllanmasi
├── CLAUDE.md <-- (Claude Code ishlatganingizda alternativa)
- ├── init.sh <-- install + verify + start ni bajaradi
+ ├── init.sh <-- oʻrnatish + tekshirish + ishga tushirishni bajaradi
├── feature_list.json <-- qanday funksiyalar mavjud, qaysilari tugallangan
├── claude-progress.md <-- har bir sessiyada nima boʻlgani
└── src/ <-- sizning haqiqiy kodingiz
@@ -224,28 +224,29 @@ Oltita kurs loyihasi bir xil mahsulot atrofida qurilgan: **Electron asosidagi sh
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Bilim bazasi desktop ilovasi │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Hujjatlar │ │ S&S paneli ││
+ │ │ roʻyxati │ │ ││
+ │ │ │ │ S: Harness eng nima? ││
+ │ │ doc-001.md │ │ J: Agent modeli atrofida ││
+ │ │ doc-002.md │ │ qurilgan muhit... ││
+ │ │ doc-003.md │ │ [manba: doc-002.md] ││
+ │ │ ... │ │ ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Holat paneli: 42 hujjat | 38 indekslangan | soʻnggi sinxronizatsiya 3d ││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Asosiy funksiyalar:
+ ├── Mahalliy hujjatlarni import qilish
+ ├── Hujjatlar kutubxonasini boshqarish
+ ├── Hujjatlarni qayta ishlash va indekslash
+ ├── Import qilingan kontent ustida KI asosidagi S&S oʻtkazish
+ └── Manbalar bilan asoslangan javoblarni qaytarish
```
Bu loyiha shuning uchun tanlanganki, u yuqori amaliy foyda, yetarli haqiqiy mahsulot murakkabligi va harness yaxshilanishlarini kuzatish uchun yaxshi stsenariyani oʻzida birlashtiradi.
@@ -259,47 +260,47 @@ Har bir kurs loyihasi (boshlangʻich/yechim) ushbu Electron ilovasining mos rivo
Kurs xronologik tartibda bajarish uchun moʻljallangan. Har bir bosqich oldingisiga asoslanadi.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ 1-bosqich: MUAMMONI KOʻRISH 2-bosqich: REPONI TUZISH
+ =========================== ========================
+
+ L01 Kuchli modellar ≠ ishonchli L03 Repo yagona haqiqat
+ bajarish manbai sifatida
+ L02 Harness nima degani haqiqatan
+ L04 Koʻrsatmalarni bitta ulkan
+ | faylga emas, bir nechta faylga boʻlish
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Faqat prompt vs. |
+ qoidalarga asoslangan solishtirish v
+ P02 Agent oʻqiy oladigan ish muhiti
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ 3-bosqich: SESSIYALARNI BOGʻLASH 4-bosqich: FIKR-MULOHAZA VA DOIRA
+ ================================ ================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Kontekstni sessiyalar L07 Aniq vazifa chegaralarini chizish
+ orasida saqlash
+ L08 Funksiya roʻyxatlari harness
+ L06 Har bir agent sessiyasidan primitivlari sifatida
+ oldin ishga tushirish
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
-
-
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ v P04 Agent xatti-harakatini
+ P03 Koʻp sessiyali uzluksizlik tuzatish uchun runtime fikr-mulohaza
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ 5-bosqich: TEKSHIRUV 6-bosqich: HAMMASINI BIRGA JAMQILISH
+ =================== ===================================
- | |
- v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ L09 Agentlarga erta L11 Agent runtime'ini
+ muvaffaqiyat haqida xabar kuzatiladigan qilish
+ berishiga toʻsqinlik qilish
+ L12 Har bir sessiya oxirida
+ L10 Toʻliq pipeline ishga toza uzatish
+ tushirish = haqiqiy tekshiruv
+ |
+ | v
+ v P06 Toʻliq harness qurish
+ P05 Agent oʻz ishini mustaqil tekshiradi (yakuniy loyiha)
```
Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar tezroq borishni xohlasangiz, 1–3 bosqichlarni bitta uzun dam olish kunlarida tugatishingiz mumkin.
@@ -339,28 +340,28 @@ Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Toʻliq harnessʼni noldan qurish (yakuniy loyiha) | Toʻliq harness: barcha mexanizmlar + kuzatuvchanlik + ablyatsiya tadqiqoti |
```text
- PROJECT EVOLUTION
- =================
+ LOYIHA RIVOJLANISHI
+ ===================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Faqat prompt vs. qoidalarga asoslangan Siz muammoni koʻrasiz
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Agent oʻqiy oladigan ish muhiti Siz repolarni qayta tuzasiz
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Koʻp sessiyali uzluksizlik Siz sessiyalarni bogʻlaysiz
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Runtime fikr-mulohaza va doira Siz fikr-mulohaza halqalarini qoʻshasiz
|
v
- P05 Self-verification You make the agent check itself
+ P05 Oʻz-oʻzini tekshirish Siz agentni oʻz-oʻzini tekshirishga majburlaysiz
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Toʻliq harness (yakuniy loyiha) Siz toʻliq tizimni qurasiz
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Har bir loyihaning yechimi keyingi loyihaning boshlangʻichiga aylanadi.
+ Ilova rivojlanadi. Harness koʻnikmalaringiz unga qarab oʻsadi.
```
### Andozalar kutubxonasi
@@ -385,44 +386,44 @@ Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar
Ushbu kursning asosiy gʻoyalaridan biri: **Agent sessiyasi tuzilgan hayot sikliga amal qilishi kerak, emas xohlagancha ishlashiga.** Bu quyidagicha koʻrinadi:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ AGENT SESSIYA HAYOT SIKLI
+ =========================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ BOSHLASH │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agent AGENTS.md / CLAUDE.md faylini oʻqiydi │
+ │ 2. Agent init.sh ni ishga tushiradi (oʻrnatish, tekshirish, sogʻliqni nazorat)│
+ │ 3. Agent claude-progress.md ni oʻqiydi (oxirgi safar nima boʻldi)│
+ │ 4. Agent feature_list.json ni oʻqiydi (nima tugadi, keyin nima)│
+ │ 5. Agent git log ni tekshiradi (soʻnggi oʻzgarishlar) │
│ │
- │ SELECT │
+ │ TANLASH │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agent aynan BITTA tugallanmagan funksiyani tanlaydi │
+ │ 7. Agent faqat shu funksiya ustida ishlaydi │
│ │
- │ EXECUTE │
+ │ BAJARISH │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agent funksiyani amalga oshiradi │
+ │ 9. Agent tekshiruvni ishga tushiradi (testlar, lint, tur-tekshirish)│
+ │ 10. Agar tekshiruv oʻtmasa: tuzatish va qayta ishga tushirish │
+ │ 11. Agar tekshiruv oʻtsa: dalilni qayd etish │
│ │
- │ WRAP UP │
+ │ YAKUNLASH │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agent claude-progress.md ni yangilaydi │
+ │ 13. Agent feature_list.json ni yangilaydi │
+ │ 14. Agent hali buzilgan yoki tekshirilmagan narsalarni qayd etadi│
+ │ 15. Agent commit qiladi (faqat xavfsiz davom ettirishda) │
+ │ 16. Agent keyingi sessiya uchun toza qayta boshlash yoʻlini qoldiradi│
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness ushbu hayot siklidagi har bir oʻtishni boshqaradi.
+ Model har bir qadamda qanday kod yozishni hal qiladi.
+ Harnessʼsiz 9-qadam "agent yaxshi koʻrinadi deydi" ga aylanadi.
+ Harness bilan 9-qadam "testlar oʻtdi, lint toza, turlar tekshirildi" boʻladi.
```
---
diff --git a/docs-readme/vi-VN/README.md b/docs-readme/vi-VN/README.md
index 918ac8e..338d317 100644
--- a/docs-readme/vi-VN/README.md
+++ b/docs-readme/vi-VN/README.md
@@ -84,22 +84,22 @@ OpenAI cũng báo cáo điều tương tự với Codex: trong một kho mã đ
**Khóa học này dạy bạn cách xây dựng môi trường đó.**
```text
- THE HARNESS PATTERN
- ====================
+ MÔ HÌNH HARNESS
+ ===============
- You --> give task --> Agent reads harness files --> Agent executes
+ Bạn --> giao tác vụ --> Agent đọc tệp harness --> Agent thực thi
|
- harness governs every step:
+ harness điều phối mọi bước:
|
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
+ +--> Hướng dẫn: làm gì, theo thứ tự nào
+ +--> Phạm vi: một tính năng mỗi lần, không vượt quá
+ +--> Trạng thái: nhật ký tiến trình, danh sách tính năng, lịch sử git
+ +--> Kiểm chứng: bài kiểm tra, lint, kiểm tra kiểu, chạy thử
+ +--> Vòng đời: khởi tạo lúc bắt đầu, trạng thái sạch lúc kết thúc
|
v
- Agent stops only when
- verification passes
+ Agent chỉ dừng khi
+ kiểm chứng đạt yêu cầu
```
---
@@ -112,32 +112,32 @@ Một harness có năm hệ thống con:
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ Hướng dẫn │ │ Trạng thái │ │ Kiểm chứng │ │
│ │ │ │ │ │ │ │
│ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ kiểm tra kiểu │ │
+ │ │ feature_list │ │ git log │ │ chạy thử │ │
+ │ │ docs/ │ │ bàn giao phiên│ │ pipeline e2e │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ Phạm vi │ │ Vòng đời phiên │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ một tính │ │ init.sh lúc bắt đầu │ │
+ │ │ năng mỗi lần │ │ danh sách kiểm tra sạch lúc kết thúc │ │
+ │ │ định nghĩa │ │ ghi chú bàn giao cho phiên tiếp │ │
+ │ │ "hoàn thành" │ │ commit chỉ khi an toàn để tiếp tục │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ MÔ HÌNH quyết định viết code gì.
+ HARNESS điều phối khi nào, ở đâu và viết như thế nào.
+ Harness không làm mô hình thông minh hơn.
+ Nó làm đầu ra của mô hình đáng tin cậy hơn.
```
Mỗi hệ thống con có một nhiệm vụ duy nhất:
@@ -157,24 +157,24 @@ Câu hỏi không phải là "mô hình có thể viết code không?" Chúng c
Hiện tại, câu trả lời là: không thể nếu không có harness.
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ KHÔNG CÓ HARNESS CÓ HARNESS
+ ================ ==========
+
+ Phiên 1: agent viết code Phiên 1: agent đọc hướng dẫn
+ agent làm hỏng bài kiểm tra agent chạy init.sh
+ agent nói "xong rồi" agent làm một tính năng
+ bạn tự sửa thủ công agent kiểm chứng trước khi nói xong
+ agent cập nhật nhật ký tiến trình
+ Phiên 2: agent bắt đầu lại từ đầu agent commit trạng thái sạch
+ agent không nhớ
+ những gì đã xảy ra trước đó Phiên 2: agent đọc nhật ký tiến trình
+ agent làm lại từ đầu agent tiếp tục chính xác nơi đã dừng
+ hoặc làm hoàn toàn việc khác agent tiếp tục tính năng chưa xong
+ bạn lại phải sửa lại bạn đánh giá, không phải cứu vãn
+
+ Kết quả: bạn dành nhiều thời gian Kết quả: agent làm công việc,
+ dọn dẹp hơn là nếu bạn bạn kiểm chứng kết quả
+ tự làm lấy
```
Những câu hỏi mà khóa học này thực sự quan tâm:
@@ -205,13 +205,13 @@ Bạn không cần phải đọc cả 12 bài giảng trước khi bắt đầu
Ý tưởng rất đơn giản: thay vì chỉ viết prompt, hãy cho agent của bạn một bộ tệp có cấu trúc xác định phải làm gì, những gì đã làm, và cách kiểm chứng công việc. Các tệp này nằm trong kho mã của bạn, vì vậy mỗi phiên bắt đầu từ cùng một trạng thái.
```text
- YOUR PROJECT ROOT
- ├── AGENTS.md <-- the agent's operating manual
- ├── CLAUDE.md <-- (alternative, if using Claude Code)
- ├── init.sh <-- runs install + verify + start
- ├── feature_list.json <-- what features exist, which are done
- ├── claude-progress.md <-- what happened each session
- └── src/ <-- your actual code
+ THƯ MỤC GỐC DỰ ÁN CỦA BẠN
+ ├── AGENTS.md <-- sổ tay vận hành của agent
+ ├── CLAUDE.md <-- (thay thế, nếu dùng Claude Code)
+ ├── init.sh <-- chạy cài đặt + xác minh + khởi động
+ ├── feature_list.json <-- tính năng nào tồn tại, cái nào đã xong
+ ├── claude-progress.md <-- những gì đã xảy ra trong mỗi phiên
+ └── src/ <-- code thực tế của bạn
```
Lấy các mẫu khởi đầu từ [Thư viện tài nguyên](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) và đưa chúng vào dự án của bạn. Đó là tất cả. Bốn tệp, và các phiên agent của bạn sẽ đã ổn định hơn đáng kể so với việc chỉ chạy trên prompt.
@@ -224,28 +224,29 @@ Tất cả sáu dự án khóa học đều xoay quanh cùng một sản phẩm:
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ Ứng dụng Desktop Cơ sở Tri thức │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
- │ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ Danh sách tài │ │ Bảng Hỏi-Đáp ││
+ │ │ liệu │ │ ││
+ │ │ doc-001.md │ │ H: Harness engineering là gì?││
+ │ │ doc-002.md │ │ Đ: Môi trường được xây dựng ││
+ │ │ doc-003.md │ │ quanh một mô hình agent...││
+ │ │ ... │ │ [trích dẫn: doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ Thanh trạng thái: 42 tài liệu | 38 đã lập chỉ │││
+ │ │ mục | đồng bộ lần cuối 3p │││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ Tính năng cốt lõi:
+ ├── Nhập tài liệu cục bộ
+ ├── Quản lý thư viện tài liệu
+ ├── Xử lý và lập chỉ mục tài liệu
+ ├── Chạy Hỏi-Đáp AI trên nội dung đã nhập
+ └── Trả lời có căn cứ kèm trích dẫn
```
Dự án này được chọn vì nó kết hợp giá trị thực tế cao, đủ độ phức tạp sản phẩm thực tế, và môi trường tốt để quan sát sự cải thiện harness trước/sau.
@@ -259,47 +260,47 @@ Mỗi starter/solution của dự án khóa học là một bản sao hoàn ch
Khóa học được thiết kế để hoàn thành theo thứ tự. Mỗi giai đoạn xây dựng dựa trên giai đoạn trước.
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
+ Giai đoạn 1: NHÌN VẤN ĐỀ Giai đoạn 2: TỔ CHỨC KHO MÃ
+ ========================= ===========================
+
+ L01 Mô hình mạnh ≠ thực thi L03 Kho mã là nguồn
+ đáng tin cậy chân lý duy nhất
+ L02 Harness thực sự nghĩa là gì
+ L04 Chia hướng dẫn thành nhiều
+ | tệp, không phải một tệp khổng lồ
v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ P01 Chỉ dùng prompt vs. |
+ ưu tiên quy tắc v
+ P02 Không gian làm việc agent đọc được
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
+ Giai đoạn 3: KẾT NỐI CÁC PHIÊN Giai đoạn 4: PHẢN HỒI & PHẠM VI
+ ============================== ================================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
+ L05 Giữ ngữ cảnh sống L07 Vẽ ranh giới tác vụ rõ ràng
+ qua các phiên
+ L08 Danh sách tính năng như
+ L06 Khởi tạo trước mọi nguyên thủy harness
+ phiên agent
|
| v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ v P04 Phản hồi thời gian chạy
+ P03 Tính liên tục đa phiên sửa hành vi agent
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
+ Giai đoạn 5: KIỂM CHỨNG Giai đoạn 6: TỔNG HỢP TẤT CẢ
+ ========================= =============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ L09 Ngăn agent tuyên bố L11 Làm thời gian chạy của
+ hoàn thành quá sớm agent có thể quan sát
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L10 Chạy toàn bộ pipeline = L12 Bàn giao sạch ở cuối
+ kiểm chứng thực sự mọi phiên
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 Agent tự kiểm chứng P06 Xây dựng harness hoàn chỉnh
+ (dự án tổng kết)
```
Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gian. Nếu bạn muốn đi nhanh hơn, các giai đoạn 1-3 có thể hoàn thành trong một cuối tuần dài.
@@ -339,28 +340,31 @@ Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gia
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Xây dựng một harness hoàn chỉnh từ đầu (tổng kết) | Harness đầy đủ: tất cả cơ chế + khả năng quan sát + nghiên cứu ablation |
```text
- PROJECT EVOLUTION
- =================
+ SỰ PHÁT TRIỂN DỰ ÁN
+ ===================
- P01 Prompt-only vs. rules-first You see the problem
+ P01 Chỉ dùng prompt vs. ưu tiên Bạn nhìn thấy vấn đề
+ quy tắc
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 Không gian làm việc Bạn tái cấu trúc kho mã
+ agent đọc được
|
v
- P03 Multi-session continuity You connect sessions
+ P03 Tính liên tục đa phiên Bạn kết nối các phiên
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 Phản hồi & phạm vi Bạn thêm các vòng phản hồi
+ thời gian chạy
|
v
- P05 Self-verification You make the agent check itself
+ P05 Tự kiểm chứng Bạn khiến agent tự kiểm tra
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 Harness hoàn chỉnh (tổng kết) Bạn xây dựng hệ thống đầy đủ
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ Solution của mỗi dự án trở thành starter của dự án tiếp theo.
+ Ứng dụng phát triển. Kỹ năng harness của bạn lớn lên cùng nó.
```
### Thư viện tài nguyên
@@ -385,44 +389,44 @@ Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gia
Một trong những ý tưởng cốt lõi trong khóa học này: **phiên của agent nên tuân theo một vòng đời có cấu trúc, không phải tự do không kiểm soát.** Đây là cách nó trông như thế này:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ VÒNG ĐỜI PHIÊN AGENT
+ ====================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ BẮT ĐẦU │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. Agent đọc AGENTS.md / CLAUDE.md │
+ │ 2. Agent chạy init.sh (cài đặt, xác minh, kiểm tra sức khỏe) │
+ │ 3. Agent đọc claude-progress.md (đã xảy ra gì lần trước) │
+ │ 4. Agent đọc feature_list.json (cái gì xong, cái gì tiếp) │
+ │ 5. Agent kiểm tra git log (thay đổi gần đây) │
│ │
- │ SELECT │
+ │ CHỌN TÁC VỤ │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. Agent chọn chính xác MỘT tính năng chưa hoàn thành │
+ │ 7. Agent chỉ làm việc trên tính năng đó │
│ │
- │ EXECUTE │
+ │ THỰC THI │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. Agent triển khai tính năng │
+ │ 9. Agent chạy kiểm chứng (bài kiểm tra, lint, kiểm tra kiểu) │
+ │ 10. Nếu kiểm chứng thất bại: sửa và chạy lại │
+ │ 11. Nếu kiểm chứng đạt: ghi nhận bằng chứng │
│ │
- │ WRAP UP │
+ │ KẾT THÚC │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. Agent cập nhật claude-progress.md │
+ │ 13. Agent cập nhật feature_list.json │
+ │ 14. Agent ghi lại những gì vẫn còn lỗi hoặc chưa kiểm chứng │
+ │ 15. Agent commit (chỉ khi an toàn để tiếp tục) │
+ │ 16. Agent để lại đường khởi động lại sạch cho phiên tiếp │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness điều phối mọi chuyển đổi trong vòng đời này.
+ Mô hình quyết định viết code gì ở mỗi bước.
+ Không có harness, bước 9 trở thành "agent nói trông ổn rồi."
+ Có harness, bước 9 là "bài kiểm tra đạt, lint sạch, kiểu đúng."
```
---
diff --git a/docs-readme/zh-CN/README.md b/docs-readme/zh-CN/README.md
index 64c6474..3c4f741 100644
--- a/docs-readme/zh-CN/README.md
+++ b/docs-readme/zh-CN/README.md
@@ -84,8 +84,8 @@ OpenAI 在 Codex 上也报告了同样的事情:在一个良好 Harness 的仓
**这门课程教你如何构建那个环境。**
```text
- THE HARNESS PATTERN
- ====================
+ HARNESS 模式
+ =============
你 --> 给出任务 --> 代理读取 harness 文件 --> 代理执行
|
@@ -112,7 +112,7 @@ Harness Engineering 是围绕模型构建一个完整的工作环境,使其产
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS 系统 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ 指令 │ │ 状态 │ │ 验证 │ │
diff --git a/docs-readme/zh-TW/README.md b/docs-readme/zh-TW/README.md
index 98d57fe..f032ff3 100644
--- a/docs-readme/zh-TW/README.md
+++ b/docs-readme/zh-TW/README.md
@@ -84,22 +84,22 @@ OpenAI 也報告了 Codex 的相同結果:在一個 well-harnessed 的儲存
**這門課程教你如何建構那個環境。**
```text
- THE HARNESS PATTERN
- ====================
+ HARNESS 模式
+ ============
- You --> give task --> Agent reads harness files --> Agent executes
+ 你 --> 給定任務 --> 代理讀取 harness 檔案 --> 代理執行
|
- harness governs every step:
+ harness 管控每個步驟:
|
- +--> Instructions: what to do, in what order
- +--> Scope: one feature at a time, no overreach
- +--> State: progress log, feature list, git history
- +--> Verification: tests, lint, type-check, smoke runs
- +--> Lifecycle: init at start, clean state at end
+ +--> 指令:該做什麼,以什麼順序
+ +--> 範圍:一次一個功能,不過度延伸
+ +--> 狀態:進度日誌、功能列表、git 歷史
+ +--> 驗證:測試、lint、型別檢查、冒煙測試
+ +--> 生命週期:開始時初始化,結束時乾淨狀態
|
v
- Agent stops only when
- verification passes
+ 代理只在驗證通過時
+ 才會停止
```
---
@@ -112,32 +112,32 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
```text
┌─────────────────────────────────────────────────────────────────┐
- │ THE HARNESS │
+ │ HARNESS 系統 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
- │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ 指令 │ │ 狀態 │ │ 驗證 │ │
│ │ │ │ │ │ │ │
- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
- │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
- │ │ feature_list │ │ git log │ │ smoke runs │ │
- │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ │ AGENTS.md │ │ progress.md │ │ 測試 + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ 型別檢查 │ │
+ │ │ feature_list │ │ git log │ │ 冒煙測試 │ │
+ │ │ docs/ │ │ 工作階段交接 │ │ 端到端流程 │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
- │ │ Scope │ │ Session Lifecycle │ │
+ │ │ 範圍 │ │ 工作階段生命週期 │ │
│ │ │ │ │ │
- │ │ one feature │ │ init.sh at start │ │
- │ │ at a time │ │ clean-state checklist at end │ │
- │ │ definition │ │ handoff note for next session │ │
- │ │ of done │ │ commit only when safe to resume │ │
+ │ │ 一次一個功能 │ │ 開始時執行 init.sh │ │
+ │ │ 明確的完成 │ │ 結束時使用乾淨狀態檢查清單 │ │
+ │ │ 定義 │ │ 為下一個工作階段留下交接筆記 │ │
+ │ │ │ │ 只在可安全恢復時才提交 │ │
│ └──────────────┘ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- The MODEL decides what code to write.
- The HARNESS governs when, where, and how it writes it.
- The harness doesn't make the model smarter.
- It makes the model's output reliable.
+ 模型決定要寫什麼程式碼。
+ HARNESS 管控何時、在哪裡、以及如何撰寫。
+ Harness 不會讓模型變得更聰明。
+ 它讓模型的輸出變得可靠。
```
每個子系統各有其職責:
@@ -157,24 +157,23 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
目前的答案是:沒有 harness 就不行。
```text
- WITHOUT HARNESS WITH HARNESS
- ============== ============
-
- Session 1: agent writes code Session 1: agent reads instructions
- agent breaks tests agent runs init.sh
- agent says "done" agent works on one feature
- you fix it manually agent verifies before claiming done
- agent updates progress log
- Session 2: agent starts fresh agent commits clean state
- agent has no memory
- of what happened before Session 2: agent reads progress log
- agent re-does work agent picks up exactly where it left off
- or does something else entirely agent continues the unfinished feature
- you fix it again you review, not rescue
-
- Result: you spend more time Result: agent does the work,
- cleaning up than if you you verify the result
- did it yourself
+ 沒有 HARNESS 有 HARNESS
+ ============== ============
+
+ 工作階段 1:代理撰寫程式碼 工作階段 1:代理讀取指令
+ 代理破壞了測試 代理執行 init.sh
+ 代理說「完成了」 代理只做一個功能
+ 你手動修復 代理在宣告完成前先驗證
+ 代理更新進度日誌
+ 工作階段 2:代理從頭開始 代理提交乾淨狀態
+ 代理沒有記憶
+ 不知道之前發生了什麼 工作階段 2:代理讀取進度日誌
+ 代理重做工作 代理精確地從上次停止處接續
+ 或者做完全不同的事情 代理繼續未完成的功能
+ 你再次修復 你是審查,不是搶救
+
+ 結果:你花在清理的時間 結果:代理做工作,
+ 比自己動手做還多 你驗證結果
```
這門課程真正關心的問題:
@@ -205,7 +204,7 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
概念很簡單:與其只寫提示,不如給你的代理一組結構化的檔案,定義該做什麼、已經做了什麼、以及如何驗證工作。這些檔案存在你的儲存庫中,所以每個工作階段都從相同的狀態開始。
```text
- YOUR PROJECT ROOT
+ 你的專案根目錄
├── AGENTS.md <-- 代理的操作手冊
├── CLAUDE.md <-- (替代方案,如果使用 Claude Code)
├── init.sh <-- 執行安裝 + 驗證 + 啟動
@@ -224,28 +223,28 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
```text
┌─────────────────────────────────────────────────────┐
- │ Knowledge Base Desktop App │
+ │ 知識庫桌面應用程式 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐│
- │ │ Document List │ │ Q&A Panel ││
+ │ │ 文件列表 │ │ 問答面板 ││
│ │ │ │ ││
- │ │ doc-001.md │ │ Q: What is harness eng? ││
- │ │ doc-002.md │ │ A: The environment built ││
- │ │ doc-003.md │ │ around an agent model... ││
- │ │ ... │ │ [citation: doc-002.md] ││
+ │ │ doc-001.md │ │ 問:什麼是 harness 工程? ││
+ │ │ doc-002.md │ │ 答:圍繞代理模型建構的 ││
+ │ │ doc-003.md │ │ 環境...... ││
+ │ │ ... │ │ [引用來源:doc-002.md] ││
│ └──────────────┘ └──────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────┐│
- │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ │ 狀態列:42 篇文件 | 38 篇已索引 | 上次同步 3 分鐘前││
│ └─────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
- Core features:
- ├── Import local documents
- ├── Manage a document library
- ├── Process and index documents
- ├── Run AI-powered Q&A over imported content
- └── Return grounded answers with citations
+ 核心功能:
+ ├── 匯入本地文件
+ ├── 管理文件庫
+ ├── 處理和索引文件
+ ├── 對匯入內容執行 AI 問答
+ └── 回傳有依據的答案與引用來源
```
選擇這個專案是因為它結合了強大的實用價值、足夠的真實產品複雜度,以及觀察 harness 改善前後差異的良好場景。
@@ -259,47 +258,42 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
課程設計為按順序進行。每個階段建立在前一個階段之上。
```text
- Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
- ======================== ==========================
-
- L01 Strong models ≠ reliable L03 Repository as single
- execution source of truth
- L02 What harness actually means
- L04 Split instructions across
- | files, not one giant file
- v
- P01 Prompt-only vs. |
- rules-first comparison v
- P02 Agent-readable workspace
+ 階段 1:看見問題 階段 2:建構儲存庫結構
+ =================== ========================
+ L01 強大的模型 ≠ 可靠的執行 L03 儲存庫作為唯一真實來源
+ L02 Harness 到底是什麼意思
+ L04 將指令分散到多個檔案,
+ | 而非一個巨大檔案
+ v
+ P01 僅提示 vs. 規則優先比較 |
+ v
+ P02 代理可讀的工作空間
- Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
- ========================== =========================
- L05 Keep context alive L07 Draw clear task boundaries
- across sessions
- L08 Feature lists as harness
- L06 Initialize before every primitives
- agent session
- |
- | v
- v P04 Runtime feedback to
- P03 Multi-session continuity correct agent behavior
+ 階段 3:連接工作階段 階段 4:回饋與範圍
+ ======================= ==================
+ L05 跨工作階段保持上下文 L07 劃清任務邊界
+ L06 每次代理工作階段前初始化 L08 功能列表作為 harness
+ 基本元素
+ |
+ v P04 執行時回饋修正
+ P03 多工作階段連續性 代理行為
- Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
- ===================== ============================
- L09 Stop agents from L11 Make agent's runtime
- declaring victory early observable
+ 階段 5:驗證 階段 6:整合所有內容
+ ================= ========================
- L10 Full-pipeline run = L12 Clean handoff at end of
- real verification every session
+ L09 阻止代理過早宣告勝利 L11 讓代理的執行時行為
+ 可觀測
+ L10 完整流程執行 = L12 每個工作階段結束時
+ 真正的驗證 乾淨的交接
| |
v v
- P05 Agent verifies its own work P06 Build a complete harness
- (capstone project)
+ P05 代理驗證自己的工作 P06 建構完整的 harness
+ (畢業專案)
```
如果你是兼職學習,每個階段大約需要一週。如果你想加快速度,階段 1-3 可以在一個長週末完成。
@@ -339,28 +333,28 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | 從零建構一個完整的 harness(畢業專案) | 完整 harness:所有機制 + 可觀測性 + 消融實驗 |
```text
- PROJECT EVOLUTION
- =================
+ 專案演進
+ ========
- P01 Prompt-only vs. rules-first You see the problem
+ P01 僅提示 vs. 規則優先 你看見問題
|
v
- P02 Agent-readable workspace You restructure the repo
+ P02 代理可讀的工作空間 你重構儲存庫
|
v
- P03 Multi-session continuity You connect sessions
+ P03 多工作階段連續性 你連接工作階段
|
v
- P04 Runtime feedback & scope You add feedback loops
+ P04 執行時回饋與範圍控制 你加入回饋迴圈
|
v
- P05 Self-verification You make the agent check itself
+ P05 自我驗證 你讓代理檢查自己
|
v
- P06 Complete harness (capstone) You build the full system
+ P06 完整 harness(畢業專案) 你建構完整系統
- Each project's solution becomes the next project's starter.
- The app evolves. Your harness skills grow with it.
+ 每個專案的 solution 成為下一個專案的 starter。
+ 應用程式在演化。你的 harness 技能也隨之成長。
```
### 資源庫
@@ -385,44 +379,44 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
這門課程的核心理念之一:**代理的工作階段應該遵循結構化的生命週期,而不是隨意進行。** 以下是它的樣貌:
```text
- AGENT SESSION LIFECYCLE
- ======================
+ 代理工作階段生命週期
+ ===================
┌──────────────────────────────────────────────────────────────────┐
- │ START │
+ │ 開始 │
│ │
- │ 1. Agent reads AGENTS.md / CLAUDE.md │
- │ 2. Agent runs init.sh (install, verify, health check) │
- │ 3. Agent reads claude-progress.md (what happened last time) │
- │ 4. Agent reads feature_list.json (what's done, what's next) │
- │ 5. Agent checks git log (recent changes) │
+ │ 1. 代理讀取 AGENTS.md / CLAUDE.md │
+ │ 2. 代理執行 init.sh(安裝、驗證、健康檢查) │
+ │ 3. 代理讀取 claude-progress.md(上次發生了什麼事) │
+ │ 4. 代理讀取 feature_list.json(什麼已完成,什麼是下一步) │
+ │ 5. 代理檢查 git log(最近的變更) │
│ │
- │ SELECT │
+ │ 選擇 │
│ │
- │ 6. Agent picks exactly ONE unfinished feature │
- │ 7. Agent works only on that feature │
+ │ 6. 代理精確挑選一個未完成的功能 │
+ │ 7. 代理只做那個功能 │
│ │
- │ EXECUTE │
+ │ 執行 │
│ │
- │ 8. Agent implements the feature │
- │ 9. Agent runs verification (tests, lint, type-check) │
- │ 10. If verification fails: fix and re-run │
- │ 11. If verification passes: record evidence │
+ │ 8. 代理實作該功能 │
+ │ 9. 代理執行驗證(測試、lint、型別檢查) │
+ │ 10. 如果驗證失敗:修復並重新執行 │
+ │ 11. 如果驗證通過:記錄證據 │
│ │
- │ WRAP UP │
+ │ 收尾 │
│ │
- │ 12. Agent updates claude-progress.md │
- │ 13. Agent updates feature_list.json │
- │ 14. Agent records what's still broken or unverified │
- │ 15. Agent commits (only when safe to resume) │
- │ 16. Agent leaves clean restart path for next session │
+ │ 12. 代理更新 claude-progress.md │
+ │ 13. 代理更新 feature_list.json │
+ │ 14. 代理記錄仍然損壞或未驗證的部分 │
+ │ 15. 代理提交(只在可安全恢復時) │
+ │ 16. 代理為下一個工作階段留下乾淨的重啟路徑 │
│ │
└──────────────────────────────────────────────────────────────────┘
- The harness governs every transition in this lifecycle.
- The model decides what code to write at each step.
- Without the harness, step 9 becomes "agent says it looks fine."
- With the harness, step 9 is "tests pass, lint is clean, types check."
+ Harness 管控這個生命週期中的每個轉換。
+ 模型決定在每個步驟寫什麼程式碼。
+ 沒有 harness 時,步驟 9 變成「代理說看起來沒問題」。
+ 有了 harness 時,步驟 9 是「測試通過、lint 乾淨、型別檢查通過」。
```
---