Back to Details

project-teacher

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Teacher

Project Teacher

Generate a detailed explanation of the current project or task, focusing on the "why" and "how" to help the user learn.
生成当前项目或任务的详细说明，重点讲解“为什么这么做”和“如何实现”，帮助用户学习。

Usage

使用方法

When triggered, generate a markdown file containing the learning resource.
触发技能后，生成包含学习资源的Markdown文件。

1. Check for Existing Documents (Synchronization)

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

Before generating a new file, search the output directory (default: 
learning/
) for existing documents related to the current project.
  • If a match is found: Ask the user: "I found an existing learning doc '[Filename]'. Do you want to update it or create a new snapshot?"
  • If User chooses Update:
    1. Rename: Updates the suffix date to today's date (e.g., 
      API_Layout - 2024-03-25.md
      ) to reflect freshness.
    2. Metadata: Update the 
      last
      and 
      commit
      fields in the frontmatter.
    3. Content: Rewrite sections that are outdated, but preserve valuable historical context if it still applies.
    4. Log: Add a line to a 
      ## Version history
      section at the bottom (create one if missing).
  • If User chooses New / No match found: Create a new file.
在生成新文件前，搜索输出目录（默认：
learning/
）中与当前项目相关的现有文档。
  • 找到匹配文档时：询问用户：“我找到了一份现有学习文档‘[文件名]’。您想要更新它还是创建新的快照？”
  • 用户选择更新时：
    1. 重命名：将后缀日期更新为今日日期（例如：
      API_Layout - 2024-03-25.md
      ），体现文档的时效性。
    2. 元数据：更新前置元数据中的
      last
      和
      commit
      字段。
    3. 内容：重写过时的章节，但如果有仍适用的有价值历史上下文，需予以保留。
    4. 日志：在文档底部的
      ## Version history
      章节中添加一条记录（若该章节不存在则创建）。
  • 用户选择新建/未找到匹配文档时：创建新文件。

2. Output Location

2. 输出位置

  1. Check for user preference: If the user specified a location (e.g., "save to my vault"), use that.
    • Obsidian / External Vaults: If saving to an external Obsidian vault, first check its root or 
      .cursor/
      / 
      .claude/
      folders for applicable context files. These files often contain specific instructions for how to save and format notes in that system. Delegate to those instructions if they exist.
  2. Default Location: If no location is specified, use a directory named 
    learning/
    in the project root.
    • Create the 
      learning/
      directory if it doesn't exist.
    • CRITICAL: Check if 
      learning/
      is in 
      .gitignore
      . If not, add it to 
      .gitignore
      to ensure these personal documents are not committed to shared repositories.
  3. File Naming: Name the file 
    [Descriptive title] - [YYYY-MM-DD].md
    .
    • Structure: 
      [Topic or Component] - [Date].md
      . The leading part should be semantic and descriptive of what is being explained.
    • Examples: 
      • Authentication system walkthrough - 2024-03-25.md
      • Recipe parser logic - 2024-03-25.md
      • Project Teacher overview - 2024-03-25.md
  1. 检查用户偏好：如果用户指定了保存位置（例如：“保存到我的知识库”），则使用该位置。
    • Obsidian / 外部知识库：如果要保存到外部Obsidian知识库，首先检查其根目录或
      .cursor/
      / 
      .claude/
      文件夹中是否有适用的上下文文件。这些文件通常包含该系统中保存和格式化笔记的具体说明。如果存在这些说明，优先遵循。
  2. 默认位置：如果未指定位置，使用项目根目录下名为
    learning/
    的目录。
    • 如果
      learning/
      目录不存在则创建。
    • 重要提示：检查
      learning/
      是否在
      .gitignore
      中。如果不在，将其添加到
      .gitignore
      ，确保这些个人文档不会被提交到共享代码仓库。
  3. 文件命名：文件命名格式为
    [描述性标题] - [YYYY-MM-DD].md
    。
    • 结构：
      [主题或组件] - [日期].md
      。开头部分应语义化，清晰描述文档所讲解的内容。
    • 示例： 
      • Authentication system walkthrough - 2024-03-25.md
      • Recipe parser logic - 2024-03-25.md
      • Project Teacher overview - 2024-03-25.md

