Skip to content

Harness engineering beginner tutorial, from 0 to 1

Improve Mermaid diagrams and viewer UX

sanbuphyfbc6d1f60e65
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index d1bbe8c..b93a14b 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -104,7 +104,13 @@ export default withMermaid(
primaryBorderColor: '#D1D1D1',
primaryTextColor: '#1A1A1A',
lineColor: '#B3B3B3',
- fontFamily: 'Inter, sans-serif'
+ fontFamily: 'Inter, sans-serif',
+ fontSize: '18px'
+ },
+ flowchart: {
+ nodeSpacing: 40,
+ rankSpacing: 56,
+ padding: 12
}
},
locales: {
diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js
index 6255b5f..7aa0a61 100644
--- a/docs/.vitepress/theme/index.js
+++ b/docs/.vitepress/theme/index.js
@@ -2,6 +2,16 @@ import DefaultTheme from 'vitepress/theme'
import './style.css'
let rootEnglishLabel = 'English'
+let mermaidViewer
+let mermaidViewerBody
+let mermaidViewerStage
+let mermaidObserver
+let mermaidViewerUrl
+let mermaidViewerImage
+let mermaidViewerNaturalWidth = 0
+let mermaidViewerNaturalHeight = 0
+let mermaidViewerFitScale = 1
+let mermaidViewerScale = 1
function dedupeLocaleMenuLinks() {
if (typeof document === 'undefined') return
@@ -60,16 +70,257 @@ function syncRootLocaleLabel(siteData, href = '') {
locales.root.label = relative.startsWith('/zh/') ? locales.zh.label : rootEnglishLabel
}
+function ensureMermaidViewer() {
+ if (typeof document === 'undefined') return
+ if (mermaidViewer && mermaidViewerBody && mermaidViewerStage) return
+
+ mermaidViewer = document.createElement('div')
+ mermaidViewer.className = 'mermaid-viewer'
+ mermaidViewer.innerHTML = `
+ <div class="mermaid-viewer__backdrop" data-mermaid-close="true"></div>
+ <div class="mermaid-viewer__panel" role="dialog" aria-modal="true" aria-label="Expanded Mermaid diagram">
+ <div class="mermaid-viewer__toolbar">
+ <button type="button" class="mermaid-viewer__tool" aria-label="Zoom out" data-mermaid-action="zoom-out">−</button>
+ <button type="button" class="mermaid-viewer__tool mermaid-viewer__tool--label" aria-label="Reset zoom" data-mermaid-action="reset">100%</button>
+ <button type="button" class="mermaid-viewer__tool" aria-label="Zoom in" data-mermaid-action="zoom-in">+</button>
+ <button type="button" class="mermaid-viewer__close" aria-label="Close diagram" data-mermaid-close="true">×</button>
+ </div>
+ <div class="mermaid-viewer__body">
+ <div class="mermaid-viewer__stage"></div>
+ </div>
+ </div>
+ `
+
+ mermaidViewerBody = mermaidViewer.querySelector('.mermaid-viewer__body')
+ mermaidViewerStage = mermaidViewer.querySelector('.mermaid-viewer__stage')
+
+ mermaidViewer.addEventListener('click', (event) => {
+ const target = event.target
+ if (!(target instanceof HTMLElement)) return
+
+ if (
+ target.dataset.mermaidClose === 'true' ||
+ target === mermaidViewerBody ||
+ target === mermaidViewerStage
+ ) {
+ closeMermaidViewer()
+ return
+ }
+
+ const action = target.dataset.mermaidAction
+ if (action === 'zoom-in') {
+ setMermaidViewerScale(mermaidViewerScale + 0.2)
+ } else if (action === 'zoom-out') {
+ setMermaidViewerScale(mermaidViewerScale - 0.2)
+ } else if (action === 'reset') {
+ setMermaidViewerScale(1)
+ }
+ })
+
+ document.addEventListener('keydown', (event) => {
+ if (event.key === 'Escape' && mermaidViewer?.classList.contains('is-open')) {
+ closeMermaidViewer()
+ } else if ((event.key === '+' || event.key === '=') && mermaidViewer?.classList.contains('is-open')) {
+ setMermaidViewerScale(mermaidViewerScale + 0.2)
+ } else if (event.key === '-' && mermaidViewer?.classList.contains('is-open')) {
+ setMermaidViewerScale(mermaidViewerScale - 0.2)
+ }
+ })
+
+ mermaidViewerBody?.addEventListener('wheel', (event) => {
+ if (!mermaidViewer?.classList.contains('is-open')) return
+ event.preventDefault()
+ const delta = event.deltaY < 0 ? 0.12 : -0.12
+ setMermaidViewerScale(mermaidViewerScale + delta)
+ }, { passive: false })
+
+ window.addEventListener('resize', () => {
+ if (mermaidViewer?.classList.contains('is-open')) {
+ updateMermaidViewerFitScale()
+ setMermaidViewerScale(mermaidViewerScale)
+ }
+ })
+
+ document.body.appendChild(mermaidViewer)
+}
+
+function serializeMermaidSvg(svg) {
+ const clone = svg.cloneNode(true)
+ if (!(clone instanceof SVGElement)) return null
+
+ if (!clone.getAttribute('xmlns')) {
+ clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg')
+ }
+ if (!clone.getAttribute('xmlns:xlink')) {
+ clone.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink')
+ }
+
+ const rect = svg.getBoundingClientRect()
+ const viewBox = svg.viewBox?.baseVal
+ const rawWidth = rect.width || viewBox?.width || Number.parseFloat(svg.getAttribute('width') || '') || 1200
+ const rawHeight = rect.height || viewBox?.height || Number.parseFloat(svg.getAttribute('height') || '') || 800
+
+ if (!clone.getAttribute('viewBox')) {
+ clone.setAttribute('viewBox', `0 0 ${Math.max(1, Math.round(rawWidth))} ${Math.max(1, Math.round(rawHeight))}`)
+ }
+
+ clone.setAttribute('width', String(Math.max(1, Math.round(rawWidth))))
+ clone.setAttribute('height', String(Math.max(1, Math.round(rawHeight))))
+
+ return {
+ markup: new XMLSerializer().serializeToString(clone),
+ width: Math.max(1, rawWidth),
+ height: Math.max(1, rawHeight)
+ }
+}
+
+function updateMermaidViewerFitScale() {
+ if (!mermaidViewerNaturalWidth || !mermaidViewerNaturalHeight || typeof window === 'undefined') return
+
+ const maxWidth = Math.max(320, window.innerWidth - 16)
+ const maxHeight = Math.max(240, window.innerHeight - 16)
+ mermaidViewerFitScale = Math.max(
+ 0.25,
+ Math.min(maxWidth / mermaidViewerNaturalWidth, maxHeight / mermaidViewerNaturalHeight)
+ )
+}
+
+function setMermaidViewerScale(nextScale) {
+ if (!mermaidViewerStage || !mermaidViewerNaturalWidth || !mermaidViewerNaturalHeight) return
+
+ mermaidViewerScale = Math.max(0.5, Math.min(nextScale, 4))
+
+ const width = mermaidViewerNaturalWidth * mermaidViewerFitScale * mermaidViewerScale
+ const height = mermaidViewerNaturalHeight * mermaidViewerFitScale * mermaidViewerScale
+
+ mermaidViewerStage.style.width = `${width}px`
+ mermaidViewerStage.style.height = `${height}px`
+
+ const resetButton = mermaidViewer?.querySelector('[data-mermaid-action="reset"]')
+ if (resetButton instanceof HTMLElement) {
+ resetButton.textContent = `${Math.round(mermaidViewerScale * 100)}%`
+ }
+}
+
+function openMermaidViewer(diagram) {
+ ensureMermaidViewer()
+ if (!mermaidViewerBody || !mermaidViewer || !mermaidViewerStage) return
+
+ const svg = diagram.querySelector('svg')
+ if (!svg) return
+
+ if (mermaidViewerUrl) {
+ URL.revokeObjectURL(mermaidViewerUrl)
+ mermaidViewerUrl = undefined
+ }
+
+ const serialized = serializeMermaidSvg(svg)
+ if (!serialized) return
+
+ const blob = new Blob([serialized.markup], { type: 'image/svg+xml;charset=utf-8' })
+ mermaidViewerUrl = URL.createObjectURL(blob)
+
+ const image = document.createElement('img')
+ image.className = 'mermaid-viewer__image'
+ image.alt = 'Expanded Mermaid diagram'
+ image.src = mermaidViewerUrl
+ image.addEventListener('load', () => {
+ mermaidViewerNaturalWidth = serialized.width
+ mermaidViewerNaturalHeight = serialized.height
+ updateMermaidViewerFitScale()
+ setMermaidViewerScale(1)
+ if (mermaidViewerBody) {
+ mermaidViewerBody.scrollTo({ top: 0, left: 0 })
+ }
+ })
+
+ mermaidViewerImage = image
+ mermaidViewerStage.replaceChildren(image)
+ mermaidViewer.classList.add('is-open')
+ document.documentElement.classList.add('has-mermaid-viewer')
+}
+
+function closeMermaidViewer() {
+ if (!mermaidViewer || !mermaidViewerBody || !mermaidViewerStage) return
+ mermaidViewer.classList.remove('is-open')
+ mermaidViewerStage.replaceChildren()
+ mermaidViewerStage.style.width = ''
+ mermaidViewerStage.style.height = ''
+ if (mermaidViewerUrl) {
+ URL.revokeObjectURL(mermaidViewerUrl)
+ mermaidViewerUrl = undefined
+ }
+ mermaidViewerImage = undefined
+ mermaidViewerNaturalWidth = 0
+ mermaidViewerNaturalHeight = 0
+ mermaidViewerFitScale = 1
+ mermaidViewerScale = 1
+ document.documentElement.classList.remove('has-mermaid-viewer')
+}
+
+function bindMermaidZoomables(root = document) {
+ if (typeof document === 'undefined') return
+ ensureMermaidViewer()
+
+ const diagrams = root.querySelectorAll('.vp-doc .mermaid')
+ for (const diagram of diagrams) {
+ if (!(diagram instanceof HTMLElement) || diagram.dataset.mermaidZoomBound === 'true') {
+ continue
+ }
+
+ diagram.dataset.mermaidZoomBound = 'true'
+ diagram.tabIndex = 0
+ diagram.setAttribute('role', 'button')
+ diagram.setAttribute('aria-label', 'Open Mermaid diagram in fullscreen')
+
+ diagram.addEventListener('click', () => {
+ openMermaidViewer(diagram)
+ })
+
+ diagram.addEventListener('keydown', (event) => {
+ if (event.key === 'Enter' || event.key === ' ') {
+ event.preventDefault()
+ openMermaidViewer(diagram)
+ }
+ })
+ }
+}
+
+function queueMermaidBinding() {
+ if (typeof window === 'undefined') return
+ window.requestAnimationFrame(() => {
+ window.requestAnimationFrame(() => {
+ bindMermaidZoomables()
+ })
+ })
+}
+
+function ensureMermaidObserver() {
+ if (typeof document === 'undefined' || mermaidObserver) return
+ mermaidObserver = new MutationObserver(() => {
+ bindMermaidZoomables()
+ })
+
+ mermaidObserver.observe(document.body, {
+ childList: true,
+ subtree: true
+ })
+}
+
export default {
extends: DefaultTheme,
enhanceApp(ctx) {
syncRootLocaleLabel(ctx.siteData)
queueLocaleMenuDedupe()
+ queueMermaidBinding()
+ ensureMermaidObserver()
const previous = ctx.router.onAfterRouteChange
ctx.router.onAfterRouteChange = async (to) => {
syncRootLocaleLabel(ctx.siteData, to)
queueLocaleMenuDedupe()
+ closeMermaidViewer()
+ queueMermaidBinding()
if (previous) {
await previous(to)
}
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
index d897c80..ebbd146 100644
--- a/docs/.vitepress/theme/style.css
+++ b/docs/.vitepress/theme/style.css
@@ -530,15 +530,216 @@
}
/* ---------- Mermaid Charts styling overrides ---------- */
-.mermaid {
- background-color: var(--vp-c-bg-elv);
- border: 1px solid var(--vp-c-divider);
- border-radius: 12px;
- padding: 16px;
- margin: 16px 0;
+.vp-doc .mermaid {
+ background: transparent;
+ border: 0;
+ border-radius: 0;
+ padding: 12px 0;
+ margin: 20px 0;
display: flex;
justify-content: center;
+ overflow-x: auto;
+ overflow-y: visible;
+ -webkit-overflow-scrolling: touch;
+ cursor: zoom-in;
+ position: relative;
+}
+
+.vp-doc .mermaid svg {
+ display: block;
+ width: clamp(780px, 100%, 1040px) !important;
+ max-width: none !important;
+ min-width: 780px;
+ height: auto !important;
+ margin: 0 auto;
+}
+
+.vp-doc .mermaid .label,
+.vp-doc .mermaid .nodeLabel,
+.vp-doc .mermaid .edgeLabel {
+ font-size: 18px !important;
+}
+
+.vp-doc .mermaid::after {
+ content: 'Click to expand';
+ position: absolute;
+ top: 0;
+ right: 0;
+ padding: 4px 8px;
+ border-radius: 999px;
+ background: rgba(0, 0, 0, 0.05);
+ color: var(--vp-c-text-2);
+ font-size: 12px;
+ font-weight: 600;
+ letter-spacing: 0.01em;
+ opacity: 0;
+ transition: opacity 0.2s ease;
+ pointer-events: none;
+}
+
+.vp-doc .mermaid:hover::after,
+.vp-doc .mermaid:focus-visible::after {
+ opacity: 1;
+}
+
+html:lang(zh-CN) .vp-doc .mermaid::after {
+ content: '点击放大';
+}
+
+.vp-doc .mermaid:focus-visible {
+ outline: 2px solid var(--vp-c-brand-1);
+ outline-offset: 6px;
+}
+
+.dark .vp-doc .mermaid::after {
+ background: rgba(255, 255, 255, 0.08);
+}
+
+@media (max-width: 768px) {
+ .vp-doc .mermaid {
+ padding: 14px 10px;
+ }
+
+ .vp-doc .mermaid svg {
+ width: clamp(640px, 100%, 920px) !important;
+ min-width: 640px;
+ }
+
+ .vp-doc .mermaid .label,
+ .vp-doc .mermaid .nodeLabel,
+ .vp-doc .mermaid .edgeLabel {
+ font-size: 16px !important;
+ }
+
+ .vp-doc .mermaid::after {
+ content: 'Tap to expand';
+ opacity: 1;
+ top: 0;
+ right: 0;
+ }
+
+ html:lang(zh-CN) .vp-doc .mermaid::after {
+ content: '点击放大';
+ }
+}
+
+html.has-mermaid-viewer,
+html.has-mermaid-viewer body {
+ overflow: hidden;
+}
+
+.mermaid-viewer {
+ position: fixed;
+ inset: 0;
+ z-index: 100;
+ display: none;
+}
+
+.mermaid-viewer.is-open {
+ display: block;
}
+
+.mermaid-viewer__backdrop {
+ position: absolute;
+ inset: 0;
+ background: rgba(250, 249, 245, 0.96);
+}
+
+.mermaid-viewer__panel {
+ position: absolute;
+ inset: 0;
+ display: flex;
+ flex-direction: column;
+}
+
+.mermaid-viewer__toolbar {
+ position: absolute;
+ top: 12px;
+ right: 12px;
+ z-index: 2;
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+
+.mermaid-viewer__tool,
+.mermaid-viewer__close {
+ border: 0;
+ border-radius: 999px;
+ width: 40px;
+ height: 40px;
+ background: rgba(0, 0, 0, 0.06);
+ color: var(--vp-c-text-1);
+ font-size: 24px;
+ line-height: 1;
+ font-weight: 400;
+ cursor: pointer;
+}
+
+.mermaid-viewer__tool--label {
+ width: auto;
+ min-width: 72px;
+ padding: 0 14px;
+ font-size: 13px;
+ font-weight: 600;
+}
+
+.mermaid-viewer__body {
+ flex: 1;
+ overflow: auto;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ padding: 8px;
+ cursor: zoom-out;
+ background: #fff;
+}
+
+.mermaid-viewer__stage {
+ flex: 0 0 auto;
+ display: block;
+}
+
+.mermaid-viewer__image {
+ display: block;
+ width: 100%;
+ height: 100%;
+ margin: 0 auto;
+ background: transparent;
+ user-select: none;
+ -webkit-user-drag: none;
+ pointer-events: none;
+}
+
+@media (max-width: 768px) {
+ .mermaid-viewer__panel {
+ inset: 0;
+ }
+
+ .mermaid-viewer__toolbar {
+ top: 8px;
+ right: 8px;
+ gap: 6px;
+ }
+
+ .mermaid-viewer__tool,
+ .mermaid-viewer__close {
+ width: 36px;
+ height: 36px;
+ font-size: 20px;
+ }
+
+ .mermaid-viewer__tool--label {
+ min-width: 64px;
+ padding: 0 10px;
+ font-size: 12px;
+ }
+
+ .mermaid-viewer__body {
+ padding: 4px;
+ }
+}
+
.VPDoc .back-to-top-btn {
border-radius: 50%;
}
diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md
index 4cee78d..65e2f61 100644
--- a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md
+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -23,26 +23,21 @@ This isn't because the model isn't smart enough. It's because the working enviro
## Failure Model Overview
```mermaid
-graph LR
- subgraph "Five Failure Layers"
- direction TB
- L1["① Task Specification"]
- L2["② Context Provision"]
- L3["③ Execution Environment"]
- L4["④ Verification Feedback"]
- L5["⑤ State Management"]
- end
-
- Agent -->|"encounters"| L1
- L1 --> L2 --> L3 --> L4 --> L5
- L5 -->|"signals defect"| Fix["Fix layer → Re-run"]
- Fix -->|"diagnostic loop"| Agent
+flowchart TB
+ Spec["Task not specific<br/>'add search' can mean many things"] --> Fail["Result:<br/>agent writes code<br/>but work is unreliable"]
+ Context["Project rules missing<br/>agent cannot see them"] --> Fail
+ Env["Environment broken<br/>deps or commands fail"] --> Fail
+ Verify["No tests or check commands"] --> Fail
+ State["No progress file<br/>next session starts blind"] --> Fail
+ Fail --> Fix["Fix the broken layer,<br/>then rerun"]
```
```mermaid
-graph LR
- Bare["Bare Run<br/>20 min / $9<br/>Core features broken"] -->|"Add harness"| Full["Full Harness<br/>6 hr / $200<br/>Playable app"]
- Bare -.->|"Same model"| Full
+flowchart LR
+ Same["Same prompt<br/>same model"] --> Bare["Bare run<br/>20 min / $9<br/>core features broken"]
+ Same --> Full["Add planning, checks, and evaluation<br/>6 hr / $200<br/>playable app"]
+ Bare --> Lesson["Only the harness changed"]
+ Full --> Lesson
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md
index 3db3efe..268994a 100644
--- a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md
+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -23,16 +23,13 @@ This lecture gives you a precise, actionable definition. Not an academic abstrac
## The Five-Tuple Harness Model
```mermaid
-graph TB
- Agent["AI Agent"] --> I["📋 Instructions<br/><i>AGENTS.md, CLAUDE.md</i>"]
- Agent --> T["🔧 Tools<br/><i>Shell, file ops, tests</i>"]
- Agent --> E["🖥️ Environment<br/><i>Dependencies, runtime</i>"]
- Agent --> S["💾 State<br/><i>Progress files, git</i>"]
- Agent --> F["✅ Feedback<br/><i>Test results, lint, build</i>"]
-
- I ~~~ T ~~~ E ~~~ S ~~~ F
-
- F -->|"highest ROI"| Star["⭐ Start here"]
+flowchart LR
+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]
+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent
+ Agent --> Tools["Tools<br/>shell / files / tests"]
+ Tools --> Env["Runtime<br/>deps / services / versions"]
+ Env --> Checks["Check results<br/>test / lint / build"]
+ Checks --> Agent
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
index 1aa8644..c4080f6 100644
--- a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -23,34 +23,29 @@ This lecture explains why you must put everything an agent needs to know into th
## Knowledge Visibility
```mermaid
-graph LR
- subgraph "Visible to Agent"
- Repo["Repository Files<br/>AGENTS.md, code, tests"]
- end
- subgraph "Invisible to Agent"
- Slack["Slack History"]
- Confluence["Confluence Docs"]
- Heads["Senior Engineers' Heads"]
- Jira["Jira Tickets"]
- end
-
- Repo -->|"accessible"| Agent["🤖 Agent"]
- Slack -.->|"inaccessible"| Agent
- Confluence -.->|"inaccessible"| Agent
- Heads -.->|"inaccessible"| Agent
- Jira -.->|"inaccessible"| Agent
+flowchart LR
+ Slack["Rules in Slack"] --> Write["Write them into repo files<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]
+ Confluence["Rules in Confluence"] --> Write
+ Heads["Rules in people's heads"] --> Write
+ Jira["Rules in Jira tickets"] --> Write
+ Write --> Repo["Repository files"]
+ Repo --> Agent["New agent session<br/>reads the repo directly"]
+ Warning["If a rule is not in the repo,<br/>the agent cannot see it"] --> Agent
```
```mermaid
-graph TB
- subgraph "Cold-Start Test"
- Q1["What is this system?"]
- Q2["How is it organized?"]
- Q3["How do I run it?"]
- Q4["How do I verify it?"]
- Q5["Where are we now?"]
- end
- Q1 & Q2 & Q3 & Q4 & Q5 -->|"all must be<br/>answerable from repo"| Pass["✅ Harness Ready"]
+flowchart TB
+ Q1["What is this system?"] --> A1["AGENTS.md / README"]
+ Q2["How is it organized?"] --> A2["ARCHITECTURE.md / module docs"]
+ Q3["How do I run it?"] --> A3["Makefile / init.sh / package scripts"]
+ Q4["How do I verify it?"] --> A4["Test, lint, and check commands"]
+ Q5["Where are we now?"] --> A5["PROGRESS.md / feature list / git history"]
+
+ A1 --> Ready["A new session can start work<br/>without asking a human"]
+ A2 --> Ready
+ A3 --> Ready
+ A4 --> Ready
+ A5 --> Ready
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
index 9acf550..d00a8fe 100644
--- a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -23,26 +23,22 @@ This is the "giant instruction file" trap. This lecture explains why "more infor
## Instruction Architecture
```mermaid
-graph TB
- subgraph "Three-Layer Structure"
- L1["<b>Layer 1: Routing File</b><br/>AGENTS.md (50–200 lines)<br/>Overview + hard constraints + links"]
- L2a["<b>Layer 2a</b><br/>api-patterns.md"]
- L2b["<b>Layer 2b</b><br/>database-rules.md"]
- L2c["<b>Layer 2c</b><br/>testing-standards.md"]
- L3["<b>Layer 3: Inline</b><br/>Type defs, interface comments"]
- end
-
- L1 -->|"link"| L2a
- L1 -->|"link"| L2b
- L1 -->|"link"| L2c
- L2a & L2b & L2c -->|"reference"| L3
-
- style L1 fill:#D95C41,color:#fff
+flowchart LR
+ Mono["One 600-line AGENTS.md"] --> MonoLoad["Even a small bug fix<br/>must read deploy rules and old notes"]
+ MonoLoad --> MonoRisk["Important rules buried in the middle<br/>are easy to miss"]
+
+ Router["Short AGENTS.md"] --> Topics["Load API / DB / testing docs<br/>only when this task needs them"]
+ Topics --> RoutedResult["More context left for code reading<br/>and verification"]
```
```mermaid
-graph LR
- Top["Top of file<br/>✅ High recall"] --- Mid["Middle of file<br/>❌ Lost in the middle"] --- Bot["Bottom of file<br/>✅ High recall"]
+flowchart TB
+ File["600-line instruction file"] --> Top["Top section<br/>quick start + hard constraints"]
+ File --> Mid["Middle section<br/>critical security rule at line 300"]
+ File --> Bot["Bottom section<br/>explicit end-of-file checklist"]
+ Top --> Seen["High chance of recall"]
+ Bot --> Seen
+ Mid --> Missed["High chance of being diluted or missed"]
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 33e7b72..9086386 100644
--- a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -23,25 +23,26 @@ This is one of the most painful problems with AI coding agents: cross-session co
## Session Continuity Flow
```mermaid
-graph LR
- subgraph "Session N"
- Work1["Work on task"] --> Update1["Update PROGRESS.md<br/>Update DECISIONS.md"]
- Update1 --> Commit1["Git commit checkpoint"]
- end
- subgraph "Session N+1"
- Read1["Read PROGRESS.md<br/>Read DECISIONS.md"] --> Resume["Resume from<br/>Next Steps"]
- Resume --> Work2["Continue work"]
- end
-
- Commit1 -->|"handoff"| Read1
+flowchart LR
+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]
+ End1 --> S2["Session 2 starts fresh"]
+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]
+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]
```
```mermaid
-graph TB
- subgraph "Information Loss"
- Full["Full Context<br/>What + Why + How"] -->|"compaction"| Compact["Compacted<br/>What ✓ · Why ✗"]
- Full -->|"new session"| Reset["Reset<br/>Rebuild from artifacts"]
- end
+flowchart LR
+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]
+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]
+ Work --> Verify["Verification notes<br/>which tests pass and fail"]
+ Work --> Commit["Git checkpoint<br/>exact repo state"]
+
+ Progress --> Rebuild["Session 2 rebuild"]
+ Decisions --> Rebuild
+ Verify --> Rebuild
+ Commit --> Rebuild
+
+ Rebuild --> Resume["New session picks up quickly"]
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 1d8cd9a..de72054 100644
--- a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -23,24 +23,19 @@ The better approach: before letting the agent start working, use a separate phas
## Initialization Lifecycle
```mermaid
-graph LR
- subgraph "Initialization Phase"
- I1["Runnable environment<br/><i>deps installed</i>"] --> I2["Test framework<br/><i>example test passes</i>"]
- I2 --> I3["Bootstrap contract<br/><i>start/test/verify docs</i>"]
- I3 --> I4["Task breakdown<br/><i>ordered feature list</i>"]
- I4 --> I5["Git checkpoint<br/><i>clean commit</i>"]
- end
- subgraph "Implementation Phase"
- I5 --> P1["Session 2: Feature 1"]
- P1 --> P2["Session 3: Feature 2"]
- P2 --> P3["Session N: Feature N"]
+flowchart TB
+ subgraph Wrong["Mixed session (wrong)"]
+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]
+ W2 --> W3["Accumulate unverified code"]
+ W3 --> W4["Next session must rediscover project state"]
end
- style I1 fill:#D95C41,color:#fff
- style I2 fill:#D95C41,color:#fff
- style I3 fill:#D95C41,color:#fff
- style I4 fill:#D95C41,color:#fff
- style I5 fill:#D95C41,color:#fff
+ subgraph Right["Dedicated initialization (right)"]
+ R1["Session 1: environment runnable"] --> R2["Example test passing"]
+ R2 --> R3["Bootstrap contract + task list written"]
+ R3 --> R4["Clean checkpoint committed"]
+ R4 --> R5["Later sessions start directly on verified tasks"]
+ end
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 1515ff8..d178c5e 100644
--- a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -23,21 +23,23 @@ Anthropic's "Effective harnesses for long-running agents" engineering blog post
## WIP=1 Workflow
```mermaid
-graph LR
- subgraph "WIP = 1 (Correct)"
- Pick1["Pick feature"] --> Do1["Implement"] --> Verify1["Verify E2E"]
- Verify1 -->|"pass"| Commit1["Commit"]
- Commit1 --> Next1["Next feature"]
- Verify1 -->|"fail"| Do1
- end
+flowchart LR
+ Queue["Feature queue"] --> Pick["Pick exactly one task"]
+ Pick --> Active["Only one active item"]
+ Active --> Verify["Run end-to-end verification"]
+ Verify -->|pass| Commit["Commit and unlock next task"]
+ Verify -->|fail| Active
+ Commit --> Queue
```
```mermaid
-graph LR
- subgraph "Unconstrained (Wrong)"
- Pick2["Activate 5 features"] --> Do2["Work on all"]
- Do2 --> Result2["800 lines, 12 files<br/>20% pass rate ❌"]
- end
+flowchart TB
+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]
+ Budget --> Many["WIP = 5<br/>C / 5 per task"]
+
+ One --> Finish["One feature reaches passing state"]
+ Many --> Partial["Five partial implementations"]
+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 21f7eef..bdeb9e2 100644
--- a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -23,26 +23,26 @@ Feature lists are not planning documents for humans to read. They are the core d
## Feature State Machine
```mermaid
-stateDiagram-v2
- [*] --> not_started
- not_started --> active: Agent picks task
- active --> passing: Verification command passes
- active --> blocked: External dependency
- blocked --> active: Dependency resolved
- passing --> [*]
-
- note right of passing
- Irreversible: once passing,
- cannot go back
- end note
+flowchart LR
+ Feature["One feature row"] --> Behavior["Behavior<br/>for example: POST /cart/items returns 201"]
+ Feature --> Check["Verification command<br/>the exact check to run"]
+ Feature --> State["State<br/>not_started / active / blocked / passing"]
+
+ Behavior --> Complete["Only with all three fields<br/>is the feature row usable"]
+ Check --> Complete
+ State --> Complete
```
```mermaid
-graph TB
- FL["📋 Feature List<br/><i>Single source of truth</i>"] --> Scheduler["Scheduler<br/><i>picks next task</i>"]
- FL --> Verifier["Verifier<br/><i>runs check commands</i>"]
- FL --> Handoff["Handoff Reporter<br/><i>generates summaries</i>"]
- FL --> Progress["Progress Tracker<br/><i>tallies state distribution</i>"]
+flowchart LR
+ List["feature_list.json / features.md"] --> Scheduler["Pick the next not_started item"]
+ Scheduler --> Agent["Agent works on that one item"]
+ Agent --> Verifier["Run that item's verification command"]
+ Verifier -->|pass| Passing["Mark it passing<br/>and write the evidence"]
+ Verifier -->|fail| Active["Keep it active"]
+ Verifier -->|dependency issue| Blocked["Mark it blocked"]
+ Passing --> Handoff["Update handoff note<br/>and current progress"]
+ Active --> Agent
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index e3902fb..7c214aa 100644
--- a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -23,27 +23,18 @@ This isn't a random event. Guo et al.'s classic 2017 ICML paper proved that **mo
## Three-Layer Termination Check
```mermaid
-graph LR
- subgraph "Verification Gates"
- L1["Layer 1<br/>Syntax & Static Analysis<br/><i>lint, type check</i>"]
- L2["Layer 2<br/>Runtime Behavior<br/><i>unit & integration tests</i>"]
- L3["Layer 3<br/>System Validation<br/><i>E2E, user scenarios</i>"]
- end
-
- L1 -->|"must pass"| L2
- L2 -->|"must pass"| L3
- L3 -->|"all pass"| Done["✅ Done"]
-
- style L1 fill:#F4F3EE
- style L2 fill:#E8E7E2
- style L3 fill:#D95C41,color:#fff
+flowchart LR
+ Claim["Agent says: done"] --> L1["First run<br/>lint / typecheck"]
+ L1 --> L2["Then run<br/>tests and app startup checks"]
+ L2 --> L3["Finally run<br/>the full user flow"]
+ L3 --> Done["All three pass -> done"]
```
```mermaid
-graph LR
- Agent["Agent: 'I'm done!'"] -->|"confidence"| High["High Confidence"]
- Reality["Actual Quality"] -->|"measured"| Low["Low Quality"]
- High -.->|"calibration gap"| Low
+flowchart LR
+ A["Code is written<br/>and unit tests are green"] --> B["But the app was not fully started<br/>and the whole flow was not run"]
+ B --> C["Config, database, or email issues<br/>stay hidden"]
+ C --> D["So the agent declares done too early"]
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 8206056..39d126d 100644
--- a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -22,26 +22,27 @@ Google's test pyramid tells us: lots of unit tests form the base, but if you sto
## Test Pyramid & Review Feedback Loop
```mermaid
-graph TB
- subgraph "Test Adequacy Gradient"
- E2E["End-to-End Tests<br/><i>catches component boundary defects</i>"]
- Int["Integration Tests"]
- Unit["Unit Tests<br/><i>fast but isolated</i>"]
+flowchart TB
+ subgraph Unit["Unit tests inspect parts in isolation"]
+ U1["Renderer test"]
+ U2["Preload test"]
+ U3["Service test"]
end
- Unit --> Int --> E2E
-
- style Unit fill:#F4F3EE
- style Int fill:#E0DFD9
- style E2E fill:#D95C41,color:#fff
+ subgraph E2E["End-to-end run crosses the real system"]
+ R["Renderer click"] --> P["Preload bridge"]
+ P --> S["Service layer"]
+ S --> F["Filesystem / OS"]
+ F --> Result["Real exported file"]
+ end
```
```mermaid
-graph LR
- Review["Code Review<br/>recurring feedback"] --> Pattern["Identify pattern"]
- Pattern --> Rule["Create executable check<br/>+ agent-oriented error msg"]
- Rule --> Harness["Add to harness"]
- Harness -->|"prevents class"| Agent["🤖 Agent"]
+flowchart LR
+ Review["Reviewer says:<br/>renderer cannot import fs"] --> Rule["Add a check for direct fs import"]
+ Rule --> Message["Error tells the agent<br/>to move file access into preload"]
+ Message --> Harness["Add the check to the harness"]
+ Harness --> Stronger["Next similar mistake fails fast"]
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index d4044ea..643c642 100644
--- a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -23,25 +23,13 @@ This isn't about the agent lacking capability. It's about your harness not provi
## Layered Observability
```mermaid
-graph TB
- subgraph "Process Layer"
- SC["Sprint Contract<br/><i>scope + standards + exclusions</i>"]
- ER["Evaluator Rubric<br/><i>structured scoring</i>"]
- end
- subgraph "System Layer"
- Logs["Runtime Logs"]
- Traces["Request Traces"]
- Health["Health Checks"]
- end
-
- SC -->|"guides"| Gen["Generator"]
- Gen -->|"produces"| Runtime["Runtime Behavior"]
- Runtime --> Logs & Traces & Health
- Logs & Traces & Health -->|"evidence"| ER
- ER -->|"feedback"| Gen
-
- style SC fill:#D95C41,color:#fff
- style ER fill:#D95C41,color:#fff
+flowchart LR
+ Contract["Write down the task first<br/>what to change / what not to change / pass criteria"] --> Generator["Generator"]
+ Generator --> Signals["Collect app logs, traces,<br/>and health checks while it runs"]
+ Contract --> Review["Check the result item by item<br/>behavior / tests / boundaries"]
+ Signals --> Review
+ Review --> Verdict["Point to the failed check<br/>and where to fix it"]
+ Verdict --> Generator
```
## Why This Happens
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 5a46044..9ea4253 100644
--- a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -23,33 +23,29 @@ Both OpenAI and Anthropic state clearly: **long-term reliability depends on oper
## Five Dimensions of Clean State
```mermaid
-graph TB
- subgraph "Session Exit Checklist"
- B["✅ Build passes"]
- T["✅ Tests pass"]
- P["✅ Progress recorded"]
- A["✅ No stale artifacts"]
- S["✅ Startup path available"]
- end
-
- B & T & P & A & S -->|"all required"| Clean["🧹 Clean State"]
- Clean -->|"enables"| Next["Next session<br/>immediate productivity"]
+flowchart LR
+ Work["Feature work complete"] --> Build{"Build passes?"}
+ Build -->|yes| Test{"Tests pass?"}
+ Build -->|no| Fix["Fix before exit"]
+ Test -->|yes| Record["Update feature list + progress"]
+ Test -->|no| Fix
+ Record --> Cleanup["Remove temp artifacts / debug code"]
+ Cleanup --> Startup{"Standard startup path works?"}
+ Startup -->|yes| Clean["Clean handoff"]
+ Startup -->|no| Fix
+ Fix --> Build
```
```mermaid
-graph LR
- subgraph "Entropy Over 12 Weeks"
- W1["Week 1<br/>100% build, 100% tests"] --> W4["Week 4<br/>95% / 92%"]
- W4 --> W8["Week 8<br/>82% / 78%"]
- W8 --> W12["Week 12<br/>68% / 61%"]
- end
-
- subgraph "With Cleanup Strategy"
- C1["Week 1<br/>100% / 100%"] --> C12["Week 12<br/>97% / 95%"]
- end
-
- style W12 fill:#D95C41,color:#fff
- style C12 fill:#4CAF50,color:#fff
+flowchart LR
+ Dirty["Session ends with<br/>red tests / temp files / no progress update"] --> Diagnose["Next session first has to<br/>figure out what happened"]
+ Diagnose --> Fragile["New work starts on a messy repo"]
+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]
+ More --> Dirty
+
+ Clean["Session ends with<br/>green tests / updated progress / temp files removed"] --> Fast["Next session can start coding immediately"]
+ Fast --> Stable["No need to rescue the repo first"]
+ Stable --> Clean
```
## Why This Happens
diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
index 73b1a69..e9f815b 100644
--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -23,26 +23,21 @@
## 五层失败模型
```mermaid
-graph LR
- subgraph "五层失败模型"
- direction TB
- L1["① 任务规范层"]
- L2["② 上下文供给层"]
- L3["③ 执行环境层"]
- L4["④ 验证反馈层"]
- L5["⑤ 状态管理层"]
- end
-
- Agent["🤖 Agent"] -->|"遇到"| L1
- L1 --> L2 --> L3 --> L4 --> L5
- L5 -->|"信号:缺陷"| Fix["修补对应层 → 重新执行"]
- Fix -->|"诊断循环"| Agent
+flowchart TB
+ Spec["任务没写清楚<br/>比如“加搜索”含义很多"] --> Fail["结果:<br/>agent 写了很多代码<br/>但做事还是不稳定"]
+ Context["项目规则没写进仓库<br/>agent 看不到"] --> Fail
+ Env["环境没配好<br/>依赖或命令跑不起来"] --> Fail
+ Verify["没有测试或检查命令"] --> Fail
+ State["没有进度文件<br/>下一会话两眼一抹黑"] --> Fail
+ Fail --> Fix["把出错那一层补上<br/>再重新跑"]
```
```mermaid
-graph LR
- Bare["裸跑模式<br/>20 分钟 / $9<br/>核心功能跑不起来"] -->|"加上 harness"| Full["完整 harness<br/>6 小时 / $200<br/>应用可以正常使用"]
- Bare -.->|"同一个模型"| Full
+flowchart LR
+ Same["同一个任务<br/>同一个模型"] --> Bare["裸跑<br/>20 分钟 / $9<br/>核心功能失效"]
+ Same --> Full["加上规划、检查和评估<br/>6 小时 / $200<br/>应用可以正常使用"]
+ Bare --> Lesson["变的只有 harness"]
+ Full --> Lesson
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
index e6c303e..7dd3ae9 100644
--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -22,16 +22,13 @@
## Harness 五子系统模型
```mermaid
-graph TB
- Agent["🤖 AI Agent"] --> I["📋 指令<br/><i>AGENTS.md, CLAUDE.md</i>"]
- Agent --> T["🔧 工具<br/><i>Shell, 文件操作, 测试</i>"]
- Agent --> E["🖥️ 环境<br/><i>依赖, 运行时</i>"]
- Agent --> S["💾 状态<br/><i>进度文件, git</i>"]
- Agent --> F["✅ 反馈<br/><i>测试结果, lint, 构建</i>"]
-
- I ~~~ T ~~~ E ~~~ S ~~~ F
-
- F -->|"最高投入产出比"| Star["⭐ 从这里开始"]
+flowchart LR
+ Rules["项目规则<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]
+ State["进度和 git<br/>PROGRESS.md / commits"] --> Agent
+ Agent --> Tools["工具<br/>shell / 文件 / 测试"]
+ Tools --> Env["运行环境<br/>依赖 / 服务 / 版本"]
+ Env --> Checks["检查结果<br/>test / lint / build"]
+ Checks --> Agent
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
index f84dfb1..8b61598 100644
--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -23,34 +23,29 @@
## 知识可见性
```mermaid
-graph LR
- subgraph "Agent 可见的"
- Repo["仓库文件<br/>AGENTS.md, 代码, 测试"]
- end
- subgraph "Agent 看不到的"
- Slack["Slack 聊天记录"]
- Confluence["Confluence 文档"]
- Heads["资深工程师的脑子"]
- Jira["Jira 工单"]
- end
-
- Repo -->|"可访问"| Agent["🤖 Agent"]
- Slack -.->|"不可访问"| Agent
- Confluence -.->|"不可访问"| Agent
- Heads -.->|"不可访问"| Agent
- Jira -.->|"不可访问"| Agent
+flowchart LR
+ Slack["Slack 里的规则"] --> Write["写进仓库文件<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]
+ Confluence["Confluence 里的规则"] --> Write
+ Heads["工程师脑子里的规则"] --> Write
+ Jira["Jira 里的规则"] --> Write
+ Write --> Repo["仓库文件"]
+ Repo --> Agent["新的 agent 会话<br/>直接读仓库"]
+ Warning["规则不写进仓库<br/>agent 就看不见"] --> Agent
```
```mermaid
-graph TB
- subgraph "冷启动测试"
- Q1["这是什么系统?"]
- Q2["怎么组织的?"]
- Q3["怎么跑?"]
- Q4["怎么验证?"]
- Q5["现在做到哪了?"]
- end
- Q1 & Q2 & Q3 & Q4 & Q5 -->|"全部能从仓库回答"| Pass["✅ Harness 就绪"]
+flowchart TB
+ Q1["这是什么系统?"] --> A1["AGENTS.md / README"]
+ Q2["怎么组织的?"] --> A2["ARCHITECTURE.md / 模块文档"]
+ Q3["怎么跑?"] --> A3["Makefile / init.sh / package scripts"]
+ Q4["怎么验证?"] --> A4["测试、lint、check 命令"]
+ Q5["现在做到哪了?"] --> A5["PROGRESS.md / 功能清单 / git 历史"]
+
+ A1 --> Ready["新的会话不用问人<br/>就能开始工作"]
+ A2 --> Ready
+ A3 --> Ready
+ A4 --> Ready
+ A5 --> Ready
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
index d6b2786..90f1995 100644
--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -23,26 +23,22 @@
## 指令文件架构
```mermaid
-graph TB
- subgraph "三层结构"
- L1["<b>第一层:路由文件</b><br/>AGENTS.md (50–200 行)<br/>概览 + 硬约束 + 链接"]
- L2a["<b>第二层 a</b><br/>api-patterns.md"]
- L2b["<b>第二层 b</b><br/>database-rules.md"]
- L2c["<b>第二层 c</b><br/>testing-standards.md"]
- L3["<b>第三层:内联注释</b><br/>类型定义, 接口注释"]
- end
-
- L1 -->|"链接"| L2a
- L1 -->|"链接"| L2b
- L1 -->|"链接"| L2c
- L2a & L2b & L2c -->|"引用"| L3
-
- style L1 fill:#D95C41,color:#fff
+flowchart LR
+ Mono["一个超长 AGENTS.md"] --> MonoLoad["改一个小 bug<br/>也得把部署说明和历史备注全读一遍"]
+ MonoLoad --> MonoRisk["关键规则埋在中间<br/>很容易漏掉"]
+
+ Router["短 AGENTS.md"] --> Topics["按任务去读 API / 数据库 / 测试文档"]
+ Topics --> RoutedResult["把更多上下文留给代码阅读<br/>和验证"]
```
```mermaid
-graph LR
- Top["文件顶部<br/>✅ 高召回率"] --- Mid["文件中间<br/>❌ 中间迷失效应"] --- Bot["文件底部<br/>✅ 高召回率"]
+flowchart TB
+ File["600 行指令文件"] --> Top["顶部<br/>快速开始 + 硬约束"]
+ File --> Mid["中部<br/>第 300 行的安全规则"]
+ File --> Bot["底部<br/>明确的结束检查清单"]
+ Top --> Seen["高概率被记住"]
+ Bot --> Seen
+ Mid --> Missed["高概率被稀释或忽略"]
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index b7cbce5..7f8bb71 100644
--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -23,25 +23,26 @@
## 会话连续性流程
```mermaid
-graph LR
- subgraph "会话 N"
- Work1["执行任务"] --> Update1["更新 PROGRESS.md<br/>更新 DECISIONS.md"]
- Update1 --> Commit1["Git 提交检查点"]
- end
- subgraph "会话 N+1"
- Read1["读取 PROGRESS.md<br/>读取 DECISIONS.md"] --> Resume["从下一步继续"]
- Resume --> Work2["继续工作"]
- end
-
- Commit1 -->|"交接"| Read1
+flowchart LR
+ S1["会话 1<br/>功能做到一半"] --> End1["上下文快满了<br/>会话结束"]
+ End1 --> S2["会话 2 重新开始"]
+ S2 --> Guess["重新读目录、重跑测试、<br/>猜上次为什么这么写"]
+ Guess --> Drift["代码会重复改<br/>恢复速度也很慢"]
```
```mermaid
-graph TB
- subgraph "信息损失"
- Full["完整上下文<br/>是什么 + 为什么 + 怎么做"] -->|"压缩"| Compact["压缩后<br/>是什么 ✓ · 为什么 ✗"]
- Full -->|"新会话"| Reset["重置<br/>从工件重建"]
- end
+flowchart LR
+ Work["会话 1 的工作"] --> Progress["PROGRESS.md<br/>已完成 / 进行中 / 下一步"]
+ Work --> Decisions["DECISIONS.md<br/>为什么这样做"]
+ Work --> Verify["验证记录<br/>哪些测试通过或失败"]
+ Work --> Commit["Git 检查点<br/>当前仓库状态"]
+
+ Progress --> Rebuild["会话 2 重建"]
+ Decisions --> Rebuild
+ Verify --> Rebuild
+ Commit --> Rebuild
+
+ Rebuild --> Resume["新会话能很快接上"]
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index f11e65c..d11507c 100644
--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -23,24 +23,19 @@
## 初始化生命周期
```mermaid
-graph LR
- subgraph "初始化阶段"
- I1["可运行环境<br/><i>依赖已安装</i>"] --> I2["测试框架<br/><i>示例测试通过</i>"]
- I2 --> I3["自举契约<br/><i>启动/测试/验证文档</i>"]
- I3 --> I4["任务拆分<br/><i>有序的功能清单</i>"]
- I4 --> I5["Git 检查点<br/><i>干净提交</i>"]
- end
- subgraph "实现阶段"
- I5 --> P1["会话 2:功能 1"]
- P1 --> P2["会话 3:功能 2"]
- P2 --> P3["会话 N:功能 N"]
+flowchart TB
+ subgraph Wrong["混在一起的一次会话(错误)"]
+ W1["一上来就开始做功能"] --> W2["做到一半才发现环境和测试缺口"]
+ W2 --> W3["累积未经验证的代码"]
+ W3 --> W4["下个会话还得重新摸项目状态"]
end
- style I1 fill:#D95C41,color:#fff
- style I2 fill:#D95C41,color:#fff
- style I3 fill:#D95C41,color:#fff
- style I4 fill:#D95C41,color:#fff
- style I5 fill:#D95C41,color:#fff
+ subgraph Right["独立初始化阶段(正确)"]
+ R1["会话 1:环境可运行"] --> R2["示例测试通过"]
+ R2 --> R3["写出启动契约 + 任务清单"]
+ R3 --> R4["提交干净检查点"]
+ R4 --> R5["后续会话直接开始做已准备好的任务"]
+ end
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index bca4520..4272ed4 100644
--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -23,21 +23,23 @@ Anthropic 在 "Effective harnesses for long-running agents" 工程博客中明
## WIP=1 工作流
```mermaid
-graph LR
- subgraph "WIP = 1(正确做法)"
- Pick1["选取功能"] --> Do1["实现"] --> Verify1["端到端验证"]
- Verify1 -->|"通过"| Commit1["提交"]
- Commit1 --> Next1["下一个功能"]
- Verify1 -->|"失败"| Do1
- end
+flowchart LR
+ Queue["功能队列"] --> Pick["只选一个任务"]
+ Pick --> Active["仅允许一个 active"]
+ Active --> Verify["跑端到端验证"]
+ Verify -->|通过| Commit["提交并解锁下一个任务"]
+ Verify -->|失败| Active
+ Commit --> Queue
```
```mermaid
-graph LR
- subgraph "无约束(错误做法)"
- Pick2["同时激活 5 个功能"] --> Do2["全部做一点"]
- Do2 --> Result2["800 行,12 个文件<br/>20% 通过率 ❌"]
- end
+flowchart TB
+ Budget["可用推理预算 = C"] --> One["WIP = 1<br/>每个任务拿到 C / 1"]
+ Budget --> Many["WIP = 5<br/>每个任务只有 C / 5"]
+
+ One --> Finish["一个功能进入 passing"]
+ Many --> Partial["五个功能都只做了一半"]
+ Partial --> VCR["已验证完成率低<br/>下一会话返工高"]
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index ab4d0a9..01499c8 100644
--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -23,26 +23,26 @@
## 功能状态机
```mermaid
-stateDiagram-v2
- [*] --> not_started
- not_started --> active: Agent 选取任务
- active --> passing: 验证命令通过
- active --> blocked: 外部依赖阻塞
- blocked --> active: 依赖已解决
- passing --> [*]
-
- note right of passing
- 不可逆:一旦 passing,
- 不能回退
- end note
+flowchart LR
+ Feature["一行功能项"] --> Behavior["行为<br/>例如:POST /cart/items 返回 201"]
+ Feature --> Check["验证命令<br/>具体要跑什么检查"]
+ Feature --> State["状态<br/>not_started / active / blocked / passing"]
+
+ Behavior --> Complete["三列都齐了<br/>这行功能项才能用"]
+ Check --> Complete
+ State --> Complete
```
```mermaid
-graph TB
- FL["📋 功能清单<br/><i>单一权威来源</i>"] --> Scheduler["调度器<br/><i>选取下一个任务</i>"]
- FL --> Verifier["验证器<br/><i>执行验证命令</i>"]
- FL --> Handoff["交接报告器<br/><i>生成摘要</i>"]
- FL --> Progress["进度追踪器<br/><i>统计状态分布</i>"]
+flowchart LR
+ List["feature_list.json / features.md"] --> Scheduler["选下一个 not_started"]
+ Scheduler --> Agent["agent 只做这一项"]
+ Agent --> Verifier["跑这一项自己的验证命令"]
+ Verifier -->|通过| Passing["写成 passing<br/>并补上验证证据"]
+ Verifier -->|失败| Active["继续保持 active"]
+ Verifier -->|依赖问题| Blocked["标成 blocked"]
+ Passing --> Handoff["更新交接说明<br/>和当前进度"]
+ Active --> Agent
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 605ff8e..64345d0 100644
--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -23,27 +23,18 @@
## 三层终止检查
```mermaid
-graph LR
- subgraph "验证闸门"
- L1["第一层<br/>语法与静态分析<br/><i>lint, 类型检查</i>"]
- L2["第二层<br/>运行时行为<br/><i>单元与集成测试</i>"]
- L3["第三层<br/>系统级确认<br/><i>端到端, 用户场景</i>"]
- end
-
- L1 -->|"必须通过"| L2
- L2 -->|"必须通过"| L3
- L3 -->|"全部通过"| Done["✅ 完成"]
-
- style L1 fill:#F4F3EE
- style L2 fill:#E8E7E2
- style L3 fill:#D95C41,color:#fff
+flowchart LR
+ Claim["agent 说:做完了"] --> L1["先跑<br/>lint / typecheck"]
+ L1 --> L2["再跑<br/>测试和启动检查"]
+ L2 --> L3["最后跑<br/>完整用户流程"]
+ L3 --> Done["三层都过才算完成"]
```
```mermaid
-graph LR
- Agent["Agent: '我做完了!'"] -->|"置信度"| High["高置信度"]
- Reality["实际质量"] -->|"实测"| Low["低质量"]
- High -.->|"校准偏差"| Low
+flowchart LR
+ A["代码写完了<br/>单测也绿了"] --> B["但应用没真正启动<br/>完整流程也没跑"]
+ B --> C["配置、数据库、外部服务问题<br/>还都藏着"]
+ C --> D["于是 agent 太早宣告完成"]
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 85da5e5..691c561 100644
--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -22,26 +22,27 @@ Google 的测试金字塔告诉我们:大量单元测试是基础,但如果
## 测试金字塔与审查反馈提升
```mermaid
-graph TB
- subgraph "测试充分性梯度"
- E2E["端到端测试<br/><i>捕获组件边界缺陷</i>"]
- Int["集成测试"]
- Unit["单元测试<br/><i>快速但隔离</i>"]
+flowchart TB
+ subgraph Unit["单元测试只看孤立部件"]
+ U1["渲染层测试"]
+ U2["Preload 测试"]
+ U3["服务层测试"]
end
- Unit --> Int --> E2E
-
- style Unit fill:#F4F3EE
- style Int fill:#E0DFD9
- style E2E fill:#D95C41,color:#fff
+ subgraph E2E["端到端运行会穿过真实系统"]
+ R["点击渲染层按钮"] --> P["Preload 桥"]
+ P --> S["服务层"]
+ S --> F["文件系统 / 操作系统"]
+ F --> Result["真实导出文件"]
+ end
```
```mermaid
-graph LR
- Review["代码审查<br/>重复性反馈"] --> Pattern["识别模式"]
- Pattern --> Rule["创建可执行检查<br/>+ 面向 agent 的错误消息"]
- Rule --> Harness["加入 harness"]
- Harness -->|"预防同类问题"| Agent["🤖 Agent"]
+flowchart LR
+ Review["审查意见:<br/>renderer 不能直接 import fs"] --> Rule["加一条 direct fs import 检查"]
+ Rule --> Message["报错里直接告诉 agent<br/>把文件访问移到 preload"]
+ Message --> Harness["把这条检查加入 harness"]
+ Harness --> Stronger["以后再犯会第一时间报错"]
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 069f53a..443b613 100644
--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -23,25 +23,13 @@
## 双层可观测性
```mermaid
-graph TB
- subgraph "过程层"
- SC["冲刺合同<br/><i>范围 + 标准 + 排除项</i>"]
- ER["评估评分标准<br/><i>结构化评分</i>"]
- end
- subgraph "系统层"
- Logs["运行时日志"]
- Traces["请求追踪"]
- Health["健康检查"]
- end
-
- SC -->|"指导"| Gen["生成器"]
- Gen -->|"产出"| Runtime["运行时行为"]
- Runtime --> Logs & Traces & Health
- Logs & Traces & Health -->|"证据"| ER
- ER -->|"反馈"| Gen
-
- style SC fill:#D95C41,color:#fff
- style ER fill:#D95C41,color:#fff
+flowchart LR
+ Contract["先把这次任务写清楚<br/>改哪些文件 / 不改哪些部分 / 怎么算通过"] --> Generator["生成器"]
+ Generator --> Signals["运行时收集<br/>日志 / 追踪 / 健康检查"]
+ Contract --> Review["按检查表逐项看<br/>功能 / 测试 / 边界"]
+ Signals --> Review
+ Review --> Verdict["指出哪一项没过<br/>以及应该去改哪里"]
+ Verdict --> Generator
```
## 为什么会这样
diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 161c992..d98a571 100644
--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -23,33 +23,29 @@ OpenAI 和 Anthropic 都明确指出:**长期可靠性取决于操作纪律,
## 清洁状态的五个维度
```mermaid
-graph TB
- subgraph "会话退出检查清单"
- B["✅ 构建通过"]
- T["✅ 测试通过"]
- P["✅ 进度已记录"]
- A["✅ 无过时工件"]
- S["✅ 启动路径可用"]
- end
-
- B & T & P & A & S -->|"缺一不可"| Clean["🧹 清洁状态"]
- Clean -->|"保障"| Next["下一会话<br/>立即进入工作状态"]
+flowchart LR
+ Work["功能工作已完成"] --> Build{"构建通过?"}
+ Build -->|是| Test{"测试通过?"}
+ Build -->|否| Fix["先修好再退出"]
+ Test -->|是| Record["更新功能清单 + 进度"]
+ Test -->|否| Fix
+ Record --> Cleanup["清理临时工件 / 调试代码"]
+ Cleanup --> Startup{"标准启动路径可用?"}
+ Startup -->|是| Clean["干净交接"]
+ Startup -->|否| Fix
+ Fix --> Build
```
```mermaid
-graph LR
- subgraph "12 周后(无清理)"
- W1["第 1 周<br/>100% 构建, 100% 测试"] --> W4["第 4 周<br/>95% / 92%"]
- W4 --> W8["第 8 周<br/>82% / 78%"]
- W8 --> W12["第 12 周<br/>68% / 61%"]
- end
-
- subgraph "12 周后(有清理策略)"
- C1["第 1 周<br/>100% / 100%"] --> C12["第 12 周<br/>97% / 95%"]
- end
-
- style W12 fill:#D95C41,color:#fff
- style C12 fill:#4CAF50,color:#fff
+flowchart LR
+ Dirty["这次退出时<br/>测试是红的、临时文件没删、进度也没写"] --> Diagnose["下个会话先花时间<br/>搞清楚发生了什么"]
+ Diagnose --> Fragile["接着在一个很乱的仓库上继续改"]
+ Fragile --> More["更多调试文件、更多坏检查、<br/>更多说不清的进度"]
+ More --> Dirty
+
+ Clean["这次退出前<br/>测试是绿的、进度写了、临时文件删了"] --> Fast["下个会话打开仓库就能继续写代码"]
+ Fast --> Stable["不用先救火"]
+ Stable --> Clean
```
## 为什么会这样