书籍框架搭建与结构规划Skill book-scaffolding

技能：书籍框架搭建与结构规划

目的：使用认知负荷管理、即时规范和教学最佳实践来规划、构建和搭建大型教育书籍的结构。

宪法对齐：v4.0.1强调：

• 原则1：规范至上（“规范即新语法”）
• 第二章a：泛学4层教学法（渐进式课程结构）
• 第二章b：AI三角色框架（双向共学伙伴关系）
• 九大支柱（第一章）：AI CLI, Markdown, MCP, AI优先IDE, 跨平台, TDD, SDD, 可组合技能, 云原生
• 原则4：连贯的教学结构（基于概念密度的灵活课程数量）

状态：可复用技能（从002-book-structure冲刺中学习，通过结构模式增强） 应用：任何多部分、多章节的教育作品

---

核心原则（冲刺中的9个学习）

1. 即时规范（“规范即新语法”）

❌ 不要：提前决定一切。在向前推进之前等待所有澄清。 ✅ 做：现在需要什么就规范什么。将部分特定的澄清推迟到该部分准备好规划时。

为什么：立即解锁工作。澄清在需要时恰好到达（在章节规划阶段）。尊重SDD循环：规范 → 计划 → 按部分实施（一次一个）。

关键：规范编写是首要技能。书籍结构框架首先学习跨所有部分的规范。

示例：

• 第1部分规范仅创建第1部分叙事（“从编码器到超级指挥家”）
• 第6部分的代理框架推迟到第6部分准备好规划时
• 每个部分规划阶段触发该部分的澄清

2. 最小MVP方法

❌ 不要：创建全面的指南、模板、所有部分规范、技能集成指南、验证指南 ✅ 做：仅创建必需品。专注于：部分介绍、章节占位符、第1部分规范、验证报告

为什么：减少冗余。消除过度工程。更快开始写作。

实际需要什么：

• 7部分介绍文件（解释每个部分的内容）
• 32章节文件夹结构及README
• 1第1部分规范（详细，准备好章节规划）
• 验证报告（确认结构有效）
• 第2-7部分规范推迟到需要时

3. 叙事连贯性

❌ 不要：将章节视为孤立单位。让每个章节走向自己的结论。 ✅ 做：使用统一的叙事弧线贯穿部分的所有章节。

为什么：读者保持参与。内容凝聚力提高。读者看到联系。

示例来自第1部分：

• 统一叙事：“从编码器到超级指挥家”
• 第1章：设置心态转变
• 第2章：解释使能的9次革命
• 第3章：安装您作为指挥家所需的工具
• 第4章：您执行第一次编排（规范 → AI → 测试 → 部署）
• 第5章：编排失败时您调试（弹性）

每一章都在强化“指挥家”身份的同时推进故事。

4. 认知负荷管理（关键）

❌ 不要：提前加载复杂概念。假设读者具备先验知识。 ✅ 做：跨章节管理认知负荷。轻 → 中等 → 高级。早期重框架。

框架：

• 认知负荷级别：轻、中等、重（每部分定义）
• 框架级别：重（早期）、中等（中期）、轻（晚期）
• 概念密度：每章3-7个关键概念（因部分而异）
• 复习周期：新材料2-3次，强化1次

示例来自第1部分：

• 认知负荷：轻（基础定位）
• 框架：重（展示后解释、指导示例、零门槛）
• 概念密度：每章3-4（吸收时间）
• 结果：初学者感到舒适，不被压倒

5. 先展示后解释的教学法

❌ 不要：先解释概念，然后展示示例 ✅ 做：先展示工作示例，然后解释原则

为什么：认知科学：当人们在抽象规则之前看到具体示例时，学习效果更好。

模式：

1. 展示：“这是一个工作规范，生成的代码，测试结果”
2. 解释：“这就是为什么这样做有效。这里有原则。”
3. 实践：“现在你用不同的领域尝试”
4. 评估：“你能独立做到这一点吗？”

6. 零门槛语言

❌ 不要：“很简单…”，“显然…”，“只是…”，“任何人都可以…” ✅ 做：解释每个假设。尊重读者的学习旅程。

为什么：门槛语言使不认为简单的读者感到疏远。包容性语言尊重所有学习者。

