Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
Fix docs routes and restore dead-link checks
sanbuphyb6fcf3849d6d
diff --git a/README-CN.md b/README-CN.mdindex 80f532c..d8fc8cf 100644--- a/README-CN.md+++ b/README-CN.md@@ -69,43 +69,43 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它- [`clean-state-checklist.md`](./docs/resources/zh/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单- [`evaluator-rubric.md`](./docs/resources/zh/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表-每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/README.md)。英文版见 [English template guide](./docs/resources/en/templates/README.md)。+每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/index.md)。英文版见 [English template guide](./docs/resources/en/templates/index.md)。如果你想直接用 OpenAI 那篇 harness engineering 文章里的更完整高级结构,可以继续看-[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/README.md)-和 [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/README.md)。+[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md)+和 [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md)。## 课程大纲### 讲义-- [Lecture 01. 模型能力强,不等于执行可靠](./lectures/lecture-01-why-capable-agents-still-fail/README.md)-- [Lecture 02. Harness 的定义](./lectures/lecture-02-what-a-harness-actually-is/README.md)-- [Lecture 03. 让代码仓库成为唯一的事实来源](./lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md)-- [Lecture 04. 把指令拆分到不同文件里](./lectures/lecture-04-why-one-giant-instruction-file-fails/README.md)-- [Lecture 05. 让跨会话的任务保持上下文连续](./lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md)-- [Lecture 06. 让 agent 每次工作前先初始化](./lectures/lecture-06-why-initialization-needs-its-own-phase/README.md)-- [Lecture 07. 给 agent 划清每次任务的边界](./lectures/lecture-07-why-agents-overreach-and-under-finish/README.md)-- [Lecture 08. 用功能清单约束 agent 该做什么](./lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md)-- [Lecture 09. 防止 agent 提前宣告完成](./lectures/lecture-09-why-agents-declare-victory-too-early/README.md)-- [Lecture 10. 跑通完整流程才算真正验证](./lectures/lecture-10-why-end-to-end-testing-changes-results/README.md)-- [Lecture 11. 让 agent 的运行过程可观测](./lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md)-- [Lecture 12. 每次会话结束前都做好交接](./lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md)+- [Lecture 01. 模型能力强,不等于执行可靠](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)+- [Lecture 02. Harness 的定义](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md)+- [Lecture 03. 让代码仓库成为唯一的事实来源](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)+- [Lecture 04. 把指令拆分到不同文件里](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+- [Lecture 05. 让跨会话的任务保持上下文连续](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)+- [Lecture 06. 让 agent 每次工作前先初始化](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+- [Lecture 07. 给 agent 划清每次任务的边界](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)+- [Lecture 08. 用功能清单约束 agent 该做什么](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+- [Lecture 09. 防止 agent 提前宣告完成](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)+- [Lecture 10. 跑通完整流程才算真正验证](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+- [Lecture 11. 让 agent 的运行过程可观测](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)+- [Lecture 12. 每次会话结束前都做好交接](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)### 项目-- [Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少](./projects/project-01-baseline-vs-minimal-harness/README.md)-- [Project 02. 让 agent 看懂项目、接住上次的工作](./projects/project-02-agent-readable-workspace/README.md)-- [Project 03. 让 agent 关掉再打开还能接着干](./projects/project-03-multi-session-continuity/README.md)-- [Project 04. 用运行反馈修正 agent 的行为](./projects/project-04-incremental-indexing/README.md)-- [Project 05. 让 agent 自己检查自己做的对不对](./projects/project-05-grounded-qa-verification/README.md)-- [Project 06. 搭建一套完整的 agent 工作环境](./projects/project-06-runtime-observability-and-debugging/README.md)+- [Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少](./docs/projects/project-01-baseline-vs-minimal-harness/index.md)+- [Project 02. 让 agent 看懂项目、接住上次的工作](./docs/projects/project-02-agent-readable-workspace/index.md)+- [Project 03. 让 agent 关掉再打开还能接着干](./docs/projects/project-03-multi-session-continuity/index.md)+- [Project 04. 用运行反馈修正 agent 的行为](./docs/projects/project-04-incremental-indexing/index.md)+- [Project 05. 让 agent 自己检查自己做的对不对](./docs/projects/project-05-grounded-qa-verification/index.md)+- [Project 06. 搭建一套完整的 agent 工作环境](./docs/projects/project-06-runtime-observability-and-debugging/index.md)### 资料库-- [Resource Library 总览](./docs/resources/README.md)-- [中文资料库](./docs/resources/zh/README.md)-- [English Resource Library](./docs/resources/en/README.md)+- [Resource Library 总览](./docs/resources/index.md)+- [中文资料库](./docs/resources/zh/index.md)+- [English Resource Library](./docs/resources/en/index.md)## 学习路径推荐@@ -243,8 +243,8 @@ npm run docs:dev## 仓库结构-- `lectures/` - 全部讲义-- `projects/` - 全部实践项目,包括 capstone+- `docs/lectures/` - 全部讲义+- `docs/projects/` - 全部实践项目,包括 capstone- `docs/resources/` - 中英双语的可复用模板、检查清单和方法参考每个 lecture 都带一个 `code/` 目录,用来放小型真实示例和 supporting artifacts。diff --git a/README.md b/README.mdindex 9232a49..cbafdaf 100644--- a/README.md+++ b/README.md@@ -69,44 +69,44 @@ When your project gets more complex, add these:- [`clean-state-checklist.md`](./docs/resources/en/templates/clean-state-checklist.md) — checklist to run before ending each session- [`evaluator-rubric.md`](./docs/resources/en/templates/evaluator-rubric.md) — scorecard for reviewing agent output quality-Each file has detailed usage instructions in the [English template guide](./docs/resources/en/templates/README.md). Chinese versions are available in [中文模板指南](./docs/resources/zh/templates/README.md).+Each file has detailed usage instructions in the [English template guide](./docs/resources/en/templates/index.md). Chinese versions are available in [中文模板指南](./docs/resources/zh/templates/index.md).If you want the fuller OpenAI-style repository layout from the"Harness engineering" post, use the advanced pack in-[`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/README.md) or-[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/README.md).+[`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md) or+[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md).## Syllabus### Lectures-- [Lecture 01. Strong models don't mean reliable execution](./lectures/lecture-01-why-capable-agents-still-fail/README.md)-- [Lecture 02. What harness actually means](./lectures/lecture-02-what-a-harness-actually-is/README.md)-- [Lecture 03. Make the repository your single source of truth](./lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md)-- [Lecture 04. Split instructions across files, not one giant file](./lectures/lecture-04-why-one-giant-instruction-file-fails/README.md)-- [Lecture 05. Keep context alive across sessions](./lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md)-- [Lecture 06. Initialize before every agent session](./lectures/lecture-06-why-initialization-needs-its-own-phase/README.md)-- [Lecture 07. Draw clear task boundaries for agents](./lectures/lecture-07-why-agents-overreach-and-under-finish/README.md)-- [Lecture 08. Use feature lists to constrain what the agent does](./lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md)-- [Lecture 09. Stop agents from declaring victory early](./lectures/lecture-09-why-agents-declare-victory-too-early/README.md)-- [Lecture 10. Only a full-pipeline run counts as real verification](./lectures/lecture-10-why-end-to-end-testing-changes-results/README.md)-- [Lecture 11. Make the agent's runtime observable](./lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md)-- [Lecture 12. Clean handoff at the end of every session](./lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md)+- [Lecture 01. Strong models don't mean reliable execution](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)+- [Lecture 02. What harness actually means](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md)+- [Lecture 03. Make the repository your single source of truth](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)+- [Lecture 04. Split instructions across files, not one giant file](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)+- [Lecture 05. Keep context alive across sessions](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)+- [Lecture 06. Initialize before every agent session](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+- [Lecture 07. Draw clear task boundaries for agents](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)+- [Lecture 08. Use feature lists to constrain what the agent does](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)+- [Lecture 09. Stop agents from declaring victory early](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)+- [Lecture 10. Only a full-pipeline run counts as real verification](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)+- [Lecture 11. Make the agent's runtime observable](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)+- [Lecture 12. Clean handoff at the end of every session](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)### Projects-- [Project 01. Prompt-only vs. rules-first: how much difference does it make](./projects/project-01-baseline-vs-minimal-harness/README.md)-- [Project 02. Make the project readable and pick up where you left off](./projects/project-02-agent-readable-workspace/README.md)-- [Project 03. Keep the agent working across session restarts](./projects/project-03-multi-session-continuity/README.md)-- [Project 04. Use runtime feedback to correct agent behavior](./projects/project-04-incremental-indexing/README.md)-- [Project 05. Make the agent verify its own work](./projects/project-05-grounded-qa-verification/README.md)-- [Project 06. Build a complete agent harness](./projects/project-06-runtime-observability-and-debugging/README.md)+- [Project 01. Prompt-only vs. rules-first: how much difference does it make](./docs/projects/project-01-baseline-vs-minimal-harness/index.md)+- [Project 02. Make the project readable and pick up where you left off](./docs/projects/project-02-agent-readable-workspace/index.md)+- [Project 03. Keep the agent working across session restarts](./docs/projects/project-03-multi-session-continuity/index.md)+- [Project 04. Use runtime feedback to correct agent behavior](./docs/projects/project-04-incremental-indexing/index.md)+- [Project 05. Make the agent verify its own work](./docs/projects/project-05-grounded-qa-verification/index.md)+- [Project 06. Build a complete agent harness](./docs/projects/project-06-runtime-observability-and-debugging/index.md)### Resource Library-- [Resource Library Overview](./docs/resources/README.md)-- [Chinese Resource Library](./docs/resources/zh/README.md)-- [English Resource Library](./docs/resources/en/README.md)+- [Resource Library Overview](./docs/resources/index.md)+- [Chinese Resource Library](./docs/resources/zh/index.md)+- [English Resource Library](./docs/resources/en/index.md)## Recommended Learning Path@@ -244,8 +244,8 @@ The final project also serves as the course's capstone harness.## Repository Structure-- `lectures/` - All lectures-- `projects/` - All hands-on projects, including the capstone+- `docs/lectures/` - All lectures+- `docs/projects/` - All hands-on projects, including the capstone- `docs/resources/` - Bilingual reusable templates, checklists, and method referencesEach lecture includes a `code/` directory for small real-world examples and supporting artifacts.diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex a9faa30..526a253 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -78,7 +78,7 @@ export default defineConfig({"A project-based course on designing the environments, state, verification, and control systems that make Codex and Claude Code reliable.",cleanUrls: true,srcExclude: ["temp/**"],- ignoreDeadLinks: true,+ ignoreDeadLinks: false,locales: {root: {label: "简体中文",diff --git a/docs/en/resources.md b/docs/en/resources.mdindex 3e3ac85..32cba47 100644--- a/docs/en/resources.md+++ b/docs/en/resources.md@@ -1,10 +1,10 @@# Resource Library-This page is the English entry point for reusable templates, checklists, and method notes.+This page is the English overview for the bilingual resource library.-Chinese is the default site language. The Chinese resource overview is available at [/resources/](../resources/).+Chinese is the default site language. The Chinese resource overview is available at [/resources/](/resources/).-## English Resources+## English Resource Library- [English Resource Library](/resources/en/)- [English Templates](/resources/en/templates/)diff --git a/docs/lectures/lecture-01-why-capable-agents-still-fail/code/README.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-01-why-capable-agents-still-fail/code/README.mdrename to docs/lectures/lecture-01-why-capable-agents-still-fail/code/index.mddiff --git a/docs/lectures/lecture-01-why-capable-agents-still-fail/README.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/index.mdsimilarity index 97%rename from docs/lectures/lecture-01-why-capable-agents-still-fail/README.mdrename to docs/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 4ac4dce..7253367 100644--- a/docs/lectures/lecture-01-why-capable-agents-still-fail/README.md+++ b/docs/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -54,7 +54,7 @@ instrumentation and diagnosis, followed by targeted harness changes.- Startup and health-check command list.- Required verification command set.- Session handoff notes in the repository.-- Code examples for this lecture: [`code/README.md`](./code/README.md)+- Code examples for this lecture: [`code/index.md`](./code/index.md)## Readingsdiff --git a/docs/lectures/lecture-02-what-a-harness-actually-is/code/README.md b/docs/lectures/lecture-02-what-a-harness-actually-is/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-02-what-a-harness-actually-is/code/README.mdrename to docs/lectures/lecture-02-what-a-harness-actually-is/code/index.mddiff --git a/docs/lectures/lecture-02-what-a-harness-actually-is/README.md b/docs/lectures/lecture-02-what-a-harness-actually-is/index.mdsimilarity index 97%rename from docs/lectures/lecture-02-what-a-harness-actually-is/README.mdrename to docs/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 0efc9c6..028b7d6 100644--- a/docs/lectures/lecture-02-what-a-harness-actually-is/README.md+++ b/docs/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -47,7 +47,7 @@ surfaces vary. Performance changes are often harness effects, not model changes.- Remove a component and ask whether agent access, action, state continuity, orerror recovery changed.- If behavior changes materially, the removed component is harness-critical.-- Lecture examples: [`code/README.md`](./code/README.md)+- Lecture examples: [`code/index.md`](./code/index.md)- Typical artifacts to audit:- `AGENTS.md` or equivalent instruction entrypoint.- Setup and verification scripts.diff --git a/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/README.md b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/README.mdrename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.mddiff --git a/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdsimilarity index 97%rename from docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.mdrename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 71094c0..2c7f913 100644--- a/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md+++ b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -49,7 +49,7 @@ minimal, durable, high-utility context for repeatable work.- Validation check:- Start a new agent session and ask it to explain the system and next tasksusing repository contents only.-- Lecture examples: [`code/README.md`](./code/README.md)+- Lecture examples: [`code/index.md`](./code/index.md)## Readingsdiff --git a/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.mdrename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.mddiff --git a/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdsimilarity index 98%rename from docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.mdrename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 47be325..e55c522 100644--- a/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md+++ b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -51,7 +51,7 @@ moving specialized detail to targeted references.- Repeated edge-case rules with no source links.- Contradictory instructions across one large file.- Large sections with unclear ownership and update cadence.-- Lecture examples: [`code/README.md`](./code/README.md)+- Lecture examples: [`code/index.md`](./code/index.md)## Readingsdiff --git a/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.mdrename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.mddiff --git a/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdsimilarity index 98%rename from docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.mdrename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdindex 17a9004..5780bbd 100644--- a/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md+++ b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -68,7 +68,7 @@ work.## Examples and Artifacts-- See [`code/`](./code/README.md) for continuity failure and recovery examples.+- See [`code/`](./code/index.md) for continuity failure and recovery examples.- Typical continuity artifacts include a progress log, a feature-status file, aclean commit checkpoint, and a short verification record from the latest run.- A useful handoff artifact states repository status, runtime status, blockers,diff --git a/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.md b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.mdrename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.mddiff --git a/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdsimilarity index 97%rename from docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.mdrename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdindex 26db732..4d7beb0 100644--- a/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md+++ b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -46,7 +46,7 @@ instead of implicit assumptions?## Examples and Artifacts-- See [`code/`](./code/README.md) for initializer output and first-run+- See [`code/`](./code/index.md) for initializer output and first-runscaffolding examples.- Common initialization artifacts include `init.sh`, a baseline commit, aprogress artifact, and a structured feature/task surface.diff --git a/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.mdrename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.mddiff --git a/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdsimilarity index 97%rename from docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.mdrename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdindex a7d8f5a..5ceb451 100644--- a/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md+++ b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -46,7 +46,7 @@ durable, testable behavior.## Examples and Artifacts-- See [`code/`](./code/README.md) for one-shot failure patterns and incremental+- See [`code/`](./code/index.md) for one-shot failure patterns and incrementaltask-shaping examples.- Useful artifacts include a structured feature/task list with explicit statusvalues and a single active-item policy.diff --git a/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.md b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.mdrename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mddiff --git a/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdsimilarity index 97%rename from docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.mdrename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdindex 5c344ad..b954e78 100644--- a/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md+++ b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -47,7 +47,7 @@ criteria.## Examples and Artifacts-- See [`code/`](./code/README.md) for pass-state gating and evaluator-loop+- See [`code/`](./code/index.md) for pass-state gating and evaluator-loopexamples.- A useful feature record includes identifier, behavior statement, verificationmethod, status, and evidence reference.diff --git a/docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/README.md b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/README.mdrename to docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mddiff --git a/docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.md b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdsimilarity index 97%rename from docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.mdrename to docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdindex d994fe9..87a7104 100644--- a/docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.md+++ b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -45,7 +45,7 @@ exit criteria before completion can be accepted.and completion signals.- [`code/clean-state-checklist.md`](./code/clean-state-checklist.md): session-exitcriteria for restartable state.-- [`code/README.md`](./code/README.md): index of lecture artifacts.+- [`code/index.md`](./code/index.md): index of lecture artifacts.## Readingsdiff --git a/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/README.md b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/README.mdrename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mddiff --git a/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdsimilarity index 98%rename from docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.mdrename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdindex d09d23f..8d13888 100644--- a/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md+++ b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -58,7 +58,7 @@ feedback loops — the agent sees the error and immediately knows the fix.that should be testable and enforceable.- [`code/review-feedback-to-rule.md`](./code/review-feedback-to-rule.md): exampleof converting recurring review feedback into automation.-- [`code/README.md`](./code/README.md): index of lecture artifacts.+- [`code/index.md`](./code/index.md): index of lecture artifacts.## Readingsdiff --git a/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.mdrename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.mddiff --git a/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdsimilarity index 98%rename from docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.mdrename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdindex 479c35c..186613d 100644--- a/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md+++ b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -71,7 +71,7 @@ explicit, pre-agreed standard.completion criteria for a bounded upgrade.- [`code/evaluator-rubric.md`](./code/evaluator-rubric.md): scoring framework forgrounded quality assessment.-- [`code/README.md`](./code/README.md): index of lecture artifacts.+- [`code/index.md`](./code/index.md): index of lecture artifacts.## Readingsdiff --git a/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/README.md b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mdsimilarity index 100%rename from docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/README.mdrename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.mddiff --git a/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdsimilarity index 98%rename from docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.mdrename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdindex dc51096..19f9381 100644--- a/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md+++ b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -115,7 +115,7 @@ Operationally, clean state and measurement reinforce each other:template for comparing harness variants.- [`code/cleanup-loop.md`](./code/cleanup-loop.md): recurring maintenance cyclefor entropy reduction.-- [`code/README.md`](./code/README.md): index of lecture artifacts.+- [`code/index.md`](./code/index.md): index of lecture artifacts.## Readingsdiff --git a/docs/projects/project-01-baseline-vs-minimal-harness/README.md b/docs/projects/project-01-baseline-vs-minimal-harness/index.mdsimilarity index 100%rename from docs/projects/project-01-baseline-vs-minimal-harness/README.mdrename to docs/projects/project-01-baseline-vs-minimal-harness/index.mddiff --git a/docs/projects/project-02-agent-readable-workspace/README.md b/docs/projects/project-02-agent-readable-workspace/index.mdsimilarity index 100%rename from docs/projects/project-02-agent-readable-workspace/README.mdrename to docs/projects/project-02-agent-readable-workspace/index.mddiff --git a/docs/projects/project-03-multi-session-continuity/README.md b/docs/projects/project-03-multi-session-continuity/index.mdsimilarity index 100%rename from docs/projects/project-03-multi-session-continuity/README.mdrename to docs/projects/project-03-multi-session-continuity/index.mddiff --git a/docs/projects/project-04-incremental-indexing/README.md b/docs/projects/project-04-incremental-indexing/index.mdsimilarity index 100%rename from docs/projects/project-04-incremental-indexing/README.mdrename to docs/projects/project-04-incremental-indexing/index.mddiff --git a/docs/projects/project-05-grounded-qa-verification/README.md b/docs/projects/project-05-grounded-qa-verification/index.mdsimilarity index 100%rename from docs/projects/project-05-grounded-qa-verification/README.mdrename to docs/projects/project-05-grounded-qa-verification/index.mddiff --git a/docs/projects/project-06-runtime-observability-and-debugging/README.md b/docs/projects/project-06-runtime-observability-and-debugging/index.mdsimilarity index 100%rename from docs/projects/project-06-runtime-observability-and-debugging/README.mdrename to docs/projects/project-06-runtime-observability-and-debugging/index.mddiff --git a/docs/resources/en/README.md b/docs/resources/en/index.mdsimilarity index 82%rename from docs/resources/en/README.mdrename to docs/resources/en/index.mdindex 4f413a7..4fb8aa4 100644--- a/docs/resources/en/README.md+++ b/docs/resources/en/index.md@@ -34,13 +34,13 @@ Then add:If you want the fuller OpenAI-style repository structure from the"Harness engineering" post, use the advanced pack:-- [`openai-advanced/README.md`](./openai-advanced/README.md)+- [`openai-advanced/index.md`](./openai-advanced/index.md)## Library Structure-- [`templates/`](./templates/README.md): templates to copy into a real repo-- [`reference/`](./reference/README.md): method notes, startup flow, and failure-mode maps-- [`openai-advanced/`](./openai-advanced/README.md): advanced repo skeleton,+- [`templates/`](./templates/index.md): templates to copy into a real repo+- [`reference/`](./reference/index.md): method notes, startup flow, and failure-mode maps+- [`openai-advanced/`](./openai-advanced/index.md): advanced repo skeleton,system-of-record docs, and agent-first governance templates## Recommended Minimal Pack@@ -54,5 +54,5 @@ Those four files are enough to make most agent workflows noticeably more stable.When the repo grows into a longer-running system with multiple domains, activeplans, quality scoring, and reliability policies, move up to the-[`openai-advanced/`](./openai-advanced/README.md) pack instead of stretching the+[`openai-advanced/`](./openai-advanced/index.md) pack instead of stretching theminimal pack too far.diff --git a/docs/resources/en/openai-advanced/README.md b/docs/resources/en/openai-advanced/index.mdsimilarity index 91%rename from docs/resources/en/openai-advanced/README.mdrename to docs/resources/en/openai-advanced/index.mdindex 6f47556..c89b786 100644--- a/docs/resources/en/openai-advanced/README.md+++ b/docs/resources/en/openai-advanced/index.md@@ -17,7 +17,7 @@ now needs:## Included Starter Layout-The starter pack under [`repo-template/`](./repo-template/README.md) mirrors the+The starter pack under [`repo-template/`](./repo-template/index.md) mirrors thestructure below:```text@@ -52,7 +52,7 @@ docs/## How To Adopt It1. Start from the minimal pack if your repo is still small.-2. Copy the files in [`repo-template/`](./repo-template/README.md) into your+2. Copy the files in [`repo-template/`](./repo-template/index.md) into yourown repository once you need stronger structure.3. Keep `AGENTS.md` short. Treat it as a router into the deeper docs, not as anencyclopedia.@@ -63,7 +63,7 @@ docs/## SOP Library-The [`sops/`](./sops/README.md) folder turns the article's diagrams into+The [`sops/`](./sops/index.md) folder turns the article's diagrams intostep-by-step operating procedures:- layered domain architecture setupdiff --git a/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/README.md b/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/index.mdsimilarity index 100%rename from docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/README.mdrename to docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/index.mddiff --git a/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/README.md b/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/index.mdsimilarity index 100%rename from docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/README.mdrename to docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/index.mddiff --git a/docs/resources/en/openai-advanced/repo-template/README.md b/docs/resources/en/openai-advanced/repo-template/index.mdsimilarity index 100%rename from docs/resources/en/openai-advanced/repo-template/README.mdrename to docs/resources/en/openai-advanced/repo-template/index.mddiff --git a/docs/resources/en/openai-advanced/sops/README.md b/docs/resources/en/openai-advanced/sops/index.mdsimilarity index 100%rename from docs/resources/en/openai-advanced/sops/README.mdrename to docs/resources/en/openai-advanced/sops/index.mddiff --git a/docs/resources/en/reference/README.md b/docs/resources/en/reference/index.mdsimilarity index 100%rename from docs/resources/en/reference/README.mdrename to docs/resources/en/reference/index.mddiff --git a/docs/resources/en/templates/README.md b/docs/resources/en/templates/index.mdsimilarity index 100%rename from docs/resources/en/templates/README.mdrename to docs/resources/en/templates/index.mddiff --git a/docs/resources/README.md b/docs/resources/index.mdsimilarity index 66%rename from docs/resources/README.mdrename to docs/resources/index.mdindex 8369913..9a4d223 100644--- a/docs/resources/README.md+++ b/docs/resources/index.md@@ -6,15 +6,15 @@## 先看中文-- [中文资料库总览](./zh/README.md)-- [中文模板](./zh/templates/README.md)-- [中文参考](./zh/reference/README.md)+- [中文资料库总览](./zh/index.md)+- [中文模板](./zh/templates/index.md)+- [中文参考](./zh/reference/index.md)## English Resources-- [English Resource Library](./en/README.md)-- [English Templates](./en/templates/README.md)-- [English Reference](./en/reference/README.md)+- [English Resource Library](./en/index.md)+- [English Templates](./en/templates/index.md)+- [English Reference](./en/reference/index.md)## 这里能找到什么@@ -38,5 +38,5 @@如果最小 harness 已经不够,可以继续看 OpenAI 风格的 advanced pack:-- 中文:[`zh/openai-advanced/README.md`](./zh/openai-advanced/README.md)-- English:[`en/openai-advanced/README.md`](./en/openai-advanced/README.md)+- 中文:[`zh/openai-advanced/index.md`](./zh/openai-advanced/index.md)+- English:[`en/openai-advanced/index.md`](./en/openai-advanced/index.md)diff --git a/docs/resources/zh/README.md b/docs/resources/zh/index.mdsimilarity index 76%rename from docs/resources/zh/README.mdrename to docs/resources/zh/index.mdindex 10536b5..63a26b7 100644--- a/docs/resources/zh/README.md+++ b/docs/resources/zh/index.md@@ -31,13 +31,13 @@如果你想直接采用 OpenAI 那篇 harness engineering 文章里更完整的仓库组织方式,可以继续看:-- [`openai-advanced/README.md`](./openai-advanced/README.md)+- [`openai-advanced/index.md`](./openai-advanced/index.md)## 资料库结构-- [`templates/`](./templates/README.md):可以直接复制到真实仓库里的模板-- [`reference/`](./reference/README.md):方法说明、启动流程和问题对照表-- [`openai-advanced/`](./openai-advanced/README.md):更完整的 OpenAI 风格高级资源包,包括 repo skeleton、质量文档、执行计划和系统级治理文件+- [`templates/`](./templates/index.md):可以直接复制到真实仓库里的模板+- [`reference/`](./reference/index.md):方法说明、启动流程和问题对照表+- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 风格高级资源包,包括 repo skeleton、质量文档、执行计划和系统级治理文件## 推荐最小组合@@ -49,4 +49,4 @@先把这四样放进项目里,再开始让 agent 持续工作,通常就已经能明显降低返工和瞎猜。如果你的仓库已经进入多模块、多阶段、多角色协作,可以直接升级到-[`openai-advanced/`](./openai-advanced/README.md) 这一套高级结构,而不是继续把最小模板硬撑成一个大而乱的系统。+[`openai-advanced/`](./openai-advanced/index.md) 这一套高级结构,而不是继续把最小模板硬撑成一个大而乱的系统。diff --git a/docs/resources/zh/openai-advanced/README.md b/docs/resources/zh/openai-advanced/index.mdsimilarity index 89%rename from docs/resources/zh/openai-advanced/README.mdrename to docs/resources/zh/openai-advanced/index.mdindex 2d4c75a..63a588e 100644--- a/docs/resources/zh/openai-advanced/README.md+++ b/docs/resources/zh/openai-advanced/index.md@@ -15,7 +15,7 @@ agent-first world》里更完整、更高阶的仓库组织方式整理成可以## 包含的目录骨架-[`repo-template/`](./repo-template/README.md) 里提供了一套可直接复制的 starter+[`repo-template/`](./repo-template/index.md) 里提供了一套可直接复制的 starter结构,核心布局如下:```text@@ -51,14 +51,14 @@ docs/1. 如果仓库还小,先用最小资源包。2. 一旦进入多模块、多轮会话、长期演化阶段,就把- [`repo-template/`](./repo-template/README.md) 里的骨架复制到你的仓库。+ [`repo-template/`](./repo-template/index.md) 里的骨架复制到你的仓库。3. 保持 `AGENTS.md` 很短,把深层规则拆到 `docs/` 里。4. 把质量文档、可靠性文档、执行计划当成日常开发的一部分,而不是事后补写。5. 把生成物和外部 reference 明确收进仓库,避免 agent 依赖聊天上下文或人的记忆。## SOP 资料库-[`sops/`](./sops/README.md) 把文章里的几张关键图,整理成可以逐步执行的标准流程:+[`sops/`](./sops/index.md) 把文章里的几张关键图,整理成可以逐步执行的标准流程:- 分层领域架构搭建 SOP- 把不可见知识编码进仓库的 SOPdiff --git a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/README.md b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.mdsimilarity index 100%rename from docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/README.mdrename to docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.mddiff --git a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/README.md b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.mdsimilarity index 100%rename from docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/README.mdrename to docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.mddiff --git a/docs/resources/zh/openai-advanced/repo-template/README.md b/docs/resources/zh/openai-advanced/repo-template/index.mdsimilarity index 100%rename from docs/resources/zh/openai-advanced/repo-template/README.mdrename to docs/resources/zh/openai-advanced/repo-template/index.mddiff --git a/docs/resources/zh/openai-advanced/sops/README.md b/docs/resources/zh/openai-advanced/sops/index.mdsimilarity index 100%rename from docs/resources/zh/openai-advanced/sops/README.mdrename to docs/resources/zh/openai-advanced/sops/index.mddiff --git a/docs/resources/zh/reference/README.md b/docs/resources/zh/reference/index.mdsimilarity index 100%rename from docs/resources/zh/reference/README.mdrename to docs/resources/zh/reference/index.mddiff --git a/docs/resources/zh/templates/README.md b/docs/resources/zh/templates/index.mdsimilarity index 100%rename from docs/resources/zh/templates/README.mdrename to docs/resources/zh/templates/index.md