docs(s16): March-feel ideal chapter + maintainer readability standard

docs/maintainers/MARCH_FEEL_AND_READABILITY.md

@@ -0,0 +1,188 @@
+# learn-claude-code：章节可读性与文风恢复说明（给维护者）
+
+**读者**：本仓库维护者 / 章节作者 / Reviewer  
+**基准对照**：2026-03-29 `16b927c`（12 课 + `docs/zh` 心智模型短章）vs 当前 `main`（17 课根目录）  
+**诉求来源**：课程创始人侧反馈——当前中后章阅读感、创作感、上头感明显变差；版式固定、AI 味、行文尴尬、难读难懂。  
+**状态**：本文为写作与改写的权威约束。机制正确性仍要守；**文风与信息优先级以本文为准**。
+
+---
+
+## 1. 一句话
+
+请把章节从「工程规格书 + AI 润色课包」拉回「短讲义卡片」：
+
+> **问题砸人 → 一张图/ASCII → 最小代码 → 试一试**
+
+深度可以保留，但必须住在折叠/附录；不能占首屏和主呼吸。
+
+---
+
+## 2. 客观诊断（不是口味吵架）
+
+### 2.1 分层结论
+
+| 范围 | 阅读感 | 创作感 | 上头感 | 说明 |
+|------|------:|------:|------:|------|
+| 2026-03 短章 | ~8.5 | ~8 | ~8 | 短、具体、对「你」说话 |
+| main 早章（约 s01–s07） | ~7 | ~6 | ~6.5 | 仍可读，已被模板镀铬 |
+| main 晚章（s08/s13/s15/s16…） | ~3.5 | ~2.5 | ~2 | 手册化 / 抽象词 / 标题墙 |
+
+### 2.2 关键数字（main 中文 README）
+
+- 三月章均约 **4KB / 5 个 H2**；main 中位约 **6.9KB**，重灾章 **11–18KB**。
+- 分水岭在 **s08**：此前多为「镀铬但仍短」，此后跳变。
+- 「你」：s01 仍在；多数中后章 **≈0**。
+- 全部 17 章：双语导航 + `translation-sync`；**`<details>` 使用率曾长期为 0**（深度只能堆主文）。
+- 重灾优先序（分诊）：**s13 → s16 → s08 → s15 → s10**（s17/s09 紧随）。
+
+### 2.3 根因 Top 5（不是「单纯更长」）
+
+1. **声音从「对你说话」变成系统旁白**  
+2. **taxonomy / 边界表 / 组件目录压过洞见**  
+3. **模板铬 + 三语文案生产线**（章感雷同）  
+4. **工程词典取代叙事动词**（宿主/registry/生命周期/语义 key…）  
+5. **覆盖焦虑**把教学文写成 runbook  
+
+### 2.4 高 AI 味的机械尾槽（特别刺眼）
+
+章章同一套收尾流水线会让人一眼看出「流水线产物」：
+
+| 槽位 | 机械套路 | 读感 | 要求 |
+|------|----------|------|------|
+| 试一下 | cd → 编号 prompt →「观察重点：是否…是否…」 | QA/CI checklist | 命令 + ≤3 prompt；**禁止观察重点勾选清单** |
+| 接下来 | 「现在能 X 了。但 Y 又爆了。」 | 万能悬念工厂 | **可选**；≤3 句且换写法；可整段删 |
+| 相对 sN | 组件/之前/之后大表 | PR 变更表塞进教材 | **默认撤出主文**；改一句能力增量或进 `<details>` |
+
+三月同题常在「试一试」后**戛然而止**——没有「接下来」，没有观察审问；更像人写的。
+
+### 2.5 同题对比（摘录）
+
+**三月 s01**  
+> 没有循环, 每次工具调用你都得手动把结果粘回去。**你自己就是那个循环。**
+
+**main s06（同主题后继）**  
+> …多数中间细节不再需要，却仍然占用上下文。  
+（正确、完整、无趣；「pytest 一个词」那种 punch 没了。）
+
+**main s08**  
+> **本节将实现一条四步压缩管线。**  
+（预告腔直接杀死好奇心。）
+
+**main s15**  
+开篇 9 条「需要同时拥有」功能 backlog +「组件在循环中的位置」大表 + 观察重点 8 条——组件目录，不是故事。
+
+**main s16**  
+抽象工程词命中可到数十上百；开篇像架构演进史，不像痛点。
+
+---
+
+## 3. 写作要求（必须遵守）
+
+### 3.1 主文硬指标（不含 `<details>`）
+
+| 指标 | 达标 | 重灾线 |
+|------|------|--------|
+| 字节 | ≤7KB | >10KB |
+| 行数 | ≤180 | >260 |
+| H2 | ≤7 | >10 |
+| 主文代码围栏 | ≤4 | >8 |
+| 主文表格 | ≤1 | ≥3 |
+| 「你」（问题/试跑） | ≥1 | 全程无人称 |
+| 「本节将/本章将」 | 0 | ≥1 |
+| 抽象工程词* | ≤15 | >40 |
+| 首屏 | 能看到「问题」/痛点 | 只见导航或目录 |
+
+\*词表示例：管线|拓扑|适配器|原语|宿主|生命周期|registry|schema|journal|元数据|编排|语义  
+
+图片：主路径 0–2 张；ASCII 能讲清就不上大图；次要图进折叠。
+
+### 3.2 推荐骨架
+
+```text
+标题（短、可记）
+一行语言切换（若课程需要）+ 一行面包屑
+格言 1 句 + Harness 层 1 行（要狠）
+
+## 问题        ← 2–5 句；有「你」或可感场景；禁止功能清单开场
+## 解决方案    ← 1 ASCII/1 关键图 + 2–4 句
+## 工作原理    ← ≤4 步；人话 → 再术语；短代码
+## 试一试      ← 命令 + ≤3 prompt；禁止观察重点清单
+## 接下来（可选）
+
+<details>…深度、模式库、边界、相对前章细表…</details>
+```
+
+复杂章只保证主文讲清「**这一章只加一件东西**」。
+
+### 3.3 声音
+
+- 先洞见，后术语。  
+- 每章至少一句 punch（删掉它章就塌）。  
+- 隐喻最多开篇一小段；禁止全章跟隐喻跑。  
+- 中文像人讲，不要英译说明书。  
+- 90 秒说不清「只加了一件东西」→ 再砍。
+
+### 3.4 机制 fidelity（教学可简化，不可说错）
+
+以各章真实教学代码与上游产品契约为准。以 s16 为例必须诚实：
+
+- Dynamic = 模型写脚本（Claude Code：`script` / `scriptPath`）；Saved = `name` + `args`  
+- 不得再暗示「模型不能提交可执行代码」仿佛是产品事实  
+- `parallel`/`pipeline` 失败隔离为 null；resume = 最长未改前缀  
+- 说明为何真 JS runtime 忌 `Date.now` / `Math.random`  
+- 本章若是 Python 教学 runtime，要标明：思想对齐，不是 bit-perfect 复刻  
+
+思想脊梁可参考官方文  
+[A harness for every task: dynamic workflows in Claude Code](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code)。
+
+### 3.5 Reviewer 清单
+
+- [ ] 首屏出现痛点  
+- [ ] 主文硬指标达标  
+- [ ] 有 punch；格言与正文咬合  
+- [ ] 对「你」说话  
+- [ ] 无「本节将」、无标题墙、无主文组件目录  
+- [ ] 无观察重点勾选、无万能「接下来」、无主文「相对 sN」大表  
+- [ ] 深度在 `<details>`  
+- [ ] GitHub 预览像讲义，不像 API 手册  
+- [ ] 机制正确  
+
+---
+
+## 4. 建议改写队列
+
+1. **P1 重灾**：s13_agent_teams，s16_workflow_runtime，s08_context_compact，s15_integrated_harness  
+2. **P2 手册化**：s10_task_system，s17_goal_loop，s09_memory，s14_mcp_plugin，s11…  
+3. **P4 镀铬早章**：少动结构；去预告腔、补 punch、减轻尾槽机械感  
+4. **全局政策**：主文短 + `<details>` 分层；尾槽去流水线化  
+
+s16 无三月祖先：叙事节奏应对标 **s01/s06 三月短章**，不要对标 s13/s15 说明书骨架。
+
+---
+
+## 5. 证据与附件（工作区）
+
+| 文件 | 内容 |
+|------|------|
+| `MARCH_FEEL_RECOVERY_PLAYBOOK.md` | 恢复标准细则 |
+| `DEEP_READABILITY_WHY_BAD.md` | 文风深挖与打分 |
+| `MAIN_CHAPTER_TRIAGE.md` | 17 章分诊表 |
+| `TEMPLATE_SLOTS_AI_SMELL.md` | 试一下/接下来/相对前章并置 |
+| `MARCH_VS_MAIN_READABILITY.md` | 量化简报 |
+| `AGENT_WRITING_BRIEF.md` | s16 思想/fidelity 总纲 |
+| `/workspace/lcc_shots2/*.png` | GitHub 渲染截图对照 |
+
+三月对照 commit：`16b927c8ee7befa07caf8844d22f86ffef0aea05`。
+
+---
+
+## 6. 非目标
+
+- 不是要求删掉三语支持或测试。  
+- 不是要求章节变浅、变错。  
+- 不是要求每章都用同一套「精修散文」或同一套隐喻。  
+- 是要求：**可读、有创作棱角、想翻下一章**；正确性放在正确的信息层级里。
+
+---
+
+*维护者文档版本：2026-08-12*