示例重写：

• ❌ “简单地写一个规范，Claude Code生成代码”

• ✅ “用清晰的需求写一个规范。Claude Code读取您的规范并生成符合这些需求的代码。”

• ❌ “调试很容易—只需阅读错误消息”

• ✅ “当代码失败时，阅读错误消息以了解发生了什么。以下是如何解释常见错误…”

7. 连接映射（部分到部分）

❌ 不要：将每个部分视为孤立的。读者想知道“我为什么要学这个？” ✅ 做：明确映射每个部分如何为后续部分做准备。

模式：

第1部分 → 心态转变（编排）
  ↓ 为您准备第2部分（工具）
  ↓ 这为您准备第3部分（提示）
  ↓ 这为您准备第4部分（Python）
  ↓ 这为您准备第5部分（Spec-Kit）
  ↓ 这为您准备第6部分（代理）
  ↓ 这为您准备第7部分（MCP）

示例来自第1部分规范：

• 第1章为：第2部分（工具很重要）、第3部分（规范）和第4部分（编排即代码）做准备
• 第2章为：第5部分（Spec-Kit）、第6部分（代理）和第7部分（MCP集成）做准备
• 第3章为：第4章（动手）和第2-7部分（假设工具正常工作）做准备

8. 成功标准定义

❌ 不要：模糊的接受标准（“学生将理解…”） ✅ 做：每个章节都有可衡量、可观察的成功标准

每章模式：

学习成果：“理解为什么编排优于编码”
成功标准：“读者可以用自己的话说出为什么编排 > 编码”
可衡量目标：“90%+的读者可以在不提示的情况下解释（用自己的话）”

示例来自第1部分，第1章：

• 读者可以列出3个垂直智能机制（子代理、技能、MCP）
• 读者看到实际的ARR数字并感到有动力（而不是受到威胁）
• 读者准备好“理解9次革命”（第2章）

9. 实践章节（动手练习）

❌ 不要：只教概念。不练习。 ✅ 做：包括实际章节的练习（工具设置、第一个程序、调试）

练习模式：

1. 任务：真实但受限的（例如，“构建电子邮件验证器”）
2. 你的角色：编写规范/设置工具/识别错误
3. AI/系统角色：生成代码/安装/修复
4. 你的角色再次：测试/验证/理解
5. 反思：“为什么这样做有效？你学到了什么？”

示例来自第1部分：

• 第3章：安装所有3个工具，验证端到端
• 第4章：为电子邮件验证器编写规范 → Claude Code生成 → 测试
• 第5章：调试故意破坏的代码，迭代修复

10. 九大支柱对齐（新 - 宪法v3.1.2）

❌ 不要：在没有九大支柱框架的情况下构建书籍 ✅ 做：框架内容，逐步引入和应用九大支柱

AI原生开发的九大支柱：

1. AI优先心态，2. 规范优先开发，3. 评估驱动验证，4. 迭代收敛，5. 上下文工程，6. 输出验证，7. 战略编排，8. 持续学习，9. 道德责任

框架策略：

• 第1部分：引入支柱1、2、8（AI优先心态，规范优先，持续学习）
• 第2-5部分：在实践中应用支柱2-6（规范优先，评估，收敛，上下文，验证）
• 第6-7部分：强调支柱7（战略编排LAMS/代理）
• 第10-13部分：在生产环境中应用所有9个支柱

每章框架：

• 确定每章教授/应用的2-3个支柱
• 确保逐步覆盖（不要一次引入所有9个）
• 在章节规范中记录支柱对齐

11. LLM到LAM演变框架（新 - 宪法v3.1.2）

❌ 不要：将所有AI交互视为各部分相同 ✅ 做：框架从LLM基础（第1-5部分）过渡到LAM基础（第6-7部分+）内容

LLM基础框架（第1-5部分）：

• 重点：AI作为推理伙伴（提示-响应）
• 技能：提示工程、规范编写、输出验证
• 模式：人类指定 → AI响应 → 人类验证

LAM基础框架（第6-7部分+）：

• 重点：AI作为自治代理（多步骤任务执行）
• 技能：代理设计、编排、安全约束
• 模式：人类编排 → AI自主行动 → 人类监督

