project-teacher

Project Teacher

生成对当前项目或任务的详细说明，重点讲解“为什么”和“如何做”，帮助用户学习。

用法

触发后，生成一个包含学习资源的 Markdown 文件。

1. 检查现有文档（同步）

生成新文件前，在输出目录（默认为 learning/）中搜索与当前项目相关的现有文档。

• 如果找到匹配项：询问用户：“我找到一篇现有的学习文档‘[Filename]’。你想要更新它，还是创建一个新的快照？”
• 如果用户选择更新：
  1. 重命名：将后缀日期更新为今天的日期（例如，API_Layout - 2024-03-25.md），以反映文档的时效性。
  2. 元数据：更新 frontmatter 中的 last 和 commit 字段。
  3. 内容：重写已过时的部分，但如果历史内容仍然适用，则予以保留。
  4. 记录：在底部的 ## Version history 部分添加一行（如果该部分不存在，则创建它）。
• 如果用户选择新建／未找到匹配项：创建一个新文件。

2. 输出位置

1. 检查用户偏好：如果用户指定了位置（例如“保存到我的知识库”），则使用该位置。
   • Obsidian／外部知识库：如果保存到外部 Obsidian 知识库，先检查其根目录或 .cursor/ / .claude/ 文件夹中是否有适用的上下文文件。这些文件通常包含如何在该系统中保存和格式化笔记的具体说明。如果存在此类说明，遵循这些说明。
2. 默认位置：如果未指定位置，则在项目根目录中使用名为 learning/ 的目录。
   • 如果 learning/ 目录不存在，则创建它。
   • 重要：检查 .gitignore 中是否包含 learning/。如果没有，则将其添加到 .gitignore，以确保这些个人文档不会提交到共享仓库。
3. 文件命名：将文件命名为 [Descriptive title] - [YYYY-MM-DD].md。
   • 结构：[Topic or Component] - [Date].md。开头部分应在语义上清楚地描述所讲解的内容。
   • 示例：
     • Authentication system walkthrough - 2024-03-25.md
     • Recipe parser logic - 2024-03-25.md
     • Project Teacher overview - 2024-03-25.md

3. 文件结构与元数据标题

使用 YAML frontmatter 记录机器可读的状态，并使用 callout 提供面向读者的背景信息。

---
last: [YYYY-MM-DD]
commit: [Current Git Commit Hash or "N/A"]
tags: [project-teacher, learning, ...]
---

# [Descriptive title in sentence case]

> [!NOTE]
> **Context**: [Brief description, e.g., "Updated after migration to v2"]
> _This document reflects the system state at the time of the last update._

## Code index
*   [MainController.ts](path/to/MainController.ts) - Handles the core logic for...
*   [UserAuth.ts](path/to/UserAuth.ts) - Manages session state.
*   [api/endpoints/](path/to/api/endpoints/) - API route definitions.

## 1. Project overview
[Explain the whole project in plain language as an expert tutor. What did we just build?]

## 2. Architecture and logic
[Use ASCII diagrams or Mermaid charts here to visualize how data flows or how components interact.]

## 3. Key technical decisions
[Explain "why" technical decisions were made.]

### Trade-offs and alternatives
[Explicitly mention what alternatives were considered and why they were rejected. e.g., "Considered using Redux, but opted for React Context because..."]

---
## Version history
*   **[YYYY-MM-DD]**: [Brief note on what changed, e.g. "Initial creation"]
*   **[YYYY-MM-DD]**: [e.g. "Updated diagram to reflect new caching layer"]

## Reflection questions
*   [Question 1 asking about a specific architectural choice]
*   [Question 2 asking about a potential edge case]
*   [Question 3 challenging the user to explain a complex part of the code]

4. 写作风格与视觉呈现

• 标题启发式规则：
  • 句首字母大写：标题始终使用句首字母大写格式（例如，“Architecture and logic”，而不是“Architecture And Logic”）。
  • 描述性：标题应准确描述实际内容。不要使用笼统的“Challenges”，而应使用“Handling concurrent requests”。
• 视觉化呈现：使用 ASCII 图示（通过代码块）或 Mermaid 图表来解释复杂逻辑、数据流或状态变化。用视觉方式呈现_工作原理_往往比文字更有价值。
• 代码索引：始终在顶部包含“Code index”或“Quick links”部分，方便用户在 IDE 中直接跳转到相关文件。
• 权衡取舍：始终包含一个关于权衡取舍的部分。这对深入学习至关重要。
• 反思：以能挑战用户理解的问题结尾，但不要提供答案。
• 灵活处理：如果僵化的模板不适用，不要强行套用。调整标题，以最有效的方式讲述学习内容。
• 专家导师风格：像向一位聪明的同事讲解一样，重点说明_推理过程_，而不只是逐行解释代码。