mirror of
https://github.com/shareAI-lab/analysis_claude_code.git
synced 2026-09-20 12:13:38 +08:00
docs(s16): ideal March-feel chapter + maintainer readability standard (v19)
This commit is contained in:
Xinlu Lai
188
docs/maintainers/MARCH_FEEL_AND_READABILITY.md
Normal file
188
docs/maintainers/MARCH_FEEL_AND_READABILITY.md
Normal file
@@ -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*
|
||||
Reference in New Issue
Block a user