过渡框架（第5部分 → 第6部分）：

• 第5部分最后几章：LLM提示掌握（基础）
• 第6部分开头：LAMs介绍（建立在LLM技能上）
• 关键教学：“告诉AI做什么”（LLM） → “告诉AI要实现什么，它自己想办法”（LAM）

12. 共学伙伴框架（新 - 宪法v3.1.2）

❌ 不要：将AI贯穿全书作为被动工具 ✅ 做：从第1章开始框架共学伙伴关系

框架进展：

• 第1部分：引入共学概念（AI教你，你教AI）
• 第2-5部分：在每一章中展示双向学习
• 第6+部分：展示高级共学（代理学习用户领域）

每章要求：

• 展示至少一个学生从AI学习的例子
• 展示至少一个AI适应学生反馈的例子
• 展示收敛（不是“第一次就完美”）

---

书籍框架工作流程

第1阶段：全局结构（书籍级别）

输入：用户对整本书的愿景（主题、章节、学习旅程） 输出：

• 多部分架构与学习进展
• 章节概览（标题、范围）
• 认知负荷映射（轻 → 重分布）

要问的问题：

1. 所有部分的统一叙事是什么？
2. 每个部分的认知负荷是什么？
3. 章节如何连接部分到部分？
4. 哪些章节是重框架点？

参考：参见reference/structural-patterns.md，了解有关书籍组织模式的详细指导。

第2阶段：部分级规范（一次一个部分）

输入：部分目的、章节标题、部分在整体旅程中的角色 输出：详细的部分规范，包括：

• 部分叙事（这部分的统一主题）
• 完全指定的章节（学习成果、关键主题、成功标准）
• 教学策略（认知负荷、框架、概念密度）
• 连接图（这部分如何为下一部分做准备）
• 实践章节的动手练习

推迟：

• 部分特定澄清（代理框架、案例研究等）→ 在章节规划阶段解决
• 未来部分规范 → 在前一部分实施时即时创建

要问的问题：

1. 这部分的目的是什么？
2. 读者应该知道什么？
3. 章节的叙事弧是什么？
4. 哪些章节需要重框架？轻？
5. 哪些动手练习可以建立信心？

参考：参见reference/chapter-flow-patterns.md，了解不同的章节排序方法。

第3阶段：章节规划阶段（调用子代理）

输入：部分规范（来自第2阶段） 子代理：章节规划器 输出：每个章节在部分中：

• chapter-NN-plan.md（详细的课程分解）
• chapter-NN-tasks.md（实施清单）

发生什么：

• 章节规划器阅读您的部分规范
• 将每个章节分解为5-7课
• 定义每课的学习目标、代码示例、练习
• 如有需要，请求澄清（即时）
• 提供时间估计

参考：参见reference/chapter-dependencies.md，了解如何管理先决条件和章节关系。

第4阶段：课程编写阶段（调用子代理）

输入：chapter-NN-plan.md（来自第3阶段） 子代理：内容实施者（迭代） 输出：完成的课程内容 流程：一次编写一课，审查，完善，批准

第5阶段：验证阶段（调用子代理）

输入：完成的章节（来自第4阶段） 子代理：验证审计员 输出：验证报告 检查：代码正确性、教学效果、宪法对齐

---

质量标准清单

所有书籍内容必须：

• ✅ 应用所有领域技能：使用学习目标、概念框架、代码示例生成器、练习设计者、评估构建者、技术清晰度、书籍框架、AI增强教学
• ✅ 先展示后解释：示例第一，原则第二，实践第三
• ✅ 零门槛：没有“简单”、“明显”、“只是”。解释每个假设。
• ✅ 类型提示：所有代码包括类型提示（语言适当）
• ✅ 测试：所有代码示例在发布前都经过测试
• ✅ 可访问性：Alt文本、高对比度、清晰语言、多种阅读路径
• ✅ 宪法对齐：与项目原则和不可协商规则保持一致

接受检查

• [ ] 每个章节/课程都标记了复杂性级别（初学者/中级/高级/专业）
• [ ] 初学者级别的部分尊重概念上限（每节≤5个新概念）
• [ ] 依赖性索引存在：先决条件和前向链接带有锚点
• [ ] SpecRef包含在部分/章节标题中

