# 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`；**`
` 使用率曾长期为 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 变更表塞进教材 | **默认撤出主文**；改一句能力增量或进 `
` | 三月同题常在「试一试」后**戛然而止**——没有「接下来」，没有观察审问；更像人写的。 ### 2.5 同题对比（摘录） **三月 s01** > 没有循环, 每次工具调用你都得手动把结果粘回去。**你自己就是那个循环。** **main s06（同主题后继）** > …多数中间细节不再需要，却仍然占用上下文。 （正确、完整、无趣；「pytest 一个词」那种 punch 没了。） **main s08** > **本节将实现一条四步压缩管线。** （预告腔直接杀死好奇心。） **main s15** 开篇 9 条「需要同时拥有」功能 backlog +「组件在循环中的位置」大表 + 观察重点 8 条——组件目录，不是故事。 **main s16** 抽象工程词命中可到数十上百；开篇像架构演进史，不像痛点。 --- ## 3. 写作要求（必须遵守） ### 3.1 主文硬指标（不含 `
`） | 指标 | 达标 | 重灾线 | |------|------|--------| | 字节 | ≤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；禁止观察重点清单 ## 接下来（可选）
…深度、模式库、边界、相对前章细表…
``` 复杂章只保证主文讲清「**这一章只加一件东西**」。 ### 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」大表 - [ ] 深度在 `
` - [ ] 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. **全局政策**：主文短 + `
` 分层；尾槽去流水线化 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*