Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
docs: add sources or mark illustrative for Real-World examples (#73) (#75)
PerryLinkec4ee30d4e88
diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 3dbf811..666d87e 100644--- a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -98,7 +98,9 @@ This analogy comes from database transaction management. You might feel like thi- **Isolation**: When multiple agents work concurrently, design state files to avoid race conditions. Simple approach: each agent uses its own progress file, or use git branches for isolation. Concurrent writes to the same file are a common source of trouble.- **Durability**: Critical project knowledge lives in git-tracked files. Temporary state can stay in session memory, but knowledge that must survive across sessions has to be written to files. What's in your head doesn't count — only what's written down counts.-## A Real Transformation Story+## Illustrative Example++> This example is a teaching illustration, not a published case study — the numbers are illustrative rather than measured from a real project.A team maintained an e-commerce platform with roughly 30 microservices. Architecture decisions — inter-service communication protocols, data consistency strategies, API versioning rules — were scattered across: Confluence (partially outdated), Slack (hard to search), a few senior engineers' heads (not scalable), and sporadic code comments (not systematic).diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 99950b1..c572549 100644--- a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -93,7 +93,9 @@ If an instruction absolutely must be in the entry file, put it at the top or botBoth OpenAI and Anthropic implicitly endorse this split approach. OpenAI says entry files should be "short and routing-oriented," while Anthropic says control information for long-running agents should be "concise and high-priority." Both are saying the same thing: don't stuff everything into a single file.-## Real-World Example+## Illustrative Example++> This example is a teaching illustration, not a published case study — the numbers are illustrative rather than measured from a real project.A SaaS team's `AGENTS.md` ballooned from 50 lines to 600. The contents mixed together tech stack versions, coding standards, historical bug fix notes, API usage guides, deployment procedures, and team members' personal preferences — everything was in there, but finding the part relevant to the current task was a slog.diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdindex 81cd57c..5309941 100644--- a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -143,7 +143,9 @@ Anthropic's actual data: for Sonnet 4.5, context anxiety is severe enough that c> Source: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)-## Real-World Example+## Illustrative Example++> This example is a teaching illustration, not a published case study — the numbers are illustrative rather than measured from a real project.An agent was tasked with implementing a blog system with user authentication — 12 feature points, estimated 5 sessions needed.diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex bb26751..2248551 100644--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -98,7 +98,9 @@ project/- **隔离性**:多个 agent 并发工作时,状态文件要避免竞争条件。简单方案:每个 agent 用独立的进度文件,或者用 git 分支隔离。并发写入同一文件是出问题的常见原因。- **持久性**:关键的项目知识用 git 跟踪的文件持久化。临时状态可以只在会话内存里,但跨会话必须的知识必须写到文件里。脑子里的不算,写在纸上的才算。-## 一个真实的改造故事+## 示意性示例++> 本示例为教学示意,并非已发表的真实案例——文中数字仅为让概念更具体,并非来自真实项目的实测数据。一个团队维护一个包含约 30 个微服务的电商平台。架构决策(服务间通信协议、数据一致性策略、API 版本化规则)散落在:Confluence(部分过时)、Slack(难以搜索)、几个资深工程师的脑子里(不可扩展)、以及零星的代码注释(不系统)。diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 8a1722f..e37833f 100644--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -93,7 +93,9 @@ Python 3.11 FastAPI 后端,PostgreSQL 15 数据库。OpenAI 和 Anthropic 都隐性支持拆分的做法。OpenAI 说入口文件应"短小且以路由为导向",Anthropic 说长运行 agent 的控制信息应"简洁且高优先级"。两家都在说同一件事:别把什么都塞进一个文件里。-## 实际案例+## 示意性示例++> 本示例为教学示意,并非已发表的真实案例——文中数字仅为让概念更具体,并非来自真实项目的实测数据。一个 SaaS 团队的 `AGENTS.md` 从最初的 50 行膨胀到 600 行。内容混合了技术栈版本、编码规范、历史 bug 修复笔记、API 使用说明、部署流程、和团队成员的个人偏好,什么都有,但很难快速找到跟当前任务相关的部分。diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdindex b5487bf..7fdfdad 100644--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -143,7 +143,9 @@ Anthropic 的实际数据:对于 Sonnet 4.5,上下文焦虑足够严重,> 来源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)-## 实际案例+## 示意性示例++> 本示例为教学示意,并非已发表的真实案例——文中数字仅为让概念更具体,并非来自真实项目的实测数据。一个 agent 被要求实现一个带用户认证的博客系统,12 个功能点,预计需要 5 个会话。