7.5 KiB
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（不是「单纯更长」）
- 声音从「对你说话」变成系统旁白
- taxonomy / 边界表 / 组件目录压过洞见
- 模板铬 + 三语文案生产线（章感雷同）
- 工程词典取代叙事动词（宿主/registry/生命周期/语义 key…）
- 覆盖焦虑把教学文写成 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 推荐骨架
标题（短、可记）
一行语言切换（若课程需要）+ 一行面包屑
格言 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。
3.5 Reviewer 清单
- 首屏出现痛点
- 主文硬指标达标
- 有 punch；格言与正文咬合
- 对「你」说话
- 无「本节将」、无标题墙、无主文组件目录
- 无观察重点勾选、无万能「接下来」、无主文「相对 sN」大表
- 深度在
<details> - GitHub 预览像讲义，不像 API 手册
- 机制正确
4. 建议改写队列
- P1 重灾：s13_agent_teams，s16_workflow_runtime，s08_context_compact，s15_integrated_harness
- P2 手册化：s10_task_system，s17_goal_loop，s09_memory，s14_mcp_plugin，s11…
- P4 镀铬早章：少动结构；去预告腔、补 punch、减轻尾槽机械感
- 全局政策：主文短 +
<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