Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
Translate 前沿 Harness 拆解 column to all 15 languages and fix Discord link
sanbuphy260a39938c2e
diff --git a/README.md b/README.mdindex f7dfea0..8e48308 100644--- a/README.md+++ b/README.md@@ -25,7 +25,7 @@<img src="https://img.shields.io/badge/Projects-8-green?style=flat-square" alt="8 Projects"><img src="https://img.shields.io/badge/Languages-15-yellow?style=flat-square" alt="15 Languages"><img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="MIT License">- <a href="https://discord.gg/XU7DQmpqk"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Join the Discord community"></a>+ <a href="https://github.com/walkinglabs"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Join the Discord community"></a></p>> 🌍 This course is available in **15 languages**: English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe, Portuguese (BR), Українська. Choose your language from the badges above.diff --git a/docs-readme/uk-UA/README.md b/docs-readme/uk-UA/README.mdindex 3f29f62..cf67dfd 100644--- a/docs-readme/uk-UA/README.md+++ b/docs-readme/uk-UA/README.md@@ -25,7 +25,7 @@<img src="https://img.shields.io/badge/Projects-8-green?style=flat-square" alt="8 проєктів"><img src="https://img.shields.io/badge/Languages-15-yellow?style=flat-square" alt="15 мов"><img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="Ліцензія MIT">- <a href="https://discord.gg/XU7DQmpqk"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Приєднатися до спільноти в Discord"></a>+ <a href="https://github.com/walkinglabs"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Приєднатися до спільноти в Discord"></a></p>> 🌍 Цей курс доступний **15 мовами**: English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe, Portuguese (BR), Українська. Оберіть свою мову за допомогою значків вище.diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex f8b1d04..d3be6ed 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -5,11 +5,12 @@ import { withMermaid } from "vitepress-plugin-mermaid";const docsBase = "/learn-harness-engineering/";const brandLogo = 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="%23D95C41" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><line x1="12.1" y1="11.9" x2="18.9" y2="8.2" /><line x1="12.1" y1="12.1" x2="20.3" y2="12.9" /><line x1="12.2" y1="12.4" x2="16.6" y2="19.1" /><line x1="11.8" y1="12.4" x2="7.3" y2="19.2" /><line x1="11.9" y1="12.1" x2="3.7" y2="13.3" /><line x1="11.8" y1="11.7" x2="7.8" y2="4.4" /></svg>';const githubRepoTreeLink = "https://github.com/walkinglabs/learn-harness-engineering/tree/main";-const discordInviteLink = "https://discord.gg/XU7DQmpqk";-const socialLinks = [+// Discord 邀请链接会过期,社区入口默认指向组织主页+const communityLink = "https://github.com/walkinglabs";+const socialLinks: Array<{ icon: "github" | "discord"; link: string }> = [{ icon: "github", link: githubRepoTreeLink },- { icon: "discord", link: discordInviteLink }-] as const;+ { icon: "discord", link: communityLink }+];const zhLectureItems = [{ text: "欢迎", link: "/zh/" },@@ -60,6 +61,14 @@ const zhHarnessDesignItems = [{ text: "拆解 DeepSeek Harness 的设计", link: "/zh/harness-designs/deepseek/" }];+const enHarnessDesignItems = [+ { text: "Frontier Harness Design Breakdowns", link: "/en/harness-designs/" },+ { text: "Breaking Down Pi's Harness Design", link: "/en/harness-designs/pi/" },+ { text: "Breaking Down Claude Code's Harness Design", link: "/en/harness-designs/claude-code/" },+ { text: "Breaking Down Codex's Harness Design", link: "/en/harness-designs/codex/" },+ { text: "Breaking Down DeepSeek Harness's Design", link: "/en/harness-designs/deepseek/" }+];+const enLectureItems = [{ text: "Welcome", link: "/en/" },{ text: "Why Capable Agents Still Fail", link: "/en/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -144,6 +153,22 @@ const viSkillItems = [{ text: "Tổng quan về Kỹ năng", link: "/vi/skills/" },];+const viHarnessDesignItems = [+ { text: "Phân tích các harness tiên tiến", link: "/vi/harness-designs/" },+ { text: "Phân tích thiết kế harness của Pi", link: "/vi/harness-designs/pi/" },+ { text: "Phân tích thiết kế harness của Claude Code", link: "/vi/harness-designs/claude-code/" },+ { text: "Phân tích thiết kế harness của Codex", link: "/vi/harness-designs/codex/" },+ { text: "Phân tích thiết kế DeepSeek Harness", link: "/vi/harness-designs/deepseek/" }+];++const ruHarnessDesignItems = [+ { text: "Разбор передовых harness", link: "/ru/harness-designs/" },+ { text: "Разбор дизайна harness в Pi", link: "/ru/harness-designs/pi/" },+ { text: "Разбор дизайна harness в Claude Code", link: "/ru/harness-designs/claude-code/" },+ { text: "Разбор дизайна harness в Codex", link: "/ru/harness-designs/codex/" },+ { text: "Разбор дизайна DeepSeek Harness", link: "/ru/harness-designs/deepseek/" }+];+const ruLectureItems = [{ text: "Добро пожаловать", link: "/ru/" },{ text: "Сильная модель ≠ надёжное исполнение", link: "/ru/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -230,6 +255,22 @@ const uzSkillItems = [{ text: "Malakalar umumiy koʻrinishi", link: "/uz/skills/" },];+const uzHarnessDesignItems = [+ { text: "Ilgʻor harness dizaynlari tahlili", link: "/uz/harness-designs/" },+ { text: "Pi harness dizayni tahlili", link: "/uz/harness-designs/pi/" },+ { text: "Claude Code harness dizayni tahlili", link: "/uz/harness-designs/claude-code/" },+ { text: "Codex harness dizayni tahlili", link: "/uz/harness-designs/codex/" },+ { text: "DeepSeek Harness dizayni tahlili", link: "/uz/harness-designs/deepseek/" }+];++const koHarnessDesignItems = [+ { text: "최전선 Harness 분석", link: "/ko/harness-designs/" },+ { text: "Pi의 harness 설계 분석", link: "/ko/harness-designs/pi/" },+ { text: "Claude Code의 harness 설계 분석", link: "/ko/harness-designs/claude-code/" },+ { text: "Codex의 harness 설계 분석", link: "/ko/harness-designs/codex/" },+ { text: "DeepSeek Harness 설계 분석", link: "/ko/harness-designs/deepseek/" }+];+const koLectureItems = [{ text: "환영합니다", link: "/ko/" },{ text: "유능한 에이전트가 여전히 실패하는 이유", link: "/ko/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -275,6 +316,14 @@ const koSkillItems = [{ text: "스킬 개요", link: "/ko/skills/" },];+const jaHarnessDesignItems = [+ { text: "最前線の Harness 設計を読み解く", link: "/ja/harness-designs/" },+ { text: "Pi の harness 設計を読み解く", link: "/ja/harness-designs/pi/" },+ { text: "Claude Code の harness 設計を読み解く", link: "/ja/harness-designs/claude-code/" },+ { text: "Codex の harness 設計を読み解く", link: "/ja/harness-designs/codex/" },+ { text: "DeepSeek Harness の設計を読み解く", link: "/ja/harness-designs/deepseek/" }+];+const jaLectureItems = [{ text: "ようこそ", link: "/ja/" },{ text: "強いモデルは信頼できる実行を意味しない", link: "/ja/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -318,6 +367,14 @@ const jaSkillItems = [{ text: "スキル概要", link: "/ja/skills/" },];+const esHarnessDesignItems = [+ { text: "Análisis de los harness más avanzados", link: "/es/harness-designs/" },+ { text: "Análisis del diseño del harness de Pi", link: "/es/harness-designs/pi/" },+ { text: "Análisis del diseño del harness de Claude Code", link: "/es/harness-designs/claude-code/" },+ { text: "Análisis del diseño del harness de Codex", link: "/es/harness-designs/codex/" },+ { text: "Análisis del diseño de DeepSeek Harness", link: "/es/harness-designs/deepseek/" }+];+const esLectureItems = [{ text: "Bienvenido", link: "/es/" },{ text: "Los modelos fuertes no significan ejecución fiable", link: "/es/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -361,6 +418,14 @@ const esSkillItems = [{ text: "Resumen de Skills", link: "/es/skills/" },];+const frHarnessDesignItems = [+ { text: "Décryptage des harnesses de pointe", link: "/fr/harness-designs/" },+ { text: "Décryptage de la conception du harness de Pi", link: "/fr/harness-designs/pi/" },+ { text: "Décryptage de la conception du harness de Claude Code", link: "/fr/harness-designs/claude-code/" },+ { text: "Décryptage de la conception du harness de Codex", link: "/fr/harness-designs/codex/" },+ { text: "Décryptage de la conception de DeepSeek Harness", link: "/fr/harness-designs/deepseek/" }+];+const frLectureItems = [{ text: "Bienvenue", link: "/fr/" },{ text: "Les modèles forts ne garantissent pas une exécution fiable", link: "/fr/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -404,6 +469,14 @@ const frSkillItems = [{ text: "Aperçu des Skills", link: "/fr/skills/" },];+const deHarnessDesignItems = [+ { text: "Analyse führender Harness-Designs", link: "/de/harness-designs/" },+ { text: "Analyse des harness-Designs von Pi", link: "/de/harness-designs/pi/" },+ { text: "Analyse des harness-Designs von Claude Code", link: "/de/harness-designs/claude-code/" },+ { text: "Analyse des harness-Designs von Codex", link: "/de/harness-designs/codex/" },+ { text: "Analyse des Designs von DeepSeek Harness", link: "/de/harness-designs/deepseek/" }+];+const deLectureItems = [{ text: "Willkommen", link: "/de/" },{ text: "Starke Modelle bedeuten keine zuverlässige Ausführung", link: "/de/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -490,6 +563,14 @@ const arSkillItems = [{ text: "نظرة عامة على المهارات", link: "/ar/skills/" },];+const arHarnessDesignItems = [+ { text: "تحليل تصميمات Harness المتقدمة", link: "/ar/harness-designs/" },+ { text: "تفكيك تصميم harness في Pi", link: "/ar/harness-designs/pi/" },+ { text: "تفكيك تصميم harness في Claude Code", link: "/ar/harness-designs/claude-code/" },+ { text: "تفكيك تصميم harness في Codex", link: "/ar/harness-designs/codex/" },+ { text: "تحليل تصميم DeepSeek Harness", link: "/ar/harness-designs/deepseek/" }+];+const trLectureItems = [{ text: "Hoş geldiniz", link: "/tr/" },{ text: "Güçlü Ajanlar Neden Hâlâ Başarısız Olur", link: "/tr/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -533,6 +614,22 @@ const trSkillItems = [{ text: "Yetenekler Genel Bakış", link: "/tr/skills/" },];+const trHarnessDesignItems = [+ { text: "Öncü Harness Tasarımlarının İncelenmesi", link: "/tr/harness-designs/" },+ { text: "Pi Harness Tasarımının İncelenmesi", link: "/tr/harness-designs/pi/" },+ { text: "Claude Code'un harness tasarımının incelenmesi", link: "/tr/harness-designs/claude-code/" },+ { text: "Codex'in harness tasarımının incelenmesi", link: "/tr/harness-designs/codex/" },+ { text: "DeepSeek Harness tasarımının incelenmesi", link: "/tr/harness-designs/deepseek/" }+];++const zhTWHarnessDesignItems = [+ { text: "前沿 Harness 拆解", link: "/zh-TW/harness-designs/" },+ { text: "拆解 Pi 的 harness 設計", link: "/zh-TW/harness-designs/pi/" },+ { text: "拆解 Claude Code 的 harness 設計", link: "/zh-TW/harness-designs/claude-code/" },+ { text: "拆解 Codex 的 harness 設計", link: "/zh-TW/harness-designs/codex/" },+ { text: "拆解 DeepSeek Harness 的設計", link: "/zh-TW/harness-designs/deepseek/" }+];+const zhTWLectureItems = [{ text: "歡迎", link: "/zh-TW/" },{ text: "模型能力強,不等於執行可靠", link: "/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -617,6 +714,14 @@ const ptBRSkillItems = [{ text: "Visão Geral das Skills", link: "/pt-BR/skills/" },];+const ptBRHarnessDesignItems = [+ { text: "Análise dos harnesses de ponta", link: "/pt-BR/harness-designs/" },+ { text: "Análise do Design de Harness do Pi", link: "/pt-BR/harness-designs/pi/" },+ { text: "Análise do design de harness do Claude Code", link: "/pt-BR/harness-designs/claude-code/" },+ { text: "Análise do design de harness do Codex", link: "/pt-BR/harness-designs/codex/" },+ { text: "Análise do Design do DeepSeek Harness", link: "/pt-BR/harness-designs/deepseek/" }+];+const ukLectureItems = [{ text: "Вітаємо", link: "/uk/" },{ text: "Сильна модель не гарантує надійного виконання", link: "/uk/lectures/lecture-01-why-capable-agents-still-fail/" },@@ -660,14 +765,22 @@ const ukSkillItems = [{ text: "Огляд Skills", link: "/uk/skills/" },];-const jaSourceItems = { lectures: jaLectureItems, projects: jaProjectItems, resources: jaResourceItems, skills: jaSkillItems };-const esSourceItems = { lectures: esLectureItems, projects: esProjectItems, resources: esResourceItems, skills: esSkillItems };-const frSourceItems = { lectures: frLectureItems, projects: frProjectItems, resources: frResourceItems, skills: frSkillItems };-const deSourceItems = { lectures: deLectureItems, projects: deProjectItems, resources: deResourceItems, skills: deSkillItems };-const arSourceItems = { lectures: arLectureItems, projects: arProjectItems, resources: arResourceItems, skills: arSkillItems };-const zhTWSourceItems = { lectures: zhTWLectureItems, projects: zhTWProjectItems, resources: zhTWResourceItems, skills: zhTWSkillItems };-const trSourceItems = { lectures: trLectureItems, projects: trProjectItems, resources: trResourceItems, skills: trSkillItems };-const ukSourceItems = { lectures: ukLectureItems, projects: ukProjectItems, resources: ukResourceItems, skills: ukSkillItems };+const ukHarnessDesignItems = [+ { text: "Розбір передових harness", link: "/uk/harness-designs/" },+ { text: "Розбір дизайну harness у Pi", link: "/uk/harness-designs/pi/" },+ { text: "Розбір дизайну harness у Claude Code", link: "/uk/harness-designs/claude-code/" },+ { text: "Розбір дизайну harness у Codex", link: "/uk/harness-designs/codex/" },+ { text: "Розбір дизайну DeepSeek Harness", link: "/uk/harness-designs/deepseek/" }+];++const jaSourceItems = { lectures: jaLectureItems, projects: jaProjectItems, resources: jaResourceItems, skills: jaSkillItems, harnessDesigns: jaHarnessDesignItems };+const esSourceItems = { lectures: esLectureItems, projects: esProjectItems, resources: esResourceItems, skills: esSkillItems, harnessDesigns: esHarnessDesignItems };+const frSourceItems = { lectures: frLectureItems, projects: frProjectItems, resources: frResourceItems, skills: frSkillItems, harnessDesigns: frHarnessDesignItems };+const deSourceItems = { lectures: deLectureItems, projects: deProjectItems, resources: deResourceItems, skills: deSkillItems, harnessDesigns: deHarnessDesignItems };+const arSourceItems = { lectures: arLectureItems, projects: arProjectItems, resources: arResourceItems, skills: arSkillItems, harnessDesigns: arHarnessDesignItems };+const zhTWSourceItems = { lectures: zhTWLectureItems, projects: zhTWProjectItems, resources: zhTWResourceItems, skills: zhTWSkillItems, harnessDesigns: zhTWHarnessDesignItems };+const trSourceItems = { lectures: trLectureItems, projects: trProjectItems, resources: trResourceItems, skills: trSkillItems, harnessDesigns: trHarnessDesignItems };+const ukSourceItems = { lectures: ukLectureItems, projects: ukProjectItems, resources: ukResourceItems, skills: ukSkillItems, harnessDesigns: ukHarnessDesignItems };const relinkItems = (items: Array<{ text: string; link: string }>, locale: string) =>items.map((item) => ({@@ -685,6 +798,7 @@ const createLocaleTheme = (projects: Array<{ text: string; link: string }>;resources: Array<{ text: string; link: string }>;skills: Array<{ text: string; link: string }>;+ harnessDesigns?: Array<{ text: string; link: string }>;},labels: {lectures: string;@@ -693,6 +807,7 @@ const createLocaleTheme = (skills: string;resourceLibrary: string;tryHarness: string;+ harnessDesign?: string;outline?: string;prev?: string;next?: string;@@ -708,6 +823,9 @@ const createLocaleTheme = (const projects = relinkItems(sourceItems.projects, locale);const resources = relinkItems(sourceItems.resources, locale);const skills = relinkItems(sourceItems.skills, locale);+ const harnessDesigns = sourceItems.harnessDesigns+ ? relinkItems(sourceItems.harnessDesigns, locale)+ : undefined;return {nav: [@@ -715,16 +833,22 @@ const createLocaleTheme = ({ text: labels.projects, link: projects[0].link, activeMatch: `^/${locale}/projects/` },{ text: labels.resources, link: `/${locale}/resources/`, activeMatch: `^/${locale}/resources/` },{ text: labels.skills, link: `/${locale}/skills/`, activeMatch: `^/${locale}/skills/` },+ ...(harnessDesigns+ ? [{ text: labels.harnessDesign as string, link: harnessDesigns[0].link, activeMatch: `^/${locale}/harness-designs/` }]+ : []),{ text: labels.tryHarness, link: `https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/${locale}/resources/templates/index.md`, target: "_blank", rel: "noopener noreferrer" },],sidebar: {[`/${locale}/projects/`]: [{ text: labels.projects, items: projects }],[`/${locale}/resources/`]: [{ text: labels.resourceLibrary, items: resources }],[`/${locale}/skills/`]: [{ text: labels.skills, items: skills }],+ ...(harnessDesigns+ ? { [`/${locale}/harness-designs/`]: [{ text: labels.harnessDesign, items: harnessDesigns }] }+ : {}),[`/${locale}/`]: [{ text: labels.lectures, items: lectures }]},outline: {- level: [2, 3],+ level: [2, 3] as [number, number],...(labels.outline ? { label: labels.outline } : {})},docFooter: {@@ -747,7 +871,8 @@ const enSourceItems = {lectures: enLectureItems,projects: enProjectItems,resources: enResourceItems,- skills: enSkillItems+ skills: enSkillItems,+ harnessDesigns: enHarnessDesignItems};const zhSourceItems = {@@ -807,12 +932,14 @@ export default withMermaid({ text: "Projects", link: enProjectItems[0].link, activeMatch: '^/en/projects/' },{ text: "Library", link: "/en/resources/", activeMatch: '^/en/resources/' },{ text: "Skills", link: "/en/skills/", activeMatch: '^/en/skills/' },+ { text: "Frontier Harness Design Breakdowns", link: "/en/harness-designs/", activeMatch: '^/en/harness-designs/' },{ text: "Try Harness ↗", link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/index.md", target: "_blank", rel: "noopener noreferrer" }],sidebar: {'/en/projects/': [{ text: "Projects", items: enProjectItems }],'/en/resources/': [{ text: "Resource Library", items: enResourceItems }],'/en/skills/': [{ text: "Skills", items: enSkillItems }],+ '/en/harness-designs/': [{ text: "Frontier Harness Design Breakdowns", items: enHarnessDesignItems }],'/en/': [{ text: "Lectures", items: enLectureItems }]},socialLinks@@ -889,6 +1016,7 @@ export default withMermaid(resources: "資源庫",skills: "技能",resourceLibrary: "資源庫",+ harnessDesign: "前沿 Harness 拆解",tryHarness: "Try Harness ↗",prev: "上一篇",next: "下一篇",@@ -910,6 +1038,7 @@ export default withMermaid(resources: "リソース",skills: "スキル",resourceLibrary: "リソースライブラリ",+ harnessDesign: "最前線の Harness 設計を読み解く",tryHarness: "Try Harness ↗",outline: "このページ",prev: "前へ",@@ -954,6 +1083,7 @@ export default withMermaid(resources: "Bibliothèque",skills: "Skills",resourceLibrary: "Bibliothèque de ressources",+ harnessDesign: "Décryptage des harnesses de pointe",tryHarness: "Try Harness ↗",outline: "Sur cette page",prev: "Précédent",@@ -1020,6 +1150,7 @@ export default withMermaid(resources: "المكتبة",skills: "المهارات",resourceLibrary: "مكتبة الموارد",+ harnessDesign: "تحليل تصميمات Harness المتقدمة",tryHarness: "Try Harness ↗",outline: "في هذه الصفحة",prev: "السابق",@@ -1058,6 +1189,11 @@ export default withMermaid(link: "/vi/skills/",activeMatch: "^/vi/skills/",},+ {+ text: "Phân tích các harness tiên tiến",+ link: "/vi/harness-designs/",+ activeMatch: "^/vi/harness-designs/",+ },{text: "Try Harness ↗",link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/vi/resources/templates/index.md",@@ -1071,6 +1207,7 @@ export default withMermaid({ text: "Thư viện Tài nguyên", items: viResourceItems },],"/vi/skills/": [{ text: "Kỹ năng", items: viSkillItems }],+ "/vi/harness-designs/": [{ text: "Phân tích các harness tiên tiến", items: viHarnessDesignItems }],"/vi/": [{ text: "Bài giảng", items: viLectureItems }],},outline: {@@ -1113,6 +1250,7 @@ export default withMermaid(activeMatch: "^/ko/resources/",},{ text: "스킬", link: "/ko/skills/", activeMatch: "^/ko/skills/" },+ { text: "최전선 Harness 분석", link: "/ko/harness-designs/", activeMatch: "^/ko/harness-designs/" },{text: "Try Harness ↗",link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ko/resources/templates/index.md",@@ -1124,6 +1262,7 @@ export default withMermaid("/ko/projects/": [{ text: "프로젝트", items: koProjectItems }],"/ko/resources/": [{ text: "리소스 모음", items: koResourceItems }],"/ko/skills/": [{ text: "스킬", items: koSkillItems }],+ "/ko/harness-designs/": [{ text: "최전선 Harness 분석", items: koHarnessDesignItems }],"/ko/": [{ text: "강의", items: koLectureItems }],},outline: {@@ -1171,6 +1310,11 @@ export default withMermaid(link: "/uz/skills/",activeMatch: "^/uz/skills/",},+ {+ text: "Ilgʻor harness dizaynlari tahlili",+ link: "/uz/harness-designs/",+ activeMatch: "^/uz/harness-designs/",+ },{text: "Harness'ni sinash ↗",link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uz/resources/templates/index.md",@@ -1184,6 +1328,7 @@ export default withMermaid({ text: "Resurslar kutubxonasi", items: uzResourceItems },],"/uz/skills/": [{ text: "Malakalar", items: uzSkillItems }],+ "/uz/harness-designs/": [{ text: "Ilgʻor harness dizaynlari tahlili", items: uzHarnessDesignItems }],"/uz/": [{ text: "Maʼruzalar", items: uzLectureItems }],},outline: {@@ -1231,6 +1376,7 @@ export default withMermaid(link: "/ru/skills/",activeMatch: "^/ru/skills/",},+ { text: "Разбор передовых harness", link: "/ru/harness-designs/", activeMatch: "^/ru/harness-designs/" },{text: "Try Harness ↗",link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ru/resources/templates/index.md",@@ -1242,6 +1388,7 @@ export default withMermaid("/ru/projects/": [{ text: "Проекты", items: ruProjectItems }],"/ru/resources/": [{ text: "Материалы", items: ruResourceItems }],"/ru/skills/": [{ text: "Скиллы", items: ruSkillItems }],+ "/ru/harness-designs/": [{ text: "Разбор передовых harness", items: ruHarnessDesignItems }],"/ru/": [{ text: "Лекции", items: ruLectureItems }],},outline: {@@ -1289,6 +1436,11 @@ export default withMermaid(link: "/pt-BR/skills/",activeMatch: "^/pt-BR/skills/",},+ {+ text: "Análise dos harnesses de ponta",+ link: "/pt-BR/harness-designs/",+ activeMatch: "^/pt-BR/harness-designs/",+ },{text: "Experimente Harness ↗",link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/pt-BR/resources/templates/index.md",@@ -1302,6 +1454,7 @@ export default withMermaid({ text: "Biblioteca de recursos", items: ptBRResourceItems },],"/pt-BR/skills/": [{ text: "Skills", items: ptBRSkillItems }],+ "/pt-BR/harness-designs/": [{ text: "Análise dos harnesses de ponta", items: ptBRHarnessDesignItems }],"/pt-BR/": [{ text: "Aulas", items: ptBRLectureItems }],},outline: {@@ -1333,6 +1486,7 @@ export default withMermaid(resources: "Бібліотека",skills: "Skills",resourceLibrary: "Бібліотека ресурсів",+ harnessDesign: "Розбір передових harness",tryHarness: "Try Harness ↗",outline: "На цій сторінці",prev: "Назад",diff --git a/docs/ar/harness-designs/claude-code/index.md b/docs/ar/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..b07e32e--- /dev/null+++ b/docs/ar/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# تحليل تصميم harness في Claude Code++توضح Anthropic في مقال [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) أن مصدر الموثوقية هو harness لا النموذج، وأن الـ agent يحتاج إلى قيود «خارج النموذج». ويعد Claude Code التجسيد العملي لهذه الفكرة؛ إذ تصنّفه Anthropic رسميًا ضمن فئة **agentic harness**. وليس ذلك شعارًا تسويقيًا—فلعل Claude Code أكثر harness جرى تحليله علنًا حتى الآن: شيفرته المصدرية مفتوحة، وتقارير المجتمع البحثية عنه مفصلة، كما حوّل معظم الآليات الجوهرية في محاضرات الدورة (الذاكرة الطبقية، وcompaction السياق، وpermissions، وhooks، وsubagents، واستمرارية session) إلى تطبيق متكامل على مستوى المنتج.++نحلل في هذه المقالة Claude Code باستخدام إطار الأنظمة الفرعية الخمسة في الدورة، مع التركيز على كيفية تطبيقه مفاهيم harness الأساسية مثل «إدارة السياق» و«منع إعلان الإنجاز مبكرًا» و«القيود الحتمية».++## التعريف في جملة واحدة++جوهر Claude Code حلقة while بسيطة: استدعاء النموذج، وتنفيذ الأدوات، وملاحظة النتائج، ثم استدعاء النموذج مجددًا. لكن **الغالبية الساحقة من الشيفرة ليست داخل هذه الحلقة، بل في النظام المحيط بها**—نظام permissions، ومسار compaction للسياق، وآليات التوسعة، وتنسيق subagents، وتخزين session. وهذه هي ماهية harness: الحلقة هي الهيكل العظمي، وما يقع خارجها هو ما يحدد الموثوقية.++## النظام الفرعي للتعليمات: منظومة ذاكرة طبقية++يمثل نظام الذاكرة في Claude Code إسهامه الأكثر مباشرة في نظرية harness، وهو يقابل محاضرتي «المستودع هو مصدر الحقيقة» و«استمرارية السياق عبر sessions» في الدورة. توضح [الوثيقة الرسمية «How Claude remembers your project»](https://code.claude.com/docs/en/memory) أن كل session يبدأ بنافذة سياق جديدة تمامًا، وأن المعرفة تنتقل بين sessions بواسطة آليتين: ملفات CLAUDE.md (التعليمات التي تكتبها) وauto memory (الملاحظات التي يكتبها Claude بنفسه).++ومن حيث النطاق، تقسم الوثائق الرسمية ملفات CLAUDE.md إلى أربع فئات (بترتيب التحميل من الأوسع إلى الأضيق):++- **مستوى سياسة المؤسسة**: تديره فرق IT/DevOps مركزيًا (مثل `/etc/claude-code/CLAUDE.md`) لقواعد المؤسسة.+- **مستوى المستخدم `~/.claude/CLAUDE.md`**: التفضيلات والقواعد الشخصية العابرة للمشروعات.+- **مستوى المشروع `./CLAUDE.md` أو `./.claude/CLAUDE.md`**: مصدر الحقيقة للمشروع، ويشمل بنية المشروع، والمكدس التقني، وأوامر التحقق، ويُشارك مع المستودع.+- **المستوى المحلي `./CLAUDE.local.md`**: التفضيلات الشخصية داخل المشروع، ويضاف عادة إلى `.gitignore` ولا يُعتمد.++وتوجد آليتان إضافيتان:++- **التحميل عند الطلب على مستوى الدليل الفرعي**: لا تُحمّل ملفات CLAUDE.md في الأدلة الفرعية عند بدء التشغيل، بل تدخل السياق عندما يقرأ Claude ملفًا في ذلك الدليل.+- **الذاكرة التلقائية (auto memory)**: يكتب Claude ملاحظات بصورة استباقية بناءً على تصحيحاتك وتفضيلاتك؛ وتُشارك على مستوى المستودع وتعمل عبر worktree، مع تحميل أول 200 سطر أو 25KB كحد أقصى في كل session.++تشكل هذه النطاقات الأربعة **تدرجًا للتعليمات**: تقول الوثائق الرسمية إن «التعليمات الأكثر تحديدًا تدخل السياق في وقت لاحق» (فتظهر تعليمات المشروع بعد تعليمات المستخدم). وتكمن القيمة في ألّا يُجبر النموذج على استيعاب ملف تعليمات ضخم كامل في بداية كل محادثة، بل تُحمّل التعليمات محليًا بحسب نطاقها. وهذا هو الجواب العملي عن سؤال المحاضرة الرابعة: «لماذا يفشل ملف التعليمات العملاق الواحد؟».++## النظام الفرعي للسياق: مسار compaction من خمس طبقات++تدير Claude Code السياق عبر **مسار compaction من خمس طبقات** (five-layer compaction pipeline)، لا بمجرد «التلخيص عند الامتلاء»—وتأتي هذه التفصيلة البنيوية من تحليل الشيفرة المصدرية في تقرير [VILA Lab «Dive into Claude Code»](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). تشرح المحاضرة الخامسة أن «المهام الطويلة تفقد الاستمرارية»، وحل Claude Code هو قمع متعدد المراحل: يبدأ بالتقليم غير الفاقد (إزالة نتائج الأدوات الزائدة)، ثم الاستخلاص المنظم، ولا يلجأ إلى تلخيص LLM الفاقد إلا في النهاية، مع آلية قاطع دائرة تمنع compaction المفرط.++ويكمل ذلك تصميم تخزين session: **تخزين session موجّه إلى الإلحاق (append-oriented storage)**، تُلحق فيه كل السجلات بـ `history.jsonl`، مع دعم الاستئناف عبر `/resume` والتفرع fork. وهذا يضمن «إجراء تسليم جيد قبل نهاية كل session»—لا بفضل ذاكرة قوية، بل لأن طبقة التخزين إلحاقية وقابلة لإعادة التشغيل.++## النظام الفرعي للأدوات: أربع آليات للتوسعة++يقسّم Claude Code سطح التوسعة إلى أربع فئات، تعالج كل منها نوعًا مختلفًا من المشكلات، وهذا أكثر ما يستحق الاقتباس في تصميمه:++- **Skills**: تعرفها [الوثائق الرسمية](https://code.claude.com/docs/en/skills) بأنها معرفة إجرائية يصفها `SKILL.md`، وتُحمّل تلقائيًا وفق كلمات التشغيل، مع إفصاح تدريجي. وهي ملائمة لمعرفة المجال المتعلقة بـ «كيفية تنفيذ شيء ما».+- **MCP**: يربط بروتوكول JSON-RPC الوارد في [الوثائق الرسمية](https://code.claude.com/docs/en/mcp) الأنظمة الخارجية، وهو الواجهة القياسية التي «تمد يد النموذج إلى العالم الخارجي».+- **Hooks**: نصوص حتمية تعلّقها [الوثائق الرسمية](https://code.claude.com/docs/en/hooks) بأحداث دورة الحياة مثل `PreToolUse` و`PostToolUse` و`Stop`.+- **Plugins / Subagents**: توكل [الوثائق الرسمية](https://code.claude.com/docs/en/sub-agents) المهام المعقدة إلى agent متخصص.++قرار التصميم الأساسي هو **فصل المسؤوليات**: يدير CLAUDE.md «ما هو الشيء»، وتدير Skills «كيفية فعله»، ويدير MCP «بماذا نتصل»، وتدير Hooks «متى نفرضه». وإذا خلط الفريق هذه الطبقات (مثل كتابة ما يخص MCP في CLAUDE.md)، ظهر تسرّب السياق الذي تصفه الدورة.++## التغذية الراجعة والتحقق: قيود حتمية + تقسيم العمل بين الإنسان والآلة++تتناول المحاضرة العاشرة أن «التحقق الحقيقي لا يتم إلا بتشغيل المسار الكامل»، ويقابل ذلك في Claude Code مساران:++**1. نظام permissions (قيود حتمية).** لا يتعامل Claude Code مع permissions بمنطق «اسأل عن كل شيء»، بل يستخدم سبعة أوضاع + مصنّف قائم على ML: يسمح بالعمليات منخفضة المخاطر، ويسأل أو يرفض العمليات عالية المخاطر وفق السياسة (راجع التفاصيل البنيوية في [تحليل VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). وهكذا تتحول فكرة «وضع حدود واضحة لكل مهمة agent» (المحاضرة السابعة) إلى فرض في runtime، بدل التوسل إليها في الموجّه.++**2. Hooks (منع إعلان الإنجاز مبكرًا).** يستطيع hook من نوع `PostToolUse` فرض تشغيل الفحوص بعد تنفيذ الأداة وكتابة النتائج مرة أخرى في السياق؛ ويتدخل hook من نوع `Stop` عندما يعلن الـ agent اكتمال العمل. وهذا يعني «فصل من ينفذ العمل عمن يفحصه»—إذ [لاحظت Anthropic صراحة في مقال harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) أن الـ agent يمدح عمله بثقة، ولذلك تستخدم hooks لحقن فحوص **حتمية** بدل الوثوق بالتقييم الذاتي للنموذج.++**3. Subagents (عزل السياق).** يُحفظ سجل محادثة كل subagent في ملف sidechain مستقل، و**لا يؤدي إلى تضخيم سياق agent الأب** (راجع [تحليل VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). ويجمع ذلك بين «حدود المهمة» و«عزل السياق»: فعند تقسيم المهمة، يُعزل تلوث السياق أيضًا.++## قابلية الرصد واستمرارية session++سجل Claude Code كامل وإلحاقي (history.jsonl)، ومع الأوامر الصريحة `/compact` و`/clear` و`/init` يمكنك إدارة حالة السياق استباقيًا، بدل انتظار امتلائه. ويحوّل `/init` فكرة «تهيئة الـ agent قبل كل عمل» (المحاضرة السادسة) إلى أمر—إذ تقول [الوثائق الرسمية](https://code.claude.com/docs/en/memory) إنه يحلل قاعدة الشيفرة تلقائيًا وينشئ CLAUDE.md أوليًا (يتضمن أوامر البناء، وتعليمات الاختبار، وأعراف المشروع).++## المواءمة مع إطار الدورة++| النظام الفرعي | تطبيق Claude Code | التقييم |+| --- | --- | --- |+| التعليمات | طبقات بحسب النطاق (المؤسسة/المستخدم/المشروع/المحلي) + ذاكرة تلقائية | الذاكرة الطبقية تطبيق مرجعي |+| الأدوات | أربعة أنواع من التوسعات: المهارات + MCP + الخطافات + الوكلاء الفرعيون | تقسيم واضح للمسؤوليات، وهو أبرز نقاط القوة |+| البيئة | إعدادات داخل المشروع + settings.json | تعتمد على وصف المستخدم الذاتي في CLAUDE.md |+| الحالة | تخزين جلسة إلحاقي + ضغط من خمس طبقات + resume/fork | قوي جدًا، وتطبيق مرجعي لاستمرارية المهام الطويلة |+| التغذية الراجعة | مصنّف أذونات + فحوص إلزامية عبر خطاف PostToolUse | يحوّل «منع إعلان الإنجاز مبكرًا» إلى آلية حتمية |++## تصميمات جديرة بالاقتباس++1. **تقسيم التعليمات إلى طبقات بحسب النطاق**، بدل تكديسها في ملف واحد. ويعد CLAUDE.md على مستوى الدليل تطبيقًا أنيقًا لـ «التحميل المحلي».+2. **compaction قمع متدرج**: غير فاقد أولًا ثم فاقد؛ فلا تبدأ بتلخيص النص كله.+3. **استخدام hooks للفحوص الحتمية**: منع إعلان الإنجاز مبكرًا يعتمد على الفرض في runtime، لا على التوسل في الموجّه.+4. **عزل سياق subagents**: قسّم السياق مع تقسيم المهمة، ولا تدع نتائج المهمة الفرعية تلوث الحلقة الرئيسية.+5. **تخزين session إلحاقي وقابل لإعادة التشغيل**: لا يعتمد التسليم على الذاكرة، بل تضمنه طبقة التخزين.++## المصادر المرجعية (النص الأصلي / الشيفرة المصدرية)++يمكن تتبع كل ادعاء إلى النص الأصلي أو الشيفرة المصدرية أدناه، تجنبًا للنقل اعتمادًا على الانطباع:++- **Claude Code — Memory**: سياق جديد لكل session، وأربعة نطاقات لـ CLAUDE.md، والتحميل عند الطلب في الأدلة الفرعية، وauto memory (200 سطر / 25KB)، وإنشاء CLAUDE.md بواسطة `/init`.<br/>https://code.claude.com/docs/en/memory+- **Claude Code — Skills / MCP / Hooks / Sub-agents**: تعريف آليات التوسعة الأربع وأحداثها (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab — Dive into Claude Code**: تحليل على مستوى الشيفرة المصدرية لمسار compaction ذي الطبقات الخمس، وسبعة أوضاع permissions + مصنّف ML، وsubagents عبر sidechain، وتخزين session الإلحاقي history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic — Effective harnesses for long-running agents**: مصدر أفكار «الموثوقية تأتي من harness لا النموذج»، وأن الـ agent يمدح عمله بثقة، واستخدام hooks للتحقق.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack Guide**: قراءة مجتمعية تكميلية عن فصل مسؤوليات طبقات CLAUDE.md / Skills / MCP / Subagents / Hooks.<br/>https://jsmanifest.com/claude-code-full-stack-guide++المحاضرات ذات الصلة: [المحاضرة الثالثة · جعل مستودع الشيفرة مصدر الحقيقة الوحيد](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [المحاضرة التاسعة · منع الـ agent من إعلان الإنجاز مبكرًا](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [المحاضرة العاشرة · التحقق الحقيقي لا يتم إلا بتشغيل المسار الكامل](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/ar/harness-designs/codex/index.md b/docs/ar/harness-designs/codex/index.mdnew file mode 100644index 0000000..2a1c40c--- /dev/null+++ b/docs/ar/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# تحليل تصميم harness في Codex++لعل [Codex](https://openai.com/index/harness-engineering/) من OpenAI أكثر المنتجات الأربعة ارتباطًا بـ «أصول harness»—فمقال «Harness Engineering» الذي منح المجال كله اسمه، هو في حد ذاته خلاصة خبرة فريق OpenAI في بناء منتج باستخدام Codex. لذلك فإن تحليل تصميم harness في Codex هو، إلى حد بعيد، تحليل للممارسات الهندسية الكامنة وراء ذلك المقال.++يمكن تلخيص فلسفة Codex في جملة واحدة: **المستودع هو مصدر الحقيقة (repository as the system of record)، وAGENTS.md مجرد صفحة فهرس، وتكمن قيمة الهندسة في تصميم البيئة، والتعبير عن المقصد، وبناء حلقات التغذية الراجعة.**++## التعريف في جملة واحدة++استخدم فريق OpenAI Codex لتسليم منتج بلغ في النهاية أكثر من مليون سطر من الشيفرة خلال بضعة أسابيع، و**كتب Codex كل سطر منها** (راجع قسم «Designing for growth» في [Harness Engineering](https://openai.com/index/harness-engineering/)). وتجيب تجربتهم عن سؤال: كيف ينبغي تنظيم النظام عندما يتحول دور المهندس من «كتابة الشيفرة» إلى «تصميم harness»؟ أما Codex CLI نفسه فهو ملف تنفيذي أحادي مفتوح المصدر (منفذ بلغة Rust، في [github.com/openai/codex](https://github.com/openai/codex))، لكن إسهامه في harness يتمحور أساسًا حول **الأعراف (convention)** و**هندسة السياق**، لا حول نقاط توسعة براقة.++## النظام الفرعي للتعليمات: AGENTS.md صفحة فهرس لا موسوعة++هذه أكثر أفكار Codex تأثيرًا في نظرية harness:++> لا يسهل فحص ملف تعليمات عملاق واحد آليًا (من حيث التغطية، وحالة التحديث، والملكية، والروابط المتقاطعة)، ولا يمكن تجنب ابتعاده عن الواقع. لذلك لم نعد نتعامل مع AGENTS.md بوصفه موسوعة، بل بوصفه **صفحة فهرس**. وتوجد معرفة قاعدة الشيفرة في وثائق منظمة، بينما يشير AGENTS.md إليها.++(ما سبق نقل مباشر بالمعنى لقسم «AGENTS.md should be a directory page» في النص الأصلي لمقال [Harness Engineering](https://openai.com/index/harness-engineering/).)++تقول المحاضرة الرابعة إن «ملف التعليمات العملاق الواحد يفشل»، ويقدم Codex الحل الصحيح مباشرة: أبقِ AGENTS.md في حدود 100 سطر تقريبًا (يوصي النص الأصلي بنحو 100 سطر، وانقله إلى `docs/` عند الاقتراب من الحد)، وقسّم ما لا يتسع له إلى دليل `docs/` ليقرأه الـ agent عند الطلب. وهذا هو المصدر الموثوق لعبارة «قدّم خريطة، لا دليل تعليمات».++ويسمى المبدأ المصاحب **فرض الثوابت بدل الإدارة الدقيقة للتنفيذ** (في النص الأصلي: "don't micromanage the implementation;focus on invariants"): لا يُكتب في AGENTS.md سوى القيود الصلبة التي لا يجوز انتهاكها وأوامر التحقق، ويُترك للنموذج تقرير كيفية التنفيذ. وهذا يقابل مباشرة «القيود لا الإدارة الدقيقة» في المحاضرة الثانية.++## النظام الفرعي للسياق: Write-Select-Compress-Isolate++يمكن تلخيص هندسة السياق في Codex بأربع استراتيجيات. وقد صاغ المجتمع هذا الإطار بعد أن أصبحت «هندسة السياق» مجالًا مستقلًا، ثم واءمه مع Codex (راجع مصدر الإطار [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):++- **Write (الكتابة إلى الخارج)**: حفظ السياق خارج النافذة—تُكتب الاستنتاجات في الوثائق، والحالة في الملفات، بدل إبقائها في المحادثة. ويقابل ذلك «المستودع هو مصدر الحقيقة».+- **Select (الانتقاء إلى الداخل)**: إدخال الـ token المطلوبة فقط إلى النافذة—يشير AGENTS.md إلى الطريق، وتُقرأ الملفات عند الطلب، بدل حشر المستودع كله فيها.+- **Compress (compaction)**: الاحتفاظ بما يهم فعلًا—يتضمن Codex compaction تلقائيًا وأمر `/compact` يدويًا، ويمكن تخصيص `compact_prompt` (راجع [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (العزل)**: تقسيم السياق إلى حدود مختلفة—استخدام subagent لعزل سياق كل مهمة، بحيث لا يرى subagent الواجهة الأمامية مخطط قاعدة بيانات الواجهة الخلفية مطلقًا.++ولدى Codex تفصيلة دقيقة في تصميم سياق البيئة: يوضح تحليل المجتمع للشيفرة المصدرية في [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) أن `build_environment_update_item` لا يخرج إلا **الحقول المتغيرة** (CWD، وفرع git، ونظام الملفات) عند تغير البيئة، بدل لصق سياق النظام كاملًا في كل جولة. وهذه تفصيلة هندسية تحقق مبدأ «عدم الاحتفاظ بـ token مكررة في السياق».++## الأدوات والحدود: عزل worktree + subagents++لدى Codex آليتان جوهريتان في harness:++**1. عزل البيئة بواسطة git worktree.** يوضح قسم «Environment» في النص الأصلي لمقال [Harness Engineering](https://openai.com/index/harness-engineering/) أن كل مهمة تعمل في git worktree مستقل، مع مكدس محلي لقابلية الرصد (السجلات، والمقاييس، والتتبعات)، كي يُتحقق من كل تغيير في بيئة مستقلة. وهذا هو التطبيق المادي للمحاضرة السابعة «وضع حدود واضحة لكل مهمة agent»—فالحدود لا تعتمد على التوسل في التعليمات، بل تفرضها عزلة البيئة. وهنا يتحول النظام الفرعي للبيئة (environment) إلى عزل صلب.++**2. subagents على مستوى النواة.** أداتا `spawn_agent` و`wait_agent` في Codex أداتان على مستوى النواة: ينشئ النموذج subagent صراحة، ويمنحه سجل session ومجموعة أدوات مستقلين، ثم ينتظر النتيجة. يرث subagent تعليمات AGENTS.md من الأب، لكنه يعمل في **سياقه الخاص**. ويوضع الإعداد في `.codex/agents/*.toml`، مع إمكان تحديد نماذج وتعليمات مختلفة (راجع قسم Sub-agents في [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)). وهذا تطبيق مباشر لـ «عزل السياق»—ولروح «التسليم» في المحاضرة الثانية عشرة أيضًا: فكل subagent وحدة عمل ذات حدود واضحة.++## النظام الفرعي للتغذية الراجعة: كتابة أوامر التحقق في المواصفات++أهم ما تؤكد عليه تجربة OpenAI هو إدراج أوامر التحقق صراحة في AGENTS.md، بحيث تصبح «كيفية التأكد من صحة العمل» جزءًا من المستودع. وفي سير العمل الهندسي لـ Codex، يولّد Codex الاختبارات، وCI، والوثائق، وإعدادات قابلية الرصد—وكلها «مسارات تحقق قابلة للتنفيذ». ولا يكون حل مشكلة نموذج قوي القدرات لكنه غير موثوق هو الدعاء بأن ينضبط من تلقاء نفسه، بل جعل **مسار التحقق مكوّنًا افتراضيًا في harness**.++أما approval policies وplan mode فهما وجه آخر للتغذية الراجعة: إذ تُعرض الخطة وتُطلب الموافقة قبل تنفيذ العمليات عالية المخاطر، فتتحول «حدود المهمة» و«سلطة القرار البشري» إلى ضوابط runtime.++## المواءمة مع إطار الدورة++| النظام الفرعي | تطبيق Codex | التقييم |+| --- | --- | --- |+| التعليمات | صفحة فهرس AGENTS.md + التقسيم إلى docs/ + فرض الثوابت | تطبيق نموذجي يعرّف «قدّم خريطة لا دليل تعليمات» |+| الأدوات | عزل worktree + الوكلاء الفرعيون spawn_agent | حدود قوية تفرضها عزلة البيئة |+| البيئة | worktree مستقل + مكدس قابلية الرصد | عزل worktree هو علامته المميزة |+| الحالة | استراتيجية Write (كتابة الحالة في الملفات/الوثائق) | تعتمد على العرف لا على ذاكرة مضمّنة |+| التغذية الراجعة | أوامر التحقق في المواصفات + سياسات الموافقة + plan mode | جعل مسار التغذية الراجعة افتراضيًا، وهو جدير بالاقتباس |++المقارنة بين Codex وClaude Code ممتعة: Claude Code يتبع «الإضافة»—إذ يضمّن الذاكرة وpermissions وsubagents كلها في النواة؛ بينما يتبع Codex «الطرح»—فيحافظ على نواة منضبطة وينقل مزيدًا من المسؤولية إلى أعراف المستودع وهندسة السياق. ولهذا كثيرًا ما يقول المجتمع إن «فلسفة harness في Codex أثمن من شيفرته».++## تصميمات جديرة بالاقتباس++1. **كتابة AGENTS.md كصفحة فهرس**: أبقه في حدود 100 سطر تقريبًا، وأشر إلى التفاصيل في docs/، واجعله قابلًا للفحص الآلي.+2. **كتابة الثوابت فقط، من دون إدارة التنفيذ تفصيليًا**: قيود صلبة + أوامر تحقق، وترك الباقي للنموذج.+3. **استخدام worktree لعزل البيئة**: فرض حدود المهمة عبر البيئة، لا بالتوسل في التعليمات.+4. **تمرير التغيرات فقط في سياق البيئة**: إخراج الحقول المتغيرة في كل جولة، من دون تكرار لصق سياق النظام كاملًا.+5. **استخدام subagents لعزل السياق**: قسّم السياق عند تقسيم المهمة، ولا تدع المهام الفرعية تلوث الحلقة الرئيسية.++## المصادر المرجعية (النص الأصلي / الشيفرة المصدرية)++يمكن تتبع كل ادعاء إلى النص الأصلي أو الشيفرة المصدرية أدناه، تجنبًا للنقل اعتمادًا على الانطباع:++- **مقال OpenAI «Harness Engineering»**: صفحة فهرس AGENTS.md والتوصية بنحو 100 سطر، وexecutive invariants / don't micromanage، وعزل worktree + مكدس قابلية الرصد، وإدراج أوامر التحقق في المواصفات، وحالة المنتج ذي أكثر من مليون سطر، وسياسات الموافقة، وplan mode. وهو المصدر الرئيسي لجميع الادعاءات الجوهرية في هذه المقالة.<br/>https://openai.com/index/harness-engineering/+- **مواصفة OpenAI الرسمية «AGENTS.md»** (معيار AGENTS.md بوصفه عرفًا عابرًا للأدوات):<br/>https://openai.com/index/agents-md/+- **مستودع Codex CLI المفتوح المصدر** (ملف تنفيذي أحادي بلغة Rust):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (من المجتمع): إطار Write-Select-Compress-Isolate، و`/compact` و`compact_prompt`، وsubagents عبر `spawn_agent` / `wait_agent`، وإعداد `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (تحليل مجتمعي للشيفرة المصدرية): تفاصيل التنفيذ مثل سياق البيئة التزايدي في `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++المحاضرات ذات الصلة: [المحاضرة الثالثة · جعل مستودع الشيفرة مصدر الحقيقة الوحيد](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [المحاضرة الرابعة · تقسيم التعليمات بين ملفات مختلفة](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [المحاضرة السابعة · وضع حدود واضحة لكل مهمة agent](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/ar/harness-designs/deepseek/index.md b/docs/ar/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..b6db77f--- /dev/null+++ b/docs/ar/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# تحليل تصميم DeepSeek Harness++أُطلق [DeepSeek Harness](https://deepseek.com/harness) (اسم الأمر `dsh`، والمستودع `deepseek-ai/deepseek-harness`) في أغسطس 2026 بصفته إصدار Developer Preview، وقد قدّم له التعريف الرسمي المباشر الآتي: **Agent = Model + Environment + Tools + State**—أي النموذج، والبيئة، والأدوات، والحالة.++إذا كانت تحليلات المنتجات الثلاثة الأولى تسأل «كيف ينبغي تصميم harness؟»، فإن DeepSeek Harness يطرح سؤالًا أكثر جرأة: **هل يمكن أن ينفصل harness عن نموذج بعينه ويصبح بيئة تشغيل مستقلة؟** إجابته نعم، وقد دفع الفكرة إلى أقصاها—إذ تقول [وثيقة البنية](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) حرفيًا: *كل جزء من المنتج هو إضافة برمجية، بما في ذلك موائم النموذج، وسجل الأدوات، وسجل الجلسة، وحتى حلقة الـ agent نفسها*.++نحلله في هذه المقالة مع التركيز على ثلاثة أمور: النواة القائمة على الإضافات، وفاصل القدرات (capability seam)، ومسار الأحداث، فضلًا عن أقوى قيد هندسي فيه: «كل ما يراه النموذج يجب تسجيله».++## التعريف في جملة واحدة++يتكون الـ coding agent التقليدي من «LLM + حلقة agent ثابتة + مجموعة أدوات ثابتة». أما DeepSeek Harness فيتكون من «نموذج + نواة إضافات (Cordis)»؛ ولا تتولى النواة سوى تحميل الإضافات وإزالتها وإدارة تبعياتها وآلية أحداثها، و**لا تمتلك أي قدرة خاصة بالـ agent**—وتقول [وثيقة البنية](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) حرفيًا: «لا توجد نواة ذات امتيازات تحتاج إلى ترقيع»، و«يمكنك توسيع dsh بتركيب إضافة إلى جوار الإضافات الأخرى» بدل تعديل النواة. وهذا يعني أن حلقة الـ agent نفسها ليست مقدسة ولا عصية على التغيير—يمكنك استخدام نموذج DeepSeek، وربط الوكلاء الفرعيين في Claude Code، وإضافة صندوق رمل بعيد، وكتابة ذاكرة مخصصة، واستبدال الحلقة وواجهة المستخدم، ثم تجميع ذلك كله في agent جديد تمامًا.++هذا هو التطبيق الأكثر شمولًا لعبارة الدورة «كل ما يقع خارج أوزان النموذج هو harness»: ما دام harness مستقلًا، فلنجعله نظام تشغيل مستقلًا.++## جوهر البنية 1: فاصل القدرات (Capability Seam)++يستخدم DeepSeek Harness مفهوم Service للتعبير عن «القدرة»، ويقسّم كل قدرة تقريبًا إلى ثلاث طبقات:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++لنأخذ نظام الملفات مثالًا: يندرج تحت `FS Service` عدد من Provider مثل Local FS وE2B FS وRemote FS، وتُعرَض جميعها للأعلى بصورة موحّدة على هيئة file tools. وتتبع Shell وSubprocess وSandbox وWeb وLLM وSubAgent البنية نفسها. وهذه البنية الثلاثية ليست خلاصة من عندنا—بل تذكر [وثيقة البنية · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) حرفيًا: *فاصل القدرة هو قدرة قابلة للاستبدال ذات ثلاثة أدوار: Service Definition يعلن الواجهة، وService Provider ينفذها، وConsumer يستخدمها، وغالبًا ما يكون الأخير أداة ظاهرة للنموذج*.++يحل ذلك مشكلة مزمنة في هندسة harness: **هل ينبغي أن يعتمد الـ agent على «أداة محددة»، أم على «واجهة قدرة»؟** يختار DeepSeek Harness الثانية. وبمصطلحات الدورة، يعني هذا توحيد «النظام الفرعي للأدوات» في واجهة: عند استبدال Provider لا يتغير شكل الأدوات المعروضة للنموذج، مع أن البيئة تتغير بالكامل.++## جوهر البنية 2: مسار الأحداث (Event Pipeline)++لا يعمل DeepSeek Harness داخليًا وفق دورة بسيطة من «LLM ← أداة ← LLM»، بل وفق مسار أحداث تكون كل مرحلة فيه نقطة حدث يمكن لإضافة برمجية الاستماع إليها:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(المسار أعلاه إعادة صياغة لقسم [وثيقة البنية · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): تمثل `turn/*` و`step/*` و`user/message` و`assistant/*` و`tool/*` أحداث جلسة دائمة، بينما تمثل `agent/pre-step` و`agent/request` و`llm/stream` و`tools/*` نقاط توسعة يمكن للإضافات الاستماع إليها.)++أكبر مزايا هذا التصميم هي أن **عددًا كبيرًا من الوظائف لا يتطلب تعديل حلقة الـ agent أصلًا**. هل تريد فحصًا أمنيًا قبل تنفيذ الأداة؟ استمع إلى `tools/pre-execute`. هل تريد إضافة ذاكرة؟ احقنها عند `agent/pre-step`. هل تريد تسجيل السلوك؟ اشترك في أحداث الجلسة. هل تريد تعديل طلب النموذج؟ اربطه بـ `agent/request`. هل تريد تقرير مواصلة الاستدلال؟ استمع إلى `agent/turn-stopping`.++مقارنة بالمحاضرة الحادية عشرة، «جعل عملية تشغيل الـ agent قابلة للرصد»، يذهب DeepSeek Harness أبعد: فهو لا «يضيف السجلات» فحسب، بل يحوّل **كل خطوة في الحلقة إلى نقطة حدث**، فتُعلّق قابلية الرصد والأذونات والذاكرة والسياسات كلها على الحلقة بصفتها مستمِعات، بدل أن تُرسّخ داخلها.++## جوهر البنية 3: Session Event Log وقاعدة «كل ما يراه النموذج يجب تسجيله»++يتضمن DeepSeek Harness **Session Event Log للإلحاق فقط**، ويفرض قيدًا هندسيًا شديد القوة. تقول [وثيقة البنية · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) حرفيًا:++> **كل ما يراه النموذج يجب تسجيله.** يجب أن يكون كل ما يصل إلى طلب النموذج قابلًا لإعادة البناء من السجل، ويؤكد ثابت وقت التشغيل ذلك.++(أي إن كل ما يستطيع النموذج رؤيته يجب أن يُسجل. وكل ما يدخل طلب النموذج يجب أن يكون قابلًا لإعادة البناء من السجل، مع وجود ثابت وقت تشغيل يفرض ذلك.)++بعبارة أخرى، ليست قابلية الرصد سجلًا يضاف بعد وقوع الحدث، بل قيدًا أوليًا في harness: كل ما يدخل سياق النموذج ينبغي افتراضيًا أن يترك سجلًا. وهذا ينسجم مباشرة مع عبارة المحاضرة الختامية «قابلية الرصد تنتمي إلى داخل harness»، ويحوّل تصميم التخزين append-only إلى مبدأ—فالسجل لا يقبل إلا الإلحاق ولا يُعاد فوقه، ويمكن إعادة تشغيل حالة الجلسة.++## المواءمة مع إطار الدورة++| النظام الفرعي | تطبيق DeepSeek Harness | التقييم |+| --- | --- | --- |+| التعليمات | قائمة على الإضافات؛ تُحقن القواعد/المهارات في صورة إضافات | حرية فائقة، لكن من دون عرف مضمّن شبيه بـ CLAUDE.md |+| الأدوات | فاصل قدرات Service Definition → Provider → Consumer | أقصى درجات توحيد النظام الفرعي للأدوات |+| البيئة | يمكن استبدال Provider لكل من صندوق الرمل/FS/Shell (بما في ذلك E2B البعيد) | بيئة قابلة للتوصيل بالكامل |+| الحالة | Session Event Log للإلحاق فقط + كل ما يراه النموذج يجب تسجيله | قابلية الرصد قيد أولي |+| التغذية الراجعة | permission / guard / policy / hook على tools/pre-execute | آليات التغذية الراجعة قائمة على الأحداث |++الفرق الجوهري بين DeepSeek Harness والمنتجات الثلاثة الأخرى هو أن Pi وClaude Code وCodex تحسّن harness داخل «agent محدد»، بينما يعرّف DeepSeek Harness harness بوصفه **نظام تشغيل مستقلًا عن النموذج**، ولا يكون الـ agent نفسه سوى تطبيق قابل للاستبدال على هذا النظام. والثمن واضح أيضًا—فالحرية الكبيرة تعني تكلفة إعداد مرتفعة، وهذا هو الوجه الآخر الملازم لفكرة «harness بوصفه نظام تشغيل» (كما أن مرحلة معاينة المطورين موجهة إلى «التجربة المبكرة، مع استمرار تطور الآليات»).++## تصميمات جديرة بالاقتباس++1. **تحويل كل خطوة في الحلقة إلى نقطة حدث**: تُعلّق الأذونات والذاكرة والسياسات والسجلات على الحلقة بوصفها مستمِعات، بدل أن تُرسّخ داخلها.+2. **توحيد فاصل القدرات**: الاعتماد على «واجهة قدرة» بدل «أداة محددة»، بحيث يمكن استبدال البيئة ككتلة كاملة من دون التأثير في واجهة الأدوات التي يراها النموذج.+3. **كل ما يراه النموذج يجب تسجيله**: تسجيل كل ما يستطيع النموذج رؤيته، وتحويل قابلية الرصد من «ميزة إضافية» إلى «قيد أولي».+4. **سجل جلسة append-only**: حالة قابلة لإعادة التشغيل، وتسليم موثوق؛ وهذا ضمان هندسي لقاعدة «ترك حالة نظيفة في نهاية كل جلسة».++## المصادر المرجعية (النص الأصلي / الشيفرة المصدرية)++يمكن تتبع كل ادعاء إلى النص الأصلي أو الشيفرة المصدرية أدناه، تجنبًا للنقل اعتمادًا على الانطباع:++- **موقع DeepSeek Harness الرسمي**: تعريف المنتج «Agent = Model + Environment + Tools + State»، وتصنيفه Developer Preview، والأمر `dsh`.<br/>https://deepseek.com/harness+- **مستودع deepseek-ai/deepseek-harness** (الأمر `dsh`، وترخيص MIT):<br/>https://github.com/deepseek-ai/deepseek-harness+- **وثيقة البنية architecture.md**: المصدر الأهم لهذه المقالة—«كل جزء من المنتج إضافة برمجية»، و«لا توجد نواة ذات امتيازات تحتاج إلى ترقيع»، ومسار أحداث Turn flow، والأدوار الثلاثة لفواصل القدرات، وقاعدة «كل ما يراه النموذج يجب تسجيله» وثابت وقت التشغيل، وSession Event Log للإلحاق فقط، وفواصل قدرات مثل fs/tools/telemetry، وأنظمة `ctx.*` الفرعية.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **الوثائق الفرعية المساندة لوثيقة البنية**: مقدمة إلى نواة Cordis (تسهم الإضافات بخدمات، وأحداث محددة الأنواع، وتأثيرات قابلة للعكس)، وتفاصيل فواصل القدرات، والنظام الفرعي للجلسة.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++المحاضرات ذات الصلة: [المحاضرة الحادية عشرة · جعل عملية تشغيل الـ agent قابلة للرصد](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [المحاضرة الثانية عشرة · إجراء تسليم جيد قبل نهاية كل جلسة](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [المحاضرة الثانية · ما هو Harness بالضبط؟](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/ar/harness-designs/index.md b/docs/ar/harness-designs/index.mdnew file mode 100644index 0000000..93bc308--- /dev/null+++ b/docs/ar/harness-designs/index.md@@ -0,0 +1,29 @@+# تحليل تصميمات Harness المتقدمة++يقارن هذا القسم نظريات harness الواردة في محاضرات الدورة، منتجًا تلو الآخر، بأحدث المنتجات الواقعية المتقدمة. وفي كل منتج نهتم بسؤال واحد فقط: **كيف صُمِّم harness الخاص به؟** أي طبقة البنية التحتية الهندسية المحيطة بالنموذج: الأنظمة الفرعية الخمسة، وهي التعليمات والأدوات والبيئة والحالة والتغذية الراجعة، إلى جانب الآليات الجوهرية مثل استمرارية السياق، والتهيئة، والتحقق، وقابلية الرصد، والتسليم، والحلقات التكرارية.++نتعمّد ألّا نناقش قوة قدرات النموذج الاستدلالية، أو ارتفاع نتيجته في اختبار معيّن، كما لا نقدّم عرضًا عامًا لما يستطيع هذا الـ agent فعله. فهذه مسائل تخص طبقتي النموذج والمنتج. ما نحلله هنا هو harness وحده—أي كل ما يقع خارج أوزان النموذج.++## لماذا يستحق التحليل++ورد في المحاضرة الأولى أن قوة النموذج لا تعني موثوقية التنفيذ. فقد يختلف أداء النموذج نفسه بمقدار رتبة كاملة عند وضعه في harness مختلف. لكن المحاضرات تشرح «ما ينبغي فعله»، بينما تجيب هذه المنتجات عن سؤال «ما الذي تفعله الفرق الرائدة فعليًا».++كل منتج هو مجموعة مستقلة من قرارات التصميم. وعند مقارنتها معًا، سترى كيف تطبّق فرق مختلفة الآليات الجوهرية نفسها بطرائق متباينة تمامًا:++- يحوّل **Pi** harness إلى نواة شديدة البساطة مع امتدادات قابلة للبرمجة، ويعتمد على «حد أدنى من موجّه النظام + التحميل عند الطلب» لهندسة السياق.+- يحوّل **Claude Code** harness إلى runtime متكامل: ذاكرة طبقية، وcompaction بخمس طبقات، وpermissions، وhooks، وsubagents.+- يدفع **Codex** فلسفة harness إلى أقصاها: المستودع هو مصدر الحقيقة، وAGENTS.md ليس سوى صفحة فهرس، مع استخدام worktree لعزل البيئة.+- يعرّف **DeepSeek Harness** harness نفسه بوصفه runtime مستقلًا عن النموذج: Everything is a Plugin.++## قائمة المقالات++- [تحليل تصميم harness في Pi](./pi/): نواة شديدة البساطة + امتدادات قابلة للبرمجة، تدمج هندسة السياق خارج موجّه النظام.+- [تحليل تصميم harness في Claude Code](./claude-code/): ذاكرة طبقية، وcompaction بخمس طبقات، وpermissions وhooks، ضمن runtime متكامل للـ agent.+- [تحليل تصميم harness في Codex](./codex/): المستودع هو مصدر الحقيقة، وAGENTS.md صفحة فهرس، مع عزل البيئة وحلقات التغذية الراجعة.+- [تحليل تصميم DeepSeek Harness](./deepseek/): كل شيء إضافة برمجية، حتى حلقة الـ agent نفسها قابلة للاستبدال.++## كيفية القراءة++نوصي بقراءة المحاضرات الأولى من المادة، ولا سيما [المحاضرة الثانية: ما هو Harness بالضبط؟](../lectures/lecture-02-what-a-harness-actually-is/)، لبناء إطار الأنظمة الفرعية الخمسة، ثم العودة إلى هنا لمعرفة كيف تطبّق المنتجات الواقعية هذه الآليات.++تتضمن نهاية كل مقالة قسمين هما «المواءمة مع إطار الدورة» و«تصميمات جديرة بالاقتباس»، لمساعدتك على إعادة ترجمة تصميم المنتج سريعًا إلى مفاهيم الدورة وتطبيقها مباشرة في مشروعك.diff --git a/docs/ar/harness-designs/pi/index.md b/docs/ar/harness-designs/pi/index.mdnew file mode 100644index 0000000..864a551--- /dev/null+++ b/docs/ar/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# تحليل تصميم harness في Pi++يصف [Pi](https://pi.dev/) (حزمة npm `@earendil-works/pi-coding-agent`) نفسه بأنه «minimal agent harness»—أي agent harness بالغ البساطة. وهذه عبارة تستحق التفكيك: فهو لا يصف نفسه بأنه «أقوى coding agent»، ولا «أفضل أداة برمجة بالذكاء الاصطناعي»، بل يرسخ موقعه في كلمة **harness** تحديدًا.++نحلل في هذه المقالة Pi باستخدام إطار الأنظمة الفرعية الخمسة في الدورة (التعليمات، والأدوات، والبيئة، والحالة، والتغذية الراجعة)، لنرى كيف تختلف فلسفة تصميمه جذريًا عن Claude Code وCodex. وإليك الجواب مقدمًا: **فلسفة Pi هي «تقليص النواة إلى الحد الأدنى + جعل التوسعة قابلة للبرمجة»؛ فهي تدمج هندسة السياق خارج موجّه النظام، وتترك للمستخدم (بل ولـ Pi نفسه) تعديل harness، بدل أن يقرر Pi harness بالنيابة عنك.**++## التعريف في جملة واحدة++Pi نواة شديدة البساطة: يتعمد تعريفه الرسمي تصغير النواة وإعادة سلطة القرار إليك—وتقول [الصفحة الرئيسية لـ pi.dev](https://pi.dev/) حرفيًا: «اطلب من Pi بناء ما تريده، أو ثبّت حزمة تنفذه بطريقتك». ويقسّم harness إلى أربع طبقات قابلة للتخصيص:++- **Extensions**: hooks بلغة TypeScript مرتبطة بأحداث دورة حياة Pi، وهي واجهة برمجية على مستوى runtime.+- **Skills**: حزم قدرات تُحمّل عند الطلب، وتتضمن تعليمات وأدوات، وفق progressive disclosure.+- **قوالب الموجّهات (Prompt templates)**: موجّهات Markdown قابلة لإعادة الاستخدام، تتوسع عند إدخال `/name`.+- **السِّمات (Themes)**: مظهر TUI.++إن فكرة التقسيم الطبقي هذه في ذاتها تصميم لـ harness: **يُترك تحديد «ما الذي يراه النموذج، ومتى يراه» بالكامل للقواعد والامتدادات، بدل ترسيخه داخل النواة.**++## الحلقة الجوهرية++Pi، مثل سائر coding agent، هو في جوهره حلقة while من «استدلال ← تنفيذ أداة ← ملاحظة ← استدلال مجدد». وما يستحق الاهتمام ليس الحلقة نفسها، بل كيفية تعامل Pi مع غلافها الخارجي: إذ وسّع إدارة السياق من «compaction» داخل الحلقة إلى «التحكم» خارجها.++يعرّض runtime الخاص بـ Pi واجهة برمجية—فإلى جانب TUI التفاعلية، تدعم فقرة [Programmatic Usage في README للشيفرة المصدرية](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) أوضاع الطباعة/JSON القابلة للبرمجة، وبروتوكول RPC، والتضمين عبر SDK. ويعني ذلك أن الإنسان يستطيع قيادة harness نفسه خطوة بخطوة، كما يستطيع CI/CD أو برنامج آخر قيادته آليًا. وهذا هو الشرط السابق لعبارة «من القيادة اليدوية إلى الحلقة التلقائية» في المحاضرة الثالثة عشرة: إذا لم يكن بالإمكان تشغيل harness إلا بالتفاعل البشري، فلن يدخل حلقة تلقائية أبدًا.++## النظام الفرعي للتعليمات: AGENTS.md وSYSTEM.md++يتعامل Pi مع «التعليمات» بانضباط، لكن بتدرج واضح:++- **AGENTS.md**: يحدد قسم [Project Context Files في README للشيفرة المصدرية](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) ترتيب التحميل بوضوح—الملف العام `~/.pi/agent/AGENTS.md` ← اجتياز الأدلة الأب صعودًا، مستوى بعد مستوى ← دليل العمل الحالي `./AGENTS.md` (مع توافق أيضًا مع CLAUDE.md). وهذا تطبيق لمبدأ «المستودع هو مصدر الحقيقة»—فالتعليمات ملفات، لا تذكيرات في مربع محادثة.+- **SYSTEM.md**: تقول [وثائق pi.dev الرسمية](https://pi.dev/docs/usage/project-context) إنه يمكن، على مستوى المشروع، استبدال (replace) موجّه النظام الافتراضي أو الإضافة إليه (append). وهذه هي القناة الرسمية الوحيدة التي يتيحها Pi لتعديل «موجّه النظام»، كما أنها طبقة «الوصف الذاتي للبيئة» فيه.++تؤكد Pi رسميًا أن موجّه النظام نفسه **شديد البساطة**. ويكمن وراء ذلك اختيار واضح: لا تحشو النواة بقواعد مطولة من قبيل «إذا... فعندئذ...»، بل تترك نقاط توسعة لا تظهر فيها القواعد، على هيئة مهارات وامتدادات، إلا عند الحاجة. وهذا ينسجم مباشرة مع المحاضرة الرابعة، «لماذا يفشل ملف التعليمات العملاق الواحد؟»—إذ يتجنب Pi المشكلة بطبيعته عبر «نواة شديدة البساطة + تقسيم الملفات + التحميل عند الطلب».++## الحالة والسياق: أكثر ما يفصله Pi دقة++تستحق هندسة السياق في Pi تحليلًا خاصًا، لأنها تحول مفاهيم الدورة مثل «استمرارية السياق» و«منع فساد السياق» إلى آليات ملموسة:++**1. جعل Compaction قابلًا للبرمجة.** عندما يقترب السياق من حده الأقصى، تُلخص الرسائل القديمة تلقائيًا—وتوضح [وثائق pi.dev الرسمية](https://pi.dev/docs/usage/sessions) أن استراتيجية compaction نفسها **قابلة للتخصيص**: يمكنك استخدام extension لتنفيذ compaction بحسب الموضوع، أو تلخيص واعٍ بالشيفرة، أو حتى استخدام نموذج مختلف للتلخيص. ويعرض README للشيفرة المصدرية تفاصيل الآلية الافتراضية أيضًا: ينطلق compaction التلقائي في حالتين (التعافي من تجاوز السياق / تجاوز عتبة الاحتفاظ)، وتبقي نقطة القطع أحدث 20 ألف token تقريبًا، بينما تُلخّص الرسائل الأسبق في «context handoff» وتخضع لـ compaction تسلسلي على مراحل. أي إن Pi لا يعامل «كيفية compaction» كثابت غير قابل للتغيير، بل كجزء من harness.++**2. السياق الديناميكي (Dynamic context).** تقول [وثائق pi.dev الرسمية](https://pi.dev/docs/usage/extensions) إن extensions تستطيع حقن الرسائل قبل كل جولة استدلال، وترشيح سجل الرسائل، وتنفيذ RAG، وبناء ذاكرة طويلة الأجل. وهذا يتجاوز «compaction بعد امتلاء السياق»: فهو يتيح لك أن تقرر ما يدخل النافذة وما لا يدخلها قبل وصول السياق إليها. ويقابل ذلك في الدورة «جعل عملية تشغيل الـ agent قابلة للرصد والتصحيح» و«الحفاظ على استمرارية السياق»؛ وقد نقل Pi كليهما إلى واجهة extensions.++**3. شجرة session (Session tree).** تذكر [الصفحة الرئيسية لـ pi.dev](https://pi.dev/) صراحة أن "sessions are stored as trees"، وأن `/tree` يستطيع العودة إلى أي عقدة تاريخية ومواصلة العمل منها، مع حفظ جميع الفروع في ملف واحد. وهذا يحل مشكلة «انقطاع السياق بين sessions» التي تكرر الدورة التشديد عليها—لا بربط صلب عبر ملخص، بل بإعادة تشغيل السجل المنظم. ويمكن تصدير الفروع إلى HTML أو رفعها كـ gist للمشاركة، فتُحل قابلية الرصد في الوقت نفسه.++## النظام الفرعي للأدوات: Skills وExtensions++تتكون «أدوات» Pi من طبقتين:++- **Skills**: يعرّفها قسم Skills في [README للشيفرة المصدرية](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) بوضوح بأنها "self-contained capability packages that the agent loads on-demand"؛ أي حزم قدرات تُحمّل عند الطلب، وتضم تعليمات وأدوات، وتتبع معيار Agent Skills. ولا تدخل تفاصيل skill السياق إلا عند تشغيلها بفضل progressive disclosure، **فلا تفجّر prompt cache**. وهذا تصميم لـ harness من زاوية التكلفة: كل token إضافية في السياق تُدفع تكلفتها في كل استدلال؛ لذا فإن تحميل Skills عند الطلب تعبير آخر عن «قدّم خريطة، لا دليل تعليمات».+- **Extensions**: hooks بلغة TypeScript متصلة بأحداث دورة الحياة المضمّنة—ويورد قسم Hooks في [README للشيفرة المصدرية](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) أمثلة رسمية للاستخدام: اعتراض الأوامر الخطرة (بوابة permissions)، وإنشاء checkpoint لحالة الشيفرة عند تبديل المهمة، وحماية المسارات (مثل منع الكتابة في `.env`)، وتعديل ناتج الأداة قبل تسليمه إلى النموذج، وحقن رسائل من الخارج (مراقبة ملف/Webhook/CI) لإيقاظ الـ agent. وتُصدّر واجهات API لهذه hooks أيضًا في `@mariozechner/pi-coding-agent/hooks`. أما harness المجتمعي [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) فيغلف واجهة hooks كذلك في extensions جاهزة مثل skill-router وsession-summary وextract-patterns وtelemetry.++Extensions هي أهم قرارات تصميم Pi: **فهو لا «يمنح المستخدم بضعة مفاتيح»، بل يعرض كامل واجهة الأحداث الداخلية لـ runtime.** أتريد إضافة ذاكرة؟ احقنها عند `agent/pre-step`. أتريد تسجيل السلوك؟ اشترك في أحداث session. أتريد تعديل طلب النموذج؟ اربطه بـ `agent/request`. ويمكنك أن تجعل Pi يعدّل harness الخاص به بنفسه—وهذا أقرب إلى تعريف «harness قابل للبرمجة» من أي «خيار إعداد».++## التغذية الراجعة والتحقق: تحويل «التعلم» نفسه إلى harness++لا يتضمن Pi نفسه بوابة اختبار إلزامية (على المستخدم كتابة أوامر التحقق في AGENTS.md)، لكن harness المجتمعي [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) يستخدم extensions لتنظيم «حلقة التغذية الراجعة»، كما يقدّم قسم Hooks في README الرسمي أساسًا لآليات مشابهة:++- **session-summary** (امتداد pi-agent-harness): يحتفظ بإدخالات متجددة في `PROGRESS.md`—وهذا هو النظام الفرعي للحالة في الدورة، أي تتبع تقدم المهام الطويلة.+- **extract-patterns** (extension في pi-agent-harness): يجمع الدروس المستفادة المرشحة من session، ويرسخها في `LESSONS.md`—فيحوّل «إجراء تسليم جيد قبل نهاية كل session» من اتفاق إلى آلية.+- **telemetry** (امتداد pi-agent-harness): يسجل استخدام token والتكلفة وغيرها—أي قابلية الرصد.++ويبرهن المستودع المجتمعي نفسه على هذا النمط: `VISION.md` (الهدف)، و`PROGRESS.md` (التقدم)، و`LESSONS.md` (الخبرات)، و`STANDARDS.md` (المعايير)، وكلها ملفات Markdown تُحفظ عبر sessions. وهذا النمط مطابق تمامًا لتوصية الدورة «المستودع هو مصدر الحقيقة + ملف تقدم + آلية تسليم»، لكن آلية Extensions في Pi حولته إلى طبقة جاهزة للاستخدام.++## المواءمة مع إطار الدورة++تقييم Pi وفق الأنظمة الفرعية الخمسة للدورة (تقييم شخصي للمقارنة):++| النظام الفرعي | تطبيق Pi | التقييم |+| --- | --- | --- |+| التعليمات | تحميل AGENTS.md طبقيًا + SYSTEM.md | تدرج واضح، لكن على المستخدم كتابة القواعد نفسها |+| الأدوات | تحميل المهارات عند الطلب + خطافات امتداد تغطي دورة الحياة كلها | قوي جدًا، فقد حوّل نظام الأدوات إلى سطح قابل للبرمجة |+| البيئة | وصف ذاتي للبيئة عبر SYSTEM.md؛ ويصرّح المستخدم ببيئة التشغيل في AGENTS.md | الآلية مفتوحة، لكن قابلية إعادة الإنتاج تعتمد على وصف المستخدم |+| الحالة | شجرة جلسة + ضغط قابل للتخصيص + PROGRESS.md | قوي جدًا، فالعمل عبر الجلسات وقابلية الاستعادة في صميمه |+| التغذية الراجعة | يعرّف المستخدم أوامر التحقق؛ وتحوّلها session-summary / extract-patterns إلى آليات | الآلية متوفرة، والمحتوى على المستخدم |++يشكل اختيار Pi تباينًا واضحًا مع Claude Code / Codex: يضمّن Claude Code «الذاكرة وpermissions وsubagents» كلها في النواة لتعمل فورًا؛ ويجعل Codex «مواصفات المستودع وعزل البيئة» افتراضيين؛ بينما يختار Pi **ألّا يقرر شيئًا نيابة عنك**—بل يحوّل سلطة القرار إلى نقاط توسعة. والثمن هو أن تكتب extensions بنفسك أو تثبّت حزمًا كتبها آخرون.++## تصميمات جديرة بالاقتباس++1. **جعل استراتيجية compaction قابلة للتوصيل**. لا ينبغي أن تكون «كيفية compaction للسياق» في harness معلمة ثابتة، بل واجهة استراتيجية قابلة للاستبدال.+2. **استخدام شجرة session بدل الملخص الصلب**. لا يلزم أن تعتمد الاستعادة عبر sessions على «ملخص الجولة السابقة»؛ فإعادة التشغيل المنظمة للسجل نظام حالة أكثر موثوقية غالبًا.+3. **مراعاة prompt cache**. إن تحميل Skills عند الطلب وعدم حشر جميع القواعد في system prompt مرة واحدة هندسة للسياق وللتكلفة معًا.+4. **تمكين الـ agent من تعديل harness الخاص به**. إذا كان سطح توسعة harness مفتوحًا بما يكفي، فيمكن للـ agent نفسه تنفيذ «تحسين سلوك الـ agent» بصورة شبه تلقائية.++## المصادر المرجعية (النص الأصلي / الشيفرة المصدرية)++يمكن تتبع كل ادعاء إلى النص الأصلي أو الشيفرة المصدرية أدناه، تجنبًا للنقل اعتمادًا على الانطباع:++- **pi.dev**: عبارة التعريف الأصلية "Ask Pi to build what you want, or install a package that does it your way"، والطبقات الأربع القابلة للتخصيص، وشجرة session ("sessions are stored as trees"، و`/tree`، والحفظ في ملف واحد، والتصدير إلى HTML / المشاركة عبر gist).<br/>https://pi.dev/+- **pi.dev — Sessions**: compaction القابل للتوصيل (بحسب الموضوع / واعٍ بالشيفرة / استبدال نموذج التلخيص)، ووصف آلية compaction التلقائي وحقن السياق الديناميكي.<br/>https://pi.dev/docs/usage/sessions+- **وثائق pi.dev الرسمية · Extensions**: تستطيع الامتدادات حقن الرسائل قبل كل جولة استدلال، وترشيح السجل، وتنفيذ RAG، وبناء ذاكرة طويلة الأجل.<br/>https://pi.dev/docs/usage/extensions+- **وثائق pi.dev الرسمية · Project Context**: دلالات replace / append في SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent README** (badlogic/pi-mono): ترتيب تحميل AGENTS.md في ثلاث درجات (العام ← الأدلة الأب ← الدليل الحالي)، وشروط تشغيل `/compact` وcompaction التلقائي ونقطة القطع عند 20 ألف token، وتحميل Skills عند الطلب ومعيار Agent Skills، ودورة حياة Hooks وأمثلة الاستخدام الرسمية، وProgrammatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **مستودع pi-agent-harness المجتمعي**: امتدادات skill-router / session-summary / extract-patterns / telemetry، ومنظومة ملفات VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++المحاضرات ذات الصلة: [المحاضرة الثانية · ما هو Harness بالضبط؟](../lectures/lecture-02-what-a-harness-actually-is/) | [المحاضرة الخامسة · الحفاظ على استمرارية سياق المهام عبر sessions](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [المحاضرة الثالثة عشرة · من القيادة اليدوية إلى الحلقة التلقائية](../lectures/lecture-13-loop-engineering/)diff --git a/docs/ar/index.md b/docs/ar/index.mdindex fca4de6..bbb71ae 100644--- a/docs/ar/index.md+++ b/docs/ar/index.md@@ -25,6 +25,10 @@ Learn Harness Engineering هو مساق مخصص لهندسة وكلاء الب<h3>مكتبة الموارد</h3><p>قوالب جاهزة للنسخ مثل AGENTS.md و feature_list.json لاستخدامها في مستودعاتك.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>تحليل تصميمات Harness المتقدمة</h3>+ <p>كيف تصمم Pi وClaude Code وCodex وDeepSeek أنظمة harness الفعلية لديها، في ضوء إطار هذا المساق.</p>+ </a></div>## الآلية الأساسية للـ harnessdiff --git a/docs/de/harness-designs/claude-code/index.md b/docs/de/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..0d4869e--- /dev/null+++ b/docs/de/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Analyse des harness-Designs von Claude Code++Anthropic erklärt in [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) ausdrücklich: Zuverlässigkeit entsteht durch den harness, nicht durch das Modell; ein agent muss „außerhalb des Modells“ begrenzt werden. Claude Code ist die Produktumsetzung dieses Gedankens, und Anthropic ordnet es offiziell direkt als **agentic harness** ein. Das ist keine Marketingformulierung: Claude Code ist möglicherweise der derzeit am gründlichsten öffentlich analysierte harness. Der Sourcecode ist offen, Forschungsberichte der Community sind detailliert, und nahezu alle Kernmechanismen der Kurslektionen – geschichtetes Memory, Context-compaction, permissions, hooks, subagents und session-Persistenz – wurden als vollständiges Produkt umgesetzt.++In diesem Artikel analysieren wir Claude Code anhand des Frameworks der fünf Subsysteme und konzentrieren uns darauf, wie es grundlegende harness-Konzepte wie „Kontextverwaltung“, „Verhindern verfrühter Fertigmeldungen“ und „deterministische Constraints“ umsetzt.++## Positionierung in einem Satz++Im Kern von Claude Code steht ein einfacher while-Loop: Modell aufrufen, Tool ausführen, Ergebnis beobachten und Modell erneut aufrufen. Doch **der größte Teil des Codes liegt nicht in diesem Loop, sondern in den Systemen um ihn herum** – im permission-System, in der Context-compaction-Pipeline, in Erweiterungsmechanismen, in der Orchestrierung von subagents und im session-Speicher. Das ist das Wesen eines harness: Der Loop ist das Skelett; alles um dieses Skelett herum bestimmt die Zuverlässigkeit.++## Anweisungssubsystem: Ein geschichtetes Memory-System++Claude Codes Memory-System ist sein direktester Beitrag zur harness-Theorie und entspricht den Kurslektionen „Das Repository als maßgebliche Informationsquelle“ und „Kontextkontinuität über sessions hinweg“. Die offizielle Dokumentation [How Claude remembers your project](https://code.claude.com/docs/en/memory) stellt klar: Jede session beginnt mit einem frischen Kontextfenster und transportiert Wissen über sessions hinweg durch zwei Mechanismen – CLAUDE.md-Dateien (von dir geschriebene Anweisungen) und auto memory (von Claude selbst geschriebene Notizen).++Nach Geltungsbereich teilt die offizielle Dokumentation CLAUDE.md-Dateien in vier Kategorien ein, geladen vom breitesten bis zum spezifischsten Bereich:++- **Ebene der Organisationsrichtlinien**: Zentral durch IT/DevOps verwaltet (zum Beispiel `/etc/claude-code/CLAUDE.md`), für unternehmensweite Standards.+- **Benutzerebene `~/.claude/CLAUDE.md`**: Projektübergreifende persönliche Präferenzen und Regeln.+- **Projektebene `./CLAUDE.md` oder `./.claude/CLAUDE.md`**: Maßgebliche Informationsquelle des Projekts für Engineering-Struktur, Technologie-Stack und Validierungsbefehle; wird mit dem Repository geteilt.+- **Lokale Ebene `./CLAUDE.local.md`**: Persönliche Präferenzen innerhalb eines Projekts; wird normalerweise in `.gitignore` aufgenommen und nicht committed.++Hinzu kommen zwei weitere Mechanismen:++- **Laden bei Bedarf auf Unterverzeichnisebene**: CLAUDE.md-Dateien in Unterverzeichnissen werden nicht beim Start geladen. Sie gelangen erst in den Kontext, wenn Claude Dateien in diesem Verzeichnis liest.+- **Auto memory**: Claude schreibt anhand deiner Korrekturen und Präferenzen proaktiv Notizen. Sie werden pro Repository geteilt, gelten über worktrees hinweg, und pro session werden höchstens die ersten 200 Zeilen oder 25KB geladen.++Diese vier Geltungsbereiche bilden eine **Anweisungshierarchie**: Laut offizieller Dokumentation erscheinen „spezifischere Anweisungen später im Kontext“; Projektanweisungen folgen also auf Benutzeranweisungen. Ihr Wert liegt darin, dass das Modell zu Beginn nicht in jedem Gespräch eine einzige riesige Anweisungsdatei verarbeiten muss. Stattdessen werden Anweisungen entsprechend ihrem Geltungsbereich dort geladen, wo sie gelten. Das ist die Produktantwort auf Lektion 4 „Warum eine einzige riesige Anweisungsdatei scheitert“.++## Kontextsubsystem: Eine fünfstufige compaction-Pipeline++Claude Code verwaltet Kontext mit einer **fünfstufigen compaction-Pipeline (five-layer compaction pipeline)**, nicht einfach nach dem Prinzip „zusammenfassen, wenn er voll ist“. Dieses Architekturdetail stammt aus der Sourcecode-Analyse [Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf) von VILA Lab. Lektion 5 erklärt, warum lang laufende Aufgaben Kontinuität verlieren; Claude Codes Antwort ist ein mehrstufiger Trichter: zuerst verlustfreies Pruning (redundante Toolresultate entfernen), dann strukturierte Verdichtung und erst zuletzt verlustbehaftete LLM-Zusammenfassungen – ergänzt durch Circuit Breaker gegen übermäßige compaction.++Dazu passt das Design des session-Speichers: **append-oriented session storage**. Der gesamte Verlauf wird an `history.jsonl` angehängt; `/resume` stellt ihn wieder her, und fork-Branches werden unterstützt. So „hinterlässt jede session vor ihrem Ende einen guten Handoff“ – nicht wegen eines guten Gedächtnisses, sondern weil die Speicherschicht append-oriented und replayable ist.++## Toolsubsystem: Vier Erweiterungsmechanismen++Claude Code unterteilt seine Erweiterungsoberfläche in vier Kategorien, von denen jede eine andere Problemklasse löst. Dieser Teil seines Designs ist besonders übernehmenswert:++- **Skills**: Laut [offizieller Dokumentation](https://code.claude.com/docs/en/skills) handelt es sich um in `SKILL.md` beschriebenes prozedurales Wissen, das anhand von Triggern automatisch durch progressive disclosure geladen wird. Skills eignen sich für Domänenwissen darüber, „wie etwas getan wird“.+- **MCP**: Das JSON-RPC-Protokoll in der [offiziellen Dokumentation](https://code.claude.com/docs/en/mcp) verbindet externe Systeme und bildet die Standardschnittstelle, über die „das Modell die Außenwelt erreichen kann“.+- **Hooks**: Deterministische Skripte an Lifecycle-Events wie `PreToolUse`, `PostToolUse` und `Stop`, beschrieben in der [offiziellen Dokumentation](https://code.claude.com/docs/en/hooks).+- **Plugins / Subagents**: Die [offizielle Dokumentation](https://code.claude.com/docs/en/sub-agents) beschreibt, wie komplexe Aufgaben an spezialisierte agents delegiert werden.++Die zentrale Designentscheidung ist die **Trennung der Verantwortlichkeiten**: CLAUDE.md verwaltet das „Was“, Skills das „Wie“, MCP das „Womit verbinden“ und hooks das „Wann erzwingen“. Vermischt ein Team diese Schichten – etwa indem es Aufgaben von MCP in CLAUDE.md schreibt –, entsteht das im Kurs beschriebene Kontextleck.++## Feedback und Validierung: Deterministische Constraints + Arbeitsteilung zwischen Mensch und agent++Lektion 10 erklärt, dass „Validierung erst zählt, wenn der vollständige Ablauf funktioniert“. Claude Code setzt dies auf zwei parallelen Wegen um:++**1. Permission-System (deterministische Constraints).** Claude Codes permissions „fragen nicht einfach bei allem nach“, sondern kombinieren sieben Modi mit einem ML-basierten Klassifikator: Operationen mit geringem Risiko werden zugelassen, solche mit hohem Risiko gemäß Richtlinie bestätigt oder abgelehnt (Architekturdetails in der [VILA-Lab-Analyse](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). So wird „dem agent klare Aufgabengrenzen setzen“ aus Lektion 7 als Runtime-Zwang umgesetzt statt als Bitte im Prompt.++**2. Hooks (verfrühte Fertigmeldungen verhindern).** `PostToolUse`-hooks können nach einer Toolausführung Prüfungen erzwingen und deren Resultate in den Kontext zurückschreiben; `Stop`-hooks greifen ein, wenn der agent die Aufgabe für abgeschlossen erklärt. Dadurch werden „die Person, die arbeitet“ und „die Person, die prüft“ getrennt. [Anthropic beobachtete im harness-Artikel ausdrücklich](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), dass agents ihre eigene Arbeit selbstbewusst lobten („confidently praised their work“). Deshalb injizieren hooks **deterministische** Prüfungen, statt der Selbsteinschätzung des Modells zu vertrauen.++**3. Subagents (Kontextisolation).** Der Gesprächsverlauf jedes subagent liegt in einer separaten sidechain-Datei und **bläht den Kontext des Eltern-agent nicht auf** (siehe [VILA-Lab-Analyse](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Das verbindet „Aufgabengrenzen“ mit „Kontextisolation“: Beim Aufteilen einer Aufgabe wird zugleich die Kontextverschmutzung isoliert.++## Observability und session-Persistenz++Claude Codes Logs sind vollständige append-oriented Aufzeichnungen (history.jsonl). Zusammen mit expliziten Befehlen wie `/compact`, `/clear` und `/init` kannst du den Kontextzustand proaktiv verwalten, statt passiv zu warten, bis er voll ist. `/init` macht sogar „den agent vor jeder Arbeit initialisieren“ aus Lektion 6 zu einem Befehl. Laut [offizieller Dokumentation](https://code.claude.com/docs/en/memory) analysiert er die Codebase automatisch und erstellt eine anfängliche CLAUDE.md mit Build-Befehlen, Testanweisungen und Engineering-Konventionen.++## Zuordnung zum Kurs-Framework++| 子系统 | Claude Code 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 作用域分层(组织/用户/项目/本地)+ 自动记忆 | 分层记忆是标杆实现 |+| 工具 | 技能 + MCP + 钩子 + 子智能体四类扩展 | 职责划分清晰,是核心亮点 |+| 环境 | 项目内设置 + settings.json | 靠用户在 CLAUDE.md 里自描述 |+| 状态 | 追加式会话存储 + 五层压缩 + resume/fork | 极强,长任务连续性的参考实现 |+| 反馈 | 权限分类器 + PostToolUse 钩子强制检查 | 把"防提前宣告完成"变成确定性机制 |++## Übernehmenswerte Designs++1. **Anweisungen nach Geltungsbereich schichten**, statt sie in einer Datei anzuhäufen. CLAUDE.md auf Verzeichnisebene ist eine elegante Umsetzung von „nah am Geltungsort laden“.+2. **compaction ist ein abgestufter Trichter**: erst verlustfrei, dann verlustbehaftet; nicht sofort alles zusammenfassen.+3. **hooks für deterministische Prüfungen verwenden**: Verfrühte Fertigmeldungen werden durch Runtime-Zwang verhindert, nicht durch Bitten im Prompt.+4. **Kontext von subagents isolieren**: Beim Aufteilen einer Aufgabe auch den Kontext trennen, damit Resultate von Teilaufgaben den Haupt-Loop nicht verunreinigen.+5. **session-Speicher append-oriented und replayable gestalten**: Handoffs werden durch die Speicherschicht gewährleistet, nicht durch Memory.++## Referenzen (Originaltexte / Sourcecode)++Jede Aussage lässt sich auf die folgenden Originaltexte oder den Sourcecode zurückführen; so werden Wiedergaben aus bloßer Erinnerung vermieden:++- **Offizielle Claude-Code-Dokumentation · Memory**: Frischer Kontext für jede session, vier Geltungsbereiche von CLAUDE.md, Laden bei Bedarf nach Unterverzeichnis, auto memory (200 Zeilen / 25KB) und Erzeugung von CLAUDE.md durch `/init`.<br/>https://code.claude.com/docs/en/memory+- **Offizielle Claude-Code-Dokumentation · Skills / MCP / Hooks / Sub-agents**: Definitionen der vier Erweiterungsmechanismen und ihrer Events (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab《Dive into Claude Code》** (Sourcecode-Analyse): fünfstufige compaction-Pipeline, sieben permission-Modi + ML-Klassifikator, sidechain-subagents und append-oriented session-Speicher in history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic《Effective harnesses for long-running agents》**: Quelle für die Aussagen „Zuverlässigkeit entsteht durch den harness statt durch das Modell“, agents loben ihre eigene Arbeit selbstbewusst und hooks sollten zur Validierung verwendet werden.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack Guide** (Community, Schichten CLAUDE.md / Skills / MCP / Subagents / Hooks): ergänzende Lektüre zur Trennung der Verantwortlichkeiten zwischen Erweiterungsmechanismen.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Verwandte Lektionen: [Lektion 3 · Warum das Repository zur maßgeblichen Informationsquelle werden muss](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Lektion 9 · Warum agents zu früh den Sieg erklären](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Lektion 10 · Warum End-to-End-Tests die Ergebnisse verändern](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/de/harness-designs/codex/index.md b/docs/de/harness-designs/codex/index.mdnew file mode 100644index 0000000..e82e7fd--- /dev/null+++ b/docs/de/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Analyse des harness-Designs von Codex++OpenAIs [Codex](https://openai.com/index/harness-engineering/) ist unter den vier Produkten möglicherweise am engsten mit den Grundprinzipien des harness verbunden: Der Artikel „Harness Engineering“, der dem gesamten Feld seinen Namen gab, fasst die Erfahrungen des OpenAI-Teams bei der Produktentwicklung mit Codex zusammen. Das harness-Design von Codex zu analysieren heißt daher in weiten Teilen, die Engineering-Praxis hinter diesem Artikel zu untersuchen.++Die Philosophie von Codex lässt sich in einem Satz zusammenfassen: **Das Repository ist die maßgebliche Informationsquelle (repository as the system of record), AGENTS.md ist nur eine Verzeichnisseite, und der Wert des Engineerings liegt darin, die Umgebung zu gestalten, Absichten auszudrücken und Feedback-Loops aufzubauen.**++## Positionierung in einem Satz++Das OpenAI-Team lieferte mit Codex innerhalb weniger Wochen ein Produkt aus, das schließlich mehr als eine Million Codezeilen umfasste – **jede einzelne Zeile wurde von Codex geschrieben** (siehe den Abschnitt „Designing for growth“ in [Harness Engineering](https://openai.com/index/harness-engineering/)). Diese Praxis beantwortet eine Frage: Wie sollte ein System organisiert sein, wenn sich die Rolle von Engineers vom „Code schreiben“ zum „harness gestalten“ verlagert? Codex CLI selbst ist ein binäres Open-Source-Monolithprogramm (in Rust implementiert, [github.com/openai/codex](https://github.com/openai/codex)); sein Beitrag zum harness liegt jedoch vor allem in **Konventionen (convention)** und **Context Engineering**, nicht in auffälligen Erweiterungspunkten.++## Anweisungssubsystem: AGENTS.md ist eine Verzeichnisseite, keine Enzyklopädie++Dies ist der einflussreichste Beitrag von Codex zur harness-Theorie:++> Eine einzelne riesige Anweisungsdatei lässt sich nur schwer mechanisch auf Abdeckung, Aktualität, Eigentümerschaft und Querverweise prüfen; Abweichungen von der Realität sind unvermeidlich. Deshalb betrachten wir AGENTS.md nicht länger als Enzyklopädie, sondern als **Verzeichnisseite**. Das Wissen über die Codebase liegt in strukturierten Dokumenten, auf die AGENTS.md verweist.++(Dies ist eine direkte Wiedergabe des Abschnitts „AGENTS.md should be a directory page“ aus [Harness Engineering](https://openai.com/index/harness-engineering/).)++Lektion 4 erklärt, warum „eine einzelne riesige Anweisungsdatei scheitert“; Codex liefert unmittelbar die richtige Lösung: AGENTS.md sollte ungefähr 100 Zeilen umfassen (der Originaltext empfiehlt rund 100 Zeilen und bei Annäherung an die Grenze eine Auslagerung nach `docs/`). Was nicht hineinpasst, wird in das Verzeichnis `docs/` aufgeteilt, damit der agent es bei Bedarf liest. Dies ist die maßgebliche Quelle für das Prinzip „Gib eine Karte, keine Bedienungsanleitung“.++Das ergänzende Prinzip lautet **Invarianten durchsetzen, die Implementierung nicht micromanagen** (Original: „don't micromanage the implementation;focus on invariants“): AGENTS.md enthält nur unverletzliche harte Constraints und Validierungsbefehle; wie sie umgesetzt werden, bleibt dem Modell überlassen. Dies entspricht direkt dem Prinzip „Constraints statt Micromanagement“ aus Lektion 2.++## Kontextsubsystem: Write-Select-Compress-Isolate++Das Context Engineering von Codex lässt sich in vier Strategien zusammenfassen. Dieses Framework entstand in der Community, nachdem sich „context engineering“ als eigene Disziplin etabliert hatte, und wurde anschließend auf Codex zurückgeführt (Quelle: [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):++- **Write (herausschreiben)**: Kontext außerhalb des Fensters persistieren – Erkenntnisse in Dokumente und Zustand in Dateien schreiben, statt beides im Gespräch zu belassen. Dies entspricht dem „Repository als maßgebliche Informationsquelle“.+- **Select (auswählen)**: Nur die benötigten token in das Fenster holen – AGENTS.md weist den Weg und Dateien werden bei Bedarf gelesen, statt das gesamte Repository hineinzuladen.+- **Compress (komprimieren)**: Nur wirklich Wichtiges bewahren – Codex unterstützt automatische compaction und das manuelle `/compact`; `compact_prompt` lässt sich anpassen (siehe [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (isolieren)**: Kontext in getrennte Grenzen aufteilen – subagents isolieren den Kontext verschiedener Aufgaben, sodass beispielsweise ein Frontend-subagent niemals das Datenbankschema des Backends sieht.++Codex besitzt außerdem ein besonders feingranulares Design für Umgebungskontext: Laut der Sourcecode-Analyse in [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) gibt `build_environment_update_item` nur dann **geänderte Felder** aus, wenn sich die Umgebung verändert hat (CWD, git-Branch, Dateisystem), statt in jedem Durchlauf den vollständigen Systemkontext erneut einzufügen. Das ist ein Engineering-Detail nach dem Prinzip, „keine doppelten token im Kontext zu halten“.++## Tools und Grenzen: worktree-Isolation + subagents++Codex besitzt zwei zentrale harness-Mechanismen:++**1. Umgebungsisolation mit git worktrees.** Der Abschnitt „Environment“ in [Harness Engineering](https://openai.com/index/harness-engineering/) erklärt, dass jede Aufgabe in einem eigenen git worktree ausgeführt wird. Zusammen mit einem lokalen Observability-Stack aus Logs, Metriken und Traces kann so jede Änderung in einer isolierten Umgebung validiert werden. Das ist die physische Umsetzung von Lektion 7, „Jeder agent-Aufgabe klare Grenzen setzen“: Die Grenze wird nicht durch eine Anweisung erbeten, sondern durch Umgebungsisolation erzwungen. Das Umgebungssubsystem wird hier zu einer harten Isolation.++**2. subagents auf Kernel-Ebene.** `spawn_agent` / `wait_agent` sind Tools auf Kernel-Ebene: Das Modell erstellt ausdrücklich subagents, gibt ihnen jeweils einen eigenen session-Verlauf und ein eigenes Toolset und wartet auf ihre Ergebnisse. subagents erben die AGENTS.md-Anweisungen des Elternprozesses, arbeiten aber in **ihrem eigenen Kontext**. Die Konfiguration liegt in `.codex/agents/*.toml`; dort lassen sich unterschiedliche Modelle und Anweisungen festlegen (Details im Abschnitt „Sub-agents“ von [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)). Dies ist die direkte Umsetzung von „Kontextisolation“ – und zugleich Ausdruck des Handoff-Gedankens aus Lektion 12: Jeder subagent ist eine Arbeitseinheit mit klaren Grenzen.++## Feedbacksubsystem: Validierungsbefehle in der Spezifikation++Ein Punkt wird in OpenAIs Praxis besonders betont: Validierungsbefehle werden ausdrücklich in AGENTS.md aufgeführt, sodass „Wie bestätigen wir, dass es richtig ist?“ Teil des Repositorys wird. Im Engineering-Prozess mit Codex werden Tests, CI, Dokumentation und Observability-Konfiguration vollständig von Codex erzeugt – und alle bilden „ausführbare Validierungspfade“. Die Lösung für leistungsfähige, aber unzuverlässige Modelle besteht nicht darin, auf ihre Gewissenhaftigkeit zu hoffen, sondern darin, **Validierungspfade zu Standardkomponenten des harness zu machen**.++Approval Policies und Plan Mode bilden die andere Seite des Feedbacks: Vor risikoreichen Aktionen wird zuerst ein Plan erstellt und eine Genehmigung eingeholt. So werden „Aufgabengrenzen“ und „menschliche Entscheidungsgewalt“ als Runtime-Kontrollen umgesetzt.++## Zuordnung zum Kurs-Framework++| 子系统 | Codex 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 目录页 + docs/ 拆分 + 执行不变量 | 教科书级,定义了"给地图不给说明书" |+| 工具 | worktree 隔离 + spawn_agent 子智能体 | 边界靠环境硬隔离,很强 |+| 环境 | 独立 worktree + 可观测性栈 | worktree 隔离是其招牌 |+| 状态 | Write 策略(状态写进文件/文档) | 依赖约定而非内建记忆 |+| 反馈 | 验证命令入规范 + 审批策略 + plan mode | 反馈路径默认化,值得抄 |++Der Vergleich zwischen Codex und Claude Code ist aufschlussreich: Claude Code verfolgt „Addition“ – Memory, permissions und subagents werden in den Kernel eingebaut. Codex verfolgt „Subtraktion“ – der Kernel bleibt möglichst zurückhaltend, während mehr Verantwortung bei Repository-Konventionen und Context Engineering liegt. Deshalb heißt es in der Community oft: „Die harness-Philosophie von Codex ist wertvoller als sein Code.“++## Übernehmenswerte Designs++1. **AGENTS.md als Verzeichnisseite schreiben**: Auf ungefähr 100 Zeilen begrenzen, auf Details in docs/ verweisen und mechanische Prüfungen ermöglichen.+2. **Nur Invarianten festhalten, die Implementierung nicht micromanagen**: Harte Constraints + Validierungsbefehle; den Rest dem Modell überlassen.+3. **worktrees zur Umgebungsisolation verwenden**: Aufgabengrenzen durch die Umgebung erzwingen, nicht durch Bitten in Anweisungen.+4. **Nur Deltas des Umgebungskontexts übertragen**: In jedem Durchlauf nur geänderte Felder ausgeben, statt den vollständigen Systemkontext erneut einzufügen.+5. **subagents zur Kontextisolation verwenden**: Beim Aufteilen der Aufgabe zugleich den Kontext trennen, damit Teilaufgaben den Haupt-Loop nicht verunreinigen.++## Referenzen (Originaltexte / Sourcecode)++Jede Aussage lässt sich auf die folgenden Originaltexte oder den Sourcecode zurückführen; so werden Wiedergaben aus bloßer Erinnerung vermieden:++- **OpenAI, Harness Engineering**: AGENTS.md als Verzeichnisseite und Empfehlung von rund 100 Zeilen, executive invariants / don't micromanage, worktree-Isolation + Observability-Stack, Validierungsbefehle in der Spezifikation, Produktbeispiel mit mehr als einer Million Zeilen sowie Approval Policies und Plan Mode. Hauptquelle für alle Kernaussagen dieses Artikels.<br/>https://openai.com/index/harness-engineering/+- **Offizielle AGENTS.md-Spezifikation von OpenAI** (AGENTS.md als werkzeugübergreifender Standard):<br/>https://openai.com/index/agents-md/+- **Open-Source-Repository von Codex CLI** (in Rust implementiertes binäres Monolithprogramm):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (Community): Write-Select-Compress-Isolate-Framework, `/compact` und `compact_prompt`, `spawn_agent` / `wait_agent`-subagents sowie die Konfiguration in `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (Sourcecode-Analyse der Community): Implementierungsdetails wie der inkrementelle Umgebungskontext von `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Verwandte Lektionen: [Lektion 3 · Warum das Repository zur maßgeblichen Informationsquelle werden muss](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Lektion 4 · Warum eine einzige riesige Anweisungsdatei scheitert](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Lektion 7 · Warum agents zu weit greifen und zu wenig abschließen](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/de/harness-designs/deepseek/index.md b/docs/de/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..1cf4f7d--- /dev/null+++ b/docs/de/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# Analyse des Designs von DeepSeek Harness++[DeepSeek Harness](https://deepseek.com/harness) (Befehl `dsh`, Repository `deepseek-ai/deepseek-harness`) erschien im August 2026 als Developer Preview. Die offizielle Definition ist direkt: **Agent = Model + Environment + Tools + State** – Modell, Umgebung, Tools und Zustand als vier Bestandteile.++Wenn die Analyse der ersten drei Produkte fragt, „wie ein harness gestaltet sein sollte“, stellt DeepSeek Harness eine radikalere Frage: **Kann sich ein harness von einem bestimmten Modell lösen und zu einer eigenständigen Runtime werden?** Die Antwort lautet ja, und das Konzept wird bis zum Äußersten getrieben. Die [Architekturdokumentation](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) formuliert es so: *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* (Jeder Teil des Produkts ist ein plugin – einschließlich Modelladapter, Tool-Registry, session-Log und sogar agent-Loop).++In dieser Analyse betrachten wir drei Dinge besonders: den plugin-basierten Kernel, Capability Seams und die Event-Pipeline sowie den stärksten Engineering-Constraint des Systems: „Model-visible means logged“.++## Positionierung in einem Satz++Die Struktur eines traditionellen coding agent lautet „LLM + fester agent-Loop + festes Toolset“. DeepSeek Harness besteht dagegen aus „Modell + plugin-Kernel (Cordis)“. Der Kernel verantwortet nur Laden und Entladen der plugins, ihre Abhängigkeiten und den Event-Mechanismus; **er besitzt keine konkrete agent-Fähigkeit**. Die [Architekturdokumentation](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) sagt dazu: „There is no privileged core to patch“ (Es gibt keinen privilegierten Kernel, der gepatcht werden muss) und „you extend dsh by mounting a plugin beside the others“ (dsh wird erweitert, indem man neben den anderen ein plugin einhängt, ohne den Kernel zu verändern). Das bedeutet, dass selbst der agent-Loop nicht unantastbar ist: Du kannst DeepSeeks Modell mit Claude Codes subagents, einer Remote-Sandbox, eigenem Memory, einem eigenen Loop und einer eigenen UI zu einem völlig neuen agent kombinieren.++Das ist die konsequenteste Umsetzung des Kurssatzes „Alles außerhalb der Modellgewichte ist harness“: Wenn der harness unabhängig ist, wird er zu einem eigenständigen Betriebssystem.++## Architekturkern 1: Capability Seam++DeepSeek Harness stellt „Fähigkeiten“ als Services dar; fast jede Fähigkeit ist in drei Ebenen aufgeteilt:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Am Beispiel des Dateisystems: Unter dem `FS Service` stehen mehrere Provider wie Local FS, E2B FS und Remote FS, die nach oben einheitlich als file tools exponiert werden. Shell, Subprocess, Sandbox, Web, LLM und SubAgent folgen derselben Struktur. Diese Dreiteilung ist keine Zusammenfassung von uns. Die [Architekturdokumentation · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) sagt: *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* (Ein Capability Seam ist eine austauschbare Fähigkeit mit drei Rollen: einer Service Definition, die das Interface deklariert, einem Service Provider, der es implementiert, und einem Consumer, der es verwendet – üblicherweise ein dem Modell zugängliches Tool).++Dies löst ein dauerhaftes Problem im harness-Engineering: **Soll ein agent von „konkreten Tools“ oder von „Fähigkeitsschnittstellen“ abhängen?** DeepSeek Harness entscheidet sich für Letztere. Für den Kurs bedeutet das: Das „Toolsubsystem“ wird als Interface standardisiert. Wird ein Provider ausgetauscht, bleibt die dem Modell gezeigte Tooloberfläche unverändert, während sich die Umgebung vollständig ändert.++## Architekturkern 2: Event-Pipeline++DeepSeek Harness besteht intern nicht aus einem einfachen „LLM → Tool → LLM“, sondern aus einer Event-Pipeline, in der jedes Glied ein durch plugins beobachtbarer Event-Punkt ist:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(Die obige Pipeline ist eine Wiedergabe des Abschnitts [Architekturdokumentation · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): `turn/*`, `step/*`, `user/message`, `assistant/*` und `tool/*` sind persistierte session-Events; `agent/pre-step`, `agent/request`, `llm/stream` und `tools/*` sind Erweiterungspunkte, die plugins beobachten können.)++Der größte Vorteil dieses Designs: **Viele Funktionen erfordern keinerlei Änderung am agent-Loop selbst.** Eine Sicherheitsprüfung vor der Toolausführung? `tools/pre-execute` beobachten. Memory hinzufügen? In `agent/pre-step` injizieren. Verhalten protokollieren? session-Events abonnieren. Modell-Requests verändern? Einen hook an `agent/request` hängen. Entscheiden, ob die Inferenz fortgesetzt wird? `agent/turn-stopping` beobachten.++Verglichen mit Lektion 11 „Den Lauf eines agent observable machen“ geht DeepSeek Harness noch weiter: Es „fügt nicht einfach Logs hinzu“, sondern macht **jeden Schritt des Loops zu einem Event-Punkt**. Observability, permissions, Memory und Richtlinien hängen als Listener am Loop, statt darin fest verdrahtet zu sein.++## Architekturkern 3: Session Event Log und „Model-visible means logged“++DeepSeek Harness besitzt ein **append-only Session Event Log** und stellt einen äußerst starken Engineering-Constraint auf. Das [Architekturdokument · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) formuliert ihn so:++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Alles, was das Modell sehen kann, muss protokolliert werden. Alles, was in einen Modell-Request gelangt, muss aus dem Log rekonstruierbar sein; eine Runtime-Invariante erzwingt dies.)++Mit anderen Worten: Observability ist kein nachträglich ergänztes Logging, sondern ein Constraint erster Ordnung des harness. Alles, was in den Modellkontext gelangt, sollte standardmäßig im Log verbleiben. Das greift „Observability gehört in den harness“ aus der Abschlusslektion direkt auf und erhebt „append-only“ zum Speicherprinzip: Logs werden nur angehängt, nie überschrieben, und der session-Zustand lässt sich replayen.++## Zuordnung zum Kurs-Framework++| 子系统 | DeepSeek Harness 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 插件化;规则/技能均以插件形态注入 | 极自由,但没有内置的"CLAUDE.md"式惯例 |+| 工具 | Service Definition → Provider → Consumer 能力接缝 | 工具子系统标准化的极致 |+| 环境 | 沙箱/FS/Shell 全部可换 Provider(含远程 E2B) | 环境彻底可插拔 |+| 状态 | append-only Session Event Log + Model-visible means logged | 可观测性是第一性约束 |+| 反馈 | tools/pre-execute 上的 permission / guard / policy / hook | 反馈机制事件化 |++Der grundlegende Unterschied zwischen DeepSeek Harness und den drei anderen Produkten: Pi, Claude Code und Codex optimieren den harness jeweils „innerhalb eines bestimmten agent“. DeepSeek Harness definiert den harness dagegen als **modellunabhängiges Betriebssystem**; der agent selbst ist nur eine austauschbare Anwendung auf diesem OS. Der Preis ist offensichtlich: Hohe Freiheit verursacht hohen Konfigurationsaufwand. Das ist die unvermeidliche Kehrseite des Designs „harness als OS“ – und in der Developer Preview lautet die Positionierung ohnehin „früh ausprobieren, während sich die Mechanismen noch entwickeln“.++## Übernehmenswerte Designs++1. **Jeden Schritt des Loops zu einem Event-Punkt machen**: permissions, Memory, Richtlinien und Logs hängen als Listener am Loop, statt darin fest verdrahtet zu sein.+2. **Capability Seams standardisieren**: Von „Fähigkeitsschnittstellen“ statt von „konkreten Tools“ abhängen, damit die gesamte Umgebung ausgetauscht werden kann, ohne die dem Modell gezeigte Tooloberfläche zu verändern.+3. **Model-visible means logged**: Alles, was das Modell sehen kann, muss protokolliert werden; Observability wird vom „Bonus“ zum „Constraint erster Ordnung“.+4. **append-only session-Logs**: Der Zustand lässt sich replayen und Handoffs werden zuverlässig – eine technische Garantie für „jede session hinterlässt einen sauberen Zustand“.++## Referenzen (Originaltexte / Sourcecode)++Jede Aussage lässt sich auf die folgenden Originaltexte oder den Sourcecode zurückführen; so werden Wiedergaben aus bloßer Erinnerung vermieden:++- **Offizielle Website von DeepSeek Harness**: Produktdefinition „Agent = Model + Environment + Tools + State“, Positionierung als Developer Preview und Befehl `dsh`.<br/>https://deepseek.com/harness+- **Repository deepseek-ai/deepseek-harness** (Befehl `dsh`, MIT-Lizenz):<br/>https://github.com/deepseek-ai/deepseek-harness+- **Architekturdokument architecture.md**: Wichtigste Quelle dieses Artikels – „Every part of the product is a plugin“, „There is no privileged core to patch“, Turn-flow-Event-Pipeline, drei Rollen der Capability Seams, „Model-visible means logged“ und Runtime-Invariante, append-only Session Event Log sowie Capability Seams wie fs/tools/telemetry und `ctx.*`-Subsysteme.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **Begleitdokumente zur Architektur**: Einführung in den Cordis-Kernel (plugins contribute services, typed events, reversible effects), Details zu Capability Seams und session-Subsystem.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Verwandte Lektionen: [Lektion 11 · Warum Observability in den harness gehört](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Lektion 12 · Warum jede session einen sauberen Zustand hinterlassen muss](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Lektion 2 · Was ein harness tatsächlich ist](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/de/harness-designs/index.md b/docs/de/harness-designs/index.mdnew file mode 100644index 0000000..525c13e--- /dev/null+++ b/docs/de/harness-designs/index.md@@ -0,0 +1,29 @@+# Analyse führender Harness-Designs++In dieser Reihe werden die in den Kurslektionen behandelten harness-Theorien einzeln mit aktuellen, führenden Produkten aus der Praxis verglichen. Bei jedem Produkt interessiert uns nur eine Frage: **Wie ist sein harness gestaltet?** Gemeint ist also jene Engineering-Infrastruktur rund um das Modell: die fünf Subsysteme für Anweisungen, Tools, Umgebung, Zustand und Feedback sowie Kernmechanismen wie Kontextkontinuität, Initialisierung, Validierung, Observability, Handoff und Loops.++Wir sprechen bewusst weder darüber, wie gut ein Modell schlussfolgern kann, noch über einzelne Benchmark-Ergebnisse, und wir geben auch keine allgemeine Übersicht darüber, „was dieser agent kann“. Das sind Fragen der Modell- und Produktebene. Hier analysieren wir ausschließlich den harness – alles außerhalb der Modellgewichte.++## Warum sich die Analyse lohnt++Die erste Lektion stellt fest: Ein leistungsfähiges Modell garantiert keine zuverlässige Ausführung. Dasselbe Modell kann sich in unterschiedlichen harnesses um eine Größenordnung anders verhalten. Die Lektionen erklären jedoch, „wie man es tun sollte“; diese Produkte zeigen, „wie führende Teams es tatsächlich tun“.++Jedes Produkt verkörpert eine eigenständige Sammlung von Designentscheidungen. Im direkten Vergleich wird sichtbar, wie dieselben Kernmechanismen von verschiedenen Teams auf völlig unterschiedliche Weise umgesetzt werden:++- **Pi** gestaltet den harness als minimalistischen Kernel mit programmierbaren Erweiterungen und betreibt Context Engineering durch „minimale System-Prompts + Laden bei Bedarf“.+- **Claude Code** gestaltet den harness als vollständige Laufzeitumgebung: geschichtetes Memory, fünfstufige compaction, permissions, hooks und subagents.+- **Codex** treibt die harness-Philosophie auf die Spitze: Das Repository ist die maßgebliche Informationsquelle, AGENTS.md lediglich eine Verzeichnisseite, und worktrees isolieren die Umgebung.+- **DeepSeek Harness** definiert den harness selbst kurzerhand als modellunabhängige Runtime: Everything is a Plugin.++## Artikelliste++- [Analyse des harness-Designs von Pi](./pi/): minimalistischer Kernel + programmierbare Erweiterungen; Context Engineering außerhalb des System-Prompts.+- [Analyse des harness-Designs von Claude Code](./claude-code/): geschichtetes Memory, fünfstufige compaction, permissions und hooks – eine vollständige agent-Laufzeitumgebung.+- [Analyse des harness-Designs von Codex](./codex/): Das Repository als maßgebliche Informationsquelle, AGENTS.md als Verzeichnisseite sowie Umgebungsisolation und Feedback-Loops.+- [Analyse des Designs von DeepSeek Harness](./deepseek/): Everything is a Plugin – selbst der agent-Loop ist ein austauschbares plugin.++## Leseempfehlung++Lies am besten zuerst die ersten Kurslektionen – insbesondere [Lektion 2: Was ein Harness tatsächlich ist](../lectures/lecture-02-what-a-harness-actually-is/) –, um das Framework der fünf Subsysteme kennenzulernen. Kehre anschließend hierher zurück und sieh dir an, wie reale Produkte diese Mechanismen umsetzen.++Jeder Artikel endet mit den beiden Abschnitten „Zuordnung zum Kurs-Framework“ und „Übernehmenswerte Designs“. Sie helfen dir, das Produktdesign schnell in die Konzepte des Kurses zurückzuübersetzen und direkt in eigene Projekte zu übernehmen.diff --git a/docs/de/harness-designs/pi/index.md b/docs/de/harness-designs/pi/index.mdnew file mode 100644index 0000000..37001fd--- /dev/null+++ b/docs/de/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Analyse des harness-Designs von Pi++[Pi](https://pi.dev/) (npm-Paket `@earendil-works/pi-coding-agent`) bezeichnet sich selbst als „minimal agent harness“ – als minimalistischen agent harness. Diese Formulierung lohnt eine genauere Betrachtung: Pi nennt sich weder „leistungsfähigster coding agent“ noch „benutzerfreundlichstes AI-Programmierwerkzeug“, sondern verankert seine Positionierung ausdrücklich im Begriff **harness**.++In diesem Artikel analysieren wir Pi anhand des Frameworks der fünf Subsysteme – Anweisungen, Tools, Umgebung, Zustand und Feedback – und untersuchen, wie sich seine Designphilosophie grundlegend von Claude Code und Codex unterscheidet. Die Antwort vorweg: **Pis Philosophie lautet „Kernel minimieren + Erweiterungen programmierbar machen“. Context Engineering findet außerhalb des System-Prompts statt, und die Nutzer – oder sogar Pi selbst – verändern den harness, statt Pi über den harness entscheiden zu lassen.**++## Positionierung in einem Satz++Pi ist ein minimalistischer Kernel: Die offizielle Positionierung hält den Kernel bewusst klein und gibt dir die Entscheidungshoheit zurück. Die [pi.dev-Startseite](https://pi.dev/) formuliert es so: „Ask Pi to build what you want, or install a package that does it your way“. Pi unterteilt den anpassbaren harness in vier Ebenen:++- **Extensions**: TypeScript-hooks an Ereignissen des Pi-Lebenszyklus, die programmierbare Oberfläche auf Runtime-Ebene.+- **Skills**: Bei Bedarf geladene Fähigkeitspakete mit Anweisungen und Tools; progressive disclosure.+- **Prompt templates**: Wiederverwendbare Markdown-Prompts, die mit `/name` expandiert werden.+- **Themes**: Das Erscheinungsbild der TUI.++Diese Schichtung ist selbst ein harness-Design: **Was das Modell wann sehen kann, wird vollständig Regeln und Erweiterungen überlassen, statt fest im Kernel verdrahtet zu sein.**++## Kern-Loop++Wie alle coding agents besteht Pi im Kern aus einem while-Loop „schlussfolgern → Tool ausführen → beobachten → erneut schlussfolgern“. Bemerkenswert ist nicht der Loop selbst, sondern wie Pi mit seiner äußeren Schicht umgeht: Kontextverwaltung wird von der „compaction“ innerhalb des Loops zur „Kontrolle“ außerhalb des Loops erweitert.++Pis Runtime stellt eine programmierbare Schnittstelle bereit. Der Abschnitt [Programmatic Usage im Sourcecode-README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) beschreibt neben der interaktiven TUI auch skriptfähige Print-/JSON-Modi, ein RPC-Protokoll und die Einbettung per SDK. So kann derselbe harness entweder schrittweise von Menschen oder automatisiert durch CI/CD beziehungsweise andere Programme gesteuert werden. Dies entspricht der Voraussetzung aus Lektion 13 „Loop Engineering“ für den Weg „von manueller Steuerung zu automatischen Loops“: Ein harness, den nur Menschen interaktiv steuern können, wird nie Teil eines automatischen Loops.++## Anweisungssubsystem: AGENTS.md und SYSTEM.md++Pi geht zurückhaltend mit „Anweisungen“ um, besitzt aber eine klare Hierarchie:++- **AGENTS.md**: Der Abschnitt [Project Context Files im Sourcecode-README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) beschreibt die Ladereihenfolge ausdrücklich: globales `~/.pi/agent/AGENTS.md` → schrittweises Durchlaufen der Elternverzeichnisse → `./AGENTS.md` im aktuellen Verzeichnis (auch mit CLAUDE.md kompatibel). Das setzt das Prinzip „Repository als maßgebliche Informationsquelle“ um: Anweisungen sind Dateien, keine Ermahnungen im Chatfenster.+- **SYSTEM.md**: Laut der [offiziellen pi.dev-Dokumentation](https://pi.dev/docs/usage/project-context) kann der Standard-System-Prompt projektspezifisch ersetzt (replace) oder ergänzt (append) werden. Dies ist der einzige offizielle Zugang, über den Pi Änderungen am „System-Prompt“ erlaubt, und zugleich seine Ebene der „Selbstbeschreibung der Umgebung“.++Pi betont offiziell, dass sein System-Prompt selbst **minimalistisch** ist. Dahinter steht ein klarer Trade-off: Der Kernel wird nicht mit langen „Wenn … dann …“-Regeln gefüllt, sondern bietet Erweiterungspunkte, über die Regeln erst bei Bedarf als Skills und Extensions erscheinen. Das greift Lektion 4 „Warum eine einzige riesige Anweisungsdatei scheitert“ direkt auf: Mit „minimalistischem Kernel + aufgeteilten Dateien + Laden bei Bedarf“ vermeidet Pi das Problem riesiger Anweisungsdateien von vornherein.++## Zustand und Kontext: Pis feingranularste Aufteilung++Pis Context Engineering verdient besondere Aufmerksamkeit, weil es Konzepte wie „Kontextkontinuität“ und „Vermeidung von Kontextkorruption“ in konkrete Mechanismen übersetzt:++**1. Compaction wird programmierbar.** Wenn sich der Kontext seinem Limit nähert, werden alte Nachrichten automatisch zusammengefasst. Die [offizielle pi.dev-Dokumentation](https://pi.dev/docs/usage/sessions) erklärt, dass die compaction-Strategie selbst **anpassbar** ist: Mit Extensions lassen sich themenbasierte compaction, codebewusste Zusammenfassungen oder sogar ein anderes Modell für die Zusammenfassung implementieren. Das Sourcecode-README beschreibt auch Details des Standardmechanismus: Automatische compaction wird in zwei Fällen ausgelöst – Wiederherstellung nach einem Kontextüberlauf oder Überschreiten des Aufbewahrungsschwellwerts. Der Schnittpunkt bewahrt ungefähr die jüngsten 20.000 token; frühere Nachrichten werden zu einem „context handoff“ zusammengefasst und schrittweise in einer Kette weiter komprimiert. Pi behandelt die Frage „Wie wird komprimiert?“ also nicht als unveränderliche Konstante, sondern als Teil des harness.++**2. Dynamic context.** Laut der [offiziellen pi.dev-Dokumentation](https://pi.dev/docs/usage/extensions) können Extensions vor jedem Inferenzdurchlauf Nachrichten injizieren, den Nachrichtenverlauf filtern, RAG implementieren und langfristiges Memory aufbauen. Dies geht über „erst komprimieren, wenn der Kontext voll ist“ hinaus: Du entscheidest, was in das Kontextfenster gelangt, bevor es dieses erreicht. Pi verlagert damit die Kurskonzepte „den Lauf eines agent observable und debuggable machen“ und „Kontextkontinuität bewahren“ auf die Erweiterungsoberfläche.++**3. Session tree.** Die [pi.dev-Startseite](https://pi.dev/) sagt ausdrücklich, dass „sessions are stored as trees“: Mit `/tree` kann man zu jedem historischen Knoten zurückkehren und dort fortfahren; alle Branches bleiben in derselben Datei erhalten. Dies löst das im Kurs wiederholt behandelte Problem von Kontextabbrüchen zwischen sessions – nicht durch das harte Aneinanderfügen von Zusammenfassungen, sondern durch strukturiertes Replay des Verlaufs. Branches lassen sich als HTML exportieren oder als gist teilen; Observability ergibt sich dabei gleich mit.++## Toolsubsystem: Skills und Extensions++Pis „Tools“ bestehen aus zwei Ebenen:++- **Skills**: Der Abschnitt [Skills im Sourcecode-README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) definiert sie eindeutig als „self-contained capability packages that the agent loads on-demand“ – bei Bedarf geladene, eigenständige Fähigkeitspakete mit Anweisungen und Tools, die dem Agent-Skills-Standard folgen. Durch progressive disclosure gelangen Details eines Skills erst beim Auslösen in den Kontext und **überladen den prompt cache nicht**. Das ist harness-Design aus Kostenperspektive: Jeder zusätzliche token im Kontext muss bei jeder Inferenz bezahlt werden. Skills nur bei Bedarf zu laden ist eine weitere Form von „Gib eine Karte, keine Bedienungsanleitung“.+- **Extensions**: TypeScript-hooks an integrierten Lifecycle-Events. Der Abschnitt [Hooks im Sourcecode-README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) nennt offizielle Anwendungsbeispiele: gefährliche Befehle abfangen (permission gate), beim Aufgabenwechsel einen checkpoint des Codezustands anlegen, Pfade schützen (etwa Schreibzugriffe auf `.env` verbieten), Toolausgaben vor der Übergabe an das Modell verändern und Nachrichten aus externen Quellen wie File Watcher, Webhook oder CI injizieren, um den agent zu wecken. Diese hooks-APIs werden außerdem über `@mariozechner/pi-coding-agent/hooks` exportiert. Der Community-harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) kapselt die hooks-Oberfläche weiter in fertige Erweiterungen wie skill-router, session-summary, extract-patterns und telemetry.++Extensions sind Pis wichtigste Designentscheidung: **Pi stellt den Nutzern nicht bloß einige Schalter bereit, sondern öffnet die gesamte Ereignisoberfläche der Runtime.** Memory hinzufügen? In `agent/pre-step` injizieren. Verhalten protokollieren? session-Events abonnieren. Modell-Requests ändern? Einen hook an `agent/request` hängen. Du kannst Pi seinen eigenen harness verändern lassen – das kommt der Definition eines „programmierbaren harness“ näher als jede Konfigurationsoption.++## Feedback und Validierung: Auch „Lernen“ wird Teil des harness++Pi selbst bringt kein obligatorisches Test-Gate mit – die Validierungsbefehle müssen Nutzer in AGENTS.md festhalten. Der Community-harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) strukturiert den „Feedback-Loop“ jedoch über Extensions; auch der Hooks-Abschnitt des offiziellen README liefert die Grundlage für ähnliche Mechanismen:++- **session-summary** (pi-agent-harness-Extension): Pflegt fortlaufende Einträge in `PROGRESS.md` – das Zustandssubsystem des Kurses für die Fortschrittsverfolgung bei langen Aufgaben.+- **extract-patterns** (pi-agent-harness-Extension): Sammelt Kandidaten für Lessons Learned aus sessions und hält sie in `LESSONS.md` fest. So wird „vor dem Ende jeder session einen guten Handoff vorbereiten“ von einer Konvention zum Mechanismus.+- **telemetry** (pi-agent-harness-Extension): Protokolliert token-Verbrauch, Kosten und weitere Werte – Observability.++Dasselbe Community-Repository bestätigt dieses Muster weiter: `VISION.md` (Ziel), `PROGRESS.md` (Fortschritt), `LESSONS.md` (Erkenntnisse) und `STANDARDS.md` (Standards) sind sämtlich Markdown-Dateien, die über sessions hinweg persistieren. Dies entspricht exakt dem vom Kurs empfohlenen Muster „Repository als maßgebliche Informationsquelle + Fortschrittsdatei + Handoff-Mechanismus“, wird durch Pis Erweiterungsmechanismus jedoch gebrauchsfertig.++## Zuordnung zum Kurs-Framework++Bewertung von Pi anhand der fünf Subsysteme des Kurses (subjektiv, zum Vergleich):++| 子系统 | Pi 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 分级加载 + SYSTEM.md | 层级清晰,但规则本身要靠用户写 |+| 工具 | 技能按需加载 + 扩展全生命周期钩子 | 极强,把工具系统做成了可编程面 |+| 环境 | SYSTEM.md 做环境自描述;运行时环境靠用户在 AGENTS.md 里声明 | 机制是开放的,但可复现性依赖用户自述 |+| 状态 | 会话树 + 压缩可定制 + PROGRESS.md | 极强,跨会话与可恢复性是其核心 |+| 反馈 | 验证命令靠用户定义;session-summary / extract-patterns 机制化 | 机制提供,内容靠用户 |++Pis Trade-offs stehen in scharfem Kontrast zu Claude Code und Codex: Claude Code baut „Memory, permissions und subagents“ gebrauchsfertig in den Kernel ein; Codex macht „Repository-Konventionen und Umgebungsisolation“ zum Standard. Pi entscheidet sich dafür, **nichts an deiner Stelle zu entscheiden** – es macht die Entscheidungshoheit zu Erweiterungspunkten. Der Preis: Du musst Extensions entweder selbst schreiben oder Pakete anderer installieren.++## Übernehmenswerte Designs++1. **Die compaction-Strategie austauschbar machen.** „Wie wird Kontext komprimiert?“ sollte in deinem harness kein fest verdrahteter Parameter, sondern eine austauschbare Strategieschnittstelle sein.+2. **Einen session tree statt harter Zusammenfassungen verwenden.** Wiederherstellung über sessions hinweg muss nicht von einer „Zusammenfassung des letzten Durchlaufs“ abhängen; strukturiertes Replay des Verlaufs ist oft das zuverlässigere Zustandssubsystem.+3. **Den prompt cache berücksichtigen.** Skills bei Bedarf laden und nicht sämtliche Regeln auf einmal in den System-Prompt packen – das ist sowohl Context Engineering als auch Kosten-Engineering.+4. **Den agent seinen eigenen harness verändern lassen.** Ist die Erweiterungsoberfläche des harness offen genug, kann die „Optimierung des agent-Verhaltens“ halbautomatisch vom agent selbst vorgenommen werden.++## Referenzen (Originaltexte / Sourcecode)++Jede Aussage lässt sich auf die folgenden Originaltexte oder den Sourcecode zurückführen; so werden Wiedergaben aus bloßer Erinnerung vermieden:++- **Offizielle pi.dev-Website**: Originale Positionierung „Ask Pi to build what you want, or install a package that does it your way“, vier anpassbare Ebenen, session tree („sessions are stored as trees“, `/tree`, Speicherung in einer Datei, HTML-Export / Teilen als gist).<br/>https://pi.dev/+- **Offizielle pi.dev-Dokumentation · Sessions**: Austauschbare compaction (topic-based / code-aware / anderes Zusammenfassungsmodell), automatische compaction und Mechanismus zur Injektion von dynamic context.<br/>https://pi.dev/docs/usage/sessions+- **Offizielle pi.dev-Dokumentation · Extensions**: Extensions können vor jedem Inferenzdurchlauf Nachrichten injizieren, den Verlauf filtern, RAG ausführen und langfristiges Memory aufbauen.<br/>https://pi.dev/docs/usage/extensions+- **Offizielle pi.dev-Dokumentation · Project Context**: replace- / append-Semantik von SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **Sourcecode-README des Pi Coding Agent** (badlogic/pi-mono): dreistufige Ladereihenfolge von AGENTS.md (global → Elternverzeichnis → aktuelles Verzeichnis), Auslöser von `/compact` und automatischer compaction sowie Schnittpunkt bei 20.000 token, Laden von Skills bei Bedarf und Agent-Skills-Standard, Hooks-Lebenszyklus und offizielle Anwendungsbeispiele, Programmatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **Community-Repository pi-agent-harness**: skill-router- / session-summary- / extract-patterns- / telemetry-Extensions und das Dateisystem aus VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++Verwandte Lektionen: [Lektion 2 · Was ein harness tatsächlich ist](../lectures/lecture-02-what-a-harness-actually-is/) | [Lektion 5 · Warum lang laufende Aufgaben ihre Kontinuität verlieren](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Lektion 13 · Loop Engineering](../lectures/lecture-13-loop-engineering/)diff --git a/docs/de/index.md b/docs/de/index.mdindex a58a7b6..d075edd 100644--- a/docs/de/index.md+++ b/docs/de/index.md@@ -25,6 +25,10 @@ Wähle deinen Lernpfad. Der Kurs besteht aus theoretischen Lektionen, praktische<h3>Ressourcenbibliothek</h3><p>Kopierfertige Vorlagen wie AGENTS.md und feature_list.json für deine eigenen Repositories.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Analyse führender Harness-Designs</h3>+ <p>Wie Pi, Claude Code, Codex und DeepSeek ihre Harnesses tatsächlich entwerfen, eingebettet in das Rahmenwerk des Kurses.</p>+ </a></div>## Der Kernmechanismus eines Harnessdiff --git a/docs/en/harness-designs/claude-code/index.md b/docs/en/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..000854d--- /dev/null+++ b/docs/en/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Breaking Down Claude Code's Harness Design++In [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), Anthropic states clearly that reliability comes from the harness, not the model, and that agents need constraints "outside the model." Claude Code is a productized example of this idea; Anthropic itself explicitly classifies it as an **agentic harness**. This is not marketing language—Claude Code may be the most thoroughly examined public harness today: its source code is open, community research reports are detailed, and it turns nearly every core mechanism in the course lectures—layered memory, context compaction, permissions, hooks, subagents, and session persistence—into a complete product implementation.++In this article, we use the course's five-subsystem framework to break down Claude Code, focusing on how it implements foundational harness concepts such as "context management," "preventing premature declarations of completion," and "deterministic constraints."++## In One Sentence++At the core of Claude Code is a simple while loop: call the model, execute a tool, observe the result, and call the model again. But **most of the code is not in that loop; it is in the systems surrounding the loop**—the permission system, context compaction pipeline, extension mechanisms, subagent orchestration, and session storage. This is the essence of a harness: the loop is the skeleton, but everything around the skeleton determines reliability.++## Instruction Subsystem: A Layered Memory System++Claude Code's memory system is its most direct contribution to harness theory, corresponding to the course lectures on "the repository as the system of record" and "cross-session context continuity." The official documentation, [How Claude remembers your project](https://code.claude.com/docs/en/memory), states clearly that every session starts with a fresh context window and carries knowledge across sessions through two mechanisms: CLAUDE.md files (instructions you write) and auto memory (notes Claude writes itself).++In terms of scope, the official documentation divides CLAUDE.md files into four categories (loaded from broadest to most specific):++- **Organization policy level**: Centrally managed by IT/DevOps (for example, `/etc/claude-code/CLAUDE.md`) for company-wide standards.+- **User-level `~/.claude/CLAUDE.md`**: Personal preferences and rules that apply across projects.+- **Project-level `./CLAUDE.md` or `./.claude/CLAUDE.md`**: The project-level system of record for architecture, technology stack, and verification commands, shared with the repository.+- **Local-level `./CLAUDE.local.md`**: Personal preferences within a project, usually added to `.gitignore` rather than committed.++There are also two additional mechanisms:++- **On-demand loading at the subdirectory level**: CLAUDE.md files in subdirectories are not loaded at startup; they enter the context only when Claude reads files in that directory.+- **Auto memory**: Claude proactively writes notes based on your corrections and preferences. These notes are shared by repository, apply across worktrees, and load at most the first 200 lines or 25KB per session.++These four scopes form an **instruction hierarchy**: the official documentation says that "more specific instructions appear later in the context" (project instructions appear after user instructions). The value is that the model does not have to digest an entire giant instruction file at the beginning of every conversation; instructions are loaded close to where they apply, according to scope. This is the productized answer to Lecture 4, "Why One Giant Instruction File Fails."++## Context Subsystem: A Five-Layer Compaction Pipeline++Claude Code manages context through a **five-layer compaction pipeline**, not simply by "summarizing when it gets full." This architectural detail comes from VILA Lab's source-level analysis, [Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). Lecture 5 explains how long-running tasks lose continuity; Claude Code's answer is a multi-stage funnel: first apply lossless pruning (removing redundant tool results), then perform structured distillation, and only then use lossy LLM summaries, with circuit breakers to prevent excessive compaction.++This is paired with the design of session storage: **append-oriented storage**. All history is appended to `history.jsonl`, with `/resume` recovery and fork branches. This ensures that "every session leaves a good handoff before ending"—not because the system has a good memory, but because the storage layer is append-oriented and replayable.++## Tool Subsystem: Four Extension Mechanisms++Claude Code divides its extension surface into four categories, each solving a different kind of problem. This is the part of its design most worth adopting:++- **Skills**: Defined in the [official documentation](https://code.claude.com/docs/en/skills) as procedural knowledge described by `SKILL.md`, loaded automatically based on triggers through progressive disclosure. They are suited to domain knowledge about "how to do something."+- **MCP**: The JSON-RPC protocol in the [official documentation](https://code.claude.com/docs/en/mcp) connects external systems, providing a standard interface through which "the model can reach the outside world."+- **Hooks**: Deterministic scripts attached to lifecycle events such as `PreToolUse`, `PostToolUse`, and `Stop`, as described in the [official documentation](https://code.claude.com/docs/en/hooks).+- **Plugins / Subagents**: The [official documentation](https://code.claude.com/docs/en/sub-agents) describes delegating complex tasks to specialized agents.++The key design is **separation of responsibilities**: CLAUDE.md manages "what," Skills manage "how," MCP manages "where to connect," and hooks manage "when to enforce." If a team mixes these layers—for example, putting work that belongs in MCP into CLAUDE.md—it creates the context leakage described in the course.++## Feedback and Verification: Deterministic Constraints + Human-Agent Division of Labor++Lecture 10 explains that "verification only counts when the complete flow works." Claude Code implements this through two tracks:++**1. Permission system (deterministic constraints).** Claude Code's permissions do not simply "ask about everything." They combine seven modes with an ML-based classifier: low-risk operations are allowed, while high-risk operations are either confirmed or denied according to policy (for architectural details, see the [VILA Lab analysis](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). This turns "setting clear task boundaries for the agent" (Lecture 7) into runtime enforcement instead of a plea in a prompt.++**2. Hooks (preventing premature declarations of completion).** `PostToolUse` hooks can force checks to run after tool execution and write the results back into the context; `Stop` hooks intervene when the agent declares completion. This separates "the one doing the work" from "the one checking the work." [Anthropic explicitly observed in its harness article](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) that agents "confidently praised their work," so hooks inject **deterministic** checks instead of trusting the model's self-evaluation.++**3. Subagents (context isolation).** Each subagent's conversation history is stored in a separate sidechain file and **does not inflate the parent agent's context** (see the [VILA Lab analysis](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). This combines "task boundaries" with "context isolation": splitting a task also isolates context pollution.++## Observability and Session Persistence++Claude Code's logs are complete append-oriented records (history.jsonl). Together with explicit commands such as `/compact`, `/clear`, and `/init`, this lets you manage context state proactively instead of passively waiting for it to fill up. `/init` even turns "initialize before the agent starts each task" (Lecture 6) into a command. The [official documentation](https://code.claude.com/docs/en/memory) says it automatically analyzes the codebase and generates an initial CLAUDE.md containing build commands, test instructions, and engineering conventions.++## Mapping to the Course Framework++| Subsystem | Claude Code's Implementation | Assessment |+| --- | --- | --- |+| Instructions | Layered scopes (organization/user/project/local) + auto memory | Layered memory is the benchmark implementation |+| Tools | Four extension types: Skills + MCP + hooks + subagents | Clear separation of responsibilities is a core strength |+| Environment | In-project settings + settings.json | Relies on users to describe the environment in CLAUDE.md |+| State | Append-oriented session storage + five-layer compaction + resume/fork | Extremely strong; a reference implementation for long-running task continuity |+| Feedback | Permission classifier + mandatory checks through PostToolUse hooks | Turns "prevent premature declarations of completion" into a deterministic mechanism |++## Designs Worth Adopting++1. **Layer instructions by scope** instead of piling them into a single file. Directory-level CLAUDE.md files are an elegant implementation of "load close to where instructions apply."+2. **Compaction should be a staged funnel**: lossless before lossy; do not start by summarizing everything.+3. **Use hooks for deterministic checks**: preventing premature declarations of completion requires runtime enforcement, not pleas in prompts.+4. **Isolate subagent context**: split the context when splitting a task so subtask results do not pollute the main loop.+5. **Make session storage append-oriented and replayable**: handoffs depend on the storage layer, not memory.++## References (Original Sources / Source Code)++Every claim can be traced back to the original sources or source code below, avoiding secondhand recollections:++- **Claude Code · Memory**: A fresh context for every session, the four CLAUDE.md scopes, on-demand loading by subdirectory, auto memory (200 lines / 25KB), and `/init` generation of CLAUDE.md.<br/>https://code.claude.com/docs/en/memory+- **Claude Code · Skills / MCP / Hooks / Sub-agents**: Definitions of the four extension mechanisms and their events (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab, Dive into Claude Code** (source-level analysis): The five-layer compaction pipeline, seven permission modes + ML classifier, sidechain subagents, and append-oriented session storage in history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic, Effective harnesses for long-running agents**: The source for the claims that "reliability comes from the harness rather than the model," that agents "confidently praised their work," and that hooks should be used for verification.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack Guide** (community guide to the CLAUDE.md / Skills / MCP / Subagents / Hooks layers): Supplementary reading on the separation of responsibilities among extension mechanisms.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Related lectures: [Lecture 3 · Why the Repository Must Become the System of Record](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Lecture 9 · Why Agents Declare Victory Too Early](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Lecture 10 · Why End-to-End Testing Changes Results](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/en/harness-designs/codex/index.md b/docs/en/harness-designs/codex/index.mdnew file mode 100644index 0000000..fce8a44--- /dev/null+++ b/docs/en/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Breaking Down Codex's Harness Design++OpenAI's [Codex](https://openai.com/index/harness-engineering/) may be the product most deeply tied to "harness fundamentals" among these four. The article that named the entire field, Harness Engineering, was itself a summary of the OpenAI team's experience building a product with Codex. Breaking down Codex's harness design therefore largely means examining the engineering practices behind that article.++Codex's philosophy can be summarized in one sentence: **the repository is the system of record, AGENTS.md is only a directory page, and engineering value lies in designing environments, expressing intent, and building feedback loops.**++## In One Sentence++The OpenAI team used Codex to deliver a product that ultimately grew to more than a million lines of code in a matter of weeks, and **every line of code was written by Codex** (see the "Designing for growth" section of [Harness Engineering](https://openai.com/index/harness-engineering/)). Their experience answers a question: how should a system be organized when the engineer's role shifts from "writing code" to "designing the harness"? Codex CLI itself is an open-source monolithic binary implemented in Rust ([github.com/openai/codex](https://github.com/openai/codex)), but its primary contribution to harness design lies in **conventions** and **context engineering**, not flashy extension points.++## Instruction Subsystem: AGENTS.md Is a Directory Page, Not an Encyclopedia++This is Codex's most influential contribution to harness theory:++> A single giant instruction file is difficult to check mechanically for coverage, freshness, ownership, and cross-links, so drift is inevitable. We therefore stopped treating AGENTS.md as an encyclopedia and began treating it as a **directory page**. Codebase knowledge lives in structured documentation, and AGENTS.md points to it.++(The passage above is a direct paraphrase of the "AGENTS.md should be a directory page" section in [Harness Engineering](https://openai.com/index/harness-engineering/).)++Lecture 4 says that "one giant instruction file fails," and Codex provides the direct answer: keep AGENTS.md to roughly 100 lines (the original recommends about 100 lines and moving content to `docs/` as it approaches the limit). If it does not fit, split it into the `docs/` directory and let the agent read files on demand. This is the authoritative source for "give the map, not the manual."++The accompanying principle is to **enforce invariants, not micromanage implementation** (in the original: "don't micromanage the implementation; focus on invariants"). AGENTS.md should contain only inviolable constraints and verification commands, leaving the implementation details to the model. This maps directly to Lecture 2's "constraints rather than micromanagement."++## Context Subsystem: Write-Select-Compress-Isolate++Codex's context engineering can be summarized as four strategies. This framework was developed by the community after "context engineering" emerged as a distinct discipline and then mapped back onto Codex (see [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) for the framework):++- **Write**: Persist context outside the window—write conclusions into documentation and state into files instead of leaving them in the conversation. This corresponds to "the repository as the system of record."+- **Select**: Pull only the necessary tokens into the window—let AGENTS.md point the way and read files on demand instead of loading the whole repository.+- **Compress**: Preserve what truly matters—Codex supports automatic compaction and manual `/compact`, with a customizable `compact_prompt` (see [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate**: Divide context across different boundaries—use subagents to isolate the context of different tasks, so a frontend subagent never sees the backend database schema.++Codex also has a fine-grained environment-context design. Community source analysis in [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) shows that `build_environment_update_item` outputs only **changed fields** (CWD, git branch, file system) when the environment changes, rather than pasting the full system context into every turn. This is an engineering detail that avoids keeping duplicate tokens in the context.++## Tools and Boundaries: Worktree Isolation + Subagents++Codex has two core harness mechanisms:++**1. Environment isolation with git worktrees.** The "Environment" section of [Harness Engineering](https://openai.com/index/harness-engineering/) states that every task runs in an independent git worktree, paired with a local observability stack (logs, metrics, and traces), so every change can be verified in an isolated environment. This is the physical implementation of Lecture 7's "setting clear boundaries for every agent task": the boundary is enforced through environment isolation, not requested through instructions. Here, the environment subsystem becomes hard isolation.++**2. Core-level subagents.** Codex's `spawn_agent` / `wait_agent` are core tools: the model explicitly creates a subagent, gives it independent session history and a tool set, and waits for the result. Subagents inherit AGENTS.md instructions from their parent, but run in **their own context**. Configuration lives in `.codex/agents/*.toml`, where different models and instructions can be specified (for details, see the Sub-agents section of [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)). This is a direct implementation of "context isolation" and also embodies the spirit of Lecture 12 on handoffs: every subagent is a work unit with clear boundaries.++## Feedback Subsystem: Put Verification Commands in the Specification++One of the strongest emphases in OpenAI's practice is to list verification commands explicitly in AGENTS.md, making "how to confirm the work is correct" part of the repository. In the Codex engineering workflow, tests, CI, documentation, and observability configuration are all generated by Codex, and every one of them provides an "executable verification path." The answer to powerful but unreliable models is not to hope the model behaves responsibly; it is to make **verification paths a default component of the harness**.++Approval policies and plan mode provide feedback in the other direction: before high-risk operations execute, the system first produces a plan and requests approval, turning "task boundaries" and "human decision-making authority" into runtime controls.++## Mapping to the Course Framework++| Subsystem | Codex's Implementation | Assessment |+| --- | --- | --- |+| Instructions | AGENTS.md directory page + split docs/ + enforced invariants | Textbook-quality; defines "give the map, not the manual" |+| Tools | Worktree isolation + spawn_agent subagents | Strong boundaries enforced through environment isolation |+| Environment | Independent worktrees + observability stack | Worktree isolation is its signature feature |+| State | Write strategy (state written to files/documentation) | Relies on conventions rather than built-in memory |+| Feedback | Verification commands in the specification + approval policies + plan mode | Makes feedback paths the default; worth adopting |++The contrast between Codex and Claude Code is revealing. Claude Code uses "addition," putting memory, permissions, and subagents into the core. Codex uses "subtraction," keeping the core restrained and placing more responsibility on repository conventions and context engineering. This is why the community often says that "Codex's harness philosophy is more valuable than its code."++## Designs Worth Adopting++1. **Write AGENTS.md as a directory page**: Keep it to roughly 100 lines, point to details in docs/, and make it mechanically checkable.+2. **Specify only invariants; do not micromanage implementation**: Hard constraints + verification commands, with the rest left to the model.+3. **Use worktrees for environment isolation**: Enforce task boundaries through the environment, not through pleas in instructions.+4. **Send only environment-context deltas**: Output only changed fields on each turn instead of repeatedly pasting the full system context.+5. **Use subagents for context isolation**: Split the context along with the task so subtasks do not pollute the main loop.++## References (Original Sources / Source Code)++Every claim can be traced back to the original sources or source code below, avoiding secondhand recollections:++- **OpenAI, Harness Engineering**: The AGENTS.md directory page and roughly 100-line recommendation, enforce invariants / don't micromanage, worktree isolation + observability stack, verification commands in the specification, the million-line product case study, approval policies, and plan mode. The primary source for every core claim in this article.<br/>https://openai.com/index/harness-engineering/+- **OpenAI, AGENTS.md** (the standard for AGENTS.md as a cross-tool convention):<br/>https://openai.com/index/agents-md/+- **Codex CLI** (a monolithic binary implemented in Rust):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (community): The Write-Select-Compress-Isolate framework, `/compact` and `compact_prompt`, `spawn_agent` / `wait_agent` subagents, and `.codex/agents/*.toml` configuration.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (community source analysis): Implementation details such as incremental environment context from `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Related lectures: [Lecture 3 · Why the Repository Must Become the System of Record](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Lecture 4 · Why One Giant Instruction File Fails](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Lecture 7 · Why Agents Overreach and Under-Finish](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/en/harness-designs/deepseek/index.md b/docs/en/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..183ff94--- /dev/null+++ b/docs/en/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# Breaking Down DeepSeek Harness's Design++[DeepSeek Harness](https://deepseek.com/harness) (command name `dsh`, repository `deepseek-ai/deepseek-harness`) was released as a Developer Preview in August 2026. Its official definition is direct: **Agent = Model + Environment + Tools + State**—a four-part combination of model, environment, tools, and state.++If the previous three product breakdowns ask "how should a harness be designed," DeepSeek Harness asks a more radical question: **can a harness become a standalone runtime independent of a particular model?** Its answer is yes, and it takes this idea to the extreme. In the words of the [architecture documentation](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself*.++In this article, we examine three things in particular: the plugin-based core, capability seams, and the event pipeline, along with its strongest engineering constraint: "Model-visible means logged."++## In One Sentence++A traditional coding agent has the structure "LLM + fixed agent loop + fixed tool set." DeepSeek Harness has the structure "model + a plugin core (Cordis)." The core is responsible only for plugin loading, unloading, dependencies, and events, and **owns no concrete agent capabilities**. In the words of the [architecture documentation](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md), "There is no privileged core to patch" and "you extend dsh by mounting a plugin beside the others." This means that not even the agent loop itself is sacred or immutable: you can combine a DeepSeek model, Claude Code subagents, a remote sandbox, custom memory, a custom loop, and a custom UI into an entirely new agent.++This is the most thorough implementation of the course's statement that "everything outside the model weights is the harness": if the harness is independent, make it an operating system of its own.++## Architectural Core 1: Capability Seam++DeepSeek Harness represents "capabilities" as Services, and divides nearly every capability into three layers:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Take the file system as an example: under `FS Service` are multiple Providers—Local FS, E2B FS, and Remote FS—all exposed upward through a consistent set of file tools. Shell, Subprocess, Sandbox, Web, LLM, and SubAgent follow the same structure. This three-layer structure is not our own summary. The [architecture documentation · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) says: *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool*.++This resolves a longstanding question in harness engineering: **should an agent depend on "concrete tools" or on "capability interfaces"?** DeepSeek Harness chooses the latter. In terms of the course, this means the "tool subsystem" is standardized as an interface. Switching Providers leaves the tool surface exposed to the model unchanged while completely replacing the environment underneath.++## Architectural Core 2: Event Pipeline++DeepSeek Harness is not built around a simple "LLM → tool → LLM" flow. Internally, it uses an event pipeline in which every stage is an event point that plugins can observe:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(The pipeline above is adapted from the [architecture documentation · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): `turn/*`, `step/*`, `user/message`, `assistant/*`, and `tool/*` are persistent session events, while `agent/pre-step`, `agent/request`, `llm/stream`, and `tools/*` are extension points that plugins can observe.)++The greatest benefit of this design is that **many features do not require modifying the agent loop itself**. Want to run a security check before a tool executes? Listen to `tools/pre-execute`. Want to add memory? Inject it at `agent/pre-step`. Want to record behavior? Subscribe to session events. Want to modify the model request? Hook into `agent/request`. Want to decide whether reasoning should continue? Listen to `agent/turn-stopping`.++Compared with Lecture 11, "making agent execution observable," DeepSeek Harness goes further: instead of merely "adding logs," it turns **every step of the loop into an event point**, allowing observability, permissions, memory, and policy to attach to the loop as listeners instead of being hard-coded into it.++## Architectural Core 3: Session Event Log and "Model-visible means logged"++DeepSeek Harness has an **append-only Session Event Log** and establishes a powerful engineering constraint. The [architecture documentation · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) states:++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Anything visible to the model must be logged. Anything that enters a model request must be reconstructable from the log, and a runtime invariant enforces this rule.)++In other words, observability is not logging added after the fact; it is a first-principles constraint of the harness. Anything that enters the model context should be logged by default. This directly echoes the closing lecture's point that "observability belongs inside the harness" and turns the append-only storage design into a principle: logs are appended, never overwritten, and session state can be replayed.++## Mapping to the Course Framework++| Subsystem | DeepSeek Harness's Implementation | Assessment |+| --- | --- | --- |+| Instructions | Plugin-based; rules/skills are injected as plugins | Extremely flexible, but lacks a built-in convention like CLAUDE.md |+| Tools | Service Definition → Provider → Consumer capability seam | Tool subsystem standardization taken to the extreme |+| Environment | Sandbox/FS/Shell Providers are all replaceable (including remote E2B) | The environment is fully pluggable |+| State | Append-only Session Event Log + Model-visible means logged | Observability is a first-principles constraint |+| Feedback | Permission / guard / policy / hook at tools/pre-execute | Feedback mechanisms are event-based |++The fundamental difference between DeepSeek Harness and the other three products is that Pi, Claude Code, and Codex all optimize the harness "inside a specific agent," while DeepSeek Harness defines the harness as an **operating system independent of the model**, with the agent itself merely a replaceable application running on that OS. The tradeoff is equally clear: greater flexibility means higher configuration cost, an inherent downside of the "harness as OS" design (the Developer Preview is also positioned as an early look at mechanisms that are still evolving).++## Designs Worth Adopting++1. **Turn every step of the loop into an event point**: Attach permissions, memory, policies, and logs to the loop as listeners instead of hard-coding them into the loop.+2. **Standardize capability seams**: Depend on "capability interfaces" instead of "concrete tools," allowing the environment to be replaced wholesale without changing the tool surface visible to the model.+3. **Model-visible means logged**: Anything visible to the model must be logged, turning observability from a "nice-to-have" into a "first-principles constraint."+4. **Append-only session logs**: Replayable state and reliable handoffs provide an engineering guarantee that "every session leaves behind clean state."++## References (Original Sources / Source Code)++Every claim can be traced back to the original sources or source code below, avoiding secondhand recollections:++- **DeepSeek Harness**: The product definition "Agent = Model + Environment + Tools + State," Developer Preview positioning, and the `dsh` command.<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness** (command `dsh`, MIT license):<br/>https://github.com/deepseek-ai/deepseek-harness+- **architecture.md**: The central source for this article—"Every part of the product is a plugin," "There is no privileged core to patch," the Turn flow event pipeline, the three roles of Capability seams, "Model-visible means logged" and its runtime invariant, the append-only Session Event Log, and capability seams such as fs/tools/telemetry and the `ctx.*` subsystems.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **Supporting architecture documentation**: An introduction to the Cordis core (plugins contribute services, typed events, reversible effects), capability seam details, and the Session subsystem.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Related lectures: [Lecture 11 · Why Observability Belongs Inside the Harness](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Lecture 12 · Why Every Session Must Leave a Clean State](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Lecture 2 · What a Harness Actually Is](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/en/harness-designs/index.md b/docs/en/harness-designs/index.mdnew file mode 100644index 0000000..c2fb9d1--- /dev/null+++ b/docs/en/harness-designs/index.md@@ -0,0 +1,29 @@+# Frontier Harness Design Breakdowns++This section takes the harness theory covered in the course lectures and compares it, product by product, with today's most advanced real-world products. For each product, we focus on just one question: **how is its harness designed?** In other words, we examine the engineering infrastructure surrounding the model: the five subsystems of instructions, tools, environment, state, and feedback, as well as core mechanisms such as context continuity, initialization, verification, observability, handoffs, and loops.++We deliberately do not discuss how strong the model's reasoning is, how high it scores on a particular benchmark, or broadly introduce "what this agent can do." Those are questions at the model and product layers. Here, we examine only the harness—everything outside the model weights.++## Why These Breakdowns Matter++The first lecture explains that strong model capabilities do not guarantee reliable execution. The same model can perform an order of magnitude differently in different harnesses. But while the lectures explain "what should be done," these products show "what leading teams actually do."++Each product represents an independent set of design decisions. Comparing them side by side reveals how different teams implement the same core mechanisms in entirely different ways:++- **Pi** builds its harness as a minimal core with programmable extensions, using a "minimal system prompt + on-demand loading" approach to context engineering.+- **Claude Code** builds its harness as a complete runtime environment: layered memory, five-layer compaction, permissions, hooks, and subagents.+- **Codex** takes the harness philosophy to its logical extreme: the repository is the system of record, AGENTS.md is only a directory page, and worktrees isolate environments.+- **DeepSeek Harness** defines the harness itself as a model-independent runtime: Everything is a Plugin.++## Articles++- [Breaking Down Pi's Harness Design](./pi/): A minimal core with programmable extensions that moves context engineering beyond the system prompt.+- [Breaking Down Claude Code's Harness Design](./claude-code/): Layered memory, five-layer compaction, permissions, and hooks—a complete agent runtime environment.+- [Breaking Down Codex's Harness Design](./codex/): The repository as the system of record, AGENTS.md as a directory page, environment isolation, and feedback loops.+- [Breaking Down DeepSeek Harness's Design](./deepseek/): Everything is a Plugin, including the agent loop itself.++## How to Read This Section++We recommend starting with the first few lectures—especially [Lecture 2: What a Harness Actually Is](../lectures/lecture-02-what-a-harness-actually-is/)—to establish the five-subsystem framework, then returning here to see how real products implement these mechanisms.++Each article ends with "Mapping to the Course Framework" and "Designs Worth Adopting" sections. These help you quickly translate product design choices back into course concepts so you can apply them directly to your own projects.diff --git a/docs/en/harness-designs/pi/index.md b/docs/en/harness-designs/pi/index.mdnew file mode 100644index 0000000..d399ab6--- /dev/null+++ b/docs/en/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Breaking Down Pi's Harness Design++[Pi](https://pi.dev/) (npm package `@earendil-works/pi-coding-agent`) describes itself as a "minimal agent harness." That phrase is worth unpacking: it does not call itself "the most powerful coding agent" or "the best AI programming tool." Instead, it anchors its identity firmly in the word **harness**.++In this article, we use the course's five-subsystem framework—instructions, tools, environment, state, and feedback—to examine Pi and identify how its design philosophy differs fundamentally from Claude Code and Codex. Here is the answer up front: **Pi's philosophy is "minimize the core + make extensions programmable." It moves context engineering beyond the system prompt and lets users—even Pi itself—modify the harness, instead of having Pi decide the harness for you.**++## In One Sentence++Pi is a minimal core: its official positioning deliberately keeps the core small and returns control to you. In the words of the [pi.dev homepage](https://pi.dev/), "Ask Pi to build what you want, or install a package that does it your way." It divides the harness into four customizable layers:++- **Extensions**: TypeScript hooks attached to Pi lifecycle events, providing a programmable surface at the runtime level.+- **Skills**: On-demand capability packages containing instructions and tools, using progressive disclosure.+- **Prompt templates**: Reusable Markdown prompts that expand when you enter `/name`.+- **Themes**: The appearance of the TUI.++This layered approach is itself a form of harness design: **rules and extensions fully determine what the model can see and when it can see it, instead of those decisions being hard-coded into the core.**++## Core Loop++Like every coding agent, Pi is fundamentally a while loop of "reasoning → tool execution → observation → more reasoning." What matters is not the loop itself, but how Pi handles the layer around it: it expands context management from "compaction" inside the loop to "control" outside the loop.++Pi's runtime exposes a programmable interface. In addition to an interactive TUI, the [Programmatic Usage section of the source README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) supports scriptable print/JSON modes, an RPC protocol, and SDK embedding. This means the same harness can be driven one step at a time by a human or automatically by CI/CD or another program. It provides the prerequisite for moving "from manual control to automated loops" described in Lecture 13 on loop engineering: a harness that can only be driven interactively by humans can never enter an automated loop.++## Instruction Subsystem: AGENTS.md and SYSTEM.md++Pi is restrained in how it handles instructions, but its hierarchy is clear:++- **AGENTS.md**: The [Project Context Files section of the source README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) explicitly documents the loading order: global `~/.pi/agent/AGENTS.md` → traverse parent directories upward level by level → current-directory `./AGENTS.md` (with CLAUDE.md compatibility as well). This puts "the repository as the system of record" into practice—instructions are files, not reminders typed into a chat box.+- **SYSTEM.md**: The [official pi.dev documentation](https://pi.dev/docs/usage/project-context) says the default system prompt can be replaced or appended to per project. This is Pi's only official entry point for modifying the "system prompt" and also serves as its "environment self-description" layer.++Pi officially emphasizes that its system prompt is **minimal**. This reflects an explicit tradeoff: the core does not pack in long lists of "if...then..." rules. Instead, it exposes extension points so rules appear as skills and extensions only when needed. This directly echoes Lecture 4, "Why One Giant Instruction File Fails"—Pi naturally avoids the giant-instruction-file problem through a "minimal core + split files + on-demand loading" approach.++## State and Context: Where Pi Is Most Granular++Pi's context engineering deserves special attention because it turns course concepts such as "context continuity" and "preventing context corruption" into concrete mechanisms:++**1. Programmable compaction.** As the context limit approaches, old messages are automatically summarized. The [official pi.dev documentation](https://pi.dev/docs/usage/sessions) explains that the compaction strategy itself is **customizable**: you can use extensions to implement topic-based compaction, code-aware summaries, or even use a different model for summarization. The source README also reveals details of the default mechanism: automatic compaction is triggered in two cases (recovery from context overflow / exceeding the retention threshold), the split point preserves approximately the most recent 20,000 tokens, and earlier messages are summarized into a "context handoff" and compacted incrementally in a chain. In other words, Pi treats "how to compact" not as a fixed constant, but as part of the harness.++**2. Dynamic context.** The [official pi.dev documentation](https://pi.dev/docs/usage/extensions) says extensions can inject messages before every reasoning turn, filter message history, implement RAG, and build long-term memory. This goes beyond "compact when the context is full": it lets you decide what enters the context window before it gets there. In terms of the course's goals of "making agent execution observable and debuggable" and "maintaining context continuity," Pi pushes both down into the extension surface.++**3. Session tree.** The [pi.dev homepage](https://pi.dev/) explicitly says "sessions are stored as trees"; `/tree` can return to any historical node and continue from there, with every branch stored in the same file. This addresses the cross-session context breaks repeatedly emphasized in the course—not by forcing summaries to bridge the gap, but through structured history replay. Branches can be exported as HTML or uploaded as a gist for sharing, which also provides observability.++## Tool Subsystem: Skills and Extensions++Pi's "tools" have two layers:++- **Skills**: The [Skills section of the source README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) defines these clearly as "self-contained capability packages that the agent loads on-demand." They contain instructions and tools and follow the Agent Skills standard. Progressive disclosure ensures that skill details enter the context only when triggered, **without blowing up the prompt cache**. This is harness design from a cost perspective: every extra token in the context has to be paid for on every inference. Loading skills on demand is another expression of "give the map, not the manual."+- **Extensions**: TypeScript hooks attached to built-in lifecycle events. The [Hooks section of the source README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) gives official examples: intercepting dangerous commands (a permission gate), checkpointing code state when switching tasks, protecting paths (for example, prohibiting writes to `.env`), modifying tool output before passing it to the model, and injecting messages from external sources (file watchers/Webhooks/CI) to wake the agent. These hook APIs are also exported from `@mariozechner/pi-coding-agent/hooks`. The community harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) further packages this hook surface into ready-made extensions such as skill-router, session-summary, extract-patterns, and telemetry.++Extensions are Pi's most important design decision: **instead of merely giving users a few toggles, Pi exposes the entire event surface inside the runtime.** Want to add memory? Inject it at `agent/pre-step`. Want to record behavior? Subscribe to session events. Want to modify a model request? Hook into `agent/request`. You can have Pi modify its own harness—this comes closer to the definition of a "programmable harness" than any set of configuration options.++## Feedback and Verification: Making "Learning" Part of the Harness++Pi itself does not include mandatory test gates (users must specify verification commands in AGENTS.md), but the community harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) uses extensions to structure the "feedback loop." The official README's Hooks section provides the foundation for similar mechanisms:++- **session-summary** (a pi-agent-harness extension): Maintains rolling `PROGRESS.md` entries—the course's state subsystem, used for progress tracking on long-running tasks.+- **extract-patterns** (a pi-agent-harness extension): Collects candidate lessons from sessions and records them in `LESSONS.md`—turning "leave a good handoff before every session ends" from a convention into a mechanism.+- **telemetry** (a pi-agent-harness extension): Records token usage, cost, and related metrics—observability.++The same community repository further demonstrates the pattern: `VISION.md` (goals), `PROGRESS.md` (progress), `LESSONS.md` (lessons), and `STANDARDS.md` (standards) are all Markdown files persisted across sessions. This is exactly the "repository as the system of record + progress files + handoff mechanism" pattern recommended by the course, made available out of the box through Pi's extension mechanism.++## Mapping to the Course Framework++Scoring Pi with the course's five subsystems (subjective, for comparison):++| Subsystem | Pi's Implementation | Assessment |+| --- | --- | --- |+| Instructions | Hierarchical AGENTS.md loading + SYSTEM.md | Clear hierarchy, but users must write the rules themselves |+| Tools | On-demand skills + full-lifecycle extension hooks | Extremely strong; turns the tool system into a programmable surface |+| Environment | SYSTEM.md for environment self-description; users declare the runtime environment in AGENTS.md | The mechanism is open, but reproducibility depends on user-written descriptions |+| State | Session tree + customizable compaction + PROGRESS.md | Extremely strong; cross-session continuity and recoverability are central |+| Feedback | User-defined verification commands; structured session-summary / extract-patterns mechanisms | The mechanism is provided; users supply the content |++Pi's tradeoffs stand in sharp contrast to Claude Code and Codex. Claude Code puts "memory, permissions, and subagents" into the core for an out-of-the-box experience; Codex makes "repository conventions and environment isolation" the defaults. Pi chooses to **decide nothing for you**—it turns decisions into extension points. The cost is that you must either write extensions yourself or install packages written by others.++## Designs Worth Adopting++1. **Make the compaction strategy pluggable.** "How context is compacted" in your harness should not be a hard-coded parameter; it should be a replaceable strategy interface.+2. **Use a session tree instead of forced summaries.** Cross-session recovery does not have to rely on "the previous turn's summary"; structured history replay is often a more reliable state subsystem.+3. **Be prompt-cache friendly.** Load skills on demand instead of putting every rule into the system prompt at once. This is both context engineering and cost engineering.+4. **Let the agent modify its own harness.** If the harness exposes enough extension points, optimizing agent behavior itself can be partially automated by the agent.++## References (Original Sources / Source Code)++Every claim can be traced back to the original sources or source code below, avoiding secondhand recollections:++- **pi.dev**: The original positioning, "Ask Pi to build what you want, or install a package that does it your way"; the four customizable layers; and session trees ("sessions are stored as trees," `/tree`, single-file storage, HTML export / gist sharing).<br/>https://pi.dev/+- **pi.dev · Sessions**: Pluggable compaction (topic-based / code-aware / alternative summarization model), automatic compaction, and dynamic context injection mechanisms.<br/>https://pi.dev/docs/usage/sessions+- **pi.dev · Extensions**: Extensions can inject messages before each reasoning turn, filter history, perform RAG, and build long-term memory.<br/>https://pi.dev/docs/usage/extensions+- **pi.dev · Project Context**: The replace / append semantics of SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent README** (badlogic/pi-mono): The three-level AGENTS.md loading order (global → parent directories → current directory), `/compact` and the trigger conditions and 20,000-token split point for automatic compaction, on-demand Skills and the Agent Skills standard, the Hooks lifecycle and four official example uses, and Programmatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness**: The skill-router / session-summary / extract-patterns / telemetry extensions and the VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md file system.<br/>https://github.com/LabidySabidy/pi-agent-harness++Related lectures: [Lecture 2 · What a Harness Actually Is](../lectures/lecture-02-what-a-harness-actually-is/) | [Lecture 5 · Why Long-Running Tasks Lose Continuity](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Lecture 13 · From Manual Control to Automated Loops](../lectures/lecture-13-loop-engineering/)diff --git a/docs/en/index.md b/docs/en/index.mdindex bedfe73..bf9db6c 100644--- a/docs/en/index.md+++ b/docs/en/index.md@@ -25,6 +25,10 @@ Choose your learning path to get started. The course is divided into theoretical<h3>Resource Library</h3><p>Copy-ready templates (AGENTS.md, feature_list.json) to use in your own repositories.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Frontier Harness Design Breakdowns</h3>+ <p>How Pi, Claude Code, Codex, and DeepSeek actually design their harnesses—mapped to the course framework.</p>+ </a></div>## The Core Mechanism of a Harnessdiff --git a/docs/es/harness-designs/claude-code/index.md b/docs/es/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..b5b3a6b--- /dev/null+++ b/docs/es/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Análisis del diseño del harness de Claude Code++Anthropic afirma explícitamente en «[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)» que la fiabilidad procede del harness, no del modelo, y que el agent necesita restricciones «fuera del modelo». Claude Code es la materialización de esta idea, y la propia Anthropic lo clasifica directamente como un **agentic harness**. No es lenguaje de marketing: Claude Code quizá sea el harness con el análisis público más exhaustivo hasta la fecha. Su código fuente es público, los informes de investigación de la comunidad son detallados y casi todos los mecanismos esenciales de las lecciones —memoria por capas, compaction del contexto, permissions, hooks, subagents y persistencia de sessions— cuentan con una implementación completa como producto.++En este artículo analizamos Claude Code mediante el marco de cinco subsistemas del curso, prestando especial atención a cómo materializa conceptos fundamentales del harness como la «gestión del contexto», la «prevención de declaraciones prematuras de finalización» y las «restricciones deterministas».++## En una frase++El núcleo de Claude Code es un sencillo ciclo while: invocar el modelo, ejecutar herramientas, observar los resultados y volver a invocar el modelo. Sin embargo, **la inmensa mayoría del código no está en ese ciclo, sino en el sistema que lo rodea**: el sistema de permissions, la pipeline de compaction del contexto, los mecanismos de extensión, la orquestación de subagents y el almacenamiento de sessions. Esta es la esencia del harness: el ciclo es el esqueleto; todo lo que lo rodea determina la fiabilidad.++## Subsistema de instrucciones: un sistema de memoria por capas++El sistema de memoria de Claude Code es su contribución más directa a la teoría del harness y se corresponde con las lecciones «el repositorio como fuente de verdad» y «continuidad del contexto entre sessions». La documentación oficial, [How Claude remembers your project](https://code.claude.com/docs/en/memory), explica claramente que cada session empieza con una ventana de contexto nueva y que el conocimiento se transfiere entre sessions mediante dos mecanismos: los archivos CLAUDE.md —instrucciones escritas por ti— y auto memory —notas escritas por Claude—.++En cuanto al alcance, la documentación oficial divide los archivos CLAUDE.md en cuatro categorías, desde la más amplia hasta la más específica según el orden de carga:++- **Política de organización**: gestionada de forma centralizada por IT/DevOps —por ejemplo, `/etc/claude-code/CLAUDE.md`— para las normas de toda la empresa.+- **Nivel de usuario `~/.claude/CLAUDE.md`**: preferencias y reglas personales comunes a distintos proyectos.+- **Nivel de proyecto `./CLAUDE.md` o `./.claude/CLAUDE.md`**: fuente de verdad del proyecto —estructura de ingeniería, stack tecnológico y comandos de verificación— compartida con el repositorio.+- **Nivel local `./CLAUDE.local.md`**: preferencias personales dentro de un proyecto, normalmente incluidas en `.gitignore` y no enviadas al repositorio.++Además, existen otros dos mecanismos:++- **Carga bajo demanda por subdirectorio**: los CLAUDE.md de los subdirectorios no se cargan al arrancar, sino que entran en el contexto cuando Claude lee un archivo de ese directorio.+- **Auto memory**: Claude toma notas activamente a partir de tus correcciones y preferencias; se comparte por repositorio, funciona entre worktree y cada session carga como máximo las primeras 200 líneas o 25 KB.++Estos cuatro alcances forman una **jerarquía de instrucciones**: la documentación oficial explica que «las instrucciones más específicas entran más tarde en el contexto» —las instrucciones del proyecto aparecen después de las del usuario—. Su valor reside en no obligar al modelo a procesar un enorme archivo de instrucciones al comienzo de cada conversación, sino cargar la información cercana según su alcance. Es la respuesta de producto a la cuarta lección, «Por qué falla un único archivo de instrucciones gigante».++## Subsistema de contexto: pipeline de compaction de cinco niveles++Claude Code gestiona el contexto mediante una **pipeline de compaction de cinco niveles** (five-layer compaction pipeline), no con un simple «resumen cuando se llena». Este detalle arquitectónico procede del análisis del código fuente de [Dive into Claude Code, de VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). La quinta lección explica que «las tareas largas pierden continuidad»; Claude Code responde mediante un embudo de varios niveles: primero aplica poda sin pérdida —elimina resultados redundantes de herramientas—, después realiza una extracción estructurada y solo al final recurre a un resumen con pérdida mediante un LLM, acompañado de un mecanismo de circuit breaker que evita una compaction excesiva.++Esto se combina con el diseño del almacenamiento de sessions: **almacenamiento de sessions orientado a append (append-oriented storage)**. Todo el historial se añade a `history.jsonl`, y `/resume` permite recuperarlo y crear ramas mediante fork. Así se garantiza «preparar el handoff antes de que termine cada session», no gracias a una buena memoria, sino porque la capa de almacenamiento es append-only y reproducible.++## Subsistema de herramientas: cuatro mecanismos de extensión++Claude Code divide la superficie de extensión en cuatro categorías, cada una destinada a un tipo de problema. Es una de las partes de su diseño que más merece la pena adoptar:++- **Skills**: la [documentación oficial](https://code.claude.com/docs/en/skills) las define como conocimiento procedimental descrito por `SKILL.md`, cargado automáticamente mediante palabras de activación y progressive disclosure. Son adecuadas para el conocimiento especializado sobre «cómo hacer algo».+- **MCP**: el protocolo JSON-RPC de la [documentación oficial](https://code.claude.com/docs/en/mcp) conecta sistemas externos; es la interfaz estándar que permite que «las manos del modelo alcancen el mundo exterior».+- **Hooks**: la [documentación oficial](https://code.claude.com/docs/en/hooks) los define como scripts deterministas conectados a eventos del ciclo de vida como `PreToolUse`, `PostToolUse` y `Stop`.+- **Plugins / Subagents**: la [documentación oficial](https://code.claude.com/docs/en/sub-agents) permite delegar tareas complejas en agents especializados.++La decisión esencial es la **separación de responsabilidades**: CLAUDE.md gestiona «qué es», las Skills «cómo hacerlo», MCP «a qué conectarse» y los Hooks «cuándo imponerlo». Si un equipo mezcla estas capas —por ejemplo, escribe en CLAUDE.md aquello que debería hacer MCP—, aparece la fuga de contexto descrita en el curso.++## Retroalimentación y verificación: restricciones deterministas + división del trabajo humano-agent++La décima lección explica que «solo completar el flujo de extremo a extremo constituye una verificación real». Claude Code implementa un mecanismo de doble vía:++**1. Sistema de permissions (restricciones deterministas).** Las permissions de Claude Code no consisten en «preguntarlo todo», sino en siete modos y un clasificador basado en ML: las operaciones de bajo riesgo se permiten, mientras que las de alto riesgo se consultan o rechazan según la política —consulta los detalles arquitectónicos en el [análisis de VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)—. Así, «definir claramente los límites del agent» —séptima lección— se convierte en una imposición del runtime en vez de una petición escrita en el prompt.++**2. Hooks (prevención de declaraciones prematuras de finalización).** Un hook `PostToolUse` puede ejecutar comprobaciones obligatorias tras usar una herramienta y escribir el resultado en el contexto; un hook `Stop` interviene cuando el agent declara que ha terminado. Así se separa «quien trabaja» de «quien comprueba»: [Anthropic observó explícitamente en su artículo sobre harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) que los agents elogiaban con seguridad su propio trabajo —«confidently praised their work»—, por lo que los hooks inyectan comprobaciones **deterministas** en lugar de confiar en la autoevaluación del modelo.++**3. Subagents (aislamiento del contexto).** El historial de conversación de cada subagent se guarda en un archivo sidechain independiente y **no amplía el contexto del agent padre** —consulta el [análisis de VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)—. Es la combinación de «límites de la tarea» y «aislamiento del contexto»: al mismo tiempo que se divide la tarea, también se aísla la contaminación del contexto.++## Observabilidad y persistencia de sessions++Los logs de Claude Code son registros completos append-only en history.jsonl. Junto con comandos explícitos como `/compact`, `/clear` y `/init`, permiten gestionar activamente el estado del contexto en vez de esperar pasivamente a que se llene. `/init` convierte «inicializar el agent antes de cada trabajo» —sexta lección— en un comando: según la [documentación oficial](https://code.claude.com/docs/en/memory), analiza automáticamente el codebase y genera un CLAUDE.md inicial con comandos de build, instrucciones de testing y convenciones de ingeniería.++## Correspondencia con el marco del curso++| 子系统 | Claude Code 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 作用域分层(组织/用户/项目/本地)+ 自动记忆 | 分层记忆是标杆实现 |+| 工具 | 技能 + MCP + 钩子 + 子智能体四类扩展 | 职责划分清晰,是核心亮点 |+| 环境 | 项目内设置 + settings.json | 靠用户在 CLAUDE.md 里自描述 |+| 状态 | 追加式会话存储 + 五层压缩 + resume/fork | 极强,长任务连续性的参考实现 |+| 反馈 | 权限分类器 + PostToolUse 钩子强制检查 | 把"防提前宣告完成"变成确定性机制 |++## Diseños que merece la pena adoptar++1. **Organizar las instrucciones por alcance** en lugar de amontonarlas en un único archivo. Los CLAUDE.md por directorio son una implementación elegante de «cargar desde el lugar más cercano».+2. **Usar un embudo de compaction por niveles**: primero sin pérdida y después con pérdida; no empezar resumiendo todo el texto.+3. **Usar hooks para comprobaciones deterministas**: evitar las declaraciones prematuras de finalización depende de una imposición del runtime, no de una petición en el prompt.+4. **Aislar el contexto de los subagents**: dividir el contexto al dividir la tarea para que los resultados de las subtareas no contaminen el ciclo principal.+5. **Almacenar las sessions mediante append + reproducción**: el handoff no depende de la memoria, sino de las garantías de la capa de almacenamiento.++## Fuentes de referencia (texto original / código fuente)++Todas las afirmaciones pueden rastrearse hasta los textos originales o el código fuente siguientes, evitando las descripciones basadas en impresiones:++- **Documentación oficial de Claude Code · Memory**: contexto nuevo en cada session, cuatro alcances de CLAUDE.md, carga bajo demanda por subdirectorio, auto memory —200 líneas / 25 KB— y generación de CLAUDE.md mediante `/init`.<br/>https://code.claude.com/docs/en/memory+- **Documentación oficial de Claude Code · Skills / MCP / Hooks / Sub-agents**: definición de los cuatro mecanismos de extensión y sus eventos —PreToolUse / PostToolUse / Stop—.<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab «Dive into Claude Code»** (informe de análisis del código fuente): pipeline de compaction de cinco niveles, siete modos de permissions + clasificador ML, subagents sidechain y almacenamiento append-only de sessions en history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic «Effective harnesses for long-running agents»**: fuente de las ideas de que «la fiabilidad procede del harness, no del modelo», que los agents elogian con seguridad su propio trabajo y que deben usarse hooks para la verificación.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Guía Claude Code Full Stack** (comunidad; capas CLAUDE.md / Skills / MCP / Subagents / Hooks): lectura complementaria sobre la separación de responsabilidades entre mecanismos de extensión.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Lecciones relacionadas: [Lección 03. Convierte el repositorio en la única fuente de verdad](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Lección 09. Evita que el agent declare la victoria demasiado pronto](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Lección 10. Solo el flujo completo constituye una verificación real](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/es/harness-designs/codex/index.md b/docs/es/harness-designs/codex/index.mdnew file mode 100644index 0000000..79dfcc4--- /dev/null+++ b/docs/es/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Análisis del diseño del harness de Codex++[Codex](https://openai.com/index/harness-engineering/) de OpenAI quizá sea, de estos cuatro productos, el más ligado a los principios fundamentales del harness: el artículo «Harness Engineering», que dio nombre a todo el campo, resume precisamente la experiencia del equipo de OpenAI al desarrollar un producto con Codex. Por eso, analizar el diseño del harness de Codex equivale en gran medida a analizar las prácticas de ingeniería que hay detrás de ese artículo.++La filosofía de Codex puede resumirse en una frase: **el repositorio es la fuente de verdad (repository as the system of record), AGENTS.md solo es una página de índice y el valor de la ingeniería reside en diseñar el entorno, expresar la intención y construir ciclos de retroalimentación.**++## En una frase++El equipo de OpenAI usó Codex para entregar en pocas semanas un producto que acabó superando el millón de líneas de código, y **Codex escribió cada una de ellas** —consulta la sección «Designing for growth» de [Harness Engineering](https://openai.com/index/harness-engineering/)—. Su experiencia responde a una pregunta: cuando el papel del ingeniero cambia de «escribir código» a «diseñar el harness», ¿cómo debe organizarse el sistema? Codex CLI es un binario monolítico open source implementado en Rust —[github.com/openai/codex](https://github.com/openai/codex)—, pero su contribución al harness reside principalmente en las **convenciones (convention)** y la **ingeniería de contexto**, no en puntos de extensión llamativos.++## Subsistema de instrucciones: AGENTS.md es una página de índice, no una enciclopedia++Esta es la decisión de diseño de Codex que más ha influido en la teoría del harness:++> Un único archivo de instrucciones gigante dificulta las comprobaciones mecánicas —cobertura, estado de actualización, propiedad y enlaces cruzados—, por lo que es inevitable que se aleje de la realidad. Dejamos de considerar AGENTS.md una enciclopedia y pasamos a tratarlo como una **página de índice**. El conocimiento del codebase reside en documentación estructurada y AGENTS.md apunta hacia ella.++(Lo anterior es una paráfrasis directa de la sección «AGENTS.md should be a directory page» del texto original [Harness Engineering](https://openai.com/index/harness-engineering/).)++La cuarta lección explica que «un único archivo de instrucciones gigante falla», y Codex ofrece una respuesta directa: mantener AGENTS.md en unas 100 líneas —el artículo original recomienda alrededor de 100; al acercarse al límite, dividirlo en `docs/`—, y trasladar lo que no quepa al directorio `docs/` para que el agent lo lea bajo demanda. Es la fuente autorizada de «dar un mapa, no un manual».++El principio complementario es **imponer invariantes sin microgestionar la implementación** —en el original: «don't micromanage the implementation; focus on invariants»—. AGENTS.md solo contiene restricciones estrictas que no pueden violarse y comandos de verificación; el modelo decide cómo implementar los detalles. Se corresponde directamente con «restringir, no microgestionar» de la segunda lección.++## Subsistema de contexto: Write-Select-Compress-Isolate++La ingeniería de contexto de Codex puede resumirse en cuatro estrategias. Es el marco que la comunidad articuló al consolidarse «context engineering» como disciplina y que posteriormente aplicó a Codex —consulta [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)—:++- **Write (escribir fuera)**: persistir el contexto fuera de la ventana; escribir las conclusiones en documentos y el estado en archivos, en vez de dejarlos en la conversación. Se corresponde con «el repositorio como fuente de verdad».+- **Select (seleccionar hacia dentro)**: introducir en la ventana solo los tokens necesarios; AGENTS.md indica el camino y los archivos se leen bajo demanda, en lugar de insertar todo el repositorio.+- **Compress (comprimir)**: conservar lo verdaderamente importante. Codex ofrece compaction automática y `/compact` manual, y permite personalizar `compact_prompt` —consulta [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)—.+- **Isolate (aislar)**: dividir el contexto según diferentes límites. Los subagents aíslan el contexto de distintas tareas; un subagent de frontend nunca ve el schema de la base de datos del backend.++Codex incluye además un diseño muy preciso para el contexto del entorno: el análisis del código fuente de la comunidad [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) muestra que `build_environment_update_item` solo emite los **campos modificados** —CWD, rama git y sistema de archivos— cuando cambia el entorno, en vez de pegar en cada ronda todo el contexto del sistema. Es un detalle de ingeniería que evita «alimentar el contexto con tokens repetidos».++## Herramientas y límites: aislamiento mediante worktree + subagents++Codex tiene dos mecanismos esenciales de harness:++**1. Aislamiento del entorno mediante git worktree.** La sección «Environment» del texto original [Harness Engineering](https://openai.com/index/harness-engineering/) explica que cada tarea se ejecuta en un git worktree independiente, acompañado de un stack local de observabilidad —logs, métricas y trazas—, para verificar cada cambio en un entorno aislado. Es la implementación física de «definir claramente los límites de cada tarea del agent» de la séptima lección: el límite no se establece mediante una petición en las instrucciones, sino que lo impone el aislamiento del entorno. El subsistema de entorno se convierte aquí en un aislamiento estricto.++**2. Subagents en el núcleo.** `spawn_agent` y `wait_agent` son herramientas del núcleo de Codex: el modelo crea explícitamente subagents, les asigna un historial de session y un conjunto de herramientas independientes, y espera sus resultados. Los subagents heredan las instrucciones AGENTS.md del padre, pero se ejecutan en **su propio contexto**. La configuración reside en `.codex/agents/*.toml` y puede indicar modelos e instrucciones distintos —consulta la sección Sub-agents de [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)—. Es una implementación directa del «aislamiento del contexto» y también del espíritu del «handoff» de la duodécima lección: cada subagent es una unidad de trabajo con límites claros.++## Subsistema de retroalimentación: comandos de verificación dentro de las normas++Una de las ideas más destacadas de la práctica de OpenAI es incluir explícitamente los comandos de verificación en AGENTS.md y convertir «cómo confirmar que está bien» en parte del repositorio. En el proceso de ingeniería de Codex, el testing, CI, la documentación y la configuración de observabilidad son generados por Codex y constituyen «rutas de verificación ejecutables». La respuesta a que los modelos capaces no sean fiables no consiste en esperar que el modelo actúe correctamente por voluntad propia, sino en hacer que **la ruta de verificación sea un componente predeterminado del harness**.++Las approval policies y plan mode llevan la retroalimentación en otra dirección: antes de ejecutar una operación de alto riesgo, se presenta un plan y se solicita aprobación, incorporando los «límites de la tarea» y el «poder de decisión humano» al control del runtime.++## Correspondencia con el marco del curso++| 子系统 | Codex 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 目录页 + docs/ 拆分 + 执行不变量 | 教科书级,定义了"给地图不给说明书" |+| 工具 | worktree 隔离 + spawn_agent 子智能体 | 边界靠环境硬隔离,很强 |+| 环境 | 独立 worktree + 可观测性栈 | worktree 隔离是其招牌 |+| 状态 | Write 策略(状态写进文件/文档) | 依赖约定而非内建记忆 |+| 反馈 | 验证命令入规范 + 审批策略 + plan mode | 反馈路径默认化,值得抄 |++La comparación entre Codex y Claude Code es interesante: Claude Code aplica la «adición», integrando en el núcleo memoria, permissions y subagents; Codex aplica la «sustracción», mantiene el núcleo lo más contenido posible y deposita más responsabilidad en las convenciones del repositorio y la ingeniería de contexto. Por eso la comunidad suele decir que «la filosofía del harness de Codex vale más que su código».++## Diseños que merece la pena adoptar++1. **Escribir AGENTS.md como página de índice**: mantenerlo en unas 100 líneas, apuntar a los detalles de docs/ y permitir comprobaciones mecánicas.+2. **Escribir solo invariantes, sin microgestionar la implementación**: restricciones estrictas + comandos de verificación; dejar el resto al modelo.+3. **Usar worktree para aislar el entorno**: imponer los límites de la tarea mediante el entorno, no mediante peticiones en las instrucciones.+4. **Transmitir solo los cambios del contexto del entorno**: emitir en cada ronda únicamente los campos modificados, sin pegar repetidamente todo el contexto del sistema.+5. **Usar subagents para aislar el contexto**: dividir el contexto al dividir la tarea para que las subtareas no contaminen el ciclo principal.++## Fuentes de referencia (texto original / código fuente)++Todas las afirmaciones pueden rastrearse hasta los textos originales o el código fuente siguientes, evitando las descripciones basadas en impresiones:++- **OpenAI «Harness Engineering»**: página de índice AGENTS.md y recomendación de unas 100 líneas, executive invariants / don't micromanage, aislamiento mediante worktree + stack de observabilidad, comandos de verificación dentro de las normas, caso del producto de más de un millón de líneas, approval policies y plan mode. Es la fuente principal de todas las afirmaciones esenciales de este artículo.<br/>https://openai.com/index/harness-engineering/+- **Especificación oficial de OpenAI «AGENTS.md»** (AGENTS.md como estándar de convenciones entre herramientas):<br/>https://openai.com/index/agents-md/+- **Repositorio open source de Codex CLI** (binario monolítico implementado en Rust):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (comunidad): marco Write-Select-Compress-Isolate, `/compact` y `compact_prompt`, subagents `spawn_agent` / `wait_agent` y configuración `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (análisis comunitario del código fuente): detalles de implementación como el contexto incremental del entorno en `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Lecciones relacionadas: [Lección 03. Convierte el repositorio en la única fuente de verdad](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Lección 04. Divide las instrucciones entre archivos](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Lección 07. Define claramente los límites de cada tarea del agent](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/es/harness-designs/deepseek/index.md b/docs/es/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..1ded1d4--- /dev/null+++ b/docs/es/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# Análisis del diseño de DeepSeek Harness++[DeepSeek Harness](https://deepseek.com/harness) —comando `dsh`, repositorio `deepseek-ai/deepseek-harness`— se publicó en agosto de 2026 como Developer Preview. Su definición oficial es directa: **Agent = Model + Environment + Tools + State**; cuatro componentes: modelo, entorno, herramientas y estado.++Si al analizar los tres productos anteriores nos preguntábamos «cómo debería diseñarse un harness», DeepSeek Harness plantea una cuestión más radical: **¿puede el harness independizarse de un modelo concreto y convertirse en un runtime autónomo?** Su respuesta es afirmativa y lleva la idea hasta el extremo. En palabras de la [documentación de arquitectura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* —cada parte del producto es un plugin, incluidos el adaptador del modelo, el registro de herramientas, el log de session e incluso el propio ciclo del agent—.++En este artículo lo analizamos centrándonos en tres elementos: el núcleo basado en plugins, los capability seams, la pipeline de eventos y la potente restricción de ingeniería «Model-visible means logged».++## En una frase++La estructura de un coding agent tradicional es «LLM + ciclo fijo del agent + conjunto fijo de herramientas». DeepSeek Harness se estructura como «modelo + un núcleo de plugins —Cordis—». El núcleo solo se ocupa de cargar y descargar plugins, gestionar sus dependencias y proporcionar el mecanismo de eventos; **no posee ninguna capacidad específica del agent**. Como explica la [documentación de arquitectura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): «There is no privileged core to patch» —no existe un núcleo privilegiado que deba parchearse— y «you extend dsh by mounting a plugin beside the others» —dsh se amplía montando un plugin junto a los demás, sin modificar el núcleo—. Esto significa que ni siquiera el propio ciclo del agent es sagrado e inmutable: puedes usar el modelo de DeepSeek, conectar los subagents de Claude Code, añadir un sandbox remoto, escribir memoria personalizada, sustituir el ciclo y la UI, y combinarlos en un agent completamente nuevo.++Es la aplicación más radical de la frase del curso «todo lo que queda fuera de los pesos del modelo es harness»: si el harness es independiente, hagamos de él un sistema operativo independiente.++## Núcleo arquitectónico 1: capability seam++DeepSeek Harness representa las «capacidades» mediante Services y divide casi todas ellas en tres capas:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Por ejemplo, debajo de `FS Service` hay varios Providers —Local FS, E2B FS y Remote FS— que se exponen de forma uniforme hacia arriba como file tools. Shell, Subprocess, Sandbox, Web, LLM y SubAgent siguen la misma estructura. Esta organización en tres capas no es una interpretación nuestra: el texto original de [Capability seams, en la documentación de arquitectura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md), dice que *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* —un capability seam es una capacidad reemplazable con tres roles: Service Definition declara la interfaz, Service Provider la implementa y Consumer la utiliza, normalmente como una herramienta expuesta al modelo—.++Esto resuelve una cuestión persistente de la ingeniería de harness: **¿debe el agent depender de una «herramienta concreta» o de una «interfaz de capacidades»?** DeepSeek Harness elige la segunda. Desde la perspectiva del curso, significa estandarizar el «subsistema de herramientas» como interfaz: al cambiar un Provider, la herramienta que ve el modelo conserva su forma, pero el entorno cambia por completo.++## Núcleo arquitectónico 2: pipeline de eventos++DeepSeek Harness no funciona internamente mediante un simple «LLM → herramienta → LLM», sino mediante una pipeline de eventos en la que cada etapa constituye un punto de eventos que los plugins pueden escuchar:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(La pipeline anterior es una transcripción de la sección [Turn flow de la documentación de arquitectura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): `turn/*`, `step/*`, `user/message`, `assistant/*` y `tool/*` son eventos persistentes de session; `agent/pre-step`, `agent/request`, `llm/stream` y `tools/*` son puntos de extensión que pueden escuchar los plugins.)++La principal ventaja del diseño es que **muchas funciones no requieren modificar en absoluto el ciclo del agent**. ¿Quieres hacer una comprobación de seguridad antes de ejecutar una herramienta? Escucha `tools/pre-execute`. ¿Quieres añadir memoria? Inyéctala en `agent/pre-step`. ¿Quieres registrar el comportamiento? Suscríbete a los eventos de session. ¿Quieres modificar la solicitud al modelo? Conecta un hook a `agent/request`. ¿Quieres decidir si continuar el razonamiento? Escucha `agent/turn-stopping`.++Comparado con «hacer observable el proceso de ejecución del agent» de la undécima lección, DeepSeek Harness va más lejos: no «añade logs», sino que convierte **cada paso del ciclo en un punto de eventos**, de modo que observabilidad, permissions, memoria y políticas se conectan al ciclo como listeners, en lugar de quedar codificadas rígidamente dentro de él.++## Núcleo arquitectónico 3: Session Event Log y «Model-visible means logged»++DeepSeek Harness incluye un **Session Event Log append-only** y establece una restricción de ingeniería muy fuerte. En palabras de [Session log, en la documentación de arquitectura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md):++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Todo lo que puede ver el modelo debe registrarse. Cualquier elemento que llegue a una solicitud al modelo debe poder reconstruirse desde el log, y un invariante del runtime lo impone.)++En otras palabras, la observabilidad no es un log añadido a posteriori, sino una restricción fundamental del harness: todo lo que entra en el contexto del modelo debe dejar un log de forma predeterminada. Esto enlaza directamente con «la observabilidad pertenece al interior del harness» de la última noche y convierte el diseño de almacenamiento append-only en un principio: el log solo añade y nunca sobrescribe, por lo que el estado de la session puede reproducirse.++## Correspondencia con el marco del curso++| 子系统 | DeepSeek Harness 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 插件化;规则/技能均以插件形态注入 | 极自由,但没有内置的"CLAUDE.md"式惯例 |+| 工具 | Service Definition → Provider → Consumer 能力接缝 | 工具子系统标准化的极致 |+| 环境 | 沙箱/FS/Shell 全部可换 Provider(含远程 E2B) | 环境彻底可插拔 |+| 状态 | append-only Session Event Log + Model-visible means logged | 可观测性是第一性约束 |+| 反馈 | tools/pre-execute 上的 permission / guard / policy / hook | 反馈机制事件化 |++La diferencia fundamental entre DeepSeek Harness y los otros tres productos es que Pi, Claude Code y Codex optimizan el harness dentro de «un agent concreto», mientras que DeepSeek Harness define el harness como un **sistema operativo independiente del modelo** y trata al propio agent como una aplicación reemplazable que se ejecuta sobre ese OS. El coste también es evidente: una mayor libertad implica un mayor coste de configuración, la otra cara inherente al diseño «harness como OS» —en la etapa de Developer Preview, su posicionamiento también es «probar pronto mientras los mecanismos siguen evolucionando»—.++## Diseños que merece la pena adoptar++1. **Convertir cada paso del ciclo en un punto de eventos**: conectar permissions, memoria, políticas y logs al ciclo como listeners, en vez de codificarlos rígidamente dentro de él.+2. **Estandarizar los capability seams**: depender de una «interfaz de capacidades», no de una «herramienta concreta», para poder reemplazar todo el entorno sin afectar a la superficie de herramientas que ve el modelo.+3. **Model-visible means logged**: registrar todo lo que puede ver el modelo y convertir la observabilidad de «mejora opcional» en «restricción fundamental».+4. **Log de session append-only**: permitir la reproducción del estado y un handoff fiable; es la garantía de ingeniería de «dejar un estado limpio al terminar cada session».++## Fuentes de referencia (texto original / código fuente)++Todas las afirmaciones pueden rastrearse hasta los textos originales o el código fuente siguientes, evitando las descripciones basadas en impresiones:++- **Sitio web de DeepSeek Harness**: definición del producto «Agent = Model + Environment + Tools + State», estado de Developer Preview y comando `dsh`.<br/>https://deepseek.com/harness+- **Repositorio deepseek-ai/deepseek-harness** (comando `dsh`, licencia MIT):<br/>https://github.com/deepseek-ai/deepseek-harness+- **Documento de arquitectura architecture.md**: fuente principal de este artículo: «Every part of the product is a plugin», «There is no privileged core to patch», pipeline de eventos Turn flow, tres roles de los capability seams, «Model-visible means logged» y el invariante del runtime, Session Event Log append-only, capability seams como fs/tools/telemetry y subsistemas `ctx.*`.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **Documentos complementarios de arquitectura**: introducción al núcleo Cordis —plugins contribute services, typed events, reversible effects—, detalles de los capability seams y subsistema Session.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Lecciones relacionadas: [Lección 11. Incorpora la observabilidad al harness](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Lección 12. Deja listo el handoff antes de terminar cada session](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Lección 02. Qué es realmente un harness](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/es/harness-designs/index.md b/docs/es/harness-designs/index.mdnew file mode 100644index 0000000..47fac96--- /dev/null+++ b/docs/es/harness-designs/index.md@@ -0,0 +1,29 @@+# Análisis de los harness más avanzados++Esta sección contrasta, uno por uno, la teoría sobre harness explicada en las lecciones con productos reales de vanguardia. En cada producto solo nos interesa una cosa: **cómo está diseñado su harness**; es decir, la capa de infraestructura de ingeniería que rodea al modelo: los cinco subsistemas de instrucciones, herramientas, entorno, estado y retroalimentación, junto con mecanismos esenciales como la continuidad del contexto, la inicialización, la verificación, la observabilidad, el handoff y los ciclos.++Deliberadamente no hablamos de si el modelo razona mejor o peor, de si obtiene una puntuación alta en un benchmark concreto ni presentamos de forma genérica «qué puede hacer este agent». Esas son cuestiones de la capa del modelo y de la capa del producto. Aquí solo analizamos el harness: todo lo que queda fuera de los pesos del modelo.++## Por qué merece la pena analizarlos++La primera lección ya lo explicó: un modelo capaz no garantiza una ejecución fiable. El mismo modelo, dentro de harness distintos, puede mostrar diferencias de rendimiento de un orden de magnitud. Pero las lecciones explican «cómo debería hacerse»; estos productos responden «cómo lo hacen realmente los equipos líderes».++Cada producto constituye un conjunto independiente de decisiones de diseño. Al compararlos, verás cómo distintos equipos implementan de maneras completamente diferentes los mismos mecanismos esenciales:++- **Pi** convierte el harness en un núcleo minimalista con extensiones programables y aplica ingeniería de contexto mediante «un system prompt mínimo + carga bajo demanda».+- **Claude Code** convierte el harness en un entorno de ejecución completo: memoria por capas, compaction de cinco niveles, permissions, hooks y subagents.+- **Codex** lleva al extremo la filosofía del harness: el repositorio es la fuente de verdad, AGENTS.md es solo una página de índice y el entorno se aísla mediante worktree.+- **DeepSeek Harness** define directamente el propio harness como un runtime independiente del modelo: Everything is a Plugin.++## Lista de artículos++- [Análisis del diseño del harness de Pi](./pi/): núcleo minimalista y extensiones programables que llevan la ingeniería de contexto más allá del system prompt.+- [Análisis del diseño del harness de Claude Code](./claude-code/): memoria por capas, compaction de cinco niveles, permissions y hooks en un entorno de ejecución completo para agents.+- [Análisis del diseño del harness de Codex](./codex/): el repositorio como fuente de verdad, AGENTS.md como página de índice, aislamiento del entorno y ciclos de retroalimentación.+- [Análisis del diseño de DeepSeek Harness](./deepseek/): Everything is a Plugin; hasta el propio ciclo del agent se convierte en un plugin reemplazable.++## Cómo leer esta sección++Recomendamos leer primero las lecciones iniciales, especialmente [Lección 02. Qué es realmente un harness](../lectures/lecture-02-what-a-harness-actually-is/), para familiarizarte con el marco de cinco subsistemas, y después volver aquí para ver cómo los productos reales implementan estos mecanismos.++Al final de cada artículo encontrarás las secciones «Correspondencia con el marco del curso» y «Diseños que merece la pena adoptar», que te ayudarán a traducir rápidamente el diseño del producto a los conceptos del curso y a incorporarlo directamente a tus proyectos.diff --git a/docs/es/harness-designs/pi/index.md b/docs/es/harness-designs/pi/index.mdnew file mode 100644index 0000000..868441c--- /dev/null+++ b/docs/es/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Análisis del diseño del harness de Pi++[Pi](https://pi.dev/) (paquete npm `@earendil-works/pi-coding-agent`) se define como «minimal agent harness»: un agent harness minimalista. Merece la pena detenerse en estas palabras: no afirma ser «el coding agent más potente» ni «la mejor herramienta de programación con IA», sino que fija su identidad precisamente en el término **harness**.++En este artículo usamos el marco de cinco subsistemas del curso —instrucciones, herramientas, entorno, estado y retroalimentación— para analizar Pi y entender en qué se diferencia fundamentalmente su filosofía de las de Claude Code y Codex. Adelantamos la conclusión: **la filosofía de Pi consiste en «minimizar el núcleo + hacer programables las extensiones», llevar la ingeniería de contexto más allá del system prompt y permitir que el usuario —o incluso el propio Pi— modifique el harness, en lugar de dejar que Pi decida el harness por ti.**++## En una frase++Pi es un núcleo minimalista: su definición oficial reduce deliberadamente el núcleo y te devuelve el poder de decisión. En palabras de la [página principal de pi.dev](https://pi.dev/): «Ask Pi to build what you want, or install a package that does it your way». Divide el harness en cuatro capas personalizables:++- **Extensions**: hooks de TypeScript conectados a los eventos del ciclo de vida de Pi; constituyen la superficie programable del runtime.+- **Skills**: paquetes de capacidades cargados bajo demanda, con instrucciones y herramientas, mediante progressive disclosure.+- **Prompt templates**: prompts reutilizables en Markdown que se despliegan al escribir `/name`.+- **Themes**: la apariencia de la TUI.++Esta organización por capas es en sí misma un diseño de harness: **las reglas y extensiones deciden por completo «qué puede ver el modelo y cuándo puede verlo», en vez de codificarlo de forma rígida en el núcleo.**++## El ciclo esencial++Como todos los coding agents, Pi es esencialmente un ciclo while de «razonamiento → ejecución de herramientas → observación → nuevo razonamiento». Lo interesante no es el ciclo en sí, sino cómo trata Pi su capa exterior: amplía la gestión del contexto desde la «compaction» dentro del ciclo hasta el «control» fuera de él.++El runtime de Pi expone una interfaz programable. El apartado [Programmatic Usage del README del código fuente](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) ofrece, además de una TUI interactiva, modos programables de impresión y JSON, un protocolo RPC y la integración mediante SDK. Esto permite que un mismo harness sea dirigido paso a paso por una persona o automáticamente por CI/CD u otro programa. Es el requisito previo de «pasar de la conducción manual al ciclo automatizado» de la lección trece: si un harness solo puede ser dirigido mediante interacción humana, nunca podrá entrar en un ciclo automático.++## Subsistema de instrucciones: AGENTS.md y SYSTEM.md++Pi trata las «instrucciones» con moderación, pero con una jerarquía clara:++- **AGENTS.md**: el apartado [Project Context Files del README del código fuente](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) especifica claramente el orden de carga: `~/.pi/agent/AGENTS.md` global → recorrido ascendente por los directorios padre → `./AGENTS.md` del directorio actual (también es compatible con CLAUDE.md). Así se materializa «el repositorio como fuente de verdad»: las instrucciones son archivos, no recordatorios en el chat.+- **SYSTEM.md**: la [documentación oficial de pi.dev](https://pi.dev/docs/usage/project-context) indica que el system prompt predeterminado puede reemplazarse o ampliarse por proyecto. Esta es la única vía formal que ofrece Pi para modificar el «system prompt», y también su capa de «autodescripción del entorno».++Pi subraya que su propio system prompt es **minimalista**. Detrás hay una decisión explícita: el núcleo no se llena con extensas reglas de «si… entonces…», sino que deja puntos de extensión para que las reglas aparezcan como Skills y Extensions solo cuando sean necesarias. Esto enlaza directamente con la cuarta lección, «Por qué falla un único archivo de instrucciones gigante»: Pi evita de forma natural ese problema mediante «núcleo minimalista + archivos separados + carga bajo demanda».++## Estado y contexto: donde Pi llega más lejos++La ingeniería de contexto de Pi merece especial atención porque convierte conceptos del curso como «continuidad del contexto» y «prevención de la corrupción del contexto» en mecanismos concretos:++**1. Compaction programable.** Cuando se aproxima al límite del contexto, resume automáticamente los mensajes antiguos. La [documentación oficial de pi.dev](https://pi.dev/docs/usage/sessions) explica que la propia estrategia de compaction es **personalizable**: una extensión puede implementar compaction por temas, resúmenes sensibles al código o incluso usar otro modelo para resumir. El README del código fuente también muestra detalles del mecanismo predeterminado: la compaction automática se activa en dos situaciones —recuperación tras desbordamiento del contexto o superación del umbral de conservación—, el punto de corte mantiene aproximadamente los 20 000 tokens más recientes y los mensajes anteriores se resumen como un «context handoff» mediante compaction encadenada por niveles. Pi no considera «cómo hacer compaction» una constante inmutable, sino una parte del harness.++**2. Contexto dinámico (Dynamic context).** La [documentación oficial de pi.dev](https://pi.dev/docs/usage/extensions) explica que las extensiones pueden inyectar mensajes antes de cada ronda de razonamiento, filtrar el historial, implementar RAG y construir memoria a largo plazo. Esto va más allá de «esperar a que el contexto se llene para hacer compaction»: permite decidir qué entra y qué no entra antes de que el contexto llegue a la ventana. En relación con «hacer observable y depurable la ejecución del agent» y «mantener la continuidad del contexto», Pi traslada ambos mecanismos a la superficie de extensiones.++**3. Árbol de sessions (Session tree).** La [página principal de pi.dev](https://pi.dev/) afirma explícitamente que «sessions are stored as trees»: `/tree` permite volver a cualquier nodo histórico y continuar desde él, y todas las ramas se guardan en un único archivo. Así se resuelve el problema, repetido a lo largo del curso, de la «ruptura del contexto entre sessions»: no mediante la unión forzada de resúmenes, sino mediante la reproducción de un historial estructurado. Las ramas se pueden exportar a HTML o subir como gist para compartirlas, lo que también aporta observabilidad.++## Subsistema de herramientas: Skills y Extensions++Las «herramientas» de Pi se dividen en dos capas:++- **Skills**: el apartado [Skills del README del código fuente](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) las define con precisión como «self-contained capability packages that the agent loads on-demand»: paquetes autónomos de capacidades, con instrucciones y herramientas, que siguen el estándar Agent Skills. Mediante progressive disclosure, los detalles de la Skill solo entran en el contexto cuando se activa, **sin saturar la prompt cache**. Es un diseño de harness orientado al coste: cada token adicional del contexto se paga en cada inferencia; cargar las Skills bajo demanda es otra forma de «dar un mapa, no un manual».+- **Extensions**: hooks de TypeScript conectados a los eventos integrados del ciclo de vida. El apartado [Hooks del README del código fuente](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) ofrece cuatro usos oficiales de ejemplo: interceptar comandos peligrosos mediante permissions gates, crear un checkpoint del estado del código al cambiar de tarea, proteger rutas —por ejemplo, prohibir escribir en `.env`—, modificar la salida de una herramienta antes de entregarla al modelo e inyectar mensajes desde el exterior —mediante vigilancia de archivos, Webhook o CI— para despertar al agent. Estas API de hooks también se exportan desde `@mariozechner/pi-coding-agent/hooks`. El harness de la comunidad [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) lleva esta superficie aún más lejos y ofrece extensiones listas para usar como skill-router, session-summary, extract-patterns y telemetry.++Las Extensions son la decisión de diseño más importante de Pi: **no se limita a «dar al usuario unos cuantos interruptores», sino que expone toda la superficie de eventos internos del runtime.** ¿Quieres añadir memoria? Inyéctala en `agent/pre-step`. ¿Quieres registrar el comportamiento? Suscríbete a los eventos de session. ¿Quieres modificar la solicitud al modelo? Conecta un hook a `agent/request`. Puedes hacer que Pi modifique su propio harness, algo más cercano a la definición de «harness programable» que cualquier conjunto de opciones de configuración.++## Retroalimentación y verificación: convertir también el «aprendizaje» en harness++Pi no incluye de serie un control de pruebas obligatorio —el usuario debe escribir los comandos de verificación en AGENTS.md—, pero el harness de la comunidad [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) usa Extensions para estructurar el «ciclo de retroalimentación», y el apartado Hooks del README oficial aporta mecanismos similares:++- **session-summary** (extensión de pi-agent-harness): mantiene entradas continuas en `PROGRESS.md`; es el subsistema de estado del curso aplicado al seguimiento del progreso de tareas largas.+- **extract-patterns** (extensión de pi-agent-harness): recopila posibles lecciones aprendidas de las sessions y las consolida en `LESSONS.md`; convierte «dejar listo el handoff antes de que termine cada session» de una convención en un mecanismo.+- **telemetry** (extensión de pi-agent-harness): registra el uso de tokens, el coste y otros datos; es observabilidad.++El mismo repositorio comunitario lleva aún más lejos este patrón: `VISION.md` —objetivo—, `PROGRESS.md` —progreso—, `LESSONS.md` —experiencia— y `STANDARDS.md` —estándares— son archivos Markdown persistentes entre sessions. Es exactamente el patrón recomendado por el curso de «repositorio como fuente de verdad + archivo de progreso + mecanismo de handoff», convertido en una capa lista para usar gracias al sistema de Extensions de Pi.++## Correspondencia con el marco del curso++Evaluación de Pi según los cinco subsistemas del curso —subjetiva y pensada para la comparación—:++| 子系统 | Pi 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 分级加载 + SYSTEM.md | 层级清晰,但规则本身要靠用户写 |+| 工具 | 技能按需加载 + 扩展全生命周期钩子 | 极强,把工具系统做成了可编程面 |+| 环境 | SYSTEM.md 做环境自描述;运行时环境靠用户在 AGENTS.md 里声明 | 机制是开放的,但可复现性依赖用户自述 |+| 状态 | 会话树 + 压缩可定制 + PROGRESS.md | 极强,跨会话与可恢复性是其核心 |+| 反馈 | 验证命令靠用户定义;session-summary / extract-patterns 机制化 | 机制提供,内容靠用户 |++La elección de Pi contrasta claramente con Claude Code y Codex: Claude Code integra en el núcleo la «memoria, permissions y subagents» para que funcionen de inmediato; Codex convierte las «convenciones del repositorio y el aislamiento del entorno» en valores predeterminados; Pi opta por **no decidir nada por ti** y convierte cada decisión en un punto de extensión. El precio es que tendrás que escribir tus propias Extensions o instalar paquetes creados por otros.++## Diseños que merece la pena adoptar++1. **Hacer conectable la estrategia de compaction.** En tu harness, «cómo se compacta el contexto» no debería ser un parámetro rígido, sino una interfaz de estrategia reemplazable.+2. **Usar un árbol de sessions en lugar de resúmenes forzados.** La recuperación entre sessions no siempre tiene que depender de «un resumen de la ronda anterior»; reproducir un historial estructurado suele constituir un subsistema de estado más fiable.+3. **Ser compatible con la prompt cache.** Carga las Skills bajo demanda y no introduzcas todas las reglas a la vez en el system prompt: es ingeniería de contexto y también ingeniería de costes.+4. **Permitir que el agent modifique su propio harness.** Si la superficie de extensión del harness es suficientemente abierta, el propio agent puede semi-automatizar la optimización de su comportamiento.++## Fuentes de referencia (texto original / código fuente)++Todas las afirmaciones pueden rastrearse hasta los textos originales o el código fuente siguientes, evitando las descripciones basadas en impresiones:++- **Sitio web de pi.dev**: definición original «Ask Pi to build what you want, or install a package that does it your way», cuatro capas personalizables y árbol de sessions —«sessions are stored as trees», `/tree`, guardado en un solo archivo, exportación a HTML y uso compartido mediante gist—.<br/>https://pi.dev/+- **Documentación oficial de pi.dev · Sessions**: compaction conectable —por temas, sensible al código o con otro modelo de resumen— y descripción del mecanismo de compaction automática e inyección de contexto dinámico.<br/>https://pi.dev/docs/usage/sessions+- **Documentación oficial de pi.dev · Extensions**: las Extensions pueden inyectar mensajes antes de cada ronda de razonamiento, filtrar el historial, implementar RAG y construir memoria a largo plazo.<br/>https://pi.dev/docs/usage/extensions+- **Documentación oficial de pi.dev · Project Context**: semántica de replace y append de SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **README del código fuente de Pi Coding Agent** (badlogic/pi-mono): orden de carga de tres niveles de AGENTS.md —global → directorio padre → directorio actual—, condiciones que activan `/compact` y la compaction automática, punto de corte de 20 000 tokens, carga bajo demanda de Skills y estándar Agent Skills, ciclo de vida de Hooks y cuatro usos oficiales de ejemplo, y Programmatic Usage —JSON / RPC / SDK—.<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **Repositorio comunitario pi-agent-harness**: Extensions skill-router, session-summary, extract-patterns y telemetry; sistema de archivos VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++Lecciones relacionadas: [Lección 02. Qué es realmente un harness](../lectures/lecture-02-what-a-harness-actually-is/) | [Lección 05. Mantén vivo el contexto entre sesiones](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Lección 13. De la conducción manual al ciclo automatizado](../lectures/lecture-13-loop-engineering/)diff --git a/docs/es/index.md b/docs/es/index.mdindex 7356675..e849b92 100644--- a/docs/es/index.md+++ b/docs/es/index.md@@ -25,6 +25,10 @@ Elige tu ruta de aprendizaje. El curso se divide en clases teóricas, proyectos<h3>Biblioteca de recursos</h3><p>Plantillas listas para copiar, como AGENTS.md y feature_list.json, para tus propios repositorios.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Análisis de los harness más avanzados</h3>+ <p>Cómo Pi, Claude Code, Codex y DeepSeek diseñan realmente sus harness, vinculado al marco del curso.</p>+ </a></div>## El mecanismo central de un harnessdiff --git a/docs/fr/harness-designs/claude-code/index.md b/docs/fr/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..c53751c--- /dev/null+++ b/docs/fr/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Décryptage de la conception du harness de Claude Code++Dans « [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) », Anthropic affirme clairement que la fiabilité vient du harness, et non du modèle, et que l’agent doit être contraint « en dehors du modèle ». Claude Code est la concrétisation de cette idée, qu’Anthropic classe d’ailleurs directement dans la catégorie des **agentic harnesses**. Il ne s’agit pas d’un argument marketing : Claude Code est peut-être aujourd’hui le harness le plus minutieusement documenté publiquement. Son code source est ouvert, les rapports de recherche communautaires sont détaillés et presque tous les mécanismes fondamentaux du cours — mémoire hiérarchisée, compaction du contexte, permissions, hooks, subagents et persistance des sessions — y sont devenus des fonctionnalités produit complètes.++Dans cet article, nous analysons Claude Code à travers les cinq sous-systèmes du cours, en nous intéressant particulièrement à la manière dont il concrétise les principes fondamentaux du harness : « gestion du contexte », « prévention des déclarations prématurées de réussite » et « contraintes déterministes ».++## Positionnement en une phrase++Le cœur de Claude Code est une simple boucle while : appeler le modèle, exécuter un outil, observer le résultat, puis rappeler le modèle. Mais **l’essentiel du code ne se trouve pas dans cette boucle ; il appartient aux systèmes qui l’entourent** : système de permissions, pipeline de compaction du contexte, mécanismes d’extension, orchestration des subagents et stockage des sessions. Voilà l’essence du harness : la boucle est le squelette, mais tout ce qui l’entoure détermine la fiabilité.++## Sous-système d’instructions : une mémoire hiérarchisée++Le système de mémoire de Claude Code constitue sa contribution la plus directe à la théorie du harness et correspond aux leçons « Faire du dépôt la source unique de vérité » et « Préserver la continuité du contexte entre sessions ». La documentation officielle [How Claude remembers your project](https://code.claude.com/docs/en/memory) précise que chaque session commence avec une fenêtre de contexte entièrement neuve et que les connaissances sont transmises d’une session à l’autre par deux mécanismes : les fichiers CLAUDE.md — vos instructions — et l’auto memory — les notes écrites par Claude.++La documentation distingue quatre portées de fichiers CLAUDE.md, chargées de la plus générale à la plus spécifique :++- **Politique d’organisation** : gérée centralement par l’IT/DevOps, par exemple dans `/etc/claude-code/CLAUDE.md`, pour les standards de l’entreprise.+- **Niveau utilisateur `~/.claude/CLAUDE.md`** : préférences et règles personnelles valables entre projets.+- **Niveau projet `./CLAUDE.md` ou `./.claude/CLAUDE.md`** : source de vérité du projet — structure, stack technique et commandes de vérification — partagée avec le dépôt.+- **Niveau local `./CLAUDE.local.md`** : préférences personnelles propres au projet, généralement ajoutées à `.gitignore` et non commitées.++Deux mécanismes s’y ajoutent :++- **Chargement à la demande au niveau des sous-répertoires** : les CLAUDE.md des sous-répertoires ne sont pas chargés au démarrage, mais entrent dans le contexte lorsque Claude lit un fichier de leur répertoire.+- **Auto memory** : Claude écrit activement des notes à partir de vos corrections et préférences ; elles sont partagées par dépôt, restent valables entre worktrees et sont chargées à hauteur de 200 lignes ou 25KB maximum par session.++Ces quatre portées forment une **hiérarchie d’instructions** : selon la documentation officielle, « les instructions les plus spécifiques entrent plus tard dans le contexte », les instructions du projet apparaissant après celles de l’utilisateur. L’intérêt est de ne pas forcer le modèle à digérer un immense fichier d’instructions au début de chaque conversation, mais de charger l’information au plus près de sa portée. C’est la réponse concrète de Claude Code à la Leçon 04 : « Pourquoi un fichier d’instructions géant échoue ».++## Sous-système de contexte : pipeline de compaction à cinq niveaux++Claude Code gère le contexte au moyen d’un **pipeline de compaction à cinq niveaux** (five-layer compaction pipeline), et non d’un simple « résumé quand la fenêtre est pleine ». Ce détail architectural provient du décryptage du code source publié par VILA Lab, [Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). Là où la Leçon 05 explique que « les tâches longues perdent leur continuité », Claude Code répond par un entonnoir à plusieurs niveaux : commencer par un élagage sans perte — suppression des résultats d’outils redondants —, poursuivre par une extraction structurée, et ne recourir qu’en dernier lieu à un résumé LLM avec perte, accompagné d’un circuit breaker contre la compaction excessive.++Cette approche est complétée par un **stockage de session orienté ajout (append-oriented storage)** : tout l’historique est ajouté à `history.jsonl`, avec reprise via `/resume` et création de branches par fork. Le handoff est ainsi préparé avant la fin de chaque session, non grâce à une bonne mémoire, mais parce que la couche de stockage est append-only et rejouable.++## Sous-système d’outils : quatre mécanismes d’extension++Claude Code sépare sa surface d’extension en quatre catégories, chacune répondant à un problème distinct. C’est l’une de ses conceptions les plus instructives :++- **Skills** : selon la [documentation officielle](https://code.claude.com/docs/en/skills), un `SKILL.md` décrit un savoir procédural, chargé automatiquement selon des mots déclencheurs et présenté progressivement. Il convient au savoir métier expliquant « comment faire ».+- **MCP** : le protocole JSON-RPC de la [documentation officielle](https://code.claude.com/docs/en/mcp) relie des systèmes externes ; c’est l’interface standard qui permet au modèle d’atteindre le monde extérieur.+- **Hooks** : la [documentation officielle](https://code.claude.com/docs/en/hooks) les définit comme des scripts déterministes attachés à des événements du cycle de vie tels que `PreToolUse`, `PostToolUse` et `Stop`.+- **Plugins / Subagents** : la [documentation officielle](https://code.claude.com/docs/en/sub-agents) confie les tâches complexes à des agents spécialisés.++La conception essentielle est la **séparation des responsabilités** : CLAUDE.md gère « ce qui est », les Skills « comment faire », MCP « à quoi se connecter » et les Hooks « quand imposer une règle ». Mélanger ces couches — par exemple décrire dans CLAUDE.md une tâche qui relève de MCP — provoque la fuite de contexte décrite dans le cours.++## Feedback et vérification : contraintes déterministes et partage humain-machine++La Leçon 10 explique que seule l’exécution du flux complet constitue une véritable vérification. Claude Code y répond par un dispositif à deux voies :++**1. Système de permissions (contraintes déterministes).** Les permissions de Claude Code ne consistent pas à « tout demander ». Elles comprennent sept modes et un classificateur fondé sur le ML : les opérations à faible risque sont autorisées, tandis que les opérations à haut risque sont soumises à la stratégie pour être demandées ou refusées — détails dans le [décryptage de VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). La délimitation des frontières de l’agent, objet de la Leçon 07, est ainsi imposée par le runtime et non sollicitée dans un prompt.++**2. Hooks (prévenir les déclarations prématurées de réussite).** Un hook `PostToolUse` peut forcer l’exécution de contrôles après un outil et réinjecter les résultats dans le contexte ; un hook `Stop` intervient lorsque l’agent annonce avoir terminé. Cela sépare « celui qui fait » de « celui qui vérifie ». [Anthropic observe explicitement dans son article sur les harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) que les agents « confidently praised their work » ; des hooks injectent donc des contrôles **déterministes**, au lieu de faire confiance à l’auto-évaluation du modèle.++**3. Subagents (isolation du contexte).** L’historique de conversation de chaque subagent est conservé dans un fichier sidechain indépendant et **ne gonfle pas le contexte du parent** — voir le [décryptage de VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). Les « frontières de tâche » sont ainsi associées à « l’isolation du contexte » : le découpage du travail isole aussi la pollution contextuelle.++## Observabilité et persistance des sessions++Les logs complets de Claude Code sont append-only (history.jsonl). Avec les commandes explicites `/compact`, `/clear` et `/init`, vous pouvez gérer activement l’état du contexte au lieu d’attendre passivement qu’il soit plein. `/init` transforme même en commande l’initialisation préalable de l’agent décrite dans la Leçon 06 : selon la [documentation officielle](https://code.claude.com/docs/en/memory), elle analyse automatiquement le codebase et génère un CLAUDE.md initial contenant commandes de build, instructions de test et conventions d’ingénierie.++## Correspondance avec le cadre du cours++| 子系统 | Claude Code 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 作用域分层(组织/用户/项目/本地)+ 自动记忆 | 分层记忆是标杆实现 |+| 工具 | 技能 + MCP + 钩子 + 子智能体四类扩展 | 职责划分清晰,是核心亮点 |+| 环境 | 项目内设置 + settings.json | 靠用户在 CLAUDE.md 里自描述 |+| 状态 | 追加式会话存储 + 五层压缩 + resume/fork | 极强,长任务连续性的参考实现 |+| 反馈 | 权限分类器 + PostToolUse 钩子强制检查 | 把"防提前宣告完成"变成确定性机制 |++## Conceptions à retenir++1. **Hiérarchiser les instructions par portée** au lieu de les entasser dans un fichier. Le CLAUDE.md au niveau du répertoire est une élégante mise en œuvre du « chargement au plus près ».+2. **Faire de la compaction un entonnoir progressif** : sans perte avant avec perte, sans commencer par résumer tout le contenu.+3. **Utiliser les hooks pour les contrôles déterministes** : empêcher les déclarations prématurées de réussite exige une contrainte du runtime, pas une supplique dans le prompt.+4. **Isoler le contexte des subagents** : découper à la fois les tâches et leur contexte pour ne pas polluer la boucle principale avec les résultats des sous-tâches.+5. **Adopter un stockage de session append-only et rejouable** : le handoff est garanti par la couche de stockage, pas par la mémoire.++## Sources de référence (texte original / code source)++Chaque affirmation peut être reliée aux textes originaux ou au code source ci-dessous, afin d’éviter toute reformulation fondée sur de simples impressions :++- **Claude Code 官方文档 · Memory** : nouveau contexte à chaque session, quatre portées de CLAUDE.md, chargement à la demande des sous-répertoires, auto memory — 200 lignes / 25KB — et génération de CLAUDE.md par `/init`.<br/>https://code.claude.com/docs/en/memory+- **Claude Code 官方文档 · Skills / MCP / Hooks / Sub-agents** : définition des quatre mécanismes d’extension et événements PreToolUse / PostToolUse / Stop.<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab《Dive into Claude Code》**(源码级拆解报告) : pipeline de compaction à cinq niveaux, sept modes de permissions avec classificateur ML, subagents sidechain et stockage de session append-only dans history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic《Effective harnesses for long-running agents》** : origine des idées selon lesquelles « la fiabilité vient du harness, et non du modèle », les agents vantent leur travail avec assurance et les hooks doivent assurer la vérification.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack 导读**(社区,CLAUDE.md / Skills / MCP / Subagents / Hooks 分层) : lecture complémentaire sur la séparation des responsabilités entre mécanismes d’extension.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Cours associés : [Leçon 03 · Faire du dépôt la source unique de vérité](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Leçon 09 · Empêcher l’agent d’annoncer prématurément sa réussite](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Leçon 10 · Seul le flux complet constitue une véritable vérification](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/fr/harness-designs/codex/index.md b/docs/fr/harness-designs/codex/index.mdnew file mode 100644index 0000000..4f4753f--- /dev/null+++ b/docs/fr/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Décryptage de la conception du harness de Codex++Le [Codex](https://openai.com/index/harness-engineering/) d’OpenAI est peut-être, parmi les quatre produits, celui qui adhère le plus profondément aux principes fondamentaux du harness. L’article « Harness Engineering », qui a donné son nom à tout le domaine, résume lui-même l’expérience acquise par l’équipe d’OpenAI en construisant un produit avec Codex. Décrypter le harness de Codex revient donc largement à analyser les pratiques d’ingénierie qui sous-tendent cet article.++La philosophie de Codex tient en une phrase : **le dépôt est la source de vérité (repository as the system of record), AGENTS.md n’est qu’une page d’index et la valeur de l’ingénierie réside dans la conception de l’environnement, l’expression de l’intention et la construction de boucles de feedback.**++## Positionnement en une phrase++En quelques semaines, l’équipe d’OpenAI a utilisé Codex pour livrer un produit comptant finalement plus d’un million de lignes de code, **toutes écrites par Codex** — voir la section « Designing for growth » de [Harness Engineering](https://openai.com/index/harness-engineering/). Cette expérience répond à une question : comment organiser un système lorsque le rôle de l’ingénieur passe de « l’écriture du code » à « la conception du harness » ? Codex CLI est lui-même un binaire monolithique open source écrit en Rust ([github.com/openai/codex](https://github.com/openai/codex)), mais sa principale contribution au harness porte sur les **conventions** et **l’ingénierie du contexte**, plutôt que sur des points d’extension sophistiqués.++## Sous-système d’instructions : AGENTS.md est une page d’index, pas une encyclopédie++Voici la contribution la plus influente de Codex à la théorie du harness :++> Un unique fichier d’instructions géant se prête mal aux contrôles mécaniques — couverture, fraîcheur, propriété et liens croisés — et finit inévitablement par s’écarter de la réalité. Nous avons donc cessé de considérer AGENTS.md comme une encyclopédie pour le traiter comme une **page d’index**. Les connaissances du codebase résident dans une documentation structurée, vers laquelle AGENTS.md renvoie.++(Le passage ci-dessus reformule directement la section « AGENTS.md should be a directory page » de l’article [Harness Engineering](https://openai.com/index/harness-engineering/).)++La Leçon 04 explique qu’un « fichier d’instructions géant échoue » ; Codex apporte une réponse directe : limiter AGENTS.md à environ 100 lignes — le texte original recommande approximativement 100 lignes et de déplacer le contenu vers `docs/` à l’approche de cette limite —, puis répartir le reste dans le répertoire `docs/` afin que l’agent le lise à la demande. C’est la source faisant autorité du principe « donner la carte, pas le manuel ».++Le principe associé consiste à **faire respecter les invariants sans micromanager l’implémentation** — dans le texte original : « don't micromanage the implementation;focus on invariants ». AGENTS.md ne doit contenir que les contraintes strictes à ne pas enfreindre et les commandes de vérification ; la manière d’implémenter reste à la discrétion du modèle. Cela correspond directement au principe « contraindre sans micromanager » de la Leçon 02.++## Sous-système de contexte : Write-Select-Compress-Isolate++L’ingénierie du contexte de Codex se résume en quatre stratégies. Ce cadre a été formulé par la communauté lorsque la « context engineering » est devenue une discipline autonome, puis appliqué à Codex — voir [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) :++- **Write (écrire à l’extérieur)** : persister le contexte hors de la fenêtre — conclusions dans la documentation, état dans des fichiers — au lieu de le laisser dans la conversation. C’est le principe du « dépôt comme source de vérité ».+- **Select (sélectionner ce qui entre)** : ne charger dans la fenêtre que les tokens nécessaires — AGENTS.md indique le chemin et les fichiers sont lus à la demande — au lieu d’y injecter tout le dépôt.+- **Compress (compacter)** : ne conserver que ce qui importe réellement. Codex dispose d’une compaction automatique et de la commande manuelle `/compact`, avec personnalisation possible de `compact_prompt` — voir [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/).+- **Isolate (isoler)** : répartir le contexte entre différentes frontières. Les subagents isolent le contexte des tâches ; un subagent frontend, par exemple, ne voit jamais le schema de la base de données du backend.++Codex possède aussi un détail subtil de conception du contexte environnemental. Selon l’analyse du code source [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals), `build_environment_update_item` ne produit que les **champs modifiés** — CWD, branche git et système de fichiers — lorsque l’environnement change, au lieu de recoller l’intégralité du contexte système à chaque tour. C’est un exemple concret de suppression des tokens répétitifs du contexte.++## Outils et frontières : isolation par worktree et subagents++Codex repose sur deux mécanismes fondamentaux de harness :++**1. Isolation de l’environnement par git worktree.** La section « Environment » de [Harness Engineering](https://openai.com/index/harness-engineering/) indique que chaque tâche s’exécute dans un git worktree indépendant, avec une stack d’observabilité locale — logs, métriques et traces —, afin de vérifier chaque changement dans un environnement isolé. C’est la mise en œuvre physique du principe « délimiter clairement chaque tâche de l’agent » de la Leçon 07 : la frontière n’est pas demandée dans une instruction, elle est imposée par l’isolation de l’environnement. Le sous-système d’environnement devient ici une séparation stricte.++**2. Subagents au niveau du noyau.** `spawn_agent` et `wait_agent` sont des outils natifs de Codex : le modèle crée explicitement un subagent, lui attribue un historique de session et un ensemble d’outils indépendants, puis attend son résultat. Le subagent hérite des instructions AGENTS.md de son parent, mais travaille dans **son propre contexte**. Sa configuration dans `.codex/agents/*.toml` peut préciser un modèle et des instructions différents — voir la section Sub-agents de [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/). Il s’agit d’une mise en œuvre directe de « l’isolation du contexte » et de l’esprit du handoff de la Leçon 12 : chaque subagent constitue une unité de travail aux frontières nettes.++## Sous-système de feedback : inscrire les commandes de vérification dans les conventions++La pratique d’OpenAI insiste avant tout sur l’inscription explicite des commandes de vérification dans AGENTS.md, afin que « la manière de confirmer que le travail est correct » fasse partie du dépôt. Dans le processus d’ingénierie de Codex, tests, CI, documentation et configuration de l’observabilité sont tous générés par Codex et constituent tous des « chemins de vérification exécutables ». La réponse à un modèle puissant mais peu fiable n’est pas d’espérer qu’il se discipline de lui-même, mais de faire du **chemin de vérification un composant par défaut du harness**.++Les approval policies et le plan mode apportent un autre type de feedback : produire d’abord un plan et demander une approbation avant d’exécuter une opération à haut risque inscrit les « frontières de la tâche » et le « pouvoir de décision humain » dans le contrôle du runtime.++## Correspondance avec le cadre du cours++| 子系统 | Codex 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 目录页 + docs/ 拆分 + 执行不变量 | 教科书级,定义了"给地图不给说明书" |+| 工具 | worktree 隔离 + spawn_agent 子智能体 | 边界靠环境硬隔离,很强 |+| 环境 | 独立 worktree + 可观测性栈 | worktree 隔离是其招牌 |+| 状态 | Write 策略(状态写进文件/文档) | 依赖约定而非内建记忆 |+| 反馈 | 验证命令入规范 + 审批策略 + plan mode | 反馈路径默认化,值得抄 |++La comparaison entre Codex et Claude Code est révélatrice : Claude Code procède par « addition », en intégrant au noyau mémoire, permissions et subagents ; Codex procède par « soustraction », en gardant un noyau aussi sobre que possible et en reportant davantage de responsabilités sur les conventions du dépôt et l’ingénierie du contexte. C’est pourquoi la communauté dit souvent que « la philosophie du harness de Codex vaut davantage que son code ».++## Conceptions à retenir++1. **Traiter AGENTS.md comme une page d’index** : le limiter à environ 100 lignes, pointer vers les détails dans docs/ et permettre des contrôles mécaniques.+2. **N’énoncer que les invariants, sans micromanager l’implémentation** : contraintes strictes et commandes de vérification, le reste revenant au modèle.+3. **Isoler l’environnement avec des worktrees** : imposer les frontières des tâches par l’environnement plutôt que les demander dans les instructions.+4. **Ne transmettre que les changements du contexte environnemental** : à chaque tour, ne produire que les champs modifiés, sans répéter tout le contexte système.+5. **Utiliser les subagents pour isoler le contexte** : séparer simultanément tâches et contexte afin que les sous-tâches ne polluent pas la boucle principale.++## Sources de référence (texte original / code source)++Chaque affirmation peut être reliée aux textes originaux ou au code source ci-dessous, afin d’éviter toute reformulation fondée sur de simples impressions :++- **OpenAI《Harness Engineering》** : AGENTS.md comme page d’index et recommandation d’environ 100 lignes, executive invariants / don't micromanage, isolation par worktree avec stack d’observabilité, commandes de vérification intégrées aux conventions, exemple du produit de plus d’un million de lignes, approval policies et plan mode. Source principale de toutes les affirmations essentielles de cet article.<br/>https://openai.com/index/harness-engineering/+- **OpenAI 官方《AGENTS.md》规范** (AGENTS.md comme convention standard entre outils) :<br/>https://openai.com/index/agents-md/+- **Codex CLI 开源仓库** (binaire monolithique écrit en Rust) :<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI**(社区) : cadre Write-Select-Compress-Isolate, `/compact` et `compact_prompt`, subagents `spawn_agent` / `wait_agent` et configuration `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals**(社区源码分析) : détails d’implémentation, dont le contexte environnemental incrémental de `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Cours associés : [Leçon 03 · Faire du dépôt la source unique de vérité](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Leçon 04 · Répartir les instructions entre plusieurs fichiers](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Leçon 07 · Délimiter clairement chaque tâche de l’agent](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/fr/harness-designs/deepseek/index.md b/docs/fr/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..5624afc--- /dev/null+++ b/docs/fr/harness-designs/deepseek/index.md@@ -0,0 +1,85 @@+# Décryptage de la conception de DeepSeek Harness++[DeepSeek Harness](https://deepseek.com/harness) (commande `dsh`, dépôt `deepseek-ai/deepseek-harness`) est sorti en août 2026 sous la forme d’une Developer Preview. Sa définition officielle va droit au but : **Agent = Model + Environment + Tools + State** — modèle, environnement, outils et état.++Si le décryptage des trois produits précédents demandait « comment concevoir un harness ? », DeepSeek Harness pose une question plus radicale : **un harness peut-il se détacher d’un modèle particulier pour devenir un runtime autonome ?** Sa réponse est oui, et il pousse cette idée jusqu’au bout. Selon les propres termes de la [documentation d’architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) : *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* (chaque partie du produit est un plugin, notamment l’adaptateur de modèle, le registre d’outils, le journal de session et la boucle de l’agent elle-même).++Dans cet article, nous nous concentrons sur trois aspects : le noyau fondé sur les plugins, les capability seams et l’event pipeline, ainsi que sur sa contrainte d’ingénierie la plus forte : « Model-visible means logged ».++## Positionnement en une phrase++Un coding agent traditionnel se compose d’un « LLM + une boucle d’agent fixe + un ensemble d’outils fixe ». DeepSeek Harness associe « un modèle + un noyau de plugins (Cordis) ». Ce noyau ne gère que le chargement et le déchargement des plugins, leurs dépendances et le mécanisme d’événements ; **il ne possède aucune capacité propre à un agent**. Selon les termes de la [documentation d’architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md), « There is no privileged core to patch » (il n’existe aucun noyau privilégié à patcher) et « you extend dsh by mounting a plugin beside the others » (pour étendre dsh, il suffit de monter un plugin aux côtés des autres, sans modifier le noyau). Cela signifie que même la boucle de l’agent n’est pas sacrée : vous pouvez utiliser le modèle de DeepSeek, y connecter les subagents de Claude Code, ajouter une sandbox distante, écrire une mémoire personnalisée, remplacer la boucle ou l’UI, et composer ainsi un agent entièrement nouveau.++C’est l’application la plus radicale de l’idée du cours selon laquelle « tout ce qui se trouve en dehors des poids du modèle relève du harness » : puisque le harness est indépendant, autant en faire un système d’exploitation autonome.++## Cœur de l’architecture 1 : Capability Seam++DeepSeek Harness représente une « capacité » par un Service et décompose presque toutes les capacités en trois couches :++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Prenons le système de fichiers : sous `FS Service` se trouvent plusieurs Providers — Local FS, E2B FS et Remote FS — qui exposent vers le haut une interface uniforme sous forme de file tools. Shell, Subprocess, Sandbox, Web, LLM et SubAgent suivent tous la même structure. Cette architecture à trois couches n’est pas notre interprétation : la section [Capability seams de la documentation d’architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) la définit ainsi : *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* (une capability seam est une capacité remplaçable qui réunit trois rôles : une Service Definition qui déclare l’interface, un Service Provider qui l’implémente et un Consumer qui l’utilise, généralement un outil exposé au modèle).++Cette approche résout une question ancienne de l’ingénierie des harnesses : **un agent doit-il dépendre d’un « outil concret » ou d’une « interface de capacité » ?** DeepSeek Harness choisit la seconde option. Dans le cadre du cours, cela signifie que le « sous-système d’outils » est standardisé sous forme d’interface : remplacer un Provider ne change pas ce que le modèle voit de l’outil, mais transforme entièrement l’environnement.++## Cœur de l’architecture 2 : Event Pipeline++Le fonctionnement interne de DeepSeek Harness n’est pas un simple enchaînement « LLM → outil → LLM », mais un event pipeline dont chaque étape constitue un point d’événement qu’un plugin peut écouter :++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(Le pipeline ci-dessus retranscrit la section [Turn flow de la documentation d’architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) : `turn/*`, `step/*`, `user/message`, `assistant/*` et `tool/*` sont des événements de session persistants ; `agent/pre-step`, `agent/request`, `llm/stream` et `tools/*` sont des points d’extension que les plugins peuvent écouter.)++Le principal avantage de cette conception est que **de nombreuses fonctionnalités ne nécessitent aucune modification de la boucle de l’agent**. Vous voulez effectuer un contrôle de sécurité avant l’exécution d’un outil ? Écoutez `tools/pre-execute`. Ajouter de la mémoire ? Injectez-la dans `agent/pre-step`. Enregistrer le comportement ? Abonnez-vous aux événements de session. Modifier la requête adressée au modèle ? Branchez un hook sur `agent/request`. Décider s’il faut poursuivre le raisonnement ? Écoutez `agent/turn-stopping`.++Par rapport à la Leçon 11, « Intégrer l’observabilité au cœur du harness », DeepSeek Harness va plus loin : il ne se contente pas « d’ajouter des logs », il transforme **chaque étape de la boucle en point d’événement**, ce qui permet à l’observabilité, aux permissions, à la mémoire et aux stratégies de se greffer sur la boucle comme des listeners au lieu d’y être codées en dur.++## Cœur de l’architecture 3 : Session Event Log et « Model-visible means logged »++DeepSeek Harness dispose d’un **Session Event Log append-only** et impose une contrainte d’ingénierie particulièrement forte. La section [Session log de la documentation d’architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) l’énonce ainsi :++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++Autrement dit, l’observabilité n’est pas un log ajouté après coup, mais une contrainte de premier principe du harness : tout élément entrant dans le contexte du modèle doit, par défaut, laisser une trace dans le log. Cela rejoint directement l’idée finale du cours selon laquelle « l’observabilité appartient au harness lui-même » et érige le stockage append-only en principe : les logs sont uniquement ajoutés, jamais écrasés, et l’état de la session peut être rejoué.++## Correspondance avec le cadre du cours++| 子系统 | DeepSeek Harness 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 插件化;规则/技能均以插件形态注入 | 极自由,但没有内置的"CLAUDE.md"式惯例 |+| 工具 | Service Definition → Provider → Consumer 能力接缝 | 工具子系统标准化的极致 |+| 环境 | 沙箱/FS/Shell 全部可换 Provider(含远程 E2B) | 环境彻底可插拔 |+| 状态 | append-only Session Event Log + Model-visible means logged | 可观测性是第一性约束 |+| 反馈 | tools/pre-execute 上的 permission / guard / policy / hook | 反馈机制事件化 |++La différence fondamentale entre DeepSeek Harness et les trois autres produits est la suivante : Pi, Claude Code et Codex optimisent tous le harness « à l’intérieur d’un agent particulier » ; DeepSeek Harness, lui, définit le harness comme un **système d’exploitation indépendant du modèle**, l’agent n’étant qu’une application remplaçable exécutée sur cet OS. Le compromis est évident : une plus grande liberté entraîne un coût de configuration plus élevé, revers inhérent à cette conception du « harness comme OS » (la Developer Preview se présente d’ailleurs comme une première expérimentation de mécanismes encore en évolution).++## Conceptions à retenir++1. **Transformer chaque étape de la boucle en point d’événement** : permissions, mémoire, stratégies et logs se greffent sur la boucle comme listeners au lieu d’y être codés en dur.+2. **Standardiser les capability seams** : dépendre d’une « interface de capacité » plutôt que d’un « outil concret » permet de remplacer l’environnement en bloc sans modifier l’interface d’outils visible par le modèle.+3. **Model-visible means logged** : tout ce que le modèle peut voir doit être enregistré, afin de faire de l’observabilité non plus un « bonus », mais une « contrainte de premier principe ».+4. **Journal de session append-only** : un état rejouable et des handoffs fiables garantissent techniquement que « chaque session laisse un état propre ».++## Sources de référence (texte original / code source)++Chaque affirmation peut être reliée aux textes originaux ou au code source ci-dessous, afin d’éviter toute reformulation fondée sur de simples impressions :++- **DeepSeek Harness 官网** : définition du produit « Agent = Model + Environment + Tools + State », positionnement Developer Preview et commande `dsh`.<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness 仓库** (commande `dsh`, licence MIT) :<br/>https://github.com/deepseek-ai/deepseek-harness+- **架构文档 architecture.md** : source principale de cet article — « Every part of the product is a plugin », « There is no privileged core to patch », event pipeline Turn flow, trois rôles des Capability seams, « Model-visible means logged » et son runtime invariant, Session Event Log append-only, capability seams fs/tools/telemetry et sous-systèmes `ctx.*`.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **架构文档 · 配套子文档** : présentation du noyau Cordis (plugins contribute services, typed events, reversible effects), détail des capability seams et sous-système Session.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Cours associés : [Leçon 11 · Intégrer l’observabilité au cœur du harness](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Leçon 12 · Laisser un état propre à la fin de chaque session](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Leçon 02 · Ce qu’est réellement un harness](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/fr/harness-designs/index.md b/docs/fr/harness-designs/index.mdnew file mode 100644index 0000000..526df89--- /dev/null+++ b/docs/fr/harness-designs/index.md@@ -0,0 +1,29 @@+# Décryptage des harnesses de pointe++Cette rubrique confronte, produit par produit, la théorie du harness présentée dans les cours aux produits réels les plus avancés du moment. Pour chacun, une seule question nous intéresse : **comment son harness est-il conçu ?** Autrement dit, comment est pensée la couche d’infrastructure d’ingénierie qui entoure le modèle : les cinq sous-systèmes d’instructions, d’outils, d’environnement, d’état et de feedback, ainsi que les mécanismes fondamentaux de continuité du contexte, d’initialisation, de vérification, d’observabilité, de handoff et de boucle.++Nous laissons volontairement de côté la puissance de raisonnement du modèle, ses scores à tel ou tel benchmark et les présentations générales de « ce que cet agent peut faire ». Ces questions relèvent de la couche modèle et de la couche produit. Ici, nous ne démontons que le harness : tout ce qui se trouve en dehors des poids du modèle.++## Pourquoi ce décryptage vaut la peine++La première leçon l’explique : un modèle puissant ne garantit pas une exécution fiable. Avec un même modèle, les performances peuvent varier d’un ordre de grandeur selon le harness. Mais les cours expliquent « ce qu’il faudrait faire », tandis que ces produits montrent « ce que font réellement les équipes de pointe ».++Chaque produit constitue un ensemble autonome de décisions de conception. En les comparant, on voit les mêmes mécanismes fondamentaux prendre des formes radicalement différentes selon les équipes :++- **Pi** conçoit son harness comme un noyau minimal assorti d’extensions programmables et pratique l’ingénierie du contexte à travers un « prompt système minimal + chargement à la demande ».+- **Claude Code** fait du harness un environnement d’exécution complet : mémoire hiérarchisée, compaction à cinq niveaux, permissions, hooks et subagents.+- **Codex** pousse la philosophie du harness à l’extrême : le dépôt est la source de vérité, AGENTS.md n’est qu’une page d’index et les environnements sont isolés par des worktrees.+- **DeepSeek Harness** définit tout simplement le harness comme un runtime indépendant du modèle : Everything is a Plugin.++## Liste des articles++- [Décryptage de la conception du harness de Pi](./pi/) : noyau minimal et extensions programmables, pour porter l’ingénierie du contexte au-delà du prompt système.+- [Décryptage de la conception du harness de Claude Code](./claude-code/) : mémoire hiérarchisée, compaction à cinq niveaux, permissions et hooks, réunis dans un environnement d’exécution complet pour agents.+- [Décryptage de la conception du harness de Codex](./codex/) : le dépôt comme source de vérité, AGENTS.md comme page d’index, isolation de l’environnement et boucles de feedback.+- [Décryptage de la conception de DeepSeek Harness](./deepseek/) : Everything is a Plugin, jusqu’à faire de la boucle de l’agent elle-même un plugin remplaçable.++## Comment lire cette rubrique++Nous vous conseillons de commencer par les premières leçons, en particulier la [Leçon 02 : Ce qu’est réellement un harness](../lectures/lecture-02-what-a-harness-actually-is/), afin d’assimiler le cadre des cinq sous-systèmes, puis de revenir ici pour voir comment des produits réels concrétisent ces mécanismes.++Chaque article se termine par deux sections, « Correspondance avec le cadre du cours » et « Conceptions à retenir », qui permettent de traduire rapidement les choix du produit dans les concepts du cours et de les réutiliser directement dans vos propres projets.diff --git a/docs/fr/harness-designs/pi/index.md b/docs/fr/harness-designs/pi/index.mdnew file mode 100644index 0000000..b5c8e3a--- /dev/null+++ b/docs/fr/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Décryptage de la conception du harness de Pi++[Pi](https://pi.dev/) (package npm `@earendil-works/pi-coding-agent`) se décrit comme un « minimal agent harness », un harness d’agent minimal. Cette formulation mérite d’être examinée : Pi ne se présente ni comme « le coding agent le plus puissant », ni comme « le meilleur outil de programmation par IA ». Il ancre délibérément son positionnement dans le mot **harness**.++Dans cet article, nous utilisons le cadre des cinq sous-systèmes du cours — instructions, outils, environnement, état et feedback — pour analyser Pi et comprendre ce qui distingue fondamentalement sa philosophie de conception de celles de Claude Code et de Codex. Voici d’emblée la réponse : **la philosophie de Pi consiste à « minimiser le noyau et rendre les extensions programmables ». Il porte l’ingénierie du contexte au-delà du prompt système et laisse l’utilisateur, voire Pi lui-même, modifier le harness, plutôt que de décider du harness à votre place.**++## Positionnement en une phrase++Pi est un noyau minimal : son positionnement officiel réduit volontairement le noyau et vous rend le pouvoir de décision. Selon les termes de la [page d’accueil de pi.dev](https://pi.dev/), « Ask Pi to build what you want, or install a package that does it your way ». Il décompose le harness en quatre couches personnalisables :++- **Extensions** : hooks TypeScript branchés sur les événements du cycle de vie de Pi, formant une surface programmable au niveau du runtime.+- **Skills** : packages de capacités chargés à la demande, qui contiennent instructions et outils selon le principe de progressive disclosure.+- **Prompt templates** : prompts Markdown réutilisables, développés en saisissant `/name`.+- **Themes** : apparence de la TUI.++Cette hiérarchie est déjà en elle-même un choix de conception du harness : **les règles et les extensions déterminent entièrement « ce que le modèle peut voir et à quel moment », au lieu de coder ces décisions en dur dans le noyau.**++## Boucle fondamentale++Comme tous les coding agents, Pi repose essentiellement sur une boucle while « raisonnement → exécution d’un outil → observation → nouveau raisonnement ». Ce qui mérite l’attention n’est pas la boucle elle-même, mais la manière dont Pi traite ce qui l’entoure : il étend la gestion du contexte, d’une simple « compaction » interne à la boucle, à un « contrôle » exercé en amont de celle-ci.++Le runtime de Pi expose une interface programmable. Outre la TUI interactive, la section [Programmatic Usage du README source](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) prend en charge les modes print/JSON scriptables, un protocole RPC et l’intégration via SDK. Un même harness peut donc être piloté étape par étape par un humain ou automatiquement par une CI/CD ou un autre programme. C’est le prérequis du passage « du pilotage manuel à la boucle automatisée » décrit dans la Leçon 13 sur l’ingénierie des boucles : un harness qui ne peut être piloté que de manière interactive par un humain ne pourra jamais entrer dans une boucle automatisée.++## Sous-système d’instructions : AGENTS.md et SYSTEM.md++Pi traite les « instructions » avec retenue, tout en maintenant une hiérarchie claire :++- **AGENTS.md** : la section [Project Context Files du README source](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) précise l’ordre de chargement : `~/.pi/agent/AGENTS.md` global → parcours ascendant des répertoires parents → `./AGENTS.md` du répertoire courant (avec compatibilité CLAUDE.md). C’est l’application du principe « le dépôt est la source de vérité » : les instructions sont des fichiers, pas des rappels glissés dans une conversation.+- **SYSTEM.md** : la [documentation officielle de pi.dev](https://pi.dev/docs/usage/project-context) indique qu’un projet peut remplacer (replace) ou compléter (append) le prompt système par défaut. C’est le seul point d’entrée officiel permettant de modifier le « prompt système » de Pi, ainsi que sa couche « d’auto-description de l’environnement ».++Pi souligne que son prompt système est lui-même **minimal**. Ce choix implique un compromis clair : le noyau n’accumule pas de longues règles du type « si… alors… », mais fournit des points d’extension afin que les règles n’apparaissent sous forme de Skills et d’Extensions que lorsqu’elles sont nécessaires. Cela fait directement écho à la Leçon 04, « Pourquoi un fichier d’instructions géant échoue » : avec un « noyau minimal + des fichiers séparés + un chargement à la demande », Pi évite naturellement le piège du fichier d’instructions géant.++## État et contexte : le domaine où Pi va le plus loin++L’ingénierie du contexte de Pi mérite une attention particulière, car elle traduit en mécanismes concrets des notions du cours telles que la « continuité du contexte » et la « prévention de la corruption du contexte » :++**1. Compaction programmable.** À l’approche de la limite du contexte, les anciens messages sont automatiquement résumés. La [documentation officielle de pi.dev](https://pi.dev/docs/usage/sessions) explique que la stratégie de compaction est elle-même **personnalisable** : une extension peut implémenter une compaction fondée sur les sujets, un résumé sensible au code ou même confier le résumé à un autre modèle. Le README source détaille aussi le mécanisme par défaut : la compaction automatique se déclenche dans deux cas — récupération après dépassement du contexte ou dépassement du seuil de conservation —, le point de coupure conserve environ les 20 000 tokens les plus récents, tandis que les messages antérieurs sont résumés dans un « context handoff » puis compactés progressivement en chaîne. Pi ne considère donc pas la manière de compacter comme une constante figée, mais comme une composante du harness.++**2. Contexte dynamique (Dynamic context).** La [documentation officielle de pi.dev](https://pi.dev/docs/usage/extensions) indique que les extensions peuvent injecter des messages avant chaque étape de raisonnement, filtrer l’historique, mettre en œuvre un RAG et construire une mémoire à long terme. Cela va plus loin que « compacter lorsque le contexte est plein » : vous choisissez ce qui entre ou non dans la fenêtre avant même que le contexte y soit injecté. Pour répondre aux objectifs du cours — « rendre le fonctionnement de l’agent observable et débogable » et « maintenir la continuité du contexte » —, Pi place ces deux responsabilités dans sa surface d’extension.++**3. Arbre de sessions (Session tree).** La [page d’accueil de pi.dev](https://pi.dev/) indique explicitement que « sessions are stored as trees » : `/tree` permet de revenir à n’importe quel nœud historique pour poursuivre le travail, toutes les branches restant enregistrées dans un seul fichier. Cela résout la « rupture du contexte entre sessions » sur laquelle insiste le cours, non pas en raccordant artificiellement des résumés, mais en rejouant un historique structuré. Les branches peuvent être exportées en HTML ou publiées sous forme de gist, ce qui apporte en même temps l’observabilité.++## Sous-système d’outils : Skills et Extensions++Les « outils » de Pi se répartissent en deux couches :++- **Skills** : la section [Skills du README source](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) les définit clairement comme des « self-contained capability packages that the agent loads on-demand » : des packages autonomes de capacités, chargés à la demande, qui contiennent des instructions et des outils et respectent le standard Agent Skills. Grâce à la progressive disclosure, le détail d’un Skill n’entre dans le contexte qu’à son déclenchement, **sans saturer le prompt cache**. Il s’agit d’un choix de conception du harness motivé par les coûts : chaque token supplémentaire dans le contexte est facturé à chaque inférence ; charger les Skills à la demande est une autre manière de « donner la carte, pas le manuel ».+- **Extensions** : des hooks TypeScript branchés sur les événements intégrés du cycle de vie. La section [Hooks du README source](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) donne plusieurs usages officiels : intercepter les commandes dangereuses (barrière de permissions), créer un checkpoint de l’état du code lors d’un changement de tâche, protéger des chemins (interdire l’écriture de `.env`, par exemple), modifier la sortie d’un outil avant de la transmettre au modèle, ou injecter des messages depuis l’extérieur — surveillance de fichiers, Webhook ou CI — pour réveiller l’agent. Les API de ces hooks sont également exportées par `@mariozechner/pi-coding-agent/hooks`. Le harness communautaire [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) enveloppe cette surface de hooks dans des extensions prêtes à l’emploi, telles que skill-router, session-summary, extract-patterns et telemetry.++Les Extensions constituent la décision de conception la plus importante de Pi : **au lieu de proposer seulement quelques interrupteurs, Pi expose toute la surface d’événements interne du runtime.** Vous voulez ajouter de la mémoire ? Injectez-la dans `agent/pre-step`. Enregistrer un comportement ? Abonnez-vous aux événements de session. Modifier une requête adressée au modèle ? Branchez un hook sur `agent/request`. Pi peut ainsi modifier son propre harness, ce qui s’approche davantage de la définition d’un « harness programmable » que n’importe quel ensemble d’options de configuration.++## Feedback et vérification : intégrer aussi « l’apprentissage » au harness++Pi n’intègre pas lui-même de barrière de tests obligatoire — c’est à l’utilisateur d’inscrire les commandes de vérification dans AGENTS.md —, mais le harness communautaire [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) structure la « boucle de feedback » au moyen d’extensions. La section Hooks du README officiel fournit également les fondations de mécanismes similaires :++- **session-summary** (extension de pi-agent-harness) : maintient des entrées glissantes dans `PROGRESS.md` ; il s’agit du sous-système d’état du cours, dédié au suivi de progression des tâches longues.+- **extract-patterns** (extension de pi-agent-harness) : recueille dans la session des enseignements potentiels et les conserve dans `LESSONS.md`, transformant la convention « préparer le handoff avant la fin de chaque session » en mécanisme.+- **telemetry** (extension de pi-agent-harness) : enregistre notamment la consommation de tokens et les coûts, pour assurer l’observabilité.++Le même dépôt communautaire confirme ce modèle : `VISION.md` (objectif), `PROGRESS.md` (progression), `LESSONS.md` (enseignements) et `STANDARDS.md` (standards) sont tous des fichiers Markdown persistants entre les sessions. C’est exactement le schéma recommandé dans le cours — « dépôt comme source de vérité + fichier de progression + mécanisme de handoff » —, simplement transformé en couche prête à l’emploi grâce au mécanisme d’extensions de Pi.++## Correspondance avec le cadre du cours++Évaluation de Pi selon les cinq sous-systèmes du cours (subjective, à titre comparatif) :++| 子系统 | Pi 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 分级加载 + SYSTEM.md | 层级清晰,但规则本身要靠用户写 |+| 工具 | 技能按需加载 + 扩展全生命周期钩子 | 极强,把工具系统做成了可编程面 |+| 环境 | SYSTEM.md 做环境自描述;运行时环境靠用户在 AGENTS.md 里声明 | 机制是开放的,但可复现性依赖用户自述 |+| 状态 | 会话树 + 压缩可定制 + PROGRESS.md | 极强,跨会话与可恢复性是其核心 |+| 反馈 | 验证命令靠用户定义;session-summary / extract-patterns 机制化 | 机制提供,内容靠用户 |++Le compromis choisi par Pi contraste fortement avec Claude Code et Codex : Claude Code intègre directement au noyau la mémoire, les permissions et les subagents, prêts à l’emploi ; Codex fait des conventions du dépôt et de l’isolation de l’environnement ses valeurs par défaut ; Pi choisit de **ne rien décider à votre place** et transforme le pouvoir de décision en points d’extension. En contrepartie, vous devez soit écrire vos propres extensions, soit installer les packages d’autres développeurs.++## Conceptions à retenir++1. **Rendre la stratégie de compaction interchangeable.** Dans votre harness, « la manière de compacter le contexte » ne devrait pas être un paramètre codé en dur, mais une interface stratégique remplaçable.+2. **Remplacer le résumé forcé par un arbre de sessions.** La reprise entre sessions ne doit pas nécessairement dépendre du « résumé de la session précédente » ; rejouer un historique structuré constitue souvent un sous-système d’état plus fiable.+3. **Préserver le prompt cache.** Charger les Skills à la demande et ne pas injecter toutes les règles d’un coup dans le prompt système relève autant de l’ingénierie du contexte que de l’ingénierie des coûts.+4. **Permettre à l’agent de modifier son propre harness.** Si la surface d’extension du harness est suffisamment ouverte, « optimiser le comportement de l’agent » peut devenir une tâche semi-automatisée par l’agent lui-même.++## Sources de référence (texte original / code source)++Chaque affirmation peut être reliée aux textes originaux ou au code source ci-dessous, afin d’éviter toute reformulation fondée sur de simples impressions :++- **pi.dev 官网** : formulation du positionnement « Ask Pi to build what you want, or install a package that does it your way », quatre couches personnalisables, arbre de sessions (« sessions are stored as trees », `/tree`, enregistrement dans un seul fichier, export HTML et partage par gist).<br/>https://pi.dev/+- **pi.dev 官方文档 · Sessions** : compaction interchangeable — topic-based, code-aware ou autre modèle de résumé —, mécanismes de compaction automatique et d’injection dynamique du contexte.<br/>https://pi.dev/docs/usage/sessions+- **pi.dev 官方文档 · Extensions** : les extensions peuvent injecter des messages avant chaque étape de raisonnement, filtrer l’historique, effectuer un RAG et construire une mémoire à long terme.<br/>https://pi.dev/docs/usage/extensions+- **pi.dev 官方文档 · Project Context** : sémantique replace / append de SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent 源码 README**(badlogic/pi-mono) : ordre de chargement à trois niveaux d’AGENTS.md — global → répertoires parents → répertoire courant —, conditions de déclenchement de `/compact` et de la compaction automatique avec point de coupure à 20 000 tokens, chargement à la demande des Skills et standard Agent Skills, cycle de vie des Hooks et exemples d’usage officiels, Programmatic Usage — JSON / RPC / SDK.<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness 社区仓库** : extensions skill-router / session-summary / extract-patterns / telemetry et organisation des fichiers VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++Cours associés : [Leçon 02 · Ce qu’est réellement un harness](../lectures/lecture-02-what-a-harness-actually-is/) | [Leçon 05 · Préserver la continuité du contexte dans les tâches longues](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Leçon 13 · Passer du pilotage manuel à la boucle automatisée](../lectures/lecture-13-loop-engineering/)diff --git a/docs/fr/index.md b/docs/fr/index.mdindex 2663a03..7f093c5 100644--- a/docs/fr/index.md+++ b/docs/fr/index.md@@ -25,6 +25,10 @@ Choisissez votre parcours d'apprentissage. Le cours est divisé en leçons théo<h3>Bibliothèque de ressources</h3><p>Modèles prêts à copier, comme AGENTS.md et feature_list.json, pour vos propres dépôts.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Décryptage des harnesses de pointe</h3>+ <p>Comment Pi, Claude Code, Codex et DeepSeek conçoivent réellement leur harness, relié au cadre du cours.</p>+ </a></div>## Le mécanisme central d'un harnessdiff --git a/docs/ja/harness-designs/claude-code/index.md b/docs/ja/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..c241b0b--- /dev/null+++ b/docs/ja/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Claude Code の harness 設計を読み解く++Anthropic は『[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)』で、信頼性の源泉はモデルではなく harness であり、agent は「モデルの外側」で制約される必要があると明確に述べています。Claude Code は、この考え方を製品化した例であり、Anthropic 公式も直接 **agentic harness** の一種に位置づけています。これはマーケティング上の表現ではありません。Claude Code は、現在公開されている中で最も詳細に分析された harness の一つでしょう。ソースコードが公開され、コミュニティの調査レポートも詳しく、講義に登場するほぼすべての中核メカニズム(階層化メモリ、コンテキストの compaction、permissions、hooks、subagent、session の永続化)が、完全に製品化されています。++この記事では、講義の5つのサブシステムのフレームワークを使って Claude Code を読み解き、「コンテキスト管理」「早すぎる完了宣言の防止」「決定論的な制約」といった harness の原則を、どう実装しているかに注目します。++## 一言で表すと++Claude Code の中核は、モデルを呼び出し、ツールを実行し、結果を観察し、再びモデルを呼び出すという単純な while ループです。しかし、**コードの大部分はこのループ内ではなく、それを取り巻くシステムにあります**。permissions システム、コンテキスト compaction pipeline、拡張メカニズム、subagent のオーケストレーション、session ストレージです。これこそ harness の本質です。ループは骨格にすぎず、信頼性を決めるのは骨格の外側にあるすべてです。++## 指示サブシステム:階層化メモリ体系++Claude Code のメモリシステムは、harness 理論に対する最も直接的な貢献であり、講義の「リポジトリを唯一の事実源にする」と「session をまたぐコンテキスト継続性」に対応します。[公式ドキュメント『How Claude remembers your project』](https://code.claude.com/docs/en/memory)には、各 session はまっさらなコンテキストウィンドウから始まり、2種類のメカニズムによって session をまたいで知識を持ち越すと明記されています。CLAUDE.md ファイル(ユーザーが書く指示)と auto memory(Claude 自身が書くメモ)です。++scope について、公式は CLAUDE.md ファイルを4種類に分類しています(読み込み順が広いものから狭いものへ)。++- **組織ポリシーレベル**:IT/DevOps が一元管理する(例:`/etc/claude-code/CLAUDE.md`)企業レベルの規約です。+- **ユーザーレベル `~/.claude/CLAUDE.md`**:プロジェクトをまたぐ個人の好みとルールです。+- **プロジェクトレベル `./CLAUDE.md` または `./.claude/CLAUDE.md`**:プロジェクトレベルの事実源であり、プロジェクト構造、技術スタック、検証コマンドを記載し、リポジトリで共有します。+- **ローカルレベル `./CLAUDE.local.md`**:プロジェクト内での個人的な好みを記載し、通常は `.gitignore` に追加して commit しません。++さらに、2つのメカニズムがあります。++- **サブディレクトリ単位のオンデマンド読み込み**:サブディレクトリ内の CLAUDE.md は起動時には読み込まれず、Claude がそのディレクトリのファイルを読むときに初めてコンテキストへ入ります。+- **auto memory**:Claude がユーザーの修正や好みに基づいて自発的にメモを書きます。リポジトリ単位で共有され、worktree をまたいで有効になり、各 session では先頭200行または25KBまで読み込まれます。++この4種類の scope が、**指示の階層**を構成します。公式ドキュメントによると、「具体的な指示ほど後からコンテキストへ入る」ため、プロジェクトの指示はユーザーの指示より後に現れます。その価値は、各対話の冒頭で一つの巨大な指示ファイルをモデルに読ませるのではなく、scope に応じて最も近いものを読み込むことにあります。これは講義04「単一の巨大な指示ファイルが失敗する理由」に対する製品レベルの回答です。++## コンテキストサブシステム:5段階の compaction pipeline++Claude Code のコンテキスト管理は、単なる「満杯になったら要約する」仕組みではなく、**5段階の compaction pipeline**(five-layer compaction pipeline)です。このアーキテクチャの詳細は、[VILA Lab の『Dive into Claude Code』](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)によるソースコードレベルの分析に基づきます。講義05では「長いタスクは継続性を失う」と説明しました。Claude Code の解決策は多段階の漏斗です。まず可逆的な pruning(冗長なツール結果を取り除く)を行い、次に構造化して抽出し、最後に初めて不可逆的な LLM 要約を使います。また、過度な compaction を防ぐ circuit breaker も備えています。++これを支えるのが session ストレージの設計です。**追記型 session ストレージ(append-oriented storage)**として、すべての履歴を `history.jsonl` へ追記し、`/resume` による復元と fork 分岐をサポートします。これにより、「各 session の終了前にハンドオフを整える」ことが保証されます。記憶力が高いからではなく、ストレージ層が追記型でリプレイ可能だからです。++## ツールサブシステム:4種類の拡張メカニズム++Claude Code は拡張インターフェースを4種類に分け、それぞれが異なる問題を解決します。これは設計上、最も参考にしたい部分です。++- **Skills**:[公式ドキュメント](https://code.claude.com/docs/en/skills)では、`SKILL.md` で記述する手続き的知識と定義されています。トリガーワードによって自動的に読み込まれ、progressive disclosure を採用します。「何かをどう行うか」というドメイン知識に適しています。+- **MCP**:[公式ドキュメント](https://code.claude.com/docs/en/mcp)にある JSON-RPC プロトコルで外部システムへ接続します。「モデルの手を外部世界へ届かせる」ための標準インターフェースです。+- **hooks**:[公式ドキュメント](https://code.claude.com/docs/en/hooks)にある、`PreToolUse`、`PostToolUse`、`Stop` などのライフサイクルイベントへ接続する決定論的なスクリプトです。+- **plugin / subagent**:[公式ドキュメント](https://code.claude.com/docs/en/sub-agents)にある、複雑なタスクを専門化した agent へ分割して実行する仕組みです。++重要な設計は、**責務の分離**です。CLAUDE.md は「何であるか」、Skills は「どう行うか」、MCP は「どこへ接続するか」、hooks は「いつ強制するか」を担います。チームがこれらの層を混同すると(たとえば MCP が担うことを CLAUDE.md に書くと)、講義で述べたコンテキスト漏れが起きます。++## フィードバックと検証:決定論的な制約 + 人間と機械の分業++講義10では、「完全なフローを実行して初めて本当に検証したと言える」と説明しました。Claude Code は2つの経路でこれに対応します。++**1. permissions システム(決定論的な制約)。** Claude Code の permissions は「すべてを一度ずつ確認する」仕組みではなく、7種類のモードと ML ベースの分類器です。低リスクな操作は許可し、高リスクな操作はポリシーに従って確認または拒否します(アーキテクチャの詳細は [VILA Lab の分析](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)を参照)。講義07の「agent に境界を明確にする」を、prompt でお願いするのではなく、runtime で強制しています。++**2. hooks(早すぎる完了宣言の防止)。** `PostToolUse` hook はツール実行後にチェックを強制し、その結果をコンテキストへ書き戻せます。`Stop` hook は agent が完了を宣言するときに介入します。これは「作業する者とチェックする者を分ける」設計です。[Anthropic は harness の記事で](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)、agent が自信満々に自らの成果を称賛する("confidently praised their work")と明確に観察しています。そのため、モデルの自己評価を信頼せず、hooks で**決定論的な**チェックを注入します。++**3. subagent(コンテキストの分離)。** 各 subagent の対話記録は独立した sidechain ファイルに保存され、**親 agent のコンテキストを膨張させません**([VILA Lab の分析](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)を参照)。これは「タスク境界」と「コンテキスト分離」の組み合わせです。タスクを分けると同時に、コンテキスト汚染も分離します。++## 可観測性と session の永続化++Claude Code のログは追記型の完全な記録(history.jsonl)です。さらに `/compact`、`/clear`、`/init` という明示的なコマンドにより、コンテキストが満杯になるまで受け身で待つのではなく、状態を能動的に管理できます。`/init` は「agent が作業前に毎回初期化する」(講義06)という考え方を、一つのコマンドにしています。[公式ドキュメント](https://code.claude.com/docs/en/memory)によると、コードベースを自動分析し、ビルドコマンド、テスト手順、プロジェクト規約を含む最初の CLAUDE.md を生成します。++## 講義のフレームワークへのマッピング++| サブシステム | Claude Code の実装 | 評価 |+| --- | --- | --- |+| 指示 | scope の階層化(組織/ユーザー/プロジェクト/ローカル)+ auto memory | 階層化メモリの模範的な実装 |+| ツール | Skills + MCP + hooks + subagent の4種類の拡張 | 責務の分割が明確で、中核的な強み |+| 環境 | プロジェクト内の設定 + settings.json | CLAUDE.md でユーザーが自己記述する |+| 状態 | 追記型 session ストレージ + 5段階の compaction + resume/fork | 非常に強力。長いタスクの継続性における参考実装 |+| フィードバック | permissions 分類器 + PostToolUse hook による強制チェック | 「早すぎる完了宣言の防止」を決定論的な仕組みにしている |++## 参考にしたい設計++1. **指示を一つのファイルに積み上げず、scope ごとに階層化する**。ディレクトリ単位の CLAUDE.md は、「近くで読み込む」美しい実装です。+2. **compaction は段階的な漏斗にする**。最初に可逆的な処理を行い、その後に不可逆的な処理を行います。最初から全文を要約してはいけません。+3. **hooks で決定論的なチェックを行う**。早すぎる完了宣言を防ぐには、prompt でお願いするのではなく、runtime で強制します。+4. **subagent のコンテキストを分離する**。タスクと同時にコンテキストも分割し、subtask の結果でメインループを汚染させないようにします。+5. **session ストレージを追記型かつリプレイ可能にする**。ハンドオフは記憶に頼らず、ストレージ層で保証します。++## 参考資料(原文 / ソースコード)++以下の原文またはソースコードから各主張を確認できるため、印象に基づく説明ではありません。++- **Claude Code 公式ドキュメント · Memory**:各 session のまっさらなコンテキスト、CLAUDE.md の4種類の scope、サブディレクトリ単位のオンデマンド読み込み、auto memory(200行 / 25KB)、`/init` による CLAUDE.md の生成。<br/>https://code.claude.com/docs/en/memory+- **Claude Code 公式ドキュメント · Skills / MCP / Hooks / Sub-agents**:4種類の拡張メカニズムとイベント(PreToolUse / PostToolUse / Stop)の定義。<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab『Dive into Claude Code』**(ソースコードレベルの分析レポート):5段階の compaction pipeline、permissions の7モード + ML 分類器、sidechain subagent、追記型 session ストレージ history.jsonl。<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic『Effective harnesses for long-running agents』**:「信頼性はモデルではなく harness に由来する」、agent は自信満々に自らの成果を称賛する、hooks で検証を行うといった見解の出典。<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack ガイド**(コミュニティ、CLAUDE.md / Skills / MCP / Subagents / Hooks の階層):拡張メカニズムの責務分離に関する補足資料。<br/>https://jsmanifest.com/claude-code-full-stack-guide++関連講義:[講義03 · リポジトリをシステムの記録にする](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [講義09 · エージェントの早すぎる勝利宣言を防ぐ](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [講義10 · エンドツーエンドテストが結果を変える理由](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/ja/harness-designs/codex/index.md b/docs/ja/harness-designs/codex/index.mdnew file mode 100644index 0000000..ebad5ad--- /dev/null+++ b/docs/ja/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Codex の harness 設計を読み解く++OpenAI の [Codex](https://openai.com/index/harness-engineering/) は、4つの製品の中で最も「harness の原則」と深く結びついているかもしれません。この分野全体の名前を定義した『Harness Engineering』という記事自体が、OpenAI チームが Codex を使って製品を開発した経験のまとめだからです。したがって、Codex の harness 設計を読み解くことは、その記事の背後にあるエンジニアリング実践を読み解くことでもあります。++Codex の思想は、次の一文に要約できます。**リポジトリを唯一の事実源(repository as the system of record)にし、AGENTS.md は目次ページにとどめる。エンジニアリングの価値は、環境を設計し、意図を表現し、フィードバックループを構築することにある。**++## 一言で表すと++OpenAI チームは Codex を使い、数週間で、最終的に100万行を超えるコードからなる製品を提供しました。**すべてのコード行を Codex が書いています**(原文は [Harness Engineering](https://openai.com/index/harness-engineering/) の "Designing for growth" セクションを参照)。この実践は、エンジニアの役割が「コードを書くこと」から「harness を設計すること」へ変わったとき、システムをどう組織すべきかという問いに答えています。Codex CLI 自体はオープンソースのモノリシックなバイナリ(Rust 実装、[github.com/openai/codex](https://github.com/openai/codex))ですが、harness への主な貢献は、華やかな拡張点ではなく、**規約(convention)**と**コンテキストエンジニアリング**にあります。++## 指示サブシステム:AGENTS.md は百科事典ではなく目次ページ++これは、Codex が harness 理論へ与えた最も影響力のある設計の一つです。++> 単一の巨大な指示ファイルは、機械的なチェック(カバレッジ、更新状況、所有者、相互リンク)に適さず、現実との乖離を避けられません。そのため、AGENTS.md を百科事典として扱うのをやめ、**目次ページ**として扱います。コードベースの知識は構造化されたドキュメントに置き、AGENTS.md はそこへの案内を担います。++(上記は、[『Harness Engineering』原文](https://openai.com/index/harness-engineering/)の "AGENTS.md should be a directory page" セクションを直接言い換えたものです。)++講義04では「単一の巨大な指示ファイルは失敗する」と説明しました。Codex は、その明確な解決策を示しています。AGENTS.md は100行程度に抑え(原文では約100行を推奨し、上限に近づいたら `docs/` へ分割)、収まらない内容は `docs/` ディレクトリへ分割して、agent がオンデマンドで読みます。これは「説明書ではなく地図を渡す」という原則の権威ある出典です。++これを支える原則は、**実装を細かく管理せず、不変条件を強制する**ことです(原文:"don't micromanage the implementation;focus on invariants")。AGENTS.md には、違反できない厳格な制約と検証コマンドだけを記載し、具体的な実装方法はモデルへ任せます。これは講義02の「細かな指示ではなく制約を与える」に直接対応します。++## コンテキストサブシステム:Write-Select-Compress-Isolate++Codex のコンテキストエンジニアリングは、4つの戦略にまとめられます。これは "context engineering" が独立した分野となった後、コミュニティが整理して Codex へマッピングしたフレームワークです(出典は [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/))。++- **Write(外へ書き出す)**:コンテキストをウィンドウの外側へ永続化します。結論はドキュメントへ、状態はファイルへ書き、対話内だけに残しません。「リポジトリを唯一の事実源にする」に対応します。+- **Select(中へ選び入れる)**:必要な token だけをウィンドウへ取り込みます。AGENTS.md で案内し、ファイルをオンデマンドで読み、リポジトリ全体を詰め込みません。+- **Compress(圧縮する)**:本当に重要な情報を残します。Codex には自動 compaction と手動の `/compact` があり、`compact_prompt` をカスタマイズできます([Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)を参照)。+- **Isolate(分離する)**:コンテキストを異なる境界へ切り分けます。subagent で異なるタスクのコンテキストを分離し、フロントエンドの subagent がバックエンドのデータベース schema を見ることがないようにします。++Codex には、さらに細かな環境コンテキストの設計があります。コミュニティによる [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) のソース分析によると、`build_environment_update_item` は、環境が変化したときだけ**変更されたフィールド**(CWD、git branch、ファイルシステム)を出力し、毎回完全なシステムコンテキストを貼り直しません。これは「コンテキスト内で重複 token を増やさない」ためのエンジニアリング上の工夫です。++## ツールと境界:worktree による分離 + subagent++Codex には、2つの中核的な harness メカニズムがあります。++**1. git worktree による環境分離。** [『Harness Engineering』原文](https://openai.com/index/harness-engineering/)の "Environment" セクションには、各タスクを独立した git worktree で実行し、ローカルの可観測性 stack(ログ、メトリクス、トレース)と組み合わせて、各変更を独立した環境で検証すると明記されています。これは講義07「agent に各タスクの境界を明確にする」の物理的な実装です。境界を指示でお願いするのではなく、環境分離によって強制します。ここでは、環境(environment)サブシステムがハードな分離として実装されています。++**2. コアレベルの subagent。** Codex の `spawn_agent` / `wait_agent` はコアレベルのツールです。モデルが明示的に subagent を作成し、独立した session 履歴とツールセットを与え、その結果を待ちます。subagent は親の AGENTS.md の指示を継承しますが、**独自のコンテキスト**で動作します。設定は `.codex/agents/*.toml` に置き、異なるモデルと指示を指定できます(詳細は [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) の Sub-agents セクションを参照)。これは「コンテキスト分離」の直接的な実装であり、講義12の「ハンドオフ」の考え方も表しています。各 subagent は明確な境界を持つ作業単位です。++## フィードバックサブシステム:検証コマンドを規約へ組み込む++OpenAI の実践で最も強調されていることの一つは、AGENTS.md に検証コマンドを明記し、「正しくできたことをどう確認するか」をリポジトリの一部にすることです。Codex のエンジニアリングフローでは、テスト、CI、ドキュメント、可観測性設定のすべてを Codex が生成し、そのすべてが「実行可能な検証経路」になります。強力だが信頼できないモデルへの解決策は、モデルの自発性を祈ることではありません。**検証経路を harness のデフォルトコンポーネントにする**ことです。++approval policies と plan mode は、別の方向からフィードバックを提供します。高リスクな操作を行う前に計画を提示し、承認を求めることで、「タスク境界」と「人間の決定権」を runtime の制御として実装します。++## 講義のフレームワークへのマッピング++| サブシステム | Codex の実装 | 評価 |+| --- | --- | --- |+| 指示 | AGENTS.md の目次ページ + docs/ への分割 + 不変条件の強制 | 教科書的。「説明書ではなく地図を渡す」を定義した |+| ツール | worktree による分離 + spawn_agent subagent | 環境で境界をハードに分離し、非常に強力 |+| 環境 | 独立した worktree + 可観測性 stack | worktree による分離が象徴的な特徴 |+| 状態 | Write 戦略(状態をファイル/ドキュメントへ書き出す) | 組み込みメモリではなく規約に依存する |+| フィードバック | 規約に含めた検証コマンド + approval policies + plan mode | フィードバック経路をデフォルト化しており、参考になる |++Codex と Claude Code の比較は興味深いものです。Claude Code は「足し算」で、メモリ、permissions、subagent をすべてコアへ組み込みます。Codex は「引き算」で、コアをできるだけ抑制し、より多くの責任をリポジトリ規約とコンテキストエンジニアリングへ置きます。コミュニティで「Codex はコードより harness の思想のほうが価値がある」とよく言われるのは、このためです。++## 参考にしたい設計++1. **AGENTS.md を目次ページとして書く**:100行程度に抑え、docs/ 内の詳細を参照させ、機械的にチェックできるようにします。+2. **実装を細かく管理せず、不変条件だけを書く**:厳格な制約 + 検証コマンドを記載し、残りはモデルへ任せます。+3. **worktree で環境を分離する**:タスク境界は環境で強制し、指示でお願いしません。+4. **環境コンテキストは差分だけを渡す**:各ターンで変更されたフィールドだけを出力し、完全なシステムコンテキストを繰り返し貼りません。+5. **subagent でコンテキストを分離する**:タスクと同時にコンテキストも分割し、subtask でメインループを汚染させません。++## 参考資料(原文 / ソースコード)++以下の原文またはソースコードから各主張を確認できるため、印象に基づく説明ではありません。++- **OpenAI『Harness Engineering』**:AGENTS.md の目次ページと約100行という推奨、executive invariants / don't micromanage、worktree による分離 + 可観測性 stack、規約に含めた検証コマンド、100万行を超える製品事例、approval policies と plan mode。この記事におけるすべての中核的な主張の主要な出典です。<br/>https://openai.com/index/harness-engineering/+- **OpenAI 公式『AGENTS.md』規約**(AGENTS.md をツール横断の規約にする標準):<br/>https://openai.com/index/agents-md/+- **Codex CLI オープンソースリポジトリ**(Rust で実装されたモノリシックなバイナリ):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI**(コミュニティ):Write-Select-Compress-Isolate フレームワーク、`/compact` と `compact_prompt`、`spawn_agent` / `wait_agent` subagent と `.codex/agents/*.toml` 設定。<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals**(コミュニティによるソース分析):`build_environment_update_item` による環境コンテキストの差分など、実装の詳細。<br/>https://github.com/AlexKenbo/codex-harness-internals++関連講義:[講義03 · リポジトリをシステムの記録にする](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [講義04 · 指示を複数のファイルに分割する](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [講義07 · エージェントに各タスクの境界を明確にする](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/ja/harness-designs/deepseek/index.md b/docs/ja/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..6b734f0--- /dev/null+++ b/docs/ja/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# DeepSeek Harness の設計を読み解く++[DeepSeek Harness](https://deepseek.com/harness)(コマンド名 `dsh`、リポジトリ `deepseek-ai/deepseek-harness`)は、2026年8月に Developer Preview として公開されました。公式による定義は明快です。**Agent = Model + Environment + Tools + State**、つまりモデル、環境、ツール、状態の4要素です。++これまでの3製品の分析が「harness をどう設計すべきか」という問いだったとすれば、DeepSeek Harness はさらに大胆な問いを投げかけています。**harness は特定のモデルから切り離され、独立した runtime になれるのか。** その答えは「できる」であり、これを徹底しています。[アーキテクチャドキュメント](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)の原文では、*Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself*(製品のすべての部分が plugin であり、モデル adapter、ツール registry、session log、さらには agent loop 自体も含まれる)と説明されています。++この記事では、plugin 化されたコア、capability seam、event pipeline、そして最も強力なエンジニアリング上の制約である "Model-visible means logged" の3点を中心に読み解きます。++## 一言で表すと++従来の coding agent の構造は、「LLM + 固定された agent loop + 固定されたツールセット」です。DeepSeek Harness の構造は「モデル + plugin コア(Cordis)」です。コアは plugin の読み込み、アンロード、依存関係、イベントメカニズムだけを担い、**agent 固有の能力を一切所有しません**。[アーキテクチャドキュメント](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)の原文は、"There is no privileged core to patch"(patch が必要な特権コアは存在しない)、"you extend dsh by mounting a plugin beside the others"(コアを変更せず、ほかの plugin と並べて一つの plugin を mount すれば dsh を拡張できる)と述べています。これは、agent loop 自体さえ変更不可侵ではないことを意味します。DeepSeek のモデル、Claude Code の subagent、リモート sandbox、カスタムメモリ、カスタムループ、カスタム UI を組み合わせ、まったく新しい agent を構成できます。++これは、講義の「モデルの重みパラメータ以外のすべてが harness」という言葉を最も徹底して実践したものです。harness が独立したものであるなら、独立した OS にしてしまおうという設計です。++## アーキテクチャの中核 1:Capability Seam++DeepSeek Harness は「能力」を Service として表し、ほぼすべての能力を3層に分けています。++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++ファイルシステムを例にすると、`FS Service` の下には Local FS、E2B FS、Remote FS という複数の Provider があり、上位には統一された file tools として公開されます。Shell、Subprocess、Sandbox、Web、LLM、SubAgent も同じ構造です。この3層構造は、私たちの要約ではありません。[アーキテクチャドキュメント · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)の原文に、*a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool*(capability seam は交換可能な能力であり、インターフェースを宣言する Service Definition、それを実装する Service Provider、それを使用する Consumer という3つの役割を持つ。Consumer は通常、モデル向けのツールである)とあります。++これは harness エンジニアリングに長く存在してきた問題を解決します。**agent は「具体的なツール」に依存すべきか、それとも「能力インターフェース」に依存すべきか。** DeepSeek Harness は後者を選びました。講義の観点では、「ツールサブシステム」がインターフェースとして標準化されたことを意味します。Provider を交換しても、モデルに公開されるツールの形は変わりませんが、環境は完全に変わります。++## アーキテクチャの中核 2:Event Pipeline++DeepSeek Harness の内部は、単純な「LLM → ツール → LLM」ではなく、event pipeline になっています。各段階が plugin から監視できるイベントポイントです。++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(上記の pipeline は、[アーキテクチャドキュメント · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)セクションの内容を書き換えたものです。`turn/*`、`step/*`、`user/message`、`assistant/*`、`tool/*` は永続化される session イベントであり、`agent/pre-step`、`agent/request`、`llm/stream`、`tools/*` は plugin が監視できる拡張点です。)++この設計の最大の利点は、**多くの機能が agent loop 自体を変更せずに実装できる**ことです。ツール実行前にセキュリティチェックを行うなら、`tools/pre-execute` を監視します。メモリを追加するなら、`agent/pre-step` で注入します。動作を記録するなら、session イベントを購読します。モデルへのリクエストを変更するなら、`agent/request` に hook します。推論を続けるかどうかを決めるなら、`agent/turn-stopping` を監視します。++講義11「エージェントの動作を可観測にする」と比べると、DeepSeek Harness はさらに先へ進んでいます。「ログを追加する」のではなく、**ループの各段階をイベントポイントにする**ことで、可観測性、permissions、メモリ、ポリシーをすべてリスナーとしてループへ接続し、ループ内にハードコードしません。++## アーキテクチャの中核 3:Session Event Log と "Model-visible means logged"++DeepSeek Harness には、**append-only の Session Event Log(追記専用の session イベントログ)**があり、非常に強力なエンジニアリング上の制約を定めています。[アーキテクチャドキュメント · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)の原文は次のとおりです。++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(モデルから見えるものは、すべて記録される。モデルへのリクエストに届くものはすべてログから再構築可能でなければならず、runtime invariant がそれを強制する。)++言い換えれば、可観測性は後から補うログではなく、harness の第一原則です。モデルのコンテキストへ入るものは、デフォルトでログに残るべきだという考え方です。これは最終講義の「可観測性は harness の内部に属する」と直接対応します。また、"append-only" というストレージ設計を原則にし、ログを追記するだけで上書きせず、session の状態をリプレイ可能にします。++## 講義のフレームワークへのマッピング++| サブシステム | DeepSeek Harness の実装 | 評価 |+| --- | --- | --- |+| 指示 | plugin 化。ルール/Skills を plugin として注入 | 極めて自由だが、「CLAUDE.md」のような組み込みの規約はない |+| ツール | Service Definition → Provider → Consumer の capability seam | ツールサブシステムの標準化を徹底している |+| 環境 | sandbox/FS/Shell はすべて Provider を交換可能(リモート E2B を含む) | 環境が完全にプラグ可能 |+| 状態 | append-only Session Event Log + Model-visible means logged | 可観測性が第一原則 |+| フィードバック | tools/pre-execute 上の permission / guard / policy / hook | フィードバックメカニズムをイベント化している |++DeepSeek Harness とほかの3製品との根本的な違いは、Pi、Claude Code、Codex が「具体的な一つの agent」内部で harness を最適化するのに対し、DeepSeek Harness は harness を**モデルから独立した OS**として定義する点です。agent 自体は、この OS 上で交換可能なアプリケーションの一つにすぎません。代償も明確です。自由度が高いほど設定コストも高くなります。これは「harness を OS にする」という設計に固有のもう一つの側面です(Developer Preview の段階でも、「まず試してみるものであり、メカニズムはまだ進化中」と位置づけられています)。++## 参考にしたい設計++1. **ループの各段階をイベントポイントにする**:permissions、メモリ、ポリシー、ログを、ループ内にハードコードせず、リスナーとして接続します。+2. **capability seam を標準化する**:「具体的なツール」ではなく「能力インターフェース」に依存すれば、モデルから見えるツールのインターフェースに影響を与えず、環境全体を交換できます。+3. **Model-visible means logged**:モデルから見えるものをすべて記録し、可観測性を「追加の長所」ではなく「第一原則」にします。+4. **append-only の session log**:状態をリプレイ可能にし、ハンドオフを信頼できるものにします。「各 session の終了時にクリーンな状態を残す」ことをエンジニアリングで保証します。++## 参考資料(原文 / ソースコード)++以下の原文またはソースコードから各主張を確認できるため、印象に基づく説明ではありません。++- **DeepSeek Harness 公式サイト**:"Agent = Model + Environment + Tools + State" という製品定義、Developer Preview という位置づけ、`dsh` コマンド。<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness リポジトリ**(コマンド `dsh`、MIT ライセンス):<br/>https://github.com/deepseek-ai/deepseek-harness+- **アーキテクチャドキュメント architecture.md**:この記事の最も重要な出典。"Every part of the product is a plugin"、"There is no privileged core to patch"、Turn flow の event pipeline、Capability seams の3層の役割、"Model-visible means logged" と runtime invariant、append-only Session Event Log、fs/tools/telemetry などの capability seam と `ctx.*` サブシステム。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **アーキテクチャドキュメント · 関連ドキュメント**:Cordis コアの概要(plugins contribute services, typed events, reversible effects)、capability seam の詳細、Session サブシステム。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++関連講義:[講義11 · エージェントの動作を可観測にする](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [講義12 · すべてのセッションでクリーンな状態を残す](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [講義02 · Harness とは実際に何か](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/ja/harness-designs/index.md b/docs/ja/harness-designs/index.mdnew file mode 100644index 0000000..db19a93--- /dev/null+++ b/docs/ja/harness-designs/index.md@@ -0,0 +1,29 @@+# 最前線の Harness 設計を読み解く++このセクションでは、講義で扱った harness の理論を、現在最先端の実在する製品と一つずつ照らし合わせます。各製品について注目するのは、ただ一つ、**その harness がどのように設計されているか**です。つまり、モデルを取り巻くエンジニアリング基盤である、指示、ツール、環境、状態、フィードバックという5つのサブシステムと、コンテキスト継続性、初期化、検証、可観測性、ハンドオフ、ループといった中核メカニズムを見ていきます。++モデルの推論能力が高いか、特定のベンチマークスコアが優れているか、あるいは「この agent に何ができるか」といった一般的な紹介は、意図的に扱いません。それらはモデル層やプロダクト層の問題です。ここで読み解くのは harness、つまりモデルの重みパラメータ以外のすべてです。++## なぜ読み解く価値があるのか++講義01で述べたように、モデルの能力が高いことと、実行が信頼できることは同じではありません。同じモデルでも、異なる harness に置けば、パフォーマンスに一桁もの差が生じることがあります。しかし、講義が説明するのは「どうあるべきか」であり、これらの製品が答えるのは「トップチームが実際にどうしているか」です。++各製品は、それぞれ独立した設計判断の集合です。並べて比較すると、同じ中核メカニズムが、チームごとにまったく異なる形で実装されていることがわかります。++- **Pi** は、harness を最小限のコアとプログラム可能な拡張として構成し、「最小限の system prompt + オンデマンド読み込み」でコンテキストエンジニアリングを行います。+- **Claude Code** は、harness を完全な実行環境として構成します。階層化メモリ、5段階の compaction、permissions、hooks、subagent を備えています。+- **Codex** は、harness の思想を徹底しています。リポジトリを唯一の事実源とし、AGENTS.md は目次ページにとどめ、worktree で環境を分離します。+- **DeepSeek Harness** は、harness 自体をモデルから独立した runtime として定義します。Everything is a Plugin という設計です。++## 記事一覧++- [Pi の harness 設計を読み解く](./pi/):最小限のコア + プログラム可能な拡張により、コンテキストエンジニアリングを system prompt の外側まで広げます。+- [Claude Code の harness 設計を読み解く](./claude-code/):階層化メモリ、5段階の compaction、permissions と hooks を備えた、完全な agent 実行環境です。+- [Codex の harness 設計を読み解く](./codex/):リポジトリを唯一の事実源とし、AGENTS.md を目次ページとして使い、環境分離とフィードバックループを構築します。+- [DeepSeek Harness の設計を読み解く](./deepseek/):Everything is a Plugin。agent ループそのものを交換可能な plugin にします。++## 読み方++まず講義の前半、特に[講義02:Harness とは実際に何か](../lectures/lecture-02-what-a-harness-actually-is/)を読み、5つのサブシステムのフレームワークを理解してから、ここに戻って実際の製品がこれらのメカニズムをどう実装しているかを見ることをおすすめします。++各記事の末尾には「講義のフレームワークへのマッピング」と「参考にしたい設計」という2つのセクションがあります。製品設計を講義の概念へすばやく置き換え、自分のプロジェクトへ直接取り入れやすくするためのものです。diff --git a/docs/ja/harness-designs/pi/index.md b/docs/ja/harness-designs/pi/index.mdnew file mode 100644index 0000000..52e6e17--- /dev/null+++ b/docs/ja/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Pi の harness 設計を読み解く++[Pi](https://pi.dev/)(npm パッケージ `@earendil-works/pi-coding-agent`)は、自らを "minimal agent harness"、つまり最小限の agent harness と称しています。この表現は分解して読む価値があります。「最強の coding agent」とも「最も使いやすい AI コーディングツール」とも名乗らず、**harness** という言葉に自らの位置づけを明確に定めているからです。++この記事では、講義の5つのサブシステム(指示、ツール、環境、状態、フィードバック)のフレームワークを使って Pi を読み解き、その設計思想が Claude Code や Codex と根本的にどう異なるかを見ていきます。先に答えを示すと、**Pi の思想は「コアの最小化 + 拡張のプログラム可能化」です。コンテキストエンジニアリングを system prompt の外側まで広げ、Pi が harness を決めるのではなく、利用者(さらには Pi 自身)が harness を変更できるようにします。**++## 一言で表すと++Pi は最小限のコアです。公式の位置づけでは、意図的にコアを小さくし、決定権を利用者へ戻しています。[pi.dev のホームページ](https://pi.dev/)には、"Ask Pi to build what you want, or install a package that does it your way" とあります。Pi は、harness を4層のカスタマイズ可能な要素に分けています。++- **Extensions**:Pi のライフサイクルイベントに接続する TypeScript hooks。runtime レベルのプログラム可能なインターフェースです。+- **Skills**:指示とツールを含み、オンデマンドで読み込まれる能力パッケージです。progressive disclosure を採用しています。+- **Prompt templates**:再利用可能な Markdown prompt で、`/name` と入力すると展開できます。+- **Themes**:TUI の外観です。++この階層化の考え方自体が、一つの harness 設計です。**「モデルに何を見せるか、いつ見せるか」を、コアへハードコードせず、ルールと拡張へ完全に委ねています。**++## 中核ループ++Pi は、ほかのすべての coding agent と同様、本質的には「推論 → ツール実行 → 観察 → 再推論」という while ループです。注目すべきなのはループ自体ではなく、Pi がループの外側をどう扱うかです。コンテキスト管理を、ループ内部での「compaction」から、ループ外部での「制御」へと拡張しています。++Pi の runtime は、外部にプログラム可能なインターフェースを公開しています。[ソース README の Programmatic Usage](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)によると、対話型 TUI に加えて、スクリプト化された print/JSON モード、RPC プロトコル、SDK への組み込みにも対応しています。これにより、同じ harness を人間が一つずつ操作することも、CI/CD や別のプログラムが自動操作することもできます。これは講義13「ループエンジニアリング」の「手動駆動から自動ループへ」の前提に対応します。人間の対話でしか操作できない harness は、決して自動ループへ移行できません。++## 指示サブシステム:AGENTS.md と SYSTEM.md++Pi の「指示」の扱いは抑制的ですが、階層は明確です。++- **AGENTS.md**:[ソース README の Project Context Files](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)には、読み込み順序が明記されています。グローバルの `~/.pi/agent/AGENTS.md` → 親ディレクトリを上へ順にたどる → 現在のディレクトリの `./AGENTS.md` です(CLAUDE.md にも対応)。これは「リポジトリを唯一の事実源にする」という原則の実践です。指示はチャット欄での念押しではなく、ファイルとして存在します。+- **SYSTEM.md**:[pi.dev 公式ドキュメント](https://pi.dev/docs/usage/project-context)によると、プロジェクト単位でデフォルトの system prompt を置き換える(replace)か、追記する(append)ことができます。これは Pi が「system prompt」の変更を許可する唯一の公式インターフェースであり、「環境の自己記述」層でもあります。++Pi 公式は、system prompt 自体が**最小限**であることを強調しています。その背後には明確なトレードオフがあります。コアに「もし……なら……」という長大なルールを詰め込まず、拡張点を用意し、ルールが必要なときだけ Skills や Extensions として現れるようにするのです。これは講義04「単一の巨大な指示ファイルが失敗する理由」と直接対応しています。Pi は「最小限のコア + ファイル分割 + オンデマンド読み込み」によって、巨大な指示ファイルの問題を自然に回避しています。++## 状態とコンテキスト:Pi が最も細かく分解した領域++Pi のコンテキストエンジニアリングは、重点的に見る価値があります。講義で扱った「コンテキスト継続性」「コンテキストの劣化を防ぐ」といった概念を、具体的なメカニズムへ落とし込んでいるからです。++**1. Compaction をプログラム可能にする。** コンテキスト上限に近づくと、古いメッセージを自動的に要約します。[pi.dev 公式ドキュメント](https://pi.dev/docs/usage/sessions)によると、compaction 戦略自体を**カスタマイズ可能**です。Extensions を使って、トピック単位の compaction、コードを認識した要約を実装でき、要約用に別のモデルを使うことさえできます。ソース README にはデフォルトの仕組みの詳細もあります。自動 compaction は2つの場合(コンテキストオーバーフローからの復旧/保持しきい値の超過)に発動し、分割点より後の直近約2万 token を保持します。それより前のメッセージは "context handoff" に要約され、段階的に連鎖して compaction されます。つまり Pi は、「どう compaction するか」を変更不能な定数ではなく、harness の一部として扱っています。++**2. Dynamic context。** [pi.dev 公式ドキュメント](https://pi.dev/docs/usage/extensions)によると、Extensions は各推論の前にメッセージを注入し、メッセージ履歴をフィルタリングし、RAG を実装し、長期メモリを構築できます。「コンテキストが満杯になったら compaction する」より一歩進み、情報がコンテキストウィンドウへ入る前に、何を入れ、何を入れないかを決められます。講義の「agent の実行プロセスを観察・デバッグ可能にする」「コンテキスト継続性を保つ」に対応し、Pi はこの2つを拡張インターフェースへ移しています。++**3. Session tree。** [pi.dev のホームページ](https://pi.dev/)には、"sessions are stored as trees" と明記されています。`/tree` で履歴上の任意のノードへ戻って続行でき、すべての分岐が同じファイルに保存されます。これは講義が繰り返し強調する「session をまたぐコンテキストの断絶」を解決します。要約だけで無理につなぐのではなく、構造化された履歴のリプレイを使います。分岐は HTML にエクスポートしたり、gist へアップロードして共有したりできるため、可観測性も同時に確保されます。++## ツールサブシステム:Skills と Extensions++Pi の「ツール」は2層に分かれています。++- **Skills**:[ソース README の Skills セクション](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)では、"self-contained capability packages that the agent loads on-demand"、つまり agent がオンデマンドで読み込む自己完結型の能力パッケージと明確に定義されています。指示とツールを含み、Agent Skills 標準に準拠します。progressive disclosure により、Skill の詳細はトリガーされたときだけコンテキストへ入り、**prompt cache を圧迫しません**。これはコストの観点からの harness 設計です。コンテキストの token が1つ増えるたびに、推論ごとにそのコストがかかります。Skills をオンデマンド読み込みにすることは、「説明書ではなく地図を渡す」という原則の別表現です。+- **Extensions**:組み込みのライフサイクルイベントに接続する TypeScript hooks です。[ソース README の Hooks セクション](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)には、公式の用途例として、危険なコマンドの阻止(permissions のゲート)、タスク切り替え時のコード状態の checkpoint、パスの保護(`.env` などへの書き込み禁止)、モデルへ渡す前のツール出力の変更、外部(ファイル監視/Webhook/CI)からのメッセージ注入による agent の起動が挙げられています。これらの hooks API は `@mariozechner/pi-coding-agent/hooks` からもエクスポートされています。コミュニティの harness([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness))は、hooks のインターフェースをさらにラップし、skill-router、session-summary、extract-patterns、telemetry など、すぐに使える Extensions を提供しています。++Extensions は Pi における最も重要な設計判断です。**単に「いくつかの設定スイッチをユーザーへ渡す」のではなく、runtime 内部のイベントインターフェースをすべて公開しています。** メモリを追加したいなら、`agent/pre-step` で注入します。動作を記録したいなら、session イベントを購読します。モデルへのリクエストを変更したいなら、`agent/request` に hook します。Pi に自分自身の harness を変更させることもできます。これはどのような「設定項目」よりも、「プログラム可能な harness」という定義に近いものです。++## フィードバックと検証:「学習」も harness にする++Pi 自体には、強制的なテストゲートは組み込まれていません(検証コマンドは利用者が AGENTS.md に記載します)。しかし、コミュニティの harness([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness))は、Extensions により「フィードバックループ」を構造化しています。公式 README の Hooks セクションにも、類似メカニズムの基盤が示されています。++- **session-summary**(pi-agent-harness の Extension):`PROGRESS.md` のローリングエントリを維持します。これは講義における状態サブシステムであり、長いタスクの進捗追跡です。+- **extract-patterns**(pi-agent-harness の Extension):session から教訓の候補を集め、`LESSONS.md` へ蓄積します。「各 session の終了前にハンドオフを整える」ことを、約束事からメカニズムへ変えます。+- **telemetry**(pi-agent-harness の Extension):token 使用量やコストなどを記録し、可観測性を提供します。++同じコミュニティリポジトリは、このパターンをさらに実証しています。`VISION.md`(目標)、`PROGRESS.md`(進捗)、`LESSONS.md`(教訓)、`STANDARDS.md`(標準)は、すべて Markdown ファイルとして session をまたいで永続化されます。これは講義が推奨する「リポジトリを唯一の事実源にする + 進捗ファイル + ハンドオフメカニズム」とまったく同じパターンですが、Pi の拡張メカニズムによってすぐに使える層になっています。++## 講義のフレームワークへのマッピング++講義の5つのサブシステムで Pi を評価します(主観的な評価であり、比較用です)。++| サブシステム | Pi の実装 | 評価 |+| --- | --- | --- |+| 指示 | AGENTS.md の階層的読み込み + SYSTEM.md | 階層は明確だが、ルール自体はユーザーが書く必要がある |+| ツール | Skills のオンデマンド読み込み + Extensions の全ライフサイクル hooks | 非常に強力。ツールシステムをプログラム可能なインターフェースにしている |+| 環境 | SYSTEM.md で環境を自己記述。runtime 環境はユーザーが AGENTS.md に宣言 | メカニズムは開かれているが、再現性はユーザーの自己記述に依存する |+| 状態 | session tree + カスタマイズ可能な compaction + PROGRESS.md | 非常に強力。session をまたぐ継続性と復元性が中核 |+| フィードバック | 検証コマンドはユーザーが定義。session-summary / extract-patterns でメカニズム化 | メカニズムは提供され、内容はユーザーに委ねられる |++Pi のトレードオフは、Claude Code / Codex と鮮明な対照をなします。Claude Code は「メモリ、permissions、subagent」をコアへ組み込み、すぐに使えるようにしています。Codex は「リポジトリ規約、環境分離」をデフォルトにしています。Pi は、**何も代わりに決めない**ことを選び、決定権を拡張点にしています。その代わり、自分で Extensions を書くか、他者のパッケージをインストールする必要があります。++## 参考にしたい設計++1. **compaction 戦略をプラグ可能にする**。harness における「コンテキストをどう compaction するか」は、ハードコードされたパラメータではなく、交換可能な戦略インターフェースにすべきです。+2. **硬い要約の代わりに session tree を使う**。session をまたぐ復元は、必ずしも「前回の要約」に頼る必要はありません。構造化された履歴のリプレイのほうが、状態サブシステムとして信頼できる場合があります。+3. **prompt cache を意識する**。Skills をオンデマンドで読み込み、すべてのルールを一度に system prompt へ詰め込まないことは、コンテキストエンジニアリングであると同時に、コストエンジニアリングでもあります。+4. **agent が自分の harness を変更できるようにする**。harness の拡張インターフェースが十分に開かれていれば、「agent の動作を最適化する」こと自体を agent が半自動で行えます。++## 参考資料(原文 / ソースコード)++以下の原文またはソースコードから各主張を確認できるため、印象に基づく説明ではありません。++- **pi.dev 公式サイト**:"Ask Pi to build what you want, or install a package that does it your way" という位置づけ、4層のカスタマイズ可能な要素、session tree("sessions are stored as trees"、`/tree`、単一ファイルへの保存、HTML へのエクスポート / gist での共有)。<br/>https://pi.dev/+- **pi.dev 公式ドキュメント · Sessions**:プラグ可能な compaction(topic-based / code-aware / 要約モデルの変更)、自動 compaction と dynamic context 注入のメカニズム。<br/>https://pi.dev/docs/usage/sessions+- **pi.dev 公式ドキュメント · Extensions**:各推論前のメッセージ注入、履歴のフィルタリング、RAG、長期メモリの構築。<br/>https://pi.dev/docs/usage/extensions+- **pi.dev 公式ドキュメント · Project Context**:SYSTEM.md の replace / append のセマンティクス。<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent ソース README**(badlogic/pi-mono):AGENTS.md の3段階の読み込み順序(グローバル → 親ディレクトリ → 現在のディレクトリ)、`/compact` と自動 compaction の発動条件および2万 token の分割点、Skills のオンデマンド読み込みと Agent Skills 標準、Hooks のライフサイクルと公式の用途例、Programmatic Usage(JSON / RPC / SDK)。<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness コミュニティリポジトリ**:skill-router / session-summary / extract-patterns / telemetry Extensions、VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md のファイル体系。<br/>https://github.com/LabidySabidy/pi-agent-harness++関連講義:[講義02 · Harness とは実際に何か](../lectures/lecture-02-what-a-harness-actually-is/) | [講義05 · セッションをまたいでコンテキストを保つ](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [講義13 · 手動駆動から自動ループへ](../lectures/lecture-13-loop-engineering/)diff --git a/docs/ja/index.md b/docs/ja/index.mdindex d1d9f44..f539d86 100644--- a/docs/ja/index.md+++ b/docs/ja/index.md@@ -25,6 +25,10 @@ Learn Harness Engineering は、AI コーディングエージェントを工程<h3>リソースライブラリ</h3><p>自分のリポジトリにそのまま使える AGENTS.md や feature_list.json などのテンプレートです。</p></a>+ <a href="./harness-designs/" class="card">+ <h3>最前線の Harness 設計を読み解く</h3>+ <p>Pi、Claude Code、Codex、DeepSeek が実際にどう harness を設計しているかを、このコースの理論で紐解きます。</p>+ </a></div>## Harness の中核メカニズムdiff --git a/docs/ko/harness-designs/claude-code/index.md b/docs/ko/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..7cac3ee--- /dev/null+++ b/docs/ko/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Claude Code의 harness 설계 분석++Anthropic은 《[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)》에서 신뢰성은 모델이 아니라 harness에서 나오며, agent는 "모델 바깥"에서 제약되어야 한다고 분명히 말합니다. Claude Code는 이 아이디어를 제품화한 사례이며, Anthropic도 이를 **agentic harness** 범주에 직접 포함합니다. 이는 마케팅 문구가 아닙니다. Claude Code는 현재 공개적으로 가장 철저히 분석된 harness일 수 있습니다. 소스 코드가 공개되어 있고 커뮤니티 연구 보고서도 상세하며, 강의에 나오는 거의 모든 핵심 메커니즘(계층형 메모리, 컨텍스트 compaction, permissions, hooks, subagent, session 영속화)을 완전한 제품 구현으로 만들었습니다.++이 글에서는 강의의 다섯 가지 하위 시스템 프레임워크로 Claude Code를 분석하고, "컨텍스트 관리", "조기 완료 선언 방지", "결정론적 제약"이라는 harness의 근본 개념을 어떻게 구현했는지 중점적으로 살펴봅니다.++## 한 문장으로 정의하기++Claude Code의 핵심은 모델 호출, 도구 실행, 결과 관찰, 모델 재호출을 반복하는 단순한 while 루프입니다. 그러나 **코드 대부분은 이 루프 안이 아니라 루프를 둘러싼 시스템에 있습니다**. permissions 시스템, 컨텍스트 compaction 파이프라인, 확장 메커니즘, subagent 오케스트레이션, session 저장소가 그것입니다. 이것이 harness의 본질입니다. 루프는 골격일 뿐이며, 골격 바깥의 모든 것이 신뢰성을 결정합니다.++## 명령 하위 시스템: 계층형 메모리 체계++Claude Code의 메모리 시스템은 harness 이론에 대한 가장 직접적인 기여이며, 강의의 "저장소가 사실의 원천"과 "session 간 컨텍스트 연속성"에 대응합니다. [공식 문서 《How Claude remembers your project》](https://code.claude.com/docs/en/memory)는 각 session이 완전히 새로운 컨텍스트 창에서 시작하며, 두 가지 메커니즘으로 session 간 지식을 전달한다고 명시합니다. 바로 CLAUDE.md 파일(사용자가 작성한 명령)과 auto memory(Claude가 직접 작성한 메모)입니다.++공식 문서는 범위에 따라 CLAUDE.md 파일을 네 종류로 구분합니다(로드 순서상 넓은 범위에서 좁은 범위 순).++- **조직 정책 수준**: IT/DevOps가 일괄 관리하며(예: `/etc/claude-code/CLAUDE.md`) 회사 수준 규범을 담습니다.+- **사용자 수준 `~/.claude/CLAUDE.md`**: 여러 프로젝트에 적용되는 개인 선호와 규칙입니다.+- **프로젝트 수준 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`**: 프로젝트 수준의 사실 원천으로, 엔지니어링 구조, 기술 스택, 검증 명령을 담고 저장소에서 공유합니다.+- **로컬 수준 `./CLAUDE.local.md`**: 프로젝트 안의 개인 선호를 담으며, 일반적으로 `.gitignore`에 추가해 커밋하지 않습니다.++이 외에도 두 가지 메커니즘이 있습니다.++- **하위 디렉터리 수준의 필요 시 로드**: 하위 디렉터리의 CLAUDE.md는 시작할 때 로드하지 않고, Claude가 해당 디렉터리의 파일을 읽을 때 컨텍스트에 들어갑니다.+- **자동 메모리(auto memory)**: Claude가 사용자의 수정과 선호를 바탕으로 능동적으로 메모를 작성합니다. 저장소 단위로 공유되고 여러 worktree에 적용되며, 각 session에서는 최대 첫 200줄 또는 25KB를 로드합니다.++이 네 가지 범위는 하나의 **명령 계층**을 이룹니다. 공식 문서에 따르면 "더 구체적인 명령일수록 컨텍스트에 더 늦게 들어갑니다"(프로젝트 명령은 사용자 명령 뒤에 나타남). 그 가치는 모델이 대화를 시작할 때마다 하나의 거대한 명령 문서를 전부 소화하는 대신, 범위에 따라 가까운 곳의 명령을 로드하는 데 있습니다. 이는 강의 4 "왜 하나의 거대한 명령 파일이 실패하는가"에 대한 제품화된 답입니다.++## 컨텍스트 하위 시스템: 5단계 compaction 파이프라인++Claude Code는 컨텍스트를 단순히 "가득 차면 요약"하는 것이 아니라 **5단계 compaction 파이프라인**(five-layer compaction pipeline)으로 관리합니다. 이 아키텍처의 세부 사항은 [VILA Lab의 《Dive into Claude Code》](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)가 소스 코드 수준에서 분석한 내용입니다. 강의 5에서는 "장기 작업이 연속성을 잃는 이유"를 다룹니다. Claude Code의 해법은 다단계 깔때기입니다. 먼저 무손실 가지치기(중복된 도구 결과 제거)를 수행하고, 그다음 구조화된 정제를 거친 뒤, 마지막에야 손실이 있는 LLM 요약을 사용하며, 과도한 compaction을 막는 회로 차단 메커니즘도 함께 둡니다.++여기에 **추가 지향 session 저장소(append-oriented storage)** 설계가 결합됩니다. 모든 기록을 `history.jsonl`에 추가하고 `/resume` 복구와 fork 브랜치를 지원합니다. 이로써 "각 session이 끝나기 전에 인계를 잘한다"는 것을 보장합니다. 기억력이 좋아서가 아니라 저장 계층이 추가 지향적이고 재생 가능하기 때문입니다.++## 도구 하위 시스템: 네 가지 확장 메커니즘++Claude Code는 확장 표면을 네 종류로 나누며, 각각 서로 다른 문제를 해결합니다. 이 부분은 설계에서 가장 참고할 만합니다.++- **스킬(Skills)**: [공식 문서](https://code.claude.com/docs/en/skills)의 정의에 따르면 `SKILL.md`에 기술된 절차적 지식이며, 트리거 단어에 따라 자동으로 로드되고 점진적 공개를 사용합니다. "어떤 일을 하는 방법"에 관한 도메인 지식에 적합합니다.+- **MCP**: [공식 문서](https://code.claude.com/docs/en/mcp)의 JSON-RPC 프로토콜로 외부 시스템에 연결하며, "모델의 손이 외부 세계에 닿게 하는" 표준 인터페이스입니다.+- **Hooks**: [공식 문서](https://code.claude.com/docs/en/hooks)에 설명된 대로 `PreToolUse`, `PostToolUse`, `Stop` 등의 생명주기 이벤트에 연결되는 결정론적 스크립트입니다.+- **Plugin / Subagents**: [공식 문서](https://code.claude.com/docs/en/sub-agents)에 따라 복잡한 작업을 전문화된 agent에게 나누어 맡깁니다.++핵심 설계는 **책임 분리**입니다. CLAUDE.md는 "무엇인가"를, 스킬은 "어떻게 하는가"를, MCP는 "어디에 연결하는가"를, hooks는 "언제 강제하는가"를 담당합니다. 팀이 이 계층을 뒤섞으면(예: MCP가 해야 할 일을 CLAUDE.md에 작성) 강의에서 설명한 컨텍스트 누수가 발생합니다.++## 피드백과 검증: 결정론적 제약 + 인간과 기계의 역할 분담++강의 10은 "전체 흐름을 실행해야 진짜 검증이다"라고 설명합니다. Claude Code는 이에 대응해 두 갈래의 메커니즘을 사용합니다.++**1. Permissions 시스템(결정론적 제약).** Claude Code의 permissions는 "모든 것을 한 번씩 묻는" 방식이 아니라 일곱 가지 모드와 ML 기반 분류기로 구성됩니다. 저위험 작업은 허용하고 고위험 작업은 정책에 따라 질문하거나 거부합니다(아키텍처 세부 사항은 [VILA Lab 분석](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf) 참고). 이는 "agent의 경계를 명확히 정하기"(강의 7)를 프롬프트로 간청하는 대신 런타임에서 강제한 것입니다.++**2. Hooks(조기 완료 선언 방지).** `PostToolUse` hooks는 도구 실행 후 검사를 강제로 실행하고 결과를 컨텍스트에 기록할 수 있으며, `Stop` hooks는 agent가 완료를 선언할 때 개입합니다. 이는 "작업하는 역할과 검사하는 역할의 분리"입니다. [Anthropic은 harness 글에서](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) agent가 자신의 작업을 자신 있게 칭찬("confidently praised their work")하는 현상을 명확히 관찰했습니다. 따라서 모델의 자기 평가를 신뢰하는 대신 hooks로 **결정론적** 검사를 주입합니다.++**3. Subagent(컨텍스트 격리).** 각 subagent의 대화 기록은 독립된 sidechain 파일에 저장되어 **부모 agent의 컨텍스트를 부풀리지 않습니다**([VILA Lab 분석](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf) 참고). 이는 "작업 경계"와 "컨텍스트 격리"를 결합한 것입니다. 작업을 나누는 동시에 컨텍스트 오염도 격리합니다.++## 관찰 가능성과 session 영속화++Claude Code의 로그는 추가 방식의 완전한 기록(history.jsonl)이며, `/compact`, `/clear`, `/init` 같은 명시적 명령을 제공하므로 컨텍스트가 가득 찰 때까지 수동적으로 기다리지 않고 상태를 능동적으로 관리할 수 있습니다. `/init`은 "agent가 매번 작업 전에 먼저 초기화하게 하기"(강의 6)를 하나의 명령으로 구현합니다. [공식 문서](https://code.claude.com/docs/en/memory)에 따르면 이 명령은 코드베이스를 자동으로 분석하고 빌드 명령, 테스트 설명, 엔지니어링 규약을 포함한 초기 CLAUDE.md를 생성합니다.++## 강의 프레임워크에 매핑하기++| 하위 시스템 | Claude Code의 구현 | 평가 |+| --- | --- | --- |+| 명령 | 범위별 계층화(조직/사용자/프로젝트/로컬) + 자동 메모리 | 계층형 메모리의 모범 구현 |+| 도구 | 스킬 + MCP + hooks + subagent의 네 가지 확장 | 책임 구분이 명확하며 핵심 강점 |+| 환경 | 프로젝트 내 설정 + settings.json | CLAUDE.md에서 사용자가 직접 설명하는 데 의존 |+| 상태 | 추가 지향 session 저장소 + 5단계 compaction + resume/fork | 매우 강력하며 장기 작업 연속성의 참고 구현 |+| 피드백 | permissions 분류기 + PostToolUse hooks 강제 검사 | "조기 완료 선언 방지"를 결정론적 메커니즘으로 만듦 |++## 참고할 만한 설계++1. **명령을 한 파일에 쌓지 말고 범위별로 계층화하세요.** 디렉터리 수준 CLAUDE.md는 "가까운 곳에서 로드"하는 훌륭한 구현입니다.+2. **Compaction은 단계별 깔때기입니다.** 무손실 처리를 먼저 하고 손실 처리를 나중에 하며, 처음부터 전체 내용을 요약하지 마세요.+3. **Hooks로 결정론적 검사를 수행하세요.** 조기 완료 선언을 막는 것은 프롬프트의 간청이 아니라 런타임 강제입니다.+4. **Subagent의 컨텍스트를 격리하세요.** 작업과 컨텍스트를 함께 분리해 하위 작업 결과가 메인 루프를 오염시키지 않게 하세요.+5. **Session 저장소는 추가 지향적으로 만들고 재생 가능하게 하세요.** 인계는 기억이 아니라 저장 계층으로 보장합니다.++## 참고 자료(원문 / 소스 코드)++각 주장은 인상에 의존한 전달을 피하기 위해 아래 원문이나 소스 코드로 거슬러 올라갈 수 있습니다.++- **Claude Code 공식 문서 · Memory**: 각 session의 새로운 컨텍스트, CLAUDE.md의 네 가지 범위, 하위 디렉터리 필요 시 로드, auto memory(200줄 / 25KB), `/init`의 CLAUDE.md 생성.<br/>https://code.claude.com/docs/en/memory+- **Claude Code 공식 문서 · Skills / MCP / Hooks / Sub-agents**: 네 가지 확장 메커니즘과 이벤트(PreToolUse / PostToolUse / Stop)의 정의.<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab 《Dive into Claude Code》**(소스 코드 수준 분석 보고서): 5단계 compaction 파이프라인, 일곱 가지 permissions 모드 + ML 분류기, sidechain subagent, 추가 지향 session 저장소 history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic 《Effective harnesses for long-running agents》**: "신뢰성은 모델이 아니라 harness에서 나온다", agent가 자신의 작업을 자신 있게 칭찬한다는 관찰, hooks를 이용한 검증 등의 출처.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack 가이드**(커뮤니티, CLAUDE.md / Skills / MCP / Subagents / Hooks 계층): 확장 메커니즘의 책임 분리에 관한 추가 읽을거리.<br/>https://jsmanifest.com/claude-code-full-stack-guide++관련 강의: [강의 3 · 코드 저장소를 유일한 사실의 원천으로 만들기](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [강의 9 · agent의 조기 완료 선언 방지하기](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [강의 10 · 전체 흐름을 실행해야 진짜 검증이다](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/ko/harness-designs/codex/index.md b/docs/ko/harness-designs/codex/index.mdnew file mode 100644index 0000000..1fa658a--- /dev/null+++ b/docs/ko/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Codex의 harness 설계 분석++OpenAI의 [Codex](https://openai.com/index/harness-engineering/)는 네 제품 중 "harness의 근본 원칙"과 가장 깊이 결합되어 있을 수 있습니다. 이 분야 전체의 이름을 정의한 《Harness Engineering》은 OpenAI 팀이 Codex로 제품을 만들며 얻은 경험을 정리한 글이기 때문입니다. 따라서 Codex의 harness 설계를 분석하는 것은 상당 부분 그 글의 배경이 된 엔지니어링 실천을 분석하는 일입니다.++Codex의 철학은 한 문장으로 압축할 수 있습니다. **저장소가 사실의 원천(repository as the system of record)이고, AGENTS.md는 디렉터리 페이지일 뿐이며, 엔지니어링의 가치는 환경을 설계하고 의도를 표현하며 피드백 루프를 구축하는 데 있습니다.**++## 한 문장으로 정의하기++OpenAI 팀은 Codex를 사용해 몇 주 만에 최종적으로 100만 줄이 넘는 규모가 된 제품을 출시했으며, **모든 코드 줄을 Codex가 작성했습니다**(원문은 [Harness Engineering](https://openai.com/index/harness-engineering/)의 "Designing for growth" 섹션 참고). 이들의 실천은 엔지니어의 역할이 "코드 작성"에서 "harness 설계"로 바뀔 때 시스템을 어떻게 구성해야 하는지에 답합니다. Codex CLI 자체는 Rust로 구현된 오픈 소스 단일 바이너리([github.com/openai/codex](https://github.com/openai/codex))이지만, harness에 대한 Codex의 기여는 화려한 확장 지점보다 **규약(convention)**과 **컨텍스트 엔지니어링**에 집중되어 있습니다.++## 명령 하위 시스템: AGENTS.md는 백과사전이 아니라 디렉터리 페이지++이는 harness 이론에 가장 큰 영향을 미친 Codex의 설계 원칙입니다.++> 하나의 거대한 명령 파일은 커버리지, 업데이트 상태, 소유권, 교차 링크를 기계적으로 검사하기 어렵고 현실과 어긋나는 일을 피할 수 없습니다. 따라서 우리는 AGENTS.md를 백과사전으로 보지 않고 **디렉터리 페이지**로 봅니다. 코드베이스 지식은 구조화된 문서 안에 있고, AGENTS.md는 그 문서들을 가리킵니다.++(위 내용은 [《Harness Engineering》 원문](https://openai.com/index/harness-engineering/)의 "AGENTS.md should be a directory page" 섹션을 직접 옮긴 것입니다.)++강의 4는 "하나의 거대한 명령 파일이 실패한다"고 설명합니다. Codex는 그 정답을 직접 제시합니다. AGENTS.md를 약 100줄로 제한하고(원문은 약 100줄을 권장하며, 상한에 가까워지면 `docs/`로 분리), 담을 수 없는 내용은 `docs/` 디렉터리로 나누어 agent가 필요할 때 읽게 합니다. 이것이 "설명서가 아니라 지도를 제공하라"는 원칙의 권위 있는 출처입니다.++함께 적용되는 원칙은 **구현을 세세하게 관리하지 말고 불변 조건을 실행하라**(원문: "don't micromanage the implementation;focus on invariants")입니다. AGENTS.md에는 어길 수 없는 강제 제약과 검증 명령만 작성하고, 구체적인 구현 방법은 모델에 맡깁니다. 이는 강의 2의 "세세한 지시가 아니라 제약"과 직접 대응합니다.++## 컨텍스트 하위 시스템: Write-Select-Compress-Isolate++Codex의 컨텍스트 엔지니어링은 네 가지 전략으로 요약할 수 있습니다. 이는 "context engineering"이 독립된 학문으로 자리 잡은 뒤 커뮤니티가 정리하여 Codex에 다시 매핑한 프레임워크입니다(출처: [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).++- **Write(밖으로 쓰기)**: 컨텍스트를 창 바깥에 영속화합니다. 결론은 문서에, 상태는 파일에 기록하고 대화 안에만 두지 않습니다. "저장소가 사실의 원천"이라는 원칙에 대응합니다.+- **Select(안으로 선택하기)**: 필요한 token만 창으로 가져옵니다. 전체 저장소를 밀어 넣지 않고 AGENTS.md가 길을 안내하며 파일은 필요할 때 읽습니다.+- **Compress(compaction)**: 정말 중요한 것만 남깁니다. Codex는 자동 compaction과 수동 `/compact`를 제공하며 `compact_prompt`를 맞춤 설정할 수 있습니다([Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) 참고).+- **Isolate(격리)**: 컨텍스트를 서로 다른 경계로 나눕니다. subagent로 서로 다른 작업의 컨텍스트를 격리하면, 프런트엔드 subagent는 백엔드의 데이터베이스 schema를 전혀 보지 않습니다.++Codex에는 매우 세밀한 환경 컨텍스트 설계도 있습니다. 커뮤니티의 [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) 소스 분석에 따르면, `build_environment_update_item`은 매번 전체 시스템 컨텍스트를 다시 붙이지 않고 환경이 바뀔 때만 **변경된 필드**(CWD, git 브랜치, 파일 시스템)를 출력합니다. 이는 "컨텍스트에 중복 token을 쌓아 두지 않는다"는 엔지니어링 세부 사항입니다.++## 도구와 경계: worktree 격리 + subagent++Codex에는 두 가지 핵심 harness 메커니즘이 있습니다.++**1. git worktree로 환경 격리.** [《Harness Engineering》 원문](https://openai.com/index/harness-engineering/)의 "Environment" 섹션에 따르면 각 작업은 독립된 git worktree에서 실행되며, 로컬 관찰 가능성 스택(로그, 메트릭, 트레이스)을 결합해 각 변경 사항을 독립된 환경에서 검증합니다. 이는 강의 7 "agent의 각 작업 경계를 명확히 정하기"를 물리적으로 구현한 것입니다. 프롬프트로 경계를 지켜 달라고 간청하지 않고 환경 격리로 강제합니다. 여기서는 환경(environment) 하위 시스템을 강제로 격리합니다.++**2. 커널 수준 subagent.** Codex의 `spawn_agent` / `wait_agent`는 커널 수준 도구입니다. 모델이 명시적으로 subagent를 생성하고, 독립된 session 기록과 도구 세트를 제공한 뒤 결과를 기다립니다. subagent는 부모의 AGENTS.md 명령을 상속하지만 **자신의 컨텍스트**에서 실행됩니다. 설정은 `.codex/agents/*.toml`에 두며 서로 다른 모델과 명령을 지정할 수 있습니다(세부 사항은 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)의 Sub-agents 섹션 참고). 이는 "컨텍스트 격리"를 직접 구현하며, 강의 12의 "인계" 정신도 반영합니다. 각 subagent는 명확한 경계가 있는 하나의 작업 단위입니다.++## 피드백 하위 시스템: 규약에 검증 명령 작성하기++OpenAI의 실천에서 가장 강조하는 점은 AGENTS.md에 검증 명령을 명시해 "올바르게 수행했는지 확인하는 방법"을 저장소의 일부로 만드는 것입니다. Codex의 엔지니어링 흐름에서는 테스트, CI, 문서, 관찰 가능성 설정을 모두 Codex가 생성하며, 모두 "실행 가능한 검증 경로"입니다. 강력하지만 신뢰할 수 없는 모델의 해법은 모델이 알아서 잘하기를 기도하는 것이 아니라 **검증 경로를 harness의 기본 구성 요소로 만드는 것**입니다.++승인 정책(approval policies)과 계획 모드(plan mode)는 피드백의 또 다른 방향입니다. 고위험 작업을 실행하기 전에 계획을 작성하고 승인을 요청함으로써 "작업 경계"와 "인간의 결정권"을 런타임 제어로 만듭니다.++## 강의 프레임워크에 매핑하기++| 하위 시스템 | Codex의 구현 | 평가 |+| --- | --- | --- |+| 명령 | AGENTS.md 디렉터리 페이지 + docs/ 분할 + 불변 조건 실행 | "설명서가 아니라 지도를 제공하라"를 정의한 교과서적 구현 |+| 도구 | worktree 격리 + spawn_agent subagent | 환경으로 경계를 강제 격리하므로 매우 강력함 |+| 환경 | 독립 worktree + 관찰 가능성 스택 | worktree 격리가 대표 특징 |+| 상태 | Write 전략(상태를 파일/문서에 기록) | 내장 메모리가 아니라 규약에 의존 |+| 피드백 | 검증 명령을 규약에 포함 + 승인 정책 + plan mode | 피드백 경로를 기본값으로 만든 참고할 만한 구현 |++Codex와 Claude Code의 대비는 흥미롭습니다. Claude Code는 메모리, permissions, subagent를 모두 커널에 넣는 "덧셈"이고, Codex는 커널을 최대한 절제하고 더 많은 책임을 저장소 규약과 컨텍스트 엔지니어링에 두는 "뺄셈"입니다. 커뮤니티에서 "Codex의 harness 철학이 코드보다 더 가치 있다"고 자주 말하는 이유이기도 합니다.++## 참고할 만한 설계++1. **AGENTS.md를 디렉터리 페이지로 작성하세요.** 약 100줄로 제한하고 docs/의 세부 내용을 가리키며 기계적으로 검사할 수 있게 하세요.+2. **불변 조건만 작성하고 구현을 세세하게 관리하지 마세요.** 강제 제약 + 검증 명령을 제공하고 나머지는 모델에 맡기세요.+3. **worktree로 환경을 격리하세요.** 작업 경계는 프롬프트의 간청이 아니라 환경으로 강제합니다.+4. **환경 컨텍스트는 변경분만 전달하세요.** 매번 전체 시스템 컨텍스트를 반복해서 붙이지 말고 변경된 필드만 출력하세요.+5. **subagent로 컨텍스트를 격리하세요.** 작업과 컨텍스트를 함께 분리해 하위 작업이 메인 루프를 오염시키지 않게 하세요.++## 참고 자료(원문 / 소스 코드)++각 주장은 인상에 의존한 전달을 피하기 위해 아래 원문이나 소스 코드로 거슬러 올라갈 수 있습니다.++- **OpenAI 《Harness Engineering》**: AGENTS.md 디렉터리 페이지와 약 100줄 권장, executive invariants / don't micromanage, worktree 격리 + 관찰 가능성 스택, 검증 명령의 규약화, 100만 줄이 넘는 제품 사례, 승인 정책과 plan mode. 이 글의 모든 핵심 주장의 주된 출처.<br/>https://openai.com/index/harness-engineering/+- **OpenAI 공식 《AGENTS.md》 규약**(여러 도구에서 사용하는 규약의 표준인 AGENTS.md):<br/>https://openai.com/index/agents-md/+- **Codex CLI 오픈 소스 저장소**(Rust로 구현한 단일 바이너리):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI**(커뮤니티): Write-Select-Compress-Isolate 프레임워크, `/compact`와 `compact_prompt`, `spawn_agent` / `wait_agent` subagent와 `.codex/agents/*.toml` 설정.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals**(커뮤니티 소스 분석): `build_environment_update_item`의 증분 환경 컨텍스트 등 구현 세부 사항.<br/>https://github.com/AlexKenbo/codex-harness-internals++관련 강의: [강의 3 · 코드 저장소를 유일한 사실의 원천으로 만들기](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [강의 4 · 명령을 여러 파일로 분리하기](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [강의 7 · agent의 각 작업 경계를 명확히 정하기](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/ko/harness-designs/deepseek/index.md b/docs/ko/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..4a85827--- /dev/null+++ b/docs/ko/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# DeepSeek Harness 설계 분석++[DeepSeek Harness](https://deepseek.com/harness)(명령 이름 `dsh`, 저장소 `deepseek-ai/deepseek-harness`)는 2026년 8월 Developer Preview로 출시되었으며, 공식 정의는 매우 직접적입니다. **Agent = Model + Environment + Tools + State**, 즉 모델, 환경, 도구, 상태의 네 가지 요소입니다.++앞선 세 제품의 분석이 "harness를 어떻게 설계해야 하는가"를 묻는다면, DeepSeek Harness는 더 급진적인 질문을 던집니다. **harness가 특정 모델에서 벗어나 독립적인 런타임이 될 수 있는가?** 대답은 그렇다는 것이며, 이를 극한까지 구현했습니다. [아키텍처 문서](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)의 원문은 다음과 같습니다. *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself*(모델 어댑터, 도구 레지스트리, session 로그, 심지어 agent 루프 자체까지 제품의 모든 부분이 plugin입니다).++이 글에서는 plugin 기반 커널, 능력 접합부(capability seam), 이벤트 파이프라인, 그리고 "Model-visible means logged"라는 가장 강력한 엔지니어링 제약을 중점적으로 분석합니다.++## 한 문장으로 정의하기++전통적인 coding agent의 구조는 "LLM + 고정된 agent 루프 + 고정된 도구 세트"입니다. DeepSeek Harness의 구조는 "모델 + plugin 커널(Cordis)"입니다. 커널은 plugin 로드, 언로드, 의존성, 이벤트 메커니즘만 담당하며 **agent의 구체적인 능력을 하나도 소유하지 않습니다**. [아키텍처 문서](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)의 원문은 "There is no privileged core to patch"(패치해야 할 특권 커널이 없음), "you extend dsh by mounting a plugin beside the others"(커널을 수정하지 않고 다른 plugin 옆에 하나를 마운트해 dsh를 확장함)입니다. 즉, agent 루프 자체도 수정할 수 없는 성역이 아닙니다. DeepSeek 모델에 Claude Code의 subagent를 연결하고, 원격 sandbox와 맞춤형 메모리를 추가하고, 사용자 정의 루프와 UI로 교체해 완전히 새로운 agent를 구성할 수 있습니다.++이는 "모델 가중치 바깥의 모든 것이 harness"라는 강의의 문장을 가장 철저히 실천한 것입니다. harness가 독립적이라면, 아예 독립된 운영 체제로 만드는 것입니다.++## 아키텍처 핵심 1: 능력 접합부(Capability Seam)++DeepSeek Harness는 "능력"을 Service로 표현하며, 거의 모든 능력을 세 계층으로 나눕니다.++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++파일 시스템을 예로 들면, `FS Service` 아래에 Local FS, E2B FS, Remote FS 등의 Provider가 있고 위쪽에는 통일된 file tools로 노출됩니다. Shell, Subprocess, Sandbox, Web, LLM, SubAgent도 같은 구조를 사용합니다. 이 3계층 구조는 여기서 요약한 것이 아닙니다. [아키텍처 문서 · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)의 원문은 *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool*(능력 접합부는 교체 가능한 능력으로서 세 가지 역할, 즉 인터페이스를 선언하는 Service Definition, 이를 구현하는 Service Provider, 이를 사용하는 Consumer로 구성되며, Consumer는 일반적으로 모델에 노출되는 도구임)입니다.++이는 harness 엔지니어링의 오랜 문제를 해결합니다. **agent는 "구체적인 도구"에 의존해야 하는가, "능력 인터페이스"에 의존해야 하는가?** DeepSeek Harness는 후자를 선택합니다. 강의 관점에서 보면 "도구 하위 시스템"을 인터페이스로 표준화한 것입니다. Provider를 교체해도 모델에 노출되는 도구의 모습은 그대로지만 환경은 완전히 달라집니다.++## 아키텍처 핵심 2: 이벤트 파이프라인(Event Pipeline)++DeepSeek Harness 내부는 단순한 "LLM → 도구 → LLM"이 아니라 이벤트 파이프라인이며, 각 단계가 plugin이 수신할 수 있는 이벤트 지점입니다.++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(위 파이프라인은 [아키텍처 문서 · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) 섹션을 옮긴 것입니다. `turn/*`, `step/*`, `user/message`, `assistant/*`, `tool/*`는 영속화되는 session 이벤트이며, `agent/pre-step`, `agent/request`, `llm/stream`, `tools/*`는 plugin이 수신할 수 있는 확장 지점입니다.)++이 설계의 가장 큰 장점은 **많은 기능이 agent 루프 자체를 수정하지 않아도 된다는 것**입니다. 도구 실행 전 안전 검사를 수행하고 싶다면 `tools/pre-execute`를 수신합니다. 메모리를 추가하려면 `agent/pre-step`에서 주입합니다. 동작을 기록하려면 session 이벤트를 구독합니다. 모델 요청을 수정하려면 `agent/request`에 hooks를 겁니다. 추론을 계속할지 결정하려면 `agent/turn-stopping`을 수신합니다.++강의 11 "agent 실행 과정을 관찰 가능하게 만들기"와 비교하면 DeepSeek Harness는 더 멀리 나아갑니다. 단순히 "로그를 추가"하는 것이 아니라 **루프의 모든 단계를 이벤트 지점으로 만들고**, 관찰, permissions, 메모리, 정책을 루프에 하드코딩하지 않고 모두 listener로 연결합니다.++## 아키텍처 핵심 3: Session Event Log와 "Model-visible means logged"++DeepSeek Harness에는 **append-only Session Event Log**가 있으며, 매우 강력한 엔지니어링 제약을 정했습니다. [아키텍처 문서 · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)의 원문은 다음과 같습니다.++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(모델이 볼 수 있는 것은 모두 기록되어야 합니다. 모델 요청에 들어가는 모든 것은 로그에서 재구성할 수 있어야 하며, 런타임 불변 조건이 이를 강제합니다.)++즉, 관찰 가능성은 사후에 추가하는 로그가 아니라 harness의 제1원칙입니다. 모델 컨텍스트에 들어가는 모든 내용은 기본적으로 로그를 남겨야 합니다. 이는 마지막 강의의 "관찰 가능성은 harness 내부에 속한다"는 내용과 직접 맞닿아 있으며, "append-only" 저장소 설계를 원칙으로 만듭니다. 로그는 덮어쓰지 않고 추가만 하므로 session 상태를 재생할 수 있습니다.++## 강의 프레임워크에 매핑하기++| 하위 시스템 | DeepSeek Harness의 구현 | 평가 |+| --- | --- | --- |+| 명령 | plugin 기반이며 규칙/스킬을 모두 plugin 형태로 주입 | 매우 자유롭지만 "CLAUDE.md" 같은 내장 규약은 없음 |+| 도구 | Service Definition → Provider → Consumer 능력 접합부 | 도구 하위 시스템 표준화의 극치 |+| 환경 | sandbox/FS/Shell의 Provider를 모두 교체 가능(원격 E2B 포함) | 환경이 완전히 교체 가능함 |+| 상태 | append-only Session Event Log + Model-visible means logged | 관찰 가능성이 제1원칙 |+| 피드백 | tools/pre-execute의 permission / guard / policy / hook | 피드백 메커니즘을 이벤트화함 |++DeepSeek Harness와 나머지 세 제품의 근본적인 차이는 다음과 같습니다. Pi, Claude Code, Codex가 모두 "하나의 구체적인 agent" 안에서 harness를 최적화한다면, DeepSeek Harness는 harness를 **모델과 독립된 운영 체제**로 정의하며 agent 자체는 이 OS에서 교체 가능한 하나의 애플리케이션일 뿐입니다. 대가도 분명합니다. 높은 자유도는 높은 설정 비용을 의미하며, 이는 "harness가 곧 OS"인 설계에 본질적으로 따르는 이면입니다(Developer Preview 단계 역시 "먼저 체험해 보는 단계이며 메커니즘이 아직 발전 중"이라는 포지셔닝입니다).++## 참고할 만한 설계++1. **루프의 모든 단계를 이벤트 지점으로 만드세요.** permissions, 메모리, 정책, 로그를 루프에 하드코딩하지 말고 listener로 연결하세요.+2. **능력 접합부를 표준화하세요.** "구체적인 도구"가 아니라 "능력 인터페이스"에 의존하면 모델이 보는 도구 표면에 영향을 주지 않고 환경 전체를 교체할 수 있습니다.+3. **Model-visible means logged.** 모델이 볼 수 있는 것은 모두 기록하여 관찰 가능성을 "가산점"이 아니라 "제1원칙"으로 만드세요.+4. **append-only session 로그를 사용하세요.** 상태를 재생할 수 있고 인계가 신뢰할 만해집니다. 이는 "각 session에 클린 상태를 남기기"를 엔지니어링으로 보장합니다.++## 참고 자료(원문 / 소스 코드)++각 주장은 인상에 의존한 전달을 피하기 위해 아래 원문이나 소스 코드로 거슬러 올라갈 수 있습니다.++- **DeepSeek Harness 공식 사이트**: 제품 정의 "Agent = Model + Environment + Tools + State", Developer Preview 포지셔닝과 `dsh` 명령.<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness 저장소**(`dsh` 명령, MIT 라이선스):<br/>https://github.com/deepseek-ai/deepseek-harness+- **아키텍처 문서 architecture.md**: 이 글의 가장 핵심적인 출처. "Every part of the product is a plugin", "There is no privileged core to patch", Turn flow 이벤트 파이프라인, Capability seams의 3계층 역할, "Model-visible means logged"와 런타임 불변 조건, append-only Session Event Log, fs/tools/telemetry 등의 능력 접합부와 `ctx.*` 하위 시스템.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **아키텍처 문서 · 관련 하위 문서**: Cordis 커널 소개(plugins contribute services, typed events, reversible effects), 능력 접합부 세부 사항, Session 하위 시스템.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++관련 강의: [강의 11 · agent 실행 과정을 관찰 가능하게 만들기](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [강의 12 · 각 session이 끝나기 전에 인계 완료하기](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [강의 2 · Harness란 정확히 무엇인가](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/ko/harness-designs/index.md b/docs/ko/harness-designs/index.mdnew file mode 100644index 0000000..8a24b41--- /dev/null+++ b/docs/ko/harness-designs/index.md@@ -0,0 +1,29 @@+# 최전선 Harness 분석++이 섹션에서는 강의에서 다룬 harness 이론을 현재 최전선의 실제 제품들과 하나씩 대조합니다. 각 제품에서 살펴볼 것은 단 하나, **harness를 어떻게 설계했는가**입니다. 즉, 모델을 둘러싼 엔지니어링 인프라인 명령, 도구, 환경, 상태, 피드백의 다섯 가지 하위 시스템과 컨텍스트 연속성, 초기화, 검증, 관찰 가능성, 인계, 루프 등의 핵심 메커니즘을 분석합니다.++모델의 추론 능력이 강한지, 특정 벤치마크 점수가 높은지는 의도적으로 다루지 않으며, "이 agent로 무엇을 할 수 있는가"도 포괄적으로 소개하지 않습니다. 그런 내용은 모델 계층과 제품 계층의 문제입니다. 여기서는 harness, 즉 모델 가중치 바깥의 모든 것만 분석합니다.++## 분석할 가치가 있는 이유++첫 번째 강의에서 설명했듯이 모델의 능력이 강하다고 해서 실행이 신뢰할 만한 것은 아닙니다. 같은 모델도 서로 다른 harness에 배치하면 성능이 한 자릿수 이상 차이 날 수 있습니다. 하지만 강의가 "어떻게 해야 하는가"를 설명한다면, 이 제품들은 "선도 팀이 실제로 어떻게 하는가"에 답합니다.++각 제품은 독립적인 설계 결정의 집합입니다. 이들을 나란히 비교하면, 서로 다른 팀이 같은 핵심 메커니즘을 완전히 다른 방식으로 구현한 모습을 볼 수 있습니다.++- **Pi**는 harness를 극도로 단순한 커널과 프로그래밍 가능한 확장으로 구성하고, "최소한의 시스템 프롬프트 + 필요할 때 로드"하는 방식으로 컨텍스트 엔지니어링을 수행합니다.+- **Claude Code**는 harness를 계층형 메모리, 5단계 compaction, permissions, hooks, subagent를 갖춘 완전한 실행 환경으로 만듭니다.+- **Codex**는 harness 철학을 극한까지 밀어붙입니다. 저장소를 사실의 원천으로 삼고 AGENTS.md는 디렉터리 페이지로만 사용하며, worktree로 환경을 격리합니다.+- **DeepSeek Harness**는 아예 harness 자체를 모델과 독립적인 런타임으로 정의합니다. Everything is a Plugin.++## 글 목록++- [Pi의 harness 설계 분석](./pi/): 극도로 단순한 커널 + 프로그래밍 가능한 확장으로, 시스템 프롬프트 바깥에 컨텍스트 엔지니어링을 구현합니다.+- [Claude Code의 harness 설계 분석](./claude-code/): 계층형 메모리, 5단계 compaction, permissions와 hooks를 갖춘 완전한 agent 실행 환경입니다.+- [Codex의 harness 설계 분석](./codex/): 저장소가 사실의 원천이고 AGENTS.md는 디렉터리 페이지이며, 환경 격리와 피드백 루프를 제공합니다.+- [DeepSeek Harness 설계 분석](./deepseek/): Everything is a Plugin. agent 루프 자체를 교체 가능한 plugin으로 만듭니다.++## 읽는 방법++먼저 강의의 앞부분, 특히 [강의 2: Harness란 정확히 무엇인가](../lectures/lecture-02-what-a-harness-actually-is/)를 읽어 다섯 가지 하위 시스템 프레임워크를 익힌 다음, 여기로 돌아와 실제 제품이 이 메커니즘을 어떻게 구현하는지 살펴보기를 권합니다.++각 글의 끝에는 "강의 프레임워크에 매핑하기"와 "참고할 만한 설계"라는 두 섹션이 있습니다. 제품 설계를 강의 개념으로 빠르게 변환해 자신의 프로젝트에 바로 적용할 수 있도록 도와줍니다.diff --git a/docs/ko/harness-designs/pi/index.md b/docs/ko/harness-designs/pi/index.mdnew file mode 100644index 0000000..870b383--- /dev/null+++ b/docs/ko/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Pi의 harness 설계 분석++[Pi](https://pi.dev/)(npm 패키지 `@earendil-works/pi-coding-agent`)는 스스로를 "minimal agent harness", 즉 극도로 단순한 agent harness라고 부릅니다. 이 표현은 뜯어볼 가치가 있습니다. "가장 강력한 coding agent"나 "가장 쓰기 좋은 AI 프로그래밍 도구"를 자처하지 않고, 자신의 위치를 **harness**라는 단어에 확실히 고정했기 때문입니다.++이 글에서는 강의의 다섯 가지 하위 시스템 프레임워크(명령, 도구, 환경, 상태, 피드백)로 Pi를 분석하고, 그 설계 철학이 Claude Code 및 Codex와 근본적으로 어떻게 다른지 살펴봅니다. 결론부터 말하면, **Pi의 철학은 "커널 최소화 + 확장의 프로그래밍 가능화"입니다. 컨텍스트 엔지니어링을 시스템 프롬프트 바깥에 구현하여 Pi가 사용자를 대신해 harness를 결정하는 것이 아니라, 사용자(심지어 Pi 자신까지)가 harness를 수정하게 합니다.**++## 한 문장으로 정의하기++Pi는 극도로 단순한 커널입니다. 공식 포지셔닝은 의도적으로 커널을 작게 만들고 결정권을 사용자에게 돌려줍니다. [pi.dev 홈페이지](https://pi.dev/)의 원문은 "Ask Pi to build what you want, or install a package that does it your way"입니다. Pi는 harness를 네 가지 맞춤형 계층으로 나눕니다.++- **확장(Extensions)**: Pi 생명주기 이벤트에 연결되는 TypeScript hooks로, 런타임(runtime) 수준의 프로그래밍 가능한 표면입니다.+- **스킬(Skills)**: 필요할 때 로드하는 능력 패키지로, 명령과 도구를 포함하며 점진적 공개(progressive disclosure)를 따릅니다.+- **프롬프트 템플릿(Prompt templates)**: 재사용 가능한 Markdown 프롬프트로, `/name`을 입력하면 펼쳐집니다.+- **테마(Themes)**: TUI의 외형입니다.++이 계층화 방식 자체가 하나의 harness 설계입니다. **"모델이 무엇을 볼 수 있는가, 언제 볼 수 있는가"를 커널에 하드코딩하지 않고 규칙과 확장에 완전히 맡깁니다.**++## 핵심 루프++Pi는 모든 coding agent와 마찬가지로 본질적으로 "추론 → 도구 실행 → 관찰 → 다시 추론"을 반복하는 while 루프입니다. 주목할 점은 루프 자체가 아니라 Pi가 루프 바깥을 다루는 방식입니다. 컨텍스트 관리를 루프 내부의 "compaction"에서 루프 외부의 "제어"로 확장합니다.++Pi의 런타임은 외부에 프로그래밍 가능한 인터페이스를 노출합니다. [소스 README의 Programmatic Usage](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)를 보면 대화형 TUI뿐 아니라 스크립트 방식의 print/JSON 모드, RPC 프로토콜, SDK 임베딩도 지원합니다. 따라서 같은 harness를 사람이 한 단계씩 구동할 수도 있고 CI/CD나 다른 프로그램이 자동으로 구동할 수도 있습니다. 이는 강의 13 "루프 엔지니어링"에서 설명하는 "수동 구동에서 자동 루프로" 전환하기 위한 전제에 해당합니다. harness를 사람의 상호작용으로만 구동할 수 있다면 영원히 자동 루프에 진입할 수 없습니다.++## 명령 하위 시스템: AGENTS.md와 SYSTEM.md++Pi는 "명령"을 절제된 방식으로 다루지만 계층은 명확합니다.++- **AGENTS.md**: [소스 README의 Project Context Files](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)에 로드 순서가 명시되어 있습니다. 전역 `~/.pi/agent/AGENTS.md` → 상위 디렉터리를 단계별로 탐색 → 현재 디렉터리 `./AGENTS.md` 순이며 CLAUDE.md도 호환합니다. 이는 "저장소가 사실의 원천"이라는 원칙을 실천한 것입니다. 명령은 채팅창의 당부가 아니라 파일입니다.+- **SYSTEM.md**: [pi.dev 공식 문서](https://pi.dev/docs/usage/project-context)에 따르면 프로젝트별로 기본 시스템 프롬프트를 교체(replace)하거나 덧붙일(append) 수 있습니다. 이는 Pi가 "시스템 프롬프트" 수정을 허용하는 유일한 공식 진입점이자 "환경 자기 설명" 계층입니다.++Pi는 공식적으로 시스템 프롬프트 자체가 **극도로 단순하다**고 강조합니다. 그 뒤에는 명확한 선택이 있습니다. 커널에 "만약……이라면……" 같은 긴 규칙을 채워 넣지 않고 확장 지점을 남겨, 규칙이 필요할 때만 스킬과 확장의 형태로 나타나게 합니다. 이는 강의 4 "왜 하나의 거대한 명령 파일이 실패하는가"와 직접 맞닿아 있습니다. Pi는 "극도로 단순한 커널 + 파일 분할 + 필요할 때 로드"하는 방식으로 거대한 명령 파일의 문제를 자연스럽게 피합니다.++## 상태와 컨텍스트: Pi가 가장 세밀하게 분해한 부분++Pi의 컨텍스트 엔지니어링은 특히 자세히 살펴볼 가치가 있습니다. 강의에서 설명한 "컨텍스트 연속성"과 "컨텍스트 부패 방지" 같은 개념을 구체적인 메커니즘으로 구현했기 때문입니다.++**1. Compaction을 프로그래밍 가능하게 만든다.** 컨텍스트 상한에 가까워지면 오래된 메시지를 자동으로 요약합니다. [pi.dev 공식 문서](https://pi.dev/docs/usage/sessions)에 따르면 compaction 전략 자체를 **맞춤 설정**할 수 있습니다. 확장을 이용해 주제 기반 compaction, 코드 인식형 요약을 구현하거나, 아예 다른 모델로 요약할 수도 있습니다. 소스 README에는 기본 메커니즘의 세부 사항도 나옵니다. 자동 compaction은 두 경우(컨텍스트 오버플로 복구 / 보존 임계값 초과)에 트리거되며, 분할 지점은 최근 약 2만 token을 유지하고 그 이전 메시지는 "context handoff"로 요약되어 단계별로 연쇄 compaction됩니다. 즉, Pi는 "어떻게 compaction할 것인가"를 변경할 수 없는 상수가 아니라 harness의 일부로 봅니다.++**2. 동적 컨텍스트(Dynamic context).** [pi.dev 공식 문서](https://pi.dev/docs/usage/extensions)에 따르면 확장은 매 추론 전에 메시지를 주입하고, 메시지 기록을 필터링하고, RAG를 구현하고, 장기 메모리를 구축할 수 있습니다. 이는 "컨텍스트가 가득 차면 compaction한다"는 수준보다 한발 더 나아갑니다. 컨텍스트가 창에 들어오기 전에 무엇을 넣고 뺄지 결정할 수 있게 합니다. 강의의 "agent 실행 과정을 관찰하고 디버깅할 수 있게 하기"와 "컨텍스트 연속성 유지하기"에 대응하며, Pi는 이 두 가지를 확장 표면으로 내려보냈습니다.++**3. Session 트리(Session tree).** [pi.dev 홈페이지](https://pi.dev/)에는 "sessions are stored as trees"라고 명시되어 있습니다. `/tree`로 임의의 과거 노드로 돌아가 계속 진행할 수 있고, 모든 브랜치는 같은 파일에 보관됩니다. 이는 강의에서 반복해서 강조한 "session 간 컨텍스트 단절" 문제를 해결합니다. 요약으로 억지로 이어 붙이는 대신 구조화된 기록 재생을 사용합니다. 브랜치를 HTML로 내보내거나 gist에 업로드해 공유할 수도 있어 관찰 가능성까지 함께 해결합니다.++## 도구 하위 시스템: 스킬과 확장++Pi의 "도구"는 두 계층으로 나뉩니다.++- **스킬(Skills)**: [소스 README의 Skills 섹션](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)에서는 "self-contained capability packages that the agent loads on-demand", 즉 agent가 필요할 때 로드하는 독립형 능력 패키지로 명확히 정의합니다. 명령과 도구를 포함하고 Agent Skills 표준을 따릅니다. 점진적 공개를 사용하면 스킬이 트리거될 때만 상세 내용이 컨텍스트에 들어가므로 **프롬프트 캐시(prompt cache)를 터뜨리지 않습니다**. 이는 비용 관점의 harness 설계입니다. 컨텍스트에 token이 하나 늘 때마다 추론할 때마다 비용을 지불해야 합니다. 스킬을 필요할 때 로드하도록 만드는 것은 "설명서가 아니라 지도를 제공하라"는 원칙의 또 다른 표현입니다.+- **확장(Extensions)**: 내장 생명주기 이벤트에 연결되는 TypeScript hooks입니다. [소스 README의 Hooks 섹션](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)은 공식 활용 사례로 위험한 명령 가로채기(permissions gate), 작업 전환 시 코드 상태 checkpoint, 경로 보호(`.env` 등에 쓰기 금지), 도구 출력을 수정한 뒤 모델에 전달하기, 외부(파일 감시/Webhook/CI)에서 메시지를 주입해 agent 깨우기를 제시합니다. 이 hooks API는 `@mariozechner/pi-coding-agent/hooks`에서도 내보냅니다. 커뮤니티 harness인 [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness)는 hooks 표면을 skill-router, session-summary, extract-patterns, telemetry 등의 준비된 확장으로 한 번 더 감쌉니다.++확장은 Pi의 가장 중요한 설계 결정입니다. **"사용자에게 몇 가지 스위치를 제공"하는 것이 아니라, 런타임 내부의 이벤트 표면 전체를 노출합니다.** 메모리를 추가하고 싶다면 `agent/pre-step`에 주입합니다. 동작을 기록하고 싶다면 session 이벤트를 구독합니다. 모델 요청을 바꾸고 싶다면 `agent/request`에 hooks를 겁니다. Pi가 자신의 harness를 스스로 수정하게 할 수도 있습니다. 이는 어떤 "설정 항목"보다도 "프로그래밍 가능한 harness"의 정의에 가깝습니다.++## 피드백과 검증: "학습"도 harness로 만들기++Pi 자체에는 강제 테스트 gate가 내장되어 있지 않습니다. 검증 명령은 사용자가 AGENTS.md에 작성해야 합니다. 하지만 커뮤니티 harness인 [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness)는 확장을 이용해 "피드백 루프"를 구조화했으며, 공식 README의 Hooks 섹션도 비슷한 메커니즘의 기반을 제공합니다.++- **session-summary**(pi-agent-harness 확장): 순환되는 `PROGRESS.md` 항목을 유지합니다. 이는 강의의 상태 하위 시스템, 즉 장기 작업 진행 추적에 해당합니다.+- **extract-patterns**(pi-agent-harness 확장): session에서 교훈 후보를 수집해 `LESSONS.md`에 축적합니다. "각 session이 끝나기 전에 인계를 잘한다"는 약속을 메커니즘으로 바꿉니다.+- **telemetry**(pi-agent-harness 확장): token 사용량과 비용 등을 기록합니다. 즉, 관찰 가능성입니다.++같은 커뮤니티 저장소는 이 패턴을 한 단계 더 검증합니다. `VISION.md`(목표), `PROGRESS.md`(진행 상황), `LESSONS.md`(경험), `STANDARDS.md`(표준)가 모두 Markdown 파일로 존재하며 session 간에 영속화됩니다. 강의에서 권장하는 "저장소가 사실의 원천 + 진행 상황 파일 + 인계 메커니즘"과 정확히 같은 방식이며, Pi의 확장 메커니즘으로 즉시 사용할 수 있는 계층이 되었습니다.++## 강의 프레임워크에 매핑하기++강의의 다섯 가지 하위 시스템으로 Pi를 평가하면 다음과 같습니다(주관적인 비교용 평가입니다).++| 하위 시스템 | Pi의 구현 | 평가 |+| --- | --- | --- |+| 명령 | AGENTS.md 계층형 로드 + SYSTEM.md | 계층은 명확하지만 규칙 자체는 사용자가 작성해야 함 |+| 도구 | 스킬 필요 시 로드 + 전체 생명주기 확장 hooks | 매우 강력하며 도구 시스템을 프로그래밍 가능한 표면으로 만듦 |+| 환경 | SYSTEM.md로 환경을 자기 설명하고, 런타임 환경은 사용자가 AGENTS.md에 선언 | 메커니즘은 개방되어 있지만 재현성은 사용자의 설명에 의존 |+| 상태 | session 트리 + 맞춤형 compaction + PROGRESS.md | 매우 강력하며 session 간 연속성과 복구 가능성이 핵심 |+| 피드백 | 검증 명령은 사용자가 정의하고 session-summary / extract-patterns로 메커니즘화 | 메커니즘은 제공하지만 내용은 사용자가 작성 |++Pi의 선택은 Claude Code / Codex와 뚜렷하게 대비됩니다. Claude Code는 "메모리, permissions, subagent"를 모두 커널에 내장해 즉시 사용할 수 있게 하고, Codex는 "저장소 규약, 환경 격리"를 기본값으로 만듭니다. 반면 Pi는 **어떤 것도 대신 결정하지 않습니다**. 결정권을 확장 지점으로 만듭니다. 그 대가로 직접 확장을 작성하거나 다른 사람이 작성한 패키지를 설치해야 합니다.++## 참고할 만한 설계++1. **Compaction 전략을 교체 가능하게 만드세요.** harness에서 "컨텍스트를 어떻게 compaction할 것인가"는 하드코딩된 매개변수가 아니라 교체 가능한 전략 인터페이스여야 합니다.+2. **Session 트리로 단순 요약을 대체하세요.** session 간 복구가 꼭 "지난번 요약"에 의존할 필요는 없습니다. 구조화된 기록 재생이 더 신뢰할 만한 상태 하위 시스템인 경우가 많습니다.+3. **프롬프트 캐시에 친화적으로 만드세요.** 스킬은 필요할 때 로드하고 모든 규칙을 시스템 프롬프트에 한꺼번에 넣지 마세요. 이는 컨텍스트 엔지니어링이자 비용 엔지니어링입니다.+4. **agent가 자신의 harness를 수정할 수 있게 하세요.** harness의 확장 표면이 충분히 열려 있다면 "agent 동작 최적화" 자체를 agent가 반자동으로 수행할 수 있습니다.++## 참고 자료(원문 / 소스 코드)++각 주장은 인상에 의존한 전달을 피하기 위해 아래 원문이나 소스 코드로 거슬러 올라갈 수 있습니다.++- **pi.dev 공식 사이트**: 포지셔닝 원문 "Ask Pi to build what you want, or install a package that does it your way", 네 가지 맞춤형 계층, session 트리("sessions are stored as trees", `/tree`, 단일 파일 저장, HTML 내보내기 / gist 공유).<br/>https://pi.dev/+- **pi.dev 공식 문서 · Sessions**: 교체 가능한 compaction(topic-based / code-aware / 요약 모델 교체), 자동 compaction과 동적 컨텍스트 주입 메커니즘 설명.<br/>https://pi.dev/docs/usage/sessions+- **pi.dev 공식 문서 · Extensions**: 확장이 매 추론 전에 메시지를 주입하고 기록을 필터링하며 RAG와 장기 메모리를 구현하는 방법.<br/>https://pi.dev/docs/usage/extensions+- **pi.dev 공식 문서 · Project Context**: SYSTEM.md의 replace / append 의미.<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent 소스 README**(badlogic/pi-mono): AGENTS.md 3단계 로드 순서(전역 → 상위 디렉터리 → 현재 디렉터리), `/compact`와 자동 compaction의 트리거 조건 및 2만 token 분할 지점, 필요 시 Skills 로드와 Agent Skills 표준, Hooks 생명주기와 네 가지 공식 활용 사례, Programmatic Usage(JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness 커뮤니티 저장소**: skill-router / session-summary / extract-patterns / telemetry 확장, VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md 파일 체계.<br/>https://github.com/LabidySabidy/pi-agent-harness++관련 강의: [강의 2 · Harness란 정확히 무엇인가](../lectures/lecture-02-what-a-harness-actually-is/) | [강의 5 · session 간 작업의 컨텍스트 연속성 유지하기](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [강의 13 · 수동 구동에서 자동 루프로](../lectures/lecture-13-loop-engineering/)diff --git a/docs/ko/index.md b/docs/ko/index.mdindex 0088de5..eafe068 100644--- a/docs/ko/index.md+++ b/docs/ko/index.md@@ -28,6 +28,10 @@ Learn Harness Engineering은 AI 코딩 에이전트(coding agent)의 엔지니<h3>리소스 모음(Resource Library)</h3><p>여러분의 저장소에서 바로 쓸 수 있는 복사용 템플릿(AGENTS.md, feature_list.json 등)입니다.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>최전선 Harness 분석</h3>+ <p>Pi, Claude Code, Codex, DeepSeek가 실제로 harness를 어떻게 설계하는지, 강의 프레임워크로 분석합니다.</p>+ </a></div>## 하네스의 핵심 메커니즘diff --git a/docs/pt-BR/harness-designs/claude-code/index.md b/docs/pt-BR/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..a30b385--- /dev/null+++ b/docs/pt-BR/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Análise do design de harness do Claude Code++Em [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), a Anthropic afirma claramente que a confiabilidade vem do harness, não do modelo, e que o agent precisa ser restringido "fora do modelo". Claude Code é a materialização dessa ideia em um produto, e a própria Anthropic o classifica diretamente como um **agentic harness**. Não se trata de linguagem de marketing: Claude Code talvez seja hoje o harness analisado publicamente em maior profundidade. Seu código-fonte é aberto, os relatórios da comunidade são detalhados, e quase todos os mecanismos centrais do curso — memória em camadas, compactação de contexto, permissões, hooks, subagents e persistência de sessões — foram transformados em uma implementação completa de produto.++Neste artigo, usamos o framework dos cinco subsistemas do curso para analisar Claude Code, concentrando-nos em como ele implementa conceitos fundamentais de harness como "gerenciamento de contexto", "prevenção de declarações prematuras de conclusão" e "restrições determinísticas".++## Posicionamento em uma frase++O núcleo do Claude Code é um loop while simples: chamar o modelo, executar ferramentas, observar os resultados e chamar o modelo novamente. Porém, **a maior parte do código não está nesse loop, e sim nos sistemas que o cercam** — sistema de permissões, pipeline de compactação de contexto, mecanismos de extensão, orquestração de subagents e armazenamento de sessões. Essa é a essência do harness: o loop é o esqueleto; tudo ao redor dele é o que determina a confiabilidade.++## Subsistema de instruções: memória em camadas++O sistema de memória do Claude Code é sua contribuição mais direta à teoria de harness e corresponde às aulas sobre "o repositório como fonte da verdade" e "continuidade de contexto entre sessões". A documentação oficial [How Claude remembers your project](https://code.claude.com/docs/en/memory) explica que cada sessão começa com uma janela de contexto nova e transporta conhecimento entre sessões por dois mecanismos: arquivos CLAUDE.md — instruções escritas por você — e auto memory — notas escritas pelo próprio Claude.++Quanto ao escopo, a documentação oficial divide os arquivos CLAUDE.md em quatro categorias, da mais ampla para a mais específica na ordem de carregamento:++- **Política organizacional**: gerenciada centralmente por IT/DevOps, como `/etc/claude-code/CLAUDE.md`, com normas corporativas.+- **Nível do usuário `~/.claude/CLAUDE.md`**: preferências e regras pessoais válidas em vários projetos.+- **Nível do projeto `./CLAUDE.md` ou `./.claude/CLAUDE.md`**: fonte da verdade do projeto, com estrutura de engenharia, stack tecnológica e comandos de validação, compartilhada no repositório.+- **Nível local `./CLAUDE.local.md`**: preferências pessoais dentro do projeto, normalmente adicionadas ao `.gitignore` e não versionadas.++Há ainda dois mecanismos:++- **Carregamento sob demanda por subdiretório**: CLAUDE.md em subdiretórios não é carregado na inicialização, mas entra no contexto quando Claude lê arquivos daquele diretório.+- **Memória automática (auto memory)**: Claude registra ativamente notas a partir de suas correções e preferências; elas são compartilhadas por repositório, funcionam entre worktree e carregam no máximo as primeiras 200 linhas ou 25KB por sessão.++Esses quatro escopos formam uma **hierarquia de instruções**: segundo a documentação oficial, "quanto mais específica a instrução, mais tarde ela entra no contexto" — instruções do projeto aparecem depois das instruções do usuário. O valor disso está em não obrigar o modelo a absorver um arquivo gigantesco de instruções no início de cada conversa, mas carregar as informações mais próximas conforme o escopo. Essa é a resposta, transformada em produto, à quarta aula: "por que um único arquivo gigante de instruções falha".++## Subsistema de contexto: pipeline de compactação em cinco níveis++O gerenciamento de contexto do Claude Code usa um **pipeline de compactação em cinco níveis** (five-layer compaction pipeline), e não um simples "resumir quando ficar cheio". Esse detalhe arquitetural vem da análise de código-fonte [Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf), do VILA Lab. A quinta aula explica como tarefas longas perdem continuidade; a solução do Claude Code é um funil de vários níveis: primeiro realiza poda sem perdas, removendo resultados redundantes de ferramentas; depois faz uma extração estruturada; e só no fim usa resumos com perdas produzidos por LLM, com mecanismos de interrupção para evitar compactação excessiva.++O design é complementado pelo armazenamento de sessões: **armazenamento orientado a anexação (append-oriented storage)**, no qual todo o histórico é acrescentado a `history.jsonl`, com suporte a restauração via `/resume` e ramificações fork. Isso garante a "passagem de contexto antes do fim de cada sessão" — não por uma memória excepcional, mas porque a camada de armazenamento é incremental e reproduzível.++## Subsistema de ferramentas: quatro mecanismos de extensão++Claude Code divide sua superfície de extensão em quatro categorias, cada uma destinada a um tipo de problema. Essa é uma das partes mais valiosas de seu design:++- **Skills**: conforme a [documentação oficial](https://code.claude.com/docs/en/skills), conhecimento procedimental descrito em `SKILL.md`, carregado automaticamente por palavras de ativação e com divulgação progressiva. Adequado ao conhecimento especializado sobre "como fazer algo".+- **MCP**: o protocolo JSON-RPC da [documentação oficial](https://code.claude.com/docs/en/mcp) conecta sistemas externos e serve como interface padrão para que "as mãos do modelo alcancem o mundo externo".+- **Hooks**: scripts determinísticos da [documentação oficial](https://code.claude.com/docs/en/hooks), associados a eventos do ciclo de vida como `PreToolUse`, `PostToolUse` e `Stop`.+- **Plugins / subagents (Subagents)**: a [documentação oficial](https://code.claude.com/docs/en/sub-agents) descreve como delegar tarefas complexas a agents especializados.++A decisão central é a **separação de responsabilidades**: CLAUDE.md trata de "o que é", Skills de "como fazer", MCP de "aonde conectar" e hooks de "quando impor". Se uma equipe misturar essas camadas — por exemplo, escrever em CLAUDE.md algo que deveria ser feito por MCP — surgirá o vazamento de contexto discutido no curso.++## Feedback e validação: restrições determinísticas + divisão entre humano e máquina++A décima aula ensina que "a validação só é real quando o fluxo completo funciona". Claude Code implementa isso em duas frentes:++**1. Sistema de permissões (restrições determinísticas).** As permissões do Claude Code não "perguntam sobre tudo": são sete modos mais um classificador baseado em ML. Operações de baixo risco são liberadas; as de alto risco são consultadas ou negadas conforme a política — veja os detalhes arquiteturais na [análise do VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). Assim, "definir claramente os limites do agent", da sétima aula, torna-se uma imposição do runtime, não um pedido no prompt.++**2. Hooks (prevenção de conclusão prematura).** Um hook `PostToolUse` pode executar verificações obrigatórias depois do uso de uma ferramenta e inserir o resultado de volta no contexto; um hook `Stop` intervém quando o agent declara que terminou. Isso separa "quem faz" de "quem verifica". A [Anthropic observou explicitamente no artigo sobre harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) que agents elogiam o próprio trabalho com confiança ("confidently praised their work"). Por isso, hooks injetam verificações **determinísticas**, em vez de confiar na autoavaliação do modelo.++**3. Subagents (isolamento de contexto).** O histórico de conversa de cada subagent fica em um arquivo sidechain separado e **não aumenta o contexto do agent pai** — veja a [análise do VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). Isso combina "limites de tarefa" e "isolamento de contexto": ao dividir a tarefa, também se isola a contaminação do contexto.++## Observabilidade e persistência de sessões++Os logs do Claude Code formam um registro completo orientado a anexação (history.jsonl). Comandos explícitos como `/compact`, `/clear` e `/init` permitem gerenciar ativamente o estado do contexto, sem esperar passivamente que ele fique cheio. `/init` transforma "inicializar o agent antes de cada trabalho", da sexta aula, em um comando: segundo a [documentação oficial](https://code.claude.com/docs/en/memory), ele analisa automaticamente a base de código e gera um CLAUDE.md inicial com comandos de build, instruções de teste e convenções de engenharia.++## Mapeamento para o framework do curso++| Subsistema | Implementação no Claude Code | Avaliação |+| --- | --- | --- |+| Instruções | Escopos em camadas (organização/usuário/projeto/local) + memória automática | Memória em camadas como implementação de referência |+| Ferramentas | Quatro tipos de extensão: Skills + MCP + hooks + subagents | Responsabilidades bem definidas; um destaque central |+| Ambiente | Configurações do projeto + settings.json | Depende da autodescrição do usuário em CLAUDE.md |+| Estado | Armazenamento de sessões orientado a anexação + compactação em cinco níveis + resume/fork | Muito robusto; referência para continuidade em tarefas longas |+| Feedback | Classificador de permissões + verificações obrigatórias em hooks PostToolUse | Transforma a prevenção de conclusão prematura em mecanismo determinístico |++## Designs que vale a pena adotar++1. **Organize instruções em camadas de escopo**, em vez de empilhá-las em um único arquivo. CLAUDE.md no nível do diretório é uma implementação elegante de "carregamento próximo ao uso".+2. **Use um funil de compactação em níveis**: primeiro sem perdas, depois com perdas; não comece resumindo tudo.+3. **Use hooks para verificações determinísticas**: evite conclusões prematuras por imposição do runtime, não por pedidos no prompt.+4. **Isole o contexto dos subagents**: ao dividir tarefas, divida também o contexto para que as subtarefas não contaminem o loop principal.+5. **Use armazenamento de sessões orientado a anexação e reproduzível**: a passagem de contexto é garantida pela camada de armazenamento, não pela memória.++## Fontes de referência (originais / código-fonte)++Cada afirmação pode ser rastreada até os textos originais ou o código-fonte abaixo, evitando paráfrases baseadas apenas em lembranças:++- **Documentação oficial do Claude Code · Memory**: contexto novo em cada sessão, quatro escopos de CLAUDE.md, carregamento sob demanda por subdiretório, auto memory (200 linhas / 25KB) e geração de CLAUDE.md com `/init`.<br/>https://code.claude.com/docs/en/memory+- **Documentação oficial do Claude Code · Skills / MCP / Hooks / Sub-agents**: definições dos quatro mecanismos de extensão e eventos PreToolUse / PostToolUse / Stop.<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab, Dive into Claude Code** (análise de código-fonte): pipeline de compactação em cinco níveis, sete modos de permissão + classificador de ML, subagents sidechain e armazenamento orientado a anexação em history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic, Effective harnesses for long-running agents**: origem das ideias de que "a confiabilidade vem do harness, não do modelo", de que o agent elogia o próprio trabalho com confiança e de usar hooks para validação.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Guia Claude Code Full Stack** (comunidade; camadas CLAUDE.md / Skills / MCP / Subagents / Hooks): leitura complementar sobre a separação de responsabilidades entre os mecanismos de extensão.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Material relacionado: [Aula 3 · Transformar o repositório na única fonte da verdade](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Aula 9 · Impedir que o agent declare vitória cedo demais](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Aula 10 · A validação só é real quando o fluxo completo funciona](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/pt-BR/harness-designs/codex/index.md b/docs/pt-BR/harness-designs/codex/index.mdnew file mode 100644index 0000000..ff66102--- /dev/null+++ b/docs/pt-BR/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Análise do design de harness do Codex++O [Codex](https://openai.com/index/harness-engineering/), da OpenAI, talvez seja, entre os quatro produtos, o mais profundamente ligado aos princípios fundamentais de harness. Afinal, o artigo Harness Engineering, que deu nome a todo esse campo, nasceu das experiências da equipe da OpenAI ao desenvolver produtos com Codex. Portanto, analisar o design de harness do Codex é, em grande medida, analisar as práticas de engenharia por trás desse artigo.++A filosofia do Codex pode ser resumida em uma frase: **o repositório é a fonte da verdade (repository as the system of record), AGENTS.md é apenas uma página de índice, e o valor da engenharia está em projetar o ambiente, expressar a intenção e construir loops de feedback.**++## Posicionamento em uma frase++A equipe da OpenAI usou Codex para entregar, em poucas semanas, um produto que chegou a ter mais de um milhão de linhas de código, **todas escritas pelo Codex** (veja a seção "Designing for growth" de [Harness Engineering](https://openai.com/index/harness-engineering/)). Essa prática respondeu a uma pergunta: quando o papel do engenheiro deixa de ser "escrever código" e passa a ser "projetar o harness", como o sistema deve ser organizado? O Codex CLI em si é um binário monolítico de código aberto, implementado em Rust ([github.com/openai/codex](https://github.com/openai/codex)), mas sua principal contribuição para harness está nas **convenções (convention)** e na **engenharia de contexto**, e não em pontos de extensão sofisticados.++## Subsistema de instruções: AGENTS.md é uma página de índice, não uma enciclopédia++Esta é a decisão de design do Codex que mais influenciou a teoria de harness:++> Um único arquivo gigante de instruções dificulta verificações automatizadas — cobertura, atualização, propriedade e referências cruzadas — e inevitavelmente acaba divergindo da realidade. Por isso, deixamos de tratar AGENTS.md como uma enciclopédia e passamos a tratá-lo como uma **página de índice**. O conhecimento da base de código fica em documentação estruturada, e AGENTS.md aponta para ela.++(O texto acima é uma paráfrase direta da seção "AGENTS.md should be a directory page" de [Harness Engineering](https://openai.com/index/harness-engineering/).)++A quarta aula explica por que "um único arquivo gigante de instruções falha", e o Codex oferece uma resposta direta: mantenha AGENTS.md em torno de 100 linhas — o texto original recomenda aproximadamente 100 e sugere mover o conteúdo para `docs/` quando esse limite se aproxima — e divida os detalhes no diretório `docs/` para que o agent os leia sob demanda. Essa é a principal referência para a ideia de "fornecer um mapa, não um manual".++O princípio complementar é **impor invariantes, sem microgerenciar a implementação** (no original: "don't micromanage the implementation; focus on invariants"): AGENTS.md contém apenas restrições rígidas que não podem ser violadas e comandos de validação; a implementação fica a cargo do modelo. Isso corresponde diretamente a "restrições, não microgerenciamento", da segunda aula.++## Subsistema de contexto: Write-Select-Compress-Isolate++A engenharia de contexto do Codex pode ser resumida em quatro estratégias. Esse framework foi elaborado pela comunidade depois que "context engineering" se consolidou como disciplina própria e então mapeado de volta para o Codex (veja [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):++- **Write (escrever para fora)**: persistir o contexto fora da janela — registrar conclusões na documentação e o estado em arquivos, em vez de deixá-los na conversa. Corresponde ao princípio de que "o repositório é a fonte da verdade".+- **Select (selecionar para dentro)**: trazer para a janela apenas os tokens necessários — AGENTS.md indica o caminho e os arquivos são lidos sob demanda, em vez de inserir todo o repositório no contexto.+- **Compress (compactar)**: preservar o que realmente importa — Codex oferece compactação automática e `/compact` manual, com possibilidade de personalizar `compact_prompt` (veja [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (isolar)**: separar o contexto em limites distintos — usar subagents para isolar o contexto de tarefas diferentes; um subagent de frontend nunca vê o schema do banco de dados do backend.++Codex também possui um detalhe refinado no contexto do ambiente: a análise de código-fonte do [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) feita pela comunidade mostra que `build_environment_update_item` emite apenas os **campos alterados** — CWD, branch do git e sistema de arquivos — quando o ambiente muda, em vez de repetir todo o contexto do sistema a cada rodada. É um detalhe de engenharia para "não manter tokens repetidos no contexto".++## Ferramentas e limites: isolamento com worktree + subagents++Codex possui dois mecanismos centrais de harness:++**1. Isolamento do ambiente com git worktree.** A seção "Environment" de [Harness Engineering](https://openai.com/index/harness-engineering/) explica que cada tarefa é executada em uma git worktree independente, junto com uma stack local de observabilidade — logs, métricas e traces — para validar cada mudança em um ambiente isolado. É a implementação física de "definir claramente os limites de cada tarefa do agent", da sétima aula: o limite não depende de um pedido em uma instrução, mas é imposto pelo isolamento do ambiente. Aqui, o subsistema de ambiente torna-se um isolamento rígido.++**2. Subagents no nível do núcleo.** `spawn_agent` / `wait_agent`, do Codex, são ferramentas do núcleo: o modelo cria explicitamente subagents, fornece a cada um um histórico de sessão e um conjunto de ferramentas independentes e aguarda os resultados. Os subagents herdam as instruções AGENTS.md do agente pai, mas são executados em **seu próprio contexto**. A configuração fica em `.codex/agents/*.toml`, onde é possível especificar modelos e instruções diferentes (veja a seção Sub-agents de [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)). Essa é uma implementação direta do "isolamento de contexto" e também representa o espírito da "passagem de contexto" da décima segunda aula: cada subagent é uma unidade de trabalho com limites claros.++## Subsistema de feedback: comandos de validação incorporados às normas++Um dos pontos mais enfatizados pela OpenAI é registrar explicitamente os comandos de validação em AGENTS.md, fazendo de "como confirmar que está correto" uma parte do repositório. No fluxo de engenharia do Codex, testes, CI, documentação e configuração de observabilidade são todos gerados pelo Codex e constituem "caminhos executáveis de validação". A solução para um modelo capaz, mas não confiável, não é esperar que ele aja corretamente por conta própria, e sim tornar **o caminho de validação um componente padrão do harness**.++As políticas de aprovação (approval policies) e o modo de planejamento (plan mode) oferecem feedback em outra direção: antes de operações de alto risco, exige-se um plano e uma aprovação, transformando os "limites da tarefa" e o "poder de decisão humano" em controles de runtime.++## Mapeamento para o framework do curso++| Subsistema | Implementação no Codex | Avaliação |+| --- | --- | --- |+| Instruções | AGENTS.md como página de índice + divisão em docs/ + imposição de invariantes | Exemplar; definiu a ideia de "fornecer um mapa, não um manual" |+| Ferramentas | Isolamento com worktree + subagents via spawn_agent | Limites impostos pelo ambiente; muito robusto |+| Ambiente | worktree independente + stack de observabilidade | O isolamento com worktree é sua marca registrada |+| Estado | Estratégia Write (estado registrado em arquivos/documentos) | Depende de convenções, não de memória integrada |+| Feedback | Comandos de validação nas normas + políticas de aprovação + plan mode | Caminhos de feedback padronizados; vale a pena adotar |++A comparação entre Codex e Claude Code é interessante: Claude Code segue a "adição", incorporando memória, permissões e subagents ao núcleo; Codex segue a "subtração", mantendo o núcleo contido e transferindo mais responsabilidade para as convenções do repositório e a engenharia de contexto. É por isso que a comunidade costuma dizer que "a filosofia de harness do Codex vale mais do que seu código".++## Designs que vale a pena adotar++1. **Escreva AGENTS.md como uma página de índice**: mantenha-o em torno de 100 linhas, aponte para os detalhes em docs/ e permita verificações automatizadas.+2. **Registre apenas invariantes, sem microgerenciar a implementação**: restrições rígidas + comandos de validação; deixe o restante para o modelo.+3. **Use worktree para isolar ambientes**: imponha os limites da tarefa pelo ambiente, não por pedidos em instruções.+4. **Transmita apenas incrementos do contexto do ambiente**: em cada rodada, emita somente os campos alterados, sem repetir todo o contexto do sistema.+5. **Use subagents para isolar o contexto**: ao dividir tarefas, divida também o contexto para não contaminar o loop principal.++## Fontes de referência (originais / código-fonte)++Cada afirmação pode ser rastreada até os textos originais ou o código-fonte abaixo, evitando paráfrases baseadas apenas em lembranças:++- **OpenAI, Harness Engineering**: AGENTS.md como página de índice e recomendação de cerca de 100 linhas; execute invariants / don't micromanage; isolamento com worktree + stack de observabilidade; comandos de validação nas normas; caso do produto com mais de um milhão de linhas; políticas de aprovação e plan mode. Principal fonte de todas as afirmações centrais deste artigo.<br/>https://openai.com/index/harness-engineering/+- **Especificação oficial AGENTS.md da OpenAI** (AGENTS.md como convenção padrão entre ferramentas):<br/>https://openai.com/index/agents-md/+- **Repositório de código aberto do Codex CLI** (binário monolítico implementado em Rust):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (comunidade): framework Write-Select-Compress-Isolate, `/compact` e `compact_prompt`, subagents `spawn_agent` / `wait_agent` e configuração `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (análise de código-fonte pela comunidade): detalhes de implementação, como o contexto incremental do ambiente em `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Material relacionado: [Aula 3 · Transformar o repositório na única fonte da verdade](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Aula 4 · Dividir instruções em arquivos diferentes](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Aula 7 · Definir claramente os limites de cada tarefa do agent](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/pt-BR/harness-designs/deepseek/index.md b/docs/pt-BR/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..3c3fa17--- /dev/null+++ b/docs/pt-BR/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# Análise do design do DeepSeek Harness++O [DeepSeek Harness](https://deepseek.com/harness) — comando `dsh`, repositório `deepseek-ai/deepseek-harness` — foi lançado em agosto de 2026 como Developer Preview. Sua definição oficial é direta: **Agent = Model + Environment + Tools + State** — modelo, ambiente, ferramentas e estado.++Se a análise dos três produtos anteriores pergunta "como um harness deve ser projetado", o DeepSeek Harness faz uma pergunta mais radical: **o harness pode se separar de um modelo específico e tornar-se um runtime independente?** A resposta é sim, e a ideia é levada ao extremo. Nas palavras da [documentação de arquitetura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* (cada parte do produto é um plugin, incluindo o adaptador do modelo, o registro de ferramentas, o log da sessão e até o próprio loop do agent).++Neste artigo, analisamos três aspectos: o núcleo baseado em plugins, as interfaces de capacidade (capability seam), o pipeline de eventos e a mais forte de suas restrições de engenharia: "Model-visible means logged".++## Posicionamento em uma frase++A estrutura tradicional de um coding agent é "LLM + loop de agent fixo + conjunto fixo de ferramentas". A estrutura do DeepSeek Harness é "modelo + núcleo de plugins (Cordis)". O núcleo cuida apenas de carregar e descarregar plugins, gerenciar dependências e fornecer o mecanismo de eventos; **ele não possui nenhuma capacidade específica de agent**. Nas palavras da [documentação de arquitetura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): "There is no privileged core to patch" (não existe um núcleo privilegiado que precise ser alterado) e "you extend dsh by mounting a plugin beside the others" (para estender dsh, basta montar um plugin ao lado dos demais, sem alterar o núcleo). Isso significa que nem o loop do agent é sagrado ou imutável: você pode combinar o modelo do DeepSeek, os subagents do Claude Code, um sandbox remoto, memória personalizada, um loop próprio e uma UI própria para formar um agent inteiramente novo.++É a aplicação mais completa da frase do curso "tudo além dos pesos do modelo é harness": se o harness é independente, que ele se torne um sistema operacional independente.++## Núcleo da arquitetura 1: interfaces de capacidade (Capability Seam)++O DeepSeek Harness representa "capacidades" por meio de Service e divide quase todas elas em três camadas:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Tomando o sistema de arquivos como exemplo: sob `FS Service`, existem vários Provider — Local FS, E2B FS e Remote FS — expostos de maneira uniforme como file tools. Shell, Subprocess, Sandbox, Web, LLM e SubAgent seguem a mesma estrutura. Essa arquitetura de três camadas não é uma interpretação nossa. A seção [Capability seams da documentação de arquitetura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) diz: *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* (uma interface de capacidade é uma capacidade substituível com três papéis: um Service Definition que declara a interface, um Service Provider que a implementa e um Consumer que a utiliza, normalmente uma ferramenta exposta ao modelo).++Isso resolve uma questão antiga da engenharia de harness: **um agent deve depender de uma "ferramenta específica" ou de uma "interface de capacidade"?** O DeepSeek Harness escolhe a segunda opção. Para o curso, isso significa que o "subsistema de ferramentas" é padronizado como uma interface: trocar o Provider não altera a aparência da ferramenta para o modelo, mas muda completamente o ambiente.++## Núcleo da arquitetura 2: pipeline de eventos (Event Pipeline)++Internamente, o DeepSeek Harness não é um simples "LLM → ferramenta → LLM", mas um pipeline de eventos no qual cada etapa é um ponto que pode ser observado por plugins:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(O pipeline acima é uma transcrição da seção [Turn flow da documentação de arquitetura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): `turn/*`, `step/*`, `user/message`, `assistant/*` e `tool/*` são eventos persistentes de sessão; `agent/pre-step`, `agent/request`, `llm/stream` e `tools/*` são pontos de extensão observáveis por plugins.)++A maior vantagem desse design é que **muitas funcionalidades não exigem nenhuma alteração no loop do agent**. Quer fazer uma verificação de segurança antes de executar uma ferramenta? Observe `tools/pre-execute`. Quer adicionar memória? Injete-a em `agent/pre-step`. Quer registrar comportamentos? Assine eventos da sessão. Quer alterar a requisição ao modelo? Use um hook em `agent/request`. Quer decidir se o raciocínio deve continuar? Observe `agent/turn-stopping`.++Comparado à décima primeira aula, "tornar observável o processo de execução do agent", o DeepSeek Harness vai além: em vez de apenas "adicionar logs", ele transforma **cada etapa do loop em um ponto de evento**, permitindo que observabilidade, permissões, memória e políticas sejam conectadas ao loop como observadores, em vez de ficarem embutidas nele.++## Núcleo da arquitetura 3: Session Event Log e "Model-visible means logged"++O DeepSeek Harness possui um **Session Event Log append-only (log de eventos de sessão somente para anexação)** e estabelece uma forte restrição de engenharia. Nas palavras da seção [Session log da documentação de arquitetura](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md):++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Tudo o que o modelo vê deve ser registrado. Qualquer coisa que chegue a uma requisição ao modelo precisa poder ser reconstruída a partir do log, e um invariante de runtime impõe essa regra.)++Em outras palavras, observabilidade não é um log acrescentado depois, mas uma restrição fundamental do harness: tudo que entra no contexto do modelo deve, por padrão, deixar um registro. Isso corresponde diretamente à ideia da aula final de que "a observabilidade pertence ao interior do harness" e transforma o design de armazenamento "append-only" em princípio: logs são apenas acrescentados, nunca sobrescritos, e o estado da sessão pode ser reproduzido.++## Mapeamento para o framework do curso++| Subsistema | Implementação no DeepSeek Harness | Avaliação |+| --- | --- | --- |+| Instruções | Baseada em plugins; regras/Skills são injetadas como plugins | Extremamente livre, mas sem uma convenção integrada como CLAUDE.md |+| Ferramentas | Interface de capacidade Service Definition → Provider → Consumer | Padronização máxima do subsistema de ferramentas |+| Ambiente | Sandbox/FS/Shell com Provider substituíveis, incluindo E2B remoto | Ambiente totalmente substituível |+| Estado | Session Event Log append-only + Model-visible means logged | Observabilidade como restrição fundamental |+| Feedback | permission / guard / policy / hook em tools/pre-execute | Mecanismo de feedback orientado a eventos |++A diferença fundamental entre o DeepSeek Harness e os outros três produtos é que Pi, Claude Code e Codex otimizam o harness dentro de "um agent específico", enquanto o DeepSeek Harness define o harness como **um sistema operacional independente do modelo**, no qual o próprio agent é apenas um aplicativo substituível. O custo também é evidente: mais liberdade implica maior custo de configuração. Esse é o outro lado inerente do design de "harness como OS" — e, na fase de Developer Preview, o posicionamento ainda é de experimentação inicial, com mecanismos em evolução.++## Designs que vale a pena adotar++1. **Transforme cada etapa do loop em um ponto de evento**: conecte permissões, memória, políticas e logs como observadores do loop, em vez de embuti-los nele.+2. **Padronize interfaces de capacidade**: dependa de "interfaces de capacidade", não de "ferramentas específicas", para substituir todo o ambiente sem alterar a superfície de ferramentas vista pelo modelo.+3. **Model-visible means logged**: tudo que o modelo vê deve ser registrado; transforme observabilidade de "diferencial" em "restrição fundamental".+4. **Log de sessão append-only**: estado reproduzível e passagem de contexto confiável como garantia de engenharia de que "cada sessão deixa um estado limpo".++## Fontes de referência (originais / código-fonte)++Cada afirmação pode ser rastreada até os textos originais ou o código-fonte abaixo, evitando paráfrases baseadas apenas em lembranças:++- **Site oficial do DeepSeek Harness**: definição "Agent = Model + Environment + Tools + State", posicionamento como Developer Preview e comando `dsh`.<br/>https://deepseek.com/harness+- **Repositório deepseek-ai/deepseek-harness** (comando `dsh`, licença MIT):<br/>https://github.com/deepseek-ai/deepseek-harness+- **Documentação de arquitetura architecture.md**: principal fonte deste artigo — "Every part of the product is a plugin", "There is no privileged core to patch", pipeline de eventos Turn flow, os três papéis de Capability seams, "Model-visible means logged" e seu invariante de runtime, Session Event Log append-only, interfaces de capacidade fs/tools/telemetry e subsistemas `ctx.*`.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **Documentos complementares de arquitetura**: introdução ao núcleo Cordis (plugins contribute services, typed events, reversible effects), detalhes das interfaces de capacidade e subsistema Session.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Material relacionado: [Aula 11 · Tornar observável o processo de execução do agent](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Aula 12 · Preparar a passagem de contexto antes do fim de cada sessão](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Aula 2 · O que exatamente é um Harness](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/pt-BR/harness-designs/index.md b/docs/pt-BR/harness-designs/index.mdnew file mode 100644index 0000000..1b5e231--- /dev/null+++ b/docs/pt-BR/harness-designs/index.md@@ -0,0 +1,29 @@+# Análise dos harnesses de ponta++Esta seção compara as teorias sobre harness apresentadas no material do curso com produtos reais de última geração. Em cada produto, nosso foco é uma única questão: **como seu harness foi projetado** — isto é, a camada de infraestrutura de engenharia ao redor do modelo: os cinco subsistemas de instruções, ferramentas, ambiente, estado e feedback, além de mecanismos centrais como continuidade de contexto, inicialização, validação, observabilidade, passagem de contexto e loops.++De propósito, não discutimos se a capacidade de raciocínio do modelo é forte, se ele obteve uma pontuação alta em determinado benchmark nem apresentamos genericamente "o que este agent consegue fazer". Essas são questões das camadas do modelo e do produto. Aqui, analisamos apenas o harness — tudo o que existe além dos pesos do modelo.++## Por que vale a pena analisar++A primeira aula já mostrou que um modelo capaz não é sinônimo de execução confiável. O mesmo modelo, em harnesses diferentes, pode apresentar uma diferença de desempenho de uma ordem de grandeza. Mas o material explica "como deveria ser feito", enquanto estes produtos mostram "como as equipes líderes realmente fazem".++Cada produto reúne um conjunto independente de decisões de design. Ao compará-los, você verá os mesmos mecanismos centrais implementados de maneiras completamente diferentes por cada equipe:++- **Pi** transforma o harness em um núcleo mínimo com extensões programáveis e faz engenharia de contexto por meio de um "prompt de sistema mínimo + carregamento sob demanda".+- **Claude Code** transforma o harness em um ambiente de execução completo: memória em camadas, compactação em cinco níveis, permissões, hooks e subagents.+- **Codex** leva a filosofia do harness ao extremo: o repositório é a fonte da verdade, AGENTS.md é apenas uma página de índice e o ambiente é isolado com worktree.+- **DeepSeek Harness** chega a definir o próprio harness como um runtime independente do modelo: Everything is a Plugin.++## Lista de artigos++- [Análise do design de harness do Pi](./pi/): núcleo mínimo + extensões programáveis, levando a engenharia de contexto para além do prompt de sistema.+- [Análise do design de harness do Claude Code](./claude-code/): memória em camadas, compactação em cinco níveis, permissões e hooks em um ambiente completo de execução de agent.+- [Análise do design de harness do Codex](./codex/): o repositório como fonte da verdade, AGENTS.md como página de índice, isolamento de ambiente e loops de feedback.+- [Análise do design do DeepSeek Harness](./deepseek/): Everything is a Plugin, tornando substituível até o próprio loop do agent.++## Como ler++Recomendamos começar pelas primeiras aulas do material — especialmente a [Aula 2: o que exatamente é um Harness](../lectures/lecture-02-what-a-harness-actually-is/) — para compreender o framework dos cinco subsistemas. Depois, volte aqui para ver como produtos reais implementam esses mecanismos.++Ao final de cada artigo, as seções "Mapeamento para o framework do curso" e "Designs que vale a pena adotar" ajudam a traduzir rapidamente o design do produto para os conceitos do curso, facilitando sua aplicação direta nos próprios projetos.diff --git a/docs/pt-BR/harness-designs/pi/index.md b/docs/pt-BR/harness-designs/pi/index.mdnew file mode 100644index 0000000..98ff06d--- /dev/null+++ b/docs/pt-BR/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Análise do design de harness do Pi++O [Pi](https://pi.dev/) — pacote npm `@earendil-works/pi-coding-agent` — se apresenta como um "minimal agent harness", ou seja, um agent harness minimalista. Vale examinar essa frase: ele não afirma ser "o coding agent mais poderoso" nem "a melhor ferramenta de programação com IA"; sua identidade está firmemente centrada na palavra **harness**.++Neste artigo, usamos o framework dos cinco subsistemas do curso — instruções, ferramentas, ambiente, estado e feedback — para analisar Pi e entender as diferenças fundamentais entre sua filosofia e as de Claude Code e Codex. A resposta, de antemão, é: **a filosofia do Pi é "minimizar o núcleo + tornar as extensões programáveis". Ele leva a engenharia de contexto para além do prompt de sistema e permite que o usuário — ou até o próprio Pi — modifique o harness, em vez de decidir o harness por você.**++## Posicionamento em uma frase++Pi é um núcleo minimalista: seu posicionamento oficial mantém o núcleo deliberadamente pequeno e devolve a você o poder de decisão. Nas palavras da [página inicial do pi.dev](https://pi.dev/): "Ask Pi to build what you want, or install a package that does it your way". Ele divide o harness em quatro camadas personalizáveis:++- **Extensões (Extensions)**: hooks TypeScript ligados aos eventos do ciclo de vida do Pi; a superfície programável no nível do runtime.+- **Skills**: pacotes de capacidade carregados sob demanda, contendo instruções e ferramentas, com divulgação progressiva (progressive disclosure).+- **Templates de prompt (Prompt templates)**: prompts reutilizáveis em Markdown, expandidos ao digitar `/name`.+- **Temas (Themes)**: aparência da TUI.++Essa organização em camadas já é, por si só, um design de harness: **o que o modelo pode ver e quando pode ver é inteiramente controlado por regras e extensões, em vez de ficar fixo no núcleo.**++## Loop central++Como todo coding agent, Pi é essencialmente um loop while de "raciocínio → execução de ferramenta → observação → novo raciocínio". O que merece atenção não é o loop em si, mas o tratamento que Pi dá à sua camada externa: ele amplia o gerenciamento de contexto da "compactação" dentro do loop para o "controle" fora dele.++O runtime do Pi expõe interfaces programáveis. Na seção Programmatic Usage do [README do código-fonte](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md), além da TUI interativa, há modos de impressão/JSON para scripts, protocolo RPC e incorporação via SDK. Assim, o mesmo harness pode ser conduzido passo a passo por uma pessoa ou automaticamente por CI/CD ou outro programa. Isso corresponde ao pré-requisito da décima terceira aula, "engenharia de loops", para passar da condução manual ao loop automatizado: um harness que só pode ser conduzido por interação humana jamais entrará em um loop automático.++## Subsistema de instruções: AGENTS.md e SYSTEM.md++Pi trata "instruções" com moderação, mas sua hierarquia é clara:++- **AGENTS.md**: a seção Project Context Files do [README do código-fonte](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) especifica a ordem de carregamento: `~/.pi/agent/AGENTS.md` global → percurso ascendente pelos diretórios pais → `./AGENTS.md` do diretório atual, com compatibilidade também com CLAUDE.md. É a aplicação de "o repositório como fonte da verdade": instruções são arquivos, não lembretes na caixa de conversa.+- **SYSTEM.md**: segundo a [documentação oficial do pi.dev](https://pi.dev/docs/usage/project-context), o prompt de sistema padrão pode ser substituído (replace) ou complementado (append) por projeto. Essa é a única entrada oficial para alterar o "prompt de sistema" e também a camada de "autodescrição do ambiente" do Pi.++Pi enfatiza oficialmente que seu prompt de sistema é **minimalista**. Por trás disso há uma escolha explícita: o núcleo não é preenchido com longas regras de "se... então..."; em vez disso, oferece pontos de extensão para que regras apareçam como Skills e extensões somente quando necessárias. Isso corresponde diretamente à quarta aula, "por que um único arquivo gigante de instruções falha". Com "núcleo minimalista + arquivos separados + carregamento sob demanda", Pi evita naturalmente o problema das instruções gigantescas.++## Estado e contexto: onde Pi vai mais longe nos detalhes++A engenharia de contexto do Pi merece atenção especial, pois transforma conceitos do curso como "continuidade de contexto" e "prevenção da degradação do contexto" em mecanismos concretos:++**1. Compactação (Compaction) programável.** Ao se aproximar do limite de contexto, mensagens antigas são automaticamente resumidas. A [documentação oficial do pi.dev](https://pi.dev/docs/usage/sessions) explica que a própria estratégia de compactação é **personalizável**: uma extensão pode implementar compactação por tópico, resumos cientes do código ou até usar outro modelo para resumir. O README do código-fonte também apresenta detalhes do mecanismo padrão: a compactação automática é acionada em duas situações — recuperação após estouro do contexto ou superação do limite de retenção —, preserva aproximadamente os 20 mil tokens mais recentes no ponto de corte e resume as mensagens anteriores como um "context handoff", compactado sucessivamente em cadeia. Portanto, Pi não trata "como compactar" como uma constante imutável, mas como parte do harness.++**2. Contexto dinâmico (Dynamic context).** A [documentação oficial do pi.dev](https://pi.dev/docs/usage/extensions) diz que extensões podem injetar mensagens antes de cada rodada de raciocínio, filtrar o histórico, implementar RAG e construir memória de longo prazo. Isso vai além de "compactar quando o contexto ficar cheio": permite decidir o que entra e o que fica de fora antes mesmo de chegar à janela. Para os conceitos do curso de "tornar observável e depurável a execução do agent" e "manter a continuidade do contexto", Pi transfere ambos para a superfície de extensões.++**3. Árvore de sessões (Session tree).** A [página inicial do pi.dev](https://pi.dev/) afirma que "sessions are stored as trees": com `/tree`, é possível voltar a qualquer ponto do histórico e continuar dali, enquanto todas as ramificações permanecem no mesmo arquivo. Isso resolve a "ruptura de contexto entre sessões", enfatizada repetidamente no curso, não com um resumo forçado, mas por meio da reprodução estruturada do histórico. As ramificações podem ser exportadas como HTML ou enviadas como gist para compartilhamento, resolvendo também a observabilidade.++## Subsistema de ferramentas: Skills e extensões++As "ferramentas" do Pi possuem duas camadas:++- **Skills**: a seção Skills do [README do código-fonte](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) fornece uma definição clara: "self-contained capability packages that the agent loads on-demand", ou seja, pacotes de capacidade autocontidos, carregados sob demanda, com instruções e ferramentas e compatíveis com o padrão Agent Skills. A divulgação progressiva faz os detalhes de uma Skill entrarem no contexto somente quando ela é ativada, **sem saturar o cache de prompts (prompt cache)**. É um design de harness orientado a custos: cada token adicional no contexto é cobrado a cada inferência; carregar Skills sob demanda é outra forma de dizer "forneça um mapa, não um manual".+- **Extensões (Extensions)**: hooks TypeScript ligados a eventos integrados do ciclo de vida. A seção Hooks do [README do código-fonte](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) oferece exemplos oficiais: interceptar comandos perigosos como barreira de permissão, criar checkpoints do estado do código ao trocar de tarefa, proteger caminhos — proibindo a escrita em `.env`, por exemplo —, modificar a saída de ferramentas antes de entregá-la ao modelo e injetar mensagens externas, por observação de arquivos/Webhook/CI, para despertar o agent. Essas APIs de hooks também são exportadas por `@mariozechner/pi-coding-agent/hooks`. O harness da comunidade [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) encapsula ainda mais essa superfície em extensões prontas, como skill-router, session-summary, extract-patterns e telemetry.++As extensões são a decisão de design mais importante do Pi: **ele não oferece apenas alguns controles; expõe toda a superfície de eventos interna do runtime.** Quer adicionar memória? Injete-a em `agent/pre-step`. Quer registrar comportamentos? Assine eventos de sessão. Quer alterar a requisição ao modelo? Use um hook em `agent/request`. Você pode fazer o próprio Pi modificar seu harness — algo mais próximo da definição de "harness programável" do que qualquer opção de configuração.++## Feedback e validação: até o "aprendizado" vira harness++Pi não traz uma barreira de testes obrigatória integrada — cabe ao usuário registrar os comandos de validação em AGENTS.md. Porém, o harness da comunidade [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) estrutura o "loop de feedback" por extensões, e a seção Hooks do README oficial fornece uma base semelhante:++- **session-summary** (extensão do pi-agent-harness): mantém entradas contínuas em `PROGRESS.md` — o subsistema de estado do curso para acompanhar o progresso de tarefas longas.+- **extract-patterns** (extensão do pi-agent-harness): coleta nas sessões possíveis lições aprendidas e as consolida em `LESSONS.md` — transformando a "passagem de contexto antes do fim de cada sessão" de convenção em mecanismo.+- **telemetry** (extensão do pi-agent-harness): registra uso de tokens, custos e outros dados — observabilidade.++O mesmo repositório da comunidade confirma ainda mais esse padrão: `VISION.md` (objetivo), `PROGRESS.md` (progresso), `LESSONS.md` (experiências) e `STANDARDS.md` (padrões), todos arquivos Markdown persistidos entre sessões. É exatamente a estratégia recomendada pelo curso — "repositório como fonte da verdade + arquivo de progresso + mecanismo de passagem de contexto" — transformada em uma camada pronta para uso pelas extensões do Pi.++## Mapeamento para o framework do curso++Avaliação do Pi pelos cinco subsistemas do curso — subjetiva, para fins de comparação:++| Subsistema | Implementação no Pi | Avaliação |+| --- | --- | --- |+| Instruções | Carregamento hierárquico de AGENTS.md + SYSTEM.md | Hierarquia clara, mas as regras precisam ser escritas pelo usuário |+| Ferramentas | Skills sob demanda + hooks de extensão em todo o ciclo de vida | Extremamente robusto; transforma o sistema de ferramentas em uma superfície programável |+| Ambiente | Autodescrição via SYSTEM.md; runtime declarado pelo usuário em AGENTS.md | Mecanismo aberto, mas reprodutibilidade depende da descrição do usuário |+| Estado | Árvore de sessões + compactação personalizável + PROGRESS.md | Extremamente robusto; continuidade entre sessões e recuperação são centrais |+| Feedback | Comandos de validação definidos pelo usuário; session-summary / extract-patterns como mecanismos | O mecanismo é fornecido; o conteúdo depende do usuário |++A escolha do Pi contrasta claramente com Claude Code e Codex: Claude Code incorpora "memória, permissões e subagents" ao núcleo, pronto para uso; Codex torna "normas do repositório e isolamento do ambiente" os padrões; Pi escolhe **não decidir nada por você** — transforma o poder de decisão em pontos de extensão. O custo é que você precisa escrever suas próprias extensões ou instalar pacotes criados por terceiros.++## Designs que vale a pena adotar++1. **Torne a estratégia de compactação conectável**. "Como compactar o contexto" não deve ser um parâmetro fixo no harness, mas uma interface de estratégia substituível.+2. **Use uma árvore de sessões no lugar de resumos rígidos**. A recuperação entre sessões não precisa depender de "um resumo da rodada anterior"; a reprodução estruturada do histórico costuma formar um subsistema de estado mais confiável.+3. **Favoreça o cache de prompts**. Carregue Skills sob demanda e não insira todas as regras de uma vez no prompt de sistema: isso é engenharia de contexto e também engenharia de custos.+4. **Permita que o agent modifique seu próprio harness**. Se a superfície de extensão do harness for aberta o bastante, a própria "otimização do comportamento do agent" poderá ser parcialmente automatizada pelo agent.++## Fontes de referência (originais / código-fonte)++Cada afirmação pode ser rastreada até os textos originais ou o código-fonte abaixo, evitando paráfrases baseadas apenas em lembranças:++- **Site oficial pi.dev**: posicionamento "Ask Pi to build what you want, or install a package that does it your way", quatro camadas personalizáveis e árvore de sessões — "sessions are stored as trees", `/tree`, armazenamento em um único arquivo, exportação em HTML e compartilhamento como gist.<br/>https://pi.dev/+- **Documentação oficial pi.dev · Sessions**: compactação conectável — por tópico, ciente de código ou com outro modelo de resumo — e descrição dos mecanismos de compactação automática e injeção dinâmica de contexto.<br/>https://pi.dev/docs/usage/sessions+- **Documentação oficial pi.dev · Extensions**: extensões podem injetar mensagens antes de cada rodada, filtrar o histórico, implementar RAG e construir memória de longo prazo.<br/>https://pi.dev/docs/usage/extensions+- **Documentação oficial pi.dev · Project Context**: semântica replace / append de SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **README do código-fonte do Pi Coding Agent** (badlogic/pi-mono): carregamento de AGENTS.md em três níveis — global → diretórios pais → diretório atual —, condições de ativação de `/compact` e da compactação automática, ponto de corte de 20 mil tokens, Skills sob demanda e padrão Agent Skills, ciclo de vida de Hooks e quatro casos oficiais de uso, Programmatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **Repositório da comunidade pi-agent-harness**: extensões skill-router / session-summary / extract-patterns / telemetry e sistema de arquivos VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++Material relacionado: [Aula 2 · O que exatamente é um Harness](../lectures/lecture-02-what-a-harness-actually-is/) | [Aula 5 · Manter a continuidade de contexto em tarefas entre sessões](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Aula 13 · Da condução manual ao loop automatizado](../lectures/lecture-13-loop-engineering/)diff --git a/docs/pt-BR/index.md b/docs/pt-BR/index.mdindex a68060b..e7f6039 100644--- a/docs/pt-BR/index.md+++ b/docs/pt-BR/index.md@@ -25,6 +25,10 @@ Escolha seu caminho de aprendizado para começar. O curso é dividido em palestr<h3>Biblioteca de Recursos</h3><p>Modelos prontos para uso (AGENTS.md, feature_list.json) para usar em seus próprios repositórios.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Análise dos harnesses de ponta</h3>+ <p>Como Pi, Claude Code, Codex e DeepSeek projetam seus harness na prática, conectado ao framework do curso.</p>+ </a></div>## O Mecanismo Central de um Harnessdiff --git a/docs/ru/harness-designs/claude-code/index.md b/docs/ru/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..6ba5f99--- /dev/null+++ b/docs/ru/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Разбор дизайна harness в Claude Code++В статье «[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)» Anthropic прямо утверждает: надёжность обеспечивает harness, а не модель; agent должен быть ограничен средствами «за пределами модели». Claude Code — продуктовая реализация этой идеи, и сама Anthropic прямо относит его к категории **agentic harness**. Это не маркетинговая формулировка: Claude Code, возможно, является наиболее подробно исследованным из публичных harness. Его исходный код открыт, сообщество подготовило обстоятельные исследовательские отчёты, а почти все ключевые механизмы из лекций курса — многоуровневая память, compaction контекста, permissions, hooks, subagent и сохранение session — получили полноценную продуктовую реализацию.++В этой статье мы разберём Claude Code через фреймворк пяти подсистем курса и сосредоточимся на том, как он реализует фундаментальные для harness идеи «управления контекстом», «предотвращения преждевременного объявления о завершении» и «детерминированных ограничений».++## Позиционирование в одном предложении++В основе Claude Code лежит простой цикл while: вызвать модель, выполнить инструмент, увидеть результат и снова вызвать модель. Но **подавляющая часть кода находится не в этом цикле, а в окружающих его системах** — системе permissions, конвейере compaction контекста, механизмах расширения, оркестрации subagent и хранилище session. В этом и состоит сущность harness: цикл — лишь скелет, а надёжность определяет всё, что находится вокруг него.++## Подсистема инструкций: многоуровневая система памяти++Система памяти Claude Code — его самый непосредственный вклад в теорию harness; она соответствует лекциям курса «Репозиторий должен стать единственным источником истины» и «Непрерывность контекста между session». [Официальная документация «How Claude remembers your project»](https://code.claude.com/docs/en/memory) прямо говорит: каждая session начинается с совершенно нового окна контекста, а знания между session переносят два механизма — файлы CLAUDE.md (написанные вами инструкции) и auto memory (заметки, которые пишет сам Claude).++Официальная документация разделяет файлы CLAUDE.md на четыре области действия — от самой широкой к самой узкой в порядке загрузки:++- **Уровень политики организации**: централизованно управляется IT/DevOps (например, `/etc/claude-code/CLAUDE.md`) и содержит корпоративные стандарты.+- **Пользовательский уровень `~/.claude/CLAUDE.md`**: личные предпочтения и правила, действующие во всех проектах.+- **Уровень проекта `./CLAUDE.md` или `./.claude/CLAUDE.md`**: проектный источник истины — структура, технологический стек и команды верификации; хранится в общем репозитории.+- **Локальный уровень `./CLAUDE.local.md`**: личные предпочтения внутри проекта; обычно добавляется в `.gitignore` и не коммитится.++Есть ещё два механизма:++- **Загрузка по требованию на уровне подкаталогов**: CLAUDE.md из подкаталога не загружается при запуске, а попадает в контекст лишь тогда, когда Claude читает файл из этого каталога.+- **Автоматическая память (auto memory)**: Claude самостоятельно записывает заметки на основе ваших исправлений и предпочтений; они общие для репозитория и действуют между worktree. В каждой session загружаются не более первых 200 строк или 25KB.++Эти четыре области действия образуют **иерархию инструкций**: в официальной документации сказано, что «чем конкретнее инструкции, тем позже они попадают в контекст» — инструкции проекта следуют за пользовательскими. Ценность этого решения в том, что в начале каждого разговора модели не приходится переваривать единый гигантский файл инструкций: они загружаются по месту, в зависимости от области действия. Это продуктовый ответ на вопрос лекции 4 «Почему один гигантский файл инструкций не работает».++## Подсистема контекста: пятиуровневый конвейер compaction++Claude Code управляет контекстом с помощью **пятиуровневого конвейера compaction** (five-layer compaction pipeline), а не простого подхода «когда заполнится — сделать summary». Эта архитектурная деталь получена из разбора исходного кода в отчёте VILA Lab [«Dive into Claude Code»](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). В лекции 5 объясняется, почему длительные задачи теряют непрерывность; ответ Claude Code — многоступенчатая воронка: сначала выполняется compaction без потерь с отсечением избыточных результатов инструментов, затем — структурированное извлечение, и только в конце используется LLM-summary с потерями. Предохранительный механизм не допускает чрезмерной compaction.++Эту схему дополняет **хранилище session с добавлением записей (append-oriented storage)**: вся история дописывается в `history.jsonl`, а `/resume` позволяет восстановить работу и создать ветвь fork. Благодаря этому принцип «перед завершением каждой session подготовить handoff» соблюдается не за счёт хорошей памяти, а за счёт дописываемого и воспроизводимого слоя хранения.++## Подсистема инструментов: четыре механизма расширения++Claude Code разделяет поверхность расширения на четыре категории, каждая из которых решает свой тип задач. Это одна из наиболее полезных частей его дизайна:++- **Skills**: [официальная документация](https://code.claude.com/docs/en/skills) определяет их как процедурные знания, описанные в `SKILL.md`, автоматически загружаемые по ключевым словам с progressive disclosure. Они подходят для предметных знаний о том, «как сделать определённую вещь».+- **MCP**: описанный в [официальной документации](https://code.claude.com/docs/en/mcp) протокол JSON-RPC подключает внешние системы; это стандартный интерфейс, позволяющий «рукам модели дотянуться до внешнего мира».+- **Hooks**: [официальная документация](https://code.claude.com/docs/en/hooks) описывает детерминированные скрипты, подключаемые к таким событиям жизненного цикла, как `PreToolUse`, `PostToolUse` и `Stop`.+- **Plugin / Subagents**: [официальная документация](https://code.claude.com/docs/en/sub-agents) описывает передачу сложных задач специализированным agent.++Ключевое решение — **разделение ответственности**: CLAUDE.md отвечает на вопрос «что», skills — «как», MCP — «куда подключаться», hooks — «когда принудительно применить». Если команда смешивает эти уровни — например, записывает в CLAUDE.md то, что должен делать MCP, — возникает описанная в курсе утечка контекста.++## Обратная связь и верификация: детерминированные ограничения + разделение ролей человека и машины++Лекция 10 утверждает, что настоящая верификация требует прохождения полного процесса. В Claude Code этому соответствует двухконтурный механизм:++**1. Система permissions (детерминированные ограничения).** Permissions Claude Code — это не правило «спрашивать обо всём», а семь режимов и классификатор на основе ML: операции с низким риском разрешаются, а для высокорисковых операций система, в зависимости от политики, запрашивает подтверждение или отклоняет их (архитектурные подробности см. в [разборе VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Так идея «задать agent чёткие границы» из лекции 7 становится принудительным правилом runtime, а не просьбой в prompt.++**2. Hooks (защита от преждевременного объявления о завершении).** Hook `PostToolUse` может принудительно запустить проверки после выполнения инструмента и вернуть их результаты в контекст; hook `Stop` вмешивается, когда agent объявляет о завершении. Это и есть разделение «исполнителя» и «проверяющего»: [Anthropic прямо отмечает в статье о harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), что agent уверенно хвалит собственную работу («confidently praised their work»), поэтому hooks внедряют **детерминированные** проверки вместо доверия самооценке модели.++**3. Subagent (изоляция контекста).** История диалога каждого subagent хранится в отдельном файле sidechain и **не раздувает контекст родительского agent** (см. [разбор VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Здесь объединены «границы задачи» и «изоляция контекста»: при разделении задач одновременно изолируется загрязнение контекста.++## Наблюдаемость и сохранение session++Логи Claude Code представляют собой полную дописываемую историю в history.jsonl, а явные команды `/compact`, `/clear` и `/init` позволяют активно управлять состоянием контекста, не дожидаясь пассивно его заполнения. Команда `/init` даже превращает принцип из лекции 6 «agent должен инициализироваться перед каждой работой» в одну команду: согласно [официальной документации](https://code.claude.com/docs/en/memory), она автоматически анализирует кодовую базу и создаёт начальный CLAUDE.md с командами сборки, инструкциями по тестированию и инженерными соглашениями.++## Сопоставление с фреймворком курса++| 子系统 | Claude Code 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 作用域分层(组织/用户/项目/本地)+ 自动记忆 | 分层记忆是标杆实现 |+| 工具 | 技能 + MCP + 钩子 + 子智能体四类扩展 | 职责划分清晰,是核心亮点 |+| 环境 | 项目内设置 + settings.json | 靠用户在 CLAUDE.md 里自描述 |+| 状态 | 追加式会话存储 + 五层压缩 + resume/fork | 极强,长任务连续性的参考实现 |+| 反馈 | 权限分类器 + PostToolUse 钩子强制检查 | 把"防提前宣告完成"变成确定性机制 |++## Дизайнерские решения, которые стоит перенять++1. **Разделяйте инструкции по области действия**, а не складывайте их в один файл. CLAUDE.md на уровне каталога — элегантная реализация «загрузки по месту».+2. **Compaction — многоступенчатая воронка**: сначала без потерь, затем с потерями; не начинайте сразу с summary всего текста.+3. **Используйте hooks для детерминированных проверок**: runtime-принуждение, а не просьба в prompt, предотвращает преждевременное объявление о завершении.+4. **Изолируйте контекст subagent**: разделяйте одновременно задачи и контекст, чтобы результаты подзадач не загрязняли основной цикл.+5. **Дописываемое и воспроизводимое хранилище session**: надёжный handoff обеспечивает слой хранения, а не память.++## Источники (оригинальные материалы / исходный код)++Каждое утверждение можно проверить по приведённому ниже оригинальному материалу или исходному коду — мы не пересказываем по памяти:++- **Claude Code 官方文档 · Memory**: новый контекст для каждой session, четыре области действия CLAUDE.md, загрузка по требованию из подкаталогов, auto memory (200 строк / 25KB), создание CLAUDE.md командой `/init`.<br/>https://code.claude.com/docs/en/memory+- **Claude Code 官方文档 · Skills / MCP / Hooks / Sub-agents**: определения четырёх механизмов расширения и событий (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab《Dive into Claude Code》** (отчёт с разбором исходного кода): пятиуровневый конвейер compaction, семь режимов permissions + ML-классификатор, sidechain для subagent и дописываемое хранилище session history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic《Effective harnesses for long-running agents》**: источник тезисов «надёжность обеспечивает harness, а не модель», о склонности agent уверенно хвалить собственную работу и об использовании hooks для верификации.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack 导读** (сообщество; разделение CLAUDE.md / Skills / MCP / Subagents / Hooks): дополнительное чтение о разделении ответственности между механизмами расширения.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Связанные лекции: [лекция 3 «Как сделать репозиторий единственным источником истины»](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [лекция 9 «Как не дать agent преждевременно объявить о победе»](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [лекция 10 «Настоящая верификация требует прохождения полного процесса»](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/ru/harness-designs/codex/index.md b/docs/ru/harness-designs/codex/index.mdnew file mode 100644index 0000000..e9881c8--- /dev/null+++ b/docs/ru/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Разбор дизайна harness в Codex++[Codex](https://openai.com/index/harness-engineering/) от OpenAI, возможно, теснее всех четырёх продуктов связан с фундаментальной идеей harness. Статья «Harness Engineering», давшая название всей области, основана на опыте команды OpenAI по созданию продуктов с помощью Codex. Поэтому разбор дизайна harness в Codex — в значительной степени разбор инженерной практики, стоящей за этой статьёй.++Философию Codex можно выразить одним предложением: **репозиторий — источник истины (repository as the system of record), AGENTS.md — лишь страница-оглавление, а ценность инженерной работы состоит в проектировании среды, выражении намерения и построении циклов обратной связи.**++## Позиционирование в одном предложении++За несколько недель команда OpenAI с помощью Codex создала продукт, который в итоге вырос до более чем миллиона строк кода, и **каждая строка была написана Codex** — см. раздел «Designing for growth» в оригинальной статье [Harness Engineering](https://openai.com/index/harness-engineering/). Эта практика отвечает на вопрос: как организовать систему, когда роль инженера меняется с «написания кода» на «проектирование harness». Сам Codex CLI — монолитный бинарный файл с открытым исходным кодом, реализованный на Rust ([github.com/openai/codex](https://github.com/openai/codex)), но его главный вклад в harness связан с **соглашениями (convention)** и **инженерией контекста**, а не с эффектными точками расширения.++## Подсистема инструкций: AGENTS.md — страница-оглавление, а не энциклопедия++Это самое влиятельное дизайнерское решение Codex для теории harness:++> Один гигантский файл инструкций плохо поддаётся механизированным проверкам — покрытия, актуальности, владения и перекрёстных ссылок, — поэтому расхождение с реальностью неизбежно. В результате мы перестали считать AGENTS.md энциклопедией и стали использовать его как **страницу-оглавление**. Знания о кодовой базе находятся в структурированной документации, а AGENTS.md указывает на неё.++(Это прямой пересказ раздела «AGENTS.md should be a directory page» из оригинальной статьи [Harness Engineering](https://openai.com/index/harness-engineering/).)++Лекция 4 объясняет, почему «один гигантский файл инструкций не работает», а Codex предлагает прямое решение: держать AGENTS.md в пределах примерно 100 строк — оригинальная статья рекомендует около 100 строк и советует при приближении к пределу переносить материал в `docs/`. Всё, что не помещается, разделяется на документы в каталоге `docs/`, которые agent читает по требованию. Именно отсюда происходит авторитетная формулировка «дайте карту, а не инструкцию».++С этим связан принцип **«обеспечивайте инварианты, не занимайтесь микроменеджментом реализации»** (в оригинале: «don't micromanage the implementation; focus on invariants»): AGENTS.md содержит только жёсткие ограничения, которые нельзя нарушать, и команды верификации, а конкретную реализацию выбирает модель. Это напрямую соответствует принципу лекции 2 «ограничения вместо микроменеджмента».++## Подсистема контекста: Write-Select-Compress-Isolate++Инженерию контекста Codex можно описать четырьмя стратегиями. Этот фреймворк был сформулирован сообществом после того, как «context engineering» стала самостоятельной дисциплиной, а затем сопоставлен с Codex; источник — [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/):++- **Write (вынести наружу)**: сохранять контекст за пределами окна — выводы записывать в документацию, состояние в файлы, а не оставлять их в разговоре. Это соответствует принципу «репозиторий — источник истины».+- **Select (выбрать для загрузки)**: помещать в окно только необходимые token — AGENTS.md указывает путь, а файлы читаются по требованию вместо загрузки всего репозитория.+- **Compress (compaction)**: сохранять действительно важное. В Codex есть автоматическая compaction и ручная команда `/compact`; `compact_prompt` можно настроить (см. [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (изолировать)**: разделять контекст по разным границам — использовать subagent для изоляции контекста отдельных задач, чтобы, например, frontend-subagent никогда не видел database schema backend.++У Codex есть ещё одна тонкая деталь дизайна контекста среды. Анализ исходного кода в сообщественном проекте [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) показывает, что `build_environment_update_item` выводит только **изменившиеся поля** — CWD, ветвь git, файловую систему — и только при изменении среды, а не вставляет полный системный контекст на каждом раунде. Это практическая реализация принципа «не держать в контексте повторяющиеся token».++## Инструменты и границы: изоляция worktree + subagent++У Codex есть два ключевых механизма harness:++**1. Изоляция среды с помощью git worktree.** В разделе «Environment» оригинальной статьи [Harness Engineering](https://openai.com/index/harness-engineering/) прямо сказано: каждая задача выполняется в отдельном git worktree вместе с локальным стеком наблюдаемости — логами, метриками и трассировками, — чтобы каждое изменение проверялось в независимой среде. Это физическая реализация принципа лекции 7 «Задавайте agent чёткие границы каждой задачи»: границы принудительно обеспечиваются изоляцией среды, а не просьбой в инструкциях. Подсистема среды здесь реализована как жёсткая изоляция.++**2. Subagent на уровне ядра.** `spawn_agent` / `wait_agent` в Codex — инструменты уровня ядра: модель явно создаёт subagent, выделяет ему отдельную историю session и набор инструментов, а затем ждёт результат. Subagent наследует инструкции AGENTS.md родителя, но работает в **собственном контексте**. Конфигурация хранится в `.codex/agents/*.toml`, где можно задать разные модели и инструкции; подробности см. в разделе Sub-agents статьи [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/). Это непосредственная реализация «изоляции контекста» и одновременно духа «handoff» из лекции 12: каждый subagent — рабочая единица с чёткими границами.++## Подсистема обратной связи: команды верификации как часть стандарта++Практика OpenAI особо подчёркивает один принцип: явно перечисляйте команды верификации в AGENTS.md, чтобы способ проверки правильности стал частью репозитория. В инженерном процессе Codex тесты, CI, документация и конфигурация наблюдаемости создаются самим Codex и образуют **исполняемые пути верификации**. Решение проблемы «модель мощная, но ненадёжная» состоит не в надежде на сознательность модели, а в том, чтобы **путь верификации стал стандартным компонентом harness**.++Политики подтверждения (approval policies) и режим планирования (plan mode) обеспечивают ещё одно направление обратной связи: перед высокорисковыми операциями сначала составляется план и запрашивается подтверждение. Так «границы задачи» и «право человека принимать решения» становятся средствами управления runtime.++## Сопоставление с фреймворком курса++| 子系统 | Codex 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 目录页 + docs/ 拆分 + 执行不变量 | 教科书级,定义了"给地图不给说明书" |+| 工具 | worktree 隔离 + spawn_agent 子智能体 | 边界靠环境硬隔离,很强 |+| 环境 | 独立 worktree + 可观测性栈 | worktree 隔离是其招牌 |+| 状态 | Write 策略(状态写进文件/文档) | 依赖约定而非内建记忆 |+| 反馈 | 验证命令入规范 + 审批策略 + plan mode | 反馈路径默认化,值得抄 |++Сравнение Codex и Claude Code особенно интересно. Claude Code следует «сложению», встраивая память, permissions и subagent в ядро. Codex следует «вычитанию»: ядро остаётся сдержанным, а больше ответственности возлагается на соглашения репозитория и инженерию контекста. Поэтому сообщество часто говорит, что «философия harness в Codex ценнее его кода».++## Дизайнерские решения, которые стоит перенять++1. **Пишите AGENTS.md как страницу-оглавление**: держите его примерно в пределах 100 строк, ссылайтесь на подробности в docs/ и обеспечьте возможность механизированной проверки.+2. **Фиксируйте только инварианты, не занимайтесь микроменеджментом реализации**: жёсткие ограничения и команды верификации, остальное — модели.+3. **Используйте worktree для изоляции среды**: границы задач должны принудительно задаваться средой, а не просьбами в инструкциях.+4. **Передавайте только приращения контекста среды**: выводите на каждом раунде лишь изменившиеся поля, не вставляя заново полный системный контекст.+5. **Используйте subagent для изоляции контекста**: разделяйте не только задачи, но и контекст, чтобы подзадачи не загрязняли основной цикл.++## Источники (оригинальные материалы / исходный код)++Каждое утверждение можно проверить по приведённому ниже оригинальному материалу или исходному коду — мы не пересказываем по памяти:++- **OpenAI《Harness Engineering》**: AGENTS.md как страница-оглавление и рекомендация примерно 100 строк, executive invariants / don't micromanage, изоляция worktree + стек наблюдаемости, включение команд верификации в стандарт, пример продукта объёмом более миллиона строк, политики подтверждения и plan mode. Основной источник всех ключевых тезисов статьи.<br/>https://openai.com/index/harness-engineering/+- **OpenAI 官方《AGENTS.md》规范** (AGENTS.md как стандарт соглашений между инструментами):<br/>https://openai.com/index/agents-md/+- **Codex CLI 开源仓库** (монолитный бинарный файл, реализованный на Rust):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (сообщество): фреймворк Write-Select-Compress-Isolate, `/compact` и `compact_prompt`, subagent `spawn_agent` / `wait_agent` и конфигурация `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (сообщественный анализ исходного кода): подробности реализации, включая инкрементальный контекст среды в `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Связанные лекции: [лекция 3 «Как сделать репозиторий единственным источником истины»](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [лекция 4 «Как разделить инструкции между разными файлами»](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [лекция 7 «Как задать agent чёткие границы каждой задачи»](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/ru/harness-designs/deepseek/index.md b/docs/ru/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..2681e0e--- /dev/null+++ b/docs/ru/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# Разбор дизайна DeepSeek Harness++[DeepSeek Harness](https://deepseek.com/harness) (команда `dsh`, репозиторий `deepseek-ai/deepseek-harness`) выпущен в августе 2026 года в статусе Developer Preview. Официальное определение предельно прямое: **Agent = Model + Environment + Tools + State** — модель, среда, инструменты и состояние.++Если при разборе первых трёх продуктов мы спрашивали «как следует проектировать harness», DeepSeek Harness задаёт более радикальный вопрос: **может ли harness отделиться от конкретной модели и стать независимым runtime?** Его ответ — да, и эта идея доведена до предела. В [архитектурной документации](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) прямо сказано: *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* — каждая часть продукта является plugin, включая адаптер модели, реестр инструментов, лог session и даже сам цикл agent.++В этой статье мы сосредоточимся на трёх аспектах: ядре на основе plugin, швах возможностей (capability seam), конвейере событий и сильнейшем инженерном ограничении «Model-visible means logged».++## Позиционирование в одном предложении++Традиционный coding agent устроен как «LLM + фиксированный цикл agent + фиксированный набор инструментов». DeepSeek Harness устроен как «модель + ядро plugin (Cordis)». Ядро отвечает только за загрузку и выгрузку plugin, зависимости и механизм событий и **не владеет никакими конкретными возможностями agent**. В [архитектурной документации](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) это сформулировано так: «There is no privileged core to patch» — нет привилегированного ядра, которое нужно изменять, — и «you extend dsh by mounting a plugin beside the others» — для расширения dsh достаточно подключить plugin рядом с остальными, не изменяя ядро. Поэтому даже сам цикл agent не является неприкосновенным: можно взять модель DeepSeek, подключить subagent Claude Code, добавить удалённую песочницу, написать собственную память, заменить цикл и UI и собрать совершенно нового agent.++Это наиболее последовательная реализация тезиса курса «всё за пределами весов модели — harness»: если harness независим, пусть он станет самостоятельной операционной системой.++## Архитектурное ядро 1: шов возможностей (Capability Seam)++DeepSeek Harness представляет «возможность» с помощью Service и разделяет почти каждую возможность на три уровня:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Возьмём файловую систему: под `FS Service` находятся несколько Provider — Local FS, E2B FS и Remote FS, — а выше они единообразно представлены как file tools. Shell, Subprocess, Sandbox, Web, LLM и SubAgent используют ту же структуру. Это трёхуровневое разделение не наше обобщение: в оригинальном разделе [Architecture · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) сказано: *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* — шов возможностей является заменяемой возможностью с тремя ролями: Service Definition объявляет интерфейс, Service Provider реализует его, а Consumer использует, обычно в виде инструмента, доступного модели.++Это решает давнюю проблему инженерии harness: **должен ли agent зависеть от «конкретного инструмента» или от «интерфейса возможностей»?** DeepSeek Harness выбирает второе. В терминах курса это означает, что «подсистема инструментов» стандартизирована как интерфейс: при замене Provider представление инструмента для модели не меняется, хотя среда полностью заменяется.++## Архитектурное ядро 2: конвейер событий (Event Pipeline)++Внутренняя архитектура DeepSeek Harness — не простой цикл «LLM → инструмент → LLM», а конвейер событий, каждый этап которого является точкой, доступной для прослушивания plugin:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(Этот конвейер воспроизводит раздел [Architecture · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): `turn/*`, `step/*`, `user/message`, `assistant/*` и `tool/*` — сохраняемые события session; `agent/pre-step`, `agent/request`, `llm/stream` и `tools/*` — точки расширения, доступные plugin.)++Главное преимущество такого дизайна: **множество функций вообще не требуют изменения самого цикла agent**. Нужна проверка безопасности перед выполнением инструмента? Слушайте `tools/pre-execute`. Нужна память? Внедряйте её в `agent/pre-step`. Хотите записывать поведение? Подпишитесь на события session. Хотите изменить запрос модели? Подключитесь к `agent/request`. Нужно решить, продолжать ли рассуждение? Слушайте `agent/turn-stopping`.++По сравнению с лекцией 11 «Как сделать работу agent наблюдаемой» DeepSeek Harness идёт дальше: он не просто «добавляет логи», а превращает **каждый шаг цикла в точку события**, позволяя подключать наблюдаемость, permissions, память и политики как слушателей цикла вместо жёсткого встраивания в него.++## Архитектурное ядро 3: Session Event Log и «Model-visible means logged»++В DeepSeek Harness есть **append-only Session Event Log** — лог событий session только для добавления — и действует чрезвычайно строгое инженерное ограничение. Оригинальный текст раздела [Architecture · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md):++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++Иными словами, всё видимое модели должно быть записано. Всё, что попадает в запрос модели, должно восстанавливаться из лога, и это принудительно обеспечивает инвариант runtime.++Наблюдаемость здесь — не логи, добавленные постфактум, а первичное ограничение harness: всё, что попадает в контекст модели, по умолчанию должно оставлять запись. Это прямо перекликается с тезисом заключительной лекции «наблюдаемость относится к внутреннему устройству harness» и превращает append-only в принцип проектирования хранилища: лог только дополняется и не перезаписывается, а состояние session можно воспроизвести.++## Сопоставление с фреймворком курса++| 子系统 | DeepSeek Harness 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 插件化;规则/技能均以插件形态注入 | 极自由,但没有内置的"CLAUDE.md"式惯例 |+| 工具 | Service Definition → Provider → Consumer 能力接缝 | 工具子系统标准化的极致 |+| 环境 | 沙箱/FS/Shell 全部可换 Provider(含远程 E2B) | 环境彻底可插拔 |+| 状态 | append-only Session Event Log + Model-visible means logged | 可观测性是第一性约束 |+| 反馈 | tools/pre-execute 上的 permission / guard / policy / hook | 反馈机制事件化 |++Принципиальное отличие DeepSeek Harness от остальных трёх продуктов состоит в том, что Pi, Claude Code и Codex оптимизируют harness «внутри конкретного agent», а DeepSeek Harness определяет harness как **независимую от модели операционную систему**, где сам agent — лишь заменяемое приложение. Цена очевидна: высокая свобода означает высокую стоимость конфигурации. Это неотъемлемая обратная сторона модели «harness как OS» — особенно на этапе Developer Preview, когда продукт предназначен для раннего знакомства, а механизмы ещё развиваются.++## Дизайнерские решения, которые стоит перенять++1. **Превратите каждый шаг цикла в точку события**: подключайте permissions, память, политики и логи к циклу как слушателей, а не встраивайте их жёстко.+2. **Стандартизируйте швы возможностей**: зависите от «интерфейсов возможностей», а не от «конкретных инструментов», чтобы можно было целиком заменить среду, не меняя поверхность инструментов, видимую модели.+3. **Model-visible means logged**: всё видимое модели должно записываться; сделайте наблюдаемость не «дополнительным преимуществом», а «первичным ограничением».+4. **Append-only лог session**: воспроизводимое состояние и надёжный handoff — инженерная гарантия того, что «каждая session оставляет после себя чистое состояние».++## Источники (оригинальные материалы / исходный код)++Каждое утверждение можно проверить по приведённому ниже оригинальному материалу или исходному коду — мы не пересказываем по памяти:++- **DeepSeek Harness 官网**: определение продукта «Agent = Model + Environment + Tools + State», статус Developer Preview и команда `dsh`.<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness 仓库** (команда `dsh`, лицензия MIT):<br/>https://github.com/deepseek-ai/deepseek-harness+- **架构文档 architecture.md**: главный источник статьи — «Every part of the product is a plugin», «There is no privileged core to patch», конвейер событий Turn flow, три роли Capability seams, «Model-visible means logged» и инвариант runtime, append-only Session Event Log, швы возможностей fs/tools/telemetry и подсистемы `ctx.*`.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **架构文档 · 配套子文档**: введение в ядро Cordis (plugins contribute services, typed events, reversible effects), подробности швов возможностей и подсистема Session.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Связанные лекции: [лекция 11 «Как сделать работу agent наблюдаемой»](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [лекция 12 «Каждая session должна завершаться чистым handoff»](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [лекция 2 «Что такое harness на самом деле»](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/ru/harness-designs/index.md b/docs/ru/harness-designs/index.mdnew file mode 100644index 0000000..5ab5fa4--- /dev/null+++ b/docs/ru/harness-designs/index.md@@ -0,0 +1,29 @@+# Разбор передовых harness++В этом разделе теория harness из лекций сопоставляется с актуальными передовыми продуктами. В каждом продукте нас интересует только одно: **как устроен его harness** — то есть слой инженерной инфраструктуры вокруг модели: пять подсистем — инструкции, инструменты, среда, состояние и обратная связь, — а также ключевые механизмы непрерывности контекста, инициализации, верификации, наблюдаемости, handoff и циклов.++Мы намеренно не обсуждаем, насколько сильны рассуждения модели, насколько высок её результат в отдельном бенчмарке и «что умеет этот agent» в целом. Это вопросы уровня модели и продукта. Здесь мы разбираем только harness — всё, что находится за пределами весов модели.++## Зачем это разбирать++В первой лекции говорилось: мощная модель ещё не означает надёжного выполнения. Одна и та же модель в разных harness может показывать результаты, отличающиеся на порядок. Но лекции объясняют, «как следует делать», а эти продукты показывают, «как это на практике делают ведущие команды».++Каждый продукт — это самостоятельный набор проектных решений. Сопоставив их, вы увидите, как одни и те же ключевые механизмы совершенно по-разному реализуются разными командами:++- **Pi** строит harness как минималистичное ядро с программируемыми расширениями и занимается инженерией контекста по принципу «минимальный системный prompt + загрузка по требованию».+- **Claude Code** превращает harness в полноценную runtime-среду: многоуровневая память, пятиуровневая compaction, permissions, hooks и subagent.+- **Codex** доводит философию harness до предела: репозиторий — источник истины, AGENTS.md — лишь страница-оглавление, а worktree изолирует среду.+- **DeepSeek Harness** и вовсе определяет сам harness как независимый от модели runtime: Everything is a Plugin.++## Список статей++- [Разбор дизайна harness в Pi](./pi/): минималистичное ядро + программируемые расширения; инженерия контекста выходит за пределы системного prompt.+- [Разбор дизайна harness в Claude Code](./claude-code/): многоуровневая память, пятиуровневая compaction, permissions и hooks — полноценная runtime-среда для agent.+- [Разбор дизайна harness в Codex](./codex/): репозиторий как источник истины, AGENTS.md как страница-оглавление, изоляция среды и циклы обратной связи.+- [Разбор дизайна DeepSeek Harness](./deepseek/): Everything is a Plugin — даже сам цикл agent реализован как заменяемый plugin.++## Как читать++Рекомендуем сначала прочитать первые лекции курса — особенно [лекцию 2 «Что такое harness на самом деле»](../lectures/lecture-02-what-a-harness-actually-is/) — и освоить модель пяти подсистем, а затем вернуться сюда и посмотреть, как эти механизмы реализованы в реальных продуктах.++В конце каждой статьи есть два раздела — «Сопоставление с фреймворком курса» и «Дизайнерские решения, которые стоит перенять». Они помогут быстро перевести продуктовые решения обратно в понятия курса и применить их в собственном проекте.diff --git a/docs/ru/harness-designs/pi/index.md b/docs/ru/harness-designs/pi/index.mdnew file mode 100644index 0000000..6ac3e71--- /dev/null+++ b/docs/ru/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Разбор дизайна harness в Pi++[Pi](https://pi.dev/) (npm-пакет `@earendil-works/pi-coding-agent`) называет себя «minimal agent harness» — минималистичным harness для agent. Эту формулировку стоит разобрать: Pi не называет себя «самым мощным coding agent» или «лучшим инструментом AI-программирования», а жёстко привязывает своё позиционирование к слову **harness**.++В этой статье мы разберём Pi через фреймворк пяти подсистем курса — инструкции, инструменты, среда, состояние и обратная связь — и посмотрим, чем его философия принципиально отличается от Claude Code и Codex. Сразу дадим ответ: **философия Pi — «минимальное ядро + программируемые расширения»; инженерия контекста выходит за пределы системного prompt, а менять harness предлагается пользователю (и даже самому Pi), вместо того чтобы Pi решал за вас, каким должен быть harness.**++## Позиционирование в одном предложении++Pi — минималистичное ядро: официальное позиционирование намеренно делает ядро небольшим и возвращает вам право принимать решения. На [главной странице pi.dev](https://pi.dev/) это сформулировано так: «Ask Pi to build what you want, or install a package that does it your way». Pi разделяет harness на четыре настраиваемых уровня:++- **Extensions**: TypeScript-hooks, подключаемые к событиям жизненного цикла Pi; программируемая поверхность уровня runtime.+- **Skills**: загружаемые по требованию пакеты возможностей с инструкциями и инструментами; progressive disclosure.+- **Prompt templates**: повторно используемые Markdown-prompts, разворачиваемые вводом `/name`.+- **Themes**: внешний вид TUI.++Само такое разделение на уровни уже является дизайном harness: **то, что увидит модель и когда именно она это увидит, полностью определяется правилами и extensions, а не жёстко зашивается в ядро.**++## Основной цикл++Как и любой coding agent, Pi в своей основе представляет собой цикл while: «рассуждение → выполнение инструмента → наблюдение → новое рассуждение». Примечателен не сам цикл, а то, как Pi работает с его внешним слоем: управление контекстом расширяется от внутренней «compaction» до внешнего «контроля» цикла.++Runtime Pi предоставляет программируемый интерфейс. В разделе [Programmatic Usage исходного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md), помимо интерактивного TUI, описаны скриптовые режимы печати/JSON, RPC-протокол и встраивание через SDK. Поэтому одним и тем же harness можно управлять вручную, шаг за шагом, либо автоматически — из CI/CD или другой программы. Это необходимое условие перехода «от ручного управления к автоматическому циклу» из лекции 13 об инженерии циклов: если harness допускает только интерактивное управление человеком, он никогда не сможет перейти к автоматическому циклу.++## Подсистема инструкций: AGENTS.md и SYSTEM.md++Pi сдержанно работает с «инструкциями», но выстраивает чёткую иерархию:++- **AGENTS.md**: раздел [Project Context Files исходного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) явно задаёт порядок загрузки: глобальный `~/.pi/agent/AGENTS.md` → последовательный обход родительских каталогов вверх → `./AGENTS.md` в текущем каталоге (CLAUDE.md также поддерживается). Так реализуется принцип «репозиторий — источник истины»: инструкции находятся в файлах, а не в напоминаниях из окна чата.+- **SYSTEM.md**: в [официальной документации pi.dev](https://pi.dev/docs/usage/project-context) сказано, что стандартный системный prompt можно заменить (replace) или дополнить (append) для конкретного проекта. Это единственная официальная точка входа, через которую Pi позволяет менять «системный prompt», и одновременно его слой «самоописания среды».++Pi подчёркивает, что его системный prompt **минималистичен**. За этим стоит явный компромисс: ядро не заполняется длинными правилами вида «если… то…»; вместо этого предоставляются точки расширения, а правила появляются в виде skills и extensions только тогда, когда нужны. Это напрямую перекликается с лекцией 4 «Почему один гигантский файл инструкций не работает»: сочетание «минимальное ядро + разделение файлов + загрузка по требованию» естественным образом позволяет Pi избежать проблемы гигантского файла инструкций.++## Состояние и контекст: наиболее детально проработанная часть Pi++Инженерия контекста в Pi заслуживает особого внимания: такие понятия курса, как «непрерывность контекста» и «предотвращение деградации контекста», здесь воплощены в конкретных механизмах.++**1. Программируемая compaction.** При приближении к пределу контекста старые сообщения автоматически сворачиваются в summary. В [официальной документации pi.dev](https://pi.dev/docs/usage/sessions) говорится, что сама стратегия compaction **настраивается**: с помощью extensions можно реализовать тематическую compaction, учитывающее код summary или даже поручить создание summary другой модели. В исходном README также описаны детали стандартного механизма: автоматическая compaction запускается в двух случаях — при восстановлении после переполнения контекста или при превышении порога сохранения; точка разбиения сохраняет примерно 20 тысяч последних token, а предшествующие сообщения сворачиваются в «context handoff» и далее проходят последовательную цепную compaction. Иными словами, Pi считает способ compaction не неизменяемой константой, а частью harness.++**2. Динамический контекст (Dynamic context).** В [официальной документации pi.dev](https://pi.dev/docs/usage/extensions) сказано, что перед каждым раундом рассуждения extensions могут внедрять сообщения, фильтровать историю сообщений, реализовывать RAG и строить долговременную память. Это следующий шаг после подхода «выполнить compaction, когда контекст заполнится»: вы решаете, что попадёт в окно, ещё до входа контекста в него. Pi переносит на поверхность extensions сразу две задачи курса — «сделать работу agent наблюдаемой и отлаживаемой» и «сохранять непрерывность контекста».++**3. Дерево session (Session tree).** На [главной странице pi.dev](https://pi.dev/) прямо сказано: «sessions are stored as trees»; команда `/tree` позволяет вернуться к любой исторической точке и продолжить работу, а все ветви сохраняются в одном файле. Это решает многократно подчёркнутую в курсе проблему «разрыва контекста между session» не жёстким склеиванием через summary, а структурированным воспроизведением истории. Ветви можно экспортировать в HTML или загрузить как gist для публикации — заодно решается и задача наблюдаемости.++## Подсистема инструментов: skills и extensions++«Инструменты» Pi разделены на два уровня:++- **Skills**: раздел [Skills исходного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) даёт точное определение — «self-contained capability packages that the agent loads on-demand», то есть автономные пакеты возможностей с инструкциями и инструментами, загружаемые по требованию и соответствующие стандарту Agent Skills. Благодаря progressive disclosure подробности skill попадают в контекст только при срабатывании и **не переполняют prompt cache**. Это дизайн harness с точки зрения стоимости: за каждый дополнительный token в контексте приходится платить при каждом рассуждении; загружать skills по требованию — ещё одна форма принципа «дайте карту, а не инструкцию».+- **Extensions**: TypeScript-hooks, подключаемые к встроенным событиям жизненного цикла. В разделе [Hooks исходного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) приведены официальные примеры применения: перехват опасных команд (шлюз permissions), checkpoint состояния кода при переключении задачи, защита путей (например, запрет записи в `.env`), изменение вывода инструмента до передачи модели, а также внедрение внешних сообщений (из наблюдателя файлов, Webhook или CI) для пробуждения agent. Эти hooks API также экспортируются из `@mariozechner/pi-coding-agent/hooks`. Сообщественный harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) дополнительно оборачивает поверхность hooks в готовые extensions: skill-router, session-summary, extract-patterns, telemetry и другие.++Extensions — главное дизайнерское решение Pi: **пользователь получает не несколько переключателей, а всю поверхность внутренних событий runtime.** Хотите добавить память? Внедрите её в `agent/pre-step`. Хотите записывать поведение? Подпишитесь на события session. Хотите изменить запрос модели? Подключитесь к `agent/request`. Можно даже поручить Pi изменить собственный harness — это гораздо ближе к определению «программируемого harness», чем любые параметры конфигурации.++## Обратная связь и верификация: даже «обучение» становится частью harness++В самом Pi нет обязательного тестового шлюза — команды верификации пользователь должен указать в AGENTS.md. Но сообщественный harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) структурирует «цикл обратной связи» посредством extensions, а раздел Hooks официального README описывает основу для подобных механизмов:++- **session-summary** (extension в pi-agent-harness): поддерживает скользящие записи в `PROGRESS.md` — это подсистема состояния из курса, отслеживающая прогресс длительных задач.+- **extract-patterns** (extension в pi-agent-harness): собирает из session кандидатов на извлечённые уроки и сохраняет их в `LESSONS.md`, превращая правило «перед завершением каждой session подготовить handoff» из договорённости в механизм.+- **telemetry** (extension в pi-agent-harness): записывает расход token, стоимость и другие показатели — наблюдаемость.++Тот же репозиторий сообщества дополнительно подтверждает этот паттерн: `VISION.md` (цель), `PROGRESS.md` (прогресс), `LESSONS.md` (опыт), `STANDARDS.md` (стандарты) — всё это Markdown-файлы с сохранением данных между session. Это в точности рекомендованная курсом схема «репозиторий как источник истины + файл прогресса + механизм handoff», превращённая механизмом extensions Pi в готовый к использованию слой.++## Сопоставление с фреймворком курса++Оценим Pi по пяти подсистемам курса (субъективно, для сравнения):++| 子系统 | Pi 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 分级加载 + SYSTEM.md | 层级清晰,但规则本身要靠用户写 |+| 工具 | 技能按需加载 + 扩展全生命周期钩子 | 极强,把工具系统做成了可编程面 |+| 环境 | SYSTEM.md 做环境自描述;运行时环境靠用户在 AGENTS.md 里声明 | 机制是开放的,但可复现性依赖用户自述 |+| 状态 | 会话树 + 压缩可定制 + PROGRESS.md | 极强,跨会话与可恢复性是其核心 |+| 反馈 | 验证命令靠用户定义;session-summary / extract-patterns 机制化 | 机制提供,内容靠用户 |++Выбор Pi резко контрастирует с Claude Code и Codex: Claude Code встраивает «память, permissions и subagent» в ядро и предоставляет их из коробки; Codex делает стандартными «соглашения репозитория и изоляцию среды»; Pi предпочитает **ничего не решать за вас**, превращая право выбора в точки расширения. Цена этого решения — необходимость писать extensions самостоятельно либо устанавливать чужие пакеты.++## Дизайнерские решения, которые стоит перенять++1. **Сделайте стратегию compaction подключаемой.** Способ compaction контекста в вашем harness должен быть не жёстко заданным параметром, а заменяемым интерфейсом стратегии.+2. **Используйте дерево session вместо жёсткого summary.** Восстановление между session не обязательно строить на «summary предыдущего раунда»: структурированное воспроизведение истории часто оказывается более надёжной подсистемой состояния.+3. **Учитывайте prompt cache.** Загружайте skills по требованию и не помещайте все правила в системный prompt сразу: это одновременно инженерия контекста и инженерия стоимости.+4. **Позвольте agent изменять собственный harness.** Если поверхность расширения harness достаточно открыта, оптимизацию поведения agent можно частично автоматизировать силами самого agent.++## Источники (оригинальные материалы / исходный код)++Каждое утверждение можно проверить по приведённому ниже оригинальному материалу или исходному коду — мы не пересказываем по памяти:++- **pi.dev 官网**: исходная формулировка позиционирования «Ask Pi to build what you want, or install a package that does it your way», четыре настраиваемых уровня и дерево session («sessions are stored as trees», `/tree`, сохранение в одном файле, экспорт HTML и публикация gist).<br/>https://pi.dev/+- **pi.dev 官方文档 · Sessions**: подключаемая compaction (topic-based / code-aware / другая модель для summary), автоматическая compaction и динамическое внедрение контекста.<br/>https://pi.dev/docs/usage/sessions+- **pi.dev 官方文档 · Extensions**: extensions могут перед каждым раундом рассуждения внедрять сообщения, фильтровать историю, выполнять RAG и строить долговременную память.<br/>https://pi.dev/docs/usage/extensions+- **pi.dev 官方文档 · Project Context**: семантика replace / append для SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent 源码 README** (badlogic/pi-mono): трёхуровневый порядок загрузки AGENTS.md (глобальный → родительские каталоги → текущий каталог), условия запуска `/compact` и автоматической compaction, точка разбиения в 20 тысяч token, загрузка Skills по требованию и стандарт Agent Skills, жизненный цикл Hooks с четырьмя официальными примерами, Programmatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness 社区仓库**: extensions skill-router / session-summary / extract-patterns / telemetry и система файлов VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++Связанные лекции: [лекция 2 «Что такое harness на самом деле»](../lectures/lecture-02-what-a-harness-actually-is/) | [лекция 5 «Как сохранять непрерывность контекста в задачах между session»](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [лекция 13 «От ручного управления к автоматическому циклу»](../lectures/lecture-13-loop-engineering/)diff --git a/docs/ru/index.md b/docs/ru/index.mdindex 66e916b..b924c49 100644--- a/docs/ru/index.md+++ b/docs/ru/index.md@@ -25,6 +25,10 @@ Learn Harness Engineering — курс, посвящённый инженери<h3>Библиотека материалов</h3><p>Готовые шаблоны (AGENTS.md, feature_list.json) для использования в своих репозиториях.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Разбор передовых harness</h3>+ <p>Как Pi, Claude Code, Codex и DeepSeek на самом деле проектируют свои harness — в привязке к рамке курса.</p>+ </a></div>## Основной механизм harnessdiff --git a/docs/tr/harness-designs/claude-code/index.md b/docs/tr/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..ccb31f5--- /dev/null+++ b/docs/tr/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Claude Code'un harness tasarımının incelenmesi++Anthropic, [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) yazısında güvenilirliğin modelden değil harness'tan geldiğini ve agent'ın "modelin dışında" kısıtlanması gerektiğini açıkça savunur. Claude Code bu düşüncenin ürünleştirilmiş örneğidir; Anthropic de onu doğrudan **agentic harness** kategorisine yerleştirir. Bu yalnızca bir pazarlama söylemi değildir. Claude Code, bugün kamuya açık biçimde en ayrıntılı incelenmiş harness olabilir: Kaynak kodu açıktır, topluluk araştırma raporları ayrıntılıdır ve ders notlarındaki temel mekanizmaların neredeyse tamamını (katmanlı bellek, bağlam compaction, permissions, hooks, subagent'lar ve session kalıcılığı) eksiksiz bir ürün uygulamasına dönüştürür.++Bu yazıda Claude Code'u dersin beş alt sistem çerçevesiyle inceliyor; özellikle "bağlam yönetimi", "tamamlandığını erken ilan etmeyi önleme" ve "deterministik kısıtlar" gibi temel harness kavramlarını nasıl hayata geçirdiğine bakıyoruz.++## Tek Cümlelik Konumlandırma++Claude Code'un merkezinde basit bir while döngüsü bulunur: modeli çağır, aracı çalıştır, sonucu gözlemle, modeli yeniden çağır. Ancak **kodun büyük çoğunluğu bu döngüde değil, döngüyü çevreleyen sistemlerdedir**: permissions sistemi, bağlam compaction hattı, genişletme mekanizmaları, subagent orkestrasyonu ve session depolama. harness'ın özü budur: Döngü iskelettir; güvenilirliği belirleyen, iskeletin dışındaki her şeydir.++## Talimat Alt Sistemi: Katmanlı Bellek Yapısı++Claude Code'un bellek sistemi, harness teorisine yaptığı en doğrudan katkıdır ve dersteki "gerçekliğin kaynağı depo" ile "session'lar arası bağlam sürekliliği" konularına karşılık gelir. [Resmî How Claude remembers your project belgesi](https://code.claude.com/docs/en/memory) açıkça şunu söyler: Her session yepyeni bir bağlam penceresiyle başlar ve bilgi, session'lar arasında iki mekanizmayla taşınır: CLAUDE.md dosyaları (sizin yazdığınız talimatlar) ve auto memory (Claude'un kendi yazdığı notlar).++Resmî belgeler CLAUDE.md dosyalarını kapsamlarına göre dört sınıfa ayırır (yükleme sırasında genelden özele):++- **Kuruluş politikası düzeyi**: IT/DevOps tarafından merkezi olarak yönetilir (ör. `/etc/claude-code/CLAUDE.md`); şirket çapındaki standartları içerir.+- **Kullanıcı düzeyi `~/.claude/CLAUDE.md`**: Projeler arası kişisel tercihler ve kurallar.+- **Proje düzeyi `./CLAUDE.md` veya `./.claude/CLAUDE.md`**: Projenin gerçeklik kaynağı; mühendislik yapısı, teknoloji yığını ve doğrulama komutları. Depoyla paylaşılır.+- **Yerel düzey `./CLAUDE.local.md`**: Proje içindeki kişisel tercihler; genellikle `.gitignore` dosyasına eklenir ve commit edilmez.++Bunlara ek olarak iki mekanizma daha vardır:++- **Alt dizin düzeyinde gerektiğinde yükleme**: Alt dizinlerdeki CLAUDE.md başlangıçta yüklenmez; yalnızca Claude o dizindeki bir dosyayı okuduğunda bağlama girer.+- **Otomatik bellek (auto memory)**: Claude, düzeltmelerinize ve tercihlerinize dayanarak kendiliğinden notlar yazar. Bu notlar depo kapsamında paylaşılır, worktree'ler arasında geçerlidir ve her session'da en fazla ilk 200 satır ya da 25KB yüklenir.++Bu dört kapsam bir **talimat hiyerarşisi** oluşturur. Resmî belgelere göre "daha özel talimatlar bağlama daha sonra girer" (proje talimatları kullanıcı talimatlarından sonra gelir). Değeri şuradadır: Modelin her konuşmanın başında dev bir talimat metnini sindirmesi yerine talimatlar, kapsamlarına göre en yakın noktada yüklenir. Bu, dördüncü dersteki "tek bir dev talimat dosyası neden başarısız olur" sorusunun ürünleştirilmiş yanıtıdır.++## Bağlam Alt Sistemi: Beş Aşamalı Compaction Hattı++Claude Code'un bağlam yönetimi, yalnızca "dolunca özetle" yaklaşımı değil, **beş aşamalı bir compaction hattıdır** (five-layer compaction pipeline). Bu mimari ayrıntı, kaynak kod düzeyindeki [VILA Lab Dive into Claude Code](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf) incelemesinden gelir. Beşinci ders "uzun görevlerin sürekliliği kaybetmesini" ele alır; Claude Code'un çözümü çok aşamalı bir hunidir: Önce kayıpsız budama (gereksiz araç sonuçlarını kaldırma), ardından yapılandırılmış damıtma, en sonunda kayıplı LLM özeti; ayrıca aşırı compaction'ı önleyen devre kesici mekanizmalar.++Buna eşlik eden session depolama tasarımı **ekleme odaklı session depolamadır (append-oriented storage)**. Tüm geçmiş `history.jsonl` dosyasına eklenir; `/resume` ile kurtarma ve fork dallanması desteklenir. Böylece "her session sona ermeden önce iyi bir devir teslimi yapılır"; iyi hafıza sayesinde değil, depolama katmanı ekleme tabanlı ve yeniden oynatılabilir olduğu için.++## Araç Alt Sistemi: Dört Genişletme Mekanizması++Claude Code, genişletme yüzeyini dört sınıfa ayırır. Her sınıf farklı bir sorunu çözer ve bu, tasarımının en çok örnek alınmaya değer kısmıdır:++- **Beceriler (Skills)**: [Resmî belgelere](https://code.claude.com/docs/en/skills) göre `SKILL.md` ile tanımlanan prosedürel bilgidir; tetikleyici sözcüklere göre otomatik yüklenir ve aşamalı açıklamayı kullanır. "Bir işin nasıl yapılacağına" ilişkin alan bilgisine uygundur.+- **MCP**: [Resmî belgelerdeki](https://code.claude.com/docs/en/mcp) JSON-RPC protokolüyle dış sistemlere bağlanır; "modelin elini dış dünyaya uzatan" standart arayüzdür.+- **Hooks**: [Resmî belgelere](https://code.claude.com/docs/en/hooks) göre `PreToolUse`, `PostToolUse`, `Stop` ve benzeri yaşam döngüsü olaylarına bağlanan deterministik betiklerdir.+- **Plugin'ler / Subagent'lar**: [Resmî belgelere](https://code.claude.com/docs/en/sub-agents) göre karmaşık görevleri uzmanlaşmış agent'lara ayırır.++Temel tasarım kararı **sorumlulukların ayrılmasıdır**: CLAUDE.md "ne olduğunu", beceriler "nasıl yapılacağını", MCP "nereye bağlanılacağını", hooks ise "ne zaman zorlanacağını" yönetir. Ekipler bu katmanları birbirine karıştırırsa (örneğin MCP'nin yapması gereken işi CLAUDE.md içine yazarsa) derste anlatılan bağlam sızıntısı ortaya çıkar.++## Geri Bildirim ve Doğrulama: Deterministik Kısıtlar + İnsan-Agent İş Bölümü++Onuncu ders, "yalnızca uçtan uca akış çalıştırıldığında gerçek doğrulama yapılmış olur" der. Claude Code bunun için iki kanallı bir mekanizma kullanır:++**1. Permissions sistemi (deterministik kısıtlar).** Claude Code'un permissions yaklaşımı "her şeyi sor" değildir; yedi mod ve ML tabanlı bir sınıflandırıcıdan oluşur. Düşük riskli işlemler serbest bırakılır, yüksek riskli işlemler ise politikaya göre sorulur ya da reddedilir (mimari ayrıntılar için [VILA Lab incelemesine](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf) bakın). Böylece "agent için net sınırlar çizmek" (Ders 7), istemlerle ricada bulunmak yerine runtime'da zorunlu hâle getirilir.++**2. Hooks (tamamlandığını erken ilan etmeyi önleme).** `PostToolUse` hook'u araç çalıştıktan sonra kontrolleri zorunlu olarak çalıştırabilir ve sonuçları yeniden bağlama yazabilir; `Stop` hook'u agent tamamlandığını ilan ettiğinde devreye girer. Böylece "işi yapan ile kontrol eden ayrılır". [Anthropic, harness yazısında](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) agent'ın kendi çalışmasını kendinden emin biçimde övdüğünü ("confidently praised their work") açıkça gözlemlemiştir. Bu nedenle modelin kendi değerlendirmesine güvenmek yerine hooks ile **deterministik** kontroller eklenir.++**3. Subagent'lar (bağlam yalıtımı).** Her subagent'ın konuşma kaydı ayrı bir sidechain dosyasında tutulur ve **üst agent'ın bağlamını şişirmez** (bkz. [VILA Lab incelemesi](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Bu, "görev sınırı" ile "bağlam yalıtımı"nı birleştirir: Görevler ayrılırken bağlam kirlenmesi de yalıtılır.++## Gözlemlenebilirlik ve Session Kalıcılığı++Claude Code'un günlüğü ekleme tabanlı eksiksiz bir kayıttır (history.jsonl). `/compact`, `/clear` ve `/init` gibi açık komutlar sayesinde bağlamın dolmasını pasifçe beklemek yerine bağlam durumunu etkin biçimde yönetebilirsiniz. `/init`, "agent'ı her işten önce başlatma" yaklaşımını (Ders 6) bir komuta dönüştürür. [Resmî belgelere](https://code.claude.com/docs/en/memory) göre kod tabanını otomatik analiz eder ve ilk CLAUDE.md dosyasını (derleme komutları, test talimatları ve mühendislik kurallarıyla birlikte) üretir.++## Ders Çerçevesiyle Eşleştirme++| Alt sistem | Claude Code'un uygulaması | Değerlendirme |+| --- | --- | --- |+| Talimatlar | Kapsam katmanları (kuruluş/kullanıcı/proje/yerel) + otomatik bellek | Katmanlı bellek için örnek uygulama |+| Araçlar | Beceriler + MCP + hooks + subagent'lardan oluşan dört genişletme türü | Sorumluluk ayrımı nettir ve temel güçlü yönüdür |+| Ortam | Proje içi ayarlar + settings.json | Kullanıcının CLAUDE.md içinde yaptığı tanıma dayanır |+| Durum | Ekleme tabanlı session depolama + beş aşamalı compaction + resume/fork | Çok güçlü; uzun görev sürekliliği için referans uygulama |+| Geri bildirim | Permissions sınıflandırıcısı + PostToolUse hook'uyla zorunlu kontrol | "Tamamlandığını erken ilan etmeyi önleme"yi deterministik bir mekanizmaya dönüştürür |++## Örnek Alınabilecek Tasarımlar++1. **Talimatları kapsama göre katmanlandırın**; tek dosyada yığmayın. Dizin düzeyindeki CLAUDE.md, "en yakın noktada yükleme"nin zarif bir uygulamasıdır.+2. **Compaction'ı kademeli bir huni olarak tasarlayın**: Önce kayıpsız, sonra kayıplı yöntemleri kullanın; doğrudan tam metin özetine geçmeyin.+3. **Deterministik kontroller için hooks kullanın**: Tamamlandığını erken ilan etmeyi istemlerle ricada bulunarak değil, runtime zorlamasıyla önleyin.+4. **Subagent bağlamlarını yalıtın**: Görevleri bölerken bağlamı da bölün; alt görevlerin sonuçlarının ana döngüyü kirletmesine izin vermeyin.+5. **Session depolamasını ekleme tabanlı ve yeniden oynatılabilir yapın**: Devir teslimi belleğe değil, depolama katmanının güvencesine dayanır.++## Referanslar (Özgün Metin / Kaynak Kod)++Her iddia, izlenime dayalı aktarımı önlemek için aşağıdaki özgün metne veya kaynak koda kadar izlenebilir:++- **Claude Code 官方文档 · Memory**:每次会话全新上下文、CLAUDE.md 四类作用域、子目录按需加载、auto memory(200 行 / 25KB)、`/init` 生成 CLAUDE.md。<br/>https://code.claude.com/docs/en/memory+- **Claude Code 官方文档 · Skills / MCP / Hooks / Sub-agents**:四类扩展机制的定义与事件(PreToolUse / PostToolUse / Stop)。<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab《Dive into Claude Code》**(源码级拆解报告):五层压缩管线、权限七模式 + ML 分类器、sidechain 子智能体、追加式会话存储 history.jsonl。<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic《Effective harnesses for long-running agents》**:"可靠性来自 harness 而非模型"、agent 会自信地夸赞自己的工作、用钩子做验证等观点出处。<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack 导读**(社区,CLAUDE.md / Skills / MCP / Subagents / Hooks 分层):作为扩展机制职责分离的补充阅读。<br/>https://jsmanifest.com/claude-code-full-stack-guide++İlgili dersler: [Ders 3 · Kod Deposu Neden Tek Gerçeklik Kaynağı Olmalıdır?](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Ders 9 · Agent'lar Neden Zaferi Erken İlan Eder?](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Ders 10 · Uçtan Uca Test Sonuçları Neden Değiştirir?](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/tr/harness-designs/codex/index.md b/docs/tr/harness-designs/codex/index.mdnew file mode 100644index 0000000..2fc7e1b--- /dev/null+++ b/docs/tr/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Codex'in harness tasarımının incelenmesi++OpenAI'ın [Codex](https://openai.com/index/harness-engineering/) ürünü, dört ürün arasında "özgün harness öğretisi"ne en sıkı bağlı olanı olabilir. Alanın adını tanımlayan Harness Engineering yazısı, OpenAI ekibinin Codex ile ürün geliştirirken edindiği deneyimlerin bir özetidir. Dolayısıyla Codex harness tasarımını incelemek, büyük ölçüde bu yazının arkasındaki mühendislik pratiğini incelemek demektir.++Codex felsefesi tek cümlede özetlenebilir: **Gerçekliğin kaynağı depodur (repository as the system of record), AGENTS.md yalnızca bir dizin sayfasıdır; mühendisliğin değeri ortamı tasarlamakta, niyeti ifade etmekte ve geri bildirim döngüleri kurmaktadır.**++## Tek Cümlelik Konumlandırma++OpenAI ekibi Codex kullanarak birkaç hafta içinde, sonunda bir milyon satırı aşan bir ürün teslim etti ve **kodun her satırını Codex yazdı** (özgün metin için [Harness Engineering](https://openai.com/index/harness-engineering/) yazısının "Designing for growth" bölümüne bakın). Bu pratik şu soruyu yanıtladı: Mühendisin rolü "kod yazmaktan" "harness tasarlamaya" dönüştüğünde sistem nasıl düzenlenmelidir? Codex CLI, Rust ile yazılmış açık kaynaklı monolitik bir ikili dosyadır ([github.com/openai/codex](https://github.com/openai/codex)); ancak harness'a asıl katkısı gösterişli genişletme noktalarından çok **kurallar (convention)** ve **bağlam mühendisliği** alanındadır.++## Talimat Alt Sistemi: AGENTS.md Bir Ansiklopedi Değil, Dizin Sayfasıdır++Bu, Codex'in harness teorisine kattığı en etkili tasarım ilkelerinden biridir:++> Tek bir dev talimat dosyası mekanik denetime (kapsam, güncellik durumu, sahiplik, çapraz bağlantılar) uygun değildir ve gerçeklikten sapması kaçınılmazdır. Bu nedenle AGENTS.md dosyasını artık bir ansiklopedi olarak değil, bir **dizin sayfası** olarak görüyoruz. Kod tabanı bilgisi yapılandırılmış belgelerde bulunur; AGENTS.md bunlara yönlendirir.++(Yukarıdaki metin, [Harness Engineering](https://openai.com/index/harness-engineering/) yazısının "AGENTS.md should be a directory page" bölümünün doğrudan aktarımıdır.)++Dördüncü ders "tek bir dev talimat dosyasının başarısız olacağını" söyler; Codex ise doğrudan doğru çözümü verir: AGENTS.md dosyasını yaklaşık 100 satırda tutun (özgün metin yaklaşık 100 satır önerir; sınıra yaklaşınca `docs/` altına bölün), sığmayan içeriği `docs/` dizinine ayırın ve agent'ın gerektiğinde okumasını sağlayın. Bu, "kılavuzu değil haritayı ver" ilkesinin yetkili kaynağıdır.++Buna eşlik eden ilke **uygulamayı mikro düzeyde yönetmek yerine değişmezleri uygulatmaktır** (özgün ifade: "don't micromanage the implementation; focus on invariants"). AGENTS.md yalnızca ihlal edilemez katı kısıtları ve doğrulama komutlarını içerir; uygulamanın ayrıntıları modele bırakılır. Bu, ikinci dersteki "mikro yönetim yerine kısıtlar" yaklaşımına doğrudan karşılık gelir.++## Bağlam Alt Sistemi: Write-Select-Compress-Isolate++Codex bağlam mühendisliği dört stratejiyle özetlenebilir. Bu çerçeve, "context engineering" bağımsız bir disiplin hâline geldikten sonra topluluk tarafından derlenmiş ve Codex'e eşlenmiştir (çerçeve için [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) kaynağına bakın):++- **Write (dışarı yaz)**: Bağlamı pencerenin dışında kalıcılaştırın; sonuçları belgelere, durumu dosyalara yazın, konuşmada bırakmayın. "Gerçekliğin kaynağı depo" ilkesine karşılık gelir.+- **Select (içeri seç)**: Yalnızca gereken token'ları pencereye alın; tüm depoyu içeri doldurmak yerine AGENTS.md ile yönlendirin ve dosyaları gerektiğinde okuyun.+- **Compress**: Gerçekten önemli olanı koruyun. Codex otomatik compaction ve manuel `/compact` sunar; `compact_prompt` özelleştirilebilir (bkz. [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (yalıt)**: Bağlamı farklı sınırlara ayırın. Subagent'larla farklı görevlerin bağlamını yalıtın; böylece bir ön yüz subagent'ı arka ucun veritabanı schema'sını hiç görmez.++Codex ayrıca incelikli bir ortam bağlamı tasarımına sahiptir. [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) üzerine topluluk kaynak kod analizine göre `build_environment_update_item`, her turda tüm sistem bağlamını yeniden yapıştırmak yerine yalnızca ortam değiştiğinde **değişen alanları** (CWD, git dalı, dosya sistemi) çıktı olarak verir. Bu, "bağlamda tekrar eden token barındırmama"nın mühendislik ayrıntısıdır.++## Araçlar ve Sınırlar: worktree Yalıtımı + Subagent'lar++Codex'in iki temel harness mekanizması vardır:++**1. git worktree ile ortam yalıtımı.** [Harness Engineering](https://openai.com/index/harness-engineering/) yazısının "Environment" bölümü, her görevin bağımsız bir git worktree içinde; yerel gözlemlenebilirlik yığınıyla (günlükler, metrikler ve izler) birlikte çalıştırıldığını açıkça belirtir. Böylece her değişiklik bağımsız bir ortamda doğrulanır. Bu, yedinci dersteki "agent'ın her görevi için net sınırlar çizme" ilkesinin fiziksel uygulamasıdır. Sınır, talimatlarla rica edilmez; ortam yalıtımıyla zorunlu kılınır. Burada ortam (environment) alt sistemi katı bir yalıtıma dönüştürülmüştür.++**2. Çekirdek düzeyinde subagent'lar.** Codex'in `spawn_agent` / `wait_agent` araçları çekirdek düzeyindedir: Model açıkça subagent'lar oluşturur, her birine bağımsız session geçmişi ve araç kümesi verir ve sonuçları bekler. Subagent'lar üst düzey AGENTS.md talimatlarını devralır, ancak **kendi bağlamlarında** çalışır. Yapılandırma `.codex/agents/*.toml` altında tutulur ve farklı modeller ile talimatlar belirtilebilir (ayrıntılar için [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) kaynağındaki Sub-agents bölümüne bakın). Bu, "bağlam yalıtımı"nın doğrudan uygulaması ve on ikinci dersteki "devir teslimi" yaklaşımının da bir yansımasıdır: Her subagent, sınırları açıkça belirlenmiş bir iş birimidir.++## Geri Bildirim Alt Sistemi: Doğrulama Komutlarını Kurallara Yazmak++OpenAI pratiğinin en çok vurguladığı noktalardan biri, doğrulama komutlarını AGENTS.md içinde açıkça listelemek ve "doğru yapıldığını nasıl anlarız" sorusunun yanıtını deponun bir parçasına dönüştürmektir. Codex mühendislik akışında testler, CI, belgeler ve gözlemlenebilirlik yapılandırması tamamen Codex tarafından üretilir ve bunların tümü "çalıştırılabilir doğrulama yollarıdır". Güçlü ama güvenilmez bir modelin çözümü, modelin kendiliğinden doğru davranmasını ummak değil, **doğrulama yolunu harness'ın varsayılan bir bileşeni yapmaktır**.++Onay politikaları (approval policies) ve plan modu (plan mode), geri bildirimin diğer yönüdür: Yüksek riskli işlemlerden önce plan çıkarıp onay isteyerek "görev sınırlarını" ve "insanın karar yetkisini" runtime kontrolüne dönüştürür.++## Ders Çerçevesiyle Eşleştirme++| Alt sistem | Codex'in uygulaması | Değerlendirme |+| --- | --- | --- |+| Talimatlar | AGENTS.md dizin sayfası + docs/ dosyalarına ayırma + değişmezleri uygulatma | "Kılavuzu değil haritayı ver" ilkesini tanımlayan ders kitabı niteliğinde uygulama |+| Araçlar | worktree yalıtımı + spawn_agent subagent'ları | Sınırları ortamla katı biçimde yalıtır; çok güçlüdür |+| Ortam | Bağımsız worktree + gözlemlenebilirlik yığını | worktree yalıtımı ayırt edici özelliğidir |+| Durum | Write stratejisi (durumu dosyalara/belgelere yazma) | Yerleşik bellek yerine kurallara dayanır |+| Geri bildirim | Doğrulama komutlarını kurallara ekleme + onay politikaları + plan mode | Geri bildirim yolunu varsayılan hâle getirir; örnek alınmaya değerdir |++Codex ile Claude Code karşılaştırması ilginçtir: Claude Code "ekleme" yaklaşımıyla bellek, permissions ve subagent'ları çekirdeğe yerleştirir; Codex ise "çıkarma" yaklaşımıyla çekirdeği olabildiğince ölçülü tutar ve daha fazla sorumluluğu depo kurallarına ve bağlam mühendisliğine bırakır. Topluluğun sıkça "Codex'in harness felsefesi kodundan daha değerlidir" demesinin nedeni de budur.++## Örnek Alınabilecek Tasarımlar++1. **AGENTS.md dosyasını bir dizin sayfası olarak yazın**: Yaklaşık 100 satırda tutun, docs/ altındaki ayrıntılara yönlendirin ve mekanik olarak denetlenebilir kılın.+2. **Yalnızca değişmezleri yazın, uygulamayı mikro düzeyde yönetmeyin**: Katı kısıtları ve doğrulama komutlarını belirtin, gerisini modele bırakın.+3. **Ortam yalıtımı için worktree kullanın**: Görev sınırlarını talimatlarla rica etmek yerine ortamla zorunlu kılın.+4. **Ortam bağlamında yalnızca farkları aktarın**: Her turda yalnızca değişen alanları çıktılayın; sistem bağlamının tamamını tekrar tekrar yapıştırmayın.+5. **Bağlam yalıtımı için subagent'lar kullanın**: Görevleri bölerken bağlamı da bölün; alt görevlerin ana döngüyü kirletmesine izin vermeyin.++## Referanslar (Özgün Metin / Kaynak Kod)++Her iddia, izlenime dayalı aktarımı önlemek için aşağıdaki özgün metne veya kaynak koda kadar izlenebilir:++- **OpenAI《Harness Engineering》**:AGENTS.md 目录页与约 100 行建议、executive invariants / don't micromanage、worktree 隔离 + 可观测性栈、验证命令入规范、上百万行产品案例、审批策略与 plan mode。本篇所有核心论断的主要出处。<br/>https://openai.com/index/harness-engineering/+- **OpenAI 官方《AGENTS.md》规范**(AGENTS.md 作为跨工具约定的标准):<br/>https://openai.com/index/agents-md/+- **Codex CLI 开源仓库**(Rust 实现的单体二进制):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI**(社区):Write-Select-Compress-Isolate 框架、`/compact` 与 `compact_prompt`、`spawn_agent` / `wait_agent` 子智能体与 `.codex/agents/*.toml` 配置。<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals**(社区源码分析):`build_environment_update_item` 增量环境上下文等实现细节。<br/>https://github.com/AlexKenbo/codex-harness-internals++İlgili dersler: [Ders 3 · Kod Deposu Neden Tek Gerçeklik Kaynağı Olmalıdır?](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Ders 4 · Talimatları Farklı Dosyalara Ayırmak](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Ders 7 · Agent'ın Her Görevi İçin Net Sınırlar Çizmek](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/tr/harness-designs/deepseek/index.md b/docs/tr/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..7ca4622--- /dev/null+++ b/docs/tr/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# DeepSeek Harness tasarımının incelenmesi++[DeepSeek Harness](https://deepseek.com/harness) (`dsh` komutu, `deepseek-ai/deepseek-harness` deposu), Ağustos 2026'da Developer Preview olarak yayımlandı. Resmî tanımı son derece doğrudandır: **Agent = Model + Environment + Tools + State** — model, ortam, araçlar ve durumdan oluşan dörtlü.++İlk üç ürünün incelemesi "harness nasıl tasarlanmalı" diye soruyorsa DeepSeek Harness daha radikal bir soru sorar: **harness belirli bir modelden ayrılıp bağımsız bir runtime olabilir mi?** Yanıtı evettir ve bu yaklaşımı son noktasına kadar götürür. [Mimari belgesindeki](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) özgün ifade şöyledir: *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* (model bağdaştırıcısı, araç kayıt defteri, session günlüğü ve hatta agent döngüsünün kendisi dâhil olmak üzere ürünün her parçası bir plugin'dir).++Bu yazıda üç noktaya odaklanıyoruz: plugin tabanlı çekirdek, yetenek eklemi (capability seam), olay hattı ve en güçlü mühendislik kısıtı olan "Model-visible means logged".++## Tek Cümlelik Konumlandırma++Geleneksel bir coding agent'ın yapısı "LLM + sabit agent döngüsü + sabit araç kümesi"dir. DeepSeek Harness'ın yapısı ise "model + plugin çekirdeği (Cordis)" biçimindedir. Çekirdek yalnızca plugin'lerin yüklenmesi, kaldırılması, bağımlılıkları ve olay mekanizmasından sorumludur; **agent'ın belirli yeteneklerinden hiçbirine sahip değildir**. [Mimari belgesindeki](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) özgün ifadeler şöyledir: "There is no privileged core to patch" (yama yapılması gereken ayrıcalıklı bir çekirdek yoktur) ve "you extend dsh by mounting a plugin beside the others" (çekirdeği değiştirmeden diğerlerinin yanına bir plugin bağlayarak dsh'yi genişletirsiniz). Bu, agent döngüsünün kendisinin bile dokunulmaz olmadığı anlamına gelir. DeepSeek modelini kullanıp Claude Code'un subagent'larını bağlayabilir; uzaktan sandbox, özel bellek, özel döngü ve özel UI ekleyerek yepyeni bir agent oluşturabilirsiniz.++Bu, dersteki "model ağırlıklarının dışındaki her şey harness'tır" ifadesinin en köklü uygulamasıdır: harness bağımsızsa onu bağımsız bir işletim sistemine dönüştürün.++## Mimari Çekirdek 1: Yetenek Eklemi (Capability Seam)++DeepSeek Harness, "yeteneği" Service ile temsil eder ve neredeyse her yeteneği üç katmana ayırır:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Örneğin dosya sisteminde `FS Service` altında Local FS, E2B FS ve Remote FS gibi birden fazla Provider bulunur; üst katmana ise tek biçimli file tools sunulur. Shell, Subprocess, Sandbox, Web, LLM ve SubAgent aynı yapıyı kullanır. Bu üç katmanlı yapı bizim özetimiz değildir. [Mimari belgesinin Capability seams bölümündeki](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) özgün ifade şöyledir: *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* (yetenek eklemi, üç rolü olan değiştirilebilir bir yetenektir: arayüzü bildiren Service Definition, onu uygulayan Service Provider ve onu kullanan, genellikle modele dönük bir araç olan Consumer).++Bu, harness mühendisliğinde uzun süredir var olan bir sorunu çözer: **Agent "belirli araçlara" mı, yoksa "yetenek arayüzlerine" mi bağımlı olmalıdır?** DeepSeek Harness ikinci seçeneği tercih eder. Ders açısından bu, "araç alt sisteminin" bir arayüz olarak standartlaştırılması demektir: Provider değiştirildiğinde ortam bütünüyle değişir, ancak modele sunulan araç yüzeyi aynı kalır.++## Mimari Çekirdek 2: Olay Hattı (Event Pipeline)++DeepSeek Harness'ın iç yapısı basit bir "LLM → araç → LLM" dizisi değildir. Her aşaması plugin'lerin dinleyebileceği bir olay noktası olan bir olay hattıdır:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(Yukarıdaki hat, [mimari belgesinin Turn flow bölümünün](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) aktarımıdır: `turn/*`, `step/*`, `user/message`, `assistant/*` ve `tool/*` kalıcı session olaylarıdır; `agent/pre-step`, `agent/request`, `llm/stream` ve `tools/*` ise plugin'lerin dinleyebildiği genişletme noktalarıdır.)++Bu tasarımın en büyük yararı şudur: **Pek çok özellik için agent döngüsünün kendisini değiştirmek gerekmez.** Araç çalıştırılmadan önce güvenlik denetimi mi yapmak istiyorsunuz? `tools/pre-execute` olayını dinleyin. Bellek mi eklemek istiyorsunuz? `agent/pre-step` aşamasında enjekte edin. Davranışları mı kaydetmek istiyorsunuz? Session olaylarına abone olun. Model isteğini mi değiştirmek istiyorsunuz? `agent/request` hook'unı kullanın. Muhakemenin sürüp sürmeyeceğine mi karar vermek istiyorsunuz? `agent/turn-stopping` olayını dinleyin.++On birinci dersteki "agent'ın çalışma sürecini gözlemlenebilir kılma" yaklaşımıyla karşılaştırıldığında DeepSeek Harness daha da ileri gider: Yalnızca "günlük eklemek" yerine **döngünün her adımını bir olay noktasına dönüştürür**. Böylece gözlemlenebilirlik, permissions, bellek ve politikalar döngüye sabit kodlanmak yerine dinleyici olarak bağlanır.++## Mimari Çekirdek 3: Session Event Log ve "Model-visible means logged"++DeepSeek Harness, **append-only Session Event Log (yalnızca eklenen session olay günlüğü)** kullanır ve son derece güçlü bir mühendislik kısıtı tanımlar. [Mimari belgesinin Session log bölümündeki](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) özgün ifade şöyledir:++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Modelin görebildiği her şey günlüğe kaydedilmelidir. Bir model isteğine ulaşan her şey günlükten yeniden oluşturulabilmeli ve bir runtime değişmezi bunu zorunlu kılmalıdır.)++Başka bir deyişle gözlemlenebilirlik, sonradan eklenen günlüklerden ibaret değil, harness'ın birincil kısıtıdır: Model bağlamına giren her şey varsayılan olarak kaydedilmelidir. Bu, kapanış dersindeki "gözlemlenebilirlik harness'ın içinde yer alır" yaklaşımıyla doğrudan örtüşür ve "append-only" depolama tasarımını bir ilkeye dönüştürür: Günlüklere yalnızca ekleme yapılır, mevcut kayıtların üzerine yazılmaz ve session durumu yeniden oynatılabilir.++## Ders Çerçevesiyle Eşleştirme++| Alt sistem | DeepSeek Harness'ın uygulaması | Değerlendirme |+| --- | --- | --- |+| Talimatlar | Plugin tabanlıdır; kurallar/beceriler plugin olarak enjekte edilir | Son derece özgürdür, ancak yerleşik bir "CLAUDE.md" kuralı yoktur |+| Araçlar | Service Definition → Provider → Consumer yetenek eklemi | Araç alt sistemini standartlaştırmanın en uç örneği |+| Ortam | Sandbox/FS/Shell Provider'larının tamamı değiştirilebilir (uzak E2B dâhil) | Ortam bütünüyle takılıp çıkarılabilir |+| Durum | append-only Session Event Log + Model-visible means logged | Gözlemlenebilirlik birincil kısıttır |+| Geri bildirim | tools/pre-execute üzerindeki permission / guard / policy / hook | Geri bildirim mekanizması olaylara dönüştürülmüştür |++DeepSeek Harness ile diğer üç ürün arasındaki temel fark şudur: Pi, Claude Code ve Codex, "belirli bir agent'ın" içindeki harness'ı iyileştirir; DeepSeek Harness ise harness'ı **modelden bağımsız bir işletim sistemi** olarak tanımlar ve agent'ın kendisini bu OS üzerinde değiştirilebilir bir uygulama olarak görür. Bunun bedeli de açıktır: Yüksek özgürlük, yüksek yapılandırma maliyeti getirir. Bu, "işletim sistemi olarak harness" tasarımının doğal diğer yüzüdür (Developer Preview aşamasında da "erken deneyim, mekanizmalar hâlâ gelişiyor" yaklaşımıyla konumlandırılmıştır).++## Örnek Alınabilecek Tasarımlar++1. **Döngünün her adımını bir olay noktasına dönüştürün**: Permissions, bellek, politikalar ve günlükler döngüye sabit kodlanmak yerine dinleyici olarak bağlansın.+2. **Yetenek eklemlerini standartlaştırın**: "Belirli araçlara" değil, "yetenek arayüzlerine" bağımlı olun; böylece modele sunulan araç yüzeyi değişmeden ortam bütünüyle değiştirilebilir.+3. **Model-visible means logged**: Modelin görebildiği her şey kaydedilmelidir; gözlemlenebilirliği "ek avantaj" olmaktan çıkarıp "birincil kısıt" hâline getirin.+4. **append-only session günlüğü**: Durum yeniden oynatılabilir ve devir teslimi güvenilir olur; bu, "her session'dan sonra temiz bir durum bırakma"nın mühendislik güvencesidir.++## Referanslar (Özgün Metin / Kaynak Kod)++Her iddia, izlenime dayalı aktarımı önlemek için aşağıdaki özgün metne veya kaynak koda kadar izlenebilir:++- **DeepSeek Harness 官网**:产品定义 "Agent = Model + Environment + Tools + State"、Developer Preview 定位与 `dsh` 命令。<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness 仓库**(命令 `dsh`,MIT 协议):<br/>https://github.com/deepseek-ai/deepseek-harness+- **架构文档 architecture.md**:本篇最核心的出处——"Every part of the product is a plugin"、"There is no privileged core to patch"、Turn flow 事件流水线、Capability seams 三层角色、"Model-visible means logged" 与运行时不变量、append-only Session Event Log、fs/tools/telemetry 等能力接缝与 `ctx.*` 子系统。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **架构文档 · 配套子文档**:Cordis 内核简介(plugins contribute services, typed events, reversible effects)、能力接缝细节、Session 子系统。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++İlgili dersler: [Ders 11 · Gözlemlenebilirlik Neden Harness'ın İçinde Yer Almalıdır?](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Ders 12 · Her Session Neden Temiz Bir Durum Bırakmalıdır?](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Ders 2 · Harness Tam Olarak Nedir?](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/tr/harness-designs/index.md b/docs/tr/harness-designs/index.mdnew file mode 100644index 0000000..154d739--- /dev/null+++ b/docs/tr/harness-designs/index.md@@ -0,0 +1,29 @@+# Öncü Harness Tasarımlarının İncelenmesi++Bu bölüm, ders notlarında ele alınan harness teorisini günümüzün en ileri gerçek ürünleriyle tek tek karşılaştırır. Her üründe yalnızca tek bir şeye odaklanıyoruz: **harness nasıl tasarlanmış** — yani modelin çevresindeki mühendislik altyapısına: talimatlar, araçlar, ortam, durum ve geri bildirimden oluşan beş alt sisteme; ayrıca bağlam sürekliliği, başlatma, doğrulama, gözlemlenebilirlik, devir ve döngü gibi temel mekanizmalara.++Modelin muhakeme gücünün ne kadar yüksek olduğunu, belirli bir benchmark sonucunu ya da genel olarak "bu agent ne yapabilir" sorusunu özellikle ele almıyoruz. Bunlar model ve ürün katmanlarının konularıdır. Burada yalnızca harness'ı, yani model ağırlıklarının dışındaki her şeyi inceliyoruz.++## Neden İncelemeye Değer++Ders notlarının ilk bölümünde belirtildiği gibi, güçlü bir model güvenilir yürütme anlamına gelmez. Aynı model farklı harness'larda kullanıldığında performansı bir büyüklük mertebesi kadar değişebilir. Ancak ders notları "nasıl yapılmalı" sorusunu yanıtlarken bu ürünler, "önde gelen ekipler bunu gerçekte nasıl yapıyor" sorusunu yanıtlar.++Her ürün bağımsız bir tasarım kararları bütünüdür. Bunları yan yana koyduğunuzda aynı temel mekanizmaların farklı ekipler tarafından bütünüyle farklı biçimlerde hayata geçirildiğini görürsünüz:++- **Pi**, harness'ı son derece yalın bir çekirdek + programlanabilir Extensions olarak kurar ve "minimum sistem istemi + gerektiğinde yükleme" yaklaşımıyla bağlam mühendisliği yapar.+- **Claude Code**, harness'ı eksiksiz bir çalışma ortamı olarak kurar: katmanlı bellek, beş aşamalı compaction, permissions, hooks ve subagent'lar.+- **Codex**, harness felsefesini en uç noktaya taşır: gerçekliğin kaynağı depodur, AGENTS.md yalnızca bir dizin sayfasıdır ve ortam worktree ile yalıtılır.+- **DeepSeek Harness**, harness'ın kendisini modelden bağımsız bir runtime olarak tanımlar: Everything is a Plugin.++## Yazı Listesi++- [Pi harness tasarımının incelenmesi](./pi/): Yalın çekirdek + programlanabilir Extensions; bağlam mühendisliğini sistem isteminin dışına taşır.+- [Claude Code harness tasarımının incelenmesi](./claude-code/): Katmanlı bellek, beş aşamalı compaction, permissions ve hooks ile eksiksiz bir agent çalışma ortamı.+- [Codex harness tasarımının incelenmesi](./codex/): Gerçekliğin kaynağı depo, AGENTS.md bir dizin sayfası; ortam yalıtımı ve geri bildirim döngüsü.+- [DeepSeek Harness tasarımının incelenmesi](./deepseek/): Everything is a Plugin; agent döngüsünün kendisini değiştirilebilir bir plugin'e dönüştürür.++## Nasıl Okunmalı++Önce beş alt sistem çerçevesini oluşturmak için ders notlarının ilk bölümlerini (özellikle [Ders 2: Harness Tam Olarak Nedir?](../lectures/lecture-02-what-a-harness-actually-is/)) okumanızı, ardından gerçek ürünlerin bu mekanizmaları nasıl hayata geçirdiğini görmek için buraya dönmenizi öneririz.++Her yazının sonunda, ürün tasarımını hızla ders kavramlarına çevirmenize ve doğrudan kendi projenize uyarlamanıza yardımcı olan "Ders Çerçevesiyle Eşleştirme" ve "Örnek Alınabilecek Tasarımlar" bölümleri bulunur.diff --git a/docs/tr/harness-designs/pi/index.md b/docs/tr/harness-designs/pi/index.mdnew file mode 100644index 0000000..9db8f45--- /dev/null+++ b/docs/tr/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Pi'nin harness tasarımının incelenmesi++[Pi](https://pi.dev/) (`@earendil-works/pi-coding-agent` npm paketi), kendisini "minimal agent harness", yani son derece yalın bir agent harness olarak tanımlar. Bu ifadeyi dikkatle okumaya değer: kendisini "en güçlü coding agent" ya da "en kullanışlı yapay zekâ programlama aracı" olarak değil, kesin biçimde bir **harness** olarak konumlandırır.++Bu yazıda Pi'yi dersin beş alt sistem çerçevesiyle (talimatlar, araçlar, ortam, durum ve geri bildirim) inceliyor; tasarım felsefesinin Claude Code ve Codex'ten temelde nasıl ayrıldığını ele alıyoruz. Yanıtı baştan verelim: **Pi'nin felsefesi "çekirdeği en aza indirmek + Extensions'ı programlanabilir kılmak"tır. Bağlam mühendisliğini sistem isteminin dışına taşır; harness'a Pi'nin sizin yerinize karar vermesi yerine kullanıcıların, hatta Pi'nin kendisinin müdahale edip harness'ı değiştirmesini sağlar.**++## Tek Cümlelik Konumlandırma++Pi yalın bir çekirdektir: Resmî konumlandırması çekirdeği bilinçli olarak küçük tutar ve karar yetkisini size geri verir. [pi.dev ana sayfasındaki](https://pi.dev/) özgün ifade şöyledir: "Ask Pi to build what you want, or install a package that does it your way"; harness'ı dört özelleştirilebilir katmana ayırır:++- **Extensions**: Pi yaşam döngüsü olaylarına bağlanan TypeScript hooks; runtime düzeyindeki programlanabilir yüzey.+- **Beceriler (Skills)**: Talimat ve araçlar içeren, gerektiğinde yüklenen yetenek paketleri; aşamalı açıklama (progressive disclosure).+- **İstem şablonları (Prompt templates)**: `/name` girildiğinde genişleyen, yeniden kullanılabilir Markdown istemleri.+- **Temalar (Themes)**: TUI görünümü.++Bu katmanlama yaklaşımının kendisi bir harness tasarımıdır: **"Model neyi, ne zaman görebilir" sorusunun yanıtını çekirdeğe sabitlemek yerine bütünüyle kurallara ve Extensions'a bırakır.**++## Temel Döngü++Pi, tüm coding agent'lar gibi özünde "muhakeme → araç çalıştırma → gözlem → yeniden muhakeme" biçiminde bir while döngüsüdür. Dikkate değer olan döngünün kendisi değil, Pi'nin döngünün dış katmanını ele alış biçimidir: Bağlam yönetimini döngü içindeki "compaction" işinden döngü dışındaki "kontrol" alanına genişletir.++Pi runtime'ı dışarıya programlanabilir bir arayüz sunar. [Kaynak kod README dosyasındaki Programmatic Usage](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) bölümünde etkileşimli TUI'nin yanı sıra betikleştirilebilir yazdırma/JSON modu, RPC protokolü ve SDK ile gömme desteği bulunur. Böylece aynı harness hem insanlar tarafından adım adım hem de CI/CD ya da başka programlar tarafından otomatik olarak çalıştırılabilir. Bu, on üçüncü dersteki "döngü mühendisliği" kapsamında "elle yürütmeden otomatik döngüye geçiş"in ön koşuluna karşılık gelir: Yalnızca insan etkileşimiyle çalışabilen bir harness hiçbir zaman otomatik döngüye giremez.++## Talimat Alt Sistemi: AGENTS.md ve SYSTEM.md++Pi, "talimatları" ölçülü ama net bir hiyerarşiyle ele alır:++- **AGENTS.md**: [Kaynak kod README dosyasındaki Project Context Files](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) bölümü yükleme sırasını açıkça belirtir: genel `~/.pi/agent/AGENTS.md` → üst dizinlerde kademeli gezinme → geçerli dizindeki `./AGENTS.md` (CLAUDE.md ile de uyumludur). Bu, "gerçekliğin kaynağı depodur" ilkesinin uygulanmasıdır: Talimatlar sohbet kutusundaki hatırlatmalar değil, dosyalardır.+- **SYSTEM.md**: [Pi'nin resmî belgelerine](https://pi.dev/docs/usage/project-context) göre varsayılan sistem istemi proje bazında değiştirilebilir (replace) veya genişletilebilir (append). Bu, Pi'nin "sistem istemine" müdahale etmeniz için sunduğu tek resmî giriş noktası ve aynı zamanda "ortamın kendini tanımlama" katmanıdır.++Pi, sistem isteminin kendisinin **son derece yalın** olduğunu özellikle vurgular. Bunun arkasında açık bir tercih vardır: Çekirdeği uzun "eğer... o zaman..." kurallarıyla doldurmak yerine genişletme noktaları bırakır ve kuralların yalnızca gerektiğinde beceri ve Extensions biçiminde ortaya çıkmasını sağlar. Bu yaklaşım dördüncü dersteki "tek bir dev talimat dosyası neden başarısız olur" sorusuyla doğrudan örtüşür. Pi, "yalın çekirdek + dosyalara ayırma + gerektiğinde yükleme" sayesinde dev talimat dosyası sorunundan doğal olarak kaçınır.++## Durum ve Bağlam: Pi'nin En İnce Ayrıntısına Kadar Ayırdığı Alan++Pi'nin bağlam mühendisliği özellikle incelenmeye değer; çünkü dersteki "bağlam sürekliliği" ve "bağlam bozulmasını önleme" kavramlarını somut mekanizmalara dönüştürür:++**1. Compaction programlanabilir.** Bağlam sınırına yaklaşırken eski mesajlar otomatik olarak özetlenir. [Pi'nin resmî belgeleri](https://pi.dev/docs/usage/sessions), compaction stratejisinin kendisinin **özelleştirilebilir** olduğunu belirtir: Extensions ile konu tabanlı compaction, kod farkındalığına sahip özetleme, hatta özetleme için farklı bir model kullanabilirsiniz. Kaynak kod README dosyasında varsayılan mekanizmanın ayrıntıları da görülebilir: Otomatik compaction iki durumda tetiklenir (bağlam taşmasından kurtarma / koruma eşiğini aşma), bölme noktası yakın zamandaki yaklaşık 20 bin token'ı korur ve önceki mesajlar bir "context handoff" hâlinde özetlenerek kademeli biçimde zincirleme compaction yapılır. Başka bir deyişle Pi, "nasıl compaction yapılacağını" değiştirilemez bir sabit değil, harness'ın bir parçası olarak görür.++**2. Dinamik bağlam (Dynamic context).** [Pi'nin resmî belgelerine](https://pi.dev/docs/usage/extensions) göre Extensions her muhakeme turundan önce mesaj ekleyebilir, mesaj geçmişini filtreleyebilir, RAG uygulayabilir ve uzun vadeli bellek oluşturabilir. Bu, "bağlam dolunca compaction" yaklaşımından bir adım öteye gider: Bilgiler bağlam penceresine girmeden önce neyin alınacağına ve neyin alınmayacağına karar vermenizi sağlar. Dersteki "agent'ın çalışma sürecini gözlemlenebilir ve hata ayıklanabilir kılma" ile "bağlam sürekliliğini koruma" hedefleri açısından Pi, bu iki işi Extension katmanına indirger.++**3. Session ağacı (Session tree).** [pi.dev ana sayfası](https://pi.dev/) açıkça "sessions are stored as trees" der: `/tree` ile geçmişteki herhangi bir düğüme dönüp devam edilebilir ve tüm dallar aynı dosyada saklanır. Bu, derste tekrar tekrar vurgulanan "session'lar arası bağlam kopukluğu" sorununu yalnızca özetlerle birbirine bağlamak yerine yapılandırılmış geçmişi yeniden oynatarak çözer. Dallar HTML olarak dışa aktarılabilir ya da gist olarak yüklenip paylaşılabilir; böylece gözlemlenebilirlik de sağlanır.++## Araç Alt Sistemi: Skills ve Extensions++Pi'nin "araçları" iki katmandan oluşur:++- **Beceriler (Skills)**: [Kaynak kod README dosyasındaki Skills bölümü](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) bunları açıkça "self-contained capability packages that the agent loads on-demand" olarak tanımlar; yani Agent Skills standardına uyan, talimat ve araçları içeren, gerektiğinde yüklenen yetenek paketleridir. Aşamalı açıklama sayesinde beceri ayrıntıları yalnızca tetiklendiğinde bağlama girer ve **istem önbelleğini şişirmez (prompt cache)**. Bu, maliyet açısından bir harness tasarımıdır: Bağlamdaki her ek token için her muhakeme turunda ödeme yapılır. Becerileri gerektiğinde yüklemek, "kılavuzu değil haritayı ver" ilkesinin başka bir ifadesidir.+- **Extensions**: Yerleşik yaşam döngüsü olaylarına bağlanan TypeScript hooks'tur. [Kaynak kod README dosyasındaki Hooks bölümü](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) dört resmî kullanım örneği verir: tehlikeli komutları durdurmak (permissions kapısı), görev değişiminde kod durumunun checkpoint'ini almak, yolları korumak (`.env` gibi dosyalara yazmayı engellemek), araç çıktısını modele vermeden önce değiştirmek ve dışarıdan (dosya izleme/Webhook/CI) mesaj ekleyerek agent'ı uyandırmak. Bu hook API'leri `@mariozechner/pi-coding-agent/hooks` paketinden de dışa aktarılır. Topluluk harness'ı olan [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) ise bu hook yüzeyini skill-router, session-summary, extract-patterns ve telemetry gibi hazır Extensions ile daha da paketler.++Extensions Pi'nin en önemli tasarım kararıdır: **Kullanıcıya yalnızca birkaç anahtar sunmak yerine runtime'daki olay yüzeyinin tamamını açar.** Bellek mi eklemek istiyorsunuz? `agent/pre-step` aşamasında enjekte edin. Davranışları mı kaydetmek istiyorsunuz? Session olaylarına abone olun. Model isteğini mi değiştirmek istiyorsunuz? `agent/request` hook'unu kullanın. Pi'nin kendi harness'ını değiştirmesini bile sağlayabilirsiniz; bu, herhangi bir "yapılandırma seçeneğinden" çok daha fazla "programlanabilir harness" tanımına yaklaşır.++## Geri Bildirim ve Doğrulama: "Öğrenmeyi" de harness'a Dönüştürmek++Pi yerleşik olarak zorunlu test kapıları sunmaz (doğrulama komutlarını AGENTS.md içinde kullanıcı yazmalıdır). Ancak topluluk harness'ı [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness), Extensions ile "geri bildirim döngüsünü" yapılandırır; resmî README dosyasının Hooks bölümü de benzer mekanizmaların temelini sunar:++- **session-summary** (pi-agent-harness Extension'ı): Sürekli güncellenen `PROGRESS.md` kayıtlarını tutar; bu, dersteki durum alt sistemi ve uzun görevlerde ilerleme takibidir.+- **extract-patterns** (pi-agent-harness Extension'ı): Session'lardan ders çıkarma adaylarını toplar ve `LESSONS.md` dosyasına işler; "her session sona ermeden önce iyi bir devir teslimi yapmayı" bir mutabakattan mekanizmaya dönüştürür.+- **telemetry** (pi-agent-harness Extension'ı): Token kullanımını, maliyeti vb. kaydeder; yani gözlemlenebilirlik sağlar.++Aynı topluluk deposu bu modeli daha da ileri götürür: `VISION.md` (hedef), `PROGRESS.md` (ilerleme), `LESSONS.md` (öğrenilen dersler) ve `STANDARDS.md` (standartlar) dosyalarının tümü Markdown biçimindedir ve session'lar arasında kalıcıdır. Bu, dersin önerdiği "gerçekliğin kaynağı depo + ilerleme dosyası + devir mekanizması" düzeniyle tamamen aynıdır; yalnızca Pi'nin Extension mekanizmasıyla kullanıma hazır bir katmana dönüştürülmüştür.++## Ders Çerçevesiyle Eşleştirme++Pi'yi dersin beş alt sistemine göre değerlendirelim (öznel bir karşılaştırmadır):++| Alt sistem | Pi'nin uygulaması | Değerlendirme |+| --- | --- | --- |+| Talimatlar | AGENTS.md hiyerarşik yükleme + SYSTEM.md | Hiyerarşi nettir, ancak kuralları kullanıcı yazmalıdır |+| Araçlar | Gerektiğinde yüklenen Skills + tüm yaşam döngüsünü kapsayan Extension hooks | Çok güçlü; araç sistemini programlanabilir bir yüzeye dönüştürür |+| Ortam | SYSTEM.md ortamın kendini tanımlamasını sağlar; runtime ortamı kullanıcı tarafından AGENTS.md içinde bildirilir | Mekanizma açıktır, ancak yeniden üretilebilirlik kullanıcının beyanına bağlıdır |+| Durum | Session ağacı + özelleştirilebilir compaction + PROGRESS.md | Çok güçlü; session'lar arası süreklilik ve kurtarılabilirlik temel odağıdır |+| Geri bildirim | Doğrulama komutlarını kullanıcı tanımlar; session-summary / extract-patterns bunları mekanizmaya bağlar | Mekanizma sağlanır, içerik kullanıcıya bağlıdır |++Pi'nin tercihi Claude Code / Codex ile belirgin bir karşıtlık oluşturur: Claude Code "bellek, permissions ve subagent'ları" yerleşik çekirdeğe koyarak kullanıma hazır sunar; Codex "depo kurallarını ve ortam yalıtımını" varsayılan hâle getirir. Pi ise **sizin yerinize hiçbir şeye karar vermemeyi** seçer ve karar yetkisini Extension noktalarına dönüştürür. Bunun bedeli, ya kendi Extensions'ınızı yazmanız ya da başkalarının paketlerini kurmanızdır.++## Örnek Alınabilecek Tasarımlar++1. **Compaction stratejisini takılabilir hâle getirin.** harness'ınızdaki "bağlamda nasıl compaction yapılır" sorusunun yanıtı sabit kodlanmış bir parametre değil, değiştirilebilir bir strateji arayüzü olmalıdır.+2. **Katı özetler yerine session ağacı kullanın.** Session'lar arası kurtarma her zaman "önceki turun özeti"ne dayanmak zorunda değildir; yapılandırılmış geçmişi yeniden oynatmak çoğu zaman daha güvenilir bir durum alt sistemidir.+3. **İstem önbelleğiyle uyumlu olun.** Becerileri gerektiğinde yükleyin ve tüm kuralları tek seferde sistem istemine doldurmayın. Bu hem bağlam hem de maliyet mühendisliğidir.+4. **Agent'ın kendi harness'ını değiştirebilmesini sağlayın.** harness'ın Extension yüzeyi yeterince açıksa "agent davranışını iyileştirme" işi agent tarafından yarı otomatik olarak yapılabilir.++## Referanslar (Özgün Metin / Kaynak Kod)++Her iddia, izlenime dayalı aktarımı önlemek için aşağıdaki özgün metne veya kaynak koda kadar izlenebilir:++- **pi.dev 官网**:定位原话 "Ask Pi to build what you want, or install a package that does it your way"、四层可定制物、会话树("sessions are stored as trees",`/tree`、单文件保存、导出 HTML / 分享 gist)。<br/>https://pi.dev/+- **pi.dev 官方文档 · Sessions**:压缩可插拔(topic-based / code-aware / 换摘要模型)、自动压缩与动态上下文注入的机制描述。<br/>https://pi.dev/docs/usage/sessions+- **pi.dev 官方文档 · Extensions**:扩展可在每轮推理前注入消息、过滤历史、做 RAG、构建长期记忆。<br/>https://pi.dev/docs/usage/extensions+- **pi.dev 官方文档 · Project Context**:SYSTEM.md 的 replace / append 语义。<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent 源码 README**(badlogic/pi-mono):AGENTS.md 三级加载顺序(全局 → 父目录 → 当前目录)、`/compact` 与自动压缩的触发条件与 2 万 token 切割点、Skills 按需加载与 Agent Skills 标准、Hooks 生命周期与四个官方示例用途、Programmatic Usage(JSON / RPC / SDK)。<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness 社区仓库**:skill-router / session-summary / extract-patterns / telemetry 扩展,VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md 文件体系。<br/>https://github.com/LabidySabidy/pi-agent-harness++İlgili dersler: [Ders 2 · Harness Tam Olarak Nedir?](../lectures/lecture-02-what-a-harness-actually-is/) | [Ders 5 · Uzun Süren Görevler Neden Bağlam Sürekliliğini Kaybeder?](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Ders 13 · Elle Yürütmeden Otomatik Döngüye](../lectures/lecture-13-loop-engineering/)diff --git a/docs/tr/index.md b/docs/tr/index.mdindex dd1cade..b6f5d53 100644--- a/docs/tr/index.md+++ b/docs/tr/index.md@@ -25,6 +25,10 @@ Başlamak için öğrenme yolunuzu seçin. Kurs üç bölümden oluşur: teorik<h3>Kaynak Kütüphanesi</h3><p>Kendi depolarınızda kullanabileceğiniz hazır şablonlar (AGENTS.md, feature_list.json).</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Öncü Harness Tasarımlarının İncelenmesi</h3>+ <p>Pi, Claude Code, Codex ve DeepSeek'in gerçek harness tasarımlarını kursun çerçevesiyle çözümleyin.</p>+ </a></div>## Harness'ın temel mekanizmasıdiff --git a/docs/uk/harness-designs/claude-code/index.md b/docs/uk/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..1cd9e76--- /dev/null+++ b/docs/uk/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Розбір дизайну harness у Claude Code++У статті «[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)» Anthropic прямо стверджує: джерелом надійності є harness, а не модель; agent потребує обмежень «поза моделлю». Claude Code — це втілений у продукті зразок такого підходу, і сама Anthropic прямо зараховує його до категорії **agentic harness**. Це не маркетингове формулювання: Claude Code, імовірно, є найдетальніше публічно дослідженим harness на сьогодні. Його вихідний код відкритий, звіти спільноти докладні, а майже всі ключові механізми з лекцій курсу — багаторівневу пам’ять, стиснення контексту, дозволи, hooks, subagent і збереження сесій — реалізовано як повноцінні продуктові функції.++У цій статті ми розберемо Claude Code за допомогою фреймворку п’яти підсистем курсу, зосередившись на тому, як він утілює такі засадничі поняття harness, як «керування контекстом», «запобігання передчасному оголошенню про завершення» та «детерміновані обмеження».++## Позиціонування одним реченням++В основі Claude Code лежить простий цикл while: викликати модель, виконати інструмент, спостерігати результат і знову викликати модель. Але **переважна частина коду міститься не в цьому циклі, а в системах навколо нього** — системі дозволів, конвеєрі стиснення контексту, механізмах розширення, оркестрації subagent і сховищі сесій. У цьому й полягає сутність harness: цикл — лише каркас, а надійність визначає все, що побудовано навколо нього.++## Підсистема інструкцій: багаторівнева система пам’яті++Система пам’яті Claude Code — його найбезпосередніший внесок у теорію harness, що відповідає лекціям курсу про «репозиторій як джерело правди» та «безперервність контексту між сесіями». В [офіційній документації «How Claude remembers your project»](https://code.claude.com/docs/en/memory) прямо сказано: кожна сесія починається з нового контекстного вікна, а знання між сесіями переносять два механізми — файли CLAUDE.md (інструкції, написані вами) і auto memory (нотатки, написані самим Claude).++За областю дії офіційна документація поділяє файли CLAUDE.md на чотири типи (від найширшої до найвужчої області завантаження):++- **Рівень політик організації**: централізовано керується IT/DevOps (наприклад, `/etc/claude-code/CLAUDE.md`) і містить корпоративні правила.+- **Рівень користувача `~/.claude/CLAUDE.md`**: особисті вподобання та правила для всіх проєктів.+- **Рівень проєкту `./CLAUDE.md` або `./.claude/CLAUDE.md`**: джерело правди проєкту — структура, технологічний стек і команди перевірки; поширюється разом із репозиторієм.+- **Локальний рівень `./CLAUDE.local.md`**: особисті вподобання в межах проєкту; зазвичай файл додають до `.gitignore` і не комітять.++Крім того, є ще два механізми:++- **Завантаження на рівні підкаталогів за потреби**: CLAUDE.md у підкаталогах не завантажуються під час запуску, а потрапляють до контексту лише тоді, коли Claude читає файли з відповідного каталогу.+- **Автоматична пам’ять (auto memory)**: Claude самостійно занотовує ваші виправлення та вподобання; пам’ять спільна для репозиторію, діє між worktree, а в кожній сесії завантажуються щонайбільше перші 200 рядків або 25 КБ.++Ці чотири області утворюють **ієрархію інструкцій**: згідно з офіційною документацією, «що конкретніші інструкції, то пізніше вони потрапляють до контексту» (інструкції проєкту з’являються після інструкцій користувача). Її цінність у тому, що моделі не доводиться на початку кожної розмови опрацьовувати один гігантський файл інструкцій: натомість вони завантажуються відповідно до найближчої області дії. Саме так Claude Code утілює відповідь четвертої лекції курсу на питання «Чому один гігантський файл інструкцій не працює».++## Підсистема контексту: п’ятирівневий конвеєр стиснення++Керування контекстом у Claude Code — це **п’ятирівневий конвеєр стиснення** (five-layer compaction pipeline), а не просте «коли заповниться — підсумувати». Цю деталь архітектури описано в дослідженні вихідного коду [«Dive into Claude Code» від VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). У п’ятій лекції курсу йдеться про те, що довгі завдання втрачають безперервність; відповідь Claude Code — багаторівнева лійка: спочатку стиснення без втрат (видалення зайвих результатів інструментів), потім структуроване виокремлення, і лише наприкінці — LLM-підсумок із втратами, доповнений запобіжниками проти надмірного стиснення.++Це доповнює дизайн сховища сесій: **дописуване сховище сесій (append-oriented storage)**, у якому вся історія додається до `history.jsonl`, із підтримкою відновлення через `/resume` і створення відгалужень fork. Це гарантує, що «перед завершенням кожної сесії залишається належна передача роботи» — не завдяки добрій пам’яті, а тому, що рівень зберігання є дописуваним і придатним до повторного відтворення.++## Підсистема інструментів: чотири механізми розширення++Claude Code поділяє поверхню розширення на чотири категорії, кожна з яких розв’язує окремий тип завдань. Це одна з найцінніших для запозичення частин його дизайну:++- **Навички (Skills)**: за визначенням [офіційної документації](https://code.claude.com/docs/en/skills), це процедурні знання, описані у `SKILL.md`, які автоматично завантажуються за словами-тригерами й застосовують поступове розкриття. Вони підходять для предметних знань про те, «як щось робити».+- **MCP**: описаний в [офіційній документації](https://code.claude.com/docs/en/mcp) протокол JSON-RPC для підключення зовнішніх систем — стандартний інтерфейс, через який «руки моделі дістаються зовнішнього світу».+- **Hooks**: за [офіційною документацією](https://code.claude.com/docs/en/hooks), це детерміновані скрипти, прив’язані до подій життєвого циклу на кшталт `PreToolUse`, `PostToolUse` і `Stop`.+- **Плагіни / subagent (Subagents)**: за [офіційною документацією](https://code.claude.com/docs/en/sub-agents), складні завдання передаються спеціалізованим agent.++Ключове проєктне рішення — **розподіл обов’язків**: CLAUDE.md визначає «що це», навички — «як це робити», MCP — «до чого підключатися», а hooks — «коли примусово застосовувати». Якщо команда змішує ці рівні (наприклад, записує в CLAUDE.md те, що має робити MCP), виникає описане в курсі протікання контексту.++## Зворотний зв’язок і перевірка: детерміновані обмеження + співпраця людини й машини++У десятій лекції курсу сказано, що «справжньою перевіркою є лише проходження повного процесу». У Claude Code цьому відповідають два паралельні контури:++**1. Система дозволів (детерміновані обмеження).** Дозволи Claude Code не «запитують про все», а використовують сім режимів і класифікатор на основі ML: дії з низьким ризиком дозволяються, а ризиковані — залежно від політики потребують підтвердження або відхиляються (деталі архітектури див. у [дослідженні VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Так принцип «окреслити agent чіткі межі» із сьомої лекції стає примусовим правилом runtime, а не проханням у промпті.++**2. Hooks (запобігання передчасному оголошенню про завершення).** Hook `PostToolUse` може після виконання інструмента примусово запускати перевірки й повертати результат до контексту; hook `Stop` втручається, коли agent оголошує роботу завершеною. Це й означає «розділити виконавця та перевіряльника»: [Anthropic прямо зауважує у статті про harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), що agent схильні впевнено вихваляти власну роботу («confidently praised their work»), тож hooks додають **детерміновані** перевірки замість довіри до самооцінки моделі.++**3. Subagent (ізоляція контексту).** Історія розмов кожного subagent зберігається в окремому файлі sidechain і **не роздуває контекст батьківського agent** (див. [дослідження VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Це поєднання «меж завдання» й «ізоляції контексту»: поділ завдання водночас ізолює контекстне забруднення.++## Спостережуваність і збереження сесій++Журнал Claude Code є повним дописуваним записом (history.jsonl), а явні команди `/compact`, `/clear` та `/init` дають змогу активно керувати станом контексту, а не пасивно чекати на його переповнення. Команда `/init` навіть утілює принцип шостої лекції «нехай agent ініціалізується перед кожним завданням»: згідно з [офіційною документацією](https://code.claude.com/docs/en/memory), вона автоматично аналізує кодову базу й створює початковий CLAUDE.md із командами збірки, інструкціями тестування та інженерними домовленостями.++## Відповідність фреймворку курсу++| Підсистема | Реалізація Claude Code | Оцінка |+| --- | --- | --- |+| Інструкції | Поділ за областями (організація/користувач/проєкт/локальна) + автоматична пам’ять | Багаторівнева пам’ять — еталонна реалізація |+| Інструменти | Чотири типи розширень: навички + MCP + hooks + subagent | Чіткий розподіл обов’язків — головна перевага |+| Середовище | Налаштування в проєкті + settings.json | Спирається на самоопис користувача в CLAUDE.md |+| Стан | Дописуване сховище сесій + п’ятирівневе стиснення + resume/fork | Надзвичайно сильна еталонна реалізація безперервності довгих завдань |+| Зворотний зв’язок | Класифікатор дозволів + примусові перевірки через hook PostToolUse | Перетворює «запобігання передчасному завершенню» на детермінований механізм |++## Проєктні рішення, які варто запозичити++1. **Розподіляйте інструкції за областю дії**, а не складайте їх в один файл. CLAUDE.md на рівні каталогу — витончена реалізація «завантаження за місцем потреби».+2. **Стиснення має бути багаторівневою лійкою**: спочатку без втрат, потім із втратами; не починайте з підсумовування всього тексту.+3. **Використовуйте hooks для детермінованих перевірок**: запобігати передчасному оголошенню про завершення слід примусово на рівні runtime, а не проханнями в промпті.+4. **Ізолюйте контекст subagent**: поділяйте не лише завдання, а й контекст, щоб підзавдання не забруднювали головний цикл.+5. **Дописуване й відтворюване сховище сесій**: передавання роботи гарантує рівень зберігання, а не пам’ять.++## Джерела (оригінали / вихідний код)++Кожне твердження можна простежити до наведеного нижче оригінального тексту або вихідного коду, щоб уникнути переказу з пам’яті:++- **Офіційна документація Claude Code · Memory**: новий контекст для кожної сесії, чотири області CLAUDE.md, завантаження підкаталогів за потреби, auto memory (200 рядків / 25 КБ), створення CLAUDE.md командою `/init`.<br/>https://code.claude.com/docs/en/memory+- **Офіційна документація Claude Code · Skills / MCP / Hooks / Sub-agents**: визначення чотирьох механізмів розширення й подій (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab «Dive into Claude Code»** (звіт із дослідженням вихідного коду): п’ятирівневий конвеєр стиснення, сім режимів дозволів + ML-класифікатор, sidechain для subagent, дописуване сховище сесій history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic «Effective harnesses for long-running agents»**: джерело тверджень про те, що «надійність походить від harness, а не моделі», agent упевнено вихваляють свою роботу, а для перевірки слід застосовувати hooks.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Огляд Claude Code Full Stack** (спільнота; поділ CLAUDE.md / Skills / MCP / Subagents / Hooks): додатковий матеріал про розподіл обов’язків між механізмами розширення.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Пов’язані лекції: [Лекція 03 · Як зробити репозиторій єдиним джерелом правди](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Лекція 09 · Як запобігти передчасному оголошенню agent про завершення](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Лекція 10 · Чому справжньою перевіркою є лише наскрізне тестування](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/uk/harness-designs/codex/index.md b/docs/uk/harness-designs/codex/index.mdnew file mode 100644index 0000000..bfe5017--- /dev/null+++ b/docs/uk/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Розбір дизайну harness у Codex++[Codex](https://openai.com/index/harness-engineering/) від OpenAI, імовірно, найтісніше з чотирьох продуктів пов’язаний із «засадничою доктриною harness»: стаття «Harness Engineering», яка дала назву всій галузі, є підсумком досвіду команди OpenAI, що створювала продукт за допомогою Codex. Тому розібрати дизайн harness у Codex значною мірою означає розібрати інженерну практику, що стоїть за цією статтею.++Філософію Codex можна звести до одного речення: **репозиторій є джерелом правди (repository as the system of record), AGENTS.md — лише сторінка-покажчик, а цінність інженерної роботи полягає в проєктуванні середовища, вираженні наміру та побудові циклів зворотного зв’язку.**++## Позиціонування одним реченням++За кілька тижнів команда OpenAI за допомогою Codex випустила продукт, що зрештою виріс до понад мільйона рядків коду, і **кожен рядок цього коду написав Codex** (див. розділ «Designing for growth» в оригінальній статті [Harness Engineering](https://openai.com/index/harness-engineering/)). Їхня практика відповідає на питання: як організувати систему, коли роль інженера змінюється з «писати код» на «проєктувати harness». Сам Codex CLI — монолітний двійковий файл із відкритим вихідним кодом, реалізований на Rust ([github.com/openai/codex](https://github.com/openai/codex)), але його головний внесок у harness полягає у **домовленостях (convention)** та **інженерії контексту**, а не в ефектних точках розширення.++## Підсистема інструкцій: AGENTS.md — сторінка-покажчик, а не енциклопедія++Це одне з найвпливовіших проєктних рішень Codex у теорії harness:++> Один гігантський файл інструкцій не придатний для автоматизованих перевірок (покриття, актуальності, власності, перехресних посилань), тому розбіжність із реальністю неминуча. Отже, ми більше не розглядаємо AGENTS.md як енциклопедію, а використовуємо його як **сторінку-покажчик**. Знання про кодову базу містяться у структурованій документації, на яку вказує AGENTS.md.++(Вище наведено прямий переказ розділу «AGENTS.md should be a directory page» з оригінальної статті [«Harness Engineering»](https://openai.com/index/harness-engineering/).)++У четвертій лекції курсу сказано, що «один гігантський файл інструкцій не працює», а Codex дає пряму відповідь: обмежувати AGENTS.md приблизно 100 рядками (оригінальна стаття рекомендує близько 100 рядків, а за наближення до межі — переносити матеріал до `docs/`), розділяти решту в каталозі `docs/` і дозволяти agent читати її за потреби. Саме звідси походить авторитетний принцип «дайте карту, а не інструкцію».++Супровідний принцип має назву **забезпечуйте виконання інваріантів, а не мікрокеруйте реалізацією** (в оригіналі: «don't micromanage the implementation; focus on invariants»): AGENTS.md містить лише жорсткі обмеження, які не можна порушувати, і команди перевірки, а спосіб реалізації залишається моделі. Це безпосередньо відповідає принципу другої лекції «обмеження замість мікрокерування».++## Підсистема контексту: Write-Select-Compress-Isolate++Інженерію контексту Codex можна узагальнити чотирма стратегіями. Спільнота сформулювала цей фреймворк після того, як «context engineering» стала окремою дисципліною, а потім зіставила його з Codex (джерело фреймворку — [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):++- **Write (записувати назовні)**: зберігати контекст поза вікном — записувати висновки в документацію, а стан у файли, замість того щоб залишати їх у розмові. Відповідає принципу «репозиторій є джерелом правди».+- **Select (вибирати всередину)**: додавати до вікна лише потрібні token — AGENTS.md показує шлях, а файли читаються за потреби, замість завантаження всього репозиторію.+- **Compress (стискати)**: зберігати справді важливе — Codex підтримує автоматичне стиснення та ручну команду `/compact`, а також налаштування `compact_prompt` (див. [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (ізолювати)**: розділяти контекст за різними межами — використовувати subagent для ізоляції контекстів різних завдань, щоб frontend-subagent ніколи не бачив schema бази даних backend.++Codex також має тонко продуманий контекст середовища: аналіз вихідного коду в спільнотному проєкті [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) показує, що `build_environment_update_item` виводить лише **змінені поля** (CWD, гілка git, файлова система) і тільки коли середовище змінюється, а не вставляє повний системний контекст у кожному циклі. Це інженерна деталь принципу «не тримати повторювані token у контексті».++## Інструменти та межі: ізоляція через worktree + subagent++Два основні механізми harness у Codex:++**1. Ізоляція середовища через git worktree.** У розділі «Environment» оригінальної статті [«Harness Engineering»](https://openai.com/index/harness-engineering/) сказано: кожне завдання виконується в окремому git worktree разом із локальним стеком спостережуваності (журналами, метриками, трасуванням), щоб кожну зміну можна було перевірити в незалежному середовищі. Це фізичне втілення принципу сьомої лекції «чітко окреслювати межі кожного завдання для agent»: межі забезпечуються не проханням в інструкціях, а примусовою ізоляцією середовища. Підсистема середовища (environment) тут реалізована як жорстка ізоляція.++**2. Subagent на рівні ядра.** `spawn_agent` / `wait_agent` у Codex — інструменти рівня ядра: модель явно створює subagent, надає йому окрему історію сесії та набір інструментів і чекає на результат. Subagent успадковує інструкції AGENTS.md від батьківського рівня, але працює у **власному контексті**. Конфігурація зберігається в `.codex/agents/*.toml` і дає змогу задавати різні моделі та інструкції (детальніше див. розділ Sub-agents у [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)). Це безпосереднє втілення «ізоляції контексту» й водночас духу дванадцятої лекції про «передавання роботи»: кожен subagent є робочою одиницею з чіткими межами.++## Підсистема зворотного зв’язку: команди перевірки в специфікації++Практика OpenAI найбільше наголошує на одному: явно вказуйте команди перевірки в AGENTS.md, перетворюючи «як переконатися, що все зроблено правильно» на частину репозиторію. В інженерному процесі Codex тести, CI, документація й конфігурація спостережуваності — усе створює Codex, і все це є «виконуваними шляхами перевірки». Якщо модель потужна, але ненадійна, розв’язання полягає не в надії на її сумлінність, а в тому, щоб зробити **шлях перевірки стандартним компонентом harness**.++Політики підтвердження (approval policies) і режим планування (plan mode) забезпечують інший напрям зворотного зв’язку: перед ризикованими діями спочатку створюється план і запитується підтвердження, а «межі завдання» та «право людини ухвалювати рішення» стають засобами контролю runtime.++## Відповідність фреймворку курсу++| Підсистема | Реалізація Codex | Оцінка |+| --- | --- | --- |+| Інструкції | AGENTS.md як сторінка-покажчик + поділ у docs/ + забезпечення інваріантів | Еталонний підхід, що визначив принцип «дайте карту, а не інструкцію» |+| Інструменти | Ізоляція через worktree + subagent через spawn_agent | Межі жорстко забезпечуються середовищем — дуже сильна реалізація |+| Середовище | Окремий worktree + стек спостережуваності | Ізоляція через worktree — його візитівка |+| Стан | Стратегія Write (стан записується у файли/документацію) | Спирається на домовленості, а не вбудовану пам’ять |+| Зворотний зв’язок | Команди перевірки у специфікації + політики підтвердження + plan mode | Стандартизований шлях зворотного зв’язку, який варто запозичити |++Порівняння Codex і Claude Code доволі показове: Claude Code діє через «додавання» — вбудовує пам’ять, дозволи та subagent у ядро; Codex — через «віднімання»: стримує ядро й покладає більше відповідальності на домовленості репозиторію та інженерію контексту. Саме тому спільнота часто каже, що «філософія harness у Codex цінніша за його код».++## Проєктні рішення, які варто запозичити++1. **Пишіть AGENTS.md як сторінку-покажчик**: обмежуйте його приблизно 100 рядками, посилайтеся на подробиці в docs/ і забезпечте можливість автоматизованої перевірки.+2. **Записуйте лише інваріанти, не мікрокеруйте реалізацією**: жорсткі обмеження + команди перевірки, а решту залишайте моделі.+3. **Використовуйте worktree для ізоляції середовища**: межі завдання забезпечує середовище, а не прохання в інструкціях.+4. **Передавайте лише зміни контексту середовища**: у кожному циклі виводьте тільки змінені поля, а не повторюйте весь системний контекст.+5. **Використовуйте subagent для ізоляції контексту**: поділяйте контекст разом із завданням, щоб підзавдання не забруднювали головний цикл.++## Джерела (оригінали / вихідний код)++Кожне твердження можна простежити до наведеного нижче оригінального тексту або вихідного коду, щоб уникнути переказу з пам’яті:++- **OpenAI «Harness Engineering»**: AGENTS.md як сторінка-покажчик і рекомендація близько 100 рядків, execute invariants / don't micromanage, ізоляція через worktree + стек спостережуваності, команди перевірки у специфікації, приклад продукту з понад мільйоном рядків, політики підтвердження й plan mode. Головне джерело всіх основних тверджень цієї статті.<br/>https://openai.com/index/harness-engineering/+- **Офіційна специфікація OpenAI «AGENTS.md»** (AGENTS.md як стандарт міжінструментальних домовленостей):<br/>https://openai.com/index/agents-md/+- **Репозиторій Codex CLI із відкритим вихідним кодом** (монолітний двійковий файл, реалізований на Rust):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (спільнота): фреймворк Write-Select-Compress-Isolate, `/compact` і `compact_prompt`, subagent через `spawn_agent` / `wait_agent` та конфігурація `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (спільнотний аналіз вихідного коду): такі деталі реалізації, як інкрементальний контекст середовища в `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Пов’язані лекції: [Лекція 03 · Як зробити репозиторій єдиним джерелом правди](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Лекція 04 · Як розподілити інструкції між різними файлами](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Лекція 07 · Як чітко окреслити межі кожного завдання для agent](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/uk/harness-designs/deepseek/index.md b/docs/uk/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..5ad945c--- /dev/null+++ b/docs/uk/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# Розбір дизайну DeepSeek Harness++[DeepSeek Harness](https://deepseek.com/harness) (команда `dsh`, репозиторій `deepseek-ai/deepseek-harness`) випущено в серпні 2026 року як Developer Preview. Офіційне визначення дуже пряме: **Agent = Model + Environment + Tools + State** — модель, середовище, інструменти та стан.++Якщо розбір перших трьох продуктів відповідав на питання «як слід проєктувати harness», то DeepSeek Harness ставить радикальніше питання: **чи може harness відокремитися від конкретної моделі й стати незалежним runtime?** Його відповідь — так, і цей підхід доведено до межі. В [архітектурній документації](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) прямо сказано: *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* (кожна частина продукту є плагіном, включно з адаптером моделі, реєстром інструментів, журналом сесії та самим циклом agent).++У цій статті ми розберемо три головні аспекти: плагінне ядро, шви можливостей (capability seam), конвеєр подій і найсильніше інженерне обмеження — «Model-visible means logged».++## Позиціонування одним реченням++Традиційний coding agent має структуру «LLM + фіксований цикл agent + фіксований набір інструментів». DeepSeek Harness має структуру «модель + плагінне ядро (Cordis)»: ядро відповідає лише за завантаження й вивантаження плагінів, залежності та механізм подій і **не володіє жодною конкретною можливістю agent**. В [архітектурній документації](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) це сформульовано так: «There is no privileged core to patch» (немає привілейованого ядра, яке потрібно виправляти) і «you extend dsh by mounting a plugin beside the others» (щоб розширити dsh, достатньо змонтувати плагін поруч з іншими, не змінюючи ядро). Це означає, що навіть цикл agent не є недоторканним: можна взяти модель DeepSeek, підключити subagent із Claude Code, додати віддалену sandbox, написати власну пам’ять, замінити цикл і UI та зібрати цілком нового agent.++Це найповніше втілення твердження курсу «все поза вагами моделі є harness»: якщо harness незалежний, нехай він стане окремою операційною системою.++## Ядро архітектури 1: шов можливості (Capability Seam)++У DeepSeek Harness поняття Service позначає «можливість», а майже кожну можливість поділено на три рівні:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Візьмімо файлову систему: під `FS Service` працюють кілька Provider — Local FS, E2B FS і Remote FS, а назовні вони надають єдиний інтерфейс file tools. Shell, Subprocess, Sandbox, Web, LLM і SubAgent мають таку саму структуру. Цю трирівневу схему не виведено в нашому аналізі — в оригіналі розділу [архітектурної документації · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) прямо сказано: *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* (шов можливості — замінна можливість із трьома ролями: Service Definition оголошує інтерфейс, Service Provider реалізує його, а Consumer використовує; останнім зазвичай є інструмент, доступний моделі).++Це розв’язує давню проблему інженерії harness: **від чого має залежати agent — від «конкретного інструмента» чи від «інтерфейсу можливості»?** DeepSeek Harness обирає друге. У термінах курсу це означає, що «підсистема інструментів» стандартизована як інтерфейс: заміна Provider не змінює інструменти, доступні моделі, але повністю змінює середовище.++## Ядро архітектури 2: конвеєр подій (Event Pipeline)++Усередині DeepSeek Harness працює не простий ланцюжок «LLM → інструмент → LLM», а конвеєр подій, кожна ланка якого є точкою події, доступною для прослуховування плагінами:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(Наведений вище конвеєр — це переказ розділу [архітектурної документації · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): `turn/*`, `step/*`, `user/message`, `assistant/*` і `tool/*` є збережуваними подіями сесії, а `agent/pre-step`, `agent/request`, `llm/stream` і `tools/*` — точками розширення, які можуть прослуховувати плагіни.)++Найбільша перевага цього дизайну: **для багатьох функцій узагалі не потрібно змінювати сам цикл agent**. Потрібна перевірка безпеки перед виконанням інструмента? Прослуховуйте `tools/pre-execute`. Потрібна пам’ять? Додавайте її через `agent/pre-step`. Потрібен запис поведінки? Підпишіться на події сесії. Потрібно змінити запит моделі? Додайте hook до `agent/request`. Потрібно вирішувати, чи продовжувати міркування? Прослуховуйте `agent/turn-stopping`.++Порівняно з одинадцятою лекцією курсу «Як зробити виконання agent спостережуваним», DeepSeek Harness заходить далі: він не просто «додає журнали», а перетворює **кожен крок циклу на точку події**, завдяки чому спостережуваність, дозволи, пам’ять і політики підключаються до циклу як слухачі, а не жорстко вбудовуються в нього.++## Ядро архітектури 3: Session Event Log і «Model-visible means logged»++DeepSeek Harness має **append-only Session Event Log (лише дописуваний журнал подій сесії)** та встановлює надзвичайно сильне інженерне обмеження. В оригіналі розділу [архітектурної документації · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) сказано:++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Усе, що бачить модель, має бути записано. Усе, що потрапляє до запиту моделі, повинно відтворюватися з журналу, і це забезпечує інваріант runtime.)++Інакше кажучи, спостережуваність — не журнал, доданий постфактум, а первинне обмеження harness: усе, що потрапляє до контексту моделі, за замовчуванням має залишити запис. Це безпосередньо перегукується з тезою фінальної лекції «спостережуваність належить до harness» і перетворює дизайн сховища append-only на принцип: журнал лише дописується, а не перезаписується, тому стан сесії можна відтворити.++## Відповідність фреймворку курсу++| Підсистема | Реалізація DeepSeek Harness | Оцінка |+| --- | --- | --- |+| Інструкції | Плагінна архітектура; правила/навички додаються як плагіни | Надзвичайна свобода, але немає вбудованої домовленості на кшталт «CLAUDE.md» |+| Інструменти | Шов можливості Service Definition → Provider → Consumer | Максимальна стандартизація підсистеми інструментів |+| Середовище | Provider для sandbox/FS/Shell можна повністю замінити (включно з віддаленим E2B) | Середовище повністю змінне |+| Стан | append-only Session Event Log + Model-visible means logged | Спостережуваність є первинним обмеженням |+| Зворотний зв’язок | permission / guard / policy / hook у tools/pre-execute | Механізм зворотного зв’язку перетворено на події |++Докорінна відмінність DeepSeek Harness від інших трьох продуктів полягає в тому, що Pi, Claude Code і Codex оптимізують harness усередині «конкретного agent», тоді як DeepSeek Harness визначає harness як **операційну систему, незалежну від моделі**, а сам agent є лише змінним застосунком у цій OS. Ціна теж очевидна: висока свобода означає вищі витрати на конфігурацію. Це невіддільний зворотний бік дизайну «harness як OS» (на етапі Developer Preview продукт також позиціонується як рання можливість випробувати механізми, що ще розвиваються).++## Проєктні рішення, які варто запозичити++1. **Перетворіть кожен крок циклу на точку події**: підключайте дозволи, пам’ять, політики та журнали до циклу як слухачів, а не вбудовуйте їх жорстко.+2. **Стандартизуйте шви можливостей**: залежте від «інтерфейсу можливості», а не від «конкретного інструмента», щоб можна було цілком замінити середовище, не змінюючи доступну моделі поверхню інструментів.+3. **Model-visible means logged**: усе, що бачить модель, має бути записано; перетворіть спостережуваність із «додаткової переваги» на «первинне обмеження».+4. **append-only журнал сесії**: відтворюваний стан і надійне передавання роботи є інженерною гарантією того, що «кожна сесія залишає чистий стан».++## Джерела (оригінали / вихідний код)++Кожне твердження можна простежити до наведеного нижче оригінального тексту або вихідного коду, щоб уникнути переказу з пам’яті:++- **Офіційний сайт DeepSeek Harness**: визначення продукту «Agent = Model + Environment + Tools + State», статус Developer Preview і команда `dsh`.<br/>https://deepseek.com/harness+- **Репозиторій deepseek-ai/deepseek-harness** (команда `dsh`, ліцензія MIT):<br/>https://github.com/deepseek-ai/deepseek-harness+- **Архітектурна документація architecture.md**: головне джерело цієї статті — «Every part of the product is a plugin», «There is no privileged core to patch», конвеєр подій Turn flow, три ролі Capability seams, «Model-visible means logged» та інваріант runtime, append-only Session Event Log, шви можливостей fs/tools/telemetry і підсистеми `ctx.*`.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **Супровідні розділи архітектурної документації**: огляд ядра Cordis (plugins contribute services, typed events, reversible effects), деталі швів можливостей і підсистема Session.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Пов’язані лекції: [Лекція 11 · Як зробити виконання agent спостережуваним](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Лекція 12 · Чому кожна сесія має залишати чистий стан](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Лекція 02 · Що таке harness насправді](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/uk/harness-designs/index.md b/docs/uk/harness-designs/index.mdnew file mode 100644index 0000000..47a5dfc--- /dev/null+++ b/docs/uk/harness-designs/index.md@@ -0,0 +1,29 @@+# Розбір передових harness++У цій рубриці теорія harness із лекцій курсу послідовно зіставляється із сучасними передовими реальними продуктами. Для кожного продукту нас цікавить лише одне: **як спроєктовано його harness** — тобто інженерну інфраструктуру навколо моделі: п’ять підсистем інструкцій, інструментів, середовища, стану й зворотного зв’язку, а також такі ключові механізми, як безперервність контексту, ініціалізація, верифікація, спостережуваність, передавання роботи та цикли.++Ми навмисно не обговорюємо, наскільки сильні міркувальні здібності моделі, наскільки високий її результат у конкретному бенчмарку, і не даємо загального огляду того, «що вміє цей agent». Це питання рівня моделі та продукту. Тут ми розбираємо лише harness — усе поза вагами моделі.++## Чому це варто розбирати++У першій лекції сказано: сильна модель не означає надійного виконання. Одна й та сама модель у різних harness може відрізнятися за результативністю на порядок. Проте лекції пояснюють, «як слід робити», а ці продукти показують, «як це насправді роблять провідні команди».++Кожен продукт — це окремий набір проєктних рішень. Зіставивши їх, ви побачите, як ті самі ключові механізми різні команди реалізують зовсім по-різному:++- **Pi** будує harness як мінімалістичне ядро з програмованими розширеннями та реалізує інженерію контексту через «мінімальний системний промпт + завантаження за потреби».+- **Claude Code** будує harness як повноцінне runtime-середовище: багаторівнева пам’ять, п’ятирівнева compaction, permissions, hooks і subagent.+- **Codex** доводить філософію harness до межі: репозиторій є джерелом правди, AGENTS.md — лише сторінкою-покажчиком, а worktree ізолює середовища.+- **DeepSeek Harness** узагалі визначає сам harness як runtime, незалежний від моделі: Everything is a Plugin.++## Перелік статей++- [Розбір дизайну harness у Pi](./pi/): мінімалістичне ядро + програмовані розширення, що виносять інженерію контексту за межі системного промпту.+- [Розбір дизайну harness у Claude Code](./claude-code/): багаторівнева пам’ять, п’ятирівнева compaction, permissions і hooks — повноцінне runtime-середовище agent.+- [Розбір дизайну harness у Codex](./codex/): репозиторій як джерело правди, AGENTS.md як сторінка-покажчик, ізоляція середовища та цикл зворотного зв’язку.+- [Розбір дизайну DeepSeek Harness](./deepseek/): Everything is a Plugin — навіть цикл agent реалізовано як замінний plugin.++## Як читати++Рекомендуємо спочатку прочитати перші лекції курсу, особливо [Лекцію 02. Що таке harness насправді](../lectures/lecture-02-what-a-harness-actually-is/), щоб опанувати фреймворк із п’яти підсистем, а потім повернутися сюди й подивитися, як реальні продукти втілюють ці механізми.++Наприкінці кожної статті є два розділи — «Відповідність фреймворку курсу» та «Проєктні рішення, які варто запозичити». Вони допоможуть швидко перекласти дизайн продукту мовою понять курсу й безпосередньо перенести вдалі рішення до власного проєкту.diff --git a/docs/uk/harness-designs/pi/index.md b/docs/uk/harness-designs/pi/index.mdnew file mode 100644index 0000000..6914a7d--- /dev/null+++ b/docs/uk/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Розбір дизайну harness у Pi++[Pi](https://pi.dev/) (npm-пакет `@earendil-works/pi-coding-agent`) називає себе "minimal agent harness" — мінімалістичним agent harness. Це формулювання варто прочитати уважно: продукт не називає себе «найсильнішим coding agent» чи «найзручнішим інструментом AI-програмування», а чітко закріплює своє позиціонування за словом **harness**.++У цій статті ми розберемо Pi за допомогою фреймворку п’яти підсистем курсу — інструкцій, інструментів, середовища, стану й зворотного зв’язку — та з’ясуємо, чим його проєктна філософія принципово відрізняється від Claude Code і Codex. Одразу наведемо відповідь: **філософія Pi — «мінімізація ядра + програмованість розширень»; інженерія контексту виходить за межі системного промпту, а змінювати harness може користувач (і навіть сам Pi), замість того щоб Pi вирішував за вас, яким має бути harness.**++## Позиціонування одним реченням++Pi — це мінімалістичне ядро: офіційне позиціонування навмисно робить ядро малим і повертає право вибору вам. На [головній сторінці pi.dev](https://pi.dev/) дослівно сказано: "Ask Pi to build what you want, or install a package that does it your way". Pi поділяє harness на чотири рівні налаштування:++- **Розширення (Extensions)**: TypeScript hooks, прив’язані до подій життєвого циклу Pi, — програмована поверхня рівня runtime.+- **Навички (Skills)**: пакети можливостей, що завантажуються за потреби, містять інструкції та інструменти й використовують поступове розкриття (progressive disclosure).+- **Шаблони промптів (Prompt templates)**: повторно використовувані Markdown-промпти, які розгортаються командою `/name`.+- **Теми (Themes)**: зовнішній вигляд TUI.++Сам цей багаторівневий підхід є дизайном harness: **правила й розширення повністю визначають, що й коли бачить модель, замість того щоб жорстко закодовувати це в ядрі.**++## Основний цикл++Як і будь-який coding agent, Pi за своєю суттю виконує цикл while «міркування → виконання інструмента → спостереження → нове міркування». Цікавий не сам цикл, а те, як Pi працює з його зовнішнім контуром: управління контекстом розширено від «compaction» усередині циклу до «контролю» поза ним.++Runtime Pi надає зовнішній програмований інтерфейс: у розділі [Programmatic Usage вихідного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md), окрім інтерактивного TUI, підтримуються скриптові режими друку/JSON, протокол RPC та вбудовування через SDK. Завдяки цьому той самий harness може керуватися як людиною крок за кроком, так і автоматично через CI/CD або іншу програму. Це відповідає передумові переходу «від ручного керування до автоматичного циклу» з тринадцятої лекції курсу: якщо harness може працювати лише через взаємодію з людиною, він ніколи не стане частиною автоматичного циклу.++## Підсистема інструкцій: AGENTS.md і SYSTEM.md++Pi стримано працює з «інструкціями», але має чітку ієрархію:++- **AGENTS.md**: у розділі [Project Context Files вихідного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) чітко вказано порядок завантаження: глобальний `~/.pi/agent/AGENTS.md` → послідовний обхід батьківських директорій угору → `./AGENTS.md` у поточній директорії (також підтримується CLAUDE.md). Це пряме втілення принципу «репозиторій — джерело правди»: інструкції є файлами, а не нагадуваннями в чаті.+- **SYSTEM.md**: в [офіційній документації pi.dev](https://pi.dev/docs/usage/project-context) сказано, що для кожного проєкту можна замінити (replace) або доповнити (append) стандартний системний промпт. Це єдиний офіційний спосіб, у який Pi дозволяє змінювати «системний промпт», і водночас його рівень «самоопису середовища».++Pi офіційно наголошує, що його системний промпт **мінімалістичний**. За цим стоїть чіткий компроміс: ядро не наповнюється довгими правилами «якщо… то…», натомість надає точки розширення, щоб правила з’являлися у формі навичок і розширень лише тоді, коли вони потрібні. Це прямо перегукується з четвертою лекцією курсу «Чому один гігантський файл інструкцій не працює»: завдяки «мінімалістичному ядру + поділу на файли + завантаженню за потреби» Pi природно уникає проблеми гігантських інструкцій.++## Стан і контекст: найдетальніша частина Pi++Інженерія контексту Pi заслуговує на особливу увагу, адже такі поняття курсу, як «безперервність контексту» та «запобігання деградації контексту», тут втілені в конкретних механізмах:++**1. Програмованість compaction.** Коли система наближається до межі контексту, старі повідомлення автоматично підсумовуються. В [офіційній документації pi.dev](https://pi.dev/docs/usage/sessions) сказано, що сама стратегія compaction **налаштовується**: через розширення можна реалізувати тематичну compaction, підсумовування з урахуванням коду або навіть використати для підсумовування іншу модель. Вихідний README також розкриває деталі стандартного механізму: автоматична compaction запускається у двох випадках — під час відновлення після переповнення контексту або після перевищення порога збереження; точка поділу залишає близько 20 тисяч останніх token, а попередні повідомлення згортаються в "context handoff" і послідовно стискаються ланцюжком. Отже, Pi розглядає «спосіб compaction» не як незмінну константу, а як частину harness.++**2. Динамічний контекст (Dynamic context).** В [офіційній документації pi.dev](https://pi.dev/docs/usage/extensions) сказано, що перед кожним кроком міркування розширення можуть додавати повідомлення, фільтрувати історію повідомлень, реалізовувати RAG і створювати довготривалу пам’ять. Це ще один крок після «compaction, коли контекст заповнився»: ви вирішуєте, що потрапить у контекстне вікно, ще до входу інформації у вікно. У термінах курсу — «зробити процес роботи agent спостережуваним і придатним до налагодження» та «зберігати безперервність контексту» — Pi переносить обидві функції на поверхню розширень.++**3. Дерево session (Session tree).** На [головній сторінці pi.dev](https://pi.dev/) прямо сказано: "sessions are stored as trees"; команда `/tree` дає змогу повернутися до будь-якого історичного вузла й продовжити роботу, а всі гілки зберігаються в одному файлі. Це розв’язує проблему «розриву контексту між session», на якій неодноразово наголошує курс: не через жорстке склеювання підсумками, а через структуроване відтворення історії. Гілку можна експортувати в HTML або завантажити як gist для поширення, що водночас забезпечує спостережуваність.++## Підсистема інструментів: навички й розширення++«Інструменти» Pi мають два рівні:++- **Навички (Skills)**: розділ [Skills вихідного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) дає чітке визначення — "self-contained capability packages that the agent loads on-demand", тобто самодостатні пакети можливостей, які завантажуються за потреби, містять інструкції та інструменти й відповідають стандарту Agent Skills. Поступове розкриття додає деталі навички до контексту лише після спрацювання, **не перевантажуючи кеш промпту (prompt cache)**. Це дизайн harness з погляду вартості: кожен додатковий token у контексті оплачується під час кожного міркування; завантаження навичок за потреби є ще одним вираженням принципу «дайте карту, а не підручник».+- **Розширення (Extensions)**: TypeScript hooks, прив’язані до вбудованих подій життєвого циклу. У розділі [Hooks вихідного README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) наведено офіційні приклади застосування: перехоплення небезпечних команд (permission gate), створення checkpoint стану коду під час перемикання завдань, захист шляхів (наприклад, заборона запису в `.env`), зміна виводу інструмента перед передаванням моделі, а також додавання повідомлень із зовнішніх джерел (спостерігач за файлами/Webhook/CI), щоб активувати agent. API цих hooks також експортується з `@mariozechner/pi-coding-agent/hooks`. Своєю чергою, спільнотний harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) додатково обгортає поверхню hooks у готові розширення skill-router, session-summary, extract-patterns, telemetry тощо.++Розширення — найважливіше проєктне рішення Pi: **продукт не просто «дає користувачеві кілька перемикачів», а відкриває всю внутрішню поверхню подій runtime.** Потрібна пам’ять? Додайте її через `agent/pre-step`. Потрібно записувати поведінку? Підпишіться на події session. Потрібно змінити запит до моделі? Підключіться до `agent/request`. Ви можете дозволити Pi змінювати власний harness — це ближче до визначення «програмованого harness», ніж будь-які «параметри конфігурації».++## Зворотний зв’язок і верифікація: навіть «навчання» як harness++Pi не має вбудованого обов’язкового шлюзу тестування — користувач має записати команди верифікації в AGENTS.md. Проте спільнотний harness [pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness) структурує «цикл зворотного зв’язку» через розширення, а розділ Hooks офіційного README надає основу для подібних механізмів:++- **session-summary** (розширення pi-agent-harness): підтримує ковзні записи в `PROGRESS.md` — це підсистема стану з курсу, відстеження прогресу тривалих завдань.+- **extract-patterns** (розширення pi-agent-harness): збирає з session потенційні уроки й зберігає їх у `LESSONS.md`, перетворюючи домовленість «належно передавати роботу наприкінці кожної session» на механізм.+- **telemetry** (розширення pi-agent-harness): записує використання token, вартість тощо — спостережуваність.++Той самий спільнотний репозиторій розвиває цей патерн: `VISION.md` (мета), `PROGRESS.md` (прогрес), `LESSONS.md` (досвід), `STANDARDS.md` (стандарти) — усе це Markdown-файли, що зберігаються між session. Це той самий підхід «репозиторій — джерело правди + файл прогресу + механізм передавання роботи», рекомендований курсом, але завдяки механізму розширень Pi він доступний одразу після встановлення.++## Відповідність фреймворку курсу++Суб’єктивна оцінка Pi за п’ятьма підсистемами курсу для порівняння:++| Підсистема | Реалізація Pi | Оцінка |+| --- | --- | --- |+| Інструкції | Ієрархічне завантаження AGENTS.md + SYSTEM.md | Чітка ієрархія, але самі правила має писати користувач |+| Інструменти | Навички за потреби + hooks для всього життєвого циклу розширень | Надзвичайно сильна реалізація, що перетворює систему інструментів на програмовану поверхню |+| Середовище | Самоопис середовища через SYSTEM.md; runtime-середовище користувач оголошує в AGENTS.md | Механізм відкритий, але відтворюваність залежить від опису користувача |+| Стан | Дерево сесій + налаштовуване стиснення + PROGRESS.md | Надзвичайно сильна реалізація; робота між сесіями та відновлюваність лежать у її основі |+| Зворотний зв’язок | Команди перевірки визначає користувач; session-summary / extract-patterns перетворено на механізми | Механізм надано, наповнення залежить від користувача |++Компроміс Pi різко контрастує з Claude Code і Codex: Claude Code вбудовує «пам’ять, permissions, subagent» у ядро й надає їх одразу; Codex робить стандартними «правила репозиторію та ізоляцію середовища»; Pi **нічого не вирішує замість вас**, а перетворює право вибору на точки розширення. Ціна цього підходу — потреба самостійно писати розширення або встановлювати чужі пакети.++## Проєктні рішення, які варто запозичити++1. **Зробіть стратегію compaction підключуваною.** У вашому harness спосіб compaction контексту має бути не жорстко заданим параметром, а замінним інтерфейсом стратегії.+2. **Використовуйте дерево session замість жорсткого підсумовування.** Відновлення між session не обов’язково має спиратися на «підсумок попереднього раунду»; структуроване відтворення історії часто є надійнішою підсистемою стану.+3. **Дбайте про кеш промпту.** Завантажуйте навички за потреби й не додавайте всі правила до системного промпту одразу — це і інженерія контексту, і інженерія вартості.+4. **Дайте agent змінювати власний harness.** Якщо поверхня розширень harness достатньо відкрита, саме «поліпшення поведінки agent» може частково автоматично виконувати agent.++## Довідкові джерела (оригінальні тексти / вихідний код)++Кожне твердження можна простежити до наведеного нижче оригінального тексту або вихідного коду, щоб уникнути переказу з пам’яті:++- **Офіційний сайт pi.dev**: оригінальне позиціонування "Ask Pi to build what you want, or install a package that does it your way", чотири рівні налаштування, дерево сесій ("sessions are stored as trees", `/tree`, збереження в одному файлі, експорт у HTML / поширення через gist).<br/>https://pi.dev/+- **Офіційна документація pi.dev · Sessions**: підключуване стиснення (topic-based / code-aware / інша модель для підсумовування), механізми автоматичного стиснення й динамічного додавання контексту.<br/>https://pi.dev/docs/usage/sessions+- **Офіційна документація pi.dev · Extensions**: розширення можуть перед кожним циклом міркування додавати повідомлення, фільтрувати історію, виконувати RAG і створювати довготривалу пам’ять.<br/>https://pi.dev/docs/usage/extensions+- **Офіційна документація pi.dev · Project Context**: семантика replace / append у SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **README вихідного коду Pi Coding Agent** (badlogic/pi-mono): трирівневий порядок завантаження AGENTS.md (глобальний → батьківські каталоги → поточний каталог), умови запуску `/compact` та автоматичного стиснення й точка поділу на 20 тисяч token, завантаження Skills за потреби та стандарт Agent Skills, життєвий цикл Hooks і чотири офіційні приклади, Programmatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **Спільнотний репозиторій pi-agent-harness**: розширення skill-router / session-summary / extract-patterns / telemetry і файлова система VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++Пов’язані лекції: [Лекція 02. Що таке harness насправді](../lectures/lecture-02-what-a-harness-actually-is/) | [Лекція 05. Збереження контексту між сесіями](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Лекція 13. Інженерія циклів: від ручного керування до автоматизації](../lectures/lecture-13-loop-engineering/)diff --git a/docs/uk/index.md b/docs/uk/index.mdindex 43657c8..a2ded51 100644--- a/docs/uk/index.md+++ b/docs/uk/index.md@@ -25,6 +25,10 @@ Learn Harness Engineering — це курс, присвячений інжене<h3>Бібліотека ресурсів</h3><p>Готові шаблони (AGENTS.md, feature_list.json) для використання у власних репозиторіях.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Розбір передових harness</h3>+ <p>Як Pi, Claude Code, Codex і DeepSeek реально проєктують свої harness — у прив'язці до рамки курсу.</p>+ </a></div>## Основний механізм harnessdiff --git a/docs/uz/harness-designs/claude-code/index.md b/docs/uz/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..98b8ff1--- /dev/null+++ b/docs/uz/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Claude Code harness dizayni tahlili++Anthropic “[Uzoq ishlaydigan agentlar uchun samarali harnessʼlar](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)” maqolasida ishonchlilik manbai model emas, harness ekanini va agent “modeldan tashqarida” cheklanishi kerakligini aniq taʼkidlaydi. Claude Code — shu gʻoyaning mahsulotga aylantirilgan namunasi; Anthropicʼning oʻzi ham uni bevosita **agentic harness** toifasiga kiritadi. Bu marketing iborasi emas: Claude Code hozirgacha ommaga eng batafsil ochib berilgan harness boʻlishi mumkin. Uning manba kodi ochiq, hamjamiyat tadqiqotlari batafsil va kurs maʼruzalaridagi deyarli barcha asosiy mexanizmlar — qatlamli xotira, kontekstni siqish, ruxsatlar, hookʼlar, subagentlar va sessiyani saqlash — toʻliq mahsulot darajasida amalga oshirilgan.++Ushbu maqolada Claude Codeʼni kursning beshta quyi tizimli modeli yordamida tahlil qilamiz. Asosiy eʼtibor uning “kontekst boshqaruvi”, “vaqtidan oldin tugallangan deb eʼlon qilishning oldini olish” va “deterministik cheklovlar” kabi harnessʼning fundamental tushunchalarini qanday amalga oshirganiga qaratiladi.++## Bir jumladagi taʼrif++Claude Codeʼning yadrosi oddiy while siklidan iborat: modelni chaqirish, vositani bajarish, natijani kuzatish va modelni yana chaqirish. Ammo **kodning mutlaq koʻpchiligi ushbu sikl ichida emas, uning atrofidagi tizimlarda joylashgan** — ruxsat tizimi, kontekstni siqish pipelineʼi, kengaytma mexanizmlari, subagentlarni muvofiqlashtirish va sessiyalar ombori. harnessʼning mohiyati ham shu: sikl — skelet, ishonchlilikni esa skelet atrofidagi barcha narsalar belgilaydi.++## Yoʻriqnomalar quyi tizimi: qatlamli xotira tizimi++Claude Code xotira tizimi — uning harness nazariyasiga qoʻshgan eng bevosita hissasi. U kursdagi “repo yagona haqiqat manbai” va “sessiyalararo kontekst uzluksizligi” mavzulariga mos keladi. [“Claude loyihangizni qanday eslab qoladi” rasmiy hujjatida](https://code.claude.com/docs/en/memory) aniq aytilishicha, har bir sessiya mutlaqo yangi kontekst oynasidan boshlanadi va bilim ikki mexanizm orqali sessiyalar orasida olib oʻtiladi: CLAUDE.md fayllari (siz yozgan yoʻriqnomalar) va auto memory (Claude oʻzi yozgan qaydlar).++Rasmiy hujjat CLAUDE.md fayllarini amal doirasiga koʻra toʻrt turga ajratadi (yuklanish tartibi kengdan tor doiraga qarab):++- **Tashkilot siyosati darajasi**: IT/DevOps tomonidan markazlashgan holda boshqariladi (masalan, `/etc/claude-code/CLAUDE.md`); kompaniya miqyosidagi standartlar.+- **Foydalanuvchi darajasi `~/.claude/CLAUDE.md`**: loyihalararo shaxsiy afzalliklar va qoidalar.+- **Loyiha darajasi `./CLAUDE.md` yoki `./.claude/CLAUDE.md`**: loyihaning yagona haqiqat manbai; muhandislik tuzilishi, tech stack va tekshiruv buyruqlari bilan repo orqali ulashiladi.+- **Mahalliy daraja `./CLAUDE.local.md`**: loyiha ichidagi shaxsiy afzalliklar; odatda `.gitignore`ʼga qoʻshilib, commit qilinmaydi.++Bundan tashqari, yana ikkita mexanizm bor:++- **Ichki katalog darajasida talab boʻyicha yuklash**: ichki kataloglardagi CLAUDE.md ishga tushirish paytida yuklanmaydi; Claude ushbu katalogdagi faylni oʻqigandagina kontekstga kiradi.+- **Avtomatik xotira (auto memory)**: Claude sizning tuzatishlaringiz va afzalliklaringiz asosida mustaqil qaydlar yozadi. Ular repo miqyosida ulashiladi, worktreeʼlar orasida amal qiladi va har bir sessiyada koʻpi bilan dastlabki 200 qator yoki 25 KB yuklanadi.++Ushbu toʻrt amal doirasi **yoʻriqnomalar iyerarxiyasi**ni hosil qiladi: rasmiy hujjatga koʻra, “aniqroq yoʻriqnomalar kontekstga keyinroq kiradi” (loyiha yoʻriqnomalari foydalanuvchi yoʻriqnomalaridan keyin keladi). Buning foydasi shundaki, model har bir suhbat boshida bitta ulkan yoʻriqnoma faylini hazm qilmaydi; yoʻriqnomalar amal doirasiga qarab eng yaqin joydan yuklanadi. Bu toʻrtinchi maʼruzadagi “nima uchun bitta ulkan yoʻriqnoma fayli muvaffaqiyatsiz boʻladi” savoliga mahsulot darajasidagi javobdir.++## Kontekst quyi tizimi: besh qatlamli siqish pipelineʼi++Claude Code kontekstni **besh qatlamli siqish pipelineʼi** (five-layer compaction pipeline) orqali boshqaradi; bu shunchaki “toʻlsa, qisqacha mazmun yozish” emas. Ushbu arxitektura tafsiloti VILA Labʼning manba kodiga asoslangan [“Dive into Claude Code” tahlilidan](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf) olingan. Beshinchi maʼruzada “uzoq vazifalar uzluksizlikni yoʻqotadi” deyiladi. Claude Code yechimi koʻp bosqichli voronkadir: avval yoʻqotishsiz kesish (ortiqcha vosita natijalarini olib tashlash), soʻng tuzilmali saralash, faqat oxirida yoʻqotishli LLM xulosasi. Haddan ortiq siqishni oldini olish uchun circuit breaker mexanizmi ham qoʻllanadi.++Bunga sessiyalar ombori dizayni hamroh boʻladi: **qoʻshib borishga yoʻnaltirilgan sessiya ombori (append-oriented storage)**. Butun tarix `history.jsonl` fayliga ketma-ket qoʻshiladi; `/resume` orqali tiklash va fork tarmoqlanishi qoʻllab-quvvatlanadi. Shu tariqa “har bir sessiya tugashidan oldin topshirishni tayyorlash” kafolatlanadi — yaxshi xotira hisobiga emas, balki saqlash qatlami qoʻshib boriladigan va qayta ijro qilinadigan qilib qurilgani sababli.++## Vositalar quyi tizimi: toʻrtta kengaytma mexanizmi++Claude Code kengaytma imkoniyatlarini toʻrt turga ajratadi. Har bir tur alohida muammoni hal qiladi va bu dizaynning eng koʻp oʻrganishga arziydigan qismidir:++- **Koʻnikmalar (Skills)**: [rasmiy hujjatdagi](https://code.claude.com/docs/en/skills) taʼrifga koʻra, `SKILL.md` bilan ifodalanadigan protsessual bilimlar; trigger soʻzlar asosida avtomatik yuklanadi va progressive disclosure usulidan foydalanadi. Muayyan ishni “qanday bajarish”ga oid soha bilimlari uchun mos.+- **MCP**: [rasmiy hujjatdagi](https://code.claude.com/docs/en/mcp) JSON-RPC protokoli tashqi tizimlarga ulanadi; bu “model qoʻllarini tashqi dunyoga yetkazish”ning standart interfeysidir.+- **Hookʼlar (Hooks)**: [rasmiy hujjatga](https://code.claude.com/docs/en/hooks) koʻra, `PreToolUse`, `PostToolUse`, `Stop` kabi lifecycle hodisalariga ulanadigan deterministik skriptlar.+- **Plaginlar / subagentlar (Subagents)**: [rasmiy hujjatga](https://code.claude.com/docs/en/sub-agents) koʻra, murakkab vazifalarni maxsus agentlarga ajratib beradi.++Asosiy dizayn qarori — **masʼuliyatlarni ajratish**: CLAUDE.md “nima”ni, koʻnikmalar “qanday”ni, MCP “qayerga ulanish”ni, hookʼlar esa “qachon majburlash”ni boshqaradi. Agar jamoa bu qatlamlarni aralashtirsa (masalan, MCP bajarishi kerak boʻlgan ishni CLAUDE.mdʼga yozsa), kursda tasvirlangan kontekst sizib chiqishi yuz beradi.++## Qayta aloqa va tekshiruv: deterministik cheklovlar + inson va mashina mehnati taqsimoti++Oʻninchi maʼruzada “faqat toʻliq jarayon bajarilgandagina tekshiruv haqiqiy hisoblanadi” deyiladi. Claude Code bunga ikki yoʻnalishli mexanizm bilan javob beradi:++**1. Ruxsat tizimi (deterministik cheklovlar).** Claude Code ruxsatlari “hamma narsani birma-bir soʻrash” tarzida ishlamaydi. U yettita rejim va ML asosidagi klassifikatordan iborat: past xavfli operatsiyalar oʻtkaziladi, yuqori xavflilari esa siyosatga muvofiq soʻraladi yoki rad etiladi (arxitektura tafsilotlari: [VILA Lab tahlili](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Bu “agent chegaralarini aniq belgilash”ni (yettinchi maʼruza) prompt orqali iltimos qilishdan runtime majburloviga aylantiradi.++**2. Hookʼlar (vaqtidan oldin tugallangan deb eʼlon qilishni toʻxtatish).** `PostToolUse` hookʼi vosita bajarilgach tekshiruvni majburan ishga tushirishi va natijani kontekstga qaytarishi mumkin; `Stop` hookʼi esa agent ish tugaganini eʼlon qilganda aralashadi. Bu “ishni bajaruvchi bilan tekshiruvchi alohida boʻlishi kerak” tamoyilidir. [Anthropic harness haqidagi maqolada kuzatganidek](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), agent oʻz ishini ishonch bilan maqtaydi (“confidently praised their work”). Shu sababli modelning oʻz bahosiga ishonish oʻrniga hook orqali **deterministik** tekshiruv kiritiladi.++**3. Subagentlar (kontekst izolyatsiyasi).** Har bir subagentning suhbat tarixi mustaqil sidechain faylida saqlanadi va **ota agent kontekstini kattalashtirmaydi** (qarang: [VILA Lab tahlili](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Bu “vazifa chegarasi” bilan “kontekst izolyatsiyasi”ning birikmasidir: vazifa boʻlinishi bilan birga kontekstning ifloslanishi ham cheklanadi.++## Kuzatuvchanlik va sessiyani saqlash++Claude Code loglari toʻliq va qoʻshib boriladigan yozuvlar (history.jsonl) shaklida saqlanadi. `/compact`, `/clear`, `/init` kabi aniq buyruqlar yordamida kontekst holatini toʻlib qolishini kutmasdan faol boshqarish mumkin. `/init` esa “agent har safar ishni boshlashdan oldin inisializatsiyadan oʻtishi kerak” tamoyilini (oltinchi maʼruza) bitta buyruqqa aylantiradi: [rasmiy hujjatga](https://code.claude.com/docs/en/memory) koʻra, u kod bazasini avtomatik tahlil qiladi va qurish buyruqlari, test yoʻriqnomalari hamda muhandislik konvensiyalarini oʻz ichiga olgan dastlabki CLAUDE.mdʼni yaratadi.++## Kurs modeliga moslashtirish++| Quyi tizim | Claude Codeʼdagi amalga oshirilishi | Baho |+| --- | --- | --- |+| Yoʻriqnomalar | Amal doirasi boʻyicha qatlamlash (tashkilot/foydalanuvchi/loyiha/mahalliy) + avtomatik xotira | Qatlamli xotira — namunaviy amalga oshirish |+| Vositalar | Koʻnikmalar + MCP + hookʼlar + subagentlardan iborat toʻrtta kengaytma turi | Masʼuliyatlar aniq ajratilgan; asosiy ustunlik |+| Muhit | Loyiha ichidagi sozlamalar + settings.json | Foydalanuvchining CLAUDE.md ichidagi tavsifiga tayanadi |+| Holat | Qoʻshib boriladigan sessiya ombori + besh qatlamli siqish + resume/fork | Juda kuchli; uzoq vazifalar uzluksizligi uchun namuna |+| Qayta aloqa | Ruxsat klassifikatori + PostToolUse hookʼining majburiy tekshiruvi | “Vaqtidan oldin tugallangan deb eʼlon qilish” deterministik mexanizm bilan toʻxtatiladi |++## Oʻrganishga arziydigan dizaynlar++1. **Yoʻriqnomalarni amal doirasi boʻyicha qatlamlang**, bitta faylga uyib tashlamang. Katalog darajasidagi CLAUDE.md — “eng yaqin joydan yuklash”ning nafis yechimi.+2. **Siqishni bosqichli voronkaga aylantiring**: avval yoʻqotishsiz, keyin yoʻqotishli; boshidanoq butun matnni umumlashtirmang.+3. **Deterministik tekshiruvlar uchun hookʼlardan foydalaning**: vaqtidan oldin tugallangan deb eʼlon qilishni prompt bilan iltimos qilish emas, runtime orqali majburlash toʻxtatadi.+4. **Subagentlar kontekstini izolyatsiya qiling**: vazifani boʻlish bilan birga kontekstni ham boʻling; kichik vazifa natijalari asosiy siklni ifloslantirmasin.+5. **Sessiyalar omborini qoʻshib boriladigan va qayta ijro qilinadigan qiling**: topshirishni xotira emas, saqlash qatlami kafolatlaydi.++## Manbalar (asl matn / manba kodi)++Har bir daʼvoni taxminlarga emas, quyidagi asl matn yoki manba kodiga bogʻlash mumkin:++- **Claude Code rasmiy hujjati · Memory**: har bir sessiyadagi yangi kontekst, CLAUDE.mdʼning toʻrtta amal doirasi, ichki kataloglardan talab boʻyicha yuklash, auto memory (200 qator / 25 KB), `/init` orqali CLAUDE.md yaratish.<br/>https://code.claude.com/docs/en/memory+- **Claude Code rasmiy hujjatlari · Skills / MCP / Hooks / Sub-agents**: toʻrtta kengaytma mexanizmi va hodisalarning taʼriflari (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab “Dive into Claude Code”** (manba kodi darajasidagi tahlil): besh qatlamli siqish pipelineʼi, yettita ruxsat rejimi + ML klassifikatori, sidechain subagentlari va qoʻshib boriladigan history.jsonl sessiya ombori.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic “Uzoq ishlaydigan agentlar uchun samarali harnessʼlar”**: “ishonchlilik modeldan emas, harnessʼdan keladi”, agent oʻz ishini ishonch bilan maqtashi va tekshiruv uchun hookʼlardan foydalanish haqidagi fikrlar manbasi.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack qoʻllanmasi** (hamjamiyat; CLAUDE.md / Skills / MCP / Subagents / Hooks qatlamlari): kengaytma mexanizmlarining masʼuliyatlarini ajratish boʻyicha qoʻshimcha oʻqish.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Tegishli maʼruzalar: [3-maʼruza · Kod reposini yagona haqiqat manbaiga aylantirish](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [9-maʼruza · Agentning vaqtidan oldin gʻalabani eʼlon qilishiga yoʻl qoʻymaslik](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [10-maʼruza · Faqat toʻliq jarayon bajarilgandagina tekshiruv haqiqiy hisoblanadi](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/uz/harness-designs/codex/index.md b/docs/uz/harness-designs/codex/index.mdnew file mode 100644index 0000000..bafe5db--- /dev/null+++ b/docs/uz/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Codex harness dizayni tahlili++OpenAI yaratgan [Codex](https://openai.com/index/harness-engineering/) ushbu toʻrt mahsulot orasida “harnessʼning asl mohiyati” bilan eng chuqur bogʻlangan mahsulot boʻlishi mumkin. Butun sohaga nom bergan “Harness Engineering” maqolasining oʻzi OpenAI jamoasining Codex yordamida mahsulot yaratish tajribasi asosida yozilgan. Shuning uchun Codex harness dizaynini tahlil qilish, asosan, oʻsha maqola ortidagi muhandislik amaliyotini tahlil qilish demakdir.++Codex falsafasini bir jumlada ifodalash mumkin: **repo yagona haqiqat manbai (repository as the system of record), AGENTS.md faqat mundarija sahifasi, muhandislikning qadri esa muhitni loyihalash, niyatni ifodalash va qayta aloqa siklini yaratishdadir.**++## Bir jumladagi taʼrif++OpenAI jamoasi Codex yordamida bir necha hafta ichida yakunda millionlab kod qatoridan iborat mahsulot yaratdi va **har bir kod qatorini Codex yozdi** (asl manba: [Harness Engineering](https://openai.com/index/harness-engineering/) maqolasining “Designing for growth” boʻlimi). Ularning tajribasi bitta savolga javob berdi: muhandisning roli “kod yozish”dan “harness loyihalash”ga oʻzgarganda tizim qanday tashkil qilinishi kerak? Codex CLIʼning oʻzi ochiq manbali monolit binar fayl (Rustʼda yozilgan, [github.com/openai/codex](https://github.com/openai/codex)), ammo uning harnessʼga asosiy hissasi bezakdor kengaytma nuqtalarida emas, balki **konvensiyalar (convention)** va **kontekst muhandisligi**dadir.++## Yoʻriqnomalar quyi tizimi: AGENTS.md ensiklopediya emas, mundarija sahifasi++Bu Codexʼning harness nazariyasiga eng katta taʼsir koʻrsatgan dizayn qaroridir:++> Bitta ulkan yoʻriqnoma faylini mexanik tekshirish qiyin: qamrov, yangilanganlik holati, egalik va oʻzaro havolalarni nazorat qilib boʻlmaydi; uning real holatdan chetlashishi muqarrar. Shuning uchun biz AGENTS.mdʼni ensiklopediya emas, **mundarija sahifasi** deb hisoblaymiz. Kod bazasi haqidagi bilimlar tuzilmali hujjatlarda saqlanadi, AGENTS.md esa ularga yoʻl koʻrsatadi.++(Yuqoridagi matn [“Harness Engineering” maqolasining](https://openai.com/index/harness-engineering/) “AGENTS.md should be a directory page” boʻlimidagi fikrning bevosita bayonidir.)++Toʻrtinchi maʼruzada “bitta ulkan yoʻriqnoma fayli muvaffaqiyatsiz boʻladi” deyiladi; Codex esa toʻgʻri yechimni bevosita koʻrsatadi: AGENTS.md taxminan 100 qator bilan cheklanadi (asl maqola qariyb 100 qatorni tavsiya qiladi; chegaraga yaqinlashganda mazmun `docs/` ichiga ajratiladi). Sigʻmagan maʼlumot `docs/` katalogiga boʻlinadi va agent uni talab boʻyicha oʻqiydi. “Qoʻllanmani emas, xaritani bering” tamoyilining nufuzli manbasi aynan shu.++Bunga hamroh tamoyil — **bajarilish invariantlarini belgilang, amalga oshirishni mayda-chuydasigacha boshqarmang** (asl matn: “don't micromanage the implementation; focus on invariants”). AGENTS.md faqat buzib boʻlmaydigan qatʼiy cheklovlar va tekshiruv buyruqlarini oʻz ichiga oladi; qanday amalga oshirishni modelning oʻzi hal qiladi. Bu ikkinchi maʼruzadagi “mayda boshqaruv emas, cheklovlar” gʻoyasiga toʻgʻridan-toʻgʻri mos keladi.++## Kontekst quyi tizimi: Write-Select-Compress-Isolate++Codex kontekst muhandisligini toʻrtta strategiya bilan ifodalash mumkin. Bu model “context engineering” mustaqil sohaga aylangach hamjamiyat tomonidan umumlashtirilib, Codexʼga tatbiq etilgan (model manbasi: [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):++- **Write (yozib qoʻyish)**: kontekstni oynadan tashqarida saqlash — xulosalarni hujjatlarga, holatni fayllarga yozish; ularni suhbat ichida qoldirmaslik. Bu “repo yagona haqiqat manbai” tamoyiliga mos keladi.+- **Select (tanlab olish)**: oynaga faqat zarur tokenlarni olib kirish — AGENTS.md yoʻl koʻrsatadi, fayllar talab boʻyicha oʻqiladi; butun repo kontekstga tiqilmaydi.+- **Compress (siqish)**: faqat haqiqatdan muhim maʼlumotni saqlash — Codexʼda avtomatik siqish va qoʻlda ishga tushiriladigan `/compact` bor; `compact_prompt`ʼni sozlash mumkin (qarang: [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (izolyatsiya qilish)**: kontekstni turli chegaralarga ajratish — subagentlar turli vazifalar kontekstini ajratadi; masalan, frontend subagenti backend maʼlumotlar bazasi schemaʼsini umuman koʻrmaydi.++Codexʼda muhit kontekstiga oid yana bir nozik dizayn mavjud. Hamjamiyatning [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) manba kodi tahliliga koʻra, `build_environment_update_item` har safar toʻliq tizim kontekstini takrorlamaydi, faqat muhit oʻzgarganda **oʻzgargan maydonlarni** (CWD, git branch, fayl tizimi) chiqaradi. Bu “kontekstda takroriy tokenlarni saqlamaslik”ning muhandislik darajasidagi amalga oshirilishidir.++## Vositalar va chegaralar: worktree izolyatsiyasi + subagentlar++Codexʼning ikkita asosiy harness mexanizmi:++**1. Muhitni git worktree bilan izolyatsiya qilish.** [“Harness Engineering” maqolasining](https://openai.com/index/harness-engineering/) “Environment” boʻlimida har bir vazifa mustaqil git worktree ichida bajarilishi aytiladi. U mahalliy kuzatuvchanlik steki (loglar, metrikalar, tracing) bilan birga ishlaydi va har bir oʻzgarishni alohida muhitda tekshirish imkonini beradi. Bu yettinchi maʼruzadagi “agent uchun har bir vazifaning chegarasini aniq belgilang” tamoyilining jismoniy amalga oshirilishidir: chegara yoʻriqnoma bilan iltimos qilish orqali emas, muhit izolyatsiyasi orqali majburan oʻrnatiladi. Bu yerda muhit (environment) quyi tizimi qatʼiy izolyatsiyaga aylantirilgan.++**2. Yadro darajasidagi subagentlar.** Codexʼning `spawn_agent` / `wait_agent` vositalari yadro darajasida ishlaydi: model subagentni bevosita yaratadi, unga mustaqil sessiya tarixi va vositalar toʻplamini beradi hamda natijasini kutadi. Subagent ota agentning AGENTS.md yoʻriqnomalarini meros qilib oladi, lekin **oʻz konteksti**da ishlaydi. Sozlamalar `.codex/agents/*.toml` ichida saqlanadi va ularda turli model hamda yoʻriqnomalarni belgilash mumkin (tafsilotlar: [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) maqolasining Sub-agents boʻlimi). Bu “kontekst izolyatsiyasi”ning bevosita amalga oshirilishi va ayni paytda oʻn ikkinchi maʼruzadagi “topshirish” ruhining ifodasidir: har bir subagent aniq chegaralangan ish birligidir.++## Qayta aloqa quyi tizimi: tekshiruv buyruqlarini standartga kiritish++OpenAI amaliyotidagi eng muhim talab: tekshiruv buyruqlarini AGENTS.md ichida aniq yozish va “toʻgʻri bajarilganini qanday tasdiqlash”ni reponing bir qismiga aylantirish. Codex muhandislik jarayonida testlar, CI, hujjatlar va kuzatuvchanlik sozlamalarining barchasini Codex yaratadi va ularning har biri “bajariladigan tekshiruv yoʻli” hisoblanadi. Model kuchli, ammo ishonchsiz boʻlishi muammosining yechimi model oʻzini nazorat qilishiga umid bogʻlash emas, balki **tekshiruv yoʻlini harnessʼning standart komponentiga aylantirish**dir.++Tasdiqlash siyosatlari (approval policies) va reja rejimi (plan mode) qayta aloqaning boshqa yoʻnalishini taʼminlaydi: xavfli operatsiyani bajarishdan oldin reja tuziladi va tasdiq soʻraladi. Shu tariqa “vazifa chegarasi” va “insonning qaror qabul qilish huquqi” runtime boshqaruviga aylantiriladi.++## Kurs modeliga moslashtirish++| Quyi tizim | Codexʼdagi amalga oshirilishi | Baho |+| --- | --- | --- |+| Yoʻriqnomalar | AGENTS.md mundarija sahifasi + docs/ ichiga ajratish + bajarilish invariantlari | Namunaviy daraja; “qoʻllanmani emas, xaritani bering” tamoyilini belgilab berdi |+| Vositalar | worktree izolyatsiyasi + spawn_agent subagentlari | Chegaralar muhit orqali qatʼiy izolyatsiya qilinadi; juda kuchli |+| Muhit | Mustaqil worktree + kuzatuvchanlik steki | worktree izolyatsiyasi — uning oʻziga xos belgisi |+| Holat | Write strategiyasi (holatni fayl/hujjatlarga yozish) | Ichki xotiradan koʻra konvensiyalarga tayanadi |+| Qayta aloqa | Tekshiruv buyruqlari standart ichida + tasdiqlash siyosatlari + plan mode | Qayta aloqa yoʻli standartlashtirilgan; oʻrganishga arziydi |++Codex va Claude Code taqqoslanishi juda qiziq. Claude Code “qoʻshish” yoʻlini tanlaydi — xotira, ruxsat va subagentlarning barchasini yadroga joylaydi. Codex esa “ayirish” yoʻlidan boradi — yadroni imkon qadar ixcham saqlab, koʻproq masʼuliyatni repo konvensiyalari va kontekst muhandisligiga yuklaydi. Shu sababli hamjamiyatda “Codexʼning harness falsafasi uning kodidan ham qimmatliroq” degan fikr tez-tez uchraydi.++## Oʻrganishga arziydigan dizaynlar++1. **AGENTS.mdʼni mundarija sahifasi sifatida yozing**: uni taxminan 100 qator bilan cheklang, tafsilotlar uchun docs/ ichidagi hujjatlarga yoʻnaltiring va mexanik tekshiruv imkonini saqlang.+2. **Faqat invariantlarni yozing, amalga oshirishni mayda boshqarmang**: qatʼiy cheklovlar + tekshiruv buyruqlari; qolganini modelga qoldiring.+3. **Muhitni worktree bilan izolyatsiya qiling**: vazifa chegarasini yoʻriqnoma bilan iltimos qilish emas, muhit bilan majburlash kerak.+4. **Muhit kontekstining faqat oʻzgarishini uzating**: har safar toʻliq tizim kontekstini qayta kiritmang, faqat oʻzgargan maydonlarni chiqaring.+5. **Kontekstni subagentlar bilan izolyatsiya qiling**: vazifani ajratish bilan birga kontekstni ham ajrating; kichik vazifalar asosiy siklni ifloslantirmasin.++## Manbalar (asl matn / manba kodi)++Har bir daʼvoni taxminlarga emas, quyidagi asl matn yoki manba kodiga bogʻlash mumkin:++- **OpenAI “Harness Engineering”**: AGENTS.md mundarija sahifasi va taxminan 100 qatorlik tavsiya, executive invariants / don't micromanage, worktree izolyatsiyasi + kuzatuvchanlik steki, tekshiruv buyruqlarini standartga kiritish, millionlab qatorli mahsulot misoli, tasdiqlash siyosatlari va plan mode. Ushbu maqoladagi barcha asosiy daʼvolarning bosh manbasi.<br/>https://openai.com/index/harness-engineering/+- **OpenAIʼning rasmiy “AGENTS.md” standarti** (AGENTS.mdʼning turli vositalar uchun umumiy konvensiyasi):<br/>https://openai.com/index/agents-md/+- **Codex CLI ochiq manbali reposi** (Rustʼda yozilgan monolit binar fayl):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (hamjamiyat): Write-Select-Compress-Isolate modeli, `/compact` va `compact_prompt`, `spawn_agent` / `wait_agent` subagentlari hamda `.codex/agents/*.toml` sozlamalari.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (hamjamiyatning manba kodi tahlili): `build_environment_update_item` orqali muhit kontekstining oʻzgarishlarini uzatish kabi amalga oshirish tafsilotlari.<br/>https://github.com/AlexKenbo/codex-harness-internals++Tegishli maʼruzalar: [3-maʼruza · Kod reposini yagona haqiqat manbaiga aylantirish](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [4-maʼruza · Yoʻriqnomalarni turli fayllarga ajratish](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [7-maʼruza · Agent uchun har bir vazifaning chegarasini aniq belgilash](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/uz/harness-designs/deepseek/index.md b/docs/uz/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..66b5d84--- /dev/null+++ b/docs/uz/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# DeepSeek Harness dizayni tahlili++[DeepSeek Harness](https://deepseek.com/harness) (`dsh` buyrugʻi, `deepseek-ai/deepseek-harness` reposi) 2026-yil avgustida Developer Preview shaklida chiqarildi. Rasmiy taʼrif juda toʻgʻridan-toʻgʻri: **Agent = Model + Environment + Tools + State** — model, muhit, vositalar va holat; toʻrtlik toʻplam.++Agar oldingi uchta mahsulot tahlili “harness qanday loyihalanishi kerak?” degan savolni bersa, DeepSeek Harness yanada keskin savol qoʻyadi: **harness muayyan modeldan ajralib, mustaqil runtime boʻla oladimi?** Uning javobi — ha, va u bu gʻoyani eng oxirgi nuqtasigacha olib boradi. [Arxitektura hujjatidagi](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) asl ibora: *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* (mahsulotning har bir qismi — model adapteri, vositalar registri, sessiya logi va hatto agent siklining oʻzi ham — plagindir).++Ushbu maqolada uch jihatga asosiy eʼtibor qaratamiz: plaginli yadro, imkoniyat tutashuvi (capability seam), hodisalar pipelineʼi hamda eng kuchli muhandislik cheklovi — “Model-visible means logged”.++## Bir jumladagi taʼrif++Anʼanaviy coding agent tuzilishi “LLM + oʻzgarmas agent sikli + oʻzgarmas vositalar toʻplami”dan iborat. DeepSeek Harness tuzilishi esa “model + plagin yadrosi (Cordis)”dir. Yadro faqat plaginlarni yuklash, tushirish, bogʻliqliklar va hodisalar mexanizmini boshqaradi; u **agentning hech qanday muayyan imkoniyatiga egalik qilmaydi**. [Arxitektura hujjatidagi](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) asl iboralar: “There is no privileged core to patch” (patch qilish kerak boʻlgan imtiyozli yadro yoʻq) va “you extend dsh by mounting a plugin beside the others” (yadroni oʻzgartirmasdan, boshqalari yoniga plagin ulash orqali dshʼni kengaytirasiz). Demak, hatto agent siklining oʻzi ham daxlsiz emas: DeepSeek modelini ishlatish, unga Claude Code subagentlarini ulash, masofaviy sandbox qoʻshish, maxsus xotira yozish, maxsus sikl yoki UI bilan almashtirish va bularning barchasidan mutlaqo yangi agent yigʻish mumkin.++Bu kursdagi “model ogʻirliklaridan tashqaridagi barcha narsa harness” iborasining eng toʻliq amalga oshirilishidir: harness mustaqil boʻlsa, uni mustaqil operatsion tizimga aylantirish mumkin.++## Arxitektura yadrosi 1: imkoniyat tutashuvi (Capability Seam)++DeepSeek Harness “imkoniyat”ni Service orqali ifodalaydi va deyarli har bir imkoniyatni uch qatlamga ajratadi:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Masalan, fayl tizimida `FS Service` ostida Local FS, E2B FS va Remote FS kabi bir nechta Provider mavjud; yuqorida esa ular yagona file tools koʻrinishida ochiladi. Shell, Subprocess, Sandbox, Web, LLM va SubAgent ham ayni tuzilishga ega. Ushbu uch qatlamli tuzilma bizning xulosamiz emas. [Arxitektura hujjatining Capability seams boʻlimida](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) aynan shunday yozilgan: *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* (imkoniyat tutashuvi — uchta roldan iborat almashtiriladigan imkoniyat: interfeysni eʼlon qiluvchi Service Definition, uni amalga oshiruvchi Service Provider va undan foydalanuvchi Consumer; oxirgisi odatda modelga koʻrinadigan vosita boʻladi).++Bu harness muhandisligidagi uzoq yillik muammoni hal qiladi: **agent “muayyan vosita”ga tayanishi kerakmi yoki “imkoniyat interfeysi”gami?** DeepSeek Harness ikkinchisini tanlaydi. Kurs nuqtayi nazaridan, bu “vositalar quyi tizimi” interfeys sifatida standartlashtirilganini anglatadi: Provider almashtirilsa, modelga ochiladigan vosita koʻrinishi oʻzgarmaydi, ammo muhit butunlay almashadi.++## Arxitektura yadrosi 2: hodisalar pipelineʼi (Event Pipeline)++DeepSeek Harness ichki tuzilishi oddiy “LLM → vosita → LLM” emas. U hodisalar pipelineʼidan iborat boʻlib, har bir bosqich plagin tinglashi mumkin boʻlgan hodisa nuqtasidir:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(Yuqoridagi pipeline [arxitektura hujjatining Turn flow boʻlimidagi](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) maʼlumotning qayta bayonidir: `turn/*`, `step/*`, `user/message`, `assistant/*`, `tool/*` — doimiy saqlanadigan sessiya hodisalari; `agent/pre-step`, `agent/request`, `llm/stream`, `tools/*` esa plaginlar tinglashi mumkin boʻlgan kengaytma nuqtalaridir.)++Bu dizaynning eng katta afzalligi: **koʻplab funksiyalar uchun agent siklining oʻzini oʻzgartirish shart emas**. Vositani bajarishdan oldin xavfsizlik tekshiruvi kerakmi? `tools/pre-execute`ʼni tinglang. Xotira qoʻshmoqchimisiz? `agent/pre-step`ʼda maʼlumot kiriting. Xatti-harakatlarni yozmoqchimisiz? Session hodisalariga obuna boʻling. Model soʻrovini oʻzgartirmoqchimisiz? `agent/request`ʼga hook ulang. Fikrlashni davom ettirish kerakligini aniqlamoqchimisiz? `agent/turn-stopping`ʼni tinglang.++Kursning oʻn birinchi maʼruzasidagi “agent ish jarayonini kuzatiladigan qiling” gʻoyasi bilan taqqoslaganda, DeepSeek Harness yanada uzoqqa boradi: u shunchaki “log qoʻshmaydi”, balki **siklning har bir qadamini hodisa nuqtasiga aylantiradi**. Shu tariqa kuzatuvchanlik, ruxsat, xotira va siyosat siklga qotirib yozilmaydi, balki tinglovchi sifatida ulanadi.++## Arxitektura yadrosi 3: Session Event Log va “Model-visible means logged”++DeepSeek Harnessʼda **append-only Session Event Log (faqat qoʻshib boriladigan sessiya hodisalari logi)** mavjud va juda kuchli muhandislik cheklovi belgilangan. [Arxitektura hujjatining Session log boʻlimidagi](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) asl matn:++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Model koʻra oladigan barcha narsa logga yozilishi shart. Model soʻroviga yetib kelgan har qanday narsani logdan qayta tiklash mumkin boʻlishi kerak va runtime invarianti buni majburan tekshiradi.)++Boshqacha aytganda, kuzatuvchanlik keyin qoʻshiladigan log emas, harnessʼning birlamchi cheklovidir: model kontekstiga kirgan har qanday narsa sukut boʻyicha logda qolishi kerak. Bu yakuniy maʼruzadagi “kuzatuvchanlik harness ichida boʻlishi kerak” gʻoyasiga toʻgʻridan-toʻgʻri mos keladi va “append-only” saqlash dizaynini tamoyilga aylantiradi: loglar faqat qoʻshiladi, qayta yozilmaydi; sessiya holatini qayta ijro qilish mumkin.++## Kurs modeliga moslashtirish++| Quyi tizim | DeepSeek Harnessʼdagi amalga oshirilishi | Baho |+| --- | --- | --- |+| Yoʻriqnomalar | Plaginlashtirilgan; qoidalar/koʻnikmalar plagin sifatida kiritiladi | Juda erkin, ammo ichki “CLAUDE.md”ga oʻxshash konvensiya yoʻq |+| Vositalar | Service Definition → Provider → Consumer imkoniyat tutashuvi | Vositalar quyi tizimini standartlashtirishning eng oxirgi nuqtasi |+| Muhit | Sandbox/FS/Shell Providerʼlari toʻliq almashtiriladi (masofaviy E2B ham) | Muhit toʻliq ulanadigan va almashtiriladigan |+| Holat | append-only Session Event Log + Model-visible means logged | Kuzatuvchanlik — birlamchi cheklov |+| Qayta aloqa | tools/pre-executeʼdagi permission / guard / policy / hook | Qayta aloqa mexanizmi hodisalarga aylantirilgan |++DeepSeek Harnessʼning qolgan uch mahsulotdan tub farqi: Pi, Claude Code va Codex harnessʼni “muayyan agent” ichida takomillashtiradi; DeepSeek Harness esa harnessʼni **modeldan mustaqil operatsion tizim** sifatida belgilaydi, agentning oʻzi esa ushbu OS ichidagi almashtiriladigan ilova xolos. Buning narxi ham ayon: yuqori erkinlik yuqori sozlash xarajatini anglatadi. Bu “harness — OS” dizaynining tabiiy ikkinchi tomonidir (Developer Preview bosqichi ham “erta sinab koʻrish, mexanizmlar hali rivojlanmoqda” tarzida taqdim etilgan).++## Oʻrganishga arziydigan dizaynlar++1. **Siklning har bir qadamini hodisa nuqtasiga aylantiring**: ruxsat, xotira, siyosat va loglarni siklga qotirib yozmang; ularni tinglovchi sifatida ulang.+2. **Imkoniyat tutashuvlarini standartlashtiring**: “muayyan vosita”ga emas, “imkoniyat interfeysi”ga tayaning; model koʻradigan vositalar qatlami oʻzgarmasdan muhitni toʻliq almashtirish mumkin boʻlsin.+3. **Model-visible means logged**: model koʻra oladigan barcha narsa yozib borilishi shart; kuzatuvchanlikni “qoʻshimcha afzallik”dan “birlamchi cheklov”ga aylantiring.+4. **append-only sessiya logi**: holatni qayta ijro qilish va ishonchli topshirish imkonini beradi; bu “har bir sessiyadan keyin toza holat qoldirish”ning muhandislik kafolatidir.++## Manbalar (asl matn / manba kodi)++Har bir daʼvoni taxminlarga emas, quyidagi asl matn yoki manba kodiga bogʻlash mumkin:++- **DeepSeek Harness rasmiy sayti**: mahsulotning “Agent = Model + Environment + Tools + State” taʼrifi, Developer Preview maqomi va `dsh` buyrugʻi.<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness reposi** (`dsh` buyrugʻi, MIT litsenziyasi):<br/>https://github.com/deepseek-ai/deepseek-harness+- **architecture.md arxitektura hujjati**: ushbu maqolaning asosiy manbasi — “Every part of the product is a plugin”, “There is no privileged core to patch”, Turn flow hodisalar pipelineʼi, Capability seams uch qatlamli rollari, “Model-visible means logged” va runtime invarianti, append-only Session Event Log, fs/tools/telemetry kabi imkoniyat tutashuvlari hamda `ctx.*` quyi tizimlari.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **Arxitektura hujjatining qoʻshimcha hujjatlari**: Cordis yadrosiga kirish (plugins contribute services, typed events, reversible effects), imkoniyat tutashuvlari tafsilotlari va Session quyi tizimi.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Tegishli maʼruzalar: [11-maʼruza · Agent ish jarayonini kuzatiladigan qilish](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [12-maʼruza · Har bir sessiya tugashidan oldin topshirishni tayyorlash](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [2-maʼruza · Harness aslida nima?](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/uz/harness-designs/index.md b/docs/uz/harness-designs/index.mdnew file mode 100644index 0000000..865ba6b--- /dev/null+++ b/docs/uz/harness-designs/index.md@@ -0,0 +1,29 @@+# Ilgʻor harness dizaynlari tahlili++Bu rukn kurs maʼruzalarida bayon qilingan harness nazariyasini hozirgi eng ilgʻor real mahsulotlar bilan birma-bir taqqoslaydi. Har bir mahsulotda bizni faqat bir narsa qiziqtiradi: **uning harnessʼi qanday loyihalangan** — yaʼni model atrofidagi muhandislik infratuzilmasi: yoʻriqnomalar, vositalar, muhit, holat va qayta aloqa kabi beshta quyi tizim, shuningdek kontekst uzluksizligi, inisializatsiya, tekshiruv, kuzatuvchanlik, topshirish va sikl kabi asosiy mexanizmlar.++Biz ataylab modelning fikrlash qobiliyati kuchlimi yoki yoʻqmi, muayyan benchmark natijasi yuqorimi yoki yoʻqmi degan mavzularni muhokama qilmaymiz. Shuningdek, “bu agent nima qila oladi” degan umumiy tanishtiruvni ham bermaymiz. Bular model va mahsulot qatlamlariga oid masalalar. Bu yerda faqat harness — model ogʻirliklaridan tashqaridagi barcha narsalar — tahlil qilinadi.++## Nega tahlil qilishga arziydi++Birinchi maʼruzada aytilganidek, modelning kuchli boʻlishi bajarilishning ishonchli boʻlishini anglatmaydi. Bir xil model turli harness ichida ishlatilsa, natijalar bir daraja miqyosida farq qilishi mumkin. Ammo maʼruzalar “qanday qilish kerak”ligini tushuntirsa, bu mahsulotlar “yetakchi jamoalar amalda qanday qilmoqda” degan savolga javob beradi.++Har bir mahsulot — mustaqil dizayn qarorlari toʻplami. Ularni yonma-yon taqqoslasangiz, ayni asosiy mexanizmlarni turli jamoalar mutlaqo boshqacha usullarda amalga oshirganini koʻrasiz:++- **Pi** harnessʼni minimal yadro + dasturlashtiriladigan kengaytmalar shaklida quradi va “minimal system prompt + talab boʻyicha yuklash” orqali kontekst muhandisligini amalga oshiradi.+- **Claude Code** harnessʼni toʻliq runtime muhitiga aylantiradi: qatlamli xotira, besh bosqichli siqish, ruxsatlar, hookʼlar va subagentlar.+- **Codex** harness falsafasini eng oxirgi nuqtasigacha olib boradi: repo yagona haqiqat manbai, AGENTS.md esa faqat mundarija sahifasi; muhit worktree yordamida izolyatsiya qilinadi.+- **DeepSeek Harness** harnessʼning oʻzini modeldan mustaqil runtime sifatida belgilaydi: Everything is a Plugin.++## Maqolalar roʻyxati++- [Pi harness dizayni tahlili](./pi/): minimal yadro + dasturlashtiriladigan kengaytmalar; kontekst muhandisligi system prompt tashqarisiga olib chiqilgan.+- [Claude Code harness dizayni tahlili](./claude-code/): qatlamli xotira, besh bosqichli siqish, ruxsatlar va hookʼlar — toʻliq agent runtime muhiti.+- [Codex harness dizayni tahlili](./codex/): repo yagona haqiqat manbai, AGENTS.md mundarija sahifasi, muhit izolyatsiyasi va qayta aloqa sikli.+- [DeepSeek Harness dizayni tahlili](./deepseek/): Everything is a Plugin; hatto agent siklining oʻzi ham almashtiriladigan plaginga aylantirilgan.++## Qanday oʻqish kerak++Avval beshta quyi tizim modelini tushunib olish uchun maʼruzalarning dastlabki qismlarini (ayniqsa [2-maʼruza: Harness aslida nima?](../lectures/lecture-02-what-a-harness-actually-is/)) oʻqishni, soʻng real mahsulotlar bu mexanizmlarni qanday amalga oshirganini koʻrish uchun bu yerga qaytishni tavsiya qilamiz.++Har bir maqola oxirida “Kurs modeliga moslashtirish” va “Oʻrganishga arziydigan dizaynlar” boʻlimlari bor. Ular mahsulot dizaynini kurs tushunchalariga tezda aylantirish va bevosita oʻz loyihangizga tatbiq etishga yordam beradi.diff --git a/docs/uz/harness-designs/pi/index.md b/docs/uz/harness-designs/pi/index.mdnew file mode 100644index 0000000..9d351c7--- /dev/null+++ b/docs/uz/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Pi harness dizayni tahlili++[Pi](https://pi.dev/) (`@earendil-works/pi-coding-agent` npm paketi) oʻzini “minimal agent harness” — minimal agent harness deb ataydi. Bu iborani qismlarga ajratib oʻqishga arziydi: u oʻzini “eng kuchli coding agent” yoki “foydalanish uchun eng qulay AI dasturlash vositasi” demaydi, balki oʻz oʻrnini qatʼiy ravishda **harness** soʻzi bilan belgilaydi.++Ushbu maqolada Piʼni kursning beshta quyi tizimli modeli — yoʻriqnomalar, vositalar, muhit, holat va qayta aloqa — orqali tahlil qilamiz hamda uning dizayn falsafasi Claude Code va Codexʼdan tubdan nimasi bilan farq qilishini koʻramiz. Javobni oldindan aytamiz: **Pi falsafasi “yadroni minimallashtirish + kengaytmalarni dasturlashtirish”dan iborat. U kontekst muhandisligini system prompt tashqarisiga olib chiqadi va harnessʼni Pi siz uchun belgilashi oʻrniga, foydalanuvchiga (hatto Piʼning oʻziga) oʻzgartirish imkonini beradi.**++## Bir jumladagi taʼrif++Pi — minimal yadro: rasmiy pozitsiya yadroni ataylab kichik saqlab, qaror qabul qilish huquqini sizga qaytaradi. [pi.dev bosh sahifasidagi](https://pi.dev/) asl ibora: “Ask Pi to build what you want, or install a package that does it your way”. U harnessʼni sozlanadigan toʻrt qatlamga ajratadi:++- **Kengaytmalar (Extensions)**: Pi lifecycle hodisalariga ulanadigan TypeScript hookʼlari; runtime darajasidagi dasturlashtiriladigan qatlam.+- **Koʻnikmalar (Skills)**: yoʻriqnomalar va vositalarni oʻz ichiga olgan, talab boʻyicha yuklanadigan imkoniyat paketlari; progressive disclosure.+- **Prompt andozalari (Prompt templates)**: `/name` kiritilganda ochiladigan, qayta ishlatiladigan Markdown promptlar.+- **Mavzular (Themes)**: TUI koʻrinishi.++Bu qatlamlash gʻoyasining oʻzi harness dizaynidir: **“model nimani koʻradi va qachon koʻradi” degan qaror yadroga qotirib qoʻyilmaydi, balki toʻliq qoidalar va kengaytmalarga topshiriladi.**++## Asosiy sikl++Barcha coding agentlar singari Piʼning mohiyati ham “fikrlash → vositani bajarish → kuzatish → qayta fikrlash” while siklidir. Eʼtiborga molik jihat siklning oʻzi emas, Piʼning uning tashqi qatlamiga munosabatidir: u kontekst boshqaruvini sikl ichidagi “siqish”dan sikl tashqarisidagi “boshqarish”gacha kengaytiradi.++Pi runtimeʼi dasturlashtiriladigan interfeysni tashqariga ochadi. [Manba kodi README faylining Programmatic Usage boʻlimida](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) interaktiv TUIʼdan tashqari skript orqali boshqariladigan print/JSON rejimlari, RPC protokoli va SDK ichiga joylash qoʻllab-quvvatlanadi. Shu sababli ayni harnessʼni inson qadamma-qadam boshqarishi ham, CI/CD yoki boshqa dastur avtomatik boshqarishi ham mumkin. Bu oʻn uchinchi maʼruzadagi “sikl muhandisligi”ning “qoʻlda boshqarishdan avtomatik siklga oʻtish” shartiga mos keladi: agar harnessʼni faqat inson interaktiv boshqara olsa, u hech qachon avtomatik siklga kira olmaydi.++## Yoʻriqnomalar quyi tizimi: AGENTS.md va SYSTEM.md++Pi “yoʻriqnomalar” bilan vazmin ishlaydi, ammo qatlamlari aniq:++- **AGENTS.md**: [manba kodi README faylining Project Context Files boʻlimida](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) yuklash tartibi aniq berilgan — global `~/.pi/agent/AGENTS.md` → ota kataloglar boʻylab yuqoriga yurish → joriy katalogdagi `./AGENTS.md` (CLAUDE.md ham qoʻllab-quvvatlanadi). Bu “repo yagona haqiqat manbai” tamoyilining amaliy ifodasi: yoʻriqnoma suhbat oynasidagi eslatma emas, fayldir.+- **SYSTEM.md**: [pi.dev rasmiy hujjatiga](https://pi.dev/docs/usage/project-context) koʻra, loyiha standart system promptʼni almashtirishi (replace) yoki unga qoʻshimcha kiritishi (append) mumkin. Bu Piʼda “system prompt”ni oʻzgartirishning yagona rasmiy kirish nuqtasi va uning “muhitning oʻzini tavsiflashi” qatlamidir.++Pi rasmiy ravishda system promptʼining oʻzi **minimal** ekanini taʼkidlaydi. Bu aniq murosaga asoslanadi: yadro ichiga uzun “agar… unda…” qoidalari tiqilmaydi; buning oʻrniga kengaytma nuqtalari qoldiriladi va qoidalar faqat kerak boʻlganda koʻnikma hamda kengaytma shaklida paydo boʻladi. Bu toʻrtinchi maʼruzadagi “nima uchun bitta ulkan yoʻriqnoma fayli muvaffaqiyatsiz boʻladi” mavzusiga bevosita mos keladi: Pi “minimal yadro + fayllarga ajratish + talab boʻyicha yuklash” yordamida ulkan yoʻriqnoma muammosini tabiiy ravishda chetlab oʻtadi.++## Holat va kontekst: Pi eng mayda qismlarga ajratgan soha++Piʼning kontekst muhandisligi alohida tahlilga loyiq, chunki u kursdagi “kontekst uzluksizligi” va “kontekst buzilishining oldini olish” tushunchalarini aniq mexanizmlarga aylantiradi:++**1. Siqish (Compaction) dasturlashtiriladi.** Kontekst chegarasiga yaqinlashganda eski xabarlar avtomatik umumlashtiriladi. [pi.dev rasmiy hujjatida](https://pi.dev/docs/usage/sessions) siqish strategiyasining oʻzi **sozlanishi mumkinligi** aytiladi: kengaytma yordamida mavzuga asoslangan siqish, kodni hisobga oladigan xulosa yoki hatto xulosa yozish uchun boshqa modelni ishlatish mumkin. Manba kodi README faylida standart mexanizm tafsilotlari ham bor: avtomatik siqish ikki holatda ishga tushadi (kontekst toshib ketishidan tiklanish / saqlash chegarasidan oshish). Kesish nuqtasi eng soʻnggi qariyb 20 ming tokenni saqlaydi, undan oldingi xabarlar “context handoff” shaklida umumlashtirilib, bosqichma-bosqich zanjirli siqiladi. Demak, Pi “qanday siqish”ni oʻzgarmas konstanta emas, harnessʼning bir qismi deb biladi.++**2. Dinamik kontekst (Dynamic context).** [pi.dev rasmiy hujjatiga](https://pi.dev/docs/usage/extensions) koʻra, kengaytmalar har bir fikrlash bosqichidan oldin xabar kiritishi, xabarlar tarixini filtrlashi, RAGʼni amalga oshirishi va uzoq muddatli xotira qurishi mumkin. Bu “kontekst toʻlgach siqish”dan bir qadam oldinda: maʼlumot kontekst oynasiga kirishidan oldin nimani kiritish va nimani kiritmaslikni tanlash imkonini beradi. Bu kursdagi “agent ish jarayonini kuzatiladigan va debug qilinadigan qilish” hamda “kontekst uzluksizligini saqlash” gʻoyalariga mos keladi; Pi ikkisini ham kengaytma qatlamiga tushiradi.++**3. Sessiya daraxti (Session tree).** [pi.dev bosh sahifasida](https://pi.dev/) “sessiyalar daraxt shaklida saqlanadi (sessions are stored as trees), `/tree` orqali tarixdagi istalgan tugunga qaytib davom etish mumkin va barcha tarmoqlar bitta faylda saqlanadi” deb aniq yozilgan. Bu kursda qayta-qayta taʼkidlangan “sessiyalararo kontekst uzilishi” muammosini hal qiladi: qattiq siqilgan xulosa orqali emas, tuzilmali tarixni qayta ijro qilish orqali. Tarmoqlarni HTMLʼga eksport qilish yoki gist sifatida ulashish mumkin, natijada kuzatuvchanlik ham bir yoʻla taʼminlanadi.++## Vositalar quyi tizimi: koʻnikmalar va kengaytmalar++Piʼning “vositalari” ikki qatlamdan iborat:++- **Koʻnikmalar (Skills)**: [manba kodi README faylining Skills boʻlimida](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) aniq “self-contained capability packages that the agent loads on-demand” deb taʼriflanadi. Yaʼni ular yoʻriqnoma va vositalarni oʻz ichiga olgan, Agent Skills standartiga mos, talab boʻyicha yuklanadigan imkoniyat paketlaridir. Progressive disclosure sababli koʻnikma tafsilotlari faqat trigger boʻlganda kontekstga kiradi va **prompt cacheʼni toʻldirib yubormaydi**. Bu xarajat nuqtayi nazaridan harness dizaynidir: kontekstdagi har bir qoʻshimcha token uchun har bir fikrlash bosqichida haq toʻlanadi. Koʻnikmalarni talab boʻyicha yuklash — “qoʻllanmani emas, xaritani bering” gʻoyasining yana bir ifodasi.+- **Kengaytmalar (Extensions)**: ichki lifecycle hodisalariga ulanadigan TypeScript hookʼlari. [Manba kodi README faylining Hooks boʻlimida](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) toʻrtta rasmiy foydalanish namunasi berilgan: xavfli buyruqlarni toʻxtatish (ruxsat darvozasi), vazifa almashganda kod holatini checkpoint qilish, yoʻllarni himoya qilish (`.env` fayliga yozishni taqiqlash va hokazo), vosita natijasini modelga berishdan oldin oʻzgartirish hamda agentni uygʻotish uchun tashqaridan (fayl kuzatuvchisi/Webhook/CI) xabar kiritish. Bu hook APIʼlari `@mariozechner/pi-coding-agent/hooks` orqali ham eksport qilinadi. Hamjamiyat harnessʼi ([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness)) esa hook qatlamini skill-router, session-summary, extract-patterns va telemetry kabi tayyor kengaytmalarga aylantiradi.++Kengaytmalar Piʼning eng muhim dizayn qaroridir: **u “foydalanuvchiga bir nechta tugma berish” bilan cheklanmaydi, balki runtime ichidagi barcha hodisalarni tashqariga ochadi.** Xotira qoʻshmoqchimisiz? `agent/pre-step`ʼda maʼlumot kiriting. Xatti-harakatlarni yozmoqchimisiz? Session hodisalariga obuna boʻling. Model soʻrovini oʻzgartirmoqchimisiz? `agent/request`ʼga hook ulang. Hatto Piʼga oʻz harnessʼini oʻzgartirish imkonini berishingiz mumkin — bu har qanday “sozlama bandi”dan koʻra “dasturlashtiriladigan harness” taʼrifiga yaqinroq.++## Qayta aloqa va tekshiruv: “oʻrganish” ham harnessʼga aylantiriladi++Piʼning oʻzida majburiy test darvozasi yoʻq (tekshiruv buyruqlarini foydalanuvchi AGENTS.md ichida yozishi kerak), ammo hamjamiyat harnessʼi ([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness)) “qayta aloqa sikli”ni kengaytmalar yordamida tuzilmalashtirgan. Rasmiy README faylining Hooks boʻlimi ham shunga oʻxshash mexanizmlar uchun asos beradi:++- **session-summary** (pi-agent-harness kengaytmasi): `PROGRESS.md` ichidagi yangilanib boradigan yozuvlarni saqlaydi — bu kursdagi holat quyi tizimi, yaʼni uzoq vazifalar jarayonini kuzatishdir.+- **extract-patterns** (pi-agent-harness kengaytmasi): sessiyadan oʻrganilgan saboqlar uchun nomzodlarni yigʻib, `LESSONS.md`ʼga saqlaydi — “har bir sessiya tugashidan oldin topshirishni tayyorlash”ni kelishuvdan mexanizmga aylantiradi.+- **telemetry** (pi-agent-harness kengaytmasi): token sarfi, xarajatlar va boshqa koʻrsatkichlarni yozadi — kuzatuvchanlik.++Ayni hamjamiyat reposi bu modelni yanada tasdiqlaydi: `VISION.md` (maqsad), `PROGRESS.md` (jarayon), `LESSONS.md` (saboqlar), `STANDARDS.md` (standartlar) — barchasi Markdown fayllari va sessiyalar orasida doimiy saqlanadi. Bu kurs tavsiya qilgan “repo yagona haqiqat manbai + jarayon fayli + topshirish mexanizmi” modelining aynan oʻzi, faqat Pi kengaytma mexanizmi uni foydalanishga tayyor qatlamga aylantirgan.++## Kurs modeliga moslashtirish++Kursning beshta quyi tizimi boʻyicha Piʼning bahosi (subyektiv, taqqoslash uchun):++| Quyi tizim | Piʼdagi amalga oshirilishi | Baho |+| --- | --- | --- |+| Yoʻriqnomalar | AGENTS.mdʼni darajalar boʻyicha yuklash + SYSTEM.md | Qatlamlar aniq, ammo qoidalarni foydalanuvchining oʻzi yozadi |+| Vositalar | Koʻnikmalarni talab boʻyicha yuklash + kengaytmalarning toʻliq lifecycle hookʼlari | Juda kuchli; vositalar tizimi dasturlashtiriladigan qatlamga aylantirilgan |+| Muhit | SYSTEM.md muhitni oʻzi tavsiflaydi; runtime muhiti AGENTS.md ichida foydalanuvchi tomonidan eʼlon qilinadi | Mexanizm ochiq, ammo qayta yaratiluvchanlik foydalanuvchi tavsifiga bogʻliq |+| Holat | Sessiya daraxti + sozlanadigan siqish + PROGRESS.md | Juda kuchli; sessiyalararo ishlash va tiklanish uning asosidir |+| Qayta aloqa | Tekshiruv buyruqlarini foydalanuvchi belgilaydi; session-summary / extract-patterns mexanizmlari | Mexanizm berilgan, mazmun foydalanuvchiga bogʻliq |++Pi tanlagan murosa Claude Code / Codexʼdan keskin farq qiladi. Claude Code “xotira, ruxsatlar, subagentlar”ning barchasini yadroga joylab, foydalanishga tayyor holatda beradi. Codex “repo standartlari va muhit izolyatsiyasi”ni standart qiladi. Pi esa **siz uchun hech narsani hal qilmaslik**ni tanlaydi — qaror qabul qilish imkonini kengaytma nuqtalariga aylantiradi. Buning evaziga kengaytmani oʻzingiz yozishingiz yoki boshqalar yaratgan paketni oʻrnatishingiz kerak.++## Oʻrganishga arziydigan dizaynlar++1. **Siqish strategiyasini ulanadigan qiling.** harnessʼingizda “kontekst qanday siqiladi” degan savolga qotirib qoʻyilgan parametr emas, almashtiriladigan strategiya interfeysi javob berishi kerak.+2. **Qattiq umumlashtirish oʻrniga sessiya daraxtidan foydalaning.** Sessiyalararo tiklanish har doim ham “oldingi sessiya xulosasi”ga tayanishi shart emas; tuzilmali tarixni qayta ijro qilish koʻpincha ishonchliroq holat quyi tizimidir.+3. **Prompt cache bilan samarali ishlang.** Koʻnikmalarni talab boʻyicha yuklang, barcha qoidalarni birdan system promptʼga tiqmang; bu ham kontekst, ham xarajat muhandisligidir.+4. **Agentga oʻz harnessʼini oʻzgartirish imkonini bering.** harness kengaytma qatlami yetarlicha ochiq boʻlsa, “agent xatti-harakatini yaxshilash”ni agentning oʻzi yarim avtomatik bajarishi mumkin.++## Manbalar (asl matn / manba kodi)++Har bir daʼvoni taxminlarga emas, quyidagi asl matn yoki manba kodiga bogʻlash mumkin:++- **pi.dev rasmiy sayti**: “Ask Pi to build what you want, or install a package that does it your way” degan asl pozitsiya, toʻrtta sozlanadigan qatlam, sessiya daraxti (“sessions are stored as trees”, `/tree`, bitta faylda saqlash, HTMLʼga eksport qilish / gist orqali ulashish).<br/>https://pi.dev/+- **pi.dev rasmiy hujjati · Sessions**: ulanadigan siqish (topic-based / code-aware / xulosa modelini almashtirish), avtomatik siqish va dinamik kontekst kiritish mexanizmlari.<br/>https://pi.dev/docs/usage/sessions+- **pi.dev rasmiy hujjati · Extensions**: kengaytmalar har bir fikrlash bosqichidan oldin xabar kiritishi, tarixni filtrlashi, RAG yaratishi va uzoq muddatli xotira qurishi mumkin.<br/>https://pi.dev/docs/usage/extensions+- **pi.dev rasmiy hujjati · Project Context**: SYSTEM.mdʼning replace / append semantikasi.<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent manba kodi README fayli** (badlogic/pi-mono): AGENTS.mdʼning uch bosqichli yuklash tartibi (global → ota katalog → joriy katalog), `/compact` va avtomatik siqishning ishga tushish shartlari hamda 20 ming tokenlik kesish nuqtasi, Skillsʼni talab boʻyicha yuklash va Agent Skills standarti, Hooks lifecycleʼi va toʻrtta rasmiy foydalanish namunasi, Programmatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness hamjamiyat reposi**: skill-router / session-summary / extract-patterns / telemetry kengaytmalari, VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md fayl tizimi.<br/>https://github.com/LabidySabidy/pi-agent-harness++Tegishli maʼruzalar: [2-maʼruza · Harness aslida nima?](../lectures/lecture-02-what-a-harness-actually-is/) | [5-maʼruza · Sessiyalararo vazifalarda kontekst uzluksizligini saqlash](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [13-maʼruza · Qoʻlda boshqarishdan avtomatik siklga oʻtish](../lectures/lecture-13-loop-engineering/)diff --git a/docs/uz/index.md b/docs/uz/index.mdindex 4c8e825..4d5de10 100644--- a/docs/uz/index.md+++ b/docs/uz/index.md@@ -26,6 +26,10 @@ Oʻqish yoʻlingizni tanlang. Kurs uch qismdan iborat: nazariy maʼruzalar, amal<h3>Resurslar kutubxonasi</h3><p>Oʻz repozitoriyalaringizda foydalanish uchun tayyor andozalar (AGENTS.md, feature_list.json).</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Ilgʻor harness dizaynlari tahlili</h3>+ <p>Pi, Claude Code, Codex va DeepSeek oʻz harness'larini qanday loyihalashini kurs ramkasiga bogʻlab tahlil qiling.</p>+ </a></div>## Harnessʼning asosiy mexanizmidiff --git a/docs/vi/harness-designs/claude-code/index.md b/docs/vi/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..d4d2af5--- /dev/null+++ b/docs/vi/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# Phân tích thiết kế harness của Claude Code++Trong bài viết “[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)”, Anthropic nêu rõ: độ tin cậy đến từ harness chứ không phải mô hình; agent cần được ràng buộc ở “bên ngoài mô hình”. Claude Code là một sản phẩm hóa của tư tưởng này, và Anthropic cũng trực tiếp xếp nó vào phạm trù **agentic harness**. Đây không phải lời quảng bá — Claude Code có lẽ là harness hiện được phân tích công khai kỹ lưỡng nhất: mã nguồn mở, báo cáo nghiên cứu của cộng đồng chi tiết, và gần như mọi cơ chế cốt lõi trong giáo trình (bộ nhớ phân tầng, nén ngữ cảnh, quyền hạn, hook, agent con, duy trì phiên) đều đã được triển khai thành sản phẩm hoàn chỉnh.++Trong bài này, chúng ta dùng khung năm hệ thống con của khóa học để phân tích Claude Code, tập trung vào cách nó hiện thực hóa những khái niệm nền tảng của harness như “quản lý ngữ cảnh”, “ngăn tuyên bố hoàn thành quá sớm” và “ràng buộc tất định”.++## Định vị trong một câu++Cốt lõi của Claude Code là một vòng lặp while đơn giản: gọi mô hình, thực thi công cụ, quan sát kết quả rồi gọi lại mô hình. Nhưng **phần lớn mã không nằm trong vòng lặp này mà nằm trong các hệ thống bao quanh nó** — hệ thống quyền hạn, pipeline nén ngữ cảnh, cơ chế mở rộng, điều phối agent con và lưu trữ phiên. Đây chính là bản chất của harness: vòng lặp là bộ khung, còn mọi thứ bên ngoài bộ khung mới quyết định độ tin cậy.++## Hệ thống con chỉ dẫn: hệ thống bộ nhớ phân tầng++Hệ thống bộ nhớ của Claude Code là đóng góp trực tiếp nhất của nó cho lý thuyết harness, tương ứng với hai bài trong khóa học về “repository là nguồn sự thật” và “tính liên tục của ngữ cảnh qua nhiều phiên”. [Tài liệu chính thức “How Claude remembers your project”](https://code.claude.com/docs/en/memory) nêu rõ: mỗi phiên đều bắt đầu với một cửa sổ ngữ cảnh hoàn toàn mới và mang tri thức qua các phiên bằng hai cơ chế — tệp CLAUDE.md (chỉ dẫn do bạn viết) và auto memory (ghi chú do Claude tự viết).++Về phạm vi, tài liệu chính thức chia tệp CLAUDE.md thành bốn loại (theo thứ tự tải từ rộng đến hẹp):++- **Cấp chính sách tổ chức**: do IT/DevOps quản lý thống nhất (chẳng hạn `/etc/claude-code/CLAUDE.md`), chứa quy chuẩn cấp công ty.+- **Cấp người dùng `~/.claude/CLAUDE.md`**: sở thích và quy tắc cá nhân dùng xuyên dự án.+- **Cấp dự án `./CLAUDE.md` hoặc `./.claude/CLAUDE.md`**: nguồn sự thật cấp dự án, gồm cấu trúc kỹ thuật, stack công nghệ và lệnh xác minh, được chia sẻ cùng repository.+- **Cấp cục bộ `./CLAUDE.local.md`**: sở thích cá nhân trong dự án, thường được thêm vào `.gitignore` và không commit.++Ngoài ra còn có hai cơ chế:++- **Tải theo nhu cầu ở cấp thư mục con**: CLAUDE.md trong thư mục con không được tải khi khởi động, mà chỉ đi vào ngữ cảnh khi Claude đọc tệp trong thư mục đó.+- **Bộ nhớ tự động (auto memory)**: Claude chủ động ghi chú dựa trên các sửa đổi và sở thích của bạn; ghi chú được chia sẻ theo repository, có hiệu lực xuyên worktree, và mỗi phiên chỉ tải tối đa 200 dòng đầu hoặc 25KB.++Bốn loại phạm vi này tạo thành một **hệ thống phân cấp chỉ dẫn**: tài liệu chính thức cho biết “chỉ dẫn càng cụ thể thì càng đi vào ngữ cảnh muộn” (chỉ dẫn dự án xuất hiện sau chỉ dẫn người dùng). Giá trị của nó nằm ở chỗ mô hình không phải tiêu hóa một tệp chỉ dẫn khổng lồ ngay đầu mỗi cuộc trò chuyện, mà tải cục bộ theo phạm vi. Đây chính là câu trả lời được sản phẩm hóa cho Bài 4 của khóa học, “Vì sao một tệp chỉ dẫn khổng lồ sẽ thất bại”.++## Hệ thống con ngữ cảnh: pipeline nén năm tầng++Claude Code quản lý ngữ cảnh bằng một **pipeline nén năm tầng** (five-layer compaction pipeline), chứ không đơn giản là “đầy thì tóm tắt” — chi tiết kiến trúc này đến từ phân tích cấp mã nguồn [“Dive into Claude Code” của VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf). Bài 5 của khóa học nói về việc “tác vụ dài sẽ mất tính liên tục”; giải pháp của Claude Code là một phễu nhiều cấp: trước tiên cắt tỉa không mất dữ liệu (loại bỏ kết quả công cụ dư thừa), sau đó tinh lọc có cấu trúc, cuối cùng mới dùng bản tóm tắt LLM có mất dữ liệu, đồng thời kết hợp cơ chế ngắt mạch để tránh nén quá mức.++Đi cùng với đó là thiết kế lưu trữ phiên: **lưu trữ phiên theo kiểu nối thêm (append-oriented storage)**, toàn bộ lịch sử được nối thêm vào `history.jsonl`, hỗ trợ khôi phục bằng `/resume` và phân nhánh fork. Điều này bảo đảm “bàn giao đầy đủ trước khi kết thúc mỗi phiên” — không phải nhờ trí nhớ tốt, mà vì tầng lưu trữ có tính nối thêm và có thể phát lại.++## Hệ thống con công cụ: bốn cơ chế mở rộng++Claude Code chia bề mặt mở rộng thành bốn loại, mỗi loại giải quyết một dạng vấn đề; đây là phần đáng học hỏi nhất trong thiết kế của nó:++- **Kỹ năng (Skills)**: [tài liệu chính thức](https://code.claude.com/docs/en/skills) định nghĩa đây là tri thức quy trình được mô tả bằng `SKILL.md`, tự động tải theo từ khóa kích hoạt và công bố dần dần. Phù hợp với tri thức chuyên môn về “cách làm một việc”.+- **MCP**: giao thức JSON-RPC trong [tài liệu chính thức](https://code.claude.com/docs/en/mcp) kết nối các hệ thống bên ngoài, là giao diện tiêu chuẩn giúp “cánh tay của mô hình vươn ra thế giới bên ngoài”.+- **Hook (Hooks)**: [tài liệu chính thức](https://code.claude.com/docs/en/hooks) mô tả các script tất định gắn vào những sự kiện vòng đời như `PreToolUse`, `PostToolUse`, `Stop`.+- **Plugin / agent con (Subagents)**: [tài liệu chính thức](https://code.claude.com/docs/en/sub-agents) giao các tác vụ phức tạp cho agent chuyên biệt thực hiện.++Thiết kế then chốt là **phân tách trách nhiệm**: CLAUDE.md quản lý “là gì”, kỹ năng quản lý “làm thế nào”, MCP quản lý “kết nối đến đâu”, còn hook quản lý “khi nào phải cưỡng chế”. Nếu một nhóm dùng lẫn các tầng này (chẳng hạn viết công việc của MCP vào CLAUDE.md), hiện tượng rò rỉ ngữ cảnh được nói đến trong khóa học sẽ xuất hiện.++## Phản hồi và xác minh: ràng buộc tất định + phân công người–máy++Bài 10 của khóa học nói rằng “chỉ khi chạy thông toàn bộ quy trình mới được xem là xác minh thực sự”; Claude Code đáp ứng bằng cơ chế hai đường:++**1. Hệ thống quyền hạn (ràng buộc tất định).** Quyền hạn của Claude Code không phải “hỏi lại mọi thứ”, mà gồm bảy chế độ + một bộ phân loại dựa trên ML: thao tác rủi ro thấp được cho phép, thao tác rủi ro cao sẽ được hỏi hoặc từ chối theo chính sách (xem chi tiết kiến trúc trong [phân tích của VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Đây là cách biến việc “vạch rõ ranh giới cho agent” (Bài 7) thành cưỡng chế ở runtime, thay vì cầu xin bằng prompt.++**2. Hook (ngăn tuyên bố hoàn thành quá sớm).** Hook `PostToolUse` có thể buộc chạy kiểm tra sau khi công cụ được thực thi rồi ghi kết quả trở lại ngữ cảnh; hook `Stop` can thiệp khi agent tuyên bố hoàn thành. Đây là cách “tách người làm khỏi người kiểm tra” — [Anthropic đã quan sát rõ trong bài viết về harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) rằng agent sẽ tự tin ca ngợi công việc của mình (“confidently praised their work”), vì vậy hook được dùng để chèn kiểm tra **tất định**, thay vì tin vào tự đánh giá của mô hình.++**3. Agent con (cô lập ngữ cảnh).** Nhật ký hội thoại của mỗi agent con được lưu trong một tệp sidechain độc lập và **không làm phình ngữ cảnh của agent cha** (xem [phân tích của VILA Lab](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)). Đây là sự kết hợp giữa “ranh giới tác vụ” và “cô lập ngữ cảnh”: khi chia nhỏ tác vụ, sự ô nhiễm ngữ cảnh cũng được cô lập.++## Khả năng quan sát và duy trì phiên++Nhật ký của Claude Code là một bản ghi đầy đủ theo kiểu nối thêm (history.jsonl). Cùng với các lệnh tường minh `/compact`, `/clear`, `/init`, nó cho phép bạn chủ động quản lý trạng thái ngữ cảnh thay vì thụ động chờ cửa sổ đầy. Đặc biệt, `/init` biến việc “để agent khởi tạo trước mỗi lần làm việc” (Bài 6) thành một lệnh — [tài liệu chính thức](https://code.claude.com/docs/en/memory) cho biết lệnh này tự động phân tích codebase và tạo CLAUDE.md ban đầu (bao gồm lệnh build, hướng dẫn kiểm thử và quy ước kỹ thuật).++## Ánh xạ vào khung của khóa học++| Hệ thống con | Cách Claude Code triển khai | Đánh giá |+| --- | --- | --- |+| Chỉ dẫn | Phân tầng theo phạm vi (tổ chức/người dùng/dự án/cục bộ) + bộ nhớ tự động | Bộ nhớ phân tầng là triển khai chuẩn mực |+| Công cụ | Bốn loại mở rộng: kỹ năng + MCP + hook + agent con | Phân chia trách nhiệm rõ ràng, là điểm nổi bật cốt lõi |+| Môi trường | Thiết lập trong dự án + settings.json | Dựa vào người dùng tự mô tả trong CLAUDE.md |+| Trạng thái | Lưu trữ phiên nối thêm + nén năm tầng + resume/fork | Rất mạnh, là triển khai tham chiếu cho tính liên tục của tác vụ dài |+| Phản hồi | Bộ phân loại quyền hạn + hook PostToolUse cưỡng chế kiểm tra | Biến việc “ngăn tuyên bố hoàn thành quá sớm” thành cơ chế tất định |++## Những thiết kế đáng học hỏi++1. **Phân tầng chỉ dẫn theo phạm vi**, thay vì chất đống trong một tệp. CLAUDE.md cấp thư mục là một cách triển khai “tải cục bộ” rất đẹp.+2. **Nén là một phễu phân cấp**: không mất dữ liệu trước, có mất dữ liệu sau; đừng bắt đầu bằng việc tóm tắt toàn văn.+3. **Dùng hook để kiểm tra tất định**: ngăn tuyên bố hoàn thành quá sớm dựa vào cưỡng chế ở runtime, không phải lời cầu xin trong prompt.+4. **Cô lập ngữ cảnh agent con**: chia tác vụ đồng thời chia ngữ cảnh, không để kết quả tác vụ con làm ô nhiễm vòng lặp chính.+5. **Lưu trữ phiên theo kiểu nối thêm + có thể phát lại**: bàn giao không dựa vào trí nhớ mà được bảo đảm bởi tầng lưu trữ.++## Nguồn tham khảo (nguyên văn / mã nguồn)++Mọi luận điểm đều có thể truy ngược về nguyên văn hoặc mã nguồn dưới đây, tránh thuật lại theo ấn tượng:++- **Tài liệu chính thức Claude Code · Memory**: ngữ cảnh hoàn toàn mới ở mỗi phiên, bốn phạm vi CLAUDE.md, tải theo nhu cầu ở thư mục con, auto memory (200 dòng / 25KB), `/init` tạo CLAUDE.md.<br/>https://code.claude.com/docs/en/memory+- **Tài liệu chính thức Claude Code · Skills / MCP / Hooks / Sub-agents**: định nghĩa bốn cơ chế mở rộng và các sự kiện (PreToolUse / PostToolUse / Stop).<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab “Dive into Claude Code”** (báo cáo phân tích cấp mã nguồn): pipeline nén năm tầng, bảy chế độ quyền hạn + bộ phân loại ML, agent con sidechain, lưu trữ phiên nối thêm history.jsonl.<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic “Effective harnesses for long-running agents”**: nguồn của các quan điểm “độ tin cậy đến từ harness chứ không phải mô hình”, agent tự tin ca ngợi công việc của mình và dùng hook để xác minh.<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Hướng dẫn Claude Code Full Stack** (cộng đồng, phân tầng CLAUDE.md / Skills / MCP / Subagents / Hooks): tài liệu đọc thêm về phân tách trách nhiệm giữa các cơ chế mở rộng.<br/>https://jsmanifest.com/claude-code-full-stack-guide++Giáo trình liên quan: [Bài 3 · Biến repository thành nguồn sự thật duy nhất](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Bài 9 · Ngăn agent tuyên bố hoàn thành quá sớm](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [Bài 10 · Chỉ chạy thông toàn bộ quy trình mới là xác minh thực sự](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/vi/harness-designs/codex/index.md b/docs/vi/harness-designs/codex/index.mdnew file mode 100644index 0000000..187b0d9--- /dev/null+++ b/docs/vi/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# Phân tích thiết kế harness của Codex++[Codex](https://openai.com/index/harness-engineering/) của OpenAI có lẽ là sản phẩm gắn bó sâu sắc nhất với “nguyên lý gốc của harness” trong bốn sản phẩm — chính bài viết “Harness Engineering”, bài đã đặt tên cho cả lĩnh vực này, là bản tổng kết kinh nghiệm của đội ngũ OpenAI khi dùng Codex để xây dựng sản phẩm. Vì vậy, phân tích thiết kế harness của Codex phần lớn cũng là phân tích thực tiễn kỹ thuật đứng sau bài viết đó.++Triết lý của Codex có thể cô đọng trong một câu: **repository là nguồn sự thật (repository as the system of record), AGENTS.md chỉ là trang mục lục, còn giá trị kỹ thuật nằm ở việc thiết kế môi trường, diễn đạt ý định và xây dựng vòng phản hồi.**++## Định vị trong một câu++Đội ngũ OpenAI đã dùng Codex để bàn giao trong vài tuần một sản phẩm cuối cùng có hơn một triệu dòng mã, và **mọi dòng mã đều do Codex viết** (xem nguyên văn ở phần “Designing for growth” trong [Harness Engineering](https://openai.com/index/harness-engineering/)). Thực tiễn của họ trả lời một câu hỏi: khi vai trò của kỹ sư chuyển từ “viết mã” sang “thiết kế harness”, hệ thống nên được tổ chức như thế nào. Bản thân Codex CLI là một binary nguyên khối mã nguồn mở (viết bằng Rust, [github.com/openai/codex](https://github.com/openai/codex)), nhưng đóng góp chủ yếu của nó cho harness nằm ở **quy ước (convention)** và **kỹ thuật ngữ cảnh**, chứ không phải các điểm mở rộng hào nhoáng.++## Hệ thống con chỉ dẫn: AGENTS.md là trang mục lục, không phải bách khoa toàn thư++Đây là quyết định thiết kế có ảnh hưởng lớn nhất của Codex đối với lý thuyết harness:++> Một tệp chỉ dẫn khổng lồ không thuận lợi cho việc kiểm tra tự động (độ bao phủ, trạng thái cập nhật, quyền sở hữu, liên kết chéo), nên việc nó lệch khỏi thực tế là không thể tránh khỏi. Vì vậy, chúng tôi không còn coi AGENTS.md là một bộ bách khoa toàn thư mà coi nó là một **trang mục lục**. Tri thức về codebase nằm trong tài liệu có cấu trúc, còn AGENTS.md chịu trách nhiệm trỏ đến chúng.++(Nội dung trên là phần thuật lại trực tiếp mục “AGENTS.md should be a directory page” trong [“Harness Engineering”](https://openai.com/index/harness-engineering/).)++Bài 4 của khóa học nói rằng “một tệp chỉ dẫn khổng lồ sẽ thất bại”, và Codex đưa ra lời giải trực tiếp: giữ AGENTS.md ở khoảng 100 dòng (nguyên văn khuyến nghị khoảng 100 dòng, gần tới giới hạn thì tách sang `docs/`); nếu không chứa hết thì chia nhỏ vào thư mục `docs/` để agent đọc theo nhu cầu. Đây là nguồn có thẩm quyền cho nguyên tắc “đưa bản đồ, không đưa sách hướng dẫn”.++Nguyên tắc đi kèm là **thực thi các bất biến, đừng vi quản lý cách triển khai** (nguyên văn: “don't micromanage the implementation; focus on invariants”): AGENTS.md chỉ viết các ràng buộc cứng không được vi phạm và lệnh xác minh, còn cách triển khai cụ thể được giao cho mô hình. Điều này tương ứng trực tiếp với “ràng buộc thay vì vi quản lý” trong Bài 2 của khóa học.++## Hệ thống con ngữ cảnh: Write-Select-Compress-Isolate++Kỹ thuật ngữ cảnh của Codex có thể được khái quát thành bốn chiến lược. Đây là khung do cộng đồng tổng kết sau khi “context engineering” trở thành một lĩnh vực riêng, rồi ánh xạ ngược lại Codex (nguồn của khung: [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):++- **Write (ghi ra ngoài)**: duy trì ngữ cảnh ở ngoài cửa sổ — ghi kết luận vào tài liệu và trạng thái vào tệp, thay vì để trong hội thoại. Tương ứng với “repository là nguồn sự thật”.+- **Select (chọn đưa vào)**: chỉ kéo các token cần thiết vào cửa sổ — AGENTS.md chỉ đường, tệp được đọc theo nhu cầu, thay vì nhồi toàn bộ repository vào.+- **Compress (nén)**: giữ lại những gì thực sự quan trọng — Codex có nén tự động và `/compact` thủ công, đồng thời cho phép tùy chỉnh `compact_prompt` (xem [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)).+- **Isolate (cô lập)**: chia ngữ cảnh theo các ranh giới khác nhau — dùng agent con (subagent) để cô lập ngữ cảnh của từng tác vụ, chẳng hạn một agent con frontend sẽ không bao giờ nhìn thấy schema cơ sở dữ liệu của backend.++Codex còn có một thiết kế ngữ cảnh môi trường rất tinh tế: phân tích mã nguồn của cộng đồng về [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) cho thấy `build_environment_update_item` chỉ xuất **các trường đã thay đổi** (CWD, nhánh git, hệ thống tệp) khi môi trường thay đổi, thay vì dán lại toàn bộ ngữ cảnh hệ thống ở mỗi lượt. Đây là một chi tiết kỹ thuật cho nguyên tắc “không nuôi token lặp lại trong ngữ cảnh”.++## Công cụ và ranh giới: cô lập bằng worktree + agent con++Codex có hai cơ chế harness cốt lõi:++**1. Cô lập môi trường bằng git worktree.** Phần “Environment” trong [“Harness Engineering”](https://openai.com/index/harness-engineering/) nêu rõ: mỗi tác vụ chạy trong một git worktree độc lập, kết hợp với stack quan sát cục bộ (log, metric, trace), để mọi thay đổi đều được xác minh trong môi trường riêng. Đây là cách hiện thực hóa về mặt vật lý cho Bài 7, “vạch rõ ranh giới mỗi tác vụ cho agent” — ranh giới không dựa vào lời cầu xin trong chỉ dẫn mà được cưỡng chế bằng cô lập môi trường. Hệ thống con môi trường (environment) ở đây trở thành một lớp cô lập cứng.++**2. Agent con cấp lõi.** `spawn_agent` / `wait_agent` của Codex là các công cụ cấp lõi: mô hình chủ động tạo agent con, cung cấp lịch sử phiên và bộ công cụ độc lập cho nó, rồi chờ kết quả. Agent con kế thừa chỉ dẫn AGENTS.md của cấp cha, nhưng chạy trong **ngữ cảnh riêng**. Cấu hình nằm trong `.codex/agents/*.toml`, có thể chỉ định mô hình và chỉ dẫn khác nhau (xem chi tiết trong phần Sub-agents của [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)). Đây là cách triển khai trực tiếp “cô lập ngữ cảnh”, đồng thời thể hiện tinh thần “bàn giao” của Bài 12: mỗi agent con là một đơn vị công việc có ranh giới rõ ràng.++## Hệ thống con phản hồi: đưa lệnh xác minh vào quy chuẩn++Điểm được nhấn mạnh nhất trong thực tiễn của OpenAI: liệt kê rõ các lệnh xác minh trong AGENTS.md, biến “làm sao biết đã làm đúng” thành một phần của repository. Trong quy trình kỹ thuật của Codex, kiểm thử, CI, tài liệu và cấu hình khả năng quan sát đều do Codex tạo ra, và tất cả đều là “đường dẫn xác minh có thể thực thi”. Giải pháp cho một mô hình mạnh nhưng không đáng tin cậy không phải là cầu mong mô hình tự giác, mà là biến **đường dẫn xác minh thành thành phần mặc định của harness**.++Chính sách phê duyệt (approval policies) và chế độ lập kế hoạch (plan mode) tạo thành một hướng phản hồi khác: trước khi thực hiện thao tác rủi ro cao, hệ thống phải đưa ra kế hoạch và xin phê duyệt, qua đó biến “ranh giới tác vụ” và “quyền quyết định của con người” thành điều khiển ở runtime.++## Ánh xạ vào khung của khóa học++| Hệ thống con | Cách Codex triển khai | Đánh giá |+| --- | --- | --- |+| Chỉ dẫn | Trang mục lục AGENTS.md + tách sang docs/ + thực thi bất biến | Chuẩn sách giáo khoa, định nghĩa nguyên tắc “đưa bản đồ, không đưa sách hướng dẫn” |+| Công cụ | Cô lập bằng worktree + agent con spawn_agent | Ranh giới được cô lập cứng bằng môi trường, rất mạnh |+| Môi trường | worktree độc lập + stack quan sát | Cô lập bằng worktree là dấu ấn đặc trưng |+| Trạng thái | Chiến lược Write (ghi trạng thái vào tệp/tài liệu) | Dựa vào quy ước thay vì bộ nhớ tích hợp |+| Phản hồi | Đưa lệnh xác minh vào quy chuẩn + chính sách phê duyệt + plan mode | Mặc định hóa đường dẫn phản hồi, đáng học hỏi |++Sự đối chiếu giữa Codex và Claude Code rất thú vị: Claude Code là “phép cộng” — đưa bộ nhớ, quyền hạn và agent con vào lõi; Codex là “phép trừ” — giữ lõi tiết chế nhất có thể và giao nhiều trách nhiệm hơn cho quy ước repository cùng kỹ thuật ngữ cảnh. Đây cũng là lý do cộng đồng thường nói “triết lý harness của Codex còn đáng giá hơn mã nguồn của nó”.++## Những thiết kế đáng học hỏi++1. **Viết AGENTS.md như trang mục lục**: giữ ở khoảng 100 dòng, trỏ tới chi tiết trong docs/, có thể kiểm tra tự động.+2. **Chỉ viết bất biến, không vi quản lý cách triển khai**: ràng buộc cứng + lệnh xác minh, phần còn lại giao cho mô hình.+3. **Dùng worktree để cô lập môi trường**: ranh giới tác vụ được cưỡng chế bằng môi trường, không dựa vào lời cầu xin trong chỉ dẫn.+4. **Chỉ truyền phần gia tăng của ngữ cảnh môi trường**: mỗi lượt chỉ xuất trường đã thay đổi, không dán lại toàn bộ ngữ cảnh hệ thống.+5. **Dùng agent con để cô lập ngữ cảnh**: vừa chia tác vụ vừa chia ngữ cảnh, không để tác vụ con làm ô nhiễm vòng lặp chính.++## Nguồn tham khảo (nguyên văn / mã nguồn)++Mọi luận điểm đều có thể truy ngược về nguyên văn hoặc mã nguồn dưới đây, tránh thuật lại theo ấn tượng:++- **OpenAI “Harness Engineering”**: trang mục lục AGENTS.md và khuyến nghị khoảng 100 dòng, executive invariants / don't micromanage, cô lập bằng worktree + stack quan sát, đưa lệnh xác minh vào quy chuẩn, trường hợp sản phẩm hơn một triệu dòng mã, chính sách phê duyệt và plan mode. Nguồn chính cho mọi luận điểm cốt lõi trong bài.<br/>https://openai.com/index/harness-engineering/+- **Quy chuẩn “AGENTS.md” chính thức của OpenAI** (AGENTS.md là quy ước tiêu chuẩn dùng xuyên công cụ):<br/>https://openai.com/index/agents-md/+- **Repository mã nguồn mở Codex CLI** (binary nguyên khối viết bằng Rust):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI** (cộng đồng): khung Write-Select-Compress-Isolate, `/compact` và `compact_prompt`, agent con `spawn_agent` / `wait_agent` cùng cấu hình `.codex/agents/*.toml`.<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals** (phân tích mã nguồn của cộng đồng): các chi tiết triển khai như ngữ cảnh môi trường gia tăng `build_environment_update_item`.<br/>https://github.com/AlexKenbo/codex-harness-internals++Giáo trình liên quan: [Bài 3 · Biến repository thành nguồn sự thật duy nhất](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [Bài 4 · Chia chỉ dẫn vào các tệp khác nhau](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [Bài 7 · Vạch rõ ranh giới mỗi tác vụ cho agent](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/vi/harness-designs/deepseek/index.md b/docs/vi/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..ec3771f--- /dev/null+++ b/docs/vi/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# Phân tích thiết kế DeepSeek Harness++[DeepSeek Harness](https://deepseek.com/harness) (tên lệnh `dsh`, repository `deepseek-ai/deepseek-harness`) được phát hành dưới dạng Developer Preview vào tháng 8 năm 2026. Định nghĩa chính thức của nó rất trực tiếp: **Agent = Model + Environment + Tools + State** — mô hình, môi trường, công cụ và trạng thái, một bộ bốn thành phần.++Nếu việc phân tích ba sản phẩm trước đặt câu hỏi “harness nên được thiết kế như thế nào”, DeepSeek Harness đặt ra một câu hỏi táo bạo hơn: **harness có thể tách khỏi mô hình cụ thể để trở thành một runtime độc lập không?** Câu trả lời của nó là có, và nó đẩy ý tưởng này đến cực hạn — nguyên văn trong [tài liệu kiến trúc](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): *Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself* (mọi phần của sản phẩm đều là plugin, bao gồm bộ điều hợp mô hình, registry công cụ, nhật ký phiên và thậm chí chính vòng lặp agent).++Trong bài này, chúng ta tập trung phân tích ba điều: lõi plugin hóa, đường nối năng lực (capability seam), pipeline sự kiện, cùng ràng buộc kỹ thuật mạnh nhất: “Model-visible means logged”.++## Định vị trong một câu++Cấu trúc của coding agent truyền thống là “LLM + vòng lặp agent cố định + bộ công cụ cố định”. Cấu trúc của DeepSeek Harness là “mô hình + một lõi plugin (Cordis)”; lõi chỉ chịu trách nhiệm tải và gỡ plugin, quan hệ phụ thuộc cùng cơ chế sự kiện, và **không sở hữu bất kỳ năng lực cụ thể nào của agent** — nguyên văn trong [tài liệu kiến trúc](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): “There is no privileged core to patch” (không có lõi đặc quyền nào cần vá), “you extend dsh by mounting a plugin beside the others” (chỉ cần gắn thêm một plugin bên cạnh các plugin khác để mở rộng dsh, không cần sửa lõi). Điều này có nghĩa ngay cả vòng lặp agent cũng không phải phần thiêng liêng bất biến — bạn có thể dùng mô hình của DeepSeek, nối với agent con của Claude Code, thêm sandbox từ xa, viết bộ nhớ tùy chỉnh, thay vòng lặp tùy chỉnh, thay UI tùy chỉnh và ghép thành một agent hoàn toàn mới.++Đây là cách hiện thực triệt để nhất câu “mọi thứ ngoài trọng số mô hình đều là harness” trong khóa học: nếu harness độc lập, hãy để nó độc lập thành một hệ điều hành.++## Cốt lõi kiến trúc 1: đường nối năng lực (Capability Seam)++DeepSeek Harness dùng Service để biểu diễn “năng lực”, và gần như mọi năng lực đều được chia thành ba tầng:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++Lấy hệ thống tệp làm ví dụ: bên dưới `FS Service` có nhiều Provider như Local FS, E2B FS, Remote FS, còn phía trên cung cấp thống nhất thành file tools. Shell, Subprocess, Sandbox, Web, LLM và SubAgent đều dùng cùng một cấu trúc. Cấu trúc ba tầng này không phải do chúng ta tự tổng kết — nguyên văn trong [tài liệu kiến trúc · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): *a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool* (đường nối năng lực = một năng lực có thể thay thế với ba vai trò: Service Definition khai báo giao diện, Service Provider triển khai giao diện và Consumer sử dụng nó; Consumer thường là công cụ hướng tới mô hình).++Điều này giải quyết một vấn đề tồn tại lâu dài trong kỹ thuật harness: **agent nên phụ thuộc vào “công cụ cụ thể” hay “giao diện năng lực”?** DeepSeek Harness chọn phương án thứ hai. Đối với khóa học, điều đó có nghĩa “hệ thống con công cụ” đã được tiêu chuẩn hóa thành giao diện — khi thay Provider, hình thức công cụ được cung cấp cho mô hình không đổi nhưng môi trường thay đổi hoàn toàn.++## Cốt lõi kiến trúc 2: pipeline sự kiện (Event Pipeline)++Bên trong DeepSeek Harness không chỉ là “LLM → công cụ → LLM”, mà là một pipeline sự kiện, trong đó mọi khâu đều là điểm sự kiện mà plugin có thể lắng nghe:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(Pipeline trên là bản chuyển lại từ phần [tài liệu kiến trúc · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md): `turn/*`, `step/*`, `user/message`, `assistant/*`, `tool/*` là các sự kiện phiên được duy trì; `agent/pre-step`, `agent/request`, `llm/stream`, `tools/*` là các điểm mở rộng mà plugin có thể lắng nghe.)++Lợi ích lớn nhất của thiết kế này là: **rất nhiều chức năng hoàn toàn không cần sửa chính vòng lặp agent**. Muốn kiểm tra an toàn trước khi thực thi công cụ? Lắng nghe `tools/pre-execute`. Muốn thêm bộ nhớ? Chèn vào `agent/pre-step`. Muốn ghi lại hành vi? Đăng ký sự kiện session. Muốn sửa yêu cầu gửi đến mô hình? Gắn hook vào `agent/request`. Muốn quyết định có tiếp tục suy luận không? Lắng nghe `agent/turn-stopping`.++So với Bài 11 của khóa học, “làm cho quá trình chạy của agent có thể quan sát được”, DeepSeek Harness còn đi xa hơn: nó không “thêm log”, mà biến **từng bước của vòng lặp thành một điểm sự kiện**, để khả năng quan sát, quyền hạn, bộ nhớ và chính sách đều gắn vào vòng lặp với tư cách listener, thay vì được viết cứng trong vòng lặp.++## Cốt lõi kiến trúc 3: Session Event Log và “Model-visible means logged”++DeepSeek Harness có một **Session Event Log chỉ nối thêm (append-only)**, đồng thời đặt ra một ràng buộc kỹ thuật rất mạnh. Nguyên văn trong [tài liệu kiến trúc · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md):++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(Mọi thứ mô hình nhìn thấy đều phải được ghi lại. Bất cứ thứ gì đi vào yêu cầu mô hình đều phải có thể được tái dựng từ log, và một bất biến runtime sẽ cưỡng chế điều này.)++Nói cách khác, khả năng quan sát không phải log bổ sung sau sự kiện, mà là ràng buộc nền tảng của harness: bất cứ thứ gì đi vào ngữ cảnh mô hình mặc định đều phải để lại log. Điều này trực tiếp tương ứng với “khả năng quan sát thuộc bên trong harness” ở bài kết thúc, đồng thời biến thiết kế lưu trữ “append-only” thành nguyên tắc — log chỉ được nối thêm, không ghi đè, và trạng thái phiên có thể phát lại.++## Ánh xạ vào khung của khóa học++| Hệ thống con | Cách DeepSeek Harness triển khai | Đánh giá |+| --- | --- | --- |+| Chỉ dẫn | Plugin hóa; quy tắc/kỹ năng đều được chèn dưới dạng plugin | Cực kỳ tự do, nhưng không có quy ước kiểu “CLAUDE.md” tích hợp sẵn |+| Công cụ | Đường nối năng lực Service Definition → Provider → Consumer | Đưa tiêu chuẩn hóa hệ thống con công cụ đến cực hạn |+| Môi trường | Sandbox/FS/Shell đều có thể thay Provider (bao gồm E2B từ xa) | Môi trường hoàn toàn có thể thay thế |+| Trạng thái | Session Event Log append-only + Model-visible means logged | Khả năng quan sát là ràng buộc nền tảng |+| Phản hồi | permission / guard / policy / hook trên tools/pre-execute | Cơ chế phản hồi được sự kiện hóa |++Khác biệt căn bản giữa DeepSeek Harness và ba sản phẩm còn lại: Pi, Claude Code và Codex đều tối ưu harness bên trong “một agent cụ thể”; còn DeepSeek Harness định nghĩa harness là một **hệ điều hành độc lập với mô hình**, trong đó chính agent chỉ là một ứng dụng có thể thay thế trên OS đó. Cái giá cũng rất rõ — mức độ tự do cao đồng nghĩa với chi phí cấu hình cao; đây là mặt còn lại vốn có của thiết kế “harness là OS” (giai đoạn Developer Preview cũng được định vị là “trải nghiệm sớm, cơ chế vẫn đang phát triển”).++## Những thiết kế đáng học hỏi++1. **Biến từng bước của vòng lặp thành điểm sự kiện**: quyền hạn, bộ nhớ, chính sách và log đều được gắn vào vòng lặp dưới dạng listener, thay vì viết cứng trong vòng lặp.+2. **Tiêu chuẩn hóa đường nối năng lực**: phụ thuộc vào “giao diện năng lực” thay vì “công cụ cụ thể”, để có thể thay toàn bộ môi trường mà không ảnh hưởng đến bề mặt công cụ mô hình nhìn thấy.+3. **Model-visible means logged**: mọi thứ mô hình nhìn thấy đều phải được ghi lại, biến khả năng quan sát từ “điểm cộng” thành “ràng buộc nền tảng”.+4. **Nhật ký phiên append-only**: trạng thái có thể phát lại, bàn giao đáng tin cậy; đây là bảo đảm kỹ thuật cho việc “mỗi phiên để lại trạng thái sạch”.++## Nguồn tham khảo (nguyên văn / mã nguồn)++Mọi luận điểm đều có thể truy ngược về nguyên văn hoặc mã nguồn dưới đây, tránh thuật lại theo ấn tượng:++- **Trang chủ DeepSeek Harness**: định nghĩa sản phẩm “Agent = Model + Environment + Tools + State”, định vị Developer Preview và lệnh `dsh`.<br/>https://deepseek.com/harness+- **Repository deepseek-ai/deepseek-harness** (lệnh `dsh`, giấy phép MIT):<br/>https://github.com/deepseek-ai/deepseek-harness+- **Tài liệu kiến trúc architecture.md**: nguồn cốt lõi nhất của bài — “Every part of the product is a plugin”, “There is no privileged core to patch”, pipeline sự kiện Turn flow, ba vai trò của Capability seams, “Model-visible means logged” cùng bất biến runtime, Session Event Log append-only, các đường nối năng lực như fs/tools/telemetry và hệ thống con `ctx.*`.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **Tài liệu con đi kèm tài liệu kiến trúc**: giới thiệu lõi Cordis (plugins contribute services, typed events, reversible effects), chi tiết đường nối năng lực và hệ thống con Session.<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++Giáo trình liên quan: [Bài 11 · Làm cho quá trình chạy của agent có thể quan sát được](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [Bài 12 · Bàn giao đầy đủ trước khi kết thúc mỗi phiên](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [Bài 2 · Harness thực chất là gì](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/vi/harness-designs/index.md b/docs/vi/harness-designs/index.mdnew file mode 100644index 0000000..6b6327a--- /dev/null+++ b/docs/vi/harness-designs/index.md@@ -0,0 +1,29 @@+# Phân tích các harness tiên tiến++Chuyên mục này đối chiếu lý thuyết về harness trong giáo trình với từng sản phẩm thực tế tiên tiến nhất hiện nay. Với mỗi sản phẩm, chúng ta chỉ quan tâm một điều: **harness của nó được thiết kế như thế nào** — tức lớp hạ tầng kỹ thuật bao quanh mô hình, gồm năm hệ thống con là chỉ dẫn, công cụ, môi trường, trạng thái và phản hồi, cùng các cơ chế cốt lõi như tính liên tục của ngữ cảnh, khởi tạo, xác minh, khả năng quan sát, bàn giao và vòng lặp.++Chúng ta chủ ý không bàn về năng lực suy luận của mô hình mạnh đến đâu, điểm benchmark trong một lần chạy cao hay thấp, cũng không giới thiệu chung chung rằng "agent này làm được gì". Đó là những vấn đề thuộc tầng mô hình và tầng sản phẩm. Ở đây chỉ phân tích harness — mọi thứ nằm ngoài trọng số mô hình.++## Vì sao đáng phân tích++Bài đầu tiên của giáo trình đã chỉ ra: mô hình mạnh không đồng nghĩa với thực thi đáng tin cậy. Cùng một mô hình nhưng được đặt trong các harness khác nhau có thể cho hiệu quả chênh lệch cả một bậc độ lớn. Tuy nhiên, giáo trình nói về "nên làm như thế nào", còn các sản phẩm này trả lời câu hỏi "những đội ngũ hàng đầu thực tế làm như thế nào".++Mỗi sản phẩm là một tập hợp quyết định thiết kế độc lập. Khi đặt chúng cạnh nhau để đối chiếu, bạn sẽ thấy cùng những cơ chế cốt lõi lại được các đội ngũ triển khai theo những cách hoàn toàn khác nhau:++- **Pi** xây dựng harness theo mô hình lõi tối giản + phần mở rộng có thể lập trình, dùng "system prompt tối thiểu + tải theo nhu cầu" để thực hiện kỹ thuật ngữ cảnh.+- **Claude Code** biến harness thành một môi trường chạy hoàn chỉnh: bộ nhớ phân tầng, nén năm cấp, quyền hạn, hook và agent con.+- **Codex** đẩy triết lý harness đến cực hạn: repository là nguồn sự thật, AGENTS.md chỉ là trang mục lục, còn môi trường được cô lập bằng worktree.+- **DeepSeek Harness** định nghĩa thẳng harness là một runtime độc lập với mô hình: Everything is a Plugin.++## Danh sách bài viết++- [Phân tích thiết kế harness của Pi](./pi/): lõi tối giản + phần mở rộng có thể lập trình, đưa kỹ thuật ngữ cảnh ra ngoài system prompt.+- [Phân tích thiết kế harness của Claude Code](./claude-code/): bộ nhớ phân tầng, nén năm cấp, quyền hạn và hook — một môi trường chạy agent hoàn chỉnh.+- [Phân tích thiết kế harness của Codex](./codex/): repository là nguồn sự thật, AGENTS.md là trang mục lục, cùng cơ chế cô lập môi trường và vòng phản hồi.+- [Phân tích thiết kế DeepSeek Harness](./deepseek/): Everything is a Plugin, biến chính vòng lặp agent thành một plugin có thể thay thế.++## Cách đọc++Bạn nên đọc trước vài bài đầu của giáo trình (đặc biệt là [Bài 2: Harness thực chất là gì](../lectures/lecture-02-what-a-harness-actually-is/)) để nắm khung năm hệ thống con, sau đó quay lại đây xem các sản phẩm thực tế triển khai những cơ chế này như thế nào.++Cuối mỗi bài đều có hai phần "Ánh xạ vào khung của khóa học" và "Những thiết kế đáng học hỏi", giúp bạn nhanh chóng chuyển thiết kế sản phẩm trở lại các khái niệm trong khóa học để có thể áp dụng trực tiếp vào dự án của mình.diff --git a/docs/vi/harness-designs/pi/index.md b/docs/vi/harness-designs/pi/index.mdnew file mode 100644index 0000000..1a86e64--- /dev/null+++ b/docs/vi/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# Phân tích thiết kế harness của Pi++[Pi](https://pi.dev/) (gói npm `@earendil-works/pi-coding-agent`) tự gọi mình là “minimal agent harness” — một agent harness tối giản. Cụm từ này đáng được phân tích kỹ: nó không tự nhận là “coding agent mạnh nhất” hay “công cụ lập trình AI dễ dùng nhất”, mà xác định dứt khoát vị trí của mình bằng chính từ **harness**.++Trong bài này, chúng ta dùng khung năm hệ thống con của khóa học (chỉ dẫn, công cụ, môi trường, trạng thái, phản hồi) để phân tích Pi và xem triết lý thiết kế của nó khác căn bản với Claude Code và Codex như thế nào. Câu trả lời trước là: **triết lý của Pi là “tối giản hóa lõi + lập trình hóa phần mở rộng”, đưa kỹ thuật ngữ cảnh ra ngoài system prompt, để người dùng (thậm chí chính Pi) sửa harness, thay vì để Pi quyết định harness thay bạn.**++## Định vị trong một câu++Pi là một lõi tối giản: định vị chính thức chủ ý thu nhỏ lõi và trao lại quyền quyết định cho bạn — nguyên văn trên [trang chủ pi.dev](https://pi.dev/) là “Ask Pi to build what you want, or install a package that does it your way”. Nó chia harness thành bốn tầng có thể tùy chỉnh:++- **Phần mở rộng (Extensions)**: hook TypeScript gắn vào các sự kiện vòng đời của Pi, là bề mặt lập trình được ở cấp runtime.+- **Kỹ năng (Skills)**: gói năng lực được tải theo nhu cầu, gồm chỉ dẫn và công cụ, theo cơ chế công bố dần dần (progressive disclosure).+- **Mẫu prompt (Prompt templates)**: prompt Markdown có thể tái sử dụng, nhập `/name` để mở rộng.+- **Chủ đề (Themes)**: giao diện TUI.++Cách phân tầng này tự thân đã là một thiết kế harness: **trao hoàn toàn việc “mô hình có thể thấy gì và thấy vào lúc nào” cho quy tắc cùng phần mở rộng, thay vì viết cứng trong lõi.**++## Vòng lặp cốt lõi++Giống mọi coding agent, về bản chất Pi là một vòng lặp while “suy luận → thực thi công cụ → quan sát → suy luận tiếp”. Điều đáng chú ý không phải bản thân vòng lặp mà là cách Pi xử lý lớp ngoài của vòng lặp: nó mở rộng việc quản lý ngữ cảnh từ “nén” bên trong vòng lặp sang “kiểm soát” bên ngoài vòng lặp.++Runtime của Pi cung cấp giao diện lập trình ra bên ngoài — trong phần Programmatic Usage của [README mã nguồn](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md), ngoài TUI tương tác còn có chế độ in/JSON có thể script hóa, giao thức RPC và khả năng nhúng qua SDK. Điều này cho phép cùng một harness vừa được con người điều khiển từng bước, vừa có thể được CI/CD hoặc chương trình khác tự động điều khiển. Nó tương ứng với tiền đề “từ điều khiển thủ công đến vòng lặp tự động” trong Bài 13 về “kỹ thuật vòng lặp”: nếu một harness chỉ có thể được con người điều khiển tương tác, nó sẽ không bao giờ đi vào vòng lặp tự động.++## Hệ thống con chỉ dẫn: AGENTS.md và SYSTEM.md++Pi xử lý “chỉ dẫn” rất tiết chế nhưng có thứ bậc rõ ràng:++- **AGENTS.md**: phần Project Context Files trong [README mã nguồn](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) nêu rõ thứ tự tải — `~/.pi/agent/AGENTS.md` toàn cục → duyệt ngược từng cấp thư mục cha → `./AGENTS.md` trong thư mục hiện tại (cũng tương thích với CLAUDE.md). Đây là cách hiện thực nguyên tắc “repository là nguồn sự thật” — chỉ dẫn là tệp, không phải lời dặn trong khung chat.+- **SYSTEM.md**: [tài liệu chính thức pi.dev](https://pi.dev/docs/usage/project-context) cho biết có thể thay thế (replace) hoặc nối thêm (append) system prompt mặc định theo từng dự án. Đây là lối vào chính thức duy nhất để Pi cho phép bạn tác động đến “system prompt”, đồng thời là tầng “môi trường tự mô tả” của nó.++Pi chính thức nhấn mạnh rằng bản thân system prompt của nó **cực kỳ tối giản**. Đằng sau là một đánh đổi rõ ràng: lõi không nhồi các quy tắc dài dòng kiểu “nếu… thì…”, mà để lại các điểm mở rộng để quy tắc chỉ xuất hiện dưới dạng kỹ năng và phần mở rộng khi cần. Điều này tương ứng trực tiếp với Bài 4, “Vì sao một tệp chỉ dẫn khổng lồ sẽ thất bại” — Pi tự nhiên tránh được vấn đề chỉ dẫn khổng lồ bằng “lõi tối giản + chia tệp + tải theo nhu cầu”.++## Trạng thái và ngữ cảnh: nơi Pi phân tách chi tiết nhất++Kỹ thuật ngữ cảnh của Pi đáng được phân tích kỹ, vì nó biến các khái niệm “tính liên tục của ngữ cảnh” và “ngăn ngữ cảnh suy thoái” trong khóa học thành những cơ chế cụ thể:++**1. Lập trình hóa việc nén (Compaction).** Khi gần đạt giới hạn ngữ cảnh, hệ thống tự động tóm tắt các tin nhắn cũ — [tài liệu chính thức pi.dev](https://pi.dev/docs/usage/sessions) nêu rằng bản thân chiến lược nén **có thể tùy chỉnh**: bạn có thể dùng phần mở rộng để triển khai nén theo chủ đề, tóm tắt nhận biết mã, thậm chí dùng một mô hình khác để tóm tắt. README mã nguồn cũng cho biết chi tiết của cơ chế mặc định: nén tự động được kích hoạt trong hai trường hợp (khôi phục khi tràn ngữ cảnh / vượt ngưỡng giữ lại), điểm cắt giữ khoảng 20 nghìn token gần nhất, các tin nhắn trước đó được tóm tắt thành “context handoff” rồi nén dây chuyền theo từng cấp. Nói cách khác, Pi không coi “nén như thế nào” là một hằng số bất biến, mà coi nó là một phần của harness.++**2. Ngữ cảnh động (Dynamic context).** [Tài liệu chính thức pi.dev](https://pi.dev/docs/usage/extensions) cho biết phần mở rộng có thể chèn tin nhắn trước mỗi lượt suy luận, lọc lịch sử tin nhắn, triển khai RAG và xây dựng bộ nhớ dài hạn. Điều này tiến xa hơn việc “đầy ngữ cảnh rồi mới nén”: nó cho phép bạn quyết định đưa gì vào và loại gì ra trước khi ngữ cảnh đi vào cửa sổ. Tương ứng với “làm cho quá trình chạy của agent có thể quan sát, gỡ lỗi” và “duy trì tính liên tục của ngữ cảnh” trong khóa học, Pi đưa cả hai xuống bề mặt mở rộng.++**3. Cây phiên (Session tree).** [Trang chủ pi.dev](https://pi.dev/) nêu rõ “các phiên được lưu theo cấu trúc cây (sessions are stored as trees)”; `/tree` có thể quay lại bất kỳ nút lịch sử nào để tiếp tục, và mọi nhánh đều được lưu trong cùng một tệp. Điều này giải quyết vấn đề “đứt gãy ngữ cảnh giữa các phiên” được nhấn mạnh nhiều lần trong khóa học — không phải bằng cách ép nối với bản tóm tắt, mà bằng cách phát lại lịch sử có cấu trúc. Nhánh có thể xuất thành HTML hoặc tải lên dưới dạng gist để chia sẻ, qua đó khả năng quan sát cũng được giải quyết.++## Hệ thống con công cụ: kỹ năng và phần mở rộng++“Công cụ” của Pi có hai tầng:++- **Kỹ năng (Skills)**: phần Skills trong [README mã nguồn](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) định nghĩa rất rõ — “self-contained capability packages that the agent loads on-demand”, tức các gói năng lực độc lập mà agent tải theo nhu cầu, bao gồm chỉ dẫn và công cụ, tuân theo tiêu chuẩn Agent Skills. Việc công bố dần dần chỉ đưa chi tiết kỹ năng vào ngữ cảnh khi được kích hoạt, **không làm nổ prompt cache**. Đây là thiết kế harness xét từ góc độ chi phí: mỗi token thêm vào ngữ cảnh đều phải trả phí ở mỗi lần suy luận; biến kỹ năng thành nội dung tải theo nhu cầu chính là một cách diễn đạt khác của “đưa bản đồ, không đưa sách hướng dẫn”.+- **Phần mở rộng (Extensions)**: hook TypeScript gắn vào các sự kiện vòng đời tích hợp sẵn — phần Hooks trong [README mã nguồn](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) đưa ra các ví dụ chính thức: chặn lệnh nguy hiểm (cổng quyền hạn), checkpoint trạng thái mã khi chuyển tác vụ, bảo vệ đường dẫn (cấm ghi `.env`, v.v.), sửa đầu ra công cụ trước khi đưa cho mô hình, và chèn tin nhắn từ bên ngoài (theo dõi tệp/Webhook/CI) để đánh thức agent. Các hook API này cũng được xuất trong `@mariozechner/pi-coding-agent/hooks`. Harness cộng đồng ([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness)) tiếp tục đóng gói bề mặt hook thành các phần mở rộng có sẵn như skill-router, session-summary, extract-patterns và telemetry.++Phần mở rộng là quyết định thiết kế quan trọng nhất của Pi: **nó không chỉ “cho người dùng vài công tắc”, mà cung cấp toàn bộ bề mặt sự kiện bên trong runtime.** Muốn thêm bộ nhớ? Chèn ở `agent/pre-step`. Muốn ghi lại hành vi? Đăng ký sự kiện session. Muốn sửa yêu cầu gửi đến mô hình? Gắn hook vào `agent/request`. Bạn có thể để Pi tự sửa harness của chính nó — điều này gần với định nghĩa “harness có thể lập trình” hơn bất kỳ “tùy chọn cấu hình” nào.++## Phản hồi và xác minh: biến cả “học hỏi” thành harness++Bản thân Pi không tích hợp cổng kiểm thử bắt buộc (người dùng phải viết lệnh xác minh trong AGENTS.md), nhưng harness cộng đồng ([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness)) đã dùng phần mở rộng để cấu trúc hóa “vòng phản hồi”; phần Hooks trong README chính thức cũng cung cấp nền tảng cơ chế tương tự:++- **session-summary** (phần mở rộng pi-agent-harness): duy trì các mục cuộn trong `PROGRESS.md` — đây là hệ thống con trạng thái của khóa học, dùng để theo dõi tiến độ tác vụ dài.+- **extract-patterns** (phần mở rộng pi-agent-harness): thu thập các bài học ứng viên từ phiên và lưu vào `LESSONS.md` — biến việc “bàn giao đầy đủ trước khi kết thúc mỗi phiên” từ quy ước thành cơ chế.+- **telemetry** (phần mở rộng pi-agent-harness): ghi lại lượng token sử dụng, chi phí, v.v. — khả năng quan sát.++Cùng repository cộng đồng đó còn xác minh thêm mô hình này: `VISION.md` (mục tiêu), `PROGRESS.md` (tiến độ), `LESSONS.md` (bài học), `STANDARDS.md` (tiêu chuẩn), tất cả đều là tệp Markdown được duy trì xuyên phiên. Cách làm này giống hệt “repository là nguồn sự thật + tệp tiến độ + cơ chế bàn giao” mà khóa học đề xuất, chỉ khác là cơ chế mở rộng của Pi biến nó thành một tầng dùng được ngay.++## Ánh xạ vào khung của khóa học++Dùng năm hệ thống con của khóa học để chấm điểm Pi (mang tính chủ quan, dùng để đối chiếu):++| Hệ thống con | Cách Pi triển khai | Đánh giá |+| --- | --- | --- |+| Chỉ dẫn | Tải AGENTS.md theo cấp + SYSTEM.md | Phân cấp rõ ràng, nhưng quy tắc phải do người dùng viết |+| Công cụ | Kỹ năng tải theo nhu cầu + hook toàn vòng đời của phần mở rộng | Rất mạnh, biến hệ thống công cụ thành bề mặt có thể lập trình |+| Môi trường | SYSTEM.md tự mô tả môi trường; môi trường runtime do người dùng khai báo trong AGENTS.md | Cơ chế mở, nhưng khả năng tái tạo phụ thuộc vào mô tả của người dùng |+| Trạng thái | Cây phiên + nén tùy chỉnh + PROGRESS.md | Rất mạnh, xuyên phiên và khả năng khôi phục là trọng tâm |+| Phản hồi | Lệnh xác minh do người dùng định nghĩa; cơ chế hóa session-summary / extract-patterns | Cung cấp cơ chế, nội dung do người dùng quyết định |++Sự đánh đổi của Pi đối lập rõ rệt với Claude Code / Codex: Claude Code đưa “bộ nhớ, quyền hạn, agent con” vào lõi để dùng ngay; Codex biến “quy chuẩn repository, cô lập môi trường” thành mặc định; Pi chọn **không quyết định thay bạn bất cứ điều gì** — nó biến quyền quyết định thành điểm mở rộng. Cái giá là bạn phải tự viết phần mở rộng hoặc cài gói do người khác viết.++## Những thiết kế đáng học hỏi++1. **Biến chiến lược nén thành thành phần có thể cắm thay**. Trong harness của bạn, “nén ngữ cảnh như thế nào” không nên là tham số viết cứng mà nên là giao diện chiến lược có thể thay thế.+2. **Dùng cây phiên thay cho bản tóm tắt cứng**. Khôi phục xuyên phiên không nhất thiết phải dựa vào “tóm tắt lượt trước”; phát lại lịch sử có cấu trúc thường là hệ thống con trạng thái đáng tin cậy hơn.+3. **Thân thiện với prompt cache**. Tải kỹ năng theo nhu cầu, không nhồi tất cả quy tắc vào system prompt cùng lúc; đây vừa là kỹ thuật ngữ cảnh vừa là kỹ thuật chi phí.+4. **Để agent có thể sửa harness của chính nó**. Nếu bề mặt mở rộng của harness đủ mở, chính agent có thể bán tự động thực hiện việc “tối ưu hành vi agent”.++## Nguồn tham khảo (nguyên văn / mã nguồn)++Mọi luận điểm đều có thể truy ngược về nguyên văn hoặc mã nguồn dưới đây, tránh thuật lại theo ấn tượng:++- **Trang chủ pi.dev**: nguyên văn định vị “Ask Pi to build what you want, or install a package that does it your way”, bốn tầng có thể tùy chỉnh, cây phiên (“sessions are stored as trees”, `/tree`, lưu trong một tệp, xuất HTML / chia sẻ gist).<br/>https://pi.dev/+- **Tài liệu chính thức pi.dev · Sessions**: nén có thể cắm thay (topic-based / code-aware / đổi mô hình tóm tắt), mô tả cơ chế nén tự động và chèn ngữ cảnh động.<br/>https://pi.dev/docs/usage/sessions+- **Tài liệu chính thức pi.dev · Extensions**: phần mở rộng có thể chèn tin nhắn trước mỗi lượt suy luận, lọc lịch sử, thực hiện RAG và xây dựng bộ nhớ dài hạn.<br/>https://pi.dev/docs/usage/extensions+- **Tài liệu chính thức pi.dev · Project Context**: ngữ nghĩa replace / append của SYSTEM.md.<br/>https://pi.dev/docs/usage/project-context+- **README mã nguồn Pi Coding Agent** (badlogic/pi-mono): thứ tự tải ba cấp AGENTS.md (toàn cục → thư mục cha → thư mục hiện tại), điều kiện kích hoạt `/compact` và nén tự động cùng điểm cắt 20 nghìn token, tải Skills theo nhu cầu và tiêu chuẩn Agent Skills, vòng đời Hooks cùng các ví dụ chính thức, Programmatic Usage (JSON / RPC / SDK).<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **Repository cộng đồng pi-agent-harness**: các phần mở rộng skill-router / session-summary / extract-patterns / telemetry, cùng hệ thống tệp VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.<br/>https://github.com/LabidySabidy/pi-agent-harness++Giáo trình liên quan: [Bài 2 · Harness thực chất là gì](../lectures/lecture-02-what-a-harness-actually-is/) | [Bài 5 · Duy trì tính liên tục của tác vụ xuyên phiên](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [Bài 13 · Từ điều khiển thủ công đến vòng lặp tự động](../lectures/lecture-13-loop-engineering/)diff --git a/docs/vi/index.md b/docs/vi/index.mdindex def95ef..0d7e179 100644--- a/docs/vi/index.md+++ b/docs/vi/index.md@@ -26,6 +26,10 @@ Hãy chọn lộ trình phù hợp để bắt đầu hành trình của bạn.<h3>Thư viện Tài nguyên</h3><p>Các mẫu sẵn sàng sao chép (AGENTS.md, feature_list.json) để bạn đưa vào kho lưu trữ của riêng mình.</p></a>+ <a href="./harness-designs/" class="card">+ <h3>Phân tích các harness tiên tiến</h3>+ <p>Pi, Claude Code, Codex và DeepSeek thực sự thiết kế harness của họ như thế nào — gắn với khung của khóa học.</p>+ </a></div>## Cơ chế cốt lõi của một Harnessdiff --git a/docs/zh-TW/harness-designs/claude-code/index.md b/docs/zh-TW/harness-designs/claude-code/index.mdnew file mode 100644index 0000000..a126ff3--- /dev/null+++ b/docs/zh-TW/harness-designs/claude-code/index.md@@ -0,0 +1,88 @@+# 拆解 Claude Code 的 harness 設計++Anthropic 在《[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)》中明確提出:可靠性來自 harness 而不是模型,agent 需要在「模型之外」受到約束。Claude Code 就是這個思路的產品化範例,Anthropic 官方也直接把它歸入 **agentic harness** 的範疇。這不是行銷話術——Claude Code 可能是目前公開拆解得最透徹的 harness:原始碼公開、社群研究報告詳盡,而且它把課程講義裡幾乎所有核心機制(分層記憶、上下文壓縮、permissions、hooks、subagent、session 持久化)都做成完整的產品化實作。++這一篇我們用課程五子系統框架拆解 Claude Code,重點看它如何落實「上下文管理」「防止提前宣告完成」「確定性約束」這些 harness 的原教旨概念。++## 一句話定位++Claude Code 的核心是一個簡單的 while 循環:呼叫模型、執行工具、觀察結果、再次呼叫模型。但**絕大部分程式碼不在這個循環裡,而是在圍繞循環的系統中**——permissions 系統、上下文壓縮管線、擴充機制、subagent 編排、session 儲存。這就是 harness 的本質:循環是骨架,骨架以外的一切才是決定可靠性的部分。++## 指令子系統:分層記憶體系++Claude Code 的記憶系統是它對 harness 理論最直接的貢獻,對應課程中的「儲存庫即事實來源」和「跨 session 上下文連續」兩講。[官方文件《How Claude remembers your project》](https://code.claude.com/docs/en/memory)明確說明:每次 session 都從全新的上下文視窗開始,透過兩類機制跨 session 攜帶知識——CLAUDE.md 檔案(你寫的指令)和 auto memory(Claude 自己寫的筆記)。++就作用範圍而言,官方把 CLAUDE.md 檔案分成四類(依載入順序由廣到窄):++- **組織原則層級**:由 IT/DevOps 統一管理(例如 `/etc/claude-code/CLAUDE.md`),公司層級的規範。+- **使用者層級 `~/.claude/CLAUDE.md`**:跨專案的個人偏好與規則。+- **專案層級 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`**:專案層級的事實來源,包括工程結構、技術堆疊、驗證指令,隨儲存庫共享。+- **本機層級 `./CLAUDE.local.md`**:個人在專案內的偏好,通常加入 `.gitignore` 而不提交。++此外還有兩項機制:++- **子目錄層級隨選載入**:子目錄裡的 CLAUDE.md 不會在啟動時載入,而是在 Claude 讀取該目錄的檔案時才進入上下文。+- **自動記憶(auto memory)**:Claude 會根據你的糾正和偏好主動寫筆記,依儲存庫共享、跨 worktree 生效,每個 session 最多載入前 200 行或 25KB。++這四種作用範圍構成一個**指令層級**:官方文件說「越具體的指令越晚進入上下文」(專案指令出現在使用者指令之後)。它的價值在於:不是讓模型在每次對話開頭消化一整篇巨型指令,而是依作用範圍就近載入。這正是課程第四講「為什麼單一巨型指令檔案會失敗」的產品化答案。++## 上下文子系統:五層壓縮管線++Claude Code 對上下文的管理是一套**五層 compaction 管線**(five-layer compaction pipeline),不是「滿了就摘要」這麼簡單——這項架構細節來自 [VILA Lab 的《Dive into Claude Code》](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf)原始碼層級拆解。課程第五講談「長任務會失去連續性」,Claude Code 的解法是多級漏斗:先進行無損修剪(移除冗餘工具結果),再進行結構化提煉,最後才使用有損的 LLM 摘要,並搭配熔斷機制避免過度壓縮。++與它搭配的是 session 儲存設計:**附加導向的 session 儲存(append-oriented storage)**,所有歷史都附加寫入 `history.jsonl`,支援 `/resume` 復原和 fork 分支。這保證了「每次 session 結束前都做好交接」——不是因為記性好,而是因為儲存層採用附加方式,並且可以重播。++## 工具子系統:四種擴充機制++Claude Code 把擴充介面分成四類,每一類解決一種問題,這是它的設計中最值得借鑑的部分:++- **技能(Skills)**:[官方文件](https://code.claude.com/docs/en/skills)定義——由 `SKILL.md` 描述的程序性知識,依觸發詞自動載入,採漸進式揭露。適合「如何做某件事」的領域知識。+- **MCP**:[官方文件](https://code.claude.com/docs/en/mcp)中的 JSON-RPC 協定會連接外部系統,是「讓模型的手能伸到外部世界」的標準介面。+- **hooks(Hooks)**:[官方文件](https://code.claude.com/docs/en/hooks)掛在 `PreToolUse`、`PostToolUse`、`Stop` 等生命週期事件上的確定性腳本。+- **plugin / subagent(Subagents)**:[官方文件](https://code.claude.com/docs/en/sub-agents)把複雜任務拆給專門化的 agent 執行。++關鍵設計是**職責分離**:CLAUDE.md 管「是什麼」,技能管「怎麼做」,MCP 管「連到哪裡」,hooks 管「何時強制」。團隊如果混用這幾層(例如把 MCP 負責的事寫進 CLAUDE.md),就會出現課程所說的上下文滲漏。++## 回饋與驗證:確定性約束 + 人機分工++課程第十講談「跑通完整流程才算真正驗證」,Claude Code 對應的機制是雙軌制:++**1. permissions 系統(確定性約束)。** Claude Code 的 permissions 不是「全部都詢問一遍」,而是七種模式 + 一個基於 ML 的分類器:低風險操作放行,高風險操作則依原則詢問或拒絕(架構細節請參閱 [VILA Lab 拆解](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf))。這是把「為 agent 劃清邊界」(第七講)做成執行時期的強制機制,而不是靠提示詞懇求。++**2. hooks(防止提前宣告完成)。** `PostToolUse` hooks 可以在工具執行後強制進行檢查、把結果寫回上下文;`Stop` hooks 則在 agent 宣告完成時介入。這就是「做事的人和檢查的人分開」——[Anthropic 在 harness 文章裡明確觀察到](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents),agent 會自信地稱讚自己的工作("confidently praised their work"),因此用 hooks 注入**確定性**檢查,而不是信任模型的自我評估。++**3. subagent(隔離上下文)。** 每個 subagent 的對話記錄都存在獨立的 sidechain 檔案裡,**不會膨脹父 agent 的上下文**(請參閱 [VILA Lab 拆解](https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf))。這是「任務邊界」和「上下文隔離」的結合:拆分任務的同時,也隔離上下文污染。++## 可觀測性與 session 持久化++Claude Code 的日誌是完整的附加式記錄(history.jsonl),加上 `/compact`、`/clear`、`/init` 這些明確指令,讓你能主動管理上下文狀態,而不是被動等它滿。`/init` 更是把「讓 agent 每次工作前先初始化」(第六講)做成一條指令——[官方文件](https://code.claude.com/docs/en/memory)指出,它會自動分析程式碼庫並產生初始 CLAUDE.md(包括建置指令、測試說明、工程慣例)。++## 對應到課程框架++| 子系统 | Claude Code 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 作用域分层(组织/用户/项目/本地)+ 自动记忆 | 分层记忆是标杆实现 |+| 工具 | 技能 + MCP + 钩子 + 子智能体四类扩展 | 职责划分清晰,是核心亮点 |+| 环境 | 项目内设置 + settings.json | 靠用户在 CLAUDE.md 里自描述 |+| 状态 | 追加式会话存储 + 五层压缩 + resume/fork | 极强,长任务连续性的参考实现 |+| 反馈 | 权限分类器 + PostToolUse 钩子强制检查 | 把"防提前宣告完成"变成确定性机制 |++## 值得借鑑的設計++1. **指令依作用範圍分層**,而不是堆在單一檔案裡。目錄層級的 CLAUDE.md 是「就近載入」的漂亮實作。+2. **compaction 是分級漏斗**:先無損、後有損,不要一開始就做全文摘要。+3. **用 hooks 進行確定性檢查**:防止提前宣告完成,靠的是執行時期強制,而不是提示詞懇求。+4. **subagent 上下文隔離**:拆任務的同時也拆上下文,不要讓子任務的結果污染主循環。+5. **session 儲存採附加式 + 可重播**:交接不是靠記憶,而是由儲存層保證。++## 參考來源(原文 / 原始碼)++每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:++- **Claude Code 官方文档 · Memory**:每次 session 使用全新上下文、CLAUDE.md 四種作用範圍、子目錄隨選載入、auto memory(200 行 / 25KB)、`/init` 產生 CLAUDE.md。<br/>https://code.claude.com/docs/en/memory+- **Claude Code 官方文档 · Skills / MCP / Hooks / Sub-agents**:四種擴充機制的定義與事件(PreToolUse / PostToolUse / Stop)。<br/>https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents+- **VILA Lab《Dive into Claude Code》**(原始碼層級拆解報告):五層 compaction 管線、permissions 七種模式 + ML 分類器、sidechain subagent、附加式 session 儲存 history.jsonl。<br/>https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf+- **Anthropic《Effective harnesses for long-running agents》**:「可靠性來自 harness 而非模型」、agent 會自信地稱讚自己的工作、用 hooks 進行驗證等觀點的出處。<br/>https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents+- **Claude Code Full Stack 导读**(社群,CLAUDE.md / Skills / MCP / Subagents / Hooks 分層):作為擴充機制職責分離的補充閱讀。<br/>https://jsmanifest.com/claude-code-full-stack-guide++相關講義:[第三講 · 讓程式碼儲存庫成為唯一的事實來源](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [第九講 · 防止 agent 提前宣告完成](../lectures/lecture-09-why-agents-declare-victory-too-early/) | [第十講 · 跑通完整流程才算真正驗證](../lectures/lecture-10-why-end-to-end-testing-changes-results/)diff --git a/docs/zh-TW/harness-designs/codex/index.md b/docs/zh-TW/harness-designs/codex/index.mdnew file mode 100644index 0000000..d387aa6--- /dev/null+++ b/docs/zh-TW/harness-designs/codex/index.md@@ -0,0 +1,78 @@+# 拆解 Codex 的 harness 設計++OpenAI 的 [Codex](https://openai.com/index/harness-engineering/) 可能是四款產品裡與「harness 原教旨」連結最深的一個——那篇定義整個領域名稱的《Harness Engineering》文章,本身就是 OpenAI 團隊使用 Codex 開發產品時的經驗總結。因此,拆解 Codex 的 harness 設計,很大程度上就是拆解那篇文章背後的工程實務。++Codex 的哲學可以濃縮成一句話:**儲存庫即事實來源(repository as the system of record),AGENTS.md 只是目錄頁,工程的價值在於設計環境、表達意圖、建構回饋循環。**++## 一句話定位++OpenAI 團隊使用 Codex,在幾週內交付了一個最後達到上百萬行程式碼的產品,**每一行程式碼都是 Codex 寫的**(原文請參閱 [Harness Engineering](https://openai.com/index/harness-engineering/) 的 "Designing for growth" 一節)。他們的實務回答了一個問題:當工程師的角色從「寫程式碼」變成「設計 harness」時,系統應該如何組織。Codex CLI 本身是開放原始碼的單體二進位檔(以 Rust 實作,[github.com/openai/codex](https://github.com/openai/codex)),但它對 harness 的貢獻主要在於**慣例(convention)**和**上下文工程**,而不是花俏的擴充點。++## 指令子系統:AGENTS.md 是目錄頁,不是百科全書++這是 Codex 對 harness 理論最具影響力的一項設計:++> 單一巨型指令檔案不利於機械化檢查(涵蓋率、更新狀態、所有權、交叉連結),偏離現實的情況無法避免。因此,我們不再把 AGENTS.md 視為百科全書,而是將它視為**目錄頁**。程式碼庫知識位於結構化文件中,AGENTS.md 負責指向它們。++(以上直接轉述自 [《Harness Engineering》原文](https://openai.com/index/harness-engineering/) 中 "AGENTS.md should be a directory page" 一節。)++課程第四講說「單一巨型指令檔案會失敗」,Codex 直接給出正解:把 AGENTS.md 控制在 100 行左右(原文建議約 100 行,接近上限就拆到 `docs/`),放不下的內容就拆分到 `docs/` 目錄,讓 agent 隨選讀取。這是「給地圖,不給說明書」的權威出處。++搭配的原則稱為**執行不變量,不要微觀管理實作**(原文:"don't micromanage the implementation;focus on invariants"):AGENTS.md 只寫不可違反的硬性約束和驗證指令,具體如何實作則交給模型。這直接對應課程第二講的「約束而非微觀操控」。++## 上下文子系統:Write-Select-Compress-Isolate++Codex 的上下文工程可概括為四種策略。這是社群在 "context engineering" 成為獨立學科後,總結並對應回 Codex 的框架(框架出處請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/)):++- **Write(寫出去)**:把上下文持久化到視窗之外——把結論寫入文件、把狀態寫入檔案,而不是留在對話裡。對應「儲存庫即事實來源」。+- **Select(選進來)**:只把需要的 token 拉進視窗——由 AGENTS.md 指路、隨選讀取檔案,而不是把整個儲存庫塞進去。+- **Compress(壓縮)**:保留真正重要的內容——Codex 有自動 compaction 和手動 `/compact`,可以自訂 `compact_prompt`(請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/))。+- **Isolate(隔離)**:把上下文切分到不同邊界——使用 subagent 隔離不同任務的上下文,前端 subagent 永遠看不到後端的資料庫 schema。++Codex 還有一項很細緻的環境上下文設計:社群對 [codex-harness-internals](https://github.com/AlexKenbo/codex-harness-internals) 的原始碼分析顯示,`build_environment_update_item` 只在環境變更時輸出**有變動的欄位**(CWD、git 分支、檔案系統),而不是每一輪都貼上一遍完整的系統上下文。這是「不要在上下文裡保留重複 token」的工程細節。++## 工具與邊界:worktree 隔離 + subagent++Codex 有兩項核心 harness 機制:++**1. git worktree 隔離環境。** [《Harness Engineering》原文](https://openai.com/index/harness-engineering/) 的 "Environment" 一節明確指出:每個任務都在獨立的 git worktree 裡執行,搭配本機可觀測性堆疊(日誌、指標、追蹤),讓每項變更都在獨立環境中驗證。這就是課程第七講「為 agent 劃清每次任務的邊界」的實體實作——邊界不是靠指令懇求,而是由環境隔離強制執行。環境(environment)子系統在此成為硬隔離。++**2. 核心層級 subagent。** Codex 的 `spawn_agent` / `wait_agent` 是核心層級工具:模型明確建立 subagent、給它獨立的 session 歷史和工具集,並等待結果。subagent 會繼承父層的 AGENTS.md 指令,但在**自己的上下文**裡執行。設定放在 `.codex/agents/*.toml`,可指定不同模型和指令(細節請參閱 [Context Engineering for Codex CLI](https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/) 的 Sub-agents 一節)。這是「上下文隔離」的直接實作——也體現了課程第十二講的「交接」精神:每個 subagent 都是邊界清楚的工作單元。++## 回饋子系統:把驗證指令寫進規範++OpenAI 的實務最強調的一點是:在 AGENTS.md 裡明確列出驗證指令,把「如何確認做對了」變成儲存庫的一部分。Codex 的工程流程中,測試、CI、文件、可觀測性設定——全都由 Codex 產生,而且全都是「可執行的驗證路徑」。模型能力強卻不可靠的解法,不是祈禱模型自律,而是讓**驗證路徑成為 harness 的預設元件**。++核准原則(approval policies)和計畫模式(plan mode)則是另一個回饋方向:執行高風險操作前先提出計畫、先取得核准,把「任務邊界」和「人類決策權」做成執行時期控制。++## 對應到課程框架++| 子系统 | Codex 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 目录页 + docs/ 拆分 + 执行不变量 | 教科书级,定义了"给地图不给说明书" |+| 工具 | worktree 隔离 + spawn_agent 子智能体 | 边界靠环境硬隔离,很强 |+| 环境 | 独立 worktree + 可观测性栈 | worktree 隔离是其招牌 |+| 状态 | Write 策略(状态写进文件/文档) | 依赖约定而非内建记忆 |+| 反馈 | 验证命令入规范 + 审批策略 + plan mode | 反馈路径默认化,值得抄 |++Codex 和 Claude Code 的對比很有意思:Claude Code 是「加法」——把記憶、permissions、subagent 全都做到核心裡;Codex 是「減法」——核心盡量保持克制,把更多責任放在儲存庫慣例和上下文工程上。這也是為什麼社群常說「Codex 的 harness 哲學比它的程式碼更有價值」。++## 值得借鑑的設計++1. **把 AGENTS.md 當成目錄頁來寫**:控制在 100 行左右,指向 docs/ 裡的細節,並可進行機械化檢查。+2. **只寫不變量,不微觀管理實作**:硬性約束 + 驗證指令,其餘交給模型。+3. **用 worktree 進行環境隔離**:任務邊界由環境強制執行,不靠指令懇求。+4. **環境上下文只傳增量**:每輪只輸出變動的欄位,不要重複貼上完整的系統上下文。+5. **用 subagent 隔離上下文**:拆任務的同時也拆上下文,不要讓子任務污染主循環。++## 參考來源(原文 / 原始碼)++每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:++- **OpenAI《Harness Engineering》**:AGENTS.md 目錄頁和約 100 行的建議、executive invariants / don't micromanage、worktree 隔離 + 可觀測性堆疊、把驗證指令寫入規範、上百萬行產品案例、核准原則與 plan mode。本篇所有核心論述的主要出處。<br/>https://openai.com/index/harness-engineering/+- **OpenAI 官方《AGENTS.md》规范**(AGENTS.md 作為跨工具慣例的標準):<br/>https://openai.com/index/agents-md/+- **Codex CLI 开源仓库**(以 Rust 實作的單體二進位檔):<br/>https://github.com/openai/codex+- **Context Engineering for Codex CLI**(社群):Write-Select-Compress-Isolate 框架、`/compact` 與 `compact_prompt`、`spawn_agent` / `wait_agent` subagent 與 `.codex/agents/*.toml` 設定。<br/>https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/+- **codex-harness-internals**(社群原始碼分析):`build_environment_update_item` 增量環境上下文等實作細節。<br/>https://github.com/AlexKenbo/codex-harness-internals++相關講義:[第三講 · 讓程式碼儲存庫成為唯一的事實來源](../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/) | [第四講 · 把指令拆分到不同檔案裡](../lectures/lecture-04-why-one-giant-instruction-file-fails/) | [第七講 · 為 agent 劃清每次任務的邊界](../lectures/lecture-07-why-agents-overreach-and-under-finish/)diff --git a/docs/zh-TW/harness-designs/deepseek/index.md b/docs/zh-TW/harness-designs/deepseek/index.mdnew file mode 100644index 0000000..767de22--- /dev/null+++ b/docs/zh-TW/harness-designs/deepseek/index.md@@ -0,0 +1,87 @@+# 拆解 DeepSeek Harness 的設計++[DeepSeek Harness](https://deepseek.com/harness)(指令名稱 `dsh`,儲存庫 `deepseek-ai/deepseek-harness`)於 2026 年 8 月以 Developer Preview 形式發佈,官方給出的定義很直接:**Agent = Model + Environment + Tools + State**——模型、環境、工具、狀態,四件套。++如果前三個產品的拆解是在問「harness 應該如何設計」,DeepSeek Harness 問的是更激進的問題:**harness 能不能脫離特定模型,成為一種獨立的執行時期?** 它的答案是可以,而且把這件事做到了極致——[架構文件](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)的原文是:*Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself*(產品的每一部分都是 plugin,包括模型轉接器、工具登錄檔、session 日誌,甚至 agent 循環本身)。++這一篇我們拆解它,重點看三件事:plugin 化的核心、能力接縫(capability seam)、事件管線,以及那項最強的工程約束 "Model-visible means logged"。++## 一句話定位++傳統 coding agent 的結構是「LLM + 固定的 agent 循環 + 固定的工具集」。DeepSeek Harness 的結構是「模型 + 一個 plugin 核心(Cordis)」,核心只負責 plugin 的載入、卸載、相依關係和事件機制,**不擁有任何 agent 的具體能力**——[架構文件](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)的原文是 "There is no privileged core to patch"(不存在需要修補的特權核心),"you extend dsh by mounting a plugin beside the others"(只要在一旁掛載一個 plugin 即可擴充,不必修改核心)。這表示連 agent 循環本身都不是神聖不可修改的——你可以使用 DeepSeek 的模型、接上 Claude Code 的 subagent、採用遠端沙箱、編寫自訂記憶、替換自訂循環、替換自訂 UI,組成一個全新的 agent。++這是對課程「模型權重以外的一切都是 harness」這句話最徹底的貫徹:既然 harness 是獨立的,就讓它獨立成為一個作業系統。++## 架構核心 1:能力接縫(Capability Seam)++DeepSeek Harness 使用 Service 表示「能力」,幾乎每項能力都拆成三層:++```+Service Definition(能力定义)+ ↓+Service Provider(能力提供者)+ ↓+Consumer(能力消费者)+```++以檔案系統為例:`FS Service` 下面有 Local FS、E2B FS、Remote FS 等多個 Provider,向上統一公開為 file tools。Shell、Subprocess、Sandbox、Web、LLM、SubAgent 都採用同一套結構。這套三層結構不是我們總結的——[架構文件 · Capability seams](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)原文就是:*a seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool*(能力接縫 = 可替換的能力,包含三種角色:宣告介面的 Service Definition、實作它的 Service Provider,以及使用它的 Consumer;後者通常是面向模型的工具)。++這解決了 harness 工程裡長期存在的問題:**agent 究竟應該依賴「具體工具」,還是依賴「能力介面」?** DeepSeek Harness 選擇後者。對課程而言,這表示「工具子系統」被標準化為介面——更換 Provider 後,工具對模型公開的樣貌不變,但環境徹底改變。++## 架構核心 2:事件管線(Event Pipeline)++DeepSeek Harness 內部不是簡單的「LLM → 工具 → LLM」,而是一條事件管線,每個環節都是 plugin 可以監聽的事件點:++```+turn/start → claim input → assemble(system prompt / context / tools)+ → agent/pre-step → step/start → LLM request(agent/request)→ llm/stream+ → assistant/message → tool/call+ → tools/pre-execute(permission / guard / policy / hook)+ → tools/execute → tools/post-execute → tool/result → step/end → 下一轮+```++(上面的管線轉寫自 [架構文件 · Turn flow](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) 一節:`turn/*`、`step/*`、`user/message`、`assistant/*`、`tool/*` 是持久化的 session 事件,`agent/pre-step`、`agent/request`、`llm/stream`、`tools/*` 則是 plugin 可以監聽的擴充點。)++這項設計最大的好處是:**大量功能根本不必修改 agent 循環本身**。想在工具執行前進行安全檢查?監聽 `tools/pre-execute`。想加入記憶?在 `agent/pre-step` 注入。想記錄行為?訂閱 session 事件。想修改模型請求?掛接 `agent/request`。想決定是否繼續推理?監聽 `agent/turn-stopping`。++對照課程第十一講「讓 agent 的執行過程可觀測」,DeepSeek Harness 走得更遠:它不是「加入日誌」,而是讓**循環的每一步都成為事件點**,使可觀測性、permissions、記憶、原則全部以監聽器的身分掛在循環上,而不是寫死在循環裡。++## 架構核心 3:Session Event Log 與 "Model-visible means logged"++DeepSeek Harness 有一個 **append-only 的 Session Event Log(僅附加的 session 事件日誌)**,並訂出一項非常強的工程約束。[架構文件 · Session log](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)的原文是:++> **Model-visible means logged.** Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.++(凡是模型能看到的,都必須記錄。任何進入模型請求的內容都必須能從日誌重建,而且有一項執行時期不變量會強制檢查這一點。)++換句話說,可觀測性不是事後補上的日誌,而是 harness 的第一性約束:任何進入模型上下文的內容,預設都應該留下日誌。這直接呼應收官之夜的「可觀測性屬於 harness 內部」,並把 "append-only" 這項儲存設計化為原則——日誌只附加、不覆寫,session 狀態可以重播。++## 對應到課程框架++| 子系统 | DeepSeek Harness 的实现 | 评价 |+| --- | --- | --- |+| 指令 | 插件化;规则/技能均以插件形态注入 | 极自由,但没有内置的"CLAUDE.md"式惯例 |+| 工具 | Service Definition → Provider → Consumer 能力接缝 | 工具子系统标准化的极致 |+| 环境 | 沙箱/FS/Shell 全部可换 Provider(含远程 E2B) | 环境彻底可插拔 |+| 状态 | append-only Session Event Log + Model-visible means logged | 可观测性是第一性约束 |+| 反馈 | tools/pre-execute 上的 permission / guard / policy / hook | 反馈机制事件化 |++DeepSeek Harness 和其他三款產品的根本差異在於:Pi、Claude Code、Codex 都是在「一個具體的 agent」內部最佳化 harness;DeepSeek Harness 則把 harness 定義成**獨立於模型的作業系統**,agent 本身只是這套 OS 上的可替換應用程式。代價也很明顯——自由度高表示設定成本也高,這是「harness 即 OS」這套設計固有的另一面(開發者預覽階段的定位也是「搶先體驗、機制仍在演進」)。++## 值得借鑑的設計++1. **讓循環的每一步都成為事件點**:permissions、記憶、原則、日誌都以監聽器的身分掛在循環上,而不是寫死在循環裡。+2. **標準化能力接縫**:依賴「能力介面」而不是「具體工具」,環境可以整組替換而不影響模型看到的工具介面。+3. **Model-visible means logged**:凡模型能看到的內容都必須記錄,把可觀測性從「加分項」變成「第一性約束」。+4. **append-only session 日誌**:狀態可以重播、交接可靠,這是「每次 session 留下乾淨狀態」的工程化保證。++## 參考來源(原文 / 原始碼)++每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:++- **DeepSeek Harness 官网**:產品定義 "Agent = Model + Environment + Tools + State"、Developer Preview 定位與 `dsh` 指令。<br/>https://deepseek.com/harness+- **deepseek-ai/deepseek-harness 仓库**(指令 `dsh`,MIT 授權條款):<br/>https://github.com/deepseek-ai/deepseek-harness+- **架构文档 architecture.md**:本篇最核心的出處——"Every part of the product is a plugin"、"There is no privileged core to patch"、Turn flow 事件管線、Capability seams 三層角色、"Model-visible means logged" 與執行時期不變量、append-only Session Event Log、fs/tools/telemetry 等能力接縫與 `ctx.*` 子系統。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md+- **架构文档 · 配套子文档**:Cordis 核心簡介(plugins contribute services, typed events, reversible effects)、能力接縫細節、Session 子系統。<br/>https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/capability-seams.md | https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.md++相關講義:[第十一講 · 讓 agent 的執行過程可觀測](../lectures/lecture-11-why-observability-belongs-inside-the-harness/) | [第十二講 · 每次 session 結束前都做好交接](../lectures/lecture-12-why-every-session-must-leave-a-clean-state/) | [第二講 · Harness 到底是什麼](../lectures/lecture-02-what-a-harness-actually-is/)diff --git a/docs/zh-TW/harness-designs/index.md b/docs/zh-TW/harness-designs/index.mdnew file mode 100644index 0000000..874acaf--- /dev/null+++ b/docs/zh-TW/harness-designs/index.md@@ -0,0 +1,29 @@+# 前沿 Harness 拆解++這個專欄把課程講義提到的 harness 理論,逐一對照目前最前沿的真實產品。每個產品我們只關心一件事:**它的 harness 是怎麼設計的**——也就是模型周圍的那一層工程基礎設施:指令、工具、環境、狀態、回饋這五個子系統,以及上下文連續性、初始化、驗證、可觀測性、交接、循環這些核心機制。++我們刻意不談模型的推理能力強不強、不談某次跑分高不高,也不籠統介紹「這個 agent 能做什麼」。那些是模型層和產品層的問題。這裡只拆解 harness——模型權重以外的一切。++## 為什麼值得拆解++講義第一講提過:模型能力強,不等於執行可靠。同一套模型,放在不同的 harness 裡,表現可能相差一個數量級。但講義談的是「應該怎麼做」,這些產品回答的則是「頂尖團隊實際怎麼做」。++每個產品都是一組獨立的設計決策。把它們放在一起對照,你會看到相同的核心機制,被不同團隊以截然不同的方式實作:++- **Pi** 把 harness 做成極簡核心 + 可程式化擴充,靠「最小系統提示 + 隨選載入」進行上下文工程。+- **Claude Code** 把 harness 做成完整的執行環境:分層記憶、五級壓縮、permissions、hooks、subagent。+- **Codex** 把 harness 的哲學推到極致:儲存庫即事實來源,AGENTS.md 只是目錄頁,使用 worktree 隔離環境。+- **DeepSeek Harness** 乾脆把 harness 本身定義成一種獨立於模型的執行時期:Everything is a Plugin。++## 文章列表++- [拆解 Pi 的 harness 設計](./pi/):極簡核心 + 可程式化擴充,把上下文工程做到系統提示之外。+- [拆解 Claude Code 的 harness 設計](./claude-code/):分層記憶、五級壓縮、permissions 與 hooks,一個完整的 agent 執行環境。+- [拆解 Codex 的 harness 設計](./codex/):儲存庫即事實來源,AGENTS.md 是目錄頁,環境隔離與回饋循環。+- [拆解 DeepSeek Harness 的設計](./deepseek/):Everything is a Plugin,把 agent 循環本身做成可替換的 plugin。++## 閱讀方式++建議先讀講義的前幾講(尤其是 [第二講:Harness 到底是什麼](../lectures/lecture-02-what-a-harness-actually-is/))建立五子系統框架,再回到這裡看真實產品如何實作這些機制。++每篇文章的末尾都有「對應到課程框架」和「值得借鑑的設計」兩節,協助你把產品設計快速轉換回課程概念,方便直接套用到自己的專案。diff --git a/docs/zh-TW/harness-designs/pi/index.md b/docs/zh-TW/harness-designs/pi/index.mdnew file mode 100644index 0000000..a3f5ff6--- /dev/null+++ b/docs/zh-TW/harness-designs/pi/index.md@@ -0,0 +1,94 @@+# 拆解 Pi 的 harness 設計++[Pi](https://pi.dev/)(npm 套件 `@earendil-works/pi-coding-agent`)自稱 "minimal agent harness"——極簡的 agent harness。這句話值得拆開來看:它沒有自稱「最強的 coding agent」,也沒有自稱「最好用的 AI 程式設計工具」,而是把自己的定位牢牢釘在 **harness** 這個詞上。++這一篇我們用課程的五子系統框架(指令、工具、環境、狀態、回饋)拆解 Pi,看看它的設計哲學和 Claude Code、Codex 有什麼根本差異。答案先說:**Pi 的哲學是「核心最小化 + 擴充可程式化」,把上下文工程做到系統提示之外,讓使用者(甚至 Pi 自己)修改 harness,而不是讓 Pi 替你決定 harness。**++## 一句話定位++Pi 是極簡核心:官方刻意把核心做小、把決定權交還給你——[pi.dev 首頁](https://pi.dev/)的原文是 "Ask Pi to build what you want, or install a package that does it your way"。它把 harness 拆成四層可自訂項目:++- **擴充(Extensions)**:掛在 Pi 生命週期事件上的 TypeScript hooks,執行時期(runtime)層級的可程式化介面。+- **技能(Skills)**:隨選載入的能力套件,包含指令和工具,漸進式揭露(progressive disclosure)。+- **提示範本(Prompt templates)**:可重複使用的 Markdown 提示,輸入 `/name` 即可展開。+- **主題(Themes)**:TUI 外觀。++這種分層思路本身就是一種 harness 設計:**把「模型能看到什麼、什麼時候能看到」完全交給規則和擴充,而不是寫死在核心裡。**++## 核心循環++Pi 和所有 coding agent 一樣,本質上是「推理 → 工具執行 → 觀察 → 再推理」的 while 循環。值得注意的不是循環本身,而是 Pi 對循環外層的處理:它把上下文管理這件事,從循環內部的「壓縮」擴展到循環外部的「控制」。++Pi 的執行時期對外公開可程式化介面——[原始碼 README 的 Programmatic Usage](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) 裡,除了互動式 TUI,還支援腳本化的列印/JSON 模式、RPC 協定與 SDK 嵌入。這決定了同一個 harness 既能由人逐條驅動,也能由 CI/CD 或其他程式自動驅動。它對應課程第十三講「循環工程」中「從手動驅動到自動循環」的前提:一個 harness 如果只能由人類互動驅動,就永遠無法進入自動循環。++## 指令子系統:AGENTS.md 與 SYSTEM.md++Pi 對「指令」的處理很克制,但層級清楚:++- **AGENTS.md**:[原始碼 README 的 Project Context Files](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md) 清楚列出載入順序——全域 `~/.pi/agent/AGENTS.md` → 逐層向上走訪父目錄 → 目前目錄 `./AGENTS.md`(也相容 CLAUDE.md)。這就是「儲存庫即事實來源」的貫徹——指令是檔案,不是聊天框裡的叮嚀。+- **SYSTEM.md**:[pi.dev 官方文件](https://pi.dev/docs/usage/project-context) 說明可依專案取代(replace)或附加(append)預設系統提示。這是 Pi 允許你修改「系統提示」的唯一正式入口,也是它的「環境自我描述」層。++Pi 官方強調它的系統提示本身**極簡**。背後是一個明確的取捨:核心不塞入「如果……那麼……」的冗長規則,而是保留擴充點,讓規則以技能和擴充的形式在需要時才出現。這直接呼應課程第四講「為什麼單一巨型指令檔案會失敗」——Pi 以「核心極簡 + 檔案拆分 + 隨選載入」自然避開巨型指令的問題。++## 狀態與上下文:Pi 拆得最細的地方++Pi 的上下文工程值得重點拆解,因為它把課程裡「上下文連續性」「防止上下文腐化」這些概念落實為具體機制:++**1. compaction 可程式化。** 接近上下文上限時,自動將舊訊息摘要化——[pi.dev 官方文件](https://pi.dev/docs/usage/sessions)說明 compaction 策略本身**可以自訂**:你可以用擴充實作基於主題的壓縮、能理解程式碼的摘要,甚至改用不同的模型來產生摘要。原始碼 README 也列出預設機制的細節:自動 compaction 會在兩種情況下觸發(上下文溢位復原 / 超過保留門檻),切割點會保留最近約 2 萬個 token,之前的訊息則摘要成 "context handoff" 並逐級鏈式壓縮。換句話說,Pi 不把「怎麼壓縮」視為不可修改的常數,而是視為 harness 的一部分。++**2. 動態上下文(Dynamic context)。** [pi.dev 官方文件](https://pi.dev/docs/usage/extensions)說明擴充可以在每一輪推理前注入訊息、過濾訊息歷史、實作 RAG、建構長期記憶。這比「上下文滿了再壓縮」更進一步:它讓你在上下文進入視窗前,就決定要放什麼、不放什麼。對應課程中的「讓 agent 的執行過程可觀測、可偵錯」和「保持上下文連續性」,Pi 把這兩件事下沉到擴充介面。++**3. session 樹(Session tree)。** [pi.dev 首頁](https://pi.dev/)明確寫著「session 以樹狀結構儲存(sessions are stored as trees),`/tree` 可以回到任意歷史節點繼續,所有分支都儲存在同一個檔案裡」。這解決了課程一再強調的「跨 session 上下文斷裂」問題——不是靠摘要硬接,而是靠結構化的歷史重播。分支可以匯出為 HTML,或上傳為 gist 分享,可觀測性也一併解決了。++## 工具子系統:技能與擴充++Pi 的「工具」分成兩層:++- **技能(Skills)**:[原始碼 README 的 Skills 一節](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)定義得很清楚——"self-contained capability packages that the agent loads on-demand",也就是隨選載入的能力套件,包含指令和工具,遵循 Agent Skills 標準。漸進式揭露讓技能細節只在觸發時才進入上下文,**不會塞爆提示快取(prompt cache)**。這是成本角度的 harness 設計:上下文每多一個 token,每次推理都要為它付費;把技能做成隨選載入,就是「給地圖,不給說明書」的另一種表達。+- **擴充(Extensions)**:掛在內建生命週期事件上的 TypeScript hooks——[原始碼 README 的 Hooks 一節](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md)列出四種官方範例用途:攔截危險指令(permissions 閘門)、切換任務時為程式碼建立 checkpoint、保護路徑(禁止寫入 `.env` 等)、修改工具輸出後再交給模型,以及從外部(檔案監看/Webhook/CI)注入訊息喚醒 agent。這些 hooks API 也在 `@mariozechner/pi-coding-agent/hooks` 裡匯出。社群 harness([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness))則進一步把 hooks 介面封裝成 skill-router、session-summary、extract-patterns、telemetry 等現成擴充。++擴充是 Pi 最重要的設計決策:**它不是「提供使用者幾個開關」,而是把執行時期內部的事件介面全部公開。** 想加記憶?在 `agent/pre-step` 注入。想記錄行為?訂閱 session 事件。想修改模型請求?掛接 `agent/request`。你可以讓 Pi 自己修改自己的 harness——這比任何「設定項目」都更接近「可程式化 harness」的定義。++## 回饋與驗證:把「學習」也做成 harness++Pi 本身沒有內建強制測試閘門(那是使用者要在 AGENTS.md 裡寫的驗證指令),但社群 harness([pi-agent-harness](https://github.com/LabidySabidy/pi-agent-harness))透過擴充把「回饋迴路」結構化了,官方 README 的 Hooks 一節也提供了相似的機制基礎:++- **session-summary**(pi-agent-harness 擴充):維護滾動更新的 `PROGRESS.md` 項目——這就是課程裡的狀態子系統,用於追蹤長任務進度。+- **extract-patterns**(pi-agent-harness 擴充):從 session 中收集經驗教訓候選項,沉澱到 `LESSONS.md`——把「每次 session 結束前做好交接」從約定變成機制。+- **telemetry**(pi-agent-harness 擴充):記錄 token 用量、成本等——可觀測性。++同一個社群儲存庫進一步驗證了這個模式:`VISION.md`(目標)、`PROGRESS.md`(進度)、`LESSONS.md`(經驗)、`STANDARDS.md`(標準),全都是 Markdown 檔案,可跨 session 持久化。這與課程建議的「儲存庫即事實來源 + 進度檔案 + 交接機制」完全是同一套做法,只是透過 Pi 的擴充機制成為開箱即用的一層。++## 對應到課程框架++用課程五子系統為 Pi 評分(主觀,僅供對照):++| 子系统 | Pi 的实现 | 评价 |+| --- | --- | --- |+| 指令 | AGENTS.md 分级加载 + SYSTEM.md | 层级清晰,但规则本身要靠用户写 |+| 工具 | 技能按需加载 + 扩展全生命周期钩子 | 极强,把工具系统做成了可编程面 |+| 环境 | SYSTEM.md 做环境自描述;运行时环境靠用户在 AGENTS.md 里声明 | 机制是开放的,但可复现性依赖用户自述 |+| 状态 | 会话树 + 压缩可定制 + PROGRESS.md | 极强,跨会话与可恢复性是其核心 |+| 反馈 | 验证命令靠用户定义;session-summary / extract-patterns 机制化 | 机制提供,内容靠用户 |++Pi 的取捨和 Claude Code / Codex 形成鮮明對比:Claude Code 把「記憶、permissions、subagent」全都做到核心裡,開箱即用;Codex 把「儲存庫規範、環境隔離」設為預設;Pi 選擇**什麼都不替你決定**——它把決定權做成擴充點。代價是你要嘛自己寫擴充,要嘛安裝別人寫好的套件。++## 值得借鑑的設計++1. **讓壓縮策略可插拔**。你的 harness 裡「上下文怎麼壓縮」不應該是寫死的參數,而應該是可替換的策略介面。+2. **用 session 樹取代強制摘要**。跨 session 復原不一定要靠「上一輪摘要」,結構化重播歷史往往是更可靠的狀態子系統。+3. **對提示快取友善**。隨選載入技能,不要把所有規則一次塞進系統提示,這既是上下文工程,也是成本工程。+4. **讓 agent 能修改自己的 harness**。如果 harness 的擴充介面夠開放,「最佳化 agent 行為」這件事本身就能由 agent 半自動完成。++## 參考來源(原文 / 原始碼)++每一項論述都能追溯到以下原文或原始碼,避免憑印象轉述:++- **pi.dev 官网**:定位原文 "Ask Pi to build what you want, or install a package that does it your way"、四層可自訂項目、session 樹("sessions are stored as trees"、`/tree`、單一檔案儲存、匯出 HTML / 分享 gist)。<br/>https://pi.dev/+- **pi.dev 官方文档 · Sessions**:compaction 可插拔(topic-based / code-aware / 更換摘要模型)、自動 compaction 與動態上下文注入的機制說明。<br/>https://pi.dev/docs/usage/sessions+- **pi.dev 官方文档 · Extensions**:擴充可在每輪推理前注入訊息、過濾歷史、執行 RAG、建構長期記憶。<br/>https://pi.dev/docs/usage/extensions+- **pi.dev 官方文档 · Project Context**:SYSTEM.md 的 replace / append 語意。<br/>https://pi.dev/docs/usage/project-context+- **Pi Coding Agent 源码 README**(badlogic/pi-mono):AGENTS.md 三級載入順序(全域 → 父目錄 → 目前目錄)、`/compact` 與自動 compaction 的觸發條件及 2 萬個 token 切割點、Skills 隨選載入與 Agent Skills 標準、Hooks 生命週期與四種官方範例用途、Programmatic Usage(JSON / RPC / SDK)。<br/>https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md+- **pi-agent-harness 社区仓库**:skill-router / session-summary / extract-patterns / telemetry 擴充,VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md 檔案體系。<br/>https://github.com/LabidySabidy/pi-agent-harness++相關講義:[第二講 · Harness 到底是什麼](../lectures/lecture-02-what-a-harness-actually-is/) | [第五講 · 讓跨 session 的任務保持上下文連續](../lectures/lecture-05-why-long-running-tasks-lose-continuity/) | [第十三講 · 從手動驅動到自動循環](../lectures/lecture-13-loop-engineering/)diff --git a/docs/zh-TW/index.md b/docs/zh-TW/index.mdindex 2b339dc..6cdf783 100644--- a/docs/zh-TW/index.md+++ b/docs/zh-TW/index.md@@ -25,6 +25,10 @@ Learn Harness Engineering 是一門專注於 AI 程式設計代理工程實踐<h3>資源庫</h3><p>開箱即用的範本(AGENTS.md、feature_list.json 等),可直接複製到你自己的儲存庫中。</p></a>+ <a href="./harness-designs/" class="card">+ <h3>前沿 Harness 拆解</h3>+ <p>用本課程的理論框架,逐層拆解 Pi、Claude Code、Codex、DeepSeek 的真實 harness 設計。</p>+ </a></div>## Harness 的核心機制