依赖性索引（示例）

先决条件：第1部分第2章（工具），第3部分第1章（提示）
接下来：第4部分第3章（类型），第5部分第1章（Spec-Kit介绍）

---

成功指标

对于每个部分：

指标	成功措施	目标
叙事清晰度	读者阐述部分的目的	90%+可以解释
认知负荷	没有压倒性的章节；框架适当	85%+认为节奏良好
学习成果	读者实现可衡量的成果	80%+实现所有成果
动手完成度	读者完成练习	80%+完成练习
信心	读者为下一部分做好准备	85%+同意
代码质量	所有示例正确运行	100%通过测试
可访问性	所有读者都可以导航（不同的阅读风格）	95%+可访问性

---

反模式（不要做什么）

❌ 过度规划：提前创建所有部分规范（推迟决策，阻碍工作） ❌ 孤立章节：没有连接映射；读者看不到旅程 ❌ 概念超载：每章10+概念；初学者不知所措 ❌ 先解释后展示：原则第一，示例第二（更难学习） ❌ 门槛语言：“简单”、“明显”、“只是”；疏远学习者 ❌ 没有练习：被动阅读；没有建立信心 ❌ 不一致的框架：中期重，开始轻（相反） ❌ 缺少成功标准：“他们会理解的”—没有可衡量的目标 ❌ 冗余工件：同一模板、指南、规范的多个版本 ❌ 部分规范太早：在第1部分实施之前创建第5部分规范（浪费努力）

---

如何使用这项技能

计划新部分时

使用书籍框架技能来：
1. 定义部分在整体书中的目的
2. 创建部分叙事（统一主题）
3. 指定章节（学习成果、关键主题、成功标准）
4. 映射教学策略（认知负荷、框架、概念密度）
5. 定义连接图（这部分如何为下一部分做准备）
6. 确定实践章节的动手练习

创建章节规范时

使用书籍框架技能来：
1. 定义章节目的（在部分叙事内）
2. 列出学习成果（与布鲁姆分类学对齐）
3. 确定要涵盖的关键主题
4. 定义成功标准（可衡量、可观察）
5. 计划教学方法（先展示后解释、概念密度）
6. 确定动手练习（如果是实践章节）

审核完成内容时

使用书籍框架技能来：
1. 验证所有领域技能的应用
2. 检查先展示后解释模式
3. 确认零门槛语言
4. 验证可访问性标准
5. 验证代码中的类型提示和测试
6. 检查宪法对齐

---

参考

有关书籍结构具体方面的更深入指导：

• 目录结构（项目特定）：specs/book/directory-structure.md

  • 权威来源：文件路径和文件夹组织
  • 3级层次结构（部分 → 章节 → 课程）
  • 命名约定（大写部分，小写章节）
  • 必需文件和验证规则

• 章节索引（项目特定）：specs/book/chapter-index.md

  • 所有32个章节标题、编号和主题
  • 将章节映射到部分
  • 章节特定内容指导

• 章节流程模式：reference/chapter-flow-patterns.md

  • 线性、螺旋、模块化、混合和基于项目流程模式
  • 选择正确模式的决策框架

• 结构模式：reference/structural-patterns.md

  • 教程与参考平衡
  • 章节内部结构（IBS, MCA, Cookbook, EEE）
  • 部分和部分组织策略

• 内容组织：reference/content-organization.md

  • 分块策略（微、迷你、标准、宏观）
  • 层次组织最佳实践
  • 交叉引用技术

• 章节依赖性：reference/chapter-dependencies.md

  • 依赖性类型和模式
  • 核心与可选章节
  • 管理循环依赖性

---

版本历史

v1.0（2025-10-29）：根据002-book-structure冲刺学习创建

• 9个核心原则
• 工作流程（第1-5阶段）
• 质量标准
• 成功指标

v2.0（2025-10-29）：增强结构模式

• 集成了book-architecture技能的参考资料
• 添加了全面的流程模式和组织策略
• 合并为8个CoLearning领域技能之一

---

状态：准备在所有多部分教育书籍上使用。在CoLearning Python和Agentic AI项目上得到验证。