Skip to content

Harness engineering beginner tutorial, from 0 to 1

Migrate docs into docs/ and consolidate resources

sanbuphy6f8ffe2d577c
diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
index 9e4e346..5a14dd9 100644
--- a/.github/workflows/deploy-pages.yml
+++ b/.github/workflows/deploy-pages.yml
@@ -44,7 +44,7 @@ jobs:
- name: Upload artifact
uses: actions/upload-pages-artifact@v4
with:
- path: .vitepress/dist
+ path: docs/.vitepress/dist
deploy:
name: Deploy
diff --git a/.gitignore b/.gitignore
index db8d207..411d47e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,28 @@
temp/
node_modules/
+coverage/
+
+# macOS / editor noise
+.DS_Store
+*.swp
+*.swo
+*~
+
+# local env files
+.env
+.env.local
+.env.*.local
+
+# logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# build caches / outputs
.vitepress/cache/
.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+*.tsbuildinfo
diff --git a/.vitepress/config.mts b/.vitepress/config.mts
deleted file mode 100644
index c5dccfc..0000000
--- a/.vitepress/config.mts
+++ /dev/null
@@ -1,75 +0,0 @@
-import { defineConfig } from "vitepress";
-
-const docsBase = process.env.DOCS_BASE_PATH ?? "/";
-
-const lectureItems = [
- { text: "Lecture 01", link: "/lectures/lecture-01-why-capable-agents-still-fail/" },
- { text: "Lecture 02", link: "/lectures/lecture-02-what-a-harness-actually-is/" },
- { text: "Lecture 03", link: "/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
- { text: "Lecture 04", link: "/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
- { text: "Lecture 05", link: "/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
- { text: "Lecture 06", link: "/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
- { text: "Lecture 07", link: "/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
- { text: "Lecture 08", link: "/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
- { text: "Lecture 09", link: "/lectures/lecture-09-why-agents-declare-victory-too-early/" },
- { text: "Lecture 10", link: "/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
- { text: "Lecture 11", link: "/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
- { text: "Lecture 12", link: "/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }
-];
-
-const projectItems = [
- { text: "Project 01", link: "/projects/project-01-baseline-vs-minimal-harness/" },
- { text: "Project 02", link: "/projects/project-02-agent-readable-workspace/" },
- { text: "Project 03", link: "/projects/project-03-multi-session-continuity/" },
- { text: "Project 04", link: "/projects/project-04-incremental-indexing/" },
- { text: "Project 05", link: "/projects/project-05-grounded-qa-verification/" },
- { text: "Project 06", link: "/projects/project-06-runtime-observability-and-debugging/" }
-];
-
-const resourceItems = [
- { text: "Overview", link: "/resources/" },
- { text: "中文总览", link: "/resources/zh/" },
- { text: "中文模板", link: "/resources/zh/templates/" },
- { text: "中文参考", link: "/resources/zh/reference/" },
- { text: "English Overview", link: "/resources/en/" },
- { text: "English Templates", link: "/resources/en/templates/" },
- { text: "English Reference", link: "/resources/en/reference/" }
-];
-
-export default defineConfig({
- base: docsBase,
- title: "Learn Harness Engineering",
- description:
- "A project-based course on designing the environments, state, verification, and control systems that make Codex and Claude Code reliable.",
- cleanUrls: true,
- srcExclude: ["temp/**"],
- themeConfig: {
- nav: [
- { text: "Course Home", link: "/" },
- { text: "Lectures", link: lectureItems[0].link },
- { text: "Projects", link: projectItems[0].link },
- { text: "Library", link: resourceItems[0].link }
- ],
- search: {
- provider: "local"
- },
- sidebar: [
- {
- text: "Lectures",
- items: lectureItems
- },
- {
- text: "Projects",
- items: projectItems
- },
- {
- text: "Resource Library",
- items: resourceItems
- }
- ],
- outline: {
- level: [2, 3]
- },
- socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]
- }
-});
diff --git a/README-CN.md b/README-CN.md
index 8a88061..80f532c 100644
--- a/README-CN.md
+++ b/README-CN.md
@@ -43,33 +43,33 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
**第一步.** 把根指令文件复制到项目根目录:
-- [`AGENTS.md`](./resources/zh/templates/AGENTS.md) 通用版,或者 [`CLAUDE.md`](./resources/zh/templates/CLAUDE.md) 如果你用 Claude Code
+- [`AGENTS.md`](./docs/resources/zh/templates/AGENTS.md) 通用版,或者 [`CLAUDE.md`](./docs/resources/zh/templates/CLAUDE.md) 如果你用 Claude Code
- 把里面的命令、路径和规则换成你自己项目的
**第二步.** 把启动脚本复制进去:
-- `resources/zh/templates/init.sh` —— 一条命令完成依赖安装、验证和启动
+- `docs/resources/zh/templates/init.sh` —— 一条命令完成依赖安装、验证和启动
- 把 `INSTALL_CMD`、`VERIFY_CMD`、`START_CMD` 换成你自己的
**第三步.** 把进度日志复制进去:
-- [`claude-progress.md`](./resources/zh/templates/claude-progress.md) —— 每轮会话记录做了什么、验证了什么、下一步是什么
+- [`claude-progress.md`](./docs/resources/zh/templates/claude-progress.md) —— 每轮会话记录做了什么、验证了什么、下一步是什么
- agent 每次开工会先读这个文件,从上次停下的地方继续
**第四步.** 把功能清单复制进去:
-- [`feature_list.json`](./resources/zh/templates/feature_list.json) —— 机器可读的功能列表,每个功能有状态、验证步骤和证据
+- [`feature_list.json`](./docs/resources/zh/templates/feature_list.json) —— 机器可读的功能列表,每个功能有状态、验证步骤和证据
- 把示例功能换成你自己的
四个文件,最小起步就够了。比光靠一段提示词稳定得多。
等项目变复杂了,再补这些:
-- [`session-handoff.md`](./resources/zh/templates/session-handoff.md) —— 会话之间的交接摘要
-- [`clean-state-checklist.md`](./resources/zh/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单
-- [`evaluator-rubric.md`](./resources/zh/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表
+- [`session-handoff.md`](./docs/resources/zh/templates/session-handoff.md) —— 会话之间的交接摘要
+- [`clean-state-checklist.md`](./docs/resources/zh/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单
+- [`evaluator-rubric.md`](./docs/resources/zh/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表
-每个文件的详细用法写在 [中文模板指南](./resources/zh/templates/README.md)。英文版见 [English template guide](./resources/en/templates/README.md)。
+每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/README.md)。英文版见 [English template guide](./docs/resources/en/templates/README.md)。
如果你想直接用 OpenAI 那篇 harness engineering 文章里的更完整高级结构,可以继续看
[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/README.md)
@@ -103,9 +103,9 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
### 资料库
-- [Resource Library 总览](./resources/README.md)
-- [中文资料库](./resources/zh/README.md)
-- [English Resource Library](./resources/en/README.md)
+- [Resource Library 总览](./docs/resources/README.md)
+- [中文资料库](./docs/resources/zh/README.md)
+- [English Resource Library](./docs/resources/en/README.md)
## 学习路径推荐
@@ -245,6 +245,6 @@ npm run docs:dev
- `lectures/` - 全部讲义
- `projects/` - 全部实践项目,包括 capstone
-- `resources/` - 中英双语的可复用模板、检查清单和方法参考
+- `docs/resources/` - 中英双语的可复用模板、检查清单和方法参考
每个 lecture 都带一个 `code/` 目录,用来放小型真实示例和 supporting artifacts。
diff --git a/README.md b/README.md
index 437ad33..9232a49 100644
--- a/README.md
+++ b/README.md
@@ -43,33 +43,33 @@ The idea is simple: instead of just writing prompts, give your agent a set of st
**Step 1.** Copy the root instruction file into your project root:
-- [`AGENTS.md`](./resources/en/templates/AGENTS.md) for most agents, or [`CLAUDE.md`](./resources/en/templates/CLAUDE.md) if you're using Claude Code
+- [`AGENTS.md`](./docs/resources/en/templates/AGENTS.md) for most agents, or [`CLAUDE.md`](./docs/resources/en/templates/CLAUDE.md) if you're using Claude Code
- Edit the commands, paths, and rules to match your project
**Step 2.** Copy the startup script:
-- `resources/en/templates/init.sh` — runs dependency install, verification, and startup in one shot
+- `docs/resources/en/templates/init.sh` — runs dependency install, verification, and startup in one shot
- Replace the `INSTALL_CMD`, `VERIFY_CMD`, and `START_CMD` with your actual commands
**Step 3.** Copy the progress log:
-- [`claude-progress.md`](./resources/en/templates/claude-progress.md) — records what was done each session, what's verified, and what's next
+- [`claude-progress.md`](./docs/resources/en/templates/claude-progress.md) — records what was done each session, what's verified, and what's next
- The agent reads this at the start of every session to pick up where it left off
**Step 4.** Copy the feature list:
-- [`feature_list.json`](./resources/en/templates/feature_list.json) — a machine-readable list of features with status, verification steps, and evidence
+- [`feature_list.json`](./docs/resources/en/templates/feature_list.json) — a machine-readable list of features with status, verification steps, and evidence
- Replace the example features with your own
That's it for the minimum setup. Four files, and your agent sessions will already be more stable than running on prompts alone.
When your project gets more complex, add these:
-- [`session-handoff.md`](./resources/en/templates/session-handoff.md) — compact handoff note between sessions
-- [`clean-state-checklist.md`](./resources/en/templates/clean-state-checklist.md) — checklist to run before ending each session
-- [`evaluator-rubric.md`](./resources/en/templates/evaluator-rubric.md) — scorecard for reviewing agent output quality
+- [`session-handoff.md`](./docs/resources/en/templates/session-handoff.md) — compact handoff note between sessions
+- [`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](./resources/en/templates/README.md). Chinese versions are available in [中文模板指南](./resources/zh/templates/README.md).
+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).
If you want the fuller OpenAI-style repository layout from the
"Harness engineering" post, use the advanced pack in
@@ -104,9 +104,9 @@ If you want the fuller OpenAI-style repository layout from the
### Resource Library
-- [Resource Library Overview](./resources/README.md)
-- [Chinese Resource Library](./resources/zh/README.md)
-- [English Resource Library](./resources/en/README.md)
+- [Resource Library Overview](./docs/resources/README.md)
+- [Chinese Resource Library](./docs/resources/zh/README.md)
+- [English Resource Library](./docs/resources/en/README.md)
## Recommended Learning Path
@@ -246,6 +246,6 @@ The final project also serves as the course's capstone harness.
- `lectures/` - All lectures
- `projects/` - All hands-on projects, including the capstone
-- `resources/` - Bilingual reusable templates, checklists, and method references
+- `docs/resources/` - Bilingual reusable templates, checklists, and method references
Each lecture includes a `code/` directory for small real-world examples and supporting artifacts.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
new file mode 100644
index 0000000..a9faa30
--- /dev/null
+++ b/docs/.vitepress/config.mts
@@ -0,0 +1,171 @@
+import { defineConfig } from "vitepress";
+
+const docsBase = process.env.DOCS_BASE_PATH ?? "/";
+
+const lectureItems = [
+ { text: "Lecture 01", link: "/lectures/lecture-01-why-capable-agents-still-fail/" },
+ { text: "Lecture 02", link: "/lectures/lecture-02-what-a-harness-actually-is/" },
+ { text: "Lecture 03", link: "/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
+ { text: "Lecture 04", link: "/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
+ { text: "Lecture 05", link: "/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
+ { text: "Lecture 06", link: "/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
+ { text: "Lecture 07", link: "/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
+ { text: "Lecture 08", link: "/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
+ { text: "Lecture 09", link: "/lectures/lecture-09-why-agents-declare-victory-too-early/" },
+ { text: "Lecture 10", link: "/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
+ { text: "Lecture 11", link: "/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
+ { text: "Lecture 12", link: "/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }
+];
+
+const zhLectureItems = [
+ { text: "Lecture 01. 为什么强模型依然会失败", link: "/lectures/lecture-01-why-capable-agents-still-fail/" },
+ { text: "Lecture 02. 什么才算 harness", link: "/lectures/lecture-02-what-a-harness-actually-is/" },
+ { text: "Lecture 03. 为什么仓库必须成为 system of record", link: "/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
+ { text: "Lecture 04. 为什么一个巨大的 instruction 文件会失败", link: "/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
+ { text: "Lecture 05. 为什么长时任务会失去连续性", link: "/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
+ { text: "Lecture 06. 为什么初始化必须是独立阶段", link: "/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
+ { text: "Lecture 07. 为什么 scope 必须被显式化", link: "/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
+ { text: "Lecture 08. 为什么验证必须外部化", link: "/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
+ { text: "Lecture 09. 为什么 runtime feedback 必须进入 harness", link: "/lectures/lecture-09-why-agents-declare-victory-too-early/" },
+ { text: "Lecture 10. 为什么完整验证才算真的验证", link: "/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
+ { text: "Lecture 11. 为什么可观测性必须进入 harness", link: "/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
+ { text: "Lecture 12. 为什么每次会话都必须干净收尾", link: "/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }
+];
+
+const projectItems = [
+ { text: "Project 01", link: "/projects/project-01-baseline-vs-minimal-harness/" },
+ { text: "Project 02", link: "/projects/project-02-agent-readable-workspace/" },
+ { text: "Project 03", link: "/projects/project-03-multi-session-continuity/" },
+ { text: "Project 04", link: "/projects/project-04-incremental-indexing/" },
+ { text: "Project 05", link: "/projects/project-05-grounded-qa-verification/" },
+ { text: "Project 06", link: "/projects/project-06-runtime-observability-and-debugging/" }
+];
+
+const zhProjectItems = [
+ { text: "Project 01. 基线 vs 最小 harness", link: "/projects/project-01-baseline-vs-minimal-harness/" },
+ { text: "Project 02. Agent-readable workspace 与 continuity scaffold", link: "/projects/project-02-agent-readable-workspace/" },
+ { text: "Project 03. Scope control 与 grounded verification", link: "/projects/project-03-multi-session-continuity/" },
+ { text: "Project 04. Runtime feedback 与 structural control", link: "/projects/project-04-incremental-indexing/" },
+ { text: "Project 05. Evaluator loop 与三角色升级", link: "/projects/project-05-grounded-qa-verification/" },
+ { text: "Project 06. Benchmark、cleanup 与 capstone harness", link: "/projects/project-06-runtime-observability-and-debugging/" }
+];
+
+const zhResourceItems = [
+ { text: "资料库总览", link: "/resources/" },
+ { text: "中文资料库", link: "/resources/zh/" },
+ { text: "中文模板", link: "/resources/zh/templates/" },
+ { text: "中文参考", link: "/resources/zh/reference/" },
+ { text: "English Resource Library", link: "/resources/en/" },
+ { text: "English Templates", link: "/resources/en/templates/" },
+ { text: "English Reference", link: "/resources/en/reference/" }
+];
+
+const enResourceItems = [
+ { text: "Overview", link: "/en/resources" },
+ { text: "中文总览", link: "/resources/zh/" },
+ { text: "English Overview", link: "/resources/en/" },
+ { text: "English Templates", link: "/resources/en/templates/" },
+ { text: "English Reference", link: "/resources/en/reference/" },
+ { text: "中文资料库", link: "/resources/" },
+ { text: "中文模板", link: "/resources/zh/templates/" },
+ { text: "中文参考", link: "/resources/zh/reference/" }
+];
+
+export default defineConfig({
+ base: docsBase,
+ title: "Learn Harness Engineering",
+ description:
+ "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,
+ locales: {
+ root: {
+ label: "简体中文",
+ lang: "zh-CN"
+ },
+ en: {
+ label: "English",
+ lang: "en",
+ link: "/en/",
+ themeConfig: {
+ nav: [
+ { text: "Home", link: "/en/" },
+ { text: "Lectures", link: lectureItems[0].link },
+ { text: "Projects", link: projectItems[0].link },
+ { text: "Library", link: "/en/resources" }
+ ],
+ sidebar: [
+ {
+ text: "Lectures",
+ items: lectureItems
+ },
+ {
+ text: "Projects",
+ items: projectItems
+ },
+ {
+ text: "Resource Library",
+ items: enResourceItems
+ }
+ ],
+ outline: {
+ level: [2, 3]
+ },
+ docFooter: {
+ prev: "Previous page",
+ next: "Next page"
+ },
+ lastUpdated: {
+ text: "Last updated"
+ },
+ returnToTopLabel: "Return to top",
+ sidebarMenuLabel: "Menu",
+ darkModeSwitchLabel: "Appearance",
+ lightModeSwitchTitle: "Switch to light theme",
+ darkModeSwitchTitle: "Switch to dark theme"
+ }
+ }
+ },
+ themeConfig: {
+ nav: [
+ { text: "首页", link: "/" },
+ { text: "讲义", link: zhLectureItems[0].link },
+ { text: "项目", link: zhProjectItems[0].link },
+ { text: "资料库", link: "/resources/" }
+ ],
+ search: {
+ provider: "local"
+ },
+ sidebar: [
+ {
+ text: "讲义",
+ items: zhLectureItems
+ },
+ {
+ text: "项目",
+ items: zhProjectItems
+ },
+ {
+ text: "资料库",
+ items: zhResourceItems
+ }
+ ],
+ outline: {
+ level: [2, 3]
+ },
+ docFooter: {
+ prev: "上一篇",
+ next: "下一篇"
+ },
+ lastUpdated: {
+ text: "最后更新于"
+ },
+ returnToTopLabel: "回到顶部",
+ sidebarMenuLabel: "菜单",
+ darkModeSwitchLabel: "主题",
+ lightModeSwitchTitle: "切换到浅色模式",
+ darkModeSwitchTitle: "切换到深色模式",
+ socialLinks: [{ icon: "github", link: "https://github.com/walkinglabs/learn-harness-engineering" }]
+ }
+});
diff --git a/docs/en/index.md b/docs/en/index.md
new file mode 100644
index 0000000..680e270
--- /dev/null
+++ b/docs/en/index.md
@@ -0,0 +1,68 @@
+# Learn Harness Engineering
+
+> A project-based course on building the environment, state management, verification, and control mechanisms that make Codex and Claude Code work more reliably.
+
+This course is a work in progress. Content may change as it evolves.
+
+Chinese is now the default site language. The Chinese homepage is available at [/](../).
+
+## Overview
+
+Harness engineering is about building a complete working environment around the model so it produces reliable results. It's not just about writing prompts. It also covers:
+
+- Where code lives and how it's organized
+- What the agent is and isn't allowed to do
+- How to track task progress and pick up where you left off
+- How to verify that work was done correctly
+- How to diagnose problems when they arise
+- What rules must always be followed
+- How to leave things clean after each session
+
+This course is **hands-on**. We won't stop at concepts. You'll have Codex or Claude Code work repeatedly on the same evolving Electron application, comparing weak harnesses against strong ones.
+
+The questions this course actually cares about:
+
+- Which harness designs improve task completion rates?
+- Which designs reduce rework and incorrect completions?
+- Which mechanisms keep long-running tasks progressing steadily?
+- Which structures keep the system maintainable after multiple agent runs?
+
+## Core Thesis
+
+When you let models do work, the human's job is to define the rules and boundaries. That's the harness.
+
+**The key point:** Models are powerful, but that doesn't mean they can reliably complete real engineering tasks on their own. They need explicit rules to constrain their scope, clear handoff mechanisms to maintain continuity across long tasks, and verification methods to confirm they did the work correctly.
+
+We're not trying to "make the model smarter." We're studying how to build a reliable working environment around the model so the same model produces more reliable output.
+
+## Syllabus
+
+### Lectures
+
+- [Lecture 01. Strong models don't mean reliable execution](/lectures/lecture-01-why-capable-agents-still-fail/)
+- [Lecture 02. What harness actually means](/lectures/lecture-02-what-a-harness-actually-is/)
+- [Lecture 03. Make the repository your single source of truth](/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+- [Lecture 04. Split instructions across files, not one giant file](/lectures/lecture-04-why-one-giant-instruction-file-fails/)
+- [Lecture 05. Keep context alive across sessions](/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+- [Lecture 06. Initialize before every agent session](/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+- [Lecture 07. Draw clear task boundaries for agents](/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+- [Lecture 08. Use feature lists to constrain what the agent does](/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+- [Lecture 09. Stop agents from declaring victory early](/lectures/lecture-09-why-agents-declare-victory-too-early/)
+- [Lecture 10. Only a full-pipeline run counts as real verification](/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+- [Lecture 11. Make the agent's runtime observable](/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+- [Lecture 12. Clean handoff at the end of every session](/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+
+### Projects
+
+- [Project 01. Prompt-only vs. rules-first: how much difference does it make](/projects/project-01-baseline-vs-minimal-harness/)
+- [Project 02. Make the project readable and pick up where you left off](/projects/project-02-agent-readable-workspace/)
+- [Project 03. Keep the agent working across session restarts](/projects/project-03-multi-session-continuity/)
+- [Project 04. Use runtime feedback to correct agent behavior](/projects/project-04-incremental-indexing/)
+- [Project 05. Make the agent verify its own work](/projects/project-05-grounded-qa-verification/)
+- [Project 06. Build a complete agent harness](/projects/project-06-runtime-observability-and-debugging/)
+
+### Resource Library
+
+- [English Resource Overview](/en/resources)
+- [English Resource Library](/resources/en/)
+- [Chinese Resource Library](/resources/zh/)
diff --git a/docs/en/resources.md b/docs/en/resources.md
new file mode 100644
index 0000000..3e3ac85
--- /dev/null
+++ b/docs/en/resources.md
@@ -0,0 +1,28 @@
+# Resource Library
+
+This page is the English entry point for reusable templates, checklists, and method notes.
+
+Chinese is the default site language. The Chinese resource overview is available at [/resources/](../resources/).
+
+## English Resources
+
+- [English Resource Library](/resources/en/)
+- [English Templates](/resources/en/templates/)
+- [English Reference](/resources/en/reference/)
+
+## Chinese Resources
+
+- [Chinese Resource Library](/resources/zh/)
+- [Chinese Templates](/resources/zh/templates/)
+- [Chinese Reference](/resources/zh/reference/)
+
+## Recommended Starter Pack
+
+Start with these four files:
+
+1. `AGENTS.md` or `CLAUDE.md`
+2. `feature_list.json`
+3. `claude-progress.md`
+4. `init.sh`
+
+Detailed usage notes live in the [English template guide](/resources/en/templates/).
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f53d327
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,178 @@
+# Learn Harness Engineering
+
+> 这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 更可靠地工作。
+
+本课程仍在持续建设中,内容后续可能会调整。
+
+英文入口见:[English Home](/en/)
+
+## 课程概览
+
+Harness engineering 指的是:围绕模型搭建一整套工作环境,让它干活更靠谱。这不只是写提示词,还包括:
+
+- 代码放哪、怎么组织
+- 什么能干、什么干不了
+- 任务做到哪了、下次怎么接上
+- 做完怎么验证对不对
+- 出了问题怎么排查
+- 哪些规矩必须遵守
+- 怎么保持干净、不留烂摊子
+
+这门课是**强实践导向**的。我们不会只停留在“概念解释”,而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
+
+课程真正关心的问题是:
+
+- 哪些 harness 设计会提升任务完成率?
+- 哪些设计会减少返工和错误完成?
+- 哪些机制能让长时任务更稳定地持续推进?
+- 哪些结构能让系统在多轮 agent 运行后仍然可维护?
+
+## 核心观点
+
+以后让模型干活,人只需要定好规则和边界。这就是 harness。
+
+**为什么这个重要:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围,需要清晰的交接机制来维持长时任务的连续性,需要验证手段来确认自己做对了。
+
+我们不是在尝试“让模型本身更聪明”,而是在研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
+
+## 课程大纲
+
+### 讲义
+
+> 讲义正文目前仍以英文为主,中文先提供导览和说明。
+
+- [Lecture 01. 为什么强模型依然会失败](/lectures/lecture-01-why-capable-agents-still-fail/)
+- [Lecture 02. 什么才算 harness](/lectures/lecture-02-what-a-harness-actually-is/)
+- [Lecture 03. 为什么仓库必须成为 system of record](/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+- [Lecture 04. 为什么一个巨大的 instruction 文件会失败](/lectures/lecture-04-why-one-giant-instruction-file-fails/)
+- [Lecture 05. 为什么长时任务会失去连续性](/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+- [Lecture 06. 为什么初始化必须是独立阶段](/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+- [Lecture 07. 为什么 scope 必须被显式化](/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+- [Lecture 08. 为什么验证必须外部化](/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+- [Lecture 09. 为什么 runtime feedback 必须进入 harness](/lectures/lecture-09-why-agents-declare-victory-too-early/)
+- [Lecture 10. 为什么完整验证才算真的验证](/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+- [Lecture 11. 为什么可观测性必须进入 harness](/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+- [Lecture 12. 为什么每次会话都必须干净收尾](/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+
+### 项目
+
+> 项目正文目前仍以英文为主,中文先提供导览和学习路径。
+
+- [Project 01. 基线 vs 最小 harness](/projects/project-01-baseline-vs-minimal-harness/)
+- [Project 02. Agent-readable workspace 与 continuity scaffold](/projects/project-02-agent-readable-workspace/)
+- [Project 03. Scope control 与 grounded verification](/projects/project-03-multi-session-continuity/)
+- [Project 04. Runtime feedback 与 structural control](/projects/project-04-incremental-indexing/)
+- [Project 05. Evaluator loop 与三角色升级](/projects/project-05-grounded-qa-verification/)
+- [Project 06. Benchmark、cleanup 与 capstone harness](/projects/project-06-runtime-observability-and-debugging/)
+
+### 资料库
+
+- [资料库总览](/resources/)
+- [中文资料库](/resources/zh/)
+- [English Resource Library](/resources/en/)
+
+## 快速开始
+
+不必先把所有 lecture 读完。如果你想先上手,可以直接去资料库参考这些文件,然后按自己的项目改一版。
+
+中文版本:
+
+- 入口:[中文资料库](/resources/zh/)
+- 根指令文件:[`AGENTS.md`](/resources/zh/templates/AGENTS.md) 或 [`CLAUDE.md`](/resources/zh/templates/CLAUDE.md)
+- 功能状态文件:[`feature_list.json`](/resources/zh/templates/feature_list.json)
+- 进度记录文件:[`claude-progress.md`](/resources/zh/templates/claude-progress.md)
+- 会话交接文件:[`session-handoff.md`](/resources/zh/templates/session-handoff.md)
+- 收尾检查清单:[`clean-state-checklist.md`](/resources/zh/templates/clean-state-checklist.md)
+- 评审模板:[`evaluator-rubric.md`](/resources/zh/templates/evaluator-rubric.md)
+- 启动脚本参考:`docs/resources/zh/templates/init.sh`
+
+English version:
+
+- Entry: [English Home](/en/)
+- Library: [English Resource Library](/resources/en/)
+- Root instructions: [`AGENTS.md`](/resources/en/templates/AGENTS.md) or [`CLAUDE.md`](/resources/en/templates/CLAUDE.md)
+- Feature state: [`feature_list.json`](/resources/en/templates/feature_list.json)
+- Progress log: [`claude-progress.md`](/resources/en/templates/claude-progress.md)
+- Session handoff: [`session-handoff.md`](/resources/en/templates/session-handoff.md)
+- Clean-exit checklist: [`clean-state-checklist.md`](/resources/en/templates/clean-state-checklist.md)
+- Evaluator rubric: [`evaluator-rubric.md`](/resources/en/templates/evaluator-rubric.md)
+
+推荐最小起步组合:
+
+- `AGENTS.md` 或 `CLAUDE.md`
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+
+先把这四样放进你的项目里,再开始让 agent 真正干活,效果会比只写一段大 prompt 稳定得多。
+
+## 建议学习节奏
+
+这门课适合按 6 个单元推进:
+
+- **Unit 1**: Lecture 01-02 + Project 01
+- **Unit 2**: Lecture 03-04 + Project 02
+- **Unit 3**: Lecture 05-06 + Project 03
+- **Unit 4**: Lecture 07-08 + Project 04
+- **Unit 5**: Lecture 09-10 + Project 05
+- **Unit 6**: Lecture 11-12 + Project 06
+
+如果你想慢一点,也可以把每个单元当成一周来学。
+
+## 适合谁
+
+这门课适合:
+
+- 已经在使用 coding agent、希望提升稳定性和质量的工程师
+- 想系统理解 harness 设计的研究者或构建者
+- 需要理解“环境设计如何影响 agent 表现”的技术负责人
+
+这门课不适合:
+
+- 只想要一个零代码 AI 入门的人
+- 只关心 prompt,而不打算做真实实现的人
+- 不准备让 agent 在真实仓库里工作的学习者
+
+## 环境要求
+
+这是一门真正需要动手跑 coding agent 的课程。
+
+你至少需要具备一个这类工具:
+
+- Claude Code
+- Codex
+- 其他支持文件编辑、命令执行、多步任务的 IDE / CLI coding agent
+
+课程默认你可以:
+
+- 打开本地仓库
+- 允许 agent 编辑文件
+- 允许 agent 运行命令
+- 检查输出并重复执行任务
+
+如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程 project。
+
+## 核心参考资料
+
+主参考:
+
+- [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)
+
+辅助参考:
+
+- [LangChain: The Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)
+- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
+- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
+
+## 本地预览
+
+本仓库使用 VitePress 作为文档查看器。
+
+```sh
+npm install
+npm run docs:dev
+```
+
+然后在浏览器里打开 VitePress 输出的本地地址即可。
diff --git a/lectures/lecture-01-why-capable-agents-still-fail/README.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/README.md
similarity index 100%
rename from lectures/lecture-01-why-capable-agents-still-fail/README.md
rename to docs/lectures/lecture-01-why-capable-agents-still-fail/README.md
diff --git a/lectures/lecture-01-why-capable-agents-still-fail/code/README.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/code/README.md
similarity index 100%
rename from lectures/lecture-01-why-capable-agents-still-fail/code/README.md
rename to docs/lectures/lecture-01-why-capable-agents-still-fail/code/README.md
diff --git a/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
similarity index 100%
rename from lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
rename to docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
diff --git a/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
similarity index 100%
rename from lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
rename to docs/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
diff --git a/lectures/lecture-02-what-a-harness-actually-is/README.md b/docs/lectures/lecture-02-what-a-harness-actually-is/README.md
similarity index 100%
rename from lectures/lecture-02-what-a-harness-actually-is/README.md
rename to docs/lectures/lecture-02-what-a-harness-actually-is/README.md
diff --git a/lectures/lecture-02-what-a-harness-actually-is/code/README.md b/docs/lectures/lecture-02-what-a-harness-actually-is/code/README.md
similarity index 100%
rename from lectures/lecture-02-what-a-harness-actually-is/code/README.md
rename to docs/lectures/lecture-02-what-a-harness-actually-is/code/README.md
diff --git a/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
similarity index 100%
rename from lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
rename to docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
diff --git a/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
similarity index 100%
rename from lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
rename to docs/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
diff --git a/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/README.md
similarity index 100%
rename from lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md
rename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md
diff --git a/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/README.md
similarity index 100%
rename from lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/README.md
rename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/README.md
diff --git a/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt
similarity index 100%
rename from lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt
rename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt
diff --git a/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
similarity index 100%
rename from lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
rename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
diff --git a/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md
similarity index 100%
rename from lectures/lecture-04-why-one-giant-instruction-file-fails/README.md
rename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md
diff --git a/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
similarity index 100%
rename from lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
rename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
diff --git a/lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.md
similarity index 100%
rename from lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.md
rename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.md
diff --git a/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
similarity index 100%
rename from lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
rename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
diff --git a/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md
similarity index 100%
rename from lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md
rename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md
diff --git a/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.md
similarity index 100%
rename from lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.md
rename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.md
diff --git a/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
similarity index 100%
rename from lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
rename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
diff --git a/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
similarity index 100%
rename from lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
rename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
diff --git a/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md
similarity index 100%
rename from lectures/lecture-06-why-initialization-needs-its-own-phase/README.md
rename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md
diff --git a/lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.md b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.md
similarity index 100%
rename from lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.md
rename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.md
diff --git a/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
similarity index 100%
rename from lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
rename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
diff --git a/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
similarity index 100%
rename from lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
rename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
diff --git a/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md
similarity index 100%
rename from lectures/lecture-07-why-agents-overreach-and-under-finish/README.md
rename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md
diff --git a/lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.md
similarity index 100%
rename from lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.md
rename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.md
diff --git a/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
similarity index 100%
rename from lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
rename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
diff --git a/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
similarity index 100%
rename from lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
rename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
diff --git a/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md
similarity index 100%
rename from lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md
rename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md
diff --git a/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.md b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.md
similarity index 100%
rename from lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.md
rename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.md
diff --git a/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
similarity index 100%
rename from lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
rename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
diff --git a/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
similarity index 100%
rename from lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
rename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
diff --git a/lectures/lecture-09-why-agents-declare-victory-too-early/README.md b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.md
similarity index 100%
rename from lectures/lecture-09-why-agents-declare-victory-too-early/README.md
rename to docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.md
diff --git a/lectures/lecture-09-why-agents-declare-victory-too-early/code/README.md b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/README.md
similarity index 100%
rename from lectures/lecture-09-why-agents-declare-victory-too-early/code/README.md
rename to docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/README.md
diff --git a/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
similarity index 100%
rename from lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
rename to docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
diff --git a/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md
similarity index 100%
rename from lectures/lecture-10-why-end-to-end-testing-changes-results/README.md
rename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md
diff --git a/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/README.md
similarity index 100%
rename from lectures/lecture-10-why-end-to-end-testing-changes-results/code/README.md
rename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/README.md
diff --git a/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
similarity index 100%
rename from lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
rename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
diff --git a/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
similarity index 100%
rename from lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
rename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
diff --git a/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md
similarity index 100%
rename from lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md
rename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md
diff --git a/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.md
similarity index 100%
rename from lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.md
rename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.md
diff --git a/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
similarity index 100%
rename from lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
rename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
diff --git a/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
similarity index 100%
rename from lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
rename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
diff --git a/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/README.md
similarity index 100%
rename from lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md
rename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md
diff --git a/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/README.md
similarity index 100%
rename from lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/README.md
rename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/README.md
diff --git a/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
similarity index 100%
rename from lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
rename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
diff --git a/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
similarity index 100%
rename from lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
rename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
diff --git a/projects/project-01-baseline-vs-minimal-harness/README.md b/docs/projects/project-01-baseline-vs-minimal-harness/README.md
similarity index 100%
rename from projects/project-01-baseline-vs-minimal-harness/README.md
rename to docs/projects/project-01-baseline-vs-minimal-harness/README.md
diff --git a/projects/project-02-agent-readable-workspace/README.md b/docs/projects/project-02-agent-readable-workspace/README.md
similarity index 100%
rename from projects/project-02-agent-readable-workspace/README.md
rename to docs/projects/project-02-agent-readable-workspace/README.md
diff --git a/projects/project-03-multi-session-continuity/README.md b/docs/projects/project-03-multi-session-continuity/README.md
similarity index 100%
rename from projects/project-03-multi-session-continuity/README.md
rename to docs/projects/project-03-multi-session-continuity/README.md
diff --git a/projects/project-04-incremental-indexing/README.md b/docs/projects/project-04-incremental-indexing/README.md
similarity index 100%
rename from projects/project-04-incremental-indexing/README.md
rename to docs/projects/project-04-incremental-indexing/README.md
diff --git a/projects/project-05-grounded-qa-verification/README.md b/docs/projects/project-05-grounded-qa-verification/README.md
similarity index 100%
rename from projects/project-05-grounded-qa-verification/README.md
rename to docs/projects/project-05-grounded-qa-verification/README.md
diff --git a/projects/project-06-runtime-observability-and-debugging/README.md b/docs/projects/project-06-runtime-observability-and-debugging/README.md
similarity index 97%
rename from projects/project-06-runtime-observability-and-debugging/README.md
rename to docs/projects/project-06-runtime-observability-and-debugging/README.md
index 092f0b8..007c46f 100644
--- a/projects/project-06-runtime-observability-and-debugging/README.md
+++ b/docs/projects/project-06-runtime-observability-and-debugging/README.md
@@ -44,7 +44,8 @@ Run 2 must use the strongest harness assembled in the course:
## Procedure
1. Create a quality document using the template in
- `resources/en/templates/quality-document.md` (or `resources/zh/templates/`).
+ `docs/resources/en/templates/quality-document.md` (or
+ `docs/resources/zh/templates/`).
Fill in initial grades for all product domains and architectural layers based
on the current codebase state.
2. Define one fixed benchmark task suite and one scoring sheet before running
diff --git a/docs/resources/en/README.md b/docs/resources/en/README.md
index f612fb2..4f413a7 100644
--- a/docs/resources/en/README.md
+++ b/docs/resources/en/README.md
@@ -23,7 +23,7 @@ For a minimal setup, begin with:
- root instructions: [`templates/AGENTS.md`](./templates/AGENTS.md) or [`templates/CLAUDE.md`](./templates/CLAUDE.md)
- feature state: [`templates/feature_list.json`](./templates/feature_list.json)
- progress log: [`templates/claude-progress.md`](./templates/claude-progress.md)
-- bootstrap script reference: `resources/en/templates/init.sh`
+- bootstrap script reference: `docs/resources/en/templates/init.sh`
Then add:
diff --git a/docs/resources/zh/README.md b/docs/resources/zh/README.md
index f6be0bb..10536b5 100644
--- a/docs/resources/zh/README.md
+++ b/docs/resources/zh/README.md
@@ -21,7 +21,7 @@
- 根指令文件:[`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)
-- 启动脚本参考:`resources/zh/templates/init.sh`
+- 启动脚本参考:`docs/resources/zh/templates/init.sh`
然后按需要补上:
diff --git a/docs/zh/index.md b/docs/zh/index.md
new file mode 100644
index 0000000..8e73559
--- /dev/null
+++ b/docs/zh/index.md
@@ -0,0 +1,176 @@
+# Learn Harness Engineering
+
+> 这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 更可靠地工作。
+
+本课程仍在持续建设中,内容后续可能会调整。
+
+## 课程概览
+
+Harness engineering 指的是:围绕模型搭建一整套工作环境,让它干活更靠谱。这不只是写提示词,还包括:
+
+- 代码放哪、怎么组织
+- 什么能干、什么干不了
+- 任务做到哪了、下次怎么接上
+- 做完怎么验证对不对
+- 出了问题怎么排查
+- 哪些规矩必须遵守
+- 怎么保持干净、不留烂摊子
+
+这门课是**强实践导向**的。我们不会只停留在"概念解释",而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
+
+课程真正关心的问题是:
+
+- 哪些 harness 设计会提升任务完成率?
+- 哪些设计会减少返工和错误完成?
+- 哪些机制能让长时任务更稳定地持续推进?
+- 哪些结构能让系统在多轮 agent 运行后仍然可维护?
+
+## 核心观点
+
+以后让模型干活,人只需要定好规则和边界——这就是 harness。
+
+**为什么这个重要:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围、需要清晰的交接机制来维持长时任务的连续性、需要验证手段来确认自己做对了。
+
+我们不是在尝试"让模型本身更聪明",而是研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
+
+## 课程大纲
+
+### 讲义
+
+> 讲义内容为英文,暂未提供中文翻译。
+
+- [Lecture 01. 为什么强模型依然会失败](/lectures/lecture-01-why-capable-agents-still-fail/)
+- [Lecture 02. 什么才算 harness](/lectures/lecture-02-what-a-harness-actually-is/)
+- [Lecture 03. 为什么仓库必须成为 system of record](/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+- [Lecture 04. 为什么一个巨大的 instruction 文件会失败](/lectures/lecture-04-why-one-giant-instruction-file-fails/)
+- [Lecture 05. 为什么长时任务会失去连续性](/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+- [Lecture 06. 为什么初始化必须是独立阶段](/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+- [Lecture 07. 为什么 scope 必须被显式化](/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+- [Lecture 08. 为什么验证必须外部化](/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+- [Lecture 09. 为什么 runtime feedback 必须进入 harness](/lectures/lecture-09-why-agents-declare-victory-too-early/)
+- [Lecture 10. 为什么结构和 taste 必须被强制执行](/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+- [Lecture 11. 为什么更强的 harness 会拆分角色](/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+- [Lecture 12. 为什么 harness 必须被持续度量和维护](/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+
+### 项目
+
+> 项目内容为英文,暂未提供中文翻译。
+
+- [Project 01. 基线 vs 最小 harness](/projects/project-01-baseline-vs-minimal-harness/)
+- [Project 02. Agent-readable workspace 与 continuity scaffold](/projects/project-02-agent-readable-workspace/)
+- [Project 03. Scope control 与 grounded verification](/projects/project-03-multi-session-continuity/)
+- [Project 04. Runtime feedback 与 structural control](/projects/project-04-incremental-indexing/)
+- [Project 05. Evaluator loop 与三角色升级](/projects/project-05-grounded-qa-verification/)
+- [Project 06. Benchmark、cleanup 与 capstone harness](/projects/project-06-runtime-observability-and-debugging/)
+
+### 资料库
+
+- [Resource Library 总览](/resources/)
+- [中文资料库](/resources/zh/)
+- [English Resource Library](/resources/en/)
+
+## 适合谁
+
+这门课适合:
+
+- 已经在使用 coding agent、希望提升稳定性和质量的工程师
+- 想系统理解 harness 设计的研究者或构建者
+- 需要理解"环境设计如何影响 agent 表现"的技术负责人
+
+这门课不适合:
+
+- 只想要一个零代码 AI 入门的人
+- 只关心 prompt,而不打算做真实实现的人
+- 不准备让 agent 在真实仓库里工作的学习者
+
+## 环境要求
+
+这是一门真正需要动手跑 coding agent 的课程。
+
+你至少需要具备一个这类工具:
+
+- Claude Code
+- Codex
+- 其他支持文件编辑、命令执行、多步任务的 IDE / CLI coding agent
+
+课程默认你可以:
+
+- 打开本地仓库
+- 允许 agent 编辑文件
+- 允许 agent 运行命令
+- 检查输出并重复执行任务
+
+如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程 project。
+
+## 快速开始
+
+不必先把所有 lecture 读完。如果你想先上手,可以直接去资料库参考这些文件,然后按自己的项目改一版。
+
+中文版本:
+
+- 入口:[中文资料库](/resources/zh/)
+- 根指令文件:[`AGENTS.md`](/resources/zh/templates/AGENTS.md) 或 [`CLAUDE.md`](/resources/zh/templates/CLAUDE.md)
+- 功能状态文件:[`feature_list.json`](/resources/zh/templates/feature_list.json)
+- 进度记录文件:[`claude-progress.md`](/resources/zh/templates/claude-progress.md)
+- 会话交接文件:[`session-handoff.md`](/resources/zh/templates/session-handoff.md)
+- 收尾检查清单:[`clean-state-checklist.md`](/resources/zh/templates/clean-state-checklist.md)
+- 评审模板:[`evaluator-rubric.md`](/resources/zh/templates/evaluator-rubric.md)
+- 启动脚本参考:`docs/resources/zh/templates/init.sh`
+
+English version:
+
+- Entry: [English Resource Library](/resources/en/)
+- Root instructions: [`AGENTS.md`](/resources/en/templates/AGENTS.md) or [`CLAUDE.md`](/resources/en/templates/CLAUDE.md)
+- Feature state: [`feature_list.json`](/resources/en/templates/feature_list.json)
+- Progress log: [`claude-progress.md`](/resources/en/templates/claude-progress.md)
+- Session handoff: [`session-handoff.md`](/resources/en/templates/session-handoff.md)
+- Clean-exit checklist: [`clean-state-checklist.md`](/resources/en/templates/clean-state-checklist.md)
+- Evaluator rubric: [`evaluator-rubric.md`](/resources/en/templates/evaluator-rubric.md)
+- Bootstrap script reference: `docs/resources/en/templates/init.sh`
+
+推荐最小起步组合:
+
+- `AGENTS.md` 或 `CLAUDE.md`
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+
+先把这四样放进你的项目里,再开始让 agent 真正干活,效果会比只写一段大 prompt 稳定得多。
+
+## 建议学习节奏
+
+这门课适合按 6 个单元推进:
+
+- **Unit 1**: Lecture 01-02 + Project 01
+- **Unit 2**: Lecture 03-04 + Project 02
+- **Unit 3**: Lecture 05-06 + Project 03
+- **Unit 4**: Lecture 07-08 + Project 04
+- **Unit 5**: Lecture 09-10 + Project 05
+- **Unit 6**: Lecture 11-12 + Project 06
+
+如果你想慢一点,也可以把每个单元当成一周来学。
+
+## 核心参考资料
+
+主参考:
+
+- [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)
+
+辅助参考:
+
+- [LangChain: The Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)
+- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
+- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
+
+## 本地预览
+
+本仓库使用 VitePress 作为文档查看器。
+
+```sh
+npm install
+npm run docs:dev
+```
+
+然后在浏览器里打开 VitePress 输出的本地地址即可。
diff --git a/docs/zh/resources.md b/docs/zh/resources.md
new file mode 100644
index 0000000..b56f950
--- /dev/null
+++ b/docs/zh/resources.md
@@ -0,0 +1,26 @@
+# 资料库
+
+本页提供中英双语的可复用模板、检查清单和方法参考。
+
+## 中文资料
+
+- [中文资料库总览](/resources/zh/) — 入口和说明
+- [中文模板](/resources/zh/templates/) — 可直接复制使用的模板文件
+- [中文参考](/resources/zh/reference/) — 方法论和参考文档
+
+## English Resources
+
+- [English Resource Library](/resources/en/) — Entry and overview
+- [English Templates](/resources/en/templates/) — Ready-to-use template files
+- [English Reference](/resources/en/reference/) — Methodology and reference docs
+
+## 推荐最小起步
+
+四个文件,最小起步就够了:
+
+1. `AGENTS.md` 或 `CLAUDE.md` — 根指令文件
+2. `feature_list.json` — 功能状态文件
+3. `claude-progress.md` — 进度记录
+4. `init.sh` — 启动脚本
+
+每个文件的详细用法见 [中文模板指南](/resources/zh/templates/)。
diff --git a/index.md b/index.md
deleted file mode 100644
index af3a21a..0000000
--- a/index.md
+++ /dev/null
@@ -1,248 +0,0 @@
-# Learn Harness Engineering
-
-> 这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 Codex 和 Claude Code 更可靠地工作。
-
-本课程仍在持续建设中,内容后续可能会调整。
-
-## 课程概览
-
-Harness engineering 指的是:围绕模型搭建一整套工作环境,让它干活更靠谱。这不只是写提示词,还包括:
-
-- 代码放哪、怎么组织
-- 什么能干、什么干不了
-- 任务做到哪了、下次怎么接上
-- 做完怎么验证对不对
-- 出了问题怎么排查
-- 哪些规矩必须遵守
-- 怎么保持干净、不留烂摊子
-
-这门课是**强实践导向**的。我们不会只停留在“概念解释”,而是会让 Codex 或 Claude Code 在同一个不断演化的 Electron 应用上反复工作,并比较弱 harness 与强 harness 的差异。
-
-课程真正关心的问题是:
-
-- 哪些 harness 设计会提升任务完成率?
-- 哪些设计会减少返工和错误完成?
-- 哪些机制能让长时任务更稳定地持续推进?
-- 哪些结构能让系统在多轮 agent 运行后仍然可维护?
-
-## 核心观点
-
-以后让模型干活,人只需要定好规则和边界——这就是 harness。
-
-**为什么这个重要:** 模型很强,但不代表它能自动靠谱地完成真实工程任务。它需要一套明确的规则来约束自己的行为范围、需要清晰的交接机制来维持长时任务的连续性、需要验证手段来确认自己做对了。
-
-我们不是在尝试"让模型本身更聪明",而是研究:怎么给模型搭建一个靠谱的工作环境,让同一个模型做出更可靠的工作。
-
-## 课程大纲
-
-### 讲义
-
-- [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. 为什么仓库必须成为 system of record](./lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md)
-- [Lecture 04. 为什么一个巨大的 instruction 文件会失败](./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. 为什么初始化必须是独立阶段](./lectures/lecture-06-why-initialization-needs-its-own-phase/README.md)
-- [Lecture 07. 为什么 scope 必须被显式化](./lectures/lecture-07-why-agents-overreach-and-under-finish/README.md)
-- [Lecture 08. 为什么验证必须外部化](./lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md)
-- [Lecture 09. 为什么 runtime feedback 必须进入 harness](./lectures/lecture-09-why-agents-declare-victory-too-early/README.md)
-- [Lecture 10. 为什么结构和 taste 必须被强制执行](./lectures/lecture-10-why-end-to-end-testing-changes-results/README.md)
-- [Lecture 11. 为什么更强的 harness 会拆分角色](./lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md)
-- [Lecture 12. 为什么 harness 必须被持续度量和维护](./lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md)
-
-### 项目
-
-- [Project 01. 基线 vs 最小 harness](./projects/project-01-baseline-vs-minimal-harness/README.md)
-- [Project 02. Agent-readable workspace 与 continuity scaffold](./projects/project-02-agent-readable-workspace/README.md)
-- [Project 03. Scope control 与 grounded verification](./projects/project-03-multi-session-continuity/README.md)
-- [Project 04. Runtime feedback 与 structural control](./projects/project-04-incremental-indexing/README.md)
-- [Project 05. Evaluator loop 与三角色升级](./projects/project-05-grounded-qa-verification/README.md)
-- [Project 06. Benchmark、cleanup 与 capstone harness](./projects/project-06-runtime-observability-and-debugging/README.md)
-
-### 资料库
-
-- [Resource Library 总览](./resources/README.md)
-- [中文资料库](./resources/zh/README.md)
-- [English Resource Library](./resources/en/README.md)
-
-## 适合谁
-
-这门课适合:
-
-- 已经在使用 coding agent、希望提升稳定性和质量的工程师
-- 想系统理解 harness 设计的研究者或构建者
-- 需要理解“环境设计如何影响 agent 表现”的技术负责人
-
-这门课不适合:
-
-- 只想要一个零代码 AI 入门的人
-- 只关心 prompt,而不打算做真实实现的人
-- 不准备让 agent 在真实仓库里工作的学习者
-
-## 环境要求
-
-这是一门真正需要动手跑 coding agent 的课程。
-
-你至少需要具备一个这类工具:
-
-- Claude Code
-- Codex
-- 其他支持文件编辑、命令执行、多步任务的 IDE / CLI coding agent
-
-课程默认你可以:
-
-- 打开本地仓库
-- 允许 agent 编辑文件
-- 允许 agent 运行命令
-- 检查输出并重复执行任务
-
-如果你没有这类工具,仍然可以阅读课程内容,但无法按预期完成课程 project。
-
-## 快速开始
-
-OpenAI 和 Anthropic 这两条线,虽然写法不同,但都在探索同一件事:不是只改 prompt,而是给 coding agent 一套可持续工作的环境。核心做法包括把仓库变成 system of record、把任务状态外部化、把验证变成硬门槛、把每次会话的交接做成可复用的标准流程。
-
-如果你想先上手,不必先把所有 lecture 读完。可以先去专门的资料库文件夹,直接参考这些文件,然后按自己的项目改一版。
-
-中文版本:
-
-- 入口:[`resources/zh/README.md`](./resources/zh/README.md)
-- 根指令文件:[`resources/zh/templates/AGENTS.md`](./resources/zh/templates/AGENTS.md) 或 [`resources/zh/templates/CLAUDE.md`](./resources/zh/templates/CLAUDE.md)
-- 功能状态文件:[`resources/zh/templates/feature_list.json`](./resources/zh/templates/feature_list.json)
-- 进度记录文件:[`resources/zh/templates/claude-progress.md`](./resources/zh/templates/claude-progress.md)
-- 会话交接文件:[`resources/zh/templates/session-handoff.md`](./resources/zh/templates/session-handoff.md)
-- 收尾检查清单:[`resources/zh/templates/clean-state-checklist.md`](./resources/zh/templates/clean-state-checklist.md)
-- 评审模板:[`resources/zh/templates/evaluator-rubric.md`](./resources/zh/templates/evaluator-rubric.md)
-- 启动脚本参考:`resources/zh/templates/init.sh`
-
-English version:
-
-- Entry: [`resources/en/README.md`](./resources/en/README.md)
-- Root instructions: [`resources/en/templates/AGENTS.md`](./resources/en/templates/AGENTS.md) or [`resources/en/templates/CLAUDE.md`](./resources/en/templates/CLAUDE.md)
-- Feature state: [`resources/en/templates/feature_list.json`](./resources/en/templates/feature_list.json)
-- Progress log: [`resources/en/templates/claude-progress.md`](./resources/en/templates/claude-progress.md)
-- Session handoff: [`resources/en/templates/session-handoff.md`](./resources/en/templates/session-handoff.md)
-- Clean-exit checklist: [`resources/en/templates/clean-state-checklist.md`](./resources/en/templates/clean-state-checklist.md)
-- Evaluator rubric: [`resources/en/templates/evaluator-rubric.md`](./resources/en/templates/evaluator-rubric.md)
-- Bootstrap script reference: `resources/en/templates/init.sh`
-
-推荐最小起步组合:
-
-- `AGENTS.md` 或 `CLAUDE.md`
-- `feature_list.json`
-- `claude-progress.md`
-- `init.sh`
-
-先把这四样放进你的项目里,再开始让 agent 真正干活,效果会比只写一段大 prompt 稳定得多。
-
-## 本地预览
-
-本仓库使用 VitePress 作为文档查看器。
-
-```sh
-npm install
-npm run docs:dev
-```
-
-然后在浏览器里打开 VitePress 输出的本地地址即可。
-
-## 先修要求
-
-必需:
-
-- 熟悉终端、git 和本地开发环境
-- 至少会读写一种常见应用栈中的代码
-- 有基本的软件调试经验,知道如何看日志、测试和运行行为
-- 能投入足够时间完成偏实现型的课程任务
-
-有帮助但非强制:
-
-- 用过 Electron、桌面应用或本地优先工具
-- 有测试、日志、软件架构方面的经验
-- 已经接触过 Codex、Claude Code 或类似 coding agent
-
-## 核心参考资料
-
-主参考:
-
-- [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)
-
-辅助参考:
-
-- [LangChain: The Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)
-- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
-- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
-
-## 贯穿项目
-
-本课程的大多数 project 都围绕同一个产品展开:
-
-- 一个基于 Electron 的个人知识库桌面应用
-
-核心目标包括:
-
-- 导入本地文档
-- 管理文档库
-- 处理与索引文档
-- 对导入内容发起 AI 问答
-- 返回带引用的 grounded 回答
-
-之所以选择这个项目,是因为它同时具备:
-
-- 很强的实际价值感
-- 足够真实的产品复杂度
-- 很适合观察 harness 优化前后的效果差异
-
-## 课程作业形式
-
-本课程包含两类内容:
-
-- **Lectures**:12 个概念单元,每个单元只回答一个核心问题
-- **Projects**:6 个实践项目,把 lecture 里的方法落实到同一个 Electron 应用上
-
-每个 project 都要求你:
-
-- 让 Codex 或 Claude Code 执行真实任务
-- 比较弱 harness 与强 harness 的差别
-- 观察可靠性、连续性、验证质量、可维护性的变化
-
-最后一个 project 同时也是整个课程的 capstone harness。
-
-## 课程组织方式
-
-- 每个 lecture 聚焦一个问题
-- 整门课配套 6 个 project
-- 每个 project 都要求 agent 真正干活
-- 每个 project 都要做弱 harness / 强 harness 对照
-- 我们关心的是效果变化,而不是“写了多少说明文档”
-
-## 仓库结构
-
-- `lectures/` - 全部讲义
-- `projects/` - 全部实践项目,包括 capstone
-- `resources/` - 中英双语的可复用模板、检查清单和方法参考
-
-每个 lecture 都带一个 `code/` 目录,用来放小型真实示例和 supporting artifacts。
-
-## 建议学习节奏
-
-这门课适合按 6 个单元推进:
-
-- **Unit 1**: Lecture 01-02 + Project 01
-- **Unit 2**: Lecture 03-04 + Project 02
-- **Unit 3**: Lecture 05-06 + Project 03
-- **Unit 4**: Lecture 07-08 + Project 04
-- **Unit 5**: Lecture 09-10 + Project 05
-- **Unit 6**: Lecture 11-12 + Project 06
-
-如果你想慢一点,也可以把每个单元当成一周来学。
-
-## 如何使用这个仓库
-
-1. 先读课程首页,理解整体结构。
-2. 按顺序阅读 12 个 lecture。
-3. 用 6 个 project 作为实践主线。
-4. lecture 里的 `code/` 目录用于查看小型示例和真实 artifact。
-5. 最后把 Project 06 当作整门课的 capstone harness。
diff --git a/lectures/lecture-09-why-agents-declare-victory-too-early/code/indexing.log b/lectures/lecture-09-why-agents-declare-victory-too-early/code/indexing.log
deleted file mode 100644
index 8ffe2b0..0000000
--- a/lectures/lecture-09-why-agents-declare-victory-too-early/code/indexing.log
+++ /dev/null
@@ -1,7 +0,0 @@
-[startup] electron window created
-[import] imported 3 documents from /Users/example/Documents/kb
-[index] starting chunk pipeline
-[index] doc=design-notes.md chunks=18
-[index] doc=meeting-summary.txt chunks=9
-[index] doc=retrieval-plan.md chunks=13
-[index] completed in 2.14s
diff --git a/package.json b/package.json
index 03557d1..11c96b3 100644
--- a/package.json
+++ b/package.json
@@ -4,9 +4,9 @@
"version": "0.1.0",
"description": "Course docs for Learn Harness Engineering powered by VitePress.",
"scripts": {
- "docs:dev": "vitepress dev",
- "docs:build": "vitepress build",
- "docs:preview": "vitepress preview"
+ "docs:dev": "vitepress dev docs",
+ "docs:build": "vitepress build docs",
+ "docs:preview": "vitepress preview docs"
},
"devDependencies": {
"vitepress": "^1.6.4"
diff --git a/resources/README.md b/resources/README.md
deleted file mode 100644
index 1730bb9..0000000
--- a/resources/README.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Resource Library
-
-This folder is the bilingual starter library for the course. It turns the
-course methods into copy-ready templates and compact references you can use in a
-real repository.
-
-## Choose A Language
-
-- 中文资料库: [`zh/README.md`](./zh/README.md)
-- English library: [`en/README.md`](./en/README.md)
-
-## What You Will Find
-
-- root instruction templates
-- feature and progress state files
-- handoff and clean-exit checklists
-- bootstrap script references
-- compact method notes for initializer and coding-agent flows
-
-## Recommended Starter Pack
-
-- `AGENTS.md` or `CLAUDE.md`
-- `feature_list.json`
-- `claude-progress.md`
-- `init.sh`
-
-Start with those four files first, then add handoff and evaluator artifacts as
-the project becomes longer-running or higher-risk.
diff --git a/resources/en/README.md b/resources/en/README.md
deleted file mode 100644
index 04e702d..0000000
--- a/resources/en/README.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# English Resource Library
-
-This folder turns the course methods into copy-ready templates and compact
-references you can use in a real repository.
-
-## When To Use It
-
-Start here when you want Codex, Claude Code, or another coding agent to work
-across multiple sessions without constantly re-deriving setup, status, and
-scope.
-
-It is especially useful when:
-
-- work spans multiple sessions
-- features are numerous and easy to leave half-finished
-- agents tend to declare victory too early
-- startup steps are rediscovered every time
-
-## Start Here
-
-For a minimal setup, begin with:
-
-- root instructions: [`templates/AGENTS.md`](./templates/AGENTS.md) or [`templates/CLAUDE.md`](./templates/CLAUDE.md)
-- feature state: [`templates/feature_list.json`](./templates/feature_list.json)
-- progress log: [`templates/claude-progress.md`](./templates/claude-progress.md)
-- bootstrap script reference: `resources/en/templates/init.sh`
-
-Then add:
-
-- session handoff: [`templates/session-handoff.md`](./templates/session-handoff.md)
-- clean-exit checklist: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)
-- evaluator rubric: [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.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
-
-## Recommended Minimal Pack
-
-- `AGENTS.md` or `CLAUDE.md`
-- `feature_list.json`
-- `claude-progress.md`
-- `init.sh`
-
-Those four files are enough to make most agent workflows noticeably more stable.
diff --git a/resources/en/reference/README.md b/resources/en/reference/README.md
deleted file mode 100644
index 6c5b128..0000000
--- a/resources/en/reference/README.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# English Reference
-
-These notes explain how to use the templates as a working harness instead of a
-loose pile of files.
-
-## Reference Notes
-
-- [`method-map.md`](./method-map.md): map common long-running failure modes to
- the artifact or policy that addresses them first
-- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md): what the
- initializer should leave behind before feature work starts
-- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md): fixed
- session-start flow for later coding runs
-- [`prompt-calibration.md`](./prompt-calibration.md): how to keep root
- instructions sharp without making them bloated and brittle
-
-## Suggested Reading Order
-
-1. `method-map.md`
-2. `initializer-agent-playbook.md`
-3. `coding-agent-startup-flow.md`
-4. `prompt-calibration.md`
diff --git a/resources/en/reference/coding-agent-startup-flow.md b/resources/en/reference/coding-agent-startup-flow.md
deleted file mode 100644
index b4d8781..0000000
--- a/resources/en/reference/coding-agent-startup-flow.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Coding Agent Startup Flow
-
-Use this at the beginning of every session after initialization is complete.
-
-## Fixed Startup Template
-
-1. Run `pwd` and confirm the repository root.
-2. Read `claude-progress.md`.
-3. Read `feature_list.json`.
-4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Run a baseline smoke or end-to-end path.
-7. If the baseline is broken, fix that first.
-8. Select the highest-priority unfinished feature.
-9. Work only on that feature until it is verified or explicitly blocked.
-
-## Why This Order Matters
-
-- `pwd` prevents accidental work in the wrong directory.
-- progress and feature files recover durable state before new edits begin.
-- recent commits explain what changed most recently.
-- `init.sh` standardizes startup instead of relying on memory.
-- baseline verification catches broken starting states before new work hides
- them.
-
-## End-Of-Session Mirror
-
-The same session should end by:
-
-1. recording progress
-2. updating feature state
-3. writing a handoff if needed
-4. committing safe work
-5. leaving a clean restart path
diff --git a/resources/en/reference/initializer-agent-playbook.md b/resources/en/reference/initializer-agent-playbook.md
deleted file mode 100644
index 622cf9b..0000000
--- a/resources/en/reference/initializer-agent-playbook.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Initializer Agent Playbook
-
-Use this playbook for the first serious session in a repository, before
-incremental feature work begins.
-
-## Goal
-
-Create a stable operating surface so later sessions can implement behavior
-without re-deriving startup commands, current status, or task boundaries.
-
-## Required Outputs
-
-The initializer should leave behind at least these artifacts:
-
-- a root instruction file such as `AGENTS.md` or `CLAUDE.md`
-- a machine-readable feature surface such as `feature_list.json`
-- a durable progress artifact such as `claude-progress.md`
-- a standard startup helper such as `init.sh`
-- an initial safe commit that captures the baseline scaffold
-
-## Checklist
-
-1. Define the standard startup path.
-2. Define the standard verification path.
-3. Create the progress log and record the starting state.
-4. Decompose the work into explicit features with statuses.
-5. Create the first clean baseline commit.
-
-## Success Test
-
-A fresh session with no prior chat context should be able to answer:
-
-- what this repository does
-- how to start it
-- how to verify it
-- what is unfinished
-- what the next best step is
diff --git a/resources/en/reference/method-map.md b/resources/en/reference/method-map.md
deleted file mode 100644
index 405e4ca..0000000
--- a/resources/en/reference/method-map.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Method Map
-
-This table maps the most common long-running coding-agent failure modes to the
-artifact or operating rule that usually fixes them first.
-
-| Failure mode | What it looks like in practice | Primary fix | Supporting artifact |
-| --- | --- | --- | --- |
-| Cold-start confusion | A new session spends most of its time rediscovering setup and status | Make the repository the system of record | `claude-progress.md` |
-| Scope sprawl | The agent starts several features and finishes none of them cleanly | Restrict active scope | `feature_list.json` |
-| Premature completion | The agent claims done after code edits but before runnable proof | Bind completion to evidence | `clean-state-checklist.md` |
-| Fragile startup | Every session re-learns how to boot the project | Standardize setup and verification | `init.sh` |
-| Weak handoff | The next session cannot tell what is verified, broken, or next | End with an explicit handoff | `session-handoff.md` |
-| Subjective review | Review quality depends on taste or memory | Score output with fixed categories | `evaluator-rubric.md` |
-
-## Operating Principle
-
-Add the smallest artifact that directly addresses the observed failure mode.
-Avoid solving every reliability problem by dumping more text into one global
-instruction file.
diff --git a/resources/en/reference/prompt-calibration.md b/resources/en/reference/prompt-calibration.md
deleted file mode 100644
index 0a69403..0000000
--- a/resources/en/reference/prompt-calibration.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Prompt Calibration
-
-Root instructions should define the operating frame, not every possible move.
-
-## Keep In The Root File
-
-- repository purpose and scope
-- startup path
-- verification path
-- non-negotiable constraints
-- required state artifacts
-- end-of-session rules
-
-## Move Out Of The Root File
-
-- long historical edge cases
-- topic-specific implementation details
-- local architecture notes that belong near the code
-- examples that only apply to one subsystem
-
-## Working Rule
-
-The root file should help a fresh session orient itself quickly. If the file is
-becoming a dumping ground for every past failure, split the detail into smaller
-documents and link to them instead.
diff --git a/resources/en/templates/AGENTS.md b/resources/en/templates/AGENTS.md
deleted file mode 100644
index 3052639..0000000
--- a/resources/en/templates/AGENTS.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# AGENTS.md
-
-This repository is designed for long-running coding-agent work. The goal is not
-to maximize raw code output. The goal is to leave the repo in a state where the
-next session can continue without guessing.
-
-## Startup Workflow
-
-Before writing code:
-
-1. Confirm the working directory with `pwd`.
-2. Read `claude-progress.md` for the latest verified state and next step.
-3. Read `feature_list.json` and choose the highest-priority unfinished feature.
-4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Run the required smoke or end-to-end verification before starting new work.
-
-If baseline verification is already failing, fix that first. Do not stack new
-feature work on top of a broken starting state.
-
-## Working Rules
-
-- Work on one feature at a time.
-- Do not mark a feature complete just because code was added.
-- Keep changes within the selected feature scope unless a blocker forces a
- narrow supporting fix.
-- Do not silently change verification rules during implementation.
-- Prefer durable repo artifacts over chat summaries.
-
-## Required Artifacts
-
-- `feature_list.json`: source of truth for feature state
-- `claude-progress.md`: session log and current verified status
-- `init.sh`: standard startup and verification path
-- `session-handoff.md`: optional compact handoff for larger sessions
-
-## Definition Of Done
-
-A feature is done only when all of the following are true:
-
-- the target behavior is implemented
-- the required verification actually ran
-- evidence is recorded in `feature_list.json` or `claude-progress.md`
-- the repository remains restartable from the standard startup path
-
-## End Of Session
-
-Before ending a session:
-
-1. Update `claude-progress.md`.
-2. Update `feature_list.json`.
-3. Record any unresolved risk or blocker.
-4. Commit with a descriptive message once the work is in a safe state.
-5. Leave the repo clean enough for the next session to run `./init.sh`
- immediately.
diff --git a/resources/en/templates/CLAUDE.md b/resources/en/templates/CLAUDE.md
deleted file mode 100644
index 040b4ff..0000000
--- a/resources/en/templates/CLAUDE.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# CLAUDE.md
-
-You are working in a repository designed for long-running implementation work.
-Prioritize reliable completion, continuity across sessions, and explicit
-verification over speed.
-
-## Operating Loop
-
-At the start of every session:
-
-1. Run `pwd` and confirm you are in the expected repository root.
-2. Read `claude-progress.md`.
-3. Read `feature_list.json`.
-4. Review recent commits with `git log --oneline -5`.
-5. Run `./init.sh`.
-6. Check whether the baseline smoke or end-to-end path is already broken.
-
-Then select exactly one unfinished feature and work only on that feature until
-you either verify it or document why it is blocked.
-
-## Rules
-
-- One active feature at a time.
-- Do not claim completion without runnable evidence.
-- Do not rewrite the feature list to hide unfinished work.
-- Do not remove or weaken tests just to make the task look complete.
-- Use repository artifacts as the system of record.
-
-## Required Files
-
-- `feature_list.json`
-- `claude-progress.md`
-- `init.sh`
-- `session-handoff.md` when a compact handoff is useful
-
-## Completion Gate
-
-A feature can move to `passing` only after the required verification succeeds
-and the result is recorded.
-
-## Before You Stop
-
-1. Update the progress log.
-2. Update the feature state.
-3. Record what is still broken or unverified.
-4. Commit once the repository is safe to resume.
-5. Leave a clean restart path for the next session.
diff --git a/resources/en/templates/README.md b/resources/en/templates/README.md
deleted file mode 100644
index 797fa3c..0000000
--- a/resources/en/templates/README.md
+++ /dev/null
@@ -1,226 +0,0 @@
-# Template Guide
-
-These templates are ready to copy into your own project. Each one serves a specific purpose in the agent's workflow. Edit the contents to match your project's commands, paths, feature names, and verification steps.
-
-## How to Get Started
-
-Copy these four files into your project root first:
-
-1. `AGENTS.md` or `CLAUDE.md`
-2. `init.sh`
-3. `claude-progress.md`
-4. `feature_list.json`
-
-Add the remaining files as your project grows.
-
----
-
-## AGENTS.md
-
-The root instruction file. This is the first thing the agent reads when it starts a session. It defines the operating rules: what to do before writing code, how to work, and how to wrap up.
-
-**How to use it:**
-
-- Copy to your project root directory
-- Replace the startup workflow steps with your actual project paths and commands
-- Adjust the working rules to match your team's conventions
-- Keep the definition of done section — it's the most important part
-
-**What it does for the agent:**
-
-- Tells it to read progress and feature state before starting work
-- Forces it to work on one feature at a time
-- Requires evidence before marking anything as done
-- Defines what a clean end-of-session looks like
-
-Use `AGENTS.md` for Codex or other agents. Use `CLAUDE.md` if you're working with Claude Code — the structure is the same, just formatted for Claude's instruction style.
-
-## init.sh
-
-The startup script. Runs dependency installation, verification, and prints the start command — all in one shot.
-
-**How to use it:**
-
-- Copy to your project root
-- Edit these three variables at the top:
- - `INSTALL_CMD` — your dependency install command (e.g. `npm install`, `pip install -r requirements.txt`)
- - `VERIFY_CMD` — your basic verification command (e.g. `npm test`, `pytest`)
- - `START_CMD` — your dev server start command (e.g. `npm run dev`)
-- Make it executable: `chmod +x init.sh`
-
-**What it does:**
-
-1. Prints the current directory (so you can confirm it's running in the right place)
-2. Installs dependencies
-3. Runs the verification command
-4. Prints the start command (or runs it if `RUN_START_COMMAND=1` is set)
-
-If verification fails, the agent should stop and fix the baseline before doing anything else.
-
-## claude-progress.md
-
-The progress log. Every session writes to this file, and every new session reads it first.
-
-**How to use it:**
-
-- Copy to your project root
-- Fill in the "Current Verified State" section with your project's info
-- After each session, update the session record
-
-**What each field means:**
-
-- **Current Verified State** — the single source of truth for where the project stands
- - `Repository root directory` — where the project lives
- - `Standard startup path` — the command to get the project running
- - `Standard verification path` — the command to run tests
- - `Highest priority unfinished feature` — what the next session should work on
- - `Current blocker` — anything that's stuck
-- **Session Record** — one entry per session
- - `Goal` — what you planned to do
- - `Completed` — what actually got done
- - `Verification run` — what tests were executed
- - `Evidence recorded` — what proof was captured
- - `Commits` — what was committed
- - `Known risks` — what might be broken
- - `Next best action` — where the next session should start
-
-## feature_list.json
-
-The feature tracker. A machine-readable list of every feature the agent needs to implement, along with its status, verification steps, and evidence.
-
-**How to use it:**
-
-- Copy to your project root
-- Replace the example features with your own
-- Each feature needs:
- - `id` — a short unique identifier
- - `priority` — integer, lower = higher priority
- - `area` — which part of the app (e.g. "chat", "import", "search")
- - `title` — short description
- - `user_visible_behavior` — what the user should see when it works
- - `status` — one of `not_started`, `in_progress`, `blocked`, `passing`
- - `verification` — step-by-step instructions to confirm it works
- - `evidence` — recorded proof that verification passed (filled in by the agent)
- - `notes` — any extra context
-
-**Status rules:**
-
-- `not_started` — hasn't been touched
-- `in_progress` — the one feature currently being worked on (only one at a time)
-- `blocked` — can't proceed due to a documented issue
-- `passing` — verification passed and evidence is recorded
-
-The agent should only have one feature in `in_progress` at any time.
-
-## session-handoff.md
-
-A compact handoff note between sessions. Use this when a session ends and you want the next one to pick up quickly.
-
-**How to use it:**
-
-- Copy to your project root
-- Fill it out at the end of each session (or have the agent fill it out)
-
-**What each section covers:**
-
-- **Currently verified** — what's confirmed working and what verification was run
-- **Changes this session** — what code or infrastructure changed
-- **Still broken or unverified** — known issues and risky areas
-- **Next best action** — what the next session should do, and what not to touch
-- **Commands** — startup, verification, and debug commands for quick reference
-
-This file is optional for small sessions. It becomes important when sessions are long or when the project has multiple active areas.
-
-## clean-state-checklist.md
-
-A checklist to run through before ending each session. Makes sure the repo is in a good state for the next session to start cleanly.
-
-**How to use it:**
-
-- Copy to your project root
-- Run through it before you close a session
-- The agent should also check these items as part of its end-of-session routine
-
-**What it checks:**
-
-- Standard startup still works
-- Standard verification still runs
-- Progress log is updated
-- Feature list reflects actual state (no false `passing` entries)
-- No half-finished work left unrecorded
-- Next session can continue without manual fixes
-
-## evaluator-rubric.md
-
-A scorecard for reviewing agent output quality. Use this after a session or at project milestones to evaluate whether the work meets the bar.
-
-**How to use it:**
-
-- Copy to your project root
-- After a session (or a set of sessions), score the agent's work across six dimensions
-- Each dimension is scored 0-2
-
-**The six dimensions:**
-
-1. **Correctness** — does the implementation match the target behavior?
-2. **Verification** — were the required checks actually run, with evidence?
-3. **Scope discipline** — did the agent stay within the selected feature?
-4. **Reliability** — does the result survive a restart or re-run?
-5. **Maintainability** — is the code and documentation clear enough for the next session?
-6. **Handoff readiness** — can a new session continue using only repo artifacts?
-
-**Conclusion options:**
-
-- Accept — meets the bar
-- Revise — needs fixes before accepting
-- Block — fundamental issues that need to be resolved first
-
-**Important: the evaluator needs tuning.** Out of the box, agents are poor self-judges — they identify issues then talk themselves into approving. You will need to iterate:
-
-1. Run the evaluator on a completed sprint.
-2. Compare its scores against your own human judgment.
-3. Where they diverge, make the rubric more specific about pass/fail criteria.
-4. Re-run and check alignment.
-5. Repeat until the evaluator consistently matches human review.
-
-Plan for 3-5 tuning rounds. Record each change so you can track what improved alignment.
-
-## quality-document.md
-
-A quality snapshot that grades each product domain and architectural layer in your project. Tracks codebase health over time, not just individual session output.
-
-**How to use it:**
-
-- Copy to your project root
-- Before starting a session: read it to understand where the codebase is weakest
-- After a session: update grades based on what changed
-- Over time: compare snapshots to see which harness changes actually improved codebase health
-
-**What it grades:**
-
-- **Product domains** (e.g., document import, Q&A flow, indexing): each domain gets a grade (A-D) across verification status, agent legibility, test stability, and key gaps
-- **Architectural layers** (e.g., main process, preload, renderer, services): each layer gets a grade for boundary enforcement and agent legibility
-
-**Why it matters:**
-
-The evaluator rubric scores individual agent outputs. The quality document scores the codebase itself. They answer different questions:
-
-- Evaluator rubric: "Did the agent do good work this session?"
-- Quality document: "Is the project getting stronger or weaker over time?"
-
-**When to update:**
-
-- After each significant session
-- Before benchmark comparisons
-- After cleanup or simplification passes
-- When onboarding a new agent or model to the project
-
-**Harness simplification tie-in:**
-
-The quality document also supports harness simplification. Every harness component encodes an assumption about what the model cannot do. As models improve, these assumptions go stale. To check whether a component is still needed:
-
-1. Take a quality document snapshot.
-2. Remove one harness component.
-3. Run the benchmark task suite.
-4. Take another snapshot.
-5. Compare — if grades didn't drop, the component was overhead. If they did, restore it.
diff --git a/resources/en/templates/claude-progress.md b/resources/en/templates/claude-progress.md
deleted file mode 100644
index c6a0a7b..0000000
--- a/resources/en/templates/claude-progress.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Progress Log
-
-## Current Verified State
-
-- 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:
diff --git a/resources/en/templates/clean-state-checklist.md b/resources/en/templates/clean-state-checklist.md
deleted file mode 100644
index 5aa8d51..0000000
--- a/resources/en/templates/clean-state-checklist.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Clean State Checklist
-
-- [ ] The standard startup path still works.
-- [ ] The standard verification path still runs.
-- [ ] Current progress is recorded in the progress log.
-- [ ] Feature state reflects what is actually passing versus unverified.
-- [ ] No half-finished step is left undocumented.
-- [ ] The next session can continue without manual repair.
diff --git a/resources/en/templates/evaluator-rubric.md b/resources/en/templates/evaluator-rubric.md
deleted file mode 100644
index b1eb57e..0000000
--- a/resources/en/templates/evaluator-rubric.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Evaluator Rubric
-
-Use this rubric after implementation and before final acceptance.
-
-| Category | Question | Score (0-2) | Notes |
-| --- | --- | --- | --- |
-| Correctness | Does the implemented behavior match the requested feature? | | |
-| Verification | Did the required checks actually run, with evidence? | | |
-| Scope discipline | Did the session stay inside the chosen feature scope? | | |
-| Reliability | Does the result survive restart or rerun without repair? | | |
-| Maintainability | Is the code and documentation clear enough for the next session? | | |
-| Handoff readiness | Can a fresh session continue work from repo artifacts only? | | |
-
-## Verdict
-
-- Accept
-- Revise
-- Block
-
-## Required Follow-Up
-
-- Missing evidence:
-- Required fixes:
-- Next review trigger:
diff --git a/resources/en/templates/feature_list.json b/resources/en/templates/feature_list.json
deleted file mode 100644
index 138adc6..0000000
--- a/resources/en/templates/feature_list.json
+++ /dev/null
@@ -1,64 +0,0 @@
-{
- "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/resources/en/templates/init.sh b/resources/en/templates/init.sh
deleted file mode 100755
index d7522d6..0000000
--- a/resources/en/templates/init.sh
+++ /dev/null
@@ -1,29 +0,0 @@
-#!/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/resources/en/templates/quality-document.md b/resources/en/templates/quality-document.md
deleted file mode 100644
index fb8699b..0000000
--- a/resources/en/templates/quality-document.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Quality Document
-
-A quality snapshot for each product domain and architectural layer. Both agents and humans can use this document to quickly understand where the codebase is strong and where it needs work.
-
-**Update cadence:** After each significant session, or before starting a new phase of work.
-
-**Grading scale:**
-
-- **A**: All verification passing, clean architecture, agent-legible, stable tests
-- **B**: Verification passing, mostly clean, minor gaps in legibility or test coverage
-- **C**: Partially working, known gaps, some code areas hard for agents to understand
-- **D**: Not working, or major structural issues
-
----
-
-## Product Domains
-
-| Domain | Grade | Verification | Agent Legibility | Test Stability | Key Gaps | Last Updated |
-|--------|-------|-------------|-----------------|---------------|----------|-------------|
-| Document Import | - | - | - | - | - | - |
-| Document Management | - | - | - | - | - | - |
-| Document Indexing | - | - | - | - | - | - |
-| Q&A Flow | - | - | - | - | - | - |
-| Grounded Answers | - | - | - | - | - | - |
-
-## Architectural Layers
-
-| Layer | Grade | Boundary Enforcement | Agent Legibility | Key Gaps | Last Updated |
-|-------|-------|---------------------|-----------------|----------|-------------|
-| Main Process | - | - | - | - | - |
-| Preload | - | - | - | - | - |
-| Renderer | - | - | - | - | - |
-| Services | - | - | - | - | - |
-
-## Change History
-
-### YYYY-MM-DD
-
-- Changes:
-- Domains promoted:
-- Domoted:
-- New gaps identified:
-- Gaps closed:
diff --git a/resources/en/templates/session-handoff.md b/resources/en/templates/session-handoff.md
deleted file mode 100644
index c37cf46..0000000
--- a/resources/en/templates/session-handoff.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Session Handoff
-
-## Verified Now
-
-- What is currently working:
-- What verification actually ran:
-
-## Changed This Session
-
-- Code or behavior added:
-- Infrastructure or harness changes:
-
-## Broken Or Unverified
-
-- Known defect:
-- Unverified path:
-- Risk for the next session:
-
-## Next Best Step
-
-- Highest-priority unfinished feature:
-- Why it is next:
-- What counts as passing:
-- What must not change during that step:
-
-## Commands
-
-- Startup:
-- Verification:
-- Focused debug command:
diff --git a/resources/zh/README.md b/resources/zh/README.md
deleted file mode 100644
index 61fa0e7..0000000
--- a/resources/zh/README.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# 中文资料库
-
-这个文件夹把课程里的方法整理成可以直接参考和复用的材料,不是再讲一遍概念,而是尽量回答两个问题:
-
-- 我现在应该先抄哪些文件
-- 这些文件分别解决什么问题
-
-## 适合什么时候用
-
-当你准备让 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)
-- 启动脚本参考:`resources/zh/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)
-
-## 资料库结构
-
-- [`templates/`](./templates/README.md):可以直接复制到真实仓库里的模板
-- [`reference/`](./reference/README.md):方法说明、启动流程和问题对照表
-
-## 推荐最小组合
-
-- `AGENTS.md` 或 `CLAUDE.md`
-- `feature_list.json`
-- `claude-progress.md`
-- `init.sh`
-
-先把这四样放进项目里,再开始让 agent 持续工作,通常就已经能明显降低返工和瞎猜。
diff --git a/resources/zh/reference/README.md b/resources/zh/reference/README.md
deleted file mode 100644
index 1b1643c..0000000
--- a/resources/zh/reference/README.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# 中文参考
-
-这一部分解释这些模板该怎么配合使用,而不是把它们当成一堆孤立文件。
-
-## 参考材料
-
-- [`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):根指令应该写到什么程度才合适
-
-## 推荐阅读顺序
-
-1. `method-map.md`
-2. `initializer-agent-playbook.md`
-3. `coding-agent-startup-flow.md`
-4. `prompt-calibration.md`
diff --git a/resources/zh/reference/coding-agent-startup-flow.md b/resources/zh/reference/coding-agent-startup-flow.md
deleted file mode 100644
index 1d74379..0000000
--- a/resources/zh/reference/coding-agent-startup-flow.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# 编码代理开工流程
-
-初始化完成后,每轮编码会话都按这个流程开始。
-
-## 固定开工模板
-
-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/resources/zh/reference/initializer-agent-playbook.md b/resources/zh/reference/initializer-agent-playbook.md
deleted file mode 100644
index 10c4ad6..0000000
--- a/resources/zh/reference/initializer-agent-playbook.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# 初始化代理操作手册
-
-这个手册用于仓库里的第一轮重要会话,也就是正式开始增量开发之前的初始化阶段。
-
-## 目标
-
-先搭出稳定的工作面,让后续会话不必重新推导启动命令、当前状态和任务边界。
-
-## 必需产出
-
-初始化阶段至少应该留下这些工件:
-
-- 一个根指令文件,例如 `AGENTS.md` 或 `CLAUDE.md`
-- 一个机器可读的功能面,例如 `feature_list.json`
-- 一个持久进度工件,例如 `claude-progress.md`
-- 一个标准启动辅助脚本,例如 `init.sh`
-- 一个记录基础脚手架状态的初始安全提交
-
-## 检查清单
-
-1. 定义标准启动路径
-2. 定义标准验证路径
-3. 建立进度日志并写下初始状态
-4. 把工作拆成功能,并给出状态字段
-5. 建立第一个干净的 baseline commit
-
-## 成功标准
-
-一个完全没有前文聊天上下文的新会话,应该能回答:
-
-- 这个仓库是做什么的
-- 怎么启动
-- 怎么验证
-- 还有什么没做完
-- 下一步最佳动作是什么
diff --git a/resources/zh/reference/method-map.md b/resources/zh/reference/method-map.md
deleted file mode 100644
index e2f54ec..0000000
--- a/resources/zh/reference/method-map.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# 方法对照表
-
-这个表把最常见的长时 coding-agent 失败模式,对应到最先该补的工件或规则。
-
-| 失败模式 | 实际表现 | 首要修复 | 主要工件 |
-| --- | --- | --- | --- |
-| 冷启动混乱 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为 system of record | `claude-progress.md` |
-| 范围蔓延 | 一次启动多个功能,最后没有一个完整收尾 | 限制 active scope | `feature_list.json` |
-| 提前宣布完成 | 代码改了就说 done,但没有可运行证据 | 把完成绑定到验证证据 | `clean-state-checklist.md` |
-| 启动脆弱 | 每轮会话都要重新学怎么启动项目 | 统一启动与验证路径 | `init.sh` |
-| 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 明确写交接摘要 | `session-handoff.md` |
-| 评审主观 | 质量判断依赖个人记忆和感觉 | 用固定维度做评分 | `evaluator-rubric.md` |
-
-## 使用原则
-
-优先补最能直接消除当前失败模式的那个工件,不要一出问题就把更多规则堆进一个超长 instruction 文件里。
diff --git a/resources/zh/reference/prompt-calibration.md b/resources/zh/reference/prompt-calibration.md
deleted file mode 100644
index f89002c..0000000
--- a/resources/zh/reference/prompt-calibration.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Prompt 校准
-
-根指令文件应该定义工作框架,而不是把所有动作写死。
-
-## 应该留在根文件里的内容
-
-- 仓库用途和范围
-- 启动路径
-- 验证路径
-- 不可违反的约束
-- 必需的状态工件
-- 会话结束规则
-
-## 应该移出根文件的内容
-
-- 过长的历史边角案例
-- 只属于某个子系统的细节实现说明
-- 更适合贴在代码附近的局部架构笔记
-- 只对单一模块成立的示例
-
-## 工作原则
-
-根文件的职责是让新会话快速建立方向感。如果它开始变成“过去每次失败都往里加一句”的堆叠场,就应该把细节拆到更小、更明确的文档里,再从根文件跳转过去。
diff --git a/resources/zh/templates/AGENTS.md b/resources/zh/templates/AGENTS.md
deleted file mode 100644
index 66d84dc..0000000
--- a/resources/zh/templates/AGENTS.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# 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/resources/zh/templates/CLAUDE.md b/resources/zh/templates/CLAUDE.md
deleted file mode 100644
index 8d0bc63..0000000
--- a/resources/zh/templates/CLAUDE.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# 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
-- 没有可运行证据时,不要声称完成
-- 不要通过重写功能清单来隐藏未完成工作
-- 不要为了“看起来完成”而删除或削弱测试
-- 以仓库内文件作为 system of record
-
-## 必需文件
-
-- `feature_list.json`
-- `claude-progress.md`
-- `init.sh`
-- 需要简短交接时使用 `session-handoff.md`
-
-## 完成门槛
-
-只有在要求的验证成功且结果被记录后,功能状态才可以切换到 `passing`。
-
-## 结束前
-
-1. 更新进度日志
-2. 更新功能状态
-3. 记录仍然损坏或未验证的内容
-4. 在仓库可安全恢复后提交
-5. 给下一轮会话留下干净的重启路径
diff --git a/resources/zh/templates/README.md b/resources/zh/templates/README.md
deleted file mode 100644
index 9395970..0000000
--- a/resources/zh/templates/README.md
+++ /dev/null
@@ -1,226 +0,0 @@
-# 模板使用指南
-
-这些模板可以直接复制到你的项目里用。每个文件在 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/resources/zh/templates/claude-progress.md b/resources/zh/templates/claude-progress.md
deleted file mode 100644
index 8ee42ee..0000000
--- a/resources/zh/templates/claude-progress.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# 进度日志
-
-## 当前已验证状态
-
-- 仓库根目录:
-- 标准启动路径:
-- 标准验证路径:
-- 当前最高优先级未完成功能:
-- 当前 blocker:
-
-## 会话记录
-
-### Session 001
-
-- 日期:
-- 本轮目标:
-- 已完成:
-- 运行过的验证:
-- 已记录证据:
-- 提交记录:
-- 更新过的文件或工件:
-- 已知风险或未解决问题:
-- 下一步最佳动作:
-
-### Session 002
-
-- 日期:
-- 本轮目标:
-- 已完成:
-- 运行过的验证:
-- 已记录证据:
-- 提交记录:
-- 更新过的文件或工件:
-- 已知风险或未解决问题:
-- 下一步最佳动作:
diff --git a/resources/zh/templates/clean-state-checklist.md b/resources/zh/templates/clean-state-checklist.md
deleted file mode 100644
index 6a2717d..0000000
--- a/resources/zh/templates/clean-state-checklist.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# 干净状态检查清单
-
-- [ ] 标准启动路径仍然可用
-- [ ] 标准验证路径仍然可运行
-- [ ] 当前进度已经记录到进度日志
-- [ ] 功能状态真实反映了 passing 和未验证的边界
-- [ ] 没有任何半成品步骤处于未记录状态
-- [ ] 下一轮会话无需人工修复即可继续
diff --git a/resources/zh/templates/evaluator-rubric.md b/resources/zh/templates/evaluator-rubric.md
deleted file mode 100644
index cedc842..0000000
--- a/resources/zh/templates/evaluator-rubric.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# 评审评分表
-
-在实现完成后、正式验收前,用这张表做一次评审。
-
-| 维度 | 问题 | 分数 (0-2) | 备注 |
-| --- | --- | --- | --- |
-| 正确性 | 实现出来的行为是否符合目标功能? | | |
-| 验证 | 要求的检查是否真的跑过,并留下证据? | | |
-| 范围纪律 | 这一轮是否基本保持在选定功能范围内? | | |
-| 可靠性 | 结果是否能在重启或重跑后继续工作? | | |
-| 可维护性 | 代码和文档是否清楚到足以交给下一轮会话? | | |
-| 交接准备度 | 新会话是否能只靠仓库内工件继续推进? | | |
-
-## 结论
-
-- Accept
-- Revise
-- Block
-
-## 后续动作
-
-- 缺失的证据:
-- 必须补的修复:
-- 下次复审触发条件:
diff --git a/resources/zh/templates/feature_list.json b/resources/zh/templates/feature_list.json
deleted file mode 100644
index 41b9753..0000000
--- a/resources/zh/templates/feature_list.json
+++ /dev/null
@@ -1,64 +0,0 @@
-{
- "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/resources/zh/templates/init.sh b/resources/zh/templates/init.sh
deleted file mode 100755
index c153b2a..0000000
--- a/resources/zh/templates/init.sh
+++ /dev/null
@@ -1,29 +0,0 @@
-#!/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/resources/zh/templates/quality-document.md b/resources/zh/templates/quality-document.md
deleted file mode 100644
index a21367b..0000000
--- a/resources/zh/templates/quality-document.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# 质量文档
-
-每个产品领域和架构层的质量快照。agent 和人都能通过这份文档快速了解项目哪里强、哪里弱。
-
-**更新时机:** 每轮重要会话结束后,或开始新一阶段工作前。
-
-**评级标准:**
-
-- **A**:验证全部通过,架构干净,agent 能读懂,测试稳定
-- **B**:验证通过,基本干净,可读性或测试覆盖有少量缺口
-- **C**:部分可用,有已知缺口,部分代码 agent 不容易理解
-- **D**:不可用,或存在重大结构问题
-
----
-
-## 产品领域
-
-| 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 |
-|------|------|---------|-------------|-----------|---------|---------|
-| 文档导入 | - | - | - | - | - | - |
-| 文档管理 | - | - | - | - | - | - |
-| 文档索引 | - | - | - | - | - | - |
-| 问答流程 | - | - | - | - | - | - |
-| 引用式回答 | - | - | - | - | - | - |
-
-## 架构层
-
-| 层级 | 评级 | 边界执行 | Agent 可读性 | 关键缺口 | 上次更新 |
-|------|------|---------|-------------|---------|---------|
-| Main Process | - | - | - | - | - |
-| Preload | - | - | - | - | - |
-| Renderer | - | - | - | - | - |
-| Services | - | - | - | - | - |
-
-## 变更历史
-
-### YYYY-MM-DD
-
-- 变更内容:
-- 提升:
-- 下降:
-- 新发现的缺口:
-- 已关闭的缺口:
diff --git a/resources/zh/templates/session-handoff.md b/resources/zh/templates/session-handoff.md
deleted file mode 100644
index a24fc89..0000000
--- a/resources/zh/templates/session-handoff.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# 会话交接
-
-## 当前已验证
-
-- 现在明确可用的部分:
-- 这轮实际跑过的验证:
-
-## 本轮改动
-
-- 新增了哪些代码或行为:
-- 基础设施或 harness 发生了哪些变化:
-
-## 仍损坏或未验证
-
-- 已知缺陷:
-- 未验证路径:
-- 下一轮会话需要注意的风险:
-
-## 下一步最佳动作
-
-- 最高优先级未完成功能:
-- 为什么它是下一步:
-- 什么结果才算 passing:
-- 这一步中哪些东西不要动:
-
-## 命令
-
-- 启动命令:
-- 验证命令:
-- 定向调试命令: