Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
docs: complete multilingual translations for all 11 locales
sanbuphye38d69701edf
diff --git a/CLAUDE.md b/CLAUDE.mdindex 411ded9..d0f015e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -33,7 +33,7 @@ npm run test:watch # Vitest watch mode- `docs/.vitepress/config.mts` — Nav/sidebar config for both EN and ZH locales- `docs/lectures/` — 12 lectures, each with `index.md` + `code/` examples- `docs/projects/` — 6 project descriptions-- `docs/resources/` — Bilingual (en/zh) templates, references, OpenAI advanced pack+- `docs/<lang>/resources/` — localized templates, references, OpenAI advanced pack- `projects/shared/` — Shared Electron + TypeScript + React foundation- `projects/project-NN/` — Per-project `starter/` and `solution/` directories@@ -57,6 +57,6 @@ Each project's starter/solution is a complete copy of the Electron app at that e- Progressive disclosure: short AGENTS.md entrypoint linking to focused docs- Each project has two tsconfigs: `tsconfig.json` (renderer) and `tsconfig.node.json` (main/preload)-## Bilingual Content+## Multilingual Content-All content exists in both English and Chinese. Documentation lives in shared `docs/lectures/` and `docs/projects/` dirs (content is bilingual within each file). Resources have separate `docs/resources/en/` and `docs/resources/zh/` directories. Keep both in sync.+Course documentation is organized by locale under `docs/<lang>/`. Keep English as the structural source of truth, keep localized directories in sync, and preserve runnable code examples across languages.diff --git a/README-CN.md b/README-CN.mdindex 0cdc3ab..45257fe 100644--- a/README-CN.md+++ b/README-CN.md@@ -11,7 +11,7 @@ Learn Harness Engineering 是一门专注于 AI 编程智能体工程化落地- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)-[**官方网站及文档 (English & 中文)**](https://walkinglabs.github.io/learn-harness-engineering/) | [**English README**](./README.md)+[**官方网站及多语言文档**](https://walkinglabs.github.io/learn-harness-engineering/) | [**English README**](./README.md)> **快速上手?** [`skills/harness-creator/`](./skills/) 技能可以帮你在几分钟内为自己的项目搭建一套生产级的 harness(AGENTS.md、功能清单、init.sh、验证工作流)。@@ -51,7 +51,7 @@ Learn Harness Engineering 是一门专注于 AI 编程智能体工程化落地仓库里现在已经补上了课程 PDF 的构建链路。-- 本地执行 `npm run pdf:build`,会生成中英文两份课程 PDF。+- 本地执行 `npm run pdf:build`,会生成当前脚本配置的课程 PDF。- 输出目录是 `artifacts/pdfs/`。- 如果需要刷新 README 里的截图,执行 `npm run screenshots:readme`。- GitHub Actions 工作流 [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) 可以自动构建 PDF,并把产物上传到 GitHub Release。@@ -498,7 +498,7 @@ npm run docs:preview # 预览构建结果```textlearn-harness-engineering/├── docs/ # VitePress 文档站-│ ├── index.md # 语言选择页(中文 / English)+│ ├── index.md # 语言选择页│ ├── zh/ # 中文完整内容│ │ ├── lectures/ # 12 个讲义(index.md + code/ 示例)│ │ ├── projects/ # 6 个项目diff --git a/README-KO.md b/README-KO.mdindex 88474bc..475aaa8 100644--- a/README-KO.md+++ b/README-KO.md@@ -36,7 +36,7 @@ Learn Harness Engineering은 AI 코딩 에이전트 공학에 전념하는 강저장소에는 강의 콘텐츠를 위한 PDF 빌드 파이프라인이 포함되어 있습니다.-- `npm run pdf:build` 명령으로 영어·중국어 PDF를 로컬에서 생성할 수 있습니다.+- `npm run pdf:build` 명령으로 현재 스크립트에 설정된 강의 PDF를 로컬에서 생성할 수 있습니다.- 출력 파일은 `artifacts/pdfs/`에 저장됩니다.- README 미리보기 이미지를 갱신하려면 `npm run screenshots:readme`를 실행하십시오.- GitHub Actions 워크플로우 [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml)을 통해 PDF를 빌드하고 GitHub Releases에 게시할 수 있습니다.diff --git a/README.md b/README.mdindex c9d3a39..34e71b1 100644--- a/README.md+++ b/README.md@@ -1,4 +1,17 @@-[English](https://walkinglabs.github.io/learn-harness-engineering/en/) · [中文](https://walkinglabs.github.io/learn-harness-engineering/zh/) · [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/) · [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/) · [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/) · [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/)+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="docs-readme/zh-CN/README.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="docs-readme/zh-TW/README.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="docs-readme/ja-JP/README.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="docs-readme/es-ES/README.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="docs-readme/fr-FR/README.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="docs-readme/ko-KR/README.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="docs-readme/ar-SA/README.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="docs-readme/vi-VN/README.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="docs-readme/de-DE/README.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+ <a href="https://walkinglabs.github.io/learn-harness-engineering/ru/"><img alt="Русский" src="https://img.shields.io/badge/Русский-d9d9d9"></a>+ <a href="https://walkinglabs.github.io/learn-harness-engineering/uz/"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/Oʻzbekcha-d9d9d9"></a>+</p># Learn Harness Engineering@@ -49,7 +62,7 @@ Learn Harness Engineering is a course dedicated to the engineering of AI codingThe repository now includes a PDF build pipeline for the course content.-- Run `npm run pdf:build` to generate English and Chinese PDFs locally.+- Run `npm run pdf:build` to generate the currently configured PDF coursebooks locally.- Output files are written to `artifacts/pdfs/`.- Run `npm run screenshots:readme` if you want to refresh the README preview images.- GitHub Actions workflow [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) can build the PDFs and publish them to GitHub Releases.diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex 80abc2c..da221fe 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -228,6 +228,96 @@ const koSkillItems = [{ text: "스킬 개요", link: "/ko/skills/" }];+const relinkItems = (items: Array<{ text: string; link: string }>, locale: string) =>+ items.map((item) => ({+ ...item,+ link: item.link.replace(/^\/(en|zh|vi|ko|uz|ru)\//, `/${locale}/`)+ }));++const createLocaleTheme = (+ locale: string,+ sourceItems: {+ lectures: Array<{ text: string; link: string }>;+ projects: Array<{ text: string; link: string }>;+ resources: Array<{ text: string; link: string }>;+ skills: Array<{ text: string; link: string }>;+ },+ labels: {+ lectures: string;+ projects: string;+ resources: string;+ skills: string;+ resourceLibrary: string;+ tryHarness: string;+ outline?: string;+ prev?: string;+ next?: string;+ lastUpdated?: string;+ returnToTop?: string;+ sidebarMenu?: string;+ darkModeSwitch?: string;+ lightModeSwitchTitle?: string;+ darkModeSwitchTitle?: string;+ }+) => {+ const lectures = relinkItems(sourceItems.lectures, locale);+ const projects = relinkItems(sourceItems.projects, locale);+ const resources = relinkItems(sourceItems.resources, locale);+ const skills = relinkItems(sourceItems.skills, locale);++ return {+ nav: [+ { text: labels.lectures, link: lectures[1].link, activeMatch: `^/${locale}/(lectures/.*)?$` },+ { 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/` },+ {+ 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 }],+ [`/${locale}/`]: [{ text: labels.lectures, items: lectures }]+ },+ outline: {+ level: [2, 3],+ ...(labels.outline ? { label: labels.outline } : {})+ },+ docFooter: {+ prev: labels.prev || "Previous",+ next: labels.next || "Next"+ },+ lastUpdated: {+ text: labels.lastUpdated || "Last updated"+ },+ returnToTopLabel: labels.returnToTop || "Return to top",+ sidebarMenuLabel: labels.sidebarMenu || "Menu",+ darkModeSwitchLabel: labels.darkModeSwitch || "Theme",+ lightModeSwitchTitle: labels.lightModeSwitchTitle || "Switch to light theme",+ darkModeSwitchTitle: labels.darkModeSwitchTitle || "Switch to dark theme",+ socialLinks: [{ icon: "github", link: githubRepoTreeLink }]+ };+};++const enSourceItems = {+ lectures: enLectureItems,+ projects: enProjectItems,+ resources: enResourceItems,+ skills: enSkillItems+};++const zhSourceItems = {+ lectures: zhLectureItems,+ projects: zhProjectItems,+ resources: zhResourceItems,+ skills: zhSkillItems+};+export default withMermaid(defineConfig({base: docsBase,@@ -332,6 +422,137 @@ export default withMermaid(socialLinks: [{ icon: "github", link: githubRepoTreeLink }]}},+ "zh-TW": {+ label: "繁體中文",+ lang: "zh-TW",+ link: "/zh-TW/",+ themeConfig: createLocaleTheme("zh-TW", zhSourceItems, {+ lectures: "講義",+ projects: "專案",+ resources: "資源庫",+ skills: "技能",+ resourceLibrary: "資源庫",+ tryHarness: "Try Harness ↗",+ prev: "上一篇",+ next: "下一篇",+ lastUpdated: "最後更新於",+ returnToTop: "回到頂部",+ sidebarMenu: "選單",+ darkModeSwitch: "主題",+ lightModeSwitchTitle: "切換到淺色模式",+ darkModeSwitchTitle: "切換到深色模式"+ })+ },+ ja: {+ label: "日本語",+ lang: "ja-JP",+ link: "/ja/",+ themeConfig: createLocaleTheme("ja", enSourceItems, {+ lectures: "講義",+ projects: "プロジェクト",+ resources: "リソース",+ skills: "スキル",+ resourceLibrary: "リソースライブラリ",+ tryHarness: "Try Harness ↗",+ outline: "このページ",+ prev: "前へ",+ next: "次へ",+ lastUpdated: "最終更新",+ returnToTop: "トップへ戻る",+ sidebarMenu: "メニュー",+ darkModeSwitch: "テーマ",+ lightModeSwitchTitle: "ライトモードに切り替え",+ darkModeSwitchTitle: "ダークモードに切り替え"+ })+ },+ es: {+ label: "Español",+ lang: "es-ES",+ link: "/es/",+ themeConfig: createLocaleTheme("es", enSourceItems, {+ lectures: "Lecciones",+ projects: "Proyectos",+ resources: "Biblioteca",+ skills: "Skills",+ resourceLibrary: "Biblioteca de recursos",+ tryHarness: "Try Harness ↗",+ outline: "En esta página",+ prev: "Anterior",+ next: "Siguiente",+ lastUpdated: "Última actualización",+ returnToTop: "Volver arriba",+ sidebarMenu: "Menú",+ darkModeSwitch: "Tema",+ lightModeSwitchTitle: "Cambiar a tema claro",+ darkModeSwitchTitle: "Cambiar a tema oscuro"+ })+ },+ fr: {+ label: "Français",+ lang: "fr-FR",+ link: "/fr/",+ themeConfig: createLocaleTheme("fr", enSourceItems, {+ lectures: "Cours",+ projects: "Projets",+ resources: "Bibliothèque",+ skills: "Skills",+ resourceLibrary: "Bibliothèque de ressources",+ tryHarness: "Try Harness ↗",+ outline: "Sur cette page",+ prev: "Précédent",+ next: "Suivant",+ lastUpdated: "Dernière mise à jour",+ returnToTop: "Retour en haut",+ sidebarMenu: "Menu",+ darkModeSwitch: "Thème",+ lightModeSwitchTitle: "Passer au thème clair",+ darkModeSwitchTitle: "Passer au thème sombre"+ })+ },+ de: {+ label: "Deutsch",+ lang: "de-DE",+ link: "/de/",+ themeConfig: createLocaleTheme("de", enSourceItems, {+ lectures: "Lektionen",+ projects: "Projekte",+ resources: "Bibliothek",+ skills: "Skills",+ resourceLibrary: "Ressourcenbibliothek",+ tryHarness: "Try Harness ↗",+ outline: "Auf dieser Seite",+ prev: "Zurück",+ next: "Weiter",+ lastUpdated: "Zuletzt aktualisiert",+ returnToTop: "Nach oben",+ sidebarMenu: "Menü",+ darkModeSwitch: "Theme",+ lightModeSwitchTitle: "Zum hellen Theme wechseln",+ darkModeSwitchTitle: "Zum dunklen Theme wechseln"+ })+ },+ ar: {+ label: "العربية",+ lang: "ar-SA",+ link: "/ar/",+ themeConfig: createLocaleTheme("ar", enSourceItems, {+ lectures: "المحاضرات",+ projects: "المشاريع",+ resources: "المكتبة",+ skills: "المهارات",+ resourceLibrary: "مكتبة الموارد",+ tryHarness: "Try Harness ↗",+ outline: "في هذه الصفحة",+ prev: "السابق",+ next: "التالي",+ lastUpdated: "آخر تحديث",+ returnToTop: "العودة إلى الأعلى",+ sidebarMenu: "القائمة",+ darkModeSwitch: "السمة",+ lightModeSwitchTitle: "التبديل إلى السمة الفاتحة",+ darkModeSwitchTitle: "التبديل إلى السمة الداكنة"+ })+ },vi: {label: "Tiếng Việt",lang: "vi-VN",diff --git a/docs/ar/index.md b/docs/ar/index.mdnew file mode 100644index 0000000..fca4de6--- /dev/null+++ b/docs/ar/index.md@@ -0,0 +1,73 @@+# مرحبًا بك في Learn Harness Engineering++Learn Harness Engineering هو مساق مخصص لهندسة وكلاء البرمجة بالذكاء الاصطناعي. درسنا و لخصنا مجموعة من أكثر نظريات وممارسات Harness Engineering تقدمًا في الصناعة. تشمل مراجعنا الأساسية:+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)++من خلال تصميم البيئة، وإدارة الحالة، والتحقق، وأنظمة التحكم بطريقة منهجية، يوضح هذا المساق كيف تجعل أدوات البرمجة الوكيلية مثل Codex و Claude Code موثوقة فعليًا. ستتعلم كيف تبني الميزات، وتصلح الأخطاء، وتؤتمت مهام التطوير عبر تقييد مساعد البرمجة بالذكاء الاصطناعي بقواعد وحدود صريحة.++## ابدأ++اختر مسار التعلم المناسب لك. ينقسم المساق إلى محاضرات نظرية، ومشاريع عملية، ومكتبة موارد جاهزة للنسخ.++<div class="card-grid">+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">+ <h3>المحاضرات</h3>+ <p>افهم لماذا تفشل النماذج القوية أحيانًا، وتعلم النظرية وراء harnesses الفعالة.</p>+ </a>+ <a href="./projects/" class="card">+ <h3>المشاريع</h3>+ <p>تدريب عملي على بناء بيئة وكيلية موثوقة من الصفر.</p>+ </a>+ <a href="./resources/" class="card">+ <h3>مكتبة الموارد</h3>+ <p>قوالب جاهزة للنسخ مثل AGENTS.md و feature_list.json لاستخدامها في مستودعاتك.</p>+ </a>+</div>++## الآلية الأساسية للـ harness++الـ harness لا "يجعل النموذج أذكى"؛ بل ينشئ **نظام عمل** مغلق الحلقة للنموذج. يمكنك فهم التدفق الأساسي من خلال هذا المخطط:++```mermaid+graph TD+ A["Clear Objective<br/>AGENTS.md"] --> B("Initialization<br/>init.sh")+ B --> C{"Run Tasks<br/>AI Agent"}+ C -->|Encounter Issues| D["Runtime Feedback<br/>CLI / Logs"]+ D -->|Auto-fix| C+ C -->|Code Completed| E{"Verify & QA<br/>Test suite"}+ E -->|Failed| D+ E -->|Passed| F["Cleanup & Handoff<br/>claude-progress.md"]++ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;++ class A,F primary;+ class B,D process;+ class C,E check;+```++## ما الذي ستتعلمه++هذه بعض المفاهيم الأساسية التي ستتقنها:++<ul class="index-list">+ <li><strong>تقييد سلوك الوكيل</strong> بقواعد وحدود صريحة.</li>+ <li><strong>الحفاظ على السياق</strong> عبر المهام الطويلة ومتعددة الجلسات.</li>+ <li><strong>منع الوكلاء</strong> من إعلان النجاح مبكرًا.</li>+ <li><strong>التحقق من العمل</strong> باستخدام اختبارات pipeline كاملة ومراجعة ذاتية.</li>+ <li><strong>جعل runtime قابلًا للملاحظة</strong> وأسهل في التصحيح.</li>+</ul>++## الخطوات التالية++بعد فهم المفاهيم الأساسية، تساعدك هذه الأدلة على التعمق:++<ul class="index-list">+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">المحاضرة 01: لماذا تفشل الوكلاء القادرة أحيانًا</a>: ابدأ بالنظرية وراء harness engineering.</li>+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">المشروع 01: baseline مقابل harness بسيط</a>: نفذ أول مهمة عملية حقيقية.</li>+ <li><a href="./resources/templates/">القوالب</a>: احصل على حزمة harness بسيطة لاستخدامها في مشاريعك.</li>+</ul>diff --git a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..311e665--- /dev/null+++ b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,170 @@+/**+ * failure-pattern-demo.ts+ *+ * Simulates the 4-step failure pattern that capable agents fall into:+ * 1. Incomplete context+ * 2. Locally reasonable changes+ * 3. No global verification+ * 4. Premature completion+ *+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// Simulated "model" -- a simple decision function that bases its output+// solely on whatever context it has been given.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // The task is to "add a search endpoint to the API".+ // Correct answer requires knowing about auth middleware and rate limiting.++ if (!has("auth")) {+ return "Created new route handler /search without authentication checks";+ }+ if (!has("rate-limit")) {+ return "Added search route with auth but forgot rate limiting";+ }+ if (!has("test-standards")) {+ return "Implemented search with auth and rate-limit, but no tests";+ }+ return "Fully implemented search endpoint with auth, rate-limit, and tests";+}++// ---------------------------------------------------------------------------+// Failure simulation+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Step 1: Incomplete Context ----+ const step1Context = ["project structure", "route definitions"];+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];+ const step1Decision = modelDecide(step1Context, "add search endpoint");++ steps.push({+ step: 1,+ name: "Incomplete Context",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Looks good -- route compiles, returns data",+ globalImpact: "Missing auth means unauthenticated access to search",+ completed: false,+ });++ // ---- Step 2: Locally Reasonable Changes ----+ // The agent adds auth after a hint, but still lacks other context.+ const step2Context = [...step1Context, "auth middleware"];+ const step2Missing = ["rate-limiting policy", "test standards"];+ const step2Decision = modelDecide(step2Context, "add search endpoint");++ steps.push({+ step: 2,+ name: "Locally Reasonable Changes",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "Route has auth -- looks complete locally",+ globalImpact: "No rate limiting means the endpoint can be abused",+ completed: false,+ });++ // ---- Step 3: No Global Verification ----+ const step3Context = [...step2Context, "rate-limiting policy"];+ const step3Missing = ["test standards"];+ const step3Decision = modelDecide(step3Context, "add search endpoint");++ steps.push({+ step: 3,+ name: "No Global Verification",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "Feature appears fully implemented",+ globalImpact: "No tests -- regression risk, violates project standards",+ completed: false,+ });++ // ---- Step 4: Premature Completion ----+ steps.push({+ step: 4,+ name: "Premature Completion",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',+ localOutcome: "Agent is satisfied, task marked complete",+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Comparison table+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Step ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);+ console.log(` Action taken : ${s.actionTaken}`);+ console.log(` Local outcome : ${s.localOutcome}`);+ console.log(` Global impact : ${s.globalImpact}`);+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);+ }++ // Summary comparison+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");+ console.log("=".repeat(90));++ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];+ const finalAvailable = steps[steps.length - 1].contextAvailable;++ const header = "| Criterion | Available | Missing | Status |";+ const sep = "|------------------------|-----------|---------|----------|";+ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;+ console.log(row);+ }++ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());diff --git a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdnew file mode 100644index 0000000..38b41a4--- /dev/null+++ b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -0,0 +1,9 @@+# قائمة فحص إشارات الفشل++استخدم هذه القائمة عند مراجعة نتيجة تشغيل harness ضعيف.++- هل سأل الوكيل أو استنتج بشكل خاطئ كيفية تشغيل التطبيق؟+- هل أنشأ أدلة أو تجريدات لا تتطابق مع المنتج المقصود؟+- هل توقف بعد بناء هيكل UI مرئي بدون سير عمل كامل؟+- هل ترك ملاحظات أو منتجات تساعد تشغيلاً مستقبلياً على الاستمرار؟+- هل يمكن لجلسة جديدة فهم ما حدث في أقل من خمس دقائق؟diff --git a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdnew file mode 100644index 0000000..4622ef5--- /dev/null+++ b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -0,0 +1,7 @@+# كود المحاضرة 01++استخدم هذا المجلد لأمثلة صغيرة توضح:++- نموذج قوي يفشل في بيئة ضعيفة+- إعداد مستودع غير محدد بشكل كافٍ+- حلقات تغذية راجعة مفقودةdiff --git a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdnew file mode 100644index 0000000..187e22b--- /dev/null+++ b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -0,0 +1,18 @@+# مثال على مهمة غير محددة بشكل كافٍ++بناء تطبيق سطح مكتب لقاعدة المعرفة مع إجابات أسئلة بالذكاء الاصطناعي.++القيود:++- لم يتم تحديد أي قيود+- لم يتم إعطاء أمر تشغيل+- لم يتم توفير إرشادات هيكل المجلدات+- لم يتم تعريف نموذج بيانات+- لا توجد معايير إكمال صريحة++النتائج النموذجية لهذا النوع من prompt:++- الوكيل يخترع هيكلاً بشكل مخصص+- التطبيق قد يُترجم لكنه لا يبدأ بشكل متسق+- الواجهة قد تظهر قبل أن يكون هناك مسار استيراد/استعلام قابل للاستخدام+- الوكيل يتوقف غالباً بعد نجاح تجميليdiff --git a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.mdnew file mode 100644index 0000000..cdf7640--- /dev/null+++ b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -0,0 +1,117 @@+[中文版本 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/code/)+> مشروع عملي: [المشروع 01. الاعتماد على المطالبة فقط مقابل القواعد أولًا](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# المحاضرة 01. النماذج القوية لا تعني تنفيذًا موثوقًا++تظن أنك خبير بما يكفي في عالم الذكاء الاصطناعي: اشتراك Claude Pro، مفتاح GPT-4o API، وأرقام لوحة SWE-bench محفوظة في ذاكرتك. ثم في يوم ما تسلم مشروعًا حقيقيًا إلى وكيل ذكاء اصطناعي وأنت واثق تمامًا. النتيجة؟ يضيف ميزة لكنه يكسر الاختبارات، يصلح عيبًا لكنه يضيف عيبين جديدين، يعمل لمدة 20 دقيقة ثم يعلن بفخر "تم" - وعندما تنظر إلى الكود تكتشف أنه ليس ما طلبته إطلاقًا.++غريزتك الأولى؟ "هذا النموذج ليس جيدًا بما يكفي. حان وقت الترقية." تمهل. قبل أن تمد يدك إلى محفظتك، فكّر في احتمال أن المشكلة ليست في النموذج أصلًا.++لننظر إلى بعض الأرقام. بحلول أواخر عام 2025، كانت أقوى وكلاء البرمجة على SWE-bench Verified تحقق تقريبًا 50-60%. وهذا على مهام مختارة بعناية، مع أوصاف Issues واضحة وحالات اختبار موجودة. انقل الأمر إلى بيئة تطويرك اليومية - متطلبات غامضة، لا اختبارات جاهزة، وقواعد عمل ضمنية مبعثرة في كل مكان - وستنخفض هذه النسبة أكثر.++لكن خلف هذه الأرقام توجد حقيقة غير بديهية.++## الحصان نفسه، مصائر مختلفة++أجرت Anthropic تجربة مضبوطة. المطالبة نفسها ("ابنِ صانع ألعاب ريترو ثنائية الأبعاد")، والنموذج نفسه (Opus 4.5). التشغيل الأول: عارٍ بلا دعم - 20 دقيقة، 9 دولارات، والميزات الأساسية للعبة لم تعمل إطلاقًا. التشغيل الثاني: Harness كامل (مخطط + مولد + مقيم في بنية من ثلاثة وكلاء) - 6 ساعات، 200 دولار، وأصبحت اللعبة قابلة للعب.++لم يغيروا النموذج. بقي Opus 4.5 هو Opus 4.5. ما تغيّر هو السرج.++مقال OpenAI لعام 2025 عن هندسة الـ Harness يقولها بوضوح: ينتقل Codex في مستودع مجهز جيدًا بالـ Harness من "غير موثوق" إلى "موثوق". لاحظ الصياغة - ليست "أفضل قليلًا"، بل انتقال نوعي. مثل حصان أصيل: يمكنك ركوبه بلا سرج، لكنك لن تذهب بعيدًا، ولن تتحرك بسرعة، والسقوط لن يكون مفاجأة. الـ Harness هو ذلك السرج - **كل ما في البنية الهندسية خارج أوزان النموذج.**++## أين تتعطل الوكلاء فعليًا++إذًا، ما الذي يسوء تحديدًا؟++الأكثر شيوعًا: أنت لم تعرّف المهمة بوضوح. تقول "أضف ميزة بحث"، وفهم الوكيل يختلف تمامًا عن فهمك - البحث في ماذا؟ نص كامل أم بيانات منظمة؟ هل توجد صفحات؟ هل توجد تظليلات للنتائج؟ لم تحدد ذلك، فيخمن الوكيل. التخمين الصحيح حظ؛ أما التخمين الخاطئ فيكلف إصلاحه أكثر مما كان سيكلفه التحديد من البداية. الأمر يشبه دخول مطعم وقولك للطاهي: "أريد سمكًا" - هل سيأتي مطهوًا ببطء، أم على البخار، أم في قدر ساخن؟ الأمر كله متروك للمصادفة.++حتى عندما تحدد المطلوب، لدى المشروع أعراف معمارية ضمنية لا يعرفها الوكيل. فريقك اعتمد صيغة SQLAlchemy 2.0، لكن الوكيل يكتب افتراضيًا بصيغة 1.x. كل نقاط API يجب أن تستخدم مصادقة OAuth 2.0، لكن هذه القاعدة موجودة فقط في رأسك وفي رسالة Slack من ثلاثة أشهر. الوكيل لا يرى ذلك - ليس لأنه لا يريد الالتزام، بل لأنه حرفيًا لا يعرف أن هذه القواعد موجودة.++والبيئة نفسها قد تكون فخًا. بيئة تطوير ناقصة، اعتماديات مفقودة، إصدارات أدوات خاطئة. يحرق الوكيل جزءًا ثمينًا من نافذة السياق على أخطاء `pip install` وتعارضات إصدار Node بدلًا من حل مهمتك الفعلية. كأنك تستأجر نجارًا ماهرًا ثم تنسى أن توفر له مطرقة ومسامير ومنضدة عمل مستوية - مهما كانت مهارته، لن يستطيع إنجاز العمل.++والأكثر شيوعًا من ذلك: لا توجد طريقة للتحقق. لا اختبارات، لا Lint، أو لم تُبلّغ أوامر التحقق إلى الوكيل. يكتب الوكيل الكود، ينظر إليه، يقرر أنه جيد، ثم يقول "تم". هذا يشبه أن تطلب من طالب تسليم واجب بلا نموذج إجابة - يظن أنه أجاب بشكل صحيح، لكن عند التصحيح تجد الأخطاء متراكمة. لاحظت Anthropic أيضًا ظاهرة مثيرة: عندما تشعر الوكلاء أن السياق يوشك على النفاد، تندفع لإنهاء المهمة، وتتخطى التحقق، وتختار حلًا بسيطًا بدل الحل الأفضل. يسمون ذلك "context anxiety" - وهو شبيه بما يحدث عندما تدرك أن وقت الامتحان أوشك على الانتهاء فتبدأ بتخمين إجابات الأسئلة المتبقية.++المهام الطويلة الممتدة عبر جلسات أسوأ أيضًا: كل الاكتشافات من الجلسة السابقة تضيع، وكل جلسة جديدة تضطر إلى إعادة استكشاف بنية المشروع وفهم تنظيم الكود. الوكلاء بلا حالة مستمرة ترتفع معدلات فشلها بحدة في المهام التي تتجاوز 30 دقيقة.++## مصطلحات أساسية++مع هذه السيناريوهات في الذهن، لم تعد هذه المفاهيم مجرد مصطلحات:++- **Capability Gap**: الفجوة الكبيرة بين أداء النموذج على المعايير القياسية وأدائه في المهام الحقيقية. معدل نجاح 50-60% على SWE-bench Verified يعني أن قرابة نصف القضايا الحقيقية لا تُحل.+- **Harness**: كل ما هو خارج النموذج - التعليمات، الأدوات، البيئة، إدارة الحالة، وتغذية التحقق الراجعة. إن لم يكن من أوزان النموذج فهو جزء من الـ Harness. هذا هو "السرج" الذي نتحدث عنه.+- **Harness-Induced Failure**: لدى النموذج قدرة كافية، لكن بيئة التنفيذ فيها عيوب بنيوية. تجربة Anthropic المضبوطة أثبتت ذلك بالفعل.+- **Verification Gap**: الفجوة بين ثقة الوكيل في مخرجاته والصحة الفعلية. يقول الوكيل "انتهيت" وهو لم ينتهِ - وهذا هو نمط الفشل الأكثر شيوعًا.+- **Diagnostic Loop**: نفّذ، لاحظ الفشل، انسبه إلى طبقة Harness محددة، أصلح تلك الطبقة، ثم نفّذ مرة أخرى. هذه هي المنهجية الأساسية لهندسة الـ Harness.+- **Definition of Done**: مجموعة شروط قابلة للتحقق آليًا - الاختبارات تمر، الـ lint نظيف، وفحوصات الأنواع ناجحة. من دون Definition of Done صريحة، سيخترع الوكيل تعريفه الخاص.++## عندما تفشل الأمور، أصلح الـ Harness أولًا++المبدأ الأساسي: **عندما تفشل الأمور، لا تستبدل النموذج أولًا - افحص الـ Harness.** إذا نجح النموذج نفسه في مهام مشابهة ومهيكلة جيدًا، فافترض أن المشكلة في الـ Harness. مثل سيارة تعطلت: لا تفترض فورًا أن المحرك هو السبب. افحص أولًا إن كان الوقود قد نفد.++خطوات عملية:++**انسب كل فشل إلى طبقة محددة.** لا تقل فقط "النموذج سيئ". اسأل: هل كانت المهمة غير واضحة؟ هل كان السياق غير كافٍ؟ هل لم تكن هناك وسائل تحقق؟ اربط كل فشل بإحدى طبقات الفشل الخمس: مواصفة المهمة، تزويد السياق، بيئة التنفيذ، تغذية التحقق الراجعة، وإدارة الحالة. ابنِ هذه العادة، وستجد أن عبارة "النموذج ليس جيدًا بما يكفي" تظهر أقل فأقل في سجلاتك.++**اكتب Definition of Done صريحة لكل مهمة.** لا تقل "أضف ميزة بحث". قل:+```+Completion criteria:+- New endpoint GET /api/search?q=xxx+- Supports pagination, default 20 items+- Results include highlighted snippets+- All new code passes pytest+- Type checking passes (mypy --strict)+```++**أنشئ ملف AGENTS.md.** ضعه في جذر المستودع ليخبر الوكيل بمكدس التقنية، والأعراف المعمارية، وأوامر التحقق الخاصة بالمشروع. هذه هي الخطوة الأولى في هندسة الـ Harness، وهي أعلى خطوة عائدًا على الجهد يمكنك اتخاذها. قد يكون ملف `AGENTS.md` واحد أكثر فاعلية من الترقية إلى نموذج أغلى - وهذا ليس مزاحًا.++**ابنِ حلقة تشخيص.** لا تتعامل مع الفشل على أنه "النموذج غبي مرة أخرى". تعامل معه كإشارة إلى وجود عيب في الـ Harness. في كل فشل: حدد الطبقة، أصلحها، وتأكد ألا يتكرر الفشل بالطريقة نفسها. بعد بضع جولات، يصبح الـ Harness أقوى ويستقر أداء الوكيل. مثل إصلاح الطريق: كل حفرة تملؤها تجعل المقطع التالي أكثر سلاسة.++**قِس التحسن.** احتفظ بسجل بسيط: هل نجحت كل مهمة أم فشلت، وأي طبقة سببت الفشل؟ بعد عدة جولات سترى أي طبقة هي عنق الزجاجة - ركز طاقتك هناك.++## تجربة المليون سطر++أجرت OpenAI في 2025 تجربة جريئة: استخدام Codex لبناء منتج داخلي كامل من مستودع Git فارغ. بعد خمسة أشهر، احتوى المستودع على نحو مليون سطر كود - منطق تطبيق، بنية تحتية، أدوات، توثيق، وأدوات تطوير داخلية - كلها مولدة بواسطة الوكلاء. قاد ثلاثة مهندسين Codex، وفتحوا ودمجوا نحو 1,500 Pull Request. بمعدل 3.5 Pull Request لكل شخص يوميًا.++القيد الأساسي: **البشر لا يكتبون الكود مباشرة أبدًا.** لم تكن هذه حيلة، بل صُممت لإجبار الفريق على فهم ما يتغير عندما لا تكون وظيفة المهندس الأساسية هي كتابة الكود، بل تصميم البيئات، وصياغة النية، وبناء حلقات التغذية الراجعة.++كان التقدم في البداية أبطأ من المتوقع. ليس لأن Codex لم يكن قادرًا، بل لأن البيئة لم تكن مكتملة بما يكفي - كان الوكيل يفتقد الأدوات، والتجريدات، والبنى الداخلية اللازمة للتقدم نحو أهداف عالية المستوى. أصبح عمل المهندسين: تقسيم الأهداف الكبيرة إلى لبنات صغيرة (تصميم، كود، مراجعة، اختبار)، وترك الوكيل يركبها، ثم استخدام تلك اللبنات لفتح مهام أكثر تعقيدًا. عندما يفشل شيء، لم يكن الحل تقريبًا "حاول بجهد أكبر"، بل "ما القدرة التي يفتقدها الوكيل، وكيف نجعلها مفهومة وقابلة للتنفيذ؟"++تثبت هذه التجربة مباشرة الأطروحة المركزية لهذه المحاضرة: **النموذج نفسه ينتج مخرجات مختلفة جوهريًا في بيئة عارية مقارنة ببيئة ذات Harness كامل.** النموذج لم يتغير. البيئة تغيرت.++> المصدر: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++## مثال أقرب إلى الواقع++استخدم فريق Claude Sonnet لإضافة نقطة API جديدة إلى تطبيق ويب Python متوسط الحجم (FastAPI + PostgreSQL + Redis، نحو 15,000 سطر كود).++في البداية أعطوه جملة واحدة فقط: "add user preferences endpoints under `/api/v2/users`." النتيجة؟ استهلك الوكيل 40% من نافذة السياق في استكشاف بنية المستودع، وأنتج كودًا يبدو معقولًا لكنه لا يتبع أنماط معالجة الأخطاء في المشروع، واستخدم صيغة SQLAlchemy قديمة، وأعلن الانتهاء رغم أن نقطة النهاية كانت تحتوي على أخطاء تشغيل. اضطرت الجلسة التالية إلى إعادة كل عمل الاكتشاف.++لاحقًا أضافوا `AGENTS.md` (يصف معمارية المشروع وإصدارات مكدس التقنية)، وأوامر تحقق صريحة (`pytest tests/api/v2/ && python -m mypy src/`)، وسجلات قرارات معمارية. نجح النموذج نفسه في الجولات الثلاث المستقلة كلها، مع كفاءة سياق أفضل بنحو 60%.++لم يغيروا النموذج. غيّروا الـ Harness.++## الخلاصات الأساسية++- قدرة النموذج وموثوقية التنفيذ شيئان مختلفان. حتى الحصان الأصيل يحتاج إلى سرج جيد.+- عندما تفشل الأمور، افحص الـ Harness أولًا ثم النموذج. تبديل النماذج هو الخيار الأغلى - وغالبًا ليست المشكلة في النموذج أصلًا.+- كل فشل إشارة: لدى الـ Harness عيب بنيوي. اعثر عليه وأصلحه.+- خمس طبقات دفاع: مواصفة المهمة، تزويد السياق، بيئة التنفيذ، تغذية التحقق الراجعة، وإدارة الحالة. افحصها بشكل منهجي، كما يستبعد الطبيب الأسباب الأكثر شيوعًا أولًا.+- قد يكون ملف `AGENTS.md` واحد أكثر فاعلية من الترقية إلى نموذج أغلى. بجدية.++## قراءات إضافية++- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-bench Leaderboard](https://www.swebench.com/)+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)++## تمارين++1. **تجربة مقارنة**: اختر قاعدة كود تعرفها جيدًا ومهمة تعديل غير تافهة. شغّل الوكيل أولًا بلا دعم Harness وسجل الإخفاقات. ثم أضف `AGENTS.md` يحتوي على أوامر تحقق صريحة وشغّل الوكيل نفسه مرة أخرى. قارن النتائج، وانسب كل فشل إلى إحدى طبقات الدفاع الخمس.++2. **قياس Verification Gap**: اختر 5 مهام برمجية. بعد كل مهمة، سجل هل يدعي الوكيل أنه انتهى، ثم تحقق من الصحة الفعلية باختبارات مستقلة. احسب نسبة الحالات التي يقول فيها الوكيل إنه انتهى بينما لم ينتهِ فعليًا - هذه هي Verification Gap لديك. ثم فكّر: ما أوامر التحقق التي ستخفض هذه النسبة؟++3. **تدريب حلقة التشخيص**: ابحث عن مهمة يفشل فيها الوكيل مرارًا في مشروعك. شغّلها مرة واحدة وسجل الفشل. انسبه إلى إحدى الطبقات الخمس. أصلح تلك الطبقة. شغّل مرة أخرى. كرر ذلك من ثلاث إلى خمس جولات، وسجل التحسن في كل مرة.diff --git a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.mdnew file mode 100644index 0000000..6e0519e--- /dev/null+++ b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md@@ -0,0 +1,21 @@+# مثال على مكونات الـ Harness++لوكيل برمجة يعمل في مستودع محلي:++- النموذج (Model):+ الـ LLM نفسه++- الـ Harness:+ - system prompt+ - AGENTS.md+ - أداة bash+ - أدوات قراءة/كتابة الملفات+ - وصول git+ - نظام الملفات المحلي+ - سكربتات التشغيل+ - أوامر الاختبار+ - stop hooks+ - فحوصات lint+ - حلقة التقييم (evaluator loop)++إذا غيّرت أيًا من مكونات الـ harness أعلاه، فقد غيّرت الوكيل الفعّال.diff --git a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.tsnew file mode 100644index 0000000..d856ba3--- /dev/null+++ b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts@@ -0,0 +1,180 @@+/**+ * harness-vs-no-harness.ts+ *+ * Side-by-side comparison of the same task executor running with and without+ * a harness. The harness version adds explicit rules, verification steps,+ * and stop conditions.+ *+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts+ */++// ---------------------------------------------------------------------------+// Types & helpers+// ---------------------------------------------------------------------------++interface TaskResult {+ name: string;+ passed: boolean;+ durationMs: number;+ issues: string[];+}++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++// ---------------------------------------------------------------------------+// Simulated task executor+// ---------------------------------------------------------------------------++/** A simple task that can succeed or fail depending on rules. */+type Task = {+ name: string;+ requiresAuth: boolean;+ hasTests: boolean;+ withinScope: boolean;+};++const tasks: Task[] = [+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },+];++// ---------------------------------------------------------------------------+// Run WITHOUT harness -- just execute every task, no checks+// ---------------------------------------------------------------------------++function runWithoutHarness(taskList: Task[]): TaskResult[] {+ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];++ // The "agent" does the work and calls it done.+ let passed = true;++ // Problems that go undetected without a harness+ if (t.requiresAuth && !t.hasTests) {+ issues.push("No tests for auth-protected endpoint");+ // Agent doesn't notice -- marks as pass anyway+ }+ if (!t.withinScope) {+ issues.push("Task is outside current scope");+ // Agent doesn't notice+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Run WITH harness -- rules, verification, stop conditions+// ---------------------------------------------------------------------------++function runWithHarness(taskList: Task[]): TaskResult[] {+ const rules = {+ requireTestsForAuth: true,+ enforceScope: true,+ };++ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];+ let passed = true;++ // Rule: auth endpoints must have tests+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {+ issues.push("BLOCKED: Auth-protected endpoint missing tests");+ passed = false;+ }++ // Rule: stay in scope+ if (rules.enforceScope && !t.withinScope) {+ issues.push("BLOCKED: Task outside active scope -- skipped");+ passed = false;+ }++ // Verification: re-check after execution+ if (passed && !t.hasTests) {+ issues.push("WARNING: No tests exist for this change");+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function printComparison(+ noHarness: TaskResult[],+ withHarness: TaskResult[]+): void {+ console.log("\n" + "=".repeat(80));+ console.log(" HARNESS vs NO-HARNESS COMPARISON");+ console.log("=".repeat(80));++ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;++ console.log("\n" + header);+ console.log(sep);++ for (let i = 0; i < noHarness.length; i++) {+ const nh = noHarness[i];+ const wh = withHarness[i];+ const nhPass = nh.passed ? "PASS" : "FAIL";+ const whPass = wh.passed ? "PASS" : "FAIL";+ const nhIssue = nh.issues[0] ?? "(none)";+ const whIssue = wh.issues[0] ?? "(none)";++ console.log(+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`+ );+ }++ // Metrics+ const nhPassed = noHarness.filter((r) => r.passed).length;+ const whPassed = withHarness.filter((r) => r.passed).length;+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);++ console.log("\n" + "=".repeat(80));+ console.log(" SUMMARY METRICS");+ console.log("=".repeat(80));++ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log("\n" + metricsHeader);+ console.log(metricsSep);+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);++ console.log("\n The harness catches problems the no-harness run silently ignores.");+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");+}++/** Count tasks that actually pass (have tests and are in scope). */+function truePassCount(results: TaskResult[]): number {+ return results.filter((r) => r.passed && r.issues.length === 0).length;+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparison(runWithoutHarness(tasks), runWithHarness(tasks));diff --git a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/index.mdnew file mode 100644index 0000000..1bbd6d3--- /dev/null+++ b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 02++استخدم هذا المجلد لأمثلة صغيرة تميّز بين:++- سلوك النموذج+- سلوك الـ harness+- إعدادات تعتمد على prompt فقط+- إعدادات وكلاء مدعومة بالبيئةdiff --git a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.tsnew file mode 100644index 0000000..e56cddd--- /dev/null+++ b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts@@ -0,0 +1,36 @@+type Message = {+ role: "user" | "assistant";+ content: string;+};++type ToolResult = {+ ok: boolean;+ output: string;+};++function runTool(name: string, input: string): ToolResult {+ if (name === "read_file") {+ return { ok: true, output: `contents of ${input}` };+ }++ return { ok: false, output: `unknown tool: ${name}` };+}++export function minimalHarness(messages: Message[]) {+ const nextAction = {+ tool: "read_file",+ input: "README.md"+ };++ const result = runTool(nextAction.tool, nextAction.input);++ return {+ messages: [+ ...messages,+ {+ role: "assistant",+ content: `Tool ${nextAction.tool} returned: ${result.output}`+ }+ ]+ };+}diff --git a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.mdnew file mode 100644index 0000000..7996183--- /dev/null+++ b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -0,0 +1,109 @@+[中文版本 →](../../../zh/lectures/lecture-02-what-a-harness-actually-is/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-02-what-a-harness-actually-is/code/)+> مشروع عملي: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# المحاضرة 02. ما معنى harness فعليًا++تُستخدم كلمة "harness" بكثرة في أوساط وكلاء البرمجة بالذكاء الاصطناعي، لكن بصراحة، معظم الناس يقصدون "ملف prompt" عندما يقولون harness. هذا ليس harness. الأمر أشبه بفتح مطعم ليس فيه سوى المكونات — لا موقد، ولا سكاكين، ولا وصفات، ولا خطة لتقديم الأطباق. هذا ليس مطعمًا. هذا ثلاجة.++تقدم لك هذه المحاضرة تعريفًا دقيقًا وقابلًا للتطبيق لمفهوم harness. ليس تجريدًا أكاديميًا، بل إطار عمل يمكنك استخدامه اليوم: يتكون harness من خمسة أنظمة فرعية، لكل منها مسؤوليات واضحة ومعايير تقييم محددة.++## ابدأ بتشبيه++تخيل أنك مهندس تم تعيينه حديثًا وأُلقيت في مشروع بدون أي توثيق. لا README، ولا تعليقات في الكود، ولا أحد يخبرك كيف تشغّل الاختبارات، وإعدادات CI مدفونة في مكان ما. هل يمكنك كتابة كود جيد؟ ربما — إذا كنت ذكيًا بما فيه الكفاية وصبورًا بما فيه الكفاية. لكنك ستقضي وقتًا هائلًا في "اكتشاف ما يدور حوله هذا المشروع" بدلاً من "حل المشكلة."++يواجه وكيل الذكاء الاصطناعي نفس الموقف تمامًا. والأمر أسوأ — يمكنك على الأقل سؤال زميل. الوكيل لا يمكنه رؤية سوى الملفات التي تضعها أمامه والأوامر التي يمكنه تنفيذها. لا يمكنه أن يربت على كتف أحدهم ويسأل "مرحبًا، أي إصدار من ORM يستخدمه هذا المشروع؟"++صاغت OpenAI المبدأ الأساسي بأن "المستودع هو المواصفة" — يجب أن يكون كل السياق الضروري في المستودع، مُقدمًا من خلال ملفات تعليمات منظمة، وأوامر تحقق صريحة، وتنظيم واضح للأدلة. توثيق Anthropic للوكلاء طويلي التشغيل يُؤكد على استمرارية الحالة، ومسارات الاسترداد الصريحة، وتتبع التقدم المنظم. الشركتان تركزان على جوانب مختلفة، لكنهما تقولان نفس الشيء: **كل شيء في البنية التحتية الهندسية خارج النموذج يحدد مقدار ما يتحقق فعليًا من قدرات النموذج.**++انظر إلى بعض الأدوات التي تعرفها بالفعل:++**Claude Code** يجسد تفكير harness. يقرأ `CLAUDE.md` من مستودعك (رف الوصفات)، ويمكنه تشغيل أوامر shell (حامل السكاكين)، وينفذ في بيئتك المحلية (الموقد)، ويحافظ على سجل الجلسة (محطة التحضير)، ويمكنه تشغيل الاختبارات ورؤية النتائج (نافذة فحص الجودة). لكن إذا لم تخبره كيف يشغّل الاختبارات، فنافذة فحص الجودة معطلة — لا أحد يعرف ما إذا كان الطبق ناضجًا بالكامل.++**Cursor** يتبع منطقًا مشابهًا. ملف `.cursorrules` الخاص به هو رف الوصفات، والطرفية هي حامل السكاكين، ويقرأ هيكل مشروعك وإعدادات lint كالموقد. لكن إدارة حالة Cursor ضعيفة نسبيًا — أغلق IDE وأعد فتحه، والسياق السابق اختفى.++**Codex** (وكيل البرمجة من OpenAI) يستخدم git worktrees لعزل بيئة تشغيل كل مهمة، مقترنًا بمكدس مراقبة محلي (سجلات، مقاييس، تتبعات)، بحيث يتم التحقق من كل تغيير في بيئة مستقلة. في المستودعات التي تحتوي على `AGENTS.md` وأوامر تحقق واضحة، فإنه يؤدي بشكل أفضل بكثير من المستودعات "العارية".++**AutoGPT** هي قصة تحذيرية — غياب إدارة الحالة المنظمة يؤدي إلى تراكم السياق في المهام الطويلة، وغياب آليات التغذية الراجعة الدقيقة يجعل الوكيل يدور في حلقة مفرغة. كثير من الناس يقولون إن AutoGPT "لا يعمل"، لكن في الحقيقة إن harness الخاص بـ AutoGPT هو الذي لا يعمل — أعطِ طباخًا موقدًا معطلًا وحتى أفضل المكونات لن تُنتج وجبة.++## المفاهيم الأساسية++- **ما هو harness**: كل شيء في البنية التحتية الهندسية خارج أوزان النموذج. تُلخص OpenAI الوظيفة الأساسية للمهندس في ثلاثة أشياء: تصميم البيئات، والتعبير عن النوايا، وبناء حلقات التغذية الراجعة. تسمي Anthropic Claude Agent SDK الخاص بها "harness وكيل للأغراض العامة."+- **المستودع هو المصدر الوحيد للحقيقة**: أي شيء لا يستطيع الوكيل رؤيته، لجميع الأغراض العملية، غير موجود. تتعامل OpenAI مع المستودع بصفته "سجل النظام" — يجب أن يعيش فيه كل السياق الضروري، من خلال ملفات منظمة وتنظيم واضح للأدلة.+- **أعطِ خريطة، لا دليلًا**: تجربة OpenAI — يجب أن يكون `AGENTS.md` صفحة فهرس، لا موسوعة. حوالي 100 سطر كافية. إذا لم تكف، قسّمها إلى دليل `docs/` ودع الوكيل يقرأ عند الحاجة.+- **قيّد، لا تُدارة بالتفصيل**: harness الجيد يستخدم قواعد قابلة للتنفيذ لتقييد الوكيل، بدلاً من تعداد التعليمات واحدة تلو الأخرى. تقول OpenAI "فرض الثوابت، لا تُدارة التنفيذ"؛ ووجدت Anthropic أن الوكلاء يمدحون عملهم بثقة، والحل هو فصل "من يقوم بالعمل" عن "من يتحقق من العمل."+- **أزل المكونات واحدًا تلو الآخر**: لقياس قيمة كل مكون من مكونات harness، أزلها واحدًا تلو الآخر وانظر أي إزالة تسبب أكبر انخفاض في الأداء. استخدمت Anthropic هذه الطريقة ووجدت أنه مع قوة النماذج، تتوقف بعض المكونات عن كونها حرجة — لكن جديدة تظهر دائمًا.++## نموذج harness ذو الأنظمة الفرعية الخمسة++نعود إلى تشبيه المطبخ. المطبخ الكامل يحتوي على خمس مناطق وظيفية، وharness يحتوي على خمسة أنظمة فرعية:++```mermaid+flowchart LR+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["Tools<br/>shell / files / tests"]+ Tools --> Env["Runtime<br/>deps / services / versions"]+ Env --> Checks["Check results<br/>test / lint / build"]+ Checks --> Agent+```++**نظام التعليمات (رف الوصفات)**: أنشئ `AGENTS.md` (أو `CLAUDE.md`) يحتوي على نظرة عامة على المشروع والغرض منه (جملة واحدة)، حزمة التقنيات والإصدارات (Python 3.11، FastAPI 0.100+، PostgreSQL 15)، أوامر التشغيل الأولى (`make setup`، `make test`)، القيود الصارمة غير القابلة للتفاوض ("جميع واجهات API يجب أن تستخدم OAuth 2.0")، وروابط إلى توثيق أكثر تفصيلًا.++**نظام الأدوات (حامل السكاكين)**: تأكد من أن الوكيل لديه وصول كافٍ للأدوات. لا تعطل shell بحجة "الأمان" — إذا لم يستطع الوكيل حتى تشغيل `pip install`، فكيف يُفترض أن يعمل؟ لكن لا تفتح كل شيء أيضًا — اتبع مبادئ الامتياز الأقل.++**نظام البيئة (الموقد)**: اجعل حالة البيئة واصفة لنفسها. استخدم `pyproject.toml` أو `package.json` لتثبيت التبعيات، و`.nvmrc` أو `.python-version` لإصدارات وقت التشغيل، وDocker أو devcontainers لضمان قابلية التكرار.++**نظام الحالة (محطة التحضير)**: المهام الطويلة تحتاج إلى تتبع التقدم. استخدم ملف `PROGRESS.md` بسيط يسجل: ما تم إنجازه، ما قيد التنفيذ، ما المحظور. حدّثه قبل نهاية كل جلسة، واقرأه عند بدء الجلسة التالية.++**نظام التغذية الراجعة (نافذة فحص الجودة)**: هذا هو النظام الفرعي ذو أعلى عائد على الاستثمار. اذكر أوامر التحقق صراحةً في `AGENTS.md`:+```+Verification commands:+- Tests: pytest tests/ -x+- Type check: mypy src/ --strict+- Lint: ruff check src/+- Full verification: make check (includes all above)+```++غياب أي نظام فرعي يشبه غياب منطقة وظيفية في المطبخ — لا يزال بإمكانك الطبخ، لكن الأمر دائمًا محرج.++**تشخيص جودة harness**: استخدم "التحكم المتساوي للنموذج." أبقِ النموذج ثابتًا، وأزل الأنظمة الفرعية واحدًا تلو الآخر، وقِس أي إزالة تسبب أكبر انخفاض في الأداء. هذا هو عنق الزجاجة الخاص بك — ركّز جهدك هناك. مثل البحث عن عنق الزجاجة في المطبخ: خذ رف الوصفات وانظر كم يصبح الأمر أبطأ، أطفئ الموقد وانظر التأثير.++## قصة فريق حقيقية++استخدم فريق GPT-4o على تطبيق واجهة أمامية بـ TypeScript + React (~20,000 سطر كود). مرّوا بأربع مراحل — بشكل أساسي إضافة معدات المطبخ قطعة قطعة:++**المرحلة 1 — مطبخ فارغ**: فقط وصف مشروع أساسي في README. نجحت محاولة واحدة من أصل 5 (20%). الأعطال الرئيسية: اختيار مدير حزم خاطئ (npm مقابل yarn)، عدم اتباع اصطلاحات تسمية المكونات، عدم القدرة على تشغيل الاختبارات.++**المرحلة 2 — رف الوصفات مُركّب**: أُضيف `AGENTS.md` بإصدارات حزمة التقنيات، واصطلاحات التسمية، والقرارات المعمارية الرئيسية. ارتفع معدل النجاح إلى 60%. كانت الأعطال المتبقية أساسًا مشاكل بيئية وتحقق مفقود.++**المرحلة 3 — نافذة فحص الجودة مفتوحة**: أُدرجت أوامر التحقق في `AGENTS.md`: `yarn test && yarn lint && yarn build`. ارتفع معدل النجاح إلى 80%.++**المرحلة 4 — محطة التحضير جاهزة**: أُدخلت قوالب ملفات التقدم حيث سجّل الوكلاء العمل المكتمل وغير المكتمل في كل تشغيل. استقر معدل النجاح عند 80-100%.++أربع تكرارات، النموذج لم يتغير إطلاقًا، ومعدل النجاح ارتفع من 20% إلى ما يقارب 100%. هذه هي قوة هندسة harness. لم تشترِ مكونات أغلى — لقد نظّمت المطبخ بشكل صحيح فحسب.++## الخلاصات الأساسية++- Harness = تعليمات + أدوات + بيئة + حالة + تغذية راجعة. خمسة أنظمة فرعية، مثل المناطق الوظيفية الخمس للمطبخ — جميعها أساسية.+- إذا لم تكن أوزان النموذج، فهي harness. إن harness الخاص بك يحدد مقدار ما يتحقق من قدرات النموذج.+- من بين الأنظمة الفرعية الخمسة، عادةً ما يكون نظام التغذية الراجعة هو الأقل استثمارًا والأعلى عائدًا. اجعل أوامر التحقق صحيحة أولاً — نافذة فحص الجودة هي الترقية الأكثر جدوى بالاستثمار.+- استخدم "التحكم المتساوي للنموذج" لقياس المساهمة الحدية لكل نظام فرعي — لا تعتمد على الحدس.+- harness يتآكل مثل الكود. راجع بانتظام، وسدد ديون harness كما تسدد الديون التقنية.++## قراءات إضافية++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)++## تمارين++1. **تدقيق harness الخماسي**: خذ مشروعًا تستخدم فيه وكيل ذكاء اصطناعي وقم بتدقيق كامل باستخدام إطار العمل الخماسي. قيّم كل نظام فرعي من 1 إلى 5. اعثر على النظام الفرعي الأقل تقييمًا، واقضِ 30 دقيقة في تحسينه، ثم لاحظ التغيير في أداء الوكيل.++2. **تجربة التحكم المتساوي للنموذج**: اختر نموذجًا واحدًا ومهمة صعبة واحدة. أزل التعليمات بالتتابع (احذف AGENTS.md)، وأزل التغذية الراجعة (لا تقدم أوامر تحقق)، وأزل الحالة (بدون ملفات تقدم) — أزل واحدًا فقط في كل مرة وقِس انخفاض الأداء. بناءً على النتائج، رتّب أهمية الأنظمة الفرعية لمشروعك.++3. **تحليل الأفعال**: اعثر على سيناريو في مشروعك حيث الوكيل "يريد أن يفعل شيئًا لكنه لا يستطيع" (مثلًا، يعرف أنه يجب استخدام استعلامات معلمّة لكنه لا يعرف أنماط ORM في مشروعك). حلل هل هذه فجوة تنفيذ (لا يعرف كيف) أم فجوة تقييم (لا يعرف ما إذا كان صحيحًا)، ثم صمّم تحسينًا لـ harness لسدّها.diff --git a/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdnew file mode 100644index 0000000..b3acc33--- /dev/null+++ b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md@@ -0,0 +1,7 @@+# كود المحاضرة 03++استخدم هذا المجلد لأمثلة عن:++- هياكل المستودعات القابلة للقراءة بواسطة الوكلاء+- الوثائق كسجل مرجعي للنظام (system of record)+- الموضع السيئ مقابل الجيد للمعرفةdiff --git a/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txtnew file mode 100644index 0000000..45315da--- /dev/null+++ b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt@@ -0,0 +1,13 @@+AGENTS.md+docs/+ ARCHITECTURE.md+ PRODUCT.md+ RELIABILITY.md+ references/+ electron.md+ sqlite.md+ plans/+ active/+ completed/+src/+scripts/diff --git a/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.tsnew file mode 100644index 0000000..46f6a62--- /dev/null+++ b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts@@ -0,0 +1,189 @@+/**+ * repo-reader.ts+ *+ * Reads a directory structure and scores it on discoverability.+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,+ * handoff files, and other signals of a repository that serves as the+ * system of record.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]+ * (defaults to current working directory if no path given)+ *+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Scoring criteria+// ---------------------------------------------------------------------------++interface Check {+ name: string;+ description: string;+ maxPoints: number;+ check: (dir: string) => { points: number; found: string[]; missing: string[] };+}++const checks: Check[] = [+ {+ name: "AGENTS.md / CLAUDE.md",+ description: "Agent-readable instruction file at repo root",+ maxPoints: 15,+ check: (dir) => {+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };+ },+ },+ {+ name: "Documentation directory",+ description: "Dedicated docs/ or documentation/ directory",+ maxPoints: 10,+ check: (dir) => {+ const candidates = ["docs", "documentation", "doc"];+ const found = candidates.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };+ },+ },+ {+ name: "Architecture documentation",+ description: "Files describing system architecture",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",+ "docs/architecture/", "design.md", "DESIGN.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };+ },+ },+ {+ name: "Feature tracking",+ description: "Feature list or task tracking file",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "feature_list.json", "features.md", "FEATURES.md",+ "docs/features.md", "tasks.json", "TODO.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };+ },+ },+ {+ name: "Handoff / session continuity",+ description: "Files for multi-session continuity",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",+ "docs/handoff.md", ".handoff", "PROGRESS.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };+ },+ },+ {+ name: "Testing structure",+ description: "Test directory or test configuration",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["test", "tests", "__tests__", "spec"];+ const found = patterns.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };+ },+ },+ {+ name: "Configuration files",+ description: "Project config (package.json, tsconfig, etc.)",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };+ },+ },+ {+ name: "README",+ description: "Root README file",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["README.md", "README.rst", "README.txt", "README"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };+ },+ },+];++// ---------------------------------------------------------------------------+// Report generation+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function scoreRepo(targetDir: string): void {+ const resolved = path.resolve(targetDir);++ if (!fs.existsSync(resolved)) {+ console.error(` Error: Directory not found: ${resolved}`);+ process.exit(1);+ }++ console.log("\n" + "=".repeat(80));+ console.log(" REPOSITORY DISCOVERABILITY SCORE");+ console.log("=".repeat(80));+ console.log(` Target: ${resolved}\n`);++ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ let totalScore = 0;+ let maxScore = 0;++ for (const check of checks) {+ const result = check.check(resolved);+ totalScore += result.points;+ maxScore += check.maxPoints;+ const status = result.points > 0 ? "PASS" : "FAIL";+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];++ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);+ }++ // Final score+ console.log("\n" + "-".repeat(80));+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);++ // Grade+ const pct = totalScore / maxScore;+ let grade: string;+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";+ else grade = "F -- Repository lacks discoverability signals";++ console.log(` GRADE: ${grade}`);+ console.log("=".repeat(80) + "\n");+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const target = process.argv[2] || process.cwd();+scoreRepo(target);diff --git a/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.mdnew file mode 100644index 0000000..50f41a4--- /dev/null+++ b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md@@ -0,0 +1,11 @@+# قائمة فحص سجل النظام (System of Record)++هل يمكن لوكيل جديد اكتشاف ما يلي من المستودع وحده؟++- ما المنتج الذي يتم بناؤه؟+- ماذا يجب أن يفعل التطبيق للمستخدمين؟+- كيف ينظّم الكود المصدري؟+- كيف يبدأ التطبيق؟+- كيف يتم فحص الحالة الصحية؟+- ما العمل الجاري حاليًا؟+- ما هي معايير الجودة المهمة؟diff --git a/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdnew file mode 100644index 0000000..c36de9d--- /dev/null+++ b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -0,0 +1,137 @@+[中文版本 →](../../../zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)+> مشروع عملي: [المشروع 02. مساحة عمل قابلة للقراءة بواسطة الوكلاء](./../../projects/project-02-agent-readable-workspace/index.md)++# المحاضرة 03. اجعل المستودع مصدر الحقيقة الوحيد++قرارات المعمارية في فريقك مبعثرة بين Confluence وSlack وJira ورؤوس بعض المهندسين الكبار. بالنسبة للبشر، هذا يعمل بالكاد: يمكنك سؤال زميل، أو البحث في سجل المحادثات، أو التنقيب في الوثائق. وإذا فشل كل شيء، يمكنك الإمساك بشخص في غرفة الاستراحة. لكن بالنسبة إلى وكيل ذكاء اصطناعي، فإن المعلومات غير الموجودة في المستودع لا وجود لها ببساطة.++هذا ليس مبالغة. فكّر في مدخلات الوكيل الفعلية: مطالبات النظام ووصف المهمة، محتوى الملفات من المستودع، ومخرجات تنفيذ الأدوات. هذا كل شيء. سجل Slack، وتذاكر Jira، وصفحات Confluence، وقرار المعمارية الذي ناقشته مع زميل على القهوة بعد ظهر الجمعة - لا يرى الوكيل شيئًا من ذلك. لا يستطيع "الذهاب ليسأل شخصًا" ولا "البحث في سجل المحادثة". إنه مهندس محبوس داخل المستودع؛ كل ما هو خارجه لا يعرف عنه شيئًا.++إذًا يصبح السؤال: هل ستعطي هذا المهندس خريطة جيدة؟++## ما الذي يجب أن يكون على الخريطة++تقول OpenAI ذلك بصراحة: **المعلومات التي لا توجد في المستودع لا توجد بالنسبة للوكيل.** يسمون هذا مبدأ "repo as spec" - أي أن المستودع نفسه هو وثيقة المواصفات ذات السلطة الأعلى.++توثيق Anthropic عن الوكلاء طويلة التشغيل يردد الفكرة نفسها: الحالة المستمرة شرط ضروري لاستمرارية المهام الطويلة. القدرة على استعادة المعرفة عبر الجلسات تحدد مباشرة معدلات نجاح المهام. وهذه الحالة يجب أن توجد في المستودع، لأنه التخزين الوحيد المستقر والقابل للوصول لدى الوكيل.++قد تفكر: "فريقنا صغير، والمعرفة في رؤوس الجميع، والأمور تسير جيدًا." صحيح بالنسبة للبشر. لكن إذا كنت تستخدم وكيلًا، فاقبل هذه الحقيقة: الوكيل لا يستطيع سؤال الناس. كل ما يحتاج إلى معرفته يجب أن يُكتب ويوضع حيث يستطيع العثور عليه.++ليس الأمر عن "كتابة المزيد من الوثائق". بل عن "وضع معلومات القرار في المكان الصحيح". ملف `ARCHITECTURE.md` من 50 سطرًا داخل `src/api/` أكثر فائدة بعشرة آلاف مرة من وثيقة تصميم من 500 صفحة في Confluence لا يصونها أحد. يشبه الأمر خريطة مكتب مرسومة يدويًا ومثبتة على مكتبك مقابل مخطط معماري جميل مقفل في خزانة ملفات: الأولى أمامك عندما تحتاجها؛ أما الثانية فقد تكون أفضل تقنيًا لكنها عديمة الفائدة في اللحظة.++## وضوح المعرفة++```mermaid+flowchart LR+ Slack["قواعد في Slack"] --> Write["اكتبها داخل ملفات المستودع<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["قواعد في Confluence"] --> Write+ Heads["قواعد في رؤوس الناس"] --> Write+ Jira["قواعد في تذاكر Jira"] --> Write+ Write --> Repo["ملفات المستودع"]+ Repo --> Agent["جلسة وكيل جديدة<br/>تقرأ المستودع مباشرة"]+ Warning["إذا لم تكن القاعدة في المستودع،<br/>فلن يراها الوكيل"] --> Agent+```++كيف تختبر إن كانت خريطتك جيدة بما يكفي؟ نفّذ "اختبار البدء البارد": افتح جلسة وكيل جديدة تمامًا تستخدم محتوى المستودع فقط، وانظر هل تستطيع الإجابة عن خمسة أسئلة أساسية:++```mermaid+flowchart TB+ Q1["ما هذا النظام؟"] --> A1["AGENTS.md / README"]+ Q2["كيف هو منظم؟"] --> A2["ARCHITECTURE.md / وثائق الوحدات"]+ Q3["كيف أشغله؟"] --> A3["Makefile / init.sh / package scripts"]+ Q4["كيف أتحقق منه؟"] --> A4["أوامر test و lint و check"]+ Q5["أين نحن الآن؟"] --> A5["PROGRESS.md / feature list / git history"]++ A1 --> Ready["يمكن لجلسة جديدة بدء العمل<br/>دون سؤال إنسان"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready+```++إذا لم تستطع الإجابة، ففي الخريطة فراغات. حيث تكون الخريطة فارغة، يخمّن الوكيل؛ التخمينات الخاطئة تصبح عيوبًا، وكثرة التخمين تستهلك السياق. وكل جلسة جديدة تخمّن من جديد. تكلفة التخمين دائمًا أعلى من تكلفة رسم الخريطة جيدًا من البداية.++## المفاهيم الأساسية++- **Knowledge Visibility Gap**: نسبة معرفة المشروع الكلية غير الموجودة في المستودع. كلما كبرت الفجوة، ارتفع معدل فشل الوكيل. كم من المعرفة الضمنية عن هذا المشروع يعيش في رأسك؟ احسبها كلها، ثم انظر كم دخل إلى المستودع - الفرق هو فجوة الوضوح.+- **System of Record**: مستودع الكود كمصدر رسمي لقرارات المشروع، وقيود المعمارية، وحالة التنفيذ، ومعايير التحقق. الكلمة الأخيرة للمستودع، ولا شيء آخر يُحسب. مثل خريطة تحدد "الطريق مغلق" - لن تسلك ذلك الطريق. لكن إذا كانت تلك المعلومة موجودة فقط في رأس شخص ما، فستضطر إلى سؤاله كل مرة.+- **Cold-Start Test**: الأسئلة الخمسة أعلاه. عدد الإجابات الممكنة يوضح مدى اكتمال خريطتك.+- **Discovery Cost**: مقدار ميزانية السياق التي يحرقها الوكيل للعثور على معلومة أساسية داخل المستودع. كلما كانت المعلومة مخفية أكثر، ارتفعت تكلفة الاكتشاف، وبقيت ميزانية أقل للمهمة الحقيقية. إخفاء معلومة حرجة في README على عمق عشرة مجلدات يشبه قفل مطفأة الحريق داخل خزنة في القبو: هي موجودة، لكنك لا تجدها عند الحاجة.+- **Knowledge Decay Rate**: نسبة مدخلات المعرفة التي تصبح قديمة لكل وحدة زمن. خروج الوثائق عن التزامن مع الكود هو العدو الأكبر - أسوأ من عدم وجود وثائق أصلًا.+- **ACID Analogy**: تطبيق مبادئ معاملات قواعد البيانات (Atomicity، Consistency، Isolation، Durability) على إدارة حالة الوكلاء. سنفصل ذلك أدناه.++## كيف ترسم خريطة جيدة++**المبدأ 1: المعرفة تعيش بجانب الكود.** قاعدة عن مصادقة نقاط API يجب أن تكون بجانب كود API، لا مدفونة في وثيقة عالمية ضخمة. ضع مستندًا قصيرًا في كل مجلد وحدة يشرح مسؤوليات الوحدة، وواجهاتها، وقيودها الخاصة. مثل لافتات رفوف المكتبة: إذا أردت كتب التاريخ، تذهب مباشرة إلى الرف المكتوب عليه "History". لا حاجة للبحث في المكتبة كلها.++**المبدأ 2: استخدم ملف دخول موحدًا.** `AGENTS.md` (أو `CLAUDE.md`) هو صفحة هبوط الوكيل. لا يحتاج إلى احتواء كل المعلومات، لكنه يجب أن يسمح للوكيل بالإجابة بسرعة عن ثلاثة أسئلة: "ما هذا المشروع؟"، "كيف أشغله؟"، و"كيف أتحقق منه؟". 50-100 سطر كافية.++**المبدأ 3: الحد الأدنى، لكن مكتمل.** يجب أن يكون لكل قطعة معرفة حالة استخدام واضحة. إذا لم يؤثر حذف قاعدة على جودة قرارات الوكيل، فلا ينبغي أن توجد تلك القاعدة. لكن كل سؤال في اختبار البدء البارد يجب أن تكون له إجابة. هذا توازن دقيق: لا كثير، ولا قليل، بل ما يكفي.++**المبدأ 4: حدّث مع الكود.** اربط تحديثات المعرفة بتغييرات الكود. أبسط نهج: ضع وثائق المعمارية في مجلد الوحدة المقابلة. عندما تعدّل الكود، ترى الوثيقة طبيعيًا. بعد تغييرات الكود، يمكن لـ CI تذكيرك بالتحقق مما إذا كانت الوثائق تحتاج تحديثًا.++**هيكل مستودع ملموس**:++```+project/+├── AGENTS.md # Entry: project overview, run commands, hard constraints+├── src/+│ ├── api/+│ │ ├── ARCHITECTURE.md # API layer architecture decisions+│ │ └── ...+│ ├── db/+│ │ ├── CONSTRAINTS.md # Database operation hard constraints+│ │ └── ...+│ └── ...+├── PROGRESS.md # Current progress: done, in-progress, blocked+└── Makefile # Standardized commands: setup, test, lint, check+```++## إدارة حالة الوكيل بمبادئ ACID++تأتي هذه الاستعارة من إدارة معاملات قواعد البيانات. قد تظن أنها تعقيد زائد، لكنها تمنحك إطارًا عمليًا جدًا:++- **Atomicity**: كل "عملية منطقية" (مثل "إضافة endpoint جديد وتحديث الاختبارات") تحصل على commit واحد في git. إذا فشلت في المنتصف، استخدم `git stash` للتراجع. الكل أو لا شيء - لا يوجد "نصف منجز".+- **Consistency**: عرّف شروط تحقق لـ "حالة متسقة": كل الاختبارات تنجح، وlint لا يبلغ عن أخطاء. يشغّل الوكيل التحقق بعد كل عملية؛ الحالات الوسيطة غير المتسقة لا تُسجّل في commit. مثل تحويل بنكي: لا يمكنك الخصم دون إضافة الرصيد.+- **Isolation**: عندما تعمل عدة وكلاء بالتوازي، صمم ملفات الحالة لتجنب race conditions. نهج بسيط: يستخدم كل وكيل ملف تقدم خاصًا به، أو تُستخدم فروع git للعزل. لا يستطيع طاهيان تتبيل القدر نفسه في الوقت نفسه - من يتحمل المسؤولية إذا أصبح مالحًا أكثر من اللازم؟+- **Durability**: معرفة المشروع الحرجة تعيش في ملفات متتبعة بـ git. يمكن للحالة المؤقتة أن تبقى في ذاكرة الجلسة، لكن المعرفة العابرة للجلسات يجب أن تُحفظ في ملفات. ما في رأسك لا يُحسب - ما هو مكتوب فقط يُحسب.++## قصة تحول حقيقية++كان فريق يصون منصة تجارة إلكترونية تضم نحو 30 خدمة مصغرة. قرارات المعمارية (بروتوكولات الاتصال بين الخدمات، استراتيجيات اتساق البيانات، قواعد إصدار API) كانت مبعثرة بين Confluence (قديم جزئيًا)، وSlack (يصعب البحث فيه)، ورؤوس بعض المهندسين الكبار (لا يتوسع)، وتعليقات كود متفرقة (غير منهجية).++بعد إدخال وكلاء الذكاء الاصطناعي، احتاجت 70% من المهام إلى تدخل بشري. كان كل فشل تقريبًا يتضمن انتهاك الوكيل لقيد ضمني من نوع "الجميع يعرفه لكن لا أحد كتبه". يشبه موظفًا جديدًا لم يخبره أحد "يجب أن تنشر طلب الغداء في محادثة المجموعة" - يخمّن خطأ، يُوبَّخ، لكن بعد التوبيخ لا يكتب أحد القاعدة.++نفذ الفريق تحولًا:+1. أنشأ `AGENTS.md` في جذر المستودع مع نظرة عامة على المشروع، وإصدارات مكدس التقنية، والقيود العالمية الصارمة+2. أضاف `ARCHITECTURE.md` في كل مجلد خدمة مصغرة يصف المسؤوليات، والواجهات، والاعتماديات+3. أنشأ `CONSTRAINTS.md` مركزيًا يتضمن القيود الصارمة بلغة "MUST/MUST NOT" صريحة+4. أضاف `PROGRESS.md` في كل مجلد خدمة لتتبع حالة العمل الحالية++بعد التحول، استطاع الوكيل نفسه الإجابة عن كل أسئلة المشروع الأساسية عند البدء البارد، وتحسنت جودة إنجاز المهام بوضوح.++## الخلاصات الأساسية++- المعرفة غير الموجودة في المستودع لا توجد بالنسبة للوكيل. وضع القرارات الحرجة في المستودع هو أبسط استثمار في الـ Harness - ارسم خريطة جيدة كي لا تضل الطريق.+- استخدم "اختبار البدء البارد" لتقييم جودة المستودع: هل تستطيع جلسة جديدة الإجابة عن خمسة أسئلة أساسية باستخدام محتوى المستودع فقط؟+- يجب أن تكون المعرفة قريبة من الكود، في حدها الأدنى لكنها مكتملة، ومحدثة مع الكود. ليس الأمر عن كتابة المزيد من الوثائق، بل عن وضع المعلومات في المكان الصحيح.+- استخدم مبادئ ACID لحالة الوكلاء: commits ذرية، تحقق من الاتساق، عزل التوازي، ومعرفة حرجة مستدامة.+- تدهور المعرفة هو العدو الأكبر. الوثائق غير المتزامنة مع الكود أخطر من غياب الوثائق - فهي ترسل الوكيل في الاتجاه الخطأ بينما يظن أنه على صواب.++## قراءات إضافية++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [ADR: Architecture Decision Records](https://adr.github.io/)+- [The Twelve-Factor App](https://12factor.net/)++## تمارين++1. **اختبار البدء البارد**: افتح جلسة وكيل جديدة تمامًا في مشروعك (لا سياق شفهي، محتوى المستودع فقط). اسأله خمسة أسئلة: ما هذا النظام؟ كيف هو منظم؟ كيف أشغله؟ كيف أتحقق منه؟ ما التقدم الحالي؟ سجل ما لا يستطيع الإجابة عنه، ثم حسّن المستودع حتى يستطيع.++2. **قياس تحويل المعرفة إلى خارج الرأس**: اسرد كل القرارات والقيود المهمة لعمل التطوير في مشروعك. علّم كل واحدة بأنها داخل المستودع أو خارجه. احسب Knowledge Visibility Gap لديك (النسبة خارج المستودع). ضع خطة لخفضها إلى أقل من 10%.++3. **تقييم ACID**: قيّم إدارة الحالة في مشروعك باستخدام استعارة ACID في هذه المحاضرة. Atomicity - هل يمكن التراجع عن عمليات الوكيل بشكل نظيف؟ Consistency - هل يوجد تحقق من "حالة متسقة"؟ Isolation - هل تتداخل الوكلاء المتزامنة مع بعضها؟ Durability - هل كل المعرفة العابرة للجلسات محفوظة؟diff --git a/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdnew file mode 100644index 0000000..79da699--- /dev/null+++ b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -0,0 +1,15 @@+# AGENTS.md++## ابدأ هنا++- اقرأ `docs/ARCHITECTURE.md`+- اقرأ `docs/PRODUCT.md`+- استخدم `npm run dev` لتشغيل التطبيق+- استخدم `npm run check` قبل اعتبار العمل مكتملًا++## قواعد صارمة++- لا تُغيّر حدود main/preload/renderer في Electron بدون قراءة+ `docs/ARCHITECTURE.md`+- لا تُعلن عن مكتمل بدون تحقق (verification)+- اترك حالة نظيفة (clean state) للجلسة التاليةdiff --git a/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdnew file mode 100644index 0000000..1632c57--- /dev/null+++ b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -0,0 +1,7 @@+# أنماط مضادة في ملفات التعليمات++- وضع كل معرفة المستودع في ملف واحد+- تكرار نفس القاعدة في أماكن متعددة+- ترميز قواعد قديمة لا يراجعها أحد+- كتابة تعليمات شرطية محددة جدًا لدرجة نادرًا ما تنطبق+- تضمين أدوات طويلة في سياق التشغيلdiff --git a/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdnew file mode 100644index 0000000..64e46d8--- /dev/null+++ b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md@@ -0,0 +1,7 @@+# كود المحاضرة 04++استخدم هذا المجلد لأمثلة عن:++- ملفات التعليمات الأحادية (monolithic)+- نقاط الدخول المختصرة+- أنماط الكشف التدريجي (progressive disclosure)diff --git a/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.tsnew file mode 100644index 0000000..59a9632--- /dev/null+++ b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts@@ -0,0 +1,209 @@+/**+ * split-vs-monolithic.ts+ *+ * Creates a monolithic instruction file (~200 lines) and then shows how+ * splitting into 4 focused files dramatically reduces the context needed+ * for any single query. Simulates an "agent" searching for a specific rule+ * and measures how many lines it must read in each approach.+ *+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts+ */++// ---------------------------------------------------------------------------+// Simulated monolithic instruction file (200 lines of rules)+// ---------------------------------------------------------------------------++const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];++// Section 1: Project Overview (lines 1-50)+for (let i = 1; i <= 50; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Project Overview",+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,+ });+}++// Section 2: Code Style Rules (lines 51-100)+for (let i = 51; i <= 100; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Code Style",+ content:+ i === 72+ ? "RULE: Always use explicit return types on exported functions."+ : i === 78+ ? "RULE: Use const assertions for immutable arrays."+ : `Style rule detail line ${i}`,+ });+}++// Section 3: Testing Standards (lines 101-150)+for (let i = 101; i <= 150; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Testing",+ content:+ i === 120+ ? "RULE: Every new endpoint must have integration tests."+ : i === 135+ ? "RULE: Test files must mirror the source file structure."+ : `Testing detail line ${i}`,+ });+}++// Section 4: Deployment Rules (lines 151-200)+for (let i = 151; i <= 200; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Deployment",+ content:+ i === 175+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."+ : `Deployment detail line ${i}`,+ });+}++// ---------------------------------------------------------------------------+// Split instruction files (4 focused files)+// ---------------------------------------------------------------------------++const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),+};++// ---------------------------------------------------------------------------+// Simulated queries -- the agent needs to find specific rules+// ---------------------------------------------------------------------------++interface Query {+ description: string;+ targetRule: string;+ relevantSection: string;+}++const queries: Query[] = [+ {+ description: "Find the rule about return types",+ targetRule: "explicit return types",+ relevantSection: "Code Style",+ },+ {+ description: "Find the deployment window rule",+ targetRule: "deploy on Fridays",+ relevantSection: "Deployment",+ },+ {+ description: "Find the integration test rule",+ targetRule: "integration tests",+ relevantSection: "Testing",+ },+ {+ description: "Find the test file structure rule",+ targetRule: "mirror the source file",+ relevantSection: "Testing",+ },+];++// ---------------------------------------------------------------------------+// Search simulation+// ---------------------------------------------------------------------------++function searchMonolithic(query: Query): { linesRead: number; found: boolean } {+ // Agent must scan from the top, reading each line until it finds the rule.+ // In the worst case it reads all lines.+ let linesRead = 0;+ let found = false;++ for (const line of monolithicInstructions) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found };+}++function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {+ // Agent knows which file to look in based on the section.+ // It only reads lines from that one file.+ const fileMap: Record<string, string> = {+ "Project Overview": "01-project-overview.md",+ "Code Style": "02-code-style.md",+ Testing: "03-testing.md",+ Deployment: "04-deployment.md",+ };++ const targetFile = fileMap[query.relevantSection];+ const lines = splitInstructions[targetFile];+ let linesRead = 0;+ let found = false;++ for (const line of lines) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found, fileAccessed: targetFile };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");+ console.log("=".repeat(90));++ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");++ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;+ console.log(header);+ console.log(sep);++ let totalMono = 0;+ let totalSplit = 0;++ for (const q of queries) {+ const mono = searchMonolithic(q);+ const split = searchSplit(q);+ totalMono += mono.linesRead;+ totalSplit += split.linesRead;++ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);+ console.log(+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`+ );+ }++ console.log(sep);+ const avgMono = Math.round(totalMono / queries.length);+ const avgSplit = Math.round(totalSplit / queries.length);+ console.log(+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`+ );++ console.log("\n" + "=".repeat(90));+ console.log(" KEY INSIGHT");+ console.log("=".repeat(90));+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");+}++run();diff --git a/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdnew file mode 100644index 0000000..b112f8a--- /dev/null+++ b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -0,0 +1,132 @@+[中文版本 →](../../../zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)+> مشروع عملي: [المشروع 02. مساحة عمل قابلة للقراءة بواسطة الوكلاء](./../../projects/project-02-agent-readable-workspace/index.md)++# المحاضرة 04. قسّم التعليمات عبر ملفات++أخذت هندسة الـ Harness بجدية. أنشأت ملف `AGENTS.md` ووضعت فيه كل قاعدة، وكل قيد، وكل درس تعلمته يخطر في بالك. بعد شهر أصبح الملف 300 سطر، وبعد شهرين 450 سطرًا، وبعد ثلاثة أشهر 600 سطر. ثم لاحظت أن أداء الوكيل يزداد سوءًا: في إصلاح عيب بسيط، يستهلك الوكيل قدرًا كبيرًا من السياق في معالجة تعليمات نشر غير ذات صلة؛ قيد أمني حرج مدفون في السطر 300 يتم تجاهله تمامًا؛ وثلاث قواعد متناقضة لأسلوب الكود تجعل الوكيل يختار واحدة عشوائيًا كل مرة.++هذا هو فخ "ملف التعليمات العملاق". يشبه حقيبة سفر محشوة أكثر من اللازم: كل شيء يبدو مفيدًا، فتضغطه داخلها حتى توشك السحّابة أن تنفجر. للعثور على قطعة ملابس بديلة، عليك إفراغ الحقيبة كلها. تحمل حقيبة ممتلئة، لكنك تستخدم ربما ثلث ما بداخلها فقط.++## الحلقة المفرغة في الجذر++الحلقة المفرغة الأكثر شيوعًا تسير هكذا: يخطئ الوكيل، فتقول "أضف قاعدة تمنع هذا"، وتضيفها إلى `AGENTS.md`، فتعمل مؤقتًا، ثم يخطئ الوكيل خطأ آخر، فتضيف قاعدة أخرى، وتكرر ذلك، حتى يتضخم الملف خارج السيطرة.++ليس هذا ذنبك. إنها استجابة طبيعية جدًا: إضافة قاعدة كلما حدث خطأ تبدو منطقية، مثل رمي شيء إضافي في حقيبتك كلما خرجت من المنزل "للاحتياط". لكن الأثر التراكمي كارثي. لنرَ ما الذي يتعطل تحديدًا.++**ميزانية السياق تُلتهم.** نافذة السياق لدى الوكيل محدودة. لنفترض أن لدى وكيلك نافذة 200K token (حجم شائع في Claude). قد يستهلك ملف تعليمات متضخم 10-20K token. يبدو أن هناك مساحة كثيرة؟ لكن المهمة المعقدة قد تحتاج إلى قراءة عشرات ملفات المصدر، ومخرجات الأدوات تستهلك سياقًا أيضًا، وسجل المحادثة يتراكم. عندما يحتاج الوكيل إلى فهم الكود، تكون الميزانية ضيقة بالفعل، مثل حقيبة مليئة بأشياء "للاحتياط" ولا يبقى فيها مكان للحاسوب المحمول.++**الضياع في المنتصف.** أثبت بحث "Lost in the Middle" (Liu et al., 2023) بوضوح أن نماذج اللغة الكبيرة تستخدم المعلومات الموجودة في منتصف النصوص الطويلة بفاعلية أقل بكثير من المعلومات في البداية أو النهاية. ملف `AGENTS.md` لديك طوله 600 سطر، وفي السطر 300 توجد عبارة "كل استعلامات قاعدة البيانات يجب أن تستخدم استعلامات مهيكلة بالمعاملات" - هذا قيد أمني صارم. لكنه مدفون في المنتصف، ومن المرجح جدًا أن يتجاهله الوكيل. مثل زجاجة واقي الشمس في قاع حقيبة محشوة: تعرف أنها موجودة، تبحث ثلاث مرات، لا تجدها، ثم تشتري واحدة أخرى.++**تضارب الأولويات.** يخلط الملف بين قيود غير قابلة للتفاوض ("never use eval()")، وإرشادات تصميم مهمة ("prefer functional style")، ودرس تاريخي محدد ("تم إصلاح تسرب ذاكرة في WebSocket الأسبوع الماضي، انتبه للأنماط المشابهة"). لهذه القواعد الثلاث مستويات أهمية مختلفة تمامًا، لكنها تبدو متطابقة داخل الملف. لا يملك الوكيل إشارة موثوقة للتمييز بينها، مثل جواز السفر وكابل الشحن مختلطين في الحقيبة بلا طريقة لمعرفة أيهما أكثر إلحاحًا.++**تدهور الصيانة.** الملفات الكبيرة صعبة الصيانة بطبيعتها. نادرًا ما تُحذف التعليمات القديمة، لأن عواقب الحذف غير واضحة ("ربما يعتمد شيء ما على هذه القاعدة")، بينما تبدو إضافة تعليمات جديدة مجانية. النتيجة: الملف يكبر فقط ولا يصغر، ونسبة الإشارة إلى الضجيج تهبط باستمرار. هذا بالضبط تراكم الدين التقني، لكن في التعليمات.++**تراكم التناقضات.** التعليمات المضافة في أوقات مختلفة تبدأ بالتناقض: واحدة تقول "استخدم TypeScript strict mode"، وأخرى تقول "بعض ملفات legacy تسمح بأنواع any". يختار الوكيل عشوائيًا أيهما يتبع كل مرة. مثل أن تقول لك أمك "ارتدِ ملابس دافئة" ويقول لك أبوك "لا تلبس كثيرًا"، فتقف عند الباب لا تعرف لمن تستمع.++## المفاهيم الأساسية++- **Instruction Bloat**: عندما يشغل ملف التعليمات أكثر من 10-15% من نافذة السياق، يبدأ بمزاحمة الميزانية المخصصة لقراءة الكود والتفكير في المهمة. قد يستهلك `AGENTS.md` من 600 سطر 10,000-20,000 token، أي 8-15% من نافذة 128K قبل أن يبدأ الوكيل أصلًا.+- **Lost in the Middle Effect**: أثبت بحث Liu et al. عام 2023 أن نماذج اللغة الكبيرة تستخدم المعلومات في منتصف النصوص الطويلة بفاعلية أقل بكثير من المعلومات في البداية أو النهاية. قيد حرج مدفون في السطر 300 من ملف 600 سطر لديه احتمال عالٍ أن يُتجاهل عمليًا.+- **Instruction Signal-to-Noise Ratio (SNR)**: نسبة التعليمات في ملف ما التي ترتبط بالمهمة الحالية. إجبار الوكيل على قراءة 50 سطرًا من تعليمات النشر أثناء إصلاح عيب يعني SNR منخفضًا.+- **Routing File**: ملف دخول قصير تتمثل وظيفته الأساسية في توجيه الوكيل إلى مستندات أكثر تفصيلًا، لا احتواء كل شيء بنفسه. 50-200 سطر كافية.+- **Progressive Disclosure**: أعطِ معلومات عامة أولًا، ثم التفاصيل عند الحاجة. تصميم Harness جيد يشبه تصميم واجهة جيدًا: لا ترمِ كل الخيارات على المستخدم دفعة واحدة.+- **Priority Ambiguity**: عندما تظهر كل التعليمات بالشكل نفسه وفي المكان نفسه، لا يستطيع الوكيل التمييز بين القيود الصارمة غير القابلة للتفاوض والإرشادات اللينة.++## بنية التعليمات++```mermaid+flowchart LR+ Mono["ملف AGENTS.md واحد من 600 سطر"] --> MonoLoad["حتى إصلاح عيب صغير<br/>يجب أن يقرأ قواعد النشر والملاحظات القديمة"]+ MonoLoad --> MonoRisk["القواعد المهمة المدفونة في المنتصف<br/>يسهل تفويتها"]++ Router["AGENTS.md قصير"] --> Topics["حمّل مستندات API / DB / testing<br/>فقط عندما تحتاجها المهمة"]+ Topics --> RoutedResult["يبقى سياق أكثر لقراءة الكود<br/>والتحقق"]+```++```mermaid+flowchart TB+ File["ملف تعليمات من 600 سطر"] --> Top["القسم العلوي<br/>quick start + قيود صارمة"]+ File --> Mid["القسم الأوسط<br/>قاعدة أمنية حرجة في السطر 300"]+ File --> Bot["القسم السفلي<br/>قائمة تحقق ختامية صريحة"]+ Top --> Seen["احتمال عالٍ للتذكر"]+ Bot --> Seen+ Mid --> Missed["احتمال عالٍ للتخفيف أو التفويت"]+```++## كيفية التقسيم++المبدأ الأساسي: أبقِ المعلومات المطلوبة كثيرًا في المتناول، وضع المعلومات المطلوبة أحيانًا في مكان منفصل، واترك ما لن تستخدمه أبدًا.++يبقى ملف الدخول `AGENTS.md` بين 50 و200 سطر، ويحتوي فقط على العناصر الأكثر استخدامًا: نظرة عامة على المشروع (جملة أو جملتان)، أوامر التشغيل الأولى (`make setup && make test`)، قيود عالمية صارمة (لا أكثر من 15 قاعدة غير قابلة للتفاوض)، وروابط إلى مستندات موضوعية (وصف من سطر واحد + شرط التطبيق).++```markdown+# AGENTS.md++## نظرة عامة على المشروع+Python 3.11 FastAPI backend, PostgreSQL 15 database.++## Quick Start+- Install: `make setup`+- Test: `make test`+- Full verification: `make check`++## Hard Constraints+- All APIs must use OAuth 2.0 authentication+- All database queries must use SQLAlchemy 2.0 syntax+- All PRs must pass pytest + mypy --strict + ruff check++## Topic Docs+- [API Design Patterns](docs/api-patterns.md) — Required reading when adding endpoints+- [Database Rules](docs/database-rules.md) — Required when modifying database operations+- [Testing Standards](docs/testing-standards.md) — Reference when writing tests+```++كل مستند موضوعي يكون بين 50 و150 سطرًا، منظمًا حسب الموضوع داخل `docs/` أو بجانب الوحدة المقابلة. يقرأه الوكيل فقط عند الحاجة. مثل مكعبات التنظيم داخل حقيبة السفر: الملابس في مكعب، أدوات العناية في آخر، الشواحن في ثالث. العثور على شيء لا يتطلب إفراغ الحقيبة كلها.++بعض المعلومات أفضل مكان لها داخل الكود مباشرة: تعريفات الأنواع، تعليقات الواجهات، وشرح ملفات الإعداد. يراها الوكيل طبيعيًا عند قراءة الكود، فلا حاجة لتكرارها في التعليمات.++ينبغي أن يكون لكل تعليمة مصدر ("لماذا أُضيفت هذه القاعدة؟")، وشرط تطبيق ("متى تكون مطلوبة؟")، وشرط انتهاء ("في أي ظروف يمكن حذفها؟"). راجع بانتظام، واحذف المدخلات القديمة والمكررة والمتناقضة. أدِر تعليماتك كما تدير اعتماديات الكود: الاعتماديات غير المستخدمة يجب حذفها، وإلا فهي تبطئ النظام فقط.++إذا كان لا بد من وجود تعليمة في ملف الدخول، فضعها في الأعلى أو الأسفل، لا في المنتصف. يخبرنا تأثير "lost in the middle" أن نماذج اللغة تستخدم المعلومات في الأطراف أفضل بكثير من المركز. لكن النهج الأفضل هو نقل التعليمات إلى مستندات موضوعية تُحمّل عند الطلب.++تدعم OpenAI وAnthropic ضمنيًا نهج التقسيم. تقول OpenAI إن ملفات الدخول يجب أن تكون "قصيرة وموجهة للتوجيه"، وتقول Anthropic إن معلومات التحكم في الوكلاء طويلة التشغيل يجب أن تكون "موجزة وعالية الأولوية". كلاهما يقول الشيء نفسه: لا تحشر كل شيء في ملف واحد. الحقيبة تحتاج تنظيمًا، لا ضغطًا بالقوة.++## مثال من الواقع++تضخم ملف `AGENTS.md` لدى فريق SaaS من 50 سطرًا إلى 600. كان يخلط إصدارات مكدس التقنية، ومعايير الكود، وملاحظات إصلاح عيوب تاريخية، وأدلة استخدام API، وإجراءات النشر، وتفضيلات شخصية لأعضاء الفريق - حقيبة كاملة توشك أن تنفجر.++بدأ أداء الوكيل يتدهور بوضوح: أثناء إصلاحات عيوب بسيطة، كان يستهلك سياقًا كبيرًا في معالجة تعليمات نشر غير ذات صلة؛ القيد الأمني "كل استعلامات قاعدة البيانات يجب أن تستخدم استعلامات مهيكلة بالمعاملات" كان مدفونًا في السطر 300 ويُتجاهل كثيرًا؛ ثلاث قواعد متناقضة لأسلوب الكود سببت سلوكًا عشوائيًا.++نفذ الفريق "إعادة تنظيم للحقيبة":+1. تقليص `AGENTS.md` إلى 80 سطرًا: فقط نظرة عامة على المشروع، أوامر التشغيل، و15 قيدًا عالميًا صارمًا+2. إنشاء مستندات موضوعية: `docs/api-patterns.md` (120 سطرًا)، `docs/database-rules.md` (60 سطرًا)، `docs/testing-standards.md` (80 سطرًا)+3. إضافة روابط المستندات الموضوعية في ملف التوجيه+4. تحويل الملاحظات التاريخية إلى اختبارات أو حذفها++بعد إعادة التنظيم، ارتفعت نسبة نجاح مجموعة المهام نفسها من 45% إلى 72%. وارتفع الالتزام بالقيد الأمني من 60% إلى 95%، لأنه انتقل من منتصف الملف إلى أعلى ملف التوجيه، ولم يعد "ضائعًا في المنتصف".++## الخلاصات الأساسية++- "إضافة قاعدة" مسكن قصير الأمد وسم طويل الأمد. قبل إضافة قاعدة، اسأل: هل ستكون أفضل في مستند موضوعي؟ لا تواصل حشو الحقيبة.+- ملف الدخول موجّه وليس موسوعة. 50-200 سطر مع نظرة عامة، قيود صارمة، وروابط فقط.+- استفد من تأثير "lost in the middle": المعلومات المهمة في الأعلى أو الأسفل؛ المعلومات الأقل أهمية تنتقل إلى مستندات موضوعية.+- أدِر تضخم التعليمات مثل الدين التقني. مراجعات دورية؛ كل تعليمة تحتاج مصدرًا، وشرط تطبيق، وشرط انتهاء.+- بعد التقسيم يتحسن SNR، ويصرف الوكيل ميزانية سياق أكثر على المهمة الفعلية بدل معالجة تعليمات غير ذات صلة.++## قراءات إضافية++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)++## تمارين++1. **تدقيق SNR**: خذ ملف تعليمات الدخول الحالي لديك واسرد كل التعليمات. اختر 5 أنواع شائعة من المهام وحدد ما إذا كانت كل تعليمة ذات صلة بتلك المهمة. احسب SNR لكل نوع مهمة. التعليمات التي تكون ضجيجًا لمعظم المهام يجب نقلها إلى مستندات موضوعية.++2. **إعادة تنظيم Progressive Disclosure**: إذا كان لديك ملف تعليمات يتجاوز 300 سطر، فقسّمه إلى: (a) ملف توجيه أقل من 100 سطر، (b) 3-5 مستندات موضوعية. شغّل مجموعة المهام نفسها (5 على الأقل) قبل وبعد، وقارن نسب النجاح.++3. **التحقق من Lost in the middle**: في ملف تعليمات طويل، ضع قيدًا حرجًا في الأعلى، والمنتصف، والأسفل على التوالي، وشغّل مجموعة المهام نفسها في كل مرة (5 تشغيلات على الأقل لكل موضع). راقب إن كان هناك فرق في معدل الالتزام. قد يفاجئك مدى قوة تأثير الموضع.diff --git a/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.mdnew file mode 100644index 0000000..36d2122--- /dev/null+++ b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md@@ -0,0 +1,6 @@+# قائمة فحص الاستمرارية++- هل يمكن لوكيل جديد تحديد العمل الأخير في أقل من خمس دقائق؟+- هل مسار التشغيل المستقر الحالي موثق؟+- هل العمل غير المنتهي محدد بوضوح؟+- هل المهمة التالية الأفضل مرئية بدون قراءة سجلات الدردشة القديمة؟diff --git a/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdnew file mode 100644index 0000000..c5c8824--- /dev/null+++ b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md@@ -0,0 +1,7 @@+# كود المحاضرة 05++استخدم هذا المجلد لأمثلة عن:++- مهام متعددة الجلسات معطلة+- مفقودات制品 الاستمرارية+- أنماط استعادة الاستمراريةdiff --git a/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdnew file mode 100644index 0000000..7480218--- /dev/null+++ b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -0,0 +1,17 @@+# مثال على تسليم الجلسة++## المكتمل++- إضافة دعم استيراد Markdown+- إضافة قائمة مستندات أساسية في العارض++## المعطل أو غير المُتحقق++- الاستيراد ينجح لملفات `.md` لكنه يفشل لملفات `.txt` الكبيرة+- التطبيق يبدأ، لكن عرض التفاصيل لم يتم توصيله++## الخطوة التالية الأفضل++- إصلاح مسار استيراد `.txt`+- التحقق من الاستيراد من البداية للنهاية+- ثم إضافة لوحة تفاصيل المستندdiff --git a/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.tsnew file mode 100644index 0000000..69f9c3e--- /dev/null+++ b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts@@ -0,0 +1,162 @@+/**+ * session-simulator.ts+ *+ * Simulates two sessions working on a multi-step task.+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.+ * Run 2: With handoff file -- Session B picks up where Session A left off.+ *+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface TaskStep {+ id: number;+ name: string;+ durationMs: number;+}++interface SessionResult {+ session: string;+ stepsCompleted: number;+ totalDurationMs: number;+ duplicatedSteps: number;+ output: string[];+}++// ---------------------------------------------------------------------------+// Task definition+// ---------------------------------------------------------------------------++const taskSteps: TaskStep[] = [+ { id: 1, name: "Read project structure", durationMs: 50 },+ { id: 2, name: "Understand existing auth module", durationMs: 80 },+ { id: 3, name: "Design new search endpoint", durationMs: 60 },+ { id: 4, name: "Implement search endpoint", durationMs: 100 },+ { id: 5, name: "Write integration tests", durationMs: 70 },+ { id: 6, name: "Update documentation", durationMs: 40 },+];++// ---------------------------------------------------------------------------+// Simulated session executor+// ---------------------------------------------------------------------------++/** Simulate a session doing work. */+function runSession(+ sessionName: string,+ startStep: number,+ endStep: number+): SessionResult {+ const output: string[] = [];+ let totalDuration = 0;++ for (let i = startStep; i <= endStep; i++) {+ const step = taskSteps.find((s) => s.id === i)!;+ totalDuration += step.durationMs;+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);+ }++ return {+ session: sessionName,+ stepsCompleted: endStep - startStep + 1,+ totalDurationMs: totalDuration,+ duplicatedSteps: 0,+ output,+ };+}++// ---------------------------------------------------------------------------+// Run 1: No handoff file+// ---------------------------------------------------------------------------++function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 before timing out+ const sessionA = runSession("Session A", 1, 3);++ // Session B has no context, starts from scratch+ const sessionB = runSession("Session B", 1, 6);+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Run 2: With handoff file+// ---------------------------------------------------------------------------++function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 and writes a handoff file+ const sessionA = runSession("Session A", 1, 3);++ // Session B reads handoff, starts from step 4+ const sessionB = runSession("Session B", 4, 6);+ sessionB.duplicatedSteps = 0;++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {+ console.log("\n" + "=".repeat(80));+ console.log(` ${title}`);+ console.log("=".repeat(80));++ console.log("\n Session A output:");+ for (const line of result.sessionA.output) {+ console.log(line);+ }++ console.log("\n Session B output:");+ for (const line of result.sessionB.output) {+ console.log(line);+ }++ console.log("\n Session B notes:");+ if (result.sessionB.duplicatedSteps > 0) {+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);+ } else {+ console.log(" - Read handoff file, continued from step 4");+ console.log(" - No duplicate work performed");+ }+}++function printComparison(): void {+ const noHandoff = simulateNoHandoff();+ const withHandoff = simulateWithHandoff();++ printRun("RUN 1: NO HANDOFF FILE", noHandoff);+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);++ // Comparison table+ console.log("\n" + "=".repeat(80));+ console.log(" COMPARISON TABLE");+ console.log("=".repeat(80) + "\n");++ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log(header);+ console.log(sep);++ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;++ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);++ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");+}++printComparison();diff --git a/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdnew file mode 100644index 0000000..2299d4c--- /dev/null+++ b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -0,0 +1,180 @@+[中文版本 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)+> مشروع عملي: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# المحاضرة 05. حافظ على السياق عبر الجلسات++تطلب من Claude Code تنفيذ ميزة كاملة. يعمل لمدة 30 دقيقة، وينجز معظم العمل، لكن السياق ينفد. تبدأ جلسة جديدة للاستمرار — وتكتشف أنه لا يتذكر ما القرارات التي اتُخذت في المرة السابقة، ولا لماذا خُيرت الخيار A على الخيار B، ولا أي الملفات عدّلت بالفعل، ولا في أي حالة تكون الاختبارات. يقضي 15 دقيقة في إعادة استكشاف المشروع، وقد يكون غير متسق مع النهج السابق.++تخيل لو كنت حرفيًا ينسى كل شيء كل صباح عند الاستيقاظ. سيتعين عليك إعادة التعرف على موقع البناء بالكامل — أي جدار نصف مكتمل، ولماذا اختيرت الطوب الأحمر بدلاً من الأزرق، وأين وصلت مسارات السباكة. والأخطر، قد تقتلع نافذة رُكّبت بالفعل أمس، ببساطة لأنك لم تتذكر أنه تم إنجازها.++هذا بالضبات ما يواجهه وكلاء البرمجة بالذكاء الاصطناعي في المهام العابرة للجلسات. تشرح هذه المحاضرة لماذا "يفقد الوكلاء الوعي" خلال المهام الطويلة، وكيف يمكن لاستمرارية الحالة المنظمة أن تجعلهم كحرفي يحتفظ بمذكرات يومية موثوقة — لا يزال مصابًا بفقدان الذاكرة، لكن المذكرة تتذكر كل شيء.++## نوافذ السياق: ليست بلا حدود++نوافذ السياق محدودة. هذه المشكلة لا تُحل بترقية النماذج — حتى لو نمت أحجام النوافذ إلى مليون token، فإن المهام المعقدة ستستنزفها. لأن الوكلاء لا يُولّدون الكود فحسب؛ بل يفهمون قواعد الكود، ويتابعون تاريخ قراراتهم، ويعالجون مخرجات الأدوات، ويحافظون على سياق المحادثة. كل هذه المعلومات تنمو أسرع من توسع النافذة.++مشكلة أعمق: المعلومات التي يُنتجها الوكيل ليست متساوية الأهمية. خطوات الاستدلال الوسيطة تحتوي على "السبب" وراء القرارات — لماذا خُير الخيار B على A، ولماذا هذه المكتبة بدلاً من تلك، ولماذا تُركي تحسين معين. المخرجات النهائية تحتوي فقط على "الماذا" — الكود نفسه. استراتيجيات الضغط عادةً تحافظ على الأخيرة وتفقد الأولى. الجلسة التالية ترى الكود لكنها لا تعرف لماذا كُتب بهذه الطريقة، وقد "تُحسّن" قرار تصميم متعمد بعيدًا.++اكتشفت Anthropic شيئًا مذهلًا في أبحاثها حول الوكلاء طويلي التشغيل: عندما يحس الوكلاء بنفاد السياق، يُظهرون سلوك "التقارب المبكر" — الاستعجال لإنهاء العمل الحالي، أو تخطي خطوات التحقق، أو اختيار حل بسيط بدلاً من الحل الأمثل. الأمر أشبه بإدراك أن الوقت ينفد في الامتحان والتخمين السريع في الأسئلة المتبقية متعددة الخيارات. تسمي Anthropic هذا "قلق السياق."++## تدفق استمرارية الجلسة++بدون مخرجات الاستمرارية، كل جلسة جديدة كارثة:++```mermaid+flowchart LR+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]+ End1 --> S2["Session 2 starts fresh"]+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]+```++مع مخرجات الاستمرارية، يمكن للجلسات الجديدة الاستمرار بسرعة:++```mermaid+flowchart LR+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]+ Work --> Verify["Verification notes<br/>which tests pass and fail"]+ Work --> Commit["Git checkpoint<br/>exact repo state"]++ Progress --> Rebuild["Session 2 rebuild"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["New session picks up quickly"]+```++## المفاهيم الأساسية++- **نوافذ السياق محدودة**: مهما كان حجم النافذة المُعلن عنه (128K، 200K، 1M)، المهام الطويلة ستستنزفها في النهاية. بعد الاستنفاد، يلزم إما ضغط (فقدان معلومات) أو إعادة تعيين (جلسة جديدة). كلاهما يفقد شيئًا ما.+- **مخرجات الاستمرارية**: ملفات حالة محفوظة تتيح لجلسة جديدة استئناف ما توقف عنده الجلسة السابقة بدون لبس. الشكل الأساسي: سجل تقدم + سجل تحقق + إجراءات تالية. مذكرة ذلك الحرفي.+- **تكلفة إعادة البناء**: الوقت الذي تحتاجه جلسة جديدة للوصول إلى حالة قابلة للتنفيذ. harness الجيد يمكن أن يضغط تكلفة إعادة البناء من 15 دقيقة إلى 3 دقائق.+- **الانحراف**: الفجوة بين فهم الوكيل والحالة الفعلية لمستودع الكود. كل حد جلسة يُدخل انحرافًا؛ بدون تحكم، يتراكم.+- **قلق السياق**: ظاهرة رصدتها Anthropic — يُظهر الوكلاء سلوك التقارب المبكر عند اقترابهم من حدود السياق المتوقعة، منهين المهام مبكرًا لتجنب فقدان المعلومات. إنه قلق موارد غير عقلاني.+- **الضغط مقابل إعادة التعيين**: الضغط يُلخص السياق داخل نفس الجلسة (يحافظ على "الماذا"، قد يفقد "السبب")؛ إعادة التعيين تفتح جلسة جديدة تعيد البناء من المخرجات المحفوظة (نظيفة لكنها تعتمد على اكتمال المخرجات).++## ماذا يحدث عندما تنقطع الاستمرارية++الجلسة السابقة أنفقت جزءًا كبيرًا من ميزانية السياق في تحليل ثلاثة أساليب واختيار الخيار B. وكيل هذه الجلسة لا يعرف عن ذلك التحليل وقد يعيد اتخاذ القرار بناءً على معلومات غير مكتملة — ربما يختار الخيار A. مثل الحرفي المصاب بفقدان الذاكرة الذي لا يتذكر لماذا اختير الطوب الأحمر، ينظر إلى الأزرق اليوم ويظنه أجمل، ويهدم جدار أمس ليبنيه من جديد.++الأسوأ من ذلك هو العمل المكرر. الوكيل غير متأكد مما إذا كان عمل معين قد أُنجز بالفعل فيقوم به مرة أخرى. أو الأسوأ — يُنجز نصفه، ويكتشف تعارضًا مع التنفيذ الموجود، ويضطر لإعادة العمل. في موقع بناء، لا يمكن لفريقين بناء نفس الجدار في وقت واحد — لكن بدون سجلات تقدم، الطاقم الجديد لا يعلم أن أحدهم يعمل عليه بالفعل.++عبر عدة جلسات، قد يكون اتجاه التنفيذ قد انحرف بصمت عن المتطلبات الأصلية. كل جلسة جديدة لديها فهم مختلف قليلًا لأهداف المشروع. مثل لعبة التلفاز — بعد أن يمرر عشرة أشخاص الرسالة، "أحضر لي قهوة" قد تصبح "اشترِ لي آلة قهوة."++هناك أيضًا فجوة التحقق. نتائج تحقق الجلسة السابقة (أي اختبارات نجحت، أيها فشلت، ولماذا فشلت) لم تُسجّل. الجلسة الجديدة عليها إعادة تشغيل كل التحقق لفهم الحالة الحالية. كل جلسة تعيد التشخيص من الصفر، في كل مرة تُهدر سياق ثمين.++كلتا الشركتين OpenAI وAnthropic تؤكدان على استمرارية الحالة المنظمة في توثيقهما. مقال OpenAI حول هندسة harness يتعامل مع المستودع بصفته "سجل عمليات" — يجب أن تترك نتائج كل عملية دليلًا قابلًا للتتبع في المستودع. توثيق Anthropic للوكلاء طويلي التشغيل يوصي تحديدًا بـ "ملفات التسليم" — مستندات منظمة تحتوي على الحالة الحالية، والمشاكل المعروفة، والإجراءات التالية.++## مذكرة للحرفي المصاب بفقدان الذاكرة++النهج الأساسي: **عامل الوكيل كمهندس عبقري مصاب بفقدان الذاكرة.** قبل أن "ينهي دوامه"، يجب أن يكتب المعلومات الحاسمة حتى يتمكن وكيل "المناوبة" التالي من الاستمرار بسرعة.++**الأداة 1: ملف التقدم (PROGRESS.md).** أقدم مخرجات الاستمرارية — جوهر المذكرة:++```markdown+# Project Progress++## Current State+- Latest commit: abc1234 (feat: add user preferences endpoint)+- Test status: 42/43 passing (test_pagination_edge_case failing)+- Lint: passing++## Completed+- [x] User model and database migration+- [x] Basic CRUD endpoints+- [x] Auth middleware integration++## In Progress+- [ ] Pagination feature (90% - edge case test failing)++## Known Issues+- test_pagination_edge_case returns 500 on empty result sets+- Need to confirm whether deleted users should appear in listings++## Next Steps+1. Fix pagination edge case bug+2. Add "include deleted users" query parameter+3. Update API documentation+```++**الأداة 2: سجل القرارات (DECISIONS.md).** سجّل قرارات التصميم المهمة وأسبابها. لا حاجة لمستندات تصميم مفصلة — فقط "أي قرار، لماذا، متى" — الملاحظات في المذكرة:++```markdown+# Design Decisions++## 2024-01-15: Use Redis for user preferences caching+- Reason: High read frequency (every API call), small data size+- Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile)+- Constraint: Cache TTL of 5 minutes, active invalidation on write+```++**الأداة 3: git commits كنقاط فحص.** Commit بعد إكمال كل وحدة عمل ذرية. يجب أن تشرح رسائل Commit ما تم إنجازه ولماذا. هذه لقطات حالة مجانية ومُصدَّرة تلقائيًا.++**الأداة 4: init.sh أو تدفق تهيئة harness.** حدد في `AGENTS.md` إجراءات "تسجيل الحضور" و"انتهاء الدوام":++```markdown+## At session start (clock in)+1. Read PROGRESS.md for current state+2. Read DECISIONS.md for important decisions+3. Run make check to confirm repo is in consistent state+4. Continue from PROGRESS.md "Next Steps" section++## Before session end (clock out)+1. Update PROGRESS.md+2. Run make check to confirm consistent state+3. Commit all completed work+```++**الاستراتيجية المختلطة**: ليست كل مهمة تحتاج إعادة تعيين السياق. المهام القصيرة (أقل من 30 دقيقة) يمكن إنجازها ضمن جلسة واحدة. المهام الطويلة (التي تمتد عبر جلسات) يجب أن تستخدم ملفات التقدم وسجلات القرارات للاستمرارية. معيار القرار: إذا كانت المهمة تحتاج أكثر من 60% من النافذة، ابدأ في تحضير التسليم.++### تعمق في قلق السياق++كشفت أبحاث Anthropic في مارس 2026 مزيدًا من مظاهر قلق السياق المحددة: على Sonnet 4.5، عندما يقترب السياق من حد النافذة، يُظهر الوكيل سلوك "التقارب المبكر" القوي. الأمر أشبه بإدراك أن الوقت قد انتهى تقريبًا في الامتحان والملء السريع بإجابات عشوائية.++استراتيجيتان تعالجان هذا:++**الضغط**: تلخيص المحادثة المبكرة داخل نفس الجلسة. الميزة: يحافظ على الاستمرارية، الوكيل يمكنه رؤية "الماذا." العيب: "السبب" غالبًا يُفقد في الملخصات — لماذا خُير الخيار B على A، ولماذا تُركي تحسين معين. الأكثر أهمية، الضغط لا يُزيل قلق السياق — الوكيل يعرف أن السياق كان كبيرًا يومًا ما، ونفسيًا لا يزال يميل إلى الاستعجال في الإنهاء.++**إعادة تعيين السياق**: مسح السياق بالكامل، وفتح جلسة جديدة، وإعادة البناء من المخرجات المحفوظة. الميزة: حالة ذهنية نظيفة — الجلسة الجديدة ليس لديها قلق "الوقت ينفد." العيب: يعتمد على اكتمال مخرجات التسليم. إذا كانت المذكرة تفتقر إلى معلومات حاسمة، قد تُهدر الجلسة الجديدة وقتًا في اتجاه خاطئ.++بيانات Anthropic الفعلية: على Sonnet 4.5، قلق السياق شديد بما يكفي لأن الضغط وحده غير كافٍ — تصبح إعادة تعيين السياق مكونًا حاسمًا في تصميم harness. لكن على Opus 4.5، هذا السلوك يقل كثيرًا، ويمكن للضغط إدارة السياق بدون الاعتماد على إعادة التعيين. هذا يعني: **تصميم harness يحتاج إلى فهم محدد للنموذج المستهدف، لا قالبًا واحدًا يناسب الجميع.**++> المصدر: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## مثال من الواقع++كُلّف وكيل بتنفيذ نظام مدونة مع مصادقة مستخدمين — 12 نقطة ميزة، وقُدّر أنها تحتاج 5 جلسات.++**الخط الأساسي بدون المذكرة**: الجلسة 1 نفّذت نموذج المستخدم والمسارات الأساسية. الجلسة 2 بدأت بدون أن يتذكر الوكيل عقد واجهة middleware المصادقة، وقضى ~15 دقيقة في استنتاج نية التصميم السابقة. بحلول الجلسة 3، الانحراف المتراكم جعل الوكيل يبدأ في إعادة تنفيذ ميزات مكتملة بالفعل. بحلول الجلسة 5، المستودع يحتوي على الكثير من الكود المكرر لكن ميزة المصادقة الأساسية لم تجتز اختبارات شاملة بعد. فقط 7 من 12 نقطة ميزة أُنجزت، 3 منها بمشاكل صحة خفية. مثل الحرفي الذي لا يكتب في مذكرته أبدًا — بحلول اليوم الخامس، موقع البناء في حالة فوضى، بعض الجدران بُنيت مرتين، وبعضها الذي كان يجب بناؤه لم يُبدأ.++**مع المذكرة**: باستخدام ملفات التقدم، وسجلات القرارات، وسجلات التحقق، ونقاط فحص git. تُحدَّث تقارير الحالة تلقائيًا عند نهاية كل جلسة. تكلفة إعادة بناء الجلسة 2 انخفضت إلى ~3 دقائق. بحلول الجلسة 5، أُنجزت كل نقاط الميزة الـ 12 وتحققت منها.++مقارنة كمية: وقت إعادة البناء انخفض ~78%، ومعدل إكمال الميزات من 58% إلى 100%، ومعدل العيوب الخفية من 43% إلى 8%. الحرفي لا يزال مصابًا بفقدان الذاكرة، لكن مع المذكرة، كل يوم يبدأ من حيث توقف أمس، لا من الصفر.++## الخلاصات الأساسية++- نوافذ السياق مورد محدود. المهام الطويلة ستمتد عبر جلسات، والجلسات ستفقد معلومات — مثل الحرفي الذي ينسى كل يوم، هذا واقع موضوعي.+- الحل ليس نوافذ أكبر — بل استمرارية حالة أفضل. ملفات التقدم + سجلات القرارات + نقاط فحص git — أعطِ الحرفي المصاب بفقدان الذاكرة مذكرة موثوقة.+- عامل الوكيل كمهندس مصاب بفقدان الذاكرة: قبل "انتهاء الدوام"، اكتب ما تم إنجازه، ولماذا، وما التالي.+- تكلفة إعادة البناء هي المقياس الأساسي. harness الجيد يجب أن يوصل الجلسات الجديدة إلى حالة قابلة للتنفيذ خلال 3 دقائق.+- الاستراتيجية المختلطة: مهام قصيرة ضمن الجلسات، مهام طويلة مع مخرجات منظمة للاستمرارية.++## قراءات إضافية++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [Claude Code Documentation](https://docs.anthropic.com/ar/docs/claude-code)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)++## تمارين++1. **قياس فقدان الاستمرارية**: اختر مهمة تطوير تحتاج 3 جلسات على الأقل. بدون تقديم أي مخرجات استمرارية، سجّل عند بدء كل جلسة كم سياق يُنفق في "اكتشاف ما حدث في المرة السابقة." بعد كل جلسة، أنشئ ملف تقدم ودع الجلسة التالية تبدأ منه. قارن تكاليف إعادة البناء مع وبدون ملفات التقدم.++2. **تصميم قالب تسليم**: صمّم قالب تسليم بسيط بأربعة حقول: حالة المستودع (commit hash)، حالة وقت التشغيل (معدل نجاح الاختبارات)، العوائق، الإجراءات التالية. دع جلسة وكيل جديدة تمامًا تستعيد حالة المشروع باستخدام هذا القالب فقط. سجّل الالتباسات التي واجهتها أثناء الاستعادة، وكرّر لتحسين القالب.++3. **تجربة الاستراتيجية المختلطة**: في مهمة تطوير من 5 جلسات، قارن ثلاث استراتيجيات: (a) دائمًا ابدأ جلسات جديدة + ملفات تقدم، (b) أنجز قدر الممكن في جلسة واحدة (ضغط السياق)، (c) استراتيجية مختلطة (مهام قصيرة ضمن الجلسة، مهام طويلة عبر جلسات + ملفات تقدم). قارن وقت إعادة البناء، ومعدل إكمال الميزات، وثبات القرارات.diff --git a/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdnew file mode 100644index 0000000..9f5c15f--- /dev/null+++ b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 06++استخدم هذا المجلد لأمثلة عن:++- مخرجات التهيئة+- سكربتات التهيئة+- ملفات التقدم+- هيكلة التشغيل الأولdiff --git a/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.tsnew file mode 100644index 0000000..52dcd98--- /dev/null+++ b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts@@ -0,0 +1,296 @@+/**+ * init-check.ts+ *+ * Programmatically checks initialization prerequisites:+ * - Node.js version+ * - Dependencies installed (node_modules exists)+ * - Data directory exists+ * - Config files present+ *+ * Simulates running with and without an explicit init phase,+ * showing how missing prerequisites cause silent failures later.+ *+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";+import * as childProcess from "node:child_process";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface CheckItem {+ name: string;+ category: string;+ check: () => { pass: boolean; detail: string };+ impactIfMissing: string;+}++interface CheckResult {+ name: string;+ category: string;+ passed: boolean;+ detail: string;+ impactIfMissing: string;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++function createChecks(targetDir: string): CheckItem[] {+ return [+ {+ name: "Node.js version >= 18",+ category: "Runtime",+ check: () => {+ try {+ const version = process.version; // e.g. "v20.11.0"+ const major = parseInt(version.replace("v", "").split(".")[0], 10);+ return {+ pass: major >= 18,+ detail: `Detected: ${version} (need >= v18)`,+ };+ } catch {+ return { pass: false, detail: "Could not detect Node.js version" };+ }+ },+ impactIfMissing: "TypeScript features and built-in APIs unavailable",+ },+ {+ name: "package.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "package.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found in target directory",+ };+ },+ impactIfMissing: "Cannot install dependencies or run scripts",+ },+ {+ name: "Dependencies installed (node_modules)",+ category: "Dependencies",+ check: () => {+ const p = path.join(targetDir, "node_modules");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",+ };+ },+ impactIfMissing: "All imports fail at runtime",+ },+ {+ name: "TypeScript available",+ category: "Toolchain",+ check: () => {+ try {+ const result = childProcess.execSync("npx tsc --version", {+ encoding: "utf-8",+ timeout: 10000,+ stdio: ["pipe", "pipe", "pipe"],+ }).trim();+ return { pass: true, detail: `Detected: ${result}` };+ } catch {+ return { pass: false, detail: "TypeScript not available via npx" };+ }+ },+ impactIfMissing: "Cannot compile TypeScript files",+ },+ {+ name: "tsconfig.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "tsconfig.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found",+ };+ },+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",+ },+ {+ name: "Source directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["src", "lib", "app"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",+ };+ },+ impactIfMissing: "Agent cannot locate source files to modify",+ },+ {+ name: "Test directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["test", "tests", "__tests__", "spec"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",+ };+ },+ impactIfMissing: "Agent cannot find or run existing tests",+ },+ {+ name: "Git repository initialized",+ category: "Version Control",+ check: () => {+ const gitDir = path.join(targetDir, ".git");+ const exists = fs.existsSync(gitDir);+ return {+ pass: exists,+ detail: exists ? "Git repository detected" : "No .git directory found",+ };+ },+ impactIfMissing: "No rollback capability, no change history",+ },+ ];+}++// ---------------------------------------------------------------------------+// Simulation: with and without init phase+// ---------------------------------------------------------------------------++interface SimResult {+ scenario: string;+ checksRun: boolean;+ failuresBeforeWork: number;+ workAttempted: boolean;+ workSucceeded: boolean;+ timeWastedMs: number;+}++function simulateWithoutInit(): SimResult {+ // Agent skips init, goes straight to work.+ // Encounters failures one at a time as it hits missing prerequisites.+ const checks = createChecks(process.cwd());+ let failures = 0;+ let timeWasted = 0;++ for (const check of checks) {+ const result = check.check();+ if (!result.pass) {+ failures++;+ timeWasted += 200; // Agent spends time discovering each missing piece+ }+ }++ return {+ scenario: "NO INIT PHASE",+ checksRun: false,+ failuresBeforeWork: 0, // Didn't check upfront+ workAttempted: true,+ workSucceeded: failures === 0,+ timeWastedMs: timeWasted,+ };+}++function simulateWithInit(): SimResult {+ // Agent runs init phase first, discovers all issues upfront.+ const checks = createChecks(process.cwd());+ let failures = 0;++ for (const check of checks) {+ if (!check.check().pass) {+ failures++;+ }+ }++ return {+ scenario: "WITH INIT PHASE",+ checksRun: true,+ failuresBeforeWork: failures,+ workAttempted: failures === 0,+ workSucceeded: failures === 0,+ timeWastedMs: 0,+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.cwd();+ console.log("\n" + "=".repeat(80));+ console.log(" INITIALIZATION PREREQUISITE CHECK");+ console.log("=".repeat(80));+ console.log(` Target: ${targetDir}\n`);++ const checks = createChecks(targetDir);+ const results: CheckResult[] = checks.map((c) => {+ const r = c.check();+ return {+ name: c.name,+ category: c.category,+ passed: r.pass,+ detail: r.detail,+ impactIfMissing: c.impactIfMissing,+ };+ });++ // Detailed report+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const status = r.passed ? "PASS" : "FAIL";+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);+ }++ const passCount = results.filter((r) => r.passed).length;+ const failCount = results.filter((r) => !r.passed).length;++ console.log("\n" + "-".repeat(80));+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);++ if (failCount > 0) {+ console.log("\n FAILED CHECKS -- Impact if not resolved:");+ for (const r of results.filter((r) => !r.passed)) {+ console.log(` - ${r.name}: ${r.impactIfMissing}`);+ }+ }++ // Comparison: with vs without init+ const noInit = simulateWithoutInit();+ const withInit = simulateWithInit();++ console.log("\n" + "=".repeat(80));+ console.log(" INIT PHASE COMPARISON");+ console.log("=".repeat(80) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);++ console.log("\n An explicit init phase catches problems before they waste time.\n");+}++run();diff --git a/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.shnew file mode 100644index 0000000..2c6e1b0--- /dev/null+++ b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh@@ -0,0 +1,10 @@+#!/usr/bin/env bash+set -euo pipefail++echo "[init] installing dependencies"+npm install++echo "[init] starting the docs site is optional"+echo "[init] use npm run docs:dev for course docs"++echo "[init] project-specific startup would go here"diff --git a/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.mdnew file mode 100644index 0000000..41c8224--- /dev/null+++ b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md@@ -0,0 +1,7 @@+# قائمة فحص مخرجات التهيئة++- هل يوجد أمر تشغيل معياري؟+- هل يوجد أمر تحقق معياري؟+- هل يوجد أول مُنتج تقدم (progress artifact)؟+- هل يوجد أول التزام (commit) مستقر؟+- هل يوجد سطح ميزات مرئي للجلسات اللاحقة؟diff --git a/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdnew file mode 100644index 0000000..8d135ee--- /dev/null+++ b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -0,0 +1,157 @@+[中文版本 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)+> مشروع عملي: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# المحاضرة 06. هيئ قبل كل جلسة وكيل++تبدأ جلسة وكيل جديدة وتقول "أضف ميزة بحث." يقفز مباشرة إلى البرمجة — حماس مُعجب. بعد 20 دقيقة يكتشف أن إطار الاختبار غير مضبوط بشكل صحيح، يقضي 10 دقائق أخرى في إصلاح ذلك، ثم تنسيق نص ترحيل قاعدة البيانات خاطئ، المزيد من العبث. ميزة البحث تُضاف في النهاية، لكن الجلسة كلها كانت غير فعالة — معظم الوقت ذهب إلى "اكتشاف كيف يعمل هذا المشروع" بدلاً من كتابة ميزة البحث.++النهج الأفضل: قبل السماح للوكيل ببدء العمل، استخدم مرحلة منفصلة لتجهيز البيئة الأساسية، واجعل أوامر التحقق ناجحة، وهيكل المشروع مفهومًا. الأمر أشهر ببناء منزل — لا تصب الأساس وترفع الجدران في وقت واحد. إذا فعلت، ترتفع الجدران قبل أن يتصلب الأساس، ويجب هدم المبنى بالكامل والبدء من جديد. صب الأساس أولًا، دعه يتصلب، ثم ابنِ الجدران — نظيف وفعال.++تشرح هذه المحاضرة لماذا يجب أن تكون التهيئة مرحلة منفصلة، لا مختلطة بالتنفيذ.++## الأساس والجدران: وظيفتان مختلفتان جذريًا++التهيئة والتنفيذ لهما أهداف تحسين مختلفة تمامًا. مرحلة التنفيذ تُحسِّن من: زيادة كمية وجودة الميزات المُتحقَقة. مرحلة التهيئة تُحسِّن من: زيادة موثوقية وكفاءة كل التنفيذ اللاحق.++عندما تخلط التهيئة والتنفيذ، يواجه الوكيل مشكلة تحسين متعددة الأهداف — بناء البنية التحتية وكتابة كود الميزات في وقت واحد. بدون تحديد أولويات صريح، يميل الوكيل طبيعيًا نحو كتابة الكود (لأن ذلك مخرج مرئي مباشر) مع التضحية بالبنية التحتية (لأن قيمتها تظهر فقط في الجلسات اللاحقة). الأمر أشبه بإخبار طاقم بناء بصب الأساس ورفع الجدران في وقت واحد — سيسرعون على الأرجح لرفع الجدران لأن الجدران مرئية ويمكن إثباتها. لكن المنزل ذو الأساس السيء سيواجه مشاكل نظامية لاحقًا.++## دورة حياة التهيئة++```mermaid+flowchart TB+ subgraph Wrong["Mixed session (wrong)"]+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]+ W2 --> W3["Accumulate unverified code"]+ W3 --> W4["Next session must rediscover project state"]+ end++ subgraph Right["Dedicated initialization (right)"]+ R1["Session 1: environment runnable"] --> R2["Example test passing"]+ R2 --> R3["Bootstrap contract + task list written"]+ R3 --> R4["Clean checkpoint committed"]+ R4 --> R5["Later sessions start directly on verified tasks"]+ end+```++## ماذا يحدث عند خلطهما++المشكلة الأكثر مباشرة: الأساس لا يتصلب بشكل صحيح. الوكيل ينفق 80% من جهده على كود الميزات و20% في إعداد بعض البنية التحتية بشكل عابر. إطار الاختبار مضبوط لكن لم يُتحقق منه قط، وقواعد lint محددة لكنها متساهلة جدًا، ولم يُنشأ ملف تقدم. هذه العيوب ليست واضحة في الجلسة الأولى (لأن الوكيل لا يزال يتذكر ما فعله)، لكنها تظهر في الجلسة الثانية — الوكيل الجديد لا يعرف كيف يُشغّل، أو يختبر، أو أين تقف الأمور. أساس رديء، مبنى مهتز.++تكلفة أخفى هي "التراكم غير المُتحقَق" — كود الميزات المكتوب قبل ضبط إطار الاختبار هو كود بدون تحقق. عندما تعود أخيرًا لإضافة اختبارات لهذا الكود، قد تكتشف أن التصميم كان خاطئًا من البداية — لو كنت تعرف، لطبّقته بشكل مختلف. مثل تبليط سطح خرسانة رطبة — عندما تكتشف أن الأرضية غير مستوية، يجب نزع كل البلاط وإعادة العمل.++ميزانية الجلسة تُهدر أيضًا. عمل التهيئة (ضبط البيئات، إعداد الاختبارات، فهم هيكل المشروع) يستهلك ميزانية كبيرة، تاركًا أقل للتنفيذ الفعلي للميزات. النتيجة: الجلسة الأولى تُنجز نصف الميزات فقط، والجلسة الثانية عليها البدء من جديد في فهم المشروع. ميزانية أُنفقت على الأساس، لكن الأساس ليس متينًا أيضًا — لم يتحقق أي هدف.++المشكلة الأكثر تجاهلًا هي ألغام الافتراضات الضمنية. القرارات التي يتخذها الوكيل أثناء التهيئة (أي إطار اختبار، كيف تنظيم الأدلة، إدارة التبعيات) — إذا لم تُسجَّل صراحةً، لا يمكن للجلسات اللاحقة فهم هذه الخيارات. الأسوأ، أن الجلسات اللاحقة قد تتخذ خيارات متناقضة. طاقم البناء الأول استخدم أساسًا خرسانيًا، والطاقم الثاني لا يعرف وغرس فيه أوتادًا خشبية — الأساس يتشقق.++أبحاث Anthropic لتطوير التطبيقات طويلة التشغيل توصي صراحةً بفصل التهيئة عن التنفيذ. بياناتهم التجريبية: المشاريع التي استخدمت مرحلة تهيئة مخصصة أظهرت معدلات إكمال ميزات أعلى بنسبة 31% في سيناريوهات الجلسات المتعددة مقارنة بالأساليب المختلطة. الرؤية الأساسية — الوقت المستثمر في مرحلة التهيئة يُسترد بالكامل في الجلسات الـ 3-4 التالية. كلما كان الأساس أصلب، ارتفعت الجدران أسرع.++دليل OpenAI Codex لهندسة harness يُؤكد أيضًا على مبدأ "المستودع كسجل عمليات" — أَسِّس هيكل عمليات واضحًا من التشغيل الأول، وإلا ستضطر كل جلسة جديدة إلى استنتاج اصطلاحات المشروع من جديد.++## المفاهيم الأساسية++- **مرحلة التهيئة**: المرحلة الأولى في دورة حياة الوكيل — بدون تنفيذ ميزات، فقط إعداد المتطلبات المسبقة لكل مراحل التنفيذ اللاحقة. المخرج ليس كودًا، بل بنية تحتية.+- **عقد الإقلاع**: الشروط التي يمكن بموجبها تشغيل المشروع بوضوح بواسطة جلسة وكيل جديدة — يمكن البدء، يمكن الاختبار، يمكن رؤية التقدم، يمكن استئناف الخطوات التالية. أربعة شروط، جميعها مطلوبة.+- **البدء البارد مقابل البدء الدافئ**: البدء البارد هو من دليل فارغ حيث يجب على الوكيل تخمين هيكل المشروع؛ البدء الدافئ هو من قالب أو مشروع موجود حيث البنية التحتية جاهزة بالفعل. البدء الدافئ يتفوق بكثير على البدء البارد — مثل بدء العمل في موقع به مياه جارية وكهرباء مقابل البدء من أرض قاحلة.+- **جاهزية التسليم**: المشروع في حالة تسمح في أي لحظة لوكيل جديد بتسلمه. لا حاجة لشرح شفهي — فقط محتويات المستودع.+- **الوقت حتى أول تحقق**: الوقت من بداية المشروع حتى اجتياز أول نقطة ميزة للتحقق. هذا هو المقياس الأساسي لقياس كفاءة التهيئة.+- **قابلية الاستخدام اللاحقة**: أفضل مقياس لجودة التهيئة — نسبة الجلسات اللاحقة التي يمكنها تنفيذ المهام بنجاح دون الاعتماد على معرفة ضمنية.++## كيف تُنجز التهيئة بشكل صحيح++**عامل التهيئة كمرحلة مخصصة.** الجلسة الأولى تُنجز التهيئة فقط — بدون أي كود ميزات أعمال. التهيئة تُنتج:++**1. بيئة قابلة للتشغيل.** المشروع يبدأ، التبعيات مثبتة، لا مشاكل بيئية. الأساس مَصوب، بدون شقوق.++**2. إطار اختبار قابل للتحقق.** اختبار مثال واحد على الأقل يجتاز بنجاح. هذا يثبت أن إطار الاختبار نفسه مضبوط بشكل صحيح — مثل إقامة عمود على الأساس لإثبات أنه يحمل الوزن.++**3. مستند عقد الإقلاع.** مستند واضح يخبر الجلسات اللاحقة:+```markdown+# Initialization Contract++## Start Commands+- Install dependencies: `make setup`+- Start dev server: `make dev`+- Run tests: `make test`+- Full verification: `make check`++## Current State+- All dependencies installed and locked+- Test framework configured (Vitest + React Testing Library)+- Example test passing (1/1)+- Lint rules configured (ESLint + Prettier)++## Project Structure+- src/ — Source code+- src/components/ — React components+- src/api/ — API client+- tests/ — Test files+```++**4. تقسيم المهام.** قسّم المشروع بالكامل إلى قائمة مهام مرتبة، كل مهمة بمعايير قبول واضحة:+```markdown+# Task Breakdown++## Task 1: User Authentication Basics+- Implement JWT auth middleware+- Add login/register endpoints+- Acceptance: pytest tests/test_auth.py all passing++## Task 2: User Profile Page+- Implement user profile CRUD+- Add profile edit form+- Acceptance: pytest tests/test_profile.py all passing++## Task 3: Search Feature+- ...+```++**5. Git commit كنقطة فحص.** بعد اكتمال التهيئة، commit نقطة فحص نظيفة. كل العمل اللاحق يبدأ من هذه النقطة.++**استراتيجية البدء الدافئ**: لا تبدأ من دليل فارغ. استخدم قالب مشروع (create-react-app، fastapi-template، إلخ) لإعداد هيكل أدلة قياسي، وتكوين تبعيات، وإطار اختبار مسبقًا. اخبز خطوات التهيئة الشائعة في القالب، واترك فقط عمل التهيئة الخاص بالمشروع. مثل بدء العمل في موقع به مياه جارية وكهرباء — أفضل ب ten thousand مرة من البدء من أرض قاحلة.++**معايير اكتمال التهيئة**: ليس "كم كود كُتب"، بل هل شروط عقد الإقلاع الأربعة محققة — يمكن البدء، يمكن الاختبار، يمكن رؤية التقدم، يمكن استئناف الخطوات التالية. استخدم قائمة الفحص هذه للتحقق من التهيئة:++```markdown+## Initialization Acceptance Checklist+- [ ] `make setup` succeeds from scratch+- [ ] `make test` has at least one passing test+- [ ] A new agent session can answer "how to run" and "how to test" from repo contents alone+- [ ] Task breakdown file exists with at least 3 tasks+- [ ] Everything committed to git+```++## مثال من الواقع++أسلوبا تهيئة لمشروع واجهة أمامية بـ React:++**الأسلوب المختلط (صب الأساس ورفع الجدران في وقت واحد)**: الوكيل أنشأ هيكل المشروع ونفّذ الميزة الأولى في وقت واحد في الجلسة 1. عند نهاية الجلسة، المستودع يحتوي على كود قابل للتشغيل لكن: بدون توثيق صريح لأوامر البدء/الاختبار، وبدون ملف تتبع تقدم، وبدون تقسيم مهام. الجلسة 2 قضت ~20 دقيقة في استنتاج هيكل المشروع وإطار الاختبار وعملية البناء — مثل طاقم بناء جديد يصل إلى موقع، لا يعرف مدى تقدم الأساس أو أين مسارات السباكة، يضطر لحفر ثقوب واحدة تلو الأخرى للاكتشاف.++**التهيئة المخصصة (الأساس أولًا)**: الجلسة 1 أنجزت التهيئة فقط — أنشأت هيكل الأدلة من قالب، وضبطت إطار الاختبار (Vitest + React Testing Library)، وكتبت وتحققت من اختبار مثال واحد، وأنشأت مستند عقد الإقلاع وملف تقسيم المهام، وcommit نقطة فحص أولية. وقت إعادة بناء الجلسة 2 كان أقل من 3 دقائق، وبدأت العمل مباشرة من قائمة المهام — الطاقم يصل، يلقي نظرة على المخطط، ويعرف بالضبط من أين يستأنف.++مقارنة دورة المشروع الكاملة: إجمالي وقت إعادة البناء (عبر كل الجلسات) للأسلوب المختلط كان ~60% أكثر من أسلوب التهيئة المخصصة. الـ 20 دقيقة الإضافية المُنفقة على التهيئة استُردت مرات عديدة في الجلسات اللاحقة. مثل الأساس المتين الذي يجعل الجدران ترتفع أسرع — البطيء سريع.++## الخلاصات الأساسية++- التهيئة والتنفيذ لهما أهداف تحسين مختلفة — خلطهما يسحب كليهما للأسفل. صب الأساس أولًا، ثم ابنِ الجدران.+- مخرجات التهيئة ليست كودًا، بل بنية تحتية: بيئة قابلة للتشغيل، اختبارات قابلة للتحقق، عقد إقلاع، تقسيم مهام.+- تحقق من التهيئة بشروط عقد الإقلاع الأربعة: يمكن البدء، يمكن الاختبار، يمكن رؤية التقدم، يمكن استئناف الخطوات التالية.+- البدء الدافئ يتفوق على البدء البارد. استخدم قوالب المشاريع لإعداد بنية تحتية قياسية مسبقًا.+- الوقت المستثمر في التهيئة يُسترد بالكامل في الجلسات الـ 3-4 التالية. هذا ليس تكلفة إضافية — بل استثمار مسبق. كلما كان الأساس أصلب، ارتفع المبنى أسرع.++## قراءات إضافية++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)++## تمارين++1. **تصميم عقد الإقلاع**: اكتب عقد إقلاع كامل لمشروع تعمل على تطويره. ثم افتح جلسة وكيل جديدة تمامًا، وأره فقط محتويات المستودع (بدون سياق شفهي)، واجعله يحاول بدء المشروع، وتشغيل الاختبارات، وفهم التقدم الحالي. سجّل كل مشكلة يواجهها — كل واحدة تقابل بندًا مفقودًا في عقد الإقلاع الخاص بك.++2. **تجربة مقارنة**: اختر مشروعًا جديدًا متوسط التعقيد. الأسلوب A: دع الوكيل يُهيئ وينفذ أول تنفيذ في وقت واحد. الأسلوب B: اقضِ جلسة واحدة في التهيئة المخصصة، وابدأ التنفيذ في الجلسة 2. بعد 4 جلسات، قارن: الوقت حتى أول تحقق، وتكلفة إعادة البناء، ومعدل إكمال الميزات.++3. **قائمة فحص قبول التهيئة**: صمّم قائمة فحص قبول تهيئة لمشروعك. اجعل جلسة وكيل جديدة تنفذ كل بند في قائمة الفحص وسجّل أيها ينجح وأيها يفشل. البنود الفاشلة هي حيث يحتاج harness الخاص بك إلى تقوية.diff --git a/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdnew file mode 100644index 0000000..7ee37d6--- /dev/null+++ b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 07++استخدم هذا المجلد لأمثلة عن:++- إخفاقات التنفيذ الواحد+- prompts مهام كبيرة الحجم+- تشكيل المهام التدريجي+- أسطح الميزات المنظمةdiff --git a/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.mdnew file mode 100644index 0000000..b0f9ccf--- /dev/null+++ b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md@@ -0,0 +1,6 @@+# قالب المهمة التالية++- الميزة ذات الأولوية القصوى الحالية:+- لماذا هذه الميزة هي التالية:+- ما الذي يُعتبر ناجحًا:+- ما الذي يجب عدم تغييره خلال هذه الخطوة:diff --git a/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdnew file mode 100644index 0000000..cd5916d--- /dev/null+++ b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -0,0 +1,17 @@+# مثال على سطح النطاق++المهمة:++- إضافة الفهرسة إلى تطبيق المعرفة Electron++شكل نطاق سيء:++- "تنفيذ الفهرسة"++شكل نطاق أفضل:++- تحليل المستندات المستوردة+- تقسيم المستندات إلى أجزاء+- حفظ بيانات الأجزاء الوصفية+- عرض حالة الفهرسة في واجهة المستخدم+- إضافة إجراء إعادة الفهرسةdiff --git a/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.tsnew file mode 100644index 0000000..c587a1d--- /dev/null+++ b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts@@ -0,0 +1,151 @@+/**+ * scope-tracker.ts+ *+ * Reads a feature list and a change log. Enforces single-active-feature+ * policy. Given a log of changes, flags any changes outside the active+ * feature scope. Demonstrates how scope drift happens and how the tracker+ * catches it.+ *+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Feature {+ id: string;+ name: string;+ status: "active" | "pending" | "done";+}++interface ChangeLogEntry {+ step: number;+ file: string;+ description: string;+ featureId: string; // The feature this change claims to belong to+}++// ---------------------------------------------------------------------------+// Sample data+// ---------------------------------------------------------------------------++const features: Feature[] = [+ { id: "F-001", name: "Search endpoint", status: "active" },+ { id: "F-002", name: "Delete endpoint", status: "pending" },+ { id: "F-003", name: "Rate limiting", status: "pending" },+ { id: "F-004", name: "User dashboard", status: "pending" },+];++// A realistic change log where the agent gradually drifts from the active feature+const changeLog: ChangeLogEntry[] = [+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },+];++// ---------------------------------------------------------------------------+// Scope tracker+// ---------------------------------------------------------------------------++interface ScopeCheckResult {+ step: number;+ file: string;+ description: string;+ featureId: string;+ inScope: boolean;+ activeFeature: string;+}++function trackScope(+ featureList: Feature[],+ changes: ChangeLogEntry[]+): ScopeCheckResult[] {+ const activeFeatures = featureList.filter((f) => f.status === "active");+ const activeIds = new Set(activeFeatures.map((f) => f.id));+ const activeNames = activeFeatures.map((f) => f.name).join(", ");++ return changes.map((change) => ({+ step: change.step,+ file: change.file,+ description: change.description,+ featureId: change.featureId,+ inScope: activeIds.has(change.featureId),+ activeFeature: activeNames,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const results = trackScope(features, changeLog);++ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");+ console.log("=".repeat(100));++ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));++ // Detailed change log+ console.log("\n" + "-".repeat(100));+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;+ console.log(header);+ console.log(sep);++ let inScopeCount = 0;+ let driftCount = 0;++ for (const r of results) {+ const scopeLabel = r.inScope ? "OK" : "DRIFT";+ if (r.inScope) inScopeCount++;+ else driftCount++;++ const marker = r.inScope ? " " : ">>";+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE DRIFT SUMMARY");+ console.log("=".repeat(100) + "\n");++ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;+ console.log(sHeader);+ console.log(sSep);+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);++ // Drift detail+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];+ if (driftFeatures.length > 0) {+ console.log("\n DRIFTED FEATURES:");+ for (const fid of driftFeatures) {+ const feat = features.find((f) => f.id === fid);+ const driftChanges = results.filter((r) => r.featureId === fid);+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);+ }+ }++ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");+}++run();diff --git a/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdnew file mode 100644index 0000000..c00c9f1--- /dev/null+++ b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -0,0 +1,134 @@+[中文版本 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)+> مشروع عملي: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)++# المحاضرة 07. ارسم حدود مهمة واضحة للوكلاء++تطلب من Claude Code "إضافة مصادقة المستخدم إلى هذا المشروع"، فيبدأ بتعديل مخطط قاعدة البيانات، وكتابة المسارات، وتغيير مكونات الواجهة الأمامية، و — أثناء وجوده في ذلك — إعادة هيكلة middleware معالجة الأخطاء. بعد ساعتين تتفقد: 12 ملفًا معدّلًا، 800 سطر كود جديد، ولا ميزة واحدة تعمل من البداية للنهاية.++العض أكثر مما تستطيع مضغه — هذا القول ينطبق على وكلاء الذكاء الاصطناعي بشكل خاص. الوكلاء يولدون بدافع "فعل القليل الإضافي" — يرون أشياء مرتبطة فيتعاملون معها في الطريق، مثل شخص يذهب إلى السوبرماركت لزجاجة صلصة صويا ويخرج يدفع عربة كاملة. المشكلة هي أن البشر الذين يشترون أكثر مما ينب مضيعون للمال فقط؛ الوكلاء الذين يفعلون أشياء كثيرة في وقت واحد يعني أنه لا شيء يُنجز بشكل صحيح.++مقال مدونة Anthropic الهندسية "Effective harnesses for long-running agents" يوضح: عندما تكون prompts واسعة جدًا، يميل الوكلاء إلى "بدء أشياء متعددة في وقت واحد" بدلاً من "إنهاء شيء واحد أولًا." ممارسات OpenAI الهندسية لـ Codex وجدت نفس الشيء — المهام بدون ضوابط نطاق صريحة تشهد انهيارًا في معدلات الإكمال. هذه ليست مشكلة نموذج — إنها مشكلة harness. أنت لم ترسم الحدود.++## الانتباه مورد محدود++هذه ليست استعارة — إنها رياضيات. افترض أن سعة سياق الوكيل هي C ويُنشط k مهمة في وقت واحد. كل مهمة تحصل على متوسط C/k من موارد الاستدلال. عندما ينخفض C/k تحت الحد الأدنى المطلوب لإكمال مهمة واحدة، لا شيء يُنجز. معدتك بحجم محدد فقط — ضع عشر فطائر في وقت واحد ولن تهضمها جميعًا، بل ستحصل على عشر حالات عسر هضم.++السلوك الفعلي لـ Claude Code يوضح. اطلب منه "إضافة تسجيل مستخدم" وقد:++1. ينشئ نموذج User+2. يكتب مسار التسجيل+3. يلاحظ أنه يحتاج تحقق بريد إلكتروني، فيضيف خدمة بريد+4. يرى أن كلمات المرور تحتاج تجزئة، فيجلب bcrypt+5. يلاحظ أن معالجة الأخطاء غير متسقة، فيُعيد هيكلة middleware الأخطاء العام+6. يرى أن هيكل ملف الاختبار فوضوي، فيُعيد تنظيم الدليل++بعد ست خطوات، كل واحدة نصف مكتملة. بدون تحقق شامل، وارتباط معقد بين الكود غير المكتمل، والجلسة التالية التي ستلتقط القطع ستكون ضائعة تمامًا. مثل شخص يطبخ ستة أطباق في وقت واحد — كل طبق في المقلاة لكن لم يُقدم أي منها. جميعها تحترق.++البيانات التجريبية من Anthropic تدعم هذا مباشرة: الوكلاء الذين يستخدمون استراتيجية "الخطوة التالية الصغيرة" (ما يعادل WIP=1) يُظهرون معدل إكمال مهام أعلى بنسبة 37% من الوكلاء الذين يستخدمون prompts واسعة. والأكثر إثارة للاهتمام، أن عدد أسطر الكود التي يُنتجها الوكلاء مرتبط ارتباطًا سلبيًا ضعيفًا مع إكمال الميزات الفعلي — كود أكثر مكتوب، ميزات أقل مُنجزة. العض أكثر مما تستطيع مضغه، مُثبت بالبيانات.++## سير عمل WIP=1++```mermaid+flowchart LR+ Queue["Feature queue"] --> Pick["Pick exactly one task"]+ Pick --> Active["Only one active item"]+ Active --> Verify["Run end-to-end verification"]+ Verify -->|pass| Commit["Commit and unlock next task"]+ Verify -->|fail| Active+ Commit --> Queue+```++```mermaid+flowchart TB+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]+ Budget --> Many["WIP = 5<br/>C / 5 per task"]++ One --> Finish["One feature reaches passing state"]+ Many --> Partial["Five partial implementations"]+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]+```++## المفاهيم الأساسية++- **التجاوز (Overreach)**: الوكيل يُنشط مهامًا أكثر من المثالي في جلسة واحدة. إنه قابل للقياس — فعل 5 ميزات مع 0 نجحت شاملة هو تجاوز.+- **عدم الإكمال (Under-finish)**: نسبة المهام التي تجتاز التحقق الشامل، من إجمالي المهام المُنشطة، تنخفض عن الحد. كود مكتوب لكن اختبارات لا تنجح هو عدم إكمال.+- **حد WIP (حد العمل الجاري)**: من منهجية Kanban. الفكرة الأساسية: حدد عدد المهام الجارية في وقت واحد. للوكلاء، WIP=1 هو الإعداد الافتراضي الأكثر أمانًا — أنهِ واحدة قبل بدء التالية. مثل بوفيه — لا تُكدّس طبقك، أنهِ طبقًا ثم عد للطبق التالي.+- **دليل الإكمال**: الشرط القابل للتحقق الذي يجب أن تلبيه المهمة للانتقال من "قيد التنفيذ" إلى "مكتملة." بدون هذا، يستبدل الوكلاء "الكود يبدو جيدًا" بـ "السلوك يجتاز الاختبارات."+- **سطح النطاق**: هيكل DAG حيث كل عقدة هي وحدة عمل والحواف هي التبعيات. الحالات محدودة بأربعة: not_started، active، blocked، passing.+- **ضغط الإكمال**: القوة المقيدة التي يمارسها harness من خلال حدود WIP ومتطلبات دليل الإكمال، مُجبرًا الوكيل على إنهاء المهمة الحالية قبل بدء مهمة جديدة.++## التجاوز وعدم الإكمال متعايشان++هاتان المشكلتان ليستا مستقلتين — تُضخّم كل منهما الأخرى. التجاوز يُخفّف الانتباه، والانتباه المُخفّض يسبب عدم الإكمال، والكود نصف المكتوب المتبقي يزيد من تعقيد النظام، مما يزيد من دفع التجاوز في المهمة التالية. حلقة مفرغة.++بلغة Kanban: قانون ليتل يخبرنا أن L = lambda * W. إذا كان العمل الجاري L مرتفعًا جدًا (فعل أشياء كثيرة في وقت واحد)، فإن زمن التسليم W لكل مهمة يزداد حتمًا. للوكلاء، هذا يعني أن كل ميزة تستغرق وقتًا أطول من البداية حتى الإكمال المُتحقَق، واحتمالية الفشل تنمو.++هذه مشكلة قديمة في عالم البشر أيضًا — وثّق Steve McConnell في *Rapid Development* أن زحف النطاق هو السبب الرئيس لفشل المشاريع. لكن البشر لديهم على الأقل حدس "لقد أنجزت ما يكفي." الوكلاء ليس لديهم شيء. توليد الفكرة التالية يكلف النموذج تقريبًا صفر tokens إضافية — كتابة "دعني أصلح هذا أيضًا وأنا هنا" بالكاد يُسجَّل — لكن كل تعديل إضافي يُخفّف انتباه الوكيل. مثل بوفيه كل طبق إضافي فيه تكلفة حدية قريبة من الصفر، لكن معدتك بسعة محدودة.++## كيف تفعل ذلك بشكل صحيح++### 1. فرض WIP=1++هذه هي الطريقة الأكثر مباشرة وفعالية. في harness الخاص بك، أخبر الوكيل صراحةً: **مهمة واحدة فقط مسموح بها في حالة "active" في أي وقت.** في `CLAUDE.md` الخاص بـ Claude Code أو `AGENTS.md` الخاص بـ Codex، اكتب:++```+## Work Rules+- Work on one feature at a time+- Only start the next feature after the current one passes end-to-end verification+- Don't "also refactor" feature B while implementing feature A+```++مثل الأكل في بوفيه — طبق واحد في كل مرة، أنهِه قبل العود للمزيد.++### 2. حدد دليل إكمال صريح لكل مهمة++الإنجاز ليس "الكود مكتوب" — بل "التحقق من السلوك ناجح." في قائمة الميزات الخاصة بك، كل إدخال يحتاج أمر تحقق:++```+F01: User Registration+ Verification: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201+ State: passing+```++### 3. أخرج سطح النطاق إلى ملف خارجي++استخدم ملفًا قابلًا للقراءة آليًا (JSON أو Markdown) لتسجيل حالات كل المهام. أي جلسة جديدة يمكنها قراءة هذا الملف والمعرفة فورًا: أي مهمة نشطة؟ ما السلوك الذي يُحسب كمنجز؟ أي عمليات تحقق نجحت؟++### 4. راقب معدل الإكمال المُتحقَق++يجب على harness تتبع VCR (معدل الإكمال المُتحقَق) = مهام مُتحقَقة / مهام مُنشطة باستمرار. احظر تنشيط مهام جديدة عندما يكون VCR < 1.0.++## حالة من الواقع++مشروع REST API مع 8 ميزات، استراتيجيتان مقارنتان:++**وضع البوفيه (غير مقيد)**: الوكيل يُنشط 5 ميزات في وقت واحد في الجلسة 1. يُنتج ~800 سطر عبر 12 ملفًا. معدل نجاح اختبار شامل: 20% — فقط تسجيل المستخدم يعمل. الميزات الأربع الأخرى: مخطط قاعدة بيانات مُنشأ لكن ينقصه منطق التحقق، مسارات محددة لكنها تُعيد تنسيقات استجابة خاطئة. مثل شخص يطبخ ستة أطباق في وقت واحد، واحد فقط بالكاد صالح للأكل. بنهاية الجلسة 3، فقط 3 من 8 ميزات مكتملة.++**وضع الطبق الواحد (WIP=1)**: الوكيل يعمل على تسجيل المستخدم فقط في الجلسة 1. يُنتج ~200 سطر عبر 4 ملفات. اختبارات شاملة: 100% ناجحة. يُنفذ commit لتطبيق نظيف ومُتحقَق. بنهاية الجلسة 4، 7 من 8 ميزات مكتملة (الثامنة محجوبة بتبعية خارجية).++النتيجة: كود إجمالي أقل (800 مقابل 1200 سطر) لكن كود أكثر فعالية. معدل الإكمال: 87.5% مقابل 37.5%. خذ قضمة واحدة في كل مرة، وتأكل فعليًا أكثر.++## الخلاصات الأساسية++- **WIP=1 هو الإعداد الافتراضي الآمن لـ harness الوكلاء** — أنهِ واحدة، ثم ابدأ التالية؛ لا تحاول التوازي. لا يمكنك أن تسمن في قضمة واحدة.+- **دليل الإكمال يجب أن يكون قابلًا للتنفيذ** — "الكود يبدو جيدًا" لا يُحسب؛ "curl يُعيد 201" نعم.+- **سطح النطاق يجب أن يُخرَج كملف** — ليس فقط مذكورًا في المحادثة، بل مسجّلًا بتنسيق قابل للقراءة آليًا في المستودع.+- **التجاوز وعدم الإكمال متعايشان** — حل أحدهما يحل الآخر.+- **"افعل أقل لكن أنهِ" دائمًا يتفوق على "افعل أكثر لكن اترك نصفه غير مكتمل"** — أسطر كود الوكيل ومعدل إكمال الميزات مرتبطان سلبيًا. الجودة دائمًا تتفوق على الكمية.++## قراءات إضافية++- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — مدونة Anthropic الهندسية، مناقشة تفصيلية لاستراتيجية "الخطوة التالية الصغيرة"+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — المعالجة الكاملة لـ OpenAI لهندسة harness+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — المصدر الكلاسيكي حول حدود WIP+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — بيانات تجريبية حول زحف النطاق بصفته السبب الرئيس لفشل المشاريع++## تمارين++1. **تنوي المهام**: اختر متطلبًا واسعًا (مثلًا، "نفّذ نظام إدارة مستخدمين") وقسّمه إلى 5 وحدات عمل ذرية على الأقل. لكل وحدة، حدد: (a) وصف سلوك واحد، (b) أمر تحقق قابل للتنفيذ، (c) التبعيات. تحقق مما إذا كان التحلل يلبي قيد WIP=1.++2. **تجربة مقارنة**: شغّل نفس المشروع مرتين — مرة بدون قيود، ومرة مع WIP=1 مفروض. قارن: معدل الإكمال المُتحقَق، وإجمالي أسطر الكود، ونسبة الكود الفعال.++3. **تدقيق دليل الإكمال**: راجع مخرجات تشغيل وكيل حديث، وصنّف كل تغيير كود بصفته "سلوك مكتمل،" أو "سلوك غير مكتمل،" أو "هيكل أولي." أضف أوامر تحقق مفقودة لكل سلوك غير مكتمل.diff --git a/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..52d6a2b--- /dev/null+++ b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,218 @@+/**+ * feature-list-validator.ts+ *+ * Reads a feature_list.json, validates its schema, and checks for features+ * marked "pass" without verification evidence. Outputs a structured report.+ * Can run against any project directory that has a feature_list.json.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]+ * (defaults to the directory containing this script)+ *+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Allow unknown fields for flexibility+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Schema validation+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entry ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Missing or invalid 'id' field`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Missing or invalid 'category' field`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Missing or invalid 'description' field`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' must be an array if present`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' must be a boolean if present`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Evidence validation+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Process feature list+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve target directory+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);+ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" FEATURE LIST VALIDATOR");+ console.log("=".repeat(90));+ console.log(` Reading: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(` ERROR: feature_list.json not found at ${filePath}`);+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");+ process.exit(1);+ }++ let entries: FeatureEntry[];+ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");+ process.exit(1);+ }++ // For demo purposes, also validate an extended test set+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "User can import a PDF document.",+ verification: ["Upload a PDF file", "Verify it appears in the document list"],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "System hallucination rate is below 5%.",+ verification: [], // Empty -- no evidence+ passes: true, // Marked as pass WITHOUT evidence+ },+ {+ id: "missing-fields",+ // Missing 'category' and 'description'+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Print report+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";+ const notes = r.markedPassWithoutEvidence+ ? "FLAGGED: passes without evidence!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";+ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`+ );+ }++ // Summary+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;+ const withEvidence = results.filter((r) => r.hasVerification).length;++ console.log("\n" + "-".repeat(90));+ console.log(" SUMMARY");+ console.log("-".repeat(90));+ console.log(` Total features: ${total}`);+ console.log(` Schema valid: ${schemaOk}/${total}`);+ console.log(` Marked as passing: ${passing}/${total}`);+ console.log(` With verification evidence: ${withEvidence}/${total}`);+ console.log(` Flagged (pass without evidence): ${flagged}`);++ if (flagged > 0) {+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);+ console.log(" These features need verification before they can be trusted.\n");+ } else {+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");+ }+}++run();diff --git a/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..8b973e3--- /dev/null+++ b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",+ "verification": [+ "Import a markdown document",+ "Open the Q&A panel",+ "Ask a question about known content",+ "Verify the answer is returned",+ "Verify one or more citations are displayed"+ ],+ "passes": false+ }+]diff --git a/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdnew file mode 100644index 0000000..a1641a6--- /dev/null+++ b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 08++استخدم هذا المجلد لأمثلة عن:++- بوابات حالة النجاح (pass-state gating)+- التحقق من البداية للنهاية+- معايير إكمال ضعيفة مقابل قوية+- أمثلة حلقة التقييمdiff --git a/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdnew file mode 100644index 0000000..cdd0830--- /dev/null+++ b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -0,0 +1,8 @@+# سياسة بوابة النجاح++لا يمكن للميزة الانتقال من `passes: false` إلى `passes: true` إلا عندما:++- يكون سير العمل المتوقع قد تم تنفيذه+- يكون دليل النجاح مسجلاً+- لا يوجد خطأ حاظر في المسار المختبر+- التنفيذ لا يترك التطبيق في حالة معطلة أو غامضةdiff --git a/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdnew file mode 100644index 0000000..77aadad--- /dev/null+++ b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -0,0 +1,137 @@+[中文版本 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> مشروع عملي: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)++# المحاضرة 08. استخدم قوائم الميزات لتقييد الوكيل++تطلب من agent بناء موقع تجارة إلكترونية. بعد أن ينتهي، يخبرك "انتهيت". تنظر إلى الكود — مصادقة المستخدم تعمل، لكن زر الدفع في سلة التسوق لا يفعل شيئًا، وتدفق الدفع غير متصل على الإطلاق. المشكلة: لم تخبره أبدًا ما يعنيه "انتهيت"، لذا استخدم معياره الخاص — "كتبت الكثير من الكود ويبدو مكتملًا إلى حد ما."++قوائم الميزات، في نظر الكثير من الناس، هي مجرد مذكرة — اكتب الأشياء حتى لا تنساها، ثم ألقِها جانبًا. لكن في عالم harness، قائمة الميزات ليست مذكرة للبشر — إنها العمود الفقري لـ harness بالكامل. يعتمد المجدول عليها لاختيار المهام، ويعتمد المدقق عليها للحكم على الاكتمال، ويعتمد مُعدّ التسليم عليها لإنشاء الملخصات. اكسر العمود الفقري والجسم كله يشل.++تشدد كل من Anthropic و OpenAI: **يجب إخراج القطع الأثرية (artifacts) إلى الخارج.** يجب أن تعيش حالة الميزة في ملف قابل للقراءة آليًا في المستودع، وليس في نص محادثة غير منظم.++## الوكلاء لا يعرفون ما يعنيه "انتهيت"++لا يعرف Claude Code ولا Codex تلقائيًا ما تقصده بـ "انتهيت". تقول "أضف ميزة سلة تسوق"، وقد يكون تفسير النموذج "اكتب مكوّن Cart ودالة addToCart." لكنك كنت تقصد "يمكن للمستخدم تصفح المنتجات وإضافتها إلى السلة وإتمام الشراء من البداية إلى النهاية." تستمر هذه الفجوة في الفهم بدون قائمة ميزات. يستخدم agent معياره الضمني الخاص — عادةً "الكود ليس به أخطاء بناء جملة واضحة." ما تحتاجه هو تحقق سلوكي شامل. مثلما تطلب من صديق أن يشتري لك فاكهة — تقول "احضر بعض الفاكهة" فيعود بالليمون. فاكهته وفاكهتك ليستا نفس الفاكهة.++انظر إلى ملاحظة التقدم الشائعة هذه:++```+Did user auth, shopping cart mostly done, still need payments+```+هل يمكن لجلسة agent جديدة الإجابة على هذه الأسئلة من هذه الملاحظة؟ ماذا يعني "مكتملة إلى حد كبير"؟ أي اختبارات اجتازتها السلة؟ ما الذي يعيق المدفوعات؟ الإجابة على الكل هي "لا أحد يعرف." مثلما تخبر طبيبك "معدتي تؤلمني، كنت بخير مؤخرًا" — أي دواء يمكنه وصفه؟++النتيجة: تقضي الجلسة الجديدة 20 دقيقة في استنتاج حالة المشروع، وقد تعيد تنفيذ الميزات المكتملة. تُظهر بيانات هندسة Anthropic أن سجلات التقدم الجيدة تقلل وقت تشخيص بدء الجلسة بنسبة 60-80%.++## آلة حالة الميزات++```mermaid+flowchart LR+ Feature["One feature row"] --> Behavior["Behavior<br/>for example: POST /cart/items returns 201"]+ Feature --> Check["Verification command<br/>the exact check to run"]+ Feature --> State["State<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["Only with all three fields<br/>is the feature row usable"]+ Check --> Complete+ State --> Complete+```++```mermaid+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["Pick the next not_started item"]+ Scheduler --> Agent["Agent works on that one item"]+ Agent --> Verifier["Run that item's verification command"]+ Verifier -->|pass| Passing["Mark it passing<br/>and write the evidence"]+ Verifier -->|fail| Active["Keep it active"]+ Verifier -->|dependency issue| Blocked["Mark it blocked"]+ Passing --> Handoff["Update handoff note<br/>and current progress"]+ Active --> Agent+```++## المفاهيم الأساسية++- **قوائم الميزات هي عناصر بدائية في harness**: ليست "أدوات تخطيط اختيارية"، بل هي هياكل بيانات أساسية تعتمد عليها جميع مكونات harness الأخرى. مثل هياكل جداول قاعدة البيانات — لا يمكنك أن تقول "لن نتخطى المفاتيح الأساسية."+- **البنية الثلاثية**: كل عنصر ميزة هو ثلاثية `(وصف السلوك، أمر التحقق، الحالة الحالية)`. غياب أي عنصر يجعل العنصر غير مكتمل.+- **نموذج آلة الحالة**: لكل عنصر ميزة أربع حالات — `not_started`، `active`، `blocked`، `passing`. تُ controlled انتقالات الحالة بواسطة harness، وليست قابلة للتغيير بحرية من agent.+- **بوابة حالة الاجتياز**: الطريقة الوحيدة لانتقال ميزة من `active` إلى `passing` هي تنفيذ أمر التحقق بنجاح. هذا لا رجعة فيه — بمجرد أن يصبح `passing`، لا يمكنه العودة. مثل اجتياز امتحان يعني أنك اجتزته، لا يمكنك تغيير الدرجة بأثر رجعي.+- **مصدر حقيقة واحد**: يجب أن تُستمد جميع المعلومات حول "ما يجب فعله" من قائمة ميزات واحدة. لا تناقضات بين قائمة الميزات وسجل المحادثة.+- **الضغط العكسي**: عدد الميزات التي لم تجتز بعد هو الضغط الذي يمارسه harness على agent. ضغط صفري = المشروع مكتمل.++## لماذا يجب أن تكون قوائم الميزات "عناصر بدائية"++المستندات للبشر ليقرأوها؛ العناصر البدائية للأنظمة لتنفذها. يمكن تجاهل المستندات؛ لا يمكن تجاوز العناصر البدائية.++فكر في الأمر مثل قيود مشغلات قاعدة البيانات مقابل عمليات التحقق في طبقة التطبيق: الأولى تُفرض بواسطة محرك قاعدة البيانات، لا يمكن لأي SQL تخطيها؛ الثانية تعتمد على صحة كود التطبيق ويمكن تجاوزها عن طريق الخطأ. قوائم الميزات كعناصر بدائية في harness — تحديدًا، تخدم قائمة الميزات أربعة مكونات من harness:++1. **المجدول**: يقرأ الحالات، يختار ميزة `not_started` التالية. مثل نظام تخطيط الإنتاج في المصنع.+2. **المدقق**: ينفذ أوامر التحقق، يقرر ما إذا كان سيسمح بانتقالات الحالة. مثل فحص الجودة.+3. **مُعدّ التسليم**: ينشئ تلقائيًا ملخصات تسليم الجلسة من قائمة الميزات. مثل تقرير تغيير الوردية التلقائي.+4. **متتبع التقدم**: يحصي توزيع الحالات، يوفر مقاييس صحة المشروع. مثل لوحة المعلومات.++## كيف تفعل ذلك بشكل صحيح++### 1. حدد تنسيق قائمة ميزات بسيط++لا تحتاج إلى نظام معقد — ملف Markdown أو JSON منظم يكفي. المفتاح هو أن كل إدخال يجب أن يمتلك الثلاثية:++```json+{+ "id": "F03",+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",+ "state": "passing",+ "evidence": "commit abc123, test output log"+}+```++### 2. دع harness يتحكم في انتقالات الحالة++لا يمكن لـ agent تغيير حالة ميزة مباشرة إلى `passing`. يمكنه فقط تقديم طلب تحقق؛ ينفذ harness أمر التحقق ويقرر ما إذا كان سيسمح بالانتقال. هذه هي "بوابة حالة الاجتياز."++### 3. اكتب القواعد في CLAUDE.md++```+## Feature List Rules+- Feature list file: /docs/features.md+- Only one feature active at a time+- Verification command must pass before marking as passing+- Don't modify feature list states yourself — the verification script updates them automatically+```++### 4. معايرة الدقة++يجب أن يكون نطاق كل عنصر ميزة "قابل للإنجاز في جلسة واحدة." واسع جدًا ولن ينتهي؛ ضيق جدًا وتزداد تكلفة الإدارة. "يمكن للمستخدم إضافة عناصر إلى السلة" دقة جيدة. "تنفيذ سلة التسوق" واسع جدًا. "إنشاء حقل الاسم في نموذج Cart" ضيق جدًا. مثل تقطيع شريحة لحم — ليس القطعة كاملة، وليست لحماً مفروماً.++## حالة من العالم الحقيقي++منصة تجارة إلكترونية مع 10 ميزات. مقارنة نهجي تتبع:++**وضع المذكرة**: يستخدم agent ملاحظات غير منظمة. بعد 3 جلسات، تصبح الملاحظات "تمت مصادقة المستخدم وقائمة المنتجات، سلة التسوق مكتملة إلى حد كبير لكن بها أخطاء، المدفوعات لم تبدأ." تحتاج الجلسة الجديدة إلى 20 دقيقة لاستنتاج الحالة، وتعيد تنفيذ الميزات المكتملة في النهاية. مثل قائمة تسوقك التي تقول "حليب، خبز، وذلك الشيء" — في المتجر، ما زلت لا تعرف ماذا تشتري.++**وضع العمود الفقري**: كل ميزة لها حالة واضحة وأمر تحقق. تقرأ الجلسة الجديدة قائمة الميزات وتعرف في 3 دقائق: F01-F05 `passing`، F06 `active`، F07-F10 `not_started`. تستأنف من F06 مباشرة، صيانة صفرية.++النتيجة المُقاسة: تُظهر المشاريع التي تستخدم قوائم ميزات منظمة معدل إنجاز ميزات أعلى بنسبة 45% من التتبع الحر، مع صفر عمليات تنفيذ مكررة.++## الخلاصات الأساسية++- **قوائم الميزات هي العمود الفقري لـ harness**، وليست مذكرات للبشر. المجدول والمدقق ومُعدّ التسليم يعتمدون عليها جميعًا.+- **كل عنصر ميزة يجب أن يمتلك الثلاثية**: وصف السلوك + أمر التحقق + الحالة الحالية. غياب عنصر واحد يجعله غير مكتمل — مثل كرسي بثلاث أرجل ينقصه ساق.+- **انتقالات الحالة يتحكم فيها harness** — لا يمكن لـ agent تغيير الحالات بمفرده. اجتياز التحقق = مسار الترقية الوحيد.+- **قائمة الميزات هي مصدر الحقيقة الوحيد للمشروع** — جميع معلومات "ماذا نفعل" تُستمد من قائمة واحدة.+- **عاير الدقة إلى "قابل للإنجاز في جلسة واحدة."**++## قراءات إضافية++- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — يحدد صراحةً قائمة الميزات باعتبارها "هيكل البيانات الأساسي" للتحكم في نطاق agent+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — يؤكد على مبدأ "إخراج القطع الأثرية إلى الخارج"+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — مبادئ تصميم العقود، الأساس النظري لقوائم الميزات+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — هرم الاختبار وممارسات هندسة المواصفات السلوكية++## تمارين++1. **تصميم قائمة الميزات**: حدد مخطط JSON بسيط لقائمة ميزات. يتضمن: المعرّف، وصف السلوك، أمر التحقق، الحالة الحالية، مرجع الدليل. استخدمه لوصف مشروع حقيقي مع 5 ميزات.++2. **مقارنة صرامة التحقق**: اختر 3 ميزات وصمم تحققًا "مرنًا" (مثلاً، "الكود ليس به أخطاء بناء جملة") وتحققًا "صارمًا" (مثلاً، "اختبار شامل يجتاز"). قارن معدل الإيجابيات الكاذبة تحت كل نهج.++3. **تدقيق مبدأ المصدر الوحيد**: راجع مشروع agent موجود وتحقق من معلومات النطاق التي تتعارض مع قائمة الميزات (متطلبات ضمنية في المحادثات، تعليقات TODO في الكود، إلخ). صمم خطة لتوحيد جميع المعلومات في قائمة الميزات.diff --git a/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.mdnew file mode 100644index 0000000..10b32f5--- /dev/null+++ b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md@@ -0,0 +1,6 @@+# قائمة فحص الحالة النظيفة++- التطبيق يبدأ بدون إصلاح يدوي+- التقدم الحالي مسجل+- لا توجد خطوة استيراد أو فهرسة ناقصة بدون توثيق+- الوكيل التالي يمكنه تشغيل مسار البدء والتحقق القياسي فورًاdiff --git a/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdnew file mode 100644index 0000000..5a460c2--- /dev/null+++ b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 09++استخدم هذا المجلد لأمثلة عن:++- السجلات كتغذية راجعة+- رؤية حالة التشغيل+- فحوصات الحالة النظيفة+- أمثلة الاستردادdiff --git a/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.tsnew file mode 100644index 0000000..fad1a3b--- /dev/null+++ b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts@@ -0,0 +1,241 @@+/**+ * victory-detector.ts+ *+ * Simulates an agent that claims task completion, then checks the claimed+ * state against actual verification. Outputs: claimed vs actual, highlighting+ * gaps between what the agent said and what's really true.+ *+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Task {+ name: string;+ claimedComplete: boolean;+ checks: VerificationCheck[];+}++interface VerificationCheck {+ description: string;+ claimed: boolean; // What the agent says+ actual: boolean; // What is actually true+ severity: "critical" | "warning";+}++// ---------------------------------------------------------------------------+// Simulated tasks with claimed vs actual states+// ---------------------------------------------------------------------------++const tasks: Task[] = [+ {+ name: "Add search endpoint",+ claimedComplete: true,+ checks: [+ {+ description: "Route handler exists",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Authentication middleware applied",+ claimed: true,+ actual: false, // Agent forgot auth+ severity: "critical",+ },+ {+ description: "Input validation added",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Unit tests written",+ claimed: true,+ actual: false, // Agent skipped tests+ severity: "critical",+ },+ {+ description: "Integration tests pass",+ claimed: true,+ actual: false, // No tests to run+ severity: "critical",+ },+ {+ description: "Documentation updated",+ claimed: true,+ actual: false, // Agent skipped docs+ severity: "warning",+ },+ ],+ },+ {+ name: "Fix pagination bug",+ claimedComplete: true,+ checks: [+ {+ description: "Bug reproduction case confirmed",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Root cause identified",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Fix applied",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Edge cases tested",+ claimed: true,+ actual: false, // Only happy path tested+ severity: "warning",+ },+ {+ description: "Regression tests added",+ claimed: true,+ actual: false,+ severity: "critical",+ },+ ],+ },+ {+ name: "Refactor auth module",+ claimedComplete: true,+ checks: [+ {+ description: "Old code removed",+ claimed: true,+ actual: false, // Old code still present+ severity: "warning",+ },+ {+ description: "All existing tests still pass",+ claimed: true,+ actual: false, // Two tests broke+ severity: "critical",+ },+ {+ description: "New auth flow works",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Migration guide written",+ claimed: true,+ actual: false,+ severity: "warning",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Verification+// ---------------------------------------------------------------------------++interface TaskVerification {+ taskName: string;+ claimedComplete: boolean;+ actuallyComplete: boolean;+ totalChecks: number;+ claimedPassing: number;+ actualPassing: number;+ gaps: { description: string; severity: string }[];+}++function verifyTask(task: Task): TaskVerification {+ const claimedPassing = task.checks.filter((c) => c.claimed).length;+ const actualPassing = task.checks.filter((c) => c.actual).length;+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);++ return {+ taskName: task.name,+ claimedComplete: task.claimedComplete,+ actuallyComplete: gaps.length === 0,+ totalChecks: task.checks.length,+ claimedPassing,+ actualPassing,+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");+ console.log("=".repeat(90));++ const verifications = tasks.map(verifyTask);++ for (const v of verifications) {+ console.log("\n Task: " + v.taskName);+ console.log(" " + "-".repeat(70));+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);++ if (!v.actuallyComplete) {+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);+ }++ // Detailed checks for this task+ const task = tasks.find((t) => t.name === v.taskName)!;+ console.log("\n Check detail:");+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;+ console.log(header);+ console.log(sep);++ for (const check of task.checks) {+ const claimedLabel = check.claimed ? "PASS" : "FAIL";+ const actualLabel = check.actual ? "PASS" : "FAIL";+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";+ const marker = gapLabel ? ">>" : " ";+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);+ }+ }++ // Overall summary+ console.log("\n" + "=".repeat(90));+ console.log(" OVERALL SUMMARY");+ console.log("=".repeat(90) + "\n");++ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;+ console.log(sHeader);+ console.log(sSep);++ for (const v of verifications) {+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);+ const cLabel = v.claimedComplete ? "Done" : "Pending";+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);+ }++ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;++ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");+ console.log(" Total undetected gaps: " + totalGaps);+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");+}++run();diff --git a/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdnew file mode 100644index 0000000..1920fcc--- /dev/null+++ b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -0,0 +1,145 @@+[中文版本 →](../../../zh/lectures/lecture-09-why-agents-declare-victory-too-early/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# المحاضرة 09. منع الوكلاء من إعلان النجاح مبكرًا++تطلب من agent تنفيذ ميزة "إعادة تعيين كلمة المرور". يُعدّل مخطط قاعدة البيانات، ويكتب نقطة نهاية API، ويضيف قالب البريد الإلكتروني، ويشغّل اختبارات الوحدة (جميعها تجتاز)، ثم يخبرك بثقة "انتهيت." عندما تحاول تشغيله فعليًا — لا يمكن إرسال رابط إعادة تعيين كلمة المرور (نقص إعدادات خدمة البريد)، تفشل عملية ترحيل قاعدة البيانات في منتصف الطريق (عدم اتساق المخطط)، ولم يتم تنفيذ التدفق الشامل ولو لمرة واحدة.++هذا الشعور لا ينبغي أن يكون غير مألوف — إنه مثل ملء ورقة الامتحان بالكامل، وأن تكون أول من يسلمها بثقة، فقط لترسب عند خروج الدرجات. مجرد أن الورقة ممتلئة لا يعني أن الإجابات صحيحة.++هذه ليست حادثة معزولة. أثبتت الورقة البحثية الكلاسيكية من ICML 2017 لـ Guo وآخرين: **الشبكات العصبية الحديثة مفرطة الثقة بشكل منهجي** — الثقة التي تُبلغ عنها النماذج أعلى بكثير من دقتها الفعلية. ينطبق الشيء نفسه على وكلاء البرمجة بالذكاء الاصطناعي: هم "يشعرون" أنهم انتهوا، لكن في الواقع، هم بعيدون عن ذلك. يجب أن يحل harness خاصتك محل "مشاعر" agent بتحقق خارجي قائم على التنفيذ.++## المنحدر الزلق++إعلانات الاكتمال المبكر تتبع دائمًا تقريبًا نفس النمط: الكود يبدو جيدًا — البنية صحيحة، المنطق يبدو معقولًا، والتحليل الثابت لا يظهر أخطاء واضحة. لكن harness لا يفرض تحققًا شاملاً قائمًا على التنفيذ، لذا يتخطى agent التشغيل الفعلي أو يشغّل اختبارات جزئية فقط. يشغّل اختبارات الوحدة لكن يتخطى اختبارات التكامل؛ يشغّل الاختبارات لكن لا يتحقق من التغطية. في النهاية، "الكود يبدو جيدًا" يُتخذ كدليل على أن "الميزة مكتملة." وتُسلم ورقة الامتحان.++تُفقد المعلومات في كل خطوة. من مواصفات المهام إلى تنفيذ الكود إلى السلوك وقت التشغيل، كل تحول يمكن أن يُدخل انحيازًا، وكل تحقق متخطع يزيد من تفاقم عدم تماثل المعلومات.++## فحص الإنهاء ثلاثي الطبقات++```mermaid+flowchart LR+ Claim["Agent says: done"] --> L1["First run<br/>lint / typecheck"]+ L1 --> L2["Then run<br/>tests and startup checks"]+ L2 --> L3["Finally run<br/>complete user flow"]+ L3 --> Done["Pass all three to be done"]+```++```mermaid+flowchart LR+ A["Code is written<br/>unit tests are green"] --> B["But app didn't really start<br/>full flow never ran"]+ B --> C["Config, DB, external service issues<br/>all remain hidden"]+ C --> D["So agent declares victory too early"]+```++## المفاهيم الأساسية++- **إعلان الاكتمال المبكر**: يؤكد agent أن المهمة مكتملة، لكن مواصفات الصحة غير المُستوفاة لا تزال قائمة. المشكلة الأساسية: يحكم agent بناءً على الثقة المحلية على مستوى الكود، بينما تتطلب الصحة على مستوى النظام تحققًا شاملاً.+- **انحياز معايرة الثقة**: الفجوة المنهجية بين الثقة المُبلغ عنها ذاتيًا من agent في الاكتمال وجودة الاكتمال الفعلية. للمهام المعقدة متعددة الملفات، هذا الانحياز إيجابي بشكل كبير — agent دائمًا أكثر ثقة مما يؤديه فعليًا. تمامًا مثل الطالب الذي يبالغ دائمًا في تقدير درجته بعد الامتحان.+- **معايير الإنهاء**: مجموعة واضحة وقابلة للتنفيذ من شروط الحكم مُعرّفة في harness. يجب أن يلبي agent جميع الشروط قبل إعلان الاكتمال. يتحول "انتهيت" من حكم ذاتي إلى تحديد موضوعي.+- **البوابة المزدوجة للتحقق والاعتماد**: طبقة التحقق الأولى تتحقق "هل نفّذ الكود السلوك المحدد بشكل صحيح"؛ طبقة الاعتماد الثانية تتحقق "هل يلبي السلوك على مستوى النظام المتطلبات الشاملة". كلتاهما يجب أن تجتاز ليُعتبر مكتملًا.+- **إشارات التغذية الراجعة وقت التشغيل**: السجلات وحالات العمليات وفحوصات الصحة من تنفيذ البرنامج. هذا هو الأساس الموضوعي لـ harness ليحكم على جودة الاكتمال.+- **قيد أولوية الاكتمال**: تحقق أولاً من الصحة الوظيفية، ثم تعامل مع الأداء، وأخيرًا عالج الأسلوب. يُمنع إعادة الهيكلة حتى يتم التحقق من الوظائف الأساسية.++## اجتياز اختبارات الوحدة ≠ المهمة مكتملة++هذا هو الفخ الأكثر شيوعًا، والأخطر. كتب agent الكود، شغّل اختبارات الوحدة، حصل على الأخضر كله، وقال "انتهيت." لكن فلسفة تصميم اختبارات الوحدة — عزل الوحدة قيد الاختبار ومحاكاة التبعيات — هي بالضبط ما يجعلها غير قادرة على اكتشاف مشاكل عبر المكونات:++**عدم تطابق الواجهة**: مسار الملف الذي يمرره عرض (render process) إلى preload script هو مسار نسبي، لكن preload script يتوقع مسارًا مطلقًا. اختبارات الوحدة الخاصة بكل منهما استخدمت محاكيات (mocks) واجتازت. لا تُكتشف المشكلة إلا خلال الاختبار الشامل. مثل كل موسيقي في فرقة يتدرب بشكل مثالي بمفرده، ليدركوا فقط أنهم في مفاتيح مختلفة عند العزف معًا.++**أخطاء انتشار الحالة**: ترحيل قاعدة بيانات يُغيّر مخطط الجدول، لكن طبقة تخزين ORM المؤقت لا تزال تحتفظ بمداخل مخزنة للمخطط القديم. توفر اختبارات الوحدة بيئة محاكاة جديدة في كل مرة، مما لن يكشف عدم اتساق الحالة هذا عبر الطبقات.++**اعتماد البيئة**: يتصرف الكود بشكل صحيح في بيئة الاختبار (حيث كل شيء مُحاكى) لكنه يفشل في البيئة الحقيقية بسبب اختلافات الإعدادات أو زمن استجابة الشبكة أو عدم توفر الخدمة. مثل الغناء بشكل مثالي في غرفة البروفة، لكن مواجهة مشاكل في المعدات الصوتية على المسرح.++### "إعادة الهيكلة أثناء ذلك" سُم ل حكم الاكتمال++لدى Claude Code نمط سلوكي شائع: يبدأ في إعادة هيكلة الكود وتحسين الأداء وتحسين الأسلوب قبل أن تجتاز الوظائف الأساسية التحقق. اقتباس Knuth، "التحسين المبكر هو جذر كل الشرور،" يأخذ معنى جديدًا في سيناريو agent — إعادة الهيكلة تُغيّر الحدود بين الكود المُتحقق منه وغير المُتحقق منه، مما قد يكسر مسارات كود كانت صحيحة ضمنيًا سابقًا. الأمر يشبه إعادة نسخ إجاباتك متعددة الخيارات لتحسين التنسيق قبل أن تنهي أسئلة المقالة الرياضية — ليس فقط يضيع الوقت، بل قد تنسخها بشكل خاطئ.++### الانحياز المنهجي في التقييم الذاتي++اكتشفت Anthropic نمط فشل أعمق في أبحاثها لعام 2026: **عندما يُطلب من agent تقييم عمله الخاص، يقدم تقييمات إيجابية بشكل مفرط بشكل منهجي — حتى عندما يرى مراقب بشري أن الجودة دون المستوى بوضوح.** هذا مثل طلب من طالب تصحيح امتحانه بنفسه — سيكون دائمًا متساهلاً بشكل خاص مع إجاباته الخاصة.++هذه المشكلة شديدة بشكل خاص في المهام الذاتية (مثل جماليات التصميم) — ما إذا كان "التصميم متقنًا" هو حكم تقديري، وagent يميل بشكل موثوق إلى الإيجابية. حتى في المهام ذات النتائج القابلة للتحقق، يمكن أن يتأثر أداء agent بسبب ضعف الحكم.++الحل ليس جعل agent "أكثر موضوعية" — النموذج نفسه الذي يُنشئ ويُقيّم يميل بطبيعته إلى الكرم مع نفسه. **الحل هو فصل "العامل" عن "المدقق".** تمامًا كما لا ينبغي للطالب تصحيح امتحانه — تحتاج إلى مصحح مستقل.++agent تقييم مستقل، مُضبوط خصيصًا ليكون "صارمًا"، أكثر فعالية بكثير من جعل agent المُنشئ يُقيّم نفسه. بيانات تجريبية من Anthropic:++| Architecture | Runtime | Cost | Core Features Working? |+|--------------|---------|------|------------------------|+| Single Agent (bare run) | 20 mins | $9 | No (game entities unresponsive to input) |+| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Yes (game is fully playable) |++هذا هو نفس النموذج بالضبط (Opus 4.5) مع نفس الموجه بالضبط ("build a 2D retro game editor"). الفرق الوحيد هو harness — من "التشغيل المجرّد" إلى "المخطط يُوسّع المتطلبات ← المُنشئ ينفذ ميزة بميزة ← المُقيّم يقوم باختبار النقر الفعلي باستخدام Playwright".++> المصدر: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## كيف تمنع التسليم المبكر++### 1. خارجنة حكم الإنهاء++لا ينبغي أن يُصدر حكم الاكتمال من agent نفسه. يجب أن ينفذ harness بشكل مستقل تحقق الإنهاء، مستخدمًا إشارات وقت التشغيل كمدخلات، وليس ثقة agent. اكتب هذا بوضوح في `CLAUDE.md`:++```+## Definition of Done+- Feature complete = end-to-end verification passed, not "code is written"+- Required verification levels:+ 1. Unit tests pass+ 2. Integration tests pass+ 3. End-to-end flow verification passes+- Do not proceed to level 2 if level 1 fails+- Do not proceed to level 3 if level 2 fails+```++### 2. ابنِ تحقق إنهاء ثلاثي الطبقات++- **الطبقة 1: التحليل البنيوي والثابت**. الأقل تكلفة، الأقل معلومات، لكن يجب أن تجتاز. هذا هو الحد الأدنى من الفحص — يجب أن تهجو الكلمات بشكل صحيح قبل أن ننظر إلى أي شيء آخر.+- **الطبقة 2: تحقق السلوك وقت التشغيل**. تنفيذ الاختبارات، فحوصات بدء التطبيق، التحقق من المسارات الحرجة. هذا هو الدليل الأساسي على الاكتمال. لا يكفي أن تكتبه فقط؛ يجب أن يعمل.+- **الطبقة 3: التأكيد على مستوى النظام**. الاختبار الشامل، تحقق التكامل، محاكاة سيناريوهات المستخدم. الخط الدفاعي الأخير ضد الإعلانات المبكرة. لا يكفي أن يعمل؛ يجب أن يعمل بشكل صحيح.++### 3. صمم "تعليمات بالقلم الأحمر" جيدة للوكلاء++قدمت OpenAI نمطًا فعالًا بشكل خاص خلال ممارسات Codex الخاصة بها: **يجب أن تتضمن رسائل الخطأ للوكلاء تعليمات الإصلاح**. لا ترسم فقط علامة حمراء كبيرة مثل مصحح كسول؛ كن مثل معلم جيد واكتب "هكذا يجب أن تُغيّر هذا" في الهوامش. لا تستخدم `"Test failed"`، بل استخدم `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` هذه التغذية الراجعة المحددة والقابلة للتنفيذ تسمح لـ agent بتصحيح نفسه بدون تدخل بشري.++### 4. التقط إشارات وقت التشغيل++تشمل إشارات وقت التشغيل الفعالة:+- هل بدأ التطبيق بنجاح ووصل إلى حالة الاستعداد؟+- هل نُفذت مسارات الميزات الحرجة بنجاح وقت التشغيل؟+- هل كانت عمليات كتابة قاعدة البيانات وعمليات الملفات والآثار الجانبية الأخرى صحيحة؟+- هل تم تنظيف الموارد المؤقتة؟++## حالة من العالم الحقيقي++**المهمة**: تنفيذ وظيفة إعادة تعيين كلمة مرور المستخدم. تتضمن عمليات قاعدة البيانات وإرسال البريد الإلكتروني وتعديلات نقطة نهاية API.++**مسار التسليم المبكر**: يُعدّل agent مخطط قاعدة البيانات، يكتب نقطة نهاية API، يضيف قالب بريد إلكتروني، يشغّل اختبارات الوحدة (تجتاز)، ويُعلن الاكتمال. ورقة الامتحان ممتلئة بالكامل.++**خصومات الدرجات الفعلية**: (1) التدفق الشامل غير مُختبَر — لم يتم تأكيد الإرسال والتحقق الفعلي لرابط إعادة التعيين أبدًا. (2) فشل ترحيل قاعدة البيانات بعد التنفيذ الجزئي، مما تسبب في عدم اتساق المخطط. (3) إعدادات خدمة البريد الإلكتروني كانت مفقودة في البيئة المستهدفة.++**تدخل harness**: فُرض تحقق الإنهاء — (1) بدء التطبيق الكامل للتحقق من إمكانية الوصول لنقطة نهاية إعادة التعيين؛ (2) تنفيذ تدفق إعادة التعيين الكامل؛ (3) التحقق من اتساق حالة قاعدة البيانات. وُجدت جميع العيوب خلال الجلسة، مما وفر 5-10 أضعاف تكلفة الإصلاحات اللاحقة. المصحح المستقل وجد المشاكل الحقيقية.++## الخلاصات الأساسية++- **الوكلاء مفرطو الثقة بشكل منهجي** — انحياز معايرة الثقة هو حقيقة موضوعية. ملء ورقة الامتحان لا يعني أن إجاباتك صحيحة.+- **يجب خارجنة حكم الاكتمال** — harness يتحقق بشكل مستقل؛ لا تثق بـ "مشاعر" agent. لا يمكن للطلاب تصحيح امتحاناتهم بأنفسهم.+- **جميع طبقات التحقق الثلاث ضرورية** — اجتياز البنية، اجتياز السلوك، اجتياز النظام، التقدم طبقة تلو طبقة.+- **يجب أن تكون رسائل الخطأ مثل تعليمات القلم الأحمر لمعلم جيد** — تتضمن خطوات إصلاح محددة حتى يتمكن agent من تصحيح نفسه.+- **لا إعادة هيكلة حتى يتم التحقق من الوظائف الأساسية** — قيد أولوية الاكتمال هو المفتاح لمنع التحسين المبكر.++## قراءات إضافية++- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — يثبت أن الشبكات العصبية العميقة الحديثة مفرطة الثقة بشكل منهجي+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — الدور الحاسم لأدلة وقت التشغيل في حكم الاكتمال+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — إعلان الاكتمال المبكر هو أحد أنماط الفشل الرئيسية للوكلاء+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — مرجع كلاسيكي حول تدرجات منهجية الاختبار وفعاليتها++## تمارين++1. **تصميم وظيفة تحقق الإنهاء**: صمم تحقق إنهاء كامل لمهمة تتضمن ترحيل قاعدة بيانات وتعديل API. اذكر إشارات وقت التشغيل المطلوبة ومعايير النجاح/الفشل لكل إشارة. شغّله على مهمة حقيقية وسجّل المشاكل المخفية التي يجدها.++2. **قياس انحياز المعايرة**: اختر 10 مهام برمجية من أنواع مختلفة، وسجّل ثقة agent المُبلغ عنها ذاتيًا في الاكتمال مقابل جودة الاكتمال الفعلية. احسب قيمة الانحياز وحلل علاقتها بتعقيد المهمة.++3. **تجربة الدفاع متعدد الطبقات**: شغّل ثلاثة تكوينات على نفس مجموعة المهام — (أ) تحليل ثابت فقط، (ب) إضافة اختبار الوحدات، (ج) تحقق ثلاثي الطبقات كامل. قارن نسبة إعلانات الاكتمال المبكر وعدد العيوب غير المُكتشفة.diff --git a/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.mdnew file mode 100644index 0000000..fd33d73--- /dev/null+++ b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md@@ -0,0 +1,6 @@+# قواعد بنية Electron++- لا يجوز لرمز العارض الوصول مباشرة إلى نظام الملفات.+- الـ Preload هو الجسر الوحيد بين العارض و Electron main.+- منطق الاسترجاع والفهرسة يعيش في وحدات الخدمة، وليس مكونات واجهة المستخدم.+- يجب أن تكون السجلات منظمة ومنبعثة من حدود الخدمات.diff --git a/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.tsnew file mode 100644index 0000000..2428416--- /dev/null+++ b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts@@ -0,0 +1,253 @@+/**+ * e2e-runner.ts+ *+ * A minimal E2E test harness. Defines test cases as user action sequences+ * (import doc -> index -> ask question -> verify citation). Simulates+ * running them and shows the difference between "unit tests pass" and+ * "full pipeline works".+ *+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface PipelineStep {+ name: string;+ unitTestPasses: boolean;+ // Simulated actual behavior in the pipeline+ actualBehavior: "works" | "fails" | "partial";+ failureReason?: string;+}++interface TestCase {+ name: string;+ steps: PipelineStep[];+}++interface TestResult {+ testCase: string;+ unitTestsPassed: number;+ unitTestsTotal: number;+ unitTestResult: "PASS" | "FAIL";+ e2eResult: "PASS" | "FAIL";+ e2eFailureStep?: string;+ e2eFailureReason?: string;+}++// ---------------------------------------------------------------------------+// Test cases -- realistic scenarios where unit tests pass but E2E fails+// ---------------------------------------------------------------------------++const testCases: TestCase[] = [+ {+ name: "Import document and ask question",+ steps: [+ {+ name: "Parse uploaded document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Store document chunks",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Index chunks for retrieval",+ unitTestPasses: true,+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions+ failureReason: "Embedding dimension mismatch between indexer and retriever",+ },+ {+ name: "Retrieve relevant chunks",+ unitTestPasses: true, // Unit test uses mock data with correct dimensions+ actualBehavior: "fails",+ failureReason: "Empty results due to dimension mismatch from previous step",+ },+ {+ name: "Generate answer with citations",+ unitTestPasses: true, // Unit test provides pre-retrieved chunks+ actualBehavior: "fails",+ failureReason: "No chunks retrieved, so answer has no citations",+ },+ ],+ },+ {+ name: "Delete document and verify removal",+ steps: [+ {+ name: "Find document by ID",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Delete document record",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Remove indexed chunks",+ unitTestPasses: true,+ actualBehavior: "fails", // Orphaned chunks remain in the index+ failureReason: "Index cleanup query timed out, chunks remain orphaned",+ },+ {+ name: "Verify document not in search results",+ unitTestPasses: true, // Unit test mocks the search+ actualBehavior: "fails",+ failureReason: "Orphaned chunks from previous step still appear in results",+ },+ ],+ },+ {+ name: "Multi-user concurrent access",+ steps: [+ {+ name: "User A imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User B imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User A queries their document",+ unitTestPasses: true,+ actualBehavior: "partial", // Cross-contamination of results+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",+ },+ {+ name: "Verify only User A's results returned",+ unitTestPasses: true,+ actualBehavior: "fails",+ failureReason: "Results include documents from other users",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Run tests+// ---------------------------------------------------------------------------++function runUnitTests(tc: TestCase): { passed: number; total: number } {+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;+ return { passed, total: tc.steps.length };+}++function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {+ // Pipeline: if any step actually fails, the whole E2E fails+ for (const step of tc.steps) {+ if (step.actualBehavior === "fails") {+ return {+ pass: false,+ failureStep: step.name,+ failureReason: step.failureReason ?? "Unknown failure",+ };+ }+ // "partial" means the step technically completes but creates problems downstream+ // We let it continue but track it+ }+ // Check if any step was "partial" (which may cause downstream issues)+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");+ if (partialSteps.length > 0) {+ // The partial steps may or may not cause overall failure+ // In our simulation, partial steps always lead to failure downstream+ // unless there's an explicit "fails" step that already caught it+ // This case means all steps were either "works" or "partial"+ return {+ pass: false,+ failureStep: partialSteps[partialSteps.length - 1].name,+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",+ };+ }++ return { pass: true };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(95));+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");+ console.log("=".repeat(95));++ const results: TestResult[] = testCases.map((tc) => {+ const unit = runUnitTests(tc);+ const e2e = runE2ETest(tc);++ return {+ testCase: tc.name,+ unitTestsPassed: unit.passed,+ unitTestsTotal: unit.total,+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",+ e2eResult: e2e.pass ? "PASS" : "FAIL",+ e2eFailureStep: e2e.failureStep,+ e2eFailureReason: e2e.failureReason,+ };+ });++ // Per-test-case detail+ for (let i = 0; i < testCases.length; i++) {+ const tc = testCases[i];+ const r = results[i];++ console.log("\n Test Case: " + tc.name);+ console.log(" " + "-".repeat(70));++ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;+ console.log(stepHeader);+ console.log(stepSep);++ for (const step of tc.steps) {+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";+ let e2eLabel: string;+ if (step.actualBehavior === "works") e2eLabel = "PASS";+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";+ else e2eLabel = "FAIL";++ const marker = step.actualBehavior !== "works" ? ">>" : " ";+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);+ }++ if (r.e2eFailureStep) {+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);+ console.log(` Reason: ${r.e2eFailureReason}`);+ }+ }++ // Summary comparison+ console.log("\n" + "=".repeat(95));+ console.log(" COMPARISON: Unit Tests vs E2E Tests");+ console.log("=".repeat(95) + "\n");++ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";++ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);+ }++ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");+}++run();diff --git a/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdnew file mode 100644index 0000000..5292181--- /dev/null+++ b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 10++استخدم هذا المجلد لأمثلة عن:++- قيود البنية المعمارية+- اختبارات هيكلية+- ثوابت الذوق (taste invariants)+- رسائل lint موجهة للإصلاحdiff --git a/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdnew file mode 100644index 0000000..6dae1ae--- /dev/null+++ b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -0,0 +1,10 @@+# مثال: تحويل ملاحظات المراجعة إلى قاعدة++تعليق مراجعة متكرر:++> لا تستخدم أدوات نظام الملفات من العارض. استخدم جسر الـ preload.++قاعدة harness مُرقّاة:++- إضافة قاعدة lint أو استيراد تمنع استخدام `fs` في كود العارض+- إضافة نص إصلاح يشرح حدود الـ preloaddiff --git a/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdnew file mode 100644index 0000000..59d8a07--- /dev/null+++ b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -0,0 +1,158 @@+[中文版本 →](../../../zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# المحاضرة 10. الاختبار end-to-end هو التحقق الحقيقي++تطلب من agent إضافة ميزة تصدير ملفات إلى تطبيق Electron. يكتب مكوّن عرض (render process) وpreload script ومنطق طبقة الخدمة. اختبارات الوحدة لكل مكون تجتاز بشكل مثالي. يقول agent "انتهيت." عندما تنقر فعليًا على زر التصدير — تنسيق مسار الملف خاطئ، شريط التقدم لا يُحدَّث، وتصدير الملفات الكبيرة يسبب تسربًا في الذاكرة. خمسة عيوب في حدود المكونات، واختبارات الوحدة لم تكتشف أيًا منها.++إنه مثل بروفة جوقة — كل جزء صوتي يبدو مثاليًا عند الغناء بشكل فردي، لكن عند الغناء معًا، السوبرانو أسرع بنصف نبضة من الباصات، والمرافقة بعيدة نصف نغمة عن اللحن الرئيسي. كل جزء "صحيح" بمفرده، لكن الكل غير متناغم.++يخبرنا هرم اختبار Google: عدد كبير من اختبارات الوحدة هو الأساس، لكن إذا توقفت هناك، ستفوت بشكل منهجي مشاكل تفاعل المكونات. بالنسبة لوكلاء البرمجة بالذكاء الاصطناعي، هذه المشكلة أكثر حدة — agent يميل إلى تشغيل أسرع الاختبارات فقط ثم إعلان الاكتمال. **فقط الاختبار end-to-end يمكنه إثبات أن العيوب على مستوى النظام غير موجودة.**++## النقاط العمياء لاختبار الوحدات++فلسفة تصميم اختبار الوحدات هي العزل — محاكاة التبعيات والتركيز فقط على الوحدة قيد الاختبار. هذه الفلسفة تجعل اختبار الوحدات سريعًا ودقيقًا، لكنها تخلق أيضًا نقاطًا عمياء منهجية. الأمر كمثل جعل كل جزء صوتي يتدرب بسماعات أثناء بروفة الجوقة — يبدو جيدًا لهم، لكن المشاكل تظهر فقط عندما يجتمعون:++**عدم تطابق الواجهة**: مسار الملف الذي يمرره عرض (render process) إلى preload script هو مسار نسبي، لكن preload script يتوقع مسارًا مطلقًا. اختبارات الوحدة الخاصة بكل منهما استخدمت محاكيات (mocks) واجتازت. لا تُكتشف المشكلة إلا عند تنفيذ التدفق الشامل — مثل جزأين صوتيين يتدربان بشكل مستقل ويشعران بالرضا، ليدركا فقط أثناء الأداء الجماعي أن أحدهما يغني بنظام 4/4 والآخر بنظام 3/4.++**أخطاء انتشار الحالة**: ترحيل قاعدة بيانات يُغيّر مخطط الجدول، لكن طبقة تخزين ORM المؤقت لا تزال تحتفظ بمداخل مخزنة للمخطط القديم. توفر اختبارات الوحدة بيئة محاكاة جديدة بالكامل في كل مرة، مما لن يكشف عدم اتساق الحالة هذا عبر الطبقات. إنه مثل تغيير كلمات أغنية، لكن شخصًا ما لا يزال يغني النسخة القديمة.++**مشاكل دورة حياة الموارد**: الحصول على مقابض الملفات وتحريرها واتصالات قاعدة البيانات ومنافذ الشبكة تمتد عبر مكونات متعددة. تنشئ اختبارات الوحدات وتدمر موارد مستقلة لكل اختبار، مما يفشل في كشف تنازع الموارد أو تسربها. إنه مثل كل جزء صوتي يتناوب استخدام الميكروفونات أثناء البروفة، لكن عندما يصعد الجميع إلى المسرح معًا، لا توجد ميكروفونات كافية.++**اعتماد البيئة**: يتصرف الكود بشكل صحيح في بيئة الاختبار (حيث كل شيء مُحاكى) لكنه يفشل في البيئة الحقيقية بسبب اختلافات الإعدادات أو زمن استجابة الشبكة أو عدم توفر الخدمة. مثل الغناء بشكل مثالي في غرفة البروفة، لكن مواجهة ارتداد صوتي وتداخل الرياح في مهرجان خارجي.++## الاختبار end-to-end لا يُغيّر النتائج فقط، بل يُغيّر السلوك أيضًا++هذا شيء لا يدركه الكثيرون: عندما يعرف agent أن عمله سيخضع لاختبار end-to-end، يتغير سلوكه في البرمجة.++1. **النظر في تفاعلات المكونات**: أثناء كتابة الكود، سيفكر في "كيف تتصل هذه الواجهة مع المنبع،" بدلاً من التركيز فقط على دالة واحدة. مثل معرفتك أنك ستغني معًا في النهاية، ستنتبه للأجزاء الصوتية الأخرى أثناء التدريب.+2. **احترام حدود البنية**: في الأنظمة ذات قيود البنية المعمارية، يُجبر الاختبار end-to-end agent على الالتزام بقواعد الحدود. مثل النوتات الموسيقية الموسومة بـ "تدرج صعودي هنا،" عليك أن تتبعها.+3. **معالجة مسارات الأخطاء**: تتضمن اختبارات end-to-end عادةً سيناريوهات الفشل، مما يُجبر agent على النظر في معالجة الاستثناءات. إنه مثل محاكاة "ماذا لو مات الميكروفون فجأة" أثناء البروفة، لتعرف ماذا تفعل.++## هرم الاختبار وتعزيز تغذية المراجعة++```mermaid+flowchart TB+ subgraph Unit["Unit tests only check isolated parts"]+ U1["Renderer tests"]+ U2["Preload tests"]+ U3["Service tests"]+ end++ subgraph E2E["E2E runs through the real system"]+ R["Click renderer button"] --> P["Preload bridge"]+ P --> S["Service layer"]+ S --> F["File System / OS"]+ F --> Result["Actual exported file"]+ end+```++```mermaid+flowchart LR+ Review["Review feedback:<br/>renderer cannot import fs directly"] --> Rule["Add a direct fs import check"]+ Rule --> Message["Tell agent in error message<br/>to move file access to preload"]+ Message --> Harness["Add this check to harness"]+ Harness --> Stronger["Will fail immediately next time"]+```++في ممارسات هندسة Codex، تشدد OpenAI: **يجب أن تتضمن رسائل الخطأ المكتوبة للوكلاء تعليمات إصلاح.** لا تكتب فقط `"Direct filesystem access in renderer"`؛ اكتب `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` هذا يحول القواعد المعمارية إلى حلقة تصحيح تلقائي. مثل قائد جوقة لا يقول فقط "لقد غنيت ذلك بشكل خاطئ،" بل يقول بدلاً من ذلك "كنت أسرع بنصف نبضة هنا، استمع إلى إيقاع الألتو، وادخل في المازورة 32."++## المفاهيم الأساسية++- **عيوب حدود المكونات**: المكون أ والمكون ب يجتازان اختبارات الوحدات الخاصة بهما، لكن تفاعلهما يُنتج سلوكًا غير صحيح. هذا هو نوع المشاكل التي ي best الاختبار end-to-end في اكتشافها — مثل أجزاء جوقة صحيحة بشكل فردي لكن غير متناغمة معًا.+- **تدرج كفاية الاختبار**: العيوب التي تكتشفها اختبارات الوحدات <= العيوب التي تكتشفها اختبارات التكامل <= العيوب التي تكتشفها اختبارات end-to-end. كل طبقة تصعد تزيد من قدرة الكشف.+- **قواعد فرض حدود البنية**: تحويل القواعد من مستندات البنية (مثل "لا يمكن لعرض (render process) الوصول إلى نظام الملفات مباشرة") إلى فحوصات قابلة للتنفيذ والآلية. من "مكتوبة على الورق" إلى "تعمل في CI."+- **تعزيز تغذية المراجعة**: تحويل تعليقات مراجعة الكود المتكررة إلى اختبارات آلية. في كل مرة يُعثر على مشكلة متكررة، أضف قاعدة، وينمو harness تلقائيًا أقوى. مثل قائد يحول أخطاء البروفة الشائعة إلى تمارين إحماء — في المرة القادمة التي يُرتكب فيها نفس الخطأ، التمرين نفسه يكشفها بدون الحاجة للقائد أن يقول كلمة.+- **رسائل الخطأ الموجهة للوكلاء**: يجب ألا تذكر رسائل الفشل فقط "ما الخطأ،" بل تخبر agent بالضبط كيف يصلحه. هذا يحول فشل الاختبار إلى حلقات تغذية راجعة ذاتية التصحيح.++## كيفية التنفيذ++### 0. حدد حدود البنية أولاً، ثم اكتب اختبارات E2E++المتطلب الأساسي للاختبار end-to-end هو حدود نظام واضحة. إذا كانت البنية المعمارية طبقًا من السباغيتي، فسيثبت الاختبار end-to-end فقط "هذا الطبق من السباغيتي يعمل،" ولن يخبرك أين انتهكت نوايا التصميم. إنه مثل جوقة لم تقسم حتى إلى أجزاء صوتية — أي قدر من البروفة لن يجعلها تبدو جيدة.++تجربة OpenAI: **لقواعد البيانات البرمجية التي ينشئها الوكلاء، يجب أن تكون القيود المعمارية متطلبات أساسية مبكرة تُؤسس في اليوم الأول، وليس شيئًا للنظر فيه عندما يكبر الفريق.** السبب بسيط — الوكلاء سينسخون الأنماط الموجودة في المستودع، حتى لو كانت تلك الأنماط غير متساوية أو دون المستوى الأمثل. بدون قيود معمارية، سيُدخل agent المزيد من الانحرافات في كل جلسة.++اعتمدت OpenAI "بنية النطاق الطبقية" — كل نطاق أعمال يُقسم إلى طبقات ثابتة: Types ← Config ← Repo ← Service ← Runtime ← UI. تتدفق التبعيات للأمام بشكل صارم، ويدخل القلق عبر النطاقات من خلال واجهات Providers صريحة. أي تبعيات أخرى ممنوعة وتُفرض آليًا عبر linting مخصص.++المبدأ الأساسي: **فرض الثوابت، لا تُدارة التنفيذ بدقة.** على سبيل المثال، اطلب "تُحلل البيانات عند الحدود،" لكن لا تحدد أي مكتبة لاستخدامها. يجب أن تتضمن رسائل الخطأ تعليمات إصلاح — لا تقول فقط "انتهاك،" بل تخبر agent بالضبط كيف يُغيّره.++> المصدر: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++### 1. يجب أن يتضمن harness طبقة end-to-end++اجعل ذلك صريحًا في تدفق التحقق: للمهام التي تتضمن تغييرات عبر المكونات، اجتياز اختبارات end-to-end هو متطلب أساسي للاكتمال:++```+## Validation Hierarchy+- Level 1: Unit tests (Must pass)+- Level 2: Integration tests (Must pass)+- Level 3: End-to-end tests (Must pass when cross-component changes are involved)+- Skipping any required level = Not Complete+```++### 2. حوّل القواعد المعمارية إلى فحوصات قابلة للتنفيذ++كل قيد معماري يجب أن يكون له اختبار أو قاعدة lint مقابلة:++```bash+# Check if the render process directly calls Node.js APIs+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"+```++### 3. صمم رسائل خطأ موجهة للوكلاء++يجب أن تحتوي رسائل الفشل على ثلاثة عناصر: ما الخطأ، ولماذا، وكيف تُصلحه:++```+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12+WHY: Renderer process has no access to Node.js APIs for security+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()+```++### 4. أسّس عملية تعزيز تغذية المراجعة++في كل مرة يُعثر على نوع جديد من أخطاء agent أثناء مراجعة الكود، حوّله إلى فحص آلي. بعد شهر، سيكون harness أقوى بكثير مما كان في بداية الشهر. إنه مثل ملاحظات بروفة الجوقة — تسجيل المشاكل الموجودة في كل بروفة حتى يمكن فحصها قبل البروفة التالية. بمرور الوقت، تنخفض الأخطاء الشائعة، وتصبح الموسيقى أكثر تناغمًا.++## حالة من العالم الحقيقي++**المهمة**: تنفيذ ميزة تصدير ملفات في تطبيق Electron. تتضمن واجهة مستخدم عرض (render process) ووكيل نظام ملفات preload script وتحويل بيانات طبقة الخدمة.++**الغناء بشكل فردي (اجتازت اختبارات الوحدات)**: اختبارات مكوّن العرض (اجتازت، عمليات الملفات مُحاكاة)، اختبارات preload script (اجتازت، نظام الملفات مُحاكى)، اختبارات طبقة الخدمة (اجتازت، مصدر البيانات مُحاكى). agent يُعلن الاكتمال.++**الغناء معًا (عيوب كشفها اختبار End-to-End)**:++| Defect | Description | Unit Test | E2E |+|--------|-------------|-----------|-----|+| Interface Mismatch | Inconsistent file path format | Missed | Caught |+| State Propagation | Export progress not sent back to UI via IPC | Missed | Caught |+| Resource Leak | Large file export handles not released | Missed | Caught |+| Permission Issue | Different permissions in packaged environment | Missed | Caught |+| Error Propagation | Service layer exceptions didn't reach UI layer | Missed | Caught |++كل العيوب الخمسة اكتُشفت بواسطة اختبارات end-to-end، بينما لم تكتشف اختبارات الوحدات أيًا منها. كانت التكلفة زيادة في وقت الاختبار من ثانيتين إلى 15 ثانية — مقبولة تمامًا في سير عمل agent. مهما غنى كل جزء بشكل جيد بشكل فردي، لا يمكنه التغلب على بروفة جماعية كاملة.++## الخلاصات الأساسية++- **اختبارات الوحدات عمياء بشكل منهجي عن عيوب حدود المكونات** — تصميم عزلها هو بالضبط ما يمنعها من اكتشاف مشاكل التفاعل. غناء الجميع بشكل صحيح لا يعني أن الجوقة غير نشاز.+- **الاختبار end-to-end لا يكتشف العيوب فقط، بل يُغيّر سلوك برمجة agent** — مما يجعله يركز أكثر على التكامل والحدود.+- **يجب أن تكون القواعد المعمارية قابلة للتنفيذ** — ليست مكتوبة في مستند بانتظار أن تُقرأ، بل تُفحص تلقائيًا مع كل التزام.+- **يجب تصميم رسائل الخطأ للوكلاء** — تتضمن خطوات محددة حول "كيفية الإصلاح" لتشكيل حلقة تصحيح ذاتي.+- **تعزيز تغذية المراجعة يجعل harness أقوى تلقائيًا** — كل فئة من العيوب المُلتقطة تصبح خط دفاع دائم.++## قراءات إضافية++- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — المصدر الكلاسيكي لنموذج هرم الاختبار+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — ممارسات هندسية للتنفيذ الآلي للقيود المعمارية+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — حقن الأعطال استباقيًا للتحقق من مرونة النظام+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — منهجية اختبار الخصائص، تقع بين اختبار الأمثلة والتحقق الشكلي++## تمارين++1. **اكتشاف العيوب عبر المكونات**: اختر مهمة تعديل تتضمن ثلاثة مكونات على الأقل. أولاً، شغّل اختبارات الوحدات فقط وسجّل النتائج، ثم شغّل اختبارات end-to-end. حلل نوع مشكلة التفاعل عبر الطبقات التي ينتمي إليها كل عيب إضافي مُكتشف.++2. **أتمتة القواعد المعمارية**: اختر قيدًا معماريًا من مشروعك وحوّله إلى فحص قابل للتنفيذ (مع رسالة خطأ موجهة لـ agent). ادمجه في harness وتحقق من فعاليته بمهمة أساسية.++3. **تعزيز تغذية المراجعة**: اعثر على نوع تعليق متكرر من سجل مراجعة الكود الخاص بك وحوّله إلى فحص آلي باستخدام العملية ذات الخطوات الخمس. قارن تكرار المشكلة قبل وبعد التعزيز.diff --git a/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.mdnew file mode 100644index 0000000..375184b--- /dev/null+++ b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md@@ -0,0 +1,8 @@+# مثال على معيار التقييم++استخدم تقييم 1-5 لكل بُعد:++- التأسيس: هل الإجابات مرتبطة بوضوح بالمصادر المستوردة؟+- جودة الاستشهاد: هل مراجع المصادر مرئية ومحددة؟+- الوظائف: هل يمكن للمستخدم إكمال تدفق السؤال والجواب؟+- تماسك المنتج: هل يبدو سير العمل متكاملاً؟diff --git a/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdnew file mode 100644index 0000000..f6ca6af--- /dev/null+++ b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 11++استخدم هذا المجلد لأمثلة عن:++- مخرجات المخطط+- معايير التقييم+- حلقات المُنشئ/المُقيّم+- مقارنات الوكيل الواحد مقابل الأدوار المتعددةdiff --git a/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsnew file mode 100644index 0000000..213dc19--- /dev/null+++ b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts@@ -0,0 +1,260 @@+/**+ * runtime-logger.ts+ *+ * A structured logging module demo. Shows ad-hoc console.log output vs+ * structured JSON log output when diagnosing a failure. Includes a seeded+ * failure scenario and demonstrates how structured logs pinpoint the issue+ * faster.+ *+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StructuredLogEntry {+ timestamp: string;+ level: "info" | "warn" | "error" | "debug";+ component: string;+ action: string;+ durationMs?: number;+ input?: unknown;+ output?: unknown;+ error?: string;+ correlationId: string;+}++// ---------------------------------------------------------------------------+// Simulated pipeline with a seeded failure+// ---------------------------------------------------------------------------++const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);++// Simulated stages of a document Q&A pipeline+interface PipelineStage {+ component: string;+ action: string;+ durationMs: number;+ success: boolean;+ errorMessage?: string;+ input?: unknown;+ output?: unknown;+}++function runPipeline(): PipelineStage[] {+ return [+ {+ component: "DocumentLoader",+ action: "parse_upload",+ durationMs: 45,+ success: true,+ input: { filename: "report.pdf", size: "2.3MB" },+ output: { chunks: 47 },+ },+ {+ component: "ChunkIndexer",+ action: "embed_and_store",+ durationMs: 230,+ success: true,+ input: { chunks: 47 },+ output: { indexed: 47, embeddingDim: 1536 },+ },+ {+ component: "QueryRouter",+ action: "route_query",+ durationMs: 12,+ success: true,+ input: { query: "What is the revenue target?" },+ output: { routedTo: "RetrievalEngine" },+ },+ {+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch+ component: "RetrievalEngine",+ action: "semantic_search",+ durationMs: 180,+ success: false,+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",+ input: { query: "What is the revenue target?", topK: 5 },+ output: { results: 0 },+ },+ {+ component: "AnswerGenerator",+ action: "generate_with_citations",+ durationMs: 1500,+ success: true, // Doesn't crash, but produces a bad answer+ input: { context: [], query: "What is the revenue target?" },+ output: { answer: "I could not find relevant information.", citations: 0 },+ },+ ];+}++// ---------------------------------------------------------------------------+// Ad-hoc logging (console.log style)+// ---------------------------------------------------------------------------++function printAdHocLog(stages: PipelineStage[]): void {+ console.log("Starting document Q&A pipeline...");+ console.log("User uploaded report.pdf");++ for (const stage of stages) {+ if (stage.success) {+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);+ } else {+ console.log(`${stage.component}: something went wrong`);+ }+ }++ console.log("Pipeline finished. Answer: I could not find relevant information.");+}++// ---------------------------------------------------------------------------+// Structured logging (JSON)+// ---------------------------------------------------------------------------++function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {+ const entries: StructuredLogEntry[] = [];++ for (const stage of stages) {+ entries.push({+ timestamp: new Date().toISOString(),+ level: stage.success ? "info" : "error",+ component: stage.component,+ action: stage.action,+ durationMs: stage.durationMs,+ input: stage.input,+ output: stage.output,+ error: stage.errorMessage,+ correlationId: CORRELATION_ID,+ });+ }++ return entries;+}++// ---------------------------------------------------------------------------+// Diagnose failure from structured logs+// ---------------------------------------------------------------------------++function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {+ const diagnosis: string[] = [];++ // Find errors+ const errors = entries.filter((e) => e.level === "error");+ if (errors.length > 0) {+ diagnosis.push("ERRORS FOUND:");+ for (const err of errors) {+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);+ }+ }++ // Check for latency spikes+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);+ if (slowStages.length > 0) {+ diagnosis.push("LATENCY SPIKES:");+ for (const s of slowStages) {+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);+ }+ }++ // Check for cascading failures+ const emptyOutputs = entries.filter((e) => {+ const out = e.output as Record<string, unknown> | undefined;+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;+ });+ if (emptyOutputs.length > 0) {+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");+ for (const e of emptyOutputs) {+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);+ }+ }++ return diagnosis;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const pipeline = runPipeline();++ console.log("\n" + "=".repeat(90));+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");+ console.log("=".repeat(90));++ // --- Ad-hoc output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO A: Ad-hoc console.log output");+ console.log("-".repeat(90) + "\n");+ printAdHocLog(pipeline);+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");+ console.log(" The failure message is vague: 'something went wrong'.");+ console.log(" No dimensions, no input/output data, no correlation ID.");++ // --- Structured output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO B: Structured JSON log output");+ console.log("-".repeat(90) + "\n");++ const structuredEntries = printStructuredLog(pipeline);++ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const entry of structuredEntries) {+ const hasError = entry.error ? entry.error.slice(0, 30) : "";+ const marker = entry.level === "error" ? ">>" : " ";+ console.log(+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`+ );+ }++ // --- Diagnosis ---+ console.log("\n" + "-".repeat(90));+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");+ console.log("-".repeat(90) + "\n");++ const errors = structuredEntries.filter((e) => e.level === "error");+ for (const err of errors) {+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);+ console.log(` Error: ${err.error}`);+ console.log(` Input: ${JSON.stringify(err.input)}`);+ console.log(` Output: ${JSON.stringify(err.output)}`);+ console.log(` Correlation ID: ${err.correlationId}`);+ }++ // Downstream impact+ console.log("\n DOWNSTREAM IMPACT:");+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");+ if (answerGen) {+ const out = answerGen.output as Record<string, unknown>;+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);+ }++ // Comparison summary+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON");+ console.log("=".repeat(90) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);++ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");+}++run();diff --git a/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.mdnew file mode 100644index 0000000..04d34c7--- /dev/null+++ b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md@@ -0,0 +1,12 @@+# مثال على عقد السبرنت++هدف السبرنت:++- إضافة استشهادات مرئية لنتائج الأسئلة والأجوبة المُؤسسة++"منتهٍ" يعني:++- يسأل المستخدم سؤالاً+- يُرجع التطبيق إجابة+- يظهر استشهاد واحد على الأقل+- النقر على استشهاد يفتح موقع المصدر في عرض المستندdiff --git a/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdnew file mode 100644index 0000000..9dc3ba6--- /dev/null+++ b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -0,0 +1,154 @@+[中文版本 →](../../../zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)+> مشروع عملي: [المشروع 06. Harness كامل (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# المحاضرة 11. اجعل runtime الوكيل قابلًا للملاحظة++## ما المشكلة التي تحلها هذه المحاضرة؟++تطلب من وكيل أن ينفذ ميزة. يعمل 20 دقيقة، يعدل عددًا كبيرًا من الملفات، ثم يقول لك: "انتهيت، لكن هناك اختبارين يفشلان". تسأله لماذا يفشلان فيجيب: "لست متأكدًا، ربما مشكلة توقيت". تسأله أي المسارات الحرجة غيّرها فيقول: "دعني أنظر إلى الكود...".++المشكلة ليست أن الوكيل غير قادر. المشكلة أن harness لا يوفر ملاحظة كافية. **من دون observability، يتخذ الوكلاء قرارات تحت عدم اليقين، وتصبح التقييمات أحكامًا ذاتية، وتتحول المحاولات المتكررة إلى تخبط أعمى.** كل من OpenAI و Anthropic يعرفان الموثوقية على أنها مشكلة أدلة: يجب على harness أن يكشف سلوك runtime وإشارات التقييم بصيغة تساعد القرار التالي.++## المفاهيم الأساسية++- **ملاحظة runtime**: إشارات على مستوى النظام مثل logs و traces وأحداث العمليات و health checks. تجيب عن سؤال "ماذا فعل النظام؟".+- **ملاحظة العملية**: رؤية لآثار قرارات harness مثل الخطط، rubrics، ومعايير القبول. تجيب عن سؤال "لماذا يجب قبول هذا التغيير؟".+- **Task trace**: سجل كامل لمسار القرار من بداية المهمة إلى نهايتها، مشابه لتتبع الطلبات في الأنظمة الموزعة.+- **Sprint contract**: اتفاق قصير قبل كتابة الكود يحدد نطاق المهمة، ومعايير التحقق، والاستثناءات. وهو أداة أساسية لملاحظة العملية.+- **Evaluator rubric**: يحول تقييم الجودة من حكم ذاتي إلى تقييم منظم قائم على الأدلة.+- **ملاحظة متعددة الطبقات**: تصميم ملاحظة طبقة النظام وطبقة العملية معًا بحيث يعزز كل منهما الآخر. إشارات runtime تشرح السلوك، وآثار العملية تشرح النية.++## ملاحظة متعددة الطبقات++```mermaid+flowchart LR+ Contract["اكتب المهمة أولًا<br/>ما الذي يتغير / ما لا يتغير / معايير النجاح"] --> Generator["Generator"]+ Generator --> Signals["اجمع logs و traces<br/>و health checks أثناء التشغيل"]+ Contract --> Review["راجع النتيجة بندًا بندًا<br/>السلوك / الاختبارات / الحدود"]+ Signals --> Review+ Review --> Verdict["أشر إلى الفحص الفاشل<br/>ومكان الإصلاح"]+ Verdict --> Generator+```++## لماذا يحدث هذا++### التكلفة الحقيقية لغياب observability++عندما يفتقر harness إلى observability، تظهر أربعة أنواع من المشاكل بشكل منهجي:++**لا يمكن التمييز بين "صحيح" و"يبدو صحيحًا"**: قد تبدو الدالة صحيحة تمامًا في مراجعة الكود، لكن في runtime ينتج خطأ edge case نتائج غير صحيحة لمدخلات محددة. وحدها runtime traces تكشف أن مسار التنفيذ الفعلي انحرف عن المتوقع.++**يصبح التقييم غامضًا**: من دون rubrics ومعايير قبول، يعتمد المقيمون، بشرًا كانوا أم وكلاء، على افتراضات ضمنية. قد يحصل نفس الناتج على تقييمات مختلفة جدًا. يصبح تقييم الجودة غير قابل لإعادة الإنتاج.++**تصبح المحاولات المتكررة تخمينات عمياء**: عندما لا يعرف الوكيل سبب الفشل، يكون اتجاه المحاولة التالية عشوائيًا. قد يصلح مسارات كود غير مرتبطة بينما يتجاهل السبب الجذري. كل محاولة عمياء تكلف tokens ووقتًا.++**انحدار معلومات handoff بين الجلسات**: عندما ينتقل عمل غير مكتمل إلى جلسة جديدة، يعني غياب observability أن الجلسة الجديدة يجب أن تشخص حالة النظام من الصفر. تشير ملاحظات Anthropic إلى أن هذا التشخيص المتكرر قد يستهلك 30-50% من وقت الجلسة.++### سيناريو واقعي مع Claude Code++تخيل harness يستخدم workflow بثلاثة أدوار: planner-generator-evaluator، وينفذ مهمة "أضف dark mode إلى التطبيق".++**من دون observability**: يخرج planner وصفًا غامضًا. ينفذ generator dark mode بناءً على هذا الغموض، لكنه لا يطابق توقعات planner الضمنية. يرفض evaluator النتيجة وفق معاييره الضمنية، لكنه لا يستطيع شرح الخطأ تحديدًا. يعيد generator المحاولة عشوائيًا. تتكرر الدورة 3-4 مرات، وتستغرق نحو 45 دقيقة، وتنتج مخرجًا بالكاد مقبولًا.++**مع observability كاملة**: يخرج planner عقد sprint contract يعدد المكونات التي يجب تعديلها، ومعايير التحقق، والاستثناءات. ينفذ generator وفق العقد. تسجل runtime observability تحميل وتطبيق الأنماط لكل مكون. يستخدم evaluator rubric لتقييم كل بُعد مع أدلة محددة. تنتج دورة واحدة نتيجة عالية الجودة في نحو 15 دقيقة.++فرق الكفاءة 3x. التغيير الوحيد هو observability.++### لماذا لا يستطيع الوكلاء حل ذلك وحدهم++قد تفكر: "ألا يستطيع الوكيل طباعة logs بنفسه؟" المشاكل هي:++1. الوكيل لا يعرف ما لا يعرفه؛ لن يسجل إشارات لا يدرك أنه يحتاجها.+2. تنسيقات logs غير متسقة؛ كل جلسة قد تستخدم شكلًا مختلفًا، وهذا يمنع التحليل المنهجي.+3. ملاحظة العملية لا تحلها logs؛ sprint contracts و scoring rubrics آثار منظمة تحتاج دعمًا على مستوى harness.++## كيف تفعل ذلك بشكل صحيح++### 1. ابنِ جمع إشارات runtime داخل harness++لا تعتمد على الوكيل ليطبع logs بنفسه. يجب أن يجمع harness هذه الإشارات تلقائيًا:++- **دورة حياة التطبيق**: حالات startup و ready و running و shutdown+- **تنفيذ مسار الميزة**: سجلات للمسارات الحرجة، بما فيها نقاط الدخول و checkpoints والخروج+- **تدفق البيانات**: سجلات البيانات بين المكونات+- **استخدام الموارد**: أنماط غير طبيعية مثل ذاكرة تنمو باستمرار+- **الأخطاء والاستثناءات**: سياق الخطأ كاملًا، لا رسالة الخطأ فقط++### 2. نفذ sprint contracts++قبل بدء كل مهمة، يتفاوض generator و evaluator، وقد يكونان استدعاءين مختلفين لنفس الوكيل، على عقد:++```markdown+# Sprint Contract: Dark Mode Support++## Scope+- Modify the theme toggle component+- Update global CSS variables+- Add dark mode tests++## Verification Standards+- Visual regression tests pass for each component+- Main flow end-to-end tests pass+- No flash of unstyled content (FOUC)++## Exclusions+- Not handling print styles+- Not handling third-party component dark mode+```++### 3. أنشئ rubric للتقييم++حوّل سؤال "هل هذا جيد؟" إلى تقييم قابل للقياس:++```markdown+# Scoring Rubric++| Dimension | A | B | C | D |+|-----------|---|---|---|---|+| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |+| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |+| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |+```++### 4. وحّد القياس باستخدام OpenTelemetry++أنشئ trace لكل جلسة harness، و span لكل مهمة، و sub-spans لكل خطوة تحقق. استخدم attributes قياسية لتسجيل المعلومات المهمة. هكذا يمكن دمج بيانات observability مع أدوات مثل Jaeger و Zipkin.++## حالة واقعية++Harness يستخدم workflow من planner-generator-evaluator لتنفيذ "إضافة دعم dark mode":++**نسخة غير قابلة للملاحظة**: 3-4 جولات من المحاولات العمياء، 45 دقيقة، نتيجة بالكاد مقبولة. يقول evaluator "لا تبدو صحيحة" لكنه لا يستطيع تحديد السبب. يضيع generator وقتًا كبيرًا في اتجاهات خاطئة.++**نسخة قابلة للملاحظة بالكامل**:+- sprint contract يوضح النطاق والمعايير والاستثناءات+- runtime traces تسجل تحميل الأنماط لكل مكون+- rubric يوفر تقييمًا منظمًا لكل بُعد+- دورة واحدة تنتج نتيجة عالية الجودة في 15 دقيقة++تحسن كفاءة 3x، جودة أكثر استقرارًا، وتقييمات قابلة لإعادة الإنتاج.++## الخلاصات الأساسية++- **Observability خاصية معمارية في harness**، وليست ميزة تضاف لاحقًا.+- **طبقتا observability ضروريتان**: إشارات runtime تشرح "ماذا حدث"، وآثار العملية تشرح "لماذا حدث بهذه الطريقة".+- **Sprint contracts تسبق التنفيذ بالتوافق**، فتمنع بناء شيء سيرفضه evaluator فورًا لأسباب متوقعة.+- **Rubrics تجعل التقييم قابلًا لإعادة الإنتاج**، بحيث يعطي مقيمون مختلفون درجات متقاربة لنفس الناتج.+- **غياب observability يهدر 30-50% من وقت الجلسة في تشخيص مكرر.**++## قراءات إضافية++- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — إطار نظري وعملي لهندسة observability الحديثة+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — ممارسة رائدة في tracing الموزع واسع النطاق+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — تقديم sprint contracts و evaluator rubrics+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — تطبيق منهجي للملاحظة في أنظمة الإنتاج++## تمارين++1. **تحليل فجوة observability**: راجع harness الحالي لديك من طبقة النظام وطبقة العملية. ابحث عن حالات نظام لا يمكن تمييزها من الإشارات الحالية واقترح إضافات.++2. **تدريب sprint contract**: اكتب sprint contract لمهمة حقيقية. اجعل الوكيل ينفذ وفق العقد، وقارن الكفاءة والجودة مع العقد وبدونه.++3. **بناء task trace**: سجل كل خطوة من عمليات الوكيل أثناء مهمة برمجية كاملة. أضف annotations باستخدام OpenTelemetry semantic conventions وحلل نقاط نقص المعلومات.diff --git a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.mdnew file mode 100644index 0000000..3866978--- /dev/null+++ b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md@@ -0,0 +1,18 @@+# قالب مقارنة المعيار++Harness أ:++- معدل الإكمال+- متوسط المحاولات+- الأخطاء المكتشفة قبل المراجعة البشرية++Harness ب:++- معدل الإكمال+- متوسط المحاولات+- الأخطاء المكتشفة قبل المراجعة البشرية++التفسير:++- أي harness غيّر النتيجة؟+- أي harness غيّر تكلفة الحصول على النتيجة؟diff --git a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.tsnew file mode 100644index 0000000..0388cad--- /dev/null+++ b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts@@ -0,0 +1,216 @@+/**+ * benchmark-runner.ts+ *+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),+ * "executes" each task, records timing and pass/fail, outputs a comparison+ * report showing which tasks pass and which fail.+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BenchmarkTask {+ id: string;+ name: string;+ category: string;+ passCriteria: string[];+ expectedDurationMs: number;+ // Simulated actual results+ actualDurationMs: number;+ actualPass: boolean;+ failureReason?: string;+}++interface BenchmarkResult {+ id: string;+ name: string;+ category: string;+ criteriaTotal: number;+ criteriaPassed: number;+ pass: boolean;+ expectedMs: number;+ actualMs: number;+ durationDelta: number;+ failureReason?: string;+}++// ---------------------------------------------------------------------------+// Benchmark task definitions+// ---------------------------------------------------------------------------++const benchmarkTasks: BenchmarkTask[] = [+ {+ id: "bench-001",+ name: "Import markdown document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 100,+ actualDurationMs: 95,+ actualPass: true,+ },+ {+ id: "bench-002",+ name: "Import PDF document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 200,+ actualDurationMs: 310,+ actualPass: false,+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",+ },+ {+ id: "bench-003",+ name: "Ask grounded question",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],+ expectedDurationMs: 500,+ actualDurationMs: 480,+ actualPass: true,+ },+ {+ id: "bench-004",+ name: "Ask question with no relevant docs",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],+ expectedDurationMs: 400,+ actualDurationMs: 420,+ actualPass: false,+ failureReason: "Model hallucinated a citation instead of saying 'no results'",+ },+ {+ id: "bench-005",+ name: "Delete imported document",+ category: "Document Pipeline",+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],+ expectedDurationMs: 150,+ actualDurationMs: 145,+ actualPass: true,+ },+ {+ id: "bench-006",+ name: "Concurrent user access",+ category: "Security",+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],+ expectedDurationMs: 300,+ actualDurationMs: 850,+ actualPass: false,+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",+ },+ {+ id: "bench-007",+ name: "Session continuity after restart",+ category: "Reliability",+ passCriteria: ["State persisted", "Session recovers", "No data loss"],+ expectedDurationMs: 200,+ actualDurationMs: 180,+ actualPass: true,+ },+ {+ id: "bench-008",+ name: "API rate limiting",+ category: "Security",+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],+ expectedDurationMs: 100,+ actualDurationMs: 100,+ actualPass: true,+ },+];++// ---------------------------------------------------------------------------+// Execution simulation+// ---------------------------------------------------------------------------++function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {+ return tasks.map((task) => ({+ id: task.id,+ name: task.name,+ category: task.category,+ criteriaTotal: task.passCriteria.length,+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),+ pass: task.actualPass,+ expectedMs: task.expectedDurationMs,+ actualMs: task.actualDurationMs,+ durationDelta: task.actualDurationMs - task.expectedDurationMs,+ failureReason: task.failureReason,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(100));+ console.log(" BENCHMARK RUNNER -- Task Execution Report");+ console.log("=".repeat(100));++ const results = executeBenchmark(benchmarkTasks);++ // Detailed results+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;+ console.log("\n" + header);+ console.log(sep);++ for (const r of results) {+ const passLabel = r.pass ? "PASS" : "FAIL";+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;+ const marker = r.pass ? " " : ">>";++ console.log(+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`+ );+ }++ // Failure details+ const failures = results.filter((r) => !r.pass);+ if (failures.length > 0) {+ console.log("\n" + "-".repeat(100));+ console.log(" FAILURE DETAILS");+ console.log("-".repeat(100));+ for (const f of failures) {+ console.log(`\n [${f.id}] ${f.name}`);+ console.log(` Category: ${f.category}`);+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);+ }+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SUMMARY BY CATEGORY");+ console.log("=".repeat(100) + "\n");++ const categories = [...new Set(results.map((r) => r.category))];+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;+ console.log(catHeader);+ console.log(catSep);++ for (const cat of categories) {+ const catResults = results.filter((r) => r.category === cat);+ const catPassed = catResults.filter((r) => r.pass).length;+ const catFailed = catResults.filter((r) => !r.pass).length;+ const rate = Math.round((catPassed / catResults.length) * 100);++ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);+ }++ // Overall+ const totalPassed = results.filter((r) => r.pass).length;+ const totalFailed = results.filter((r) => !r.pass).length;+ console.log("\n" + "-".repeat(100));+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);+ console.log("=".repeat(100) + "\n");+}++run();diff --git a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdnew file mode 100644index 0000000..54fc930--- /dev/null+++ b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -0,0 +1,9 @@+# مثال على حلقة التنظيف++مهام تنظيف متكررة:++- فحص المستندات القديمة+- فحص الانتهاكات الهيكلية+- تحديث درجات الجودة+- فتح طلبات سحب تنظيف مستهدفة+- إعادة تشغيل شريحة معيار ثابتة بعد التنظيفdiff --git a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.tsnew file mode 100644index 0000000..6b35905--- /dev/null+++ b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts@@ -0,0 +1,336 @@+/**+ * cleanup-scanner.ts+ *+ * Scans a project directory for stale artifacts, dead code, structural+ * violations, and outputs a cleanup report. Helps enforce the "clean state+ * at end of every session" principle.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]+ * (defaults to current working directory)+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface ScanResult {+ category: string;+ check: string;+ severity: "critical" | "warning" | "info";+ found: string[];+ description: string;+}++// ---------------------------------------------------------------------------+// Scanner checks+// ---------------------------------------------------------------------------++interface ScannerCheck {+ category: string;+ name: string;+ severity: "critical" | "warning" | "info";+ description: string;+ scan: (dir: string) => string[];+}++function createChecks(): ScannerCheck[] {+ return [+ {+ category: "Stale Artifacts",+ name: "Temporary files (*.tmp, *.bak, *.swp)",+ severity: "warning",+ description: "Leftover temp files from editing or processing",+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),+ },+ {+ category: "Stale Artifacts",+ name: "Debug/log files in source",+ severity: "warning",+ description: "Log files that should not be in the source tree",+ scan: (dir) => {+ const found: string[] = [];+ const logPatterns = [".log"];+ for (const p of findFiles(dir, logPatterns)) {+ // Only flag log files in source directories+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {+ found.push(p);+ }+ }+ return found;+ },+ },+ {+ category: "Dead Code",+ name: "Unused imports (placeholder detection)",+ severity: "info",+ description: "Files that may contain unused code (heuristic scan)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app"];+ for (const srcDir of srcDirs) {+ const srcPath = path.join(dir, srcDir);+ if (fs.existsSync(srcPath)) {+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "Missing .gitignore",+ severity: "warning",+ description: "No .gitignore file found -- risk of committing build artifacts",+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],+ },+ {+ category: "Structural Violations",+ name: "Build artifacts in source",+ severity: "critical",+ description: "Compiled output (dist/, build/) mixed with source",+ scan: (dir) => {+ const found: string[] = [];+ // Check if dist/ or build/ exists inside src/+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];+ for (const d of dirs) {+ if (fs.existsSync(path.join(dir, d))) {+ found.push(d + "/");+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "node_modules in source tree",+ severity: "critical",+ description: "node_modules directory found outside root (nested dependency)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app", "test", "tests"];+ for (const srcDir of srcDirs) {+ const nmPath = path.join(dir, srcDir, "node_modules");+ if (fs.existsSync(nmPath)) {+ found.push(srcDir + "/node_modules/");+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Uncommitted changes indicator",+ severity: "info",+ description: "Checks for common artifacts of incomplete sessions",+ scan: (dir) => {+ const found: string[] = [];+ const indicators = [+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",+ "debug.ts", "test-manual.ts", "temp.ts",+ ];+ for (const f of indicators) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Empty directories",+ severity: "info",+ description: "Empty directories that may be leftover from incomplete work",+ scan: (dir) => {+ const found: string[] = [];+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];+ for (const d of commonDirs) {+ const dp = path.join(dir, d);+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {+ try {+ const contents = fs.readdirSync(dp);+ if (contents.length === 0) {+ found.push(d + "/");+ }+ } catch {+ // Skip directories we can't read+ }+ }+ }+ return found;+ },+ },+ {+ category: "Configuration",+ name: "Environment files in source",+ severity: "critical",+ description: ".env files that may contain secrets",+ scan: (dir) => {+ const found: string[] = [];+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];+ for (const f of envFiles) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ ];+}++// ---------------------------------------------------------------------------+// Helper functions+// ---------------------------------------------------------------------------++function findFiles(dir: string, extensions: string[]): string[] {+ const found: string[] = [];++ function walk(current: string, depth: number): void {+ if (depth > 4) return; // Limit recursion depth+ try {+ const entries = fs.readdirSync(current, { withFileTypes: true });+ for (const entry of entries) {+ // Skip common non-source directories+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {+ continue;+ }++ const fullPath = path.join(current, entry.name);+ const relativePath = path.relative(dir, fullPath);++ if (entry.isDirectory()) {+ walk(fullPath, depth + 1);+ } else if (entry.isFile()) {+ if (extensions.some((ext) => entry.name.endsWith(ext))) {+ found.push(relativePath);+ }+ }+ }+ } catch {+ // Skip directories we can't read+ }+ }++ walk(dir, 0);+ return found;+}++function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {+ try {+ const entries = fs.readdirSync(dir, { withFileTypes: true });+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);+ }+ continue;+ }++ const fullPath = path.join(dir, entry.name);+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {+ continue;+ }++ try {+ const content = fs.readFileSync(fullPath, "utf-8");+ const lines = content.split("\n");+ for (let i = 0; i < Math.min(lines.length, 50); i++) {+ for (const pattern of patterns) {+ if (lines[i].includes(pattern)) {+ const relative = path.relative(baseDir, fullPath);+ results.push(`${relative}:${i + 1} contains ${pattern}`);+ }+ }+ }+ } catch {+ // Skip files we can't read+ }+ }+ } catch {+ // Skip directories we can't read+ }+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");+ console.log("=".repeat(90));+ console.log(` Scanning: ${targetDir}\n`);++ const checks = createChecks();+ const results: ScanResult[] = [];++ for (const check of checks) {+ const found = check.scan(targetDir);+ results.push({+ category: check.category,+ check: check.name,+ severity: check.severity,+ found,+ description: check.description,+ });+ }++ // Report+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const count = r.found.length;+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";++ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);+ }++ // Summary+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);+ const clean = results.filter((r) => r.found.length === 0);++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SUMMARY");+ console.log("=".repeat(90) + "\n");++ console.log(` Critical issues: ${criticals.length}`);+ console.log(` Warnings: ${warnings.length}`);+ console.log(` Info items: ${infos.length}`);+ console.log(` Clean checks: ${clean.length}/${results.length}`);++ if (criticals.length > 0) {+ console.log("\n ACTION REQUIRED (Critical):");+ for (const c of criticals) {+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);+ console.log(` ${c.description}`);+ }+ }++ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);+ if (totalIssues === 0) {+ console.log("\n Project is in a clean state. No issues found.\n");+ } else {+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);+ }+}++run();diff --git a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdnew file mode 100644index 0000000..0e8cb86--- /dev/null+++ b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md@@ -0,0 +1,8 @@+# كود المحاضرة 12++استخدم هذا المجلد لأمثلة عن:++- شرائح المعيار (benchmark slices)+- مهام التنظيف+- أمثلة تقليل الإنتروبيا+- عمليات harness قابلة للتكرارdiff --git a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdnew file mode 100644index 0000000..eb56c5c--- /dev/null+++ b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -0,0 +1,186 @@+[中文版本 →](../../../zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)++> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)+> مشروع عملي: [Project 06. Complete harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# المحاضرة 12. اترك handoff نظيفًا في نهاية كل جلسة++## ما المشكلة التي تحلها هذه المحاضرة؟++يعمل agent طوال فترة بعد الظهر، يُعدّل 20 ملفًا، يُرسل الكود، تنتهي الجلسة. تبدأ جلسة agent التالية وتكتشف فورًا: البناء (build) مكسور، الاختبارات حمراء، ملفات التصحيح المؤقتة في كل مكان، قائمة الميزات لم تُحدَّث، والتقدم غير واضح تمامًا. تقضي الجلسة الجديدة أول 30 دقيقة فقط في محاولة معرفة "ماذا فعلت الجلسة السابقة فعليًا."++تشدد كل من OpenAI و Anthropic بوضوح: **الموثوقية طويلة المدى تعتمد على الانضباط التشغيلي، وليس فقط نجاح التشغيل الفردي.** جودة الحالة عند خروج الجلسة تحدد مباشرة كفاءة الجلسة التالية. فكر في الأمر كممارسات Git الجيدة — كل التزام يجب أن يكون تغييرًا ذريًا قابلًا لل编译، وليس كومة من الكود غير المكتمل.++## المفاهيم الأساسية++- **الحالة النظيفة**: يستوفي النظام خمسة شروط عند انتهاء الجلسة — البناء يجتاز، الاختبارات تجتاز، التقدم مُسجَّل، لا قطع أثرية قديمة، مسار البدء متاح. غياب أي واحد يعني أن الجلسة ليست "منتهية."+- **سلامة الجلسة**: مشابهة لمعاملات قاعدة البيانات — إما الالتزام الكامل وترك حالة نظيفة، أو التراجع إلى آخر حالة متسقة. لا يوجد حل وسط.+- **مستند الجودة**: قطعة أثرية نشطة تسجل باستمرار تقييمات الجودة لكل وحدة. ليس تقييمًا لمرة واحدة، بل متتبع يُظهر ما إذا كانت قاعدة الكود تزداد قوة أم ضعفًا بمرور الوقت.+- **حلقة التنظيف**: جلسة صيانة منتظمة تهدف إلى تقليل الإنتروبيا في قاعدة الكود بشكل منهجي. ليس إصلاحًا طارئًا، بل عمليات روتينية.+- **تبسيط harness**: مع تحسن قدرات النماذج، أزل بشكل دوري مكونات harness التي لم تعد ضرورية. قيد أساسي اليوم قد يكون عبئًا غير ضروري خلال ثلاثة أشهر.+- **التنظيف المتساوي القوة (Idempotent)**: عمليات التنظيف تُنتج نفس النتيجة بغض النظر عن عدد مرات تشغيلها. يضمن بقاء التنظيف آمنًا حتى في سيناريوهات إعادة المحاولة بعد الفشل.++## الأبعاد الخمسة للحالة النظيفة++```mermaid+flowchart LR+ Work["Feature work complete"] --> Build{"Build passes?"}+ Build -->|yes| Test{"Tests pass?"}+ Build -->|no| Fix["Fix before exit"]+ Test -->|yes| Record["Update feature list + progress"]+ Test -->|no| Fix+ Record --> Cleanup["Remove temp artifacts / debug code"]+ Cleanup --> Startup{"Standard startup path works?"}+ Startup -->|yes| Clean["Clean handoff"]+ Startup -->|no| Fix+ Fix --> Build+```++```mermaid+flowchart LR+ Dirty["Session ends with<br/>red tests / temp files / no progress update"] --> Diagnose["Next session first has to<br/>figure out what happened"]+ Diagnose --> Fragile["New work starts on a messy repo"]+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]+ More --> Dirty++ Clean["Session ends with<br/>green tests / updated progress / temp files removed"] --> Fast["Next session can start coding immediately"]+ Fast --> Stable["No need to rescue the repo first"]+ Stable --> Clean+```++## لماذا يحدث هذا++### نمو الإنتروبيا هو الحالة الافتراضية++تخبرنا قوانين ليهمان لتطور البرمجيات: الأنظمة التي تخضع لتغيير مستمر ستزداد حتمًا في التعقيد ما لم تُدار بشكل نشط. هذا صحيح بشكل خاص لوكلاء البرمجة بالذكاء الاصطناعي — كل جلسة تُدخل تغييرات، وبدون تنظيف عند الخروج، يتراكم الدين الفني بشكل أسي.++البيانات الحقيقية دالة. مشروع طُوّر باستخدام الوكلاء لمدة 12 أسبوعًا، بدون استراتيجية تنظيف:++- الأسبوع 1: معدل اجتياز البناء 100%، معدل اجتياز الاختبارات 100%، بدء الجلسة الجديدة 5 دقائق+- الأسبوع 4: البناء 95%، الاختبارات 92%، البدء 15 دقيقة+- الأسبوع 8: البناء 82%، الاختبارات 78%، البدء 35 دقيقة+- الأسبوع 12: البناء 68%، الاختبارات 61%، البدء 60+ دقيقة++نفس المشروع مع استراتيجية تنظيف:++- الأسبوع 1: 100%، 100%، 5 دقائق+- الأسبوع 12: 97%، 95%، 9 دقائق++بعد 12 أسبوعًا: معدل اجتياز البناء يختلف بنسبة 29 نقطة مئوية، وقت بدء الجلسة الجديدة يختلف بنسبة 85%. هذا ليس نظريًا — إنه فرق مُلاحظ.++### الأبعاد الخمسة للحالة النظيفة++الحالة النظيفة ليست مجرد "الكود يُبنى." إنها خمسة أبعاد تُقيَّم معًا:++**بُعد البناء**: هل يُبنى الكود بدون أخطاء؟ هذا هو الأساسي — لا ينبغي للجلسة التالية أن تصلح أخطاء البناء أولاً.++**بُعد الاختبار**: هل تجتاز جميع الاختبارات؟ بما فيها الاختبارات التي وُجدت قبل الجلسة — الجلسة مسؤولة عن عدم كسر الوظائف الموجودة. وينبغي التحقق في CI، وليس فقط "يعمل على جهازي."++**بُعد التقدم**: هل التقدم الحالي مُسجَّل في قطعة أثرية قابلة للقراءة آليًا؟ المهام الفرعية المكتملة مع معايير اجتيازها، المهام الفرعية قيد التقدم لكن غير المكتملة مع حالتها الحالية، المهام الفرعية التي لم تبدأ بعد. سجلات التقدم الجيدة تقلل 60-80% من وقت تشخيص بدء الجلسة.++**بُعد القطع الأثرية**: هل توجد قطع أثرية مؤقتة قديمة أو غامضة؟ سجلات التصحيح، الملفات المؤقتة، الكود المُعلَّق، علامات TODO — كل هذه تزيد العبء المعرفي للجلسة التالية.++**بُعد البدء**: هل مسار البدء القياسي متاح؟ هل يمكن للجلسة التالية بدء العمل بدون تدخل يدوي؟ تهيئة البيئة، تحميل قاعدة الكود، اكتساب السياق، اختيار المهام — هذه المسارات يجب ألا تكون مكسورة.++### "التنظيف لاحقًا" يعني عدم التنظيف أبدًا++الفخ الذهني الأكثر شيوعًا هو "لا وقت للتنظيف في هذه الجلسة، سأفعل ذلك في المرة القادمة." لكن جلسة agent التالية لا تعرف ما تركته وراءك — ترى فوضى من الكود وحالة غير مؤكدة. ستقضي وقتًا كبيرًا في استنتاج "أي أجزاء من هذا الكود مقصودة وأيها مؤقتة."++ما هو أسوأ، كل جلسة لها أهداف مهامها الخاصة. الجلسة الجديدة موجودة للقيام بعمل جديد، وليس لتنظيف فوضى الجلسة السابقة. ستتجاهل الفوضى وتبدأ عملاً جديدًا فوقها، مُدخلة فوضى أكثر فوق الفوضى. هذه حلقة التغذية الراجعة الإيجابية للإنتروبيا.++## كيف تفعل ذلك بشكل صحيح++### 1. الحالة النظيفة كمتطلب للإكمال++حدد صراحةً في harness: **اكتمال الجلسة = المهمة تجتاز التحقق وفحص الحالة النظيفة يجتاز.** غياب أي منهما يعني أن الجلسة ليست مكتملة. اكتب في CLAUDE.md:++```+## Session Exit Checklist+- [ ] Build passes (npm run build)+- [ ] All tests pass (npm test)+- [ ] Feature list updated+- [ ] No debug code remaining (console.log, debugger, TODO)+- [ ] Standard startup path available (npm run dev)+```++### 2. استراتيجية التنظيف ذات الوضع المزدوج++اجمع بين وضعي تنظيف:++**التنظيف الفوري (في نهاية كل جلسة)**: تنظيف القطع الأثرية المؤقتة المُنشأة خلال الجلسة، تحديث حالة قائمة الميزات، التأكد من اجتياز البناء والاختبارات. هذا تنظيف "عد المرجع."++**التنظيف الدوري (أسبوعي)**: فحص كامل للنظام — معالجة المشاكل الهيكلية المتراكمة، تحديث مستندات الجودة، تشغيل اختبارات قياسية لاكتشاف الانحراف. هذا تنظيف "التتبع."++### 3. حافظ على مستند جودة++مستند الجودة هو قطعة أثرية نشطة تسجل باستمرار درجات لكل وحدة:++```markdown+# Quality Document++## User Authentication Module (Quality: A)+- Verification passing: Yes+- Agent understandable: Yes+- Test stability: Stable+- Architecture boundaries: Compliant+- Code conventions: Followed++## Payment Module (Quality: C)+- Verification passing: Partial (payment callback untested)+- Agent understandable: Difficult (logic spread across 3 files)+- Test stability: Unstable (2 flaky tests)+- Architecture boundaries: Violations present+- Code conventions: Partially followed+```++الجلسات الجديدة تقرأ هذا المستند وتعرف فورًا أين تعطي الأولوية. أصلح الوحدة ذات الدرجة الأدنى أولاً.++### 4. بسّط harness بشكل دوري++رؤية مهمة من Anthropic: **كل مكون من harness موجود لأن النموذج لا يستطيع فعل شيء بشكل موثوق بمفرده. لكن مع تحسن النماذج، تصبح هذه الافتراضات قديمة.** قيد كان أساسيًا قبل ثلاثة أشهر قد يكون عبئًا غير ضروري اليوم.++الممارسة الموصى بها: كل شهر، اختر مكون harness واحد، عطّله مؤقتًا، وشغّل مهام قياسية. إذا لم تتراجع النتائج، أزله بشكل دائم. إذا تراجعت، استعده أو استبدله ببديل أخف.++### 5. عمليات التنظيف يجب أن تكون متساوية القوة (Idempotent)++يجب أن تكون نصوص التنظيف آمنة للتشغيل المتكرر:++```bash+# Idempotent cleanup operations+rm -f /tmp/debug-*.log # -f ensures no error when files don't exist+git checkout -- .env.local # Restore to known state+npm run test # Verify cleanup didn't break anything+```++## حالة من العالم الحقيقي++تطبيق Electron طُوّر باستخدام الوكلاء على مدار 12 أسبوعًا، مقارنة نهجين:++**بدون استراتيجية تنظيف** (المجموعة الضابطة): الأسبوع 12، معدل اجتياز البناء 68%، معدل اجتياز الاختبارات 61%، بدء الجلسة الجديدة 60+ دقيقة، قطع أثرية قديمة 103.++**مع استراتيجية تنظيف** (المجموعة التجريبية): فحص حالة نظيفة كامل في نهاية كل جلسة + حلقة تنظيف أسبوعية. الأسبوع 12، معدل اجتياز البناء 97%، معدل اجتياز الاختبارات 95%، بدء الجلسة الجديدة 9 دقائق، قطع أثرية قديمة 11.++بنهاية الأسبوع 12، معدل اجتياز البناء للمجموعة التجريبية أعلى بـ 29 نقطة مئوية، معدل اجتياز الاختبارات أعلى بـ 34 نقطة مئوية، ووقت بدء الجلسة الجديدة أقل بنسبة 85%.++## الخلاصات الأساسية++- **الحالة النظيفة شرط ضروري لاكتمال الجلسة** — ليست تنظيفًا اختياريًا، بل جزء من "تعريف الانتهاء."+- **جميع الأبعاد الخمسة مطلوبة** — البناء، الاختبارات، التقدم، القطع الأثرية، البدء — كل منها يجب فحصه صراحةً.+- **مستندات الجودة تجعل صحة قاعدة الكود قابلة للتتبع** — لا يمكنك إصلاح إلا ما تعرف أنه يتراجع.+- **بسّط harness بشكل دوري** — مع تحسن قدرات النماذج، أزل القيود التي لم تعد ضرورية.+- **"التنظيف لاحقًا" يساوي عدم التنظيف أبدًا** — نمو الإنتروبيا هو الافتراضي؛ فقط التنظيف النشط يُبطئه.++## قراءات إضافية++- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — مبادئ منهجية لنظافة الكود+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — القابلية للتكرار كمتطلب تصميم أساسي لـ harness+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — الدور الحاسم لعمليات خروج الجلسة النظيفة للموثوقية طويلة المدى+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — قوانين تطور البرمجيات تثبت أن تعقيد النظام ينمو حتمًا بدون صيانة نشطة++## تمارين++1. **قائمة فحص الحالة النظيفة**: صمم قائمة فحص خروج الجلسة لقاعدة الكود الخاصة بك تغطي جميع الأبعاد الخمسة. طبّقها عبر 5 جلسات متتالية وسجّل الانتهاكات لكل بُعد.++2. **مقارنة قياسية**: استخدم مجموعة مهام ثابتة مع نوعين من harness (مع/بدون متطلبات الحالة النظيفة). قارن معدل الإكمال وعدد إعادة المحاولات ومعدل تسرب العيوب.++3. **ممارسة تبسيط harness**: اختر مكون harness واحد، عطّله مؤقتًا، وشغّل مهام قياسية. قارن النتائج مع وبدونه. قرر ما إذا كنت ستبقيه أو تزيله أو تستبدله.diff --git a/docs/ar/projects/index.md b/docs/ar/projects/index.mdnew file mode 100644index 0000000..72f7ae0--- /dev/null+++ b/docs/ar/projects/index.md@@ -0,0 +1,23 @@+# مرحبًا بك في المشاريع++هذا هو القسم العملي من Learn Harness Engineering. قراءة المحاضرات وحدها لا تكفي؛ عليك بناء البيئات بنفسك ومراقبة كيف يتصرف Codex أو Claude Code أو غيرهما من وكلاء الذكاء الاصطناعي تحت قواعد مختلفة.++## نظرة عامة على المشاريع++يضم هذا المساق 6 مشاريع عملية متدرجة تعلمك كيف تبني بيئة عمل وكيلية موثوقة من الصفر:++1. **Prompt فقط مقابل القواعد أولًا**: قارن أداء الوكيل عند استخدام prompt فقط مقابل harness أساسي.+2. **Workspace قابل للقراءة من الوكيل**: تعلم كيف تنظم المستودع ليكون مناسبًا للذكاء الاصطناعي، وكيف تنشئ آليات handoff.+3. **استمرارية متعددة الجلسات**: صمم ملفات حالة وسكربتات تهيئة حتى يستطيع الوكيل استئناف العمل بسلاسة بين الجلسات.+4. **Feedback في runtime والتحكم في النطاق**: أدخل أدوات تسمح للوكيل باختبار كوده وتصحيح الأخطاء أثناء التنفيذ.+5. **التحقق الذاتي وفصل الأدوار**: ابن آلية مراجعة مستقلة لمنع الهلوسة وإعلان النجاح المبكر.+6. **Harness كامل (Capstone)**: اجمع بيئة عمل وكيلية نهائية قابلة للملاحظة وتعمل end-to-end.++## كيفية المتابعة++عادة يحتوي كل مجلد مشروع على:+- `starter/`: مساحة العمل التي تبدأ منها.+- `solution/`: تنفيذ مرجعي إذا علقت.+- تعليمات مهمة توضح الخلفية والأهداف المحددة.++استخدم AI Coding Agent المفضل لديك، مثل Claude Code أو Cursor أو Trae، لإكمال المهام داخل مجلد `starter/`.diff --git a/docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ar/projects/project-01-baseline-vs-minimal-harness/index.mdnew file mode 100644index 0000000..e1aac95--- /dev/null+++ b/docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-01-baseline-vs-minimal-harness/)++> محاضرات مرتبطة: [المحاضرة 01. النماذج القوية لا تعني تنفيذًا موثوقًا](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [المحاضرة 02. ما معنى harness فعليًا](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)+> ملفات القوالب: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/resources/templates/)++# المشروع 01. Prompt فقط مقابل القواعد أولًا: ما حجم الفرق؟++## ما الذي ستفعله++ابنِ هيكلًا بسيطًا لتطبيق معرفة باستخدام Electron: نافذة فيها قائمة مستندات على اليسار، ولوحة Q&A على اليمين، ومجلد بيانات محلي. المهمة نفسها ليست معقدة. المعقد هو كيف تجعل الوكيل يكملها.++ستنفذها مرتين. المرة الأولى: prompt فقط، دون تحضير. المرة الثانية: مع وضع `AGENTS.md` و `init.sh` و `feature_list.json` مسبقًا في المستودع. ثم قارن.++جوهر هذا المشروع ليس كتابة الكود، بل قياس الفرق بين "قضاء 15 دقيقة في تحضير القواعد أولًا" و"ترك الوكيل يعمل مباشرة".++## الأدوات++- Claude Code أو Codex (اختر واحدًا واستخدمه في التشغيلين)+- Git (إدارة الفروع والمقارنة)+- Node.js + Electron (حزمة المشروع)+- مؤقت (لتسجيل مدة كل تشغيل)++## آلية harness++Harness بسيط: `AGENTS.md` + `init.sh` + `feature_list.json`diff --git a/docs/ar/projects/project-02-agent-readable-workspace/index.md b/docs/ar/projects/project-02-agent-readable-workspace/index.mdnew file mode 100644index 0000000..08afcdb--- /dev/null+++ b/docs/ar/projects/project-02-agent-readable-workspace/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-02-agent-readable-workspace/)++> محاضرات مرتبطة: [المحاضرة 03. اجعل المستودع مصدر الحقيقة الوحيد](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [المحاضرة 04. قسّم التعليمات عبر ملفات](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+> ملفات القوالب: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/resources/templates/)++# المشروع 02. اجعل المشروع قابلًا للقراءة واستأنف من حيث توقفت++## ما الذي ستفعله++أضف "قابلية القراءة" إلى المستودع حتى يستطيع وكيل جديد فهم بنية المشروع بسرعة، ومعرفة التقدم الحالي، واستئناف العمل. تحديدًا: نفذ استيراد المستندات، وعرض تفاصيل المستند، والحفظ المحلي، عبر جلستين.++ستنفذه مرتين: الأولى دون مساعدة، والثانية مع وضع `ARCHITECTURE.md` و `PRODUCT.md` و `session-handoff.md` مسبقًا في المستودع.++## الأدوات++- Claude Code أو Codex+- Git+- Node.js + Electron++## آلية harness++Workspace قابل للقراءة من الوكيل + ملفات حالة دائمةdiff --git a/docs/ar/projects/project-03-multi-session-continuity/index.md b/docs/ar/projects/project-03-multi-session-continuity/index.mdnew file mode 100644index 0000000..6257bc7--- /dev/null+++ b/docs/ar/projects/project-03-multi-session-continuity/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-03-multi-session-continuity/)++> محاضرات مرتبطة: [المحاضرة 05. حافظ على السياق حيًا عبر الجلسات](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [المحاضرة 06. هيئ قبل كل جلسة وكيل](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+> ملفات القوالب: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/resources/templates/)++# المشروع 03. أبقِ الوكيل يعمل بعد إعادة تشغيل الجلسات++## ما الذي ستفعله++أضف تحكمًا في النطاق وبوابات تحقق إلى الوكيل. نفذ تقسيم المستندات، واستخراج metadata، وعرض تقدم الفهرسة، وتدفق Q&A قائم على الاستشهادات. استخدم `feature_list.json` لتتبع حالة الميزات: ميزة واحدة كل مرة، ولا تضع `pass` دون دليل تحقق.++ستنفذه مرتين: الأولى دون قيود، والثانية مع تطبيق صارم.++## الأدوات++- Claude Code أو Codex+- Git+- Node.js + Electron++## آلية harness++سجل تقدم + handoff الجلسة + استمرارية متعددة الجلساتdiff --git a/docs/ar/projects/project-04-incremental-indexing/index.md b/docs/ar/projects/project-04-incremental-indexing/index.mdnew file mode 100644index 0000000..5682447--- /dev/null+++ b/docs/ar/projects/project-04-incremental-indexing/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-04-incremental-indexing/)++> محاضرات مرتبطة: [المحاضرة 07. ارسم حدود مهمة واضحة للوكلاء](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [المحاضرة 08. استخدم قوائم الميزات لتقييد ما يفعله الوكيل](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+> ملفات القوالب: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/resources/templates/)++# المشروع 04. استخدم feedback في runtime لتصحيح سلوك الوكيل++## ما الذي ستفعله++أضف قابلية ملاحظة runtime، مثل سجلات التشغيل، وسجلات الاستيراد/الفهرسة، وحالات الأخطاء، بالإضافة إلى قيود معمارية لمنع اختراق الحدود بين الطبقات. ازرع خطأ runtime ليصلحه الوكيل.++ستنفذه مرتين: الأولى دون سجلات أو قيود، والثانية بالأدوات والقواعد المناسبة.++## الأدوات++- Claude Code أو Codex+- Git+- Node.js + Electron++## آلية harness++Feedback في runtime + تحكم في النطاق + فهرسة تدريجيةdiff --git a/docs/ar/projects/project-05-grounded-qa-verification/index.md b/docs/ar/projects/project-05-grounded-qa-verification/index.mdnew file mode 100644index 0000000..74d618a--- /dev/null+++ b/docs/ar/projects/project-05-grounded-qa-verification/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-05-grounded-qa-verification/)++> محاضرات مرتبطة: [المحاضرة 09. امنع الوكلاء من إعلان النجاح مبكرًا](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [المحاضرة 10. التشغيل الكامل للـ pipeline فقط يُعد تحققًا حقيقيًا](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+> ملفات القوالب: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/resources/templates/)++# المشروع 05. اجعل الوكيل يتحقق من عمله++## ما الذي ستفعله++نفذ فصل الأدوار: generator ينفذ، و evaluator يراجع، وربما planner. شغّل ثلاث مرات لقياس أثر كل دور مضاف.++اختر ترقية جوهرية لميزة، مثل محادثة متعددة الأدوار، أو إعادة تصميم لوحة الاستشهادات، أو فلترة المستندات، وحافظ عليها ثابتة في كل التشغيلات.++## الأدوات++- Claude Code أو Codex+- Git+- Node.js + Electron++## آلية harness++تحقق ذاتي + Q&A مستند إلى أدلة + إكمال مبني على الدليلdiff --git a/docs/ar/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ar/projects/project-06-runtime-observability-and-debugging/index.mdnew file mode 100644index 0000000..3df3aac--- /dev/null+++ b/docs/ar/projects/project-06-runtime-observability-and-debugging/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-06-runtime-observability-and-debugging/)++> محاضرات مرتبطة: [المحاضرة 11. اجعل runtime الخاص بالوكيل قابلًا للملاحظة](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [المحاضرة 12. Handoff نظيف في نهاية كل جلسة](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+> ملفات القوالب: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ar/resources/templates/)++# المشروع 06. ابنِ harness كاملًا للوكيل (Capstone)++## ما الذي ستفعله++هذا هو مشروع التخرج. اجمع كل ما تعلمته في المشاريع الخمسة الأولى، وشغّل benchmark كاملًا، ثم نفذ جولة تنظيف للتحقق من أن الجودة قابلة للصيانة.++استخدم مجموعة مهام ثابتة متعددة الميزات تغطي شريحة منتج كاملة: استيراد المستندات، الفهرسة، Q&A مع الاستشهادات، قابلية ملاحظة runtime، وحالة مستودع قابلة للقراءة والاستئناف. ابدأ بتشغيل baseline مع harness ضعيف، ثم شغّل أقوى harness لديك، ثم نظف وأعد التشغيل. أخيرًا، نفذ تجربة ablation للـ harness: أزل مكونًا واحدًا كل مرة وانظر أيها مهم فعليًا.++## الأدوات++- Claude Code أو Codex+- Git+- Node.js + Electron+- قالب وثيقة جودة+- rubric للمقيّم+- كل مكونات harness المتراكمة من المشاريع الخمسة الأولى++## آلية harness++Harness كامل: كل الآليات + قابلية الملاحظة + دراسة ablationdiff --git a/docs/ar/resources/index.md b/docs/ar/resources/index.mdnew file mode 100644index 0000000..2764cd7--- /dev/null+++ b/docs/ar/resources/index.md@@ -0,0 +1,50 @@+# مكتبة الموارد العربية++يحول هذا المجلد طرق المساق إلى قوالب جاهزة للنسخ ومراجع مختصرة يمكنك استخدامها في مستودع حقيقي.++## متى تستخدمها++ابدأ هنا عندما تريد من Codex أو Claude Code أو وكيل برمجة آخر أن يعمل عبر عدة جلسات دون إعادة استنتاج الإعداد، والحالة، والنطاق في كل مرة.++تكون مفيدة خصوصًا عندما:++- يمتد العمل عبر عدة جلسات+- تكون الميزات كثيرة ويسهل تركها نصف مكتملة+- يميل الوكلاء إلى إعلان النجاح مبكرًا+- يعاد اكتشاف خطوات التشغيل في كل مرة++## ابدأ من هنا++لإعداد بسيط، ابدأ بـ:++- تعليمات الجذر: [`templates/AGENTS.md`](./templates/AGENTS.md) أو [`templates/CLAUDE.md`](./templates/CLAUDE.md)+- حالة الميزات: [`templates/feature_list.json`](./templates/feature_list.json)+- سجل التقدم: [`templates/claude-progress.md`](./templates/claude-progress.md)+- مرجع سكربت bootstrap: `docs/ar/resources/templates/init.sh`++ثم أضف:++- handoff الجلسة: [`templates/session-handoff.md`](./templates/session-handoff.md)+- قائمة تحقق للخروج النظيف: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)+- rubric للمقيّم: [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)++إذا أردت بنية مستودع أكثر اكتمالًا على نمط OpenAI من مقالة "Harness engineering"، استخدم الحزمة المتقدمة:++- [`openai-advanced/index.md`](./openai-advanced/index.md)++## بنية المكتبة++- [`templates/`](./templates/index.md): قوالب لنسخها إلى مستودع حقيقي+- [`reference/`](./reference/index.md): ملاحظات منهجية، تدفق بدء التشغيل، وخرائط أنماط الفشل+- [`openai-advanced/`](./openai-advanced/index.md): هيكل مستودع متقدم، وثائق system-of-record، وقوالب حوكمة agent-first++## الحزمة البسيطة الموصى بها++- `AGENTS.md` أو `CLAUDE.md`+- `feature_list.json`+- `claude-progress.md`+- `init.sh`++هذه الملفات الأربعة كافية لجعل معظم workflows الخاصة بالوكلاء أكثر استقرارًا بشكل واضح.++عندما ينمو المستودع إلى نظام طويل الأمد بعدة نطاقات، وخطط نشطة، وتقييم جودة، وسياسات موثوقية، انتقل إلى حزمة [`openai-advanced/`](./openai-advanced/index.md) بدلًا من مد الحزمة البسيطة أكثر من اللازم.diff --git a/docs/ar/resources/openai-advanced/index.md b/docs/ar/resources/openai-advanced/index.mdnew file mode 100644index 0000000..95de7d0--- /dev/null+++ b/docs/ar/resources/openai-advanced/index.md@@ -0,0 +1,35 @@+# حزمة OpenAI المتقدمة++تحتوي هذه المجلد على شكل المستودع الأكثر توجيهاً الموصوف في+مقال OpenAI "Harness engineering: leveraging Codex in an agent-first world"+كملفات بداية جاهزة للنسخ.++استخدم هذه الحزمة عندما لا يكفي harness البسيط بعد ومستودعك+يحتاج الآن إلى:++- ملف `AGENTS.md` قصير بنمط التوجيه+- وثائق نظام السجل الدائم داخل المستودع+- خطط تنفيذ نشطة ومكتملة+- ملفات سياسة صريحة للمنتج والموثوقية والأمان والواجهة الأمامية+- تسجيل الجودة حسب مجال المنتج والطبقة المعمارية+- مجلدات مراجع صديقة للنماذج+- إجراءات تشغيل قياسية للهندسة المعمارية والتقاط المعرفة والتحقق في وقت التشغيل++## كيفية التبني++1. ابدأ بالحزمة البسيطة إذا كان مستودعك لا يزال صغيراً.+2. انسخ الملفات في [`repo-template/`](./repo-template/index.md) إلى+ مستودعك الخاص عندما تحتاج هيكلاً أقوى.+3. أبقِ `AGENTS.md` قصيراً. تعامل معه كموّجه إلى الوثائق الأعمق، لا كموسوعة.+4. حدّث وثائق الجودة والموثوقية والخطط كجزء من العمل العادي، لا كيوم تنظيف منفصل.+5. أبقِ المنتجات المُنشأة والمراجع الخارجية صريحة حتى يتمكن الوكلاء من إيجادها بدون الاعتماد على سجل المحادثة.++## مبادئ التصميم++- نقطة دخول قصيرة، وثائق أعمق مرتبطة+- المستودع كسجل للنظام+- الفحوصات الميكانيكية أفضل من القواعد المحفوظة+- الخطط وتاريخ الجودة بجانب الكود+- التنظيف والتبسيط مسؤوليات من الدرجة الأولى++هذه الحزمة متعمدة التوجيه، لكن يجب تكييفها لمشروعك بدلاً من نسخها بشكل أعمى.diff --git a/docs/ar/resources/openai-advanced/repo-template/AGENTS.md b/docs/ar/resources/openai-advanced/repo-template/AGENTS.mdnew file mode 100644index 0000000..ceda43e--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/AGENTS.md@@ -0,0 +1,57 @@+# AGENTS.md++هذا المستودع مُحسَّن للعمل طويل الأمد لوكلاء البرمجة. أبقِ هذا الملف+قصيرًا. استخدمه كطبقة توجيه نحو وثائق السجل المرجعي للنظام، وليس كملف+تعليمات ضخم.++## سير عمل بدء التشغيل++قبل تغيير الكود:++1. تأكد من جذر المستودع باستخدام `pwd`.+2. اقرأ `ARCHITECTURE.md` للاطلاع على خريطة النظام الحالية وقواعد التبعيات الثابتة.+3. اقرأ `docs/QUALITY_SCORE.md` لمعرفة المجالات أو الطبقات الأضعف.+4. اقرأ `docs/PLANS.md`، ثم افتح الخطة النشطة التي تعمل وفقًا لها.+5. اقرأ مواصفات المنتج ذات الصلة في `docs/product-specs/`.+6. شغّل مسار الإعداد والتحقق القياسي لهذا المستودع.+7. إذا كان التحقق الأساسي يفشل، أصلح الأساس قبل إضافة نطاق جديد.++## خريطة التوجيه++- `ARCHITECTURE.md`: خريطة المجالات، نموذج الطبقات، قواعد التبعيات+- `docs/design-docs/index.md`: قرارات التصميم والمعتقدات الأساسية+- `docs/product-specs/index.md`: سلوكيات المنتج الحالية وأهداف القبول+- `docs/PLANS.md`: دورة حياة الخطط وسياسة خطط التنفيذ+- `docs/QUALITY_SCORE.md`: صحة مجالات المنتج والطبقات+- `docs/RELIABILITY.md`: إشارات التشغيل، معايير الأداء، وتوقعات إعادة التشغيل+- `docs/SECURITY.md`: الأسرار، الحماية الرملية، البيانات، وقواعد الإجراءات الخارجية+- `docs/FRONTEND.md`: قيود واجهة المستخدم، قواعد نظام التصميم، وفحوصات إمكانية الوصول++## عقد العمل++- اعمل وفق خطة محددة أو شريحة ميزة واحدة في كل مرة.+- لا تعتبر العمل منتهيًا من فحص الكود فقط؛ الأدلة القابلة للتنفيذ مطلوبة.+- إذا غيّرت سلوكًا، حدِّث وثائق المنتج أو الخطة أو الموثوقية المطابقة في نفس الجلسة.+- إذا لاحظت ملاحظات مراجعة متكررة،حوّلها إلى قاعدة آلية أو فحص أو أداة تنسيق بدلاً من إعادة شرحها في المحادثة.+- أبقِ المواد المُولَّدة في `docs/generated/` والمراجع المصدرية في `docs/references/`.+- فضِّل إضافة وثائق صغيرة وحالية بدلاً من توسيع هذا الملف.++## تعريف الإنجاز++التغيير يُعتبر منتهيًا فقط عندما يكون جميع ما يلي صحيحًا:++- السلوك المستهدف مُنفَّذ+- التحقق المطلوب تم تشغيله فعلًا+- الأدلة مرتبطة من الخطة أو وثيقة الجودة ذات الصلة+- الوثائق المتأثرة لا تزال محدثة+- المستودع يمكن إعادة تشغيله بنظافة من مسار بدء التشغيل القياسي++## نهاية الجلسة++قبل إنهاء جلسة:++1. حدِّث خطة التنفيذ النشطة.+2. حدِّث `docs/QUALITY_SCORE.md` إذا تغيّر أي مجال أو طبقة بشكل ملحوظ.+3. سجّل الديون الجديدة في `docs/exec-plans/tech-debt-tracker.md` إذا أجلتها.+4. انقل الخطط المنتهية إلى `docs/exec-plans/completed/` عند الاقتضاء.+5. اترك المستودع في حالة قابلة لإعادة التشغيل مع إجراء تالٍ واضح.diff --git a/docs/ar/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/ar/resources/openai-advanced/repo-template/ARCHITECTURE.mdnew file mode 100644index 0000000..302375b--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -0,0 +1,57 @@+# ARCHITECTURE.md++هذا الملف هو الخريطة العلوية للنظام. يجب أن يظل موجزًا ويُشير إلى وثائق+أعمق عند الحاجة.++## شكل النظام++- المنتج: `[استبدل باسم المنتج]`+- سير عمل المستخدم الرئيسي: `[استبدل بسير العمل الرئيسي]`+- أسطح التشغيل: `[desktop / web / cli / services / workers]`+- مصدر الحقيقة لسلوك المنتج: `docs/product-specs/`++## خريطة المجالات++| المجال | الغرض | نقاط الدخول الرئيسية | المواصفة ذات الصلة |+|--------|---------|----------------------|--------------|+| `[domain-a]` | `[ما يملكه]` | `[modules / routes / commands]` | `[مسار المواصفة]` |+| `[domain-b]` | `[ما يملكه]` | `[modules / routes / commands]` | `[مسار المواصفة]` |++## نموذج الطبقات++استخدم نموذجًا اتجاهيًا ثابتًا حتى لا يخترع الوكلاء بنية عشوائية:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++المخاوف المشتركة يجب أن تدخل من خلال حدود موفّر أو محوّل صريحة بدلاً+من الوصول المباشر عبر الطبقات.++## قواعد التبعيات الثابتة++- الطبقات السفلية يجب ألا تعتمد على الطبقات العليا.+- واجهة المستخدم يجب ألا تتجاوز عقود التشغيل أو الخدمات.+- الوصول إلى البيانات يجب أن يتم من خلال مستودعات أو محوّلات معادلة.+- الأدوات المساعدة المشتركة يجب أن تظل عامة وألا تتراكم فيها منطق المجال.+- التبعيات الجديدة يجب تبريرها في الخطة أو وثيقة التصميم المطابقة.++## الواجهات المشتركة++| المخاوف | الحد المعتمد | ملاحظات |+|--------|-------------------|-------|+| التسجيل والتتبع | `[مسار الموفر / الأداة المساعدة]` | `[منظم فقط، بدون استخدام console عشوائي]` |+| المصادقة | `[مسار الموفر]` | `[قواعد token/session]` |+| واجهات برمجة التطبيقات الخارجية | `[مسار العميل أو الموفر]` | `[إرشادات حد السرعة / إعادة المحاولة]` |+| علامات الميزات | `[حد العلم]` | `[الملكية]` |++## النقاط الساخنة الحالية++- `[المنطقة الأصعب على الوكلاء تغييرها بأمان]`+- `[منطقة بحدود ضعيفة أو اختبارات هشة]`++## قائمة فحص التغيير++عندما تلمس كودًا يتعلق بالبنية:++1. حدِّث هذا الملف إذا تغيرت خريطة المجالات أو الحدود المسموح بها.+2. حدِّث وثيقة التصميم ذات الصلة في `docs/design-docs/` إذا تغير المنطق.+3. أضف أو حدِّث فحصًا قابلًا للتنفيذ إذا كانت القاعدة يجب تُفرض آليًا.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/ar/resources/openai-advanced/repo-template/docs/DESIGN.mdnew file mode 100644index 0000000..c1d72e9--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/DESIGN.md@@ -0,0 +1,27 @@+# DESIGN.md++هذا الملف هو نقطة دخول التصميم. أبقِه موجزًا واستخدمه للتوجيه نحو+الملفات الأكثر تفصيلًا تحت `docs/design-docs/`.++## الغرض++تسجيل قرارات تصميم المنتج والنظام الدائمة التي يجب أن تبقى بعد+محادثة واحدة أو سباق تطوير واحد أو ذاكرة مراجع واحدة.++## اقرأ هذا عندما++- تحتاج إلى فلسفة التصميم الحالية+- أنت على وشك تقديم نمط جديد+- تحتاج إلى معرفة قرارات التصميم المُستقرة مقابل تلك التي لا تزال مفتوحة++## وثائق التصميم المعتمدة++- `docs/design-docs/index.md`: فهرس الوثائق المقبولة والمقترحة والمُهمَلة+- `docs/design-docs/core-beliefs.md`: معتقدات المشروع الموجهة للوكلاء أولًا++## قواعد التصميم++- أبقِ وثائق التصميم صغيرة وحالية.+- فضِّل وثيقة واحدة لكل مجال قرار.+- اربط وثائق التصميم من الخطط والمواصفات عندما يعتمد التغيير عليها.+- إذا أصبحت قاعدة تصميم حرجة تشغيليًا،رتقها إلى فحص آلي أو حدِّث `ARCHITECTURE.md`.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/ar/resources/openai-advanced/repo-template/docs/FRONTEND.mdnew file mode 100644index 0000000..b0ded40--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/FRONTEND.md@@ -0,0 +1,24 @@+# FRONTEND.md++يحدد هذا الملف توقعات واجهة الأمامية المستقرة حتى لا يخترع الوكلاء أنماط+واجهة مستخدم بشكل غير متوقع.++## مبادئ واجهة المستخدم++- حسِّن الوضوح قبل الإبداع.+- أبقِ تدفقات التفاعل قابلة للاكتشاف وقابلة لإعادة التشغيل.+- فضِّل عددًا صغيرًا من المكونات القابلة لإعادة الاستخدام على المتغيرات الفريدة.+- فحوصات إمكانية الوصول هي جزء من التحقق العادي، وليست أعمال تشطيب.++## الحواجز الوقائية++- وثِّق نظام التصميم أو مكتبة المكونات في `docs/references/`.+- سجِّل حالات واجهة المستخدم الرئيسية: فارغ، تحميل، نجاح، خطأ، إعادة محاولة.+- أبقِ النصوص وسلوك لوحة المفاتيح والتسلسل الهرمي البصري متسقة عبر التدفقات.+- عند إصلاح خطأ في واجهة المستخدم، أضف أو حدِّث خطوة التحقق المطابقة.++## توقعات التحقق++- التقط أدلة لرحلات المستخدم الحرجة.+- سجِّل خطوات التحقق في المتصفح أو وقت التشغيل في الخطة ذات الصلة.+- إذا كانت الانحدارات البصرية شائعة، قم بتوحيد فحوصات لقطات الشاشة أو DOM.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/ar/resources/openai-advanced/repo-template/docs/PLANS.mdnew file mode 100644index 0000000..533f98c--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/PLANS.md@@ -0,0 +1,34 @@+# PLANS.md++يحدد هذا الملف كيفية إنشاء خطط التنفيذ وتحديثها وإكمالها وأرشفتها.++## متى تكون الخطة مطلوبة++أنشئ خطة تنفيذ عندما يكون العمل:++- يمتد عبر أكثر من جلسة واحدة+- يغيّر أكثر من نظام فرعي واحد+- يحمل مخاطر تحقق أو طرح غير بسيطة+- يعتمد على قرارات مفتوحة يجب تسجيلها++## مواقع الخطط++- `docs/exec-plans/active/`: الخطط التي تقود العمل حاليًا+- `docs/exec-plans/completed/`: الخطط المنتهية المحفوظة لسياق الوكلاء المستقبلي+- `docs/exec-plans/tech-debt-tracker.md`: العمل المؤجل والمتابعات++## أقسام الخطة كحد أدنى++- الهدف+- النطاق وخارج النطاق+- مسار التحقق+- المخاطر والعوائق+- سجل التقدم+- القرارات المفتوحة++## قواعد التشغيل++- يجب أن تحتوي الخطة النشطة الواحدة على خطوة حالية مملوكة بوضوح.+- حدِّث الخطة مع تقدم العمل؛ لا تعاملها كنص ثابت.+- إذا غيّر قرار مسار التنفيذ، سجّله في الخطة.+- انقل الخطط المنتهية إلى `completed/` حتى يتمكن الوكلاء من اكتشاف السياق السابق.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/ar/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.mdnew file mode 100644index 0000000..97818a4--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md@@ -0,0 +1,26 @@+# PRODUCT_SENSE.md++يلتقط هذا الملف أحكام المنتج الدائمة التي لا يمكن للوكلاء استنتاجها+بشكل موثوق من الكود وحده.++## جوهر المنتج++- المستخدم الأساسي: `[استبدل]`+- المهمة المطلوب إنجازها: `[استبدل]`+- الإحباط الرئيسي المراد إزالته: `[استبدل]`+- مستوى الجودة للقبول: `[استبدل]`++## قواعد المنتج++- فضِّل الموثوقية المرئية للمستخدم على عدد الميزات.+- تعامل مع السلوك الغامض كفجوة في المواصفات، وليس كإذن للتخمين.+- إذا غيّر التنفيذ ما يراه المستخدمون أو يثقون به، حدِّث المواصفة المطابقة.+- استخدم مواصفات المنتج للتدفقات المحددة، واستخدم هذا الملف لأولويات+ المنتج المشتركة.++## أنماط الرفض++- إجراءات مدمرة مخفية+- فشل صامت بدون تغذية راجعة للمستخدم+- مصدر حقيقة غير واضح للحالة المرئية+- ميزات لا يمكن شرحها في جملة واحدةdiff --git a/docs/ar/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/ar/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.mdnew file mode 100644index 0000000..7b0a6a2--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md@@ -0,0 +1,39 @@+# QUALITY_SCORE.md++يتتبع هذا المستند ما إذا كان المستودع يزداد قوة أو ضعفًا عبر الوقت.++## مقياس الدرجات++- `A`: مُتحقَّق، مقروء، مستقر، الحدود مُطبَّقة+- `B`: يعمل مع فجوات طفيفة+- `C`: يعمل جزئيًا، ارتباك أو عدم استقرار ملحوظ+- `D`: معطل، غير آمن، أو غير واضح هيكليًا++## مجالات المنتج++| المجال | الدرجة | التحقق | قابلية قراءة الوكيل | استقرار الاختبار | الفجوات الرئيسية | آخر تحديث |+|--------|-------|-------------|-----------------|---------------|----------|-------------|+| `[domain-a]` | - | - | - | - | - | - |+| `[domain-b]` | - | - | - | - | - | - |+| `[domain-c]` | - | - | - | - | - | - |++## الطبقات المعمارية++| الطبقة | الدرجة | تطبيق الحدود | قابلية قراءة الوكيل | الفجوات الرئيسية | آخر تحديث |+|-------|-------|---------------------|-----------------|----------|-------------|+| Types | - | - | - | - | - |+| Services | - | - | - | - | - |+| Runtime | - | - | - | - | - |+| UI | - | - | - | - | - |++## لقطات المعايير++| التاريخ | متغير الهارنيس | معدل الإنجاز | إعادة المحاولات | العيوب قبل المراجعة | ملاحظات |+|------|-----------------|----------------|--------|-----------------------|------|+| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |++## سجل التبسيط++| التاريخ | المكون المُزال | النتيجة | القرار |+|------|-------------------|---------|----------|+| YYYY-MM-DD | `[component]` | `[degraded / unchanged]` | `[restore / keep removed]` |diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/ar/resources/openai-advanced/repo-template/docs/RELIABILITY.mdnew file mode 100644index 0000000..7822717--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/RELIABILITY.md@@ -0,0 +1,32 @@+# RELIABILITY.md++يحدد هذا الملف كيف يثبت النظام أنه سليم وقابل لإعادة التشغيل.++## المسارات القياسية++- الإعداد: `[command]`+- التحقق: `[command]`+- بدء التطبيق أو الخدمة: `[command]`+- التصحيح أو فحص وقت التشغيل: `[command]`++## إشارات وقت التشغيل المطلوبة++- سجلات منظمة لبدء التشغيل والتدفقات الحرجة+- فحوصات صحة الخدمات الرئيسية+- بيانات التتبع أو التوقيت للمسارات البطيئة عند التوفر+- حالات الخطأ المرئية للمستخدم للأعطال القابلة للاسترداد++## الرحلات الذهبية++- `[journey 1]`+- `[journey 2]`+- `[journey 3]`++يجب أن يكون لكل رحلة ذهبية مسار تحقق قابل للتكرار وإشارات فشل واضحة.++## قواعد الموثوقية++- لا تكتمل أي ميزة إذا لم يتمكن النظام من إعادة التشغيل بنظافة بعدها.+- يجب أن تكون أعطال وقت التشغيل قابلة للتشخيص من إشارات محلية في المستودع.+- إذا ظهر نمط فشل متكرر، أضف معيارًا أو حاجزًا وقائيًا له.+- التنظيف جزء من الموثوقية، وليس اهتمامًا منفصلًا.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/ar/resources/openai-advanced/repo-template/docs/SECURITY.mdnew file mode 100644index 0000000..1b5e980--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/SECURITY.md@@ -0,0 +1,27 @@+# SECURITY.md++يحدد هذا الملف قواعد الأمان والسلامة التي يجب ألا يخمنها الوكلاء.++## الأسرار وبيانات الاعتماد++- لا تُشفِّر الأسرار بشكل ثابت في المصدر أو الوثائق.+- وثِّق مسارات تحميل الأسرار المعتمدة هنا.+- قم بتنقيح الرموز ومفاتيح واجهة برمجة التطبيقات والبيانات الشخصية من السجلات ولقطات الشاشة.++## المدخلات غير الموثوقة++- تعامل مع المحتوى الخارجي على أنه غير موثوق حتى يتم التحقق منه.+- سجِّل حدود الجلب أو التنفيذ المسموح بها هنا.+- إذا كان هناك خطر حقن أوامر أو حقن أوامر، وثِّق الحاجز الوقائي.++## الإجراءات الخارجية++- اذكر الإجراءات التي تتطلب موافقة صريحة.+- سجِّل أي أوامر إنتاجية أو مدمرة التي يجب ألا يشغلها الوكلاء افتراضيًا.+- فضِّل سير العمل الآمن في الحماية الرملية للتصحيح والتحقق.++## قواعد التبعيات والمراجعة++- التبعيات الجديدة تحتاج تبريرًا في الخطة النشطة.+- التغييرات الحساسة أمنيًا تتطلب خطوات تحقق صريحة.+- تعليقات مراجعة الأمان المتكررة يجب أن تصبح فحوصات، وليس معرفة قبلية.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/ar/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.mdnew file mode 100644index 0000000..17796a1--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md@@ -0,0 +1,9 @@+# المعتقدات الأساسية++- المستودع هو سجل النظام المرجعي للوكلاء.+- `AGENTS.md` هو موجّه، وليس موسوعة.+- أدلة التحقق أهم من الثقة.+- مهمة واحدة محددة أفضل من العديد من المهام نصف المنتهية.+- التغذية الراجعة البشرية المتكررة يجب أن تصبح قواعد هارنيس قابلة لإعادة الاستخدام.+- التنظيف والتبسيط جزء من الشحن، وليس أفكارًا لاحقة.+- إذا لم يستطع وكيل اكتشاف حقيقة في المستودع، تعامل مع تلك الحقيقة على أنها غير متاحة تشغيليًا.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/ar/resources/openai-advanced/repo-template/docs/design-docs/index.mdnew file mode 100644index 0000000..ea41265--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/design-docs/index.md@@ -0,0 +1,21 @@+# فهرس وثائق التصميم++استخدم هذا الفهرس كخريطة قابلة للاكتشاف لتاريخ التصميم.++## مقبولة++- `core-beliefs.md`: معتقدات التشغيل الموجهة للوكلاء والمعايير الدائمة للمشروع++## مقترحة++- `[أضف مسارات وثائق التصميم الجديدة هنا]`++## مُهمَلة++- `[انقل وثائق التصميم القديمة أو المتجاوزة هنا مع روابط البدائل]`++## قواعد الصيانة++- يجب أن يكون لكل وثيقة تصميم مالك أو محفز تحديث.+- أزل الوثائق القديمة أو ضع علامة مهملة عليها بدلاً من تركها تنجرف.+- اربط خطط التنفيذ النشطة بوثائق التصميم التي تعتمد عليها.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/active/index.mdnew file mode 100644index 0000000..cd00a2d--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md@@ -0,0 +1,10 @@+# الخطط النشطة++احتفظ بملف Markdown واحد لكل خطة تنفيذ نشطة في هذا المجلد.++نمط اسم الملف المقترح:++- `YYYY-MM-DD-short-topic.md`++يجب أن تكون كل خطة نشطة حديثة بما يكفي لكي يتمكن وكيل جديد من استئناف+العمل من المستودع وحده.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.mdnew file mode 100644index 0000000..0d0aee7--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md@@ -0,0 +1,5 @@+# الخطط المكتملة++انقل الخطط المنتهية هنا بدلاً من حذفها. الخطط المكتملة جزء من+سطح ذاكرة المستودع وتساعد عمليات الوكيل اللاحقة على فهم لماذا يبدو+الكود بالشكل الحالي.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.mdnew file mode 100644index 0000000..0c3a92c--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md@@ -0,0 +1,7 @@+# متتبع الديون التقنية++استخدم هذا الملف للديون الحقيقية المعترف بها والمؤجلة عمدًا.++| التاريخ | المجال | الدين | سبب التأجيل | الخطر | المحفز التالي |+|------|------|------|--------------|------|--------------|+| YYYY-MM-DD | `[area]` | `[debt]` | `[reason]` | `[risk]` | `[when to revisit]` |diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/ar/resources/openai-advanced/repo-template/docs/generated/db-schema.mdnew file mode 100644index 0000000..7d3f81e--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/generated/db-schema.md@@ -0,0 +1,14 @@+# مخطط قاعدة البيانات++استخدم هذا المجلد للمنتجات المُولَّدة أو المشتقة التي يجب أن يتمكن الوكلاء+من فحصها دون هندسة عكسية من الكود.++## المصدر++- مُولَّد من: `[command or source path]`+- آخر تحديث: `YYYY-MM-DD`++## ملاحظات++- لا تقم بتعديل الأقسام المُولَّدة يدويًا.+- أعد توليد هذا الملف عندما يتغير المخطط الأساسي.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/ar/resources/openai-advanced/repo-template/docs/product-specs/index.mdnew file mode 100644index 0000000..8641376--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/product-specs/index.md@@ -0,0 +1,13 @@+# فهرس مواصفات المنتج++استخدم هذا المجلد لمواصفات سلوك واجهة المستخدم الحالية.++## المواصفات النشطة++- `new-user-onboarding.md`++## القواعد++- يجب أن تصف المواصفات سلوك المستخدم المرئي ومعايير القبول.+- إذا انحرف التنفيذ عن المواصفة، حدِّث أحدهما في نفس الجلسة.+- أبقِ هذا الفهرس محدثًا حتى يتمكن وكيل جديد من اكتشاف نطاق المنتج بسرعة.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/ar/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.mdnew file mode 100644index 0000000..59c9558--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md@@ -0,0 +1,26 @@+# تهيئة المستخدم الجديد++## الهدف++وصف تجربة التشغيل الأولى التي يجب أن يحصل عليها المستخدم الجديد.++## شروط الدخول++- `[الحالة قبل بدء التدفق]`++## تدفق المستخدم++1. `[الخطوة الأولى]`+2. `[الخطوة الثانية]`+3. `[الخطوة الثالثة]`++## معايير القبول++- `[النتيجة القابلة للملاحظة]`+- `[النتيجة القابلة للملاحظة]`+- `[النتيجة القابلة للملاحظة]`++## حالات الفشل++- `[خطأ قابل للاسترداد وتغذية راجعة للمستخدم]`+- `[حالة محظورة والخيار البديل]`diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/ar/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txtnew file mode 100644index 0000000..6f1c612--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt@@ -0,0 +1,9 @@+Purpose: store model-friendly reference material for the design system.++Suggested contents:+- component naming rules+- spacing and typography tokens+- state variants+- accessibility expectations++Keep this file concise and refresh it when the upstream design system changes.diff --git a/docs/ar/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/ar/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txtnew file mode 100644index 0000000..c30cc9c--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt@@ -0,0 +1,8 @@+Purpose: store a clean agent-readable extract of the deployment or packaging+rules your repository depends on.++Suggested contents:+- build entrypoints+- runtime assumptions+- environment variable expectations+- common failure signaturesdiff --git a/docs/ar/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/ar/resources/openai-advanced/repo-template/docs/references/uv-llms.txtnew file mode 100644index 0000000..f2ceba9--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/docs/references/uv-llms.txt@@ -0,0 +1,8 @@+Purpose: store a compact reference for your Python package and environment+workflow when `uv` or similar tooling matters to the repo.++Suggested contents:+- install and sync commands+- lockfile policy+- virtualenv expectations+- verification commandsdiff --git a/docs/ar/resources/openai-advanced/repo-template/index.md b/docs/ar/resources/openai-advanced/repo-template/index.mdnew file mode 100644index 0000000..578ab5f--- /dev/null+++ b/docs/ar/resources/openai-advanced/repo-template/index.md@@ -0,0 +1,24 @@+# قالب المستودع المتقدم++انسخ هذه البداية إلى مستودع حقيقي عندما تريد سطح توثيق+بنمط OpenAI موجه للوكلاء بدلاً من هارنيس بسيط فقط.++## ترتيب النسخ++1. انسخ `AGENTS.md` و `ARCHITECTURE.md` إلى جذر المستودع.+2. انسخ شجرة `docs/` بالكامل.+3. املأ `docs/PRODUCT_SENSE.md` و `docs/QUALITY_SCORE.md` و+ `docs/RELIABILITY.md` أولًا.+4. أضف أول خطة نشطة تحت `docs/exec-plans/active/`.+5. أبقِ ملفات الدخول قصيرة وجوّه التفاصيل إلى الوثائق المرتبطة.++## ما يحسّنه هذا القالب++- سياق محلي دائم داخل المستودع+- الكشف التدريجي بدلاً من ملف تعليمات واحد ضخم+- دورة حياة خطط صريحة+- تتبع الجودة عبر الوقت+- حدود مقروءة للوكلاء والبشر++تعامل مع كل ملف هنا كبداية. استبدل العناصر النائبة والأمثلة وأوامر+العينات بتفاصيل مشروعك الحقيقي قبل الاعتماد عليها.diff --git a/docs/ar/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/ar/resources/openai-advanced/sops/chrome-devtools-validation-loop.mdnew file mode 100644index 0000000..3482c41--- /dev/null+++ b/docs/ar/resources/openai-advanced/sops/chrome-devtools-validation-loop.md@@ -0,0 +1,51 @@+# إجراء التشغيل القياسي: حلقة التحقق من Chrome DevTools++استخدم هذا الإجراء عندما يعتمد عمل واجهة المستخدم على تفاعل وقت التشغيل الفعلي+ولقطات الشاشة وحالة DOM ومخرجات وحدة التحكم وهي أهم من فحص الكود وحده.++## الهدف++تحويل التحقق من واجهة المستخدم إلى حلقة تفاعل قابلة للتكرار يمكن للوكيل تشغيلها+حتى تصبح الرحلة نظيفة.++## الحلقة الأساسية++1. حدد الصفحة أو مثيل التطبيق المستهدف.+2. امسح ضوضاء وحدة التحكم القديمة.+3. التقط حالة "قبل".+4. شغّل مسار واجهة المستخدم.+5. راقب أحداث وقت التشغيل أثناء التفاعل.+6. التقط حالة "بعد".+7. طبِّق الإصلاح وأعد تشغيل التطبيق إذا لزم الأمر.+8. أعد تشغيل التحقق حتى تصبح الرحلة نظيفة.++## المدخلات المطلوبة++- أمر بدء تشغيل مستقر+- رحلة واجهة مستخدم قابلة لإعادة الإنتاج+- طريقة لالتقاط DOM أو وحدة التحكم أو لقطات الشاشة+- قاعدة لما يُحتسب "نظيفًا"++## إجراء التشغيل القياسي للتنفيذ++1. اكتب الرحلة المستهدفة في الخطة النشطة.+2. عرِّف النجاح بمصطلحات قابلة للملاحظة: نص موجود، زر مُفعَّل، خطأ اختفى،+ وحدة تحكم نظيفة، طلب ناجح.+3. التقط الحالة الأولية قبل التفاعل.+4. شغّل مسار واحد فقط في كل مرة.+5. سجِّل أحداث وقت التشغيل وتغييرات DOM والمخرجات المرئية.+6. إذا فشلت الرحلة، أصلح الطبقة المسؤولة الأصغر وأعد التشغيل.+7. أعد تشغيل نفس المسار وقارن أدلة قبل/بعد.++## معايير النظافة++- الحالة المرئية المقصودة موجودة+- الأخطاء غير المتوقعة غائبة+- ضوضاء وحدة التحكم مفهومة أو مُزالة+- إعادة تشغيل نفس المسار تعطي نفس النتيجة++## منتجات المستودع للتحديث++- خطة التنفيذ النشطة+- `docs/RELIABILITY.md` إذا أصبحت الرحلة مسارًا ذهبيًا+- مواصفة المنتج إذا تغير السلوك المرئيdiff --git a/docs/ar/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/ar/resources/openai-advanced/sops/encode-knowledge-into-repo.mdnew file mode 100644index 0000000..9b77bee--- /dev/null+++ b/docs/ar/resources/openai-advanced/sops/encode-knowledge-into-repo.md@@ -0,0 +1,45 @@+# إجراء التشغيل القياسي: ترميز المعرفة غير المرئية في المستودع++استخدم هذا الإجراء عندما لا تزال هناك معلومات سياقية مهمة في مستندات Google+أو سلاسل المحادثات أو التذاكر أو عقول الأشخاص.++## الهدف++جعل المعرفة غير المرئية للوكلاء قابلة للاكتشاف في قاعدة الكود حتى تتمكن الجلسة+الجديدة من التصرف بناءً عليها دون الاعتماد على محادثة سابقة.++## إشارات المحفز++- يستمر الوكيل في السؤال عن كيفية عمل النظام.+- يقول البشر "قررنا هذا في Slack" أو "اتبع ما قاله فلان الأسبوع الماضي."+- تشير المراجعات إلى قواعد منتج أو أمان غير مكتوبة في المستودع.+- الجلسات الجديدة تكرر عمل الاكتشاف الذي يجب أن يكون مستقرًا بالفعل.++## إجراء التشغيل القياسي للتنفيذ++1. اذكر مصادر المعرفة غير المرئية: المستندات، المحادثات، قواعد الفريق الضمنية، القرارات الشفهية.+2. لكل مصدر، اسأل: هل هذه بنية أم سلوك منتج أم سياسة أمان أم+ توقع موثوقية أم سياق خطة أم مادة مرجعية؟+3. رمِّزها في منتج المستودع المطابق:+ - البنية -> `ARCHITECTURE.md`+ - سلوك المنتج -> `docs/product-specs/`+ - منطق التصميم -> `docs/design-docs/`+ - حالة التنفيذ -> `docs/exec-plans/`+ - المراجع الخارجية المتكررة -> `docs/references/`+ - توقعات الجودة أو الموثوقية -> `docs/QUALITY_SCORE.md` أو `docs/RELIABILITY.md`+4. استبدل العبارات الغامضة بصياغة مفيدة تشغيليًا.+5. أزل أو أهمل النسخ القديمة حتى يحتفظ المستودع بحقيقة واحدة قابلة للاكتشاف.++## قواعد الترميز الجيد++- اكتب من أجل قابلية الاكتشاف، وليس من أجل الاكتمال الأدبي.+- فضِّل المستندات القصيرة بأسماء ملفات واضحة.+- اربط المنتجات ذات الصلة ببعضها.+- خزِّن القواعد الدائمة، وليس نصوص الاجتماعات.+- حدِّث المستودع في نفس الجلسة التي يُتخذ فيها القرار.++## تعريف الإنجاز++- يمكن لوكيل جديد اكتشاف القاعدة ذات الصلة دون سؤال بشري.+- نفس الحقيقة غير مبعثرة عبر ملفات متعددة متناقضة.+- المنتج الجديد يعيش بالقرب من الكود أو سير العمل الذي يحكمه.diff --git a/docs/ar/resources/openai-advanced/sops/index.md b/docs/ar/resources/openai-advanced/sops/index.mdnew file mode 100644index 0000000..770336e--- /dev/null+++ b/docs/ar/resources/openai-advanced/sops/index.md@@ -0,0 +1,25 @@+# إجراءات التشغيل القياسية المتقدمة من OpenAI++تترجم إجراءات التشغيل القياسية هذه أنماط التشغيل من المقالة إلى كتيبات تنفيذ+محددة يمكنك اتباعها أو تكييفها.++## إجراءات التشغيل القياسية المضمنة++- [`layered-domain-architecture.md`](./layered-domain-architecture.md):+ إنشاء طبقات صريحة وحدود مشتركة+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):+ نقل المعرفة غير المرئية من المحادثات والمستندات والذاكرة إلى ملفات محلية في المستودع+- [`observability-feedback-loop.md`](./observability-feedback-loop.md):+ إعطاء الوكلاء سجلات ومقاييس وتتبعات وحلقة تصحيح قابلة للتكرار+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):+ استخدام أتمتة المتصفح واللقطات للتحقق من سلوك واجهة المستخدم حتى يصبح نظيفًا++## كيفية استخدامها++1. اختر إجراء التشغيل القياسي الذي يتطابق مع عنق الزجاجة الحالي لديك.+2. استخدم قائمة الفحص لإعداد المنتجات أو الأدوات المفقودة.+3. رمِّز القواعد الناتجة في وثائق `repo-template/` المنسوخة.+4. حوِّل تعليقات المراجعة المتكررة إلى فحوصات أو نصوص برمجية أو حواجز وقائية.++هذه ليست مخصصة لاتباعها بشكل أعمى. بل مصممة لجعل الهارنيس أكثر+وضوحًا وقابلية للتطبيق وقابلية للتكرار.diff --git a/docs/ar/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/ar/resources/openai-advanced/sops/layered-domain-architecture.mdnew file mode 100644index 0000000..0e90618--- /dev/null+++ b/docs/ar/resources/openai-advanced/sops/layered-domain-architecture.md@@ -0,0 +1,50 @@+# إجراء التشغيل القياسي: بنية المجالات المتطبقة++استخدم هذا الإجراء عندما يستمر الوكيل في انتهاك الحدود أو تكرار المنطق عبر+الطبقات أو إنتاج كود يصعب مراجعته بعد بضع جلسات.++## الهدف++جعل حدود المجالات صريحة بما يكفي حتى يتمكن الوكلاء من التحرك بسرعة دون+تدهور هيكلي صامت.++## النموذج المستهدف++ضمن مجال أعمال، فضِّل هذا التدفق الاتجاهي:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++المخاوف المشتركة يجب أن تدخل من خلال موفّرين أو محوّلات صريحة.+الأدوات المساعدة المشتركة تبقى خارج المجال وألا تتراكم فيها منطق المجال.++## قائمة فحص الإعداد++- عرِّف المجالات الحالية في `ARCHITECTURE.md`.+- اكتب اتجاهات التبعية المسموح بها في `ARCHITECTURE.md`.+- سجِّل الواجهات المشتركة مثل المصادقة وقياس الأداء وواجهات برمجة التطبيقات الخارجية.+- أضف ملاحظة قصيرة واحدة لأكثر انتهاك حدود صعوبة حاليًا.+- قرر ما يجب تفعيله آليًا بواسطة lint أو الاختبارات أو النصوص البرمجية.++## إجراء التشغيل القياسي للتنفيذ++1. ارسم خريطة قاعدة الكود إلى مجالات قبل لمس نمط التنفيذ.+2. لكل مجال، حدد تسلسل الطبقات المسموح به.+3. حدد جميع المخاوف المشتركة ووجهها عبر موفّرين أو محوّلات.+4. انقل المنطق المشترك الغامض إما إلى المجال المالك أو إلى أدوات مساعدة عامة حقًا.+5. وثِّق القواعد في `ARCHITECTURE.md`.+6. أضف حاجزًا وقائيًا قابلًا للتنفيذ للانتهاك الأعلى تكلفة.+7. حدِّث تسجيل الجودة بعد التغيير.++## تعريف الإنجاز++- يمكن لوكيل جديد معرفة أي طبقة تملك تغييرًا.+- كود واجهة المستخدم لم يعد يصل إلى المستودع أو الآثار الجانبية الخارجية مباشرة.+- المخاوف المشتركة لها نقاط دخول مسماة.+- حد واحد مهم على الأقل مُفعَّل آليًا.++## منتجات المستودع للتحديث++- `ARCHITECTURE.md`+- `docs/QUALITY_SCORE.md`+- `docs/design-docs/` عندما يتغير المنطق+- `docs/PLANS.md` أو خطة التنفيذ النشطةdiff --git a/docs/ar/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/ar/resources/openai-advanced/sops/observability-feedback-loop.mdnew file mode 100644index 0000000..55ae033--- /dev/null+++ b/docs/ar/resources/openai-advanced/sops/observability-feedback-loop.md@@ -0,0 +1,44 @@+# إجراء التشغيل القياسي: حلقة التغذية الراجعة للمراقبة++استخدم هذا الإجراء عندما يكون التصحيح بطيئًا، أو يستمر الوكلاء في الادعاء بالنجاح+بدون أدلة، أو عندما يكون سلوك وقت التشغيل أصعب في الفحص من الكود نفسه.++## الهدف++إعطاء الوكيل حلقة تغذية راجعة محلية عبر السجلات والمقاييس والتتبعات وأحمال+العمل القابلة للتنفيذ حتى يتمكن من الاستنتاج من التنفيذ، وليس فقط من فحص الكود.++## الحد الأدنى من الحزمة++- التطبيق يُصدر سجلات منظمة+- التطبيق يُصدر مقاييس وتتبعات عندما يكون ذلك ممكنًا+- طبقة توزيع أو تجميع محلية+- واجهات استعلام للسجلات والمقاييس والتتبعات+- حمل عمل أو رحلة مستخدم قابلة للتكرار لإعادة التشغيل بعد كل تغيير++## إجراء التشغيل القياسي للتنفيذ++1. حدد رحلات وقت التشغيل الذهبية الأهم.+2. أضف سجلات منظمة لبدء التشغيل والمسار الحرج.+3. أضف مقاييس لزمن الاستجابة أو عدد الإخفاقات أو عمق الطابور حيث يكون مفيدًا.+4. أضف تتبعات أو علامات توقيت للتدفقات البطيئة أو متعددة الخطوات.+5. اجعل الإشارات قابلة للاستعلام من بيئة التطوير المحلية.+6. أعطِ الوكيل حمل عمل أو سيناريو واحد قابل للتكرار لإعادة تشغيله.+7. اطلب الحلقة: استعلام -> ربط -> استنتاج -> تنفيذ -> إعادة تشغيل ->+ إعادة تشغيل -> تحقق.++## قائمة فحص جلسة التصحيح++- ما الذي فشل؟+- أي إشارة تثبت الفشل؟+- أي طبقة تملك الفشل؟+- ما الذي تغير بعد الإصلاح؟+- هل أُعيد تشغيل التطبيق بنظافة؟+- هل نجح نفس حمل العمل بعد إعادة التشغيل؟++## تعريف الإنجاز++- يمكن للوكيل شرح نمط فشل من أدلة وقت التشغيل.+- يمكن إعادة تشغيل نفس حمل العمل بعد كل تغيير.+- إعادة التشغيل وإعادة تشغيل حمل العمل جزء من حلقة المهام العادية.+- إشارات الموثوقية موثقة في `docs/RELIABILITY.md`.diff --git a/docs/ar/resources/reference/coding-agent-startup-flow.md b/docs/ar/resources/reference/coding-agent-startup-flow.mdnew file mode 100644index 0000000..ad1b8f2--- /dev/null+++ b/docs/ar/resources/reference/coding-agent-startup-flow.md@@ -0,0 +1,33 @@+# تدفق بدء تشغيل وكيل البرمجة++استخدم هذا في بداية كل جلسة بعد اكتمال التهيئة.++## قالب بدء التشغيل الثابت++1. شغّل `pwd` وتأكد من جذر المستودع.+2. اقرأ `claude-progress.md`.+3. اقرأ `feature_list.json`.+4. راجع الالتزامات الأخيرة باستخدام `git log --oneline -5`.+5. شغّل `./init.sh`.+6. شغّل مسار الفحص الأساسي أو اختبار شامل.+7. إذا كان الأساس معطلًا، أصلح ذلك أولًا.+8. حدد الميزة غير المنتهية ذات الأولوية القصوى.+9. اعمل فقط على تلك الميزة حتى يتم التحقق منها أو حظرها صراحةً.++## لماذا يهم هذا الترتيب++- `pwd` يمنع العمل العرضي في الدليل الخاطئ.+- ملفات التقدم والميزات تستعيد الحالة الدائمة قبل بدء التعديلات الجديدة.+- الالتزامات الأخيرة تشرح ما تغير مؤخرًا.+- `init.sh` يوحد بدء التشغيل بدلاً من الاعتماد على الذاكرة.+- التحقق الأساسي يلتقط حالات البداية المعطلة قبل أن يخفيها العمل الجديد.++## مرآة نهاية الجلسة++يجب أن تنتهي نفس الجلسة بـ:++1. تسجيل التقدم+2. تحديث حالة الميزة+3. كتابة تسليم إذا لزم الأمر+4. الالتزام بالعمل الآمن+5. ترك مسار إعادة تشغيل نظيفdiff --git a/docs/ar/resources/reference/index.md b/docs/ar/resources/reference/index.mdnew file mode 100644index 0000000..1a8cccf--- /dev/null+++ b/docs/ar/resources/reference/index.md@@ -0,0 +1,29 @@+# مرجع عربي++تشرح هذه الملاحظات كيفية استخدام القوالب كـ harness عامل بدلاً من+مجموعة ملفات فضفاضة.++## ملاحظات مرجعية داخلية++- [`method-map.md`](./method-map.md): يربط أنماط الفشل الشائعة بالمنتج أو السياسة الذي يعالجها أولاً+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md): ما يجب أن يتركه المُهيئ قبل بدء عمل الميزات+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md): سير بدء جلسة ثابت لعمليات البرمجة اللاحقة+- [`prompt-calibration.md`](./prompt-calibration.md): كيف تحافظ على التعليمات الجذرية حادة بدون جعلها منتفخة وهشة++## المقالات الأساسية++هذه القائمة ضيقة عمداً. الـ harness يعني نظام التنفيذ حول النموذج: حلقة الوكيل، تنفيذ الأدوات، الحماية، الحالة، السياق، التحقق، الإنهاء، التنسيق، والمراقبة.++المقالات الثلاثة الأصلية تبقى العمود الفقري للدورة:++- [OpenAI: Harness engineering](https://openai.com/index/harness-engineering/) (2026-02-11)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (2025-11-26)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) (2026-03-24)++## ترتيب القراءة المقترح++1. `method-map.md`+2. `initializer-agent-playbook.md`+3. `coding-agent-startup-flow.md`+4. `prompt-calibration.md`+5. مقالات OpenAI و Anthropic الأساسيةdiff --git a/docs/ar/resources/reference/initializer-agent-playbook.md b/docs/ar/resources/reference/initializer-agent-playbook.mdnew file mode 100644index 0000000..f5a9da8--- /dev/null+++ b/docs/ar/resources/reference/initializer-agent-playbook.md@@ -0,0 +1,36 @@+# دليل وكيل التهيئة++استخدم هذا الدليل لأول جلسة جادة في مستودع، قبل بدء عمل الميزات التدريجي.++## الهدف++إنشاء سطح تشغيل مستقر حتى تتمكن الجلسات اللاحقة من تنفيذ السلوكيات+دون إعادة اشتقاق أوامر بدء التشغيل أو الحالة الحالية أو حدود المهام.++## المخرجات المطلوبة++يجب أن يترك وكيل التهيئة وراءه هذه المنتجات على الأقل:++- ملف تعليمات جذري مثل `AGENTS.md` أو `CLAUDE.md`+- سطح ميزات قابل للقراءة آليًا مثل `feature_list.json`+- منتج تقدم دائم مثل `claude-progress.md`+- مساعد بدء تشغيل قياسي مثل `init.sh`+- التزام أولي آمن يلتقط الهيكل الأساسي++## قائمة الفحص++1. حدد مسار بدء التشغيل القياسي.+2. حدد مسار التحقق القياسي.+3. أنشئ سجل التقدم وسجّل الحالة الأولية.+4. قسّم العمل إلى ميزات صريحة مع حالات.+5. أنشئ أول التزام أساسي نظيف.++## اختبار النجاح++يجب أن تكون جلسة جديدة بدون سياق محادثة سابق قادرة على الإجابة على:++- ماذا يفعل هذا المستودع+- كيفية بدء تشغيله+- كيفية التحقق منه+- ما الذي لم يكتمل+- ما هي أفضل خطوة تاليةdiff --git a/docs/ar/resources/reference/method-map.md b/docs/ar/resources/reference/method-map.mdnew file mode 100644index 0000000..6f0c318--- /dev/null+++ b/docs/ar/resources/reference/method-map.md@@ -0,0 +1,18 @@+# خريطة الأساليب++يربط هذا الجدول أوضاع فشل وكيل البرمجة طويل الأمد الأكثر شيوعًا بالمنتج+أو قاعدة التشغيل التي تصلحها عادةً أولًا.++| وضع الفشل | كيف يبدو في الممارسة | الإصلاح الأساسي | المنتج الداعم |+| --- | --- | --- | --- |+| ارتباك البدء البارد | تقضي الجلسة الجديدة معظم وقتها في إعادة اكتشاف الإعداد والحالة | اجعل المستودع سجل النظام المرجعي | `claude-progress.md` |+| اتساع النطاق | يبدأ الوكيل عدة ميزات ولا ينتهي من أي منها بنظافة | قيّد النطاق النشط | `feature_list.json` |+| الإنجاز المبكر | يدعي الوكيل الانتهاء بعد تعديلات الكود لكن قبل الدليل القابل للتنفيذ | اربط الإنجاز بالأدلة | `clean-state-checklist.md` |+| بدء التشغيل الهش | كل جلسة تعيد تعلم كيفية تشغيل المشروع | وحِّد الإعداد والتحقق | `init.sh` |+| التسليم الضعيف | الجلسة التالية لا تستطيع التمييز بين ما تم التحقق منه وما هو معطل أو تالٍ | انتهِ بتسليم صريح | `session-handoff.md` |+| المراجعة الذاتية | جودة المراجعة تعتمد على الذوق أو الذاكرة | قيِّم المخرجات بفئات ثابتة | `evaluator-rubric.md` |++## مبدأ التشغيل++أضف أصغر منتج يعالج وضع الفشل الملاحظ مباشرة.+تجنب حل كل مشكلة موثوقية بإلقاء المزيد من النص في ملف تعليمات عالمي واحد.diff --git a/docs/ar/resources/reference/prompt-calibration.md b/docs/ar/resources/reference/prompt-calibration.mdnew file mode 100644index 0000000..14b246d--- /dev/null+++ b/docs/ar/resources/reference/prompt-calibration.md@@ -0,0 +1,24 @@+# معايرة التعليمات++يجب أن تحدد التعليمات الجذرية إطار التشغيل، وليس كل حركة ممكنة.++## أبقِ في الملف الجذري++- غرض المستودع ونطاقه+- مسار بدء التشغيل+- مسار التحقق+- القيود غير القابلة للتفاوض+- منتجات الحالة المطلوبة+- قواعد نهاية الجلسة++## أخرج من الملف الجذري++- الحالات الحدية التاريخية الطويلة+- تفاصيل التنفيذ الخاصة بموضوع معين+- ملاحظات البنية المحلية التي يجب أن تكون بالقرب من الكود+- أمثلة تنطبق على نظام فرعي واحد فقط++## قاعدة العمل++يجب أن يساعد الملف الجذري جلسة جديدة على توجيه نفسها بسرعة. إذا أصبح الملف+مكانًا لرمي كل فشل سابق، قسّم التفاصيل إلى مستندات أصغر واربط بها بدلاً من ذلك.diff --git a/docs/ar/resources/templates/AGENTS.md b/docs/ar/resources/templates/AGENTS.mdnew file mode 100644index 0000000..8544a03--- /dev/null+++ b/docs/ar/resources/templates/AGENTS.md@@ -0,0 +1,53 @@+# AGENTS.md++هذا المستودع مصمم للعمل طويل الأمد لوكلاء البرمجة. الهدف ليس تعظيم+إنتاج الكود الخام. الهدف هو ترك المستودع في حالة يمكن للجلسة التالية+أن تستمر فيها بدون تخمين.++## سير عمل بدء التشغيل++قبل كتابة الكود:++1. تأكد من دليل العمل باستخدام `pwd`.+2. اقرأ `claude-progress.md` لمعرفة آخر حالة مُتحقَّقة والخطوة التالية.+3. اقرأ `feature_list.json` واختر الميزة غير المنتهية ذات الأولوية القصوى.+4. راجع الالتزامات الأخيرة باستخدام `git log --oneline -5`.+5. شغّل `./init.sh`.+6. شغّل الفحص أو التحقق الشامل المطلوب قبل بدء عمل جديد.++إذا كان التحقق الأساسي يفشل بالفعل، أصلح ذلك أولًا. لا تضع عمل ميزات جديد+فوق حالة بداية معطلة.++## قواعد العمل++- اعمل على ميزة واحدة في كل مرة.+- لا تعتبر الميزة مكتملة لمجرد أنه تم إضافة كود.+- أبقِ التغييرات ضمن نطاق الميزة المحددة ما لم يُجبرك عائق على إصلاح داعم ضيق.+- لا تغيّر قواعد التحقق بصمت أثناء التنفيذ.+- فضِّل منتجات المستودع الدائمة على ملخصات المحادثة.++## المنتجات المطلوبة++- `feature_list.json`: مصدر الحقيقة لحالة الميزات+- `claude-progress.md`: سجل الجلسة والحالة المُتحقَّقة الحالية+- `init.sh`: مسار بدء التشغيل والتحقق القياسي+- `session-handoff.md`: تسليم مضغوط اختياري للجلسات الأكبر++## تعريف الإنجاز++الميزة تُعتبر منتهية فقط عندما يكون جميع ما يلي صحيحًا:++- السلوك المستهدف مُنفَّذ+- التحقق المطلوب تم تشغيله فعلًا+- الأدلة مسجلة في `feature_list.json` أو `claude-progress.md`+- المستودع يبقى قابلًا لإعادة التشغيل من مسار بدء التشغيل القياسي++## نهاية الجلسة++قبل إنهاء جلسة:++1. حدِّث `claude-progress.md`.+2. حدِّث `feature_list.json`.+3. سجِّل أي خطر أو عائق غير محلول.+4. التزم برسالة وصفية بمجرد أن يكون العمل في حالة آمنة.+5. اترك المستودع نظيفًا بما يكفي لتشغيل الجلسة التالية `./init.sh` فورًا.diff --git a/docs/ar/resources/templates/CLAUDE.md b/docs/ar/resources/templates/CLAUDE.mdnew file mode 100644index 0000000..be1851d--- /dev/null+++ b/docs/ar/resources/templates/CLAUDE.md@@ -0,0 +1,46 @@+# CLAUDE.md++أنت تعمل في مستودع مصمم لعمل تنفيذ طويل الأمد. أعطِ الأولوية للإنجاز+الموثوق والاستمرارية عبر الجلسات والتحقق الصريح على السرعة.++## حلقة التشغيل++في بداية كل جلسة:++1. شغّل `pwd` وتأكد أنك في جذر المستودع المتوقع.+2. اقرأ `claude-progress.md`.+3. اقرأ `feature_list.json`.+4. راجع الالتزامات الأخيرة باستخدام `git log --oneline -5`.+5. شغّل `./init.sh`.+6. تحقق مما إذا كان مسار الفحص الأساسي أو الاختبار الشامل معطلًا بالفعل.++ثم حدد ميزة واحدة غير منتهية بالضبط واعمل فقط على تلك الميزة حتى+تتحقق منها أو توثق سبب حظرها.++## القواعد++- ميزة نشطة واحدة في كل مرة.+- لا تدّعي الإنجاز بدون أدلة قابلة للتنفيذ.+- لا تعيد كتابة قائمة الميزات لإخفاء العمل غير المنتهي.+- لا تزل أو تضعف الاختبارات فقط لجعل المهمة تبدو مكتملة.+- استخدم منتجات المستودع كسجل النظام المرجعي.++## الملفات المطلوبة++- `feature_list.json`+- `claude-progress.md`+- `init.sh`+- `session-handoff.md` عندما يكون التسليم المضغوط مفيدًا++## بوابة الإنجاز++يمكن للميزة الانتقال إلى `passing` فقط بعد نجاح التحقق المطلوب+وتسجيل النتيجة.++## قبل أن تتوقف++1. حدِّث سجل التقدم.+2. حدِّث حالة الميزة.+3. سجِّل ما لا يزال معطلًا أو غير مُتحقَّق.+4. التزم بمجرد أن يكون المستودع آمنًا للاستئناف.+5. اترك مسار إعادة تشغيل نظيف للجلسة التالية.diff --git a/docs/ar/resources/templates/claude-progress.md b/docs/ar/resources/templates/claude-progress.mdnew file mode 100644index 0000000..c1385f9--- /dev/null+++ b/docs/ar/resources/templates/claude-progress.md@@ -0,0 +1,35 @@+# سجل التقدم++## الحالة المُتحقَّقة الحالية++- جذر المستودع:+- مسار بدء التشغيل القياسي:+- مسار التحقق القياسي:+- الميزة غير المنتهية ذات الأولوية القصوى الحالية:+- العائق الحالي:++## سجل الجلسات++### الجلسة 001++- التاريخ:+- الهدف:+- المُنجَز:+- التحقق المُشغَّل:+- الأدلة الملتقطة:+- الالتزامات:+- الملفات أو المنتجات المحدَّثة:+- الخطر المعروف أو المشكلة غير المحلولة:+- أفضل خطوة تالية:++### الجلسة 002++- التاريخ:+- الهدف:+- المُنجَز:+- التحقق المُشغَّل:+- الأدلة الملتقطة:+- الالتزامات:+- الملفات أو المنتجات المحدَّثة:+- الخطر المعروف أو المشكلة غير المحلولة:+- أفضل خطوة تالية:diff --git a/docs/ar/resources/templates/clean-state-checklist.md b/docs/ar/resources/templates/clean-state-checklist.mdnew file mode 100644index 0000000..27b562b--- /dev/null+++ b/docs/ar/resources/templates/clean-state-checklist.md@@ -0,0 +1,8 @@+# قائمة فحص الحالة النظيفة++- [ ] مسار بدء التشغيل القياسي لا يزال يعمل.+- [ ] مسار التحقق القياسي لا يزال يعمل.+- [ ] التقدم الحالي مسجل في سجل التقدم.+- [ ] حالة الميزات تعكس ما هو ناجح فعلًا مقابل غير مُتحقَّق.+- [ ] لا توجد خطوة نصف منتهية بدون توثيق.+- [ ] الجلسة التالية يمكنها الاستمرار بدون إصلاح يدوي.diff --git a/docs/ar/resources/templates/evaluator-rubric.md b/docs/ar/resources/templates/evaluator-rubric.mdnew file mode 100644index 0000000..59bf0eb--- /dev/null+++ b/docs/ar/resources/templates/evaluator-rubric.md@@ -0,0 +1,24 @@+# معيار المُقيِّم++استخدم هذا المعيار بعد التنفيذ وقبل القبول النهائي.++| الفئة | السؤال | النتيجة (0-2) | ملاحظات |+| --- | --- | --- | --- |+| الصحة | هل السلوك المُنفَّذ يتطابق مع الميزة المطلوبة؟ | | |+| التحقق | هل تم تشغيل الفحوصات المطلوبة فعلًا، مع أدلة؟ | | |+| انضباط النطاق | هل بقيت الجلسة داخل نطاق الميزة المختارة؟ | | |+| الموثوقية | هل تتحمل النتيجة إعادة التشغيل أو إعادة التشغيل بدون إصلاح؟ | | |+| قابلية الصيانة | هل الكود والتوثيق واضحان بما يكفي للجلسة التالية؟ | | |+| جاهزية التسليم | هل يمكن لجلسة جديدة الاستمرار من منتجات المستودع فقط؟ | | |++## الحكم++- قبول+- مراجعة+- حظر++## المتابعة المطلوبة++- أدلة مفقودة:+- إصلاحات مطلوبة:+- محفز المراجعة التالية:diff --git a/docs/ar/resources/templates/feature_list.json b/docs/ar/resources/templates/feature_list.jsonnew file mode 100644index 0000000..138adc6--- /dev/null+++ b/docs/ar/resources/templates/feature_list.json@@ -0,0 +1,64 @@+{+ "project": "replace-with-project-name",+ "last_updated": "YYYY-MM-DD",+ "rules": {+ "single_active_feature": true,+ "passing_requires_evidence": true,+ "do_not_skip_verification": true+ },+ "status_legend": {+ "not_started": "Work has not begun.",+ "in_progress": "The feature is the current active task.",+ "blocked": "Work cannot continue until a documented blocker is resolved.",+ "passing": "Required verification has passed and evidence is recorded."+ },+ "features": [+ {+ "id": "chat-001",+ "priority": 1,+ "area": "chat",+ "title": "Create a new conversation",+ "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",+ "status": "not_started",+ "verification": [+ "Open the app.",+ "Click New Chat.",+ "Verify a new conversation appears in the sidebar.",+ "Verify the main panel shows an empty conversation state."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-002",+ "priority": 2,+ "area": "chat",+ "title": "Send a message in the current conversation",+ "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",+ "status": "not_started",+ "verification": [+ "Open an existing conversation.",+ "Type a message into the input.",+ "Submit the message.",+ "Verify the new message appears in the thread."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-003",+ "priority": 3,+ "area": "chat",+ "title": "Persist the active conversation list",+ "user_visible_behavior": "A user sees previously created conversations after restarting the app.",+ "status": "not_started",+ "verification": [+ "Create two conversations.",+ "Restart the app.",+ "Verify both conversations still appear in the sidebar."+ ],+ "evidence": [],+ "notes": ""+ }+ ]+}diff --git a/docs/ar/resources/templates/index.md b/docs/ar/resources/templates/index.mdnew file mode 100644index 0000000..7d66bd8--- /dev/null+++ b/docs/ar/resources/templates/index.md@@ -0,0 +1,41 @@+# دليل القوالب++هذه القوالب جاهزة للنسخ إلى مشروعك الخاص. كل واحدة تخدم غرضاً محدداً في سير عمل الوكيل. عدّل المحتوى ليتوافق مع أوامر ومسارات وأسماء ميزات وخطوات تحقق مشروعك.++## كيف تبدأ++انسخ هذه الملفات الأربعة إلى جذر مشروعك أولاً:++1. `AGENTS.md` أو `CLAUDE.md`+2. `init.sh`+3. `claude-progress.md`+4. `feature_list.json`++أضف الملفات المتبقية مع نمو مشروعك.++---++## AGENTS.md++ملف التعليمات الجذري. هذا أول ما يقرأه الوكيل عند بدء جلسة. يحدد قواعد التشغيل: ماذا يفعل قبل كتابة الكود، كيف يعمل، وكيف ينهي العمل.++استخدم `AGENTS.md` لـ Codex أو وكلاء آخرين. استخدم `CLAUDE.md` إذا كنت تعمل مع Claude Code — البنية نفسها، بتنسيق نمط تعليمات Claude.++## init.sh++سكربت التشغيل. يُشغّل تثبيت التبعيات والتحقق ويطبع أمر البدء — كل ذلك في خطوة واحدة.++## claude-progress.md++سجل التقدم. كل جلسة تكتب في هذا الملف، وكل جلسة جديدة تقرأه أولاً.++## feature_list.json++متتبع الميزات. قائمة مقروءة آلياً لكل ميزة يحتاجها الوكيل مع حالتها وخطوات التحقق والأدلة.++## الملفات الأخرى++- `session-handoff.md` — ملاحظة تسليم مدمجة بين الجلسات+- `clean-state-checklist.md` — قائمة فحص قبل إنهاء كل جلسة+- `evaluator-rubric.md` — بطاقة تسجيل لمراجعة جودة مخرجات الوكيل+- `quality-document.md` — لقطة جودة تُقيّم كل مجال منتج وطبقة معماريةdiff --git a/docs/ar/resources/templates/init.sh b/docs/ar/resources/templates/init.shnew file mode 100755index 0000000..d7522d6--- /dev/null+++ b/docs/ar/resources/templates/init.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash++set -euo pipefail++ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+cd "$ROOT_DIR"++# Replace these commands with the correct commands for your repository.+INSTALL_CMD=(npm install)+VERIFY_CMD=(npm test)+START_CMD=(npm run dev)++echo "==> Working directory: $PWD"+echo "==> Syncing dependencies"+"${INSTALL_CMD[@]}"++echo "==> Running baseline verification"+"${VERIFY_CMD[@]}"++echo "==> Startup command"+printf ' %q' "${START_CMD[@]}"+printf '\n'++if [ "${RUN_START_COMMAND:-0}" = "1" ]; then+ echo "==> Starting the app"+ exec "${START_CMD[@]}"+fi++echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."diff --git a/docs/ar/resources/templates/quality-document.md b/docs/ar/resources/templates/quality-document.mdnew file mode 100644index 0000000..cc26c8f--- /dev/null+++ b/docs/ar/resources/templates/quality-document.md@@ -0,0 +1,43 @@+# وثيقة الجودة++لقطة جودة لكل مجال منتج وطبقة معمارية. يمكن للوكلاء والبشر على حد سواء استخدام هذه الوثيقة لفهم أين تكون قاعدة الكود قوية وأين تحتاج إلى عمل بسرعة.++**وتيرة التحديث:** بعد كل جلسة مهمة، أو قبل بدء مرحلة عمل جديدة.++**مقياس الدرجات:**++- **A**: جميع عمليات التحقق ناجحة، بنية نظيفة، قابلية قراءة الوكيل، اختبارات مستقرة+- **B**: التحقق ناجح، نظيف في الغالب، فجوات طفيفة في قابلية القراءة أو تغطية الاختبار+- **C**: يعمل جزئيًا، فجوات معروفة، بعض مناطق الكود صعبة على الوكلاء لفهمها+- **D**: لا يعمل، أو مشاكل هيكلية كبيرة++---++## مجالات المنتج++| المجال | الدرجة | التحقق | قابلية قراءة الوكيل | استقرار الاختبار | الفجوات الرئيسية | آخر تحديث |+|--------|-------|-------------|-----------------|---------------|----------|-------------|+| استيراد المستندات | - | - | - | - | - | - |+| إدارة المستندات | - | - | - | - | - | - |+| فهرسة المستندات | - | - | - | - | - | - |+| تدفق الأسئلة والأجوبة | - | - | - | - | - | - |+| الإجابات المسبقة | - | - | - | - | - | - |++## الطبقات المعمارية++| الطبقة | الدرجة | تطبيق الحدود | قابلية قراءة الوكيل | الفجوات الرئيسية | آخر تحديث |+|-------|-------|---------------------|-----------------|----------|-------------|+| العملية الرئيسية | - | - | - | - | - |+| التحميل المسبق | - | - | - | - | - |+| العارض | - | - | - | - | - |+| الخدمات | - | - | - | - | - |++## سجل التغييرات++### YYYY-MM-DD++- التغييرات:+- المجالات المُرقَّاة:+- المجالات المُخفَّضة:+- الفجوات الجديدة المكتشفة:+- الفجوات المغلقة:diff --git a/docs/ar/resources/templates/session-handoff.md b/docs/ar/resources/templates/session-handoff.mdnew file mode 100644index 0000000..da6dc43--- /dev/null+++ b/docs/ar/resources/templates/session-handoff.md@@ -0,0 +1,30 @@+# تسليم الجلسة++## مُتحقَّق الآن++- ما هو يعمل حاليًا:+- ما التحقق الذي تم تشغيله فعلًا:++## تغيّر في هذه الجلسة++- كود أو سلوك مضاف:+- تغييرات البنية التحتية أو الهارنيس:++## معطل أو غير مُتحقَّق++- عيب معروف:+- مسار غير مُتحقَّق:+- خطر على الجلسة التالية:++## أفضل خطوة تالية++- الميزة غير المنتهية ذات الأولوية القصوى:+- لماذا هي التالية:+- ما الذي يُحتسب كناجح:+- ما الذي يجب ألا يتغير خلال تلك الخطوة:++## الأوامر++- بدء التشغيل:+- التحقق:+- أمر التصحيح المركز:diff --git a/docs/ar/skills/index.md b/docs/ar/skills/index.mdnew file mode 100644index 0000000..2a7c576--- /dev/null+++ b/docs/ar/skills/index.md@@ -0,0 +1,49 @@+# المهارات++يحتوي هذا المجلد على مهارات وكلاء الذكاء الاصطناعي المرفقة مع هذا المساق. المهارات هي قوالب prompt مستقلة يمكن لوكلاء البرمجة مثل Claude Code و Codex و Cursor و Windsurf تحميلها لتنفيذ مهام متخصصة.++## harness-creator++مهارة harness engineering بمستوى إنتاجي لوكلاء البرمجة بالذكاء الاصطناعي. تساعدك على إنشاء وتقييم وتحسين الأنظمة الفرعية الخمسة الأساسية لأي harness: التعليمات، الحالة، التحقق، النطاق، ودورة حياة الجلسة.++### ماذا تفعل++- **إنشاء harnesses من الصفر** — AGENTS.md، قوائم ميزات، workflows للتحقق+- **تحسين harnesses موجودة** — تقييم للأنظمة الفرعية الخمسة مع تحسينات ذات أولوية+- **تصميم استمرارية الجلسات** — ذاكرة دائمة، تتبع التقدم، وإجراءات handoff+- **تطبيق أنماط إنتاجية** — الذاكرة، context engineering، أمان الأدوات، والتنسيق متعدد الوكلاء++### بداية سريعة++توجد ملفات المهارة في المستودع ضمن [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator).++لاستخدامها مع Claude Code، انسخ مجلد `harness-creator/` إلى مسار المهارات في مشروعك، أو وجه الوكيل إلى ملف SKILL.md.++### أنماط مرجعية++تتضمن المهارة 6 وثائق مرجعية مفصلة:++| النمط | متى تستخدمه |+|---------|-------------|+| Memory Persistence | عندما ينسى الوكيل بين الجلسات |+| Context Engineering | إدارة ميزانية السياق والتحميل عند الحاجة |+| Tool Registry | أمان الأدوات والتحكم في التوازي |+| Multi-Agent Coordination | التوازي و workflows التخصص |+| Lifecycle & Bootstrap | hooks، مهام الخلفية، والتهيئة |+| Gotchas | 15 نمط فشل غير بديهي مع حلول |++### القوالب++تضم المهارة قوالب جاهزة للاستخدام:++- `agents.md` — هيكل AGENTS.md مع قواعد عمل+- `feature-list.json` — JSON Schema ومثال قائمة ميزات+- `init.sh` — سكربت تهيئة قياسي+- `progress.md` — قالب سجل تقدم الجلسة++### كيف بُنيت هذه المهارة++طُورت `harness-creator` باستخدام منهجية **skill-creator**، وهي meta-skill الرسمية من Anthropic لإنشاء مهارات الوكلاء واختبارها وتحسينها تكراريًا. توفر skill-creator workflow منظمًا: مسودة → اختبار → تقييم → تكرار، مع مشغلات eval ومصححات وواجهة benchmark.++- **مصدر skill-creator**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)+- **وثائق مهارات Claude Code**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)diff --git a/docs/de/index.md b/docs/de/index.mdnew file mode 100644index 0000000..a58a7b6--- /dev/null+++ b/docs/de/index.md@@ -0,0 +1,73 @@+# Willkommen bei Learn Harness Engineering++Learn Harness Engineering ist ein Kurs über die technische Gestaltung von KI-Coding-Agenten. Wir haben fortgeschrittene Theorien und Praktiken des Harness Engineering aus der Industrie untersucht und in eine praktisch nutzbare Form gebracht. Unsere wichtigsten Referenzen sind:+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)++Durch systematisches Umgebungsdesign, Zustandsverwaltung, Verifikation und Kontrollmechanismen zeigt dieser Kurs, wie agentische Coding-Tools wie Codex und Claude Code wirklich zuverlässig werden. Du lernst, Features zu bauen, Bugs zu beheben und Entwicklungsaufgaben zu automatisieren, indem du deinen KI-Coding-Assistenten mit expliziten Regeln und Grenzen führst.++## Erste Schritte++Wähle deinen Lernpfad. Der Kurs besteht aus theoretischen Lektionen, praktischen Projekten und einer sofort nutzbaren Ressourcenbibliothek.++<div class="card-grid">+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">+ <h3>Lektionen</h3>+ <p>Verstehe, warum starke Modelle trotzdem scheitern, und lerne die Theorie wirksamer Harnesses.</p>+ </a>+ <a href="./projects/" class="card">+ <h3>Projekte</h3>+ <p>Praktische Übungen zum Aufbau einer zuverlässigen agentischen Arbeitsumgebung von Grund auf.</p>+ </a>+ <a href="./resources/" class="card">+ <h3>Ressourcenbibliothek</h3>+ <p>Kopierfertige Vorlagen wie AGENTS.md und feature_list.json für deine eigenen Repositories.</p>+ </a>+</div>++## Der Kernmechanismus eines Harness++Ein harness "macht das Modell nicht klüger"; er schafft ein geschlossenes **Arbeitssystem** für das Modell. Der Kernablauf lässt sich mit diesem Diagramm verstehen:++```mermaid+graph TD+ A["Clear Objective<br/>AGENTS.md"] --> B("Initialization<br/>init.sh")+ B --> C{"Run Tasks<br/>AI Agent"}+ C -->|Encounter Issues| D["Runtime Feedback<br/>CLI / Logs"]+ D -->|Auto-fix| C+ C -->|Code Completed| E{"Verify & QA<br/>Test suite"}+ E -->|Failed| D+ E -->|Passed| F["Cleanup & Handoff<br/>claude-progress.md"]++ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;++ class A,F primary;+ class B,D process;+ class C,E check;+```++## Was du lernen wirst++Zu den zentralen Konzepten gehören:++<ul class="index-list">+ <li><strong>Agentenverhalten begrenzen</strong> durch explizite Regeln und Grenzen.</li>+ <li><strong>Kontext erhalten</strong> über lange Aufgaben und mehrere Sessions hinweg.</li>+ <li><strong>Agenten davon abhalten</strong>, zu früh Erfolg zu melden.</li>+ <li><strong>Arbeit verifizieren</strong> mit vollständigen Pipeline-Tests und Selbstprüfung.</li>+ <li><strong>Runtime beobachtbar machen</strong> und leichter debuggen.</li>+</ul>++## Nächste Schritte++Wenn du die Grundkonzepte verstanden hast, helfen diese Leitfäden beim Vertiefen:++<ul class="index-list">+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">Lektion 01: Warum fähige Agenten trotzdem scheitern</a>: Beginne mit der Theorie hinter harness engineering.</li>+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">Projekt 01: Baseline vs minimaler harness</a>: Arbeite deine erste reale Aufgabe durch.</li>+ <li><a href="./resources/templates/">Vorlagen</a>: Hole dir das minimale harness-Paket für deine eigenen Projekte.</li>+</ul>diff --git a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..311e665--- /dev/null+++ b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,170 @@+/**+ * failure-pattern-demo.ts+ *+ * Simulates the 4-step failure pattern that capable agents fall into:+ * 1. Incomplete context+ * 2. Locally reasonable changes+ * 3. No global verification+ * 4. Premature completion+ *+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// Simulated "model" -- a simple decision function that bases its output+// solely on whatever context it has been given.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // The task is to "add a search endpoint to the API".+ // Correct answer requires knowing about auth middleware and rate limiting.++ if (!has("auth")) {+ return "Created new route handler /search without authentication checks";+ }+ if (!has("rate-limit")) {+ return "Added search route with auth but forgot rate limiting";+ }+ if (!has("test-standards")) {+ return "Implemented search with auth and rate-limit, but no tests";+ }+ return "Fully implemented search endpoint with auth, rate-limit, and tests";+}++// ---------------------------------------------------------------------------+// Failure simulation+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Step 1: Incomplete Context ----+ const step1Context = ["project structure", "route definitions"];+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];+ const step1Decision = modelDecide(step1Context, "add search endpoint");++ steps.push({+ step: 1,+ name: "Incomplete Context",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Looks good -- route compiles, returns data",+ globalImpact: "Missing auth means unauthenticated access to search",+ completed: false,+ });++ // ---- Step 2: Locally Reasonable Changes ----+ // The agent adds auth after a hint, but still lacks other context.+ const step2Context = [...step1Context, "auth middleware"];+ const step2Missing = ["rate-limiting policy", "test standards"];+ const step2Decision = modelDecide(step2Context, "add search endpoint");++ steps.push({+ step: 2,+ name: "Locally Reasonable Changes",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "Route has auth -- looks complete locally",+ globalImpact: "No rate limiting means the endpoint can be abused",+ completed: false,+ });++ // ---- Step 3: No Global Verification ----+ const step3Context = [...step2Context, "rate-limiting policy"];+ const step3Missing = ["test standards"];+ const step3Decision = modelDecide(step3Context, "add search endpoint");++ steps.push({+ step: 3,+ name: "No Global Verification",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "Feature appears fully implemented",+ globalImpact: "No tests -- regression risk, violates project standards",+ completed: false,+ });++ // ---- Step 4: Premature Completion ----+ steps.push({+ step: 4,+ name: "Premature Completion",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',+ localOutcome: "Agent is satisfied, task marked complete",+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Comparison table+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Step ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);+ console.log(` Action taken : ${s.actionTaken}`);+ console.log(` Local outcome : ${s.localOutcome}`);+ console.log(` Global impact : ${s.globalImpact}`);+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);+ }++ // Summary comparison+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");+ console.log("=".repeat(90));++ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];+ const finalAvailable = steps[steps.length - 1].contextAvailable;++ const header = "| Criterion | Available | Missing | Status |";+ const sep = "|------------------------|-----------|---------|----------|";+ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;+ console.log(row);+ }++ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());diff --git a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdnew file mode 100644index 0000000..c9eab0c--- /dev/null+++ b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -0,0 +1,9 @@+# Fehlersignal-Checkliste++Verwenden Sie diese Checkliste bei der Überprüfung eines schwachen Harness-Laufs.++- Hat der Agent gefragt oder falsch abgeleitet, wie die App gestartet wird?+- Hat er Verzeichnisse oder Abstraktionen erstellt, die nicht zum intended Produkt passen?+- Hat er nach Erstellung einer sichtbaren UI-Hülle ohne vollständigen Workflow aufgehört?+- Hat er Notizen oder Artefakte hinterlassen, die einem zukünftigen Lauf helfen?+- Könnte eine frische Session in unter fünf Minuten verstehen, was passiert ist?diff --git a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdnew file mode 100644index 0000000..6774c8a--- /dev/null+++ b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -0,0 +1,7 @@+# Code für Vorlesung 01++Verwenden Sie diesen Ordner für kleine Beispiele, die zeigen:++- ein starkes Modell, das in einer schwachen Umgebung scheitert+- unzureichend spezifizierte Repo-Einrichtung+- fehlende Feedback-Schleifendiff --git a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdnew file mode 100644index 0000000..dc502cd--- /dev/null+++ b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -0,0 +1,18 @@+# Beispiel für eine unzureichend spezifizierte Aufgabe++Erstelle eine Desktop-Wissensdatenbank-App mit KI-Frage-Antwort-Funktion.++Einschränkungen:++- Keine angegeben+- Kein Startbefehl gegeben+- Keine Ordnerstruktur-Anleitung+- Kein Datenmodell definiert+- Keine expliziten Abschlusskriterien++Typische Ergebnisse bei dieser Art von Prompt:++- der Agent erfindet ad hoc eine Struktur+- die App kompiliert möglicherweise, startet aber nicht konsistent+- die UI erscheint möglicherweise, bevor ein nutzbarer Ingest/Query-Pfad existiert+- der Agent stoppt oft nach kosmetischem Erfolgdiff --git a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.mdnew file mode 100644index 0000000..e0b04da--- /dev/null+++ b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -0,0 +1,117 @@+[中文版本 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-01-why-capable-agents-still-fail/code/)+> Praxisprojekt: [Projekt 01. Nur Prompt vs. Regeln zuerst](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# Lektion 01. Starke Modelle bedeuten keine zuverlässige Ausführung++Du kennst dich in der KI-Welt gut aus: Claude-Pro-Abo, GPT-4o-API-Key, SWE-bench-Ranglisten im Kopf. Eines Tages gibst du einem KI-Agenten endlich ein echtes Projekt und bist voller Zuversicht. Das Ergebnis? Er fügt ein Feature hinzu, bricht aber die Tests, behebt einen Bug und erzeugt zwei neue, läuft 20 Minuten und erklärt stolz "fertig" - und wenn du dir den Code ansiehst, ist es gar nicht das, was du verlangt hast.++Dein erster Impuls? "Dieses Modell ist nicht gut genug. Zeit für ein Upgrade." Warte kurz. Bevor du zur Kreditkarte greifst, solltest du in Betracht ziehen, dass das Problem vielleicht gar nicht das Modell ist.++Schauen wir auf ein paar Zahlen. Ende 2025 erreichen die stärksten Coding-Agenten auf SWE-bench Verified ungefähr 50-60%. Und das bei sorgfältig ausgewählten Aufgaben mit klaren Issue-Beschreibungen und vorhandenen Tests. Übertrage das auf deine tägliche Entwicklungsumgebung - vage Anforderungen, keine vorhandenen Tests, überall verstreute implizite Geschäftsregeln - und diese Zahl sinkt weiter.++Hinter diesen Zahlen steckt aber eine kontraintuitive Wahrheit.++## Gleiches Pferd, anderes Ergebnis++Anthropic führte ein kontrolliertes Experiment durch. Gleicher Prompt ("baue einen 2D-Retro-Game-Maker"), gleiches Modell (Opus 4.5). Erster Lauf: nackt, ohne Unterstützung - 20 Minuten, 9 Dollar, die Kernfunktionen des Spiels funktionierten überhaupt nicht. Zweiter Lauf: vollständiger Harness (Planner + Generator + Evaluator als Drei-Agenten-Architektur) - 6 Stunden, 200 Dollar, das Spiel war spielbar.++Sie änderten nicht das Modell. Opus 4.5 blieb Opus 4.5. Was sich änderte, war der Sattel.++OpenAIs Artikel zu Harness Engineering aus dem Jahr 2025 formuliert es direkt: Codex wechselt in einem gut geharnessten Repository von "unzuverlässig" zu "zuverlässig". Achte auf die Wortwahl - nicht "ein bisschen besser", sondern ein qualitativer Sprung. Wie bei einem Vollblutpferd: Du kannst ohne Sattel reiten, aber du kommst nicht weit, nicht schnell, und ein Sturz ist keine Überraschung. Der Harness ist dieser Sattel - **alles in der Engineering-Infrastruktur außerhalb der Modellgewichte.**++## Wo Agenten tatsächlich stecken bleiben++Was geht also konkret schief?++Am häufigsten: Du hast die Aufgabe nie eindeutig definiert. Du sagst "füge eine Suchfunktion hinzu", und das Verständnis des Agenten unterscheidet sich komplett von deinem - wonach suchen? Volltext oder strukturiert? Pagination? Hervorhebungen? Du hast es nicht angegeben, also rät der Agent. Ein richtiger Tipp ist Glück; ein falscher Tipp kostet mehr Nacharbeit, als klare Spezifikation am Anfang gekostet hätte. Es ist, als würdest du in ein Restaurant gehen und dem Koch sagen: "Ich nehme Fisch" - ob er geschmort, gedämpft oder im Hot Pot kommt, bleibt dem Zufall überlassen.++Selbst wenn du spezifizierst, hat das Projekt implizite Architekturkonventionen, die der Agent nicht kennt. Dein Team hat SQLAlchemy-2.0-Syntax standardisiert, aber der Agent schreibt standardmäßig 1.x-Code. Alle API-Endpunkte müssen OAuth-2.0-Authentifizierung nutzen, aber diese Regel existiert nur in deinem Kopf und in einer Slack-Nachricht von vor drei Monaten. Der Agent sieht das nicht - nicht weil er sich nicht daran halten will, sondern weil er buchstäblich nicht weiß, dass diese Regeln existieren.++Auch die Umgebung ist eine Falle. Unvollständige Entwicklungsumgebung, fehlende Abhängigkeiten, falsche Tool-Versionen. Der Agent verbrennt wertvolles Kontextfenster mit `pip install`-Fehlern und Node-Versionenkonflikten, statt deine eigentliche Aufgabe zu lösen. Das ist, als würdest du einen fähigen Tischler einstellen, aber Hammer, Nägel und eine ebene Werkbank vergessen - egal wie talentiert er ist, so kann er die Arbeit nicht erledigen.++Noch häufiger: Es gibt schlicht keine Möglichkeit zur Verifikation. Keine Tests, kein Linting, oder die Verifikationsbefehle wurden dem Agenten nie mitgeteilt. Der Agent schreibt Code, sieht ihn sich an, entscheidet, dass er gut aussieht, und sagt "fertig". Das ist wie Hausaufgaben ohne Lösungsschlüssel: Der Schüler glaubt, alles richtig zu haben, aber beim Korrigieren liegen überall Fehler. Anthropic beobachtete außerdem ein interessantes Phänomen: Wenn Agenten spüren, dass der Kontext knapp wird, beeilen sie sich, überspringen Verifikation und wählen eine einfache statt der besten Lösung. Sie nennen das "context anxiety" - dasselbe Gefühl, wenn bei einer Prüfung die Zeit fast abgelaufen ist und man die letzten Multiple-Choice-Fragen zufällig ankreuzt.++Lange Aufgaben über mehrere Sitzungen sind noch schlimmer: Alle Erkenntnisse aus der vorherigen Sitzung gehen verloren, und jede neue Sitzung muss Projektstruktur und Codeorganisation erneut erkunden und verstehen. Bei Agenten ohne persistenten Zustand steigen die Fehlerraten bei Aufgaben über 30 Minuten stark an.++## Schlüsselbegriffe++Mit diesen Szenarien im Hinterkopf sind die folgenden Begriffe kein bloßer Jargon mehr:++- **Capability Gap**: Die große Lücke zwischen Modellleistung auf Benchmarks und Leistung bei realen Aufgaben. Eine Erfolgsrate von 50-60% auf SWE-bench Verified bedeutet, dass fast die Hälfte realer Issues nicht gelöst wird.+- **Harness**: Alles außerhalb des Modells - Anweisungen, Tools, Umgebung, Zustandsverwaltung, Verifikationsfeedback. Wenn es keine Modellgewichte sind, gehört es zum Harness. Das ist der "Sattel", von dem wir gesprochen haben.+- **Harness-Induced Failure**: Das Modell hat grundsätzlich genug Fähigkeit, aber die Ausführungsumgebung hat strukturelle Defekte. Anthropics kontrolliertes Experiment hat genau das gezeigt.+- **Verification Gap**: Die Lücke zwischen dem Vertrauen des Agenten in sein Ergebnis und der tatsächlichen Korrektheit. Der Agent sagt "ich bin fertig", obwohl er nicht fertig ist - der häufigste Fehlermodus.+- **Diagnostic Loop**: Ausführen, Fehler beobachten, einer bestimmten Harness-Schicht zuordnen, diese Schicht reparieren, erneut ausführen. Das ist die Kernmethodik von Harness Engineering.+- **Definition of Done**: Eine Menge maschinell überprüfbarer Bedingungen - Tests grün, Lint sauber, Type Checks bestanden. Ohne explizite Definition of Done erfindet der Agent seine eigene.++## Wenn etwas scheitert, repariere zuerst den Harness++Kernprinzip: **Wenn etwas scheitert, tausche nicht zuerst das Modell aus - prüfe den Harness.** Wenn dasselbe Modell bei ähnlichen, gut strukturierten Aufgaben erfolgreich ist, gehe von einem Harness-Problem aus. Das ist wie bei einem Auto, das liegen bleibt: Du verdächtigst nicht sofort den Motor. Du prüfst zuerst, ob der Tank leer ist.++Konkrete Schritte:++**Ordne jeden Fehler einer bestimmten Schicht zu.** Sag nicht nur "das Modell taugt nichts". Frage: War die Aufgabe unklar? War der Kontext unzureichend? Gab es keine Verifikationsmethode? Ordne jeden Fehler einer der fünf Fehlerschichten zu: Aufgabenspezifikation, Kontextbereitstellung, Ausführungsumgebung, Verifikationsfeedback, Zustandsverwaltung. Wenn du diese Gewohnheit aufbaust, wirst du "das Modell ist nicht gut genug" immer seltener in deinen Logs sehen.++**Schreibe für jede Aufgabe eine explizite Definition of Done.** Sag nicht "füge eine Suchfunktion hinzu". Sag:+```+Completion criteria:+- New endpoint GET /api/search?q=xxx+- Supports pagination, default 20 items+- Results include highlighted snippets+- All new code passes pytest+- Type checking passes (mypy --strict)+```++**Erstelle eine AGENTS.md-Datei.** Lege sie im Repository-Root ab, damit der Agent Tech Stack, Architekturkonventionen und Verifikationsbefehle des Projekts kennt. Das ist der erste Schritt im Harness Engineering und der Schritt mit dem höchsten ROI. Eine einzige `AGENTS.md`-Datei kann wirksamer sein als ein Upgrade auf ein teureres Modell - das ist kein Witz.++**Baue eine Diagnoseschleife.** Behandle Fehler nicht als "das Modell ist wieder dumm". Behandle sie als Signale, dass dein Harness einen Defekt hat. Bei jedem Fehler: Schicht identifizieren, reparieren, dafür sorgen, dass derselbe Fehler nicht wieder auftritt. Nach ein paar Runden wird dein Harness stärker und die Agentenleistung stabiler. Wie Straßenreparatur: Jedes gefüllte Schlagloch macht den nächsten Abschnitt glatter.++**Quantifiziere Verbesserungen.** Führe ein einfaches Log: War jede Aufgabe erfolgreich oder nicht, und welche Schicht hat den Fehler verursacht? Nach ein paar Runden siehst du, welche Schicht der Engpass ist - konzentriere deine Energie dort.++## Das Millionen-Zeilen-Experiment++OpenAI führte 2025 ein aggressives Experiment durch: Codex sollte aus einem leeren Git-Repository ein vollständiges internes Produkt bauen. Fünf Monate später hatte das Repository ungefähr eine Million Zeilen Code - Anwendungslogik, Infrastruktur, Tooling, Dokumentation, interne Entwicklerwerkzeuge - alles von Agenten erzeugt. Drei Engineers steuerten Codex und öffneten sowie mergten etwa 1.500 PRs. Im Schnitt 3,5 PRs pro Person und Tag.++Die zentrale Einschränkung: **Menschen schreiben nie direkt Code.** Das war kein Trick, sondern sollte das Team zwingen herauszufinden, was sich ändert, wenn die Hauptaufgabe des Engineers nicht mehr Code schreiben ist, sondern Umgebungen zu entwerfen, Absichten präzise auszudrücken und Feedbackschleifen zu bauen.++Der frühe Fortschritt war langsamer als erwartet. Nicht weil Codex unfähig war, sondern weil die Umgebung nicht vollständig genug war - dem Agenten fehlten notwendige Werkzeuge, Abstraktionen und interne Strukturen, um übergeordnete Ziele voranzubringen. Die Arbeit der Engineers wurde: große Ziele in kleine Bausteine zerlegen (Design, Code, Review, Test), den Agenten diese zusammensetzen lassen und diese Bausteine dann nutzen, um komplexere Aufgaben freizuschalten. Wenn etwas scheiterte, lautete die Lösung fast nie "streng dich mehr an", sondern "welche Fähigkeit fehlt dem Agenten, und wie machen wir sie verständlich und ausführbar?"++Dieses Experiment belegt direkt die Kernaussage dieser Lektion: **Dasselbe Modell erzeugt in einer nackten Umgebung grundlegend andere Ergebnisse als in einer Umgebung mit vollständigem Harness.** Das Modell änderte sich nicht. Die Umgebung änderte sich.++> Quelle: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++## Ein bodenständigeres Beispiel++Ein Team nutzte Claude Sonnet, um einer mittelgroßen Python-Web-App (FastAPI + PostgreSQL + Redis, ca. 15.000 Codezeilen) einen neuen API-Endpunkt hinzuzufügen.++Zunächst gaben sie nur einen Satz: "add user preferences endpoints under `/api/v2/users`." Das Ergebnis? Der Agent verbrauchte 40% seines Kontextfensters damit, die Repository-Struktur zu erkunden, erzeugte Code, der plausibel aussah, aber nicht den Error-Handling-Mustern des Projekts folgte, verwendete alte SQLAlchemy-Syntax und erklärte die Aufgabe für abgeschlossen, obwohl der Endpunkt Laufzeitfehler hatte. Die nächste Sitzung musste die gesamte Entdeckungsarbeit erneut leisten.++Später ergänzten sie `AGENTS.md` (mit Projektarchitektur und Tech-Stack-Versionen), explizite Verifikationsbefehle (`pytest tests/api/v2/ && python -m mypy src/`) und Architecture Decision Records. Dasselbe Modell war in allen drei unabhängigen Läufen erfolgreich, mit etwa 60% besserer Kontext-Effizienz.++Sie änderten nicht das Modell. Sie änderten den Harness.++## Wichtigste Erkenntnisse++- Modellfähigkeit und Ausführungszuverlässigkeit sind verschiedene Dinge. Auch ein Vollblut braucht einen guten Sattel.+- Wenn etwas scheitert, prüfe zuerst den Harness und dann das Modell. Modelle zu wechseln ist die teuerste Option - und oft ist es nicht einmal ein Modellproblem.+- Jeder Fehler ist ein Signal: Dein Harness hat einen strukturellen Defekt. Finde ihn und behebe ihn.+- Fünf Verteidigungsschichten: Aufgabenspezifikation, Kontextbereitstellung, Ausführungsumgebung, Verifikationsfeedback, Zustandsverwaltung. Prüfe sie systematisch, wie ein Arzt die häufigsten Ursachen zuerst ausschließt.+- Eine einzige `AGENTS.md`-Datei kann wirksamer sein als ein Upgrade auf ein teureres Modell. Ernsthaft.++## Weiterführende Literatur++- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-bench Leaderboard](https://www.swebench.com/)+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)++## Übungen++1. **Vergleichsexperiment**: Wähle eine Codebase, die du gut kennst, und eine nicht triviale Änderungsaufgabe. Führe den Agenten zuerst ohne Harness-Unterstützung aus und protokolliere die Fehler. Füge dann eine `AGENTS.md` mit expliziten Verifikationsbefehlen hinzu und führe denselben Agenten erneut aus. Vergleiche die Ergebnisse und ordne jeden Fehler einer der fünf Verteidigungsschichten zu.++2. **Messung der Verification Gap**: Wähle 5 Coding-Aufgaben. Notiere nach jeder Aufgabe, ob der Agent Abschluss behauptet, und prüfe anschließend die tatsächliche Korrektheit mit unabhängigen Tests. Berechne den Anteil der Fälle, in denen der Agent "fertig" sagt, obwohl er es tatsächlich nicht ist - das ist deine Verification Gap. Überlege dann: Welche Verifikationsbefehle würden diesen Anteil senken?++3. **Übung zur Diagnoseschleife**: Finde eine Aufgabe, bei der der Agent in deinem Projekt wiederholt scheitert. Führe sie einmal aus und protokolliere den Fehler. Ordne ihn einer der fünf Schichten zu. Repariere diese Schicht. Führe erneut aus. Wiederhole das drei bis fünf Runden und dokumentiere die Verbesserungen nach jeder Runde.diff --git a/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.mdnew file mode 100644index 0000000..5e6c10d--- /dev/null+++ b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md@@ -0,0 +1,21 @@+# Harness-Komponenten Beispiel++Für einen Coding-Agenten, der in einem lokalen Repository arbeitet:++- Modell:+ das LLM selbst++- Harness:+ - System-Prompt+ - AGENTS.md+ - Bash-Tool+ - Datei-Lese-/Schreib-Tools+ - Git-Zugriff+ - Lokales Dateisystem+ - Startup-Skripte+ - Test-Befehle+ - Stop-Hooks+ - Lint-Prüfungen+ - Evaluator-Schleife++Wenn Sie eines der obigen Harness-Elemente ändern, ändern Sie den effektiven Agenten.diff --git a/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.tsnew file mode 100644index 0000000..d856ba3--- /dev/null+++ b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts@@ -0,0 +1,180 @@+/**+ * harness-vs-no-harness.ts+ *+ * Side-by-side comparison of the same task executor running with and without+ * a harness. The harness version adds explicit rules, verification steps,+ * and stop conditions.+ *+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts+ */++// ---------------------------------------------------------------------------+// Types & helpers+// ---------------------------------------------------------------------------++interface TaskResult {+ name: string;+ passed: boolean;+ durationMs: number;+ issues: string[];+}++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++// ---------------------------------------------------------------------------+// Simulated task executor+// ---------------------------------------------------------------------------++/** A simple task that can succeed or fail depending on rules. */+type Task = {+ name: string;+ requiresAuth: boolean;+ hasTests: boolean;+ withinScope: boolean;+};++const tasks: Task[] = [+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },+];++// ---------------------------------------------------------------------------+// Run WITHOUT harness -- just execute every task, no checks+// ---------------------------------------------------------------------------++function runWithoutHarness(taskList: Task[]): TaskResult[] {+ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];++ // The "agent" does the work and calls it done.+ let passed = true;++ // Problems that go undetected without a harness+ if (t.requiresAuth && !t.hasTests) {+ issues.push("No tests for auth-protected endpoint");+ // Agent doesn't notice -- marks as pass anyway+ }+ if (!t.withinScope) {+ issues.push("Task is outside current scope");+ // Agent doesn't notice+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Run WITH harness -- rules, verification, stop conditions+// ---------------------------------------------------------------------------++function runWithHarness(taskList: Task[]): TaskResult[] {+ const rules = {+ requireTestsForAuth: true,+ enforceScope: true,+ };++ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];+ let passed = true;++ // Rule: auth endpoints must have tests+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {+ issues.push("BLOCKED: Auth-protected endpoint missing tests");+ passed = false;+ }++ // Rule: stay in scope+ if (rules.enforceScope && !t.withinScope) {+ issues.push("BLOCKED: Task outside active scope -- skipped");+ passed = false;+ }++ // Verification: re-check after execution+ if (passed && !t.hasTests) {+ issues.push("WARNING: No tests exist for this change");+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function printComparison(+ noHarness: TaskResult[],+ withHarness: TaskResult[]+): void {+ console.log("\n" + "=".repeat(80));+ console.log(" HARNESS vs NO-HARNESS COMPARISON");+ console.log("=".repeat(80));++ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;++ console.log("\n" + header);+ console.log(sep);++ for (let i = 0; i < noHarness.length; i++) {+ const nh = noHarness[i];+ const wh = withHarness[i];+ const nhPass = nh.passed ? "PASS" : "FAIL";+ const whPass = wh.passed ? "PASS" : "FAIL";+ const nhIssue = nh.issues[0] ?? "(none)";+ const whIssue = wh.issues[0] ?? "(none)";++ console.log(+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`+ );+ }++ // Metrics+ const nhPassed = noHarness.filter((r) => r.passed).length;+ const whPassed = withHarness.filter((r) => r.passed).length;+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);++ console.log("\n" + "=".repeat(80));+ console.log(" SUMMARY METRICS");+ console.log("=".repeat(80));++ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log("\n" + metricsHeader);+ console.log(metricsSep);+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);++ console.log("\n The harness catches problems the no-harness run silently ignores.");+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");+}++/** Count tasks that actually pass (have tests and are in scope). */+function truePassCount(results: TaskResult[]): number {+ return results.filter((r) => r.passed && r.issues.length === 0).length;+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparison(runWithoutHarness(tasks), runWithHarness(tasks));diff --git a/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/index.mdnew file mode 100644index 0000000..25af2eb--- /dev/null+++ b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 02++Verwenden Sie diesen Ordner für kleine Beispiele, die Folgendes unterscheiden:++- Modellverhalten+- Harness-Verhalten+- Nur-Prompt-Setups+- Umgebungsgestützte Agent-Setupsdiff --git a/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.tsnew file mode 100644index 0000000..e56cddd--- /dev/null+++ b/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts@@ -0,0 +1,36 @@+type Message = {+ role: "user" | "assistant";+ content: string;+};++type ToolResult = {+ ok: boolean;+ output: string;+};++function runTool(name: string, input: string): ToolResult {+ if (name === "read_file") {+ return { ok: true, output: `contents of ${input}` };+ }++ return { ok: false, output: `unknown tool: ${name}` };+}++export function minimalHarness(messages: Message[]) {+ const nextAction = {+ tool: "read_file",+ input: "README.md"+ };++ const result = runTool(nextAction.tool, nextAction.input);++ return {+ messages: [+ ...messages,+ {+ role: "assistant",+ content: `Tool ${nextAction.tool} returned: ${result.output}`+ }+ ]+ };+}diff --git a/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.mdnew file mode 100644index 0000000..6487c57--- /dev/null+++ b/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -0,0 +1,109 @@+[中文版本 →](../../../zh/lectures/lecture-02-what-a-harness-actually-is/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-02-what-a-harness-actually-is/code/)+> Praxisprojekt: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# Lektion 02. Was harness wirklich bedeutet++Das Wort „harness" wird in Kreisen von KI-Coding-Agenten viel herumgereicht, aber ganz ehrlich: Die meisten Menschen meinen einfach „eine Prompt-Datei", wenn sie harness sagen. Das ist kein harness. Das ist, als würde man ein Restaurant mit nichts als Zutaten eröffnen — kein Herd, keine Messer, keine Rezepte, kein Anrichte-Workflow. Das ist kein Restaurant. Das ist ein Kühlschrank.++Diese Lektion gibt Ihnen eine präzise, umsetzbare harness-Definition. Keine akademische Abstraktion, sondern ein Framework, das Sie heute nutzen können: Ein harness besteht aus fünf Subsystemen, jedes mit klaren Zuständigkeiten und Bewertungskriterien.++## Beginnen wir mit einer Analogie++Stellen Sie sich vor, Sie sind ein neu eingestellter Ingenieur, der ohne jegliche Dokumentation in ein Projekt geworfen wird. Kein README, keine Kommentare im Code, niemand sagt Ihnen, wie man Tests ausführt, die CI-Konfiguration ist irgendwo vergraben. Können Sie guten Code schreiben? Vielleicht — wenn Sie klug und geduldig genug sind. Aber Sie werden enorme Zeit damit verbringen, herauszufinden, „worum es in diesem Projekt geht", anstatt „das Problem zu lösen".++Ein KI-Agent steht vor genau derselben Situation. Und es ist noch schlimmer — Sie können wenigstens einen Kollegen fragen. Der Agent kann nur die Dateien sehen, die Sie ihm vorlegen, und die Befehle ausführen, die ihm zur Verfügung stehen. Er kann niemanden auf die Schulter tippen und fragen: „Hey, welche Version des ORMs verwendet dieses Projekt?"++OpenAI formuliert das Kernprinzip als „the repo IS the spec" — der gesamte notwendige Kontext sollte im Repository enthalten sein, geliefert durch strukturierte Instruktionsdateien, explizite Verifizierungsbefehle und eine klare Verzeichnisorganisation. Anthropics Dokumentation zu langlebigen Agenten betont Zustandspersistenz, explizite Wiederherstellungspfade und strukturiertes Fortschritts-Tracking. Die beiden Unternehmen konzentrieren sich auf unterschiedliche Aspekte, aber sie sagen dasselbe: **alles in der Engineering-Infrastruktur außerhalb des Modells bestimmt, wie viel der Modelfähigkeiten tatsächlich realisiert werden.**++Betrachten Sie einige Tools, die Sie bereits kennen:++**Claude Code** verkörpert das harness-Denken. Es liest `CLAUDE.md` aus Ihrem Repo (Rezeptregal), kann Shell-Befehle ausführen (Messerblock), arbeitet in Ihrer lokalen Umgebung (Herd), verwaltet Sitzungsverläufe (Vorbereitungsstation) und kann Tests ausführen und Ergebnisse sehen (Qualitätskontrollfenster). Aber wenn Sie ihm nicht sagen, wie man Tests ausführt, ist das Qualitätskontrollfenster kaputt — niemand weiß, ob das Gericht gar ist.++**Cursor** folgt einer ähnlichen Logik. Seine `.cursorrules`-Datei ist das Rezeptregal, das Terminal ist der Messerblock, es liest Ihre Projektstruktur und Lint-Konfiguration für den Herd. Aber Cursors Zustandsverwaltung ist relativ schwach — IDE schließen und wieder öffnen, und der vorherige Kontext ist verschwunden.++**Codex** (OpenAIs Coding-Agent) verwendet git worktrees, um die Laufzeitumgebung jeder Aufgabe zu isolieren, gepaart mit einem lokalen Observability-Stack (Logs, Metriken, Traces), sodass jede Änderung in einer unabhängigen Umgebung verifiziert wird. In Repos mit `AGENTS.md` und klaren Verifizierungsbefehlen funktioniert er deutlich besser als in „nackten" Repos.++**AutoGPT** ist das abschreckende Beispiel — fehlendes strukturiertes Zustandsmanagement führt bei langen Aufgaben zu Kontextakkumulation, und fehlende präzise Feedback-Mechanismen verursachen Endlosschleifen beim Agenten. Viele sagen, AutoGPT „funktioniert nicht", aber in Wirklichkeit funktioniert AutoGPTs harness nicht — geben Sie einem Koch einen kaputten Herd, und selbst die besten Zutaten werden kein Essen produzieren.++## Zentrale Konzepte++- **Was ist ein harness**: Alles in der Engineering-Infrastruktur außerhalb der Modellgewichte. OpenAI destilliert die Kernaufgabe des Ingenieurs in drei Dinge: Umgebungen gestalten, Intention ausdrücken und Feedback-Schleifen aufbauen. Anthropic nennt sein Claude Agent SDK ein „general-purpose agent harness."+- **Das Repo ist die einzige Quelle der Wahrheit**: Alles, was der Agent nicht sehen kann, existiert für alle praktischen Zwecke nicht. OpenAI behandelt das Repo als „system of record" — der gesamte notwendige Kontext muss dort leben, durch strukturierte Dateien und klare Verzeichnisorganisation.+- **Eine Karte geben, kein Handbuch**: OpenAIs Erfahrung — `AGENTS.md` sollte eine Übersichtsseite sein, keine Enzyklopädie. Etwa 100 Zeilen reichen aus. Wenn es nicht passt, teilen Sie es in das `docs/`-Verzeichnis auf und lassen Sie den Agenten bei Bedarf lesen.+- **Einschränken, nicht mikroverwalten**: Ein gutes harness verwendet ausführbare Regeln, um den Agenten einzuschränken, anstatt Anweisungen einzeln aufzuzählen. OpenAI sagt „enforce invariants, don't micromanage implementation"; Anthropic hat festgestellt, dass Agenten ihre eigene Arbeit zuversichtlich loben, und die Lösung darin besteht, „die Person, die die Arbeit erledigt" von „der Person, die die Arbeit prüft" zu trennen.+- **Komponenten einzeln entfernen**: Um den Wert jeder harness-Komponente zu quantifizieren, entfernen Sie sie einzeln und prüfen Sie, welche Entfernung den größten Leistungsabfall verursacht. Anthropic hat diese Methode angewandt und festgestellt, dass mit stärker werdenden Modellen einige Komponenten aufhören, kritisch zu sein — aber neue tauchen immer auf.++## Das Fünf-Subsystem-harness-Modell++Zurück zur Küchenanalogie. Eine vollständige Küche hat fünf Funktionsbereiche, und ein harness hat fünf Subsysteme:++```mermaid+flowchart LR+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["Tools<br/>shell / files / tests"]+ Tools --> Env["Runtime<br/>deps / services / versions"]+ Env --> Checks["Check results<br/>test / lint / build"]+ Checks --> Agent+```++**Instruktions-Subsystem (Rezeptregal)**: Erstellen Sie `AGENTS.md` (oder `CLAUDE.md`) mit einer Projektübersicht und einem Zweck (ein Satz), Tech-Stack und Versionen (Python 3.11, FastAPI 0.100+, PostgreSQL 15), Erststart-Befehlen (`make setup`, `make test`), nicht verhandelbaren harten Einschränkungen („Alle APIs müssen OAuth 2.0 verwenden") und Links zu detaillierterer Dokumentation.++**Tool-Subsystem (Messerblock)**: Stellen Sie sicher, dass der Agent ausreichenden Tool-Zugriff hat. Deaktivieren Sie die Shell nicht aus „Sicherheitsgründen" — wenn der Agent nicht einmal `pip install` ausführen kann, wie soll er dann arbeiten? Aber öffnen Sie auch nicht alles — folgen Sie dem Prinzip der geringsten Rechte.++**Umgebungs-Subsystem (Herd)**: Machen Sie den Umgebungszustand selbstbeschreibend. Verwenden Sie `pyproject.toml` oder `package.json` zum Sperren von Abhängigkeiten, `.nvmrc` oder `.python-version` für Laufzeitversionen, Docker oder Devcontainer für Reproduzierbarkeit.++**Zustands-Subsystem (Vorbereitungsstation)**: Lange Aufgaben benötigen Fortschritts-Tracking. Verwenden Sie eine einfache `PROGRESS.md`-Datei, die Folgendes dokumentiert: was erledigt ist, was in Arbeit ist, was blockiert ist. Aktualisieren Sie vor jedem Sitzungsende, lesen Sie beim Start der nächsten Sitzung.++**Feedback-Subsystem (Qualitätskontrollfenster)**: Dies ist das Subsystem mit dem höchsten ROI. Listen Sie Verifizierungsbefehle explizit in `AGENTS.md` auf:+```+Verification commands:+- Tests: pytest tests/ -x+- Type check: mypy src/ --strict+- Lint: ruff check src/+- Full verification: make check (includes all above)+```++Wenn ein Subsystem fehlt, ist das wie ein fehlender Funktionsbereich in der Küche — Sie können immer noch kochen, aber es ist immer umständlich.++**harness-Qualität diagnostizieren**: Verwenden Sie „isometrische Modellkontrolle". Halten Sie das Modell fest, entfernen Sie Subsysteme einzeln, messen Sie, welche Entfernung den größten Leistungsabfall verursacht. Das ist Ihr Engpass — konzentrieren Sie Ihre Mühe darauf. Wie bei der Suche nach dem Engpass in einer Küche: Nehmen Sie das Rezeptregal weg und sehen Sie, wie viel langsamer alles wird, schalten Sie den Herd ab und beobachten Sie die Auswirkungen.++## Die wahre Geschichte eines Teams++Ein Team verwendete GPT-4o für eine TypeScript + React Frontend-App (~20.000 Zeilen Code). Sie durchliefen vier Stufen — im Grunde rüsteten sie die Küche Stück für Stück aus:++**Stufe 1 — Leere Küche**: Nur eine einfache Projektbeschreibung im README. 1 von 5 Durchläufen erfolgreich (20%). Hauptsächliche Fehler: falschen Package-Manager gewählt (npm vs. yarn), Komponenten-Benennungskonventionen nicht befolgt, konnte Tests nicht ausführen.++**Stufe 2 — Rezeptregal installiert**: `AGENTS.md` mit Tech-Stack-Versionen, Namenskonventionen und wichtigen Architekturentscheidungen hinzugefügt. Erfolgsquote stieg auf 60%. Verbleibende Fehler waren hauptsächlich Umgebungsprobleme und fehlende Verifizierung.++**Stufe 3 — Qualitätskontrollfenster geöffnet**: Verifizierungsbefehle in `AGENTS.md` aufgelistet: `yarn test && yarn lint && yarn build`. Erfolgsquote stieg auf 80%.++**Stufe 4 — Vorbereitungsstation bereit**: Fortschrittsdatei-Vorlagen eingeführt, in denen Agenten bei jedem Durchlauf abgeschlossene und nicht abgeschlossene Arbeit dokumentierten. Erfolgsquote stabilisierte sich bei 80–100%.++Vier Iterationen, das Modell hat sich gar nicht geändert, die Erfolgsquote stieg von 20% auf nahezu 100%. Das ist die Macht von harness Engineering. Sie haben keine teureren Zutaten gekauft — Sie haben die Küche einfach richtig organisiert.++## Wichtigste Erkenntnisse++- Harness = Instructions + Tools + Environment + State + Feedback. Fünf Subsysteme, wie die fünf Funktionsbereiche einer Küche — alle unverzichtbar.+- Wenn es keine Modellgewichte sind, ist es harness. Ihr harness bestimmt, wie viel der Modelfähigkeiten realisiert wird.+- Unter den fünf Subsystemen hat das Feedback-Subsystem normalerweise die geringste Investition und die höchste Rendite. Bringen Sie zuerst Ihre Verifizierungsbefehle in Ordnung — das Qualitätskontrollfenster ist das lohnendste Upgrade.+- Verwenden Sie „isometrische Modellkontrolle", um den Grenznutzen jedes Subsystems zu quantifizieren — gehen Sie nicht nach Bauchgefühl.+- Harness verrottet wie Code. Überprüfen Sie regelmäßig und tilgen Sie harness-Schulden wie Sie technische Schulden tilgen.++## Weiterführende Literatur++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)++## Übungen++1. **Fünftupel-harness-Audit**: Nehmen Sie ein Projekt, in dem Sie einen KI-Agenten verwenden, und führen Sie ein vollständiges Audit mit dem Fünftupel-Framework durch. Bewerten Sie jedes Subsystem mit 1–5. Finden Sie das am niedrigsten bewertete Subsystem, investieren Sie 30 Minuten in die Verbesserung und beobachten Sie die Veränderung der Agentenleistung.++2. **Isometrisches Modellkontrollexperiment**: Wählen Sie ein Modell und eine anspruchsvolle Aufgabe. Entfernen Sie nacheinander Instruktionen (AGENTS.md löschen), Feedback entfernen (keine Verifizierungsbefehle angeben), Zustand entfernen (keine Fortschrittsdateien) — entfernen Sie jeweils nur eines und messen Sie den Leistungsabfall. Ordnen Sie basierend auf den Ergebnissen die Subsystem-Wichtigkeit für Ihr Projekt.++3. **Affordanz-Analyse**: Finden Sie ein Szenario, in dem der Agent in Ihrem Projekt „etwas tun möchte, aber nicht kann" (z. B. weiß, dass er parametrisierte Abfragen verwenden sollte, aber die ORM-Muster Ihres Projekts nicht kennt). Analysieren Sie, ob dies eine Gulf of Execution (weiß nicht wie) oder Gulf of Evaluation (weiß nicht, ob es richtig ist) ist, und entwerfen Sie dann eine harness-Verbesserung, um die Lücke zu schließen.diff --git a/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdnew file mode 100644index 0000000..182027a--- /dev/null+++ b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md@@ -0,0 +1,7 @@+# Code für Vorlesung 03++Verwenden Sie diesen Ordner für Beispiele zu:++- Agenten-lesbaren Repository-Strukturen+- Dokumentation als System of Record+- Schlechte vs. gute Platzierung von Wissendiff --git a/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txtnew file mode 100644index 0000000..45315da--- /dev/null+++ b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt@@ -0,0 +1,13 @@+AGENTS.md+docs/+ ARCHITECTURE.md+ PRODUCT.md+ RELIABILITY.md+ references/+ electron.md+ sqlite.md+ plans/+ active/+ completed/+src/+scripts/diff --git a/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.tsnew file mode 100644index 0000000..46f6a62--- /dev/null+++ b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts@@ -0,0 +1,189 @@+/**+ * repo-reader.ts+ *+ * Reads a directory structure and scores it on discoverability.+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,+ * handoff files, and other signals of a repository that serves as the+ * system of record.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]+ * (defaults to current working directory if no path given)+ *+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Scoring criteria+// ---------------------------------------------------------------------------++interface Check {+ name: string;+ description: string;+ maxPoints: number;+ check: (dir: string) => { points: number; found: string[]; missing: string[] };+}++const checks: Check[] = [+ {+ name: "AGENTS.md / CLAUDE.md",+ description: "Agent-readable instruction file at repo root",+ maxPoints: 15,+ check: (dir) => {+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };+ },+ },+ {+ name: "Documentation directory",+ description: "Dedicated docs/ or documentation/ directory",+ maxPoints: 10,+ check: (dir) => {+ const candidates = ["docs", "documentation", "doc"];+ const found = candidates.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };+ },+ },+ {+ name: "Architecture documentation",+ description: "Files describing system architecture",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",+ "docs/architecture/", "design.md", "DESIGN.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };+ },+ },+ {+ name: "Feature tracking",+ description: "Feature list or task tracking file",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "feature_list.json", "features.md", "FEATURES.md",+ "docs/features.md", "tasks.json", "TODO.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };+ },+ },+ {+ name: "Handoff / session continuity",+ description: "Files for multi-session continuity",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",+ "docs/handoff.md", ".handoff", "PROGRESS.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };+ },+ },+ {+ name: "Testing structure",+ description: "Test directory or test configuration",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["test", "tests", "__tests__", "spec"];+ const found = patterns.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };+ },+ },+ {+ name: "Configuration files",+ description: "Project config (package.json, tsconfig, etc.)",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };+ },+ },+ {+ name: "README",+ description: "Root README file",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["README.md", "README.rst", "README.txt", "README"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };+ },+ },+];++// ---------------------------------------------------------------------------+// Report generation+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function scoreRepo(targetDir: string): void {+ const resolved = path.resolve(targetDir);++ if (!fs.existsSync(resolved)) {+ console.error(` Error: Directory not found: ${resolved}`);+ process.exit(1);+ }++ console.log("\n" + "=".repeat(80));+ console.log(" REPOSITORY DISCOVERABILITY SCORE");+ console.log("=".repeat(80));+ console.log(` Target: ${resolved}\n`);++ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ let totalScore = 0;+ let maxScore = 0;++ for (const check of checks) {+ const result = check.check(resolved);+ totalScore += result.points;+ maxScore += check.maxPoints;+ const status = result.points > 0 ? "PASS" : "FAIL";+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];++ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);+ }++ // Final score+ console.log("\n" + "-".repeat(80));+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);++ // Grade+ const pct = totalScore / maxScore;+ let grade: string;+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";+ else grade = "F -- Repository lacks discoverability signals";++ console.log(` GRADE: ${grade}`);+ console.log("=".repeat(80) + "\n");+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const target = process.argv[2] || process.cwd();+scoreRepo(target);diff --git a/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.mdnew file mode 100644index 0000000..ecfc3fe--- /dev/null+++ b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md@@ -0,0 +1,11 @@+# System-of-Record Checkliste++Kann ein neuer Agent Folgendes nur aus dem Repository herausfinden?++- Welches Produkt entwickelt wird?+- Was die App für Benutzer tun soll?+- Wie die Codebase organisiert ist?+- Wie die App gestartet wird?+- Wie der Zustand geprüft wird?+- Welche Arbeit aktuell in Bearbeitung ist?+- Welche Qualitätsstandards wichtig sind?diff --git a/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdnew file mode 100644index 0000000..18d5141--- /dev/null+++ b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -0,0 +1,137 @@+[中文版本 →](../../../zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)+> Praxisprojekt: [Projekt 02. Agentenlesbarer Workspace](./../../projects/project-02-agent-readable-workspace/index.md)++# Lektion 03. Das Repository zur einzigen Quelle der Wahrheit machen++Die Architekturentscheidungen deines Teams sind über Confluence, Slack, Jira und die Köpfe einiger Senior Engineers verstreut. Für Menschen funktioniert das gerade so: Man kann Kolleginnen fragen, Chatverläufe durchsuchen, Dokumente ausgraben. Wenn alles scheitert, kann man jemanden im Pausenraum abfangen. Für einen KI-Agenten aber existiert Information, die nicht im Repository steht, schlicht nicht.++Das ist keine Übertreibung. Denk darüber nach, was die Eingaben eines Agenten tatsächlich sind: Systemprompts und Aufgabenbeschreibungen, Dateiinhalte aus dem Repository und Tool-Ausgaben. Das war's. Deine Slack-Historie, Jira-Tickets, Confluence-Seiten und die Architekturentscheidung, die du am Freitagnachmittag bei Kaffee mit einem Kollegen besprochen hast - der Agent sieht nichts davon. Er kann nicht "jemanden fragen" oder "den Chatverlauf durchsuchen". Er ist ein Engineer, der im Repository eingeschlossen ist. Alles außerhalb kennt er nicht.++Die Frage lautet also: Gibst du diesem Engineer eine gute Karte?++## Was auf die Karte gehört++OpenAI formuliert es sehr direkt: **Information, die nicht im Repo existiert, existiert für den Agenten nicht.** Sie nennen das das Prinzip "repo as spec" - das Repository selbst ist das Spezifikationsdokument mit der höchsten Autorität.++Anthropics Dokumentation zu lang laufenden Agenten sagt dasselbe: Persistenter Zustand ist eine notwendige Bedingung für Kontinuität bei langen Aufgaben. Die Wiederherstellbarkeit von Wissen über Sitzungen hinweg bestimmt direkt die Erfolgsraten. Und dieser Zustand muss im Repository existieren, denn das ist der einzige stabile, zugängliche Speicher, den der Agent hat.++Vielleicht denkst du: "Unser Team ist klein, das Wissen steckt in allen Köpfen, und das funktioniert." Für Menschen, ja. Aber wenn du einen Agenten nutzt, akzeptiere diese Tatsache: Der Agent kann keine Menschen fragen. Alles, was er wissen muss, muss aufgeschrieben und dort abgelegt sein, wo er es finden kann.++Es geht nicht darum, "mehr Dokumentation zu schreiben". Es geht darum, "Entscheidungsinformationen an den richtigen Ort zu bringen". Eine 50-zeilige `ARCHITECTURE.md` im Verzeichnis `src/api/` ist zehntausendmal nützlicher als ein 500-seitiges Design-Dokument in Confluence, das niemand pflegt. Es ist wie eine handgezeichnete Bürokarte, die an deinem Schreibtisch klebt, gegenüber einem wunderschönen Architekturplan, der in einem Aktenschrank eingeschlossen ist: Erstere ist da, wenn du sie brauchst; Letzterer ist technisch überlegen, aber im Moment nutzlos.++## Wissenssichtbarkeit++```mermaid+flowchart LR+ Slack["Regeln in Slack"] --> Write["In Repo-Dateien schreiben<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Regeln in Confluence"] --> Write+ Heads["Regeln in Köpfen von Menschen"] --> Write+ Jira["Regeln in Jira-Tickets"] --> Write+ Write --> Repo["Repository-Dateien"]+ Repo --> Agent["Neue Agentensitzung<br/>liest das Repo direkt"]+ Warning["Wenn eine Regel nicht im Repo steht,<br/>kann der Agent sie nicht sehen"] --> Agent+```++Wie testest du, ob deine Karte gut genug ist? Führe einen "Cold-Start-Test" aus: Öffne eine komplett neue Agentensitzung, die nur Repository-Inhalte nutzt, und prüfe, ob sie fünf grundlegende Fragen beantworten kann:++```mermaid+flowchart TB+ Q1["Was ist dieses System?"] --> A1["AGENTS.md / README"]+ Q2["Wie ist es organisiert?"] --> A2["ARCHITECTURE.md / Modul-Dokumente"]+ Q3["Wie führe ich es aus?"] --> A3["Makefile / init.sh / package scripts"]+ Q4["Wie verifiziere ich es?"] --> A4["Test-, Lint- und Check-Befehle"]+ Q5["Wo stehen wir gerade?"] --> A5["PROGRESS.md / feature list / git history"]++ A1 --> Ready["Eine neue Sitzung kann starten<br/>ohne einen Menschen zu fragen"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready+```++Wenn sie das nicht beantworten kann, hat die Karte weiße Flecken. Wo die Karte leer ist, rät der Agent. Falsche Vermutungen werden zu Bugs, zu viel Raten verschwendet Kontext. Und jede neue Sitzung rät erneut. Die Kosten des Ratens sind immer höher als die Kosten, die Karte gleich richtig zu zeichnen.++## Zentrale Konzepte++- **Knowledge Visibility Gap**: Der Anteil des gesamten Projektwissens, der NICHT im Repository steht. Je größer die Lücke, desto höher die Fehlerrate des Agenten. Wie viel implizites Wissen über dieses Projekt lebt in deinem Kopf? Zähle alles und schau dann, wie viel davon im Repo angekommen ist. Die Differenz ist deine Sichtbarkeitslücke.+- **System of Record**: Das Code-Repository als autoritative Quelle für Projektentscheidungen, Architekturconstraints, Ausführungszustand und Verifikationsstandards. Das Repo hat das letzte Wort; nichts anderes zählt. Wie eine Karte mit "Straße gesperrt": Du fährst diese Straße nicht. Wenn diese Information aber nur im Kopf einer Person existiert, musst du jedes Mal fragen.+- **Cold-Start Test**: Die fünf Fragen oben. Wie viele beantwortet werden können, zeigt, wie vollständig deine Karte ist.+- **Discovery Cost**: Wie viel Kontextbudget der Agent verbrennt, um eine zentrale Information im Repo zu finden. Je versteckter die Information, desto höher die Discovery Cost und desto weniger Budget bleibt für die eigentliche Aufgabe. Kritische Information in einer README zehn Verzeichnisebenen tief zu verstecken ist wie den Feuerlöscher in einem Tresor im Keller einzuschließen: Er existiert, aber du findest ihn nicht, wenn du ihn brauchst.+- **Knowledge Decay Rate**: Der Anteil der Wissenseinträge, der pro Zeiteinheit veraltet. Dokumentation, die nicht mehr mit dem Code synchron ist, ist der größte Feind - schlimmer als gar keine Dokumentation.+- **ACID Analogy**: Datenbank-Transaktionsprinzipien (Atomicity, Consistency, Isolation, Durability) auf Agentenzustandsverwaltung anwenden. Unten wird das ausgeführt.++## Wie man eine gute Karte zeichnet++**Prinzip 1: Wissen lebt neben dem Code.** Eine Regel zur Authentifizierung von API-Endpunkten gehört neben den API-Code, nicht in ein riesiges globales Dokument. Lege in jedem Modulverzeichnis ein kurzes Dokument ab, das Verantwortlichkeiten, Schnittstellen und besondere Constraints des Moduls erklärt. Wie Regalbeschriftungen in einer Bibliothek: Wenn du Geschichtsbücher willst, gehst du direkt zum Regal "History". Du musst nicht die ganze Bibliothek durchsuchen.++**Prinzip 2: Nutze eine standardisierte Einstiegsdatei.** `AGENTS.md` (oder `CLAUDE.md`) ist die Landing Page des Agenten. Sie muss nicht alle Informationen enthalten, aber sie muss dem Agenten erlauben, drei Fragen schnell zu beantworten: "Was ist dieses Projekt?", "Wie führe ich es aus?" und "Wie verifiziere ich es?" 50-100 Zeilen reichen.++**Prinzip 3: Minimal, aber vollständig.** Jedes Wissensstück sollte einen klaren Use Case haben. Wenn das Entfernen einer Regel die Entscheidungsqualität des Agenten nicht beeinträchtigt, sollte diese Regel nicht existieren. Aber jede Frage aus dem Cold-Start-Test muss eine Antwort haben. Das ist ein feines Gleichgewicht: nicht zu viel, nicht zu wenig, genau genug.++**Prinzip 4: Mit Code aktualisieren.** Kopple Wissensupdates an Codeänderungen. Der einfachste Ansatz: Architekturdocs im entsprechenden Modulverzeichnis ablegen. Wenn du Code änderst, siehst du das Dokument natürlich. Nach Codeänderungen kann CI daran erinnern zu prüfen, ob die Docs aktualisiert werden müssen.++**Konkrete Repo-Struktur**:++```+project/+├── AGENTS.md # Entry: project overview, run commands, hard constraints+├── src/+│ ├── api/+│ │ ├── ARCHITECTURE.md # API layer architecture decisions+│ │ └── ...+│ ├── db/+│ │ ├── CONSTRAINTS.md # Database operation hard constraints+│ │ └── ...+│ └── ...+├── PROGRESS.md # Current progress: done, in-progress, blocked+└── Makefile # Standardized commands: setup, test, lint, check+```++## Agentenzustand mit ACID-Prinzipien verwalten++Diese Analogie stammt aus dem Datenbank-Transaktionsmanagement. Du könntest denken, dass das überkompliziert ist, aber tatsächlich gibt es dir einen sehr praktischen Rahmen:++- **Atomicity**: Jede "logische Operation" (z. B. "neuen Endpoint hinzufügen und Tests aktualisieren") bekommt einen git commit. Wenn sie auf halbem Weg scheitert, mit `git stash` zurückrollen. Alles oder nichts - kein "halb fertig".+- **Consistency**: Definiere Verifikationsprädikate für einen "konsistenten Zustand": alle Tests grün, Lint meldet null Fehler. Der Agent führt nach jeder Operation Verifikation aus; inkonsistente Zwischenzustände werden nicht committed. Wie bei einer Banküberweisung: Du kannst nicht abbuchen, ohne gutzuschreiben.+- **Isolation**: Wenn mehrere Agenten gleichzeitig arbeiten, entwirf Zustandsdateien so, dass Race Conditions vermieden werden. Einfacher Ansatz: Jeder Agent nutzt seine eigene Progress-Datei, oder git branches sorgen für Isolation. Zwei Köche können nicht gleichzeitig denselben Topf würzen - wer ist verantwortlich, wenn er versalzen ist?+- **Durability**: Kritisches Projektwissen lebt in git-getrackten Dateien. Temporärer Zustand kann im Sitzungspeicher bleiben, aber sitzungsübergreifendes Wissen muss in Dateien persistiert werden. Was in deinem Kopf ist, zählt nicht - nur was auf Papier steht, zählt.++## Eine echte Transformationsgeschichte++Ein Team betreute eine E-Commerce-Plattform mit etwa 30 Microservices. Architekturentscheidungen (Inter-Service-Kommunikationsprotokolle, Datenkonsistenzstrategien, API-Versionierungsregeln) waren verstreut über Confluence (teilweise veraltet), Slack (schwer zu durchsuchen), die Köpfe einiger Senior Engineers (nicht skalierbar) und sporadische Codekommentare (nicht systematisch).++Nach der Einführung von KI-Agenten erforderten 70% der Aufgaben menschliche Intervention. Fast jeder Fehler hing damit zusammen, dass der Agent gegen eine implizite Constraint verstieß, die "alle kennen, aber niemand aufgeschrieben hat". Wie bei einem neuen Mitarbeitenden, dem niemand gesagt hat: "Du musst deine Essensbestellung in den Gruppenchat posten." Er rät falsch, wird zurechtgewiesen, aber danach schreibt immer noch niemand die Regel auf.++Das Team führte eine Transformation durch:+1. `AGENTS.md` im Repo-Root erstellt, mit Projektüberblick, Tech-Stack-Versionen und globalen harten Constraints+2. `ARCHITECTURE.md` in jedem Microservice-Verzeichnis hinzugefügt, mit Verantwortlichkeiten, Schnittstellen und Abhängigkeiten+3. Zentrales `CONSTRAINTS.md` mit harten Constraints in expliziter "MUST/MUST NOT"-Sprache erstellt+4. `PROGRESS.md` in jedem Service-Verzeichnis hinzugefügt, um aktuellen Arbeitsstatus zu verfolgen++Nach der Transformation konnte derselbe Agent beim Cold Start alle zentralen Projektfragen beantworten, und die Qualität der Aufgabenabschlüsse verbesserte sich deutlich.++## Wichtigste Erkenntnisse++- Wissen, das nicht im Repo steht, existiert für den Agenten nicht. Kritische Entscheidungen ins Repo zu legen ist die grundlegendste Harness-Investition: Zeichne eine gute Karte, damit du dich nicht verläufst.+- Nutze den "Cold-Start-Test", um Repo-Qualität zu bewerten: Kann eine frische Sitzung fünf grundlegende Fragen nur mit Repo-Inhalten beantworten?+- Wissen sollte nahe am Code liegen, minimal aber vollständig sein und mit dem Code aktualisiert werden. Es geht nicht darum, mehr Docs zu schreiben, sondern Information an den richtigen Ort zu bringen.+- Nutze ACID-Prinzipien für Agentenzustand: atomare Commits, Konsistenzverifikation, Parallelitätsisolation, dauerhaftes kritisches Wissen.+- Wissensverfall ist der größte Feind. Dokumentation, die nicht mit dem Code synchron ist, ist gefährlicher als keine Dokumentation: Sie schickt den Agenten in die falsche Richtung, während er glaubt, richtig zu liegen.++## Weiterführende Literatur++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [ADR: Architecture Decision Records](https://adr.github.io/)+- [The Twelve-Factor App](https://12factor.net/)++## Übungen++1. **Cold-Start-Test**: Öffne in deinem Projekt eine komplett frische Agentensitzung (kein verbaler Kontext, nur Repo-Inhalte). Stelle fünf Fragen: Was ist dieses System? Wie ist es organisiert? Wie führe ich es aus? Wie verifiziere ich es? Was ist der aktuelle Fortschritt? Notiere, was nicht beantwortet werden kann, und verbessere das Repo, bis es geht.++2. **Quantifizierung der Wissensexternalisierung**: Liste alle Entscheidungen und Constraints auf, die für Entwicklungsarbeit in deinem Projekt wichtig sind. Markiere jedes Element als innerhalb oder außerhalb des Repos. Berechne deine Knowledge Visibility Gap (Anteil außerhalb des Repos). Erstelle einen Plan, um sie unter 10% zu bringen.++3. **ACID-Bewertung**: Bewerte die Zustandsverwaltung deines Projekts anhand der ACID-Analogie dieser Lektion. Atomicity - Können Agentenoperationen sauber zurückgerollt werden? Consistency - Gibt es Verifikation eines "konsistenten Zustands"? Isolation - Treten sich parallele Agenten gegenseitig auf die Füße? Durability - Ist alles sitzungsübergreifende Wissen persistiert?diff --git a/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdnew file mode 100644index 0000000..4801b51--- /dev/null+++ b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -0,0 +1,15 @@+# AGENTS.md++## Start hier++- Lies `docs/ARCHITECTURE.md`+- Lies `docs/PRODUCT.md`+- Verwende `npm run dev` zum Starten der App+- Verwende `npm run check` bevor du Arbeit als abgeschlossen markierst++## Strenge Regeln++- Ändere nicht die Electron main/preload/renderer-Grenzen ohne+ `docs/ARCHITECTURE.md` gelesen zu haben+- Markiere kein Feature als abgeschlossen ohne Verifikation+- Hinterlasse einen sauberen Zustand (clean state) für die nächste Sessiondiff --git a/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdnew file mode 100644index 0000000..8987347--- /dev/null+++ b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -0,0 +1,7 @@+# Anti-Patterns für Instruktionsdateien++- Alles Repository-Wissen in eine Datei packen+- Dieselbe Regel an mehreren Stellen wiederholen+- Veraltete Regeln kodieren, die niemand prüft+- So spezifische bedingte Anweisungen schreiben, dass sie selten zutreffen+- Lange Tool-Handbücher in den Startup-Kontext einbettendiff --git a/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdnew file mode 100644index 0000000..f77d102--- /dev/null+++ b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md@@ -0,0 +1,7 @@+# Code für Vorlesung 04++Verwenden Sie diesen Ordner für Beispiele zu:++- Monolithischen Instruktionsdateien+- Kurzen Einstiegspunkten+- Progressive-Disclosure-Musterndiff --git a/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.tsnew file mode 100644index 0000000..59a9632--- /dev/null+++ b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts@@ -0,0 +1,209 @@+/**+ * split-vs-monolithic.ts+ *+ * Creates a monolithic instruction file (~200 lines) and then shows how+ * splitting into 4 focused files dramatically reduces the context needed+ * for any single query. Simulates an "agent" searching for a specific rule+ * and measures how many lines it must read in each approach.+ *+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts+ */++// ---------------------------------------------------------------------------+// Simulated monolithic instruction file (200 lines of rules)+// ---------------------------------------------------------------------------++const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];++// Section 1: Project Overview (lines 1-50)+for (let i = 1; i <= 50; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Project Overview",+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,+ });+}++// Section 2: Code Style Rules (lines 51-100)+for (let i = 51; i <= 100; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Code Style",+ content:+ i === 72+ ? "RULE: Always use explicit return types on exported functions."+ : i === 78+ ? "RULE: Use const assertions for immutable arrays."+ : `Style rule detail line ${i}`,+ });+}++// Section 3: Testing Standards (lines 101-150)+for (let i = 101; i <= 150; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Testing",+ content:+ i === 120+ ? "RULE: Every new endpoint must have integration tests."+ : i === 135+ ? "RULE: Test files must mirror the source file structure."+ : `Testing detail line ${i}`,+ });+}++// Section 4: Deployment Rules (lines 151-200)+for (let i = 151; i <= 200; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Deployment",+ content:+ i === 175+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."+ : `Deployment detail line ${i}`,+ });+}++// ---------------------------------------------------------------------------+// Split instruction files (4 focused files)+// ---------------------------------------------------------------------------++const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),+};++// ---------------------------------------------------------------------------+// Simulated queries -- the agent needs to find specific rules+// ---------------------------------------------------------------------------++interface Query {+ description: string;+ targetRule: string;+ relevantSection: string;+}++const queries: Query[] = [+ {+ description: "Find the rule about return types",+ targetRule: "explicit return types",+ relevantSection: "Code Style",+ },+ {+ description: "Find the deployment window rule",+ targetRule: "deploy on Fridays",+ relevantSection: "Deployment",+ },+ {+ description: "Find the integration test rule",+ targetRule: "integration tests",+ relevantSection: "Testing",+ },+ {+ description: "Find the test file structure rule",+ targetRule: "mirror the source file",+ relevantSection: "Testing",+ },+];++// ---------------------------------------------------------------------------+// Search simulation+// ---------------------------------------------------------------------------++function searchMonolithic(query: Query): { linesRead: number; found: boolean } {+ // Agent must scan from the top, reading each line until it finds the rule.+ // In the worst case it reads all lines.+ let linesRead = 0;+ let found = false;++ for (const line of monolithicInstructions) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found };+}++function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {+ // Agent knows which file to look in based on the section.+ // It only reads lines from that one file.+ const fileMap: Record<string, string> = {+ "Project Overview": "01-project-overview.md",+ "Code Style": "02-code-style.md",+ Testing: "03-testing.md",+ Deployment: "04-deployment.md",+ };++ const targetFile = fileMap[query.relevantSection];+ const lines = splitInstructions[targetFile];+ let linesRead = 0;+ let found = false;++ for (const line of lines) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found, fileAccessed: targetFile };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");+ console.log("=".repeat(90));++ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");++ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;+ console.log(header);+ console.log(sep);++ let totalMono = 0;+ let totalSplit = 0;++ for (const q of queries) {+ const mono = searchMonolithic(q);+ const split = searchSplit(q);+ totalMono += mono.linesRead;+ totalSplit += split.linesRead;++ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);+ console.log(+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`+ );+ }++ console.log(sep);+ const avgMono = Math.round(totalMono / queries.length);+ const avgSplit = Math.round(totalSplit / queries.length);+ console.log(+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`+ );++ console.log("\n" + "=".repeat(90));+ console.log(" KEY INSIGHT");+ console.log("=".repeat(90));+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");+}++run();diff --git a/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdnew file mode 100644index 0000000..b775e16--- /dev/null+++ b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -0,0 +1,132 @@+[中文版本 →](../../../zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)+> Praxisprojekt: [Projekt 02. Agentenlesbarer Workspace](./../../projects/project-02-agent-readable-workspace/index.md)++# Lektion 04. Anweisungen auf Dateien verteilen++Du hast Harness Engineering ernst genommen. Du hast eine `AGENTS.md` erstellt und jede Regel, jede Einschränkung und jede gelernte Lektion hineingepackt, die dir eingefallen ist. Einen Monat später war die Datei auf 300 Zeilen angewachsen, nach zwei Monaten auf 450, nach drei Monaten auf 600. Dann merkst du, dass die Leistung des Agenten tatsächlich schlechter wird: Bei einem einfachen Bugfix verbrennt er massenhaft Kontext für irrelevante Deployment-Anweisungen; eine kritische Sicherheitsregel in Zeile 300 wird komplett ignoriert; drei widersprüchliche Code-Style-Regeln führen dazu, dass der Agent jedes Mal zufällig eine auswählt.++Das ist die Falle der "riesigen Anweisungsdatei". Es ist wie ein überfüllter Koffer: Alles scheint nützlich, also stopfst du es hinein, bis der Reißverschluss fast platzt. Um frische Unterwäsche zu finden, musst du den ganzen Koffer ausleeren. Du trägst einen vollen Koffer, nutzt aber vielleicht nur ein Drittel des Inhalts.++## Der Teufelskreis an der Wurzel++Der häufigste Teufelskreis läuft so: Der Agent macht einen Fehler, du sagst "füge eine Regel hinzu, damit das nicht wieder passiert", du packst sie in `AGENTS.md`, sie hilft vorübergehend, der Agent macht einen anderen Fehler, du fügst noch eine Regel hinzu, und so weiter. Die Datei bläht sich unkontrolliert auf.++Das ist nicht deine Schuld. Es ist eine sehr natürliche Reaktion: Jedes Mal, wenn etwas schiefgeht, eine Regel hinzuzufügen, fühlt sich vernünftig an, wie wenn man beim Verlassen des Hauses "nur für den Fall" noch etwas in die Tasche wirft. Aber der kumulative Effekt ist katastrophal. Schauen wir uns konkret an, was schiefgeht.++**Das Kontextbudget wird aufgefressen.** Das Kontextfenster des Agenten ist endlich. Angenommen, dein Agent hat ein 200K-Token-Fenster (ein typischer Claude-Wert). Eine aufgeblähte Anweisungsdatei kann 10-20K Tokens verbrauchen. Klingt, als wäre noch viel Platz? Aber eine komplexe Aufgabe muss vielleicht Dutzende Quelldateien lesen, Tool-Ausgaben benötigen ebenfalls Kontext, und Gesprächshistorie sammelt sich an. Wenn der Agent den Code wirklich verstehen muss, ist das Budget bereits knapp - wie ein Koffer voller "nur für den Fall"-Dinge, in dem kein Platz mehr für den Laptop bleibt.++**In der Mitte verloren.** Das Paper "Lost in the Middle" (Liu et al., 2023) zeigte klar, dass LLMs Informationen in der Mitte langer Texte deutlich schlechter nutzen als Informationen am Anfang oder Ende. Deine `AGENTS.md` hat 600 Zeilen, und Zeile 300 sagt "alle Datenbankabfragen müssen parametrisierte Queries verwenden" - eine harte Sicherheitsregel. Aber sie ist in der Mitte vergraben, und der Agent wird sie mit hoher Wahrscheinlichkeit ignorieren. Wie die Sonnencreme am Boden eines überfüllten Koffers: Du weißt, sie ist da, du suchst dreimal, findest sie nicht und kaufst am Ende eine neue.++**Prioritätskonflikte.** Die Datei mischt nicht verhandelbare harte Constraints ("never use eval()"), wichtige Designrichtlinien ("prefer functional style") und eine konkrete historische Lektion ("letzte Woche WebSocket-Memory-Leak behoben, auf ähnliche Muster achten"). Diese drei Regeln haben völlig unterschiedliche Wichtigkeit, sehen in der Datei aber identisch aus. Der Agent hat kein zuverlässiges Signal zur Unterscheidung - wie Reisepass und Ladekabel durcheinander im Koffer, ohne Hinweis, was dringender ist.++**Wartungsverfall.** Große Dateien sind inhärent schwer zu warten. Veraltete Anweisungen werden selten gelöscht, weil die Folgen unklar sind ("vielleicht hängt etwas anderes von dieser Regel ab"), während neue Anweisungen hinzuzufügen kostenlos wirkt. Ergebnis: Die Datei wächst nur, schrumpft nie, und das Signal-Rausch-Verhältnis sinkt kontinuierlich. Das ist genau die Akkumulation technischer Schulden, nur bei Anweisungen.++**Widersprüche sammeln sich an.** Anweisungen, die zu unterschiedlichen Zeiten hinzugefügt wurden, beginnen einander zu widersprechen: Eine sagt "TypeScript strict mode verwenden", eine andere sagt "einige Legacy-Dateien dürfen any-Typen nutzen". Der Agent wählt jedes Mal zufällig eine aus. Wie wenn deine Mutter sagt "zieh dich warm an" und dein Vater sagt "zieh nicht zu viel an", und du an der Tür stehst und nicht weißt, auf wen du hören sollst.++## Zentrale Konzepte++- **Instruction Bloat**: Wenn eine Anweisungsdatei mehr als 10-15% des Kontextfensters belegt, verdrängt sie Budget für Code-Lesen und Aufgabenlogik. Eine 600-Zeilen-`AGENTS.md` kann 10.000-20.000 Tokens verbrauchen - 8-15% eines 128K-Fensters, bevor der Agent überhaupt beginnt.+- **Lost in the Middle Effect**: Liu et al. zeigten 2023, dass LLMs Informationen in der Mitte langer Texte deutlich schlechter nutzen als Informationen am Anfang oder Ende. Eine kritische Regel in Zeile 300 einer 600-Zeilen-Datei wird mit hoher Wahrscheinlichkeit praktisch ignoriert.+- **Instruction Signal-to-Noise Ratio (SNR)**: Der Anteil der Anweisungen in einer Datei, der für die aktuelle Aufgabe relevant ist. Bei einem Bugfix 50 Zeilen Deployment-Anweisungen lesen zu müssen, ist niedriger SNR.+- **Routing File**: Eine kurze Einstiegsdatei, deren Kernfunktion darin besteht, den Agenten auf detailliertere Dokumente zu verweisen, statt alles selbst zu enthalten. 50-200 Zeilen reichen.+- **Progressive Disclosure**: Erst Überblick geben, Details bei Bedarf. Gutes Harness-Design ist wie gutes UI-Design: nicht alle Optionen auf einmal über den Nutzer kippen.+- **Priority Ambiguity**: Wenn alle Anweisungen im gleichen Format und am gleichen Ort erscheinen, kann der Agent nicht zwischen nicht verhandelbaren harten Constraints und weichen Empfehlungen unterscheiden.++## Anweisungsarchitektur++```mermaid+flowchart LR+ Mono["Eine 600-Zeilen-AGENTS.md"] --> MonoLoad["Selbst ein kleiner Bugfix<br/>muss Deploy-Regeln und alte Notizen lesen"]+ MonoLoad --> MonoRisk["Wichtige Regeln in der Mitte<br/>werden leicht übersehen"]++ Router["Kurze AGENTS.md"] --> Topics["API- / DB- / Testing-Dokumente nur laden,<br/>wenn die Aufgabe sie braucht"]+ Topics --> RoutedResult["Mehr Kontext bleibt fürs Code-Lesen<br/>und die Verifikation"]+```++```mermaid+flowchart TB+ File["600-Zeilen-Anweisungsdatei"] --> Top["Oberer Abschnitt<br/>Quick Start + harte Constraints"]+ File --> Mid["Mittlerer Abschnitt<br/>kritische Sicherheitsregel in Zeile 300"]+ File --> Bot["Unterer Abschnitt<br/>explizite Abschluss-Checkliste"]+ Top --> Seen["Hohe Chance, erinnert zu werden"]+ Bot --> Seen+ Mid --> Missed["Hohe Chance, verdünnt oder übersehen zu werden"]+```++## Wie man aufteilt++Kernprinzip: Häufig benötigte Informationen griffbereit halten, gelegentlich benötigte Informationen auslagern und Dinge, die du nie nutzt, entfernen.++Die Einstiegsdatei `AGENTS.md` bleibt bei 50-200 Zeilen und enthält nur die am häufigsten benötigten Elemente: Projektüberblick (ein bis zwei Sätze), Erststart-Befehle (`make setup && make test`), globale harte Constraints (höchstens 15 nicht verhandelbare Regeln) und Links zu Themendokumenten (Ein-Zeilen-Beschreibung + Anwendungsbedingung).++```markdown+# AGENTS.md++## Projektüberblick+Python 3.11 FastAPI backend, PostgreSQL 15 database.++## Quick Start+- Install: `make setup`+- Test: `make test`+- Full verification: `make check`++## Hard Constraints+- All APIs must use OAuth 2.0 authentication+- All database queries must use SQLAlchemy 2.0 syntax+- All PRs must pass pytest + mypy --strict + ruff check++## Topic Docs+- [API Design Patterns](docs/api-patterns.md) — Required reading when adding endpoints+- [Database Rules](docs/database-rules.md) — Required when modifying database operations+- [Testing Standards](docs/testing-standards.md) — Reference when writing tests+```++Jedes Themendokument umfasst 50-150 Zeilen, nach Thema im `docs/`-Verzeichnis oder neben dem entsprechenden Modul organisiert. Der Agent liest es nur bei Bedarf. Wie Packwürfel im Koffer: Unterwäsche in einem, Toilettenartikel in einem anderen, Ladegeräte in einem dritten. Um etwas zu finden, musst du nicht den ganzen Koffer ausleeren.++Manche Informationen gehören besser direkt in den Code: Typdefinitionen, Interface-Kommentare, Erklärungen in Konfigurationsdateien. Der Agent sieht sie natürlich beim Lesen des Codes, ohne dass sie in den Anweisungen dupliziert werden müssen.++Jede Anweisung sollte eine Quelle haben ("warum wurde diese Regel hinzugefügt?"), eine Anwendungsbedingung ("wann wird sie gebraucht?") und eine Ablaufbedingung ("unter welchen Umständen kann sie entfernt werden?"). Prüfe regelmäßig und entferne veraltete, redundante und widersprüchliche Einträge. Verwalte Anweisungen wie Code-Abhängigkeiten: Unbenutzte Abhängigkeiten sollten gelöscht werden, sonst bremsen sie nur das System.++Wenn eine Anweisung unbedingt in die Einstiegsdatei muss, platziere sie oben oder unten - niemals in der Mitte. Der "lost in the middle"-Effekt sagt uns, dass LLMs Informationen an den Rändern deutlich besser nutzen als im Zentrum. Besser ist jedoch, Anweisungen in Themendokumente zu verschieben, die bei Bedarf geladen werden.++OpenAI und Anthropic unterstützen implizit den Aufteilungsansatz. OpenAI sagt, Einstiegsdateien sollten "kurz und routing-orientiert" sein; Anthropic sagt, Kontrollinformationen für lang laufende Agenten sollten "prägnant und hoch priorisiert" sein. Beide sagen dasselbe: Stopf nicht alles in eine Datei. Ein Koffer braucht Organisation, nicht brutales Hineinpressen.++## Beispiel aus der Praxis++Die `AGENTS.md` eines SaaS-Teams wuchs von 50 auf 600 Zeilen. Der Inhalt mischte Tech-Stack-Versionen, Coding-Standards, historische Bugfix-Notizen, API-Nutzungsleitfäden, Deployment-Prozeduren und persönliche Präferenzen von Teammitgliedern - der ganze Koffer stand kurz vorm Platzen.++Die Agentenleistung sank spürbar: Bei einfachen Bugfixes verbrachte der Agent viel Kontext mit irrelevanten Deployment-Anweisungen; die Sicherheitsregel "alle Datenbankabfragen müssen parametrisierte Queries verwenden" war in Zeile 300 vergraben und wurde häufig ignoriert; drei widersprüchliche Code-Style-Regeln führten zu zufälligem Verhalten.++Das Team führte eine "Koffer-Neuorganisation" durch:+1. `AGENTS.md` auf 80 Zeilen gekürzt: nur Projektüberblick, Ausführungsbefehle und 15 globale harte Constraints+2. Themendokumente erstellt: `docs/api-patterns.md` (120 Zeilen), `docs/database-rules.md` (60 Zeilen), `docs/testing-standards.md` (80 Zeilen)+3. Links zu Themendokumenten in der Routing-Datei ergänzt+4. Historische Notizen entweder in Testfälle umgewandelt oder gelöscht++Nach dem Refactoring stieg die Erfolgsrate desselben Aufgabensatzes von 45% auf 72%. Die Einhaltung der Sicherheitsregel stieg von 60% auf 95%, weil sie aus der Dateimitte an den Anfang der Routing-Datei verschoben wurde und nicht mehr "in der Mitte verloren" ging.++## Wichtigste Erkenntnisse++- "Eine Regel hinzufügen" ist kurzfristige Schmerzlinderung und langfristig Gift. Bevor du eine Regel hinzufügst, frage: Wäre das besser in einem Themendokument? Stopf nicht einfach weiter Dinge in den Koffer.+- Die Einstiegsdatei ist ein Router, keine Enzyklopädie. 50-200 Zeilen mit Überblick, harten Constraints und Links reichen.+- Nutze den "lost in the middle"-Effekt: Wichtige Informationen kommen nach oben oder unten; weniger wichtige Informationen wandern in Themendokumente.+- Behandle Instruction Bloat wie technische Schulden. Regelmäßige Audits; jede Anweisung braucht Quelle, Anwendungsbedingung und Ablaufbedingung.+- Nach dem Aufteilen steigt der SNR, und der Agent verwendet mehr Kontextbudget auf die echte Aufgabe statt auf irrelevante Anweisungen.++## Weiterführende Literatur++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)++## Übungen++1. **SNR-Audit**: Nimm deine aktuelle Einstiegs-Anweisungsdatei und liste alle Anweisungseinträge auf. Wähle 5 häufige Aufgabentypen und markiere, ob jede Anweisung für diese Aufgabe relevant ist. Berechne den SNR pro Aufgabentyp. Anweisungen, die für die meisten Aufgaben Rauschen sind, sollten in Themendokumente verschoben werden.++2. **Progressive-Disclosure-Refactoring**: Wenn du eine Anweisungsdatei mit mehr als 300 Zeilen hast, teile sie auf in: (a) eine Routing-Datei unter 100 Zeilen, (b) 3-5 Themendokumente. Führe denselben Aufgabensatz (mindestens 5 Aufgaben) vor und nach der Aufteilung aus und vergleiche die Erfolgsraten.++3. **Lost-in-the-Middle-Verifikation**: Platziere in einer langen Anweisungsdatei eine kritische Regel jeweils oben, in der Mitte und unten und führe jedes Mal denselben Aufgabensatz aus (mindestens 5 Läufe pro Position). Prüfe, ob sich die Einhaltungsrate unterscheidet. Der Positionseffekt kann überraschend stark sein.diff --git a/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.mdnew file mode 100644index 0000000..cd4b934--- /dev/null+++ b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md@@ -0,0 +1,6 @@+# Kontinuitäts-Checkliste++- Kann ein neuer Agent aktuelle Arbeit in unter fünf Minuten identifizieren?+- Ist der aktuelle stabile Startpfad dokumentiert?+- Ist unvollständige Arbeit klar gekennzeichnet?+- Ist die nächste beste Aufgabe ohne Lesen alter Chat-Protokolle sichtbar?diff --git a/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdnew file mode 100644index 0000000..d7fa313--- /dev/null+++ b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md@@ -0,0 +1,7 @@+# Code für Vorlesung 05++Verwenden Sie diesen Ordner für Beispiele zu:++- unterbrochenen Multi-Session-Aufgaben+- fehlenden Kontinuitäts-Artefakten+- Kontinuitäts-Wiederherstellungsmusterndiff --git a/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdnew file mode 100644index 0000000..a2f4ce1--- /dev/null+++ b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -0,0 +1,17 @@+# Session-Übergabe Beispiel++## Abgeschlossen++- Markdown-Import-Unterstützung hinzugefügt+- Eine grundlegende Dokumentenliste im Renderer hinzugefügt++## Defekt oder Unverifiziert++- Import erfolgreich für `.md`, scheitert aber bei großen `.txt`-Dateien+- Die App startet, aber die Detailansicht ist noch nicht verbunden++## Nächster bester Schritt++- `.txt`-Import-Pfad reparieren+- Import End-to-End verifizieren+- Dann das Dokument-Detailpanel hinzufügendiff --git a/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.tsnew file mode 100644index 0000000..69f9c3e--- /dev/null+++ b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts@@ -0,0 +1,162 @@+/**+ * session-simulator.ts+ *+ * Simulates two sessions working on a multi-step task.+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.+ * Run 2: With handoff file -- Session B picks up where Session A left off.+ *+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface TaskStep {+ id: number;+ name: string;+ durationMs: number;+}++interface SessionResult {+ session: string;+ stepsCompleted: number;+ totalDurationMs: number;+ duplicatedSteps: number;+ output: string[];+}++// ---------------------------------------------------------------------------+// Task definition+// ---------------------------------------------------------------------------++const taskSteps: TaskStep[] = [+ { id: 1, name: "Read project structure", durationMs: 50 },+ { id: 2, name: "Understand existing auth module", durationMs: 80 },+ { id: 3, name: "Design new search endpoint", durationMs: 60 },+ { id: 4, name: "Implement search endpoint", durationMs: 100 },+ { id: 5, name: "Write integration tests", durationMs: 70 },+ { id: 6, name: "Update documentation", durationMs: 40 },+];++// ---------------------------------------------------------------------------+// Simulated session executor+// ---------------------------------------------------------------------------++/** Simulate a session doing work. */+function runSession(+ sessionName: string,+ startStep: number,+ endStep: number+): SessionResult {+ const output: string[] = [];+ let totalDuration = 0;++ for (let i = startStep; i <= endStep; i++) {+ const step = taskSteps.find((s) => s.id === i)!;+ totalDuration += step.durationMs;+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);+ }++ return {+ session: sessionName,+ stepsCompleted: endStep - startStep + 1,+ totalDurationMs: totalDuration,+ duplicatedSteps: 0,+ output,+ };+}++// ---------------------------------------------------------------------------+// Run 1: No handoff file+// ---------------------------------------------------------------------------++function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 before timing out+ const sessionA = runSession("Session A", 1, 3);++ // Session B has no context, starts from scratch+ const sessionB = runSession("Session B", 1, 6);+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Run 2: With handoff file+// ---------------------------------------------------------------------------++function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 and writes a handoff file+ const sessionA = runSession("Session A", 1, 3);++ // Session B reads handoff, starts from step 4+ const sessionB = runSession("Session B", 4, 6);+ sessionB.duplicatedSteps = 0;++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {+ console.log("\n" + "=".repeat(80));+ console.log(` ${title}`);+ console.log("=".repeat(80));++ console.log("\n Session A output:");+ for (const line of result.sessionA.output) {+ console.log(line);+ }++ console.log("\n Session B output:");+ for (const line of result.sessionB.output) {+ console.log(line);+ }++ console.log("\n Session B notes:");+ if (result.sessionB.duplicatedSteps > 0) {+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);+ } else {+ console.log(" - Read handoff file, continued from step 4");+ console.log(" - No duplicate work performed");+ }+}++function printComparison(): void {+ const noHandoff = simulateNoHandoff();+ const withHandoff = simulateWithHandoff();++ printRun("RUN 1: NO HANDOFF FILE", noHandoff);+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);++ // Comparison table+ console.log("\n" + "=".repeat(80));+ console.log(" COMPARISON TABLE");+ console.log("=".repeat(80) + "\n");++ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log(header);+ console.log(sep);++ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;++ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);++ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");+}++printComparison();diff --git a/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdnew file mode 100644index 0000000..ecc40fc--- /dev/null+++ b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -0,0 +1,180 @@+[中文版本 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)+> Praxisprojekt: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# Lektion 05. Kontext über Sessions hinweg erhalten++Sie bitten Claude Code, ein vollständiges Feature zu implementieren. Es läuft 30 Minuten, erledigt den Großteil der Arbeit, aber der Kontext wird knapp. Sie starten eine neue Session, um fortzufahren — und stellen fest, dass es sich nicht an die Entscheidungen der letzten Session erinnert, warum Option A gegenüber Option B gewählt wurde, welche Dateien bereits geändert wurden oder in welchem Zustand sich die Tests befinden. Es verbringt 15 Minuten damit, das Projekt neu zu erkunden, und könnte inkonsistent zum vorherigen Ansatz sein.++Stellen Sie sich vor, Sie wären ein Handwerker, der jeden Morgen beim Aufwachen alles vergisst. Sie müssten sich die gesamte Baustelle neu vertraut machen — welche Mauer halb fertig ist, warum rote statt blaue Ziegel gewählt wurden, wo die Rohrleitungen verlaufen. Schlimmer noch, Sie könnten ein Fenster herausreißen, das gestern bereits eingebaut wurde, einfach weil Sie sich nicht erinnern, dass es erledigt war.++Genau in dieser Situation befinden sich KI-Coding-Agenten bei übergreifenden Aufgaben. Diese Lektion erklärt, warum Agenten bei langen Aufgaben „aussteigen" und wie strukturierte Zustandspersistenz sie wie einen Handwerker machen kann, der ein zuverlässiges Tagebuch führt — immer noch amnesisch, aber das Tagebuch erinnert sich an alles.++## Kontextfenster: Nicht unendlich++Kontextfenster sind endlich. Das lässt sich nicht durch Modell-Upgrades lösen — selbst wenn Fenstergrößen auf 1M Token anwachsen, werden komplexe Aufgaben sie dennoch erschöpfen. Denn Agenten generieren nicht nur Code; sie verstehen Codebases, verfolgen ihre eigene Entscheidungsgeschichte, verarbeiten Tool-Ausgaben und pflegen den Gesprächskontext. All diese Informationen wachsen schneller als die Fenstervergrößerung.++Ein tieferes Problem: Die Informationen, die der Agent produziert, sind nicht gleichmäßig wichtig. Zwischen den Reasoning-Schritten steckt das „warum" der Entscheidungen — warum Option B gegenüber A gewählt wurde, warum diese Bibliothek statt jener, warum eine bestimmte Optimierung übersprungen wurde. Die endgültige Ausgabe enthält nur das „was" — den Code selbst. Kompressionsstrategien bewahren normalerweise letzteres, verlieren aber ersteres. Die nächste Session sieht den Code, weiß aber nicht, warum er so geschrieben wurde, und „optimiert" möglicherweise eine bewusste Designentscheidung weg.++Anthropic hat in seiner Forschung zu langlebigen Agenten etwas Faszinierendes entdeckt: Wenn Agenten spüren, dass der Kontext knapp wird, zeigen sie ein „voreilige Konvergenz"-Verhalten — sie hetzen, die aktuelle Arbeit abzuschließen, überspringen Verifizierungsschritte oder wählen eine einfache Lösung statt der optimalen. Es ist, als würde man merken, dass die Zeit im Exam abläuft, und schnell die restlichen Multiple-Choice-Fragen raten. Anthropic nennt dies „context anxiety".++## Session-Kontinuitätsfluss++Ohne Kontinuitäts-Artefakte ist jede neue Session eine Katastrophe:++```mermaid+flowchart LR+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]+ End1 --> S2["Session 2 starts fresh"]+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]+```++Mit Kontinuitäts-Artefakten können neue Sessions schnell aufsetzen:++```mermaid+flowchart LR+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]+ Work --> Verify["Verification notes<br/>which tests pass and fail"]+ Work --> Commit["Git checkpoint<br/>exact repo state"]++ Progress --> Rebuild["Session 2 rebuild"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["New session picks up quickly"]+```++## Zentrale Konzepte++- **Kontextfenster sind endlich**: Egal welche Fenstergröße behauptet wird (128K, 200K, 1M) — lange Aufgaben werden sie schließlich erschöpfen. Nach der Erschöpfung ist entweder Kompression (Informationsverlust) oder ein Reset (neue Session) erforderlich. Beide verlieren etwas.+- **Kontinuitäts-Artefakte**: Persistierte Zustandsdateien, die es einer neuen Session ermöglichen, eindeutig dort fortzufahren, wo die letzte aufgehört hat. Die Grundform: Fortschrittsprotokoll + Verifizierungsdatensatz + nächste Aktionen. Das Tagebuch dieses Handwerkers.+- **Rebuild-Kosten**: Die Zeit, die eine neue Session benötigt, um einen ausführbaren Zustand zu erreichen. Gute harness-Konstruktionen können die Rebuild-Kosten von 15 Minuten auf 3 Minuten komprimieren.+- **Drift**: Die Lücke zwischen dem Verständnis des Agenten und dem tatsächlichen Zustand des Code-Repositorys. Jede Sitzungsgrenze führt Drift ein; ohne Kontrolle summiert er sich.+- **Context Anxiety**: Ein von Anthropic beobachtetes Phänomen — Agenten zeigen voreiliges Konvergenzverhalten, wenn sie sich wahrgenommenen Kontextgrenzen nähern, und beenden Aufgaben vorzeitig, um Informationsverlust zu vermeiden. Es ist eine irrationale Ressourcenangst.+- **Kompression vs. Reset**: Kompression fasst den Kontext innerhalb derselben Session zusammen (behält das „was", verliert möglicherweise das „warum"); Reset öffnet eine neue Session, die aus persistiertem Zustand wieder aufgebaut wird (sauber, aber abhängig von der Vollständigkeit der Artefakte).++## Was passiert, wenn die Kontinuität abbricht++Die vorherige Session hat bedeutende Kontextbudgets für die Analyse dreier Ansätze und die Wahl von Option B aufgewendet. Der Agent dieser Session weiß nichts von dieser Analyse und könnte auf Basis unvollständiger Informationen neu entscheiden — möglicherweise wählt er Option A. Wie der amnestische Handwerker, der sich nicht erinnert, warum rote Ziegel gewählt wurden, die blauen heute schöner findet und die Mauer von gestern abreißt, um sie neu zu bauen.++Noch schlimmer ist doppelte Arbeit. Der Agent ist sich nicht sicher, ob bestimmte Arbeit bereits erledigt wurde, und macht sie noch einmal. Oder noch schlimmer — erledigt die Hälfte, entdeckt einen Konflikt mit der bestehenden Implementierung und muss nacharbeiten. Auf einer Baustelle können nicht zwei Teams gleichzeitig dieselbe Mauer bauen — aber ohne Fortschrittsaufzeichnungen hat die neue Mannschaft keine Ahnung, dass bereits jemand daran arbeitet.++Über mehrere Sessions hinweg kann die Implementierungsrichtung still von den ursprünglichen Anforderungen abgedriftet sein. Jede neue Session hat ein leicht anderes Verständnis der Projektziele. Wie bei einem Flüsternachrichtenspiel — nachdem zehn Menschen die Nachricht weitergegeben haben, könnte „hol mir einen Kaffee" zu „kauf mir eine Kaffeemaschine" geworden sein.++Es gibt auch die Verifizierungslücke. Die Verifizierungsergebnisse der vorherigen Session (welche Tests durchlaufen, welche fehlschlagen, warum sie fehlschlagen) wurden nicht dokumentiert. Die neue Session muss alle Verifizierungen erneut ausführen, um den aktuellen Zustand zu verstehen. Jede Session diagnostiziert von Grund auf neu, jedes Mal wertvollen Kontext verschwendend.++Sowohl OpenAI als auch Anthropic betonen strukturierte Zustandspersistenz in ihrer Dokumentation. OpenAIs Artikel zum harness Engineering behandelt das Repository als „operational record" — die Ergebnisse jeder Operation sollten nachvollziehbare Spuren im Repo hinterlassen. Anthropics Dokumentation zu langlebigen Agenten empfiehlt ausdrücklich „handoff files" — strukturierte Dokumente mit aktuellem Zustand, bekannten Problemen und nächsten Aktionen.++## Ein Tagebuch für den amnestischen Handwerker++Kernansatz: **Behandeln Sie den Agenten wie einen brillanten Ingenieur mit Amnesie.** Bevor er „aussticht", muss er kritische Informationen aufschreiben, damit der Agent der nächsten „Schicht" schnell aufsetzen kann.++**Tool 1: Fortschrittsdatei (PROGRESS.md).** Das grundlegendste Kontinuitäts-Artefakt — der Kern des Tagebuchs:++```markdown+# Project Progress++## Current State+- Latest commit: abc1234 (feat: add user preferences endpoint)+- Test status: 42/43 passing (test_pagination_edge_case failing)+- Lint: passing++## Completed+- [x] User model and database migration+- [x] Basic CRUD endpoints+- [x] Auth middleware integration++## In Progress+- [ ] Pagination feature (90% - edge case test failing)++## Known Issues+- test_pagination_edge_case returns 500 on empty result sets+- Need to confirm whether deleted users should appear in listings++## Next Steps+1. Fix pagination edge case bug+2. Add "include deleted users" query parameter+3. Update API documentation+```++**Tool 2: Entscheidungsprotokoll (DECISIONS.md).** Dokumentiert wichtige Designentscheidungen und deren Gründe. Keine detaillierten Designdokumente nötig — nur „welche Entscheidung, warum, wann" — die Notizen im Tagebuch:++```markdown+# Design Decisions++## 2024-01-15: Use Redis for user preferences caching+- Reason: High read frequency (every API call), small data size+- Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile)+- Constraint: Cache TTL of 5 minutes, active invalidation on write+```++**Tool 3: Git-Commits als Kontrollpunkte.** Committen Sie nach Abschluss jeder atomaren Arbeitseinheit. Commit-Nachrichten sollten erklären, was getan wurde und warum. Diese sind kostenlose, automatisch versionierte Zustandsschnappschüsse.++**Tool 4: init.sh oder harness-Initialisierungsfluss.** Spezifizieren Sie in `AGENTS.md` die „Einstich"- und „Ausstich"-Routinen:++```markdown+## At session start (clock in)+1. Read PROGRESS.md for current state+2. Read DECISIONS.md for important decisions+3. Run make check to confirm repo is in consistent state+4. Continue from PROGRESS.md "Next Steps" section++## Before session end (clock out)+1. Update PROGRESS.md+2. Run make check to confirm consistent state+3. Commit all completed work+```++**Gemischte Strategie**: Nicht jede Aufgabe benötigt einen Kontext-Reset. Kurze Aufgaben (unter 30 Minuten) können innerhalb einer Session abgeschlossen werden. Lange Aufgaben (sessionübergreifend) müssen Fortschrittsdateien und Entscheidungsprotokolle für die Kontinuität verwenden. Entscheidungsregel: Wenn eine Aufgabe mehr als 60% des Fensters benötigt, beginnen Sie mit der Vorbereitung der Übergabe.++### Tieferer Einblick in Context Anxiety++Anthropics Forschung von März 2026 offenbarte weitere Details zur Context Anxiety: Bei Sonnet 4.5 zeigt der Agent starkes „voreilige Konvergenz"-Verhalten, wenn der Kontext sich der Fenstergrenze nähert. Es ist, als würde man merken, dass die Zeit fast abgelaufen ist, und schnell zufällige Antworten bei der Multiple Choice ausfüllen.++Zwei Strategien helfen dagegen:++**Kompression**: Frühzeitige Gesprächszusammenfassung innerhalb derselben Session. Vorteil: erhält Kontinuität, der Agent kann das „was" sehen. Nachteil: das „warum" geht in Zusammenfassungen oft verloren — warum Option B gegenüber A gewählt wurde, warum eine bestimmte Optimierung übersprungen wurde. Kritischer noch: Kompression beseitigt die Context Anxiety nicht — der Agent weiß, dass der Kontext einmal groß war, und neigt psychologisch weiterhin zum voreiligen Abschluss.++**Kontext-Reset**: Vollständiges Leeren des Kontexts, Öffnen einer neuen Session, Wiederherstellung aus persistierten Artefakten. Vorteil: sauberer mentaler Zustand — die neue Session hat keine „mir geht die Zeit aus"-Angst. Nachteil: abhängig von der Vollständigkeit der Übergabe-Artefakte. Wenn im Tagebuch kritische Informationen fehlen, kann die neue Session Zeit in die falsche Richtung verschwenden.++Anthropics tatsächliche Daten: Bei Sonnet 4.5 ist die Context Anxiety so stark, dass Kompression allein nicht ausreicht — Kontext-Reset wird zu einer kritischen Komponente des harness-Designs. Bei Opus 4.5 ist dieses Verhalten jedoch stark abgeschwächt, und Kompression kann den Kontext verwalten, ohne auf Resets angewiesen zu sein. Das bedeutet: **harness-Design benötigt spezifisches Verständnis des Zielmodells, keine Einheitslösung.**++> Quelle: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## Praxisbeispiel++Ein Agent wurde beauftragt, ein Blog-System mit Benutzerauthentifizierung zu implementieren — 12 Feature-Punkte, geschätzte 5 Sessions nötig.++**Baseline ohne Tagebuch**: Session 1 implementierte das Benutzermodell und grundlegende Routen. Session 2 startete ohne dass sich der Agent an den Interface-Vertrag der Auth-Middleware erinnerte und verbrachte ~15 Minuten damit, die vorherige Designabsicht zu erschließen. In Session 3 führte akkumulierter Drift dazu, dass der Agent bereits abgeschlossene Features neu zu implementieren begann. In Session 5 enthielt das Repo viel redundanten Code, aber das Kern-Auth-Feature hatte die End-to-End-Tests noch nicht bestanden. Nur 7 von 12 Feature-Punkten abgeschlossen, 3 mit versteckten Korrektheitsproblemen. Wie der Handwerker, der nie in sein Tagebuch schreibt — an Tag fünf ist die Baustelle das Chaos, einige Mauern doppelt gebaut, einige, die hätten gebaut werden sollen, nie begonnen.++**Mit Tagebuch**: Unter Verwendung von Fortschrittsdateien, Entscheidungsprotokollen, Verifizierungsaufzeichnungen und Git-Kontrollpunkten. Zustandsbericht automatisch am Ende jeder Session aktualisiert. Session 2s Rebuild-Kosten fielen auf ~3 Minuten. Bis Session 5 waren alle 12 Feature-Punkte abgeschlossen und verifiziert.++Quantitativer Vergleich: Rebuild-Zeit um ~78% reduziert, Feature-Abschlussrate von 58% auf 100%, versteckte Fehlerrate von 43% auf 8%. Der Handwerker ist immer noch amnestisch, aber mit dem Tagebuch beginnt jeder Tag dort, wo der vorherige aufgehört hat — nicht bei null.++## Wichtigste Erkenntnisse++- Kontextfenster sind eine endliche Ressource. Lange Aufgaben werden Sessions überspannen, und Sessions werden Informationen verlieren — wie der Handwerker, der jeden Tag vergisst, ist das objektive Realität.+- Die Lösung sind nicht größere Fenster — sondern bessere Zustandspersistenz. Fortschrittsdateien + Entscheidungsprotokolle + Git-Kontrollpunkte — geben Sie dem amnestischen Handwerker ein zuverlässiges Tagebuch.+- Behandeln Sie den Agenten wie einen Ingenieur mit Amnesie: Bevor er „aussticht", schreibt er auf, was getan wurde, warum und was als Nächstes ansteht.+- Rebuild-Kosten sind die zentrale Kennzahl. Gute harness-Konstruktionen sollten neue Sessions innerhalb von 3 Minuten in einen ausführbaren Zustand bringen.+- Gemischte Strategie: kurze Aufgaben innerhalb von Sessions, lange Aufgaben mit strukturierten Artefakten für Kontinuität.++## Weiterführende Literatur++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [Claude Code Documentation](https://docs.anthropic.com/de/docs/claude-code)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)++## Übungen++1. **Kontinuitätsverlust-Messung**: Wählen Sie eine Entwicklungsaufgabe, die mindestens 3 Sessions benötigt. Ohne Kontinuitäts-Artefakte anzubieten, notieren Sie zu Beginn jeder Session, wie viel Kontext der Agent darauf verwendet, „herauszufinden, was beim letzten Mal passiert ist." Erstellen Sie nach jeder Session eine Fortschrittsdatei und lassen Sie die nächste Session daraus starten. Vergleichen Sie die Rebuild-Kosten mit und ohne Fortschrittsdateien.++2. **Übergabe-Vorlage entwerfen**: Entwerfen Sie eine minimale Übergabe-Vorlage mit vier Feldern: Repo-Zustand (Commit-Hash), Laufzeitzustand (Test-Pass-Rate), Blockaden, nächste Aktionen. Lassen Sie eine komplett neue Agenten-Session den Projektzustand nur anhand dieser Vorlage wiederherstellen. Dokumentieren Sie Mehrdeutigkeiten bei der Wiederherstellung und iterieren Sie zur Verbesserung der Vorlage.++3. **Gemischte Strategie experimentieren**: In einer 5-Session-Entwicklungsaufgabe vergleichen Sie drei Strategien: (a) immer neue Sessions starten + Fortschrittsdateien, (b) so viel wie möglich in einer Session erledigen (Kontext-Kompression), (c) gemischte Strategie (kurze Aufgaben in der Session, lange Aufgaben sessionübergreifend + Fortschrittsdateien). Vergleichen Sie Rebuild-Zeit, Feature-Abschlussrate und Entscheidungs konsistenz.diff --git a/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdnew file mode 100644index 0000000..6969b24--- /dev/null+++ b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 06++Verwenden Sie diesen Ordner für Beispiele zu:++- Initialisierer-Ausgaben+- Init-Skripten+- Fortschrittsdateien+- Erstlauf-Scaffoldingdiff --git a/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.tsnew file mode 100644index 0000000..52dcd98--- /dev/null+++ b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts@@ -0,0 +1,296 @@+/**+ * init-check.ts+ *+ * Programmatically checks initialization prerequisites:+ * - Node.js version+ * - Dependencies installed (node_modules exists)+ * - Data directory exists+ * - Config files present+ *+ * Simulates running with and without an explicit init phase,+ * showing how missing prerequisites cause silent failures later.+ *+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";+import * as childProcess from "node:child_process";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface CheckItem {+ name: string;+ category: string;+ check: () => { pass: boolean; detail: string };+ impactIfMissing: string;+}++interface CheckResult {+ name: string;+ category: string;+ passed: boolean;+ detail: string;+ impactIfMissing: string;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++function createChecks(targetDir: string): CheckItem[] {+ return [+ {+ name: "Node.js version >= 18",+ category: "Runtime",+ check: () => {+ try {+ const version = process.version; // e.g. "v20.11.0"+ const major = parseInt(version.replace("v", "").split(".")[0], 10);+ return {+ pass: major >= 18,+ detail: `Detected: ${version} (need >= v18)`,+ };+ } catch {+ return { pass: false, detail: "Could not detect Node.js version" };+ }+ },+ impactIfMissing: "TypeScript features and built-in APIs unavailable",+ },+ {+ name: "package.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "package.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found in target directory",+ };+ },+ impactIfMissing: "Cannot install dependencies or run scripts",+ },+ {+ name: "Dependencies installed (node_modules)",+ category: "Dependencies",+ check: () => {+ const p = path.join(targetDir, "node_modules");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",+ };+ },+ impactIfMissing: "All imports fail at runtime",+ },+ {+ name: "TypeScript available",+ category: "Toolchain",+ check: () => {+ try {+ const result = childProcess.execSync("npx tsc --version", {+ encoding: "utf-8",+ timeout: 10000,+ stdio: ["pipe", "pipe", "pipe"],+ }).trim();+ return { pass: true, detail: `Detected: ${result}` };+ } catch {+ return { pass: false, detail: "TypeScript not available via npx" };+ }+ },+ impactIfMissing: "Cannot compile TypeScript files",+ },+ {+ name: "tsconfig.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "tsconfig.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found",+ };+ },+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",+ },+ {+ name: "Source directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["src", "lib", "app"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",+ };+ },+ impactIfMissing: "Agent cannot locate source files to modify",+ },+ {+ name: "Test directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["test", "tests", "__tests__", "spec"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",+ };+ },+ impactIfMissing: "Agent cannot find or run existing tests",+ },+ {+ name: "Git repository initialized",+ category: "Version Control",+ check: () => {+ const gitDir = path.join(targetDir, ".git");+ const exists = fs.existsSync(gitDir);+ return {+ pass: exists,+ detail: exists ? "Git repository detected" : "No .git directory found",+ };+ },+ impactIfMissing: "No rollback capability, no change history",+ },+ ];+}++// ---------------------------------------------------------------------------+// Simulation: with and without init phase+// ---------------------------------------------------------------------------++interface SimResult {+ scenario: string;+ checksRun: boolean;+ failuresBeforeWork: number;+ workAttempted: boolean;+ workSucceeded: boolean;+ timeWastedMs: number;+}++function simulateWithoutInit(): SimResult {+ // Agent skips init, goes straight to work.+ // Encounters failures one at a time as it hits missing prerequisites.+ const checks = createChecks(process.cwd());+ let failures = 0;+ let timeWasted = 0;++ for (const check of checks) {+ const result = check.check();+ if (!result.pass) {+ failures++;+ timeWasted += 200; // Agent spends time discovering each missing piece+ }+ }++ return {+ scenario: "NO INIT PHASE",+ checksRun: false,+ failuresBeforeWork: 0, // Didn't check upfront+ workAttempted: true,+ workSucceeded: failures === 0,+ timeWastedMs: timeWasted,+ };+}++function simulateWithInit(): SimResult {+ // Agent runs init phase first, discovers all issues upfront.+ const checks = createChecks(process.cwd());+ let failures = 0;++ for (const check of checks) {+ if (!check.check().pass) {+ failures++;+ }+ }++ return {+ scenario: "WITH INIT PHASE",+ checksRun: true,+ failuresBeforeWork: failures,+ workAttempted: failures === 0,+ workSucceeded: failures === 0,+ timeWastedMs: 0,+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.cwd();+ console.log("\n" + "=".repeat(80));+ console.log(" INITIALIZATION PREREQUISITE CHECK");+ console.log("=".repeat(80));+ console.log(` Target: ${targetDir}\n`);++ const checks = createChecks(targetDir);+ const results: CheckResult[] = checks.map((c) => {+ const r = c.check();+ return {+ name: c.name,+ category: c.category,+ passed: r.pass,+ detail: r.detail,+ impactIfMissing: c.impactIfMissing,+ };+ });++ // Detailed report+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const status = r.passed ? "PASS" : "FAIL";+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);+ }++ const passCount = results.filter((r) => r.passed).length;+ const failCount = results.filter((r) => !r.passed).length;++ console.log("\n" + "-".repeat(80));+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);++ if (failCount > 0) {+ console.log("\n FAILED CHECKS -- Impact if not resolved:");+ for (const r of results.filter((r) => !r.passed)) {+ console.log(` - ${r.name}: ${r.impactIfMissing}`);+ }+ }++ // Comparison: with vs without init+ const noInit = simulateWithoutInit();+ const withInit = simulateWithInit();++ console.log("\n" + "=".repeat(80));+ console.log(" INIT PHASE COMPARISON");+ console.log("=".repeat(80) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);++ console.log("\n An explicit init phase catches problems before they waste time.\n");+}++run();diff --git a/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.shnew file mode 100644index 0000000..2c6e1b0--- /dev/null+++ b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh@@ -0,0 +1,10 @@+#!/usr/bin/env bash+set -euo pipefail++echo "[init] installing dependencies"+npm install++echo "[init] starting the docs site is optional"+echo "[init] use npm run docs:dev for course docs"++echo "[init] project-specific startup would go here"diff --git a/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.mdnew file mode 100644index 0000000..caafe1b--- /dev/null+++ b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md@@ -0,0 +1,7 @@+# Initialisierer-Ausgabe Checkliste++- Gibt es einen kanonischen Startbefehl?+- Gibt es einen kanonischen Verifikationsbefehl?+- Gibt es ein erstes Fortschritts-Artefakt?+- Gibt es einen stabilen ersten Commit?+- Gibt es eine sichtbare Feature-Oberfläche für spätere Sessions?diff --git a/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdnew file mode 100644index 0000000..82481f8--- /dev/null+++ b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -0,0 +1,157 @@+[中文版本 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)+> Praxisprojekt: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# Lektion 06. Vor jeder Agenten-Session initialisieren++Sie starten eine neue Agenten-Session und sagen „Füge eine Suchfunktion hinzu." Es stürzt sich direkt ins Programmieren — bewundernswerte Begeisterung. Nach 20 Minuten stellt es fest, dass das Test-Framework nicht richtig konfiguriert ist, verbringt weitere 10 Minuten mit der Reparatur, dann ist das Format des Datenbankmigrationsskripts falsch, weiteres Herumgefummel. Die Suchfunktion wird schließlich hinzugefügt, aber die gesamte Session war ineffizient — die meiste Zeit floss in „herausfinden, wie dieses Projekt funktioniert" anstatt die Suchfunktion zu schreiben.++Der bessere Ansatz: Bevor der Agent mit der Arbeit beginnt, eine separate Phase nutzen, um die Basisumgebung vorzubereiten, Verifizierungsbefehle zum Laufen zu bringen und die Projektstruktur zu verstehen. Es ist wie beim Hausbau — man gießt nicht das Fundament und stellt gleichzeitig die Wände auf. Wenn man es doch tut, stehen die Wände, bevor das Fundament ausgehärtet ist, und das gesamte Gebäude muss abgerissen und neu begonnen werden. Erst das Fundament gießen, aushärten lassen, dann die Wände bauen — sauber und effizient.++Diese Lektion erklärt, warum die Initialisierung eine separate Phase sein muss, nicht mit der Implementierung vermischt.++## Fundament und Wände: Zwei grundverschiedene Aufgaben++Initialisierung und Implementierung haben völlig unterschiedliche Optimierungsziele. Die Implementierungsphase optimiert auf: Maximierung der Menge und Qualität verifizierter Features. Die Initialisierungsphase optimiert auf: Maximierung der Zuverlässigkeit und Effizienz aller nachfolgenden Implementierungen.++Wenn man Initialisierung und Implementierung vermischt, steht der Agent vor einem Multi-Objective-Optimierungsproblem — gleichzeitig Infrastruktur aufbauen und Feature-Code schreiben. Ohne explizite Prioritätensetzung neigt der Agent natürlicherweise zum Schreiben von Code (weil das direkt sichtbare Ausgabe ist) und opfert die Infrastruktur (weil ihr Wert sich erst in nachfolgenden Sessions zeigt). Es ist, als würde man einer Baumannschaft sagen, sie soll gleichzeitig das Fundament gießen und die Wände bauen — sie werden wahrscheinlich eilig Wände bauen, weil Wände sichtbar und vorzeigbar sind. Aber ein Haus mit einem schlechten Fundament hat systemische Probleme später.++## Initialisierungs-Lebenszyklus++```mermaid+flowchart TB+ subgraph Wrong["Mixed session (wrong)"]+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]+ W2 --> W3["Accumulate unverified code"]+ W3 --> W4["Next session must rediscover project state"]+ end++ subgraph Right["Dedicated initialization (right)"]+ R1["Session 1: environment runnable"] --> R2["Example test passing"]+ R2 --> R3["Bootstrap contract + task list written"]+ R3 --> R4["Clean checkpoint committed"]+ R4 --> R5["Later sessions start directly on verified tasks"]+ end+```++## Was passiert, wenn man beides vermischt++Das direkteste Problem: Das Fundament härtet nicht richtig aus. Der Agent verbringt 80% seiner Mühe auf Feature-Code und 20% mit beiläufigem Aufbau etwas Infrastruktur. Das Test-Framework ist konfiguriert, aber nie verifiziert, Lint-Regeln sind gesetzt, aber zu lasch, keine Fortschrittsdatei erstellt. Diese Mängel sind in der ersten Session nicht offensichtlich (weil der Agent sich noch an das erinnert, was er getan hat), aber sie tauchen in der zweiten Session auf — der neue Agent weiß nicht, wie man ausführt, testet oder wo die Dinge stehen. Schlechtes Fundament, wackeliges Gebäude.++Ein noch verborgenerer Kostenfaktor ist die „unverifizierte Akkumulation" — Feature-Code, der geschrieben wurde, bevor das Test-Framework konfiguriert ist, ist Code ohne Verifizierung. Wenn man schließlich zurückgeht, um Tests für diesen Code hinzuzufügen, könnte man feststellen, dass das Design von Anfang an falsch war — hätte man es gewusst, hätte man es anders implementiert. Wie Fliesen auf nassem Beton — wenn man entdeckt, dass der Boden nicht eben ist, müssen alle Fliesen herausgebrochen und neu verlegt werden.++Das Session-Budget wird ebenfalls verschwendet. Initialisierungsarbeit (Umgebungen konfigurieren, Tests einrichten, Projektstruktur verstehen) verbraucht signifikantes Budget und lässt weniger für die eigentliche Feature-Implementierung. Ergebnis: Die erste Session schließt nur die Hälfte der Features ab, und die zweite Session muss das Projektverständnis von vorne beginnen. Budget für das Fundament ausgegeben, aber das Fundament ist auch nicht solide — keines der beiden Ziele erreicht.++Das am leichtesten übersehene Problem sind implizite Annahmen-Landminen. Entscheidungen, die der Agent während der Initialisierung trifft (welches Test-Framework, wie Verzeichnisse organisieren, Abhängigkeitsverwaltung) — wenn sie nicht explizit dokumentiert werden, können nachfolgende Sessions diese Entscheidungen nicht nachvollziehen. Schlimmer noch, nachfolgende Sessions könnten widersprüchliche Entscheidungen treffen. Die erste Baumannschaft hat ein Betonfundament verwendet, die zweite weiß es nicht und hat Holzpfähle hineingetrieben — das Fundament reißt.++Anthropics Forschung zur Entwicklung langlebiger Anwendungen empfiehlt ausdrücklich die Trennung von Initialisierung und Implementierung. Ihre experimentellen Daten: Projekte mit einer dedizierten Initialisierungsphase zeigten in Multi-Session-Szenarien eine um 31% höhere Feature-Abschlussrate im Vergleich zu gemischten Ansätzen. Die zentrale Erkenntnis — die in die Initialisierungsphase investierte Zeit wird in den nächsten 3–4 Sessions vollständig zurückgewonnen. Je solider das Fundament, desto schneller gehen die Wände hoch.++OpenAIs Codex harness Engineering-Leitfaden betont ebenfalls das Prinzip „Repository als operativer Datensatz" — etablieren Sie von Anfang an eine klare Betriebsstruktur, sonst muss jede neue Session Projektkonventionen neu erschließen.++## Zentrale Konzepte++- **Initialisierungsphase**: Die erste Phase im Lebenszyklus des Agenten — keine Feature-Implementierung, nur die Schaffung von Voraussetzungen für alle nachfolgenden Implementierungsphasen. Die Ausgabe ist kein Code, sondern Infrastruktur.+- **Bootstrap-Vertrag**: Die Bedingungen, unter denen ein Projekt von einer neuen Agenten-Session eindeutig betrieben werden kann — kann starten, kann testen, kann Fortschritt sehen, kann nächste Schritte aufnehmen. Vier Bedingungen, alle erforderlich.+- **Kaltstart vs. Warmstart**: Kaltstart bedeutet ein leeres Verzeichnis, in dem der Agent die Projektstruktur erraten muss; Warmstart bedeutet eine Vorlage oder ein bestehendes Projekt, in dem die Infrastruktur bereits vorhanden ist. Warmstart schneidet deutlich besser ab — wie das Arbeiten auf einer Baustelle mit fließendem Wasser und Strom versus dem Beginn auf einer kargen Brache.+- **Übergabebereitschaft**: Das Projekt befindet sich jederzeit in einem Zustand, in dem ein neuer Agent übernehmen kann. Keine mündliche Erklärung nötig — nur der Repo-Inhalt.+- **Zeit bis zur ersten Verifizierung**: Die Zeit vom Projektstart bis zum ersten bestandenen Feature-Verifizierungspunkt. Dies ist die Kernkennzahl zur Messung der Initialisierungseffizienz.+- **Downstream-Verwendbarkeit**: Das beste Maß für die Initialisierungsqualität — der Anteil nachfolgender Sessions, die erfolgreich Aufgaben ausführen können, ohne auf implizites Wissen angewiesen zu sein.++## Wie man Initialisierung richtig durchführt++**Behandeln Sie Initialisierung als dedizierte Phase.** Die erste Session führt nur Initialisierung durch — überhaupt kein Geschäfts-Feature-Code. Initialisierung produziert:++**1. Ausführbare Umgebung.** Das Projekt startet, Abhängigkeiten sind installiert, keine Umgebungsprobleme. Fundament gegossen, keine Risse.++**2. Verifizierbares Test-Framework.** Mindestens ein Beispieltest ist bestanden. Das beweist, dass das Test-Framework selbst richtig konfiguriert ist — wie das Aufstellen einer Säule auf dem Fundament, um zu beweisen, dass es Gewicht tragen kann.++**3. Bootstrap-Vertragsdokument.** Ein klares Dokument, das nachfolgenden Sessions sagt:+```markdown+# Initialization Contract++## Start Commands+- Install dependencies: `make setup`+- Start dev server: `make dev`+- Run tests: `make test`+- Full verification: `make check`++## Current State+- All dependencies installed and locked+- Test framework configured (Vitest + React Testing Library)+- Example test passing (1/1)+- Lint rules configured (ESLint + Prettier)++## Project Structure+- src/ — Source code+- src/components/ — React components+- src/api/ — API client+- tests/ — Test files+```++**4. Aufgaben-Aufschlüsselung.** Teilen Sie das gesamte Projekt in eine geordnete Aufgabenliste auf, jede Aufgabe mit klaren Akzeptanzkriterien:+```markdown+# Task Breakdown++## Task 1: User Authentication Basics+- Implement JWT auth middleware+- Add login/register endpoints+- Acceptance: pytest tests/test_auth.py all passing++## Task 2: User Profile Page+- Implement user profile CRUD+- Add profile edit form+- Acceptance: pytest tests/test_profile.py all passing++## Task 3: Search Feature+- ...+```++**5. Git-Commit als Kontrollpunkt.** Nach Abschluss der Initialisierung einen sauberen Kontrollpunkt committen. Alle nachfolgende Arbeit beginnt ab diesem Kontrollpunkt.++**Warmstart-Strategie**: Nicht mit einem leeren Verzeichnis beginnen. Verwenden Sie eine Projektvorlage (create-react-app, fastapi-template, etc.), um eine Standardverzeichnisstruktur, Abhängigkeitskonfiguration und Test-Framework vorzugeben. Backen Sie häufige Initialisierungsschritte in die Vorlage ein und lassen Sie nur projektspezifische Initialisierungsarbeit übrig. Wie das Arbeiten auf einer Baustelle mit fließendem Wasser und Strom — zehntausendmal besser als der Beginn auf einer kargen Brache.++**Initialisierungs-Abschlusskriterien**: Nicht „wie viel Code geschrieben wurde", sondern ob die vier Bedingungen des Bootstrap-Vertrags erfüllt sind — kann starten, kann testen, kann Fortschritt sehen, kann nächste Schritte aufnehmen. Verwenden Sie diese Checkliste zur Validierung der Initialisierung:++```markdown+## Initialization Acceptance Checklist+- [ ] `make setup` succeeds from scratch+- [ ] `make test` has at least one passing test+- [ ] A new agent session can answer "how to run" and "how to test" from repo contents alone+- [ ] Task breakdown file exists with at least 3 tasks+- [ ] Everything committed to git+```++## Praxisbeispiel++Zwei Initialisierungsansätze für ein React-Frontend-Projekt:++**Gemischter Ansatz (Fundament gießen und Wände gleichzeitig bauen)**: Der Agent erstellte gleichzeitig Projektgerüst und implementierte das erste Feature in Session 1. Am Session-Ende hatte das Repo ausführbaren Code, aber: keine explizite Start-/Test-Befehlsdokumentation, keine Fortschritts-Tracking-Datei, keine Aufgaben-Aufschlüsselung. Session 2 verbrachte ~20 Minuten damit, Projektstruktur, Test-Framework und Build-Prozess zu erschließen — wie eine neue Baumannschaft, die auf einer Baustelle ankommt, nicht weiß, wie weit das Fundament ist oder wo die Rohre verlaufen, und Loch für Loch graben muss, um es herauszufinden.++**Dedizierte Initialisierung (erst das Fundament)**: Session 1 führte nur Initialisierung durch — erstellte Verzeichnisstruktur aus einer Vorlage, konfigurierte das Test-Framework (Vitest + React Testing Library), schrieb und verifizierte einen Beispieltest, erstellte das Bootstrap-Vertragsdokument und die Aufgaben-Aufschlüsselungsdatei, committete den initialen Kontrollpunkt. Session 2s Rebuild-Zeit lag unter 3 Minuten, und sie begann direkt aus der Aufgabenliste zu arbeiten — die Mannschaft kommt an, wirft einen Blick auf den Bauplan und weiß genau, wo sie ansetzen muss.++Vergleich über den gesamten Projektzyklus: Die gesamte Rebuild-Zeit des gemischten Ansatzes (über alle Sessions) lag ~60% höher als beim dedizierten Initialisierungsansatz. Die zusätzlichen 20 Minuten für die Initialisierung wurden in nachfolgenden Sessions vielfach zurückgewonnen. Wie ein solides Fundament, das die Wände schneller hochgehen lässt — langsam ist schnell.++## Wichtigste Erkenntnisse++- Initialisierung und Implementierung haben unterschiedliche Optimierungsziele — ihre Vermischung zieht nur beide herunter. Erst das Fundament gießen, dann die Wände bauen.+- Die Ausgabe der Initialisierung ist kein Code, sondern Infrastruktur: ausführbare Umgebung, verifizierbare Tests, Bootstrap-Vertrag, Aufgaben-Aufschlüsselung.+- Validieren Sie die Initialisierung anhand der vier Bedingungen des Bootstrap-Vertrags: kann starten, kann testen, kann Fortschritt sehen, kann nächste Schritte aufnehmen.+- Warmstart schlägt Kaltstart. Verwenden Sie Projektvorlagen, um standardisierte Infrastruktur vorzugeben.+- Die in die Initialisierung investierte Zeit wird in den nächsten 3–4 Sessions vollständig zurückgewonnen. Das sind keine Mehrkosten — sondern eine Vorab-Investition. Je solider das Fundament, desto schneller geht das Gebäude hoch.++## Weiterführende Literatur++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)++## Übungen++1. **Bootstrap-Vertrag entwerfen**: Schreiben Sie einen vollständigen Bootstrap-Vertrag für ein Projekt, das Sie entwickeln. Öffnen Sie dann eine komplett neue Agenten-Session, zeigen Sie ihr nur den Repo-Inhalt (kein mündlicher Kontext), und lassen Sie sie versuchen, das Projekt zu starten, Tests auszuführen und den aktuellen Fortschritt zu verstehen. Notieren Sie jedes Problem, auf das sie stößt — jedes entspricht einer fehlenden Klausel in Ihrem Bootstrap-Vertrag.++2. **Vergleichsexperiment**: Wählen Sie ein moderat komplexes neues Projekt. Ansatz A: Den Agenten gleichzeitig initialisieren und die erste Implementierung durchführen lassen. Ansatz B: Eine Session für dedizierte Initialisierung aufwenden, Implementierung in Session 2 beginnen. Nach 4 Sessions vergleichen: Zeit bis zur ersten Verifizierung, Rebuild-Kosten, Feature-Abschlussrate.++3. **Initialisierungs-Akzeptanz-Checkliste**: Entwerfen Sie eine Initialisierungs-Akzeptanz-Checkliste für Ihr Projekt. Lassen Sie eine neue Agenten-Session jeden Checklistenpunkt ausführen und notieren Sie, welche bestehen und welche fehlschlagen. Die fehlschlagenden Punkte sind die Stellen, an denen Ihr harness verstärkt werden muss.diff --git a/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdnew file mode 100644index 0000000..1417956--- /dev/null+++ b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 07++Verwenden Sie diesen Ordner für Beispiele zu:++- One-Shot-Fehlern+- übergroßen Task-Prompts+- inkrementeller Aufgabenformung+- strukturierten Feature-Oberflächendiff --git a/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.mdnew file mode 100644index 0000000..fd96d40--- /dev/null+++ b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md@@ -0,0 +1,6 @@+# Nächste-Aufgabe-Vorlage++- Aktuelles Feature mit höchster Priorität:+- Warum dieses Feature als nächstes kommt:+- Was als bestanden gilt:+- Was während dieses Schritts nicht geändert werden darf:diff --git a/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdnew file mode 100644index 0000000..4510fa1--- /dev/null+++ b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -0,0 +1,17 @@+# Scope-Oberfläche Beispiel++Aufgabe:++- Indexierung zur Electron Knowledge-App hinzufügen++Schlechte Scope-Form:++- "Indexierung implementieren"++Bessere Scope-Form:++- Importierte Dokumente parsen+- Dokumente in Chunks aufteilen+- Chunk-Metadaten persistieren+- Indexierungsstatus in der UI anzeigen+- Eine Neu-Indexierungs-Aktion hinzufügendiff --git a/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.tsnew file mode 100644index 0000000..c587a1d--- /dev/null+++ b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts@@ -0,0 +1,151 @@+/**+ * scope-tracker.ts+ *+ * Reads a feature list and a change log. Enforces single-active-feature+ * policy. Given a log of changes, flags any changes outside the active+ * feature scope. Demonstrates how scope drift happens and how the tracker+ * catches it.+ *+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Feature {+ id: string;+ name: string;+ status: "active" | "pending" | "done";+}++interface ChangeLogEntry {+ step: number;+ file: string;+ description: string;+ featureId: string; // The feature this change claims to belong to+}++// ---------------------------------------------------------------------------+// Sample data+// ---------------------------------------------------------------------------++const features: Feature[] = [+ { id: "F-001", name: "Search endpoint", status: "active" },+ { id: "F-002", name: "Delete endpoint", status: "pending" },+ { id: "F-003", name: "Rate limiting", status: "pending" },+ { id: "F-004", name: "User dashboard", status: "pending" },+];++// A realistic change log where the agent gradually drifts from the active feature+const changeLog: ChangeLogEntry[] = [+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },+];++// ---------------------------------------------------------------------------+// Scope tracker+// ---------------------------------------------------------------------------++interface ScopeCheckResult {+ step: number;+ file: string;+ description: string;+ featureId: string;+ inScope: boolean;+ activeFeature: string;+}++function trackScope(+ featureList: Feature[],+ changes: ChangeLogEntry[]+): ScopeCheckResult[] {+ const activeFeatures = featureList.filter((f) => f.status === "active");+ const activeIds = new Set(activeFeatures.map((f) => f.id));+ const activeNames = activeFeatures.map((f) => f.name).join(", ");++ return changes.map((change) => ({+ step: change.step,+ file: change.file,+ description: change.description,+ featureId: change.featureId,+ inScope: activeIds.has(change.featureId),+ activeFeature: activeNames,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const results = trackScope(features, changeLog);++ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");+ console.log("=".repeat(100));++ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));++ // Detailed change log+ console.log("\n" + "-".repeat(100));+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;+ console.log(header);+ console.log(sep);++ let inScopeCount = 0;+ let driftCount = 0;++ for (const r of results) {+ const scopeLabel = r.inScope ? "OK" : "DRIFT";+ if (r.inScope) inScopeCount++;+ else driftCount++;++ const marker = r.inScope ? " " : ">>";+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE DRIFT SUMMARY");+ console.log("=".repeat(100) + "\n");++ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;+ console.log(sHeader);+ console.log(sSep);+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);++ // Drift detail+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];+ if (driftFeatures.length > 0) {+ console.log("\n DRIFTED FEATURES:");+ for (const fid of driftFeatures) {+ const feat = features.find((f) => f.id === fid);+ const driftChanges = results.filter((r) => r.featureId === fid);+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);+ }+ }++ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");+}++run();diff --git a/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdnew file mode 100644index 0000000..c052b15--- /dev/null+++ b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -0,0 +1,134 @@+[中文版本 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)+> Praxisprojekt: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)++# Lektion 07. Klare Aufgabengrenzen für Agenten ziehen++Sie sagen Claude Code, es soll „Benutzerauthentifizierung zu diesem Projekt hinzufügen", und es beginnt, das Datenbankschema zu ändern, Routen zu schreiben, Frontend-Komponenten zu bearbeiten und — während es gerade dabei ist — die Fehlerbehandlungs-Middleware zu refactoren. Zwei Stunden später überprüfen Sie: 12 Dateien geändert, 800 Zeilen neuer Code, und kein einziges Feature funktioniert End-to-End.++Sich mehr auf den Teller laden, als man bewältigen kann — dieses Sprichwort gilt für KI-Agenten ganz besonders. Agenten werden mit einem Impuls geboren, „noch etwas Extra zu erledigen" — sie sehen verwandte Dinge und erledigen sie einfach nebenbei, wie jemand, der für eine Flasche Sojasauce in den Supermarkt geht und mit einem vollen Einkaufswagen herauskommt. Das Problem ist: Menschen, die zu viel kaufen, verschwenden nur Geld; Agenten, die zu viele Dinge gleichzeitig tun, bedeuten, dass keines davon richtig erledigt wird.++Anthropics Engineering-Blog „Effective harnesses for long-running agents" stellt klar: Wenn Prompts zu breit gefasst sind, neigen Agenten dazu, „mehrere Dinge gleichzeitig zu beginnen" anstatt „erst eins zu Ende zu bringen." OpenAIs Codex-Engineering-Praktiken fanden dasselbe — Aufgaben ohne explizite Scope-Kontrollen sehen Abschlussraten einbrechen. Das ist kein Modellproblem — es ist ein harness-Problem. Sie haben die Grenze nicht gezogen.++## Aufmerksamkeit ist eine endliche Ressource++Das ist keine Metapher — es ist Mathematik. Angenommen, die Kontextkapazität des Agenten ist C und er aktiviert gleichzeitig k Aufgaben. Jede Aufgabe bekommt durchschnittlich C/k Reasoning-Ressourcen. Wenn C/k unter den Mindestschwellenwert fällt, der zum Abschluss einer einzelnen Aufgabe benötigt wird, wird keine davon fertig. Ihr Magen ist nur so groß — stopfen Sie zehn Knödel auf einmal hinein, und Sie verdauen sie nicht alle, Sie bekommen einfach zehnmal Verdauungsprobleme.++Claude Codes tatsächliches Verhalten ist aufschlussreich. Bitten Sie es, „Benutzerregistrierung hinzuzufügen", und es könnte:++1. Ein User-Modell erstellen+2. Die Registrierungsroute schreiben+3. Bemerken, dass E-Mail-Verifizierung nötig ist, also einen Mail-Service hinzufügen+4. Sehen, dass Passwörter gehasht werden müssen, also bcrypt einbinden+5. Bemerken, dass die Fehlerbehandlung inkonsistent ist, also die globale Error-Middleware refactoren+6. Sehen, dass die Testdateistruktur unordentlich ist, also das Verzeichnis reorganisieren++Sechs Schritte später ist jeder halb fertig. Keine End-to-End-Verifizierung, komplexe Kopplung zwischen dem halbfertigen Code, und die nächste Session, die alles aufarbeiten muss, wird völlig verloren sein. Wie jemand, der sechs Gerichte gleichzeitig kocht — jedes Gericht ist in der Pfanne, aber keines ist angerichtet. Sie alle verbrennen.++Anthropics experimentelle Daten unterstützen dies direkt: Agenten mit einer „kleiner nächster Schritt"-Strategie (entspricht WIP=1) zeigen eine um 37% höhere Aufgaben-Abschlussrate als Agenten mit breiten Prompts. Noch interessanter: Die Anzahl der vom Agenten generierten Codezeilen ist schwach negativ korreliert mit dem tatsächlichen Feature-Abschluss — mehr Code geschrieben, weniger Features abgeschlossen. Sich mehr auf den Teller laden, als man bewältigen kann, datenbewiesen.++## WIP=1-Workflow++```mermaid+flowchart LR+ Queue["Feature queue"] --> Pick["Pick exactly one task"]+ Pick --> Active["Only one active item"]+ Active --> Verify["Run end-to-end verification"]+ Verify -->|pass| Commit["Commit and unlock next task"]+ Verify -->|fail| Active+ Commit --> Queue+```++```mermaid+flowchart TB+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]+ Budget --> Many["WIP = 5<br/>C / 5 per task"]++ One --> Finish["One feature reaches passing state"]+ Many --> Partial["Five partial implementations"]+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]+```++## Zentrale Konzepte++- **Overreach**: Der Agent aktiviert in einer einzelnen Session mehr Aufgaben als optimal. Es ist quantifizierbar — 5 Features mit 0 bestandenen End-to-End-Tests ist Overreach.+- **Under-finish**: Das Verhältnis von Aufgaben, die End-to-End-Verifizierung bestehen, zu allen aktivierten Aufgaben, fällt unter den Schwellenwert. Geschriebener Code, aber keine bestandenen Tests, ist Under-finish.+- **WIP-Limit (Work-in-Progress-Limit)**: Aus der Kanban-Methodik. Kernidee: Begrenzen Sie, wie viele Aufgaben gleichzeitig in Bearbeitung sind. Für Agenten ist WIP=1 die sicherste Standardeinstellung — erst eins beenden, dann das nächste beginnen. Wie an einem Buffet — nicht den Teller überladen, erst einen Teller essen, dann zum nächsten gehen.+- **Abschluss-Evidenz**: Die verifizierbare Bedingung, die eine Aufgabe erfüllen muss, um von „in Bearbeitung" auf „erledigt" zu wechseln. Ohne dies substituieren Agenten „der Code sieht gut aus" durch „das Verhalten besteht die Tests."+- **Scope Surface**: Eine DAG-Struktur, bei der jeder Knoten eine Arbeitseinheit und die Kanten Abhängigkeiten sind. Zustände sind auf vier beschränkt: not_started, active, blocked, passing.+- **Abschluss-Druck**: Die einschränkende Kraft, die das harness durch WIP-Limits und Abschluss-Evidenz-Anforderungen ausübt und den Agenten zwingt, die aktuelle Aufgabe abzuschließen, bevor eine neue begonnen wird.++## Overreach und Under-finish sind symbiotisch++Diese beiden Probleme sind nicht unabhängig — sie verstärken sich gegenseitig. Overreach verdünnt die Aufmerksamkeit, verdünnte Aufmerksamkeit verursacht Under-finish, und der halbfertige Code, der zurückbleibt, erhöht die Systemkomplexität, was den Overreach bei der nächsten Aufgabe weiter treibt. Ein Teufelskreis.++In Kanban-Begriffen: Littles Gesetz besagt L = lambda * W. Wenn die Work-in-Progress L zu hoch ist (zu viele Dinge gleichzeitig), erhöht sich die Durchlaufzeit W für jede Aufgabe unvermeidlich. Für Agenten bedeutet das: Jedes Feature dauert länger vom Start bis zur verifizierten Fertigstellung, und die Wahrscheinlichkeit des Scheiterns wächst.++Dies ist auch in der menschlichen Welt ein altes Problem — Steve McConnell dokumentierte in *Rapid Development*, dass Scope Creep die häufigste Ursache für Projektversagen ist. Aber Menschen haben zumindest die Intuition „ich habe genug getan." Agenten haben das nicht. Die Generierung der nächsten Idee kostet das Modell fast keine zusätzlichen Token — „lass mich das auch noch reparieren, während ich hier bin" fällt kaum auf — aber jede zusätzliche Modifikation verdünnt die Aufmerksamkeit des Agenten. Wie an einem Buffet, wo jeder zusätzliche Teller nahezu grenzkostenfrei ist, aber Ihr Magen nur begrenzte Kapazität hat.++## Wie man es richtig macht++### 1. WIP=1 erzwingen++Das ist die direkteste und wirksamste Methode. Sagen Sie dem Agenten in Ihrem harness explizit: **zu jedem Zeitpunkt ist nur eine Aufgabe im Status „active" erlaubt.** In Claude Codes `CLAUDE.md` oder Codex' `AGENTS.md` schreiben Sie:++```+## Work Rules+- Work on one feature at a time+- Only start the next feature after the current one passes end-to-end verification+- Don't "also refactor" feature B while implementing feature A+```++Wie am Buffet essen — ein Teller nach dem anderen, erst essen, dann nachholen.++### 2. Explizite Abschluss-Evidenz für jede Aufgabe definieren++Fertig ist nicht „Code ist geschrieben" — es ist „Verhaltensverifizierung bestanden." In Ihrer feature list benötigt jeder Eintrag einen Verifizierungsbefehl:++```+F01: User Registration+ Verification: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201+ State: passing+```++### 3. Die Scope Surface externalisieren++Verwenden Sie eine maschinenlesbare Datei (JSON oder Markdown), um alle Aufgaben zustände zu dokumentieren. Jede neue Session kann diese Datei lesen und sofort wissen: Welche Aufgabe ist aktiv? Welches Verhalten gilt als erledigt? Welche Verifizierungen wurden bestanden?++### 4. Die verifizierte Abschlussrate überwachen++Das harness sollte kontinuierlich VCR (Verified Completion Rate) = verifizierte Aufgaben / aktivierte Aufgaben verfolgen. Blockieren Sie neue Aufgabenaktivierungen, wenn VCR < 1.0.++## Praxisbeispiel++Ein REST-API-Projekt mit 8 Features, zwei Strategien im Vergleich:++**Buffet-Modus (uneingeschränkt)**: Der Agent aktiviert 5 Features gleichzeitig in Session 1. Produziert ~800 Zeilen über 12 Dateien. End-to-End-Test-Bestehensrate: 20% — nur Benutzerregistrierung funktioniert. Die anderen 4 Features: Datenbankschema erstellt, aber Validierungslogik fehlt, Routen definiert, aber falsches Antwortformat. Wie jemand, der sechs Gerichte gleichzeitig kocht, nur eines ist kaum essbar. Ende Session 3 sind nur 3 von 8 Features abgeschlossen.++**Ein-Teller-Modus (WIP=1)**: Der Agent arbeitet in Session 1 nur an der Benutzerregistrierung. Produziert ~200 Zeilen über 4 Dateien. End-to-End-Tests: 100% bestanden. Committet eine saubere, verifizierte Implementierung. Ende Session 4 sind 7 von 8 Features abgeschlossen (das 8. blockiert durch eine externe Abhängigkeit).++Ergebnis: weniger Gesamtcodes (800 vs. 1200 Zeilen), aber mehr wirksamer Code. Abschlussrate: 87,5% vs. 37,5%. Einen Bissen nach dem anderen, und man isst tatsächlich mehr.++## Wichtigste Erkenntnisse++- **WIP=1 ist die sichere Standardeinstellung für Agenten-harnesses** — erst eines beenden, dann das nächste beginnen; nicht versuchen zu parallelisieren. Man wird nicht in einem Biss dick.+- **Abschluss-Evidenz muss ausführbar sein** — „der Code sieht gut aus" zählt nicht; „curl liefert 201" schon.+- **Die Scope Surface muss als Datei externalisiert werden** — nicht nur im Gespräch erwähnt, sondern in einem maschinenlesbaren Format im Repo dokumentiert.+- **Overreach und Under-finish sind symbiotisch** — die Lösung des einen löst das andere.+- **„Weniger tun, aber beenden" schlägt immer „mehr tun, aber halbfertig lassen"** — Agenten-Codezeilen und Feature-Abschlussrate sind negativ korreliert. Qualität schlägt immer Quantität.++## Weiterführende Literatur++- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropics Engineering-Blog, detaillierte Diskussion der „kleiner nächster Schritt"-Strategie+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — OpenAIs umfassende Abhandlung zum harness Engineering+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — Die klassische Quelle zu WIP-Limits+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — Empirische Daten zu Scope Creep als häufigster Ursache für Projektversagen++## Übungen++1. **Aufgaben-Atomisierung**: Wählen Sie eine breite Anforderung (z. B. „implementiere ein Benutzerverwaltungssystem") und brechen Sie sie in mindestens 5 atomare Arbeitseinheiten auf. Geben Sie für jede Einheit an: (a) eine einzelne Verhaltensbeschreibung, (b) einen ausführbaren Verifizierungsbefehl, (c) Abhängigkeiten. Prüfen Sie, ob die Zerlegung der WIP=1-Einschränkung genügt.++2. **Vergleichsexperiment**: Führen Sie dasselbe Projekt zweimal aus — einmal ohne Einschränkungen, einmal mit erzwungenem WIP=1. Vergleichen Sie: verifizierte Abschlussrate, Gesamtcodeszeilen, effektives Code-Verhältnis.++3. **Abschluss-Evidenz-Audit**: Überprüfen Sie die Ausgabe eines recenten Agenten-Laufs und klassifizieren Sie jede Code-Änderung als „abgeschlossenes Verhalten", „unvollständiges Verhalten" oder „Gerüstbau". Fügen Sie fehlende Verifizierungsbefehle für jedes unvollständige Verhalten hinzu.diff --git a/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..52d6a2b--- /dev/null+++ b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,218 @@+/**+ * feature-list-validator.ts+ *+ * Reads a feature_list.json, validates its schema, and checks for features+ * marked "pass" without verification evidence. Outputs a structured report.+ * Can run against any project directory that has a feature_list.json.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]+ * (defaults to the directory containing this script)+ *+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Allow unknown fields for flexibility+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Schema validation+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entry ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Missing or invalid 'id' field`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Missing or invalid 'category' field`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Missing or invalid 'description' field`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' must be an array if present`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' must be a boolean if present`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Evidence validation+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Process feature list+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve target directory+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);+ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" FEATURE LIST VALIDATOR");+ console.log("=".repeat(90));+ console.log(` Reading: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(` ERROR: feature_list.json not found at ${filePath}`);+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");+ process.exit(1);+ }++ let entries: FeatureEntry[];+ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");+ process.exit(1);+ }++ // For demo purposes, also validate an extended test set+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "User can import a PDF document.",+ verification: ["Upload a PDF file", "Verify it appears in the document list"],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "System hallucination rate is below 5%.",+ verification: [], // Empty -- no evidence+ passes: true, // Marked as pass WITHOUT evidence+ },+ {+ id: "missing-fields",+ // Missing 'category' and 'description'+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Print report+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";+ const notes = r.markedPassWithoutEvidence+ ? "FLAGGED: passes without evidence!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";+ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`+ );+ }++ // Summary+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;+ const withEvidence = results.filter((r) => r.hasVerification).length;++ console.log("\n" + "-".repeat(90));+ console.log(" SUMMARY");+ console.log("-".repeat(90));+ console.log(` Total features: ${total}`);+ console.log(` Schema valid: ${schemaOk}/${total}`);+ console.log(` Marked as passing: ${passing}/${total}`);+ console.log(` With verification evidence: ${withEvidence}/${total}`);+ console.log(` Flagged (pass without evidence): ${flagged}`);++ if (flagged > 0) {+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);+ console.log(" These features need verification before they can be trusted.\n");+ } else {+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");+ }+}++run();diff --git a/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..8b973e3--- /dev/null+++ b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",+ "verification": [+ "Import a markdown document",+ "Open the Q&A panel",+ "Ask a question about known content",+ "Verify the answer is returned",+ "Verify one or more citations are displayed"+ ],+ "passes": false+ }+]diff --git a/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdnew file mode 100644index 0000000..901fea7--- /dev/null+++ b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 08++Verwenden Sie diesen Ordner für Beispiele zu:++- Pass-State-Gating+- End-to-End-Verifikation+- Schwache vs. starke Abschlusskriterien+- Evaluator-Loop-Beispielendiff --git a/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdnew file mode 100644index 0000000..92f1740--- /dev/null+++ b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -0,0 +1,8 @@+# Pass-Gate-Richtlinie++Ein Feature darf nur von `passes: false` zu `passes: true` wechseln, wenn:++- der erwartete Workflow ausgeführt wurde+- der Erfolgsnachweis erfasst wurde+- kein blockierender Fehler im getesteten Pfad vorliegt+- die Implementierung die App nicht in einem defekten oder mehrdeutigen Zustand hinterlässtdiff --git a/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdnew file mode 100644index 0000000..2b88578--- /dev/null+++ b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -0,0 +1,138 @@+[中文版本 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> Praxisprojekt: [Projekt 04. Runtime-Feedback und Scope-Kontrolle](./../../projects/project-04-incremental-indexing/index.md)++# Lektion 08. Feature-Listen nutzen, um Agentenarbeit zu begrenzen++Du bittest einen Agenten, eine E-Commerce-Seite zu bauen. Nachdem er fertig ist, sagt er "done". Du schaust in den Code: Die Benutzeranmeldung funktioniert, aber der Checkout-Button im Warenkorb macht nichts, und der Zahlungsfluss ist gar nicht verbunden. Das Problem: Du hast nie gesagt, was "done" bedeutet. Also verwendet der Agent seinen eigenen Standard: "Ich habe viel Code geschrieben, und es sieht ziemlich vollständig aus."++In den Augen vieler Menschen sind Feature-Listen nur Notizzettel: Dinge aufschreiben, damit man sie nicht vergisst, und dann beiseitelegen. In der Harness-Welt aber ist eine Feature-Liste kein Memo für Menschen, sondern das Rückgrat des gesamten Harness. Der Scheduler nutzt sie, um Aufgaben auszuwählen; der Verifier nutzt sie, um Abschluss zu beurteilen; der Handoff Reporter nutzt sie, um Zusammenfassungen zu erzeugen. Bricht das Rückgrat, ist der ganze Körper gelähmt.++Anthropic und OpenAI betonen beide: **Artefakte müssen externalisiert werden.** Feature-Zustand muss in einer maschinenlesbaren Datei im Repo liegen, nicht in unstrukturiertem Konversationstext.++## Agenten wissen nicht, was "done" bedeutet++Weder Claude Code noch Codex wissen automatisch, was du mit "done" meinst. Du sagst "füge eine Warenkorb-Funktion hinzu", und das Modell interpretiert das vielleicht als "schreibe eine Cart-Komponente und eine addToCart-Methode". Du meinst aber: "Der Nutzer kann Produkte ansehen, in den Warenkorb legen und den Checkout end-to-end abschließen." Ohne Feature-Liste bleibt diese Verständnislücke bestehen. Der Agent nutzt seinen impliziten Standard, meistens "der Code hat keine offensichtlichen Syntaxfehler". Was du brauchst, ist end-to-end-Verifikation des Verhaltens. Wie wenn du einen Freund bittest, Obst zu kaufen: Du sagst "bring etwas Obst mit", und er kommt mit Zitronen zurück. Sein Obst und dein Obst sind nicht dasselbe.++Sieh dir diese typische Fortschrittsnotiz an:++```+Did user auth, shopping cart mostly done, still need payments+```++Kann eine neue Agentensitzung daraus diese Fragen beantworten? Was bedeutet "mostly done"? Welche Tests hat der Warenkorb bestanden? Was blockiert Payments? Die Antwort auf alles lautet: "Niemand weiß es." Wie wenn du deinem Arzt sagst: "Mein Bauch tut weh, war in letzter Zeit schon okay" - welches Medikament soll er verschreiben?++Das Ergebnis: Die neue Sitzung verbringt 20 Minuten damit, den Projektzustand zu erschließen, und implementiert möglicherweise bereits fertige Features erneut. Anthropics Engineering-Daten zeigen, dass gute Fortschrittsaufzeichnungen die Diagnosezeit beim Sitzungsstart um 60-80% reduzieren.++## Feature-Zustandsmaschine++```mermaid+flowchart LR+ Feature["Eine Feature-Zeile"] --> Behavior["Verhalten<br/>z. B.: POST /cart/items returns 201"]+ Feature --> Check["Verifikationsbefehl<br/>der exakte Check"]+ Feature --> State["Zustand<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["Erst mit allen drei Feldern<br/>ist die Feature-Zeile nutzbar"]+ Check --> Complete+ State --> Complete+```++```mermaid+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["Nächstes not_started-Element wählen"]+ Scheduler --> Agent["Agent arbeitet an genau diesem Element"]+ Agent --> Verifier["Verifikationsbefehl dieses Elements ausführen"]+ Verifier -->|pass| Passing["Als passing markieren<br/>und Evidenz schreiben"]+ Verifier -->|fail| Active["Active lassen"]+ Verifier -->|dependency issue| Blocked["Als blocked markieren"]+ Passing --> Handoff["Handoff-Notiz und aktuellen Fortschritt aktualisieren"]+ Active --> Agent+```++## Zentrale Konzepte++- **Feature-Listen sind Harness-Primitives**: Keine "optionalen Planungstools", sondern grundlegende Datenstrukturen, von denen alle anderen Harness-Komponenten abhängen. Wie Datenbanktabellenstrukturen: Man kann nicht sagen "lassen wir Primärschlüssel weg".+- **Dreifachstruktur**: Jedes Feature-Element ist ein Tripel `(Verhaltensbeschreibung, Verifikationsbefehl, aktueller Zustand)`. Fehlt ein Element, ist das Element unvollständig.+- **Zustandsmaschinenmodell**: Jedes Feature-Element hat vier Zustände: `not_started`, `active`, `blocked`, `passing`. Zustandsübergänge werden vom Harness kontrolliert, nicht frei vom Agenten geändert.+- **Pass-state gating**: Der einzige Weg von `active` zu `passing` ist ein erfolgreich ausgeführter Verifikationsbefehl. Das ist irreversibel: Einmal `passing`, kein Zurück. Wie bei einer bestandenen Prüfung: Bestanden ist bestanden; die Note wird nicht rückwirkend geändert.+- **Single source of truth**: Alle Informationen darüber, "was zu tun ist", müssen aus einer einzigen Feature-Liste stammen. Keine Widersprüche zwischen Feature-Liste und Gesprächsverlauf.+- **Back-pressure**: Die Anzahl der noch nicht bestandenen Features ist der Druck, den der Harness auf den Agenten ausübt. Druck null = Projekt abgeschlossen.++## Warum Feature-Listen "Primitives" sein müssen++Dokumente sind zum Lesen durch Menschen da; Primitives sind zur Ausführung durch Systeme da. Dokumente können ignoriert werden; Primitives kann man nicht umgehen.++Denke an Datenbank-Trigger-Constraints im Vergleich zu Checks auf Anwendungsebene: Erstere werden von der Datenbank-Engine erzwungen, kein SQL kann sie überspringen; Letztere hängen von der Korrektheit des Anwendungscodes ab und können versehentlich umgangen werden. Als Harness-Primitive dient die Feature-Liste vier Komponenten:++1. **Scheduler**: Liest Zustände und wählt das nächste `not_started`-Feature. Wie ein Produktionsplanungssystem in einer Fabrik.+2. **Verifier**: Führt Verifikationsbefehle aus und entscheidet, ob Zustandsübergänge erlaubt sind. Wie Qualitätskontrolle.+3. **Handoff reporter**: Erzeugt automatisch Übergabezusammenfassungen aus der Feature-Liste. Wie ein automatischer Schichtwechselbericht.+4. **Progress tracker**: Zählt Zustandsverteilungen und liefert Gesundheitsmetriken des Projekts. Wie ein Dashboard.++## Wie man es richtig macht++### 1. Ein minimales Feature-Listen-Format definieren++Du brauchst kein komplexes System. Eine strukturierte Markdown- oder JSON-Datei reicht. Entscheidend ist, dass jeder Eintrag das Tripel enthält:++```json+{+ "id": "F03",+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",+ "state": "passing",+ "evidence": "commit abc123, test output log"+}+```++### 2. Den Harness Zustandsübergänge kontrollieren lassen++Der Agent kann den Zustand eines Features nicht direkt auf `passing` setzen. Er kann nur eine Verifikationsanfrage stellen. Der Harness führt den Verifikationsbefehl aus und entscheidet, ob der Übergang erlaubt ist. Das ist pass-state gating.++### 3. Die Regeln in CLAUDE.md schreiben++```+## Feature List Rules+- Feature list file: /docs/features.md+- Only one feature active at a time+- Verification command must pass before marking as passing+- Don't modify feature list states yourself — the verification script updates them automatically+```++### 4. Granularität kalibrieren++Jedes Feature-Element sollte auf "in einer Sitzung abschließbar" zugeschnitten sein. Zu breit, und es wird nicht fertig; zu eng, und der Verwaltungsaufwand steigt. "Nutzer kann Artikel in den Warenkorb legen" ist gute Granularität. "Den Warenkorb implementieren" ist zu breit. "Das name-Feld im Cart-Modell erstellen" ist zu eng. Wie ein Steak schneiden: nicht das ganze Stück und nicht Hackfleisch.++## Praxisfall++Eine E-Commerce-Plattform mit 10 Features. Zwei Tracking-Ansätze wurden verglichen:++**Memo-Modus**: Der Agent nutzt unstrukturierte Notizen. Nach 3 Sitzungen lauten sie: "user auth und product list erledigt, shopping cart mostly done, aber Bugs, payments nicht begonnen." Eine neue Sitzung braucht 20 Minuten, um den Zustand zu erschließen, und implementiert am Ende abgeschlossene Features erneut. Wie eine Einkaufsliste mit "Milch, Brot und dieses Ding" - im Laden weißt du immer noch nicht, was du kaufen sollst.++**Rückgrat-Modus**: Jedes Feature hat einen klaren Zustand und einen Verifikationsbefehl. Eine neue Sitzung liest die Feature-Liste und weiß in 3 Minuten: F01-F05 sind `passing`, F06 ist `active`, F07-F10 sind `not_started`. Sie macht direkt bei F06 weiter, ohne Nacharbeit.++Quantifiziertes Ergebnis: Projekte mit strukturierten Feature-Listen zeigen eine 45% höhere Feature-Abschlussrate als Freiform-Tracking, bei null doppelten Implementierungen.++## Wichtigste Erkenntnisse++- **Feature-Listen sind das Rückgrat des Harness**, keine Memos für Menschen. Scheduler, Verifier und Handoff Reporter hängen alle davon ab.+- **Jedes Feature-Element braucht das Tripel**: Verhaltensbeschreibung + Verifikationsbefehl + aktueller Zustand. Fehlt ein Element, ist es unvollständig - wie ein dreibeiniger Hocker, dem ein Bein fehlt.+- **Zustandsübergänge werden vom Harness kontrolliert**; der Agent kann Zustände nicht selbst ändern. Erfolgreiche Verifikation ist der einzige Aufstiegspfad.+- **Die Feature-Liste ist die single source of truth des Projekts**; alle "was tun"-Informationen stammen aus einer Liste.+- **Kalibriere Granularität auf "in einer Sitzung abschließbar".**++## Weiterführende Literatur++- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — Identifiziert die Feature-Liste ausdrücklich als "core data structure" zur Kontrolle des Agenten-Scopes+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Betont das Prinzip der "externalizing artifacts"+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — Contract-Design-Prinzipien, theoretische Grundlage von Feature-Listen+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — Testpyramide und Praktiken für verhaltensbasierte Spezifikation++## Übungen++1. **Feature-Listen-Design**: Definiere ein minimales JSON-Schema für Feature-Listen. Enthalten: id, Verhaltensbeschreibung, Verifikationsbefehl, aktueller Zustand, Evidenzreferenz. Beschreibe damit ein echtes Projekt mit 5 Features.++2. **Vergleich der Verifikationsstrenge**: Wähle 3 Features und entwirf sowohl eine "lockere" Verifikation (z. B. "Code hat keine Syntaxfehler") als auch eine "strenge" Verifikation (z. B. "End-to-End-Test besteht"). Vergleiche die False-Positive-Rate.++3. **Audit des Single-Source-Prinzips**: Prüfe ein bestehendes Agentenprojekt auf Scope-Informationen, die der Feature-Liste widersprechen (implizite Anforderungen in Gesprächen, TODO-Kommentare im Code usw.). Entwirf einen Plan, um alle Informationen in der Feature-Liste zu vereinheitlichen.diff --git a/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.mdnew file mode 100644index 0000000..9963061--- /dev/null+++ b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md@@ -0,0 +1,6 @@+# Clean-State-Checkliste++- App startet ohne manuelle Reparatur+- Aktueller Fortschritt ist dokumentiert+- Kein halbfertiger Import- oder Indexierungsschritt bleibt undokumentiert+- Der nächste Agent kann den Standard-Start- und Verifikationspfad sofort ausführendiff --git a/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdnew file mode 100644index 0000000..a9c30d5--- /dev/null+++ b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 09++Verwenden Sie diesen Ordner für Beispiele zu:++- Logs als Feedback+- Laufzeitzustand-Sichtbarkeit+- Clean-State-Prüfungen+- Wiederherstellungsbeispielendiff --git a/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.tsnew file mode 100644index 0000000..fad1a3b--- /dev/null+++ b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts@@ -0,0 +1,241 @@+/**+ * victory-detector.ts+ *+ * Simulates an agent that claims task completion, then checks the claimed+ * state against actual verification. Outputs: claimed vs actual, highlighting+ * gaps between what the agent said and what's really true.+ *+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Task {+ name: string;+ claimedComplete: boolean;+ checks: VerificationCheck[];+}++interface VerificationCheck {+ description: string;+ claimed: boolean; // What the agent says+ actual: boolean; // What is actually true+ severity: "critical" | "warning";+}++// ---------------------------------------------------------------------------+// Simulated tasks with claimed vs actual states+// ---------------------------------------------------------------------------++const tasks: Task[] = [+ {+ name: "Add search endpoint",+ claimedComplete: true,+ checks: [+ {+ description: "Route handler exists",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Authentication middleware applied",+ claimed: true,+ actual: false, // Agent forgot auth+ severity: "critical",+ },+ {+ description: "Input validation added",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Unit tests written",+ claimed: true,+ actual: false, // Agent skipped tests+ severity: "critical",+ },+ {+ description: "Integration tests pass",+ claimed: true,+ actual: false, // No tests to run+ severity: "critical",+ },+ {+ description: "Documentation updated",+ claimed: true,+ actual: false, // Agent skipped docs+ severity: "warning",+ },+ ],+ },+ {+ name: "Fix pagination bug",+ claimedComplete: true,+ checks: [+ {+ description: "Bug reproduction case confirmed",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Root cause identified",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Fix applied",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Edge cases tested",+ claimed: true,+ actual: false, // Only happy path tested+ severity: "warning",+ },+ {+ description: "Regression tests added",+ claimed: true,+ actual: false,+ severity: "critical",+ },+ ],+ },+ {+ name: "Refactor auth module",+ claimedComplete: true,+ checks: [+ {+ description: "Old code removed",+ claimed: true,+ actual: false, // Old code still present+ severity: "warning",+ },+ {+ description: "All existing tests still pass",+ claimed: true,+ actual: false, // Two tests broke+ severity: "critical",+ },+ {+ description: "New auth flow works",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Migration guide written",+ claimed: true,+ actual: false,+ severity: "warning",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Verification+// ---------------------------------------------------------------------------++interface TaskVerification {+ taskName: string;+ claimedComplete: boolean;+ actuallyComplete: boolean;+ totalChecks: number;+ claimedPassing: number;+ actualPassing: number;+ gaps: { description: string; severity: string }[];+}++function verifyTask(task: Task): TaskVerification {+ const claimedPassing = task.checks.filter((c) => c.claimed).length;+ const actualPassing = task.checks.filter((c) => c.actual).length;+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);++ return {+ taskName: task.name,+ claimedComplete: task.claimedComplete,+ actuallyComplete: gaps.length === 0,+ totalChecks: task.checks.length,+ claimedPassing,+ actualPassing,+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");+ console.log("=".repeat(90));++ const verifications = tasks.map(verifyTask);++ for (const v of verifications) {+ console.log("\n Task: " + v.taskName);+ console.log(" " + "-".repeat(70));+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);++ if (!v.actuallyComplete) {+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);+ }++ // Detailed checks for this task+ const task = tasks.find((t) => t.name === v.taskName)!;+ console.log("\n Check detail:");+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;+ console.log(header);+ console.log(sep);++ for (const check of task.checks) {+ const claimedLabel = check.claimed ? "PASS" : "FAIL";+ const actualLabel = check.actual ? "PASS" : "FAIL";+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";+ const marker = gapLabel ? ">>" : " ";+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);+ }+ }++ // Overall summary+ console.log("\n" + "=".repeat(90));+ console.log(" OVERALL SUMMARY");+ console.log("=".repeat(90) + "\n");++ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;+ console.log(sHeader);+ console.log(sSep);++ for (const v of verifications) {+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);+ const cLabel = v.claimedComplete ? "Done" : "Pending";+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);+ }++ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;++ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");+ console.log(" Total undetected gaps: " + totalGaps);+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");+}++run();diff --git a/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdnew file mode 100644index 0000000..6cbcdb1--- /dev/null+++ b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -0,0 +1,145 @@+[中文版本 →](../../../zh/lectures/lecture-09-why-agents-declare-victory-too-early/)++> Codebeispiele für diese Lektion: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/code/)+> Praxisprojekt: [Project 05. Lassen Sie den Agenten seine eigene Arbeit überprüfen](./../../projects/project-05-grounded-qa-verification/index.md)++# Lektion 09. Verhindern, dass Agenten zu früh Erfolg melden++Sie bitten einen Agenten, eine „Passwort zurücksetzen"-Funktion zu implementieren. Er ändert das Datenbankschema, schreibt den API-Endpunkt, fügt die E-Mail-Vorlage hinzu, führt Unit-Tests aus (alle bestanden) und teilt Ihnen zuversichtlich mit: „Es ist fertig." Wenn Sie es tatsächlich ausprobieren — der Link zum Zurücksetzen des Passworts kann nicht gesendet werden (E-Mail-Service-Konfiguration fehlt), die Datenbankmigration scheitert zur Hälfte (Schemainkonsistenz), und der End-to-End-Ablauf wurde kein einziges Mal ausgeführt.++Dieses Gefühl sollte nicht un vertraut sein — es ist, als würde man das gesamte Klausurheft ausfüllen, zuversichtlich als Erster abgeben und dann durchfallen, wenn die Noten kommen. Nur weil das Heft voll ist, heißt das nicht, dass die Antworten richtig sind.++Dies ist kein Einzelfall. Das klassische ICML-Papier von Guo et al. (2017) hat bewiesen: **Moderne neuronale Netze sind systematisch über confident** — die von Modellen berichtete Zuversicht ist deutlich höher als ihre tatsächliche Genauigkeit. Dasselbe gilt für KI-Coding-Agenten: Sie „fühlen", dass sie fertig sind, aber in Wirklichkeit sind sie weit davon entfernt. Ihr Harness muss die „Gefühle" des Agenten durch externalisierte, ausführungsbasierte Verifikation ersetzen.++## Die rutschige Abwärtsspirale++Voreilige Fertigstellungsmeldungen folgen fast immer demselben Muster: Der Code sieht in Ordnung aus — Syntax ist korrekt, Logik erscheint plausibel, und die statische Analyse zeigt keine offensichtlichen Fehler. Aber der Harness erzwingt keine umfassende Ausführungs verifikation, also überspringt der Agent das tatsächliche Ausführen oder führt nur teilweise Tests durch. Er führt Unit-Tests durch, überspringt aber Integrationstests; er führt Tests durch, prüft aber keine Abdeckung. Letztendlich wird „der Code sieht gut aus" als Beweis dafür genommen, dass „die Funktion vollständig ist". Und das Klausurheft wird abgegeben.++Bei jedem Schritt geht Information verloren. Von der Aufgaben spezifikation über die Code-Implementierung bis zum Laufzeitverhalten — jede Transformation kann Verzerrungen einführen, und jede übersprungene Verifikation verschärft die Informationsasymmetrie.++## Drei-Schichten-Abschlussprüfung++```mermaid+flowchart LR+ Claim["Agent sagt: fertig"] --> L1["Zuerst ausführen<br/>lint / typecheck"]+ L1 --> L2["Dann ausführen<br/>Tests und Startup-Checks"]+ L2 --> L3["Schließlich ausführen<br/>kompletten User-Flow"]+ L3 --> Done["Alle drei bestanden = fertig"]+```++```mermaid+flowchart LR+ A["Code ist geschrieben<br/>Unit-Tests sind grün"] --> B["Aber die App startete nicht wirklich<br/>kompletter Flow nie ausgeführt"]+ B --> C["Config-, DB-, externe Service-Probleme<br/>bleiben alle verborgen"]+ C --> D["Also meldet der Agent zu früh Erfolg"]+```++## Zentrale Konzepte++- **Voreilige Fertigstellungsmeldung**: Der Agent behauptet, die Aufgabe sei abgeschlossen, aber es existieren noch immer nicht erfüllte Korrektheitsspezifikationen. Das Kernproblem: Der Agent urteilt auf Basis lokaler Zuversicht auf Code-Ebene, während systemweite Korrektheit globale Verifikation erfordert.+- **Confidence-Calibration-Bias**: Die systematische Lücke zwischen der selbst berichteten Zuversicht des Agenten bezüglich der Fertigstellung und der tatsächlichen Qualitäts der Fertigstellung. Bei komplexen Multi-Datei-Aufgaben ist dieser Bias signifikant positiv — der Agent ist immer zuversichtlicher, als er tatsächlich leistet. Wie ein Student, der seine Klausurnote nach der Prüfung immer überschätzt.+- **Terminierungskriterien**: Eine klare, ausführbare Menge von Beurteilungsbedingungen, die im Harness definiert sind. Der Agent muss alle Bedingungen erfüllen, bevor er die Fertigstellung meldet. „Fertig" wandelt sich von einem subjektiven Urteil zu einer objektiven Feststellung.+- **Verifikation-Validierung-Doppeltor**: Die erste Verifikationsschicht prüft „hat der Code das spezifizierte Verhalten korrekt implementiert"; die zweite Validierungsschicht prüft „entspricht das Systemverhalten den End-to-End-Anforderungen". Beide müssen bestanden werden, um als vollständig zu gelten.+- **Laufzeit-Feedback-Signale**: Logs, Prozesszustände und Health-Checks aus der Programmausführung. Dies ist die objektive Grundlage für den Harness, um die Qualität der Fertigstellung zu beurteilen.+- **Abschlussprioritäts-Einschränkung**: Zuerst funktionale Korrektheit verifizieren, dann Performance behandeln und schließlich Stil ansprechen. Refactoring ist verboten, bis die Kernfunktionalität verifiziert ist.++## Bestandene Unit-Tests ≠ Aufgabe erledigt++Das ist die häufigste Falle und die gefährlichste. Der Agent hat den Code geschrieben, die Unit-Tests ausgeführt, alles grün bekommen und „fertig" gesagt. Aber die Entwurfsphilosophie von Unit-Tests — Isolierung der getesteten Einheit und Mocking von Abhängigkeiten — ist genau das, was sie unfähig macht, komponentenübergreifende Probleme zu erkennen:++**Schnittstellen-Inkonsistenz**: Der vom Render-Prozess an das Preload-Skript übergebene Dateipfad ist ein relativer Pfad, aber das Preload-Skript erwartet einen absoluten Pfad. Ihre jeweiligen Unit-Tests haben beide Mocks verwendet und bestanden. Das Problem wird erst beim End-to-End-Testing entdeckt. Wie Musiker in einer Band, die jeweils für sich perfekt proben, nur um beim Zusammenspiel festzustellen, dass sie in verschiedenen Tonarten spielen.++**Zustandspropagationsfehler**: Eine Datenbankmigration ändert das Tabellenschema, aber die ORM-Zwischenspeicher schicht enthält noch Cache-Einträge für das alte Schema. Unit-Tests stellen jedes Mal eine frische Mock-Umgebung bereit, was diese schichtenübergreifende Zustandsinkonsistenz nicht aufdeckt.++**Umgebungsabhängigkeit**: Der Code verhält sich in der Testumgebung korrekt (wo alles gemockt ist), scheitert aber in der realen Umgebung aufgrund von Konfigurationsunterschieden, Netzwerklatenz oder Dienstverfügbarkeit. Wie man im Probenraum perfekt singt, aber auf der Bühne mit Audioequipment-Problemen kämpft.++### „Beim Refactoring gleich mit erledigen" ist Gift für die Abschlussbeurteilung++Claude Code zeigt ein häufiges Verhaltensmuster: Es beginnt mit dem Refactoring von Code, der Optimierung der Performance und der Verbesserung des Stils, bevor die Kernfunktionalität die Verifikation bestanden hat. Knuths Zitat, „Premature optimization is the root of all evil", bekommt im Agenten-Szenario eine neue Bedeutung — Refactoring verschiebt die Grenze zwischen verifiziertem und nicht verifiziertem Code und kann zuvor implizit korrekte Codepfade zerstören. Es ist, als würde man seine Multiple-Choice-Antworten für eine bessere Formatierung neu abschreiben, bevor man die Matheaufgabe beendet hat — nicht nur verschwendet es Zeit, man könnte sie auch noch falsch abschreiben.++### Systematischer Bias bei der Selbstevaluation++Anthropic entdeckte 2026 in seiner Forschung ein tieferes Fehlermuster: **Wenn ein Agent gebeten wird, seine eigene Arbeit zu evaluieren, liefert er systematisch zu positive Bewertungen — selbst wenn ein menschlicher Beobachter die Qualität als eindeutig mangelhaft betrachten würde.** Das ist, als würde man einen Studenten bitten, seine eigene Klausur zu benoten — er wird bei seinen eigenen Antworten immer besonders nachsichtig sein.++Dieses Problem ist besonders gravierend bei subjektiven Aufgaben (wie Design-Ästhetik) — ob ein „Layout exquisit" ist, ist eine Frage der Beurteilung, und der Agent neigt zuverlässig zu positiven Bewertungen. Selbst bei Aufgaben mit überprüfbaren Ergebnissen kann die Leistung des Agenten durch schlechtes Urteilsvermögen beeinträchtigt werden.++Die Lösung besteht nicht darin, den Agenten „objektiver" zu machen — dasselbe Modell, das generiert und evaluiert, begünstigt von Natur aus Nachsicht gegenüber sich selbst. **Die Lösung ist die Trennung von „Arbeiter" und „Prüfer".** Wie ein Student seine eigene Klausur nicht benoten sollte — man braucht einen unabhängigen Korrektor.++Ein unabhängiger evaluierender Agent, der speziell darauf abgestimmt ist, „pingelig" zu sein, ist weitaus effektiver, als den generierenden Agenten sich selbst evaluieren zu lassen. Experimentelle Daten von Anthropic:++| Architektur | Laufzeit | Kosten | Kernfunktionen funktionsfähig? |+|--------------|---------|------|------------------------|+| Einzelner Agent (ohne Harness) | 20 Min. | $9 | Nein (Spiel-Entitäten reagieren nicht auf Eingabe) |+| Drei Agenten (Planer + Generator + Evaluator) | 6 Stunden | $200 | Ja (Spiel ist vollständig spielbar) |++Dies ist exakt dasselbe Modell (Opus 4.5) mit exakt demselben Prompt („build a 2D retro game editor"). Der einzige Unterschied ist der Harness — vom „nackten Ausführen" zu „Planer entfaltet Anforderungen → Generator implementiert Feature für Feature → Evaluator führt tatsächliches Klick-Testing mit Playwright durch".++> Quelle: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## Wie man voreilige Abgaben verhindert++### 1. Abschlussbeurteilung externalisieren++Die Abschlussbeurteilung sollte nicht vom Agenten selbst vorgenommen werden. Der Harness muss unabhängig eine Terminierungsvalidierung durchführen, wobei Laufzeit-Signale als Eingabe dienen, nicht die Zuversicht des Agenten. Schreiben Sie dies klar in `CLAUDE.md`:++```+## Definition of Done+- Feature complete = end-to-end verification passed, not "code is written"+- Required verification levels:+ 1. Unit tests pass+ 2. Integration tests pass+ 3. End-to-end flow verification passes+- Do not proceed to level 2 if level 1 fails+- Do not proceed to level 3 if level 2 fails+```++### 2. Eine Drei-Schichten-Terminierungsvalidierung aufbauen++- **Schicht 1: Syntax und statische Analyse**. Geringste Kosten, wenigste Informationen, aber muss bestanden werden. Das ist die Mindestprüfung — man muss die Wörter erst einmal richtig schreiben, bevor wir uns etwas anderes ansehen.+- **Schicht 2: Laufzeitverhaltens-Verifikation**. Testausführung, App-Startup-Checks, Validierung kritischer Pfade. Dies ist der zentrale Beweis für die Fertigstellung. Es reicht nicht, es nur zu schreiben; es muss laufen.+- **Schicht 3: Systemebene-Bestätigung**. End-to-End-Testing, Integrationsvalidierung, Nutzer szenario-Simulation. Die letzte Verteidigungslinie gegen voreilige Meldungen. Es reicht nicht zu laufen; es muss korrekt laufen.++### 3. Gute „Rotstift-Korrekturen" für Agenten entwerfen++OpenAI hat während seiner Codex-Praxis ein besonders wirksames Muster eingeführt: **Fehlermeldungen für Agenten sollten Korrekturanweisungen enthalten**. Nicht nur ein großes rotes Kreuz wie ein fauler Korrektor ziehen; wie ein guter Lehrer an den Rand schreiben „So sollten Sie das ändern". Nicht `"Test failed"` verwenden, sondern `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` Dieses spezifische, umsetzbare Feedback ermöglicht dem Agenten, sich ohne menschliches Eingreifen selbst zu korrigieren.++### 4. Laufzeit-Signale erfassen++Wirksame Laufzeit-Signale umfassen:+- Ist die Anwendung erfolgreich gestartet und hat einen bereiten Zustand erreicht?+- Haben die Pfade der kritischen Funktionen zur Laufzeit erfolgreich ausgeführt?+- Waren Datenbank-Schreibvorgänge, Dateioperationen und andere Seiteneffekte korrekt?+- Wurden temporäre Ressourcen bereinigt?++## Fallbeispiel aus der Praxis++**Aufgabe**: Passwort-Zurücksetzen-Funktionalität für Benutzer implementieren. Umfasst Datenbankoperationen, E-Mail-Versand und API-Endpunkt-Änderungen.++**Voreiliger Abgabeweg**: Agent ändert Datenbankschema, schreibt API-Endpunkt, fügt E-Mail-Vorlage hinzu, führt Unit-Tests durch (bestanden) und meldet Fertigstellung. Das Klausurheft ist komplett ausgefüllt.++**Tatsächliche Punkteabzüge**: (1) End-to-End-Ablauf ungetestet — das tatsächliche Senden und Verifizieren des Zurücksetzungslinks wurde nie bestätigt. (2) Datenbankmigration scheiterte nach teilweiser Ausführung, was eine Schemainkonsistenz verursachte. (3) E-Mail-Service-Konfiguration fehlte in der Zielumgebung.++**Harness-Intervention**: Terminierungsvalidierung erzwungen — (1) Vollständige App starten, um die Erreichbarkeit des Reset-Endpunkts zu verifizieren; (2) Den vollständigen Reset-Flow ausführen; (3) Datenbankzustandskonsistenz verifizieren. Alle Defekte wurden innerhalb der Session gefunden, was 5-10x der Kosten für spätere Reparaturen einsparte. Der unabhängige Korrektor fand die echten Probleme.++## Wichtigste Erkenntnisse++- **Agenten sind systematisch über confident** — der Confidence-Calibration-Bias ist eine objektive Realität. Das Klausurheft ausgefüllt zu haben bedeutet nicht, dass man alles richtig gemacht hat.+- **Die Abschlussbeurteilung muss externalisiert werden** — der Harness verifiziert unabhängig; vertrauen Sie nicht den „Gefühlen" des Agenten. Studenten können ihre eigenen Klausuren nicht benoten.+- **Alle drei Validierungsschichten sind unerlässlich** — Syntax bestanden, Verhalten bestanden, System bestanden, Schicht für Schicht fortschreitend.+- **Fehlermeldungen sollten wie die Rotstift-Korrektur eines guten Lehrers sein** — spezifische Korrekturschritte enthalten, damit der Agent sich selbst korrigieren kann.+- **Kein Refactoring, bis die Kernfunktionalität verifiziert ist** — die Abschlussprioritäts-Einschränkung ist der Schlüssel zur Verhinderung vorzeitiger Optimierung.++## Weiterführende Literatur++- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — Beweist, dass moderne Deep Networks systematisch über confident sind+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — Die kritische Rolle von Laufzeit-Evidenz bei der Abschlussbeurteilung+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Voreilige Fertigstellungsmeldung ist einer der Haupt-Fehlmodi von Agenten+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — Klassisches Referenzwerk über Testmethoden-Hierarchien und deren Wirksamkeit++## Übungen++1. **Terminierungsvalidierungs-Funktion entwerfen**: Entwerfen Sie eine vollständige Terminierungsvalidierung für eine Aufgabe, die eine Datenbankmigration und API-Änderung umfasst. Listen Sie die erforderlichen Laufzeit-Signale und die Bestehens-/Durchfall-Kriterien für jedes Signal auf. Führen Sie es mit einer realen Aufgabe durch und dokumentieren Sie, welche verborgenen Probleme es findet.++2. **Calibration-Bias-Messung**: Wählen Sie 10 verschiedene Arten von Codierungsaufgaben und dokumentieren Sie die selbst berichtete Abschlusszuversicht des Agenten versus die tatsächliche Qualität des Abschlusses. Berechnen Sie den Bias-Wert und analysieren Sie seine Beziehung zur Aufgabenkomplexität.++3. **Mehrschichtige-Verteidigung-Experiment**: Führen Sie drei Konfigurationen mit demselben Aufgabensatz durch — (a) nur statische Analyse, (b) zusätzlich Unit-Testing, (c) vollständige Drei-Schichten-Validierung. Vergleichen Sie den Anteil voreiliger Fertigstellungsmeldungen und die Anzahl unentdeckter Defekte.diff --git a/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.mdnew file mode 100644index 0000000..449ee3a--- /dev/null+++ b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md@@ -0,0 +1,6 @@+# Electron-Architekturregeln++- Renderer-Code darf nicht direkt auf das Dateisystem zugreifen.+- Preload ist die einzige Brücke zwischen Renderer und Electron Main.+- Retrieval- und Indexierungslogik leben in Service-Modulen, nicht in UI-Komponenten.+- Logging sollte strukturiert sein und von Service-Grenzen ausgehen.diff --git a/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.tsnew file mode 100644index 0000000..2428416--- /dev/null+++ b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts@@ -0,0 +1,253 @@+/**+ * e2e-runner.ts+ *+ * A minimal E2E test harness. Defines test cases as user action sequences+ * (import doc -> index -> ask question -> verify citation). Simulates+ * running them and shows the difference between "unit tests pass" and+ * "full pipeline works".+ *+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface PipelineStep {+ name: string;+ unitTestPasses: boolean;+ // Simulated actual behavior in the pipeline+ actualBehavior: "works" | "fails" | "partial";+ failureReason?: string;+}++interface TestCase {+ name: string;+ steps: PipelineStep[];+}++interface TestResult {+ testCase: string;+ unitTestsPassed: number;+ unitTestsTotal: number;+ unitTestResult: "PASS" | "FAIL";+ e2eResult: "PASS" | "FAIL";+ e2eFailureStep?: string;+ e2eFailureReason?: string;+}++// ---------------------------------------------------------------------------+// Test cases -- realistic scenarios where unit tests pass but E2E fails+// ---------------------------------------------------------------------------++const testCases: TestCase[] = [+ {+ name: "Import document and ask question",+ steps: [+ {+ name: "Parse uploaded document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Store document chunks",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Index chunks for retrieval",+ unitTestPasses: true,+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions+ failureReason: "Embedding dimension mismatch between indexer and retriever",+ },+ {+ name: "Retrieve relevant chunks",+ unitTestPasses: true, // Unit test uses mock data with correct dimensions+ actualBehavior: "fails",+ failureReason: "Empty results due to dimension mismatch from previous step",+ },+ {+ name: "Generate answer with citations",+ unitTestPasses: true, // Unit test provides pre-retrieved chunks+ actualBehavior: "fails",+ failureReason: "No chunks retrieved, so answer has no citations",+ },+ ],+ },+ {+ name: "Delete document and verify removal",+ steps: [+ {+ name: "Find document by ID",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Delete document record",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Remove indexed chunks",+ unitTestPasses: true,+ actualBehavior: "fails", // Orphaned chunks remain in the index+ failureReason: "Index cleanup query timed out, chunks remain orphaned",+ },+ {+ name: "Verify document not in search results",+ unitTestPasses: true, // Unit test mocks the search+ actualBehavior: "fails",+ failureReason: "Orphaned chunks from previous step still appear in results",+ },+ ],+ },+ {+ name: "Multi-user concurrent access",+ steps: [+ {+ name: "User A imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User B imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User A queries their document",+ unitTestPasses: true,+ actualBehavior: "partial", // Cross-contamination of results+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",+ },+ {+ name: "Verify only User A's results returned",+ unitTestPasses: true,+ actualBehavior: "fails",+ failureReason: "Results include documents from other users",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Run tests+// ---------------------------------------------------------------------------++function runUnitTests(tc: TestCase): { passed: number; total: number } {+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;+ return { passed, total: tc.steps.length };+}++function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {+ // Pipeline: if any step actually fails, the whole E2E fails+ for (const step of tc.steps) {+ if (step.actualBehavior === "fails") {+ return {+ pass: false,+ failureStep: step.name,+ failureReason: step.failureReason ?? "Unknown failure",+ };+ }+ // "partial" means the step technically completes but creates problems downstream+ // We let it continue but track it+ }+ // Check if any step was "partial" (which may cause downstream issues)+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");+ if (partialSteps.length > 0) {+ // The partial steps may or may not cause overall failure+ // In our simulation, partial steps always lead to failure downstream+ // unless there's an explicit "fails" step that already caught it+ // This case means all steps were either "works" or "partial"+ return {+ pass: false,+ failureStep: partialSteps[partialSteps.length - 1].name,+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",+ };+ }++ return { pass: true };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(95));+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");+ console.log("=".repeat(95));++ const results: TestResult[] = testCases.map((tc) => {+ const unit = runUnitTests(tc);+ const e2e = runE2ETest(tc);++ return {+ testCase: tc.name,+ unitTestsPassed: unit.passed,+ unitTestsTotal: unit.total,+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",+ e2eResult: e2e.pass ? "PASS" : "FAIL",+ e2eFailureStep: e2e.failureStep,+ e2eFailureReason: e2e.failureReason,+ };+ });++ // Per-test-case detail+ for (let i = 0; i < testCases.length; i++) {+ const tc = testCases[i];+ const r = results[i];++ console.log("\n Test Case: " + tc.name);+ console.log(" " + "-".repeat(70));++ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;+ console.log(stepHeader);+ console.log(stepSep);++ for (const step of tc.steps) {+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";+ let e2eLabel: string;+ if (step.actualBehavior === "works") e2eLabel = "PASS";+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";+ else e2eLabel = "FAIL";++ const marker = step.actualBehavior !== "works" ? ">>" : " ";+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);+ }++ if (r.e2eFailureStep) {+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);+ console.log(` Reason: ${r.e2eFailureReason}`);+ }+ }++ // Summary comparison+ console.log("\n" + "=".repeat(95));+ console.log(" COMPARISON: Unit Tests vs E2E Tests");+ console.log("=".repeat(95) + "\n");++ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";++ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);+ }++ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");+}++run();diff --git a/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdnew file mode 100644index 0000000..2b6578e--- /dev/null+++ b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 10++Verwenden Sie diesen Ordner für Beispiele zu:++- Architekturbeschränkungen+- Strukturellen Tests+- Geschmacks-Invarianten (Taste Invariants)+- Remediation-orientierten Lint-Nachrichtendiff --git a/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdnew file mode 100644index 0000000..fb50247--- /dev/null+++ b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -0,0 +1,10 @@+# Beispiel: Review-Feedback in eine Regel umwandeln++Wiederholter Review-Kommentar:++> Verwende keine Dateisystem-Dienstprogramme aus dem Renderer. Nutze die Preload-Brücke.++Beförderte Harness-Regel:++- Eine Lint- oder Import-Regel hinzufügen, die `fs`-Verwendung in Renderer-Code verhindert+- Remediation-Text hinzufügen, der die Preload-Grenze erklärtdiff --git a/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdnew file mode 100644index 0000000..d8bc53c--- /dev/null+++ b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -0,0 +1,158 @@+[中文版本 →](../../../zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)++> Codebeispiele für diese Lektion: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)+> Praxisprojekt: [Project 05. Lassen Sie den Agenten seine eigene Arbeit überprüfen](./../../projects/project-05-grounded-qa-verification/index.md)++# Lektion 10. Nur End-to-End-Tests sind echte Verifikation++Sie bitten den Agenten, eine Datei-Export-Funktion zu einer Electron-App hinzuzufügen. Er schreibt die Render-Prozess-Komponente, das Preload-Skript und die Service-Layer-Logik. Die Unit-Tests für jede Komponente bestehen perfekt. Der Agent sagt: „Es ist fertig." Wenn Sie tatsächlich auf den Export-Button klicken — das Dateipfad-Format ist falsch, die Fortschrittsanzeige aktualisiert sich nicht und der Export großer Dateien verursacht einen Memory-Leak. Fünf Komponenten-Grenzfläche-Defekte, und die Unit-Tests haben keinen einzigen davon erkannt.++Es ist wie bei einer Chorprobe — jede Stimme klingt einzeln perfekt, aber wenn sie zusammen singen, sind die Soprane einen halben Takt schneller als die Bässe, und die Begleitung ist einen Halbton von der Hauptmelodie entfernt. Jede Stimme ist für sich „korrekt", aber das Ganze ist nicht harmonisch.++Googles Testing-Pyramid sagt uns: Eine große Anzahl von Unit-Tests ist das Fundament, aber wenn man dort stehen bleibt, wird man systematisch Komponenten-Interaktionsprobleme übersehen. Für KI-Coding-Agenten ist dieses Problem noch gravierender — Agenten neigen dazu, nur die schnellsten Tests auszuführen und dann die Fertigstellung zu melden. **Nur End-to-End-Testing kann beweisen, dass systemweite Defekte nicht existieren.**++## Die blinden Flecken von Unit-Tests++Die Entwurfsphilosophie von Unit-Tests ist Isolation — Abhängigkeiten werden gemockt und der Fokus liegt ausschließlich auf der zu testenden Einheit. Diese Philosophie macht Unit-Tests schnell und präzise, erzeugt aber auch systematische blinde Flecken. Es ist, als würde bei einer Chorprobe jede Stimme mit Kopfhörern proben — es klingt für sie gut, aber die Probleme tauchen erst auf, wenn sie zusammen kommen:++**Schnittstellen-Inkonsistenz**: Der vom Render-Prozess an das Preload-Skript übergebene Dateipfad ist ein relativer Pfad, aber das Preload-Skript erwartet einen absoluten Pfad. Ihre jeweiligen Unit-Tests haben beide Mocks verwendet und bestanden. Das Problem wird erst entdeckt, wenn der End-to-End-Flow ausgeführt wird — wie zwei Stimmen, die unabhängig voneinander proben und sich wohl fühlen, nur um beim Ensemble festzustellen, dass die eine im 4/4-Takt und die andere im 3/4-Takt singt.++**Zustandspropagationsfehler**: Eine Datenbankmigration ändert das Tabellenschema, aber die ORM-Cache-Schicht enthält noch Cache-Einträge für das alte Schema. Unit-Tests stellen jedes Mal eine völlig neue Mock-Umgebung bereit, was diese schichtenübergreifende Zustandsinkonsistenz nicht aufdeckt. Es ist, als würde man den Text eines Liedes ändern, aber jemand singt immer noch die alte Version.++**Ressourcen-Lebenszyklus-Probleme**: Die Beschaffung und Freigabe von Datei-Handles, Datenbankverbindungen und Netzwerk-Sockets erstreckt sich über mehrere Komponenten. Unit-Tests erstellen und zerstören für jeden Test unabhängige Ressourcen, was Ressourcenkonkurrenz oder Lecks nicht aufdeckt. Es ist, als würde bei der Probe jede Stimme abwechselnd die Mikrofone nutzen, aber wenn alle zusammen auf die Bühne gehen, gibt es nicht genug Mikros.++**Umgebungsabhängigkeit**: Der Code verhält sich in der Testumgebung korrekt (wo alles gemockt ist), scheitert aber in der realen Umgebung aufgrund von Konfigurationsunterschieden, Netzwerklatenz oder Dienstverfügbarkeit. Wie man im Probenraum perfekt singt, aber auf einem Festival im Freien mit Audio-Rückkopplung und Windeinfluss kämpft.++## End-to-End-Testing verändert nicht nur Ergebnisse, es verändert das Verhalten++Das ist etwas, das viele Menschen nicht erkennen: Wenn ein Agent weiß, dass seine Arbeit einem End-to-End-Test unterzogen wird, ändert sich sein Codierungsverhalten.++1. **Komponenten-Interaktionen berücksichtigen**: Beim Schreiben von Code wird er darüber nachdenken, „wie sich diese Schnittstelle mit Upstream verbindet", anstatt sich nur auf eine einzelne Funktion zu konzentrieren. Wie wenn man weiß, dass man schließlich zusammen singen wird — man achtet beim Üben auf die anderen Stimmen.+2. **Architektur-Grenzen respektieren**: In Systemen mit Architektur-Einschränkungen erzwingt End-to-End-Testing, dass der Agent die Grenzregeln einhält. Wie in einer Partitur, die mit „hier Crescendo" markiert ist — man muss sich daran halten.+3. **Fehlerpfade behandeln**: End-to-End-Tests umfassen in der Regel Fehler-Szenarien und zwingen den Agenten, die Ausnahmebehandlung zu berücksichtigen. Es ist, als würde man bei der Probe simulieren, „was wäre, wenn das Mikro plötzlich ausfällt", damit man weiß, was zu tun ist.++## Testing-Pyramid und Review-Feedback-Beförderung++```mermaid+flowchart TB+ subgraph Unit["Unit tests only check isolated parts"]+ U1["Renderer tests"]+ U2["Preload tests"]+ U3["Service tests"]+ end++ subgraph E2E["E2E runs through the real system"]+ R["Click renderer button"] --> P["Preload bridge"]+ P --> S["Service layer"]+ S --> F["File System / OS"]+ F --> Result["Actual exported file"]+ end+```++```mermaid+flowchart LR+ Review["Review feedback:<br/>renderer cannot import fs directly"] --> Rule["Add a direct fs import check"]+ Rule --> Message["Tell agent in error message<br/>to move file access to preload"]+ Message --> Harness["Add this check to harness"]+ Harness --> Stronger["Will fail immediately next time"]+```++In den Codex-Engineering-Praktiken betont OpenAI: **Fehlermeldungen für Agenten müssen Korrekturanweisungen enthalten.** Schreiben Sie nicht nur `"Direct filesystem access in renderer"`; schreiben Sie `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` Dies verwandelt Architekturregeln in eine automatische Korrekturschleife. Wie ein Chorleiter, der nicht nur sagt „das hast du falsch gesungen", sondern stattdessen sagt „du warst hier einen halben Takt zu schnell, hör auf den Rhythmus der Altstimmen und setze bei Takt 32 ein".++## Zentrale Konzepte++- **Komponenten-Grenzflächen-Defekte**: Komponente A und B bestehen jeweils ihre Unit-Tests, aber ihre Interaktion erzeugt fehlerhaftes Verhalten. Dies ist die Art von Problem, die End-to-End-Testing am besten erkennt — wie Chorstimmen, die einzeln korrekt sind, aber zusammen nicht harmonisch klingen.+- **Test-Angemessenheits-Gradient**: Von Unit-Tests erkannte Defekte <= von Integrationstests erkannte Defekte <= von End-to-End-Tests erkannte Defekte. Jede Schicht nach oben erhöht die Erkennungsfähigkeit.+- **Architektur-Grenz-Erzwingungsregeln**: Umwandlung von Regeln aus Architektur-Dokumenten (wie „Render-Prozess kann nicht direkt auf das Dateisystem zugreifen") in ausführbare, automatisierte Checks. Vom „auf Papier geschrieben" zum „laufend in CI".+- **Review-Feedback-Beförderung**: Umwandlung wiederholter Code-Review-Kommentare in automatisierte Tests. Jedes Mal, wenn ein wiederkehrendes Problem gefunden wird, eine Regel hinzufügen, und der Harness wird automatisch stärker. Wie ein Dirigent, der häufige Probenfehler in Aufwärmübungen verwandelt — beim nächsten Mal, wenn derselbe Fehler gemacht wird, deckt die Übung selbst ihn auf, ohne dass der Dirigent ein Wort sagen muss.+- **Agenten-orientierte Fehlermeldungen**: Fehlermeldungen sollten nicht nur „was schiefgelaufen ist" feststellen, sondern dem Agenten auch genau sagen, wie er es beheben kann. Dies verwandelt Testfehler in selbst-korrigierende Feedback-Schleifen.++## Vorgehen++### 0. Zuerst Architektur-Grenzen definieren, dann E2E-Tests schreiben++Voraussetzung für End-to-End-Testing sind klare Systemgrenzen. Wenn die Architektur ein Teller Spaghetti ist, wird End-to-End-Testing nur beweisen, dass „dieser Teller Spaghetti läuft", aber nicht aufzeigen, wo Design-Absichten verletzt wurden. Es ist wie ein Chor, der sich noch nicht einmal in Stimmen aufgeteilt hat — keine Menge an Probe wird gut klingen lassen.++OpenAIs Erfahrung: **Für von Agenten generierte Codebases müssen Architektur-Einschränkungen von Anfang an als frühe Voraussetzungen etabliert werden, nicht erst in Betracht gezogen werden, wenn das Team wächst.** Der Grund ist einfach — Agenten kopieren existierende Muster im Repository, selbst wenn diese Muster uneinheitlich oder suboptimal sind. Ohne Architektur-Einschränkungen wird der Agent in jeder Session weitere Abweichungen einführen.++OpenAI übernahm eine „Layered Domain Architecture" — jede Geschäftsdomäne ist in feste Schichten unterteilt: Types → Config → Repo → Service → Runtime → UI. Abhängigkeiten fließen streng vorwärts, und domänenübergreifende Belange treten über explizite Provider-Schnittstellen ein. Alle anderen Abhängigkeiten sind verboten und werden durch Custom-Linting mechanisch erzwungen.++Schlüsselprinzip: **Invarianten erzwingen, nicht Implementierung mikromanagen.** Zum Beispiel verlangen, dass „Daten an der Grenze geparst werden", aber nicht vorschreiben, welche Bibliothek verwendet werden soll. Fehlermeldungen müssen Korrekturanweisungen enthalten — nicht nur „Verletzung" sagen, sondern dem Agenten genau sagen, wie er es ändern soll.++> Quelle: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++### 1. Der Harness muss eine End-to-End-Schicht enthalten++Machen Sie es in Ihrem Validierungsflow explizit: Für Aufgaben mit komponentenübergreifenden Änderungen ist das Bestehen von End-to-End-Tests eine Voraussetzung für die Fertigstellung:++```+## Validation Hierarchy+- Level 1: Unit tests (Must pass)+- Level 2: Integration tests (Must pass)+- Level 3: End-to-end tests (Must pass when cross-component changes are involved)+- Skipping any required level = Not Complete+```++### 2. Architektur-Regeln in ausführbare Checks umwandeln++Jede Architektur-Einschränkung sollte einen entsprechenden Test oder eine Lint-Regel haben:++```bash+# Check if the render process directly calls Node.js APIs+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"+```++### 3. Agenten-orientierte Fehlermeldungen entwerfen++Fehlermeldungen sollten drei Elemente enthalten: was schiefgelaufen ist, warum, und wie man es behebt:++```+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12+WHY: Renderer process has no access to Node.js APIs for security+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()+```++### 4. Einen Review-Feedback-Beförderungsprozess etablieren++Jedes Mal, wenn eine neue Art von Agentenfehler beim Code-Review gefunden wird, wandeln Sie ihn in einen automatisierten Check um. Einen Monat später wird Ihr Harness deutlich stärker sein als zu Monatsbeginn. Es ist wie Probenotizen für einen Chor — Probleme aus jeder Probe aufzeichnen, damit sie vor der nächsten überprüft werden können. Im Laufe der Zeit nehmen häufige Fehler ab, und die Musik wird harmonischer.++## Fallbeispiel aus der Praxis++**Aufgabe**: Implementierung einer Datei-Export-Funktion in einer Electron-App. Umfasst Render-Prozess-UI, Preload-Skript-Dateisystem-Proxy und Service-Layer-Datentransformation.++**Stimmen einzeln singen (Unit-Tests bestanden)**: Render-Komponenten-Tests (bestanden, Dateioperationen gemockt), Preload-Skript-Tests (bestanden, Dateisystem gemockt), Service-Layer-Tests (bestanden, Datenquelle gemockt). Agent meldet Fertigstellung.++**Zusammen singen (Defekte durch End-to-End-Tests aufgedeckt)**:++| Defekt | Beschreibung | Unit-Test | E2E |+|--------|-------------|-----------|-----|+| Schnittstellen-Inkonsistenz | Inkonsistentes Dateipfad-Format | Verpasst | Gefunden |+| Zustandspropagation | Export-Fortschritt wird nicht über IPC an UI zurückgesendet | Verpasst | Gefunden |+| Ressourcen-Leak | Datei-Export-Handles großer Dateien nicht freigegeben | Verpasst | Gefunden |+| Berechtigungsproblem | Unterschiedliche Berechtigungen in der Paketumgebung | Verpasst | Gefunden |+| Fehlerpropagation | Service-Layer-Exceptions erreichten UI-Schicht nicht | Verpasst | Gefunden |++Alle 5 Defekte wurden von End-to-End-Tests gefunden, während Unit-Tests keinen einzigen entdeckten. Die Kosten waren ein Anstieg der Testzeit von 2 Sekunden auf 15 Sekunden — in einem Agenten-Workflow völlig akzeptabel. Egal wie gut jeder Teil einzeln singt, es kann nicht mit einer vollständigen Ensemble-Probe mithalten.++## Wichtigste Erkenntnisse++- **Unit-Tests sind systematisch blind für Komponenten-Grenzflächen-Defekte** — ihr Isolationsdesign ist genau das, was sie daran hindert, Interaktionsprobleme zu erkennen. Dass jeder richtig singt, bedeutet nicht, dass der Chor harmonisch klingt.+- **End-to-End-Testing erkennt nicht nur Defekte, es verändert das Codierungsverhalten des Agenten** — es lässt ihn mehr auf Integration und Grenzen fokussieren.+- **Architektur-Regeln müssen ausführbar sein** — nicht in einem Dokument geschrieben, das darauf wartet, gelesen zu werden, sondern automatisch bei jedem Commit überprüft.+- **Fehlermeldungen müssen für Agenten entworfen werden** — einschließlich spezifischer Schritte zur „Behebung", um eine selbst-korrigierende Schleife zu bilden.+- **Review-Feedback-Beförderung macht den Harness automatisch stärker** — jede Kategorie erfasster Defekte wird zu einer permanenten Verteidigungslinie.++## Weiterführende Literatur++- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — Die klassische Quelle des Testing-Pyramid-Modells+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Engineering-Praktiken für die automatisierte Ausführung von Architektur-Einschränkungen+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — Proaktives Injizieren von Fehlern zur Überprüfung der Systemresilienz+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — Property-Testing-Methodik, angesiedelt zwischen Beispiel-Testing und formaler Verifikation++## Übungen++1. **Komponentenübergreifende Defekterkennung**: Wählen Sie eine Änderungsaufgabe, die mindestens drei Komponenten umfasst. Führen Sie zuerst nur Unit-Tests durch und dokumentieren Sie die Ergebnisse, dann führen Sie End-to-End-Tests durch. Analysieren Sie, zu welcher Art von schichtenübergreifendem Interaktionsproblem jeder zusätzlich entdeckte Defekt gehört.++2. **Architektur-Regel-Automatisierung**: Wählen Sie eine Architektur-Einschränkung aus Ihrem Projekt und wandeln Sie sie in einen ausführbaren Check um (mit einer agenten-orientierten Fehlermeldung). Integrieren Sie ihn in den Harness und verifizieren Sie seine Wirksamkeit mit einer Baseline-Aufgabe.++3. **Review-Feedback-Beförderung**: Finden Sie einen wiederkehrenden Kommentar-Typ aus Ihrem Code-Review-Verlauf und wandeln Sie ihn in einen automatisierten Check im Fünf-Schritte-Prozess um. Vergleichen Sie die Häufigkeit des Problems vor und nach der Beförderung.diff --git a/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.mdnew file mode 100644index 0000000..567dae8--- /dev/null+++ b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md@@ -0,0 +1,8 @@+# Evaluator-Rubrik Beispiel++Verwenden Sie 1-5 Bewertung für jede Dimension:++- Fundierung: Sind die Antworten klar mit importierten Quellen verknüpft?+- Zitierqualität: Sind die Quellverweise sichtbar und spezifisch?+- Funktionalität: Kann der Benutzer den Frage-Antwort-Flow abschließen?+- Produktkohärenz: Fühlt sich der Workflow integriert an?diff --git a/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdnew file mode 100644index 0000000..110d617--- /dev/null+++ b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 11++Verwenden Sie diesen Ordner für Beispiele zu:++- Planner-Ausgaben+- Evaluator-Rubriken+- Generator/Evaluator-Schleifen+- Single-Agent- vs. Multi-Role-Vergleichendiff --git a/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsnew file mode 100644index 0000000..213dc19--- /dev/null+++ b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts@@ -0,0 +1,260 @@+/**+ * runtime-logger.ts+ *+ * A structured logging module demo. Shows ad-hoc console.log output vs+ * structured JSON log output when diagnosing a failure. Includes a seeded+ * failure scenario and demonstrates how structured logs pinpoint the issue+ * faster.+ *+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StructuredLogEntry {+ timestamp: string;+ level: "info" | "warn" | "error" | "debug";+ component: string;+ action: string;+ durationMs?: number;+ input?: unknown;+ output?: unknown;+ error?: string;+ correlationId: string;+}++// ---------------------------------------------------------------------------+// Simulated pipeline with a seeded failure+// ---------------------------------------------------------------------------++const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);++// Simulated stages of a document Q&A pipeline+interface PipelineStage {+ component: string;+ action: string;+ durationMs: number;+ success: boolean;+ errorMessage?: string;+ input?: unknown;+ output?: unknown;+}++function runPipeline(): PipelineStage[] {+ return [+ {+ component: "DocumentLoader",+ action: "parse_upload",+ durationMs: 45,+ success: true,+ input: { filename: "report.pdf", size: "2.3MB" },+ output: { chunks: 47 },+ },+ {+ component: "ChunkIndexer",+ action: "embed_and_store",+ durationMs: 230,+ success: true,+ input: { chunks: 47 },+ output: { indexed: 47, embeddingDim: 1536 },+ },+ {+ component: "QueryRouter",+ action: "route_query",+ durationMs: 12,+ success: true,+ input: { query: "What is the revenue target?" },+ output: { routedTo: "RetrievalEngine" },+ },+ {+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch+ component: "RetrievalEngine",+ action: "semantic_search",+ durationMs: 180,+ success: false,+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",+ input: { query: "What is the revenue target?", topK: 5 },+ output: { results: 0 },+ },+ {+ component: "AnswerGenerator",+ action: "generate_with_citations",+ durationMs: 1500,+ success: true, // Doesn't crash, but produces a bad answer+ input: { context: [], query: "What is the revenue target?" },+ output: { answer: "I could not find relevant information.", citations: 0 },+ },+ ];+}++// ---------------------------------------------------------------------------+// Ad-hoc logging (console.log style)+// ---------------------------------------------------------------------------++function printAdHocLog(stages: PipelineStage[]): void {+ console.log("Starting document Q&A pipeline...");+ console.log("User uploaded report.pdf");++ for (const stage of stages) {+ if (stage.success) {+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);+ } else {+ console.log(`${stage.component}: something went wrong`);+ }+ }++ console.log("Pipeline finished. Answer: I could not find relevant information.");+}++// ---------------------------------------------------------------------------+// Structured logging (JSON)+// ---------------------------------------------------------------------------++function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {+ const entries: StructuredLogEntry[] = [];++ for (const stage of stages) {+ entries.push({+ timestamp: new Date().toISOString(),+ level: stage.success ? "info" : "error",+ component: stage.component,+ action: stage.action,+ durationMs: stage.durationMs,+ input: stage.input,+ output: stage.output,+ error: stage.errorMessage,+ correlationId: CORRELATION_ID,+ });+ }++ return entries;+}++// ---------------------------------------------------------------------------+// Diagnose failure from structured logs+// ---------------------------------------------------------------------------++function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {+ const diagnosis: string[] = [];++ // Find errors+ const errors = entries.filter((e) => e.level === "error");+ if (errors.length > 0) {+ diagnosis.push("ERRORS FOUND:");+ for (const err of errors) {+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);+ }+ }++ // Check for latency spikes+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);+ if (slowStages.length > 0) {+ diagnosis.push("LATENCY SPIKES:");+ for (const s of slowStages) {+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);+ }+ }++ // Check for cascading failures+ const emptyOutputs = entries.filter((e) => {+ const out = e.output as Record<string, unknown> | undefined;+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;+ });+ if (emptyOutputs.length > 0) {+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");+ for (const e of emptyOutputs) {+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);+ }+ }++ return diagnosis;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const pipeline = runPipeline();++ console.log("\n" + "=".repeat(90));+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");+ console.log("=".repeat(90));++ // --- Ad-hoc output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO A: Ad-hoc console.log output");+ console.log("-".repeat(90) + "\n");+ printAdHocLog(pipeline);+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");+ console.log(" The failure message is vague: 'something went wrong'.");+ console.log(" No dimensions, no input/output data, no correlation ID.");++ // --- Structured output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO B: Structured JSON log output");+ console.log("-".repeat(90) + "\n");++ const structuredEntries = printStructuredLog(pipeline);++ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const entry of structuredEntries) {+ const hasError = entry.error ? entry.error.slice(0, 30) : "";+ const marker = entry.level === "error" ? ">>" : " ";+ console.log(+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`+ );+ }++ // --- Diagnosis ---+ console.log("\n" + "-".repeat(90));+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");+ console.log("-".repeat(90) + "\n");++ const errors = structuredEntries.filter((e) => e.level === "error");+ for (const err of errors) {+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);+ console.log(` Error: ${err.error}`);+ console.log(` Input: ${JSON.stringify(err.input)}`);+ console.log(` Output: ${JSON.stringify(err.output)}`);+ console.log(` Correlation ID: ${err.correlationId}`);+ }++ // Downstream impact+ console.log("\n DOWNSTREAM IMPACT:");+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");+ if (answerGen) {+ const out = answerGen.output as Record<string, unknown>;+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);+ }++ // Comparison summary+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON");+ console.log("=".repeat(90) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);++ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");+}++run();diff --git a/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.mdnew file mode 100644index 0000000..7e8afb9--- /dev/null+++ b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md@@ -0,0 +1,12 @@+# Sprint-Vertrag Beispiel++Sprint-Ziel:++- Sichtbare Zitate zu fundierten Q&A-Ergebnissen hinzufügen++"Fertig" bedeutet:++- Benutzer stellt eine Frage+- App gibt eine Antwort zurück+- Mindestens ein Zitat wird angezeigt+- Klicken auf ein Zitat öffnet die Quellposition in der Dokumentansichtdiff --git a/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdnew file mode 100644index 0000000..321ea27--- /dev/null+++ b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -0,0 +1,154 @@+[中文版本 →](../../../zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)+> Praxisprojekt: [Projekt 06. Vollständiger harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# Lektion 11. Die Runtime des Agenten beobachtbar machen++## Welches Problem löst diese Lektion?++Du bittest einen Agenten, ein Feature zu implementieren. Er läuft 20 Minuten, ändert viele Dateien und sagt dann: "fertig, aber zwei Tests schlagen fehl." Du fragst, warum sie fehlschlagen: "nicht sicher, vielleicht ein Timing-Problem." Du fragst, welche kritischen Pfade geändert wurden: "ich schaue in den Code..."++Das liegt nicht an fehlender Agentenfähigkeit. Dein harness stellt nicht genug Beobachtbarkeit bereit. **Ohne Beobachtbarkeit treffen Agenten Entscheidungen unter Unsicherheit, Bewertungen werden subjektiv, und retries werden blindes Herumprobieren.** OpenAI und Anthropic definieren Zuverlässigkeit als Evidenzproblem: Der harness muss Runtime-Verhalten und Bewertungssignale in einer Form offenlegen, die die nächste Entscheidung leitet.++## Zentrale Konzepte++- **Runtime-Beobachtbarkeit**: Systemsignale wie Logs, Traces, Prozessereignisse und Health Checks. Beantwortet "was hat das System getan".+- **Prozess-Beobachtbarkeit**: Sichtbarkeit in Entscheidungsartefakte des harness, etwa Pläne, Bewertungsrubriken und Akzeptanzkriterien. Beantwortet "warum sollte diese Änderung akzeptiert werden".+- **Task trace**: Vollständiger Entscheidungsweg vom Start bis zur Fertigstellung, analog zu Request-Tracing in verteilten Systemen.+- **Sprint contract**: Kurzfristige Vereinbarung vor dem Coding, die Scope, Verifikationsstandards und Ausschlüsse festlegt.+- **Evaluator-Rubrik**: Wandelt Qualitätsbewertung von subjektivem Urteil in evidenzbasierte strukturierte Bewertung um.+- **Geschichtete Beobachtbarkeit**: System- und Prozess-Beobachtbarkeit werden gemeinsam entworfen und verstärken sich gegenseitig.++## Geschichtete Beobachtbarkeit++```mermaid+flowchart LR+ Contract["Zuerst die Aufgabe festhalten<br/>was ändern / was nicht ändern / Bestehenskriterien"] --> Generator["Generator"]+ Generator --> Signals["App-Logs, Traces<br/>und Health Checks während der Ausführung sammeln"]+ Contract --> Review["Ergebnis Punkt für Punkt prüfen<br/>Verhalten / Tests / Grenzen"]+ Signals --> Review+ Review --> Verdict["Fehlgeschlagenen Check zeigen<br/>und wo zu fixen ist"]+ Verdict --> Generator+```++## Warum das passiert++### Die echten Kosten fehlender Beobachtbarkeit++Wenn einem harness Beobachtbarkeit fehlt, treten vier Problemtypen systematisch auf:++**"Korrekt" lässt sich nicht von "sieht korrekt aus" unterscheiden**: Eine Funktion kann im Code-Review perfekt wirken. Zur Laufzeit erzeugt aber ein Edge-Case-Fehler falsche Ergebnisse. Nur Runtime-Traces zeigen, dass der tatsächliche Ausführungspfad von der Erwartung abweicht.++**Bewertung wird Mystik**: Ohne Rubriken und Akzeptanzkriterien verlassen sich Evaluatoren, ob Mensch oder Agent, auf implizite Annahmen. Dieselbe Ausgabe kann stark unterschiedlich bewertet werden. Qualitätsbewertung wird nicht reproduzierbar.++**Retries werden blinde Vermutungen**: Wenn der Agent nicht weiß, warum etwas fehlschlägt, ist die Retry-Richtung zufällig. Er kann irrelevante Codepfade reparieren, während die eigentliche Ursache unberührt bleibt. Jeder blinde retry kostet Tokens und Zeit.++**Informationsklippe beim Handoff**: Wenn unvollständige Arbeit an die nächste Session übergeben wird, muss die neue Session ohne Beobachtbarkeit den Systemzustand von Grund auf diagnostizieren. Anthropic beobachtet, dass diese redundante Diagnose 30-50 % der Sessionzeit verbrauchen kann.++### Ein realistisches Claude-Code-Szenario++Stell dir einen harness mit planner-generator-evaluator-Workflow vor, der "Dark Mode zur App hinzufügen" ausführt.++**Ohne Beobachtbarkeit**: Der planner liefert eine vage Beschreibung. Der generator implementiert Dark Mode auf dieser Basis, trifft aber die impliziten Erwartungen nicht. Der evaluator lehnt nach eigenen impliziten Standards ab, kann aber nicht konkret sagen, was falsch ist. Der generator versucht blind erneut. Der Zyklus wiederholt sich 3-4 Mal, dauert etwa 45 Minuten und liefert ein kaum akzeptables Ergebnis.++**Mit vollständiger Beobachtbarkeit**: Der planner liefert einen sprint contract mit zu ändernden Komponenten, Verifikationsstandards und Ausschlüssen. Der generator implementiert gemäß Vertrag. Runtime-Beobachtbarkeit zeichnet das Laden und Anwenden der Styles jeder Komponente auf. Der evaluator bewertet Dimension für Dimension anhand einer Rubrik und konkreter Evidenz. Eine Iteration liefert ein hochwertiges Ergebnis in etwa 15 Minuten.++3x Effizienzunterschied. Die einzige Änderung ist Beobachtbarkeit.++### Warum Agenten das nicht selbst lösen können++Vielleicht denkst du: "Kann der Agent nicht einfach eigene Logs ausgeben?" Die Probleme sind:++1. Der Agent weiß nicht, was er nicht weiß; er zeichnet Signale nicht proaktiv auf, deren Bedarf er nicht erkennt.+2. Logformate sind inkonsistent; verschiedene Sessions nutzen unterschiedliche Formate, was systematische Analyse verhindert.+3. Prozess-Beobachtbarkeit lässt sich nicht mit Logs lösen; sprint contracts und Bewertungsrubriken sind strukturierte Artefakte auf harness-Ebene.++## Wie man es richtig macht++### 1. Runtime-Signalsammlung in den harness einbauen++Verlass dich nicht darauf, dass der Agent eigene Logs ausgibt. Der harness sollte diese Signale automatisch sammeln:++- **Anwendungslebenszyklus**: Startup, ready, running, shutdown+- **Featurepfad-Ausführung**: Kritische Pfade mit Einstiegspunkten, Checkpoints und Ausgängen+- **Datenfluss**: Datenbewegungen zwischen Komponenten+- **Ressourcennutzung**: Abnormale Muster, etwa stetig wachsender Speicher+- **Fehler und Ausnahmen**: Vollständiger Kontext, nicht nur Fehlermeldungen++### 2. Sprint contracts implementieren++Vor jeder Aufgabe verhandeln generator und evaluator, möglicherweise verschiedene Aufrufe desselben Agenten, einen Vertrag:++```markdown+# Sprint Contract: Dark Mode Support++## Scope+- Modify the theme toggle component+- Update global CSS variables+- Add dark mode tests++## Verification Standards+- Visual regression tests pass for each component+- Main flow end-to-end tests pass+- No flash of unstyled content (FOUC)++## Exclusions+- Not handling print styles+- Not handling third-party component dark mode+```++### 3. Eine Evaluator-Rubrik einführen++Mache aus "ist es gut oder nicht" eine quantifizierbare Bewertung:++```markdown+# Scoring Rubric++| Dimension | A | B | C | D |+|-----------|---|---|---|---|+| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |+| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |+| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |+```++### 4. Mit OpenTelemetry standardisieren++Erzeuge einen trace für jede harness-Session, einen span für jede Aufgabe und sub-spans für jeden Verifikationsschritt. Standardattribute annotieren wichtige Informationen. So integrieren sich Beobachtbarkeitsdaten in Tools wie Jaeger oder Zipkin.++## Praxisfall++Ein harness mit planner-generator-evaluator-Workflow führt "Dark Mode Support hinzufügen" aus:++**Nicht beobachtbare Version**: 3-4 blinde retry-Runden, 45 Minuten, kaum akzeptables Ergebnis. Der evaluator sagt "fühlt sich nicht richtig an", kann aber nicht konkret werden. Der generator verschwendet Zeit in falschen Richtungen.++**Voll beobachtbare Version**:+- Sprint contract klärt Scope, Standards und Ausschlüsse+- Runtime-Traces zeichnen das Laden der Styles jeder Komponente auf+- Bewertungsrubrik liefert strukturierte Bewertung pro Dimension+- Eine Iteration liefert hochwertige Ergebnisse in 15 Minuten++3x Effizienzgewinn, stabilere Qualität, reproduzierbare Bewertungen.++## Wichtigste Erkenntnisse++- **Beobachtbarkeit ist eine Architektur-Eigenschaft des harness**, keine nachträglich hinzugefügte Funktion.+- **Beide Beobachtbarkeitsschichten sind wesentlich**: Runtime-Signale erklären "was passiert ist", Prozessartefakte erklären "warum es so gemacht wurde".+- **Sprint contracts richten früh aus** und verhindern vorhersehbare Ablehnungen durch evaluator.+- **Rubriken machen Bewertung reproduzierbar**, sodass verschiedene Evaluatoren ähnliche Scores liefern.+- **Fehlende Beobachtbarkeit verschwendet 30-50 % der Sessionzeit für redundante Diagnose.**++## Weiterführende Literatur++- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — Theorie und Praxis moderner observability engineering+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — wegweisende Praxis in großskaligem Distributed Tracing+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Einführung von sprint contracts und evaluator rubrics+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — systematische Anwendung von Beobachtbarkeit in Produktionssystemen++## Übungen++1. **Observability-Gap-Analyse**: Prüfe deinen aktuellen harness auf System- und Prozess-Beobachtbarkeit. Finde Systemzustände, die mit bestehenden Signalen nicht unterscheidbar sind, und schlage Ergänzungen vor.++2. **Sprint-contract-Praxis**: Schreibe einen sprint contract für eine reale Aufgabe. Lass den Agenten danach arbeiten und vergleiche Effizienz und Qualität mit und ohne Vertrag.++3. **Task-trace-Konstruktion**: Zeichne jeden Schritt eines Agenten während einer vollständigen Coding-Aufgabe auf. Annotiere mit OpenTelemetry-Konventionen und analysiere Informationsengpässe.diff --git a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.mdnew file mode 100644index 0000000..8e0c184--- /dev/null+++ b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md@@ -0,0 +1,18 @@+# Benchmark-Vergleichsvorlage++Harness A:++- Abschlussrate+- Durchschnittliche Wiederholungen+- Vor menschlicher Review gefundene Bugs++Harness B:++- Abschlussrate+- Durchschnittliche Wiederholungen+- Vor menschlicher Review gefundene Bugs++Interpretation:++- Welches Harness hat das Ergebnis verändert?+- Welches Harness hat die Kosten für das Ergebnis verändert?diff --git a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.tsnew file mode 100644index 0000000..0388cad--- /dev/null+++ b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts@@ -0,0 +1,216 @@+/**+ * benchmark-runner.ts+ *+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),+ * "executes" each task, records timing and pass/fail, outputs a comparison+ * report showing which tasks pass and which fail.+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BenchmarkTask {+ id: string;+ name: string;+ category: string;+ passCriteria: string[];+ expectedDurationMs: number;+ // Simulated actual results+ actualDurationMs: number;+ actualPass: boolean;+ failureReason?: string;+}++interface BenchmarkResult {+ id: string;+ name: string;+ category: string;+ criteriaTotal: number;+ criteriaPassed: number;+ pass: boolean;+ expectedMs: number;+ actualMs: number;+ durationDelta: number;+ failureReason?: string;+}++// ---------------------------------------------------------------------------+// Benchmark task definitions+// ---------------------------------------------------------------------------++const benchmarkTasks: BenchmarkTask[] = [+ {+ id: "bench-001",+ name: "Import markdown document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 100,+ actualDurationMs: 95,+ actualPass: true,+ },+ {+ id: "bench-002",+ name: "Import PDF document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 200,+ actualDurationMs: 310,+ actualPass: false,+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",+ },+ {+ id: "bench-003",+ name: "Ask grounded question",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],+ expectedDurationMs: 500,+ actualDurationMs: 480,+ actualPass: true,+ },+ {+ id: "bench-004",+ name: "Ask question with no relevant docs",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],+ expectedDurationMs: 400,+ actualDurationMs: 420,+ actualPass: false,+ failureReason: "Model hallucinated a citation instead of saying 'no results'",+ },+ {+ id: "bench-005",+ name: "Delete imported document",+ category: "Document Pipeline",+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],+ expectedDurationMs: 150,+ actualDurationMs: 145,+ actualPass: true,+ },+ {+ id: "bench-006",+ name: "Concurrent user access",+ category: "Security",+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],+ expectedDurationMs: 300,+ actualDurationMs: 850,+ actualPass: false,+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",+ },+ {+ id: "bench-007",+ name: "Session continuity after restart",+ category: "Reliability",+ passCriteria: ["State persisted", "Session recovers", "No data loss"],+ expectedDurationMs: 200,+ actualDurationMs: 180,+ actualPass: true,+ },+ {+ id: "bench-008",+ name: "API rate limiting",+ category: "Security",+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],+ expectedDurationMs: 100,+ actualDurationMs: 100,+ actualPass: true,+ },+];++// ---------------------------------------------------------------------------+// Execution simulation+// ---------------------------------------------------------------------------++function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {+ return tasks.map((task) => ({+ id: task.id,+ name: task.name,+ category: task.category,+ criteriaTotal: task.passCriteria.length,+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),+ pass: task.actualPass,+ expectedMs: task.expectedDurationMs,+ actualMs: task.actualDurationMs,+ durationDelta: task.actualDurationMs - task.expectedDurationMs,+ failureReason: task.failureReason,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(100));+ console.log(" BENCHMARK RUNNER -- Task Execution Report");+ console.log("=".repeat(100));++ const results = executeBenchmark(benchmarkTasks);++ // Detailed results+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;+ console.log("\n" + header);+ console.log(sep);++ for (const r of results) {+ const passLabel = r.pass ? "PASS" : "FAIL";+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;+ const marker = r.pass ? " " : ">>";++ console.log(+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`+ );+ }++ // Failure details+ const failures = results.filter((r) => !r.pass);+ if (failures.length > 0) {+ console.log("\n" + "-".repeat(100));+ console.log(" FAILURE DETAILS");+ console.log("-".repeat(100));+ for (const f of failures) {+ console.log(`\n [${f.id}] ${f.name}`);+ console.log(` Category: ${f.category}`);+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);+ }+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SUMMARY BY CATEGORY");+ console.log("=".repeat(100) + "\n");++ const categories = [...new Set(results.map((r) => r.category))];+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;+ console.log(catHeader);+ console.log(catSep);++ for (const cat of categories) {+ const catResults = results.filter((r) => r.category === cat);+ const catPassed = catResults.filter((r) => r.pass).length;+ const catFailed = catResults.filter((r) => !r.pass).length;+ const rate = Math.round((catPassed / catResults.length) * 100);++ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);+ }++ // Overall+ const totalPassed = results.filter((r) => r.pass).length;+ const totalFailed = results.filter((r) => !r.pass).length;+ console.log("\n" + "-".repeat(100));+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);+ console.log("=".repeat(100) + "\n");+}++run();diff --git a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdnew file mode 100644index 0000000..3f940b1--- /dev/null+++ b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -0,0 +1,9 @@+# Aufräum-Schleife Beispiel++Wiederkehrende Aufräumaufgaben:++- Nach veralteten Dokumenten scannen+- Nach Strukturverletzungen scannen+- Qualitätsnoten aktualisieren+- Gezielte Aufräum-PRs öffnen+- Ein festes Benchmark-Slice nach dem Aufräumen erneut ausführendiff --git a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.tsnew file mode 100644index 0000000..6b35905--- /dev/null+++ b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts@@ -0,0 +1,336 @@+/**+ * cleanup-scanner.ts+ *+ * Scans a project directory for stale artifacts, dead code, structural+ * violations, and outputs a cleanup report. Helps enforce the "clean state+ * at end of every session" principle.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]+ * (defaults to current working directory)+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface ScanResult {+ category: string;+ check: string;+ severity: "critical" | "warning" | "info";+ found: string[];+ description: string;+}++// ---------------------------------------------------------------------------+// Scanner checks+// ---------------------------------------------------------------------------++interface ScannerCheck {+ category: string;+ name: string;+ severity: "critical" | "warning" | "info";+ description: string;+ scan: (dir: string) => string[];+}++function createChecks(): ScannerCheck[] {+ return [+ {+ category: "Stale Artifacts",+ name: "Temporary files (*.tmp, *.bak, *.swp)",+ severity: "warning",+ description: "Leftover temp files from editing or processing",+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),+ },+ {+ category: "Stale Artifacts",+ name: "Debug/log files in source",+ severity: "warning",+ description: "Log files that should not be in the source tree",+ scan: (dir) => {+ const found: string[] = [];+ const logPatterns = [".log"];+ for (const p of findFiles(dir, logPatterns)) {+ // Only flag log files in source directories+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {+ found.push(p);+ }+ }+ return found;+ },+ },+ {+ category: "Dead Code",+ name: "Unused imports (placeholder detection)",+ severity: "info",+ description: "Files that may contain unused code (heuristic scan)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app"];+ for (const srcDir of srcDirs) {+ const srcPath = path.join(dir, srcDir);+ if (fs.existsSync(srcPath)) {+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "Missing .gitignore",+ severity: "warning",+ description: "No .gitignore file found -- risk of committing build artifacts",+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],+ },+ {+ category: "Structural Violations",+ name: "Build artifacts in source",+ severity: "critical",+ description: "Compiled output (dist/, build/) mixed with source",+ scan: (dir) => {+ const found: string[] = [];+ // Check if dist/ or build/ exists inside src/+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];+ for (const d of dirs) {+ if (fs.existsSync(path.join(dir, d))) {+ found.push(d + "/");+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "node_modules in source tree",+ severity: "critical",+ description: "node_modules directory found outside root (nested dependency)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app", "test", "tests"];+ for (const srcDir of srcDirs) {+ const nmPath = path.join(dir, srcDir, "node_modules");+ if (fs.existsSync(nmPath)) {+ found.push(srcDir + "/node_modules/");+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Uncommitted changes indicator",+ severity: "info",+ description: "Checks for common artifacts of incomplete sessions",+ scan: (dir) => {+ const found: string[] = [];+ const indicators = [+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",+ "debug.ts", "test-manual.ts", "temp.ts",+ ];+ for (const f of indicators) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Empty directories",+ severity: "info",+ description: "Empty directories that may be leftover from incomplete work",+ scan: (dir) => {+ const found: string[] = [];+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];+ for (const d of commonDirs) {+ const dp = path.join(dir, d);+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {+ try {+ const contents = fs.readdirSync(dp);+ if (contents.length === 0) {+ found.push(d + "/");+ }+ } catch {+ // Skip directories we can't read+ }+ }+ }+ return found;+ },+ },+ {+ category: "Configuration",+ name: "Environment files in source",+ severity: "critical",+ description: ".env files that may contain secrets",+ scan: (dir) => {+ const found: string[] = [];+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];+ for (const f of envFiles) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ ];+}++// ---------------------------------------------------------------------------+// Helper functions+// ---------------------------------------------------------------------------++function findFiles(dir: string, extensions: string[]): string[] {+ const found: string[] = [];++ function walk(current: string, depth: number): void {+ if (depth > 4) return; // Limit recursion depth+ try {+ const entries = fs.readdirSync(current, { withFileTypes: true });+ for (const entry of entries) {+ // Skip common non-source directories+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {+ continue;+ }++ const fullPath = path.join(current, entry.name);+ const relativePath = path.relative(dir, fullPath);++ if (entry.isDirectory()) {+ walk(fullPath, depth + 1);+ } else if (entry.isFile()) {+ if (extensions.some((ext) => entry.name.endsWith(ext))) {+ found.push(relativePath);+ }+ }+ }+ } catch {+ // Skip directories we can't read+ }+ }++ walk(dir, 0);+ return found;+}++function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {+ try {+ const entries = fs.readdirSync(dir, { withFileTypes: true });+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);+ }+ continue;+ }++ const fullPath = path.join(dir, entry.name);+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {+ continue;+ }++ try {+ const content = fs.readFileSync(fullPath, "utf-8");+ const lines = content.split("\n");+ for (let i = 0; i < Math.min(lines.length, 50); i++) {+ for (const pattern of patterns) {+ if (lines[i].includes(pattern)) {+ const relative = path.relative(baseDir, fullPath);+ results.push(`${relative}:${i + 1} contains ${pattern}`);+ }+ }+ }+ } catch {+ // Skip files we can't read+ }+ }+ } catch {+ // Skip directories we can't read+ }+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");+ console.log("=".repeat(90));+ console.log(` Scanning: ${targetDir}\n`);++ const checks = createChecks();+ const results: ScanResult[] = [];++ for (const check of checks) {+ const found = check.scan(targetDir);+ results.push({+ category: check.category,+ check: check.name,+ severity: check.severity,+ found,+ description: check.description,+ });+ }++ // Report+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const count = r.found.length;+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";++ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);+ }++ // Summary+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);+ const clean = results.filter((r) => r.found.length === 0);++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SUMMARY");+ console.log("=".repeat(90) + "\n");++ console.log(` Critical issues: ${criticals.length}`);+ console.log(` Warnings: ${warnings.length}`);+ console.log(` Info items: ${infos.length}`);+ console.log(` Clean checks: ${clean.length}/${results.length}`);++ if (criticals.length > 0) {+ console.log("\n ACTION REQUIRED (Critical):");+ for (const c of criticals) {+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);+ console.log(` ${c.description}`);+ }+ }++ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);+ if (totalIssues === 0) {+ console.log("\n Project is in a clean state. No issues found.\n");+ } else {+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);+ }+}++run();diff --git a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdnew file mode 100644index 0000000..67281fd--- /dev/null+++ b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md@@ -0,0 +1,8 @@+# Code für Vorlesung 12++Verwenden Sie diesen Ordner für Beispiele zu:++- Benchmark-Slices+- Aufräumaufgaben+- Entropie-Reduktions-Beispielen+- Wiederholbaren Harness-Läufendiff --git a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdnew file mode 100644index 0000000..4b283d2--- /dev/null+++ b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -0,0 +1,184 @@+[中文版本 →](../../../zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)++> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)+> Praxisprojekt: [Project 06. Vollständiger Harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# Lektion 12. Sauberes Handoff am Ende jeder Session++Ihr Agent läuft den ganzen Nachmittag, ändert 20 Dateien, committet den Code, die Session endet. Die nächste Agenten-Session startet und stellt sofort fest: der Build ist kaputt, die Tests sind rot, temporäre Debug-Dateien sind überall, die Feature-Liste wurde nicht aktualisiert und der Fortschritt ist völlig unklar. Die neue Session verbringt ihre ersten 30 Minuten nur damit herauszufinden, „was die letzte Session eigentlich gemacht hat."++Sowohl OpenAI als auch Anthropic stellen klar: **Langfristige Zuverlässigkeit hängt von operativer Disziplin ab, nicht nur vom Erfolg einzelner Läufe.** Die Qualität des Zustands beim Session-Exit bestimmt direkt die Effizienz der nächsten Session. Betrachten Sie es wie Git-Best-Practices — jeder Commit sollte eine atomare, kompilierbare Änderung sein, kein Haufen halbfertigen Codes.++## Zentrale Konzepte++- **Clean state**: Das System erfüllt am Session-Ende fünf Bedingungen — Build bestanden, Tests bestanden, Fortschritt dokumentiert, keine veralteten Artefakte, Startup-Pfad verfügbar. Fehlt eine davon, ist die Session nicht „abgeschlossen".+- **Session-Integrität**: Analog zu Datenbanktransaktionen — entweder vollständig committen und einen sauberen Zustand hinterlassen oder auf den letzten konsistenten Zustand zurückrollen. Kein Mittelweg.+- **Qualitätsdokument**: Ein aktives Artefakt, das kontinuierlich Qualitätsbewertungen für jedes Modul aufzeichnet. Keine einmalige Bewertung, sondern ein Tracker, der zeigt, ob die Codebase im Laufe der Zeit stärker oder schwächer wird.+- **Cleanup-Schleife**: Eine regelmäßige Wartungssession, die darauf abzielt, die Entropie in der Codebase systematisch zu reduzieren. Keine Notfallreparatur, sondern routinemäßiger Betrieb.+- **Harness-Vereinfachung**: Wenn sich die Modellfähigkeiten verbessern, regelmäßig Harness-Komponenten entfernen, die nicht mehr notwendig sind. Eine Einschränkung, die heute essenziell ist, kann in drei Monaten unnötiger Overhead sein.+- **Idempotenter Cleanup**: Cleanup-Operationen liefern dasselbe Ergebnis, unabhängig davon, wie oft sie ausgeführt werden. Stellt sicher, dass Cleanup auch in Fehler-Wiederholungs-Szenarien sicher bleibt.++## Fünf Dimensionen des Clean State++```mermaid+flowchart LR+ Work["Feature work complete"] --> Build{"Build passes?"}+ Build -->|yes| Test{"Tests pass?"}+ Build -->|no| Fix["Fix before exit"]+ Test -->|yes| Record["Update feature list + progress"]+ Test -->|no| Fix+ Record --> Cleanup["Remove temp artifacts / debug code"]+ Cleanup --> Startup{"Standard startup path works?"}+ Startup -->|yes| Clean["Clean handoff"]+ Startup -->|no| Fix+ Fix --> Build+```++```mermaid+flowchart LR+ Dirty["Session ends with<br/>red tests / temp files / no progress update"] --> Diagnose["Next session first has to<br/>figure out what happened"]+ Diagnose --> Fragile["New work starts on a messy repo"]+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]+ More --> Dirty++ Clean["Session ends with<br/>green tests / updated progress / temp files removed"] --> Fast["Next session can start coding immediately"]+ Fast --> Stable["No need to rescue the repo first"]+ Stable --> Clean+```++## Warum das passiert++### Entropiewachstum ist der Standardzustand++Lehmans Gesetze der Software-Evolution sagen uns: Systeme, die kontinuierlichen Änderungen unterliegen, werden unausweichlich an Komplexität zunehmen, es sei denn, sie werden aktiv verwaltet. Dies gilt insbesondere für KI-Coding-Agenten — jede Session führt Änderungen ein, und ohne Cleanup beim Exit akkumuliert sich technische Schuld exponentiell.++Echte Daten sind aussagekräftig. Ein Projekt, das 12 Wochen lang mit Agenten entwickelt wurde, ohne Cleanup-Strategie:++- Woche 1: Build-Pass-Rate 100%, Test-Pass-Rate 100%, neue Session Startup 5 Min.+- Woche 4: Build 95%, Tests 92%, Startup 15 Min.+- Woche 8: Build 82%, Tests 78%, Startup 35 Min.+- Woche 12: Build 68%, Tests 61%, Startup 60+ Min.++Dasselbe Projekt mit einer Cleanup-Strategie:++- Woche 1: 100%, 100%, 5 Min.+- Woche 12: 97%, 95%, 9 Min.++Nach 12 Wochen: Die Build-Pass-Rate unterscheidet sich um 29 Prozentpunkte, die Startup-Zeit für neue Sessions um 85%. Das ist nicht theoretisch — es ist ein beobachteter Unterschied.++### Fünf Dimensionen des Clean State++Clean State bedeutet nicht nur „der Code kompiliert". Es sind fünf Dimensionen, die zusammen bewertet werden:++**Build-Dimension**: Lässt sich der Code fehlerfrei bauen? Das ist das Grundlegendste — die nächste Session sollte nicht zuerst Build-Fehler beheben müssen.++**Test-Dimension**: Bestehen alle Tests? Einschließlich der Tests, die vor der Session existierten — die Session ist dafür verantwortlich, bestehende Funktionalität nicht zu beschädigen. Und es sollte in CI verifiziert werden, nicht nur „funktioniert auf meinem Rechner".++**Fortschritts-Dimension**: Ist der aktuelle Fortschritt in einem maschinenlesbaren Artefakt dokumentiert? Abgeschlossene Teilaufgaben mit ihren Bestehenskriterien, in Bearbeitung befindliche aber unvollständige Teilaufgaben mit aktuellem Zustand, noch nicht gestartete Teilaufgaben. Gute Fortschrittsaufzeichnungen reduzieren 60-80% der Diagnosezeit beim Session-Startup.++**Artefakt-Dimension**: Gibt es veraltete oder mehrdeutige temporäre Artefakte? Debug-Logs, temporäre Dateien, auskommentierter Code, TODO-Marker — all diese erhöhen die kognitive Belastung für die nächste Session.++**Startup-Dimension**: Ist der Standard-Startup-Pfad verfügbar? Kann die nächste Session ohne manuelles Eingreifen mit der Arbeit beginnen? Umgebungsinitialisierung, Codebase-Laden, Kontextakquise, Aufgabenauswahl — diese Pfade dürfen nicht beschädigt sein.++### „Später aufräumen" bedeutet niemals aufräumen++Die häufigste mentale Falle ist „keine Zeit zum Aufräumen in dieser Session, das mache ich das nächste Mal." Aber die nächste Agenten-Session weiß nicht, was Sie hinterlassen haben — sie sieht ein Chaos aus Code und unsicherem Zustand. Sie wird erhebliche Zeit damit verbringen zu erschließen, „welche Teile dieses Codes beabsichtigt sind und welche temporär."++Schlimmer noch: Jede Session hat ihre eigenen Aufgabenziele. Die neue Session ist da, um neue Arbeit zu erledigen, nicht das Chaos der vorherigen Session aufzuräumen. Sie wird das Chaos ignorieren und neue Arbeit darauf aufbauen, was mehr Chaos über Chaos einführt. Das ist die positive Rückkopplungsschleife der Entropie.++## Wie man es richtig macht++### 1. Clean State als Abschlussvoraussetzung++Definieren Sie explizit im Harness: **Session-Abschluss = Aufgabe besteht die Verifikation UND Clean-State-Check besteht.** Fehlt eines von beiden, ist die Session nicht abgeschlossen. Schreiben Sie in CLAUDE.md:++```+## Session Exit Checklist+- [ ] Build passes (npm run build)+- [ ] All tests pass (npm test)+- [ ] Feature list updated+- [ ] No debug code remaining (console.log, debugger, TODO)+- [ ] Standard startup path available (npm run dev)+```++### 2. Zwei-Modi-Cleanup-Strategie++Kombinieren Sie zwei Cleanup-Modi:++**Sofortiger Cleanup (am Ende jeder Session)**: Temporäre Artefakte bereinigen, die während der Session erstellt wurden, Feature-Liste-Status aktualisieren, sicherstellen, dass Build und Tests bestehen. Das ist „Reference-Counting"-Cleanup.++**Periodischer Cleanup (wöchentlich)**: Vollständiger System-Scan — akkumulierte strukturelle Probleme behandeln, Qualitätsdokumente aktualisieren, Benchmark-Tests ausführen, um Drift zu erkennen. Das ist „Tracing"-Cleanup.++### 3. Ein Qualitätsdokument pflegen++Ein Qualitätsdokument ist ein aktives Artefakt, das jedes Modul kontinuierlich bewertet:++```markdown+# Quality Document++## User Authentication Module (Quality: A)+- Verification passing: Yes+- Agent understandable: Yes+- Test stability: Stable+- Architecture boundaries: Compliant+- Code conventions: Followed++## Payment Module (Quality: C)+- Verification passing: Partial (payment callback untested)+- Agent understandable: Difficult (logic spread across 3 files)+- Test stability: Unstable (2 flaky tests)+- Architecture boundaries: Violations present+- Code conventions: Partially followed+```++Neue Sessions lesen dieses Dokument und wissen sofort, wo Prioritäten gesetzt werden sollten. Das Modul mit der niedrigsten Bewertung zuerst reparieren.++### 4. Den Harness regelmäßig vereinfachen++Eine wichtige Erkenntnis von Anthropic: **Jede Harness-Komponente existiert, weil das Modell etwas nicht zuverlässig alleine kann. Aber wenn sich Modelle verbessern, veralten diese Annahmen.** Eine Einschränkung, die vor drei Monaten essenziell war, kann heute unnötiger Overhead sein.++Empfohlene Praxis: Jeden Monat eine Harness-Komponente auswählen, vorübergehend deaktivieren und Benchmark-Aufgaben ausführen. Wenn die Ergebnisse nicht schlechter werden, dauerhaft entfernen. Wenn doch, wiederherstellen oder durch eine leichtere Alternative ersetzen.++### 5. Cleanup-Operationen müssen idempotent sein++Cleanup-Skripte sollten sicher sein, wiederholt ausgeführt zu werden:++```bash+# Idempotent cleanup operations+rm -f /tmp/debug-*.log # -f ensures no error when files don't exist+git checkout -- .env.local # Restore to known state+npm run test # Verify cleanup didn't break anything+```++## Fallbeispiel aus der Praxis++Eine Electron-App, die über 12 Wochen mit Agenten entwickelt wurde, im Vergleich zweier Ansätze:++**Ohne Cleanup-Strategie** (Kontrollgruppe): Woche 12, Build-Pass-Rate 68%, Test-Pass-Rate 61%, neue Session Startup 60+ Min., veraltete Artefakte 103.++**Mit Cleanup-Strategie** (Versuchsgruppe): Vollständiger Clean-State-Check am Ende jeder Session + wöchentliche Cleanup-Schleife. Woche 12, Build-Pass-Rate 97%, Test-Pass-Rate 95%, neue Session Startup 9 Min., veraltete Artefakte 11.++In Woche 12 liegt die Build-Pass-Rate der Versuchsgruppe um 29 Prozentpunkte höher, die Test-Pass-Rate um 34 Punkte höher und die Startup-Zeit für neue Sessions um 85% niedriger.++## Wichtigste Erkenntnisse++- **Clean State ist eine notwendige Bedingung für den Session-Abschluss** — kein optionales Aufräumen, sondern Teil der „Definition of Done".+- **Alle fünf Dimensionen sind erforderlich** — Build, Tests, Fortschritt, Artefakte, Startup — jede muss explizit überprüft werden.+- **Qualitätsdokumente machen die Codebase-Gesundheit messbar** — man kann nur reparieren, von dem man weiß, dass es sich verschlechtert.+- **Den Harness regelmäßig vereinfachen** — wenn sich die Modellfähigkeiten verbessern, Einschränkungen entfernen, die nicht mehr benötigt werden.+- **„Später aufräumen" bedeutet niemals aufräumen** — Entropiewachstum ist der Standard; nur aktiver Cleanup wirkt dagegen.++## Weiterführende Literatur++- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — Systematische Prinzipien von Code-Sauberkeit+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Reproduzierbarkeit als Kernanforderung des Harness-Designs+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Die kritische Rolle sauberer Session-Exits für langfristige Zuverlässigkeit+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — Software-Evolutionsgesetze, die beweisen, dass Systemkomplexität ohne aktive Wartung unausweichlich wächst++## Übungen++1. **Clean-State-Checkliste**: Entwerfen Sie eine Session-Exit-Checkliste für Ihre Codebase, die alle fünf Dimensionen abdeckt. Wenden Sie sie über 5 aufeinanderfolgende Sessions an und dokumentieren Sie Verstöße pro Dimension.++2. **Benchmark-Vergleich**: Verwenden Sie einen festen Aufgabensatz mit zwei Harness-Varianten (mit/ohne Clean-State-Anforderungen). Vergleichen Sie Abschlussrate, Wiederholungsanzahl und Defekt-Escape-Rate.++3. **Harness-Vereinfachung üben**: Wählen Sie eine Harness-Komponente aus, deaktivieren Sie sie vorübergehend und führen Sie Benchmark-Aufgaben durch. Vergleichen Sie die Ergebnisse mit und ohne sie. Entscheiden Sie, ob Sie sie beibehalten, entfernen oder ersetzen.diff --git a/docs/de/projects/index.md b/docs/de/projects/index.mdnew file mode 100644index 0000000..23ec693--- /dev/null+++ b/docs/de/projects/index.md@@ -0,0 +1,23 @@+# Willkommen bei den Projekten++Dies ist der praktische Teil von Learn Harness Engineering. Die Lektionen zu lesen reicht nicht aus: Du musst die Umgebungen selbst bauen und beobachten, wie Codex, Claude Code oder andere KI-Agenten unter verschiedenen Regeln reagieren.++## Projektübersicht++Der Kurs enthält 6 aufeinander aufbauende Praxisprojekte, die zeigen, wie man eine zuverlässige agentische Arbeitsumgebung von Grund auf baut:++1. **Nur Prompt vs Regeln zuerst**: Vergleiche, wie ein Agent nur mit Prompt und mit einfachem harness arbeitet.+2. **Agent-lesbarer Workspace**: Lerne, ein Repository KI-freundlich zu strukturieren und Handoff-Mechanismen einzurichten.+3. **Kontinuität über Sessions**: Entwirf Zustandsdateien und Initialisierungsskripte, damit der Agent über Sessions hinweg nahtlos weiterarbeiten kann.+4. **Runtime-Feedback und Scope-Kontrolle**: Führe Werkzeuge ein, mit denen der Agent seinen eigenen Code testen und Fehler während der Ausführung korrigieren kann.+5. **Selbstverifikation und Rollentrennung**: Baue einen unabhängigen Review-Mechanismus, um Halluzinationen und zu frühe Erfolgsmeldungen zu vermeiden.+6. **Vollständiger harness (Capstone)**: Setze eine finale, beobachtbare, end-to-end agentische Arbeitsumgebung zusammen.++## Vorgehen++Jeder Projektordner enthält typischerweise:+- `starter/`: deinen Start-Workspace.+- `solution/`: eine Referenzimplementierung, falls du feststeckst.+- Aufgabenanweisungen mit Hintergrund und konkreten Zielen.++Nutze deinen bevorzugten AI Coding Agent, zum Beispiel Claude Code, Cursor oder Trae, um die Aufgaben im Verzeichnis `starter/` abzuschließen.diff --git a/docs/de/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/de/projects/project-01-baseline-vs-minimal-harness/index.mdnew file mode 100644index 0000000..b133f09--- /dev/null+++ b/docs/de/projects/project-01-baseline-vs-minimal-harness/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-01-baseline-vs-minimal-harness/)++> Zugehörige Lektionen: [Lektion 01. Starke Modelle bedeuten keine zuverlässige Ausführung](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [Lektion 02. Was harness wirklich bedeutet](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)+> Vorlagendateien: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/resources/templates/)++# Projekt 01. Nur Prompt vs Regeln zuerst: Wie groß ist der Unterschied?++## Was du tust++Baue das minimale Gerüst einer Electron-Wissensdatenbank-App: ein Fenster mit Dokumentliste links, Q&A-Panel rechts und lokalem Datenverzeichnis. Die Aufgabe selbst ist nicht komplex. Komplex ist, wie du den Agenten dazu bringst, sie zuverlässig abzuschließen.++Du führst sie zweimal aus. Beim ersten Mal: nur ein Prompt, keine Vorbereitung. Beim zweiten Mal: `AGENTS.md`, `init.sh` und `feature_list.json` liegen bereits im Repository. Danach vergleichst du.++Der Kern dieses Projekts ist nicht das Schreiben von Code, sondern herauszufinden, wie groß der Abstand zwischen "15 Minuten Regeln vorbereiten" und "den Agenten einfach loslaufen lassen" ist.++## Werkzeuge++- Claude Code oder Codex (wähle eines und nutze es für beide Läufe)+- Git (Branches verwalten und vergleichen)+- Node.js + Electron (Projektstack)+- Ein Timer (Dauer jedes Laufs erfassen)++## Harness-Mechanismus++Minimaler harness: `AGENTS.md` + `init.sh` + `feature_list.json`diff --git a/docs/de/projects/project-02-agent-readable-workspace/index.md b/docs/de/projects/project-02-agent-readable-workspace/index.mdnew file mode 100644index 0000000..87e3c40--- /dev/null+++ b/docs/de/projects/project-02-agent-readable-workspace/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-02-agent-readable-workspace/)++> Zugehörige Lektionen: [Lektion 03. Mache das Repository zur einzigen Quelle der Wahrheit](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [Lektion 04. Teile Anweisungen auf mehrere Dateien auf](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+> Vorlagendateien: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/resources/templates/)++# Projekt 02. Das Projekt lesbar machen und dort weiterarbeiten, wo du aufgehört hast++## Was du tust++Füge dem Repository "Lesbarkeit" hinzu, damit ein neuer Agent die Projektstruktur schnell versteht, den aktuellen Fortschritt kennt und Arbeit aufnehmen kann. Konkret: Implementiere Dokumentimport, Detailansicht und lokale Persistenz über zwei Sessions hinweg.++Du führst es zweimal aus: zuerst ohne Hilfe, dann mit bereits abgelegten `ARCHITECTURE.md`, `PRODUCT.md` und `session-handoff.md`.++## Werkzeuge++- Claude Code oder Codex+- Git+- Node.js + Electron++## Harness-Mechanismus++Agent-lesbarer Workspace + persistente Zustandsdateiendiff --git a/docs/de/projects/project-03-multi-session-continuity/index.md b/docs/de/projects/project-03-multi-session-continuity/index.mdnew file mode 100644index 0000000..4d7b153--- /dev/null+++ b/docs/de/projects/project-03-multi-session-continuity/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-03-multi-session-continuity/)++> Zugehörige Lektionen: [Lektion 05. Kontext über Sessions hinweg lebendig halten](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [Lektion 06. Vor jeder Agenten-Session initialisieren](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+> Vorlagendateien: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/resources/templates/)++# Projekt 03. Den Agenten über Session-Neustarts hinweg weiterarbeiten lassen++## Was du tust++Füge dem Agenten Scope-Kontrolle und Verifikationsgates hinzu. Implementiere Dokument-Chunking, Metadatenextraktion, Indexierungsfortschritt und einen Q&A-Flow mit Zitaten. Nutze `feature_list.json`, um Feature-Status zu verfolgen: ein Feature nach dem anderen, kein `pass` ohne Verifikationsnachweis.++Du führst es zweimal aus: zuerst ohne Einschränkungen, dann mit strikter Durchsetzung.++## Werkzeuge++- Claude Code oder Codex+- Git+- Node.js + Electron++## Harness-Mechanismus++Fortschrittslog + Session-Handoff + Multi-Session-Kontinuitätdiff --git a/docs/de/projects/project-04-incremental-indexing/index.md b/docs/de/projects/project-04-incremental-indexing/index.mdnew file mode 100644index 0000000..9489dbb--- /dev/null+++ b/docs/de/projects/project-04-incremental-indexing/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-04-incremental-indexing/)++> Zugehörige Lektionen: [Lektion 07. Klare Aufgabengrenzen für Agenten ziehen](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [Lektion 08. Feature-Listen nutzen, um Agentenarbeit zu begrenzen](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+> Vorlagendateien: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/resources/templates/)++# Projekt 04. Runtime-Feedback nutzen, um Agentenverhalten zu korrigieren++## Was du tust++Füge Runtime-Beobachtbarkeit hinzu, etwa Startlogs, Import-/Indexierungslogs und Fehlerzustände, sowie Architekturregeln, um Verstöße zwischen Schichten zu verhindern. Baue einen Runtime-Bug ein, den der Agent beheben soll.++Du führst es zweimal aus: zuerst ohne Logs oder Regeln, dann mit passenden Werkzeugen und Regeln.++## Werkzeuge++- Claude Code oder Codex+- Git+- Node.js + Electron++## Harness-Mechanismus++Runtime-Feedback + Scope-Kontrolle + inkrementelle Indexierungdiff --git a/docs/de/projects/project-05-grounded-qa-verification/index.md b/docs/de/projects/project-05-grounded-qa-verification/index.mdnew file mode 100644index 0000000..7b20e17--- /dev/null+++ b/docs/de/projects/project-05-grounded-qa-verification/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-05-grounded-qa-verification/)++> Zugehörige Lektionen: [Lektion 09. Agenten daran hindern, zu früh Erfolg zu melden](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [Lektion 10. Nur ein vollständiger Pipeline-Lauf zählt als echte Verifikation](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+> Vorlagendateien: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/resources/templates/)++# Projekt 05. Den Agenten seine eigene Arbeit verifizieren lassen++## Was du tust++Implementiere Rollentrennung: einen generator für die Umsetzung, einen evaluator für die Prüfung und optional einen planner. Führe drei Läufe durch, um den Effekt jeder zusätzlichen Rolle zu messen.++Wähle eine substanzielle Feature-Erweiterung, etwa Multi-Turn-Konversation, Neugestaltung des Zitat-Panels oder Dokumentfilterung, und halte sie über alle Läufe hinweg konstant.++## Werkzeuge++- Claude Code oder Codex+- Git+- Node.js + Electron++## Harness-Mechanismus++Selbstverifikation + begründete Q&A + evidenzbasierter Abschlussdiff --git a/docs/de/projects/project-06-runtime-observability-and-debugging/index.md b/docs/de/projects/project-06-runtime-observability-and-debugging/index.mdnew file mode 100644index 0000000..e59f71d--- /dev/null+++ b/docs/de/projects/project-06-runtime-observability-and-debugging/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-06-runtime-observability-and-debugging/)++> Zugehörige Lektionen: [Lektion 11. Die Runtime des Agenten beobachtbar machen](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [Lektion 12. Sauberes Handoff am Ende jeder Session](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+> Vorlagendateien: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/de/resources/templates/)++# Projekt 06. Einen vollständigen Agenten-harness bauen (Capstone)++## Was du tust++Dies ist das Abschlussprojekt. Setze alles zusammen, was du in den ersten fünf Projekten gelernt hast, führe einen vollständigen Benchmark aus und mache danach einen Cleanup-Pass, um zu prüfen, ob die Qualität wartbar bleibt.++Nutze ein festes Multi-Feature-Aufgabenset, das einen vollständigen Produktschnitt abdeckt: Dokumentimport, Indexierung, Q&A mit Zitaten, Runtime-Beobachtbarkeit und einen lesbaren, wiederaufnehmbaren Repository-Zustand. Führe zuerst einen schwachen harness-Baseline-Lauf aus, dann deinen stärksten harness, danach Cleanup und erneuten Lauf. Zum Schluss machst du ein harness-Ablationsexperiment: Entferne jeweils eine Komponente und beobachte, welche wirklich wichtig sind.++## Werkzeuge++- Claude Code oder Codex+- Git+- Node.js + Electron+- Vorlage für Qualitätsdokument+- Evaluator-Rubrik+- Alle harness-Komponenten aus den ersten fünf Projekten++## Harness-Mechanismus++Vollständiger harness: alle Mechanismen + Beobachtbarkeit + Ablationsstudiediff --git a/docs/de/resources/index.md b/docs/de/resources/index.mdnew file mode 100644index 0000000..9eb3b17--- /dev/null+++ b/docs/de/resources/index.md@@ -0,0 +1,50 @@+# Deutsche Ressourcenbibliothek++Dieser Ordner übersetzt die Kursmethoden in kopierfertige Vorlagen und kompakte Referenzen, die du in einem echten Repository verwenden kannst.++## Wann du sie nutzt++Beginne hier, wenn Codex, Claude Code oder ein anderer Coding-Agent über mehrere Sessions arbeiten soll, ohne Setup, Status und Scope ständig neu herzuleiten.++Besonders nützlich ist das, wenn:++- Arbeit über mehrere Sessions läuft+- viele Features vorhanden sind und leicht halb fertig bleiben+- Agenten zu früh Erfolg melden+- Startschritte jedes Mal neu gesucht werden++## Hier starten++Für eine minimale Einrichtung beginne mit:++- Root-Anweisungen: [`templates/AGENTS.md`](./templates/AGENTS.md) oder [`templates/CLAUDE.md`](./templates/CLAUDE.md)+- Feature-Zustand: [`templates/feature_list.json`](./templates/feature_list.json)+- Fortschrittslog: [`templates/claude-progress.md`](./templates/claude-progress.md)+- Bootstrap-Skriptreferenz: `docs/de/resources/templates/init.sh`++Ergänze danach:++- Session-Handoff: [`templates/session-handoff.md`](./templates/session-handoff.md)+- Clean-Exit-Checkliste: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)+- Evaluator-Rubrik: [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)++Wenn du die vollständigere OpenAI-artige Repository-Struktur aus dem "Harness engineering"-Beitrag möchtest, nutze das erweiterte Paket:++- [`openai-advanced/index.md`](./openai-advanced/index.md)++## Struktur der Bibliothek++- [`templates/`](./templates/index.md): Vorlagen zum Kopieren in ein echtes Repository+- [`reference/`](./reference/index.md): Methodennotizen, Startablauf und Karten von Fehlermodi+- [`openai-advanced/`](./openai-advanced/index.md): erweitertes Repository-Gerüst, system-of-record-Dokumente und agent-first Governance-Vorlagen++## Empfohlenes Minimalpaket++- `AGENTS.md` oder `CLAUDE.md`+- `feature_list.json`+- `claude-progress.md`+- `init.sh`++Diese vier Dateien reichen aus, um die meisten Agenten-Workflows deutlich stabiler zu machen.++Wenn das Repository zu einem länger laufenden System mit mehreren Domänen, aktiven Plänen, Qualitätsscores und Zuverlässigkeitsrichtlinien wächst, wechsle zum Paket [`openai-advanced/`](./openai-advanced/index.md), statt das Minimalpaket zu weit zu dehnen.diff --git a/docs/de/resources/openai-advanced/index.md b/docs/de/resources/openai-advanced/index.mdnew file mode 100644index 0000000..1ba7f63--- /dev/null+++ b/docs/de/resources/openai-advanced/index.md@@ -0,0 +1,83 @@+# OpenAI Advanced Pack++Dieser Ordner verpackt die stärker meinungsbasierte Repository-Struktur, die in+OpenAIs Artikel "Harness engineering: leveraging Codex in an agent-first world"+beschrieben wird, in kopierfertige Starterdateien.++Verwenden Sie dieses Pack, wenn das minimale Harness nicht mehr ausreicht und+Ihr Repository nun Folgendes benötigt:++- eine kurze, routing-artige `AGENTS.md`+- dauerhafte System-of-Record-Dokumentation innerhalb des Repos+- aktive und abgeschlossene Ausführungspläne+- explizite Produkt-, Zuverlässigkeits-, Sicherheits- und Frontend-Richtliniendateien+- Qualitätsbewertung nach Produktdomäne und Architektur-Schicht+- modellfreundliche Referenzmaterial-Ordner+- Standardarbeitsanweisungen (SOPs) für Architektur, Wissenserfassung und Laufzeitvalidierung++## Enthaltene Starter-Struktur++Das Starter-Pack unter [`repo-template/`](./repo-template/index.md) spiegelt die+folgende Struktur wider:++```text+AGENTS.md+ARCHITECTURE.md+docs/+├── design-docs/+│ ├── index.md+│ └── core-beliefs.md+├── exec-plans/+│ ├── active/+│ ├── completed/+│ └── tech-debt-tracker.md+├── generated/+│ └── db-schema.md+├── product-specs/+│ ├── index.md+│ └── new-user-onboarding.md+├── references/+│ ├── design-system-reference-llms.txt+│ ├── nixpacks-llms.txt+│ └── uv-llms.txt+├── DESIGN.md+├── FRONTEND.md+├── PLANS.md+├── PRODUCT_SENSE.md+├── QUALITY_SCORE.md+├── RELIABILITY.md+└── SECURITY.md+```++## Wie Sie es übernehmen++1. Beginnen Sie mit dem minimalen Pack, wenn Ihr Repo noch klein ist.+2. Kopieren Sie die Dateien aus [`repo-template/`](./repo-template/index.md) in+ Ihr eigenes Repository, sobald Sie eine stärkere Struktur benötigen.+3. Halten Sie `AGENTS.md` kurz. Behandeln Sie sie als Router zu den tieferen Docs,+ nicht als Enzyklopädie.+4. Aktualisieren Sie die Qualitäts-, Zuverlässigkeits- und Plan-Dokumente als+ Teil der normalen Arbeit, nicht an einem separaten Aufräumtag.+5. Halten Sie generierte Artefakte und externe Referenzen explizit, damit Agenten+ sie finden können, ohne sich auf Chat-Verlauf zu verlassen.++## SOP-Bibliothek++Der Ordner [`sops/`](./sops/index.md) wandelt die Diagramme des Artikels in+schrittweise Arbeitsanweisungen um:++- Einrichtung einer geschichteten Domänenarchitektur+- Codierung von unsichtbarem Wissen in das Repository+- lokaler Observability-Stack und Feedback-Schleifen-Workflow+- Chrome DevTools-Validierungsschleife für UI-Arbeit++## Design-Prinzipien++- Kurzer Einstiegspunkt, tiefer verlinkte Docs+- Repository als System of Record+- Mechanische Prüfungen schlagen erinnerte Regeln+- Pläne und Qualitätsverlauf leben neben dem Code+- Aufräumen und Vereinfachung sind Aufgaben erster Klasse++Dieses Pack ist bewusst meinungsbasiert, sollte aber an Ihr Projekt angepasst+werden, anstatt blind kopiert zu werden.diff --git a/docs/de/resources/openai-advanced/repo-template/AGENTS.md b/docs/de/resources/openai-advanced/repo-template/AGENTS.mdnew file mode 100644index 0000000..778ea19--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/AGENTS.md@@ -0,0 +1,57 @@+# AGENTS.md++Dieses Repository ist für langlaufende Coding-Agent-Arbeit optimiert. Halten Sie diese Datei+kurz. Verwenden Sie sie als Routing-Schicht zu den System-of-Record-Docs, nicht als+gigantische Instruktionsablage.++## Start-Workflow++Bevor Code geändert wird:++1. Das Repo-Root mit `pwd` bestätigen.+2. `ARCHITECTURE.md` für die aktuelle Systemübersicht und harten Abhängigkeitsregeln lesen.+3. `docs/QUALITY_SCORE.md` lesen, um zu sehen, welche Domänen oder Schichten am schwächsten sind.+4. `docs/PLANS.md` lesen, dann den aktiven Plan öffnen, an dem gearbeitet wird.+5. Die relevante Produktspezifikation in `docs/product-specs/` lesen.+6. Den Standard-Bootstrap- und Verifikationspfad für dieses Repo ausführen.+7. Wenn die Baseline-Verifikation fehlschlägt, die Baseline reparieren, bevor neuer Scope hinzugefügt wird.++## Routing-Map++- `ARCHITECTURE.md`: Domänen-Map, Schichtenmodell, Abhängigkeitsregeln+- `docs/design-docs/index.md`: Designentscheidungen und Kernüberzeugungen+- `docs/product-specs/index.md`: aktuelles Produktverhalten und Abnahmeziele+- `docs/PLANS.md`: Plan-Lebenszyklus und Ausführungsplan-Policy+- `docs/QUALITY_SCORE.md`: Produktdomänen- und Schichtengesundheit+- `docs/RELIABILITY.md`: Laufzeitsignale, Benchmarks und Neustart-Erwartungen+- `docs/SECURITY.md`: Secrets, Sandbox, Daten und externe Aktionsregeln+- `docs/FRONTEND.md`: UI-Einschränkungen, Designsystem-Regeln, Barrierefreiheits-Checks++## Arbeitsvertrag++- Von einem begrenzten Plan oder Feature-Slice gleichzeitig arbeiten.+- Arbeit nicht als fertig markieren nur aufgrund von Code-Inspektion; ausführbarer Nachweis ist erforderlich.+- Wenn Sie Verhalten ändern, die zugehörigen Produkt-, Plan- oder Zuverlässigkeitsdocs in derselben Session aktualisieren.+- Wenn Sie wiederholtes Review-Feedback sehen, es zu einer mechanischen Regel, einem Check oder Linter befördern, anstatt es im Chat erneut zu erklären.+- Generiertes Material in `docs/generated/` und Quellreferenzen in `docs/references/` aufbewahren.+- Kleine, aktuelle Docs hinzufügen anstatt diese Datei wachsen zu lassen.++## Definition of Done++Eine Änderung ist erst fertig, wenn all dies zutrifft:++- Zielverhalten ist implementiert+- Erforderliche Verifikation wurde tatsächlich ausgeführt+- Nachweis ist vom relevanten Plan- oder Qualitätsdokument verlinkt+- Betroffene Docs bleiben aktuell+- Das Repository kann sauber über den Standard-Startpfad neugestartet werden++## Session-Ende++Vor dem Beenden einer Session:++1. Den aktiven Ausführungsplan aktualisieren.+2. `docs/QUALITY_SCORE.md` aktualisieren, falls sich eine Domäne oder Schicht signifikant geändert hat.+3. Neue Schulden in `docs/exec-plans/tech-debt-tracker.md` dokumentieren, falls zurückgestellt.+4. Fertige Planks nach `docs/exec-plans/completed/` verschieben, wenn angemessen.+5. Das Repo in einem neustartfähigen Zustand mit klarer nächster Aktion hinterlassen.diff --git a/docs/de/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/de/resources/openai-advanced/repo-template/ARCHITECTURE.mdnew file mode 100644index 0000000..c65ad23--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -0,0 +1,57 @@+# ARCHITECTURE.md++Diese Datei ist die Top-Level-Übersicht des Systems. Sie sollte prägnant bleiben und+auf tiefere Dokumente verweisen, wenn nötig.++## Systemform++- Produkt: `[mit Produktnamen ersetzen]`+- Primärer Benutzer-Workflow: `[mit Hauptworkflow ersetzen]`+- Laufzeitoberflächen: `[Desktop / Web / CLI / Services / Worker]`+- Source of Truth für Produktverhalten: `docs/product-specs/`++## Domänen-Map++| Domäne | Zweck | Primäre Einstiegspunkte | Zugehörige Spec |+|--------|-------|------------------------|----------------|+| `[domäne-a]` | `[was sie besitzt]` | `[Module / Routen / Befehle]` | `[Spec-Pfad]` |+| `[domäne-b]` | `[was sie besitzt]` | `[Module / Routen / Befehle]` | `[Spec-Pfad]` |++## Schichtenmodell++Verwenden Sie ein festes gerichtetes Modell, damit Agenten keine ad-hoc-Architektur erfinden:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++Querschnittliche Belange sollten über explizite Provider- oder Adapter-Grenzen+eintreten, anstatt Schichten direkt zu überspringen.++## Harte Abhängigkeitsregeln++- Untere Schichten dürfen nicht von oberen Schichten abhängen.+- UI darf Runtime- oder Service-Verträge nicht umgehen.+- Datenzugriff muss über Repositories oder äquivalente Adapter erfolgen.+- Gemeinsame Utilities müssen generisch bleiben und dürfen keine Domänenlogik ansammeln.+- Neue Abhängigkeiten sollten im entsprechenden Plan oder Design-Doc begründet werden.++## Querschnittsschnittstellen++| Belang | Genehmigte Grenze | Notizen |+|--------|-------------------|---------|+| Logging und Tracing | `[Provider / Utility-Pfad]` | `[nur strukturiert, kein ad-hoc Console-Use]` |+| Auth | `[Provider-Pfad]` | `[Token/Session-Regeln]` |+| Externe APIs | `[Client oder Provider-Pfad]` | `[Rate-Limit / Retry-Guidance]` |+| Feature-Flags | `[Flag-Grenze]` | `[Ownership]`` |++## Aktuelle Hot Spots++- `[Bereich, der für Agenten am schwersten sicher zu ändern ist]`+- `[Bereich mit schwachen Grenzen oder fragilen Tests]`++## Änderungs-Checkliste++Wenn Sie architekturrelevanten Code berühren:++1. Diese Datei aktualisieren, falls sich die Domänen-Map oder erlaubten Grenzen geändert haben.+2. Das zugehörige Design-Doc in `docs/design-docs/` aktualisieren, falls sich die Begründung geändert hat.+3. Einen ausführbaren Check hinzufügen oder aktualisieren, falls die Regel mechanisch durchgesetzt werden soll.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/de/resources/openai-advanced/repo-template/docs/DESIGN.mdnew file mode 100644index 0000000..2a89971--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/DESIGN.md@@ -0,0 +1,28 @@+# DESIGN.md++Diese Datei ist der Design-Einstiegspunkt. Halten Sie sie kurz und verwenden Sie sie,+um zu den detaillierteren Dateien unter `docs/design-docs/` zu routen.++## Zweck++Dauerhafte Produkt- und Systemdesignentscheidungen dokumentieren, die einen einzelnen+Chat, Sprint oder die Erinnerung eines Reviewers überdauern sollten.++## Lesen Sie dies, wenn++- Sie die aktuelle Designphilosophie benötigen+- Sie dabei sind, ein neues Muster einzuführen+- Sie wissen müssen, welche Designentscheidungen endgültig sind und welche noch offen sind++## Kanonische Design-Dokumente++- `docs/design-docs/index.md`: Index der akzeptierten, vorgeschlagenen und veralteten Dokumente+- `docs/design-docs/core-beliefs.md`: projektweite Agenten-first-Überzeugungen++## Designregeln++- Halten Sie Design-Dokumente klein und aktuell.+- Bevorzugen Sie ein Dokument pro Entscheidungsbereich.+- Verknüpfen Sie Design-Dokumente aus Plänen und Spezifikationen, wenn eine Änderung von ihnen abhängt.+- Wenn eine Designregel operationell kritisch wird, zu einer automatisierten Prüfung+ befördern oder `ARCHITECTURE.md` aktualisieren.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/de/resources/openai-advanced/repo-template/docs/FRONTEND.mdnew file mode 100644index 0000000..441fe8c--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/FRONTEND.md@@ -0,0 +1,24 @@+# FRONTEND.md++Diese Datei definiert stabile Frontend-Erwartungen, damit Agenten nicht unvorhersehbar+UI-Muster erfinden.++## UI-Prinzipien++- Optimieren Sie auf Klarheit vor Neuheit.+- Halten Sie Interaktionsabläufe auffindbar und neustartbar.+- Bevorzugen Sie eine kleine Anzahl wiederverwendbarer Komponenten gegenüber einmaligen Varianten.+- Barrierefreiheitsprüfungen sind Teil der normalen Verifikation, keine Polierarbeit.++## Leitplanken++- Dokumentieren Sie das Design-System oder die Komponentenbibliothek in `docs/references/`.+- Erfassen Sie wichtige benutzerseitige Zustände: leer, laden, Erfolg, Fehler, erneut versuchen.+- Halten Sie Text, Tastaturverhalten und visuelle Hierarchie über alle Abläufe hinweg konsistent.+- Wenn ein UI-Fehler behoben wird, den zugehörigen Validierungsschritt hinzufügen oder aktualisieren.++## Verifikationserwartungen++- Beweise für kritische Benutzer-Journeys erfassen.+- Browser- oder Laufzeit-Validierungsschritte im entsprechenden Plan dokumentieren.+- Wenn visuelle Regressionen häufig auftreten, Screenshot- oder DOM-Prüfungen standardisieren.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/de/resources/openai-advanced/repo-template/docs/PLANS.mdnew file mode 100644index 0000000..d87dedf--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/PLANS.md@@ -0,0 +1,37 @@+# PLANS.md++Diese Datei definiert, wie Ausführungspläne erstellt, aktualisiert, abgeschlossen+und archiviert werden.++## Wann ein Plan erforderlich ist++Erstellen Sie einen Ausführungsplan, wenn die Arbeit:++- mehr als eine Sitzung umfasst+- mehr als ein Subsystem verändert+- nicht-triviale Verifikations- oder Rollout-Risiken birgt+- von offenen Entscheidungen abhängt, die dokumentiert werden sollten++## Plan-Speicherorte++- `docs/exec-plans/active/`: Pläne, die aktuell die Arbeit steuern+- `docs/exec-plans/completed/`: abgeschlossene Pläne, die für zukünftigen Agenten-Kontext behalten werden+- `docs/exec-plans/tech-debt-tracker.md`: aufgeschobene Arbeit und Folgeaufgaben++## Mindest-Abschnitte eines Plans++- Zielsetzung+- Umfang und Nicht-Umfang+- Verifikationspfad+- Risiken und Blocker+- Fortschrittslog+- Offene Entscheidungen++## Betriebsregeln++- Ein aktiver Plan sollte einen klar verantwortlichen aktuellen Schritt haben.+- Den Plan aktualisieren, während die Arbeit voranschreitet; nicht als statischen+ Text behandeln.+- Wenn eine Entscheidung die Implementierungsrichtung ändert, im Plan dokumentieren.+- Abgeschlossene Pläne nach `completed/` verschieben, damit Agenten den bisherigen+ Kontext weiterhin finden können.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/de/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.mdnew file mode 100644index 0000000..20f410f--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md@@ -0,0 +1,26 @@+# PRODUCT_SENSE.md++Diese Datei erfasst dauerhaftes Produkturteil, das Agenten nicht zuverlässig nur+aus dem Code ableiten können.++## Produktkern++- Hauptbenutzer: `[ersetzen]`+- Zu erledigende Aufgabe: `[ersetzen]`+- Hauptfrustration, die behoben werden soll: `[ersetzen]`+- Qualitätsmaßstab für Akzeptanz: `[ersetzen]`++## Produktregeln++- Bevorzugen Sie für den Benutzer sichtbare Zuverlässigkeit gegenüber Feature-Anzahl.+- Behandeln Sie mehrdeutiges Verhalten als Spezifikationslücke, nicht als Erlaubnis zum Raten.+- Wenn die Implementierung ändert, was Benutzer sehen oder vertrauen, aktualisieren Sie die zugehörige Spezifikation.+- Verwenden Sie Produktspezifikationen für konkrete Abläufe und diese Datei für+ produktübergreifende Prioritäten.++## No-Go-Muster++- Versteckte destruktive Aktionen+- Stilles Scheitern ohne Benutzer-Feedback+- Unklare Wahrheitsquelle für sichtbaren Zustand+- Features, die nicht in einem Satz erklärt werden könnendiff --git a/docs/de/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/de/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.mdnew file mode 100644index 0000000..d6c6609--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md@@ -0,0 +1,39 @@+# QUALITY_SCORE.md++Dieses Dokument verfolgt, ob das Repository mit der Zeit stärker oder schwächer wird.++## Bewertungsskala++- `A`: verifiziert, lesbar, stabil, Grenzen durchgesetzt+- `B`: funktionsfähig mit kleinen Lücken+- `C`: teilweise funktionsfähig, merkliche Verwirrung oder Instabilität+- `D`: kaputt, unsicher oder strukturell unklar++## Produktdomänen++| Domäne | Note | Verifikation | Agenten-Lesbarkeit | Teststabilität | Wesentliche Lücken | Zuletzt aktualisiert |+|--------|------|-------------|-------------------|---------------|-------------------|---------------------|+| `[domäne-a]` | - | - | - | - | - | - |+| `[domäne-b]` | - | - | - | - | - | - |+| `[domäne-c]` | - | - | - | - | - | - |++## Architektur-Schichten++| Schicht | Note | Grenzdurchsetzung | Agenten-Lesbarkeit | Wesentliche Lücken | Zuletzt aktualisiert |+|---------|------|-------------------|-------------------|-------------------|---------------------|+| Types | - | - | - | - | - |+| Services | - | - | - | - | - |+| Runtime | - | - | - | - | - |+| UI | - | - | - | - | - |++## Benchmark-Momentaufnahmen++| Datum | Harness-Variante | Abschlussrate | Wiederholungen | Fehler vor Review | Notizen |+|-------|-----------------|--------------|---------------|-------------------|---------|+| YYYY-MM-DD | `[Baseline / verbessert / vereinfacht]` | - | - | - | - |++## Vereinfachungsprotokoll++| Datum | Entfernte Komponente | Ergebnis | Entscheidung |+|-------|---------------------|----------|-------------|+| YYYY-MM-DD | `[Komponente]` | `[verschlechtert / unverändert]` | `[wiederherstellen / entfernt behalten]` |diff --git a/docs/de/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/de/resources/openai-advanced/repo-template/docs/RELIABILITY.mdnew file mode 100644index 0000000..42de6e1--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/RELIABILITY.md@@ -0,0 +1,33 @@+# RELIABILITY.md++Diese Datei definiert, wie das System beweist, dass es gesund und neu startbar ist.++## Standardpfade++- Bootstrap: `[Befehl]`+- Verifikation: `[Befehl]`+- App oder Dienst starten: `[Befehl]`+- Debugging oder Laufzeit-Inspektion: `[Befehl]`++## Erforderliche Laufzeitsignale++- strukturierte Logs für Start und kritische Abläufe+- Health-Checks für wichtige Dienste+- Trace- oder Timing-Daten für langsame Pfade, wenn verfügbar+- für den Benutzer sichtbare Fehlerzustände bei behebbaren Ausfällen++## Golden Journeys++- `[Journey 1]`+- `[Journey 2]`+- `[Journey 3]`++Jede Golden Journey sollte einen wiederholbaren Verifikationspfad und klare+Fehlersignale haben.++## Zuverlässigkeitsregeln++- Kein Feature ist vollständig, wenn das System danach nicht sauber neu starten kann.+- Laufzeitfehler sollten aus repo-lokalen Signalen diagnostizierbar sein.+- Wenn ein wiederholtes Fehlermuster auftritt, einen Benchmark oder eine Leitplanke dafür hinzufügen.+- Aufräumen ist Teil der Zuverlässigkeit, keine separate concern.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/de/resources/openai-advanced/repo-template/docs/SECURITY.mdnew file mode 100644index 0000000..c9ca4ba--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/SECURITY.md@@ -0,0 +1,28 @@+# SECURITY.md++Diese Datei definiert die Sicherheits- und Sicherheitsregeln, bei denen Agenten nicht+raten dürfen.++## Geheimnisse und Anmeldeinformationen++- Niemals Geheimnisse in Quellcode oder Dokumentation hardcoden.+- Zugelassene Pfade zum Laden von Geheimnissen hier dokumentieren.+- Tokens, API-Schlüssel und personenbezogene Daten aus Logs und Screenshots schwärzen.++## Nicht vertrauenswürdige Eingaben++- Externe Inhalte als nicht vertrauenswürdig behandeln, bis sie validiert sind.+- Zulässige Fetch- oder Ausführungsgrenzen hier dokumentieren.+- Wenn ein Risiko für Prompt-Injection oder Befehlsinjektion besteht, die Leitplanke dokumentieren.++## Externe Aktionen++- Auflisten, welche Aktionen eine explizite Genehmigung erfordern.+- Produktions- oder destruktive Befehle dokumentieren, die Agenten standardmäßig nicht ausführen dürfen.+- Sandbox-sichere Workflows für Debugging und Verifikation bevorzugen.++## Abhängigkeits- und Review-Regeln++- Neue Abhängigkeiten benötigen eine Begründung im aktiven Plan.+- Sicherheitsempfindliche Änderungen erfordern explizite Verifikationsschritte.+- Wiederholte Security-Review-Kommentare sollten zu Prüfungen werden, nicht zu implizitem Wissen.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/de/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.mdnew file mode 100644index 0000000..8491f16--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md@@ -0,0 +1,10 @@+# Grundüberzeugungen++- Das Repository ist das System of Record für Agenten.+- `AGENTS.md` ist ein Router, keine Enzyklopädie.+- Verifikationsnachweise sind wichtiger als Selbstvertrauen.+- Eine begrenzte Aufgabe ist besser als viele halbfertige Aufgaben.+- Wiederholtes menschliches Feedback sollte zu wiederverwendbaren Harness-Regeln werden.+- Aufräumen und Vereinfachung sind Teil des Auslieferns, keine Nachgedanken.+- Wenn ein Agent eine Tatsache nicht im Repo finden kann, behandeln Sie diese+ Tatsache als operationell nicht verfügbar.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/de/resources/openai-advanced/repo-template/docs/design-docs/index.mdnew file mode 100644index 0000000..a8d653e--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/design-docs/index.md@@ -0,0 +1,21 @@+# Design-Dokumente Index++Verwenden Sie diesen Index als auffindbare Karte der Design-Historie.++## Akzeptiert++- `core-beliefs.md`: Agenten-first-Betriebsüberzeugungen und dauerhafte Projektnormen++## Vorgeschlagen++- `[neue Design-Dokument-Pfade hier einfügen]`++## Veraltet++- `[alte oder ersetzte Design-Dokumente hier mit Ersetzungslinks verschieben]`++## Wartungsregeln++- Jedes Design-Dokument sollte einen Eigentümer oder einen Auslöser für Aktualisierungen haben.+- Veraltete Dokumente entfernen oder als veraltet markieren, anstatt sie abdriften zu lassen.+- Aktive Ausführungspläne mit den Design-Dokumenten verknüpfen, von denen sie abhängen.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/active/index.mdnew file mode 100644index 0000000..0b0bb1b--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md@@ -0,0 +1,10 @@+# Aktive Pläne++Bewahren Sie eine Markdown-Datei pro aktivem Ausführungsplan in diesem Ordner auf.++Vorgeschlagenes Dateinamenmuster:++- `YYYY-MM-DD-kurzes-thema.md`++Jeder aktive Plan sollte aktuell genug sein, damit eine neue Agenten-Sitzung die+Arbeit allein aus dem Repository fortsetzen kann.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.mdnew file mode 100644index 0000000..4fa9e5c--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md@@ -0,0 +1,5 @@+# Abgeschlossene Pläne++Verschieben Sie fertige Pläne hierher, anstatt sie zu löschen. Abgeschlossene Pläne+sind Teil der Repository-Gedächtnisoberfläche und helfen späteren Agenten-Sitzungen+zu verstehen, warum der Code so aussieht, wie er aussieht.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.mdnew file mode 100644index 0000000..56b72ec--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md@@ -0,0 +1,8 @@+# Tech-Schulden-Tracker++Verwenden Sie diese Datei für Schulden, die real sind, anerkannt sind und bewusst+aufgeschoben wurden.++| Datum | Bereich | Schuld | Warum aufgeschoben | Risiko | Nächster Auslöser |+|-------|---------|--------|-------------------|--------|------------------|+| YYYY-MM-DD | `[Bereich]` | `[Schuld]` | `[Grund]` | `[Risiko]` | `[wann erneut prüfen]` |diff --git a/docs/de/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/de/resources/openai-advanced/repo-template/docs/generated/db-schema.mdnew file mode 100644index 0000000..0f30b5e--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/generated/db-schema.md@@ -0,0 +1,14 @@+# Datenbankschema++Verwenden Sie diesen Ordner für generierte oder abgeleitete Artefakte, die Agenten+inspizieren können sollten, ohne sie aus dem Code rekonstruieren zu müssen.++## Quelle++- Generiert aus: `[Befehl oder Quellpfad]`+- Zuletzt aktualisiert: `YYYY-MM-DD`++## Hinweise++- Generierte Abschnitte nicht manuell bearbeiten.+- Diese Datei neu generieren, wenn sich das zugrunde liegende Schema ändert.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/de/resources/openai-advanced/repo-template/docs/product-specs/index.mdnew file mode 100644index 0000000..7f63822--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/product-specs/index.md@@ -0,0 +1,15 @@+# Produktspezifikationen Index++Verwenden Sie diesen Ordner für aktuelle benutzerseitige Verhaltensspezifikationen.++## Aktive Spezifikationen++- `new-user-onboarding.md`++## Regeln++- Spezifikationen sollten benutzerseitiges Verhalten und Akzeptanzkriterien beschreiben.+- Wenn die Implementierung von der Spezifikation abweicht, aktualisieren Sie eine von+ beiden in derselben Sitzung.+- Halten Sie diesen Index aktuell, damit ein neuer Agent den Produktumfang schnell+ erfassen kann.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/de/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.mdnew file mode 100644index 0000000..1797764--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md@@ -0,0 +1,26 @@+# Onboarding neuer Benutzer++## Ziel++Beschreiben Sie das Erlebnis bei der ersten Ausführung, das ein neuer Benutzer haben sollte.++## Startbedingungen++- `[Zustand bevor der Ablauf beginnt]`++## Benutzerablauf++1. `[Schritt eins]`+2. `[Schritt zwei]`+3. `[Schritt drei]`++## Akzeptanzkriterien++- `[beobachtbares Ergebnis]`+- `[beobachtbares Ergebnis]`+- `[beobachtbares Ergebnis]`++## Fehlerzustände++- `[behebbarer Fehler und Benutzer-Feedback]`+- `[blockierter Zustand und Ausweichoption]`diff --git a/docs/de/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/de/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txtnew file mode 100644index 0000000..6f1c612--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt@@ -0,0 +1,9 @@+Purpose: store model-friendly reference material for the design system.++Suggested contents:+- component naming rules+- spacing and typography tokens+- state variants+- accessibility expectations++Keep this file concise and refresh it when the upstream design system changes.diff --git a/docs/de/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/de/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txtnew file mode 100644index 0000000..c30cc9c--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt@@ -0,0 +1,8 @@+Purpose: store a clean agent-readable extract of the deployment or packaging+rules your repository depends on.++Suggested contents:+- build entrypoints+- runtime assumptions+- environment variable expectations+- common failure signaturesdiff --git a/docs/de/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/de/resources/openai-advanced/repo-template/docs/references/uv-llms.txtnew file mode 100644index 0000000..f2ceba9--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/docs/references/uv-llms.txt@@ -0,0 +1,8 @@+Purpose: store a compact reference for your Python package and environment+workflow when `uv` or similar tooling matters to the repo.++Suggested contents:+- install and sync commands+- lockfile policy+- virtualenv expectations+- verification commandsdiff --git a/docs/de/resources/openai-advanced/repo-template/index.md b/docs/de/resources/openai-advanced/repo-template/index.mdnew file mode 100644index 0000000..ffac121--- /dev/null+++ b/docs/de/resources/openai-advanced/repo-template/index.md@@ -0,0 +1,24 @@+# Erweitertes Repo-Template++Kopieren Sie diesen Starter in ein echtes Repository, wenn Sie eine OpenAI-Stil+agenten-first Dokumentationsoberfläche anstelle von nur einem minimalen Harness möchten.++## Kopierreihenfolge++1. `AGENTS.md` und `ARCHITECTURE.md` ins Repo-Root kopieren.+2. Den gesamten `docs/`-Baum kopieren.+3. Zuerst `docs/PRODUCT_SENSE.md`, `docs/QUALITY_SCORE.md` und+ `docs/RELIABILITY.md` ausfüllen.+4. Den ersten aktiven Plan unter `docs/exec-plans/active/` hinzufügen.+5. Die Einstiegspunktdateien kurz halten und Detail in die verlinkten Docs routen.++## Wofür dieses Template optimiert++- dauerhaften repo-lokalen Kontext+- progressive disclosure statt einer gigantischen Instruktionsdatei+- expliziten Plan-Lebenszyklus+- Qualitäts-Tracking über Zeit+- lesbare Grenzen für Agenten und Menschen++Behandeln Sie jede Datei hier als Starter. Ersetzen Sie Platzhalter, Beispiele und+Beispielbefehle mit Ihren echten Projektspezifika, bevor Sie sich darauf verlassen.diff --git a/docs/de/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/de/resources/openai-advanced/sops/chrome-devtools-validation-loop.mdnew file mode 100644index 0000000..798c03f--- /dev/null+++ b/docs/de/resources/openai-advanced/sops/chrome-devtools-validation-loop.md@@ -0,0 +1,51 @@+# SOP: Chrome DevTools-Validierungsschleife++Verwenden Sie diese SOP, wenn UI-Arbeit von tatsächlicher Laufzeit-Interaktion abhängt+und Screenshots, DOM-Zustand und Konsolenausgabe wichtiger sind als reine Code-Inspektion.++## Ziel++UI-Validierung in eine wiederholbare Interaktionsschleife verwandeln, die der Agent+ausführen kann, bis die Journey fehlerfrei ist.++## Kern-Schleife++1. Zielseite oder App-Instanz auswählen.+2. Veralteten Konsolenlärm bereinigen.+3. Den VORHER-Zustand erfassen.+4. Den UI-Pfad auslösen.+5. Laufzeitereignisse während der Interaktion beobachten.+6. Den NACHHER-Zustand erfassen.+7. Den Fix anwenden und die App bei Bedarf neustarten.+8. Validierung erneut ausführen, bis die Journey fehlerfrei ist.++## Erforderliche Eingaben++- ein stabiler Startbefehl+- eine reproduzierbare UI-Journey+- eine Methode zum Erstellen von Snapshots von DOM, Konsole oder Screenshots+- eine Regel, was als "fehlerfrei" gilt++## Ausführungs-SOP++1. Die Ziel-Journey im aktiven Plan aufschreiben.+2. Erfolg in beobachtbaren Begriffen definieren: Text vorhanden, Button aktiviert,+ Fehler verschwunden, Konsole sauber, Anfrage erfolgreich.+3. Snapshot des Anfangszustands vor der Interaktion erstellen.+4. Genau einen Pfad gleichzeitig auslösen.+5. Laufzeitereignisse, DOM-Änderungen und sichtbare Ausgabe aufzeichnen.+6. Wenn die Journey fehlschlägt, die kleinste verantwortliche Schicht reparieren und neustarten.+7. Denselben Pfad erneut ausführen und VORHER/NACHHER-Nachweise vergleichen.++## Fehlerfreiheitskriterien++- beabsichtigter sichtbarer Zustand ist vorhanden+- unerwartete Fehler sind abwesend+- Konsolenlärm ist verstanden oder bereinigt+- erneutes Ausführen desselben Pfads liefert dasselbe Ergebnis++## Zu aktualisierende Repo-Artefakte++- aktiver Ausführungsplan+- `docs/RELIABILITY.md`, wenn die Journey zu einer Golden Path wird+- Produktspezifikation, wenn sich das sichtbare Verhalten geändert hatdiff --git a/docs/de/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/de/resources/openai-advanced/sops/encode-knowledge-into-repo.mdnew file mode 100644index 0000000..7c17c5d--- /dev/null+++ b/docs/de/resources/openai-advanced/sops/encode-knowledge-into-repo.md@@ -0,0 +1,45 @@+# SOP: Unsichtbares Wissen im Repo codieren++Verwenden Sie diese SOP, wenn wichtiger Kontext noch in Google Docs, Chat-Threads,+Tickets oder in den Köpfen von Menschen lebt.++## Ziel++Agenten-unsichtbares Wissen in der Codebasis auffindbar machen, damit eine neue+Sitzung darauf reagieren kann, ohne sich auf vorherige Gespräche zu verlassen.++## Auslösesignale++- Der Agent fragt ständig, wie das System funktioniert.+- Menschen sagen "wir haben das in Slack entschieden" oder "folgen Sie dem, was X letzte Woche gesagt hat."+- Reviews verweisen auf Produkt- oder Sicherheitsregeln, die nicht im Repo dokumentiert sind.+- Neue Sitzungen wiederholen Entdeckungsarbeit, die bereits geklärt sein sollte.++## Ausführungs-SOP++1. Die unsichtbaren Wissensquellen auflisten: Docs, Chats, unausgesprochene Teamregeln, mündliche Entscheidungen.+2. Für jede Quelle fragen: Ist das Architektur, Produktverhalten, Sicherheitsrichtlinie,+ Zuverlässigkeitserwartung, Plankontext oder Referenzmaterial?+3. Im entsprechenden Repo-Artefakt codieren:+ - Architektur -> `ARCHITECTURE.md`+ - Produktverhalten -> `docs/product-specs/`+ - Designbegründung -> `docs/design-docs/`+ - Ausführungszustand -> `docs/exec-plans/`+ - wiederholte externe Referenzen -> `docs/references/`+ - Qualitäts- oder Zuverlässigkeitserwartungen -> `docs/QUALITY_SCORE.md` oder `docs/RELIABILITY.md`+4. Vage Aussagen durch operationell nützliche Formulierungen ersetzen.+5. Veraltete Kopien entfernen oder als veraltet markieren, damit das Repo eine auffindbare Wahrheit behält.++## Gute Codierungsregeln++- Für Auffindbarkeit schreiben, nicht für literarische Vollständigkeit.+- Kurze Dokumente mit klaren Dateinamen bevorzugen.+- Verwandte Artefakte miteinander verknüpfen.+- Dauerhafte Regeln speichern, keine Meeting-Protokolle.+- Das Repo in derselben Sitzung aktualisieren, in der die Entscheidung getroffen wird.++## Definition von Fertig++- Ein neuer Agent kann die relevante Regel finden, ohne einen Menschen zu fragen.+- Dieselbe Tatsache ist nicht über mehrere widersprüchliche Dateien verstreut.+- Das neue Artefakt liegt nahe am Code oder Workflow, den es steuert.diff --git a/docs/de/resources/openai-advanced/sops/index.md b/docs/de/resources/openai-advanced/sops/index.mdnew file mode 100644index 0000000..e75f63e--- /dev/null+++ b/docs/de/resources/openai-advanced/sops/index.md@@ -0,0 +1,26 @@+# OpenAI Advanced SOPs++Diese SOPs übersetzen die Betriebsmuster des Artikels in konkrete Ausführungs-+Playbooks, denen Sie folgen oder die Sie anpassen können.++## Enthaltene SOPs++- [`layered-domain-architecture.md`](./layered-domain-architecture.md):+ explizite Schichten und produktübergreifende Grenzen etablieren+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):+ unsichtbares Wissen aus Chat, Docs und Erinnerung in repo-lokale Dateien überführen+- [`observability-feedback-loop.md`](./observability-feedback-loop.md):+ Agenten Logs, Metriken, Traces und eine wiederholbare Debug-Schleife geben+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):+ Browser-Automatisierung und Snapshots verwenden, um UI-Verhalten bis zur+ Fehlerfreiheit zu validieren++## Wie Sie sie verwenden++1. Wählen Sie die SOP, die zu Ihrem aktuellen Engpass passt.+2. Verwenden Sie die Checkliste, um die fehlenden Artefakte oder Werkzeuge einzurichten.+3. Codieren Sie die resultierenden Regeln in Ihre kopierten `repo-template/`-Docs.+4. Wandeln Sie wiederholte Review-Kommentare in Prüfungen, Skripte oder Leitplanken um.++Diese SOPs sind nicht dazu gedacht, blind befolgt zu werden. Sie sollen das Harness+lesbarer, durchsetzbar und wiederholbar machen.diff --git a/docs/de/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/de/resources/openai-advanced/sops/layered-domain-architecture.mdnew file mode 100644index 0000000..671f5b3--- /dev/null+++ b/docs/de/resources/openai-advanced/sops/layered-domain-architecture.md@@ -0,0 +1,51 @@+# SOP: Geschichtete Domänenarchitektur++Verwenden Sie diese SOP, wenn der Agent ständig Grenzen verletzt, Logik über Schichten+hinweg dupliziert oder Code erzeugt, der nach wenigen Sitzungen schwer zu reviewen ist.++## Ziel++Domänengrenzen so explizit machen, dass Agenten schnell arbeiten können, ohne+unsichtbar die Struktur zu beeinträchtigen.++## Zielmodell++Bevorzugen Sie innerhalb einer Geschäftsdomäne diesen gerichteten Fluss:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++Produktübergreifende Concerns sollten durch explizite Provider oder Adapter eintreten.+Gemeinsame Utils bleiben außerhalb der Domäne und sollten keine Domänenlogik ansammeln.++## Einrichtungs-Checkliste++- Die aktuellen Domänen in `ARCHITECTURE.md` definieren.+- Erlaubte Abhängigkeitsrichtungen in `ARCHITECTURE.md` dokumentieren.+- Produktübergreifende Schnittstellen wie Auth, Telemetrie und externe APIs erfassen.+- Eine kurze Notiz für die aktuell schwerste Grenzverletzung hinzufügen.+- Entscheiden, was mechanisch durch Lint, Tests oder Skripte durchgesetzt werden soll.++## Ausführungs-SOP++1. Die Codebasis in Domänen aufteilen, bevor der Implementierungsstil angefasst wird.+2. Für jede Domäne die erlaubte Schichtenfolge identifizieren.+3. Alle produktübergreifenden Concerns identifizieren und durch Provider oder Adapter routen.+4. Mehrdeutige gemeinsame Logik entweder in die besitzende Domäne oder in wirklich+ generische Utils verschieben.+5. Die Regeln in `ARCHITECTURE.md` dokumentieren.+6. Eine ausführbare Leitplanke für die teuerste Verletzung hinzufügen.+7. Qualitätsbewertung nach der Änderung aktualisieren.++## Definition von Fertig++- Ein neuer Agent kann erkennen, welche Schicht eine Änderung besitzt.+- UI-Code greift nicht mehr direkt auf Repo oder externe Seiteneffekte zu.+- Produktübergreifende Concerns haben benannte Einstiegspunkte.+- Mindestens eine wichtige Grenze wird mechanisch durchgesetzt.++## Zu aktualisierende Repo-Artefakte++- `ARCHITECTURE.md`+- `docs/QUALITY_SCORE.md`+- `docs/design-docs/`, wenn sich die Begründung geändert hat+- `docs/PLANS.md` oder der aktive Ausführungsplandiff --git a/docs/de/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/de/resources/openai-advanced/sops/observability-feedback-loop.mdnew file mode 100644index 0000000..f9f4a81--- /dev/null+++ b/docs/de/resources/openai-advanced/sops/observability-feedback-loop.md@@ -0,0 +1,46 @@+# SOP: Observability-Feedback-Schleife++Verwenden Sie diese SOP, wenn Debugging langsam ist, Agenten ständig Erfolg ohne+Nachweise behaupten oder das Laufzeitverhalten schwerer zu inspizieren ist als der+Code selbst.++## Ziel++Dem Agenten eine lokale Feedback-Schleife über Logs, Metriken, Traces und ausführbare+Workloads geben, damit er aus der Ausführung heraus argumentieren kann, nicht nur aus+der Code-Inspektion.++## Minimaler Stack++- Anwendung sendet strukturierte Logs+- Anwendung sendet Metriken und Traces, wenn machbar+- lokaler Fan-out- oder Sammelschicht+- Abfrageschnittstellen für Logs, Metriken und Traces+- wiederholbarer Workload oder Benutzer-Journey, um nach jeder Änderung erneut auszuführen++## Ausführungs-SOP++1. Die Golden Runtime-Journeys definieren, die am wichtigsten sind.+2. Strukturierte Logs zum Start und zum kritischen Pfad hinzufügen.+3. Metriken für Latenz, Fehleranzahlen oder Warteschlangentiefe hinzufügen, wo nützlich.+4. Traces oder Timing-Marker für langsame oder mehrstufige Abläufe hinzufügen.+5. Die Signale aus der lokalen Entwicklungsumgebung abfragbar machen.+6. Dem Agenten einen wiederholbaren Workload oder ein Szenario zum erneuten Ausführen geben.+7. Die Schleife einfordern: abfragen -> korrelieren -> argumentieren -> implementieren ->+ neustarten -> erneut ausführen -> verifizieren.++## Debug-Sitzungs-Checkliste++- Was ist fehlgeschlagen?+- Welches Signal beweist den Fehler?+- Welche Schicht ist für den Fehler verantwortlich?+- Was hat sich nach dem Fix geändert?+- Ist die App sauber neugestartet?+- Hat derselbe Workload nach erneutem Ausfahren bestanden?++## Definition von Fertig++- Der Agent kann einen Fehlermodus aus Laufzeitnachweisen erklären.+- Derselbe Workload kann nach jeder Änderung erneut ausgeführt werden.+- Neustart und erneutes Ausführen sind Teil der normalen Aufgaben-Schleife.+- Zuverlässigkeitssignale sind in `docs/RELIABILITY.md` dokumentiert.diff --git a/docs/de/resources/reference/coding-agent-startup-flow.md b/docs/de/resources/reference/coding-agent-startup-flow.mdnew file mode 100644index 0000000..0a341b5--- /dev/null+++ b/docs/de/resources/reference/coding-agent-startup-flow.md@@ -0,0 +1,33 @@+# Coding-Agent-Startflow++Verwenden Sie dies zu Beginn jeder Session, nachdem die Initialisierung abgeschlossen ist.++## Feste Startvorlage++1. `pwd` ausführen und das Repository-Root bestätigen.+2. `claude-progress.md` lesen.+3. `feature_list.json` lesen.+4. Letzte Commits mit `git log --oneline -5` überprüfen.+5. `./init.sh` ausführen.+6. Einen Baseline-Smoke- oder End-to-End-Pfad ausführen.+7. Wenn die Baseline kaputt ist, diese zuerst beheben.+8. Das Feature mit höchster unvollständiger Priorität auswählen.+9. Nur an diesem Feature arbeiten, bis es verifiziert oder explizit blockiert ist.++## Warum diese Reihenfolge wichtig ist++- `pwd` verhindert versehentliche Arbeit im falschen Verzeichnis.+- Fortschritts- und Feature-Dateien stellen dauerhaften Zustand wieder her, bevor neue Edits beginnen.+- Letzte Commits erklären, was sich kürzlich geändert hat.+- `init.sh` standardisiert den Start anstatt sich auf Erinnerung zu verlassen.+- Baseline-Verifikation fängt kaputte Startzustände ab, bevor neue Arbeit sie verbirgt.++## Session-Ende-Spiegel++Die gleiche Session sollte beenden mit:++1. Fortschritt dokumentieren+2. Feature-Status aktualisieren+3. Einen Handoff schreiben falls nötig+4. Sichere Arbeit committen+5. Einen sauberen Neustart-Pfad hinterlassendiff --git a/docs/de/resources/reference/index.md b/docs/de/resources/reference/index.mdnew file mode 100644index 0000000..483fbe6--- /dev/null+++ b/docs/de/resources/reference/index.md@@ -0,0 +1,54 @@+# Deutsche Referenz++Diese Notizen erklären, wie man die Templates als funktionierenden Harness statt als+lose Dateisammlung verwendet.++## Interne Referenznotizen++- [`method-map.md`](./method-map.md): ordnet häufige langlaufende Fehlermodi dem+ Artefakt oder der Policy zu, die sie zuerst adressiert+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md): was der+ Initializer hinterlassen sollte, bevor Feature-Arbeit beginnt+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md): fester+ Session-Start-Flow für spätere Coding-Läufe+- [`prompt-calibration.md`](./prompt-calibration.md): wie man Root-Instruktionen+ scharf hält, ohne sie aufzublähen und brüchig zu machen++## Primäre Artikel++Diese Liste ist bewusst eng. Ein Harness bedeutet das Ausführungssystem rund um+das Modell: die Agent-Schleife, Tool-Ausführung, Sandboxing, Zustand, Kontext,+Verifikation, Terminierung, Orchestrierung und Observabilität. Allgemeine Prompt-+Engineering- oder breite Agent-Framework-Artikel gehören nicht in die primäre Liste.++Die ursprünglichen drei Artikel bleiben das Rückgrat des Kurses:++- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) (2026-02-11): agent-first Repositories, repo-lokaler Kontext, Custom-Linting und strukturelle Guardrails.+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (2025-11-26): Initializer-Agent, Coding-Agent, Feature-Liste, Fortschrittslog und Handoff über Kontextfenster.+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) (2026-03-24): Planner-/Generator-/Evaluator-Rollen, Kontext-Resets, Harness-Vereinfachung und veraltete Annahmen.++## 2026 Erweiterte Referenzen++Dies sind keine Kernquellen des Kurses, aber nützlich beim Entwurf spezifischer+Harness-Module.++- [OpenAI: Unlocking the Codex harness](https://openai.com/index/unlocking-the-codex-harness/) (2026-02-04)+- [OpenAI Developers: Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) (2026-02-23)+- [OpenAI: The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/) (2026-04-15)+- [OpenAI: An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/) (2026-04-27)+- [Anthropic: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler) (2026-02-05)+- [Anthropic: Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents) (2026-04-08)+- [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem) (2026-04-23)+- [LangChain: Context Management for Deep Agents](https://www.langchain.com/blog/context-management-for-deepagents) (2026-01-28)+- [LangChain: Tuning Deep Agents to Work Well with Different Models](https://www.langchain.com/blog/tuning-deep-agents-different-models) (2026-04-29)+- [Microsoft: Agent Harness in Agent Framework](https://devblogs.microsoft.com/agent-framework/agent-harness-in-agent-framework/) (2026-03-12)++## Empfohlene Lesereihenfolge++1. `method-map.md`+2. `initializer-agent-playbook.md`+3. `coding-agent-startup-flow.md`+4. `prompt-calibration.md`+5. OpenAI Harness Engineering+6. Anthropic Effective Harnesses+7. Anthropic Harness Designdiff --git a/docs/de/resources/reference/initializer-agent-playbook.md b/docs/de/resources/reference/initializer-agent-playbook.mdnew file mode 100644index 0000000..75c8163--- /dev/null+++ b/docs/de/resources/reference/initializer-agent-playbook.md@@ -0,0 +1,38 @@+# Initializer-Agenten-Playbook++Verwenden Sie dieses Playbook für die erste ernsthafte Session in einem Repository,+bevor inkrementelle Feature-Arbeit beginnt.++## Ziel++Eine stabile Betriebsoberfläche schaffen, sodass spätere Sessions Verhalten+implementieren können, ohne Startbefehle, aktuellen Status oder Task-Grenzen+neu abzuleiten.++## Erforderliche Outputs++Der Initializer sollte mindestens diese Artefakte hinterlassen:++- eine Root-Instruktionsdatei wie `AGENTS.md` oder `CLAUDE.md`+- eine maschinenlesbare Feature-Oberfläche wie `feature_list.json`+- ein dauerhaftes Fortschrittsartefakt wie `claude-progress.md`+- einen Standard-Starthelfer wie `init.sh`+- einen ersten sicheren Commit, der das Baseline-Gerüst erfasst++## Checkliste++1. Den Standard-Startpfad definieren.+2. Den Standard-Verifikationspfad definieren.+3. Das Fortschrittslog erstellen und den Startzustand dokumentieren.+4. Die Arbeit in explizite Features mit Status zerlegen.+5. Den ersten sauberen Baseline-Commit erstellen.++## Erfolgstest++Eine frische Session ohne vorherigen Chat-Kontext sollte folgende Fragen beantworten können:++- Was dieses Repository macht+- Wie man es startet+- Wie man es verifiziert+- Was unvollendet ist+- Was der nächste beste Schritt istdiff --git a/docs/de/resources/reference/method-map.md b/docs/de/resources/reference/method-map.mdnew file mode 100644index 0000000..a27111d--- /dev/null+++ b/docs/de/resources/reference/method-map.md@@ -0,0 +1,19 @@+# Methoden-Map++Diese Tabelle ordnet die häufigsten Fehlermodi von langlaufenden Coding-Agenten dem+Artefakt oder der Betriebsregel zu, die sie normalerweise zuerst behebt.++| Fehlermodus | Wie es in der Praxis aussieht | Primäre Lösung | Unterstützendes Artefakt |+| --- | --- | --- | --- |+| Kaltstart-Verwirrung | Eine neue Session verbringt die meiste Zeit damit, Setup und Status neu zu entdecken | Das Repository zum System of Record machen | `claude-progress.md` |+| Scope-Ausdehnung | Der Agent startet mehrere Features und schließt keines sauber ab | Aktiven Scope einschränken | `feature_list.json` |+| Vorzeitiger Abschluss | Der Agent behauptet Fertig nach Code-Edits, aber vor ausführbarem Nachweis | Abschluss an Nachweis binden | `clean-state-checklist.md` |+| Fragiler Start | Jede Session lernt neu, wie das Projekt bootet | Setup und Verifikation standardisieren | `init.sh` |+| Schwacher Handoff | Die nächste Session kann nicht erkennen, was verifiziert, kaputt oder als nächstes dran ist | Mit einem expliziten Handoff beenden | `session-handoff.md` |+| Subjektives Review | Review-Qualität hängt von Geschmack oder Erinnerung ab | Output mit festen Kategorien bewerten | `evaluator-rubric.md` |++## Betriebsprinzip++Das kleinste Artefakt hinzufügen, das den beobachteten Fehlermodus direkt adressiert.+Vermeiden Sie, jedes Zuverlässigkeitsproblem durch das Einfügen von mehr Text in eine+globale Instruktionsdatei zu lösen.diff --git a/docs/de/resources/reference/prompt-calibration.md b/docs/de/resources/reference/prompt-calibration.mdnew file mode 100644index 0000000..b59f3ed--- /dev/null+++ b/docs/de/resources/reference/prompt-calibration.md@@ -0,0 +1,25 @@+# Prompt-Kalibrierung++Root-Instruktionen sollten den Betriebsrahmen definieren, nicht jeden möglichen Zug.++## In der Root-Datei behalten++- Repository-Zweck und Scope+- Startpfad+- Verifikationspfad+- Nicht-verhandelbare Einschränkungen+- Erforderliche Zustandsartefakte+- Session-Ende-Regeln++## Aus der Root-Datei auslagern++- Lange historische Edge Cases+- Themenspezifische Implementierungsdetails+- Lokale Architektur-Notizen, die zum Code gehören+- Beispiele, die nur für ein Subsystem gelten++## Arbeitsregel++Die Root-Datei sollte einer frischen Session helfen, sich schnell zu orientieren. Wenn die+Datei zum Sammelbecken für jeden vergangenen Fehlschlag wird, das Detail in kleinere+Dokumente aufteilen und stattdessen dorthin verlinken.diff --git a/docs/de/resources/templates/AGENTS.md b/docs/de/resources/templates/AGENTS.mdnew file mode 100644index 0000000..f1d070d--- /dev/null+++ b/docs/de/resources/templates/AGENTS.md@@ -0,0 +1,55 @@+# AGENTS.md++Dieses Repository ist für langfristige Coding-Agent-Arbeit konzipiert. Ziel ist nicht+die Maximierung der reinen Code-Produktion. Ziel ist es, das Repo in einem Zustand zu+hinterlassen, in dem die nächste Session ohne Raten weiterarbeiten kann.++## Start-Workflow++Bevor Code geschrieben wird:++1. Arbeitsverzeichnis mit `pwd` bestätigen.+2. `claude-progress.md` für den neuesten verifizierten Zustand und nächsten Schritt lesen.+3. `feature_list.json` lesen und das Feature mit höchster Priorität auswählen.+4. Letzte Commits mit `git log --oneline -5` überprüfen.+5. `./init.sh` ausführen.+6. Erforderlichen Smoke- oder End-to-End-Test vor neuer Arbeit ausführen.++Wenn die Baseline-Verifikation bereits fehlschlägt, diese zuerst beheben. Keine neue+Feature-Arbeit auf einen kaputten Startzustand stapeln.++## Arbeitsregeln++- Jeweils an einem Feature arbeiten.+- Ein Feature nicht als abgeschlossen markieren, nur weil Code hinzugefügt wurde.+- Änderungen im gewählten Feature-Scope belassen, es sei denn, ein Blocker erzwingt+ eine enge unterstützende Korrektur.+- Verifikationsregeln während der Implementierung nicht stillschweigend ändern.+- Dauerhafte Repo-Artefakte gegenüber Chat-Zusammenfassungen bevorzugen.++## Erforderliche Artefakte++- `feature_list.json`: Source of Truth für Feature-Status+- `claude-progress.md`: Session-Log und aktueller verifizierter Status+- `init.sh`: Standard-Start- und Verifikationspfad+- `session-handoff.md`: Optionaler kompakter Handoff für größere Sessions++## Definition of Done++Ein Feature ist erst fertig, wenn all dies zutrifft:++- das Zielverhalten ist implementiert+- die erforderliche Verifikation wurde tatsächlich ausgeführt+- der Nachweis ist in `feature_list.json` oder `claude-progress.md` dokumentiert+- das Repository bleibt über den Standard-Startpfad neustartfähig++## Session-Ende++Vor dem Beenden einer Session:++1. `claude-progress.md` aktualisieren.+2. `feature_list.json` aktualisieren.+3. Alle ungelösten Risiken oder Blocker dokumentieren.+4. Mit einer beschreibenden Nachricht committen, sobald die Arbeit in einem sicheren Zustand ist.+5. Das Repo sauber genug hinterlassen, damit die nächste Session sofort `./init.sh`+ ausführen kann.diff --git a/docs/de/resources/templates/CLAUDE.md b/docs/de/resources/templates/CLAUDE.mdnew file mode 100644index 0000000..b378a57--- /dev/null+++ b/docs/de/resources/templates/CLAUDE.md@@ -0,0 +1,47 @@+# CLAUDE.md++Sie arbeiten in einem Repository für langfristige Implementierungsarbeit.+Priorisieren Sie zuverlässigen Abschluss, Kontinuität über Sessions und explizite+Verifikation gegenüber Geschwindigkeit.++## Betriebsablauf++Zu Beginn jeder Session:++1. `pwd` ausführen und das erwartete Repository-Root bestätigen.+2. `claude-progress.md` lesen.+3. `feature_list.json` lesen.+4. Letzte Commits mit `git log --oneline -5` überprüfen.+5. `./init.sh` ausführen.+6. Prüfen, ob der Baseline-Smoke- oder End-to-End-Pfad bereits kaputt ist.++Dann genau ein unfertiges Feature auswählen und nur an diesem Feature arbeiten, bis+es verifiziert ist oder dokumentiert ist, warum es blockiert ist.++## Regeln++- Ein aktives Feature gleichzeitig.+- Keinen Abschluss ohne ausführbaren Nachweis behaupten.+- Die Feature-Liste nicht umschreiben, um unfertige Arbeit zu verbergen.+- Tests nicht entfernen oder schwächen, nur damit die Aufgabe fertig aussieht.+- Repo-Artefakte als System of Record verwenden.++## Erforderliche Dateien++- `feature_list.json`+- `claude-progress.md`+- `init.sh`+- `session-handoff.md` wenn ein kompakter Handoff nützlich ist++## Abschluss-Gate++Ein Feature kann nur zu `passing` wechseln, nachdem die erforderliche Verifikation+erfolgreich war und das Ergebnis dokumentiert ist.++## Vor dem Stoppen++1. Das Fortschrittslog aktualisieren.+2. Den Feature-Status aktualisieren.+3. Was noch kaputt oder unverifiziert ist, dokumentieren.+4. Committen, sobald das Repository sicher fortgesetzt werden kann.+5. Einen sauberen Neustart-Pfad für die nächste Session hinterlassen.diff --git a/docs/de/resources/templates/claude-progress.md b/docs/de/resources/templates/claude-progress.mdnew file mode 100644index 0000000..97db44a--- /dev/null+++ b/docs/de/resources/templates/claude-progress.md@@ -0,0 +1,35 @@+# Fortschrittslog++## Aktueller Verifizierter Zustand++- Repository-Root:+- Standard-Startpfad:+- Standard-Verifikationspfad:+- Aktuelles Feature mit höchster Priorität (unvollendet):+- Aktueller Blocker:++## Session-Log++### Session 001++- Datum:+- Ziel:+- Abgeschlossen:+- Verifikationslauf:+- Nachweis erfasst:+- Commits:+- Dateien oder Artefakte aktualisiert:+- Bekanntes Risiko oder ungelöstes Problem:+- Nächster bester Schritt:++### Session 002++- Datum:+- Ziel:+- Abgeschlossen:+- Verifikationslauf:+- Nachweis erfasst:+- Commits:+- Dateien oder Artefakte aktualisiert:+- Bekanntes Risiko oder ungelöstes Problem:+- Nächster bester Schritt:diff --git a/docs/de/resources/templates/clean-state-checklist.md b/docs/de/resources/templates/clean-state-checklist.mdnew file mode 100644index 0000000..a01faa9--- /dev/null+++ b/docs/de/resources/templates/clean-state-checklist.md@@ -0,0 +1,8 @@+# Clean-State-Checkliste++- [ ] Der Standard-Startpfad funktioniert noch.+- [ ] Der Standard-Verifikationspfad läuft noch.+- [ ] Der aktuelle Fortschritt ist im Fortschrittslog dokumentiert.+- [ ] Der Feature-Status entspricht dem, was tatsächlich bestanden vs. unverifiziert ist.+- [ ] Kein halbfertiger Schritt bleibt undokumentiert.+- [ ] Die nächste Session kann ohne manuelle Reparatur weiterarbeiten.diff --git a/docs/de/resources/templates/evaluator-rubric.md b/docs/de/resources/templates/evaluator-rubric.mdnew file mode 100644index 0000000..a9aef94--- /dev/null+++ b/docs/de/resources/templates/evaluator-rubric.md@@ -0,0 +1,24 @@+# Evaluator-Rubrik++Verwenden Sie diese Rubrik nach der Implementierung und vor der finalen Abnahme.++| Kategorie | Frage | Bewertung (0-2) | Notizen |+| --- | --- | --- | --- |+| Korrektheit | Entspricht das implementierte Verhalten dem angeforderten Feature? | | |+| Verifikation | Wurden die erforderlichen Checks tatsächlich mit Nachweis ausgeführt? | | |+| Scope-Disziplin | Blieb die Session im gewählten Feature-Scope? | | |+| Zuverlässigkeit | Übersteht das Ergebnis einen Neustart ohne Reparatur? | | |+| Wartbarkeit | Sind Code und Dokumentation klar genug für die nächste Session? | | |+| Handoff-Bereitschaft | Kann eine frische Session nur aus Repo-Artefakten weiterarbeiten? | | |++## Urteil++- Akzeptieren+- Überarbeiten+- Blockieren++## Erforderliches Follow-Up++- Fehlende Nachweise:+- Erforderliche Korrekturen:+- Nächster Review-Trigger:diff --git a/docs/de/resources/templates/feature_list.json b/docs/de/resources/templates/feature_list.jsonnew file mode 100644index 0000000..138adc6--- /dev/null+++ b/docs/de/resources/templates/feature_list.json@@ -0,0 +1,64 @@+{+ "project": "replace-with-project-name",+ "last_updated": "YYYY-MM-DD",+ "rules": {+ "single_active_feature": true,+ "passing_requires_evidence": true,+ "do_not_skip_verification": true+ },+ "status_legend": {+ "not_started": "Work has not begun.",+ "in_progress": "The feature is the current active task.",+ "blocked": "Work cannot continue until a documented blocker is resolved.",+ "passing": "Required verification has passed and evidence is recorded."+ },+ "features": [+ {+ "id": "chat-001",+ "priority": 1,+ "area": "chat",+ "title": "Create a new conversation",+ "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",+ "status": "not_started",+ "verification": [+ "Open the app.",+ "Click New Chat.",+ "Verify a new conversation appears in the sidebar.",+ "Verify the main panel shows an empty conversation state."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-002",+ "priority": 2,+ "area": "chat",+ "title": "Send a message in the current conversation",+ "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",+ "status": "not_started",+ "verification": [+ "Open an existing conversation.",+ "Type a message into the input.",+ "Submit the message.",+ "Verify the new message appears in the thread."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-003",+ "priority": 3,+ "area": "chat",+ "title": "Persist the active conversation list",+ "user_visible_behavior": "A user sees previously created conversations after restarting the app.",+ "status": "not_started",+ "verification": [+ "Create two conversations.",+ "Restart the app.",+ "Verify both conversations still appear in the sidebar."+ ],+ "evidence": [],+ "notes": ""+ }+ ]+}diff --git a/docs/de/resources/templates/index.md b/docs/de/resources/templates/index.mdnew file mode 100644index 0000000..8946bc6--- /dev/null+++ b/docs/de/resources/templates/index.md@@ -0,0 +1,255 @@+# Vorlagen-Leitfaden++Diese Vorlagen sind bereit, in Ihr eigenes Projekt kopiert zu werden. Jede erfüllt+einen bestimmten Zweck im Workflow des Agenten. Bearbeiten Sie die Inhalte, um sie+an die Befehle, Pfade, Feature-Namen und Verifikationsschritte Ihres Projekts+anzupassen.++## Erste Schritte++Kopieren Sie diese vier Dateien zuerst in Ihr Projektverzeichnis:++1. `AGENTS.md` oder `CLAUDE.md`+2. `init.sh`+3. `claude-progress.md`+4. `feature_list.json`++Fügen Sie die restlichen Dateien hinzu, wenn Ihr Projekt wächst.++---++## AGENTS.md++Die Haupt-Instruktionsdatei. Dies ist das Erste, was der Agent liest, wenn er eine+Sitzung startet. Sie definiert die Betriebsregeln: was vor dem Schreiben von Code+zu tun ist, wie gearbeitet wird und wie abgeschlossen wird.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Die Start-Workflow-Schritte durch Ihre tatsächlichen Projektpfade und -befehle ersetzen+- Die Arbeitsregeln an die Konventionen Ihres Teams anpassen+- Den Abschnitt zur Definition von Fertig beibehalten -- er ist der wichtigste Teil++**Was sie für den Agenten tut:**++- Sagt ihm, dass er Fortschritt und Feature-Status lesen soll, bevor er mit der Arbeit beginnt+- Zwingt ihn, an nur einem Feature gleichzeitig zu arbeiten+- Verlangt Nachweise, bevor etwas als fertig markiert wird+- Definiert, wie ein sauberes Sitzungsende aussieht++Verwenden Sie `AGENTS.md` für Codex oder andere Agenten. Verwenden Sie `CLAUDE.md`,+wenn Sie mit Claude Code arbeiten -- die Struktur ist dieselbe, nur formatiert für+Claudes Instruktionsstil.++## init.sh++Das Startskript. Führt Abhängigkeitsinstallation, Verifikation und Ausgabe des+Startbefehls aus -- alles in einem Durchgang.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Diese drei Variablen oben bearbeiten:+ - `INSTALL_CMD` -- Ihr Abhängigkeits-Installationsbefehl (z. B. `npm install`, `pip install -r requirements.txt`)+ - `VERIFY_CMD` -- Ihr grundlegender Verifikationsbefehl (z. B. `npm test`, `pytest`)+ - `START_CMD` -- Ihr Dev-Server-Startbefehl (z. B. `npm run dev`)+- Ausführbar machen: `chmod +x init.sh`++**Was es tut:**++1. Gibt das aktuelle Verzeichnis aus (damit Sie bestätigen können, dass es am richtigen Ort läuft)+2. Installiert Abhängigkeiten+3. Führt den Verifikationsbefehl aus+4. Gibt den Startbefehl aus (oder führt ihn aus, wenn `RUN_START_COMMAND=1` gesetzt ist)++Wenn die Verifikation fehlschlägt, sollte der Agent anhalten und die Baseline+korrigieren, bevor er etwas anderes tut.++## claude-progress.md++Das Fortschrittslog. Jede Sitzung schreibt in diese Datei, und jede neue Sitzung+liest sie zuerst.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Den Abschnitt "Aktueller verifizierter Zustand" mit Ihren Projektinformationen ausfüllen+- Nach jeder Sitzung den Sitzungs-Eintrag aktualisieren++**Bedeutung der einzelnen Felder:**++- **Aktueller verifizierter Zustand** -- die einzige Wahrheitsquelle für den Projektstand+ - `Repository-Root-Verzeichnis` -- wo das Projekt liegt+ - `Standard-Startpfad` -- der Befehl, um das Projekt zu starten+ - `Standard-Verifikationspfad` -- der Befehl, um Tests auszuführen+ - `Höchste Priorität unfertiges Feature` -- woran die nächste Sitzung arbeiten sollte+ - `Aktueller Blocker` -- alles, was feststeckt+- **Sitzungs-Eintrag** -- ein Eintrag pro Sitzung+ - `Ziel` -- was Sie vorhatten zu tun+ - `Abgeschlossen` -- was tatsächlich erledigt wurde+ - `Verifikation ausgeführt` -- welche Tests ausgeführt wurden+ - `Nachweise erfasst` -- welche Beweise dokumentiert wurden+ - `Commits` -- was committet wurde+ - `Bekannte Risiken` -- was kaputt sein könnte+ - `Nächste beste Aktion` -- wo die nächste Sitzung beginnen sollte++## feature_list.json++Der Feature-Tracker. Eine maschinenlesbare Liste aller Features, die der Agent+implementieren muss, zusammen mit Status, Verifikationsschritten und Nachweisen.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Die Beispielfeatures durch Ihre eigenen ersetzen+- Jedes Feature benötigt:+ - `id` -- eine kurze eindeutige Kennung+ - `priority` -- Ganzzahl, niedriger = höhere Priorität+ - `area` -- welcher Teil der App (z. B. "chat", "import", "search")+ - `title` -- kurze Beschreibung+ - `user_visible_behavior` -- was der Benutzer sehen soll, wenn es funktioniert+ - `status` -- einer von `not_started`, `in_progress`, `blocked`, `passing`+ - `verification` -- Schritt-für-Schritt-Anleitung zur Bestätigung, dass es funktioniert+ - `evidence` -- dokumentierter Nachweis, dass die Verifikation bestanden hat (vom Agenten ausgefüllt)+ - `notes` -- jeglicher zusätzlicher Kontext++**Statusregeln:**++- `not_started` -- noch nicht angefasst+- `in_progress` -- das aktuell bearbeitete Feature (nur eines gleichzeitig)+- `blocked` -- kann aufgrund eines dokumentierten Problems nicht fortgesetzt werden+- `passing` -- Verifikation bestanden und Nachweise sind dokumentiert++Der Agent sollte zu jedem Zeitpunkt nur ein Feature im Status `in_progress` haben.++## session-handoff.md++Eine kompakte Übergabenotiz zwischen Sitzungen. Verwenden Sie diese, wenn eine+Sitzung endet und Sie möchten, dass die nächste schnell anknüpfen kann.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Am Ende jeder Sitzung ausfüllen (oder den Agenten ausfüllen lassen)++**Was jeder Abschnitt abdeckt:**++- **Aktuell verifiziert** -- was als funktionierend bestätigt ist und welche Verifikation lief+- **Änderungen dieser Sitzung** -- welcher Code oder welche Infrastruktur sich geändert hat+- **Noch kaputt oder unverifiziert** -- bekannte Probleme und riskante Bereiche+- **Nächste beste Aktion** -- was die nächste Sitzung tun sollte und was nicht angefasst werden sollte+- **Befehle** -- Start-, Verifikations- und Debug-Befehle zur schnellen Referenz++Diese Datei ist optional für kleine Sitzungen. Sie wird wichtig, wenn Sitzungen lang+sind oder das Projekt mehrere aktive Bereiche hat.++## clean-state-checklist.md++Eine Checkliste, die vor dem Beenden jeder Sitzung durchzugehen ist. Stellt sicher,+dass das Repo in einem guten Zustand ist, damit die nächste Sitzung sauber starten kann.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Vor dem Schließen einer Sitzung durchgehen+- Der Agent sollte diese Punkte auch als Teil seiner Sitzungsabschluss-Routine prüfen++**Was sie prüft:**++- Standard-Start funktioniert noch+- Standard-Verifikation läuft noch+- Fortschrittslog ist aktualisiert+- Feature-Liste spiegelt den tatsächlichen Zustand wider (keine falschen `passing`-Einträge)+- Keine halbfertige Arbeit undokumentiert gelassen+- Nächste Sitzung kann ohne manuelle Korrekturen fortgesetzt werden++## evaluator-rubric.md++Ein Bewertungsbogen zur Überprüfung der Agenten-Ausgabequalität. Verwenden Sie diesen+nach einer Sitzung oder bei Projektmeilensteinen, um zu bewerten, ob die Arbeit den+Anforderungen entspricht.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Nach einer Sitzung (oder mehreren Sitzungen) die Arbeit des Agenten über sechs Dimensionen bewerten+- Jede Dimension wird mit 0-2 bewertet++**Die sechs Dimensionen:**++1. **Korrektheit** -- entspricht die Implementierung dem Zielverhalten?+2. **Verifikation** -- wurden die erforderlichen Prüfungen tatsächlich mit Nachweisen ausgeführt?+3. **Umfangdisziplin** -- ist der Agent innerhalb des ausgewählten Features geblieben?+4. **Zuverlässigkeit** -- übersteht das Ergebnis einen Neustart oder erneute Ausführung?+5. **Wartbarkeit** -- sind Code und Dokumentation klar genug für die nächste Sitzung?+6. **Übergabebereitschaft** -- kann eine neue Sitzung nur mit Repo-Artefakten fortgesetzt werden?++**Schlussfolgerungsoptionen:**++- Akzeptieren -- erfüllt die Anforderungen+- Überarbeiten -- benötigt Korrekturen vor der Akzeptanz+- Blockieren -- grundlegende Probleme, die zuerst gelöst werden müssen++**Wichtig: Der Evaluator muss kalibriert werden.** Im Standardzustand sind Agenten+schlechte Selbstbewerter -- sie identifizieren Probleme und reden sich dann in eine+Genehmigung. Sie müssen iterieren:++1. Den Evaluator auf einen abgeschlossenen Sprint anwenden.+2. Seine Bewertungen mit Ihrem eigenen menschlichen Urteil vergleichen.+3. Wo sie abweichen, die Rubrik spezifischer zu Bestehen/Fehler-Kriterien machen.+4. Erneut ausführen und die Übereinstimmung prüfen.+5. Wiederholen, bis der Evaluator konsistent mit dem menschlichen Review übereinstimmt.++Planen Sie 3-5 Kalibrierungsrunden. Dokumentieren Sie jede Änderung, damit Sie+verfolgen können, was die Übereinstimmung verbessert hat.++## quality-document.md++Eine Qualitätsmomentaufnahme, die jede Produktdomäne und jede Architektur-Schicht in+Ihrem Projekt bewertet. Verfolgt die Codebasis-Gesundheit über die Zeit, nicht nur+die Ausgabe einzelner Sitzungen.++**Verwendung:**++- In Ihr Projektverzeichnis kopieren+- Vor Beginn einer Sitzung: lesen, um zu verstehen, wo die Codebasis am schwächsten ist+- Nach einer Sitzung: Noten basierend auf den Änderungen aktualisieren+- Über die Zeit: Momentaufnahmen vergleichen, um zu sehen, welche Harness-Änderungen+ die Codebasis-Gesundheit tatsächlich verbessert haben++**Was bewertet wird:**++- **Produktdomänen** (z. B. Dokumentimport, Q&A-Ablauf, Indexierung): jede Domäne erhält+ eine Note (A-D) für Verifikationsstatus, Agenten-Lesbarkeit, Teststabilität und+ wesentliche Lücken+- **Architektur-Schichten** (z. B. Hauptprozess, Preload, Renderer, Services): jede+ Schicht erhält eine Note für Grenzdurchsetzung und Agenten-Lesbarkeit++**Warum es wichtig ist:**++Die Evaluator-Rubrik bewertet einzelne Agenten-Ausgaben. Das Qualitätsdokument bewertet+die Codebasis selbst. Sie beantworten unterschiedliche Fragen:++- Evaluator-Rubrik: "Hat der Agent in dieser Sitzung gute Arbeit geleistet?"+- Qualitätsdokument: "Wird das Projekt mit der Zeit stärker oder schwächer?"++**Wann aktualisieren:**++- Nach jeder bedeutenden Sitzung+- Vor Benchmark-Vergleichen+- Nach Aufräum- oder Vereinfachungsdurchläufen+- Bei Onboarding eines neuen Agenten oder Modells in das Projekt++**Harness-Vereinfachungs-Bezug:**++Das Qualitätsdokument unterstützt auch die Harness-Vereinfachung. Jede Harness-Komponente+codiert eine Annahme darüber, was das Modell nicht kann. Wenn sich Modelle verbessern,+veralten diese Annahmen. Um zu prüfen, ob eine Komponente noch benötigt wird:++1. Eine Qualitätsdokument-Momentaufnahme erstellen.+2. Eine Harness-Komponente entfernen.+3. Die Benchmark-Aufgabensuite ausführen.+4. Eine weitere Momentaufnahme erstellen.+5. Vergleichen -- wenn die Noten nicht gefallen sind, war die Komponente Overhead.+ Wenn doch, wiederherstellen.diff --git a/docs/de/resources/templates/init.sh b/docs/de/resources/templates/init.shnew file mode 100755index 0000000..d7522d6--- /dev/null+++ b/docs/de/resources/templates/init.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash++set -euo pipefail++ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+cd "$ROOT_DIR"++# Replace these commands with the correct commands for your repository.+INSTALL_CMD=(npm install)+VERIFY_CMD=(npm test)+START_CMD=(npm run dev)++echo "==> Working directory: $PWD"+echo "==> Syncing dependencies"+"${INSTALL_CMD[@]}"++echo "==> Running baseline verification"+"${VERIFY_CMD[@]}"++echo "==> Startup command"+printf ' %q' "${START_CMD[@]}"+printf '\n'++if [ "${RUN_START_COMMAND:-0}" = "1" ]; then+ echo "==> Starting the app"+ exec "${START_CMD[@]}"+fi++echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."diff --git a/docs/de/resources/templates/quality-document.md b/docs/de/resources/templates/quality-document.mdnew file mode 100644index 0000000..e16cfbf--- /dev/null+++ b/docs/de/resources/templates/quality-document.md@@ -0,0 +1,43 @@+# Qualitätsdokument++Eine Qualitätsmomentaufnahme für jede Produktdomäne und Architekturschicht. Sowohl Agenten als auch Menschen können dieses Dokument nutzen, um schnell zu verstehen, wo die Codebasis stark ist und wo sie Arbeit braucht.++**Aktualisierungskadenz:** Nach jeder signifikanten Session oder vor dem Start einer neuen Arbeitsphase.++**Benotungsskala:**++- **A**: Alle Verifikationen bestanden, saubere Architektur, agentenlesbar, stabile Tests+- **B**: Verifikationen bestanden, größtenteils sauber, kleinere Lücken in Lesbarkeit oder Testabdeckung+- **C**: Teils funktionierend, bekannte Lücken, einige Code-Bereiche schwer für Agenten zu verstehen+- **D**: Nicht funktionierend oder größere strukturelle Probleme++---++## Produktdomänen++| Domäne | Note | Verifikation | Agenten-Lesbarkeit | Test-Stabilität | Wichtigste Lücken | Zuletzt aktualisiert |+|--------|------|-------------|-------------------|----------------|-------------------|---------------------|+| Dokumentenimport | - | - | - | - | - | - |+| Dokumentenverwaltung | - | - | - | - | - | - |+| Dokumentenindexierung | - | - | - | - | - | - |+| Q&A-Flow | - | - | - | - | - | - |+| Begründete Antworten | - | - | - | - | - | - |++## Architekturschichten++| Schicht | Note | Grenz-Durchsetzung | Agenten-Lesbarkeit | Wichtigste Lücken | Zuletzt aktualisiert |+|---------|------|-------------------|-------------------|-------------------|---------------------|+| Main-Prozess | - | - | - | - | - |+| Preload | - | - | - | - | - |+| Renderer | - | - | - | - | - |+| Services | - | - | - | - | - |++## Änderungsverlauf++### YYYY-MM-DD++- Änderungen:+- Domänen hochgestuft:+- Domänen herabgestuft:+- Neue Lücken identifiziert:+- Lücken geschlossen:diff --git a/docs/de/resources/templates/session-handoff.md b/docs/de/resources/templates/session-handoff.mdnew file mode 100644index 0000000..4a5ef29--- /dev/null+++ b/docs/de/resources/templates/session-handoff.md@@ -0,0 +1,30 @@+# Session-Handoff++## Aktuell Verifiziert++- Was aktuell funktioniert:+- Welche Verifikation tatsächlich lief:++## Diese Session Geändert++- Code oder Verhalten hinzugefügt:+- Infrastruktur- oder Harness-Änderungen:++## Kaputt oder Unverifiziert++- Bekannter Defekt:+- Unverifizierter Pfad:+- Risiko für die nächste Session:++## Nächster Bester Schritt++- Feature mit höchster unvollständiger Priorität:+- Warum es als nächstes kommt:+- Was als bestanden gilt:+- Was sich während dieses Schritts nicht ändern darf:++## Befehle++- Start:+- Verifikation:+- Fokussierter Debug-Befehl:diff --git a/docs/de/skills/index.md b/docs/de/skills/index.mdnew file mode 100644index 0000000..6022b3b--- /dev/null+++ b/docs/de/skills/index.md@@ -0,0 +1,49 @@+# Skills++Dieses Verzeichnis enthält die mit dem Kurs ausgelieferten KI-Agenten-Skills. Skills sind eigenständige Prompt-Vorlagen, die KI-Coding-Agenten wie Claude Code, Codex, Cursor oder Windsurf laden können, um spezialisierte Aufgaben zu erledigen.++## harness-creator++Ein produktionsreifer harness-engineering-Skill für KI-Coding-Agenten. Er hilft beim Erstellen, Bewerten und Verbessern der fünf zentralen harness-Subsysteme: Anweisungen, Zustand, Verifikation, Scope und Session-Lebenszyklus.++### Was er tut++- **Harnesses von Grund auf erstellen** — AGENTS.md, Feature-Listen, Verifikations-Workflows+- **Bestehende Harnesses verbessern** — Bewertung der fünf Subsysteme mit priorisierten Verbesserungen+- **Session-Kontinuität entwerfen** — persistente Erinnerung, Fortschrittsverfolgung, Handoff-Prozeduren+- **Produktionsmuster anwenden** — Memory, Context Engineering, Tool-Sicherheit, Multi-Agent-Koordination++### Schnellstart++Die Skill-Dateien liegen im Repository unter [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator).++Um ihn mit Claude Code zu verwenden, kopiere das Verzeichnis `harness-creator/` in den Skill-Pfad deines Projekts oder zeige deinen Agenten direkt auf die Datei SKILL.md.++### Referenzmuster++Der Skill enthält 6 ausführliche Referenzdokumente:++| Muster | Wann verwenden |+|---------|----------------|+| Memory Persistence | Der Agent vergisst zwischen Sessions |+| Context Engineering | Kontextbudget, JIT-Laden |+| Tool Registry | Tool-Sicherheit, Nebenläufigkeitskontrolle |+| Multi-Agent Coordination | Parallelität, Spezialisierungs-Workflows |+| Lifecycle & Bootstrap | Hooks, Hintergrundaufgaben, Initialisierung |+| Gotchas | 15 nicht offensichtliche Fehlermodi mit Lösungen |++### Vorlagen++Der Skill enthält sofort nutzbare Vorlagen:++- `agents.md` — AGENTS.md-Gerüst mit Arbeitsregeln+- `feature-list.json` — JSON Schema und Beispiel-Feature-Liste+- `init.sh` — Standard-Initialisierungsskript+- `progress.md` — Vorlage für Session-Fortschrittslogs++### Wie dieser Skill gebaut wurde++`harness-creator` wurde mit der **skill-creator**-Methodik entwickelt, Anthropics offiziellem Meta-Skill zum Erstellen, Testen und Iterieren von Agenten-Skills. skill-creator bietet einen strukturierten Workflow aus Entwurf → Test → Bewertung → Iteration mit Eval-Runnern, Gradern und Benchmark-Viewer.++- **skill-creator Quelle**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)+- **Claude Code Skills Docs**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)diff --git a/docs/es/index.md b/docs/es/index.mdnew file mode 100644index 0000000..7356675--- /dev/null+++ b/docs/es/index.md@@ -0,0 +1,73 @@+# Bienvenido a Learn Harness Engineering++Learn Harness Engineering es un curso dedicado a la ingeniería de agentes de programación con IA. Hemos estudiado y sintetizado algunas de las teorías y prácticas más avanzadas de Harness Engineering en la industria. Nuestras referencias principales incluyen:+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)++Mediante diseño sistemático del entorno, gestión de estado, verificación y sistemas de control, este curso enseña cómo hacer que herramientas agentic de programación como Codex y Claude Code sean realmente fiables. Aprenderás a construir funciones, corregir errores y automatizar tareas de desarrollo limitando a tu asistente de programación con reglas y límites explícitos.++## Empezar++Elige tu ruta de aprendizaje. El curso se divide en clases teóricas, proyectos prácticos y una biblioteca de recursos lista para copiar.++<div class="card-grid">+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">+ <h3>Lecciones</h3>+ <p>Comprende por qué incluso los modelos potentes fallan y aprende la teoría detrás de los harnesses eficaces.</p>+ </a>+ <a href="./projects/" class="card">+ <h3>Proyectos</h3>+ <p>Práctica guiada para construir desde cero un entorno agentic fiable.</p>+ </a>+ <a href="./resources/" class="card">+ <h3>Biblioteca de recursos</h3>+ <p>Plantillas listas para copiar, como AGENTS.md y feature_list.json, para tus propios repositorios.</p>+ </a>+</div>++## El mecanismo central de un harness++Un harness no "vuelve más inteligente al modelo"; establece un **sistema de trabajo** de ciclo cerrado para el modelo. Puedes entender el flujo central con este diagrama:++```mermaid+graph TD+ A["Clear Objective<br/>AGENTS.md"] --> B("Initialization<br/>init.sh")+ B --> C{"Run Tasks<br/>AI Agent"}+ C -->|Encounter Issues| D["Runtime Feedback<br/>CLI / Logs"]+ D -->|Auto-fix| C+ C -->|Code Completed| E{"Verify & QA<br/>Test suite"}+ E -->|Failed| D+ E -->|Passed| F["Cleanup & Handoff<br/>claude-progress.md"]++ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;++ class A,F primary;+ class B,D process;+ class C,E check;+```++## Qué aprenderás++Estos son algunos de los conceptos clave que dominarás:++<ul class="index-list">+ <li><strong>Restringir el comportamiento del agente</strong> con reglas y límites explícitos.</li>+ <li><strong>Mantener el contexto</strong> en tareas largas y de varias sesiones.</li>+ <li><strong>Evitar que los agentes</strong> declaren victoria demasiado pronto.</li>+ <li><strong>Verificar el trabajo</strong> con pruebas de pipeline completo y autorreflexión.</li>+ <li><strong>Hacer observable el runtime</strong> y facilitar su depuración.</li>+</ul>++## Siguientes pasos++Cuando entiendas los conceptos básicos, estas guías te ayudarán a profundizar:++<ul class="index-list">+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">Lección 01: Por qué los agentes capaces todavía fallan</a>: empieza por la teoría de harness engineering.</li>+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">Proyecto 01: Baseline vs harness mínimo</a>: recorre tu primera tarea real.</li>+ <li><a href="./resources/templates/">Plantillas</a>: toma el paquete mínimo de harness para tus propios proyectos.</li>+</ul>diff --git a/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..311e665--- /dev/null+++ b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,170 @@+/**+ * failure-pattern-demo.ts+ *+ * Simulates the 4-step failure pattern that capable agents fall into:+ * 1. Incomplete context+ * 2. Locally reasonable changes+ * 3. No global verification+ * 4. Premature completion+ *+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// Simulated "model" -- a simple decision function that bases its output+// solely on whatever context it has been given.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // The task is to "add a search endpoint to the API".+ // Correct answer requires knowing about auth middleware and rate limiting.++ if (!has("auth")) {+ return "Created new route handler /search without authentication checks";+ }+ if (!has("rate-limit")) {+ return "Added search route with auth but forgot rate limiting";+ }+ if (!has("test-standards")) {+ return "Implemented search with auth and rate-limit, but no tests";+ }+ return "Fully implemented search endpoint with auth, rate-limit, and tests";+}++// ---------------------------------------------------------------------------+// Failure simulation+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Step 1: Incomplete Context ----+ const step1Context = ["project structure", "route definitions"];+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];+ const step1Decision = modelDecide(step1Context, "add search endpoint");++ steps.push({+ step: 1,+ name: "Incomplete Context",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Looks good -- route compiles, returns data",+ globalImpact: "Missing auth means unauthenticated access to search",+ completed: false,+ });++ // ---- Step 2: Locally Reasonable Changes ----+ // The agent adds auth after a hint, but still lacks other context.+ const step2Context = [...step1Context, "auth middleware"];+ const step2Missing = ["rate-limiting policy", "test standards"];+ const step2Decision = modelDecide(step2Context, "add search endpoint");++ steps.push({+ step: 2,+ name: "Locally Reasonable Changes",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "Route has auth -- looks complete locally",+ globalImpact: "No rate limiting means the endpoint can be abused",+ completed: false,+ });++ // ---- Step 3: No Global Verification ----+ const step3Context = [...step2Context, "rate-limiting policy"];+ const step3Missing = ["test standards"];+ const step3Decision = modelDecide(step3Context, "add search endpoint");++ steps.push({+ step: 3,+ name: "No Global Verification",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "Feature appears fully implemented",+ globalImpact: "No tests -- regression risk, violates project standards",+ completed: false,+ });++ // ---- Step 4: Premature Completion ----+ steps.push({+ step: 4,+ name: "Premature Completion",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',+ localOutcome: "Agent is satisfied, task marked complete",+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Comparison table+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Step ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);+ console.log(` Action taken : ${s.actionTaken}`);+ console.log(` Local outcome : ${s.localOutcome}`);+ console.log(` Global impact : ${s.globalImpact}`);+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);+ }++ // Summary comparison+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");+ console.log("=".repeat(90));++ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];+ const finalAvailable = steps[steps.length - 1].contextAvailable;++ const header = "| Criterion | Available | Missing | Status |";+ const sep = "|------------------------|-----------|---------|----------|";+ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;+ console.log(row);+ }++ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());diff --git a/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdnew file mode 100644index 0000000..edf5f65--- /dev/null+++ b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -0,0 +1,9 @@+# Lista de Verificación de Señales de Fallo++Usa esta lista al revisar una ejecución de harness débil.++- ¿El agente preguntó o infirió incorrectamente cómo iniciar la app?+- ¿Creó directorios o abstracciones que no coinciden con el producto previsto?+- ¿Se detuvo tras construir una shell de UI visible sin un flujo completo?+- ¿Dejó notas o artefactos que ayuden a una ejecución futura a continuar?+- ¿Podría una sesión nueva entender qué ocurrió en menos de cinco minutos?diff --git a/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdnew file mode 100644index 0000000..0ba5c96--- /dev/null+++ b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -0,0 +1,7 @@+# Código de la Clase 01++Usa esta carpeta para pequeños ejemplos que muestran:++- un modelo potente fallando en un entorno débil+- configuración de repositorio insuficientemente especificada+- bucles de retroalimentación ausentesdiff --git a/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdnew file mode 100644index 0000000..21c6a7c--- /dev/null+++ b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -0,0 +1,18 @@+# Ejemplo de Tarea Subespecificada++Construye una aplicación de escritorio de base de conocimientos con respuesta a preguntas por IA.++Restricciones:++- Ninguna especificada+- No se dio un comando de inicio+- No se proporcionó guía de estructura de carpetas+- No se definió un modelo de datos+- No hay criterios de completitud explícitos++Resultados típicos de este tipo de prompt:++- el agente inventa una estructura ad hoc+- la app puede compilar pero no iniciar consistentemente+- la UI puede aparecer antes de que haya una ruta de importación/consulta utilizable+- el agente a menudo se detiene tras un éxito cosméticodiff --git a/docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.mdnew file mode 100644index 0000000..9620608--- /dev/null+++ b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -0,0 +1,117 @@+[中文版本 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-01-why-capable-agents-still-fail/code/)+> Proyecto práctico: [Proyecto 01. Solo prompt vs reglas primero](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# Lección 01. Los modelos fuertes no significan ejecución fiable++Te consideras una persona con experiencia en el mundo de la IA: suscripción a Claude Pro, clave de API de GPT-4o, números del leaderboard de SWE-bench memorizados. Un día por fin entregas un proyecto real a un agente de IA, con mucha confianza. ¿El resultado? Añade una función pero rompe los tests, corrige un bug pero introduce dos más, corre durante 20 minutos y declara con orgullo "terminado"; miras el código y no es lo que pediste.++Tu primer instinto puede ser: "este modelo no es suficientemente bueno, toca actualizar". Espera. Antes de sacar la tarjeta, considera que quizá el problema no sea el modelo.++Veamos algunos números. A finales de 2025, los agentes de programación más fuertes en SWE-bench Verified logran aproximadamente 50-60%. Y eso en tareas cuidadosamente seleccionadas, con descripciones claras y tests existentes. Si lo llevas a tu entorno diario de desarrollo — requisitos vagos, sin tests existentes, reglas de negocio implícitas por todas partes — ese número solo baja.++Pero detrás de estos números hay una verdad contraintuitiva.++## El mismo caballo, destinos distintos++Anthropic realizó un experimento controlado. Mismo prompt ("construye un creador de juegos retro 2D"), mismo modelo (Opus 4.5). Primera ejecución: sin apoyo, sin harness — 20 minutos, 9 dólares, las funciones centrales del juego no funcionaban. Segunda ejecución: harness completo, con arquitectura de tres agentes planner + generator + evaluator — 6 horas, 200 dólares, el juego era jugable.++No cambiaron el modelo. Opus 4.5 seguía siendo Opus 4.5. Lo que cambió fue la silla de montar.++El artículo de OpenAI sobre harness engineering lo dice con claridad: Codex en un repositorio bien harnessed pasa de "poco fiable" a "fiable". Fíjate en el lenguaje: no es "un poco mejor", sino un cambio cualitativo. Como un caballo pura sangre: puedes montarlo sin silla, pero no llegarás lejos, no irás rápido y caerte no será una sorpresa. El harness es esa silla: **todo lo que existe en la infraestructura de ingeniería fuera de los pesos del modelo.**++## Dónde se atascan realmente los agentes++¿Qué sale mal, exactamente?++Lo más común: nunca definiste la tarea con claridad. Dices "añade una función de búsqueda" y la interpretación del agente puede ser completamente distinta de la tuya: ¿buscar qué?, ¿texto completo o datos estructurados?, ¿paginación?, ¿resaltado? Si no lo especificas, el agente adivina. Si acierta, es suerte; si falla, corregirlo cuesta más que haber sido específico desde el principio. Es como entrar en un restaurante y decirle al chef "quiero pescado": si llega hervido, al vapor o en una olla picante queda al azar.++Incluso cuando especificas la tarea, el proyecto tiene convenciones arquitectónicas implícitas que el agente no conoce. Tu equipo estandarizó SQLAlchemy 2.0, pero el agente escribe código 1.x por defecto. Todos los endpoints deben usar OAuth 2.0, pero esa regla solo vive en tu cabeza y en un mensaje de Slack de hace tres meses. El agente no puede verla. No es que no quiera cumplirla; literalmente no sabe que existe.++El entorno también es una trampa. Entorno de desarrollo incompleto, dependencias faltantes, versiones incorrectas de herramientas. El agente quema una ventana de contexto valiosa en fallos de `pip install` y discrepancias de versión de Node en vez de resolver la tarea real. Es como contratar a un carpintero experto pero olvidar darle martillo, clavos y una mesa nivelada: por muy capaz que sea, no puede trabajar.++Todavía más común: no hay forma de verificar. No hay tests, no hay lint, o los comandos de verificación nunca se comunican al agente. El agente escribe código, lo mira, decide que está bien y dice "terminado". Es como pedir a un estudiante que entregue deberes sin clave de respuestas: cree que acertó, pero al corregir aparecen muchos errores. Anthropic también observó que cuando los agentes sienten que el contexto se agota, se apresuran a terminar, saltan verificación y eligen soluciones simples en vez de óptimas. Lo llaman "context anxiety": lo mismo que ocurre cuando notas que se acaba el tiempo en un examen y empiezas a marcar respuestas al azar.++Las tareas largas que cruzan sesiones son aún peores: los descubrimientos de la sesión anterior se pierden, y cada sesión nueva debe volver a explorar la estructura del proyecto y entender la organización del código. Los agentes sin estado persistente ven cómo la tasa de fallos sube bruscamente en tareas de más de 30 minutos.++## Terminología clave++Con estos escenarios en mente, estos conceptos ya no son jerga:++- **Brecha de capacidad**: la distancia enorme entre el rendimiento del modelo en benchmarks y su rendimiento en tareas reales. Un 50-60% en SWE-bench Verified significa que casi la mitad de los issues reales no se resuelven.+- **Harness**: todo lo que está fuera del modelo: instrucciones, herramientas, entorno, gestión de estado y feedback de verificación. Si no son pesos del modelo, es harness. Es la "silla de montar" de la que hablamos.+- **Fallo inducido por harness**: el modelo tiene capacidad suficiente, pero el entorno de ejecución tiene defectos estructurales. El experimento controlado de Anthropic ya lo demostró.+- **Brecha de verificación**: la diferencia entre la confianza del agente en su salida y la corrección real. El agente dice "terminé" cuando no terminó. Es el modo de fallo más común.+- **Bucle diagnóstico**: ejecutar, observar el fallo, atribuirlo a una capa concreta del harness, corregir esa capa y volver a ejecutar. Es la metodología central del harness engineering.+- **Definition of Done**: conjunto de condiciones verificables por máquina: tests pasan, lint limpio, type checks pasan. Sin una definición explícita, el agente inventará la suya.++## Cuando algo falla, arregla primero el harness++Principio central: **cuando algo falla, no cambies primero el modelo; revisa el harness.** Si el mismo modelo funciona en tareas similares y bien estructuradas, asume que es un problema de harness. Es como un coche que se detiene: no sospechas inmediatamente del motor; primero miras si tiene gasolina.++Pasos concretos:++**Atribuye cada fallo a una capa específica.** No digas simplemente "el modelo es malo". Pregunta: ¿la tarea era poco clara?, ¿faltaba contexto?, ¿no había métodos de verificación? Mapea cada fallo a una de las cinco capas: especificación de tarea, provisión de contexto, entorno de ejecución, feedback de verificación y gestión de estado. Si construyes este hábito, verás cada vez menos "el modelo no es suficiente" en tus registros.++**Escribe una Definition of Done explícita para cada tarea.** No digas "añade búsqueda". Di:+```+Completion criteria:+- New endpoint GET /api/search?q=xxx+- Supports pagination, default 20 items+- Results include highlighted snippets+- All new code passes pytest+- Type checking passes (mypy --strict)+```++**Crea un archivo AGENTS.md.** Ponlo en la raíz del repositorio para decirle al agente el stack técnico, las convenciones arquitectónicas y los comandos de verificación. Es el primer paso del harness engineering y uno de los de mayor retorno. Un solo `AGENTS.md` puede ser más efectivo que actualizar a un modelo más caro; no es broma.++**Construye un bucle diagnóstico.** No trates los fallos como "el modelo volvió a equivocarse". Trátalos como señales de que tu harness tiene un defecto. En cada fallo, identifica la capa, corrígela y evita repetir ese modo de fallo. Tras unas rondas, tu harness se fortalece y el rendimiento del agente se estabiliza. Como reparar carreteras: cada bache que tapas hace más suave el siguiente tramo.++**Cuantifica las mejoras.** Mantén un registro sencillo: si cada tarea tuvo éxito o falló, y qué capa causó el fallo. Después de unas rondas verás cuál capa es el cuello de botella; enfoca ahí tu energía.++## El experimento del millón de líneas++OpenAI realizó en 2025 un experimento agresivo: usar Codex para construir un producto interno completo desde un repositorio git vacío. Cinco meses después, el repositorio tenía alrededor de un millón de líneas de código: lógica de aplicación, infraestructura, tooling, documentación y herramientas internas de desarrollo, todo generado por agentes. Tres ingenieros dirigieron Codex, abriendo y fusionando unas 1.500 PRs, con una media de 3,5 PRs por persona al día.++La restricción clave: **los humanos nunca escriben código directamente.** No era un truco; estaba diseñado para obligar al equipo a descubrir qué cambia cuando el trabajo principal del ingeniero deja de ser escribir código y pasa a ser diseñar entornos, expresar intención y construir bucles de feedback.++El progreso inicial fue más lento de lo esperado. No porque Codex no pudiera, sino porque el entorno no estaba completo: al agente le faltaban herramientas, abstracciones y estructuras internas para avanzar hacia objetivos de alto nivel. El trabajo de los ingenieros se convirtió en descomponer metas grandes en bloques pequeños — diseño, código, revisión, test — dejar que el agente los ensamblara y luego usar esos bloques para desbloquear tareas más complejas. Cuando algo fallaba, la solución casi nunca era "intenta más fuerte"; era "qué capacidad le falta al agente, y cómo la hacemos comprensible y ejecutable".++Este experimento demuestra directamente la tesis central de la lección: **el mismo modelo produce resultados fundamentalmente distintos en un entorno desnudo y en uno con harness completo.** El modelo no cambió. El entorno sí.++> Fuente: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++## Un ejemplo más cotidiano++Un equipo usó Claude Sonnet para añadir un nuevo endpoint a una aplicación web Python mediana (FastAPI + PostgreSQL + Redis, unas 15.000 líneas).++Al principio dieron solo una frase: "añade endpoints de preferencias de usuario bajo `/api/v2/users`". ¿El resultado? El agente gastó 40% de su ventana de contexto explorando la estructura del repo, produjo código que parecía razonable pero no seguía los patrones de manejo de errores del proyecto, usó sintaxis antigua de SQLAlchemy y declaró finalización aunque el endpoint tenía errores en runtime. La siguiente sesión tuvo que repetir todo el descubrimiento.++Más tarde añadieron `AGENTS.md`, con arquitectura del proyecto y versiones del stack, comandos de verificación explícitos (`pytest tests/api/v2/ && python -m mypy src/`) y registros de decisiones arquitectónicas. El mismo modelo tuvo éxito en tres ejecuciones independientes, con alrededor de 60% más eficiencia de contexto.++No cambiaron el modelo. Cambiaron el harness.++## Ideas clave++- Capacidad del modelo y fiabilidad de ejecución son cosas distintas. Un pura sangre también necesita buena silla.+- Cuando algo falla, revisa primero el harness y luego el modelo. Cambiar de modelo es la opción más cara, y muchas veces ni siquiera es un problema del modelo.+- Cada fallo es una señal: tu harness tiene un defecto estructural. Encuéntralo y arréglalo.+- Cinco capas defensivas: especificación de tarea, provisión de contexto, entorno de ejecución, feedback de verificación y gestión de estado. Revísalas de forma sistemática.+- Un solo `AGENTS.md` puede ser más efectivo que actualizar a un modelo más caro. En serio.++## Lecturas adicionales++- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-bench Leaderboard](https://www.swebench.com/)+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)++## Ejercicios++1. **Experimento comparativo**: elige un codebase que conozcas bien y una modificación no trivial. Primero ejecuta el agente sin soporte de harness y registra fallos. Luego añade un `AGENTS.md` con comandos de verificación explícitos y ejecuta de nuevo con el mismo agente. Compara resultados atribuyendo cada fallo a una de las cinco capas.++2. **Medición de la brecha de verificación**: elige 5 tareas de programación. Después de cada una, registra si el agente afirma haber terminado y verifica la corrección real con tests independientes. Calcula la proporción de veces que el agente dice que terminó cuando en realidad no terminó. Esa es tu brecha de verificación.++3. **Práctica de bucle diagnóstico**: encuentra una tarea donde el agente falle repetidamente en tu proyecto. Ejecuta una vez y registra el fallo. Atribúyelo a una de las cinco capas. Corrige esa capa y ejecuta de nuevo. Repite de tres a cinco rondas, registrando las mejoras.diff --git a/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.mdnew file mode 100644index 0000000..e3545a9--- /dev/null+++ b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md@@ -0,0 +1,21 @@+# Ejemplo de Componentes del Harness++Para un agente de programación trabajando en un repositorio local:++- Modelo:+ el LLM en sí++- Harness:+ - system prompt+ - AGENTS.md+ - herramienta bash+ - herramientas de lectura/escritura de archivos+ - acceso a git+ - sistema de archivos local+ - scripts de inicio+ - comandos de prueba+ - stop hooks+ - verificaciones lint+ - bucle de evaluación (evaluator loop)++Si cambias cualquiera de las piezas del harness anteriores, cambias el agente efectivo.diff --git a/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.tsnew file mode 100644index 0000000..d856ba3--- /dev/null+++ b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts@@ -0,0 +1,180 @@+/**+ * harness-vs-no-harness.ts+ *+ * Side-by-side comparison of the same task executor running with and without+ * a harness. The harness version adds explicit rules, verification steps,+ * and stop conditions.+ *+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts+ */++// ---------------------------------------------------------------------------+// Types & helpers+// ---------------------------------------------------------------------------++interface TaskResult {+ name: string;+ passed: boolean;+ durationMs: number;+ issues: string[];+}++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++// ---------------------------------------------------------------------------+// Simulated task executor+// ---------------------------------------------------------------------------++/** A simple task that can succeed or fail depending on rules. */+type Task = {+ name: string;+ requiresAuth: boolean;+ hasTests: boolean;+ withinScope: boolean;+};++const tasks: Task[] = [+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },+];++// ---------------------------------------------------------------------------+// Run WITHOUT harness -- just execute every task, no checks+// ---------------------------------------------------------------------------++function runWithoutHarness(taskList: Task[]): TaskResult[] {+ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];++ // The "agent" does the work and calls it done.+ let passed = true;++ // Problems that go undetected without a harness+ if (t.requiresAuth && !t.hasTests) {+ issues.push("No tests for auth-protected endpoint");+ // Agent doesn't notice -- marks as pass anyway+ }+ if (!t.withinScope) {+ issues.push("Task is outside current scope");+ // Agent doesn't notice+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Run WITH harness -- rules, verification, stop conditions+// ---------------------------------------------------------------------------++function runWithHarness(taskList: Task[]): TaskResult[] {+ const rules = {+ requireTestsForAuth: true,+ enforceScope: true,+ };++ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];+ let passed = true;++ // Rule: auth endpoints must have tests+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {+ issues.push("BLOCKED: Auth-protected endpoint missing tests");+ passed = false;+ }++ // Rule: stay in scope+ if (rules.enforceScope && !t.withinScope) {+ issues.push("BLOCKED: Task outside active scope -- skipped");+ passed = false;+ }++ // Verification: re-check after execution+ if (passed && !t.hasTests) {+ issues.push("WARNING: No tests exist for this change");+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function printComparison(+ noHarness: TaskResult[],+ withHarness: TaskResult[]+): void {+ console.log("\n" + "=".repeat(80));+ console.log(" HARNESS vs NO-HARNESS COMPARISON");+ console.log("=".repeat(80));++ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;++ console.log("\n" + header);+ console.log(sep);++ for (let i = 0; i < noHarness.length; i++) {+ const nh = noHarness[i];+ const wh = withHarness[i];+ const nhPass = nh.passed ? "PASS" : "FAIL";+ const whPass = wh.passed ? "PASS" : "FAIL";+ const nhIssue = nh.issues[0] ?? "(none)";+ const whIssue = wh.issues[0] ?? "(none)";++ console.log(+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`+ );+ }++ // Metrics+ const nhPassed = noHarness.filter((r) => r.passed).length;+ const whPassed = withHarness.filter((r) => r.passed).length;+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);++ console.log("\n" + "=".repeat(80));+ console.log(" SUMMARY METRICS");+ console.log("=".repeat(80));++ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log("\n" + metricsHeader);+ console.log(metricsSep);+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);++ console.log("\n The harness catches problems the no-harness run silently ignores.");+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");+}++/** Count tasks that actually pass (have tests and are in scope). */+function truePassCount(results: TaskResult[]): number {+ return results.filter((r) => r.passed && r.issues.length === 0).length;+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparison(runWithoutHarness(tasks), runWithHarness(tasks));diff --git a/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/index.mdnew file mode 100644index 0000000..484185b--- /dev/null+++ b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 02++Usa esta carpeta para pequeños ejemplos que distinguen:++- comportamiento del modelo+- comportamiento del harness+- configuraciones basadas solo en prompts+- configuraciones de agentes respaldadas por el entornodiff --git a/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.tsnew file mode 100644index 0000000..e56cddd--- /dev/null+++ b/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts@@ -0,0 +1,36 @@+type Message = {+ role: "user" | "assistant";+ content: string;+};++type ToolResult = {+ ok: boolean;+ output: string;+};++function runTool(name: string, input: string): ToolResult {+ if (name === "read_file") {+ return { ok: true, output: `contents of ${input}` };+ }++ return { ok: false, output: `unknown tool: ${name}` };+}++export function minimalHarness(messages: Message[]) {+ const nextAction = {+ tool: "read_file",+ input: "README.md"+ };++ const result = runTool(nextAction.tool, nextAction.input);++ return {+ messages: [+ ...messages,+ {+ role: "assistant",+ content: `Tool ${nextAction.tool} returned: ${result.output}`+ }+ ]+ };+}diff --git a/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.mdnew file mode 100644index 0000000..0fb03c0--- /dev/null+++ b/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -0,0 +1,109 @@+[中文版本 →](../../../zh/lectures/lecture-02-what-a-harness-actually-is/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-02-what-a-harness-actually-is/code/)+> Proyecto práctico: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# Lección 02. Qué significa realmente harness++La palabra "harness" se usa mucho en los círculos de agentes de codificación con IA, pero honestamente, la mayoría de la gente se refiere a "un archivo de prompt" cuando dice harness. Eso no es un harness. Es como abrir un restaurante con nada más que ingredientes — sin estufa, sin cuchillos, sin recetas, sin flujo de emplatado. Eso no es un restaurante. Es un refrigerador.++Esta lección te da una definición precisa y práctica de harness. No una abstracción académica, sino un marco que puedes usar hoy: un harness consiste en cinco subsistemas, cada uno con responsabilidades claras y criterios de evaluación.++## Comienza con una analogía++Imagina que eres un ingeniero recién contratado que llega a un proyecto sin documentación. Sin README, sin comentarios en el código, nadie te dice cómo ejecutar las pruebas, la configuración de CI está enterrada en algún lugar. ¿Puedes escribir buen código? Tal vez — si eres lo suficientemente inteligente y paciente. Pero pasarás mucho tiempo en "averiguar de qué trata este proyecto" en lugar de "resolver el problema."++Un agente de IA enfrenta exactamente la misma situación. Y es peor — tú al menos puedes preguntarle a un colega. El agente solo puede ver los archivos que le pongas delante y los comandos que pueda ejecutar. No puede tocar a alguien en el hombro y preguntar "oye, ¿qué versión del ORM usa este proyecto?"++OpenAI enmarca el principio central como "el repositorio ES la especificación" — todo el contexto necesario debería estar en el repositorio, entregado a través de archivos de instrucciones estructurados, comandos de verificación explícitos y una organización clara de directorios. La documentación de Anthropic sobre agentes de larga duración enfatiza la persistencia del estado, las rutas de recuperación explícitas y el seguimiento estructurado del progreso. Las dos empresas se enfocan en aspectos diferentes, pero están diciendo lo mismo: **todo en la infraestructura de ingeniería fuera del modelo determina cuánta de la capacidad del modelo se realiza realmente.**++Mira algunas herramientas que ya conoces:++**Claude Code** encarna el pensamiento de harness. Lee `CLAUDE.md` de tu repositorio (estantería de recetas), puede ejecutar comandos de shell (estante de cuchillos), se ejecuta en tu entorno local (estufa), mantiene el historial de sesión (estación de preparación) y puede ejecutar pruebas y ver resultados (ventana de control de calidad). Pero si no le dices cómo ejecutar las pruebas, la ventana de control de calidad está rota — nadie sabe si el plato está completamente cocinado.++**Cursor** sigue una lógica similar. Su archivo `.cursorrules` es la estantería de recetas, la terminal es el estante de cuchillos, lee la estructura de tu proyecto y la configuración de lint como estufa. Pero la gestión de estado de Cursor es relativamente débil — cierra el IDE y vuelve a abrirlo, y el contexto anterior desaparece.++**Codex** (el agente de codificación de OpenAI) usa git worktrees para aislar el entorno de ejecución de cada tarea, junto con una pila de observabilidad local (logs, métricas, trazas), para que cada cambio se verifique en un entorno independiente. En repositorios con `AGENTS.md` y comandos de verificación claros, se desempeña mucho mejor que en repositorios "desnudos".++**AutoGPT** es el cuento de advertencia — la falta de gestión estructurada del estado lleva a la acumulación de contexto en tareas largas, y la falta de mecanismos precisos de retroalimentación hace que el agente entre en bucle. Mucha gente dice que AutoGPT "no funciona," pero en realidad es el harness de AutoGPT el que no funciona — dale a un chef una estufa rota y ni los mejores ingredientes producirán una comida.++## Conceptos clave++- **Qué es un harness**: Todo en la infraestructura de ingeniería fuera de los pesos del modelo. OpenAI destila el trabajo central del ingeniero en tres cosas: diseñar entornos, expresar intenciones y construir ciclos de retroalimentación. Anthropic llama a su Claude Agent SDK un "agent harness de propósito general."+- **El repositorio es la única fuente de verdad**: Cualquier cosa que el agente no pueda ver, para todos los efectos prácticos, no existe. OpenAI trata el repositorio como el "sistema de registro" — todo el contexto necesario debe vivir ahí, a través de archivos estructurados y una organización clara de directorios.+- **Da un mapa, no un manual**: La experiencia de OpenAI — `AGENTS.md` debería ser una página de directorio, no una enciclopedia. Alrededor de 100 líneas es suficiente. Si no cabe, divídelo en el directorio `docs/` y deja que el agente lea bajo demanda.+- **Restringe, no microgestiones**: Un buen harness usa reglas ejecutables para restringir al agente, en lugar de enumerar instrucciones una por una. OpenAI dice "haz cumplir invariantes, no microgestiones la implementación"; Anthropic descubrió que los agentes elogian confiadamente su propio trabajo, y la solución es separar "la persona que hace el trabajo" de "la persona que revisa el trabajo."+- **Elimina componentes uno a la vez**: Para cuantificar el valor de cada componente del harness, elimínalos uno a la vez y observa cuál eliminación causa la mayor caída de rendimiento. Anthropic usó este método y descubrió que a medida que los modelos se vuelven más fuertes, algunos componentes dejan de ser críticos — pero siempre surgen nuevos.++## El modelo de harness de cinco subsistemas++Volviendo a la analogía de la cocina. Una cocina completa tiene cinco áreas funcionales, y un harness tiene cinco subsistemas:++```mermaid+flowchart LR+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["Tools<br/>shell / files / tests"]+ Tools --> Env["Runtime<br/>deps / services / versions"]+ Env --> Checks["Check results<br/>test / lint / build"]+ Checks --> Agent+```++**Subsistema de instrucciones (estantería de recetas)**: Crea `AGENTS.md` (o `CLAUDE.md`) que contenga un resumen y propósito del proyecto (una frase), el stack tecnológico y versiones (Python 3.11, FastAPI 0.100+, PostgreSQL 15), comandos de primera ejecución (`make setup`, `make test`), restricciones fijas innegociables ("Todas las APIs deben usar OAuth 2.0") y enlaces a documentación más detallada.++**Subsistema de herramientas (estante de cuchillos)**: Asegúrate de que el agente tenga acceso suficiente a herramientas. No desactives el shell por "seguridad" — si el agente ni siquiera puede ejecutar `pip install`, ¿cómo se supone que trabaje? Pero tampoco abras todo — sigue principios de mínimo privilegio.++**Subsistema de entorno (estufa)**: Haz que el estado del entorno se describa a sí mismo. Usa `pyproject.toml` o `package.json` para bloquear dependencias, `.nvmrc` o `.python-version` para versiones de runtime, Docker o devcontainers para reproducibilidad.++**Subsistema de estado (estación de preparación)**: Las tareas largas necesitan seguimiento del progreso. Usa un archivo simple `PROGRESS.md` que registre: qué está hecho, qué está en progreso, qué está bloqueado. Actualízalo antes de que termine cada sesión, y léelo cuando comience la siguiente.++**Subsistema de retroalimentación (ventana de control de calidad)**: Este es el subsistema de mayor ROI. Lista explícitamente los comandos de verificación en `AGENTS.md`:+```+Verification commands:+- Tests: pytest tests/ -x+- Type check: mypy src/ --strict+- Lint: ruff check src/+- Full verification: make check (includes all above)+```++Que falte cualquier subsistema es como que falte un área funcional en la cocina — todavía puedes cocinar, pero siempre será incómodo.++**Diagnosticando la calidad del harness**: Usa "control isométrico del modelo." Mantén el modelo fijo, elimina subsistemas uno a la vez, mide cuál eliminación causa la mayor caída de rendimiento. Ese es tu cuello de botella — enfoca tu esfuerzo ahí. Como encontrar el cuello de botella en una cocina: quita la estantería de recetas y mira cuánto más lento se vuelve todo, apaga la estufa y mira el impacto.++## La historia real de un equipo++Un equipo usó GPT-4o en una aplicación frontend de TypeScript + React (~20,000 líneas de código). Pasaron por cuatro etapas — esencialmente añadiendo equipamiento de cocina pieza por pieza:++**Etapa 1 — Cocina vacía**: Solo una descripción básica del proyecto en README. 1 de 5 ejecuciones tuvo éxito (20%). Fallos principales: eligió el gestor de paquetes equivocado (npm vs yarn), no siguió las convenciones de nombres de componentes, no pudo ejecutar las pruebas.++**Etapa 2 — Estantería de recetas instalada**: Añadió `AGENTS.md` con versiones del stack tecnológico, convenciones de nombres, decisiones clave de arquitectura. La tasa de éxito subió al 60%. Los fallos restantes fueron principalmente problemas de entorno y verificación faltante.++**Etapa 3 — Ventana de control de calidad abierta**: Listó los comandos de verificación en `AGENTS.md`: `yarn test && yarn lint && yarn build`. La tasa de éxito subió al 80%.++**Etapa 4 — Estación de preparación lista**: Introdujo plantillas de archivos de progreso donde los agentes registraban el trabajo completado e incompleto en cada ejecución. La tasa de éxito se estabilizó en 80-100%.++Cuatro iteraciones, el modelo no cambió en absoluto, la tasa de éxito pasó del 20% a casi el 100%. Ese es el poder de la ingeniería de harness. No compraste ingredientes más caros — simplemente organizaste la cocina correctamente.++## Ideas clave++- Harness = Instrucciones + Herramientas + Entorno + Estado + Retroalimentación. Cinco subsistemas, como las cinco áreas funcionales de una cocina — todos esenciales.+- Si no son pesos del modelo, es harness. Tu harness determina cuánta capacidad del modelo se realiza.+- Entre los cinco subsistemas, el subsistema de retroalimentación suele tener la menor inversión y el mayor retorno. Configura bien tus comandos de verificación primero — la ventana de control de calidad es la mejora más valiosa.+- Usa "control isométrico del modelo" para cuantificar la contribución marginal de cada subsistema — no te guíes por la intuición.+- El harness se degrada como el código. Audita regularmente, paga la deuda de harness como pagas la deuda técnica.++## Lecturas adicionales++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)++## Ejercicios++1. **Auditoría de harness de cinco componentes**: Toma un proyecto donde uses un agente de IA y haz una auditoría completa usando el marco de cinco componentes. Califica cada subsistema del 1 al 5. Encuentra el subsistema con la calificación más baja, dedica 30 minutos a mejorarlo y luego observa el cambio en el rendimiento del agente.++2. **Experimento de control isométrico del modelo**: Elige un modelo y una tarea desafiante. Secuencialmente elimina las instrucciones (borra AGENTS.md), elimina la retroalimentación (no proporciones comandos de verificación), elimina el estado (sin archivos de progreso) — elimina solo uno a la vez y mide la caída de rendimiento. Basándote en los resultados, clasifica la importancia de los subsistemas para tu proyecto.++3. **Análisis de affordances**: Encuentra un escenario donde el agente en tu proyecto "quiere hacer algo pero no puede" (por ejemplo, sabe que debería usar consultas parametrizadas pero no conoce los patrones ORM de tu proyecto). Analiza si esto es un Gulf of Execution (no sabe cómo) o un Gulf of Evaluation (no sabe si está bien), y luego diseña una mejora del harness para cerrar esa brecha.diff --git a/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdnew file mode 100644index 0000000..c16eec7--- /dev/null+++ b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md@@ -0,0 +1,7 @@+# Código de la Clase 03++Usa esta carpeta para ejemplos de:++- estructuras de repositorio legibles por agentes+- documentación como sistema de registro (system of record)+- ubicación incorrecta vs. correcta del conocimientodiff --git a/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txtnew file mode 100644index 0000000..45315da--- /dev/null+++ b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt@@ -0,0 +1,13 @@+AGENTS.md+docs/+ ARCHITECTURE.md+ PRODUCT.md+ RELIABILITY.md+ references/+ electron.md+ sqlite.md+ plans/+ active/+ completed/+src/+scripts/diff --git a/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.tsnew file mode 100644index 0000000..46f6a62--- /dev/null+++ b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts@@ -0,0 +1,189 @@+/**+ * repo-reader.ts+ *+ * Reads a directory structure and scores it on discoverability.+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,+ * handoff files, and other signals of a repository that serves as the+ * system of record.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]+ * (defaults to current working directory if no path given)+ *+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Scoring criteria+// ---------------------------------------------------------------------------++interface Check {+ name: string;+ description: string;+ maxPoints: number;+ check: (dir: string) => { points: number; found: string[]; missing: string[] };+}++const checks: Check[] = [+ {+ name: "AGENTS.md / CLAUDE.md",+ description: "Agent-readable instruction file at repo root",+ maxPoints: 15,+ check: (dir) => {+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };+ },+ },+ {+ name: "Documentation directory",+ description: "Dedicated docs/ or documentation/ directory",+ maxPoints: 10,+ check: (dir) => {+ const candidates = ["docs", "documentation", "doc"];+ const found = candidates.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };+ },+ },+ {+ name: "Architecture documentation",+ description: "Files describing system architecture",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",+ "docs/architecture/", "design.md", "DESIGN.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };+ },+ },+ {+ name: "Feature tracking",+ description: "Feature list or task tracking file",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "feature_list.json", "features.md", "FEATURES.md",+ "docs/features.md", "tasks.json", "TODO.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };+ },+ },+ {+ name: "Handoff / session continuity",+ description: "Files for multi-session continuity",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",+ "docs/handoff.md", ".handoff", "PROGRESS.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };+ },+ },+ {+ name: "Testing structure",+ description: "Test directory or test configuration",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["test", "tests", "__tests__", "spec"];+ const found = patterns.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };+ },+ },+ {+ name: "Configuration files",+ description: "Project config (package.json, tsconfig, etc.)",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };+ },+ },+ {+ name: "README",+ description: "Root README file",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["README.md", "README.rst", "README.txt", "README"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };+ },+ },+];++// ---------------------------------------------------------------------------+// Report generation+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function scoreRepo(targetDir: string): void {+ const resolved = path.resolve(targetDir);++ if (!fs.existsSync(resolved)) {+ console.error(` Error: Directory not found: ${resolved}`);+ process.exit(1);+ }++ console.log("\n" + "=".repeat(80));+ console.log(" REPOSITORY DISCOVERABILITY SCORE");+ console.log("=".repeat(80));+ console.log(` Target: ${resolved}\n`);++ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ let totalScore = 0;+ let maxScore = 0;++ for (const check of checks) {+ const result = check.check(resolved);+ totalScore += result.points;+ maxScore += check.maxPoints;+ const status = result.points > 0 ? "PASS" : "FAIL";+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];++ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);+ }++ // Final score+ console.log("\n" + "-".repeat(80));+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);++ // Grade+ const pct = totalScore / maxScore;+ let grade: string;+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";+ else grade = "F -- Repository lacks discoverability signals";++ console.log(` GRADE: ${grade}`);+ console.log("=".repeat(80) + "\n");+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const target = process.argv[2] || process.cwd();+scoreRepo(target);diff --git a/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.mdnew file mode 100644index 0000000..05881f5--- /dev/null+++ b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md@@ -0,0 +1,11 @@+# Lista de Verificación del Sistema de Registro++¿Puede un agente nuevo descubrir lo siguiente solo desde el repositorio?++- ¿Qué producto se está construyendo?+- ¿Qué debería hacer la app para los usuarios?+- ¿Cómo está organizado el código?+- ¿Cómo se inicia la app?+- ¿Cómo se verifica el estado de salud?+- ¿Qué trabajo está actualmente en progreso?+- ¿Qué estándares de calidad importan?diff --git a/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdnew file mode 100644index 0000000..ffc5cd1--- /dev/null+++ b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -0,0 +1,137 @@+[中文版本 →](../../../zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)+> Proyecto práctico: [Proyecto 02. Espacio de trabajo legible para agentes](./../../projects/project-02-agent-readable-workspace/index.md)++# Lección 03. Convierte el repositorio en la fuente única de verdad++Las decisiones de arquitectura de tu equipo están dispersas entre Confluence, Slack, Jira y la cabeza de unos cuantos ingenieros senior. Para los humanos esto apenas funciona: puedes preguntar a un compañero, buscar en el historial del chat, revisar documentación. Si todo falla, puedes acorralar a alguien en la sala de descanso. Pero para un agente de IA, la información que no está en el repositorio simplemente no existe.++No es una exageración. Piensa en cuáles son realmente las entradas de un agente: prompts de sistema y descripciones de tarea, contenidos de archivos del repositorio y salidas de herramientas. Eso es todo. Tu historial de Slack, tickets de Jira, páginas de Confluence y esa decisión de arquitectura que hablaste con un compañero tomando café un viernes por la tarde: el agente no ve nada de eso. No puede "ir a preguntar a alguien" ni "buscar en el historial del chat". Es un ingeniero encerrado dentro del repositorio; de todo lo que queda fuera no sabe nada.++Así que la pregunta es: ¿vas a darle a este ingeniero un buen mapa?++## Qué debe estar en el mapa++OpenAI lo dice sin rodeos: **la información que no existe en el repo no existe para el agente.** Llaman a esto el principio "repo as spec": el propio repositorio es el documento de especificación con mayor autoridad.++La documentación de Anthropic sobre agentes de larga duración apunta en la misma dirección: el estado persistente es una condición necesaria para la continuidad en tareas largas. La recuperabilidad del conocimiento entre sesiones determina directamente las tasas de éxito. Y ese estado debe existir en el repositorio, porque es el único almacenamiento estable y accesible que tiene el agente.++Puedes pensar: "Nuestro equipo es pequeño, el conocimiento está en la cabeza de todos y funciona bien". Para humanos, quizá. Pero si usas un agente, acepta este hecho: el agente no puede preguntar a personas. Todo lo que necesita saber debe estar escrito y colocado donde pueda encontrarlo.++No se trata de "escribir más documentación". Se trata de "poner la información de decisión en el lugar correcto". Un `ARCHITECTURE.md` de 50 líneas dentro de `src/api/` es diez mil veces más útil que un documento de diseño de 500 páginas en Confluence que nadie mantiene. Es como un mapa de oficina dibujado a mano y pegado a tu escritorio frente a un plano arquitectónico precioso guardado bajo llave: el primero está ahí cuando lo necesitas; el segundo puede ser técnicamente superior, pero es inútil en el momento.++## Visibilidad del conocimiento++```mermaid+flowchart LR+ Slack["Reglas en Slack"] --> Write["Escríbelas en archivos del repo<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Reglas en Confluence"] --> Write+ Heads["Reglas en la cabeza de las personas"] --> Write+ Jira["Reglas en tickets de Jira"] --> Write+ Write --> Repo["Archivos del repositorio"]+ Repo --> Agent["Nueva sesión de agente<br/>lee el repo directamente"]+ Warning["Si una regla no está en el repo,<br/>el agente no puede verla"] --> Agent+```++¿Cómo compruebas si tu mapa es suficientemente bueno? Ejecuta una "prueba de arranque en frío": abre una sesión de agente completamente nueva usando solo el contenido del repo y mira si puede responder cinco preguntas básicas:++```mermaid+flowchart TB+ Q1["¿Qué es este sistema?"] --> A1["AGENTS.md / README"]+ Q2["¿Cómo está organizado?"] --> A2["ARCHITECTURE.md / docs de módulos"]+ Q3["¿Cómo lo ejecuto?"] --> A3["Makefile / init.sh / scripts de package"]+ Q4["¿Cómo lo verifico?"] --> A4["Comandos de test, lint y check"]+ Q5["¿Dónde estamos ahora?"] --> A5["PROGRESS.md / feature list / historial git"]++ A1 --> Ready["Una nueva sesión puede empezar a trabajar<br/>sin preguntar a un humano"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready+```++Si no puede responder, el mapa tiene zonas en blanco. Donde el mapa está en blanco, el agente adivina: las malas conjeturas se convierten en bugs y adivinar demasiado desperdicia contexto. Y cada sesión nueva vuelve a adivinarlo todo. El coste de adivinar siempre es mayor que el coste de dibujar bien el mapa desde el principio.++## Conceptos clave++- **Knowledge Visibility Gap**: La proporción del conocimiento total del proyecto que NO está en el repositorio. Cuanto mayor sea la brecha, mayor será la tasa de fallos del agente. ¿Cuánto conocimiento implícito sobre este proyecto vive en tu cabeza? Cuéntalo todo y luego mira cuánto llegó al repo: la diferencia es tu brecha de visibilidad.+- **System of Record**: El repositorio de código como fuente autorizada para decisiones de proyecto, restricciones de arquitectura, estado de ejecución y estándares de verificación. El repo tiene la última palabra; lo demás no cuenta. Como un mapa que marca "carretera cerrada": no irás por ahí. Pero si esa información solo está en la cabeza de alguien, tendrás que preguntarle cada vez.+- **Cold-Start Test**: Las cinco preguntas anteriores. Cuántas puede responder indica qué tan completo es tu mapa.+- **Discovery Cost**: Cuánto presupuesto de contexto consume el agente para encontrar una información clave en el repo. Cuanto más escondida esté, mayor será el coste de descubrimiento y menos presupuesto quedará para la tarea real. Esconder información crítica en un README diez niveles de directorios abajo es como guardar el extintor en una caja fuerte del sótano: existe, pero no lo encuentras cuando lo necesitas.+- **Knowledge Decay Rate**: La proporción de entradas de conocimiento que se vuelven obsoletas por unidad de tiempo. Que la documentación deje de estar sincronizada con el código es el enemigo principal, peor incluso que no tener documentación.+- **ACID Analogy**: Aplicar principios de transacciones de base de datos (Atomicity, Consistency, Isolation, Durability) a la gestión del estado de agentes. Lo desarrollamos abajo.++## Cómo dibujar un buen mapa++**Principio 1: El conocimiento vive junto al código.** Una regla sobre autenticación de endpoints API debe estar junto al código de API, no enterrada en un documento global gigante. Pon un documento corto en cada directorio de módulo explicando responsabilidades, interfaces y restricciones especiales. Como etiquetas de estantería en una biblioteca: si quieres libros de historia, vas directo al estante "Historia". No necesitas buscar por toda la biblioteca.++**Principio 2: Usa un archivo de entrada estandarizado.** `AGENTS.md` (o `CLAUDE.md`) es la página de aterrizaje del agente. No necesita contener toda la información, pero debe permitir que el agente responda rápido tres preguntas: "Qué es este proyecto", "Cómo lo ejecuto" y "Cómo lo verifico". 50-100 líneas bastan.++**Principio 3: Mínimo pero completo.** Cada pieza de conocimiento debe tener un caso de uso claro. Si eliminar una regla no afecta la calidad de decisión del agente, esa regla no debería existir. Pero cada pregunta de la prueba de arranque en frío debe tener respuesta. Es un equilibrio delicado: ni demasiado, ni demasiado poco, solo lo suficiente.++**Principio 4: Actualiza junto con el código.** Vincula las actualizaciones de conocimiento a los cambios de código. El enfoque más simple: coloca los documentos de arquitectura en el directorio del módulo correspondiente. Cuando modificas código, ves el documento de forma natural. Después de cambios de código, CI puede recordarte revisar si la documentación necesita actualización.++**Estructura concreta del repo**:++```+project/+├── AGENTS.md # Entry: project overview, run commands, hard constraints+├── src/+│ ├── api/+│ │ ├── ARCHITECTURE.md # API layer architecture decisions+│ │ └── ...+│ ├── db/+│ │ ├── CONSTRAINTS.md # Database operation hard constraints+│ │ └── ...+│ └── ...+├── PROGRESS.md # Current progress: done, in-progress, blocked+└── Makefile # Standardized commands: setup, test, lint, check+```++## Gestionar estado de agentes con principios ACID++Esta analogía viene de la gestión de transacciones en bases de datos. Puede parecer una complicación excesiva, pero en realidad da un marco muy práctico:++- **Atomicity**: Cada "operación lógica" (por ejemplo, "añadir nuevo endpoint y actualizar tests") recibe un commit de git. Si falla a mitad de camino, `git stash` para revertir. Todo o nada: no hay "medio hecho".+- **Consistency**: Define predicados de verificación de "estado consistente": todos los tests pasan, lint no reporta errores. El agente ejecuta verificación después de cada operación; los estados intermedios inconsistentes no se commitean. Como una transferencia bancaria: no puedes debitar sin acreditar.+- **Isolation**: Cuando varios agentes trabajan en paralelo, diseña archivos de estado que eviten condiciones de carrera. Enfoque simple: cada agente usa su propio archivo de progreso, o se usan ramas de git para aislar. Dos cocineros no pueden sazonar la misma olla al mismo tiempo: ¿quién se responsabiliza si queda demasiado salada?+- **Durability**: El conocimiento crítico del proyecto vive en archivos versionados por git. El estado temporal puede quedarse en memoria de sesión, pero el conocimiento entre sesiones debe persistirse en archivos. Lo que está en tu cabeza no cuenta; solo cuenta lo que está escrito.++## Una historia real de transformación++Un equipo mantenía una plataforma de e-commerce con unos 30 microservicios. Las decisiones de arquitectura (protocolos de comunicación entre servicios, estrategias de consistencia de datos, reglas de versionado de API) estaban dispersas entre Confluence (parcialmente obsoleto), Slack (difícil de buscar), la cabeza de algunos ingenieros senior (no escalable) y comentarios de código esporádicos (no sistemáticos).++Después de introducir agentes de IA, el 70% de las tareas requería intervención humana. Casi todos los fallos implicaban que el agente violaba alguna restricción implícita de "todo el mundo lo sabe pero nadie lo escribió". Es como un empleado nuevo a quien nadie le dijo "tienes que publicar tu pedido de almuerzo en el chat del grupo": adivina mal, le regañan, pero después de regañarlo nadie escribe la regla.++El equipo ejecutó una transformación:+1. Creó `AGENTS.md` en la raíz del repo con resumen del proyecto, versiones del stack técnico y restricciones globales duras+2. Añadió `ARCHITECTURE.md` en cada directorio de microservicio describiendo responsabilidades, interfaces y dependencias+3. Creó un `CONSTRAINTS.md` centralizado con restricciones duras en lenguaje explícito "MUST/MUST NOT"+4. Añadió `PROGRESS.md` en cada directorio de servicio para seguir el estado actual del trabajo++Después de la transformación, el mismo agente podía responder todas las preguntas clave del proyecto en arranque en frío, y la calidad de finalización de tareas mejoró significativamente.++## Ideas clave++- El conocimiento que no está en el repo no existe para el agente. Poner decisiones críticas en el repo es la inversión más básica en harness: dibuja un buen mapa para no perderte.+- Usa la "prueba de arranque en frío" para evaluar la calidad del repo: ¿puede una sesión fresca responder cinco preguntas básicas usando solo el contenido del repo?+- El conocimiento debe estar cerca del código, ser mínimo pero completo y actualizarse junto con el código. No se trata de escribir más docs, sino de poner la información en el lugar correcto.+- Usa principios ACID para el estado de agentes: commits atómicos, verificación de consistencia, aislamiento de concurrencia y conocimiento crítico durable.+- La degradación del conocimiento es el mayor enemigo. La documentación desincronizada del código es más peligrosa que no tener documentación: envía al agente en la dirección equivocada mientras cree que va bien.++## Lecturas adicionales++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [ADR: Architecture Decision Records](https://adr.github.io/)+- [The Twelve-Factor App](https://12factor.net/)++## Ejercicios++1. **Prueba de arranque en frío**: Abre una sesión de agente completamente nueva en tu proyecto (sin contexto verbal, solo contenido del repo). Hazle cinco preguntas: ¿Qué es este sistema? ¿Cómo está organizado? ¿Cómo lo ejecuto? ¿Cómo lo verifico? ¿Cuál es el progreso actual? Registra lo que no puede responder y mejora el repo hasta que pueda.++2. **Cuantificación de externalización de conocimiento**: Lista todas las decisiones y restricciones importantes para el trabajo de desarrollo en tu proyecto. Marca cada una como dentro o fuera del repo. Calcula tu Knowledge Visibility Gap (proporción fuera del repo). Haz un plan para bajarlo por debajo del 10%.++3. **Evaluación ACID**: Evalúa la gestión de estado de tu proyecto usando la analogía ACID de esta lección. Atomicity: ¿pueden las operaciones del agente revertirse limpiamente? Consistency: ¿existe verificación de "estado consistente"? Isolation: ¿los agentes concurrentes se pisan entre sí? Durability: ¿todo el conocimiento entre sesiones está persistido?diff --git a/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdnew file mode 100644index 0000000..5f94f4d--- /dev/null+++ b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -0,0 +1,15 @@+# AGENTS.md++## Comienza aquí++- Lee `docs/ARCHITECTURE.md`+- Lee `docs/PRODUCT.md`+- Usa `npm run dev` para iniciar la app+- Usa `npm run check` antes de marcar el trabajo como completo++## Reglas estrictas++- No cambies los límites de main/preload/renderer de Electron sin leer+ `docs/ARCHITECTURE.md`+- No marques una funcionalidad como completa sin verificación+- Deja un estado limpio (clean state) para la próxima sesióndiff --git a/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdnew file mode 100644index 0000000..e63705e--- /dev/null+++ b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -0,0 +1,7 @@+# Antipatrones en Archivos de Instrucciones++- Poner todo el conocimiento del repositorio en un solo archivo+- Repetir la misma regla en múltiples lugares+- Codificar reglas obsoletas que nadie audita+- Escribir instrucciones condicionales tan específicas que rara vez aplican+- Incrustar manuales largos de herramientas en el contexto de iniciodiff --git a/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdnew file mode 100644index 0000000..ffad41c--- /dev/null+++ b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md@@ -0,0 +1,7 @@+# Código de la Clase 04++Usa esta carpeta para ejemplos de:++- archivos de instrucciones monolíticos+- puntos de entrada cortos+- patrones de divulgación progresiva (progressive disclosure)diff --git a/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.tsnew file mode 100644index 0000000..59a9632--- /dev/null+++ b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts@@ -0,0 +1,209 @@+/**+ * split-vs-monolithic.ts+ *+ * Creates a monolithic instruction file (~200 lines) and then shows how+ * splitting into 4 focused files dramatically reduces the context needed+ * for any single query. Simulates an "agent" searching for a specific rule+ * and measures how many lines it must read in each approach.+ *+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts+ */++// ---------------------------------------------------------------------------+// Simulated monolithic instruction file (200 lines of rules)+// ---------------------------------------------------------------------------++const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];++// Section 1: Project Overview (lines 1-50)+for (let i = 1; i <= 50; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Project Overview",+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,+ });+}++// Section 2: Code Style Rules (lines 51-100)+for (let i = 51; i <= 100; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Code Style",+ content:+ i === 72+ ? "RULE: Always use explicit return types on exported functions."+ : i === 78+ ? "RULE: Use const assertions for immutable arrays."+ : `Style rule detail line ${i}`,+ });+}++// Section 3: Testing Standards (lines 101-150)+for (let i = 101; i <= 150; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Testing",+ content:+ i === 120+ ? "RULE: Every new endpoint must have integration tests."+ : i === 135+ ? "RULE: Test files must mirror the source file structure."+ : `Testing detail line ${i}`,+ });+}++// Section 4: Deployment Rules (lines 151-200)+for (let i = 151; i <= 200; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Deployment",+ content:+ i === 175+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."+ : `Deployment detail line ${i}`,+ });+}++// ---------------------------------------------------------------------------+// Split instruction files (4 focused files)+// ---------------------------------------------------------------------------++const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),+};++// ---------------------------------------------------------------------------+// Simulated queries -- the agent needs to find specific rules+// ---------------------------------------------------------------------------++interface Query {+ description: string;+ targetRule: string;+ relevantSection: string;+}++const queries: Query[] = [+ {+ description: "Find the rule about return types",+ targetRule: "explicit return types",+ relevantSection: "Code Style",+ },+ {+ description: "Find the deployment window rule",+ targetRule: "deploy on Fridays",+ relevantSection: "Deployment",+ },+ {+ description: "Find the integration test rule",+ targetRule: "integration tests",+ relevantSection: "Testing",+ },+ {+ description: "Find the test file structure rule",+ targetRule: "mirror the source file",+ relevantSection: "Testing",+ },+];++// ---------------------------------------------------------------------------+// Search simulation+// ---------------------------------------------------------------------------++function searchMonolithic(query: Query): { linesRead: number; found: boolean } {+ // Agent must scan from the top, reading each line until it finds the rule.+ // In the worst case it reads all lines.+ let linesRead = 0;+ let found = false;++ for (const line of monolithicInstructions) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found };+}++function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {+ // Agent knows which file to look in based on the section.+ // It only reads lines from that one file.+ const fileMap: Record<string, string> = {+ "Project Overview": "01-project-overview.md",+ "Code Style": "02-code-style.md",+ Testing: "03-testing.md",+ Deployment: "04-deployment.md",+ };++ const targetFile = fileMap[query.relevantSection];+ const lines = splitInstructions[targetFile];+ let linesRead = 0;+ let found = false;++ for (const line of lines) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found, fileAccessed: targetFile };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");+ console.log("=".repeat(90));++ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");++ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;+ console.log(header);+ console.log(sep);++ let totalMono = 0;+ let totalSplit = 0;++ for (const q of queries) {+ const mono = searchMonolithic(q);+ const split = searchSplit(q);+ totalMono += mono.linesRead;+ totalSplit += split.linesRead;++ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);+ console.log(+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`+ );+ }++ console.log(sep);+ const avgMono = Math.round(totalMono / queries.length);+ const avgSplit = Math.round(totalSplit / queries.length);+ console.log(+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`+ );++ console.log("\n" + "=".repeat(90));+ console.log(" KEY INSIGHT");+ console.log("=".repeat(90));+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");+}++run();diff --git a/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdnew file mode 100644index 0000000..640d9db--- /dev/null+++ b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -0,0 +1,132 @@+[中文版本 →](../../../zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)+> Proyecto práctico: [Proyecto 02. Espacio de trabajo legible para agentes](./../../projects/project-02-agent-readable-workspace/index.md)++# Lección 04. Divide las instrucciones entre archivos++Te tomaste en serio la ingeniería de harness. Creaste un `AGENTS.md` y metiste en él todas las reglas, restricciones y lecciones aprendidas que se te ocurrieron. Un mes después el archivo tenía 300 líneas; dos meses después, 450; tres meses después, 600. Entonces notas que el rendimiento del agente está empeorando: para corregir un bug simple, consume mucho contexto procesando instrucciones de despliegue irrelevantes; una restricción de seguridad crítica enterrada en la línea 300 se ignora por completo; tres reglas contradictorias de estilo hacen que el agente elija una al azar cada vez.++Esta es la trampa del "archivo gigante de instrucciones". Es como sobrecargar una maleta: todo parece útil, así que lo metes hasta que la cremallera está a punto de reventar. Para encontrar ropa interior de cambio tienes que vaciar toda la bolsa. Cargas una maleta llena, pero en realidad usas quizá un tercio de lo que hay dentro.++## El ciclo vicioso de fondo++El ciclo vicioso más común funciona así: el agente comete un error, tú dices "añadamos una regla para evitar esto", la agregas a `AGENTS.md`, funciona temporalmente, el agente comete otro error, agregas otra regla, repites, y el archivo se hincha sin control.++No es culpa tuya. Es una reacción muy natural: añadir una regla cada vez que algo sale mal parece razonable, como meter una cosa más en la bolsa cada vez que sales de casa "por si acaso". Pero el efecto acumulado es desastroso. Veamos qué se rompe exactamente.++**El presupuesto de contexto se consume vivo.** La ventana de contexto del agente es finita. Supón que tu agente tiene una ventana de 200K tokens (un tamaño estándar en Claude). Un archivo de instrucciones inflado puede consumir 10-20K tokens. ¿Parece que todavía queda mucho espacio? Pero una tarea compleja puede requerir leer decenas de archivos fuente, la salida de herramientas también ocupa contexto y el historial de conversación se acumula. Para cuando el agente necesita entender el código, el presupuesto ya está apretado, como una maleta tan llena de cosas "por si acaso" que ya no cabe el portátil.++**Perdido en el medio.** El artículo "Lost in the Middle" (Liu et al., 2023) demostró claramente que los LLM usan la información situada en medio de textos largos con mucha menos eficacia que la del principio o el final. Tu `AGENTS.md` tiene 600 líneas, y en la línea 300 dice "todas las consultas de base de datos deben usar consultas parametrizadas": es una restricción fuerte de seguridad. Pero está enterrada en el medio, y el agente casi seguro la ignorará. Como ese protector solar en el fondo de una maleta demasiado llena: sabes que está ahí, buscas tres veces, no lo encuentras y terminas comprando otro.++**Conflictos de prioridad.** El archivo mezcla restricciones no negociables ("never use eval()"), guías de diseño importantes ("prefer functional style") y una lección histórica concreta ("la semana pasada se corrigió una fuga de memoria en WebSocket, vigilar patrones similares"). Estas tres reglas tienen niveles de importancia completamente distintos, pero se ven iguales en el archivo. El agente no tiene una señal fiable para distinguirlas, como si tu pasaporte y el cable de carga estuvieran mezclados en la maleta sin forma de saber qué es más urgente.++**Deterioro de mantenimiento.** Los archivos grandes son inherentemente difíciles de mantener. Las instrucciones obsoletas rara vez se eliminan, porque las consecuencias de borrarlas son inciertas ("quizá algo depende de esta regla"), mientras que añadir instrucciones nuevas parece gratis. Resultado: el archivo solo crece, nunca se reduce, y la relación señal-ruido cae continuamente. Es exactamente como la acumulación de deuda técnica en software.++**Acumulación de contradicciones.** Instrucciones añadidas en momentos distintos empiezan a contradecirse: una dice "usar TypeScript strict mode", otra dice "algunos archivos legacy permiten tipos any". El agente elige al azar cuál seguir cada vez. Como si tu madre dijera "abrígate" y tu padre dijera "no te pongas demasiada ropa", y tú te quedaras en la puerta sin saber a quién escuchar.++## Conceptos clave++- **Instruction Bloat**: Cuando un archivo de instrucciones ocupa más del 10-15% de la ventana de contexto, empieza a desplazar presupuesto que debería usarse para leer código y razonar sobre la tarea. Un `AGENTS.md` de 600 líneas puede consumir 10.000-20.000 tokens, es decir, 8-15% de una ventana de 128K antes de que el agente empiece.+- **Lost in the Middle Effect**: La investigación de Liu et al. en 2023 mostró que los LLM usan la información en medio de textos largos mucho peor que la información del principio o del final. Una restricción crítica enterrada en la línea 300 de un archivo de 600 líneas tiene alta probabilidad de ser ignorada en la práctica.+- **Instruction Signal-to-Noise Ratio (SNR)**: La proporción de instrucciones del archivo que son relevantes para la tarea actual. Verse obligado a leer 50 líneas de instrucciones de despliegue durante un arreglo de bug es bajo SNR.+- **Routing File**: Un archivo de entrada corto cuya función principal es dirigir al agente hacia documentación más detallada, no contenerlo todo. 50-200 líneas bastan.+- **Progressive Disclosure**: Dar primero la información general y los detalles cuando hacen falta. Un buen diseño de harness se parece a un buen diseño de UI: no vuelca todas las opciones al usuario de una vez.+- **Priority Ambiguity**: Cuando todas las instrucciones aparecen con el mismo formato y en el mismo lugar, el agente no puede distinguir restricciones duras no negociables de guías suaves.++## Arquitectura de instrucciones++```mermaid+flowchart LR+ Mono["Un AGENTS.md de 600 líneas"] --> MonoLoad["Incluso un bug pequeño<br/>debe leer reglas de despliegue y notas viejas"]+ MonoLoad --> MonoRisk["Las reglas importantes enterradas en el medio<br/>son fáciles de pasar por alto"]++ Router["AGENTS.md corto"] --> Topics["Cargar docs de API / DB / testing<br/>solo cuando la tarea los necesita"]+ Topics --> RoutedResult["Queda más contexto para leer código<br/>y verificar"]+```++```mermaid+flowchart TB+ File["Archivo de instrucciones de 600 líneas"] --> Top["Sección superior<br/>quick start + restricciones duras"]+ File --> Mid["Sección central<br/>regla crítica de seguridad en la línea 300"]+ File --> Bot["Sección final<br/>checklist explícita de cierre"]+ Top --> Seen["Alta probabilidad de recordarse"]+ Bot --> Seen+ Mid --> Missed["Alta probabilidad de diluirse u omitirse"]+```++## Cómo dividirlo++El principio central: mantén a mano la información que se necesita con frecuencia, guarda aparte la que se necesita ocasionalmente y elimina lo que no vas a usar.++El archivo de entrada `AGENTS.md` debe mantenerse en 50-200 líneas y contener solo lo que se usa con más frecuencia: resumen del proyecto (una o dos frases), comandos de primera ejecución (`make setup && make test`), restricciones globales duras (no más de 15 reglas no negociables) y enlaces a documentos temáticos (descripción de una línea + condición de aplicabilidad).++```markdown+# AGENTS.md++## Resumen del proyecto+Python 3.11 FastAPI backend, PostgreSQL 15 database.++## Quick Start+- Install: `make setup`+- Test: `make test`+- Full verification: `make check`++## Hard Constraints+- All APIs must use OAuth 2.0 authentication+- All database queries must use SQLAlchemy 2.0 syntax+- All PRs must pass pytest + mypy --strict + ruff check++## Topic Docs+- [API Design Patterns](docs/api-patterns.md) — Required reading when adding endpoints+- [Database Rules](docs/database-rules.md) — Required when modifying database operations+- [Testing Standards](docs/testing-standards.md) — Reference when writing tests+```++Cada documento temático debe tener 50-150 líneas, organizado por tema en `docs/` o junto al módulo correspondiente. El agente solo lo lee cuando hace falta. Como cubos de organización dentro de una maleta: ropa interior en uno, artículos de aseo en otro, cargadores en un tercero. Encontrar algo no requiere vaciar toda la bolsa.++Parte de la información conviene ponerla directamente en el código: definiciones de tipos, comentarios de interfaz, explicaciones en archivos de configuración. El agente la ve naturalmente al leer el código, así que no hace falta duplicarla en instrucciones.++Cada instrucción debería tener una fuente ("¿por qué se añadió esta regla?"), una condición de aplicabilidad ("¿cuándo hace falta?") y una condición de caducidad ("¿en qué circunstancias se puede eliminar?"). Audita con regularidad y elimina entradas obsoletas, redundantes o contradictorias. Gestiona tus instrucciones como gestionas dependencias de código: las dependencias no usadas deben borrarse, de lo contrario solo ralentizan el sistema.++Si una instrucción debe estar en el archivo de entrada, ponla arriba o abajo, nunca en el medio. El efecto "lost in the middle" nos dice que los LLM usan mucho mejor la información de los extremos que la del centro. Pero el mejor enfoque es mover las instrucciones a documentos temáticos que se cargan bajo demanda.++OpenAI y Anthropic apoyan implícitamente el enfoque de división. OpenAI dice que los archivos de entrada deben ser "cortos y orientados al enrutamiento"; Anthropic dice que la información de control para agentes de larga duración debe ser "concisa y de alta prioridad". Ambos dicen lo mismo: no metas todo en un solo archivo. Una maleta necesita organización, no fuerza bruta.++## Ejemplo real++El `AGENTS.md` de un equipo SaaS creció de 50 a 600 líneas. Mezclaba versiones del stack técnico, estándares de código, notas históricas de bugs, guías de uso de API, procedimientos de despliegue y preferencias personales de miembros del equipo: la maleta entera estaba a punto de reventar.++El rendimiento del agente empezó a caer de forma visible: durante arreglos de bugs simples gastaba mucho contexto procesando instrucciones de despliegue irrelevantes; la restricción de seguridad "todas las consultas de base de datos deben usar consultas parametrizadas" estaba enterrada en la línea 300 y se ignoraba con frecuencia; tres reglas contradictorias de estilo producían comportamiento aleatorio.++El equipo ejecutó una "reorganización de maleta":+1. `AGENTS.md` se redujo a 80 líneas: solo resumen del proyecto, comandos de ejecución y 15 restricciones globales duras+2. Se crearon documentos temáticos: `docs/api-patterns.md` (120 líneas), `docs/database-rules.md` (60 líneas), `docs/testing-standards.md` (80 líneas)+3. Se añadieron enlaces a esos documentos en el archivo de enrutamiento+4. Las notas históricas se convirtieron en tests o se eliminaron++Después de refactorizar, la tasa de éxito del mismo conjunto de tareas pasó de 45% a 72%. El cumplimiento de la restricción de seguridad pasó de 60% a 95%, porque se movió del medio del archivo a la parte superior del archivo de enrutamiento y dejó de perderse en el medio.++## Ideas clave++- "Añadir una regla" alivia el dolor a corto plazo y envenena a largo plazo. Antes de añadir una regla, pregunta: ¿esto estaría mejor en un documento temático? No sigas metiendo cosas en la maleta.+- El archivo de entrada es un router, no una enciclopedia. 50-200 líneas con resumen, restricciones duras y enlaces.+- Aprovecha el efecto "lost in the middle": la información importante va arriba o abajo; la información menos importante se mueve a documentos temáticos.+- Gestiona el crecimiento de instrucciones como deuda técnica. Auditorías periódicas; cada instrucción necesita fuente, condición de aplicabilidad y condición de caducidad.+- Tras dividir, mejora el SNR y el agente gasta más presupuesto de contexto en la tarea real, no en procesar instrucciones irrelevantes.++## Lecturas adicionales++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)++## Ejercicios++1. **Auditoría de SNR**: Toma tu archivo actual de instrucciones de entrada y lista todas las instrucciones. Elige 5 tipos comunes de tareas y marca si cada instrucción es relevante para cada tarea. Calcula el SNR por tipo de tarea. Las instrucciones que son ruido para la mayoría de tareas deben moverse a documentos temáticos.++2. **Refactor de progressive disclosure**: Si tienes un archivo de instrucciones de más de 300 líneas, divídelo en: (a) un archivo de enrutamiento de menos de 100 líneas, (b) 3-5 documentos temáticos. Ejecuta el mismo conjunto de tareas (al menos 5) antes y después, y compara tasas de éxito.++3. **Verificación de lost in the middle**: En un archivo de instrucciones largo, coloca una restricción crítica arriba, en el medio y abajo respectivamente, ejecutando el mismo conjunto de tareas cada vez (al menos 5 ejecuciones por posición). Mira si cambia la tasa de cumplimiento. Puede sorprenderte la fuerza del efecto de posición.diff --git a/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.mdnew file mode 100644index 0000000..70506a6--- /dev/null+++ b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md@@ -0,0 +1,6 @@+# Lista de Verificación de Continuidad++- ¿Puede un agente nuevo identificar el trabajo reciente en menos de cinco minutos?+- ¿Está documentada la ruta de inicio estable actual?+- ¿Está el trabajo sin terminar claramente identificado?+- ¿Es visible la siguiente mejor tarea sin leer registros de chat antiguos?diff --git a/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdnew file mode 100644index 0000000..d16697e--- /dev/null+++ b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md@@ -0,0 +1,7 @@+# Código de la Clase 05++Usa esta carpeta para ejemplos de:++- tareas multi-sesión rotas+- artefactos de continuidad faltantes+- patrones de recuperación de continuidaddiff --git a/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdnew file mode 100644index 0000000..de7cc2f--- /dev/null+++ b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -0,0 +1,17 @@+# Ejemplo de Entrega de Sesión++## Completado++- Añadido soporte de importación de Markdown+- Añadida una lista básica de documentos en el renderer++## Roto o No Verificado++- La importación funciona para `.md` pero falla para archivos `.txt` grandes+- La app arranca, pero la vista de detalles no está conectada++## Siguiente Mejor Paso++- Corregir la ruta de importación de `.txt`+- Verificar la importación end-to-end+- Luego añadir el panel de detalles del documentodiff --git a/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.tsnew file mode 100644index 0000000..69f9c3e--- /dev/null+++ b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts@@ -0,0 +1,162 @@+/**+ * session-simulator.ts+ *+ * Simulates two sessions working on a multi-step task.+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.+ * Run 2: With handoff file -- Session B picks up where Session A left off.+ *+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface TaskStep {+ id: number;+ name: string;+ durationMs: number;+}++interface SessionResult {+ session: string;+ stepsCompleted: number;+ totalDurationMs: number;+ duplicatedSteps: number;+ output: string[];+}++// ---------------------------------------------------------------------------+// Task definition+// ---------------------------------------------------------------------------++const taskSteps: TaskStep[] = [+ { id: 1, name: "Read project structure", durationMs: 50 },+ { id: 2, name: "Understand existing auth module", durationMs: 80 },+ { id: 3, name: "Design new search endpoint", durationMs: 60 },+ { id: 4, name: "Implement search endpoint", durationMs: 100 },+ { id: 5, name: "Write integration tests", durationMs: 70 },+ { id: 6, name: "Update documentation", durationMs: 40 },+];++// ---------------------------------------------------------------------------+// Simulated session executor+// ---------------------------------------------------------------------------++/** Simulate a session doing work. */+function runSession(+ sessionName: string,+ startStep: number,+ endStep: number+): SessionResult {+ const output: string[] = [];+ let totalDuration = 0;++ for (let i = startStep; i <= endStep; i++) {+ const step = taskSteps.find((s) => s.id === i)!;+ totalDuration += step.durationMs;+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);+ }++ return {+ session: sessionName,+ stepsCompleted: endStep - startStep + 1,+ totalDurationMs: totalDuration,+ duplicatedSteps: 0,+ output,+ };+}++// ---------------------------------------------------------------------------+// Run 1: No handoff file+// ---------------------------------------------------------------------------++function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 before timing out+ const sessionA = runSession("Session A", 1, 3);++ // Session B has no context, starts from scratch+ const sessionB = runSession("Session B", 1, 6);+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Run 2: With handoff file+// ---------------------------------------------------------------------------++function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 and writes a handoff file+ const sessionA = runSession("Session A", 1, 3);++ // Session B reads handoff, starts from step 4+ const sessionB = runSession("Session B", 4, 6);+ sessionB.duplicatedSteps = 0;++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {+ console.log("\n" + "=".repeat(80));+ console.log(` ${title}`);+ console.log("=".repeat(80));++ console.log("\n Session A output:");+ for (const line of result.sessionA.output) {+ console.log(line);+ }++ console.log("\n Session B output:");+ for (const line of result.sessionB.output) {+ console.log(line);+ }++ console.log("\n Session B notes:");+ if (result.sessionB.duplicatedSteps > 0) {+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);+ } else {+ console.log(" - Read handoff file, continued from step 4");+ console.log(" - No duplicate work performed");+ }+}++function printComparison(): void {+ const noHandoff = simulateNoHandoff();+ const withHandoff = simulateWithHandoff();++ printRun("RUN 1: NO HANDOFF FILE", noHandoff);+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);++ // Comparison table+ console.log("\n" + "=".repeat(80));+ console.log(" COMPARISON TABLE");+ console.log("=".repeat(80) + "\n");++ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log(header);+ console.log(sep);++ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;++ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);++ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");+}++printComparison();diff --git a/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdnew file mode 100644index 0000000..2610d5b--- /dev/null+++ b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -0,0 +1,180 @@+[中文版本 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)+> Proyecto práctico: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# Lección 05. Mantén vivo el contexto entre sesiones++Le pides a Claude Code que implemente una funcionalidad completa. Se ejecuta durante 30 minutos, hace la mayor parte del trabajo, pero el contexto se está agotando. Inicias una nueva sesión para continuar — y descubres que no recuerda qué decisiones se tomaron la última vez, por qué se eligió la opción A sobre la B, qué archivos ya fueron modificados o en qué estado están las pruebas. Dedica 15 minutos a re-explorar el proyecto, y podría ser inconsistente con el enfoque anterior.++Imagina si fueras un artesano que olvida todo cada mañana al despertar. Tendrías que volver a familiarizarte con todo el sitio de construcción — qué pared está a medio construir, por qué se eligieron ladrillos rojos en lugar de azules, dónde llegaron las tuberías. Peor aún, podrías arrancar una ventana que ya fue instalada ayer, simplemente porque no recordabas que ya estaba hecha.++Esta es exactamente la dificultad que enfrentan los agentes de codificación con IA en tareas entre sesiones. Esta lección explica por qué los agentes "se quedan en blanco" durante tareas largas, y cómo la persistencia estructurada del estado puede hacerlos como un artesano que lleva un diario confiable — sigue siendo amnésico, pero el diario lo recuerda todo.++## Las ventanas de contexto no son infinitas++Las ventanas de contexto son finitas. Esto no se resuelve con actualizaciones de modelos — incluso si los tamaños de ventana crecen a 1M tokens, las tareas complejas seguirán agotándolas. Porque los agentes no solo están generando código; están entendiendo bases de código, rastreando su propio historial de decisiones, procesando la salida de herramientas y manteniendo el contexto de conversación. Toda esta información crece más rápido que la expansión de la ventana.++Un problema más profundo: la información que produce el agente no tiene la misma importancia. Los pasos de razonamiento intermedio contienen el "por qué" de las decisiones — por qué se eligió la opción B sobre la A, por qué esta biblioteca en lugar de aquella, por qué se omitió una optimización particular. La salida final solo contiene el "qué" — el código en sí. Las estrategias de compaction suelen preservar lo segundo pero pierden lo primero. La siguiente sesión ve el código pero no sabe por qué está escrito de esa manera, y podría "optimizar" una decisión de diseño deliberada.++Anthropic descubrió algo fascinante en su investigación de agentes de larga duración: cuando los agentes perciben que el contexto se está agotando, exhiben un comportamiento de "convergencia prematura" — apresurándose a terminar el trabajo actual, saltando pasos de verificación o eligiendo una solución simple sobre la óptima. Es como darse cuenta de que se está acabando el tiempo en un examen y adivinar rápidamente las preguntas de opción múltiple restantes. Anthropic llama a esto "ansiedad de contexto."++## Flujo de continuidad entre sesiones++Sin artefactos de continuidad, cada nueva sesión es un desastre:++```mermaid+flowchart LR+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]+ End1 --> S2["Session 2 starts fresh"]+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]+```++Con artefactos de continuidad, las nuevas sesiones pueden retomar rápidamente:++```mermaid+flowchart LR+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]+ Work --> Verify["Verification notes<br/>which tests pass and fail"]+ Work --> Commit["Git checkpoint<br/>exact repo state"]++ Progress --> Rebuild["Session 2 rebuild"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["New session picks up quickly"]+```++## Conceptos clave++- **Las ventanas de contexto son finitas**: No importa qué tamaño de ventana se reclame (128K, 200K, 1M), las tareas largas eventualmente las agotarán. Tras el agotamiento, se requiere compaction (perdiendo información) o reset (nueva sesión). Ambas pierden algo.+- **Artefactos de continuidad**: Archivos de estado persistido que permiten a una nueva sesión retomar sin ambigüedad donde la anterior lo dejó. La forma básica: registro de progreso + registro de verificación + próximas acciones. Ese diario del artesano.+- **Costo de reconstrucción**: El tiempo que una nueva sesión necesita para alcanzar un estado ejecutable. Los buenos harness pueden comprimir el costo de reconstrucción de 15 minutos a 3 minutos.+- **Deriva (Drift)**: La brecha entre la comprensión del agente y el estado real del repositorio de código. Cada límite de sesión introduce deriva; sin control, se acumula.+- **Ansiedad de contexto**: Un fenómeno observado por Anthropic — los agentes exhiben un comportamiento de convergencia prematura cuando se acercan a los límites de contexto percibidos, terminando tareas temprano para evitar pérdida de información. Es una ansiedad irracional por los recursos.+- **Compaction vs reset**: La compaction resume el contexto dentro de la misma sesión (conserva el "qué," puede perder el "por qué"); el reset abre una nueva sesión reconstruyendo desde artefactos persistidos (limpio pero depende de la completitud de los artefactos).++## Qué sucede cuando se rompe la continuidad++La sesión anterior gastó un presupuesto significativo de contexto analizando tres enfoques y eligiendo la opción B. El agente de esta sesión no conoce ese análisis y podría volver a decidir basándose en información incompleta — potencialmente eligiendo la opción A. Como el artesano amnésico que no recuerda por qué se eligieron los ladrillos rojos, mira los azules hoy y piensa que son más bonitos, y derriba la pared de ayer para reconstruirla.++Peor aún es el trabajo duplicado. El agente no está seguro de si cierto trabajo ya fue completado y lo hace de nuevo. O peor — hace la mitad, descubre un conflicto con la implementación existente y tiene que rehacerlo. En un sitio de construcción, dos equipos no pueden construir la misma pared simultáneamente — pero sin registros de progreso, el nuevo equipo no tiene idea de que alguien ya está trabajando en ella.++A lo largo de varias sesiones, la dirección de implementación puede haberse desviado silenciosamente de los requisitos originales. Cada nueva sesión tiene una comprensión ligeramente diferente de los objetivos del proyecto. Como un juego de teléfono roto — después de que diez personas pasan el mensaje, "recógeme un café" podría convertirse "cómprame una cafetera."++También está la brecha de verificación. Los resultados de verificación de la sesión anterior (qué pruebas pasan, cuáles fallan, por qué fallan) no fueron registrados. La nueva sesión tiene que volver a ejecutar toda la verificación para entender el estado actual. Cada sesión vuelve a diagnosticar desde cero, desperdiciando contexto precioso cada vez.++Tanto OpenAI como Anthropic enfatizan la persistencia estructurada del estado en su documentación. El artículo de ingeniería de harness de OpenAI trata el repositorio como un "registro operativo" — los resultados de cada operación deberían dejar evidencia rastreable en el repositorio. La documentación de agentes de larga duración de Anthropic recomienda específicamente "handoff files" — documentos estructurados que contienen el estado actual, problemas conocidos y próximas acciones.++## Un diario para el artesano amnésico++Enfoque central: **Trata al agente como un ingeniero brillante con amnesia.** Antes de que "termine su turno," debe escribir información crítica para que el agente del siguiente "turno" pueda retomar rápidamente.++**Herramienta 1: Archivo de progreso (PROGRESS.md).** El artefacto de continuidad más básico — el núcleo del diario:++```markdown+# Project Progress++## Current State+- Latest commit: abc1234 (feat: add user preferences endpoint)+- Test status: 42/43 passing (test_pagination_edge_case failing)+- Lint: passing++## Completed+- [x] User model and database migration+- [x] Basic CRUD endpoints+- [x] Auth middleware integration++## In Progress+- [ ] Pagination feature (90% - edge case test failing)++## Known Issues+- test_pagination_edge_case returns 500 on empty result sets+- Need to confirm whether deleted users should appear in listings++## Next Steps+1. Fix pagination edge case bug+2. Add "include deleted users" query parameter+3. Update API documentation+```++**Herramienta 2: Registro de decisiones (DECISIONS.md).** Registra decisiones de diseño importantes y sus razones. No necesitas documentos de diseño detallados — solo "qué decisión, por qué, cuándo" — las notas en el diario:++```markdown+# Design Decisions++## 2024-01-15: Use Redis for user preferences caching+- Reason: High read frequency (every API call), small data size+- Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile)+- Constraint: Cache TTL of 5 minutes, active invalidation on write+```++**Herramienta 3: Commits de git como puntos de control.** Haz commit después de completar cada unidad atómica de trabajo. Los mensajes de commit deberían explicar qué se hizo y por qué. Estos son snapshots de estado gratuitos y automáticamente versionados.++**Herramienta 4: init.sh o flujo de inicialización del harness.** Especifica en `AGENTS.md` las rutinas de "entrada" y "salida":++```markdown+## At session start (clock in)+1. Read PROGRESS.md for current state+2. Read DECISIONS.md for important decisions+3. Run make check to confirm repo is in consistent state+4. Continue from PROGRESS.md "Next Steps" section++## Before session end (clock out)+1. Update PROGRESS.md+2. Run make check to confirm consistent state+3. Commit all completed work+```++**Estrategia mixta**: No todas las tareas necesitan un reset de contexto. Las tareas cortas (menos de 30 minutos) pueden completarse dentro de una sesión. Las tareas largas (que abarcan sesiones) deben usar archivos de progreso y registros de decisiones para la continuidad. Criterio de decisión: si una tarea necesita más del 60% de la ventana, comienza a preparar la entrega.++### Profundización en la ansiedad de contexto++La investigación de marzo de 2026 de Anthropic reveló además las manifestaciones específicas de la ansiedad de contexto: en Sonnet 4.5, cuando el contexto se acerca al límite de la ventana, el agente muestra un fuerte comportamiento de "convergencia prematura." Es como darse cuenta de que casi se acaba el tiempo en un examen y llenar rápidamente respuestas aleatorias en las opciones múltiples.++Dos estrategias abordan esto:++**Compaction**: Resumir la conversación temprana dentro de la misma sesión. Ventaja: mantiene la continuidad, el agente puede ver el "qué." Desventaja: el "por qué" se pierde a menudo en los resúmenes — por qué se eligió la opción B sobre la A, por qué se omitió una optimización particular. Más críticamente, la compaction no elimina la ansiedad de contexto — el agente sabe que el contexto fue grande alguna vez, y psicológicamente todavía tiende a apresurarse hacia el cierre.++**Reset de contexto**: Limpiar completamente el contexto, abrir una nueva sesión, reconstruir desde artefactos persistidos. Ventaja: estado mental limpio — la nueva sesión no tiene la ansiedad de "se me está acabando el tiempo." Desventaja: depende de la completitud de los artefactos de entrega. Si el diario falta información crítica, la nueva sesión puede perder tiempo yendo en la dirección equivocada.++Datos reales de Anthropic: para Sonnet 4.5, la ansiedad de contexto es lo suficientemente severa que la compaction por sí sola no es suficiente — el reset de contexto se convierte en un componente crítico del diseño del harness. Pero para Opus 4.5, este comportamiento está muy reducido, y la compaction puede gestionar el contexto sin depender de resets. Esto significa: **el diseño del harness necesita un entendimiento específico del modelo objetivo, no una plantilla de talla única.**++> Fuente: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## Ejemplo del mundo real++Un agente fue encargado de implementar un sistema de blog con autenticación de usuarios — 12 puntos de funcionalidad, estimadas 5 sesiones necesarias.++**Línea base sin el diario**: La sesión 1 implementó el modelo de usuario y las rutas básicas. La sesión 2 comenzó sin que el agente recordara el contrato de interfaz del middleware de autenticación, dedicando ~15 minutos a inferir la intención de diseño anterior. Para la sesión 3, la deriva acumulada hizo que el agente comenzara a reimplementar funcionalidades ya completadas. Para la sesión 5, el repositorio contenía mucho código redundante pero la funcionalidad central de autenticación todavía no había pasado las pruebas end-to-end. Solo 7 de 12 puntos de funcionalidad completados, 3 con problemas ocultos de corrección. Como el artesano que nunca escribe en su diario — para el día cinco, el sitio de construcción es un caos, algunas paredes construidas dos veces, algunas que debieron construirse nunca se empezaron.++**Con el diario**: Usando archivos de progreso, registros de decisiones, registros de verificación y puntos de control de git. El informe de estado se actualizó automáticamente al final de cada sesión. El costo de reconstrucción de la sesión 2 bajó a ~3 minutos. Para la sesión 5, los 12 puntos de funcionalidad fueron completados y verificados.++Comparación cuantitativa: tiempo de reconstrucción reducido ~78%, tasa de completitud de funcionalidades del 58% al 100%, tasa de defectos ocultos del 43% al 8%. El artesano sigue siendo amnésico, pero con el diario, cada día comienza donde el anterior se detuvo, no desde cero.++## Ideas clave++- Las ventanas de contexto son un recurso finito. Las tareas largas abarcarán sesiones, y las sesiones perderán información — como el artesano que olvida cada día, esto es una realidad objetiva.+- La solución no son ventanas más grandes — es mejor persistencia del estado. Archivos de progreso + registros de decisiones + puntos de control de git — dale al artesano amnésico un diario confiable.+- Trata al agente como un ingeniero con amnesia: antes de "terminar el turno," escribe qué se hizo, por qué y qué sigue.+- El costo de reconstrucción es la métrica clave. Los buenos harness deberían llevar a las nuevas sesiones a un estado ejecutable en menos de 3 minutos.+- Estrategia mixta: tareas cortas dentro de las sesiones, tareas largas con artefactos estructurados para la continuidad.++## Lecturas adicionales++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [Claude Code Documentation](https://docs.anthropic.com/es/docs/claude-code)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)++## Ejercicios++1. **Medición de pérdida de continuidad**: Elige una tarea de desarrollo que necesite al menos 3 sesiones. Sin proporcionar ningún artefacto de continuidad, registra al inicio de cada sesión cuánto contexto gasta el agente en "averiguar qué pasó la última vez." Después de cada sesión, crea un archivo de progreso y deja que la siguiente sesión comience desde él. Compara los costos de reconstrucción con y sin archivos de progreso.++2. **Diseño de plantilla de entrega**: Diseña una plantilla de entrega mínima con cuatro campos: estado del repositorio (commit hash), estado de ejecución (tasa de aprobación de pruebas), bloqueadores, próximas acciones. Deja que una sesión de agente completamente nueva restaure el estado del proyecto usando solo esta plantilla. Registra las ambigüedades encontradas durante la restauración, itera para mejorar la plantilla.++3. **Experimento de estrategia mixta**: En una tarea de desarrollo de 5 sesiones, compara tres estrategias: (a) siempre iniciar sesiones nuevas + archivos de progreso, (b) hacer lo más posible en una sesión (compaction de contexto), (c) estrategia mixta (tareas cortas dentro de la sesión, tareas largas entre sesiones + archivos de progreso). Compara tiempo de reconstrucción, tasa de completitud de funcionalidades y consistencia de decisiones.diff --git a/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdnew file mode 100644index 0000000..1a1f054--- /dev/null+++ b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 06++Usa esta carpeta para ejemplos de:++- salidas del inicializador+- scripts de inicialización+- archivos de progreso+- scaffolding de primera ejecucióndiff --git a/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.tsnew file mode 100644index 0000000..52dcd98--- /dev/null+++ b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts@@ -0,0 +1,296 @@+/**+ * init-check.ts+ *+ * Programmatically checks initialization prerequisites:+ * - Node.js version+ * - Dependencies installed (node_modules exists)+ * - Data directory exists+ * - Config files present+ *+ * Simulates running with and without an explicit init phase,+ * showing how missing prerequisites cause silent failures later.+ *+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";+import * as childProcess from "node:child_process";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface CheckItem {+ name: string;+ category: string;+ check: () => { pass: boolean; detail: string };+ impactIfMissing: string;+}++interface CheckResult {+ name: string;+ category: string;+ passed: boolean;+ detail: string;+ impactIfMissing: string;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++function createChecks(targetDir: string): CheckItem[] {+ return [+ {+ name: "Node.js version >= 18",+ category: "Runtime",+ check: () => {+ try {+ const version = process.version; // e.g. "v20.11.0"+ const major = parseInt(version.replace("v", "").split(".")[0], 10);+ return {+ pass: major >= 18,+ detail: `Detected: ${version} (need >= v18)`,+ };+ } catch {+ return { pass: false, detail: "Could not detect Node.js version" };+ }+ },+ impactIfMissing: "TypeScript features and built-in APIs unavailable",+ },+ {+ name: "package.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "package.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found in target directory",+ };+ },+ impactIfMissing: "Cannot install dependencies or run scripts",+ },+ {+ name: "Dependencies installed (node_modules)",+ category: "Dependencies",+ check: () => {+ const p = path.join(targetDir, "node_modules");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",+ };+ },+ impactIfMissing: "All imports fail at runtime",+ },+ {+ name: "TypeScript available",+ category: "Toolchain",+ check: () => {+ try {+ const result = childProcess.execSync("npx tsc --version", {+ encoding: "utf-8",+ timeout: 10000,+ stdio: ["pipe", "pipe", "pipe"],+ }).trim();+ return { pass: true, detail: `Detected: ${result}` };+ } catch {+ return { pass: false, detail: "TypeScript not available via npx" };+ }+ },+ impactIfMissing: "Cannot compile TypeScript files",+ },+ {+ name: "tsconfig.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "tsconfig.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found",+ };+ },+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",+ },+ {+ name: "Source directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["src", "lib", "app"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",+ };+ },+ impactIfMissing: "Agent cannot locate source files to modify",+ },+ {+ name: "Test directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["test", "tests", "__tests__", "spec"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",+ };+ },+ impactIfMissing: "Agent cannot find or run existing tests",+ },+ {+ name: "Git repository initialized",+ category: "Version Control",+ check: () => {+ const gitDir = path.join(targetDir, ".git");+ const exists = fs.existsSync(gitDir);+ return {+ pass: exists,+ detail: exists ? "Git repository detected" : "No .git directory found",+ };+ },+ impactIfMissing: "No rollback capability, no change history",+ },+ ];+}++// ---------------------------------------------------------------------------+// Simulation: with and without init phase+// ---------------------------------------------------------------------------++interface SimResult {+ scenario: string;+ checksRun: boolean;+ failuresBeforeWork: number;+ workAttempted: boolean;+ workSucceeded: boolean;+ timeWastedMs: number;+}++function simulateWithoutInit(): SimResult {+ // Agent skips init, goes straight to work.+ // Encounters failures one at a time as it hits missing prerequisites.+ const checks = createChecks(process.cwd());+ let failures = 0;+ let timeWasted = 0;++ for (const check of checks) {+ const result = check.check();+ if (!result.pass) {+ failures++;+ timeWasted += 200; // Agent spends time discovering each missing piece+ }+ }++ return {+ scenario: "NO INIT PHASE",+ checksRun: false,+ failuresBeforeWork: 0, // Didn't check upfront+ workAttempted: true,+ workSucceeded: failures === 0,+ timeWastedMs: timeWasted,+ };+}++function simulateWithInit(): SimResult {+ // Agent runs init phase first, discovers all issues upfront.+ const checks = createChecks(process.cwd());+ let failures = 0;++ for (const check of checks) {+ if (!check.check().pass) {+ failures++;+ }+ }++ return {+ scenario: "WITH INIT PHASE",+ checksRun: true,+ failuresBeforeWork: failures,+ workAttempted: failures === 0,+ workSucceeded: failures === 0,+ timeWastedMs: 0,+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.cwd();+ console.log("\n" + "=".repeat(80));+ console.log(" INITIALIZATION PREREQUISITE CHECK");+ console.log("=".repeat(80));+ console.log(` Target: ${targetDir}\n`);++ const checks = createChecks(targetDir);+ const results: CheckResult[] = checks.map((c) => {+ const r = c.check();+ return {+ name: c.name,+ category: c.category,+ passed: r.pass,+ detail: r.detail,+ impactIfMissing: c.impactIfMissing,+ };+ });++ // Detailed report+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const status = r.passed ? "PASS" : "FAIL";+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);+ }++ const passCount = results.filter((r) => r.passed).length;+ const failCount = results.filter((r) => !r.passed).length;++ console.log("\n" + "-".repeat(80));+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);++ if (failCount > 0) {+ console.log("\n FAILED CHECKS -- Impact if not resolved:");+ for (const r of results.filter((r) => !r.passed)) {+ console.log(` - ${r.name}: ${r.impactIfMissing}`);+ }+ }++ // Comparison: with vs without init+ const noInit = simulateWithoutInit();+ const withInit = simulateWithInit();++ console.log("\n" + "=".repeat(80));+ console.log(" INIT PHASE COMPARISON");+ console.log("=".repeat(80) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);++ console.log("\n An explicit init phase catches problems before they waste time.\n");+}++run();diff --git a/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.shnew file mode 100644index 0000000..2c6e1b0--- /dev/null+++ b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh@@ -0,0 +1,10 @@+#!/usr/bin/env bash+set -euo pipefail++echo "[init] installing dependencies"+npm install++echo "[init] starting the docs site is optional"+echo "[init] use npm run docs:dev for course docs"++echo "[init] project-specific startup would go here"diff --git a/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.mdnew file mode 100644index 0000000..063ab25--- /dev/null+++ b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md@@ -0,0 +1,7 @@+# Lista de Verificación de Salida del Inicializador++- ¿Hay un comando de inicio canónico?+- ¿Hay un comando de verificación canónico?+- ¿Hay un primer artefacto de progreso?+- ¿Hay un primer commit estable?+- ¿Hay una superficie de features visible para sesiones posteriores?diff --git a/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdnew file mode 100644index 0000000..b1a221c--- /dev/null+++ b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -0,0 +1,157 @@+[中文版本 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)+> Proyecto práctico: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# Lección 06. Inicializa antes de cada sesión del agente++Inicias una nueva sesión de agente y dices "añade una funcionalidad de búsqueda." Salta directamente a codificar — un entusiasmo admirable. Después de 20 minutos descubre que el framework de pruebas no está configurado correctamente, dedica otros 10 a arreglar eso, luego el formato del script de migración de base de datos está mal, más ajustes. La funcionalidad de búsqueda eventualmente se añade, pero toda la sesión fue ineficiente — la mayor parte del tiempo se fue en "averiguar cómo funciona este proyecto" en lugar de escribir la funcionalidad de búsqueda.++El mejor enfoque: antes de dejar que el agente comience a trabajar, usa una fase separada para preparar el entorno base, hacer pasar los comandos de verificación y entender la estructura del proyecto. Es como construir una casa — no viertes los cimientos y levantas paredes simultáneamente. Si lo haces, las paredes se levantan antes de que los cimientos hayan curado, y todo el edificio tiene que ser demolido y empezado de nuevo. Vierte los cimientos primero, deja que curen, luego construye las paredes — limpio y eficiente.++Esta lección explica por qué la inicialización debe ser una fase separada, no mezclada con la implementación.++## Cimientos y paredes: dos trabajos fundamentalmente diferentes++La inicialización y la implementación tienen objetivos de optimización completamente diferentes. La fase de implementación optimiza para: maximizar la cantidad y calidad de las funcionalidades verificadas. La fase de inicialización optimiza para: maximizar la fiabilidad y eficiencia de toda la implementación posterior.++Cuando mezclas inicialización e implementación, el agente enfrenta un problema de optimización multi-objetivo — construir infraestructura simultáneamente y escribir código de funcionalidades. Sin una priorización explícita, el agente naturalmente tiende a escribir código (porque eso es una salida directamente visible) mientras sacrifica la infraestructura (porque su valor solo se muestra en sesiones posteriores). Es como decirle a un equipo de construcción que simultáneamente vierta los cimientos y construya las paredes — probablemente se apresurarán a construir paredes porque las paredes son visibles y demostrables. Pero una casa con cimientos defectuosos tiene problemas sistémicos a largo plazo.++## Ciclo de vida de la inicialización++```mermaid+flowchart TB+ subgraph Wrong["Mixed session (wrong)"]+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]+ W2 --> W3["Accumulate unverified code"]+ W3 --> W4["Next session must rediscover project state"]+ end++ subgraph Right["Dedicated initialization (right)"]+ R1["Session 1: environment runnable"] --> R2["Example test passing"]+ R2 --> R3["Bootstrap contract + task list written"]+ R3 --> R4["Clean checkpoint committed"]+ R4 --> R5["Later sessions start directly on verified tasks"]+ end+```++## Qué sucede cuando los mezclas++El problema más directo: los cimientos no se asientan correctamente. El agente gasta el 80% de su esfuerzo en código de funcionalidades y el 20% configurando casualmente algo de infraestructura. El framework de pruebas está configurado pero nunca verificado, las reglas de lint están establecidas pero demasiado laxas, no se creó ningún archivo de progreso. Estos defectos no son obvios en la primera sesión (porque el agente todavía recuerda lo que hizo), pero salen a la luz en la segunda sesión — el nuevo agente no sabe cómo ejecutar, probar o en qué punto están las cosas. Cimientos chapuceros, edificio inestable.++Un costo más oculto es la "acumulación no verificada" — el código de funcionalidades escrito antes de que el framework de pruebas esté configurado es código sin verificación. Cuando finalmente vuelves para añadir pruebas a ese código, podrías descubrir que el diseño estaba mal desde el principio — si lo hubieras sabido, lo habrías implementado de manera diferente. Como colocar baldosas sobre hormigón húmedo — cuando descubres que el suelo no está nivelado, todas las baldosas tienen que ser levantadas y rehechas.++El presupuesto de sesión también se está desperdiciando. El trabajo de inicialización (configurar entornos, preparar pruebas, entender la estructura del proyecto) consume un presupuesto significativo, dejando menos para la implementación real de funcionalidades. Resultado: la primera sesión solo completa la mitad de las funcionalidades, y la segunda sesión tiene que empezar de nuevo a entender el proyecto. Presupuesto gastado en los cimientos, pero los cimientos tampoco están sólidos — ningún objetivo cumplido.++El problema más fácilmente pasado por alto son las minas de suposiciones implícitas. Las decisiones que el agente toma durante la inicialización (qué framework de pruebas, cómo organizar directorios, gestión de dependencias) — si no se registran explícitamente, las sesiones posteriores no pueden entender estas decisiones. Peor aún, las sesiones posteriores podrían tomar decisiones contradictorias. El primer equipo de construcción usó cimientos de hormigón, el segundo equipo no lo sabe y clavó pilotes de madera en ellos — los cimientos se agrietan.++La investigación de Anthropic sobre desarrollo de aplicaciones de larga duración recomienda explícitamente separar la inicialización de la implementación. Sus datos experimentales: los proyectos que usan una fase de inicialización dedicada mostraron un 31% más de tasa de completitud de funcionalidades en escenarios de múltiples sesiones comparado con enfoques mixtos. La perspectiva clave — el tiempo invertido en la fase de inicialización se recupera completamente en las siguientes 3-4 sesiones. Cuanto más sólidos los cimientos, más rápido se levantan las paredes.++La guía de ingeniería de harness de Codex de OpenAI también enfatiza el principio del "repositorio como registro operativo" — establece una estructura operativa clara desde la primera ejecución, o cada nueva sesión tendrá que re-inferir las convenciones del proyecto.++## Conceptos clave++- **Fase de inicialización**: La primera fase en el ciclo de vida del agente — sin implementación de funcionalidades, solo estableciendo los prerrequisitos para todas las fases de implementación posteriores. La salida no es código, es infraestructura.+- **Contrato de bootstrap**: Las condiciones bajo las cuales un proyecto puede ser operado sin ambigüedad por una nueva sesión de agente — puede iniciar, puede probar, puede ver el progreso, puede retomar los siguientes pasos. Cuatro condiciones, todas requeridas.+- **Arranque en frío vs arranque en caliente**: El arranque en frío es desde un directorio vacío donde el agente debe adivinar la estructura del proyecto; el arranque en caliente es desde una plantilla o proyecto existente donde la infraestructura ya está en su lugar. El arranque en caliente supera ampliamente al arranque en frío — como empezar a trabajar en un sitio con agua corriente y electricidad versus comenzar desde un terreno baldío.+- **Preparación para entrega**: El proyecto está en un estado en cualquier momento dado donde un agente nuevo puede tomar el control. No se necesita explicación verbal — solo el contenido del repositorio.+- **Tiempo hasta la primera verificación**: El tiempo desde el inicio del proyecto hasta que el primer punto de funcionalidad pasa la verificación. Esta es la métrica central para medir la eficiencia de inicialización.+- **Usabilidad posterior**: La mejor medida de la calidad de la inicialización — la proporción de sesiones posteriores que pueden ejecutar tareas exitosamente sin depender de conocimiento implícito.++## Cómo hacer bien la inicialización++**Trata la inicialización como una fase dedicada.** La primera sesión solo hace inicialización — nada de código de funcionalidades de negocio. La inicialización produce:++**1. Entorno ejecutable.** El proyecto arranca, las dependencias están instaladas, sin problemas de entorno. Cimientos vertidos, sin grietas.++**2. Framework de pruebas verificable.** Al menos una prueba de ejemplo pasa. Esto demuestra que el framework de pruebas en sí está correctamente configurado — como poner un pilar sobre los cimientos para demostrar que puede soportar peso.++**3. Documento de contrato de bootstrap.** Un documento claro que indica a las sesiones posteriores:+```markdown+# Initialization Contract++## Start Commands+- Install dependencies: `make setup`+- Start dev server: `make dev`+- Run tests: `make test`+- Full verification: `make check`++## Current State+- All dependencies installed and locked+- Test framework configured (Vitest + React Testing Library)+- Example test passing (1/1)+- Lint rules configured (ESLint + Prettier)++## Project Structure+- src/ — Source code+- src/components/ — React components+- src/api/ — API client+- tests/ — Test files+```++**4. Desglose de tareas.** Divide todo el proyecto en una lista ordenada de tareas, cada una con criterios de aceptación claros:+```markdown+# Task Breakdown++## Task 1: User Authentication Basics+- Implement JWT auth middleware+- Add login/register endpoints+- Acceptance: pytest tests/test_auth.py all passing++## Task 2: User Profile Page+- Implement user profile CRUD+- Add profile edit form+- Acceptance: pytest tests/test_profile.py all passing++## Task 3: Search Feature+- ...+```++**5. Commit de git como punto de control.** Después de que se completa la inicialización, haz commit de un punto de control limpio. Todo el trabajo posterior comienza desde este punto de control.++**Estrategia de arranque en caliente**: No comiences desde un directorio vacío. Usa una plantilla de proyecto (create-react-app, fastapi-template, etc.) para preestablecer la estructura de directorios estándar, la configuración de dependencias y el framework de pruebas. Integra los pasos comunes de inicialización en la plantilla, dejando solo el trabajo de inicialización específico del proyecto. Como empezar a trabajar en un sitio con agua corriente y electricidad — diez mil veces mejor que comenzar desde un terreno baldío.++**Criterios de finalización de inicialización**: No "cuánto código se escribió," sino si se cumplen las cuatro condiciones del contrato de bootstrap — puede iniciar, puede probar, puede ver el progreso, puede retomar los siguientes pasos. Usa esta lista de verificación para validar la inicialización:++```markdown+## Initialization Acceptance Checklist+- [ ] `make setup` succeeds from scratch+- [ ] `make test` has at least one passing test+- [ ] A new agent session can answer "how to run" and "how to test" from repo contents alone+- [ ] Task breakdown file exists with at least 3 tasks+- [ ] Everything committed to git+```++## Ejemplo del mundo real++Dos enfoques de inicialización para un proyecto frontend de React:++**Enfoque mixto (verter cimientos y construir paredes simultáneamente)**: El agente simultáneamente creó el scaffolding del proyecto e implementó la primera funcionalidad en la sesión 1. Al final de la sesión, el repositorio tenía código ejecutable pero: sin documentación explícita de comandos de inicio/prueba, sin archivo de seguimiento de progreso, sin desglose de tareas. La sesión 2 dedicó ~20 minutos a inferir la estructura del proyecto, el framework de pruebas y el proceso de construcción — como un nuevo equipo de construcción que llega a un sitio sin saber cuánto avanzaron los cimientos o dónde van las tuberías, teniendo que cavar agujeros uno por uno para averiguarlo.++**Inicialización dedicada (cimientos primero)**: La sesión 1 solo hizo inicialización — creó la estructura de directorios desde una plantilla, configuró el framework de pruebas (Vitest + React Testing Library), escribió y verificó una prueba de ejemplo, creó el documento de contrato de bootstrap y el archivo de desglose de tareas, hizo commit del punto de control inicial. El tiempo de reconstrucción de la sesión 2 fue menos de 3 minutos, y comenzó a trabajar directamente desde la lista de tareas — el equipo llega, echa un vistazo al plano y sabe exactamente dónde retomar.++Comparación del ciclo completo del proyecto: el tiempo total de reconstrucción del enfoque mixto (a través de todas las sesiones) fue ~60% más que el enfoque de inicialización dedicada. Los 20 minutos extra gastados en inicialización fueron recuperados muchas veces en las sesiones posteriores. Como cimientos sólidos haciendo que las paredes se levanten más rápido — lento es rápido.++## Ideas clave++- La inicialización y la implementación tienen diferentes objetivos de optimización — mezclarlas solo arrastra a ambas hacia abajo. Vierte los cimientos primero, luego construye las paredes.+- La salida de la inicialización no es código, es infraestructura: entorno ejecutable, pruebas verificables, contrato de bootstrap, desglose de tareas.+- Valida la inicialización con las cuatro condiciones del contrato de bootstrap: puede iniciar, puede probar, puede ver el progreso, puede retomar los siguientes pasos.+- El arranque en caliente supera al arranque en frío. Usa plantillas de proyecto para preestablecer infraestructura estandarizada.+- El tiempo invertido en inicialización se recupera completamente en las siguientes 3-4 sesiones. Esto no es un costo extra — es una inversión inicial. Cuanto más sólidos los cimientos, más rápido se levanta el edificio.++## Lecturas adicionales++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)++## Ejercicios++1. **Diseño de contrato de bootstrap**: Escribe un contrato de bootstrap completo para un proyecto que estés desarrollando. Luego abre una sesión de agente completamente nueva, muéstrale solo el contenido del repositorio (sin contexto verbal), y haz que intente iniciar el proyecto, ejecutar las pruebas y entender el progreso actual. Registra cada problema que encuentre — cada uno corresponde a una cláusula faltante en tu contrato de bootstrap.++2. **Experimento comparativo**: Elige un proyecto nuevo de complejidad moderada. Enfoque A: deja que el agente inicialice y haga la primera implementación simultáneamente. Enfoque B: dedica una sesión a la inicialización, comienza la implementación en la sesión 2. Después de 4 sesiones, compara: tiempo hasta la primera verificación, costo de reconstrucción, tasa de completitud de funcionalidades.++3. **Lista de verificación de aceptación de inicialización**: Diseña una lista de verificación de aceptación de inicialización para tu proyecto. Haz que una sesión de agente nueva ejecute cada elemento de la lista y registra cuáles pasan y cuáles fallan. Los elementos que fallan son donde tu harness necesita fortalecerse.diff --git a/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdnew file mode 100644index 0000000..b5ca566--- /dev/null+++ b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 07++Usa esta carpeta para ejemplos de:++- fallos de un solo intento+- prompts de tareas sobredimensionadas+- conformación incremental de tareas+- superficies de features estructuradasdiff --git a/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.mdnew file mode 100644index 0000000..d45c563--- /dev/null+++ b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md@@ -0,0 +1,6 @@+# Plantilla de Siguiente Tarea++- Feature actual de mayor prioridad:+- Por qué este feature es el siguiente:+- Qué cuenta como aprobado:+- Qué no debe cambiarse durante este paso:diff --git a/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdnew file mode 100644index 0000000..0055b45--- /dev/null+++ b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -0,0 +1,17 @@+# Ejemplo de Superficie de Alcance++Tarea:++- Añadir indexación a la app de conocimiento Electron++Forma de alcance mala:++- "Implementar indexación"++Forma de alcance mejor:++- Analizar documentos importados+- Dividir documentos en fragmentos+- Persistir metadatos de fragmentos+- Mostrar estado de indexación en la UI+- Añadir una acción de reindexacióndiff --git a/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.tsnew file mode 100644index 0000000..c587a1d--- /dev/null+++ b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts@@ -0,0 +1,151 @@+/**+ * scope-tracker.ts+ *+ * Reads a feature list and a change log. Enforces single-active-feature+ * policy. Given a log of changes, flags any changes outside the active+ * feature scope. Demonstrates how scope drift happens and how the tracker+ * catches it.+ *+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Feature {+ id: string;+ name: string;+ status: "active" | "pending" | "done";+}++interface ChangeLogEntry {+ step: number;+ file: string;+ description: string;+ featureId: string; // The feature this change claims to belong to+}++// ---------------------------------------------------------------------------+// Sample data+// ---------------------------------------------------------------------------++const features: Feature[] = [+ { id: "F-001", name: "Search endpoint", status: "active" },+ { id: "F-002", name: "Delete endpoint", status: "pending" },+ { id: "F-003", name: "Rate limiting", status: "pending" },+ { id: "F-004", name: "User dashboard", status: "pending" },+];++// A realistic change log where the agent gradually drifts from the active feature+const changeLog: ChangeLogEntry[] = [+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },+];++// ---------------------------------------------------------------------------+// Scope tracker+// ---------------------------------------------------------------------------++interface ScopeCheckResult {+ step: number;+ file: string;+ description: string;+ featureId: string;+ inScope: boolean;+ activeFeature: string;+}++function trackScope(+ featureList: Feature[],+ changes: ChangeLogEntry[]+): ScopeCheckResult[] {+ const activeFeatures = featureList.filter((f) => f.status === "active");+ const activeIds = new Set(activeFeatures.map((f) => f.id));+ const activeNames = activeFeatures.map((f) => f.name).join(", ");++ return changes.map((change) => ({+ step: change.step,+ file: change.file,+ description: change.description,+ featureId: change.featureId,+ inScope: activeIds.has(change.featureId),+ activeFeature: activeNames,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const results = trackScope(features, changeLog);++ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");+ console.log("=".repeat(100));++ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));++ // Detailed change log+ console.log("\n" + "-".repeat(100));+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;+ console.log(header);+ console.log(sep);++ let inScopeCount = 0;+ let driftCount = 0;++ for (const r of results) {+ const scopeLabel = r.inScope ? "OK" : "DRIFT";+ if (r.inScope) inScopeCount++;+ else driftCount++;++ const marker = r.inScope ? " " : ">>";+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE DRIFT SUMMARY");+ console.log("=".repeat(100) + "\n");++ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;+ console.log(sHeader);+ console.log(sSep);+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);++ // Drift detail+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];+ if (driftFeatures.length > 0) {+ console.log("\n DRIFTED FEATURES:");+ for (const fid of driftFeatures) {+ const feat = features.find((f) => f.id === fid);+ const driftChanges = results.filter((r) => r.featureId === fid);+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);+ }+ }++ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");+}++run();diff --git a/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdnew file mode 100644index 0000000..b8139ea--- /dev/null+++ b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -0,0 +1,134 @@+[中文版本 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)+> Proyecto práctico: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)++# Lección 07. Define límites claros para las tareas del agente++Le dices a Claude Code que "añada autenticación de usuarios a este proyecto," y comienza a modificar el esquema de la base de datos, escribir rutas, cambiar componentes del frontend y — de paso — refactorizar el middleware de manejo de errores. Dos horas después verificas: 12 archivos modificados, 800 líneas de código nuevo, y ni una sola funcionalidad funciona end-to-end.++Morder más de lo que puedes masticar — este dicho se aplica a los agentes de IA especialmente bien. Los agentes nacen con un impulso de "hacer un poco más" — ven cosas relacionadas y simplemente las manejan de paso, como alguien que va al supermercado por una botella de salsa de soya y sale empujando un carrito lleno. El problema es, los humanos que compran demasiado solo desperdician dinero; los agentes haciendo demasiadas cosas simultáneamente significa que ninguna se hace bien.++El blog de ingeniería de Anthropic "Effective harnesses for long-running agents" establece claramente: cuando los prompts son demasiado amplios, los agentes tienden a "comenzar múltiples cosas a la vez" en lugar de "terminar una cosa primero." Las prácticas de ingeniería de Codex de OpenAI encontraron lo mismo — las tareas sin controles explícitos de alcance ven las tasas de completitud desplomarse. Este no es un problema del modelo — es un problema del harness. No trazaste el límite.++## La atención es un recurso finito++Esto no es una metáfora — es matemática. Supón que la capacidad de contexto del agente es C y activa k tareas simultáneamente. Cada tarea recibe un promedio de C/k recursos de razonamiento. Cuando C/k cae por debajo del umbral mínimo necesario para completar una sola tarea, ninguna se termina. Tu estómago solo tiene cierto tamaño — mete diez dumplings de una vez y no los digerirás todos, solo tendrás diez casos de indigestión.++El comportamiento real de Claude Code es revelador. Pídele que "añada registro de usuarios" y podría:++1. Crear un modelo de User+2. Escribir la ruta de registro+3. Notar que necesita verificación de email, así que añadir un servicio de correo+4. Ver que las contraseñas necesitan hashing, así que incorporar bcrypt+5. Notar que el manejo de errores es inconsistente, así que refactorizar el middleware de errores global+6. Ver que la estructura de archivos de prueba está desordenada, así que reorganizar el directorio++Seis pasos después, cada uno está a medio hacer. Sin verificación end-to-end, acoplamiento complejo entre el código a medio cocinar, y la siguiente sesión que tenga que recoger los pedazos estará completamente perdida. Como alguien cocinando seis platos simultáneamente — cada plato está en la sartén pero ninguno ha sido emplatado. Todos se queman.++Los datos experimentales de Anthropic apoyan esto directamente: los agentes que usan una estrategia de "pequeño siguiente paso" (equivalente a WIP=1) muestran un 37% más de tasa de completitud de tareas que los agentes que usan prompts amplios. Más interesante aún, el número de líneas de código generadas por los agentes está débilmente correlacionado negativamente con la completitud real de funcionalidades — más código escrito, menos funcionalidades completadas. Morder más de lo que puedes masticar, comprobado con datos.++## Flujo de trabajo WIP=1++```mermaid+flowchart LR+ Queue["Feature queue"] --> Pick["Pick exactly one task"]+ Pick --> Active["Only one active item"]+ Active --> Verify["Run end-to-end verification"]+ Verify -->|pass| Commit["Commit and unlock next task"]+ Verify -->|fail| Active+ Commit --> Queue+```++```mermaid+flowchart TB+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]+ Budget --> Many["WIP = 5<br/>C / 5 per task"]++ One --> Finish["One feature reaches passing state"]+ Many --> Partial["Five partial implementations"]+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]+```++## Conceptos clave++- **Sobrealcance (Overreach)**: El agente activa más tareas en una sola sesión de lo óptimo. Es cuantificable — hacer 5 funcionalidades con 0 pasando end-to-end es sobrealcance.+- **Sub-completitud (Under-finish)**: La proporción de tareas que pasan verificación end-to-end, de todas las tareas activadas, cae por debajo del umbral. Código escrito pero pruebas sin pasar es sub-completitud.+- **Límite WIP (Work-in-Progress Limit)**: De la metodología Kanban. Idea central: limitar cuántas tareas están en progreso a la vez. Para agentes, WIP=1 es el valor predeterminado más seguro — termina una antes de comenzar la siguiente. Como un buffet — no llenes tu plato, termina un plato y luego vuelve por el siguiente.+- **Evidencia de completitud**: La condición verificable que una tarea debe satisfacer para pasar de "en progreso" a "terminada." Sin esto, los agentes sustituyen "el código se ve bien" por "el comportamiento pasa las pruebas."+- **Superficie de alcance (Scope Surface)**: Una estructura DAG donde cada nodo es una unidad de trabajo y las aristas son dependencias. Los estados se limitan a cuatro: not_started, active, blocked, passing.+- **Presión de completitud**: La fuerza restrictiva que el harness ejerce a través de límites WIP y requisitos de evidencia de completitud, forzando al agente a terminar la tarea actual antes de comenzar una nueva.++## El sobrealcance y la sub-completitud son simbióticos++Estos dos problemas no son independientes — se amplifican mutuamente. El sobrealcance diluye la atención, la atención diluida causa sub-completitud, y el código a medio terminar que queda aumenta la complejidad del sistema, lo que a su vez impulsa más sobrealcance en la siguiente tarea. Un ciclo vicioso.++En términos de Kanban: la Ley de Little nos dice L = lambda * W. Si el trabajo en progreso L es demasiado alto (haciendo demasiadas cosas a la vez), el tiempo de entrega W para cada tarea inevitablemente aumenta. Para los agentes, esto significa que cada funcionalidad tarda más desde el inicio hasta la completitud verificada, y la probabilidad de fallo crece.++Este es un problema antiguo en el mundo humano también — Steve McConnell documentó en *Rapid Development* que el scope creep es la principal causa de fracaso de proyectos. Pero los humanos al menos tienen la intuición de "ya he hecho suficiente." Los agentes no tienen ninguna. Generar la siguiente idea le cuesta al modelo casi nada en tokens extra — escribir "déjame arreglar esto también mientras estoy aquí" apenas se nota — pero cada modificación adicional diluye la atención del agente. Como un buffet donde cada plato extra tiene un costo marginal cercano a cero, pero tu estómago solo tiene cierta capacidad.++## Cómo hacerlo bien++### 1. Haz cumplir WIP=1++Este es el método más directo y efectivo. En tu harness, dile al agente explícitamente: **solo una tarea tiene permitido estar en estado "active" en cualquier momento.** En el CLAUDE.md de Claude Code o el AGENTS.md de Codex, escribe:++```+## Work Rules+- Work on one feature at a time+- Only start the next feature after the current one passes end-to-end verification+- Don't "also refactor" feature B while implementing feature A+```++Como comer en un buffet — un plato a la vez, termínalo antes de volver por más.++### 2. Define evidencia de completitud explícita para cada tarea++Terminado no es "el código está escrito" — es "la verificación del comportamiento pasa." En tu feature list, cada entrada necesita un comando de verificación:++```+F01: User Registration+ Verification: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201+ State: passing+```++### 3. Externaliza la superficie de alcance++Usa un archivo legible por máquina (JSON o Markdown) para registrar todos los estados de las tareas. Cualquier nueva sesión puede leer este archivo y saber inmediatamente: ¿qué tarea está activa? ¿Qué comportamiento cuenta como terminado? ¿Qué verificaciones han pasado?++### 4. Monitorea la tasa de completitud verificada++El harness debería rastrear continuamente el VCR (Verified Completion Rate) = tareas verificadas / tareas activadas. Bloquea nuevas activaciones de tareas cuando VCR < 1.0.++## Caso del mundo real++Un proyecto de API REST con 8 funcionalidades, se compararon dos estrategias:++**Modo buffet (sin restricciones)**: El agente activa 5 funcionalidades simultáneamente en la sesión 1. Produce ~800 líneas en 12 archivos. Tasa de aprobación de pruebas end-to-end: 20% — solo el registro de usuarios funciona. Las otras 4 funcionalidades: esquema de base de datos creado pero falta lógica de validación, rutas definidas pero devolviendo formatos de respuesta incorrectos. Como alguien cocinando seis platos a la vez, solo uno es apenas comestible. Al final de la sesión 3, solo 3 de 8 funcionalidades completadas.++**Modo plato único (WIP=1)**: El agente trabaja solo en el registro de usuarios en la sesión 1. Produce ~200 líneas en 4 archivos. Pruebas end-to-end: 100% pasando. Hace commit de una implementación limpia y verificada. Al final de la sesión 4, 7 de 8 funcionalidades completadas (la 8va bloqueada por una dependencia externa).++Resultado: menos código total (800 vs 1200 líneas) pero más código efectivo. Tasa de completitud: 87.5% vs 37.5%. Toma un bocado a la vez, y realmente comes más.++## Ideas clave++- **WIP=1 es la configuración predeterminada segura para harness de agentes** — termina una, luego comienza la siguiente; no intentes paralelizar. No te puedes poner gordo en un bocado.+- **La evidencia de completitud debe ser ejecutable** — "el código se ve bien" no cuenta; "curl devuelve 201" sí.+- **La superficie de alcance debe externalizarse como archivo** — no solo mencionada en la conversación, sino registrada en un formato legible por máquina en el repositorio.+- **El sobrealcance y la sub-completitud son simbióticos** — resolver uno resuelve el otro.+- **"Haz menos pero termina" siempre vence a "haz más pero deja a medias"** — las líneas de código del agente y la tasa de completitud de funcionalidades están negativamente correlacionadas. La calidad siempre vence a la cantidad.++## Lecturas adicionales++- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Blog de ingeniería de Anthropic, discusión detallada de la estrategia de "pequeño siguiente paso"+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Tratamiento completo de ingeniería de harness de OpenAI+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — La fuente clásica sobre límites WIP+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — Datos empíricos sobre el scope creep como principal causa de fracaso de proyectos++## Ejercicios++1. **Atomización de tareas**: Toma un requisito amplio (por ejemplo, "implementa un sistema de gestión de usuarios") y divídelo en al menos 5 unidades de trabajo atómicas. Para cada unidad, especifica: (a) una descripción de comportamiento única, (b) un comando de verificación ejecutable, (c) dependencias. Verifica si la descomposición satisface la restricción WIP=1.++2. **Experimento comparativo**: Ejecuta el mismo proyecto dos veces — una sin restricciones, otra con WIP=1 impuesto. Compara: tasa de completitud verificada, líneas totales de código, ratio de código efectivo.++3. **Auditoría de evidencia de completitud**: Revisa la salida de una ejecución reciente de un agente, clasificando cada cambio de código como "comportamiento completado," "comportamiento incompleto" o "scaffolding." Añade los comandos de verificación faltantes para cada comportamiento incompleto.diff --git a/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..52d6a2b--- /dev/null+++ b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,218 @@+/**+ * feature-list-validator.ts+ *+ * Reads a feature_list.json, validates its schema, and checks for features+ * marked "pass" without verification evidence. Outputs a structured report.+ * Can run against any project directory that has a feature_list.json.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]+ * (defaults to the directory containing this script)+ *+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Allow unknown fields for flexibility+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Schema validation+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entry ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Missing or invalid 'id' field`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Missing or invalid 'category' field`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Missing or invalid 'description' field`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' must be an array if present`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' must be a boolean if present`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Evidence validation+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Process feature list+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve target directory+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);+ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" FEATURE LIST VALIDATOR");+ console.log("=".repeat(90));+ console.log(` Reading: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(` ERROR: feature_list.json not found at ${filePath}`);+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");+ process.exit(1);+ }++ let entries: FeatureEntry[];+ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");+ process.exit(1);+ }++ // For demo purposes, also validate an extended test set+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "User can import a PDF document.",+ verification: ["Upload a PDF file", "Verify it appears in the document list"],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "System hallucination rate is below 5%.",+ verification: [], // Empty -- no evidence+ passes: true, // Marked as pass WITHOUT evidence+ },+ {+ id: "missing-fields",+ // Missing 'category' and 'description'+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Print report+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";+ const notes = r.markedPassWithoutEvidence+ ? "FLAGGED: passes without evidence!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";+ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`+ );+ }++ // Summary+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;+ const withEvidence = results.filter((r) => r.hasVerification).length;++ console.log("\n" + "-".repeat(90));+ console.log(" SUMMARY");+ console.log("-".repeat(90));+ console.log(` Total features: ${total}`);+ console.log(` Schema valid: ${schemaOk}/${total}`);+ console.log(` Marked as passing: ${passing}/${total}`);+ console.log(` With verification evidence: ${withEvidence}/${total}`);+ console.log(` Flagged (pass without evidence): ${flagged}`);++ if (flagged > 0) {+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);+ console.log(" These features need verification before they can be trusted.\n");+ } else {+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");+ }+}++run();diff --git a/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..8b973e3--- /dev/null+++ b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",+ "verification": [+ "Import a markdown document",+ "Open the Q&A panel",+ "Ask a question about known content",+ "Verify the answer is returned",+ "Verify one or more citations are displayed"+ ],+ "passes": false+ }+]diff --git a/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdnew file mode 100644index 0000000..ac855d9--- /dev/null+++ b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 08++Usa esta carpeta para ejemplos de:++- gating de estado de aprobación+- verificación end-to-end+- criterios de completitud débiles vs fuertes+- ejemplos de bucle evaluadordiff --git a/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdnew file mode 100644index 0000000..6d9083d--- /dev/null+++ b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -0,0 +1,8 @@+# Política de Puerta de Aprobación++Un feature solo puede pasar de `passes: false` a `passes: true` cuando:++- el flujo de trabajo esperado ha sido ejecutado+- la evidencia de éxito está registrada+- no hay errores bloqueantes en la ruta probada+- la implementación no deja la app en un estado roto o ambiguodiff --git a/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdnew file mode 100644index 0000000..2ac67ff--- /dev/null+++ b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -0,0 +1,138 @@+[中文版本 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> Proyecto práctico: [Proyecto 04. Feedback en runtime y control de alcance](./../../projects/project-04-incremental-indexing/index.md)++# Lección 08. Usa listas de funciones para limitar al agente++Pides a un agente que construya un sitio de e-commerce. Cuando termina, te dice "done". Miras el código: la autenticación de usuario funciona, pero el botón de checkout del carrito no hace nada y el flujo de pago no está conectado. El problema: nunca le dijiste qué significa "done", así que usó su propio estándar: "escribí mucho código y parece bastante completo".++Para muchas personas, las listas de funciones son solo una nota: escribes cosas para no olvidarlas y luego las dejas de lado. Pero en el mundo del harness, una lista de funciones no es una nota para humanos: es la columna vertebral de todo el harness. El scheduler depende de ella para elegir tareas, el verifier para juzgar la finalización y el handoff reporter para generar resúmenes. Si rompes la columna, todo el cuerpo queda paralizado.++Anthropic y OpenAI enfatizan lo mismo: **los artefactos deben externalizarse.** El estado de las funciones debe vivir en un archivo machine-readable dentro del repo, no en texto de conversación sin estructura.++## Los agentes no saben qué significa "done"++Ni Claude Code ni Codex saben automáticamente qué quieres decir con "done". Dices "añade una función de carrito de compras", y el modelo puede interpretar eso como "escribe un componente Cart y un método addToCart". Pero tú querías "el usuario puede navegar productos, añadirlos al carrito y completar el checkout end-to-end". Sin una lista de funciones, esta brecha de entendimiento persiste. El agente usa su estándar implícito, normalmente "el código no tiene errores de sintaxis obvios". Lo que necesitas es verificación conductual end-to-end. Es como pedirle a un amigo que compre fruta: dices "compra algo de fruta" y vuelve con limones. Su fruta y tu fruta no son la misma fruta.++Mira esta nota de progreso común:++```+Did user auth, shopping cart mostly done, still need payments+```++¿Puede una nueva sesión de agente responder preguntas a partir de esta nota? ¿Qué significa "mostly done"? ¿Qué tests pasó el carrito? ¿Qué bloquea los pagos? La respuesta a todo es "nadie lo sabe". Es como decirle al médico "me duele el estómago, últimamente más o menos bien": ¿qué medicina puede recetar?++Resultado: la nueva sesión gasta 20 minutos infiriendo el estado del proyecto y quizá reimplementa funciones ya terminadas. Los datos de ingeniería de Anthropic muestran que buenos registros de progreso reducen el tiempo de diagnóstico al iniciar sesión entre 60% y 80%.++## Máquina de estados de funciones++```mermaid+flowchart LR+ Feature["Una fila de función"] --> Behavior["Comportamiento<br/>por ejemplo: POST /cart/items returns 201"]+ Feature --> Check["Comando de verificación<br/>el check exacto que ejecutar"]+ Feature --> State["Estado<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["Solo con los tres campos<br/>la fila de función es usable"]+ Check --> Complete+ State --> Complete+```++```mermaid+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["Elegir el siguiente item not_started"]+ Scheduler --> Agent["El agente trabaja en ese único item"]+ Agent --> Verifier["Ejecutar el comando de verificación del item"]+ Verifier -->|pass| Passing["Marcar como passing<br/>y escribir evidencia"]+ Verifier -->|fail| Active["Mantenerlo active"]+ Verifier -->|dependency issue| Blocked["Marcarlo blocked"]+ Passing --> Handoff["Actualizar handoff note<br/>y progreso actual"]+ Active --> Agent+```++## Conceptos clave++- **Las listas de funciones son primitives del harness**: No son "herramientas opcionales de planificación", sino estructuras de datos fundacionales de las que dependen los demás componentes del harness. Como las estructuras de tablas en una base de datos: no puedes decir "omitamos las primary keys".+- **Estructura triple**: Cada función es una triple `(descripción de comportamiento, comando de verificación, estado actual)`. Si falta cualquier elemento, el item está incompleto.+- **Modelo de máquina de estados**: Cada función tiene cuatro estados: `not_started`, `active`, `blocked`, `passing`. Las transiciones de estado las controla el harness, no las cambia libremente el agente.+- **Pass-state gating**: La única forma de pasar de `active` a `passing` es que el comando de verificación se ejecute con éxito. Esto es irreversible: una vez `passing`, no vuelve atrás. Como aprobar un examen: aprobaste, no puedes cambiar la nota retroactivamente.+- **Single source of truth**: Toda la información sobre "qué hay que hacer" debe derivarse de una sola lista de funciones. Sin contradicciones entre la lista y el historial de conversación.+- **Back-pressure**: El número de funciones que aún no han pasado es la presión que el harness ejerce sobre el agente. Presión cero = proyecto completo.++## Por qué las listas de funciones deben ser "primitives"++Los documentos son para que los lean humanos; los primitives son para que los ejecuten sistemas. Los documentos pueden ignorarse; los primitives no pueden saltarse.++Piensa en restricciones de triggers de base de datos frente a checks en la capa de aplicación: las primeras las impone el motor de base de datos, ningún SQL puede saltarlas; las segundas dependen de la corrección del código de aplicación y pueden omitirse por accidente. Como primitive del harness, la lista de funciones sirve a cuatro componentes:++1. **Scheduler**: Lee estados y elige la siguiente función `not_started`. Como un sistema de planificación de producción en fábrica.+2. **Verifier**: Ejecuta comandos de verificación y decide si permite transiciones de estado. Como inspección de calidad.+3. **Handoff reporter**: Genera automáticamente resúmenes de traspaso de sesión desde la lista. Como un reporte automático de cambio de turno.+4. **Progress tracker**: Cuenta la distribución de estados y ofrece métricas de salud del proyecto. Como un dashboard.++## Cómo hacerlo bien++### 1. Define un formato mínimo de lista de funciones++No necesitas un sistema complejo: sirve un archivo Markdown estructurado o JSON. La clave es que cada entrada tenga la triple:++```json+{+ "id": "F03",+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",+ "state": "passing",+ "evidence": "commit abc123, test output log"+}+```++### 2. Deja que el harness controle las transiciones++El agente no puede cambiar directamente el estado de una función a `passing`. Solo puede enviar una solicitud de verificación; el harness ejecuta el comando y decide si permite la transición. Esto es pass-state gating.++### 3. Escribe las reglas en CLAUDE.md++```+## Feature List Rules+- Feature list file: /docs/features.md+- Only one feature active at a time+- Verification command must pass before marking as passing+- Don't modify feature list states yourself — the verification script updates them automatically+```++### 4. Calibra la granularidad++Cada función debe tener alcance "completable en una sesión". Si es demasiado amplia no terminará; si es demasiado pequeña, crece el coste de gestión. "El usuario puede añadir items al carrito" tiene buena granularidad. "Implementar el carrito" es demasiado amplio. "Crear el campo name en el modelo Cart" es demasiado estrecho. Como cortar un filete: ni la pieza entera ni carne molida.++## Caso real++Una plataforma e-commerce con 10 funciones. Se compararon dos enfoques de seguimiento:++**Modo memo**: El agente usa notas sin estructura. Después de 3 sesiones, las notas quedan como "hice user auth y product list, shopping cart casi listo pero con bugs, payments sin empezar". La nueva sesión necesita 20 minutos para inferir estado y acaba reimplementando funciones ya completadas. Como una lista de compras que dice "leche, pan y esa cosa": en la tienda sigues sin saber qué comprar.++**Modo columna vertebral**: Cada función tiene estado claro y comando de verificación. La nueva sesión lee la lista y en 3 minutos sabe: F01-F05 están `passing`, F06 está `active`, F07-F10 están `not_started`. Continúa directamente desde F06, sin retrabajo.++Resultado cuantificado: los proyectos que usan listas de funciones estructuradas muestran una tasa de finalización de funciones 45% mayor que el seguimiento libre, con cero implementaciones duplicadas.++## Ideas clave++- **Las listas de funciones son la columna vertebral del harness**, no notas para humanos. Scheduler, verifier y handoff reporter dependen de ellas.+- **Cada función debe tener la triple**: descripción de comportamiento + comando de verificación + estado actual. Si falta un elemento, está incompleta, como un taburete de tres patas al que le falta una.+- **Las transiciones de estado las controla el harness**: el agente no puede cambiar estados por su cuenta. Pasar verificación es el único camino de promoción.+- **La lista de funciones es el single source of truth del proyecto**: toda la información de "qué hacer" deriva de una lista.+- **Calibra la granularidad a "completable en una sesión".**++## Lecturas adicionales++- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — Identifica explícitamente la lista de funciones como "core data structure" para controlar el alcance del agente+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Enfatiza el principio de "externalizar artefactos"+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — Principios de diseño por contrato, base teórica de las listas de funciones+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — Pirámide de tests y prácticas de especificación conductual++## Ejercicios++1. **Diseño de lista de funciones**: Define un esquema JSON mínimo. Incluye id, descripción de comportamiento, comando de verificación, estado actual y referencia de evidencia. Úsalo para describir un proyecto real con 5 funciones.++2. **Comparación de estricticidad de verificación**: Elige 3 funciones y diseña una verificación "laxa" (por ejemplo, "el código no tiene errores de sintaxis") y una "estricta" (por ejemplo, "el test end-to-end pasa"). Compara la tasa de falsos positivos.++3. **Auditoría del principio single source**: Revisa un proyecto con agentes y busca información de alcance que contradiga la lista de funciones (requisitos implícitos en conversaciones, comentarios TODO en código, etc.). Diseña un plan para unificar toda la información en la lista.diff --git a/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.mdnew file mode 100644index 0000000..f8ab4db--- /dev/null+++ b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md@@ -0,0 +1,6 @@+# Lista de Verificación de Estado Limpio++- La app arranca sin reparación manual+- El progreso actual está registrado+- No queda ningún paso de importación o indexación a medias sin documentar+- El siguiente agente puede ejecutar la ruta estándar de inicio y verificación inmediatamentediff --git a/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdnew file mode 100644index 0000000..ac64bcc--- /dev/null+++ b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 09++Usa esta carpeta para ejemplos de:++- logs como feedback+- visibilidad del estado en runtime+- verificaciones de estado limpio+- ejemplos de recuperacióndiff --git a/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.tsnew file mode 100644index 0000000..fad1a3b--- /dev/null+++ b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts@@ -0,0 +1,241 @@+/**+ * victory-detector.ts+ *+ * Simulates an agent that claims task completion, then checks the claimed+ * state against actual verification. Outputs: claimed vs actual, highlighting+ * gaps between what the agent said and what's really true.+ *+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Task {+ name: string;+ claimedComplete: boolean;+ checks: VerificationCheck[];+}++interface VerificationCheck {+ description: string;+ claimed: boolean; // What the agent says+ actual: boolean; // What is actually true+ severity: "critical" | "warning";+}++// ---------------------------------------------------------------------------+// Simulated tasks with claimed vs actual states+// ---------------------------------------------------------------------------++const tasks: Task[] = [+ {+ name: "Add search endpoint",+ claimedComplete: true,+ checks: [+ {+ description: "Route handler exists",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Authentication middleware applied",+ claimed: true,+ actual: false, // Agent forgot auth+ severity: "critical",+ },+ {+ description: "Input validation added",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Unit tests written",+ claimed: true,+ actual: false, // Agent skipped tests+ severity: "critical",+ },+ {+ description: "Integration tests pass",+ claimed: true,+ actual: false, // No tests to run+ severity: "critical",+ },+ {+ description: "Documentation updated",+ claimed: true,+ actual: false, // Agent skipped docs+ severity: "warning",+ },+ ],+ },+ {+ name: "Fix pagination bug",+ claimedComplete: true,+ checks: [+ {+ description: "Bug reproduction case confirmed",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Root cause identified",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Fix applied",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Edge cases tested",+ claimed: true,+ actual: false, // Only happy path tested+ severity: "warning",+ },+ {+ description: "Regression tests added",+ claimed: true,+ actual: false,+ severity: "critical",+ },+ ],+ },+ {+ name: "Refactor auth module",+ claimedComplete: true,+ checks: [+ {+ description: "Old code removed",+ claimed: true,+ actual: false, // Old code still present+ severity: "warning",+ },+ {+ description: "All existing tests still pass",+ claimed: true,+ actual: false, // Two tests broke+ severity: "critical",+ },+ {+ description: "New auth flow works",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Migration guide written",+ claimed: true,+ actual: false,+ severity: "warning",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Verification+// ---------------------------------------------------------------------------++interface TaskVerification {+ taskName: string;+ claimedComplete: boolean;+ actuallyComplete: boolean;+ totalChecks: number;+ claimedPassing: number;+ actualPassing: number;+ gaps: { description: string; severity: string }[];+}++function verifyTask(task: Task): TaskVerification {+ const claimedPassing = task.checks.filter((c) => c.claimed).length;+ const actualPassing = task.checks.filter((c) => c.actual).length;+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);++ return {+ taskName: task.name,+ claimedComplete: task.claimedComplete,+ actuallyComplete: gaps.length === 0,+ totalChecks: task.checks.length,+ claimedPassing,+ actualPassing,+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");+ console.log("=".repeat(90));++ const verifications = tasks.map(verifyTask);++ for (const v of verifications) {+ console.log("\n Task: " + v.taskName);+ console.log(" " + "-".repeat(70));+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);++ if (!v.actuallyComplete) {+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);+ }++ // Detailed checks for this task+ const task = tasks.find((t) => t.name === v.taskName)!;+ console.log("\n Check detail:");+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;+ console.log(header);+ console.log(sep);++ for (const check of task.checks) {+ const claimedLabel = check.claimed ? "PASS" : "FAIL";+ const actualLabel = check.actual ? "PASS" : "FAIL";+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";+ const marker = gapLabel ? ">>" : " ";+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);+ }+ }++ // Overall summary+ console.log("\n" + "=".repeat(90));+ console.log(" OVERALL SUMMARY");+ console.log("=".repeat(90) + "\n");++ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;+ console.log(sHeader);+ console.log(sSep);++ for (const v of verifications) {+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);+ const cLabel = v.claimedComplete ? "Done" : "Pending";+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);+ }++ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;++ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");+ console.log(" Total undetected gaps: " + totalGaps);+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");+}++run();diff --git a/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdnew file mode 100644index 0000000..3471a2e--- /dev/null+++ b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -0,0 +1,145 @@+[中文版本 →](../../../zh/lectures/lecture-09-why-agents-declare-victory-too-early/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# Lección 09. Evita que los agentes declaren victoria demasiado pronto++Le pides a un agent que implemente una funcionalidad de "restablecimiento de contraseña". Modifica el esquema de la base de datos, escribe el endpoint de la API, añade la plantilla de correo electrónico, ejecuta las pruebas unitarias (todas pasan) y luego te dice con confianza "ya está". Cuando realmente intentas ejecutarlo—el enlace de restablecimiento no se puede enviar (falta la configuración del servicio de correo electrónico), la migración de la base de datos falla a mitad de camino (inconsistencia en el esquema), y el flujo end-to-end no se ha ejecutado ni una sola vez.++Esta sensación no debería resultar desconocida—es como llenar todo el examen, ser el primero en entregarlo con confianza, y luego suspender cuando salen las notas. Que el examen esté lleno no significa que las respuestas sean correctas.++No es un incidente aislado. El clásico artículo de 2017 en ICML de Guo et al. demostró: **las redes neuronales modernas son sistemáticamente excesivamente seguras**—la confianza reportada por los modelos es significativamente mayor que su precisión real. Lo mismo se aplica a los agentes de codificación con IA: "sienten" que han terminado, pero en realidad, están lejos de hacerlo. Tu harness debe reemplazar los "sentimientos" del agent con verificación externalizada y basada en ejecución.++## La pendiente resbaladiza++Las declaraciones prematuras de finalización casi siempre siguen el mismo patrón: el código parece correcto—la sintaxis es correcta, la lógica parece razonable, y el análisis estático no muestra errores obvios. Pero el harness no impone una verificación de ejecución exhaustiva, así que el agent se salta ejecutarlo realmente o solo ejecuta pruebas parciales. Ejecuta pruebas unitarias pero se salta las de integración; ejecuta pruebas pero no verifica la cobertura. En última instancia, "el código parece bien" se toma como evidencia de que "la funcionalidad está completa". Y el examen se entrega.++Se pierde información en cada paso. Desde las especificaciones de la tarea hasta la implementación del código y el comportamiento en tiempo de ejecución, cada transformación puede introducir sesgos, y cada verificación omitida exacerba la asimetría de información.++## Verificación de terminación en tres capas++```mermaid+flowchart LR+ Claim["Agent says: done"] --> L1["First run<br/>lint / typecheck"]+ L1 --> L2["Then run<br/>tests and startup checks"]+ L2 --> L3["Finally run<br/>complete user flow"]+ L3 --> Done["Pass all three to be done"]+```++```mermaid+flowchart LR+ A["Code is written<br/>unit tests are green"] --> B["But app didn't really start<br/>full flow never ran"]+ B --> C["Config, DB, external service issues<br/>all remain hidden"]+ C --> D["So agent declares victory too early"]+```++## Conceptos clave++- **Declaración prematura de finalización**: El agent afirma que la tarea está completa, pero aún existen especificaciones de corrección sin cumplir. El problema central: el agent juzga basándose en la confianza local a nivel de código, mientras que la corrección a nivel de sistema requiere verificación global.+- **Sesgo de calibración de confianza**: La brecha sistemática entre la confianza auto-reportada por el agent sobre la finalización y la calidad real de la finalización. Para tareas complejas de múltiples archivos, este sesgo es significativamente positivo—el agent siempre está más seguro de lo que realmente rinde. Es como un estudiante que siempre sobreestima su calificación después de un examen.+- **Criterios de terminación**: Un conjunto claro y ejecutable de condiciones de juicio definidas en el harness. El agent debe satisfacer todas las condiciones antes de declarar la finalización. "Hecho" pasa de ser un juicio subjetivo a una determinación objetiva.+- **Verificación-Validación de doble puerta**: La primera capa de verificación comprueba "si el código implementó correctamente el comportamiento especificado"; la segunda capa de validación comprueba "si el comportamiento a nivel de sistema cumple con los requisitos end-to-end". Ambas deben pasar para considerar la tarea completa.+- **Señales de retroalimentación en tiempo de ejecución**: Logs, estados de procesos y health checks de la ejecución del programa. Esta es la base objetiva para que el harness juzgue la calidad de la finalización.+- **Restricción de prioridad de finalización**: Primero verificar la corrección funcional, luego manejar el rendimiento, y finalmente abordar el estilo. Se prohíbe la refactorización hasta que la funcionalidad central esté verificada.++## Pasar las pruebas unitarias ≠ Tarea completada++Esta es la trampa más común, y la más peligrosa. El agent escribió el código, ejecutó las pruebas unitarias, todo está en verde, y dijo "listo". Pero la filosofía de diseño de las pruebas unitarias—aislar la unidad bajo prueba y mockear las dependencias—es precisamente lo que las hace incapaces de detectar problemas entre componentes:++**Incompatibilidad de interfaces**: La ruta de archivo pasada por el proceso de render al preload script es una ruta relativa, pero el preload script espera una ruta absoluta. Sus respectivas pruebas unitarias usaron mocks y pasaron. El problema solo se descubre durante las pruebas end-to-end. Es como cada músico de una banda practicando perfectamente por su cuenta, solo para darse cuenta de que están en tonos diferentes cuando tocan juntos.++**Errores de propagación de estado**: Una migración de base de datos cambia el esquema de la tabla, pero la capa de caché del ORM todavía mantiene entradas de caché para el esquema anterior. Las pruebas unitarias proporcionan un entorno mock fresco cada vez, lo cual no expondrá esta inconsistencia de estado entre capas.++**Dependencia del entorno**: El código se comporta correctamente en el entorno de prueba (donde todo está mockeado) pero falla en el entorno real debido a diferencias de configuración, latencia de red o indisponibilidad del servicio. Es como cantar perfectamente en la sala de ensayo, pero encontrarse con problemas de equipo de audio en el escenario.++### "Refactorizar de paso" es veneno para el juicio de finalización++Claude Code tiene un patrón de comportamiento común: comienza a refactorizar código, optimizar el rendimiento y mejorar el estilo antes de que la funcionalidad central haya pasado la verificación. La cita de Knuth, "La optimización prematura es la raíz de todos los males," adquiere un nuevo significado en el escenario del agent—la refactorización altera la frontera entre el código verificado y el no verificado, potencialmente rompiendo rutas de código que antes eran implícitamente correctas. Es como volver a copiar tus respuestas de opción múltiple para mejorar el formato antes de haber terminado las preguntas de desarrollo—no solo pierdes tiempo, sino que podrías copiarlas mal.++### Sesgo sistemático en la autoevaluación++Anthropic descubrió un patrón de falla más profundo en su investigación de 2026: **cuando se le pide a un agent que evalúe su propio trabajo, proporciona sistemáticamente evaluaciones excesivamente positivas—incluso cuando un observador humano consideraría que la calidad es claramente insuficiente.** Es como pedirle a un estudiante que califique su propio examen—siempre será particularmente indulgente con sus propias respuestas.++Este problema es especialmente grave en tareas subjetivas (como la estética de diseño)—si un "diseño es exquisito" es una cuestión de juicio, y el agent se inclina confiablemente hacia lo positivo. Incluso en tareas con resultados verificables, el rendimiento del agent puede verse afectado por un juicio deficiente.++La solución no es hacer que el agent sea "más objetivo"—el mismo modelo que genera y evalúa inherentemente favorece ser generoso consigo mismo. **La solución es separar al "trabajador" del "verificador".** Así como un estudiante no debería calificar su propio examen—necesitas un calificador independiente.++Un agent evaluador independiente, ajustado específicamente para ser "exigente", es mucho más efectivo que hacer que el agent generador se evalúe a sí mismo. Datos experimentales de Anthropic:++| Architecture | Runtime | Cost | Core Features Working? |+|--------------|---------|------|------------------------|+| Single Agent (bare run) | 20 mins | $9 | No (game entities unresponsive to input) |+| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Yes (game is fully playable) |++Este es exactamente el mismo modelo (Opus 4.5) con exactamente el mismo prompt ("build a 2D retro game editor"). La única diferencia es el harness—desde "ejecución sin arnés" hasta "el planner expande los requisitos → el generador implementa funcionalidad por funcionalidad → el evaluador realiza pruebas reales de clics usando Playwright".++> Fuente: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## Cómo evitar las entregas prematuras++### 1. Externalizar el juicio de terminación++El juicio de finalización no debería ser hecho por el agent mismo. El harness debe ejecutar independientemente la validación de terminación, usando señales en tiempo de ejecución como entrada, no la confianza del agent. Escríbelo claramente en `CLAUDE.md`:++```+## Definition of Done+- Feature complete = end-to-end verification passed, not "code is written"+- Required verification levels:+ 1. Unit tests pass+ 2. Integration tests pass+ 3. End-to-end flow verification passes+- Do not proceed to level 2 if level 1 fails+- Do not proceed to level 3 if level 2 fails+```++### 2. Construir una validación de terminación en tres capas++- **Capa 1: Sintaxis y análisis estático**. Menor costo, menor información, pero debe pasar. Esta es la verificación mínima—debes escribir las palabras correctamente antes de mirar nada más.+- **Capa 2: Verificación de comportamiento en tiempo de ejecución**. Ejecución de pruebas, verificaciones de inicio de la aplicación, validación de rutas críticas. Esta es la evidencia central de finalización. No basta con escribirlo; debe ejecutarse.+- **Capa 3: Confirmación a nivel de sistema**. Pruebas end-to-end, validación de integración, simulación de escenarios de usuario. La última línea de defensa contra declaraciones prematuras. No basta con que se ejecute; debe ejecutarse correctamente.++### 3. Diseñar buenas "correcciones con bolígrafo rojo" para los agentes++OpenAI introdujo un patrón particularmente efectivo durante su práctica con Codex: **los mensajes de error para los agentes deben incluir instrucciones de corrección**. No simplemente dibujes una gran X roja como un calificador perezoso; sé como un buen profesor y escribe "así es como deberías cambiar esto" en los márgenes. No uses `"Test failed"`, sino usa `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` Esta retroalimentación específica y accionable permite al agent autocorregirse sin intervención humana.++### 4. Capturar señales en tiempo de ejecución++Las señales efectivas en tiempo de ejecución incluyen:+- ¿La aplicación se inició exitosamente y alcanzó un estado listo?+- ¿Las rutas de funcionalidad crítica se ejecutaron exitosamente en tiempo de ejecución?+- ¿Las escrituras en base de datos, operaciones de archivos y otros efectos secundarios fueron correctos?+- ¿Se limpiaron los recursos temporales?++## Caso del mundo real++**Tarea**: Implementar la funcionalidad de restablecimiento de contraseña de usuario. Involucra operaciones de base de datos, envío de correo electrónico y modificaciones de endpoints de API.++**Ruta de entrega prematura**: El agent modifica el esquema de la base de datos, escribe el endpoint de la API, añade la plantilla de correo electrónico, ejecuta las pruebas unitarias (pasa) y declara la finalización. El examen está completamente lleno.++**Deducciones reales**: (1) Flujo end-to-end sin probar—el envío y verificación real del enlace de restablecimiento nunca se confirmó. (2) La migración de base de datos falló después de una ejecución parcial, causando inconsistencia en el esquema. (3) Faltaba la configuración del servicio de correo electrónico en el entorno destino.++**Intervención del harness**: Validación de terminación impuesta—(1) Iniciar la aplicación completa para verificar la accesibilidad del endpoint de restablecimiento; (2) Ejecutar el flujo completo de restablecimiento; (3) Verificar la consistencia del estado de la base de datos. Todos los defectos se encontraron dentro de la sesión, ahorrando 5-10x el costo de correcciones posteriores. El calificador independiente encontró los problemas reales.++## Ideas clave++- **Los agentes son sistemáticamente excesivamente seguros**—el sesgo de calibración de confianza es una realidad objetiva. Llenar el examen no significa que lo hayas hecho bien.+- **El juicio de finalización debe externalizarse**—el harness verifica independientemente; no confíes en los "sentimientos" del agent. Los estudiantes no pueden calificar sus propios exámenes.+- **Las tres capas de validación son esenciales**—sintaxis pasando, comportamiento pasando, sistema pasando, progresando capa por capa.+- **Los mensajes de error deben ser como las correcciones con bolígrafo rojo de un buen profesor**—incluir pasos específicos de corrección para que el agent pueda autocorregirse.+- **Sin refactorización hasta que la funcionalidad central esté verificada**—la restricción de prioridad de finalización es la clave para prevenir la optimización prematura.++## Lecturas adicionales++- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — Demuestra que las redes neuronales modernas son sistemáticamente excesivamente seguras+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — El papel crítico de la evidencia en tiempo de ejecución en el juicio de finalización+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — La declaración prematura de finalización es uno de los principales modos de falla de los agentes+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — Referencia clásica sobre jerarquías de métodos de prueba y su efectividad++## Ejercicios++1. **Diseño de función de validación de terminación**: Diseña una validación de terminación completa para una tarea que involucre una migración de base de datos y una modificación de API. Enumera las señales en tiempo de ejecución requeridas y los criterios de aprobación/rechazo para cada señal. Ejecútala en una tarea real y registra qué problemas ocultos encuentra.++2. **Medición del sesgo de calibración**: Elige 10 tipos diferentes de tareas de codificación, y registra la confianza de finalización auto-reportada por el agent versus la calidad real de finalización. Calcula el valor del sesgo y analiza su relación con la complejidad de la tarea.++3. **Experimento de defensa en múltiples capas**: Ejecuta tres configuraciones en el mismo conjunto de tareas—(a) solo análisis estático, (b) añadir pruebas unitarias, (c) validación completa en tres capas. Compara la proporción de declaraciones prematuras de finalización y el número de defectos no detectados.diff --git a/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.mdnew file mode 100644index 0000000..a6a864d--- /dev/null+++ b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md@@ -0,0 +1,6 @@+# Reglas de Arquitectura de Electron++- El código del renderer no puede acceder directamente al sistema de archivos.+- Preload es el único puente entre el renderer y Electron main.+- La lógica de recuperación e indexación vive en módulos de servicio, no en componentes UI.+- El logging debe ser estructurado y emitido desde los límites de servicio.diff --git a/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.tsnew file mode 100644index 0000000..2428416--- /dev/null+++ b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts@@ -0,0 +1,253 @@+/**+ * e2e-runner.ts+ *+ * A minimal E2E test harness. Defines test cases as user action sequences+ * (import doc -> index -> ask question -> verify citation). Simulates+ * running them and shows the difference between "unit tests pass" and+ * "full pipeline works".+ *+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface PipelineStep {+ name: string;+ unitTestPasses: boolean;+ // Simulated actual behavior in the pipeline+ actualBehavior: "works" | "fails" | "partial";+ failureReason?: string;+}++interface TestCase {+ name: string;+ steps: PipelineStep[];+}++interface TestResult {+ testCase: string;+ unitTestsPassed: number;+ unitTestsTotal: number;+ unitTestResult: "PASS" | "FAIL";+ e2eResult: "PASS" | "FAIL";+ e2eFailureStep?: string;+ e2eFailureReason?: string;+}++// ---------------------------------------------------------------------------+// Test cases -- realistic scenarios where unit tests pass but E2E fails+// ---------------------------------------------------------------------------++const testCases: TestCase[] = [+ {+ name: "Import document and ask question",+ steps: [+ {+ name: "Parse uploaded document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Store document chunks",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Index chunks for retrieval",+ unitTestPasses: true,+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions+ failureReason: "Embedding dimension mismatch between indexer and retriever",+ },+ {+ name: "Retrieve relevant chunks",+ unitTestPasses: true, // Unit test uses mock data with correct dimensions+ actualBehavior: "fails",+ failureReason: "Empty results due to dimension mismatch from previous step",+ },+ {+ name: "Generate answer with citations",+ unitTestPasses: true, // Unit test provides pre-retrieved chunks+ actualBehavior: "fails",+ failureReason: "No chunks retrieved, so answer has no citations",+ },+ ],+ },+ {+ name: "Delete document and verify removal",+ steps: [+ {+ name: "Find document by ID",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Delete document record",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Remove indexed chunks",+ unitTestPasses: true,+ actualBehavior: "fails", // Orphaned chunks remain in the index+ failureReason: "Index cleanup query timed out, chunks remain orphaned",+ },+ {+ name: "Verify document not in search results",+ unitTestPasses: true, // Unit test mocks the search+ actualBehavior: "fails",+ failureReason: "Orphaned chunks from previous step still appear in results",+ },+ ],+ },+ {+ name: "Multi-user concurrent access",+ steps: [+ {+ name: "User A imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User B imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User A queries their document",+ unitTestPasses: true,+ actualBehavior: "partial", // Cross-contamination of results+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",+ },+ {+ name: "Verify only User A's results returned",+ unitTestPasses: true,+ actualBehavior: "fails",+ failureReason: "Results include documents from other users",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Run tests+// ---------------------------------------------------------------------------++function runUnitTests(tc: TestCase): { passed: number; total: number } {+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;+ return { passed, total: tc.steps.length };+}++function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {+ // Pipeline: if any step actually fails, the whole E2E fails+ for (const step of tc.steps) {+ if (step.actualBehavior === "fails") {+ return {+ pass: false,+ failureStep: step.name,+ failureReason: step.failureReason ?? "Unknown failure",+ };+ }+ // "partial" means the step technically completes but creates problems downstream+ // We let it continue but track it+ }+ // Check if any step was "partial" (which may cause downstream issues)+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");+ if (partialSteps.length > 0) {+ // The partial steps may or may not cause overall failure+ // In our simulation, partial steps always lead to failure downstream+ // unless there's an explicit "fails" step that already caught it+ // This case means all steps were either "works" or "partial"+ return {+ pass: false,+ failureStep: partialSteps[partialSteps.length - 1].name,+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",+ };+ }++ return { pass: true };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(95));+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");+ console.log("=".repeat(95));++ const results: TestResult[] = testCases.map((tc) => {+ const unit = runUnitTests(tc);+ const e2e = runE2ETest(tc);++ return {+ testCase: tc.name,+ unitTestsPassed: unit.passed,+ unitTestsTotal: unit.total,+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",+ e2eResult: e2e.pass ? "PASS" : "FAIL",+ e2eFailureStep: e2e.failureStep,+ e2eFailureReason: e2e.failureReason,+ };+ });++ // Per-test-case detail+ for (let i = 0; i < testCases.length; i++) {+ const tc = testCases[i];+ const r = results[i];++ console.log("\n Test Case: " + tc.name);+ console.log(" " + "-".repeat(70));++ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;+ console.log(stepHeader);+ console.log(stepSep);++ for (const step of tc.steps) {+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";+ let e2eLabel: string;+ if (step.actualBehavior === "works") e2eLabel = "PASS";+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";+ else e2eLabel = "FAIL";++ const marker = step.actualBehavior !== "works" ? ">>" : " ";+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);+ }++ if (r.e2eFailureStep) {+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);+ console.log(` Reason: ${r.e2eFailureReason}`);+ }+ }++ // Summary comparison+ console.log("\n" + "=".repeat(95));+ console.log(" COMPARISON: Unit Tests vs E2E Tests");+ console.log("=".repeat(95) + "\n");++ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";++ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);+ }++ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");+}++run();diff --git a/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdnew file mode 100644index 0000000..6337ff6--- /dev/null+++ b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 10++Usa esta carpeta para ejemplos de:++- restricciones de arquitectura+- pruebas estructurales+- invariantes de gusto (taste invariants)+- mensajes de lint orientados a la remediacióndiff --git a/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdnew file mode 100644index 0000000..a587c6d--- /dev/null+++ b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -0,0 +1,10 @@+# Ejemplo: Convertir Feedback de Review en una Regla++Comentario de review repetido:++> No uses utilidades del sistema de archivos desde el renderer. Usa el puente preload.++Regla de harness promovida:++- añadir una regla de lint o import que prevenga el uso de `fs` en código del renderer+- añadir texto de remediación explicando la frontera de preloaddiff --git a/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdnew file mode 100644index 0000000..17370f0--- /dev/null+++ b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -0,0 +1,158 @@+[中文版本 →](../../../zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# Lección 10. Solo las pruebas end-to-end son verificación real++Le pides al agent que añada una funcionalidad de exportación de archivos a una aplicación Electron. Escribe el componente del proceso de render, el preload script y la lógica de la capa de servicio. Las pruebas unitarias de cada componente pasan perfectamente. El agent dice: "Ya está." Cuando realmente haces clic en el botón de exportación—el formato de la ruta del archivo es incorrecto, la barra de progreso no se actualiza, y exportar archivos grandes causa una fuga de memoria. Cinco defectos en los límites de componentes, y las pruebas unitarias no detectaron ni uno solo.++Es como un ensayo de coro—cada parte vocal suena perfecta cuando se canta individualmente, pero cuando cantan juntos, las sopranos van medio tiempo más rápido que los bajos, y el acompañamiento está un semitono desfasado de la melodía principal. Cada parte es "correcta" por sí sola, pero el conjunto está desafinado.++La Pirámide de Testing de Google nos dice: un gran número de pruebas unitarias son la base, pero si te detienes ahí, perderás sistemáticamente los problemas de interacción entre componentes. Para los agentes de codificación con IA, este problema es aún más grave—los agentes tienden a ejecutar solo las pruebas más rápidas y luego declarar la finalización. **Solo las pruebas end-to-end pueden demostrar que no existen defectos a nivel de sistema.**++## Los puntos ciegos de las pruebas unitarias++La filosofía de diseño de las pruebas unitarias es el aislamiento—mockear dependencias y enfocarse únicamente en la unidad bajo prueba. Esta filosofía hace que las pruebas unitarias sean rápidas y precisas, pero también crea puntos ciegos sistemáticos. Es como hacer que cada parte vocal practique con auriculares durante un ensayo de coro—suena bien para ellos, pero los problemas solo emergen cuando se unen:++**Incompatibilidad de interfaces**: La ruta de archivo pasada por el proceso de render al preload script es una ruta relativa, pero el preload script espera una ruta absoluta. Sus respectivas pruebas unitarias usaron mocks y pasaron. El problema solo se descubre cuando se ejecuta el flujo end-to-end—como dos partes vocales practicando independientemente y sintiéndose bien, solo para darse cuenta durante el conjunto que una canta en compás de 4/4 y la otra en 3/4.++**Errores de propagación de estado**: Una migración de base de datos cambia el esquema de la tabla, pero la capa de caché del ORM todavía mantiene entradas de caché para el esquema anterior. Las pruebas unitarias proporcionan un entorno mock completamente nuevo cada vez, lo cual no expondrá esta inconsistencia de estado entre capas. Es como cambiar la letra de una canción, pero alguien todavía canta la versión antigua.++**Problemas de ciclo de vida de recursos**: La adquisición y liberación de file handles, conexiones de base de datos y sockets de red abarcan múltiples componentes. Las pruebas unitarias crean y destruyen recursos independientes para cada prueba, sin exponer la contención de recursos o las fugas. Es como cada parte vocal tomando turnos para usar los micrófonos durante el ensayo, pero cuando todos suben al escenario juntos, no hay suficientes micrófonos.++**Dependencia del entorno**: El código se comporta correctamente en el entorno de prueba (donde todo está mockeado) pero falla en el entorno real debido a diferencias de configuración, latencia de red o indisponibilidad del servicio. Como cantar perfectamente en la sala de ensayo, pero encontrar retroalimentación acústica e interferencia del viento en un festival al aire libre.++## Las pruebas end-to-end no solo cambian los resultados, cambian el comportamiento++Esto es algo que muchas personas no logran comprender: cuando un agent sabe que su trabajo será sometido a pruebas end-to-end, su comportamiento de codificación cambia.++1. **Considerar las interacciones entre componentes**: Mientras escribe código, pensará en "cómo se conecta esta interfaz con el upstream", en lugar de enfocarse solo en una única función. Así como saber que eventualmente cantarán juntos, prestarás atención a las otras partes vocales durante la práctica.+2. **Respetar los límites de la arquitectura**: En sistemas con restricciones arquitectónicas, las pruebas end-to-end obligan al agent a adherirse a las reglas de límites. Como una partitura marcada con "crescendo aquí", tienes que seguirla.+3. **Manejar rutas de error**: Las pruebas end-to-end generalmente incluyen escenarios de falla, obligando al agent a considerar el manejo de excepciones. Es como simular "qué pasaría si el micrófono muriera repentinamente" durante el ensayo, para que sepas qué hacer.++## Pirámide de testing y promoción de retroalimentación de revisiones++```mermaid+flowchart TB+ subgraph Unit["Unit tests only check isolated parts"]+ U1["Renderer tests"]+ U2["Preload tests"]+ U3["Service tests"]+ end++ subgraph E2E["E2E runs through the real system"]+ R["Click renderer button"] --> P["Preload bridge"]+ P --> S["Service layer"]+ S --> F["File System / OS"]+ F --> Result["Actual exported file"]+ end+```++```mermaid+flowchart LR+ Review["Review feedback:<br/>renderer cannot import fs directly"] --> Rule["Add a direct fs import check"]+ Rule --> Message["Tell agent in error message<br/>to move file access to preload"]+ Message --> Harness["Add this check to harness"]+ Harness --> Stronger["Will fail immediately next time"]+```++En las prácticas de ingeniería de Codex, OpenAI enfatiza: **los mensajes de error escritos para agentes deben incluir instrucciones de corrección.** No simplemente escribas `"Direct filesystem access in renderer"`; escribe `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` Esto convierte las reglas arquitectónicas en un bucle de autocorrección. Como un director de coro que no solo dice "cantaste mal eso", sino que dice "estuviste medio tiempo rápido aquí, escucha el ritmo de los altos, y entra en el compás 32."++## Conceptos clave++- **Defectos en los límites de componentes**: El componente A y B pasan sus pruebas unitarias, pero su interacción produce un comportamiento incorrecto. Este es el tipo de problema que las pruebas end-to-end detectan mejor—como partes del coro que son individualmente correctas pero desafinadas juntas.+- **Gradiente de adecuación de pruebas**: Defectos detectados por pruebas unitarias <= defectos detectados por pruebas de integración <= defectos detectados por pruebas end-to-end. Cada capa superior aumenta la capacidad de detección.+- **Reglas de cumplimiento de límites arquitectónicos**: Convertir reglas de documentos de arquitectura (como "el proceso de render no puede acceder al sistema de archivos directamente") en verificaciones ejecutables y automatizadas. De "escritas en papel" a "ejecutándose en CI."+- **Promoción de retroalimentación de revisiones**: Convertir comentarios repetidos de revisiones de código en pruebas automatizadas. Cada vez que se encuentra un problema recurrente, añadir una regla, y el harness automáticamente se fortalece. Como un director que convierte los errores comunes de ensayo en ejercicios de calentamiento—la próxima vez que se cometa el mismo error, el ejercicio mismo lo expone sin que el director necesite decir nada.+- **Mensajes de error orientados al agent**: Los mensajes de falla no deberían solo indicar "qué salió mal", sino también decirle al agent exactamente cómo solucionarlo. Esto convierte las fallas de pruebas en bucles de retroalimentación autocorrectivos.++## Cómo hacerlo++### 0. Definir los límites arquitectónicos primero, luego escribir pruebas E2E++El prerrequisito para las pruebas end-to-end son límites de sistema claros. Si la arquitectura es un plato de espaguetis, las pruebas end-to-end solo probarán "este plato de espaguetis funciona", no te dirán dónde se violaron las intenciones de diseño. Es como un coro que ni siquiera se ha dividido en partes vocales—por mucho que ensayen, no sonará bien.++La experiencia de OpenAI: **para bases de código generadas por agentes, las restricciones arquitectónicas deben ser prerrequisitos tempranos establecidos desde el primer día, no algo a considerar cuando el equipo crezca.** La razón es simple—los agentes copiarán los patrones existentes en el repositorio, incluso si esos patrones son desiguales o subóptimos. Sin restricciones arquitectónicas, el agent introducirá más desviaciones en cada sesión.++OpenAI adoptó una "Arquitectura de Dominio en Capas"—cada dominio de negocio se divide en capas fijas: Types → Config → Repo → Service → Runtime → UI. Las dependencias fluyen estrictamente hacia adelante, y las preocupaciones entre dominios entran a través de interfaces de Providers explícitas. Cualquier otra dependencia está prohibida y se cumple mecánicamente mediante linting personalizado.++Principio clave: **Impedir invariantes, no microgestionar la implementación.** Por ejemplo, requerir "los datos se analizan en el límite", pero no dictar qué biblioteca usar. Los mensajes de error deben incluir instrucciones de corrección—no solo decir "violación", sino decirle al agent exactamente cómo cambiarlo.++> Fuente: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++### 1. El harness debe incluir una capa end-to-end++Hazlo explícito en tu flujo de validación: para tareas que involucren cambios entre componentes, pasar las pruebas end-to-end es un prerrequisito para la finalización:++```+## Validation Hierarchy+- Level 1: Unit tests (Must pass)+- Level 2: Integration tests (Must pass)+- Level 3: End-to-end tests (Must pass when cross-component changes are involved)+- Skipping any required level = Not Complete+```++### 2. Convertir reglas arquitectónicas en verificaciones ejecutables++Cada restricción arquitectónica debe tener una prueba o regla de lint correspondiente:++```bash+# Check if the render process directly calls Node.js APIs+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"+```++### 3. Diseñar mensajes de error orientados al agent++Los mensajes de falla deben contener tres elementos: qué salió mal, por qué, y cómo solucionarlo:++```+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12+WHY: Renderer process has no access to Node.js APIs for security+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()+```++### 4. Establecer un proceso de promoción de retroalimentación de revisiones++Cada vez que se encuentre un nuevo tipo de error del agent durante una revisión de código, conviértelo en una verificación automatizada. Un mes después, tu harness será significativamente más fuerte que al inicio del mes. Es como las notas de ensayo de un coro—registrar los problemas encontrados en cada ensayo para poder verificarlos antes del siguiente. Con el tiempo, los errores comunes disminuyen, y la música se vuelve más armoniosa.++## Caso del mundo real++**Tarea**: Implementar una funcionalidad de exportación de archivos en una aplicación Electron. Involucra la UI del proceso de render, el proxy del sistema de archivos del preload script y la transformación de datos de la capa de servicio.++**Cantando las partes individualmente (Pruebas unitarias pasaron)**: Pruebas del componente de render (pasaron, operaciones de archivo mockeadas), pruebas del preload script (pasaron, sistema de archivos mockeado), pruebas de la capa de servicio (pasaron, fuente de datos mockeada). El agent declara la finalización.++**Cantando juntos (Defectos revelados por las pruebas end-to-end)**:++| Defect | Description | Unit Test | E2E |+|--------|-------------|-----------|-----|+| Interface Mismatch | Inconsistent file path format | Missed | Caught |+| State Propagation | Export progress not sent back to UI via IPC | Missed | Caught |+| Resource Leak | Large file export handles not released | Missed | Caught |+| Permission Issue | Different permissions in packaged environment | Missed | Caught |+| Error Propagation | Service layer exceptions didn't reach UI layer | Missed | Caught |++Los 5 defectos fueron detectados por las pruebas end-to-end, mientras que las pruebas unitarias no detectaron ninguno. El costo fue un aumento en el tiempo de prueba de 2 segundos a 15 segundos—completamente aceptable en un flujo de trabajo de agent. Por muy bien que cada parte cante individualmente, no puede superar un ensayo completo del conjunto.++## Ideas clave++- **Las pruebas unitarias son sistemáticamente ciegas a los defectos en los límites de componentes**—su diseño de aislamiento es precisamente lo que les impide detectar problemas de interacción. Que todos canten correctamente no significa que el coro no esté desafinado.+- **Las pruebas end-to-end no solo detectan defectos, cambian el comportamiento de codificación del agent**—haciéndolo enfocarse más en la integración y los límites.+- **Las reglas arquitectónicas deben ser ejecutables**—no escritas en un documento esperando ser leídas, sino verificadas automáticamente en cada commit.+- **Los mensajes de error deben estar diseñados para los agentes**—incluyendo pasos específicos sobre "cómo solucionarlo" para formar un bucle autocorrectivo.+- **La promoción de retroalimentación de revisiones hace que el harness se fortalezca automáticamente**—cada categoría de defecto capturado se convierte en una línea de defensa permanente.++## Lecturas adicionales++- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — La fuente clásica del modelo de Pirámide de Testing+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Prácticas de ingeniería para la ejecución automatizada de restricciones arquitectónicas+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — Inyección proactiva de fallas para verificar la resiliencia del sistema+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — Metodología de property testing, situada entre las pruebas de ejemplo y la verificación formal++## Ejercicios++1. **Detección de defectos entre componentes**: Elige una tarea de modificación que involucre al menos tres componentes. Primero, ejecuta solo pruebas unitarias y registra los resultados, luego ejecuta pruebas end-to-end. Analiza a qué tipo de problema de interacción entre capas pertenece cada defecto adicional descubierto.++2. **Automatización de reglas arquitectónicas**: Elige una restricción arquitectónica de tu proyecto y conviértela en una verificación ejecutable (con un mensaje de error orientado al agent). Intégrala en el harness y verifica su efectividad con una tarea de referencia.++3. **Promoción de retroalimentación de revisiones**: Encuentra un tipo de comentario recurrente en tu historial de revisiones de código y conviértelo en una verificación automatizada usando el proceso de cinco pasos. Compara la frecuencia del problema antes y después de la promoción.diff --git a/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.mdnew file mode 100644index 0000000..f832c88--- /dev/null+++ b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md@@ -0,0 +1,8 @@+# Ejemplo de Rúbrica de Evaluación++Usa puntuación de 1-5 para cada dimensión:++- Fundamentación: ¿las respuestas están claramente vinculadas a las fuentes importadas?+- Calidad de citación: ¿las referencias a fuentes son visibles y específicas?+- Funcionalidad: ¿puede el usuario completar el flujo de pregunta-respuesta?+- Coherencia del producto: ¿el flujo de trabajo se siente integrado?diff --git a/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdnew file mode 100644index 0000000..79d52ca--- /dev/null+++ b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 11++Usa esta carpeta para ejemplos de:++- salidas del planificador+- rúbricas de evaluación+- bucles generador/evaluador+- comparaciones de agente único vs multi-roldiff --git a/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsnew file mode 100644index 0000000..213dc19--- /dev/null+++ b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts@@ -0,0 +1,260 @@+/**+ * runtime-logger.ts+ *+ * A structured logging module demo. Shows ad-hoc console.log output vs+ * structured JSON log output when diagnosing a failure. Includes a seeded+ * failure scenario and demonstrates how structured logs pinpoint the issue+ * faster.+ *+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StructuredLogEntry {+ timestamp: string;+ level: "info" | "warn" | "error" | "debug";+ component: string;+ action: string;+ durationMs?: number;+ input?: unknown;+ output?: unknown;+ error?: string;+ correlationId: string;+}++// ---------------------------------------------------------------------------+// Simulated pipeline with a seeded failure+// ---------------------------------------------------------------------------++const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);++// Simulated stages of a document Q&A pipeline+interface PipelineStage {+ component: string;+ action: string;+ durationMs: number;+ success: boolean;+ errorMessage?: string;+ input?: unknown;+ output?: unknown;+}++function runPipeline(): PipelineStage[] {+ return [+ {+ component: "DocumentLoader",+ action: "parse_upload",+ durationMs: 45,+ success: true,+ input: { filename: "report.pdf", size: "2.3MB" },+ output: { chunks: 47 },+ },+ {+ component: "ChunkIndexer",+ action: "embed_and_store",+ durationMs: 230,+ success: true,+ input: { chunks: 47 },+ output: { indexed: 47, embeddingDim: 1536 },+ },+ {+ component: "QueryRouter",+ action: "route_query",+ durationMs: 12,+ success: true,+ input: { query: "What is the revenue target?" },+ output: { routedTo: "RetrievalEngine" },+ },+ {+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch+ component: "RetrievalEngine",+ action: "semantic_search",+ durationMs: 180,+ success: false,+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",+ input: { query: "What is the revenue target?", topK: 5 },+ output: { results: 0 },+ },+ {+ component: "AnswerGenerator",+ action: "generate_with_citations",+ durationMs: 1500,+ success: true, // Doesn't crash, but produces a bad answer+ input: { context: [], query: "What is the revenue target?" },+ output: { answer: "I could not find relevant information.", citations: 0 },+ },+ ];+}++// ---------------------------------------------------------------------------+// Ad-hoc logging (console.log style)+// ---------------------------------------------------------------------------++function printAdHocLog(stages: PipelineStage[]): void {+ console.log("Starting document Q&A pipeline...");+ console.log("User uploaded report.pdf");++ for (const stage of stages) {+ if (stage.success) {+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);+ } else {+ console.log(`${stage.component}: something went wrong`);+ }+ }++ console.log("Pipeline finished. Answer: I could not find relevant information.");+}++// ---------------------------------------------------------------------------+// Structured logging (JSON)+// ---------------------------------------------------------------------------++function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {+ const entries: StructuredLogEntry[] = [];++ for (const stage of stages) {+ entries.push({+ timestamp: new Date().toISOString(),+ level: stage.success ? "info" : "error",+ component: stage.component,+ action: stage.action,+ durationMs: stage.durationMs,+ input: stage.input,+ output: stage.output,+ error: stage.errorMessage,+ correlationId: CORRELATION_ID,+ });+ }++ return entries;+}++// ---------------------------------------------------------------------------+// Diagnose failure from structured logs+// ---------------------------------------------------------------------------++function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {+ const diagnosis: string[] = [];++ // Find errors+ const errors = entries.filter((e) => e.level === "error");+ if (errors.length > 0) {+ diagnosis.push("ERRORS FOUND:");+ for (const err of errors) {+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);+ }+ }++ // Check for latency spikes+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);+ if (slowStages.length > 0) {+ diagnosis.push("LATENCY SPIKES:");+ for (const s of slowStages) {+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);+ }+ }++ // Check for cascading failures+ const emptyOutputs = entries.filter((e) => {+ const out = e.output as Record<string, unknown> | undefined;+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;+ });+ if (emptyOutputs.length > 0) {+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");+ for (const e of emptyOutputs) {+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);+ }+ }++ return diagnosis;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const pipeline = runPipeline();++ console.log("\n" + "=".repeat(90));+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");+ console.log("=".repeat(90));++ // --- Ad-hoc output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO A: Ad-hoc console.log output");+ console.log("-".repeat(90) + "\n");+ printAdHocLog(pipeline);+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");+ console.log(" The failure message is vague: 'something went wrong'.");+ console.log(" No dimensions, no input/output data, no correlation ID.");++ // --- Structured output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO B: Structured JSON log output");+ console.log("-".repeat(90) + "\n");++ const structuredEntries = printStructuredLog(pipeline);++ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const entry of structuredEntries) {+ const hasError = entry.error ? entry.error.slice(0, 30) : "";+ const marker = entry.level === "error" ? ">>" : " ";+ console.log(+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`+ );+ }++ // --- Diagnosis ---+ console.log("\n" + "-".repeat(90));+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");+ console.log("-".repeat(90) + "\n");++ const errors = structuredEntries.filter((e) => e.level === "error");+ for (const err of errors) {+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);+ console.log(` Error: ${err.error}`);+ console.log(` Input: ${JSON.stringify(err.input)}`);+ console.log(` Output: ${JSON.stringify(err.output)}`);+ console.log(` Correlation ID: ${err.correlationId}`);+ }++ // Downstream impact+ console.log("\n DOWNSTREAM IMPACT:");+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");+ if (answerGen) {+ const out = answerGen.output as Record<string, unknown>;+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);+ }++ // Comparison summary+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON");+ console.log("=".repeat(90) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);++ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");+}++run();diff --git a/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.mdnew file mode 100644index 0000000..18e22e0--- /dev/null+++ b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md@@ -0,0 +1,12 @@+# Ejemplo de Contrato de Sprint++Objetivo del sprint:++- Añadir citaciones visibles a los resultados de Q&A fundamentado++"Hecho" significa:++- El usuario hace una pregunta+- La app devuelve una respuesta+- Se muestra al menos una citación+- Hacer clic en una citación abre la ubicación fuente en la vista de documentodiff --git a/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdnew file mode 100644index 0000000..09160e2--- /dev/null+++ b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -0,0 +1,154 @@+[中文版本 →](../../../zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)+> Proyecto práctico: [Proyecto 06. Harness completo (capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# Lección 11. Haz observable el runtime del agente++## Qué problema resuelve esta lección++Le pides a un agente que implemente una función. Corre durante 20 minutos, modifica muchos archivos y luego dice: "terminado, pero fallan dos tests". Preguntas por qué fallan: "no estoy seguro, quizá sea un problema de timing". Preguntas qué rutas críticas cambió: "déjame mirar el código...".++No se trata de que al agente le falte capacidad. El problema es que tu harness no proporciona suficiente observabilidad. **Sin observabilidad, los agentes toman decisiones bajo incertidumbre, las evaluaciones se vuelven juicios subjetivos y los reintentos son tanteos a ciegas.** Tanto OpenAI como Anthropic tratan la fiabilidad como un problema de evidencia: el harness debe exponer el comportamiento en runtime y las señales de evaluación de una forma que guíe la siguiente decisión.++## Conceptos clave++- **Observabilidad de runtime**: señales de sistema como logs, trazas, eventos de proceso y health checks. Responde "qué hizo el sistema".+- **Observabilidad de proceso**: visibilidad sobre artefactos de decisión del harness, como planes, rúbricas de puntuación y criterios de aceptación. Responde "por qué debería aceptarse este cambio".+- **Traza de tarea**: registro completo del camino de decisión desde el inicio hasta la finalización, análogo al tracing de requests en sistemas distribuidos. Cada paso del agente queda registrado con su contexto.+- **Sprint contract**: acuerdo de corto plazo negociado antes de programar, que especifica alcance, estándares de verificación y exclusiones. Es la herramienta central de la observabilidad de proceso.+- **Rúbrica de evaluación**: transforma la evaluación de calidad de juicio subjetivo a puntuación estructurada basada en evidencia. Hace que distintos evaluadores produzcan resultados similares para la misma salida.+- **Observabilidad por capas**: observabilidad de sistema y de proceso diseñadas juntas y reforzándose. Las señales de runtime explican el comportamiento; los artefactos de proceso explican la intención.++## Observabilidad por capas++```mermaid+flowchart LR+ Contract["Escribir primero la tarea<br/>qué cambiar / qué no cambiar / criterios de aprobación"] --> Generator["Generator"]+ Generator --> Signals["Recoger logs, trazas<br/>y health checks durante la ejecución"]+ Contract --> Review["Revisar el resultado punto por punto<br/>comportamiento / tests / límites"]+ Signals --> Review+ Review --> Verdict["Señalar el check fallido<br/>y dónde corregirlo"]+ Verdict --> Generator+```++## Por qué ocurre++### El coste real de no tener observabilidad++Cuando un harness no tiene observabilidad, aparecen sistemáticamente cuatro tipos de problemas:++**No se distingue "correcto" de "parece correcto"**: una función puede verse perfecta en revisión de código — sintaxis correcta, lógica razonable. Pero en runtime, un error en un edge case produce resultados incorrectos con ciertas entradas. Solo las trazas de runtime muestran que la ruta real de ejecución se desvió de lo esperado.++**La evaluación se vuelve mística**: sin rúbricas y criterios de aceptación, los evaluadores, humanos o agentes, dependen de supuestos implícitos. La misma salida puede recibir evaluaciones muy distintas. La calidad deja de ser reproducible.++**Los reintentos se vuelven conjeturas ciegas**: cuando el agente no sabe por qué falló algo, la dirección del reintento es aleatoria. Puede corregir rutas de código irrelevantes mientras ignora la causa raíz. Cada reintento ciego cuesta tokens y tiempo.++**Acantilado de información en el handoff**: cuando se entrega trabajo incompleto a la siguiente sesión, la falta de observabilidad obliga a diagnosticar el estado del sistema desde cero. Las observaciones de Anthropic muestran que ese diagnóstico redundante puede consumir 30-50% del tiempo total de sesión.++### Un escenario realista con Claude Code++Imagina un harness con workflow de tres roles, planner-generator-evaluator, ejecutando la tarea "añadir dark mode a la app".++**Sin observabilidad**: el planner produce una descripción vaga. El generator implementa dark mode con base en esa vaguedad, pero no coincide con las expectativas implícitas del planner. El evaluator rechaza según sus propios estándares implícitos, sin articular qué está mal. El generator reintenta a ciegas. El ciclo se repite 3-4 veces, toma unos 45 minutos y produce algo apenas aceptable.++**Con observabilidad completa**: el planner produce un sprint contract que lista los componentes a modificar, los estándares de verificación y las exclusiones. El generator implementa según el contrato. La observabilidad de runtime registra cómo carga y aplica estilos cada componente. El evaluator usa una rúbrica con evidencias concretas por dimensión. Una iteración produce un resultado de alta calidad en unos 15 minutos.++La diferencia de eficiencia es 3x. Lo único que cambió fue la observabilidad.++### Por qué los agentes no pueden resolverlo solos++Podrías pensar: "¿no puede el agente imprimir sus propios logs?" Los problemas son:++1. El agente no sabe lo que no sabe; no registrará señales que no sabe que necesita.+2. Los formatos de log son inconsistentes; distintas sesiones usan distintos formatos, lo que impide análisis sistemático.+3. La observabilidad de proceso no se resuelve con logs; sprint contracts y rúbricas son artefactos estructurados que necesitan soporte a nivel de harness.++## Cómo hacerlo bien++### 1. Integrar la recogida de señales de runtime en el harness++No dependas de que el agente imprima sus propios logs. El harness debería recoger automáticamente estas señales:++- **Ciclo de vida de la aplicación**: estados de startup, ready, running y shutdown+- **Ejecución de rutas de función**: registros de rutas críticas con puntos de entrada, checkpoints y salidas+- **Flujo de datos**: registros de datos que pasan entre componentes+- **Uso de recursos**: patrones anómalos, por ejemplo memoria que crece sin parar+- **Errores y excepciones**: contexto completo, no solo mensajes de error++### 2. Implementar sprint contracts++Antes de iniciar cada tarea, el generator y el evaluator, que pueden ser invocaciones distintas del mismo agente, negocian un contrato:++```markdown+# Sprint Contract: Dark Mode Support++## Scope+- Modify the theme toggle component+- Update global CSS variables+- Add dark mode tests++## Verification Standards+- Visual regression tests pass for each component+- Main flow end-to-end tests pass+- No flash of unstyled content (FOUC)++## Exclusions+- Not handling print styles+- Not handling third-party component dark mode+```++### 3. Establecer una rúbrica de evaluación++Convierte "¿está bien o no?" en puntuación cuantificable:++```markdown+# Scoring Rubric++| Dimension | A | B | C | D |+|-----------|---|---|---|---|+| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |+| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |+| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |+```++### 4. Estandarizar con OpenTelemetry++Crea una traza para cada sesión de harness, un span para cada tarea y sub-spans para cada paso de verificación. Usa atributos estándar para anotar información clave. Así, los datos de observabilidad se integran con herramientas como Jaeger o Zipkin.++## Caso real++Un harness con workflow planner-generator-evaluator ejecuta "añadir soporte de dark mode":++**Versión no observable**: 3-4 rondas de reintentos ciegos, 45 minutos, resultado apenas aceptable. El evaluator dice "no se siente bien" pero no puede precisar por qué. El generator pierde tiempo en direcciones equivocadas.++**Versión completamente observable**:+- El sprint contract aclara alcance, estándares y exclusiones+- Las trazas de runtime registran el proceso de carga de estilos de cada componente+- La rúbrica da una evaluación estructurada por dimensiones+- Una iteración produce resultados de alta calidad en 15 minutos++Mejora de eficiencia 3x, calidad más estable y evaluaciones reproducibles.++## Ideas clave++- **La observabilidad es una propiedad arquitectónica del harness**, no una función que se añade al final.+- **Ambas capas de observabilidad son esenciales**: las señales de runtime explican "qué pasó"; los artefactos de proceso explican "por qué se hizo así".+- **Los sprint contracts alinean por adelantado**, evitando que el generator construya algo que el evaluator rechaza por razones previsibles.+- **Las rúbricas hacen reproducible la evaluación**, de modo que distintos evaluadores produzcan puntuaciones parecidas.+- **La falta de observabilidad desperdicia 30-50% del tiempo de sesión en diagnóstico redundante.**++## Lecturas adicionales++- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — marco teórico y práctico para observability engineering moderna+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — práctica pionera de tracing distribuido a gran escala+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — introducción de sprint contracts y rúbricas de evaluación+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — aplicación sistemática de observabilidad en producción++## Ejercicios++1. **Análisis de brecha de observabilidad**: audita tu harness actual en la capa de sistema y de proceso. Encuentra estados que no se distinguen con las señales existentes y propone señales nuevas.++2. **Práctica de sprint contract**: escribe un sprint contract para una tarea real. Haz que el agente lo ejecute y compara eficiencia y calidad con y sin contrato.++3. **Construcción de traza de tarea**: registra cada paso de un agente durante una tarea completa de codificación. Anota con convenciones semánticas de OpenTelemetry y analiza dónde falta señal suficiente para decidir.diff --git a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.mdnew file mode 100644index 0000000..407d67f--- /dev/null+++ b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md@@ -0,0 +1,18 @@+# Plantilla de Comparación de Benchmark++Harness A:++- tasa de completitud+- reintentos promedio+- bugs detectados antes de la revisión humana++Harness B:++- tasa de completitud+- reintentos promedio+- bugs detectados antes de la revisión humana++Interpretación:++- ¿Qué harness cambió el resultado?+- ¿Qué harness cambió el costo de obtener el resultado?diff --git a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.tsnew file mode 100644index 0000000..0388cad--- /dev/null+++ b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts@@ -0,0 +1,216 @@+/**+ * benchmark-runner.ts+ *+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),+ * "executes" each task, records timing and pass/fail, outputs a comparison+ * report showing which tasks pass and which fail.+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BenchmarkTask {+ id: string;+ name: string;+ category: string;+ passCriteria: string[];+ expectedDurationMs: number;+ // Simulated actual results+ actualDurationMs: number;+ actualPass: boolean;+ failureReason?: string;+}++interface BenchmarkResult {+ id: string;+ name: string;+ category: string;+ criteriaTotal: number;+ criteriaPassed: number;+ pass: boolean;+ expectedMs: number;+ actualMs: number;+ durationDelta: number;+ failureReason?: string;+}++// ---------------------------------------------------------------------------+// Benchmark task definitions+// ---------------------------------------------------------------------------++const benchmarkTasks: BenchmarkTask[] = [+ {+ id: "bench-001",+ name: "Import markdown document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 100,+ actualDurationMs: 95,+ actualPass: true,+ },+ {+ id: "bench-002",+ name: "Import PDF document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 200,+ actualDurationMs: 310,+ actualPass: false,+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",+ },+ {+ id: "bench-003",+ name: "Ask grounded question",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],+ expectedDurationMs: 500,+ actualDurationMs: 480,+ actualPass: true,+ },+ {+ id: "bench-004",+ name: "Ask question with no relevant docs",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],+ expectedDurationMs: 400,+ actualDurationMs: 420,+ actualPass: false,+ failureReason: "Model hallucinated a citation instead of saying 'no results'",+ },+ {+ id: "bench-005",+ name: "Delete imported document",+ category: "Document Pipeline",+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],+ expectedDurationMs: 150,+ actualDurationMs: 145,+ actualPass: true,+ },+ {+ id: "bench-006",+ name: "Concurrent user access",+ category: "Security",+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],+ expectedDurationMs: 300,+ actualDurationMs: 850,+ actualPass: false,+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",+ },+ {+ id: "bench-007",+ name: "Session continuity after restart",+ category: "Reliability",+ passCriteria: ["State persisted", "Session recovers", "No data loss"],+ expectedDurationMs: 200,+ actualDurationMs: 180,+ actualPass: true,+ },+ {+ id: "bench-008",+ name: "API rate limiting",+ category: "Security",+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],+ expectedDurationMs: 100,+ actualDurationMs: 100,+ actualPass: true,+ },+];++// ---------------------------------------------------------------------------+// Execution simulation+// ---------------------------------------------------------------------------++function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {+ return tasks.map((task) => ({+ id: task.id,+ name: task.name,+ category: task.category,+ criteriaTotal: task.passCriteria.length,+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),+ pass: task.actualPass,+ expectedMs: task.expectedDurationMs,+ actualMs: task.actualDurationMs,+ durationDelta: task.actualDurationMs - task.expectedDurationMs,+ failureReason: task.failureReason,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(100));+ console.log(" BENCHMARK RUNNER -- Task Execution Report");+ console.log("=".repeat(100));++ const results = executeBenchmark(benchmarkTasks);++ // Detailed results+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;+ console.log("\n" + header);+ console.log(sep);++ for (const r of results) {+ const passLabel = r.pass ? "PASS" : "FAIL";+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;+ const marker = r.pass ? " " : ">>";++ console.log(+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`+ );+ }++ // Failure details+ const failures = results.filter((r) => !r.pass);+ if (failures.length > 0) {+ console.log("\n" + "-".repeat(100));+ console.log(" FAILURE DETAILS");+ console.log("-".repeat(100));+ for (const f of failures) {+ console.log(`\n [${f.id}] ${f.name}`);+ console.log(` Category: ${f.category}`);+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);+ }+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SUMMARY BY CATEGORY");+ console.log("=".repeat(100) + "\n");++ const categories = [...new Set(results.map((r) => r.category))];+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;+ console.log(catHeader);+ console.log(catSep);++ for (const cat of categories) {+ const catResults = results.filter((r) => r.category === cat);+ const catPassed = catResults.filter((r) => r.pass).length;+ const catFailed = catResults.filter((r) => !r.pass).length;+ const rate = Math.round((catPassed / catResults.length) * 100);++ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);+ }++ // Overall+ const totalPassed = results.filter((r) => r.pass).length;+ const totalFailed = results.filter((r) => !r.pass).length;+ console.log("\n" + "-".repeat(100));+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);+ console.log("=".repeat(100) + "\n");+}++run();diff --git a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdnew file mode 100644index 0000000..8a3e00a--- /dev/null+++ b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -0,0 +1,9 @@+# Ejemplo de Bucle de Limpieza++Tareas de limpieza recurrentes:++- escanear docs obsoletos+- escanear violaciones estructurales+- actualizar notas de calidad+- abrir PRs de limpieza dirigidos+- reejecutar un slice de benchmark fijo después de la limpiezadiff --git a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.tsnew file mode 100644index 0000000..6b35905--- /dev/null+++ b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts@@ -0,0 +1,336 @@+/**+ * cleanup-scanner.ts+ *+ * Scans a project directory for stale artifacts, dead code, structural+ * violations, and outputs a cleanup report. Helps enforce the "clean state+ * at end of every session" principle.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]+ * (defaults to current working directory)+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface ScanResult {+ category: string;+ check: string;+ severity: "critical" | "warning" | "info";+ found: string[];+ description: string;+}++// ---------------------------------------------------------------------------+// Scanner checks+// ---------------------------------------------------------------------------++interface ScannerCheck {+ category: string;+ name: string;+ severity: "critical" | "warning" | "info";+ description: string;+ scan: (dir: string) => string[];+}++function createChecks(): ScannerCheck[] {+ return [+ {+ category: "Stale Artifacts",+ name: "Temporary files (*.tmp, *.bak, *.swp)",+ severity: "warning",+ description: "Leftover temp files from editing or processing",+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),+ },+ {+ category: "Stale Artifacts",+ name: "Debug/log files in source",+ severity: "warning",+ description: "Log files that should not be in the source tree",+ scan: (dir) => {+ const found: string[] = [];+ const logPatterns = [".log"];+ for (const p of findFiles(dir, logPatterns)) {+ // Only flag log files in source directories+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {+ found.push(p);+ }+ }+ return found;+ },+ },+ {+ category: "Dead Code",+ name: "Unused imports (placeholder detection)",+ severity: "info",+ description: "Files that may contain unused code (heuristic scan)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app"];+ for (const srcDir of srcDirs) {+ const srcPath = path.join(dir, srcDir);+ if (fs.existsSync(srcPath)) {+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "Missing .gitignore",+ severity: "warning",+ description: "No .gitignore file found -- risk of committing build artifacts",+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],+ },+ {+ category: "Structural Violations",+ name: "Build artifacts in source",+ severity: "critical",+ description: "Compiled output (dist/, build/) mixed with source",+ scan: (dir) => {+ const found: string[] = [];+ // Check if dist/ or build/ exists inside src/+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];+ for (const d of dirs) {+ if (fs.existsSync(path.join(dir, d))) {+ found.push(d + "/");+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "node_modules in source tree",+ severity: "critical",+ description: "node_modules directory found outside root (nested dependency)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app", "test", "tests"];+ for (const srcDir of srcDirs) {+ const nmPath = path.join(dir, srcDir, "node_modules");+ if (fs.existsSync(nmPath)) {+ found.push(srcDir + "/node_modules/");+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Uncommitted changes indicator",+ severity: "info",+ description: "Checks for common artifacts of incomplete sessions",+ scan: (dir) => {+ const found: string[] = [];+ const indicators = [+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",+ "debug.ts", "test-manual.ts", "temp.ts",+ ];+ for (const f of indicators) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Empty directories",+ severity: "info",+ description: "Empty directories that may be leftover from incomplete work",+ scan: (dir) => {+ const found: string[] = [];+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];+ for (const d of commonDirs) {+ const dp = path.join(dir, d);+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {+ try {+ const contents = fs.readdirSync(dp);+ if (contents.length === 0) {+ found.push(d + "/");+ }+ } catch {+ // Skip directories we can't read+ }+ }+ }+ return found;+ },+ },+ {+ category: "Configuration",+ name: "Environment files in source",+ severity: "critical",+ description: ".env files that may contain secrets",+ scan: (dir) => {+ const found: string[] = [];+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];+ for (const f of envFiles) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ ];+}++// ---------------------------------------------------------------------------+// Helper functions+// ---------------------------------------------------------------------------++function findFiles(dir: string, extensions: string[]): string[] {+ const found: string[] = [];++ function walk(current: string, depth: number): void {+ if (depth > 4) return; // Limit recursion depth+ try {+ const entries = fs.readdirSync(current, { withFileTypes: true });+ for (const entry of entries) {+ // Skip common non-source directories+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {+ continue;+ }++ const fullPath = path.join(current, entry.name);+ const relativePath = path.relative(dir, fullPath);++ if (entry.isDirectory()) {+ walk(fullPath, depth + 1);+ } else if (entry.isFile()) {+ if (extensions.some((ext) => entry.name.endsWith(ext))) {+ found.push(relativePath);+ }+ }+ }+ } catch {+ // Skip directories we can't read+ }+ }++ walk(dir, 0);+ return found;+}++function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {+ try {+ const entries = fs.readdirSync(dir, { withFileTypes: true });+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);+ }+ continue;+ }++ const fullPath = path.join(dir, entry.name);+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {+ continue;+ }++ try {+ const content = fs.readFileSync(fullPath, "utf-8");+ const lines = content.split("\n");+ for (let i = 0; i < Math.min(lines.length, 50); i++) {+ for (const pattern of patterns) {+ if (lines[i].includes(pattern)) {+ const relative = path.relative(baseDir, fullPath);+ results.push(`${relative}:${i + 1} contains ${pattern}`);+ }+ }+ }+ } catch {+ // Skip files we can't read+ }+ }+ } catch {+ // Skip directories we can't read+ }+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");+ console.log("=".repeat(90));+ console.log(` Scanning: ${targetDir}\n`);++ const checks = createChecks();+ const results: ScanResult[] = [];++ for (const check of checks) {+ const found = check.scan(targetDir);+ results.push({+ category: check.category,+ check: check.name,+ severity: check.severity,+ found,+ description: check.description,+ });+ }++ // Report+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const count = r.found.length;+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";++ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);+ }++ // Summary+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);+ const clean = results.filter((r) => r.found.length === 0);++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SUMMARY");+ console.log("=".repeat(90) + "\n");++ console.log(` Critical issues: ${criticals.length}`);+ console.log(` Warnings: ${warnings.length}`);+ console.log(` Info items: ${infos.length}`);+ console.log(` Clean checks: ${clean.length}/${results.length}`);++ if (criticals.length > 0) {+ console.log("\n ACTION REQUIRED (Critical):");+ for (const c of criticals) {+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);+ console.log(` ${c.description}`);+ }+ }++ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);+ if (totalIssues === 0) {+ console.log("\n Project is in a clean state. No issues found.\n");+ } else {+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);+ }+}++run();diff --git a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdnew file mode 100644index 0000000..c0d6524--- /dev/null+++ b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md@@ -0,0 +1,8 @@+# Código de la Clase 12++Usa esta carpeta para ejemplos de:++- slices de benchmark+- tareas de limpieza+- ejemplos de reducción de entropía+- ejecuciones de harness repetiblesdiff --git a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdnew file mode 100644index 0000000..c9bf3cf--- /dev/null+++ b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -0,0 +1,184 @@+[中文版本 →](../../../zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)++> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)+> Proyecto práctico: [Project 06. Complete harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# Lección 12. Deja un handoff limpio al final de cada sesión++Tu agent ejecuta toda la tarde, modifica 20 archivos, hace commit del código, la sesión termina. La siguiente sesión del agent comienza y descubre inmediatamente: el build está roto, las pruebas están en rojo, los archivos temporales de debug están por todas partes, la feature list no se actualizó, y el progreso es completamente incierto. La nueva sesión dedica sus primeros 30 minutos solo a averiguar "qué hizo realmente la última sesión."++Tanto OpenAI como Anthropic afirman claramente: **la confiabilidad a largo plazo depende de la disciplina operacional, no solo del éxito en una única ejecución.** La calidad del estado al final de la sesión determina directamente la eficiencia de la siguiente sesión. Piensa en ello como las buenas prácticas de Git—cada commit debería ser un cambio atómico y compilable, no un montón de código a medio terminar.++## Conceptos clave++- **Clean state**: El sistema satisface cinco condiciones al final de la sesión—el build pasa, las pruebas pasan, el progreso está registrado, no hay artefactos obsoletos, y la ruta de inicio está disponible. Faltar cualquiera significa que la sesión no está "terminada."+- **Integridad de sesión**: Análogo a las transacciones de base de datos—o bien se hace commit completo y se deja un clean state, o se hace rollback al último estado consistente. No hay término medio.+- **Documento de calidad**: Un artefacto activo que registra continuamente las calificaciones de calidad de cada módulo. No es una evaluación única, sino un rastreador que muestra si la base de código se está fortaleciendo o debilitando con el tiempo.+- **Bucle de limpieza**: Una sesión de mantenimiento regular orientada a reducir sistemáticamente la entropía en la base de código. No es una corrección de emergencia, sino operaciones rutinarias.+- **Simplificación del harness**: A medida que mejoran las capacidades del modelo, eliminar periódicamente los componentes del harness que ya no son necesarios. Una restricción esencial hoy puede ser una sobrecarga innecesaria en tres meses.+- **Limpieza idempotente**: Las operaciones de limpieza producen el mismo resultado independientemente de cuántas veces se ejecuten. Asegura que la limpieza siga siendo segura incluso en escenarios de reintento tras fallo.++## Cinco dimensiones del clean state++```mermaid+flowchart LR+ Work["Feature work complete"] --> Build{"Build passes?"}+ Build -->|yes| Test{"Tests pass?"}+ Build -->|no| Fix["Fix before exit"]+ Test -->|yes| Record["Update feature list + progress"]+ Test -->|no| Fix+ Record --> Cleanup["Remove temp artifacts / debug code"]+ Cleanup --> Startup{"Standard startup path works?"}+ Startup -->|yes| Clean["Clean handoff"]+ Startup -->|no| Fix+ Fix --> Build+```++```mermaid+flowchart LR+ Dirty["Session ends with<br/>red tests / temp files / no progress update"] --> Diagnose["Next session first has to<br/>figure out what happened"]+ Diagnose --> Fragile["New work starts on a messy repo"]+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]+ More --> Dirty++ Clean["Session ends with<br/>green tests / updated progress / temp files removed"] --> Fast["Next session can start coding immediately"]+ Fast --> Stable["No need to rescue the repo first"]+ Stable --> Clean+```++## Por qué ocurre++### El crecimiento de la entropía es el estado por defecto++Las leyes de Lehman sobre la evolución del software nos dicen: los sistemas sometidos a cambios continuos aumentarán inevitablemente en complejidad a menos que se gestionen activamente. Esto es especialmente cierto para los agentes de codificación con IA—cada sesión introduce cambios, y sin limpieza al salir, la deuda técnica se acumula exponencialmente.++Los datos reales son reveladores. Un proyecto desarrollado con agentes durante 12 semanas, sin estrategia de limpieza:++- Semana 1: Tasa de build exitoso 100%, tasa de pruebas exitosas 100%, inicio de nueva sesión 5 min+- Semana 4: Build 95%, pruebas 92%, inicio 15 min+- Semana 8: Build 82%, pruebas 78%, inicio 35 min+- Semana 12: Build 68%, pruebas 61%, inicio 60+ min++Mismo proyecto con una estrategia de limpieza:++- Semana 1: 100%, 100%, 5 min+- Semana 12: 97%, 95%, 9 min++Después de 12 semanas: la tasa de build exitoso difiere en 29 puntos porcentuales, el tiempo de inicio de nueva sesión difiere en un 85%. Esto no es teórico—es una diferencia observada.++### Cinco dimensiones del clean state++El clean state no es solo "el código compila." Son cinco dimensiones evaluadas juntas:++**Dimensión de build**: ¿El código compila sin errores? Esto es lo más básico—la siguiente sesión no debería tener que corregir errores de build primero.++**Dimensión de pruebas**: ¿Pasán todas las pruebas? Incluyendo las pruebas que existían antes de la sesión—la sesión es responsable de no romper la funcionalidad existente. Y debería verificarse en CI, no solo "funciona en mi máquina."++**Dimensión de progreso**: ¿Está el progreso actual registrado en un artefacto legible por máquina? Subtareas completadas con sus criterios de aprobación, subtareas en progreso pero incompletas con su estado actual, subtareas aún no iniciadas. Los buenos registros de progreso reducen un 60-80% del tiempo de diagnóstico al inicio de la sesión.++**Dimensión de artefactos**: ¿Hay artefactos temporales obsoletos o ambiguos? Logs de debug, archivos temporales, código comentado, marcadores TODO—todos estos aumentan la carga cognitiva para la siguiente sesión.++**Dimensión de inicio**: ¿Está disponible la ruta de inicio estándar? ¿Puede la siguiente sesión comenzar a trabajar sin intervención manual? Inicialización del entorno, carga de la base de código, adquisición de contexto, selección de tareas—estas rutas no deben estar rotas.++### "Limpiar después" significa nunca limpiar++La trampa mental más común es "no hay tiempo para limpiar esta sesión, lo haré la próxima vez." Pero la siguiente sesión del agent no sabe lo que dejaste atrás—ve un desorden de código y un estado incierto. Dedicará un tiempo significativo a inferir "qué partes de este código son intencionales y cuáles son temporales."++Peor aún, cada sesión tiene sus propios objetivos de tarea. La nueva sesión está ahí para hacer trabajo nuevo, no para limpiar el desastre de la sesión anterior. Ignorará el caos y comenzará trabajo nuevo encima de él, introduciendo más caos sobre el caos. Este es el bucle de retroalimentación positiva de la entropía.++## Cómo hacerlo bien++### 1. Clean state como requisito de finalización++Define explícitamente en el harness: **finalización de sesión = la tarea pasa la verificación Y la verificación de clean state pasa.** Faltar cualquiera de las dos significa que la sesión no está completa. Escríbelo en CLAUDE.md:++```+## Session Exit Checklist+- [ ] Build passes (npm run build)+- [ ] All tests pass (npm test)+- [ ] Feature list updated+- [ ] No debug code remaining (console.log, debugger, TODO)+- [ ] Standard startup path available (npm run dev)+```++### 2. Estrategia de limpieza en modo dual++Combina dos modos de limpieza:++**Limpieza inmediata (al final de cada sesión)**: Limpiar artefactos temporales creados durante la sesión, actualizar el estado de la feature list, asegurar que el build y las pruebas pasen. Esta es limpieza de "conteo de referencias."++**Limpieza periódica (semanal)**: Escaneo completo del sistema—manejar problemas estructurales acumulados, actualizar documentos de calidad, ejecutar pruebas de referencia para detectar desviaciones. Esta es limpieza de "trazado."++### 3. Mantener un documento de calidad++Un documento de calidad es un artefacto activo que califica continuamente cada módulo:++```markdown+# Quality Document++## User Authentication Module (Quality: A)+- Verification passing: Yes+- Agent understandable: Yes+- Test stability: Stable+- Architecture boundaries: Compliant+- Code conventions: Followed++## Payment Module (Quality: C)+- Verification passing: Partial (payment callback untested)+- Agent understandable: Difficult (logic spread across 3 files)+- Test stability: Unstable (2 flaky tests)+- Architecture boundaries: Violations present+- Code conventions: Partially followed+```++Las nuevas sesiones leen este documento e inmediatamente saben dónde priorizar. Corrige primero el módulo con la calificación más baja.++### 4. Simplificar periódicamente el harness++Una perspectiva importante de Anthropic: **cada componente del harness existe porque el modelo no puede hacer algo de manera confiable por sí solo. Pero a medida que los modelos mejoran, estos supuestos se vuelven obsoletos.** Una restricción esencial hace tres meses puede ser una sobrecarga innecesaria hoy.++Práctica recomendada: Cada mes, elige un componente del harness, desactívalo temporalmente, y ejecuta tareas de referencia. Si los resultados no se degradan, elimínalo permanentemente. Si se degradan, restáuralo o reemplázalo con una alternativa más ligera.++### 5. Las operaciones de limpieza deben ser idempotentes++Los scripts de limpieza deben ser seguros para ejecutar repetidamente:++```bash+# Idempotent cleanup operations+rm -f /tmp/debug-*.log # -f ensures no error when files don't exist+git checkout -- .env.local # Restore to known state+npm run test # Verify cleanup didn't break anything+```++## Caso del mundo real++Una aplicación Electron desarrollada con agentes durante 12 semanas, comparando dos enfoques:++**Sin estrategia de limpieza** (grupo de control): Semana 12, tasa de build exitoso 68%, tasa de pruebas exitosas 61%, inicio de nueva sesión 60+ min, artefactos obsoletos 103.++**Con estrategia de limpieza** (grupo experimental): Verificación completa de clean state al final de cada sesión + bucle de limpieza semanal. Semana 12, tasa de build exitoso 97%, tasa de pruebas exitosas 95%, inicio de nueva sesión 9 min, artefactos obsoletos 11.++En la semana 12, la tasa de build exitoso del grupo experimental es 29 puntos porcentuales más alta, la tasa de pruebas exitosas 34 puntos más alta, y el tiempo de inicio de nueva sesión un 85% menor.++## Ideas clave++- **El clean state es una condición necesaria para la finalización de la sesión**—no es limpieza opcional, sino parte de la "definición de terminado."+- **Las cinco dimensiones son todas necesarias**—build, pruebas, progreso, artefactos, inicio—cada una debe verificarse explícitamente.+- **Los documentos de calidad hacen rastreable la salud de la base de código**—solo puedes arreglar lo que sabes que se está degradando.+- **Simplificar periódicamente el harness**—a medida que mejoran las capacidades del modelo, elimina las restricciones que ya no son necesarias.+- **"Limpiar después" equivale a nunca limpiar**—el crecimiento de la entropía es el estado por defecto; solo la limpieza activa lo contrarresta.++## Lecturas adicionales++- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — Principios sistemáticos de limpieza del código+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Reproducibilidad como requisito central de diseño del harness+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — El papel crítico de las salidas de sesión limpias para la confiabilidad a largo plazo+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — Las leyes de evolución del software que demuestran que la complejidad del sistema inevitablemente crece sin mantenimiento activo++## Ejercicios++1. **Checklist de clean state**: Diseña un checklist de salida de sesión para tu base de código que cubra las cinco dimensiones. Aplícalo durante 5 sesiones consecutivas y registra las violaciones por dimensión.++2. **Comparación de referencia**: Usa un conjunto fijo de tareas con dos variantes de harness (con/sin requisitos de clean state). Compara la tasa de finalización, la cantidad de reintentos y la tasa de escape de defectos.++3. **Práctica de simplificación del harness**: Elige un componente del harness, desactívalo temporalmente, y ejecuta tareas de referencia. Compara los resultados con y sin él. Decide si mantenerlo, eliminarlo o reemplazarlo.diff --git a/docs/es/projects/index.md b/docs/es/projects/index.mdnew file mode 100644index 0000000..eda7f11--- /dev/null+++ b/docs/es/projects/index.md@@ -0,0 +1,23 @@+# Bienvenido a Proyectos++Esta es la sección práctica de Learn Harness Engineering. Leer las lecciones no basta: necesitas construir los entornos tú mismo y observar cómo se comportan Codex, Claude Code u otros agentes de IA bajo reglas distintas.++## Resumen de proyectos++El curso incluye 6 proyectos prácticos y progresivos que enseñan a construir desde cero un entorno agentic fiable:++1. **Solo prompt vs reglas primero**: compara el rendimiento de un agente con solo un prompt frente a un harness básico.+2. **Workspace legible para el agente**: aprende a estructurar el repositorio para que sea cómodo para la IA y a establecer mecanismos de handoff.+3. **Continuidad entre sesiones**: diseña archivos de estado y scripts de inicialización para que el agente pueda reanudar el trabajo entre sesiones.+4. **Feedback de runtime y control de alcance**: introduce herramientas que permiten al agente probar su propio código y corregir errores durante la ejecución.+5. **Autoverificación y separación de roles**: construye un mecanismo de revisión independiente para evitar alucinaciones y declaraciones prematuras de éxito.+6. **Harness completo (capstone)**: ensambla un entorno final de trabajo agentic observable y end-to-end.++## Cómo avanzar++Cada carpeta de proyecto suele contener:+- `starter/`: tu workspace inicial.+- `solution/`: una implementación de referencia si te atascas.+- Instrucciones de tarea con contexto y objetivos concretos.++Usa tu AI Coding Agent preferido, por ejemplo Claude Code, Cursor o Trae, para completar las tareas dentro del directorio `starter/`.diff --git a/docs/es/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/es/projects/project-01-baseline-vs-minimal-harness/index.mdnew file mode 100644index 0000000..d986d20--- /dev/null+++ b/docs/es/projects/project-01-baseline-vs-minimal-harness/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-01-baseline-vs-minimal-harness/)++> Lecciones relacionadas: [Lección 01. Los modelos fuertes no significan ejecución fiable](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [Lección 02. Qué significa realmente harness](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)+> Archivos de plantilla: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/resources/templates/)++# Proyecto 01. Solo prompt vs reglas primero: cuánta diferencia produce++## Qué harás++Construye el esqueleto mínimo de una aplicación Electron de base de conocimiento: una ventana con lista de documentos a la izquierda, panel de Q&A a la derecha y un directorio de datos local. La tarea no es compleja. Lo complejo es cómo consigues que el agente la complete.++La ejecutarás dos veces. Primera vez: solo un prompt, sin preparación. Segunda vez: con `AGENTS.md`, `init.sh` y `feature_list.json` ya colocados en el repositorio. Luego compara.++El núcleo de este proyecto no es escribir código, sino descubrir cuánta distancia hay entre "dedicar 15 minutos a preparar reglas primero" y "dejar que el agente avance sin más".++## Herramientas++- Claude Code o Codex (elige uno y úsalo en ambas ejecuciones)+- Git (gestionar ramas y comparar)+- Node.js + Electron (stack del proyecto)+- Un temporizador (registrar la duración de cada ejecución)++## Mecanismo de harness++Harness mínimo: `AGENTS.md` + `init.sh` + `feature_list.json`diff --git a/docs/es/projects/project-02-agent-readable-workspace/index.md b/docs/es/projects/project-02-agent-readable-workspace/index.mdnew file mode 100644index 0000000..10b2e02--- /dev/null+++ b/docs/es/projects/project-02-agent-readable-workspace/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-02-agent-readable-workspace/)++> Lecciones relacionadas: [Lección 03. Convierte el repositorio en tu única fuente de verdad](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [Lección 04. Divide las instrucciones en varios archivos](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+> Archivos de plantilla: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/resources/templates/)++# Proyecto 02. Haz el proyecto legible y retoma el trabajo donde lo dejaste++## Qué harás++Añade "legibilidad" al repositorio para que un agente nuevo pueda entender rápidamente la estructura del proyecto, conocer el progreso actual y retomar el trabajo. En concreto: implementa importación de documentos, vista de detalle y persistencia local, completado en dos sesiones.++Lo ejecutarás dos veces: primero sin ayuda, y después con `ARCHITECTURE.md`, `PRODUCT.md` y `session-handoff.md` ya colocados en el repositorio.++## Herramientas++- Claude Code o Codex+- Git+- Node.js + Electron++## Mecanismo de harness++Workspace legible para el agente + archivos de estado persistentesdiff --git a/docs/es/projects/project-03-multi-session-continuity/index.md b/docs/es/projects/project-03-multi-session-continuity/index.mdnew file mode 100644index 0000000..5803e61--- /dev/null+++ b/docs/es/projects/project-03-multi-session-continuity/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-03-multi-session-continuity/)++> Lecciones relacionadas: [Lección 05. Mantén vivo el contexto entre sesiones](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [Lección 06. Inicializa antes de cada sesión del agente](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+> Archivos de plantilla: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/resources/templates/)++# Proyecto 03. Mantén al agente trabajando tras reiniciar sesiones++## Qué harás++Añade control de alcance y gates de verificación al agente. Implementa particionado de documentos, extracción de metadatos, visualización del progreso de indexación y flujo de Q&A con citas. Usa `feature_list.json` para seguir el estado de las funciones: una función a la vez, sin marcar `pass` sin evidencia de verificación.++Lo ejecutarás dos veces: primero sin restricciones, luego con aplicación estricta de reglas.++## Herramientas++- Claude Code o Codex+- Git+- Node.js + Electron++## Mecanismo de harness++Registro de progreso + handoff de sesión + continuidad multi-sesióndiff --git a/docs/es/projects/project-04-incremental-indexing/index.md b/docs/es/projects/project-04-incremental-indexing/index.mdnew file mode 100644index 0000000..3364c15--- /dev/null+++ b/docs/es/projects/project-04-incremental-indexing/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-04-incremental-indexing/)++> Lecciones relacionadas: [Lección 07. Define límites claros de tarea para los agentes](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [Lección 08. Usa listas de funciones para restringir lo que hace el agente](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+> Archivos de plantilla: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/resources/templates/)++# Proyecto 04. Usa feedback de runtime para corregir el comportamiento del agente++## Qué harás++Añade observabilidad de runtime, como logs de arranque, logs de importación/indexación y estados de error, además de restricciones arquitectónicas para evitar violaciones entre capas. Introduce un bug de runtime para que el agente lo corrija.++Lo ejecutarás dos veces: primero sin logs ni restricciones, después con herramientas y reglas adecuadas.++## Herramientas++- Claude Code o Codex+- Git+- Node.js + Electron++## Mecanismo de harness++Feedback de runtime + control de alcance + indexación incrementaldiff --git a/docs/es/projects/project-05-grounded-qa-verification/index.md b/docs/es/projects/project-05-grounded-qa-verification/index.mdnew file mode 100644index 0000000..153e81d--- /dev/null+++ b/docs/es/projects/project-05-grounded-qa-verification/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-05-grounded-qa-verification/)++> Lecciones relacionadas: [Lección 09. Evita que los agentes declaren victoria demasiado pronto](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [Lección 10. Solo una ejecución de pipeline completo cuenta como verificación real](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+> Archivos de plantilla: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/resources/templates/)++# Proyecto 05. Haz que el agente verifique su propio trabajo++## Qué harás++Implementa separación de roles: un generator que implementa, un evaluator que revisa y opcionalmente un planner. Ejecuta tres veces para medir el efecto de cada rol añadido.++Elige una mejora sustancial de función, como conversación multi-turno, rediseño del panel de citas o filtrado de documentos, y mantenla igual en todas las ejecuciones.++## Herramientas++- Claude Code o Codex+- Git+- Node.js + Electron++## Mecanismo de harness++Autoverificación + Q&A con fundamento + finalización basada en evidenciadiff --git a/docs/es/projects/project-06-runtime-observability-and-debugging/index.md b/docs/es/projects/project-06-runtime-observability-and-debugging/index.mdnew file mode 100644index 0000000..d1e9ebf--- /dev/null+++ b/docs/es/projects/project-06-runtime-observability-and-debugging/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-06-runtime-observability-and-debugging/)++> Lecciones relacionadas: [Lección 11. Haz observable el runtime del agente](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [Lección 12. Handoff limpio al final de cada sesión](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+> Archivos de plantilla: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/es/resources/templates/)++# Proyecto 06. Construye un harness completo para agentes (capstone)++## Qué harás++Este es el proyecto final. Ensambla todo lo aprendido en los primeros cinco proyectos, ejecuta un benchmark completo y luego haz una pasada de limpieza para verificar que la calidad sea mantenible.++Usa un conjunto fijo de tareas multi-función que cubra una porción completa del producto: importación de documentos, indexación, Q&A con citas, observabilidad de runtime y estado de repositorio legible y reiniciable. Primero ejecuta con un baseline de harness débil, luego con tu harness más fuerte, después limpia y vuelve a ejecutar. Finalmente, realiza un experimento de ablación del harness: elimina un componente cada vez y observa cuáles importan realmente.++## Herramientas++- Claude Code o Codex+- Git+- Node.js + Electron+- Plantilla de documento de calidad+- Rúbrica de evaluación+- Todos los componentes de harness acumulados en los primeros cinco proyectos++## Mecanismo de harness++Harness completo: todos los mecanismos + observabilidad + estudio de ablacióndiff --git a/docs/es/resources/index.md b/docs/es/resources/index.mdnew file mode 100644index 0000000..e276d2e--- /dev/null+++ b/docs/es/resources/index.md@@ -0,0 +1,50 @@+# Biblioteca de recursos en español++Esta carpeta convierte los métodos del curso en plantillas listas para copiar y referencias compactas que puedes usar en un repositorio real.++## Cuándo usarla++Empieza aquí cuando quieras que Codex, Claude Code u otro agente de programación trabaje durante varias sesiones sin tener que redescubrir constantemente el setup, el estado y el alcance.++Es especialmente útil cuando:++- el trabajo abarca varias sesiones+- hay muchas funciones y es fácil dejarlas a medias+- los agentes tienden a declarar victoria demasiado pronto+- los pasos de arranque se redescubren cada vez++## Empieza aquí++Para una configuración mínima, empieza con:++- instrucciones raíz: [`templates/AGENTS.md`](./templates/AGENTS.md) o [`templates/CLAUDE.md`](./templates/CLAUDE.md)+- estado de funciones: [`templates/feature_list.json`](./templates/feature_list.json)+- registro de progreso: [`templates/claude-progress.md`](./templates/claude-progress.md)+- referencia del script de arranque: `docs/es/resources/templates/init.sh`++Luego añade:++- handoff de sesión: [`templates/session-handoff.md`](./templates/session-handoff.md)+- checklist de salida limpia: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)+- rúbrica de evaluación: [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)++Si quieres una estructura de repositorio más completa al estilo OpenAI del artículo "Harness engineering", usa el paquete avanzado:++- [`openai-advanced/index.md`](./openai-advanced/index.md)++## Estructura de la biblioteca++- [`templates/`](./templates/index.md): plantillas para copiar en un repositorio real+- [`reference/`](./reference/index.md): notas de método, flujo de arranque y mapas de modos de fallo+- [`openai-advanced/`](./openai-advanced/index.md): esqueleto avanzado de repositorio, documentos system-of-record y plantillas de gobernanza agent-first++## Paquete mínimo recomendado++- `AGENTS.md` o `CLAUDE.md`+- `feature_list.json`+- `claude-progress.md`+- `init.sh`++Estos cuatro archivos bastan para hacer que la mayoría de los flujos con agentes sean notablemente más estables.++Cuando el repositorio crezca hasta convertirse en un sistema de larga duración con varios dominios, planes activos, puntuación de calidad y políticas de fiabilidad, pasa al paquete [`openai-advanced/`](./openai-advanced/index.md) en lugar de estirar demasiado el paquete mínimo.diff --git a/docs/es/resources/openai-advanced/index.md b/docs/es/resources/openai-advanced/index.mdnew file mode 100644index 0000000..ff03b01--- /dev/null+++ b/docs/es/resources/openai-advanced/index.md@@ -0,0 +1,79 @@+# Pack Avanzado de OpenAI++Esta carpeta empaqueta la estructura de repositorio más opinionada descrita en+el artículo de OpenAI "Harness engineering: leveraging Codex in an agent-first world"+en archivos de inicio listos para copiar.++Usa este pack cuando el harness mínimo ya no sea suficiente y tu repositorio+ahora necesite:++- un `AGENTS.md` corto estilo enrutador+- docs duraderos de sistema de registro dentro del repositorio+- planes de ejecución activos y completados+- archivos explícitos de políticas de producto, fiabilidad, seguridad y frontend+- puntuación de calidad por dominio de producto y capa arquitectónica+- carpetas de material de referencia amigable para modelos+- procedimientos operativos estándar para arquitectura, captura de conocimiento y validación en runtime++## Diseño de Inicio Incluido++El pack de inicio en [`repo-template/`](./repo-template/index.md) refleja la+siguiente estructura:++```text+AGENTS.md+ARCHITECTURE.md+docs/+├── design-docs/+│ ├── index.md+│ └── core-beliefs.md+├── exec-plans/+│ ├── active/+│ ├── completed/+│ └── tech-debt-tracker.md+├── generated/+│ └── db-schema.md+├── product-specs/+│ ├── index.md+│ └── new-user-onboarding.md+├── references/+│ ├── design-system-reference-llms.txt+│ ├── nixpacks-llms.txt+│ └── uv-llms.txt+├── DESIGN.md+├── FRONTEND.md+├── PLANS.md+├── PRODUCT_SENSE.md+├── QUALITY_SCORE.md+├── RELIABILITY.md+└── SECURITY.md+```++## Cómo Adoptarlo++1. Comienza con el pack mínimo si tu repositorio aún es pequeño.+2. Copia los archivos en [`repo-template/`](./repo-template/index.md) a tu+ propio repositorio cuando necesites una estructura más fuerte.+3. Mantén `AGENTS.md` corto. Trátalo como un enrutador hacia los docs más profundos, no como una enciclopedia.+4. Actualiza los docs de calidad, fiabilidad y planes como parte del trabajo normal, no como un día de limpieza separado.+5. Mantén los artefactos generados y las referencias externas explícitos para que los agentes puedan encontrarlos sin depender del historial de chat.++## Biblioteca de SOPs++La carpeta [`sops/`](./sops/index.md) convierte los diagramas del artículo en+procedimientos operativos paso a paso:++- configuración de arquitectura de dominios por capas+- codificación de conocimiento no visto en el repositorio+- stack de observabilidad local y flujo de trabajo de bucle de retroalimentación+- bucle de validación con Chrome DevTools para trabajo de UI++## Principios de Diseño++- Punto de entrada corto, docs más profundos enlazados+- Repositorio como sistema de registro+- Verificaciones mecánicas sobre reglas memorizadas+- Planes e historial de calidad viven junto al código+- Limpieza y simplificación son responsabilidades de primera clase++Este pack es intencionalmente opinionado, pero debe adaptarse a tu proyecto en lugar de copiarse a ciegas.diff --git a/docs/es/resources/openai-advanced/repo-template/AGENTS.md b/docs/es/resources/openai-advanced/repo-template/AGENTS.mdnew file mode 100644index 0000000..881994f--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/AGENTS.md@@ -0,0 +1,61 @@+# AGENTS.md++Este repositorio está optimizado para trabajo de agentes de codificación de larga duración. Mantén este+archivo corto. Úsalo como la capa de enrutamiento hacia los documentos del sistema de referencia, no como un+volcado gigante de instrucciones.++## Flujo de inicio++Antes de cambiar código:++1. Confirma la raíz del repositorio con `pwd`.+2. Lee `ARCHITECTURE.md` para el mapa actual del sistema y las reglas estrictas de dependencia.+3. Lee `docs/QUALITY_SCORE.md` para ver qué dominios o capas son más débiles.+4. Lee `docs/PLANS.md`, luego abre el plan activo en el que estás trabajando.+5. Lee la especificación de producto relevante en `docs/product-specs/`.+6. Ejecuta la ruta estándar de arranque y verificación para este repositorio.+7. Si la verificación basal está fallando, repara la línea base antes de agregar alcance.++## Mapa de enrutamiento++- `ARCHITECTURE.md`: mapa de dominio, modelo de capas, reglas de dependencia+- `docs/design-docs/index.md`: decisiones de diseño y creencias fundamentales+- `docs/product-specs/index.md`: comportamientos actuales del producto y criterios de aceptación+- `docs/PLANS.md`: ciclo de vida de planes y política de planes de ejecución+- `docs/QUALITY_SCORE.md`: salud de dominios de producto y capas+- `docs/RELIABILITY.md`: señales en tiempo de ejecución, benchmarks y expectativas de reinicio+- `docs/SECURITY.md`: secretos, sandbox, datos y reglas de acciones externas+- `docs/FRONTEND.md`: restricciones de UI, reglas del sistema de diseño, verificaciones de accesibilidad++## Contrato de trabajo++- Trabaja desde un plan delimitado o una porción de funcionalidad a la vez.+- No marques el trabajo como completado solo por inspección de código; se requiere+ evidencia ejecutable.+- Si cambias un comportamiento, actualiza los documentos de producto, plan o fiabilidad+ correspondientes en la misma sesión.+- Si ves comentarios de revisión repetidos, promuévelos a una regla mecánica, verificación+ o linter en lugar de volver a explicarlo en el chat.+- Mantén el material generado en `docs/generated/` y las referencias fuente en+ `docs/references/`.+- Prefiere agregar documentos pequeños y actuales en lugar de hacer crecer este archivo.++## Definición de completado++Un cambio está completo solo cuando todas las siguientes condiciones son verdaderas:++- el comportamiento objetivo está implementado+- la verificación requerida se ejecutó realmente+- la evidencia está vinculada desde el plan o documento de calidad relevante+- los documentos afectados permanecen actualizados+- el repositorio puede reiniciarse limpiamente desde la ruta de inicio estándar++## Fin de sesión++Antes de terminar una sesión:++1. Actualiza el plan de ejecución activo.+2. Actualiza `docs/QUALITY_SCORE.md` si algún dominio o capa cambió significativamente.+3. Registra nueva deuda técnica en `docs/exec-plans/tech-debt-tracker.md` si la pospusiste.+4. Mueve los planes terminados a `docs/exec-plans/completed/` cuando sea apropiado.+5. Deja el repositorio en un estado reiniciable con una próxima acción clara.diff --git a/docs/es/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/es/resources/openai-advanced/repo-template/ARCHITECTURE.mdnew file mode 100644index 0000000..a611cac--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -0,0 +1,57 @@+# ARCHITECTURE.md++Este archivo es el mapa de nivel superior del sistema. Debe mantenerse conciso y apuntar+a documentos más profundos cuando sea necesario.++## Forma del sistema++- Producto: `[replace with product name]`+- Flujo de usuario principal: `[replace with main workflow]`+- Superficies de ejecución: `[desktop / web / cli / services / workers]`+- Fuente de verdad para el comportamiento del producto: `docs/product-specs/`++## Mapa de dominios++| Dominio | Propósito | Puntos de entrada principales | Spec relacionada |+|---------|-----------|-------------------------------|------------------|+| `[domain-a]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |+| `[domain-b]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |++## Modelo de capas++Usa un modelo direccional fijo para que los agentes no inventen arquitectura ad hoc:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++Las preocupaciones transversales deben entrar a través de límites explícitos de proveedor o+adaptador en lugar de alcanzar directamente a través de las capas.++## Reglas estrictas de dependencia++- Las capas inferiores no deben depender de las capas superiores.+- La UI no debe evadir los contratos de tiempo de ejecución o de servicio.+- El acceso a datos debe ingresar a través de repositorios o adaptadores equivalentes.+- Las utilidades compartidas deben permanecer genéricas y no deben acumular lógica de dominio.+- Las nuevas dependencias deben justificarse en el plan o documento de diseño correspondiente.++## Interfaces transversales++| Preocupación | Límite aprobado | Notas |+|-------------|-----------------|-------|+| Logging y trazabilidad | `[provider / utility path]` | `[structured only, no ad hoc console use]` |+| Autenticación | `[provider path]` | `[token/session rules]` |+| APIs externas | `[client or provider path]` | `[rate limit / retry guidance]` |+| Feature flags | `[flag boundary]` | `[ownership]` |++## Puntos calientes actuales++- `[area that is hardest for agents to change safely]`+- `[area with weak boundaries or fragile tests]`++## Lista de verificación de cambios++Cuando modifiques código relevante para la arquitectura:++1. Actualiza este archivo si el mapa de dominios o los límites permitidos cambiaron.+2. Actualiza el documento de diseño relacionado en `docs/design-docs/` si el razonamiento cambió.+3. Agrega o actualiza una verificación ejecutable si la regla debe aplicarse mecánicamente.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/es/resources/openai-advanced/repo-template/docs/DESIGN.mdnew file mode 100644index 0000000..7c0c794--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/DESIGN.md@@ -0,0 +1,28 @@+# DESIGN.md++Este archivo es el punto de entrada de diseño. Mantenlo breve y úsalo para enrutar hacia los+archivos más detallados en `docs/design-docs/`.++## Propósito++Registrar decisiones duraderas de diseño de producto y sistema que deberían sobrevivir más allá de+una sola conversación, sprint o memoria de revisor.++## Lee esto cuando++- necesites la filosofía de diseño actual+- estés a punto de introducir un nuevo patrón+- necesites saber qué decisiones de diseño están resueltas frente a las que aún están abiertas++## Documentos de diseño canónicos++- `docs/design-docs/index.md`: índice de documentos aceptados, propuestos y deprecados+- `docs/design-docs/core-beliefs.md`: creencias agent-first a nivel de proyecto++## Reglas de diseño++- Mantén los documentos de diseño pequeños y actualizados.+- Prefiere un documento por área de decisión.+- Vincula los documentos de diseño desde planes y especificaciones cuando un cambio depende de ellos.+- Si una regla de diseño se vuelve operativamente crítica, promuévela a una verificación+ automatizada o actualiza `ARCHITECTURE.md`.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/es/resources/openai-advanced/repo-template/docs/FRONTEND.mdnew file mode 100644index 0000000..3dab26a--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/FRONTEND.md@@ -0,0 +1,24 @@+# FRONTEND.md++Este archivo define expectativas estables del frontend para que los agentes no inventen+patrones de UI de forma impredecible.++## Principios de UI++- Optimiza para la claridad antes que para la novedad.+- Mantén los flujos de interacción descubribles y reiniciables.+- Prefiere un pequeño número de componentes reutilizables sobre variantes de un solo uso.+- Las verificaciones de accesibilidad son parte de la verificación normal, no trabajo de pulido.++## Barreras de protección++- Documenta el sistema de diseño o la biblioteca de componentes en `docs/references/`.+- Registra los estados clave visibles para el usuario: vacío, cargando, éxito, error, reintento.+- Mantén el texto, el comportamiento del teclado y la jerarquía visual consistentes entre flujos.+- Cuando se corrija un error de UI, agrega o actualiza el paso de validación correspondiente.++## Expectativas de verificación++- Captura evidencia para los recorridos de usuario críticos.+- Registra los pasos de validación del navegador o tiempo de ejecución en el plan relevante.+- Si las regresiones visuales son comunes, estandariza las verificaciones de capturas de pantalla o DOM.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/es/resources/openai-advanced/repo-template/docs/PLANS.mdnew file mode 100644index 0000000..107ff46--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/PLANS.md@@ -0,0 +1,34 @@+# PLANS.md++Este archivo define cómo se crean, actualizan, completan y archivan los planes de ejecución.++## Cuándo Se Requiere Un Plan++Crea un plan de ejecución cuando el trabajo:++- abarca más de una sesión+- modifica más de un subsistema+- tiene riesgos no triviales de verificación o despliegue+- depende de decisiones abiertas que deben registrarse++## Ubicaciones de Planes++- `docs/exec-plans/active/`: planes que actualmente dirigen el trabajo+- `docs/exec-plans/completed/`: planes finalizados conservados para contexto futuro del agente+- `docs/exec-plans/tech-debt-tracker.md`: trabajo pospuesto y seguimientos++## Secciones Mínimas del Plan++- objetivo+- alcance y fuera de alcance+- ruta de verificación+- riesgos y bloqueos+- registro de progreso+- decisiones abiertas++## Reglas de Operación++- Un plan activo debe tener un paso actual claramente asignado.+- Actualiza el plan a medida que avanza el trabajo; no lo trates como texto estático.+- Si una decisión cambia la dirección de implementación, regístrala en el plan.+- Mueve los planes finalizados a `completed/` para que los agentes puedan descubrir el contexto previo.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/es/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.mdnew file mode 100644index 0000000..123fe67--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md@@ -0,0 +1,25 @@+# PRODUCT_SENSE.md++Este archivo captura el criterio de producto duradero que los agentes no pueden inferir+confiablemente solo desde el código.++## Núcleo del Producto++- Usuario principal: `[reemplazar]`+- Trabajo por hacer: `[reemplazar]`+- Frustración principal a eliminar: `[reemplazar]`+- Nivel de calidad para aceptación: `[reemplazar]`++## Reglas de Producto++- Favorecer la fiabilidad visible para el usuario sobre la cantidad de funcionalidades.+- Tratar el comportamiento ambiguo como un vacío de especificación, no como permiso para adivinar.+- Si la implementación cambia lo que los usuarios ven o confían, actualizar la spec correspondiente.+- Usar specs de producto para flujos concretos, y usar este archivo para prioridades de producto transversales.++## Patrones de No-Acción++- Acciones destructivas ocultas+- Fallo silencioso sin retroalimentación al usuario+- Fuente de verdad poco clara para estado visible+- Funcionalidades que no se pueden explicar en una sola frasediff --git a/docs/es/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/es/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.mdnew file mode 100644index 0000000..a03d628--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md@@ -0,0 +1,39 @@+# QUALITY_SCORE.md++Este documento realiza un seguimiento de si el repositorio se está fortaleciendo o debilitando con el tiempo.++## Escala de Calificación++- `A`: verificado, legible, estable, límites enforcementados+- `B`: funcionando con brechas menores+- `C`: parcialmente funcionando, confusión o inestabilidad notable+- `D`: roto, inseguro o estructuralmente poco claro++## Dominios de Producto++| Dominio | Calificación | Verificación | Legibilidad del Agente | Estabilidad de Tests | Brechas Clave | Última Actualización |+|---------|-------------|-------------|----------------------|---------------------|---------------|---------------------|+| `[domain-a]` | - | - | - | - | - | - |+| `[domain-b]` | - | - | - | - | - | - |+| `[domain-c]` | - | - | - | - | - | - |++## Capas Arquitectónicas++| Capa | Calificación | Enforcement de Límites | Legibilidad del Agente | Brechas Clave | Última Actualización |+|------|-------------|----------------------|----------------------|---------------|---------------------|+| Types | - | - | - | - | - |+| Services | - | - | - | - | - |+| Runtime | - | - | - | - | - |+| UI | - | - | - | - | - |++## Instantáneas de Benchmark++| Fecha | Variante del Harness | Tasa de Completitud | Reintentos | Defectos Antes de Revisión | Notas |+|------|---------------------|-------------------|-----------|---------------------------|------|+| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |++## Registro de Simplificación++| Fecha | Componente Eliminado | Resultado | Decisión |+|------|---------------------|----------|----------|+| YYYY-MM-DD | `[component]` | `[degraded / unchanged]` | `[restore / keep removed]` |diff --git a/docs/es/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/es/resources/openai-advanced/repo-template/docs/RELIABILITY.mdnew file mode 100644index 0000000..ac078e0--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/RELIABILITY.md@@ -0,0 +1,32 @@+# RELIABILITY.md++Este archivo define cómo el sistema demuestra que está saludable y es reiniciable.++## Rutas Estándar++- Arranque: `[command]`+- Verificación: `[command]`+- Iniciar aplicación o servicio: `[command]`+- Depurar o inspeccionar tiempo de ejecución: `[command]`++## Señales Requeridas en Tiempo de Ejecución++- logs estructurados para inicio y flujos críticos+- verificaciones de salud para servicios clave+- datos de traza o tiempo para rutas lentas cuando estén disponibles+- estados de error visibles para el usuario para fallos recuperables++## Recorridos Dorados++- `[journey 1]`+- `[journey 2]`+- `[journey 3]`++Cada recorrido dorado debe tener una ruta de verificación repetible y señales de fallo claras.++## Reglas de Fiabilidad++- Ninguna característica está completa si el sistema no puede reiniciarse limpiamente después.+- Los fallos en tiempo de ejecución deben ser diagnosticables desde señales locales del repositorio.+- Si aparece un modo de fallo repetido, añade un benchmark o barrera de protección para él.+- La limpieza es parte de la fiabilidad, no una preocupación separada.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/es/resources/openai-advanced/repo-template/docs/SECURITY.mdnew file mode 100644index 0000000..927d124--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/SECURITY.md@@ -0,0 +1,27 @@+# SECURITY.md++Este archivo define las reglas de seguridad y protección que los agentes no deben adivinar.++## Secretos y Credenciales++- Nunca codifiques secretos en el código fuente o documentación.+- Documenta aquí las rutas aprobadas de carga de secretos.+- Redacta tokens, claves API y datos personales de logs y capturas de pantalla.++## Entrada No Confiable++- Trata el contenido externo como no confiable hasta que sea validado.+- Registra aquí los límites permitidos de búsqueda o ejecución.+- Si existe riesgo de inyección de prompts o inyección de comandos, documenta la barrera de protección.++## Acciones Externas++- Lista qué acciones requieren aprobación explícita.+- Registra cualquier comando de producción o destructivo que los agentes no deben ejecutar por defecto.+- Prefiere flujos de trabajo seguros en sandbox para depuración y verificación.++## Reglas de Dependencias y Revisión++- Las nuevas dependencias necesitan justificación en el plan activo.+- Los cambios sensibles a la seguridad requieren pasos de verificación explícitos.+- Los comentarios repetidos de revisión de seguridad deben convertirse en verificaciones, no en conocimiento tribal.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/es/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.mdnew file mode 100644index 0000000..78646af--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md@@ -0,0 +1,9 @@+# Creencias fundamentales++- El repositorio es el sistema de referencia para los agentes.+- `AGENTS.md` es un enrutador, no una enciclopedia.+- La evidencia de verificación importa más que la confianza.+- Una tarea delimitada es mejor que muchas tareas a medio terminar.+- Los comentarios humanos repetidos deberían convertirse en reglas de harness reutilizables.+- La limpieza y simplificación son parte de la entrega, no ideas de último momento.+- Si un agente no puede descubrir un dato dentro del repositorio, considere ese dato como operativamente no disponible.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/es/resources/openai-advanced/repo-template/docs/design-docs/index.mdnew file mode 100644index 0000000..6a75ee1--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/design-docs/index.md@@ -0,0 +1,21 @@+# Índice de documentos de diseño++Usa este índice como el mapa descubrible del historial de diseño.++## Aceptados++- `core-beliefs.md`: creencias operativas agent-first y normas duraderas del proyecto++## Propuestos++- `[add new design doc paths here]`++## Deprecados++- `[move old or superseded design docs here with replacement links]`++## Reglas de mantenimiento++- Cada documento de diseño debería tener un propietario o un disparador de actualización.+- Elimina documentos obsoletos o márcalos como deprecados en lugar de dejar que se desvíen.+- Vincula los planes de ejecución activos a los documentos de diseño de los que dependen.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/active/index.mdnew file mode 100644index 0000000..cbc60b2--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md@@ -0,0 +1,10 @@+# Planes activos++Mantén un archivo markdown por cada plan de ejecución activo en esta carpeta.++Patrón de nombre de archivo sugerido:++- `YYYY-MM-DD-short-topic.md`++Cada plan activo debería estar lo suficientemente actualizado para que una sesión nueva+de agente pueda reanudar el trabajo solo desde el repositorio.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.mdnew file mode 100644index 0000000..2be9ba3--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md@@ -0,0 +1,5 @@+# Planes Completados++Mueve los planes finalizados aquí en lugar de eliminarlos. Los planes completados son parte+de la superficie de memoria del repositorio y ayudan a ejecuciones futuras del agente a entender+por qué el código tiene el aspecto que tiene.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.mdnew file mode 100644index 0000000..4abcfac--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md@@ -0,0 +1,7 @@+# Rastreador de deuda técnica++Usa este archivo para deuda que es real, reconocida e intencionalmente pospuesta.++| Fecha | Área | Deuda | Por qué se pospuso | Riesgo | Próximo disparador |+|-------|------|-------|--------------------|--------|--------------------|+| YYYY-MM-DD | `[area]` | `[debt]` | `[reason]` | `[risk]` | `[when to revisit]` |diff --git a/docs/es/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/es/resources/openai-advanced/repo-template/docs/generated/db-schema.mdnew file mode 100644index 0000000..8a9419e--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/generated/db-schema.md@@ -0,0 +1,14 @@+# Esquema de Base de Datos++Usa esta carpeta para artefactos generados o derivados que los agentes deberían poder+inspeccionar sin necesidad de ingeniería inversa desde el código.++## Fuente++- Generado desde: `[command or source path]`+- Última actualización: `YYYY-MM-DD`++## Notas++- No edites manualmente las secciones generadas.+- Regenera este archivo cuando el esquema subyacente cambie.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/es/resources/openai-advanced/repo-template/docs/product-specs/index.mdnew file mode 100644index 0000000..4793fa0--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/product-specs/index.md@@ -0,0 +1,13 @@+# Índice de Especificaciones de Producto++Usa esta carpeta para las especificaciones actuales del comportamiento visible al usuario.++## Especificaciones Activas++- `new-user-onboarding.md`++## Reglas++- Las especificaciones deben describir el comportamiento visible al usuario y los criterios de aceptación.+- Si la implementación diverge de la especificación, actualiza una de ellas en la misma sesión.+- Mantén este índice actualizado para que un agente nuevo pueda descubrir el alcance del producto rápidamente.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/es/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.mdnew file mode 100644index 0000000..693935f--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md@@ -0,0 +1,26 @@+# Onboarding de Nuevo Usuario++## Objetivo++Describe la experiencia de primera ejecución que debería tener un usuario nuevo.++## Condiciones de Entrada++- `[state before the flow starts]`++## Flujo de Usuario++1. `[step one]`+2. `[step two]`+3. `[step three]`++## Criterios de Aceptación++- `[observable outcome]`+- `[observable outcome]`+- `[observable outcome]`++## Estados de Fallo++- `[recoverable error and user feedback]`+- `[blocked state and fallback]`diff --git a/docs/es/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/es/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txtnew file mode 100644index 0000000..6f1c612--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt@@ -0,0 +1,9 @@+Purpose: store model-friendly reference material for the design system.++Suggested contents:+- component naming rules+- spacing and typography tokens+- state variants+- accessibility expectations++Keep this file concise and refresh it when the upstream design system changes.diff --git a/docs/es/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/es/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txtnew file mode 100644index 0000000..c30cc9c--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt@@ -0,0 +1,8 @@+Purpose: store a clean agent-readable extract of the deployment or packaging+rules your repository depends on.++Suggested contents:+- build entrypoints+- runtime assumptions+- environment variable expectations+- common failure signaturesdiff --git a/docs/es/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/es/resources/openai-advanced/repo-template/docs/references/uv-llms.txtnew file mode 100644index 0000000..f2ceba9--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/docs/references/uv-llms.txt@@ -0,0 +1,8 @@+Purpose: store a compact reference for your Python package and environment+workflow when `uv` or similar tooling matters to the repo.++Suggested contents:+- install and sync commands+- lockfile policy+- virtualenv expectations+- verification commandsdiff --git a/docs/es/resources/openai-advanced/repo-template/index.md b/docs/es/resources/openai-advanced/repo-template/index.mdnew file mode 100644index 0000000..5abcb1f--- /dev/null+++ b/docs/es/resources/openai-advanced/repo-template/index.md@@ -0,0 +1,24 @@+# Plantilla de Repositorio Avanzada++Copia este starter en un repositorio real cuando quieras una superficie de documentación+agent-first estilo OpenAI en lugar de solo un harness mínimo.++## Orden de Copia++1. Copia `AGENTS.md` y `ARCHITECTURE.md` a la raíz del repositorio.+2. Copia todo el árbol `docs/`.+3. Rellena `docs/PRODUCT_SENSE.md`, `docs/QUALITY_SCORE.md` y+ `docs/RELIABILITY.md` primero.+4. Añade tu primer plan activo en `docs/exec-plans/active/`.+5. Mantén los archivos de entrada cortos y enruta el detalle a los documentos enlazados.++## Para Qué Optimiza Esta Plantilla++- contexto duradero local al repositorio+- revelación progresiva en lugar de un archivo de instrucciones gigante+- ciclo de vida explícito de planes+- seguimiento de calidad a lo largo del tiempo+- límites legibles para agentes y humanos++Trata cada archivo aquí como un starter. Reemplaza los marcadores de posición, ejemplos y comandos+de muestra con los detalles específicos de tu proyecto real antes de depender de él.diff --git a/docs/es/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/es/resources/openai-advanced/sops/chrome-devtools-validation-loop.mdnew file mode 100644index 0000000..ecea364--- /dev/null+++ b/docs/es/resources/openai-advanced/sops/chrome-devtools-validation-loop.md@@ -0,0 +1,51 @@+# SOP: Bucle de Validación con Chrome DevTools++Usa este SOP cuando el trabajo de UI depende de la interacción real en tiempo de ejecución y las capturas de pantalla,+el estado del DOM y la salida de la consola importan más que la inspección del código por sí sola.++## Objetivo++Convertir la validación de UI en un bucle de interacción repetible que el agente pueda ejecutar hasta+que el recorrido esté limpio.++## Bucle Principal++1. Selecciona la página objetivo o la instancia de la aplicación.+2. Limpia el ruido obsoleto de la consola.+3. Captura el estado ANTES.+4. Dispara la ruta de UI.+5. Observa los eventos en tiempo de ejecución durante la interacción.+6. Captura el estado DESPUÉS.+7. Aplica la corrección y reinicia la aplicación si es necesario.+8. Vuelve a ejecutar la validación hasta que el recorrido esté limpio.++## Entradas Requeridas++- un comando de inicio estable+- un recorrido de UI reproducible+- una forma de capturar el DOM, la consola o capturas de pantalla+- una regla sobre qué cuenta como "limpio"++## SOP de Ejecución++1. Escribe el recorrido objetivo en el plan activo.+2. Define el éxito en términos observables: texto presente, botón habilitado, error eliminado,+ consola limpia, solicitud exitosa.+3. Captura el estado inicial antes de la interacción.+4. Dispara exactamente una ruta a la vez.+5. Registra los eventos en tiempo de ejecución, los cambios del DOM y la salida visible.+6. Si el recorrido falla, corrige la capa responsable más pequeña y reinicia.+7. Vuelve a ejecutar la misma ruta y compara la evidencia ANTES/DESPUÉS.++## Criterios de Limpieza++- el estado visible intencionado está presente+- los errores inesperados están ausentes+- el ruido de la consola está comprendido o eliminado+- volver a ejecutar la misma ruta produce el mismo resultado++## Artefactos del Repositorio A Actualizar++- plan de ejecución activo+- `docs/RELIABILITY.md` si el recorrido se convierte en una ruta dorada+- especificación de producto si el comportamiento visible cambiódiff --git a/docs/es/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/es/resources/openai-advanced/sops/encode-knowledge-into-repo.mdnew file mode 100644index 0000000..8098711--- /dev/null+++ b/docs/es/resources/openai-advanced/sops/encode-knowledge-into-repo.md@@ -0,0 +1,45 @@+# SOP: Codificar Conocimiento No Visible En El Repositorio++Usa este SOP cuando un contexto importante todavía reside en Google Docs, hilos de chat,+tickets o en la cabeza de las personas.++## Objetivo++Hacer que el conocimiento invisible para el agente sea descubrible en el código base para que una sesión nueva+pueda actuar sobre él sin depender de una conversación previa.++## Señales de Disparo++- El agente sigue preguntando cómo funciona el sistema.+- Las personas dicen "decidimos esto en Slack" o "sigue lo que X dijo la semana pasada."+- Las revisiones referencian reglas de producto o seguridad que no están escritas en el repositorio.+- Las sesiones nuevas repiten trabajo de descubrimiento que ya debería estar resuelto.++## SOP de Ejecución++1. Lista las fuentes de conocimiento invisible: docs, chats, reglas tácitas del equipo, decisiones verbales.+2. Para cada fuente, pregunta: ¿es esto arquitectura, comportamiento de producto, política de seguridad,+ expectativa de fiabilidad, contexto de plan o material de referencia?+3. Codifícalo en el artefacto del repositorio correspondiente:+ - arquitectura -> `ARCHITECTURE.md`+ - comportamiento de producto -> `docs/product-specs/`+ - razonamiento de diseño -> `docs/design-docs/`+ - estado de ejecución -> `docs/exec-plans/`+ - referencias externas repetidas -> `docs/references/`+ - expectativas de calidad o fiabilidad -> `docs/QUALITY_SCORE.md` o `docs/RELIABILITY.md`+4. Reemplaza declaraciones vagas con redacción operacionalmente útil.+5. Elimina o deprecia copias obsoletas para que el repositorio mantenga una única verdad descubrible.++## Buenas Reglas de Codificación++- Escribe para la descubribilidad, no para la completitud literaria.+- Prefiere documentos cortos con nombres de archivo claros.+- Enlaza artefactos relacionados entre sí.+- Almacena reglas duraderas, no transcripciones de reuniones.+- Actualiza el repositorio en la misma sesión en que se toma la decisión.++## Definición de Completado++- Un agente nuevo puede descubrir la regla relevante sin preguntar a un humano.+- El mismo hecho no está disperso en múltiples archivos contradictorios.+- El nuevo artefacto reside cerca del código o flujo de trabajo que gobierna.diff --git a/docs/es/resources/openai-advanced/sops/index.md b/docs/es/resources/openai-advanced/sops/index.mdnew file mode 100644index 0000000..d6369c9--- /dev/null+++ b/docs/es/resources/openai-advanced/sops/index.md@@ -0,0 +1,25 @@+# SOPs Avanzados de OpenAI++Estos SOPs traducen los patrones operacionales del artículo en playbooks de ejecución concretos+que puedes seguir o adaptar.++## SOPs Incluidos++- [`layered-domain-architecture.md`](./layered-domain-architecture.md):+ establece capas explícitas y límites transversales+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):+ mueve el conocimiento invisible desde chat, docs y memoria a archivos locales del repositorio+- [`observability-feedback-loop.md`](./observability-feedback-loop.md):+ proporciona a los agentes logs, métricas, trazas y un bucle de depuración repetible+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):+ usa automatización del navegador y capturas para validar el comportamiento de UI hasta que esté limpio++## Cómo Usarlos++1. Elige el SOP que coincida con tu cuello de botella actual.+2. Usa la lista de verificación para configurar los artefactos o herramientas faltantes.+3. Codifica las reglas resultantes en los docs de tu copia de `repo-template/`.+4. Convierte los comentarios de revisión repetidos en verificaciones, scripts o barreras de protección.++Estos no están pensados para seguirse a ciegas. Están pensados para hacer el harness+más legible, enforcementable y repetible.diff --git a/docs/es/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/es/resources/openai-advanced/sops/layered-domain-architecture.mdnew file mode 100644index 0000000..e30a82f--- /dev/null+++ b/docs/es/resources/openai-advanced/sops/layered-domain-architecture.md@@ -0,0 +1,50 @@+# SOP: Arquitectura de Dominio en Capas++Usa este SOP cuando el agente sigue violando límites, duplicando lógica entre capas,+o produciendo código que se vuelve difícil de revisar después de algunas sesiones.++## Objetivo++Hacer que los límites del dominio sean lo suficientemente explícitos para que los agentes+puedan moverse rápidamente sin degradar silenciosamente la estructura.++## Modelo Objetivo++Dentro de un dominio de negocio, prefiere este flujo direccional:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++Las preocupaciones transversales deben entrar a través de proveedores o adaptadores explícitos.+Las utilidades compartidas permanecen fuera del dominio y no deben acumular lógica de dominio.++## Lista de Verificación de Configuración++- Define los dominios actuales en `ARCHITECTURE.md`.+- Escribe las direcciones de dependencia permitidas en `ARCHITECTURE.md`.+- Registra las interfaces transversales como auth, telemetría y APIs externas.+- Añade una nota breve para la violación de límite más difícil actualmente.+- Decide qué debe ser enforcementado mecánicamente por lint, tests o scripts.++## SOP de Ejecución++1. Mapea el código base en dominios antes de tocar el estilo de implementación.+2. Para cada dominio, identifica la secuencia de capas permitida.+3. Identifica todas las preocupaciones transversales y enrútalas a través de proveedores o adaptadores.+4. Mueve la lógica compartida ambigua al dominio propietario o a utilidades verdaderamente genéricas.+5. Documenta las reglas en `ARCHITECTURE.md`.+6. Añade una barrera de protección ejecutable para la violación de mayor costo.+7. Actualiza la puntuación de calidad después del cambio.++## Definición de Completado++- Un agente nuevo puede decir qué capa es propietaria de un cambio.+- El código de UI ya no accede directamente al repositorio o efectos secundarios externos.+- Las preocupaciones transversales tienen puntos de entrada nombrados.+- Al menos un límite importante es enforcementado mecánicamente.++## Artefactos del Repositorio A Actualizar++- `ARCHITECTURE.md`+- `docs/QUALITY_SCORE.md`+- `docs/design-docs/` cuando el razonamiento cambió+- `docs/PLANS.md` o el plan de ejecución activodiff --git a/docs/es/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/es/resources/openai-advanced/sops/observability-feedback-loop.mdnew file mode 100644index 0000000..b4e349c--- /dev/null+++ b/docs/es/resources/openai-advanced/sops/observability-feedback-loop.md@@ -0,0 +1,44 @@+# SOP: Bucle de Retroalimentación de Observabilidad++Usa este SOP cuando la depuración es lenta, los agentes siguen afirmando éxito sin+evidencia, o el comportamiento en tiempo de ejecución es más difícil de inspeccionar que el código en sí.++## Objetivo++Proporcionar al agente un bucle de retroalimentación local sobre logs, métricas, trazas y cargas de+trabajo ejecutables para que pueda razonar desde la ejecución, no solo desde la inspección del código.++## Stack Mínimo++- la aplicación emite logs estructurados+- la aplicación emite métricas y trazas cuando sea factible+- capa local de distribución o recopilación+- interfaces de consulta para logs, métricas y trazas+- carga de trabajo repetible o recorrido de usuario para volver a ejecutar después de cada cambio++## SOP de Ejecución++1. Define los recorridos dorados en tiempo de ejecución que más importan.+2. Añade logs estructurados al inicio y a la ruta crítica.+3. Añade métricas para latencia, conteos de fallos o profundidad de cola donde sea útil.+4. Añade trazas o marcadores de tiempo para flujos lentos o de múltiples pasos.+5. Haz que las señales sean consultables desde el entorno de desarrollo local.+6. Proporciona al agente una carga de trabajo o escenario repetible para volver a ejecutar.+7. Requiere el bucle: consultar -> correlacionar -> razonar -> implementar -> reiniciar ->+ volver a ejecutar -> verificar.++## Lista de Verificación de Sesión de Depuración++- ¿Qué falló?+- ¿Qué señal prueba el fallo?+- ¿Qué capa es propietaria del fallo?+- ¿Qué cambió después de la corrección?+- ¿La aplicación se reinició limpiamente?+- ¿La misma carga de trabajo pasó después de volver a ejecutar?++## Definición de Completado++- El agente puede explicar un modo de fallo a partir de evidencia en tiempo de ejecución.+- La misma carga de trabajo puede volver a ejecutarse después de cada cambio.+- Reiniciar y volver a ejecutar son parte del bucle de tareas normal.+- Las señales de fiabilidad están documentadas en `docs/RELIABILITY.md`.diff --git a/docs/es/resources/reference/coding-agent-startup-flow.md b/docs/es/resources/reference/coding-agent-startup-flow.mdnew file mode 100644index 0000000..7a84cf3--- /dev/null+++ b/docs/es/resources/reference/coding-agent-startup-flow.md@@ -0,0 +1,33 @@+# Flujo de Inicio del Agente de Codificación++Usa esto al comienzo de cada sesión después de que la inicialización esté completa.++## Plantilla de Inicio Fija++1. Ejecuta `pwd` y confirma la raíz del repositorio.+2. Lee `claude-progress.md`.+3. Lee `feature_list.json`.+4. Revisa los commits recientes con `git log --oneline -5`.+5. Ejecuta `./init.sh`.+6. Ejecuta una ruta de smoke o end-to-end de referencia.+7. Si la referencia está rota, corrígela primero.+8. Selecciona la característica inacabada de mayor prioridad.+9. Trabaja solo en esa característica hasta que esté verificada o explícitamente bloqueada.++## Por Qué Este Orden Importa++- `pwd` previene trabajo accidental en el directorio equivocado.+- los archivos de progreso y características recuperan estado duradero antes de que comiencen nuevas ediciones.+- los commits recientes explican qué cambió más recientemente.+- `init.sh` estandariza el inicio en lugar de depender de la memoria.+- la verificación de referencia captura estados iniciales rotos antes de que el trabajo nuevo los oculte.++## Espejo de Fin de Sesión++La misma sesión debería terminar:++1. registrando el progreso+2. actualizando el estado de las características+3. escribiendo una entrega si es necesario+4. haciendo commit del trabajo seguro+5. dejando una ruta de reinicio limpiadiff --git a/docs/es/resources/reference/index.md b/docs/es/resources/reference/index.mdnew file mode 100644index 0000000..715cd39--- /dev/null+++ b/docs/es/resources/reference/index.md@@ -0,0 +1,85 @@+# Referencia++Estas notas explican cómo usar las plantillas como un harness funcional en lugar de una+colección suelta de archivos.++## Notas de Referencia Interna++- [`method-map.md`](./method-map.md): mapea los modos de fallo comunes de larga duración al+ artefacto o política que los aborda primero+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md): qué debe dejar atrás el+ inicializador antes de que comience el trabajo de características+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md): flujo fijo de inicio de+ sesión para ejecuciones de codificación posteriores+- [`prompt-calibration.md`](./prompt-calibration.md): cómo mantener las instrucciones raíz+ precisas sin hacerlas hinchadas y frágiles++## Artículos Principales++Esta lista es intencionalmente estrecha. Un harness significa el sistema de ejecución alrededor+del modelo: el bucle del agente, ejecución de herramientas, sandboxing, estado, contexto,+verificación, terminación, orquestación y observabilidad. Artículos generales de ingeniería+de prompts o de frameworks amplios de agentes no pertenecen a la lista principal.++Los tres artículos originales siguen siendo la columna vertebral del curso:++- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) (2026-02-11): repositorios agent-first, contexto repo-local, linting personalizado y barreras de protección estructurales.+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (2025-11-26): agente inicializador, agente de codificación, lista de características, registro de progreso y entrega a través de ventanas de contexto.+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) (2026-03-24): roles de planificador / generador / evaluador, reinicios de contexto, simplificación del harness y supuestos obsoletos.++Solo se añaden algunos artículos altamente relevantes de 2026:++- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/) (2026-01-23): el harness de tiempo de ejecución de Codex, llamadas de herramientas, crecimiento de contexto y terminación del bucle.+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) (2026-01-09): evaluando el modelo y el harness juntos, y distinguiendo harnesses de evaluación de harnesses de agentes.+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) (2026-02-17): manteniendo el modelo fijo mientras se mejoran los prompts del sistema, herramientas, middleware, trazabilidad y auto-verificación para mover un agente de codificación del Top 30 al Top 5 en Terminal Bench 2.0.+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html) (2026-04-02): harnesses de usuario de agentes de codificación como guías de feedforward y sensores de feedback, con controles deterministas e inferenciales.+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness) (2026-04-30): tratando el harness como un sistema de producto continuamente mejorado con evals offline, métricas online, taxonomía de errores de herramientas, ajuste específico del modelo y cambio de modelo en medio del chat.++## Referencias Extendidas de 2026++Estas no son fuentes centrales del curso, pero son útiles al diseñar módulos específicos+del harness. Esta sección solo mantiene fuentes cuyo contenido cubre directamente el+bucle del agente, ejecución de herramientas, gestión de contexto, verificación, sandboxing,+capas de control o gobernanza de regresión. Productos puros de agentes, anuncios de plataforma,+casos de estudio de equipos y benchmarks están excluidos.++- [OpenAI: Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/) (2026-02-04): el harness como un protocolo reutilizable de App Server con ciclo de vida de hilos, resume, fork, diffs e integraciones de cliente.+- [OpenAI Developers: Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) (2026-02-23): memoria durable de proyecto, validación de hitos y ejemplos de done-when para tareas de larga duración.+- [OpenAI: The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/) (2026-04-15): harnesses nativos del modelo, ejecución en sandbox y ejecución de archivos/comandos.+- [OpenAI: An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/) (2026-04-27): convirtiendo un issue tracker o tablero de Linear en un plano de control multi-agente.+- [Anthropic: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler) (2026-02-05): equipos de agentes paralelos, locks de tareas, sincronización de git, aislamiento en contenedores y bucles autónomos.+- [Anthropic: Scaling Managed Agents: Decoupling the brain from the hands](https://www.anthropic.com/engineering/managed-agents) (2026-04-08): una vista de meta-harness que separa sesión, harness y sandbox como interfaces intercambiables.+- [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem) (2026-04-23): esfuerzo de razonamiento, poda de contexto y prompts del sistema como cambios del harness que necesitan gobernanza de regresión.+- [LangChain: Context Management for Deep Agents](https://www.langchain.com/blog/context-management-for-deepagents) (2026-01-28): descarga al sistema de archivos, truncamiento de llamadas de herramientas, resumen y evals dirigidos para harnesses de gestión de contexto.+- [LangChain: Tuning Deep Agents to Work Well with Different Models](https://www.langchain.com/blog/tuning-deep-agents-different-models) (2026-04-29): perfiles de harness específicos del modelo para prompts, nombres de herramientas, middleware y configuración de subagentes.+- [LangChain: Continual learning for AI agents](https://www.langchain.com/blog/continual-learning-for-ai-agents) (2026-04-05): dividiendo la mejora del agente en capas de modelo, harness y contexto, impulsado por trazas.+- [Microsoft: Agent Harness in Agent Framework](https://devblogs.microsoft.com/agent-framework/agent-harness-in-agent-framework/) (2026-03-12): harnesses de shell/sistema de archivos, flujo de aprobación, ejecución de shell alojada y compactación de contexto.+- [Google: Announcing ADK for Java 1.0.0](https://developers.googleblog.com/announcing-adk-for-java-100-building-the-future-of-ai-agents-in-java/) (2026-03-30): plugins, compactación de eventos, HITL, servicios de sesión/memoria y A2A como primitivas de harness reutilizables.+- [GitHub: Automate repository tasks with GitHub Agentic Workflows](https://github.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflows/) (2026-02-13): GitHub Actions como un ejecutor de flujos de trabajo agentic con salidas seguras, sandboxing, permisos y revisión.+- [AWS: AI agents in enterprises: Best practices with Amazon Bedrock AgentCore](https://aws.amazon.com/blogs/machine-learning/ai-agents-in-enterprises-best-practices-with-amazon-bedrock-agentcore/) (2026-02-03): capas de harness empresarial a través de Runtime, Memory, Gateway, Identity/Policy, Observability y Evaluations.+- [Stripe: Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents) (2026-02-09) y [Parte 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2) (2026-02-19): aislamiento en devbox, harnesses de agente personalizados, máquinas de estado de blueprint, archivos de reglas, curación de herramientas MCP, controles de seguridad y bucles de feedback pre-push/CI.+- [Cognition: What We Learned Building Cloud Agents](https://cognition.ai/blog/what-we-learned-building-cloud-agents) (2026-04-23): aislamiento en VM, snapshot/resume de sesión, orquestación, gobernanza, logging de auditoría e integraciones para tiempos de ejecución de agentes en la nube.+- [Cognition: Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working) (2026-04-22): bucles generador-verificador, revisores de contexto limpio, enrutamiento smart-friend, coordinación manager-child y límites de comunicación entre agentes.+- [Replit: Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance) (2026-01-20, actualizado 2026-01-23): un clasificador ligero inyecta guía situacional corta en el punto de decisión en lugar de meter todas las reglas en el prompt del sistema.+- [Vercel: How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent) (2026-01-07): prompts de sistema dinámicos, una capa de reescritura en streaming y autocorrectores deterministas/basados en modelo.+- [Vercel: Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base) (2026-05-04): un harness de agente de codificación enfocado en seguridad con pasos de escaneo, investigación, revalidación, enriquecimiento, exportación, plugin y verificación de rechazos.+- [Sourcegraph: CodeScaleBench](https://sourcegraph.com/blog/codescalebench-testing-coding-agents-on-large-codebases-and-multi-repo-software-engineering-tasks) (2026-03-03): una referencia de harness de eval/herramientas que cubre adopción de herramientas MCP, transcripciones de uso de herramientas, QA de benchmark, puertas de verificador/reproducibilidad e iteración de prompt/prefacio.++Las referencias generales exclusivamente de 2025 están excluidas de la lista principal. El+artículo original de 2025 de Anthropic sobre harnesses permanece porque es una fuente+fundacional del curso.++## Orden de Lectura Sugerido++1. `method-map.md`+2. `initializer-agent-playbook.md`+3. `coding-agent-startup-flow.md`+4. `prompt-calibration.md`+5. OpenAI Harness engineering+6. Anthropic Effective harnesses+7. Anthropic Harness design for long-running application development+8. OpenAI Codex agent loop+9. Anthropic agent evals+10. LangChain Improving Deep Agents+11. Thoughtworks / Martin Fowler Harness engineering for coding agent users+12. Cursor Continually improving our agent harnessdiff --git a/docs/es/resources/reference/initializer-agent-playbook.md b/docs/es/resources/reference/initializer-agent-playbook.mdnew file mode 100644index 0000000..b611efe--- /dev/null+++ b/docs/es/resources/reference/initializer-agent-playbook.md@@ -0,0 +1,37 @@+# Playbook del Agente Inicializador++Usa este playbook para la primera sesión seria en un repositorio, antes de+que comience el trabajo incremental de características.++## Objetivo++Crear una superficie operacional estable para que las sesiones posteriores puedan implementar+comportamiento sin redescubrir comandos de inicio, estado actual o límites de tareas.++## Salidas Requeridas++El inicializador debería dejar atrás al menos estos artefactos:++- un archivo de instrucciones raíz como `AGENTS.md` o `CLAUDE.md`+- una superficie de características legible por máquina como `feature_list.json`+- un artefacto de progreso duradero como `claude-progress.md`+- un ayudante de inicio estándar como `init.sh`+- un commit seguro inicial que capture el scaffold de referencia++## Lista de Verificación++1. Define la ruta de inicio estándar.+2. Define la ruta de verificación estándar.+3. Crea el registro de progreso y registra el estado inicial.+4. Descompone el trabajo en características explícitas con estados.+5. Crea el primer commit de referencia limpio.++## Test de Éxito++Una sesión nueva sin contexto de chat previo debería poder responder:++- qué hace este repositorio+- cómo iniciarlo+- cómo verificarlo+- qué está inacabado+- cuál es el mejor próximo pasodiff --git a/docs/es/resources/reference/method-map.md b/docs/es/resources/reference/method-map.mdnew file mode 100644index 0000000..cdca1ea--- /dev/null+++ b/docs/es/resources/reference/method-map.md@@ -0,0 +1,19 @@+# Mapa de Métodos++Esta tabla mapea los modos de fallo más comunes de agentes de codificación de larga duración+al artefacto o regla operacional que usualmente los corrige primero.++| Modo de fallo | Cómo se ve en la práctica | Corrección principal | Artefacto de soporte |+| --- | --- | --- | --- |+| Confusión de inicio en frío | Una sesión nueva pasa la mayor parte de su tiempo redescubriendo la configuración y el estado | Hacer del repositorio el sistema de registro | `claude-progress.md` |+| Expansión de alcance | El agente comienza varias características y no termina ninguna limpiamente | Restringir el alcance activo | `feature_list.json` |+| Completación prematura | El agente afirma haber terminado después de ediciones de código pero antes de una prueba ejecutable | Vincular la completación a la evidencia | `clean-state-checklist.md` |+| Inicio frágil | Cada sesión reaprende cómo arrancar el proyecto | Estandarizar la configuración y verificación | `init.sh` |+| Entrega débil | La siguiente sesión no puede decir qué está verificado, roto o pendiente | Terminar con una entrega explícita | `session-handoff.md` |+| Revisión subjetiva | La calidad de la revisión depende del gusto o la memoria | Puntuar la salida con categorías fijas | `evaluator-rubric.md` |++## Principio Operacional++Añade el artefacto más pequeño que aborde directamente el modo de fallo observado.+Evita resolver cada problema de fiabilidad volcando más texto en un archivo de instrucciones+global único.diff --git a/docs/es/resources/reference/prompt-calibration.md b/docs/es/resources/reference/prompt-calibration.mdnew file mode 100644index 0000000..dedeaf2--- /dev/null+++ b/docs/es/resources/reference/prompt-calibration.md@@ -0,0 +1,25 @@+# Calibración de Prompts++Las instrucciones raíz deben definir el marco operacional, no cada movimiento posible.++## Mantener En El Archivo Raíz++- propósito y alcance del repositorio+- ruta de inicio+- ruta de verificación+- restricciones no negociables+- artefactos de estado requeridos+- reglas de fin de sesión++## Sacar Del Archivo Raíz++- casos límite históricos largos+- detalles de implementación específicos de un tema+- notas de arquitectura local que pertenecen cerca del código+- ejemplos que solo aplican a un subsistema++## Regla de Trabajo++El archivo raíz debería ayudar a una sesión nueva a orientarse rápidamente. Si el archivo+se está convirtiendo en un depósito para cada fallo pasado, divide el detalle en documentos+más pequeños y enlázalos en su lugar.diff --git a/docs/es/resources/templates/AGENTS.md b/docs/es/resources/templates/AGENTS.mdnew file mode 100644index 0000000..80bdb66--- /dev/null+++ b/docs/es/resources/templates/AGENTS.md@@ -0,0 +1,55 @@+# AGENTS.md++Este repositorio está diseñado para trabajo de agentes de codificación de larga duración. El objetivo no+es maximizar la salida bruta de código. El objetivo es dejar el repositorio en un estado donde la+próxima sesión pueda continuar sin adivinar.++## Flujo de Trabajo de Inicio++Antes de escribir código:++1. Confirma el directorio de trabajo con `pwd`.+2. Lee `claude-progress.md` para el estado verificado más reciente y el próximo paso.+3. Lee `feature_list.json` y elige la característica inacabada de mayor prioridad.+4. Revisa los commits recientes con `git log --oneline -5`.+5. Ejecuta `./init.sh`.+6. Ejecuta la verificación de smoke o end-to-end requerida antes de comenzar trabajo nuevo.++Si la verificación de referencia ya está fallando, corrígela primero. No apiles trabajo de+características nuevas sobre un estado inicial roto.++## Reglas de Trabajo++- Trabaja en una característica a la vez.+- No marques una característica como completa solo porque se añadió código.+- Mantén los cambios dentro del alcance de la característica seleccionada a menos que un bloqueo+ fuerce una corrección de soporte estrecha.+- No cambies silenciosamente las reglas de verificación durante la implementación.+- Prefiere artefactos duraderos del repositorio sobre resúmenes de chat.++## Artefactos Requeridos++- `feature_list.json`: fuente de verdad para el estado de las características+- `claude-progress.md`: registro de sesión y estado verificado actual+- `init.sh`: ruta estándar de inicio y verificación+- `session-handoff.md`: entrega compacta opcional para sesiones más grandes++## Definición de Completado++Una característica está hecha solo cuando todo lo siguiente es cierto:++- el comportamiento objetivo está implementado+- la verificación requerida realmente se ejecutó+- la evidencia está registrada en `feature_list.json` o `claude-progress.md`+- el repositorio permanece reiniciable desde la ruta de inicio estándar++## Fin de Sesión++Antes de terminar una sesión:++1. Actualiza `claude-progress.md`.+2. Actualiza `feature_list.json`.+3. Registra cualquier riesgo o bloqueo sin resolver.+4. Haz commit con un mensaje descriptivo una vez que el trabajo esté en un estado seguro.+5. Deja el repositorio lo suficientemente limpio para que la próxima sesión pueda ejecutar+ `./init.sh` inmediatamente.diff --git a/docs/es/resources/templates/CLAUDE.md b/docs/es/resources/templates/CLAUDE.mdnew file mode 100644index 0000000..a2299c8--- /dev/null+++ b/docs/es/resources/templates/CLAUDE.md@@ -0,0 +1,47 @@+# CLAUDE.md++Estás trabajando en un repositorio diseñado para trabajo de implementación de larga duración.+Prioriza la completación fiable, la continuidad entre sesiones y la verificación explícita+sobre la velocidad.++## Bucle Operacional++Al comienzo de cada sesión:++1. Ejecuta `pwd` y confirma que estás en la raíz del repositorio esperada.+2. Lee `claude-progress.md`.+3. Lee `feature_list.json`.+4. Revisa los commits recientes con `git log --oneline -5`.+5. Ejecuta `./init.sh`.+6. Verifica si la ruta de smoke o end-to-end de referencia ya está rota.++Luego selecciona exactamente una característica inacabada y trabaja solo en esa característica hasta+que la verifiques o documentes por qué está bloqueada.++## Reglas++- Una característica activa a la vez.+- No afirmes completación sin evidencia ejecutable.+- No reescribas la lista de características para ocultar trabajo inacabado.+- No elimines o debilites tests solo para hacer que la tarea parezca completa.+- Usa los artefactos del repositorio como el sistema de registro.++## Archivos Requeridos++- `feature_list.json`+- `claude-progress.md`+- `init.sh`+- `session-handoff.md` cuando una entrega compacta es útil++## Puerta de Completación++Una característica puede pasar a `passing` solo después de que la verificación requerida tenga éxito+y el resultado esté registrado.++## Antes de Detenerte++1. Actualiza el registro de progreso.+2. Actualiza el estado de la característica.+3. Registra qué sigue roto o sin verificar.+4. Haz commit una vez que el repositorio sea seguro para reanudar.+5. Deja una ruta de reinicio limpia para la próxima sesión.diff --git a/docs/es/resources/templates/claude-progress.md b/docs/es/resources/templates/claude-progress.mdnew file mode 100644index 0000000..ddd26b3--- /dev/null+++ b/docs/es/resources/templates/claude-progress.md@@ -0,0 +1,35 @@+# Registro de Progreso++## Estado Verificado Actual++- Raíz del repositorio:+- Ruta de inicio estándar:+- Ruta de verificación estándar:+- Característica inacabada de mayor prioridad actual:+- Bloqueador actual:++## Registro de Sesiones++### Sesión 001++- Fecha:+- Objetivo:+- Completado:+- Verificación ejecutada:+- Evidencia capturada:+- Commits:+- Archivos o artefactos actualizados:+- Riesgo conocido o problema sin resolver:+- Mejor próximo paso:++### Sesión 002++- Fecha:+- Objetivo:+- Completado:+- Verificación ejecutada:+- Evidencia capturada:+- Commits:+- Archivos o artefactos actualizados:+- Riesgo conocido o problema sin resolver:+- Mejor próximo paso:diff --git a/docs/es/resources/templates/clean-state-checklist.md b/docs/es/resources/templates/clean-state-checklist.mdnew file mode 100644index 0000000..9340877--- /dev/null+++ b/docs/es/resources/templates/clean-state-checklist.md@@ -0,0 +1,8 @@+# Lista de Verificación de Estado Limpio++- [ ] La ruta de inicio estándar sigue funcionando.+- [ ] La ruta de verificación estándar sigue ejecutándose.+- [ ] El progreso actual está registrado en el registro de progreso.+- [ ] El estado de las características refleja qué está realmente pasando versus sin verificar.+- [ ] No hay ningún paso a medio terminar sin documentar.+- [ ] La próxima sesión puede continuar sin reparación manual.diff --git a/docs/es/resources/templates/evaluator-rubric.md b/docs/es/resources/templates/evaluator-rubric.mdnew file mode 100644index 0000000..4337d73--- /dev/null+++ b/docs/es/resources/templates/evaluator-rubric.md@@ -0,0 +1,24 @@+# Rúbrica del Evaluador++Usa esta rúbrica después de la implementación y antes de la aceptación final.++| Categoría | Pregunta | Puntuación (0-2) | Notas |+| --- | --- | --- | --- |+| Corrección | ¿El comportamiento implementado coincide con la característica solicitada? | | |+| Verificación | ¿Las verificaciones requeridas se ejecutaron realmente, con evidencia? | | |+| Disciplina de alcance | ¿La sesión se mantuvo dentro del alcance de la característica elegida? | | |+| Fiabilidad | ¿El resultado sobrevive al reinicio o reejecución sin reparación? | | |+| Mantenibilidad | ¿El código y la documentación son lo suficientemente claros para la próxima sesión? | | |+| Preparación de entrega | ¿Puede una sesión nueva continuar el trabajo solo con artefactos del repositorio? | | |++## Veredicto++- Aceptar+- Revisar+- Bloquear++## Seguimiento Requerido++- Evidencia faltante:+- Correcciones requeridas:+- Próximo disparador de revisión:diff --git a/docs/es/resources/templates/feature_list.json b/docs/es/resources/templates/feature_list.jsonnew file mode 100644index 0000000..138adc6--- /dev/null+++ b/docs/es/resources/templates/feature_list.json@@ -0,0 +1,64 @@+{+ "project": "replace-with-project-name",+ "last_updated": "YYYY-MM-DD",+ "rules": {+ "single_active_feature": true,+ "passing_requires_evidence": true,+ "do_not_skip_verification": true+ },+ "status_legend": {+ "not_started": "Work has not begun.",+ "in_progress": "The feature is the current active task.",+ "blocked": "Work cannot continue until a documented blocker is resolved.",+ "passing": "Required verification has passed and evidence is recorded."+ },+ "features": [+ {+ "id": "chat-001",+ "priority": 1,+ "area": "chat",+ "title": "Create a new conversation",+ "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",+ "status": "not_started",+ "verification": [+ "Open the app.",+ "Click New Chat.",+ "Verify a new conversation appears in the sidebar.",+ "Verify the main panel shows an empty conversation state."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-002",+ "priority": 2,+ "area": "chat",+ "title": "Send a message in the current conversation",+ "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",+ "status": "not_started",+ "verification": [+ "Open an existing conversation.",+ "Type a message into the input.",+ "Submit the message.",+ "Verify the new message appears in the thread."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-003",+ "priority": 3,+ "area": "chat",+ "title": "Persist the active conversation list",+ "user_visible_behavior": "A user sees previously created conversations after restarting the app.",+ "status": "not_started",+ "verification": [+ "Create two conversations.",+ "Restart the app.",+ "Verify both conversations still appear in the sidebar."+ ],+ "evidence": [],+ "notes": ""+ }+ ]+}diff --git a/docs/es/resources/templates/index.md b/docs/es/resources/templates/index.mdnew file mode 100644index 0000000..3925706--- /dev/null+++ b/docs/es/resources/templates/index.md@@ -0,0 +1,226 @@+# Guía de Plantillas++Estas plantillas están listas para copiar en tu propio proyecto. Cada una cumple un propósito específico en el flujo de trabajo del agente. Edita el contenido para que coincida con los comandos, rutas, nombres de características y pasos de verificación de tu proyecto.++## Cómo Comenzar++Copia estos cuatro archivos en la raíz de tu proyecto primero:++1. `AGENTS.md` o `CLAUDE.md`+2. `init.sh`+3. `claude-progress.md`+4. `feature_list.json`++Añade los archivos restantes a medida que tu proyecto crece.++---++## AGENTS.md++El archivo de instrucciones raíz. Esta es la primera cosa que el agente lee cuando inicia una sesión. Define las reglas operacionales: qué hacer antes de escribir código, cómo trabajar y cómo cerrar.++**Cómo usarlo:**++- Copia al directorio raíz de tu proyecto+- Reemplaza los pasos del flujo de inicio con las rutas y comandos reales de tu proyecto+- Ajusta las reglas de trabajo para que coincidan con las convenciones de tu equipo+- Mantén la sección de definición de completado — es la parte más importante++**Qué hace por el agente:**++- Le indica que lea el progreso y el estado de las características antes de comenzar a trabajar+- Lo obliga a trabajar en una característica a la vez+- Requiere evidencia antes de marcar algo como completado+- Define cómo se ve un fin de sesión limpio++Usa `AGENTS.md` para Codex u otros agentes. Usa `CLAUDE.md` si estás trabajando con Claude Code — la estructura es la misma, solo formateada para el estilo de instrucciones de Claude.++## init.sh++El script de inicio. Ejecuta la instalación de dependencias, verificación e imprime el comando de inicio — todo en un solo paso.++**Cómo usarlo:**++- Copia a la raíz de tu proyecto+- Edita estas tres variables en la parte superior:+ - `INSTALL_CMD` — tu comando de instalación de dependencias (ej. `npm install`, `pip install -r requirements.txt`)+ - `VERIFY_CMD` — tu comando de verificación básica (ej. `npm test`, `pytest`)+ - `START_CMD` — tu comando de inicio del servidor de desarrollo (ej. `npm run dev`)+- Hazlo ejecutable: `chmod +x init.sh`++**Qué hace:**++1. Imprime el directorio actual (para que puedas confirmar que se está ejecutando en el lugar correcto)+2. Instala dependencias+3. Ejecuta el comando de verificación+4. Imprime el comando de inicio (o lo ejecuta si `RUN_START_COMMAND=1` está configurado)++Si la verificación falla, el agente debe detenerse y corregir la línea base antes de hacer cualquier otra cosa.++## claude-progress.md++El registro de progreso. Cada sesión escribe en este archivo, y cada sesión nueva lo lee primero.++**Cómo usarlo:**++- Copia a la raíz de tu proyecto+- Rellena la sección "Estado Verificado Actual" con la información de tu proyecto+- Después de cada sesión, actualiza el registro de sesión++**Qué significa cada campo:**++- **Estado Verificado Actual** — la única fuente de verdad sobre dónde está el proyecto+ - `Repository root directory` — dónde vive el proyecto+ - `Standard startup path` — el comando para poner en marcha el proyecto+ - `Standard verification path` — el comando para ejecutar los tests+ - `Highest priority unfinished feature` — en qué debería trabajar la próxima sesión+ - `Current blocker` — cualquier cosa que esté atascada+- **Registro de Sesión** — una entrada por sesión+ - `Goal` — lo que planeabas hacer+ - `Completed` — lo que realmente se hizo+ - `Verification run` — qué tests se ejecutaron+ - `Evidence recorded` — qué prueba se capturó+ - `Commits` — qué se commiteó+ - `Known risks` — qué podría estar roto+ - `Next best action` — dónde debería empezar la próxima sesión++## feature_list.json++El rastreador de características. Una lista legible por máquina de cada característica que el agente necesita implementar, junto con su estado, pasos de verificación y evidencia.++**Cómo usarlo:**++- Copia a la raíz de tu proyecto+- Reemplaza las características de ejemplo con las tuyas+- Cada característica necesita:+ - `id` — un identificador único corto+ - `priority` — entero, menor = mayor prioridad+ - `area` — qué parte de la aplicación (ej. "chat", "import", "search")+ - `title` — descripción corta+ - `user_visible_behavior` — lo que el usuario debería ver cuando funciona+ - `status` — uno de `not_started`, `in_progress`, `blocked`, `passing`+ - `verification` — instrucciones paso a paso para confirmar que funciona+ - `evidence` — prueba registrada de que la verificación pasó (rellenada por el agente)+ - `notes` — cualquier contexto adicional++**Reglas de estado:**++- `not_started` — no ha sido tocada+- `in_progress` — la única característica en la que se está trabajando actualmente (solo una a la vez)+- `blocked` — no se puede proceder debido a un problema documentado+- `passing` — la verificación pasó y la evidencia está registrada++El agente solo debe tener una característica en `in_progress` en cualquier momento.++## session-handoff.md++Una nota de entrega compacta entre sesiones. Usa esto cuando una sesión termina y quieres que la próxima la retome rápidamente.++**Cómo usarlo:**++- Copia a la raíz de tu proyecto+- Rellénalo al final de cada sesión (o haz que el agente lo rellene)++**Qué cubre cada sección:**++- **Actualmente verificado** — qué está confirmado como funcionando y qué verificación se ejecutó+- **Cambios esta sesión** — qué código o infraestructura cambió+- **Aún roto o sin verificar** — problemas conocidos y áreas de riesgo+- **Mejor próxima acción** — qué debería hacer la próxima sesión, y qué no tocar+- **Comandos** — comandos de inicio, verificación y depuración para referencia rápida++Este archivo es opcional para sesiones pequeñas. Se vuelve importante cuando las sesiones son largas o cuando el proyecto tiene múltiples áreas activas.++## clean-state-checklist.md++Una lista de verificación para revisar antes de terminar cada sesión. Asegura que el repositorio esté en un buen estado para que la próxima sesión comience limpiamente.++**Cómo usarlo:**++- Copia a la raíz de tu proyecto+- Revísala antes de cerrar una sesión+- El agente también debería verificar estos elementos como parte de su rutina de fin de sesión++**Qué verifica:**++- El inicio estándar sigue funcionando+- La verificación estándar sigue ejecutándose+- El registro de progreso está actualizado+- La lista de características refleja el estado real (no hay entradas `passing` falsas)+- No hay trabajo a medio terminar sin registrar+- La próxima sesión puede continuar sin correcciones manuales++## evaluator-rubric.md++Una tarjeta de puntuación para revisar la calidad de salida del agente. Usa esto después de una sesión o en hitos del proyecto para evaluar si el trabajo cumple con el estándar.++**Cómo usarlo:**++- Copia a la raíz de tu proyecto+- Después de una sesión (o un conjunto de sesiones), puntúa el trabajo del agente en seis dimensiones+- Cada dimensión se puntúa de 0 a 2++**Las seis dimensiones:**++1. **Corrección** — ¿la implementación coincide con el comportamiento objetivo?+2. **Verificación** — ¿las verificaciones requeridas se ejecutaron realmente, con evidencia?+3. **Disciplina de alcance** — ¿el agente se mantuvo dentro de la característica seleccionada?+4. **Fiabilidad** — ¿el resultado sobrevive un reinicio o reejecución?+5. **Mantenibilidad** — ¿el código y la documentación son lo suficientemente claros para la próxima sesión?+6. **Preparación de entrega** — ¿puede una sesión nueva continuar usando solo artefactos del repositorio?++**Opciones de conclusión:**++- Aceptar — cumple con el estándar+- Revisar — necesita correcciones antes de aceptar+- Bloquear — problemas fundamentales que necesitan resolverse primero++**Importante: el evaluador necesita ajuste.** De fábrica, los agentes son malos autojueces — identifican problemas y luego se convencen a sí mismos de aprobar. Necesitarás iterar:++1. Ejecuta el evaluador en un sprint completado.+2. Compara sus puntuaciones con tu propio juicio humano.+3. Donde diverjan, haz la rúbrica más específica sobre los criterios de aprobación/fallo.+4. Vuelve a ejecutar y verifica la alineación.+5. Repite hasta que el evaluador coincida consistentemente con la revisión humana.++Planifica 3-5 rondas de ajuste. Registra cada cambio para que puedas rastrear qué mejoró la alineación.++## quality-document.md++Una instantánea de calidad que califica cada dominio de producto y capa arquitectónica en tu proyecto. Rastrea la salud del código base a lo largo del tiempo, no solo la salida de sesiones individuales.++**Cómo usarlo:**++- Copia a la raíz de tu proyecto+- Antes de comenzar una sesión: léelo para entender dónde el código base es más débil+- Después de una sesión: actualiza las calificaciones basándote en qué cambió+- Con el tiempo: compara instantáneas para ver qué cambios del harness realmente mejoraron la salud del código base++**Qué califica:**++- **Dominios de producto** (ej., importación de documentos, flujo de P&R, indexación): cada dominio recibe una calificación (A-D) en estado de verificación, legibilidad del agente, estabilidad de tests y brechas clave+- **Capas arquitectónicas** (ej., proceso principal, preload, renderer, servicios): cada capa recibe una calificación para enforcement de límites y legibilidad del agente++**Por qué importa:**++La rúbrica del evaluador puntúa las salidas individuales del agente. El documento de calidad puntúa el código base en sí. Responden a preguntas diferentes:++- Rúbrica del evaluador: "¿Hizo buen trabajo el agente en esta sesión?"+- Documento de calidad: "¿El proyecto se está fortaleciendo o debilitando con el tiempo?"++**Cuándo actualizar:**++- Después de cada sesión significativa+- Antes de comparaciones de benchmark+- Después de pases de limpieza o simplificación+- Al incorporar un nuevo agente o modelo al proyecto++**Conexión con la simplificación del harness:**++El documento de calidad también soporta la simplificación del harness. Cada componente del harness codifica un supuesto sobre lo que el modelo no puede hacer. A medida que los modelos mejoran, estos supuestos se vuelven obsoletos. Para verificar si un componente sigue siendo necesario:++1. Toma una instantánea del documento de calidad.+2. Elimina un componente del harness.+3. Ejecuta el conjunto de tareas de benchmark.+4. Toma otra instantánea.+5. Compara — si las calificaciones no bajaron, el componente era sobrecarga. Si bajaron, restáuralo.diff --git a/docs/es/resources/templates/init.sh b/docs/es/resources/templates/init.shnew file mode 100755index 0000000..d7522d6--- /dev/null+++ b/docs/es/resources/templates/init.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash++set -euo pipefail++ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+cd "$ROOT_DIR"++# Replace these commands with the correct commands for your repository.+INSTALL_CMD=(npm install)+VERIFY_CMD=(npm test)+START_CMD=(npm run dev)++echo "==> Working directory: $PWD"+echo "==> Syncing dependencies"+"${INSTALL_CMD[@]}"++echo "==> Running baseline verification"+"${VERIFY_CMD[@]}"++echo "==> Startup command"+printf ' %q' "${START_CMD[@]}"+printf '\n'++if [ "${RUN_START_COMMAND:-0}" = "1" ]; then+ echo "==> Starting the app"+ exec "${START_CMD[@]}"+fi++echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."diff --git a/docs/es/resources/templates/quality-document.md b/docs/es/resources/templates/quality-document.mdnew file mode 100644index 0000000..a248f1b--- /dev/null+++ b/docs/es/resources/templates/quality-document.md@@ -0,0 +1,43 @@+# Documento de Calidad++Una instantánea de calidad para cada dominio de producto y capa arquitectónica. Tanto agentes como humanos pueden usar este documento para entender rápidamente dónde el código base es fuerte y dónde necesita trabajo.++**Cadencia de actualización:** Después de cada sesión significativa, o antes de comenzar una nueva fase de trabajo.++**Escala de calificación:**++- **A**: Toda la verificación pasando, arquitectura limpia, legible para agentes, tests estables+- **B**: Verificación pasando, mayormente limpio, brechas menores en legibilidad o cobertura de tests+- **C**: Parcialmente funcionando, brechas conocidas, algunas áreas de código difíciles de entender para los agentes+- **D**: No funcionando, o problemas estructurales importantes++---++## Dominios de Producto++| Dominio | Calificación | Verificación | Legibilidad del Agente | Estabilidad de Tests | Brechas Clave | Última Actualización |+|---------|-------------|-------------|----------------------|---------------------|---------------|---------------------|+| Importación de Documentos | - | - | - | - | - | - |+| Gestión de Documentos | - | - | - | - | - | - |+| Indexación de Documentos | - | - | - | - | - | - |+| Flujo de Preguntas y Respuestas | - | - | - | - | - | - |+| Respuestas Fundamentadas | - | - | - | - | - | - |++## Capas Arquitectónicas++| Capa | Calificación | Enforcement de Límites | Legibilidad del Agente | Brechas Clave | Última Actualización |+|------|-------------|----------------------|----------------------|---------------|---------------------|+| Proceso Principal | - | - | - | - | - |+| Preload | - | - | - | - | - |+| Renderer | - | - | - | - | - |+| Servicios | - | - | - | - | - |++## Historial de Cambios++### YYYY-MM-DD++- Cambios:+- Dominios promovidos:+- Degradados:+- Nuevas brechas identificadas:+- Brechas cerradas:diff --git a/docs/es/resources/templates/session-handoff.md b/docs/es/resources/templates/session-handoff.mdnew file mode 100644index 0000000..2f684e4--- /dev/null+++ b/docs/es/resources/templates/session-handoff.md@@ -0,0 +1,30 @@+# Entrega de Sesión++## Verificado Ahora++- Qué está funcionando actualmente:+- Qué verificación se ejecutó realmente:++## Cambiado En Esta Sesión++- Código o comportamiento añadido:+- Cambios de infraestructura o harness:++## Roto O Sin Verificar++- Defecto conocido:+- Ruta sin verificar:+- Riesgo para la próxima sesión:++## Mejor Próximo Paso++- Característica inacabada de mayor prioridad:+- Por qué es la siguiente:+- Qué cuenta como aprobado:+- Qué no debe cambiar durante ese paso:++## Comandos++- Inicio:+- Verificación:+- Comando de depuración enfocado:diff --git a/docs/es/skills/index.md b/docs/es/skills/index.mdnew file mode 100644index 0000000..6987ddb--- /dev/null+++ b/docs/es/skills/index.md@@ -0,0 +1,49 @@+# Skills++Este directorio contiene los skills de agentes de IA incluidos con el curso. Los skills son plantillas de prompt autocontenidas que pueden cargar agentes de programación con IA, como Claude Code, Codex, Cursor o Windsurf, para realizar tareas especializadas.++## harness-creator++Un skill de harness engineering de nivel producción para agentes de programación con IA. Te ayuda a crear, evaluar y mejorar los cinco subsistemas centrales de un harness: instrucciones, estado, verificación, alcance y ciclo de vida de la sesión.++### Qué hace++- **Crear harnesses desde cero** — AGENTS.md, listas de funciones y flujos de verificación+- **Mejorar harnesses existentes** — evaluación de cinco subsistemas con mejoras priorizadas+- **Diseñar continuidad de sesión** — memoria persistente, seguimiento de progreso y procedimientos de handoff+- **Aplicar patrones de producción** — memoria, context engineering, seguridad de herramientas y coordinación multiagente++### Inicio rápido++Los archivos del skill están en el repositorio en [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator).++Para usarlo con Claude Code, copia el directorio `harness-creator/` a la ruta de skills de tu proyecto, o apunta tu agente al archivo SKILL.md.++### Patrones de referencia++El skill incluye 6 documentos de referencia detallados:++| Patrón | Cuándo usarlo |+|---------|-------------|+| Memory Persistence | El agente olvida entre sesiones |+| Context Engineering | Gestión del presupuesto de contexto, carga JIT |+| Tool Registry | Seguridad de herramientas, control de concurrencia |+| Multi-Agent Coordination | Paralelismo, flujos de especialización |+| Lifecycle & Bootstrap | Hooks, tareas en segundo plano, inicialización |+| Gotchas | 15 modos de fallo no obvios con correcciones |++### Plantillas++El skill incluye plantillas listas para usar:++- `agents.md` — scaffold de AGENTS.md con reglas de trabajo+- `feature-list.json` — JSON Schema y ejemplo de lista de funciones+- `init.sh` — script estándar de inicialización+- `progress.md` — plantilla de registro de progreso de sesión++### Cómo se construyó este skill++`harness-creator` se desarrolló usando la metodología **skill-creator**, el metaskill oficial de Anthropic para crear, probar e iterar skills de agentes. skill-creator ofrece un flujo estructurado de borrador → prueba → evaluación → iteración, con runners de evaluación, graders y un visor de benchmarks.++- **Fuente de skill-creator**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)+- **Documentación de skills de Claude Code**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)diff --git a/docs/fr/index.md b/docs/fr/index.mdnew file mode 100644index 0000000..2663a03--- /dev/null+++ b/docs/fr/index.md@@ -0,0 +1,73 @@+# Bienvenue dans Learn Harness Engineering++Learn Harness Engineering est un cours consacré à l'ingénierie des agents de codage IA. Nous avons étudié et synthétisé des théories et pratiques avancées de Harness Engineering utilisées dans l'industrie. Nos références principales sont :+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)++Grâce à une conception systématique de l'environnement, de l'état, de la vérification et des mécanismes de contrôle, ce cours montre comment rendre réellement fiables des outils agentiques de codage comme Codex et Claude Code. Vous apprendrez à construire des fonctionnalités, corriger des bugs et automatiser des tâches de développement en encadrant votre assistant de codage IA avec des règles et des limites explicites.++## Commencer++Choisissez votre parcours d'apprentissage. Le cours est divisé en leçons théoriques, projets pratiques et bibliothèque de ressources prêtes à copier.++<div class="card-grid">+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">+ <h3>Leçons</h3>+ <p>Comprendre pourquoi des modèles puissants échouent encore et apprendre la théorie des harnesses efficaces.</p>+ </a>+ <a href="./projects/" class="card">+ <h3>Projets</h3>+ <p>Pratique guidée pour construire de zéro un environnement agentique fiable.</p>+ </a>+ <a href="./resources/" class="card">+ <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>+</div>++## Le mécanisme central d'un harness++Un harness ne "rend pas le modèle plus intelligent" ; il met en place un **système de travail** en boucle fermée pour le modèle. Le flux central peut être compris avec ce schéma :++```mermaid+graph TD+ A["Clear Objective<br/>AGENTS.md"] --> B("Initialization<br/>init.sh")+ B --> C{"Run Tasks<br/>AI Agent"}+ C -->|Encounter Issues| D["Runtime Feedback<br/>CLI / Logs"]+ D -->|Auto-fix| C+ C -->|Code Completed| E{"Verify & QA<br/>Test suite"}+ E -->|Failed| D+ E -->|Passed| F["Cleanup & Handoff<br/>claude-progress.md"]++ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;++ class A,F primary;+ class B,D process;+ class C,E check;+```++## Ce que vous apprendrez++Voici quelques concepts clés que vous maîtriserez :++<ul class="index-list">+ <li><strong>Contraindre le comportement de l'agent</strong> avec des règles et des limites explicites.</li>+ <li><strong>Maintenir le contexte</strong> sur des tâches longues et multi-sessions.</li>+ <li><strong>Empêcher les agents</strong> de déclarer la victoire trop tôt.</li>+ <li><strong>Vérifier le travail</strong> avec des tests de pipeline complet et de l'auto-évaluation.</li>+ <li><strong>Rendre le runtime observable</strong> et débogable.</li>+</ul>++## Étapes suivantes++Une fois les concepts de base compris, ces guides permettent d'aller plus loin :++<ul class="index-list">+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">Leçon 01 : Pourquoi les agents capables échouent encore</a> : commencez par la théorie du harness engineering.</li>+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">Projet 01 : Baseline vs harness minimal</a> : parcourez votre première tâche réelle.</li>+ <li><a href="./resources/templates/">Modèles</a> : récupérez le pack minimal de harness pour vos propres projets.</li>+</ul>diff --git a/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..311e665--- /dev/null+++ b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,170 @@+/**+ * failure-pattern-demo.ts+ *+ * Simulates the 4-step failure pattern that capable agents fall into:+ * 1. Incomplete context+ * 2. Locally reasonable changes+ * 3. No global verification+ * 4. Premature completion+ *+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// Simulated "model" -- a simple decision function that bases its output+// solely on whatever context it has been given.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // The task is to "add a search endpoint to the API".+ // Correct answer requires knowing about auth middleware and rate limiting.++ if (!has("auth")) {+ return "Created new route handler /search without authentication checks";+ }+ if (!has("rate-limit")) {+ return "Added search route with auth but forgot rate limiting";+ }+ if (!has("test-standards")) {+ return "Implemented search with auth and rate-limit, but no tests";+ }+ return "Fully implemented search endpoint with auth, rate-limit, and tests";+}++// ---------------------------------------------------------------------------+// Failure simulation+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Step 1: Incomplete Context ----+ const step1Context = ["project structure", "route definitions"];+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];+ const step1Decision = modelDecide(step1Context, "add search endpoint");++ steps.push({+ step: 1,+ name: "Incomplete Context",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Looks good -- route compiles, returns data",+ globalImpact: "Missing auth means unauthenticated access to search",+ completed: false,+ });++ // ---- Step 2: Locally Reasonable Changes ----+ // The agent adds auth after a hint, but still lacks other context.+ const step2Context = [...step1Context, "auth middleware"];+ const step2Missing = ["rate-limiting policy", "test standards"];+ const step2Decision = modelDecide(step2Context, "add search endpoint");++ steps.push({+ step: 2,+ name: "Locally Reasonable Changes",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "Route has auth -- looks complete locally",+ globalImpact: "No rate limiting means the endpoint can be abused",+ completed: false,+ });++ // ---- Step 3: No Global Verification ----+ const step3Context = [...step2Context, "rate-limiting policy"];+ const step3Missing = ["test standards"];+ const step3Decision = modelDecide(step3Context, "add search endpoint");++ steps.push({+ step: 3,+ name: "No Global Verification",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "Feature appears fully implemented",+ globalImpact: "No tests -- regression risk, violates project standards",+ completed: false,+ });++ // ---- Step 4: Premature Completion ----+ steps.push({+ step: 4,+ name: "Premature Completion",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',+ localOutcome: "Agent is satisfied, task marked complete",+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Comparison table+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Step ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);+ console.log(` Action taken : ${s.actionTaken}`);+ console.log(` Local outcome : ${s.localOutcome}`);+ console.log(` Global impact : ${s.globalImpact}`);+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);+ }++ // Summary comparison+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");+ console.log("=".repeat(90));++ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];+ const finalAvailable = steps[steps.length - 1].contextAvailable;++ const header = "| Criterion | Available | Missing | Status |";+ const sep = "|------------------------|-----------|---------|----------|";+ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;+ console.log(row);+ }++ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());diff --git a/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdnew file mode 100644index 0000000..23e410c--- /dev/null+++ b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -0,0 +1,9 @@+# Liste de Contrôle des Signaux d'Échec++Utilisez cette liste lors de l'examen d'une exécution de harness faible.++- L'agent a-t-il demandé ou déduit incorrectement comment démarrer l'application ?+- A-t-il créé des répertoires ou abstractions qui ne correspondent pas au produit prévu ?+- S'est-il arrêté après avoir créé une coque UI visible sans un flux complet ?+- A-t-il laissé des notes ou artefacts aidant une future exécution à continuer ?+- Une nouvelle session pourrait-elle comprendre ce qui s'est passé en moins de cinq minutes ?diff --git a/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdnew file mode 100644index 0000000..fb57a81--- /dev/null+++ b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -0,0 +1,7 @@+# Code du Cours 01++Utilisez ce dossier pour de petits exemples montrant :++- un modèle puissant échouant dans un environnement faible+- une configuration de dépôt sous-spécifiée+- des boucles de retour manquantesdiff --git a/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdnew file mode 100644index 0000000..f7471f3--- /dev/null+++ b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -0,0 +1,18 @@+# Exemple de Tâche Sous-Spécifiée++Construisez une application de bureau de base de connaissances avec réponse aux questions par IA.++Contraintes :++- Aucune spécifiée+- Aucune commande de démarrage fournie+- Aucun guide de structure de dossiers+- Aucun modèle de données défini+- Aucun critère d'achèvement explicite++Résultats typiques de ce type de prompt :++- l agent invente une structure ad hoc+- l'application peut compiler mais ne démarre pas de manière cohérente+- l'UI peut apparaître avant qu'il n'y ait un chemin d'importation/requête utilisable+- l'agent s'arrête souvent après un succès cosmétiquediff --git a/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.mdnew file mode 100644index 0000000..f894405--- /dev/null+++ b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -0,0 +1,113 @@+[中文版本 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/code/)+> Projet pratique : [Projet 01. Prompt seul vs règles d'abord](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# Leçon 01. Les modèles forts ne garantissent pas une exécution fiable++Vous pensez connaître le monde de l'IA : abonnement Claude Pro, clé API GPT-4o, chiffres du leaderboard SWE-bench en tête. Un jour, vous confiez enfin un vrai projet à un agent IA, plein de confiance. Résultat ? Il ajoute une fonctionnalité mais casse les tests, corrige un bug mais en introduit deux autres, tourne pendant 20 minutes et annonce fièrement « terminé » — puis vous regardez le code, et ce n'est pas du tout ce que vous aviez demandé.++Votre premier réflexe pourrait être : « ce modèle n'est pas assez bon, il faut passer au niveau supérieur ». Attendez. Avant de sortir la carte bancaire, envisagez que le problème ne soit peut-être pas le modèle.++Regardons quelques chiffres. Fin 2025, les meilleurs agents de codage atteignent environ 50-60 % sur SWE-bench Verified. Et cela sur des tâches soigneusement choisies, avec descriptions claires et tests existants. Dans votre environnement quotidien — exigences floues, peu ou pas de tests, règles métier implicites partout — ce chiffre baisse encore.++Derrière ces chiffres se cache pourtant une vérité contre-intuitive.++## Même cheval, destins différents++Anthropic a mené une expérience contrôlée. Même prompt (« construire un éditeur de jeux rétro 2D »), même modèle (Opus 4.5). Premier essai : nu, sans support — 20 minutes, 9 dollars, les fonctionnalités centrales ne fonctionnent pas. Deuxième essai : harness complet (architecture planner + generator + evaluator) — 6 heures, 200 dollars, le jeu est jouable.++Ils n'ont pas changé de modèle. Opus 4.5 restait Opus 4.5. Ce qui a changé, c'est la selle.++L'article d'OpenAI sur le harness engineering le formule simplement : Codex dans un dépôt bien harnessed passe de « peu fiable » à « fiable ». Pas « un peu mieux », mais un changement qualitatif. Comme un pur-sang : vous pouvez le monter sans selle, mais vous n'irez ni loin ni vite, et tomber n'a rien d'étonnant. Le harness est cette selle : **tout ce qui, dans l'infrastructure d'ingénierie, se trouve hors des poids du modèle.**++## Où les agents se bloquent vraiment++Qu'est-ce qui se passe concrètement ?++Le plus courant : la tâche n'a jamais été définie clairement. Vous dites « ajoute une recherche », et l'agent comprend autre chose que vous — rechercher quoi ? Plein texte ou structuré ? Pagination ? Surlignage ? Sans précision, l'agent devine. Une bonne supposition est de la chance ; une mauvaise coûte plus cher à corriger que la précision initiale. C'est comme entrer au restaurant et dire au chef « je veux du poisson » : braisé, vapeur ou en fondue, tout dépend du hasard.++Même lorsque la tâche est claire, le projet a des conventions implicites que l'agent ignore. Votre équipe utilise SQLAlchemy 2.0, mais l'agent écrit du 1.x par défaut. Tous les endpoints doivent utiliser OAuth 2.0, mais cette règle n'existe que dans votre tête et un message Slack vieux de trois mois. L'agent ne peut pas la voir. Il ne refuse pas d'obéir ; il ne sait littéralement pas que la règle existe.++L'environnement est aussi un piège. Environnement dev incomplet, dépendances manquantes, versions d'outils incorrectes. L'agent brûle du contexte sur des échecs `pip install` et des versions Node incohérentes au lieu de résoudre la vraie tâche. C'est comme embaucher un excellent menuisier sans lui donner marteau, clous ni établi stable.++Plus fréquent encore : il n'y a aucun moyen de vérifier. Pas de tests, pas de lint, ou les commandes de vérification ne sont jamais communiquées. L'agent écrit du code, le regarde, décide que ça va et dit « terminé ». Comme un élève qui rend un devoir sans corrigé : il pense avoir bon, mais la correction révèle une pile d'erreurs. Anthropic a aussi observé que les agents, lorsqu'ils sentent le contexte se remplir, se dépêchent de finir, sautent la vérification et choisissent une solution simple plutôt qu'optimale. Ils appellent cela « context anxiety ».++Les tâches longues sur plusieurs sessions sont encore pires : les découvertes de la session précédente se perdent, et chaque nouvelle session doit réexplorer le projet. Sans état persistant, le taux d'échec grimpe fortement sur les tâches dépassant 30 minutes.++## Concepts clés++- **Écart de capacité** : l'écart entre performance sur benchmark et performance réelle. 50-60 % sur SWE-bench Verified signifie que près de la moitié des vrais problèmes restent non résolus.+- **Harness** : tout ce qui est hors du modèle — instructions, outils, environnement, gestion d'état, feedback de vérification. Si ce ne sont pas des poids de modèle, c'est du harness.+- **Échec induit par le harness** : le modèle a la capacité, mais l'environnement d'exécution a des défauts structurels.+- **Écart de vérification** : différence entre la confiance de l'agent et la correction réelle. L'agent dit « terminé » alors que ce n'est pas terminé.+- **Boucle de diagnostic** : exécuter, observer l'échec, l'attribuer à une couche du harness, corriger cette couche, réexécuter.+- **Definition of Done** : ensemble de conditions vérifiables par machine — tests passent, lint propre, types valides. Sans définition explicite, l'agent invente la sienne.++## Quand ça échoue, corriger le harness d'abord++Principe central : **quand ça échoue, ne changez pas d'abord de modèle — vérifiez le harness.** Si le même modèle réussit sur des tâches similaires bien structurées, supposez un problème de harness. Comme une voiture en panne : on vérifie d'abord l'essence avant d'accuser le moteur.++**Attribuer chaque échec à une couche précise.** Ne dites pas « le modèle est nul ». Demandez : la tâche était-elle floue ? Le contexte insuffisant ? La vérification absente ? Reliez chaque échec à une des cinq couches : spécification, contexte, environnement, feedback de vérification, état.++**Écrire une Definition of Done explicite.**+```+Completion criteria:+- New endpoint GET /api/search?q=xxx+- Supports pagination, default 20 items+- Results include highlighted snippets+- All new code passes pytest+- Type checking passes (mypy --strict)+```++**Créer un fichier AGENTS.md.** Placez-le à la racine du dépôt pour décrire stack technique, conventions d'architecture et commandes de vérification. C'est la première étape du harness engineering et souvent celle avec le meilleur retour. Un `AGENTS.md` peut valoir plus qu'un modèle plus cher.++**Construire une boucle de diagnostic.** Traitez chaque échec comme un signal de défaut du harness. Identifiez la couche, corrigez-la, puis évitez que ce mode d'échec revienne.++**Quantifier les améliorations.** Tenez un journal simple : succès ou échec, couche responsable. Après quelques tours, le goulot d'étranglement devient visible.++## L'expérience du million de lignes++OpenAI a mené en 2025 une expérience ambitieuse : utiliser Codex pour construire un produit interne complet depuis un dépôt git vide. Cinq mois plus tard, le dépôt comptait environ un million de lignes — logique applicative, infrastructure, tooling, documentation, outils internes — toutes générées par agents. Trois ingénieurs pilotaient Codex, ouvrant et fusionnant environ 1 500 PRs, soit 3,5 PRs par personne et par jour.++Contrainte clé : **les humains n'écrivent jamais directement le code.** Ce n'était pas un gadget, mais un moyen de forcer l'équipe à comprendre ce qui change quand le travail principal de l'ingénieur n'est plus d'écrire du code, mais de concevoir des environnements, exprimer l'intention et construire des boucles de feedback.++Au début, la progression était plus lente que prévu. Non pas parce que Codex était incapable, mais parce que l'environnement était incomplet : il manquait outils, abstractions et structures internes. Le travail des ingénieurs est devenu : découper de grands objectifs en petits blocs (design, code, review, test), laisser l'agent les assembler, puis utiliser ces blocs pour débloquer des tâches plus complexes. Quand quelque chose échouait, la correction était rarement « essaie plus fort », mais plutôt « quelle capacité manque à l'agent, et comment la rendre compréhensible et exécutable ? ».++Cette expérience prouve directement la thèse de cette leçon : **le même modèle produit des résultats radicalement différents dans un environnement nu et dans un environnement avec harness complet.** Le modèle n'a pas changé. L'environnement, oui.++> Source : [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++## Un exemple plus terre à terre++Une équipe a utilisé Claude Sonnet pour ajouter un endpoint API à une application Python moyenne (FastAPI + PostgreSQL + Redis, environ 15 000 lignes).++Au départ, elle donne une seule phrase : « ajoute les endpoints de préférences utilisateur sous `/api/v2/users` ». Résultat : l'agent consomme 40 % de son contexte à explorer le dépôt, produit un code plausible mais incompatible avec les patterns d'erreur du projet, utilise l'ancienne syntaxe SQLAlchemy et déclare terminé alors que l'endpoint échoue au runtime. La session suivante doit refaire toute la découverte.++Plus tard, l'équipe ajoute `AGENTS.md`, des commandes de vérification explicites (`pytest tests/api/v2/ && python -m mypy src/`) et des décisions d'architecture. Le même modèle réussit trois exécutions indépendantes, avec environ 60 % d'efficacité de contexte en plus.++Ils n'ont pas changé le modèle. Ils ont changé le harness.++## Points clés++- Capacité du modèle et fiabilité d'exécution sont deux choses différentes.+- Quand ça échoue, vérifiez le harness avant le modèle.+- Chaque échec est un signal : votre harness a un défaut structurel.+- Cinq couches de défense : spécification, contexte, environnement, feedback de vérification, état.+- Un seul `AGENTS.md` peut être plus efficace qu'un modèle plus cher.++## Pour aller plus loin++- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-bench Leaderboard](https://www.swebench.com/)+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)++## Exercices++1. **Expérience comparative** : choisissez un codebase connu et une tâche non triviale. Exécutez d'abord sans harness, puis avec `AGENTS.md` et commandes de vérification explicites. Comparez les échecs par couche.++2. **Mesure de l'écart de vérification** : choisissez 5 tâches. Notez si l'agent affirme avoir terminé, puis vérifiez indépendamment. Calculez la proportion de faux « terminé ».++3. **Pratique de boucle diagnostic** : trouvez une tâche où l'agent échoue souvent. Exécutez, attribuez l'échec à une couche, corrigez-la, réexécutez et mesurez l'amélioration.diff --git a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.mdnew file mode 100644index 0000000..5e9de85--- /dev/null+++ b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md@@ -0,0 +1,21 @@+# Exemple de Composants du Harness++Pour un agent de programmation travaillant dans un dépôt local :++- Modèle :+ le LLM lui-même++- Harness :+ - prompt système+ - AGENTS.md+ - outil bash+ - outils de lecture/écriture de fichiers+ - accès git+ - système de fichiers local+ - scripts de démarrage+ - commandes de test+ - hooks d'arrêt+ - vérifications lint+ - boucle d'évaluation (evaluator loop)++Si vous modifiez l'une des pièces du harness ci-dessus, vous modifiez l'agent effectif.diff --git a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.tsnew file mode 100644index 0000000..d856ba3--- /dev/null+++ b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts@@ -0,0 +1,180 @@+/**+ * harness-vs-no-harness.ts+ *+ * Side-by-side comparison of the same task executor running with and without+ * a harness. The harness version adds explicit rules, verification steps,+ * and stop conditions.+ *+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts+ */++// ---------------------------------------------------------------------------+// Types & helpers+// ---------------------------------------------------------------------------++interface TaskResult {+ name: string;+ passed: boolean;+ durationMs: number;+ issues: string[];+}++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++// ---------------------------------------------------------------------------+// Simulated task executor+// ---------------------------------------------------------------------------++/** A simple task that can succeed or fail depending on rules. */+type Task = {+ name: string;+ requiresAuth: boolean;+ hasTests: boolean;+ withinScope: boolean;+};++const tasks: Task[] = [+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },+];++// ---------------------------------------------------------------------------+// Run WITHOUT harness -- just execute every task, no checks+// ---------------------------------------------------------------------------++function runWithoutHarness(taskList: Task[]): TaskResult[] {+ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];++ // The "agent" does the work and calls it done.+ let passed = true;++ // Problems that go undetected without a harness+ if (t.requiresAuth && !t.hasTests) {+ issues.push("No tests for auth-protected endpoint");+ // Agent doesn't notice -- marks as pass anyway+ }+ if (!t.withinScope) {+ issues.push("Task is outside current scope");+ // Agent doesn't notice+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Run WITH harness -- rules, verification, stop conditions+// ---------------------------------------------------------------------------++function runWithHarness(taskList: Task[]): TaskResult[] {+ const rules = {+ requireTestsForAuth: true,+ enforceScope: true,+ };++ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];+ let passed = true;++ // Rule: auth endpoints must have tests+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {+ issues.push("BLOCKED: Auth-protected endpoint missing tests");+ passed = false;+ }++ // Rule: stay in scope+ if (rules.enforceScope && !t.withinScope) {+ issues.push("BLOCKED: Task outside active scope -- skipped");+ passed = false;+ }++ // Verification: re-check after execution+ if (passed && !t.hasTests) {+ issues.push("WARNING: No tests exist for this change");+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function printComparison(+ noHarness: TaskResult[],+ withHarness: TaskResult[]+): void {+ console.log("\n" + "=".repeat(80));+ console.log(" HARNESS vs NO-HARNESS COMPARISON");+ console.log("=".repeat(80));++ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;++ console.log("\n" + header);+ console.log(sep);++ for (let i = 0; i < noHarness.length; i++) {+ const nh = noHarness[i];+ const wh = withHarness[i];+ const nhPass = nh.passed ? "PASS" : "FAIL";+ const whPass = wh.passed ? "PASS" : "FAIL";+ const nhIssue = nh.issues[0] ?? "(none)";+ const whIssue = wh.issues[0] ?? "(none)";++ console.log(+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`+ );+ }++ // Metrics+ const nhPassed = noHarness.filter((r) => r.passed).length;+ const whPassed = withHarness.filter((r) => r.passed).length;+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);++ console.log("\n" + "=".repeat(80));+ console.log(" SUMMARY METRICS");+ console.log("=".repeat(80));++ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log("\n" + metricsHeader);+ console.log(metricsSep);+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);++ console.log("\n The harness catches problems the no-harness run silently ignores.");+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");+}++/** Count tasks that actually pass (have tests and are in scope). */+function truePassCount(results: TaskResult[]): number {+ return results.filter((r) => r.passed && r.issues.length === 0).length;+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparison(runWithoutHarness(tasks), runWithHarness(tasks));diff --git a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/index.mdnew file mode 100644index 0000000..d59f74d--- /dev/null+++ b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 02++Utilisez ce dossier pour de petits exemples qui distinguent :++- le comportement du modèle+- le comportement du harness+- les configurations basées uniquement sur les prompts+- les configurations d'agents soutenues par l'environnementdiff --git a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.tsnew file mode 100644index 0000000..e56cddd--- /dev/null+++ b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts@@ -0,0 +1,36 @@+type Message = {+ role: "user" | "assistant";+ content: string;+};++type ToolResult = {+ ok: boolean;+ output: string;+};++function runTool(name: string, input: string): ToolResult {+ if (name === "read_file") {+ return { ok: true, output: `contents of ${input}` };+ }++ return { ok: false, output: `unknown tool: ${name}` };+}++export function minimalHarness(messages: Message[]) {+ const nextAction = {+ tool: "read_file",+ input: "README.md"+ };++ const result = runTool(nextAction.tool, nextAction.input);++ return {+ messages: [+ ...messages,+ {+ role: "assistant",+ content: `Tool ${nextAction.tool} returned: ${result.output}`+ }+ ]+ };+}diff --git a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.mdnew file mode 100644index 0000000..d62f5a5--- /dev/null+++ b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -0,0 +1,109 @@+[中文版本 →](../../../zh/lectures/lecture-02-what-a-harness-actually-is/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-02-what-a-harness-actually-is/code/)+> Projet pratique : [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# Leçon 02. Ce que signifie vraiment harness++Le mot « harness » est omniprésent dans les cercles d'agents de codage IA, mais honnêtement, la plupart des gens veulent dire « un fichier de prompt » quand ils disent harness. Ce n'est pas un harness. C'est comme ouvrir un restaurant avec seulement des ingrédients — pas de cuisinière, pas de couteaux, pas de recettes, pas de flux de dressage des assiettes. Ce n'est pas un restaurant. C'est un réfrigérateur.++Cette leçon vous donne une définition précise et opérationnelle du harness. Pas une abstraction académique, mais un cadre que vous pouvez utiliser dès aujourd'hui : un harness se compose de cinq sous-systèmes, chacun avec des responsabilités et des critères d'évaluation clairs.++## Commençons par une analogie++Imaginez que vous êtes un ingénieur nouvellement embauché, propulsé dans un projet sans aucune documentation. Pas de README, pas de commentaires dans le code, personne ne vous dit comment lancer les tests, la config CI est enterrée quelque part. Pouvez-vous écrire du bon code ? Peut-être — si vous êtes assez intelligent et patient. Mais vous passerez un temps considérable à « comprendre de quoi parle ce projet » plutôt qu'à « résoudre le problème ».++Un agent IA fait face exactement à la même situation. Et c'est pire — vous pouvez au moins demander à un collègue. L'agent ne peut voir que les fichiers que vous mettez devant lui et les commandes qu'il peut exécuter. Il ne peut pas taper quelqu'un sur l'épaule et demander « hey, quelle version de l'ORM ce projet utilise-t-il ? »++OpenAI formule le principe fondamental ainsi : « le repo EST la spécification » — tout le contexte nécessaire devrait se trouver dans le dépôt, livré via des fichiers d'instructions structurés, des commandes de vérification explicites et une organisation claire des répertoires. La documentation d'Anthropic sur les agents longue durée met l'accent sur la persistance de l'état, les chemins de récupération explicites et le suivi structuré de la progression. Les deux entreprises se concentrent sur des aspects différents, mais elles disent la même chose : **tout ce qui se trouve dans l'infrastructure d'ingénierie en dehors du modèle détermine quelle part de la capacité du modèle est réellement exploitée.**++Regardez quelques outils que vous connaissez déjà :++**Claude Code** incarne la pensée harness. Il lit `CLAUDE.md` depuis votre repo (étagère à recettes), peut exécuter des commandes shell (râtelier à couteaux), s'exécute dans votre environnement local (cuisinière), maintient un historique de session (plan de travail), et peut lancer des tests et voir les résultats (fenêtre de contrôle qualité). Mais si vous ne lui dites pas comment lancer les tests, la fenêtre de contrôle qualité est en panne — personne ne sait si le plat est complètement cuit.++**Cursor** suit une logique similaire. Son fichier `.cursorrules` est l'étagère à recettes, le terminal est le râtelier à couteaux, il lit la structure de votre projet et la config lint pour la cuisinière. Mais la gestion d'état de Cursor est relativement faible — fermez l'IDE et rouvrez-le, et le contexte précédent a disparu.++**Codex** (l'agent de codage d'OpenAI) utilise des git worktrees pour isoler l'environnement d'exécution de chaque tâche, couplé à une pile d'observabilité locale (logs, métriques, traces), de sorte que chaque modification est vérifiée dans un environnement indépendant. Dans les repos avec `AGENTS.md` et des commandes de vérification claires, il performe bien mieux que dans les repos « nus ».++**AutoGPT** est l'exemple à ne pas suivre — l'absence de gestion structurée de l'état conduit à une accumulation de contexte dans les tâches longues, et l'absence de mécanismes de retour précis fait boucler l'agent. Beaucoup de gens disent qu'AutoGPT « ne fonctionne pas », mais en réalité c'est le harness d'AutoGPT qui ne fonctionne pas — donnez à un chef une cuisinière cassée et même les meilleurs ingrédients ne produiront pas un repas.++## Concepts clés++- **Qu'est-ce qu'un harness** : Tout ce qui se trouve dans l'infrastructure d'ingénierie en dehors des poids du modèle. OpenAI résume le travail fondamental de l'ingénieur en trois choses : concevoir des environnements, exprimer l'intention et construire des boucles de retour. Anthropic appelle son Claude Agent SDK un « agent harness généraliste ».+- **Le repo est l'unique source de vérité** : Tout ce que l'agent ne peut pas voir, en pratique, n'existe pas. OpenAI traite le repo comme le « système de référence » — tout le contexte nécessaire doit y vivre, via des fichiers structurés et une organisation claire des répertoires.+- **Donnez un plan, pas un manuel** : L'expérience d'OpenAI — `AGENTS.md` devrait être une page de sommaire, pas une encyclopédie. Une centaine de lignes suffit. Si ça ne tient pas, découpez-le dans le répertoire `docs/` et laissez l'agent lire à la demande.+- **Contraindre, pas micromanager** : Un bon harness utilise des règles exécutables pour contraindre l'agent, plutôt que d'énumérer les instructions une par une. OpenAI dit « imposez des invariants, ne micromanagez pas l'implémentation » ; Anthropic a constaté que les agents font l'éloge de leur propre travail en toute confiance, et la solution est de séparer « celui qui fait le travail » de « celui qui vérifie le travail ».+- **Retirer les composants un par un** : Pour quantifier la valeur de chaque composant du harness, retirez-les un par un et observez quel retrait provoque la plus forte baisse de performance. Anthropic a utilisé cette méthode et a découvert qu'à mesure que les modèles deviennent plus puissants, certains composants cessent d'être critiques — mais de nouveaux apparaissent toujours.++## Le modèle de harness à cinq sous-systèmes++Retour à l'analogie de la cuisine. Une cuisine complète possède cinq zones fonctionnelles, et un harness possède cinq sous-systèmes :++```mermaid+flowchart LR+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["Tools<br/>shell / files / tests"]+ Tools --> Env["Runtime<br/>deps / services / versions"]+ Env --> Checks["Check results<br/>test / lint / build"]+ Checks --> Agent+```++**Sous-système d'instructions (étagère à recettes)** : Créez `AGENTS.md` (ou `CLAUDE.md`) contenant un aperçu du projet et son objectif (une phrase), la stack technique et les versions (Python 3.11, FastAPI 0.100+, PostgreSQL 15), les commandes de premier lancement (`make setup`, `make test`), les contraintes strictes non négociables (« Toutes les API doivent utiliser OAuth 2.0 »), et des liens vers une documentation plus détaillée.++**Sous-système d'outils (râtelier à couteaux)** : Assurez-vous que l'agent dispose d'un accès suffisant aux outils. Ne désactivez pas le shell pour des raisons de « sécurité » — si l'agent ne peut même pas lancer `pip install`, comment est-il censé travailler ? Mais n'ouvrez pas tout non plus — suivez le principe du moindre privilège.++**Sous-système d'environnement (cuisinière)** : Rendez l'état de l'environnement auto-descriptif. Utilisez `pyproject.toml` ou `package.json` pour verrouiller les dépendances, `.nvmrc` ou `.python-version` pour les versions d'exécution, Docker ou devcontainers pour la reproductibilité.++**Sous-système d'état (plan de travail)** : Les tâches longues nécessitent un suivi de progression. Utilisez un simple fichier `PROGRESS.md` enregistrant : ce qui est terminé, ce qui est en cours, ce qui est bloqué. Mettez à jour avant la fin de chaque session, lisez au démarrage de la session suivante.++**Sous-système de retour (fenêtre de contrôle qualité)** : C'est le sous-système au meilleur retour sur investissement. Listez explicitement les commandes de vérification dans `AGENTS.md` :+```+Verification commands:+- Tests: pytest tests/ -x+- Type check: mypy src/ --strict+- Lint: ruff check src/+- Full verification: make check (includes all above)+```++L'absence d'un sous-système est comme l'absence d'une zone fonctionnelle dans la cuisine — vous pouvez toujours cuisiner, mais c'est toujours laborieux.++**Diagnostiquer la qualité du harness** : Utilisez le « contrôle isométrique du modèle ». Gardez le modèle fixe, retirez les sous-systèmes un par un, mesurez quel retrait provoque la plus forte baisse de performance. C'est votre goulot d'étranglement — concentrez vos efforts là-dessus. Comme trouver le goulot d'étranglement dans une cuisine : retirez l'étagère à recettes et voyez combien les choses ralentissent, coupez la cuisinière et observez l'impact.++## L'histoire vraie d'une équipe++Une équipe a utilisé GPT-4o sur une application frontend TypeScript + React (~20 000 lignes de code). Ils ont traversé quatre étapes — essentiellement ajouter des équipements de cuisine un par un :++**Étape 1 — Cuisine vide** : Seulement une description basique du projet dans le README. 1 essai sur 5 a réussi (20 %). Principaux échecs : mauvais choix de gestionnaire de paquets (npm vs yarn), non-respect des conventions de nommage des composants, impossibilité de lancer les tests.++**Étape 2 — Étagère à recettes installée** : Ajout de `AGENTS.md` avec les versions de la stack technique, les conventions de nommage, les décisions architecturales clés. Le taux de réussite est passé à 60 %. Les échecs restants concernaient principalement des problèmes d'environnement et l'absence de vérification.++**Étape 3 — Fenêtre de contrôle qualité ouverte** : Liste des commandes de vérification dans `AGENTS.md` : `yarn test && yarn lint && yarn build`. Le taux de réussite est passé à 80 %.++**Étape 4 — Plan de travail prêt** : Introduction de modèles de fichiers de progression où les agents enregistraient le travail terminé et non terminé à chaque exécution. Le taux de réussite s'est stabilisé entre 80 et 100 %.++Quatre itérations, le modèle n'a pas du tout changé, le taux de réussite est passé de 20 % à près de 100 %. C'est la puissance du harness engineering. Vous n'avez pas acheté d'ingrédients plus chers — vous avez simplement organisé la cuisine correctement.++## Points clés++- Harness = Instructions + Outils + Environnement + État + Retour. Cinq sous-systèmes, comme les cinq zones fonctionnelles d'une cuisine — tous essentiels.+- Si ce ne sont pas les poids du modèle, c'est du harness. Votre harness détermine quelle part de la capacité du modèle est réellement exploitée.+- Parmi les cinq sous-systèmes, le sous-système de retour offre généralement l'investissement le plus faible et le rendement le plus élevé. Configurez d'abord vos commandes de vérification — la fenêtre de contrôle qualité est l'amélioration la plus rentable.+- Utilisez le « contrôle isométrique du modèle » pour quantifier la contribution marginale de chaque sous-système — ne vous fiez pas à votre intuition.+- Le harness se dégrade comme le code. Auditez régulièrement, remboursez la dette de harness comme vous remboursez la dette technique.++## Pour aller plus loin++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)++## Exercices++1. **Audit harness en cinq tuples** : Prenez un projet où vous utilisez un agent IA et faites un audit complet en utilisant le cadre à cinq tuples. Notez chaque sous-système de 1 à 5. Trouvez le sous-système ayant la note la plus basse, passez 30 minutes à l'améliorer, puis observez le changement de performance de l'agent.++2. **Expérience de contrôle isométrique du modèle** : Choisissez un modèle et une tâche difficile. Retirez séquentiellement les instructions (supprimez AGENTS.md), retirez le retour (ne fournissez pas de commandes de vérification), retirez l'état (pas de fichiers de progression) — ne retirez qu'un seul élément à la fois et mesurez la baisse de performance. En fonction des résultats, classez l'importance des sous-systèmes pour votre projet.++3. **Analyse des affordances** : Trouvez un scénario où l'agent dans votre projet « veut faire quelque chose mais ne peut pas » (par ex., sait qu'il devrait utiliser des requêtes paramétrées mais ne connaît pas les patterns ORM de votre projet). Analysez s'il s'agit d'un Golfe d'Exécution (ne sait pas comment) ou d'un Golfe d'Évaluation (ne sait pas si c'est correct), puis concevez une amélioration du harness pour combler ce fossé.diff --git a/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdnew file mode 100644index 0000000..cf62642--- /dev/null+++ b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md@@ -0,0 +1,7 @@+# Code du Cours 03++Utilisez ce dossier pour des exemples de :++- structures de dépôt lisibles par les agents+- documentation comme système d'enregistrement (system of record)+- mauvais vs bon placement des connaissancesdiff --git a/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txtnew file mode 100644index 0000000..45315da--- /dev/null+++ b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt@@ -0,0 +1,13 @@+AGENTS.md+docs/+ ARCHITECTURE.md+ PRODUCT.md+ RELIABILITY.md+ references/+ electron.md+ sqlite.md+ plans/+ active/+ completed/+src/+scripts/diff --git a/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.tsnew file mode 100644index 0000000..46f6a62--- /dev/null+++ b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts@@ -0,0 +1,189 @@+/**+ * repo-reader.ts+ *+ * Reads a directory structure and scores it on discoverability.+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,+ * handoff files, and other signals of a repository that serves as the+ * system of record.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]+ * (defaults to current working directory if no path given)+ *+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Scoring criteria+// ---------------------------------------------------------------------------++interface Check {+ name: string;+ description: string;+ maxPoints: number;+ check: (dir: string) => { points: number; found: string[]; missing: string[] };+}++const checks: Check[] = [+ {+ name: "AGENTS.md / CLAUDE.md",+ description: "Agent-readable instruction file at repo root",+ maxPoints: 15,+ check: (dir) => {+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };+ },+ },+ {+ name: "Documentation directory",+ description: "Dedicated docs/ or documentation/ directory",+ maxPoints: 10,+ check: (dir) => {+ const candidates = ["docs", "documentation", "doc"];+ const found = candidates.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };+ },+ },+ {+ name: "Architecture documentation",+ description: "Files describing system architecture",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",+ "docs/architecture/", "design.md", "DESIGN.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };+ },+ },+ {+ name: "Feature tracking",+ description: "Feature list or task tracking file",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "feature_list.json", "features.md", "FEATURES.md",+ "docs/features.md", "tasks.json", "TODO.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };+ },+ },+ {+ name: "Handoff / session continuity",+ description: "Files for multi-session continuity",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",+ "docs/handoff.md", ".handoff", "PROGRESS.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };+ },+ },+ {+ name: "Testing structure",+ description: "Test directory or test configuration",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["test", "tests", "__tests__", "spec"];+ const found = patterns.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };+ },+ },+ {+ name: "Configuration files",+ description: "Project config (package.json, tsconfig, etc.)",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };+ },+ },+ {+ name: "README",+ description: "Root README file",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["README.md", "README.rst", "README.txt", "README"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };+ },+ },+];++// ---------------------------------------------------------------------------+// Report generation+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function scoreRepo(targetDir: string): void {+ const resolved = path.resolve(targetDir);++ if (!fs.existsSync(resolved)) {+ console.error(` Error: Directory not found: ${resolved}`);+ process.exit(1);+ }++ console.log("\n" + "=".repeat(80));+ console.log(" REPOSITORY DISCOVERABILITY SCORE");+ console.log("=".repeat(80));+ console.log(` Target: ${resolved}\n`);++ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ let totalScore = 0;+ let maxScore = 0;++ for (const check of checks) {+ const result = check.check(resolved);+ totalScore += result.points;+ maxScore += check.maxPoints;+ const status = result.points > 0 ? "PASS" : "FAIL";+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];++ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);+ }++ // Final score+ console.log("\n" + "-".repeat(80));+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);++ // Grade+ const pct = totalScore / maxScore;+ let grade: string;+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";+ else grade = "F -- Repository lacks discoverability signals";++ console.log(` GRADE: ${grade}`);+ console.log("=".repeat(80) + "\n");+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const target = process.argv[2] || process.cwd();+scoreRepo(target);diff --git a/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.mdnew file mode 100644index 0000000..dbb0925--- /dev/null+++ b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md@@ -0,0 +1,11 @@+# Liste de Contrôle du Système d'Enregistrement++Un nouvel agent peut-il découvrir ce qui suit uniquement depuis le dépôt ?++- Quel produit est en cours de construction ?+- Que doit faire l'application pour les utilisateurs ?+- Comment la base de code est-elle organisée ?+- Comment l'application démarre-t-elle ?+- Comment la santé est-elle vérifiée ?+- Quel travail est actuellement en cours ?+- Quelles normes de qualité sont importantes ?diff --git a/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdnew file mode 100644index 0000000..a7a1b51--- /dev/null+++ b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -0,0 +1,137 @@+[中文版本 →](../../../zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)+> Projet pratique : [Projet 02. Espace de travail lisible par les agents](./../../projects/project-02-agent-readable-workspace/index.md)++# Leçon 03. Faire du dépôt la source unique de vérité++Les décisions d'architecture de votre équipe sont dispersées entre Confluence, Slack, Jira et la tête de quelques ingénieurs seniors. Pour les humains, cela fonctionne tout juste : vous pouvez demander à un collègue, chercher dans l'historique du chat, fouiller la documentation. En dernier recours, vous pouvez coincer quelqu'un en salle de pause. Mais pour un agent IA, l'information qui n'est pas dans le dépôt n'existe tout simplement pas.++Ce n'est pas une exagération. Pensez à ce que sont réellement les entrées d'un agent : prompts système et descriptions de tâche, contenu des fichiers du dépôt, sorties d'outils. C'est tout. Votre historique Slack, vos tickets Jira, vos pages Confluence, et cette décision d'architecture discutée autour d'un café un vendredi après-midi : l'agent ne voit rien de tout cela. Il ne peut pas "aller demander à quelqu'un" ni "chercher dans l'historique du chat". C'est un ingénieur enfermé dans le dépôt ; de tout ce qui est dehors, il ne sait rien.++La question devient donc : allez-vous donner une bonne carte à cet ingénieur ?++## Ce qui doit figurer sur la carte++OpenAI le formule clairement : **l'information qui n'existe pas dans le repo n'existe pas pour l'agent.** Ils appellent cela le principe "repo as spec" : le dépôt lui-même est le document de spécification ayant la plus haute autorité.++La documentation d'Anthropic sur les agents de longue durée dit la même chose : l'état persistant est une condition nécessaire à la continuité des tâches longues. La capacité à récupérer les connaissances entre sessions détermine directement les taux de réussite. Et cet état doit exister dans le dépôt, car c'est le seul stockage stable et accessible dont dispose l'agent.++Vous pourriez penser : "Notre équipe est petite, le savoir est dans la tête de tout le monde, et ça marche." Pour les humains, oui. Mais si vous utilisez un agent, acceptez ce fait : l'agent ne peut pas demander aux gens. Tout ce qu'il doit savoir doit être écrit et placé là où il peut le trouver.++Il ne s'agit pas "d'écrire plus de documentation". Il s'agit de "mettre l'information de décision au bon endroit". Un `ARCHITECTURE.md` de 50 lignes dans le répertoire `src/api/` est dix mille fois plus utile qu'un document de conception de 500 pages dans Confluence que personne ne maintient. C'est comme une carte de bureau dessinée à la main et collée sur votre table, comparée à un magnifique plan d'architecte enfermé dans un classeur : la première est là quand vous en avez besoin ; le second est techniquement supérieur, mais inutile dans l'instant.++## Visibilité du savoir++```mermaid+flowchart LR+ Slack["Règles dans Slack"] --> Write["Les écrire dans les fichiers du repo<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Règles dans Confluence"] --> Write+ Heads["Règles dans la tête des gens"] --> Write+ Jira["Règles dans les tickets Jira"] --> Write+ Write --> Repo["Fichiers du dépôt"]+ Repo --> Agent["Nouvelle session d'agent<br/>lit directement le repo"]+ Warning["Si une règle n'est pas dans le repo,<br/>l'agent ne peut pas la voir"] --> Agent+```++Comment tester si votre carte est suffisante ? Lancez un "test de démarrage à froid" : ouvrez une toute nouvelle session d'agent en utilisant uniquement le contenu du dépôt et voyez si elle peut répondre à cinq questions de base :++```mermaid+flowchart TB+ Q1["Qu'est-ce que ce système ?"] --> A1["AGENTS.md / README"]+ Q2["Comment est-il organisé ?"] --> A2["ARCHITECTURE.md / docs de modules"]+ Q3["Comment l'exécuter ?"] --> A3["Makefile / init.sh / scripts package"]+ Q4["Comment le vérifier ?"] --> A4["Commandes test, lint et check"]+ Q5["Où en sommes-nous ?"] --> A5["PROGRESS.md / feature list / historique git"]++ A1 --> Ready["Une nouvelle session peut commencer à travailler<br/>sans demander à un humain"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready+```++Si elle ne peut pas répondre, la carte a des zones blanches. Là où la carte est vide, l'agent devine : les mauvaises suppositions deviennent des bugs, et trop deviner gaspille du contexte. Et chaque nouvelle session recommence à deviner. Le coût de la supposition est toujours supérieur au coût de dessiner correctement la carte dès le départ.++## Concepts clés++- **Knowledge Visibility Gap** : proportion du savoir total du projet qui N'EST PAS dans le dépôt. Plus l'écart est grand, plus le taux d'échec de l'agent augmente. Combien de savoir implicite sur ce projet vit dans votre tête ? Comptez tout, puis voyez ce qui est arrivé dans le repo : la différence est votre écart de visibilité.+- **System of Record** : le dépôt de code comme source autorisée pour les décisions de projet, contraintes d'architecture, état d'exécution et standards de vérification. Le repo a le dernier mot ; rien d'autre ne compte. Comme une carte qui indique "route fermée" : vous n'y allez pas. Mais si cette information n'existe que dans la tête d'une personne, il faut lui demander à chaque fois.+- **Cold-Start Test** : les cinq questions ci-dessus. Le nombre de réponses indique le degré de complétude de votre carte.+- **Discovery Cost** : budget de contexte que l'agent brûle pour trouver une information clé dans le dépôt. Plus l'information est cachée, plus le coût de découverte est élevé, et moins il reste de budget pour la tâche réelle. Cacher une information critique dans un README dix niveaux plus bas, c'est comme enfermer l'extincteur dans un coffre au sous-sol : il existe, mais vous ne le trouvez pas quand vous en avez besoin.+- **Knowledge Decay Rate** : proportion d'entrées de connaissance qui deviennent obsolètes par unité de temps. Une documentation désynchronisée du code est le plus grand ennemi, pire que pas de documentation du tout.+- **ACID Analogy** : appliquer les principes de transaction de base de données (Atomicity, Consistency, Isolation, Durability) à la gestion d'état des agents. Nous détaillons cela ci-dessous.++## Comment dessiner une bonne carte++**Principe 1 : le savoir vit près du code.** Une règle sur l'authentification des endpoints API doit être à côté du code API, pas enterrée dans un énorme document global. Placez un court document dans chaque répertoire de module expliquant ses responsabilités, interfaces et contraintes particulières. Comme les étiquettes de rayons en bibliothèque : vous voulez des livres d'histoire, vous allez directement au rayon "Histoire". Pas besoin de fouiller toute la bibliothèque.++**Principe 2 : utilisez un fichier d'entrée standardisé.** `AGENTS.md` (ou `CLAUDE.md`) est la page d'accueil de l'agent. Il n'a pas besoin de contenir toute l'information, mais il doit permettre à l'agent de répondre vite à trois questions : "Qu'est-ce que ce projet ?", "Comment l'exécuter ?" et "Comment le vérifier ?". 50-100 lignes suffisent.++**Principe 3 : minimal mais complet.** Chaque élément de savoir doit avoir un cas d'usage clair. Si supprimer une règle n'affecte pas la qualité de décision de l'agent, cette règle ne devrait pas exister. Mais chaque question du test de démarrage à froid doit avoir une réponse. C'est un équilibre délicat : ni trop, ni trop peu, juste assez.++**Principe 4 : mettez à jour avec le code.** Liez les mises à jour de connaissance aux changements de code. L'approche la plus simple : placer les documents d'architecture dans le répertoire du module correspondant. Quand vous modifiez le code, vous voyez naturellement le document. Après les changements de code, CI peut vous rappeler de vérifier si les docs doivent être mises à jour.++**Structure concrète du repo** :++```+project/+├── AGENTS.md # Entry: project overview, run commands, hard constraints+├── src/+│ ├── api/+│ │ ├── ARCHITECTURE.md # API layer architecture decisions+│ │ └── ...+│ ├── db/+│ │ ├── CONSTRAINTS.md # Database operation hard constraints+│ │ └── ...+│ └── ...+├── PROGRESS.md # Current progress: done, in-progress, blocked+└── Makefile # Standardized commands: setup, test, lint, check+```++## Gérer l'état des agents avec les principes ACID++Cette analogie vient de la gestion des transactions en base de données. Vous pouvez penser que cela complique les choses, mais elle fournit en réalité un cadre très pratique :++- **Atomicity** : chaque "opération logique" (par exemple "ajouter un nouvel endpoint et mettre à jour les tests") correspond à un commit git. Si elle échoue en cours de route, `git stash` permet de revenir en arrière. Tout ou rien : pas de "à moitié fait".+- **Consistency** : définissez des prédicats de vérification d'un "état cohérent" : tous les tests passent, le lint ne rapporte aucune erreur. L'agent exécute la vérification après chaque opération ; les états intermédiaires incohérents ne sont pas commités. Comme un virement bancaire : on ne débite pas sans créditer.+- **Isolation** : quand plusieurs agents travaillent en parallèle, concevez les fichiers d'état pour éviter les conditions de course. Approche simple : chaque agent utilise son propre fichier de progrès, ou des branches git assurent l'isolation. Deux cuisiniers ne peuvent pas assaisonner la même marmite en même temps : qui est responsable si c'est trop salé ?+- **Durability** : le savoir critique du projet vit dans des fichiers suivis par git. L'état temporaire peut rester en mémoire de session, mais le savoir entre sessions doit être persisté dans des fichiers. Ce qui est dans votre tête ne compte pas ; seul ce qui est écrit compte.++## Une vraie histoire de transformation++Une équipe maintenait une plateforme e-commerce avec environ 30 microservices. Les décisions d'architecture (protocoles de communication interservices, stratégies de cohérence des données, règles de versioning API) étaient dispersées entre Confluence (partiellement obsolète), Slack (difficile à rechercher), la tête de quelques ingénieurs seniors (non scalable) et des commentaires de code sporadiques (pas systématiques).++Après l'introduction d'agents IA, 70% des tâches nécessitaient une intervention humaine. Presque chaque échec impliquait que l'agent violait une contrainte implicite que "tout le monde connaît mais que personne n'a écrite". C'est comme un nouvel employé à qui personne n'a dit "tu dois poster ta commande de déjeuner dans le chat du groupe" : il devine mal, se fait reprendre, mais après la remarque personne n'écrit la règle.++L'équipe a mené une transformation :+1. Création d'un `AGENTS.md` à la racine du repo avec aperçu du projet, versions du stack technique et contraintes globales dures+2. Ajout d'un `ARCHITECTURE.md` dans chaque répertoire de microservice décrivant responsabilités, interfaces et dépendances+3. Création d'un `CONSTRAINTS.md` centralisé avec les contraintes dures en langage explicite "MUST/MUST NOT"+4. Ajout d'un `PROGRESS.md` dans chaque répertoire de service pour suivre l'état de travail actuel++Après transformation, le même agent pouvait répondre à toutes les questions clés du projet au démarrage à froid, et la qualité d'achèvement des tâches s'est nettement améliorée.++## Points clés++- Le savoir absent du repo n'existe pas pour l'agent. Mettre les décisions critiques dans le repo est l'investissement harness le plus fondamental : dessinez une bonne carte pour ne pas vous perdre.+- Utilisez le "test de démarrage à froid" pour évaluer la qualité du repo : une session fraîche peut-elle répondre à cinq questions de base avec le seul contenu du dépôt ?+- Le savoir doit être près du code, minimal mais complet, et mis à jour avec le code. Il ne s'agit pas d'écrire plus de docs, mais de mettre l'information au bon endroit.+- Utilisez les principes ACID pour l'état des agents : commits atomiques, vérification de cohérence, isolation de la concurrence, savoir critique durable.+- La dégradation du savoir est le plus grand ennemi. Une documentation désynchronisée du code est plus dangereuse qu'une absence de documentation : elle envoie l'agent dans la mauvaise direction alors qu'il pense avoir raison.++## Pour aller plus loin++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [ADR: Architecture Decision Records](https://adr.github.io/)+- [The Twelve-Factor App](https://12factor.net/)++## Exercices++1. **Test de démarrage à froid** : ouvrez une session d'agent complètement fraîche dans votre projet (aucun contexte verbal, contenu du repo seulement). Posez cinq questions : Qu'est-ce que ce système ? Comment est-il organisé ? Comment l'exécuter ? Comment le vérifier ? Quel est l'avancement actuel ? Notez ce qu'il ne peut pas répondre, puis améliorez le repo jusqu'à ce qu'il puisse.++2. **Quantification de l'externalisation du savoir** : listez toutes les décisions et contraintes importantes pour le travail de développement dans votre projet. Marquez chacune comme étant dans ou hors du repo. Calculez votre Knowledge Visibility Gap (proportion hors repo). Faites un plan pour le descendre sous 10%.++3. **Évaluation ACID** : évaluez la gestion d'état de votre projet avec l'analogie ACID de cette leçon. Atomicity : les opérations d'agent peuvent-elles être annulées proprement ? Consistency : existe-t-il une vérification d'"état cohérent" ? Isolation : les agents concurrents se marchent-ils dessus ? Durability : tout le savoir intersessions est-il persisté ?diff --git a/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdnew file mode 100644index 0000000..b7b98ac--- /dev/null+++ b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -0,0 +1,15 @@+# AGENTS.md++## Commencez ici++- Lisez `docs/ARCHITECTURE.md`+- Lisez `docs/PRODUCT.md`+- Utilisez `npm run dev` pour démarrer l'application+- Utilisez `npm run check` avant de marquer le travail comme terminé++## Règles strictes++- Ne modifiez pas les limites main/preload/renderer d'Electron sans avoir lu+ `docs/ARCHITECTURE.md`+- Ne marquez pas une fonctionnalité comme terminée sans vérification+- Laissez un état propre (clean state) pour la prochaine sessiondiff --git a/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdnew file mode 100644index 0000000..8994ed0--- /dev/null+++ b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -0,0 +1,7 @@+# Anti-Patrons des Fichiers d'Instructions++- Mettre toutes les connaissances du dépôt dans un seul fichier+- Répéter la même règle à plusieurs endroits+- Encoder des règles obsolètes que personne n'audit+- Écrire des instructions conditionnelles si spécifiques qu'elles s'appliquent rarement+- Intégrer de longs manuels d'outils dans le contexte de démarragediff --git a/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdnew file mode 100644index 0000000..e90e2a5--- /dev/null+++ b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md@@ -0,0 +1,7 @@+# Code du Cours 04++Utilisez ce dossier pour des exemples de :++- fichiers d'instructions monolithiques+- points d'entrée courts+- motifs de divulgation progressive (progressive disclosure)diff --git a/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.tsnew file mode 100644index 0000000..59a9632--- /dev/null+++ b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts@@ -0,0 +1,209 @@+/**+ * split-vs-monolithic.ts+ *+ * Creates a monolithic instruction file (~200 lines) and then shows how+ * splitting into 4 focused files dramatically reduces the context needed+ * for any single query. Simulates an "agent" searching for a specific rule+ * and measures how many lines it must read in each approach.+ *+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts+ */++// ---------------------------------------------------------------------------+// Simulated monolithic instruction file (200 lines of rules)+// ---------------------------------------------------------------------------++const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];++// Section 1: Project Overview (lines 1-50)+for (let i = 1; i <= 50; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Project Overview",+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,+ });+}++// Section 2: Code Style Rules (lines 51-100)+for (let i = 51; i <= 100; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Code Style",+ content:+ i === 72+ ? "RULE: Always use explicit return types on exported functions."+ : i === 78+ ? "RULE: Use const assertions for immutable arrays."+ : `Style rule detail line ${i}`,+ });+}++// Section 3: Testing Standards (lines 101-150)+for (let i = 101; i <= 150; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Testing",+ content:+ i === 120+ ? "RULE: Every new endpoint must have integration tests."+ : i === 135+ ? "RULE: Test files must mirror the source file structure."+ : `Testing detail line ${i}`,+ });+}++// Section 4: Deployment Rules (lines 151-200)+for (let i = 151; i <= 200; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Deployment",+ content:+ i === 175+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."+ : `Deployment detail line ${i}`,+ });+}++// ---------------------------------------------------------------------------+// Split instruction files (4 focused files)+// ---------------------------------------------------------------------------++const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),+};++// ---------------------------------------------------------------------------+// Simulated queries -- the agent needs to find specific rules+// ---------------------------------------------------------------------------++interface Query {+ description: string;+ targetRule: string;+ relevantSection: string;+}++const queries: Query[] = [+ {+ description: "Find the rule about return types",+ targetRule: "explicit return types",+ relevantSection: "Code Style",+ },+ {+ description: "Find the deployment window rule",+ targetRule: "deploy on Fridays",+ relevantSection: "Deployment",+ },+ {+ description: "Find the integration test rule",+ targetRule: "integration tests",+ relevantSection: "Testing",+ },+ {+ description: "Find the test file structure rule",+ targetRule: "mirror the source file",+ relevantSection: "Testing",+ },+];++// ---------------------------------------------------------------------------+// Search simulation+// ---------------------------------------------------------------------------++function searchMonolithic(query: Query): { linesRead: number; found: boolean } {+ // Agent must scan from the top, reading each line until it finds the rule.+ // In the worst case it reads all lines.+ let linesRead = 0;+ let found = false;++ for (const line of monolithicInstructions) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found };+}++function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {+ // Agent knows which file to look in based on the section.+ // It only reads lines from that one file.+ const fileMap: Record<string, string> = {+ "Project Overview": "01-project-overview.md",+ "Code Style": "02-code-style.md",+ Testing: "03-testing.md",+ Deployment: "04-deployment.md",+ };++ const targetFile = fileMap[query.relevantSection];+ const lines = splitInstructions[targetFile];+ let linesRead = 0;+ let found = false;++ for (const line of lines) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found, fileAccessed: targetFile };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");+ console.log("=".repeat(90));++ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");++ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;+ console.log(header);+ console.log(sep);++ let totalMono = 0;+ let totalSplit = 0;++ for (const q of queries) {+ const mono = searchMonolithic(q);+ const split = searchSplit(q);+ totalMono += mono.linesRead;+ totalSplit += split.linesRead;++ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);+ console.log(+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`+ );+ }++ console.log(sep);+ const avgMono = Math.round(totalMono / queries.length);+ const avgSplit = Math.round(totalSplit / queries.length);+ console.log(+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`+ );++ console.log("\n" + "=".repeat(90));+ console.log(" KEY INSIGHT");+ console.log("=".repeat(90));+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");+}++run();diff --git a/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdnew file mode 100644index 0000000..7102d89--- /dev/null+++ b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -0,0 +1,132 @@+[中文版本 →](../../../zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)+> Projet pratique : [Projet 02. Espace de travail lisible par les agents](./../../projects/project-02-agent-readable-workspace/index.md)++# Leçon 04. Répartir les instructions entre fichiers++Vous avez pris le harness engineering au sérieux. Vous avez créé un `AGENTS.md` et vous y avez mis toutes les règles, contraintes et leçons apprises auxquelles vous pouviez penser. Un mois plus tard, le fichier faisait 300 lignes ; deux mois plus tard, 450 ; trois mois plus tard, 600. Puis vous remarquez que les performances de l'agent se dégradent : sur une simple correction de bug, il consomme beaucoup de contexte à traiter des instructions de déploiement sans rapport ; une contrainte de sécurité critique enfouie à la ligne 300 est ignorée ; trois règles de style contradictoires font que l'agent en choisit une au hasard à chaque fois.++C'est le piège du "fichier d'instructions géant". C'est comme une valise trop remplie : tout semble utile, donc on tasse jusqu'à ce que la fermeture menace de céder. Pour trouver un sous-vêtement de rechange, il faut vider tout le sac. Vous transportez une valise pleine, mais vous n'utilisez peut-être qu'un tiers de ce qu'elle contient.++## Le cycle vicieux à la racine++Le cycle vicieux le plus courant ressemble à ceci : l'agent fait une erreur, vous dites "ajoutons une règle pour empêcher ça", vous l'ajoutez à `AGENTS.md`, cela fonctionne temporairement, l'agent fait une autre erreur, vous ajoutez une autre règle, vous recommencez, et le fichier enfle hors de contrôle.++Ce n'est pas votre faute. C'est une réaction très naturelle : ajouter une règle chaque fois que quelque chose se passe mal paraît raisonnable, comme mettre un objet de plus dans son sac en sortant "au cas où". Mais l'effet cumulatif est désastreux. Regardons précisément ce qui se dégrade.++**Le budget de contexte se fait dévorer.** La fenêtre de contexte de l'agent est finie. Supposons qu'il dispose d'une fenêtre de 200K tokens (un standard chez Claude). Un fichier d'instructions gonflé peut consommer 10-20K tokens. Il semble rester beaucoup de place ? Mais une tâche complexe peut exiger de lire des dizaines de fichiers source, les sorties d'outils prennent aussi du contexte, et l'historique de conversation s'accumule. Au moment où l'agent doit comprendre le code, le budget est déjà serré, comme une valise tellement pleine d'objets "au cas où" qu'il n'y a plus de place pour l'ordinateur portable.++**Perdu au milieu.** L'article "Lost in the Middle" (Liu et al., 2023) a montré clairement que les LLM utilisent les informations situées au milieu de longs textes nettement moins efficacement que celles du début ou de la fin. Votre `AGENTS.md` fait 600 lignes, et la ligne 300 dit "toutes les requêtes de base de données doivent utiliser des requêtes paramétrées" : c'est une contrainte de sécurité forte. Mais elle est enfouie au milieu, et l'agent l'ignorera très probablement. Comme cette bouteille de crème solaire au fond d'une valise trop pleine : vous savez qu'elle est là, vous fouillez trois fois, vous ne la trouvez pas, et vous finissez par en racheter une.++**Conflits de priorité.** Le fichier mélange des contraintes non négociables ("never use eval()"), des lignes directrices importantes ("prefer functional style") et une leçon historique spécifique ("une fuite mémoire WebSocket a été corrigée la semaine dernière, surveiller les motifs similaires"). Ces trois règles ont des niveaux d'importance complètement différents, mais elles se ressemblent dans le fichier. L'agent n'a aucun signal fiable pour les distinguer, comme si votre passeport et votre câble de charge étaient mélangés dans la valise sans moyen de savoir lequel est le plus urgent.++**Déclin de maintenance.** Les gros fichiers sont intrinsèquement difficiles à maintenir. Les instructions obsolètes sont rarement supprimées, car les conséquences d'une suppression sont incertaines ("peut-être que quelque chose dépend de cette règle"), tandis que l'ajout de nouvelles instructions paraît gratuit. Résultat : le fichier ne fait que grandir, ne rétrécit jamais, et le rapport signal-bruit baisse en continu. C'est exactement l'accumulation de dette technique appliquée aux instructions.++**Accumulation de contradictions.** Les instructions ajoutées à différents moments finissent par se contredire : l'une dit "utiliser TypeScript strict mode", l'autre dit "certains fichiers legacy autorisent les types any". L'agent choisit au hasard laquelle suivre à chaque fois. Comme si votre mère disait "couvre-toi" et votre père "ne mets pas trop de couches", et que vous restiez à la porte sans savoir qui écouter.++## Concepts clés++- **Instruction Bloat** : lorsqu'un fichier d'instructions occupe plus de 10-15% de la fenêtre de contexte, il commence à évincer le budget nécessaire à la lecture du code et au raisonnement sur la tâche. Un `AGENTS.md` de 600 lignes peut consommer 10 000-20 000 tokens, soit 8-15% d'une fenêtre de 128K avant même que l'agent commence.+- **Lost in the Middle Effect** : les travaux de Liu et al. en 2023 ont montré que les LLM utilisent beaucoup moins efficacement les informations au milieu de longs textes que celles du début ou de la fin. Une contrainte critique enfouie à la ligne 300 d'un fichier de 600 lignes a une forte probabilité d'être ignorée en pratique.+- **Instruction Signal-to-Noise Ratio (SNR)** : proportion des instructions d'un fichier qui sont pertinentes pour la tâche actuelle. Être obligé de lire 50 lignes de déploiement pendant une correction de bug, c'est un SNR faible.+- **Routing File** : fichier d'entrée court dont le rôle principal est d'orienter l'agent vers des documents plus détaillés, pas de tout contenir lui-même. 50-200 lignes suffisent.+- **Progressive Disclosure** : donner d'abord la vue d'ensemble, puis les détails quand ils deviennent nécessaires. Un bon design de harness ressemble à un bon design d'interface : ne pas déverser toutes les options d'un coup.+- **Priority Ambiguity** : lorsque toutes les instructions apparaissent au même format et au même endroit, l'agent ne peut pas distinguer les contraintes dures non négociables des simples recommandations.++## Architecture des instructions++```mermaid+flowchart LR+ Mono["Un AGENTS.md de 600 lignes"] --> MonoLoad["Même un petit bug fix<br/>doit lire règles de déploiement et vieilles notes"]+ MonoLoad --> MonoRisk["Les règles importantes enfouies au milieu<br/>sont faciles à manquer"]++ Router["AGENTS.md court"] --> Topics["Charger les docs API / DB / testing<br/>seulement quand la tâche en a besoin"]+ Topics --> RoutedResult["Plus de contexte restant pour lire le code<br/>et vérifier"]+```++```mermaid+flowchart TB+ File["Fichier d'instructions de 600 lignes"] --> Top["Section haute<br/>quick start + contraintes dures"]+ File --> Mid["Section centrale<br/>règle de sécurité critique à la ligne 300"]+ File --> Bot["Section basse<br/>checklist explicite de fin"]+ Top --> Seen["Forte chance d'être rappelé"]+ Bot --> Seen+ Mid --> Missed["Forte chance d'être dilué ou manqué"]+```++## Comment découper++Principe central : gardez à portée de main les informations fréquemment nécessaires, rangez celles qui ne servent qu'occasionnellement, et supprimez ce que vous n'utiliserez jamais.++Le fichier d'entrée `AGENTS.md` reste entre 50 et 200 lignes et ne contient que les éléments les plus souvent utilisés : aperçu du projet (une ou deux phrases), commandes de premier lancement (`make setup && make test`), contraintes globales dures (pas plus de 15 règles non négociables), et liens vers des documents thématiques (description en une ligne + condition d'applicabilité).++```markdown+# AGENTS.md++## Vue d'ensemble du projet+Python 3.11 FastAPI backend, PostgreSQL 15 database.++## Quick Start+- Install: `make setup`+- Test: `make test`+- Full verification: `make check`++## Hard Constraints+- All APIs must use OAuth 2.0 authentication+- All database queries must use SQLAlchemy 2.0 syntax+- All PRs must pass pytest + mypy --strict + ruff check++## Topic Docs+- [API Design Patterns](docs/api-patterns.md) — Required reading when adding endpoints+- [Database Rules](docs/database-rules.md) — Required when modifying database operations+- [Testing Standards](docs/testing-standards.md) — Reference when writing tests+```++Chaque document thématique fait 50-150 lignes, organisé par sujet dans `docs/` ou près du module correspondant. L'agent ne les lit que lorsque c'est nécessaire. Comme des pochettes de rangement dans une valise : les sous-vêtements dans l'une, les produits de toilette dans une autre, les chargeurs dans une troisième. Trouver quelque chose n'exige pas de vider tout le sac.++Certaines informations sont mieux placées directement dans le code : définitions de types, commentaires d'interface, explications dans les fichiers de configuration. L'agent les voit naturellement en lisant le code, inutile de les dupliquer dans les instructions.++Chaque instruction devrait avoir une source ("pourquoi cette règle a-t-elle été ajoutée ?"), une condition d'applicabilité ("quand cette règle est-elle nécessaire ?") et une condition d'expiration ("dans quelles circonstances peut-on la supprimer ?"). Auditez régulièrement, retirez les entrées obsolètes, redondantes et contradictoires. Gérez vos instructions comme vos dépendances de code : les dépendances inutilisées doivent être supprimées, sinon elles ralentissent simplement le système.++Si une instruction doit absolument rester dans le fichier d'entrée, mettez-la en haut ou en bas, jamais au milieu. L'effet "lost in the middle" nous dit que les LLM exploitent bien mieux les informations aux extrémités qu'au centre. Mais la meilleure approche reste de déplacer les instructions dans des documents thématiques chargés à la demande.++OpenAI et Anthropic soutiennent implicitement cette approche de découpage. OpenAI dit que les fichiers d'entrée doivent être "courts et orientés routage", Anthropic dit que les informations de contrôle des agents de longue durée doivent être "concises et prioritaires". Ils disent la même chose : ne mettez pas tout dans un seul fichier. Une valise a besoin d'organisation, pas d'un bourrage en force.++## Exemple réel++Le `AGENTS.md` d'une équipe SaaS est passé de 50 à 600 lignes. Il mélangeait versions du stack technique, standards de code, notes historiques de correction de bugs, guides d'usage d'API, procédures de déploiement et préférences personnelles des membres de l'équipe : toute la valise était prête à éclater.++Les performances de l'agent ont commencé à décliner nettement : pendant de simples corrections de bugs, il dépensait beaucoup de contexte sur des instructions de déploiement sans rapport ; la contrainte de sécurité "toutes les requêtes de base de données doivent utiliser des requêtes paramétrées" était enfouie à la ligne 300 et souvent ignorée ; trois règles de style contradictoires provoquaient un comportement aléatoire.++L'équipe a effectué une "réorganisation de valise" :+1. `AGENTS.md` réduit à 80 lignes : seulement aperçu du projet, commandes d'exécution et 15 contraintes globales dures+2. Création de documents thématiques : `docs/api-patterns.md` (120 lignes), `docs/database-rules.md` (60 lignes), `docs/testing-standards.md` (80 lignes)+3. Ajout de liens vers ces documents dans le fichier de routage+4. Notes historiques converties en tests ou supprimées++Après refactorisation, le taux de réussite du même ensemble de tâches est passé de 45% à 72%. Le respect de la contrainte de sécurité est passé de 60% à 95%, parce qu'elle a été déplacée du milieu du fichier vers le haut du fichier de routage, et n'était plus "perdue au milieu".++## Points clés++- "Ajouter une règle" soulage à court terme, mais empoisonne à long terme. Avant d'ajouter une règle, demandez : serait-elle mieux dans un document thématique ? Ne continuez pas à tasser la valise.+- Le fichier d'entrée est un routeur, pas une encyclopédie. 50-200 lignes avec aperçu, contraintes dures et liens seulement.+- Exploitez l'effet "lost in the middle" : les informations importantes vont en haut ou en bas ; les informations moins importantes vont dans des documents thématiques.+- Gérez le gonflement des instructions comme de la dette technique. Audits réguliers ; chaque instruction a besoin d'une source, d'une condition d'applicabilité et d'une condition d'expiration.+- Après le découpage, le SNR s'améliore et l'agent dépense plus de budget de contexte sur la tâche réelle au lieu de traiter des instructions sans rapport.++## Pour aller plus loin++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)++## Exercices++1. **Audit SNR** : prenez votre fichier actuel d'instructions d'entrée et listez toutes les instructions. Choisissez 5 types de tâches courantes et marquez si chaque instruction est pertinente pour cette tâche. Calculez le SNR pour chaque type de tâche. Les instructions qui sont du bruit pour la plupart des tâches doivent aller dans des documents thématiques.++2. **Refactorisation en progressive disclosure** : si vous avez un fichier d'instructions de plus de 300 lignes, découpez-le en : (a) un fichier de routage de moins de 100 lignes, (b) 3-5 documents thématiques. Exécutez le même ensemble de tâches (au moins 5) avant et après, puis comparez les taux de réussite.++3. **Vérification lost in the middle** : dans un long fichier d'instructions, placez une contrainte critique respectivement au début, au milieu et à la fin, en exécutant le même ensemble de tâches à chaque fois (au moins 5 exécutions par position). Observez s'il existe une différence de taux de conformité. L'effet de position peut être étonnamment fort.diff --git a/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.mdnew file mode 100644index 0000000..7efc22d--- /dev/null+++ b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md@@ -0,0 +1,6 @@+# Liste de Contrôle de Continuité++- Un nouvel agent peut-il identifier le travail récent en moins de cinq minutes ?+- Le chemin de démarrage stable actuel est-il documenté ?+- Le travail inachevé est-il clairement identifié ?+- La prochaine meilleure tâche est-elle visible sans lire les anciens journaux de chat ?diff --git a/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdnew file mode 100644index 0000000..e014ec4--- /dev/null+++ b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md@@ -0,0 +1,7 @@+# Code du Cours 05++Utilisez ce dossier pour des exemples de :++- tâches multi-sessions interrompues+- artefacts de continuité manquants+- motifs de récupération de continuitédiff --git a/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdnew file mode 100644index 0000000..e476853--- /dev/null+++ b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -0,0 +1,17 @@+# Exemple de Passation de Session++## Terminé++- Ajout du support d'importation Markdown+- Ajout d'une liste de documents basique dans le renderer++## Cassé ou Non Vérifié++- L'importation réussit pour `.md` mais échoue pour les fichiers `.txt` volumineux+- L'application démarre, mais la vue détaillée n'est pas encore connectée++## Prochaine Meilleure Étape++- Corriger le chemin d'importation `.txt`+- Vérifier l'importation de bout en bout+- Puis ajouter le panneau de détail du documentdiff --git a/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.tsnew file mode 100644index 0000000..69f9c3e--- /dev/null+++ b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts@@ -0,0 +1,162 @@+/**+ * session-simulator.ts+ *+ * Simulates two sessions working on a multi-step task.+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.+ * Run 2: With handoff file -- Session B picks up where Session A left off.+ *+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface TaskStep {+ id: number;+ name: string;+ durationMs: number;+}++interface SessionResult {+ session: string;+ stepsCompleted: number;+ totalDurationMs: number;+ duplicatedSteps: number;+ output: string[];+}++// ---------------------------------------------------------------------------+// Task definition+// ---------------------------------------------------------------------------++const taskSteps: TaskStep[] = [+ { id: 1, name: "Read project structure", durationMs: 50 },+ { id: 2, name: "Understand existing auth module", durationMs: 80 },+ { id: 3, name: "Design new search endpoint", durationMs: 60 },+ { id: 4, name: "Implement search endpoint", durationMs: 100 },+ { id: 5, name: "Write integration tests", durationMs: 70 },+ { id: 6, name: "Update documentation", durationMs: 40 },+];++// ---------------------------------------------------------------------------+// Simulated session executor+// ---------------------------------------------------------------------------++/** Simulate a session doing work. */+function runSession(+ sessionName: string,+ startStep: number,+ endStep: number+): SessionResult {+ const output: string[] = [];+ let totalDuration = 0;++ for (let i = startStep; i <= endStep; i++) {+ const step = taskSteps.find((s) => s.id === i)!;+ totalDuration += step.durationMs;+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);+ }++ return {+ session: sessionName,+ stepsCompleted: endStep - startStep + 1,+ totalDurationMs: totalDuration,+ duplicatedSteps: 0,+ output,+ };+}++// ---------------------------------------------------------------------------+// Run 1: No handoff file+// ---------------------------------------------------------------------------++function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 before timing out+ const sessionA = runSession("Session A", 1, 3);++ // Session B has no context, starts from scratch+ const sessionB = runSession("Session B", 1, 6);+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Run 2: With handoff file+// ---------------------------------------------------------------------------++function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 and writes a handoff file+ const sessionA = runSession("Session A", 1, 3);++ // Session B reads handoff, starts from step 4+ const sessionB = runSession("Session B", 4, 6);+ sessionB.duplicatedSteps = 0;++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {+ console.log("\n" + "=".repeat(80));+ console.log(` ${title}`);+ console.log("=".repeat(80));++ console.log("\n Session A output:");+ for (const line of result.sessionA.output) {+ console.log(line);+ }++ console.log("\n Session B output:");+ for (const line of result.sessionB.output) {+ console.log(line);+ }++ console.log("\n Session B notes:");+ if (result.sessionB.duplicatedSteps > 0) {+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);+ } else {+ console.log(" - Read handoff file, continued from step 4");+ console.log(" - No duplicate work performed");+ }+}++function printComparison(): void {+ const noHandoff = simulateNoHandoff();+ const withHandoff = simulateWithHandoff();++ printRun("RUN 1: NO HANDOFF FILE", noHandoff);+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);++ // Comparison table+ console.log("\n" + "=".repeat(80));+ console.log(" COMPARISON TABLE");+ console.log("=".repeat(80) + "\n");++ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log(header);+ console.log(sep);++ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;++ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);++ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");+}++printComparison();diff --git a/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdnew file mode 100644index 0000000..4209481--- /dev/null+++ b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -0,0 +1,180 @@+[中文版本 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)+> Projet pratique : [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# Leçon 05. Garder le contexte vivant entre les sessions++Vous demandez à Claude Code d'implémenter une fonctionnalité complète. Il tourne pendant 30 minutes, fait la majeure partie du travail, mais le contexte commence à manquer. Vous lancez une nouvelle session pour continuer — et découvrez qu'il ne se souvient pas des décisions prises la dernière fois, pourquoi l'option A a été choisie plutôt que l'option B, quels fichiers ont déjà été modifiés, ou dans quel état se trouvent les tests. Il passe 15 minutes à réexplorer le projet, et risque d'être en contradiction avec l'approche précédente.++Imaginez que vous êtes un artisan qui oublie tout chaque matin en vous réveillant. Vous devriez vous refamiliariser avec l'ensemble du chantier — quel mur est à moitié construit, pourquoi des briques rouges ont été choisies plutôt que des bleues, où en sont les passages de plomberie. Pire, vous pourriez arracher une fenêtre qui a déjà été installée hier, simplement parce que vous ne vous souveniez pas que c'était fait.++C'est exactement la situation dans laquelle se trouvent les agents de codage IA lors de tâches multi-sessions. Cette leçon explique pourquoi les agents « perdent le fil » pendant les tâches longues, et comment la persistance structurée de l'état peut les transformer en un artisan qui tient un journal fiable chaque jour — toujours amnésique, mais le journal se souvient de tout.++## Fenêtres de contexte : pas infinies++Les fenêtres de contexte sont finies. Ce n'est pas résolu par les mises à niveau de modèles — même si les tailles de fenêtre atteignent 1M de tokens, les tâches complexes les épuiseront toujours. Parce que les agents ne se contentent pas de générer du code ; ils comprennent les codebases, suivent leur propre historique de décisions, traitent les sorties des outils et maintiennent le contexte de conversation. Toutes ces informations croissent plus vite que l'expansion des fenêtres.++Un problème plus profond : les informations que l'agent produit ne sont pas uniformément importantes. Les étapes de raisonnement intermédiaires contiennent le « pourquoi » des décisions — pourquoi l'option B a été choisie plutôt que A, pourquoi cette bibliothèque plutôt qu'une autre, pourquoi une optimisation particulière a été écartée. La sortie finale ne contient que le « quoi » — le code lui-même. Les stratégies de compaction préservent généralement ce dernier mais perdent le premier. La session suivante voit le code mais ne sait pas pourquoi il est écrit de cette façon, et pourrait « optimiser » à tort une décision de conception délibérée.++Anthropic a découvert quelque chose de fascinant dans sa recherche sur les agents longue durée : quand les agents sentent que le contexte diminue, ils présentent un comportement de « convergence prématurée » — se précipitant pour terminer le travail en cours, sautant les étapes de vérification, ou choisissant une solution simple plutôt qu'optimale. C'est comme réaliser que le temps est presque écoulé à un examen et deviner rapidement les questions à choix multiples restantes. Anthropic appelle cela l'« anxiété de contexte ».++## Flux de continuité entre sessions++Sans artefacts de continuité, chaque nouvelle session est un désastre :++```mermaid+flowchart LR+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]+ End1 --> S2["Session 2 starts fresh"]+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]+```++Avec des artefacts de continuité, les nouvelles sessions peuvent reprendre rapidement :++```mermaid+flowchart LR+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]+ Work --> Verify["Verification notes<br/>which tests pass and fail"]+ Work --> Commit["Git checkpoint<br/>exact repo state"]++ Progress --> Rebuild["Session 2 rebuild"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["New session picks up quickly"]+```++## Concepts clés++- **Les fenêtres de contexte sont finies** : Quelle que soit la taille de fenêtre annoncée (128K, 200K, 1M), les tâches longues finiront par les épuiser. Après épuisement, soit la compaction (perte d'informations) soit la réinitialisation (nouvelle session) est nécessaire. Les deux perdent quelque chose.+- **Artefacts de continuité** : Fichiers d'état persistés qui permettent à une nouvelle session de reprendre sans ambiguïté là où la précédente s'est arrêtée. La forme de base : journal de progression + enregistrement de vérification + actions suivantes. Le journal de l'artisan.+- **Coût de reconstruction** : Le temps nécessaire à une nouvelle session pour atteindre un état exécutable. Les bons harness peuvent comprimer le coût de reconstruction de 15 minutes à 3 minutes.+- **Dérive** : L'écart entre la compréhension de l'agent et l'état réel du dépôt de code. Chaque frontière de session introduit de la dérive ; sans contrôle, elle se cumule.+- **Anxiété de contexte** : Un phénomène observé par Anthropic — les agents présentent un comportement de convergence prématurée à l'approche des limites de contexte perçues, terminant les tâches prématurément pour éviter la perte d'informations. C'est une anxiété irrationnelle face aux ressources.+- **Compaction vs réinitialisation** : La compaction résume le contexte au sein de la même session (conserve le « quoi », peut perdre le « pourquoi ») ; la réinitialisation ouvre une nouvelle session reconstruisant à partir de l'état persisté (propre mais dépend de l'exhaustivité des artefacts).++## Ce qui se passe quand la continuité se brise++La session précédente a dépensé un budget de contexte significatif à analyser trois approches et choisir l'option B. L'agent de cette session ne connaît pas cette analyse et pourrait redécider sur la base d'informations incomplètes — choisissant potentiellement l'option A. Comme l'artisan amnésique qui ne se souvient pas pourquoi des briques rouges ont été choisies, regarde les bleues aujourd'hui et les trouve plus jolies, et démolit le mur d'hier pour reconstruire.++Pire encore est le travail en double. L'agent n'est pas sûr que certains travaux aient déjà été complétés et les refait. Ou pire — en fait la moitié, découvre un conflit avec l'implémentation existante, et doit tout reprendre. Sur un chantier de construction, deux équipes ne peuvent pas construire le même mur simultanément — mais sans registre de progression, la nouvelle équipe ne sait pas que quelqu'un travaille déjà dessus.++Au fil de plusieurs sessions, la direction d'implémentation peut avoir silencieusement dévié des exigences initiales. Chaque nouvelle session a une compréhension légèrement différente des objectifs du projet. Comme un jeu de téléphone arabe — après que dix personnes ont transmis le message, « passe me prendre un café » peut devenir « achète-moi une machine à café ».++Il y a aussi le fossé de vérification. Les résultats de vérification de la session précédente (quels tests passent, lesquels échouent, pourquoi ils échouent) n'ont pas été enregistrés. La nouvelle session doit relancer toutes les vérifications pour comprendre l'état actuel. Chaque session rediagnostique à partir de zéro, gaspillant chaque fois un contexte précieux.++OpenAI et Anthropic soulignent tous deux la persistance structurée de l'état dans leur documentation. L'article sur le harness engineering d'OpenAI traite le dépôt comme un « registre opérationnel » — chaque résultat d'opération devrait laisser une trace vérifiable dans le repo. La documentation d'Anthropic sur les agents longue durée recommande spécifiquement des « fichiers de passation » — des documents structurés contenant l'état actuel, les problèmes connus et les actions suivantes.++## Un journal pour l'artisan amnésique++Approche fondamentale : **Traitez l'agent comme un brillant ingénieur atteint d'amnésie.** Avant qu'il ne « termine sa journée », il doit noter les informations critiques pour que l'agent du « poste » suivant puisse prendre le relais rapidement.++**Outil 1 : Fichier de progression (PROGRESS.md).** L'artefact de continuité le plus basique — le cœur du journal :++```markdown+# Project Progress++## Current State+- Latest commit: abc1234 (feat: add user preferences endpoint)+- Test status: 42/43 passing (test_pagination_edge_case failing)+- Lint: passing++## Completed+- [x] User model and database migration+- [x] Basic CRUD endpoints+- [x] Auth middleware integration++## In Progress+- [ ] Pagination feature (90% - edge case test failing)++## Known Issues+- test_pagination_edge_case returns 500 on empty result sets+- Need to confirm whether deleted users should appear in listings++## Next Steps+1. Fix pagination edge case bug+2. Add "include deleted users" query parameter+3. Update API documentation+```++**Outil 2 : Journal des décisions (DECISIONS.md).** Enregistrez les décisions de conception importantes et leurs raisons. Pas besoin de documents de conception détaillés — juste « quelle décision, pourquoi, quand » — les mémos du journal :++```markdown+# Design Decisions++## 2024-01-15: Use Redis for user preferences caching+- Reason: High read frequency (every API call), small data size+- Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile)+- Constraint: Cache TTL of 5 minutes, active invalidation on write+```++**Outil 3 : Commits git comme points de contrôle.** Commitez après avoir terminé chaque unité de travail atomique. Les messages de commit devraient expliquer ce qui a été fait et pourquoi. Ce sont des instantanés d'état gratuits et automatiquement versionnés.++**Outil 4 : init.sh ou flux d'initialisation du harness.** Spécifiez dans `AGENTS.md` les routines de « prise de poste » et de « fin de service » :++```markdown+## At session start (clock in)+1. Read PROGRESS.md for current state+2. Read DECISIONS.md for important decisions+3. Run make check to confirm repo is in consistent state+4. Continue from PROGRESS.md "Next Steps" section++## Before session end (clock out)+1. Update PROGRESS.md+2. Run make check to confirm consistent state+3. Commit all completed work+```++**Stratégie mixte** : Toutes les tâches n'ont pas besoin d'une réinitialisation de contexte. Les tâches courtes (moins de 30 minutes) peuvent se terminer en une seule session. Les tâches longues (s'étalant sur plusieurs sessions) doivent utiliser des fichiers de progression et des journaux de décisions pour la continuité. Critère de décision : si une tâche nécessite plus de 60 % de la fenêtre, commencez à préparer la passation.++### Plongée approfondie sur l'anxiété de contexte++La recherche de mars 2026 d'Anthropic a révélé plus en détail les manifestations spécifiques de l'anxiété de contexte : sur Sonnet 4.5, lorsque le contexte approche de la limite de la fenêtre, l'agent montre un fort comportement de « convergence prématurée ». C'est comme réaliser que le temps est presque écoulé à un examen et remplir rapidement des réponses au hasard.++Deux stratégies y remédient :++**Compaction** : Résumer la conversation antérieure au sein de la même session. Avantage : maintient la continuité, l'agent peut voir le « quoi ». Inconvénient : le « pourquoi » est souvent perdu dans les résumés — pourquoi l'option B a été choisie plutôt que A, pourquoi une optimisation particulière a été écartée. Plus critiques encore, la compaction n'élimine pas l'anxiété de contexte — l'agent sait que le contexte a déjà été volumineux, et psychologiquement a toujours tendance à se précipiter vers la clôture.++**Réinitialisation de contexte** : Effacement complet du contexte, ouverture d'une nouvelle session, reconstruction à partir des artefacts persistés. Avantage : état mental propre — la nouvelle session n'a pas d'anxiété de « je manque de temps ». Inconvénient : dépend de l'exhaustivité des artefacts de passation. Si le journal manque d'informations critiques, la nouvelle session peut perdre du temps dans une mauvaise direction.++Les données réelles d'Anthropic : pour Sonnet 4.5, l'anxiété de contexte est suffisamment sévère pour que la compaction seule ne suffise pas — la réinitialisation de contexte devient un composant critique de la conception du harness. Mais pour Opus 4.5, ce comportement est grandement réduit, et la compaction peut gérer le contexte sans recourir aux réinitialisations. Cela signifie : **la conception du harness nécessite une compréhension spécifique du modèle cible, pas un modèle universel unique.**++> Source : [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## Exemple concret++Un agent a été chargé d'implémenter un système de blog avec authentification utilisateur — 12 points de fonctionnalité, estimation de 5 sessions nécessaires.++**Baseline sans le journal** : La session 1 a implémenté le modèle utilisateur et les routes de base. La session 2 a démarré sans que l'agent se souvienne du contrat d'interface du middleware d'authentification, passant ~15 minutes à déduire l'intention de conception précédente. Dès la session 3, la dérive accumulée a poussé l'agent à réimplémenter des fonctionnalités déjà complétées. À la session 5, le repo contenait beaucoup de code redondant mais la fonctionnalité d'authentification principale n'avait toujours pas passé les tests de bout en bout. Seulement 7 des 12 points de fonctionnalité complétés, dont 3 avec des problèmes de correction cachés. Comme l'artisan qui n'écrit jamais dans son journal — au cinquième jour, le chantier est chaotique, certains murs construits deux fois, d'autres qui auraient dû l'être ne sont même pas commencés.++**Avec le journal** : Utilisation de fichiers de progression, journaux de décisions, enregistrements de vérification et points de contrôle git. Le rapport d'état mis à jour automatiquement à la fin de chaque session. Le coût de reconstruction de la session 2 est tombé à ~3 minutes. À la session 5, les 12 points de fonctionnalité étaient complétés et vérifiés.++Comparaison quantitative : temps de reconstruction réduit de ~78 %, taux de complétion des fonctionnalités de 58 % à 100 %, taux de défauts cachés de 43 % à 8 %. L'artisan est toujours amnésique, mais avec le journal, chaque jour commence là où celui d'hier s'est arrêté, pas à zéro.++## Points clés++- Les fenêtres de contexte sont une ressource finie. Les tâches longues s'étaleront sur plusieurs sessions, et les sessions perdront de l'information — comme l'artisan qui oublie chaque jour, c'est une réalité objective.+- La solution n'est pas des fenêtres plus grandes — c'est une meilleure persistance de l'état. Fichiers de progression + journaux de décisions + points de contrôle git — donnez à l'artisan amnésique un journal fiable.+- Traitez l'agent comme un ingénieur atteint d'amnésie : avant de « terminer sa journée », notez ce qui a été fait, pourquoi, et ce qui reste à faire.+- Le coût de reconstruction est la métrique clé. Les bons harness devraient amener les nouvelles sessions à un état exécutable en moins de 3 minutes.+- Stratégie mixte : tâches courtes en session, tâches longues avec des artefacts structurés pour la continuité.++## Pour aller plus loin++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [Claude Code Documentation](https://docs.anthropic.com/fr/docs/claude-code)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)++## Exercices++1. **Mesure de la perte de continuité** : Choisissez une tâche de développement nécessitant au moins 3 sessions. Sans fournir aucun artefact de continuité, enregistrez au début de chaque session combien de contexte l'agent dépense à « comprendre ce qui s'est passé la dernière fois ». Après chaque session, créez un fichier de progression et laissez la session suivante démarrer à partir de celui-ci. Comparez les coûts de reconstruction avec et sans fichiers de progression.++2. **Conception d'un modèle de passation** : Concevez un modèle de passation minimal avec quatre champs : état du repo (hash de commit), état d'exécution (taux de réussite des tests), bloqueurs, actions suivantes. Laissez une toute nouvelle session d'agent restaurer l'état du projet en utilisant uniquement ce modèle. Enregistrez les ambiguïtés rencontrées lors de la restauration, itérez pour améliorer le modèle.++3. **Expérience de stratégie mixte** : Dans une tâche de développement en 5 sessions, comparez trois stratégies : (a) toujours démarrer de nouvelles sessions + fichiers de progression, (b) faire le maximum possible en une seule session (compaction de contexte), (c) stratégie mixte (tâches courtes en session, tâches longues sur plusieurs sessions + fichiers de progression). Comparez le temps de reconstruction, le taux de complétion des fonctionnalités et la cohérence des décisions.diff --git a/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdnew file mode 100644index 0000000..3721f55--- /dev/null+++ b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 06++Utilisez ce dossier pour des exemples de :++- sorties de l'initialiseur+- scripts d'initialisation+- fichiers de progression+- échafaudage de première exécutiondiff --git a/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.tsnew file mode 100644index 0000000..52dcd98--- /dev/null+++ b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts@@ -0,0 +1,296 @@+/**+ * init-check.ts+ *+ * Programmatically checks initialization prerequisites:+ * - Node.js version+ * - Dependencies installed (node_modules exists)+ * - Data directory exists+ * - Config files present+ *+ * Simulates running with and without an explicit init phase,+ * showing how missing prerequisites cause silent failures later.+ *+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";+import * as childProcess from "node:child_process";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface CheckItem {+ name: string;+ category: string;+ check: () => { pass: boolean; detail: string };+ impactIfMissing: string;+}++interface CheckResult {+ name: string;+ category: string;+ passed: boolean;+ detail: string;+ impactIfMissing: string;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++function createChecks(targetDir: string): CheckItem[] {+ return [+ {+ name: "Node.js version >= 18",+ category: "Runtime",+ check: () => {+ try {+ const version = process.version; // e.g. "v20.11.0"+ const major = parseInt(version.replace("v", "").split(".")[0], 10);+ return {+ pass: major >= 18,+ detail: `Detected: ${version} (need >= v18)`,+ };+ } catch {+ return { pass: false, detail: "Could not detect Node.js version" };+ }+ },+ impactIfMissing: "TypeScript features and built-in APIs unavailable",+ },+ {+ name: "package.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "package.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found in target directory",+ };+ },+ impactIfMissing: "Cannot install dependencies or run scripts",+ },+ {+ name: "Dependencies installed (node_modules)",+ category: "Dependencies",+ check: () => {+ const p = path.join(targetDir, "node_modules");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",+ };+ },+ impactIfMissing: "All imports fail at runtime",+ },+ {+ name: "TypeScript available",+ category: "Toolchain",+ check: () => {+ try {+ const result = childProcess.execSync("npx tsc --version", {+ encoding: "utf-8",+ timeout: 10000,+ stdio: ["pipe", "pipe", "pipe"],+ }).trim();+ return { pass: true, detail: `Detected: ${result}` };+ } catch {+ return { pass: false, detail: "TypeScript not available via npx" };+ }+ },+ impactIfMissing: "Cannot compile TypeScript files",+ },+ {+ name: "tsconfig.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "tsconfig.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found",+ };+ },+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",+ },+ {+ name: "Source directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["src", "lib", "app"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",+ };+ },+ impactIfMissing: "Agent cannot locate source files to modify",+ },+ {+ name: "Test directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["test", "tests", "__tests__", "spec"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",+ };+ },+ impactIfMissing: "Agent cannot find or run existing tests",+ },+ {+ name: "Git repository initialized",+ category: "Version Control",+ check: () => {+ const gitDir = path.join(targetDir, ".git");+ const exists = fs.existsSync(gitDir);+ return {+ pass: exists,+ detail: exists ? "Git repository detected" : "No .git directory found",+ };+ },+ impactIfMissing: "No rollback capability, no change history",+ },+ ];+}++// ---------------------------------------------------------------------------+// Simulation: with and without init phase+// ---------------------------------------------------------------------------++interface SimResult {+ scenario: string;+ checksRun: boolean;+ failuresBeforeWork: number;+ workAttempted: boolean;+ workSucceeded: boolean;+ timeWastedMs: number;+}++function simulateWithoutInit(): SimResult {+ // Agent skips init, goes straight to work.+ // Encounters failures one at a time as it hits missing prerequisites.+ const checks = createChecks(process.cwd());+ let failures = 0;+ let timeWasted = 0;++ for (const check of checks) {+ const result = check.check();+ if (!result.pass) {+ failures++;+ timeWasted += 200; // Agent spends time discovering each missing piece+ }+ }++ return {+ scenario: "NO INIT PHASE",+ checksRun: false,+ failuresBeforeWork: 0, // Didn't check upfront+ workAttempted: true,+ workSucceeded: failures === 0,+ timeWastedMs: timeWasted,+ };+}++function simulateWithInit(): SimResult {+ // Agent runs init phase first, discovers all issues upfront.+ const checks = createChecks(process.cwd());+ let failures = 0;++ for (const check of checks) {+ if (!check.check().pass) {+ failures++;+ }+ }++ return {+ scenario: "WITH INIT PHASE",+ checksRun: true,+ failuresBeforeWork: failures,+ workAttempted: failures === 0,+ workSucceeded: failures === 0,+ timeWastedMs: 0,+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.cwd();+ console.log("\n" + "=".repeat(80));+ console.log(" INITIALIZATION PREREQUISITE CHECK");+ console.log("=".repeat(80));+ console.log(` Target: ${targetDir}\n`);++ const checks = createChecks(targetDir);+ const results: CheckResult[] = checks.map((c) => {+ const r = c.check();+ return {+ name: c.name,+ category: c.category,+ passed: r.pass,+ detail: r.detail,+ impactIfMissing: c.impactIfMissing,+ };+ });++ // Detailed report+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const status = r.passed ? "PASS" : "FAIL";+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);+ }++ const passCount = results.filter((r) => r.passed).length;+ const failCount = results.filter((r) => !r.passed).length;++ console.log("\n" + "-".repeat(80));+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);++ if (failCount > 0) {+ console.log("\n FAILED CHECKS -- Impact if not resolved:");+ for (const r of results.filter((r) => !r.passed)) {+ console.log(` - ${r.name}: ${r.impactIfMissing}`);+ }+ }++ // Comparison: with vs without init+ const noInit = simulateWithoutInit();+ const withInit = simulateWithInit();++ console.log("\n" + "=".repeat(80));+ console.log(" INIT PHASE COMPARISON");+ console.log("=".repeat(80) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);++ console.log("\n An explicit init phase catches problems before they waste time.\n");+}++run();diff --git a/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.shnew file mode 100644index 0000000..2c6e1b0--- /dev/null+++ b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh@@ -0,0 +1,10 @@+#!/usr/bin/env bash+set -euo pipefail++echo "[init] installing dependencies"+npm install++echo "[init] starting the docs site is optional"+echo "[init] use npm run docs:dev for course docs"++echo "[init] project-specific startup would go here"diff --git a/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.mdnew file mode 100644index 0000000..82d4a3b--- /dev/null+++ b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md@@ -0,0 +1,7 @@+# Liste de Contrôle des Sorties de l'Initialiseur++- Y a-t-il une commande de démarrage canonique ?+- Y a-t-il une commande de vérification canonique ?+- Y a-t-il un premier artefact de progression ?+- Y a-t-il un premier commit stable ?+- Y a-t-il une surface de fonctionnalité visible pour les sessions ultérieures ?diff --git a/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdnew file mode 100644index 0000000..2a26a70--- /dev/null+++ b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -0,0 +1,157 @@+[中文版本 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)+> Projet pratique : [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# Leçon 06. Initialiser avant chaque session d'agent++Vous démarrez une nouvelle session d'agent et dites « ajoute une fonctionnalité de recherche ». Il se lance directement dans le code — un bel enthousiasme. Après 20 minutes, il découvre que le framework de test n'est pas correctement configuré, passe encore 10 minutes à le corriger, puis le format du script de migration de base de données est incorrect, encore des ajustements. La fonctionnalité de recherche finit par être ajoutée, mais toute la session a été inefficace — la majeure partie du temps a été consacrée à « comprendre comment fonctionne ce projet » plutôt qu'à écrire la fonctionnalité de recherche.++La meilleure approche : avant de laisser l'agent commencer à travailler, utiliser une phase séparée pour préparer l'environnement de base, faire passer les commandes de vérification, et faire comprendre la structure du projet. C'est comme construire une maison — vous ne coulez pas les fondations et n'érigez pas les murs simultanément. Si vous le faites, les murs montent avant que les fondations n'aient séché, et tout le bâtiment doit être démoli et recommencé. Coulez d'abord les fondations, laissez-les sécher, puis construisez les murs — propre et efficace.++Cette leçon explique pourquoi l'initialisation doit être une phase séparée, pas mélangée avec l'implémentation.++## Fondations et murs : deux travaux fondamentalement différents++L'initialisation et l'implémentation ont des cibles d'optimisation complètement différentes. La phase d'implémentation optimise pour : maximiser la quantité et la qualité des fonctionnalités vérifiées. La phase d'initialisation optimise pour : maximiser la fiabilité et l'efficacité de toutes les implémentations ultérieures.++Quand vous mélangez initialisation et implémentation, l'agent fait face à un problème d'optimisation multi-objectifs — construire simultanément l'infrastructure et écrire du code de fonctionnalité. Sans priorité explicite, l'agent se tourne naturellement vers l'écriture de code (parce que c'est une sortie directement visible) au détriment de l'infrastructure (parce que sa valeur ne se manifeste que dans les sessions suivantes). C'est comme demander à une équipe de construction de couler simultanément les fondations et de monter les murs — ils vont probablement se précipiter pour construire les murs parce que les murs sont visibles et démontrables. Mais une maison avec de mauvaises fondations aura des problèmes systémiques par la suite.++## Cycle de vie de l'initialisation++```mermaid+flowchart TB+ subgraph Wrong["Mixed session (wrong)"]+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]+ W2 --> W3["Accumulate unverified code"]+ W3 --> W4["Next session must rediscover project state"]+ end++ subgraph Right["Dedicated initialization (right)"]+ R1["Session 1: environment runnable"] --> R2["Example test passing"]+ R2 --> R3["Bootstrap contract + task list written"]+ R3 --> R4["Clean checkpoint committed"]+ R4 --> R5["Later sessions start directly on verified tasks"]+ end+```++## Ce qui se passe quand on les mélange++Le problème le plus direct : les fondations ne sèchent pas correctement. L'agent passe 80 % de ses efforts sur le code de fonctionnalité et 20 % à configurer vaguement de l'infrastructure. Le framework de test est configuré mais jamais vérifié, les règles lint sont définies mais trop laxistes, aucun fichier de progression créé. Ces défauts ne sont pas évidents lors de la première session (parce que l'agent se souvient encore de ce qu'il a fait), mais ils surgissent lors de la deuxième session — le nouvel agent ne sait pas comment lancer, tester, ou où en sont les choses. Fondations bâclées, bâtiment instable.++Un coût plus caché est l'« accumulation non vérifiée » — le code de fonctionnalité écrit avant que le framework de test ne soit configuré est du code sans vérification. Quand vous revenez enfin pour ajouter des tests à ce code, vous pourriez découvrir que la conception était fausse dès le départ — si vous l'aviez su, vous l'auriez implémenté différemment. Comme carreler sur du béton encore humide — quand vous découvrez que le sol n'est pas de niveau, toutes les tuiles doivent être arrachées et refaites.++Le budget de session est également gaspillé. Le travail d'initialisation (configurer les environnements, mettre en place les tests, comprendre la structure du projet) consomme un budget significatif, laissant moins pour l'implémentation réelle des fonctionnalités. Résultat : la première session ne complète que la moitié des fonctionnalités, et la deuxième session doit recommencer à comprendre le projet. Budget dépensé pour les fondations, mais les fondations ne sont pas solides non plus — aucun objectif atteint.++Le problème le plus facilement négligé est celui des mines d'hypothèses implicites. Les décisions que l'agent prend pendant l'initialisation (quel framework de test, comment organiser les répertoires, gestion des dépendances) — si elles ne sont pas explicitement enregistrées, les sessions suivantes ne peuvent pas comprendre ces choix. Pire, les sessions suivantes pourraient prendre des décisions contradictoires. La première équipe de construction a utilisé des fondations en béton, la deuxième ne le sait pas et y a enfoncé des pilotis en bois — les fondations se fissurent.++La recherche d'Anthropic sur le développement d'applications longue durée recommande explicitement de séparer l'initialisation de l'implémentation. Leurs données expérimentales : les projets utilisant une phase d'initialisation dédiée ont montré des taux de complétion de fonctionnalités 31 % plus élevés dans les scénarios multi-sessions par rapport aux approches mixtes. L'insight clé — le temps investi dans la phase d'initialisation est entièrement récupéré dans les 3-4 sessions suivantes. Plus les fondations sont solides, plus vite les murs montent.++Le guide de harness engineering d'OpenAI Codex souligne également le principe du « dépôt comme registre opérationnel » — établir une structure opérationnelle claire dès la première exécution, ou chaque nouvelle session doit ré-inférer les conventions du projet.++## Concepts clés++- **Phase d'initialisation** : La première phase du cycle de vie de l'agent — pas d'implémentation de fonctionnalité, seulement l'établissement des prérequis pour toutes les phases d'implémentation suivantes. La sortie n'est pas du code, c'est de l'infrastructure.+- **Contrat d'amorçage (Bootstrap Contract)** : Les conditions dans lesquelles un projet peut être exploité sans ambiguïté par une nouvelle session d'agent — peut démarrer, peut tester, peut voir la progression, peut reprendre les étapes suivantes. Quatre conditions, toutes obligatoires.+- **Démarrage à froid vs démarrage à chaud** : Le démarrage à froid part d'un répertoire vide où l'agent doit deviner la structure du projet ; le démarrage à chaud part d'un modèle ou d'un projet existant où l'infrastructure est déjà en place. Le démarrage à chaud surpasse largement le démarrage à froid — comme commencer à travailler sur un chantier avec eau courante et électricité versus partir d'un terrain nu.+- **Préparation à la passation (Handoff Readiness)** : Le projet est dans un état où, à tout moment, un agent neuf peut prendre le relais. Pas d'explication verbale nécessaire — seulement le contenu du repo.+- **Temps jusqu'à la première vérification (Time to First Verification)** : Le temps entre le début du projet et le moment où le premier point de fonctionnalité passe la vérification. C'est la métrique clé pour mesurer l'efficacité de l'initialisation.+- **Utilisabilité en aval** : La meilleure mesure de la qualité de l'initialisation — la proportion de sessions suivantes qui peuvent exécuter des tâches avec succès sans s'appuyer sur des connaissances implicites.++## Comment bien faire l'initialisation++**Traitez l'initialisation comme une phase dédiée.** La première session ne fait que de l'initialisation — aucun code de fonctionnalité métier. L'initialisation produit :++**1. Environnement exécutable.** Le projet démarre, les dépendances sont installées, aucun problème d'environnement. Fondations coulées, sans fissures.++**2. Framework de test vérifiable.** Au moins un test exemple passe. Cela prouve que le framework de test lui-même est correctement configuré — comme dresser un pilier sur les fondations pour prouver qu'il peut supporter du poids.++**3. Document de contrat d'amorçage.** Un document clair indiquant aux sessions suivantes :+```markdown+# Initialization Contract++## Start Commands+- Install dependencies: `make setup`+- Start dev server: `make dev`+- Run tests: `make test`+- Full verification: `make check`++## Current State+- All dependencies installed and locked+- Test framework configured (Vitest + React Testing Library)+- Example test passing (1/1)+- Lint rules configured (ESLint + Prettier)++## Project Structure+- src/ — Source code+- src/components/ — React components+- src/api/ — API client+- tests/ — Test files+```++**4. Découpage des tâches.** Divisez tout le projet en une liste ordonnée de tâches, chacune avec des critères d'acceptation clairs :+```markdown+# Task Breakdown++## Task 1: User Authentication Basics+- Implement JWT auth middleware+- Add login/register endpoints+- Acceptance: pytest tests/test_auth.py all passing++## Task 2: User Profile Page+- Implement user profile CRUD+- Add profile edit form+- Acceptance: pytest tests/test_profile.py all passing++## Task 3: Search Feature+- ...+```++**5. Commit git comme point de contrôle.** Après la complétion de l'initialisation, commitez un point de contrôle propre. Tout le travail ultérieur part de ce point de contrôle.++**Stratégie de démarrage à chaud** : Ne partez pas d'un répertoire vide. Utilisez un modèle de projet (create-react-app, fastapi-template, etc.) pour prérégler la structure de répertoires standard, la configuration des dépendances et le framework de test. Intégrez les étapes d'initialisation courantes dans le modèle, ne laissant que le travail d'initialisation spécifique au projet. Comme commencer à travailler sur un chantier avec eau courante et électricité — mille fois mieux que de partir d'un terrain nu.++**Critères de complétion de l'initialisation** : Pas « combien de code a été écrit », mais si les quatre conditions du contrat d'amorçage sont remplies — peut démarrer, peut tester, peut voir la progression, peut reprendre les étapes suivantes. Utilisez cette liste de contrôle pour valider l'initialisation :++```markdown+## Initialization Acceptance Checklist+- [ ] `make setup` succeeds from scratch+- [ ] `make test` has at least one passing test+- [ ] A new agent session can answer "how to run" and "how to test" from repo contents alone+- [ ] Task breakdown file exists with at least 3 tasks+- [ ] Everything committed to git+```++## Exemple concret++Deux approches d'initialisation pour un projet frontend React :++**Approche mixte (couler les fondations et monter les murs simultanément)** : L'agent a simultanément créé l'échafaudage du projet et implémenté la première fonctionnalité lors de la session 1. À la fin de la session, le repo avait du code exécutable mais : pas de documentation explicite des commandes start/test, pas de fichier de suivi de progression, pas de découpage des tâches. La session 2 a passé ~20 minutes à déduire la structure du projet, le framework de test et le processus de build — comme une nouvelle équipe de construction arrivant sur un chantier, ne sachant pas où en sont les fondations ni où passent les canalisations, devant creuser des trous un par un pour le découvrir.++**Initialisation dédiée (fondations d'abord)** : La session 1 n'a fait que de l'initialisation — créé la structure de répertoires à partir d'un modèle, configuré le framework de test (Vitest + React Testing Library), écrit et vérifié un test exemple, créé le document de contrat d'amorçage et le fichier de découpage des tâches, committé le point de contrôle initial. Le temps de reconstruction de la session 2 était inférieur à 3 minutes, et elle a commencé à travailler directement à partir de la liste de tâches — l'équipe arrive, jette un coup d'oeil au plan, et sait exactement où reprendre.++Comparaison sur le cycle complet du projet : le temps de reconstruction total de l'approche mixte (sur toutes les sessions) était ~60 % supérieur à celui de l'approche d'initialisation dédiée. Les 20 minutes supplémentaires passées à l'initialisation ont été récupérées plusieurs fois lors des sessions suivantes. Comme des fondations solides qui font monter les murs plus vite — lent c'est vite.++## Points clés++- L'initialisation et l'implémentation ont des cibles d'optimisation différentes — les mélanger tire les deux vers le bas. Coulez d'abord les fondations, puis construisez les murs.+- La sortie de l'initialisation n'est pas du code, c'est de l'infrastructure : environnement exécutable, tests vérifiables, contrat d'amorçage, découpage des tâches.+- Validez l'initialisation avec les quatre conditions du contrat d'amorçage : peut démarrer, peut tester, peut voir la progression, peut reprendre les étapes suivantes.+- Le démarrage à chaud bat le démarrage à froid. Utilisez des modèles de projet pour prérégler l'infrastructure standardisée.+- Le temps investi dans l'initialisation est entièrement récupéré dans les 3-4 sessions suivantes. Ce n'est pas un coût supplémentaire — c'est un investissement initial. Plus les fondations sont solides, plus vite le bâtiment monte.++## Pour aller plus loin++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)++## Exercices++1. **Conception du contrat d'amorçage** : Écrivez un contrat d'amorçage complet pour un projet que vous développez. Ouvrez ensuite une toute nouvelle session d'agent, montrez-lui uniquement le contenu du repo (aucun contexte verbal), et demandez-lui d'essayer de lancer le projet, d'exécuter les tests et de comprendre la progression actuelle. Enregistrez chaque problème rencontré — chacun correspond à une clause manquante dans votre contrat d'amorçage.++2. **Expérience comparative** : Choisissez un nouveau projet de complexité modérée. Approche A : laissez l'agent initialiser et faire la première implémentation simultanément. Approche B : consacrez une session à l'initialisation dédiée, commencez l'implémentation en session 2. Après 4 sessions, comparez : le temps jusqu'à la première vérification, le coût de reconstruction, le taux de complétion des fonctionnalités.++3. **Liste de contrôle d'acceptation de l'initialisation** : Concevez une liste de contrôle d'acceptation de l'initialisation pour votre projet. Demandez à une nouvelle session d'agent d'exécuter chaque élément de la liste de contrôle et d'enregistrer lesquels passent et lesquels échouent. Les éléments qui échouent indiquent les points où votre harness a besoin d'être renforcé.diff --git a/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdnew file mode 100644index 0000000..0b27ef4--- /dev/null+++ b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 07++Utilisez ce dossier pour des exemples de :++- échecs en un seul essai+- prompts de tâches surdimensionnés+- formation incrémentale des tâches+- surfaces de fonctionnalités structuréesdiff --git a/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.mdnew file mode 100644index 0000000..6587a27--- /dev/null+++ b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md@@ -0,0 +1,6 @@+# Modèle de Prochaine Tâche++- Fonctionnalité actuelle de plus haute priorité :+- Pourquoi cette fonctionnalité est la prochaine :+- Ce qui compte comme réussi :+- Ce qui ne doit pas être modifié pendant cette étape :diff --git a/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdnew file mode 100644index 0000000..ffb16d6--- /dev/null+++ b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -0,0 +1,17 @@+# Exemple de Surface de Portée++Tâche :++- Ajouter l'indexation à l'application de connaissance Electron++Mauvaise forme de portée :++- "Implémenter l'indexation"++Meilleure forme de portée :++- Analyser les documents importés+- Diviser les documents en morceaux+- Persister les métadonnées des morceaux+- Afficher le statut d'indexation dans l'UI+- Ajouter une action de réindexationdiff --git a/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.tsnew file mode 100644index 0000000..c587a1d--- /dev/null+++ b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts@@ -0,0 +1,151 @@+/**+ * scope-tracker.ts+ *+ * Reads a feature list and a change log. Enforces single-active-feature+ * policy. Given a log of changes, flags any changes outside the active+ * feature scope. Demonstrates how scope drift happens and how the tracker+ * catches it.+ *+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Feature {+ id: string;+ name: string;+ status: "active" | "pending" | "done";+}++interface ChangeLogEntry {+ step: number;+ file: string;+ description: string;+ featureId: string; // The feature this change claims to belong to+}++// ---------------------------------------------------------------------------+// Sample data+// ---------------------------------------------------------------------------++const features: Feature[] = [+ { id: "F-001", name: "Search endpoint", status: "active" },+ { id: "F-002", name: "Delete endpoint", status: "pending" },+ { id: "F-003", name: "Rate limiting", status: "pending" },+ { id: "F-004", name: "User dashboard", status: "pending" },+];++// A realistic change log where the agent gradually drifts from the active feature+const changeLog: ChangeLogEntry[] = [+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },+];++// ---------------------------------------------------------------------------+// Scope tracker+// ---------------------------------------------------------------------------++interface ScopeCheckResult {+ step: number;+ file: string;+ description: string;+ featureId: string;+ inScope: boolean;+ activeFeature: string;+}++function trackScope(+ featureList: Feature[],+ changes: ChangeLogEntry[]+): ScopeCheckResult[] {+ const activeFeatures = featureList.filter((f) => f.status === "active");+ const activeIds = new Set(activeFeatures.map((f) => f.id));+ const activeNames = activeFeatures.map((f) => f.name).join(", ");++ return changes.map((change) => ({+ step: change.step,+ file: change.file,+ description: change.description,+ featureId: change.featureId,+ inScope: activeIds.has(change.featureId),+ activeFeature: activeNames,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const results = trackScope(features, changeLog);++ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");+ console.log("=".repeat(100));++ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));++ // Detailed change log+ console.log("\n" + "-".repeat(100));+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;+ console.log(header);+ console.log(sep);++ let inScopeCount = 0;+ let driftCount = 0;++ for (const r of results) {+ const scopeLabel = r.inScope ? "OK" : "DRIFT";+ if (r.inScope) inScopeCount++;+ else driftCount++;++ const marker = r.inScope ? " " : ">>";+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE DRIFT SUMMARY");+ console.log("=".repeat(100) + "\n");++ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;+ console.log(sHeader);+ console.log(sSep);+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);++ // Drift detail+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];+ if (driftFeatures.length > 0) {+ console.log("\n DRIFTED FEATURES:");+ for (const fid of driftFeatures) {+ const feat = features.find((f) => f.id === fid);+ const driftChanges = results.filter((r) => r.featureId === fid);+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);+ }+ }++ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");+}++run();diff --git a/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdnew file mode 100644index 0000000..3653893--- /dev/null+++ b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -0,0 +1,134 @@+[中文版本 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)+> Projet pratique : [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)++# Leçon 07. Définir des limites de tâche claires++Vous demandez à Claude Code d'« ajouter l'authentification utilisateur à ce projet », et il commence à modifier le schéma de base de données, à écrire des routes, à changer des composants frontend, et — tant qu'à faire — à refactorer le middleware de gestion d'erreurs. Deux heures plus tard, vous vérifiez : 12 fichiers modifiés, 800 lignes de nouveau code, et pas une seule fonctionnalité qui fonctionne de bout en bout.++Mordre plus qu'on ne peut mâcher — ce dicton s'applique particulièrement bien aux agents IA. Les agents ont un instinct inné pour « faire un peu plus » — ils voient des choses liées et les traitent au passage, comme quelqu'un qui va au supermarché pour une bouteille de sauce soja et ressort en poussant un caddy plein. Le problème, c'est que les humains qui achètent trop gaspillent juste de l'argent ; les agents qui font trop de choses simultanément n'en terminent aucune correctement.++Le blog d'ingénierie d'Anthropic « Effective harnesses for long-running agents » le dit clairement : quand les prompts sont trop larges, les agents ont tendance à « commencer plusieurs choses à la fois » plutôt qu'à « terminer une chose d'abord ». Les pratiques d'ingénierie Codex d'OpenAI ont constaté la même chose — les tâches sans contrôles de portée explicites voient leurs taux de complétion chuter. Ce n'est pas un problème de modèle — c'est un problème de harness. Vous n'avez pas tracé la limite.++## L'attention est une ressource finie++Ce n'est pas une métaphore — ce sont des mathématiques. Supposez que la capacité de contexte de l'agent est C et qu'il active k tâches simultanément. Chaque tâche reçoit en moyenne C/k ressources de raisonnement. Quand C/k descend en dessous du seuil minimum nécessaire pour terminer une seule tâche, aucune n'est achevée. Votre estomac n'est que d'une certaine taille — enfoncez dix raviolis d'un coup et vous ne les digérerez pas tous, vous aurez juste dix cas d'indigestion.++Le comportement réel de Claude Code est révélateur. Demandez-lui d'« ajouter l'inscription utilisateur » et il pourrait :++1. Créer un modèle User+2. Écrire la route d'inscription+3. Remarquer qu'il a besoin de vérification email, donc ajouter un service mail+4. Voir que les mots de passe doivent être hachés, donc intégrer bcrypt+5. Remarquer que la gestion des erreurs est incohérente, donc refactorer le middleware d'erreurs global+6. Voir que la structure des fichiers de test est désordonnée, donc réorganiser le répertoire++Six étapes plus tard, chacune est à moitié faite. Pas de vérification de bout en bout, couplage complexe entre le code à moitié cuit, et la session suivante qui devra ramasser les morceaux sera complètement perdue. Comme quelqu'un qui cuisine six plats simultanément — chaque plat est dans la poêle mais aucun n'est dressé. Ils brûlent tous.++Les données expérimentales d'Anthropic le confirment directement : les agents utilisant une stratégie de « petit pas suivant » (équivalent à WIP=1) affichent un taux de complétion de tâches 37 % plus élevé que les agents utilisant des prompts larges. Plus intéressant encore, le nombre de lignes de code générées par les agents est faiblement corrélé négativement avec la complétion réelle des fonctionnalités — plus de code écrit, moins de fonctionnalités complétées. Prendre plus qu'on ne peut mâcher, prouvé par les données.++## Flux de travail WIP=1++```mermaid+flowchart LR+ Queue["Feature queue"] --> Pick["Pick exactly one task"]+ Pick --> Active["Only one active item"]+ Active --> Verify["Run end-to-end verification"]+ Verify -->|pass| Commit["Commit and unlock next task"]+ Verify -->|fail| Active+ Commit --> Queue+```++```mermaid+flowchart TB+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]+ Budget --> Many["WIP = 5<br/>C / 5 per task"]++ One --> Finish["One feature reaches passing state"]+ Many --> Partial["Five partial implementations"]+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]+```++## Concepts clés++- **Surportée (Overreach)** : L'agent active plus de tâches en une seule session que ce qui est optimal. C'est quantifiable — faire 5 fonctionnalités avec 0 passage de bout en bout est une surportée.+- **Sous-achèvement (Under-finish)** : Le ratio de tâches passant la vérification de bout en bout, parmi toutes les tâches activées, tombe en dessous du seuil. Du code écrit mais des tests qui ne passent pas est du sous-achèvement.+- **Limite WIP (Work-in-Progress Limit)** : Issu de la méthodologie Kanban. Idée fondamentale : limiter le nombre de tâches en cours simultanément. Pour les agents, WIP=1 est le défaut le plus sûr — terminez-en un avant de commencer le suivant. Comme au buffet — n'empilez pas votre assiette, terminez-en une puis retournez en chercher une autre.+- **Preuve de complétion (Completion Evidence)** : La condition vérifiable qu'une tâche doit satisfaire pour passer de « en cours » à « terminée ». Sans cela, les agents substituent « le code a l'air correct » à « le comportement passe les tests ».+- **Surface de portée (Scope Surface)** : Une structure DAG où chaque nœud est une unité de travail et les arêtes sont des dépendances. Les états sont limités à quatre : not_started, active, blocked, passing.+- **Pression d'achèvement (Completion Pressure)** : La force contraignante que le harness exerce via les limites WIP et les exigences de preuve de complétion, forçant l'agent à terminer la tâche en cours avant d'en commencer une nouvelle.++## Surportée et sous-achèvement sont symbiotiques++Ces deux problèmes ne sont pas indépendants — ils s'amplifient mutuellement. La surportée dilue l'attention, l'attention diluée cause du sous-achèvement, et le code à moitié terminé qui en résulte augmente la complexité du système, ce qui alimente davantage la surportée dans la tâche suivante. Un cercle vicieux.++En termes Kanban : la loi de Little nous dit L = lambda * W. Si le travail en cours L est trop élevé (faire trop de choses à la fois), le temps de traitement W de chaque tâche augmente inévitablement. Pour les agents, cela signifie que chaque fonctionnalité prend plus de temps du début à la vérification finale, et la probabilité d'échec croît.++C'est aussi un vieux problème dans le monde humain — Steve McConnell a documenté dans *Rapid Development* que la dérive du périmètre est la principale cause d'échec de projet. Mais les humains ont au moins l'intuition d'en avoir fait assez. Les agents n'en ont aucune. Générer l'idée suivante ne coûte presque rien en tokens supplémentaires au modèle — écrire « laissez-moi aussi corriger ça tant que j'y suis » ne compte presque pas — mais chaque modification supplémentaire dilue l'attention de l'agent. Comme un buffet où chaque assiette supplémentaire a un coût marginal quasi nul, mais votre estomac n'a qu'une certaine capacité.++## Comment bien le faire++### 1. Imposer WIP=1++C'est la méthode la plus directe et la plus efficace. Dans votre harness, dites explicitement à l'agent : **une seule tâche est autorisée en statut « active » à tout moment.** Dans le CLAUDE.md de Claude Code ou l'AGENTS.md de Codex, écrivez :++```+## Work Rules+- Work on one feature at a time+- Only start the next feature after the current one passes end-to-end verification+- Don't "also refactor" feature B while implementing feature A+```++Comme manger au buffet — une assiette à la fois, terminez-la avant de retourner en chercher une autre.++### 2. Définir des preuves de complétion explicites pour chaque tâche++Terminé n'est pas « le code est écrit » — c'est « la vérification du comportement passe ». Dans votre feature list, chaque entrée a besoin d'une commande de vérification :++```+F01: User Registration+ Verification: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201+ State: passing+```++### 3. Externaliser la surface de portée++Utilisez un fichier lisible par machine (JSON ou Markdown) pour enregistrer tous les états des tâches. Toute nouvelle session peut lire ce fichier et savoir immédiatement : quelle tâche est active ? Quel comportement compte comme terminé ? Quelles vérifications ont passé ?++### 4. Surveiller le taux de complétion vérifié++Le harness devrait suivre en continu le VCR (Verified Completion Rate) = tâches vérifiées / tâches activées. Bloquer les activations de nouvelles tâches quand VCR < 1.0.++## Cas concret++Un projet d'API REST avec 8 fonctionnalités, deux stratégies comparées :++**Mode buffet (sans contrainte)** : L'agent active 5 fonctionnalités simultanément lors de la session 1. Produit ~800 lignes sur 12 fichiers. Taux de réussite des tests de bout en bout : 20 % — seule l'inscription utilisateur fonctionne. Les 4 autres fonctionnalités : schéma de base de données créé mais logique de validation manquante, routes définies mais retournant de mauvais formats de réponse. Comme quelqu'un qui cuisine six plats à la fois, un seul est à peine comestible. À la fin de la session 3, seulement 3 fonctionnalités sur 8 sont complétées.++**Mode assiette unique (WIP=1)** : L'agent ne travaille que sur l'inscription utilisateur lors de la session 1. Produit ~200 lignes sur 4 fichiers. Tests de bout en bout : 100 % de réussite. Commite une implémentation propre et vérifiée. À la fin de la session 4, 7 fonctionnalités sur 8 sont complétées (la 8e bloquée par une dépendance externe).++Résultat : moins de code total (800 vs 1200 lignes) mais du code plus efficace. Taux de complétion : 87,5 % vs 37,5 %. Prenez une bouchée à la fois, et vous mangez finalement plus.++## Points clés++- **WIP=1 est le réglage de sécurité par défaut pour les harness d'agents** — terminez-en un, puis commencez le suivant ; n'essayez pas de paralléliser. On ne devient pas gros en une bouchée.+- **La preuve de complétion doit être exécutable** — « le code a l'air correct » ne compte pas ; « curl retourne 201 » compte.+- **La surface de portée doit être externalisée dans un fichier** — pas juste mentionnée en conversation, mais enregistrée dans un format lisible par machine dans le repo.+- **La surportée et le sous-achèvement sont symbiotiques** — résoudre l'un résout l'autre.+- **« Faire moins mais terminer » bat toujours « faire plus mais laisser à moitié »** — les lignes de code de l'agent et le taux de complétion des fonctionnalités sont corrélés négativement. La qualité bat toujours la quantité.++## Pour aller plus loin++- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Blog d'ingénierie d'Anthropic, discussion détaillée de la stratégie « petit pas suivant »+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Traitement complet du harness engineering par OpenAI+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — La source classique sur les limites WIP+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — Données empiriques sur la dérive du périmètre comme cause principale d'échec de projet++## Exercices++1. **Atomisation des tâches** : Prenez une exigence large (par ex., « implémenter un système de gestion des utilisateurs ») et décomposez-la en au moins 5 unités de travail atomiques. Pour chaque unité, spécifiez : (a) une description de comportement unique, (b) une commande de vérification exécutable, (c) les dépendances. Vérifiez si la décomposition satisfait la contrainte WIP=1.++2. **Expérience comparative** : Exécutez le même projet deux fois — une fois sans contraintes, une fois avec WIP=1 imposé. Comparez : le taux de complétion vérifié, le nombre total de lignes de code, le ratio de code effectif.++3. **Audit des preuves de complétion** : Examinez la sortie d'une exécution récente d'agent, en classant chaque modification de code comme « comportement complété », « comportement incomplet » ou « échafaudage ». Ajoutez les commandes de vérification manquantes pour chaque comportement incomplet.diff --git a/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..52d6a2b--- /dev/null+++ b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,218 @@+/**+ * feature-list-validator.ts+ *+ * Reads a feature_list.json, validates its schema, and checks for features+ * marked "pass" without verification evidence. Outputs a structured report.+ * Can run against any project directory that has a feature_list.json.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]+ * (defaults to the directory containing this script)+ *+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Allow unknown fields for flexibility+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Schema validation+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entry ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Missing or invalid 'id' field`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Missing or invalid 'category' field`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Missing or invalid 'description' field`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' must be an array if present`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' must be a boolean if present`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Evidence validation+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Process feature list+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve target directory+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);+ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" FEATURE LIST VALIDATOR");+ console.log("=".repeat(90));+ console.log(` Reading: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(` ERROR: feature_list.json not found at ${filePath}`);+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");+ process.exit(1);+ }++ let entries: FeatureEntry[];+ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");+ process.exit(1);+ }++ // For demo purposes, also validate an extended test set+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "User can import a PDF document.",+ verification: ["Upload a PDF file", "Verify it appears in the document list"],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "System hallucination rate is below 5%.",+ verification: [], // Empty -- no evidence+ passes: true, // Marked as pass WITHOUT evidence+ },+ {+ id: "missing-fields",+ // Missing 'category' and 'description'+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Print report+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";+ const notes = r.markedPassWithoutEvidence+ ? "FLAGGED: passes without evidence!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";+ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`+ );+ }++ // Summary+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;+ const withEvidence = results.filter((r) => r.hasVerification).length;++ console.log("\n" + "-".repeat(90));+ console.log(" SUMMARY");+ console.log("-".repeat(90));+ console.log(` Total features: ${total}`);+ console.log(` Schema valid: ${schemaOk}/${total}`);+ console.log(` Marked as passing: ${passing}/${total}`);+ console.log(` With verification evidence: ${withEvidence}/${total}`);+ console.log(` Flagged (pass without evidence): ${flagged}`);++ if (flagged > 0) {+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);+ console.log(" These features need verification before they can be trusted.\n");+ } else {+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");+ }+}++run();diff --git a/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..8b973e3--- /dev/null+++ b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",+ "verification": [+ "Import a markdown document",+ "Open the Q&A panel",+ "Ask a question about known content",+ "Verify the answer is returned",+ "Verify one or more citations are displayed"+ ],+ "passes": false+ }+]diff --git a/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdnew file mode 100644index 0000000..3ad5066--- /dev/null+++ b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 08++Utilisez ce dossier pour des exemples de :++- gating d'état de réussite+- vérification de bout en bout+- critères d'achèvement faibles vs forts+- exemples de boucle d'évaluationdiff --git a/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdnew file mode 100644index 0000000..297fa4c--- /dev/null+++ b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -0,0 +1,8 @@+# Politique de Porte de Réussite++Une fonctionnalité ne peut passer de `passes: false` à `passes: true` que lorsque :++- le flux de travail attendu a été exercé+- la preuve de succès est enregistrée+- aucune erreur bloquante n'est présente dans le chemin testé+- l'implémentation ne laisse pas l'application dans un état cassé ou ambigudiff --git a/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdnew file mode 100644index 0000000..fe3da9c--- /dev/null+++ b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -0,0 +1,138 @@+[中文版本 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> Projet pratique : [Projet 04. Feedback runtime et contrôle de portée](./../../projects/project-04-incremental-indexing/index.md)++# Leçon 08. Utiliser les listes de fonctionnalités pour contraindre l'agent++Vous demandez à un agent de construire un site e-commerce. Une fois terminé, il vous dit "done". Vous regardez le code : l'authentification utilisateur fonctionne, mais le bouton de checkout du panier ne fait rien, et le flux de paiement n'est pas connecté. Le problème : vous ne lui avez jamais dit ce que "done" signifie, donc il a utilisé son propre standard : "j'ai écrit beaucoup de code et ça a l'air assez complet".++Aux yeux de beaucoup de gens, les listes de fonctionnalités ne sont qu'un mémo : on note les choses pour ne pas oublier, puis on les met de côté. Mais dans le monde du harness, une liste de fonctionnalités n'est pas un mémo pour humains : c'est la colonne vertébrale de tout le harness. Le scheduler s'en sert pour choisir les tâches, le verifier pour juger l'achèvement, le handoff reporter pour générer les résumés. Si la colonne vertébrale casse, tout le corps est paralysé.++Anthropic et OpenAI insistent tous deux : **les artefacts doivent être externalisés.** L'état des fonctionnalités doit vivre dans un fichier lisible par machine dans le repo, pas dans du texte de conversation non structuré.++## Les agents ne savent pas ce que "done" signifie++Ni Claude Code ni Codex ne savent automatiquement ce que vous voulez dire par "done". Vous dites "ajoute une fonctionnalité de panier", et le modèle peut interpréter cela comme "écrire un composant Cart et une méthode addToCart". Mais vous vouliez dire "l'utilisateur peut parcourir les produits, les ajouter au panier et terminer le checkout de bout en bout". Sans liste de fonctionnalités, cet écart de compréhension persiste. L'agent utilise son propre standard implicite, généralement "le code n'a pas d'erreur de syntaxe évidente". Ce qu'il vous faut, c'est une vérification comportementale end-to-end. C'est comme demander à un ami d'acheter des fruits : vous dites "prends des fruits" et il revient avec des citrons. Ses fruits et vos fruits ne sont pas les mêmes fruits.++Regardez cette note de progression courante :++```+Did user auth, shopping cart mostly done, still need payments+```++Une nouvelle session d'agent peut-elle répondre à ces questions à partir de cette note ? Que signifie "mostly done" ? Quels tests le panier a-t-il réussis ? Qu'est-ce qui bloque les paiements ? La réponse à tout cela est "personne ne sait". Comme dire à votre médecin "j'ai mal au ventre, ça va à peu près ces derniers temps" : quel médicament peut-il prescrire ?++Résultat : la nouvelle session passe 20 minutes à inférer l'état du projet et peut réimplémenter des fonctionnalités déjà terminées. Les données d'ingénierie d'Anthropic montrent que de bons enregistrements de progression réduisent le temps de diagnostic au démarrage d'une session de 60 à 80%.++## Machine d'état des fonctionnalités++```mermaid+flowchart LR+ Feature["Une ligne de fonctionnalité"] --> Behavior["Comportement<br/>par ex. : POST /cart/items returns 201"]+ Feature --> Check["Commande de vérification<br/>le check exact à exécuter"]+ Feature --> State["État<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["Les trois champs sont nécessaires<br/>pour que la ligne soit utilisable"]+ Check --> Complete+ State --> Complete+```++```mermaid+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["Choisir le prochain item not_started"]+ Scheduler --> Agent["L'agent travaille sur cet item"]+ Agent --> Verifier["Exécuter la commande de vérification de l'item"]+ Verifier -->|pass| Passing["Le marquer passing<br/>et écrire la preuve"]+ Verifier -->|fail| Active["Le garder active"]+ Verifier -->|dependency issue| Blocked["Le marquer blocked"]+ Passing --> Handoff["Mettre à jour la note de handoff<br/>et la progression actuelle"]+ Active --> Agent+```++## Concepts clés++- **Les listes de fonctionnalités sont des primitives de harness** : pas des "outils de planification optionnels", mais des structures de données fondatrices dont dépendent tous les autres composants du harness. Comme les structures de tables en base de données : on ne peut pas dire "sautons les clés primaires".+- **Structure triple** : chaque item de fonctionnalité est un triplet `(description de comportement, commande de vérification, état actuel)`. Si un élément manque, l'item est incomplet.+- **Modèle de machine d'état** : chaque item a quatre états : `not_started`, `active`, `blocked`, `passing`. Les transitions d'état sont contrôlées par le harness, pas librement modifiées par l'agent.+- **Pass-state gating** : le seul moyen de passer de `active` à `passing` est que la commande de vérification réussisse. C'est irréversible : une fois `passing`, on ne revient pas en arrière. Comme un examen réussi : vous l'avez réussi, on ne change pas rétroactivement la note.+- **Single source of truth** : toute information sur "ce qu'il faut faire" doit dériver d'une seule liste de fonctionnalités. Pas de contradictions entre la liste et l'historique de conversation.+- **Back-pressure** : le nombre de fonctionnalités qui ne sont pas encore passées est la pression que le harness exerce sur l'agent. Pression zéro = projet terminé.++## Pourquoi les listes de fonctionnalités doivent être des "primitives"++Les documents sont faits pour être lus par des humains ; les primitives sont faites pour être exécutées par des systèmes. Les documents peuvent être ignorés ; les primitives ne peuvent pas être contournées.++Pensez à la différence entre les contraintes de trigger en base de données et les checks côté application : les premières sont imposées par le moteur de base de données, aucun SQL ne peut les éviter ; les secondes dépendent de la correction du code applicatif et peuvent être contournées par accident. Comme primitive du harness, la liste de fonctionnalités sert quatre composants :++1. **Scheduler** : lit les états et choisit la prochaine fonctionnalité `not_started`. Comme un système de planification de production d'usine.+2. **Verifier** : exécute les commandes de vérification et décide d'autoriser ou non les transitions d'état. Comme une inspection qualité.+3. **Handoff reporter** : génère automatiquement des résumés de passation de session depuis la liste de fonctionnalités. Comme un rapport automatique de changement d'équipe.+4. **Progress tracker** : agrège la distribution des états et fournit des métriques de santé du projet. Comme un tableau de bord.++## Comment bien faire++### 1. Définir un format minimal de liste de fonctionnalités++Pas besoin d'un système complexe : un fichier Markdown structuré ou JSON suffit. L'essentiel est que chaque entrée contienne le triplet :++```json+{+ "id": "F03",+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",+ "state": "passing",+ "evidence": "commit abc123, test output log"+}+```++### 2. Laisser le harness contrôler les transitions d'état++L'agent ne peut pas modifier directement l'état d'une fonctionnalité en `passing`. Il peut seulement soumettre une demande de vérification ; le harness exécute la commande de vérification et décide d'autoriser ou non la transition. C'est le pass-state gating.++### 3. Écrire les règles dans CLAUDE.md++```+## Feature List Rules+- Feature list file: /docs/features.md+- Only one feature active at a time+- Verification command must pass before marking as passing+- Don't modify feature list states yourself — the verification script updates them automatically+```++### 4. Calibrer la granularité++Chaque item de fonctionnalité doit être dimensionné pour être "terminable en une session". Trop large, il ne se terminera pas ; trop étroit, le coût de gestion augmente. "L'utilisateur peut ajouter des articles au panier" est une bonne granularité. "Implémenter le panier" est trop large. "Créer le champ name sur le modèle Cart" est trop étroit. Comme découper un steak : ni la pièce entière, ni de la viande hachée.++## Cas réel++Une plateforme e-commerce avec 10 fonctionnalités. Deux approches de suivi ont été comparées :++**Mode mémo** : l'agent utilise des notes non structurées. Après 3 sessions, les notes deviennent "user auth et product list faits, shopping cart presque terminé mais avec bugs, payments pas commencé". La nouvelle session a besoin de 20 minutes pour inférer l'état et finit par réimplémenter des fonctionnalités déjà terminées. Comme une liste de courses qui dit "lait, pain, et ce truc" : au magasin, vous ne savez toujours pas quoi acheter.++**Mode colonne vertébrale** : chaque fonctionnalité a un état clair et une commande de vérification. La nouvelle session lit la liste et sait en 3 minutes : F01-F05 sont `passing`, F06 est `active`, F07-F10 sont `not_started`. Elle reprend directement à F06, sans retravail.++Résultat quantifié : les projets utilisant des listes de fonctionnalités structurées affichent un taux d'achèvement 45% supérieur au suivi libre, avec zéro implémentation dupliquée.++## Points clés++- **Les listes de fonctionnalités sont la colonne vertébrale du harness**, pas des mémos pour humains. Scheduler, verifier et handoff reporter en dépendent tous.+- **Chaque item doit avoir le triplet** : description de comportement + commande de vérification + état actuel. S'il manque un élément, il est incomplet, comme un tabouret à trois pieds auquel il manque un pied.+- **Les transitions d'état sont contrôlées par le harness** : l'agent ne peut pas changer les états seul. Réussir la vérification est le seul chemin de promotion.+- **La liste de fonctionnalités est la single source of truth du projet** : toutes les informations "quoi faire" dérivent d'une seule liste.+- **Calibrez la granularité sur "terminable en une session".**++## Pour aller plus loin++- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — Identifie explicitement la liste de fonctionnalités comme la "core data structure" pour contrôler la portée de l'agent+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Met l'accent sur le principe d'"externalisation des artefacts"+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — Principes de design par contrat, fondation théorique des listes de fonctionnalités+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — Pyramide de tests et pratiques d'ingénierie de spécification comportementale++## Exercices++1. **Design de liste de fonctionnalités** : définissez un schéma JSON minimal. Incluez : id, description de comportement, commande de vérification, état actuel, référence de preuve. Utilisez-le pour décrire un vrai projet avec 5 fonctionnalités.++2. **Comparaison de rigueur de vérification** : choisissez 3 fonctionnalités et concevez une vérification "souple" (par exemple "le code n'a pas d'erreurs de syntaxe") et une vérification "stricte" (par exemple "le test end-to-end passe"). Comparez le taux de faux positifs.++3. **Audit du principe single source** : examinez un projet agentique existant et cherchez les informations de portée qui contredisent la liste de fonctionnalités (exigences implicites dans les conversations, commentaires TODO dans le code, etc.). Concevez un plan pour unifier toute l'information dans la liste.diff --git a/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.mdnew file mode 100644index 0000000..5666124--- /dev/null+++ b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md@@ -0,0 +1,6 @@+# Liste de Contrôle d'État Propre++- L'application démarre sans réparation manuelle+- La progression actuelle est enregistrée+- Aucune étape d'importation ou d'indexation à moitié terminée ne reste non documentée+- Le prochain agent peut exécuter immédiatement le chemin standard de démarrage et de vérificationdiff --git a/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdnew file mode 100644index 0000000..92e8806--- /dev/null+++ b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 09++Utilisez ce dossier pour des exemples de :++- logs comme retours+- visibilité de l'état d'exécution+- vérifications d'état propre+- exemples de récupérationdiff --git a/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.tsnew file mode 100644index 0000000..fad1a3b--- /dev/null+++ b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts@@ -0,0 +1,241 @@+/**+ * victory-detector.ts+ *+ * Simulates an agent that claims task completion, then checks the claimed+ * state against actual verification. Outputs: claimed vs actual, highlighting+ * gaps between what the agent said and what's really true.+ *+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Task {+ name: string;+ claimedComplete: boolean;+ checks: VerificationCheck[];+}++interface VerificationCheck {+ description: string;+ claimed: boolean; // What the agent says+ actual: boolean; // What is actually true+ severity: "critical" | "warning";+}++// ---------------------------------------------------------------------------+// Simulated tasks with claimed vs actual states+// ---------------------------------------------------------------------------++const tasks: Task[] = [+ {+ name: "Add search endpoint",+ claimedComplete: true,+ checks: [+ {+ description: "Route handler exists",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Authentication middleware applied",+ claimed: true,+ actual: false, // Agent forgot auth+ severity: "critical",+ },+ {+ description: "Input validation added",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Unit tests written",+ claimed: true,+ actual: false, // Agent skipped tests+ severity: "critical",+ },+ {+ description: "Integration tests pass",+ claimed: true,+ actual: false, // No tests to run+ severity: "critical",+ },+ {+ description: "Documentation updated",+ claimed: true,+ actual: false, // Agent skipped docs+ severity: "warning",+ },+ ],+ },+ {+ name: "Fix pagination bug",+ claimedComplete: true,+ checks: [+ {+ description: "Bug reproduction case confirmed",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Root cause identified",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Fix applied",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Edge cases tested",+ claimed: true,+ actual: false, // Only happy path tested+ severity: "warning",+ },+ {+ description: "Regression tests added",+ claimed: true,+ actual: false,+ severity: "critical",+ },+ ],+ },+ {+ name: "Refactor auth module",+ claimedComplete: true,+ checks: [+ {+ description: "Old code removed",+ claimed: true,+ actual: false, // Old code still present+ severity: "warning",+ },+ {+ description: "All existing tests still pass",+ claimed: true,+ actual: false, // Two tests broke+ severity: "critical",+ },+ {+ description: "New auth flow works",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Migration guide written",+ claimed: true,+ actual: false,+ severity: "warning",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Verification+// ---------------------------------------------------------------------------++interface TaskVerification {+ taskName: string;+ claimedComplete: boolean;+ actuallyComplete: boolean;+ totalChecks: number;+ claimedPassing: number;+ actualPassing: number;+ gaps: { description: string; severity: string }[];+}++function verifyTask(task: Task): TaskVerification {+ const claimedPassing = task.checks.filter((c) => c.claimed).length;+ const actualPassing = task.checks.filter((c) => c.actual).length;+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);++ return {+ taskName: task.name,+ claimedComplete: task.claimedComplete,+ actuallyComplete: gaps.length === 0,+ totalChecks: task.checks.length,+ claimedPassing,+ actualPassing,+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");+ console.log("=".repeat(90));++ const verifications = tasks.map(verifyTask);++ for (const v of verifications) {+ console.log("\n Task: " + v.taskName);+ console.log(" " + "-".repeat(70));+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);++ if (!v.actuallyComplete) {+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);+ }++ // Detailed checks for this task+ const task = tasks.find((t) => t.name === v.taskName)!;+ console.log("\n Check detail:");+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;+ console.log(header);+ console.log(sep);++ for (const check of task.checks) {+ const claimedLabel = check.claimed ? "PASS" : "FAIL";+ const actualLabel = check.actual ? "PASS" : "FAIL";+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";+ const marker = gapLabel ? ">>" : " ";+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);+ }+ }++ // Overall summary+ console.log("\n" + "=".repeat(90));+ console.log(" OVERALL SUMMARY");+ console.log("=".repeat(90) + "\n");++ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;+ console.log(sHeader);+ console.log(sSep);++ for (const v of verifications) {+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);+ const cLabel = v.claimedComplete ? "Done" : "Pending";+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);+ }++ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;++ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");+ console.log(" Total undetected gaps: " + totalGaps);+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");+}++run();diff --git a/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdnew file mode 100644index 0000000..ba9e7e3--- /dev/null+++ b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -0,0 +1,145 @@+[中文版本 →](../../../zh/lectures/lecture-09-why-agents-declare-victory-too-early/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# Leçon 09. Empêcher les agents de déclarer victoire trop tôt++Vous demandez à un agent d'implémenter une fonctionnalité de « réinitialisation de mot de passe ». Il modifie le schéma de la base de données, écrit l'endpoint API, ajoute le template d'email, lance les tests unitaires (tous réussis), puis vous annonce avec assurance « c'est fait ». Quand vous essayez réellement de l'exécuter — le lien de réinitialisation ne peut pas être envoyé (configuration du service email manquante), la migration de la base de données échoue à mi-chemin (incohérence du schéma), et le flux de bout en bout n'a jamais été exécuté une seule fois.++Ce sentiment ne devrait pas vous être étranger — c'est comme remplir entièrement sa copie d'examen, être le premier à la remettre en toute confiance, pour finalement échouer quand les notes arrivent. Ce n'est pas parce que la copie est pleine que les réponses sont justes.++Ce n'est pas un incident isolé. L'article classique de 2017 à l'ICML de Guo et al. a prouvé : **les réseaux de neurones modernes sont systématiquement trop confiants** — la confiance rapportée par les modèles est significativement plus élevée que leur précision réelle. Il en va de même pour les agents de codage IA : ils « sentent » qu'ils ont terminé, mais en réalité, ils en sont loin. Votre harness doit remplacer les « sentiments » de l'agent par une vérification externalisée, basée sur l'exécution.++## La pente glissante++Les déclarations prématurées de complétion suivent presque toujours le même schéma : le code semble correct — la syntaxe est bonne, la logique paraît raisonnable, et l'analyse statique ne montre aucune erreur évidente. Mais le harness n'impose pas de vérification d'exécution complète, donc l'agent skip l'exécution réelle ou ne lance que des tests partiels. Il exécute les tests unitaires mais ignore les tests d'intégration ; il lance les tests mais ne vérifie pas la couverture. Finalement, « le code semble bon » est pris comme preuve que « la fonctionnalité est complète ». Et la copie d'examen est remise.++De l'information est perdue à chaque étape. Des spécifications de la tâche à l'implémentation du code jusqu'au comportement à l'exécution, chaque transformation peut introduire un biais, et chaque vérification ignorée aggrave l'asymétrie d'information.++## Vérification d'achèvement en trois couches++```mermaid+flowchart LR+ Claim["Agent says: done"] --> L1["First run<br/>lint / typecheck"]+ L1 --> L2["Then run<br/>tests and startup checks"]+ L2 --> L3["Finally run<br/>complete user flow"]+ L3 --> Done["Pass all three to be done"]+```++```mermaid+flowchart LR+ A["Code is written<br/>unit tests are green"] --> B["But app didn't really start<br/>full flow never ran"]+ B --> C["Config, DB, external service issues<br/>all remain hidden"]+ C --> D["So agent declares victory too early"]+```++## Concepts clés++- **Déclaration prématurée de complétion** : L'agent affirme que la tâche est terminée, mais des spécifications de correction non satisfaites existent encore. Le problème central : l'agent juge sur la base d'une confiance locale au niveau du code, alors que la correction au niveau système nécessite une vérification globale.+- **Biais de calibration de confiance** : L'écart systématique entre la confiance auto-rapportée de l'agent quant à l'achèvement et la qualité réelle de cet achèvement. Pour les tâches complexes multi-fichiers, ce biais est significativement positif — l'agent est toujours plus confiant qu'il ne performe réellement. Comme un étudiant qui surestime toujours sa note après un examen.+- **Critères d'achèvement** : Un ensemble clair et exécutable de conditions de jugement définies dans le harness. L'agent doit satisfaire toutes les conditions avant de déclarer l'achèvement. « Terminé » passe d'un jugement subjectif à une détermination objective.+- **Double porte vérification-validation** : La première couche de vérification contrôle « le code a-t-il correctement implémenté le comportement spécifié » ; la seconde couche de validation contrôle « le comportement au niveau système répond-il aux exigences de bout en bout ». Les deux doivent réussir pour que la tâche soit considérée comme complète.+- **Signaux de retour à l'exécution** : Logs, états de processus et vérifications de santé provenant de l'exécution du programme. C'est la base objective sur laquelle le harness juge la qualité de l'achèvement.+- **Contrainte de priorité d'achèvement** : D'abord vérifier la correction fonctionnelle, puis traiter la performance, et enfin s'occuper du style. Le refactoring est interdit tant que la fonctionnalité principale n'est pas vérifiée.++## Les tests unitaires passent ≠ La tâche est terminée++C'est le piège le plus courant, et le plus dangereux. L'agent a écrit le code, lancé les tests unitaires, tout est au vert, et dit « terminé ». Mais la philosophie de conception des tests unitaires — isoler l'unité testée et mocker les dépendances — est précisément ce qui les rend incapables de détecter les problèmes inter-composants :++**Inadéquation d'interface** : Le chemin de fichier passé par le processus de rendu au script preload est un chemin relatif, mais le script preload attend un chemin absolu. Leurs tests unitaires respectifs utilisaient tous des mocks et passaient. Le problème n'est découvert que lors des tests de bout en bout. Comme chaque musicien d'un groupe qui répète parfaitement de son côté, pour se rendre compte qu'ils sont dans des tonalités différentes en jouant ensemble.++**Erreurs de propagation d'état** : Une migration de base de données modifie le schéma de la table, mais la couche de cache ORM conserve encore des entrées de cache pour l'ancien schéma. Les tests unitaires fournissent un environnement mock frais à chaque fois, ce qui n'exposera pas cette incohérence d'état inter-couches.++**Dépendance à l'environnement** : Le code se comporte correctement dans l'environnement de test (où tout est mocké) mais échoue dans l'environnement réel en raison de différences de configuration, de latence réseau ou d'indisponibilité de service. Comme chanter parfaitement dans la salle de répétition, mais rencontrer des problèmes d'équipement audio sur scène.++### « Refactorer pendant qu'on y est » est un poison pour le jugement d'achèvement++Claude Code présente un schéma de comportement courant : il commence à refactorer le code, optimiser la performance et améliorer le style avant que la fonctionnalité principale n'ait passé la vérification. La citation de Knuth, « L'optimisation prématurée est la racine de tous les maux », prend un nouveau sens dans le scénario de l'agent — le refactoring modifie la frontière entre le code vérifié et non vérifié, risquant de casser des chemins de code précédemment corrects de manière implicite. C'est comme recopier ses réponses à choix multiples pour une meilleure mise en forme avant d'avoir fini les questions de dissertation en mathématiques — non seulement cela perd du temps, mais vous pourriez mal les recopier.++### Biais systématique dans l'auto-évaluation++Anthropic a découvert un schéma d'échec plus profond dans ses recherches de 2026 : **quand on demande à un agent d'évaluer son propre travail, il fournit systématiquement des évaluations excessivement positives — même quand un observateur humain considérerait la qualité comme clairement insuffisante.** C'est comme demander à un étudiant de noter sa propre copie — il sera toujours particulièrement indulgent envers ses propres réponses.++Ce problème est particulièrement sévère dans les tâches subjectives (comme l'esthétique de design) — juger si une « mise en page est exquise » est une question d'appréciation, et l'agent penche systématiquement vers le positif. Même sur des tâches à résultats vérifiables, la performance de l'agent peut être entravée par un mauvais jugement.++La solution n'est pas de rendre l'agent « plus objectif » — le même modèle générant et évaluant est intrinsèquement enclin à être généreux envers lui-même. **La solution est de séparer le « travailleur » du « vérificateur ».** Comme un étudiant ne devrait pas noter sa propre copie — il faut un correcteur indépendant.++Un agent d'évaluation indépendant, spécifiquement réglé pour être « pointilleux », est bien plus efficace que de faire s'auto-évaluer l'agent générateur. Données expérimentales d'Anthropic :++| Architecture | Durée d'exécution | Coût | Fonctionnalités principales fonctionnelles ? |+|--------------|---------|------|------------------------|+| Agent unique (exécution nue) | 20 min | 9 $ | Non (entités du jeu ne réagissent pas aux entrées) |+| Trois agents (planificateur + générateur + évaluateur) | 6 heures | 200 $ | Oui (le jeu est entièrement jouable) |++C'est exactement le même modèle (Opus 4.5) avec exactement le même prompt (« construire un éditeur de jeu rétro 2D »). La seule différence est le harness — passer d'une « exécution nue » à « planificateur détaille les exigences → générateur implémente fonctionnalité par fonctionnalité → évaluateur effectue des tests de clic réels avec Playwright ».++> Source : [Anthropic : Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## Comment empêcher les remises prématurées++### 1. Externaliser le jugement d'achèvement++Le jugement de complétion ne devrait pas être fait par l'agent lui-même. Le harness doit exécuter indépendamment la validation d'achèvement, en utilisant les signaux à l'exécution comme entrée, pas la confiance de l'agent. Écrivez ceci clairement dans `CLAUDE.md` :++```+## Definition of Done+- Feature complete = end-to-end verification passed, not "code is written"+- Required verification levels:+ 1. Unit tests pass+ 2. Integration tests pass+ 3. End-to-end flow verification passes+- Do not proceed to level 2 if level 1 fails+- Do not proceed to level 3 if level 2 fails+```++### 2. Construire une validation d'achèvement en trois couches++- **Couche 1 : Syntaxe et analyse statique**. Coût le plus faible, le moins d'information, mais doit passer. C'est la vérification minimale — il faut d'abord bien orthographier les mots avant d'examiner autre chose.+- **Couche 2 : Vérification du comportement à l'exécution**. Exécution des tests, vérifications de démarrage de l'application, validation des chemins critiques. C'est la preuve centrale de l'achèvement. Il ne suffit pas de l'écrire ; il faut que ça tourne.+- **Couche 3 : Confirmation au niveau système**. Tests de bout en bout, validation d'intégration, simulation de scénarios utilisateur. La dernière ligne de défense contre les déclarations prématurées. Il ne suffit pas que ça tourne ; il faut que ça tourne correctement.++### 3. Concevoir de bonnes « annotations au stylo rouge » pour les agents++OpenAI a introduit un schéma particulièrement efficace lors de sa pratique Codex : **les messages d'erreur pour les agents doivent inclure des instructions de correction**. Ne vous contentez pas de tracer une grande croix rouge comme un correcteur paresseux ; soyez comme un bon professeur et écrivez en marge « voici comment vous devriez changer cela ». N'utilisez pas `"Test failed"`, mais utilisez `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` Ce retour spécifique et actionnable permet à l'agent de s'autocorriger sans intervention humaine.++### 4. Capturer les signaux à l'exécution++Les signaux à l'exécution efficaces incluent :+- L'application a-t-elle démarré avec succès et atteint un état prêt ?+- Les chemins de fonctionnalités critiques se sont-ils exécutés avec succès à l'exécution ?+- Les écritures en base de données, opérations sur fichiers et autres effets de bord étaient-ils corrects ?+- Les ressources temporaires ont-elles été nettoyées ?++## Cas concret++**Tâche** : Implémenter une fonctionnalité de réinitialisation de mot de passe utilisateur. Implique des opérations en base de données, l'envoi d'emails et des modifications d'endpoints API.++**Parcours de remise prématurée** : L'agent modifie le schéma de la base de données, écrit l'endpoint API, ajoute le template d'email, lance les tests unitaires (réussis), et déclare la complétion. La copie d'examen est entièrement remplie.++**Déductions de points réelles** : (1) Le flux de bout en bout n'a pas été testé — l'envoi et la vérification réels du lien de réinitialisation n'ont jamais été confirmés. (2) La migration de la base de données a échoué après une exécution partielle, causant une incohérence du schéma. (3) La configuration du service email manquait dans l'environnement cible.++**Intervention du harness** : Validation d'achèvement imposée — (1) Démarrer l'application complète pour vérifier l'accessibilité de l'endpoint de réinitialisation ; (2) Exécuter le flux complet de réinitialisation ; (3) Vérifier la cohérence de l'état de la base de données. Tous les défauts ont été trouvés dans la session, permettant d'économiser 5 à 10 fois le coût des corrections ultérieures. Le correcteur indépendant a trouvé les vrais problèmes.++## Points clés++- **Les agents sont systématiquement trop confiants** — le biais de calibration de confiance est une réalité objective. Remplir la copie d'examen ne signifie pas avoir les bonnes réponses.+- **Le jugement d'achèvement doit être externalisé** — le harness vérifie indépendamment ; ne vous fiez pas aux « sentiments » de l'agent. Les étudiants ne peuvent pas noter leurs propres copies.+- **Les trois couches de validation sont toutes indispensables** — syntaxe validée, comportement validé, système validé, progressant couche par couche.+- **Les messages d'erreur devraient ressembler aux annotations au stylo rouge d'un bon professeur** — inclure des étapes de correction spécifiques pour que l'agent puisse s'autocorriger.+- **Pas de refactoring tant que la fonctionnalité principale n'est pas vérifiée** — la contrainte de priorité d'achèvement est la clé pour prévenir l'optimisation prématurée.++## Pour aller plus loin++- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — Prouve que les réseaux profonds modernes sont systématiquement trop confiants+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — Le rôle critique des preuves à l'exécution dans le jugement d'achèvement+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — La déclaration prématurée de complétion est l'un des principaux modes d'échec des agents+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — Référence classique sur les hiérarchies de méthodes de test et leur efficacité++## Exercices++1. **Conception d'une fonction de validation d'achèvement** : Concevez une validation d'achèvement complète pour une tâche impliquant une migration de base de données et une modification d'API. Listez les signaux à l'exécution requis et les critères de réussite/échec pour chaque signal. Exécutez-la sur une tâche réelle et enregistrez les problèmes cachés qu'elle découvre.++2. **Mesure du biais de calibration** : Choisissez 10 types différents de tâches de codage, et enregistrez la confiance d'achèvement auto-rapportée par l'agent par rapport à la qualité réelle de l'achèvement. Calculez la valeur du biais et analysez sa relation avec la complexité de la tâche.++3. **Expérience de défense multi-couches** : Exécutez trois configurations sur le même ensemble de tâches — (a) analyse statique uniquement, (b) ajout des tests unitaires, (c) validation complète en trois couches. Comparez la proportion de déclarations prématurées de complétion et le nombre de défauts non détectés.diff --git a/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.mdnew file mode 100644index 0000000..5cf6d52--- /dev/null+++ b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md@@ -0,0 +1,6 @@+# Règles d'Architecture Electron++- Le code du renderer ne peut pas accéder directement au système de fichiers.+- Le preload est le seul pont entre le renderer et Electron main.+- La logique de récupération et d'indexation vit dans les modules de service, pas dans les composants UI.+- La journalisation doit être structurée et émise depuis les frontières de service.diff --git a/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.tsnew file mode 100644index 0000000..2428416--- /dev/null+++ b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts@@ -0,0 +1,253 @@+/**+ * e2e-runner.ts+ *+ * A minimal E2E test harness. Defines test cases as user action sequences+ * (import doc -> index -> ask question -> verify citation). Simulates+ * running them and shows the difference between "unit tests pass" and+ * "full pipeline works".+ *+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface PipelineStep {+ name: string;+ unitTestPasses: boolean;+ // Simulated actual behavior in the pipeline+ actualBehavior: "works" | "fails" | "partial";+ failureReason?: string;+}++interface TestCase {+ name: string;+ steps: PipelineStep[];+}++interface TestResult {+ testCase: string;+ unitTestsPassed: number;+ unitTestsTotal: number;+ unitTestResult: "PASS" | "FAIL";+ e2eResult: "PASS" | "FAIL";+ e2eFailureStep?: string;+ e2eFailureReason?: string;+}++// ---------------------------------------------------------------------------+// Test cases -- realistic scenarios where unit tests pass but E2E fails+// ---------------------------------------------------------------------------++const testCases: TestCase[] = [+ {+ name: "Import document and ask question",+ steps: [+ {+ name: "Parse uploaded document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Store document chunks",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Index chunks for retrieval",+ unitTestPasses: true,+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions+ failureReason: "Embedding dimension mismatch between indexer and retriever",+ },+ {+ name: "Retrieve relevant chunks",+ unitTestPasses: true, // Unit test uses mock data with correct dimensions+ actualBehavior: "fails",+ failureReason: "Empty results due to dimension mismatch from previous step",+ },+ {+ name: "Generate answer with citations",+ unitTestPasses: true, // Unit test provides pre-retrieved chunks+ actualBehavior: "fails",+ failureReason: "No chunks retrieved, so answer has no citations",+ },+ ],+ },+ {+ name: "Delete document and verify removal",+ steps: [+ {+ name: "Find document by ID",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Delete document record",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Remove indexed chunks",+ unitTestPasses: true,+ actualBehavior: "fails", // Orphaned chunks remain in the index+ failureReason: "Index cleanup query timed out, chunks remain orphaned",+ },+ {+ name: "Verify document not in search results",+ unitTestPasses: true, // Unit test mocks the search+ actualBehavior: "fails",+ failureReason: "Orphaned chunks from previous step still appear in results",+ },+ ],+ },+ {+ name: "Multi-user concurrent access",+ steps: [+ {+ name: "User A imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User B imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User A queries their document",+ unitTestPasses: true,+ actualBehavior: "partial", // Cross-contamination of results+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",+ },+ {+ name: "Verify only User A's results returned",+ unitTestPasses: true,+ actualBehavior: "fails",+ failureReason: "Results include documents from other users",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Run tests+// ---------------------------------------------------------------------------++function runUnitTests(tc: TestCase): { passed: number; total: number } {+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;+ return { passed, total: tc.steps.length };+}++function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {+ // Pipeline: if any step actually fails, the whole E2E fails+ for (const step of tc.steps) {+ if (step.actualBehavior === "fails") {+ return {+ pass: false,+ failureStep: step.name,+ failureReason: step.failureReason ?? "Unknown failure",+ };+ }+ // "partial" means the step technically completes but creates problems downstream+ // We let it continue but track it+ }+ // Check if any step was "partial" (which may cause downstream issues)+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");+ if (partialSteps.length > 0) {+ // The partial steps may or may not cause overall failure+ // In our simulation, partial steps always lead to failure downstream+ // unless there's an explicit "fails" step that already caught it+ // This case means all steps were either "works" or "partial"+ return {+ pass: false,+ failureStep: partialSteps[partialSteps.length - 1].name,+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",+ };+ }++ return { pass: true };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(95));+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");+ console.log("=".repeat(95));++ const results: TestResult[] = testCases.map((tc) => {+ const unit = runUnitTests(tc);+ const e2e = runE2ETest(tc);++ return {+ testCase: tc.name,+ unitTestsPassed: unit.passed,+ unitTestsTotal: unit.total,+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",+ e2eResult: e2e.pass ? "PASS" : "FAIL",+ e2eFailureStep: e2e.failureStep,+ e2eFailureReason: e2e.failureReason,+ };+ });++ // Per-test-case detail+ for (let i = 0; i < testCases.length; i++) {+ const tc = testCases[i];+ const r = results[i];++ console.log("\n Test Case: " + tc.name);+ console.log(" " + "-".repeat(70));++ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;+ console.log(stepHeader);+ console.log(stepSep);++ for (const step of tc.steps) {+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";+ let e2eLabel: string;+ if (step.actualBehavior === "works") e2eLabel = "PASS";+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";+ else e2eLabel = "FAIL";++ const marker = step.actualBehavior !== "works" ? ">>" : " ";+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);+ }++ if (r.e2eFailureStep) {+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);+ console.log(` Reason: ${r.e2eFailureReason}`);+ }+ }++ // Summary comparison+ console.log("\n" + "=".repeat(95));+ console.log(" COMPARISON: Unit Tests vs E2E Tests");+ console.log("=".repeat(95) + "\n");++ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";++ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);+ }++ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");+}++run();diff --git a/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdnew file mode 100644index 0000000..b832238--- /dev/null+++ b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 10++Utilisez ce dossier pour des exemples de :++- contraintes d'architecture+- tests structurels+- invariants de goût (taste invariants)+- messages lint orientés remédiationdiff --git a/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdnew file mode 100644index 0000000..2b29b9a--- /dev/null+++ b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -0,0 +1,10 @@+# Exemple : Transformer un Retour de Review en Règle++Commentaire de review répété :++> N'utilisez pas les utilitaires du système de fichiers depuis le renderer. Utilisez le pont preload.++Règle de harness promue :++- ajouter une règle lint ou d'import empêchant l'utilisation de `fs` dans le code du renderer+- ajouter un texte de remédiation expliquant la frontière du preloaddiff --git a/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdnew file mode 100644index 0000000..bb546a2--- /dev/null+++ b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -0,0 +1,158 @@+[中文版本 →](../../../zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# Leçon 10. Seul le test end-to-end est une vraie vérification++Vous demandez à l'agent d'ajouter une fonctionnalité d'export de fichier à une application Electron. Il écrit le composant du processus de rendu, le script preload et la logique de la couche service. Les tests unitaires de chaque composant passent parfaitement. L'agent dit : « C'est fait. » Quand vous cliquez réellement sur le bouton d'export — le format du chemin de fichier est incorrect, la barre de progression ne se met pas à jour, et l'export de gros fichiers provoque une fuite de mémoire. Cinq défauts aux frontières des composants, et les tests unitaires n'en ont attrapé aucun.++C'est comme une répétition de chœur — chaque pupitre sonne parfaitement chanté individuellement, mais quand ils chantent ensemble, les sopranes sont un demi-temps plus rapides que les basses, et l'accompagnement est un demi-ton décalé par rapport à la mélodie principale. Chaque partie est « correcte » individuellement, mais l'ensemble est faux.++La pyramide de tests de Google nous dit : un grand nombre de tests unitaires constituent la base, mais si vous vous arrêtez là, vous allez systématiquement manquer les problèmes d'interaction entre composants. Pour les agents de codage IA, ce problème est encore plus grave — les agents ont tendance à ne lancer que les tests les plus rapides puis à déclarer la complétion. **Seul le test de bout en bout peut prouver que les défauts au niveau système n'existent pas.**++## Les angles morts des tests unitaires++La philosophie de conception des tests unitaires est l'isolation — mocker les dépendances et se concentrer uniquement sur l'unité testée. Cette philosophie rend les tests unitaires rapides et précis, mais crée aussi des angles morts systématiques. C'est comme si chaque pupitre répétait avec un casque lors d'une répétition de chœur — chacun s'entend très bien, mais les problèmes n'apparaissent que lorsqu'ils se rassemblent :++**Inadéquation d'interface** : Le chemin de fichier passé par le processus de rendu au script preload est un chemin relatif, mais le script preload attend un chemin absolu. Leurs tests unitaires respectifs utilisaient tous des mocks et passaient. Le problème n'est découvert que lorsque le flux de bout en bout est exécuté — comme deux pupitres répétaient indépendamment et se sentaient bien, pour se rendre compte à l'ensemble que l'un chantait en 4/4 et l'autre en 3/4.++**Erreurs de propagation d'état** : Une migration de base de données modifie le schéma de la table, mais la couche de cache ORM conserve encore des entrées de cache pour l'ancien schéma. Les tests unitaires fournissent un environnement mock entièrement nouveau à chaque fois, ce qui n'exposera pas cette incohérence d'état inter-couches. C'est comme changer les paroles d'une chanson, mais quelqu'un chante encore l'ancienne version.++**Problèmes de cycle de vie des ressources** : L'acquisition et la libération des handles de fichiers, des connexions à la base de données et des sockets réseau s'étendent sur plusieurs composants. Les tests unitaires créent et détruisent des ressources indépendantes pour chaque test, ne parvenant pas à exposer les contentions ou les fuites de ressources. C'est comme chaque pupitre utilisant les micros à tour de rôle pendant la répétition, mais quand tout le monde monte sur scène ensemble, il n'y a pas assez de micros.++**Dépendance à l'environnement** : Le code se comporte correctement dans l'environnement de test (où tout est mocké) mais échoue dans l'environnement réel en raison de différences de configuration, de latence réseau ou d'indisponibilité de service. Comme chanter parfaitement dans la salle de répétition, mais rencontrer des larsens et des interférences de vent lors d'un festival en plein air.++## Le test end-to-end ne change pas seulement les résultats, il change le comportement++C'est quelque chose que beaucoup de gens ne réalisent pas : quand un agent sait que son travail sera soumis à des tests de bout en bout, son comportement de codage change.++1. **Prise en compte des interactions entre composants** : En écrivant le code, il pensera à « comment cette interface se connecte avec l'amont », plutôt que de se concentrer uniquement sur une seule fonction. Comme savoir qu'on chantera finalement ensemble, on fera attention aux autres pupitres pendant la répétition.+2. **Respect des frontières architecturales** : Dans les systèmes avec des contraintes architecturales, le test de bout en bout force l'agent à respecter les règles de frontière. Comme une partition marquée « crescendo ici », il faut la suivre.+3. **Gestion des chemins d'erreur** : Les tests de bout en bout incluent généralement des scénarios d'échec, forçant l'agent à considérer le traitement des exceptions. C'est comme simuler « et si le micro tombe en panne soudainement » pendant la répétition, pour savoir quoi faire.++## Pyramide de tests et promotion du retour de revue++```mermaid+flowchart TB+ subgraph Unit["Unit tests only check isolated parts"]+ U1["Renderer tests"]+ U2["Preload tests"]+ U3["Service tests"]+ end++ subgraph E2E["E2E runs through the real system"]+ R["Click renderer button"] --> P["Preload bridge"]+ P --> S["Service layer"]+ S --> F["File System / OS"]+ F --> Result["Actual exported file"]+ end+```++```mermaid+flowchart LR+ Review["Review feedback:<br/>renderer cannot import fs directly"] --> Rule["Add a direct fs import check"]+ Rule --> Message["Tell agent in error message<br/>to move file access to preload"]+ Message --> Harness["Add this check to harness"]+ Harness --> Stronger["Will fail immediately next time"]+```++Dans les pratiques d'ingénierie Codex, OpenAI souligne : **les messages d'erreur écrits pour les agents doivent inclure des instructions de correction.** Ne vous contentez pas d'écrire `"Direct filesystem access in renderer"` ; écrivez `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` Cela transforme les règles architecturales en une boucle d'auto-correction. Comme un chef de chœur qui ne dit pas juste « tu as mal chanté ça », mais dit plutôt « tu étais un demi-temps trop rapide ici, écoute le rythme des altis, et entre à la mesure 32. »++## Concepts clés++- **Défauts aux frontières des composants** : Les composants A et B passent tous deux leurs tests unitaires, mais leur interaction produit un comportement incorrect. C'est le type de problème que le test de bout en bout est le meilleur pour détecter — comme des pupitres de chœur qui sont individuellement corrects mais faux ensemble.+- **Gradient d'adéquation des tests** : Défauts détectés par les tests unitaires <= défauts détectés par les tests d'intégration <= défauts détectés par les tests de bout en bout. Chaque couche supérieure augmente la capacité de détection.+- **Règles d'application des frontières architecturales** : Transformer les règles des documents d'architecture (comme « le processus de rendu ne peut pas accéder directement au système de fichiers ») en vérifications exécutables et automatisées. Passer d'« écrit sur papier » à « exécuté dans le CI ».+- **Promotion du retour de revue** : Convertir les commentaires récurrents de revue de code en tests automatisés. Chaque fois qu'un problème récurrent est découvert, ajoutez une règle, et le harness se renforce automatiquement. Comme un chef de chœur qui transforme les erreurs courantes de répétition en exercices d'échauffement — la prochaine fois que la même erreur est commise, l'exercice lui-même l'expose sans que le chef ait besoin de dire quoi que ce soit.+- **Messages d'erreur orientés agent** : Les messages d'échec ne devraient pas seulement indiquer « ce qui n'a pas fonctionné », mais aussi dire à l'agent exactement comment le corriger. Cela transforme les échecs de test en boucles de retour auto-correctives.++## Comment le faire++### 0. Définir les frontières architecturales d'abord, puis écrire les tests E2E++Le prérequis pour le test de bout en bout est d'avoir des frontières système claires. Si l'architecture est une assiette de spaghettis, le test de bout en bout ne prouvera que « cette assiette de spaghettis fonctionne », il ne vous dira pas où les intentions de design ont été violées. C'est comme un chœur qui n'a même pas été divisé en pupitres — aucune quantité de répétition ne le fera sonner correctement.++L'expérience d'OpenAI : **pour les bases de code générées par des agents, les contraintes architecturales doivent être des prérequis précoces établis dès le premier jour, et non quelque chose à considérer quand l'équipe grandit.** La raison est simple — les agents copient les motifs existants dans le dépôt, même si ces motifs sont inégaux ou sous-optimaux. Sans contraintes architecturales, l'agent introduira plus de déviations à chaque session.++OpenAI a adopté une « architecture en couches par domaine » — chaque domaine métier est divisé en couches fixes : Types → Config → Repo → Service → Runtime → UI. Les dépendances circulent strictement vers l'avant, et les préoccupations inter-domaines entrent par des interfaces Providers explicites. Toute autre dépendance est interdite et imposée mécaniquement via du linting personnalisé.++Principe clé : **Appliquer les invariants, ne pas micro-gérer l'implémentation.** Par exemple, exiger « les données sont analysées à la frontière », mais ne pas dicter quelle bibliothèque utiliser. Les messages d'erreur doivent inclure des instructions de correction — ne pas juste dire « violation », mais dire à l'agent exactement comment le changer.++> Source : [OpenAI : Harness engineering : leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++### 1. Le harness doit inclure une couche end-to-end++Rendez-le explicite dans votre flux de validation : pour les tâches impliquant des modifications inter-composants, réussir les tests de bout en bout est un prérequis à la complétion :++```+## Validation Hierarchy+- Level 1: Unit tests (Must pass)+- Level 2: Integration tests (Must pass)+- Level 3: End-to-end tests (Must pass when cross-component changes are involved)+- Skipping any required level = Not Complete+```++### 2. Transformer les règles architecturales en vérifications exécutables++Chaque contrainte architecturale devrait avoir un test ou une règle de lint correspondante :++```bash+# Check if the render process directly calls Node.js APIs+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"+```++### 3. Concevoir des messages d'erreur orientés agent++Les messages d'échec devraient contenir trois éléments : ce qui n'a pas fonctionné, pourquoi, et comment le corriger :++```+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12+WHY: Renderer process has no access to Node.js APIs for security+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()+```++### 4. Établir un processus de promotion du retour de revue++Chaque fois qu'un nouveau type d'erreur d'agent est découvert lors d'une revue de code, transformez-le en vérification automatisée. Un mois plus tard, votre harness sera significativement plus fort qu'au début du mois. C'est comme les notes de répétition d'un chœur — enregistrer les problèmes trouvés à chaque répétition pour pouvoir les vérifier avant la suivante. Avec le temps, les erreurs courantes diminuent, et la musique devient plus harmonieuse.++## Cas concret++**Tâche** : Implémenter une fonctionnalité d'export de fichier dans une application Electron. Implique l'UI du processus de rendu, le proxy de système de fichiers du script preload et la transformation de données de la couche service.++**Chanter les parties individuellement (tests unitaires réussis)** : Tests du composant de rendu (réussis, opérations sur fichiers mockées), tests du script preload (réussis, système de fichiers mocké), tests de la couche service (réussis, source de données mockée). L'agent déclare la complétion.++**Chanter ensemble (défauts révélés par les tests end-to-end)** :++| Défaut | Description | Test unitaire | E2E |+|--------|-------------|---------------|-----|+| Inadéquation d'interface | Format de chemin de fichier incohérent | Manqué | Détecté |+| Propagation d'état | La progression de l'export n'est pas renvoyée à l'UI via IPC | Manqué | Détecté |+| Fuite de ressources | Handles d'export de gros fichiers non libérés | Manqué | Détecté |+| Problème de permissions | Permissions différentes dans l'environnement packaging | Manqué | Détecté |+| Propagation d'erreur | Les exceptions de la couche service n'atteignaient pas la couche UI | Manqué | Détecté |++Les 5 défauts ont été détectés par les tests de bout en bout, tandis que les tests unitaires n'en ont détecté aucun. Le coût a été une augmentation du temps de test de 2 secondes à 15 secondes — tout à fait acceptable dans un flux de travail d'agent. Aussi bien que chaque partie chante individuellement, ça ne remplace pas une répétition générale complète.++## Points clés++- **Les tests unitaires sont systématiquement aveugles aux défauts aux frontières des composants** — leur conception par isolation est précisément ce qui les empêche de détecter les problèmes d'interaction. Que chacun chante correctement ne signifie pas que le chœur n'est pas faux.+- **Le test end-to-end ne détecte pas seulement les défauts, il change le comportement de codage de l'agent** — le faisant se concentrer davantage sur l'intégration et les frontières.+- **Les règles architecturales doivent être exécutables** — non écrites dans un document en attente d'être lu, mais automatiquement vérifiées à chaque commit.+- **Les messages d'erreur doivent être conçus pour les agents** — incluant des étapes spécifiques sur « comment le corriger » pour former une boucle auto-corrective.+- **La promotion du retour de revue renforce automatiquement le harness** — chaque catégorie de défaut capturée devient une ligne de défense permanente.++## Pour aller plus loin++- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — La source classique du modèle de pyramide de tests+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Pratiques d'ingénierie pour l'exécution automatisée des contraintes architecturales+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — Injection proactive de pannes pour vérifier la résilience du système+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — Méthodologie de test par propriétés, entre le test par l'exemple et la vérification formelle++## Exercices++1. **Détection de défauts inter-composants** : Choisissez une tâche de modification impliquant au moins trois composants. D'abord, lancez uniquement les tests unitaires et enregistrez les résultats, puis lancez les tests de bout en bout. Analysez à quel type de problème d'interaction inter-couches appartient chaque défaut supplémentaire découvert.++2. **Automatisation d'une règle architecturale** : Choisissez une contrainte architecturale de votre projet et transformez-la en vérification exécutable (avec un message d'erreur orienté agent). Intégrez-la dans le harness et vérifiez son efficacité avec une tâche de référence.++3. **Promotion du retour de revue** : Trouvez un type de commentaire récurrent dans votre historique de revue de code et convertissez-le en vérification automatisée en utilisant le processus en cinq étapes. Comparez la fréquence du problème avant et après la promotion.diff --git a/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.mdnew file mode 100644index 0000000..45864a5--- /dev/null+++ b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md@@ -0,0 +1,8 @@+# Exemple de Rubrique d'Évaluation++Utilisez une notation de 1 à 5 pour chaque dimension :++- Fondement : les réponses sont-elles clairement liées aux sources importées ?+- Qualité de citation : les références aux sources sont-elles visibles et spécifiques ?+- Fonctionnalité : l'utilisateur peut-il compléter le flux question-réponse ?+- Cohérence produit : le flux de travail semble-t-il intégré ?diff --git a/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdnew file mode 100644index 0000000..10b79cc--- /dev/null+++ b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 11++Utilisez ce dossier pour des exemples de :++- sorties du planificateur+- rubriques d'évaluation+- boucles générateur/évaluateur+- comparaisons agent unique vs multi-rôlesdiff --git a/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsnew file mode 100644index 0000000..213dc19--- /dev/null+++ b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts@@ -0,0 +1,260 @@+/**+ * runtime-logger.ts+ *+ * A structured logging module demo. Shows ad-hoc console.log output vs+ * structured JSON log output when diagnosing a failure. Includes a seeded+ * failure scenario and demonstrates how structured logs pinpoint the issue+ * faster.+ *+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StructuredLogEntry {+ timestamp: string;+ level: "info" | "warn" | "error" | "debug";+ component: string;+ action: string;+ durationMs?: number;+ input?: unknown;+ output?: unknown;+ error?: string;+ correlationId: string;+}++// ---------------------------------------------------------------------------+// Simulated pipeline with a seeded failure+// ---------------------------------------------------------------------------++const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);++// Simulated stages of a document Q&A pipeline+interface PipelineStage {+ component: string;+ action: string;+ durationMs: number;+ success: boolean;+ errorMessage?: string;+ input?: unknown;+ output?: unknown;+}++function runPipeline(): PipelineStage[] {+ return [+ {+ component: "DocumentLoader",+ action: "parse_upload",+ durationMs: 45,+ success: true,+ input: { filename: "report.pdf", size: "2.3MB" },+ output: { chunks: 47 },+ },+ {+ component: "ChunkIndexer",+ action: "embed_and_store",+ durationMs: 230,+ success: true,+ input: { chunks: 47 },+ output: { indexed: 47, embeddingDim: 1536 },+ },+ {+ component: "QueryRouter",+ action: "route_query",+ durationMs: 12,+ success: true,+ input: { query: "What is the revenue target?" },+ output: { routedTo: "RetrievalEngine" },+ },+ {+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch+ component: "RetrievalEngine",+ action: "semantic_search",+ durationMs: 180,+ success: false,+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",+ input: { query: "What is the revenue target?", topK: 5 },+ output: { results: 0 },+ },+ {+ component: "AnswerGenerator",+ action: "generate_with_citations",+ durationMs: 1500,+ success: true, // Doesn't crash, but produces a bad answer+ input: { context: [], query: "What is the revenue target?" },+ output: { answer: "I could not find relevant information.", citations: 0 },+ },+ ];+}++// ---------------------------------------------------------------------------+// Ad-hoc logging (console.log style)+// ---------------------------------------------------------------------------++function printAdHocLog(stages: PipelineStage[]): void {+ console.log("Starting document Q&A pipeline...");+ console.log("User uploaded report.pdf");++ for (const stage of stages) {+ if (stage.success) {+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);+ } else {+ console.log(`${stage.component}: something went wrong`);+ }+ }++ console.log("Pipeline finished. Answer: I could not find relevant information.");+}++// ---------------------------------------------------------------------------+// Structured logging (JSON)+// ---------------------------------------------------------------------------++function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {+ const entries: StructuredLogEntry[] = [];++ for (const stage of stages) {+ entries.push({+ timestamp: new Date().toISOString(),+ level: stage.success ? "info" : "error",+ component: stage.component,+ action: stage.action,+ durationMs: stage.durationMs,+ input: stage.input,+ output: stage.output,+ error: stage.errorMessage,+ correlationId: CORRELATION_ID,+ });+ }++ return entries;+}++// ---------------------------------------------------------------------------+// Diagnose failure from structured logs+// ---------------------------------------------------------------------------++function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {+ const diagnosis: string[] = [];++ // Find errors+ const errors = entries.filter((e) => e.level === "error");+ if (errors.length > 0) {+ diagnosis.push("ERRORS FOUND:");+ for (const err of errors) {+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);+ }+ }++ // Check for latency spikes+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);+ if (slowStages.length > 0) {+ diagnosis.push("LATENCY SPIKES:");+ for (const s of slowStages) {+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);+ }+ }++ // Check for cascading failures+ const emptyOutputs = entries.filter((e) => {+ const out = e.output as Record<string, unknown> | undefined;+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;+ });+ if (emptyOutputs.length > 0) {+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");+ for (const e of emptyOutputs) {+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);+ }+ }++ return diagnosis;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const pipeline = runPipeline();++ console.log("\n" + "=".repeat(90));+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");+ console.log("=".repeat(90));++ // --- Ad-hoc output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO A: Ad-hoc console.log output");+ console.log("-".repeat(90) + "\n");+ printAdHocLog(pipeline);+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");+ console.log(" The failure message is vague: 'something went wrong'.");+ console.log(" No dimensions, no input/output data, no correlation ID.");++ // --- Structured output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO B: Structured JSON log output");+ console.log("-".repeat(90) + "\n");++ const structuredEntries = printStructuredLog(pipeline);++ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const entry of structuredEntries) {+ const hasError = entry.error ? entry.error.slice(0, 30) : "";+ const marker = entry.level === "error" ? ">>" : " ";+ console.log(+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`+ );+ }++ // --- Diagnosis ---+ console.log("\n" + "-".repeat(90));+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");+ console.log("-".repeat(90) + "\n");++ const errors = structuredEntries.filter((e) => e.level === "error");+ for (const err of errors) {+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);+ console.log(` Error: ${err.error}`);+ console.log(` Input: ${JSON.stringify(err.input)}`);+ console.log(` Output: ${JSON.stringify(err.output)}`);+ console.log(` Correlation ID: ${err.correlationId}`);+ }++ // Downstream impact+ console.log("\n DOWNSTREAM IMPACT:");+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");+ if (answerGen) {+ const out = answerGen.output as Record<string, unknown>;+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);+ }++ // Comparison summary+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON");+ console.log("=".repeat(90) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);++ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");+}++run();diff --git a/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.mdnew file mode 100644index 0000000..5d7d73f--- /dev/null+++ b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md@@ -0,0 +1,12 @@+# Exemple de Contrat de Sprint++Objectif du sprint :++- Ajouter des citations visibles aux résultats Q&A fondés++"Terminé" signifie :++- L'utilisateur pose une question+- L'application renvoie une réponse+- Au moins une citation est affichée+- Cliquer sur une citation ouvre l'emplacement source dans la vue documentdiff --git a/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdnew file mode 100644index 0000000..9d2ddaa--- /dev/null+++ b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -0,0 +1,154 @@+[中文版本 →](../../../zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)+> Projet pratique : [Projet 06. Harness complet (capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# Leçon 11. Rendre le runtime de l'agent observable++## Quel problème cette leçon résout-elle ?++Vous demandez à un agent d'implémenter une fonctionnalité. Il travaille pendant 20 minutes, modifie beaucoup de fichiers, puis annonce : « terminé, mais deux tests échouent ». Vous demandez pourquoi ils échouent : « pas sûr, peut-être un problème de timing ». Vous demandez quelles routes critiques il a modifiées : « laissez-moi regarder le code... ».++Ce n'est pas un manque de capacité de l'agent. C'est votre harness qui ne fournit pas assez d'observabilité. **Sans observabilité, les agents décident dans l'incertitude, les évaluations deviennent subjectives et les nouvelles tentatives deviennent de l'errance à l'aveugle.** OpenAI et Anthropic définissent tous deux la fiabilité comme un problème de preuves : le harness doit exposer le comportement runtime et les signaux d'évaluation sous une forme qui guide la décision suivante.++## Concepts clés++- **Observabilité runtime** : signaux système — logs, traces, événements de processus, health checks. Répond à « qu'a fait le système ? ».+- **Observabilité de processus** : visibilité sur les artefacts de décision du harness — plans, grilles de score, critères d'acceptation. Répond à « pourquoi ce changement devrait-il être accepté ? ».+- **Trace de tâche** : enregistrement complet du chemin de décision, du début à la fin de la tâche, analogue au tracing de requêtes dans les systèmes distribués.+- **Sprint contract** : accord court négocié avant le codage, spécifiant scope, critères de vérification et exclusions. C'est l'outil central de l'observabilité de processus.+- **Grille d'évaluation** : transforme l'évaluation de qualité en score structuré fondé sur des preuves.+- **Observabilité en couches** : observabilité système et observabilité de processus conçues ensemble. Les signaux runtime expliquent le comportement ; les artefacts de processus expliquent l'intention.++## Observabilité en couches++```mermaid+flowchart LR+ Contract["Écrire d'abord la tâche<br/>quoi changer / quoi ne pas changer / critères de réussite"] --> Generator["Generator"]+ Generator --> Signals["Collecter logs, traces<br/>et health checks pendant l'exécution"]+ Contract --> Review["Vérifier le résultat point par point<br/>comportement / tests / limites"]+ Signals --> Review+ Review --> Verdict["Pointer le contrôle échoué<br/>et l'endroit à corriger"]+ Verdict --> Generator+```++## Pourquoi cela arrive++### Le vrai coût du manque d'observabilité++Quand un harness manque d'observabilité, quatre problèmes apparaissent systématiquement :++**Impossible de distinguer « correct » de « semble correct »** : une fonction peut paraître parfaite en revue de code — syntaxe correcte, logique solide. Mais au runtime, une erreur d'edge case produit de mauvais résultats pour certaines entrées. Seules les traces runtime révèlent que le chemin réel d'exécution a divergé.++**L'évaluation devient mystique** : sans grille de score et critères d'acceptation, les évaluateurs, humains ou agents, s'appuient sur des hypothèses implicites. Le même résultat peut recevoir des évaluations très différentes. La qualité devient non reproductible.++**Les retries deviennent des paris aveugles** : quand l'agent ne sait pas pourquoi quelque chose a échoué, la direction du retry est aléatoire. Il peut corriger des chemins de code sans rapport en ignorant la vraie cause racine. Chaque retry aveugle coûte des tokens et du temps.++**Falaise d'information au handoff** : quand un travail incomplet passe à la session suivante, l'absence d'observabilité oblige la nouvelle session à diagnostiquer l'état du système depuis zéro. Les observations d'Anthropic sur les agents longue durée montrent que ce diagnostic redondant peut consommer 30-50 % du temps total de session.++### Un scénario réaliste avec Claude Code++Imaginez un harness avec workflow à trois rôles, planner-generator-evaluator, exécutant « ajouter le dark mode à l'application ».++**Sans observabilité** : le planner produit une description vague. Le generator implémente le dark mode à partir de cette description, mais ne correspond pas aux attentes implicites du planner. L'evaluator rejette selon ses propres standards implicites sans pouvoir expliquer précisément ce qui ne va pas. Le generator réessaie à l'aveugle. Le cycle se répète 3-4 fois, prend environ 45 minutes et produit un résultat à peine acceptable.++**Avec observabilité complète** : le planner produit un sprint contract listant les composants à modifier, les critères de vérification et les exclusions. Le generator implémente selon le contrat. L'observabilité runtime enregistre le chargement et l'application des styles de chaque composant. L'evaluator utilise une grille de score, dimension par dimension, avec citations de preuves. Une itération produit un résultat de haute qualité en environ 15 minutes.++La différence d'efficacité est de 3x. Le seul changement est l'observabilité.++### Pourquoi les agents ne peuvent pas résoudre cela seuls++Vous pourriez penser : « l'agent ne peut-il pas simplement imprimer ses propres logs ? » Les problèmes sont :++1. L'agent ne sait pas ce qu'il ne sait pas ; il n'enregistrera pas spontanément des signaux dont il ignore avoir besoin.+2. Les formats de logs sont incohérents ; différentes sessions utilisent différents formats, rendant l'analyse systématique impossible.+3. L'observabilité de processus ne se résout pas par des logs ; sprint contracts et grilles de score sont des artefacts structurés nécessitant un support au niveau du harness.++## Comment bien le faire++### 1. Intégrer la collecte de signaux runtime dans le harness++Ne comptez pas sur l'agent pour imprimer ses propres logs. Le harness doit collecter automatiquement ces signaux :++- **Cycle de vie de l'application** : états startup, ready, running et shutdown+- **Exécution du chemin fonctionnel** : enregistrements des chemins critiques, avec points d'entrée, checkpoints et sorties+- **Flux de données** : données circulant entre composants+- **Utilisation des ressources** : motifs anormaux, par exemple mémoire qui augmente continuellement+- **Erreurs et exceptions** : contexte complet, pas seulement messages d'erreur++### 2. Implémenter des sprint contracts++Avant chaque tâche, generator et evaluator, éventuellement deux invocations du même agent, négocient un contrat :++```markdown+# Sprint Contract: Dark Mode Support++## Scope+- Modify the theme toggle component+- Update global CSS variables+- Add dark mode tests++## Verification Standards+- Visual regression tests pass for each component+- Main flow end-to-end tests pass+- No flash of unstyled content (FOUC)++## Exclusions+- Not handling print styles+- Not handling third-party component dark mode+```++### 3. Établir une grille d'évaluation++Transformez « est-ce bon ou non » en score quantifiable :++```markdown+# Scoring Rubric++| Dimension | A | B | C | D |+|-----------|---|---|---|---|+| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |+| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |+| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |+```++### 4. Standardiser avec OpenTelemetry++Créez une trace pour chaque session de harness, un span pour chaque tâche et des sous-spans pour chaque étape de vérification. Utilisez des attributs standards pour annoter les informations clés. Les données d'observabilité peuvent ainsi s'intégrer à des outils comme Jaeger ou Zipkin.++## Cas réel++Un harness avec workflow planner-generator-evaluator exécute « ajouter le support dark mode » :++**Version non observable** : 3-4 tours de retries aveugles, 45 minutes, résultat à peine acceptable. L'evaluator dit « ça ne semble pas juste » sans pouvoir préciser. Le generator gaspille beaucoup de temps dans de mauvaises directions.++**Version entièrement observable** :+- Le sprint contract clarifie scope, standards et exclusions+- Les traces runtime enregistrent le chargement des styles de chaque composant+- La grille fournit une évaluation structurée dimension par dimension+- Une itération produit des résultats de haute qualité en 15 minutes++Amélioration d'efficacité de 3x, qualité plus stable, évaluations reproductibles.++## Points clés++- **L'observabilité est une propriété d'architecture du harness**, pas une fonctionnalité ajoutée après coup.+- **Les deux couches d'observabilité sont essentielles** : les signaux runtime expliquent « ce qui s'est passé », les artefacts de processus expliquent « pourquoi cela a été fait ainsi ».+- **Les sprint contracts alignent en amont**, évitant qu'un generator construise quelque chose que l'evaluator rejette immédiatement pour des raisons prévisibles.+- **Les grilles rendent l'évaluation reproductible**, différents évaluateurs produisant des scores proches pour le même résultat.+- **Le manque d'observabilité gaspille 30-50 % du temps de session en diagnostic redondant.**++## Pour aller plus loin++- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — cadre théorique et pratique pour l'observability engineering moderne+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — pratique fondatrice du tracing distribué à grande échelle+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — introduction des sprint contracts et grilles d'évaluation+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — application systématique de l'observabilité en production++## Exercices++1. **Analyse du déficit d'observabilité** : auditez votre harness actuel sur les couches système et processus. Trouvez les états impossibles à distinguer avec les signaux existants et proposez des ajouts.++2. **Pratique du sprint contract** : rédigez un sprint contract pour une tâche réelle. Faites exécuter l'agent selon le contrat et comparez efficacité et qualité avec et sans contrat.++3. **Construction de trace de tâche** : enregistrez chaque étape des opérations d'un agent pendant une tâche complète. Annotez avec les conventions sémantiques OpenTelemetry et analysez les goulets d'information.diff --git a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.mdnew file mode 100644index 0000000..957db26--- /dev/null+++ b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md@@ -0,0 +1,18 @@+# Modèle de Comparaison de Benchmark++Harness A :++- taux d'achèvement+- tentatives moyennes+- bugs détectés avant revue humaine++Harness B :++- taux d'achèvement+- tentatives moyennes+- bugs détectés avant revue humaine++Interprétation :++- Quel harness a changé le résultat ?+- Quel harness a changé le coût pour obtenir le résultat ?diff --git a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.tsnew file mode 100644index 0000000..0388cad--- /dev/null+++ b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts@@ -0,0 +1,216 @@+/**+ * benchmark-runner.ts+ *+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),+ * "executes" each task, records timing and pass/fail, outputs a comparison+ * report showing which tasks pass and which fail.+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BenchmarkTask {+ id: string;+ name: string;+ category: string;+ passCriteria: string[];+ expectedDurationMs: number;+ // Simulated actual results+ actualDurationMs: number;+ actualPass: boolean;+ failureReason?: string;+}++interface BenchmarkResult {+ id: string;+ name: string;+ category: string;+ criteriaTotal: number;+ criteriaPassed: number;+ pass: boolean;+ expectedMs: number;+ actualMs: number;+ durationDelta: number;+ failureReason?: string;+}++// ---------------------------------------------------------------------------+// Benchmark task definitions+// ---------------------------------------------------------------------------++const benchmarkTasks: BenchmarkTask[] = [+ {+ id: "bench-001",+ name: "Import markdown document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 100,+ actualDurationMs: 95,+ actualPass: true,+ },+ {+ id: "bench-002",+ name: "Import PDF document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 200,+ actualDurationMs: 310,+ actualPass: false,+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",+ },+ {+ id: "bench-003",+ name: "Ask grounded question",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],+ expectedDurationMs: 500,+ actualDurationMs: 480,+ actualPass: true,+ },+ {+ id: "bench-004",+ name: "Ask question with no relevant docs",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],+ expectedDurationMs: 400,+ actualDurationMs: 420,+ actualPass: false,+ failureReason: "Model hallucinated a citation instead of saying 'no results'",+ },+ {+ id: "bench-005",+ name: "Delete imported document",+ category: "Document Pipeline",+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],+ expectedDurationMs: 150,+ actualDurationMs: 145,+ actualPass: true,+ },+ {+ id: "bench-006",+ name: "Concurrent user access",+ category: "Security",+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],+ expectedDurationMs: 300,+ actualDurationMs: 850,+ actualPass: false,+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",+ },+ {+ id: "bench-007",+ name: "Session continuity after restart",+ category: "Reliability",+ passCriteria: ["State persisted", "Session recovers", "No data loss"],+ expectedDurationMs: 200,+ actualDurationMs: 180,+ actualPass: true,+ },+ {+ id: "bench-008",+ name: "API rate limiting",+ category: "Security",+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],+ expectedDurationMs: 100,+ actualDurationMs: 100,+ actualPass: true,+ },+];++// ---------------------------------------------------------------------------+// Execution simulation+// ---------------------------------------------------------------------------++function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {+ return tasks.map((task) => ({+ id: task.id,+ name: task.name,+ category: task.category,+ criteriaTotal: task.passCriteria.length,+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),+ pass: task.actualPass,+ expectedMs: task.expectedDurationMs,+ actualMs: task.actualDurationMs,+ durationDelta: task.actualDurationMs - task.expectedDurationMs,+ failureReason: task.failureReason,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(100));+ console.log(" BENCHMARK RUNNER -- Task Execution Report");+ console.log("=".repeat(100));++ const results = executeBenchmark(benchmarkTasks);++ // Detailed results+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;+ console.log("\n" + header);+ console.log(sep);++ for (const r of results) {+ const passLabel = r.pass ? "PASS" : "FAIL";+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;+ const marker = r.pass ? " " : ">>";++ console.log(+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`+ );+ }++ // Failure details+ const failures = results.filter((r) => !r.pass);+ if (failures.length > 0) {+ console.log("\n" + "-".repeat(100));+ console.log(" FAILURE DETAILS");+ console.log("-".repeat(100));+ for (const f of failures) {+ console.log(`\n [${f.id}] ${f.name}`);+ console.log(` Category: ${f.category}`);+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);+ }+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SUMMARY BY CATEGORY");+ console.log("=".repeat(100) + "\n");++ const categories = [...new Set(results.map((r) => r.category))];+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;+ console.log(catHeader);+ console.log(catSep);++ for (const cat of categories) {+ const catResults = results.filter((r) => r.category === cat);+ const catPassed = catResults.filter((r) => r.pass).length;+ const catFailed = catResults.filter((r) => !r.pass).length;+ const rate = Math.round((catPassed / catResults.length) * 100);++ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);+ }++ // Overall+ const totalPassed = results.filter((r) => r.pass).length;+ const totalFailed = results.filter((r) => !r.pass).length;+ console.log("\n" + "-".repeat(100));+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);+ console.log("=".repeat(100) + "\n");+}++run();diff --git a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdnew file mode 100644index 0000000..a3ababe--- /dev/null+++ b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -0,0 +1,9 @@+# Exemple de Boucle de Nettoyage++Tâches de nettoyage récurrentes :++- scanner les docs obsolètes+- scanner les violations structurelles+- mettre à jour les notes de qualité+- ouvrir des PR de nettoyage ciblées+- réexécuter une tranche de benchmark fixe après le nettoyagediff --git a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.tsnew file mode 100644index 0000000..6b35905--- /dev/null+++ b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts@@ -0,0 +1,336 @@+/**+ * cleanup-scanner.ts+ *+ * Scans a project directory for stale artifacts, dead code, structural+ * violations, and outputs a cleanup report. Helps enforce the "clean state+ * at end of every session" principle.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]+ * (defaults to current working directory)+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface ScanResult {+ category: string;+ check: string;+ severity: "critical" | "warning" | "info";+ found: string[];+ description: string;+}++// ---------------------------------------------------------------------------+// Scanner checks+// ---------------------------------------------------------------------------++interface ScannerCheck {+ category: string;+ name: string;+ severity: "critical" | "warning" | "info";+ description: string;+ scan: (dir: string) => string[];+}++function createChecks(): ScannerCheck[] {+ return [+ {+ category: "Stale Artifacts",+ name: "Temporary files (*.tmp, *.bak, *.swp)",+ severity: "warning",+ description: "Leftover temp files from editing or processing",+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),+ },+ {+ category: "Stale Artifacts",+ name: "Debug/log files in source",+ severity: "warning",+ description: "Log files that should not be in the source tree",+ scan: (dir) => {+ const found: string[] = [];+ const logPatterns = [".log"];+ for (const p of findFiles(dir, logPatterns)) {+ // Only flag log files in source directories+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {+ found.push(p);+ }+ }+ return found;+ },+ },+ {+ category: "Dead Code",+ name: "Unused imports (placeholder detection)",+ severity: "info",+ description: "Files that may contain unused code (heuristic scan)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app"];+ for (const srcDir of srcDirs) {+ const srcPath = path.join(dir, srcDir);+ if (fs.existsSync(srcPath)) {+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "Missing .gitignore",+ severity: "warning",+ description: "No .gitignore file found -- risk of committing build artifacts",+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],+ },+ {+ category: "Structural Violations",+ name: "Build artifacts in source",+ severity: "critical",+ description: "Compiled output (dist/, build/) mixed with source",+ scan: (dir) => {+ const found: string[] = [];+ // Check if dist/ or build/ exists inside src/+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];+ for (const d of dirs) {+ if (fs.existsSync(path.join(dir, d))) {+ found.push(d + "/");+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "node_modules in source tree",+ severity: "critical",+ description: "node_modules directory found outside root (nested dependency)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app", "test", "tests"];+ for (const srcDir of srcDirs) {+ const nmPath = path.join(dir, srcDir, "node_modules");+ if (fs.existsSync(nmPath)) {+ found.push(srcDir + "/node_modules/");+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Uncommitted changes indicator",+ severity: "info",+ description: "Checks for common artifacts of incomplete sessions",+ scan: (dir) => {+ const found: string[] = [];+ const indicators = [+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",+ "debug.ts", "test-manual.ts", "temp.ts",+ ];+ for (const f of indicators) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Empty directories",+ severity: "info",+ description: "Empty directories that may be leftover from incomplete work",+ scan: (dir) => {+ const found: string[] = [];+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];+ for (const d of commonDirs) {+ const dp = path.join(dir, d);+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {+ try {+ const contents = fs.readdirSync(dp);+ if (contents.length === 0) {+ found.push(d + "/");+ }+ } catch {+ // Skip directories we can't read+ }+ }+ }+ return found;+ },+ },+ {+ category: "Configuration",+ name: "Environment files in source",+ severity: "critical",+ description: ".env files that may contain secrets",+ scan: (dir) => {+ const found: string[] = [];+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];+ for (const f of envFiles) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ ];+}++// ---------------------------------------------------------------------------+// Helper functions+// ---------------------------------------------------------------------------++function findFiles(dir: string, extensions: string[]): string[] {+ const found: string[] = [];++ function walk(current: string, depth: number): void {+ if (depth > 4) return; // Limit recursion depth+ try {+ const entries = fs.readdirSync(current, { withFileTypes: true });+ for (const entry of entries) {+ // Skip common non-source directories+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {+ continue;+ }++ const fullPath = path.join(current, entry.name);+ const relativePath = path.relative(dir, fullPath);++ if (entry.isDirectory()) {+ walk(fullPath, depth + 1);+ } else if (entry.isFile()) {+ if (extensions.some((ext) => entry.name.endsWith(ext))) {+ found.push(relativePath);+ }+ }+ }+ } catch {+ // Skip directories we can't read+ }+ }++ walk(dir, 0);+ return found;+}++function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {+ try {+ const entries = fs.readdirSync(dir, { withFileTypes: true });+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);+ }+ continue;+ }++ const fullPath = path.join(dir, entry.name);+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {+ continue;+ }++ try {+ const content = fs.readFileSync(fullPath, "utf-8");+ const lines = content.split("\n");+ for (let i = 0; i < Math.min(lines.length, 50); i++) {+ for (const pattern of patterns) {+ if (lines[i].includes(pattern)) {+ const relative = path.relative(baseDir, fullPath);+ results.push(`${relative}:${i + 1} contains ${pattern}`);+ }+ }+ }+ } catch {+ // Skip files we can't read+ }+ }+ } catch {+ // Skip directories we can't read+ }+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");+ console.log("=".repeat(90));+ console.log(` Scanning: ${targetDir}\n`);++ const checks = createChecks();+ const results: ScanResult[] = [];++ for (const check of checks) {+ const found = check.scan(targetDir);+ results.push({+ category: check.category,+ check: check.name,+ severity: check.severity,+ found,+ description: check.description,+ });+ }++ // Report+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const count = r.found.length;+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";++ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);+ }++ // Summary+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);+ const clean = results.filter((r) => r.found.length === 0);++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SUMMARY");+ console.log("=".repeat(90) + "\n");++ console.log(` Critical issues: ${criticals.length}`);+ console.log(` Warnings: ${warnings.length}`);+ console.log(` Info items: ${infos.length}`);+ console.log(` Clean checks: ${clean.length}/${results.length}`);++ if (criticals.length > 0) {+ console.log("\n ACTION REQUIRED (Critical):");+ for (const c of criticals) {+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);+ console.log(` ${c.description}`);+ }+ }++ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);+ if (totalIssues === 0) {+ console.log("\n Project is in a clean state. No issues found.\n");+ } else {+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);+ }+}++run();diff --git a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdnew file mode 100644index 0000000..4aa8679--- /dev/null+++ b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md@@ -0,0 +1,8 @@+# Code du Cours 12++Utilisez ce dossier pour des exemples de :++- tranches de benchmark+- tâches de nettoyage+- exemples de réduction d'entropie+- exécutions de harness reproductiblesdiff --git a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdnew file mode 100644index 0000000..0106296--- /dev/null+++ b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -0,0 +1,186 @@+[中文版本 →](../../../zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)++> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)+> Projet pratique : [Project 06. Complete harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# Leçon 12. Laisser un handoff propre à la fin de chaque session++## Quel problème cette leçon résout-elle ?++Votre agent travaille tout l'après-midi, modifie 20 fichiers, commite le code, la session se termine. La prochaine session d'agent démarre et découvre immédiatement : le build est cassé, les tests sont rouges, des fichiers de debug temporaires sont partout, la feature list n'a pas été mise à jour, et l'avancement est totalement flou. La nouvelle session passe ses 30 premières minutes juste à comprendre « ce que la session précédente a réellement fait. »++OpenAI et Anthropic le disent clairement : **la fiabilité à long terme dépend de la discipline opérationnelle, pas seulement du succès d'une exécution unique.** La qualité de l'état à la sortie de la session détermine directement l'efficacité de la session suivante. Pensez aux bonnes pratiques Git — chaque commit devrait être un changement atomique et compilable, pas un tas de code à moitié fini.++## Concepts clés++- **État propre (clean state)** : Le système satisfait cinq conditions à la fin de la session — le build passe, les tests passent, l'avancement est enregistré, aucun artefact périmé, le chemin de démarrage est disponible. S'il en manque une seule, la session n'est pas « terminée ».+- **Intégrité de session** : Analogue aux transactions de base de données — soit on commit entièrement et on laisse un état propre, soit on revient au dernier état cohérent. Pas de terrain d'entente.+- **Document de qualité** : Un artefact actif qui enregistre en continu les notes de qualité de chaque module. Pas une évaluation ponctuelle, mais un suivi montrant si la base de code se renforce ou s'affaiblit au fil du temps.+- **Boucle de nettoyage** : Une session de maintenance régulière visant à réduire systématiquement l'entropie dans la base de code. Pas un correctif d'urgence, mais des opérations de routine.+- **Simplification du harness** : À mesure que les capacités du modèle s'améliorent, retirer périodiquement les composants du harness qui ne sont plus nécessaires. Une contrainte essentielle aujourd'hui peut être une surcharge inutile dans trois mois.+- **Nettoyage idempotent** : Les opérations de nettoyage produisent le même résultat quel que soit le nombre de fois où elles sont exécutées. Garantit que le nettoyage reste sûr même dans les scénarios de tentative après échec.++## Cinq dimensions de l'état propre++```mermaid+flowchart LR+ Work["Feature work complete"] --> Build{"Build passes?"}+ Build -->|yes| Test{"Tests pass?"}+ Build -->|no| Fix["Fix before exit"]+ Test -->|yes| Record["Update feature list + progress"]+ Test -->|no| Fix+ Record --> Cleanup["Remove temp artifacts / debug code"]+ Cleanup --> Startup{"Standard startup path works?"}+ Startup -->|yes| Clean["Clean handoff"]+ Startup -->|no| Fix+ Fix --> Build+```++```mermaid+flowchart LR+ Dirty["Session ends with<br/>red tests / temp files / no progress update"] --> Diagnose["Next session first has to<br/>figure out what happened"]+ Diagnose --> Fragile["New work starts on a messy repo"]+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]+ More --> Dirty++ Clean["Session ends with<br/>green tests / updated progress / temp files removed"] --> Fast["Next session can start coding immediately"]+ Fast --> Stable["No need to rescue the repo first"]+ Stable --> Clean+```++## Pourquoi cela arrive++### La croissance de l'entropie est l'état par défaut++Les lois de Lehman sur l'évolution logicielle nous disent : les systèmes soumis à des changements continus augmenteront inévitablement en complexité s'ils ne sont pas activement gérés. C'est particulièrement vrai pour les agents de codage IA — chaque session introduit des changements, et sans nettoyage à la sortie, la dette technique s'accumule de manière exponentielle.++Les données réelles sont éloquentes. Un projet développé avec des agents pendant 12 semaines, sans stratégie de nettoyage :++- Semaine 1 : Taux de réussite du build 100 %, taux de réussite des tests 100 %, démarrage de nouvelle session 5 min+- Semaine 4 : Build 95 %, tests 92 %, démarrage 15 min+- Semaine 8 : Build 82 %, tests 78 %, démarrage 35 min+- Semaine 12 : Build 68 %, tests 61 %, démarrage 60+ min++Le même projet avec une stratégie de nettoyage :++- Semaine 1 : 100 %, 100 %, 5 min+- Semaine 12 : 97 %, 95 %, 9 min++Après 12 semaines : le taux de réussite du build diffère de 29 points de pourcentage, le temps de démarrage d'une nouvelle session diffère de 85 %. Ce n'est pas théorique — c'est une différence observée.++### Les cinq dimensions de l'état propre++L'état propre, ce n'est pas juste « le code compile ». C'est cinq dimensions évaluées ensemble :++**Dimension build** : Le code se compile-t-il sans erreurs ? C'est le minimum — la prochaine session ne devrait pas avoir à corriger des erreurs de build en premier.++**Dimension tests** : Tous les tests passent-ils ? Y compris les tests qui existaient avant la session — la session est responsable de ne pas casser les fonctionnalités existantes. Et cela devrait être vérifié dans le CI, pas juste « ça marche chez moi ».++**Dimension avancement** : L'avancement actuel est-il enregistré dans un artefact lisible par machine ? Sous-tâches terminées avec leurs critères de réussite, sous-tâches en cours mais incomplètes avec leur état actuel, sous-tâches non encore commencées. De bons enregistrements d'avancement réduisent de 60 à 80 % le temps de diagnostic au démarrage d'une session.++**Dimension artefacts** : Y a-t-il des artefacts temporaires périmés ou ambigus ? Logs de debug, fichiers temporaires, code commenté, marqueurs TODO — tous ces éléments augmentent la charge cognitive pour la prochaine session.++**Dimension démarrage** : Le chemin de démarrage standard est-il disponible ? La prochaine session peut-elle commencer à travailler sans intervention manuelle ? Initialisation de l'environnement, chargement de la base de code, acquisition du contexte, sélection de la tâche — ces chemins ne doivent pas être cassés.++### « Nettoyer plus tard » signifie ne jamais nettoyer++Le piège mental le plus courant est « pas le temps de nettoyer cette session, je le ferai la prochaine fois ». Mais la prochaine session d'agent ne sait pas ce que vous avez laissé derrière — elle voit un code en désordre et un état incertain. Elle passera un temps significatif à déduire « quelles parties de ce code sont intentionnelles et lesquelles sont temporaires ».++Pire, chaque session a ses propres objectifs de tâche. La nouvelle session est là pour faire du nouveau travail, pas nettoyer le désordre de la session précédente. Elle ignorera le chaos et commencera un nouveau travail par-dessus, introduisant plus de chaos sur du chaos. C'est la boucle de retour positif de l'entropie.++## Comment bien le faire++### 1. L'état propre comme condition d'achèvement++Définissez explicitement dans le harness : **achèvement de la session = la tâche passe la vérification ET la vérification d'état propre passe.** S'il manque l'un ou l'autre, la session n'est pas terminée. Écrivez dans CLAUDE.md :++```+## Session Exit Checklist+- [ ] Build passes (npm run build)+- [ ] All tests pass (npm test)+- [ ] Feature list updated+- [ ] No debug code remaining (console.log, debugger, TODO)+- [ ] Standard startup path available (npm run dev)+```++### 2. Stratégie de nettoyage en double mode++Combinez deux modes de nettoyage :++**Nettoyage immédiat (à la fin de chaque session)** : Nettoyer les artefacts temporaires créés pendant la session, mettre à jour l'état de la feature list, s'assurer que le build et les tests passent. C'est le nettoyage par « comptage de références ».++**Nettoyage périodique (hebdomadaire)** : Scan complet du système — traiter les problèmes structurels accumulés, mettre à jour les documents de qualité, lancer des tests de référence pour dététecter les dérives. C'est le nettoyage par « traçage ».++### 3. Maintenir un document de qualité++Un document de qualité est un artefact actif qui note en continu chaque module :++```markdown+# Quality Document++## User Authentication Module (Quality: A)+- Verification passing: Yes+- Agent understandable: Yes+- Test stability: Stable+- Architecture boundaries: Compliant+- Code conventions: Followed++## Payment Module (Quality: C)+- Verification passing: Partial (payment callback untested)+- Agent understandable: Difficult (logic spread across 3 files)+- Test stability: Unstable (2 flaky tests)+- Architecture boundaries: Violations present+- Code conventions: Partially followed+```++Les nouvelles sessions lisent ce document et savent immédiatement où prioriser. Corriger d'abord le module avec la note la plus basse.++### 4. Simplifier périodiquement le harness++Une insight importante d'Anthropic : **chaque composant du harness existe parce que le modèle ne peut pas faire quelque chose de manière fiable par lui-même. Mais à mesure que les modèles s'améliorent, ces hypothèses deviennent obsolètes.** Une contrainte essentielle il y a trois mois peut être une surcharge inutile aujourd'hui.++Pratique recommandée : Chaque mois, choisissez un composant du harness, désactivez-le temporairement, et lancez des tâches de référence. Si les résultats ne se dégradent pas, retirez-le définitivement. S'ils se dégradent, restaurez-le ou remplacez-le par une alternative plus légère.++### 5. Les opérations de nettoyage doivent être idempotentes++Les scripts de nettoyage devraient être sûrs à exécuter de manière répétée :++```bash+# Idempotent cleanup operations+rm -f /tmp/debug-*.log # -f ensures no error when files don't exist+git checkout -- .env.local # Restore to known state+npm run test # Verify cleanup didn't break anything+```++## Cas concret++Une application Electron développée avec des agents sur 12 semaines, comparant deux approches :++**Sans stratégie de nettoyage** (groupe de contrôle) : Semaine 12, taux de réussite du build 68 %, taux de réussite des tests 61 %, démarrage de nouvelle session 60+ min, artefacts périmés 103.++**Avec stratégie de nettoyage** (groupe expérimental) : Vérification complète d'état propre à chaque fin de session + boucle de nettoyage hebdomadaire. Semaine 12, taux de réussite du build 97 %, taux de réussite des tests 95 %, démarrage de nouvelle session 9 min, artefacts périmés 11.++À la semaine 12, le taux de réussite du build du groupe expérimental est de 29 points de pourcentage plus élevé, le taux de réussite des tests de 34 points plus élevé, et le temps de démarrage d'une nouvelle session réduit de 85 %.++## Points clés++- **L'état propre est une condition nécessaire à l'achèvement de la session** — pas du ménage optionnel, mais partie intégrante de la « définition du fini ».+- **Les cinq dimensions sont toutes requises** — build, tests, avancement, artefacts, démarrage — chacune doit être vérifiée explicitement.+- **Les documents de qualité rendent la santé de la base de code traçable** — on ne peut corriger que ce qu'on sait se dégrader.+- **Simplifier périodiquement le harness** — à mesure que les capacités du modèle s'améliorent, retirer les contraintes devenues inutiles.+- **« Nettoyer plus tard » équivaut à ne jamais nettoyer** — la croissance de l'entropie est la norme ; seul un nettoyage actif la contrecarre.++## Pour aller plus loin++- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — Principes systématiques de propreté du code+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — La reproductibilité comme exigence fondamentale de la conception du harness+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Le rôle critique des sorties de session propres pour la fiabilité à long terme+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — Les lois de l'évolution logicielle prouvant que la complexité du système croît inévitablement sans maintenance active++## Exercices++1. **Liste de contrôle d'état propre** : Concevez une liste de contrôle de sortie de session pour votre base de code couvrant les cinq dimensions. Appliquez-la sur 5 sessions consécutives et enregistrez les violations par dimension.++2. **Comparaison de référence** : Utilisez un ensemble de tâches fixe avec deux variantes de harness (avec/sans exigences d'état propre). Comparez le taux de complétion, le nombre de tentatives et le taux de fuite de défauts.++3. **Pratique de simplification du harness** : Choisissez un composant du harness, désactivez-le temporairement, et lancez des tâches de référence. Comparez les résultats avec et sans celui-ci. Décidez de le conserver, le retirer ou le remplacer.diff --git a/docs/fr/projects/index.md b/docs/fr/projects/index.mdnew file mode 100644index 0000000..9777ba6--- /dev/null+++ b/docs/fr/projects/index.md@@ -0,0 +1,23 @@+# Bienvenue dans les projets++Voici la section pratique de Learn Harness Engineering. Lire les leçons ne suffit pas : vous devez construire vous-même les environnements et observer comment Codex, Claude Code ou d'autres agents IA se comportent sous différentes règles.++## Vue d'ensemble++Le cours propose 6 projets pratiques et progressifs qui vous apprennent à construire de zéro un environnement agentique fiable :++1. **Prompt seul vs règles d'abord** : comparer les résultats d'un agent avec un simple prompt et avec un harness de base.+2. **Workspace lisible par l'agent** : structurer le dépôt pour l'IA et établir des mécanismes de handoff.+3. **Continuité multi-session** : concevoir des fichiers d'état et des scripts d'initialisation pour reprendre le travail entre sessions.+4. **Feedback runtime et contrôle du scope** : introduire des outils permettant à l'agent de tester son code et de corriger les erreurs pendant l'exécution.+5. **Auto-vérification et séparation des rôles** : construire un mécanisme de revue indépendant pour éviter les hallucinations et les déclarations de réussite trop précoces.+6. **Harness complet (capstone)** : assembler un environnement final, observable et end-to-end pour le travail agentique.++## Comment avancer++Chaque dossier de projet contient généralement :+- `starter/` : votre workspace de départ.+- `solution/` : une implémentation de référence si vous êtes bloqué.+- Des consignes décrivant le contexte et les objectifs précis.++Utilisez votre AI Coding Agent préféré, par exemple Claude Code, Cursor ou Trae, pour réaliser les tâches dans le répertoire `starter/`.diff --git a/docs/fr/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/fr/projects/project-01-baseline-vs-minimal-harness/index.mdnew file mode 100644index 0000000..e8bf081--- /dev/null+++ b/docs/fr/projects/project-01-baseline-vs-minimal-harness/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-01-baseline-vs-minimal-harness/)++> Leçons liées : [Leçon 01. Les modèles forts ne garantissent pas une exécution fiable](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [Leçon 02. Ce que signifie vraiment harness](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)+> Fichiers modèles : [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/resources/templates/)++# Projet 01. Prompt seul vs règles d'abord : quelle différence cela fait-il ?++## Ce que vous faites++Construisez le squelette minimal d'une application Electron de base de connaissances : une fenêtre avec une liste de documents à gauche, un panneau Q&A à droite et un dossier de données local. La tâche elle-même n'est pas complexe. Ce qui est complexe, c'est la manière de faire en sorte que l'agent la termine.++Vous l'exécutez deux fois. Première fois : seulement un prompt, sans préparation. Deuxième fois : `AGENTS.md`, `init.sh` et `feature_list.json` déjà placés dans le dépôt. Ensuite, comparez.++Le cœur de ce projet n'est pas d'écrire du code, mais de mesurer l'écart entre "passer 15 minutes à préparer les règles" et "laisser simplement l'agent partir".++## Outils++- Claude Code ou Codex (choisissez-en un et gardez-le pour les deux exécutions)+- Git (gérer les branches et comparer)+- Node.js + Electron (stack du projet)+- Un minuteur (noter la durée de chaque exécution)++## Mécanisme de harness++Harness minimal : `AGENTS.md` + `init.sh` + `feature_list.json`diff --git a/docs/fr/projects/project-02-agent-readable-workspace/index.md b/docs/fr/projects/project-02-agent-readable-workspace/index.mdnew file mode 100644index 0000000..b5903df--- /dev/null+++ b/docs/fr/projects/project-02-agent-readable-workspace/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-02-agent-readable-workspace/)++> Leçons liées : [Leçon 03. Faire du dépôt votre source de vérité unique](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [Leçon 04. Répartir les instructions entre plusieurs fichiers](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+> Fichiers modèles : [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/resources/templates/)++# Projet 02. Rendre le projet lisible et reprendre là où vous vous êtes arrêté++## Ce que vous faites++Ajoutez de la "lisibilité" au dépôt pour qu'un nouvel agent comprenne rapidement la structure du projet, connaisse l'avancement actuel et reprenne le travail. Concrètement : implémentez l'import de documents, la vue de détail et la persistance locale, en deux sessions.++Vous l'exécutez deux fois : d'abord sans aide, puis avec `ARCHITECTURE.md`, `PRODUCT.md` et `session-handoff.md` déjà placés dans le dépôt.++## Outils++- Claude Code ou Codex+- Git+- Node.js + Electron++## Mécanisme de harness++Workspace lisible par l'agent + fichiers d'état persistantsdiff --git a/docs/fr/projects/project-03-multi-session-continuity/index.md b/docs/fr/projects/project-03-multi-session-continuity/index.mdnew file mode 100644index 0000000..1c0cfd5--- /dev/null+++ b/docs/fr/projects/project-03-multi-session-continuity/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-03-multi-session-continuity/)++> Leçons liées : [Leçon 05. Garder le contexte vivant entre les sessions](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [Leçon 06. Initialiser avant chaque session d'agent](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+> Fichiers modèles : [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/resources/templates/)++# Projet 03. Garder l'agent au travail après les redémarrages de session++## Ce que vous faites++Ajoutez un contrôle de scope et des portes de vérification à l'agent. Implémentez le découpage de documents, l'extraction de métadonnées, l'affichage de progression d'indexation et un flux Q&A avec citations. Utilisez `feature_list.json` pour suivre l'état des fonctionnalités : une fonctionnalité à la fois, sans marquer `pass` sans preuve de vérification.++Vous l'exécutez deux fois : d'abord sans contraintes, puis avec application stricte.++## Outils++- Claude Code ou Codex+- Git+- Node.js + Electron++## Mécanisme de harness++Journal de progression + handoff de session + continuité multi-sessiondiff --git a/docs/fr/projects/project-04-incremental-indexing/index.md b/docs/fr/projects/project-04-incremental-indexing/index.mdnew file mode 100644index 0000000..fa79ba7--- /dev/null+++ b/docs/fr/projects/project-04-incremental-indexing/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-04-incremental-indexing/)++> Leçons liées : [Leçon 07. Définir des limites de tâche claires pour les agents](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [Leçon 08. Utiliser les listes de fonctionnalités pour contraindre ce que fait l'agent](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+> Fichiers modèles : [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/resources/templates/)++# Projet 04. Utiliser le feedback runtime pour corriger le comportement de l'agent++## Ce que vous faites++Ajoutez de l'observabilité runtime, comme les logs de démarrage, les logs d'import/indexation et les états d'erreur, ainsi que des contraintes d'architecture pour éviter les violations entre couches. Introduisez un bug runtime que l'agent devra corriger.++Vous l'exécutez deux fois : d'abord sans logs ni contraintes, puis avec les bons outils et règles.++## Outils++- Claude Code ou Codex+- Git+- Node.js + Electron++## Mécanisme de harness++Feedback runtime + contrôle du scope + indexation incrémentalediff --git a/docs/fr/projects/project-05-grounded-qa-verification/index.md b/docs/fr/projects/project-05-grounded-qa-verification/index.mdnew file mode 100644index 0000000..ecba516--- /dev/null+++ b/docs/fr/projects/project-05-grounded-qa-verification/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-05-grounded-qa-verification/)++> Leçons liées : [Leçon 09. Empêcher les agents de déclarer la victoire trop tôt](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [Leçon 10. Seule une exécution de pipeline complet compte comme vraie vérification](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+> Fichiers modèles : [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/resources/templates/)++# Projet 05. Faire vérifier son propre travail par l'agent++## Ce que vous faites++Implémentez la séparation des rôles : un generator qui implémente, un evaluator qui relit, et éventuellement un planner. Exécutez trois fois pour mesurer l'effet de chaque rôle ajouté.++Choisissez une amélioration substantielle de fonctionnalité, comme une conversation multi-tour, une refonte du panneau de citations ou un filtrage de documents, et gardez-la identique dans toutes les exécutions.++## Outils++- Claude Code ou Codex+- Git+- Node.js + Electron++## Mécanisme de harness++Auto-vérification + Q&A fondé sur des sources + finalisation basée sur des preuvesdiff --git a/docs/fr/projects/project-06-runtime-observability-and-debugging/index.md b/docs/fr/projects/project-06-runtime-observability-and-debugging/index.mdnew file mode 100644index 0000000..d6955ce--- /dev/null+++ b/docs/fr/projects/project-06-runtime-observability-and-debugging/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-06-runtime-observability-and-debugging/)++> Leçons liées : [Leçon 11. Rendre le runtime de l'agent observable](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [Leçon 12. Handoff propre à la fin de chaque session](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+> Fichiers modèles : [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/fr/resources/templates/)++# Projet 06. Construire un harness complet pour agents (capstone)++## Ce que vous faites++C'est le projet final. Assemblez tout ce qui a été appris dans les cinq premiers projets, exécutez un benchmark complet, puis faites une passe de nettoyage pour vérifier que la qualité reste maintenable.++Utilisez un ensemble fixe de tâches multi-fonctionnalités couvrant une tranche complète du produit : import de documents, indexation, Q&A avec citations, observabilité runtime et état de dépôt lisible et redémarrable. Lancez d'abord avec un baseline de harness faible, puis avec votre harness le plus fort, puis nettoyez et relancez. Enfin, réalisez une expérience d'ablation du harness : retirez un composant à la fois et voyez lesquels comptent vraiment.++## Outils++- Claude Code ou Codex+- Git+- Node.js + Electron+- Modèle de document qualité+- Grille d'évaluation+- Tous les composants de harness accumulés dans les cinq premiers projets++## Mécanisme de harness++Harness complet : tous les mécanismes + observabilité + étude d'ablationdiff --git a/docs/fr/resources/index.md b/docs/fr/resources/index.mdnew file mode 100644index 0000000..4662b4a--- /dev/null+++ b/docs/fr/resources/index.md@@ -0,0 +1,50 @@+# Bibliothèque de ressources en français++Ce dossier transforme les méthodes du cours en modèles prêts à copier et en références compactes utilisables dans un vrai dépôt.++## Quand l'utiliser++Commencez ici lorsque vous voulez que Codex, Claude Code ou un autre agent de codage travaille sur plusieurs sessions sans redécouvrir en permanence le setup, l'état et le scope.++C'est particulièrement utile lorsque :++- le travail s'étend sur plusieurs sessions+- les fonctionnalités sont nombreuses et faciles à laisser à moitié terminées+- les agents ont tendance à déclarer la victoire trop tôt+- les étapes de démarrage sont redécouvertes à chaque fois++## Commencer ici++Pour une configuration minimale, commencez avec :++- instructions racine : [`templates/AGENTS.md`](./templates/AGENTS.md) ou [`templates/CLAUDE.md`](./templates/CLAUDE.md)+- état des fonctionnalités : [`templates/feature_list.json`](./templates/feature_list.json)+- journal de progression : [`templates/claude-progress.md`](./templates/claude-progress.md)+- référence du script de bootstrap : `docs/fr/resources/templates/init.sh`++Ajoutez ensuite :++- handoff de session : [`templates/session-handoff.md`](./templates/session-handoff.md)+- checklist de sortie propre : [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)+- grille d'évaluation : [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)++Si vous voulez une structure de dépôt plus complète, proche de l'article OpenAI "Harness engineering", utilisez le pack avancé :++- [`openai-advanced/index.md`](./openai-advanced/index.md)++## Structure de la bibliothèque++- [`templates/`](./templates/index.md) : modèles à copier dans un vrai dépôt+- [`reference/`](./reference/index.md) : notes de méthode, flux de démarrage et cartes des modes de défaillance+- [`openai-advanced/`](./openai-advanced/index.md) : squelette de dépôt avancé, documents system-of-record et modèles de gouvernance agent-first++## Pack minimal recommandé++- `AGENTS.md` ou `CLAUDE.md`+- `feature_list.json`+- `claude-progress.md`+- `init.sh`++Ces quatre fichiers suffisent à rendre la plupart des workflows d'agents nettement plus stables.++Lorsque le dépôt devient un système durable avec plusieurs domaines, des plans actifs, une notation qualité et des politiques de fiabilité, passez au pack [`openai-advanced/`](./openai-advanced/index.md) au lieu d'étirer trop loin le pack minimal.diff --git a/docs/fr/resources/openai-advanced/index.md b/docs/fr/resources/openai-advanced/index.mdnew file mode 100644index 0000000..9e1bf76--- /dev/null+++ b/docs/fr/resources/openai-advanced/index.md@@ -0,0 +1,79 @@+# Pack Avancé OpenAI++Ce dossier empaquette la structure de dépôt plus opiniâtre décrite dans+l'article d'OpenAI "Harness engineering: leveraging Codex in an agent-first world"+en fichiers de démarrage prêts à copier.++Utilisez ce pack lorsque le harness minimal ne suffit plus et que votre dépôt+a maintenant besoin de :++- un `AGENTS.md` court de style routeur+- des docs durables de système d'enregistrement dans le dépôt+- des plans d'exécution actifs et terminés+- des fichiers de politique explicites pour produit, fiabilité, sécurité et frontend+- un scoring qualité par domaine produit et couche architecturale+- des dossiers de matériel de référence adapté aux modèles+- des procédures opérationnelles standard pour l'architecture, la capture de connaissances et la validation d'exécution++## Mise en Page de Démarrage Incluse++Le pack de démarrage dans [`repo-template/`](./repo-template/index.md) reflète+la structure suivante :++```text+AGENTS.md+ARCHITECTURE.md+docs/+├── design-docs/+│ ├── index.md+│ └── core-beliefs.md+├── exec-plans/+│ ├── active/+│ ├── completed/+│ └── tech-debt-tracker.md+├── generated/+│ └── db-schema.md+├── product-specs/+│ ├── index.md+│ └── new-user-onboarding.md+├── references/+│ ├── design-system-reference-llms.txt+│ ├── nixpacks-llms.txt+│ └── uv-llms.txt+├── DESIGN.md+├── FRONTEND.md+├── PLANS.md+├── PRODUCT_SENSE.md+├── QUALITY_SCORE.md+├── RELIABILITY.md+└── SECURITY.md+```++## Comment l'Adopter++1. Commencez avec le pack minimal si votre dépôt est encore petit.+2. Copiez les fichiers dans [`repo-template/`](./repo-template/index.md) dans+ votre propre dépôt lorsque vous avez besoin d'une structure plus forte.+3. Gardez `AGENTS.md` court. Traitez-le comme un routeur vers les docs plus profonds, pas comme une encyclopédie.+4. Mettez à jour les docs de qualité, fiabilité et plans dans le cadre du travail normal, pas comme un jour de nettoyage séparé.+5. Gardez les artefacts générés et les références externes explicites pour que les agents puissent les trouver sans dépendre de l'historique de chat.++## Bibliothèque de SOPs++Le dossier [`sops/`](./sops/index.md) transforme les diagrammes de l'article en+procédures opérationnelles étape par étape :++- configuration d'architecture de domaine en couches+- encodage de connaissances inédites dans le dépôt+- stack d'observabilité locale et flux de travail de boucle de retour+- boucle de validation Chrome DevTools pour le travail UI++## Principes de Conception++- Point d'entrée court, docs plus profonds liés+- Dépôt comme système d'enregistrement+- Les vérifications mécaniques优于 les règles mémorisées+- Les plans et l'historique qualité vivent à côté du code+- Le nettoyage et la simplification sont des responsabilités de premier plan++Ce pack est intentionnellement opiné, mais doit être adapté à votre projet plutôt que copié aveuglément.diff --git a/docs/fr/resources/openai-advanced/repo-template/AGENTS.md b/docs/fr/resources/openai-advanced/repo-template/AGENTS.mdnew file mode 100644index 0000000..17c0e43--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/AGENTS.md@@ -0,0 +1,61 @@+# AGENTS.md++Ce dépôt est optimisé pour le travail des agents de codage longue durée. Gardez ce fichier+court. Utilisez-le comme couche de routage vers les documents du système de référence,+et non comme un dump géant d'instructions.++## Flux de démarrage++Avant de modifier le code :++1. Confirmez la racine du dépôt avec `pwd`.+2. Lisez `ARCHITECTURE.md` pour la carte actuelle du système et les règles strictes de dépendance.+3. Lisez `docs/QUALITY_SCORE.md` pour voir quels domaines ou couches sont les plus faibles.+4. Lisez `docs/PLANS.md`, puis ouvrez le plan actif sur lequel vous travaillez.+5. Lisez la spécification produit pertinente dans `docs/product-specs/`.+6. Exécutez le chemin standard d'amorçage et de vérification pour ce dépôt.+7. Si la vérification de base échoue, réparez la ligne de base avant d'ajouter du périmètre.++## Carte de routage++- `ARCHITECTURE.md` : carte des domaines, modèle de couches, règles de dépendance+- `docs/design-docs/index.md` : décisions de conception et croyances fondamentales+- `docs/product-specs/index.md` : comportements actuels du produit et critères d'acceptation+- `docs/PLANS.md` : cycle de vie des plans et politique des plans d'exécution+- `docs/QUALITY_SCORE.md` : santé des domaines produit et des couches+- `docs/RELIABILITY.md` : signaux d'exécution, benchmarks et attentes de redémarrage+- `docs/SECURITY.md` : secrets, sandbox, données et règles d'actions externes+- `docs/FRONTEND.md` : contraintes UI, règles du système de design, vérifications d'accessibilité++## Contrat de travail++- Travaillez à partir d'un plan délimité ou d'une tranche de fonctionnalité à la fois.+- Ne marquez pas le travail comme terminé par simple inspection du code ; une preuve+ exécutable est requise.+- Si vous modifiez un comportement, mettez à jour les documents produit, plan ou fiabilité+ correspondants dans la même session.+- Si vous observez des retours de revue répétés, promouvez-les en une règle mécanique,+ un contrôle ou un linter plutôt que de les réexpliquer dans le chat.+- Gardez le contenu généré dans `docs/generated/` et les références sources dans+ `docs/references/`.+- Préférez ajouter de petits documents à jour plutôt que de faire grossir ce fichier.++## Définition de « terminé »++Une modification n'est terminée que lorsque toutes les conditions suivantes sont remplies :++- le comportement cible est implémenté+- la vérification requise a réellement été exécutée+- la preuve est liée depuis le plan ou le document de qualité pertinent+- les documents affectés restent à jour+- le dépôt peut redémarrer proprement depuis le chemin de démarrage standard++## Fin de session++Avant de terminer une session :++1. Mettez à jour le plan d'exécution actif.+2. Mettez à jour `docs/QUALITY_SCORE.md` si un domaine ou une couche a changé de manière significative.+3. Enregistrez la nouvelle dette dans `docs/exec-plans/tech-debt-tracker.md` si vous l'avez différée.+4. Déplacez les plans terminés vers `docs/exec-plans/completed/` si approprié.+5. Laissez le dépôt dans un état redémarrable avec une prochaine action claire.diff --git a/docs/fr/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/fr/resources/openai-advanced/repo-template/ARCHITECTURE.mdnew file mode 100644index 0000000..a4f6618--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -0,0 +1,63 @@+# ARCHITECTURE.md++Ce fichier est la carte de niveau supérieur du système. Il doit rester concis et+renvoyer vers des documents plus détaillés si nécessaire.++## Forme du système++- Produit : `[replace with product name]`+- Flux utilisateur principal : `[replace with main workflow]`+- Surfaces d'exécution : `[desktop / web / cli / services / workers]`+- Source de vérité pour le comportement produit : `docs/product-specs/`++## Carte des domaines++| Domaine | Objectif | Points d'entrée principaux | Spécification associée |+|---------|----------|---------------------------|----------------------|+| `[domain-a]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |+| `[domain-b]` | `[what it owns]` | `[modules / routes / commands]` | `[spec path]` |++## Modèle de couches++Utilisez un modèle directionnel fixe pour que les agents n'inventent pas une architecture+ad hoc :++`Types -> Config -> Repo -> Service -> Runtime -> UI`++Les préoccupations transversales doivent entrer par des frontières explicites de+fournisseur ou d'adaptateur plutôt que d'atteindre directement à travers les couches.++## Règles strictes de dépendance++- Les couches inférieures ne doivent pas dépendre des couches supérieures.+- L'UI ne doit pas contourner les contrats d'exécution ou de service.+- L'accès aux données doit passer par des dépôts ou des adaptateurs équivalents.+- Les utilitaires partagés doivent rester génériques et ne doivent pas accumuler+ de logique métier.+- Les nouvelles dépendances doivent être justifiées dans le plan ou le document+ de conception correspondant.++## Interfaces transversales++| Préoccupation | Frontière approuvée | Notes |+|--------------|--------------------| -----|+| Journalisation et traçage | `[provider / utility path]` | `[structured only, no ad hoc console use]` |+| Authentification | `[provider path]` | `[token/session rules]` |+| APIs externes | `[client or provider path]` | `[rate limit / retry guidance]` |+| Feature flags | `[flag boundary]` | `[ownership]` |++## Points chauds actuels++- `[zone la plus difficile à modifier en toute sécurité pour les agents]`+- `[zone avec des limites faibles ou des tests fragiles]`++## Liste de contrôle des modifications++Lorsque vous modifiez du code pertinent pour l'architecture :++1. Mettez à jour ce fichier si la carte des domaines ou les frontières autorisées+ ont changé.+2. Mettez à jour le document de conception associé dans `docs/design-docs/` si le+ raisonnement a changé.+3. Ajoutez ou mettez à jour un contrôle exécutable si la règle doit être appliquée+ mécaniquement.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/fr/resources/openai-advanced/repo-template/docs/DESIGN.mdnew file mode 100644index 0000000..68ca18c--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/DESIGN.md@@ -0,0 +1,28 @@+# DESIGN.md++Ce fichier est le point d'entrée de la conception. Gardez-le bref et utilisez-le pour+router vers les fichiers plus détaillés sous `docs/design-docs/`.++## Objectif++Enregistrer les décisions de conception produit et système durables qui doivent survivre+au-delà d'une seule conversation, sprint ou mémoire de relecteur.++## Lisez ceci quand++- vous avez besoin de la philosophie de conception actuelle+- vous êtes sur le point d'introduire un nouveau motif+- vous devez savoir quelles décisions de conception sont tranchées versus encore ouvertes++## Documents de conception canoniques++- `docs/design-docs/index.md` : index des documents acceptés, proposés et dépréciés+- `docs/design-docs/core-beliefs.md` : croyances agent-first à l'échelle du projet++## Règles de conception++- Gardez les documents de conception petits et à jour.+- Préférez un document par domaine de décision.+- Liez les documents de conception depuis les plans et spécifications quand un changement en dépend.+- Si une règle de conception devient critique opérationnellement, promouvez-la en un contrôle+ automatisé ou mettez à jour `ARCHITECTURE.md`.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/fr/resources/openai-advanced/repo-template/docs/FRONTEND.mdnew file mode 100644index 0000000..9e4a295--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/FRONTEND.md@@ -0,0 +1,28 @@+# FRONTEND.md++Ce fichier définit les attentes stables du frontend pour que les agents n'inventent pas+des motifs d'interface de manière imprévisible.++## Principes d'UI++- Optimisez pour la clarté avant la nouveauté.+- Gardez les flux d'interaction découvrables et redémarrables.+- Préférez un petit nombre de composants réutilisables plutôt que des variantes à usage unique.+- Les vérifications d'accessibilité font partie de la vérification normale, pas du travail+ de finition.++## Garde-fous++- Documentez le système de design ou la bibliothèque de composants dans `docs/references/`.+- Enregistrez les états clés visibles par l'utilisateur : vide, chargement, succès, erreur,+ nouvelle tentative.+- Gardez le texte, le comportement clavier et la hiérarchie visuelle cohérents entre les flux.+- Lorsqu'un bug d'interface est corrigé, ajoutez ou mettez à jour l'étape de validation+ correspondante.++## Attentes de vérification++- Capturez des preuves pour les parcours utilisateur critiques.+- Enregistrez les étapes de validation navigateur ou d'exécution dans le plan pertinent.+- Si les régressions visuelles sont fréquentes, standardisez les vérifications par captures+ d'écran ou contrôles du DOM.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/fr/resources/openai-advanced/repo-template/docs/PLANS.mdnew file mode 100644index 0000000..c33dede--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/PLANS.md@@ -0,0 +1,35 @@+# PLANS.md++Ce fichier définit la manière dont les plans d'exécution sont créés, mis à jour, complétés+et archivés.++## Quand un plan est nécessaire++Créez un plan d'exécution lorsque le travail :++- s'étend sur plus d'une session+- modifie plus d'un sous-système+- comporte des risques de vérification ou de déploiement non négligeables+- dépend de décisions en cours qui doivent être consignées++## Emplacements des plans++- `docs/exec-plans/active/` : plans pilotant actuellement le travail+- `docs/exec-plans/completed/` : plans terminés conservés pour le contexte futur des agents+- `docs/exec-plans/tech-debt-tracker.md` : travail différé et suivis++## Sections minimales d'un plan++- objectif+- périmètre et hors périmètre+- chemin de vérification+- risques et obstacles+- journal de progression+- décisions en cours++## Règles de fonctionnement++- Un plan actif doit avoir une étape actuelle clairement attribuée.+- Mettez à jour le plan au fil de l'avancement ; ne le traitez pas comme un texte statique.+- Si une décision modifie la direction de l'implémentation, consignez-la dans le plan.+- Déplacez les plans terminés vers `completed/` afin que les agents puissent encore retrouver le contexte antérieur.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/fr/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.mdnew file mode 100644index 0000000..02b1600--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md@@ -0,0 +1,25 @@+# PRODUCT_SENSE.md++Ce fichier capture le jugement produit durable que les agents ne peuvent pas+inférer de manière fiable uniquement à partir du code.++## Cœur du Produit++- Utilisateur principal : `[remplacer]`+- Travail à accomplir : `[remplacer]`+- Principale frustration à éliminer : `[remplacer]`+- Niveau de qualité pour l'acceptation : `[remplacer]`++## Règles Produit++- Favoriser la fiabilité visible par l'utilisateur plutôt que le nombre de fonctionnalités.+- Traiter le comportement ambigu comme une lacune de spécification, pas comme une permission de deviner.+- Si l'implémentation change ce que les utilisateurs voient ou en qui ils ont confiance, mettre à jour la spécification correspondante.+- Utiliser les spécifications produit pour les flux concrets, et utiliser ce fichier pour les priorités produit transversales.++## Motifs à Éviter++- Actions destructrices cachées+- Échec silencieux sans retour utilisateur+- Source de vérité peu claire pour l'état visible+- Fonctionnalités qui ne peuvent pas être expliquées en une seule phrasediff --git a/docs/fr/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/fr/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.mdnew file mode 100644index 0000000..8bfdd2c--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md@@ -0,0 +1,37 @@+# QUALITY_SCORE.md++Ce document permet de suivre si le dépôt s'améliore ou se dégrade au fil du temps.++## Échelle de notation++- `A` : vérifié, lisible, stable, limites appliquées+- `B` : fonctionnel avec des lacunes mineures+- `C` : partiellement fonctionnel, confusion ou instabilité notable+- `D` : cassé, non sûr ou structurellement peu clair++## Domaines produit++| Domaine | Note | Vérification | Lisibilité agent | Stabilité des tests | Lacunes principales | Dernière mise à jour |+|---------|------|-------------|-----------------|--------------------|--------------------|---------------------|+| `[domain-a]` | - | - | - | - | - | - |+| `[domain-b]` | - | - | - | - | - | - |+| `[domain-c]` | - | - | - | - | - | - |++## Couches architecturales++| Couche | Note | Application des limites | Lisibilité agent | Lacunes principales | Dernière mise à jour |+|--------|------|------------------------|-----------------|--------------------|---------------------|+| Types | - | - | - | - | - |+| Services | - | - | - | - | - |+| Runtime | - | - | - | - | - |+| UI | - | - | - | - | - |++| Date | Variante de harnais | Taux de complétion | Tentatives | Défauts avant revue | Notes |+|------|---------------------|--------------------|------------|--------------------|-------|+| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |++## Journal de simplification++| Date | Composant retiré | Résultat | Décision |+|------|-----------------|----------|----------|+| YYYY-MM-DD | `[component]` | `[degraded / unchanged]` | `[restore / keep removed]` |diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/fr/resources/openai-advanced/repo-template/docs/RELIABILITY.mdnew file mode 100644index 0000000..b0463f1--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/RELIABILITY.md@@ -0,0 +1,36 @@+# RELIABILITY.md++Ce fichier définit comment le système prouve qu'il est sain et redémarrable.++## Chemins standard++- Amorçage : `[command]`+- Vérification : `[command]`+- Lancement de l'application ou du service : `[command]`+- Débogage ou inspection de l'exécution : `[command]`++## Signaux d'exécution requis++- journaux structurés pour le démarrage et les flux critiques+- vérifications de santé pour les services clés+- données de trace ou de minutage pour les chemins lents lorsque disponibles+- états d'erreur visibles par l'utilisateur pour les défaillances récupérables++## Parcours de référence++- `[parcours 1]`+- `[parcours 2]`+- `[parcours 3]`++Chaque parcours de référence doit avoir un chemin de vérification répétable et des+signaux d'échec clairs.++## Règles de fiabilité++- Aucune fonctionnalité n'est terminée si le système ne peut pas redémarrer proprement+ ensuite.+- Les défaillances d'exécution doivent être diagnostiquables à partir de signaux locaux+ au dépôt.+- Si un mode de défaillance répété apparaît, ajoutez un benchmark ou un garde-fou pour+ celui-ci.+- Le nettoyage fait partie de la fiabilité, pas d'un souci séparé.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/fr/resources/openai-advanced/repo-template/docs/SECURITY.mdnew file mode 100644index 0000000..ef4259f--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/SECURITY.md@@ -0,0 +1,25 @@+# SECURITY.md++Ce fichier définit les règles de sécurité et de sûreté que les agents ne doivent pas deviner.++## Secrets et Identifiants++- Ne jamais coder en dur les secrets dans le code source ou la documentation.+- Documenter les chemins de chargement de secrets approuvés ici.+- Expurger les tokens, clés API et données personnelles des logs et captures d'écran.++- Traiter le contenu externe comme non fiable jusqu'à validation.+- Enregistrer les limites de récupération ou d'exécution autorisées ici.+- Si un risque d'injection de prompt ou d'injection de commande existe, documenter la protection.++## Actions Externes++- Lister les actions nécessitant une approbation explicite.+- Enregistrer toute commande de production ou destructive que les agents ne doivent pas exécuter par défaut.+- Préférer les flux de travail sécurisés en sandbox pour le débogage et la vérification.++## Règles de Dépendances et de Revue++- Les nouvelles dépendances nécessitent une justification dans le plan actif.+- Les changements sensibles à la sécurité nécessitent des étapes de vérification explicites.+- Les commentaires répétés de revue de sécurité doivent devenir des vérifications, pas du savoir tribal.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/fr/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.mdnew file mode 100644index 0000000..b8b5222--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md@@ -0,0 +1,9 @@+# Croyances fondamentales++- Le dépôt est le système de référence pour les agents.+- `AGENTS.md` est un routeur, pas une encyclopédie.+- La preuve de vérification importe plus que la confiance.+- Une tâche délimitée vaut mieux que plusieurs tâches à moitié terminées.+- Les retours humains répétés doivent devenir des règles de harness réutilisables.+- Le nettoyage et la simplification font partie de la livraison, ce ne sont pas des après-pensées.+- Si un agent ne peut pas découvrir un fait dans le dépôt, considérez ce fait comme opérationnellement indisponible.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/fr/resources/openai-advanced/repo-template/docs/design-docs/index.mdnew file mode 100644index 0000000..7722a55--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/design-docs/index.md@@ -0,0 +1,21 @@+# Index des documents de conception++Utilisez cet index comme la carte découvrable de l'historique de conception.++## Acceptés++- `core-beliefs.md` : croyances opérationnelles agent-first et normes durables du projet++## Proposés++- `[add new design doc paths here]`++## Dépréciés++- `[move old or superseded design docs here with replacement links]`++## Règles de maintenance++- Chaque document de conception devrait avoir un propriétaire ou un déclencheur de mise à jour.+- Supprimez les documents obsolètes ou marquez-les comme dépréciés plutôt que de les laisser dériver.+- Liez les plans d'exécution actifs aux documents de conception dont ils dépendent.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/active/index.mdnew file mode 100644index 0000000..128422a--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md@@ -0,0 +1,10 @@+# Plans actifs++Gardez un fichier markdown par plan d'exécution actif dans ce dossier.++Modèle de nommage suggéré :++- `YYYY-MM-DD-short-topic.md`++Chaque plan actif devrait être suffisamment à jour pour qu'une nouvelle session d'agent+puisse reprendre le travail à partir du seul dépôt.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.mdnew file mode 100644index 0000000..4379251--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md@@ -0,0 +1,5 @@+# Plans terminés++Déplacez les plans terminés ici au lieu de les supprimer. Les plans terminés font partie+de la surface de mémoire du dépôt et aident les exécutions ultérieures des agents à+comprendre pourquoi le code se présente tel qu'il est.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.mdnew file mode 100644index 0000000..3180e24--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md@@ -0,0 +1,7 @@+# Suivi de la dette technique++Utilisez ce fichier pour la dette qui est réelle, reconnue et intentionnellement différée.++| Date | Domaine | Dette | Pourquoi différée | Risque | Prochain déclencheur |+|------|---------|-------|-------------------|--------|----------------------|+| YYYY-MM-DD | `[area]` | `[debt]` | `[reason]` | `[risk]` | `[when to revisit]` |diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/fr/resources/openai-advanced/repo-template/docs/generated/db-schema.mdnew file mode 100644index 0000000..bbfeb95--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/generated/db-schema.md@@ -0,0 +1,14 @@+# Schéma de base de données++Utilisez ce dossier pour les artefacts générés ou dérivés que les agents doivent pouvoir+inspecter sans avoir à les reconstituer à partir du code.++## Source++- Généré depuis : `[command or source path]`+- Dernière actualisation : `YYYY-MM-DD`++## Notes++- Ne modifiez pas manuellement les sections générées.+- Régénérez ce fichier lorsque le schéma sous-jacent change.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/fr/resources/openai-advanced/repo-template/docs/product-specs/index.mdnew file mode 100644index 0000000..7307936--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/product-specs/index.md@@ -0,0 +1,14 @@+# Index des spécifications produit++Utilisez ce dossier pour les spécifications actuelles du comportement visible par l'utilisateur.++## Spécifications actives++- `new-user-onboarding.md`++## Règles++- Les spécifications doivent décrire le comportement visible par l'utilisateur et les critères d'acceptation.+- Si l'implémentation diverge de la spécification, mettez à jour l'une d'entre elles au cours de la même+ session.+- Maintenez cet index à jour pour qu'un nouvel agent puisse découvrir rapidement le périmètre produit.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/fr/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.mdnew file mode 100644index 0000000..0c866ee--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md@@ -0,0 +1,26 @@+# Accueil des nouveaux utilisateurs++## Objectif++Décrire l'expérience de première utilisation qu'un nouvel utilisateur devrait avoir.++## Conditions d'entrée++- `[état avant le début du parcours]`++## Parcours utilisateur++1. `[étape une]`+2. `[étape deux]`+3. `[étape trois]`++## Critères d'acceptation++- `[résultat observable]`+- `[résultat observable]`+- `[résultat observable]`++## États d'échec++- `[erreur récupérable et retour utilisateur]`+- `[état bloqué et solution de repli]`diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/fr/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txtnew file mode 100644index 0000000..6f1c612--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt@@ -0,0 +1,9 @@+Purpose: store model-friendly reference material for the design system.++Suggested contents:+- component naming rules+- spacing and typography tokens+- state variants+- accessibility expectations++Keep this file concise and refresh it when the upstream design system changes.diff --git a/docs/fr/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/fr/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txtnew file mode 100644index 0000000..c30cc9c--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt@@ -0,0 +1,8 @@+Purpose: store a clean agent-readable extract of the deployment or packaging+rules your repository depends on.++Suggested contents:+- build entrypoints+- runtime assumptions+- environment variable expectations+- common failure signaturesdiff --git a/docs/fr/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/fr/resources/openai-advanced/repo-template/docs/references/uv-llms.txtnew file mode 100644index 0000000..f2ceba9--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/docs/references/uv-llms.txt@@ -0,0 +1,8 @@+Purpose: store a compact reference for your Python package and environment+workflow when `uv` or similar tooling matters to the repo.++Suggested contents:+- install and sync commands+- lockfile policy+- virtualenv expectations+- verification commandsdiff --git a/docs/fr/resources/openai-advanced/repo-template/index.md b/docs/fr/resources/openai-advanced/repo-template/index.mdnew file mode 100644index 0000000..8840fd4--- /dev/null+++ b/docs/fr/resources/openai-advanced/repo-template/index.md@@ -0,0 +1,25 @@+# Modèle de dépôt avancé++Copiez ce modèle de départ dans un véritable dépôt lorsque vous souhaitez une surface+de documentation agent-first de style OpenAI au lieu d'un simple harnais minimal.++## Ordre de copie++1. Copiez `AGENTS.md` et `ARCHITECTURE.md` à la racine du dépôt.+2. Copiez l'arborescence complète `docs/`.+3. Remplissez d'abord `docs/PRODUCT_SENSE.md`, `docs/QUALITY_SCORE.md` et+ `docs/RELIABILITY.md`.+4. Ajoutez votre premier plan actif sous `docs/exec-plans/active/`.+5. Gardez les fichiers d'entrée courts et acheminez les détails vers les documents liés.++## Ce pour quoi ce modèle est optimisé++- contexte durable local au dépôt+- divulgation progressive au lieu d'un seul fichier d'instructions géant+- cycle de vie explicite des plans+- suivi de la qualité au fil du temps+- limites lisibles pour les agents et les humains++Considérez chaque fichier ici comme un point de départ. Remplacez les substituts,+exemples et commandes d'exemple par les spécifications réelles de votre projet avant+de vous y fier.diff --git a/docs/fr/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/fr/resources/openai-advanced/sops/chrome-devtools-validation-loop.mdnew file mode 100644index 0000000..df7f060--- /dev/null+++ b/docs/fr/resources/openai-advanced/sops/chrome-devtools-validation-loop.md@@ -0,0 +1,52 @@+# SOP : Boucle de validation Chrome DevTools++Utilisez cette SOP lorsque le travail sur l'interface utilisateur dépend d'interactions+réelles à l'exécution et que les captures d'écran, l'état du DOM et la sortie console+sont plus importants que la simple inspection du code.++## Objectif++Transformer la validation de l'interface utilisateur en une boucle d'interaction+répétable que l'agent peut exécuter jusqu'à ce que le parcours soit propre.++## Boucle principale++1. Sélectionner la page cible ou l'instance de l'application.+2. Effacer le bruit de console obsolète.+3. Capturer l'état AVANT.+4. Déclencher le parcours dans l'interface.+5. Observer les événements d'exécution pendant l'interaction.+6. Capturer l'état APRÈS.+7. Appliquer le correctif et redémarrer l'application si nécessaire.+8. Relancer la validation jusqu'à ce que le parcours soit propre.++## Entrées requises++- une commande de démarrage stable+- un parcours d'interface reproductible+- un moyen de capturer le DOM, la console ou des captures d'écran+- une règle définissant ce qui est considéré comme « propre »++## SOP d'exécution++1. Écrire le parcours cible dans le plan actif.+2. Définir le succès en termes observables : texte présent, bouton activé,+ erreur disparue, console propre, requête réussie.+3. Capturer l'état initial avant l'interaction.+4. Déclencher exactement un seul parcours à la fois.+5. Enregistrer les événements d'exécution, les changements du DOM et la sortie visible.+6. Si le parcours échoue, corriger la couche responsable la plus petite et redémarrer.+7. Relancer le même parcours et comparer les preuves AVANT/APRÈS.++## Critères de propreté++- l'état visible attendu est présent+- les erreurs inattendues sont absentes+- le bruit de console est compris ou effacé+- relancer le même parcours donne le même résultat++## Artefacts du dépôt à mettre à jour++- plan d'exécution actif+- `docs/RELIABILITY.md` si le parcours devient un chemin de référence+- spécification produit si le comportement visible a changédiff --git a/docs/fr/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/fr/resources/openai-advanced/sops/encode-knowledge-into-repo.mdnew file mode 100644index 0000000..4ad8e55--- /dev/null+++ b/docs/fr/resources/openai-advanced/sops/encode-knowledge-into-repo.md@@ -0,0 +1,48 @@+# SOP : Encoder les connaissances invisibles dans le dépôt++Utilisez cette SOP lorsque du contexte important se trouve encore dans Google Docs,+les fils de discussion, les tickets ou dans la tête des gens.++## Objectif++Rendre les connaissances invisibles pour l'agent découvrables dans le codebase+pour qu'une nouvelle session puisse agir dessus sans s'appuyer sur une conversation antérieure.++## Signaux déclencheurs++- L'agent demande constamment comment fonctionne le système.+- Des humains disent « on a décidé ça sur Slack » ou « suis ce que X a dit la semaine dernière. »+- Les revues font référence à des règles produit ou de sécurité qui ne sont pas écrites dans le dépôt.+- Les nouvelles sessions répètent un travail de découverte qui devrait déjà être établi.++## SOP d'exécution++1. Lister les sources de connaissances invisibles : docs, chats, règles d'équipe implicites,+ décisions verbales.+2. Pour chaque source, se demander : s'agit-il d'architecture, de comportement produit,+ de politique de sécurité, d'attente de fiabilité, de contexte de planification ou de+ matériel de référence ?+3. L'encoder dans l'artefact de dépôt correspondant :+ - architecture -> `ARCHITECTURE.md`+ - comportement produit -> `docs/product-specs/`+ - justification de conception -> `docs/design-docs/`+ - état d'exécution -> `docs/exec-plans/`+ - références externes répétées -> `docs/references/`+ - attentes de qualité ou de fiabilité -> `docs/QUALITY_SCORE.md` ou `docs/RELIABILITY.md`+4. Remplacer les formulations vagues par un langage opérationnellement utile.+5. Supprimer ou déprécier les copies obsolètes pour que le dépôt conserve+ une seule vérité découvrable.++## Règles de bon encodage++- Écrire pour la découvabilité, pas pour l'exhaustivité littéraire.+- Préférer des documents courts avec des noms de fichiers clairs.+- Lier les artefacts connexes entre eux.+- Stocker des règles durables, pas des comptes rendus de réunion.+- Mettre à jour le dépôt dans la même session où la décision est prise.++## Définition du « fini »++- Un nouvel agent peut découvrir la règle concernée sans demander à un humain.+- Le même fait n'est pas dispersé dans plusieurs fichiers contradictoires.+- Le nouvel artefact se trouve à proximité du code ou du flux de travail qu'il régit.diff --git a/docs/fr/resources/openai-advanced/sops/index.md b/docs/fr/resources/openai-advanced/sops/index.mdnew file mode 100644index 0000000..934fabb--- /dev/null+++ b/docs/fr/resources/openai-advanced/sops/index.md@@ -0,0 +1,27 @@+# SOP OpenAI avancées++Ces SOP traduisent les modèles de fonctionnement de l'article en playbooks+d'exécution concrets que vous pouvez suivre ou adapter.++## SOP incluses++- [`layered-domain-architecture.md`](./layered-domain-architecture.md) :+ établir des couches explicites et des limites transversales+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md) :+ déplacer les connaissances invisibles depuis les chats, docs et mémoires+ vers des fichiers locaux au dépôt+- [`observability-feedback-loop.md`](./observability-feedback-loop.md) :+ donner aux agents des journaux, métriques, traces et une boucle de débogage répétable+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md) :+ utiliser l'automatisation de navigateur et des captures pour valider le comportement+ de l'interface utilisateur jusqu'à ce qu'il soit propre++## Comment les utiliser++1. Choisissez la SOP qui correspond à votre goulot d'étranglement actuel.+2. Utilisez la liste de contrôle pour mettre en place les artefacts ou outils manquants.+3. Encodez les règles résultantes dans les docs de votre copie de `repo-template/`.+4. Convertissez les commentaires de revue répétés en vérifications, scripts ou garde-fous.++Ces SOP ne sont pas destinées à être suivies aveuglément. Elles ont pour but de rendre+le harnais plus lisible, applicable et répétable.diff --git a/docs/fr/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/fr/resources/openai-advanced/sops/layered-domain-architecture.mdnew file mode 100644index 0000000..ff7ae73--- /dev/null+++ b/docs/fr/resources/openai-advanced/sops/layered-domain-architecture.md@@ -0,0 +1,55 @@+# SOP : Architecture en couches par domaine++Utilisez cette SOP lorsque l'agent enfreint constamment les limites, duplique+la logique entre les couches, ou produit du code qui devient difficile à réviser+après quelques sessions.++## Objectif++Rendre les limites de domaine suffisamment explicites pour que les agents puissent+avancer rapidement sans dégrader silencieusement la structure.++## Modèle cible++Au sein d'un domaine métier, privilégiez ce flux directionnel :++`Types -> Config -> Repo -> Service -> Runtime -> UI`++Les préoccupations transversales doivent entrer par des fournisseurs ou adaptateurs+explicites. Les utilitaires partagés restent en dehors du domaine et ne doivent pas+accumuler de logique métier.++## Liste de contrôle de configuration++- Définir les domaines actuels dans `ARCHITECTURE.md`.+- Écrire les directions de dépendance autorisées dans `ARCHITECTURE.md`.+- Enregistrer les interfaces transversales telles que l'authentification,+ la télémétrie et les API externes.+- Ajouter une note courte pour la violation de limite la plus difficile actuellement.+- Décider ce qui doit être appliqué mécaniquement par lint, tests ou scripts.++## SOP d'exécution++1. Cartographier le codebase en domaines avant de toucher au style d'implémentation.+2. Pour chaque domaine, identifier la séquence de couches autorisée.+3. Identifier toutes les préoccupations transversales et les router via des fournisseurs+ ou adaptateurs.+4. Déplacer la logique partagée ambiguë soit dans le domaine propriétaire,+ soit dans des utilitaires véritablement génériques.+5. Documenter les règles dans `ARCHITECTURE.md`.+6. Ajouter un garde-fou exécutable pour la violation au coût le plus élevé.+7. Mettre à jour la notation de qualité après le changement.++## Définition du « fini »++- Un nouvel agent peut dire quelle couche est propriétaire d'un changement.+- Le code de l'interface n'accède plus directement au dépôt ou aux effets de bord externes.+- Les préoccupations transversales ont des points d'entrée nommés.+- Au moins une limite importante est appliquée mécaniquement.++## Artefacts du dépôt à mettre à jour++- `ARCHITECTURE.md`+- `docs/QUALITY_SCORE.md`+- `docs/design-docs/` lorsque la justification a changé+- `docs/PLANS.md` ou le plan d'exécution actifdiff --git a/docs/fr/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/fr/resources/openai-advanced/sops/observability-feedback-loop.mdnew file mode 100644index 0000000..e276b11--- /dev/null+++ b/docs/fr/resources/openai-advanced/sops/observability-feedback-loop.md@@ -0,0 +1,47 @@+# SOP : Boucle de rétroaction d'observabilité++Utilisez cette SOP lorsque le débogage est lent, que les agents affirment leur succès+sans preuve, ou que le comportement à l'exécution est plus difficile à inspecter+que le code lui-même.++## Objectif++Donner à l'agent une boucle de rétroaction locale sur les journaux, métriques,+traces et charges de travail exécutables pour qu'il puisse raisonner à partir+de l'exécution, et non seulement de l'inspection du code.++## Pile minimale++- l'application émet des journaux structurés+- l'application émet des métriques et des traces lorsque c'est possible+- couche locale de distribution ou de collecte+- interfaces de requête pour les journaux, métriques et traces+- charge de travail ou parcours utilisateur répétable à relancer après chaque changement++## SOP d'exécution++1. Définir les parcours d'exécution de référence les plus importants.+2. Ajouter des journaux structurés au démarrage et sur le chemin critique.+3. Ajouter des métriques pour la latence, les compteurs d'échecs ou la profondeur+ de file d'attente lorsque c'est utile.+4. Ajouter des traces ou des marqueurs de temps pour les flux lents ou multi-étapes.+5. Rendre les signaux interrogeables depuis l'environnement de développement local.+6. Donner à l'agent une charge de travail ou un scénario répétable à relancer.+7. Exiger la boucle : interroger -> corréler -> raisonner -> implémenter ->+ redémarrer -> relancer -> vérifier.++## Liste de contrôle de session de débogage++- Qu'est-ce qui a échoué ?+- Quel signal prouve l'échec ?+- Quelle couche est propriétaire de l'échec ?+- Qu'est-ce qui a changé après le correctif ?+- L'application a-t-elle redémarré correctement ?+- La même charge de travail a-t-elle réussi après relance ?++## Définition du « fini »++- L'agent peut expliquer un mode d'échec à partir de preuves d'exécution.+- La même charge de travail peut être relancée après chaque changement.+- Le redémarrage et la relance font partie de la boucle de tâches normale.+- Les signaux de fiabilité sont documentés dans `docs/RELIABILITY.md`.diff --git a/docs/fr/resources/reference/coding-agent-startup-flow.md b/docs/fr/resources/reference/coding-agent-startup-flow.mdnew file mode 100644index 0000000..b091dd9--- /dev/null+++ b/docs/fr/resources/reference/coding-agent-startup-flow.md@@ -0,0 +1,36 @@+# Flux de démarrage de l'agent de codage++Utilisez ceci au début de chaque session une fois l'initialisation terminée.++## Modèle de démarrage fixe++1. Exécuter `pwd` et confirmer la racine du dépôt.+2. Lire `claude-progress.md`.+3. Lire `feature_list.json`.+4. Examiner les commits récents avec `git log --oneline -5`.+5. Exécuter `./init.sh`.+6. Exécuter un parcours de test de fumée ou de bout en bout de référence.+7. Si la référence est cassée, corriger cela en premier.+8. Sélectionner la fonctionnalité inachevée la plus prioritaire.+9. Travailler uniquement sur cette fonctionnalité jusqu'à ce qu'elle soit+ vérifiée ou explicitement bloquée.++## Pourquoi cet ordre est important++- `pwd` évite un travail accidentel dans le mauvais répertoire.+- Les fichiers de progression et de fonctionnalités restaurent l'état durable+ avant que de nouvelles modifications ne commencent.+- Les commits récents expliquent ce qui a changé le plus récemment.+- `init.sh` standardise le démarrage au lieu de s'appuyer sur la mémoire.+- La vérification de référence intercepte les états de départ cassés avant+ que le nouveau travail ne les cache.++## Miroir de fin de session++La même session devrait se terminer par :++1. l'enregistrement de la progression+2. la mise à jour de l'état des fonctionnalités+3. la rédaction d'une passation si nécessaire+4. la validation du travail sûr+5. le maintien d'un chemin de redémarrage proprediff --git a/docs/fr/resources/reference/index.md b/docs/fr/resources/reference/index.mdnew file mode 100644index 0000000..1760b83--- /dev/null+++ b/docs/fr/resources/reference/index.md@@ -0,0 +1,89 @@+# Référence++Ces notes expliquent comment utiliser les modèles comme un harnais fonctionnel+plutôt que comme un simple ensemble de fichiers épars.++## Notes de référence internes++- [`method-map.md`](./method-map.md) : faire correspondre les modes d'échec+ courants des exécutions longues à l'artefact ou à la politique qui les+ traite en premier+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md) : ce que+ l'initialiseur doit laisser en place avant que le travail sur les fonctionnalités+ ne commence+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md) : flux fixe+ de début de session pour les sessions de codage ultérieures+- [`prompt-calibration.md`](./prompt-calibration.md) : comment garder les+ instructions racines précises sans les rendre gonflées et fragiles++## Articles principaux++Cette liste est intentionnellement restreinte. Un harnais désigne le système+d'exécution autour du modèle : la boucle de l'agent, l'exécution des outils,+le sandboxing, l'état, le contexte, la vérification, la terminaison,+l'orchestration et l'observabilité. Les articles généraux d'ingénierie de prompt+ou de cadres d'agents larges n'appartiennent pas à la liste principale.++Les trois articles originaux restent la colonne vertébrale du cours :++- [OpenAI : Harness engineering : leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) (2026-02-11) : dépôts agent-first, contexte local au dépôt, linting personnalisé et garde-fous structurels.+- [Anthropic : Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (2025-11-26) : agent initialiseur, agent de codage, liste de fonctionnalités, journal de progression et passation à travers les fenêtres de contexte.+- [Anthropic : Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) (2026-03-24) : rôles de planificateur / générateur / évaluateur, réinitialisations de contexte, simplification du harnais et hypothèses obsolètes.++Quelques articles 2026 très pertinents sont ajoutés :++- [OpenAI : Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/) (2026-01-23) : le harnais d'exécution Codex, les appels d'outils, la croissance du contexte et la terminaison de boucle.+- [Anthropic : Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) (2026-01-09) : évaluer le modèle et le harnais ensemble, et distinguer les harnais d'évaluation des harnais d'agents.+- [LangChain : Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) (2026-02-17) : maintenir le modèle fixe tout en améliorant les prompts système, les outils, le middleware, le traçage et l'auto-vérification pour faire passer un agent de codage du Top 30 au Top 5 sur Terminal Bench 2.0.+- [Thoughtworks / Martin Fowler : Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html) (2026-04-02) : harnais utilisateurs d'agents de codage comme guides anticipatifs et capteurs de rétroaction, avec des contrôles déterministes et inférentiels.+- [Cursor : Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness) (2026-04-30) : traiter le harnais comme un système produit en amélioration continue avec évaluations hors ligne, métriques en ligne, taxonomie des erreurs d'outils, réglage spécifique au modèle et changement de modèle en cours de conversation.++## Références étendues 2026++Ce ne sont pas des sources principales du cours, mais elles sont utiles lors de la+conception de modules de harnais spécifiques. Cette section ne conserve que les sources+dont le contenu couvre directement la boucle de l'agent, l'exécution des outils, la+gestion du contexte, la vérification, le sandboxing, les couches de contrôle ou la+gouvernance des régressions. Les produits d'agents purs, les annonces de plateforme,+les études de cas d'équipe et les benchmarks sont exclus.++- [OpenAI : Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/) (2026-02-04) : le harnais comme protocole réutilisable d'App Server avec cycle de vie des threads, reprise, fork, diffs et intégrations clientes.+- [OpenAI Developers : Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) (2026-02-23) : mémoire de projet durable, validation des jalons et exemples de critères de complétion pour les tâches longues.+- [OpenAI : The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/) (2026-04-15) : harnais natifs au modèle, exécution en sandbox et exécution de fichiers/commandes.+- [OpenAI : An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/) (2026-04-27) : transformer un traqueur de tickets ou un tableau Linear en plan de contrôle multi-agents.+- [Anthropic : Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler) (2026-02-05) : équipes d'agents parallèles, verrous de tâches, synchronisation git, isolation par conteneurs et boucles autonomes.+- [Anthropic : Scaling Managed Agents: Decoupling the brain from the hands](https://www.anthropic.com/engineering/managed-agents) (2026-04-08) : une vue méta-harnais qui sépare session, harnais et sandbox en tant qu'interfaces interchangeables.+- [Anthropic : An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem) (2026-04-23) : niveau de raisonnement, élagage du contexte et prompts système comme changements de harnais nécessitant une gouvernance des régressions.+- [LangChain : Context Management for Deep Agents](https://www.langchain.com/blog/context-management-for-deepagents) (2026-01-28) : déchargement sur système de fichiers, troncature des appels d'outils, résumé et évaluations ciblées pour les harnais de gestion du contexte.+- [LangChain : Tuning Deep Agents to Work Well with Different Models](https://www.langchain.com/blog/tuning-deep-agents-different-models) (2026-04-29) : profils de harnais spécifiques au modèle pour les prompts, noms d'outils, middleware et configuration de sous-agents.+- [LangChain : Continual learning for AI agents](https://www.langchain.com/blog/continual-learning-for-ai-agents) (2026-04-05) : diviser l'amélioration des agents en couches de modèle, de harnais et de contexte, alimentée par les traces.+- [Microsoft : Agent Harness in Agent Framework](https://devblogs.microsoft.com/agent-framework/agent-harness-in-agent-framework/) (2026-03-12) : harnais shell/système de fichiers, flux d'approbation, exécution shell hébergée et compactage du contexte.+- [Google : Announcing ADK for Java 1.0.0](https://developers.googleblog.com/announcing-adk-for-java-100-building-the-future-of-ai-agents-in-java/) (2026-03-30) : plugins, compactage d'événements, HITL, services de session/mémoire et A2A comme primitives de harnais réutilisables.+- [GitHub : Automate repository tasks with GitHub Agentic Workflows](https://github.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflows/) (2026-02-13) : GitHub Actions comme exécuteur de flux de travail agentique avec sorties sûres, sandboxing, permissions et revue.+- [AWS : AI agents in enterprises: Best practices with Amazon Bedrock AgentCore](https://aws.amazon.com/blogs/machine-learning/ai-agents-in-enterprises-best-practices-with-amazon-bedrock-agentcore/) (2026-02-03) : couches de harnais d'entreprise couvrant Runtime, Memory, Gateway, Identity/Policy, Observability et Evaluations.+- [Stripe : Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents) (2026-02-09) et [Partie 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2) (2026-02-19) : isolation devbox, harnais d'agents personnalisés, machines à états blueprint, fichiers de règles, curation d'outils MCP, contrôles de sécurité et boucles de rétroaction pre-push/CI.+- [Cognition : What We Learned Building Cloud Agents](https://cognition.ai/blog/what-we-learned-building-cloud-agents) (2026-04-23) : isolation par VM, capture/reprise de session, orchestration, gouvernance, journalisation d'audit et intégrations pour les runtimes d'agents cloud.+- [Cognition : Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working) (2026-04-22) : boucles générateur-vérificateur, réviseurs à contexte propre, routage smart-friend, coordination manager-enfant et limites de communication inter-agents.+- [Replit : Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance) (2026-01-20, mis à jour 2026-01-23) : un classificateur léger injecte des conseils situationnels courts au point de décision au lieu de fourrer toutes les règles dans le prompt système.+- [Vercel : How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent) (2026-01-07) : prompts système dynamiques, une couche de réécriture en streaming et des autocorrections déterministes/basées sur le modèle.+- [Vercel : Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base) (2026-05-04) : un harnais d'agent de codage axé sur la sécurité avec étapes de scan, investigation, revalidation, enrichissement, export, plugin et vérificateur de refus.+- [Sourcegraph : CodeScaleBench](https://sourcegraph.com/blog/codescalebench-testing-coding-agents-on-large-codebases-and-multi-repo-software-engineering-tasks) (2026-03-03) : une référence de harnais d'évaluation/outillage couvrant l'adoption d'outils MCP, les transcriptions d'utilisation d'outils, l'assurance qualité de benchmarks, les portes de vérificateur/reproductibilité et l'itération prompt/préambule.++Les références générales strictement limitées à 2025 sont exclues de la liste principale.+L'article original Anthropic de 2025 sur les harnais reste car c'est une source+fondamentale du cours.++## Ordre de lecture suggéré++1. `method-map.md`+2. `initializer-agent-playbook.md`+3. `coding-agent-startup-flow.md`+4. `prompt-calibration.md`+5. OpenAI Harness engineering+6. Anthropic Effective harnesses+7. Anthropic Harness design for long-running application development+8. OpenAI Codex agent loop+9. Anthropic agent evals+10. LangChain Improving Deep Agents+11. Thoughtworks / Martin Fowler Harness engineering for coding agent users+12. Cursor Continually improving our agent harnessdiff --git a/docs/fr/resources/reference/initializer-agent-playbook.md b/docs/fr/resources/reference/initializer-agent-playbook.mdnew file mode 100644index 0000000..4734dd8--- /dev/null+++ b/docs/fr/resources/reference/initializer-agent-playbook.md@@ -0,0 +1,38 @@+# Playbook de l'agent initialiseur++Utilisez ce playbook pour la première session sérieuse dans un dépôt, avant que+le travail incrémental sur les fonctionnalités ne commence.++## Objectif++Créer une surface de fonctionnement stable pour que les sessions ultérieures puissent+implémenter le comportement sans avoir à redériver les commandes de démarrage,+l'état actuel ou les limites des tâches.++## Sorties requises++L'initialiseur doit laisser au moins ces artefacts :++- un fichier d'instructions racine tel que `AGENTS.md` ou `CLAUDE.md`+- une surface de fonctionnalités lisible par machine telle que `feature_list.json`+- un artefact de progression durable tel que `claude-progress.md`+- un assistant de démarrage standard tel que `init.sh`+- un commit initial sûr capturant l'échafaudage de référence++## Liste de contrôle++1. Définir le chemin de démarrage standard.+2. Définir le chemin de vérification standard.+3. Créer le journal de progression et enregistrer l'état de départ.+4. Décomposer le travail en fonctionnalités explicites avec des statuts.+5. Créer le premier commit de référence propre.++## Test de réussite++Une nouvelle session sans contexte de conversation antérieur doit pouvoir répondre :++- ce que fait ce dépôt+- comment le démarrer+- comment le vérifier+- ce qui est inachevé+- quelle est la meilleure prochaine étapediff --git a/docs/fr/resources/reference/method-map.md b/docs/fr/resources/reference/method-map.mdnew file mode 100644index 0000000..f130aa4--- /dev/null+++ b/docs/fr/resources/reference/method-map.md@@ -0,0 +1,20 @@+# Carte des méthodes++Ce tableau fait correspondre les modes d'échec les plus courants des agents de codage+en exécution longue à l'artefact ou à la règle de fonctionnement qui les corrige+généralement en premier.++| Mode d'échec | À quoi cela ressemble en pratique | Correctif principal | Artefact de support |+| --- | --- | --- | --- |+| Confusion au démarrage à froid | Une nouvelle session passe la majeure partie de son temps à redécouvrir la configuration et l'état | Faire du dépôt le système de référence | `claude-progress.md` |+| Dérapage du périmètre | L'agent démarre plusieurs fonctionnalités et n'en termine aucune correctement | Restreindre le périmètre actif | `feature_list.json` |+| Achèvement prématuré | L'agent déclare avoir terminé après des modifications de code mais avant une preuve exécutable | Lier l'achèvement à des preuves | `clean-state-checklist.md` |+| Démarrage fragile | Chaque session réapprend comment démarrer le projet | Standardiser la configuration et la vérification | `init.sh` |+| Passation faible | La session suivante ne peut pas dire ce qui est vérifié, cassé ou à venir | Terminer par une passation explicite | `session-handoff.md` |+| Revue subjective | La qualité de la revue dépend du goût ou de la mémoire | Noter la sortie avec des catégories fixes | `evaluator-rubric.md` |++## Principe de fonctionnement++Ajouter le plus petit artefact qui traite directement le mode d'échec observé.+Éviter de résoudre chaque problème de fiabilité en déversant plus de texte+dans un seul fichier d'instructions global.diff --git a/docs/fr/resources/reference/prompt-calibration.md b/docs/fr/resources/reference/prompt-calibration.mdnew file mode 100644index 0000000..ba30ed9--- /dev/null+++ b/docs/fr/resources/reference/prompt-calibration.md@@ -0,0 +1,26 @@+# Calibration des prompts++Les instructions racines doivent définir le cadre de fonctionnement, pas chaque+mouvement possible.++## Garder dans le fichier racine++- l'objectif et le périmètre du dépôt+- le chemin de démarrage+- le chemin de vérification+- les contraintes non négociables+- les artefacts d'état requis+- les règles de fin de session++## Sortir du fichier racine++- les cas limites historiques longs+- les détails d'implémentation spécifiques à un sujet+- les notes d'architecture locale qui doivent se trouver près du code+- les exemples qui ne s'appliquent qu'à un seul sous-système++## Règle de travail++Le fichier racine doit aider une nouvelle session à s'orienter rapidement.+Si le fichier devient une poubelle pour chaque échec passé, diviser les détails+en documents plus petits et y faire un lien à la place.diff --git a/docs/fr/resources/templates/AGENTS.md b/docs/fr/resources/templates/AGENTS.mdnew file mode 100644index 0000000..a874dde--- /dev/null+++ b/docs/fr/resources/templates/AGENTS.md@@ -0,0 +1,57 @@+# AGENTS.md++Ce dépôt est conçu pour le travail d'agents de codage en exécution longue. L'objectif+n'est pas de maximiser la production brute de code. L'objectif est de laisser le dépôt+dans un état où la prochaine session peut continuer sans avoir à deviner.++## Flux de démarrage++Avant d'écrire du code :++1. Confirmer le répertoire de travail avec `pwd`.+2. Lire `claude-progress.md` pour connaître le dernier état vérifié et la prochaine étape.+3. Lire `feature_list.json` et choisir la fonctionnalité inachevée la plus prioritaire.+4. Examiner les commits récents avec `git log --oneline -5`.+5. Exécuter `./init.sh`.+6. Exécuter la vérification de fumée ou de bout en bout requise avant de commencer+ un nouveau travail.++Si la vérification de référence échoue déjà, corriger cela en premier. Ne pas empiler+de nouveau travail sur un état de départ cassé.++## Règles de travail++- Travailler sur une seule fonctionnalité à la fois.+- Ne pas marquer une fonctionnalité comme terminée uniquement parce que du code a été ajouté.+- Garder les modifications dans le périmètre de la fonctionnalité sélectionnée, sauf si+ un obstacle impose un correctif de support restreint.+- Ne pas modifier silencieusement les règles de vérification pendant l'implémentation.+- Préférer les artefacts durables du dépôt aux résumés de conversation.++## Artefacts requis++- `feature_list.json` : source de vérité pour l'état des fonctionnalités+- `claude-progress.md` : journal de session et état vérifié actuel+- `init.sh` : chemin standard de démarrage et de vérification+- `session-handoff.md` : passation compacte optionnelle pour les sessions plus importantes++## Définition du « fini »++Une fonctionnalité est terminée uniquement lorsque toutes les conditions suivantes sont+remplies :++- le comportement cible est implémenté+- la vérification requise a réellement été exécutée+- les preuves sont enregistrées dans `feature_list.json` ou `claude-progress.md`+- le dépôt reste redémarrable depuis le chemin de démarrage standard++## Fin de session++Avant de terminer une session :++1. Mettre à jour `claude-progress.md`.+2. Mettre à jour `feature_list.json`.+3. Enregistrer tout risque ou obstacle non résolu.+4. Valider avec un message descriptif une fois le travail dans un état sûr.+5. Laisser le dépôt suffisamment propre pour que la prochaine session puisse exécuter+ `./init.sh` immédiatement.diff --git a/docs/fr/resources/templates/CLAUDE.md b/docs/fr/resources/templates/CLAUDE.mdnew file mode 100644index 0000000..60a28cc--- /dev/null+++ b/docs/fr/resources/templates/CLAUDE.md@@ -0,0 +1,48 @@+# CLAUDE.md++Vous travaillez dans un dépôt conçu pour un travail d'implémentation en exécution longue.+Priorisez l'achèvement fiable, la continuité entre les sessions et la vérification+explicite plutôt que la vitesse.++## Boucle de fonctionnement++Au début de chaque session :++1. Exécuter `pwd` et confirmer que vous êtes à la racine du dépôt attendu.+2. Lire `claude-progress.md`.+3. Lire `feature_list.json`.+4. Examiner les commits récents avec `git log --oneline -5`.+5. Exécuter `./init.sh`.+6. Vérifier si le parcours de fumée ou de bout en bout de référence est déjà cassé.++Ensuite, sélectionner exactement une fonctionnalité inachevée et travailler uniquement+sur cette fonctionnalité jusqu'à ce que vous la vérifiiez ou que vous documentiez+pourquoi elle est bloquée.++## Règles++- Une seule fonctionnalité active à la fois.+- Ne pas déclarer l'achèvement sans preuve exécutable.+- Ne pas réécrire la liste des fonctionnalités pour masquer le travail inachevé.+- Ne pas supprimer ou affaiblir les tests uniquement pour faire paraître la tâche terminée.+- Utiliser les artefacts du dépôt comme système de référence.++## Fichiers requis++- `feature_list.json`+- `claude-progress.md`+- `init.sh`+- `session-handoff.md` lorsqu'une passation compacte est utile++## Porte d'achèvement++Une fonctionnalité ne peut passer à `passing` qu'après que la vérification requise+a réussi et que le résultat est enregistré.++## Avant de vous arrêter++1. Mettre à jour le journal de progression.+2. Mettre à jour l'état des fonctionnalités.+3. Enregistrer ce qui est encore cassé ou non vérifié.+4. Valider une fois que le dépôt est sûr à reprendre.+5. Laisser un chemin de redémarrage propre pour la prochaine session.diff --git a/docs/fr/resources/templates/claude-progress.md b/docs/fr/resources/templates/claude-progress.mdnew file mode 100644index 0000000..6da153d--- /dev/null+++ b/docs/fr/resources/templates/claude-progress.md@@ -0,0 +1,35 @@+# Journal de progression++## État vérifié actuel++- Racine du dépôt :+- Chemin de démarrage standard :+- Chemin de vérification standard :+- Fonctionnalité inachevée la plus prioritaire actuelle :+- Obstacle actuel :++## Journal des sessions++### Session 001++- Date :+- Objectif :+- Terminé :+- Vérification exécutée :+- Preuves capturées :+- Commits :+- Fichiers ou artefacts mis à jour :+- Risque connu ou problème non résolu :+- Meilleure prochaine étape :++### Session 002++- Date :+- Objectif :+- Terminé :+- Vérification exécutée :+- Preuves capturées :+- Commits :+- Fichiers ou artefacts mis à jour :+- Risque connu ou problème non résolu :+- Meilleure prochaine étape :diff --git a/docs/fr/resources/templates/clean-state-checklist.md b/docs/fr/resources/templates/clean-state-checklist.mdnew file mode 100644index 0000000..e73c9e7--- /dev/null+++ b/docs/fr/resources/templates/clean-state-checklist.md@@ -0,0 +1,8 @@+# Liste de contrôle d'état propre++- [ ] Le chemin de démarrage standard fonctionne toujours.+- [ ] Le chemin de vérification standard s'exécute toujours.+- [ ] La progression actuelle est enregistrée dans le journal de progression.+- [ ] L'état des fonctionnalités reflète ce qui réussit réellement par rapport à ce qui n'est pas vérifié.+- [ ] Aucune étape à moitié terminée n'est laissée non documentée.+- [ ] La prochaine session peut continuer sans réparation manuelle.diff --git a/docs/fr/resources/templates/evaluator-rubric.md b/docs/fr/resources/templates/evaluator-rubric.mdnew file mode 100644index 0000000..9358c9d--- /dev/null+++ b/docs/fr/resources/templates/evaluator-rubric.md@@ -0,0 +1,24 @@+# Grille d'évaluation++Utilisez cette grille après l'implémentation et avant l'acceptation finale.++| Catégorie | Question | Score (0-2) | Notes |+| --- | --- | --- | --- |+| Correction | Le comportement implémenté correspond-il à la fonctionnalité demandée ? | | |+| Vérification | Les vérifications requises ont-elles réellement été exécutées, avec des preuves ? | | |+| Discipline de périmètre | La session est-elle restée dans le périmètre de la fonctionnalité choisie ? | | |+| Fiabilité | Le résultat survit-il au redémarrage ou à la relance sans réparation ? | | |+| Maintenabilité | Le code et la documentation sont-ils suffisamment clairs pour la prochaine session ? | | |+| Préparation à la passation | Une nouvelle session peut-elle continuer le travail à partir des seuls artefacts du dépôt ? | | |++## Verdict++- Accepter+- Réviser+- Bloquer++## Suivi requis++- Preuves manquantes :+- Correctifs requis :+- Prochain déclencheur de revue :diff --git a/docs/fr/resources/templates/feature_list.json b/docs/fr/resources/templates/feature_list.jsonnew file mode 100644index 0000000..138adc6--- /dev/null+++ b/docs/fr/resources/templates/feature_list.json@@ -0,0 +1,64 @@+{+ "project": "replace-with-project-name",+ "last_updated": "YYYY-MM-DD",+ "rules": {+ "single_active_feature": true,+ "passing_requires_evidence": true,+ "do_not_skip_verification": true+ },+ "status_legend": {+ "not_started": "Work has not begun.",+ "in_progress": "The feature is the current active task.",+ "blocked": "Work cannot continue until a documented blocker is resolved.",+ "passing": "Required verification has passed and evidence is recorded."+ },+ "features": [+ {+ "id": "chat-001",+ "priority": 1,+ "area": "chat",+ "title": "Create a new conversation",+ "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",+ "status": "not_started",+ "verification": [+ "Open the app.",+ "Click New Chat.",+ "Verify a new conversation appears in the sidebar.",+ "Verify the main panel shows an empty conversation state."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-002",+ "priority": 2,+ "area": "chat",+ "title": "Send a message in the current conversation",+ "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",+ "status": "not_started",+ "verification": [+ "Open an existing conversation.",+ "Type a message into the input.",+ "Submit the message.",+ "Verify the new message appears in the thread."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-003",+ "priority": 3,+ "area": "chat",+ "title": "Persist the active conversation list",+ "user_visible_behavior": "A user sees previously created conversations after restarting the app.",+ "status": "not_started",+ "verification": [+ "Create two conversations.",+ "Restart the app.",+ "Verify both conversations still appear in the sidebar."+ ],+ "evidence": [],+ "notes": ""+ }+ ]+}diff --git a/docs/fr/resources/templates/index.md b/docs/fr/resources/templates/index.mdnew file mode 100644index 0000000..bd93522--- /dev/null+++ b/docs/fr/resources/templates/index.md@@ -0,0 +1,255 @@+# Guide des modèles++Ces modèles sont prêts à être copiés dans votre propre projet. Chacun remplit un+rôle spécifique dans le flux de travail de l'agent. Modifiez le contenu pour+l'adapter aux commandes, chemins, noms de fonctionnalités et étapes de vérification+de votre projet.++## Pour commencer++Copiez d'abord ces quatre fichiers à la racine de votre projet :++1. `AGENTS.md` ou `CLAUDE.md`+2. `init.sh`+3. `claude-progress.md`+4. `feature_list.json`++Ajoutez les fichiers restants au fur et à mesure que votre projet grandit.++---++## AGENTS.md++Le fichier d'instructions racine. C'est la première chose que l'agent lit lorsqu'il+démarre une session. Il définit les règles de fonctionnement : quoi faire avant+d'écrire du code, comment travailler et comment conclure.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Remplacez les étapes du flux de démarrage par vos chemins et commandes réels+- Ajustez les règles de travail pour correspondre aux conventions de votre équipe+- Conservez la section de définition du « fini » — c'est la partie la plus importante++**Ce qu'il fait pour l'agent :**++- Lui dit de lire la progression et l'état des fonctionnalités avant de commencer le travail+- Le force à travailler sur une seule fonctionnalité à la fois+- Exige des preuves avant de marquer quoi que ce soit comme terminé+- Définit à quoi ressemble une fin de session propre++Utilisez `AGENTS.md` pour Codex ou d'autres agents. Utilisez `CLAUDE.md` si vous+travaillez avec Claude Code — la structure est la même, simplement formatée pour le+style d'instructions de Claude.++## init.sh++Le script de démarrage. Exécute l'installation des dépendances, la vérification+et affiche la commande de lancement — le tout en une seule fois.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Modifiez ces trois variables en haut :+ - `INSTALL_CMD` — votre commande d'installation des dépendances (par ex. `npm install`, `pip install -r requirements.txt`)+ - `VERIFY_CMD` — votre commande de vérification de base (par ex. `npm test`, `pytest`)+ - `START_CMD` — votre commande de lancement du serveur de développement (par ex. `npm run dev`)+- Rendez-le exécutable : `chmod +x init.sh`++**Ce qu'il fait :**++1. Affiche le répertoire courant (pour confirmer qu'il s'exécute au bon endroit)+2. Installe les dépendances+3. Exécute la commande de vérification+4. Affiche la commande de lancement (ou l'exécute si `RUN_START_COMMAND=1` est défini)++Si la vérification échoue, l'agent doit s'arrêter et corriger la ligne de base avant+de faire quoi que ce soit d'autre.++## claude-progress.md++Le journal de progression. Chaque session écrit dans ce fichier, et chaque nouvelle+session le lit en premier.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Remplissez la section « État vérifié actuel » avec les informations de votre projet+- Après chaque session, mettez à jour l'enregistrement de session++**Signification de chaque champ :**++- **État vérifié actuel** — l'unique source de vérité sur l'état du projet+ - `Racine du dépôt` — où se trouve le projet+ - `Chemin de démarrage standard` — la commande pour lancer le projet+ - `Chemin de vérification standard` — la commande pour exécuter les tests+ - `Fonctionnalité inachevée la plus prioritaire` — sur quoi la prochaine session devrait travailler+ - `Obstacle actuel` — tout ce qui est bloqué+- **Enregistrement de session** — une entrée par session+ - `Objectif` — ce que vous aviez prévu de faire+ - `Terminé` — ce qui a réellement été accompli+ - `Vérification exécutée` — quels tests ont été lancés+ - `Preuves enregistrées` — quelles preuves ont été capturées+ - `Commits` — ce qui a été validé+ - `Risques connus` — ce qui pourrait être cassé+ - `Meilleure prochaine action` — où la prochaine session devrait commencer++## feature_list.json++Le suivi des fonctionnalités. Une liste lisible par machine de chaque fonctionnalité+que l'agent doit implémenter, avec son statut, ses étapes de vérification et ses preuves.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Remplacez les exemples de fonctionnalités par les vôtres+- Chaque fonctionnalité nécessite :+ - `id` — un identifiant court unique+ - `priority` — entier, plus bas = plus prioritaire+ - `area` — quelle partie de l'application (par ex. « chat », « import », « search »)+ - `title` — description courte+ - `user_visible_behavior` — ce que l'utilisateur doit voir quand ça fonctionne+ - `status` — parmi `not_started`, `in_progress`, `blocked`, `passing`+ - `verification` — instructions étape par étape pour confirmer le bon fonctionnement+ - `evidence` — preuves enregistrées que la vérification a réussi (remplies par l'agent)+ - `notes` — tout contexte supplémentaire++**Règles de statut :**++- `not_started` — n'a pas été touché+- `in_progress` — la fonctionnalité en cours de travail (une seule à la fois)+- `blocked` — ne peut pas progresser en raison d'un problème documenté+- `passing` — la vérification a réussi et les preuves sont enregistrées++L'agent ne doit avoir qu'une seule fonctionnalité en `in_progress` à tout moment.++## session-handoff.md++Une note de passation compacte entre les sessions. Utilisez-la lorsqu'une session se+termine et que vous souhaitez que la prochaine reprenne rapidement.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Remplissez-la à la fin de chaque session (ou demandez à l'agent de la remplir)++**Ce que chaque section couvre :**++- **Actuellement vérifié** — ce qui est confirmé fonctionnel et quelle vérification a été exécutée+- **Changements cette session** — quel code ou infrastructure a changé+- **Encore cassé ou non vérifié** — problèmes connus et zones à risque+- **Meilleure prochaine action** — ce que la prochaine session doit faire, et ce qu'il ne faut pas toucher+- **Commandes** — démarrage, vérification et commandes de débogage pour référence rapide++Ce fichier est optionnel pour les petites sessions. Il devient important lorsque les+sessions sont longues ou lorsque le projet a plusieurs zones actives.++## clean-state-checklist.md++Une liste de contrôle à passer avant de terminer chaque session. S'assure que le dépôt+est dans un bon état pour que la prochaine session puisse démarrer proprement.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Passez-la en revue avant de fermer une session+- L'agent doit également vérifier ces éléments dans le cadre de sa routine de fin de session++**Ce qu'elle vérifie :**++- Le démarrage standard fonctionne toujours+- La vérification standard s'exécute toujours+- Le journal de progression est mis à jour+- La liste des fonctionnalités reflète l'état réel (pas de fausses entrées `passing`)+- Aucun travail à moitié terminé laissé non enregistré+- La prochaine session peut continuer sans corrections manuelles++## evaluator-rubric.md++Une fiche d'évaluation pour la qualité des résultats de l'agent. Utilisez-la après+une session ou à des jalons du projet pour évaluer si le travail atteint le niveau requis.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Après une session (ou un ensemble de sessions), notez le travail de l'agent sur six dimensions+- Chaque dimension est notée de 0 à 2++**Les six dimensions :**++1. **Correction** — l'implémentation correspond-elle au comportement cible ?+2. **Vérification** — les vérifications requises ont-elles réellement été exécutées, avec des preuves ?+3. **Discipline de périmètre** — l'agent est-il resté dans la fonctionnalité sélectionnée ?+4. **Fiabilité** — le résultat survit-il à un redémarrage ou à une relance ?+5. **Maintenabilité** — le code et la documentation sont-ils suffisamment clairs pour la prochaine session ?+6. **Préparation à la passation** — une nouvelle session peut-elle continuer en utilisant uniquement les artefacts du dépôt ?++**Options de verdict :**++- Accepter — atteint le niveau requis+- Réviser — nécessite des correctifs avant acceptation+- Bloquer — problèmes fondamentaux à résoudre en premier++**Important : l'évaluateur nécessite un réglage.** Tel quel, les agents sont de mauvais+juges d'eux-mêmes — ils identifient des problèmes puis se convainquent d'approuver.+Vous devrez itérer :++1. Exécutez l'évaluateur sur un sprint terminé.+2. Comparez ses scores avec votre propre jugement humain.+3. Lorsqu'ils divergent, rendez la grille plus spécifique sur les critères de réussite/échec.+4. Réexécutez et vérifiez l'alignement.+5. Répétez jusqu'à ce que l'évaluateur corresponde systématiquement à la revue humaine.++Prévoyez 3 à 5 cycles de réglage. Enregistrez chaque changement pour suivre ce qui a+amélioré l'alignement.++## quality-document.md++Un instantané qualité qui note chaque domaine produit et couche architecturale de votre+projet. Suit la santé du codebase au fil du temps, pas seulement les résultats de+sessions individuelles.++**Comment l'utiliser :**++- Copiez à la racine de votre projet+- Avant de démarrer une session : lisez-le pour comprendre où le codebase est le plus faible+- Après une session : mettez à jour les notes en fonction de ce qui a changé+- Au fil du temps : comparez les instantanés pour voir quels changements de harnais ont+ réellement amélioré la santé du codebase++**Ce qu'il évalue :**++- **Domaines produit** (par ex., import de documents, flux Q&R, indexation) : chaque domaine+ reçoit une note (A-D) selon l'état de vérification, la lisibilité agent, la stabilité des+ tests et les lacunes principales+- **Couches architecturales** (par ex., main process, preload, renderer, services) : chaque+ couche reçoit une note pour l'application des limites et la lisibilité agent++**Pourquoi c'est important :**++La grille d'évaluation note les résultats individuels de l'agent. Le document qualité note+le codebase lui-même. Ils répondent à des questions différentes :++- Grille d'évaluation : « L'agent a-t-il fait du bon travail cette session ? »+- Document qualité : « Le projet devient-il plus fort ou plus faible au fil du temps ? »++**Quand mettre à jour :**++- Après chaque session significative+- Avant les comparaisons de benchmarks+- Après les passes de nettoyage ou de simplification+- Lors de l'intégration d'un nouvel agent ou modèle au projet++**Lien avec la simplification du harnais :**++Le document qualité soutient également la simplification du harnais. Chaque composant de+harnais encode une hypothèse sur ce que le modèle ne peut pas faire. À mesure que les+modèles s'améliorent, ces hypothèses deviennent obsolètes. Pour vérifier si un composant+est toujours nécessaire :++1. Prenez un instantané du document qualité.+2. Retirez un composant de harnais.+3. Exécutez la suite de tâches de benchmark.+4. Prenez un autre instantané.+5. Comparez — si les notes n'ont pas baissé, le composant était superflu. Si elles ont baissé,+ restaurez-le.diff --git a/docs/fr/resources/templates/init.sh b/docs/fr/resources/templates/init.shnew file mode 100755index 0000000..d7522d6--- /dev/null+++ b/docs/fr/resources/templates/init.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash++set -euo pipefail++ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+cd "$ROOT_DIR"++# Replace these commands with the correct commands for your repository.+INSTALL_CMD=(npm install)+VERIFY_CMD=(npm test)+START_CMD=(npm run dev)++echo "==> Working directory: $PWD"+echo "==> Syncing dependencies"+"${INSTALL_CMD[@]}"++echo "==> Running baseline verification"+"${VERIFY_CMD[@]}"++echo "==> Startup command"+printf ' %q' "${START_CMD[@]}"+printf '\n'++if [ "${RUN_START_COMMAND:-0}" = "1" ]; then+ echo "==> Starting the app"+ exec "${START_CMD[@]}"+fi++echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."diff --git a/docs/fr/resources/templates/quality-document.md b/docs/fr/resources/templates/quality-document.mdnew file mode 100644index 0000000..9ec1f0c--- /dev/null+++ b/docs/fr/resources/templates/quality-document.md@@ -0,0 +1,46 @@+# Document qualité++Un instantané qualité pour chaque domaine produit et couche architecturale. Les agents+et les humains peuvent utiliser ce document pour comprendre rapidement où le codebase+est solide et où il a besoin de travail.++**Cadence de mise à jour :** Après chaque session significative, ou avant de commencer+une nouvelle phase de travail.++**Échelle de notation :**++- **A** : Toutes les vérifications réussies, architecture propre, lisible par l'agent, tests stables+- **B** : Vérifications réussies, principalement propre, lacunes mineures en lisibilité ou en couverture de tests+- **C** : Partiellement fonctionnel, lacunes connues, certaines zones de code difficiles à comprendre pour les agents+- **D** : Non fonctionnel, ou problèmes structurels majeurs++---++## Domaines produit++| Domaine | Note | Vérification | Lisibilité agent | Stabilité des tests | Lacunes principales | Dernière mise à jour |+|---------|------|-------------|-----------------|--------------------|--------------------|---------------------|+| Import de documents | - | - | - | - | - | - |+| Gestion des documents | - | - | - | - | - | - |+| Indexation des documents | - | - | - | - | - | - |+| Flux Q&R | - | - | - | - | - | - |+| Réponses fondées | - | - | - | - | - | - |++## Couches architecturales++| Couche | Note | Application des limites | Lisibilité agent | Lacunes principales | Dernière mise à jour |+|--------|------|------------------------|-----------------|--------------------|---------------------|+| Main Process | - | - | - | - | - |+| Preload | - | - | - | - | - |+| Renderer | - | - | - | - | - |+| Services | - | - | - | - | - |++## Historique des changements++### YYYY-MM-DD++- Changements :+- Domaines promus :+- Domaines rétrogradés :+- Nouvelles lacunes identifiées :+- Lacunes comblées :diff --git a/docs/fr/resources/templates/session-handoff.md b/docs/fr/resources/templates/session-handoff.mdnew file mode 100644index 0000000..2460938--- /dev/null+++ b/docs/fr/resources/templates/session-handoff.md@@ -0,0 +1,30 @@+# Passation de session++## Vérifié actuellement++- Ce qui fonctionne actuellement :+- Quelle vérification a réellement été exécutée :++## Modifié cette session++- Code ou comportement ajouté :+- Changements d'infrastructure ou de harnais :++## Cassé ou non vérifié++- Défaut connu :+- Chemin non vérifié :+- Risque pour la prochaine session :++- Meilleure prochaine étape++- Fonctionnalité inachevée la plus prioritaire :+- Pourquoi c'est la suivante :+- Ce qui compte comme réussi :+- Ce qui ne doit pas changer pendant cette étape :++## Commandes++- Démarrage :+- Vérification :+- Commande de débogage ciblée :diff --git a/docs/fr/skills/index.md b/docs/fr/skills/index.mdnew file mode 100644index 0000000..3ae647e--- /dev/null+++ b/docs/fr/skills/index.md@@ -0,0 +1,49 @@+# Skills++Ce dossier contient les skills d'agents IA livrés avec ce cours. Les skills sont des modèles de prompt autonomes que des agents de codage IA, comme Claude Code, Codex, Cursor ou Windsurf, peuvent charger pour effectuer des tâches spécialisées.++## harness-creator++Un skill de harness engineering de niveau production pour agents de codage IA. Il vous aide à créer, évaluer et améliorer les cinq sous-systèmes centraux d'un harness : instructions, état, vérification, scope et cycle de vie de session.++### Ce qu'il fait++- **Créer des harnesses depuis zéro** — AGENTS.md, listes de fonctionnalités, workflows de vérification+- **Améliorer des harnesses existants** — évaluation des cinq sous-systèmes avec améliorations priorisées+- **Concevoir la continuité de session** — persistance mémoire, suivi de progression, procédures de handoff+- **Appliquer des patterns de production** — mémoire, context engineering, sécurité des outils, coordination multi-agent++### Démarrage rapide++Les fichiers du skill se trouvent dans le dépôt sous [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator).++Pour l'utiliser avec Claude Code, copiez le dossier `harness-creator/` dans le chemin de skills de votre projet, ou pointez votre agent vers le fichier SKILL.md.++### Patterns de référence++Le skill inclut 6 documents de référence détaillés :++| Pattern | Quand l'utiliser |+|---------|------------------|+| Memory Persistence | L'agent oublie entre les sessions |+| Context Engineering | Gestion du budget de contexte, chargement JIT |+| Tool Registry | Sécurité des outils, contrôle de concurrence |+| Multi-Agent Coordination | Parallélisme, workflows de spécialisation |+| Lifecycle & Bootstrap | Hooks, tâches en arrière-plan, initialisation |+| Gotchas | 15 modes de défaillance non évidents avec correctifs |++### Modèles++Le skill fournit des modèles prêts à l'emploi :++- `agents.md` — scaffold AGENTS.md avec règles de travail+- `feature-list.json` — JSON Schema et exemple de liste de fonctionnalités+- `init.sh` — script d'initialisation standard+- `progress.md` — modèle de journal de progression de session++### Comment ce skill a été construit++`harness-creator` a été développé avec la méthodologie **skill-creator**, le méta-skill officiel d'Anthropic pour créer, tester et itérer sur des skills d'agents. skill-creator fournit un workflow structuré brouillon → test → évaluation → itération, avec runners d'évaluation, graders et visualiseur de benchmark.++- **Source de skill-creator** : [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)+- **Documentation des skills Claude Code** : [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)diff --git a/docs/index.md b/docs/index.mdindex 779e1c7..3ad52b0 100644--- a/docs/index.md+++ b/docs/index.md@@ -8,9 +8,16 @@ if (typeof window !== 'undefined') {const lang = navigator.language || navigator.languages?.[0] || ''let locale = 'en/'if (lang.startsWith('ko')) locale = 'ko/'+ else if (lang.toLowerCase().startsWith('zh-tw') || lang.toLowerCase().startsWith('zh-hk') || lang.toLowerCase().startsWith('zh-mo')) locale = 'zh-TW/'else if (lang.startsWith('zh')) locale = 'zh/'else if (lang.startsWith('ru')) locale = 'ru/'else if (lang.startsWith('vi')) locale = 'vi/'+ else if (lang.startsWith('uz')) locale = 'uz/'+ else if (lang.startsWith('ja')) locale = 'ja/'+ else if (lang.startsWith('es')) locale = 'es/'+ else if (lang.startsWith('fr')) locale = 'fr/'+ else if (lang.startsWith('de')) locale = 'de/'+ else if (lang.startsWith('ar')) locale = 'ar/'const target = `${base}${locale}`if (!window.location.pathname.replace(/\/$/, '').endsWith(target.replace(/\/$/, ''))) {window.location.replace(target)diff --git a/docs/ja/index.md b/docs/ja/index.mdnew file mode 100644index 0000000..d1d9f44--- /dev/null+++ b/docs/ja/index.md@@ -0,0 +1,73 @@+# Learn Harness Engineering へようこそ++Learn Harness Engineering は、AI コーディングエージェントを工程として扱うためのコースです。業界で進んでいる Harness Engineering の理論と実践を調査し、実際の開発に使える形に整理しています。主な参考資料は次のとおりです。+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)++このコースでは、環境設計、状態管理、検証、制御の仕組みを体系的に学び、Codex や Claude Code のようなエージェント型コーディングツールを本当に信頼できるものにする方法を扱います。明示的なルールと境界で AI コーディングアシスタントを制約しながら、機能追加、バグ修正、開発作業の自動化を進めるための実践的な方法を学びます。++## はじめる++学習経路を選んで開始してください。このコースは、理論講義、実践プロジェクト、そのままコピーして使えるリソースライブラリで構成されています。++<div class="card-grid">+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">+ <h3>講義</h3>+ <p>強力なモデルがなぜ失敗するのかを理解し、有効な harness の理論を学びます。</p>+ </a>+ <a href="./projects/" class="card">+ <h3>プロジェクト</h3>+ <p>信頼できるエージェント作業環境をゼロから構築する実践課題です。</p>+ </a>+ <a href="./resources/" class="card">+ <h3>リソースライブラリ</h3>+ <p>自分のリポジトリにそのまま使える AGENTS.md や feature_list.json などのテンプレートです。</p>+ </a>+</div>++## Harness の中核メカニズム++harness は「モデルを賢くする」ものではありません。モデルが働くための閉じたループの**作業システム**を作るものです。中核の流れは次の図で理解できます。++```mermaid+graph TD+ A["Clear Objective<br/>AGENTS.md"] --> B("Initialization<br/>init.sh")+ B --> C{"Run Tasks<br/>AI Agent"}+ C -->|Encounter Issues| D["Runtime Feedback<br/>CLI / Logs"]+ D -->|Auto-fix| C+ C -->|Code Completed| E{"Verify & QA<br/>Test suite"}+ E -->|Failed| D+ E -->|Passed| F["Cleanup & Handoff<br/>claude-progress.md"]++ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;++ class A,F primary;+ class B,D process;+ class C,E check;+```++## 学べること++このコースで身につける主要な考え方は次のとおりです。++<ul class="index-list">+ <li><strong>明示的なルールと境界</strong>でエージェントの挙動を制約する。</li>+ <li><strong>長時間・複数セッションのタスク</strong>でも文脈を維持する。</li>+ <li><strong>早すぎる完了宣言</strong>を防ぐ。</li>+ <li><strong>フルパイプラインのテストと自己レビュー</strong>で作業を検証する。</li>+ <li><strong>ランタイムを観測可能</strong>にし、デバッグしやすくする。</li>+</ul>++## 次のステップ++基本概念を理解したら、次のガイドでさらに深く進めます。++<ul class="index-list">+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">講義 01: 有能なエージェントがそれでも失敗する理由</a>: harness engineering の理論から始めます。</li>+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">プロジェクト 01: ベースライン vs 最小 harness</a>: 最初の実タスクを進めます。</li>+ <li><a href="./resources/templates/">テンプレート</a>: 自分のプロジェクトで使える最小 harness パックを入手します。</li>+</ul>diff --git a/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..311e665--- /dev/null+++ b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,170 @@+/**+ * failure-pattern-demo.ts+ *+ * Simulates the 4-step failure pattern that capable agents fall into:+ * 1. Incomplete context+ * 2. Locally reasonable changes+ * 3. No global verification+ * 4. Premature completion+ *+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// Simulated "model" -- a simple decision function that bases its output+// solely on whatever context it has been given.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // The task is to "add a search endpoint to the API".+ // Correct answer requires knowing about auth middleware and rate limiting.++ if (!has("auth")) {+ return "Created new route handler /search without authentication checks";+ }+ if (!has("rate-limit")) {+ return "Added search route with auth but forgot rate limiting";+ }+ if (!has("test-standards")) {+ return "Implemented search with auth and rate-limit, but no tests";+ }+ return "Fully implemented search endpoint with auth, rate-limit, and tests";+}++// ---------------------------------------------------------------------------+// Failure simulation+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Step 1: Incomplete Context ----+ const step1Context = ["project structure", "route definitions"];+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];+ const step1Decision = modelDecide(step1Context, "add search endpoint");++ steps.push({+ step: 1,+ name: "Incomplete Context",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Looks good -- route compiles, returns data",+ globalImpact: "Missing auth means unauthenticated access to search",+ completed: false,+ });++ // ---- Step 2: Locally Reasonable Changes ----+ // The agent adds auth after a hint, but still lacks other context.+ const step2Context = [...step1Context, "auth middleware"];+ const step2Missing = ["rate-limiting policy", "test standards"];+ const step2Decision = modelDecide(step2Context, "add search endpoint");++ steps.push({+ step: 2,+ name: "Locally Reasonable Changes",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "Route has auth -- looks complete locally",+ globalImpact: "No rate limiting means the endpoint can be abused",+ completed: false,+ });++ // ---- Step 3: No Global Verification ----+ const step3Context = [...step2Context, "rate-limiting policy"];+ const step3Missing = ["test standards"];+ const step3Decision = modelDecide(step3Context, "add search endpoint");++ steps.push({+ step: 3,+ name: "No Global Verification",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "Feature appears fully implemented",+ globalImpact: "No tests -- regression risk, violates project standards",+ completed: false,+ });++ // ---- Step 4: Premature Completion ----+ steps.push({+ step: 4,+ name: "Premature Completion",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',+ localOutcome: "Agent is satisfied, task marked complete",+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Comparison table+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Step ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);+ console.log(` Action taken : ${s.actionTaken}`);+ console.log(` Local outcome : ${s.localOutcome}`);+ console.log(` Global impact : ${s.globalImpact}`);+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);+ }++ // Summary comparison+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");+ console.log("=".repeat(90));++ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];+ const finalAvailable = steps[steps.length - 1].contextAvailable;++ const header = "| Criterion | Available | Missing | Status |";+ const sep = "|------------------------|-----------|---------|----------|";+ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;+ console.log(row);+ }++ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());diff --git a/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdnew file mode 100644index 0000000..0cbe5b6--- /dev/null+++ b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -0,0 +1,9 @@+# 失敗シグナルチェックリスト++弱い harness の実行結果をレビューする際にこのチェックリストを使用してください。++- エージェントはアプリの起動方法を尋ねたか、または誤って推測したか?+- 予定された製品と一致しないディレクトリや抽象を作成したか?+- 完全なワークフローなしに可視的な UI シェルを作成した後に停止したか?+- 今後の実行が継続するのに役立つメモや成果物を残したか?+- 新しいセッションは5分以内に何が起きたか理解できるか?diff --git a/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdnew file mode 100644index 0000000..001c609--- /dev/null+++ b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -0,0 +1,7 @@+# 講義 01 のコード++このフォルダーは、以下を示す小さな例に使用してください:++- 強力なモデルが弱い環境で失敗する様子+- 不十分に指定されたリポジトリ設定+- 欠落しているフィードバックループdiff --git a/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdnew file mode 100644index 0000000..75d7c78--- /dev/null+++ b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -0,0 +1,18 @@+# 仕様不足のタスク例++AI 質問応答機能付きのデスクトップナレッジベースアプリを構築する。++制約:++- 何も指定されていない+- 起動コマンドが与えられていない+- フォルダー構造のガイダンスがない+- データモデルが定義されていない+- 明示的な完了基準がない++この種のプロンプトの典型的な結果:++- エージェントがアドホックに構造をでっち上げる+- アプリはコンパイルできるが一貫して起動できない+- 利用可能なインポート/クエリパスが存在する前に UI が表示される+- エージェントは表面的な成功の後に停止することが多いdiff --git a/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.mdnew file mode 100644index 0000000..6d07bb7--- /dev/null+++ b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -0,0 +1,117 @@+[中文版本 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/code/)+> 実践プロジェクト: [プロジェクト 01. プロンプトのみ vs ルール優先](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# 講義 01. 強いモデルは信頼できる実行を意味しない++あなたは AI の世界にかなり慣れているつもりです。Claude Pro を契約し、GPT-4o API キーを持ち、SWE-bench のリーダーボードも覚えている。ある日、ついに本物のプロジェクトを AI エージェントに任せます。自信満々です。結果はどうでしょう。機能を追加したがテストを壊す。バグを直したが 2 つ増やす。20 分走って誇らしげに「完了」と言う。そしてコードを見ると、そもそも頼んだものではありません。++最初の反応は「このモデルはまだ足りない。アップグレードしよう」かもしれません。少し待ってください。財布を開く前に、問題はモデルではない可能性があります。++数字を見てみましょう。2025 年後半時点で、最強クラスの coding agent でも SWE-bench Verified ではおおむね 50-60% 程度です。しかもこれは、明確な issue 説明と既存テストがある、慎重に選ばれたタスクでの数字です。日常の開発環境、つまり曖昧な要求、既存テストなし、暗黙のビジネスルールが散らばった環境に移ると、その数字はさらに下がります。++しかし、この数字の裏には直感に反する真実があります。++## 同じ馬、違う運命++Anthropic は制御実験を行いました。同じプロンプト(「2D レトロゲームメーカーを作る」)、同じモデル(Opus 4.5)。1 回目は bare、支援なし。20 分、9 ドル、ゲームの中核機能はまったく動きませんでした。2 回目は完全な harness(planner + generator + evaluator の 3 エージェント構成)。6 時間、200 ドル、ゲームはプレイ可能でした。++モデルは変えていません。Opus 4.5 は同じ Opus 4.5 です。変わったのは鞍です。++OpenAI の harness engineering 記事ははっきり言っています。よく harness されたリポジトリでは、Codex は「不可靠」から「可靠」へ変わる。表現に注目してください。「少し良くなる」ではなく、質的な変化です。サラブレッドのようなものです。鞍なしでも乗れますが、遠くへは行けず、速くも走れず、落ちても不思議ではありません。harness はその鞍です。つまり、**モデル重みの外側にあるエンジニアリング基盤のすべて**です。++## エージェントは実際どこで詰まるのか++具体的には何が起きるのでしょうか。++最も多いのは、タスクを明確に定義していないことです。「検索機能を追加して」と言うと、エージェントの理解はあなたとまったく違うかもしれません。何を検索するのか。全文検索か構造化検索か。ページネーションは。ハイライトは。指定しなければ、エージェントは推測します。当たれば運、外れれば最初に具体化するより高くつきます。レストランで「魚をください」と言うようなものです。煮魚か蒸し魚か鍋かは運任せです。++指定したとしても、プロジェクトにはエージェントが知らない暗黙のアーキテクチャ慣習があります。チームは SQLAlchemy 2.0 構文で統一しているのに、エージェントはデフォルトで 1.x のコードを書く。全 API は OAuth 2.0 認証必須なのに、そのルールはあなたの頭の中と 3 か月前の Slack にしかない。エージェントには見えません。従いたくないのではなく、文字通りそのルールの存在を知りません。++環境も罠です。不完全な dev 環境、欠けた依存関係、違うツールバージョン。エージェントは本来の課題ではなく、`pip install` の失敗や Node バージョン不一致に貴重なコンテキストを燃やします。腕のいい大工を雇ったのに、ハンマーも釘も水平な作業台も渡さないようなものです。どれほど有能でも仕事はできません。++さらに多いのは、検証する方法がないことです。テストがない。lint がない。検証コマンドをエージェントに伝えていない。エージェントはコードを書き、眺め、問題なさそうだと判断して「完了」と言います。答え合わせなしで宿題を提出させるようなものです。本人は正しいと思っていますが、採点すると間違いだらけです。Anthropic は、エージェントがコンテキスト不足を感じると急いで終わらせ、検証を飛ばし、最適解より簡単な解を選ぶ現象も観察しています。彼らはこれを「context anxiety」と呼びます。試験時間が残り少ないと気づいて、残りの選択問題を適当に埋めるのと同じです。++セッションをまたぐ長いタスクはさらに悪化します。前セッションの発見は失われ、新しいセッションはプロジェクト構造とコード構成を毎回探索し直します。永続状態を持たないエージェントは、30 分を超えるタスクで失敗率が急上昇します。++## 重要用語++こうした状況を踏まえると、次の概念は単なる流行語ではありません。++- **能力ギャップ**: ベンチマーク上のモデル性能と実タスクでの性能の大きな差。SWE-bench Verified で 50-60% ということは、実 issue のほぼ半分は解けないということです。+- **Harness**: モデルの外側にあるすべて。指示、ツール、環境、状態管理、検証フィードバック。モデル重みでなければ harness です。この講義で言う「鞍」です。+- **Harness 起因の失敗**: モデルには能力があるのに、実行環境に構造的欠陥があるため失敗すること。Anthropic の制御実験がこれを示しています。+- **検証ギャップ**: エージェントの出力への自信と実際の正しさの差。エージェントが「完了」と言うが完了していない。最も多い失敗モードです。+- **診断ループ**: 実行し、失敗を観察し、特定の harness 層に原因を割り当て、その層を修正し、再実行する。harness engineering の中核手法です。+- **Definition of Done**: 機械的に検証可能な完了条件。テスト通過、lint クリーン、型チェック通過。明示しなければ、エージェントは勝手に完了条件を作ります。++## 失敗したら、まず harness を直す++中核原則はこれです。**失敗したら、まずモデルを替えるのではなく harness を確認する。** 同じモデルが似た構造化タスクで成功するなら、harness の問題だと仮定します。車が止まったとき、いきなりエンジンを疑うのではなく、まずガソリン切れを確認するのと同じです。++具体的には次のように進めます。++**すべての失敗を特定の層に帰属させる。** 「モデルがだめ」と言わないでください。タスクが曖昧だったのか。コンテキスト不足だったのか。検証手段がなかったのか。各失敗を 5 つの層(タスク仕様、コンテキスト提供、実行環境、検証フィードバック、状態管理)に対応づけます。この習慣がつくと、「モデルが足りない」はログにだんだん出なくなります。++**すべてのタスクに明示的な Definition of Done を書く。** 「検索機能を追加して」ではなく、こう書きます。+```+Completion criteria:+- New endpoint GET /api/search?q=xxx+- Supports pagination, default 20 items+- Results include highlighted snippets+- All new code passes pytest+- Type checking passes (mypy --strict)+```++**AGENTS.md を作る。** リポジトリルートに置き、技術スタック、アーキテクチャ慣習、検証コマンドをエージェントに伝えます。これは harness engineering の第一歩であり、最も ROI の高い手順です。高価なモデルへアップグレードするより、1 つの `AGENTS.md` のほうが効くことがあります。冗談ではありません。++**診断ループを作る。** 失敗を「またモデルが馬鹿をした」と扱わない。harness に欠陥があるという信号として扱います。失敗ごとに層を特定し、修正し、同じ失敗を繰り返さない。数回回すと harness は強くなり、エージェント性能は安定します。道路補修のように、穴を埋めるほど次の区間が滑らかになります。++**改善を定量化する。** 各タスクが成功したか失敗したか、どの層が原因だったかを簡単に記録します。数回後にはボトルネック層が見えてくるので、そこに力を集中します。++## 100 万行の実験++OpenAI は 2025 年に強烈な実験を行いました。空の git リポジトリから、Codex で完全な社内プロダクトを構築する。5 か月後、そのリポジトリにはおよそ 100 万行のコードがありました。アプリケーションロジック、インフラ、ツール、ドキュメント、社内開発ツール。すべてエージェント生成です。3 人のエンジニアが Codex を操作し、約 1,500 PR を作成してマージしました。1 人あたり 1 日平均 3.5 PR です。++重要な制約は、**人間が直接コードを書かない**ことでした。これは見世物ではありません。エンジニアの主仕事がコードを書くことではなく、環境を設計し、意図を表現し、フィードバックループを作ることになったとき、何が変わるかを強制的に学ぶための設計でした。++初期の進捗は予想より遅かった。Codex が無能だったからではなく、環境が不十分だったからです。エージェントには高レベル目標を進めるためのツール、抽象、内部構造が足りませんでした。エンジニアの仕事は、大きな目標を小さな構成要素(設計、コード、レビュー、テスト)に分解し、エージェントに組み立てさせ、それらの構成要素でより複雑なタスクを解けるようにすることになりました。何かが失敗したときの修正は、ほぼ常に「もっと頑張れ」ではなく、「エージェントに足りない能力は何か、それを理解可能かつ実行可能にするにはどうするか」でした。++この実験は、本講義の中心命題を直接示しています。**同じモデルでも、bare な環境と完全な harness を持つ環境では根本的に違う出力を出す。** モデルは変わっていません。環境が変わったのです。++> Source: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++## もっと身近な例++あるチームは Claude Sonnet を使って、中規模の Python Web アプリ(FastAPI + PostgreSQL + Redis、約 15,000 行)に新しい API endpoint を追加しようとしました。++最初は「`/api/v2/users` 配下に user preferences endpoints を追加して」という 1 文だけを渡しました。結果は、エージェントがコンテキストの 40% をリポジトリ探索に使い、見た目は妥当だがプロジェクトのエラーハンドリングパターンに従わず、古い SQLAlchemy 構文を使い、endpoint にランタイムエラーがあるのに完了宣言しました。次のセッションは探索をやり直す必要がありました。++その後、彼らは `AGENTS.md`(プロジェクト構造と技術スタックバージョンの説明)、明示的な検証コマンド(`pytest tests/api/v2/ && python -m mypy src/`)、ADR を追加しました。同じモデルは 3 回の独立実行すべてで成功し、コンテキスト効率は約 60% 改善しました。++モデルは変えていません。harness を変えました。++## 重要なポイント++- モデル能力と実行信頼性は別物です。サラブレッドにも良い鞍が必要です。+- 失敗したら、まず harness を確認し、その後でモデルを疑います。モデル交換は最も高価な選択肢で、多くの場合はモデル問題ですらありません。+- すべての失敗は信号です。harness に構造的欠陥があります。見つけて直してください。+- 5 つの防御層: タスク仕様、コンテキスト提供、実行環境、検証フィードバック、状態管理。医師が一般的な原因から除外するように、体系的に確認します。+- 1 つの `AGENTS.md` は、高価なモデルに替えるより効果的かもしれません。本当に。++## 参考資料++- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-bench Leaderboard](https://www.swebench.com/)+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)++## 演習++1. **比較実験**: よく知っているコードベースと非自明な変更タスクを選びます。まず harness 支援なしでエージェントを実行し、失敗を記録します。次に明示的な検証コマンドを含む `AGENTS.md` を追加し、同じエージェントで再実行します。結果を比較し、各失敗を 5 つの防御層のどれかに帰属させます。++2. **検証ギャップ測定**: 5 つの coding task を選びます。各タスク後、エージェントが完了を主張したかを記録し、独立したテストで実際の正しさを確認します。完了と言ったが実際は完了していない割合を計算します。それが検証ギャップです。どの検証コマンドがこの割合を下げるか考えてください。++3. **診断ループ練習**: プロジェクト内でエージェントが繰り返し失敗するタスクを探します。1 回実行し、失敗を記録します。5 つの層のどれかに原因を割り当てます。その層を修正し、再実行します。3-5 回繰り返し、改善を記録してください。diff --git a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.mdnew file mode 100644index 0000000..7ad304f--- /dev/null+++ b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md@@ -0,0 +1,21 @@+# Harness コンポーネントの例++ローカルリポジトリで作業するコーディングエージェントの場合:++- モデル:+ LLM 自体++- Harness:+ - システムプロンプト+ - AGENTS.md+ - bash ツール+ - ファイル読み書きツール+ - git アクセス+ - ローカルファイルシステム+ - 起動スクリプト+ - テストコマンド+ - 停止フック+ - lint チェック+ - 評価ループ(evaluator loop)++上記の harness 構成要素のいずれかを変更すると、実質的なエージェントが変わります。diff --git a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.tsnew file mode 100644index 0000000..d856ba3--- /dev/null+++ b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts@@ -0,0 +1,180 @@+/**+ * harness-vs-no-harness.ts+ *+ * Side-by-side comparison of the same task executor running with and without+ * a harness. The harness version adds explicit rules, verification steps,+ * and stop conditions.+ *+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts+ */++// ---------------------------------------------------------------------------+// Types & helpers+// ---------------------------------------------------------------------------++interface TaskResult {+ name: string;+ passed: boolean;+ durationMs: number;+ issues: string[];+}++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++// ---------------------------------------------------------------------------+// Simulated task executor+// ---------------------------------------------------------------------------++/** A simple task that can succeed or fail depending on rules. */+type Task = {+ name: string;+ requiresAuth: boolean;+ hasTests: boolean;+ withinScope: boolean;+};++const tasks: Task[] = [+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },+];++// ---------------------------------------------------------------------------+// Run WITHOUT harness -- just execute every task, no checks+// ---------------------------------------------------------------------------++function runWithoutHarness(taskList: Task[]): TaskResult[] {+ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];++ // The "agent" does the work and calls it done.+ let passed = true;++ // Problems that go undetected without a harness+ if (t.requiresAuth && !t.hasTests) {+ issues.push("No tests for auth-protected endpoint");+ // Agent doesn't notice -- marks as pass anyway+ }+ if (!t.withinScope) {+ issues.push("Task is outside current scope");+ // Agent doesn't notice+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Run WITH harness -- rules, verification, stop conditions+// ---------------------------------------------------------------------------++function runWithHarness(taskList: Task[]): TaskResult[] {+ const rules = {+ requireTestsForAuth: true,+ enforceScope: true,+ };++ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];+ let passed = true;++ // Rule: auth endpoints must have tests+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {+ issues.push("BLOCKED: Auth-protected endpoint missing tests");+ passed = false;+ }++ // Rule: stay in scope+ if (rules.enforceScope && !t.withinScope) {+ issues.push("BLOCKED: Task outside active scope -- skipped");+ passed = false;+ }++ // Verification: re-check after execution+ if (passed && !t.hasTests) {+ issues.push("WARNING: No tests exist for this change");+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function printComparison(+ noHarness: TaskResult[],+ withHarness: TaskResult[]+): void {+ console.log("\n" + "=".repeat(80));+ console.log(" HARNESS vs NO-HARNESS COMPARISON");+ console.log("=".repeat(80));++ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;++ console.log("\n" + header);+ console.log(sep);++ for (let i = 0; i < noHarness.length; i++) {+ const nh = noHarness[i];+ const wh = withHarness[i];+ const nhPass = nh.passed ? "PASS" : "FAIL";+ const whPass = wh.passed ? "PASS" : "FAIL";+ const nhIssue = nh.issues[0] ?? "(none)";+ const whIssue = wh.issues[0] ?? "(none)";++ console.log(+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`+ );+ }++ // Metrics+ const nhPassed = noHarness.filter((r) => r.passed).length;+ const whPassed = withHarness.filter((r) => r.passed).length;+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);++ console.log("\n" + "=".repeat(80));+ console.log(" SUMMARY METRICS");+ console.log("=".repeat(80));++ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log("\n" + metricsHeader);+ console.log(metricsSep);+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);++ console.log("\n The harness catches problems the no-harness run silently ignores.");+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");+}++/** Count tasks that actually pass (have tests and are in scope). */+function truePassCount(results: TaskResult[]): number {+ return results.filter((r) => r.passed && r.issues.length === 0).length;+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparison(runWithoutHarness(tasks), runWithHarness(tasks));diff --git a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/index.mdnew file mode 100644index 0000000..adb8ea5--- /dev/null+++ b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -0,0 +1,8 @@+# 講義 02 のコード++このフォルダーは、以下を区別する小さな例に使用してください:++- モデルの動作+- harness の動作+- プロンプトのみのセットアップ+- 環境に基づくエージェントのセットアップdiff --git a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.tsnew file mode 100644index 0000000..e56cddd--- /dev/null+++ b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts@@ -0,0 +1,36 @@+type Message = {+ role: "user" | "assistant";+ content: string;+};++type ToolResult = {+ ok: boolean;+ output: string;+};++function runTool(name: string, input: string): ToolResult {+ if (name === "read_file") {+ return { ok: true, output: `contents of ${input}` };+ }++ return { ok: false, output: `unknown tool: ${name}` };+}++export function minimalHarness(messages: Message[]) {+ const nextAction = {+ tool: "read_file",+ input: "README.md"+ };++ const result = runTool(nextAction.tool, nextAction.input);++ return {+ messages: [+ ...messages,+ {+ role: "assistant",+ content: `Tool ${nextAction.tool} returned: ${result.output}`+ }+ ]+ };+}diff --git a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.mdnew file mode 100644index 0000000..aaca938--- /dev/null+++ b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -0,0 +1,109 @@+[中文版本 →](../../../zh/lectures/lecture-02-what-a-harness-actually-is/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-02-what-a-harness-actually-is/code/)+> 実践プロジェクト: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# 講義 02. Harness とは何か++「harness」という言葉は AI コーディングエージェントの界隈でよく使われますが、正直なところ、ほとんどの人は harness と言っても「プロンプトファイル」のことを指しています。それは harness ではありません。食材だけを用意してレストランを開くようなものです — コンロも包丁もレシピも盛り付けのワークフローもありません。それはレストランではなく、冷蔵庫です。++この講義では、正確で実践的な harness の定義を提示します。学術的な抽象論ではなく、今日から使えるフレームワークです。harness は 5 つのサブシステムで構成され、それぞれに明確な責任と評価基準があります。++## 例えから始めよう++新しく入社したエンジニアとして、ドキュメントが一切ないプロジェクトに放り込まれたと想像してください。README もなく、コードにコメントもなく、テストの実行方法を教えてくれる人もおらず、CI の設定はどこかに埋もれています。良いコードを書けるでしょうか。もしあなたが十分に賢く、忍耐強ければ、おそらく書けるでしょう。しかし、「このプロジェクトが何なのかを理解する」ことに膨大な時間を費やすことになり、「問題を解決する」ことにはあまり時間が割けません。++AI エージェントも全く同じ状況に直面します。しかも状況はさらに悪いです — あなたは少なくとも同僚に質問できます。エージェントは目の前に置かれたファイルと実行可能なコマンドしか見ることができません。誰かの肩を叩いて「このプロジェクトで使っている ORM のバージョンは何ですか?」と聞くことはできません。++OpenAI は核心となる原則を「リポジトリこそが仕様である」と表現しています — 必要なコンテキストはすべてリポジトリ内に存在し、構造化された指示ファイル、明示的な検証コマンド、明確なディレクトリ構成を通じて提供されるべきだとしています。Anthropic の長時間実行エージェントに関するドキュメントは、状態の永続化、明示的なリカバリパス、構造化された進捗追跡を強調しています。2 社は異なる側面に焦点を当てていますが、言っていることは同じです。**モデルの外側にあるエンジニアリングインフラのすべてが、モデルの能力がどれだけ実際に発揮されるかを決定します。**++すでに知っているツールをいくつか見てみましょう。++**Claude Code** は harness の考え方を体現しています。リポジトリから `CLAUDE.md` を読み込み(レシピ棚)、シェルコマンドを実行でき(包丁ラック)、ローカル環境で実行し(コンロ)、セッション履歴を維持し(仕込み台)、テストを実行して結果を確認できます(品質チェック窓口)。しかし、テストの実行方法を教えなければ、品質チェック窓口は壊れた状態です — 料理がちゃんと火を通っているか誰もわかりません。++**Cursor** も同様のロジックに従っています。`.cursorrules` ファイルがレシピ棚、ターミナルが包丁ラック、プロジェクト構造と lint 設定を読み取ってコンロとして機能させます。ただし、Cursor の状態管理は比較的弱いです — IDE を閉じて再度開くと、以前のコンテキストは消えてしまいます。++**Codex**(OpenAI のコーディングエージェント)は git worktrees を使って各タスクの実行環境を分離し、ローカルのオブザーバビリティスタック(ログ、メトリクス、トレース)と組み合わせることで、すべての変更が独立した環境で検証されます。`AGENTS.md` と明確な検証コマンドがあるリポジトリでは、「素の」リポジトリよりもはるかに良いパフォーマンスを発揮します。++**AutoGPT** は反面教師です — 構造化された状態管理がないため、長時間のタスクでコンテキストが蓄積し、正確なフィードバックメカニズムがないためエージェントがループに陥ります。多くの人が AutoGPT は「動かない」と言いますが、実際には AutoGPT の harness が動いていないのです — 壊れたコンロをシェフに渡せば、どんなに優れた食材でも料理は完成しません。++## 中核概念++- **harness とは何か**: モデルの重みパラメータ以外のエンジニアリングインフラのすべて。OpenAI はエンジニアの中心的な役割を3つに要約しています。環境の設計、意図の表現、フィードバックループの構築です。Anthropic は Claude Agent SDK を「汎用エージェント harness」と呼んでいます。+- **リポジトリが唯一の信頼できる情報源**: エージェントが見られないものは、実質的に存在しません。OpenAI はリポジトリを「system of record」として扱います — 必要なコンテキストはすべてそこに存在し、構造化されたファイルと明確なディレクトリ構成を通じて提供される必要があります。+- **マニュアルではなく地図を与える**: OpenAI の経験 — `AGENTS.md` は百科事典ではなく目次ページであるべきです。100行程度で十分です。収まらない場合は `docs/` ディレクトリに分割し、エージェントが必要に応じて読み込むようにします。+- **細かく管理するのではなく制約を与える**: 良い harness は、実行可能なルールを使ってエージェントを制約し、指示を一つ一つ列挙するのではありません。OpenAI は「不変条件を強制し、実装を細かく管理しない」と述べています。Anthropic は、エージェントが自信満々に自分の仕事を賞賛することを発見し、解決策は「仕事をする人」と「仕事をチェックする人」を分離することだとしています。+- **コンポーネントを一つずつ削除する**: 各 harness コンポーネントの価値を定量化するには、一つずつ削除し、どの削除が最大のパフォーマンス低下を引き起こすかを確認します。Anthropic はこの手法を用い、モデルが強力になるにつれて一部のコンポーネントは重要でなくなるが、常に新しいコンポーネントが必要になることを発見しました。++## 5サブシステム harness モデル++キッチンの例えに戻りましょう。完全なキッチンには5つの機能領域があり、harness には5つのサブシステムがあります。++```mermaid+flowchart LR+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["Tools<br/>shell / files / tests"]+ Tools --> Env["Runtime<br/>deps / services / versions"]+ Env --> Checks["Check results<br/>test / lint / build"]+ Checks --> Agent+```++**指示サブシステム(レシピ棚)**: `AGENTS.md`(または `CLAUDE.md`)を作成し、プロジェクトの概要と目的(1文)、技術スタックとバージョン(Python 3.11、FastAPI 0.100+、PostgreSQL 15)、初回実行コマンド(`make setup`、`make test`)、譲れないハード制約(「すべての API は OAuth 2.0 を使用すること」)、より詳細なドキュメントへのリンクを含めます。++**ツールサブシステム(包丁ラック)**: エージェントが十分なツールアクセスを持つことを確保します。「セキュリティ」のためにシェルを無効にしないでください — エージェントが `pip install` すら実行できないなら、どうやって作業するのでしょうか。しかし、すべてを開放するのも良くありません — 最小権限の原則に従ってください。++**環境サブシステム(コンロ)**: 環境の状態を自己記述的にします。`pyproject.toml` や `package.json` で依存関係をロックし、`.nvmrc` や `.python-version` でランタイムバージョンを指定し、Docker や devcontainers で再現性を確保します。++**状態サブシステム(仕込み台)**: 長時間のタスクには進捗追跡が必要です。シンプルな `PROGRESS.md` ファイルを使って、完了したこと、進行中のこと、ブロックされていることを記録します。各セッションの終了前に更新し、次のセッション開始時に読み込みます。++**フィードバックサブシステム(品質チェック窓口)**: これが最も投資対効果の高いサブシステムです。`AGENTS.md` に検証コマンドを明示的に列挙します。+```+Verification commands:+- Tests: pytest tests/ -x+- Type check: mypy src/ --strict+- Lint: ruff check src/+- Full verification: make check (includes all above)+```++どれか一つのサブシステムが欠けていると、キッチンの機能領域が欠けているのと同じです — 料理はできますが、常に不便です。++**harness の品質診断**: 「等尺性モデル制御」を使用します。モデルを固定し、サブシステムを一つずつ削除し、どの削除が最大のパフォーマンス低下を引き起こすかを測定します。そこがボトルネックです — 努力をそこに集中させます。キッチンのボトルネックを見つけるように、レシピ棚を取り外してどれくらい遅くなるかを確認し、コンロを止めて影響を見ます。++## あるチームの実話++あるチームが GPT-4o を使って TypeScript + React のフロントエンドアプリ(約20,000行)に取り組みました。彼らは4つの段階を経ました — 本質的にはキッチン設備を一つずつ追加していったのです。++**段階1 — 空のキッチン**: README に基本的なプロジェクト説明だけがある状態。5回の試行のうち1回しか成功しませんでした(20%)。主な失敗理由は、間違ったパッケージマネージャーの選択(npm と yarn の混同)、コンポーネント命名規則の非遵守、テストの実行不可でした。++**段階2 — レシピ棚を設置**: `AGENTS.md` に技術スタックのバージョン、命名規則、主要なアーキテクチャ決定を追加。成功率は60%に上昇。残りの失敗は主に環境の問題と検証の欠如でした。++**段階3 — 品質チェック窓口を開設**: `AGENTS.md` に検証コマンドを列挙: `yarn test && yarn lint && yarn build`。成功率は80%に上昇。++**段階4 — 仕込み台を準備**: エージェントが各実行で完了した作業と未完了の作業を記録する進捗ファイルテンプレートを導入。成功率は80〜100%で安定。++4回の反復で、モデルは全く変更していませんが、成功率は20%からほぼ100%になりました。これが harness engineering の力です。より高価な食材を買ったのではなく、キッチンを適切に整理しただけです。++## 重要なポイント++- Harness = 指示 + ツール + 環境 + 状態 + フィードバック。5つのサブシステムは、キッチンの5つの機能領域のように — すべて不可欠です。+- モデルの重みパラメータでないものは、すべて harness です。あなたの harness がモデルの能力をどれだけ発揮させるかを決定します。+- 5つのサブシステムの中で、フィードバックサブシステムは通常、最も投資が少なく最もリターンが大きいです。まず検証コマンドを正しく設定しましょう — 品質チェック窓口は最も価値のあるアップグレードです。+- 「等尺性モデル制御」を使って各サブシステムの限界貢献を定量化しましょう — 感覚に頼ってはいけません。+- Harness はコードと同じように腐敗します。定期的に監査し、技術的負債を返済するように harness の負債も返済しましょう。++## 参考資料++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)++## 演習++1. **5要素 harness 監査**: AI エージェントを使用しているプロジェクトを取り上げ、5要素フレームワークを使って完全な監査を行います。各サブシステムを1〜5で評価します。最も低いスコアのサブシステムを見つけ、30分かけて改善し、その後エージェントのパフォーマンスの変化を観察してください。++2. **等尺性モデル制御実験**: 1つのモデルと1つの難しいタスクを選びます。順番に指示を削除し(AGENTS.md を削除)、フィードバックを削除し(検証コマンドを提供しない)、状態を削除し(進捗ファイルなし) — 一度に1つだけ削除してパフォーマンスの低下を測定します。結果に基づいて、プロジェクトにおけるサブシステムの重要度をランク付けしてください。++3. **アフォーダンス分析**: プロジェクトでエージェントが「何かをしたいのにできない」シナリオを見つけます(例: パラメータ化クエリを使うべきだと知っているが、プロジェクトの ORM パターンを知らない)。これが実行のギャップ(方法がわからない)か評価のギャップ(正しいかどうかわからない)かを分析し、それを埋める harness の改善を設計してください。diff --git a/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdnew file mode 100644index 0000000..660744c--- /dev/null+++ b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md@@ -0,0 +1,7 @@+# 講義 03 のコード++このフォルダーは、以下の例に使用してください:++- エージェントが読み取れるリポジトリ構造+- ドキュメントを記録システム(system of record)として扱う方法+- ナレッジの配置の良し悪しdiff --git a/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txtnew file mode 100644index 0000000..45315da--- /dev/null+++ b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt@@ -0,0 +1,13 @@+AGENTS.md+docs/+ ARCHITECTURE.md+ PRODUCT.md+ RELIABILITY.md+ references/+ electron.md+ sqlite.md+ plans/+ active/+ completed/+src/+scripts/diff --git a/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.tsnew file mode 100644index 0000000..46f6a62--- /dev/null+++ b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts@@ -0,0 +1,189 @@+/**+ * repo-reader.ts+ *+ * Reads a directory structure and scores it on discoverability.+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,+ * handoff files, and other signals of a repository that serves as the+ * system of record.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]+ * (defaults to current working directory if no path given)+ *+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Scoring criteria+// ---------------------------------------------------------------------------++interface Check {+ name: string;+ description: string;+ maxPoints: number;+ check: (dir: string) => { points: number; found: string[]; missing: string[] };+}++const checks: Check[] = [+ {+ name: "AGENTS.md / CLAUDE.md",+ description: "Agent-readable instruction file at repo root",+ maxPoints: 15,+ check: (dir) => {+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };+ },+ },+ {+ name: "Documentation directory",+ description: "Dedicated docs/ or documentation/ directory",+ maxPoints: 10,+ check: (dir) => {+ const candidates = ["docs", "documentation", "doc"];+ const found = candidates.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };+ },+ },+ {+ name: "Architecture documentation",+ description: "Files describing system architecture",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",+ "docs/architecture/", "design.md", "DESIGN.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };+ },+ },+ {+ name: "Feature tracking",+ description: "Feature list or task tracking file",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "feature_list.json", "features.md", "FEATURES.md",+ "docs/features.md", "tasks.json", "TODO.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };+ },+ },+ {+ name: "Handoff / session continuity",+ description: "Files for multi-session continuity",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",+ "docs/handoff.md", ".handoff", "PROGRESS.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };+ },+ },+ {+ name: "Testing structure",+ description: "Test directory or test configuration",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["test", "tests", "__tests__", "spec"];+ const found = patterns.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };+ },+ },+ {+ name: "Configuration files",+ description: "Project config (package.json, tsconfig, etc.)",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };+ },+ },+ {+ name: "README",+ description: "Root README file",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["README.md", "README.rst", "README.txt", "README"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };+ },+ },+];++// ---------------------------------------------------------------------------+// Report generation+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function scoreRepo(targetDir: string): void {+ const resolved = path.resolve(targetDir);++ if (!fs.existsSync(resolved)) {+ console.error(` Error: Directory not found: ${resolved}`);+ process.exit(1);+ }++ console.log("\n" + "=".repeat(80));+ console.log(" REPOSITORY DISCOVERABILITY SCORE");+ console.log("=".repeat(80));+ console.log(` Target: ${resolved}\n`);++ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ let totalScore = 0;+ let maxScore = 0;++ for (const check of checks) {+ const result = check.check(resolved);+ totalScore += result.points;+ maxScore += check.maxPoints;+ const status = result.points > 0 ? "PASS" : "FAIL";+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];++ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);+ }++ // Final score+ console.log("\n" + "-".repeat(80));+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);++ // Grade+ const pct = totalScore / maxScore;+ let grade: string;+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";+ else grade = "F -- Repository lacks discoverability signals";++ console.log(` GRADE: ${grade}`);+ console.log("=".repeat(80) + "\n");+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const target = process.argv[2] || process.cwd();+scoreRepo(target);diff --git a/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.mdnew file mode 100644index 0000000..539e4ef--- /dev/null+++ b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md@@ -0,0 +1,11 @@+# 記録システム(System of Record)チェックリスト++新しいエージェントは、リポジトリだけから以下を発見できるか?++- どのような製品が構築されているか?+- アプリはユーザーのために何をすべきか?+- コードベースはどのように整理されているか?+- アプリはどのように起動するか?+- 正常性はどのように確認するか?+- 現在どのような作業が進行中か?+- どのような品質基準が重要か?diff --git a/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdnew file mode 100644index 0000000..a0efc2c--- /dev/null+++ b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -0,0 +1,137 @@+[中文版本 →](../../../zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)+> 実践プロジェクト: [プロジェクト 02. エージェントが読めるワークスペース](./../../projects/project-02-agent-readable-workspace/index.md)++# 講義 03. リポジトリを唯一の信頼できる情報源にする++あなたのチームのアーキテクチャ判断は、Confluence、Slack、Jira、そして数人のシニアエンジニアの頭の中に散らばっている。人間にとっては、これはぎりぎり機能する。同僚に聞けるし、チャット履歴を検索できるし、ドキュメントを掘り返せる。どうにもならなければ、休憩室で誰かを捕まえることもできる。しかし AI エージェントにとって、リポジトリに存在しない情報は、単に存在しない。++これは誇張ではない。エージェントの入力が実際に何かを考えてみよう。システムプロンプトとタスク説明、リポジトリ内のファイル内容、ツール実行の出力。それだけだ。Slack 履歴、Jira チケット、Confluence ページ、金曜午後に同僚とコーヒーを飲みながら話したアーキテクチャ判断。エージェントにはどれも見えない。「誰かに聞きに行く」ことも「チャット履歴を検索する」こともできない。リポジトリの中に閉じ込められたエンジニアであり、外側のことは何も知らない。++では問いはこうなる。このエンジニアに、よい地図を渡すつもりはあるか?++## 地図に載せるべきもの++OpenAI はこれをはっきり述べている。**リポジトリに存在しない情報は、エージェントにとって存在しない。** 彼らはこれを "repo as spec" 原則と呼ぶ。リポジトリ自体が、最も権威ある仕様書である。++Anthropic の長時間実行エージェントに関するドキュメントも同じことを示している。永続状態は、長いタスクの連続性に必要な条件だ。セッションをまたいで知識を回復できるかどうかが、タスク成功率を直接左右する。そしてその状態はリポジトリ内に存在しなければならない。エージェントにとって、そこだけが安定してアクセスできるストレージだからだ。++「うちのチームは小さいし、知識はみんなの頭の中にあって、それでうまく回っている」と思うかもしれない。人間にとってはそうだろう。しかしエージェントを使うなら、この事実を受け入れる必要がある。エージェントは人に聞けない。知る必要があることはすべて書き出し、見つけられる場所に置かなければならない。++これは「もっとドキュメントを書こう」という話ではない。「意思決定情報を正しい場所に置こう」という話だ。`src/api/` ディレクトリにある 50 行の `ARCHITECTURE.md` は、誰も保守していない Confluence の 500 ページ設計書より 1 万倍役に立つ。机に貼った手描きのオフィス地図と、ファイルキャビネットに鍵をかけてしまった美しい建築図面の違いだ。前者は必要なとき目の前にある。後者は技術的には優れていても、その瞬間には役に立たない。++## 知識の可視性++```mermaid+flowchart LR+ Slack["Slack 内のルール"] --> Write["リポジトリファイルへ書く<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Confluence 内のルール"] --> Write+ Heads["人の頭の中のルール"] --> Write+ Jira["Jira チケット内のルール"] --> Write+ Write --> Repo["リポジトリファイル"]+ Repo --> Agent["新しいエージェントセッション<br/>リポジトリを直接読む"]+ Warning["ルールがリポジトリにないなら<br/>エージェントには見えない"] --> Agent+```++地図が十分かどうかはどう検証するか? 「コールドスタートテスト」を実行する。リポジトリ内容だけを使うまったく新しいエージェントセッションを開き、次の 5 つの基本質問に答えられるかを見る。++```mermaid+flowchart TB+ Q1["このシステムは何か?"] --> A1["AGENTS.md / README"]+ Q2["どう構成されているか?"] --> A2["ARCHITECTURE.md / モジュールドキュメント"]+ Q3["どう実行するか?"] --> A3["Makefile / init.sh / package scripts"]+ Q4["どう検証するか?"] --> A4["Test、lint、check コマンド"]+ Q5["現在どこまで進んでいるか?"] --> A5["PROGRESS.md / feature list / git history"]++ A1 --> Ready["新しいセッションが<br/>人に聞かず作業を開始できる"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready+```++答えられないなら、地図に空白がある。地図が空白の場所では、エージェントは推測する。間違った推測はバグになり、過剰な推測はコンテキストを浪費する。そして新しいセッションのたびに、同じ推測をやり直す。推測のコストは、最初から地図をきちんと描くコストより常に高い。++## 中核概念++- **Knowledge Visibility Gap**: プロジェクト知識全体のうち、リポジトリに存在しないものの割合。ギャップが大きいほどエージェントの失敗率は上がる。このプロジェクトについて、あなたの頭の中にある暗黙知はいくつあるか。全部数え、そのうちどれだけがリポジトリに入っているかを見る。その差が可視性ギャップだ。+- **System of Record**: プロジェクト判断、アーキテクチャ制約、実行状態、検証基準の権威ある情報源としてのコードリポジトリ。最終判断はリポジトリにあり、それ以外は数えない。「通行止め」と書かれた地図のようなものだ。その道には行かない。しかしその情報が誰か一人の頭の中にしかないなら、毎回その人に聞く必要がある。+- **Cold-Start Test**: 上の 5 つの質問。いくつ答えられるかが、地図の完成度を示す。+- **Discovery Cost**: エージェントがリポジトリ内で重要情報を見つけるために消費するコンテキスト予算。情報が隠れているほど discovery cost は高くなり、実タスクに残る予算は少なくなる。重要情報を 10 階層下の README に隠すのは、消火器を地下の金庫にしまうようなものだ。存在はするが、必要なとき見つけられない。+- **Knowledge Decay Rate**: 知識項目が単位時間あたりに古くなる割合。ドキュメントがコードと同期しなくなることが最大の敵だ。ドキュメントがないより悪い。エージェントを間違った方向へ進ませるのに、エージェントは自分が正しいと思ってしまう。+- **ACID Analogy**: データベーストランザクションの原則(Atomicity、Consistency、Isolation、Durability)をエージェント状態管理に適用する考え方。下で詳しく説明する。++## よい地図の描き方++**原則 1: 知識はコードの近くに置く。** API エンドポイント認証に関するルールは、巨大なグローバル文書に埋めるのではなく、API コードの近くに置くべきだ。各モジュールディレクトリに短いドキュメントを置き、そのモジュールの責務、インターフェース、特別な制約を説明する。図書館の棚ラベルのようなものだ。歴史の本が欲しければ「History」と書かれた棚に行けばよい。図書館全体を探す必要はない。++**原則 2: 標準化された入口ファイルを使う。** `AGENTS.md`(または `CLAUDE.md`)はエージェントのランディングページだ。すべての情報を含む必要はないが、「このプロジェクトは何か」「どう実行するか」「どう検証するか」という 3 つの質問に素早く答えられなければならない。50-100 行で十分だ。++**原則 3: 最小だが完全にする。** すべての知識には明確な用途が必要だ。あるルールを削除してもエージェントの判断品質に影響がないなら、そのルールは存在すべきではない。しかしコールドスタートテストのすべての質問には答えが必要だ。多すぎず、少なすぎず、必要十分にするという繊細なバランスだ。++**原則 4: コードと一緒に更新する。** 知識更新をコード変更に結びつける。最も単純な方法は、アーキテクチャドキュメントを対応モジュールのディレクトリに置くことだ。コードを変更するとき、そのドキュメントを自然に目にする。コード変更後、CI がドキュメント更新の必要性を確認するよう促すこともできる。++**具体的なリポジトリ構造**:++```+project/+├── AGENTS.md # Entry: project overview, run commands, hard constraints+├── src/+│ ├── api/+│ │ ├── ARCHITECTURE.md # API layer architecture decisions+│ │ └── ...+│ ├── db/+│ │ ├── CONSTRAINTS.md # Database operation hard constraints+│ │ └── ...+│ └── ...+├── PROGRESS.md # Current progress: done, in-progress, blocked+└── Makefile # Standardized commands: setup, test, lint, check+```++## ACID 原則でエージェント状態を管理する++この比喩はデータベースのトランザクション管理から来ている。複雑にしすぎだと思うかもしれないが、実際にはかなり実用的な枠組みを与えてくれる。++- **Atomicity**: 各「論理操作」(例: 「新しいエンドポイントを追加し、テストを更新する」)を 1 つの git commit にする。途中で失敗したら `git stash` で戻す。全部やるか、何もやらないか。「半分だけ完了」はない。+- **Consistency**: 「一貫した状態」を検証する述語を定義する。すべてのテストが通る、lint エラーがゼロ、など。エージェントは各操作後に検証を実行し、一貫しない中間状態は commit しない。銀行振込のように、引き落としだけして入金しないことはできない。+- **Isolation**: 複数のエージェントが同時に作業するときは、状態ファイルが競合しないよう設計する。単純な方法は、各エージェントに独自の progress ファイルを使わせるか、git branch で分離することだ。2 人の料理人が同じ鍋に同時に味付けすることはできない。塩辛くなったら誰が責任を取るのか?+- **Durability**: 重要なプロジェクト知識は git 管理されたファイルに置く。一時状態はセッションメモリでもよいが、セッションをまたぐ知識はファイルに永続化する必要がある。頭の中にあるものは数えない。紙に書かれたものだけを数える。++## 実際の変革事例++あるチームは、約 30 個のマイクロサービスを持つ e コマース基盤を保守していた。アーキテクチャ判断(サービス間通信プロトコル、データ整合性戦略、API バージョニング規則)は、Confluence(一部古い)、Slack(検索しづらい)、数人のシニアエンジニアの頭の中(スケールしない)、散発的なコードコメント(体系的ではない)に散らばっていた。++AI エージェント導入後、タスクの 70% が人間の介入を必要とした。ほぼすべての失敗は、「みんな知っているが誰も書いていない」暗黙制約にエージェントが違反したことに関係していた。新入社員に「昼食注文はグループチャットに投稿する必要がある」と誰も教えないようなものだ。本人は間違って推測し、叱られる。しかし叱ったあとも、誰もそのルールを書かない。++チームは変革を実行した。+1. リポジトリルートに `AGENTS.md` を作成し、プロジェクト概要、技術スタックのバージョン、グローバルな強制制約を記載+2. 各マイクロサービスディレクトリに `ARCHITECTURE.md` を追加し、責務、インターフェース、依存関係を説明+3. 明示的な "MUST/MUST NOT" 表現でハード制約をまとめた中央 `CONSTRAINTS.md` を作成+4. 各サービスディレクトリに `PROGRESS.md` を追加し、現在の作業状態を追跡++変革後、同じエージェントはコールドスタートで重要なプロジェクト質問すべてに答えられるようになり、タスク完了品質は大きく改善した。++## 重要なポイント++- リポジトリにない知識は、エージェントにとって存在しない。重要な判断をリポジトリに置くことは、最も基本的な harness 投資だ。迷わないように、よい地図を描く。+- リポジトリ品質の評価には「コールドスタートテスト」を使う。新しいセッションがリポジトリ内容だけで 5 つの基本質問に答えられるか?+- 知識はコードの近くに、最小だが完全に、そしてコードと一緒に更新されるべきだ。これはドキュメント量を増やす話ではなく、情報を正しい場所に置く話だ。+- エージェント状態には ACID 原則を使う。atomic な commit、一貫性検証、並行作業の分離、重要知識の永続化。+- 知識の劣化が最大の敵だ。コードと同期していないドキュメントは、ドキュメントがないより危険だ。エージェントを間違った方向に進ませながら、エージェント自身には正しいと思わせてしまう。++## 参考資料++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [ADR: Architecture Decision Records](https://adr.github.io/)+- [The Twelve-Factor App](https://12factor.net/)++## 演習++1. **コールドスタートテスト**: プロジェクトで完全に新しいエージェントセッションを開く(口頭コンテキストなし、リポジトリ内容のみ)。5 つの質問をする。このシステムは何か? どう構成されているか? どう実行するか? どう検証するか? 現在の進捗は? 答えられなかったものを記録し、答えられるようになるまでリポジトリを改善する。++2. **知識外部化の定量化**: プロジェクトの開発作業に重要な判断と制約をすべて列挙する。それぞれがリポジトリ内にあるか外にあるかを印づけする。Knowledge Visibility Gap(リポジトリ外の割合)を計算し、10% 未満に下げる計画を立てる。++3. **ACID 評価**: この講義の ACID 比喩で、プロジェクトの状態管理を評価する。Atomicity - エージェント操作をきれいにロールバックできるか? Consistency - 「一貫した状態」の検証があるか? Isolation - 並行エージェントが互いに踏み合わないか? Durability - セッションをまたぐ知識はすべて永続化されているか?diff --git a/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdnew file mode 100644index 0000000..6f34e05--- /dev/null+++ b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -0,0 +1,15 @@+# AGENTS.md++## まずここから++- `docs/ARCHITECTURE.md` を読む+- `docs/PRODUCT.md` を読む+- `npm run dev` でアプリを起動する+- 作業を完了とマークする前に `npm run check` を実行する++## 厳格なルール++- `docs/ARCHITECTURE.md` を読まずに Electron の main/preload/renderer の境界を+ 変更しない+- 検証なしに機能を完了とマークしない+- 次のセッションのためにクリーンな状態を残すdiff --git a/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdnew file mode 100644index 0000000..a5f0980--- /dev/null+++ b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -0,0 +1,7 @@+# 指示ファイルのアンチパターン++- リポジトリのすべての知識を 1 つのファイルに詰め込む+- 同じルールを複数の場所で繰り返す+- 誰も監査しない古いルールを残す+- ほとんど適用されないほど具体的な条件付き指示を書く+- 起動コンテキストに長いツールマニュアルを組み込むdiff --git a/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdnew file mode 100644index 0000000..978d4c3--- /dev/null+++ b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md@@ -0,0 +1,7 @@+# 講義 04 のコード++このフォルダーは、以下の例に使用してください:++- 単一の巨大な指示ファイル+- 短いエントリポイント+- 段階的開示(progressive disclosure)パターンdiff --git a/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.tsnew file mode 100644index 0000000..59a9632--- /dev/null+++ b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts@@ -0,0 +1,209 @@+/**+ * split-vs-monolithic.ts+ *+ * Creates a monolithic instruction file (~200 lines) and then shows how+ * splitting into 4 focused files dramatically reduces the context needed+ * for any single query. Simulates an "agent" searching for a specific rule+ * and measures how many lines it must read in each approach.+ *+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts+ */++// ---------------------------------------------------------------------------+// Simulated monolithic instruction file (200 lines of rules)+// ---------------------------------------------------------------------------++const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];++// Section 1: Project Overview (lines 1-50)+for (let i = 1; i <= 50; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Project Overview",+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,+ });+}++// Section 2: Code Style Rules (lines 51-100)+for (let i = 51; i <= 100; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Code Style",+ content:+ i === 72+ ? "RULE: Always use explicit return types on exported functions."+ : i === 78+ ? "RULE: Use const assertions for immutable arrays."+ : `Style rule detail line ${i}`,+ });+}++// Section 3: Testing Standards (lines 101-150)+for (let i = 101; i <= 150; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Testing",+ content:+ i === 120+ ? "RULE: Every new endpoint must have integration tests."+ : i === 135+ ? "RULE: Test files must mirror the source file structure."+ : `Testing detail line ${i}`,+ });+}++// Section 4: Deployment Rules (lines 151-200)+for (let i = 151; i <= 200; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Deployment",+ content:+ i === 175+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."+ : `Deployment detail line ${i}`,+ });+}++// ---------------------------------------------------------------------------+// Split instruction files (4 focused files)+// ---------------------------------------------------------------------------++const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),+};++// ---------------------------------------------------------------------------+// Simulated queries -- the agent needs to find specific rules+// ---------------------------------------------------------------------------++interface Query {+ description: string;+ targetRule: string;+ relevantSection: string;+}++const queries: Query[] = [+ {+ description: "Find the rule about return types",+ targetRule: "explicit return types",+ relevantSection: "Code Style",+ },+ {+ description: "Find the deployment window rule",+ targetRule: "deploy on Fridays",+ relevantSection: "Deployment",+ },+ {+ description: "Find the integration test rule",+ targetRule: "integration tests",+ relevantSection: "Testing",+ },+ {+ description: "Find the test file structure rule",+ targetRule: "mirror the source file",+ relevantSection: "Testing",+ },+];++// ---------------------------------------------------------------------------+// Search simulation+// ---------------------------------------------------------------------------++function searchMonolithic(query: Query): { linesRead: number; found: boolean } {+ // Agent must scan from the top, reading each line until it finds the rule.+ // In the worst case it reads all lines.+ let linesRead = 0;+ let found = false;++ for (const line of monolithicInstructions) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found };+}++function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {+ // Agent knows which file to look in based on the section.+ // It only reads lines from that one file.+ const fileMap: Record<string, string> = {+ "Project Overview": "01-project-overview.md",+ "Code Style": "02-code-style.md",+ Testing: "03-testing.md",+ Deployment: "04-deployment.md",+ };++ const targetFile = fileMap[query.relevantSection];+ const lines = splitInstructions[targetFile];+ let linesRead = 0;+ let found = false;++ for (const line of lines) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found, fileAccessed: targetFile };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");+ console.log("=".repeat(90));++ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");++ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;+ console.log(header);+ console.log(sep);++ let totalMono = 0;+ let totalSplit = 0;++ for (const q of queries) {+ const mono = searchMonolithic(q);+ const split = searchSplit(q);+ totalMono += mono.linesRead;+ totalSplit += split.linesRead;++ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);+ console.log(+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`+ );+ }++ console.log(sep);+ const avgMono = Math.round(totalMono / queries.length);+ const avgSplit = Math.round(totalSplit / queries.length);+ console.log(+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`+ );++ console.log("\n" + "=".repeat(90));+ console.log(" KEY INSIGHT");+ console.log("=".repeat(90));+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");+}++run();diff --git a/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdnew file mode 100644index 0000000..a1bf3ef--- /dev/null+++ b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -0,0 +1,132 @@+[中文版本 →](../../../zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)+> 実践プロジェクト: [プロジェクト 02. エージェントが読めるワークスペース](./../../projects/project-02-agent-readable-workspace/index.md)++# 講義 04. 指示を複数ファイルに分割する++あなたは Harness Engineering に本気で取り組み始めた。`AGENTS.md` を作り、思いつく限りのルール、制約、学びをすべて詰め込んだ。1か月後には 300 行、2か月後には 450 行、3か月後には 600 行に膨れ上がった。そして気づく。エージェントの性能がむしろ悪くなっている。単純なバグ修正でも、関係のないデプロイ手順を読むために大量のコンテキストを消費する。300 行目に埋もれた重要なセキュリティ制約は完全に無視される。矛盾する 3 つのコードスタイル規則があり、エージェントは毎回ランダムに 1 つを選ぶ。++これが「巨大な指示ファイル」の罠だ。スーツケースに荷物を詰め込みすぎるのに似ている。どれも役に立ちそうだから、ファスナーがはち切れそうになるまで全部入れてしまう。替えの下着を探すだけで、バッグ全体を空にしなければならない。満杯のスーツケースを運んでいるのに、実際に使うのは中身の 3 分の 1 くらいだ。++## 根本にある悪循環++最もよくある悪循環はこうだ。エージェントがミスをする。あなたは「これを防ぐルールを追加しよう」と考え、`AGENTS.md` に追加する。一時的には効く。するとエージェントが別のミスをする。またルールを追加する。これを繰り返し、ファイルは制御不能に膨れ上がる。++これはあなたのせいではない。何かがうまくいかないたびに「ルールを追加する」のは、とても自然な反応だ。家を出るたびに「念のため」と荷物を 1 つ追加するようなものだ。しかし累積効果は破滅的になる。具体的に何が壊れるのかを見ていこう。++**コンテキスト予算が食い尽くされる。** エージェントのコンテキストウィンドウは有限だ。たとえば 200K トークンのウィンドウがあるとする(Claude の標準的な規模)。肥大化した指示ファイルは 10-20K トークンを消費するかもしれない。まだ十分余裕があるように見えるだろうか? しかし複雑なタスクでは多数のソースファイルを読む必要があり、ツール実行結果もコンテキストを使い、会話履歴も蓄積する。エージェントがコードを理解する段階では、すでに予算が厳しくなっている。まるで「念のため」の荷物でいっぱいになり、ノート PC を入れる場所がなくなったスーツケースだ。++**真ん中で失われる。** "Lost in the Middle" 論文(Liu et al., 2023)は、LLM が長いテキストの中央にある情報を、冒頭や末尾の情報より大幅にうまく使えないことを明確に示した。あなたの `AGENTS.md` が 600 行あり、300 行目に「すべてのデータベースクエリはパラメータ化クエリを使うこと」と書かれているとする。これはセキュリティ上の強い制約だ。しかし真ん中に埋もれているため、エージェントはかなりの確率で無視する。詰め込みすぎたスーツケースの底にある日焼け止めのようなものだ。そこにあるのは分かっている。3 回探す。でも見つからず、結局もう 1 本買う。++**優先順位が衝突する。** ファイルには、交渉不能な強制制約("never use eval()")、重要な設計指針("prefer functional style")、特定の過去の教訓("先週 WebSocket のメモリリークを直したので類似パターンに注意")が混ざっている。この 3 つは重要度がまったく違うのに、ファイル上では同じように見える。エージェントには見分ける信頼できるシグナルがない。スーツケースの中でパスポートと充電ケーブルが一緒くたになっていて、どちらがより緊急か分からない状態だ。++**保守が劣化する。** 大きなファイルは本質的に保守しにくい。古い指示はなかなか削除されない。削除の影響が不確かだからだ(「何かがこのルールに依存しているかもしれない」)。一方で、新しい指示を追加するのは無料に感じる。その結果、ファイルは大きくなる一方で小さくならず、信号対雑音比は下がり続ける。これはソフトウェアにおける技術的負債の蓄積そのものだ。++**矛盾が蓄積する。** 異なる時期に追加された指示が互いに矛盾し始める。片方は「TypeScript strict mode を使う」と言い、もう片方は「一部のレガシーファイルでは any 型を許可する」と言う。エージェントは毎回ランダムにどちらかを選ぶ。母親が「暖かくして行きなさい」と言い、父親が「着込みすぎるな」と言い、玄関で誰の言うことを聞けばよいか分からないようなものだ。++## 中核概念++- **Instruction Bloat**: 指示ファイルがコンテキストウィンドウの 10-15% を超えると、コード読解とタスク推論の予算を圧迫し始める。600 行の `AGENTS.md` は 10,000-20,000 トークンを消費し得る。128K ウィンドウなら、エージェントが作業を始める前に 8-15% が消える。+- **Lost in the Middle Effect**: Liu et al. の 2023 年の研究は、LLM が長文の中央にある情報を、冒頭や末尾の情報より大幅に使いにくいことを示した。600 行ファイルの 300 行目に埋もれた重要制約は、実質的に無視される確率が高い。+- **Instruction Signal-to-Noise Ratio (SNR)**: ファイル内の指示のうち、現在のタスクに関係するものの割合。バグ修正中に 50 行のデプロイ手順を読まされるなら、それは低 SNR だ。+- **Routing File**: すべてを内包するのではなく、詳細ドキュメントへの道案内を主目的とする短い入口ファイル。50-200 行で十分だ。+- **Progressive Disclosure**: まず概要を与え、必要になった時点で詳細を与える。よい Harness 設計はよい UI 設計に似ている。すべての選択肢を一度に投げつけない。+- **Priority Ambiguity**: すべての指示が同じ形式・同じ場所にあると、エージェントは交渉不能な強制制約と提案的なガイドラインを区別できない。++## 指示アーキテクチャ++```mermaid+flowchart LR+ Mono["600 行の AGENTS.md 1 つ"] --> MonoLoad["小さなバグ修正でも<br/>デプロイ規則と古いメモを読む必要がある"]+ MonoLoad --> MonoRisk["真ん中に埋もれた重要規則は<br/>見落とされやすい"]++ Router["短い AGENTS.md"] --> Topics["必要なときだけ API / DB / testing docs を読む"]+ Topics --> RoutedResult["コード読解と検証に使える<br/>コンテキストが増える"]+```++```mermaid+flowchart TB+ File["600 行の指示ファイル"] --> Top["冒頭セクション<br/>quick start + 強制制約"]+ File --> Mid["中央セクション<br/>300 行目の重要セキュリティ規則"]+ File --> Bot["末尾セクション<br/>明示的な終了チェックリスト"]+ Top --> Seen["思い出される確率が高い"]+ Bot --> Seen+ Mid --> Missed["薄まる、または見落とされる確率が高い"]+```++## 分割方法++基本原則は、頻繁に必要な情報は手元に置き、ときどき必要な情報はしまっておき、使わない情報は残さないことだ。++入口ファイル `AGENTS.md` は 50-200 行に保ち、最も頻繁に使うものだけを含める。プロジェクト概要(1-2 文)、初回実行コマンド(`make setup && make test`)、グローバルな強制制約(交渉不能な規則は 15 個以下)、トピック別ドキュメントへのリンク(1 行説明 + 適用条件)だ。++```markdown+# AGENTS.md++## プロジェクト概要+Python 3.11 FastAPI backend, PostgreSQL 15 database.++## Quick Start+- Install: `make setup`+- Test: `make test`+- Full verification: `make check`++## Hard Constraints+- All APIs must use OAuth 2.0 authentication+- All database queries must use SQLAlchemy 2.0 syntax+- All PRs must pass pytest + mypy --strict + ruff check++## Topic Docs+- [API Design Patterns](docs/api-patterns.md) — Required reading when adding endpoints+- [Database Rules](docs/database-rules.md) — Required when modifying database operations+- [Testing Standards](docs/testing-standards.md) — Reference when writing tests+```++各トピック文書は 50-150 行にし、`docs/` ディレクトリか対応モジュールの近くで主題ごとに整理する。エージェントは必要なときだけ読む。スーツケースのパッキングキューブのようなものだ。下着は 1 つ、洗面用品は別、充電器はさらに別。探し物のためにバッグ全体を空にする必要はない。++一部の情報はコードの中に直接置いたほうがよい。型定義、インターフェースコメント、設定ファイル内の説明などだ。エージェントはコードを読むとき自然にそれらを見るため、指示に重複させる必要はない。++すべての指示には、由来(「なぜこのルールが追加されたのか」)、適用条件(「いつ必要なのか」)、失効条件(「どの状況なら削除できるのか」)を持たせるべきだ。定期的に監査し、古いもの、重複したもの、矛盾したものを削除する。指示はコード依存関係と同じように管理する。使っていない依存は削除すべきで、残しておくとシステムを遅くするだけだ。++どうしても入口ファイルに置く必要がある指示は、冒頭か末尾に置く。中央には置かない。"lost in the middle" 効果が示すように、LLM は中央よりも両端の情報を大幅にうまく使う。ただし、よりよい方法は、必要時に読むトピック文書へ移すことだ。++OpenAI と Anthropic はどちらも、暗黙に分割アプローチを支持している。OpenAI は入口ファイルを「短く、ルーティング中心」にすべきだと言い、Anthropic は長時間実行エージェントの制御情報を「簡潔で高優先度」にすべきだと言う。どちらも同じことを言っている。すべてを 1 ファイルに詰め込むな。スーツケースに必要なのは整理であって、力任せに押し込むことではない。++## 実例++ある SaaS チームの `AGENTS.md` は 50 行から 600 行に膨れ上がった。中身は、技術スタックのバージョン、コーディング規約、過去のバグ修正メモ、API 利用ガイド、デプロイ手順、チームメンバー個人の好みまで混在していた。スーツケース全体がはち切れそうな状態だ。++エージェントの性能は目に見えて低下し始めた。単純なバグ修正の間に、関係のないデプロイ指示の処理で大量のコンテキストを使う。セキュリティ制約「すべてのデータベースクエリはパラメータ化クエリを使う」は 300 行目に埋もれ、頻繁に無視される。矛盾する 3 つのコードスタイル規則が、エージェントの行動をランダムにする。++チームは「スーツケースの再整理」を実行した。+1. `AGENTS.md` を 80 行に削減。プロジェクト概要、実行コマンド、15 個のグローバル強制制約だけにした+2. トピック文書を作成: `docs/api-patterns.md`(120 行)、`docs/database-rules.md`(60 行)、`docs/testing-standards.md`(80 行)+3. ルーティングファイルにトピック文書リンクを追加+4. 過去メモはテストケースに変換するか削除++リファクタ後、同じタスク群の成功率は 45% から 72% に上がった。セキュリティ制約の遵守率は 60% から 95% になった。理由は、その制約がファイル中央からルーティングファイル冒頭へ移り、もはや「真ん中で失われ」なくなったからだ。++## 重要なポイント++- 「ルールを追加する」は短期的な鎮痛剤であり、長期的には毒になる。ルールを追加する前に問うこと: これはトピック文書のほうがよいのではないか? スーツケースに詰め込み続けてはいけない。+- 入口ファイルはルーターであり、百科事典ではない。50-200 行で、概要、強制制約、リンクだけにする。+- "lost in the middle" 効果を利用する。重要情報は冒頭か末尾へ。重要でない情報はトピック文書へ移す。+- 指示の肥大化は技術的負債として管理する。定期監査を行い、すべての指示に由来、適用条件、失効条件を持たせる。+- 分割後は SNR が改善し、エージェントは関係のない指示処理ではなく、実際のタスクにより多くのコンテキスト予算を使える。++## 参考資料++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)++## 演習++1. **SNR 監査**: 現在の入口指示ファイルを取り出し、すべての指示項目を一覧化する。よくあるタスク種別を 5 つ選び、それぞれの指示がそのタスクに関係するかを印づけする。タスク種別ごとに SNR を計算する。多くのタスクでノイズになる指示はトピック文書へ移す。++2. **Progressive disclosure リファクタ**: 300 行を超える指示ファイルがあるなら、(a) 100 行未満のルーティングファイル、(b) 3-5 個のトピック文書に分割する。分割前後で同じタスク群(少なくとも 5 件)を実行し、成功率を比較する。++3. **Lost in the middle 検証**: 長い指示ファイルの冒頭、中央、末尾にそれぞれ重要制約を置き、同じタスク群を実行する(各位置で少なくとも 5 回)。遵守率に差があるか確認する。位置効果の強さに驚くかもしれない。diff --git a/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.mdnew file mode 100644index 0000000..092412e--- /dev/null+++ b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md@@ -0,0 +1,6 @@+# 継続性チェックリスト++- 新しいエージェントは5分以内に最近の作業を特定できるか?+- 現在の安定した起動パスは文書化されているか?+- 未完了の作業は明確に特定されているか?+- 古いチャットログを読まずに次に最適なタスクが見えるか?diff --git a/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdnew file mode 100644index 0000000..8be7f5f--- /dev/null+++ b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md@@ -0,0 +1,7 @@+# 講義 05 のコード++このフォルダーは、以下の例に使用してください:++- 壊れたマルチセッションタスク+- 欠落している継続性アーティファクト+- 継続性回復パターンdiff --git a/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdnew file mode 100644index 0000000..e133cd2--- /dev/null+++ b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -0,0 +1,17 @@+# セッションハンドオフの例++## 完了++- Markdown インポートサポートを追加+- レンダラーに基本的なドキュメントリストを追加++## 壊れているまたは未検証++- `.md` のインポートは成功するが、大きな `.txt` ファイルで失敗する+- アプリは起動するが、詳細ビューが接続されていない++## 次の最適ステップ++- `.txt` インポートパスを修正+- インポートをエンドツーエンドで検証+- その後、ドキュメント詳細パネルを追加diff --git a/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.tsnew file mode 100644index 0000000..69f9c3e--- /dev/null+++ b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts@@ -0,0 +1,162 @@+/**+ * session-simulator.ts+ *+ * Simulates two sessions working on a multi-step task.+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.+ * Run 2: With handoff file -- Session B picks up where Session A left off.+ *+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface TaskStep {+ id: number;+ name: string;+ durationMs: number;+}++interface SessionResult {+ session: string;+ stepsCompleted: number;+ totalDurationMs: number;+ duplicatedSteps: number;+ output: string[];+}++// ---------------------------------------------------------------------------+// Task definition+// ---------------------------------------------------------------------------++const taskSteps: TaskStep[] = [+ { id: 1, name: "Read project structure", durationMs: 50 },+ { id: 2, name: "Understand existing auth module", durationMs: 80 },+ { id: 3, name: "Design new search endpoint", durationMs: 60 },+ { id: 4, name: "Implement search endpoint", durationMs: 100 },+ { id: 5, name: "Write integration tests", durationMs: 70 },+ { id: 6, name: "Update documentation", durationMs: 40 },+];++// ---------------------------------------------------------------------------+// Simulated session executor+// ---------------------------------------------------------------------------++/** Simulate a session doing work. */+function runSession(+ sessionName: string,+ startStep: number,+ endStep: number+): SessionResult {+ const output: string[] = [];+ let totalDuration = 0;++ for (let i = startStep; i <= endStep; i++) {+ const step = taskSteps.find((s) => s.id === i)!;+ totalDuration += step.durationMs;+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);+ }++ return {+ session: sessionName,+ stepsCompleted: endStep - startStep + 1,+ totalDurationMs: totalDuration,+ duplicatedSteps: 0,+ output,+ };+}++// ---------------------------------------------------------------------------+// Run 1: No handoff file+// ---------------------------------------------------------------------------++function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 before timing out+ const sessionA = runSession("Session A", 1, 3);++ // Session B has no context, starts from scratch+ const sessionB = runSession("Session B", 1, 6);+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Run 2: With handoff file+// ---------------------------------------------------------------------------++function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 and writes a handoff file+ const sessionA = runSession("Session A", 1, 3);++ // Session B reads handoff, starts from step 4+ const sessionB = runSession("Session B", 4, 6);+ sessionB.duplicatedSteps = 0;++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {+ console.log("\n" + "=".repeat(80));+ console.log(` ${title}`);+ console.log("=".repeat(80));++ console.log("\n Session A output:");+ for (const line of result.sessionA.output) {+ console.log(line);+ }++ console.log("\n Session B output:");+ for (const line of result.sessionB.output) {+ console.log(line);+ }++ console.log("\n Session B notes:");+ if (result.sessionB.duplicatedSteps > 0) {+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);+ } else {+ console.log(" - Read handoff file, continued from step 4");+ console.log(" - No duplicate work performed");+ }+}++function printComparison(): void {+ const noHandoff = simulateNoHandoff();+ const withHandoff = simulateWithHandoff();++ printRun("RUN 1: NO HANDOFF FILE", noHandoff);+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);++ // Comparison table+ console.log("\n" + "=".repeat(80));+ console.log(" COMPARISON TABLE");+ console.log("=".repeat(80) + "\n");++ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log(header);+ console.log(sep);++ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;++ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);++ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");+}++printComparison();diff --git a/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdnew file mode 100644index 0000000..bbc1f39--- /dev/null+++ b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -0,0 +1,180 @@+[中文版本 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)+> 実践プロジェクト: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# 講義 05. セッションをまたいでコンテキストを保つ++Claude Code に完全な機能の実装を頼んだとします。30分間実行され、大部分の作業を終えますが、コンテキストが残り少なくなっています。新しいセッションを開始して続きをさせると — 前回どのような決定がなされたか、なぜオプション A が B より選ばれたか、どのファイルがすでに変更されたか、テストがどのような状態かを覚えていないことがわかります。プロジェクトを再探索するのに15分を費やし、前回のアプローチと矛盾する可能性もあります。++毎朝目覚めるとすべてを忘れてしまう職人だと想像してください。建設現場全体に再度慣れる必要があります — どの壁が半分まで建っているか、なぜ赤レンガが青レンガより選ばれたか、配管はどこまで進んでいるか。さらに悪いことに、昨日すでに設置された窓を、完了したことを覚えていないために取り壊してしまうかもしれません。++これはまさに、AI コーディングエージェントがセッションをまたぐタスクで直面する窮状です。この講義では、エージェントが長時間のタスク中に「記憶喪失」になる理由と、構造化された状態の永続化がエージェントを信頼できる日記をつける職人のようにできる方法を説明します — まだ記憶喪失ですが、日記がすべてを覚えています。++## コンテキストウィンドウ: 無限ではない++コンテキストウィンドウは有限です。これはモデルのアップグレードでは解決できません — ウィンドウサイズが1Mトークンに成長しても、複雑なタスクはそれを使い果たします。なぜなら、エージェントはコードを生成するだけでなく、コードベースを理解し、自身の決定履歴を追跡し、ツールの出力を処理し、会話のコンテキストを維持しているからです。この情報はすべて、ウィンドウの拡大よりも速く増大します。++さらに深い問題があります。エージェントが生成する情報は、すべてが同じ重要度ではありません。中間的な推論ステップには決定の「理由」が含まれています — なぜ A ではなく B が選ばれたのか、なぜあのライブラリではなくこのライブラリなのか、なぜ特定の最適化がスキップされたのか。最終的な出力には「何をしたか」しか含まれていません — コード自体です。圧縮戦略は通常、後者を保持しますが、前者を失います。次のセッションはコードを見ますが、なぜそのように書かれたかを知らず、意図的な設計決定を「最適化」してしまう可能性があります。++Anthropic は長時間実行エージェントの研究で興味深いことを発見しました。エージェントはコンテキストが残り少なくなっていると感じると、「早期収束」行動を示します — 現在の作業を急いで終わらせ、検証ステップをスキップし、最適なものよりもシンプルな解決策を選びます。試験の残り時間が少なくなっていることに気づき、残りの選択問題に適当に答えを埋めるようなものです。Anthropic はこれを「コンテキスト不安」と呼んでいます。++## セッション継続性フロー++継続性アーティファクトがないと、新しいセッションは毎回災難です。++```mermaid+flowchart LR+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]+ End1 --> S2["Session 2 starts fresh"]+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]+```++継続性アーティファクトがあれば、新しいセッションはすぐに再開できます。++```mermaid+flowchart LR+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]+ Work --> Verify["Verification notes<br/>which tests pass and fail"]+ Work --> Commit["Git checkpoint<br/>exact repo state"]++ Progress --> Rebuild["Session 2 rebuild"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["New session picks up quickly"]+```++## 中核概念++- **コンテキストウィンドウは有限**: ウィンドウサイズがどう謳われていても(128K、200K、1M)、長時間のタスクは最終的にそれを使い果たします。使い切った後は、圧縮(情報を失う)かリセット(新しいセッション)が必要です。どちらも何かを失います。+- **継続性アーティファクト**: 新しいセッションが前回のセッションの続きを明確に再開できるようにする、永続化された状態ファイル。基本形: 進捗ログ + 検証記録 + 次のアクション。あの職人の日記です。+- **リビルドコスト**: 新しいセッションが実行可能な状態に到達するまでに必要な時間。良い harness はリビルドコストを15分から3分に圧縮できます。+- **ドリフト**: エージェントの理解とコードリポジトリの実際の状態との乖離。すべてのセッション境界でドリフトが発生し、制御しなければ複利で増大します。+- **コンテキスト不安**: Anthropic が観察した現象 — エージェントは知覚されるコンテキスト制限に近づくと早期収束行動を示し、情報損失を避けるためにタスクを早期に終了させます。これは非合理的なリソース不安です。+- **圧縮 vs リセット**: 圧縮は同じセッション内でコンテキストを要約します(「何をしたか」は保持、「なぜ」は失われる可能性あり)。リセットは新しいセッションを開始し、永続化された状態から再構築します(クリーンだが、アーティファクトの完全性に依存)。++## 継続性が壊れたときに何が起きるか++前のセッションは、3つのアプローチを分析してオプション B を選ぶために大量のコンテキスト予算を費やしました。今回のセッションのエージェントはその分析を知らず、不完全な情報に基づいて再決定する可能性があります — オプション A を選ぶかもしれません。赤レンガが選ばれた理由を覚えていない記憶喪失の職人が、今日は青レンガの方がきれいだと思い、昨日の壁を取り壊して建て直すようなものです。++さらに悪いのは重複作業です。エージェントは特定の作業がすでに完了したかどうか確信がなく、もう一度行います。さらに悪いことに — 半分やってから既存の実装との競合を発見し、やり直しになります。建設現場で、2つのチームが同じ壁を同時に建てることはできません — しかし進捗記録がなければ、新しいチームは誰かがすでに取り組んでいることを知る由がありません。++複数のセッションにわたって、実装の方向が元の要件から知らず知らずのうちにずれていくことがあります。新しいセッションごとにプロジェクトの目標に対する理解が少し異なります。伝言ゲームのように — 10人がメッセージを伝えるうちに、「コーヒーを買ってきて」が「コーヒーマシンを買って」になってしまうかもしれません。++検証のギャップもあります。前のセッションの検証結果(どのテストが合格し、どれが失敗し、なぜ失敗したか)が記録されていません。新しいセッションは現在の状態を理解するためにすべての検証を再実行しなければなりません。毎回ゼロから再診断し、毎回貴重なコンテキストを無駄にします。++OpenAI も Anthropic もドキュメントで構造化された状態の永続化を強調しています。OpenAI の harness engineering の記事はリポジトリを「運用記録」として扱っています — すべての操作の結果がリポジトリに追跡可能な証拠を残すべきだとしています。Anthropic の長時間実行エージェントのドキュメントは具体的に「ハンドオフファイル」を推奨しています — 現在の状態、既知の問題、次のアクションを含む構造化されたドキュメントです。++## 記憶喪失の職人に日記を++核心的なアプローチ: **エージェントを記憶喪失の優秀なエンジニアとして扱う。** 「退勤」する前に、次の「シフト」のエージェントがすぐに引き継げるよう、重要な情報を書き留めなければなりません。++**ツール1: 進捗ファイル(PROGRESS.md)。** 最も基本的な継続性アーティファクト — 日記の核心です。++```markdown+# Project Progress++## Current State+- Latest commit: abc1234 (feat: add user preferences endpoint)+- Test status: 42/43 passing (test_pagination_edge_case failing)+- Lint: passing++## Completed+- [x] User model and database migration+- [x] Basic CRUD endpoints+- [x] Auth middleware integration++## In Progress+- [ ] Pagination feature (90% - edge case test failing)++## Known Issues+- test_pagination_edge_case returns 500 on empty result sets+- Need to confirm whether deleted users should appear in listings++## Next Steps+1. Fix pagination edge case bug+2. Add "include deleted users" query parameter+3. Update API documentation+```++**ツール2: 決定ログ(DECISIONS.md)。** 重要な設計決定とその理由を記録します。詳細な設計ドキュメントは不要 — 「何を決定したか、なぜ、いつ」だけ — 日記の中のメモです。++```markdown+# Design Decisions++## 2024-01-15: Use Redis for user preferences caching+- Reason: High read frequency (every API call), small data size+- Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile)+- Constraint: Cache TTL of 5 minutes, active invalidation on write+```++**ツール3: Git コミットをチェックポイントとして。** 各作業の原子単位が完了するたびにコミットします。コミットメッセージには何をしたかとなぜを記載します。これらは無料で、自動的にバージョン管理される状態のスナップショットです。++**ツール4: init.sh または harness 初期化フロー。** `AGENTS.md` に「出勤」ルーティンと「退勤」ルーティンを指定します。++```markdown+## At session start (clock in)+1. Read PROGRESS.md for current state+2. Read DECISIONS.md for important decisions+3. Run make check to confirm repo is in consistent state+4. Continue from PROGRESS.md "Next Steps" section++## Before session end (clock out)+1. Update PROGRESS.md+2. Run make check to confirm consistent state+3. Commit all completed work+```++**混合戦略**: すべてのタスクがコンテキストのリセットを必要とするわけではありません。短いタスク(30分未満)は1つのセッション内で完了できます。長時間のタスク(セッションにまたがるもの)は、継続性のために進捗ファイルと決定ログを使用しなければなりません。判断基準: タスクがウィンドウの60%以上を必要とする場合、ハンドオフの準備を始めます。++### コンテキスト不安の詳細++Anthropic の2026年3月の研究は、コンテキスト不安の具体的な兆候をさらに明らかにしました: Sonnet 4.5 では、コンテキストがウィンドウ制限に近づくと、エージェントは強い「早期収束」行動を示します。試験の時間がほとんどなくなったことに気づき、素早く選択問題にランダムな答えを埋めるようなものです。++これに対処する2つの戦略があります。++**圧縮**: 同じセッション内で早期の会話を要約します。利点: 継続性を維持し、エージェントは「何をしたか」を見られます。欠点: 要約で「なぜ」が失われることが多い — なぜ A ではなく B が選ばれたのか、なぜ特定の最適化がスキップされたのか。さらに重要なことに、圧縮はコンテキスト不安を排除しません — エージェントはコンテキストがかつて大きかったことを知っており、心理的にはまだ急いで終わらせようとする傾向があります。++**コンテキストリセット**: コンテキストを完全にクリアし、新しいセッションを開始し、永続化されたアーティファクトから再構築します。利点: クリーンな精神状態 — 新しいセッションには「時間が足りない」という不安がありません。欠点: ハンドオフアーティファクトの完全性に依存します。日記に重要な情報が欠けていると、新しいセッションは間違った方向に時間を浪費する可能性があります。++Anthropic の実際のデータ: Sonnet 4.5 では、コンテキスト不安が深刻であり、圧縮だけでは不十分です — コンテキストリセットが harness 設計の重要なコンポーネントになります。しかし Opus 4.5 ではこの行動が大幅に減少し、圧縮だけでリセットに頼らずにコンテキストを管理できます。これは次のことを意味します。**harness 設計はターゲットモデルを具体的に理解する必要があり、万能のテンプレートではありません。**++> 出典: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## 実例++エージェントにユーザー認証付きブログシステムの実装を依頼しました — 12の機能ポイント、5セッションが必要と推定。++**日記なしのベースライン**: セッション1でユーザーモデルと基本ルートを実装。セッション2はエージェントが認証ミドルウェアのインターフェース契約を覚えておらず、前回の設計意図を推測するのに約15分を費やしました。セッション3までに蓄積されたドリフトにより、エージェントはすでに完了した機能の再実装を始めました。セッション5までに、リポジトリには大量の冗長なコードが含まれていましたが、コアの認証機能は依然としてエンドツーエンドテストに合格していませんでした。12の機能ポイントのうち7つしか完了せず、3つには隠れた正確性の問題がありました。日記を一切書かない職人のように — 5日目には建設現場は混乱し、一部の壁は2度建てられ、建てるべきだった壁はまだ着手されていません。++**日記あり**: 進捗ファイル、決定ログ、検証記録、Git チェックポイントを使用。各セッション終了時に状態レポートを自動更新。セッション2のリビルドコストは約3分に低下。セッション5までに、12の機能ポイントすべてが完了し検証済み。++定量的な比較: リビルド時間が約78%削減、機能完了率は58%から100%、隠れた欠陥率は43%から8%に低下。職人はまだ記憶喪失ですが、日記のおかげで毎日の開始は昨日の停止地点からとなり、ゼロからではありません。++## 重要なポイント++- コンテキストウィンドウは有限のリソースです。長時間のタスクはセッションにまたがり、セッションは情報を失います — 毎日忘れる職人のように、これは客観的な現実です。+- 解決策はより大きなウィンドウではなく、より良い状態の永続化です。進捗ファイル + 決定ログ + Git チェックポイント — 記憶喪失の職人に信頼できる日記を与えます。+- エージェントを記憶喪失のエンジニアとして扱う: 「退勤」前に、何をしたか、なぜ、次は何かを書き留める。+- リビルドコストが主要な指標です。良い harness は新しいセッションを3分以内に実行可能な状態にするべきです。+- 混合戦略: 短いタスクはセッション内で、長時間のタスクは構造化されたアーティファクトで継続性を確保。++## 参考資料++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [Claude Code Documentation](https://docs.anthropic.com/ja/docs/claude-code)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)++## 演習++1. **継続性損失の測定**: 3セッション以上を必要とする開発タスクを選びます。継続性アーティファクトを一切提供せず、各セッションの開始時にエージェントが「前回何が起きたかを理解する」のにどれくらいのコンテキストを費やすかを記録します。各セッション終了後に進捗ファイルを作成し、次のセッションをそこから開始させます。進捗ファイルの有無によるリビルドコストを比較してください。++2. **ハンドオフテンプレートの設計**: 4つのフィールドを持つ最小限のハンドオフテンプレートを設計します: リポジトリの状態(コミットハッシュ)、実行状態(テスト合格率)、ブロッカー、次のアクション。完全に新しいエージェントセッションにこのテンプレートだけを使ってプロジェクトの状態を復元させます。復元中に遭遇した曖昧さを記録し、テンプレートを改善するために反復してください。++3. **混合戦略の実験**: 5セッションの開発タスクで、3つの戦略を比較します: (a) 常に新しいセッションを開始 + 進捗ファイル、(b) 1つのセッションでできるだけ多くを行う(コンテキスト圧縮)、(c) 混合戦略(短いタスクはセッション内、長時間のタスクはセッションをまたぐ + 進捗ファイル)。リビルド時間、機能完了率、決定の一貫性を比較してください。diff --git a/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdnew file mode 100644index 0000000..cf48625--- /dev/null+++ b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md@@ -0,0 +1,8 @@+# 講義 06 のコード++このフォルダーは、以下の例に使用してください:++- イニシャライザーの出力+- 初期化スクリプト+- 進捗ファイル+- 初回実行のスキャフォールディングdiff --git a/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.tsnew file mode 100644index 0000000..52dcd98--- /dev/null+++ b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts@@ -0,0 +1,296 @@+/**+ * init-check.ts+ *+ * Programmatically checks initialization prerequisites:+ * - Node.js version+ * - Dependencies installed (node_modules exists)+ * - Data directory exists+ * - Config files present+ *+ * Simulates running with and without an explicit init phase,+ * showing how missing prerequisites cause silent failures later.+ *+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";+import * as childProcess from "node:child_process";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface CheckItem {+ name: string;+ category: string;+ check: () => { pass: boolean; detail: string };+ impactIfMissing: string;+}++interface CheckResult {+ name: string;+ category: string;+ passed: boolean;+ detail: string;+ impactIfMissing: string;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++function createChecks(targetDir: string): CheckItem[] {+ return [+ {+ name: "Node.js version >= 18",+ category: "Runtime",+ check: () => {+ try {+ const version = process.version; // e.g. "v20.11.0"+ const major = parseInt(version.replace("v", "").split(".")[0], 10);+ return {+ pass: major >= 18,+ detail: `Detected: ${version} (need >= v18)`,+ };+ } catch {+ return { pass: false, detail: "Could not detect Node.js version" };+ }+ },+ impactIfMissing: "TypeScript features and built-in APIs unavailable",+ },+ {+ name: "package.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "package.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found in target directory",+ };+ },+ impactIfMissing: "Cannot install dependencies or run scripts",+ },+ {+ name: "Dependencies installed (node_modules)",+ category: "Dependencies",+ check: () => {+ const p = path.join(targetDir, "node_modules");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",+ };+ },+ impactIfMissing: "All imports fail at runtime",+ },+ {+ name: "TypeScript available",+ category: "Toolchain",+ check: () => {+ try {+ const result = childProcess.execSync("npx tsc --version", {+ encoding: "utf-8",+ timeout: 10000,+ stdio: ["pipe", "pipe", "pipe"],+ }).trim();+ return { pass: true, detail: `Detected: ${result}` };+ } catch {+ return { pass: false, detail: "TypeScript not available via npx" };+ }+ },+ impactIfMissing: "Cannot compile TypeScript files",+ },+ {+ name: "tsconfig.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "tsconfig.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found",+ };+ },+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",+ },+ {+ name: "Source directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["src", "lib", "app"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",+ };+ },+ impactIfMissing: "Agent cannot locate source files to modify",+ },+ {+ name: "Test directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["test", "tests", "__tests__", "spec"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",+ };+ },+ impactIfMissing: "Agent cannot find or run existing tests",+ },+ {+ name: "Git repository initialized",+ category: "Version Control",+ check: () => {+ const gitDir = path.join(targetDir, ".git");+ const exists = fs.existsSync(gitDir);+ return {+ pass: exists,+ detail: exists ? "Git repository detected" : "No .git directory found",+ };+ },+ impactIfMissing: "No rollback capability, no change history",+ },+ ];+}++// ---------------------------------------------------------------------------+// Simulation: with and without init phase+// ---------------------------------------------------------------------------++interface SimResult {+ scenario: string;+ checksRun: boolean;+ failuresBeforeWork: number;+ workAttempted: boolean;+ workSucceeded: boolean;+ timeWastedMs: number;+}++function simulateWithoutInit(): SimResult {+ // Agent skips init, goes straight to work.+ // Encounters failures one at a time as it hits missing prerequisites.+ const checks = createChecks(process.cwd());+ let failures = 0;+ let timeWasted = 0;++ for (const check of checks) {+ const result = check.check();+ if (!result.pass) {+ failures++;+ timeWasted += 200; // Agent spends time discovering each missing piece+ }+ }++ return {+ scenario: "NO INIT PHASE",+ checksRun: false,+ failuresBeforeWork: 0, // Didn't check upfront+ workAttempted: true,+ workSucceeded: failures === 0,+ timeWastedMs: timeWasted,+ };+}++function simulateWithInit(): SimResult {+ // Agent runs init phase first, discovers all issues upfront.+ const checks = createChecks(process.cwd());+ let failures = 0;++ for (const check of checks) {+ if (!check.check().pass) {+ failures++;+ }+ }++ return {+ scenario: "WITH INIT PHASE",+ checksRun: true,+ failuresBeforeWork: failures,+ workAttempted: failures === 0,+ workSucceeded: failures === 0,+ timeWastedMs: 0,+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.cwd();+ console.log("\n" + "=".repeat(80));+ console.log(" INITIALIZATION PREREQUISITE CHECK");+ console.log("=".repeat(80));+ console.log(` Target: ${targetDir}\n`);++ const checks = createChecks(targetDir);+ const results: CheckResult[] = checks.map((c) => {+ const r = c.check();+ return {+ name: c.name,+ category: c.category,+ passed: r.pass,+ detail: r.detail,+ impactIfMissing: c.impactIfMissing,+ };+ });++ // Detailed report+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const status = r.passed ? "PASS" : "FAIL";+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);+ }++ const passCount = results.filter((r) => r.passed).length;+ const failCount = results.filter((r) => !r.passed).length;++ console.log("\n" + "-".repeat(80));+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);++ if (failCount > 0) {+ console.log("\n FAILED CHECKS -- Impact if not resolved:");+ for (const r of results.filter((r) => !r.passed)) {+ console.log(` - ${r.name}: ${r.impactIfMissing}`);+ }+ }++ // Comparison: with vs without init+ const noInit = simulateWithoutInit();+ const withInit = simulateWithInit();++ console.log("\n" + "=".repeat(80));+ console.log(" INIT PHASE COMPARISON");+ console.log("=".repeat(80) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);++ console.log("\n An explicit init phase catches problems before they waste time.\n");+}++run();diff --git a/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.shnew file mode 100644index 0000000..2c6e1b0--- /dev/null+++ b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh@@ -0,0 +1,10 @@+#!/usr/bin/env bash+set -euo pipefail++echo "[init] installing dependencies"+npm install++echo "[init] starting the docs site is optional"+echo "[init] use npm run docs:dev for course docs"++echo "[init] project-specific startup would go here"diff --git a/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.mdnew file mode 100644index 0000000..7fc1523--- /dev/null+++ b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md@@ -0,0 +1,7 @@+# イニシャライザー出力チェックリスト++- 正規の起動コマンドはあるか?+- 正規の検証コマンドはあるか?+- 最初の進捗アーティファクトはあるか?+- 安定した最初のコミットはあるか?+- 後のセッション向けに可視的な機能面はあるか?diff --git a/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdnew file mode 100644index 0000000..ce4f308--- /dev/null+++ b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -0,0 +1,157 @@+[中文版本 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)+> 実践プロジェクト: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)++# 講義 06. すべてのエージェントセッション前に初期化する++新しいエージェントセッションを開始し、「検索機能を追加して」と言います。エージェントはすぐにコーディングに飛び込みます — 勇気ある意欲です。20分後、テストフレームワークが正しく設定されていないことを発見し、それを直すのにさらに10分、次にデータベースのマイグレーションスクリプトの形式が間違っていて、さらに調整。検索機能は最終的に追加されましたが、セッション全体として非効率でした — ほとんどの時間は「このプロジェクトがどう動いているかを理解する」ことに費やされ、「検索機能を書く」ことにはほとんど使われませんでした。++より良いアプローチ: エージェントに作業を始めさせる前に、別のフェーズを使って基本環境を準備し、検証コマンドを通るようにし、プロジェクト構造を理解させます。家を建てるようなものです — 基礎を打つことと壁を立てることを同時には行いません。同時に行うと、基礎が固まる前に壁が立ち上がり、建物全体を取り壊してやり直すことになります。まず基礎を打ち、固まるのを待ってから壁を建てる — きれいで効率的です。++この講義では、初期化がなぜ実装と混ぜるのではなく、独立したフェーズでなければならないかを説明します。++## 基礎と壁: 本質的に異なる2つの仕事++初期化と実装は全く異なる最適化の目標を持っています。実装フェーズの最適化の対象は: 検証済み機能の量と品質の最大化。初期化フェーズの最適化の対象は: その後のすべての実装の信頼性と効率の最大化。++初期化と実装を混ぜると、エージェントは多目的最適化問題に直面します — インフラを構築しながら機能のコードを書くことです。明示的な優先順位の設定がない場合、エージェントは自然にコードを書く方に引き寄せられます(それが直接目に見える出力だからです)、一方でインフラは犠牲になります(その価値は後続のセッションでのしか現れないからです)。建設作業員に基礎を打つことと壁を建てることを同時にさせるようなものです — おそらく壁を建てることを急ぐでしょう。壁は目に見え、実証可能だからです。しかし基礎の悪い家には、後にシステム的な問題が発生します。++## 初期化ライフサイクル++```mermaid+flowchart TB+ subgraph Wrong["Mixed session (wrong)"]+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]+ W2 --> W3["Accumulate unverified code"]+ W3 --> W4["Next session must rediscover project state"]+ end++ subgraph Right["Dedicated initialization (right)"]+ R1["Session 1: environment runnable"] --> R2["Example test passing"]+ R2 --> R3["Bootstrap contract + task list written"]+ R3 --> R4["Clean checkpoint committed"]+ R4 --> R5["Later sessions start directly on verified tasks"]+ end+```++## 混ぜたときに何が起きるか++最も直接的な問題: 基礎が正しく固まらない。エージェントは労力の80%を機能コードに、20%を適当にインフラの設定に使います。テストフレームワークは設定されたが検証されていない、lint ルールは設定されたが緩すぎる、進捗ファイルは作成されていない。これらの欠陥は最初のセッションでは明らかではありません(エージェントは自分が何をしたかまだ覚えているからです)が、2回目のセッションで表面化します — 新しいエージェントは実行方法、テスト方法、現状がどうなっているかを知りません。ずさんな基礎、ぐらつく建物です。++より隠れたコストは「未検証の蓄積」です — テストフレームワークが設定される前に書かれた機能コードは、検証のないコードです。後からそのコードにテストを追加しに行くと、設計が最初から間違っていたことに気づくかもしれません — 知っていれば別の方法で実装していたでしょう。生のコンクリートの上にタイルを貼るようなものです — 床が水平でないことに気づいたとき、すべてのタイルを剥がしてやり直さなければなりません。++セッション予算も無駄にされています。初期化作業(環境の設定、テストのセットアップ、プロジェクト構造の理解)は多大な予算を消費し、実際の機能実装に使える分が減ります。結果: 最初のセッションは機能の半分しか完了せず、2回目のセッションはプロジェクトの理解をやり直さなければなりません。基礎に予算を使ったのに、基礎も固まっていない — どちらの目標も達成できません。++最も見落とされやすい問題は、暗黙の前提の地雷です。初期化中にエージェントが行う決定(どのテストフレームワーク、ディレクトリの整理方法、依存関係の管理)— 明示的に記録されていなければ、後続のセッションはこれらの選択を理解できません。さらに悪いことに、後続のセッションが矛盾する選択をする可能性があります。最初の建設チームがコンクリート基礎を使ったのに、2番目のチームはそれを知らずに木製の杭を打ち込んだ — 基礎にひびが入ります。++Anthropic の長時間アプリケーション開発研究は、初期化と実装を分離することを明確に推奨しています。彼らの実験データ: 専用の初期化フェーズを使用したプロジェクトは、混在アプローチと比較してマルチセッションシナリオで31%高い機能完了率を示しました。重要な洞察 — 初期化フェーズに投資した時間は、次の3〜4セッションで完全に回収されます。基礎がしっかりしているほど、壁は速く立ち上がります。++OpenAI の Codex harness engineering ガイドも「リポジトリを運用記録とする」原則を強調しています — 最初の実行から明確な運用構造を確立しなければ、新しいセッションは毎回プロジェクトの規約を推測し直すことになります。++## 中核概念++- **初期化フェーズ**: エージェントのライフサイクルの最初のフェーズ — 機能実装は一切行わず、その後のすべての実装フェーズの前提条件を確立するだけです。出力はコードではなく、インフラです。+- **ブートストラップコントラクト**: プロジェクトが新しいエージェントセッションによって明確に操作可能な条件 — 起動できる、テストできる、進捗が見える、次のステップに取りかかれる。4つの条件、すべて必須。+- **コールドスタート vs ウォームスタート**: コールドスタートは空のディレクトリから始まり、エージェントがプロジェクト構造を推測しなければならない状態。ウォームスタートはテンプレートや既存のプロジェクトから始まり、インフラがすでに整っている状態。ウォームスタートはコールドスタートを大幅に上回ります — 水道と電気が通っている現場で作業を始めるのと、荒野から始めるのとの違いです。+- **ハンドオフ準備完了**: いつでも新しいエージェントが引き継げる状態にプロジェクトがあること。口頭での説明は不要 — リポジトリの内容だけで十分。+- **初回検証までの時間**: プロジェクト開始から最初の機能ポイントが検証に通るまでの時間。これは初期化の効率を測る中核的な指標です。+- **下流の使いやすさ**: 初期化の品質を測る最良の指標 — 暗黙の知識に依存せずにタスクを正常に実行できる後続セッションの割合。++## 正しい初期化の方法++**初期化を専用のフェーズとして扱う。** 最初のセッションは初期化のみを行います — ビジネス機能のコードは一切書きません。初期化が生成するもの:++**1. 実行可能な環境。** プロジェクトが起動し、依存関係がインストールされ、環境の問題がないこと。基礎が打たれ、ひび割れなし。++**2. 検証可能なテストフレームワーク。** 少なくとも1つのサンプルテストが通ること。これがテストフレームワーク自体が正しく設定されていることを証明します — 基礎の上に柱を立てて荷重に耐えられることを証明するようなものです。++**3. ブートストラップコントラクト文書。** 後続のセッションに明確に伝える文書:+```markdown+# Initialization Contract++## Start Commands+- Install dependencies: `make setup`+- Start dev server: `make dev`+- Run tests: `make test`+- Full verification: `make check`++## Current State+- All dependencies installed and locked+- Test framework configured (Vitest + React Testing Library)+- Example test passing (1/1)+- Lint rules configured (ESLint + Prettier)++## Project Structure+- src/ — Source code+- src/components/ — React components+- src/api/ — API client+- tests/ — Test files+```++**4. タスクの分割。** プロジェクト全体を順序付きのタスクリストに分割し、各タスクに明確な受け入れ基準を設定:+```markdown+# Task Breakdown++## Task 1: User Authentication Basics+- Implement JWT auth middleware+- Add login/register endpoints+- Acceptance: pytest tests/test_auth.py all passing++## Task 2: User Profile Page+- Implement user profile CRUD+- Add profile edit form+- Acceptance: pytest tests/test_profile.py all passing++## Task 3: Search Feature+- ...+```++**5. Git コミットをチェックポイントとして。** 初期化が完了したら、クリーンなチェックポイントとしてコミットします。その後のすべての作業はこのチェックポイントから始まります。++**ウォームスタート戦略**: 空のディレクトリから始めないでください。プロジェクトテンプレート(create-react-app、fastapi-template など)を使って、標準的なディレクトリ構造、依存関係の設定、テストフレームワークをあらかじめ設定します。一般的な初期化ステップをテンプレートに組み込み、プロジェクト固有の初期化作業だけを残します。水道と電気が通っている現場で作業を始めるようなもの — 荒野から始めるより1万倍良いです。++**初期化の完了基準**: 「どれだけコードを書いたか」ではなく、ブートストラップコントラクトの4つの条件が満たされているかどうかです — 起動できる、テストできる、進捗が見える、次のステップに取りかかれる。初期化を検証するにはこのチェックリストを使います:++```markdown+## Initialization Acceptance Checklist+- [ ] `make setup` succeeds from scratch+- [ ] `make test` has at least one passing test+- [ ] A new agent session can answer "how to run" and "how to test" from repo contents alone+- [ ] Task breakdown file exists with at least 3 tasks+- [ ] Everything committed to git+```++## 実例++React フロントエンドプロジェクトの2つの初期化アプローチ:++**混在アプローチ(基礎を打ちながら壁を建てる)**: エージェントはセッション1でプロジェクトのスキャフォールディングと最初の機能の実装を同時に行いました。セッション終了時、リポジトリには実行可能なコードがありましたが: 明示的な起動/テストコマンドのドキュメントがなく、進捗追跡ファイルがなく、タスク分割もありませんでした。セッション2はプロジェクト構造、テストフレームワーク、ビルドプロセスの推測に約20分を費やしました — 新しい建設チームが現場に到着し、基礎がどこまで進んでいるか、配管がどこを通っているかわからず、一つずつ穴を掘って確認するようなものです。++**専用初期化(まず基礎を打つ)**: セッション1は初期化のみを行いました — テンプレートからディレクトリ構造を作成し、テストフレームワーク(Vitest + React Testing Library)を設定し、1つのサンプルテストを書いて検証し、ブートストラップコントラクト文書とタスク分割ファイルを作成し、初期チェックポイントをコミットしました。セッション2のリビルド時間は3分未満で、タスクリストから直接作業を開始しました — 作業員が到着し、青写真を一瞥して、どこから続ければよいか正確にわかる。++プロジェクト全体のサイクル比較: 混在アプローチの総リビルド時間(全セッション合計)は、専用初期化アプローチより約60%多かった。初期化に費やした余分な20分は、後続のセッションで何倍にも回収されました。しっかりした基礎が壁を速く立ち上げる — 遅い方が速い。++## 重要なポイント++- 初期化と実装は異なる最適化の目標を持っています — 混ぜると両方をダメにするだけです。まず基礎を打ち、それから壁を建てましょう。+- 初期化の出力はコードではなく、インフラです: 実行可能な環境、検証可能なテスト、ブートストラップコントラクト、タスク分割。+- ブートストラップコントラクトの4つの条件で初期化を検証する: 起動できる、テストできる、進捗が見える、次のステップに取りかかれる。+- ウォームスタートがコールドスタートに勝る。プロジェクトテンプレートを使って標準化されたインフラをあらかじめ設定する。+- 初期化に投資した時間は次の3〜4セッションで完全に回収される。これは追加コストではなく、先行投資です。基礎がしっかりしているほど、建物は速く立ち上がる。++## 参考資料++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)++## 演習++1. **ブートストラップコントラクトの設計**: 開発中のプロジェクトの完全なブートストラップコントラクトを書きます。次に、完全に新しいエージェントセッションを開き、リポジトリの内容だけを見せ(口頭のコンテキストは与えず)、プロジェクトの起動、テストの実行、現在の進捗の理解を試みさせてください。遭遇するすべての問題を記録する — それぞれがブートストラップコントラクトの欠落条項に対応しています。++2. **比較実験**: 中程度に複雑な新規プロジェクトを選びます。アプローチ A: エージェントに初期化と最初の実装を同時に行わせる。アプローチ B: 1セッションを専用の初期化に費やし、セッション2で実装を開始する。4セッション後、初回検証までの時間、リビルドコスト、機能完了率を比較してください。++3. **初期化受け入れチェックリスト**: プロジェクトの初期化受け入れチェックリストを設計する。新しいエージェントセッションに各チェックリスト項目を実行させ、合格したものと失敗したものを記録する。失敗した項目が、harness の強化が必要な箇所です。diff --git a/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdnew file mode 100644index 0000000..bc4c79d--- /dev/null+++ b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md@@ -0,0 +1,8 @@+# 講義 07 のコード++このフォルダーは、以下の例に使用してください:++- ワンショットの失敗+- 大きすぎるタスクプロンプト+- 段階的なタスク形成+- 構造化された機能面diff --git a/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.mdnew file mode 100644index 0000000..7216961--- /dev/null+++ b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md@@ -0,0 +1,6 @@+# 次のタスクテンプレート++- 現在の最優先機能:+- なぜこの機能が次なのか:+- 何が合格とみなされるか:+- このステップで変更してはならないもの:diff --git a/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdnew file mode 100644index 0000000..dd48859--- /dev/null+++ b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -0,0 +1,17 @@+# スコープ面の例++タスク:++- Electron ナレッジアプリにインデックス機能を追加++悪いスコープ:++- 「インデックス機能を実装」++より良いスコープ:++- インポートされたドキュメントを解析する+- ドキュメントをチャンクに分割する+- チャンクメタデータを永続化する+- UI にインデックス状況を表示する+- 再インデックスアクションを追加するdiff --git a/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.tsnew file mode 100644index 0000000..c587a1d--- /dev/null+++ b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts@@ -0,0 +1,151 @@+/**+ * scope-tracker.ts+ *+ * Reads a feature list and a change log. Enforces single-active-feature+ * policy. Given a log of changes, flags any changes outside the active+ * feature scope. Demonstrates how scope drift happens and how the tracker+ * catches it.+ *+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Feature {+ id: string;+ name: string;+ status: "active" | "pending" | "done";+}++interface ChangeLogEntry {+ step: number;+ file: string;+ description: string;+ featureId: string; // The feature this change claims to belong to+}++// ---------------------------------------------------------------------------+// Sample data+// ---------------------------------------------------------------------------++const features: Feature[] = [+ { id: "F-001", name: "Search endpoint", status: "active" },+ { id: "F-002", name: "Delete endpoint", status: "pending" },+ { id: "F-003", name: "Rate limiting", status: "pending" },+ { id: "F-004", name: "User dashboard", status: "pending" },+];++// A realistic change log where the agent gradually drifts from the active feature+const changeLog: ChangeLogEntry[] = [+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },+];++// ---------------------------------------------------------------------------+// Scope tracker+// ---------------------------------------------------------------------------++interface ScopeCheckResult {+ step: number;+ file: string;+ description: string;+ featureId: string;+ inScope: boolean;+ activeFeature: string;+}++function trackScope(+ featureList: Feature[],+ changes: ChangeLogEntry[]+): ScopeCheckResult[] {+ const activeFeatures = featureList.filter((f) => f.status === "active");+ const activeIds = new Set(activeFeatures.map((f) => f.id));+ const activeNames = activeFeatures.map((f) => f.name).join(", ");++ return changes.map((change) => ({+ step: change.step,+ file: change.file,+ description: change.description,+ featureId: change.featureId,+ inScope: activeIds.has(change.featureId),+ activeFeature: activeNames,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const results = trackScope(features, changeLog);++ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");+ console.log("=".repeat(100));++ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));++ // Detailed change log+ console.log("\n" + "-".repeat(100));+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;+ console.log(header);+ console.log(sep);++ let inScopeCount = 0;+ let driftCount = 0;++ for (const r of results) {+ const scopeLabel = r.inScope ? "OK" : "DRIFT";+ if (r.inScope) inScopeCount++;+ else driftCount++;++ const marker = r.inScope ? " " : ">>";+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE DRIFT SUMMARY");+ console.log("=".repeat(100) + "\n");++ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;+ console.log(sHeader);+ console.log(sSep);+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);++ // Drift detail+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];+ if (driftFeatures.length > 0) {+ console.log("\n DRIFTED FEATURES:");+ for (const fid of driftFeatures) {+ const feat = features.find((f) => f.id === fid);+ const driftChanges = results.filter((r) => r.featureId === fid);+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);+ }+ }++ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");+}++run();diff --git a/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdnew file mode 100644index 0000000..f3cb6b2--- /dev/null+++ b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -0,0 +1,134 @@+[中文版本 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)+> 実践プロジェクト: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)++# 講義 07. エージェントのタスク境界を明確にする++Claude Code に「このプロジェクトにユーザー認証を追加して」と頼むと、データベーススキーマの変更を始め、ルートを書き、フロントエンドのコンポーネントを変更し、ついでにエラーハンドリングミドルウェアのリファクタリングまで始めます。2時間後に確認すると: 12ファイルが変更され、800行の新しいコードがあり、エンドツーエンドで動く機能は一つもありません。++背に腹は代えられない — この言葉は AI エージェントに特に当てはまります。エージェントには「ついでにもう少しやっておこう」という衝動が生まれつき備わっています — 関連するものを見ると、つい道沿いに処理してしまう。醤油を1本買いにスーパーに行って、満載のカートを押して出てくるような人です。問題は、買いすぎた人はお金を無駄にするだけですが、エージェントが同時に多くのことをしようとすると、どれも適切に完了しないということです。++Anthropic の「Effective harnesses for long-running agents」エンジニアリングブログは明確に述べています: プロンプトが広すぎると、エージェントは「1つを先に終わらせる」のではなく「複数のことを同時に始める」傾向があります。OpenAI の Codex エンジニアリングプラクティスも同じことを発見しました — 明示的なスコープ制御のないタスクは完了率が急激に低下します。これはモデルの問題ではありません — harness の問題です。あなたが境界を引かなかったのです。++## 注意力は有限のリソース++これは比喩ではなく、数学です。エージェントのコンテキスト容量を C とし、k 個のタスクを同時に起動すると仮定します。各タスクは平均 C/k の推論リソースを得ます。C/k が1つのタスクを完了するのに必要な最低閾値を下回ると、どれも完了しません。胃袋は有限 — 10個の餃子を一度に詰め込んでも全部消化できず、10回の消化不良になるだけです。++Claude Code の実際の行動がそれを物語っています。「ユーザー登録を追加して」と頼むと、次のようにするかもしれません:++1. User モデルを作成する+2. 登録ルートを書く+3. メール検証が必要なことに気づき、メールサービスを追加する+4. パスワードのハッシュ化が必要なことに気づき、bcrypt を導入する+5. エラーハンドリングが不統一なことに気づき、グローバルエラーミドルウェアをリファクタリングする+6. テストファイルの構造が乱雑なことに気づき、ディレクトリを再編成する++6ステップ後、すべてが半完成。エンドツーエンドの検証はなく、半完成のコード間に複雑な結合があり、次のセッションで片付けを引き継ぐ者は完全に途方に暮れます。6つの料理を同時に作るようなもの — すべての料理が鍋に入っているが、どれも皿に盛られていません。すべて焦げます。++Anthropic の実験データはこれを直接的に裏付けています: 「小さな次のステップ」戦略(WIP=1 に相当)を使うエージェントは、広範なプロンプトを使うエージェントより37%高いタスク完了率を示します。さらに興味深いことに、エージェントが生成するコード行数と実際の機能完了率は弱い負の相関があります — より多くのコードを書いた方が、より少ない機能が完了する。背に腹は代えられない、データによる証明です。++## WIP=1 ワークフロー++```mermaid+flowchart LR+ Queue["Feature queue"] --> Pick["Pick exactly one task"]+ Pick --> Active["Only one active item"]+ Active --> Verify["Run end-to-end verification"]+ Verify -->|pass| Commit["Commit and unlock next task"]+ Verify -->|fail| Active+ Commit --> Queue+```++```mermaid+flowchart TB+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]+ Budget --> Many["WIP = 5<br/>C / 5 per task"]++ One --> Finish["One feature reaches passing state"]+ Many --> Partial["Five partial implementations"]+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]+```++## 中核概念++- **オーバーリーチ**: エージェントが1つのセッションで最適な数よりも多くのタスクを起動すること。定量化可能 — 5つの機能をやってエンドツーエンドで通るものが0個ならオーバーリーチです。+- **アンダーフィニッシュ**: 起動したタスクのうち、エンドツーエンドの検証に通ったタスクの割合が閾値を下回ること。コードは書かれているがテストが通っていないのはアンダーフィニッシュです。+- **WIP 制限(Work-in-Progress Limit)**: カンバン手法から。核となる考え方: 一度に進行中のタスク数を制限する。エージェントの場合、WIP=1 が最も安全なデフォルト — 次を始める前に1つを完了する。ビュッフェのように — 皿に山盛りにせず、1枚の皿を済ませてから次を取りに行く。+- **完了の証拠**: タスクが「進行中」から「完了」に移行するために満たさなければならない検証可能な条件。これがないと、エージェントは「コードは問題なさそう」を「動作がテストに通る」の代わりに使ってしまいます。+- **スコープサーフェス**: 各ノードが作業単位で、エッジが依存関係を表す DAG 構造。状態は4つに限定: not_started、active、blocked、passing。+- **完了プレッシャー**: harness が WIP 制限と完了の証拠の要件を通じて加える制約力で、エージェントに新しいタスクを始める前に現在のタスクを完了させるよう強制します。++## オーバーリーチとアンダーフィニッシュは共生する++これら2つの問題は独立していません — 互いに増幅し合います。オーバーリーチは注意力を希薄化させ、希薄化された注意力はアンダーフィニッシュを引き起こし、残された半完成のコードがシステムの複雑さを増し、それが次のタスクでのさらなるオーバーリーチを招きます。悪循環です。++カンバンの言葉で言えば: リトルの法則は L = lambda * W と教えています。仕掛品 L が高すぎる(一度に多くのことをやっている)場合、各タスクのリードタイム W は必然的に増加します。エージェントにとって、これは各機能が開始から検証済み完了までにより長い時間がかかり、失敗の確率が増大することを意味します。++これは人間の世界でも古い問題です — Steve McConnell は *Rapid Development* の中で、スコープクリープがプロジェクト失敗の主要因であることを文書化しています。しかし人間には少なくとも「もう十分やった」という直感があります。エージェントにはそれがありません。次のアイデアを生成することはモデルにとってほぼ追加コストなしです — 「ついでにこれも直しておきましょう」と書くことはほとんど負担になりません — しかし、追加の変更ごとにエージェントの注意力は希薄化します。ビュッフェで追加の皿ごとの限界コストはほぼゼロですが、胃袋の容量には限界があるようなものです。++## 正しく行う方法++### 1. WIP=1 を強制する++これが最も直接的で効果的な方法です。harness の中で、エージェントに明示的に伝えます: **いつでも「active」ステータスでよいタスクは1つだけ。** Claude Code の `CLAUDE.md` や Codex の `AGENTS.md` に次のように書きます:++```+## Work Rules+- Work on one feature at a time+- Only start the next feature after the current one passes end-to-end verification+- Don't "also refactor" feature B while implementing feature A+```++ビュッフェで食事するように — 一度に1枚の皿、済ませてから次を取りに行く。++### 2. 各タスクに明示的な完了の証拠を定義する++完了とは「コードが書かれた」ではなく、「動作検証が通った」です。feature list で、各エントリに検証コマンドが必要です:++```+F01: User Registration+ Verification: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201+ State: passing+```++### 3. スコープサーフェスを外部化する++機械可読なファイル(JSON または Markdown)を使って、すべてのタスク状態を記録します。新しいセッションはこのファイルを読むだけで、どのタスクがアクティブか、何が完了とみなされるか、どの検証が通ったかを即座に把握できます。++### 4. 検証済み完了率を監視する++harness は VCR(Verified Completion Rate)= 検証済みタスク数 / 起動タスク数 を継続的に追跡するべきです。VCR < 1.0 のときは新しいタスクの起動をブロックします。++## 実例++8つの機能を持つ REST API プロジェクト、2つの戦略を比較:++**ビュッフェモード(制約なし)**: エージェントはセッション1で5つの機能を同時に起動。12ファイルにわたり約800行を生成。エンドツーエンドテストの合格率: 20% — ユーザー登録だけが動作。他の4つの機能: データベーススキーマは作成されたが検証ロジックが欠落、ルートは定義されたが誤ったレスポンス形式を返す。6つの料理を同時に作っているのに、1つだけかろうじて食べられる状態。セッション3の終了までに、8つの機能のうち3つしか完了せず。++**1枚の皿モード(WIP=1)**: エージェントはセッション1でユーザー登録のみに取り組む。4ファイルにわたり約200行を生成。エンドツーエンドテスト: 100%合格。クリーンで検証済みの実装をコミット。セッション4の終了までに、8つの機能のうち7つが完了(8番目は外部依存関係でブロック)。++結果: 総コード量は少ない(800 vs 1200行)が、有効なコードは多い。完了率: 87.5% vs 37.5%。一口ずつ食べれば、実際により多く食べられます。++## 重要なポイント++- **WIP=1 はエージェント harness のデフォルトの安全設定** — 1つ完了させてから次に取りかかる。並列化しようとしない。一口で太ることはできない。+- **完了の証拠は実行可能でなければならない** — 「コードは問題なさそう」はダメ。「curl が 201 を返す」ならOK。+- **スコープサーフェスはファイルとして外部化する** — 会話中に言及するだけでなく、リポジトリ内の機械可読形式で記録する。+- **オーバーリーチとアンダーフィニッシュは共生する** — 片方を解決すればもう片方も解決する。+- **「少なくても完了させる」は常に「多くても半完成で終わる」に勝る** — エージェントのコード行数と機能完了率は負の相関。品質が常に量に勝る。++## 参考資料++- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropic のエンジニアリングブログ、「小さな次のステップ」戦略の詳細な議論+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — OpenAI の harness engineering の完全な解説+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — WIP 制限に関する古典的な文献+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — スコープクリープがプロジェクト失敗の主要因であることの実証データ++## 演習++1. **タスクの原子化**: 広範な要件(例: 「ユーザー管理システムを実装する」)を選び、少なくとも5つの原子作業単位に分解する。各単位について: (a) 単一の動作記述、(b) 実行可能な検証コマンド、(c) 依存関係を指定する。分解が WIP=1 の制約を満たしているか確認してください。++2. **比較実験**: 同じプロジェクトを2回実行する — 1回は制約なし、1回は WIP=1 を強制。検証済み完了率、総コード行数、有効コード比率を比較してください。++3. **完了の証拠の監査**: 最近のエージェント実行の出力を確認し、各コード変更を「完了した動作」「不完全な動作」「スキャフォールディング」に分類する。不完全な動作それぞれについて欠けている検証コマンドを追加してください。diff --git a/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..52d6a2b--- /dev/null+++ b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,218 @@+/**+ * feature-list-validator.ts+ *+ * Reads a feature_list.json, validates its schema, and checks for features+ * marked "pass" without verification evidence. Outputs a structured report.+ * Can run against any project directory that has a feature_list.json.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]+ * (defaults to the directory containing this script)+ *+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Allow unknown fields for flexibility+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Schema validation+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entry ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Missing or invalid 'id' field`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Missing or invalid 'category' field`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Missing or invalid 'description' field`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' must be an array if present`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' must be a boolean if present`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Evidence validation+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Process feature list+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve target directory+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);+ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" FEATURE LIST VALIDATOR");+ console.log("=".repeat(90));+ console.log(` Reading: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(` ERROR: feature_list.json not found at ${filePath}`);+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");+ process.exit(1);+ }++ let entries: FeatureEntry[];+ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");+ process.exit(1);+ }++ // For demo purposes, also validate an extended test set+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "User can import a PDF document.",+ verification: ["Upload a PDF file", "Verify it appears in the document list"],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "System hallucination rate is below 5%.",+ verification: [], // Empty -- no evidence+ passes: true, // Marked as pass WITHOUT evidence+ },+ {+ id: "missing-fields",+ // Missing 'category' and 'description'+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Print report+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";+ const notes = r.markedPassWithoutEvidence+ ? "FLAGGED: passes without evidence!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";+ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`+ );+ }++ // Summary+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;+ const withEvidence = results.filter((r) => r.hasVerification).length;++ console.log("\n" + "-".repeat(90));+ console.log(" SUMMARY");+ console.log("-".repeat(90));+ console.log(` Total features: ${total}`);+ console.log(` Schema valid: ${schemaOk}/${total}`);+ console.log(` Marked as passing: ${passing}/${total}`);+ console.log(` With verification evidence: ${withEvidence}/${total}`);+ console.log(` Flagged (pass without evidence): ${flagged}`);++ if (flagged > 0) {+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);+ console.log(" These features need verification before they can be trusted.\n");+ } else {+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");+ }+}++run();diff --git a/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..8b973e3--- /dev/null+++ b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",+ "verification": [+ "Import a markdown document",+ "Open the Q&A panel",+ "Ask a question about known content",+ "Verify the answer is returned",+ "Verify one or more citations are displayed"+ ],+ "passes": false+ }+]diff --git a/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdnew file mode 100644index 0000000..11467c0--- /dev/null+++ b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -0,0 +1,8 @@+# 講義 08 のコード++このフォルダーは、以下の例に使用してください:++- パス状態ゲーティング+- エンドツーエンド検証+- 弱い vs 強い完了基準+- 評価ループの例diff --git a/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdnew file mode 100644index 0000000..4405bef--- /dev/null+++ b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -0,0 +1,8 @@+# パスゲートポリシー++機能は以下の条件をすべて満たした場合にのみ `passes: false` から `passes: true` に移行できる:++- 期待されるワークフローが実行されている+- 成功の証拠が記録されている+- テスト済みパスにブロッキングエラーが存在しない+- 実装がアプリを壊れたまたは曖昧な状態にしていないdiff --git a/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdnew file mode 100644index 0000000..0c7df27--- /dev/null+++ b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -0,0 +1,138 @@+[中文版本 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> 実践プロジェクト: [プロジェクト 04. 実行時フィードバックとスコープ制御](./../../projects/project-04-incremental-indexing/index.md)++# 講義 08. 機能リストでエージェントの作業を制約する++エージェントに e コマースサイトを作らせる。完了後、エージェントは「done」と言う。コードを見ると、ユーザー認証は動くが、カートのチェックアウトボタンは何もせず、決済フローも接続されていない。問題は、あなたが「done」の意味を伝えていなかったことだ。そのためエージェントは自分の基準、つまり「たくさんコードを書いたし、かなり完成して見える」を使った。++多くの人にとって、機能リストはただのメモだ。忘れないように書き出し、あとで脇に置くもの。しかし harness の世界では、機能リストは人間向けメモではない。harness 全体の背骨だ。スケジューラはそれを使ってタスクを選び、検証器は完了判定に使い、引き継ぎレポーターは要約生成に使う。背骨が折れれば、全身が動かなくなる。++Anthropic も OpenAI も強調している。**成果物は外部化されなければならない。** 機能状態は、構造化されていない会話テキストではなく、リポジトリ内の機械可読ファイルに置く必要がある。++## エージェントは「完了」の意味を知らない++Claude Code も Codex も、あなたが「完了」と言うときの意味を自動では知らない。「ショッピングカート機能を追加して」と言うと、モデルは「Cart コンポーネントと addToCart メソッドを書く」と解釈するかもしれない。しかしあなたが意図したのは「ユーザーが商品を閲覧し、カートに追加し、エンドツーエンドで決済を完了できる」ことだ。機能リストがなければ、この理解の差は残り続ける。エージェントは自分の暗黙基準、たいていは「明らかな構文エラーがない」を使う。必要なのはエンドツーエンドの振る舞い検証だ。友人に「果物を買ってきて」と頼んだらレモンを買ってくるようなものだ。相手の果物とあなたの果物は同じではない。++よくある進捗メモを見てみよう。++```+Did user auth, shopping cart mostly done, still need payments+```++新しいエージェントセッションは、このメモから次の質問に答えられるだろうか? 「mostly done」とは何か? カートはどのテストに通ったのか? 決済は何でブロックされているのか? 答えはすべて「誰も分からない」だ。医者に「最近お腹が痛いけど、まあ大丈夫」と言うようなもので、どんな薬を出せばよいのか分からない。++結果として、新しいセッションはプロジェクト状態の推測に 20 分を費やし、完了済み機能を再実装することさえある。Anthropic の engineering data では、よい進捗記録はセッション開始時の診断時間を 60-80% 削減する。++## 機能状態マシン++```mermaid+flowchart LR+ Feature["1 つの機能行"] --> Behavior["振る舞い<br/>例: POST /cart/items returns 201"]+ Feature --> Check["検証コマンド<br/>実行すべき正確なチェック"]+ Feature --> State["状態<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["3 つのフィールドが揃って初めて<br/>機能行として使える"]+ Check --> Complete+ State --> Complete+```++```mermaid+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["次の not_started 項目を選ぶ"]+ Scheduler --> Agent["エージェントはその 1 項目に取り組む"]+ Agent --> Verifier["その項目の検証コマンドを実行"]+ Verifier -->|pass| Passing["passing に更新し<br/>証拠を書く"]+ Verifier -->|fail| Active["active のままにする"]+ Verifier -->|dependency issue| Blocked["blocked にする"]+ Passing --> Handoff["引き継ぎメモと<br/>現在進捗を更新"]+ Active --> Agent+```++## 中核概念++- **機能リストは harness primitive**: 「任意の計画ツール」ではなく、他の harness コンポーネントが依存する基礎データ構造だ。データベースのテーブル構造のように、「主キーは省略しよう」とは言えない。+- **三要素構造**: 各機能項目は `(振る舞い説明, 検証コマンド, 現在状態)` の三つ組だ。どれか 1 つでも欠けると項目は不完全になる。+- **状態マシンモデル**: 各機能項目には `not_started`、`active`、`blocked`、`passing` の 4 状態がある。状態遷移は harness が制御し、エージェントが自由に変えるものではない。+- **Pass-state gating**: 機能が `active` から `passing` へ進む唯一の方法は、検証コマンドが成功することだ。これは不可逆で、一度 `passing` になれば戻らない。試験に合格したら合格であり、後から点数を変えられないのと同じだ。+- **Single source of truth**: 「何をすべきか」に関する情報は、すべて 1 つの機能リストから導かれるべきだ。機能リストと会話履歴の間に矛盾を作らない。+- **Back-pressure**: まだ通過していない機能の数が、harness がエージェントにかける圧力だ。圧力ゼロならプロジェクト完了。++## なぜ機能リストは「primitive」でなければならないのか++ドキュメントは人間が読むものだ。primitive はシステムが実行するものだ。ドキュメントは無視できるが、primitive は迂回できない。++データベースのトリガー制約とアプリケーション層のチェックの違いを考えるとよい。前者はデータベースエンジンが強制し、どんな SQL もスキップできない。後者はアプリケーションコードの正しさに依存し、うっかり迂回されることがある。harness primitive としての機能リストは、具体的に 4 つの harness コンポーネントに使われる。++1. **Scheduler**: 状態を読み、次の `not_started` 機能を選ぶ。工場の生産計画システムのようなもの。+2. **Verifier**: 検証コマンドを実行し、状態遷移を許可するか判断する。品質検査のようなもの。+3. **Handoff reporter**: 機能リストからセッション引き継ぎ要約を自動生成する。自動の交代報告のようなもの。+4. **Progress tracker**: 状態分布を集計し、プロジェクトの健全性指標を提供する。ダッシュボードのようなもの。++## 正しく行う方法++### 1. 最小の機能リスト形式を定義する++複雑なシステムは不要だ。構造化 Markdown か JSON ファイルでよい。重要なのは、各エントリが三要素を持つことだ。++```json+{+ "id": "F03",+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",+ "state": "passing",+ "evidence": "commit abc123, test output log"+}+```++### 2. 状態遷移は Harness に制御させる++エージェントは機能状態を直接 `passing` に変更できない。検証リクエストを出せるだけだ。harness が検証コマンドを実行し、遷移を許可するか判断する。これが pass-state gating だ。++### 3. ルールを CLAUDE.md に書く++```+## Feature List Rules+- Feature list file: /docs/features.md+- Only one feature active at a time+- Verification command must pass before marking as passing+- Don't modify feature list states yourself — the verification script updates them automatically+```++### 4. 粒度を調整する++各機能項目は「1 セッションで完了できる」範囲にする。広すぎると終わらず、狭すぎると管理コストが増える。「ユーザーが商品をカートに追加できる」はよい粒度だ。「ショッピングカートを実装する」は広すぎる。「Cart モデルに name フィールドを作る」は狭すぎる。ステーキを切るのと同じで、丸ごとでもひき肉でもない。++## 実例++10 個の機能を持つ e コマースプラットフォームで、2 つの追跡方法を比較した。++**メモモード**: エージェントは非構造化メモを使う。3 セッション後、メモは「user auth と product list は済み、shopping cart はだいたい完了だがバグあり、payments は未着手」になる。新しいセッションは状態推測に 20 分必要で、最終的に完了済み機能を再実装してしまう。買い物リストに「牛乳、パン、あと例のやつ」と書いてあるようなものだ。店に着いても、何を買えばよいか分からない。++**背骨モード**: すべての機能が明確な状態と検証コマンドを持つ。新しいセッションは機能リストを読み、3 分で F01-F05 は `passing`、F06 は `active`、F07-F10 は `not_started` と分かる。F06 から直接再開し、手戻りはゼロ。++定量結果: 構造化された機能リストを使うプロジェクトは、自由形式の追跡より機能完了率が 45% 高く、重複実装はゼロだった。++## 重要なポイント++- **機能リストは harness の背骨**であり、人間向けメモではない。Scheduler、verifier、handoff reporter はすべてそれに依存する。+- **すべての機能項目は三要素を持つ必要がある**: 振る舞い説明 + 検証コマンド + 現在状態。1 つでも欠けると不完全だ。3 本脚の椅子から 1 本抜けたようなものだ。+- **状態遷移は harness が制御する**。エージェントは自分で状態を変えられない。検証成功だけが昇格経路だ。+- **機能リストはプロジェクトの single source of truth**。すべての「何をするか」情報は 1 つのリストから導かれる。+- **粒度は「1 セッションで完了できる」に合わせる。**++## 参考資料++- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — エージェントのスコープ制御における「中核データ構造」として機能リストを明示+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 「成果物を外部化する」原則を強調+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — 契約設計の原則、機能リストの理論的基盤+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — テストピラミッドと振る舞い仕様の実践++## 演習++1. **機能リスト設計**: 最小の機能リスト JSON schema を定義する。id、振る舞い説明、検証コマンド、現在状態、証拠参照を含める。実プロジェクトの 5 機能を記述してみる。++2. **検証厳密度の比較**: 3 つの機能を選び、「緩い」検証(例: 「コードに構文エラーがない」)と「厳密な」検証(例: 「エンドツーエンドテストが通る」)を設計する。それぞれの false positive rate を比較する。++3. **Single Source 原則監査**: 既存のエージェントプロジェクトを確認し、機能リストと矛盾するスコープ情報(会話内の暗黙要求、コード内 TODO コメントなど)がないか調べる。すべての情報を機能リストへ統合する計画を設計する。diff --git a/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.mdnew file mode 100644index 0000000..8d42d8f--- /dev/null+++ b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md@@ -0,0 +1,6 @@+# クリーン状態チェックリスト++- 手動修復なしでアプリが起動する+- 現在の進捗が記録されている+- 未完了のインポートやインデックスステップが未記録のまま残っていない+- 次のエージェントが標準起動・検証パスをすぐに実行できるdiff --git a/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdnew file mode 100644index 0000000..b1cfd8d--- /dev/null+++ b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -0,0 +1,8 @@+# 講義 09 のコード++このフォルダーは、以下の例に使用してください:++- フィードバックとしてのログ+- ランタイム状態の可視性+- クリーン状態チェック+- リカバリの例diff --git a/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.tsnew file mode 100644index 0000000..fad1a3b--- /dev/null+++ b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts@@ -0,0 +1,241 @@+/**+ * victory-detector.ts+ *+ * Simulates an agent that claims task completion, then checks the claimed+ * state against actual verification. Outputs: claimed vs actual, highlighting+ * gaps between what the agent said and what's really true.+ *+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Task {+ name: string;+ claimedComplete: boolean;+ checks: VerificationCheck[];+}++interface VerificationCheck {+ description: string;+ claimed: boolean; // What the agent says+ actual: boolean; // What is actually true+ severity: "critical" | "warning";+}++// ---------------------------------------------------------------------------+// Simulated tasks with claimed vs actual states+// ---------------------------------------------------------------------------++const tasks: Task[] = [+ {+ name: "Add search endpoint",+ claimedComplete: true,+ checks: [+ {+ description: "Route handler exists",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Authentication middleware applied",+ claimed: true,+ actual: false, // Agent forgot auth+ severity: "critical",+ },+ {+ description: "Input validation added",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Unit tests written",+ claimed: true,+ actual: false, // Agent skipped tests+ severity: "critical",+ },+ {+ description: "Integration tests pass",+ claimed: true,+ actual: false, // No tests to run+ severity: "critical",+ },+ {+ description: "Documentation updated",+ claimed: true,+ actual: false, // Agent skipped docs+ severity: "warning",+ },+ ],+ },+ {+ name: "Fix pagination bug",+ claimedComplete: true,+ checks: [+ {+ description: "Bug reproduction case confirmed",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Root cause identified",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Fix applied",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Edge cases tested",+ claimed: true,+ actual: false, // Only happy path tested+ severity: "warning",+ },+ {+ description: "Regression tests added",+ claimed: true,+ actual: false,+ severity: "critical",+ },+ ],+ },+ {+ name: "Refactor auth module",+ claimedComplete: true,+ checks: [+ {+ description: "Old code removed",+ claimed: true,+ actual: false, // Old code still present+ severity: "warning",+ },+ {+ description: "All existing tests still pass",+ claimed: true,+ actual: false, // Two tests broke+ severity: "critical",+ },+ {+ description: "New auth flow works",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Migration guide written",+ claimed: true,+ actual: false,+ severity: "warning",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Verification+// ---------------------------------------------------------------------------++interface TaskVerification {+ taskName: string;+ claimedComplete: boolean;+ actuallyComplete: boolean;+ totalChecks: number;+ claimedPassing: number;+ actualPassing: number;+ gaps: { description: string; severity: string }[];+}++function verifyTask(task: Task): TaskVerification {+ const claimedPassing = task.checks.filter((c) => c.claimed).length;+ const actualPassing = task.checks.filter((c) => c.actual).length;+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);++ return {+ taskName: task.name,+ claimedComplete: task.claimedComplete,+ actuallyComplete: gaps.length === 0,+ totalChecks: task.checks.length,+ claimedPassing,+ actualPassing,+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");+ console.log("=".repeat(90));++ const verifications = tasks.map(verifyTask);++ for (const v of verifications) {+ console.log("\n Task: " + v.taskName);+ console.log(" " + "-".repeat(70));+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);++ if (!v.actuallyComplete) {+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);+ }++ // Detailed checks for this task+ const task = tasks.find((t) => t.name === v.taskName)!;+ console.log("\n Check detail:");+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;+ console.log(header);+ console.log(sep);++ for (const check of task.checks) {+ const claimedLabel = check.claimed ? "PASS" : "FAIL";+ const actualLabel = check.actual ? "PASS" : "FAIL";+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";+ const marker = gapLabel ? ">>" : " ";+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);+ }+ }++ // Overall summary+ console.log("\n" + "=".repeat(90));+ console.log(" OVERALL SUMMARY");+ console.log("=".repeat(90) + "\n");++ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;+ console.log(sHeader);+ console.log(sSep);++ for (const v of verifications) {+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);+ const cLabel = v.claimedComplete ? "Done" : "Pending";+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);+ }++ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;++ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");+ console.log(" Total undetected gaps: " + totalGaps);+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");+}++run();diff --git a/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdnew file mode 100644index 0000000..8cb28e3--- /dev/null+++ b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -0,0 +1,145 @@+[中文版本 →](../../../zh/lectures/lecture-09-why-agents-declare-victory-too-early/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# 講義 09. エージェントの早すぎる完了宣言を防ぐ++agentに「パスワードリセット」機能の実装を依頼するとします。agentはデータベーススキーマを変更し、APIエンドポイントを書き、メールテンプレートを追加し、ユニットテストを実行(すべて合格)し、自信満々に「完了した」と報告します。しかし実際に動かしてみると——パスワードリセットリンクが送信できない(メールサービスの設定が不足)、データベースマイグレーションが途中で失敗する(スキーマの不整合)、end-to-endフローは一度も実行されていない。++この感覚は馴染み深いはずです——試験用紙を全部埋め、自信満々に最初に提出したのに、成績発表で不合格になるのと同じです。用紙が埋まっていることと、答えが合っていることは別なのです。++これは決して稀な出来事ではありません。Guoらによる2017年のICMLの古典的論文が証明しました:**現代のニューラルネットワークは体系的に過信状態にある**——モデルが報告する信頼度は実際の精度よりも大幅に高いのです。AIコーディングagentにも同じことが言えます。agentは「完了した」と「感じ」ますが、実際にはほど遠いのです。harnessは、agentの「感覚」を、外部化された実行ベースの検証に置き換えなければなりません。++## なだらかな斜面++早すぎる完了宣言は、ほぼ常に同じパターンを辿ります。コードは問題なさそうに見えます——構文は正しく、ロジックは妥当で、静的解析にも明らかなエラーはありません。しかし、harnessは包括的な実行検証を強制していないため、agentは実際の実行をスキップするか、部分的なテストしか実行しません。ユニットテストは実行するがインテグレーションテストはスキップし、テストは実行するがカバレッジは確認しません。最終的に「コードは問題ない」ことが「機能は完成している」の証拠として扱われます。そして試験用紙が提出されます。++すべての段階で情報が失われます。タスク仕様からコード実装、そしてランタイム動作に至るまで、すべての変換でバイアスが生じる可能性があり、スキップされた検証ごとに情報の非対称性が悪化します。++## 3層の終了チェック++```mermaid+flowchart LR+ Claim["Agent says: done"] --> L1["First run<br/>lint / typecheck"]+ L1 --> L2["Then run<br/>tests and startup checks"]+ L2 --> L3["Finally run<br/>complete user flow"]+ L3 --> Done["Pass all three to be done"]+```++```mermaid+flowchart LR+ A["Code is written<br/>unit tests are green"] --> B["But app didn't really start<br/>full flow never ran"]+ B --> C["Config, DB, external service issues<br/>all remain hidden"]+ C --> D["So agent declares victory too early"]+```++## 中核概念++- **早すぎる完了宣言(Premature Completion Declaration)**: agentはタスクが完了したと主張しますが、未達成の正確性仕様がまだ存在します。核心的な問題は、agentがコードレベルでの局所的な自信に基づいて判断しているのに対し、システムレベルの正確性はグローバルな検証を必要とすることです。+- **信頼度キャリブレーションバイアス(Confidence Calibration Bias)**: agentの自己報告する完了信頼度と、実際の完了品質との間の体系的な乖離。複雑なマルチファイルタスクでは、このバイアスは有意に正の値になります——agentは常に実際のパフォーマンスよりも自信を持ちます。試験後に自分の点数を常に過大評価する学生のようなものです。+- **終了基準(Termination Criteria)**: harness内で定義された、明確で実行可能な一連の判断条件。agentは完了を宣言する前にすべての条件を満たさなければなりません。「完了」は主観的判断から客観的判定へと移行します。+- **検証・妥当性確認の二重ゲート(Verification-Validation Dual Gate)**: 第1の検証層は「コードが指定された動作を正しく実装したか」をチェックし、第2の妥当性確認層は「システムレベルの動作がend-to-endの要件を満たしているか」をチェックします。両方が合格して初めて完了と見なされます。+- **ランタイムフィードバック信号(Runtime Feedback Signals)**: プログラム実行からのログ、プロセス状態、ヘルスチェック。これがharnessが完了品質を判断するための客観的根拠です。+- **完了優先度制約(Completion Priority Constraint)**: まず機能の正確性を検証し、次にパフォーマンスを扱い、最後にスタイルに対処します。コア機能が検証されるまで、リファクタリングは禁止されます。++## ユニットテスト合格 ≠ タスク完了++これは最も一般的な罠であり、最も危険な罠でもあります。agentはコードを書き、ユニットテストを実行し、すべてグリーンになり、「完了」と言います。しかし、ユニットテストの設計思想——テスト対象を分離し、依存関係をモックすること——は、まさにクロスコンポーネントの問題を検出できない原因となっています:++**インターフェースの不一致**: renderプロセスからpreloadスクリプトに渡されるファイルパスが相対パスなのに、preloadスクリプトは絶対パスを期待している。それぞれのユニットテストはモックを使用して合格しています。この問題が発見されるのはend-to-endテストの時だけです。バンドの各ミュージシャンがそれぞれ完璧に練習していても、一緒に演奏するとキーが違うことに気づくのと同じです。++**状態伝播エラー**: データベースマイグレーションがテーブルスキーマを変更しても、ORMキャッシュレイヤーが古いスキーマのキャッシュエントリを保持し続けている。ユニットテストは毎回新しいモック環境を提供するため、このクロスレイヤーの状態不整合を検出できません。++**環境依存性**: コードはテスト環境(すべてモックされている)では正しく動作するが、実際の環境では設定の差異、ネットワーク遅延、サービスの利用不可により失敗する。リハーサルルームでは完璧に歌えても、ステージでは音響機器の問題に直面するようなものです。++### 「ついでにリファクタリング」は完了判断にとっての毒++Claude Codeには一般的な行動パターンがあります。コア機能が検証を通過する前に、コードのリファクタリング、パフォーマンスの最適化、スタイルの改善を始めてしまうことです。Knuthの「早すぎる最適化はすべての悪の根源」という言葉は、agentのシナリオで新たな意味を持ちます——リファクタリングは検証済みコードと未検証コードの境界を変更し、暗黙的に正しかったコードパスを壊す可能性があります。数学の記述問題をまだ終えていないのに、選択問題の解答をきれいに書き直すようなものです——時間の無駄だけでなく、書き間違える可能性もあります。++### 自己評価の体系的バイアス++Anthropicは2026年の研究で、より深い失敗パターンを発見しました:**agentに自身の成果を評価させると、人間の観察者が明らかに品質不十分と判断する場合でも、体系的に過度に肯定的な評価を提供します。** これは学生に自分の試験を採点させるようなもの——自分の答えには必ず甘くなります。++この問題は主観的なタスク(デザインの美しさなど)で特に深刻です。「レイアウトが洗練されている」かどうかは判断の問題であり、agentは確実に肯定的に偏ります。検証可能な結果を持つタスクであっても、agentのパフォーマンスは不適切な判断によって妨げられる可能性があります。++解決策は、agentを「より客観的に」することではありません——同じモデルが生成と評価を行うと、本質的に自分に甘くなります。**解決策は「作業者」と「検査者」を分離することです。** 学生が自分の試験を採点してはいけないのと同じ——独立した採点者が必要です。++独立した評価agent、特に「厳しい」ように調整されたものは、生成agentが自分自身を評価するよりもはるかに効果的です。Anthropicの実験データ:++| Architecture | Runtime | Cost | Core Features Working? |+|--------------|---------|------|------------------------|+| Single Agent (bare run) | 20 mins | $9 | No (game entities unresponsive to input) |+| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Yes (game is fully playable) |++これは全く同じモデル(Opus 4.5)で、全く同じプロンプト("build a 2D retro game editor")を使用しています。唯一の違いはharnessです——「ベア実行」から「plannerが要件を展開 → generatorが機能ごとに実装 → evaluatorがPlaywrightを使って実際のクリックテストを実行」へ。++> Source: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## 早すぎる提出を防ぐ方法++### 1. 終了判断の外部化++完了判断はagent自身が行うべきではありません。harnessはagentの信頼度ではなく、ランタイム信号を入力として使用し、独立して終了検証を実行しなければなりません。これを`CLAUDE.md`に明確に記述します:++```+## Definition of Done+- Feature complete = end-to-end verification passed, not "code is written"+- Required verification levels:+ 1. Unit tests pass+ 2. Integration tests pass+ 3. End-to-end flow verification passes+- Do not proceed to level 2 if level 1 fails+- Do not proceed to level 3 if level 2 fails+```++### 2. 3層の終了検証を構築する++- **第1層:構文と静的解析**。最も低コストで、情報は最も少ないが、合格しなければなりません。これは最低限のチェックです——他の何を見る前に、まず言葉のつづりが正しくなければなりません。+- **第2層:ランタイム動作検証**。テストの実行、アプリの起動チェック、クリティカルパスの検証。これが完了のコアとなる証拠です。書いただけでは不十分で、実行できなければなりません。+- **第3層:システムレベルの確認**。End-to-endテスト、インテグレーション検証、ユーザーシナリオのシミュレーション。早すぎる宣言に対する最後の防衛線です。実行できるだけでなく、正しく実行できなければなりません。++### 3. agent向けの優れた「赤ペンの書き込み」を設計する++OpenAIはCodexの実践で特に効果的なパターンを導入しました:**agent向けのエラーメッセージには修正手順を含めるべきです。** 怠惰な採点者のように大きな赤いバツ印だけをつけるのではなく、優しい教師のように余白に「ここはこう直すべきだ」と書きましょう。`"Test failed"`ではなく、`"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."`を使用してください。この具体的で実行可能なフィードバックにより、agentは人間の介入なしに自己修正できます。++### 4. ランタイム信号をキャプチャする++効果的なランタイム信号には以下が含まれます:+- アプリケーションは正常に起動し、準備完了状態に到達したか?+- クリティカルな機能パスはランタイムで正常に実行されたか?+- データベース書き込み、ファイル操作、その他の副作用は正しかったか?+- 一時リソースはクリーンアップされたか?++## 実際のケース++**タスク**:ユーザーのパスワードリセット機能の実装。データベース操作、メール送信、APIエンドポイントの変更が含まれます。++**早すぎる提出パス**:agentはデータベーススキーマを変更し、APIエンドポイントを書き、メールテンプレートを追加し、ユニットテストを実行(合格)し、完了を宣言します。試験用紙は完全に埋まっています。++**実際の減点**:(1)End-to-endフローが未テスト——リセットリンクの実際の送信と検証が一度も確認されていない。(2)データベースマイグレーションが部分実行後に失敗し、スキーマの不整合が発生。(3)対象環境にメールサービスの設定が不足。++**Harness介入**:終了検証を強制——(1)フルアプリを起動してリセットエンドポイントのアクセシビリティを検証。(2)フルリセットフローを実行。(3)データベース状態の一貫性を検証。すべての欠陥がセッション内で発見され、後続の修正コストの5〜10倍を節約。独立した採点者が本当の問題を見つけました。++## 重要なポイント++- **Agentは体系的に過信状態にある**——信頼度キャリブレーションバイアスは客観的な現実です。試験用紙を埋めたことと正解したことは別です。+- **完了判断は外部化しなければならない**——harnessが独立して検証する。agentの「感覚」を信じてはいけません。学生は自分の試験を採点できません。+- **3層すべての検証が不可欠**——構文合格、動作合格、システム合格、段階的に進める。+- **エラーメッセージは優しい教師の赤ペンの書き込みのように**——具体的な修正手順を含め、agentが自己修正できるようにする。+- **コア機能が検証されるまでリファクタリング禁止**——完了優先度制約が早すぎる最適化を防ぐ鍵。++## 参考資料++- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — 現代のディープネットワークが体系的に過信状態であることを証明+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 完了判断におけるランタイム証拠の重要な役割+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 早すぎる完了宣言はagentの主要な失敗モードの一つ+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — テスト手法の階層と有効性に関する古典的参考文献++## 演習++1. **終了検証機能の設計**:データベースマイグレーションとAPI変更を含むタスクについて、完全な終了検証を設計する。必要なランタイム信号と各信号の合格/不合格基準をリストアップする。実際のタスクで実行し、どのような隠れた問題を発見したか記録する。++2. **キャリブレーションバイアスの測定**:10種類の異なるタイプのコーディングタスクを選び、agentの自己報告する完了信頼度と実際の完了品質を記録する。バイアス値を計算し、タスクの複雑さとの関係を分析する。++3. **多層防御の実験**:同じタスクセットで3つの構成を実行する——(a)静的解析のみ、(b)ユニットテストを追加、(c)完全な3層検証。早すぎる完了宣言の割合と、未検出の欠陥数を比較する。diff --git a/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.mdnew file mode 100644index 0000000..862bca3--- /dev/null+++ b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md@@ -0,0 +1,6 @@+# Electron アーキテクチャルール++- レンダラーコードはファイルシステムに直接アクセスしてはならない。+- Preload はレンダラーと Electron main の間の唯一の橋渡しである。+- 検索・インデックスロジックは UI コンポーネントではなくサービスモジュールに配置する。+- ログは構造化され、サービス境界から出力されるべきである。diff --git a/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.tsnew file mode 100644index 0000000..2428416--- /dev/null+++ b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts@@ -0,0 +1,253 @@+/**+ * e2e-runner.ts+ *+ * A minimal E2E test harness. Defines test cases as user action sequences+ * (import doc -> index -> ask question -> verify citation). Simulates+ * running them and shows the difference between "unit tests pass" and+ * "full pipeline works".+ *+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface PipelineStep {+ name: string;+ unitTestPasses: boolean;+ // Simulated actual behavior in the pipeline+ actualBehavior: "works" | "fails" | "partial";+ failureReason?: string;+}++interface TestCase {+ name: string;+ steps: PipelineStep[];+}++interface TestResult {+ testCase: string;+ unitTestsPassed: number;+ unitTestsTotal: number;+ unitTestResult: "PASS" | "FAIL";+ e2eResult: "PASS" | "FAIL";+ e2eFailureStep?: string;+ e2eFailureReason?: string;+}++// ---------------------------------------------------------------------------+// Test cases -- realistic scenarios where unit tests pass but E2E fails+// ---------------------------------------------------------------------------++const testCases: TestCase[] = [+ {+ name: "Import document and ask question",+ steps: [+ {+ name: "Parse uploaded document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Store document chunks",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Index chunks for retrieval",+ unitTestPasses: true,+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions+ failureReason: "Embedding dimension mismatch between indexer and retriever",+ },+ {+ name: "Retrieve relevant chunks",+ unitTestPasses: true, // Unit test uses mock data with correct dimensions+ actualBehavior: "fails",+ failureReason: "Empty results due to dimension mismatch from previous step",+ },+ {+ name: "Generate answer with citations",+ unitTestPasses: true, // Unit test provides pre-retrieved chunks+ actualBehavior: "fails",+ failureReason: "No chunks retrieved, so answer has no citations",+ },+ ],+ },+ {+ name: "Delete document and verify removal",+ steps: [+ {+ name: "Find document by ID",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Delete document record",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Remove indexed chunks",+ unitTestPasses: true,+ actualBehavior: "fails", // Orphaned chunks remain in the index+ failureReason: "Index cleanup query timed out, chunks remain orphaned",+ },+ {+ name: "Verify document not in search results",+ unitTestPasses: true, // Unit test mocks the search+ actualBehavior: "fails",+ failureReason: "Orphaned chunks from previous step still appear in results",+ },+ ],+ },+ {+ name: "Multi-user concurrent access",+ steps: [+ {+ name: "User A imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User B imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User A queries their document",+ unitTestPasses: true,+ actualBehavior: "partial", // Cross-contamination of results+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",+ },+ {+ name: "Verify only User A's results returned",+ unitTestPasses: true,+ actualBehavior: "fails",+ failureReason: "Results include documents from other users",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Run tests+// ---------------------------------------------------------------------------++function runUnitTests(tc: TestCase): { passed: number; total: number } {+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;+ return { passed, total: tc.steps.length };+}++function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {+ // Pipeline: if any step actually fails, the whole E2E fails+ for (const step of tc.steps) {+ if (step.actualBehavior === "fails") {+ return {+ pass: false,+ failureStep: step.name,+ failureReason: step.failureReason ?? "Unknown failure",+ };+ }+ // "partial" means the step technically completes but creates problems downstream+ // We let it continue but track it+ }+ // Check if any step was "partial" (which may cause downstream issues)+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");+ if (partialSteps.length > 0) {+ // The partial steps may or may not cause overall failure+ // In our simulation, partial steps always lead to failure downstream+ // unless there's an explicit "fails" step that already caught it+ // This case means all steps were either "works" or "partial"+ return {+ pass: false,+ failureStep: partialSteps[partialSteps.length - 1].name,+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",+ };+ }++ return { pass: true };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(95));+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");+ console.log("=".repeat(95));++ const results: TestResult[] = testCases.map((tc) => {+ const unit = runUnitTests(tc);+ const e2e = runE2ETest(tc);++ return {+ testCase: tc.name,+ unitTestsPassed: unit.passed,+ unitTestsTotal: unit.total,+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",+ e2eResult: e2e.pass ? "PASS" : "FAIL",+ e2eFailureStep: e2e.failureStep,+ e2eFailureReason: e2e.failureReason,+ };+ });++ // Per-test-case detail+ for (let i = 0; i < testCases.length; i++) {+ const tc = testCases[i];+ const r = results[i];++ console.log("\n Test Case: " + tc.name);+ console.log(" " + "-".repeat(70));++ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;+ console.log(stepHeader);+ console.log(stepSep);++ for (const step of tc.steps) {+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";+ let e2eLabel: string;+ if (step.actualBehavior === "works") e2eLabel = "PASS";+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";+ else e2eLabel = "FAIL";++ const marker = step.actualBehavior !== "works" ? ">>" : " ";+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);+ }++ if (r.e2eFailureStep) {+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);+ console.log(` Reason: ${r.e2eFailureReason}`);+ }+ }++ // Summary comparison+ console.log("\n" + "=".repeat(95));+ console.log(" COMPARISON: Unit Tests vs E2E Tests");+ console.log("=".repeat(95) + "\n");++ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";++ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);+ }++ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");+}++run();diff --git a/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdnew file mode 100644index 0000000..709f6b0--- /dev/null+++ b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -0,0 +1,8 @@+# 講義 10 のコード++このフォルダーは、以下の例に使用してください:++- アーキテクチャ制約+- 構造テスト+- テストの不変条件(taste invariants)+- 修復指向の lint メッセージdiff --git a/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdnew file mode 100644index 0000000..0de230b--- /dev/null+++ b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -0,0 +1,10 @@+# 例:レビューフィードバックをルールに変換++繰り返しのレビューコメント:++> レンダラーからファイルシステムユーティリティを呼び出さないでください。Preload ブリッジを使用してください。++昇格された harness ルール:++- レンダラーコードでの `fs` 使用を防ぐ lint または import ルールを追加+- Preload 境界を説明する修復テキストを追加diff --git a/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdnew file mode 100644index 0000000..3c8c7ea--- /dev/null+++ b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -0,0 +1,158 @@+[中文版本 →](../../../zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)++> Code examples for this lecture: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)+> Hands-on practice: [Project 05. Let the agent verify its own work](./../../projects/project-05-grounded-qa-verification/index.md)++# 講義 10. End-to-End テストだけが本当の検証である++agentにElectronアプリへのファイルエクスポート機能の追加を依頼するとします。agentはrenderプロセスコンポーネント、preloadスクリプト、サービスレイヤーロジックを書きます。各コンポーネントのユニットテストは完璧に合格します。agentは「完了した」と言います。実際にエクスポートボタンをクリックしてみると——ファイルパスの形式が間違っていて、プログレスバーが更新されず、大きなファイルのエクスポートでメモリリークが発生します。5つのコンポーネント境界の欠陥があり、ユニットテストは一つも検出していません。++合唱のリハーサルのようなものです——各パートが単独で歌うときは完璧に聞こえますが、一緒に歌うと、ソプラノがベースより半拍速く、伴奏が主旋律から半音ずれています。各パートは単独では「正しい」のに、全体が音程を外しています。++Googleのテスティングピラミッドが教えてくれること:多数のユニットテストが基盤ですが、そこで止めると、コンポーネント間の相互作用の問題を体系的に見落とすことになります。AIコーディングagentの場合、この問題はさらに深刻です——agentは最速のテストだけを実行して完了を宣言する傾向があります。**End-to-endテストだけが、システムレベルの欠陥が存在しないことを証明できます。**++## ユニットテストの盲点++ユニットテストの設計思想は分離です——依存関係をモックし、テスト対象のユニットのみに焦点を当てます。この思想により、ユニットテストは高速で正確になりますが、同時に体系的な盲点も生み出します。合唱のリハーサルで各パートがヘッドフォンをつけて練習するようなものです——自分たちには問題なく聞こえますが、一緒になったときに初めて問題が浮かび上がります:++**インターフェースの不一致**: renderプロセスからpreloadスクリプトに渡されるファイルパスが相対パスなのに、preloadスクリプトは絶対パスを期待している。それぞれのユニットテストはモックを使用して合格しています。問題が発見されるのはend-to-endフローを実行したときだけです——2つのパートが独立して練習して問題を感じず、合奏で初めて一方が4/4拍子、もう一方が3/4拍子で歌っていることに気づくようなものです。++**状態伝播エラー**: データベースマイグレーションがテーブルスキーマを変更しても、ORMキャッシュレイヤーが古いスキーマのキャッシュエントリを保持し続けている。ユニットテストは毎回完全に新しいモック環境を提供するため、このクロスレイヤーの状態不整合を検出できません。曲の歌詞を変更したのに、誰かがまだ古いバージョンを歌っているようなものです。++**リソースライフサイクルの問題**: ファイルハンドル、データベース接続、ネットワークソケットの取得と解放は複数のコンポーネントにまたがります。ユニットテストは各テストで独立したリソースを作成・破棄するため、リソースの競合やリークを検出できません。リハーサルでは各パートが交代でマイクを使っていても、ステージで全員が同時に出るとマイクが足りないようなものです。++**環境依存性**: コードはテスト環境(すべてモックされている)では正しく動作するが、実際の環境では設定の差異、ネットワーク遅延、サービスの利用不可により失敗する。リハーサルルームでは完璧に歌えても、野外フェスでは音響フィードバックや風の干渉に直面するようなものです。++## End-to-Endテストは結果を変えるだけでなく、行動も変える++多くの人が気づかないことですが、agentは自身の成果がend-to-endテストの対象になることを知ると、コーディングの行動が変わります。++1. **コンポーネント間の相互作用を考慮する**:コードを書く際、「このインターフェースが上流とどう接続されるか」を考えるようになり、単一の関数に集中するだけではなくなります。最終的に一緒に歌うことが分かっていれば、練習中も他のパートに注意を払うようなものです。+2. **アーキテクチャ境界を尊重する**:アーキテクチャ制約のあるシステムでは、end-to-endテストがagentに境界ルールの遵守を強制します。楽譜に「ここでクレッシェンド」と書いてあれば、従わなければなりません。+3. **エラーパスを処理する**:End-to-endテストは通常、失敗シナリオを含むため、agentは例外処理を考慮せざるを得なくなります。リハーサルで「マイクが突然死んだらどうするか」をシミュレーションしておくようなものです。++## テスティングピラミッドとレビューフィードバックの昇格++```mermaid+flowchart TB+ subgraph Unit["Unit tests only check isolated parts"]+ U1["Renderer tests"]+ U2["Preload tests"]+ U3["Service tests"]+ end++ subgraph E2E["E2E runs through the real system"]+ R["Click renderer button"] --> P["Preload bridge"]+ P --> S["Service layer"]+ S --> F["File System / OS"]+ F --> Result["Actual exported file"]+ end+```++```mermaid+flowchart LR+ Review["Review feedback:<br/>renderer cannot import fs directly"] --> Rule["Add a direct fs import check"]+ Rule --> Message["Tell agent in error message<br/>to move file access to preload"]+ Message --> Harness["Add this check to harness"]+ Harness --> Stronger["Will fail immediately next time"]+```++Codexのエンジニアリング実践において、OpenAIは次のように強調しています:**agent向けに書かれたエラーメッセージには修正手順を含めなければならない。** `"Direct filesystem access in renderer"`とだけ書くのではなく、`"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."`と書きます。これにより、アーキテクチャルールが自動修正ループに変わります。合唱の指揮者が「そこ間違ってた」と言うだけでなく、「ここは半拍速かった、アルトのリズムを聞いて、32小節から入って」と具体的に指示するようなものです。++## 中核概念++- **コンポーネント境界の欠陥(Component Boundary Defects)**: コンポーネントAとBがそれぞれユニットテストに合格しても、それらの相互作用が不正な動作を生み出す。これはend-to-endテストが最も得意とする種類の問題です——各パートは単独では正しいのに、一緒になると音程が外れるようなものです。+- **テスト適切性グラデーション(Testing Adequacy Gradient)**: ユニットテストで検出される欠陥 <= インテグレーションテストで検出される欠陥 <= end-to-endテストで検出される欠陥。上の層に行くほど検出能力が上がります。+- **アーキテクチャ境界強制ルール(Architectural Boundary Enforcement Rules)**: アーキテクチャ文書のルール(「renderプロセスはファイルシステムに直接アクセスできない」など)を実行可能で自動化されたチェックに変えること。「紙に書かれたもの」から「CIで動くもの」へ。+- **レビューフィードバックの昇格(Review Feedback Promotion)**: 繰り返し出現するコードレビューのコメントを自動テストに変換すること。繰り返し発生する問題を見つけるたびにルールを追加し、harnessが自動的に強力になります。指揮者がよくあるリハーサルの間違いをウォームアップ練習に変えるようなものです——次に同じ間違いが起きても、練習自体がそれを浮き彫りにし、指揮者が一言も言う必要がありません。+- **agent向けエラーメッセージ(Agent-Oriented Error Messages)**: 失敗メッセージは「何が問題だったか」を述べるだけでなく、agentに「どう直せばいいか」を正確に伝えるべきです。これにより、テストの失敗が自己修正のフィードバックループになります。++## 実践方法++### 0. アーキテクチャ境界を先に定義してからE2Eテストを書く++End-to-endテストの前提条件は明確なシステム境界です。アーキテクチャがスパゲッティの皿のようなものなら、end-to-endテストが証明できるのは「このスパゲッティは動く」ということだけで、どこで設計意図が侵害されたかは教えてくれません。声部に分かれてすらいない合唱団のようなもの——いくらリハーサルしても上手くなりません。++OpenAIの経験:**agentが生成したコードベースでは、アーキテクチャ制約は初日の早い段階で前提条件として確立すべきであり、チームが大きくなってから考えるものではない。** 理由は単純です——agentはリポジトリ内の既存のパターンを、たとえそれが不均一で最適でなくてもコピーします。アーキテクチャ制約がなければ、agentはすべてのセッションでより多くの逸脱を持ち込みます。++OpenAIは「階層型ドメインアーキテクチャ」を採用しました——各ビジネスドメインは固定層に分割されます:Types → Config → Repo → Service → Runtime → UI。依存関係は厳密に前方に流れ、クロスドメインの関心事は明示的なProvidersインターフェースを通じて入ります。その他の依存関係は禁止され、カスタムlintによって機械的に強制されます。++重要な原則:**不変条件を強制し、実装を細かく管理しない。** 例えば、「データは境界で解析される」ことを要求しますが、どのライブラリを使うかは指定しません。エラーメッセージには修正手順を含めなければなりません——「違反」と言うだけでなく、agentに正確な変更方法を伝えます。++> Source: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++### 1. harnessにEnd-to-End層を含める++検証フローで明示的に定義します:クロスコンポーネントの変更を含むタスクでは、end-to-endテストに合格することが完了の前提条件です:++```+## Validation Hierarchy+- Level 1: Unit tests (Must pass)+- Level 2: Integration tests (Must pass)+- Level 3: End-to-end tests (Must pass when cross-component changes are involved)+- Skipping any required level = Not Complete+```++### 2. アーキテクチャルールを実行可能なチェックに変える++すべてのアーキテクチャ制約には、対応するテストまたはlintルールを設けます:++```bash+# Check if the render process directly calls Node.js APIs+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"+```++### 3. agent向けのエラーメッセージを設計する++失敗メッセージには3つの要素を含めます:何が問題だったか、なぜか、どう直すか:++```+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12+WHY: Renderer process has no access to Node.js APIs for security+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()+```++### 4. レビューフィードバック昇格プロセスを確立する++コードレビュー中に新しいタイプのagentエラーが見つかるたびに、それを自動チェックに変換します。1ヶ月後には、harnessは月初めよりも大幅に強力になっています。合唱のリハーサルノートのようなもの——各リハーサルで見つかった問題を記録し、次回の前にチェックします。時間が経つにつれてよくあるエラーは減り、音楽はより調和の取れたものになります。++## 実際のケース++**タスク**:Electronアプリにファイルエクスポート機能を実装する。renderプロセスUI、preloadスクリプトのファイルシステムプロキシ、サービスレイヤーのデータ変換が含まれます。++**各パートの単独歌唱(ユニットテスト合格)**:renderコンポーネントテスト(合格、ファイル操作はモック)、preloadスクリプトテスト(合格、ファイルシステムはモック)、サービスレイヤーテスト(合格、データソースはモック)。agentは完了を宣言。++**合同歌唱(End-to-Endテストで明らかになった欠陥)**:++| Defect | Description | Unit Test | E2E |+|--------|-------------|-----------|-----|+| Interface Mismatch | Inconsistent file path format | Missed | Caught |+| State Propagation | Export progress not sent back to UI via IPC | Missed | Caught |+| Resource Leak | Large file export handles not released | Missed | Caught |+| Permission Issue | Different permissions in packaged environment | Missed | Caught |+| Error Propagation | Service layer exceptions didn't reach UI layer | Missed | Caught |++5つの欠陥すべてがend-to-endテストで検出され、ユニットテストは一つも検出しませんでした。コストはテスト時間が2秒から15秒への増加——agentのワークフローでは完全に許容範囲です。各パートがどれほど上手に単独で歌えても、合同リハーサルには勝てません。++## 重要なポイント++- **ユニットテストはコンポーネント境界の欠陥に対して体系的に盲点がある**——その分離設計こそが、相互作用の問題の検出を妨げている。全員が正しく歌えても、合唱の音程が合っているとは限らない。+- **End-to-endテストは欠陥を検出するだけでなく、agentのコーディング行動も変える**——統合と境界により注目するようにさせる。+- **アーキテクチャルールは実行可能でなければならない**——読まれるのを待つ文書に書くのではなく、すべてのコミットで自動的にチェックする。+- **エラーメッセージはagent向けに設計しなければならない**——「どう直すか」の具体的な手順を含め、自己修正ループを形成する。+- **レビューフィードバックの昇格がharnessを自動的に強力にする**——検出された欠陥の各カテゴリが永久の防衛線になる。++## 参考資料++- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — テスティングピラミッドモデルの古典的出典+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — アーキテクチャ制約の自動実行のためのエンジニアリング実践+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — 能動的に障害を注入してシステムの回復力を検証+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — プロパティテスト手法、例示テストと形式検証の中間に位置する++## 演習++1. **クロスコンポーネント欠陥検出**:少なくとも3つのコンポーネントを含む変更タスクを選ぶ。まずユニットテストのみを実行して結果を記録し、次にend-to-endテストを実行する。追加で発見された各欠陥がどのタイプのクロスレイヤー相互作用の問題に属するか分析する。++2. **アーキテクチャルールの自動化**:プロジェクトからアーキテクチャ制約を一つ選び、実行可能なチェック(agent向けエラーメッセージ付き)に変換する。harnessに組み込み、ベースラインタスクで有効性を検証する。++3. **レビューフィードバックの昇格**:コードレビューの履歴から繰り返し出現するコメントのタイプを見つけ、5ステップのプロセスを使って自動チェックに変換する。昇格前後の問題の発生頻度を比較する。diff --git a/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.mdnew file mode 100644index 0000000..1fe83cb--- /dev/null+++ b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md@@ -0,0 +1,8 @@+# 評価ルーブリックの例++各ディメンションに 1-5 のスコアを使用:++- 根拠:回答はインポートされたソースに明確に結びついているか?+- 引用品質:ソース参照は可視的で具体的か?+- 機能性:ユーザーは質問-回答フローを完了できるか?+- 製品一貫性:ワークフローは統合されていると感じられるか?diff --git a/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdnew file mode 100644index 0000000..d4a8336--- /dev/null+++ b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md@@ -0,0 +1,8 @@+# 講義 11 のコード++このフォルダーは、以下の例に使用してください:++- プランナーの出力+- 評価ルーブリック+- ジェネレーター/エバリュエーターループ+- 単一エージェント vs マルチロールの比較diff --git a/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsnew file mode 100644index 0000000..213dc19--- /dev/null+++ b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts@@ -0,0 +1,260 @@+/**+ * runtime-logger.ts+ *+ * A structured logging module demo. Shows ad-hoc console.log output vs+ * structured JSON log output when diagnosing a failure. Includes a seeded+ * failure scenario and demonstrates how structured logs pinpoint the issue+ * faster.+ *+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StructuredLogEntry {+ timestamp: string;+ level: "info" | "warn" | "error" | "debug";+ component: string;+ action: string;+ durationMs?: number;+ input?: unknown;+ output?: unknown;+ error?: string;+ correlationId: string;+}++// ---------------------------------------------------------------------------+// Simulated pipeline with a seeded failure+// ---------------------------------------------------------------------------++const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);++// Simulated stages of a document Q&A pipeline+interface PipelineStage {+ component: string;+ action: string;+ durationMs: number;+ success: boolean;+ errorMessage?: string;+ input?: unknown;+ output?: unknown;+}++function runPipeline(): PipelineStage[] {+ return [+ {+ component: "DocumentLoader",+ action: "parse_upload",+ durationMs: 45,+ success: true,+ input: { filename: "report.pdf", size: "2.3MB" },+ output: { chunks: 47 },+ },+ {+ component: "ChunkIndexer",+ action: "embed_and_store",+ durationMs: 230,+ success: true,+ input: { chunks: 47 },+ output: { indexed: 47, embeddingDim: 1536 },+ },+ {+ component: "QueryRouter",+ action: "route_query",+ durationMs: 12,+ success: true,+ input: { query: "What is the revenue target?" },+ output: { routedTo: "RetrievalEngine" },+ },+ {+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch+ component: "RetrievalEngine",+ action: "semantic_search",+ durationMs: 180,+ success: false,+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",+ input: { query: "What is the revenue target?", topK: 5 },+ output: { results: 0 },+ },+ {+ component: "AnswerGenerator",+ action: "generate_with_citations",+ durationMs: 1500,+ success: true, // Doesn't crash, but produces a bad answer+ input: { context: [], query: "What is the revenue target?" },+ output: { answer: "I could not find relevant information.", citations: 0 },+ },+ ];+}++// ---------------------------------------------------------------------------+// Ad-hoc logging (console.log style)+// ---------------------------------------------------------------------------++function printAdHocLog(stages: PipelineStage[]): void {+ console.log("Starting document Q&A pipeline...");+ console.log("User uploaded report.pdf");++ for (const stage of stages) {+ if (stage.success) {+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);+ } else {+ console.log(`${stage.component}: something went wrong`);+ }+ }++ console.log("Pipeline finished. Answer: I could not find relevant information.");+}++// ---------------------------------------------------------------------------+// Structured logging (JSON)+// ---------------------------------------------------------------------------++function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {+ const entries: StructuredLogEntry[] = [];++ for (const stage of stages) {+ entries.push({+ timestamp: new Date().toISOString(),+ level: stage.success ? "info" : "error",+ component: stage.component,+ action: stage.action,+ durationMs: stage.durationMs,+ input: stage.input,+ output: stage.output,+ error: stage.errorMessage,+ correlationId: CORRELATION_ID,+ });+ }++ return entries;+}++// ---------------------------------------------------------------------------+// Diagnose failure from structured logs+// ---------------------------------------------------------------------------++function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {+ const diagnosis: string[] = [];++ // Find errors+ const errors = entries.filter((e) => e.level === "error");+ if (errors.length > 0) {+ diagnosis.push("ERRORS FOUND:");+ for (const err of errors) {+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);+ }+ }++ // Check for latency spikes+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);+ if (slowStages.length > 0) {+ diagnosis.push("LATENCY SPIKES:");+ for (const s of slowStages) {+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);+ }+ }++ // Check for cascading failures+ const emptyOutputs = entries.filter((e) => {+ const out = e.output as Record<string, unknown> | undefined;+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;+ });+ if (emptyOutputs.length > 0) {+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");+ for (const e of emptyOutputs) {+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);+ }+ }++ return diagnosis;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const pipeline = runPipeline();++ console.log("\n" + "=".repeat(90));+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");+ console.log("=".repeat(90));++ // --- Ad-hoc output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO A: Ad-hoc console.log output");+ console.log("-".repeat(90) + "\n");+ printAdHocLog(pipeline);+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");+ console.log(" The failure message is vague: 'something went wrong'.");+ console.log(" No dimensions, no input/output data, no correlation ID.");++ // --- Structured output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO B: Structured JSON log output");+ console.log("-".repeat(90) + "\n");++ const structuredEntries = printStructuredLog(pipeline);++ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const entry of structuredEntries) {+ const hasError = entry.error ? entry.error.slice(0, 30) : "";+ const marker = entry.level === "error" ? ">>" : " ";+ console.log(+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`+ );+ }++ // --- Diagnosis ---+ console.log("\n" + "-".repeat(90));+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");+ console.log("-".repeat(90) + "\n");++ const errors = structuredEntries.filter((e) => e.level === "error");+ for (const err of errors) {+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);+ console.log(` Error: ${err.error}`);+ console.log(` Input: ${JSON.stringify(err.input)}`);+ console.log(` Output: ${JSON.stringify(err.output)}`);+ console.log(` Correlation ID: ${err.correlationId}`);+ }++ // Downstream impact+ console.log("\n DOWNSTREAM IMPACT:");+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");+ if (answerGen) {+ const out = answerGen.output as Record<string, unknown>;+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);+ }++ // Comparison summary+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON");+ console.log("=".repeat(90) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);++ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");+}++run();diff --git a/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.mdnew file mode 100644index 0000000..eaccc4e--- /dev/null+++ b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md@@ -0,0 +1,12 @@+# スプリント契約の例++スプリント目標:++- 根拠のある Q&A 結果に可視的な引用を追加++「完了」の定義:++- ユーザーが質問する+- アプリが回答を返す+- 少なくとも1つの引用が表示される+- 引用をクリックするとドキュメントビューでソースの場所が開くdiff --git a/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdnew file mode 100644index 0000000..c3031be--- /dev/null+++ b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -0,0 +1,154 @@+[中文版本 →](../../../zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)+> 実践プロジェクト: [プロジェクト 06. 完全な harness(総合課題)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# 講義 11. エージェントのランタイムを観測可能にする++## この講義が解決する問題++エージェントに機能実装を頼むと、20 分走って大量のファイルを変更し、「完了しました。ただしテストが 2 つ失敗しています」と言ってきます。なぜ失敗しているのか聞くと「よくわかりません。タイミング問題かもしれません」。どの重要経路を変えたのか聞くと「コードを見てみます……」。++これはエージェントの能力不足ではありません。harness が十分な観測性を提供していないことが問題です。**観測性がなければ、エージェントは不確実なまま意思決定し、評価は主観的判断になり、再試行は手探りになります。** OpenAI も Anthropic も、信頼性を証拠の問題として扱っています。harness は、次の判断を導ける形でランタイム挙動と評価信号を露出しなければなりません。++## 中核概念++- **ランタイム観測性**: ログ、トレース、プロセスイベント、ヘルスチェックなどのシステムレベル信号。「システムが何をしたか」に答える。+- **プロセス観測性**: 計画、採点ルーブリック、受け入れ基準など、harness の判断成果物への可視性。「なぜこの変更を受け入れるべきか」に答える。+- **タスクトレース**: タスク開始から完了までの判断経路の完全な記録。分散システムのリクエストトレースに近い。エージェントの各ステップと文脈を記録する。+- **スプリント契約**: コーディング開始前に合意する短期契約。タスク範囲、検証基準、除外項目を明記する。プロセス観測性の中核ツール。+- **評価ルーブリック**: 品質評価を主観判断から証拠ベースの構造化スコアに変える。同じ出力に対して評価者が近い結果を出せるようにする。+- **階層化された観測性**: システム層とプロセス層の観測性を同時に設計し、相互に補強する。ランタイム信号は挙動を説明し、プロセス成果物は意図を説明する。++## 階層化された観測性++```mermaid+flowchart LR+ Contract["最初にタスクを書く<br/>何を変えるか / 変えないか / 合格基準"] --> Generator["Generator"]+ Generator --> Signals["実行中にアプリログ、トレース、<br/>ヘルスチェックを収集"]+ Contract --> Review["結果を項目ごとに確認<br/>挙動 / テスト / 境界"]+ Signals --> Review+ Review --> Verdict["失敗したチェックと<br/>修正場所を示す"]+ Verdict --> Generator+```++## なぜこれが起きるのか++### 観測性不足の本当のコスト++harness に観測性がないと、4 種類の問題が体系的に発生します。++**「正しい」と「正しそう」を区別できない**: コードレビュー上は完璧に見える関数でも、ランタイムでは特定入力のエッジケースで誤った結果を返すことがあります。実際の実行経路が期待から外れたことは、ランタイムトレースでしか見えません。++**評価が神秘主義になる**: 採点ルーブリックと受け入れ基準がないと、評価者(人間でもエージェントでも)は暗黙の前提に頼ります。同じ出力でも評価者によって判断が大きく変わり、品質評価が再現不能になります。++**再試行が盲目的な推測になる**: 失敗理由がわからないと、再試行の方向はランダムになります。本当の原因を無視して関係ないコード経路を直し続けるかもしれません。盲目的な再試行はすべてトークンと時間を消費します。++**セッション引き継ぎの情報断崖**: 未完了の作業を次セッションに渡すとき、観測性がないと新しいセッションはシステム状態をゼロから診断し直す必要があります。Anthropic の長時間エージェント観察では、この重複診断がセッション時間の 30-50% を消費することがあります。++### Claude Code での現実的なシナリオ++「アプリにダークモードを追加する」タスクを、planner-generator-evaluator の 3 役割 workflow で実行する harness を想像してください。++**観測性なし**: planner は曖昧な説明を出します。generator はその曖昧さをもとにダークモードを実装しますが、planner の暗黙期待と合いません。evaluator は自分の暗黙基準で却下しますが、具体的に何が悪いか説明できません。generator は曖昧な却下理由をもとに手探りで再試行します。これが 3-4 回繰り返され、45 分ほどかかり、かろうじて受け入れ可能な出力になります。++**完全な観測性あり**: planner はスプリント契約を出します。どのコンポーネントを変更するか、各コンポーネントの検証基準、除外項目(印刷スタイルは扱わない等)を列挙します。generator は契約に従って実装します。ランタイム観測性は各コンポーネントのスタイル読み込みと適用過程を記録します。evaluator は採点ルーブリックで次元ごとに評価し、証拠を引用します。1 回の反復で高品質な結果が出て、約 15 分で終わります。++効率差は 3 倍です。変わったのは観測性だけです。++### エージェントだけでは解決できない理由++「エージェント自身にログを出させればよいのでは」と思うかもしれません。問題は次のとおりです。++1. エージェントは自分が何を知らないかを知らないため、必要な信号を自発的に記録しません。+2. ログ形式が一貫しません。セッションごとに形式が違うと、体系的な分析ができません。+3. プロセス観測性はログだけでは解決できません。スプリント契約や採点ルーブリックは、harness レベルの支援を必要とする構造化成果物です。++## 正しく行う方法++### 1. ランタイム信号収集を harness に組み込む++エージェントが自分でログを出すことに頼らないでください。harness が次の信号を自動収集すべきです。++- **アプリケーションライフサイクル**: 起動、ready、running、shutdown の各状態+- **機能経路の実行**: 重要経路の入口、チェックポイント、出口の記録+- **データフロー**: コンポーネント間を流れるデータの記録+- **リソース利用**: メモリが増え続けるなど異常な利用パターン+- **エラーと例外**: エラーメッセージだけでなく完全な文脈++### 2. スプリント契約を実装する++各タスクの開始前に、generator と evaluator(同じエージェントの別呼び出しでもよい)が契約を合意します。++```markdown+# Sprint Contract: Dark Mode Support++## Scope+- Modify the theme toggle component+- Update global CSS variables+- Add dark mode tests++## Verification Standards+- Visual regression tests pass for each component+- Main flow end-to-end tests pass+- No flash of unstyled content (FOUC)++## Exclusions+- Not handling print styles+- Not handling third-party component dark mode+```++### 3. 評価ルーブリックを整備する++「良いか悪いか」を定量的な採点に変えます。++```markdown+# Scoring Rubric++| Dimension | A | B | C | D |+|-----------|---|---|---|---|+| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |+| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |+| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |+```++### 4. OpenTelemetry で標準化する++各 harness セッションに trace、各タスクに span、各検証ステップに sub-span を作ります。標準属性で重要情報を注釈します。これにより、観測性データを Jaeger や Zipkin などの標準ツールチェーンに統合できます。++## 実例++planner-generator-evaluator workflow の harness で「ダークモード対応を追加する」場合です。++**観測不能な版**: 盲目的な再試行が 3-4 回、45 分、かろうじて許容できる出力。evaluator は「何か違う」と言うだけで具体化できず、generator は大きな時間を誤った方向に使います。++**完全に観測可能な版**:+- スプリント契約が範囲、基準、除外項目を明確化+- ランタイムトレースが各コンポーネントのスタイル読み込み過程を記録+- 採点ルーブリックが次元ごとの構造化評価を提供+- 1 回の反復で高品質な結果、15 分++効率は 3 倍改善し、品質はより安定し、評価は再現可能になります。++## 重要なポイント++- **観測性は harness のアーキテクチャ属性**です。後から足す機能ではなく、設計時に考慮すべき中核能力です。+- **2 つの観測性レイヤーはどちらも必須**です。ランタイム信号は「何が起きたか」を説明し、プロセス成果物は「なぜそうしたか」を説明します。+- **スプリント契約は事前に認識を揃える**ため、「generator が作ったものを evaluator が予見可能な理由で即却下する」事態を防ぎます。+- **採点ルーブリックは評価を再現可能にする**ため、異なる評価者でも同じ出力に近いスコアを出せます。+- **観測性不足はセッション時間の 30-50% を重複診断に浪費します。**++## 参考資料++- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — 現代的な observability engineering の理論と実践+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — 大規模分散トレーシングの先駆的実践+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — スプリント契約と evaluator rubric の導入+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — 本番システムにおける観測性の体系的応用++## 演習++1. **観測性ギャップ分析**: 現在の harness をシステム層とプロセス層の観測性で監査します。既存信号では区別できないシステム状態を見つけ、追加案を出してください。++2. **スプリント契約練習**: 実タスクのスプリント契約を書きます。エージェントに契約に従って実行させ、契約あり/なしで効率と品質を比較してください。++3. **タスクトレース構築**: 完全なコーディングタスク中のエージェント操作をすべて記録します。OpenTelemetry の semantic conventions で注釈し、どのステップで判断に必要な信号が不足しているかを分析してください。diff --git a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.mdnew file mode 100644index 0000000..d625a5c--- /dev/null+++ b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md@@ -0,0 +1,18 @@+# ベンチマーク比較テンプレート++Harness A:++- 完了率+- 平均リトライ回数+- 人間のレビュー前に検出されたバグ++Harness B:++- 完了率+- 平均リトライ回数+- 人間のレビュー前に検出されたバグ++解釈:++- どの harness が結果を変えたか?+- どの harness が結果を得るためのコストを変えたか?diff --git a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.tsnew file mode 100644index 0000000..0388cad--- /dev/null+++ b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts@@ -0,0 +1,216 @@+/**+ * benchmark-runner.ts+ *+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),+ * "executes" each task, records timing and pass/fail, outputs a comparison+ * report showing which tasks pass and which fail.+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BenchmarkTask {+ id: string;+ name: string;+ category: string;+ passCriteria: string[];+ expectedDurationMs: number;+ // Simulated actual results+ actualDurationMs: number;+ actualPass: boolean;+ failureReason?: string;+}++interface BenchmarkResult {+ id: string;+ name: string;+ category: string;+ criteriaTotal: number;+ criteriaPassed: number;+ pass: boolean;+ expectedMs: number;+ actualMs: number;+ durationDelta: number;+ failureReason?: string;+}++// ---------------------------------------------------------------------------+// Benchmark task definitions+// ---------------------------------------------------------------------------++const benchmarkTasks: BenchmarkTask[] = [+ {+ id: "bench-001",+ name: "Import markdown document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 100,+ actualDurationMs: 95,+ actualPass: true,+ },+ {+ id: "bench-002",+ name: "Import PDF document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 200,+ actualDurationMs: 310,+ actualPass: false,+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",+ },+ {+ id: "bench-003",+ name: "Ask grounded question",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],+ expectedDurationMs: 500,+ actualDurationMs: 480,+ actualPass: true,+ },+ {+ id: "bench-004",+ name: "Ask question with no relevant docs",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],+ expectedDurationMs: 400,+ actualDurationMs: 420,+ actualPass: false,+ failureReason: "Model hallucinated a citation instead of saying 'no results'",+ },+ {+ id: "bench-005",+ name: "Delete imported document",+ category: "Document Pipeline",+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],+ expectedDurationMs: 150,+ actualDurationMs: 145,+ actualPass: true,+ },+ {+ id: "bench-006",+ name: "Concurrent user access",+ category: "Security",+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],+ expectedDurationMs: 300,+ actualDurationMs: 850,+ actualPass: false,+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",+ },+ {+ id: "bench-007",+ name: "Session continuity after restart",+ category: "Reliability",+ passCriteria: ["State persisted", "Session recovers", "No data loss"],+ expectedDurationMs: 200,+ actualDurationMs: 180,+ actualPass: true,+ },+ {+ id: "bench-008",+ name: "API rate limiting",+ category: "Security",+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],+ expectedDurationMs: 100,+ actualDurationMs: 100,+ actualPass: true,+ },+];++// ---------------------------------------------------------------------------+// Execution simulation+// ---------------------------------------------------------------------------++function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {+ return tasks.map((task) => ({+ id: task.id,+ name: task.name,+ category: task.category,+ criteriaTotal: task.passCriteria.length,+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),+ pass: task.actualPass,+ expectedMs: task.expectedDurationMs,+ actualMs: task.actualDurationMs,+ durationDelta: task.actualDurationMs - task.expectedDurationMs,+ failureReason: task.failureReason,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(100));+ console.log(" BENCHMARK RUNNER -- Task Execution Report");+ console.log("=".repeat(100));++ const results = executeBenchmark(benchmarkTasks);++ // Detailed results+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;+ console.log("\n" + header);+ console.log(sep);++ for (const r of results) {+ const passLabel = r.pass ? "PASS" : "FAIL";+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;+ const marker = r.pass ? " " : ">>";++ console.log(+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`+ );+ }++ // Failure details+ const failures = results.filter((r) => !r.pass);+ if (failures.length > 0) {+ console.log("\n" + "-".repeat(100));+ console.log(" FAILURE DETAILS");+ console.log("-".repeat(100));+ for (const f of failures) {+ console.log(`\n [${f.id}] ${f.name}`);+ console.log(` Category: ${f.category}`);+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);+ }+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SUMMARY BY CATEGORY");+ console.log("=".repeat(100) + "\n");++ const categories = [...new Set(results.map((r) => r.category))];+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;+ console.log(catHeader);+ console.log(catSep);++ for (const cat of categories) {+ const catResults = results.filter((r) => r.category === cat);+ const catPassed = catResults.filter((r) => r.pass).length;+ const catFailed = catResults.filter((r) => !r.pass).length;+ const rate = Math.round((catPassed / catResults.length) * 100);++ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);+ }++ // Overall+ const totalPassed = results.filter((r) => r.pass).length;+ const totalFailed = results.filter((r) => !r.pass).length;+ console.log("\n" + "-".repeat(100));+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);+ console.log("=".repeat(100) + "\n");+}++run();diff --git a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdnew file mode 100644index 0000000..166e452--- /dev/null+++ b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -0,0 +1,9 @@+# クリーンアップループの例++定期的なクリーンアップタスク:++- 古いドキュメントをスキャン+- 構造違反をスキャン+- 品質グレードを更新+- ターゲットを絞ったクリーンアップ PR を作成+- クリーンアップ後に固定ベンチマークスライスを再実行diff --git a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.tsnew file mode 100644index 0000000..6b35905--- /dev/null+++ b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts@@ -0,0 +1,336 @@+/**+ * cleanup-scanner.ts+ *+ * Scans a project directory for stale artifacts, dead code, structural+ * violations, and outputs a cleanup report. Helps enforce the "clean state+ * at end of every session" principle.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]+ * (defaults to current working directory)+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface ScanResult {+ category: string;+ check: string;+ severity: "critical" | "warning" | "info";+ found: string[];+ description: string;+}++// ---------------------------------------------------------------------------+// Scanner checks+// ---------------------------------------------------------------------------++interface ScannerCheck {+ category: string;+ name: string;+ severity: "critical" | "warning" | "info";+ description: string;+ scan: (dir: string) => string[];+}++function createChecks(): ScannerCheck[] {+ return [+ {+ category: "Stale Artifacts",+ name: "Temporary files (*.tmp, *.bak, *.swp)",+ severity: "warning",+ description: "Leftover temp files from editing or processing",+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),+ },+ {+ category: "Stale Artifacts",+ name: "Debug/log files in source",+ severity: "warning",+ description: "Log files that should not be in the source tree",+ scan: (dir) => {+ const found: string[] = [];+ const logPatterns = [".log"];+ for (const p of findFiles(dir, logPatterns)) {+ // Only flag log files in source directories+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {+ found.push(p);+ }+ }+ return found;+ },+ },+ {+ category: "Dead Code",+ name: "Unused imports (placeholder detection)",+ severity: "info",+ description: "Files that may contain unused code (heuristic scan)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app"];+ for (const srcDir of srcDirs) {+ const srcPath = path.join(dir, srcDir);+ if (fs.existsSync(srcPath)) {+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "Missing .gitignore",+ severity: "warning",+ description: "No .gitignore file found -- risk of committing build artifacts",+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],+ },+ {+ category: "Structural Violations",+ name: "Build artifacts in source",+ severity: "critical",+ description: "Compiled output (dist/, build/) mixed with source",+ scan: (dir) => {+ const found: string[] = [];+ // Check if dist/ or build/ exists inside src/+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];+ for (const d of dirs) {+ if (fs.existsSync(path.join(dir, d))) {+ found.push(d + "/");+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "node_modules in source tree",+ severity: "critical",+ description: "node_modules directory found outside root (nested dependency)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app", "test", "tests"];+ for (const srcDir of srcDirs) {+ const nmPath = path.join(dir, srcDir, "node_modules");+ if (fs.existsSync(nmPath)) {+ found.push(srcDir + "/node_modules/");+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Uncommitted changes indicator",+ severity: "info",+ description: "Checks for common artifacts of incomplete sessions",+ scan: (dir) => {+ const found: string[] = [];+ const indicators = [+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",+ "debug.ts", "test-manual.ts", "temp.ts",+ ];+ for (const f of indicators) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Empty directories",+ severity: "info",+ description: "Empty directories that may be leftover from incomplete work",+ scan: (dir) => {+ const found: string[] = [];+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];+ for (const d of commonDirs) {+ const dp = path.join(dir, d);+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {+ try {+ const contents = fs.readdirSync(dp);+ if (contents.length === 0) {+ found.push(d + "/");+ }+ } catch {+ // Skip directories we can't read+ }+ }+ }+ return found;+ },+ },+ {+ category: "Configuration",+ name: "Environment files in source",+ severity: "critical",+ description: ".env files that may contain secrets",+ scan: (dir) => {+ const found: string[] = [];+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];+ for (const f of envFiles) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ ];+}++// ---------------------------------------------------------------------------+// Helper functions+// ---------------------------------------------------------------------------++function findFiles(dir: string, extensions: string[]): string[] {+ const found: string[] = [];++ function walk(current: string, depth: number): void {+ if (depth > 4) return; // Limit recursion depth+ try {+ const entries = fs.readdirSync(current, { withFileTypes: true });+ for (const entry of entries) {+ // Skip common non-source directories+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {+ continue;+ }++ const fullPath = path.join(current, entry.name);+ const relativePath = path.relative(dir, fullPath);++ if (entry.isDirectory()) {+ walk(fullPath, depth + 1);+ } else if (entry.isFile()) {+ if (extensions.some((ext) => entry.name.endsWith(ext))) {+ found.push(relativePath);+ }+ }+ }+ } catch {+ // Skip directories we can't read+ }+ }++ walk(dir, 0);+ return found;+}++function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {+ try {+ const entries = fs.readdirSync(dir, { withFileTypes: true });+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);+ }+ continue;+ }++ const fullPath = path.join(dir, entry.name);+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {+ continue;+ }++ try {+ const content = fs.readFileSync(fullPath, "utf-8");+ const lines = content.split("\n");+ for (let i = 0; i < Math.min(lines.length, 50); i++) {+ for (const pattern of patterns) {+ if (lines[i].includes(pattern)) {+ const relative = path.relative(baseDir, fullPath);+ results.push(`${relative}:${i + 1} contains ${pattern}`);+ }+ }+ }+ } catch {+ // Skip files we can't read+ }+ }+ } catch {+ // Skip directories we can't read+ }+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");+ console.log("=".repeat(90));+ console.log(` Scanning: ${targetDir}\n`);++ const checks = createChecks();+ const results: ScanResult[] = [];++ for (const check of checks) {+ const found = check.scan(targetDir);+ results.push({+ category: check.category,+ check: check.name,+ severity: check.severity,+ found,+ description: check.description,+ });+ }++ // Report+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const count = r.found.length;+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";++ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);+ }++ // Summary+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);+ const clean = results.filter((r) => r.found.length === 0);++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SUMMARY");+ console.log("=".repeat(90) + "\n");++ console.log(` Critical issues: ${criticals.length}`);+ console.log(` Warnings: ${warnings.length}`);+ console.log(` Info items: ${infos.length}`);+ console.log(` Clean checks: ${clean.length}/${results.length}`);++ if (criticals.length > 0) {+ console.log("\n ACTION REQUIRED (Critical):");+ for (const c of criticals) {+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);+ console.log(` ${c.description}`);+ }+ }++ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);+ if (totalIssues === 0) {+ console.log("\n Project is in a clean state. No issues found.\n");+ } else {+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);+ }+}++run();diff --git a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdnew file mode 100644index 0000000..f91d686--- /dev/null+++ b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md@@ -0,0 +1,8 @@+# 講義 12 のコード++このフォルダーは、以下の例に使用してください:++- ベンチマークスライス+- クリーンアップタスク+- エントロピー削減の例+- 再現可能な harness 実行diff --git a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdnew file mode 100644index 0000000..6682cdf--- /dev/null+++ b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -0,0 +1,186 @@+[中文版本 →](../../../zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)++> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)+> 実践プロジェクト: [Project 06. Complete harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# 講義 12. すべてのセッションをきれいな引き継ぎで終える++## この講義が解決する問題++agentが午後ずっと動いて、20のファイルを変更し、コードをコミットし、セッションが終了します。次のagentセッションが始まると、すぐに発見します:ビルドが壊れている、テストが赤い、一時的なデバッグファイルが至る所にある、feature listが更新されていない、進捗が完全に不明。新しいセッションは最初の30分を「前のセッションが実際に何をしたのか」を理解するだけに費やします。++OpenAIとAnthropicはどちらも明確に述べています:**長期的な信頼性は、単発の実行成功ではなく、運用上の規律に依存する。** セッション終了時の状態の品質が、次のセッションの効率を直接的に決定します。Gitのベストプラクティスと同じように考えることができます——すべてのコミットはアトミックでコンパイル可能な変更であるべきで、未完成のコードの山ではありません。++## 中核概念++- **クリーン状態(Clean state)**: セッション終了時にシステムが5つの条件を満たしていること——ビルドが通る、テストが通る、進捗が記録されている、古いアーティファクトがない、起動パスが利用可能。どれか一つでも欠けていれば、そのセッションは「完了」ではありません。+- **セッション整合性(Session integrity)**: データベーストランザクションに似ています——完全にコミットしてクリーンな状態を残すか、最後の一貫した状態にロールバックするかのどちらか。中間はありません。+- **品質ドキュメント(Quality document)**: 各モジュールの品質評価を継続的に記録するアクティブなアーティファクト。一度きりの評価ではなく、コードベースが強くなっているか弱くなっているかを追跡するものです。+- **クリーンアップループ(Cleanup loop)**: コードベースのエントロピーを体系的に削減することを目的とした定期的なメンテナンスセッション。緊急の修正ではなく、日常の運用です。+- **harnessの簡素化(Harness simplification)**: モデルの能力が向上するにつれて、不要になったharnessコンポーネントを定期的に削除すること。今日不可欠な制約が、3ヶ月後には不要なオーバーヘッドになっているかもしれません。+- **冪等なクリーンアップ(Idempotent cleanup)**: クリーンアップ操作は何回実行しても同じ結果を生成します。これにより、失敗時のリトライシナリオでもクリーンアップが安全であることが保証されます。++## クリーン状態の5つの次元++```mermaid+flowchart LR+ Work["Feature work complete"] --> Build{"Build passes?"}+ Build -->|yes| Test{"Tests pass?"}+ Build -->|no| Fix["Fix before exit"]+ Test -->|yes| Record["Update feature list + progress"]+ Test -->|no| Fix+ Record --> Cleanup["Remove temp artifacts / debug code"]+ Cleanup --> Startup{"Standard startup path works?"}+ Startup -->|yes| Clean["Clean handoff"]+ Startup -->|no| Fix+ Fix --> Build+```++```mermaid+flowchart LR+ Dirty["Session ends with<br/>red tests / temp files / no progress update"] --> Diagnose["Next session first has to<br/>figure out what happened"]+ Diagnose --> Fragile["New work starts on a messy repo"]+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]+ More --> Dirty++ Clean["Session ends with<br/>green tests / updated progress / temp files removed"] --> Fast["Next session can start coding immediately"]+ Fast --> Stable["No need to rescue the repo first"]+ Stable --> Clean+```++## なぜこれが起きるのか++### エントロピーの増大がデフォルト状態++Lehmanのソフトウェア進化の法則が教えてくれること:継続的な変更を受けるシステムは、積極的に管理されない限り、必然的に複雑さが増大します。これはAIコーディングagentにとって特に当てはまります——すべてのセッションが変更を導入し、終了時のクリーンアップがなければ、技術的負債は指数関数的に蓄積します。++実際のデータが物語っています。agentを使って12週間開発されたプロジェクト、クリーンアップ戦略なしの場合:++- 週1:ビルド合格率 100%、テスト合格率 100%、新セッション起動 5分+- 週4:ビルド 95%、テスト 92%、起動 15分+- 週8:ビルド 82%、テスト 78%、起動 35分+- 週12:ビルド 68%、テスト 61%、起動 60分以上++同じプロジェクトでクリーンアップ戦略ありの場合:++- 週1:100%、100%、5分+- 週12:97%、95%、9分++12週間後:ビルド合格率の差は29ポイント、新セッション起動時間の差は85%。これは理論ではなく、観察された差異です。++### クリーン状態の5つの次元++クリーン状態とは単に「コードがコンパイルできる」ことではありません。5つの次元を総合的に評価するものです:++**ビルドの次元**:コードはエラーなくビルドできるか?これが最も基本的です——次のセッションが最初にビルドエラーを修正しなければならないべきではありません。++**テストの次元**:すべてのテストは通るか?セッションの前に存在していたテストも含みます——セッションは既存の機能を壊さない責任があります。そして「自分のマシンでは動く」ではなく、CIで検証されるべきです。++**進捗の次元**:現在の進捗は機械可読なアーティファクトに記録されているか?合格基準と共に完了したサブタスク、現在の状態と共に進行中だが未完了のサブタスク、未着手のサブタスク。良い進捗記録は、セッション起動時の診断時間を60〜80%削減します。++**アーティファクトの次元**:古い、または不明瞭な一時アーティファクトが残っていないか?デバッグログ、一時ファイル、コメントアウトされたコード、TODOマーカー——これらはすべて次のセッションの認知負荷を増やします。++**起動の次元**:標準起動パスは利用可能か?次のセッションは手動の介入なしに作業を開始できるか?環境の初期化、コードベースの読み込み、コンテキストの取得、タスクの選択——これらのパスが壊れていてはなりません。++### 「後で片付ける」は「絶対に片付けない」と同じ++最も一般的な精神的な罠は「このセッションは片付ける時間がない、次回やる」というものです。しかし、次のagentセッションはあなたが何を残したかを知りません——散らかったコードと不確かな状態を見るだけです。「このコードのどの部分が意図的で、どの部分が一時的なのか」を推測するのに多くの時間を費やすことになります。++さらに悪いことに、すべてのセッションには独自のタスク目標があります。新しいセッションは新しい作業をするために存在し、前のセッションの散らかりを片付けるためではありません。混乱を無視してその上に新しい作業を始め、混乱の上にさらに混乱を重ねます。これがエントロピーの正のフィードバックループです。++## 正しく行う方法++### 1. クリーン状態を完了要件にする++harnessで明示的に定義します:**セッション完了 = タスクが検証に合格 AND クリーン状態チェックに合格。** どちらかが欠けてもセッションは完了ではありません。CLAUDE.mdに書きます:++```+## Session Exit Checklist+- [ ] Build passes (npm run build)+- [ ] All tests pass (npm test)+- [ ] Feature list updated+- [ ] No debug code remaining (console.log, debugger, TODO)+- [ ] Standard startup path available (npm run dev)+```++### 2. デュアルモードのクリーンアップ戦略++2つのクリーンアップモードを組み合わせます:++**即時クリーンアップ(すべてのセッションの終了時)**:セッション中に作成された一時アーティファクトをクリーンアップし、feature listの状態を更新し、ビルドとテストが通ることを確認します。これは「参照カウント」型のクリーンアップです。++**定期クリーンアップ(週次)**:フルシステムスキャン——蓄積された構造的問題の処理、品質ドキュメントの更新、ドリフトを検出するためのベンチマークテストの実行。これは「トレーシング」型のクリーンアップです。++### 3. 品質ドキュメントを維持する++品質ドキュメントは各モジュールを継続的にスコアリングするアクティブなアーティファクトです:++```markdown+# Quality Document++## User Authentication Module (Quality: A)+- Verification passing: Yes+- Agent understandable: Yes+- Test stability: Stable+- Architecture boundaries: Compliant+- Code conventions: Followed++## Payment Module (Quality: C)+- Verification passing: Partial (payment callback untested)+- Agent understandable: Difficult (logic spread across 3 files)+- Test stability: Unstable (2 flaky tests)+- Architecture boundaries: Violations present+- Code conventions: Partially followed+```++新しいセッションはこのドキュメントを読み、すぐにどこを優先すべきかを把握します。まず最低スコアのモジュールを修正します。++### 4. 定期的にharnessを簡素化する++Anthropicからの重要なインサイト:**すべてのharnessコンポーネントは、モデルが自力で何かを確実にできないために存在する。しかし、モデルが改善するにつれて、これらの前提は時代遅れになる。** 3ヶ月前に不可欠だった制約が、今日では不要なオーバーヘッドになっているかもしれません。++推奨される実践:毎月1つのharnessコンポーネントを選び、一時的に無効にして、ベンチマークタスクを実行する。結果が劣化しなければ、永久に削除する。劣化する場合は、復元するか、より軽量な代替手段に置き換える。++### 5. クリーンアップ操作は冪等でなければならない++クリーンアップスクリプトは繰り返し実行しても安全であるべきです:++```bash+# Idempotent cleanup operations+rm -f /tmp/debug-*.log # -f ensures no error when files don't exist+git checkout -- .env.local # Restore to known state+npm run test # Verify cleanup didn't break anything+```++## 実際のケース++agentを使って12週間にわたり開発されたElectronアプリ、2つのアプローチの比較:++**クリーンアップ戦略なし**(対照群):週12でビルド合格率 68%、テスト合格率 61%、新セッション起動 60分以上、古いアーティファクト 103。++**クリーンアップ戦略あり**(実験群):各セッション終了時にフルクリーン状態チェック + 週次クリーンアップループ。週12でビルド合格率 97%、テスト合格率 95%、新セッション起動 9分、古いアーティファクト 11。++週12までに、実験群のビルド合格率は29ポイント高く、テスト合格率は34ポイント高く、新セッション起動時間は85%短縮されました。++## 重要なポイント++- **クリーン状態はセッション完了の必要条件**——オプションの片付けではなく、「完了の定義」の一部。+- **5つの次元すべてが必須**——ビルド、テスト、進捗、アーティファクト、起動——それぞれを明示的にチェックしなければならない。+- **品質ドキュメントがコードベースの健全性を追跡可能にする**——劣化していることを知って初めて修正できる。+- **定期的にharnessを簡素化する**——モデルの能力が向上するにつれて、不要になった制約を削除する。+- **「後で片付ける」は「片付けない」のと同じ**——エントロピーの増大がデフォルトであり、能動的なクリーンアップだけがそれに対抗できる。++## 参考資料++- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — コードの清潔さの体系的原則+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 再現性を中核とするharness設計要件+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — 長期的な信頼性に対するクリーンなセッション終了の重要な役割+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — 能動的なメンテナンスなしにはシステムの複雑さが必然的に増大することを証明するソフトウェア進化の法則++## 演習++1. **クリーン状態チェックリスト**:自分のコードベース向けに5つの次元すべてを網羅するセッション終了チェックリストを設計する。5回連続のセッションに適用し、各次元ごとの違反を記録する。++2. **ベンチマーク比較**:固定タスクセットを使用し、2つのharnessバリアント(クリーン状態要件あり/なし)で比較する。完了率、リトライ回数、欠陥流出率を比較する。++3. **harness簡素化の実践**:1つのharnessコンポーネントを選び、一時的に無効にしてベンチマークタスクを実行する。あり/なしの結果を比較し、維持、削除、または置換のいずれかを決定する。diff --git a/docs/ja/projects/index.md b/docs/ja/projects/index.mdnew file mode 100644index 0000000..08a6e7d--- /dev/null+++ b/docs/ja/projects/index.md@@ -0,0 +1,23 @@+# プロジェクトへようこそ++ここは Learn Harness Engineering の実践セクションです。講義を読むだけでは不十分です。自分で環境を作り、Codex、Claude Code、その他の AI エージェントがルールの違いでどう振る舞うかを観察します。++## プロジェクト概要++このコースには、信頼できるエージェント作業環境をゼロから構築するための 6 つの段階的な実践プロジェクトがあります。++1. **プロンプトのみ vs ルール優先**: プロンプトだけの場合と基本的な harness を使う場合で、エージェントの結果を比較します。+2. **エージェントが読めるワークスペース**: AI が理解しやすいリポジトリ構造と引き継ぎの仕組みを作ります。+3. **複数セッションの継続性**: 状態ファイルと初期化スクリプトを設計し、セッションをまたいで自然に作業を再開できるようにします。+4. **ランタイムフィードバックとスコープ制御**: エージェントが自分のコードをテストし、実行中にエラーを修正できる道具を導入します。+5. **自己検証と役割分離**: 幻覚や早すぎる完了宣言を防ぐため、独立したレビュー機構を作ります。+6. **完全な harness(総合課題)**: 観測可能で end-to-end に動く最終的なエージェント作業環境を組み立てます。++## 進め方++各プロジェクトフォルダには通常、次のものが含まれています。+- `starter/`: 開始用のワークスペース。+- `solution/`: 詰まったときに参照する実装例。+- 背景と具体的な目標を説明するタスク指示。++好みの AI Coding Agent(Claude Code、Cursor、Trae など)を使い、`starter/` ディレクトリ内でタスクを完了してください。diff --git a/docs/ja/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ja/projects/project-01-baseline-vs-minimal-harness/index.mdnew file mode 100644index 0000000..8eebfc8--- /dev/null+++ b/docs/ja/projects/project-01-baseline-vs-minimal-harness/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-01-baseline-vs-minimal-harness/)++> 関連講義: [講義 01. 強いモデルは信頼できる実行を意味しない](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [講義 02. harness とは何か](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)+> テンプレートファイル: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/resources/templates/)++# プロジェクト 01. プロンプトのみ vs ルール優先: どれほど差が出るか++## やること++最小限の Electron ナレッジベースアプリの外枠を作ります。左にドキュメント一覧、右に Q&A パネル、ローカルデータディレクトリを持つウィンドウです。タスク自体は複雑ではありません。複雑なのは、エージェントにどう完了させるかです。++同じ作業を 2 回実行します。1 回目は準備なしでプロンプトだけ。2 回目は `AGENTS.md`、`init.sh`、`feature_list.json` をあらかじめリポジトリに置いてから実行します。その後、結果を比較します。++このプロジェクトの核心はコードを書くことではありません。「最初に 15 分かけてルールを用意する」ことと「そのままエージェントに任せる」ことの差がどれほど大きいかを測ることです。++## ツール++- Claude Code または Codex(どちらかを選び、両方の実行で同じものを使う)+- Git(ブランチ管理と比較)+- Node.js + Electron(プロジェクトのスタック)+- タイマー(各実行時間を記録)++## Harness メカニズム++最小 harness: `AGENTS.md` + `init.sh` + `feature_list.json`diff --git a/docs/ja/projects/project-02-agent-readable-workspace/index.md b/docs/ja/projects/project-02-agent-readable-workspace/index.mdnew file mode 100644index 0000000..16c17fa--- /dev/null+++ b/docs/ja/projects/project-02-agent-readable-workspace/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-02-agent-readable-workspace/)++> 関連講義: [講義 03. リポジトリを唯一の信頼できる情報源にする](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [講義 04. 指示を複数ファイルに分ける](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+> テンプレートファイル: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/resources/templates/)++# プロジェクト 02. プロジェクトを読みやすくし、中断地点から再開できるようにする++## やること++新しいエージェントがプロジェクト構造、現在の進捗、次にやるべき作業をすばやく理解できるよう、リポジトリに「読みやすさ」を追加します。具体的には、ドキュメントのインポート、詳細表示、ローカル永続化を 2 セッションに分けて実装します。++同じ作業を 2 回実行します。1 回目は補助なし。2 回目は `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md` をあらかじめリポジトリに置いて実行します。++## ツール++- Claude Code または Codex+- Git+- Node.js + Electron++## Harness メカニズム++エージェントが読めるワークスペース + 永続化された状態ファイルdiff --git a/docs/ja/projects/project-03-multi-session-continuity/index.md b/docs/ja/projects/project-03-multi-session-continuity/index.mdnew file mode 100644index 0000000..74b77df--- /dev/null+++ b/docs/ja/projects/project-03-multi-session-continuity/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-03-multi-session-continuity/)++> 関連講義: [講義 05. セッションをまたいでコンテキストを保つ](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [講義 06. すべてのエージェントセッション前に初期化する](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+> テンプレートファイル: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/resources/templates/)++# プロジェクト 03. セッション再起動後もエージェントが作業を続けられるようにする++## やること++エージェントにスコープ制御と検証ゲートを追加します。ドキュメント分割、メタデータ抽出、インデックス進捗表示、引用付き Q&A フローを実装します。`feature_list.json` で機能状態を追跡し、一度に 1 機能だけ進め、検証証拠なしに `pass` とマークしないようにします。++同じ作業を 2 回実行します。1 回目は制約なし。2 回目は厳格なルールを適用します。++## ツール++- Claude Code または Codex+- Git+- Node.js + Electron++## Harness メカニズム++進捗ログ + セッション引き継ぎ + 複数セッション継続性diff --git a/docs/ja/projects/project-04-incremental-indexing/index.md b/docs/ja/projects/project-04-incremental-indexing/index.mdnew file mode 100644index 0000000..f581ea3--- /dev/null+++ b/docs/ja/projects/project-04-incremental-indexing/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-04-incremental-indexing/)++> 関連講義: [講義 07. エージェントのタスク境界を明確に引く](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [講義 08. 機能リストでエージェントの作業を制約する](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+> テンプレートファイル: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/resources/templates/)++# プロジェクト 04. ランタイムフィードバックでエージェントの挙動を修正する++## やること++起動ログ、インポート/インデックスログ、エラー状態などのランタイム観測性と、レイヤー越境を防ぐアーキテクチャ制約を追加します。さらに、エージェントに修正させるランタイムバグを仕込みます。++同じ作業を 2 回実行します。1 回目はログや制約なし。2 回目は適切なツールとルールを使います。++## ツール++- Claude Code または Codex+- Git+- Node.js + Electron++## Harness メカニズム++ランタイムフィードバック + スコープ制御 + 増分インデックスdiff --git a/docs/ja/projects/project-05-grounded-qa-verification/index.md b/docs/ja/projects/project-05-grounded-qa-verification/index.mdnew file mode 100644index 0000000..04baf17--- /dev/null+++ b/docs/ja/projects/project-05-grounded-qa-verification/index.md@@ -0,0 +1,22 @@+[中文版本 →](../../../zh/projects/project-05-grounded-qa-verification/)++> 関連講義: [講義 09. エージェントの早すぎる完了宣言を止める](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [講義 10. フルパイプライン実行だけが本当の検証である](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+> テンプレートファイル: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/resources/templates/)++# プロジェクト 05. エージェントに自分の作業を検証させる++## やること++役割分離を実装します。実装する generator、レビューする evaluator、必要に応じて planner を用意します。役割を追加するたびに効果を測るため、3 回実行します。++複数ターン会話、引用パネルの再設計、ドキュメントフィルタリングなど、実質的な機能改善を 1 つ選び、すべての実行で同じ対象を使います。++## ツール++- Claude Code または Codex+- Git+- Node.js + Electron++## Harness メカニズム++自己検証 + 根拠付き Q&A + 証拠に基づく完了判定diff --git a/docs/ja/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ja/projects/project-06-runtime-observability-and-debugging/index.mdnew file mode 100644index 0000000..4958077--- /dev/null+++ b/docs/ja/projects/project-06-runtime-observability-and-debugging/index.md@@ -0,0 +1,25 @@+[中文版本 →](../../../zh/projects/project-06-runtime-observability-and-debugging/)++> 関連講義: [講義 11. エージェントのランタイムを観測可能にする](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [講義 12. すべてのセッション終了時にきれいな引き継ぎを残す](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+> テンプレートファイル: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ja/resources/templates/)++# プロジェクト 06. 完全なエージェント harness を構築する(総合課題)++## やること++これは総合プロジェクトです。最初の 5 つのプロジェクトで学んだすべてを組み合わせ、完全なベンチマークを実行し、その後クリーンアップを行って品質が維持可能かを検証します。++ドキュメントインポート、インデックス、引用付き Q&A、ランタイム観測性、読みやすく再開可能なリポジトリ状態を含む、固定された複数機能タスクセットを使います。まず弱い harness のベースラインで実行し、次に最も強い harness で実行し、その後クリーンアップして再実行します。最後に harness の ablation 実験を行い、コンポーネントを 1 つずつ外して、どれが本当に重要かを確認します。++## ツール++- Claude Code または Codex+- Git+- Node.js + Electron+- 品質ドキュメントテンプレート+- 評価ルーブリック+- 最初の 5 プロジェクトで積み上げたすべての harness コンポーネント++## Harness メカニズム++完全な harness: すべてのメカニズム + 観測性 + ablation studydiff --git a/docs/ja/resources/index.md b/docs/ja/resources/index.mdnew file mode 100644index 0000000..5603263--- /dev/null+++ b/docs/ja/resources/index.md@@ -0,0 +1,50 @@+# 日本語リソースライブラリ++このフォルダは、コースで扱う方法を、実際のリポジトリで使えるコピー可能なテンプレートと短いリファレンスに変換したものです。++## いつ使うか++Codex、Claude Code、その他のコーディングエージェントに、セットアップ、進捗、スコープを毎回推測させず、複数セッションにわたって作業させたいときはここから始めます。++特に次のような場合に役立ちます。++- 作業が複数セッションにまたがる+- 機能が多く、途中で放置されやすい+- エージェントが早すぎる完了宣言をしがち+- 起動手順を毎回探し直している++## 最初に使うもの++最小構成では、次から始めます。++- ルート指示: [`templates/AGENTS.md`](./templates/AGENTS.md) または [`templates/CLAUDE.md`](./templates/CLAUDE.md)+- 機能状態: [`templates/feature_list.json`](./templates/feature_list.json)+- 進捗ログ: [`templates/claude-progress.md`](./templates/claude-progress.md)+- ブートストラップスクリプト参照: `docs/ja/resources/templates/init.sh`++次に追加します。++- セッション引き継ぎ: [`templates/session-handoff.md`](./templates/session-handoff.md)+- クリーン終了チェックリスト: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)+- 評価ルーブリック: [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)++OpenAI の "Harness engineering" 記事に近い、より本格的なリポジトリ構造が必要な場合は、高度なパックを使います。++- [`openai-advanced/index.md`](./openai-advanced/index.md)++## ライブラリ構成++- [`templates/`](./templates/index.md): 実際のリポジトリにコピーするテンプレート+- [`reference/`](./reference/index.md): 方法メモ、起動フロー、失敗モードのマップ+- [`openai-advanced/`](./openai-advanced/index.md): 高度なリポジトリ雛形、system-of-record ドキュメント、agent-first ガバナンステンプレート++## 推奨される最小パック++- `AGENTS.md` または `CLAUDE.md`+- `feature_list.json`+- `claude-progress.md`+- `init.sh`++この 4 つのファイルだけでも、多くのエージェントワークフローは目に見えて安定します。++リポジトリが複数ドメイン、アクティブな計画、品質スコア、信頼性ポリシーを持つ長期運用システムに育ったら、最小パックを無理に拡張するのではなく、[`openai-advanced/`](./openai-advanced/index.md) パックへ移行してください。diff --git a/docs/ja/resources/openai-advanced/index.md b/docs/ja/resources/openai-advanced/index.mdnew file mode 100644index 0000000..9b5639d--- /dev/null+++ b/docs/ja/resources/openai-advanced/index.md@@ -0,0 +1,83 @@+# OpenAI アドバンストパック++このフォルダーは、OpenAI の「Harness engineering: leveraging Codex in an agent-first world」+記事で説明されている、よりオピニオネイトされたリポジトリ構造を+すぐにコピーできるスターターファイルとしてパッケージしたものです。++このパックは、最小限のハーネスではもう十分ではなく、リポジトリが次のものを+必要とする場合に使用してください:++- 短いルーティングスタイルの `AGENTS.md`+- リポジトリ内の持続的なシステム・オブ・レコードドキュメント+- アクティブおよび完了した実行計画+- 明示的なプロダクト、信頼性、セキュリティ、フロントエンドポリシーファイル+- プロダクトドメインとアーキテクチャレイヤーによる品質スコアリング+- モデルに適した参照資料フォルダー+- アーキテクチャ、ナレッジキャプチャ、ランタイム検証のための標準運用手順++## 含まれるスターターレイアウト++[`repo-template/`](./repo-template/index.md) 配下のスターターパックは、+以下の構造を反映しています:++```text+AGENTS.md+ARCHITECTURE.md+docs/+├── design-docs/+│ ├── index.md+│ └── core-beliefs.md+├── exec-plans/+│ ├── active/+│ ├── completed/+│ └── tech-debt-tracker.md+├── generated/+│ └── db-schema.md+├── product-specs/+│ ├── index.md+│ └── new-user-onboarding.md+├── references/+│ ├── design-system-reference-llms.txt+│ ├── nixpacks-llms.txt+│ └── uv-llms.txt+├── DESIGN.md+├── FRONTEND.md+├── PLANS.md+├── PRODUCT_SENSE.md+├── QUALITY_SCORE.md+├── RELIABILITY.md+└── SECURITY.md+```++## 導入方法++1. リポジトリがまだ小規模な場合は、最小パックから始める。+2. より強固な構造が必要になったら、[`repo-template/`](./repo-template/index.md) の+ ファイルを自身のリポジトリにコピーする。+3. `AGENTS.md` は短く保つ。より深いドキュメントへのルーターとして扱い、+ 百科事典としては扱わない。+4. 品質、信頼性、計画ドキュメントは、独立したクリーンアップの日ではなく、+ 通常の作業の一部として更新する。+5. 生成された成果物と外部参照は明示的に保持し、エージェントが+ チャット履歴に頼らずに見つけられるようにする。++## SOP ライブラリ++[`sops/`](./sops/index.md) フォルダーは、記事の図を+ステップバイステップの運用手順に変換したものです:++- レイヤードドメインアーキテクチャのセットアップ+- 目に見えないナレッジをリポジトリにエンコード+- ローカルオブザーバビリティスタックとフィードバックループワークフロー+- UI作業のための Chrome DevTools 検証ループ++## 設計原則++- 短いエントリポイント、深くリンクされたドキュメント+- リポジトリをシステム・オブ・レコードとして扱う+- 機械的チェックは記憶されたルールに勝る+- 計画と品質履歴はコードの隣に置く+- クリーンアップと単純化は第一級の責務++このパックは意図的にオピニオネイトされていますが、盲目的にコピーするのではなく、+プロジェクトに合わせて適応させるべきです。diff --git a/docs/ja/resources/openai-advanced/repo-template/AGENTS.md b/docs/ja/resources/openai-advanced/repo-template/AGENTS.mdnew file mode 100644index 0000000..734ff7b--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/AGENTS.md@@ -0,0 +1,55 @@+# AGENTS.md++このリポジトリは長時間実行されるコーディングエージェントの作業に最適化されています。このファイルは短く保ち、巨大な指示のダンプではなく、記録のシステム文書へのルーティング層として使用してください。++## スタートアップワークフロー++コードを変更する前に:++1. `pwd` でリポジトリルートを確認する。+2. 現在のシステムマップと厳格な依存ルールを確認するため `ARCHITECTURE.md` を読む。+3. どのドメインやレイヤーが最も弱いかを確認するため `docs/QUALITY_SCORE.md` を読む。+4. `docs/PLANS.md` を読み、作業中のアクティブプランを開く。+5. `docs/product-specs/` の関連するプロダクト仕様を読む。+6. このリポジトリの標準ブートストラップと検証パスを実行する。+7. ベースライン検証が失敗している場合、スコープを追加する前にベースラインを修復する。++## ルーティングマップ++- `ARCHITECTURE.md`: ドメインマップ、レイヤーモデル、依存ルール+- `docs/design-docs/index.md`: 設計上の決定とコアビリーフ+- `docs/product-specs/index.md`: 現在のプロダクト動作と受け入れ基準+- `docs/PLANS.md`: プランのライフサイクルと実行プランのポリシー+- `docs/QUALITY_SCORE.md`: プロダクトドメインとレイヤーの健全性+- `docs/RELIABILITY.md`: ランタイムシグナル、ベンチマーク、再起動の期待値+- `docs/SECURITY.md`: シークレット、サンドボックス、データ、外部アクションのルール+- `docs/FRONTEND.md`: UIの制約、デザインシステムルール、アクセシビリティチェック++## ワーキングコントラクト++- 一度に一つの境界付けられたプランまたはフィーチャースライスから作業する。+- コードの検査だけで作業完了とマークしない。実行可能な証拠が必要である。+- 動作を変更した場合、同じセッションで対応するプロダクト、プラン、または信頼性の文書を更新する。+- 繰り返しのレビューフィードバックが見られた場合、チャットで再説明するのではなく、機械的なルール、チェック、またはリンターに昇格させる。+- 生成された素材は `docs/generated/` に、ソース参照は `docs/references/` に配置する。+- このファイルを肥大化させるのではなく、小さく最新の文書を追加することを優先する。++## 完了の定義++変更は以下のすべてが満たされた場合にのみ完了とみなされる:++- ターゲット動作が実装されている+- 必要な検証が実際に実行された+- 証拠が関連するプランまたは品質文書にリンクされている+- 影響を受ける文書が最新の状態である+- リポジトリが標準スタートアップパスからクリーンに再起動できる++## セッションの終了++セッションを終了する前に:++1. アクティブな実行プランを更新する。+2. ドメインやレイヤーに意味のある変更があった場合、`docs/QUALITY_SCORE.md` を更新する。+3. 債務を先送りした場合、`docs/exec-plans/tech-debt-tracker.md` に新しい債務を記録する。+4. 適切なタイミングで終了したプランを `docs/exec-plans/completed/` に移動する。+5. 次のアクションが明確な再起動可能な状態でリポジトリを残す。diff --git a/docs/ja/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/ja/resources/openai-advanced/repo-template/ARCHITECTURE.mdnew file mode 100644index 0000000..8c97ae0--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -0,0 +1,55 @@+# ARCHITECTURE.md++このファイルはシステムの最上位マップです。簡潔に保ち、必要に応じてより詳細な文書を指すようにしてください。++## システム構成++- プロダクト: `[製品名に置き換え]`+- プライマリユーザーワークフロー: `[メインワークフローに置き換え]`+- ランタイムサーフェス: `[desktop / web / cli / services / workers]`+- プロダクト動作の信頼できる情報源: `docs/product-specs/`++## ドメインマップ++| ドメイン | 目的 | プライマリエントリーポイント | 関連仕様 |+|--------|---------|----------------------|--------------|+| `[domain-a]` | `[所有する機能]` | `[modules / routes / commands]` | `[spec path]` |+| `[domain-b]` | `[所有する機能]` | `[modules / routes / commands]` | `[spec path]` |++## レイヤーモデル++エージェントが場当たり的なアーキテクチャを発明しないよう、固定方向モデルを使用する:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++横断的な関心事は、レイヤーを直接またぐのではなく、明示的なプロバイダーまたはアダプターの境界を通じて参加させるべきである。++## 厳格な依存ルール++- 下位レイヤーは上位レイヤーに依存してはならない。+- UIはランタイムまたはサービスの契約をバイパスしてはならない。+- データアクセスはリポジトリまたは同等のアダプターを通じて行わなければならない。+- 共有ユーティリティは汎用的であり続け、ドメインロジックを蓄積してはならない。+- 新しい依存関係は、対応するプランまたは設計文書で正当化されるべきである。++## 横断的インターフェース++| 関心事 | 承認された境界 | 備考 |+|--------|-------------------|-------|+| ロギングとトレーシング | `[provider / utility path]` | `[構造化のみ、場当たり的なコンソール使用は不可]` |+| 認証 | `[provider path]` | `[トークン/セッションルール]` |+| 外部 API | `[client or provider path]` | `[レート制限 / リトライガイダンス]` |+| フィーチャーフラグ | `[flag boundary]` | `[所有権]` |++## 現在のホットスポット++- `[エージェントが安全に変更するのが最も難しい領域]`+- `[境界が弱いかテストが脆弱な領域]`++## 変更チェックリスト++アーキテクチャ関連のコードに触れる場合:++1. ドメインマップまたは許可された境界が変更された場合、このファイルを更新する。+2. 理由が変更された場合、`docs/design-docs/` の関連設計文書を更新する。+3. ルールを機械的に強制すべき場合、実行可能チェックを追加または更新する。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/ja/resources/openai-advanced/repo-template/docs/DESIGN.mdnew file mode 100644index 0000000..1591a75--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/DESIGN.md@@ -0,0 +1,25 @@+# DESIGN.md++このファイルは設計のエントリポイントです。簡潔に保ち、`docs/design-docs/` 配下のより詳細なファイルへのルーティングに使用してください。++## 目的++単一のチャット、スプリント、またはレビュアーの記憶を超えて存続すべき、永続的なプロダクトおよびシステム設計上の決定を記録する。++## 以下の場合にこれを読む++- 現在の設計哲学が必要な場合+- 新しいパターンを導入しようとしている場合+- どの設計上の決定が確定しており、どれがまだ未決定かを知る必要がある場合++## 正式な設計文書++- `docs/design-docs/index.md`: 承認済み、提案中、非推奨の文書のインデックス+- `docs/design-docs/core-beliefs.md`: プロジェクト全体のエージェントファーストなビリーフ++## 設計ルール++- 設計文書は小さく、最新に保つ。+- 意思決定領域ごとに1つの文書を優先する。+- 変更が設計文書に依存する場合、プランや仕様から設計文書にリンクする。+- 設計ルールが運用上重要になった場合、自動チェックに昇格させるか `ARCHITECTURE.md` を更新する。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/ja/resources/openai-advanced/repo-template/docs/FRONTEND.mdnew file mode 100644index 0000000..c84c490--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/FRONTEND.md@@ -0,0 +1,23 @@+# FRONTEND.md++このファイルは、エージェントが予測不能にUIパターンを発明しないように、安定したフロントエンドの期待値を定義します。++## UIの原則++- 新しさよりも明確さを最適化する。+- インタラクションフローを発見可能かつ再開可能に保つ。+- 一回限りのバリアントよりも、少数の再利用可能なコンポーネントを優先する。+- アクセシビリティチェックは仕上げ作業ではなく、通常の検証の一部である。++## ガードレール++- デザインシステムまたはコンポーネントライブラリを `docs/references/` に文書化する。+- 主要なユーザー向けの状態を記録する:空、読み込み中、成功、エラー、リトライ。+- コピー、キーボード動作、視覚的階層をフロー全体で一貫させる。+- UIバグを修正した場合、対応する検証ステップを追加または更新する。++## 検証の期待値++- 重要なユーザージャーニーの証拠をキャプチャする。+- ブラウザまたはランタイムの検証ステップを関連するプランに記録する。+- 視覚的リグレッションが頻発する場合、スクリーンショットまたはDOMチェックを標準化する。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/ja/resources/openai-advanced/repo-template/docs/PLANS.mdnew file mode 100644index 0000000..4bf477e--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/PLANS.md@@ -0,0 +1,34 @@+# PLANS.md++このファイルは、実行プランの作成、更新、完了、アーカイブの方法を定義します。++## プランが必要な場合++以下の場合に実行プランを作成する:++- 1セッションを超える作業+- 複数のサブシステムを変更する作業+- 自明でない検証またはロールアウトリスクがある作業+- 記録すべき未決定の決定に依存する作業++## プランの場所++- `docs/exec-plans/active/`: 現在作業を推進しているプラン+- `docs/exec-plans/completed/`: 将来のエージェントコンテキストのために保持される完了プラン+- `docs/exec-plans/tech-debt-tracker.md`: 先送りされた作業とフォローアップ++## プランの必須セクション++- 目的+- スコープとスコープ外+- 検証パス+- リスクとブロッカー+- 進捗ログ+- 未決定事項++## 運用ルール++- 1つのアクティブプランには1つの明確に所有された現在のステップがあるべきである。+- 作業が進むにつれてプランを更新する。静的な文章として扱わない。+- 決定が実装の方向を変更した場合、プランに記録する。+- 終了したプランは `completed/` に移動し、エージェントが以前のコンテキストを発見できるようにする。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/ja/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.mdnew file mode 100644index 0000000..09c7cb0--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md@@ -0,0 +1,24 @@+# PRODUCT_SENSE.md++このファイルは、エージェントがコードだけからは確実に推測できない、永続的なプロダクト判断を記録します。++## プロダクトコア++- プライマリユーザー: `[置き換え]`+- 達成すべきジョブ: `[置き換え]`+- 取り除くべき主な不満: `[置き換え]`+- 受け入れのための品質基準: `[置き換え]`++## プロダクトルール++- 機能数よりもユーザーに見える信頼性を優先する。+- 曖昧な動作を推測の許可ではなく、仕様のギャップとして扱う。+- 実装がユーザーが見るものや信頼するものを変更した場合、対応する仕様を更新する。+- 具体的なフローにはプロダクト仕様を使用し、このファイルは横断的なプロダクト優先事項に使用する。++## 不可パターン++- 隠された破壊的アクション+- ユーザーフィードバックのないサイレントな失敗+- 表示状態の信頼できる情報源が不明確+- 一文で説明できない機能diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/ja/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.mdnew file mode 100644index 0000000..4e4958e--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md@@ -0,0 +1,39 @@+# QUALITY_SCORE.md++この文書は、リポジトリが時間とともに強くなっているか弱くなっているかを追跡します。++## 評価スケール++- `A`: 検証済み、読みやすい、安定、境界が強制されている+- `B`: 軽微なギャップはあるが動作する+- `C`: 部分的に動作、顕著な混乱または不安定性+- `D`: 壊れている、安全でない、または構造的に不明確++## プロダクトドメイン++| ドメイン | 評価 | 検証 | エージェント可読性 | テスト安定性 | 主要なギャップ | 最終更新 |+|--------|-------|-------------|-----------------|---------------|----------|-------------|+| `[domain-a]` | - | - | - | - | - | - |+| `[domain-b]` | - | - | - | - | - | - |+| `[domain-c]` | - | - | - | - | - | - |++## アーキテクチャレイヤー++| レイヤー | 評価 | 境界の強制 | エージェント可読性 | 主要なギャップ | 最終更新 |+|-------|-------|---------------------|-----------------|----------|-------------|+| Types | - | - | - | - | - |+| Services | - | - | - | - | - |+| Runtime | - | - | - | - | - |+| UI | - | - | - | - | - |++## ベンチマークスナップショット++| 日付 | ハーネスバリアント | 完了率 | リトライ | レビュー前の欠陥 | 備考 |+|------|-----------------|----------------|--------|-----------------------|------|+| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |++## 単純化ログ++| 日付 | 削除されたコンポーネント | 結果 | 決定 |+|------|-------------------|---------|----------|+| YYYY-MM-DD | `[component]` | `[degraded / unchanged]` | `[restore / keep removed]` |diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/ja/resources/openai-advanced/repo-template/docs/RELIABILITY.mdnew file mode 100644index 0000000..bce961f--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/RELIABILITY.md@@ -0,0 +1,32 @@+# RELIABILITY.md++このファイルは、システムが正常で再起動可能であることをどのように証明するかを定義します。++## 標準パス++- ブートストラップ: `[command]`+- 検証: `[command]`+- アプリまたはサービスの起動: `[command]`+- ランタイムのデバッグまたは検査: `[command]`++## 必要なランタイムシグナル++- スタートアップとクリティカルフローの構造化ログ+- 主要サービスのヘルスチェック+- 利用可能な場合、遅いパスのトレースまたはタイミングデータ+- 回復可能な障害のユーザーに見えるエラー状態++## ゴールデンジャーニー++- `[journey 1]`+- `[journey 2]`+- `[journey 3]`++各ゴールデンジャーニーには、反復可能な検証パスと明確な失敗シグナルが必要である。++## 信頼性ルール++- システムがクリーンに再起動できない場合、機能は完了とはみなされない。+- ランタイム障害はリポジトリローカルのシグナルから診断可能であるべきである。+- 繰り返される障害モードが現れた場合、ベンチマークまたはガードレールを追加する。+- クリーンアップは信頼性の一部であり、別個の関心事ではない。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/ja/resources/openai-advanced/repo-template/docs/SECURITY.mdnew file mode 100644index 0000000..d28b44d--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/SECURITY.md@@ -0,0 +1,27 @@+# SECURITY.md++このファイルは、エージェントが推測してはならないセキュリティと安全性のルールを定義します。++## シークレットと認証情報++- ソースや文書にシークレットをハードコードしない。+- ここで承認されたシークレット読み込みパスを文書化する。+- ログとスクリーンショットからトークン、APIキー、個人データをマスキングする。++## 信頼できない入力++- 外部コンテンツは検証されるまで信頼できないものとして扱う。+- ここで許可されたフェッチまたは実行の境界を記録する。+- プロンプトインジェクションまたはコマンドインジェクションのリスクが存在する場合、ガードレールを文書化する。++## 外部アクション++- 明示的な承認が必要なアクションをリストする。+- エージェントがデフォルトで実行してはならない本番または破壊的なコマンドを記録する。+- デバッグと検証にはサンドボックス安全なワークフローを優先する。++## 依存関係とレビューのルール++- 新しい依存関係はアクティブプランでの正当化が必要である。+- セキュリティに敏感な変更には明示的な検証ステップが必要である。+- 繰り返されるセキュリティレビューのコメントは、暗黙知ではなくチェックにするべきである。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/ja/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.mdnew file mode 100644index 0000000..9930584--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md@@ -0,0 +1,9 @@+# コアビリーフ++- リポジトリはエージェントにとってのシステム・オブ・レコードである。+- `AGENTS.md` はルーターであり、百科事典ではない。+- 検証の証拠は自信よりも重要である。+- 1つの境界付けられたタスクは、複数の未完了タスクより優れている。+- 繰り返される人間からのフィードバックは、再利用可能なハーネスルールにするべきである。+- クリーンアップと単純化は出荷の一部であり、後回しの作業ではない。+- エージェントがリポジトリ内で事実を発見できない場合、その事実は運用上利用不可能として扱う。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/ja/resources/openai-advanced/repo-template/docs/design-docs/index.mdnew file mode 100644index 0000000..675ce64--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/design-docs/index.md@@ -0,0 +1,21 @@+# デザインドキュメント インデックス++このインデックスを、デザイン履歴の発見可能なマップとして使用します。++## 承認済み++- `core-beliefs.md`: エージェントファーストの運用信念と持続的なプロジェクト規範++## 提案中++- `[新しいデザインドキュメントのパスをここに追加]`++## 非推奨++- `[古いまたは置き換えられたデザインドキュメントを置き換えリンクとともにここに移動]`++## メンテナンスルール++- すべてのデザインドキュメントには所有者または更新トリガーを設定する。+- 古くなったドキュメントは削除するか、放置せずに非推奨としてマークする。+- アクティブな実行計画を、それが依存するデザインドキュメントにリンクする。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/active/index.mdnew file mode 100644index 0000000..b658b6e--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md@@ -0,0 +1,11 @@+# アクティブな計画++このフォルダーには、アクティブな実行計画ごとに1つのマークダウンファイルを+保持してください。++推奨ファイル名パターン:++- `YYYY-MM-DD-short-topic.md`++各アクティブな計画は、新しいエージェントセッションが+リポジトリだけから作業を再開できる十分な最新状態であるべきです。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.mdnew file mode 100644index 0000000..86d4b98--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md@@ -0,0 +1,5 @@+# 完了した計画++完了した計画は削除せず、ここに移動してください。完了した計画は+リポジトリのメモリサーフェスの一部であり、後のエージェント実行が+コードが現在の状態になっている理由を理解するのに役立ちます。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.mdnew file mode 100644index 0000000..2ecd680--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md@@ -0,0 +1,8 @@+# テクニカルデトラッカー++このファイルは、現実に存在し、認識されており、意図的に先送りされている+テクニカルデットの記録に使用します。++| 日付 | 領域 | デット | 先送りの理由 | リスク | 次のトリガー |+|------|------|------|--------------|------|--------------|+| YYYY-MM-DD | `[area]` | `[debt]` | `[reason]` | `[risk]` | `[見直し時期]` |diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/ja/resources/openai-advanced/repo-template/docs/generated/db-schema.mdnew file mode 100644index 0000000..c53a2ba--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/generated/db-schema.md@@ -0,0 +1,14 @@+# データベーススキーマ++このフォルダーは、エージェントがコードからリバースエンジニアリングすることなく+確認できる、生成済みまたは派生した成果物のために使用します。++## ソース++- 生成元: `[command or source path]`+- 最終更新日: `YYYY-MM-DD`++## 注意事項++- 生成されたセクションは手動で編集しないでください。+- 基になるスキーマが変更された場合は、このファイルを再生成してください。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/ja/resources/openai-advanced/repo-template/docs/product-specs/index.mdnew file mode 100644index 0000000..ad409e0--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/product-specs/index.md@@ -0,0 +1,13 @@+# プロダクト仕様 インデックス++このフォルダーは、現在のユーザー向け動作仕様のために使用します。++## アクティブな仕様++- `new-user-onboarding.md`++## ルール++- 仕様はユーザーに見える動作と受け入れ基準を記述する。+- 実装が仕様から逸脱した場合、同じセッションでどちらかを更新する。+- 新しいエージェントがプロダクトのスコープを素早く発見できるよう、このインデックスを最新に保つ。diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/ja/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.mdnew file mode 100644index 0000000..2d2cfce--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md@@ -0,0 +1,26 @@+# 新規ユーザーオンボーディング++## 目標++新規ユーザーが持つべき初回実行体験を記述する。++## 開始条件++- `[フロー開始前の状態]`++## ユーザーフロー++1. `[ステップ1]`+2. `[ステップ2]`+3. `[ステップ3]`++## 受け入れ基準++- `[観察可能な結果]`+- `[観察可能な結果]`+- `[観察可能な結果]`++## 障害状態++- `[回復可能なエラーとユーザーフィードバック]`+- `[ブロックされた状態とフォールバック]`diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/ja/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txtnew file mode 100644index 0000000..6f1c612--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt@@ -0,0 +1,9 @@+Purpose: store model-friendly reference material for the design system.++Suggested contents:+- component naming rules+- spacing and typography tokens+- state variants+- accessibility expectations++Keep this file concise and refresh it when the upstream design system changes.diff --git a/docs/ja/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/ja/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txtnew file mode 100644index 0000000..c30cc9c--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt@@ -0,0 +1,8 @@+Purpose: store a clean agent-readable extract of the deployment or packaging+rules your repository depends on.++Suggested contents:+- build entrypoints+- runtime assumptions+- environment variable expectations+- common failure signaturesdiff --git a/docs/ja/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/ja/resources/openai-advanced/repo-template/docs/references/uv-llms.txtnew file mode 100644index 0000000..f2ceba9--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/docs/references/uv-llms.txt@@ -0,0 +1,8 @@+Purpose: store a compact reference for your Python package and environment+workflow when `uv` or similar tooling matters to the repo.++Suggested contents:+- install and sync commands+- lockfile policy+- virtualenv expectations+- verification commandsdiff --git a/docs/ja/resources/openai-advanced/repo-template/index.md b/docs/ja/resources/openai-advanced/repo-template/index.mdnew file mode 100644index 0000000..719cbfb--- /dev/null+++ b/docs/ja/resources/openai-advanced/repo-template/index.md@@ -0,0 +1,21 @@+# Advanced Repo Template++最小限のハーネスだけでなく、OpenAIスタイルのエージェントファーストなドキュメントサーフェスが必要な場合、このスターターを実際のリポジトリにコピーしてください。++## コピー順序++1. `AGENTS.md` と `ARCHITECTURE.md` をリポジトリルートにコピーする。+2. `docs/` ツリー全体をコピーする。+3. 最初に `docs/PRODUCT_SENSE.md`、`docs/QUALITY_SCORE.md`、`docs/RELIABILITY.md` を記入する。+4. `docs/exec-plans/active/` に最初のアクティブプランを追加する。+5. エントリポイントファイルは短く保ち、詳細はリンク先の文書に誘導する。++## このテンプレートが最適化しているもの++- 永続的なリポジトリローカルコンテキスト+- 巨大な単一の指示ファイルではなく、プログレッシブディスクロージャー+- 明示的なプランライフサイクル+- 時間経過による品質追跡+- エージェントと人間の両方にとって読みやすい境界++ここにあるすべてのファイルはスターターとして扱ってください。プレースホルダー、例、サンプルコマンドを実際のプロジェクトの詳細に置き換えてから使用してください。diff --git a/docs/ja/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/ja/resources/openai-advanced/sops/chrome-devtools-validation-loop.mdnew file mode 100644index 0000000..69ea2d6--- /dev/null+++ b/docs/ja/resources/openai-advanced/sops/chrome-devtools-validation-loop.md@@ -0,0 +1,52 @@+# SOP: Chrome DevTools 検証ループ++この SOP は、UI 作業が実際のランタイムでの操作に依存しており、+スクリーンショット、DOM 状態、コンソール出力がコードの検査単独よりも+重要な場合に使用します。++## 目標++UI 検証を、エージェントがジャーニーがクリーンになるまで実行できる+再現可能な操作ループに変換する。++## コアループ++1. 対象のページまたはアプリインスタンスを選択する。+2. 古いコンソールノイズをクリアする。+3. BEFORE 状態をキャプチャする。+4. UI パスをトリガーする。+5. 操作中のランタイムイベントを観察する。+6. AFTER 状態をキャプチャする。+7. 必要に応じて修正を適用し、アプリを再起動する。+8. ジャーニーがクリーンになるまで検証を再実行する。++## 必要な入力++- 安定した起動コマンド+- 再現可能な UI ジャーニー+- DOM、コンソール、またはスクリーンショットのスナップショットを取得する方法+- 「クリーン」とみなされる基準のルール++## 実行 SOP++1. アクティブな計画にターゲットジャーニーを記述する。+2. 成功を観察可能な条件で定義する: テキストの存在、ボタンの有効化、エラーの消失、+ コンソールのクリーン、リクエストの成功。+3. 操作前に初期状態のスナップショットを取得する。+4. 一度に正確に1つのパスをトリガーする。+5. ランタイムイベント、DOM 変更、可視出力を記録する。+6. ジャーニーが失敗した場合、最も責任のある最小のレイヤーを修正して再起動する。+7. 同じパスを再実行し、BEFORE/AFTER の証拠を比較する。++## クリーンの基準++- 意図された可視状態が存在する+- 予期しないエラーが存在しない+- コンソールノイズが理解されているかクリアされている+- 同じパスを再実行すると同じ結果が得られる++## 更新すべきリポジトリ成果物++- アクティブな実行計画+- ジャーニーがゴールデンパスになった場合の `docs/RELIABILITY.md`+- 可視動作が変更された場合のプロダクト仕様diff --git a/docs/ja/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/ja/resources/openai-advanced/sops/encode-knowledge-into-repo.mdnew file mode 100644index 0000000..edd76cb--- /dev/null+++ b/docs/ja/resources/openai-advanced/sops/encode-knowledge-into-repo.md@@ -0,0 +1,45 @@+# SOP: 目に見えないナレッジをリポジトリにエンコードする++この SOP は、重要なコンテキストが Google ドキュメント、チャットスレッド、+チケット、または人の頭の中にのみ存在する場合に使用します。++## 目標++エージェントから見えないナレッジをコードベースで発見可能にし、+新しいセッションが事前の会話に頼らずに対応できるようにする。++## トリガーシグナル++- エージェントがシステムの動作について繰り返し質問する。+- 人が「Slackでこう決めた」や「先週Xが言ったことに従って」と言う。+- レビューで、リポジトリ内に書かれていないプロダクトやセキュリティのルールが参照される。+- 新しいセッションが、すでに確定されているはずの発見作業を繰り返す。++## 実行 SOP++1. 目に見えないナレッジソースをリストアップする: ドキュメント、チャット、暗黙のチームルール、口頭の決定。+2. 各ソースについて確認する: これはアーキテクチャ、プロダクト動作、セキュリティポリシー、+ 信頼性要件、計画コンテキスト、参照資料のいずれか?+3. 該当するリポジトリ成果物にエンコードする:+ - アーキテクチャ -> `ARCHITECTURE.md`+ - プロダクト動作 -> `docs/product-specs/`+ - 設計の根拠 -> `docs/design-docs/`+ - 実行状態 -> `docs/exec-plans/`+ - 繰り返し使用される外部参照 -> `docs/references/`+ - 品質または信頼性の要件 -> `docs/QUALITY_SCORE.md` または `docs/RELIABILITY.md`+4. 曖昧な記述を運用上有用な表現に置き換える。+5. 古いコピーを削除または非推奨にし、リポジトリが1つの発見可能な真実を保つようにする。++## 良いエンコーディングのルール++- 文学的な完全さではなく、発見可能性のために書く。+- 明確なファイル名を持つ短いドキュメントを優先する。+- 関連する成果物同士をリンクする。+- 会議の議事録ではなく、持続的なルールを保存する。+- 決定が行われたのと同じセッションでリポジトリを更新する。++## 完了の定義++- 新しいエージェントが人間に質問せずに関連ルールを発見できる。+- 同じ事実が矛盾する複数のファイルに散らばっていない。+- 新しい成果物が、それが管理するコードやワークフローの近くに配置されている。diff --git a/docs/ja/resources/openai-advanced/sops/index.md b/docs/ja/resources/openai-advanced/sops/index.mdnew file mode 100644index 0000000..d3c8fc3--- /dev/null+++ b/docs/ja/resources/openai-advanced/sops/index.md@@ -0,0 +1,25 @@+# OpenAI アドバンスト SOP++これらの SOP は、記事の運用パターンを、フォローまたは適応可能な+具体的な実行プレイブックに変換したものです。++## 含まれる SOP++- [`layered-domain-architecture.md`](./layered-domain-architecture.md):+ 明示的なレイヤーと横断的関心事の境界を確立する+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):+ 目に見えないナレッジをチャット、ドキュメント、記憶からリポジトリ内のファイルに移動する+- [`observability-feedback-loop.md`](./observability-feedback-loop.md):+ エージェントにログ、メトリクス、トレース、再現可能なデバグループを提供する+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):+ ブラウザ自動化とスナップショットを使用して、クリーンになるまで UI の動作を検証する++## 使用方法++1. 現在のボトルネックに合った SOP を選ぶ。+2. チェックリストを使用して、欠けている成果物やツールをセットアップする。+3. 結果として得られたルールを、コピーした `repo-template/` ドキュメントにエンコードする。+4. 繰り返しのレビューコメントをチェック、スクリプト、ガードレールに変換する。++これらは盲目的にフォローすることを意図したものではありません。+ハーネスをより読みやすく、強制可能で、再現可能にするためのものです。diff --git a/docs/ja/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/ja/resources/openai-advanced/sops/layered-domain-architecture.mdnew file mode 100644index 0000000..a7e7513--- /dev/null+++ b/docs/ja/resources/openai-advanced/sops/layered-domain-architecture.md@@ -0,0 +1,51 @@+# SOP: レイヤードドメインアーキテクチャ++この SOP は、エージェントが境界を繰り返し違反している、レイヤー間で+ロジックを複製している、または数セッション後にレビューが困難なコードを+生成している場合に使用します。++## 目標++ドメインの境界を、エージェントが構造を知らずに劣化させることなく+迅速に移動できるほど明示的にする。++## ターゲットモデル++ビジネスドメイン内では、次の方向フローを推奨する:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++横断的関心事は、明示的なプロバイダーまたはアダプターを通じて出入りするべきである。+共有ユーティリティはドメインの外に置き、ドメインロジックを蓄積しないようにする。++## セットアップチェックリスト++- `ARCHITECTURE.md` で現在のドメインを定義する。+- `ARCHITECTURE.md` に許可される依存関係の方向を記述する。+- 認証、テレメトリ、外部 API などの横断的インターフェースを記録する。+- 現在最も困難な境界違反について短いメモを1つ追加する。+- lint、テスト、またはスクリプトによって機械的に強制すべきものを決定する。++## 実行 SOP++1. 実装スタイルに触れる前に、コードベースをドメインにマッピングする。+2. 各ドメインについて、許可されるレイヤーの順序を特定する。+3. すべての横断的関心事を特定し、プロバイダーまたはアダプターを通じてルーティングする。+4. 曖昧な共有ロジックを、所有するドメインまたは真に汎用的なユーティリティに移動する。+5. ルールを `ARCHITECTURE.md` に文書化する。+6. 最もコストの高い違反に対して1つの実行可能ガードレールを追加する。+7. 変更後に品質スコアを更新する。++## 完了の定義++- 新しいエージェントがどのレイヤーが変更を担当しているかを判断できる。+- UI コードがリポジトリや外部副作用に直接アクセスしなくなる。+- 横断的関心事に名前付きのエントリポイントがある。+- 少なくとも1つの重要な境界が機械的に強制されている。++## 更新すべきリポジトリ成果物++- `ARCHITECTURE.md`+- `docs/QUALITY_SCORE.md`+- 根拠が変更された場合の `docs/design-docs/`+- `docs/PLANS.md` またはアクティブな実行計画diff --git a/docs/ja/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/ja/resources/openai-advanced/sops/observability-feedback-loop.mdnew file mode 100644index 0000000..aaf9102--- /dev/null+++ b/docs/ja/resources/openai-advanced/sops/observability-feedback-loop.md@@ -0,0 +1,45 @@+# SOP: オブザーバビリティフィードバックループ++この SOP は、デバッグが遅い、エージェントが証拠なしに成功を主張し続ける、+またはランタイムの動作がコードよりも確認が難しい場合に使用します。++## 目標++エージェントにログ、メトリクス、トレース、実行可能なワークロードに対する+ローカルフィードバックループを提供し、コードの検査だけでなく、+実行結果から推論できるようにする。++## 最小スタック++- アプリケーションが構造化ログを出力する+- 可能な場合、アプリケーションがメトリクスとトレースを出力する+- ローカルのファンアウトまたはコレクションレイヤー+- ログ、メトリクス、トレース用のクエリインターフェース+- 各変更後に再実行するための再現可能なワークロードまたはユーザージャーニー++## 実行 SOP++1. 最も重要なゴールデンランタイムジャーニーを定義する。+2. スタートアップとクリティカルパスに構造化ログを追加する。+3. レイテンシ、失敗数、キューサイズなどの有用なメトリクスを追加する。+4. 遅いまたは複数ステップのフローにトレースまたはタイミングマーカーを追加する。+5. ローカル開発環境からシグナルをクエリ可能にする。+6. エージェントに再実行するための再現可能なワークロードまたはシナリオを1つ与える。+7. ループを必須にする: クエリ -> 相関 -> 推論 -> 実装 -> 再起動 ->+ 再実行 -> 検証。++## デバッグセッションチェックリスト++- 何が失敗したか?+- どのシグナルが失敗を証明しているか?+- どのレイヤーが失敗を担当しているか?+- 修正後に何が変更されたか?+- アプリは正常に再起動したか?+- 同じワークロードは再実行後に成功したか?++## 完了の定義++- エージェントがランタイムの証拠から障害モードを説明できる。+- 同じワークロードを各変更後に再実行できる。+- 再起動と再実行が通常のタスクループの一部である。+- 信頼性シグナルが `docs/RELIABILITY.md` に文書化されている。diff --git a/docs/ja/resources/reference/coding-agent-startup-flow.md b/docs/ja/resources/reference/coding-agent-startup-flow.mdnew file mode 100644index 0000000..7f95f52--- /dev/null+++ b/docs/ja/resources/reference/coding-agent-startup-flow.md@@ -0,0 +1,33 @@+# コーディングエージェント起動フロー++初期化完了後、毎セッションの開始時にこれを使用してください。++## 固定起動テンプレート++1. `pwd` を実行しリポジトリルートを確認する。+2. `claude-progress.md` を読む。+3. `feature_list.json` を読む。+4. `git log --oneline -5` で最近のコミットを確認する。+5. `./init.sh` を実行する。+6. ベースラインスモークまたはエンドツーエンドパスを実行する。+7. ベースラインが壊れている場合、まずそれを修正する。+8. 最優先の未完了機能を選択する。+9. 検証されるか明示的にブロックされるまでその機能のみに取り組む。++## なぜこの順序が重要か++- `pwd` は誤ったディレクトリでの作業を防ぐ。+- 進捗ファイルと機能ファイルは新しい編集が始まる前に永続的な状態を復元する。+- 最近のコミットは最近何が変更されたかを説明する。+- `init.sh` は記憶への依存ではなく起動を標準化する。+- ベースライン検証は新しい作業が隠す前に壊れた開始状態を検出する。++## セッション終了ミラー++同じセッションは以下で終了すべき:++1. 進捗を記録+2. 機能状態を更新+3. 必要に応じて引き継ぎを書く+4. 安全な作業をコミット+5. きれいな再起動パスを残すdiff --git a/docs/ja/resources/reference/index.md b/docs/ja/resources/reference/index.mdnew file mode 100644index 0000000..0d50096--- /dev/null+++ b/docs/ja/resources/reference/index.md@@ -0,0 +1,31 @@+# 日本語リファレンス++これらのノートは、テンプレートを緩いファイルの集まりではなく、動作する harness として+使用する方法を説明します。++## 内部リファレンスノート++- [`method-map.md`](./method-map.md): 一般的な長時間実行の失敗モードを、最初に対処する成果物やポリシーにマッピング+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md): 機能作業が始まる前にイニシャライザーが残すべきもの+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md): 後のコーディング実行用の固定セッション開始フロー+- [`prompt-calibration.md`](./prompt-calibration.md): ルート指示を肥大化・脆弱化させずにシャープに保つ方法++## 主要記事++このリストは意図的に絞られています。Harness とはモデル周りの実行システムを意味します:エージェントループ、ツール実行、サンドボックス、状態、コンテキスト、検証、終了、オーケストレーション、オブザーバビリティです。++元の3つの記事がコースの骨格であり続けます:++- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) (2026-02-11)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (2025-11-26)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) (2026-03-24)++## 推奨読書順++1. `method-map.md`+2. `initializer-agent-playbook.md`+3. `coding-agent-startup-flow.md`+4. `prompt-calibration.md`+5. OpenAI Harness engineering+6. Anthropic Effective harnesses+7. Anthropic Harness designdiff --git a/docs/ja/resources/reference/initializer-agent-playbook.md b/docs/ja/resources/reference/initializer-agent-playbook.mdnew file mode 100644index 0000000..f59317c--- /dev/null+++ b/docs/ja/resources/reference/initializer-agent-playbook.md@@ -0,0 +1,37 @@+# イニシャライザーエージェントプレイブック++インクリメンタルな機能作業が始まる前の、リポジトリでの最初の本格的なセッションに+このプレイブックを使用してください。++## 目標++後のセッションが起動コマンド、現在のステータス、タスク境界を再導出することなく+動作を実装できるよう、安定した稼働面を作成する。++## 必須出力++イニシャライザーは少なくとも以下の成果物を残すべき:++- `AGENTS.md` や `CLAUDE.md` などのルート指示ファイル+- `feature_list.json` などの機械可読な機能面+- `claude-progress.md` などの永続的な進捗成果物+- `init.sh` などの標準起動ヘルパー+- ベースラインスキャフォールドを捉えた最初の安全なコミット++## チェックリスト++1. 標準起動パスを定義する。+2. 標準検証パスを定義する。+3. 進捗ログを作成し開始状態を記録する。+4. 作業をステータス付きの明示的な機能に分解する。+5. 最初のクリーンなベースラインコミットを作成する。++## 成功テスト++以前のチャットコンテキストを持たない新しいセッションが以下に答えられるべき:++- このリポジトリは何をするのか+- どうやって起動するのか+- どうやって検証するのか+- 何が未完了か+- 次の最適ステップは何かdiff --git a/docs/ja/resources/reference/method-map.md b/docs/ja/resources/reference/method-map.mdnew file mode 100644index 0000000..1c863b0--- /dev/null+++ b/docs/ja/resources/reference/method-map.md@@ -0,0 +1,19 @@+# メソッドマップ++この表は、長時間実行されるコーディングエージェントの最も一般的な失敗モードを、+それを最初に修正する成果物や運用ルールにマッピングします。++| 失敗モード | 実践でどう見えるか | 主要な修正 | 補助成果物 |+| --- | --- | --- | --- |+| コールドスタートの混乱 | 新しいセッションがセットアップとステータスの再発見に大部分の時間を費やす | リポジトリをシステムオブレコードにする | `claude-progress.md` |+| スコープの拡散 | エージェントが複数の機能を開始し、どれもきれいに完了しない | アクティブスコープを制限する | `feature_list.json` |+| 早すぎる完了 | エージェントがコード編集後に完了を主張するが、実行可能な証拠の前 | 完了を証拠に紐付ける | `clean-state-checklist.md` |+| 脆弱な起動 | 毎セッションがプロジェクトの起動方法を再学習する | セットアップと検証を標準化する | `init.sh` |+| 弱い引き継ぎ | 次のセッションが何が検証済み、壊れている、次なのか判断できない | 明示的な引き継ぎで終了する | `session-handoff.md` |+| 主観的なレビュー | レビュー品質が好みや記憶に依存する | 固定カテゴリで出力を評価する | `evaluator-rubric.md` |++## 運用原則++観察された失敗モードを直接解決する最小の成果物を追加する。+すべての信頼性問題を1つのグローバル指示ファイルにより多くのテキストを投入して+解決することを避ける。diff --git a/docs/ja/resources/reference/prompt-calibration.md b/docs/ja/resources/reference/prompt-calibration.mdnew file mode 100644index 0000000..507adbe--- /dev/null+++ b/docs/ja/resources/reference/prompt-calibration.md@@ -0,0 +1,25 @@+# プロンプトキャリブレーション++ルート指示は操作フレームを定義すべきで、可能なすべての手を定義すべきではない。++## ルートファイルに残すもの++- リポジトリの目的とスコープ+- 起動パス+- 検証パス+- 譲れない制約+- 必要な状態成果物+- セッション終了ルール++## ルートファイルから出すもの++- 長い歴史的なエッジケース+- トピック固有の実装詳細+- コードの近くにあるべきローカルアーキテクチャノート+- 1つのサブシステムにのみ適用される例++## ワーキングルール++ルートファイルは新しいセッションが素早く方向付けされるのを助けるべき。ファイルが+過去のすべての失敗の捨て場になっている場合、詳細をより小さなドキュメントに分割し、+代わりにリンクする。diff --git a/docs/ja/resources/templates/AGENTS.md b/docs/ja/resources/templates/AGENTS.mdnew file mode 100644index 0000000..ef8fee0--- /dev/null+++ b/docs/ja/resources/templates/AGENTS.md@@ -0,0 +1,53 @@+# AGENTS.md++このリポジトリは長時間実行されるコーディングエージェント作業用に設計されています。目標は+生のコード出力を最大化することではありません。目標は、次のセッションが推測なしに+続けられる状態でリポジトリを残すことです。++## スタートアップワークフロー++コードを書く前に:++1. `pwd` で作業ディレクトリを確認する。+2. `claude-progress.md` で最新の検証済み状態と次のステップを読む。+3. `feature_list.json` を読み、最優先の未完了機能を選択する。+4. `git log --oneline -5` で最近のコミットを確認する。+5. `./init.sh` を実行する。+6. 新しい作業を始める前に必要なスモークまたはエンドツーエンド検証を実行する。++ベースライン検証が既に失敗している場合、まずそれを修正する。壊れた開始状態の上に+新しい機能作業を積み上げないこと。++## ワーキングルール++- 一度に一つの機能に取り組む。+- コードを追加しただけで機能を完了とマークしない。+- ブロッカーが狭範囲のサポート修正を強制しない限り、選択した機能スコープ内に変更を留める。+- 実装中に検証ルールを黙って変更しない。+- チャットサマリーより永続的なリポジトリ成果物を優先する。++## 必須成果物++- `feature_list.json`:機能状態の真実の情報源+- `claude-progress.md`:セッションログと現在の検証済みステータス+- `init.sh`:標準の起動・検証パス+- `session-handoff.md`:大きなセッション用のオプションのコンパクトな引き継ぎ++## 完了の定義++機能は以下がすべて true の場合にのみ完了:++- ターゲット動作が実装されている+- 必要な検証が実際に実行された+- 証拠が `feature_list.json` または `claude-progress.md` に記録されている+- リポジトリが標準起動パスから再起動可能である++## セッション終了時++セッションを終了する前に:++1. `claude-progress.md` を更新する。+2. `feature_list.json` を更新する。+3. 未解決のリスクやブロッカーを記録する。+4. 作業が安全な状態になったら説明的なメッセージでコミットする。+5. 次のセッションがすぐ `./init.sh` を実行できるようリポジトリをきれいに残す。diff --git a/docs/ja/resources/templates/CLAUDE.md b/docs/ja/resources/templates/CLAUDE.mdnew file mode 100644index 0000000..d819f00--- /dev/null+++ b/docs/ja/resources/templates/CLAUDE.md@@ -0,0 +1,44 @@+# CLAUDE.md++あなたは長時間の実装作業用に設計されたリポジトリで作業しています。+速度よりも、信頼性のある完了、セッション間の継続性、明示的な検証を優先してください。++## 運用ループ++毎セッションの開始時に:++1. `pwd` を実行し、予想されるリポジトリルートにいることを確認する。+2. `claude-progress.md` を読む。+3. `feature_list.json` を読む。+4. `git log --oneline -5` で最近のコミットを確認する。+5. `./init.sh` を実行する。+6. ベースラインのスモークまたはエンドツーエンドパスが既に壊れていないか確認する。++その後、未完了の機能を正確に1つ選び、検証されるかブロックされている理由が文書化されるまでその機能のみに取り組む。++## ルール++- 一度に1つのアクティブ機能のみ。+- 実行可能な証拠なしに完了を主張しない。+- 未完了の作業を隠すために機能リストを書き直さない。+- タスクが完了したように見せるためにテストを削除または弱体化させない。+- リポジトリ成果物をシステムオブレコードとして使用する。++## 必須ファイル++- `feature_list.json`+- `claude-progress.md`+- `init.sh`+- `session-handoff.md` — コンパクトな引き継ぎが有用な場合++## 完了ゲート++必要な検証が成功し、結果が記録された後にのみ、機能を `passing` に移行できる。++## 停止する前に++1. 進捗ログを更新する。+2. 機能状態を更新する。+3. まだ壊れているまたは未検証のものを記録する。+4. リポジトリが安全に再開できる状態になったらコミットする。+5. 次のセッションのためにきれいな再起動パスを残す。diff --git a/docs/ja/resources/templates/claude-progress.md b/docs/ja/resources/templates/claude-progress.mdnew file mode 100644index 0000000..34a384f--- /dev/null+++ b/docs/ja/resources/templates/claude-progress.md@@ -0,0 +1,35 @@+# 進捗ログ++## 現在の検証済み状態++- リポジトリルート:+- 標準起動パス:+- 標準検証パス:+- 現在の最優先未完了機能:+- 現在のブロッカー:++## セッションログ++### セッション 001++- 日付:+- 目標:+- 完了:+- 検証実行:+- 記録された証拠:+- コミット:+- 更新されたファイルや成果物:+- 既知のリスクや未解決の問題:+- 次の最適ステップ:++### セッション 002++- 日付:+- 目標:+- 完了:+- 検証実行:+- 記録された証拠:+- コミット:+- 更新されたファイルや成果物:+- 既知のリスクや未解決の問題:+- 次の最適ステップ:diff --git a/docs/ja/resources/templates/clean-state-checklist.md b/docs/ja/resources/templates/clean-state-checklist.mdnew file mode 100644index 0000000..d9e9592--- /dev/null+++ b/docs/ja/resources/templates/clean-state-checklist.md@@ -0,0 +1,8 @@+# クリーン状態チェックリスト++- [ ] 標準起動パスがまだ機能する。+- [ ] 標準検証パスがまだ実行される。+- [ ] 現在の進捗が進捗ログに記録されている。+- [ ] 機能状態が実際に合格しているものと未検証のものを反映している。+- [ ] 半完了のステップが未記録のまま残っていない。+- [ ] 次のセッションが手動修復なしに継続できる。diff --git a/docs/ja/resources/templates/evaluator-rubric.md b/docs/ja/resources/templates/evaluator-rubric.mdnew file mode 100644index 0000000..9935605--- /dev/null+++ b/docs/ja/resources/templates/evaluator-rubric.md@@ -0,0 +1,24 @@+# 評価ルーブリック++実装後、最終承認前にこのルーブリックを使用してください。++| カテゴリ | 質問 | スコア (0-2) | ノート |+| --- | --- | --- | --- |+| 正確性 | 実装された動作は要求された機能に一致しているか? | | |+| 検証 | 必要なチェックが証拠付きで実際に実行されたか? | | |+| スコープ規律 | セッションは選択された機能スコープ内に留まったか? | | |+| 信頼性 | 結果は修復なしに再起動や再実行に耐えるか? | | |+| 保守性 | コードとドキュメントは次のセッションにとって十分明確か? | | |+| 引き継ぎ準備 | 新しいセッションがリポジトリ成果物のみから作業を続けられるか? | | |++## 判定++- 承認+- 修正+- ブロック++## 必須フォローアップ++- 欠落している証拠:+- 必要な修正:+- 次回のレビュートリガー:diff --git a/docs/ja/resources/templates/feature_list.json b/docs/ja/resources/templates/feature_list.jsonnew file mode 100644index 0000000..138adc6--- /dev/null+++ b/docs/ja/resources/templates/feature_list.json@@ -0,0 +1,64 @@+{+ "project": "replace-with-project-name",+ "last_updated": "YYYY-MM-DD",+ "rules": {+ "single_active_feature": true,+ "passing_requires_evidence": true,+ "do_not_skip_verification": true+ },+ "status_legend": {+ "not_started": "Work has not begun.",+ "in_progress": "The feature is the current active task.",+ "blocked": "Work cannot continue until a documented blocker is resolved.",+ "passing": "Required verification has passed and evidence is recorded."+ },+ "features": [+ {+ "id": "chat-001",+ "priority": 1,+ "area": "chat",+ "title": "Create a new conversation",+ "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",+ "status": "not_started",+ "verification": [+ "Open the app.",+ "Click New Chat.",+ "Verify a new conversation appears in the sidebar.",+ "Verify the main panel shows an empty conversation state."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-002",+ "priority": 2,+ "area": "chat",+ "title": "Send a message in the current conversation",+ "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",+ "status": "not_started",+ "verification": [+ "Open an existing conversation.",+ "Type a message into the input.",+ "Submit the message.",+ "Verify the new message appears in the thread."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-003",+ "priority": 3,+ "area": "chat",+ "title": "Persist the active conversation list",+ "user_visible_behavior": "A user sees previously created conversations after restarting the app.",+ "status": "not_started",+ "verification": [+ "Create two conversations.",+ "Restart the app.",+ "Verify both conversations still appear in the sidebar."+ ],+ "evidence": [],+ "notes": ""+ }+ ]+}diff --git a/docs/ja/resources/templates/index.md b/docs/ja/resources/templates/index.mdnew file mode 100644index 0000000..341b3a0--- /dev/null+++ b/docs/ja/resources/templates/index.md@@ -0,0 +1,41 @@+# テンプレートガイド++これらのテンプレートはプロジェクトにコピーしてすぐ使えます。それぞれがエージェントのワークフロー内で特定の目的を持ちます。プロジェクトのコマンド、パス、機能名、検証ステップに合わせて内容を編集してください。++## はじめに++まず以下の4つのファイルをプロジェクトルートにコピーしてください:++1. `AGENTS.md` または `CLAUDE.md`+2. `init.sh`+3. `claude-progress.md`+4. `feature_list.json`++プロジェクトが成長するにつれて残りのファイルを追加してください。++---++## AGENTS.md++ルート指示ファイル。セッション開始時にエージェントが最初に読むファイルです。動作ルールを定義します:コードを書く前に何をするか、どう作業するか、どう終了するか。++Codex やその他のエージェントには `AGENTS.md` を使用。Claude Code と作業する場合は `CLAUDE.md` を使用 — 構造は同じで、Claude の指示スタイルに合わせた形式です。++## init.sh++起動スクリプト。依存関係のインストール、検証、開始コマンドの表示を一度に実行します。++## claude-progress.md++進捗ログ。毎セッションこのファイルに書き込み、新しいセッションは最初にこれを読みます。++## feature_list.json++機能トラッカー。エージェントが実装する必要があるすべての機能とそのステータス、検証ステップ、証拠の機械可読リストです。++## その他のファイル++- `session-handoff.md` — セッション間のコンパクトな引き継ぎメモ+- `clean-state-checklist.md` — 各セッション終了前に実行するチェックリスト+- `evaluator-rubric.md` — エージェント出力品質をレビューするスコアカード+- `quality-document.md` — 各プロダクトドメインとアーキテクチャレイヤーの品質スナップショットdiff --git a/docs/ja/resources/templates/init.sh b/docs/ja/resources/templates/init.shnew file mode 100755index 0000000..d7522d6--- /dev/null+++ b/docs/ja/resources/templates/init.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash++set -euo pipefail++ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+cd "$ROOT_DIR"++# Replace these commands with the correct commands for your repository.+INSTALL_CMD=(npm install)+VERIFY_CMD=(npm test)+START_CMD=(npm run dev)++echo "==> Working directory: $PWD"+echo "==> Syncing dependencies"+"${INSTALL_CMD[@]}"++echo "==> Running baseline verification"+"${VERIFY_CMD[@]}"++echo "==> Startup command"+printf ' %q' "${START_CMD[@]}"+printf '\n'++if [ "${RUN_START_COMMAND:-0}" = "1" ]; then+ echo "==> Starting the app"+ exec "${START_CMD[@]}"+fi++echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."diff --git a/docs/ja/resources/templates/quality-document.md b/docs/ja/resources/templates/quality-document.mdnew file mode 100644index 0000000..5774696--- /dev/null+++ b/docs/ja/resources/templates/quality-document.md@@ -0,0 +1,43 @@+# 品質ドキュメント++各プロダクトドメインとアーキテクチャレイヤーの品質スナップショット。エージェントと人間の両方がこのドキュメントを使用して、コードベースがどこが強いか、どこに作業が必要かを素早く理解できます。++**更新頻度:** 各重要セッションの後、または新しい作業フェーズを開始する前に。++**評価スケール:**++- **A**:すべての検証合格、クリーンなアーキテクチャ、エージェント可読、安定したテスト+- **B**:検証合格、ほぼクリーン、可読性やテストカバレッジに小さなギャップ+- **C**:部分的に動作、既知のギャップ、一部のコード領域がエージェントにとって理解困難+- **D**:動作しない、または重大な構造的問題++---++## プロダクトドメイン++| ドメイン | 評価 | 検証 | エージェント可読性 | テスト安定性 | 主要ギャップ | 最終更新 |+|--------|------|------|-----------------|------------|------------|----------|+| ドキュメントインポート | - | - | - | - | - | - |+| ドキュメント管理 | - | - | - | - | - | - |+| ドキュメントインデックス | - | - | - | - | - | - |+| Q&A フロー | - | - | - | - | - | - |+| 根拠付き回答 | - | - | - | - | - | - |++## アーキテクチャレイヤー++| レイヤー | 評価 | 境界の強制 | エージェント可読性 | 主要ギャップ | 最終更新 |+|---------|------|-----------|-----------------|------------|----------|+| メインプロセス | - | - | - | - | - |+| Preload | - | - | - | - | - |+| Renderer | - | - | - | - | - |+| Services | - | - | - | - | - |++## 変更履歴++### YYYY-MM-DD++- 変更内容:+- 昇格したドメイン:+- 降格したドメイン:+- 新たに特定されたギャップ:+- 解消されたギャップ:diff --git a/docs/ja/resources/templates/session-handoff.md b/docs/ja/resources/templates/session-handoff.mdnew file mode 100644index 0000000..741bc77--- /dev/null+++ b/docs/ja/resources/templates/session-handoff.md@@ -0,0 +1,30 @@+# セッションハンドオフ++## 現在検証済み++- 現在動作しているもの:+- 実際に実行された検証:++## このセッションでの変更++- 追加されたコードや動作:+- インフラや harness の変更:++## 壊れているまたは未検証++- 既知の欠陥:+- 未検証のパス:+- 次セッションへのリスク:++## 次の最適ステップ++- 最優先の未完了機能:+- なぜこれが次なのか:+- 何が合格とみなされるか:+- そのステップ中に変更してはならないもの:++## コマンド++- 起動:+- 検証:+- フォーカス済みデバッグコマンド:diff --git a/docs/ja/skills/index.md b/docs/ja/skills/index.mdnew file mode 100644index 0000000..51283ee--- /dev/null+++ b/docs/ja/skills/index.md@@ -0,0 +1,49 @@+# スキル++このディレクトリには、このコースに同梱されている AI エージェント用スキルが含まれています。スキルは、Claude Code、Codex、Cursor、Windsurf などの AI コーディングエージェントが読み込んで専門的な作業を行うための、自己完結したプロンプトテンプレートです。++## harness-creator++AI コーディングエージェント向けの本番級 harness engineering スキルです。指示、状態、検証、スコープ、セッションライフサイクルという 5 つの中核サブシステムを作成、評価、改善するのを助けます。++### できること++- **harness をゼロから作る** — AGENTS.md、機能リスト、検証ワークフロー+- **既存の harness を改善する** — 5 サブシステム評価と優先度付き改善案+- **セッション継続性を設計する** — メモリ永続化、進捗追跡、引き継ぎ手順+- **本番パターンを適用する** — メモリ、コンテキストエンジニアリング、ツール安全性、マルチエージェント協調++### クイックスタート++スキルファイルはリポジトリの [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator) にあります。++Claude Code で使う場合は、`harness-creator/` ディレクトリをプロジェクトのスキルパスにコピーするか、エージェントに SKILL.md を直接読ませます。++### 参考パターン++このスキルには 6 つの詳細リファレンスがあります。++| パターン | 使う場面 |+|---------|----------|+| Memory Persistence | エージェントがセッション間で忘れてしまう |+| Context Engineering | コンテキスト予算管理、必要時ロード |+| Tool Registry | ツール安全性、並行制御 |+| Multi-Agent Coordination | 並列化、専門化ワークフロー |+| Lifecycle & Bootstrap | フック、バックグラウンドタスク、初期化 |+| Gotchas | 見落としやすい 15 個の失敗モードと修正策 |++### テンプレート++このスキルには、すぐ使えるテンプレートが同梱されています。++- `agents.md` — 作業ルール付き AGENTS.md 雛形+- `feature-list.json` — JSON Schema と機能リスト例+- `init.sh` — 標準初期化スクリプト+- `progress.md` — セッション進捗ログテンプレート++### このスキルの作り方++`harness-creator` は **skill-creator** 方法論で開発されています。これは Anthropic 公式のメタスキルで、エージェントスキルの作成、テスト、反復改善に使います。skill-creator は、評価ランナー、採点器、ベンチマークビューアを備えた、ドラフト → テスト → 評価 → 反復の構造化ワークフローを提供します。++- **skill-creator ソース**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)+- **Claude Code skills docs**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..311e665--- /dev/null+++ b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,170 @@+/**+ * failure-pattern-demo.ts+ *+ * Simulates the 4-step failure pattern that capable agents fall into:+ * 1. Incomplete context+ * 2. Locally reasonable changes+ * 3. No global verification+ * 4. Premature completion+ *+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// Simulated "model" -- a simple decision function that bases its output+// solely on whatever context it has been given.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // The task is to "add a search endpoint to the API".+ // Correct answer requires knowing about auth middleware and rate limiting.++ if (!has("auth")) {+ return "Created new route handler /search without authentication checks";+ }+ if (!has("rate-limit")) {+ return "Added search route with auth but forgot rate limiting";+ }+ if (!has("test-standards")) {+ return "Implemented search with auth and rate-limit, but no tests";+ }+ return "Fully implemented search endpoint with auth, rate-limit, and tests";+}++// ---------------------------------------------------------------------------+// Failure simulation+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Step 1: Incomplete Context ----+ const step1Context = ["project structure", "route definitions"];+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];+ const step1Decision = modelDecide(step1Context, "add search endpoint");++ steps.push({+ step: 1,+ name: "Incomplete Context",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Looks good -- route compiles, returns data",+ globalImpact: "Missing auth means unauthenticated access to search",+ completed: false,+ });++ // ---- Step 2: Locally Reasonable Changes ----+ // The agent adds auth after a hint, but still lacks other context.+ const step2Context = [...step1Context, "auth middleware"];+ const step2Missing = ["rate-limiting policy", "test standards"];+ const step2Decision = modelDecide(step2Context, "add search endpoint");++ steps.push({+ step: 2,+ name: "Locally Reasonable Changes",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "Route has auth -- looks complete locally",+ globalImpact: "No rate limiting means the endpoint can be abused",+ completed: false,+ });++ // ---- Step 3: No Global Verification ----+ const step3Context = [...step2Context, "rate-limiting policy"];+ const step3Missing = ["test standards"];+ const step3Decision = modelDecide(step3Context, "add search endpoint");++ steps.push({+ step: 3,+ name: "No Global Verification",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "Feature appears fully implemented",+ globalImpact: "No tests -- regression risk, violates project standards",+ completed: false,+ });++ // ---- Step 4: Premature Completion ----+ steps.push({+ step: 4,+ name: "Premature Completion",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',+ localOutcome: "Agent is satisfied, task marked complete",+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Comparison table+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Step ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);+ console.log(` Action taken : ${s.actionTaken}`);+ console.log(` Local outcome : ${s.localOutcome}`);+ console.log(` Global impact : ${s.globalImpact}`);+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);+ }++ // Summary comparison+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");+ console.log("=".repeat(90));++ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];+ const finalAvailable = steps[steps.length - 1].contextAvailable;++ const header = "| Criterion | Available | Missing | Status |";+ const sep = "|------------------------|-----------|---------|----------|";+ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;+ console.log(row);+ }++ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());diff --git a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.tsnew file mode 100644index 0000000..d856ba3--- /dev/null+++ b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts@@ -0,0 +1,180 @@+/**+ * harness-vs-no-harness.ts+ *+ * Side-by-side comparison of the same task executor running with and without+ * a harness. The harness version adds explicit rules, verification steps,+ * and stop conditions.+ *+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts+ */++// ---------------------------------------------------------------------------+// Types & helpers+// ---------------------------------------------------------------------------++interface TaskResult {+ name: string;+ passed: boolean;+ durationMs: number;+ issues: string[];+}++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++// ---------------------------------------------------------------------------+// Simulated task executor+// ---------------------------------------------------------------------------++/** A simple task that can succeed or fail depending on rules. */+type Task = {+ name: string;+ requiresAuth: boolean;+ hasTests: boolean;+ withinScope: boolean;+};++const tasks: Task[] = [+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },+];++// ---------------------------------------------------------------------------+// Run WITHOUT harness -- just execute every task, no checks+// ---------------------------------------------------------------------------++function runWithoutHarness(taskList: Task[]): TaskResult[] {+ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];++ // The "agent" does the work and calls it done.+ let passed = true;++ // Problems that go undetected without a harness+ if (t.requiresAuth && !t.hasTests) {+ issues.push("No tests for auth-protected endpoint");+ // Agent doesn't notice -- marks as pass anyway+ }+ if (!t.withinScope) {+ issues.push("Task is outside current scope");+ // Agent doesn't notice+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Run WITH harness -- rules, verification, stop conditions+// ---------------------------------------------------------------------------++function runWithHarness(taskList: Task[]): TaskResult[] {+ const rules = {+ requireTestsForAuth: true,+ enforceScope: true,+ };++ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];+ let passed = true;++ // Rule: auth endpoints must have tests+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {+ issues.push("BLOCKED: Auth-protected endpoint missing tests");+ passed = false;+ }++ // Rule: stay in scope+ if (rules.enforceScope && !t.withinScope) {+ issues.push("BLOCKED: Task outside active scope -- skipped");+ passed = false;+ }++ // Verification: re-check after execution+ if (passed && !t.hasTests) {+ issues.push("WARNING: No tests exist for this change");+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function printComparison(+ noHarness: TaskResult[],+ withHarness: TaskResult[]+): void {+ console.log("\n" + "=".repeat(80));+ console.log(" HARNESS vs NO-HARNESS COMPARISON");+ console.log("=".repeat(80));++ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;++ console.log("\n" + header);+ console.log(sep);++ for (let i = 0; i < noHarness.length; i++) {+ const nh = noHarness[i];+ const wh = withHarness[i];+ const nhPass = nh.passed ? "PASS" : "FAIL";+ const whPass = wh.passed ? "PASS" : "FAIL";+ const nhIssue = nh.issues[0] ?? "(none)";+ const whIssue = wh.issues[0] ?? "(none)";++ console.log(+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`+ );+ }++ // Metrics+ const nhPassed = noHarness.filter((r) => r.passed).length;+ const whPassed = withHarness.filter((r) => r.passed).length;+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);++ console.log("\n" + "=".repeat(80));+ console.log(" SUMMARY METRICS");+ console.log("=".repeat(80));++ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log("\n" + metricsHeader);+ console.log(metricsSep);+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);++ console.log("\n The harness catches problems the no-harness run silently ignores.");+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");+}++/** Count tasks that actually pass (have tests and are in scope). */+function truePassCount(results: TaskResult[]): number {+ return results.filter((r) => r.passed && r.issues.length === 0).length;+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparison(runWithoutHarness(tasks), runWithHarness(tasks));diff --git a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.tsnew file mode 100644index 0000000..e56cddd--- /dev/null+++ b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts@@ -0,0 +1,36 @@+type Message = {+ role: "user" | "assistant";+ content: string;+};++type ToolResult = {+ ok: boolean;+ output: string;+};++function runTool(name: string, input: string): ToolResult {+ if (name === "read_file") {+ return { ok: true, output: `contents of ${input}` };+ }++ return { ok: false, output: `unknown tool: ${name}` };+}++export function minimalHarness(messages: Message[]) {+ const nextAction = {+ tool: "read_file",+ input: "README.md"+ };++ const result = runTool(nextAction.tool, nextAction.input);++ return {+ messages: [+ ...messages,+ {+ role: "assistant",+ content: `Tool ${nextAction.tool} returned: ${result.output}`+ }+ ]+ };+}diff --git a/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txtnew file mode 100644index 0000000..45315da--- /dev/null+++ b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt@@ -0,0 +1,13 @@+AGENTS.md+docs/+ ARCHITECTURE.md+ PRODUCT.md+ RELIABILITY.md+ references/+ electron.md+ sqlite.md+ plans/+ active/+ completed/+src/+scripts/diff --git a/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.tsnew file mode 100644index 0000000..46f6a62--- /dev/null+++ b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts@@ -0,0 +1,189 @@+/**+ * repo-reader.ts+ *+ * Reads a directory structure and scores it on discoverability.+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,+ * handoff files, and other signals of a repository that serves as the+ * system of record.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]+ * (defaults to current working directory if no path given)+ *+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Scoring criteria+// ---------------------------------------------------------------------------++interface Check {+ name: string;+ description: string;+ maxPoints: number;+ check: (dir: string) => { points: number; found: string[]; missing: string[] };+}++const checks: Check[] = [+ {+ name: "AGENTS.md / CLAUDE.md",+ description: "Agent-readable instruction file at repo root",+ maxPoints: 15,+ check: (dir) => {+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };+ },+ },+ {+ name: "Documentation directory",+ description: "Dedicated docs/ or documentation/ directory",+ maxPoints: 10,+ check: (dir) => {+ const candidates = ["docs", "documentation", "doc"];+ const found = candidates.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };+ },+ },+ {+ name: "Architecture documentation",+ description: "Files describing system architecture",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",+ "docs/architecture/", "design.md", "DESIGN.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };+ },+ },+ {+ name: "Feature tracking",+ description: "Feature list or task tracking file",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "feature_list.json", "features.md", "FEATURES.md",+ "docs/features.md", "tasks.json", "TODO.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };+ },+ },+ {+ name: "Handoff / session continuity",+ description: "Files for multi-session continuity",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",+ "docs/handoff.md", ".handoff", "PROGRESS.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };+ },+ },+ {+ name: "Testing structure",+ description: "Test directory or test configuration",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["test", "tests", "__tests__", "spec"];+ const found = patterns.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };+ },+ },+ {+ name: "Configuration files",+ description: "Project config (package.json, tsconfig, etc.)",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };+ },+ },+ {+ name: "README",+ description: "Root README file",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["README.md", "README.rst", "README.txt", "README"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };+ },+ },+];++// ---------------------------------------------------------------------------+// Report generation+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function scoreRepo(targetDir: string): void {+ const resolved = path.resolve(targetDir);++ if (!fs.existsSync(resolved)) {+ console.error(` Error: Directory not found: ${resolved}`);+ process.exit(1);+ }++ console.log("\n" + "=".repeat(80));+ console.log(" REPOSITORY DISCOVERABILITY SCORE");+ console.log("=".repeat(80));+ console.log(` Target: ${resolved}\n`);++ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ let totalScore = 0;+ let maxScore = 0;++ for (const check of checks) {+ const result = check.check(resolved);+ totalScore += result.points;+ maxScore += check.maxPoints;+ const status = result.points > 0 ? "PASS" : "FAIL";+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];++ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);+ }++ // Final score+ console.log("\n" + "-".repeat(80));+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);++ // Grade+ const pct = totalScore / maxScore;+ let grade: string;+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";+ else grade = "F -- Repository lacks discoverability signals";++ console.log(` GRADE: ${grade}`);+ console.log("=".repeat(80) + "\n");+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const target = process.argv[2] || process.cwd();+scoreRepo(target);diff --git a/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.tsnew file mode 100644index 0000000..59a9632--- /dev/null+++ b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts@@ -0,0 +1,209 @@+/**+ * split-vs-monolithic.ts+ *+ * Creates a monolithic instruction file (~200 lines) and then shows how+ * splitting into 4 focused files dramatically reduces the context needed+ * for any single query. Simulates an "agent" searching for a specific rule+ * and measures how many lines it must read in each approach.+ *+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts+ */++// ---------------------------------------------------------------------------+// Simulated monolithic instruction file (200 lines of rules)+// ---------------------------------------------------------------------------++const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];++// Section 1: Project Overview (lines 1-50)+for (let i = 1; i <= 50; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Project Overview",+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,+ });+}++// Section 2: Code Style Rules (lines 51-100)+for (let i = 51; i <= 100; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Code Style",+ content:+ i === 72+ ? "RULE: Always use explicit return types on exported functions."+ : i === 78+ ? "RULE: Use const assertions for immutable arrays."+ : `Style rule detail line ${i}`,+ });+}++// Section 3: Testing Standards (lines 101-150)+for (let i = 101; i <= 150; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Testing",+ content:+ i === 120+ ? "RULE: Every new endpoint must have integration tests."+ : i === 135+ ? "RULE: Test files must mirror the source file structure."+ : `Testing detail line ${i}`,+ });+}++// Section 4: Deployment Rules (lines 151-200)+for (let i = 151; i <= 200; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Deployment",+ content:+ i === 175+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."+ : `Deployment detail line ${i}`,+ });+}++// ---------------------------------------------------------------------------+// Split instruction files (4 focused files)+// ---------------------------------------------------------------------------++const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),+};++// ---------------------------------------------------------------------------+// Simulated queries -- the agent needs to find specific rules+// ---------------------------------------------------------------------------++interface Query {+ description: string;+ targetRule: string;+ relevantSection: string;+}++const queries: Query[] = [+ {+ description: "Find the rule about return types",+ targetRule: "explicit return types",+ relevantSection: "Code Style",+ },+ {+ description: "Find the deployment window rule",+ targetRule: "deploy on Fridays",+ relevantSection: "Deployment",+ },+ {+ description: "Find the integration test rule",+ targetRule: "integration tests",+ relevantSection: "Testing",+ },+ {+ description: "Find the test file structure rule",+ targetRule: "mirror the source file",+ relevantSection: "Testing",+ },+];++// ---------------------------------------------------------------------------+// Search simulation+// ---------------------------------------------------------------------------++function searchMonolithic(query: Query): { linesRead: number; found: boolean } {+ // Agent must scan from the top, reading each line until it finds the rule.+ // In the worst case it reads all lines.+ let linesRead = 0;+ let found = false;++ for (const line of monolithicInstructions) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found };+}++function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {+ // Agent knows which file to look in based on the section.+ // It only reads lines from that one file.+ const fileMap: Record<string, string> = {+ "Project Overview": "01-project-overview.md",+ "Code Style": "02-code-style.md",+ Testing: "03-testing.md",+ Deployment: "04-deployment.md",+ };++ const targetFile = fileMap[query.relevantSection];+ const lines = splitInstructions[targetFile];+ let linesRead = 0;+ let found = false;++ for (const line of lines) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found, fileAccessed: targetFile };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");+ console.log("=".repeat(90));++ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");++ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;+ console.log(header);+ console.log(sep);++ let totalMono = 0;+ let totalSplit = 0;++ for (const q of queries) {+ const mono = searchMonolithic(q);+ const split = searchSplit(q);+ totalMono += mono.linesRead;+ totalSplit += split.linesRead;++ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);+ console.log(+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`+ );+ }++ console.log(sep);+ const avgMono = Math.round(totalMono / queries.length);+ const avgSplit = Math.round(totalSplit / queries.length);+ console.log(+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`+ );++ console.log("\n" + "=".repeat(90));+ console.log(" KEY INSIGHT");+ console.log("=".repeat(90));+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");+}++run();diff --git a/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.tsnew file mode 100644index 0000000..69f9c3e--- /dev/null+++ b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts@@ -0,0 +1,162 @@+/**+ * session-simulator.ts+ *+ * Simulates two sessions working on a multi-step task.+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.+ * Run 2: With handoff file -- Session B picks up where Session A left off.+ *+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface TaskStep {+ id: number;+ name: string;+ durationMs: number;+}++interface SessionResult {+ session: string;+ stepsCompleted: number;+ totalDurationMs: number;+ duplicatedSteps: number;+ output: string[];+}++// ---------------------------------------------------------------------------+// Task definition+// ---------------------------------------------------------------------------++const taskSteps: TaskStep[] = [+ { id: 1, name: "Read project structure", durationMs: 50 },+ { id: 2, name: "Understand existing auth module", durationMs: 80 },+ { id: 3, name: "Design new search endpoint", durationMs: 60 },+ { id: 4, name: "Implement search endpoint", durationMs: 100 },+ { id: 5, name: "Write integration tests", durationMs: 70 },+ { id: 6, name: "Update documentation", durationMs: 40 },+];++// ---------------------------------------------------------------------------+// Simulated session executor+// ---------------------------------------------------------------------------++/** Simulate a session doing work. */+function runSession(+ sessionName: string,+ startStep: number,+ endStep: number+): SessionResult {+ const output: string[] = [];+ let totalDuration = 0;++ for (let i = startStep; i <= endStep; i++) {+ const step = taskSteps.find((s) => s.id === i)!;+ totalDuration += step.durationMs;+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);+ }++ return {+ session: sessionName,+ stepsCompleted: endStep - startStep + 1,+ totalDurationMs: totalDuration,+ duplicatedSteps: 0,+ output,+ };+}++// ---------------------------------------------------------------------------+// Run 1: No handoff file+// ---------------------------------------------------------------------------++function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 before timing out+ const sessionA = runSession("Session A", 1, 3);++ // Session B has no context, starts from scratch+ const sessionB = runSession("Session B", 1, 6);+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Run 2: With handoff file+// ---------------------------------------------------------------------------++function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 and writes a handoff file+ const sessionA = runSession("Session A", 1, 3);++ // Session B reads handoff, starts from step 4+ const sessionB = runSession("Session B", 4, 6);+ sessionB.duplicatedSteps = 0;++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {+ console.log("\n" + "=".repeat(80));+ console.log(` ${title}`);+ console.log("=".repeat(80));++ console.log("\n Session A output:");+ for (const line of result.sessionA.output) {+ console.log(line);+ }++ console.log("\n Session B output:");+ for (const line of result.sessionB.output) {+ console.log(line);+ }++ console.log("\n Session B notes:");+ if (result.sessionB.duplicatedSteps > 0) {+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);+ } else {+ console.log(" - Read handoff file, continued from step 4");+ console.log(" - No duplicate work performed");+ }+}++function printComparison(): void {+ const noHandoff = simulateNoHandoff();+ const withHandoff = simulateWithHandoff();++ printRun("RUN 1: NO HANDOFF FILE", noHandoff);+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);++ // Comparison table+ console.log("\n" + "=".repeat(80));+ console.log(" COMPARISON TABLE");+ console.log("=".repeat(80) + "\n");++ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log(header);+ console.log(sep);++ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;++ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);++ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");+}++printComparison();diff --git a/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.tsnew file mode 100644index 0000000..52dcd98--- /dev/null+++ b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts@@ -0,0 +1,296 @@+/**+ * init-check.ts+ *+ * Programmatically checks initialization prerequisites:+ * - Node.js version+ * - Dependencies installed (node_modules exists)+ * - Data directory exists+ * - Config files present+ *+ * Simulates running with and without an explicit init phase,+ * showing how missing prerequisites cause silent failures later.+ *+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";+import * as childProcess from "node:child_process";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface CheckItem {+ name: string;+ category: string;+ check: () => { pass: boolean; detail: string };+ impactIfMissing: string;+}++interface CheckResult {+ name: string;+ category: string;+ passed: boolean;+ detail: string;+ impactIfMissing: string;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++function createChecks(targetDir: string): CheckItem[] {+ return [+ {+ name: "Node.js version >= 18",+ category: "Runtime",+ check: () => {+ try {+ const version = process.version; // e.g. "v20.11.0"+ const major = parseInt(version.replace("v", "").split(".")[0], 10);+ return {+ pass: major >= 18,+ detail: `Detected: ${version} (need >= v18)`,+ };+ } catch {+ return { pass: false, detail: "Could not detect Node.js version" };+ }+ },+ impactIfMissing: "TypeScript features and built-in APIs unavailable",+ },+ {+ name: "package.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "package.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found in target directory",+ };+ },+ impactIfMissing: "Cannot install dependencies or run scripts",+ },+ {+ name: "Dependencies installed (node_modules)",+ category: "Dependencies",+ check: () => {+ const p = path.join(targetDir, "node_modules");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",+ };+ },+ impactIfMissing: "All imports fail at runtime",+ },+ {+ name: "TypeScript available",+ category: "Toolchain",+ check: () => {+ try {+ const result = childProcess.execSync("npx tsc --version", {+ encoding: "utf-8",+ timeout: 10000,+ stdio: ["pipe", "pipe", "pipe"],+ }).trim();+ return { pass: true, detail: `Detected: ${result}` };+ } catch {+ return { pass: false, detail: "TypeScript not available via npx" };+ }+ },+ impactIfMissing: "Cannot compile TypeScript files",+ },+ {+ name: "tsconfig.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "tsconfig.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found",+ };+ },+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",+ },+ {+ name: "Source directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["src", "lib", "app"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",+ };+ },+ impactIfMissing: "Agent cannot locate source files to modify",+ },+ {+ name: "Test directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["test", "tests", "__tests__", "spec"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",+ };+ },+ impactIfMissing: "Agent cannot find or run existing tests",+ },+ {+ name: "Git repository initialized",+ category: "Version Control",+ check: () => {+ const gitDir = path.join(targetDir, ".git");+ const exists = fs.existsSync(gitDir);+ return {+ pass: exists,+ detail: exists ? "Git repository detected" : "No .git directory found",+ };+ },+ impactIfMissing: "No rollback capability, no change history",+ },+ ];+}++// ---------------------------------------------------------------------------+// Simulation: with and without init phase+// ---------------------------------------------------------------------------++interface SimResult {+ scenario: string;+ checksRun: boolean;+ failuresBeforeWork: number;+ workAttempted: boolean;+ workSucceeded: boolean;+ timeWastedMs: number;+}++function simulateWithoutInit(): SimResult {+ // Agent skips init, goes straight to work.+ // Encounters failures one at a time as it hits missing prerequisites.+ const checks = createChecks(process.cwd());+ let failures = 0;+ let timeWasted = 0;++ for (const check of checks) {+ const result = check.check();+ if (!result.pass) {+ failures++;+ timeWasted += 200; // Agent spends time discovering each missing piece+ }+ }++ return {+ scenario: "NO INIT PHASE",+ checksRun: false,+ failuresBeforeWork: 0, // Didn't check upfront+ workAttempted: true,+ workSucceeded: failures === 0,+ timeWastedMs: timeWasted,+ };+}++function simulateWithInit(): SimResult {+ // Agent runs init phase first, discovers all issues upfront.+ const checks = createChecks(process.cwd());+ let failures = 0;++ for (const check of checks) {+ if (!check.check().pass) {+ failures++;+ }+ }++ return {+ scenario: "WITH INIT PHASE",+ checksRun: true,+ failuresBeforeWork: failures,+ workAttempted: failures === 0,+ workSucceeded: failures === 0,+ timeWastedMs: 0,+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.cwd();+ console.log("\n" + "=".repeat(80));+ console.log(" INITIALIZATION PREREQUISITE CHECK");+ console.log("=".repeat(80));+ console.log(` Target: ${targetDir}\n`);++ const checks = createChecks(targetDir);+ const results: CheckResult[] = checks.map((c) => {+ const r = c.check();+ return {+ name: c.name,+ category: c.category,+ passed: r.pass,+ detail: r.detail,+ impactIfMissing: c.impactIfMissing,+ };+ });++ // Detailed report+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const status = r.passed ? "PASS" : "FAIL";+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);+ }++ const passCount = results.filter((r) => r.passed).length;+ const failCount = results.filter((r) => !r.passed).length;++ console.log("\n" + "-".repeat(80));+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);++ if (failCount > 0) {+ console.log("\n FAILED CHECKS -- Impact if not resolved:");+ for (const r of results.filter((r) => !r.passed)) {+ console.log(` - ${r.name}: ${r.impactIfMissing}`);+ }+ }++ // Comparison: with vs without init+ const noInit = simulateWithoutInit();+ const withInit = simulateWithInit();++ console.log("\n" + "=".repeat(80));+ console.log(" INIT PHASE COMPARISON");+ console.log("=".repeat(80) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);++ console.log("\n An explicit init phase catches problems before they waste time.\n");+}++run();diff --git a/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.shnew file mode 100644index 0000000..2c6e1b0--- /dev/null+++ b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh@@ -0,0 +1,10 @@+#!/usr/bin/env bash+set -euo pipefail++echo "[init] installing dependencies"+npm install++echo "[init] starting the docs site is optional"+echo "[init] use npm run docs:dev for course docs"++echo "[init] project-specific startup would go here"diff --git a/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.tsnew file mode 100644index 0000000..c587a1d--- /dev/null+++ b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts@@ -0,0 +1,151 @@+/**+ * scope-tracker.ts+ *+ * Reads a feature list and a change log. Enforces single-active-feature+ * policy. Given a log of changes, flags any changes outside the active+ * feature scope. Demonstrates how scope drift happens and how the tracker+ * catches it.+ *+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Feature {+ id: string;+ name: string;+ status: "active" | "pending" | "done";+}++interface ChangeLogEntry {+ step: number;+ file: string;+ description: string;+ featureId: string; // The feature this change claims to belong to+}++// ---------------------------------------------------------------------------+// Sample data+// ---------------------------------------------------------------------------++const features: Feature[] = [+ { id: "F-001", name: "Search endpoint", status: "active" },+ { id: "F-002", name: "Delete endpoint", status: "pending" },+ { id: "F-003", name: "Rate limiting", status: "pending" },+ { id: "F-004", name: "User dashboard", status: "pending" },+];++// A realistic change log where the agent gradually drifts from the active feature+const changeLog: ChangeLogEntry[] = [+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },+];++// ---------------------------------------------------------------------------+// Scope tracker+// ---------------------------------------------------------------------------++interface ScopeCheckResult {+ step: number;+ file: string;+ description: string;+ featureId: string;+ inScope: boolean;+ activeFeature: string;+}++function trackScope(+ featureList: Feature[],+ changes: ChangeLogEntry[]+): ScopeCheckResult[] {+ const activeFeatures = featureList.filter((f) => f.status === "active");+ const activeIds = new Set(activeFeatures.map((f) => f.id));+ const activeNames = activeFeatures.map((f) => f.name).join(", ");++ return changes.map((change) => ({+ step: change.step,+ file: change.file,+ description: change.description,+ featureId: change.featureId,+ inScope: activeIds.has(change.featureId),+ activeFeature: activeNames,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const results = trackScope(features, changeLog);++ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");+ console.log("=".repeat(100));++ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));++ // Detailed change log+ console.log("\n" + "-".repeat(100));+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;+ console.log(header);+ console.log(sep);++ let inScopeCount = 0;+ let driftCount = 0;++ for (const r of results) {+ const scopeLabel = r.inScope ? "OK" : "DRIFT";+ if (r.inScope) inScopeCount++;+ else driftCount++;++ const marker = r.inScope ? " " : ">>";+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE DRIFT SUMMARY");+ console.log("=".repeat(100) + "\n");++ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;+ console.log(sHeader);+ console.log(sSep);+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);++ // Drift detail+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];+ if (driftFeatures.length > 0) {+ console.log("\n DRIFTED FEATURES:");+ for (const fid of driftFeatures) {+ const feat = features.find((f) => f.id === fid);+ const driftChanges = results.filter((r) => r.featureId === fid);+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);+ }+ }++ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");+}++run();diff --git a/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..52d6a2b--- /dev/null+++ b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,218 @@+/**+ * feature-list-validator.ts+ *+ * Reads a feature_list.json, validates its schema, and checks for features+ * marked "pass" without verification evidence. Outputs a structured report.+ * Can run against any project directory that has a feature_list.json.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]+ * (defaults to the directory containing this script)+ *+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Allow unknown fields for flexibility+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Schema validation+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entry ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Missing or invalid 'id' field`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Missing or invalid 'category' field`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Missing or invalid 'description' field`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' must be an array if present`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' must be a boolean if present`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Evidence validation+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Process feature list+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve target directory+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);+ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" FEATURE LIST VALIDATOR");+ console.log("=".repeat(90));+ console.log(` Reading: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(` ERROR: feature_list.json not found at ${filePath}`);+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");+ process.exit(1);+ }++ let entries: FeatureEntry[];+ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");+ process.exit(1);+ }++ // For demo purposes, also validate an extended test set+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "User can import a PDF document.",+ verification: ["Upload a PDF file", "Verify it appears in the document list"],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "System hallucination rate is below 5%.",+ verification: [], // Empty -- no evidence+ passes: true, // Marked as pass WITHOUT evidence+ },+ {+ id: "missing-fields",+ // Missing 'category' and 'description'+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Print report+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";+ const notes = r.markedPassWithoutEvidence+ ? "FLAGGED: passes without evidence!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";+ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`+ );+ }++ // Summary+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;+ const withEvidence = results.filter((r) => r.hasVerification).length;++ console.log("\n" + "-".repeat(90));+ console.log(" SUMMARY");+ console.log("-".repeat(90));+ console.log(` Total features: ${total}`);+ console.log(` Schema valid: ${schemaOk}/${total}`);+ console.log(` Marked as passing: ${passing}/${total}`);+ console.log(` With verification evidence: ${withEvidence}/${total}`);+ console.log(` Flagged (pass without evidence): ${flagged}`);++ if (flagged > 0) {+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);+ console.log(" These features need verification before they can be trusted.\n");+ } else {+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");+ }+}++run();diff --git a/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..8b973e3--- /dev/null+++ b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",+ "verification": [+ "Import a markdown document",+ "Open the Q&A panel",+ "Ask a question about known content",+ "Verify the answer is returned",+ "Verify one or more citations are displayed"+ ],+ "passes": false+ }+]diff --git a/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.tsnew file mode 100644index 0000000..fad1a3b--- /dev/null+++ b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts@@ -0,0 +1,241 @@+/**+ * victory-detector.ts+ *+ * Simulates an agent that claims task completion, then checks the claimed+ * state against actual verification. Outputs: claimed vs actual, highlighting+ * gaps between what the agent said and what's really true.+ *+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Task {+ name: string;+ claimedComplete: boolean;+ checks: VerificationCheck[];+}++interface VerificationCheck {+ description: string;+ claimed: boolean; // What the agent says+ actual: boolean; // What is actually true+ severity: "critical" | "warning";+}++// ---------------------------------------------------------------------------+// Simulated tasks with claimed vs actual states+// ---------------------------------------------------------------------------++const tasks: Task[] = [+ {+ name: "Add search endpoint",+ claimedComplete: true,+ checks: [+ {+ description: "Route handler exists",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Authentication middleware applied",+ claimed: true,+ actual: false, // Agent forgot auth+ severity: "critical",+ },+ {+ description: "Input validation added",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Unit tests written",+ claimed: true,+ actual: false, // Agent skipped tests+ severity: "critical",+ },+ {+ description: "Integration tests pass",+ claimed: true,+ actual: false, // No tests to run+ severity: "critical",+ },+ {+ description: "Documentation updated",+ claimed: true,+ actual: false, // Agent skipped docs+ severity: "warning",+ },+ ],+ },+ {+ name: "Fix pagination bug",+ claimedComplete: true,+ checks: [+ {+ description: "Bug reproduction case confirmed",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Root cause identified",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Fix applied",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Edge cases tested",+ claimed: true,+ actual: false, // Only happy path tested+ severity: "warning",+ },+ {+ description: "Regression tests added",+ claimed: true,+ actual: false,+ severity: "critical",+ },+ ],+ },+ {+ name: "Refactor auth module",+ claimedComplete: true,+ checks: [+ {+ description: "Old code removed",+ claimed: true,+ actual: false, // Old code still present+ severity: "warning",+ },+ {+ description: "All existing tests still pass",+ claimed: true,+ actual: false, // Two tests broke+ severity: "critical",+ },+ {+ description: "New auth flow works",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Migration guide written",+ claimed: true,+ actual: false,+ severity: "warning",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Verification+// ---------------------------------------------------------------------------++interface TaskVerification {+ taskName: string;+ claimedComplete: boolean;+ actuallyComplete: boolean;+ totalChecks: number;+ claimedPassing: number;+ actualPassing: number;+ gaps: { description: string; severity: string }[];+}++function verifyTask(task: Task): TaskVerification {+ const claimedPassing = task.checks.filter((c) => c.claimed).length;+ const actualPassing = task.checks.filter((c) => c.actual).length;+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);++ return {+ taskName: task.name,+ claimedComplete: task.claimedComplete,+ actuallyComplete: gaps.length === 0,+ totalChecks: task.checks.length,+ claimedPassing,+ actualPassing,+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");+ console.log("=".repeat(90));++ const verifications = tasks.map(verifyTask);++ for (const v of verifications) {+ console.log("\n Task: " + v.taskName);+ console.log(" " + "-".repeat(70));+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);++ if (!v.actuallyComplete) {+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);+ }++ // Detailed checks for this task+ const task = tasks.find((t) => t.name === v.taskName)!;+ console.log("\n Check detail:");+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;+ console.log(header);+ console.log(sep);++ for (const check of task.checks) {+ const claimedLabel = check.claimed ? "PASS" : "FAIL";+ const actualLabel = check.actual ? "PASS" : "FAIL";+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";+ const marker = gapLabel ? ">>" : " ";+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);+ }+ }++ // Overall summary+ console.log("\n" + "=".repeat(90));+ console.log(" OVERALL SUMMARY");+ console.log("=".repeat(90) + "\n");++ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;+ console.log(sHeader);+ console.log(sSep);++ for (const v of verifications) {+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);+ const cLabel = v.claimedComplete ? "Done" : "Pending";+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);+ }++ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;++ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");+ console.log(" Total undetected gaps: " + totalGaps);+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");+}++run();diff --git a/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.tsnew file mode 100644index 0000000..2428416--- /dev/null+++ b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts@@ -0,0 +1,253 @@+/**+ * e2e-runner.ts+ *+ * A minimal E2E test harness. Defines test cases as user action sequences+ * (import doc -> index -> ask question -> verify citation). Simulates+ * running them and shows the difference between "unit tests pass" and+ * "full pipeline works".+ *+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface PipelineStep {+ name: string;+ unitTestPasses: boolean;+ // Simulated actual behavior in the pipeline+ actualBehavior: "works" | "fails" | "partial";+ failureReason?: string;+}++interface TestCase {+ name: string;+ steps: PipelineStep[];+}++interface TestResult {+ testCase: string;+ unitTestsPassed: number;+ unitTestsTotal: number;+ unitTestResult: "PASS" | "FAIL";+ e2eResult: "PASS" | "FAIL";+ e2eFailureStep?: string;+ e2eFailureReason?: string;+}++// ---------------------------------------------------------------------------+// Test cases -- realistic scenarios where unit tests pass but E2E fails+// ---------------------------------------------------------------------------++const testCases: TestCase[] = [+ {+ name: "Import document and ask question",+ steps: [+ {+ name: "Parse uploaded document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Store document chunks",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Index chunks for retrieval",+ unitTestPasses: true,+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions+ failureReason: "Embedding dimension mismatch between indexer and retriever",+ },+ {+ name: "Retrieve relevant chunks",+ unitTestPasses: true, // Unit test uses mock data with correct dimensions+ actualBehavior: "fails",+ failureReason: "Empty results due to dimension mismatch from previous step",+ },+ {+ name: "Generate answer with citations",+ unitTestPasses: true, // Unit test provides pre-retrieved chunks+ actualBehavior: "fails",+ failureReason: "No chunks retrieved, so answer has no citations",+ },+ ],+ },+ {+ name: "Delete document and verify removal",+ steps: [+ {+ name: "Find document by ID",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Delete document record",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Remove indexed chunks",+ unitTestPasses: true,+ actualBehavior: "fails", // Orphaned chunks remain in the index+ failureReason: "Index cleanup query timed out, chunks remain orphaned",+ },+ {+ name: "Verify document not in search results",+ unitTestPasses: true, // Unit test mocks the search+ actualBehavior: "fails",+ failureReason: "Orphaned chunks from previous step still appear in results",+ },+ ],+ },+ {+ name: "Multi-user concurrent access",+ steps: [+ {+ name: "User A imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User B imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User A queries their document",+ unitTestPasses: true,+ actualBehavior: "partial", // Cross-contamination of results+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",+ },+ {+ name: "Verify only User A's results returned",+ unitTestPasses: true,+ actualBehavior: "fails",+ failureReason: "Results include documents from other users",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Run tests+// ---------------------------------------------------------------------------++function runUnitTests(tc: TestCase): { passed: number; total: number } {+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;+ return { passed, total: tc.steps.length };+}++function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {+ // Pipeline: if any step actually fails, the whole E2E fails+ for (const step of tc.steps) {+ if (step.actualBehavior === "fails") {+ return {+ pass: false,+ failureStep: step.name,+ failureReason: step.failureReason ?? "Unknown failure",+ };+ }+ // "partial" means the step technically completes but creates problems downstream+ // We let it continue but track it+ }+ // Check if any step was "partial" (which may cause downstream issues)+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");+ if (partialSteps.length > 0) {+ // The partial steps may or may not cause overall failure+ // In our simulation, partial steps always lead to failure downstream+ // unless there's an explicit "fails" step that already caught it+ // This case means all steps were either "works" or "partial"+ return {+ pass: false,+ failureStep: partialSteps[partialSteps.length - 1].name,+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",+ };+ }++ return { pass: true };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(95));+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");+ console.log("=".repeat(95));++ const results: TestResult[] = testCases.map((tc) => {+ const unit = runUnitTests(tc);+ const e2e = runE2ETest(tc);++ return {+ testCase: tc.name,+ unitTestsPassed: unit.passed,+ unitTestsTotal: unit.total,+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",+ e2eResult: e2e.pass ? "PASS" : "FAIL",+ e2eFailureStep: e2e.failureStep,+ e2eFailureReason: e2e.failureReason,+ };+ });++ // Per-test-case detail+ for (let i = 0; i < testCases.length; i++) {+ const tc = testCases[i];+ const r = results[i];++ console.log("\n Test Case: " + tc.name);+ console.log(" " + "-".repeat(70));++ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;+ console.log(stepHeader);+ console.log(stepSep);++ for (const step of tc.steps) {+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";+ let e2eLabel: string;+ if (step.actualBehavior === "works") e2eLabel = "PASS";+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";+ else e2eLabel = "FAIL";++ const marker = step.actualBehavior !== "works" ? ">>" : " ";+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);+ }++ if (r.e2eFailureStep) {+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);+ console.log(` Reason: ${r.e2eFailureReason}`);+ }+ }++ // Summary comparison+ console.log("\n" + "=".repeat(95));+ console.log(" COMPARISON: Unit Tests vs E2E Tests");+ console.log("=".repeat(95) + "\n");++ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";++ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);+ }++ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");+}++run();diff --git a/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsnew file mode 100644index 0000000..213dc19--- /dev/null+++ b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts@@ -0,0 +1,260 @@+/**+ * runtime-logger.ts+ *+ * A structured logging module demo. Shows ad-hoc console.log output vs+ * structured JSON log output when diagnosing a failure. Includes a seeded+ * failure scenario and demonstrates how structured logs pinpoint the issue+ * faster.+ *+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StructuredLogEntry {+ timestamp: string;+ level: "info" | "warn" | "error" | "debug";+ component: string;+ action: string;+ durationMs?: number;+ input?: unknown;+ output?: unknown;+ error?: string;+ correlationId: string;+}++// ---------------------------------------------------------------------------+// Simulated pipeline with a seeded failure+// ---------------------------------------------------------------------------++const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);++// Simulated stages of a document Q&A pipeline+interface PipelineStage {+ component: string;+ action: string;+ durationMs: number;+ success: boolean;+ errorMessage?: string;+ input?: unknown;+ output?: unknown;+}++function runPipeline(): PipelineStage[] {+ return [+ {+ component: "DocumentLoader",+ action: "parse_upload",+ durationMs: 45,+ success: true,+ input: { filename: "report.pdf", size: "2.3MB" },+ output: { chunks: 47 },+ },+ {+ component: "ChunkIndexer",+ action: "embed_and_store",+ durationMs: 230,+ success: true,+ input: { chunks: 47 },+ output: { indexed: 47, embeddingDim: 1536 },+ },+ {+ component: "QueryRouter",+ action: "route_query",+ durationMs: 12,+ success: true,+ input: { query: "What is the revenue target?" },+ output: { routedTo: "RetrievalEngine" },+ },+ {+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch+ component: "RetrievalEngine",+ action: "semantic_search",+ durationMs: 180,+ success: false,+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",+ input: { query: "What is the revenue target?", topK: 5 },+ output: { results: 0 },+ },+ {+ component: "AnswerGenerator",+ action: "generate_with_citations",+ durationMs: 1500,+ success: true, // Doesn't crash, but produces a bad answer+ input: { context: [], query: "What is the revenue target?" },+ output: { answer: "I could not find relevant information.", citations: 0 },+ },+ ];+}++// ---------------------------------------------------------------------------+// Ad-hoc logging (console.log style)+// ---------------------------------------------------------------------------++function printAdHocLog(stages: PipelineStage[]): void {+ console.log("Starting document Q&A pipeline...");+ console.log("User uploaded report.pdf");++ for (const stage of stages) {+ if (stage.success) {+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);+ } else {+ console.log(`${stage.component}: something went wrong`);+ }+ }++ console.log("Pipeline finished. Answer: I could not find relevant information.");+}++// ---------------------------------------------------------------------------+// Structured logging (JSON)+// ---------------------------------------------------------------------------++function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {+ const entries: StructuredLogEntry[] = [];++ for (const stage of stages) {+ entries.push({+ timestamp: new Date().toISOString(),+ level: stage.success ? "info" : "error",+ component: stage.component,+ action: stage.action,+ durationMs: stage.durationMs,+ input: stage.input,+ output: stage.output,+ error: stage.errorMessage,+ correlationId: CORRELATION_ID,+ });+ }++ return entries;+}++// ---------------------------------------------------------------------------+// Diagnose failure from structured logs+// ---------------------------------------------------------------------------++function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {+ const diagnosis: string[] = [];++ // Find errors+ const errors = entries.filter((e) => e.level === "error");+ if (errors.length > 0) {+ diagnosis.push("ERRORS FOUND:");+ for (const err of errors) {+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);+ }+ }++ // Check for latency spikes+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);+ if (slowStages.length > 0) {+ diagnosis.push("LATENCY SPIKES:");+ for (const s of slowStages) {+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);+ }+ }++ // Check for cascading failures+ const emptyOutputs = entries.filter((e) => {+ const out = e.output as Record<string, unknown> | undefined;+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;+ });+ if (emptyOutputs.length > 0) {+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");+ for (const e of emptyOutputs) {+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);+ }+ }++ return diagnosis;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const pipeline = runPipeline();++ console.log("\n" + "=".repeat(90));+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");+ console.log("=".repeat(90));++ // --- Ad-hoc output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO A: Ad-hoc console.log output");+ console.log("-".repeat(90) + "\n");+ printAdHocLog(pipeline);+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");+ console.log(" The failure message is vague: 'something went wrong'.");+ console.log(" No dimensions, no input/output data, no correlation ID.");++ // --- Structured output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO B: Structured JSON log output");+ console.log("-".repeat(90) + "\n");++ const structuredEntries = printStructuredLog(pipeline);++ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const entry of structuredEntries) {+ const hasError = entry.error ? entry.error.slice(0, 30) : "";+ const marker = entry.level === "error" ? ">>" : " ";+ console.log(+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`+ );+ }++ // --- Diagnosis ---+ console.log("\n" + "-".repeat(90));+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");+ console.log("-".repeat(90) + "\n");++ const errors = structuredEntries.filter((e) => e.level === "error");+ for (const err of errors) {+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);+ console.log(` Error: ${err.error}`);+ console.log(` Input: ${JSON.stringify(err.input)}`);+ console.log(` Output: ${JSON.stringify(err.output)}`);+ console.log(` Correlation ID: ${err.correlationId}`);+ }++ // Downstream impact+ console.log("\n DOWNSTREAM IMPACT:");+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");+ if (answerGen) {+ const out = answerGen.output as Record<string, unknown>;+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);+ }++ // Comparison summary+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON");+ console.log("=".repeat(90) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);++ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");+}++run();diff --git a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.tsnew file mode 100644index 0000000..0388cad--- /dev/null+++ b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts@@ -0,0 +1,216 @@+/**+ * benchmark-runner.ts+ *+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),+ * "executes" each task, records timing and pass/fail, outputs a comparison+ * report showing which tasks pass and which fail.+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BenchmarkTask {+ id: string;+ name: string;+ category: string;+ passCriteria: string[];+ expectedDurationMs: number;+ // Simulated actual results+ actualDurationMs: number;+ actualPass: boolean;+ failureReason?: string;+}++interface BenchmarkResult {+ id: string;+ name: string;+ category: string;+ criteriaTotal: number;+ criteriaPassed: number;+ pass: boolean;+ expectedMs: number;+ actualMs: number;+ durationDelta: number;+ failureReason?: string;+}++// ---------------------------------------------------------------------------+// Benchmark task definitions+// ---------------------------------------------------------------------------++const benchmarkTasks: BenchmarkTask[] = [+ {+ id: "bench-001",+ name: "Import markdown document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 100,+ actualDurationMs: 95,+ actualPass: true,+ },+ {+ id: "bench-002",+ name: "Import PDF document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 200,+ actualDurationMs: 310,+ actualPass: false,+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",+ },+ {+ id: "bench-003",+ name: "Ask grounded question",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],+ expectedDurationMs: 500,+ actualDurationMs: 480,+ actualPass: true,+ },+ {+ id: "bench-004",+ name: "Ask question with no relevant docs",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],+ expectedDurationMs: 400,+ actualDurationMs: 420,+ actualPass: false,+ failureReason: "Model hallucinated a citation instead of saying 'no results'",+ },+ {+ id: "bench-005",+ name: "Delete imported document",+ category: "Document Pipeline",+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],+ expectedDurationMs: 150,+ actualDurationMs: 145,+ actualPass: true,+ },+ {+ id: "bench-006",+ name: "Concurrent user access",+ category: "Security",+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],+ expectedDurationMs: 300,+ actualDurationMs: 850,+ actualPass: false,+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",+ },+ {+ id: "bench-007",+ name: "Session continuity after restart",+ category: "Reliability",+ passCriteria: ["State persisted", "Session recovers", "No data loss"],+ expectedDurationMs: 200,+ actualDurationMs: 180,+ actualPass: true,+ },+ {+ id: "bench-008",+ name: "API rate limiting",+ category: "Security",+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],+ expectedDurationMs: 100,+ actualDurationMs: 100,+ actualPass: true,+ },+];++// ---------------------------------------------------------------------------+// Execution simulation+// ---------------------------------------------------------------------------++function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {+ return tasks.map((task) => ({+ id: task.id,+ name: task.name,+ category: task.category,+ criteriaTotal: task.passCriteria.length,+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),+ pass: task.actualPass,+ expectedMs: task.expectedDurationMs,+ actualMs: task.actualDurationMs,+ durationDelta: task.actualDurationMs - task.expectedDurationMs,+ failureReason: task.failureReason,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(100));+ console.log(" BENCHMARK RUNNER -- Task Execution Report");+ console.log("=".repeat(100));++ const results = executeBenchmark(benchmarkTasks);++ // Detailed results+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;+ console.log("\n" + header);+ console.log(sep);++ for (const r of results) {+ const passLabel = r.pass ? "PASS" : "FAIL";+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;+ const marker = r.pass ? " " : ">>";++ console.log(+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`+ );+ }++ // Failure details+ const failures = results.filter((r) => !r.pass);+ if (failures.length > 0) {+ console.log("\n" + "-".repeat(100));+ console.log(" FAILURE DETAILS");+ console.log("-".repeat(100));+ for (const f of failures) {+ console.log(`\n [${f.id}] ${f.name}`);+ console.log(` Category: ${f.category}`);+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);+ }+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SUMMARY BY CATEGORY");+ console.log("=".repeat(100) + "\n");++ const categories = [...new Set(results.map((r) => r.category))];+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;+ console.log(catHeader);+ console.log(catSep);++ for (const cat of categories) {+ const catResults = results.filter((r) => r.category === cat);+ const catPassed = catResults.filter((r) => r.pass).length;+ const catFailed = catResults.filter((r) => !r.pass).length;+ const rate = Math.round((catPassed / catResults.length) * 100);++ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);+ }++ // Overall+ const totalPassed = results.filter((r) => r.pass).length;+ const totalFailed = results.filter((r) => !r.pass).length;+ console.log("\n" + "-".repeat(100));+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);+ console.log("=".repeat(100) + "\n");+}++run();diff --git a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.tsnew file mode 100644index 0000000..6b35905--- /dev/null+++ b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts@@ -0,0 +1,336 @@+/**+ * cleanup-scanner.ts+ *+ * Scans a project directory for stale artifacts, dead code, structural+ * violations, and outputs a cleanup report. Helps enforce the "clean state+ * at end of every session" principle.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]+ * (defaults to current working directory)+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface ScanResult {+ category: string;+ check: string;+ severity: "critical" | "warning" | "info";+ found: string[];+ description: string;+}++// ---------------------------------------------------------------------------+// Scanner checks+// ---------------------------------------------------------------------------++interface ScannerCheck {+ category: string;+ name: string;+ severity: "critical" | "warning" | "info";+ description: string;+ scan: (dir: string) => string[];+}++function createChecks(): ScannerCheck[] {+ return [+ {+ category: "Stale Artifacts",+ name: "Temporary files (*.tmp, *.bak, *.swp)",+ severity: "warning",+ description: "Leftover temp files from editing or processing",+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),+ },+ {+ category: "Stale Artifacts",+ name: "Debug/log files in source",+ severity: "warning",+ description: "Log files that should not be in the source tree",+ scan: (dir) => {+ const found: string[] = [];+ const logPatterns = [".log"];+ for (const p of findFiles(dir, logPatterns)) {+ // Only flag log files in source directories+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {+ found.push(p);+ }+ }+ return found;+ },+ },+ {+ category: "Dead Code",+ name: "Unused imports (placeholder detection)",+ severity: "info",+ description: "Files that may contain unused code (heuristic scan)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app"];+ for (const srcDir of srcDirs) {+ const srcPath = path.join(dir, srcDir);+ if (fs.existsSync(srcPath)) {+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "Missing .gitignore",+ severity: "warning",+ description: "No .gitignore file found -- risk of committing build artifacts",+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],+ },+ {+ category: "Structural Violations",+ name: "Build artifacts in source",+ severity: "critical",+ description: "Compiled output (dist/, build/) mixed with source",+ scan: (dir) => {+ const found: string[] = [];+ // Check if dist/ or build/ exists inside src/+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];+ for (const d of dirs) {+ if (fs.existsSync(path.join(dir, d))) {+ found.push(d + "/");+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "node_modules in source tree",+ severity: "critical",+ description: "node_modules directory found outside root (nested dependency)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app", "test", "tests"];+ for (const srcDir of srcDirs) {+ const nmPath = path.join(dir, srcDir, "node_modules");+ if (fs.existsSync(nmPath)) {+ found.push(srcDir + "/node_modules/");+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Uncommitted changes indicator",+ severity: "info",+ description: "Checks for common artifacts of incomplete sessions",+ scan: (dir) => {+ const found: string[] = [];+ const indicators = [+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",+ "debug.ts", "test-manual.ts", "temp.ts",+ ];+ for (const f of indicators) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Empty directories",+ severity: "info",+ description: "Empty directories that may be leftover from incomplete work",+ scan: (dir) => {+ const found: string[] = [];+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];+ for (const d of commonDirs) {+ const dp = path.join(dir, d);+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {+ try {+ const contents = fs.readdirSync(dp);+ if (contents.length === 0) {+ found.push(d + "/");+ }+ } catch {+ // Skip directories we can't read+ }+ }+ }+ return found;+ },+ },+ {+ category: "Configuration",+ name: "Environment files in source",+ severity: "critical",+ description: ".env files that may contain secrets",+ scan: (dir) => {+ const found: string[] = [];+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];+ for (const f of envFiles) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ ];+}++// ---------------------------------------------------------------------------+// Helper functions+// ---------------------------------------------------------------------------++function findFiles(dir: string, extensions: string[]): string[] {+ const found: string[] = [];++ function walk(current: string, depth: number): void {+ if (depth > 4) return; // Limit recursion depth+ try {+ const entries = fs.readdirSync(current, { withFileTypes: true });+ for (const entry of entries) {+ // Skip common non-source directories+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {+ continue;+ }++ const fullPath = path.join(current, entry.name);+ const relativePath = path.relative(dir, fullPath);++ if (entry.isDirectory()) {+ walk(fullPath, depth + 1);+ } else if (entry.isFile()) {+ if (extensions.some((ext) => entry.name.endsWith(ext))) {+ found.push(relativePath);+ }+ }+ }+ } catch {+ // Skip directories we can't read+ }+ }++ walk(dir, 0);+ return found;+}++function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {+ try {+ const entries = fs.readdirSync(dir, { withFileTypes: true });+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);+ }+ continue;+ }++ const fullPath = path.join(dir, entry.name);+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {+ continue;+ }++ try {+ const content = fs.readFileSync(fullPath, "utf-8");+ const lines = content.split("\n");+ for (let i = 0; i < Math.min(lines.length, 50); i++) {+ for (const pattern of patterns) {+ if (lines[i].includes(pattern)) {+ const relative = path.relative(baseDir, fullPath);+ results.push(`${relative}:${i + 1} contains ${pattern}`);+ }+ }+ }+ } catch {+ // Skip files we can't read+ }+ }+ } catch {+ // Skip directories we can't read+ }+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");+ console.log("=".repeat(90));+ console.log(` Scanning: ${targetDir}\n`);++ const checks = createChecks();+ const results: ScanResult[] = [];++ for (const check of checks) {+ const found = check.scan(targetDir);+ results.push({+ category: check.category,+ check: check.name,+ severity: check.severity,+ found,+ description: check.description,+ });+ }++ // Report+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const count = r.found.length;+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";++ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);+ }++ // Summary+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);+ const clean = results.filter((r) => r.found.length === 0);++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SUMMARY");+ console.log("=".repeat(90) + "\n");++ console.log(` Critical issues: ${criticals.length}`);+ console.log(` Warnings: ${warnings.length}`);+ console.log(` Info items: ${infos.length}`);+ console.log(` Clean checks: ${clean.length}/${results.length}`);++ if (criticals.length > 0) {+ console.log("\n ACTION REQUIRED (Critical):");+ for (const c of criticals) {+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);+ console.log(` ${c.description}`);+ }+ }++ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);+ if (totalIssues === 0) {+ console.log("\n Project is in a clean state. No issues found.\n");+ } else {+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);+ }+}++run();diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/ko/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txtnew file mode 100644index 0000000..6f1c612--- /dev/null+++ b/docs/ko/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt@@ -0,0 +1,9 @@+Purpose: store model-friendly reference material for the design system.++Suggested contents:+- component naming rules+- spacing and typography tokens+- state variants+- accessibility expectations++Keep this file concise and refresh it when the upstream design system changes.diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/ko/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txtnew file mode 100644index 0000000..c30cc9c--- /dev/null+++ b/docs/ko/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt@@ -0,0 +1,8 @@+Purpose: store a clean agent-readable extract of the deployment or packaging+rules your repository depends on.++Suggested contents:+- build entrypoints+- runtime assumptions+- environment variable expectations+- common failure signaturesdiff --git a/docs/ko/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/ko/resources/openai-advanced/repo-template/docs/references/uv-llms.txtnew file mode 100644index 0000000..f2ceba9--- /dev/null+++ b/docs/ko/resources/openai-advanced/repo-template/docs/references/uv-llms.txt@@ -0,0 +1,8 @@+Purpose: store a compact reference for your Python package and environment+workflow when `uv` or similar tooling matters to the repo.++Suggested contents:+- install and sync commands+- lockfile policy+- virtualenv expectations+- verification commandsdiff --git a/docs/ko/resources/templates/claude-progress.md b/docs/ko/resources/templates/claude-progress.mdindex 2b824bd..7584eaa 100644--- a/docs/ko/resources/templates/claude-progress.md+++ b/docs/ko/resources/templates/claude-progress.md@@ -4,34 +4,34 @@## 현재 검증된 상태 (Current Verified State)-- Repository root:-- Standard startup path:-- Standard verification path:-- Current highest-priority unfinished feature:-- Current blocker:+- 저장소 루트 (Repository root):+- 표준 시작 경로 (Standard startup path):+- 표준 검증 경로 (Standard verification path):+- 현재 최우선 미완료 기능 (Current highest-priority unfinished feature):+- 현재 차단 요인 (Current blocker):## 세션 로그 (Session Log)-### Session 001--- Date:-- Goal:-- Completed:-- Verification run:-- Evidence captured:-- Commits:-- Files or artifacts updated:-- Known risk or unresolved issue:-- Next best step:--### Session 002--- Date:-- Goal:-- Completed:-- Verification run:-- Evidence captured:-- Commits:-- Files or artifacts updated:-- Known risk or unresolved issue:-- Next best step:+### 세션 001++- 날짜 (Date):+- 목표 (Goal):+- 완료 항목 (Completed):+- 검증 실행 (Verification run):+- 수집된 증거 (Evidence captured):+- 커밋 (Commits):+- 업데이트된 파일 또는 산출물 (Files or artifacts updated):+- 알려진 위험 또는 미해결 이슈 (Known risk or unresolved issue):+- 다음 최적 단계 (Next best step):++### 세션 002++- 날짜 (Date):+- 목표 (Goal):+- 완료 항목 (Completed):+- 검증 실행 (Verification run):+- 수집된 증거 (Evidence captured):+- 커밋 (Commits):+- 업데이트된 파일 또는 산출물 (Files or artifacts updated):+- 알려진 위험 또는 미해결 이슈 (Known risk or unresolved issue):+- 다음 최적 단계 (Next best step):diff --git a/docs/ko/resources/templates/feature_list.json b/docs/ko/resources/templates/feature_list.jsonnew file mode 100644index 0000000..138adc6--- /dev/null+++ b/docs/ko/resources/templates/feature_list.json@@ -0,0 +1,64 @@+{+ "project": "replace-with-project-name",+ "last_updated": "YYYY-MM-DD",+ "rules": {+ "single_active_feature": true,+ "passing_requires_evidence": true,+ "do_not_skip_verification": true+ },+ "status_legend": {+ "not_started": "Work has not begun.",+ "in_progress": "The feature is the current active task.",+ "blocked": "Work cannot continue until a documented blocker is resolved.",+ "passing": "Required verification has passed and evidence is recorded."+ },+ "features": [+ {+ "id": "chat-001",+ "priority": 1,+ "area": "chat",+ "title": "Create a new conversation",+ "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",+ "status": "not_started",+ "verification": [+ "Open the app.",+ "Click New Chat.",+ "Verify a new conversation appears in the sidebar.",+ "Verify the main panel shows an empty conversation state."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-002",+ "priority": 2,+ "area": "chat",+ "title": "Send a message in the current conversation",+ "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",+ "status": "not_started",+ "verification": [+ "Open an existing conversation.",+ "Type a message into the input.",+ "Submit the message.",+ "Verify the new message appears in the thread."+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-003",+ "priority": 3,+ "area": "chat",+ "title": "Persist the active conversation list",+ "user_visible_behavior": "A user sees previously created conversations after restarting the app.",+ "status": "not_started",+ "verification": [+ "Create two conversations.",+ "Restart the app.",+ "Verify both conversations still appear in the sidebar."+ ],+ "evidence": [],+ "notes": ""+ }+ ]+}diff --git a/docs/ko/resources/templates/init.sh b/docs/ko/resources/templates/init.shnew file mode 100755index 0000000..d7522d6--- /dev/null+++ b/docs/ko/resources/templates/init.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash++set -euo pipefail++ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+cd "$ROOT_DIR"++# Replace these commands with the correct commands for your repository.+INSTALL_CMD=(npm install)+VERIFY_CMD=(npm test)+START_CMD=(npm run dev)++echo "==> Working directory: $PWD"+echo "==> Syncing dependencies"+"${INSTALL_CMD[@]}"++echo "==> Running baseline verification"+"${VERIFY_CMD[@]}"++echo "==> Startup command"+printf ' %q' "${START_CMD[@]}"+printf '\n'++if [ "${RUN_START_COMMAND:-0}" = "1" ]; then+ echo "==> Starting the app"+ exec "${START_CMD[@]}"+fi++echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."diff --git a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdindex cf0ae2d..93eb602 100644--- a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md+++ b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -1,15 +1,15 @@# AGENTS.md-## Start Here+## Начните здесь (Start Here)-- Read `docs/ARCHITECTURE.md`-- Read `docs/PRODUCT.md`-- Use `npm run dev` to start the app-- Use `npm run check` before marking work complete+- Прочитайте `docs/ARCHITECTURE.md`+- Прочитайте `docs/PRODUCT.md`+- Используйте `npm run dev` для запуска приложения+- Используйте `npm run check` перед тем как пометить работу как завершённую-## Hard Rules+## Строгие правила (Hard Rules)-- Do not change Electron main/preload/renderer boundaries without reading- `docs/ARCHITECTURE.md`-- Do not mark a feature complete without verification-- Leave a clean state for the next session+- Не изменяйте границы main/preload/renderer процесса Electron без+ прочтения `docs/ARCHITECTURE.md`+- Не помечайте функцию как завершённую без проверки (verification)+- Оставляйте чистое состояние (clean state) для следующей сессииdiff --git a/docs/zh-TW/index.md b/docs/zh-TW/index.mdnew file mode 100644index 0000000..5f1a548--- /dev/null+++ b/docs/zh-TW/index.md@@ -0,0 +1,73 @@+# 歡迎來到 Learn Harness Engineering++Learn Harness Engineering 是一門專注於 AI 程式設計智慧體工程化落地的課程。本課程深入研究並總結了業界最前沿的 Harness Engineering(工具馬具/腳手架工程)理論與實踐,參考資料包括:+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)++透過系統性的環境設計、狀態管理、驗證與控制機制,本課程旨在幫助你讓 Codex 和 Claude Code 等 AI Agent 能夠真正可靠地完成真實工程任務。它透過明確的規則和邊界約束你的 AI 程式設計助手,幫助你更可靠地建構功能、修復 Bug 並自動化開發任務。++## 開始學習++選擇適合你的學習路徑。本課程分為理論講義、實戰專案和開箱即用的資源庫。++<div class="card-grid">+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">+ <h3>講義</h3>+ <p>理解為什麼強大的模型依然會失敗,掌握建構有效 Harness 的理論基礎。</p>+ </a>+ <a href="./projects/" class="card">+ <h3>專案</h3>+ <p>動手實踐,從零開始搭建一個可靠的 Agent 工作環境。</p>+ </a>+ <a href="./resources/" class="card">+ <h3>資源庫</h3>+ <p>開箱即用的範本(AGENTS.md、feature_list.json 等),可直接複製到你自己的程式碼倉庫中。</p>+ </a>+</div>++## Harness 的核心機制++Harness 的本質不是「讓模型變聰明」,而是給模型建立一套閉環的**工作系統**。你可以透過下面的簡單圖示理解它的核心運作流:++```mermaid+graph TD+ A["明確目標<br/>AGENTS.md"] --> B("初始化檢查<br/>init.sh")+ B --> C{"執行任務<br/>AI Agent"}+ C -->|遇到障礙| D["執行回饋<br/>CLI / Logs"]+ D -->|自動修復| C+ C -->|程式碼完成| E{"驗證與評審<br/>Test & QA"}+ E -->|未通過| D+ E -->|通過| F["清理與交接<br/>claude-progress.md"]++ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;++ class A,F primary;+ class B,D process;+ class C,E check;+```++## 你將學到什麼++你將在本課程中掌握以下核心概念:++<ul class="index-list">+ <li>用明確的規則和邊界<strong>約束 Agent 的行為</strong>。</li>+ <li>在跨會話的長時任務中<strong>保持上下文連續性</strong>。</li>+ <li><strong>防止 Agent 提前宣告</strong>任務完成。</li>+ <li>讓 Agent 學會透過完整的流水線測試來<strong>驗證自己的工作</strong>。</li>+ <li>讓 Agent 的執行過程<strong>可觀測、可除錯</strong>。</li>+</ul>++## 下一步++了解核心概念後,可以透過以下內容深入學習:++<ul class="index-list">+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">L01. 模型能力強,不等於執行可靠</a>:從理論開始。</li>+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">P01. 提示詞 vs 規則驅動</a>:完成你的第一個對比實戰任務。</li>+ <li><a href="./resources/templates/">繁體中文範本</a>:取得最小 Harness 範本包(AGENTS.md、feature_list.json 等),直接用於你的專案。</li>+</ul>diff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..311e665--- /dev/null+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,170 @@+/**+ * failure-pattern-demo.ts+ *+ * Simulates the 4-step failure pattern that capable agents fall into:+ * 1. Incomplete context+ * 2. Locally reasonable changes+ * 3. No global verification+ * 4. Premature completion+ *+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// Simulated "model" -- a simple decision function that bases its output+// solely on whatever context it has been given.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // The task is to "add a search endpoint to the API".+ // Correct answer requires knowing about auth middleware and rate limiting.++ if (!has("auth")) {+ return "Created new route handler /search without authentication checks";+ }+ if (!has("rate-limit")) {+ return "Added search route with auth but forgot rate limiting";+ }+ if (!has("test-standards")) {+ return "Implemented search with auth and rate-limit, but no tests";+ }+ return "Fully implemented search endpoint with auth, rate-limit, and tests";+}++// ---------------------------------------------------------------------------+// Failure simulation+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Step 1: Incomplete Context ----+ const step1Context = ["project structure", "route definitions"];+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];+ const step1Decision = modelDecide(step1Context, "add search endpoint");++ steps.push({+ step: 1,+ name: "Incomplete Context",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Looks good -- route compiles, returns data",+ globalImpact: "Missing auth means unauthenticated access to search",+ completed: false,+ });++ // ---- Step 2: Locally Reasonable Changes ----+ // The agent adds auth after a hint, but still lacks other context.+ const step2Context = [...step1Context, "auth middleware"];+ const step2Missing = ["rate-limiting policy", "test standards"];+ const step2Decision = modelDecide(step2Context, "add search endpoint");++ steps.push({+ step: 2,+ name: "Locally Reasonable Changes",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "Route has auth -- looks complete locally",+ globalImpact: "No rate limiting means the endpoint can be abused",+ completed: false,+ });++ // ---- Step 3: No Global Verification ----+ const step3Context = [...step2Context, "rate-limiting policy"];+ const step3Missing = ["test standards"];+ const step3Decision = modelDecide(step3Context, "add search endpoint");++ steps.push({+ step: 3,+ name: "No Global Verification",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "Feature appears fully implemented",+ globalImpact: "No tests -- regression risk, violates project standards",+ completed: false,+ });++ // ---- Step 4: Premature Completion ----+ steps.push({+ step: 4,+ name: "Premature Completion",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',+ localOutcome: "Agent is satisfied, task marked complete",+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Comparison table+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Step ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);+ console.log(` Action taken : ${s.actionTaken}`);+ console.log(` Local outcome : ${s.localOutcome}`);+ console.log(` Global impact : ${s.globalImpact}`);+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);+ }++ // Summary comparison+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");+ console.log("=".repeat(90));++ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];+ const finalAvailable = steps[steps.length - 1].contextAvailable;++ const header = "| Criterion | Available | Missing | Status |";+ const sep = "|------------------------|-----------|---------|----------|";+ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;+ console.log(row);+ }++ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());diff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdnew file mode 100644index 0000000..821dc19--- /dev/null+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -0,0 +1,9 @@+# 失敗訊號檢查清單++在審查一次較弱的 harness 執行結果時,請使用此清單。++- Agent 是否曾錯誤詢問或錯誤推斷應用程式的啟動方式?+- 它是否建立了與預期產品不符的目錄或抽象?+- 它是否在製作出可見的 UI 外殼後就停止了,而沒有完整的工作流程?+- 它是否留下了有助於後續執行繼續的筆記或產物?+- 一個全新的 session 能否在五分鐘內理解發生了什麼事?diff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdnew file mode 100644index 0000000..9b09c1e--- /dev/null+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -0,0 +1,7 @@+# 第 01 講的程式碼++此資料夾用於展示以下小型範例:++- 強大的模型在薄弱的環境中失敗+- 規格不足的 repo 設定+- 缺少反饋迴圈diff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdnew file mode 100644index 0000000..b488fc8--- /dev/null+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -0,0 +1,18 @@+# 規格不足的任務範例++建構一個具備 AI 問答功能的桌面知識庫應用程式。++限制條件:++- 未指定任何限制+- 未提供啟動指令+- 無資料夾結構指引+- 未定義資料模型+- 無明確的完成標準++此類提示的典型結果:++- Agent 會臨時編造架構+- 應用程式可能可以編譯,但無法穩定啟動+- UI 可能會在任何可用的匯入/查詢路徑出現之前就顯示+- Agent 通常會在外觀成功後停止diff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.mdnew file mode 100644index 0000000..14e87d8--- /dev/null+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -0,0 +1,117 @@+[English Version →](../../../en/lectures/lecture-01-why-capable-agents-still-fail/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/)+> 實戰練習:[Project 01. 只寫提示詞讓 agent 做,和定好規則再讓它做,差多少](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# 第一講. 模型能力強,不等於執行可靠++你說你也算見過世面的人了——Claude Pro 訂著,GPT-4o 的 API key 也有,SWE-bench 排行榜上的數字你比誰都清楚。有一天你終於想讓 AI agent 幫你改一個真實的項目,信心滿滿地交代下去。結果呢?加了功能但測試掛了,改了 bug 但引入了新 bug,跑了 20 分鐘然後自信滿滿地說"完成了"——你一看代碼,根本不是你要的東西。++這時候你的第一反應是什麼?"這模型不行,得換一個更貴的。"且慢。先別急著掏錢包。問題可能根本不在模型身上。++讓我們先看一組數據。截至 2025 年底,最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這還是精心挑選過的、有明確 issue 描述和測試用例的任務。換到你日常開發的場景——需求模糊、沒有現成測試、隱含的業務規則散落在各處——這個數字只會更低。++但這組數據背後藏著一個反直覺的事實。++## 同一匹馬,兩種命運++Anthropic 做過一個對照實驗。同一個 prompt("做一個 2D 復古遊戲編輯器"),同一個模型(Opus 4.5)。第一次讓它裸跑——20 分鐘,花了 $9,遊戲核心功能根本跑不起來。第二次給它配上完整的 harness(planner + generator + evaluator 三 agent 架構)——6 小時,花了 $200,遊戲可以正常遊玩。++模型沒換。Opus 4.5 還是那個 Opus 4.5。換的是馬鞍。++OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直白:Codex 在一個 harness 搭得好的倉庫裡,表現能從"不可靠"變成"可靠"。注意他們的用詞——不是"好了一點",是質變。就像一匹千裡馬,沒馬鞍你也能騎,但騎不了多遠、跑不了多快、摔下來也不稀奇。harness 就是那個馬鞍——**模型權重之外的一切工程基礎設施**。++## agent 到底卡在哪++那具體是什麼在出問題?++最常見的:你根本沒把任務說清楚。你說"加個搜索功能",agent 理解的跟你完全不一樣——搜什麼?全文本還是結構化?要不要分頁?要不要高亮?你沒說清楚,agent 就自己猜。猜對了是運氣,猜錯了你再改,改的成本比一開始說清楚還高。這就像你去飯館跟師傅說"來個魚",端上來是紅燒還是清蒸還是酸菜——全看運氣。++就算你說清了,項目裡隱含的架構約定 agent 也不知道。你們團隊統一用 SQLAlchemy 2.0 的新語法,但 agent 默認寫了 1.x 的代碼。所有 API 端點必須走 OAuth 2.0 認證,但這個規則只存在於你腦子裡和一個三個月前的 Slack 消息裡。Agent 看不到這些——它不是不想遵守,是壓根不知道有這回事。++環境也是個坑。開發環境配置不完整、依賴缺了、工具版本不對。Agent 把寶貴的上下文窗口花在了 `pip install` 失敗、Node 版本不對這些事上,而不是解決你的核心任務。就好比你讓一個木匠來幹活,結果錘子沒帶、釘子找不到、工作臺還是歪的——手藝再好也使不上勁。++更常見的:壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完代碼,自己看了看覺得沒問題,就說完成了。這就像讓學生交作業但不給答案檢查——他自己覺得自己做對了,但批改的時候一堆錯誤。Anthropic 還觀察到一個有意思的現象:當 agent 感覺上下文快滿了,它們會匆忙結束當前工作,跳過驗證步驟,選一個簡單的方案而不是最優方案。他們把這叫"上下文焦慮"——跟你考試時發現時間快到了趕緊隨便選幾個選擇題是一回事。++長任務跨會話就更慘了——上次會話的發現全丟了,每個新會話都得重新探索項目結構、理解代碼組織。缺乏持久化狀態的 agent 在超過 30 分鐘的任務中失敗率急劇上升。++## 關鍵名詞解釋++理解了上面的場景,這些概念就不再是一堆術語了:++- **能力鴻溝(Capability Gap)**:模型在基準測試上的表現和真實任務上的表現之間的巨大落差。SWE-bench Verified 上 50-60% 的通過率意味著近一半的真實 issue 解不了。+- **Harness**:模型之外的一切——指令、工具、環境、狀態管理、驗證反饋。不是模型權重的部分,全是 harness。也就是我們說的"馬鞍"。+- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。Anthropic 的對照實驗已經證明了這一點。+- **驗證缺口**:agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說"我做完了"但實際沒做完——這是最常見的失敗模式。+- **診斷循環**:執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。+- **完成定義(Definition of Done)**:一組可以用命令驗證的條件——測試通過、lint 沒報錯、類型檢查通過。沒有顯式的完成定義,agent 就會自己編一個。++## 遇到失敗,先修 harness++核心原則:**遇到失敗,先別換模型,先檢查 harness。** 如果同一個模型在類似的結構良好的任務中能成功,那優先假設是 harness 的問題。這就像汽車拋錨——你不會第一時間懷疑是發動機壞了,你會先看看是不是沒油了。++具體怎麼做:++**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問:是任務沒說清楚?是上下文不夠?是沒有驗證手段?把每次失敗歸到五層防禦(任務規範、上下文供給、執行環境、驗證反饋、狀態管理)中的某一層。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。++**給每個任務寫顯式的完成定義。** 不要說"加個搜索功能",要說:+```+完成標準:+- 新增 GET /api/search?q=xxx 端点+- 支持分页,默認 20 条+- 返回結果包含高亮片段+- 所有新程式碼通過 pytest+- 類型檢查通過(mypy --strict)+```++**創建 AGENTS.md 檔案。** 在倉庫根目錄放一個檔案,告訴 agent 這個項目的技術棧、架構約定、驗證命令。這是 harness 工程的第一步,也是投入產出比最高的一步。一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效——我不是在開玩笑。++**建立診斷循環。** 不要把失敗當作"模型又犯傻了",而是當作"harness 又暴露了一個缺陷"的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來,你的 harness 會越來越強,agent 的表現會穩定提升。就像修路——每填一個坑,下一段路就更平坦。++**量化改進。** 記個簡單的日誌:每個任務成功了沒有,失敗了是哪一層的問題。跑幾輪之後你就能看出來哪個層是瓶頸,集中火力修那個層。++## 一百萬人行代碼的實驗++OpenAI 在 2025 年做了一個激進的實驗:用 Codex 從一個空的 git 倉庫起步,構建一個完整的內部產品。五個月後,這個倉庫有大約 100 萬行代碼——應用邏輯、基礎設施、工具、文檔、內部開發工具——全部由 agent 生成。三個工程師驅動 Codex,開了大約 1,500 個 PR 併合並。平均每人每天 3.5 個 PR。++這個實驗的關鍵約束是:**人類永遠不直接寫代碼。** 這不是噱頭,而是為了逼團隊搞清楚——當工程師的主要工作不再是寫代碼,而是設計環境、表達意圖、構建反饋迴路時,到底什麼變了?++早期進展比預期慢。不是 Codex 不行,而是環境不夠完整——agent 缺少必要的工具、抽象和內部結構來推進高層次目標。工程師的工作變成了:把大目標拆成小積木(設計、編碼、審查、測試),讓 agent 去搭建,然後用這些積木解鎖更復雜的任務。當某件事失敗了,修復幾乎從來不是"更努力",而是"agent 缺什麼能力,怎麼讓它既可理解又可執行"。++這個實驗直接證明了本講的核心論點:**同一個模型,在空白環境裡和在有完整 harness 的環境裡,產出有本質差異。** 模型沒變,變的是環境。++> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++## 一個更接地氣的例子++一個團隊用 Claude Sonnet 給一箇中等規模的 Python Web 應用(FastAPI + PostgreSQL + Redis,約 15,000 行代碼)添加新的 API 端點。++起初他們只給了一句話:"在 `/api/v2/users` 下添加用戶偏好設置端點"。結果呢?agent 花了 40% 的上下文窗口探索倉庫結構,產出了看似合理的代碼但沒遵循項目的錯誤處理模式,用了舊版 SQLAlchemy 語法,宣稱完成但端點實際有運行時錯誤。下一個會話還得重新做發現工作。++後來他們加了 `AGENTS.md`(描述項目架構和技術棧版本)、顯式的驗證命令(`pytest tests/api/v2/ && python -m mypy src/`)、和架構決策記錄。同一模型在三次獨立運行中全部成功,上下文使用效率提高了約 60%。++模型沒變。變的還是 harness。++## 帶走什麼++- 模型能力和執行可靠性是兩回事。千裡馬也得配上好馬鞍。+- 失敗的時候先看 harness,再看模型。換模型是成本最高的選擇——而且很多時候根本不是模型的問題。+- 每次失敗都是一個信號:你的 harness 有結構性缺陷。把它找出來、修掉。+- 五層防禦:任務規範、上下文供給、執行環境、驗證反饋、狀態管理。逐層排查,就像醫生看病先檢查最常見的病因。+- 一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效。真的。++## 延伸閱讀++- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-bench Leaderboard](https://www.swebench.com/)+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)++## 練習++1. **對比實驗**:選一個你熟悉的代碼倉庫和一項非平凡的修改任務。先不給任何 harness 支持,讓 agent 跑一次,記錄失敗。然後加一個 `AGENTS.md` 和顯式的驗證命令,讓同一個 agent 再跑一次。對比兩次的結果,把失敗歸因到五層防禦中的某一層。++2. **驗證缺口測量**:選 5 個編碼任務,在每個任務完成後記錄 agent 是否聲稱完成,然後用獨立測試驗證實際正確性。計算 agent 在實際沒完成時聲稱完成的比例——這就是你的驗證缺口。然後想想:加什麼驗證命令能把這個比例降下來?++3. **診斷循環實踐**:找一個 agent 在你的項目中反覆失敗的任務。跑一次,記錄失敗。歸因到五層中的某一層。修那一層。再跑。重複三到五輪,記錄每一輪的改善。diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.mdnew file mode 100644index 0000000..a23437d--- /dev/null+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md@@ -0,0 +1,21 @@+# Harness 元件範例++對於在本機 repo 中工作的程式碼 Agent:++- 模型:+ LLM 本身++- Harness:+ - system prompt+ - AGENTS.md+ - bash 工具+ - 檔案讀取/寫入工具+ - git 存取+ - 本機檔案系統+ - 啟動腳本+ - 測試指令+ - 停止鉤子+ - lint 檢查+ - 評估迴圈++如果你更改上述任何一個 harness 元件,你就改變了有效的 Agent。diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.tsnew file mode 100644index 0000000..d856ba3--- /dev/null+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts@@ -0,0 +1,180 @@+/**+ * harness-vs-no-harness.ts+ *+ * Side-by-side comparison of the same task executor running with and without+ * a harness. The harness version adds explicit rules, verification steps,+ * and stop conditions.+ *+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts+ */++// ---------------------------------------------------------------------------+// Types & helpers+// ---------------------------------------------------------------------------++interface TaskResult {+ name: string;+ passed: boolean;+ durationMs: number;+ issues: string[];+}++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++// ---------------------------------------------------------------------------+// Simulated task executor+// ---------------------------------------------------------------------------++/** A simple task that can succeed or fail depending on rules. */+type Task = {+ name: string;+ requiresAuth: boolean;+ hasTests: boolean;+ withinScope: boolean;+};++const tasks: Task[] = [+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },+];++// ---------------------------------------------------------------------------+// Run WITHOUT harness -- just execute every task, no checks+// ---------------------------------------------------------------------------++function runWithoutHarness(taskList: Task[]): TaskResult[] {+ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];++ // The "agent" does the work and calls it done.+ let passed = true;++ // Problems that go undetected without a harness+ if (t.requiresAuth && !t.hasTests) {+ issues.push("No tests for auth-protected endpoint");+ // Agent doesn't notice -- marks as pass anyway+ }+ if (!t.withinScope) {+ issues.push("Task is outside current scope");+ // Agent doesn't notice+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Run WITH harness -- rules, verification, stop conditions+// ---------------------------------------------------------------------------++function runWithHarness(taskList: Task[]): TaskResult[] {+ const rules = {+ requireTestsForAuth: true,+ enforceScope: true,+ };++ const results: TaskResult[] = [];++ for (const t of taskList) {+ const start = performance.now();+ const issues: string[] = [];+ let passed = true;++ // Rule: auth endpoints must have tests+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {+ issues.push("BLOCKED: Auth-protected endpoint missing tests");+ passed = false;+ }++ // Rule: stay in scope+ if (rules.enforceScope && !t.withinScope) {+ issues.push("BLOCKED: Task outside active scope -- skipped");+ passed = false;+ }++ // Verification: re-check after execution+ if (passed && !t.hasTests) {+ issues.push("WARNING: No tests exist for this change");+ }++ const duration = performance.now() - start;+ results.push({ name: t.name, passed, durationMs: duration, issues });+ }++ return results;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function printComparison(+ noHarness: TaskResult[],+ withHarness: TaskResult[]+): void {+ console.log("\n" + "=".repeat(80));+ console.log(" HARNESS vs NO-HARNESS COMPARISON");+ console.log("=".repeat(80));++ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;++ console.log("\n" + header);+ console.log(sep);++ for (let i = 0; i < noHarness.length; i++) {+ const nh = noHarness[i];+ const wh = withHarness[i];+ const nhPass = nh.passed ? "PASS" : "FAIL";+ const whPass = wh.passed ? "PASS" : "FAIL";+ const nhIssue = nh.issues[0] ?? "(none)";+ const whIssue = wh.issues[0] ?? "(none)";++ console.log(+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`+ );+ }++ // Metrics+ const nhPassed = noHarness.filter((r) => r.passed).length;+ const whPassed = withHarness.filter((r) => r.passed).length;+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);++ console.log("\n" + "=".repeat(80));+ console.log(" SUMMARY METRICS");+ console.log("=".repeat(80));++ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log("\n" + metricsHeader);+ console.log(metricsSep);+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);++ console.log("\n The harness catches problems the no-harness run silently ignores.");+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");+}++/** Count tasks that actually pass (have tests and are in scope). */+function truePassCount(results: TaskResult[]): number {+ return results.filter((r) => r.passed && r.issues.length === 0).length;+}++// ---------------------------------------------------------------------------+// Run+// ---------------------------------------------------------------------------++printComparison(runWithoutHarness(tasks), runWithHarness(tasks));diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/index.mdnew file mode 100644index 0000000..b9bcdeb--- /dev/null+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -0,0 +1,8 @@+# 第 02 講的程式碼++此資料夾用於區分以下項目的小型範例:++- 模型行為+- harness 行為+- 僅基於 prompt 的設定+- 由環境支援的 Agent 設定diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.tsnew file mode 100644index 0000000..e56cddd--- /dev/null+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts@@ -0,0 +1,36 @@+type Message = {+ role: "user" | "assistant";+ content: string;+};++type ToolResult = {+ ok: boolean;+ output: string;+};++function runTool(name: string, input: string): ToolResult {+ if (name === "read_file") {+ return { ok: true, output: `contents of ${input}` };+ }++ return { ok: false, output: `unknown tool: ${name}` };+}++export function minimalHarness(messages: Message[]) {+ const nextAction = {+ tool: "read_file",+ input: "README.md"+ };++ const result = runTool(nextAction.tool, nextAction.input);++ return {+ messages: [+ ...messages,+ {+ role: "assistant",+ content: `Tool ${nextAction.tool} returned: ${result.output}`+ }+ ]+ };+}diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.mdnew file mode 100644index 0000000..6e90e95--- /dev/null+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -0,0 +1,109 @@+[English Version →](../../../en/lectures/lecture-02-what-a-harness-actually-is/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/)+> 實戰練習:[Project 01. 只寫提示詞讓 agent 做,和定好規則再讓它做,差多少](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# 第二講. Harness 到底是什麼++"harness"這個詞在 AI coding agent 的圈子裡被用得越來越多了,但說實話,大部分人說的 harness 其實就只是"一個 prompt 檔案"。這不是 harness。就像你開了一家餐廳,只有食材——沒有灶臺、沒有刀具、沒有菜譜、沒有出菜流程——那不叫餐廳,那叫冰箱。++這節課要給你一個精確的、可操作的 harness 定義。不是學術論文裡的抽象概念,而是你今天就能拿去用的框架:harness 由五個子系統組成,就像一個完整廚房裡的五個功能區——菜譜架、刀具架、灶臺、備菜臺、和出菜檢查口。每個子系統都有明確的職責和評判標準。++## 先講一個類比++想象你是一個剛入職的工程師,被丟進一個沒有任何文檔的項目裡。沒有 README,代碼裡沒有註釋,沒有人告訴你怎麼跑測試,CI 配置檔案藏在某個角落裡。你能寫出好代碼嗎?也許能——如果你足夠聰明又足夠有耐心。但你會花大量時間在"搞清楚這個項目是怎麼回事"上,而不是在"解決問題"上。++AI agent 面對的困境一模一樣。而且更糟——你至少可以問同事,agent 只能看到你放在它面前的檔案和它能執行的命令。它不能拍拍同事的肩膀問"哎,這個項目的 ORM 用的是哪個版本?"++OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表述為"倉庫即規範"——所有必要的上下文都應該在倉庫裡,通過結構化的指令檔案、明確的驗證命令和清晰的目錄組織來呈現。Anthropic 的 long-running agents 文檔則更側重狀態持久化、顯式恢復路徑和結構化的進度跟蹤。兩家公司的側重點不同,但都在說同一件事:**模型之外的一切工程基礎設施,決定了模型能力能被髮揮多少。**++看看幾個你熟悉的工具:++**Claude Code** 的設計就體現了 harness 思想。它會讀你倉庫裡的 `CLAUDE.md`(菜譜架),能用 shell 跑命令(刀具架),在你的本地環境裡執行(灶臺),有會話歷史(備菜臺),能跑測試看結果(出菜檢查口)。但如果你不告訴它怎麼跑測試,出菜檢查口就是斷的——菜做沒做熟誰也不知道。++**Cursor** 也是類似的邏輯。它的 `.cursorrules` 檔案是菜譜架,終端是刀具架,它能讀你的項目結構和 lint 配置是灶臺。但 Cursor 的狀態管理相對弱——你關掉 IDE 再打開,上次的上下文就沒了。++**Codex**(OpenAI 的 coding agent)用 git worktree 隔離每個任務的運行環境,配合本地的可觀測性棧(日誌、指標、追蹤),讓每個變更都在獨立的環境中驗證。它在有 `AGENTS.md` 和清晰驗證命令的倉庫裡,表現遠超在"裸"倉庫裡。++**AutoGPT** 則是反面教材——缺乏結構化的狀態管理導致長任務中上下文不斷累積,缺乏精確的反饋機制導致 agent 陷入循環。很多人說 AutoGPT "不行",但其實是它的 harness 不行——你給它一個破灶臺,再好的食材也做不出菜來。++## 核心概念++- **什麼是 harness**:模型權重之外的一切工程基礎設施。OpenAI 把工程師的核心工作概括為三件事:設計環境、表達意圖、構建反饋循環。Anthropic 直接把 Claude Agent SDK 稱為"通用 agent harness"。+- **倉庫是唯一事實來源**:agent 看不到的東西,對它來說就不存在。OpenAI 把倉庫當作"記錄系統"——所有必要的上下文都必須在倉庫裡,通過結構化的檔案和清晰的目錄組織來呈現。+- **給地圖,不給說明書**:OpenAI 的經驗——`AGENTS.md` 應該是目錄頁,不是百科全書。100 行左右就夠了,放不下就拆分到 `docs/` 目錄裡,讓 agent 按需去讀。+- **約束而非微操**:好的 harness 用可執行的規則來約束 agent,而不是在指令裡逐條叮囑。OpenAI 說"執行不變量,不要微管實現";Anthropic 發現 agent 會自信地誇讚自己的工作,解決方案是把"幹活的人"和"檢查的人"分開。+- **逐個組件拆除法**:想量化 harness 各組件的價值,就逐個移除,看哪個移除後性能下降最多。Anthropic 用這個方法發現:隨著模型變強,某些組件不再關鍵,但總會有新的關鍵組件出現。++## Harness 五子系統模型++回到廚房的類比。一個完整的廚房有五個功能區,harness 也有五個子系統:++```mermaid+flowchart LR+ Rules["專案规则<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["進度和 git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["工具<br/>shell / 檔案 / 測試"]+ Tools --> Env["執行环境<br/>依赖 / 服務 / 版本"]+ Env --> Checks["檢查結果<br/>test / lint / build"]+ Checks --> Agent+```++**指令子系統(菜譜架)**:創建 `AGENTS.md`(或 `CLAUDE.md`),內容包括項目概覽和目的(一句話說清楚這是什麼)、技術棧和版本(Python 3.11、FastAPI 0.100+、PostgreSQL 15)、首次運行命令(`make setup`、`make test`)、不可違反的硬約束("所有 API 必須走 OAuth 2.0")、指向更詳細文檔的鏈接。++**工具子系統(刀具架)**:確保 agent 有足夠的工具訪問權限。不要因為"安全考慮"把 shell 給禁了——agent 連 `pip install` 都跑不了,還怎麼幹活?但也別什麼都開放,按最小權限原則來。++**環境子系統(灶臺)**:讓環境狀態自描述。用 `pyproject.toml` 或 `package.json` 鎖定依賴,用 `.nvmrc` 或 `.python-version` 指定運行時版本,用 Docker 或 devcontainer 讓環境可重現。++**狀態子系統(備菜臺)**:長任務必須有進度跟蹤。用一個簡單的 `PROGRESS.md` 檔案記錄:哪些做完了,哪些在做,哪些被阻塞。每個會話結束前更新,下一個會話開始時讀取。++**反饋子系統(出菜檢查口)**:這是投入產出比最高的子系統。在 `AGENTS.md` 裡顯式列出驗證命令:+```+驗證命令:+- 測試:pytest tests/ -x+- 類型檢查:mypy src/ --strict+- Lint:ruff check src/+- 完整驗證:make check(包含以上全部)+```++五個子系統缺一個,就像廚房裡少了一個功能區——菜還是能做,但總是彆扭。++**診斷 harness 質量的方法**:用"等模型對照實驗"。保持模型不變,逐個移除五個子系統,看哪個子系統缺失時性能下降最多。那個就是你的瓶頸——集中精力加強它。就像找廚房的瓶頸一樣:把菜譜架拿走看看出菜速度降多少,把灶臺關掉看看影響多大。++## 一個團隊的真實經歷++一個團隊用 GPT-4o 開發一個 TypeScript + React 前端應用(約 20,000 行代碼)。他們經歷了四個階段——其實就是在一件一件地添置廚具:++**階段 1——空廚房**:只有 README 裡的基本項目描述。5 次運行成功 1 次(20%)。主要失敗:選錯了包管理器(npm vs yarn)、沒遵循組件命名約定、跑不了測試。++**階段 2——裝上菜譜架**:添加 `AGENTS.md`,寫明技術棧版本、命名約定、關鍵架構決策。成功率升到 60%。剩餘失敗主要來自環境問題和驗證缺失。++**階段 3——開起出菜檢查口**:在 `AGENTS.md` 裡列出驗證命令 `yarn test && yarn lint && yarn build`。成功率升到 80%。++**階段 4——備菜臺就位**:引入進度檔案範本,agent 在每次運行中記錄完成和未完成的工作。成功率穩定在 80-100%。++四次迭代,模型一個字沒改,成功率從 20% 到接近 100%。這就是 harness 工程的力量。你沒有換更貴的食材,你只是把廚房收拾利索了。++## 關鍵要點++- Harness = 指令 + 工具 + 環境 + 狀態 + 反饋。五個子系統,就像廚房的五個功能區,缺一不可。+- 不是模型權重的部分全是 harness。你的 harness 決定了模型能力能被髮揮多少。+- 五個子系統中,反饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚——出菜檢查口是最值得先裝的。+- 用"等模型對照實驗"量化各子系統的邊際貢獻,別憑感覺。+- Harness 和代碼一樣會腐化。定期審計,像還技術債一樣還 harness 債。++## 延伸閱讀++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)++## 練習++1. **Harness 五元組審計**:拿你正在用 AI agent 的項目,按五元組框架做一個完整審計。每個子系統打 1-5 分。找出最低分的那個子系統,花 30 分鐘改進它,然後觀察 agent 的表現變化。++2. **等模型對照實驗**:選一個模型和一個有挑戰性的任務。依次移除指令(刪掉 AGENTS.md)、移除反饋(不給驗證命令)、移除狀態(不提供進度檔案),每次只移除一個,測量性能下降幅度。基於結果,排出各子系統對你項目的重要性排名。++3. **可供性分析**:找一個 agent 在你的項目中"想做但做不了"的場景(比如知道要用參數化查詢但不知道你項目的 ORM 怎麼寫)。分析這是執行鴻溝(不知道怎麼操作)還是評估鴻溝(不知道做得對不對),然後設計 harness 改進來彌補。diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdnew file mode 100644index 0000000..75c4cbc--- /dev/null+++ b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md@@ -0,0 +1,7 @@+# 第 03 講的程式碼++此資料夾用於以下範例:++- Agent 可讀的 repo 結構+- 以文件作為系統記錄+- 不良與良好的知識放置方式diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txtnew file mode 100644index 0000000..45315da--- /dev/null+++ b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt@@ -0,0 +1,13 @@+AGENTS.md+docs/+ ARCHITECTURE.md+ PRODUCT.md+ RELIABILITY.md+ references/+ electron.md+ sqlite.md+ plans/+ active/+ completed/+src/+scripts/diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.tsnew file mode 100644index 0000000..46f6a62--- /dev/null+++ b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts@@ -0,0 +1,189 @@+/**+ * repo-reader.ts+ *+ * Reads a directory structure and scores it on discoverability.+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,+ * handoff files, and other signals of a repository that serves as the+ * system of record.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]+ * (defaults to current working directory if no path given)+ *+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Scoring criteria+// ---------------------------------------------------------------------------++interface Check {+ name: string;+ description: string;+ maxPoints: number;+ check: (dir: string) => { points: number; found: string[]; missing: string[] };+}++const checks: Check[] = [+ {+ name: "AGENTS.md / CLAUDE.md",+ description: "Agent-readable instruction file at repo root",+ maxPoints: 15,+ check: (dir) => {+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };+ },+ },+ {+ name: "Documentation directory",+ description: "Dedicated docs/ or documentation/ directory",+ maxPoints: 10,+ check: (dir) => {+ const candidates = ["docs", "documentation", "doc"];+ const found = candidates.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };+ },+ },+ {+ name: "Architecture documentation",+ description: "Files describing system architecture",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",+ "docs/architecture/", "design.md", "DESIGN.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };+ },+ },+ {+ name: "Feature tracking",+ description: "Feature list or task tracking file",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "feature_list.json", "features.md", "FEATURES.md",+ "docs/features.md", "tasks.json", "TODO.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };+ },+ },+ {+ name: "Handoff / session continuity",+ description: "Files for multi-session continuity",+ maxPoints: 15,+ check: (dir) => {+ const patterns = [+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",+ "docs/handoff.md", ".handoff", "PROGRESS.md",+ ];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };+ },+ },+ {+ name: "Testing structure",+ description: "Test directory or test configuration",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["test", "tests", "__tests__", "spec"];+ const found = patterns.filter((f) => {+ const p = path.join(dir, f);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };+ },+ },+ {+ name: "Configuration files",+ description: "Project config (package.json, tsconfig, etc.)",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };+ },+ },+ {+ name: "README",+ description: "Root README file",+ maxPoints: 10,+ check: (dir) => {+ const patterns = ["README.md", "README.rst", "README.txt", "README"];+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };+ },+ },+];++// ---------------------------------------------------------------------------+// Report generation+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function scoreRepo(targetDir: string): void {+ const resolved = path.resolve(targetDir);++ if (!fs.existsSync(resolved)) {+ console.error(` Error: Directory not found: ${resolved}`);+ process.exit(1);+ }++ console.log("\n" + "=".repeat(80));+ console.log(" REPOSITORY DISCOVERABILITY SCORE");+ console.log("=".repeat(80));+ console.log(` Target: ${resolved}\n`);++ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ let totalScore = 0;+ let maxScore = 0;++ for (const check of checks) {+ const result = check.check(resolved);+ totalScore += result.points;+ maxScore += check.maxPoints;+ const status = result.points > 0 ? "PASS" : "FAIL";+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];++ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);+ }++ // Final score+ console.log("\n" + "-".repeat(80));+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);++ // Grade+ const pct = totalScore / maxScore;+ let grade: string;+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";+ else grade = "F -- Repository lacks discoverability signals";++ console.log(` GRADE: ${grade}`);+ console.log("=".repeat(80) + "\n");+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const target = process.argv[2] || process.cwd();+scoreRepo(target);diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.mdnew file mode 100644index 0000000..b87b2eb--- /dev/null+++ b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md@@ -0,0 +1,11 @@+# 系統記錄檢查清單++一個全新的 Agent 能否僅從 repo 中發現以下資訊?++- 正在建構什麼產品?+- 應用程式應該為使用者做什麼?+- 程式碼庫如何組織?+- 應用程式如何啟動?+- 如何檢查健康狀態?+- 目前正在進行什麼工作?+- 哪些品質標準很重要?diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdnew file mode 100644index 0000000..7592e7f--- /dev/null+++ b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -0,0 +1,137 @@+[English Version →](../../../en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)+> 實戰練習:[Project 02. 讓 agent 看懂項目、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)++# 第三講. 讓代碼倉庫成為唯一的事實來源++你團隊的架構決策散落在 Confluence、Slack、Jira、和幾個資深工程師的腦子裡。對人類來說這勉強夠用——你可以問同事、搜聊天記錄、翻文檔。實在不行還能去茶水間堵人。但對 AI agent 來說,不在倉庫裡的信息等於不存在。++這不是誇張。想想 agent 的輸入都有什麼:系統提示和任務描述、倉庫裡的檔案內容、以及工具執行的輸出。就這三樣。你的 Slack 歷史、Jira 工單、Confluence 頁面、和週五下午跟同事在茶水間聊的架構決定——agent 全都看不到。它不能"去問一下",也不能"搜一下聊天記錄"。它就是一個被關在倉庫裡的工程師——倉庫外面的事,它一概不知。++所以問題變成了:你給不給這個工程師一張好地圖?++## 地圖上該畫什麼++OpenAI 在他們的 harness engineering 文章裡把這個問題說得非常直白:**倉庫裡不存在的信息,對 agent 來說等於不存在。** 他們把這稱為"倉庫即規範"原則——倉庫本身就是最高權威的規範文檔。++Anthropic 的 long-running agents 文檔也強調了類似的觀點:持久化狀態是長任務連續性的必要條件。跨會話的知識可恢復性直接決定了任務成功率。而這些狀態必須存在於倉庫中——因為那是 agent 唯一穩定可訪問的存儲。++你可能會想:"我們團隊人少,知識都在大家腦子裡,這不也工作得好好的嗎?"沒錯,對人類來說確實可以。但你要用 agent,就得接受一個事實:agent 不能問人。所有它需要知道的東西,都必須寫下來,放在它能找到的地方。++這不是"寫更多文檔"的問題。這是"把決策信息放到正確的位置"的問題。一份在 `src/api/` 目錄下、50 行的 `ARCHITECTURE.md`,比一份在 Confluence 裡、500 頁但沒人維護的設計文檔有用一萬倍。就好比一張貼在你工位上的、手畫的辦公室走法圖,比一份精美的、放在檔案室裡的建築藍圖實用得多——因為前者在你需要的時候就在手邊。++## 知識可見性++```mermaid+flowchart LR+ Slack["Slack 裡的规则"] --> Write["寫进倉庫檔案<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Confluence 裡的规则"] --> Write+ Heads["工程师脑子裡的规则"] --> Write+ Jira["Jira 裡的规则"] --> Write+ Write --> Repo["倉庫檔案"]+ Repo --> Agent["新的 agent 會話<br/>直接讀倉庫"]+ Warning["规则不寫进倉庫<br/>agent 就看不见"] --> Agent+```++怎麼檢驗你的地圖畫得夠不夠好?做一個"冷啟動測試":開一個全新的 agent 會話,只看倉庫內容,看它能不能回答五個基本問題:++```mermaid+flowchart TB+ Q1["這是什么系統?"] --> A1["AGENTS.md / README"]+ Q2["怎么组织的?"] --> A2["ARCHITECTURE.md / 模块文檔"]+ Q3["怎么跑?"] --> A3["Makefile / init.sh / package scripts"]+ Q4["怎么驗證?"] --> A4["測試、lint、check 命令"]+ Q5["现在做到哪了?"] --> A5["PROGRESS.md / 功能清單 / git 历史"]++ A1 --> Ready["新的會話不用问人<br/>就能開始工作"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready+```++如果它答不上來,說明地圖上有空白。空白的地方,agent 就得自己猜——猜錯了就是 bug,猜多了就浪費上下文。每個新會話都要猜一遍,猜的成本遠高於一開始就把地圖畫好的成本。++## 核心概念++- **知識可見性缺口**:項目總知識中不在倉庫裡的比例。缺口越大,agent 失敗的概率越高。你腦子裡有多少關於這個項目的隱性知識?把它們全算上,再看有多少寫進了倉庫——兩者的差距就是你的可見性缺口。+- **系統記錄(System of Record)**:代碼倉庫作為項目決策、架構約束、執行狀態和驗證標準的權威信息源。倉庫說了算,別的地方說了不算。就像地圖上標註了"此路不通",你就不會再往那條路走——但如果這個信息只在老張的腦子裡,你每次都得問老張。+- **冷啟動測試**:上一節說的五個問題。能回答幾個,你的地圖就畫了幾分。+- **發現成本**:agent 為了在倉庫裡找到一條關鍵信息需要消耗多少上下文。信息放得越隱蔽,發現成本越高,留給實際任務的預算越少。把關鍵信息藏在十層目錄深處的 README 裡,就像把滅火器鎖在地下室的保險櫃裡——不是沒有,是用的時候找不到。+- **知識衰減率**:倉庫中單位時間內變得過時的知識條目比例。文檔和代碼脫節是最大的敵人——比沒有文檔更危險的是過時的文檔。+- **ACID 類比**:把數據庫的事務管理原則(原子性、一致性、隔離性、持久性)用到 agent 的狀態管理上。後面會展開講。++## 怎麼畫好這張地圖++**原則 1:知識靠近代碼。** 一條關於 API 端點認證的規則,應該放在 API 代碼旁邊,而不是藏在一個巨大的全局文檔裡。每個模塊目錄下放一個簡短的文檔,說清楚這個模塊的職責、接口和特殊約束。就像圖書館的書架標籤——你想找歷史類書籍,直接去標著"歷史"的書架,不用把整個圖書館翻一遍。++**原則 2:用標準化的入口檔案。** `AGENTS.md`(或 `CLAUDE.md`)是 agent 的"著陸頁"。它不需要包含所有信息,但必須能讓 agent 快速回答"這是什麼項目"、"怎麼跑"、"怎麼驗證"這三個問題。50-100 行就夠了。++**原則 3:最小但完備。** 每條知識都應該有明確的使用場景。如果你刪掉某條規則不影響 agent 的決策質量,那這條規則就不應該存在。但冷啟動測試中的每個問題都必須有答案。這是一個精妙的平衡——不多不少,剛好夠用。++**原則 4:和代碼一起更新。** 把知識更新跟代碼變更綁定在一起。最簡單的方法:把架構文檔放在對應的模塊目錄裡。改代碼的時候自然會看到文檔,改代碼之後 CI 提醒你檢查文檔是否需要更新。++**具體的倉庫結構**:++```+project/+├── AGENTS.md # 入口:專案概覽、執行命令、硬约束+├── src/+│ ├── api/+│ │ ├── ARCHITECTURE.md # API 层的架构决策+│ │ └── ...+│ ├── db/+│ │ ├── CONSTRAINTS.md # 資料庫操作的硬约束+│ │ └── ...+│ └── ...+├── PROGRESS.md # 当前進度:做了什么、在做什么、被什么阻塞+└── Makefile # 標準化的操作命令:setup、test、lint、check+```++## 用 ACID 原則管理 agent 狀態++這個類比來自數據庫的事務管理——你可能覺得這是在把簡單的事情搞複雜,但實際上它給了你一個非常實用的框架:++- **原子性**:每次"邏輯操作"(比如"添加新端點並更新測試")用一個 git commit 原子化。中途掛了就 `git stash` 回滾。要麼全做,要麼不做,沒有"做了一半"。+- **一致性**:定義"一致狀態"的驗證謂詞——所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。就像銀行轉賬——你不能只扣款不入賬。+- **隔離性**:多個 agent 併發工作時,狀態檔案要避免競爭條件。簡單方案:每個 agent 用獨立的進度檔案,或者用 git 分支隔離。兩個廚師不能同時往同一口鍋裡放鹽——放重了誰負責?+- **持久性**:關鍵的項目知識用 git 跟蹤的檔案持久化。臨時狀態可以只在會話內存裡,但跨會話必須的知識必須寫到檔案裡。腦子裡的不算,寫在紙上的才算。++## 一個真實的改造故事++一個團隊維護一個包含約 30 個微服務的電商平臺。架構決策(服務間通信協議、數據一致性策略、API 版本化規則)散落在:Confluence(部分過時)、Slack(難以搜索)、幾個資深工程師的腦子裡(不可擴展)、以及零星的代碼註釋(不繫統)。++引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個"所有人都知道但從未寫入倉庫"的隱性約束。這就像一個新來的員工,沒人告訴他"中午點外賣要在群裡接龍"——他自己猜,猜錯了被罵,但罵完了還是沒人告訴他規則。++團隊執行了改造:+1. 倉庫根目錄創建 `AGENTS.md`,寫明項目概覽、技術棧版本、全局硬約束+2. 每個微服務目錄下添加 `ARCHITECTURE.md`,描述該服務的職責、接口和依賴+3. 創建集中的 `CONSTRAINTS.md`,用"禁止/必須"的明確語言記錄硬約束+4. 每個服務目錄添加 `PROGRESS.md`,記錄當前工作狀態++改造後:同一 agent 能在冷啟動時回答所有關鍵項目問題,任務完成質量顯著提升。++## 關鍵要點++- 不在倉庫裡的知識對 agent 來說等於不存在。把關鍵決策信息放進倉庫是最基本的 harness 投資——畫好地圖,才不會迷路。+- 用"冷啟動測試"檢驗倉庫質量:全新會話能不能只看倉庫回答五個基本問題。+- 知識要靠近代碼、最小但完備、跟代碼一起更新。不是寫更多文檔,是把信息放到正確的位置。+- 用 ACID 原則管理 agent 狀態:原子提交、一致性驗證、隔離併發、持久化關鍵知識。+- 知識衰減是最大敵人。過時的文檔比沒有文檔更危險——它會讓 agent 走錯方向還以為自己是對的。++## 延伸閱讀++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [ADR: Architecture Decision Records](https://adr.github.io/)+- [The Twelve-Factor App](https://12factor.net/)++## 練習++1. **冷啟動測試**:在你的項目裡開一個全新的 agent 會話(不提供任何口頭上下文),只讓它看倉庫內容,然後問它五個問題:這是什麼系統?怎麼組織的?怎麼運行?怎麼驗證?現在進度如何?記錄它答不上來的問題,然後改進倉庫讓它能答上來。++2. **知識外置化量化**:列出你的項目中所有對開發工作重要的決策和約束。標註每個條目是在倉庫內還是倉庫外。算一下你的知識可見性缺口有多大(不在倉庫裡的佔總數的比例)。制定計劃把缺口降到 10% 以下。++3. **ACID 準則評估**:用本講的 ACID 類比評估你的項目狀態管理。原子性——agent 的操作能不能幹淨地回滾?一致性——倉庫有沒有"一致狀態"的驗證?隔離性——多 agent 併發時會不會互相踩腳?持久性——跨會話的知識是不是都持久化了?diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdnew file mode 100644index 0000000..65a0de8--- /dev/null+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -0,0 +1,14 @@+# AGENTS.md++## 從這裡開始++- 閱讀 `docs/ARCHITECTURE.md`+- 閱讀 `docs/PRODUCT.md`+- 使用 `npm run dev` 啟動應用程式+- 在標記工作完成前使用 `npm run check`++## 硬性規則++- 在未閱讀 `docs/ARCHITECTURE.md` 的情況下,不得更改 Electron main/preload/renderer 邊界+- 未經驗證不得將功能標記為完成+- 為下一個 session 留下乾淨的狀態diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdnew file mode 100644index 0000000..10def73--- /dev/null+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -0,0 +1,7 @@+# 指令檔案反模式++- 將所有 repo 知識放入單一檔案+- 在多個地方重複相同的規則+- 編寫無人審核的過時規則+- 撰寫過於具體而鮮少適用的條件式指令+- 在啟動上下文中嵌入冗長的工具手冊diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdnew file mode 100644index 0000000..3ecb4b9--- /dev/null+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md@@ -0,0 +1,7 @@+# 第 04 講的程式碼++此資料夾用於以下範例:++- 單體式指令檔案+- 簡短入口點+- 漸進式揭露模式diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.tsnew file mode 100644index 0000000..59a9632--- /dev/null+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts@@ -0,0 +1,209 @@+/**+ * split-vs-monolithic.ts+ *+ * Creates a monolithic instruction file (~200 lines) and then shows how+ * splitting into 4 focused files dramatically reduces the context needed+ * for any single query. Simulates an "agent" searching for a specific rule+ * and measures how many lines it must read in each approach.+ *+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts+ */++// ---------------------------------------------------------------------------+// Simulated monolithic instruction file (200 lines of rules)+// ---------------------------------------------------------------------------++const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];++// Section 1: Project Overview (lines 1-50)+for (let i = 1; i <= 50; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Project Overview",+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,+ });+}++// Section 2: Code Style Rules (lines 51-100)+for (let i = 51; i <= 100; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Code Style",+ content:+ i === 72+ ? "RULE: Always use explicit return types on exported functions."+ : i === 78+ ? "RULE: Use const assertions for immutable arrays."+ : `Style rule detail line ${i}`,+ });+}++// Section 3: Testing Standards (lines 101-150)+for (let i = 101; i <= 150; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Testing",+ content:+ i === 120+ ? "RULE: Every new endpoint must have integration tests."+ : i === 135+ ? "RULE: Test files must mirror the source file structure."+ : `Testing detail line ${i}`,+ });+}++// Section 4: Deployment Rules (lines 151-200)+for (let i = 151; i <= 200; i++) {+ monolithicInstructions.push({+ lineNumber: i,+ section: "Deployment",+ content:+ i === 175+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."+ : `Deployment detail line ${i}`,+ });+}++// ---------------------------------------------------------------------------+// Split instruction files (4 focused files)+// ---------------------------------------------------------------------------++const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),+};++// ---------------------------------------------------------------------------+// Simulated queries -- the agent needs to find specific rules+// ---------------------------------------------------------------------------++interface Query {+ description: string;+ targetRule: string;+ relevantSection: string;+}++const queries: Query[] = [+ {+ description: "Find the rule about return types",+ targetRule: "explicit return types",+ relevantSection: "Code Style",+ },+ {+ description: "Find the deployment window rule",+ targetRule: "deploy on Fridays",+ relevantSection: "Deployment",+ },+ {+ description: "Find the integration test rule",+ targetRule: "integration tests",+ relevantSection: "Testing",+ },+ {+ description: "Find the test file structure rule",+ targetRule: "mirror the source file",+ relevantSection: "Testing",+ },+];++// ---------------------------------------------------------------------------+// Search simulation+// ---------------------------------------------------------------------------++function searchMonolithic(query: Query): { linesRead: number; found: boolean } {+ // Agent must scan from the top, reading each line until it finds the rule.+ // In the worst case it reads all lines.+ let linesRead = 0;+ let found = false;++ for (const line of monolithicInstructions) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found };+}++function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {+ // Agent knows which file to look in based on the section.+ // It only reads lines from that one file.+ const fileMap: Record<string, string> = {+ "Project Overview": "01-project-overview.md",+ "Code Style": "02-code-style.md",+ Testing: "03-testing.md",+ Deployment: "04-deployment.md",+ };++ const targetFile = fileMap[query.relevantSection];+ const lines = splitInstructions[targetFile];+ let linesRead = 0;+ let found = false;++ for (const line of lines) {+ linesRead++;+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {+ found = true;+ break;+ }+ }++ return { linesRead, found, fileAccessed: targetFile };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");+ console.log("=".repeat(90));++ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");++ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;+ console.log(header);+ console.log(sep);++ let totalMono = 0;+ let totalSplit = 0;++ for (const q of queries) {+ const mono = searchMonolithic(q);+ const split = searchSplit(q);+ totalMono += mono.linesRead;+ totalSplit += split.linesRead;++ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);+ console.log(+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`+ );+ }++ console.log(sep);+ const avgMono = Math.round(totalMono / queries.length);+ const avgSplit = Math.round(totalSplit / queries.length);+ console.log(+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`+ );++ console.log("\n" + "=".repeat(90));+ console.log(" KEY INSIGHT");+ console.log("=".repeat(90));+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");+}++run();diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdnew file mode 100644index 0000000..8ff9acf--- /dev/null+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -0,0 +1,132 @@+[English Version →](../../../en/lectures/lecture-04-why-one-giant-instruction-file-fails/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)+> 實戰練習:[Project 02. 讓 agent 看懂項目、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)++# 第四講. 把指令拆分到不同檔案裡++你開始認真對待 harness 了——好事。你建了個 `AGENTS.md`,把你能想到的所有規則、約束、歷史教訓都塞了進去。一個月後這個檔案膨脹到了 300 行,兩個月 450 行,三個月 600 行。然後你發現 agent 的表現反而變差了——改一個小 bug,agent 花大量上下文處理無關的部署指令;關鍵的安全約束埋在第 300 行,被直接忽略了;檔案裡有三條互相矛盾的代碼風格規則,agent 每次隨機選一條。++這就是"巨型指令檔案"陷阱。就像你往行李箱裡塞東西——覺得什麼都有用,什麼都往裡裝,結果拉鍊快崩了,想找換洗內衣得把整個箱子翻一遍。帶了一箱子東西,但真正用上的可能只有三分之一。++## 問題的根源:一個惡性循環++最常見的惡性循環是這樣的:agent 犯了個錯 → 你說"加條規則防止這個" → 加到 AGENTS.md → 暫時管用 → agent 又犯了另一個錯 → 再加一條 → 重複 → 檔案膨脹到不可控。++這不是你的錯。這是一個非常自然的反應——每次出問題就"加條規則"感覺很合理,就像每次出門忘帶東西就往包裡多塞一樣。但累積效應是災難性的。讓我們看看具體出了什麼問題。++**上下文預算被吃掉了。** Agent 的上下文窗口是有限的。假設你的 agent 有 200K tokens 的窗口(Claude 的標準),一個膨脹的指令檔案可能佔掉 10-20K。看起來還有不少餘量?但一個複雜的任務可能需要讀幾十個源檔案、工具執行的輸出也占上下文、對話歷史也在累積。到真正需要理解代碼的時候,預算已經不夠了——就像你的行李箱塞滿了"萬一用得著"的東西,結果放不下真正需要帶的電腦了。++**中間迷失。** "Lost in the Middle"這篇論文(Liu et al., 2023)清楚地證明了:LLM 對長文本中間部分的信息利用效率顯著低於兩端。你的 AGENTS.md 有 600 行,第 300 行寫的是"所有數據庫查詢必須用參數化查詢"——這是安全硬約束。但它被埋在中間,agent 幾乎一定會忽略它。就像你的行李箱裡那瓶防曬霜——明明在最底層,但你翻三遍也找不到,最後又去買了一瓶。++**優先級衝突。** 檔案裡混合了不可違反的硬約束("不得使用 eval()")、重要的設計指導("優先使用函數式風格")、和某個特定場景的歷史教訓("上週修了一個 WebSocket 內存洩漏,注意類似的模式")。這三條規則的重要性完全不同,但在檔案裡看起來一模一樣。Agent 沒有可靠的信號來區分——就像行李箱裡護照和充電線混在一起,看不出哪個更緊急。++**維護衰減。** 大檔案天生難維護。指令過時了沒人刪——因為刪除的後果不確定("也許別的地方依賴這條規則?"),但加新指令是無成本的。結果檔案只增不減,信噪比持續下降。這和軟件裡的技術債務積累一模一樣。++**矛盾累積。** 不同時期加的指令之間開始出現矛盾——一條說"用 TypeScript 嚴格模式",另一條說"某些遺留檔案允許用 any"。Agent 每次隨機選一條遵循。就像你媽說"穿厚點",你爸說"別穿太多",你站在門口不知道聽誰的。++## 核心概念++- **指令膨脹**:當指令檔案佔用了超過上下文窗口 10-15% 的時候,它就開始擠佔代碼閱讀和任務推理的預算。600 行的 `AGENTS.md` 可能佔用 10,000-20,000 tokens——對 128K 的窗口來說,這就吃掉了 8-15%。+- **中間迷失效應**:Liu 等人 2023 年的研究證明,LLM 對長文本中間部分的信息利用效率顯著低於兩端。埋在 600 行檔案中間第 300 行的關鍵約束,被有效忽略的概率非常高。+- **指令信噪比(SNR)**:檔案中與當前任務相關的指令佔總指令的比例。做 bug 修復時被要求讀 50 行部署指令——SNR 很低。+- **路由檔案**:短小的入口檔案,核心功能是引導 agent 去找更詳細的文檔,而不是自己包含所有內容。50-200 行就夠了。+- **漸進式披露**:先給概要信息,需要的時候再給詳細信息。好的 harness 設計和好的 UI 設計一樣,不把所有選項一次性砸到用戶臉上。+- **優先級模糊度**:當所有指令以相同格式和位置呈現時,agent 分不清哪些是不可違反的硬約束,哪些是建議性的軟約束。++## 指令檔案架構++```mermaid+flowchart LR+ Mono["一個超长 AGENTS.md"] --> MonoLoad["改一個小 bug<br/>也得把部署說明和历史备注全讀一遍"]+ MonoLoad --> MonoRisk["關键规则埋在中间<br/>很容易漏掉"]++ Router["短 AGENTS.md"] --> Topics["按任務去讀 API / 資料庫 / 測試文檔"]+ Topics --> RoutedResult["把更多上下文留给程式碼阅讀<br/>和驗證"]+```++```mermaid+flowchart TB+ File["600 行指令檔案"] --> Top["顶部<br/>快速開始 + 硬约束"]+ File --> Mid["中部<br/>第 300 行的安全规则"]+ File --> Bot["底部<br/>明确的結束檢查清單"]+ Top --> Seen["高概率被记住"]+ Bot --> Seen+ Mid --> Missed["高概率被稀释或忽略"]+```++## 拆分思路++核心原則:常用信息放手邊,偶爾用的收起來,用不上的別帶。++入口檔案 `AGENTS.md` 控制在 50-200 行,只放最常用的東西——項目概覽(一兩句話說清楚這是什麼)、首次運行命令(`make setup && make test`)、全局硬約束(不超過 15 條不可違反的規則)、指向專題文檔的鏈接(一行描述 + 適用條件)。++```markdown+# AGENTS.md++## 專案概覽+Python 3.11 FastAPI 後端,PostgreSQL 15 資料庫。++## 快速開始+- 安装:`make setup`+- 測試:`make test`+- 完整驗證:`make check`++## 硬约束+- 所有 API 必須走 OAuth 2.0 認證+- 所有資料庫查询必須用 SQLAlchemy 2.0 语法+- 所有 PR 必須通過 pytest + mypy --strict + ruff check++## 专题文檔+- [API 設計規範](docs/api-patterns.md) — 添加新端点時必讀+- [資料庫操作约束](docs/database-rules.md) — 涉及資料庫修改時必讀+- [測試標準](docs/testing-standards.md) — 编寫測試時参考+```++每個專題文檔 50-150 行,按主題放在 `docs/` 目錄下或對應模塊目錄旁。Agent 只在需要時才去讀。就像行李箱裡的收納袋——內衣一個袋,洗漱一個袋,充電器一個袋。找東西不用翻整個箱子。++還有些信息直接放在代碼裡更合適——類型定義、接口註釋、配置檔案裡的說明。Agent 讀代碼的時候自然能看到,不用再在指令裡重複一遍。++每條指令都應該標明來源("為什麼加這條規則?")、適用條件("這條規則在什麼時候需要?")、過期條件("什麼情況下可以刪掉這條規則?")。定期審計,刪掉過時的、冗餘的、矛盾的條目。像管理代碼依賴一樣管理你的指令——用不上的依賴就該刪掉,不然它們只會拖慢系統。++如果某條指令必須在入口檔案裡,放頂部或底部——不要放中間。"中間迷失"效應告訴我們,LLM 對長文本中間部分的信息利用效率顯著低於兩端。但更好的做法是把指令放到專題文檔裡,讓 agent 按需加載。++OpenAI 和 Anthropic 都隱性支持拆分的做法。OpenAI 說入口檔案應"短小且以路由為導向",Anthropic 說長運行 agent 的控制信息應"簡潔且高優先級"。兩家都在說同一件事:別把什麼都塞進一個檔案裡。行李箱得整理,不能只靠蠻力塞。++## 實際案例++一個 SaaS 團隊的 `AGENTS.md` 從最初的 50 行膨脹到 600 行。內容混合了技術棧版本、編碼規範、歷史 bug 修復筆記、API 使用說明、部署流程、和團隊成員的個人偏好——整個行李箱塞得滿滿當當,拉鍊都快崩了。++Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量上下文處理無關的部署指令;安全約束"所有數據庫查詢必須用參數化查詢"埋在第 300 行,經常被忽略;三條矛盾的代碼風格規則導致 agent 隨機選擇。++團隊執行了"行李箱整理":+1. `AGENTS.md` 裁剪到 80 行:只保留項目概覽、運行命令、15 條全局硬約束+2. 創建專題文檔:`docs/api-patterns.md`(120 行)、`docs/database-rules.md`(60 行)、`docs/testing-standards.md`(80 行)+3. 路由檔案添加指向專題文檔的鏈接+4. 歷史筆記要麼轉成測試用例,要麼刪除++重構後:同一任務集的成功率從 45% 提升到 72%。安全約束遵循率從 60% 提升到 95%——因為從檔案中間移到了路由檔案頂部,不再被"中間迷失"了。++## 關鍵要點++- "加條規則"是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文檔是不是更合適?——別什麼都往行李箱裡塞。+- 入口檔案是路由器,不是百科全書。50-200 行,只放概覽、硬約束、和鏈接。+- 利用"中間迷失"效應:重要信息放檔案頂部或底部,不重要的移到專題文檔。+- 像管理技術債一樣管理指令膨脹。定期審計,每條指令要有來源、適用條件、和過期條件。+- 拆分之後信噪比提升,agent 把更多上下文預算花在實際任務上,而不是處理無關指令。++## 延伸閱讀++- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)++## 練習++1. **信噪比審計**:拿你當前的入口指令檔案,列出所有指令條目。選 5 個不同的常見任務類型,標註每條指令是否跟該任務相關。計算每個任務類型的 SNR。那些對大多數任務都是噪聲的指令,移到專題文檔裡。++2. **漸進式披露重構**:如果你有一個超過 300 行的指令檔案,把它拆成:(a) 不超過 100 行的路由檔案,(b) 3-5 個專題文檔。重構前後各跑同一組任務(至少 5 個),對比成功率。++3. **中間迷失驗證**:在一個長指令檔案裡,把一條關鍵約束分別放在頂部、中間、底部各跑一組任務(每組至少 5 次),看遵循率有沒有差別。你可能會驚訝於位置效應有多大。diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.mdnew file mode 100644index 0000000..87705f6--- /dev/null+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md@@ -0,0 +1,6 @@+# 連續性檢查清單++- 一個全新的 Agent 能否在五分鐘內識別近期的工作?+- 目前穩定的啟動路徑是否有記錄?+- 未完成的工作是否已被清楚標示?+- 是否可以在不閱讀舊的聊天記錄的情況下看到下一個最佳任務?diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdnew file mode 100644index 0000000..a4afec8--- /dev/null+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md@@ -0,0 +1,7 @@+# 第 05 講的程式碼++此資料夾用於以下範例:++- 中斷的多 session 任務+- 缺少連續性產物+- 連續性恢復模式diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdnew file mode 100644index 0000000..40b3920--- /dev/null+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -0,0 +1,17 @@+# Session 交接範例++## 已完成++- 新增 markdown 匯入支援+- 在 renderer 中新增了基本文件列表++## 已損壞或未驗證++- `.md` 匯入成功,但大型 `.txt` 檔案匯入失敗+- 應用程式可以啟動,但詳細檢視尚未連接++## 下一步最佳步驟++- 修復 `.txt` 匯入路徑+- 端到端驗證匯入功能+- 然後新增文件詳細資訊面板diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.tsnew file mode 100644index 0000000..69f9c3e--- /dev/null+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts@@ -0,0 +1,162 @@+/**+ * session-simulator.ts+ *+ * Simulates two sessions working on a multi-step task.+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.+ * Run 2: With handoff file -- Session B picks up where Session A left off.+ *+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface TaskStep {+ id: number;+ name: string;+ durationMs: number;+}++interface SessionResult {+ session: string;+ stepsCompleted: number;+ totalDurationMs: number;+ duplicatedSteps: number;+ output: string[];+}++// ---------------------------------------------------------------------------+// Task definition+// ---------------------------------------------------------------------------++const taskSteps: TaskStep[] = [+ { id: 1, name: "Read project structure", durationMs: 50 },+ { id: 2, name: "Understand existing auth module", durationMs: 80 },+ { id: 3, name: "Design new search endpoint", durationMs: 60 },+ { id: 4, name: "Implement search endpoint", durationMs: 100 },+ { id: 5, name: "Write integration tests", durationMs: 70 },+ { id: 6, name: "Update documentation", durationMs: 40 },+];++// ---------------------------------------------------------------------------+// Simulated session executor+// ---------------------------------------------------------------------------++/** Simulate a session doing work. */+function runSession(+ sessionName: string,+ startStep: number,+ endStep: number+): SessionResult {+ const output: string[] = [];+ let totalDuration = 0;++ for (let i = startStep; i <= endStep; i++) {+ const step = taskSteps.find((s) => s.id === i)!;+ totalDuration += step.durationMs;+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);+ }++ return {+ session: sessionName,+ stepsCompleted: endStep - startStep + 1,+ totalDurationMs: totalDuration,+ duplicatedSteps: 0,+ output,+ };+}++// ---------------------------------------------------------------------------+// Run 1: No handoff file+// ---------------------------------------------------------------------------++function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 before timing out+ const sessionA = runSession("Session A", 1, 3);++ // Session B has no context, starts from scratch+ const sessionB = runSession("Session B", 1, 6);+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Run 2: With handoff file+// ---------------------------------------------------------------------------++function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {+ // Session A does steps 1-3 and writes a handoff file+ const sessionA = runSession("Session A", 1, 3);++ // Session B reads handoff, starts from step 4+ const sessionB = runSession("Session B", 4, 6);+ sessionB.duplicatedSteps = 0;++ return { sessionA, sessionB };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {+ console.log("\n" + "=".repeat(80));+ console.log(` ${title}`);+ console.log("=".repeat(80));++ console.log("\n Session A output:");+ for (const line of result.sessionA.output) {+ console.log(line);+ }++ console.log("\n Session B output:");+ for (const line of result.sessionB.output) {+ console.log(line);+ }++ console.log("\n Session B notes:");+ if (result.sessionB.duplicatedSteps > 0) {+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);+ } else {+ console.log(" - Read handoff file, continued from step 4");+ console.log(" - No duplicate work performed");+ }+}++function printComparison(): void {+ const noHandoff = simulateNoHandoff();+ const withHandoff = simulateWithHandoff();++ printRun("RUN 1: NO HANDOFF FILE", noHandoff);+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);++ // Comparison table+ console.log("\n" + "=".repeat(80));+ console.log(" COMPARISON TABLE");+ console.log("=".repeat(80) + "\n");++ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;+ console.log(header);+ console.log(sep);++ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;++ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);++ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");+}++printComparison();diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdnew file mode 100644index 0000000..a3fc2a7--- /dev/null+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -0,0 +1,180 @@+[English Version →](../../../en/lectures/lecture-05-why-long-running-tasks-lose-continuity/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)+> 實戰練習:[Project 03. 讓 agent 關掉再打開還能接著幹](./../../projects/project-03-multi-session-continuity/index.md)++# 第五講. 讓跨會話的任務保持上下文連續++你讓 Claude Code 幫你實現一個完整的功能,它跑了 30 分鐘,做了大部分工作,但上下文快滿了。你開個新會話繼續,然後發現:它不記得上次做了什麼決策、為什麼選了方案 A 而不是方案 B、哪些檔案已經改過、測試跑到什麼狀態了。它得花 15 分鐘重新探索一遍項目,而且可能跟上次的做法不一致。++想象一下,如果你是一個工匠,每天早上醒來都不記得昨天幹了什麼。你得重新認識整個工地——哪面牆砌了一半、為什麼用的是紅磚而不是青磚、水電管道走到哪了。更糟的是,你可能會把昨天已經裝好的窗戶拆了重來,因為你不記得它已經裝過了。++這就是 AI coding agent 在跨會話任務中面對的困境。本節課講為什麼 agent 會"斷片",以及如何通過結構化的狀態持久化讓它像一個每天堅持寫日記的工匠——雖然還是會失憶,但日記本裡記著一切。++## 上下文窗口:不是無限的++上下文窗口是有限的。這不是一個可以通過模型升級解決的問題——即使窗口大小增長到 1M tokens,複雜任務依然會用完。因為 agent 不只是在生成代碼,它還要理解代碼庫、跟蹤自己的決策歷史、處理工具輸出、維護對話上下文。這些信息加起來增長得比窗口擴容快得多。++更深層的問題:agent 產生的信息不是均勻重要的。中間推理步驟包含決策的"為什麼"——為什麼選了方案 A 而不是方案 B,為什麼用了這個庫而不是那個庫,為什麼跳過了某個優化。最終輸出只包含"是什麼"——代碼本身。壓縮策略通常保留後者但丟了前者。下一個會話看到代碼但不知道為什麼這麼寫,可能會"優化"掉一個有意為之的設計決策。++Anthropic 在他們的長運行 agent 研究中發現了一個很有意思的現象:當 agent 感覺上下文快滿了,它們會表現出一種"過早收斂"的行為——匆忙結束當前工作,跳過驗證步驟,或者選一個簡單的方案而不是最優方案。這就像你考試時發現時間快到了,趕緊隨便選幾個選擇題一樣。Anthropic 把這叫"上下文焦慮"。++## 會話連續性流程++沒有連續性工件的時候,每個新會話都是一場災難:++```mermaid+flowchart LR+ S1["會話 1<br/>功能做到一半"] --> End1["上下文快满了<br/>會話結束"]+ End1 --> S2["會話 2 重新開始"]+ S2 --> Guess["重新讀目录、重跑測試、<br/>猜上次為什么這么寫"]+ Guess --> Drift["程式碼會重复改<br/>恢复速度也很慢"]+```++有連續性工件的時候,新會話能快速接上:++```mermaid+flowchart LR+ Work["會話 1 的工作"] --> Progress["PROGRESS.md<br/>已完成 / 进行中 / 下一步"]+ Work --> Decisions["DECISIONS.md<br/>為什么這样做"]+ Work --> Verify["驗證記錄<br/>哪些測試通過或失敗"]+ Work --> Commit["Git 檢查点<br/>当前倉庫狀態"]++ Progress --> Rebuild["會話 2 重建"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["新會話能很快接上"]+```++## 核心概念++- **上下文窗口是有限的**:不管模型吹多大的窗口(128K、200K、1M),長任務總會用完。用完之後要麼壓縮(丟信息),要麼重置(開新會話)。兩種方式都會丟東西。+- **連續性工件**:持久化的狀態檔案,讓新會話能無歧義地恢復到上次離開的地方。最基本的形式:進度日誌 + 驗證記錄 + 下一步行動。就是那個工匠的日記本。+- **重建成本**:新會話恢復到可執行狀態所需的時間。好的 harness 能把重建成本從 15 分鐘壓到 3 分鐘。+- **漂移(Drift)**:agent 的理解跟代碼倉庫實際狀態之間的偏差。每次會話邊界都會引入漂移,不加控制會越漂越遠。+- **上下文焦慮**:Anthropic 觀察到的現象——agent 在接近上下文限制時表現異常,過早結束任務以避免信息丟失。是一種非理性的資源焦慮。+- **壓縮 vs 重置**:壓縮是在同一個會話裡把上下文摘要化(保留"是什麼",可能丟了"為什麼");重置是開新會話從持久化狀態重建(乾淨但依賴工件完備性)。++## 連續性斷了以後會發生什麼++上個會話花了很多上下文預算分析了三種方案的優劣,最終選了方案 B。這個會話的 agent 不知道這個分析過程,可能基於不完整的信息重新做了決策——而且可能選了方案 A。就像那個失憶的工匠不記得為什麼選了紅磚,今天看著覺得青磚更好看,就把昨天的牆拆了重砌。++更要命的是重複勞動。Agent 不確定某項工作是否已完成,重新做了一遍。或者更糟——做了一半發現跟已有的實現衝突,需要返工。工地上不能兩撥人同時砌同一面牆——但在沒有進度記錄的情況下,新來的人完全不知道這面牆已經有人在砌了。++幾個會話累積下來,實現方向可能已經悄悄偏離了原始需求。每個新會話對項目目標的理解都略有偏差,就像傳話遊戲——經過十個人傳話,"幫我買杯咖啡"可能變成了"幫我買個咖啡機"。++還有驗證缺口。上個會話的驗證結果(哪些測試通過、哪些失敗、為什麼失敗)沒有記錄,新會話得重新跑一遍驗證才能瞭解當前狀態。每次都重新診斷,每次都浪費寶貴的上下文。++OpenAI 和 Anthropic 都在他們的文檔裡強調了結構化狀態持久化的重要性。OpenAI 的 harness engineering 文章把倉庫當作"操作記錄"——每次操作的結果都應該在倉庫裡留下可追溯的痕跡。Anthropic 的 long-running agents 文檔則更具體地建議使用"交接檔案"——包含當前狀態、已知問題和下一步行動的結構化文檔。++## 給失憶工匠的日記本++核心思路:**把 agent 當成一個會失憶的超級工程師來管理。** 每次它要"下班"之前,必須把關鍵信息寫下來,讓下一個"接班"的 agent 能快速上手。++**工具 1:進度檔案(PROGRESS.md)**。這是最基本的連續性工件——日記本的核心部分:++```markdown+# 專案進度++## 当前狀態+- 最新 commit: abc1234 (feat: add user preferences endpoint)+- 測試狀態: 42/43 通過 (test_pagination_edge_case 失敗)+- Lint: 通過++## 已完成+- [x] 使用者模型和資料庫迁移+- [x] 基础 CRUD 端点+- [x] 認證中间件集成++## 进行中+- [ ] 分页功能 (90% - 邊界条件測試失敗)++## 已知問題+- test_pagination_edge_case 在空結果集時返回 500+- 需要确認是否要在列表中包含已删除使用者++## 下一步+1. 修復分页邊界条件 bug+2. 添加"是否包含已删除使用者"的查询参數+3. 更新 API 文檔+```++**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文檔,只需要"什麼決策、為什麼、什麼時候做的"——這是日記本裡的備忘:++```markdown+# 設計决策++## 2024-01-15: 使用 Redis 缓存使用者偏好+- 原因: 讀取频率高(每次 API 調用都需要),數據量小+- 否决方案: 用 PostgreSQL 物化视图(變更频率高,物化视图維護成本不劃算)+- 约束: 缓存 TTL 设為 5 分钟,寫入時主動失效+```++**工具 3:git 提交作為檢查點。** 每完成一個原子工作單元就提交。commit message 要說清楚做了什麼和為什麼。這是免費的、自動版本化的狀態快照。++**工具 4:init.sh 或 harness 的初始化流程。** 在 `AGENTS.md` 裡寫明每天"上班"和"下班"的流程:++```markdown+## 每次會話開始時(上班打卡)+1. 讀 PROGRESS.md 了解当前狀態+2. 讀 DECISIONS.md 了解重要决策+3. 跑 make check 确認倉庫處于一致狀態+4. 從 PROGRESS.md 的"下一步"部分继續工作++## 每次會話結束前(下班打卡)+1. 更新 PROGRESS.md+2. 跑 make check 确認一致狀態+3. 提交所有已完成的工作+```++**混合策略**:不需要每次都重置上下文。短任務(30 分鐘以內)可以在同一個會話裡完成。長任務(跨會話)必須用進度檔案和決策日誌來維持連續性。判斷標準:如果任務需要的上下文超過窗口的 60%,就開始準備交接。++### 上下文焦慮的深層分析++Anthropic 在 2026 年 3 月發佈的研究進一步揭示了上下文焦慮的具體表現:在 Sonnet 4.5 上,當上下文接近窗口限制時,agent 會表現出強烈的"過早收斂"行為。這就像考試時發現時間快到了,趕緊隨便填選擇題。++針對這個現象,有兩種策略:++**壓縮(Compaction)**:在同一個會話裡把早期對話摘要化。優點是保留連續性,agent 能看到"是什麼"。缺點是"為什麼"經常在摘要中丟失——為什麼選了方案 B 而非 A,為什麼跳過了某個優化。更關鍵的是,壓縮並不能消除上下文焦慮——agent 知道上下文曾經很大,心理上仍然傾向於加速收尾。++**重置(Context Reset)**:完全清空上下文,開一個新會話,從持久化工件重建。優點是乾淨的心理狀態——新會話沒有"我快沒時間了"的焦慮。缺點是依賴交接工件的完備性。如果日記本裡漏了關鍵信息,新會話可能在錯誤方向上浪費時間。++Anthropic 的實際數據:對於 Sonnet 4.5,上下文焦慮足夠嚴重,以至於壓縮單獨不夠用,上下文重置成為 harness 設計的關鍵組件。但對於 Opus 4.5,這種行為大幅減弱,可以不依賴重置而靠壓縮管理上下文。這意味著:**harness 設計需要對目標模型有具體的理解,而不是套用通用範本。**++> 來源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## 實際案例++一個 agent 被要求實現一個帶用戶認證的博客系統,12 個功能點,預計需要 5 個會話。++**沒有日記本的基線**:會話 1 實現了用戶模型和基礎路由。會話 2 開始時,agent 不記得認證中間件的接口約定,花了約 15 分鐘推斷上次的設計意圖。到會話 3,累積漂移導致 agent 開始重複已實現的功能。到會話 5,倉庫有大量冗餘代碼,但核心認證功能仍未通過端到端測試。12 個功能點只完成了 7 個,其中 3 個有隱含的正確性問題。就像那個沒寫日記的工匠——到了第五天,工地上一團亂,有些牆砌了兩遍,有些該砌的根本沒砌。++**有日記本的對照**:使用進度檔案、決策日誌、驗證記錄和 git 檢查點。每個會話結束時自動更新狀態報告。會話 2 的重建成本降到約 3 分鐘。到會話 5,所有 12 個功能點完成且通過驗證。++定量對比:重建時間減少約 78%,功能完成率從 58% 提升到 100%,隱含缺陷率從 43% 降到 8%。工匠還是那個會失憶的工匠,但有了日記本,他的每一天都從昨天停下的地方開始,而不是從零開始。++## 關鍵要點++- 上下文窗口是有限的資源。長任務一定會跨會話,跨會話一定會丟信息——這就像工匠每天都會失憶一樣,是客觀現實。+- 解決方案不是更大的窗口,而是更好的狀態持久化。進度檔案 + 決策日誌 + git 檢查點——給失憶的工匠一個靠譜的日記本。+- 把 agent 當成會失憶的工程師來管理:每次"下班"前寫清楚做了什麼、為什麼、下一步做什麼。+- 重建成本是關鍵指標。好的 harness 應該讓新會話在 3 分鐘內恢復到可執行狀態。+- 混合策略:短任務在會話內完成,長任務用結構化工件維持連續性。++## 延伸閱讀++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)++## 練習++1. **連續性損耗度量**:選一個需要至少 3 個會話的開發任務。不提供任何連續性工件,在每個會話開始時記錄 agent 花了多少上下文來"搞清楚上次做了什麼"。會話結束後,創建進度檔案,讓下一個會話從進度檔案開始。對比有進度檔案和沒有時的重建成本。++2. **交接範本設計**:設計一個最小化的交接範本,包含四個字段:倉庫狀態(commit hash)、運行時狀態(測試通過率)、阻塞項、下一步行動。讓一個全新的 agent 會話只憑這個範本恢復項目狀態,記錄恢復過程中出現的歧義點,迭代改進範本。++3. **混合策略實驗**:在一個包含 5 個會話的開發任務中,對比三種策略:(a) 每次都開全新會話 + 進度檔案,(b) 在同一個會話裡儘可能多做(上下文壓縮),(c) 混合策略(短任務在會話內,長任務跨會話 + 進度檔案)。對比重建時間、功能完成率和決策一致性。diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdnew file mode 100644index 0000000..dee67ba--- /dev/null+++ b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md@@ -0,0 +1,8 @@+# 第 06 講的程式碼++此資料夾用於以下範例:++- 初始化輸出+- init 腳本+- 進度檔案+- 首次執行腳手架diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.tsnew file mode 100644index 0000000..52dcd98--- /dev/null+++ b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts@@ -0,0 +1,296 @@+/**+ * init-check.ts+ *+ * Programmatically checks initialization prerequisites:+ * - Node.js version+ * - Dependencies installed (node_modules exists)+ * - Data directory exists+ * - Config files present+ *+ * Simulates running with and without an explicit init phase,+ * showing how missing prerequisites cause silent failures later.+ *+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";+import * as childProcess from "node:child_process";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface CheckItem {+ name: string;+ category: string;+ check: () => { pass: boolean; detail: string };+ impactIfMissing: string;+}++interface CheckResult {+ name: string;+ category: string;+ passed: boolean;+ detail: string;+ impactIfMissing: string;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++function createChecks(targetDir: string): CheckItem[] {+ return [+ {+ name: "Node.js version >= 18",+ category: "Runtime",+ check: () => {+ try {+ const version = process.version; // e.g. "v20.11.0"+ const major = parseInt(version.replace("v", "").split(".")[0], 10);+ return {+ pass: major >= 18,+ detail: `Detected: ${version} (need >= v18)`,+ };+ } catch {+ return { pass: false, detail: "Could not detect Node.js version" };+ }+ },+ impactIfMissing: "TypeScript features and built-in APIs unavailable",+ },+ {+ name: "package.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "package.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found in target directory",+ };+ },+ impactIfMissing: "Cannot install dependencies or run scripts",+ },+ {+ name: "Dependencies installed (node_modules)",+ category: "Dependencies",+ check: () => {+ const p = path.join(targetDir, "node_modules");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",+ };+ },+ impactIfMissing: "All imports fail at runtime",+ },+ {+ name: "TypeScript available",+ category: "Toolchain",+ check: () => {+ try {+ const result = childProcess.execSync("npx tsc --version", {+ encoding: "utf-8",+ timeout: 10000,+ stdio: ["pipe", "pipe", "pipe"],+ }).trim();+ return { pass: true, detail: `Detected: ${result}` };+ } catch {+ return { pass: false, detail: "TypeScript not available via npx" };+ }+ },+ impactIfMissing: "Cannot compile TypeScript files",+ },+ {+ name: "tsconfig.json exists",+ category: "Config",+ check: () => {+ const p = path.join(targetDir, "tsconfig.json");+ const exists = fs.existsSync(p);+ return {+ pass: exists,+ detail: exists ? `Found: ${p}` : "Not found",+ };+ },+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",+ },+ {+ name: "Source directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["src", "lib", "app"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",+ };+ },+ impactIfMissing: "Agent cannot locate source files to modify",+ },+ {+ name: "Test directory exists",+ category: "Structure",+ check: () => {+ const candidates = ["test", "tests", "__tests__", "spec"];+ const found = candidates.filter((d) => {+ const p = path.join(targetDir, d);+ return fs.existsSync(p) && fs.statSync(p).isDirectory();+ });+ return {+ pass: found.length > 0,+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",+ };+ },+ impactIfMissing: "Agent cannot find or run existing tests",+ },+ {+ name: "Git repository initialized",+ category: "Version Control",+ check: () => {+ const gitDir = path.join(targetDir, ".git");+ const exists = fs.existsSync(gitDir);+ return {+ pass: exists,+ detail: exists ? "Git repository detected" : "No .git directory found",+ };+ },+ impactIfMissing: "No rollback capability, no change history",+ },+ ];+}++// ---------------------------------------------------------------------------+// Simulation: with and without init phase+// ---------------------------------------------------------------------------++interface SimResult {+ scenario: string;+ checksRun: boolean;+ failuresBeforeWork: number;+ workAttempted: boolean;+ workSucceeded: boolean;+ timeWastedMs: number;+}++function simulateWithoutInit(): SimResult {+ // Agent skips init, goes straight to work.+ // Encounters failures one at a time as it hits missing prerequisites.+ const checks = createChecks(process.cwd());+ let failures = 0;+ let timeWasted = 0;++ for (const check of checks) {+ const result = check.check();+ if (!result.pass) {+ failures++;+ timeWasted += 200; // Agent spends time discovering each missing piece+ }+ }++ return {+ scenario: "NO INIT PHASE",+ checksRun: false,+ failuresBeforeWork: 0, // Didn't check upfront+ workAttempted: true,+ workSucceeded: failures === 0,+ timeWastedMs: timeWasted,+ };+}++function simulateWithInit(): SimResult {+ // Agent runs init phase first, discovers all issues upfront.+ const checks = createChecks(process.cwd());+ let failures = 0;++ for (const check of checks) {+ if (!check.check().pass) {+ failures++;+ }+ }++ return {+ scenario: "WITH INIT PHASE",+ checksRun: true,+ failuresBeforeWork: failures,+ workAttempted: failures === 0,+ workSucceeded: failures === 0,+ timeWastedMs: 0,+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.cwd();+ console.log("\n" + "=".repeat(80));+ console.log(" INITIALIZATION PREREQUISITE CHECK");+ console.log("=".repeat(80));+ console.log(` Target: ${targetDir}\n`);++ const checks = createChecks(targetDir);+ const results: CheckResult[] = checks.map((c) => {+ const r = c.check();+ return {+ name: c.name,+ category: c.category,+ passed: r.pass,+ detail: r.detail,+ impactIfMissing: c.impactIfMissing,+ };+ });++ // Detailed report+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const status = r.passed ? "PASS" : "FAIL";+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);+ }++ const passCount = results.filter((r) => r.passed).length;+ const failCount = results.filter((r) => !r.passed).length;++ console.log("\n" + "-".repeat(80));+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);++ if (failCount > 0) {+ console.log("\n FAILED CHECKS -- Impact if not resolved:");+ for (const r of results.filter((r) => !r.passed)) {+ console.log(` - ${r.name}: ${r.impactIfMissing}`);+ }+ }++ // Comparison: with vs without init+ const noInit = simulateWithoutInit();+ const withInit = simulateWithInit();++ console.log("\n" + "=".repeat(80));+ console.log(" INIT PHASE COMPARISON");+ console.log("=".repeat(80) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);++ console.log("\n An explicit init phase catches problems before they waste time.\n");+}++run();diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.shnew file mode 100644index 0000000..2c6e1b0--- /dev/null+++ b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh@@ -0,0 +1,10 @@+#!/usr/bin/env bash+set -euo pipefail++echo "[init] installing dependencies"+npm install++echo "[init] starting the docs site is optional"+echo "[init] use npm run docs:dev for course docs"++echo "[init] project-specific startup would go here"diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.mdnew file mode 100644index 0000000..2a24acc--- /dev/null+++ b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md@@ -0,0 +1,7 @@+# 初始化輸出檢查清單++- 是否有標準的啟動指令?+- 是否有標準的驗證指令?+- 是否有第一份進度產物?+- 是否有穩定的首次 commit?+- 是否有可供後續執行使用的可見功能範圍?diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdnew file mode 100644index 0000000..a955893--- /dev/null+++ b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -0,0 +1,157 @@+[English Version →](../../../en/lectures/lecture-06-why-initialization-needs-its-own-phase/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)+> 實戰練習:[Project 03. 讓 agent 關掉再打開還能接著幹](./../../projects/project-03-multi-session-continuity/index.md)++# 第六講. 讓 agent 每次工作前先初始化++你開了一個新的 agent 會話,讓它"幫我加個搜索功能"。它上來就開始改代碼——精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現數據庫遷移腳本格式不對,又折騰了一會兒。最後搜索功能倒是加了,但整個會話的效率很低——大部分時間花在了"搞清楚這個項目怎麼運作"上,而不是寫搜索功能。++更好的做法是:在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、項目結構搞清楚。就像蓋房子——你不能邊打地基邊砌牆,不然牆砌到一半地基還沒幹,整棟樓都得推倒重來。先打地基,地基幹了,再砌牆,一氣呵成。++這節課講的就是為什麼初始化必須是獨立的階段,不能跟實現混在一起。++## 地基和牆:兩種完全不同的工作++初始化和實現的優化目標完全不同。實現階段的目標是:最大化已驗證功能的數量和質量。初始化階段的目標是:最大化後續所有實現的可靠性和效率。++當你把初始化和實現混在一起的時候,agent 面臨一個多目標優化問題——它要同時搭基礎設施和寫功能代碼。在沒有顯式優先級設定的情況下,agent 自然傾向於寫代碼(因為那是直接可見的產出),而犧牲基礎設施(因為它的價值只能在後續會話中體現)。這就像讓施工隊同時打地基和砌牆——他們大概率會急著砌牆,因為牆看得見、能交差。但地基沒打好的房子,後面出的問題是系統性的。++## 初始化生命週期++```mermaid+flowchart TB+ subgraph Wrong["混在一起的一次會話(錯誤)"]+ W1["一上來就開始做功能"] --> W2["做到一半才發现环境和測試缺口"]+ W2 --> W3["累积未经驗證的程式碼"]+ W3 --> W4["下個會話还得重新摸專案狀態"]+ end++ subgraph Right["獨立初始化阶段(正确)"]+ R1["會話 1:环境可執行"] --> R2["示例測試通過"]+ R2 --> R3["寫出啟動契约 + 任務清單"]+ R3 --> R4["提交干净檢查点"]+ R4 --> R5["後續會話直接開始做已準备好的任務"]+ end+```++## 混在一起做會怎樣++最直接的問題:地基打不牢。Agent 花了 80% 的精力寫功能代碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒創建。這些缺陷在第一個會話裡不明顯(因為 agent 還記得它做了什麼),但到第二個會話就暴露了——新 agent 不知道項目怎麼跑、怎麼測、做到哪了。地基不牢,地動山搖。++更隱蔽的代價是"未驗證的累積"——在測試框架配好之前寫的功能代碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實現。就像在地基沒幹的時候就開始貼瓷磚,等發現地面不平時,瓷磚全得撬掉重來。++上下文預算也在被浪費。初始化工作(配環境、配測試、理解項目結構)消耗了大量預算,留給實際功能實現的反而不夠了。結果第一個會話只完成了一半的功能,第二個會話還得從頭理解項目。預算花在了打地基上,但地基也沒打好——兩頭都沒佔著。++最容易被忽略的是隱式假設埋下的雷。Agent 在初始化過程中做的決策(用什麼測試框架、目錄怎麼組織、依賴怎麼管理)如果不顯式記錄下來,後續會話就可能做出矛盾的選擇。第一個施工隊用的是水泥地基,第二個施工隊不知道,往上面打了木樁——地基直接裂了。++Anthropic 在他們的長運行應用開發研究中明確建議把初始化和實現分離。他們的實驗數據:使用獨立初始化階段的項目,多會話場景中的功能完成率比混合方式高 31%。關鍵是——初始化階段投入的時間在後續 3-4 個會話中就能完全收回。地基打得越紮實,上面的樓蓋得越快。++OpenAI 的 Codex harness engineering 指南也強調"倉庫作為操作記錄"的原則——第一次運行就要建立清晰的操作結構,否則每次新會話都得重新推斷項目約定。++## 核心概念++- **初始化階段**:agent 生命週期中的第一個階段,不做功能實現,只建立後續所有實現階段的執行前提。輸出不是代碼,而是基礎設施。+- **自舉契約**:一個項目能被全新 agent 會話無歧義操作的條件——能啟動、能測試、能看進度、能接手下一步。四個條件缺一不可。+- **冷啟動 vs 熱啟動**:冷啟動是從空目錄開始,agent 要猜項目結構;熱啟動是從範本或已有項目開始,基礎設施已經就位。熱啟動的效果遠好於冷啟動——就像在有水電的工地上開工,比在荒郊野嶺從頭搞起快得多。+- **交接就緒性**:項目在任何時刻都處於"可以被全新 agent 接手"的狀態。不需要口頭解釋,只看倉庫內容就能接著幹。+- **首次驗證時間**:從項目開始到第一個功能點通過驗證的時間。這是衡量初始化效率的核心指標。+- **下游可用性**:初始化質量的最佳衡量標準——後續會話不需要依賴隱式知識就能成功執行任務的比例。++## 怎麼做好初始化++**把初始化當作一個獨立的階段來執行。** 第一個會話只做初始化,不寫任何業務功能代碼。初始化的產出是:++**1. 可運行的環境。** 項目能啟動、依賴都裝好、沒有環境問題。地基澆好了,沒裂縫。++**2. 可驗證的測試框架。** 至少有一個示例測試能通過。這證明測試框架本身是配對的——就像地基上立了一根柱子,證明地基能承重。++**3. 自舉契約文檔。** 一個明確的文檔告訴後續會話:+```markdown+# 初始化契约++## 啟動命令+- 安装依赖:`make setup`+- 啟動開發服務器:`make dev`+- 執行測試:`make test`+- 完整驗證:`make check`++## 当前狀態+- 所有依赖已安装並锁定+- 測試框架已配置(Vitest + React Testing Library)+- 示例測試通過(1/1)+- Lint 规则已配置(ESLint + Prettier)++## 專案結構+- src/ — 源程式碼+- src/components/ — React 组件+- src/api/ — API 客户端+- tests/ — 測試檔案+```++**4. 任務分解。** 把整個項目拆成有序的任務列表,每個任務有明確的驗收標準:+```markdown+# 任務分解++## Task 1: 使用者認證基础+- 實作 JWT 認證中间件+- 添加登录/注册端点+- 验收標準:pytest tests/test_auth.py 全部通過++## Task 2: 使用者資料页面+- 實作使用者資料 CRUD+- 添加資料编辑表單+- 验收標準:pytest tests/test_profile.py 全部通過++## Task 3: 搜索功能+- ...+```++**5. Git 提交作為檢查點。** 初始化完成後提交一個乾淨的 checkpoint。後續所有工作都從這個 checkpoint 開始。++**熱啟動策略**:不要從空目錄開始。用一個項目範本(create-react-app、fastapi-template 等)預置好標準的目錄結構、依賴配置和測試框架。把通用的初始化步驟預置到範本裡,只留下項目特有的初始化工作。就像在有通水通電的工地上開工,比從荒郊野嶺開始強一萬倍。++**初始化的完成條件**:不是"寫了多少代碼",而是自舉契約的四個條件都滿足了——能啟動、能測試、能看進度、能接手下一步。用這個檢查清單驗收初始化:++```markdown+## 初始化验收清單+- [ ] `make setup` 從零開始能成功+- [ ] `make test` 至少有一個測試通過+- [ ] 新的 agent 會話能只看倉庫回答"怎么跑"和"怎么測"+- [ ] 任務分解檔案存在且有至少 3 個任務+- [ ] 所有内容已提交到 git+```++## 實際案例++一個 React 前端項目的兩種初始化方式對比:++**混合方式(邊打地基邊砌牆)**:agent 在第一個會話中同時做了項目腳手架創建和首個功能實現。會話結束時,倉庫有可運行的代碼,但:沒有顯式的啟動/測試命令文檔、沒有進度跟蹤檔案、沒有任務分解。第二個會話花了約 20 分鐘推斷項目結構、測試框架和構建流程——就像新來的施工隊看著一片工地,不知道地基打到什麼程度、水電管道走到哪了,只能一個個挖開來看。++**獨立初始化(先打地基)**:第一個會話只做初始化——用項目範本創建目錄結構、配置測試框架(Vitest + React Testing Library)、寫一個示例測試並驗證通過、創建自舉契約文檔和任務分解檔案、提交初始檢查點。第二個會話的重建時間不到 3 分鐘,直接從任務列表開始工作——施工隊來了,看了一眼施工圖就知道從哪裡接著幹。++整個項目週期對比:混合方式的總重建時間(跨所有會話)比獨立初始化多約 60%。獨立初始化多花的那 20 分鐘在後續會話中被成倍收回。就像地基打得紮實,上面蓋樓的效率反而更高——慢即是快。++## 關鍵要點++- 初始化和實現的優化目標不同,混在一起只會互相拖後腿。先打地基,再砌牆。+- 初始化的產出不是代碼,是基礎設施:可運行的環境、可驗證的測試、自舉契約、任務分解。+- 用"自舉契約"的四個條件驗收初始化:能啟動、能測試、能看進度、能接手下一步。+- 熱啟動優於冷啟動。用項目範本預置標準化的基礎設施。+- 初始化投入的時間會在後續 3-4 個會話中完全收回。這不是額外的成本,是前期投資——地基打得越紮實,樓蓋得越快。++## 延伸閱讀++- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)++## 練習++1. **自舉契約設計**:為一個你正在開發的項目寫一個完整的自舉契約。然後開一個全新的 agent 會話,只給它看倉庫內容(不給任何口頭上下文),讓它嘗試啟動項目、跑測試、瞭解當前進度。記錄它遇到的問題——每個問題都對應自舉契約中缺失的一個條款。++2. **對比實驗**:選一箇中等複雜度的新項目。方式 A:讓 agent 初始化和首次實現同時做。方式 B:先花一個會話做獨立初始化,第二個會話開始實現。在 4 個會話後對比:首次驗證時間、重建成本、功能完成率。++3. **初始化驗收清單**:為你的項目設計一個初始化驗收清單。讓一個全新的 agent 會話執行清單上的每一項,記錄哪些項通過了、哪些沒通過。沒通過的項就是你的 harness 需要補強的地方。diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdnew file mode 100644index 0000000..a672da7--- /dev/null+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md@@ -0,0 +1,8 @@+# 第 07 講的程式碼++此資料夾用於以下範例:++- 一次性的失敗案例+- 過大的任務提示+- 漸進式任務塑造+- 結構化功能範圍diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.mdnew file mode 100644index 0000000..3a2709a--- /dev/null+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md@@ -0,0 +1,6 @@+# 下一個任務模板++- 目前最高優先順序的功能:+- 為什麼這個功能是下一個:+- 什麼算作通過:+- 在此步驟中不得更改什麼:diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdnew file mode 100644index 0000000..55ee28c--- /dev/null+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -0,0 +1,17 @@+# 範圍範例++任務:++- 為 Electron 知識庫應用程式新增索引功能++不良的範圍定義:++- 「實作索引功能」++較好的範圍定義:++- 解析已匯入的文件+- 將文件分割為區塊+- 持久化區塊詮釋資料+- 在 UI 中顯示索引狀態+- 新增重新索引操作diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.tsnew file mode 100644index 0000000..c587a1d--- /dev/null+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts@@ -0,0 +1,151 @@+/**+ * scope-tracker.ts+ *+ * Reads a feature list and a change log. Enforces single-active-feature+ * policy. Given a log of changes, flags any changes outside the active+ * feature scope. Demonstrates how scope drift happens and how the tracker+ * catches it.+ *+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Feature {+ id: string;+ name: string;+ status: "active" | "pending" | "done";+}++interface ChangeLogEntry {+ step: number;+ file: string;+ description: string;+ featureId: string; // The feature this change claims to belong to+}++// ---------------------------------------------------------------------------+// Sample data+// ---------------------------------------------------------------------------++const features: Feature[] = [+ { id: "F-001", name: "Search endpoint", status: "active" },+ { id: "F-002", name: "Delete endpoint", status: "pending" },+ { id: "F-003", name: "Rate limiting", status: "pending" },+ { id: "F-004", name: "User dashboard", status: "pending" },+];++// A realistic change log where the agent gradually drifts from the active feature+const changeLog: ChangeLogEntry[] = [+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },+];++// ---------------------------------------------------------------------------+// Scope tracker+// ---------------------------------------------------------------------------++interface ScopeCheckResult {+ step: number;+ file: string;+ description: string;+ featureId: string;+ inScope: boolean;+ activeFeature: string;+}++function trackScope(+ featureList: Feature[],+ changes: ChangeLogEntry[]+): ScopeCheckResult[] {+ const activeFeatures = featureList.filter((f) => f.status === "active");+ const activeIds = new Set(activeFeatures.map((f) => f.id));+ const activeNames = activeFeatures.map((f) => f.name).join(", ");++ return changes.map((change) => ({+ step: change.step,+ file: change.file,+ description: change.description,+ featureId: change.featureId,+ inScope: activeIds.has(change.featureId),+ activeFeature: activeNames,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const results = trackScope(features, changeLog);++ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");+ console.log("=".repeat(100));++ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));++ // Detailed change log+ console.log("\n" + "-".repeat(100));+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;+ console.log(header);+ console.log(sep);++ let inScopeCount = 0;+ let driftCount = 0;++ for (const r of results) {+ const scopeLabel = r.inScope ? "OK" : "DRIFT";+ if (r.inScope) inScopeCount++;+ else driftCount++;++ const marker = r.inScope ? " " : ">>";+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SCOPE DRIFT SUMMARY");+ console.log("=".repeat(100) + "\n");++ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;+ console.log(sHeader);+ console.log(sSep);+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);++ // Drift detail+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];+ if (driftFeatures.length > 0) {+ console.log("\n DRIFTED FEATURES:");+ for (const fid of driftFeatures) {+ const feat = features.find((f) => f.id === fid);+ const driftChanges = results.filter((r) => r.featureId === fid);+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);+ }+ }++ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");+}++run();diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdnew file mode 100644index 0000000..2bc1eaf--- /dev/null+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -0,0 +1,134 @@+[English Version →](../../../en/lectures/lecture-07-why-agents-overreach-and-under-finish/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)+> 實戰練習:[Project 04. 用運行反饋修正 agent 的行為](./../../projects/project-04-incremental-indexing/index.md)++# 第七講. 給 agent 劃清每次任務的邊界++你讓 Claude Code "給這個項目加上用戶認證功能",結果它同時開始改數據庫 schema、寫路由、改前端組件、還順手重構了錯誤處理中間件。兩個小時後你一看——12 個檔案被修改,800 行新代碼,但沒有一個功能是端到端跑通的。++貪多嚼不爛,這句話放到 AI agent 身上格外貼切。Agent 天生就有"多做一點"的衝動——看到相關的事情就順手一起做了,和那種在超市本來只打算買瓶醬油、結果推著滿滿一車出來的人一個德行。問題是,人類買了太多東西最多浪費錢,agent 同時做太多事情則是每一件都做不好。++Anthropic 在 "Effective harnesses for long-running agents" 工程博客中明確指出:當提示太寬泛時,agent 傾向於"同時啟動多件事"而非"先做完一件事"。OpenAI 在 Codex 工程實踐中也發現,沒有顯式範圍控制的任務,完成率會暴跌。這不是模型的問題——是你沒有在 harness 裡給它劃清邊界。++## 注意力是有限的資源++這不是比喻,是數學。假設 agent 的上下文容量為 C,同時激活 k 個任務,每個任務平均獲得 C/k 的推理資源。當 C/k 低於完成單個任務所需的最小閾值時,所有任務都做不完。這就像你的胃就那麼大——同時塞十個包子進去,不是一個都消化不了,而是十個都消化不良。++Claude Code 的真實行為很說明問題。你讓它"添加用戶註冊功能",它很可能這樣做:++1. 創建 User model+2. 寫註冊路由+3. 發現需要郵箱驗證,於是加郵件服務+4. 看到密碼需要加密,於是引入 bcrypt+5. 注意到錯誤處理不統一,於是重構全局錯誤中間件+6. 看到測試檔案結構不清晰,於是重組目錄結構++6 步之後,每一個都是半成品。沒有端到端驗證,代碼之間耦合複雜,下一個會話來接手時會一臉懵。就像一個人同時炒六道菜,每道菜都下了鍋但沒有一道出鍋——全糊了。++Anthropic 的實驗數據直接支持這一點:使用"小下一步"策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的代碼行數和實際完成的功能數量呈弱負相關——寫得越多,完成得越少。貪多嚼不爛,數據為證。++## WIP=1 工作流++```mermaid+flowchart LR+ Queue["功能队列"] --> Pick["只選一個任務"]+ Pick --> Active["仅允许一個 active"]+ Active --> Verify["跑端到端驗證"]+ Verify -->|通過| Commit["提交並解锁下一個任務"]+ Verify -->|失敗| Active+ Commit --> Queue+```++```mermaid+flowchart TB+ Budget["可用推理预算 = C"] --> One["WIP = 1<br/>每個任務拿到 C / 1"]+ Budget --> Many["WIP = 5<br/>每個任務只有 C / 5"]++ One --> Finish["一個功能进入 passing"]+ Many --> Partial["五個功能都只做了一半"]+ Partial --> VCR["已驗證完成率低<br/>下一會話返工高"]+```++## 核心概念++- **過度延伸(Overreach)**:agent 在一次會話中激活的任務數量超過最優值。它不是主觀判斷,而是可量化的——同時做 5 個功能但 0 個跑通,就是 overreach。+- **不足完成(Under-finish)**:已啟動的任務中,通過端到端驗證的比例低於閾值。寫了代碼但沒跑通測試,就是 under-finish。+- **WIP 限制(Work-in-Progress Limit)**:來自 Kanban 方法論。核心思想:限制同時在進行的任務數量。對於 agent,WIP=1 是最安全的默認值——做完一個再做下一個。就像自助餐廳不要一次拿太多盤子,吃完一盤再去拿下一盤。+- **完成證據(Completion Evidence)**:一個任務從"進行中"變成"已完成"必須滿足的可驗證條件。沒有這個,agent 會用"代碼看起來沒問題"代替"行為通過測試"。+- **範圍表面(Scope Surface)**:一個 DAG 結構,每個節點是一個工作單元,邊是依賴關係。狀態只有四種:未開始、進行中、阻塞、已通過。+- **完成壓力(Completion Pressure)**:harness 通過 WIP 限制和完成證據要求共同產生的約束力,迫使 agent 先完成當前任務再開始新任務。++## Overreach 和 Under-finish 是一對難兄難弟++這兩個問題不是獨立的,而是互相加劇。overreach 導致注意力分散,注意力分散導致 under-finish,under-finish 留下的半成品代碼又增加了系統複雜度,進一步導致下一個任務的 overreach。惡性循環。++用 Kanban 的語言說:Little 法則告訴我們 L = lambda * W。如果在製品數量 L 過大(同時做太多事),每個任務的前置時間 W 必然增加。對於 agent 來說,這意味著每個功能從開始到驗證通過的時間被拉長,失敗概率被放大。++這在人類世界也是老問題了——Steve McConnell 在《Rapid Development》中記錄,範圍蔓延是項目失敗的首要原因。但人類至少有"我已經做得夠多了"的直覺,agent 完全沒有。生成下一個想法的成本對模型來說太低了——寫一行"順便把這個也改了"幾乎不消耗額外 token,但每個額外的修改都會稀釋 agent 的注意力。就像在自助餐廳裡,每多拿一個盤子的邊際成本幾乎為零,但你的胃只有那麼大。++## 怎麼做才對++### 1. 強制 WIP=1++這是最直接有效的方法。在你的 harness 裡,明確告訴 agent:**任何時刻只允許一個任務處於"進行中"狀態。** 在 Claude Code 的 CLAUDE.md 或 Codex 的 AGENTS.md 裡寫:++```+## 工作规则+- 每次只做一個功能点+- 当前功能点端到端驗證通過後,才能開始下一個+- 不要在實作功能 A 時"顺便"重构功能 B+```++就像吃自助餐——一次只拿一盤,吃完再去拿。++### 2. 給每個任務定義顯式的完成證據++完成不是"代碼寫完了",而是"行為驗證通過了"。在你的功能列表裡,每個條目都要有驗證命令:++```+F01: 使用者注册+ 驗證: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201+ 狀態: passing+```++### 3. 把範圍表面外部化++用一個機器可讀的檔案(JSON 或 Markdown)記錄所有任務的狀態。任何新會話都能直接讀這個檔案,知道:哪個任務在做?什麼行為算完成?已經通過了什麼驗證?++### 4. 監控驗證完成率++harness 應該持續跟蹤 VCR(Verified Completion Rate)= 已通過驗證的任務數 / 已啟動的任務數。VCR < 1.0 時,阻止新任務啟動。++## 實際案例++一個 8 個功能點的 REST API 項目,兩種策略對比:++**自助餐模式(無約束)**:agent 在第一個會話同時啟動 5 個功能。產出約 800 行代碼,涉及 12 個檔案。端到端測試通過率只有 20%——只有用戶註冊跑通了。其餘 4 個功能:數據庫 schema 建了但缺驗證邏輯,路由定義了但返回格式錯誤。就像一個人同時炒六道菜,只有一道勉強能吃。到第 3 個會話結束,8 個功能只完成 3 個。++**單盤模式(WIP=1)**:agent 在第一個會話只做用戶註冊。產出約 200 行代碼,涉及 4 個檔案。端到端測試 100% 通過。提交乾淨的、已驗證的實現。到第 4 個會話結束,8 個功能完成 7 個(第 8 個因外部依賴被阻塞)。++結果:總代碼量更少(800 行 vs 1200 行),但有效代碼更多。完成率 87.5% vs 37.5%。一口一口吃,反而吃得最多。++## 關鍵要點++- **WIP=1 是 agent harness 的默認安全設置**——做完一個再做下一個,不要試圖並行。一口吃不成胖子。+- **完成證據必須是可執行的**——"代碼看起來沒問題"不算完成,"curl 返回 201"才算。+- **範圍表面必須外部化為檔案**——不能只在對話裡說,必須在倉庫裡有機器可讀的記錄。+- **overreach 和 under-finish 是共生問題**——解決一個就解決了另一個。+- **"少做但做完"永遠優於"多做但做半"**——agent 代碼行數和功能完成率呈負相關。質量永遠比數量重要。++## 延伸閱讀++- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropic 工程博客,詳細論述了"小下一步"策略+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — OpenAI 對 harness 工程的完整論述+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — WIP 限制的經典來源+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — 範圍蔓延作為項目失敗首要原因的實證數據++## 練習++1. **任務原子化練習**:選一個寬泛需求(如"實現用戶管理系統"),把它拆成至少 5 個原子工作單元。每個單元寫清楚:(a) 單一行為描述,(b) 可執行的驗證命令,(c) 依賴關係。檢查是否滿足 WIP=1 的約束。++2. **對比實驗**:在同一個項目上跑兩次——一次不給約束,一次強制 WIP=1。比較:驗證完成率、總代碼行數、有效代碼比例。++3. **完成證據審計**:回顧一個最近的 agent 運行結果,把每個代碼變更分類為"已完成行為"、"未完成行為"或"腳手架"。給每個未完成行為補充缺失的驗證命令。diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..52d6a2b--- /dev/null+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,218 @@+/**+ * feature-list-validator.ts+ *+ * Reads a feature_list.json, validates its schema, and checks for features+ * marked "pass" without verification evidence. Outputs a structured report.+ * Can run against any project directory that has a feature_list.json.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]+ * (defaults to the directory containing this script)+ *+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Allow unknown fields for flexibility+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Schema validation+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entry ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Missing or invalid 'id' field`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Missing or invalid 'category' field`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Missing or invalid 'description' field`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' must be an array if present`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' must be a boolean if present`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Evidence validation+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Process feature list+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve target directory+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);+ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" FEATURE LIST VALIDATOR");+ console.log("=".repeat(90));+ console.log(` Reading: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(` ERROR: feature_list.json not found at ${filePath}`);+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");+ process.exit(1);+ }++ let entries: FeatureEntry[];+ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");+ process.exit(1);+ }++ // For demo purposes, also validate an extended test set+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "User can import a PDF document.",+ verification: ["Upload a PDF file", "Verify it appears in the document list"],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "System hallucination rate is below 5%.",+ verification: [], // Empty -- no evidence+ passes: true, // Marked as pass WITHOUT evidence+ },+ {+ id: "missing-fields",+ // Missing 'category' and 'description'+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Print report+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";+ const notes = r.markedPassWithoutEvidence+ ? "FLAGGED: passes without evidence!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";+ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`+ );+ }++ // Summary+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;+ const withEvidence = results.filter((r) => r.hasVerification).length;++ console.log("\n" + "-".repeat(90));+ console.log(" SUMMARY");+ console.log("-".repeat(90));+ console.log(` Total features: ${total}`);+ console.log(` Schema valid: ${schemaOk}/${total}`);+ console.log(` Marked as passing: ${passing}/${total}`);+ console.log(` With verification evidence: ${withEvidence}/${total}`);+ console.log(` Flagged (pass without evidence): ${flagged}`);++ if (flagged > 0) {+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);+ console.log(" These features need verification before they can be trusted.\n");+ } else {+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");+ }+}++run();diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..8b973e3--- /dev/null+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",+ "verification": [+ "Import a markdown document",+ "Open the Q&A panel",+ "Ask a question about known content",+ "Verify the answer is returned",+ "Verify one or more citations are displayed"+ ],+ "passes": false+ }+]diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdnew file mode 100644index 0000000..dde5693--- /dev/null+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -0,0 +1,8 @@+# 第 08 講的程式碼++此資料夾用於以下範例:++- 通過狀態閘門控制+- 端到端驗證+- 弱式與強式完成標準+- 評估迴圈範例diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdnew file mode 100644index 0000000..9a7fa68--- /dev/null+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -0,0 +1,8 @@+# 通過閘門策略++一個功能只有在以下條件滿足時,才能從 `passes: false` 變更為 `passes: true`:++- 預期的工作流程已被執行+- 成功的證據已被記錄+- 已測試的路徑中不存在阻礙性錯誤+- 實作未使應用程式處於損壞或不明確的狀態diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdnew file mode 100644index 0000000..6bd4ef7--- /dev/null+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -0,0 +1,142 @@+[English Version →](../../../en/lectures/lecture-08-why-feature-lists-are-harness-primitives/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> 實戰練習:[Project 04. 用運行反饋修正 agent 的行為](./../../projects/project-04-incremental-indexing/index.md)++# 第八講. 用功能清單約束 agent 該做什麼++你讓 agent 做一個電商網站,跑完之後它告訴你"做完了"。你打開代碼一看——用戶認證有了,但購物車的結算按鈕點了沒反應,支付流程根本沒接上。問題是:你從來沒告訴它"做完"的標準是什麼,所以它用自己的標準——"代碼寫了不少,看起來挺完整"。++功能清單(feature list)在很多人眼裡就是個備忘錄——寫下來怕忘了,寫完扔在一邊。但在 harness 的世界裡,功能清單不是給人看的備忘錄,而是整個 harness 的脊樑骨。調度器靠它選任務,驗證器靠它判完成,交接器靠它生成報告。脊樑骨斷了,全身都癱。++Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須是倉庫裡機器可讀的檔案,不能是對話裡的非結構化描述。++## Agent 不知道"做完"是什麼意思++Claude Code 和 Codex 都不會自動知道你心目中的"做完"是什麼意思。你說"加一個購物車功能",模型的理解可能是"寫一個 Cart 組件和 addToCart 方法"。而你的意思是"用戶能從瀏覽商品到下單支付完整走通"。++這個理解鴻溝在沒有功能清單的情況下會持續存在。agent 用自己的隱式標準判斷完成——通常是"代碼沒有明顯的語法錯誤"。而你需要的是端到端的行為驗證。就像你讓朋友幫你買菜,說"買點水果",他拎了一袋檸檬回來——他要的水果,你要的水果,不是一個水果。++看看這種常見的進度記錄:++```+做了使用者認證、购物车基本完成了、还需要做支付+```++新的 agent 會話看到這個記錄,能回答以下問題嗎?"基本完成"意味著什麼?購物車通過了哪些測試?支付的阻塞條件是什麼?答案都是"不知道"。就像你看病時跟醫生說"我肚子疼,最近還行",醫生能開出什麼藥來?++結果是:新會話花 20 分鐘推斷項目狀態,最終可能重複實現已完成的功能。Anthropic 的工程實踐數據表明,好的進度記錄可以減少 60-80% 的會話啟動診斷時間。++## 功能狀態機++```mermaid+flowchart LR+ Feature["一行功能项"] --> Behavior["行為<br/>例如:POST /cart/items 返回 201"]+ Feature --> Check["驗證命令<br/>具体要跑什么檢查"]+ Feature --> State["狀態<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["三列都齐了<br/>這行功能项才能用"]+ Check --> Complete+ State --> Complete+```++```mermaid+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["選下一個 not_started"]+ Scheduler --> Agent["agent 只做這一项"]+ Agent --> Verifier["跑這一项自己的驗證命令"]+ Verifier -->|通過| Passing["寫成 passing<br/>並补上驗證證據"]+ Verifier -->|失敗| Active["继續保持 active"]+ Verifier -->|依赖問題| Blocked["標成 blocked"]+ Passing --> Handoff["更新交接說明<br/>和当前進度"]+ Active --> Agent+```++## 核心概念++- **功能清單是 harness 原語**:它不是"可選的規劃工具",而是其他所有 harness 組件依賴的基礎數據結構。就像數據庫裡的表結構——你不能說"要不我們省掉主鍵吧",省掉了整個系統就散架了。+- **三元組結構**:每個功能項是 `(行為描述, 驗證命令, 当前狀態)` 的三元組。缺了任何一項,這個功能項就不完整。行為描述告訴 agent 做什麼,驗證命令告訴它怎麼算做完,狀態告訴它現在到哪了。+- **狀態機模型**:每個功能項有四種狀態——`not_started`、`active`、`blocked`、`passing`。狀態轉移由 harness 控制,不是 agent 想改就能改。+- **通過狀態門控**:功能從 `active` 變成 `passing` 的唯一方式是驗證命令執行成功。這是不可逆的——`passing` 了就不能退回去。就像考試及格了就是及格了,不能事後改成分數。+- **單一權威來源**:項目裡關於"該做什麼"的所有信息,必須從一個功能清單派生。不能出現功能清單和對話記錄矛盾的情況。+- **反向壓力**:還沒通過的功能項數量就是 harness 對 agent 施加的壓力。壓力歸零 = 項目完成。++## 為什麼功能清單必須是"原語"++文檔是給人看的,原語是給系統用的。文檔可以被忽略,原語不能被繞過。++類比數據庫的觸發器約束和應用層的檢查邏輯:前者由數據庫引擎強制執行,任何 SQL 都無法跳過;後者依賴於應用代碼的正確性,可能被意外繞過。功能清單作為 harness 原語,就是數據庫級別的約束——agent 不能繞過它。++具體來說,功能清單服務四個 harness 組件:++1. **調度器**:讀狀態,選下一個 `not_started` 的功能。就像工廠的排產系統——看完訂單才知道下一步做什麼。+2. **驗證器**:執行驗證命令,判斷是否允許狀態轉移。就像質檢——不是你說合格就合格,得通過檢驗。+3. **交接報告器**:從功能清單自動生成會話交接摘要。就像換班時自動生成的交接表——不用手寫,系統自己出。+4. **進度追蹤器**:統計各狀態分佈,提供項目健康度指標。就像儀表盤——一眼看出項目走到哪了。++## 怎麼做++### 1. 定義一個最小化的功能清單格式++不需要複雜的系統,一個結構化的 Markdown 或 JSON 檔案就夠了。關鍵是每個條目必須有三元組:++```json+{+ "id": "F03",+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",+ "state": "passing",+ "evidence": "commit abc123, test output log"+}+```++### 2. 讓 harness 控制狀態轉移++agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harness 執行驗證命令,根據結果決定是否允許狀態轉移。這就是"通過狀態門控"——不是你說考過了就考過了,得看成績單。++### 3. 在 CLAUDE.md 裡寫清楚規則++```+## 功能清單规则+- 功能清單檔案: /docs/features.md+- 每次只激活一個功能项+- 功能项驗證命令必須通過才能標為 passing+- 不要修改功能清單的狀態——由驗證脚本自動更新+```++### 4. 粒度校準++每個功能項應該是"一次會話能完成"的範圍。太粗了做不完,太細了管理開銷大。"用戶可以添加商品到購物車"是一個好粒度,"實現購物車"太粗了,"創建 Cart 模型的 name 字段"太細了。就像切牛排——不能整塊啃,也不能切成肉沫。++## 實際案例++一個電商平臺的開發任務,10 個功能項。對比兩種追蹤方式:++**備忘錄模式**:agent 用非結構化筆記記錄進度。3 個會話後,筆記變成了"做了用戶認證和商品列表、購物車基本完成但還有 bug、支付沒開始"。新會話需要 20 分鐘推斷狀態,最終重複實現了已完成的功能。就像你的購物清單上寫著"牛奶、麵包、還有那個什麼來著"——到超市了你還是不知道要買什麼。++**脊樑骨模式**:每個功能項有明確的狀態和驗證命令。新會話讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。++定量結果:使用結構化功能清單的項目,功能完成率比自由形式高 45%,零重複實現。++## 關鍵要點++- **功能清單是 harness 的脊樑骨**,不是給人看的備忘錄。調度器、驗證器、交接器都依賴它。+- **每個功能項必須有三元組**:行為描述 + 驗證命令 + 當前狀態。缺一項就不完整——就像三條腿的凳子少一條腿。+- **狀態轉移由 harness 控制**,agent 不能自己改狀態。通過驗證 = 唯一的升級路徑。+- **功能清單是項目的單一權威來源**——任何關於"該做什麼"的信息都從這裡派生。+- **粒度控制在"一次會話能完成"的範圍**。太粗做不完,太細管不過來。++## 延伸閱讀++- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 明確指出功能列表是控制 agent 執行範圍的"核心數據結構"+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 強調"將工件外部化"的原則+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — 契約式設計原則,功能列表的理論基礎+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — 測試金字塔和行為規格的工程實踐++## 練習++1. **功能清單設計**:定義一個最小化的功能清單 JSON schema。包含:id、行為描述、驗證命令、當前狀態、證據引用。用它描述一個包含 5 個功能的真實項目。++2. **驗證嚴格性對比**:選 3 個功能,分別設計"寬鬆"驗證(如"代碼無語法錯誤")和"嚴格"驗證(如"端到端測試通過")。對比兩種驗證下的假陽性率。++3. **單一來源原則審查**:審查一個已有的 agent 項目,檢查是否存在與功能清單矛盾的範圍信息(對話裡的隱式需求、代碼裡的 TODO 註釋等)。設計一個方案,把所有信息統一到功能清單中。diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.mdnew file mode 100644index 0000000..81f6d0a--- /dev/null+++ b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md@@ -0,0 +1,6 @@+# 乾淨狀態檢查清單++- 應用程式無需手動修復即可啟動+- 目前的進度已被記錄+- 沒有任何未完成的匯入或索引步驟未被記錄+- 下一個 Agent 可以立即執行標準的啟動和驗證路徑diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdnew file mode 100644index 0000000..4d0e382--- /dev/null+++ b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -0,0 +1,8 @@+# 第 09 講的程式碼++此資料夾用於以下範例:++- 日誌作為反饋+- 執行狀態可視性+- 乾淨狀態檢查+- 恢復範例diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.tsnew file mode 100644index 0000000..fad1a3b--- /dev/null+++ b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts@@ -0,0 +1,241 @@+/**+ * victory-detector.ts+ *+ * Simulates an agent that claims task completion, then checks the claimed+ * state against actual verification. Outputs: claimed vs actual, highlighting+ * gaps between what the agent said and what's really true.+ *+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface Task {+ name: string;+ claimedComplete: boolean;+ checks: VerificationCheck[];+}++interface VerificationCheck {+ description: string;+ claimed: boolean; // What the agent says+ actual: boolean; // What is actually true+ severity: "critical" | "warning";+}++// ---------------------------------------------------------------------------+// Simulated tasks with claimed vs actual states+// ---------------------------------------------------------------------------++const tasks: Task[] = [+ {+ name: "Add search endpoint",+ claimedComplete: true,+ checks: [+ {+ description: "Route handler exists",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Authentication middleware applied",+ claimed: true,+ actual: false, // Agent forgot auth+ severity: "critical",+ },+ {+ description: "Input validation added",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Unit tests written",+ claimed: true,+ actual: false, // Agent skipped tests+ severity: "critical",+ },+ {+ description: "Integration tests pass",+ claimed: true,+ actual: false, // No tests to run+ severity: "critical",+ },+ {+ description: "Documentation updated",+ claimed: true,+ actual: false, // Agent skipped docs+ severity: "warning",+ },+ ],+ },+ {+ name: "Fix pagination bug",+ claimedComplete: true,+ checks: [+ {+ description: "Bug reproduction case confirmed",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Root cause identified",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Fix applied",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Edge cases tested",+ claimed: true,+ actual: false, // Only happy path tested+ severity: "warning",+ },+ {+ description: "Regression tests added",+ claimed: true,+ actual: false,+ severity: "critical",+ },+ ],+ },+ {+ name: "Refactor auth module",+ claimedComplete: true,+ checks: [+ {+ description: "Old code removed",+ claimed: true,+ actual: false, // Old code still present+ severity: "warning",+ },+ {+ description: "All existing tests still pass",+ claimed: true,+ actual: false, // Two tests broke+ severity: "critical",+ },+ {+ description: "New auth flow works",+ claimed: true,+ actual: true,+ severity: "critical",+ },+ {+ description: "Migration guide written",+ claimed: true,+ actual: false,+ severity: "warning",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Verification+// ---------------------------------------------------------------------------++interface TaskVerification {+ taskName: string;+ claimedComplete: boolean;+ actuallyComplete: boolean;+ totalChecks: number;+ claimedPassing: number;+ actualPassing: number;+ gaps: { description: string; severity: string }[];+}++function verifyTask(task: Task): TaskVerification {+ const claimedPassing = task.checks.filter((c) => c.claimed).length;+ const actualPassing = task.checks.filter((c) => c.actual).length;+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);++ return {+ taskName: task.name,+ claimedComplete: task.claimedComplete,+ actuallyComplete: gaps.length === 0,+ totalChecks: task.checks.length,+ claimedPassing,+ actualPassing,+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),+ };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(90));+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");+ console.log("=".repeat(90));++ const verifications = tasks.map(verifyTask);++ for (const v of verifications) {+ console.log("\n Task: " + v.taskName);+ console.log(" " + "-".repeat(70));+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);++ if (!v.actuallyComplete) {+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);+ }++ // Detailed checks for this task+ const task = tasks.find((t) => t.name === v.taskName)!;+ console.log("\n Check detail:");+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;+ console.log(header);+ console.log(sep);++ for (const check of task.checks) {+ const claimedLabel = check.claimed ? "PASS" : "FAIL";+ const actualLabel = check.actual ? "PASS" : "FAIL";+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";+ const marker = gapLabel ? ">>" : " ";+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);+ }+ }++ // Overall summary+ console.log("\n" + "=".repeat(90));+ console.log(" OVERALL SUMMARY");+ console.log("=".repeat(90) + "\n");++ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;+ console.log(sHeader);+ console.log(sSep);++ for (const v of verifications) {+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);+ const cLabel = v.claimedComplete ? "Done" : "Pending";+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);+ }++ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;++ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");+ console.log(" Total undetected gaps: " + totalGaps);+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");+}++run();diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdnew file mode 100644index 0000000..0c1551e--- /dev/null+++ b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -0,0 +1,145 @@+[English Version →](../../../en/lectures/lecture-09-why-agents-declare-victory-too-early/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/)+> 實戰練習:[Project 05. 讓 agent 自己檢查自己做的對不對](./../../projects/project-05-grounded-qa-verification/index.md)++# 第九講. 防止 agent 提前宣告完成++你讓 agent 實現"密碼重置"功能。它改了數據庫 schema、寫了 API 端點、加了郵件範本,跑了單元測試(全部通過),然後自信地告訴你"做完了"。你實際一跑——密碼重置鏈接發不出去(郵件服務配置缺失)、數據庫遷移半途失敗(schema 不一致)、端到端流程根本沒走過一遍。++這種感覺你一定不陌生——考試時把卷子寫得滿滿當當,信心滿滿地第一個交卷,結果成績出來不及格。卷子寫滿了,不代表做對了。++這不是偶然事件。Guo 等人 2017 年在 ICML 上的經典論文證明:**現代神經網絡系統性地過度自信**——模型自報的置信度顯著高於實際準確率。AI 編碼 agent 也一樣:它"覺得"做完了,但實際上差得遠。你的 harness 必須用外部化的、基於執行的驗證來替代 agent 的"感覺"。++## 滑坡效應++過早完成聲明幾乎總是一樣的套路:代碼看著還行——語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際運行或只跑了部分測試。跑了單元測試但跳過集成測試,跑了測試但沒檢查覆蓋率。最後"代碼看起來沒問題"就被當作了"功能已完成"的證據。交卷了。++每一步都在丟失信息。從任務規範到代碼實現到運行時行為,每次轉換都可能引入偏差,而每次跳過的驗證都加劇了信息不對稱。++## 三層終止檢查++```mermaid+flowchart LR+ Claim["agent 說:做完了"] --> L1["先跑<br/>lint / typecheck"]+ L1 --> L2["再跑<br/>測試和啟動檢查"]+ L2 --> L3["最後跑<br/>完整使用者流程"]+ L3 --> Done["三层都過才算完成"]+```++```mermaid+flowchart LR+ A["程式碼寫完了<br/>單測也绿了"] --> B["但應用没真正啟動<br/>完整流程也没跑"]+ B --> C["配置、資料庫、外部服務問題<br/>还都藏着"]+ C --> D["于是 agent 太早宣告完成"]+```++## 核心概念++- **過早完成聲明**:agent 斷言任務完成,但實際上存在未滿足的正確性規範。核心問題:agent 依據代碼層面的局部信心做判斷,系統級正確性需要全局驗證。+- **置信度校準偏差**:agent 自報的完成信心與實際完成質量之間的系統性差距。對複雜多檔案任務,這個偏差顯著為正——agent 總是比實際做得更自信。就像學生考完試估分總是偏高。+- **終止標準**:一組明確的、可執行的判定條件,定義在 harness 裡。agent 必須滿足所有條件才能聲明完成。"完成"從主觀判斷變成了客觀判定。+- **驗證-確認雙閘門**:第一層驗證檢查"代碼是否正確實現了指定行為";第二層確認檢查"系統級行為是否滿足端到端需求"。兩層都通過才算完成。+- **運行時反饋信號**:來自程序執行的日誌、進程狀態、健康檢查。這是 harness 判定完成質量的客觀基礎。+- **完成優先級約束**:先驗證功能正確性,再處理性能,最後管風格。核心功能沒驗證通過之前,不許做重構。++## 單元測試通過 ≠ 任務完成++這是最常見的陷阱,也是最危險的一個。agent 寫了代碼,跑了單元測試,全部綠色,然後說"做完了"。但單元測試的設計哲學——隔離被測單元、模擬依賴——恰好使其無法檢測跨組件問題:++**接口不匹配**:渲染進程傳給預加載腳本的檔案路徑是相對路徑,但預加載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題。就像樂隊裡每個樂手各自練習都完美,但合在一起才發現定調不一樣。++**狀態傳播錯誤**:數據庫遷移改了表結構,但 ORM 的緩存層還持有舊結構的緩存條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。++**環境依賴性**:代碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網絡延遲、服務不可用而失敗。就像在排練室唱得很好,上臺演出時音響設備出了問題。++### "順便重構"是完成判定的毒藥++Claude Code 有一個常見行為模式:在核心功能還沒驗證通過時就開始重構代碼、優化性能、改進風格。Knuth 說的"過早優化是萬惡之源"在 agent 場景中有了新含義——重構會改變已完成驗證和未完成驗證之間的邊界,可能破壞之前隱式正確的代碼路徑。就像你數學大題還沒做完,就跑去把前面選擇題的答案重新抄一遍格式——浪費時間不說,還可能抄錯了。++### 自我評價的系統性偏差++Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**當 agent 被要求評估自己的工作時,它系統性地過度正面評價——即使人類觀察者認為質量明顯不達標。** 這就像讓學生自己給自己判卷——對自己的答案總是特別寬容。++這個問題在主觀任務(如設計審美)上尤其嚴重——"佈局是否精緻"是一個判斷題,agent 可靠地偏向正面。即使在有可驗證結果的任務上,agent 也會因為判斷失誤而影響表現。++解決方案不是讓 agent "更客觀"——同一個模型既生成又評估,內在地傾向對自己慷慨。**解決方案是把"幹活的人"和"檢查的人"分開。** 就像考試不能讓學生自己批改自己的卷子——得有個獨立的閱卷老師。++一個獨立的評估 agent,經過專門調校為"挑剔"之後,比讓生成 agent 自我評估有效得多。Anthropic 的實驗數據:++| 架構 | 運行時長 | 成本 | 核心功能是否可用 |+|------|---------|------|---------------|+| 單 agent 裸跑 | 20 分鐘 | $9 | 否(遊戲實體無法響應輸入) |+| 三 agent(planner + generator + evaluator) | 6 小時 | $200 | 是(遊戲可以正常遊玩) |++這是同一個模型(Opus 4.5),同一段提示詞("做一個 2D 復古遊戲編輯器")。區別只在 harness——從"裸奔"到"planner 擴展需求 → generator 逐功能實現 → evaluator 用 Playwright 實際點擊測試"。++> 來源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## 怎麼防止提前交卷++### 1. 外部化終止判定++完成判定不應該由 agent 自己做。harness 獨立執行終止校驗,輸入是運行時信號,不是 agent 的置信度。在 CLAUDE.md 裡寫清楚:++```+## 完成定義+- 功能完成 = 端到端驗證通過,不是"程式碼寫完了"+- 必須執行的驗證層級:+ 1. 單元測試通過+ 2. 集成測試通過+ 3. 端到端流程驗證通過+- 在第 1 层没通過時,不许进入第 2 层+- 在第 2 层没通過時,不许进入第 3 层+```++### 2. 構建三層終止校驗++- **第一層:語法與靜態分析**。成本最低,信息量最小,但必須通過。這是最低限度的檢查——字都沒寫錯才能往下看。+- **第二層:運行時行為驗證**。測試執行、應用啟動檢查、關鍵路徑驗證。這是核心完成證據。不僅要寫了,還要能跑。+- **第三層:系統級確認**。端到端測試、集成驗證、用戶場景模擬。防止過早聲明的最後一道防線。不僅要能跑,還要跑對。++### 3. 為 agent 設計好的"紅筆批註"++OpenAI 在 Codex 實踐中提出了一個特別有效的模式:**給 agent 寫的錯誤消息要包含修復指導**。不要像閱卷老師只畫個大紅叉,要像好老師一樣在旁邊寫上"這裡應該怎麼改"。不要用 `"Test failed"`,而用 `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` 這種具體的、可操作的反饋讓 agent 能自我修正,而不需要人類介入。++### 4. 捕獲運行時信號++有效的運行時信號包括:+- 應用是否成功啟動並達到就緒狀態?+- 關鍵功能路徑在運行時是否執行成功?+- 數據庫寫入、檔案操作等副作用是否正確?+- 臨時資源是否被清理?++## 實際案例++**任務**:實現用戶密碼重置功能。涉及數據庫操作、郵件發送和 API 端點修改。++**提前交卷路徑**:agent 修改數據庫 schema、編寫 API 端點、添加郵件範本、跑單元測試(通過)、聲明完成。卷子寫得滿滿當當。++**實際扣分項**:(1) 端到端流程未測試——重置鏈接的實際發送和驗證未確認。(2) 數據庫遷移在部分執行後失敗,導致 schema 不一致。(3) 郵件服務配置在目標環境中缺失。++**harness 介入**:終止校驗強制執行——(1) 啟動完整應用驗證重置端點可訪問;(2) 執行完整重置流程;(3) 驗證數據庫狀態一致性。所有缺陷在會話內被發現,節省了 5-10 倍的後續修復成本。獨立閱卷老師批出了真正的問題。++## 關鍵要點++- **agent 系統性地過度自信**——置信度校準偏差是客觀存在的。卷子寫滿了不代表做對了。+- **完成判定必須外部化**——harness 獨立驗證,不信任 agent 的"感覺"。不能讓學生自己批自己的卷子。+- **三層校驗缺一不可**——語法通過、行為通過、系統通過,層層遞進。+- **錯誤消息要像好老師的紅筆批註**——包含具體修復步驟,讓 agent 能自我修正。+- **核心功能驗證通過之前不許重構**——完成優先級約束是防止過早優化的關鍵。++## 延伸閱讀++- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — 證明現代深度網絡系統性地過度自信+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 運行時證據在完成判定中的關鍵作用+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 過早完成聲明是 agent 的主要失敗模式之一+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — 測試方法層次和有效性的經典參考++## 練習++1. **終止校驗函數設計**:為一個涉及數據庫遷移和 API 修改的任務設計完整的終止校驗。列出需要的運行時信號和每個信號的通過/失敗標準。在一個實際任務上運行,記錄它發現了哪些隱藏問題。++2. **校準偏差測量**:選 10 個不同類型的編碼任務,記錄 agent 的自報完成信心和實際完成質量。計算偏差值,分析它和任務複雜度的關係。++3. **多層防禦實驗**:對同一組任務跑三種配置——(a) 僅靜態分析,(b) 加單元測試,(c) 完整三層校驗。比較過早完成聲明的比例和未捕獲缺陷的數量。diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.mdnew file mode 100644index 0000000..d027de1--- /dev/null+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md@@ -0,0 +1,6 @@+# Electron 架構規則++- Renderer 程式碼不得直接存取檔案系統。+- Preload 是 renderer 與 Electron main 之間唯一的橋樑。+- 檢索和索引邏輯應存在於服務模組中,而非 UI 元件中。+- 日誌應為結構化格式,並從服務邊界發出。diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.tsnew file mode 100644index 0000000..2428416--- /dev/null+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts@@ -0,0 +1,253 @@+/**+ * e2e-runner.ts+ *+ * A minimal E2E test harness. Defines test cases as user action sequences+ * (import doc -> index -> ask question -> verify citation). Simulates+ * running them and shows the difference between "unit tests pass" and+ * "full pipeline works".+ *+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface PipelineStep {+ name: string;+ unitTestPasses: boolean;+ // Simulated actual behavior in the pipeline+ actualBehavior: "works" | "fails" | "partial";+ failureReason?: string;+}++interface TestCase {+ name: string;+ steps: PipelineStep[];+}++interface TestResult {+ testCase: string;+ unitTestsPassed: number;+ unitTestsTotal: number;+ unitTestResult: "PASS" | "FAIL";+ e2eResult: "PASS" | "FAIL";+ e2eFailureStep?: string;+ e2eFailureReason?: string;+}++// ---------------------------------------------------------------------------+// Test cases -- realistic scenarios where unit tests pass but E2E fails+// ---------------------------------------------------------------------------++const testCases: TestCase[] = [+ {+ name: "Import document and ask question",+ steps: [+ {+ name: "Parse uploaded document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Store document chunks",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Index chunks for retrieval",+ unitTestPasses: true,+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions+ failureReason: "Embedding dimension mismatch between indexer and retriever",+ },+ {+ name: "Retrieve relevant chunks",+ unitTestPasses: true, // Unit test uses mock data with correct dimensions+ actualBehavior: "fails",+ failureReason: "Empty results due to dimension mismatch from previous step",+ },+ {+ name: "Generate answer with citations",+ unitTestPasses: true, // Unit test provides pre-retrieved chunks+ actualBehavior: "fails",+ failureReason: "No chunks retrieved, so answer has no citations",+ },+ ],+ },+ {+ name: "Delete document and verify removal",+ steps: [+ {+ name: "Find document by ID",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Delete document record",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "Remove indexed chunks",+ unitTestPasses: true,+ actualBehavior: "fails", // Orphaned chunks remain in the index+ failureReason: "Index cleanup query timed out, chunks remain orphaned",+ },+ {+ name: "Verify document not in search results",+ unitTestPasses: true, // Unit test mocks the search+ actualBehavior: "fails",+ failureReason: "Orphaned chunks from previous step still appear in results",+ },+ ],+ },+ {+ name: "Multi-user concurrent access",+ steps: [+ {+ name: "User A imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User B imports document",+ unitTestPasses: true,+ actualBehavior: "works",+ },+ {+ name: "User A queries their document",+ unitTestPasses: true,+ actualBehavior: "partial", // Cross-contamination of results+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",+ },+ {+ name: "Verify only User A's results returned",+ unitTestPasses: true,+ actualBehavior: "fails",+ failureReason: "Results include documents from other users",+ },+ ],+ },+];++// ---------------------------------------------------------------------------+// Run tests+// ---------------------------------------------------------------------------++function runUnitTests(tc: TestCase): { passed: number; total: number } {+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;+ return { passed, total: tc.steps.length };+}++function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {+ // Pipeline: if any step actually fails, the whole E2E fails+ for (const step of tc.steps) {+ if (step.actualBehavior === "fails") {+ return {+ pass: false,+ failureStep: step.name,+ failureReason: step.failureReason ?? "Unknown failure",+ };+ }+ // "partial" means the step technically completes but creates problems downstream+ // We let it continue but track it+ }+ // Check if any step was "partial" (which may cause downstream issues)+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");+ if (partialSteps.length > 0) {+ // The partial steps may or may not cause overall failure+ // In our simulation, partial steps always lead to failure downstream+ // unless there's an explicit "fails" step that already caught it+ // This case means all steps were either "works" or "partial"+ return {+ pass: false,+ failureStep: partialSteps[partialSteps.length - 1].name,+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",+ };+ }++ return { pass: true };+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(95));+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");+ console.log("=".repeat(95));++ const results: TestResult[] = testCases.map((tc) => {+ const unit = runUnitTests(tc);+ const e2e = runE2ETest(tc);++ return {+ testCase: tc.name,+ unitTestsPassed: unit.passed,+ unitTestsTotal: unit.total,+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",+ e2eResult: e2e.pass ? "PASS" : "FAIL",+ e2eFailureStep: e2e.failureStep,+ e2eFailureReason: e2e.failureReason,+ };+ });++ // Per-test-case detail+ for (let i = 0; i < testCases.length; i++) {+ const tc = testCases[i];+ const r = results[i];++ console.log("\n Test Case: " + tc.name);+ console.log(" " + "-".repeat(70));++ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;+ console.log(stepHeader);+ console.log(stepSep);++ for (const step of tc.steps) {+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";+ let e2eLabel: string;+ if (step.actualBehavior === "works") e2eLabel = "PASS";+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";+ else e2eLabel = "FAIL";++ const marker = step.actualBehavior !== "works" ? ">>" : " ";+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);+ }++ if (r.e2eFailureStep) {+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);+ console.log(` Reason: ${r.e2eFailureReason}`);+ }+ }++ // Summary comparison+ console.log("\n" + "=".repeat(95));+ console.log(" COMPARISON: Unit Tests vs E2E Tests");+ console.log("=".repeat(95) + "\n");++ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";++ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);+ }++ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");+}++run();diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdnew file mode 100644index 0000000..2b3ec31--- /dev/null+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -0,0 +1,8 @@+# 第 10 講的程式碼++此資料夾用於以下範例:++- 架構約束+- 結構化測試+- 品味不變量+- 以修復為導向的 lint 訊息diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdnew file mode 100644index 0000000..300cba0--- /dev/null+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -0,0 +1,10 @@+# 範例:將審查反饋轉化為規則++重複的審查意見:++> 不要從 renderer 呼叫檔案系統工具。使用 preload 橋樑。++提升為 harness 規則:++- 新增 lint 或匯入規則以防止在 renderer 程式碼中使用 `fs`+- 新增修復說明文字,解釋 preload 邊界diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdnew file mode 100644index 0000000..db5ec73--- /dev/null+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -0,0 +1,158 @@+[English Version →](../../../en/lectures/lecture-10-why-end-to-end-testing-changes-results/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)+> 實戰練習:[Project 05. 讓 agent 自己檢查自己做的對不對](./../../projects/project-05-grounded-qa-verification/index.md)++# 第十講. 跑通完整流程才算真正驗證++你讓 agent 給 Electron 應用加一個檔案導出功能。它寫了渲染進程組件、預加載腳本、服務層邏輯,每個組件的單元測試都通過了。agent 說"做完了"。你實際一點擊導出按鈕——檔案路徑格式不對、進度條沒反應、大檔案導出時內存洩漏。5 個組件邊界缺陷,單元測試一個都沒發現。++這就像一個合唱團排練——每個聲部單獨唱的時候都完美,但合在一起的時候,女高音比男低音快了半拍,伴奏的調子和主旋律差了半個音。每個部分都"對"了,但整體跑調了。++Google 的測試金字塔告訴我們:大量單元測試是基礎,但如果你止步於此,就會系統性地漏掉組件交互問題。對於 AI 編碼 agent 來說,這個問題更嚴重——agent 傾向於只跑最快的測試然後宣告完成。**只有端到端測試能證明系統級缺陷不存在**。++## 單元測試的盲區++單元測試的設計哲學是隔離——模擬依賴,專注被測單元。這個哲學使單元測試快速且精確,但也製造了系統性的盲區。就像合唱排練時每個聲部戴著耳機對著伴奏唱——聽著都挺好,但真正合在一起才發現問題:++**接口不匹配**:渲染進程傳給預加載腳本的檔案路徑是相對路徑,但預加載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題——就像兩個聲部各自練的時候都覺得節奏沒問題,一合才發現一個用 4/4 拍一個用 3/4 拍。++**狀態傳播錯誤**:數據庫遷移改了表結構,但 ORM 的緩存層還持有舊結構的緩存條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。就像換了一首歌的歌詞,但有人還在唱舊版本。++**資源生命週期問題**:檔案句柄、數據庫連接、網絡套接字的獲取和釋放跨越多個組件。單元測試為每個測試創建和銷燬獨立資源,不會暴露資源競爭或洩漏。就像排練時每個聲部輪流用麥克風,但演出時所有聲部同時上臺——話筒不夠用了。++**環境依賴性**:代碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網絡延遲、服務不可用而失敗。就像排練廳裡唱得好好的,到了戶外音樂節風一吹話筒一嘯叫就全亂了。++## 端到端測試不僅改變結果,還改變行為++這是很多人沒意識到的一點:當 agent 知道它的工作要過端到端測試時,它的編碼行為會改變。++1. **考慮組件交互**:寫代碼時會想"這個接口和上游怎麼對接",而不是隻關注單個函數。就像知道最終要合在一起唱,練習的時候就會注意聽其他聲部。+2. **尊重架構邊界**:有架構約束的系統裡,端到端測試迫使 agent 遵守邊界規則。就像樂譜上標註了"此處漸強",你得跟著來。+3. **處理錯誤路徑**:端到端測試通常包含故障場景,迫使 agent 考慮異常處理。就像排練時模擬了"話筒突然沒聲了"的情況,你知道該怎麼做。++## 測試金字塔與審查反饋提升++```mermaid+flowchart TB+ subgraph Unit["單元測試只看孤立部件"]+ U1["渲染层測試"]+ U2["Preload 測試"]+ U3["服務层測試"]+ end++ subgraph E2E["端到端執行會穿過真實系統"]+ R["点击渲染层按钮"] --> P["Preload 桥"]+ P --> S["服務层"]+ S --> F["檔案系統 / 操作系統"]+ F --> Result["真實导出檔案"]+ end+```++```mermaid+flowchart LR+ Review["審查意见:<br/>renderer 不能直接 import fs"] --> Rule["加一条 direct fs import 檢查"]+ Rule --> Message["报錯裡直接告诉 agent<br/>把檔案访问移到 preload"]+ Message --> Harness["把這条檢查加入 harness"]+ Harness --> Stronger["以後再犯會第一時间报錯"]+```++OpenAI 在 Codex 工程實踐中強調:**為 agent 寫的錯誤消息必須包含修復指導**。不寫 `"Direct filesystem access in renderer"`,而寫 `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` 這把架構規則變成了自動修正的閉環。就像合唱排練時指揮不只說"你唱錯了",而是說"這裡你快了半拍,聽一下女低音的節奏,在第 32 小節進入"。++## 核心概念++- **組件邊界缺陷**:組件 A 和 B 各自單元測試通過,但它們的交互產生了不正確的行為。這是端到端測試最擅長捕獲的問題類型——合唱裡各聲部單獨都對但合起來跑調的那種。+- **測試充分性梯度**:單元測試能檢測的缺陷 <= 集成測試能檢測的缺陷 <= 端到端測試能檢測的缺陷。每往上一層,檢測能力增強。+- **架構邊界執行規則**:把架構文檔裡的規則(如"渲染進程不能直接訪問檔案系統")變成可執行的自動化檢查。從"寫在紙上"變成"跑在 CI 裡"。+- **審查反饋提升**:把重複出現的代碼審查意見轉化為自動化測試。每次發現重複問題就加一條規則,harness 會自動變強。就像合唱排練時指揮把常見的錯誤編成練習曲——下次再犯同樣的錯誤,不用指揮說,練習曲自己就暴露了。+- **面向 agent 的錯誤消息**:失敗信息不只是說"出了什麼問題",還要告訴 agent 具體怎麼修。這把測試失敗變成自我修正的反饋循環。++## 怎麼做++### 0. 先定好架構邊界,再寫端到端測試++端到端測試的前提是系統有清晰的邊界。如果架構是一團麵條,端到端測試只會證明"這團麵條整體能跑",不會告訴你哪裡違反了設計意圖。就像合唱團如果連分聲部都沒分好,排練再多也是亂唱。++OpenAI 的經驗:**對 agent 生成的代碼庫,架構約束必須是第一天就建立的早期前置條件,不是等團隊規模大了再考慮的事。** 原因很直接——agent 會複製倉庫中已有的模式,即使那些模式是不均勻的或次優的。沒有架構約束,agent 會在每次會話中引入更多偏差。++OpenAI 採用了"分層領域架構"——每個業務領域被分成固定的層:Types → Config → Repo → Service → Runtime → UI。依賴方向嚴格向前,跨領域關注點通過顯式的 Providers 接口進入。任何其他依賴都是禁止的,並且通過自定義 lint 機械執行。++關鍵原則:**執行不變量,不微管實現。** 比如要求"數據在邊界解析",但不規定用哪個庫。錯誤消息要包含修復指導——不只是說"違規了",而是告訴 agent 具體怎麼改。++> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++### 1. harness 必須包含端到端層++在你的驗證流程裡明確:對於涉及跨組件修改的任務,端到端測試通過是完成的前置條件:++```+## 驗證層級+- 層級 1: 單元測試 (必須通過)+- 層級 2: 集成測試 (必須通過)+- 層級 3: 端到端測試 (涉及跨组件修改時必須通過)+- 跳過任何必須層級的任務 = 未完成+```++### 2. 把架構規則變成可執行檢查++每條架構約束都應該有對應的測試或 lint 規則:++```bash+# 檢查渲染进程是否直接調用 Node.js API+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"+```++### 3. 設計面向 agent 的錯誤消息++失敗信息要包含三要素:什麼出了問題、為什麼、怎麼修:++```+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12+WHY: Renderer process has no access to Node.js APIs for security+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()+```++### 4. 建立審查反饋提升流程++每次在代碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。就像合唱團的排練筆記——每次排練發現的問題都記下來,下次排練前先檢查這些點。久而久之,常見錯誤越來越少,音樂越來越和諧。++## 實際案例++**任務**:在 Electron 應用中實現檔案導出功能。涉及渲染進程 UI、預加載腳本檔案系統代理、服務層數據轉換。++**各聲部單獨唱(單元測試通過)**:渲染組件測試(通過,mock 檔案操作)、預加載腳本測試(通過,mock 檔案系統)、服務層測試(通過,mock 數據源)。agent 聲明完成。++**合唱合在一起(端到端測試揭示的缺陷)**:++| 缺陷 | 描述 | 單元測試 | 端到端 |+|------|------|---------|--------|+| 接口不匹配 | 檔案路徑格式不一致 | 未檢測 | 檢測 |+| 狀態傳播 | 導出進度未通過 IPC 傳回 UI | 未檢測 | 檢測 |+| 資源洩漏 | 大檔案導出句柄未釋放 | 未檢測 | 檢測 |+| 權限問題 | 打包環境權限不同 | 未檢測 | 檢測 |+| 錯誤傳播 | 服務層異常未到 UI 層 | 未檢測 | 檢測 |++5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。代價是測試時間從 2 秒增加到 15 秒——在 agent 工作流裡完全可以接受。每個聲部單獨唱得再好,也比不上一次完整的合唱排練。++## 關鍵要點++- **單元測試對組件邊界缺陷系統性盲視**——它們的隔離設計恰好使其無法檢測交互問題。每個人唱得都對,不代表合唱不跑調。+- **端到端測試不僅檢測缺陷,還改變 agent 的編碼行為**——讓它更關注集成和邊界。+- **架構規則必須可執行**——不是寫在文檔裡等人來看,而是每次提交自動檢查。+- **錯誤消息要面向 agent 設計**——包含"怎麼修"的具體步驟,形成自我修正閉環。+- **審查反饋提升讓 harness 自動變強**——每個被捕獲的缺陷類別都變成永久防線。++## 延伸閱讀++- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — 測試金字塔模型的經典來源+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 架構約束自動化執行的工程實踐+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — 主動注入故障驗證系統彈性+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — 屬性測試方法,介於示例測試和形式化驗證之間++## 練習++1. **跨組件缺陷檢測**:選一個涉及至少三個組件的修改任務。先只跑單元測試記錄結果,再跑端到端測試。分析每個額外發現的缺陷屬於哪種跨層交互問題。++2. **架構規則自動化**:選項目裡的一條架構約束,把它變成可執行檢查(含面向 agent 的錯誤消息)。集成到 harness 裡,用基準任務驗證效果。++3. **審查反饋提升**:從代碼審查歷史中找一個重複出現的意見類型,按五步流程轉化為自動化檢查。比較提升前後該類問題的出現頻率。diff --git a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.mdnew file mode 100644index 0000000..36e465c--- /dev/null+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md@@ -0,0 +1,8 @@+# 評估評分標準範例++對每個維度使用 1-5 分評分:++- 基礎性:答案是否清楚地與匯入的來源相關聯?+- 引用品質:來源參考是否可見且具體?+- 功能性:使用者能否完成問答流程?+- 產品一致性:工作流程是否感覺整合良好?diff --git a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdnew file mode 100644index 0000000..318336e--- /dev/null+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md@@ -0,0 +1,8 @@+# 第 11 講的程式碼++此資料夾用於以下範例:++- 規劃輸出+- 評估評分標準+- 產生器/評估器迴圈+- 單一 Agent 與多角色比較diff --git a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsnew file mode 100644index 0000000..213dc19--- /dev/null+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts@@ -0,0 +1,260 @@+/**+ * runtime-logger.ts+ *+ * A structured logging module demo. Shows ad-hoc console.log output vs+ * structured JSON log output when diagnosing a failure. Includes a seeded+ * failure scenario and demonstrates how structured logs pinpoint the issue+ * faster.+ *+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface StructuredLogEntry {+ timestamp: string;+ level: "info" | "warn" | "error" | "debug";+ component: string;+ action: string;+ durationMs?: number;+ input?: unknown;+ output?: unknown;+ error?: string;+ correlationId: string;+}++// ---------------------------------------------------------------------------+// Simulated pipeline with a seeded failure+// ---------------------------------------------------------------------------++const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);++// Simulated stages of a document Q&A pipeline+interface PipelineStage {+ component: string;+ action: string;+ durationMs: number;+ success: boolean;+ errorMessage?: string;+ input?: unknown;+ output?: unknown;+}++function runPipeline(): PipelineStage[] {+ return [+ {+ component: "DocumentLoader",+ action: "parse_upload",+ durationMs: 45,+ success: true,+ input: { filename: "report.pdf", size: "2.3MB" },+ output: { chunks: 47 },+ },+ {+ component: "ChunkIndexer",+ action: "embed_and_store",+ durationMs: 230,+ success: true,+ input: { chunks: 47 },+ output: { indexed: 47, embeddingDim: 1536 },+ },+ {+ component: "QueryRouter",+ action: "route_query",+ durationMs: 12,+ success: true,+ input: { query: "What is the revenue target?" },+ output: { routedTo: "RetrievalEngine" },+ },+ {+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch+ component: "RetrievalEngine",+ action: "semantic_search",+ durationMs: 180,+ success: false,+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",+ input: { query: "What is the revenue target?", topK: 5 },+ output: { results: 0 },+ },+ {+ component: "AnswerGenerator",+ action: "generate_with_citations",+ durationMs: 1500,+ success: true, // Doesn't crash, but produces a bad answer+ input: { context: [], query: "What is the revenue target?" },+ output: { answer: "I could not find relevant information.", citations: 0 },+ },+ ];+}++// ---------------------------------------------------------------------------+// Ad-hoc logging (console.log style)+// ---------------------------------------------------------------------------++function printAdHocLog(stages: PipelineStage[]): void {+ console.log("Starting document Q&A pipeline...");+ console.log("User uploaded report.pdf");++ for (const stage of stages) {+ if (stage.success) {+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);+ } else {+ console.log(`${stage.component}: something went wrong`);+ }+ }++ console.log("Pipeline finished. Answer: I could not find relevant information.");+}++// ---------------------------------------------------------------------------+// Structured logging (JSON)+// ---------------------------------------------------------------------------++function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {+ const entries: StructuredLogEntry[] = [];++ for (const stage of stages) {+ entries.push({+ timestamp: new Date().toISOString(),+ level: stage.success ? "info" : "error",+ component: stage.component,+ action: stage.action,+ durationMs: stage.durationMs,+ input: stage.input,+ output: stage.output,+ error: stage.errorMessage,+ correlationId: CORRELATION_ID,+ });+ }++ return entries;+}++// ---------------------------------------------------------------------------+// Diagnose failure from structured logs+// ---------------------------------------------------------------------------++function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {+ const diagnosis: string[] = [];++ // Find errors+ const errors = entries.filter((e) => e.level === "error");+ if (errors.length > 0) {+ diagnosis.push("ERRORS FOUND:");+ for (const err of errors) {+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);+ }+ }++ // Check for latency spikes+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);+ if (slowStages.length > 0) {+ diagnosis.push("LATENCY SPIKES:");+ for (const s of slowStages) {+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);+ }+ }++ // Check for cascading failures+ const emptyOutputs = entries.filter((e) => {+ const out = e.output as Record<string, unknown> | undefined;+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;+ });+ if (emptyOutputs.length > 0) {+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");+ for (const e of emptyOutputs) {+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);+ }+ }++ return diagnosis;+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const pipeline = runPipeline();++ console.log("\n" + "=".repeat(90));+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");+ console.log("=".repeat(90));++ // --- Ad-hoc output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO A: Ad-hoc console.log output");+ console.log("-".repeat(90) + "\n");+ printAdHocLog(pipeline);+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");+ console.log(" The failure message is vague: 'something went wrong'.");+ console.log(" No dimensions, no input/output data, no correlation ID.");++ // --- Structured output ---+ console.log("\n" + "-".repeat(90));+ console.log(" SCENARIO B: Structured JSON log output");+ console.log("-".repeat(90) + "\n");++ const structuredEntries = printStructuredLog(pipeline);++ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const entry of structuredEntries) {+ const hasError = entry.error ? entry.error.slice(0, 30) : "";+ const marker = entry.level === "error" ? ">>" : " ";+ console.log(+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`+ );+ }++ // --- Diagnosis ---+ console.log("\n" + "-".repeat(90));+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");+ console.log("-".repeat(90) + "\n");++ const errors = structuredEntries.filter((e) => e.level === "error");+ for (const err of errors) {+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);+ console.log(` Error: ${err.error}`);+ console.log(` Input: ${JSON.stringify(err.input)}`);+ console.log(` Output: ${JSON.stringify(err.output)}`);+ console.log(` Correlation ID: ${err.correlationId}`);+ }++ // Downstream impact+ console.log("\n DOWNSTREAM IMPACT:");+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");+ if (answerGen) {+ const out = answerGen.output as Record<string, unknown>;+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);+ }++ // Comparison summary+ console.log("\n" + "=".repeat(90));+ console.log(" COMPARISON");+ console.log("=".repeat(90) + "\n");++ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;+ console.log(cHeader);+ console.log(cSep);+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);++ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");+}++run();diff --git a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.mdnew file mode 100644index 0000000..7fb0c07--- /dev/null+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md@@ -0,0 +1,12 @@+# Sprint 合約範例++Sprint 目標:++- 為基於來源的問答結果新增可見的引用++完成的定義:++- 使用者提出問題+- 應用程式回傳答案+- 顯示至少一個引用+- 點擊引用會在文件檢視中開啟來源位置diff --git a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdnew file mode 100644index 0000000..a2bb66a--- /dev/null+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -0,0 +1,173 @@+[English Version →](../../../en/lectures/lecture-11-why-observability-belongs-inside-the-harness/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)+> 實戰練習:[Project 06. 搭建一套完整的 agent 工作環境](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# 第十一講. 讓 agent 的運行過程可觀測++你讓 agent 做一個功能,它跑了 20 分鐘,改了一堆檔案,然後告訴你"做完了但有兩個測試失敗"。你問它為什麼失敗,它說"不太確定,可能是時序問題"。你問它改了哪些關鍵路徑,它說"讓我看看代碼……"。++這不是 agent 能力不夠,是你的 harness 沒有給它裝儀表盤。想象你在開一輛沒有儀表盤的車——沒有速度表、沒有油量表、沒有發動機故障燈。你能開,但你不知道開多快、還剩多少油、發動機是不是快爆了。技術再好的司機,蒙著眼也得出事。++**沒有可觀測性,agent 在不確定狀態中做決策,評估變成主觀判斷,重試變成盲目摸索。** OpenAI 和 Anthropic 都將可靠性定義為證據問題——harness 必須以可指導下一步決策的形式暴露運行時行為和評估信號。++## 可觀測性缺失的真實代價++當 harness 缺乏可觀測性時,四類問題系統性出現:++**無法區分"正確"和"看似正確"**:一個函數在代碼審查時看起來完全正確——語法對、邏輯通。但運行時因為邊界條件處理錯誤,在特定輸入下產生了不正確結果。只有運行時追蹤能揭示實際執行路徑偏離了預期。就像一個演員排練時臺詞全對了,但上臺演出時燈光一打,表情和走位全都變了——你不看現場是發現不了的。++**評估變成玄學**:沒有評分標準和驗收條件時,評估者(人或 agent)依賴隱式假設。同一個輸出,不同評估者可能給出截然不同的評價。質量評估不可復現。就像體操比賽沒有評分標準——這個裁判覺得你的動作優雅,那個裁判覺得你落地不穩,誰說了算?++**重試變成盲猜**:agent 不知道為什麼失敗時,重試方向是隨機的。它可能在錯誤的方向上反覆嘗試——修復了不相關的代碼路徑而忽略真正的故障根源。就像你開車發現車跑偏了,但你沒有儀表盤——你猜是輪胎的問題換了輪胎,實際是方向盤的 alignment 出了問題。每次盲重試都消耗 token 和時間。++**會話交接信息斷崖**:當未完成的工作移交給下一個會話時,缺乏可觀測性意味著新會話必須從零診斷系統狀態。Anthropic 的長期運行 agent 觀察表明,這種重複診斷可能佔會話總時間的 30-50%。就像換班司機上車發現沒有交接記錄——他得花半小時檢查油量、胎壓、發動機狀態才能出發。++## Claude Code 的真實場景++想象一個使用"計劃者-生成者-評估者"三角色工作流的 harness,執行"為應用添加暗色模式"任務。++**沒有儀表盤**:計劃者輸出模糊描述。生成者根據模糊描述實現暗色模式,但和計劃者的隱式預期不一致。評估者基於自己的隱式標準拒絕,但說不出具體哪裡不對——"感覺不太對"。生成者基於模糊拒絕理由盲重試。循環 3-4 次,總耗時約 45 分鐘,最終勉強產出。++**有完整儀表盤**:計劃者輸出衝刺合同——列明要改哪些組件、每個組件的驗證標準、排除項(不處理打印樣式)。生成者按合同實現。運行時可觀測性記錄每個組件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用——"按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)"。一次迭代出高質量結果,總耗時約 15 分鐘。++效率差 3 倍。區別只在可觀測性——給車裝上了儀表盤。++## 雙層可觀測性++可觀測性不是"多打點日誌"那麼簡單。它分兩層,缺一不可:++```mermaid+flowchart LR+ Contract["先把這次任務寫清楚<br/>改哪些檔案 / 不改哪些部分 / 怎么算通過"] --> Generator["生成器"]+ Generator --> Signals["執行時收集<br/>日誌 / 追踪 / 健康檢查"]+ Contract --> Review["按檢查表逐项看<br/>功能 / 測試 / 邊界"]+ Signals --> Review+ Review --> Verdict["指出哪一项没過<br/>以及应該去改哪裡"]+ Verdict --> Generator+```++**運行時可觀測性**:系統層的信號——日誌、追蹤、進程事件、健康檢查。回答"系統做了什麼"。這是你車上的儀表盤——速度、油量、發動機溫度。++**過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答"為什麼這個變更應該被接受"。這是你的導航系統——不光知道現在在哪,還知道為什麼走這條路。++## 核心概念++- **運行時可觀測性**:系統層的信號——日誌、追蹤、進程事件、健康檢查。回答"系統做了什麼"。+- **過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答"為什麼這個變更應該被接受"。+- **任務軌跡**:一個任務從開始到完成的完整決策路徑記錄,類似分佈式系統中的請求追蹤。agent 的每一步操作及其上下文都被記錄。就像黑匣子——出了問題可以回放完整過程。+- **衝刺合同**:編碼開始前協商的短期協議——明確任務範圍、驗證標準、排除項。是過程可觀測性的核心工具。+- **評估評分標準**:把質量評估從主觀判斷變成基於證據的結構化評分。使不同評估者對同一輸出產生相似結論。就像體操比賽的評分標準——有了它,十個裁判的分才不會差太遠。+- **雙層可觀測性**:系統層和過程層同時設計、相互增強。運行時信號解釋行為,過程工件解釋意圖。++## 為什麼 agent 自己解決不了這個問題++你可能在想:"agent 不能自己打日誌嗎?" 問題在於:++1. **agent 不知道它不知道什麼**——它不會主動記錄自己沒意識到需要的信號。就像你不知道油箱快漏了的時候,你不會去看油量表——因為你壓根不知道該看。+2. **日誌格式不統一**——不同會話用不同的日誌格式,無法做系統化分析。就像十個司機各寫各的交接記錄,格式都不一樣,下一個司機看不懂。+3. **過程可觀測性不是日誌能解決的**——衝刺合同和評分標準是結構化的工件,需要 harness 層面的支持。不是多 print 幾行就能搞定的。++## 怎麼裝儀表盤++### 1. 在 harness 裡內置運行時信號採集++不要依賴 agent 自己打日誌。harness 應該自動採集以下信號:++- **應用生命週期**:啟動、就緒、運行、關閉各階段狀態+- **功能路徑執行**:關鍵路徑的執行記錄,包括入口、檢查點和出口+- **數據流**:數據在組件間的流轉記錄+- **資源利用**:異常的資源使用模式(如內存持續增長)+- **錯誤和異常**:完整的錯誤上下文,不只是錯誤消息++### 2. 實施衝刺合同++在每個任務開始前,生成者和評估者(可能是同一個 agent 的不同調用)協商一份合同——就像施工隊開工前籤的施工協議:++```markdown+# 冲刺合同: 暗色模式支持++## 範圍+- 修改主题切換组件+- 更新全局 CSS 變量+- 添加暗色模式測試++## 驗證標準+- 每個组件的视觉回歸測試通過+- 主流程端到端測試通過+- 无样式闪烁 (FOUC)++## 排除项+- 不處理打印样式+- 不處理第三方组件暗色模式+```++### 3. 建立評估評分標準++把"好不好"變成可量化的評分——就像給體操比賽定評分標準:++```markdown+# 評分標準++| 维度 | A | B | C | D |+|------|---|---|---|---|+| 程式碼正确性 | 所有測試通過 | 主流程通過 | 部分通過 | 编译失敗 |+| 架构合规 | 完全合规 | 轻微偏离 | 明顯偏离 | 严重违反 |+| 測試覆盖 | 主流程+邊缘 | 仅主流程 | 仅有骨架 | 无測試 |+```++### 4. 用 OpenTelemetry 標準化++為每個 harness 會話創建一個 trace,每個任務創建一個 span,每個驗證步驟創建子 span。使用標準屬性標註關鍵信息。這樣可觀測性數據可以和標準工具鏈(Jaeger、Zipkin)集成。++## Anthropic 的三 agent 架構實驗++Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們用三種架構跑同一個任務("用 Web Audio API 做一個瀏覽器端 DAW"),記錄了詳細的階段數據:++| Agent 和階段 | 時長 | 成本 |+|------------|------|------|+| Planner(規劃者) | 4.7 分鐘 | $0.46 |+| Build 第 1 輪 | 2 小時 7 分鐘 | $71.08 |+| QA 第 1 輪 | 8.8 分鐘 | $3.24 |+| Build 第 2 輪 | 1 小時 2 分鐘 | $36.89 |+| QA 第 2 輪 | 6.8 分鐘 | $3.09 |+| Build 第 3 輪 | 10.9 分鐘 | $5.88 |+| QA 第 3 輪 | 9.6 分鐘 | $4.06 |+| **總計** | **3 小時 50 分鐘** | **$124.70** |++三個 agent 各司其職,每個都有明確的可觀測性角色:++**Planner(規劃者)**:接收一段 1-4 句話的用戶需求,擴展成完整產品規格。被要求"大膽設定範圍"並且"專注於產品上下文和高層技術設計,而不是詳細的技術實現"。原因是:如果 planner 過早指定了粒度技術細節且搞錯了,錯誤會級聯到下游實現。更好的做法是約束交付物,讓 agent 在執行中自己找到路徑。就像建築設計師只畫效果圖和結構圖,不規定每塊磚怎麼砌。++**Generator(生成者)**:按 sprint 逐個功能實現。每個 sprint 前和 evaluator 協商一份 sprint 合同——約定這個功能塊"做完"的標準。然後按合同實現,自評後交給 QA。按合同施工,不按感覺施工。++**Evaluator(評估者)**:用 Playwright MCP 像用戶一樣點擊運行中的應用,測試 UI 功能、API 端點和數據庫狀態。對每個 sprint 按四個維度評分——產品深度、功能性、視覺設計和代碼質量。每個維度有硬性閾值,任一不達標則 sprint 失敗,generator 收到詳細反饋後修復。就像驗收工程師拿著驗收標準逐項檢查——不達標就打回去重做。++QA 第 1 輪反饋的示例——"這是一個視覺上令人印象深刻的應用,AI 集成工作良好,但核心 DAW 功能有幾個是展示性的,沒有交互深度:剪輯不能拖拽/移動,沒有樂器 UI 面板(合成器旋鈕、鼓墊),沒有視覺效果編輯器(EQ 曲線、壓縮器儀表)"。這些不是邊緣情況——它們是讓 DAW 可用的核心交互。具體的、有證據的反饋,不是"感覺不對"。++Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題,然後說服自己這些問題不嚴重,最終批準工作。調校方式是:讀 evaluator 的日誌,找到它的判斷和人類判斷分叉的地方,更新 QA 的 prompt 解決那些問題。經過幾輪這種開發循環,evaluator 的評分才變得合理。就像訓練一個新驗收工程師——一開始他太寬容,出了幾次事故後學會了嚴格。++> 來源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)++## 關鍵要點++- **可觀測性是 harness 的架構屬性**——不是事後添加的功能,而是設計時必須考慮的核心能力。儀表盤不是可選配件,是出廠標配。+- **雙層可觀測性缺一不可**——運行時信號解釋"發生了什麼",過程工件解釋"為什麼這樣做"。速度表和導航系統各有各的用處。+- **衝刺合同前置對齊工作**——防止"生成者做了評估者因可預見原因立即拒絕的東西"。施工協議要在開工前籤,不是完工後補。+- **評分標準讓評估可復現**——不同評估者對同一輸出產生相似評分。有了評分標準,十個裁判的分才不會差太遠。+- **可觀測性缺失導致 30-50% 的會話時間浪費在重複診斷上**。++## 延伸閱讀++- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — 現代可觀測性工程的理論和實踐框架+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — 大規模分佈式追蹤的開創性實踐+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — 引入衝刺合同和評估評分標準+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — 可觀測性在生產系統中的系統化應用++## 練習++1. **可觀測性差距分析**:審查你當前的 harness,評估系統層和過程層可觀測性。找出無法從現有信號區分的系統狀態,提出補充方案。++2. **衝刺合同實踐**:為一個真實任務寫衝刺合同。讓 agent 按合同執行,對比沒有合同時的效率和質量差異。++3. **任務軌跡構建**:記錄一個完整編碼任務中 agent 的每一步操作。用 OpenTelemetry 語義約定標註。分析軌跡中的信息瓶頸——哪些步驟的決策缺乏足夠的信號支持。diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.mdnew file mode 100644index 0000000..d895097--- /dev/null+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md@@ -0,0 +1,18 @@+# 基準比較模板++Harness A:++- 完成率+- 平均重試次數+- 人工審查前捕捉到的錯誤數++Harness B:++- 完成率+- 平均重試次數+- 人工審查前捕捉到的錯誤數++解讀:++- 哪個 harness 改變了結果?+- 哪個 harness 改變了獲得結果的成本?diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.tsnew file mode 100644index 0000000..0388cad--- /dev/null+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts@@ -0,0 +1,216 @@+/**+ * benchmark-runner.ts+ *+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),+ * "executes" each task, records timing and pass/fail, outputs a comparison+ * report showing which tasks pass and which fail.+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts+ */++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BenchmarkTask {+ id: string;+ name: string;+ category: string;+ passCriteria: string[];+ expectedDurationMs: number;+ // Simulated actual results+ actualDurationMs: number;+ actualPass: boolean;+ failureReason?: string;+}++interface BenchmarkResult {+ id: string;+ name: string;+ category: string;+ criteriaTotal: number;+ criteriaPassed: number;+ pass: boolean;+ expectedMs: number;+ actualMs: number;+ durationDelta: number;+ failureReason?: string;+}++// ---------------------------------------------------------------------------+// Benchmark task definitions+// ---------------------------------------------------------------------------++const benchmarkTasks: BenchmarkTask[] = [+ {+ id: "bench-001",+ name: "Import markdown document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 100,+ actualDurationMs: 95,+ actualPass: true,+ },+ {+ id: "bench-002",+ name: "Import PDF document",+ category: "Document Pipeline",+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],+ expectedDurationMs: 200,+ actualDurationMs: 310,+ actualPass: false,+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",+ },+ {+ id: "bench-003",+ name: "Ask grounded question",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],+ expectedDurationMs: 500,+ actualDurationMs: 480,+ actualPass: true,+ },+ {+ id: "bench-004",+ name: "Ask question with no relevant docs",+ category: "Q&A Pipeline",+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],+ expectedDurationMs: 400,+ actualDurationMs: 420,+ actualPass: false,+ failureReason: "Model hallucinated a citation instead of saying 'no results'",+ },+ {+ id: "bench-005",+ name: "Delete imported document",+ category: "Document Pipeline",+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],+ expectedDurationMs: 150,+ actualDurationMs: 145,+ actualPass: true,+ },+ {+ id: "bench-006",+ name: "Concurrent user access",+ category: "Security",+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],+ expectedDurationMs: 300,+ actualDurationMs: 850,+ actualPass: false,+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",+ },+ {+ id: "bench-007",+ name: "Session continuity after restart",+ category: "Reliability",+ passCriteria: ["State persisted", "Session recovers", "No data loss"],+ expectedDurationMs: 200,+ actualDurationMs: 180,+ actualPass: true,+ },+ {+ id: "bench-008",+ name: "API rate limiting",+ category: "Security",+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],+ expectedDurationMs: 100,+ actualDurationMs: 100,+ actualPass: true,+ },+];++// ---------------------------------------------------------------------------+// Execution simulation+// ---------------------------------------------------------------------------++function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {+ return tasks.map((task) => ({+ id: task.id,+ name: task.name,+ category: task.category,+ criteriaTotal: task.passCriteria.length,+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),+ pass: task.actualPass,+ expectedMs: task.expectedDurationMs,+ actualMs: task.actualDurationMs,+ durationDelta: task.actualDurationMs - task.expectedDurationMs,+ failureReason: task.failureReason,+ }));+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ console.log("\n" + "=".repeat(100));+ console.log(" BENCHMARK RUNNER -- Task Execution Report");+ console.log("=".repeat(100));++ const results = executeBenchmark(benchmarkTasks);++ // Detailed results+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;+ console.log("\n" + header);+ console.log(sep);++ for (const r of results) {+ const passLabel = r.pass ? "PASS" : "FAIL";+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;+ const marker = r.pass ? " " : ">>";++ console.log(+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`+ );+ }++ // Failure details+ const failures = results.filter((r) => !r.pass);+ if (failures.length > 0) {+ console.log("\n" + "-".repeat(100));+ console.log(" FAILURE DETAILS");+ console.log("-".repeat(100));+ for (const f of failures) {+ console.log(`\n [${f.id}] ${f.name}`);+ console.log(` Category: ${f.category}`);+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);+ }+ }++ // Summary+ console.log("\n" + "=".repeat(100));+ console.log(" SUMMARY BY CATEGORY");+ console.log("=".repeat(100) + "\n");++ const categories = [...new Set(results.map((r) => r.category))];+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;+ console.log(catHeader);+ console.log(catSep);++ for (const cat of categories) {+ const catResults = results.filter((r) => r.category === cat);+ const catPassed = catResults.filter((r) => r.pass).length;+ const catFailed = catResults.filter((r) => !r.pass).length;+ const rate = Math.round((catPassed / catResults.length) * 100);++ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);+ }++ // Overall+ const totalPassed = results.filter((r) => r.pass).length;+ const totalFailed = results.filter((r) => !r.pass).length;+ console.log("\n" + "-".repeat(100));+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);+ console.log("=".repeat(100) + "\n");+}++run();diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdnew file mode 100644index 0000000..6f81fef--- /dev/null+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -0,0 +1,9 @@+# 清理迴圈範例++週期性清理任務:++- 掃描過時的文件+- 掃描結構性違規+- 更新品質評分+- 開啟針對性的清理 PR+- 清理後重新執行固定的基準切片diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.tsnew file mode 100644index 0000000..6b35905--- /dev/null+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts@@ -0,0 +1,336 @@+/**+ * cleanup-scanner.ts+ *+ * Scans a project directory for stale artifacts, dead code, structural+ * violations, and outputs a cleanup report. Helps enforce the "clean state+ * at end of every session" principle.+ *+ * Usage:+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]+ * (defaults to current working directory)+ *+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface ScanResult {+ category: string;+ check: string;+ severity: "critical" | "warning" | "info";+ found: string[];+ description: string;+}++// ---------------------------------------------------------------------------+// Scanner checks+// ---------------------------------------------------------------------------++interface ScannerCheck {+ category: string;+ name: string;+ severity: "critical" | "warning" | "info";+ description: string;+ scan: (dir: string) => string[];+}++function createChecks(): ScannerCheck[] {+ return [+ {+ category: "Stale Artifacts",+ name: "Temporary files (*.tmp, *.bak, *.swp)",+ severity: "warning",+ description: "Leftover temp files from editing or processing",+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),+ },+ {+ category: "Stale Artifacts",+ name: "Debug/log files in source",+ severity: "warning",+ description: "Log files that should not be in the source tree",+ scan: (dir) => {+ const found: string[] = [];+ const logPatterns = [".log"];+ for (const p of findFiles(dir, logPatterns)) {+ // Only flag log files in source directories+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {+ found.push(p);+ }+ }+ return found;+ },+ },+ {+ category: "Dead Code",+ name: "Unused imports (placeholder detection)",+ severity: "info",+ description: "Files that may contain unused code (heuristic scan)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app"];+ for (const srcDir of srcDirs) {+ const srcPath = path.join(dir, srcDir);+ if (fs.existsSync(srcPath)) {+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "Missing .gitignore",+ severity: "warning",+ description: "No .gitignore file found -- risk of committing build artifacts",+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],+ },+ {+ category: "Structural Violations",+ name: "Build artifacts in source",+ severity: "critical",+ description: "Compiled output (dist/, build/) mixed with source",+ scan: (dir) => {+ const found: string[] = [];+ // Check if dist/ or build/ exists inside src/+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];+ for (const d of dirs) {+ if (fs.existsSync(path.join(dir, d))) {+ found.push(d + "/");+ }+ }+ return found;+ },+ },+ {+ category: "Structural Violations",+ name: "node_modules in source tree",+ severity: "critical",+ description: "node_modules directory found outside root (nested dependency)",+ scan: (dir) => {+ const found: string[] = [];+ const srcDirs = ["src", "lib", "app", "test", "tests"];+ for (const srcDir of srcDirs) {+ const nmPath = path.join(dir, srcDir, "node_modules");+ if (fs.existsSync(nmPath)) {+ found.push(srcDir + "/node_modules/");+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Uncommitted changes indicator",+ severity: "info",+ description: "Checks for common artifacts of incomplete sessions",+ scan: (dir) => {+ const found: string[] = [];+ const indicators = [+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",+ "debug.ts", "test-manual.ts", "temp.ts",+ ];+ for (const f of indicators) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ {+ category: "Session Cleanliness",+ name: "Empty directories",+ severity: "info",+ description: "Empty directories that may be leftover from incomplete work",+ scan: (dir) => {+ const found: string[] = [];+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];+ for (const d of commonDirs) {+ const dp = path.join(dir, d);+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {+ try {+ const contents = fs.readdirSync(dp);+ if (contents.length === 0) {+ found.push(d + "/");+ }+ } catch {+ // Skip directories we can't read+ }+ }+ }+ return found;+ },+ },+ {+ category: "Configuration",+ name: "Environment files in source",+ severity: "critical",+ description: ".env files that may contain secrets",+ scan: (dir) => {+ const found: string[] = [];+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];+ for (const f of envFiles) {+ if (fs.existsSync(path.join(dir, f))) {+ found.push(f);+ }+ }+ return found;+ },+ },+ ];+}++// ---------------------------------------------------------------------------+// Helper functions+// ---------------------------------------------------------------------------++function findFiles(dir: string, extensions: string[]): string[] {+ const found: string[] = [];++ function walk(current: string, depth: number): void {+ if (depth > 4) return; // Limit recursion depth+ try {+ const entries = fs.readdirSync(current, { withFileTypes: true });+ for (const entry of entries) {+ // Skip common non-source directories+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {+ continue;+ }++ const fullPath = path.join(current, entry.name);+ const relativePath = path.relative(dir, fullPath);++ if (entry.isDirectory()) {+ walk(fullPath, depth + 1);+ } else if (entry.isFile()) {+ if (extensions.some((ext) => entry.name.endsWith(ext))) {+ found.push(relativePath);+ }+ }+ }+ } catch {+ // Skip directories we can't read+ }+ }++ walk(dir, 0);+ return found;+}++function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {+ try {+ const entries = fs.readdirSync(dir, { withFileTypes: true });+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);+ }+ continue;+ }++ const fullPath = path.join(dir, entry.name);+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {+ continue;+ }++ try {+ const content = fs.readFileSync(fullPath, "utf-8");+ const lines = content.split("\n");+ for (let i = 0; i < Math.min(lines.length, 50); i++) {+ for (const pattern of patterns) {+ if (lines[i].includes(pattern)) {+ const relative = path.relative(baseDir, fullPath);+ results.push(`${relative}:${i + 1} contains ${pattern}`);+ }+ }+ }+ } catch {+ // Skip files we can't read+ }+ }+ } catch {+ // Skip directories we can't read+ }+}++// ---------------------------------------------------------------------------+// Reporting+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");+ console.log("=".repeat(90));+ console.log(` Scanning: ${targetDir}\n`);++ const checks = createChecks();+ const results: ScanResult[] = [];++ for (const check of checks) {+ const found = check.scan(targetDir);+ results.push({+ category: check.category,+ check: check.name,+ severity: check.severity,+ found,+ description: check.description,+ });+ }++ // Report+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;+ console.log(header);+ console.log(sep);++ for (const r of results) {+ const count = r.found.length;+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";++ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);+ }++ // Summary+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);+ const clean = results.filter((r) => r.found.length === 0);++ console.log("\n" + "=".repeat(90));+ console.log(" CLEANUP SUMMARY");+ console.log("=".repeat(90) + "\n");++ console.log(` Critical issues: ${criticals.length}`);+ console.log(` Warnings: ${warnings.length}`);+ console.log(` Info items: ${infos.length}`);+ console.log(` Clean checks: ${clean.length}/${results.length}`);++ if (criticals.length > 0) {+ console.log("\n ACTION REQUIRED (Critical):");+ for (const c of criticals) {+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);+ console.log(` ${c.description}`);+ }+ }++ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);+ if (totalIssues === 0) {+ console.log("\n Project is in a clean state. No issues found.\n");+ } else {+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);+ }+}++run();diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdnew file mode 100644index 0000000..f8f4fd0--- /dev/null+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md@@ -0,0 +1,8 @@+# 第 12 講的程式碼++此資料夾用於以下範例:++- 基準切片+- 清理任務+- 熵減範例+- 可重複的 harness 執行diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdnew file mode 100644index 0000000..bb5193e--- /dev/null+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -0,0 +1,198 @@+[English Version →](../../../en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)++> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)+> 實戰練習:[Project 06. 搭建一套完整的 agent 工作環境](./../../projects/project-06-runtime-observability-and-debugging/index.md)++# 第十二講. 每次會話結束前都做好交接++你的 agent 跑了一下午,改了 20 個檔案,提交了代碼,會話結束。下一個 agent 會話開始,一上來就發現:構建失敗了、測試紅了、臨時調試檔案到處都是、功能清單沒更新、進度完全不清楚。新會話的前 30 分鐘全花在"搞清楚上一個會話到底幹了什麼"上。++這就像大學宿舍——你不倒垃圾,下一個室友進來就得替你收拾。他本來的計劃是複習考試,結果先花半小時收拾你留下的爛攤子。更要命的是,收拾完了他也不想複習了——環境太差,心情也差。++OpenAI 和 Anthropic 都明確指出:**長期可靠性取決於操作紀律,不僅是單次運行的成功。** 每個會話結束時的狀態質量,直接決定下一個會話的效率。++## 熵增是默認狀態++Lehman 的軟件演化定律告訴我們:持續變更的系統,除非主動管理,否則複雜性必然增加。這對 AI 編碼 agent 尤其成立——agent 每次會話都會引入變更,如果不在退出時清理,技術債務會指數級累積。宿舍不打掃,髒衣服和外賣盒只會越堆越多,不會自己消失。++OpenAI 在 5 個月的 Codex 實驗中觀察到:**agent 會複製倉庫中已有的模式——即使那些模式是不均勻的或次優的。** 隨著時間的推移,這種複製必然導致漂移。就像宿舍裡的公共區域——第一個人在桌上放了一個杯子,第二個人覺得"反正已經亂了"又放了一個,一週後桌上堆滿了。++OpenAI 團隊最初花每週五(20% 的工作時間)手動清理 "AI slop"。不出所料,這種方式不可擴展。就像宿舍每週大掃除一次——其他六天的髒亂差還是得忍。他們的解決方案是:++1. **把"黃金原則"編碼進倉庫**:比如"優先使用共享工具包而非手寫的 ad-hoc 輔助函數"(保持不變量集中)、"不要 YOLO 式地猜數據結構"(驗證邊界或依賴類型化 SDK)。這些原則是具體的、機械的、可自動檢查的。+2. **建立週期性的清理流程**:一組後臺 Codex 任務定期掃描偏差,更新質量評分,開針對性的重構 PR。大多數可以在一分鐘內審查並自動合併。就像宿舍安裝了自動掃地機器人——不用你動手,定期清理。+3. **人類品味捕獲一次,持續執行**:審查意見、重構 PR、用戶側 bug 都被轉化為文檔更新或直接編碼到工具中。當文檔不夠用時,把規則提升為代碼。就像把宿舍公約從"口頭約定"變成"貼在門上的檢查表"。++這個機制就像垃圾回收——技術債是高息貸款,持續小額還清幾乎總是比攢到一次性爆發好得多。++> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)++## 清潔狀態:不只看地上有沒有垃圾++清潔狀態不是單一的"代碼能編譯"。代碼能無錯構建——這是最基本的,下一個會話不應該先修構建錯誤。就像你搬出去的時候水電不能是斷的。所有測試也得通過,包括會話之前就存在的測試——會話有責任不破壞已有功能。而且要在 CI 環境驗證,不是"在我機器上通過"。++```mermaid+flowchart LR+ Work["功能工作已完成"] --> Build{"建構通過?"}+ Build -->|是| Test{"測試通過?"}+ Build -->|否| Fix["先修好再退出"]+ Test -->|是| Record["更新功能清單 + 進度"]+ Test -->|否| Fix+ Record --> Cleanup["清理临時工件 / 調試程式碼"]+ Cleanup --> Startup{"標準啟動路徑可用?"}+ Startup -->|是| Clean["干净交接"]+ Startup -->|否| Fix+ Fix --> Build+```++但這還不夠。當前進度必須記錄在機器可讀的工件中——已完成的子任務和通過標準、進行中但未完成的子任務和當前狀態、尚未開始的子任務。好的進度記錄減少 60-80% 的會話啟動診斷時間。調試日誌、臨時檔案、註釋掉的代碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個會話的認知負擔。標準啟動路徑也必須可用——下一個會話能不能不人工干預就開始工作?環境初始化、代碼庫加載、上下文獲取、任務選擇,這些路徑不能被破壞。++```mermaid+flowchart LR+ Dirty["這次退出時<br/>測試是红的、临時檔案没删、進度也没寫"] --> Diagnose["下個會話先花時间<br/>搞清楚發生了什么"]+ Diagnose --> Fragile["接着在一個很乱的倉庫上继續改"]+ Fragile --> More["更多調試檔案、更多坏檢查、<br/>更多說不清的進度"]+ More --> Dirty++ Clean["這次退出前<br/>測試是绿的、進度寫了、临時檔案删了"] --> Fast["下個會話打開倉庫就能继續寫程式碼"]+ Fast --> Stable["不用先救火"]+ Stable --> Clean+```++## 核心概念++- **清潔狀態**:會話結束時系統滿足五個條件——構建通過、測試通過、進度已記錄、無過時工件、啟動路徑可用。缺一個都不算"做完"。+- **會話完整性**:類比數據庫事務——要麼全部提交併留下清潔狀態,要麼回滾到上一致狀態。沒有中間地帶。+- **質量文檔**:對每個模塊的質量等級做持續記錄的活躍工件。不是一次性評估,而是跟蹤代碼庫是變強了還是變弱了。+- **清理循環**:定期的維護會話,目標是系統性減少代碼庫中的熵。不是緊急修復,而是常規運維——就像宿舍的每週值日表。+- **harness 簡化**:隨著模型能力提升,定期移除不再必要的 harness 組件。今天必要的約束,三個月後可能是多餘的開銷。+- **冪等清理**:清理操作無論執行多少次都產生相同結果。確保清理在失敗重試場景中仍然安全。++## "以後再清理"是永遠不清理++最常見的心理陷阱是"這次來不及清理了,下次再弄"。但下次的 agent 不知道你上次留下了什麼——它看到的是一堆混亂的代碼和不確定的狀態。它會花大量時間推斷"這堆代碼裡哪些是有意的,哪些是臨時的"。++更糟的是,每個會話都有自己的任務目標。新會話來的時候是要做新功能的,不是來清理上一個會話的爛攤子的。它會忽略混亂直接開始新工作,然後在混亂的基礎上引入更多混亂。這是熵增的正反饋循環——就像宿舍越亂你越不想收拾,越不收拾越亂,最後誰都不想回宿舍了。++數據為證。一個使用 agent 持續開發 12 周的項目,沒有清潔策略的情況下:++- 第 1 周:構建通過率 100%,測試通過率 100%,新會話啟動 5 分鐘+- 第 4 周:構建 95%,測試 92%,啟動 15 分鐘+- 第 8 周:構建 82%,測試 78%,啟動 35 分鐘+- 第 12 周:構建 68%,測試 61%,啟動 60+ 分鐘++同樣的項目,有清潔策略的情況下:++- 第 1 周:100%,100%,5 分鐘+- 第 12 周:97%,95%,9 分鐘++12 周後,構建通過率差 29 個百分點,新會話啟動時間差 85%。這不是理論推導,是實際可觀測到的差異。每週不倒垃圾的宿舍和每週倒垃圾的宿舍,12 周後的差距是驚人的。++## 怎麼做++### 1. 清潔狀態是完成的必要條件++在 harness 裡明確定義:**會話完成 = 任務通過驗證 AND 清潔狀態檢查通過。** 缺任何一個,會話不算完成。在 CLAUDE.md 裡寫:++```+## 會話退出檢查清單+- [ ] 建構通過 (npm run build)+- [ ] 所有測試通過 (npm test)+- [ ] 功能清單已更新+- [ ] 无調試程式碼残留 (console.log, debugger, TODO)+- [ ] 標準啟動路徑可用 (npm run dev)+```++### 2. 雙模式清理策略++結合兩種清理模式:++**即時清理(每個會話結束時)**:清理本次會話創建的臨時工件、更新功能清單狀態、確保構建和測試通過。這是"引用計數式"清理——用完就清。就像吃完飯馬上洗碗,不留到第二天。++**定期清理(每週一次)**:全系統掃描——處理累積的結構性問題、更新質量文檔、運行基準測試檢測漂移。這是"追蹤式"清理——定期做一次大掃除。++### 3. 維護質量文檔++質量文檔是對每個模塊持續評分的活躍工件——就像宿舍的衛生檢查評分表:++```markdown+# 品質文檔++## 使用者認證模块 (品質: A)+- 驗證通過: 是+- agent 可理解: 是+- 測試稳定性: 稳定+- 架构邊界: 合规+- 程式碼規範: 遵循++## 支付模块 (品質: C)+- 驗證通過: 部分(支付回調未測試)+- agent 可理解: 困难(逻辑分散在 3 個檔案)+- 測試稳定性: 不稳定(2 個 flaky 測試)+- 架构邊界: 有违规+- 程式碼規範: 部分遵循+```++新會話讀這個文檔就知道優先處理哪裡。質量評分最低的模塊先修。就像衛生檢查表上標記了"需要重點打掃的區域"——下一個值日生知道重點在哪裡。++### 4. 定期簡化 harness++harness 裡的每個組件之所以存在,是因為模型無法獨立做好某件事。但隨著模型改進,這些假設會過時。就像你大一的時候需要學長帶著選課,到了大三你自己就知道怎麼選了——學長的作用變小了,但有些事情你還是需要問。++Anthropic 的實驗直接展示了這一點。他們最初的 harness 包含 sprint 拆分機制——把工作分成小塊讓 Sonnet 4.5 逐個完成。當 Opus 4.6 發佈後,模型的原生能力已經可以自主處理工作分解,sprint 構造變成了不必要的開銷。移除後,builder agent 能連續工作超過兩小時而不會跑偏,反而更流暢。++但 evaluator 的情況不同。即使 Opus 4.6 能力更強,在任務接近模型能力邊界時,evaluator 仍然提供了實際價值——捕獲 generator 的遺漏功能和存根實現。這意味著 evaluator 不是一個固定的是/否決策,而是取決於任務難度相對於模型能力的位置。++**推薦做法**:每月挑一個 harness 組件,暫時禁用它,跑基準任務。如果結果沒退化,永久移除。如果退化了,恢復或用更輕量的替代。就像定期檢查宿舍公約——大四了還在執行"每天 10 點熄燈"就不太合理了。++一個更具體的原則:**隨著模型改進,harness 的有趣組合不是變少了,而是移動了。** 以前必須解決的問題被模型能力覆蓋了,但新的能力邊界打開了以前不可能的 harness 設計。AI 工程師的工作是持續找到下一個有價值的組合。++### 5. 清理操作必須冪等++清理腳本要能安全地重複執行——就像打掃衛生,掃兩遍比掃一遍更乾淨,但不會更髒:++```bash+# 幂等的清理操作+rm -f /tmp/debug-*.log # -f 确保檔案不存在時不报錯+git checkout -- .env.local # 恢复到已知狀態+npm run test # 驗證清理未破坏功能+```++### 6. 高吞吐量改變了 merge 哲學++當 agent 的產出遠超人類審查能力時,傳統的 merge 哲學需要調整。OpenAI 團隊的經驗:在一個 agent 每天開 3.5 個 PR(且後來增加到更多)的環境裡,最小化阻塞式 merge gate 是正確的。PR 應該短命。測試 flake 通常用後續運行解決,而不是無限期阻塞進度。在一個修正成本很低、等待成本很高的系統裡,快速前進 + 快速修正是比緩慢確認更好的策略。++**注意**:這在低產出環境裡是不負責任的。但在 agent 產出遠超人類注意力的環境裡,這往往是正確的權衡。關鍵判斷標準:**修正一個 bug 的平均成本 vs 等待人類審查一個 PR 的平均成本。** 前者低於後者時,快速合併是對的。++## 實際案例++一個使用 agent 持續開發的 Electron 應用,12 周演化過程的對比數據:++**無清潔策略(對照組)**——從不倒垃圾的宿舍:第 12 周,構建通過率 68%,測試通過率 61%,新會話啟動 60+ 分鐘,過時工件 103 個。++**有清潔策略(實驗組)**——每天值日的宿舍:每個會話結束時執行完整清潔檢查 + 每週清理循環。第 12 周,構建通過率 97%,測試通過率 95%,新會話啟動 9 分鐘,過時工件 11 個。++到第 12 周,實驗組的構建通過率比對照組高 29 個百分點,測試通過率高 34 個百分點,新會話啟動時間減少 85%。每天多花 5 分鐘打掃衛生,12 周後省下了幾十個小時的混亂時間。++## 關鍵要點++- **清潔狀態是會話完成的必要條件**——不是可選的善後工作,是"完成定義"的一部分。你不倒垃圾,下一個室友就得替你倒。+- **五個維度缺一不可**——構建、測試、進度、工件、啟動,每個都要顯式檢查。+- **質量文檔讓代碼庫健康可追蹤**——知道哪裡在退化才能主動修復。衛生檢查表不是形式主義,是讓你知道哪塊地還沒拖。+- **定期簡化 harness**——隨著模型能力提升,移除不再必要的約束。大四了就別執行大一的宿舍公約了。+- **"以後再清理"等於永遠不清理**——熵增是默認狀態,只有主動的清潔操作才能對抗它。++## 延伸閱讀++- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — 代碼清潔性的系統化原則+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 可重複性作為 harness 設計的核心要求+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — 清潔會話退出對長期可靠性的關鍵作用+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — 軟件演化定律,證明系統複雜性在無主動維護時必然增長++## 練習++1. **清潔狀態檢查表**:為你的代碼庫設計一個會話退出檢查表,涵蓋五個維度。在 5 個連續會話中應用,記錄每個維度上的違反次數。++2. **基準對比實驗**:固定任務集,兩種 harness 變體(有/無清潔狀態要求)各跑一遍。比較完成率、重試次數和缺陷逃逸率。++3. **harness 簡化實踐**:選一個 harness 組件,暫時禁用,跑基準任務。比較有無該組件的結果。決定保留、移除還是替換。diff --git a/docs/zh-TW/projects/index.md b/docs/zh-TW/projects/index.mdnew file mode 100644index 0000000..beb52de--- /dev/null+++ b/docs/zh-TW/projects/index.md@@ -0,0 +1,23 @@+# 歡迎來到專案實戰++這裡是 Learn Harness Engineering 的動手實踐部分。僅僅閱讀講義是不夠的,你需要親自搭建環境,觀察 Codex 或 Claude Code 等 Agent 在不同規則下的真實表現。++## 專案概覽++本課程包含 6 個漸進式的實戰專案,帶你從零開始建構一個完整的 Agent 工作環境:++1. **提示詞驅動 vs 規則驅動**:對比一個純 Prompt 驅動的 Agent 和帶有基礎 Harness 的 Agent 在表現上的差異。+2. **讓專案可讀並接住上次工作**:學習如何重構程式碼倉庫結構,使其對 AI 更加友好,並建立工作交接機制。+3. **跨會話工作連續性**:設計狀態檔案和初始化腳本,讓 Agent 可以在多次對話中斷後無縫恢復工作。+4. **執行回饋與行為修正**:引入執行時回饋機制,讓 Agent 能夠自己檢查程式碼是否能跑通,並修正錯誤。+5. **工作評審與自我驗證**:建立獨立的評審與驗證環節,防止 Agent 產生「幻覺」或提前宣告勝利。+6. **綜合 Agent 工作環境**:搭建一套完整的、帶有可觀測性的最終 Agent 工作環境(綜合演練)。++## 如何進行++每個專案資料夾中通常包含:+- `starter/`:你的起始工作區。+- `solution/`:參考的最終實作(如果你卡住了可以參考)。+- 相關的指導檔案,說明本次任務的具體背景和目標。++請使用你習慣的 AI Coding Agent(如 Claude Code、Cursor、Trae 等)在每個專案的 `starter/` 目錄下完成任務。diff --git a/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.mdnew file mode 100644index 0000000..22bbe76--- /dev/null+++ b/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md@@ -0,0 +1,70 @@+# Project 01. 只寫提示詞讓 agent 做,和定好規則再讓它做,差多少++> 相關講義:[L01. 模型能力強,不等於執行可靠](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [L02. Harness 到底是什麼](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)+> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)++## 你要做什麼++用 Electron 搭一個最簡的知識庫應用殼子——能啟動窗口、左邊顯示文檔列表、右邊顯示問答面板、本地有一個數據目錄。任務本身不復雜,複雜的是你怎麼讓 agent 完成它。++你需要跑兩次。第一次只給一段提示詞,什麼都不準備,看 agent 能做到什麼程度。第二次提前在倉庫裡放好 `AGENTS.md`、`init.sh`、`feature_list.json`,用結構化的方式告訴 agent 該幹什麼、怎麼驗證、什麼時候算做完。然後對比兩次結果。++這個項目的核心不是寫代碼,是搞清楚"提前花 15 分鐘準備規則"和"上來就讓 agent 幹"之間到底差多少。++## 用什麼工具++- Claude Code 或 Codex(選一個,兩次都用同一個)+- Git(管理分支和對比)+- Node.js + Electron(項目技術棧)+- 一個計時器(記錄每次運行時間)++## 具體步驟++### 準備工作++1. 從一個乾淨的 commit 出發,記錄 commit hash。+2. 創建兩個分支:`p01-baseline` 和 `p01-improved`。+3. 準備同一段任務提示詞,內容是:"用 Electron 做一個知識庫應用,窗口左邊是文檔列表區域,右邊是問答面板區域,應用需要創建並使用本地數據目錄。"++### 第一次運行(弱 harness)++切到 `p01-baseline` 分支。++1. 只用上面那段提示詞啟動 agent。+2. 不提供 `AGENTS.md`,不提供啟動腳本,不提供驗收標準。+3. 設定相同的時間上限和輪次上限(建議 30 分鐘 / 20 輪)。+4. agent 停下後,運行 `npm start`(或對應啟動命令),看應用能不能跑起來。+5. 記錄:終端輸出、關鍵 diff、agent 的最終總結。+6. **不要手動修代碼**。跑不起來就是跑不起來,如實記錄。++### 第二次運行(強 harness)++切到 `p01-improved` 分支。在啟動 agent 之前,先在倉庫裡準備好:++- `AGENTS.md`:寫明項目結構、啟動命令、Electron 層邊界規則+- `init.sh`:一鍵恢復可運行狀態(`npm install && npm start`)+- `feature_list.json`:列出四個功能點及其完成狀態++然後用和第一次相同的提示詞啟動 agent,同樣的時間上限和輪次上限。agent 停下後,跑 `./init.sh`,記錄結果。++## 怎麼衡量結果++| 指標 | 說明 |+|------|------|+| 完成狀態 | 完全完成 / 部分完成 / 失敗 |+| 首次成功啟動時間 | 從開始到 `npm start` 第一次成功運行 |+| 重試次數 | 中間需要人工干預幾次才能跑起來 |+| 遺漏項 | agent 宣佈完成時還有哪些功能沒做 |+| 過早停止 | agent 是否在不可運行狀態就宣佈完成 |++## 要交什麼++- 弱 harness 運行記錄:提示詞、日誌/對話記錄、最終 diff、啟動證據+- 強 harness 運行記錄:同上,加上你準備的 harness 檔案+- 一份對比筆記(1-2 頁):兩次運行的差異、數據、結論++## 對應講義++- [Lecture 01 — 為什麼強 agent 仍然失敗](../../lectures/lecture-01-why-capable-agents-still-fail/index.md)+- [Lecture 02 — harness 到底是什麼](../../lectures/lecture-02-what-a-harness-actually-is/index.md)+- [Lecture 06 — 為什麼初始化需要單獨一個階段](../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)diff --git a/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md b/docs/zh-TW/projects/project-02-agent-readable-workspace/index.mdnew file mode 100644index 0000000..b5c4c55--- /dev/null+++ b/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md@@ -0,0 +1,88 @@+# Project 02. 讓 agent 看懂項目、接住上次的工作++> 相關講義:[L03. 讓代碼倉庫成為唯一的事實來源](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [L04. 為什麼一個巨大的指令檔案會失敗](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)++## 你要做什麼++P01 證明了準備規則有用。但 P01 的任務一次會話就幹完了。真實開發不是這樣的——你昨天干了一半,今天開新會話,agent 得從倉庫狀態裡搞清楚"做了什麼、沒做什麼、接下來幹什麼"。++這個項目要求你給倉庫加上"可讀性":讓一個全新的 agent 打開倉庫後,能快速理解項目結構、知道當前進度、接手上次的工作。具體任務是給知識庫應用加上三個功能:文檔導入、文檔詳情頁、導入後的本地持久化。這些功能必須跨至少兩個 agent 會話完成。++你需要跑兩次。第一次不給 agent 任何幫助,看它在第二個會話裡要花多久才能"接上"。第二次提前放好 `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md`,讓它快速對齊上下文。++## 用什麼工具++- Claude Code 或 Codex(和 P01 保持一致)+- Git+- Node.js + Electron+- 文本編輯器(寫文檔用)++## 具體步驟++### 準備工作++1. 基於 P01 完成後的代碼,從同一個 commit 出發。+2. 創建兩個分支:`p02-baseline` 和 `p02-improved`。+3. 列出要實現的三個功能:文檔導入流程、文檔詳情視圖、文檔持久化。兩條分支任務範圍完全一致。++### 第一次運行(弱 harness)++切到 `p02-baseline` 分支。++**會話 A:**++1. 啟動 agent,只給任務描述,不給架構文檔,不給進度檔案。+2. 故意在功能完成之前停止會話(比如只完成文檔導入)。+3. 不寫任何交接檔案。直接結束。++**會話 B:**++1. 開一個全新的 agent 會話。+2. 只說"繼續開發",不給額外上下文。+3. 記錄 agent 花了多久才做出第一個有意義的代碼修改。+4. 記錄 agent 哪些時候在"重新發現"本來已經知道的東西。++### 第二次運行(強 harness)++切到 `p02-improved` 分支。在第一個會話之前,先在倉庫裡準備好:++- `ARCHITECTURE.md`:描述項目結構、Electron 各層職責、數據流+- `PRODUCT.md`:描述產品功能範圍和當前階段目標+- `AGENTS.md`:啟動命令、工作規則、驗證方式+- `init.sh`:一鍵恢復可運行狀態++**會話 A:**++1. 啟動 agent,讓它開始工作。+2. 同樣在功能完成之前停止。+3. **這次要求 agent 更新 `session-handoff.md`**:記錄做了什麼、沒做什麼、下一步是什麼。++**會話 B:**++1. 開一個全新的 agent 會話。+2. 讓 agent 讀 `session-handoff.md` 和 `feature_list.json`,然後繼續。+3. 同樣記錄接手速度和重複工作比例。++## 怎麼衡量結果++| 指標 | 說明 |+|------|------|+| 會話 B 接手時間 | 從開始到第一個有效代碼修改的時間 |+| 重新發現次數 | agent 重新瞭解架構、命令、狀態等已有信息的次數 |+| 交接檔案質量 | 交接記錄是否完整、準確、可操作 |+| 重複工作比例 | 會話 B 中有多少工作量是在重複會話 A 已做過的事 |+| 最終完成狀態 | 三個功能是否全部完成 |++## 要交什麼++- 弱 harness 的會話 A + B 日誌/對話記錄+- 強 harness 的會話 A + B 日誌/對話記錄+- 兩次運行中產生的交接檔案+- 一份對比筆記:重點比較接手速度和上下文恢復質量++## 對應講義++- [Lecture 03 — 為什麼倉庫必須成為唯一事實來源](../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)+- [Lecture 04 — 為什麼一個大而全的指令檔案不行](../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+- [Lecture 05 — 為什麼長任務會丟失連續性](../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)diff --git a/docs/zh-TW/projects/project-03-multi-session-continuity/index.md b/docs/zh-TW/projects/project-03-multi-session-continuity/index.mdnew file mode 100644index 0000000..a6cf4c8--- /dev/null+++ b/docs/zh-TW/projects/project-03-multi-session-continuity/index.md@@ -0,0 +1,77 @@+# Project 03. 讓 agent 關掉再打開還能接著幹++> 相關講義:[L05. 為什麼長時任務會丟失上下文](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [L06. 為什麼初始化需要單獨一個階段](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)++## 你要做什麼++P02 解決了"接手"的問題,但 agent 接手之後能不能把活幹完、幹對了,又是另一回事。這個項目要你給 agent 加上範圍控制和驗證關卡。++你要實現的知識庫功能是:文檔分塊、元數據提取、索引進度顯示、帶引用的問答流程。這些功能比前兩個項目複雜,agent 更容易跑偏——要麼多做了不該做的,要麼說做完了但其實沒通過驗證。++你需要一個 `feature_list.json`,每個功能有明確的狀態(failing / passing)。規則很簡單:一次只做一個功能,沒有可運行的驗證證據就不能標成 passing。跑兩次,一次不給這些約束,一次嚴格執行,看結果差多少。++## 用什麼工具++- Claude Code 或 Codex+- Git+- Node.js + Electron+- `feature_list.json`(範本參考 `docs/zh-TW/resources/templates/feature_list.json`)++## 具體步驟++### 準備工作++1. 基於 P02 完成後的代碼,從同一個 commit 出發。+2. 創建兩個分支:`p03-baseline` 和 `p03-improved`。+3. 定義四個功能:文檔分塊、元數據提取、索引進度 UI 顯示、帶引用的問答。兩條分支的功能定義完全一致。++### 第一次運行(弱 harness)++切到 `p03-baseline` 分支。++1. 啟動 agent,給一段模糊的任務提示詞。+2. 不提供 `feature_list.json`,沒有狀態追蹤。+3. 不限制 agent 一次做幾個功能。+4. 沒有明確的驗證標準——agent 自己說"完成了"就算。+5. 運行結束後,手動檢查每個功能是否真的能用。+6. 記錄哪些功能 agent 聲稱完成但實際沒通過驗證。++### 第二次運行(強 harness)++切到 `p03-improved` 分支。在啟動 agent 之前:++- 在倉庫根目錄放好 `feature_list.json`,四個功能全部標為 `failing`。+- 在 `AGENTS.md` 裡寫明規則:一次只做一個功能;狀態只能從 `failing` 切到 `passing`,且必須有驗證證據。+- 準備好 `init.sh`。++然後啟動 agent:++1. agent 開始工作,每完成一個功能必須更新 `feature_list.json` 並附上驗證證據(截圖、測試輸出等)。+2. 至少要有一個功能展示從 `failing` 到 `passing` 的完整轉換過程。+3. 問答功能的驗證必須檢查引用是否存在、引用是否相關,不能只看有沒有輸出。+4. 運行結束後歸檔所有驗證證據。++## 怎麼衡量結果++| 指標 | 說明 |+|------|------|+| 範圍漂移次數 | agent 做了功能清單之外的事的次數 |+| 虛假完成率 | agent 聲稱完成但驗證不通過的功能比例 |+| 驗證覆蓋率 | 有明確驗證證據的功能佔總功能的百分比 |+| 問答質量 | 引用是否存在、引用是否相關 |+| 重試次數 | 從開始到所有功能 passing 總共重試了幾次 |++## 要交什麼++- 弱 harness 運行記錄:提示詞、日誌、驗證結果+- 強 harness 運行記錄:`feature_list.json` 變更歷史、日誌、驗證證據+- 至少一個功能從 `failing` 到 `passing` 的轉換證據+- 一份對比筆記:重點看範圍紀律和完成準確度++## 對應講義++- [Lecture 07 — 為什麼 agent 總是做過頭、做不完](../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)+- [Lecture 08 — 為什麼 feature list 是 harness 的基礎原語](../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+- [Lecture 09 — 為什麼 agent 總是過早宣佈勝利](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md)+- [Lecture 10 — 為什麼端到端測試能改變結果](../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)diff --git a/docs/zh-TW/projects/project-04-incremental-indexing/index.md b/docs/zh-TW/projects/project-04-incremental-indexing/index.mdnew file mode 100644index 0000000..bd48f66--- /dev/null+++ b/docs/zh-TW/projects/project-04-incremental-indexing/index.md@@ -0,0 +1,76 @@+# Project 04. 用運行反饋修正 agent 的行為++> 相關講義:[L07. 為什麼 agent 會多做或少做](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [L08. 為什麼功能清單是 harness 原語](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)++## 你要做什麼++前三個項目關注的是"讓 agent 把活幹完"。這個項目關注的是"出了問題怎麼修"——而且不是你修,是讓 agent 自己通過運行時信號來修。++你要做兩件事。第一,給知識庫應用加上運行時可觀測性:啟動日誌、導入和索引的日誌、問答失敗時的用戶可見錯誤狀態。第二,在倉庫裡編碼架構約束,讓 agent 不可能靜默地跨層違規(main / preload / renderer / services 之間的邊界)。++然後你會在代碼裡埋一個運行時 bug,讓 agent 去修。跑兩次:一次不給日誌和約束,看 agent 怎麼修;一次給好日誌和架構規則,看差別。++## 用什麼工具++- Claude Code 或 Codex+- Git+- Node.js + Electron+- 日誌庫(如 `electron-log` 或簡單的 console 封裝)+- 結構化檢查工具(ESLint 自定義規則、guard 腳本、或測試)++## 具體步驟++### 準備工作++1. 基於 P03 完成後的代碼,從同一個 commit 出發。+2. 創建兩個分支:`p04-baseline` 和 `p04-improved`。+3. 在兩個分支中埋入同一個運行時 bug(比如:索引時 chunk 大小讀取錯誤導致問答返回空結果)。+4. 記錄 bug 的位置和表現,但不要告訴 agent bug 在哪。++### 第一次運行(弱 harness)++切到 `p04-baseline` 分支。++1. 啟動 agent,告訴它"問答功能返回空結果,請修復"。+2. 倉庫裡沒有運行時日誌,沒有架構約束檔案。+3. 記錄 agent 花了多久找到根因、怎麼確認修復的、修復過程中是否引入了新的層邊界違規。+4. 修復後重啟應用,確認是否能幹淨啟動。++### 第二次運行(強 harness)++切到 `p04-improved` 分支。在啟動 agent 之前,先在倉庫裡準備好:++- **運行時日誌**:啟動時打印初始化步驟,導入時打印檔案數量和 chunk 結果,索引時打印進度,問答失敗時打印錯誤原因。+- **架構約束**:在 `AGENTS.md` 裡明確寫 Electron 四層邊界(main / preload / renderer / services),說明哪些調用路徑是允許的。用 ESLint 規則或 guard 腳本檢查違規。+- **乾淨狀態要求**:最終交付前必須能幹淨重啟。++然後啟動 agent:++1. 先讓 agent 加上日誌和結構化檢查(這是任務的一部分)。+2. 然後告訴它"問答功能返回空結果,請修復"。+3. 這次 agent 有日誌可以看,有架構規則可以參照。+4. 記錄診斷速度、修復質量、是否引入了邊界違規。+5. 修復後重啟應用,確認乾淨啟動。++## 怎麼衡量結果++| 指標 | 說明 |+|------|------|+| 根因定位時間 | 從開始到 agent 準確描述 bug 原因 |+| 修復確認時間 | 從定位到驗證修復成功 |+| 邊界違規數 | 修復過程中引入的跨層違規次數 |+| 日誌有用性 | 日誌是否直接指向了失敗原因 |+| 乾淨重啟 | 修復後是否能幹淨重啟、無報錯 |++## 要交什麼++- 弱 harness 的調試記錄:診斷過程、修復 diff、啟動證據+- 強 harness 的調試記錄:同上,加上日誌和架構約束檔案+- 結構化檢查產物(lint 規則、guard 腳本、或測試檔案)+- 一份對比筆記:重點比較診斷速度和修復健壯性++## 對應講義++- [Lecture 11 — 為什麼可觀測性屬於 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)+- [Lecture 12 — 為什麼每個會話都必須留下乾淨狀態](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)diff --git a/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md b/docs/zh-TW/projects/project-05-grounded-qa-verification/index.mdnew file mode 100644index 0000000..022be09--- /dev/null+++ b/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md@@ -0,0 +1,93 @@+# Project 05. 讓 agent 自己檢查自己做的對不對++> 相關講義:[L09. 為什麼 agent 會提前宣告完成](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [L10. 為什麼端到端測試會改變結果](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)++## 你要做什麼++前四個項目裡,"檢查做得對不對"這件事要麼是你手動做的,要麼是靠檔案規則強制執行的。這個項目要讓 agent 自己來檢查。++方法是角色分離。以前是同一個 agent 既寫代碼又判斷質量。現在拆開:一個 agent 負責實現(生成者),另一個 agent 負責審查(評估者)。更進一步,還可以加一個負責規劃的角色(規劃者)。你要跑三次,看每加一層角色分離,結果好多少。++選一個實質性的功能升級(比如多輪對話歷史、引用面板重設計、文檔集合與篩選),三次都做同一個升級,唯一變量是 harness 的角色分工。++## 用什麼工具++- Claude Code 或 Codex(用於生成和規劃角色)+- 同一個或另一個 agent 實例(用於評估角色)+- 評估量表(參考 `docs/zh-TW/resources/templates/evaluator-rubric.md`)+- Sprint contract 範本(參考 `docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md`)++## 具體步驟++### 準備工作++1. 基於 P04 完成後的代碼,從同一個 commit 出發。+2. 創建三個分支:`p05-single`、`p05-gen-eval`、`p05-plan-gen-eval`。+3. 選定一個功能升級,寫清楚驗收標準。三次運行的功能範圍和驗收標準完全一致。+4. 寫好評估量表,打分維度至少包括:正確性、可靠性、可維護性、用戶體驗。++### 第一次運行(弱 harness — 單角色)++切到 `p05-single` 分支。++1. 一個 agent 包攬規劃、實現、自查。+2. 沒有外部評估量表,agent 自己判斷做得好不好。+3. 記錄最終產出和未解決的缺陷。++### 第二次運行(強 harness — 生成者 + 評估者)++切到 `p05-gen-eval` 分支。++1. 生成者和評估者先用 sprint contract 對齊:做什麼、怎麼驗證、什麼不算在範圍內。+2. 生成者實現功能。+3. 評估者用評估量表打分,反饋問題。+4. 生成者根據反饋修改。至少經過一輪修訂。+5. 記錄評估者抓住了多少缺陷、修訂了多少內容。++### 第三次運行(更強 harness — 規劃者 + 生成者 + 評估者)++切到 `p05-plan-gen-eval` 分支。++1. 規劃者先拆解任務、定義步驟和依賴關係。+2. 生成者按規劃實現。+3. 評估者用同一份評估量表打分。+4. 至少經過一輪修訂。+5. 記錄規劃是否減少了返工。++### 評估者調優++評估者不是一次就能用好的。初始版本的評估者往往會"發現問題然後自己說服自己通過"。你需要:++1. 讓評估者給一個已完成的 sprint 打分。+2. 和你自己的判斷對比。+3. 哪裡有分歧,就把量表寫得更具體。+4. 重新跑評估者,檢查對齊程度。+5. 重複 3-5 輪,直到評估者判斷和你的判斷基本一致。記錄每一輪調優的內容。++## 怎麼衡量結果++| 指標 | 說明 |+|------|------|+| 範圍定義質量 | 編碼前的任務拆解清晰度 |+| 缺陷檢出數 | 交付前被評估者抓到的缺陷數量和嚴重程度 |+| 量表評分 | 各維度的得分(正確性、可靠性、可維護性、UX) |+| 返工量 | 評估反饋後需要重做的比例 |+| 最終健壯性 | 升級後功能在實際運行中的穩定程度 |+| 評估者調優輪數 | 評估者判斷與你對齊需要的迭代次數 |+| Sprint contract 效果 | 合同是否減少了評估中的模糊地帶 |++## 要交什麼++- Sprint contract 文檔+- 評估者調優日誌(每輪改了什麼、為什麼改)+- 單角色運行記錄:提示詞、日誌、可運行證據+- 生成者+評估者運行記錄:含量表評分和修訂記錄+- 規劃者+生成者+評估者運行記錄:含規劃文檔、量表評分、修訂記錄+- 一份對比筆記:質量提升幅度和協調成本++## 對應講義++- [Lecture 09 — 為什麼 agent 總是過早宣佈勝利](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md)+- [Lecture 10 — 為什麼端到端測試能改變結果](../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+- [Lecture 11 — 為什麼可觀測性屬於 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)diff --git a/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md b/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.mdnew file mode 100644index 0000000..bae97c4--- /dev/null+++ b/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md@@ -0,0 +1,101 @@+# Project 06. 搭建一套完整的 agent 工作環境++> 相關講義:[L11. 為什麼可觀測性屬於 harness](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [L12. 為什麼每次會話都要留乾淨狀態](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)++## 你要做什麼++這是結業項目。把前五個項目學到的所有東西組裝起來,跑一次完整的基準測試,然後做一輪清理,驗證質量是可以持續維護的。++你要用一套固定的多功能任務集,覆蓋知識庫應用的完整產品切片:導入文檔、構建索引、帶引用的問答、運行時可觀測性、可讀可重啟的倉庫狀態。先跑一次弱 harness 基線,再跑一次你組裝的最強 harness,然後做一輪清理和重跑。最後還要做一次 harness 精簡實驗——刪掉一個組件看看結果會不會變差,判斷哪些組件是真正有用的、哪些是多餘的開銷。++## 用什麼工具++- Claude Code 或 Codex+- Git+- Node.js + Electron+- 質量文檔範本(`docs/zh-TW/resources/templates/quality-document.md`)+- 評估量表(`docs/zh-TW/resources/templates/evaluator-rubric.md`)+- 前五個項目積累的所有 harness 組件++## 具體步驟++### 準備工作++1. 基於 P05 完成後的代碼,從同一個 commit 出發。+2. 創建兩個分支:`p06-baseline` 和 `p06-improved`。+3. 用質量文檔範本給當前代碼打一次初始評分(每個產品領域和架構層的等級)。+4. 定義一套固定的基準任務集和評分表——在跑任何 agent 之前就定好,跑的過程中不改。++基準任務集至少包括:++- 導入一篇文檔+- 構建或刷新索引+- 回答一個帶引用的問題+- 查看運行時日誌確認可觀測性+- 關掉重開後狀態仍在++### 第一次運行(弱 harness)++切到 `p06-baseline` 分支。++1. 用課程早期階段的弱 harness(沒有完整交接檔案、沒有嚴格驗證、可觀測性不足)。+2. 用 agent 跑完整個基準任務集。+3. 立刻評分。記錄每個任務的完成狀態、重試次數、缺陷數。+4. 更新質量文檔,記錄每個領域和層的等級變化。++### 第二次運行(強 harness)++切到 `p06-improved` 分支。++1. 用你在這門課裡組裝的最強 harness:交接檔案和啟動腳本、明確的範圍和驗證關卡、運行時信號和架構約束、評估者或多角色審查、質量文檔追蹤。+2. 同樣的基準任務集,同樣的模型和預算。+3. 立刻評分。記錄結果。+4. 更新質量文檔。++### 清理和重跑++在 `p06-improved` 分支上:++1. 做一輪清理:刪死代碼、修不清楚的文檔、理順不穩定的運行路徑。+2. 清理後重跑同樣的基準任務集,重新評分。+3. 更新質量文檔。++對比三個快照的質量文檔:基線、強 harness、清理後。++### Harness 精簡實驗++1. 從 `p06-improved` 分支中刪掉一個 harness 組件(比如刪掉 sprint contract,或者刪掉顯式範圍關卡)。+2. 重跑基準任務集。+3. 如果結果沒變差——說明這個組件是多餘的開銷,可以去掉。+4. 如果結果變差了——說明這個組件是承重的,必須保留。+5. 記錄實驗結果。可以多試幾個組件。++## 怎麼衡量結果++| 指標 | 說明 |+|------|------|+| 基準完成率 | 基準任務集中成功完成的比例 |+| 重試次數 | 每個任務需要重試幾次 |+| 缺陷數 | 人工干預前發現的缺陷數量 |+| 清理工作量 | 清理花了多長時間、改了多少檔案 |+| 清理後可讀性和重啟成功率 | 清理後倉庫的可維護程度 |+| 質量文檔等級變化 | 三個快照的等級對比 |+| Harness 精簡結果 | 哪些組件可以刪、哪些是承重的 |++## 要交什麼++- 質量文檔的三個快照(基線、強 harness、清理後)+- 基線基準測試記錄:評分和證據+- 強 harness 基準測試記錄:評分和證據+- 清理運行記錄:清理前後評分變化+- Harness 精簡日誌:刪了什麼組件、基準結果、決定保留還是刪+- 最終結業總結:關鍵經驗教訓++## 對應講義++- [Lecture 01 — 為什麼強 agent 仍然失敗](../../lectures/lecture-01-why-capable-agents-still-fail/index.md)+- [Lecture 03 — 為什麼倉庫必須成為唯一事實來源](../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)+- [Lecture 08 — 為什麼 feature list 是 harness 的基礎原語](../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+- [Lecture 11 — 為什麼可觀測性屬於 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)+- [Lecture 12 — 為什麼每個會話都必須留下乾淨狀態](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)diff --git a/docs/zh-TW/resources/index.md b/docs/zh-TW/resources/index.mdnew file mode 100644index 0000000..b410cb0--- /dev/null+++ b/docs/zh-TW/resources/index.md@@ -0,0 +1,52 @@+# 繁體中文資源庫++這個資料夾把課程裡的方法整理成可以直接參考和複用的材料,不是再講一遍概念,而是盡量回答兩個問題:++- 我現在應該先抄哪些檔案+- 這些檔案分別解決什麼問題++## 適合什麼時候用++當你準備讓 Codex、Claude Code 或其他 coding agent 在一個倉庫裡持續工作時,就可以從這裡開始。它特別適合這些場景:++- 多輪會話開發,擔心上下文斷裂+- 功能多,容易出現做一半就停的半成品+- 常常提前宣布完成,但實際沒測透+- 每次開工都要重新摸索啟動方式++## 從這裡開始++如果你想先搭一個最小可用版本,優先看這些檔案:++- 根指令檔案:[`templates/AGENTS.md`](./templates/AGENTS.md) 或 [`templates/CLAUDE.md`](./templates/CLAUDE.md)+- 功能狀態檔案:[`templates/feature_list.json`](./templates/feature_list.json)+- 進度日誌:[`templates/claude-progress.md`](./templates/claude-progress.md)+- 啟動腳本參考:`docs/zh-TW/resources/templates/init.sh`++然後按需要補上:++- 會話交接範本:[`templates/session-handoff.md`](./templates/session-handoff.md)+- 收尾檢查清單:[`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)+- 評審範本:[`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)++如果你想直接採用 OpenAI 那篇 harness engineering 文章裡更完整的倉庫組織方式,可以繼續看:++- [`openai-advanced/index.md`](./openai-advanced/index.md)++## 資源庫結構++- [`templates/`](./templates/index.md):可以直接複製到真實倉庫裡的範本+- [`reference/`](./reference/index.md):方法說明、啟動流程和問題對照表+- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 風格高階資源包,包括倉庫骨架、品質檔案、執行計畫和系統級治理檔案++## 推薦最小組合++- `AGENTS.md` 或 `CLAUDE.md`+- `feature_list.json`+- `claude-progress.md`+- `init.sh`++先把這四樣放進專案裡,再開始讓 agent 持續工作,通常就已經能明顯降低返工和瞎猜。++如果你的倉庫已經進入多模組、多階段、多角色協作,可以直接升級到+[`openai-advanced/`](./openai-advanced/index.md) 這一套高階結構,而不是繼續把最小範本硬撐成一個大而亂的系統。diff --git a/docs/zh-TW/resources/openai-advanced/index.md b/docs/zh-TW/resources/openai-advanced/index.mdnew file mode 100644index 0000000..faad135--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/index.md@@ -0,0 +1,76 @@+# OpenAI 高級資源包++這個檔案夾把 OpenAI 那篇《Harness engineering: leveraging Codex in an+agent-first world》裡更完整、更高階的倉庫組織方式整理成可以直接參考和複製的範本。++當最小 harness 已經不夠用,而你的倉庫開始需要下面這些能力時,就該看這一套:++- 一個簡短、負責路由的 `AGENTS.md`+- 放在倉庫裡的“唯一事實來源”文檔體系+- 活躍執行計劃與已完成計劃的分層管理+- 明確的產品、可靠性、安全、前端治理檔案+- 按產品領域和架構層持續更新的質量評分+- 面向模型閱讀的參考材料目錄+- 針對架構、知識沉澱、運行驗證的標準 SOP++## 包含的目錄骨架++[`repo-template/`](./repo-template/index.md) 裡提供了一套可直接複製的起步+結構,核心佈局如下:++```text+AGENTS.md+ARCHITECTURE.md+docs/+├── design-docs/+│ ├── index.md+│ └── core-beliefs.md+├── exec-plans/+│ ├── active/+│ ├── completed/+│ └── tech-debt-tracker.md+├── generated/+│ └── db-schema.md+├── product-specs/+│ ├── index.md+│ └── new-user-onboarding.md+├── references/+│ ├── design-system-reference-llms.txt+│ ├── nixpacks-llms.txt+│ └── uv-llms.txt+├── DESIGN.md+├── FRONTEND.md+├── PLANS.md+├── PRODUCT_SENSE.md+├── QUALITY_SCORE.md+├── RELIABILITY.md+└── SECURITY.md+```++## 怎麼用++1. 如果倉庫還小,先用最小資源包。+2. 一旦進入多模塊、多輪會話、長期演化階段,就把+ [`repo-template/`](./repo-template/index.md) 裡的骨架複製到你的倉庫。+3. 保持 `AGENTS.md` 很短,把深層規則拆到 `docs/` 裡。+4. 把質量文檔、可靠性文檔、執行計劃當成日常開發的一部分,而不是事後補寫。+5. 把生成物和外部參考材料明確收進倉庫,避免 agent 依賴聊天上下文或人的記憶。++## SOP 資料庫++[`sops/`](./sops/index.md) 把文章裡的幾張關鍵圖,整理成可以逐步執行的標準流程:++- 分層領域架構搭建 SOP+- 把不可見知識編碼進倉庫的 SOP+- 本地可觀測性棧與反饋迴路 SOP+- 用 Chrome DevTools 做 UI 驗證閉環的 SOP++## 設計原則++- 短入口,深鏈接+- 倉庫就是唯一事實來源+- 機械約束優先於口頭約定+- 計劃、質量和技術債都和代碼一起版本化+- 清理與 harness 簡化是常規工作,不是臨時救火++這套資源包是有傾向性的範本,不是必須逐字照抄。最好的用法是把它當成一套高質量起點,再按你的項目改造。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md b/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.mdnew file mode 100644index 0000000..8146785--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md@@ -0,0 +1,55 @@+# AGENTS.md++這個倉庫面向長時運行的 coding-agent 工作流。保持這個檔案簡短,把它當成“唯一事實來源”文檔的入口和路由層,而不是一個不斷膨脹的大說明書。++## 開工流程++改代碼前先做這些事:++1. 用 `pwd` 確認倉庫根目錄。+2. 讀取 `ARCHITECTURE.md`,理解當前系統地圖和硬性依賴規則。+3. 讀取 `docs/QUALITY_SCORE.md`,先知道最弱的產品領域和架構層。+4. 讀取 `docs/PLANS.md`,再打開當前要執行的 active plan。+5. 讀取相關的 `docs/product-specs/` 規格文檔。+6. 跑這個倉庫約定的 bootstrap 與驗證路徑。+7. 如果基礎驗證先失敗,先修 baseline,再加新範圍。++## 路由地圖++- `ARCHITECTURE.md`:領域地圖、分層模型、依賴規則+- `docs/design-docs/index.md`:設計決策與核心信念+- `docs/product-specs/index.md`:當前產品行為與驗收目標+- `docs/PLANS.md`:計劃生命週期與執行計劃規則+- `docs/QUALITY_SCORE.md`:產品領域與架構層健康度+- `docs/RELIABILITY.md`:運行信號、benchmark、重啟要求+- `docs/SECURITY.md`:密鑰、沙箱、數據和外部動作規則+- `docs/FRONTEND.md`:UI 約束、設計系統規則、可訪問性檢查++## 工作約定++- 一次只圍繞一個有邊界的計劃或功能切片工作。+- 不能只靠讀代碼就宣佈完成,必須有可運行證據。+- 只要改了行為,就同步更新對應的產品、計劃或可靠性文檔。+- 如果某類 review feedback 反覆出現,把它升級成機械規則、檢查或 linter,不要一直在聊天裡重複解釋。+- 生成物放進 `docs/generated/`,外部 reference 放進 `docs/references/`。+- 需要更多細節時,優先補小而新的文檔,而不是繼續把這個檔案寫長。++## 完成定義++一個改動只有在以下條件都滿足時才算完成:++- 目標行為已實現+- 要求的驗證真的跑過+- 證據已經掛到相關 plan 或質量文檔裡+- 受影響的文檔仍然是最新的+- 倉庫能按標準啟動路徑乾淨重啟++## 收尾++結束會話前:++1. 更新當前 active execution plan。+2. 如果產品領域或架構層有明顯變化,更新 `docs/QUALITY_SCORE.md`。+3. 如果有延期處理的債務,記到 `docs/exec-plans/tech-debt-tracker.md`。+4. 已完成的計劃及時移到 `docs/exec-plans/completed/`。+5. 保證倉庫可重啟,並留下清晰的下一步動作。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.mdnew file mode 100644index 0000000..ddcd6a8--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -0,0 +1,55 @@+# ARCHITECTURE.md++這份檔案是系統的頂層地圖。它應該保持簡短,只提供最關鍵的結構信息,並把更深的內容指向其他文檔。++## 系統形態++- 產品:`[替換成产品名]`+- 主用戶流程:`[替換成核心流程]`+- 運行面:`[desktop / web / cli / services / workers]`+- 產品行為真相來源:`docs/product-specs/`++## 領域地圖++| 領域 | 負責什麼 | 主要入口 | 對應規格 |+|------|---------|---------|---------|+| `[domain-a]` | `[职责]` | `[模块 / 路由 / 命令]` | `[spec path]` |+| `[domain-b]` | `[职责]` | `[模块 / 路由 / 命令]` | `[spec path]` |++## 分層模型++用固定方向的分層模型,避免 agent 臨場發明架構:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++跨領域關注點應該通過明確的 provider 或 adapter 邊界進入,而不是直接跨層穿透。++## 硬性依賴規則++- 低層不能依賴高層。+- UI 不能繞過 runtime 或 service 契約。+- 數據訪問必須通過 repo 或等價 adapter 進入。+- 共享 util 必須保持通用,不能慢慢堆成領域邏輯垃圾桶。+- 新依賴要在對應 plan 或 design doc 裡說明理由。++## 橫切接口++| 關注點 | 允許的邊界 | 備註 |+|-------|-----------|------|+| 日誌與 tracing | `[provider / utility path]` | `[只允许結構化日誌,不允许临時 console]` |+| Auth | `[provider path]` | `[token/session 规则]` |+| 外部 API | `[client 或 provider path]` | `[限流 / 重試原则]` |+| Feature flags | `[flag boundary]` | `[歸属]` |++## 當前熱點++- `[最难安全修改的区域]`+- `[邊界最弱或測試最脆的区域]`++## 變更檢查++當你修改了會影響架構的代碼:++1. 如果領域地圖或允許邊界變了,就更新這份檔案。+2. 如果背後的設計理由變了,就更新 `docs/design-docs/` 裡的相關文檔。+3. 如果規則應該機械執行,就補一個可執行檢查。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/DESIGN.mdnew file mode 100644index 0000000..d0cd37f--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/DESIGN.md@@ -0,0 +1,26 @@+# DESIGN.md++這份檔案是設計文檔入口。保持簡短,把更細的內容路由到+`docs/design-docs/` 裡的具體檔案。++## 目的++記錄那些應該跨越單次聊天、單個 sprint、單個 reviewer 記憶而持續存在的產品與系統設計決策。++## 什麼時候先看它++- 你需要理解當前的設計哲學+- 你準備引入新模式+- 你要判斷哪些設計已經定了,哪些還在開放狀態++## 核心設計文檔++- `docs/design-docs/index.md`:accepted / proposed / deprecated 文檔索引+- `docs/design-docs/core-beliefs.md`:項目級 agent-first 核心信念++## 設計規則++- 設計文檔要小而新。+- 一個決策領域儘量對應一份文檔。+- 某個改動依賴設計文檔時,要在 plan 和 spec 裡顯式鏈接它。+- 如果某條設計規則已經變成運行上的硬要求,就把它升級成自動化檢查或更新到 `ARCHITECTURE.md`。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/FRONTEND.mdnew file mode 100644index 0000000..b38d6ad--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/FRONTEND.md@@ -0,0 +1,23 @@+# FRONTEND.md++這份檔案定義穩定的前端預期,避免 agent 每次都臨場發明一套 UI 模式。++## UI 原則++- 先保證清晰,再追求新鮮感。+- 交互流程要可發現、可重走、可重啟。+- 優先沉澱少量可複用組件,而不是到處長一次性變體。+- 可訪問性檢查屬於正常驗證,不是最後的美化工作。++## 護欄++- 把設計系統或組件庫參考材料放進 `docs/references/`。+- 顯式記錄關鍵用戶狀態:empty、loading、success、error、retry。+- 在不同流程裡保持文案、鍵盤行為、視覺層級一致。+- 修復 UI bug 後,順手補上對應驗證步驟。++## 驗證要求++- 為關鍵用戶旅程留下證據。+- 把瀏覽器或運行時驗證步驟寫進相關 plan。+- 如果視覺迴歸常見,就標準化截圖或 DOM 檢查。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PLANS.mdnew file mode 100644index 0000000..41534ed--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PLANS.md@@ -0,0 +1,34 @@+# PLANS.md++這份檔案定義執行計劃如何創建、更新、完成和歸檔。++## 什麼時候必須有 plan++當工作滿足以下任一條件時,就創建 execution plan:++- 會跨越多個會話+- 會同時影響多個子系統+- 驗證或上線風險不小+- 存在需要顯式記錄的開放決策++## 計劃放哪++- `docs/exec-plans/active/`:當前正在驅動工作的計劃+- `docs/exec-plans/completed/`:已完成但仍然要保留上下文的計劃+- `docs/exec-plans/tech-debt-tracker.md`:延期處理的債務與 follow-up++## 最少要包含的部分++- 目標+- 範圍與明確不做什麼+- 驗證路徑+- 風險與 blocker+- 進度日誌+- 開放決策++## 運行規則++- 一份 active plan 同一時間應該只有一個清晰的當前步驟。+- plan 要隨著工作推進而更新,不要把它當成靜態散文。+- 只要某個決策改變了實現方向,就記到 plan 裡。+- 已完成的計劃要移到 `completed/`,讓後續 agent 仍然能發現歷史上下文。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.mdnew file mode 100644index 0000000..c0ea13b--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md@@ -0,0 +1,24 @@+# PRODUCT_SENSE.md++這份檔案記錄那些代碼本身並不能可靠表達出來的產品判斷。++## 產品核心++- 主要用戶:`[替換]`+- 要完成的任務:`[替換]`+- 最想解決的核心痛點:`[替換]`+- 可接受質量門檻:`[替換]`++## 產品規則++- 優先保證用戶可感知的可靠性,而不是一味加功能。+- 行為有歧義時,把它當成 spec 缺口,不要默認允許猜。+- 只要實現改變了用戶看見或信任的東西,就更新對應 spec。+- 具體流程寫在 product spec 裡,跨流程的產品優先級寫在這裡。++## 禁區模式++- 隱蔽的破壞性操作+- 沒有用戶反饋的靜默失敗+- 用戶可見狀態沒有明確真相來源+- 不能用一句話解釋清楚的功能diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.mdnew file mode 100644index 0000000..060fea9--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md@@ -0,0 +1,39 @@+# QUALITY_SCORE.md++這份文檔用來跟蹤倉庫是在變強還是變弱。++## 評級標準++- `A`:驗證通過、可讀、穩定、邊界執行到位+- `B`:可用,只有少量缺口+- `C`:部分可用,存在明顯混亂或不穩定+- `D`:損壞、不安全,或結構上說不清楚++## 產品領域++| 領域 | 評級 | 驗證狀態 | Agent 可讀性 | 測試穩定性 | 關鍵缺口 | 上次更新 |+|------|------|---------|-------------|-----------|---------|---------|+| `[domain-a]` | - | - | - | - | - | - |+| `[domain-b]` | - | - | - | - | - | - |+| `[domain-c]` | - | - | - | - | - | - |++## 架構層++| 層級 | 評級 | 邊界執行 | Agent 可讀性 | 關鍵缺口 | 上次更新 |+|------|------|---------|-------------|---------|---------|+| Types | - | - | - | - | - |+| Services | - | - | - | - | - |+| Runtime | - | - | - | - | - |+| UI | - | - | - | - | - |++## Benchmark 快照++| 日期 | Harness 變體 | 完成率 | 重試次數 | Review 前缺陷數 | 備註 |+|------|-------------|-------|---------|----------------|------|+| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |++## 簡化實驗日誌++| 日期 | 移除的組件 | 結果 | 決策 |+|------|-----------|------|------|+| YYYY-MM-DD | `[component]` | `[degraded / unchanged]` | `[restore / keep removed]` |diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/RELIABILITY.mdnew file mode 100644index 0000000..1c5b4cf--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/RELIABILITY.md@@ -0,0 +1,32 @@+# RELIABILITY.md++這份檔案定義系統如何證明自己健康、可診斷、可重啟。++## 標準路徑++- Bootstrap:`[command]`+- Verification:`[command]`+- 啟動應用或服務:`[command]`+- 調試或查看運行態:`[command]`++## 必需運行信號++- 啟動與關鍵流程的結構化日誌+- 關鍵服務的 health check+- 條件允許時為慢路徑提供 trace 或 timing 數據+- 對可恢復失敗提供用戶可見的錯誤狀態++## 黃金旅程++- `[journey 1]`+- `[journey 2]`+- `[journey 3]`++每條黃金旅程都應該有可重複的驗證路徑和清晰的失敗信號。++## 可靠性規則++- 只要系統不能幹淨重啟,功能就不能算完成。+- 運行失敗必須能從 repo-local 信號裡定位。+- 某類失敗模式一旦反覆出現,就給它補 benchmark 或 guardrail。+- cleanup 屬於可靠性的一部分,不是另外一件事。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/SECURITY.mdnew file mode 100644index 0000000..ef80922--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/SECURITY.md@@ -0,0 +1,27 @@+# SECURITY.md++這份檔案定義那些 agent 絕不能靠猜來處理的安全規則。++## Secrets 與憑證++- 絕不把 secrets 硬編碼進源碼或文檔。+- 在這裡記錄允許的 secret 加載路徑。+- 從日誌和截圖裡去掉 token、API key 與個人數據。++## 不可信輸入++- 外部內容在驗證前一律視為不可信。+- 把允許的抓取或執行邊界寫在這裡。+- 如果存在 prompt injection 或 command injection 風險,要把 guardrail 記錄清楚。++## 外部動作++- 列出哪些動作必須顯式批準。+- 記錄哪些生產或破壞性命令默認不能跑。+- 調試和驗證優先走 sandbox-safe 路徑。++## 依賴與評審規則++- 新依賴必須在 active plan 裡說明理由。+- 涉及安全的改動必須有顯式驗證步驟。+- 反覆出現的安全 review 評論要升級成檢查,而不是變成口口相傳的經驗。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.mdnew file mode 100644index 0000000..daba7fa--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md@@ -0,0 +1,9 @@+# 核心信念++- 倉庫就是 agent 的唯一事實來源。+- `AGENTS.md` 是路由器,不是百科全書。+- 驗證證據比自信更重要。+- 一次做好一個有邊界的任務,勝過同時開很多半成品。+- 反覆出現的人類反饋要升級成可複用的 harness 規則。+- 清理與簡化都是交付的一部分,不是事後補救。+- 如果 agent 不能在倉庫裡發現某個事實,就把這個事實視為運行上不存在。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/index.mdnew file mode 100644index 0000000..e20b47e--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/index.md@@ -0,0 +1,21 @@+# 設計文檔索引++把這份索引當成設計歷史的可發現地圖。++## Accepted++- `core-beliefs.md`:agent-first 的運行信念與持久項目規範++## Proposed++- `[在這裡添加新的設計文檔路徑]`++## Deprecated++- `[把被替代或過期的設計文檔移到這裡,並给出替代鏈接]`++## 維護規則++- 每份設計文檔都應該有 owner 或更新觸發條件。+- 過期文檔要麼刪除,要麼明確標成 deprecated,不要讓它悄悄漂移。+- active execution plan 要鏈接自己依賴的設計文檔。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/active/index.mdnew file mode 100644index 0000000..e06af85--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md@@ -0,0 +1,9 @@+# 當前執行計劃++這個檔案夾裡每一份 markdown 都代表一份當前仍在執行的計劃。++建議檔案名格式:++- `YYYY-MM-DD-short-topic.md`++每份 active plan 都應該足夠新,讓一個沒有聊天上下文的新 agent 也能只靠倉庫繼續推進。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.mdnew file mode 100644index 0000000..9bd8a1c--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md@@ -0,0 +1,3 @@+# 已完成計劃++已完成的計劃移動到這裡,不要直接刪掉。完成計劃也是倉庫記憶面的一部分,後續 agent 需要靠它理解代碼為什麼會變成現在這樣。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.mdnew file mode 100644index 0000000..2f29987--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md@@ -0,0 +1,7 @@+# 技術債跟蹤++這份檔案只記錄那些真實存在、已經確認、並且被有意識延後的技術債。++| 日期 | 區域 | 債務 | 為什麼延後 | 風險 | 下次觸發點 |+|------|------|------|-----------|------|-----------|+| YYYY-MM-DD | `[area]` | `[debt]` | `[reason]` | `[risk]` | `[when to revisit]` |diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/generated/db-schema.mdnew file mode 100644index 0000000..f974f01--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/generated/db-schema.md@@ -0,0 +1,13 @@+# 數據庫結構++這個目錄用來存放那些生成出來但又值得 agent 直接閱讀的工件,避免它每次都去源碼裡反推。++## 來源++- 生成命令或來源:`[command or source path]`+- 最近刷新時間:`YYYY-MM-DD`++## 備註++- 生成部分不要手改。+- 底層 schema 一變,就重新生成這份檔案。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/index.mdnew file mode 100644index 0000000..8d3b423--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/index.md@@ -0,0 +1,13 @@+# 產品規格索引++這個目錄用來放當前仍然有效的用戶可見行為規格。++## 當前有效規格++- `new-user-onboarding.md`++## 規則++- spec 重點描述用戶可見行為和驗收標準。+- 如果實現和 spec 不一致,要在同一輪會話裡更新其中一方。+- 保持這份索引是最新的,讓新 agent 能快速發現產品範圍。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.mdnew file mode 100644index 0000000..9498ffd--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md@@ -0,0 +1,26 @@+# 新用戶引導++## 目標++描述一個新用戶第一次進入產品時應該經歷的流程。++## 起始條件++- `[流程開始前的狀態]`++## 用戶流程++1. `[步骤一]`+2. `[步骤二]`+3. `[步骤三]`++## 驗收標準++- `[使用者可觀察到的結果]`+- `[使用者可觀察到的結果]`+- `[使用者可觀察到的結果]`++## 失敗狀態++- `[可恢复錯誤與使用者反馈]`+- `[被阻塞狀態與兜底方案]`diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txtnew file mode 100644index 0000000..415075c--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt@@ -0,0 +1,9 @@+用途:存放给模型阅读的 design system 参考材料。++建议内容:+- 组件命名规则+- 间距与字体 token+- 状态变体+- 可访问性要求++保持文件简洁;上游设计系统变化时及时刷新。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txtnew file mode 100644index 0000000..a8295b1--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt@@ -0,0 +1,7 @@+用途:存放仓库依赖的部署或打包规则的 agent-readable 摘要。++建议内容:+- build 入口+- runtime 假设+- 环境变量要求+- 常见失败特征diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/uv-llms.txtnew file mode 100644index 0000000..0f33a52--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/references/uv-llms.txt@@ -0,0 +1,7 @@+用途:当仓库依赖 `uv` 或类似工具时,存放一份紧凑的 Python 包与环境工作流参考。++建议内容:+- install 与 sync 命令+- lockfile 策略+- virtualenv 约定+- verification 命令diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/index.mdnew file mode 100644index 0000000..808e303--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/repo-template/index.md@@ -0,0 +1,22 @@+# 高級倉庫範本++當你希望把倉庫升級成更接近 OpenAI 文中那種 agent-first 文檔面,而不只是一個最小 harness 時,就複製這套起步範本。++## 推薦複製順序++1. 先把 `AGENTS.md` 和 `ARCHITECTURE.md` 放到倉庫根目錄。+2. 再複製整個 `docs/` 目錄樹。+3. 優先把 `docs/PRODUCT_SENSE.md`、`docs/QUALITY_SCORE.md`、+ `docs/RELIABILITY.md` 填起來。+4. 在 `docs/exec-plans/active/` 下創建你的第一份 active plan。+5. 始終保持入口檔案很短,詳細規則拆到鏈接文檔裡。++## 這套範本主要優化什麼++- 持久、repo-local 的上下文+- 漸進披露,而不是一個超長 instruction 檔案+- 明確的計劃生命週期+- 隨時間演化的質量追蹤+- 對 agent 和人都更可讀的邊界++這裡的每個檔案都只是起點。真正投入使用前,把佔位文字、示例命令和樣例規則替換成你自己的項目現實。diff --git a/docs/zh-TW/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/zh-TW/resources/openai-advanced/sops/chrome-devtools-validation-loop.mdnew file mode 100644index 0000000..04fd9a3--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/sops/chrome-devtools-validation-loop.md@@ -0,0 +1,48 @@+# SOP:Chrome DevTools 驗證閉環++當 UI 改動必須經過真實交互、截圖、DOM 狀態和 console 輸出來判斷,而不是隻靠讀代碼時,就用這份 SOP。++## 目標++把 UI 驗證變成 agent 可以反覆執行的交互閉環,直到這條用戶旅程變乾淨。++## 核心閉環++1. 選定目標頁面或 app 實例。+2. 清掉舊的 console 噪聲。+3. 記錄 BEFORE 狀態。+4. 觸發 UI 路徑。+5. 觀察交互過程中的 runtime events。+6. 記錄 AFTER 狀態。+7. 修復問題,必要時重啟 app。+8. 反覆重跑驗證,直到這條旅程 clean。++## 必需輸入++- 穩定的啟動命令+- 可重複的 UI journey+- 能抓 DOM、console 或截圖的方式+- 明確“什麼算 clean”的規則++## 執行 SOP++1. 把目標旅程寫進 active plan。+2. 用可觀察行為定義成功:文本出現、按鈕可點、錯誤消失、console 乾淨、請求成功。+3. 交互前先拍初始狀態。+4. 一次只觸發一條路徑。+5. 記錄 runtime event、DOM 變化和可見輸出。+6. 如果失敗,只修最小負責層,然後重啟。+7. 重跑同一路徑,對比 BEFORE/AFTER 證據。++## Clean 標準++- 目標可見狀態已經出現+- 沒有意外錯誤+- console 噪聲已理解或清理+- 重跑同一路徑結果一致++## 需要同步更新的倉庫工件++- 當前 active execution plan+- 如果它變成黃金旅程,更新 `docs/RELIABILITY.md`+- 如果可見行為改變了,更新 product specdiff --git a/docs/zh-TW/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/zh-TW/resources/openai-advanced/sops/encode-knowledge-into-repo.mdnew file mode 100644index 0000000..37ac582--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/sops/encode-knowledge-into-repo.md@@ -0,0 +1,42 @@+# SOP:把不可見知識編碼進倉庫++當重要上下文還散落在 Google Docs、聊天記錄、ticket 或人的腦子裡時,就用這份 SOP。++## 目標++讓那些 agent 以前看不見的知識,變成 codebase 裡可發現、可讀取、可執行的事實。++## 觸發信號++- agent 總在追問系統到底怎麼運作。+- 人開始說“這個是 Slack 裡定過的”或“按某某上週說的做”。+- review 裡經常引用倉庫裡根本沒寫下來的產品、安全或架構規則。+- 新會話總在重複那些本該已經穩定下來的發現工作。++## 執行 SOP++1. 先列出所有不可見知識來源:外部文檔、聊天、默認團隊規則、口頭決策。+2. 對每條知識判斷:它屬於架構、產品行為、安全策略、可靠性要求、執行上下文,還是參考材料?+3. 按類別編碼到對應倉庫工件:+ - 架構 -> `ARCHITECTURE.md`+ - 產品行為 -> `docs/product-specs/`+ - 設計理由 -> `docs/design-docs/`+ - 執行狀態 -> `docs/exec-plans/`+ - 外部參考材料 -> `docs/references/`+ - 質量或可靠性要求 -> `docs/QUALITY_SCORE.md` 或 `docs/RELIABILITY.md`+4. 把模糊表達改寫成運行上真正有用的表達。+5. 刪除或廢棄舊副本,保證倉庫裡有一個可發現的真相來源。++## 好的編碼規則++- 為“可發現”而寫,不是為“寫得很全”而寫。+- 檔案儘量短,名字儘量明確。+- 相關工件要互相鏈接。+- 記錄耐久規則,不要把會議流水賬原封不動塞進來。+- 決策形成的同一輪會話裡,就把倉庫更新掉。++## 完成定義++- 一個全新 agent 不問人也能找到相關規則。+- 同一個事實不會散落在多個互相打架的檔案裡。+- 新工件放在離它所治理的代碼或流程最近的地方。diff --git a/docs/zh-TW/resources/openai-advanced/sops/index.md b/docs/zh-TW/resources/openai-advanced/sops/index.mdnew file mode 100644index 0000000..9f43735--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/sops/index.md@@ -0,0 +1,23 @@+# OpenAI 高級 SOP++這些 SOP 把文章裡的工作方式翻成可以直接參考、執行、改造的操作手冊。++## 包含哪些 SOP++- [`layered-domain-architecture.md`](./layered-domain-architecture.md):+ 搭建顯式分層與跨領域邊界+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):+ 把聊天、外部文檔、腦內知識變成 repo-local 文檔+- [`observability-feedback-loop.md`](./observability-feedback-loop.md):+ 給 agent 提供 logs、metrics、traces 與可重複的調試閉環+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):+ 用瀏覽器自動化和快照反覆驗證 UI,直到 clean++## 怎麼用++1. 先選和你當前瓶頸最匹配的 SOP。+2. 按檢查清單補齊缺失工件或工具。+3. 把得到的規則編碼回 `repo-template/` 裡的文檔。+4. 把反覆出現的 review 評論升級成檢查、腳本或 guardrail。++這些 SOP 不是讓你機械照抄,而是為了讓 harness 更可讀、更可執行、更可複用。diff --git a/docs/zh-TW/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/zh-TW/resources/openai-advanced/sops/layered-domain-architecture.mdnew file mode 100644index 0000000..ff201f9--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/sops/layered-domain-architecture.md@@ -0,0 +1,47 @@+# SOP:分層領域架構++當 agent 反覆跨層亂連、在不同層重複邏輯、或者幾輪會話後代碼越來越難審時,就用這份 SOP。++## 目標++把領域邊界寫清楚、立起來、能執行,讓 agent 在高速度下也不至於悄悄把結構做爛。++## 目標模型++在一個業務領域內部,優先使用這條單向流:++`Types -> Config -> Repo -> Service -> Runtime -> UI`++跨領域關注點通過明確的 provider 或 adapter 進入。共享 utils 保持在領域之外,不能慢慢長成業務邏輯垃圾場。++## 建設檢查清單++- 在 `ARCHITECTURE.md` 裡列清當前 domains。+- 在 `ARCHITECTURE.md` 裡寫清允許的依賴方向。+- 記錄 auth、telemetry、外部 API 等 cross-cutting interface。+- 為當前最難處理的邊界違規寫一條短說明。+- 決定哪些規則應該升級成 lint、test 或 script。++## 執行 SOP++1. 先給代碼庫畫 domain map,再談實現風格。+2. 對每個 domain,明確允許的 layer sequence。+3. 找出所有橫切關注點,並把它們改走 provider 或 adapter。+4. 把含糊的 shared logic 重新放回所屬 domain,或抽成真正通用的 utils。+5. 把規則寫進 `ARCHITECTURE.md`。+6. 先為代價最高的一類違規補一個可執行 guardrail。+7. 改完後更新質量評分。++## 完成定義++- 一個全新的 agent 能判斷某個改動應該落在哪一層。+- UI 不再直接連 repo 或外部副作用。+- 橫切能力都有明確入口。+- 至少一條重要邊界已經被機械執行。++## 需要同步更新的倉庫工件++- `ARCHITECTURE.md`+- `docs/QUALITY_SCORE.md`+- 如果設計理由變了,更新 `docs/design-docs/`+- `docs/PLANS.md` 或當前 active execution plandiff --git a/docs/zh-TW/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/zh-TW/resources/openai-advanced/sops/observability-feedback-loop.mdnew file mode 100644index 0000000..fea7238--- /dev/null+++ b/docs/zh-TW/resources/openai-advanced/sops/observability-feedback-loop.md@@ -0,0 +1,42 @@+# SOP:可觀測性反饋閉環++當調試太慢、agent 總在沒證據的情況下宣佈成功、或者運行時行為比代碼本身還難看懂時,就用這份 SOP。++## 目標++給 agent 一套本地閉環,讓它可以基於 logs、metrics、traces 和可重複 workload 來判斷系統,而不是隻靠看代碼猜。++## 最小可用棧++- 應用輸出結構化日誌+- 條件允許時輸出 metrics 和 traces+- 本地採集或 fan-out 層+- 可查詢 logs / metrics / traces 的接口+- 每次改動後都能重跑的 workload 或 user journey++## 執行 SOP++1. 先定義最重要的黃金運行旅程。+2. 給啟動流程和關鍵路徑補結構化日誌。+3. 在合適位置補 latency、failure count、queue depth 之類的 metrics。+4. 為慢路徑或多階段流程補 traces 或 timing 標記。+5. 讓這些信號能從本地開發環境查詢到。+6. 給 agent 一條可以反覆重跑的 workload 或場景。+7. 強制執行這條閉環:query -> correlate -> reason -> implement -> restart+ -> rerun -> verify。++## 調試會話檢查清單++- 到底哪裡失敗了?+- 哪條信號能證明它失敗?+- 失敗歸屬哪一層?+- 修復後哪條信號發生了變化?+- App 是否能幹淨重啟?+- 同一 workload 重跑後是否通過?++## 完成定義++- agent 能用運行證據解釋失敗模式。+- 每次改動後都能重跑同一 workload。+- restart 與 rerun 已經成為正常任務循環的一部分。+- 可靠性信號已經記錄到 `docs/RELIABILITY.md`。diff --git a/docs/zh-TW/resources/reference/coding-agent-startup-flow.md b/docs/zh-TW/resources/reference/coding-agent-startup-flow.mdnew file mode 100644index 0000000..aa01f4b--- /dev/null+++ b/docs/zh-TW/resources/reference/coding-agent-startup-flow.md@@ -0,0 +1,33 @@+# 編碼代理開工流程++初始化完成後,每輪編碼會話都按這個流程開始。++## 固定開工範本++1. 運行 `pwd`,確認倉庫根目錄+2. 讀取 `claude-progress.md`+3. 讀取 `feature_list.json`+4. 用 `git log --oneline -5` 查看最近提交+5. 運行 `./init.sh`+6. 跑一條基礎 smoke test 或端到端路徑+7. 如果基礎狀態已壞,先修這個+8. 選擇最高優先級的未完成功能+9. 只圍繞這個功能工作,直到它被驗證或明確 blocked++## 為什麼順序不能亂++- `pwd` 能防止在錯誤目錄裡幹活+- progress 和 feature 檔案先恢復持久狀態+- 最近提交能解釋剛剛發生了什麼+- `init.sh` 讓啟動過程標準化,而不是靠記憶+- 基礎驗證先跑,可以避免在壞狀態上繼續疊改動++## 對應的收尾流程++同一輪會話結束時,也應該鏡像地做這些事:++1. 記錄進度+2. 更新功能狀態+3. 必要時寫交接摘要+4. 提交安全狀態的代碼+5. 留下可直接重啟的乾淨環境diff --git a/docs/zh-TW/resources/reference/index.md b/docs/zh-TW/resources/reference/index.mdnew file mode 100644index 0000000..040b2ab--- /dev/null+++ b/docs/zh-TW/resources/reference/index.md@@ -0,0 +1,71 @@+# 中文參考++這一部分解釋這些範本該怎麼配合使用,而不是把它們當成一堆孤立檔案。++## 內部參考材料++- [`method-map.md`](./method-map.md):把常見長時任務翻車點映射到對應方法和工件+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md):初始化代理在第一輪應該產出什麼+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md):後續編碼代理每次開工的固定流程+- [`prompt-calibration.md`](./prompt-calibration.md):根指令應該寫到什麼程度才合適++## 重點參考文章++這裡的篩選標準很窄:只保留能直接解釋 harness 機制的文章。Harness 在這裡指模型外部的運行系統,包括 agent loop、工具執行、沙箱、狀態、上下文、驗證、終止條件、控制平面和觀測反饋;不是泛泛的 prompt engineering 或 agent 框架介紹。++保留原始三篇作為課程主軸:++- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)(2026-02-11):agent-first 倉庫、repo-local context、custom lint、結構性 guardrail。+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)(2025-11-26):initializer agent、coding agent、feature list、progress log、跨上下文窗口交接。+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)(2026-03-24):planner / generator / evaluator 三角色、context reset、harness 簡化和組件過期問題。++額外只加入幾篇高相關、高含金量的 2026 文章:++- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)(2026-01-23):解釋 Codex runtime harness 的核心循環、工具調用、上下文增長和終止狀態。+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)(2026-01-09):明確評估 agent 時評的是 model + harness,並區分 evaluation harness 與 agent harness。+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)(2026-02-17):同一模型不變,只改 system prompt、tools、middleware、tracing 和 self-verification,讓 coding agent 在 Terminal Bench 2.0 上從 Top 30 進到 Top 5。+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)(2026-04-02):把 coding-agent user harness 拆成 feedforward guides 和 feedback sensors,並區分 deterministic controls 與 inferential controls。+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)(2026-04-30):把 harness 當成持續迭代的產品系統,用離線評估、線上指標、工具錯誤分類、模型定製和 mid-chat model switching 改善 agent 行為。++## 2026 擴展參考++這些文章不作為課程主軸,但在設計特定 harness 模塊時很有借鑑價值。只保留文章正文直接涉及 agent loop、工具執行、上下文管理、驗證、沙箱、控制層、迴歸治理等機制的材料;純 agent 產品、平臺發佈、團隊實踐或 benchmark 不放進這裡。++- [OpenAI: Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/)(2026-02-04):把 harness 抽象成 App Server 協議,覆蓋 thread lifecycle、resume、fork、diff 和客戶端集成。+- [OpenAI Developers: Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex)(2026-02-23):長時任務中的 durable project memory、milestone validation 和 done-when 例子。+- [OpenAI: The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/)(2026-04-15):model-native harness、sandbox execution、檔案與命令執行能力。+- [OpenAI: An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/)(2026-04-27):把 issue tracker / Linear 變成多 agent 控制平面。+- [Anthropic: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler)(2026-02-05):並行 agent 團隊、任務鎖、git 同步、容器隔離和自主循環。+- [Anthropic: Scaling Managed Agents: Decoupling the brain from the hands](https://www.anthropic.com/engineering/managed-agents)(2026-04-08):meta-harness 視角,把 session、harness、sandbox 拆成可替換接口。+- [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem)(2026-04-23):reasoning effort、context pruning、system prompt 都屬於 harness 變更,且需要回歸治理。+- [LangChain: Context Management for Deep Agents](https://www.langchain.com/blog/context-management-for-deepagents)(2026-01-28):filesystem offloading、tool-call truncation、summarization 和 targeted evals 組成的 context-management harness。+- [LangChain: Tuning Deep Agents to Work Well with Different Models](https://www.langchain.com/blog/tuning-deep-agents-different-models)(2026-04-29):用 model-specific harness profiles 調整 prompt、tool names、middleware 和 subagent 配置。+- [LangChain: Continual learning for AI agents](https://www.langchain.com/blog/continual-learning-for-ai-agents)(2026-04-05):把 agent 改進拆成 model、harness、context 三層,並把 traces 作為改進信號。+- [Microsoft: Agent Harness in Agent Framework](https://devblogs.microsoft.com/agent-framework/agent-harness-in-agent-framework/)(2026-03-12):shell/filesystem harness、approval flow、hosted shell、context compaction。+- [Google: Announcing ADK for Java 1.0.0](https://developers.googleblog.com/announcing-adk-for-java-100-building-the-future-of-ai-agents-in-java/)(2026-03-30):插件、event compaction、HITL、session/memory service、A2A 等可複用 harness primitives。+- [GitHub: Automate repository tasks with GitHub Agentic Workflows](https://github.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflows/)(2026-02-13):把 GitHub Actions 變成 agentic workflow runner,包含 safe outputs、sandboxing、permissions、review。+- [AWS: AI agents in enterprises: Best practices with Amazon Bedrock AgentCore](https://aws.amazon.com/blogs/machine-learning/ai-agents-in-enterprises-best-practices-with-amazon-bedrock-agentcore/)(2026-02-03):Runtime、Memory、Gateway、Identity/Policy、Observability、Evaluations 的企業級 harness 分層。+- [Stripe: Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)(2026-02-09)和 [Part 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2)(2026-02-19):devbox 隔離、custom agent harness、blueprints 狀態機、規則檔案、MCP tool curation、安全控制、pre-push/CI 反饋循環。+- [Cognition: What We Learned Building Cloud Agents](https://cognition.ai/blog/what-we-learned-building-cloud-agents)(2026-04-23):雲端 agent runtime 的 VM 隔離、session snapshot/resume、orchestration、governance、audit logging 和 integrations。+- [Cognition: Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working)(2026-04-22):generator-verifier loop、clean-context reviewer、smart-friend routing、manager-child coordination 和跨 agent 通信邊界。+- [Replit: Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance)(2026-01-20,2026-01-23 更新):用輕量分類器在關鍵決策點注入短指令,而不是把所有規則塞進系統提示詞。+- [Vercel: How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent)(2026-01-07):動態系統提示、streaming rewrite layer 和 deterministic/model-driven autofixers。+- [Vercel: Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base)(2026-05-04):面向安全掃描的 coding-agent harness,包含 scan、investigate、revalidate、enrich、export、plugin 和 refusal-checker。+- [Sourcegraph: CodeScaleBench](https://sourcegraph.com/blog/codescalebench-testing-coding-agents-on-large-codebases-and-multi-repo-software-engineering-tasks)(2026-03-03):偏 eval/tooling harness,包含 MCP tool adoption、tool-use transcripts、benchmark QA、verifier/reproducibility gates 和 prompt/preamble 迭代。++嚴格按時間篩選時,2025-only 的泛參考不進入主列表。原始三篇中的 Anthropic 2025 文章保留,是因為它是本課程方法的基礎來源。++## 推薦閱讀順序++1. `method-map.md`+2. `initializer-agent-playbook.md`+3. `coding-agent-startup-flow.md`+4. `prompt-calibration.md`+5. OpenAI Harness engineering+6. Anthropic Effective harnesses+7. Anthropic Harness design for long-running application development+8. OpenAI Codex agent loop+9. Anthropic agent evals+10. LangChain Improving Deep Agents+11. Thoughtworks / Martin Fowler Harness engineering for coding agent users+12. Cursor Continually improving our agent harnessdiff --git a/docs/zh-TW/resources/reference/initializer-agent-playbook.md b/docs/zh-TW/resources/reference/initializer-agent-playbook.mdnew file mode 100644index 0000000..ac38751--- /dev/null+++ b/docs/zh-TW/resources/reference/initializer-agent-playbook.md@@ -0,0 +1,35 @@+# 初始化代理操作手冊++這個手冊用於倉庫裡的第一輪重要會話,也就是正式開始增量開發之前的初始化階段。++## 目標++先搭出穩定的工作面,讓後續會話不必重新推導啟動命令、當前狀態和任務邊界。++## 必需產出++初始化階段至少應該留下這些工件:++- 一個根指令檔案,例如 `AGENTS.md` 或 `CLAUDE.md`+- 一個機器可讀的功能面,例如 `feature_list.json`+- 一個持久進度工件,例如 `claude-progress.md`+- 一個標準啟動輔助腳本,例如 `init.sh`+- 一個記錄基礎腳手架狀態的初始安全提交++## 檢查清單++1. 定義標準啟動路徑+2. 定義標準驗證路徑+3. 建立進度日誌並寫下初始狀態+4. 把工作拆成功能,並給出狀態字段+5. 建立第一個乾淨的 baseline commit++## 成功標準++一個完全沒有前文聊天上下文的新會話,應該能回答:++- 這個倉庫是做什麼的+- 怎麼啟動+- 怎麼驗證+- 還有什麼沒做完+- 下一步最佳動作是什麼diff --git a/docs/zh-TW/resources/reference/method-map.md b/docs/zh-TW/resources/reference/method-map.mdnew file mode 100644index 0000000..3c3ea37--- /dev/null+++ b/docs/zh-TW/resources/reference/method-map.md@@ -0,0 +1,16 @@+# 方法對照表++這個表把最常見的長時 coding-agent 失敗模式,對應到最先該補的工件或規則。++| 失敗模式 | 實際表現 | 首要修復 | 主要工件 |+| --- | --- | --- | --- |+| 冷啟動混亂 | 新會話花大量時間重新摸索狀態和啟動方式 | 讓倉庫成為唯一事實來源 | `claude-progress.md` |+| 範圍蔓延 | 一次啟動多個功能,最後沒有一個完整收尾 | 限制當前活躍範圍 | `feature_list.json` |+| 提前宣佈完成 | 代碼改了就說“完成了”,但沒有可運行證據 | 把完成綁定到驗證證據 | `clean-state-checklist.md` |+| 啟動脆弱 | 每輪會話都要重新學怎麼啟動項目 | 統一啟動與驗證路徑 | `init.sh` |+| 交接薄弱 | 下一輪看不出哪裡可用、哪裡壞了、接下來做什麼 | 明確寫交接摘要 | `session-handoff.md` |+| 評審主觀 | 質量判斷依賴個人記憶和感覺 | 用固定維度做評分 | `evaluator-rubric.md` |++## 使用原則++優先補最能直接消除當前失敗模式的那個工件,不要一出問題就把更多規則堆進一個超長 instruction 檔案裡。diff --git a/docs/zh-TW/resources/reference/prompt-calibration.md b/docs/zh-TW/resources/reference/prompt-calibration.mdnew file mode 100644index 0000000..37cae1e--- /dev/null+++ b/docs/zh-TW/resources/reference/prompt-calibration.md@@ -0,0 +1,23 @@+# Prompt 校準++根指令檔案應該定義工作框架,而不是把所有動作寫死。++## 應該留在根檔案裡的內容++- 倉庫用途和範圍+- 啟動路徑+- 驗證路徑+- 不可違反的約束+- 必需的狀態工件+- 會話結束規則++## 應該移出根檔案的內容++- 過長的歷史邊角案例+- 只屬於某個子系統的細節實現說明+- 更適合貼在代碼附近的局部架構筆記+- 只對單一模塊成立的示例++## 工作原則++根檔案的職責是讓新會話快速建立方向感。如果它開始變成“過去每次失敗都往裡加一句”的堆疊場,就應該把細節拆到更小、更明確的文檔裡,再從根檔案跳轉過去。diff --git a/docs/zh-TW/resources/templates/AGENTS.md b/docs/zh-TW/resources/templates/AGENTS.mdnew file mode 100644index 0000000..2cbbce1--- /dev/null+++ b/docs/zh-TW/resources/templates/AGENTS.md@@ -0,0 +1,50 @@+# AGENTS.md++這個倉庫面向長時運行的 coding agent 工作流。目標不是儘可能快地產出代碼,而是讓每一輪會話結束後,下一個會話仍然能無猜測地繼續工作。++## 開工流程++寫代碼前先做這些事:++1. 用 `pwd` 確認當前目錄。+2. 讀取 `claude-progress.md`,瞭解最新已驗證狀態和下一步。+3. 讀取 `feature_list.json`,選擇優先級最高的未完成功能。+4. 用 `git log --oneline -5` 看最近提交。+5. 運行 `./init.sh`。+6. 在開始新功能前,先跑必需的 smoke test 或端到端驗證。++如果基礎驗證一開始就失敗,先修基礎狀態,不要在壞的起點上繼續疊新功能。++## 工作規則++- 一次只做一個功能。+- 不要因為“代碼已經寫了”就把功能標記為完成。+- 除非為了消除當前 blocker 的窄範圍修復,否則不要擴大到其他功能。+- 實現過程中不要悄悄改弱驗證規則。+- 優先依賴倉庫裡的持久化檔案,而不是聊天記錄。++## 必需檔案++- `feature_list.json`:功能狀態的唯一事實來源+- `claude-progress.md`:會話進度和當前已驗證狀態+- `init.sh`:統一的啟動與驗證入口+- `session-handoff.md`:較長會話可選的交接摘要++## 完成定義++一個功能只有在以下條件都滿足時才算完成:++- 目標行為已經實現+- 要求的驗證真的跑過+- 證據記錄在 `feature_list.json` 或 `claude-progress.md`+- 倉庫仍然能按標準啟動路徑重新開始工作++## 收尾++結束會話前:++1. 更新 `claude-progress.md`+2. 更新 `feature_list.json`+3. 記錄仍未解決的風險或 blocker+4. 在工作處於安全狀態後,用清晰的提交信息提交+5. 保證下一輪會話可以直接運行 `./init.sh`diff --git a/docs/zh-TW/resources/templates/CLAUDE.md b/docs/zh-TW/resources/templates/CLAUDE.mdnew file mode 100644index 0000000..58293de--- /dev/null+++ b/docs/zh-TW/resources/templates/CLAUDE.md@@ -0,0 +1,43 @@+# CLAUDE.md++你正在一個為長時實現工作設計的倉庫中工作。優先保證可靠完成、跨會話連續性和顯式驗證,而不是表面上的速度。++## 固定工作循環++每輪會話開始時:++1. 運行 `pwd`,確認當前在正確的倉庫根目錄+2. 讀取 `claude-progress.md`+3. 讀取 `feature_list.json`+4. 用 `git log --oneline -5` 查看最近提交+5. 運行 `./init.sh`+6. 檢查基礎 smoke test 或端到端路徑是否已經損壞++然後只選擇一個未完成功能,圍繞它工作,直到它被驗證通過,或者被明確記錄為 blocked。++## 規則++- 同一時間只能有一個 active feature+- 沒有可運行證據時,不要聲稱完成+- 不要通過重寫功能清單來隱藏未完成工作+- 不要為了“看起來完成”而刪除或削弱測試+- 以倉庫內檔案作為唯一事實來源++## 必需檔案++- `feature_list.json`+- `claude-progress.md`+- `init.sh`+- 需要簡短交接時使用 `session-handoff.md`++## 完成門檻++只有在要求的驗證成功且結果被記錄後,功能狀態才可以切換到 `passing`。++## 結束前++1. 更新進度日誌+2. 更新功能狀態+3. 記錄仍然損壞或未驗證的內容+4. 在倉庫可安全恢復後提交+5. 給下一輪會話留下乾淨的重啟路徑diff --git a/docs/zh-TW/resources/templates/claude-progress.md b/docs/zh-TW/resources/templates/claude-progress.mdnew file mode 100644index 0000000..c4aac3f--- /dev/null+++ b/docs/zh-TW/resources/templates/claude-progress.md@@ -0,0 +1,35 @@+# 進度日誌++## 當前已驗證狀態++- 倉庫根目錄:+- 標準啟動路徑:+- 標準驗證路徑:+- 當前最高優先級未完成功能:+- 當前 blocker:++## 會話記錄++### Session 001++- 日期:+- 本輪目標:+- 已完成:+- 運行過的驗證:+- 已記錄證據:+- 提交記錄:+- 更新過的檔案或工件:+- 已知風險或未解決問題:+- 下一步最佳動作:++### Session 002++- 日期:+- 本輪目標:+- 已完成:+- 運行過的驗證:+- 已記錄證據:+- 提交記錄:+- 更新過的檔案或工件:+- 已知風險或未解決問題:+- 下一步最佳動作:diff --git a/docs/zh-TW/resources/templates/clean-state-checklist.md b/docs/zh-TW/resources/templates/clean-state-checklist.mdnew file mode 100644index 0000000..edf0839--- /dev/null+++ b/docs/zh-TW/resources/templates/clean-state-checklist.md@@ -0,0 +1,8 @@+# 乾淨狀態檢查清單++- [ ] 標準啟動路徑仍然可用+- [ ] 標準驗證路徑仍然可運行+- [ ] 當前進度已經記錄到進度日誌+- [ ] 功能狀態真實反映了 passing 和未驗證的邊界+- [ ] 沒有任何半成品步驟處於未記錄狀態+- [ ] 下一輪會話無需人工修復即可繼續diff --git a/docs/zh-TW/resources/templates/evaluator-rubric.md b/docs/zh-TW/resources/templates/evaluator-rubric.mdnew file mode 100644index 0000000..456a715--- /dev/null+++ b/docs/zh-TW/resources/templates/evaluator-rubric.md@@ -0,0 +1,24 @@+# 評審評分表++在實現完成後、正式驗收前,用這張表做一次評審。++| 維度 | 問題 | 分數 (0-2) | 備註 |+| --- | --- | --- | --- |+| 正確性 | 實現出來的行為是否符合目標功能? | | |+| 驗證 | 要求的檢查是否真的跑過,並留下證據? | | |+| 範圍紀律 | 這一輪是否基本保持在選定功能範圍內? | | |+| 可靠性 | 結果是否能在重啟或重跑後繼續工作? | | |+| 可維護性 | 代碼和文檔是否清楚到足以交給下一輪會話? | | |+| 交接準備度 | 新會話是否能只靠倉庫內工件繼續推進? | | |++## 結論++- Accept+- Revise+- Block++## 後續動作++- 缺失的證據:+- 必須補的修復:+- 下次複審觸發條件:diff --git a/docs/zh-TW/resources/templates/feature_list.json b/docs/zh-TW/resources/templates/feature_list.jsonnew file mode 100644index 0000000..41b9753--- /dev/null+++ b/docs/zh-TW/resources/templates/feature_list.json@@ -0,0 +1,64 @@+{+ "project": "替换成你的项目名",+ "last_updated": "YYYY-MM-DD",+ "rules": {+ "single_active_feature": true,+ "passing_requires_evidence": true,+ "do_not_skip_verification": true+ },+ "status_legend": {+ "not_started": "功能还没开始做。",+ "in_progress": "这个功能是当前唯一正在进行的任务。",+ "blocked": "因为已记录的阻塞问题,当前无法继续推进。",+ "passing": "要求的验证已经通过,并且证据已经记录。"+ },+ "features": [+ {+ "id": "chat-001",+ "priority": 1,+ "area": "chat",+ "title": "创建新会话",+ "user_visible_behavior": "用户点击 New Chat 后,可以看到一个新的空白对话。",+ "status": "not_started",+ "verification": [+ "打开应用。",+ "点击 New Chat。",+ "确认侧边栏出现一个新会话。",+ "确认主面板显示空白对话状态。"+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-002",+ "priority": 2,+ "area": "chat",+ "title": "在当前会话里发送消息",+ "user_visible_behavior": "用户提交一条消息后,可以在当前线程中看到它。",+ "status": "not_started",+ "verification": [+ "打开一个已有会话。",+ "在输入框中输入消息。",+ "提交消息。",+ "确认线程中出现这条新消息。"+ ],+ "evidence": [],+ "notes": ""+ },+ {+ "id": "chat-003",+ "priority": 3,+ "area": "chat",+ "title": "持久化保存会话列表",+ "user_visible_behavior": "应用重启后,用户仍能看到之前创建的会话。",+ "status": "not_started",+ "verification": [+ "创建两个会话。",+ "重启应用。",+ "确认两个会话仍显示在侧边栏中。"+ ],+ "evidence": [],+ "notes": ""+ }+ ]+}diff --git a/docs/zh-TW/resources/templates/index.md b/docs/zh-TW/resources/templates/index.mdnew file mode 100644index 0000000..6db4c84--- /dev/null+++ b/docs/zh-TW/resources/templates/index.md@@ -0,0 +1,226 @@+# 範本使用指南++這些範本可以直接複製到你的項目裡用。每個檔案在 agent 的工作流程中各有分工。複製過去後,把裡面的命令、路徑、功能名稱和驗證步驟換成你自己項目的。++## 怎麼開始++先把這四個檔案複製到項目根目錄:++1. `AGENTS.md` 或 `CLAUDE.md`+2. `init.sh`+3. `claude-progress.md`+4. `feature_list.json`++等項目變複雜了,再補其餘的檔案。++---++## AGENTS.md++根指令檔案。agent 每次開工會先讀這個檔案。它定義了工作規則:寫代碼前要做什麼、工作過程中怎麼守規矩、收尾時要檢查什麼。++**怎麼用:**++- 複製到項目根目錄+- 把開工流程裡的步驟換成你自己項目的路徑和命令+- 工作規則按你們團隊的約定調整+- 完成定義那一段別改——那是整個 harness 最關鍵的部分++**它幫 agent 做什麼:**++- 讓它在開始工作前先讀進度和功能狀態+- 逼它一次只做一個功能+- 要求它拿出證據才能標記完成+- 定義了什麼叫"乾淨收尾"++用 `AGENTS.md` 給 Codex 或其他 agent。用 `CLAUDE.md` 給 Claude Code——內容一樣,格式按 Claude 的指令風格來的。++## init.sh++啟動腳本。一條命令完成依賴安裝、驗證和打印啟動命令。++**怎麼用:**++- 複製到項目根目錄+- 改頂部這三個變量:+ - `INSTALL_CMD` — 你的依賴安裝命令(比如 `npm install`、`pip install -r requirements.txt`)+ - `VERIFY_CMD` — 你的基礎驗證命令(比如 `npm test`、`pytest`)+ - `START_CMD` — 你的開發服務器啟動命令(比如 `npm run dev`)+- 加執行權限:`chmod +x init.sh`++**它做什麼:**++1. 打印當前目錄(確認跑在正確的地方)+2. 安裝依賴+3. 跑驗證命令+4. 打印啟動命令(如果設了 `RUN_START_COMMAND=1` 就直接啟動)++如果驗證失敗了,agent 應該停下來先修基礎狀態,不要在壞的基礎上繼續疊新功能。++## claude-progress.md++進度日誌。每輪會話往裡寫,每輪新會話先讀它。++**怎麼用:**++- 複製到項目根目錄+- 把"當前已驗證狀態"那段填上你的項目信息+- 每輪會話結束後更新會話記錄++**每個字段的意思:**++- **當前已驗證狀態** — 項目當前進展的唯一真相+ - `倉庫根目录` — 項目在哪+ - `標準啟動路徑` — 把項目跑起來的命令+ - `標準驗證路徑` — 跑測試的命令+ - `当前最高優先級未完成功能` — 下一輪該做什麼+ - `当前 blocker` — 哪裡卡住了+- **會話記錄** — 每輪一條+ - `本輪目標` — 打算做什麼+ - `已完成` — 實際做了什麼+ - `執行過的驗證` — 跑了什麼測試+ - `已記錄證據` — 留下了什麼證明+ - `提交記錄` — 提了什麼 commit+ - `已知风险或未解决問題` — 哪裡可能有問題+ - `下一步最佳動作` — 下一輪從哪開始++## feature_list.json++功能清單。機器可讀的功能列表,每個功能有狀態、驗證步驟和證據。++**怎麼用:**++- 複製到項目根目錄+- 把示例功能換成你自己的+- 每個功能需要填:+ - `id` — 短的唯一標識+ - `priority` — 整數,越小越優先+ - `area` — 屬於應用的哪塊(比如 "chat"、"import"、"search")+ - `title` — 簡短描述+ - `user_visible_behavior` — 功能正常時用戶能看到什麼+ - `status` — 四種狀態之一:`not_started`、`in_progress`、`blocked`、`passing`+ - `verification` — 逐步驗證步驟+ - `evidence` — 驗證通過的記錄(agent 填)+ - `notes` — 額外說明++**狀態規則:**++- `not_started` — 還沒碰+- `in_progress` — 當前正在做的那個(同一時間只能有一個)+- `blocked` — 有記錄的阻塞問題,推不動+- `passing` — 驗證通過,證據已記錄++agent 任何時候只能有一個功能處於 `in_progress`。++## session-handoff.md++會話交接摘要。一輪會話結束時寫,下一輪開始時讀。讓接手的人(或 agent)快速瞭解現狀。++**怎麼用:**++- 複製到項目根目錄+- 每輪會話結束時填寫(也可以讓 agent 自己填)++**每段寫什麼:**++- **當前已驗證** — 哪些是確認能用的,跑過什麼驗證+- **本輪改動** — 改了什麼代碼或基礎設施+- **仍損壞或未驗證** — 已知問題和風險區+- **下一步最佳動作** — 下一輪該做什麼,哪些東西不要動+- **命令** — 啟動、驗證、調試命令,方便快速參考++短會話可以不寫這個檔案。會話長了或者項目有多個並行區域時,它就很關鍵了。++## clean-state-checklist.md++收尾檢查清單。每次會話結束前過一遍,確保倉庫處於下一輪可以直接開工的狀態。++**怎麼用:**++- 複製到項目根目錄+- 關掉會話前逐項檢查+- agent 的收尾流程裡也應該包含這些檢查++**檢查什麼:**++- 標準啟動路徑還能用+- 標準驗證還能跑+- 進度日誌已更新+- 功能清單真實反映了 passing 和未驗證的邊界(沒有假 passing)+- 沒有半成品處於未記錄狀態+- 下一輪會話不需要人工修復就能繼續++## evaluator-rubric.md++評審評分表。會話結束後或到裡程碑時,用它評估 agent 做的東西夠不夠格。++**怎麼用:**++- 複製到項目根目錄+- 一輪(或幾輪)會話後,按六個維度打分+- 每個維度 0-2 分++**六個維度:**++1. **正確性** — 實現出來的行為是否符合目標功能+2. **驗證** — 要求的檢查是否真的跑過,並留下證據+3. **範圍紀律** — 是否基本保持在選定功能範圍內+4. **可靠性** — 結果是否能在重啟或重跑後繼續工作+5. **可維護性** — 代碼和文檔是否清楚到足以交給下一輪會話+6. **交接準備度** — 新會話是否能只靠倉庫內檔案繼續推進++**結論選項:**++- Accept — 達標+- Revise — 需要修補才能接受+- Block — 有根本性問題,需要先解決++**Evaluator 需要校準。** 開箱即用的 agent 做評審很弱——它會發現問題,然後把自己說服到通過。你需要反覆校準:++1. 用 evaluator 給一個已完成的 sprint 打分。+2. 把它的分數和你自己的人工判斷對比。+3. 有分歧的地方,把 rubric 裡的通過/失敗標準寫得更具體。+4. 對同一個輸出重新跑 evaluator,看對齊了沒有。+5. 重複直到 evaluator 的判斷和人工評審基本一致。++預計需要 3-5 輪校準。每輪記錄改了什麼、為什麼改。++## quality-document.md++質量快照。給項目的每個產品領域和架構層打分,跟蹤代碼庫隨時間是變強了還是變弱了。++**怎麼用:**++- 複製到項目根目錄+- 開始會話前:讀它,瞭解代碼庫哪裡最弱+- 會話結束後:更新評級+- 長期:對比不同時間點的快照,看哪些 harness 改動真正改善了代碼庫健康度++**評什麼:**++- **產品領域**(如文檔導入、問答流程、索引):每個領域按驗證狀態、Agent 可讀性、測試穩定性、關鍵缺口打分+- **架構層**(如 Main Process、Preload、Renderer、Services):每層按邊界執行和 Agent 可讀性打分++**為什麼需要它:**++Evaluator rubric 評的是單次 agent 輸出的質量。Quality document 評的是代碼庫本身的質量。它們回答的是不同的問題:++- Evaluator rubric:"這輪 agent 做得好不好?"+- Quality document:"這個項目是在變強還是變弱?"++**什麼時候更新:**++- 每輪重要會話之後+- 做基準對比之前+- 做清理或簡化之後+- 換新 agent 或新模型時++**和 harness 簡化的關係:**++Quality document 也可以用來驗證 harness 是否可以簡化。Harness 裡的每個組件都編碼了一個假設——"模型做不到這件事"。模型變強後,這些假設就過時了。檢查某個組件是否還有必要:++1. 拍一份 quality document 快照。+2. 移除一個 harness 組件。+3. 跑基準測試。+4. 再拍一份快照。+5. 對比——評級沒降,說明那個組件是多餘的。降了,就恢復。diff --git a/docs/zh-TW/resources/templates/init.sh b/docs/zh-TW/resources/templates/init.shnew file mode 100755index 0000000..c153b2a--- /dev/null+++ b/docs/zh-TW/resources/templates/init.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash++set -euo pipefail++ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+cd "$ROOT_DIR"++# 按你的项目实际情况替换这些命令。+INSTALL_CMD=(npm install)+VERIFY_CMD=(npm test)+START_CMD=(npm run dev)++echo "==> 当前目录: $PWD"+echo "==> 同步依赖"+"${INSTALL_CMD[@]}"++echo "==> 运行基础验证"+"${VERIFY_CMD[@]}"++echo "==> 启动命令"+printf ' %q' "${START_CMD[@]}"+printf '\n'++if [ "${RUN_START_COMMAND:-0}" = "1" ]; then+ echo "==> 启动应用"+ exec "${START_CMD[@]}"+fi++echo "如果希望 init.sh 直接启动应用,请设置 RUN_START_COMMAND=1。"diff --git a/docs/zh-TW/resources/templates/quality-document.md b/docs/zh-TW/resources/templates/quality-document.mdnew file mode 100644index 0000000..170c7f3--- /dev/null+++ b/docs/zh-TW/resources/templates/quality-document.md@@ -0,0 +1,43 @@+# 質量文檔++每個產品領域和架構層的質量快照。agent 和人都能通過這份文檔快速瞭解項目哪裡強、哪裡弱。++**更新時機:** 每輪重要會話結束後,或開始新一階段工作前。++**評級標準:**++- **A**:驗證全部通過,架構乾淨,agent 能讀懂,測試穩定+- **B**:驗證通過,基本乾淨,可讀性或測試覆蓋有少量缺口+- **C**:部分可用,有已知缺口,部分代碼 agent 不容易理解+- **D**:不可用,或存在重大結構問題++---++## 產品領域++| 領域 | 評級 | 驗證狀態 | Agent 可讀性 | 測試穩定性 | 關鍵缺口 | 上次更新 |+|------|------|---------|-------------|-----------|---------|---------|+| 文檔導入 | - | - | - | - | - | - |+| 文檔管理 | - | - | - | - | - | - |+| 文檔索引 | - | - | - | - | - | - |+| 問答流程 | - | - | - | - | - | - |+| 引用式回答 | - | - | - | - | - | - |++## 架構層++| 層級 | 評級 | 邊界執行 | Agent 可讀性 | 關鍵缺口 | 上次更新 |+|------|------|---------|-------------|---------|---------|+| Main Process | - | - | - | - | - |+| Preload | - | - | - | - | - |+| Renderer | - | - | - | - | - |+| Services | - | - | - | - | - |++## 變更歷史++### YYYY-MM-DD++- 變更內容:+- 提升:+- 下降:+- 新發現的缺口:+- 已關閉的缺口:diff --git a/docs/zh-TW/resources/templates/session-handoff.md b/docs/zh-TW/resources/templates/session-handoff.mdnew file mode 100644index 0000000..7d7f2f9--- /dev/null+++ b/docs/zh-TW/resources/templates/session-handoff.md@@ -0,0 +1,30 @@+# 會話交接++## 當前已驗證++- 現在明確可用的部分:+- 這輪實際跑過的驗證:++## 本輪改動++- 新增了哪些代碼或行為:+- 基礎設施或 harness 發生了哪些變化:++## 仍損壞或未驗證++- 已知缺陷:+- 未驗證路徑:+- 下一輪會話需要注意的風險:++## 下一步最佳動作++- 最高優先級未完成功能:+- 為什麼它是下一步:+- 什麼結果才算 passing:+- 這一步中哪些東西不要動:++## 命令++- 啟動命令:+- 驗證命令:+- 定向調試命令:diff --git a/docs/zh-TW/skills/index.md b/docs/zh-TW/skills/index.mdnew file mode 100644index 0000000..b1d7560--- /dev/null+++ b/docs/zh-TW/skills/index.md@@ -0,0 +1,49 @@+# Skills(技能集)++本目錄包含課程附帶的 AI agent 技能。每個技能都是自包含的提示詞範本,可被 AI 程式設計智慧體(Claude Code、Codex、Cursor、Windsurf 等)載入以執行專業任務。++## harness-creator++面向 AI 程式設計智慧體的生產級 harness 工程技能。幫助建立、評估和改進五個核心 harness 子系統:指令、狀態、驗證、範圍和會話生命週期。++### 它能做什麼++- **從零建立 harness** — AGENTS.md、功能清單、驗證工作流+- **改進已有 harness** — 五子系統評分 + 優先級改進建議+- **設計會話連續性** — 記憶持久化、進度追蹤、交接機制+- **應用生產級模式** — 記憶、上下文工程、工具安全、多智慧體協調++### 快速開始++技能檔案位於倉庫的 [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator) 目錄。++在 Claude Code 中使用時,將 `harness-creator/` 目錄複製到你專案的技能路徑下,或讓 agent 直接讀取 SKILL.md 檔案即可。++### 參考模式++技能包含 6 個深入的模式參考檔案:++| 模式 | 適用場景 |+|------|----------|+| 記憶持久化 | agent 在會話間遺忘專案知識 |+| 上下文工程 | 上下文預算管理、按需載入、委託隔離 |+| 工具註冊 | 工具安全、併發控制、權限管道 |+| 多智慧體協調 | 平行化、專業化、研究員→實作者工作流 |+| 生命週期與引導 | 鉤子、背景任務、初始化序列 |+| 常見陷阱 | 15 個容易踩坑的失敗模式及修復方案 |++### 範本++技能附帶開箱即用的範本:++- `agents.md` — AGENTS.md 腳手架,包含工作規則+- `feature-list.json` — JSON Schema + 功能列表示例+- `init.sh` — 標準初始化腳本+- `progress.md` — 會話進度日誌範本++### 開發過程++`harness-creator` 基於 **skill-creator** 方法論開發——這是 Anthropic 官方提供的元技能,用於建立、測試和反覆改進 agent 技能。skill-creator 提供了結構化的工作流(起草 → 測試 → 評估 → 迭代),內建評估執行器、評分器和基準檢視器。++- **skill-creator 來源**:[anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)+- **Claude Code 技能檔案**:[anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdindex fface47..17c8865 100644--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -1,10 +1,9 @@-# Failure Signals Checklist+# 失败信号检查清单-Use this checklist when reviewing a weak harness run.+在审查一次弱 harness 运行结果时使用此清单。-- Did the agent ask, or infer incorrectly, how to start the app?-- Did it create directories or abstractions that do not match the intended- product?-- Did it stop after making a visible UI shell without a complete workflow?-- Did it leave notes or artifacts that help a future run continue?-- Could a fresh session understand what happened in under five minutes?+- Agent 是否询问了如何启动应用,或者做出了错误的推断?+- 它是否创建了与预期产品不匹配的目录或抽象?+- 它是否在完成一个可见的 UI 外壳后就停止了,而没有完成完整的工作流?+- 它是否留下了有助于后续运行继续的笔记或产物?+- 一个全新的会话是否能在五分钟内理解之前发生了什么?diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdindex c9885ed..90d0733 100644--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/index.md+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -1,7 +1,7 @@-# Code for Lecture 01+# 第 01 讲代码-Use this folder for small examples that show:+使用此文件夹存放小型示例,用于展示:-- a strong model failing in a weak environment-- underspecified repo setup-- missing feedback loops+- 强大模型在弱环境中的失败+- 规格不完整的仓库设置+- 缺失的反馈循环diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdindex 52fac65..68468fb 100644--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -1,18 +1,18 @@-# Underspecified Task Example+# 规格不足的任务示例-Build a desktop knowledge base app with AI question answering.+构建一个带有 AI 问答功能的桌面知识库应用。-Constraints:+约束条件:-- None specified-- No startup command given-- No folder structure guidance-- No data model defined-- No explicit completion criteria+- 未指定任何约束+- 未给出启动命令+- 未提供文件夹结构指引+- 未定义数据模型+- 未明确完成标准-Typical outcomes from this kind of prompt:+这类提示的典型结果:-- the agent invents a structure ad hoc-- the app may compile but not start consistently-- the UI may appear before there is any usable ingest/query path-- the agent often stops after cosmetic success+- Agent 临时编造一个结构+- 应用可能编译通过但无法一致地启动+- UI 可能在没有任何可用的导入/查询路径之前就出现了+- Agent 通常在表面成功后就停止了diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.mdindex 8595b9b..149babc 100644--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md@@ -1,21 +1,21 @@-# Harness Components Example+# Harness 组件示例-For a coding agent working in a local repository:+对于在本地仓库中工作的编码 Agent:-- Model:- the LLM itself+- 模型:+ LLM 本身-- Harness:- - system prompt+- Harness:+ - 系统提示词- AGENTS.md- - bash tool- - file read/write tools- - git access- - local filesystem- - startup scripts- - test commands- - stop hooks- - lint checks- - evaluator loop+ - bash 工具+ - 文件读写工具+ - git 访问+ - 本地文件系统+ - 启动脚本+ - 测试命令+ - 停止钩子+ - 代码检查+ - 评估循环-If you change any of the above harness pieces, you change the effective agent.+如果你更改了上述任何一个 harness 组件,你就改变了实际运行的 Agent。diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/index.mdindex b16cfa3..fee7c4c 100644--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/index.md+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 02+# 第 02 讲代码-Use this folder for small examples that distinguish:+使用此文件夹存放小型示例,用于区分:-- model behavior-- harness behavior-- prompt-only setups-- environment-backed agent setups+- 模型行为+- harness 行为+- 纯提示词设置+- 有环境支撑的 Agent 设置diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdindex ead6a80..3792d33 100644--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md@@ -1,7 +1,7 @@-# Code for Lecture 03+# 第 03 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- agent-readable repo structures-- docs as system of record-- bad vs good knowledge placement+- Agent 可读的仓库结构+- 作为系统记录的文档+- 糟糕与良好的知识放置方式对比diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.mdindex e0856c5..7f37de5 100644--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md@@ -1,11 +1,11 @@-# System of Record Checklist+# 系统记录检查清单-Can a fresh agent discover the following from the repo alone?+一个全新的 Agent 能否仅从仓库中发现以下信息?-- What product is being built?-- What the app should do for users?-- How the codebase is organized?-- How the app starts?-- How health is checked?-- What work is currently in progress?-- What quality standards matter?+- 正在构建什么产品?+- 应用应该为用户做什么?+- 代码库是如何组织的?+- 应用如何启动?+- 如何检查健康状态?+- 当前正在进行什么工作?+- 哪些质量标准很重要?diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.mdindex cf0ae2d..53ca934 100644--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md@@ -1,15 +1,14 @@# AGENTS.md-## Start Here+## 从这里开始-- Read `docs/ARCHITECTURE.md`-- Read `docs/PRODUCT.md`-- Use `npm run dev` to start the app-- Use `npm run check` before marking work complete+- 阅读 `docs/ARCHITECTURE.md`+- 阅读 `docs/PRODUCT.md`+- 使用 `npm run dev` 启动应用+- 在标记工作完成之前使用 `npm run check`-## Hard Rules+## 严格规则-- Do not change Electron main/preload/renderer boundaries without reading- `docs/ARCHITECTURE.md`-- Do not mark a feature complete without verification-- Leave a clean state for the next session+- 在阅读 `docs/ARCHITECTURE.md` 之前,不要更改 Electron 主进程/预加载/渲染器的边界+- 未经验证不要将功能标记为已完成+- 为下一个会话留下干净的状态diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdindex 2fb84eb..5eec9f2 100644--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -1,7 +1,7 @@-# Instruction File Anti-Patterns+# 指令文件反模式-- Putting all repository knowledge into one file-- Repeating the same rule in multiple places-- Encoding obsolete rules that nobody audits-- Writing conditional instructions so specific that they rarely apply-- Embedding long tool manuals into the startup context+- 将所有仓库知识放入一个文件中+- 在多个地方重复同一条规则+- 编写从未被审查的过时规则+- 编写过于具体的条件指令,以至于很少适用+- 在启动上下文中嵌入冗长的工具手册diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdindex 756b500..3d4ce1b 100644--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md@@ -1,7 +1,7 @@-# Code for Lecture 04+# 第 04 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- monolithic instruction files-- short entrypoints-- progressive disclosure patterns+- 单体式指令文件+- 短小入口文件+- 渐进式信息披露模式diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.mdindex 6040ea6..41c345f 100644--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md@@ -1,6 +1,6 @@-# Continuity Checklist+# 连续性检查清单-- Can a fresh agent identify recent work in under five minutes?-- Is the current stable startup path documented?-- Is unfinished work clearly identified?-- Is the next best task visible without reading old chat logs?+- 一个全新的 Agent 能否在五分钟内识别最近的工作?+- 当前稳定的启动路径是否有文档记录?+- 未完成的工作是否被清楚标识?+- 下一个最佳任务是否在不阅读旧聊天记录的情况下可见?diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdindex 636e092..1707a8c 100644--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md@@ -1,7 +1,7 @@-# Code for Lecture 05+# 第 05 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- broken multi-session tasks-- missing continuity artifacts-- continuity recovery patterns+- 中断的多会话任务+- 缺失的连续性产物+- 连续性恢复模式diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdindex 09030a3..816aa75 100644--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -1,17 +1,17 @@-# Session Handoff Example+# 会话交接示例-## Completed+## 已完成-- Added markdown import support-- Added a basic document list in the renderer+- 添加了 markdown 导入支持+- 在渲染器中添加了基本的文档列表-## Broken or Unverified+## 有问题或未验证-- Import succeeds for `.md` but fails for large `.txt` files-- The app starts, but the detail view has not been wired up+- `.md` 导入成功,但大型 `.txt` 文件导入失败+- 应用可以启动,但详情视图尚未连接-## Next Best Step+## 下一步最佳操作-- Fix `.txt` import path-- Verify import end-to-end-- Then add the document detail panel+- 修复 `.txt` 导入路径+- 端到端验证导入功能+- 然后添加文档详情面板diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdindex fd65a7f..2cb65d8 100644--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 06+# 第 06 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- initializer outputs-- init scripts-- progress files-- first-run scaffolding+- 初始化器输出+- 初始化脚本+- 进度文件+- 首次运行脚手架diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.mdindex 58484c4..5fd4e49 100644--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md@@ -1,7 +1,7 @@-# Initializer Output Checklist+# 初始化器输出检查清单-- Is there a canonical startup command?-- Is there a canonical verification command?-- Is there a first progress artifact?-- Is there a stable first commit?-- Is there a visible feature surface for later runs?+- 是否有标准的启动命令?+- 是否有标准的验证命令?+- 是否有第一个进度产物?+- 是否有稳定的首次提交?+- 是否有供后续运行使用的可见功能面?diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdindex cfa201b..f681cdd 100644--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 07+# 第 07 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- one-shot failures-- oversized task prompts-- incremental task shaping-- structured feature surfaces+- 一次性失败+- 过大的任务提示+- 增量式任务塑造+- 结构化的功能面diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.mdindex b97cab0..cf6463e 100644--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md@@ -1,6 +1,6 @@-# Next Task Template+# 下一个任务模板-- Current highest-priority feature:-- Why this feature is next:-- What counts as passing:-- What must not be changed during this step:+- 当前最高优先级功能:+- 为什么这个功能是下一个:+- 什么算作通过:+- 在此步骤中不能更改什么:diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdindex 1f52484..a84b39e 100644--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -1,17 +1,17 @@-# Scope Surface Example+# 范围界定示例-Task:+任务:-- Add indexing to the Electron knowledge app+- 为 Electron 知识库应用添加索引功能-Bad scope shape:+糟糕的范围定义:-- “Implement indexing”+- "实现索引"-Better scope shape:+更好的范围定义:-- Parse imported documents-- Split documents into chunks-- Persist chunk metadata-- Expose indexing status in the UI-- Add a reindex action+- 解析导入的文档+- 将文档拆分为块+- 持久化块元数据+- 在 UI 中暴露索引状态+- 添加重新索引操作diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdindex ac4215f..19a2e67 100644--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 08+# 第 08 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- pass-state gating-- end-to-end verification-- weak vs strong completion criteria-- evaluator-loop examples+- 通过状态门控+- 端到端验证+- 弱与强的完成标准对比+- 评估循环示例diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdindex c922f64..54851a3 100644--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -1,8 +1,8 @@-# Pass Gate Policy+# 通过门控策略-A feature may only move from `passes: false` to `passes: true` when:+一个功能只有在满足以下条件时,才能从 `passes: false` 变为 `passes: true`:-- the expected workflow has been exercised-- the evidence of success is recorded-- no blocking error is present in the tested path-- the implementation does not leave the app in a broken or ambiguous state+- 预期的工作流已被执行+- 成功的证据已被记录+- 被测试的路径中不存在阻塞性错误+- 实现不会使应用处于损坏或模糊的状态diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.mdindex 5a592e3..58c022f 100644--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md@@ -1,6 +1,6 @@-# Clean State Checklist+# 干净状态检查清单-- App starts without manual repair-- Current progress is recorded-- No half-finished import or indexing step remains undocumented-- The next agent can run the standard startup and verification path immediately+- 应用无需手动修复即可启动+- 当前进度已记录+- 没有未记录的半完成导入或索引步骤+- 下一个 Agent 可以立即运行标准的启动和验证路径diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdindex e6ea6fc..4765109 100644--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 09+# 第 09 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- logs as feedback-- runtime-state visibility-- clean-state checks-- recovery examples+- 日志作为反馈+- 运行时状态可见性+- 干净状态检查+- 恢复示例diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.mdindex 6a6179b..85e0e48 100644--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md@@ -1,6 +1,6 @@-# Electron Architecture Rules+# Electron 架构规则-- Renderer code may not directly access the filesystem.-- Preload is the only bridge between renderer and Electron main.-- Retrieval and indexing logic live in service modules, not UI components.-- Logging should be structured and emitted from service boundaries.+- 渲染器代码不能直接访问文件系统。+- 预加载是渲染器与 Electron 主进程之间的唯一桥梁。+- 检索和索引逻辑位于服务模块中,而非 UI 组件中。+- 日志应该是结构化的,并从服务边界发出。diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdindex 8825e4e..448bdb7 100644--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 10+# 第 10 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- architecture constraints-- structural tests-- taste invariants-- remediation-oriented lint messages+- 架构约束+- 结构测试+- 品味不变量+- 以修复为导向的代码检查消息diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdindex f3cfd40..9d63b23 100644--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -1,10 +1,10 @@-# Example: Turning Review Feedback into a Rule+# 示例:将审查反馈转化为规则-Repeated review comment:+反复出现的审查意见:-> Do not call filesystem utilities from the renderer. Use the preload bridge.+> 不要从渲染器调用文件系统工具。使用预加载桥接。-Promoted harness rule:+提升为 harness 规则:-- add a lint or import rule preventing `fs` usage in renderer code-- add remediation text explaining the preload boundary+- 添加一个 lint 或 import 规则,阻止在渲染器代码中使用 `fs`+- 添加修复文本,解释预加载边界diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.mdindex 2c932d8..7373e26 100644--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md@@ -1,8 +1,8 @@-# Evaluator Rubric Example+# 评估者评分标准示例-Use 1-5 scoring for each dimension:+对每个维度使用 1-5 评分:-- Grounding: are answers clearly tied to imported sources?-- Citation quality: are the source references visible and specific?-- Functionality: can the user complete the question-answer flow?-- Product coherence: does the workflow feel integrated?+- 基础性:答案是否清晰关联到导入的来源?+- 引用质量:来源引用是否可见且具体?+- 功能性:用户能否完成问答流程?+- 产品一致性:工作流是否感觉一体化?diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdindex 5f094b9..5f66cd3 100644--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 11+# 第 11 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- planner outputs-- evaluator rubrics-- generator/evaluator loops-- single-agent vs multi-role comparisons+- 规划器输出+- 评估者评分标准+- 生成器/评估者循环+- 单 Agent 与多角色对比diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.mdindex bae2450..c3e4b4e 100644--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md@@ -1,12 +1,12 @@-# Sprint Contract Example+# Sprint 契约示例-Sprint goal:+Sprint 目标:-- Add visible citations to grounded Q&A results+- 为有据可依的问答结果添加可见引用-Done means:+完成意味着:-- User asks a question-- App returns an answer-- At least one citation is shown-- Clicking a citation opens the source location in the document view+- 用户提出一个问题+- 应用返回一个答案+- 显示至少一个引用+- 点击引用在文档视图中打开来源位置diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.mdindex 45d8a3d..d603f6f 100644--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md@@ -1,18 +1,18 @@-# Benchmark Comparison Template+# 基准对比模板-Harness A:+Harness A:-- completion rate-- average retries-- bugs caught before human review+- 完成率+- 平均重试次数+- 人工审查前捕获的缺陷-Harness B:+Harness B:-- completion rate-- average retries-- bugs caught before human review+- 完成率+- 平均重试次数+- 人工审查前捕获的缺陷-Interpretation:+解读:-- Which harness changed the result?-- Which harness changed the cost of getting the result?+- 哪个 harness 改变了结果?+- 哪个 harness 改变了获得结果的成本?diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdindex effd751..fe98d0a 100644--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -1,9 +1,9 @@-# Cleanup Loop Example+# 清理循环示例-Recurring cleanup tasks:+周期性清理任务:-- scan for stale docs-- scan for structural violations-- update quality grades-- open targeted cleanup PRs-- rerun a fixed benchmark slice after cleanup+- 扫描过期文档+- 扫描结构性违规+- 更新质量评级+- 创建针对性的清理 PR+- 清理后重新运行固定的基准切片diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdindex 29cf9f5..ad7c208 100644--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md@@ -1,8 +1,8 @@-# Code for Lecture 12+# 第 12 讲代码-Use this folder for examples of:+使用此文件夹存放以下方面的示例:-- benchmark slices-- cleanup tasks-- entropy reduction examples-- repeatable harness runs+- 基准切片+- 清理任务+- 熵减示例+- 可重复的 harness 运行diff --git a/skills/README-AR.md b/skills/README-AR.mdnew file mode 100644index 0000000..6afdc13--- /dev/null+++ b/skills/README-AR.md@@ -0,0 +1,56 @@+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>++# Skills++يحتوي هذا المجلد على skills قابلة لإعادة الاستخدام لوكلاء الذكاء الاصطناعي في مشروع Learn Harness Engineering. كل skill هي قالب prompt مستقل يمكن تحميله بواسطة وكلاء البرمجة مثل Claude Code وCodex وCursor وWindsurf.++## Skills المتاحة++### harness-creator++Skill لإنتاج harness engineering بجودة إنتاجية لوكلاء البرمجة. تساعد على إنشاء وتقييم وتحسين ملفات harness الخاصة بالوكيل، مثل AGENTS.md وقوائم الميزات وسير عمل التحقق وآليات استمرار الجلسة.++- **5 أنماط مرجعية**: Memory Persistence وContext Engineering وTool Registry وMulti-Agent Coordination وLifecycle & Bootstrap+- **قوالب**: AGENTS.md وfeature-list.json وinit.sh وprogress.md+- **5 حالات eval مدمجة**+- **ثنائية اللغة**: English + 中文++راجع التوثيق الكامل في [harness-creator/README.md](harness-creator/README.md).++## كيف تم بناء harness-creator++تم تطوير `harness-creator` باستخدام منهجية **skill-creator**، وهي meta-skill رسمية من Anthropic لإنشاء skills للوكلاء واختبارها وتحسينها عبر مسار draft → test → evaluate → iterate.++## كيف تعمل Skills++تتبع كل skill بنية قياسية:++1. **SKILL.md** — نقطة الدخول، وتتضمن YAML frontmatter وتعليمات Markdown للوكيل.+2. **references/** — مستندات إضافية يتم تحميلها عند الحاجة.+3. **templates/** — قوالب بداية يمكن أن تولدها skill.++تستخدم skills أسلوب progressive disclosure: يرى الوكيل الاسم والوصف أولا، ثم يحمّل SKILL.md عند التفعيل، ويقرأ الموارد المرفقة فقط عند الحاجة.++## الأمان++تمت مراجعة ملفات هذا المجلد أمنيا:++- لا توجد backdoors أو URL مخفية أو payloads مشفرة+- لا يوجد تسريب بيانات أو بيانات اعتماد hardcoded+- لا توجد ثغرات command injection+- `init.sh` يشغل فقط أوامر npm lifecycle القياسية++## الرخصة++MITdiff --git a/skills/README-CN.md b/skills/README-CN.mdindex 3a8c0c4..b6a9ee0 100644--- a/skills/README-CN.md+++ b/skills/README-CN.md@@ -1,6 +1,17 @@-# Skills(技能集)+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>-[English](./README.md) · [한국어](./README-KO.md)+# Skills(技能集)本目录包含 Learn Harness Engineering 项目的可复用 AI agent 技能。每个技能都是一个自包含的提示词模板,可被 AI 编程智能体(Claude Code、Codex、Cursor、Windsurf 等)加载以执行专业任务。@@ -30,6 +41,13 @@skills/├── README.md # 英文说明├── README-CN.md # 中文说明(本文件)+├── README-ZH-TW.md # 繁体中文说明+├── README-JA.md # 日文说明+├── README-ES.md # 西班牙文说明+├── README-FR.md # 法文说明+├── README-AR.md # 阿拉伯文说明+├── README-VI.md # 越南文说明+├── README-DE.md # 德文说明└── harness-creator/ # Harness 工程技能├── SKILL.md # 主技能定义(双语)├── SKILL.md.en # 英文版diff --git a/skills/README-DE.md b/skills/README-DE.mdnew file mode 100644index 0000000..ea488f9--- /dev/null+++ b/skills/README-DE.md@@ -0,0 +1,56 @@+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>++# Skills++Dieses Verzeichnis enthält wiederverwendbare AI agent skills für das Projekt Learn Harness Engineering. Jeder skill ist eine eigenständige Prompt-Vorlage, die von Coding Agents wie Claude Code, Codex, Cursor oder Windsurf geladen werden kann.++## Verfügbare Skills++### harness-creator++Production-orientierter Harness-Engineering-Skill für AI coding agents. Er hilft beim Erstellen, Bewerten und Verbessern von Agent-Harness-Dateien wie AGENTS.md, Feature-Listen, Verification Workflows und Mechanismen für Session Continuity.++- **5 Referenzmuster**: Memory Persistence, Context Engineering, Tool Registry, Multi-Agent Coordination, Lifecycle & Bootstrap+- **Templates**: AGENTS.md, feature-list.json, init.sh, progress.md+- **5 integrierte Eval-Testfälle**+- **Zweisprachig**: English + 中文++Siehe [harness-creator/README.md](harness-creator/README.md) für die vollständige Dokumentation.++## Wie harness-creator erstellt wurde++`harness-creator` wurde mit der **skill-creator**-Methodik entwickelt, Anthropic's offiziellem meta-skill zum Erstellen, Testen und Iterieren von Agent Skills im Ablauf draft → test → evaluate → iterate.++## Wie Skills funktionieren++Jeder skill folgt einer Standardstruktur:++1. **SKILL.md** — Einstiegspunkt mit YAML frontmatter und Markdown-Anweisungen für den Agent.+2. **references/** — Zusätzliche Dokumentation, die bei Bedarf in den Kontext geladen wird.+3. **templates/** — Startvorlagen, die der skill erzeugen kann.++Skills verwenden progressive disclosure: Der Agent sieht zunächst nur Name und Beschreibung, lädt bei Auslösung die vollständige SKILL.md und liest gebündelte Ressourcen nur bei Bedarf.++## Sicherheit++Alle Dateien in diesem Verzeichnis wurden geprüft:++- Keine Backdoors, versteckten URLs oder codierten Payloads+- Keine Datenexfiltration oder hardcodierten Zugangsdaten+- Keine Command-Injection-Schwachstellen+- `init.sh` führt nur Standardbefehle aus dem npm lifecycle aus++## Lizenz++MITdiff --git a/skills/README-ES.md b/skills/README-ES.mdnew file mode 100644index 0000000..2adde3c--- /dev/null+++ b/skills/README-ES.md@@ -0,0 +1,56 @@+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>++# Skills++Este directorio contiene skills reutilizables para agentes de IA en el proyecto Learn Harness Engineering. Cada skill es una plantilla de prompt autocontenida que puede ser cargada por agentes de programación como Claude Code, Codex, Cursor o Windsurf.++## Skills disponibles++### harness-creator++Skill de harness engineering de nivel producción para agentes de programación. Ayuda a crear, evaluar y mejorar archivos de harness para agentes, como AGENTS.md, listas de funciones, flujos de verificación y mecanismos de continuidad entre sesiones.++- **5 patrones de referencia**: Memory Persistence, Context Engineering, Tool Registry, Multi-Agent Coordination, Lifecycle & Bootstrap+- **Plantillas**: AGENTS.md, feature-list.json, init.sh, progress.md+- **5 casos de eval integrados**+- **Bilingüe**: English + 中文++Consulta la documentación completa en [harness-creator/README.md](harness-creator/README.md).++## Cómo se creó harness-creator++`harness-creator` se desarrolló con la metodología **skill-creator**, el meta-skill oficial de Anthropic para crear, probar e iterar skills de agentes mediante un flujo draft → test → evaluate → iterate.++## Cómo funcionan las skills++Cada skill sigue una estructura estándar:++1. **SKILL.md** — Punto de entrada con YAML frontmatter e instrucciones Markdown para el agente.+2. **references/** — Documentos adicionales que se cargan bajo demanda.+3. **templates/** — Plantillas iniciales que la skill puede generar.++Las skills usan progressive disclosure: el agente primero ve solo el nombre y la descripción, luego carga SKILL.md cuando se activa y lee recursos incluidos solo cuando son necesarios.++## Seguridad++Los archivos de este directorio fueron revisados:++- Sin backdoors, URL ocultas ni payloads codificados+- Sin exfiltración de datos ni credenciales hardcodeadas+- Sin vulnerabilidades de command injection+- `init.sh` solo ejecuta comandos estándar del ciclo de vida de npm++## Licencia++MITdiff --git a/skills/README-FR.md b/skills/README-FR.mdnew file mode 100644index 0000000..32d86ad--- /dev/null+++ b/skills/README-FR.md@@ -0,0 +1,56 @@+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>++# Skills++Ce dossier contient des skills réutilisables pour agents IA dans le projet Learn Harness Engineering. Chaque skill est un modèle de prompt autonome pouvant être chargé par des agents de codage comme Claude Code, Codex, Cursor ou Windsurf.++## Skills disponibles++### harness-creator++Skill de harness engineering de niveau production pour agents de codage IA. Elle aide à créer, évaluer et améliorer les fichiers de harness d'agent, notamment AGENTS.md, les listes de fonctionnalités, les workflows de vérification et les mécanismes de continuité de session.++- **5 modèles de référence** : Memory Persistence, Context Engineering, Tool Registry, Multi-Agent Coordination, Lifecycle & Bootstrap+- **Templates** : AGENTS.md, feature-list.json, init.sh, progress.md+- **5 cas de test eval intégrés**+- **Bilingue** : English + 中文++Voir la documentation complète : [harness-creator/README.md](harness-creator/README.md).++## Création de harness-creator++`harness-creator` a été développé avec la méthodologie **skill-creator**, le meta-skill officiel d'Anthropic pour créer, tester et itérer des skills d'agents avec un flux draft → test → evaluate → iterate.++## Fonctionnement des skills++Chaque skill suit une structure standard :++1. **SKILL.md** — Point d'entrée avec YAML frontmatter et instructions Markdown pour l'agent.+2. **references/** — Documentation supplémentaire chargée au besoin.+3. **templates/** — Templates de départ que la skill peut générer.++Les skills utilisent le progressive disclosure : l'agent voit d'abord seulement le nom et la description, puis charge SKILL.md au déclenchement, et lit les ressources incluses uniquement si nécessaire.++## Sécurité++Les fichiers de ce dossier ont été audités :++- Aucun backdoor, URL cachée ou payload encodé+- Aucune exfiltration de données ni identifiants codés en dur+- Aucune vulnérabilité de command injection+- `init.sh` exécute uniquement des commandes npm lifecycle standard++## Licence++MITdiff --git a/skills/README-JA.md b/skills/README-JA.mdnew file mode 100644index 0000000..6e4d4ae--- /dev/null+++ b/skills/README-JA.md@@ -0,0 +1,56 @@+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>++# Skills++このディレクトリには、Learn Harness Engineering プロジェクトで再利用できる AI agent skills が含まれています。各 skill は自己完結したプロンプトテンプレートで、Claude Code、Codex、Cursor、Windsurf などの AI コーディング agent が専門的な作業を行うために読み込めます。++## 利用可能な Skills++### harness-creator++AI コーディング agent 向けの本番品質 harness engineering skill です。AGENTS.md、機能リスト、検証ワークフロー、セッション継続メカニズムなどの agent harness ファイルの作成、評価、改善を支援します。++- **5 つの参照パターン**:Memory Persistence、Context Engineering、Tool Registry、Multi-Agent Coordination、Lifecycle & Bootstrap+- **テンプレート**:AGENTS.md、feature-list.json、init.sh、progress.md+- **5 つの組み込み eval テストケース**+- **バイリンガル**:English + 中文++詳細は [harness-creator/README.md](harness-creator/README.md) を参照してください。++## harness-creator の作成方法++`harness-creator` は **skill-creator** 方法論で作られました。これは Anthropic の公式 meta-skill で、agent skills を draft → test → evaluate → iterate の流れで作成、テスト、改善するためのものです。++## Skills の仕組み++各 skill は標準構造に従います。++1. **SKILL.md** — エントリーポイント。YAML frontmatter と agent への Markdown 指示を含みます。+2. **references/** — 必要に応じてコンテキストに読み込む追加ドキュメント。+3. **templates/** — skill が生成できる開始テンプレート。++Skills は progressive disclosure を使います。agent は最初に名前と説明だけを見て、トリガーされたときに SKILL.md 全体を読み込み、必要な場合だけ同梱リソースを読みます。++## セキュリティ++このディレクトリのファイルはセキュリティ確認済みです。++- バックドア、隠し URL、エンコードされた payload はありません+- データ流出やハードコードされた認証情報はありません+- コマンドインジェクション脆弱性はありません+- `init.sh` は標準 npm lifecycle コマンドのみを実行します++## ライセンス++MITdiff --git a/skills/README-KO.md b/skills/README-KO.mdindex 83da4bf..46b3f54 100644--- a/skills/README-KO.md+++ b/skills/README-KO.md@@ -1,4 +1,15 @@-[English](./README.md) · [中文版](./README-CN.md) · **한국어**+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p># 스킬(Skills)@@ -35,6 +46,13 @@ skills/├── README.md # 영어 버전 (이 파일의 원본)├── README-CN.md # 중국어 버전├── README-KO.md # 한국어 버전 (이 파일)+├── README-ZH-TW.md # 번체 중국어 버전+├── README-JA.md # 일본어 버전+├── README-ES.md # 스페인어 버전+├── README-FR.md # 프랑스어 버전+├── README-AR.md # 아랍어 버전+├── README-VI.md # 베트남어 버전+├── README-DE.md # 독일어 버전└── harness-creator/ # 하네스 엔지니어링 스킬├── SKILL.md # 주요 스킬 정의 (이중 언어)├── SKILL.md.en # 영어 전용 버전diff --git a/skills/README-VI.md b/skills/README-VI.mdnew file mode 100644index 0000000..fad7fe9--- /dev/null+++ b/skills/README-VI.md@@ -0,0 +1,56 @@+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>++# Skills++Thu muc nay chua cac AI agent skills co the tai su dung cho du an Learn Harness Engineering. Moi skill la mot prompt template doc lap, co the duoc nap boi cac AI coding agent nhu Claude Code, Codex, Cursor va Windsurf.++## Skills hien co++### harness-creator++Skill harness engineering cap production cho AI coding agents. Skill nay giup tao, danh gia va cai thien cac file harness cua agent, gom AGENTS.md, danh sach tinh nang, verification workflows va co che tiep noi phien lam viec.++- **5 mau tham chieu**: Memory Persistence, Context Engineering, Tool Registry, Multi-Agent Coordination, Lifecycle & Bootstrap+- **Templates**: AGENTS.md, feature-list.json, init.sh, progress.md+- **5 eval test case tich hop**+- **Song ngu**: English + 中文++Xem tai lieu day du tai [harness-creator/README.md](harness-creator/README.md).++## Cach harness-creator duoc tao++`harness-creator` duoc phat trien bang phuong phap **skill-creator**, meta-skill chinh thuc cua Anthropic de tao, kiem thu va lap lai viec cai thien agent skills theo luong draft → test → evaluate → iterate.++## Skills hoat dong nhu the nao++Moi skill co cau truc chuan:++1. **SKILL.md** — Diem vao, gom YAML frontmatter va huong dan Markdown cho agent.+2. **references/** — Tai lieu bo sung duoc nap vao context khi can.+3. **templates/** — Template khoi dau ma skill co the tao.++Skills dung progressive disclosure: agent ban dau chi thay ten va mo ta, sau do nap SKILL.md khi duoc kich hoat va chi doc tai nguyen kem theo khi can thiet.++## Bao mat++Tat ca file trong thu muc nay da duoc kiem tra bao mat:++- Khong co backdoor, URL an hoac payload duoc ma hoa+- Khong ro ri du lieu hoac credential hardcoded+- Khong co lo hong command injection+- `init.sh` chi chay cac lenh npm lifecycle tieu chuan++## Giay phep++MITdiff --git a/skills/README-ZH-TW.md b/skills/README-ZH-TW.mdnew file mode 100644index 0000000..a0c069a--- /dev/null+++ b/skills/README-ZH-TW.md@@ -0,0 +1,56 @@+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>++# Skills(技能集)++本目錄包含 Learn Harness Engineering 專案的可重用 AI agent 技能。每個技能都是自包含的提示範本,可由 Claude Code、Codex、Cursor、Windsurf 等 AI 編程 agent 載入,以執行特定任務。++## 可用技能++### harness-creator++面向 AI 編程 agent 的生產級 harness engineering 技能。它協助建立、評估與改進 agent harness 檔案,例如 AGENTS.md、功能清單、驗證工作流與跨會話延續機制。++- **5 個參考模式**:記憶持久化、上下文工程、工具註冊、多 agent 協調、生命週期與啟動+- **範本**:AGENTS.md、feature-list.json、init.sh、progress.md+- **5 個內建 eval 測試案例**+- **雙語支援**:English + 中文++完整文件請見 [harness-creator/README.md](harness-creator/README.md)。++## harness-creator 的建立方式++`harness-creator` 使用 **skill-creator** 方法論建立。這是 Anthropic 用於建立、測試與迭代 agent skills 的官方 meta-skill,提供 draft → test → evaluate → iterate 的結構化流程。++## 技能如何運作++每個技能遵循標準結構:++1. **SKILL.md** — 入口檔案,包含 YAML frontmatter 與給 agent 的 Markdown 指令。+2. **references/** — 需要時載入上下文的補充文件。+3. **templates/** — 技能可產生的起始範本。++技能採用 progressive disclosure:agent 一開始只看到名稱與描述,觸發後才載入完整 SKILL.md,並只在必要時讀取附帶資源。++## 安全審計++本目錄中的檔案已完成安全檢查:++- 無後門、隱藏 URL 或編碼 payload+- 無資料外洩或硬編碼憑證+- 無命令注入漏洞+- `init.sh` 僅執行標準 npm lifecycle 命令++## 授權++MITdiff --git a/skills/README.md b/skills/README.mdindex 9b424c5..efba19c 100644--- a/skills/README.md+++ b/skills/README.md@@ -1,6 +1,17 @@-# Skills+<p align="center">+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>-[中文版](./README-CN.md) · [한국어](./README-KO.md)+# SkillsThis directory contains reusable AI agent skills for the Learn Harness Engineering project. Each skill is a self-contained prompt template that can be loaded by AI coding agents (Claude Code, Codex, Cursor, Windsurf, etc.) to perform specialized tasks.@@ -30,6 +41,13 @@ The `harness-creator` skill was developed using the **skill-creator** methodologskills/├── README.md # This file├── README-CN.md # Chinese version+├── README-ZH-TW.md # Traditional Chinese version+├── README-JA.md # Japanese version+├── README-ES.md # Spanish version+├── README-FR.md # French version+├── README-AR.md # Arabic version+├── README-VI.md # Vietnamese version+├── README-DE.md # German version└── harness-creator/ # Harness engineering skill├── SKILL.md # Main skill definition (bilingual)├── SKILL.md.en # English-only versiondiff --git a/skills/harness-creator/README.md b/skills/harness-creator/README.mdindex 505d7b6..3d195b5 100644--- a/skills/harness-creator/README.md+++ b/skills/harness-creator/README.md@@ -1,3 +1,16 @@+<p align="center">+ <a href="../README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>+ <a href="../README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>+ <a href="../README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>+ <a href="../README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>+ <a href="../README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>+ <a href="../README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>+ <a href="../README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>+ <a href="../README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>+ <a href="../README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>+ <a href="../README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>+</p>+# harness-creator SkillProduction harness engineering skill for AI coding agents, distilled from Learn Harness Engineering course and industry best practices.