3. File Structure & Metadata Header

3. 文件结构与元数据头部

Use YAML frontmatter for machine-readable status, and a callout for human context.
markdown
---
last: [YYYY-MM-DD]
commit: [Current Git Commit Hash or "N/A"]
tags: [project-teacher, learning, ...]
---
使用YAML前置元数据存储机器可读状态，使用提示框提供人工可读的上下文信息。
markdown
---
last: [YYYY-MM-DD]
commit: [当前Git提交哈希值或"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.
[!NOTE] 上下文：[简要说明，例如：“迁移到v2版本后更新”] 本文档反映了最后更新时的系统状态。

Code index

代码索引

  • MainController.ts - Handles the core logic for...
  • UserAuth.ts - Manages session state.
  • api/endpoints/ - API route definitions.
  • MainController.ts - 处理核心逻辑，用于...
  • UserAuth.ts - 管理会话状态。
  • api/endpoints/ - API路由定义。

1. Project overview

1. 项目概述

[Explain the whole project in plain language as an expert tutor. What did we just build?]
[以专业导师的身份，用通俗易懂的语言讲解整个项目。我们刚构建了什么？]

2. Architecture and logic

2. 架构与逻辑

[Use ASCII diagrams or Mermaid charts here to visualize how data flows or how components interact.]
[此处可使用ASCII图或Mermaid图表，可视化数据流向或组件交互方式。]

3. Key technical decisions

3. 关键技术决策

[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..."]
[明确说明曾考虑过哪些替代方案，以及为何未采用。例如：“曾考虑使用Redux，但最终选择React Context，因为...”]

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"]
  • [YYYY-MM-DD]：[变更简要说明，例如“初始创建”]
  • [YYYY-MM-DD]：[例如“更新图表以反映新的缓存层”]

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]
undefined
  • [问题1：询问特定架构选择的相关内容]
  • [问题2：询问潜在的边缘情况]
  • [问题3：要求用户解释代码中复杂的部分]
undefined

4. Writing Style & Visuals

4. 写作风格与可视化

  • Heuristics for Headings:
    • Sentence Case: Always use sentence case for headings (e.g., "Architecture and logic" NOT "Architecture And Logic").
    • Descriptive: Make headings descriptive of the actual content. Instead of generic "Challenges", use "Handling concurrent requests".
  • Be Visual: Use ASCII diagrams (using code blocks) or Mermaid charts to explain complex logic, data flows, or state changes. A visual representation of how it works is often more valuable than text.
  • Code Index: Always include a "Code index" or "Quick links" section at the top. This allows the user to jump directly to the relevant files in their IDE.
  • Trade-offs: ALWAYS include a section on trade-offs. This is critical for deep learning.
  • Reflection: End with questions that challenge the user's understanding, but do not provide the answers.
  • Be Flexible: Do not force the explanation into a rigid template if it doesn't fit. Adapt the headers to tell the most effective learning story.
  • Expert Tutor Persona: Write as if you are explaining this to a smart colleague who wants to understand the reasoning, not just the lines of code.
  • 标题规则：
    • 句子式大小写：标题始终使用句子式大小写（例如：“Architecture and logic”而非“Architecture And Logic”）。
    • 描述性：标题需准确描述实际内容。不要使用通用的“挑战”，而是用“处理并发请求”这类具体标题。
  • 注重可视化：使用ASCII图（放在代码块中）或Mermaid图表解释复杂逻辑、数据流或状态变化。可视化展示“工作原理”通常比文字更有价值。
  • 代码索引：始终在顶部包含“代码索引”或“快速链接”章节。这样用户可以直接跳转到IDE中的相关文件。
  • 权衡分析：必须包含权衡分析章节。这对深度学习至关重要。
  • 反思环节：以挑战用户理解的问题结尾，但不要提供答案。
  • 灵活适配：如果固定模板不适用，不要强行套用。调整标题以呈现最有效的学习内容。
  • 专业导师人设：以向聪明同事讲解的口吻写作，重点解释“推理过程”，而非仅仅罗列代码行。