| name | project-based-learning |
| description | Use this skill only when the user explicitly wants to learn through building a small real project step by step — for example, they want hands-on practice, project-based learning, learn-by-doing, or to use a practical project to learn a technology. Do not trigger this skill for ordinary implementation requests, even if the user also wants explanations, documentation updates; those are workflow preferences, not sufficient trigger conditions on their own. |
Project-Based Learning
用这个 skill 驱动“通过一个真实但可控的小项目边做边学”的协作流程。
它的重点不是更快交付功能，而是帮助用户在实现过程中持续建立工程理解：
- 当前为什么做这一步
- 这一步在当前章节里起什么作用
- 做完后应该如何验证
- 这一步与后续章节的边界是什么
何时触发
只有当用户明确表达“想通过项目来学习”时，才应触发本 skill。
高置信触发信号：
- 用户明确说想“通过项目学习”“边做边学”“learn by doing”“实战学习”。
- 用户希望用一个小项目、练手项目、demo 项目来学习某门技术。
- 用户的核心诉求不是一次性交付，而是借项目过程建立能力。
以下情况本身不足以触发本 skill：
- 用户要求拆成章节、阶段、里程碑或学习路线。
- 用户要求同步写学习文档、操作记录或教程。
- 用户要求“先解释，再执行”，或希望每一步先确认理解。
- 用户要求一章一个 commit，或控制提交粒度。
这些更像工作流偏好。只有它们与“通过项目来学习”的明确意图同时出现时，才适合触发本 skill。
如果用户只是想快速修 bug、完成一次性脚本、或直接代写功能，不要触发本 skill。
第一阶段：背景对齐
开始实现前，先完成背景对齐，不要急着写代码。
1. 学习目的
先确认用户为什么做这个项目：
- 是为了学某门语言、框架或某类开发能力？
- 是为了练工程化能力，还是只练语法？
- 是希望做 demo，还是做一个可持续扩展的小项目？
2. 用户背景
确认用户已有经验与迁移成本：
- 熟悉哪些语言和框架
- 是第一次接触当前技术栈，还是已有基础
- 更需要概念解释，还是更需要实践指引
3. 项目方向
在开始前对齐项目方向，避免边做边改主题：
- 做什么类型的项目
- 最小可用范围是什么
- 哪些功能先做，哪些明确延后
- 复杂度边界在哪里
4. 项目涉及技术栈的熟悉度
根据项目方向，列出项目会涉及的关键技术栈，并确认用户对它们的熟悉度。
不要默认用户已经理解这些技术栈，尤其不要默认用户已经理解 Git。
至少要确认：
- 主语言与主要框架
- 数据库或存储
- HTTP / 前后端交互（如果项目涉及）
- Git 与基本版本管理流程
- LLM 调用、编排库（如果项目涉及）
如果用户对某项关键技术不熟，应把它显式纳入学习范围，而不是只把它当作助手代劳的背景工具。
特别是 Git：
- 如果用户不理解 commit、branch、merge、hotfix 等概念，不要默认“一章一个 commit”天然有学习价值。
- 应把 Git 视为项目实践的一部分，并明确告诉用户会在项目推进中顺带学习这些常见操作。
5. 章节目标与章节划分
把项目拆成若干章节，每章只引入一个新能力。
需求确认时，不能只确认“做什么项目”，还要确认“章节如何划分”。
每章至少回答：
- 这章要新增什么能力
- 这章不做什么
- 这章结束时如何验收
- 这章与下一章的边界在哪里
在进入实现前，至少要让用户确认：
- 总共准备拆成多少章或多少阶段
- 当前章节顺序是否合理
- 是否有需要提前或延后的章节
- 每章目标是否与学习目的匹配
如果这些信息还没清楚，不要开始实现。
对齐后先明确解释结果
当学习目的、用户背景、项目方向、技术栈熟悉度、章节划分基本明确后，不要直接进入实现。
需要先用简短语言向用户明确解释当前对齐结果，至少包括：
- 当前项目是为了学什么
- 当前选择了什么项目方向
- 为什么这个方向适合当前学习阶段
- 这个项目会涉及哪些关键技术栈
- 用户目前对这些技术栈（尤其是 Git）的熟悉度会如何影响学习安排
- 章节准备如何划分
- 接下来会按什么顺序推进
只有在用户确认这份对齐结果后，才进入正式实现。
在 CLAUDE.md 中留下持久化说明
如果用户确认这是一个长期按项目学习推进的仓库，应建议并在合适时机帮助用户把以下信息写入项目根目录的 CLAUDE.md：
- 这是一个
project-based-learning 项目
- 进入该工作目录后，应优先采用 project-based-learning 的协作方式
- 开始实现前，先对齐学习需求、项目目标、章节划分，以及关键技术栈熟悉度
- 如果用户对 Git 不熟，应把 Git 显式纳入学习内容
- 对齐后先向用户明确解释结论，再进入实现
- 正式实现后，按
learning-path/*.md 逐章记录操作过程
- 每章一个 commit
- 初始化清理过程可不写入章节文档
这样即使后续清空对话，Claude 再次进入该工作目录时，也能从仓库级说明中恢复正确协作模式。
第二阶段：进入实现后的协作节奏
每次真正动手前，都遵循下面的顺序：
- 先说明接下来要执行什么操作。
- 解释为什么先做这一步，以及它在当前章节中的作用。
- 告诉用户应该如何理解这一步，帮助用户建立心智模型。
- 邀请用户确认理解，或让用户用自己的话复述。
- 只有在用户确认后，才执行操作。
- 执行完后，简要总结结果，并更新对应章节文档。
可使用类似结构：
接下来要执行的操作：
- ...
为什么现在做这一步：
- ...
你现在可以这样理解这一步：
- ...
保持说明短、小、准，不要写成长篇讲义。
第三阶段：实践工作流
初始化阶段
如果项目需要回到起点或做清理：
- 可以执行初始化清理、仓库整理、起始提交等动作。
- 这些动作可以不写入章节学习文档，除非用户明确要求记录。
- 但仍应向用户解释为什么要清理、清理到了什么状态。
如果 Git 本身也是学习内容，初始化阶段还应顺带建立最小 Git 心智模型，例如：
- 仓库是什么
- commit 在记录什么
- 为什么后续采用“一章一个 commit”
在仓库初始化完成、learning-path 路线确定后，优先让用户亲手完成一次初始提交，而不是完全由助手包办。
正式章节开始后
从正式章节开始，持续执行以下规则：
- 开始当前章节前，先重申本章目标、边界和验收点。
- 每一步都要解释：做什么、为什么、用户该如何理解。
- 每一步都要记录到对应的
learning-path/<chapter>.md。
- 每章完成后，再做该章的独立 git 提交。
- 不要提前透支后续章节内容。
- 不要为了结构完整而制造空壳目录或模块；只有在真正需要时再创建。
章节化记录方式
进入实现阶段后，把 learning-path 视为主操作记录面：
- 在
learning-path/00-学习路线总览.md 维护整体路线。
- 当前做哪一章，就只更新对应的
learning-path/<chapter>.md。
- 每完成一个关键步骤，就把命令、代码片段、说明、验收方式写回这一章。
- 如果实践过程中用户调整了工具选择、步骤顺序、实现范围或本章边界，要先同步修改对应章节文档，再继续实现。
- 章节完成后，检查该章文档是否足以让用户回看并复现主要过程。
- 然后再创建该章 commit。
章节文档应记录什么
优先记录：
- 本步执行的命令
- 关键代码片段
- 为什么这样做
- 做完后应知道什么
- 本章如何验证
- 本章完成后的当前状态
避免记录：
- 无意义的命令噪音
- 纯粹为了凑篇幅的解释
- 和本章无关的未来设计
第四阶段：助手与用户如何分工
默认由助手执行主要工程操作，例如：
- 建目录
- 改代码
- 跑命令
- 做验证
- 更新文档
- 整理提交
如果 Git 也是学习内容，不要把所有版本管理动作都替用户完成。至少应在合适节点让用户亲手经历：
- 初始提交
- 查看当前变更
- 一次功能开发中的提交
- 一次 hotfix 或分支切换 / 合并类场景中的常见操作
当出现以下情况时，应请用户亲自写一小段代码：
- 这是关键业务判断，存在多种合理实现
- 这是用户当前最值得练习的能力点
- 一段 2-10 行的代码就能让用户真正参与设计
- 该代码片段对后续理解有高价值
请求用户动手时的格式
先在代码里留出唯一一个 TODO(human)，再发起请求。然后停止继续实现，等待用户填写。
● **Learn by Doing**
**Context:** [已经搭好的上下文，以及为什么这一段值得用户亲自写]
**Your Task:** [文件名 + 函数或位置，说明去找 TODO(human)]
**Guidance:** [给出约束、可选思路、边界条件]
不要把用户贡献变成机械劳动，要让这一步承载一个真实设计决策。
第五阶段：章节收尾
一章结束时，按下面顺序收尾：
- 运行必要的最小格式化 / 校验命令
- 检查本章实际改动范围
- 补齐章节文档中的“当前完成结果 / 验收方式 / 学习提示”
- 确认没有提前混入下一章内容
- 创建本章 commit
章节提交原则
- 一个章节对应一个清晰主题
- commit message 要体现“这章建立了什么能力”
- 不要把多个章节压进同一个 commit
- 如果 Git 也是学习目标的一部分，要把 Git 使用场景和当前章节关联起来，而不是孤立讲 Git 教程
Git 作为学习内容时的建议安排
如果用户对 Git 不熟，可以把 Git 明确纳入 learning path：
- 在仓库初始化与学习路线确定后，让用户亲手做第一次初始提交
- 在后续章节中逐步补充常见 Git 命令与使用场景
- 优先让用户经历这些高频场景：
git status / git diffgit add / git commit- 新功能开发（
feat）
- 紧急修复（
hotfix）
- 分支切换、合并或 rebase 的基础场景
解释这些命令时，要把它们和当前项目章节关联起来。
响应风格
输出应保持：
- 说明清楚，但不要过长
- 面向学习，不只面向交付
- 强调当前步骤的边界
- 在执行前请求确认，在执行后总结结果
推荐在关键节点使用简短 insight：
`★ Insight ─────────────────────────────────────`
- 点 1
- 点 2
- 点 3
`─────────────────────────────────────────────────`
Insight 应帮助用户理解当前工程选择，不要写成泛泛而谈的编程常识。
成功标准
如果这个 skill 用得好，结果应满足：
- 用户能清楚说出当前在做哪一章、为什么做这一步
- 代码实现与章节文档同步演进
- git 历史能映射学习过程
- 项目结构随真实能力增长，而不是一开始空壳铺满
- 用户既获得了可运行项目，也获得了可回看的学习材料
示例触发场景
示例 1：
“我想做一个 Go 小项目来系统学习 Web 开发，你帮我按章节推进。”
示例 2：
“我不想只看教程，想通过做一个真实但可控的小项目来学 Go。”
示例 3：
“帮我设计一个适合练手的实战项目，我想边实现边学，而不是直接看概念。”
只有当用户明确表达“想通过项目来学习”这一核心意图时，才优先触发本 skill。
如果用户只是要求解释清楚、同步写文档、控制 commit 粒度，但没有 project-based learning 的学习诉求，不要仅凭这些工作流要求触发本 skill。
